@inflexa-ai/harness 0.19.0 → 0.19.2

package/dist/agents/report-session-agent.d.ts

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools and the preview tool bind to the session-state gateway, thus one
- * assembled definition serves every thread, and the per-session state stays behind
- * the tool boundary.
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -19,20 +19,25 @@
  * across threads, and the provider cache reuses it.
  */
 import type { Pool } from "pg";
+import type { AuthContext } from "../auth/types.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { EmbeddingProvider } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ChromeConfig } from "../lib/chrome.js";
 import type { Logger } from "../lib/logger.js";
+import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
+import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+import { type ResolvePageAsset } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
 /**
  * The shared dependencies of the report agent. The gateway binds the per-session
  * state to the thread, thus every tool that touches the state gets the same
- * gateway. The resolver is optional, because a resolver realization can be absent,
- * and the preview tool degrades as data when it is.
+ * gateway. The resolver factory is optional, because a resolver realization can be
+ * absent, and the preview tool and the record tool degrade as data when it is.
  */
 export interface ReportSessionAgentDeps {
     /** Model id -- the provenance and metric label. The provider owns the wire model. */
@@ -43,12 +48,30 @@ export interface ReportSessionAgentDeps {
     readonly embedding: EmbeddingProvider;
     /** Workspace filesystem read seam -- the four read tools. */
     readonly workspaceFs: WorkspaceFilesystem;
-    /** Session-state gateway -- the authoring tools and the preview tool bind to it. */
+    /** Session-state gateway -- the authoring tools, the preview tool, the eyes tool, and the record tool bind to it. */
     readonly gateway: ReportSessionStateGateway;
-    /** Workspace-root resolution seam -- the preview tool resolves the page root per call. */
+    /** Workspace-root resolution seam -- the preview tool and the eyes tool resolve the page root per call. */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
-    /** Reference-resolution seam -- absent until a realization lands; the preview tool degrades as data. */
-    readonly resolver?: ReferenceResolver;
+    /** Append-only version store -- the record tool gates the whole document first, then records one version. */
+    readonly store: ReportVersionStore;
+    /** Thread reader -- the record tool reads the anchor of the report thread. */
+    readonly threads: Pick<ThreadStore, "getThread">;
+    /** Headless-Chrome config -- the eyes tool opens the rendered page. */
+    readonly chrome: ChromeConfig;
+    /**
+     * Reference-resolution factory -- absent until a realization lands; the preview tool and the record tool
+     * degrade as data. The factory binds one analysis, thus a tool makes the resolver over the scope of the call.
+     */
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
+    /**
+     * Page-asset lookup -- the preview tool maps the module specifier of a manifest
+     * entry onto a file on disk. Omitted falls back to the module resolution of the
+     * installation of the harness.
+     */
+    readonly resolvePageAsset?: ResolvePageAsset;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

package/dist/agents/report-session-agent.js

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools and the preview tool bind to the session-state gateway, thus one
- * assembled definition serves every thread, and the per-session state stays behind
- * the tool boundary.
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -19,7 +19,7 @@
  * across threads, and the provider cache reuses it.
  */
 import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
-import { createPreviewReportTool } from "../tools/report-session/preview-report.js";
+import { createExaminePageTool, createPreviewReportTool, createRecordVersionTool } from "../tools/report-session/index.js";
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
 import { createInspectDataProfileTool, createInspectRunTool } from "../tools/research/index.js";
 import { reportSessionPrompt } from "../prompts/report-session.js";
@@ -33,7 +33,7 @@ export const REPORT_SESSION_AGENT_ID = "report-session";
 const REPORT_SESSION_MAX_ITERATIONS = 50;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
-    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, resolver, logger } = deps;
+    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, makeResolver, resolvePageAsset, logger } = deps;
     const authoring = createReportAuthoringTools(gateway);
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
@@ -58,7 +58,23 @@ export function createReportSessionAgent(deps) {
         createPreviewReportTool({
             gateway,
             resolveWorkspaceRoot,
-            ...(resolver ? { resolver } : {}),
+            ...(makeResolver ? { makeResolver } : {}),
+            ...(resolvePageAsset ? { resolvePageAsset } : {}),
+            ...(logger ? { logger } : {}),
+        }),
+        // The eyes tool. It opens the rendered page in headless Chrome.
+        createExaminePageTool({
+            gateway,
+            resolveWorkspaceRoot,
+            chrome,
+            ...(logger ? { logger } : {}),
+        }),
+        // The record tool. It gates the whole document, then records one version.
+        createRecordVersionTool({
+            gateway,
+            store,
+            threads,
+            ...(makeResolver ? { makeResolver } : {}),
             ...(logger ? { logger } : {}),
         }),
     ];

package/dist/app/report-session-runtime.js

@@ -115,6 +115,7 @@ export function createReportSessionRuntime(deps) {
             state: { document: state.document ?? EMPTY_DRAFT, snapshot: state.snapshot },
             analysisId: state.analysisId,
             token: state.document,
+            seenDocumentHash: state.seenDocumentHash,
         };
     }
     const gateway = {
@@ -152,6 +153,31 @@ export function createReportSessionRuntime(deps) {
                 return { outcome: "failed", detail: describeDbError(error) };
             });
         },
+        async stampRendered(threadId, hash) {
+            const result = await store.stampRendered(threadId, hash);
+            return result.match((outcome) => (outcome === "stamped" ? { outcome: "stamped" } : { outcome: "absent" }), (error) => {
+                log.error("the rendered-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+        async stampSeen(threadId) {
+            const result = await store.stampSeen(threadId);
+            return result.match((outcome) => {
+                switch (outcome) {
+                    case "stamped":
+                        return { outcome: "stamped" };
+                    case "no-rendered":
+                        // The row holds no rendered hash, thus no preview stamped one and the copy found
+                        // none. The eyes direct a new preview from this arm.
+                        return { outcome: "no-rendered" };
+                    case "absent":
+                        return { outcome: "absent" };
+                }
+            }, (error) => {
+                log.error("the seen-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
     };
     return { gateway, ensureSessionState };
 }

package/dist/app/spawn-report-session.d.ts

@@ -18,10 +18,19 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import type { DbError } from "../lib/db-result.js";
+import { type ChromeConfig } from "../lib/chrome.js";
+import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -34,9 +43,15 @@ import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType }
  * state is not permitted. `parent_not_a_conversation` keeps the tree flat: a
  * report session cannot spawn another. `empty_parent_transcript` refuses a
  * report on a parent that holds no messages, because such a report reports
- * nothing.
+ * nothing. `no_browser` refuses every spawn under a composition that gives no
+ * eyes, and it carries the line that explains the absent capability.
  */
 export type SpawnRefusal = {
+    readonly type: "no_browser";
+    readonly op: string;
+    readonly parentThreadId: string;
+    readonly detail: string;
+} | {
     readonly type: "parent_not_found";
     readonly op: string;
     readonly parentThreadId: string;
@@ -57,6 +72,18 @@ export interface ReportSessionPaging {
 }
 export interface ReportSessionSpawnDeps {
     readonly pool: Pool;
+    /**
+     * The chrome config that the same composition gives to the eyes tool. The
+     * spawn reads only whether it names a browser, thus the spawn and the tool
+     * decide the availability of the eyes from one value.
+     */
+    readonly chrome: ChromeConfig;
+    /**
+     * The capture seam that the same composition gives to the eyes tool. A
+     * present seam is a route to a look with no browser endpoint, thus it
+     * satisfies the gate on its own.
+     */
+    readonly capture?: CapturePage;
 }
 export interface ReportSessionSpawn {
     /**
@@ -64,10 +91,10 @@ export interface ReportSessionSpawn {
      * The child takes the analysis of the parent, the parent thread id, and the
      * anchor — the parent's latest `messages.seq` at this moment.
      *
-     * Refused with a `SpawnRefusal`, no row written: an absent or archived
-     * parent, a parent that is not a conversation, and a parent with no
-     * messages. A store refusal (`DbError`, `ThreadInputError`) passes through
-     * unchanged.
+     * Refused with a `SpawnRefusal`, no row written: a composition with no
+     * eyes, an absent or archived parent, a parent that is not a conversation,
+     * and a parent with no messages. A store refusal (`DbError`,
+     * `ThreadInputError`) passes through unchanged.
      */
     spawnReportSession(parentThreadId: string): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
     /**

package/dist/app/spawn-report-session.js

@@ -18,13 +18,23 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { randomUUID } from "node:crypto";
 import { errAsync } from "neverthrow";
+import { hasBrowserUrl } from "../lib/chrome.js";
 import { createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 const _assertDomainError = true;
 const OP = "spawn-report-session";
+/** The line that the caller reads when the composition gives no eyes. */
+const NO_BROWSER_DETAIL = "the composition gives no browser, thus a report session can never record a version";
 /**
  * Compose the child title. N counts the existing report children of the parent
  * plus one. A parent with no title yields `Report N` alone, because the seed of
@@ -43,7 +53,16 @@ export function createReportSessionSpawn(deps) {
     const { pool } = deps;
     const store = createThreadStore(pool);
     const history = createThreadHistory(pool);
+    // The eyes of the composition are fixed at construction, thus the gate reads
+    // one boolean and never a live probe of the sidecar.
+    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
     function spawnReportSession(parentThreadId) {
+        // The gate runs before the parent read. A session with no route to a look
+        // reaches the record gate and refuses there forever, thus the spawn is the
+        // one honest place to say so.
+        if (!eyesAvailable) {
+            return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
+        }
         return store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.

package/dist/auth/local-run-authorizer.d.ts

@@ -2,8 +2,9 @@
  * LocalRunAuthorizer — the OSS realization of the `RunAuthorizer` seam.
  *
  * Issues a durable `RunSession` straight from the async-edge input: no remote
- * authorization, no credential read. It owns nothing revocable, so `revoke` is
- * a no-op. The opaque caller `auth` is forwarded untouched — local code never
+ * authorization, no credential read. It owns nothing revocable (it mints no
+ * jti), so `revoke` and `revokeByJti` are no-ops. The opaque caller `auth` is
+ * forwarded untouched — local code never
  * inspects it (no `getAuth`).
  */
 import type { RunAuthorizer } from "../execution/run-authorizer.js";

package/dist/auth/local-run-authorizer.js

@@ -2,8 +2,9 @@
  * LocalRunAuthorizer — the OSS realization of the `RunAuthorizer` seam.
  *
  * Issues a durable `RunSession` straight from the async-edge input: no remote
- * authorization, no credential read. It owns nothing revocable, so `revoke` is
- * a no-op. The opaque caller `auth` is forwarded untouched — local code never
+ * authorization, no credential read. It owns nothing revocable (it mints no
+ * jti), so `revoke` and `revokeByJti` are no-ops. The opaque caller `auth` is
+ * forwarded untouched — local code never
  * inspects it (no `getAuth`).
  */
 export function createLocalRunAuthorizer() {
@@ -19,5 +20,6 @@ export function createLocalRunAuthorizer() {
             return { runSession, ownsMandate: false }; // oss-core-managed-ok
         },
         async revoke() { },
+        async revokeByJti() { },
     };
 }

package/dist/config/environment-stores.d.ts

@@ -18,17 +18,22 @@
  * one. Neither store is ever written through these paths.
  *
  * Both are optional, and absence is a NORMAL state rather than an error: an
- * omitted path makes its tool report the store as unavailable or unknown, which
- * is a truthful answer an agent can act on. Absence must never be reported as a
- * failure, and never papered over with a guessed path.
+ * omitted path falls back to the store's container mountpoint — correct for a
+ * host whose own process sees the store the way a sandbox does, and harmless for
+ * one that does not, because every consumer stats the root before it reports
+ * anything. A host with nothing mounted there gets the same "unavailable" or
+ * "unknown" answer an omitted path has always produced, so the fallback can no
+ * more invent a store than an explicit path can. Set a path only to name a
+ * location the container mountpoint does not describe; absence must never be
+ * reported as a failure.
  */
 export interface EnvironmentStorePaths {
     /**
      * Host path of the reference store — the same bytes sandboxes mount at
-     * `/mnt/refs`. Omit when no store is provisioned; reference discovery then
-     * reports the store as unavailable. Note that an installed store reads as
-     * absent if this is omitted, which is indistinguishable to an agent from
-     * having no data — so omit it only when there is genuinely nothing staged.
+     * `/mnt/refs`. Omit when the host's own process sees the store at that same
+     * path, as a K8s pod holding the ref-store PVC does; set it when the host
+     * reads the store somewhere else, as a native process bind-mounting a host
+     * directory into Docker does.
      */
     readonly refStorePath?: string;
     /**

package/dist/config/resource-limits.d.ts

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 export declare const GpuSpecSchema: z.ZodObject<{
@@ -47,13 +50,6 @@ export declare const DEFAULT_SANDBOX_MAX_STEPS = 75;
 export declare class ResourceLimitsConfigError extends Error {
     constructor(message: string);
 }
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export declare function loadResourceLimits(): ResourceLimits;
 /**
  * Validate an embedder-supplied resource policy.
  *

package/dist/config/resource-limits.js

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 // ── Schemas ─────────────────────────────────────────────────────────
@@ -38,47 +41,6 @@ export class ResourceLimitsConfigError extends Error {
         this.name = "ResourceLimitsConfigError";
     }
 }
-// ── Parsing ─────────────────────────────────────────────────────────
-function parsePositiveNumber(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num <= 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a positive number, got: ${value}`);
-    }
-    return num;
-}
-function parseNonNegativeInt(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num < 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a non-negative number, got: ${value}`);
-    }
-    if (!Number.isInteger(num)) {
-        throw new ResourceLimitsConfigError(`${name} must be an integer, got: ${value}`);
-    }
-    return num;
-}
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export function loadResourceLimits() {
-    const maxCpu = parsePositiveNumber("SANDBOX_MAX_CPU", process.env.SANDBOX_MAX_CPU);
-    const maxMemoryGb = parsePositiveNumber("SANDBOX_MAX_MEMORY_GB", process.env.SANDBOX_MAX_MEMORY_GB);
-    const maxGpuCount = parseNonNegativeInt("SANDBOX_MAX_GPU_COUNT", process.env.SANDBOX_MAX_GPU_COUNT);
-    const limits = { maxCpu, maxMemoryGb, maxGpuCount };
-    const result = ResourceLimitsSchema.safeParse(limits);
-    if (!result.success) {
-        throw new ResourceLimitsConfigError(`Invalid resource limits configuration: ${result.error.message}`);
-    }
-    return result.data;
-}
 /**
  * Validate an embedder-supplied resource policy.
  *

package/dist/contracts/report-reference.d.ts

@@ -313,6 +313,8 @@ export declare const ScalarReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject
  * the path. `unreadable-artifact` means that the entry exists, and that the resolver cannot read the
  * artifact as a table. Two conditions give the second reason. The file type refuses a read of a cell, or
  * the bytes are unrecoverable.
+ *
+ * `extraction-unavailable` means that the value tier must use an extraction arm that is not wired.
  */
 export declare const UnresolvedReasonSchema: z.ZodEnum<{
     "artifact-missing": "artifact-missing";
@@ -321,6 +323,7 @@ export declare const UnresolvedReasonSchema: z.ZodEnum<{
     "ambiguous-match": "ambiguous-match";
     "assertion-failed": "assertion-failed";
     "unreadable-artifact": "unreadable-artifact";
+    "extraction-unavailable": "extraction-unavailable";
 }>;
 /** A reference that resolution could not bind, with the reason and an optional detail. */
 export declare const UnresolvedReferenceSchema: z.ZodObject<{
@@ -419,6 +422,7 @@ export declare const UnresolvedReferenceSchema: z.ZodObject<{
         "ambiguous-match": "ambiguous-match";
         "assertion-failed": "assertion-failed";
         "unreadable-artifact": "unreadable-artifact";
+        "extraction-unavailable": "extraction-unavailable";
     }>;
     detail: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;

package/dist/contracts/report-reference.js

@@ -175,6 +175,8 @@ export const ScalarReferenceSchema = z.discriminatedUnion("kind", [ArtifactValue
  * the path. `unreadable-artifact` means that the entry exists, and that the resolver cannot read the
  * artifact as a table. Two conditions give the second reason. The file type refuses a read of a cell, or
  * the bytes are unrecoverable.
+ *
+ * `extraction-unavailable` means that the value tier must use an extraction arm that is not wired.
  */
 export const UnresolvedReasonSchema = z.enum([
     "artifact-missing",
@@ -183,6 +185,7 @@ export const UnresolvedReasonSchema = z.enum([
     "ambiguous-match",
     "assertion-failed",
     "unreadable-artifact",
+    "extraction-unavailable",
 ]);
 /** A reference that resolution could not bind, with the reason and an optional detail. */
 export const UnresolvedReferenceSchema = z.strictObject({

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

@@ -15,6 +15,16 @@
  * realization injected at the composition root.
  */
 import type { AuthContext, Provenance, RunFrame, RunSession, Scope } from "../auth/types.js";
+/**
+ * Locates a run credential when no `RunAuthorization` exists: the persisted
+ * jti from `cortex_runs` plus the revoking caller's opaque `auth` — the sole
+ * carrier of credential/org behind a session, downcast only by managed
+ * realizations.
+ */
+export interface RevokeByJtiRef {
+    readonly jti: string;
+    readonly auth: AuthContext;
+}
 /** What an async edge knows when it authorizes a run: the opaque caller auth,
  * the scope + provenance to stamp on the run, and the run frame to mint for. */
 export interface AuthorizeRunInput {
@@ -40,4 +50,12 @@ export interface RunAuthorization {
 export interface RunAuthorizer {
     authorize(input: AuthorizeRunInput): Promise<RunAuthorization>;
     revoke(authorization: RunAuthorization, reason: string): Promise<void>;
+    /**
+     * Out-of-band revocation for paths holding no `RunAuthorization`. Normal
+     * terminal paths use `revoke(authorization, reason)` under the run
+     * credential; `revokeByJti` covers external cancellation, where the run
+     * credential's JWT was never persisted and only its jti survives on
+     * `cortex_runs`. Local/OSS authorizers no-op — they mint no jti.
+     */
+    revokeByJti(ref: RevokeByJtiRef, reason: string): Promise<void>;
 }

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

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * No stream writes: `DBOS.writeStream` is body-only, so hosts synthesize the
+ * terminal frame read-side.
+ */
+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 { RunStatus } from "../state/schema.js";
+import type { RunAuthorizer } from "./run-authorizer.js";
+export declare class UnknownRunError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+export interface CancelRunResult {
+    readonly runId: string;
+    /** The DBOS parent workflow id — equal to `runId` by the launch contract
+     * (`execute_analysis` launches with `workflowId: runId`). */
+    readonly workflowId: string;
+    readonly outcome: "canceled" | "already_terminal";
+    /**
+     * The run row's status after the cancel. `canceled` when this cancel won
+     * the row; the run's own terminal status when it completed concurrently
+     * (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. */
+    readonly converged: {
+        readonly steps: boolean;
+        readonly charge: boolean;
+        readonly mandate: boolean;
+    };
+}
+export interface RunCancelerDeps {
+    readonly pool: Pool;
+    readonly runCharge: RunCharge;
+    readonly runAuthorizer: RunAuthorizer;
+    readonly logger?: Logger;
+    /** Test seam over the engine cancel. Production default: the workflow
+     * purger's `DBOSClient`-backed cancel, child-cascading and launch-free. */
+    readonly cancelWorkflows?: (workflowIds: readonly string[]) => Promise<void>;
+}
+export interface RunCanceler {
+    /**
+     * Cancel the run's workflows and converge its ledgers. Rejects when the
+     * engine cancel itself fails (retry-safe: nothing converged) or the run is
+     * unknown; convergence-phase failures resolve with their flag false.
+     */
+    cancel(runId: string, session: AgentSession): Promise<CancelRunResult>;
+}
+export declare function createRunCanceler(deps: RunCancelerDeps): RunCanceler;