@vercel/factory 0.0.13 → 0.0.15

package/dist/sandbox/execution-run-ledger.d.mts

@@ -0,0 +1,115 @@
+import { JsonValue } from "../schema/work.mjs";
+import { ExecutionReference } from "../schema/task.mjs";
+import "../workflows.mjs";
+import { MillisecondClock } from "../schema/common.mjs";
+import { CodingExecutionRequest, ExecutionLaunchKey, ExecutionResult } from "../schema/execution.mjs";
+import { BlobClient } from "../blob/index.mjs";
+import { HarnessTurnUsage } from "./harness-runner.mjs";
+import { z } from "zod";
+//#region src/sandbox/execution-run-ledger.d.ts
+declare const runRecordSchema: z.ZodObject<{
+  key: z.ZodType<`factory-task:task_${string}:${number}`, string, z.core.$ZodTypeInternals<`factory-task:task_${string}:${number}`, string>>;
+  request: z.ZodObject<{
+    repository: z.ZodObject<{
+      slug: z.ZodType<`${string}/${string}`, string, z.core.$ZodTypeInternals<`${string}/${string}`, string>>;
+      baseSha: z.ZodString;
+    }, z.core.$strict>;
+    harness: z.ZodEnum<{
+      "claude-code": "claude-code";
+      codex: "codex";
+      fx: "fx";
+      pi: "pi";
+    }>;
+    prompt: z.ZodString;
+    allowedConstructs: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    environment: z.ZodObject<{
+      snapshotId: z.ZodOptional<z.ZodString>;
+      timeoutMs: z.ZodNumber;
+    }, z.core.$strict>;
+    limits: z.ZodObject<{
+      maxTokens: z.ZodOptional<z.ZodNumber>;
+      maxCostUsd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    taskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+    attempt: z.ZodNumber;
+  }, z.core.$strict>;
+  execution: z.ZodObject<{
+    provider: z.ZodString;
+    sessionId: z.ZodString;
+    environmentId: z.ZodOptional<z.ZodString>;
+    harness: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>;
+  harnessSessionId: z.ZodString;
+  model: z.ZodString;
+  reportSchema: z.ZodCustom<JsonValue, JsonValue>;
+  createdAtMs: z.ZodNumber;
+  launched: z.ZodBoolean;
+  startedAtMs: z.ZodOptional<z.ZodNumber>;
+  promptedAtMs: z.ZodOptional<z.ZodNumber>;
+  resumeState: z.ZodOptional<z.ZodCustom<JsonValue, JsonValue>>;
+  turns: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    noCacheInputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    complete: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>>;
+  lostUsage: z.ZodOptional<z.ZodBoolean>;
+  result: z.ZodOptional<z.ZodType<ExecutionResult, unknown, z.core.$ZodTypeInternals<ExecutionResult, unknown>>>;
+}, z.core.$strict>;
+/** Durable identity, continuation, usage, and terminal result for one sandbox execution. */
+type RunRecord = z.infer<typeof runRecordSchema>;
+/** A run record paired with the ETag required for its next confirmed CAS update. */
+interface RunSnapshot {
+  record: RunRecord;
+  etag: string;
+}
+/** Workflow-owned outcome fields combined with observed execution identity and usage at finalize time. */
+type WithoutObservedExecution<Result extends ExecutionResult> = Result extends ExecutionResult ? Omit<Result, "execution" | "usage"> : never;
+/** Workflow-owned outcome fields before observed execution identity and usage are attached. */
+type ExecutionOutcome = WithoutObservedExecution<ExecutionResult>;
+/** Durable state, clock, and model pricing used to construct an execution ledger. */
+interface ExecutionRunLedgerOptions {
+  state: BlobClient;
+  now?: MillisecondClock;
+  calculateCostUsd?(model: string, turns: readonly HarnessTurnUsage[]): number | undefined;
+}
+/** Immutable admission arguments for one stable sandbox execution key. */
+interface AdmitExecutionRunInput {
+  request: CodingExecutionRequest;
+  key: ExecutionLaunchKey;
+  model: string;
+  environmentId: string;
+  reportSchema?: unknown;
+}
+/** Identifies the prompt acceptance to persist for one admitted execution run. */
+interface MarkExecutionRunPromptedInput {
+  readonly base: RunSnapshot;
+  readonly resumeState: unknown;
+  readonly origin: "this-driver" | "recovered";
+}
+/** Identifies the first measured turn to persist for one admitted execution run. */
+interface RecordExecutionRunTurnInput {
+  readonly base: RunSnapshot;
+  readonly turn: HarnessTurnUsage;
+  readonly resumeState: unknown;
+  readonly origin: "this-driver" | "recovered";
+}
+/** CAS-backed operations for one sandbox execution's admission and continuation state. */
+interface ExecutionRunLedger {
+  usage(record: RunRecord): ExecutionResult["usage"];
+  read(execution: ExecutionReference): Promise<RunSnapshot | null>;
+  admit(input: AdmitExecutionRunInput): Promise<RunSnapshot>;
+  markLaunched(base: RunSnapshot, resumeState: unknown): Promise<RunSnapshot>;
+  markPrompted(input: MarkExecutionRunPromptedInput): Promise<RunSnapshot>;
+  recordTurn(input: RecordExecutionRunTurnInput): Promise<RunSnapshot>;
+  finalize(base: RunSnapshot, outcome: ExecutionOutcome): Promise<ExecutionResult>;
+  pending(): Promise<readonly ExecutionReference[]>;
+}
+/** Create a CAS-backed ledger for idempotent execution admission, continuation, and finalization. */
+declare function createExecutionRunLedger(input: ExecutionRunLedgerOptions): ExecutionRunLedger;
+//#endregion
+export { AdmitExecutionRunInput, ExecutionOutcome, ExecutionRunLedger, ExecutionRunLedgerOptions, MarkExecutionRunPromptedInput, RecordExecutionRunTurnInput, RunRecord, RunSnapshot, createExecutionRunLedger };
+//# sourceMappingURL=execution-run-ledger.d.mts.map

package/dist/sandbox/execution-run-ledger.mjs

@@ -0,0 +1,209 @@
+import { jsonValueSchema } from "../schema/work.mjs";
+import { executionReferenceSchema } from "../schema/task.mjs";
+import { codingExecutionRequestSchema, executionLaunchKeySchema, executionResultSchema } from "../schema/execution.mjs";
+import { ExecutionLaunchPendingError } from "../dispatch.mjs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/sandbox/execution-run-ledger.ts
+const turnUsageSchema = z.strictObject({
+	inputTokens: z.number().int().nonnegative(),
+	noCacheInputTokens: z.number().int().nonnegative(),
+	cacheReadTokens: z.number().int().nonnegative(),
+	cacheWriteTokens: z.number().int().nonnegative(),
+	outputTokens: z.number().int().nonnegative(),
+	complete: z.boolean().optional()
+});
+const runRecordSchema = z.strictObject({
+	key: executionLaunchKeySchema,
+	request: codingExecutionRequestSchema,
+	execution: executionReferenceSchema,
+	harnessSessionId: z.string().min(1),
+	model: z.string().min(1),
+	reportSchema: jsonValueSchema,
+	createdAtMs: z.number().int().nonnegative(),
+	launched: z.boolean(),
+	startedAtMs: z.number().int().nonnegative().optional(),
+	/** Set durably right after the prompt was accepted by the runtime. */
+	promptedAtMs: z.number().int().nonnegative().optional(),
+	resumeState: jsonValueSchema.optional(),
+	turns: z.array(turnUsageSchema).readonly(),
+	/** Unobserved spend makes cost permanently unknown, even if later usage is measured. */
+	lostUsage: z.boolean().optional(),
+	result: executionResultSchema.optional()
+});
+const sameJson = (left, right) => isDeepStrictEqual(left === void 0 ? void 0 : JSON.parse(JSON.stringify(left)), right === void 0 ? void 0 : JSON.parse(JSON.stringify(right)));
+const asStoredJson = (value) => JSON.parse(JSON.stringify(value ?? null));
+const runPrefix = "factory-executions/";
+/** Create a CAS-backed ledger for idempotent execution admission, continuation, and finalization. */
+function createExecutionRunLedger(input) {
+	const { state } = input;
+	const now = input.now ?? Date.now;
+	const runPath = (sessionId) => `${runPrefix}${sessionId}/run`;
+	async function readRun(sessionId) {
+		const stored = await state.read({ pathname: runPath(sessionId) });
+		if (!stored) return null;
+		return {
+			record: runRecordSchema.parse(JSON.parse(stored.body)),
+			etag: stored.etag
+		};
+	}
+	async function writeRun(record, etag) {
+		await state.write({
+			pathname: runPath(record.execution.sessionId),
+			body: JSON.stringify(record),
+			overwrite: etag !== void 0,
+			...etag === void 0 ? {} : { ifMatch: etag }
+		});
+	}
+	async function persistRun(base, apply, verify) {
+		try {
+			await writeRun(apply(base.record), base.etag);
+		} catch {}
+		let current = await readRun(base.record.execution.sessionId);
+		if (current && !current.record.result && !verify(current.record)) {
+			try {
+				await writeRun(apply(current.record), current.etag);
+			} catch {}
+			current = await readRun(base.record.execution.sessionId);
+		}
+		if (current && (current.record.result || verify(current.record))) return current;
+		throw new Error("Execution state could not be persisted; drive again with the same reference");
+	}
+	function usage(record) {
+		const totals = {
+			inputTokens: record.turns.reduce((sum, turn) => sum + turn.inputTokens, 0),
+			outputTokens: record.turns.reduce((sum, turn) => sum + turn.outputTokens, 0)
+		};
+		const costUsd = record.lostUsage !== true && (!record.launched || record.turns.length > 0) ? input.calculateCostUsd?.(record.model, record.turns) : void 0;
+		return {
+			computeMs: Math.max(0, now() - (record.startedAtMs ?? record.createdAtMs)),
+			...totals,
+			...costUsd === void 0 ? {} : { costUsd }
+		};
+	}
+	return {
+		usage,
+		async read(execution) {
+			const stored = await readRun(execution.sessionId);
+			return stored && sameJson(stored.record.execution, execution) ? stored : null;
+		},
+		async admit(input) {
+			const request = codingExecutionRequestSchema.parse(input.request);
+			if (input.key !== `factory-task:${request.taskId}:${request.attempt}`) throw new Error("Execution key must be derived from the request's Task and attempt");
+			const sessionId = createHash("sha256").update(input.key).digest("hex");
+			const execution = executionReferenceSchema.parse({
+				provider: "vercel-sandbox",
+				sessionId,
+				environmentId: input.environmentId,
+				harness: request.harness
+			});
+			const reportSchema = jsonValueSchema.parse(asStoredJson(input.reportSchema ?? {}));
+			const matches = (record) => sameJson(record.request, request) && record.model === input.model && sameJson(record.reportSchema, reportSchema) && sameJson(record.execution, execution);
+			const existing = await readRun(sessionId);
+			if (existing) {
+				if (!matches(existing.record)) throw new Error("Launch key is already bound to a different execution request");
+				return existing;
+			}
+			const record = {
+				key: input.key,
+				request,
+				execution,
+				model: input.model,
+				reportSchema,
+				harnessSessionId: `factory-${sessionId.slice(0, 24)}`,
+				createdAtMs: now(),
+				launched: false,
+				turns: []
+			};
+			let writeError;
+			try {
+				await writeRun(record);
+			} catch (error) {
+				writeError = error;
+			}
+			let stored;
+			try {
+				stored = await readRun(sessionId);
+			} catch (cause) {
+				throw new ExecutionLaunchPendingError("Execution admission requires recovery with its original key", { cause });
+			}
+			if (!stored) {
+				if (writeError) throw writeError;
+				throw new ExecutionLaunchPendingError("Execution admission could not be confirmed");
+			}
+			if (!matches(stored.record)) throw new Error("Launch key is already bound to a different execution request");
+			return stored;
+		},
+		markLaunched(base, resumeState) {
+			const normalized = jsonValueSchema.parse(asStoredJson(resumeState));
+			return persistRun(base, (record) => record.launched ? record : {
+				...record,
+				launched: true,
+				resumeState: normalized,
+				startedAtMs: now()
+			}, (record) => record.launched);
+		},
+		markPrompted({ base, resumeState, origin }) {
+			if (!base.record.launched) throw new Error("The execution must be launched before recording a prompt");
+			const normalized = jsonValueSchema.parse(asStoredJson(resumeState));
+			return persistRun(base, (record) => record.promptedAtMs !== void 0 ? record : {
+				...record,
+				promptedAtMs: now(),
+				resumeState: normalized,
+				...origin === "recovered" || record.lostUsage ? { lostUsage: true } : {}
+			}, (record) => record.promptedAtMs !== void 0);
+		},
+		recordTurn({ base, turn, resumeState, origin }) {
+			if (!base.record.launched) throw new Error("The execution must be launched before recording a turn");
+			const normalized = jsonValueSchema.parse(asStoredJson(resumeState));
+			const measured = turnUsageSchema.parse(turn);
+			return persistRun(base, (record) => record.turns.length > 0 ? record : {
+				...record,
+				promptedAtMs: record.promptedAtMs ?? now(),
+				turns: [measured],
+				resumeState: normalized,
+				...origin === "recovered" || record.lostUsage ? { lostUsage: true } : {}
+			}, (record) => record.turns.length > 0 && record.promptedAtMs !== void 0);
+		},
+		async finalize(base, outcome) {
+			if (base.record.result) return base.record.result;
+			const record = base.record;
+			const observed = usage(record);
+			const cancelledUsage = record.launched ? observed : {
+				computeMs: 0,
+				costUsd: 0
+			};
+			const result = executionResultSchema.parse({
+				...outcome,
+				execution: record.execution,
+				usage: outcome.status === "cancelled" ? cancelledUsage : observed
+			});
+			try {
+				await writeRun({
+					...record,
+					result
+				}, base.etag);
+			} catch {
+				const latest = await readRun(record.execution.sessionId);
+				if (latest?.record.result) return latest.record.result;
+				throw new Error("Execution result could not be recorded; retry with the same key");
+			}
+			const confirmed = await readRun(record.execution.sessionId);
+			if (confirmed?.record.result) return confirmed.record.result;
+			throw new Error("Execution result could not be recorded; retry with the same key");
+		},
+		async pending() {
+			const references = [];
+			for (const path of await state.listPaths({ prefix: runPrefix })) {
+				const stored = await readRun(path.slice(19).split("/")[0]);
+				if (stored && !stored.record.result) references.push(stored.record.execution);
+			}
+			return references;
+		}
+	};
+}
+//#endregion
+export { createExecutionRunLedger };
+
+//# sourceMappingURL=execution-run-ledger.mjs.map

package/dist/sandbox/execution-run-ledger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-run-ledger.mjs","names":[],"sources":["../../src/sandbox/execution-run-ledger.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport { ExecutionLaunchPendingError } from \"../dispatch\";\nimport type { MillisecondClock } from \"../schema/common\";\nimport {\n  codingExecutionRequestSchema,\n  executionLaunchKeySchema,\n  executionResultSchema,\n  type CodingExecutionRequest,\n  type ExecutionLaunchKey,\n  type ExecutionResult,\n} from \"../schema/execution\";\nimport { executionReferenceSchema, type ExecutionReference } from \"../schema/task\";\nimport { jsonValueSchema } from \"../schema/work\";\nimport type { BlobClient } from \"../blob/index\";\nimport type { HarnessTurnUsage } from \"./harness-runner\";\n\nconst turnUsageSchema = z.strictObject({\n  inputTokens: z.number().int().nonnegative(),\n  noCacheInputTokens: z.number().int().nonnegative(),\n  cacheReadTokens: z.number().int().nonnegative(),\n  cacheWriteTokens: z.number().int().nonnegative(),\n  outputTokens: z.number().int().nonnegative(),\n  complete: z.boolean().optional(),\n});\n\nconst runRecordSchema = z.strictObject({\n  key: executionLaunchKeySchema,\n  request: codingExecutionRequestSchema,\n  execution: executionReferenceSchema,\n  harnessSessionId: z.string().min(1),\n  model: z.string().min(1),\n  reportSchema: jsonValueSchema,\n  createdAtMs: z.number().int().nonnegative(),\n  launched: z.boolean(),\n  startedAtMs: z.number().int().nonnegative().optional(),\n  /** Set durably right after the prompt was accepted by the runtime. */\n  promptedAtMs: z.number().int().nonnegative().optional(),\n  resumeState: jsonValueSchema.optional(),\n  turns: z.array(turnUsageSchema).readonly(),\n  /** Unobserved spend makes cost permanently unknown, even if later usage is measured. */\n  lostUsage: z.boolean().optional(),\n  result: executionResultSchema.optional(),\n});\n\n/** Durable identity, continuation, usage, and terminal result for one sandbox execution. */\nexport type RunRecord = z.infer<typeof runRecordSchema>;\n\nconst sameJson = (left: unknown, right: unknown) =>\n  isDeepStrictEqual(\n    left === undefined ? undefined : JSON.parse(JSON.stringify(left)),\n    right === undefined ? undefined : JSON.parse(JSON.stringify(right)),\n  );\n// SDK values can carry non-plain properties; validate their persisted JSON form.\nconst asStoredJson = (value: unknown) => JSON.parse(JSON.stringify(value ?? null)) as unknown;\n\n/** A run record paired with the ETag required for its next confirmed CAS update. */\nexport interface RunSnapshot {\n  record: RunRecord;\n  etag: string;\n}\n\n/** Workflow-owned outcome fields combined with observed execution identity and usage at finalize time. */\ntype WithoutObservedExecution<Result extends ExecutionResult> = Result extends ExecutionResult\n  ? Omit<Result, \"execution\" | \"usage\">\n  : never;\n\n/** Workflow-owned outcome fields before observed execution identity and usage are attached. */\nexport type ExecutionOutcome = WithoutObservedExecution<ExecutionResult>;\nconst runPrefix = \"factory-executions/\";\n\n/** Durable state, clock, and model pricing used to construct an execution ledger. */\nexport interface ExecutionRunLedgerOptions {\n  state: BlobClient;\n  now?: MillisecondClock;\n  calculateCostUsd?(model: string, turns: readonly HarnessTurnUsage[]): number | undefined;\n}\n\n/** Immutable admission arguments for one stable sandbox execution key. */\nexport interface AdmitExecutionRunInput {\n  request: CodingExecutionRequest;\n  key: ExecutionLaunchKey;\n  model: string;\n  environmentId: string;\n  reportSchema?: unknown;\n}\n\n/** Identifies the prompt acceptance to persist for one admitted execution run. */\nexport interface MarkExecutionRunPromptedInput {\n  readonly base: RunSnapshot;\n  readonly resumeState: unknown;\n  readonly origin: \"this-driver\" | \"recovered\";\n}\n\n/** Identifies the first measured turn to persist for one admitted execution run. */\nexport interface RecordExecutionRunTurnInput {\n  readonly base: RunSnapshot;\n  readonly turn: HarnessTurnUsage;\n  readonly resumeState: unknown;\n  readonly origin: \"this-driver\" | \"recovered\";\n}\n\n/** CAS-backed operations for one sandbox execution's admission and continuation state. */\nexport interface ExecutionRunLedger {\n  usage(record: RunRecord): ExecutionResult[\"usage\"];\n  read(execution: ExecutionReference): Promise<RunSnapshot | null>;\n  admit(input: AdmitExecutionRunInput): Promise<RunSnapshot>;\n  markLaunched(base: RunSnapshot, resumeState: unknown): Promise<RunSnapshot>;\n  markPrompted(input: MarkExecutionRunPromptedInput): Promise<RunSnapshot>;\n  recordTurn(input: RecordExecutionRunTurnInput): Promise<RunSnapshot>;\n  finalize(base: RunSnapshot, outcome: ExecutionOutcome): Promise<ExecutionResult>;\n  pending(): Promise<readonly ExecutionReference[]>;\n}\n\n/** Create a CAS-backed ledger for idempotent execution admission, continuation, and finalization. */\nexport function createExecutionRunLedger(input: ExecutionRunLedgerOptions): ExecutionRunLedger {\n  const { state } = input;\n  const now = input.now ?? Date.now;\n  const runPath = (sessionId: string) => `${runPrefix}${sessionId}/run`;\n  async function readRun(sessionId: string): Promise<{ record: RunRecord; etag: string } | null> {\n    const stored = await state.read({ pathname: runPath(sessionId) });\n    if (!stored) return null;\n    return { record: runRecordSchema.parse(JSON.parse(stored.body)), etag: stored.etag };\n  }\n\n  async function writeRun(record: RunRecord, etag?: string): Promise<void> {\n    await state.write({\n      pathname: runPath(record.execution.sessionId),\n      body: JSON.stringify(record),\n      overwrite: etag !== undefined,\n      ...(etag === undefined ? {} : { ifMatch: etag }),\n    });\n  }\n\n  // A lost write response is ambiguous; confirm durable state before the next provider effect.\n  async function persistRun(\n    base: { record: RunRecord; etag: string },\n    apply: (record: RunRecord) => RunRecord,\n    verify: (record: RunRecord) => boolean,\n  ): Promise<{ record: RunRecord; etag: string }> {\n    try {\n      await writeRun(apply(base.record), base.etag);\n    } catch {\n      // Confirmed or retried below.\n    }\n    let current = await readRun(base.record.execution.sessionId);\n    if (current && !current.record.result && !verify(current.record)) {\n      try {\n        await writeRun(apply(current.record), current.etag);\n      } catch {\n        // Confirmed below.\n      }\n      current = await readRun(base.record.execution.sessionId);\n    }\n    if (current && (current.record.result || verify(current.record))) return current;\n    throw new Error(\"Execution state could not be persisted; drive again with the same reference\");\n  }\n\n  function usage(record: RunRecord): ExecutionResult[\"usage\"] {\n    const totals = {\n      inputTokens: record.turns.reduce((sum, turn) => sum + turn.inputTokens, 0),\n      outputTokens: record.turns.reduce((sum, turn) => sum + turn.outputTokens, 0),\n    };\n    const costUsd =\n      record.lostUsage !== true && (!record.launched || record.turns.length > 0)\n        ? input.calculateCostUsd?.(record.model, record.turns)\n        : undefined;\n    return {\n      computeMs: Math.max(0, now() - (record.startedAtMs ?? record.createdAtMs)),\n      ...totals,\n      ...(costUsd === undefined ? {} : { costUsd }),\n    };\n  }\n\n  return {\n    usage,\n    async read(execution: ExecutionReference): Promise<RunSnapshot | null> {\n      const stored = await readRun(execution.sessionId);\n      return stored && sameJson(stored.record.execution, execution) ? stored : null;\n    },\n    async admit(input: AdmitExecutionRunInput): Promise<RunSnapshot> {\n      const request = codingExecutionRequestSchema.parse(input.request);\n      if (input.key !== `factory-task:${request.taskId}:${request.attempt}`)\n        throw new Error(\"Execution key must be derived from the request's Task and attempt\");\n      const sessionId = createHash(\"sha256\").update(input.key).digest(\"hex\");\n      const execution = executionReferenceSchema.parse({\n        provider: \"vercel-sandbox\",\n        sessionId,\n        environmentId: input.environmentId,\n        harness: request.harness,\n      });\n      const reportSchema = jsonValueSchema.parse(asStoredJson(input.reportSchema ?? {}));\n      const matches = (record: RunRecord) =>\n        sameJson(record.request, request) &&\n        record.model === input.model &&\n        sameJson(record.reportSchema, reportSchema) &&\n        sameJson(record.execution, execution);\n      const existing = await readRun(sessionId);\n      if (existing) {\n        if (!matches(existing.record))\n          throw new Error(\"Launch key is already bound to a different execution request\");\n        return existing;\n      }\n      const record: RunRecord = {\n        key: input.key,\n        request,\n        execution,\n        model: input.model,\n        reportSchema,\n        harnessSessionId: `factory-${sessionId.slice(0, 24)}`,\n        createdAtMs: now(),\n        launched: false,\n        turns: [],\n      };\n      let writeError: unknown;\n      try {\n        await writeRun(record);\n      } catch (error) {\n        writeError = error;\n      }\n      let stored: RunSnapshot | null;\n      try {\n        stored = await readRun(sessionId);\n      } catch (cause) {\n        throw new ExecutionLaunchPendingError(\n          \"Execution admission requires recovery with its original key\",\n          { cause },\n        );\n      }\n      if (!stored) {\n        if (writeError) throw writeError;\n        throw new ExecutionLaunchPendingError(\"Execution admission could not be confirmed\");\n      }\n      if (!matches(stored.record))\n        throw new Error(\"Launch key is already bound to a different execution request\");\n      return stored;\n    },\n    markLaunched(base: RunSnapshot, resumeState: unknown): Promise<RunSnapshot> {\n      const normalized = jsonValueSchema.parse(asStoredJson(resumeState));\n      return persistRun(\n        base,\n        (record) =>\n          record.launched\n            ? record\n            : {\n                ...record,\n                launched: true,\n                resumeState: normalized,\n                startedAtMs: now(),\n              },\n        (record) => record.launched,\n      );\n    },\n    markPrompted({\n      base,\n      resumeState,\n      origin,\n    }: MarkExecutionRunPromptedInput): Promise<RunSnapshot> {\n      if (!base.record.launched)\n        throw new Error(\"The execution must be launched before recording a prompt\");\n      const normalized = jsonValueSchema.parse(asStoredJson(resumeState));\n      return persistRun(\n        base,\n        (record) =>\n          record.promptedAtMs !== undefined\n            ? record\n            : {\n                ...record,\n                promptedAtMs: now(),\n                resumeState: normalized,\n                ...(origin === \"recovered\" || record.lostUsage ? { lostUsage: true } : {}),\n              },\n        (record) => record.promptedAtMs !== undefined,\n      );\n    },\n    recordTurn({\n      base,\n      turn,\n      resumeState,\n      origin,\n    }: RecordExecutionRunTurnInput): Promise<RunSnapshot> {\n      if (!base.record.launched)\n        throw new Error(\"The execution must be launched before recording a turn\");\n      const normalized = jsonValueSchema.parse(asStoredJson(resumeState));\n      const measured = turnUsageSchema.parse(turn);\n      return persistRun(\n        base,\n        (record) =>\n          record.turns.length > 0\n            ? record\n            : {\n                ...record,\n                promptedAtMs: record.promptedAtMs ?? now(),\n                turns: [measured],\n                resumeState: normalized,\n                ...(origin === \"recovered\" || record.lostUsage ? { lostUsage: true } : {}),\n              },\n        (record) => record.turns.length > 0 && record.promptedAtMs !== undefined,\n      );\n    },\n    async finalize(base: RunSnapshot, outcome: ExecutionOutcome): Promise<ExecutionResult> {\n      if (base.record.result) return base.record.result;\n      const record = base.record;\n      const observed = usage(record);\n      const cancelledUsage = record.launched ? observed : { computeMs: 0, costUsd: 0 };\n      const result = executionResultSchema.parse({\n        ...outcome,\n        execution: record.execution,\n        usage: outcome.status === \"cancelled\" ? cancelledUsage : observed,\n      });\n      try {\n        await writeRun({ ...record, result }, base.etag);\n      } catch {\n        const latest = await readRun(record.execution.sessionId);\n        if (latest?.record.result) return latest.record.result;\n        throw new Error(\"Execution result could not be recorded; retry with the same key\");\n      }\n      const confirmed = await readRun(record.execution.sessionId);\n      if (confirmed?.record.result) return confirmed.record.result;\n      throw new Error(\"Execution result could not be recorded; retry with the same key\");\n    },\n    async pending(): Promise<readonly ExecutionReference[]> {\n      const references: ExecutionReference[] = [];\n      for (const path of await state.listPaths({ prefix: runPrefix })) {\n        const stored = await readRun(path.slice(runPrefix.length).split(\"/\")[0]!);\n        if (stored && !stored.record.result) references.push(stored.record.execution);\n      }\n      return references;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/execution.d.mts

@@ -0,0 +1,54 @@
+import { ExecutionReference } from "../schema/task.mjs";
+import { MillisecondClock } from "../schema/common.mjs";
+import { CodingExecutionRequest, ExecutionLaunchKey, ExecutionResult } from "../schema/execution.mjs";
+import { BlobClient } from "../blob/index.mjs";
+import { ExecutionAdapter } from "../execution.mjs";
+import { ConfiguredHarnessRunner, HarnessTurnUsage, SandboxHandle } from "./harness-runner.mjs";
+import { ExecutionEnvironment } from "./execution-environment.mjs";
+import { ExecutionOutcome } from "./execution-run-ledger.mjs";
+//#region src/sandbox/execution.d.ts
+/** Context used to construct the immutable prompt for an admitted sandbox execution. */
+interface SandboxExecutionPromptContext {
+  request: CodingExecutionRequest;
+  reportSchema: unknown;
+  sandbox: SandboxHandle;
+}
+/** Context used to validate and extract artifacts after a sandbox turn completes. */
+interface SandboxExecutionOutcomeContext {
+  request: CodingExecutionRequest;
+  sandbox: SandboxHandle;
+}
+/** Configures durable state, harnesses, environments, prompts, evidence, and usage pricing. */
+interface SandboxExecutionOptions {
+  state: BlobClient;
+  harnesses: Partial<Record<CodingExecutionRequest["harness"], ConfiguredHarnessRunner>>;
+  environment: ExecutionEnvironment;
+  buildPrompt(context: SandboxExecutionPromptContext): string;
+  extractOutcome(context: SandboxExecutionOutcomeContext): Promise<ExecutionOutcome>;
+  calculateCostUsd?(model: string, turns: readonly HarnessTurnUsage[]): number | undefined;
+  sandboxTimeoutMarginMs?: number;
+  now?: MillisecondClock;
+}
+/** Coding request, stable launch key, and optional report contract for sandbox admission. */
+interface StartSandboxExecutionInput {
+  request: CodingExecutionRequest;
+  launchKey: ExecutionLaunchKey;
+  context?: SandboxExecutionStartContext;
+}
+/** Optional report contract associated with one sandbox execution launch. */
+interface SandboxExecutionStartContext {
+  reportSchema: unknown;
+}
+/** Execution adapter with explicit serial driving and pending-run discovery for sandbox work. */
+interface SandboxExecutionAdapter extends ExecutionAdapter {
+  start(input: StartSandboxExecutionInput): Promise<ExecutionReference>;
+  /** Serialize calls per execution; ledger CAS does not fence provider effects. */
+  drive(execution: ExecutionReference): Promise<ExecutionResult>;
+  /** Launch keys with admitted but unfinished runs, for drivers and drills. */
+  pending(): Promise<readonly ExecutionReference[]>;
+}
+/** Create a durable execution adapter that runs configured harnesses in Task-scoped sandboxes. */
+declare function createSandboxExecutionAdapter(options: SandboxExecutionOptions): SandboxExecutionAdapter;
+//#endregion
+export { SandboxExecutionAdapter, SandboxExecutionOptions, SandboxExecutionOutcomeContext, SandboxExecutionPromptContext, SandboxExecutionStartContext, StartSandboxExecutionInput, createSandboxExecutionAdapter };
+//# sourceMappingURL=execution.d.mts.map

package/dist/sandbox/execution.mjs

@@ -0,0 +1,228 @@
+import { codingExecutionRequestSchema, executionResultSchema } from "../schema/execution.mjs";
+import { ExecutionLaunchPendingError } from "../dispatch.mjs";
+import { ExecutionTimeoutError, withExecutionAbort } from "./execution-abort.mjs";
+import { createExecutionRunLedger } from "./execution-run-ledger.mjs";
+//#region src/sandbox/execution.ts
+const defaultSandboxTimeoutMarginMs = 3e5;
+const bounded = (reason) => reason.slice(0, 2e3);
+/** Create a durable execution adapter that runs configured harnesses in Task-scoped sandboxes. */
+function createSandboxExecutionAdapter(options) {
+	const now = options.now ?? Date.now;
+	const ledger = createExecutionRunLedger({
+		state: options.state,
+		now,
+		...options.calculateCostUsd ? { calculateCostUsd: options.calculateCostUsd } : {}
+	});
+	function configuredHarness(harness) {
+		const configured = options.harnesses[harness];
+		if (!configured || !configured.model.trim()) throw new Error(`Execution harness ${harness} has no configured runner and model`);
+		return configured;
+	}
+	const keyOf = (record) => ({
+		taskId: record.request.taskId,
+		attempt: record.request.attempt
+	});
+	const sandboxTimeout = (request) => request.environment.timeoutMs + (options.sandboxTimeoutMarginMs ?? defaultSandboxTimeoutMarginMs);
+	async function extract(sandbox, record) {
+		const request = record.request;
+		const failed = (reason) => ({
+			status: "failed",
+			artifacts: [],
+			reason: bounded(reason)
+		});
+		const usage = ledger.usage(record);
+		const { maxCostUsd, maxTokens } = request.limits;
+		if (maxCostUsd !== void 0 && usage.costUsd !== void 0 && usage.costUsd > maxCostUsd) return failed(`Execution spent $${usage.costUsd}, exceeding its maxCostUsd of $${maxCostUsd}`);
+		if (maxTokens !== void 0 && (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0) > maxTokens) return failed(`Execution used ${(usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)} tokens, exceeding its maxTokens of ${maxTokens}`);
+		return options.extractOutcome({
+			sandbox,
+			request
+		});
+	}
+	/** Best-effort idempotent environment shutdown; ambiguity propagates for retry. */
+	async function stopEnvironment(record) {
+		const sandbox = await options.environment.find(keyOf(record));
+		if (sandbox) await options.environment.stop(sandbox.sandbox);
+	}
+	return {
+		async start({ request, launchKey, context }) {
+			const parsed = codingExecutionRequestSchema.parse(request);
+			const configured = configuredHarness(parsed.harness);
+			const keyParts = {
+				taskId: parsed.taskId,
+				attempt: parsed.attempt
+			};
+			const stored = await ledger.admit({
+				request: parsed,
+				key: launchKey,
+				model: configured.model,
+				environmentId: options.environment.name(keyParts),
+				reportSchema: context?.reportSchema
+			});
+			if (stored.record.launched || stored.record.result) return stored.record.execution;
+			try {
+				await options.environment.ensure(keyParts, {
+					timeoutMs: sandboxTimeout(parsed),
+					request: parsed
+				});
+			} catch (cause) {
+				throw new ExecutionLaunchPendingError("Execution environment provisioning is unresolved; recover with the original key", { cause });
+			}
+			return stored.record.execution;
+		},
+		async inspect(execution) {
+			const stored = await ledger.read(execution);
+			if (!stored) return { status: "expired" };
+			if (stored.record.result) return {
+				status: "finished",
+				result: stored.record.result
+			};
+			const sandbox = await options.environment.find(keyOf(stored.record));
+			if (!sandbox || sandbox.liveness === "terminal") return { status: "expired" };
+			if (sandbox.liveness !== "live") throw new Error("Execution environment is transitioning; inspect again shortly");
+			return { status: "active" };
+		},
+		async stop(execution) {
+			const stored = await ledger.read(execution);
+			if (!stored) return executionResultSchema.parse({
+				status: "cancelled",
+				execution,
+				artifacts: [],
+				usage: { computeMs: 0 },
+				reason: "No admitted execution matches this reference; its cost is unknown"
+			});
+			const { record } = stored;
+			if (record.result) {
+				await stopEnvironment(record);
+				return record.result;
+			}
+			await stopEnvironment(record);
+			return ledger.finalize(stored, {
+				status: "cancelled",
+				artifacts: [],
+				reason: record.launched ? record.turns.length > 0 ? "Execution was stopped after its completed turn was recorded" : "Execution was stopped after launch; unfinished turn cost is unknown" : "Execution was stopped before its prompt was sent"
+			});
+		},
+		async drive(execution) {
+			const admitted = await ledger.read(execution);
+			if (!admitted) throw new Error("No admitted execution matches this reference");
+			let stored = admitted;
+			if (stored.record.result) return stored.record.result;
+			const request = stored.record.request;
+			const configured = configuredHarness(request.harness);
+			if (configured.model !== stored.record.model) throw new Error("Execution model changed; restore its admitted harness configuration");
+			let sandbox;
+			if (!stored.record.launched) {
+				const observed = await options.environment.ensure(keyOf(stored.record), {
+					timeoutMs: sandboxTimeout(request),
+					request
+				});
+				if (observed.liveness !== "live") throw new Error("Execution environment is not live");
+				sandbox = observed.sandbox;
+			} else {
+				const found = await options.environment.find(keyOf(stored.record));
+				if (!found || found.liveness === "terminal") return ledger.finalize(stored, {
+					status: "failed",
+					artifacts: [],
+					reason: "Execution environment expired before a result was extracted; replacement requires a new attempt"
+				});
+				if (found.liveness !== "live") throw new Error("Execution environment is transitioning; drive again shortly");
+				sandbox = found.sandbox;
+			}
+			const remainingMs = Math.max(0, request.environment.timeoutMs - (now() - (stored.record.startedAtMs ?? now())));
+			try {
+				return await withExecutionAbort({
+					timeoutMs: remainingMs,
+					isStopped: async () => {
+						const latest = await ledger.read(execution);
+						if (!latest) throw new Error("The admitted execution disappeared");
+						return latest.record.result !== void 0;
+					},
+					run: async (abortSignal) => {
+						if (remainingMs === 0) throw new ExecutionTimeoutError();
+						let observedFlip = false;
+						if (!stored.record.launched) {
+							const session = await configured.runner.open({
+								sandbox,
+								sessionId: stored.record.harnessSessionId,
+								abortSignal
+							});
+							stored = await ledger.markLaunched(stored, await session.detach());
+							if (stored.record.result) return stored.record.result;
+							observedFlip = true;
+						}
+						let turn;
+						let promptedHere = false;
+						if (stored.record.promptedAtMs === void 0 && stored.record.turns.length === 0) {
+							const session = await configured.runner.open({
+								sandbox,
+								sessionId: stored.record.harnessSessionId,
+								resumeFrom: stored.record.resumeState,
+								abortSignal
+							});
+							const prompt = options.buildPrompt({
+								request,
+								reportSchema: stored.record.reportSchema,
+								sandbox
+							});
+							const foreignFlip = !observedFlip;
+							try {
+								const inflight = await session.beginPrompt(prompt);
+								stored = await ledger.markPrompted({
+									base: stored,
+									resumeState: inflight,
+									origin: foreignFlip ? "recovered" : "this-driver"
+								});
+								promptedHere = true;
+							} catch (error) {
+								if (!(error instanceof Error && /unfinished turn/iu.test(error.message))) throw error;
+								turn = await session.continueTurn();
+								stored = await ledger.recordTurn({
+									base: stored,
+									turn: turn.usage,
+									resumeState: await session.detach(),
+									origin: "recovered"
+								});
+							}
+							if (stored.record.result) return stored.record.result;
+						}
+						if (turn === void 0 && stored.record.turns.length === 0) {
+							const session = await configured.runner.open({
+								sandbox,
+								sessionId: stored.record.harnessSessionId,
+								resumeFrom: stored.record.resumeState,
+								abortSignal
+							});
+							turn = await session.continueTurn();
+							stored = await ledger.recordTurn({
+								base: stored,
+								turn: turn.usage,
+								resumeState: await session.detach(),
+								origin: promptedHere ? "this-driver" : "recovered"
+							});
+							if (stored.record.result) return stored.record.result;
+						}
+						const result = await extract(sandbox, stored.record);
+						abortSignal.throwIfAborted();
+						return ledger.finalize(stored, result);
+					}
+				});
+			} catch (error) {
+				const latest = await ledger.read(execution);
+				if (latest?.record.result) return latest.record.result;
+				if (!(error instanceof ExecutionTimeoutError) || !latest) throw error;
+				await stopEnvironment(latest.record);
+				return ledger.finalize(latest, {
+					status: "failed",
+					artifacts: [],
+					reason: error.message
+				});
+			}
+		},
+		pending: ledger.pending
+	};
+}
+//#endregion
+export { createSandboxExecutionAdapter };
+
+//# sourceMappingURL=execution.mjs.map