@inflexa-ai/harness 0.13.0 → 0.14.1

package/dist/execution/run-event-parts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The two input-only rules of the run-event read seam: narrowing a raw durable
+ * stream value to the chat data-part contract, and the latest-wins reconciling
+ * fold applied before delivery.
+ *
+ * They live apart from the reader because they are the only part of the seam
+ * whose correctness is a function of its argument alone — no database, no
+ * durability engine, no clock — and keeping them here is what lets that be
+ * proven directly instead of inferred from a driven subscription.
+ */
+import type { CortexChatPart } from "../contracts/chat-parts.js";
+/**
+ * Narrow one raw stream value to a chat data part, or `null` when it is not one.
+ *
+ * A run's streams carry more than the contract: a sandbox step also writes its
+ * loop orchestration under envelopes (`data-loop-event`, `data-sandbox-event`)
+ * that belong to the workflow layer and have no registry entry. The seam's
+ * contract is the `CortexChatPart` union, so anything the registry does not
+ * classify is not deliverable — which also covers a part written by a producer
+ * newer than the reader.
+ *
+ * The registry is keyed by the discriminant alone, so this validates `type` and
+ * trusts the producer for the payload. There is no per-part schema to validate
+ * against: `contracts/chat-parts.ts` declares interfaces, not Zod objects. Both
+ * ends of this stream are typed against that same union inside this package, so
+ * the discriminant is the boundary that can actually drift (a producer emitting
+ * something else entirely) and the one worth checking.
+ */
+export declare function parseRunEventPart(value: unknown): CortexChatPart | null;
+/**
+ * Collapse a batch of parts so each reconciling id appears once, carrying its
+ * latest value, and every other part survives untouched in write order.
+ *
+ * `reconciling` in `PART_REGISTRY` already means "a later emission under this id
+ * supersedes the earlier one" — `data-step-activity` mints a stable id per
+ * `(runId, stepId)` precisely so a fold collapses every phase transition. Reading
+ * the flag rather than holding a list of part types here keeps one source of
+ * truth: a part type added to the registry later folds correctly without this
+ * module changing.
+ *
+ * A survivor keeps the position of its LAST occurrence, so relative order among
+ * the parts that are delivered is the order they were written.
+ */
+export declare function foldRunEventParts(parts: readonly CortexChatPart[]): CortexChatPart[];

package/dist/execution/run-event-stream.d.ts

@@ -0,0 +1,91 @@
+/**
+ * RunEventStream — the read side of the durable per-run event stream.
+ *
+ * Every analysis run already writes a rich, typed event stream: the parent
+ * `executeAnalysis` workflow writes the run-level parts, and each `sandbox-step`
+ * child writes its own step-level parts to its OWN stream, because a workflow can
+ * only write the stream it owns. This seam reads all of them back as one channel,
+ * so an embedder can show a user what a run is actually doing without
+ * reconstructing progress from the durability engine's internal step-cache tables
+ * — which record a step only when it *completes*, and so describe the thing that
+ * just finished rather than the thing in flight.
+ *
+ * The seam quarantines the engine the same way `RunLauncher` does for starting
+ * workflows: the delivered values are the harness's own `contracts/` part types,
+ * and no engine type appears in the exported signature.
+ *
+ * It is a push subscription rather than a snapshot reader because the engine's
+ * read primitive is an async generator with no offset parameter — "give me what
+ * is new since X" is not expressible on the public API, and expressing it would
+ * mean reaching into the SDK internals this seam exists to remove. A merged async
+ * iterator was the other candidate and was rejected because the set of sources
+ * grows during iteration (children join mid-run), which costs materially more
+ * code than invoking a handler; a callback also matches the `EmitFn` idiom the
+ * producers already speak.
+ *
+ * `subscribe` resolves rather than returning a `Result` because it has no failure
+ * to report. Observation is a diagnostic channel: a throwing handler and a
+ * failing stream are both logged and contained, mirroring the `safeEmit` stance
+ * on the write side, where a dropped UI frame must never fail a step. A read side
+ * that tore itself down on one bad part would be strictly less robust than the
+ * writer it observes.
+ */
+import type { Pool } from "pg";
+import type { CortexChatPart } from "../contracts/chat-parts.js";
+import type { Logger } from "../lib/logger.js";
+/**
+ * Construction-time dependencies. The pool is the application pool the run
+ * ledger lives in; the logger is where every contained failure is reported, and
+ * defaults to silence so an embedder that wired none sees nothing rather than
+ * having console forced on it.
+ */
+export interface RunEventStreamDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * Receives one part. May be async — the subscription awaits it, so a handler is
+ * never invoked concurrently with itself and back-pressure is the caller's to
+ * exert by taking its time. A throw is logged and swallowed.
+ */
+export type RunEventPartHandler = (part: CortexChatPart) => void | Promise<void>;
+/** Call-time parameters of one subscription. */
+export interface RunEventSubscribeOptions {
+    /** The run to observe. Also the parent workflow's id. */
+    readonly runId: string;
+    /** Where each delivered part goes. */
+    readonly onPart: RunEventPartHandler;
+    /** Aborting stops delivery and settles the returned promise. */
+    readonly signal: AbortSignal;
+}
+/**
+ * The run-event read seam. One method, because a run-scoped subscription is the
+ * whole capability: a general-purpose stream reader would leak the engine's model
+ * back into the surface this exists to quarantine.
+ */
+export interface RunEventStream {
+    /**
+     * Deliver every part the run produces — parent and children alike — to
+     * `onPart`, resolving when the run is terminal and every stream opened has
+     * drained, or promptly when the signal aborts.
+     *
+     * Parts from one workflow arrive in the order that workflow wrote them. No
+     * order is promised ACROSS the parent and its children: those workflows
+     * execute concurrently and the producers establish no cross-stream clock, so
+     * a total order could only be synthesised from timestamps that were never
+     * meant to be one. Consumers do not need it — every part is addressed by
+     * `runId`/`stepId` and the reconciling fold is per id.
+     */
+    subscribe(options: RunEventSubscribeOptions): Promise<void>;
+}
+/**
+ * Build the DBOS-backed realization of {@link RunEventStream}.
+ *
+ * Every stream is read from its beginning, and each workflow is opened at most
+ * once per subscription. Replay is not a cost worked around here, it is what
+ * makes attaching mid-run correct: a subscriber joining at minute ten receives
+ * the run's whole history and folding it yields the true current state.
+ * Re-opening a workflow would redeliver that history and duplicate every part
+ * the fold does not reconcile.
+ */
+export declare function createRunEventStream(deps: RunEventStreamDeps): RunEventStream;

package/dist/execution/run-event-stream.js

@@ -0,0 +1,212 @@
+/**
+ * RunEventStream — the read side of the durable per-run event stream.
+ *
+ * Every analysis run already writes a rich, typed event stream: the parent
+ * `executeAnalysis` workflow writes the run-level parts, and each `sandbox-step`
+ * child writes its own step-level parts to its OWN stream, because a workflow can
+ * only write the stream it owns. This seam reads all of them back as one channel,
+ * so an embedder can show a user what a run is actually doing without
+ * reconstructing progress from the durability engine's internal step-cache tables
+ * — which record a step only when it *completes*, and so describe the thing that
+ * just finished rather than the thing in flight.
+ *
+ * The seam quarantines the engine the same way `RunLauncher` does for starting
+ * workflows: the delivered values are the harness's own `contracts/` part types,
+ * and no engine type appears in the exported signature.
+ *
+ * It is a push subscription rather than a snapshot reader because the engine's
+ * read primitive is an async generator with no offset parameter — "give me what
+ * is new since X" is not expressible on the public API, and expressing it would
+ * mean reaching into the SDK internals this seam exists to remove. A merged async
+ * iterator was the other candidate and was rejected because the set of sources
+ * grows during iteration (children join mid-run), which costs materially more
+ * code than invoking a handler; a callback also matches the `EmitFn` idiom the
+ * producers already speak.
+ *
+ * `subscribe` resolves rather than returning a `Result` because it has no failure
+ * to report. Observation is a diagnostic channel: a throwing handler and a
+ * failing stream are both logged and contained, mirroring the `safeEmit` stance
+ * on the write side, where a dropped UI frame must never fail a step. A read side
+ * that tore itself down on one bad part would be strictly less robust than the
+ * writer it observes.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { sleep } from "../lib/async-utils.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
+import { queryStepsByRun } from "../state/step-executions.js";
+import { foldRunEventParts, parseRunEventPart } from "./run-event-parts.js";
+/** Durable stream key every run producer writes its parts under. */
+const RUN_EVENT_STREAM_KEY = "events";
+/**
+ * How often the run's step ledger is re-read for children that have started
+ * since the last look.
+ *
+ * A child records its own workflow id as it begins, so discovery can only be as
+ * timely as that write and there is nothing to subscribe to before it lands.
+ * Polling is the honest mechanism: the parent's dag snapshot marks a step running
+ * before the child's body has written its row, so an event-driven re-check would
+ * race the ledger. One second matches the engine's own stream-polling fallback,
+ * and lagging a child's first writes costs nothing — a stream subscribed late is
+ * still read from its beginning.
+ */
+const CHILD_DISCOVERY_INTERVAL_MS = 1_000;
+/**
+ * Build the DBOS-backed realization of {@link RunEventStream}.
+ *
+ * Every stream is read from its beginning, and each workflow is opened at most
+ * once per subscription. Replay is not a cost worked around here, it is what
+ * makes attaching mid-run correct: a subscriber joining at minute ten receives
+ * the run's whole history and folding it yields the true current state.
+ * Re-opening a workflow would redeliver that history and duplicate every part
+ * the fold does not reconcile.
+ */
+export function createRunEventStream(deps) {
+    const baseLogger = (deps.logger ?? createNoopLogger()).named("run-event-stream");
+    return {
+        async subscribe({ runId, onPart, signal }) {
+            const logger = baseLogger.with({ runId });
+            // Open generators, so an abort can ask each to wind down. The engine's
+            // reader exposes no cancellation: while it waits on a quiet-but-active
+            // workflow it is suspended inside an await, where a queued `return()` is
+            // only honoured once it next reaches a yield. Teardown is therefore
+            // best-effort by construction, and the subscription's own promise is
+            // raced against the signal rather than waiting on it.
+            const open = new Set();
+            let resolveAbort;
+            const aborted = new Promise((resolve) => {
+                resolveAbort = resolve;
+            });
+            const onAbort = () => {
+                resolveAbort();
+                for (const generator of open) {
+                    void generator.return(undefined).catch(() => {
+                        /* the read is already being abandoned */
+                    });
+                }
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+            // Delivery is serialized through one queue across every stream. That
+            // gives the fold a batch to collapse — whatever accumulated while the
+            // previous handler call was in flight is reconciled before it is handed
+            // over, which is what spares a mid-run subscriber the superseded
+            // intermediates it replayed. The queue is FIFO and the fold keeps
+            // survivors in place, so a single stream's write order survives it.
+            const pending = [];
+            let delivering = false;
+            const deliver = async () => {
+                if (delivering)
+                    return;
+                delivering = true;
+                try {
+                    while (pending.length > 0 && !signal.aborted) {
+                        const batch = pending.splice(0, pending.length);
+                        for (const part of foldRunEventParts(batch)) {
+                            if (signal.aborted)
+                                return;
+                            try {
+                                await onPart(part);
+                            }
+                            catch (err) {
+                                logger.warn("run-event handler threw", { partType: part.type, ...logger.errorFields(err) });
+                            }
+                        }
+                    }
+                }
+                finally {
+                    delivering = false;
+                }
+            };
+            const readWorkflowStream = async (workflowId) => {
+                const streamLogger = logger.with({ workflowId });
+                const generator = DBOS.readStream(workflowId, RUN_EVENT_STREAM_KEY);
+                open.add(generator);
+                try {
+                    for (;;) {
+                        const next = await generator.next();
+                        // Checked after the read, not before: `next()` is what notices
+                        // the workflow going inactive, and an aborted subscription
+                        // must not enqueue anything the drain will never take.
+                        if (next.done === true || signal.aborted)
+                            return;
+                        const part = parseRunEventPart(next.value);
+                        if (part === null) {
+                            streamLogger.debug("dropped a stream value outside the chat-part contract");
+                            continue;
+                        }
+                        pending.push(part);
+                        void deliver();
+                    }
+                }
+                catch (err) {
+                    // One stream's failure is contained here so the parent and every
+                    // other child keep arriving.
+                    streamLogger.error("run-event stream read failed", streamLogger.errorFields(err));
+                }
+                finally {
+                    open.delete(generator);
+                    void generator.return(undefined).catch(() => {
+                        /* already finished, or abandoned under abort */
+                    });
+                }
+            };
+            const subscribed = new Set([runId]);
+            const childReads = [];
+            // Children are addressed by the id the workflow bodies already persist.
+            // Deriving them from the scheduler's `${runId}-${idx}` naming would
+            // hard-code a scheme that belongs to the scheduler, and the engine's own
+            // child bookkeeping is internals of the kind this seam removes.
+            const discoverChildren = async () => {
+                (await queryStepsByRun(deps.pool, runId)).match((rows) => {
+                    for (const row of rows) {
+                        const childWorkflowId = row.childWorkflowId;
+                        if (childWorkflowId === null || subscribed.has(childWorkflowId))
+                            continue;
+                        subscribed.add(childWorkflowId);
+                        childReads.push(readWorkflowStream(childWorkflowId));
+                    }
+                }, (error) => {
+                    logger.warn("child discovery failed", { err: describeDbError(error) });
+                });
+            };
+            let parentDrained = false;
+            const parentRead = readWorkflowStream(runId).finally(() => {
+                parentDrained = true;
+            });
+            // The parent's stream draining IS the run reaching terminal: the engine
+            // ends a read exactly when the workflow is no longer active. One further
+            // pass runs after that — a child whose id landed in the ledger late is
+            // still replayed from zero — and then discovery stops.
+            const discovery = (async () => {
+                for (;;) {
+                    if (signal.aborted)
+                        return;
+                    await discoverChildren();
+                    if (signal.aborted || parentDrained)
+                        return;
+                    await Promise.race([sleep(CHILD_DISCOVERY_INTERVAL_MS), aborted, parentRead]);
+                }
+            })();
+            const settled = (async () => {
+                await discovery;
+                await parentRead;
+                await Promise.all(childReads);
+            })().catch((err) => {
+                // Defensive: every stream read and every discovery pass contains its
+                // own failure, so arriving here is a defect in this seam rather than
+                // a runtime condition. Logged rather than left to surface as an
+                // unhandled rejection after an abort already settled the caller.
+                logger.error("run-event subscription failed", logger.errorFields(err));
+            });
+            try {
+                await Promise.race([settled, aborted]);
+            }
+            finally {
+                signal.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}

package/dist/execution/run-synthesis.js

@@ -369,9 +369,9 @@ export async function generateRunSynthesis(input) {
         signal,
         emit,
         runStep: passthroughStep,
+        resolved: () => holder.outcome !== null,
     };
     await runToTerminal(agent, [{ role: "user", content: prompt }], input.session, loopDeps, {
-        resolved: () => holder.outcome !== null,
         tools: [submitTool, blockerTool],
         nudge: "You ended without calling a terminal tool. You MUST call " +
             "submit_synthesis with the final synthesis now, or report_blocker " +

package/dist/index.d.ts

@@ -54,6 +54,7 @@ export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
+export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";
@@ -88,9 +89,11 @@ export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.j
 export { ExecEventMessageSchema } from "./sandbox/types.js";
 export type { ExecEventMessage, DoneMarker } from "./sandbox/types.js";
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
-export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunProvenanceEvent } from "./workflows/execute-analysis.js";
+export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
+export { createRunEventStream } from "./execution/run-event-stream.js";
+export type { RunEventStream, RunEventStreamDeps, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";
 export type { SandboxAgentDeps, SandboxStepCoords, AgentMeta } from "./agents/sandbox/index.js";
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
@@ -101,7 +104,7 @@ export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export type { UpsertPlanInput } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export type { InsertRunInput, RunReservation } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";

package/dist/index.js

@@ -81,6 +81,16 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export { createThreadHistory } from "./memory/thread-history.js";
+// The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's
+// outcome) into a thread through `appendTurn`, and needs a message the model reads but that is not
+// user input — which is exactly what the marker denotes. The constructor is exported rather than
+// the marker key so a host can never hand-assemble a message that the turn-boundary predicates
+// (`isGenuineUserStart` and its SQL twin) would then fail to recognise; `isSyntheticUserMessage`
+// lets a host renderer tell such a message apart from a genuine user turn on the way back out.
+// `syntheticRecordMessage` is the one a HOST reaches for: equally non-turn-opening, but rendered —
+// the display reconstruction emits it as a `system` message rather than dropping it as loop
+// machinery, so an appended run outcome is visible in the transcript instead of silently absent.
+export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
@@ -138,6 +148,15 @@ export { ExecEventMessageSchema } from "./sandbox/types.js";
 // these, but an embedder running only the run engine registers them directly.
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
+// Run-event read seam — the fine-grained durable channel beside `observeRun`.
+// The two are a deliberate pair, not a duplication: `observeRun` is the coarse,
+// in-process run/step snapshot a workflow hands its host synchronously, and it
+// defers sub-step detail to the run's durable event stream. This is that stream,
+// read back — the per-tool-call activity, file trees, and step summaries a run
+// writes, fanned in from the parent workflow and every sandbox-step child.
+// Nothing in the signature belongs to the durability engine, so an embedder
+// consumes run events without depending on it.
+export { createRunEventStream } from "./execution/run-event-stream.js";
 // Sandbox-agent catalog. `buildAgent` maps a `SandboxAgentBuildContext` onto
 // `SandboxAgentDeps`, then selects the per-step agent by id from this record;
 // `SANDBOX_AGENT_META` is the planner-facing meta the same ids key.
@@ -155,7 +174,7 @@ export { validatePlan } from "./schemas/validate-plan.js";
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
 export { upsertPlan, loadPlan } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 // Host-neutral reference-data catalog and shared installation receipts. Each
 // artifact names the third-party upstream it is fetched from; embedders own all

package/dist/input-sanitization.d.ts

@@ -1,9 +1,10 @@
 /**
- * Input sanitization — two pure, always-on functions applied once to the
- * incoming user message by the chat route (change 6). Never applied to
- * assistant messages or tool results.
+ * Input sanitization — pure, always-on text functions, not a plug-in pipeline.
+ * What runs is exactly what is declared here.
  *
- * Two pure functions, not a plug-in pipeline. What runs is exactly these two.
+ * `normalizeUnicode` and `redactSecrets` are applied once to the incoming user
+ * message by the chat route (change 6), and never to assistant messages or tool
+ * results. `stripNulCharacters` is the exception — it applies to tool results.
  */
 /**
  * NFC-normalize and strip control characters.
@@ -13,6 +14,15 @@
  * that could smuggle formatting or terminal escapes.
  */
 export declare function normalizeUnicode(text: string): string;
+/**
+ * Strip every NUL from `text`. Applied where a tool result is built — so the
+ * loop's in-memory message and the stored row agree byte-for-byte and the
+ * prompt-cache prefix survives the round trip — and again where the turn is
+ * written, which holds the invariant for writers that are not the loop. User
+ * input needs no separate treatment: `normalizeUnicode` already strips NUL along
+ * with the rest of the C0 range.
+ */
+export declare function stripNulCharacters(text: string): string;
 /**
  * Replace structured secret formats with `[REDACTED: <name>]`.
  *

package/dist/input-sanitization.js

@@ -1,9 +1,10 @@
 /**
- * Input sanitization — two pure, always-on functions applied once to the
- * incoming user message by the chat route (change 6). Never applied to
- * assistant messages or tool results.
+ * Input sanitization — pure, always-on text functions, not a plug-in pipeline.
+ * What runs is exactly what is declared here.
  *
- * Two pure functions, not a plug-in pipeline. What runs is exactly these two.
+ * `normalizeUnicode` and `redactSecrets` are applied once to the incoming user
+ * message by the chat route (change 6), and never to assistant messages or tool
+ * results. `stripNulCharacters` is the exception — it applies to tool results.
  */
 /**
  * C0/C1 control characters and DEL, excluding `\t` (U+0009) and `\n`
@@ -21,6 +22,28 @@ const CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 export function normalizeUnicode(text) {
     return text.normalize("NFC").replace(CONTROL_CHARS, "");
 }
+/**
+ * NUL (U+0000) — the one character a stored message cannot carry. Postgres
+ * refuses it inside JSON: a `jsonb` column rejects the insert outright, and a
+ * `json` column accepts it but errors the moment a JSON operator reads that row
+ * ("U+0000 cannot be converted to text"), which is what `retractLastTurn`'s
+ * boundary predicate does. Either way one NUL byte poisons a thread, and it
+ * arrives through no fault of the model: tool results carry raw command output
+ * and file bytes, which is why they are otherwise left unsanitized.
+ */
+// eslint-disable-next-line no-control-regex -- matching NUL is the intent; see above.
+const NUL = /\u0000/g;
+/**
+ * Strip every NUL from `text`. Applied where a tool result is built — so the
+ * loop's in-memory message and the stored row agree byte-for-byte and the
+ * prompt-cache prefix survives the round trip — and again where the turn is
+ * written, which holds the invariant for writers that are not the loop. User
+ * input needs no separate treatment: `normalizeUnicode` already strips NUL along
+ * with the rest of the C0 range.
+ */
+export function stripNulCharacters(text) {
+    return text.replace(NUL, "");
+}
 /**
  * Each entry redacts one structured, prefixed secret format. Every pattern
  * has a prefix (`AKIA`, `sk-`, `gh*_`, `eyJ`, `Bearer`, a DB scheme) that

package/dist/lib/storage.js

@@ -7,7 +7,7 @@
  * the composition root and threaded as a constructor dep (see the harness-durable-runtime spec).
  */
 import pg from "pg";
-import { resolveAppPoolSize } from "../runtime/pools.js";
+import { APP_POOL_ACQUIRE_TIMEOUT_MS, resolveAppPoolSize } from "../runtime/pools.js";
 function poolOptions(config) {
     return {
         host: config.host,
@@ -18,6 +18,9 @@ function poolOptions(config) {
         // Per-pod app pool; DBOS owns its system-DB connections separately
         // (see the postgres-storage-backend spec). The boot guard checks this fits `max_connections`.
         max: resolveAppPoolSize(config.poolMax),
+        // Acquisition is bounded so a saturated pool fails a caller instead of
+        // hanging it — see `APP_POOL_ACQUIRE_TIMEOUT_MS` for the invariant.
+        connectionTimeoutMillis: APP_POOL_ACQUIRE_TIMEOUT_MS,
         // `pg` accepts `ssl: false` to disable entirely, or an object with
         // `rejectUnauthorized` to tune TLS. We map sslmode to those forms.
         ssl: config.sslMode === "disable"

package/dist/loop/budget-exceeded.d.ts

@@ -6,15 +6,31 @@
  * is wasteful because every subsequent call charged to the same budget will
  * also fail until the user tops up.
  *
- * Classification order (first hit wins):
+ * Classification order (first hit wins), and the order is load-bearing:
  *   1. Structured `statusCode === 402` (or `status === 402`) on any
  *      link of the cause chain. The gateway emits 402 exclusively for
  *      `budget_exceeded`, so a structured 402 is unambiguous.
- *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *   2. A `ProviderError` on the value or its cause chain that was decided on
+ *      a status: its `type` answers, and the text patterns are skipped.
+ *   3. Pattern fallback: `/budget.?exceeded/i` on the stringified
  *      top-level error message. Covers stringified throws and paths
  *      where no `statusCode` is attached (ops scripts, sandbox-server
  *      surfacing upstream billing errors as text).
  *
+ * Step 2 exists because the text heuristic must never outrank a real
+ * classification. A `ProviderError` message carries an excerpt of the provider's
+ * response body, so a non-retryable 400 whose body merely mentions a budget would
+ * otherwise match step 3 — and the callers of this predicate act on it fatally
+ * (`sandbox-step` self-cancels the workflow, `execute-analysis` re-raises it as a
+ * budget throw). A phrase inside a quoted body is not evidence against the status
+ * the failure actually carried.
+ *
+ * "Decided on a status" is the load-bearing qualifier. `toProviderError` wraps
+ * every throwable, including ones `classifyProviderError` had no status for — it
+ * returns `provider` as a fall-through default there, which is an absence of
+ * classification, not a determination. Treating that as authoritative would
+ * silence step 3 in precisely the case it was written for.
+ *
  * Returns `false` for all other errors. Safe to call with any value;
  * non-Error inputs hit the stringified-pattern branch and return `false`
  * unless the string happens to match.

package/dist/loop/budget-exceeded.js

@@ -6,19 +6,36 @@
  * is wasteful because every subsequent call charged to the same budget will
  * also fail until the user tops up.
  *
- * Classification order (first hit wins):
+ * Classification order (first hit wins), and the order is load-bearing:
  *   1. Structured `statusCode === 402` (or `status === 402`) on any
  *      link of the cause chain. The gateway emits 402 exclusively for
  *      `budget_exceeded`, so a structured 402 is unambiguous.
- *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *   2. A `ProviderError` on the value or its cause chain that was decided on
+ *      a status: its `type` answers, and the text patterns are skipped.
+ *   3. Pattern fallback: `/budget.?exceeded/i` on the stringified
  *      top-level error message. Covers stringified throws and paths
  *      where no `statusCode` is attached (ops scripts, sandbox-server
  *      surfacing upstream billing errors as text).
  *
+ * Step 2 exists because the text heuristic must never outrank a real
+ * classification. A `ProviderError` message carries an excerpt of the provider's
+ * response body, so a non-retryable 400 whose body merely mentions a budget would
+ * otherwise match step 3 — and the callers of this predicate act on it fatally
+ * (`sandbox-step` self-cancels the workflow, `execute-analysis` re-raises it as a
+ * budget throw). A phrase inside a quoted body is not evidence against the status
+ * the failure actually carried.
+ *
+ * "Decided on a status" is the load-bearing qualifier. `toProviderError` wraps
+ * every throwable, including ones `classifyProviderError` had no status for — it
+ * returns `provider` as a fall-through default there, which is an absence of
+ * classification, not a determination. Treating that as authoritative would
+ * silence step 3 in precisely the case it was written for.
+ *
  * Returns `false` for all other errors. Safe to call with any value;
  * non-Error inputs hit the stringified-pattern branch and return `false`
  * unless the string happens to match.
  */
+import { extractStatus, isProviderError } from "../providers/errors.js";
 const BUDGET_EXCEEDED_PATTERNS = [/budget.?exceeded/i];
 /** Max depth walked on the cause chain looking for a structured statusCode. */
 const MAX_CAUSE_HOPS = 5;
@@ -33,9 +50,39 @@ function hasStatus402(err) {
     }
     return false;
 }
+/**
+ * Find a `ProviderError` on the value or its cause chain. A `ResultError`
+ * thrown at a step boundary carries the structured value on `.cause`, which is
+ * the shape the callers of this predicate actually catch.
+ */
+function findProviderError(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        if (isProviderError(cursor))
+            return cursor;
+        cursor = cursor.cause;
+    }
+    return undefined;
+}
 export function isBudgetExceeded(err) {
     if (hasStatus402(err))
         return true;
+    const classified = findProviderError(err);
+    if (classified) {
+        if (classified.type === "budget")
+            return true;
+        // `auth` and `tenant-blocked` exist only because a status produced them, and
+        // a `provider` arm that carried a status was decided on it. None can be
+        // overturned by a phrase inside a response body the message merely quotes.
+        //
+        // A `provider` arm with NO status is the one exception: there
+        // `classifyProviderError` had nothing to key on and applied a fall-through
+        // default, so it made no determination to respect. That is exactly the shape
+        // a gateway reporting `budget_exceeded` as plain text arrives in, and the
+        // patterns below are the reason it is still caught.
+        if (classified.type !== "provider" || extractStatus(classified) !== undefined)
+            return false;
+    }
     const msg = err instanceof Error ? err.message : String(err ?? "");
     return BUDGET_EXCEEDED_PATTERNS.some((p) => p.test(msg));
 }