intentdna 1.8.6 → 1.8.7

package/dist/runtime/run-controller.d.ts

@@ -0,0 +1,149 @@
+import type { AttemptId, AttemptIdentity, AttemptRecord, ClaimToken, EventId, HandoffBinding, ResultId, RetryPolicy, RunId, StepId, StepPacket, TaskClaim, WorkerSessionId } from "./run-contracts.js";
+import type { ExecutionProvider } from "./execution-provider.js";
+import { HandoffResolver, type QuoteHandoffRequest } from "./handoff-resolver.js";
+import { DurableRunStore, type RunRecord, type RunStoreSnapshot } from "./run-store.js";
+import { executeWorkerAttempt, type WorkerExecutorOptions } from "./worker-executor.js";
+type SourceWithoutResultId = {
+    readonly step_id: StepId;
+    readonly output_name: string;
+};
+interface ControllerHandoffBase {
+    readonly binding_id: string;
+    readonly input_name: string;
+    readonly required: boolean;
+    readonly description: string;
+}
+export interface ControllerReferenceHandoff extends ControllerHandoffBase {
+    readonly mode: "reference";
+    readonly source: SourceWithoutResultId;
+}
+export interface ControllerQuoteHandoff extends ControllerHandoffBase {
+    readonly mode: "quote";
+    readonly source: SourceWithoutResultId;
+    readonly selection: QuoteHandoffRequest["selection"];
+}
+export interface ControllerStructuredHandoff extends ControllerHandoffBase {
+    readonly mode: "structured";
+    readonly source: SourceWithoutResultId;
+    readonly schema_ref: string | null;
+}
+export interface ControllerNoHandoff extends ControllerHandoffBase {
+    readonly mode: "none";
+    readonly required: false;
+    readonly reason: string | null;
+}
+export type ControllerHandoffDeclaration = ControllerReferenceHandoff | ControllerQuoteHandoff | ControllerStructuredHandoff | ControllerNoHandoff;
+export interface MaterializeStepPacketInput extends AttemptIdentity {
+    readonly attempt_number: number;
+    readonly input_bindings: readonly HandoffBinding[];
+    readonly retry_policy: RetryPolicy;
+    readonly created_at: string;
+}
+/**
+ * M1-S06 owns adapting compiled workflow Steps into these declarations and the
+ * packet materializer. The Controller consumes them without compiling workflow
+ * syntax or adding undeclared inputs.
+ */
+export interface ControllerStepDefinition {
+    readonly step_id: StepId;
+    readonly dependencies: readonly StepId[];
+    readonly initially_skipped?: boolean;
+    readonly retry_policy: RetryPolicy;
+    readonly handoffs: readonly ControllerHandoffDeclaration[];
+    materialize_packet(input: MaterializeStepPacketInput): StepPacket;
+}
+export type ReconciledAttemptState = "live" | "dead" | "unknown";
+export type AttemptReconciler = (attempt: AttemptRecord, claim: TaskClaim) => Promise<ReconciledAttemptState>;
+export interface RunControllerOptions {
+    readonly run_store: DurableRunStore;
+    readonly handoff_resolver?: HandoffResolver;
+    readonly steps: readonly ControllerStepDefinition[];
+    readonly provider_for_step: (definition: ControllerStepDefinition) => ExecutionProvider;
+    readonly max_concurrency: number;
+    readonly lease_duration_ms: number;
+    readonly lease_heartbeat_ms?: number;
+    readonly scheduler_poll_ms?: number;
+    readonly owner_id?: string;
+    readonly reconcile_attempt?: AttemptReconciler;
+    readonly execute_attempt?: typeof executeWorkerAttempt;
+    readonly worker_options?: Omit<WorkerExecutorOptions, "cancellationSignal" | "cancellationReason" | "now">;
+    readonly now?: () => Date;
+    readonly create_attempt_id?: () => AttemptId;
+    readonly create_worker_session_id?: () => WorkerSessionId;
+    readonly create_claim_token?: () => ClaimToken;
+    readonly create_result_id?: () => ResultId;
+    readonly create_event_id?: () => EventId;
+}
+export interface CreateControllerRunInput {
+    readonly run: RunRecord;
+}
+export interface ClaimedStep {
+    readonly definition: ControllerStepDefinition;
+    readonly attempt: AttemptRecord;
+    readonly claim: TaskClaim;
+    readonly snapshot: RunStoreSnapshot;
+}
+export type RunControllerErrorCode = "invalid_configuration" | "invalid_definition" | "invalid_packet" | "claim_lost" | "run_cancelling" | "scheduler_stalled";
+export declare class RunControllerError extends Error {
+    readonly code: RunControllerErrorCode;
+    constructor(code: RunControllerErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class RunController {
+    private readonly store;
+    private readonly resolver;
+    private readonly definitions;
+    private readonly definitionByStep;
+    private readonly providerForStep;
+    private readonly maxConcurrency;
+    private readonly leaseDurationMs;
+    private readonly leaseHeartbeatMs;
+    private readonly schedulerPollMs;
+    private readonly ownerId;
+    private readonly reconcileAttempt;
+    private readonly executeAttempt;
+    private readonly workerOptions;
+    private readonly now;
+    private readonly createAttemptId;
+    private readonly createWorkerSessionId;
+    private readonly createClaimToken;
+    private readonly createResultId;
+    private readonly createEventId;
+    private readonly active;
+    constructor(options: RunControllerOptions);
+    private validateDefinitions;
+    private events;
+    createRun(input: CreateControllerRunInput): Promise<RunStoreSnapshot>;
+    inspect(runId: RunId): Promise<RunStoreSnapshot>;
+    private dependenciesFor;
+    /**
+     * A dependency is satisfied only by a succeeded task whose referenced result
+     * is present in the immutable committed-result collection.
+     */
+    refreshDependencyReadiness(runId: RunId): Promise<RunStoreSnapshot>;
+    private readyAt;
+    claimNextReady(runId: RunId): Promise<ClaimedStep | null>;
+    private assertCurrentClaim;
+    renewClaim(claim: TaskClaim): Promise<TaskClaim>;
+    private markRunning;
+    private handoffRequest;
+    private persistResolvedHandoffs;
+    private materializePacket;
+    private finalizeAttempt;
+    private syntheticExecution;
+    private reclaimDeadAttempt;
+    /**
+     * Resume never infers death from lease expiry alone. Reclaim is allowed only
+     * after the injected reconciler explicitly confirms the owned worker is dead.
+     */
+    resume(runId: RunId): Promise<RunStoreSnapshot>;
+    requestCancellation(runId: RunId, reason?: string | null): Promise<RunStoreSnapshot>;
+    private finalizeRunIfTerminal;
+    private launchClaimed;
+    /**
+     * Runs scheduling until durable terminal state. Every successful claim creates
+     * a fresh attempt and worker session; this Controller never gives a worker a
+     * second Step.
+     */
+    runUntilTerminal(runId: RunId): Promise<RunStoreSnapshot>;
+}
+export {};