@inflexa-ai/harness 0.37.0 → 0.39.0

package/dist/execution/post-step-pipeline.js

@@ -11,6 +11,7 @@
  * fail-fast vs. best-effort. This module owns only the stage bodies.
  */
 import { join } from "node:path";
+import { err, ok } from "neverthrow";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
@@ -92,14 +93,18 @@ export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
     }
     return summary;
 }
+export function describeStepRegistrationFailure(failure) {
+    return failure.kind === "refused" ? `the artifact registry refused the registration: ${failure.refusal.reason}` : failure.message;
+}
 /**
  * Reconcile the manifest against disk (drop phantoms, rehash) and register the
  * survivors with the local ledger + the injected `ArtifactRegistry`. Fail-fast
  * (see the artifact-manifest spec): `externalFailed` counts only the terminal
  * rejections — a rejected output whose bytes exist nowhere but the step tree,
  * plus anything rejected as a consequence of one — so a non-zero count means
- * real outputs went unregistered, and it throws with the per-file detail (the
- * OSS filesystem registry returns `externalFailed: 0`, so it never trips).
+ * real outputs went unregistered, and the `err` carries the per-file detail (the
+ * OSS filesystem registry returns `externalFailed: 0`, so it never trips). A
+ * refusal of the `register` gate is the other `err`.
  * Returns the reconciled manifest.
  */
 export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest) {
@@ -115,14 +120,17 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         ...(deps.logger ? { logger: deps.logger } : {}),
     });
     if (reconciled.manifest.length === 0)
-        return reconciled.manifest;
-    const reg = await registerStepArtifacts(deps.pool, deps.artifactRegistry, {
+        return ok(reconciled.manifest);
+    const registered = await registerStepArtifacts(deps.pool, deps.artifactRegistry, {
         resourceId: input.analysisId,
         runId: input.runId,
         stepId: input.stepId,
         artifacts: reconciled.manifest,
         collector: lineageCollector,
     }, session, deps.logger);
+    if (registered.isErr())
+        return err({ kind: "refused", refusal: registered.error });
+    const reg = registered.value;
     if (reg.externalFailed > 0) {
         // The registry commits per leaf and per activity, so accepted and rejected
         // rows arriving together is ordinary and `externalRegistered` is what
@@ -137,7 +145,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
             `${reg.externalFailed} terminal rejection(s), ${reg.externalRegistered}/${reg.localCount} local artifact(s) registered` +
             (noneRegistered ? " (nothing in this batch registered)" : "") +
             (detail ? `\n  ${detail}` : "");
-        // Logged as fields as well as thrown: the throw reaches `failStep` as one
+        // Logged as fields as well as returned: the failure reaches `failStep` as one
         // opaque string, so the per-path rejections are only queryable from here.
         // This is what distinguishes a registry rejection from the attestation
         // throws in `reconcileManifestWithDisk` when a step dies.
@@ -150,9 +158,9 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
             noneRegistered,
             failures: reg.failureDetails,
         });
-        throw new Error(msg);
+        return err({ kind: "rejected", message: msg });
     }
-    return reconciled.manifest;
+    return ok(reconciled.manifest);
 }
 /**
  * Vector-index the threaded file descriptions + the step summary into the
@@ -212,7 +220,12 @@ export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
     let indexed = 0;
     let failed = 0;
     for (const entry of liveMetadata) {
-        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, { text: entry.description, type: "output", ...entry.metadata, path: entry.dbPath });
+        const ok = await indexOne(`/${input.analysisId}/${entry.dbPath}`, entry.description, {
+            text: entry.description,
+            type: "output",
+            ...entry.metadata,
+            path: entry.dbPath,
+        });
         if (ok)
             indexed++;
         else

package/dist/execution/run-authorizer.d.ts

@@ -14,7 +14,9 @@
  * Mirrors the `SessionPagePublisher` seam: a narrow interface in the harness, the managed
  * realization injected at the composition root.
  */
+import type { ResultAsync } from "neverthrow";
 import type { AuthContext, Provenance, RunFrame, RunSession, Scope } from "../auth/types.js";
+import type { GateFailure, NoticeFailure } from "../lib/hooks.js";
 /**
  * Locates a run credential when no `RunAuthorization` exists: the persisted
  * jti from `cortex_runs` plus the revoking caller's opaque `auth` — the sole
@@ -48,8 +50,8 @@ export interface RunAuthorization {
  * path (a no-op for reused or local authorizations).
  */
 export interface RunAuthorizer {
-    authorize(input: AuthorizeRunInput): Promise<RunAuthorization>;
-    revoke(authorization: RunAuthorization, reason: string): Promise<void>;
+    authorize(input: AuthorizeRunInput): ResultAsync<RunAuthorization, GateFailure>;
+    revoke(authorization: RunAuthorization, reason: string): ResultAsync<void, NoticeFailure>;
     /**
      * Out-of-band revocation for paths holding no `RunAuthorization`. Normal
      * terminal paths use `revoke(authorization, reason)` under the run
@@ -57,5 +59,5 @@ export interface RunAuthorizer {
      * credential's JWT was never persisted and only its jti survives on
      * `cortex_runs`. Local/OSS authorizers no-op — they mint no jti.
      */
-    revokeByJti(ref: RevokeByJtiRef, reason: string): Promise<void>;
+    revokeByJti(ref: RevokeByJtiRef, reason: string): ResultAsync<void, NoticeFailure>;
 }

package/dist/execution/run-canceler.js

@@ -18,6 +18,7 @@
  * terminal frame read-side.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice } from "../lib/hooks.js";
 import { elapsedSinceIso, recordRunCompleted, recordStepCompleted } from "../lib/metrics.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { markRunCanceledIfActive, queryRun } from "../state/runs.js";
@@ -113,26 +114,9 @@ export function createRunCanceler(deps) {
             catch (err) {
                 logger.error("pending-step sweep failed", { runId, ...logger.errorFields(err) });
             }
-            // Best-effort: the billing authority self-heals (defensive open + stale
-            // reaper), so a failed close loses attribution only.
-            let charge = false;
-            try {
-                await runCharge.close({ analysisId: row.analysisId, runId, reason: "canceled", session });
-                charge = true;
-            }
-            catch (err) {
-                logger.error("running-charge close failed", { runId, ...logger.errorFields(err) });
-            }
-            let mandate = row.mandateJti === null;
-            if (row.mandateJti !== null) {
-                try {
-                    await runAuthorizer.revokeByJti({ jti: row.mandateJti, auth: session.auth }, EXTERNAL_CANCEL_REASON);
-                    mandate = true;
-                }
-                catch (err) {
-                    logger.error("mandate revoke failed", { runId, jti: row.mandateJti, ...logger.errorFields(err) });
-                }
-            }
+            const charge = await deliverNotice(logger.with({ runId }), "RunCharge.close", runCharge.close({ analysisId: row.analysisId, runId, outcome: { kind: "canceled" }, session }));
+            const mandate = row.mandateJti === null ||
+                (await deliverNotice(logger.with({ runId, jti: row.mandateJti }), "RunAuthorizer.revokeByJti", runAuthorizer.revokeByJti({ jti: row.mandateJti, auth: session.auth }, EXTERNAL_CANCEL_REASON)));
             // No transition means the run reached a terminal state on its own (or the
             // write failed) — report the row as it stands rather than claiming `canceled`.
             let finalStatus = "canceled";

package/dist/index.d.ts

@@ -24,10 +24,10 @@ export type { ConversationAgentDeps } from "./agents/conversation-agent.js";
 export type { BioToolKeys } from "./tools/bio/keys.js";
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
 export type { RunAuthorizer, AuthorizeRunInput, RunAuthorization, RevokeByJtiRef } from "./execution/run-authorizer.js";
-export { createNoopBillingResolver } from "./billing/noop-resolver.js";
-export type { ResolveBilling, ResolvableSession, BillingMap, BillingHeaders, BillingFetchResult } from "./billing/resolver.js";
+export type { GateFailure, NoticeFailure } from "./lib/hooks.js";
+export type { RequestHeaders, ResolveRequestHeaders } from "./providers/request-headers.js";
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
-export type { RunCharge } from "./billing/run-charge.js";
+export type { RunCharge, RunChargeOutcome } from "./billing/run-charge.js";
 export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 export type { UsageRecorder, LlmUsageRecord } from "./billing/usage-recorder.js";
 export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.js";
@@ -35,7 +35,7 @@ export type { ArtifactRegistry, ArtifactRegistrationInput, ArtifactSyncInput, Ex
 export type { ArtifactManifestEntry } from "./schemas/artifact-manifest.js";
 export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
-export type { MakeSessionPagePublisher, SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
+export type { MakeSessionPagePublisher, SessionPageGrant, SessionPageMintFailure, SessionPagePublisher, } from "./tools/report-session/session-page-publisher.js";
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
 export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";
@@ -63,12 +63,12 @@ export type { RunAgentOptions, RunAgentResult, AgentFinish } from "./loop/run-ag
 export type { AgentDefinition, RunStep, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
 export { passthroughStep } from "./loop/run-step.js";
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
-export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, } from "./auth/types.js";
+export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, HookSessionView, ResolvableSession, } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
 export { createAnthropicProvider } from "./providers/anthropic.js";
 export type { AnthropicProviderDeps } from "./providers/anthropic.js";
 export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
-export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } from "./providers/ai-sdk.js";
+export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps, ProviderHostPolicy } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
 export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
@@ -76,6 +76,10 @@ export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakp
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
+export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
+export type { SuspendOn } from "./providers/errors.js";
+export { suspensionOfFailure } from "./workflows/suspension.js";
+export type { Suspension } from "./workflows/suspension.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
@@ -137,8 +141,10 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
-export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
-export type { SandboxError } from "./sandbox/sandbox-error.js";
+export type { ResolveSandboxLabels, SandboxLabels, SandboxSpec } from "./sandbox/types.js";
+export type { SpawnSession } from "./auth/types.js";
+export { describeSandboxError, keepSuspendingRefusal, SandboxFailure } from "./sandbox/sandbox-error.js";
+export type { SandboxError, SuspendingRefusal } from "./sandbox/sandbox-error.js";
 export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
 export { formatQuery, identityAddress, identityKey, identityOf, parseIdentityKey, parseQuery, pythonIdentity, resolveQuery, rIdentity, } from "./sandbox/package-identity.js";
 export type { PackageIdentity, PackageQuery, ParseQueryError, PoolIndex, QueryResolution, Track } from "./sandbox/package-identity.js";

package/dist/index.js

@@ -29,13 +29,11 @@ export { bootHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
 // Seam: run authorization.
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
-// Seam: billing resolution.
-export { createNoopBillingResolver } from "./billing/noop-resolver.js";
 // Seam: run-level billing bracket.
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
-// Seam: per-call LLM usage accounting. `record` is fire-and-forget — the loop
-// neither awaits nor guards it, so a realization must not throw and must not
-// block. Wired as the optional `usageRecorder` of `assembleCoreRuntime`;
+// Seam: per-call LLM usage accounting. `record` is a notice: the loop does not
+// wait for its result, and it logs the reason of an err when the result
+// arrives. Wired as the optional `usageRecorder` of `assembleCoreRuntime`;
 // unwired, every call is dropped by `createNoopUsageRecorder`.
 export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 // Seam: artifact registration.
@@ -135,6 +133,12 @@ export { DEFAULT_REASONING } from "./providers/reasoning.js";
 // directly needs: `chatStream` throws a `ProviderError` value (a plain object,
 // not an `Error`), so a `catch` recognizes it by shape, not `instanceof`.
 export { toProviderError, isProviderError } from "./providers/errors.js";
+// The suspend map of a provider: an HTTP status to the suspend reason of the
+// host. A map from the host replaces `DEFAULT_SUSPEND_ON`, which holds `402`.
+export { DEFAULT_SUSPEND_ON } from "./providers/errors.js";
+// The suspension of work. A host reads the suspend reason of a failed chat turn
+// with `suspensionOfFailure`, by the kind of the error, never by its text.
+export { suspensionOfFailure } from "./workflows/suspension.js";
 // `createStreamingChat` wraps a `ChatProvider` as a streaming `AgentChat` (the
 // type `runAgent`'s `provider` option takes): its `chat` drives the provider's
 // `chatStream` and forwards each text delta to `onText`, so a same-process host
@@ -248,7 +252,9 @@ export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 // The throw of the client seam. An embedder matches the class and reads the
 // typed variant on `error`, instead of a string match on the message.
-export { describeSandboxError, SandboxFailure } from "./sandbox/sandbox-error.js";
+// `createSandbox` gives each failure as an `err`, and `keepSuspendingRefusal`
+// keeps a refusal of the label hook with the suspend flag as a value and throws each other failure.
+export { describeSandboxError, keepSuspendingRefusal, SandboxFailure } from "./sandbox/sandbox-error.js";
 // The identity of a package, the query that asks for one, and the resolution
 // between the two. An embedder reads `by_name` of the dependency graph with
 // these, thus the host lookup, the census, and the graph key never disagree on

package/dist/lib/hooks.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two kinds of host hook: a gate and a notice.
+ *
+ * A gate gives a value or a permission that the harness must have before it
+ * can continue an operation. A notice reports a fact after the operation. The
+ * type of each hook shows its kind:
+ *
+ *   gate:   (input) => ResultAsync<T, GateFailure>
+ *   notice: (input) => ResultAsync<void, NoticeFailure>
+ *
+ * The harness calls each hook through `passGate` or `deliverNotice`, thus no
+ * call site selects its own failure policy, and no call site puts a `try` or a
+ * `catch` around a hook. A hook gives a failure as an `err`. A hook whose
+ * promise rejects has a defect, and the rejection passes through the helpers
+ * with no change.
+ *
+ * The reason of a failure is the text of the host. The harness carries it and
+ * never reads it. The flag `suspend` is part of the contract, thus the harness
+ * branches on it.
+ */
+import { ResultAsync } from "neverthrow";
+import type { Logger } from "./logger.js";
+export interface GateFailure {
+    readonly reason: string;
+    /** True when the host asks the harness to suspend the work in place of a failure. */
+    readonly suspend: boolean;
+}
+export interface NoticeFailure {
+    readonly reason: string;
+}
+export type GateName = "RunAuthorizer.authorize" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
+export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByJti" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record";
+export type GateRefusal = {
+    readonly kind: "failed";
+    readonly gate: GateName;
+    readonly reason: string;
+} | {
+    readonly kind: "suspended";
+    readonly gate: GateName;
+    readonly reason: string;
+};
+/**
+ * The host can build its `Result` with its own copy of neverthrow. The helper
+ * gives the outcome again as a `Result` of the copy of the harness. Thus the
+ * checkpoint recipes (`runtime/result-serialization.ts`) recognize the class,
+ * and a replay reads the same outcome.
+ */
+export declare function passGate<T>(gate: GateName, result: ResultAsync<T, GateFailure>): ResultAsync<T, GateRefusal>;
+export declare function deliverNotice(log: Logger, notice: NoticeName, result: ResultAsync<void, NoticeFailure>): Promise<boolean>;

package/dist/lib/hooks.js

@@ -0,0 +1,39 @@
+/**
+ * The two kinds of host hook: a gate and a notice.
+ *
+ * A gate gives a value or a permission that the harness must have before it
+ * can continue an operation. A notice reports a fact after the operation. The
+ * type of each hook shows its kind:
+ *
+ *   gate:   (input) => ResultAsync<T, GateFailure>
+ *   notice: (input) => ResultAsync<void, NoticeFailure>
+ *
+ * The harness calls each hook through `passGate` or `deliverNotice`, thus no
+ * call site selects its own failure policy, and no call site puts a `try` or a
+ * `catch` around a hook. A hook gives a failure as an `err`. A hook whose
+ * promise rejects has a defect, and the rejection passes through the helpers
+ * with no change.
+ *
+ * The reason of a failure is the text of the host. The harness carries it and
+ * never reads it. The flag `suspend` is part of the contract, thus the harness
+ * branches on it.
+ */
+import { err, ok, ResultAsync } from "neverthrow";
+/**
+ * The host can build its `Result` with its own copy of neverthrow. The helper
+ * gives the outcome again as a `Result` of the copy of the harness. Thus the
+ * checkpoint recipes (`runtime/result-serialization.ts`) recognize the class,
+ * and a replay reads the same outcome.
+ */
+export function passGate(gate, result) {
+    return new ResultAsync(Promise.resolve(result).then((settled) => settled.isOk()
+        ? ok(settled.value)
+        : err({ kind: settled.error.suspend ? "suspended" : "failed", gate, reason: settled.error.reason })));
+}
+export async function deliverNotice(log, notice, result) {
+    const delivered = await result;
+    if (delivered.isOk())
+        return true;
+    log.error("a notice of the host failed", { notice, reason: delivered.error.reason });
+    return false;
+}

package/dist/lib/result.d.ts

@@ -4,20 +4,31 @@
  * The agent loop and execution boundary model failure as values, not throws.
  * The house rules:
  *
- *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
- *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
- *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
- *     Everything above them flows `Result` / `ResultAsync`.
+ *  1. `try/catch` lives ONLY at a boundary:
+ *       - the thin wrappers at calls to code external to ours — a third-party
+ *         SDK, the `pg` driver, `fs`, the DBOS runtime. Those wrappers turn a
+ *         throw into an `err(DomainError)`.
+ *       - an API entry point, where a caller outside the harness gets the
+ *         outcome.
+ *       - a workflow body that gets the throw of a failed step or a failed
+ *         child workflow, and runs its failure path.
+ *       - the dispatch catch of the loop.
+ *     Everything else flows `Result` / `ResultAsync`. A host hook has no
+ *     `try/catch` around it: `passGate` / `deliverNotice` (`lib/hooks.ts`)
+ *     consume its `Result`.
  *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
  *     data variant (`ok({ found: false })`), never an `err`. `err` is
  *     reserved for what used to be `throw`n — an unexpected upstream failure.
  *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
  *     dialect of failure:
  *       - HTTP routes `.match(...)` a `Result` into a response.
- *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
- *         `resultStep` in `loop/run-step.ts`): durability records a step as
- *         failed — and retries / fails fast — ONLY on a thrown exception, so
- *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - The DBOS step boundary throws on an `err` that must fail or retry
+ *         the step (`unwrapOrThrow` / `resultStep` in `loop/run-step.ts`):
+ *         durability records a step as failed — and retries / fails fast —
+ *         ONLY on a thrown exception. A step can also return a `Result` as
+ *         its value: `runtime/result-serialization.ts` keeps the `Ok` / `Err`
+ *         class across the checkpoint, DBOS records the step as a success,
+ *         and the body MUST use the `err`.
  *       - Tool dispatch maps `err` into an `is_error` `tool_result`
  *         (`loop/run-agent.ts`).
  *
@@ -43,9 +54,9 @@ export interface DomainError {
 /**
  * A thrown wrapper for a structured error value that is not already an
  * `Error`. The original value rides on `.cause`, so the cause-walking
- * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
- * `status` / `code` signals they look for after a `Result` is rethrown at a
- * boundary.
+ * classifiers (`classifyProviderError`, `findSuspendError`) still reach the
+ * `status` / `code` / `type` signals they look for after a `Result` is
+ * rethrown at a boundary.
  */
 export declare class ResultError extends Error {
     readonly value: unknown;

package/dist/lib/result.js

@@ -4,20 +4,31 @@
  * The agent loop and execution boundary model failure as values, not throws.
  * The house rules:
  *
- *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
- *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
- *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
- *     Everything above them flows `Result` / `ResultAsync`.
+ *  1. `try/catch` lives ONLY at a boundary:
+ *       - the thin wrappers at calls to code external to ours — a third-party
+ *         SDK, the `pg` driver, `fs`, the DBOS runtime. Those wrappers turn a
+ *         throw into an `err(DomainError)`.
+ *       - an API entry point, where a caller outside the harness gets the
+ *         outcome.
+ *       - a workflow body that gets the throw of a failed step or a failed
+ *         child workflow, and runs its failure path.
+ *       - the dispatch catch of the loop.
+ *     Everything else flows `Result` / `ResultAsync`. A host hook has no
+ *     `try/catch` around it: `passGate` / `deliverNotice` (`lib/hooks.ts`)
+ *     consume its `Result`.
  *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
  *     data variant (`ok({ found: false })`), never an `err`. `err` is
  *     reserved for what used to be `throw`n — an unexpected upstream failure.
  *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
  *     dialect of failure:
  *       - HTTP routes `.match(...)` a `Result` into a response.
- *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
- *         `resultStep` in `loop/run-step.ts`): durability records a step as
- *         failed — and retries / fails fast — ONLY on a thrown exception, so
- *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - The DBOS step boundary throws on an `err` that must fail or retry
+ *         the step (`unwrapOrThrow` / `resultStep` in `loop/run-step.ts`):
+ *         durability records a step as failed — and retries / fails fast —
+ *         ONLY on a thrown exception. A step can also return a `Result` as
+ *         its value: `runtime/result-serialization.ts` keeps the `Ok` / `Err`
+ *         class across the checkpoint, DBOS records the step as a success,
+ *         and the body MUST use the `err`.
  *       - Tool dispatch maps `err` into an `is_error` `tool_result`
  *         (`loop/run-agent.ts`).
  *
@@ -32,9 +43,9 @@ import { Err, Ok } from "neverthrow";
 /**
  * A thrown wrapper for a structured error value that is not already an
  * `Error`. The original value rides on `.cause`, so the cause-walking
- * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
- * `status` / `code` signals they look for after a `Result` is rethrown at a
- * boundary.
+ * classifiers (`classifyProviderError`, `findSuspendError`) still reach the
+ * `status` / `code` / `type` signals they look for after a `Result` is
+ * rethrown at a boundary.
  */
 export class ResultError extends Error {
     value;
@@ -49,9 +60,8 @@ function describe(value) {
         return value.message;
     if (value && typeof value === "object" && "type" in value) {
         // Prefer a human `message` field when the structured error carries one
-        // (e.g. a `ProviderError`) so the wrapped `Error.message` stays
-        // pattern-matchable (`isBudgetExceeded`'s message backstop); fall back
-        // to the `type` discriminant otherwise.
+        // (e.g. a `ProviderError`) so the wrapped `Error.message` names the
+        // failure; fall back to the `type` discriminant otherwise.
         const message = value.message;
         if (typeof message === "string" && message.length > 0)
             return message;

package/dist/loop/run-agent.d.ts

@@ -100,8 +100,8 @@ export interface RunAgentOptions {
     readonly logger?: Logger;
     /**
      * Per-call LLM usage-accounting seam. Omitted falls back to the no-op
-     * recorder. Delivery is fire-and-forget by contract — the loop neither
-     * awaits `record` nor guards it, so a realization must not throw or block.
+     * recorder. `record` is a notice: the loop does not wait for its result,
+     * and it logs the reason of an `err` when the result arrives.
      */
     readonly usageRecorder?: UsageRecorder;
     /**

package/dist/loop/run-agent.js

@@ -3,6 +3,7 @@ import { jsonSchema, tool as aiTool, } from "ai";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice } from "../lib/hooks.js";
 import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/otel-spans.js";
 import { ResultError } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
@@ -150,8 +151,8 @@ async function runAgentLoop(agent, initial, session, opts) {
      * reported nothing to account for, so it is folded (to no effect) and left
      * out of the ledger rather than entered as an all-absent record.
      *
-     * Delivery is bare — no `await`, no `try` — because the `UsageRecorder`
-     * contract forbids `record` to throw or block.
+     * `record` is a notice. The loop does not wait for its result, thus a
+     * recorder that blocks does not make the run slower.
      */
     const accountForCall = (reply, stepName) => {
         addChatUsage(usage, reply.usage);
@@ -159,7 +160,7 @@ async function runAgentLoop(agent, initial, session, opts) {
         const reported = reply.usage;
         if (reported === undefined || !hasReportedUsage(reported))
             return;
-        usageRecorder.record({
+        void deliverNotice(log, "UsageRecorder.record", usageRecorder.record({
             recordKey: recordKeyFor(session, opts.invocationId, stepName),
             agentId: source.agentId,
             callPath: source.callPath,
@@ -169,7 +170,7 @@ async function runAgentLoop(agent, initial, session, opts) {
             ...(reply.requestedModelId === undefined ? {} : { requestedModelId: reply.requestedModelId }),
             ...(reply.servedModelId === undefined ? {} : { servedModelId: reply.servedModelId }),
             usage: reported,
-        });
+        }));
     };
     /** The rollups this loop stamps on its finish — each absent when nothing reported. */
     const finishUsage = () => ({

package/dist/provenance/seam.d.ts

@@ -69,7 +69,7 @@ export type RunProvenanceEvent = {
     runId: string;
     /**
      * The body's terminal status. Both boundary sites resolve it through `deriveFinalStatus`,
-     * which records a budget pause as `"canceled"` — so `"suspended_insufficient_funds"` (a
+     * which records a suspension as `"canceled"` — so `"suspended_insufficient_funds"` (a
      * `RunStatus` member) is never emitted here and is deliberately absent from this narrower
      * `ExecuteAnalysisFinalStatus`-minus-`"running"` set.
      */

package/dist/providers/ai-sdk.d.ts

@@ -1,6 +1,8 @@
 import { type LanguageModel } from "ai";
-import type { ResolveBilling } from "../billing/resolver.js";
+import { type AgentSession } from "../auth/types.js";
 import type { Logger } from "../lib/logger.js";
+import { type ProviderError, type SuspendOn } from "./errors.js";
+import { type ResolveRequestHeaders } from "./request-headers.js";
 import type { ChatProvider, FetchLike, ProviderCapabilities } from "./types.js";
 /**
  * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
@@ -30,9 +32,13 @@ export declare const RETRY_MAX_DELAY_MS = 30000;
  * and the server then enforces the true cap of the model.
  */
 export declare const DEFAULT_MAX_OUTPUT_TOKENS = 64000;
-export interface AiSdkProviderDeps {
+/** With no `suspendOn`, a provider uses {@link DEFAULT_SUSPEND_ON}. */
+export interface ProviderHostPolicy {
+    readonly resolveRequestHeaders?: ResolveRequestHeaders;
+    readonly suspendOn?: SuspendOn;
+}
+export interface AiSdkProviderDeps extends ProviderHostPolicy {
     readonly model: LanguageModel;
-    readonly resolveBilling: ResolveBilling;
     readonly capabilities?: Partial<ProviderCapabilities>;
     readonly logger?: Logger;
     /**
@@ -193,9 +199,8 @@ export type AiSdkProviderConfig = {
      */
     readonly maxRetries?: number;
 };
-export interface ConfiguredAiSdkProviderDeps {
+export interface ConfiguredAiSdkProviderDeps extends ProviderHostPolicy {
     readonly config: AiSdkProviderConfig;
-    readonly resolveBilling: ResolveBilling;
     readonly logger?: Logger;
 }
 /**
@@ -207,6 +212,38 @@ export interface ConfiguredAiSdkProviderDeps {
  * the same retry tick. `random` is injectable so the delay is testable.
  */
 export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDelay: number, random?: () => number): number;
+/**
+ * A rejection of the request headers hook is a defect of the host, and the
+ * harness does not catch it (host-hooks spec): the envelope never retries it,
+ * and the outer catch rethrows it unchanged. The hook call has no `catch`, thus
+ * this flag marks the rejection: it stays set when the hook call of the attempt
+ * did not settle as a value.
+ */
+export interface HookCall {
+    unsettled: boolean;
+}
+/** A refusal of the hook throws `HeadersRefused`. */
+export declare function headersForAttempt(hook: ResolveRequestHeaders | undefined, session: AgentSession, call: HookCall): Promise<Record<string, string>>;
+export declare function failureOf(e: unknown, workload: string, suspendOn: SuspendOn): ProviderError;
+/**
+ * Wrap a single wire attempt in the harness retry envelope. Built per call so
+ * the caller's `AbortSignal` reaches the primitive: it rethrows abort errors
+ * without retrying and cancels its own backoff sleep when the signal fires, so
+ * the retried closure adds no abort handling of its own. `shouldRetry` defers to
+ * the harness retryability taxonomy under the `suspendOn` map of the provider —
+ * thus a mapped status is never retried — and it never retries a refusal or a
+ * rejection of the request headers hook. A non-retried first failure is rethrown untouched,
+ * preserving the exact throwable the outer catch classifies. `createRetryError` carries the last real failure on `cause` so
+ * that, once retries are exhausted, `toProviderError`'s status walk reaches the
+ * true HTTP status instead of stopping at a synthetic wrapper. The attempt
+ * counter is per-instance because each call builds its own retry.
+ *
+ * An aborted caller signal also stops the retry. A wall-clock guard of a caller
+ * aborts with a `TimeoutError` reason, which the taxonomy marks as a retryable
+ * timeout. Without this guard the envelope would loop an expiry that the caller
+ * itself declared.
+ */
+export declare function createRetry(signal: AbortSignal | undefined, logger: Logger, maxRetries: number, suspendOn: SuspendOn, hookCall: HookCall): import("@ai-sdk/provider-utils").RetryFunction;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
 /**
  * Wrap a fetch so that the wait until the response starts does not exceed
@@ -227,6 +264,7 @@ export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvid
  * and the behavior stays byte-identical.
  */
 export declare function wrapFetchWithRequestTimeout(fetchImpl: FetchLike, requestTimeoutMs: number): FetchLike;
+export declare function hostPolicyOf(deps: ProviderHostPolicy): ProviderHostPolicy;
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it