@inflexa-ai/harness 0.45.0 → 0.46.0

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>>;

package/dist/sandbox/step-sandbox.js

@@ -0,0 +1,53 @@
+/**
+ * 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 { DBOS } from "@dbos-inc/dbos-sdk";
+import { err, ok } from "neverthrow";
+import { randomUUID } from "node:crypto";
+import { durableStepKey } from "../tools/workspace/edit-file.js";
+import { keyedSandboxIdentity } from "./identity.js";
+import { keepSuspendingRefusal } from "./sandbox-error.js";
+/**
+ * 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 function passSpawnSession(caller, pass) {
+    return {
+        identity: caller.identity,
+        scope: { kind: "analysis", analysisId: pass.analysisId },
+        provenance: { agentId: pass.agentId, callPath: [pass.agentId] },
+        runFrame: { runId: pass.runId, stepId: pass.stepId },
+        auth: caller.auth,
+    };
+}
+const noopEmit = () => { };
+/**
+ * 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 async function withStepSandbox(client, request, logger, work) {
+    const stepKey = durableStepKey();
+    const execId = stepKey === undefined ? `${request.session.runFrame.runId}:${randomUUID()}` : request.execKey === undefined ? stepKey : `${stepKey}:${request.execKey}`;
+    const spawned = keepSuspendingRefusal(await client.createSandbox(request.session, { ...request.spec, childWorkflowId: DBOS.workflowID ?? execId }, keyedSandboxIdentity(request.session.runFrame.runId, execId)));
+    if (spawned.isErr())
+        return err(spawned.error);
+    const sandbox = spawned.value;
+    try {
+        return ok(await work(async (execRequest, budgetMs) => client.exec(sandbox, execRequest, noopEmit, (await DBOS.now()) + budgetMs, execId)));
+    }
+    finally {
+        try {
+            await client.teardown(sandbox);
+        }
+        catch (cause) {
+            logger.warn("the sandbox of the pass did not tear down", { sandboxId: sandbox.sandboxId, ...logger.errorFields(cause) });
+        }
+    }
+}

package/dist/sandbox/types.d.ts

@@ -33,10 +33,10 @@ export type ToolchainSource = "image" | "store";
  * per-analysis read-write cache. When it is present, the backend mounts it
  * at `/mnt/libs/cache`.
  */
-export interface FarmLocation {
+export type FarmLocation = {
     readonly farmPath: string;
     readonly cachePath?: string;
-}
+};
 /** The answer of a farm resolver: a usable farm, or a refusal that carries the reason of the embedder. */
 export type FarmResolution = {
     readonly kind: "available";
@@ -141,10 +141,10 @@ export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQ
  * terminated reason `OOMKilled`) — the exec surfaces it as the
  * `sandbox-oom-killed` failure reason instead of the generic `sandbox-dead`.
  */
-export interface SandboxLiveness {
+export type SandboxLiveness = {
     readonly alive: boolean;
     readonly oomKilled: boolean;
-}
+};
 export type SandboxRef = PersistedSandboxRef;
 /**
  * One tracked file operation in the sandbox-server provenance frame.
@@ -241,7 +241,7 @@ export type ExecResult = z.infer<typeof ExecResultSchema>;
  */
 export declare const PollEventSchema: z.ZodObject<{
     seq: z.ZodNumber;
-    payload: z.ZodUnknown;
+    payload: z.ZodJSONSchema;
 }, z.core.$strip>;
 export type PollEvent = z.infer<typeof PollEventSchema>;
 /**
@@ -253,13 +253,13 @@ export type PollEvent = z.infer<typeof PollEventSchema>;
  */
 export declare const PollResponseSchema: z.ZodObject<{
     status: z.ZodEnum<{
+        completed: "completed";
         failed: "failed";
         running: "running";
-        completed: "completed";
     }>;
     events: z.ZodDefault<z.ZodArray<z.ZodObject<{
         seq: z.ZodNumber;
-        payload: z.ZodUnknown;
+        payload: z.ZodJSONSchema;
     }, z.core.$strip>>>;
     cursor: z.ZodNumber;
     truncated: z.ZodDefault<z.ZodBoolean>;
@@ -303,14 +303,14 @@ export type PollResponse = z.infer<typeof PollResponseSchema>;
  * One command for `SandboxClient.exec`. It carries no exec id: the exec
  * derives its id from the durable step it runs in.
  */
-export interface ExecRequest {
+export type ExecRequest = {
     readonly command: readonly string[];
     readonly cwd?: string;
     readonly env?: Readonly<Record<string, string>>;
     readonly timeoutSeconds?: number;
-}
+};
 /** Wire shape the exec POSTs to sandbox-server's `/exec`. */
-export interface SubmitExecBody {
+export type SubmitExecBody = {
     command: string[];
     execId: string;
     cwd?: string;
@@ -324,9 +324,9 @@ export interface SubmitExecBody {
      */
     stdoutByteCap?: number;
     stderrByteCap?: number;
-}
+};
 /** What a spawn needs beside its session. */
-export interface SandboxSpec {
+export type SandboxSpec = {
     /** Owning DBOS child workflow id (`"${parentRunId}-${N}"`). Recorded verbatim
      *  on the sandbox machine under `cortex/owner-workflow-id` so the reaper can
      *  map a cluster-side machine back to its workflow and check liveness. */
@@ -335,8 +335,7 @@ export interface SandboxSpec {
     image?: string;
     extraEnv?: Record<string, string>;
     /** CPU/memory/GPU request for the sandbox machine. Required of every
-     *  caller — `createSandboxClient` clamps it to cluster limits and rejects
-     *  a sandbox with none. */
+     *  caller — `createSandboxClient` clamps it to cluster limits. */
     resources: ResourceSpec;
     /** Enforced read-only: provision with no read-write step mount, only the
      *  read-only analysis tree for generic read-only agents. */
@@ -347,7 +346,7 @@ export interface SandboxSpec {
      *  mount, thus a run provisions exactly as before. A tail beside `readOnly` is
      *  a contradiction, and the mount builders refuse it. */
     writableTail?: string;
-}
+};
 /** The labels that the host adds to a sandbox. The harness stamps each one as the host gives it. */
 export type SandboxLabels = Readonly<Record<string, string>>;
 /**
@@ -362,11 +361,11 @@ export type ResolveSandboxLabels = (session: RunSession) => ResultAsync<SandboxL
  * recovery re-run of the spawn step adopts the already-created machine under
  * the same name instead of leaking a second one.
  */
-export interface SandboxIdentity {
+export type SandboxIdentity = {
     /** `sbx-{run8}-{uuid4}` — informative for `kubectl`, not load-bearing; the
      *  checkpoint, not the name, is what makes create idempotent. */
     sandboxId: string;
-}
+};
 /**
  * A sandbox machine the backend is running that Cortex *manages*
  * (`app.kubernetes.io/managed-by=cortex`), enumerated by the reaper for the
@@ -375,11 +374,11 @@ export interface SandboxIdentity {
  * machine records no owner, and such a machine is reaped only past a
  * creation-time grace and only when observably dead.
  */
-export interface ManagedSandbox {
+export type ManagedSandbox = {
     sandboxId: string;
     ownerWorkflowId: string | null;
     createdAtMs: number | null;
-}
+};
 /**
  * Progress callback of `SandboxClient.exec`, called with each sandbox event in
  * sequence order. The exec awaits each call before it polls again.

package/dist/sandbox/types.js

@@ -100,7 +100,7 @@ export const ExecResultSchema = z.object({
  */
 export const PollEventSchema = z.object({
     seq: z.number().int(),
-    payload: z.unknown(),
+    payload: z.json(),
 });
 /**
  * Body of `GET /exec/{execId}?since={cursor}`. Mirrors Go's

package/dist/schemas/artifact-manifest.d.ts

@@ -7,11 +7,11 @@
 import { z } from "zod";
 /** Artifact type inferred from the step subdirectory. */
 export declare const ArtifactTypeSchema: z.ZodEnum<{
-    output: "output";
-    script: "script";
     figure: "figure";
     log: "log";
     notebook: "notebook";
+    output: "output";
+    script: "script";
 }>;
 export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
 /** A single artifact manifest entry. */
@@ -21,11 +21,11 @@ export declare const ArtifactManifestEntrySchema: z.ZodObject<{
     path: z.ZodString;
     size: z.ZodNumber;
     type: z.ZodEnum<{
-        output: "output";
-        script: "script";
         figure: "figure";
         log: "log";
         notebook: "notebook";
+        output: "output";
+        script: "script";
     }>;
     hash: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;