@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/contracts/schemas/chat-parts.d.ts

@@ -15,6 +15,19 @@ export declare const PlanStepSchema: z.ZodObject<{
             count: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    grounding: z.ZodOptional<z.ZodObject<{
+        status: z.ZodString;
+        snapshot: z.ZodString;
+        claims: z.ZodArray<z.ZodString>;
+        template: z.ZodOptional<z.ZodString>;
+        settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            step: z.ZodString;
+            name: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+            source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
     maxSteps: z.ZodNumber;
     track: z.ZodOptional<z.ZodString>;
     step_type: z.ZodOptional<z.ZodString>;
@@ -106,6 +119,19 @@ export declare const PlanPartSchema: z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        grounding: z.ZodOptional<z.ZodObject<{
+            status: z.ZodString;
+            snapshot: z.ZodString;
+            claims: z.ZodArray<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                step: z.ZodString;
+                name: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
         maxSteps: z.ZodNumber;
         track: z.ZodOptional<z.ZodString>;
         step_type: z.ZodOptional<z.ZodString>;
@@ -670,6 +696,19 @@ export declare const ChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 count: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        grounding: z.ZodOptional<z.ZodObject<{
+            status: z.ZodString;
+            snapshot: z.ZodString;
+            claims: z.ZodArray<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                step: z.ZodString;
+                name: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
         maxSteps: z.ZodNumber;
         track: z.ZodOptional<z.ZodString>;
         step_type: z.ZodOptional<z.ZodString>;

package/dist/contracts/schemas/chat-parts.js

@@ -12,6 +12,23 @@ export const PlanStepSchema = z.object({
     question: z.string(),
     depends_on: z.array(z.string()),
     resources: z.object({ cpu: z.number(), memoryGb: z.number(), gpu: z.object({ count: z.number() }).optional() }).optional(),
+    grounding: z
+        .object({
+        status: z.string(),
+        snapshot: z.string(),
+        claims: z.array(z.string()),
+        template: z.string().optional(),
+        settings: z
+            .array(z.object({
+            step: z.string(),
+            name: z.string(),
+            value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]),
+            source: z.string().optional(),
+        }))
+            .optional(),
+        reason: z.string(),
+    })
+        .optional(),
     maxSteps: z.number(),
     track: z.string().optional(),
     step_type: z.string().optional(),

package/dist/contracts/schemas/index.d.ts

@@ -1,3 +1,3 @@
 export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, PlanApprovalPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, ActivityEntryPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, FindingReferenceSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, ChatPartSchema, } from "./chat-parts.js";
-export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
+export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, MessageStartEventSchema, ChatEventSchema, } from "./chat-events.js";
 export { TokenUsageRollupSchema } from "./usage.js";

package/dist/contracts/schemas/index.js

@@ -1,3 +1,3 @@
 export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, PlanApprovalPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, ActivityEntryPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, FindingReferenceSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, ChatPartSchema, } from "./chat-parts.js";
-export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, ChatEventSchema, } from "./chat-events.js";
+export { EventSourceSchema, TextDeltaEventSchema, IterationEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, MessageStartEventSchema, ChatEventSchema, } from "./chat-events.js";
 export { TokenUsageRollupSchema } from "./usage.js";

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";
@@ -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/index.d.ts

@@ -17,7 +17,7 @@ export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/asse
 export { createReportSessionSpawn } from "./app/spawn-report-session.js";
 export type { ReportSessionSpawn, ReportSessionSpawnDeps, ReportSessionPaging, SpawnRefusal, ReportBrief, ReportSessionDelta, NewestReportChild, } from "./app/spawn-report-session.js";
 export { launchPlanRun } from "./tools/execute-analysis.js";
-export type { LaunchPlanRunDeps, LaunchPlanRunRefusal, PlanLaunch } from "./tools/execute-analysis.js";
+export type { LaunchPlanRunDeps, LaunchPlanRunInput, LaunchPlanRunRefusal, PlanLaunch } from "./tools/execute-analysis.js";
 export { approvePlan } from "./app/approve-plan.js";
 export type { ApprovePlanDeps, ApprovePlanInput, ApprovePlanRefusal, PlanApproval } from "./app/approve-plan.js";
 export type { EnsureSessionStateResult } from "./app/report-session-runtime.js";
@@ -52,10 +52,14 @@ export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 export type { RunCanceler, RunCancelerDeps, CancelRunResult } from "./execution/run-canceler.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
+export type { KnowledgeClient, KnowledgeSituation, HttpKnowledgeClientConfig } from "./tools/knowledge/index.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 export { createCitationResolver } from "./citations/resolve.js";
 export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
+export type { WebSearchEngine } from "./tools/research/web-search.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 export type { CitationKind, CitationInput, CitationSource, CitationSourceStatus, CitationResolver, CitationResolveOptions, CitationResolutionResult, CitationVerdict, CitationCoverage, ComparisonStatus, CitationField, UnsupportedWorkKind, CitationIdentifiers, NormalizedCitationMetadata, NormalizedCitation, CitationSourceOutcome, CitationRecord, IdentifierEvidence, CitationFieldComparison, CitationConflict, CitationCandidateCluster, CitationSourceClient, CitationSourceRequest, CitationSourceOperation, CitationSourcePlanItem, RegistrationAgencyEvidence, } from "./citations/types.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
@@ -91,14 +95,14 @@ export type { ChatTurnOutcome, ChatTurnRan, ChatTurnRefusal, ChatTurnResult, Cha
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ListRecentThreadsInput, ThreadPage, } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, LoadPageOptions, TurnPage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
 export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions } from "./memory/conversation-display-recorder.js";
 export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMessage, StoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
-export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
+export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, MessageStartEvent, } from "./contracts/chat-events.js";
 export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
 export { createSubAgentActivityTracker, SUBAGENT_ACTIVITY_MAX_ENTRIES } from "./contracts/subagent-activity.js";
 export type { SubAgentActivityTracker } from "./contracts/subagent-activity.js";
@@ -141,7 +145,7 @@ export type { DataProfileStatus } from "./state/data-profile.js";
 export { queryLatestRunsByAnalyses, queryDataProfileStatusByAnalyses, queryRunProgressByRuns, queryRunsEndedSince } from "./state/analyses-metrics.js";
 export type { DataProfileSummary, EndedRunSummary, LatestRunSummary, RunProgressSummary } from "./state/analyses-metrics.js";
 export { queryArtifactPage, countArtifactsByRuns } from "./state/artifacts.js";
-export type { ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount } from "./state/artifacts.js";
+export type { ArtifactExtensionCount, ArtifactPage, ArtifactPageEntry, ArtifactPageQuery, ArtifactPageSort, RunArtifactCount } from "./state/artifacts.js";
 export { readRunSynthesis } from "./execution/run-synthesis.js";
 export type { ReadSynthesisInput } from "./execution/run-synthesis.js";
 export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBES, DIMENSION_PROBE_IDS, GROUP_CATEGORIES, GROUP_CATEGORY_IDS, GROUP_ROLES, GROUP_ROLE_IDS, PROBE_OUTCOME_IDS, dimensionCategoryEntry, dimensionScope, groupCategoryEntry, } from "./contracts/profile-vocabulary.js";
@@ -191,7 +195,7 @@ export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
 export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
 export type { UpsertPlanInput, PlanRecord } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, 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, TerminalRunStatus } from "./state/schema.js";

package/dist/index.js

@@ -70,6 +70,10 @@ export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 export { createRunCanceler, UnknownRunError } from "./execution/run-canceler.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// The knowledge plane: an embedder binds a client at its composition root
+// (or none), and it can hand `knowledge_recommend` to the conversation agent
+// through `hostTools`.
+export { createHttpKnowledgeClient, createKnowledgeRecommendTool, createKnowledgeCheckTool, createKnowledgeTools, knowledgeToolDefinitionHash, } from "./tools/knowledge/index.js";
 // Tool-call-detail authoring aids for an embedder that contributes a host tool.
 // A `describeCall` hook that pre-empts truncation — a count in place of a
 // mid-value cut that would name a file that does not exist — must gate on the
@@ -81,6 +85,12 @@ export { defineTool, isToolError } from "./tools/define-tool.js";
 export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 // Host-agnostic citation verification service and its public contracts.
 export { createCitationResolver } from "./citations/resolve.js";
+// The web-search engine type and the SearXNG realization. An embedder cannot
+// build its composition root without these two names: it constructs the engine
+// and types the `webSearch` field of `ConversationAgentDeps` (the front-door
+// rule of the harness-embedder-exports spec). The tools stay off the barrel —
+// the conversation agent constructs them itself.
+export { createSearxngEngine } from "./tools/research/searxng-engine.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 // Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
 // over the injected `Pool` and carries the outward `answer`/`pending` API plus
@@ -296,7 +306,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, loadPlanRecord } from "./state/plans.js";
-export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, 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