@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/contracts/subagent-activity.js

@@ -0,0 +1,76 @@
+// The sub-agent activity of a chat turn, beside `applyChatFrame`. Browser-safe: each import from outside `contracts/` is a type import.
+/** The most entries that one root tool call holds. Each later call of its sub-agents only adds to `dropped`. */
+export const SUBAGENT_ACTIVITY_MAX_ENTRIES = 200;
+// A call id is unique only inside the loop that made the call, thus the call path of that loop is part of the key.
+// The path is the lineage of the sub-agent, the same read as `isRootFrame`. No control flow of the harness uses it.
+function callKey(loopPath, callId) {
+    return JSON.stringify([loopPath, callId]);
+}
+export function createSubAgentActivityTracker() {
+    // A dropped call stays in the map, thus a deeper call below it still counts in `dropped`.
+    const calls = new Map();
+    const records = new Map();
+    const partOf = (rootId, record) => ({
+        type: "data-subagent-activity",
+        id: `subagent-activity-${rootId}`,
+        toolCallId: rootId,
+        entries: record.entries.map((entry) => ({ ...entry, callPath: [...entry.callPath] })),
+        dropped: record.dropped,
+    });
+    return {
+        track(frame, nowMs) {
+            if (frame.type !== "tool-started" && frame.type !== "tool-finished")
+                return null;
+            const { source } = frame;
+            if (frame.type === "tool-started") {
+                if (source.callPath.length <= 1) {
+                    calls.set(callKey(source.callPath, frame.toolUseId), { rootId: frame.toolUseId, startedMs: nowMs });
+                    return null;
+                }
+                if (source.invocationId === undefined)
+                    return null;
+                const parent = calls.get(callKey(source.callPath.slice(0, -1), source.invocationId));
+                if (parent === undefined)
+                    return null;
+                let record = records.get(parent.rootId);
+                if (record === undefined) {
+                    record = { entries: [], dropped: 0 };
+                    records.set(parent.rootId, record);
+                }
+                if (record.entries.length >= SUBAGENT_ACTIVITY_MAX_ENTRIES) {
+                    record.dropped += 1;
+                    calls.set(callKey(source.callPath, frame.toolUseId), { rootId: parent.rootId, startedMs: nowMs });
+                }
+                else {
+                    record.entries.push({
+                        agentId: source.agentId,
+                        callPath: [...source.callPath],
+                        tool: frame.name,
+                        ...(frame.detail === undefined ? {} : { label: frame.detail }),
+                        startedAt: new Date(nowMs).toISOString(),
+                    });
+                    calls.set(callKey(source.callPath, frame.toolUseId), {
+                        rootId: parent.rootId,
+                        entryIndex: record.entries.length - 1,
+                        startedMs: nowMs,
+                    });
+                }
+                return partOf(parent.rootId, record);
+            }
+            if (source.callPath.length <= 1)
+                return null;
+            const call = calls.get(callKey(source.callPath, frame.toolUseId));
+            if (call?.entryIndex === undefined)
+                return null;
+            const record = records.get(call.rootId);
+            const entry = record?.entries[call.entryIndex];
+            if (record === undefined || entry === undefined)
+                return null;
+            entry.outcome = frame.outcome;
+            if (frame.detail !== undefined)
+                entry.label = frame.detail;
+            entry.endedAt = new Date(frame.durationMs === undefined ? nowMs : call.startedMs + frame.durationMs).toISOString();
+            return partOf(call.rootId, record);
+        },
+    };
+}

package/dist/execution/artifact-metadata.js

@@ -78,9 +78,7 @@ function fileExtension(displayPath) {
  * composed from facts already on disk so search still finds the file.
  */
 function fallbackEntry(artifact, extra) {
-    // Leading slash so `inferArtifactType` matches the `/figures/` etc. segment
-    // on a working-directory-relative display path.
-    const fileType = inferArtifactType(`/${artifact.displayPath}`);
+    const fileType = inferArtifactType(artifact.displayPath);
     const format = fileExtension(artifact.displayPath);
     const sizePart = artifact.sizeBytes != null ? `, ${artifact.sizeBytes} bytes` : "";
     const description = `${artifact.displayPath} — ${fileType} file (${format}${sizePart}); automated description unavailable.`;

package/dist/execution/dbos-workflow-purger.d.ts

@@ -19,6 +19,7 @@
  * and queue rows each hold an `ON DELETE CASCADE` foreign key to
  * `workflow_status`, so they go with the status row.
  */
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
 import type { WorkflowPurger } from "./workflow-purger.js";
@@ -27,4 +28,5 @@ export interface DbosWorkflowPurgerDeps {
     readonly pool: Pool;
     readonly logger?: Logger;
 }
+export declare function dbosClientFor(pool: Pool, logger: Logger): Promise<DBOSClient>;
 export declare function createDbosWorkflowPurger({ pool, logger: injected }: DbosWorkflowPurgerDeps): WorkflowPurger;

package/dist/execution/dbos-workflow-purger.js

@@ -64,23 +64,30 @@ function asEngineLogger(logger) {
         error: (entry, metadata) => logger.error(render(entry), metadata?.stack === undefined ? undefined : { stack: metadata.stack }),
     };
 }
-export function createDbosWorkflowPurger({ pool, logger: injected }) {
-    const logger = (injected ?? createNoopLogger()).named("workflow-purger");
-    // One client per factory, not per call. Creating a client does no I/O, but the
-    // client registers `error` and `connect` handlers on the pool it is handed, so a
-    // client per purge would accumulate handler pairs on a long-lived pool. Its
-    // `destroy()` ends that pool, so a client over an injected pool must never be
-    // destroyed either — which leaves a per-call client nothing to release. Creation
-    // is lazy so building a purger stays free for a host that never purges.
-    let pending;
-    const engine = () => {
+/**
+ * One client for each pool, shared by every purger and by the run canceler. A client registers
+ * `error` and `connect` handlers on the pool it is handed, so a client for each caller would
+ * accumulate handler pairs on a long-lived pool. Its `destroy()` ends that pool, so a client over
+ * an injected pool must never be destroyed either — which leaves a per-call client nothing to
+ * release. Creation is lazy so a host that never reaches the engine builds no client. The logger of
+ * the first caller for a pool becomes the engine logger of that pool.
+ */
+const clients = new WeakMap();
+export function dbosClientFor(pool, logger) {
+    let client = clients.get(pool);
+    if (client === undefined) {
         // `create` never initializes the system database, and initialization is the
         // only path that reads the connection string once a pool is supplied — so the
         // url is unreachable from this client rather than merely untaken, and there is
-        // none to thread through the seam.
-        pending ??= DBOSClient.create({ systemDatabaseUrl: "", systemDatabasePool: pool, logger: asEngineLogger(logger) });
-        return pending;
-    };
+        // no url to pass.
+        client = DBOSClient.create({ systemDatabaseUrl: "", systemDatabasePool: pool, logger: asEngineLogger(logger) });
+        clients.set(pool, client);
+    }
+    return client;
+}
+export function createDbosWorkflowPurger({ pool, logger: injected }) {
+    const logger = (injected ?? createNoopLogger()).named("workflow-purger");
+    const engine = () => dbosClientFor(pool, logger);
     /**
      * Whether the engine's schema exists at all — the only thing that separates a
      * ledger the engine never created from one that is broken. It costs a round trip

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

@@ -1,18 +1,32 @@
 /**
  * RunCanceler — the encapsulated external-cancel path for an `executeAnalysis` run.
  *
- * A cancelled DBOS workflow can never execute another step, so the body's own
- * terminal block (`collectAndComplete`) is unreachable on external cancel and
- * nothing converges: the run row stays `running` (blocking same-plan relaunch
- * through `queryActiveRun`'s active-status dedup), pending step rows never
- * sweep, the running charge never closes, and the run mandate is never
- * revoked. This module is the host-side counterpart: cancel the engine's
- * parent + children, then converge each ledger the workflow would have.
+ * A cancelled DBOS workflow can never start another step, so the body's own
+ * terminal block (`collectAndComplete`) can be unreachable once the cancel lands
+ * and nothing converges: the run row stays `running` (blocking same-plan relaunch
+ * through `queryActiveRun`'s active-status dedup) and pending step rows never
+ * sweep. A step that started before the cancel still runs to its end, and its
+ * run status write is conditional on a `running` row. This module is the
+ * host-side counterpart: cancel the engine's parent + children, then converge
+ * the ledgers the workflow would have.
+ *
+ * The writer that wins the conditional terminal write of the run row owns the
+ * run end: the run emit, the charge close, and the mandate revoke. This module
+ * does those acts only when its write changed the row. A refused write means
+ * the body won the row and owns them; a failed write leaves the row `running`,
+ * so a second cancel converges the run. The step rows settle on every path.
+ *
+ * One exception: after a failed status write the body does the run end and
+ * records it as a workflow event (`run-end-record.ts`), while the row stays
+ * `running`. This module reads that record before its terminal write. A present
+ * record makes the terminal write carry the recorded status and error, and no
+ * act of the run end follows. A failed read writes nothing, so a second cancel
+ * converges the run.
  *
  * The engine capability stays internal — the production default is the
  * purger's `DBOSClient`-backed child-cascading cancel, which needs no launched
  * engine (see `dbos-workflow-purger.ts` for why the static `DBOS` facade is
- * the wrong tool here). `cancelWorkflows` is an optional test seam over it.
+ * the wrong tool here). `cancelWorkflows` is an optional injected function over it.
  *
  * No stream writes: `DBOS.writeStream` writes only from inside the workflow
  * that owns the stream, so the run-event reader (`run-event-stream.ts`)
@@ -22,6 +36,7 @@ import type { Pool } from "pg";
 import type { AgentSession } from "../auth/types.js";
 import type { RunCharge } from "../billing/run-charge.js";
 import type { Logger } from "../lib/logger.js";
+import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { RunStatus } from "../state/schema.js";
 import type { RunAuthorizer } from "./run-authorizer.js";
 export declare class UnknownRunError extends Error {
@@ -40,8 +55,10 @@ export interface CancelRunResult {
      * (the conditional write refuses to clobber it).
      */
     readonly finalStatus: RunStatus;
-    /** What actually converged. `mandate` is vacuously true for a row with no
-     * persisted jti — nothing to revoke, so hosts alert on any false flag. */
+    /** What actually converged. `charge` and `mandate` are vacuously true when
+     * there is nothing for this cancel to converge — a refused terminal write
+     * (the body owns them) and, for `mandate`, a row with no persisted jti — so
+     * hosts alert on any false flag. */
     readonly converged: {
         readonly steps: boolean;
         readonly charge: boolean;
@@ -53,9 +70,14 @@ export interface RunCancelerDeps {
     readonly runCharge: RunCharge;
     readonly runAuthorizer: RunAuthorizer;
     readonly logger?: Logger;
-    /** Test seam over the engine cancel. Production default: the workflow
+    /** Receives the end of a run that this canceler cancels. An absent binding, or a binding with no run emit, emits nothing. */
+    readonly provenance?: ProvenanceSeam;
+    /** The engine cancel. Production default: the workflow
      * purger's `DBOSClient`-backed cancel, child-cascading and launch-free. */
     readonly cancelWorkflows?: (workflowIds: readonly string[]) => Promise<void>;
+    /** The run end that the body recorded: `null` when it recorded none, a rejection when the read fails.
+     * The value is unchecked engine data. Production default: `DBOSClient.getEvent` with a zero timeout. */
+    readonly readRecordedRunEnd?: (runId: string) => Promise<unknown>;
 }
 export interface RunCanceler {
     /**

package/dist/execution/run-canceler.js

@@ -1,18 +1,32 @@
 /**
  * RunCanceler — the encapsulated external-cancel path for an `executeAnalysis` run.
  *
- * A cancelled DBOS workflow can never execute another step, so the body's own
- * terminal block (`collectAndComplete`) is unreachable on external cancel and
- * nothing converges: the run row stays `running` (blocking same-plan relaunch
- * through `queryActiveRun`'s active-status dedup), pending step rows never
- * sweep, the running charge never closes, and the run mandate is never
- * revoked. This module is the host-side counterpart: cancel the engine's
- * parent + children, then converge each ledger the workflow would have.
+ * A cancelled DBOS workflow can never start another step, so the body's own
+ * terminal block (`collectAndComplete`) can be unreachable once the cancel lands
+ * and nothing converges: the run row stays `running` (blocking same-plan relaunch
+ * through `queryActiveRun`'s active-status dedup) and pending step rows never
+ * sweep. A step that started before the cancel still runs to its end, and its
+ * run status write is conditional on a `running` row. This module is the
+ * host-side counterpart: cancel the engine's parent + children, then converge
+ * the ledgers the workflow would have.
+ *
+ * The writer that wins the conditional terminal write of the run row owns the
+ * run end: the run emit, the charge close, and the mandate revoke. This module
+ * does those acts only when its write changed the row. A refused write means
+ * the body won the row and owns them; a failed write leaves the row `running`,
+ * so a second cancel converges the run. The step rows settle on every path.
+ *
+ * One exception: after a failed status write the body does the run end and
+ * records it as a workflow event (`run-end-record.ts`), while the row stays
+ * `running`. This module reads that record before its terminal write. A present
+ * record makes the terminal write carry the recorded status and error, and no
+ * act of the run end follows. A failed read writes nothing, so a second cancel
+ * converges the run.
  *
  * The engine capability stays internal — the production default is the
  * purger's `DBOSClient`-backed child-cascading cancel, which needs no launched
  * engine (see `dbos-workflow-purger.ts` for why the static `DBOS` facade is
- * the wrong tool here). `cancelWorkflows` is an optional test seam over it.
+ * the wrong tool here). `cancelWorkflows` is an optional injected function over it.
  *
  * No stream writes: `DBOS.writeStream` writes only from inside the workflow
  * that owns the stream, so the run-event reader (`run-event-stream.ts`)
@@ -22,9 +36,10 @@ 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";
-import { queryStepsByRun, sweepPendingStepExecutions } from "../state/step-executions.js";
-import { createDbosWorkflowPurger } from "./dbos-workflow-purger.js";
+import { markRunCanceledIfActive, queryRun, updateRunStatus } from "../state/runs.js";
+import { cancelRunningStepExecutions, queryStepsByRun, sweepPendingStepExecutions } from "../state/step-executions.js";
+import { createDbosWorkflowPurger, dbosClientFor } from "./dbos-workflow-purger.js";
+import { parseRecordedRunEnd, RUN_END_EVENT_KEY } from "./run-end-record.js";
 /** The reason stamped on the run row and the revoke — the same literal
  * `collectAndComplete` records for a cancel it observes from inside. */
 const EXTERNAL_CANCEL_REASON = "external_cancel";
@@ -36,7 +51,7 @@ export class UnknownRunError extends Error {
         this.name = "UnknownRunError";
     }
 }
-const TERMINAL = new Set(["completed", "partial", "failed", "canceled"]);
+const TERMINAL = new Set(["completed", "partial", "failed", "canceled", "suspended_insufficient_funds"]);
 export function createRunCanceler(deps) {
     const { pool, runCharge, runAuthorizer } = deps;
     const logger = (deps.logger ?? createNoopLogger()).named("run-canceler");
@@ -52,9 +67,22 @@ export function createRunCanceler(deps) {
         })();
         await engineCancel(workflowIds);
     };
+    const readRecordedRunEnd = deps.readRecordedRunEnd ??
+        (async (runId) => (await dbosClientFor(pool, logger)).getEvent(runId, RUN_END_EVENT_KEY, 0));
     /** Steps whose child started (a persisted child workflow id) and has not written its terminal row. */
     const incompleteSteps = async (runId) => unwrapOrThrow(await queryStepsByRun(pool, runId)).filter((step) => step.childWorkflowId !== null && step.completedAt === null);
     const childIds = (steps) => steps.flatMap((step) => (step.childWorkflowId !== null ? [step.childWorkflowId] : []));
+    const emitRunEvent = deps.provenance?.emitRunEvent;
+    const emitGuarded = (event, session) => {
+        if (emitRunEvent === undefined)
+            return;
+        try {
+            emitRunEvent(event, session);
+        }
+        catch (err) {
+            logger.error("the run emit of the provenance binding threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
+        }
+    };
     return {
         async cancel(runId, session) {
             const row = unwrapOrThrow(await queryRun(pool, runId));
@@ -89,38 +117,112 @@ export function createRunCanceler(deps) {
             catch (err) {
                 logger.error("late-child cancel sweep failed", { runId, ...logger.errorFields(err) });
             }
-            // Convergence — each phase isolated so one failure skips nothing after it.
-            let transitioned = false;
+            // The run end that the body recorded after a failed status write. A value
+            // that is not a recorded run end counts as a failed read.
+            let recorded = null;
+            let readFailed = false;
             try {
-                transitioned = unwrapOrThrow(await markRunCanceledIfActive(pool, runId, EXTERNAL_CANCEL_REASON));
+                const value = await readRecordedRunEnd(runId);
+                if (value !== null && value !== undefined) {
+                    recorded = parseRecordedRunEnd(value);
+                    if (recorded === null) {
+                        readFailed = true;
+                        logger.error("the recorded run end has the wrong shape", { runId });
+                    }
+                }
             }
             catch (err) {
-                logger.error("markRunCanceledIfActive failed", { runId, ...logger.errorFields(err) });
+                readFailed = true;
+                logger.error("the read of the recorded run end failed", { runId, ...logger.errorFields(err) });
+            }
+            // Convergence — each phase isolated so one failure skips nothing after it.
+            // The terminal write has three outcomes: changed (this cancel won the row),
+            // refused (the body won it), failed (the row is unchanged). A failed read of
+            // the recorded run end is a failed write that never ran.
+            let writeOutcome = "failed";
+            if (!readFailed) {
+                try {
+                    const changed = recorded === null
+                        ? unwrapOrThrow(await markRunCanceledIfActive(pool, runId, EXTERNAL_CANCEL_REASON))
+                        : unwrapOrThrow(await updateRunStatus(pool, runId, recorded.status, recorded.error));
+                    writeOutcome = changed ? "changed" : "refused";
+                }
+                catch (err) {
+                    logger.error("the terminal write of the run failed", { runId, ...logger.errorFields(err) });
+                }
+            }
+            const transitioned = writeOutcome === "changed";
+            // A terminal step of the workflow that started before the cancel can still
+            // write, but its write is conditional on a `running` row too. The first
+            // write wins, and the run-end acts ride behind the write that won: a
+            // refused write means the run settled on its own and its own terminal step
+            // does them. A cut child never reached its terminal row, so its step
+            // records here too. A recorded run end means the body did the acts, so
+            // only the run metric rides behind the repair write.
+            if (transitioned && recorded !== null) {
+                recordRunCompleted({ workflow: "analysis", status: recorded.status, durationMs: elapsedSinceIso(row.startedAt) });
             }
-            // The workflow's own terminal step never runs after a cancel, so this
-            // conditional write is the one terminal write of an external cancel, and
-            // the outcome metrics ride behind it: a refused write means the run
-            // settled on its own and its own terminal step recorded them. A cut
-            // child never reached its terminal row, so its step records here too.
-            if (transitioned) {
+            if (transitioned && recorded === null) {
                 recordRunCompleted({ workflow: "analysis", status: "canceled", durationMs: elapsedSinceIso(row.startedAt) });
                 for (const step of cutSteps ?? [])
                     recordStepCompleted({ agentId: step.agentId, status: "canceled" });
+                // The end of the run rides the same condition. One wall-clock read stamps every event:
+                // the canceler is not a workflow, so no replay fires these emits again.
+                const atMs = Date.now();
+                for (const step of cutSteps ?? []) {
+                    const durationMs = elapsedSinceIso(step.startedAt, atMs);
+                    emitGuarded({
+                        type: "step_completed",
+                        analysisId: row.analysisId,
+                        runId,
+                        stepId: step.stepId,
+                        status: "canceled",
+                        ...(durationMs !== undefined ? { durationMs } : {}),
+                        atMs,
+                    }, session);
+                }
+                emitGuarded({
+                    type: "run_completed",
+                    analysisId: row.analysisId,
+                    runId,
+                    status: "canceled",
+                    atMs,
+                    durationMs: Math.max(0, atMs - Date.parse(row.startedAt)),
+                }, session);
             }
-            let steps = false;
+            let pendingSwept = false;
             try {
                 unwrapOrThrow(await sweepPendingStepExecutions(pool, runId));
-                steps = true;
+                pendingSwept = true;
             }
             catch (err) {
                 logger.error("pending-step sweep failed", { runId, ...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)));
+            let runningSettled = false;
+            try {
+                unwrapOrThrow(await cancelRunningStepExecutions(pool, runId, EXTERNAL_CANCEL_REASON));
+                runningSettled = true;
+            }
+            catch (err) {
+                logger.error("running-step settle failed", { runId, ...logger.errorFields(err) });
+            }
+            const steps = pendingSwept && runningSettled;
+            // Only the writer that won the row closes the charge and revokes. A refused
+            // write left both to the body; a failed write left the row `running`, so a
+            // second cancel converges the run. The flags of a refused write are true
+            // because there is nothing for this cancel to converge. With a recorded run
+            // end the body did both acts, and the flags are its results.
+            let charge = recorded !== null ? recorded.closed : writeOutcome === "refused";
+            let mandate = recorded !== null ? recorded.revoked : writeOutcome === "refused" || (writeOutcome === "failed" && row.mandateJti === null);
+            if (transitioned && recorded === null) {
+                charge = await deliverNotice(logger.with({ runId }), "RunCharge.close", runCharge.close({ analysisId: row.analysisId, runId, outcome: { kind: "canceled" }, session }));
+                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";
+            let finalStatus = recorded?.status ?? "canceled";
             if (!transitioned) {
                 const reread = unwrapOrThrow(await queryRun(pool, runId));
                 finalStatus = reread?.status ?? "canceled";

package/dist/execution/run-end-record.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/**
+ * The workflow event under which the body of `executeAnalysis` records its run
+ * end after a failed status write. The run canceler reads it with
+ * `DBOSClient.getEvent`.
+ */
+export declare const RUN_END_EVENT_KEY = "run-end";
+/**
+ * The run end that the body did: the status and the error that its failed
+ * status write tried to write, and the results of the charge close and of the
+ * revoke.
+ */
+export declare const RecordedRunEndSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+        partial: "partial";
+        canceled: "canceled";
+        suspended_insufficient_funds: "suspended_insufficient_funds";
+    }>;
+    error: z.ZodNullable<z.ZodString>;
+    closed: z.ZodBoolean;
+    revoked: z.ZodBoolean;
+}, z.core.$strip>;
+export type RecordedRunEnd = z.infer<typeof RecordedRunEndSchema>;
+/**
+ * The engine hands back deserialized data, thus a value of an event is unknown
+ * until this check. A value of the wrong shape gives `null`.
+ */
+export declare function parseRecordedRunEnd(value: unknown): RecordedRunEnd | null;

package/dist/execution/run-end-record.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { RunStatus } from "../state/schema.js";
+/**
+ * The workflow event under which the body of `executeAnalysis` records its run
+ * end after a failed status write. The run canceler reads it with
+ * `DBOSClient.getEvent`.
+ */
+export const RUN_END_EVENT_KEY = "run-end";
+/**
+ * The run end that the body did: the status and the error that its failed
+ * status write tried to write, and the results of the charge close and of the
+ * revoke.
+ */
+export const RecordedRunEndSchema = z.object({
+    status: RunStatus.exclude(["running"]),
+    error: z.string().nullable(),
+    closed: z.boolean(),
+    revoked: z.boolean(),
+});
+/**
+ * The engine hands back deserialized data, thus a value of an event is unknown
+ * until this check. A value of the wrong shape gives `null`.
+ */
+export function parseRecordedRunEnd(value) {
+    const parsed = RecordedRunEndSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}

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

@@ -19,11 +19,12 @@ import type { ChatPart } from "../contracts/chat-parts.js";
  * 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.
+ * trusts the producer for the payload. The part schemas in `contracts/schemas/`
+ * are for a consumer at the edge of the package, which parses what it receives.
+ * Both ends of this stream are typed against the same union inside this package,
+ * so the discriminant is the boundary that can drift (a producer that emits
+ * something else entirely), and a part that fails its schema still reaches the
+ * consumer for its own check.
  */
 export declare function parseRunEventPart(value: unknown): ChatPart | null;
 /**

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

@@ -20,11 +20,12 @@ import { PART_REGISTRY } from "../contracts/part-registry.js";
  * 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.
+ * trusts the producer for the payload. The part schemas in `contracts/schemas/`
+ * are for a consumer at the edge of the package, which parses what it receives.
+ * Both ends of this stream are typed against the same union inside this package,
+ * so the discriminant is the boundary that can drift (a producer that emits
+ * something else entirely), and a part that fails its schema still reaches the
+ * consumer for its own check.
  */
 export function parseRunEventPart(value) {
     if (typeof value !== "object" || value === null)

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

@@ -36,6 +36,11 @@ import type { ChatPart } from "../contracts/chat-parts.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import type { RunStatus } from "../state/schema.js";
+/** The part of a run row that the terminal part is made from. */
+export interface RunEventRunRead {
+    readonly status: RunStatus;
+    readonly error: string | null;
+}
 /**
  * Construction-time dependencies. The pool is the application pool the run
  * ledger lives in; the logger is where every contained failure is reported, and
@@ -45,8 +50,13 @@ import type { RunStatus } from "../state/schema.js";
 export interface RunEventStreamDeps {
     readonly pool: Pool;
     readonly logger?: Logger;
-    /** Reads the status of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
-    readonly readRunStatus?: (runId: string) => ResultAsync<RunStatus | null, DbError>;
+    /** Reads the status and the error of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
+    readonly readRun?: (runId: string) => ResultAsync<RunEventRunRead | null, DbError>;
+    /**
+     * Reads the status of the parent workflow in the durability engine, `null` when no workflow exists. Defaults to
+     * `DBOS.getWorkflowStatus`.
+     */
+    readonly readWorkflowStatus?: (runId: string) => Promise<string | null>;
     /** The wait between two reads of the run row. Defaults to a timer. */
     readonly sleep?: (ms: number) => Promise<void>;
 }
@@ -78,10 +88,12 @@ export interface RunEventStream {
      * aborts.
      *
      * A canceled workflow runs no more steps, thus it never writes its own
-     * terminal part, and the canceler cannot write a stream. When the parent
-     * stream ends with no `data-run-completed` or `data-run-failed` part and
-     * the run row reads `canceled`, the last part delivered is a
-     * `data-run-failed` part with `reason: "canceled"`.
+     * terminal part, and the canceler cannot write a stream. When every stream
+     * ends with no `data-run-completed` or `data-run-failed` part, the last
+     * part delivered is a `data-run-failed` part that the run row gives, or the
+     * status of the parent workflow when the row still reads `running`. A row
+     * that does not exist, a `completed` or `partial` row, an active workflow,
+     * and no workflow give no part.
      *
      * Parts from one workflow arrive in the order that workflow wrote them. No
      * order is promised ACROSS the parent and its children: those workflows