@inflexa-ai/harness 0.37.0 → 0.38.0

package/dist/providers/errors.js

@@ -2,18 +2,20 @@
  * Provider error taxonomy.
  *
  * Callers (the agent loop, the chat route, DBOS steps) branch on error
- * origin: a billing-gateway governance rejection is permanent and user-facing; a
+ * origin: a status that the host maps to a suspension stops the work; a
  * transient upstream hiccup is retryable. This module owns the
  * classification so callers do not re-derive it.
  *
- * The billing-gateway convention is status-code driven (no dedicated error header
- * is required to disambiguate): the gateway emits `402` exclusively for
- * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
- * failures (429, 5xx, connection) surface with their own status or as a
- * network error with no status at all. A `401` is `auth`: the credential the
- * host put behind the call is expired, revoked, or absent, and only a human
- * re-authenticating fixes it — which is a different remedy from every other
- * non-retryable 4xx, so it is a different kind.
+ * The classification keys on the HTTP status alone. The meaning of a status
+ * belongs to the gateway of the host, thus each provider takes a map from a
+ * status to a suspend reason (`suspendOn`). A status in the map is a `suspend`
+ * error, before each other rule, and it is never retried. The harness carries
+ * the reason and never reads it. Provider-originated failures (429, 5xx,
+ * connection) surface with their own status or as a network error with no
+ * status at all. A `401` is `auth`: the credential the host put behind the call
+ * is expired, revoked, or absent, and only a human re-authenticating fixes it —
+ * which is a different remedy from every other non-retryable 4xx, so it is a
+ * different kind.
  */
 import { redactSecrets } from "../input-sanitization.js";
 /**
@@ -34,6 +36,8 @@ export class RequestTimeoutError extends Error {
         this.requestTimeoutMs = requestTimeoutMs;
     }
 }
+/** The map of a provider that the host gives no map: `402` names a payment that the gateway requires. */
+export const DEFAULT_SUSPEND_ON = { 402: "payment_required" };
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
  * `ProviderError` is a plain object, not an `Error`, so it cannot be
@@ -44,16 +48,27 @@ export function isProviderError(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const v = value;
-    return ((v.type === "auth" || v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") &&
-        typeof v.retryable === "boolean" &&
-        typeof v.message === "string");
+    return (v.type === "auth" || v.type === "suspend" || v.type === "provider") && typeof v.retryable === "boolean" && typeof v.message === "string";
+}
+/**
+ * Find a `suspend` error on a failure or on its `cause` chain. A step boundary
+ * rethrows a `ProviderError` inside a `ResultError`, with the value on
+ * `.cause`, thus the walk reaches it.
+ *
+ * A failed step that DBOS replays gives the error that DBOS recorded. That
+ * record keeps only the enumerable fields of a `ResultError`: `.value` stays,
+ * and the non-enumerable `.cause` does not. Thus the walk also reads `.value`.
+ */
+export function findSuspendError(err) {
+    const asSuspend = (value) => (isProviderError(value) && value.type === "suspend" ? value : undefined);
+    return findInCauseChain(err, (link) => asSuspend(link) ?? (typeof link === "object" && link !== null ? asSuspend(link.value) : undefined));
 }
 /**
  * Turn a caught SDK throwable into a `ProviderError` value. Routes through
- * `classifyProviderError` so the `provider` variant's `retryable` keeps the
- * transient (429 / 5xx / connection) classification. `cause` is the original
- * throwable verbatim — for the budget variant it MUST be the SDK error
- * carrying status 402, which is what `isBudgetExceeded` walks.
+ * `classifyProviderError` with the `suspendOn` map of the provider, so the
+ * `provider` variant's `retryable` keeps the transient (429 / 5xx / connection)
+ * classification and a mapped status becomes a `suspend` error. `cause` is the
+ * original throwable verbatim.
  *
  * Idempotent: `chatStream` throws a `ProviderError` value, which
  * `streaming-chat`'s `catch` re-wraps by calling this again. Returning an
@@ -61,7 +76,7 @@ export function isProviderError(value) {
  * `String()`-ing the object (a `ProviderError` is not an `Error`) into a
  * `"[object Object]"` message that would bury the real inner one.
  */
-export function toProviderError(e, workload) {
+export function toProviderError(e, workload, suspendOn = DEFAULT_SUSPEND_ON) {
     if (isProviderError(e))
         return e;
     // A guard abort names the configured value in its message. Compose a message
@@ -78,9 +93,9 @@ export function toProviderError(e, workload) {
             cause: e,
         };
     }
-    const { kind, retryable } = classifyProviderError(e);
+    const classified = classifyProviderError(e, suspendOn);
     const detail = e instanceof Error ? e.message : String(e);
-    if (kind === "auth") {
+    if (classified.kind === "auth") {
         return {
             type: "auth",
             retryable: false,
@@ -88,25 +103,11 @@ export function toProviderError(e, workload) {
             cause: e,
         };
     }
-    if (kind === "budget") {
-        return {
-            type: "budget",
-            retryable: false,
-            message: `Billing budget exceeded for ${workload}: ${detail}`,
-            cause: e,
-        };
-    }
-    if (kind === "tenant-blocked") {
-        return {
-            type: "tenant-blocked",
-            retryable: false,
-            message: `Billing gateway blocked tenant for ${workload}: ${detail}`,
-            cause: e,
-        };
-    }
-    // The `provider` arm composes like its three siblings rather than forwarding
-    // the SDK message verbatim. It has to: when a 4xx body does not parse against
-    // the configured provider's error schema, the AI SDK falls back to
+    // The `provider` and `suspend` arms compose one generic HTTP message rather
+    // than forwarding the SDK message verbatim. A `suspend` message names no
+    // cause of its own: the reason of the host rides beside it. The composition
+    // has to happen: when a 4xx body does not parse against the configured
+    // provider's error schema, the AI SDK falls back to
     // `response.statusText`, so the "detail" is a bare HTTP reason phrase —
     // `"Bad Request"` — that names neither the call nor the cause, while the
     // status, the workload, and the body the SDK captured are all still on the
@@ -120,18 +121,17 @@ export function toProviderError(e, workload) {
     // A transport that carries no reason phrase (an HTTP/2 hop yields
     // `statusText === ""`) leaves `detail` empty; appending it regardless would
     // trail a bare `": "` on an otherwise complete message.
-    const reason = detail.trim();
-    const diagnosed = reason ? `${lead}: ${reason}` : lead;
+    const phrase = detail.trim();
+    const diagnosed = phrase ? `${lead}: ${phrase}` : lead;
     const body = extractResponseBody(e);
-    return {
-        type: "provider",
-        retryable,
-        // The excerpt trails deliberately — workload and status lead, so a
-        // downstream truncation (`profileFailureReason` cuts the line at 200)
-        // eats the least diagnostic content first.
-        message: body ? `${diagnosed} — response body: ${excerptResponseBody(body)}` : diagnosed,
-        cause: e,
-    };
+    // The excerpt trails deliberately — workload and status lead, so a
+    // downstream truncation (`profileFailureReason` cuts the line at 200)
+    // eats the least diagnostic content first.
+    const message = body ? `${diagnosed} — response body: ${excerptResponseBody(body)}` : diagnosed;
+    if (classified.kind === "suspend") {
+        return { type: "suspend", retryable: false, reason: classified.reason, status: classified.status, message, cause: e };
+    }
+    return { type: "provider", retryable: classified.retryable, message, cause: e };
 }
 /**
  * Max characters of a captured provider response body carried in a message.
@@ -284,13 +284,13 @@ function looksLikeConnectionError(err) {
 /**
  * Classify a provider failure by origin.
  *
+ * - A status in `suspendOn` → `suspend` with the reason of the map, not
+ *   retryable. This rule comes before each other status rule.
  * - Provider `401` → `auth`, not retryable.
- * - Billing-gateway `402` → `budget`, not retryable.
- * - Billing-gateway `403` → `tenant-blocked`, not retryable.
  * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
  * - Other `4xx` and parse / unknown errors → `provider`, not retryable.
  */
-export function classifyProviderError(e) {
+export function classifyProviderError(e, suspendOn = DEFAULT_SUSPEND_ON) {
     // The request-timeout guard aborts an attempt with a typed sentinel, and the
     // chunk bound of the SDK aborts one with a `TimeoutError`. Each classifies as
     // a retryable provider timeout, thus the envelope retries it under the same
@@ -300,6 +300,9 @@ export function classifyProviderError(e) {
     if (findRequestTimeout(e) !== undefined || findSdkTimeout(e) !== undefined)
         return { kind: "provider", retryable: true };
     const status = extractStatus(e);
+    if (status !== undefined && Object.hasOwn(suspendOn, status)) {
+        return { kind: "suspend", retryable: false, reason: suspendOn[status], status };
+    }
     // `auth` is its own kind rather than a plain non-retryable 4xx because the
     // remedy is categorically different: the request was well-formed and the
     // credential behind it is not, so no amount of re-issuing or rephrasing
@@ -307,16 +310,12 @@ export function classifyProviderError(e) {
     // 4xx branch below would tell them the request was wrong, which is false.
     if (status === 401)
         return { kind: "auth", retryable: false };
-    if (status === 402)
-        return { kind: "budget", retryable: false };
-    if (status === 403)
-        return { kind: "tenant-blocked", retryable: false };
     if (status === 429 || (status !== undefined && status >= 500)) {
         return { kind: "provider", retryable: true };
     }
     if (status !== undefined) {
-        // A concrete 4xx (other than 402/403) — the request is wrong; retrying
-        // it unchanged will fail again.
+        // A concrete 4xx that the map does not hold — the request is wrong;
+        // retrying it unchanged will fail again.
         return { kind: "provider", retryable: false };
     }
     // No status: a transport failure is retryable; anything else (parse

package/dist/providers/request-headers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The model request headers hook.
+ *
+ * The hook is a gate (`lib/hooks.ts`): the provider calls it before each
+ * attempt of a model request, and it adds the headers to the request as the
+ * hook gives them. The harness reads no header and makes no header of its own.
+ *
+ * The hook is not the model wire, thus a refusal stops the call at once, with
+ * no retry, and the refused attempt is never sent.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { ResolvableSession } from "../auth/types.js";
+import { type GateFailure, type GateRefusal } from "../lib/hooks.js";
+import type { ProviderError } from "./errors.js";
+export type RequestHeaders = Readonly<Record<string, string>>;
+export type ResolveRequestHeaders = (session: ResolvableSession) => ResultAsync<RequestHeaders, GateFailure>;
+export declare function requestHeadersFor(hook: ResolveRequestHeaders | undefined, session: ResolvableSession): ResultAsync<RequestHeaders, GateRefusal>;
+export declare function headersRefusalError(refusal: GateRefusal, workload: string): ProviderError;

package/dist/providers/request-headers.js

@@ -0,0 +1,22 @@
+/**
+ * The model request headers hook.
+ *
+ * The hook is a gate (`lib/hooks.ts`): the provider calls it before each
+ * attempt of a model request, and it adds the headers to the request as the
+ * hook gives them. The harness reads no header and makes no header of its own.
+ *
+ * The hook is not the model wire, thus a refusal stops the call at once, with
+ * no retry, and the refused attempt is never sent.
+ */
+import { okAsync } from "neverthrow";
+import { passGate } from "../lib/hooks.js";
+const NO_HEADERS = {};
+export function requestHeadersFor(hook, session) {
+    return hook === undefined ? okAsync(NO_HEADERS) : passGate("resolveRequestHeaders", hook(session));
+}
+export function headersRefusalError(refusal, workload) {
+    const message = `The request headers hook refused the model call for ${workload}: ${refusal.reason}`;
+    return refusal.kind === "suspended"
+        ? { type: "suspend", retryable: false, reason: refusal.reason, message }
+        : { type: "provider", retryable: false, message };
+}

package/dist/report-model/production-resolver.d.ts

@@ -17,6 +17,8 @@
  * and the reason choices of `fixture-resolver.ts`. Thus one semantics exists, and the fixture stays the
  * executable specification of the value tier. The two realizations are substitutable behind the seam.
  */
+import { type Result } from "neverthrow";
+import type { Suspension } from "../workflows/suspension.js";
 import { type ReferenceResolver } from "./reference-resolver.js";
 /**
  * One artifact that the host fast path could not read, addressed for the extraction arm. The `hash` pins
@@ -37,13 +39,14 @@ export interface ExtractionArtifact {
 /**
  * The out-of-process read arm. One `extract` call covers every fall-through artifact of one document
  * pass. The result maps each requested path to its rows. A path that the arm could not read is absent
- * from the map, and the reference at that path fails as `unreadable-artifact`.
+ * from the map, and the reference at that path fails as `unreadable-artifact`. A suspension of the pass is
+ * the `err`, and each reference of the batch reports its reason.
  *
  * The arm is a seam, thus a test stubs it. While no realization is wired, a fall-through reference fails
  * with `extraction-unavailable`, and the detail names the absent arm.
  */
 export interface ExtractionArm {
-    extract(requests: readonly ExtractionRequest[]): Promise<ReadonlyMap<string, ExtractionArtifact>>;
+    extract(requests: readonly ExtractionRequest[]): Promise<Result<ReadonlyMap<string, ExtractionArtifact>, Suspension>>;
 }
 /**
  * The disk facts of one artifact that outlive one resolver.

package/dist/report-model/production-resolver.js

@@ -437,9 +437,9 @@ async function extractFallThrough(arm, requests) {
         }
         return out;
     }
-    let answers;
+    let answered;
     try {
-        answers = await arm.extract(requests.map((request) => ({ path: request.path, hash: request.hash, format: request.format })));
+        answered = await arm.extract(requests.map((request) => ({ path: request.path, hash: request.hash, format: request.format })));
     }
     catch {
         // The arm speaks the throw protocol for a genuine infrastructure fault. This boundary turns the
@@ -449,6 +449,16 @@ async function extractFallThrough(arm, requests) {
         }
         return out;
     }
+    if (answered.isErr()) {
+        for (const request of requests) {
+            out.set(request.path, {
+                kind: "unavailable",
+                detail: `the analysis is suspended (${answered.error.reason}), thus the file at ${request.path} was not read`,
+            });
+        }
+        return out;
+    }
+    const answers = answered.value;
     for (const request of requests) {
         const answer = answers.get(request.path);
         out.set(request.path, answer === undefined

package/dist/runtime/assemble.d.ts

@@ -25,6 +25,7 @@ import { type AcquireEyes } from "../lib/eyes.js";
 import type { ThreadType } from "../memory/thread-store.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
+import type { Suspension } from "../workflows/suspension.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
 import { type ExtractValuesResult, type ExtractValuesWorkflowInput } from "../tasks/extract-values.js";
 import type { DeriveTableExecInput } from "../tools/report-session/derive-table.js";
@@ -60,8 +61,8 @@ export interface RegisteredWorkflows {
     readonly executeAnalysis: (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
     readonly sandboxStep: SandboxStepCallable;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
-    readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
-    readonly deriveTableExec: (input: DeriveTableExecInput) => Promise<ExecResult>;
+    readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<Result<ExtractValuesResult, Suspension>>;
+    readonly deriveTableExec: (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, the

package/dist/runtime/dbos.d.ts

@@ -92,9 +92,10 @@ export declare function dbosSdkConfig(config: DbosConfig, logger: Logger): DBOSC
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
  *
- * Order is load-bearing: `setConfig` must precede `launch`, and `launch`
- * must resolve before the HTTP listener accepts traffic (otherwise the
- * readiness probe could 200 against a runtime that can't own workflows).
+ * Order is load-bearing: `setConfig` and the `Result` recipes must precede
+ * `launch`, and `launch` must resolve before the HTTP listener accepts traffic
+ * (otherwise the readiness probe could 200 against a runtime that can't own
+ * workflows).
  */
 export declare function launchDbos({ config, logger: injected }: {
     config: DbosConfig;

package/dist/runtime/dbos.js

@@ -14,6 +14,7 @@
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { DBOS_SYSTEM_POOL_SIZE } from "./pools.js";
+import { errRecipe, okRecipe } from "./result-serialization.js";
 const state = {
     launched: false,
     recoveryStarted: false,
@@ -115,13 +116,26 @@ export function dbosSdkConfig(config, logger) {
         otelAttributeFormat: "semconv",
     };
 }
+let resultRecipesRegistered = false;
+/**
+ * DBOS refuses a registration after the launch, and the registry of SuperJSON
+ * is global to the process, thus a relaunch keeps the recipes.
+ */
+function registerResultSerialization() {
+    if (resultRecipesRegistered)
+        return;
+    DBOS.registerSerialization(okRecipe);
+    DBOS.registerSerialization(errRecipe);
+    resultRecipesRegistered = true;
+}
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.
  *
- * Order is load-bearing: `setConfig` must precede `launch`, and `launch`
- * must resolve before the HTTP listener accepts traffic (otherwise the
- * readiness probe could 200 against a runtime that can't own workflows).
+ * Order is load-bearing: `setConfig` and the `Result` recipes must precede
+ * `launch`, and `launch` must resolve before the HTTP listener accepts traffic
+ * (otherwise the readiness probe could 200 against a runtime that can't own
+ * workflows).
  */
 export async function launchDbos({ config, logger: injected }) {
     if (state.launched)
@@ -129,6 +143,7 @@ export async function launchDbos({ config, logger: injected }) {
     const logger = injected.named("dbos");
     const sdkConfig = dbosSdkConfig(config, logger);
     DBOS.setConfig(sdkConfig);
+    registerResultSerialization();
     const start = performance.now();
     await DBOS.launch();
     state.launched = true;

package/dist/runtime/result-serialization.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The DBOS serialization recipes of the neverthrow `Ok` and `Err` classes.
+ *
+ * DBOS saves each workflow input, step output, workflow output, and message
+ * with SuperJSON, and SuperJSON drops the class of an object that it does not
+ * know. Without these recipes a step that returns a `Result` gives back a plain
+ * object with no `Result` methods, on the first run and on each replay alike,
+ * because DBOS hands the body the deserialized value. `launchDbos` registers
+ * the recipes one time, before DBOS launches.
+ *
+ * SuperJSON does not walk the output of a custom recipe, thus each recipe
+ * encodes the value that it holds as JSON itself. An `Error` inside that value
+ * keeps its name and its message only, and a `Result` nested inside the value
+ * loses its class. A step that must keep more maps its error to plain data
+ * inside the step, before the checkpoint.
+ */
+import type { SerializationRecipe } from "@dbos-inc/dbos-sdk";
+import { Err, Ok } from "neverthrow";
+export type Json = string | number | boolean | null | undefined | Json[] | {
+    [key: string]: Json;
+};
+export type EncodedOk = {
+    value?: Json;
+};
+export type EncodedErr = {
+    error?: Json;
+};
+export declare const okRecipe: SerializationRecipe<Ok<unknown, never>, EncodedOk>;
+export declare const errRecipe: SerializationRecipe<Err<never, unknown>, EncodedErr>;

package/dist/runtime/result-serialization.js

@@ -0,0 +1,45 @@
+/**
+ * The DBOS serialization recipes of the neverthrow `Ok` and `Err` classes.
+ *
+ * DBOS saves each workflow input, step output, workflow output, and message
+ * with SuperJSON, and SuperJSON drops the class of an object that it does not
+ * know. Without these recipes a step that returns a `Result` gives back a plain
+ * object with no `Result` methods, on the first run and on each replay alike,
+ * because DBOS hands the body the deserialized value. `launchDbos` registers
+ * the recipes one time, before DBOS launches.
+ *
+ * SuperJSON does not walk the output of a custom recipe, thus each recipe
+ * encodes the value that it holds as JSON itself. An `Error` inside that value
+ * keeps its name and its message only, and a `Result` nested inside the value
+ * loses its class. A step that must keep more maps its error to plain data
+ * inside the step, before the checkpoint.
+ */
+import { Err, Ok, err, ok } from "neverthrow";
+/**
+ * The JSON form of the value inside a `Result`, with the rules of
+ * `JSON.stringify`. An `Error` becomes `{ name, message }`, because
+ * `JSON.stringify` gives `{}` for one. A `bigint` becomes its decimal text,
+ * because `JSON.stringify` throws on one.
+ */
+function toJson(value) {
+    const text = JSON.stringify(value, (_key, v) => {
+        if (v instanceof Error)
+            return { name: v.name, message: v.message };
+        if (typeof v === "bigint")
+            return v.toString();
+        return v;
+    });
+    return text === undefined ? undefined : JSON.parse(text);
+}
+export const okRecipe = {
+    name: "neverthrow.Ok",
+    isApplicable: (v) => v instanceof Ok,
+    serialize: (v) => ({ value: toJson(v.value) }),
+    deserialize: (s) => ok(s.value),
+};
+export const errRecipe = {
+    name: "neverthrow.Err",
+    isApplicable: (v) => v instanceof Err,
+    serialize: (v) => ({ error: toJson(v.error) }),
+    deserialize: (s) => err(s.error),
+};

package/dist/sandbox/client.d.ts

@@ -25,7 +25,10 @@
  * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
  * rule yet, thus a new caller must read this paragraph.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody, ToolchainSource } from "./types.js";
+import type { ResultAsync } from "neverthrow";
+import type { SpawnSession } from "../auth/types.js";
+import type { SandboxError } from "./sandbox-error.js";
+import type { ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxSpec, SubmitExecBody, ToolchainSource } from "./types.js";
 export interface SandboxClient {
     /**
      * The declared owner of the sandbox toolchain, as the client was composed
@@ -40,12 +43,17 @@ export interface SandboxClient {
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the
      * pre-minted `identity` (name + HMAC secret checkpointed by `sandbox.mint`),
-     * stamps ownership labels, waits for `/health`, records the live handle in
+     * stamps the labels, waits for `/health`, records the live handle in
      * the active-sandbox registry, and returns the in-memory `SandboxRef`. A
      * recovery re-run whose machine already exists (the crash window between
      * spawn and checkpoint) **adopts** it rather than leaking a second one.
+     *
+     * Each spawn failure is an `err` value, the refusal of the label hook
+     * (`labels_refused`) included: a spawn path splits the result with
+     * `keepSuspendingRefusal`. Only a defect of the deployment config, or a
+     * throw of the workspace-root resolver, throws, and it fails the workflow.
      */
-    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): Promise<SandboxRef>;
+    createSandbox(session: SpawnSession, spec: SandboxSpec, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
     /**
      * DBOS step (`sandbox.submit-exec.${execId}`). POSTs the command to
      * sandbox-server's `/exec` and returns after the HTTP 202 ack. Does NOT

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

@@ -19,8 +19,9 @@ import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { clearSandboxRef } from "../state/index.js";
 import { type AwaitExecOptions } from "./await-exec.js";
 import type { SandboxClient } from "./client.js";
+import { type MountPlanCoords } from "./mount-plan.js";
 import { type SubmitExecDeps } from "./submit-exec.js";
-import { type CreateSandboxMeta, type FarmSource, type SandboxTransport, type ToolchainSource } from "./types.js";
+import { type FarmSource, type ResolveSandboxLabels, type SandboxTransport, type ToolchainSource } from "./types.js";
 /**
  * Narrow config slice the sandbox factory reads off `Env` — the backend
  * default and the K8s namespace fallback. Composition roots map their
@@ -144,6 +145,8 @@ export interface CreateSandboxClientConfig {
     runtimeClassName?: string;
     /** Override the backend selection — defaults to `env.SANDBOX_BACKEND`. */
     backend?: "docker" | "k8s";
+    /** Absent, a sandbox carries no host labels. */
+    resolveSandboxLabels?: ResolveSandboxLabels;
     /**
      * Optional logger forwarded to the Docker backend so a store degradation
      * (a resolved farm whose `inflexa.lock` vanished or went invalid
@@ -186,7 +189,7 @@ export declare function composeAwaitOptions(base: AwaitExecOptions | undefined,
 export declare function precreateStepTree(deps: {
     resolveWorkspaceRoot: ResolveWorkspaceRoot;
     stepTreeAccess?: "world-writable";
-}, meta: CreateSandboxMeta): Promise<void>;
+}, coords: MountPlanCoords): Promise<void>;
 export declare function createSandboxClient(config: CreateSandboxClientConfig): SandboxClient;
 /** Re-exports so consumers import once from this module. */
 export { clearSandboxRef };

package/dist/sandbox/create-sandbox.js

@@ -13,6 +13,8 @@
  */
 import { chmod, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { ResultAsync, err, okAsync } from "neverthrow";
+import { passGate } from "../lib/hooks.js";
 import { recordSandboxExec } from "../lib/metrics.js";
 import { clampResources } from "../config/resource-limits.js";
 import { tailWritePrefix } from "../workspace/paths.js";
@@ -24,10 +26,10 @@ import { awaitExec } from "./await-exec.js";
 import { createDockerSandboxOps } from "./docker-client.js";
 import { noteExecOutcome, sandboxExecOutcomeOf, summarizeExec } from "./exec-outcome.js";
 import { createK8sSandboxOps } from "./k8s-client.js";
-import { sandboxWriteTail } from "./mount-plan.js";
+import { mountCoordsOf, sandboxWriteTail } from "./mount-plan.js";
 import { SandboxFailure } from "./sandbox-error.js";
 import { submitExec } from "./submit-exec.js";
-import { toPersistedRef } from "./types.js";
+import { toPersistedRef, } from "./types.js";
 /**
  * Assemble `awaitExec`'s options: the liveness probe self-wires from the
  * backend ops (the poll loop's escalation always has its arbiter under the
@@ -58,14 +60,14 @@ export function composeAwaitOptions(base, transport, isAlive) {
  * would not touch them either way. Scoped to the write tree — the
  * read-only mount sources are never re-moded. Exported for tests.
  */
-export async function precreateStepTree(deps, meta) {
-    const write = sandboxWriteTail(meta);
+export async function precreateStepTree(deps, coords) {
+    const write = sandboxWriteTail(coords);
     if (write === undefined)
         return;
     // `tailWritePrefix` (not a raw `join`) so every segment runs through the same
     // id validation the mount builders apply — a crafted tail cannot escape the
     // resolved root.
-    const writeDir = tailWritePrefix({ workspaceRoot: deps.resolveWorkspaceRoot(meta.analysisId), tail: write.tail });
+    const writeDir = tailWritePrefix({ workspaceRoot: deps.resolveWorkspaceRoot(coords.analysisId), tail: write.tail });
     await mkdir(writeDir, { recursive: true });
     await Promise.all(write.subdirs.map((sub) => mkdir(join(writeDir, sub), { recursive: true })));
     if (deps.stepTreeAccess === "world-writable") {
@@ -109,8 +111,8 @@ export function createSandboxClient(config) {
      * unwraps below stay on the plain bridge: they carry a `DbError`.
      */
     const failing = (e) => new SandboxFailure(e);
-    const registerSandbox = async (meta, ref) => {
-        unwrapOrThrow(await setSandboxRef(config.pool, meta.runId, meta.stepId, toPersistedRef(ref), meta.execId ?? null));
+    const registerSandbox = async (session, spec, ref) => {
+        unwrapOrThrow(await setSandboxRef(config.pool, session.runFrame.runId, session.runFrame.stepId, toPersistedRef(ref), spec.execId ?? null));
     };
     const ops = backend === "k8s"
         ? createK8sSandboxOps({
@@ -171,26 +173,50 @@ export function createSandboxClient(config) {
     // One arbiter for both surfaces: the client's `isAlive` method and the
     // poll loop's escalation probe are the same backend inspect.
     const isAlive = async (ref) => unwrapOrThrow((await ops.isAlive(ref)).mapErr(failing));
+    const hostLabelsFor = (session) => {
+        const hook = config.resolveSandboxLabels;
+        if (hook === undefined)
+            return okAsync({});
+        return passGate("resolveSandboxLabels", hook(session)).mapErr((refusal) => ({
+            type: "labels_refused",
+            op: "createSandbox",
+            reason: refusal.reason,
+            suspend: refusal.kind === "suspended",
+        }));
+    };
+    const createSandbox = async (session, spec, identity) => {
+        // The label hook runs first: a refusal makes no step tree and calls no backend.
+        const hostLabels = await hostLabelsFor(session);
+        if (hostLabels.isErr())
+            return err(hostLabels.error);
+        const createFailed = (op) => (cause) => ({
+            type: "container_create_failed",
+            op,
+            sandboxId: identity.sandboxId,
+            cause,
+        });
+        // Every caller must declare resources — a sandbox with no cpu/memory
+        // request is a semantic error, not something to paper over with a
+        // default.
+        if (!spec.resources) {
+            return err(createFailed("createSandbox")(new Error(`createSandbox: ${session.scope.analysisId}/${session.runFrame.runId}/${session.runFrame.stepId} has no resources — every caller must declare cpu/memoryGb`)));
+        }
+        // The config states an engine fact (binds preserve host ownership);
+        // which remediation that fact demands — today, a world-writable step
+        // write tree — is harness-owned and chosen here, not by the embedder.
+        const precreated = await ResultAsync.fromPromise(precreateStepTree({
+            resolveWorkspaceRoot: config.resolveWorkspaceRoot,
+            stepTreeAccess: config.engineBindOwnership === "host-preserved" ? "world-writable" : undefined,
+        }, mountCoordsOf(session, spec)), createFailed("createSandbox.precreateStepTree"));
+        if (precreated.isErr())
+            return err(precreated.error);
+        // Clamp to cluster ceilings so the pod is always quota-admissible.
+        const resources = clampResources(spec.resources, config.resourceLimits);
+        return ops.createSandbox(session, { ...spec, resources }, identity, hostLabels.value);
+    };
     return {
         toolchainSource,
-        createSandbox: async (meta, identity) => {
-            // The config states an engine fact (binds preserve host ownership);
-            // which remediation that fact demands — today, a world-writable step
-            // write tree — is harness-owned and chosen here, not by the embedder.
-            await precreateStepTree({
-                resolveWorkspaceRoot: config.resolveWorkspaceRoot,
-                stepTreeAccess: config.engineBindOwnership === "host-preserved" ? "world-writable" : undefined,
-            }, meta);
-            // Every caller must declare resources — a sandbox with no cpu/memory
-            // request is a semantic error, not something to paper over with a
-            // default (a DBOS replay of a pre-resources workflow input lands here).
-            if (!meta.resources) {
-                throw new Error(`createSandbox: ${meta.analysisId}/${meta.runId}/${meta.stepId} has no resources — every caller must declare cpu/memoryGb`);
-            }
-            // Clamp to cluster ceilings so the pod is always quota-admissible.
-            const resources = clampResources(meta.resources, config.resourceLimits);
-            return unwrapOrThrow((await ops.createSandbox({ ...meta, resources }, identity)).mapErr(failing));
-        },
+        createSandbox: (session, spec, identity) => new ResultAsync(createSandbox(session, spec, identity)),
         submitExec: async (ref, body) => submitExec(ref, body, {
             ...config.submitDeps,
             execStreamByteCap: config.submitDeps?.execStreamByteCap ?? config.execStreamByteCap,