@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/sandbox/liveness.js

@@ -9,6 +9,8 @@
  * versus live-but-slow, invoked through {@link probeLiveness} once
  * {@link createEscalationPolicy} arms.
  */
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
 /**
  * Consecutive `unavailable` polls tolerated before probing. On the fast poll
  * cadence (~1.5 s) this is seconds of silence before the first probe — a dead
@@ -50,7 +52,7 @@ export async function probeLiveness(isAlive, ref) {
         liveness = await isAlive(ref);
     }
     catch (cause) {
-        return { kind: "inconclusive", detail: cause instanceof Error ? cause.message : String(cause) };
+        return { kind: "inconclusive", detail: errorMessageOf(cause) ?? textOf(cause) };
     }
     return liveness.alive ? { kind: "alive" } : { kind: "dead", oomKilled: liveness.oomKilled };
 }

package/dist/sandbox/mount-plan.d.ts

@@ -46,7 +46,7 @@ export declare const FARM_CACHE_CONTAINER_PATH = "/mnt/libs/cache";
  * images name that path.
  */
 export declare function farmContainerPath(toolchainSource: ToolchainSource | undefined): string;
-export interface MountPlanCoords {
+export type MountPlanCoords = {
     analysisId: string;
     runId: string;
     stepId: string;
@@ -64,9 +64,9 @@ export interface MountPlanCoords {
      * contradiction, and the builders refuse it.
      */
     writableTail?: string;
-}
+};
 export declare function mountCoordsOf(session: SpawnSession, spec: Pick<SandboxSpec, "readOnly" | "writableTail">): MountPlanCoords;
-export interface MountPlanStores {
+export type MountPlanStores = {
     /** Lib store is mounted at `/mnt/libs`, with the farm nested inside it, and its env is emitted. */
     libs: boolean;
     /** Ref store is mounted at `/mnt/refs`. */
@@ -79,8 +79,8 @@ export interface MountPlanStores {
     toolchainSource?: ToolchainSource;
     /** The farm resolution carries a cache location, mounted read-write at `/mnt/libs/cache`. */
     cache?: boolean;
-}
-export interface MountPlan {
+};
+export type MountPlan = {
     /** Flat read-only mount of the whole analysis tree. */
     readonlyTreePath: string;
     /**
@@ -106,21 +106,21 @@ export interface MountPlan {
     stepSubdirs: readonly string[];
     /** Env merged into the sandbox container: provenance + lib-store vars. */
     env: Record<string, string>;
-}
+};
 /** K8s `subPath` strings into the session PVC. No leading or trailing slash. */
-export interface SessionSubPaths {
+export type SessionSubPaths = {
     /** Read-only mount of the whole analysis tree. */
     readonly ro: string;
     /** Read-write mount of the step's artifact dir, or of the declared tail; absent when read-only. */
     readonly rw?: string;
-}
+};
 /** The one writable mount of a sandbox: its workspace-relative tail, and what the host pre-makes under it. */
-export interface SandboxWriteTail {
+export type SandboxWriteTail = {
     /** The tail beneath the workspace root, in both container and PVC-relative space. */
     readonly tail: string;
     /** The subdirectories the host pre-creates under the tail. A declared tail is one directory, thus none. */
     readonly subdirs: readonly string[];
-}
+};
 /**
  * The write tail of a sandbox, or `undefined` when the sandbox holds no write mount.
  *

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 } }`