@fabric-harness/sdk 1.14.0 → 2.0.0

package/dist/submission-runner.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Durable submission runner (v2 migration, phase A5).
+ *
+ * The execution engine over an {@link AgentSubmissionStore}: a claim loop
+ * that takes runnable session heads with lease-fenced CAS claims, an
+ * executor seam that applies the input to the instance session, and a
+ * reconciler that classifies interrupted work after a crash and produces
+ * exactly-once observable outcomes — completed work settles, repairable
+ * work resumes, unstarted work requeues, exhausted work fails with a
+ * terminal advisory. Ported from flue's node agent coordinator +
+ * `reconcileInterruptedSubmission`, adapted to the harness session model
+ * (SessionEntry DAG; `session.prompt({ submission })` is idempotent by
+ * submission id, so re-execution after a crash never double-applies input).
+ */
+import type { AgentDispatchAdmission, AgentSubmission, AgentSubmissionStore, SubmissionAttemptRef, SubmissionSettlementObligation } from './submission-store.js';
+import type { AgentSubmissionInput, SubmissionSettledRecord } from './submission-store.js';
+import type { AttachmentStore } from './attachment-store.js';
+import type { DispatchInput, DispatchQueue } from './dispatch.js';
+import type { SubmissionInspection } from './submission-state.js';
+import type { SubmissionTelemetrySink } from './submission-telemetry.js';
+export declare class SubmissionAbortedError extends Error {
+    readonly code = "SUBMISSION_ABORTED";
+    constructor();
+}
+export declare class SubmissionTimeoutError extends Error {
+    readonly code = "SUBMISSION_TIMEOUT";
+    constructor();
+}
+export declare class SubmissionRetryExhaustedError extends Error {
+    readonly code = "SUBMISSION_RETRY_EXHAUSTED";
+    readonly interruptedTools: InterruptedToolCallRef[] | undefined;
+    constructor(options: {
+        attemptCount: number;
+        maxAttempts: number;
+        interruptedTools?: InterruptedToolCallRef[];
+    });
+}
+export declare class SubmissionInterruptedError extends Error {
+    readonly code = "SUBMISSION_INTERRUPTED";
+    readonly phase: 'retry_exhausted_before_input' | 'after_input_application';
+    constructor(phase: SubmissionInterruptedError['phase'], detail?: string);
+}
+export interface SubmissionInterruption {
+    readonly submissionId: string;
+    readonly kind: 'dispatch' | 'direct';
+    readonly reason: 'interrupted_before_input_marker' | 'interrupted_after_input_application' | 'exhausted_retry_budget' | 'exceeded_timeout' | 'aborted';
+    readonly message: string;
+}
+/** A tool call settled with an explicit interrupted-outcome marker at terminalization. */
+export interface InterruptedToolCallRef {
+    readonly name: string;
+    readonly id?: string;
+}
+export interface SubmissionExecuteOptions {
+    readonly attempt: SubmissionAttemptRef;
+    /** Aborted for graceful shutdown or a durable abort request. */
+    readonly signal: AbortSignal;
+    /**
+     * Must be invoked at the input-applied boundary (canonical input durable,
+     * no provider work started). Throws when the attempt lost ownership — the
+     * executor must let that abort the turn.
+     */
+    readonly onInputApplied: () => Promise<void>;
+}
+/**
+ * How the runner touches sessions. `execute` applies the submission's input
+ * to the addressed instance session and resolves with the turn result;
+ * everything else is store-level and must not require a live agent.
+ *
+ * Contract requirements:
+ * - `execute` must be idempotent by submission id (a resumed attempt whose
+ *   input entry already exists must not append it again).
+ * - `recordTerminal` settles the conversation to a deterministic rest state
+ *   (unresolved trailing tool calls get explicit interrupted-outcome
+ *   markers — NEVER re-executed) and appends a terminal advisory.
+ * - `appendSettlement` appends the canonical `submission_settled` entry,
+ *   idempotent by its deterministic record id.
+ */
+export interface SubmissionExecutor {
+    execute(submission: AgentSubmission, options: SubmissionExecuteOptions): Promise<unknown>;
+    inspect(submission: AgentSubmission): Promise<SubmissionInspection>;
+    recordTerminal(submission: AgentSubmission, interruption: SubmissionInterruption): Promise<InterruptedToolCallRef[]>;
+    appendSettlement(submission: AgentSubmission, obligation: SubmissionSettlementObligation): Promise<void>;
+    /** The canonical settlement record for the submission, when one exists. */
+    getSettlement(submission: AgentSubmission): Promise<SubmissionSettledRecord | null>;
+}
+export interface SubmissionSettlement {
+    readonly outcome: 'completed' | 'failed' | 'aborted';
+    readonly result?: unknown;
+    readonly error?: string;
+}
+export interface SubmissionRunnerOptions {
+    submissions: AgentSubmissionStore;
+    executor: SubmissionExecutor;
+    /** Validate an admission target before persisting it (e.g. agent exists). */
+    validateInput?: (input: AgentSubmissionInput) => Promise<void> | void;
+    /**
+     * Durable content-addressed attachment storage. When configured, inline
+     * base64 attachments are materialized into refs BEFORE admission so the
+     * persisted submission payload never carries the bytes. Materialization is
+     * deterministic (ids from the submission/dispatch id + index, digests from
+     * content), preserving admission idempotency for exact redeliveries.
+     */
+    attachments?: {
+        store: AttachmentStore;
+    };
+    /**
+     * Lifecycle telemetry sink (v2 C4): one event per submission transition
+     * (accepted / started / settled), keyed by the stable submission id.
+     * Failures are reported through `onError` and never affect execution.
+     */
+    telemetry?: SubmissionTelemetrySink;
+    onSettled?: (submissionId: string, settlement: SubmissionSettlement) => void;
+    onError?: (context: string, error: unknown) => void;
+    /** Lease renewal cadence for active submissions. Default 10s. */
+    heartbeatIntervalMs?: number;
+    /** Expired-lease discovery cadence. Default 15s. */
+    leaseScanIntervalMs?: number;
+}
+export interface SubmissionRunner {
+    /** Durable dispatch admission; processing is asynchronous. */
+    admitDispatch(input: DispatchInput): Promise<AgentDispatchAdmission>;
+    /** Durable direct-prompt admission; processing is asynchronous. */
+    admitDirect(input: AgentSubmissionInput): Promise<AgentSubmission>;
+    /**
+     * Record a durable abort request for every unsettled submission of the
+     * session and abort any attempt running in this process. Returns the
+     * affected submission ids (empty when the session was idle).
+     */
+    requestAbort(storeSessionId: string): Promise<string[]>;
+    /** Reconcile interrupted work from a previous process; call once at startup. */
+    reconcile(): Promise<void>;
+    /** Resolve when the submission settles, with its outcome. */
+    waitForSettlement(submissionId: string, options?: {
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<SubmissionSettlement>;
+    /** Resolve when no active or runnable work remains. */
+    waitForIdle(): Promise<void>;
+    /** Stop claiming, abort active work at the turn boundary, wait (with timeout). */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /** Wake the claim loop (new work may be runnable). */
+    wake(): void;
+    /** A DispatchQueue façade over durable admission. */
+    createDispatchQueue(): DispatchQueue;
+}
+export declare function createSubmissionRunner(options: SubmissionRunnerOptions): SubmissionRunner;
+/** Store-session FIFO key of a submission (re-exported convenience). */
+export declare function submissionSessionKey(input: Pick<AgentSubmissionInput, 'agent' | 'id' | 'session'>): string;
+//# sourceMappingURL=submission-runner.d.ts.map

package/dist/submission-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submission-runner.d.ts","sourceRoot":"","sources":["../src/submission-runner.ts"],"names":[],"mappings":"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"}