@inflexa-ai/harness 0.37.0 → 0.39.0

package/dist/tasks/derive-table-exec.d.ts

@@ -18,8 +18,10 @@
  * callback unroutable and it lands as a `400`. The pull backstop still settles such an exec, but it pays
  * the quiet interval first.
  */
+import { type Result } from "neverthrow";
 import type { Logger } from "../lib/logger.js";
 import type { SandboxClient } from "../sandbox/client.js";
+import { type Suspension } from "../workflows/suspension.js";
 import type { ExecResult } from "../sandbox/types.js";
 import { type DeriveTableExecInput } from "../tools/report-session/derive-table.js";
 /** The construction-time deps of the body. The registration closes over them, thus the trigger holds none. */
@@ -35,15 +37,17 @@ export interface DeriveTableExecDeps {
 /**
  * The body, exported so a test drives it without a registered workflow.
  *
- * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
- * result type here.
+ * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
+ * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
+ * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
+ * conversation agent.
  */
-export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<ExecResult>;
+export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<Result<ExecResult, Suspension>>;
 /**
  * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
  * dispatches with `DBOS.startWorkflow`.
  */
-export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<ExecResult>;
+export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
 /**
  * The workflow id of one derivation.
  *
@@ -55,6 +59,6 @@ export declare function deriveTableExecWorkflowId(executionId: string): string;
  * The async edge. It starts the registered workflow and it awaits the terminal result.
  *
  * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise.
+ * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
  */
-export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<ExecResult>, input: DeriveTableExecInput): Promise<ExecResult>;
+export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>, input: DeriveTableExecInput): Promise<Result<ExecResult, Suspension>>;

package/dist/tasks/derive-table-exec.js

@@ -19,16 +19,22 @@
  * the quiet interval first.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { err, ok } from "neverthrow";
+import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
+import { suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { buildDerivationExec, DERIVATION_DEADLINE_MS, DERIVATION_RESOURCES, DERIVE_RUN_LITERAL, DERIVE_STEP_LITERAL, } from "../tools/report-session/derive-table.js";
 /** The awaitExec callback. A derivation reports no live activity, thus the callback drops each event. */
 const noopEmit = () => { };
 /**
  * The body, exported so a test drives it without a registered workflow.
  *
- * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
- * result type here.
+ * A fault of any seam call throws. The tool reads a rejection as one short detail. A chat turn awaits this
+ * workflow, thus a suspension is the `err` of the result, and the workflow does not cancel
+ * (workflow-suspension spec). The body does not mark the analysis: the tool reports the suspension to the
+ * conversation agent.
  */
 export async function runDeriveTableExecBody(input, deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table-exec").with({ analysisId: input.analysisId });
@@ -36,14 +42,13 @@ export async function runDeriveTableExecBody(input, deps) {
     // One workflow submits one exec, thus the function id is a constant. The three segments are what a
     // callback host parses to find the workflow that awaits this exec.
     const execId = `${workflowId}:${DERIVE_STEP_LITERAL}:fn-0`;
-    const sandbox = await deps.sandboxClient.createSandbox({
-        runId: DERIVE_RUN_LITERAL,
-        stepId: DERIVE_STEP_LITERAL,
-        analysisId: input.analysisId,
-        childWorkflowId: workflowId,
-        resources: DERIVATION_RESOURCES,
-        writableTail: input.writableTail,
-    }, mintSandboxIdentity(DERIVE_RUN_LITERAL));
+    const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(input.runSession, DERIVE_STEP_LITERAL), { childWorkflowId: workflowId, resources: DERIVATION_RESOURCES, writableTail: input.writableTail }, mintSandboxIdentity(DERIVE_RUN_LITERAL)));
+    if (spawned.isErr()) {
+        const suspension = suspensionOfSpawnRefusal(spawned.error);
+        logger.warn("derivation suspended", { reason: suspension.reason });
+        return err(suspension);
+    }
+    const sandbox = spawned.value;
     try {
         // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
         // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
@@ -55,7 +60,7 @@ export async function runDeriveTableExecBody(input, deps) {
             inputs: input.inputs,
             output: input.output,
         }));
-        return await deps.sandboxClient.awaitExec(sandbox, execId, noopEmit, deadline);
+        return ok(await deps.sandboxClient.awaitExec(sandbox, execId, noopEmit, deadline));
     }
     finally {
         try {
@@ -86,7 +91,7 @@ export function deriveTableExecWorkflowId(executionId) {
  * The async edge. It starts the registered workflow and it awaits the terminal result.
  *
  * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
- * lifecycle of its own. A workflow fault rejects the returned promise.
+ * lifecycle of its own. A workflow fault rejects the returned promise, and a suspension is the `err`.
  */
 export async function triggerDeriveTableExec(workflow, input) {
     const handle = (await DBOS.startWorkflow(workflow, {

package/dist/tasks/extract-values.d.ts

@@ -11,11 +11,13 @@
  * authorization on every terminal path. The container is ephemeral, and it goes away with the work, thus no
  * standing machine exists.
  */
-import type { AuthContext, RunSession } from "../auth/types.js";
+import { type Result } from "neverthrow";
+import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { Logger } from "../lib/logger.js";
 import type { ExtractionArm, ExtractionArtifact, ExtractionRequest } from "../report-model/production-resolver.js";
 import type { SandboxClient } from "../sandbox/client.js";
+import { type Suspension } from "../workflows/suspension.js";
 import type { ExecResult, SubmitExecBody } from "../sandbox/types.js";
 import { type ExtractValuesResult } from "./extract-values-script.js";
 export type { ExtractValuesResult } from "./extract-values-script.js";
@@ -71,13 +73,16 @@ export declare function parseExtractionOutput(result: ExecResult): ExtractValues
  * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
  * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
  * authorization on every terminal path, and it tears the container down on both paths.
+ *
+ * A chat turn awaits this workflow, thus a suspension is the `err` of the result, and the workflow does not
+ * cancel (workflow-suspension spec). The body does not mark the analysis: the caller reports the suspension.
  */
-export declare function runExtractValuesBody(input: ExtractValuesWorkflowInput, deps: ExtractValuesDeps): Promise<ExtractValuesResult>;
+export declare function runExtractValuesBody(input: ExtractValuesWorkflowInput, deps: ExtractValuesDeps): Promise<Result<ExtractValuesResult, Suspension>>;
 /**
  * Register the extraction workflow with DBOS. It gives back the registered callable, thus a trigger
  * dispatches with `DBOS.startWorkflow`.
  */
-export declare function registerExtractValuesWorkflow(deps: ExtractValuesDeps): (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+export declare function registerExtractValuesWorkflow(deps: ExtractValuesDeps): (input: ExtractValuesWorkflowInput) => Promise<Result<ExtractValuesResult, Suspension>>;
 /** The per-attempt workflow id. A fresh nonce keeps each pass under a distinct id. */
 export declare function extractValuesWorkflowId(analysisId: string, nonce: string): string;
 /**
@@ -86,7 +91,7 @@ export declare function extractValuesWorkflowId(analysisId: string, nonce: strin
  */
 export interface ExtractValuesTriggerDeps {
     readonly runAuthorizer: RunAuthorizer;
-    readonly workflow: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+    readonly workflow: (input: ExtractValuesWorkflowInput) => Promise<Result<ExtractValuesResult, Suspension>>;
 }
 /** The identity and the requests for one extraction pass. */
 export interface ExtractValuesTriggerParams {
@@ -96,12 +101,13 @@ export interface ExtractValuesTriggerParams {
 }
 /**
  * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
- * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
- * promise.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault and a refused
+ * authorization reject the returned promise. A suspension is the `err` of the result: of the workflow, or of
+ * an authorization that the host refused with the suspend flag.
  */
-export declare function triggerExtractValues(deps: ExtractValuesTriggerDeps, params: ExtractValuesTriggerParams): Promise<ExtractValuesResult>;
-/** Runs one extraction pass for the bound analysis, and gives the raw value map back. */
-export type ExtractionRunner = (requests: readonly ExtractionRequest[]) => Promise<ExtractValuesResult>;
+export declare function triggerExtractValues(deps: ExtractValuesTriggerDeps, params: ExtractValuesTriggerParams): Promise<Result<ExtractValuesResult, Suspension>>;
+/** Runs one extraction pass for the bound analysis, and gives the raw value map back, or the suspension. */
+export type ExtractionRunner = (requests: readonly ExtractionRequest[]) => Promise<Result<ExtractValuesResult, Suspension>>;
 /**
  * Bind the trigger to one analysis and one auth context. The result runs one pass with every request in it.
  */
@@ -119,6 +125,6 @@ export declare function extractionArtifactsFromResult(result: ExtractValuesResul
 /**
  * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
  * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
- * reference.
+ * reference. A suspension is the `err`, and the resolver reports its reason on each reference.
  */
 export declare function createExtractionArm(run: ExtractionRunner): ExtractionArm;

package/dist/tasks/extract-values.js

@@ -12,10 +12,15 @@
  * standing machine exists.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { err, ok } from "neverthrow";
 import { randomUUID } from "node:crypto";
+import { forStep } from "../auth/types.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice, passGate } from "../lib/hooks.js";
 import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
+import { suspensionOfRefusal, suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { EXTRACTION_INPUT_ENV, EXTRACTION_SCRIPT, ExtractValuesResultSchema } from "./extract-values-script.js";
 /** The synthetic run id and step id of the extraction pass. Both are constants shared by every analysis. */
 const EXTRACT_VALUES_RUN_LITERAL = "extract-values";
@@ -85,24 +90,28 @@ export function parseExtractionOutput(result) {
  * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
  * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
  * authorization on every terminal path, and it tears the container down on both paths.
+ *
+ * A chat turn awaits this workflow, thus a suspension is the `err` of the result, and the workflow does not
+ * cancel (workflow-suspension spec). The body does not mark the analysis: the caller reports the suspension.
  */
 export async function runExtractValuesBody(input, deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("extract-values").with({ analysisId: input.analysisId });
     const { analysisId, runSession, requests, ownsMandate = true } = input; // oss-core-managed-ok
     const authorization = { runSession, ownsMandate }; // oss-core-managed-ok
+    const revoke = (reason) => deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, reason));
     try {
         const executionId = generateExecutionId(EXTRACT_VALUES_AGENT_ID);
         const workflowId = DBOS.workflowID ?? `${EXTRACT_VALUES_RUN_LITERAL}:${executionId}`;
         // The container mounts the analysis tree read-only. The extraction pass only reads, thus it needs
         // no writable step mount.
-        const sandbox = await deps.sandboxClient.createSandbox({
-            runId: EXTRACT_VALUES_RUN_LITERAL,
-            stepId: EXTRACT_VALUES_STEP_LITERAL,
-            analysisId,
-            childWorkflowId: workflowId,
-            resources: EXTRACTION_RESOURCES,
-            readOnly: true,
-        }, mintSandboxIdentity(EXTRACT_VALUES_RUN_LITERAL));
+        const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(runSession, EXTRACT_VALUES_STEP_LITERAL), { childWorkflowId: workflowId, resources: EXTRACTION_RESOURCES, readOnly: true }, mintSandboxIdentity(EXTRACT_VALUES_RUN_LITERAL)));
+        if (spawned.isErr()) {
+            const suspension = suspensionOfSpawnRefusal(spawned.error);
+            logger.warn("extraction suspended", { reason: suspension.reason });
+            await revoke("extract-values-suspended");
+            return err(suspension);
+        }
+        const sandbox = spawned.value;
         try {
             // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
             // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
@@ -110,8 +119,8 @@ export async function runExtractValuesBody(input, deps) {
             await deps.sandboxClient.submitExec(sandbox, buildExtractionExec(analysisId, requests, executionId));
             const result = await deps.sandboxClient.awaitExec(sandbox, executionId, noopEmit, deadlineAbs);
             const map = parseExtractionOutput(result);
-            await deps.runAuthorizer.revoke(authorization, "extract-values-completed");
-            return map;
+            await revoke("extract-values-completed");
+            return ok(map);
         }
         finally {
             try {
@@ -124,7 +133,7 @@ export async function runExtractValuesBody(input, deps) {
     }
     catch (err) {
         logger.error("extraction failed", logger.errorFields(err));
-        await deps.runAuthorizer.revoke(authorization, "extract-values-failed");
+        await revoke("extract-values-failed");
         throw err;
     }
 }
@@ -141,18 +150,25 @@ export function extractValuesWorkflowId(analysisId, nonce) {
 }
 /**
  * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
- * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
- * promise.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault and a refused
+ * authorization reject the returned promise. A suspension is the `err` of the result: of the workflow, or of
+ * an authorization that the host refused with the suspend flag.
  */
 export async function triggerExtractValues(deps, params) {
     const { auth, analysisId, requests } = params;
-    const { runSession, ownsMandate } = await deps.runAuthorizer.authorize({
-        // oss-core-managed-ok
+    const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
         auth,
         scope: { kind: "analysis", analysisId },
         provenance: { agentId: EXTRACT_VALUES_AGENT_ID, callPath: [EXTRACT_VALUES_AGENT_ID] },
         frame: { runId: EXTRACT_VALUES_RUN_LITERAL, stepId: EXTRACT_VALUES_STEP_LITERAL },
-    });
+    }));
+    if (authorized.isErr()) {
+        const suspension = suspensionOfRefusal(authorized.error);
+        if (suspension !== undefined)
+            return err(suspension);
+        throw new Error(`the extraction was not authorized: ${authorized.error.reason}`);
+    }
+    const { runSession, ownsMandate } = authorized.value; // oss-core-managed-ok
     const handle = (await DBOS.startWorkflow(deps.workflow, {
         workflowID: extractValuesWorkflowId(analysisId, randomUUID()),
     })({ analysisId, runSession, requests: [...requests], ownsMandate })); // oss-core-managed-ok
@@ -182,12 +198,12 @@ export function extractionArtifactsFromResult(result) {
 /**
  * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
  * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
- * reference.
+ * reference. A suspension is the `err`, and the resolver reports its reason on each reference.
  */
 export function createExtractionArm(run) {
     return {
         async extract(requests) {
-            return extractionArtifactsFromResult(await run(requests));
+            return (await run(requests)).map(extractionArtifactsFromResult);
         },
     };
 }

package/dist/tools/execute-analysis.js

@@ -3,21 +3,23 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import { randomUUID } from "node:crypto";
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../config/resource-limits.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { deliverNotice, passGate } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { buildRunCardData } from "../memory/card-builders.js";
 import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { validatePlan } from "../schemas/validate-plan.js";
-import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, updateRunStatus, upsertPlan } from "../state/index.js";
+import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRunById, suspendAnalysis, updateRunStatus, upsertPlan } from "../state/index.js";
 import { routeAdHocRequest } from "./ad-hoc-router.js";
 import { adHocPlanId, adHocRunId } from "./analysis-invocation.js";
 import { defineTool } from "./define-tool.js";
 import { queryPackages, readInventorySections } from "./sandbox/list-available-packages.js";
+import { callExtendAnalysisFarm } from "./sandbox/link-packages.js";
 const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
 const inputSchema = z
     .object({
@@ -119,16 +121,13 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     const queries = [...union.values()];
     if (queries.length === 0)
         return 0;
-    let outcomes;
-    try {
-        outcomes = await extendAnalysisFarm(analysisId, queries);
-    }
-    catch (cause) {
-        // A realization throw is an `unavailable` answer, not a driver error.
-        // The sibling resolver seam maps a throw the same way (farm.ts), and
-        // the planner can act on "the store cannot answer" — not on a stack.
-        throw new PlanPackagesMissingError([], [], cause instanceof Error ? cause.message : String(cause));
+    const linked = await callExtendAnalysisFarm(extendAnalysisFarm, analysisId, queries);
+    if (linked.isErr()) {
+        // A call that gave no answer is an `unavailable` answer, not a driver
+        // error: the planner can act on "the store cannot answer".
+        throw new PlanPackagesMissingError([], [], linked.error);
     }
+    const outcomes = linked.value;
     // An `unavailable` outcome preempts everything: the link pass could not
     // answer at all (an unreadable graph, a locked farm), so a per-package
     // absence list would be a fabrication. One reason covers the batch.
@@ -383,19 +382,25 @@ export function createExecuteAnalysisTool(deps) {
                     return ok({ runId: reservation.row.runId, status: "in_progress" });
                 }
             }
-            let authorization;
-            try {
-                authorization = await deps.runAuthorizer.authorize({
-                    auth: ctx.session.auth,
-                    scope: ctx.session.scope,
-                    provenance: ctx.session.provenance,
-                    frame: { runId },
-                });
-            }
-            catch (error) {
-                await updateRunStatus(deps.pool, runId, "failed", "run authorization failed").match(() => { }, () => { });
-                throw error;
+            const authorized = await passGate("RunAuthorizer.authorize", deps.runAuthorizer.authorize({
+                auth: ctx.session.auth,
+                scope: ctx.session.scope,
+                provenance: ctx.session.provenance,
+                frame: { runId },
+            }));
+            if (authorized.isErr()) {
+                // The refusal ends the run before a workflow exists, thus the
+                // reserved row must not stay `running`.
+                const { kind, reason } = authorized.error;
+                if (kind === "suspended") {
+                    await updateRunStatus(deps.pool, runId, "canceled", reason).match(() => { }, () => { });
+                    unwrapOrThrow(await suspendAnalysis(deps.pool, analysisId));
+                    return err({ error: `The analysis is suspended: ${reason}`, retryable: false });
+                }
+                await updateRunStatus(deps.pool, runId, "failed", reason).match(() => { }, () => { });
+                return err({ error: `The run was not authorized: ${reason}`, retryable: false });
             }
+            const authorization = authorized.value;
             const wfInput = workflowInput(planId, plan, {
                 analysisId,
                 threadId,
@@ -408,7 +413,7 @@ export function createExecuteAnalysisTool(deps) {
                 await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
             }
             catch (error) {
-                await deps.runAuthorizer.revoke(authorization, "workflow-start-failed").catch(() => { });
+                await deliverNotice(logger, "RunAuthorizer.revoke", deps.runAuthorizer.revoke(authorization, "workflow-start-failed"));
                 await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
                 throw error;
             }

package/dist/tools/report-session/derive-table.d.ts

@@ -33,7 +33,10 @@
  * under the callback transport, and a report turn is not a body. Thus the tool takes an injected runner,
  * and a registered workflow owns the container. The tool holds no sandbox client, and it imports no DBOS.
  */
+import { type Result } from "neverthrow";
 import { z } from "zod";
+import type { RunSession } from "../../auth/types.js";
+import type { Suspension } from "../../workflows/suspension.js";
 import type { RunAuthorizer } from "../../execution/run-authorizer.js";
 import { type Logger } from "../../lib/logger.js";
 import type { ResourceSpec } from "../../config/resource-limits.js";
@@ -90,6 +93,10 @@ export type DeriveTableResult = {
 } | {
     outcome: "exec-failed";
     detail: string;
+} | {
+    outcome: "suspended";
+    reason: string;
+    detail: string;
 } | {
     outcome: "no-output";
     detail: string;
@@ -172,6 +179,7 @@ export declare function describeExecFailure(result: ExecResult): string | undefi
  */
 export interface DeriveTableExecInput {
     readonly analysisId: string;
+    readonly runSession: RunSession;
     readonly executionId: string;
     readonly script: string;
     readonly writableTail: string;
@@ -186,7 +194,7 @@ export interface DeriveTableExecInput {
  * and the await is legal under each transport. A fault of the sandbox rejects the promise, and the tool
  * turns that rejection into one short detail.
  */
-export type DeriveTableRunner = (input: DeriveTableExecInput) => Promise<ExecResult>;
+export type DeriveTableRunner = (input: DeriveTableExecInput) => Promise<Result<ExecResult, Suspension>>;
 /**
  * Make the derivation tool over the session-state gateway, the derivation ledger, and the sandbox rails.
  *

package/dist/tools/report-session/derive-table.js

@@ -38,6 +38,7 @@ import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
+import { deliverNotice, passGate } from "../../lib/hooks.js";
 import { classifyWithinRoot, computeSha256, computeSha256File } from "../../lib/fs-helpers.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { snapshotEntry } from "../../report-model/reference-resolver.js";
@@ -223,19 +224,20 @@ export function createDeriveTableTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "unavailable", detail: "the workspace root did not resolve, thus the derived table has no place to land" });
             }
-            let authorization;
-            try {
-                authorization = await runAuthorizer.authorize({
-                    auth: ctx.session.auth,
-                    scope: { kind: "analysis", analysisId },
-                    provenance: { agentId: DERIVE_AGENT_ID, callPath: [DERIVE_AGENT_ID] },
-                    frame: { runId: DERIVE_RUN_LITERAL, stepId: DERIVE_STEP_LITERAL },
-                });
-            }
-            catch (cause) {
-                logger.error("the derivation was not authorized", { threadId, analysisId, ...defaultErrorFields(cause) });
-                return ok({ outcome: "unavailable", detail: "the derivation was not authorized" });
+            const authorized = await passGate("RunAuthorizer.authorize", runAuthorizer.authorize({
+                auth: ctx.session.auth,
+                scope: { kind: "analysis", analysisId },
+                provenance: { agentId: DERIVE_AGENT_ID, callPath: [DERIVE_AGENT_ID] },
+                frame: { runId: DERIVE_RUN_LITERAL, stepId: DERIVE_STEP_LITERAL },
+            }));
+            if (authorized.isErr()) {
+                const { kind, reason } = authorized.error;
+                logger.error("the derivation was not authorized", { threadId, analysisId, reason, suspend: kind === "suspended" });
+                if (kind === "suspended")
+                    return ok({ outcome: "suspended", reason, detail: `the analysis is suspended (${reason}), thus the derivation did not run` });
+                return ok({ outcome: "unavailable", detail: `the derivation was not authorized: ${reason}` });
             }
+            const authorization = authorized.value;
             // The work sits inside the `try`, and the revoke sits in the `finally`. Thus the authorization
             // revokes on every terminal path, the thrown one included: a path builder refuses a hostile
             // stored path with a throw, and that throw must not leave an authorization standing.
@@ -247,6 +249,7 @@ export function createDeriveTableTool(deps) {
                     root,
                     threadId,
                     analysisId,
+                    runSession: authorization.runSession,
                     script: input.script,
                     sources,
                     writableTail,
@@ -270,14 +273,9 @@ export function createDeriveTableTool(deps) {
                 return ok(result);
             }
             finally {
-                // A revoke fault changes no outcome of the call, thus it reaches the log alone. An absent
-                // result means that the work threw, and a throw is a failed derivation.
-                try {
-                    await runAuthorizer.revoke(authorization, result?.outcome === "derived" ? "derive-table-completed" : "derive-table-failed");
-                }
-                catch (cause) {
-                    logger.warn("the derivation authorization did not revoke", { threadId, analysisId, ...defaultErrorFields(cause) });
-                }
+                // The revoke is a notice: its failure changes no outcome of the call, thus it reaches the log
+                // alone. An absent result means that the work threw, and a throw is a failed derivation.
+                await deliverNotice(logger.with({ threadId, analysisId }), "RunAuthorizer.revoke", runAuthorizer.revoke(authorization, result?.outcome === "derived" ? "derive-table-completed" : "derive-table-failed"));
             }
         },
     });
@@ -318,6 +316,7 @@ async function derive(args) {
     // thus that refusal stays a throw and it never reads as a fault of the container.
     const execInput = {
         analysisId: args.analysisId,
+        runSession: args.runSession,
         executionId,
         script: args.script,
         writableTail: args.writableTail,
@@ -325,14 +324,18 @@ async function derive(args) {
         inputs: args.sources.map((source) => ({ path: toSandboxPath(args.root, args.analysisId, join(args.root, source.path)), hash: source.hash })),
         output: toSandboxPath(args.root, args.analysisId, absolute),
     };
-    let executed;
+    let ran;
     try {
-        executed = await args.runDerivation(execInput);
+        ran = await args.runDerivation(execInput);
     }
     catch (cause) {
         args.logger.error("the derivation exec did not complete", { threadId: args.threadId, ...defaultErrorFields(cause) });
         return { outcome: "exec-failed", detail: "the derivation exec did not complete" };
     }
+    if (ran.isErr()) {
+        return { outcome: "suspended", reason: ran.error.reason, detail: `the analysis is suspended (${ran.error.reason}), thus the derivation did not run` };
+    }
+    const executed = ran.value;
     const failure = describeExecFailure(executed);
     if (failure !== undefined) {
         return { outcome: "exec-failed", detail: failure };

package/dist/tools/report-session/examine-page.d.ts

@@ -37,16 +37,19 @@
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
- * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The URL
+ * seam gives a `Result`. The tool guards each of them, thus a fault of a look becomes a typed outcome and
+ * the loop never sees a throw.
  *
  * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
  * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
  * and no outcome would ever arrive.
  */
+import { type ResultAsync } from "neverthrow";
 import { z } from "zod";
 import type { AuthContext } from "../../auth/types.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
+import type { GateFailure } from "../../lib/hooks.js";
 import { type AcquireEyes } from "../../lib/eyes.js";
 import { type Logger } from "../../lib/logger.js";
 import { type CaptureCoverage, type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
@@ -65,7 +68,7 @@ export type ResolvePageUrl = (args: {
     analysisId: string;
     threadId: string;
     auth: AuthContext;
-}) => Promise<string>;
+}) => ResultAsync<string, GateFailure>;
 /** The empty input. The tool examines the current page of the thread, thus it needs no field. */
 declare const examinePageInput: z.ZodObject<{}, z.core.$strip>;
 export type ExaminePageInput = z.infer<typeof examinePageInput>;

package/dist/tools/report-session/examine-page.js

@@ -37,8 +37,9 @@
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
- * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The URL
+ * seam gives a `Result`. The tool guards each of them, thus a fault of a look becomes a typed outcome and
+ * the loop never sees a throw.
  *
  * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
  * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
@@ -273,14 +274,21 @@ export function createExaminePageTool(deps) {
                 logger.warn("the session page could not be read", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the session page could not be read" });
             }
-            // The URL seam speaks the throw protocol like the other seams, thus a fault of the formation
-            // becomes a typed outcome and the look never starts.
+            // An `err` of the URL seam and a rejected realization each become a typed outcome, and the look
+            // never starts.
             let url;
             try {
-                url =
-                    deps.resolvePageUrl !== undefined
-                        ? await deps.resolvePageUrl({ pagePath, analysisId, threadId, auth: ctx.session.auth })
-                        : pathToFileURL(pagePath).href;
+                if (deps.resolvePageUrl === undefined) {
+                    url = pathToFileURL(pagePath).href;
+                }
+                else {
+                    const resolved = await deps.resolvePageUrl({ pagePath, analysisId, threadId, auth: ctx.session.auth });
+                    if (resolved.isErr()) {
+                        logger.warn("the page URL did not resolve", { threadId, analysisId, reason: resolved.error.reason });
+                        return ok({ outcome: "capture-failed", detail: "the page URL did not resolve" });
+                    }
+                    url = resolved.value;
+                }
             }
             catch (cause) {
                 logger.warn("the page URL did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

package/dist/tools/report-session/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, type SessionPageAccess, } from "./preview-report.js";
 export { createExaminePageTool, type CaptureCoverage, type CapturePage, type ExaminedTile, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
-export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageMintFailure, type SessionPageMintResult, type SessionPagePublisher, } from "./session-page-publisher.js";
+export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageGrant, type SessionPageMintFailure, type SessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
 export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";
 export { createListPinnedArtifactsTool, type ListPinnedArtifactsInput, type ListPinnedArtifactsResult, type ListPinnedArtifactsToolDeps, type PinnedArtifact, type PinnedCitation, } from "./list-artifacts.js";