@vercel/factory 0.0.13 → 0.0.15

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":"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"}

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,9 @@
+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

package/dist/sandbox/task-environment.mjs

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { Sandbox } from "@vercel/sandbox";
+//#region src/sandbox/task-environment.ts
+const livenessByStatus = {
+	pending: "transitioning",
+	running: "live",
+	stopping: "terminal",
+	stopped: "terminal",
+	failed: "terminal",
+	aborted: "terminal",
+	snapshotting: "terminal"
+};
+function observe(sandbox) {
+	const liveness = livenessByStatus[sandbox.status];
+	if (liveness === void 0) throw new Error("Unsupported sandbox liveness state");
+	return {
+		sandbox,
+		liveness
+	};
+}
+const discoveryTagKey = "factoryTask";
+const defaultSeededMarker = "/workspace/.factory-seeded";
+const defaultBridgePorts = [4e3];
+/** Derive a deterministic provider sandbox name from a scoped Task-attempt identity. */
+function taskSandboxName(key, scope) {
+	return `factory-task-${createHash("sha256").update(`${scope}:${key.taskId}:${key.attempt}`).digest("hex").slice(0, 16)}`;
+}
+/** Build the complete tag set used to discover and re-verify a Task sandbox. */
+function taskSandboxTags(key, scope) {
+	return {
+		[discoveryTagKey]: taskSandboxName(key, scope),
+		factoryScope: createHash("sha256").update(scope).digest("hex").slice(0, 16),
+		factoryTaskId: key.taskId,
+		factoryTaskAttempt: String(key.attempt)
+	};
+}
+function verifyTags(key, scope, name, tags) {
+	const expected = taskSandboxTags(key, scope);
+	if (name !== taskSandboxName(key, scope) || tags?.[discoveryTagKey] !== expected[discoveryTagKey] || tags?.factoryScope !== expected.factoryScope || tags?.factoryTaskId !== expected.factoryTaskId || tags?.factoryTaskAttempt !== expected.factoryTaskAttempt) throw new Error(`Sandbox ${name} does not carry the identity of Task ${key.taskId} attempt ${key.attempt}`);
+}
+async function isSeeded(sandbox, marker) {
+	return (await sandbox.runCommand({
+		cmd: "test",
+		args: ["-f", marker],
+		timeoutMs: 1e4
+	})).exitCode === 0;
+}
+async function markSeeded(sandbox, marker) {
+	await sandbox.writeFiles([{
+		path: marker,
+		content: "seeded"
+	}]);
+}
+/** Create or recover the exact sandbox for a Task attempt and ensure seeding completed. */
+async function ensureTaskSandbox(key, options) {
+	const api = options.api ?? Sandbox;
+	const name = taskSandboxName(key, options.scope);
+	const seededMarker = options.seededMarker ?? defaultSeededMarker;
+	const sandbox = await api.getOrCreate({
+		name,
+		runtime: options.runtime ?? "node24",
+		ports: [...options.ports ?? defaultBridgePorts],
+		timeout: options.timeoutMs,
+		tags: taskSandboxTags(key, options.scope),
+		async onCreate(created) {
+			await options.seed(created);
+			await markSeeded(created, seededMarker);
+		}
+	});
+	verifyTags(key, options.scope, sandbox.name, sandbox.tags);
+	if (!await isSeeded(sandbox, seededMarker)) {
+		await options.seed(sandbox);
+		await markSeeded(sandbox, seededMarker);
+	}
+	return sandbox;
+}
+/** Discover an existing Task sandbox without resuming or replacing it. */
+async function findTaskSandbox(key, options) {
+	const api = options.api ?? Sandbox;
+	const name = taskSandboxName(key, options.scope);
+	const matches = await api.list({
+		tags: { [discoveryTagKey]: name },
+		limit: 2
+	});
+	if (matches.sandboxes.length === 0) return null;
+	if (matches.sandboxes.length > 1 || matches.pagination.next) throw new Error(`More than one sandbox matches Task ${key.taskId} attempt ${key.attempt}; refusing to select one`);
+	const candidate = matches.sandboxes[0];
+	verifyTags(key, options.scope, candidate.name, candidate.tags);
+	let sandbox;
+	try {
+		sandbox = await api.get({
+			name: candidate.name,
+			resume: false
+		});
+	} catch (error) {
+		if (isMissing(error)) return null;
+		throw error;
+	}
+	verifyTags(key, options.scope, sandbox.name, sandbox.tags);
+	return sandbox;
+}
+/** Stop a live Task sandbox idempotently while treating provider disappearance as success. */
+async function stopTaskSandbox(sandbox) {
+	if (observe(sandbox).liveness === "terminal") return;
+	try {
+		await sandbox.stop();
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+}
+function isMissing(error) {
+	return typeof error === "object" && error !== null && ("status" in error && error.status === 404 || "response" in error && error.response instanceof Response && error.response.status === 404);
+}
+/** Adapt scoped Vercel Sandbox creation and discovery to the execution-environment contract. */
+function createTaskSandboxEnvironment(options) {
+	return {
+		name: (key) => taskSandboxName(key, options.scope),
+		ensure: (key, { timeoutMs, request }) => ensureTaskSandbox(key, {
+			scope: options.scope,
+			timeoutMs,
+			seed: (sandbox) => options.seed(request, sandbox),
+			...options.runtime ? { runtime: options.runtime } : {},
+			...options.ports ? { ports: options.ports } : {},
+			...options.seededMarker ? { seededMarker: options.seededMarker } : {},
+			api: options.api
+		}).then(observe),
+		find: async (key) => {
+			const sandbox = await findTaskSandbox(key, {
+				scope: options.scope,
+				api: options.api
+			});
+			return sandbox ? observe(sandbox) : null;
+		},
+		stop: stopTaskSandbox
+	};
+}
+//#endregion
+export { createTaskSandboxEnvironment, ensureTaskSandbox, findTaskSandbox, stopTaskSandbox, taskSandboxName, taskSandboxTags };
+
+//# sourceMappingURL=task-environment.mjs.map

package/dist/sandbox/task-environment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-environment.mjs","names":[],"sources":["../../src/sandbox/task-environment.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { Sandbox } from \"@vercel/sandbox\";\nimport type { CodingExecutionRequest, TaskAttemptRef } from \"../schema/execution\";\nimport type { ExecutionEnvironment, EnvironmentLiveness } from \"./execution-environment\";\n\nconst livenessByStatus: Record<Sandbox[\"status\"], EnvironmentLiveness> = {\n  pending: \"transitioning\",\n  running: \"live\",\n  stopping: \"terminal\",\n  stopped: \"terminal\",\n  failed: \"terminal\",\n  aborted: \"terminal\",\n  snapshotting: \"terminal\",\n};\n\nfunction observe(sandbox: Sandbox) {\n  const liveness = livenessByStatus[sandbox.status];\n  if (liveness === undefined) throw new Error(\"Unsupported sandbox liveness state\");\n  return { sandbox, liveness };\n}\n\n/** Isolates stores that reuse Task IDs within the project's shared sandbox namespace. */\nexport interface TaskSandboxScope {\n  scope: string;\n}\n\n/** Injectable subset of the Vercel Sandbox API used for creation and exact identity discovery. */\nexport type SandboxApi = Pick<typeof Sandbox, \"getOrCreate\" | \"get\" | \"list\">;\n\nconst discoveryTagKey = \"factoryTask\";\nconst defaultSeededMarker = \"/workspace/.factory-seeded\";\n// The harness bridge listens on port 4000.\nconst defaultBridgePorts = [4000];\n\n/** Derive a deterministic provider sandbox name from a scoped Task-attempt identity. */\nexport function taskSandboxName(key: TaskAttemptRef, scope: string): string {\n  const digest = createHash(\"sha256\")\n    .update(`${scope}:${key.taskId}:${key.attempt}`)\n    .digest(\"hex\")\n    .slice(0, 16);\n  return `factory-task-${digest}`;\n}\n\n/** Build the complete tag set used to discover and re-verify a Task sandbox. */\nexport function taskSandboxTags(key: TaskAttemptRef, scope: string): Record<string, string> {\n  return {\n    [discoveryTagKey]: taskSandboxName(key, scope),\n    factoryScope: createHash(\"sha256\").update(scope).digest(\"hex\").slice(0, 16),\n    factoryTaskId: key.taskId,\n    factoryTaskAttempt: String(key.attempt),\n  };\n}\n\nfunction verifyTags(\n  key: TaskAttemptRef,\n  scope: string,\n  name: string,\n  tags: Record<string, string> | undefined,\n) {\n  const expected = taskSandboxTags(key, scope);\n  if (\n    name !== taskSandboxName(key, scope) ||\n    tags?.[discoveryTagKey] !== expected[discoveryTagKey] ||\n    tags?.factoryScope !== expected.factoryScope ||\n    tags?.factoryTaskId !== expected.factoryTaskId ||\n    tags?.factoryTaskAttempt !== expected.factoryTaskAttempt\n  ) {\n    throw new Error(\n      `Sandbox ${name} does not carry the identity of Task ${key.taskId} attempt ${key.attempt}`,\n    );\n  }\n}\n\nasync function isSeeded(sandbox: Sandbox, marker: string): Promise<boolean> {\n  const command = await sandbox.runCommand({\n    cmd: \"test\",\n    args: [\"-f\", marker],\n    timeoutMs: 10_000,\n  });\n  return command.exitCode === 0;\n}\n\nasync function markSeeded(sandbox: Sandbox, marker: string): Promise<void> {\n  await sandbox.writeFiles([{ path: marker, content: \"seeded\" }]);\n}\n\n/** Configures idempotent creation and workspace seeding for a Task sandbox. */\nexport interface EnsureTaskSandboxOptions extends TaskSandboxScope {\n  /** Sandbox lifetime; callers add margin over the execution timeout. */\n  timeoutMs: number;\n  /** Seeds the workspace; must be idempotent because a crashed seed reruns. */\n  seed(sandbox: Sandbox): Promise<void>;\n  runtime?: string;\n  ports?: readonly number[];\n  seededMarker?: string;\n  api?: SandboxApi;\n}\n\n/** Create or recover the exact sandbox for a Task attempt and ensure seeding completed. */\nexport async function ensureTaskSandbox(\n  key: TaskAttemptRef,\n  options: EnsureTaskSandboxOptions,\n): Promise<Sandbox> {\n  const api = options.api ?? Sandbox;\n  const name = taskSandboxName(key, options.scope);\n  const seededMarker = options.seededMarker ?? defaultSeededMarker;\n  const sandbox = await api.getOrCreate({\n    name,\n    runtime: options.runtime ?? \"node24\",\n    ports: [...(options.ports ?? defaultBridgePorts)],\n    timeout: options.timeoutMs,\n    tags: taskSandboxTags(key, options.scope),\n    async onCreate(created) {\n      await options.seed(created);\n      await markSeeded(created, seededMarker);\n    },\n  });\n  verifyTags(key, options.scope, sandbox.name, sandbox.tags);\n  // onCreate can crash between creation and the marker; finish seeding here.\n  if (!(await isSeeded(sandbox, seededMarker))) {\n    await options.seed(sandbox);\n    await markSeeded(sandbox, seededMarker);\n  }\n  return sandbox;\n}\n\n/** Scope and provider API used to discover an existing Task sandbox. */\nexport interface FindTaskSandboxOptions extends TaskSandboxScope {\n  api?: SandboxApi;\n}\n\n/** Discover an existing Task sandbox without resuming or replacing it. */\nexport async function findTaskSandbox(\n  key: TaskAttemptRef,\n  options: FindTaskSandboxOptions,\n): Promise<Sandbox | null> {\n  const api = options.api ?? Sandbox;\n  const name = taskSandboxName(key, options.scope);\n  // The Sandbox API accepts only one tag filter; all tags are re-verified below.\n  const matches = await api.list({ tags: { [discoveryTagKey]: name }, limit: 2 });\n  if (matches.sandboxes.length === 0) return null;\n  if (matches.sandboxes.length > 1 || matches.pagination.next) {\n    throw new Error(\n      `More than one sandbox matches Task ${key.taskId} attempt ${key.attempt}; refusing to select one`,\n    );\n  }\n  const candidate = matches.sandboxes[0]!;\n  verifyTags(key, options.scope, candidate.name, candidate.tags);\n  let sandbox: Sandbox;\n  try {\n    sandbox = await api.get({ name: candidate.name, resume: false });\n  } catch (error) {\n    if (isMissing(error)) return null;\n    throw error;\n  }\n  verifyTags(key, options.scope, sandbox.name, sandbox.tags);\n  return sandbox;\n}\n\n/** Stop a live Task sandbox idempotently while treating provider disappearance as success. */\nexport async function stopTaskSandbox(sandbox: Sandbox): Promise<void> {\n  if (observe(sandbox).liveness === \"terminal\") return;\n  try {\n    await sandbox.stop();\n  } catch (error) {\n    if (!isMissing(error)) throw error;\n  }\n}\n\nfunction isMissing(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    ((\"status\" in error && error.status === 404) ||\n      (\"response\" in error && error.response instanceof Response && error.response.status === 404))\n  );\n}\n\n/** Scoped creation, seeding, and provider dependencies for a Task sandbox environment. */\nexport interface TaskSandboxEnvironmentOptions {\n  /** Deployment- or run-unique namespace; see {@link TaskSandboxScope}. */\n  scope: string;\n  seed(request: CodingExecutionRequest, sandbox: Sandbox): Promise<void>;\n  runtime?: EnsureTaskSandboxOptions[\"runtime\"];\n  ports?: readonly number[];\n  seededMarker?: string;\n  api?: SandboxApi;\n}\n\n/** Adapt scoped Vercel Sandbox creation and discovery to the execution-environment contract. */\nexport function createTaskSandboxEnvironment(\n  options: TaskSandboxEnvironmentOptions,\n): ExecutionEnvironment<Sandbox> {\n  return {\n    name: (key) => taskSandboxName(key, options.scope),\n    ensure: (key, { timeoutMs, request }) =>\n      ensureTaskSandbox(key, {\n        scope: options.scope,\n        timeoutMs,\n        seed: (sandbox) => options.seed(request, sandbox),\n        ...(options.runtime ? { runtime: options.runtime } : {}),\n        ...(options.ports ? { ports: options.ports } : {}),\n        ...(options.seededMarker ? { seededMarker: options.seededMarker } : {}),\n        api: options.api,\n      }).then(observe),\n    find: async (key) => {\n      const sandbox = await findTaskSandbox(key, { scope: options.scope, api: options.api });\n      return sandbox ? observe(sandbox) : null;\n    },\n    stop: stopTaskSandbox,\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/workspace.d.mts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+//#region src/sandbox/workspace.d.ts
+declare const outputPathSchema: z.core.$ZodBranded<z.ZodString, "SandboxOutputPath", "out">;
+/** An absolute, normalized artifact path confined to the configured sandbox output directory. */
+type SandboxOutputPath = z.infer<typeof outputPathSchema>;
+/** Current working directory reported by a sandbox session. */
+interface SandboxSession {
+  cwd: string;
+}
+/** Minimal sandbox session boundary needed to derive workspace paths. */
+interface SandboxWorkspaceHandle {
+  currentSession(): SandboxSession;
+}
+/** Standard repository, output, and artifact paths inside a harness workspace. */
+interface HarnessWorkspace {
+  root: string;
+  repo: string;
+  out: string;
+  artifacts: string;
+}
+/** File existence, symlinks, and read limits are checked by the sandbox reader. */
+declare function parseSandboxOutputPath(value: unknown, outputDirectory: string): SandboxOutputPath;
+/** Default harness SDK working directory beneath the sandbox session root. */
+declare const defaultHarnessWorkDir = "workspace";
+/** Resolve the standard repository, output, and artifact paths for a harness workspace. */
+declare function harnessWorkspace(sandbox: SandboxWorkspaceHandle): HarnessWorkspace;
+//#endregion
+export { HarnessWorkspace, SandboxOutputPath, SandboxSession, SandboxWorkspaceHandle, defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath };
+//# sourceMappingURL=workspace.d.mts.map

package/dist/sandbox/workspace.mjs

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { posix } from "node:path";
+//#region src/sandbox/workspace.ts
+const outputPathSchema = z.string().refine((value) => posix.isAbsolute(value) && posix.normalize(value) === value && !value.includes("\0"), "Artifact paths must stay inside the captured workspace output").brand();
+/** File existence, symlinks, and read limits are checked by the sandbox reader. */
+function parseSandboxOutputPath(value, outputDirectory) {
+	const path = outputPathSchema.parse(value);
+	if (!path.startsWith(`${outputDirectory}/`)) throw new Error("Artifact paths must stay inside the captured workspace output");
+	return path;
+}
+/** Default harness SDK working directory beneath the sandbox session root. */
+const defaultHarnessWorkDir = "workspace";
+/** Resolve the standard repository, output, and artifact paths for a harness workspace. */
+function harnessWorkspace(sandbox) {
+	const cwd = sandbox.currentSession().cwd;
+	if (!posix.isAbsolute(cwd)) throw new Error("The sandbox working directory must be absolute");
+	const root = posix.join(cwd, defaultHarnessWorkDir);
+	return {
+		root,
+		repo: posix.join(root, "repo"),
+		out: posix.join(root, "out"),
+		artifacts: posix.join(root, "artifacts")
+	};
+}
+//#endregion
+export { defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath };
+
+//# sourceMappingURL=workspace.mjs.map

package/dist/sandbox/workspace.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.mjs","names":[],"sources":["../../src/sandbox/workspace.ts"],"sourcesContent":["import { posix } from \"node:path\";\nimport { z } from \"zod\";\n\nconst outputPathSchema = z\n  .string()\n  .refine(\n    (value) => posix.isAbsolute(value) && posix.normalize(value) === value && !value.includes(\"\\0\"),\n    \"Artifact paths must stay inside the captured workspace output\",\n  )\n  .brand<\"SandboxOutputPath\">();\n\n/** An absolute, normalized artifact path confined to the configured sandbox output directory. */\nexport type SandboxOutputPath = z.infer<typeof outputPathSchema>;\n\n/** Current working directory reported by a sandbox session. */\nexport interface SandboxSession {\n  cwd: string;\n}\n\n/** Minimal sandbox session boundary needed to derive workspace paths. */\nexport interface SandboxWorkspaceHandle {\n  currentSession(): SandboxSession;\n}\n\n/** Standard repository, output, and artifact paths inside a harness workspace. */\nexport interface HarnessWorkspace {\n  root: string;\n  repo: string;\n  out: string;\n  artifacts: string;\n}\n\n/** File existence, symlinks, and read limits are checked by the sandbox reader. */\nexport function parseSandboxOutputPath(value: unknown, outputDirectory: string): SandboxOutputPath {\n  const path = outputPathSchema.parse(value);\n  if (!path.startsWith(`${outputDirectory}/`))\n    throw new Error(\"Artifact paths must stay inside the captured workspace output\");\n  return path;\n}\n\n/** Default harness SDK working directory beneath the sandbox session root. */\nexport const defaultHarnessWorkDir = \"workspace\";\n\n/** Resolve the standard repository, output, and artifact paths for a harness workspace. */\nexport function harnessWorkspace(sandbox: SandboxWorkspaceHandle): HarnessWorkspace {\n  const cwd = sandbox.currentSession().cwd;\n  if (!posix.isAbsolute(cwd)) throw new Error(\"The sandbox working directory must be absolute\");\n  const root = posix.join(cwd, defaultHarnessWorkDir);\n  return {\n    root,\n    repo: posix.join(root, \"repo\"),\n    out: posix.join(root, \"out\"),\n    artifacts: posix.join(root, \"artifacts\"),\n  };\n}\n"],"mappings":";;;AAGA,MAAM,mBAAmB,EACtB,OAAO,CAAC,CACR,QACE,UAAU,MAAM,WAAW,KAAK,KAAK,MAAM,UAAU,KAAK,MAAM,SAAS,CAAC,MAAM,SAAS,IAAI,GAC9F,+DACF,CAAC,CACA,MAA2B;;AAwB9B,SAAgB,uBAAuB,OAAgB,iBAA4C;CACjG,MAAM,OAAO,iBAAiB,MAAM,KAAK;CACzC,IAAI,CAAC,KAAK,WAAW,GAAG,gBAAgB,EAAE,GACxC,MAAM,IAAI,MAAM,+DAA+D;CACjF,OAAO;AACT;;AAGA,MAAa,wBAAwB;;AAGrC,SAAgB,iBAAiB,SAAmD;CAClF,MAAM,MAAM,QAAQ,eAAe,CAAC,CAAC;CACrC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,gDAAgD;CAC5F,MAAM,OAAO,MAAM,KAAK,KAAK,qBAAqB;CAClD,OAAO;EACL;EACA,MAAM,MAAM,KAAK,MAAM,MAAM;EAC7B,KAAK,MAAM,KAAK,MAAM,KAAK;EAC3B,WAAW,MAAM,KAAK,MAAM,WAAW;CACzC;AACF"}