Recoverable execution graphs

export interface ExecutionGraphResult {
    task: DurableTaskRecord;
    graph: DurableGraphState;
    output?: DurableJSON;
}

export interface ExecutionGraphRuntimeOptions {
    program: ExecutionGraphProgram;
    catalog: readonly GraphBinding[];
    harness: Omit<HarnessRuntimeConfig, "driver" | "tools">;
    limits?: ExecutionGraphLimits;
    store?: DurableTaskStore;
    requireDurable?: boolean;
    leaseMs?: number;
    pollMs?: number;
    onAdmission?: (event: RootExecutionEvent) => void;
}

export interface ExecutionGraphTaskOptions {
    id: string;
    identity: DurableIdentity;
    input: DurableJSON;
    deadline?: number;
    policyRevision?: number;
    grantRefs?: string[];
    maxAttempts?: number;
}

/** Recovery protocol over the existing local harness and Workflow scheduler.
 * Host binding versions attest schemas, callbacks, providers and effect policy. */
export declare class ExecutionGraphRuntime {
    readonly capabilities: {
        durable: boolean;
        recovery: "recorded-agent-decisions";
        globalAdmission: true;
        streamedPlans: true;
    };
    readonly store: DurableTaskStore;
    constructor(options: ExecutionGraphRuntimeOptions);
    create(input: ExecutionGraphTaskOptions): Promise<DurableTaskRecord>;
    inspect(key: DurableTaskKey): Promise<ExecutionGraphResult>;
    cancel(key: DurableTaskKey, reason?: string): Promise<DurableTaskRecord>;
    run(key: DurableTaskKey, workerId: string): Promise<ExecutionGraphResult>;
}

export declare class ExecutionPlanValidationError extends Error {
    readonly code = "execution_plan_invalid";
    constructor(message: string, options?: ErrorOptions);
}

/** Serializable catalog identity excludes executable code and credentials; hosts version opaque behavior. */
export declare function graphCatalogDescriptor(catalog: readonly GraphBinding[], limits: PlanValidationLimits): DurableJSON[];

export declare function graphCatalogDigest(catalog: readonly GraphBinding[], limits: PlanValidationLimits): string;

/** Validate and copy a complete proposal without invoking models, effects, policy or guards. */
export declare function validateExecutionPlan(value: unknown, catalog: readonly GraphBinding[], limits: PlanValidationLimits, initialDepth?: number): ValidatedExecutionPlan;

export interface ExecutionGraphLimits extends RootExecutionLimits {
    plan?: Partial<Omit<PlanValidationLimits, "durable">>;
}

export interface ExecutionGraphPlannerOptions {
    provider: ModelProvider;
    hostInstructions: string;
    maxCorrections: number;
    maxOutputTokens: number;
    stream: PlanStreamLimits;
}

/** A complete static proposal or an authorized planner; nested programs inherit the root catalog. */
export interface ExecutionGraphProgram {
    id: string;
    version: string;
    plan?: ExecutionPlan;
    planner?: ExecutionGraphPlannerOptions & {
        mode?: "complete" | "stream";
    };
}

export interface ExecutionPlan {
    schemaVersion: 1;
    revision: number;
    nodes: readonly ExecutionPlanNode[];
    maxConcurrency?: number;
    merge?: "error" | "declaration_order";
}

export interface ExecutionPlanNode {
    id: string;
    binding: string;
    version: string;
    args: Record<string, DurableJSON>;
    dependsOn?: readonly string[];
    inputsFrom?: readonly string[];
}

export interface GraphAgentBinding extends GraphBindingBase {
    kind: "agent";
    agent: Agent;
    /** Explicit approved tool binding IDs, including any static Agent-local tools. */
    tools: readonly string[];
}

export type GraphBinding = GraphToolBinding | GraphAgentBinding | GraphNestedBinding | GraphRepeatBinding;

export interface GraphNestedBinding extends GraphBindingBase {
    kind: "graph";
    program: ExecutionGraphProgram;
}

export interface GraphRepeatBinding extends GraphBindingBase {
    kind: "repeat";
    program: ExecutionGraphProgram;
    maxIterations: number;
    /** Pinned by binding version; evaluated decisions are persisted before child work. */
    while(output: DurableJSON, completedIterations: number): boolean;
}

export interface GraphToolBinding extends GraphBindingBase {
    kind: "tool";
    tool: ToolDef;
    /** Pure is a trusted host declaration of no external mutation. */
    recovery?: "pure" | {
        connector: DurableActionConnector;
        destination: string;
        resolveResult(resultRef: string): Promise<DurableJSON>;
    };
}

/** Host-owned schema boundary; validators/code/credentials never come from proposals. */
export interface GraphValueSchema {
    parse(value: unknown): unknown;
}

export interface PlanCommitFrame {
    baseRevision: number;
    plan: ExecutionPlan;
}

export interface PlanReferenceRequirement {
    consumer: string;
    producer: string;
    outputPath: readonly string[];
    argumentPath: readonly string[];
}

export interface PlanStreamLimits {
    maxFrameBytes: number;
    maxTotalBytes: number;
    maxFrames: number;
    /** Per planning call, default 30 seconds; original root deadline still applies. */
    maxLatencyMs?: number;
}

export interface PlanValidationLimits {
    maxBytes: number;
    maxNodes: number;
    maxDepth: number;
    maxConcurrency: number;
    durable: boolean;
}

export interface ValidatedExecutionPlan {
    plan: ExecutionPlan;
    order: readonly string[];
    referenceRequirements: readonly PlanReferenceRequirement[];
    digest: string;
    catalogDigest: string;
    bindingKinds: Record<string, GraphBinding["kind"]>;
}

interface GraphBindingBase {
    id: string;
    version: string;
    input: GraphValueSchema;
    output: GraphValueSchema;
    /** Dot-separated supported reference paths; empty string denotes the whole value. */
    referenceInputs?: readonly string[];
    referenceOutputs?: readonly string[];
    /** Required for templates containing future values: pure literal/template validation. */
    validateTemplate?: (template: Record<string, DurableJSON>) => void;
}