intentdna 1.8.6 → 1.8.7

package/dist/runtime/providers/claude.js

@@ -0,0 +1,64 @@
+import { decodeDeclaredOutputs, MalformedProviderResultError, } from "../execution-provider.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createClaudeExecutionProvider(options = {}) {
+    return {
+        name: "claude",
+        createLaunch(packet) {
+            return {
+                command: options.executable ?? "claude",
+                args: [
+                    "-p",
+                    "--agent",
+                    options.agentName?.(packet) ?? packet.role,
+                    "--output-format",
+                    "json",
+                    "--session-id",
+                    packet.worker_session_id,
+                    "--no-session-persistence",
+                    ...(options.extraArgs ?? []),
+                ],
+                stdin: packet.standalone_prompt,
+                cwd: packet.workspace.working_directory,
+                ...(options.env ? { env: options.env } : {}),
+            };
+        },
+        parseResult(context) {
+            let value;
+            try {
+                value = JSON.parse(context.stdout);
+            }
+            catch {
+                throw new MalformedProviderResultError("Claude output is not valid JSON");
+            }
+            if (!isRecord(value)) {
+                throw new MalformedProviderResultError("Claude output must be a JSON object");
+            }
+            if (value.is_error === true) {
+                throw new MalformedProviderResultError(typeof value.result === "string"
+                    ? value.result
+                    : "Claude reported an error result");
+            }
+            if (value.result === undefined
+                && context.packet.output_contract.length === 0) {
+                return {
+                    provider_session_id: typeof value.session_id === "string"
+                        ? value.session_id
+                        : null,
+                    outputs: [],
+                };
+            }
+            if (typeof value.result !== "string") {
+                throw new MalformedProviderResultError("Claude output is missing its result text");
+            }
+            const providerSessionId = typeof value.session_id === "string"
+                ? value.session_id
+                : null;
+            return {
+                provider_session_id: providerSessionId,
+                outputs: decodeDeclaredOutputs(value.result, context.packet.output_contract),
+            };
+        },
+    };
+}

package/dist/runtime/providers/codex.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionProvider } from "../execution-provider.js";
+export interface CodexExecutionProviderOptions {
+    readonly executable?: string;
+    readonly sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    readonly extraArgs?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function createCodexExecutionProvider(options?: CodexExecutionProviderOptions): ExecutionProvider;

package/dist/runtime/providers/codex.js

@@ -0,0 +1,72 @@
+import { decodeDeclaredOutputs, MalformedProviderResultError, } from "../execution-provider.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createCodexExecutionProvider(options = {}) {
+    return {
+        name: "codex",
+        createLaunch(packet) {
+            return {
+                command: options.executable ?? "codex",
+                args: [
+                    "exec",
+                    "--ephemeral",
+                    "--json",
+                    "--skip-git-repo-check",
+                    "-C",
+                    packet.workspace.working_directory,
+                    "--sandbox",
+                    options.sandbox ?? "workspace-write",
+                    ...(options.extraArgs ?? []),
+                    packet.standalone_prompt,
+                ],
+                stdin: null,
+                cwd: packet.workspace.working_directory,
+                ...(options.env ? { env: options.env } : {}),
+            };
+        },
+        parseResult(context) {
+            let providerSessionId = null;
+            let finalText = null;
+            const lines = context.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+            if (lines.length === 0) {
+                throw new MalformedProviderResultError("Codex returned no JSON events");
+            }
+            for (const line of lines) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    throw new MalformedProviderResultError("Codex output contains a malformed JSON event");
+                }
+                if (!isRecord(event) || typeof event.type !== "string") {
+                    throw new MalformedProviderResultError("Codex output contains an invalid event");
+                }
+                if (event.type === "thread.started"
+                    && typeof event.thread_id === "string") {
+                    providerSessionId = event.thread_id;
+                }
+                if (event.type === "item.completed" && isRecord(event.item)) {
+                    if (event.item.type === "agent_message"
+                        && typeof event.item.text === "string") {
+                        finalText = event.item.text;
+                    }
+                }
+                if (event.type === "error") {
+                    const message = isRecord(event.error) && typeof event.error.message === "string"
+                        ? event.error.message
+                        : "Codex reported an error event";
+                    throw new MalformedProviderResultError(message);
+                }
+            }
+            if (finalText === null) {
+                throw new MalformedProviderResultError("Codex output has no completed agent message");
+            }
+            return {
+                provider_session_id: providerSessionId,
+                outputs: decodeDeclaredOutputs(finalText, context.packet.output_contract),
+            };
+        },
+    };
+}

package/dist/runtime/result-store.d.ts

@@ -0,0 +1,32 @@
+import type { AttemptId, CommittedStepResult, ResultId, RunId } from "./run-contracts.js";
+import { DurableRunStore, type RunStoreSnapshot } from "./run-store.js";
+export type ResultStoreErrorCode = "invalid_result" | "result_not_found";
+export declare class ResultStoreError extends Error {
+    readonly code: ResultStoreErrorCode;
+    constructor(code: ResultStoreErrorCode, message: string);
+}
+export interface CommitStepResultRequest {
+    readonly result: CommittedStepResult;
+    readonly expected_record_version: number;
+}
+export interface CommitStepResultResponse {
+    readonly result: CommittedStepResult;
+    readonly snapshot: RunStoreSnapshot;
+    /** False only when the exact immutable result was already committed. */
+    readonly committed: boolean;
+}
+/**
+ * Immutable result access over the durable run ledger.
+ *
+ * Mutation authority remains in DurableRunStore so result commits share the
+ * run's atomic/versioned transaction boundary.
+ */
+export declare class ImmutableResultStore {
+    private readonly runStore;
+    constructor(runStore: DurableRunStore);
+    commit(request: CommitStepResultRequest): Promise<CommitStepResultResponse>;
+    read(runId: RunId, resultId: ResultId): Promise<CommittedStepResult | null>;
+    require(runId: RunId, resultId: ResultId): Promise<CommittedStepResult>;
+    readByAttempt(runId: RunId, attemptId: AttemptId): Promise<CommittedStepResult | null>;
+    list(runId: RunId): Promise<readonly CommittedStepResult[]>;
+}

package/dist/runtime/result-store.js

@@ -0,0 +1,130 @@
+export class ResultStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ResultStoreError";
+        this.code = code;
+    }
+}
+function assertNonEmptyString(value, label) {
+    if (!value) {
+        throw new ResultStoreError("invalid_result", `${label} must be a non-empty string`);
+    }
+}
+function assertJsonValue(value, path) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new ResultStoreError("invalid_result", `${path} must contain only finite JSON numbers`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => assertJsonValue(entry, `${path}[${index}]`));
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined) {
+                throw new ResultStoreError("invalid_result", `${path}.${key} must not be undefined`);
+            }
+            assertJsonValue(entry, `${path}.${key}`);
+        }
+        return;
+    }
+    throw new ResultStoreError("invalid_result", `${path} must be a JSON value`);
+}
+function assertOutput(output, index) {
+    const label = `result.outputs[${index}]`;
+    assertNonEmptyString(output.name, `${label}.name`);
+    if (output.kind === "reference") {
+        assertNonEmptyString(output.reference.value, `${label}.reference.value`);
+        return;
+    }
+    if (output.kind === "text") {
+        return;
+    }
+    assertJsonValue(output.value, `${label}.value`);
+}
+function assertCommittedResult(result) {
+    assertNonEmptyString(result.result_id, "result.result_id");
+    assertNonEmptyString(result.run_id, "result.run_id");
+    assertNonEmptyString(result.step_id, "result.step_id");
+    assertNonEmptyString(result.attempt_id, "result.attempt_id");
+    assertNonEmptyString(result.worker_session_id, "result.worker_session_id");
+    assertNonEmptyString(result.provider, "result.provider");
+    assertNonEmptyString(result.started_at, "result.started_at");
+    assertNonEmptyString(result.completed_at, "result.completed_at");
+    assertNonEmptyString(result.committed_at, "result.committed_at");
+    if (result.commit_status !== "committed") {
+        throw new ResultStoreError("invalid_result", `result ${result.result_id} is not committed`);
+    }
+    const outputNames = new Set();
+    result.outputs.forEach((output, index) => {
+        assertOutput(output, index);
+        if (outputNames.has(output.name)) {
+            throw new ResultStoreError("invalid_result", `result ${result.result_id} has duplicate output ${output.name}`);
+        }
+        outputNames.add(output.name);
+    });
+}
+/**
+ * Immutable result access over the durable run ledger.
+ *
+ * Mutation authority remains in DurableRunStore so result commits share the
+ * run's atomic/versioned transaction boundary.
+ */
+export class ImmutableResultStore {
+    runStore;
+    constructor(runStore) {
+        this.runStore = runStore;
+    }
+    async commit(request) {
+        assertCommittedResult(request.result);
+        const update = await this.runStore.updateRun({
+            run_id: request.result.run_id,
+            expected_record_version: request.expected_record_version,
+            results: [request.result],
+        });
+        const result = update.snapshot.results.find((candidate) => candidate.result_id === request.result.result_id);
+        if (!result) {
+            throw new ResultStoreError("result_not_found", `committed result ${request.result.result_id} was not retained`);
+        }
+        return {
+            result,
+            snapshot: update.snapshot,
+            committed: update.applied,
+        };
+    }
+    async read(runId, resultId) {
+        const snapshot = await this.runStore.loadRun(runId);
+        const result = snapshot?.results.find((candidate) => candidate.result_id === resultId) ?? null;
+        if (result)
+            assertCommittedResult(result);
+        return result;
+    }
+    async require(runId, resultId) {
+        const result = await this.read(runId, resultId);
+        if (!result) {
+            throw new ResultStoreError("result_not_found", `committed result ${resultId} was not found in run ${runId}`);
+        }
+        return result;
+    }
+    async readByAttempt(runId, attemptId) {
+        const snapshot = await this.runStore.loadRun(runId);
+        const result = snapshot?.results.find((candidate) => candidate.attempt_id === attemptId) ?? null;
+        if (result)
+            assertCommittedResult(result);
+        return result;
+    }
+    async list(runId) {
+        const snapshot = await this.runStore.loadRun(runId);
+        const results = snapshot?.results ?? [];
+        results.forEach(assertCommittedResult);
+        return results;
+    }
+}

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

@@ -0,0 +1,290 @@
+/**
+ * Foundation Runtime contracts.
+ *
+ * These types describe durable run truth and the boundary to one disposable
+ * worker session. They intentionally contain no storage, scheduling, provider,
+ * CLI, or Hook behavior.
+ */
+declare const runtimeIdBrand: unique symbol;
+export type RuntimeId<Kind extends string> = string & {
+    readonly [runtimeIdBrand]: Kind;
+};
+export type RunId = RuntimeId<"run_id">;
+export type StepId = RuntimeId<"step_id">;
+export type AttemptId = RuntimeId<"attempt_id">;
+export type WorkerSessionId = RuntimeId<"worker_session_id">;
+export type ResultId = RuntimeId<"result_id">;
+export type EventId = RuntimeId<"event_id">;
+export type ClaimToken = RuntimeId<"claim_token">;
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface TaskKey {
+    readonly run_id: RunId;
+    readonly step_id: StepId;
+}
+/**
+ * A worker_session_id is allocated once for one attempt and is carried through
+ * its packet, provider events, provider result, and committed result.
+ */
+export interface AttemptIdentity extends TaskKey {
+    readonly attempt_id: AttemptId;
+    readonly worker_session_id: WorkerSessionId;
+}
+export declare const TASK_STATE_VALUES: readonly ["dependency_blocked", "ready", "claimed", "running", "succeeded", "failed", "skipped", "cancelled"];
+export type TaskState = typeof TASK_STATE_VALUES[number];
+export type TerminalTaskState = Extract<TaskState, "succeeded" | "failed" | "skipped" | "cancelled">;
+/**
+ * Failed attempts may return a non-terminal task to ready for a new attempt.
+ * Terminal task states are immutable and therefore have no outgoing edges.
+ */
+export declare const TASK_STATE_TRANSITIONS: {
+    readonly dependency_blocked: readonly ["ready", "skipped", "cancelled"];
+    readonly ready: readonly ["claimed", "skipped", "cancelled"];
+    readonly claimed: readonly ["ready", "running", "cancelled"];
+    readonly running: readonly ["ready", "succeeded", "failed", "cancelled"];
+    readonly succeeded: readonly [];
+    readonly failed: readonly [];
+    readonly skipped: readonly [];
+    readonly cancelled: readonly [];
+};
+export interface TaskRecord extends TaskKey {
+    readonly state: TaskState;
+    readonly attempt_count: number;
+    readonly current_attempt_id: AttemptId | null;
+    readonly committed_result_id: ResultId | null;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+export interface TaskLease {
+    readonly acquired_at: string;
+    readonly expires_at: string;
+    readonly heartbeat_at: string;
+}
+export interface TaskClaim extends AttemptIdentity {
+    readonly claim_token: ClaimToken;
+    readonly owner_id: string;
+    readonly claimed_record_version: number;
+    readonly lease: TaskLease;
+}
+export declare const RETRY_BACKOFF_VALUES: readonly ["none", "linear", "exponential"];
+export type RetryBackoff = typeof RETRY_BACKOFF_VALUES[number];
+export interface RetryPolicy {
+    /** Includes the initial attempt. */
+    readonly max_attempts: number;
+    readonly backoff: RetryBackoff;
+    readonly initial_delay_ms: number;
+    readonly max_delay_ms: number | null;
+    readonly retryable_outcomes: readonly TerminalOutcomeKind[];
+}
+export type RetryDecision = {
+    readonly action: "retry";
+    readonly prior_attempt_id: AttemptId;
+    readonly next_attempt_number: number;
+    readonly delay_ms: number;
+    readonly requires_new_attempt_id: true;
+    readonly requires_new_worker_session_id: true;
+} | {
+    readonly action: "stop";
+    readonly prior_attempt_id: AttemptId;
+    readonly reason: "attempts_exhausted" | "outcome_not_retryable" | "task_cancelled" | "run_terminal";
+};
+export type AttemptPhase = "claimed" | "running" | "terminal";
+export interface AttemptRecord extends AttemptIdentity {
+    readonly attempt_number: number;
+    readonly phase: AttemptPhase;
+    readonly claim_token: ClaimToken;
+    /** Direct provider process owned by this attempt, once launch is observed. */
+    readonly process_id: number | null;
+    readonly started_at: string | null;
+    readonly completed_at: string | null;
+    readonly terminal_outcome: TerminalOutcome | null;
+}
+export type HandoffSource = {
+    readonly result_id: ResultId;
+    readonly step_id: StepId;
+    readonly output_name: string;
+};
+interface HandoffBindingBase {
+    readonly binding_id: string;
+    readonly input_name: string;
+    readonly required: boolean;
+    readonly description: string;
+}
+export interface ReferenceHandoffBinding extends HandoffBindingBase {
+    readonly mode: "reference";
+    readonly source: HandoffSource;
+    readonly reference: {
+        readonly kind: "file" | "directory" | "artifact" | "uri";
+        readonly value: string;
+    };
+}
+export interface QuoteHandoffBinding extends HandoffBindingBase {
+    readonly mode: "quote";
+    readonly source: HandoffSource;
+    /** Exact upstream text. A resolver must not summarize or paraphrase it. */
+    readonly exact_text: string;
+    readonly selection: {
+        readonly start: number | null;
+        readonly end: number | null;
+        readonly selector: string | null;
+    };
+}
+export interface StructuredHandoffBinding extends HandoffBindingBase {
+    readonly mode: "structured";
+    readonly source: HandoffSource;
+    readonly value: JsonValue;
+    readonly schema_ref: string | null;
+}
+export interface NoHandoffBinding extends HandoffBindingBase {
+    readonly mode: "none";
+    readonly required: false;
+    readonly reason: string | null;
+}
+export type HandoffBinding = ReferenceHandoffBinding | QuoteHandoffBinding | StructuredHandoffBinding | NoHandoffBinding;
+export type StepOutputKind = "reference" | "text" | "structured";
+export interface DeclaredStepOutput {
+    readonly name: string;
+    readonly kind: StepOutputKind;
+    readonly required: boolean;
+    readonly description: string;
+    readonly schema_ref: string | null;
+}
+export type StepOutput = {
+    readonly name: string;
+    readonly kind: "reference";
+    readonly reference: {
+        readonly kind: "file" | "directory" | "artifact" | "uri";
+        readonly value: string;
+    };
+} | {
+    readonly name: string;
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly name: string;
+    readonly kind: "structured";
+    readonly value: JsonValue;
+    readonly schema_ref: string | null;
+};
+export interface StepPacket extends AttemptIdentity {
+    readonly packet_version: 1;
+    readonly attempt_number: number;
+    readonly role: string;
+    readonly constraints: readonly string[];
+    readonly standalone_prompt: string;
+    readonly input_bindings: readonly HandoffBinding[];
+    readonly output_contract: readonly DeclaredStepOutput[];
+    readonly workspace: {
+        readonly isolation: "none" | "worktree";
+        readonly working_directory: string;
+    };
+    readonly execution: {
+        readonly timeout_ms: number | null;
+        readonly cancellation_grace_ms: number;
+        readonly retry: RetryPolicy;
+    };
+    readonly created_at: string;
+}
+export declare const TERMINAL_OUTCOME_KIND_VALUES: readonly ["success", "non_zero_exit", "malformed_result", "timeout", "cancelled", "signal", "launch_error"];
+export type TerminalOutcomeKind = typeof TERMINAL_OUTCOME_KIND_VALUES[number];
+export type TerminalOutcome = {
+    readonly kind: "success";
+    readonly exit_code: 0;
+    readonly signal: null;
+} | {
+    readonly kind: "non_zero_exit";
+    readonly exit_code: number;
+    readonly signal: null;
+} | {
+    readonly kind: "malformed_result";
+    readonly exit_code: number | null;
+    readonly signal: null;
+    readonly error: string;
+} | {
+    readonly kind: "timeout";
+    readonly exit_code: number | null;
+    readonly signal: string | null;
+    readonly timeout_ms: number;
+} | {
+    readonly kind: "cancelled";
+    readonly exit_code: number | null;
+    readonly signal: string | null;
+    readonly reason: string | null;
+} | {
+    readonly kind: "signal";
+    readonly exit_code: null;
+    readonly signal: string;
+} | {
+    readonly kind: "launch_error";
+    readonly exit_code: null;
+    readonly signal: null;
+    readonly error: string;
+};
+interface ProviderEventBase extends AttemptIdentity {
+    readonly event_id: EventId;
+    readonly sequence: number;
+    readonly occurred_at: string;
+}
+export type ProviderEvent = (ProviderEventBase & {
+    readonly type: "launch_started";
+    readonly provider: string;
+}) | (ProviderEventBase & {
+    readonly type: "session_started";
+    readonly provider_session_id: string | null;
+}) | (ProviderEventBase & {
+    readonly type: "process_started";
+    readonly process_id: number;
+}) | (ProviderEventBase & {
+    readonly type: "stdout";
+    readonly text: string;
+}) | (ProviderEventBase & {
+    readonly type: "stderr";
+    readonly text: string;
+}) | (ProviderEventBase & {
+    readonly type: "termination_requested";
+    readonly reason: "timeout" | "cancellation" | "process_limit";
+}) | (ProviderEventBase & {
+    readonly type: "process_exited";
+    readonly exit_code: number | null;
+    readonly signal: string | null;
+});
+/**
+ * Provider-neutral output from one worker launch. Policy such as retry, skip,
+ * or run failure is deliberately not represented here.
+ */
+export interface ProviderExecutionResult extends AttemptIdentity {
+    readonly provider: string;
+    readonly provider_session_id: string | null;
+    readonly started_at: string;
+    readonly completed_at: string;
+    readonly outcome: TerminalOutcome;
+    readonly outputs: readonly StepOutput[];
+    readonly stdout_reference: string | null;
+    readonly stderr_reference: string | null;
+}
+/**
+ * The immutable, committed result used by downstream handoffs. A retry commits
+ * a different result_id for a different attempt_id and worker_session_id.
+ */
+export interface CommittedStepResult extends ProviderExecutionResult {
+    readonly result_id: ResultId;
+    readonly commit_status: "committed";
+    readonly committed_at: string;
+}
+export declare const RUNTIME_EVENT_TYPE_VALUES: readonly ["run_created", "run_cancel_requested", "run_terminal", "task_state_changed", "task_claimed", "task_lease_renewed", "task_claim_released", "attempt_started", "attempt_terminal", "handoff_resolved", "result_committed"];
+export type RuntimeEventType = typeof RUNTIME_EVENT_TYPE_VALUES[number];
+export interface RuntimeEvent {
+    readonly event_id: EventId;
+    readonly run_id: RunId;
+    readonly step_id: StepId | null;
+    readonly attempt_id: AttemptId | null;
+    readonly worker_session_id: WorkerSessionId | null;
+    readonly result_id: ResultId | null;
+    readonly sequence: number;
+    readonly idempotency_key: string;
+    readonly type: RuntimeEventType;
+    readonly occurred_at: string;
+    readonly payload: JsonValue;
+}
+export {};

package/dist/runtime/run-contracts.js

@@ -0,0 +1,58 @@
+/**
+ * Foundation Runtime contracts.
+ *
+ * These types describe durable run truth and the boundary to one disposable
+ * worker session. They intentionally contain no storage, scheduling, provider,
+ * CLI, or Hook behavior.
+ */
+export const TASK_STATE_VALUES = [
+    "dependency_blocked",
+    "ready",
+    "claimed",
+    "running",
+    "succeeded",
+    "failed",
+    "skipped",
+    "cancelled",
+];
+/**
+ * Failed attempts may return a non-terminal task to ready for a new attempt.
+ * Terminal task states are immutable and therefore have no outgoing edges.
+ */
+export const TASK_STATE_TRANSITIONS = {
+    dependency_blocked: ["ready", "skipped", "cancelled"],
+    ready: ["claimed", "skipped", "cancelled"],
+    claimed: ["ready", "running", "cancelled"],
+    running: ["ready", "succeeded", "failed", "cancelled"],
+    succeeded: [],
+    failed: [],
+    skipped: [],
+    cancelled: [],
+};
+export const RETRY_BACKOFF_VALUES = [
+    "none",
+    "linear",
+    "exponential",
+];
+export const TERMINAL_OUTCOME_KIND_VALUES = [
+    "success",
+    "non_zero_exit",
+    "malformed_result",
+    "timeout",
+    "cancelled",
+    "signal",
+    "launch_error",
+];
+export const RUNTIME_EVENT_TYPE_VALUES = [
+    "run_created",
+    "run_cancel_requested",
+    "run_terminal",
+    "task_state_changed",
+    "task_claimed",
+    "task_lease_renewed",
+    "task_claim_released",
+    "attempt_started",
+    "attempt_terminal",
+    "handoff_resolved",
+    "result_committed",
+];