@inflexa-ai/harness 0.45.1 → 0.46.0

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