@vercel/factory 0.0.14 → 0.0.16

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

package/dist/sandbox/execution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.mjs","names":[],"sources":["../../src/sandbox/execution.ts"],"sourcesContent":["import { ExecutionLaunchPendingError } from \"../dispatch\";\nimport {\n  codingExecutionRequestSchema,\n  executionResultSchema,\n  type CodingExecutionRequest,\n  type ExecutionLaunchKey,\n  type ExecutionResult,\n} from \"../schema/execution\";\nimport { type ExecutionAdapter } from \"../execution\";\nimport type { MillisecondClock } from \"../schema/common\";\nimport type { ExecutionReference } from \"../schema/task\";\nimport type { BlobClient } from \"../blob\";\nimport { ExecutionTimeoutError, withExecutionAbort } from \"./execution-abort\";\nimport type { ExecutionEnvironment } from \"./execution-environment\";\nimport {\n  createExecutionRunLedger,\n  type RunRecord,\n  type ExecutionOutcome,\n} from \"./execution-run-ledger\";\nimport type {\n  ConfiguredHarnessRunner,\n  HarnessTurn,\n  HarnessTurnUsage,\n  SandboxHandle,\n} from \"./harness-runner\";\n\nconst defaultSandboxTimeoutMarginMs = 300_000;\n\n/** Context used to construct the immutable prompt for an admitted sandbox execution. */\nexport interface SandboxExecutionPromptContext {\n  request: CodingExecutionRequest;\n  reportSchema: unknown;\n  sandbox: SandboxHandle;\n}\n\n/** Context used to validate and extract artifacts after a sandbox turn completes. */\nexport interface SandboxExecutionOutcomeContext {\n  request: CodingExecutionRequest;\n  sandbox: SandboxHandle;\n}\n\n/** Configures durable state, harnesses, environments, prompts, evidence, and usage pricing. */\nexport interface SandboxExecutionOptions {\n  state: BlobClient;\n  harnesses: Partial<Record<CodingExecutionRequest[\"harness\"], ConfiguredHarnessRunner>>;\n  environment: ExecutionEnvironment;\n  buildPrompt(context: SandboxExecutionPromptContext): string;\n  extractOutcome(context: SandboxExecutionOutcomeContext): Promise<ExecutionOutcome>;\n  calculateCostUsd?(model: string, turns: readonly HarnessTurnUsage[]): number | undefined;\n  sandboxTimeoutMarginMs?: number;\n  now?: MillisecondClock;\n}\n\n/** Coding request, stable launch key, and optional report contract for sandbox admission. */\nexport interface StartSandboxExecutionInput {\n  request: CodingExecutionRequest;\n  launchKey: ExecutionLaunchKey;\n  context?: SandboxExecutionStartContext;\n}\n\n/** Optional report contract associated with one sandbox execution launch. */\nexport interface SandboxExecutionStartContext {\n  reportSchema: unknown;\n}\n\n/** Execution adapter with explicit serial driving and pending-run discovery for sandbox work. */\nexport interface SandboxExecutionAdapter extends ExecutionAdapter {\n  start(input: StartSandboxExecutionInput): Promise<ExecutionReference>;\n  /** Serialize calls per execution; ledger CAS does not fence provider effects. */\n  drive(execution: ExecutionReference): Promise<ExecutionResult>;\n  /** Launch keys with admitted but unfinished runs, for drivers and drills. */\n  pending(): Promise<readonly ExecutionReference[]>;\n}\n\nconst bounded = (reason: string) => reason.slice(0, 2000);\n\n/** Create a durable execution adapter that runs configured harnesses in Task-scoped sandboxes. */\nexport function createSandboxExecutionAdapter(\n  options: SandboxExecutionOptions,\n): SandboxExecutionAdapter {\n  const now = options.now ?? Date.now;\n  const ledger = createExecutionRunLedger({\n    state: options.state,\n    now,\n    ...(options.calculateCostUsd ? { calculateCostUsd: options.calculateCostUsd } : {}),\n  });\n\n  function configuredHarness(harness: CodingExecutionRequest[\"harness\"]) {\n    const configured = options.harnesses[harness];\n    if (!configured || !configured.model.trim()) {\n      throw new Error(`Execution harness ${harness} has no configured runner and model`);\n    }\n    return configured;\n  }\n\n  const keyOf = (record: RunRecord) => ({\n    taskId: record.request.taskId,\n    attempt: record.request.attempt,\n  });\n\n  const sandboxTimeout = (request: CodingExecutionRequest) =>\n    request.environment.timeoutMs +\n    (options.sandboxTimeoutMarginMs ?? defaultSandboxTimeoutMarginMs);\n\n  async function extract(sandbox: SandboxHandle, record: RunRecord): Promise<ExecutionOutcome> {\n    const request = record.request;\n    const failed = (reason: string): ExecutionOutcome => ({\n      status: \"failed\",\n      artifacts: [],\n      reason: bounded(reason),\n    });\n    // Post-turn checks detect overruns; they cannot enforce a hard cap.\n    const usage = ledger.usage(record);\n    const { maxCostUsd, maxTokens } = request.limits;\n    if (maxCostUsd !== undefined && usage.costUsd !== undefined && usage.costUsd > maxCostUsd) {\n      return failed(\n        `Execution spent $${usage.costUsd}, exceeding its maxCostUsd of $${maxCostUsd}`,\n      );\n    }\n    if (\n      maxTokens !== undefined &&\n      (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0) > maxTokens\n    ) {\n      return failed(\n        `Execution used ${(usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)} tokens, exceeding its maxTokens of ${maxTokens}`,\n      );\n    }\n    return options.extractOutcome({ sandbox, request });\n  }\n\n  /** Best-effort idempotent environment shutdown; ambiguity propagates for retry. */\n  async function stopEnvironment(record: RunRecord): Promise<void> {\n    const sandbox = await options.environment.find(keyOf(record));\n    if (sandbox) await options.environment.stop(sandbox.sandbox);\n  }\n\n  return {\n    async start({ request, launchKey, context }) {\n      const parsed = codingExecutionRequestSchema.parse(request);\n      const configured = configuredHarness(parsed.harness);\n      const keyParts = { taskId: parsed.taskId, attempt: parsed.attempt };\n      const stored = await ledger.admit({\n        request: parsed,\n        key: launchKey,\n        model: configured.model,\n        environmentId: options.environment.name(keyParts),\n        reportSchema: context?.reportSchema,\n      });\n      if (stored.record.launched || stored.record.result) return stored.record.execution;\n      try {\n        await options.environment.ensure(keyParts, {\n          timeoutMs: sandboxTimeout(parsed),\n          request: parsed,\n        });\n      } catch (cause) {\n        // Admission already exists; provisioning failure must recover with the same key.\n        throw new ExecutionLaunchPendingError(\n          \"Execution environment provisioning is unresolved; recover with the original key\",\n          { cause },\n        );\n      }\n      return stored.record.execution;\n    },\n\n    async inspect(execution) {\n      const stored = await ledger.read(execution);\n      if (!stored) return { status: \"expired\" };\n      if (stored.record.result) return { status: \"finished\", result: stored.record.result };\n      const sandbox = await options.environment.find(keyOf(stored.record));\n      if (!sandbox || sandbox.liveness === \"terminal\") {\n        return { status: \"expired\" };\n      }\n      if (sandbox.liveness !== \"live\")\n        throw new Error(\"Execution environment is transitioning; inspect again shortly\");\n      return { status: \"active\" };\n    },\n\n    async stop(execution) {\n      const stored = await ledger.read(execution);\n      if (!stored) {\n        return executionResultSchema.parse({\n          status: \"cancelled\",\n          execution,\n          artifacts: [],\n          usage: { computeMs: 0 },\n          reason: \"No admitted execution matches this reference; its cost is unknown\",\n        });\n      }\n      const { record } = stored;\n      if (record.result) {\n        // A final result does not imply the sandbox has stopped.\n        await stopEnvironment(record);\n        return record.result;\n      }\n      await stopEnvironment(record);\n      return ledger.finalize(stored, {\n        status: \"cancelled\",\n        artifacts: [],\n        reason: record.launched\n          ? record.turns.length > 0\n            ? \"Execution was stopped after its completed turn was recorded\"\n            : \"Execution was stopped after launch; unfinished turn cost is unknown\"\n          : \"Execution was stopped before its prompt was sent\",\n      });\n    },\n\n    async drive(execution) {\n      const admitted = await ledger.read(execution);\n      if (!admitted) {\n        throw new Error(\"No admitted execution matches this reference\");\n      }\n      let stored = admitted;\n      if (stored.record.result) return stored.record.result;\n      const request = stored.record.request;\n      const configured = configuredHarness(request.harness);\n      if (configured.model !== stored.record.model) {\n        throw new Error(\"Execution model changed; restore its admitted harness configuration\");\n      }\n      // A launched attempt must never recreate its environment.\n      let sandbox: SandboxHandle;\n      if (!stored.record.launched) {\n        const observed = await options.environment.ensure(keyOf(stored.record), {\n          timeoutMs: sandboxTimeout(request),\n          request,\n        });\n        if (observed.liveness !== \"live\") throw new Error(\"Execution environment is not live\");\n        sandbox = observed.sandbox;\n      } else {\n        const found = await options.environment.find(keyOf(stored.record));\n        if (!found || found.liveness === \"terminal\") {\n          return ledger.finalize(stored, {\n            status: \"failed\",\n            artifacts: [],\n            reason:\n              \"Execution environment expired before a result was extracted; replacement requires a new attempt\",\n          });\n        }\n        if (found.liveness !== \"live\") {\n          throw new Error(\"Execution environment is transitioning; drive again shortly\");\n        }\n        sandbox = found.sandbox;\n      }\n      const remainingMs = Math.max(\n        0,\n        request.environment.timeoutMs - (now() - (stored.record.startedAtMs ?? now())),\n      );\n      try {\n        return await withExecutionAbort({\n          timeoutMs: remainingMs,\n          isStopped: async () => {\n            const latest = await ledger.read(execution);\n            if (!latest) throw new Error(\"The admitted execution disappeared\");\n            return latest.record.result !== undefined;\n          },\n          run: async (abortSignal) => {\n            if (remainingMs === 0) throw new ExecutionTimeoutError();\n            let observedFlip = false;\n            if (!stored.record.launched) {\n              // Confirm launch intent durably before sending any prompt.\n              const session = await configured.runner.open({\n                sandbox,\n                sessionId: stored.record.harnessSessionId,\n                abortSignal,\n              });\n              stored = await ledger.markLaunched(stored, await session.detach());\n              if (stored.record.result) return stored.record.result;\n              observedFlip = true;\n            }\n            let turn: HarnessTurn | undefined;\n            let promptedHere = false;\n            if (stored.record.promptedAtMs === undefined && stored.record.turns.length === 0) {\n              const session = await configured.runner.open({\n                sandbox,\n                sessionId: stored.record.harnessSessionId,\n                resumeFrom: stored.record.resumeState,\n                abortSignal,\n              });\n              const prompt = options.buildPrompt({\n                request,\n                reportSchema: stored.record.reportSchema,\n                sandbox,\n              });\n              // An unmarked prompt from another driver may have spent money already.\n              const foreignFlip = !observedFlip;\n              try {\n                const inflight = await session.beginPrompt(prompt);\n                stored = await ledger.markPrompted({\n                  base: stored,\n                  resumeState: inflight,\n                  origin: foreignFlip ? \"recovered\" : \"this-driver\",\n                });\n                promptedHere = true;\n              } catch (error) {\n                if (!(error instanceof Error && /unfinished turn/iu.test(error.message)))\n                  throw error;\n                // Drain the existing turn; its earlier usage was not observed.\n                turn = await session.continueTurn();\n                stored = await ledger.recordTurn({\n                  base: stored,\n                  turn: turn.usage,\n                  resumeState: await session.detach(),\n                  origin: \"recovered\",\n                });\n              }\n              if (stored.record.result) return stored.record.result;\n            }\n            if (turn === undefined && stored.record.turns.length === 0) {\n              const session = await configured.runner.open({\n                sandbox,\n                sessionId: stored.record.harnessSessionId,\n                resumeFrom: stored.record.resumeState,\n                abortSignal,\n              });\n              turn = await session.continueTurn();\n              stored = await ledger.recordTurn({\n                base: stored,\n                turn: turn.usage,\n                resumeState: await session.detach(),\n                origin: promptedHere ? \"this-driver\" : \"recovered\",\n              });\n              if (stored.record.result) return stored.record.result;\n            }\n            const result = await extract(sandbox, stored.record);\n            abortSignal.throwIfAborted();\n            return ledger.finalize(stored, result);\n          },\n        });\n      } catch (error) {\n        const latest = await ledger.read(execution);\n        if (latest?.record.result) return latest.record.result;\n        if (!(error instanceof ExecutionTimeoutError) || !latest) throw error;\n        await stopEnvironment(latest.record);\n        return ledger.finalize(latest, {\n          status: \"failed\",\n          artifacts: [],\n          reason: error.message,\n        });\n      }\n    },\n\n    pending: ledger.pending,\n  };\n}\n"],"mappings":";;;;;AA0BA,MAAM,gCAAgC;AAgDtC,MAAM,WAAW,WAAmB,OAAO,MAAM,GAAG,GAAI;;AAGxD,SAAgB,8BACd,SACyB;CACzB,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,SAAS,yBAAyB;EACtC,OAAO,QAAQ;EACf;EACA,GAAI,QAAQ,mBAAmB,EAAE,kBAAkB,QAAQ,iBAAiB,IAAI,CAAC;CACnF,CAAC;CAED,SAAS,kBAAkB,SAA4C;EACrE,MAAM,aAAa,QAAQ,UAAU;EACrC,IAAI,CAAC,cAAc,CAAC,WAAW,MAAM,KAAK,GACxC,MAAM,IAAI,MAAM,qBAAqB,QAAQ,oCAAoC;EAEnF,OAAO;CACT;CAEA,MAAM,SAAS,YAAuB;EACpC,QAAQ,OAAO,QAAQ;EACvB,SAAS,OAAO,QAAQ;CAC1B;CAEA,MAAM,kBAAkB,YACtB,QAAQ,YAAY,aACnB,QAAQ,0BAA0B;CAErC,eAAe,QAAQ,SAAwB,QAA8C;EAC3F,MAAM,UAAU,OAAO;EACvB,MAAM,UAAU,YAAsC;GACpD,QAAQ;GACR,WAAW,CAAC;GACZ,QAAQ,QAAQ,MAAM;EACxB;EAEA,MAAM,QAAQ,OAAO,MAAM,MAAM;EACjC,MAAM,EAAE,YAAY,cAAc,QAAQ;EAC1C,IAAI,eAAe,KAAA,KAAa,MAAM,YAAY,KAAA,KAAa,MAAM,UAAU,YAC7E,OAAO,OACL,oBAAoB,MAAM,QAAQ,iCAAiC,YACrE;EAEF,IACE,cAAc,KAAA,MACb,MAAM,eAAe,MAAM,MAAM,gBAAgB,KAAK,WAEvD,OAAO,OACL,mBAAmB,MAAM,eAAe,MAAM,MAAM,gBAAgB,GAAG,sCAAsC,WAC/G;EAEF,OAAO,QAAQ,eAAe;GAAE;GAAS;EAAQ,CAAC;CACpD;;CAGA,eAAe,gBAAgB,QAAkC;EAC/D,MAAM,UAAU,MAAM,QAAQ,YAAY,KAAK,MAAM,MAAM,CAAC;EAC5D,IAAI,SAAS,MAAM,QAAQ,YAAY,KAAK,QAAQ,OAAO;CAC7D;CAEA,OAAO;EACL,MAAM,MAAM,EAAE,SAAS,WAAW,WAAW;GAC3C,MAAM,SAAS,6BAA6B,MAAM,OAAO;GACzD,MAAM,aAAa,kBAAkB,OAAO,OAAO;GACnD,MAAM,WAAW;IAAE,QAAQ,OAAO;IAAQ,SAAS,OAAO;GAAQ;GAClE,MAAM,SAAS,MAAM,OAAO,MAAM;IAChC,SAAS;IACT,KAAK;IACL,OAAO,WAAW;IAClB,eAAe,QAAQ,YAAY,KAAK,QAAQ;IAChD,cAAc,SAAS;GACzB,CAAC;GACD,IAAI,OAAO,OAAO,YAAY,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO;GACzE,IAAI;IACF,MAAM,QAAQ,YAAY,OAAO,UAAU;KACzC,WAAW,eAAe,MAAM;KAChC,SAAS;IACX,CAAC;GACH,SAAS,OAAO;IAEd,MAAM,IAAI,4BACR,mFACA,EAAE,MAAM,CACV;GACF;GACA,OAAO,OAAO,OAAO;EACvB;EAEA,MAAM,QAAQ,WAAW;GACvB,MAAM,SAAS,MAAM,OAAO,KAAK,SAAS;GAC1C,IAAI,CAAC,QAAQ,OAAO,EAAE,QAAQ,UAAU;GACxC,IAAI,OAAO,OAAO,QAAQ,OAAO;IAAE,QAAQ;IAAY,QAAQ,OAAO,OAAO;GAAO;GACpF,MAAM,UAAU,MAAM,QAAQ,YAAY,KAAK,MAAM,OAAO,MAAM,CAAC;GACnE,IAAI,CAAC,WAAW,QAAQ,aAAa,YACnC,OAAO,EAAE,QAAQ,UAAU;GAE7B,IAAI,QAAQ,aAAa,QACvB,MAAM,IAAI,MAAM,+DAA+D;GACjF,OAAO,EAAE,QAAQ,SAAS;EAC5B;EAEA,MAAM,KAAK,WAAW;GACpB,MAAM,SAAS,MAAM,OAAO,KAAK,SAAS;GAC1C,IAAI,CAAC,QACH,OAAO,sBAAsB,MAAM;IACjC,QAAQ;IACR;IACA,WAAW,CAAC;IACZ,OAAO,EAAE,WAAW,EAAE;IACtB,QAAQ;GACV,CAAC;GAEH,MAAM,EAAE,WAAW;GACnB,IAAI,OAAO,QAAQ;IAEjB,MAAM,gBAAgB,MAAM;IAC5B,OAAO,OAAO;GAChB;GACA,MAAM,gBAAgB,MAAM;GAC5B,OAAO,OAAO,SAAS,QAAQ;IAC7B,QAAQ;IACR,WAAW,CAAC;IACZ,QAAQ,OAAO,WACX,OAAO,MAAM,SAAS,IACpB,gEACA,wEACF;GACN,CAAC;EACH;EAEA,MAAM,MAAM,WAAW;GACrB,MAAM,WAAW,MAAM,OAAO,KAAK,SAAS;GAC5C,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,8CAA8C;GAEhE,IAAI,SAAS;GACb,IAAI,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO;GAC/C,MAAM,UAAU,OAAO,OAAO;GAC9B,MAAM,aAAa,kBAAkB,QAAQ,OAAO;GACpD,IAAI,WAAW,UAAU,OAAO,OAAO,OACrC,MAAM,IAAI,MAAM,qEAAqE;GAGvF,IAAI;GACJ,IAAI,CAAC,OAAO,OAAO,UAAU;IAC3B,MAAM,WAAW,MAAM,QAAQ,YAAY,OAAO,MAAM,OAAO,MAAM,GAAG;KACtE,WAAW,eAAe,OAAO;KACjC;IACF,CAAC;IACD,IAAI,SAAS,aAAa,QAAQ,MAAM,IAAI,MAAM,mCAAmC;IACrF,UAAU,SAAS;GACrB,OAAO;IACL,MAAM,QAAQ,MAAM,QAAQ,YAAY,KAAK,MAAM,OAAO,MAAM,CAAC;IACjE,IAAI,CAAC,SAAS,MAAM,aAAa,YAC/B,OAAO,OAAO,SAAS,QAAQ;KAC7B,QAAQ;KACR,WAAW,CAAC;KACZ,QACE;IACJ,CAAC;IAEH,IAAI,MAAM,aAAa,QACrB,MAAM,IAAI,MAAM,6DAA6D;IAE/E,UAAU,MAAM;GAClB;GACA,MAAM,cAAc,KAAK,IACvB,GACA,QAAQ,YAAY,aAAa,IAAI,KAAK,OAAO,OAAO,eAAe,IAAI,GAC7E;GACA,IAAI;IACF,OAAO,MAAM,mBAAmB;KAC9B,WAAW;KACX,WAAW,YAAY;MACrB,MAAM,SAAS,MAAM,OAAO,KAAK,SAAS;MAC1C,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,oCAAoC;MACjE,OAAO,OAAO,OAAO,WAAW,KAAA;KAClC;KACA,KAAK,OAAO,gBAAgB;MAC1B,IAAI,gBAAgB,GAAG,MAAM,IAAI,sBAAsB;MACvD,IAAI,eAAe;MACnB,IAAI,CAAC,OAAO,OAAO,UAAU;OAE3B,MAAM,UAAU,MAAM,WAAW,OAAO,KAAK;QAC3C;QACA,WAAW,OAAO,OAAO;QACzB;OACF,CAAC;OACD,SAAS,MAAM,OAAO,aAAa,QAAQ,MAAM,QAAQ,OAAO,CAAC;OACjE,IAAI,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO;OAC/C,eAAe;MACjB;MACA,IAAI;MACJ,IAAI,eAAe;MACnB,IAAI,OAAO,OAAO,iBAAiB,KAAA,KAAa,OAAO,OAAO,MAAM,WAAW,GAAG;OAChF,MAAM,UAAU,MAAM,WAAW,OAAO,KAAK;QAC3C;QACA,WAAW,OAAO,OAAO;QACzB,YAAY,OAAO,OAAO;QAC1B;OACF,CAAC;OACD,MAAM,SAAS,QAAQ,YAAY;QACjC;QACA,cAAc,OAAO,OAAO;QAC5B;OACF,CAAC;OAED,MAAM,cAAc,CAAC;OACrB,IAAI;QACF,MAAM,WAAW,MAAM,QAAQ,YAAY,MAAM;QACjD,SAAS,MAAM,OAAO,aAAa;SACjC,MAAM;SACN,aAAa;SACb,QAAQ,cAAc,cAAc;QACtC,CAAC;QACD,eAAe;OACjB,SAAS,OAAO;QACd,IAAI,EAAE,iBAAiB,SAAS,oBAAoB,KAAK,MAAM,OAAO,IACpE,MAAM;QAER,OAAO,MAAM,QAAQ,aAAa;QAClC,SAAS,MAAM,OAAO,WAAW;SAC/B,MAAM;SACN,MAAM,KAAK;SACX,aAAa,MAAM,QAAQ,OAAO;SAClC,QAAQ;QACV,CAAC;OACH;OACA,IAAI,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO;MACjD;MACA,IAAI,SAAS,KAAA,KAAa,OAAO,OAAO,MAAM,WAAW,GAAG;OAC1D,MAAM,UAAU,MAAM,WAAW,OAAO,KAAK;QAC3C;QACA,WAAW,OAAO,OAAO;QACzB,YAAY,OAAO,OAAO;QAC1B;OACF,CAAC;OACD,OAAO,MAAM,QAAQ,aAAa;OAClC,SAAS,MAAM,OAAO,WAAW;QAC/B,MAAM;QACN,MAAM,KAAK;QACX,aAAa,MAAM,QAAQ,OAAO;QAClC,QAAQ,eAAe,gBAAgB;OACzC,CAAC;OACD,IAAI,OAAO,OAAO,QAAQ,OAAO,OAAO,OAAO;MACjD;MACA,MAAM,SAAS,MAAM,QAAQ,SAAS,OAAO,MAAM;MACnD,YAAY,eAAe;MAC3B,OAAO,OAAO,SAAS,QAAQ,MAAM;KACvC;IACF,CAAC;GACH,SAAS,OAAO;IACd,MAAM,SAAS,MAAM,OAAO,KAAK,SAAS;IAC1C,IAAI,QAAQ,OAAO,QAAQ,OAAO,OAAO,OAAO;IAChD,IAAI,EAAE,iBAAiB,0BAA0B,CAAC,QAAQ,MAAM;IAChE,MAAM,gBAAgB,OAAO,MAAM;IACnC,OAAO,OAAO,SAAS,QAAQ;KAC7B,QAAQ;KACR,WAAW,CAAC;KACZ,QAAQ,MAAM;IAChB,CAAC;GACH;EACF;EAEA,SAAS,OAAO;CAClB;AACF"}

package/dist/sandbox/harness-runner.d.mts

@@ -0,0 +1,79 @@
+import { SandboxWorkspaceHandle } from "./workspace.mjs";
+import { HarnessAgentAdapter } from "@ai-sdk/harness/agent";
+//#region src/sandbox/harness-runner.d.ts
+/** Normalized per-turn token accounting, including whether the observation is complete. */
+interface HarnessTurnUsage {
+  inputTokens: number;
+  noCacheInputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  outputTokens: number;
+  /** False when the SDK omitted token details or suspension lost usage. */
+  complete?: boolean;
+}
+/** Bounded harness response text paired with its normalized usage observation. */
+interface HarnessTurn {
+  text: string;
+  usage: HarnessTurnUsage;
+}
+/** One recoverable harness session opened against a supplied sandbox. */
+interface HarnessSession {
+  hasUnfinishedTurn(): boolean;
+  /** Do not reuse this handle; persist the returned state before reopening. */
+  beginPrompt(text: string): Promise<unknown>;
+  /** Drain the current turn — still running or already finished — to completion. */
+  continueTurn(): Promise<HarnessTurn>;
+  /** Persist cross-process resume state; the session handle is done afterwards. */
+  detach(): Promise<unknown>;
+}
+/** Minimal sandbox command and working-directory boundary required by harness runners. */
+interface SandboxHandle extends SandboxWorkspaceHandle {
+  runCommand(params: SandboxRunCommandInput): Promise<SandboxRunCommandResult>;
+}
+/** Executable, arguments, and optional execution bounds for a sandbox command. */
+interface SandboxRunCommandInput {
+  cmd: string;
+  args?: readonly string[];
+  cwd?: string;
+  timeoutMs?: number;
+}
+/** Exit status and lazy output streams returned by a sandbox command. */
+interface SandboxRunCommandResult {
+  exitCode: number | null;
+  stdout(): Promise<string>;
+  stderr(): Promise<string>;
+}
+/** Sandbox, session identity, and optional continuation used to open a harness session. */
+interface OpenHarnessSessionOptions {
+  sandbox: SandboxHandle;
+  sessionId: string;
+  resumeFrom?: unknown;
+  abortSignal?: AbortSignal;
+}
+/** Opens recoverable, serial harness sessions against a supplied sandbox. */
+interface HarnessRunner {
+  open(options: OpenHarnessSessionOptions): Promise<HarnessSession>;
+}
+/** Harness adapter, model, workspace, and continuation policy used by a harness runner. */
+interface HarnessAgentRunnerOptions {
+  harness: HarnessAgentAdapter;
+  model: string;
+  /** Directory used by the harness SDK inside the sandbox. */
+  workDir?: string;
+  /** Pi resolves a provider-qualified ID; persisted pricing uses the gateway ID. */
+  providerModel?: string;
+  /** Pi suspends its host model loop by aborting and replaying its journal. */
+  suspensionLosesUsage?: boolean;
+  /** A changed or unavailable runtime identity makes continuation usage incomplete. */
+  continuationIdentity?(state: unknown): string | undefined;
+}
+/** Model and configured runner selected for one execution harness. */
+interface ConfiguredHarnessRunner {
+  model: string;
+  runner: HarnessRunner;
+}
+/** Adapt an AI SDK harness agent into Factory's durable open/continue/detach session contract. */
+declare function createHarnessAgentRunner(options: HarnessAgentRunnerOptions): HarnessRunner;
+//#endregion
+export { ConfiguredHarnessRunner, HarnessAgentRunnerOptions, HarnessRunner, HarnessSession, HarnessTurn, HarnessTurnUsage, OpenHarnessSessionOptions, SandboxHandle, SandboxRunCommandInput, SandboxRunCommandResult, createHarnessAgentRunner };
+//# sourceMappingURL=harness-runner.d.mts.map

package/dist/sandbox/harness-runner.mjs

@@ -0,0 +1,162 @@
+import { jsonValueSchema } from "../schema/work.mjs";
+import "./workspace.mjs";
+import { z } from "zod";
+import { HarnessAgent } from "@ai-sdk/harness/agent";
+import { createVercelSandbox } from "@ai-sdk/sandbox-vercel";
+//#region src/sandbox/harness-runner.ts
+const count = z.number().int().nonnegative();
+const turnSchema = z.object({
+	text: z.string(),
+	usage: z.object({
+		inputTokens: count,
+		noCacheInputTokens: count,
+		cacheReadTokens: count,
+		cacheWriteTokens: count,
+		outputTokens: count,
+		complete: z.boolean()
+	})
+});
+const resumeSchema = z.strictObject({
+	harness: z.string(),
+	model: z.string(),
+	session: jsonValueSchema,
+	usageIncomplete: z.boolean(),
+	completedTurn: turnSchema.optional()
+});
+const usageSchema = z.object({
+	inputTokens: count.optional(),
+	outputTokens: count.optional(),
+	inputTokenDetails: z.object({
+		noCacheTokens: count.optional(),
+		cacheReadTokens: count.optional(),
+		cacheWriteTokens: count.optional()
+	}).optional()
+});
+function observedTurn(result, usageIncomplete) {
+	const usage = usageSchema.parse(result.totalUsage ?? {});
+	const details = usage.inputTokenDetails;
+	return {
+		text: result.text.slice(0, 2e3),
+		usage: {
+			inputTokens: usage.inputTokens ?? 0,
+			noCacheInputTokens: details?.noCacheTokens ?? 0,
+			cacheReadTokens: details?.cacheReadTokens ?? 0,
+			cacheWriteTokens: details?.cacheWriteTokens ?? 0,
+			outputTokens: usage.outputTokens ?? 0,
+			complete: !usageIncomplete && usage.inputTokens !== void 0 && usage.outputTokens !== void 0 && details?.noCacheTokens !== void 0 && details.cacheReadTokens !== void 0 && details.cacheWriteTokens !== void 0 && details.noCacheTokens + details.cacheReadTokens + details.cacheWriteTokens === usage.inputTokens
+		}
+	};
+}
+/** Adapt an AI SDK harness agent into Factory's durable open/continue/detach session contract. */
+function createHarnessAgentRunner(options) {
+	return { async open({ sandbox, sessionId, resumeFrom, abortSignal }) {
+		abortSignal?.throwIfAborted();
+		const abortOptions = abortSignal ? { abortSignal } : {};
+		const saved = resumeFrom === void 0 ? void 0 : resumeSchema.parse(resumeFrom);
+		if (saved && (saved.harness !== options.harness.harnessId || saved.model !== options.model)) throw new Error("Harness continuation belongs to a different harness or model");
+		if (saved?.completedTurn) {
+			const turn = saved.completedTurn;
+			return {
+				hasUnfinishedTurn: () => false,
+				beginPrompt: async () => {
+					throw new Error("A completed turn cannot be prompted again");
+				},
+				continueTurn: async () => {
+					abortSignal?.throwIfAborted();
+					return turn;
+				},
+				detach: async () => saved
+			};
+		}
+		const provider = createVercelSandbox({ sandbox });
+		let finished = false;
+		const observe = (emit) => (event) => {
+			if (event.type === "finish") finished = true;
+			emit(event);
+		};
+		const harness = {
+			...options.harness,
+			async doStart(input) {
+				const runtime = await options.harness.doStart(input);
+				return {
+					...runtime,
+					doPromptTurn: (turn) => runtime.doPromptTurn({
+						...turn,
+						emit: observe(turn.emit)
+					}),
+					doContinueTurn: (turn) => runtime.doContinueTurn({
+						...turn,
+						emit: observe(turn.emit)
+					})
+				};
+			}
+		};
+		const agent = new HarnessAgent({
+			id: `factory-${options.harness.harnessId}`,
+			harness,
+			model: options.providerModel ?? options.model,
+			sandbox: provider,
+			sandboxConfig: { workDir: options.workDir ?? "workspace" }
+		});
+		const session = await agent.createSession({
+			sessionId,
+			...abortOptions,
+			...saved ? { resumeFrom: saved.session } : {}
+		});
+		let usageIncomplete = saved?.usageIncomplete ?? false;
+		let detached;
+		async function abortable(run) {
+			try {
+				return await run();
+			} finally {
+				if (abortSignal?.aborted) await session.destroy();
+			}
+		}
+		const snapshot = (state, completedTurn) => resumeSchema.parse({
+			harness: options.harness.harnessId,
+			model: options.model,
+			session: JSON.parse(JSON.stringify(state)),
+			usageIncomplete,
+			...completedTurn ? { completedTurn } : {}
+		});
+		return {
+			hasUnfinishedTurn: () => session.hasUnfinishedTurn(),
+			beginPrompt: (text) => abortable(async () => {
+				const stream = await agent.stream({
+					session,
+					prompt: text,
+					...abortOptions
+				});
+				const state = await session.detach();
+				if (state.continueFrom && !finished) {
+					usageIncomplete ||= options.suspensionLosesUsage === true;
+					return snapshot(state);
+				}
+				return snapshot(state, observedTurn({
+					text: await stream.text,
+					totalUsage: await stream.totalUsage
+				}, usageIncomplete));
+			}),
+			continueTurn: () => abortable(async () => {
+				const result = await agent.continueGenerate({
+					session,
+					...abortOptions
+				});
+				const state = await session.detach();
+				if (saved && options.continuationIdentity) {
+					const before = options.continuationIdentity(saved.session);
+					const after = options.continuationIdentity(state);
+					usageIncomplete ||= before === void 0 || after === void 0 || before !== after;
+				}
+				const turn = observedTurn(result, usageIncomplete);
+				detached = snapshot(state, turn);
+				return turn;
+			}),
+			detach: async () => detached ?? snapshot(await session.detach())
+		};
+	} };
+}
+//#endregion
+export { createHarnessAgentRunner };
+
+//# sourceMappingURL=harness-runner.mjs.map

package/dist/sandbox/harness-runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-runner.mjs","names":[],"sources":["../../src/sandbox/harness-runner.ts"],"sourcesContent":["import {\n  HarnessAgent,\n  type HarnessAgentAdapter,\n  type HarnessAgentResumeSessionState,\n} from \"@ai-sdk/harness/agent\";\nimport { createVercelSandbox } from \"@ai-sdk/sandbox-vercel\";\nimport type { HarnessV1StreamPart } from \"@ai-sdk/harness\";\nimport { jsonValueSchema } from \"../schema/work\";\nimport { z } from \"zod\";\nimport { defaultHarnessWorkDir, type SandboxWorkspaceHandle } from \"./workspace\";\n\n/** Normalized per-turn token accounting, including whether the observation is complete. */\nexport interface HarnessTurnUsage {\n  inputTokens: number;\n  noCacheInputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  outputTokens: number;\n  /** False when the SDK omitted token details or suspension lost usage. */\n  complete?: boolean;\n}\n\n/** Bounded harness response text paired with its normalized usage observation. */\nexport interface HarnessTurn {\n  text: string;\n  usage: HarnessTurnUsage;\n}\n\n/** One recoverable harness session opened against a supplied sandbox. */\nexport interface HarnessSession {\n  hasUnfinishedTurn(): boolean;\n  /** Do not reuse this handle; persist the returned state before reopening. */\n  beginPrompt(text: string): Promise<unknown>;\n  /** Drain the current turn — still running or already finished — to completion. */\n  continueTurn(): Promise<HarnessTurn>;\n  /** Persist cross-process resume state; the session handle is done afterwards. */\n  detach(): Promise<unknown>;\n}\n\n/** Minimal sandbox command and working-directory boundary required by harness runners. */\nexport interface SandboxHandle extends SandboxWorkspaceHandle {\n  runCommand(params: SandboxRunCommandInput): Promise<SandboxRunCommandResult>;\n}\n\n/** Executable, arguments, and optional execution bounds for a sandbox command. */\nexport interface SandboxRunCommandInput {\n  cmd: string;\n  args?: readonly string[];\n  cwd?: string;\n  timeoutMs?: number;\n}\n\n/** Exit status and lazy output streams returned by a sandbox command. */\nexport interface SandboxRunCommandResult {\n  exitCode: number | null;\n  stdout(): Promise<string>;\n  stderr(): Promise<string>;\n}\n\n/** Sandbox, session identity, and optional continuation used to open a harness session. */\nexport interface OpenHarnessSessionOptions {\n  sandbox: SandboxHandle;\n  sessionId: string;\n  resumeFrom?: unknown;\n  abortSignal?: AbortSignal;\n}\n\n/** Opens recoverable, serial harness sessions against a supplied sandbox. */\nexport interface HarnessRunner {\n  open(options: OpenHarnessSessionOptions): Promise<HarnessSession>;\n}\n\n/** Harness adapter, model, workspace, and continuation policy used by a harness runner. */\nexport interface HarnessAgentRunnerOptions {\n  harness: HarnessAgentAdapter;\n  model: string;\n  /** Directory used by the harness SDK inside the sandbox. */\n  workDir?: string;\n  /** Pi resolves a provider-qualified ID; persisted pricing uses the gateway ID. */\n  providerModel?: string;\n  /** Pi suspends its host model loop by aborting and replaying its journal. */\n  suspensionLosesUsage?: boolean;\n  /** A changed or unavailable runtime identity makes continuation usage incomplete. */\n  continuationIdentity?(state: unknown): string | undefined;\n}\n\n/** Model and configured runner selected for one execution harness. */\nexport interface ConfiguredHarnessRunner {\n  model: string;\n  runner: HarnessRunner;\n}\n\nconst count = z.number().int().nonnegative();\nconst turnSchema = z.object({\n  text: z.string(),\n  usage: z.object({\n    inputTokens: count,\n    noCacheInputTokens: count,\n    cacheReadTokens: count,\n    cacheWriteTokens: count,\n    outputTokens: count,\n    complete: z.boolean(),\n  }),\n});\nconst resumeSchema = z.strictObject({\n  harness: z.string(),\n  model: z.string(),\n  session: jsonValueSchema,\n  usageIncomplete: z.boolean(),\n  completedTurn: turnSchema.optional(),\n});\nconst usageSchema = z.object({\n  inputTokens: count.optional(),\n  outputTokens: count.optional(),\n  inputTokenDetails: z\n    .object({\n      noCacheTokens: count.optional(),\n      cacheReadTokens: count.optional(),\n      cacheWriteTokens: count.optional(),\n    })\n    .optional(),\n});\n\nfunction observedTurn(\n  result: { text: string; totalUsage: unknown },\n  usageIncomplete: boolean,\n): HarnessTurn & z.infer<typeof turnSchema> {\n  const usage = usageSchema.parse(result.totalUsage ?? {});\n  const details = usage.inputTokenDetails;\n  return {\n    text: result.text.slice(0, 2000),\n    usage: {\n      inputTokens: usage.inputTokens ?? 0,\n      noCacheInputTokens: details?.noCacheTokens ?? 0,\n      cacheReadTokens: details?.cacheReadTokens ?? 0,\n      cacheWriteTokens: details?.cacheWriteTokens ?? 0,\n      outputTokens: usage.outputTokens ?? 0,\n      complete:\n        !usageIncomplete &&\n        usage.inputTokens !== undefined &&\n        usage.outputTokens !== undefined &&\n        details?.noCacheTokens !== undefined &&\n        details.cacheReadTokens !== undefined &&\n        details.cacheWriteTokens !== undefined &&\n        details.noCacheTokens + details.cacheReadTokens + details.cacheWriteTokens ===\n          usage.inputTokens,\n    },\n  };\n}\n\n/** Adapt an AI SDK harness agent into Factory's durable open/continue/detach session contract. */\nexport function createHarnessAgentRunner(options: HarnessAgentRunnerOptions): HarnessRunner {\n  return {\n    async open({ sandbox, sessionId, resumeFrom, abortSignal }) {\n      abortSignal?.throwIfAborted();\n      const abortOptions = abortSignal ? { abortSignal } : {};\n      const saved = resumeFrom === undefined ? undefined : resumeSchema.parse(resumeFrom);\n      if (saved && (saved.harness !== options.harness.harnessId || saved.model !== options.model)) {\n        throw new Error(\"Harness continuation belongs to a different harness or model\");\n      }\n      if (saved?.completedTurn) {\n        const turn = saved.completedTurn;\n        return {\n          hasUnfinishedTurn: () => false,\n          beginPrompt: async () => {\n            throw new Error(\"A completed turn cannot be prompted again\");\n          },\n          continueTurn: async () => {\n            abortSignal?.throwIfAborted();\n            return turn;\n          },\n          detach: async () => saved,\n        };\n      }\n      // sandbox-vercel types target Sandbox 3.x; this caller-owned 2.x instance has the same operations.\n      const provider = createVercelSandbox({ sandbox } as unknown as Parameters<\n        typeof createVercelSandbox\n      >[0]);\n      let finished = false;\n      const observe =\n        (emit: (event: HarnessV1StreamPart) => void) => (event: HarnessV1StreamPart) => {\n          if (event.type === \"finish\") finished = true;\n          emit(event);\n        };\n      const harness: HarnessAgentAdapter = {\n        ...options.harness,\n        async doStart(input) {\n          const runtime = await options.harness.doStart(input);\n          return {\n            ...runtime,\n            doPromptTurn: (turn) => runtime.doPromptTurn({ ...turn, emit: observe(turn.emit) }),\n            doContinueTurn: (turn) => runtime.doContinueTurn({ ...turn, emit: observe(turn.emit) }),\n          };\n        },\n      };\n      const agent = new HarnessAgent({\n        id: `factory-${options.harness.harnessId}`,\n        harness,\n        model: options.providerModel ?? options.model,\n        sandbox: provider,\n        sandboxConfig: { workDir: options.workDir ?? defaultHarnessWorkDir },\n      });\n      const session = await agent.createSession({\n        sessionId,\n        ...abortOptions,\n        // HarnessAgent validates the provider-specific lifecycle payload.\n        ...(saved\n          ? { resumeFrom: saved.session as unknown as HarnessAgentResumeSessionState }\n          : {}),\n      });\n      let usageIncomplete = saved?.usageIncomplete ?? false;\n      let detached: z.infer<typeof resumeSchema> | undefined;\n      async function abortable<T>(run: () => Promise<T>): Promise<T> {\n        try {\n          return await run();\n        } finally {\n          // Pi may emit an error before its host loop stops; wait for cleanup.\n          if (abortSignal?.aborted) await session.destroy();\n        }\n      }\n      const snapshot = (\n        state: HarnessAgentResumeSessionState,\n        completedTurn?: z.infer<typeof turnSchema>,\n      ) =>\n        resumeSchema.parse({\n          harness: options.harness.harnessId,\n          model: options.model,\n          session: JSON.parse(JSON.stringify(state)) as unknown,\n          usageIncomplete,\n          ...(completedTurn ? { completedTurn } : {}),\n        });\n      return {\n        hasUnfinishedTurn: () => session.hasUnfinishedTurn(),\n        beginPrompt: (text) =>\n          abortable(async () => {\n            // hasUnfinishedTurn can reflect local intent; stream confirms runtime acceptance.\n            const stream = await agent.stream({ session, prompt: text, ...abortOptions });\n            const state = await session.detach();\n            if (state.continueFrom && !finished) {\n              usageIncomplete ||= options.suspensionLosesUsage === true;\n              return snapshot(state);\n            }\n            // A fast turn can finish before detach; retain its result for continuation.\n            return snapshot(\n              state,\n              observedTurn(\n                {\n                  text: await stream.text,\n                  totalUsage: await stream.totalUsage,\n                },\n                usageIncomplete,\n              ),\n            );\n          }),\n        continueTurn: () =>\n          abortable(async () => {\n            const result = await agent.continueGenerate({ session, ...abortOptions });\n            const state = await session.detach();\n            if (saved && options.continuationIdentity) {\n              const before = options.continuationIdentity(saved.session);\n              const after = options.continuationIdentity(state);\n              usageIncomplete ||= before === undefined || after === undefined || before !== after;\n            }\n            const turn = observedTurn(result, usageIncomplete);\n            detached = snapshot(state, turn);\n            return turn;\n          }),\n        detach: async () => detached ?? snapshot(await session.detach()),\n      };\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/index.d.mts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import { CommandSandbox, CommandSandboxRunInput, CommandSandboxRunResult } from "./command.mjs";
+import { HarnessWorkspace, SandboxOutputPath, SandboxSession, SandboxWorkspaceHandle, defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath } from "./workspace.mjs";
+import { ConfiguredHarnessRunner, HarnessAgentRunnerOptions, HarnessRunner, HarnessSession, HarnessTurn, HarnessTurnUsage, OpenHarnessSessionOptions, SandboxHandle, SandboxRunCommandInput, SandboxRunCommandResult, createHarnessAgentRunner } from "./harness-runner.mjs";
+import { EnsureExecutionEnvironmentOptions, EnvironmentLiveness, ExecutionEnvironment, ExecutionEnvironmentObservation } from "./execution-environment.mjs";
+import { AdmitExecutionRunInput, ExecutionOutcome, ExecutionRunLedger, ExecutionRunLedgerOptions, MarkExecutionRunPromptedInput, RecordExecutionRunTurnInput, RunRecord, RunSnapshot, createExecutionRunLedger } from "./execution-run-ledger.mjs";
+import { SandboxExecutionAdapter, SandboxExecutionOptions, SandboxExecutionOutcomeContext, SandboxExecutionPromptContext, SandboxExecutionStartContext, StartSandboxExecutionInput, createSandboxExecutionAdapter } from "./execution.mjs";
+import { ExecutionAbortOptions, ExecutionTimeoutError, withExecutionAbort } from "./execution-abort.mjs";
+import { EnsureTaskSandboxOptions, FindTaskSandboxOptions, SandboxApi, TaskSandboxEnvironmentOptions, TaskSandboxScope, createTaskSandboxEnvironment, ensureTaskSandbox, findTaskSandbox, stopTaskSandbox, taskSandboxName, taskSandboxTags } from "./task-environment.mjs";
+export { type AdmitExecutionRunInput, type CommandSandbox, type CommandSandboxRunInput, type CommandSandboxRunResult, type ConfiguredHarnessRunner, type EnsureExecutionEnvironmentOptions, type EnsureTaskSandboxOptions, type EnvironmentLiveness, type ExecutionAbortOptions, type ExecutionEnvironment, type ExecutionEnvironmentObservation, type ExecutionOutcome, type ExecutionRunLedger, type ExecutionRunLedgerOptions, ExecutionTimeoutError, type FindTaskSandboxOptions, type HarnessAgentRunnerOptions, type HarnessRunner, type HarnessSession, type HarnessTurn, type HarnessTurnUsage, type HarnessWorkspace, type MarkExecutionRunPromptedInput, type OpenHarnessSessionOptions, type RecordExecutionRunTurnInput, type RunRecord, type RunSnapshot, type SandboxApi, type SandboxExecutionAdapter, type SandboxExecutionOptions, type SandboxExecutionOutcomeContext, type SandboxExecutionPromptContext, type SandboxExecutionStartContext, type SandboxHandle, type SandboxOutputPath, type SandboxRunCommandInput, type SandboxRunCommandResult, type SandboxSession, type SandboxWorkspaceHandle, type StartSandboxExecutionInput, type TaskSandboxEnvironmentOptions, type TaskSandboxScope, createExecutionRunLedger, createHarnessAgentRunner, createSandboxExecutionAdapter, createTaskSandboxEnvironment, defaultHarnessWorkDir, ensureTaskSandbox, findTaskSandbox, harnessWorkspace, parseSandboxOutputPath, stopTaskSandbox, taskSandboxName, taskSandboxTags, withExecutionAbort };

package/dist/sandbox/index.mjs

@@ -0,0 +1,7 @@
+import { ExecutionTimeoutError, withExecutionAbort } from "./execution-abort.mjs";
+import { createExecutionRunLedger } from "./execution-run-ledger.mjs";
+import { createSandboxExecutionAdapter } from "./execution.mjs";
+import { defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath } from "./workspace.mjs";
+import { createHarnessAgentRunner } from "./harness-runner.mjs";
+import { createTaskSandboxEnvironment, ensureTaskSandbox, findTaskSandbox, stopTaskSandbox, taskSandboxName, taskSandboxTags } from "./task-environment.mjs";
+export { ExecutionTimeoutError, createExecutionRunLedger, createHarnessAgentRunner, createSandboxExecutionAdapter, createTaskSandboxEnvironment, defaultHarnessWorkDir, ensureTaskSandbox, findTaskSandbox, harnessWorkspace, parseSandboxOutputPath, stopTaskSandbox, taskSandboxName, taskSandboxTags, withExecutionAbort };

package/dist/sandbox/task-environment.d.mts

@@ -0,0 +1,50 @@
+import { CodingExecutionRequest, TaskAttemptRef } from "../schema/execution.mjs";
+import { ExecutionEnvironment } from "./execution-environment.mjs";
+import { Sandbox } from "@vercel/sandbox";
+//#region src/sandbox/task-environment.d.ts
+/** Isolates stores that reuse Task IDs within the project's shared sandbox namespace. */
+interface TaskSandboxScope {
+  scope: string;
+}
+/** Injectable subset of the Vercel Sandbox API used for creation and exact identity discovery. */
+type SandboxApi = Pick<typeof Sandbox, "getOrCreate" | "get" | "list">;
+/** Derive a deterministic provider sandbox name from a scoped Task-attempt identity. */
+declare function taskSandboxName(key: TaskAttemptRef, scope: string): string;
+/** Build the complete tag set used to discover and re-verify a Task sandbox. */
+declare function taskSandboxTags(key: TaskAttemptRef, scope: string): Record<string, string>;
+/** Configures idempotent creation and workspace seeding for a Task sandbox. */
+interface EnsureTaskSandboxOptions extends TaskSandboxScope {
+  /** Sandbox lifetime; callers add margin over the execution timeout. */
+  timeoutMs: number;
+  /** Seeds the workspace; must be idempotent because a crashed seed reruns. */
+  seed(sandbox: Sandbox): Promise<void>;
+  runtime?: string;
+  ports?: readonly number[];
+  seededMarker?: string;
+  api?: SandboxApi;
+}
+/** Create or recover the exact sandbox for a Task attempt and ensure seeding completed. */
+declare function ensureTaskSandbox(key: TaskAttemptRef, options: EnsureTaskSandboxOptions): Promise<Sandbox>;
+/** Scope and provider API used to discover an existing Task sandbox. */
+interface FindTaskSandboxOptions extends TaskSandboxScope {
+  api?: SandboxApi;
+}
+/** Discover an existing Task sandbox without resuming or replacing it. */
+declare function findTaskSandbox(key: TaskAttemptRef, options: FindTaskSandboxOptions): Promise<Sandbox | null>;
+/** Stop a live Task sandbox idempotently while treating provider disappearance as success. */
+declare function stopTaskSandbox(sandbox: Sandbox): Promise<void>;
+/** Scoped creation, seeding, and provider dependencies for a Task sandbox environment. */
+interface TaskSandboxEnvironmentOptions {
+  /** Deployment- or run-unique namespace; see {@link TaskSandboxScope}. */
+  scope: string;
+  seed(request: CodingExecutionRequest, sandbox: Sandbox): Promise<void>;
+  runtime?: EnsureTaskSandboxOptions["runtime"];
+  ports?: readonly number[];
+  seededMarker?: string;
+  api?: SandboxApi;
+}
+/** Adapt scoped Vercel Sandbox creation and discovery to the execution-environment contract. */
+declare function createTaskSandboxEnvironment(options: TaskSandboxEnvironmentOptions): ExecutionEnvironment<Sandbox>;
+//#endregion
+export { EnsureTaskSandboxOptions, FindTaskSandboxOptions, SandboxApi, TaskSandboxEnvironmentOptions, TaskSandboxScope, createTaskSandboxEnvironment, ensureTaskSandbox, findTaskSandbox, stopTaskSandbox, taskSandboxName, taskSandboxTags };
+//# sourceMappingURL=task-environment.d.mts.map