@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/sandbox/mount-plan.js

@@ -52,8 +52,8 @@ export function mountCoordsOf(session, spec) {
         analysisId: session.scope.analysisId,
         runId: session.runFrame.runId,
         stepId: session.runFrame.stepId,
-        ...(spec.readOnly !== undefined ? { readOnly: spec.readOnly } : {}),
-        ...(spec.writableTail !== undefined ? { writableTail: spec.writableTail } : {}),
+        readOnly: spec.readOnly,
+        writableTail: spec.writableTail,
     };
 }
 /**
@@ -110,7 +110,7 @@ export function buildSessionSubPaths(coords, workspaceSubPath) {
     const write = sandboxWriteTail(coords);
     return {
         ro: workspaceSubPath,
-        ...(write === undefined ? {} : { rw: `${workspaceSubPath}/${write.tail}` }),
+        rw: write === undefined ? undefined : `${workspaceSubPath}/${write.tail}`,
     };
 }
 /**
@@ -135,17 +135,16 @@ function libStoreEnv(toolchainSource, cache) {
         };
     }
     const farm = farmContainerPath(toolchainSource);
-    return {
+    const env = {
         R_LIBS_SITE: `${farm}/r/github:${farm}/r/bioconductor:${farm}/r/cran`,
         NODE_PATH: "/opt/node/node_modules",
         PATH: `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/conda/bin:${farm}/python/bin`,
-        ...(cache
-            ? {
-                NUMBA_CACHE_DIR: `${FARM_CACHE_CONTAINER_PATH}/numba-cache`,
-                MPLCONFIGDIR: `${FARM_CACHE_CONTAINER_PATH}/matplotlib_config`,
-            }
-            : {}),
     };
+    if (cache) {
+        env.NUMBA_CACHE_DIR = `${FARM_CACHE_CONTAINER_PATH}/numba-cache`;
+        env.MPLCONFIGDIR = `${FARM_CACHE_CONTAINER_PATH}/matplotlib_config`;
+    }
+    return env;
 }
 export function buildMountPlan(coords, stores) {
     const { analysisId } = coords;
@@ -156,6 +155,9 @@ export function buildMountPlan(coords, stores) {
     const write = sandboxWriteTail(coords);
     const writableStepPath = write === undefined ? undefined : `${readonlyTreePath}/${write.tail}`;
     const cache = stores.libs && stores.cache === true;
+    const env = { PROVENANCE_WATCH_DIRS: readonlyTreePath };
+    if (stores.libs)
+        Object.assign(env, libStoreEnv(stores.toolchainSource, cache));
     return {
         readonlyTreePath,
         writableStepPath,
@@ -165,9 +167,6 @@ export function buildMountPlan(coords, stores) {
         cachePath: cache ? FARM_CACHE_CONTAINER_PATH : undefined,
         refsPath: stores.refs ? REFS_CONTAINER_PATH : undefined,
         stepSubdirs: write?.subdirs ?? [],
-        env: {
-            PROVENANCE_WATCH_DIRS: readonlyTreePath,
-            ...(stores.libs ? libStoreEnv(stores.toolchainSource, cache) : {}),
-        },
+        env,
     };
 }

package/dist/sandbox/notification-sweep.d.ts

@@ -15,14 +15,14 @@
  */
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
-export interface SweepDeps {
+export type SweepDeps = {
     /**
      * Execute the bounded DELETE. Returns the row count cleared. Injected
      * for tests; production wires the app pool.
      */
     deleteStale: (limit: number) => Promise<number>;
     logger?: Logger;
-}
+};
 export declare function sweepStaleNotifications(deps: SweepDeps): Promise<number>;
 /**
  * Default `deleteStale` for production — issues the bounded DELETE
@@ -30,10 +30,10 @@ export declare function sweepStaleNotifications(deps: SweepDeps): Promise<number
  * to. The CTE form keeps the join + the LIMIT in one statement.
  */
 export declare function makeDefaultDeleteStale(pool: Pool): (limit: number) => Promise<number>;
-export interface RegisterNotificationSweepDeps {
+export type RegisterNotificationSweepDeps = {
     pool: Pool;
     logger?: Logger;
     /** Override the DELETE driver — production defaults to the app pool. */
     deleteStale?: (limit: number) => Promise<number>;
-}
+};
 export declare function registerNotificationSweep(deps: RegisterNotificationSweepDeps): void;

package/dist/sandbox/notification-sweep.js

@@ -16,6 +16,7 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { untracedWorkflow } from "../lib/otel-spans.js";
+import { scheduleWorkflow } from "../runtime/dbos.js";
 const SWEEP_CRON = "0 */5 * * * *";
 const SWEEP_WORKFLOW = "dbos-notifications-sweep";
 const DELETE_BATCH_LIMIT = 10_000;
@@ -62,15 +63,11 @@ export function makeDefaultDeleteStale(pool) {
 }
 export function registerNotificationSweep(deps) {
     const deleteStale = deps.deleteStale ?? makeDefaultDeleteStale(deps.pool);
-    // The scheduled target must itself be a registered workflow — DBOS's
-    // scheduler loop skips (and errors on) any `@scheduled` function that lacks
-    // a workflow registration. Register, then schedule the same callable.
+    // The scheduled target must itself be a registered workflow. Register, then
+    // schedule the same callable.
     const sweep = DBOS.registerWorkflow(async () => {
         await sweepStaleNotifications({ deleteStale, logger: deps.logger });
     }, { name: SWEEP_WORKFLOW });
     untracedWorkflow(SWEEP_WORKFLOW);
-    DBOS.registerScheduled(sweep, {
-        name: SWEEP_WORKFLOW,
-        crontab: SWEEP_CRON,
-    });
+    scheduleWorkflow({ scheduleName: SWEEP_WORKFLOW, workflowFn: sweep, schedule: SWEEP_CRON });
 }

package/dist/sandbox/package-identity.d.ts

@@ -9,9 +9,11 @@
  *
  * Two types carry the two ideas. A {@link PackageQuery} is what a person or an
  * agent asked: a spelling, an optional track, an optional version. A
- * {@link PackageIdentity} is the name that an ecosystem recognizes. The
- * identity is opaque, thus a caller cannot invent one, and every identity comes
- * from {@link pythonIdentity}, {@link rIdentity}, or {@link identityOf}.
+ * {@link PackageIdentity} is the name that an ecosystem recognizes. The name is
+ * a plain string, so the type alone cannot make a caller construct through the
+ * rule; the guard is the constructor funnel — every identity comes from
+ * {@link pythonIdentity}, {@link rIdentity}, or {@link identityOf}, and each
+ * of them validates and folds the name before it hands one out.
  *
  * The PEP 503 fold lives in exactly one function of this file. The provisioner
  * holds the Python twin, `images/sandbox-provisioner/package_identity.py`, and
@@ -34,12 +36,6 @@ export type PackageQuery = {
     readonly track?: Track;
     readonly version?: string;
 };
-/**
- * The brand of an identity name. It has no runtime value: it exists so that a
- * literal `{ track, name }` fails the typecheck outside this module, and thus
- * every identity comes from a constructor that applied the rule of its track.
- */
-declare const identityBrand: unique symbol;
 /**
  * The name that one ecosystem recognizes, under the track that holds it.
  *
@@ -50,9 +46,7 @@ declare const identityBrand: unique symbol;
  */
 export type PackageIdentity = {
     readonly track: Track;
-    readonly name: string & {
-        readonly [identityBrand]: true;
-    };
+    readonly name: string;
 };
 /**
  * The Python identity of a spelling. The name folds, because PEP 503 makes
@@ -205,4 +199,3 @@ export type QueryResolution = {
  * `decoupler`, and the R package never links.
  */
 export declare function resolveQuery(query: PackageQuery, pool: PoolIndex): QueryResolution;
-export {};

package/dist/sandbox/package-identity.js

@@ -9,9 +9,11 @@
  *
  * Two types carry the two ideas. A {@link PackageQuery} is what a person or an
  * agent asked: a spelling, an optional track, an optional version. A
- * {@link PackageIdentity} is the name that an ecosystem recognizes. The
- * identity is opaque, thus a caller cannot invent one, and every identity comes
- * from {@link pythonIdentity}, {@link rIdentity}, or {@link identityOf}.
+ * {@link PackageIdentity} is the name that an ecosystem recognizes. The name is
+ * a plain string, so the type alone cannot make a caller construct through the
+ * rule; the guard is the constructor funnel — every identity comes from
+ * {@link pythonIdentity}, {@link rIdentity}, or {@link identityOf}, and each
+ * of them validates and folds the name before it hands one out.
  *
  * The PEP 503 fold lives in exactly one function of this file. The provisioner
  * holds the Python twin, `images/sandbox-provisioner/package_identity.py`, and
@@ -24,19 +26,22 @@ import { err, ok } from "neverthrow";
  * idempotent, thus a fold of a folded name gives that name again.
  */
 function fold(name) {
-    return name.replace(/[-_.]+/g, "-").toLowerCase();
-}
-/**
- * Brand a name that a constructor of this module already ruled on.
- *
- * The cast is the whole point of the brand: the brand has no runtime value,
- * thus only a cast can produce one, and this function is the one place that
- * casts. A caller outside the module reaches a name through a constructor.
- */
-function brand(name) {
-    // The brand is a compile-time marker with no runtime value, thus a cast is
-    // the only way to mint one, and this function is the only site that casts.
-    return name;
+    let out = "";
+    let inRun = false;
+    for (const char of name) {
+        if (char === "-" || char === "_" || char === ".") {
+            inRun = true;
+            continue;
+        }
+        if (inRun) {
+            out += "-";
+            inRun = false;
+        }
+        out += char;
+    }
+    if (inRun)
+        out += "-";
+    return out.toLowerCase();
 }
 /**
  * The Python identity of a spelling. The name folds, because PEP 503 makes
@@ -45,7 +50,7 @@ function brand(name) {
  * @param spelling The distribution name, as the caller spells it.
  */
 export function pythonIdentity(spelling) {
-    return { track: "python", name: brand(fold(spelling)) };
+    return { track: "python", name: fold(spelling) };
 }
 /**
  * The R identity of a name. The name keeps its spelling, because `library()`
@@ -54,7 +59,7 @@ export function pythonIdentity(spelling) {
  * @param name The DESCRIPTION `Package` value.
  */
 export function rIdentity(name) {
-    return { track: "r", name: brand(name) };
+    return { track: "r", name };
 }
 /**
  * The identity of a name that an emitter already minted — a graph node, a lock
@@ -113,10 +118,23 @@ export function identityAddress(identity) {
  * A path, a URL, or a store directory. The entry is trimmed already, thus a
  * leading space cannot defeat the guard.
  */
-const LOCATION = /^[.~]|[/\\]|:\/\//;
-/** The `<word>:` prefix of an entry. The group holds the word before the colon. */
-const PREFIX = /^([A-Za-z][A-Za-z0-9_.-]*):/;
-/** A run of specifier characters. Only the exact run `==` names a version. */
+function isLocation(entry) {
+    return entry.startsWith(".") || entry.startsWith("~") || entry.includes("/") || entry.includes("\\") || entry.includes("://");
+}
+/** The `<word>:` prefix of an entry, or `undefined` when the word before the colon is empty or starts outside the letters. */
+function prefixWordOf(entry) {
+    const at = entry.indexOf(":");
+    if (at < 1)
+        return undefined;
+    const word = entry.slice(0, at);
+    const first = word.charAt(0);
+    const isLeadingLetter = (first >= "A" && first <= "Z") || (first >= "a" && first <= "z");
+    if (!isLeadingLetter)
+        return undefined;
+    const isWordChar = (char) => (char >= "A" && char <= "Z") || (char >= "a" && char <= "z") || (char >= "0" && char <= "9") || char === "_" || char === "." || char === "-";
+    return Array.from(word).every(isWordChar) ? word : undefined;
+}
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the specifier grammar is a run of comparison characters; the parser reads the first run verbatim to accept only `==` and to report any other run.
 const SPECIFIER = /[<>!~=]+/;
 /**
  * A run of characters that an exact version cannot hold: a specifier
@@ -124,6 +142,7 @@ const SPECIFIER = /[<>!~=]+/;
  * thus `numpy==1.26,<2` gives the version `1.26,<2` without this guard, and
  * the compound range then rides into the pool as a version string.
  */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the guard reads the first intruder run of the version text to report it verbatim; the run is the compound specifier the pool must not see.
 const VERSION_INTRUDER = /[<>!~=,\s]+/;
 /**
  * Read one entry of the grammar `[python:|r:]<spelling>[==<version>]`.
@@ -139,10 +158,9 @@ export function parseQuery(entry) {
     const trimmed = entry.trim();
     if (trimmed === "")
         return err({ type: "empty" });
-    if (LOCATION.test(trimmed))
+    if (isLocation(trimmed))
         return err({ type: "location", entry: trimmed });
-    const prefix = PREFIX.exec(trimmed);
-    const word = prefix?.[1];
+    const word = prefixWordOf(trimmed);
     if (word !== undefined && word !== "python" && word !== "r") {
         return err({ type: "unknown_prefix", prefix: word, entry: trimmed });
     }
@@ -152,7 +170,7 @@ export function parseQuery(entry) {
         return err({ type: "empty" });
     const specifier = SPECIFIER.exec(rest);
     if (specifier === null)
-        return ok({ spelling: rest, ...(track === undefined ? {} : { track }) });
+        return ok({ spelling: rest, track });
     if (specifier[0] !== "==") {
         return err({ type: "unsupported_specifier", specifier: specifier[0], entry: trimmed });
     }
@@ -172,8 +190,8 @@ export function parseQuery(entry) {
     }
     return ok({
         spelling,
-        ...(track === undefined ? {} : { track }),
-        ...(version === "" ? {} : { version }),
+        track,
+        version: version === "" ? undefined : version,
     });
 }
 /**

package/dist/sandbox/reaper.d.ts

@@ -19,8 +19,8 @@
  * hoisted for unit testing without a DBOS runtime; `registerSandboxReaper` is
  * the thin production wiring.
  */
-import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
+import type { Querier } from "../state/db.js";
 import type { SandboxClient } from "./client.js";
 import type { ManagedSandbox } from "./types.js";
 export type ReapDecision = "leave" | "reap" | "reap-if-dead";
@@ -41,8 +41,8 @@ export declare function classifyManaged(sb: ManagedSandbox, status: {
 } | null, nowMs: number, graceMs: number): ReapDecision;
 /** Map the owning workflow's terminal status to the step row's terminal status. */
 export declare function terminalStepStatus(workflowStatus: string | null): "canceled" | "failed" | "completed";
-export interface ReaperDeps {
-    pool: Pool;
+export type ReaperDeps = {
+    pool: Querier;
     sandboxClient: Pick<SandboxClient, "listManagedSandboxes" | "teardownById" | "isAliveById">;
     getStatus: (workflowId: string) => Promise<{
         status: string;
@@ -52,8 +52,8 @@ export interface ReaperDeps {
     /** Wall-clock ms; injected for tests. */
     nowMs?: () => number;
     logger?: Logger;
-}
-export interface ReapSummary {
+};
+export type ReapSummary = {
     managedCount: number;
     reapedCount: number;
     rowsReconciled: number;
@@ -64,18 +64,18 @@ export interface ReapSummary {
      * *and* a bug signal — it means owner ids are not round-tripping.
      */
     liveUnattributed: number;
-}
+};
 /**
  * One cluster→registry sweep. Lists managed machines, classifies each against
  * its owner workflow's status, and reaps the terminal/orphaned ones. A reap
  * failure on one machine is logged and skipped — the next sweep retries.
  */
 export declare function reapOnce(deps: ReaperDeps): Promise<ReapSummary>;
-export interface RegisterReaperDeps {
-    pool: Pool;
+export type RegisterReaperDeps = {
+    pool: Querier;
     sandboxClient: Pick<SandboxClient, "listManagedSandboxes" | "teardownById" | "isAliveById">;
     graceMs?: number;
     logger?: Logger;
-}
-/** Production registration: a single (unsharded) `@DBOS.scheduled` workflow. */
+};
+/** Production registration: a single (unsharded) scheduled workflow. */
 export declare function registerSandboxReaper(deps: RegisterReaperDeps): void;

package/dist/sandbox/reaper.js

@@ -22,6 +22,7 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { untracedWorkflow } from "../lib/otel-spans.js";
+import { scheduleWorkflow } from "../runtime/dbos.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { reconcileReapedSandbox } from "../state/active-sandboxes.js";
 const REAPER_CRON = "0 */5 * * * *";
@@ -138,7 +139,7 @@ export async function reapOnce(deps) {
     logger.info("sweep completed", { ...summary });
     return summary;
 }
-/** Production registration: a single (unsharded) `@DBOS.scheduled` workflow. */
+/** Production registration: a single (unsharded) scheduled workflow. */
 export function registerSandboxReaper(deps) {
     const reaper = DBOS.registerWorkflow(async () => {
         // The whole sweep is ONE step: `listManagedSandboxes` is live cluster
@@ -150,14 +151,11 @@ export function registerSandboxReaper(deps) {
         await DBOS.runStep(() => reapOnce({
             pool: deps.pool,
             sandboxClient: deps.sandboxClient,
-            getStatus: async (workflowId) => (await DBOS.getWorkflowStatus(workflowId)),
+            getStatus: async (workflowId) => await DBOS.getWorkflowStatus(workflowId),
             graceMs: deps.graceMs,
             logger: deps.logger,
         }), { name: "sandbox-reaper-sweep" });
     }, { name: REAPER_WORKFLOW });
     untracedWorkflow(REAPER_WORKFLOW);
-    DBOS.registerScheduled(reaper, {
-        name: REAPER_WORKFLOW,
-        crontab: REAPER_CRON,
-    });
+    scheduleWorkflow({ scheduleName: REAPER_WORKFLOW, workflowFn: reaper, schedule: REAPER_CRON });
 }

package/dist/sandbox/sandbox-error.d.ts

@@ -85,8 +85,8 @@ export type SandboxError = {
     /**
      * The label hook of the host refused the spawn. The client made no
      * step tree and called no backend. `reason` is the text of the host,
-     * and `suspend` asks the caller to suspend the work in place of a
-     * failure (see `lib/hooks.ts`).
+     * and `suspend` asks a caller inside a workflow to pause the work in
+     * place of a failure (see `workflows/pause.ts`).
      */
     readonly type: "labels_refused";
     readonly op: string;
@@ -122,13 +122,6 @@ export type SandboxError = {
     readonly lockError: FarmLockError["type"];
     readonly cause: unknown;
 };
-/**
- * The HTTP/driver status a backend SDK error carries. dockerode exposes it on
- * `.statusCode`; `@kubernetes/client-node` (v1.x) on `.code` (a number).
- * Mirror the per-client `statusCodeOf` so 404/409 classification is identical.
- * A Node system error (`code: "ECONNREFUSED"`) has a string `code`, so guard on
- * `typeof === "number"` to avoid returning it as a status.
- */
 export declare function sandboxStatusOf(cause: unknown): number | undefined;
 /**
  * A one-line, user-facing description of a `SandboxError` for logs/error

package/dist/sandbox/sandbox-error.js

@@ -37,7 +37,9 @@
  * step and throws directly, so the seam forwards its promise as-is.)
  */
 import { ResultAsync, err, ok } from "neverthrow";
-import { ZodError } from "zod";
+import { z, ZodError } from "zod";
+import { presentFirst } from "../lib/present.js";
+import { errorMessageOf } from "../lib/thrown.js";
 import { unwrapOrThrow } from "../lib/result.js";
 const _assertDomainError = true;
 /**
@@ -47,11 +49,22 @@ const _assertDomainError = true;
  * A Node system error (`code: "ECONNREFUSED"`) has a string `code`, so guard on
  * `typeof === "number"` to avoid returning it as a status.
  */
+/** The error fields the backend SDKs attach: dockerode `statusCode`, k8s numeric `code`, and the SDK `response`. */
+const SandboxCauseSchema = z.looseObject({
+    code: z.unknown().optional(),
+    statusCode: z.unknown().optional(),
+    response: z.looseObject({ statusCode: z.unknown().optional() }).nullish(),
+});
 export function sandboxStatusOf(cause) {
-    const e = cause;
+    const parsed = SandboxCauseSchema.safeParse(cause);
+    if (!parsed.success)
+        return undefined;
+    const e = parsed.data;
     if (typeof e.code === "number")
         return e.code;
-    return e.statusCode ?? e.response?.statusCode;
+    if (typeof e.statusCode === "number")
+        return e.statusCode;
+    return typeof e.response?.statusCode === "number" ? e.response.statusCode : undefined;
 }
 /**
  * The bound on the appended cause line — the same 200 characters the profile
@@ -78,16 +91,16 @@ function causeLine(cause) {
         const path = issue.path.join(".");
         text = path.length > 0 ? `${path}: ${issue.message}` : issue.message;
     }
-    else if (cause instanceof Error) {
-        text = cause.message;
-    }
     else if (typeof cause === "string") {
         text = cause;
     }
     else {
-        return undefined;
+        const message = errorMessageOf(cause);
+        if (message === undefined)
+            return undefined;
+        text = message;
     }
-    const first = text.split("\n", 1)[0].trim();
+    const first = presentFirst(text.split("\n", 1), "the first cause line").trim();
     if (first.length === 0)
         return undefined;
     return first.length > CAUSE_LINE_MAX ? `${first.slice(0, CAUSE_LINE_MAX - 1)}…` : first;

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -23,16 +23,19 @@ export declare function stepPartId(kind: string, runId: string, stepId: string):
 /**
  * The two parts of one activity emission: the reconciling `data-step-activity` that holds the current activity,
  * and the `data-activity-entry` that keeps the emission in the run stream. Both carry the same phase, activity,
- * and time. `seq` is the position of the emission in the body of its workflow, so each entry has its own id, and a
- * recovered body counts the same emissions again and gives the same ids. Every producer mints the two parts here.
+ * and time. `key` names the entry: the position of a body emission in the body of its workflow, or `tool-` and the
+ * id of the call for the emission of a tool call. A recovered body counts the same body emissions again, and a
+ * replayed tool step emits nothing, thus each entry keeps its id. Every producer mints the two parts here.
  */
 export declare function activityEmission(frame: {
     readonly runId: string;
     readonly stepId: string;
-}, seq: number, phase: StepPhase, activity: string, at: string): {
+}, key: number | string, phase: StepPhase, activity: string, at: string): {
     readonly activity: StepActivityPart;
     readonly entry: ActivityEntryPart;
 };
+/** The key of the activity entry of one tool call. */
+export declare function toolActivityKey(toolUseId: string): string;
 /**
  * The two parts of one synthesis progress report: the reconciling `data-synthesis-progress` that holds the current
  * phase, and the `data-activity-entry` that keeps the report in the run stream under the synthesis step. `seq` is the
@@ -65,11 +68,11 @@ export declare function synthesisEmission(runId: string, stepId: string, seq: nu
 export declare function activityForTool(name: string, input?: unknown, resolveDetail?: ToolDetailResolver): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */
-export interface SandboxTreeDelta {
+export type SandboxTreeDelta = {
     added?: string[];
     modified?: string[];
     removed?: string[];
-}
+};
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by
  *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { event } }`

package/dist/sandbox/sandbox-step-translate.js

@@ -5,6 +5,8 @@
  * extraction/fold, and the chat-data-part narrowing a workflow body composes
  * into its emitters.
  */
+import { z } from "zod";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 /**
  * Stable reconciliation id for a step's reconciling parts
  * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
@@ -22,16 +24,21 @@ export function stepPartId(kind, runId, stepId) {
 /**
  * The two parts of one activity emission: the reconciling `data-step-activity` that holds the current activity,
  * and the `data-activity-entry` that keeps the emission in the run stream. Both carry the same phase, activity,
- * and time. `seq` is the position of the emission in the body of its workflow, so each entry has its own id, and a
- * recovered body counts the same emissions again and gives the same ids. Every producer mints the two parts here.
+ * and time. `key` names the entry: the position of a body emission in the body of its workflow, or `tool-` and the
+ * id of the call for the emission of a tool call. A recovered body counts the same body emissions again, and a
+ * replayed tool step emits nothing, thus each entry keeps its id. Every producer mints the two parts here.
  */
-export function activityEmission(frame, seq, phase, activity, at) {
+export function activityEmission(frame, key, phase, activity, at) {
     const { runId, stepId } = frame;
     return {
         activity: { type: "data-step-activity", id: stepPartId("step-activity", runId, stepId), runId, stepId, phase, activity, at },
-        entry: { type: "data-activity-entry", id: `${stepPartId("activity-entry", runId, stepId)}-${seq}`, runId, stepId, phase, activity, at },
+        entry: { type: "data-activity-entry", id: `${stepPartId("activity-entry", runId, stepId)}-${key}`, runId, stepId, phase, activity, at },
     };
 }
+/** The key of the activity entry of one tool call. */
+export function toolActivityKey(toolUseId) {
+    return `tool-${toolUseId}`;
+}
 /**
  * The two parts of one synthesis progress report: the reconciling `data-synthesis-progress` that holds the current
  * phase, and the `data-activity-entry` that keeps the report in the run stream under the synthesis step. `seq` is the
@@ -67,6 +74,11 @@ export function activityForTool(name, input, resolveDetail) {
     const detail = resolveDetail?.(name, input);
     return detail === undefined ? name : `${name} ${detail}`;
 }
+const SandboxTreeDeltaSchema = z.object({
+    added: z.array(z.string()).optional(),
+    modified: z.array(z.string()).optional(),
+    removed: z.array(z.string()).optional(),
+});
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by
  *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { event } }`
@@ -74,10 +86,12 @@ export function activityForTool(name, input, resolveDetail) {
 export function sandboxTreeDelta(part) {
     if (part.type !== "data-sandbox-event")
         return null;
-    const inner = part.data?.event;
-    if (!inner || inner.kind !== "file-tree" || !inner.tree)
+    const data = parseUnknownRecord(part.data);
+    const inner = data === undefined ? undefined : parseUnknownRecord(data.event);
+    if (!inner || inner.kind !== "file-tree")
         return null;
-    return inner.tree;
+    const tree = SandboxTreeDeltaSchema.safeParse(inner.tree);
+    return tree.success ? tree.data : null;
 }
 /** Apply one on-change delta to the per-step cumulative path set. `added`
  *  and `modified` add the path; `removed` deletes it. Folding many deltas
@@ -98,5 +112,5 @@ export function applyTreeDelta(files, delta) {
  * `done`) never start with `data-`.
  */
 export function isChatDataPart(event) {
-    return typeof event.type === "string" && event.type.startsWith("data-");
+    return "type" in event && typeof event.type === "string" && event.type.startsWith("data-");
 }

package/dist/sandbox/step-sandbox.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One ephemeral sandbox for one exec, inside the durable step of a tool call.
+ *
+ * The identity comes from the step: the exec id is the key of the step, plus a discriminator when one step
+ * runs more than one exec, and the sandbox name comes from the exec id. Thus a rerun of the step adopts the
+ * container of the earlier attempt (`createOrAdopt`), and sandbox-server gives the record of the same exec.
+ * The container goes away when the work ends. Outside a workflow nothing reruns, thus the ids are random.
+ */
+import { type Result } from "neverthrow";
+import type { AuthContext, Identity, SpawnSession } from "../auth/types.js";
+import type { Logger } from "../lib/logger.js";
+import type { SandboxClient } from "./client.js";
+import { type SuspendingRefusal } from "./sandbox-error.js";
+import type { ExecRequest, ExecResult, SandboxSpec } from "./types.js";
+/** The pass of the harness that a sandbox serves. Its run id and its step id name no run of the analysis. */
+export type SandboxPass = {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly stepId: string;
+    readonly agentId: string;
+};
+/**
+ * The spawn session of a pass that runs under the auth of a tool call.
+ *
+ * The pass mints no mandate. The session never enters durable state: the sandbox client reads its scope and
+ * its frame for the mounts and the labels, and the label hook of the host reads it in process.
+ */
+export declare function passSpawnSession(caller: {
+    readonly identity: Identity;
+    readonly auth: AuthContext;
+}, pass: SandboxPass): SpawnSession;
+export type StepSandboxRequest = {
+    readonly session: SpawnSession;
+    readonly spec: Omit<SandboxSpec, "childWorkflowId">;
+    /** Tells two execs of one step apart. A step that runs one exec gives none. */
+    readonly execKey?: string;
+};
+/**
+ * The one exec of a step sandbox, with its budget in milliseconds. A pass reports no live activity, thus the
+ * events go nowhere.
+ */
+export type StepSandboxExec = (request: ExecRequest, budgetMs: number) => Promise<ExecResult>;
+/**
+ * Make the sandbox, give `work` its exec, and remove the sandbox when `work` ends. A suspending refusal of
+ * the spawn is the `err`, and each other fault throws.
+ */
+export declare function withStepSandbox<T>(client: SandboxClient, request: StepSandboxRequest, logger: Logger, work: (exec: StepSandboxExec) => Promise<T>): Promise<Result<T, SuspendingRefusal>>;