@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/attach-preflight.d.ts

@@ -0,0 +1,85 @@
+import { JournalPaths } from './journal.js';
+import { SandboxHandle } from './contracts.js';
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { RunStore } from '@tanstack/ai';
+/**
+ * How long an attach waits for a live run's journal to appear before failing.
+ *
+ * User-relevant, hence exported: this bounds how long an attach REQUEST can sit
+ * before it answers, so an application that fronts the attach route with its own
+ * timeout needs to know the number. Generous relative to the gap between a
+ * driver claiming a run and its first journal write (a `spawn` plus one line),
+ * and short relative to any sane HTTP timeout. Override per run with
+ * `SandboxDurabilityOptions.attachWaitMs`.
+ */
+export declare const DEFAULT_ATTACH_JOURNAL_WAIT_MS = 10000;
+/**
+ * How often the bounded wait re-probes for the journal. Not user-facing: it
+ * trades a `test -f` per interval for attach latency, and neither number is
+ * something an application tunes.
+ */
+export declare const DEFAULT_ATTACH_PROBE_INTERVAL_MS = 100;
+/**
+ * Which of the three hopeless-attach cases was hit. Exported so a consumer can
+ * branch (a 404 for `'unknown-run'`, a 410 for `'terminal-run'`, a 504 for
+ * `'journal-timeout'`) instead of matching on message text.
+ */
+export type AttachUnavailableReason = 'unknown-run' | 'terminal-run' | 'journal-timeout'
+/**
+ * The journal EXISTS but produced no bytes at all within the deadline, so no
+ * sentinel can be coming and the follow would tail an empty (or abandoned)
+ * file forever. Raised by `journal-reader.ts`, not by the preflight: the
+ * preflight cannot see this state, because `test -f` succeeds for it.
+ *
+ * A 504 at an attach route, exactly like `'journal-timeout'`, which is why it
+ * shares {@link JournalAttachUnavailableError} — but a distinct value, because
+ * the cause is different: `'journal-timeout'` means nobody created the
+ * journal, `'journal-stalled'` means somebody did and then stopped (a
+ * SIGKILLed agent shell, a destroyed sandbox, a reader that created the file
+ * itself on a fail-open path).
+ */
+ | 'journal-stalled';
+/**
+ * An attach cannot succeed, and waiting longer would not change that.
+ *
+ * One class with a {@link AttachUnavailableReason} discriminant rather than three
+ * classes: every consumer of this path handles all three cases at the same seam
+ * (the attach route), so one `instanceof` plus a `switch (error.reason)` is the
+ * shape that is actually written, while the message names the specific case for a
+ * human reading a log.
+ */
+export declare class JournalAttachUnavailableError extends Error {
+    readonly runId: string;
+    readonly reason: AttachUnavailableReason;
+    constructor(runId: string, reason: AttachUnavailableReason, detail: string);
+}
+export interface AwaitAttachableJournalOptions {
+    /** The run's journal paths, as {@link journalPaths} derived them. */
+    paths: JournalPaths;
+    /** Run id, for the store lookup and the error messages. */
+    runId: string;
+    /**
+     * The authoritative run record store. Omitted only by a caller with no store
+     * wired, which loses the unknown/terminal classification but keeps the bound.
+     */
+    runs?: RunStore;
+    /** Bounded wait. Defaults to {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS}. */
+    waitMs?: number;
+    /** Re-probe interval. Defaults to {@link DEFAULT_ATTACH_PROBE_INTERVAL_MS}. */
+    probeIntervalMs?: number;
+    /**
+     * The consumer's abort. An aborted wait returns rather than throwing: the
+     * caller stopped caring, which is not a diagnosis about the run.
+     */
+    signal?: AbortSignal;
+    logger?: InternalLogger;
+}
+/**
+ * Resolve once the run's journal can be tailed, or reject with a
+ * {@link JournalAttachUnavailableError} explaining why it never will be.
+ *
+ * Call this BEFORE the first follow/poll read of an attach, never on a fresh
+ * run: a fresh run's journal is created by its own `journaledCommand` spawn,
+ * which has not happened yet, so gating it would fail every new run.
+ */
+export declare function awaitAttachableJournal(handle: SandboxHandle, options: AwaitAttachableJournalOptions): Promise<void>;

package/dist/esm/attach-preflight.js

@@ -0,0 +1,189 @@
+import { journalExistsCommand } from "./journal.js";
+import { isTerminalRunStatus } from "@tanstack/ai";
+//#region src/attach-preflight.ts
+/**
+* The gate that turns a HOPELESS attach into an error instead of an infinite
+* wait.
+*
+* `journalFollowCommand` creates the journal before tailing it (`: >> file`),
+* because `tail -f` on a missing path prints a diagnostic and EXITS rather than
+* waiting — a defect that made a legitimate attach racing the driver's first
+* write deliver zero lines. But creating the file has a cost: an attach for a
+* `runId` that never had a journal creates an EMPTY one and tails it forever. No
+* `{"__exit":N}` sentinel can ever arrive, so the caller waits indefinitely with
+* no error, no timeout, and no log line — for what is the single most likely
+* mistake on this path (a stale link, a typo, a run whose journal was cleaned up
+* after completing).
+*
+* Absence of the journal alone cannot decide the question, which is exactly why
+* `: >> file` exists: "not written YET" and "will never be written" look
+* identical on the filesystem. The RUN RECORD is what distinguishes them, and it
+* is authoritative — `runs.get(runId)` says whether the run exists at all,
+* whether it is terminal, and (via `detachedSince`) whether anyone is expected
+* to be driving it. So the policy is:
+*
+* | journal   | record                  | decision                              |
+* | --------- | ----------------------- | ------------------------------------- |
+* | exists    | (not consulted)         | attach, under the reader's own bound  |
+* | absent    | unknown (`null`)        | fail fast, `'unknown-run'`            |
+* | absent    | terminal                | fail fast, `'terminal-run'`           |
+* | absent    | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|
+* | unusable  | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|
+*
+* Four deliberate choices in that table:
+*
+* 1. **An existing journal short-circuits this gate**, before the store is read
+*    at all — because gating it would make a perfectly readable journal
+*    unreadable whenever a store lost its record. It does NOT mean the read is
+*    unbounded: this module used to justify the short-circuit with "a journal
+*    that exists either carries a sentinel or is still being appended to, neither
+*    hangs", and that trichotomy was FALSE. `journalFollowCommand`'s first act is
+*    `: >> file`, so the reader itself manufactures the third state — a file that
+*    exists, receives nothing, and can never receive a sentinel — and the same
+*    state is independently reachable by SIGKILL/OOM of the agent's shell before
+*    its `printf`. The bound for it lives where it belongs, on the read:
+*    `journal-reader.ts` fails a follow/poll that receives no bytes at all within
+*    {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} with `'journal-stalled'`.
+* 2. **A terminal record with no journal fails rather than waiting.** Nothing
+*    will ever be appended: the run is over and `journalCleanupCommand` deletes a
+*    terminal run's files by design. Its transcript lives in the event log, which
+*    the resume response serves independently of this path.
+* 3. **A live or detached record waits, but not forever.** A driver that has
+*    claimed the run and not yet written its first line is the normal case, not
+*    the unlucky one, so failing fast here would break the very race
+*    `journalFollowCommand` was fixed to tolerate. `detachedSince` does NOT
+*    change the decision — a detached run's journal is exactly what a successor
+*    is supposed to read, and a driver that died before its first write leaves an
+*    identical filesystem state — but it IS reported in the timeout message,
+*    since "detached with no journal after N ms" and "attached with no journal
+*    after N ms" point at different causes.
+* 4. **An UNUSABLE probe falls through to the bounded wait; it does not skip the
+*    gate.** This module used to fail open here — `if (existence === 'unknown')
+*    return` — on the reasoning that a diagnostic gate must not break an attach
+*    that would otherwise have worked. That reasoning inverted the actual risk.
+*    Returning handed control to a reader whose very first act CREATES the
+*    journal (`journalFollowCommand`'s `: >> file`) and then tails it forever, so
+*    the fail-open path did not preserve a working attach — it manufactured the
+*    exact infinite wait this module exists to prevent. Worse, it was
+*    self-perpetuating: the file it created made `test -f` succeed from then on,
+*    so every LATER attach short-circuited at choice 1 and hung too, permanently,
+*    long after the transient probe failure had cleared. An unanswerable probe is
+*    precisely when a deadline matters most, so an unusable probe is re-polled
+*    (it may recover) and, failing that, times out. The store checks still run
+*    first and need no probe, so an unknown or terminal `runId` still fails fast.
+*/
+/**
+* How long an attach waits for a live run's journal to appear before failing.
+*
+* User-relevant, hence exported: this bounds how long an attach REQUEST can sit
+* before it answers, so an application that fronts the attach route with its own
+* timeout needs to know the number. Generous relative to the gap between a
+* driver claiming a run and its first journal write (a `spawn` plus one line),
+* and short relative to any sane HTTP timeout. Override per run with
+* `SandboxDurabilityOptions.attachWaitMs`.
+*/
+var DEFAULT_ATTACH_JOURNAL_WAIT_MS = 1e4;
+/**
+* How often the bounded wait re-probes for the journal. Not user-facing: it
+* trades a `test -f` per interval for attach latency, and neither number is
+* something an application tunes.
+*/
+var DEFAULT_ATTACH_PROBE_INTERVAL_MS = 100;
+/**
+* An attach cannot succeed, and waiting longer would not change that.
+*
+* One class with a {@link AttachUnavailableReason} discriminant rather than three
+* classes: every consumer of this path handles all three cases at the same seam
+* (the attach route), so one `instanceof` plus a `switch (error.reason)` is the
+* shape that is actually written, while the message names the specific case for a
+* human reading a log.
+*/
+var JournalAttachUnavailableError = class extends Error {
+	runId;
+	reason;
+	constructor(runId, reason, detail) {
+		super(`cannot attach to run ${runId}: ${detail}`);
+		this.runId = runId;
+		this.reason = reason;
+		this.name = "JournalAttachUnavailableError";
+	}
+};
+/**
+* Shell `test -f`, never `handle.fs.exists` — `journal.ts` rule 3: on
+* local-process the two resolve `/tmp` differently, so `fs.exists` would probe a
+* path the journal was never written to and report `false` for every run.
+*/
+async function probeJournal(handle, options) {
+	try {
+		return (await handle.process.exec(journalExistsCommand(options.paths))).exitCode === 0 ? "yes" : "no";
+	} catch (error) {
+		options.logger?.provider(`attach preflight: journal existence probe failed for run ${options.runId}; re-probing under the bounded wait rather than attaching blind`, {
+			runId: options.runId,
+			error
+		});
+		return "unknown";
+	}
+}
+/**
+* `null` means the store answered "no such run" — a real, actionable fact.
+* `undefined` means there is no answer to be had (no store, or `get` threw), and
+* the caller must not treat that as "unknown run".
+*/
+async function readRecord(options) {
+	if (options.runs === void 0) return void 0;
+	try {
+		return await options.runs.get(options.runId);
+	} catch (error) {
+		options.logger?.errors(`attach preflight: reading the run record failed for run ${options.runId}`, {
+			runId: options.runId,
+			error
+		});
+		return;
+	}
+}
+function sleep(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => {
+		const timer = setTimeout(finish, ms);
+		function finish() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		}
+		signal?.addEventListener("abort", finish, { once: true });
+	});
+}
+function describeRecord(record) {
+	return record.detachedSince === void 0 ? `status '${record.status}' with a viewer attached` : `status '${record.status}', detached since ${new Date(record.detachedSince).toISOString()}`;
+}
+/**
+* Resolve once the run's journal can be tailed, or reject with a
+* {@link JournalAttachUnavailableError} explaining why it never will be.
+*
+* Call this BEFORE the first follow/poll read of an attach, never on a fresh
+* run: a fresh run's journal is created by its own `journaledCommand` spawn,
+* which has not happened yet, so gating it would fail every new run.
+*/
+async function awaitAttachableJournal(handle, options) {
+	const existence = await probeJournal(handle, options);
+	if (existence === "yes") return;
+	const record = await readRecord(options);
+	if (record === null) throw new JournalAttachUnavailableError(options.runId, "unknown-run", `no run record exists and the journal (${options.paths.journal}) has never been written, so nothing will ever be appended to it. The runId is unknown to the RunStore — it is mistyped, from another deployment, or its record has been evicted.`);
+	if (record !== void 0 && isTerminalRunStatus(record.status)) throw new JournalAttachUnavailableError(options.runId, "terminal-run", `the run is already '${record.status}' and its journal (${options.paths.journal}) does not exist, so nothing will ever be appended to it. A terminal run's transcript lives in its event log, not in a journal — serve the log instead of attaching.`);
+	const waitMs = options.waitMs ?? 1e4;
+	const probeIntervalMs = options.probeIntervalMs ?? 100;
+	const deadline = Date.now() + waitMs;
+	let lastExistence = existence;
+	for (;;) {
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) throw new JournalAttachUnavailableError(options.runId, "journal-timeout", `the run record says ${record === void 0 ? "nothing (no run store is wired)" : describeRecord(record)}, ` + (lastExistence === "unknown" ? `and its journal (${options.paths.journal}) could not be probed at all within ${waitMs}ms — every '${journalExistsCommand(options.paths)}' failed. Attaching anyway would create that journal and tail it forever, so this fails instead. Check that the sandbox is still alive and that its exec transport works.` : `but its journal (${options.paths.journal}) did not appear within ${waitMs}ms. Either the driver died before writing its first line, or the journal directory does not match the one the agent was started with.`));
+		if (options.signal?.aborted) return;
+		await sleep(Math.min(probeIntervalMs, remaining), options.signal);
+		lastExistence = await probeJournal(handle, options);
+		if (lastExistence === "yes") return;
+	}
+}
+//#endregion
+export { DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, JournalAttachUnavailableError, awaitAttachableJournal };
+
+//# sourceMappingURL=attach-preflight.js.map

package/dist/esm/attach-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-preflight.js","names":[],"sources":["../../src/attach-preflight.ts"],"sourcesContent":["/**\n * The gate that turns a HOPELESS attach into an error instead of an infinite\n * wait.\n *\n * `journalFollowCommand` creates the journal before tailing it (`: >> file`),\n * because `tail -f` on a missing path prints a diagnostic and EXITS rather than\n * waiting — a defect that made a legitimate attach racing the driver's first\n * write deliver zero lines. But creating the file has a cost: an attach for a\n * `runId` that never had a journal creates an EMPTY one and tails it forever. No\n * `{\"__exit\":N}` sentinel can ever arrive, so the caller waits indefinitely with\n * no error, no timeout, and no log line — for what is the single most likely\n * mistake on this path (a stale link, a typo, a run whose journal was cleaned up\n * after completing).\n *\n * Absence of the journal alone cannot decide the question, which is exactly why\n * `: >> file` exists: \"not written YET\" and \"will never be written\" look\n * identical on the filesystem. The RUN RECORD is what distinguishes them, and it\n * is authoritative — `runs.get(runId)` says whether the run exists at all,\n * whether it is terminal, and (via `detachedSince`) whether anyone is expected\n * to be driving it. So the policy is:\n *\n * | journal   | record                  | decision                              |\n * | --------- | ----------------------- | ------------------------------------- |\n * | exists    | (not consulted)         | attach, under the reader's own bound  |\n * | absent    | unknown (`null`)        | fail fast, `'unknown-run'`            |\n * | absent    | terminal                | fail fast, `'terminal-run'`           |\n * | absent    | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|\n * | unusable  | running / interrupted   | BOUNDED wait, then `'journal-timeout'`|\n *\n * Four deliberate choices in that table:\n *\n * 1. **An existing journal short-circuits this gate**, before the store is read\n *    at all — because gating it would make a perfectly readable journal\n *    unreadable whenever a store lost its record. It does NOT mean the read is\n *    unbounded: this module used to justify the short-circuit with \"a journal\n *    that exists either carries a sentinel or is still being appended to, neither\n *    hangs\", and that trichotomy was FALSE. `journalFollowCommand`'s first act is\n *    `: >> file`, so the reader itself manufactures the third state — a file that\n *    exists, receives nothing, and can never receive a sentinel — and the same\n *    state is independently reachable by SIGKILL/OOM of the agent's shell before\n *    its `printf`. The bound for it lives where it belongs, on the read:\n *    `journal-reader.ts` fails a follow/poll that receives no bytes at all within\n *    {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS} with `'journal-stalled'`.\n * 2. **A terminal record with no journal fails rather than waiting.** Nothing\n *    will ever be appended: the run is over and `journalCleanupCommand` deletes a\n *    terminal run's files by design. Its transcript lives in the event log, which\n *    the resume response serves independently of this path.\n * 3. **A live or detached record waits, but not forever.** A driver that has\n *    claimed the run and not yet written its first line is the normal case, not\n *    the unlucky one, so failing fast here would break the very race\n *    `journalFollowCommand` was fixed to tolerate. `detachedSince` does NOT\n *    change the decision — a detached run's journal is exactly what a successor\n *    is supposed to read, and a driver that died before its first write leaves an\n *    identical filesystem state — but it IS reported in the timeout message,\n *    since \"detached with no journal after N ms\" and \"attached with no journal\n *    after N ms\" point at different causes.\n * 4. **An UNUSABLE probe falls through to the bounded wait; it does not skip the\n *    gate.** This module used to fail open here — `if (existence === 'unknown')\n *    return` — on the reasoning that a diagnostic gate must not break an attach\n *    that would otherwise have worked. That reasoning inverted the actual risk.\n *    Returning handed control to a reader whose very first act CREATES the\n *    journal (`journalFollowCommand`'s `: >> file`) and then tails it forever, so\n *    the fail-open path did not preserve a working attach — it manufactured the\n *    exact infinite wait this module exists to prevent. Worse, it was\n *    self-perpetuating: the file it created made `test -f` succeed from then on,\n *    so every LATER attach short-circuited at choice 1 and hung too, permanently,\n *    long after the transient probe failure had cleared. An unanswerable probe is\n *    precisely when a deadline matters most, so an unusable probe is re-polled\n *    (it may recover) and, failing that, times out. The store checks still run\n *    first and need no probe, so an unknown or terminal `runId` still fails fast.\n */\nimport { isTerminalRunStatus } from '@tanstack/ai'\nimport { journalExistsCommand } from './journal'\nimport type { JournalPaths } from './journal'\nimport type { SandboxHandle } from './contracts'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { RunRecord, RunStore } from '@tanstack/ai'\n\n/**\n * How long an attach waits for a live run's journal to appear before failing.\n *\n * User-relevant, hence exported: this bounds how long an attach REQUEST can sit\n * before it answers, so an application that fronts the attach route with its own\n * timeout needs to know the number. Generous relative to the gap between a\n * driver claiming a run and its first journal write (a `spawn` plus one line),\n * and short relative to any sane HTTP timeout. Override per run with\n * `SandboxDurabilityOptions.attachWaitMs`.\n */\nexport const DEFAULT_ATTACH_JOURNAL_WAIT_MS = 10_000\n\n/**\n * How often the bounded wait re-probes for the journal. Not user-facing: it\n * trades a `test -f` per interval for attach latency, and neither number is\n * something an application tunes.\n */\nexport const DEFAULT_ATTACH_PROBE_INTERVAL_MS = 100\n\n/**\n * Which of the three hopeless-attach cases was hit. Exported so a consumer can\n * branch (a 404 for `'unknown-run'`, a 410 for `'terminal-run'`, a 504 for\n * `'journal-timeout'`) instead of matching on message text.\n */\nexport type AttachUnavailableReason =\n  | 'unknown-run'\n  | 'terminal-run'\n  | 'journal-timeout'\n  /**\n   * The journal EXISTS but produced no bytes at all within the deadline, so no\n   * sentinel can be coming and the follow would tail an empty (or abandoned)\n   * file forever. Raised by `journal-reader.ts`, not by the preflight: the\n   * preflight cannot see this state, because `test -f` succeeds for it.\n   *\n   * A 504 at an attach route, exactly like `'journal-timeout'`, which is why it\n   * shares {@link JournalAttachUnavailableError} — but a distinct value, because\n   * the cause is different: `'journal-timeout'` means nobody created the\n   * journal, `'journal-stalled'` means somebody did and then stopped (a\n   * SIGKILLed agent shell, a destroyed sandbox, a reader that created the file\n   * itself on a fail-open path).\n   */\n  | 'journal-stalled'\n\n/**\n * An attach cannot succeed, and waiting longer would not change that.\n *\n * One class with a {@link AttachUnavailableReason} discriminant rather than three\n * classes: every consumer of this path handles all three cases at the same seam\n * (the attach route), so one `instanceof` plus a `switch (error.reason)` is the\n * shape that is actually written, while the message names the specific case for a\n * human reading a log.\n */\nexport class JournalAttachUnavailableError extends Error {\n  constructor(\n    readonly runId: string,\n    readonly reason: AttachUnavailableReason,\n    detail: string,\n  ) {\n    super(`cannot attach to run ${runId}: ${detail}`)\n    this.name = 'JournalAttachUnavailableError'\n  }\n}\n\n/** Existence of the journal, or `'unknown'` when the probe itself failed. */\ntype JournalExistence = 'yes' | 'no' | 'unknown'\n\nexport interface AwaitAttachableJournalOptions {\n  /** The run's journal paths, as {@link journalPaths} derived them. */\n  paths: JournalPaths\n  /** Run id, for the store lookup and the error messages. */\n  runId: string\n  /**\n   * The authoritative run record store. Omitted only by a caller with no store\n   * wired, which loses the unknown/terminal classification but keeps the bound.\n   */\n  runs?: RunStore\n  /** Bounded wait. Defaults to {@link DEFAULT_ATTACH_JOURNAL_WAIT_MS}. */\n  waitMs?: number\n  /** Re-probe interval. Defaults to {@link DEFAULT_ATTACH_PROBE_INTERVAL_MS}. */\n  probeIntervalMs?: number\n  /**\n   * The consumer's abort. An aborted wait returns rather than throwing: the\n   * caller stopped caring, which is not a diagnosis about the run.\n   */\n  signal?: AbortSignal\n  logger?: InternalLogger\n}\n\n/**\n * Shell `test -f`, never `handle.fs.exists` — `journal.ts` rule 3: on\n * local-process the two resolve `/tmp` differently, so `fs.exists` would probe a\n * path the journal was never written to and report `false` for every run.\n */\nasync function probeJournal(\n  handle: SandboxHandle,\n  options: AwaitAttachableJournalOptions,\n): Promise<JournalExistence> {\n  try {\n    const result = await handle.process.exec(\n      journalExistsCommand(options.paths),\n    )\n    return result.exitCode === 0 ? 'yes' : 'no'\n  } catch (error) {\n    options.logger?.provider(\n      `attach preflight: journal existence probe failed for run ${options.runId}; re-probing under the bounded wait rather than attaching blind`,\n      { runId: options.runId, error },\n    )\n    return 'unknown'\n  }\n}\n\n/**\n * `null` means the store answered \"no such run\" — a real, actionable fact.\n * `undefined` means there is no answer to be had (no store, or `get` threw), and\n * the caller must not treat that as \"unknown run\".\n */\nasync function readRecord(\n  options: AwaitAttachableJournalOptions,\n): Promise<RunRecord | null | undefined> {\n  if (options.runs === undefined) return undefined\n  try {\n    return await options.runs.get(options.runId)\n  } catch (error) {\n    options.logger?.errors(\n      `attach preflight: reading the run record failed for run ${options.runId}`,\n      { runId: options.runId, error },\n    )\n    return undefined\n  }\n}\n\nfunction sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {\n  if (ms <= 0) return Promise.resolve()\n  return new Promise<void>((resolve) => {\n    const timer = setTimeout(finish, ms)\n    function finish(): void {\n      clearTimeout(timer)\n      signal?.removeEventListener('abort', finish)\n      resolve()\n    }\n    signal?.addEventListener('abort', finish, { once: true })\n  })\n}\n\nfunction describeRecord(record: RunRecord): string {\n  return record.detachedSince === undefined\n    ? `status '${record.status}' with a viewer attached`\n    : `status '${record.status}', detached since ${new Date(record.detachedSince).toISOString()}`\n}\n\n/**\n * Resolve once the run's journal can be tailed, or reject with a\n * {@link JournalAttachUnavailableError} explaining why it never will be.\n *\n * Call this BEFORE the first follow/poll read of an attach, never on a fresh\n * run: a fresh run's journal is created by its own `journaledCommand` spawn,\n * which has not happened yet, so gating it would fail every new run.\n */\nexport async function awaitAttachableJournal(\n  handle: SandboxHandle,\n  options: AwaitAttachableJournalOptions,\n): Promise<void> {\n  const existence = await probeJournal(handle, options)\n  if (existence === 'yes') return\n\n  const record = await readRecord(options)\n  if (record === null) {\n    throw new JournalAttachUnavailableError(\n      options.runId,\n      'unknown-run',\n      `no run record exists and the journal (${options.paths.journal}) has never been written, so nothing will ever be appended to it. ` +\n        `The runId is unknown to the RunStore — it is mistyped, from another deployment, or its record has been evicted.`,\n    )\n  }\n  if (record !== undefined && isTerminalRunStatus(record.status)) {\n    throw new JournalAttachUnavailableError(\n      options.runId,\n      'terminal-run',\n      `the run is already '${record.status}' and its journal (${options.paths.journal}) does not exist, so nothing will ever be appended to it. ` +\n        `A terminal run's transcript lives in its event log, not in a journal — serve the log instead of attaching.`,\n    )\n  }\n\n  // NOTE: no fail-open branch here. An `existence === 'unknown'` probe falls\n  // through into the bounded wait below — see choice 4 in the module doc for why\n  // returning was worse than timing out, not safer.\n  const waitMs = options.waitMs ?? DEFAULT_ATTACH_JOURNAL_WAIT_MS\n  const probeIntervalMs =\n    options.probeIntervalMs ?? DEFAULT_ATTACH_PROBE_INTERVAL_MS\n  const deadline = Date.now() + waitMs\n  let lastExistence: JournalExistence = existence\n  for (;;) {\n    const remaining = deadline - Date.now()\n    if (remaining <= 0) {\n      throw new JournalAttachUnavailableError(\n        options.runId,\n        'journal-timeout',\n        `the run record says ${record === undefined ? 'nothing (no run store is wired)' : describeRecord(record)}, ` +\n          (lastExistence === 'unknown'\n            ? `and its journal (${options.paths.journal}) could not be probed at all within ${waitMs}ms — every '${journalExistsCommand(options.paths)}' failed. ` +\n              `Attaching anyway would create that journal and tail it forever, so this fails instead. Check that the sandbox is still alive and that its exec transport works.`\n            : `but its journal (${options.paths.journal}) did not appear within ${waitMs}ms. ` +\n              `Either the driver died before writing its first line, or the journal directory does not match the one the agent was started with.`),\n      )\n    }\n    // The consumer gave up (client gone, lease lost). Returning hands control\n    // back to the reader, whose own AbortSignal handling ends the read — a\n    // caller's abort is not a diagnosis about the run.\n    if (options.signal?.aborted) return\n    await sleep(Math.min(probeIntervalMs, remaining), options.signal)\n    lastExistence = await probeJournal(handle, options)\n    if (lastExistence === 'yes') return\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,IAAa,iCAAiC;;;;;;AAO9C,IAAa,mCAAmC;;;;;;;;;;AAmChD,IAAa,gCAAb,cAAmD,MAAM;CAE5C;CACA;CAFX,YACE,OACA,QACA,QACA;EACA,MAAM,wBAAwB,MAAM,IAAI,QAAQ;EAJvC,KAAA,QAAA;EACA,KAAA,SAAA;EAIT,KAAK,OAAO;CACd;AACF;;;;;;AAgCA,eAAe,aACb,QACA,SAC2B;CAC3B,IAAI;EAIF,QAAO,MAHc,OAAO,QAAQ,KAClC,qBAAqB,QAAQ,KAAK,CACpC,EAAA,CACc,aAAa,IAAI,QAAQ;CACzC,SAAS,OAAO;EACd,QAAQ,QAAQ,SACd,4DAA4D,QAAQ,MAAM,kEAC1E;GAAE,OAAO,QAAQ;GAAO;EAAM,CAChC;EACA,OAAO;CACT;AACF;;;;;;AAOA,eAAe,WACb,SACuC;CACvC,IAAI,QAAQ,SAAS,KAAA,GAAW,OAAO,KAAA;CACvC,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,IAAI,QAAQ,KAAK;CAC7C,SAAS,OAAO;EACd,QAAQ,QAAQ,OACd,2DAA2D,QAAQ,SACnE;GAAE,OAAO,QAAQ;GAAO;EAAM,CAChC;EACA;CACF;AACF;AAEA,SAAS,MAAM,IAAY,QAAgD;CACzE,IAAI,MAAM,GAAG,OAAO,QAAQ,QAAQ;CACpC,OAAO,IAAI,SAAe,YAAY;EACpC,MAAM,QAAQ,WAAW,QAAQ,EAAE;EACnC,SAAS,SAAe;GACtB,aAAa,KAAK;GAClB,QAAQ,oBAAoB,SAAS,MAAM;GAC3C,QAAQ;EACV;EACA,QAAQ,iBAAiB,SAAS,QAAQ,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;AACH;AAEA,SAAS,eAAe,QAA2B;CACjD,OAAO,OAAO,kBAAkB,KAAA,IAC5B,WAAW,OAAO,OAAO,4BACzB,WAAW,OAAO,OAAO,oBAAoB,IAAI,KAAK,OAAO,aAAa,CAAC,CAAC,YAAY;AAC9F;;;;;;;;;AAUA,eAAsB,uBACpB,QACA,SACe;CACf,MAAM,YAAY,MAAM,aAAa,QAAQ,OAAO;CACpD,IAAI,cAAc,OAAO;CAEzB,MAAM,SAAS,MAAM,WAAW,OAAO;CACvC,IAAI,WAAW,MACb,MAAM,IAAI,8BACR,QAAQ,OACR,eACA,yCAAyC,QAAQ,MAAM,QAAQ,kLAEjE;CAEF,IAAI,WAAW,KAAA,KAAa,oBAAoB,OAAO,MAAM,GAC3D,MAAM,IAAI,8BACR,QAAQ,OACR,gBACA,uBAAuB,OAAO,OAAO,qBAAqB,QAAQ,MAAM,QAAQ,qKAElF;CAMF,MAAM,SAAS,QAAQ,UAAA;CACvB,MAAM,kBACJ,QAAQ,mBAAA;CACV,MAAM,WAAW,KAAK,IAAI,IAAI;CAC9B,IAAI,gBAAkC;CACtC,SAAS;EACP,MAAM,YAAY,WAAW,KAAK,IAAI;EACtC,IAAI,aAAa,GACf,MAAM,IAAI,8BACR,QAAQ,OACR,mBACA,uBAAuB,WAAW,KAAA,IAAY,oCAAoC,eAAe,MAAM,EAAE,OACtG,kBAAkB,YACf,oBAAoB,QAAQ,MAAM,QAAQ,sCAAsC,OAAO,cAAc,qBAAqB,QAAQ,KAAK,EAAE,6KAEzI,oBAAoB,QAAQ,MAAM,QAAQ,0BAA0B,OAAO,uIAEnF;EAKF,IAAI,QAAQ,QAAQ,SAAS;EAC7B,MAAM,MAAM,KAAK,IAAI,iBAAiB,SAAS,GAAG,QAAQ,MAAM;EAChE,gBAAgB,MAAM,aAAa,QAAQ,OAAO;EAClD,IAAI,kBAAkB,OAAO;CAC/B;AACF"}

package/dist/esm/bootstrap.js

@@ -1,124 +1,110 @@
+import { resolveAllSecrets, resolveSecret } from "./secrets.js";
 import { buildSetupPlan } from "./setup-plan.js";
 import { createBootstrapShell } from "./shell.js";
-import { resolveGitSkillDir, mergeAgentsContent, writeAgentsFile } from "./agents-file.js";
-import { resolveAllSecrets, resolveSecret } from "./secrets.js";
-const LOCKFILES = {
-  pnpm: "pnpm-lock.yaml",
-  yarn: "yarn.lock",
-  bun: "bun.lockb",
-  npm: "package-lock.json"
+import { mergeAgentsContent, resolveGitSkillDir, writeAgentsFile } from "./agents-file.js";
+//#region src/bootstrap.ts
+/**
+* Workspace bootstrap engine — provider-agnostic because it only uses the
+* {@link SandboxHandle} contract. Runs once when a sandbox is freshly created
+* (or restored without its working tree): land the source, inject secrets,
+* detect the package manager, and run setup commands.
+*
+* Harness-specific projection (CLAUDE.md, agent skills, MCP config) is NOT done
+* here — that's each adapter's `projectWorkspace()` hook, since the format
+* differs per harness.
+*/
+var LOCKFILES = {
+	pnpm: "pnpm-lock.yaml",
+	yarn: "yarn.lock",
+	bun: "bun.lockb",
+	npm: "package-lock.json"
 };
-const DEFAULT_WORKSPACE_ROOT = "/workspace";
+var DEFAULT_WORKSPACE_ROOT = "/workspace";
+/** Resolve the package manager, detecting from a lockfile when `'auto'`. */
 async function detectPackageManager(handle, workspace, root) {
-  const pm = workspace.packageManager ?? "auto";
-  if (pm !== "auto") return pm;
-  for (const [manager, lockfile] of Object.entries(LOCKFILES)) {
-    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager;
-  }
-  return void 0;
+	const pm = workspace.packageManager ?? "auto";
+	if (pm !== "auto") return pm;
+	for (const [manager, lockfile] of Object.entries(LOCKFILES)) if (await handle.fs.exists(`${root}/${lockfile}`)) return manager;
 }
+/**
+* Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe
+* on restore: a git clone into a populated dir is skipped by checking for the
+* target dir first.
+*/
 async function bootstrapWorkspace(handle, workspace, options = {}) {
-  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT;
-  if (workspace.secrets !== void 0) {
-    const resolved = resolveAllSecrets(workspace.secrets);
-    if (Object.keys(resolved).length > 0) {
-      await handle.env.set(resolved);
-    }
-  }
-  if (workspace.source.type === "git") {
-    const alreadyCloned = await handle.fs.exists(`${root}/.git`);
-    if (!alreadyCloned) {
-      await handle.git.clone({
-        url: workspace.source.url,
-        ref: workspace.source.ref,
-        auth: workspace.source.auth,
-        ...workspace.source.depth !== void 0 ? { depth: workspace.source.depth } : {}
-      });
-    }
-  }
-  const skills = workspace.skills ?? [];
-  for (const skill of skills) {
-    if (skill.kind === "git") {
-      const url = skill.repo.startsWith("http") ? skill.repo : `https://github.com/${skill.repo}.git`;
-      const dir = skill.into ?? resolveGitSkillDir(root, skill);
-      const auth = skill.secret !== void 0 && workspace.secrets !== void 0 ? { token: resolveSecret(workspace.secrets, skill.secret) } : void 0;
-      await handle.git.clone({
-        url,
-        dir,
-        ...auth !== void 0 ? { auth } : {},
-        depth: 1
-      });
-    }
-  }
-  let agentsContent;
-  if (workspace.instructions !== void 0 && workspace.instructions.length > 0) {
-    agentsContent = workspace.instructions;
-  } else {
-    const agentsFileSkill = skills.find(
-      (s) => s.kind === "file" && s.path === "AGENTS.md"
-    );
-    if (agentsFileSkill !== void 0) {
-      agentsContent = agentsFileSkill.content;
-    }
-  }
-  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts);
-  if (agentsContent !== void 0) {
-    await writeAgentsFile(handle, root, agentsContent);
-  }
-  for (const skill of skills) {
-    if (skill.kind === "file" && skill.path !== "AGENTS.md") {
-      await handle.fs.write(`${root}/${skill.path}`, skill.content);
-    }
-  }
-  const packageManager = await detectPackageManager(handle, workspace, root);
-  const ranSetup = [];
-  const plan = buildSetupPlan(workspace.setup);
-  if (plan.length > 0) {
-    const shell = await createBootstrapShell(handle, { cwd: root });
-    try {
-      for (const group of plan) {
-        if (group.kind === "serial") {
-          const result = await shell.run(group.command);
-          if (result.exitCode !== 0) {
-            const tail = result.stdout.trim().slice(-1500);
-            throw new Error(
-              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `
-${tail}` : ""}`
-            );
-          }
-          ranSetup.push(group.command);
-        } else {
-          const { cwd, env } = await shell.forkState();
-          const results = await Promise.all(
-            group.commands.map(
-              (command) => handle.process.exec(command, {
-                cwd,
-                env,
-                ...options.signal ? { signal: options.signal } : {}
-              }).then((res) => ({ command, res }))
-            )
-          );
-          const failed = results.find((entry) => entry.res.exitCode !== 0);
-          if (failed !== void 0) {
-            const tail = `${failed.res.stdout}
-${failed.res.stderr}`.trim().slice(-1500);
-            throw new Error(
-              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `
-${tail}` : ""}`
-            );
-          }
-          ranSetup.push(...group.commands);
-        }
-      }
-    } finally {
-      await shell.dispose();
-    }
-  }
-  return { packageManager, ranSetup };
+	const root = workspace.root ?? "/workspace";
+	if (workspace.secrets !== void 0) {
+		const resolved = resolveAllSecrets(workspace.secrets);
+		if (Object.keys(resolved).length > 0) await handle.env.set(resolved);
+	}
+	if (workspace.source.type === "git") {
+		if (!await handle.fs.exists(`${root}/.git`)) await handle.git.clone({
+			url: workspace.source.url,
+			ref: workspace.source.ref,
+			auth: workspace.source.auth,
+			...workspace.source.depth !== void 0 ? { depth: workspace.source.depth } : {}
+		});
+	}
+	const skills = workspace.skills ?? [];
+	for (const skill of skills) if (skill.kind === "git") {
+		const url = skill.repo.startsWith("http") ? skill.repo : `https://github.com/${skill.repo}.git`;
+		const dir = skill.into ?? resolveGitSkillDir(root, skill);
+		const auth = skill.secret !== void 0 && workspace.secrets !== void 0 ? { token: resolveSecret(workspace.secrets, skill.secret) } : void 0;
+		await handle.git.clone({
+			url,
+			dir,
+			...auth !== void 0 ? { auth } : {},
+			depth: 1
+		});
+	}
+	let agentsContent;
+	if (workspace.instructions !== void 0 && workspace.instructions.length > 0) agentsContent = workspace.instructions;
+	else {
+		const agentsFileSkill = skills.find((s) => s.kind === "file" && s.path === "AGENTS.md");
+		if (agentsFileSkill !== void 0) agentsContent = agentsFileSkill.content;
+	}
+	agentsContent = mergeAgentsContent(agentsContent, workspace.scripts);
+	if (agentsContent !== void 0) await writeAgentsFile(handle, root, agentsContent);
+	for (const skill of skills) if (skill.kind === "file" && skill.path !== "AGENTS.md") await handle.fs.write(`${root}/${skill.path}`, skill.content);
+	const packageManager = await detectPackageManager(handle, workspace, root);
+	const ranSetup = [];
+	const plan = buildSetupPlan(workspace.setup);
+	if (plan.length > 0) {
+		const shell = await createBootstrapShell(handle, { cwd: root });
+		try {
+			for (const group of plan) if (group.kind === "serial") {
+				const result = await shell.run(group.command);
+				if (result.exitCode !== 0) {
+					const tail = result.stdout.trim().slice(-1500);
+					throw new Error(`setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `\n${tail}` : ""}`);
+				}
+				ranSetup.push(group.command);
+			} else {
+				const { cwd, env } = await shell.forkState();
+				const failed = (await Promise.all(group.commands.map((command) => handle.process.exec(command, {
+					cwd,
+					env,
+					...options.signal ? { signal: options.signal } : {}
+				}).then((res) => ({
+					command,
+					res
+				}))))).find((entry) => entry.res.exitCode !== 0);
+				if (failed !== void 0) {
+					const tail = `${failed.res.stdout}\n${failed.res.stderr}`.trim().slice(-1500);
+					throw new Error(`setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `\n${tail}` : ""}`);
+				}
+				ranSetup.push(...group.commands);
+			}
+		} finally {
+			await shell.dispose();
+		}
+	}
+	return {
+		packageManager,
+		ranSetup
+	};
 }
-export {
-  DEFAULT_WORKSPACE_ROOT,
-  bootstrapWorkspace,
-  detectPackageManager
-};
-//# sourceMappingURL=bootstrap.js.map
+//#endregion
+export { DEFAULT_WORKSPACE_ROOT, bootstrapWorkspace, detectPackageManager };
+
+//# sourceMappingURL=bootstrap.js.map

package/dist/esm/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sources":["../../src/bootstrap.ts"],"sourcesContent":["/**\n * Workspace bootstrap engine — provider-agnostic because it only uses the\n * {@link SandboxHandle} contract. Runs once when a sandbox is freshly created\n * (or restored without its working tree): land the source, inject secrets,\n * detect the package manager, and run setup commands.\n *\n * Harness-specific projection (CLAUDE.md, agent skills, MCP config) is NOT done\n * here — that's each adapter's `projectWorkspace()` hook, since the format\n * differs per harness.\n */\nimport { buildSetupPlan } from './setup-plan'\nimport { createBootstrapShell } from './shell'\nimport {\n  mergeAgentsContent,\n  resolveGitSkillDir,\n  writeAgentsFile,\n} from './agents-file'\nimport { resolveAllSecrets, resolveSecret } from './secrets'\nimport type { SandboxHandle } from './contracts'\nimport type { PackageManager, WorkspaceDefinition } from './workspace'\n\nconst LOCKFILES: Record<Exclude<PackageManager, 'auto'>, string> = {\n  pnpm: 'pnpm-lock.yaml',\n  yarn: 'yarn.lock',\n  bun: 'bun.lockb',\n  npm: 'package-lock.json',\n}\n\nexport const DEFAULT_WORKSPACE_ROOT = '/workspace'\n\n/** Resolve the package manager, detecting from a lockfile when `'auto'`. */\nexport async function detectPackageManager(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  root: string,\n): Promise<Exclude<PackageManager, 'auto'> | undefined> {\n  const pm = workspace.packageManager ?? 'auto'\n  if (pm !== 'auto') return pm\n  for (const [manager, lockfile] of Object.entries(LOCKFILES) as Array<\n    [Exclude<PackageManager, 'auto'>, string]\n  >) {\n    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager\n  }\n  return undefined\n}\n\nexport interface BootstrapResult {\n  packageManager?: Exclude<PackageManager, 'auto'>\n  ranSetup: Array<string>\n}\n\n/**\n * Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe\n * on restore: a git clone into a populated dir is skipped by checking for the\n * target dir first.\n */\nexport async function bootstrapWorkspace(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  options: { signal?: AbortSignal } = {},\n): Promise<BootstrapResult> {\n  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT\n\n  // Secrets live only in the running sandbox env (never persisted).\n  if (workspace.secrets !== undefined) {\n    const resolved = resolveAllSecrets(workspace.secrets)\n    if (Object.keys(resolved).length > 0) {\n      await handle.env.set(resolved)\n    }\n  }\n\n  // Land the source. Clone into the handle's own default root (each provider\n  // maps the conventional `/workspace` virtual root to its real backing dir),\n  // rather than passing a virtual `dir` that can't be remapped inside a shell\n  // command string.\n  if (workspace.source.type === 'git') {\n    const alreadyCloned = await handle.fs.exists(`${root}/.git`)\n    if (!alreadyCloned) {\n      await handle.git.clone({\n        url: workspace.source.url,\n        ref: workspace.source.ref,\n        auth: workspace.source.auth,\n        ...(workspace.source.depth !== undefined\n          ? { depth: workspace.source.depth }\n          : {}),\n      })\n    }\n  }\n  // 'local' is provider-pre-populated at create; 'none' starts empty.\n\n  // Clone git-skill repos so setup steps (and the harness projector) can use\n  // them. gitSkill clones are always shallow (depth 1) unless the skill's own\n  // repo entry carries a depth override — the WorkspaceSkill `git` variant\n  // does not expose one, so depth always defaults to 1 inside git.clone.\n  const skills = workspace.skills ?? []\n  for (const skill of skills) {\n    if (skill.kind === 'git') {\n      const url = skill.repo.startsWith('http')\n        ? skill.repo\n        : `https://github.com/${skill.repo}.git`\n      const dir = skill.into ?? resolveGitSkillDir(root, skill)\n      const auth =\n        skill.secret !== undefined && workspace.secrets !== undefined\n          ? { token: resolveSecret(workspace.secrets, skill.secret) }\n          : undefined\n      await handle.git.clone({\n        url,\n        dir,\n        ...(auth !== undefined ? { auth } : {}),\n        depth: 1,\n      })\n    }\n  }\n\n  // Write AGENTS.md (and its per-CLI symlinks) when instructions are provided\n  // directly on the workspace, via a fileSkill whose path is `AGENTS.md`, or\n  // when named workspace scripts should be surfaced for the agent.\n  let agentsContent: string | undefined\n  if (\n    workspace.instructions !== undefined &&\n    workspace.instructions.length > 0\n  ) {\n    agentsContent = workspace.instructions\n  } else {\n    const agentsFileSkill = skills.find(\n      (s): s is Extract<typeof s, { kind: 'file' }> =>\n        s.kind === 'file' && s.path === 'AGENTS.md',\n    )\n    if (agentsFileSkill !== undefined) {\n      agentsContent = agentsFileSkill.content\n    }\n  }\n  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts)\n  if (agentsContent !== undefined) {\n    await writeAgentsFile(handle, root, agentsContent)\n  }\n\n  // Write all other fileSkills directly into the workspace root.\n  for (const skill of skills) {\n    if (skill.kind === 'file' && skill.path !== 'AGENTS.md') {\n      await handle.fs.write(`${root}/${skill.path}`, skill.content)\n    }\n  }\n\n  const packageManager = await detectPackageManager(handle, workspace, root)\n\n  // Run setup over a single persistent shell so `cd`/exports persist across\n  // serial steps. Parallel groups fork the shell's current cwd+env into\n  // concurrent one-shot exec calls.\n  const ranSetup: Array<string> = []\n  const plan = buildSetupPlan(workspace.setup)\n  if (plan.length > 0) {\n    const shell = await createBootstrapShell(handle, { cwd: root })\n    try {\n      for (const group of plan) {\n        if (group.kind === 'serial') {\n          const result = await shell.run(group.command)\n          if (result.exitCode !== 0) {\n            const tail = result.stdout.trim().slice(-1500)\n            throw new Error(\n              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(group.command)\n        } else {\n          const { cwd, env } = await shell.forkState()\n          const results = await Promise.all(\n            group.commands.map((command) =>\n              handle.process\n                .exec(command, {\n                  cwd,\n                  env,\n                  ...(options.signal ? { signal: options.signal } : {}),\n                })\n                .then((res) => ({ command, res })),\n            ),\n          )\n          const failed = results.find((entry) => entry.res.exitCode !== 0)\n          if (failed !== undefined) {\n            const tail = `${failed.res.stdout}\\n${failed.res.stderr}`\n              .trim()\n              .slice(-1500)\n            throw new Error(\n              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(...group.commands)\n        }\n      }\n    } finally {\n      await shell.dispose()\n    }\n  }\n\n  return { packageManager, ranSetup }\n}\n"],"names":[],"mappings":";;;;AAqBA,MAAM,YAA6D;AAAA,EACjE,MAAM;AAAA,EACN,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AACP;AAEO,MAAM,yBAAyB;AAGtC,eAAsB,qBACpB,QACA,WACA,MACsD;AACtD,QAAM,KAAK,UAAU,kBAAkB;AACvC,MAAI,OAAO,OAAQ,QAAO;AAC1B,aAAW,CAAC,SAAS,QAAQ,KAAK,OAAO,QAAQ,SAAS,GAEvD;AACD,QAAI,MAAM,OAAO,GAAG,OAAO,GAAG,IAAI,IAAI,QAAQ,EAAE,EAAG,QAAO;AAAA,EAC5D;AACA,SAAO;AACT;AAYA,eAAsB,mBACpB,QACA,WACA,UAAoC,CAAA,GACV;AAC1B,QAAM,OAAO,UAAU,QAAQ;AAG/B,MAAI,UAAU,YAAY,QAAW;AACnC,UAAM,WAAW,kBAAkB,UAAU,OAAO;AACpD,QAAI,OAAO,KAAK,QAAQ,EAAE,SAAS,GAAG;AACpC,YAAM,OAAO,IAAI,IAAI,QAAQ;AAAA,IAC/B;AAAA,EACF;AAMA,MAAI,UAAU,OAAO,SAAS,OAAO;AACnC,UAAM,gBAAgB,MAAM,OAAO,GAAG,OAAO,GAAG,IAAI,OAAO;AAC3D,QAAI,CAAC,eAAe;AAClB,YAAM,OAAO,IAAI,MAAM;AAAA,QACrB,KAAK,UAAU,OAAO;AAAA,QACtB,KAAK,UAAU,OAAO;AAAA,QACtB,MAAM,UAAU,OAAO;AAAA,QACvB,GAAI,UAAU,OAAO,UAAU,SAC3B,EAAE,OAAO,UAAU,OAAO,UAC1B,CAAA;AAAA,MAAC,CACN;AAAA,IACH;AAAA,EACF;AAOA,QAAM,SAAS,UAAU,UAAU,CAAA;AACnC,aAAW,SAAS,QAAQ;AAC1B,QAAI,MAAM,SAAS,OAAO;AACxB,YAAM,MAAM,MAAM,KAAK,WAAW,MAAM,IACpC,MAAM,OACN,sBAAsB,MAAM,IAAI;AACpC,YAAM,MAAM,MAAM,QAAQ,mBAAmB,MAAM,KAAK;AACxD,YAAM,OACJ,MAAM,WAAW,UAAa,UAAU,YAAY,SAChD,EAAE,OAAO,cAAc,UAAU,SAAS,MAAM,MAAM,MACtD;AACN,YAAM,OAAO,IAAI,MAAM;AAAA,QACrB;AAAA,QACA;AAAA,QACA,GAAI,SAAS,SAAY,EAAE,KAAA,IAAS,CAAA;AAAA,QACpC,OAAO;AAAA,MAAA,CACR;AAAA,IACH;AAAA,EACF;AAKA,MAAI;AACJ,MACE,UAAU,iBAAiB,UAC3B,UAAU,aAAa,SAAS,GAChC;AACA,oBAAgB,UAAU;AAAA,EAC5B,OAAO;AACL,UAAM,kBAAkB,OAAO;AAAA,MAC7B,CAAC,MACC,EAAE,SAAS,UAAU,EAAE,SAAS;AAAA,IAAA;AAEpC,QAAI,oBAAoB,QAAW;AACjC,sBAAgB,gBAAgB;AAAA,IAClC;AAAA,EACF;AACA,kBAAgB,mBAAmB,eAAe,UAAU,OAAO;AACnE,MAAI,kBAAkB,QAAW;AAC/B,UAAM,gBAAgB,QAAQ,MAAM,aAAa;AAAA,EACnD;AAGA,aAAW,SAAS,QAAQ;AAC1B,QAAI,MAAM,SAAS,UAAU,MAAM,SAAS,aAAa;AACvD,YAAM,OAAO,GAAG,MAAM,GAAG,IAAI,IAAI,MAAM,IAAI,IAAI,MAAM,OAAO;AAAA,IAC9D;AAAA,EACF;AAEA,QAAM,iBAAiB,MAAM,qBAAqB,QAAQ,WAAW,IAAI;AAKzE,QAAM,WAA0B,CAAA;AAChC,QAAM,OAAO,eAAe,UAAU,KAAK;AAC3C,MAAI,KAAK,SAAS,GAAG;AACnB,UAAM,QAAQ,MAAM,qBAAqB,QAAQ,EAAE,KAAK,MAAM;AAC9D,QAAI;AACF,iBAAW,SAAS,MAAM;AACxB,YAAI,MAAM,SAAS,UAAU;AAC3B,gBAAM,SAAS,MAAM,MAAM,IAAI,MAAM,OAAO;AAC5C,cAAI,OAAO,aAAa,GAAG;AACzB,kBAAM,OAAO,OAAO,OAAO,KAAA,EAAO,MAAM,KAAK;AAC7C,kBAAM,IAAI;AAAA,cACR,sBAAsB,MAAM,OAAO,UAAU,OAAO,QAAQ,IAAI,OAAO;AAAA,EAAK,IAAI,KAAK,EAAE;AAAA,YAAA;AAAA,UAE3F;AACA,mBAAS,KAAK,MAAM,OAAO;AAAA,QAC7B,OAAO;AACL,gBAAM,EAAE,KAAK,IAAA,IAAQ,MAAM,MAAM,UAAA;AACjC,gBAAM,UAAU,MAAM,QAAQ;AAAA,YAC5B,MAAM,SAAS;AAAA,cAAI,CAAC,YAClB,OAAO,QACJ,KAAK,SAAS;AAAA,gBACb;AAAA,gBACA;AAAA,gBACA,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAA,IAAW,CAAA;AAAA,cAAC,CACpD,EACA,KAAK,CAAC,SAAS,EAAE,SAAS,MAAM;AAAA,YAAA;AAAA,UACrC;AAEF,gBAAM,SAAS,QAAQ,KAAK,CAAC,UAAU,MAAM,IAAI,aAAa,CAAC;AAC/D,cAAI,WAAW,QAAW;AACxB,kBAAM,OAAO,GAAG,OAAO,IAAI,MAAM;AAAA,EAAK,OAAO,IAAI,MAAM,GACpD,OACA,MAAM,KAAK;AACd,kBAAM,IAAI;AAAA,cACR,sBAAsB,OAAO,OAAO,UAAU,OAAO,IAAI,QAAQ,IAAI,OAAO;AAAA,EAAK,IAAI,KAAK,EAAE;AAAA,YAAA;AAAA,UAEhG;AACA,mBAAS,KAAK,GAAG,MAAM,QAAQ;AAAA,QACjC;AAAA,MACF;AAAA,IACF,UAAA;AACE,YAAM,MAAM,QAAA;AAAA,IACd;AAAA,EACF;AAEA,SAAO,EAAE,gBAAgB,SAAA;AAC3B;"}
+{"version":3,"file":"bootstrap.js","names":[],"sources":["../../src/bootstrap.ts"],"sourcesContent":["/**\n * Workspace bootstrap engine — provider-agnostic because it only uses the\n * {@link SandboxHandle} contract. Runs once when a sandbox is freshly created\n * (or restored without its working tree): land the source, inject secrets,\n * detect the package manager, and run setup commands.\n *\n * Harness-specific projection (CLAUDE.md, agent skills, MCP config) is NOT done\n * here — that's each adapter's `projectWorkspace()` hook, since the format\n * differs per harness.\n */\nimport { buildSetupPlan } from './setup-plan'\nimport { createBootstrapShell } from './shell'\nimport {\n  mergeAgentsContent,\n  resolveGitSkillDir,\n  writeAgentsFile,\n} from './agents-file'\nimport { resolveAllSecrets, resolveSecret } from './secrets'\nimport type { SandboxHandle } from './contracts'\nimport type { PackageManager, WorkspaceDefinition } from './workspace'\n\nconst LOCKFILES: Record<Exclude<PackageManager, 'auto'>, string> = {\n  pnpm: 'pnpm-lock.yaml',\n  yarn: 'yarn.lock',\n  bun: 'bun.lockb',\n  npm: 'package-lock.json',\n}\n\nexport const DEFAULT_WORKSPACE_ROOT = '/workspace'\n\n/** Resolve the package manager, detecting from a lockfile when `'auto'`. */\nexport async function detectPackageManager(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  root: string,\n): Promise<Exclude<PackageManager, 'auto'> | undefined> {\n  const pm = workspace.packageManager ?? 'auto'\n  if (pm !== 'auto') return pm\n  for (const [manager, lockfile] of Object.entries(LOCKFILES) as Array<\n    [Exclude<PackageManager, 'auto'>, string]\n  >) {\n    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager\n  }\n  return undefined\n}\n\nexport interface BootstrapResult {\n  packageManager?: Exclude<PackageManager, 'auto'>\n  ranSetup: Array<string>\n}\n\n/**\n * Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe\n * on restore: a git clone into a populated dir is skipped by checking for the\n * target dir first.\n */\nexport async function bootstrapWorkspace(\n  handle: SandboxHandle,\n  workspace: WorkspaceDefinition,\n  options: { signal?: AbortSignal } = {},\n): Promise<BootstrapResult> {\n  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT\n\n  // Secrets live only in the running sandbox env (never persisted).\n  if (workspace.secrets !== undefined) {\n    const resolved = resolveAllSecrets(workspace.secrets)\n    if (Object.keys(resolved).length > 0) {\n      await handle.env.set(resolved)\n    }\n  }\n\n  // Land the source. Clone into the handle's own default root (each provider\n  // maps the conventional `/workspace` virtual root to its real backing dir),\n  // rather than passing a virtual `dir` that can't be remapped inside a shell\n  // command string.\n  if (workspace.source.type === 'git') {\n    const alreadyCloned = await handle.fs.exists(`${root}/.git`)\n    if (!alreadyCloned) {\n      await handle.git.clone({\n        url: workspace.source.url,\n        ref: workspace.source.ref,\n        auth: workspace.source.auth,\n        ...(workspace.source.depth !== undefined\n          ? { depth: workspace.source.depth }\n          : {}),\n      })\n    }\n  }\n  // 'local' is provider-pre-populated at create; 'none' starts empty.\n\n  // Clone git-skill repos so setup steps (and the harness projector) can use\n  // them. gitSkill clones are always shallow (depth 1) unless the skill's own\n  // repo entry carries a depth override — the WorkspaceSkill `git` variant\n  // does not expose one, so depth always defaults to 1 inside git.clone.\n  const skills = workspace.skills ?? []\n  for (const skill of skills) {\n    if (skill.kind === 'git') {\n      const url = skill.repo.startsWith('http')\n        ? skill.repo\n        : `https://github.com/${skill.repo}.git`\n      const dir = skill.into ?? resolveGitSkillDir(root, skill)\n      const auth =\n        skill.secret !== undefined && workspace.secrets !== undefined\n          ? { token: resolveSecret(workspace.secrets, skill.secret) }\n          : undefined\n      await handle.git.clone({\n        url,\n        dir,\n        ...(auth !== undefined ? { auth } : {}),\n        depth: 1,\n      })\n    }\n  }\n\n  // Write AGENTS.md (and its per-CLI symlinks) when instructions are provided\n  // directly on the workspace, via a fileSkill whose path is `AGENTS.md`, or\n  // when named workspace scripts should be surfaced for the agent.\n  let agentsContent: string | undefined\n  if (\n    workspace.instructions !== undefined &&\n    workspace.instructions.length > 0\n  ) {\n    agentsContent = workspace.instructions\n  } else {\n    const agentsFileSkill = skills.find(\n      (s): s is Extract<typeof s, { kind: 'file' }> =>\n        s.kind === 'file' && s.path === 'AGENTS.md',\n    )\n    if (agentsFileSkill !== undefined) {\n      agentsContent = agentsFileSkill.content\n    }\n  }\n  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts)\n  if (agentsContent !== undefined) {\n    await writeAgentsFile(handle, root, agentsContent)\n  }\n\n  // Write all other fileSkills directly into the workspace root.\n  for (const skill of skills) {\n    if (skill.kind === 'file' && skill.path !== 'AGENTS.md') {\n      await handle.fs.write(`${root}/${skill.path}`, skill.content)\n    }\n  }\n\n  const packageManager = await detectPackageManager(handle, workspace, root)\n\n  // Run setup over a single persistent shell so `cd`/exports persist across\n  // serial steps. Parallel groups fork the shell's current cwd+env into\n  // concurrent one-shot exec calls.\n  const ranSetup: Array<string> = []\n  const plan = buildSetupPlan(workspace.setup)\n  if (plan.length > 0) {\n    const shell = await createBootstrapShell(handle, { cwd: root })\n    try {\n      for (const group of plan) {\n        if (group.kind === 'serial') {\n          const result = await shell.run(group.command)\n          if (result.exitCode !== 0) {\n            const tail = result.stdout.trim().slice(-1500)\n            throw new Error(\n              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(group.command)\n        } else {\n          const { cwd, env } = await shell.forkState()\n          const results = await Promise.all(\n            group.commands.map((command) =>\n              handle.process\n                .exec(command, {\n                  cwd,\n                  env,\n                  ...(options.signal ? { signal: options.signal } : {}),\n                })\n                .then((res) => ({ command, res })),\n            ),\n          )\n          const failed = results.find((entry) => entry.res.exitCode !== 0)\n          if (failed !== undefined) {\n            const tail = `${failed.res.stdout}\\n${failed.res.stderr}`\n              .trim()\n              .slice(-1500)\n            throw new Error(\n              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `\\n${tail}` : ''}`,\n            )\n          }\n          ranSetup.push(...group.commands)\n        }\n      }\n    } finally {\n      await shell.dispose()\n    }\n  }\n\n  return { packageManager, ranSetup }\n}\n"],"mappings":"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"}