@inflexa-ai/harness 0.37.0 → 0.39.0

package/dist/workflows/metrics.d.ts

@@ -12,11 +12,12 @@
 /**
  * Record one child cancellation. The parent calls this once per
  * `DBOS.cancelWorkflow(childWorkflowId)` in the cascade (fail-fast OR
- * pause). `cause` distinguishes the two so dashboards can split the
- * counter.
+ * suspension). `cause` is `fail_fast`, `external_cancel`, or the reason of
+ * the host for a suspension, carried unread, so dashboards can split the
+ * counter by the reason that the host gave.
  */
 export declare function recordCancelledChild(args: {
-    readonly cause: "fail_fast" | "budget_exceeded" | "external_cancel";
+    readonly cause: string;
 }): void;
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export declare function __resetWorkflowMetricsForTest(): void;

package/dist/workflows/metrics.js

@@ -16,7 +16,7 @@ function getInstruments() {
         const meter = metrics.getMeter("cortex.workflow");
         instruments = {
             cancelledChildren: meter.createCounter("cortex.workflow.parent.cancelled_children", {
-                description: "Children cancelled by the parent's fail-fast or pause cascade",
+                description: "Children cancelled by the parent's fail-fast or suspension cascade",
             }),
         };
     }
@@ -25,8 +25,9 @@ function getInstruments() {
 /**
  * Record one child cancellation. The parent calls this once per
  * `DBOS.cancelWorkflow(childWorkflowId)` in the cascade (fail-fast OR
- * pause). `cause` distinguishes the two so dashboards can split the
- * counter.
+ * suspension). `cause` is `fail_fast`, `external_cancel`, or the reason of
+ * the host for a suspension, carried unread, so dashboards can split the
+ * counter by the reason that the host gave.
  */
 export function recordCancelledChild(args) {
     getInstruments().cancelledChildren.add(1, { cause: args.cause });

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

@@ -9,9 +9,6 @@
  *  2. `createSandbox`       — provision the sandbox; persist its handle.
  *  3. `runAgent`            — the harness agent loop. Every LLM and tool
  *                             call inside is its own durableStep.
- *                             Catches `isBudgetExceeded` and self-cancels
- *                             via `DBOS.cancelWorkflow(self)` to CANCELLED
- *                             (resumable, not ERROR).
  *  4. `generateFileMetadata`— post-step LLM call (chunked, slice-to-length).
  *  5. `generateStepSummary` — post-step LLM call producing `output/summary.md`.
  *  6. `reconcile + register`— write artifact manifest entries to cortex_artifacts.
@@ -22,9 +19,12 @@
  * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
  *                             onto the parent's DBOS stream.
  *
- * The parent owns sibling lifecycle: fail-fast and 402-cascade live on the
- * parent (`executeAnalysis`). This child only owns its own teardown and
- * its own self-cancel on 402.
+ * The parent owns sibling lifecycle: the halt cascade of a suspension lives
+ * on the parent (`executeAnalysis`). This child owns its own teardown and its
+ * own suspension (workflow-suspension spec): a `suspend` error of the agent
+ * loop, or a refusal with the suspend flag of the label gate or the register
+ * gate. The child records the reason on its row, sends the typed suspension on
+ * `CHILD_SUSPENDED_TOPIC`, and self-cancels to CANCELLED (resumable, not ERROR).
  */
 import type { TokenUsageRollup } from "@inflexa-ai/harness/contracts/usage.js";
 import type { Pool } from "pg";
@@ -33,7 +33,7 @@ import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AgentDefinition, LoopMessage } from "../loop/types.js";
 import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
-import { type RunSession } from "../auth/types.js";
+import { type RunSession, type SpawnSession } from "../auth/types.js";
 import type { FileMetadataEntry } from "../execution/artifact-metadata.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
@@ -72,9 +72,9 @@ export interface SandboxStepInput {
     readonly prompt: string;
     /**
      * DBOS workflow id of the parent (`executeAnalysis`). The child uses
-     * this to address the parent for the budget-exceeded side-channel
-     * (`DBOS.send(parent, …, "child-budget-exceeded")`) — the parent's
-     * scheduler-loop classifier relies on it to disambiguate a budget-induced
+     * this to address the parent for its typed suspension
+     * (`DBOS.send(parent, …, CHILD_SUSPENDED_TOPIC)`) — the parent's
+     * scheduler-loop classifier relies on it to disambiguate a suspension
      * self-cancel from an operator-driven sibling cancel (CANCELLED is the
      * same terminal state for both).
      */
@@ -99,7 +99,7 @@ export interface SandboxStepInput {
      * DBOS replay reconstructs it on resume — the body never reads the JWT
      * from `cortex_runs`.
      */
-    readonly runSession: RunSession;
+    readonly runSession: SpawnSession;
 }
 /**
  * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
@@ -114,20 +114,18 @@ export declare const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
 export declare const CAPPED_OUT_EMPTY_REASON = "The step hit its iteration cap with no output files persisted.";
 export type SandboxStepStatus = "complete" | "failed" | "canceled" | "blocked";
 /**
- * DBOS message topic the child uses to notify the parent that it is
- * about to self-cancel because of a 402 budget-exceeded error. The
- * notification fires BEFORE `DBOS.cancelWorkflow(self)` so the parent's
- * concurrent recv accumulator records the child id before the child's
- * terminal state lands. Without it the parent observes
- * `DBOSWorkflowCancelledError` from `getResult` — a generic message that
- * `isBudgetExceeded` does NOT match — and misclassifies the failure as
- * fail-fast, skipping the 402 pause cascade.
+ * DBOS message topic the child uses to tell the parent that it suspends. The
+ * message goes BEFORE `DBOS.cancelWorkflow(self)`, thus the parent's recv
+ * accumulator records the child before the child's terminal state lands.
+ * Without it the parent observes only `DBOSWorkflowCancelledError` from
+ * `getResult`, and it cannot tell a suspension from a cancel.
  */
-export declare const BUDGET_EXCEEDED_TOPIC = "child-budget-exceeded";
-export interface BudgetExceededNotification {
+export declare const CHILD_SUSPENDED_TOPIC = "child-suspended";
+export interface ChildSuspended {
+    readonly kind: "suspended";
     readonly childWorkflowId: string;
     readonly stepId: string;
-    readonly error: string;
+    readonly reason: string;
 }
 export interface SandboxStepResult {
     readonly status: SandboxStepStatus;
@@ -238,13 +236,6 @@ export interface SandboxStepDeps {
     /** Write-side embedder for the post-step vector index. */
     readonly embedding: EmbeddingProvider;
     readonly sandboxClient: SandboxClient;
-    /**
-     * Host-supplied labels for this step's sandbox pod, resolved under the
-     * step's session. The map is opaque to the harness: it stamps each entry
-     * and interprets none of it. Absent in a wiring that attributes nothing —
-     * the pod then carries the harness's own labels only.
-     */
-    readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
     /**
      * External artifact registration + sync seam. The harness's post-step pipeline
      * registers each step's outputs through it (filesystem index in the

package/dist/workflows/sandbox-step.js

@@ -9,9 +9,6 @@
  *  2. `createSandbox`       — provision the sandbox; persist its handle.
  *  3. `runAgent`            — the harness agent loop. Every LLM and tool
  *                             call inside is its own durableStep.
- *                             Catches `isBudgetExceeded` and self-cancels
- *                             via `DBOS.cancelWorkflow(self)` to CANCELLED
- *                             (resumable, not ERROR).
  *  4. `generateFileMetadata`— post-step LLM call (chunked, slice-to-length).
  *  5. `generateStepSummary` — post-step LLM call producing `output/summary.md`.
  *  6. `reconcile + register`— write artifact manifest entries to cortex_artifacts.
@@ -22,16 +19,19 @@
  * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
  *                             onto the parent's DBOS stream.
  *
- * The parent owns sibling lifecycle: fail-fast and 402-cascade live on the
- * parent (`executeAnalysis`). This child only owns its own teardown and
- * its own self-cancel on 402.
+ * The parent owns sibling lifecycle: the halt cascade of a suspension lives
+ * on the parent (`executeAnalysis`). This child owns its own teardown and its
+ * own suspension (workflow-suspension spec): a `suspend` error of the agent
+ * loop, or a refusal with the suspend flag of the label gate or the register
+ * gate. The child records the reason on its row, sends the typed suspension on
+ * `CHILD_SUSPENDED_TOPIC`, and self-cancels to CANCELLED (resumable, not ERROR).
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { insertStepExecution, updateStepExecution } from "../state/index.js";
 import { recordStepCompleted } from "../lib/metrics.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
 import { durableStep } from "../loop/run-step.js";
 import { lastExecOutcome } from "../sandbox/exec-outcome.js";
@@ -39,10 +39,12 @@ import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, step
 import { createDetailResolver } from "../tools/detail-resolver.js";
 import { forSubAgent } from "../auth/types.js";
 import { walkStepArtifacts } from "../execution/post-step.js";
-import { collectStepOutputs, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
+import { collectStepOutputs, describeStepRegistrationFailure, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
 import { ProvenanceCollector } from "../provenance/collector.js";
 import { createBlockerHolder } from "../tools/sandbox/report-blocker.js";
+import { cancelSelf, suspensionOfFailure, suspensionOfRefusal, suspensionOfSpawnRefusal } from "./suspension.js";
 /**
  * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
  * declare it explicitly.
@@ -55,16 +57,13 @@ export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
  */
 export const CAPPED_OUT_EMPTY_REASON = "The step hit its iteration cap with no output files persisted.";
 /**
- * DBOS message topic the child uses to notify the parent that it is
- * about to self-cancel because of a 402 budget-exceeded error. The
- * notification fires BEFORE `DBOS.cancelWorkflow(self)` so the parent's
- * concurrent recv accumulator records the child id before the child's
- * terminal state lands. Without it the parent observes
- * `DBOSWorkflowCancelledError` from `getResult` — a generic message that
- * `isBudgetExceeded` does NOT match — and misclassifies the failure as
- * fail-fast, skipping the 402 pause cascade.
+ * DBOS message topic the child uses to tell the parent that it suspends. The
+ * message goes BEFORE `DBOS.cancelWorkflow(self)`, thus the parent's recv
+ * accumulator records the child before the child's terminal state lands.
+ * Without it the parent observes only `DBOSWorkflowCancelledError` from
+ * `getResult`, and it cannot tell a suspension from a cancel.
  */
-export const BUDGET_EXCEEDED_TOPIC = "child-budget-exceeded";
+export const CHILD_SUSPENDED_TOPIC = "child-suspended";
 // ── Helpers ───────────────────────────────────────────────────────────
 function nextFunctionIdFactory() {
     let n = 0;
@@ -144,6 +143,24 @@ export async function runSandboxStepBody(input, deps) {
             childWorkflowId,
         }));
     }, { name: "mark-running" });
+    // The sandbox, if one stands, stays up for the resume. The steps run only on
+    // this path, and a replay takes the same path from the same checkpoints.
+    const suspendStep = async (suspension) => {
+        const durationMs = (await DBOS.now()) - startedAt;
+        await DBOS.runStep(async () => {
+            unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
+                status: "canceled",
+                durationMs,
+                error: suspension.reason,
+                attempts: 1,
+                lastErrorClass: suspension.reason,
+            }));
+            recordStepCompleted({ agentId: input.agentId, status: "canceled", durationMs });
+        }, { name: "mark-suspended" });
+        const message = { kind: "suspended", childWorkflowId, stepId: input.stepId, reason: suspension.reason };
+        await DBOS.runStep(() => DBOS.send(input.parentWorkflowId, message, CHILD_SUSPENDED_TOPIC), { name: "notify-parent-suspended" });
+        return cancelSelf("self-cancel-suspended");
+    };
     // Stamp the sandbox agent's id into provenance so loop events carry
     // `source.agentId === input.agentId` (the parent's RunSession still reads
     // "conversation-agent"). `run-agent.ts` builds source from
@@ -159,34 +176,19 @@ export async function runSandboxStepBody(input, deps) {
     const identity = await DBOS.runStep(() => Promise.resolve(mintSandboxIdentity(input.runId)), { name: "sandbox.mint" });
     // (2b) sandbox.create — spawn (or adopt) the machine under the minted
     // identity. The handle (secret included) is cached so recovery picks the
-    // same machine back up without re-provisioning. Pod-label resolution lives
-    // INSIDE this step (not as its own step) so the child's step sequence is
-    // unchanged — in-flight workflows resumed across a deploy replay cleanly.
-    const sandboxMeta = {
-        runId: input.runId,
-        stepId: input.stepId,
-        analysisId: input.analysisId,
+    // same machine back up without re-provisioning.
+    const sandboxSpec = {
         childWorkflowId,
         image: input.image,
         extraEnv: input.extraEnv,
         resources: input.resources,
     };
-    const sandbox = await DBOS.runStep(async () => {
-        let podLabels;
-        if (deps.resolvePodLabels) {
-            try {
-                podLabels = await deps.resolvePodLabels(session);
-            }
-            catch (err) {
-                logger.warn("pod-label resolution failed", { analysisId: input.analysisId, ...logger.errorFields(err) });
-            }
-            // A wired resolver that yields nothing is the one loud case: the
-            // host asked for attribution and the pod spawns without it.
-            if (!podLabels || Object.keys(podLabels).length === 0)
-                logger.warn("sandbox spawned with no pod labels", { analysisId: input.analysisId });
-        }
-        return deps.sandboxClient.createSandbox({ ...sandboxMeta, podLabels }, identity);
-    }, { name: "sandbox.create" });
+    const spawned = await DBOS.runStep(async () => keepSuspendingRefusal(await deps.sandboxClient.createSandbox(session, sandboxSpec, identity)), {
+        name: "sandbox.create",
+    });
+    if (spawned.isErr())
+        return suspendStep(suspensionOfSpawnRefusal(spawned.error));
+    const sandbox = spawned.value;
     // Recovery path: re-check `isAlive` on the persisted ref before continuing.
     // A classified-dead sandbox triggers a fresh `createSandbox` (task 4.6).
     // For first execution this is a cheap no-op; on replay it's the seam
@@ -371,52 +373,9 @@ export async function runSandboxStepBody(input, deps) {
         stepUsage = agentResult.finish.usage;
     }
     catch (err) {
-        if (isBudgetExceeded(err)) {
-            // Notify the parent BEFORE self-cancel — DBOSWorkflowCancelledError
-            // surfaced by `getResult` carries a generic message that
-            // `isBudgetExceeded` cannot match, so without this side-channel the
-            // parent classifier falls through to fail-fast and the 402 pause
-            // cascade never fires. Wrapped in `DBOS.runStep` for replay
-            // idempotency (DBOS persists the send under (workflowID, function_id),
-            // a recovered child does not re-send). Failure to send is logged but
-            // swallowed: the worst case is the parent misclassifies the cancel
-            // as fail-fast, which is the pre-fix behaviour and still safe.
-            const errMsg = err instanceof Error ? err.message : String(err);
-            const notification = {
-                childWorkflowId,
-                stepId: input.stepId,
-                error: errMsg,
-            };
-            try {
-                await DBOS.runStep(() => DBOS.send(input.parentWorkflowId, notification, BUDGET_EXCEEDED_TOPIC), { name: "notify-parent-budget-exceeded" });
-            }
-            catch (sendErr) {
-                logger.warn("notify-parent-budget-exceeded failed (non-fatal)", {
-                    ...logger.errorFields(sendErr),
-                });
-            }
-            // Self-cancel to CANCELLED so the parent's `getResult` observes the
-            // cancellation and triggers the 402 pause cascade. ERROR is NOT
-            // resumable (NOTES #3); CANCELLED is what `resumeWorkflow` reads.
-            // The subsequent runStep flips the cortex_step_executions row to
-            // canceled and raises `DBOSWorkflowCancelledError` — nothing past
-            // that line executes. The parent's classifier reads the budget
-            // notification from the side-channel set populated above and
-            // observes the cancel terminal state via `getResult`.
-            await DBOS.cancelWorkflow(childWorkflowId);
-            const durationMs = (await DBOS.now()) - startedAt;
-            await DBOS.runStep(async () => {
-                unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
-                    status: "canceled",
-                    durationMs,
-                    error: "budget_exceeded",
-                    attempts: 1,
-                    lastErrorClass: "budget_exceeded",
-                }));
-            }, { name: "mark-canceled" });
-            // Unreachable — the runStep above raises DBOSWorkflowCancelledError.
-            throw new Error("unreachable: mark-canceled did not raise", { cause: err });
-        }
+        const suspension = suspensionOfFailure(err);
+        if (suspension !== undefined)
+            return suspendStep(suspension);
         // Non-resumable failure — tear down, mark failed (scrubbed), re-raise so
         // the parent's `getResult` sees ERROR and the fail-fast cascade fires.
         // `failStep` always throws; the outer `throw` is for control-flow analysis.
@@ -524,67 +483,52 @@ export async function runSandboxStepBody(input, deps) {
     const summary = await safeRunValue(logger, () => DBOS.runStep(() => generateStepSummaryAndWrite(deps, postCtx, manifest), {
         name: "post-step.generate-step-summary",
     }), "post-step.summary", undefined);
-    // Lineage attestation (registration + sync) is fail-fast (see the artifact-manifest spec): unlike
+    // Lineage attestation (registration) is fail-fast (see the artifact-manifest spec): unlike
     // the best-effort enrichment stages, a failure here orphans the step's real
     // outputs, so it fails the step loudly instead of finishing green. Transient
-    // managed-root errors are already retried in the client, so anything thrown here is
+    // managed-root errors are already retried in the client, so a failure here is
     // persistent — tear down, mark failed, and re-raise so the parent's fail-fast
-    // cascade fires (mirrors the agent-loop failure path). The two operations are
-    // sequenced independently: byte-sync is attempted on both arms, so a rejected
-    // registration still uploads the bytes of whatever DID register.
+    // cascade fires (mirrors the agent-loop failure path). The byte-sync is
+    // attempted after the registration on every arm, so a rejected registration
+    // still uploads the bytes of whatever DID register: the rows that registered
+    // carry `artifact_id` with `file_id` still NULL, which is exactly what
+    // `queryUnsyncedStepArtifacts` selects, and a row that never registered is not
+    // selected, so the sync stays idempotent under re-execution.
     await emitActivity("persisting", "Registering artifacts");
     // A bare call, deliberately not `DBOS.runStep`-wrapped: it is reachable from
     // two arms below, and a checkpointed step reached from a conditional arm
     // would shift the body's function-ID sequence between the two paths (see the
-    // harness-durable-runtime spec).
-    const syncStepArtifacts = () => deps.artifactRegistry.sync({
+    // harness-durable-runtime spec). The sync is a notice: it never displaces a
+    // registration failure as the cause of one.
+    const syncStepArtifacts = () => deliverNotice(logger.named("post-step.sync"), "ArtifactRegistry.sync", deps.artifactRegistry.sync({
         resourceId: input.analysisId,
         runId: input.runId,
         stepId: input.stepId,
-    }, session);
-    let reconciledManifest;
+    }, session));
+    let registered;
     try {
-        reconciledManifest = await reconcileAndRegisterStepArtifacts(deps, postCtx, manifest);
-    }
-    catch (registrationErr) {
-        // Registration and byte-sync are independent, and a registry rejection is
-        // partial: the rows that DID register carry `artifact_id` with `file_id`
-        // still NULL, which is exactly what `queryUnsyncedStepArtifacts` selects.
-        // Syncing anyway uploads their bytes (rows that never registered are not
-        // selected, so this stays idempotent under re-execution); skipping it is
-        // what strands them registered-but-byteless.
-        try {
-            await syncStepArtifacts();
-        }
-        catch (syncErr) {
-            // A cancellation is control-flow, not a sync failure — re-raise it
-            // verbatim, as every other stage in this body does. Any real failure
-            // is swallowed so it cannot displace the registration rejection as the
-            // step's cause; this record is the only account of it.
-            if (syncErr instanceof DBOSErrors.DBOSWorkflowCancelledError)
-                throw syncErr;
-            logger.named("post-step.sync").warn("failed after a registration rejection (non-fatal)", logger.errorFields(syncErr));
-        }
-        throw await failStep("lineage_attestation", registrationErr);
+        registered = await reconcileAndRegisterStepArtifacts(deps, postCtx, manifest);
     }
-    try {
+    catch (attestationErr) {
+        if (attestationErr instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw attestationErr;
         await syncStepArtifacts();
+        throw await failStep("lineage_attestation", attestationErr);
     }
-    catch (err) {
-        throw await failStep("lineage_attestation", err);
+    await syncStepArtifacts();
+    if (registered.isErr()) {
+        const refused = registered.error.kind === "refused" ? suspensionOfRefusal(registered.error.refusal) : undefined;
+        if (refused !== undefined)
+            return suspendStep(refused);
+        throw await failStep("lineage_attestation", new Error(describeStepRegistrationFailure(registered.error)));
     }
+    const reconciledManifest = registered.value;
     const postArtifacts = {
         metadataEntries,
         summary,
         reconciledManifest,
     };
-    let stepOutputs;
-    try {
-        stepOutputs = collectStepOutputs(postCtx, postArtifacts);
-    }
-    catch (err) {
-        logger.warn("post-step.collect failed (non-fatal)", logger.errorFields(err));
-    }
+    const stepOutputs = collectStepOutputs(postCtx, postArtifacts);
     await emitActivity("indexing", "Indexing outputs for search");
     await safeRun(logger, () => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
     // (9) teardown — destroy sandbox + clear sandbox_ref.

package/dist/workflows/suspension.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The suspension of work (workflow-suspension spec).
+ *
+ * A suspension starts only from a model request that fails with a `suspend`
+ * error, or from a gate that refuses with the suspend flag. The harness carries
+ * the reason of the host as it is and never reads it: no path compares a
+ * reason to a value, and no path reads the text of an error message.
+ *
+ * The owner of the result of a workflow selects the mechanism. A durable owner
+ * (`executeAnalysis`, `sandbox-step`, `data-profile`) records the reason in its
+ * stored state and ends in the DBOS state `CANCELLED`, which `resumeWorkflow`
+ * reads. A workflow with a live caller (`derive-table-exec`, `extract-values`)
+ * returns the suspension as the `err` of its result. A suspension of an
+ * analysis run or of a data profile marks the analysis through
+ * `suspendAnalysis` (`state/analyses.ts`). A workflow with a live caller does
+ * not mark it: the conversation agent reads the suspension as a tool result.
+ */
+import type { GateRefusal } from "../lib/hooks.js";
+import type { SuspendingRefusal } from "../sandbox/sandbox-error.js";
+/** Plain data, thus it crosses a DBOS checkpoint as it is. */
+export interface Suspension {
+    readonly kind: "suspended";
+    readonly reason: string;
+}
+export declare function suspensionOfFailure(err: unknown): Suspension | undefined;
+export declare function suspensionOfRefusal(refusal: GateRefusal): Suspension | undefined;
+export declare function suspensionOfSpawnRefusal(refusal: SuspendingRefusal): Suspension;
+/**
+ * The cancel lands at the next DBOS operation, thus the named step raises
+ * `DBOSWorkflowCancelledError` and nothing after it runs.
+ */
+export declare function cancelSelf(stepName: string): Promise<never>;

package/dist/workflows/suspension.js

@@ -0,0 +1,38 @@
+/**
+ * The suspension of work (workflow-suspension spec).
+ *
+ * A suspension starts only from a model request that fails with a `suspend`
+ * error, or from a gate that refuses with the suspend flag. The harness carries
+ * the reason of the host as it is and never reads it: no path compares a
+ * reason to a value, and no path reads the text of an error message.
+ *
+ * The owner of the result of a workflow selects the mechanism. A durable owner
+ * (`executeAnalysis`, `sandbox-step`, `data-profile`) records the reason in its
+ * stored state and ends in the DBOS state `CANCELLED`, which `resumeWorkflow`
+ * reads. A workflow with a live caller (`derive-table-exec`, `extract-values`)
+ * returns the suspension as the `err` of its result. A suspension of an
+ * analysis run or of a data profile marks the analysis through
+ * `suspendAnalysis` (`state/analyses.ts`). A workflow with a live caller does
+ * not mark it: the conversation agent reads the suspension as a tool result.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { findSuspendError } from "../providers/errors.js";
+export function suspensionOfFailure(err) {
+    const found = findSuspendError(err);
+    return found === undefined ? undefined : { kind: "suspended", reason: found.reason };
+}
+export function suspensionOfRefusal(refusal) {
+    return refusal.kind === "suspended" ? { kind: "suspended", reason: refusal.reason } : undefined;
+}
+export function suspensionOfSpawnRefusal(refusal) {
+    return { kind: "suspended", reason: refusal.reason };
+}
+/**
+ * The cancel lands at the next DBOS operation, thus the named step raises
+ * `DBOSWorkflowCancelledError` and nothing after it runs.
+ */
+export async function cancelSelf(stepName) {
+    await DBOS.cancelWorkflow(DBOS.workflowID);
+    await DBOS.runStep(async () => undefined, { name: stepName });
+    throw new Error(`unreachable: ${stepName} did not raise the cancellation`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.37.0",
+    "version": "0.39.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",

package/dist/billing/noop-resolver.d.ts

@@ -1,6 +0,0 @@
-import type { ResolveBilling } from "./resolver.js";
-/**
- * Local/OSS billing resolver: resolves to an empty header map. No upstream
- * call, no credential reads. Wire calls carry no attribution headers.
- */
-export declare function createNoopBillingResolver(): ResolveBilling;

package/dist/billing/noop-resolver.js

@@ -1,7 +0,0 @@
-/**
- * Local/OSS billing resolver: resolves to an empty header map. No upstream
- * call, no credential reads. Wire calls carry no attribution headers.
- */
-export function createNoopBillingResolver() {
-    return async () => ({});
-}

package/dist/billing/resolver.d.ts

@@ -1,64 +0,0 @@
-/**
- * Billing attribution seam.
- *
- * Defines the `ResolveBilling` contract the provider calls at the
- * LLM/embedding call site, plus the session view and fetcher types a
- * concrete resolver implements. The provider calls `resolveBilling(session)`
- * just before the wire call; read-only routes never call it, so they never
- * incur a billing round-trip.
- *
- * This module is the vendor-neutral seam: it declares types only. A concrete
- * resolver (managed/upstream-backed or noop) supplies the fetch + assembly
- * behavior behind the `ResolveBilling` function type.
- */
-import type { AuthContext, BillingSessionView, Credential, ResourceCoordinates } from "../auth/types.js";
-export type BillingMap = Record<string, string>;
-/** Final wire-format header map sent to the upstream gateway. */
-export type BillingHeaders = Record<string, string>;
-/**
- * Result of a single billing-attribution fetch. The seam's own type — a
- * concrete resolver's richer result (e.g. a generic upstream envelope)
- * structurally satisfies it. The failure branch carries what the resolver
- * needs to raise a `BillingResolutionError`.
- */
-export type BillingFetchResult = {
-    ok: true;
-    data: BillingMap;
-} | {
-    ok: false;
-    status: number;
-    error: {
-        error: string;
-        message: string;
-    };
-};
-/**
- * The minimal session view a resolver reads. The cached map is keyed by
- * `(user, resourceType, resourceId)` (from `identity`/`scope` on
- * `BillingSessionView`); header assembly additionally consumes
- * `provenance`/`runFrame` (per-call). The fetch resolves the credential
- * + org via `getAuth(session)`, so only the opaque `auth` is needed here —
- * `AgentSession` structurally satisfies it.
- */
-export interface ResolvableSession extends BillingSessionView {
-    readonly auth: AuthContext;
-}
-/**
- * Resolve the FINAL wire headers at the call site. The raw attribution map is
- * fetched once per `(user, resource)` and cached; the per-call identity tags
- * (`agentId`/`runId`/`stepId`) vary within that key, so header assembly runs
- * POST-CACHE on every call against the live `session` — assembled headers are
- * never cached.
- */
-export type ResolveBilling = (session: ResolvableSession) => Promise<BillingHeaders>;
-/**
- * The upstream call seam — overridable in tests with a fake. A concrete
- * resolver resolves the attribution map for the given credential/org/coords.
- */
-export type BillingFetcher = (credential: Credential, orgId: string, coords: ResourceCoordinates) => Promise<BillingFetchResult>;
-/** A billing-resolution failure (e.g. 403/404). Fails the LLM call. */
-export declare class BillingResolutionError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(status: number, code: string, message: string);
-}

package/dist/billing/resolver.js

@@ -1,24 +0,0 @@
-/**
- * Billing attribution seam.
- *
- * Defines the `ResolveBilling` contract the provider calls at the
- * LLM/embedding call site, plus the session view and fetcher types a
- * concrete resolver implements. The provider calls `resolveBilling(session)`
- * just before the wire call; read-only routes never call it, so they never
- * incur a billing round-trip.
- *
- * This module is the vendor-neutral seam: it declares types only. A concrete
- * resolver (managed/upstream-backed or noop) supplies the fetch + assembly
- * behavior behind the `ResolveBilling` function type.
- */
-/** A billing-resolution failure (e.g. 403/404). Fails the LLM call. */
-export class BillingResolutionError extends Error {
-    status;
-    code;
-    constructor(status, code, message) {
-        super(`Billing resolution failed (${status} ${code}): ${message}`);
-        this.status = status;
-        this.code = code;
-        this.name = "BillingResolutionError";
-    }
-}