@inflexa-ai/harness 0.45.1 → 0.46.0

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

@@ -5,11 +5,10 @@
  * The operation owns no table. It composes the reads and the writes that the
  * store, the thread history, and the working memory already give. `getThread`
  * finds the parent, and `latestSeq` gives the anchor. `listThreads` counts the
- * report children, and `createThread` writes the insert. `render` and
- * `appendTurn` make the seed, and `purgeThread` removes a child that holds no
- * seed. The two storage reads that this capability adds, `latestSeq` and
- * `countUserTurnsAfter`, live on the thread history, because that module owns
- * the `messages` table.
+ * report children, and `render` makes the seed. `createThread` writes the row
+ * and the seed in one transaction. The two storage reads that this capability
+ * adds, `latestSeq` and `countUserTurnsAfter`, live on the thread history,
+ * because that module owns the `messages` table.
  *
  * The reads and the insert take no lock and no transaction. A concurrent turn
  * can append between the anchor read and the insert, and a retract can cut the
@@ -18,8 +17,10 @@
  * past the parent's current end is a normal state a reader expects.
  *
  * 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.
+ * operation with no UI in front of it. Thus the caller gives the child id, or
+ * the spawn mints a `randomUUID`, and the spawn returns the full row. A managed
+ * deployment gets the same behavior with no host code. A second spawn with the
+ * id of a child gives that child, and it writes nothing.
  *
  * 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.
@@ -32,9 +33,9 @@
  * The spawn seeds the context of the child at the anchor. It writes one message
  * that holds the brief and a copy of the working-memory render. The transcript
  * is append-only, thus the copy stays frozen at the anchor by construction, and
- * a later change to the working memory leaves it as it is. When the seed write
- * fails, the spawn purges the child, because a report thread with no context is
- * a dead end.
+ * a later change to the working memory leaves it as it is. The row and the seed
+ * commit in one transaction, because a report thread with no context is a dead
+ * end.
  *
  * The seed takes no redaction pass, and that is deliberate. The two parts are
  * agent-authored, the same trust tier as the working-memory render of a
@@ -169,34 +170,14 @@ export function createReportSessionSpawn(deps) {
     // An unbound member gives a call that does nothing, thus the spawn emits at
     // one site with no test of its own.
     const observe = bindSessionEmit(deps.provenance, log);
-    /**
-     * Write the one seed message of the child and give the child back. The
-     * message rides as a record, not as user input: nobody typed it in the child
-     * thread, and a record is displayed but it never opens a turn.
-     */
-    function seedChildContext(child, brief) {
-        return workingMemory
-            .render(child.analysisId)
-            .andThen((memory) => history.appendTurn(child.threadId, conversationRecordTurn(composeSeed(brief, memory))))
-            .map(() => child)
-            .orElse((fault) => 
-        // A report thread with no context is a dead end, thus the purge
-        // removes the child. The seed fault is the cause, thus it returns
-        // from each route. A failed purge leaves the child, and the caller
-        // still reads why the seed stopped.
-        store
-            .purgeThread(child.threadId)
-            .andThen(() => errAsync(fault))
-            .orElse(() => errAsync(fault)));
-    }
     /**
      * Pin the data snapshot of the child, through the injected anchor operation.
      * The spawn mints one moment, and the transcript anchor and this snapshot are
      * the two pins of that moment.
      *
-     * The pin runs after the seed. A failed seed purges the child, and
+     * The pin runs after the row and the seed commit.
      * `cortex_report_session_state` carries no foreign key to the thread table,
-     * thus a pin before a purged seed would leave an orphan row.
+     * thus a pin before a failed create would leave an orphan row.
      *
      * A failed pin keeps the child. The operation is idempotent, thus the first
      * session tool call pins again, and a purge on a transient store fault would
@@ -247,7 +228,7 @@ export function createReportSessionSpawn(deps) {
             return collectReportChildren(analysisId, parentThreadId, page + 1, all);
         });
     }
-    function spawnReportSession(parentThreadId, brief) {
+    function spawnReportSession(parentThreadId, brief, childThreadId = randomUUID()) {
         // 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.
@@ -274,18 +255,22 @@ export function createReportSessionSpawn(deps) {
                 // The result is two titles a user renames, and no identifier collides.
                 return store
                     .listThreads({ analysisId: parent.analysisId, type: "report", parentThreadId })
-                    .andThen((children) => store
-                    .createThread({
-                    threadId: randomUUID(),
+                    .andThen((children) => 
+                // The render follows the anchor read, thus the copy of the
+                // working memory is the state at the anchor.
+                workingMemory
+                    .render(parent.analysisId)
+                    .andThen((memory) => store.createThread({
+                    threadId: childThreadId,
                     analysisId: parent.analysisId,
                     title: composeTitle(parent.title, children.total + 1),
                     type: "report",
                     parentThreadId,
                     parentSeq: anchor,
-                })
-                    // The seed follows the insert, thus the copy of the working
-                    // memory is the state at the anchor.
-                    .andThen((child) => seedChildContext(child, brief))
+                    // The seed rides as a record, not as user input: nobody typed it in
+                    // the child thread, and a record is displayed but it never opens a turn.
+                    firstTurn: conversationRecordTurn(composeSeed(brief, memory)),
+                }))
                     // The pin follows the seed. `pinSessionSnapshot` never
                     // rejects, thus the safe bridge adds no error variant.
                     .andThen((child) => ResultAsync.fromSafePromise(pinSessionSnapshot(child))));

package/dist/app/synthesize-run.d.ts

@@ -14,23 +14,23 @@
  * honest non-fatal outcomes (no summaries, blocker) return empty findings after
  * a `skipped` phase.
  */
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import type { SynthesisPhase } from "@inflexa-ai/harness/contracts/chat-parts.js";
 import type { RunSession } from "../auth/types.js";
+import type { LoopOptions } from "../loop/run-loop.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { EmitFn } from "../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
-import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { RunFinding } from "../workflows/execute-analysis.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { SynthesisStatus } from "../state/index.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
-import type { CitationResolver } from "../citations/types.js";
-export interface SynthesizeRunDeps {
+import type { Tool } from "../tools/define-tool.js";
+export type SynthesizeRunDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-    readonly pool: Pool;
+    readonly pool: Querier;
     readonly provider: ChatProvider;
     /** Write-side embedder — its `dimensions` sizes the per-analysis index. */
     readonly embedding: EmbeddingProvider;
@@ -38,22 +38,20 @@ export interface SynthesizeRunDeps {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Model id for the synthesizer agent loop. */
     readonly synthesisModel: string;
-    /** API keys for the bio/chem tools the embedded literature reviewer uses. */
-    readonly bioKeys: BioToolKeys;
-    /** Shared resolver used by the embedded literature reviewer. */
-    readonly citationResolver: CitationResolver;
+    /** The `literature_reviewer` tool of the synthesizer. */
+    readonly literatureReviewer: Tool;
     /** LLM usage-accounting seam for the synthesizer loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** The store of the synthesizer and reviewer loops and of their read tools. */
     readonly toolOutputStore?: ToolOutputStore;
-}
+};
 /** Optional fields for a progress update, mirroring the wire part. */
-export interface SynthesisProgressExtra {
+export type SynthesisProgressExtra = {
     readonly delegationCount?: number;
     readonly reason?: string;
     readonly error?: string;
-}
-export interface SynthesizeRunParams {
+};
+export type SynthesizeRunParams = {
     readonly analysisId: string;
     readonly runId: string;
     readonly completedSteps: readonly string[];
@@ -62,10 +60,18 @@ export interface SynthesizeRunParams {
     readonly emit: EmitFn;
     /** Domain progress callback — the phases the run-completed UI renders. */
     readonly onProgress: (phase: SynthesisPhase, activity: string, extra?: SynthesisProgressExtra) => void | Promise<void>;
-}
-export interface SynthesizeRunResult {
+    /**
+     * Run a read or a write of the synthesis once: a step in the body of a workflow, a plain call in a process. The
+     * loop of the synthesizer runs outside it, thus each of its model calls is a step of its own, and each reviewer
+     * call starts a child workflow.
+     */
+    readonly durably: <T>(name: string, run: () => Promise<T>) => Promise<T>;
+    /** The pause of the run, for the loop of the synthesizer. Absent: a failed request fails the synthesis. */
+    readonly pause?: LoopOptions["pause"];
+};
+export type SynthesizeRunResult = {
     readonly findings: readonly RunFinding[];
     readonly synthesisStatus: Exclude<SynthesisStatus, "failed">;
     readonly synthesisReason: string | null;
-}
+};
 export declare function synthesizeRun(deps: SynthesizeRunDeps, params: SynthesizeRunParams): Promise<SynthesizeRunResult>;

package/dist/app/synthesize-run.js

@@ -14,6 +14,9 @@
  * honest non-fatal outcomes (no summaries, blocker) return empty findings after
  * a `skipped` phase.
  */
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
+import { z } from "zod";
 import { forSubAgent } from "../auth/types.js";
 import { buildRunSynthesisPart, formatSynthesisEmbeddingText, generateRunSynthesis, loadStepSummariesFromDisk, persistSynthesis, } from "../execution/run-synthesis.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
@@ -22,15 +25,13 @@ import { loadPlan, queryRun } from "../state/index.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 export async function synthesizeRun(deps, params) {
-    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys, citationResolver, usageRecorder } = deps;
-    const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
+    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, literatureReviewer, usageRecorder } = deps;
+    const { analysisId, runId, completedSteps, session, emit, onProgress, durably, pause } = params;
     await onProgress("starting", "Beginning literature-grounded synthesis");
     try {
-        const workspaceRoot = await resolveWorkspaceRoot(analysisId);
-        const summaries = await loadStepSummariesFromDisk({
-            workspaceRoot,
-            runId,
-            completedSteps,
+        const { workspaceRoot, summaries } = await durably("synthesis.read-summaries", async () => {
+            const root = await resolveWorkspaceRoot(analysisId);
+            return { workspaceRoot: root, summaries: await loadStepSummariesFromDisk({ workspaceRoot: root, runId, completedSteps }) };
         });
         if (summaries.length === 0) {
             const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
@@ -40,20 +41,20 @@ export async function synthesizeRun(deps, params) {
             });
             return { findings: [], synthesisStatus: "skipped_no_summaries", synthesisReason: "no-summaries" };
         }
-        const planNarrative = await loadPlanNarrative(pool, runId, analysisId);
+        const planNarrative = await durably("synthesis.read-plan", () => loadPlanNarrative(pool, runId, analysisId));
         const synthesizerSession = forSubAgent(session, "run-synthesizer");
         const result = await generateRunSynthesis({
             provider,
             session: synthesizerSession,
             model: synthesisModel,
-            bioKeys,
-            citationResolver,
+            literatureReviewer,
             usageRecorder,
-            ...(deps.toolOutputStore ? { toolOutputStore: deps.toolOutputStore } : {}),
+            toolOutputStore: deps.toolOutputStore,
             summaries,
             planNarrative,
             runId,
             emit,
+            pause,
         });
         if (result.kind === "skipped") {
             const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
@@ -68,27 +69,29 @@ export async function synthesizeRun(deps, params) {
         }
         const synthesis = result.synthesis;
         await onProgress("indexing", "Indexing synthesis for search");
-        try {
-            await ensureSearchIndex(pool, analysisId, embedding.dimensions);
-            const vectorStore = createVectorStore(pool);
-            const indexName = searchIndexName(analysisId);
-            const synthesisText = formatSynthesisEmbeddingText(synthesis);
-            const [vector] = unwrapOrThrow(await embedding.embed([synthesisText], synthesizerSession));
-            if (!vector)
-                throw new Error("synthesize-run: empty embedding response");
-            unwrapOrThrow(await vectorStore.upsert({
-                indexName,
-                vectors: [vector],
-                metadata: [{ text: synthesisText, type: "synthesis", runId, path: `runs/${runId}/synthesis.json` }],
-                ids: [`/${analysisId}/runs/${runId}/synthesis.json`],
-            }));
-        }
-        catch (indexErr) {
-            const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
-            logger.warn("vector indexing failed", { runId, ...logger.errorFields(indexErr) });
-        }
+        await durably("synthesis.index", async () => {
+            try {
+                await ensureSearchIndex(pool, analysisId, embedding.dimensions);
+                const vectorStore = createVectorStore(pool);
+                const indexName = searchIndexName(analysisId);
+                const synthesisText = formatSynthesisEmbeddingText(synthesis);
+                const [vector] = unwrapOrThrow(await embedding.embed([synthesisText], synthesizerSession));
+                if (!vector)
+                    throw new Error("synthesize-run: empty embedding response");
+                unwrapOrThrow(await vectorStore.upsert({
+                    indexName,
+                    vectors: [vector],
+                    metadata: [{ text: synthesisText, type: "synthesis", runId, path: `runs/${runId}/synthesis.json` }],
+                    ids: [`/${analysisId}/runs/${runId}/synthesis.json`],
+                }));
+            }
+            catch (indexErr) {
+                const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
+                logger.warn("vector indexing failed", { runId, ...logger.errorFields(indexErr) });
+            }
+        });
         await onProgress("persisting", "Persisting synthesis");
-        await persistSynthesis({ workspaceRoot, runId, synthesis });
+        await durably("synthesis.persist", () => persistSynthesis({ workspaceRoot, runId, synthesis }));
         await emit(buildRunSynthesisPart(runId, synthesis));
         await onProgress("complete", "Literature-grounded synthesis ready");
         return {
@@ -101,11 +104,11 @@ export async function synthesizeRun(deps, params) {
         };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errorMessageOf(err) ?? textOf(err);
         await onProgress("failed", "Synthesis could not be completed — step summaries are still available", { error: msg });
         // A genuine synthesis failure must fail the run loudly (D10): re-throw so
-        // the synthesis step errors and the parent workflow goes to ERROR. The
-        // honest non-fatal outcomes (no-summaries / blocker) early-return above.
+        // the parent workflow goes to ERROR. The honest non-fatal outcomes
+        // (no-summaries / blocker) early-return above.
         throw err;
     }
 }
@@ -115,5 +118,8 @@ async function loadPlanNarrative(pool, runId, analysisId) {
     if (!planId)
         return "";
     const plan = unwrapOrThrow(await loadPlan(pool, planId, { analysisId }));
-    return plan?.analytical_narrative ?? "";
+    const parsed = PlanNarrativeSchema.nullable().catch(null).parse(plan);
+    return parsed?.analytical_narrative ?? "";
 }
+/** The one field of the stored plan document this reader takes; every other field passes. */
+const PlanNarrativeSchema = z.looseObject({ analytical_narrative: z.string().optional() });

package/dist/app/work.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The durable work of an analysis, as a host lists, stops, resumes, and holds it (work-pause spec).
+ *
+ * A work is a chat turn, a run, or a data profile. Each work that is active is in the list, and a work that waits
+ * in a pause carries each of its waiting workflows. One work can have more than one waiting workflow: a sub-agent
+ * of a turn and each step of a run wait in their own workflows. A stop ends a work in each state. A resume and a
+ * hold reach only a work that waits. Only a client resumes paused work.
+ */
+import type { PauseCause, WorkKind } from "../contracts/chat-parts.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { RunCanceler } from "../execution/run-canceler.js";
+import type { Logger } from "../lib/logger.js";
+import type { Querier } from "../state/db.js";
+import type { ChatTurnSession } from "./chat-turn.js";
+/** One waiting workflow of a paused work. */
+export type PausedWorkflow = {
+    readonly workflowId: string;
+    readonly state: "retrying" | "paused";
+    readonly cause: PauseCause;
+    /** The count of timer retries before this wait. */
+    readonly attempt: number;
+    /** ISO 8601. Present for the state `retrying` only. */
+    readonly retryAt?: string;
+    /** ISO 8601. */
+    readonly pausedAt: string;
+};
+/** One active work: a turn, a run, or a data profile. */
+export type Work = {
+    /** The turn id, the run id, or the id of the profile workflow. */
+    readonly workId: string;
+    readonly kind: WorkKind;
+    readonly analysisId: string;
+    readonly threadId?: string;
+    /** Each waiting workflow of the work. Empty for a work that runs. */
+    readonly waiting: readonly PausedWorkflow[];
+};
+export type WorkStop = {
+    readonly kind: "stopped";
+    readonly work: Work;
+} | {
+    readonly kind: "not_found";
+};
+export type WorkResume = {
+    readonly kind: "resumed";
+    readonly workflows: number;
+} | {
+    readonly kind: "not_found";
+}
+/** The host refused to renew the run credential under the session, thus the work stays paused. */
+ | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/** `workflows` is the count of waits in `retrying` that the hold reached. A wait in `paused` needs no hold. */
+export type WorkHold = {
+    readonly kind: "held";
+    readonly workflows: number;
+} | {
+    readonly kind: "not_found";
+};
+/** The durable work of a runtime, as a host uses it. */
+export type WorkSurface = {
+    /**
+     * The active work of an analysis: each turn that holds a thread, each `running` run, and the profile that runs.
+     * A pause row whose workflow ended is not in it, and the list deletes that row.
+     */
+    list(analysisId: string): Promise<Work[]>;
+    /**
+     * Stop the work, in each state: a turn stops, a run cancels with its children, and a profile fails. Work of a
+     * different analysis than the session gives `not_found`.
+     */
+    stop(session: ChatTurnSession, workId: string): Promise<WorkStop>;
+    /**
+     * Resume the work: each of its waiting workflows sends its request again. A wait in `retrying` ends at once, thus
+     * the same call is "retry now". For a turn, the credential of the session goes to the turn first. For a run or a
+     * profile, the host renews the run credential under the session first, and a refusal sends nothing. Work of a
+     * different analysis than the session gives `not_found`.
+     */
+    resume(session: ChatTurnSession, workId: string): Promise<WorkResume>;
+    /**
+     * Hold the work: each of its waits in `retrying` moves to `paused`, and its timer stops. The work then waits for a
+     * resume. Work of a different analysis than the session gives `not_found`.
+     */
+    hold(session: ChatTurnSession, workId: string): Promise<WorkHold>;
+};
+export type WorkDeps = {
+    readonly pool: Querier;
+    readonly runAuthorizer: RunAuthorizer;
+    readonly logger?: Logger;
+    /** The stop of a chat turn. */
+    readonly stopTurn: (turnId: string) => Promise<void>;
+    readonly runCanceler: RunCanceler;
+    /** The stop of the profile workflow of an analysis. */
+    readonly stopProfile: (analysisId: string, workflowId: string) => Promise<void>;
+};
+export declare function createWork(deps: WorkDeps): WorkSurface;

package/dist/app/work.js

@@ -0,0 +1,147 @@
+/**
+ * The durable work of an analysis, as a host lists, stops, resumes, and holds it (work-pause spec).
+ *
+ * A work is a chat turn, a run, or a data profile. Each work that is active is in the list, and a work that waits
+ * in a pause carries each of its waiting workflows. One work can have more than one waiting workflow: a sub-agent
+ * of a turn and each step of a run wait in their own workflows. A stop ends a work in each state. A resume and a
+ * hold reach only a work that waits. Only a client resumes paused work.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { passGate } from "../lib/hooks.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { turnCredentials } from "../loop/turn-credentials.js";
+import { queryTurnsOfAnalysis } from "../state/active-turns.js";
+import { loadDataProfileStatus } from "../state/data-profile.js";
+import { clearPauses, queryPausesOfAnalysis, queryPausesOfWork } from "../state/paused-work.js";
+import { queryActiveRunsByAnalysis } from "../state/runs.js";
+import { HOLD_MESSAGE, RESUME_MESSAGE } from "../workflows/pause.js";
+/** The workflow statuses that can still wait. */
+const ACTIVE_STATUSES = new Set(["PENDING", "ENQUEUED"]);
+/** The provenance of a run cancel that a stop of work makes. */
+const WORK_STOP_PROVENANCE = { agentId: "work-stop", callPath: ["work-stop"] };
+function workflowOf(record) {
+    return {
+        workflowId: record.workflowId,
+        state: record.state,
+        cause: record.cause,
+        attempt: record.attempt,
+        retryAt: record.retryAt,
+        pausedAt: record.pausedAt,
+    };
+}
+async function activeWorkflows(workflowIds) {
+    if (workflowIds.length === 0)
+        return new Set();
+    const statuses = await DBOS.listWorkflows({ workflowIDs: [...workflowIds], loadInput: false, loadOutput: false });
+    return new Set(statuses.filter((status) => ACTIVE_STATUSES.has(status.status)).map((status) => status.workflowID));
+}
+export function createWork(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.work");
+    async function list(analysisId) {
+        const [records, turns, runs, profile] = await Promise.all([
+            (async () => unwrapOrThrow(await queryPausesOfAnalysis(deps.pool, analysisId)))(),
+            (async () => unwrapOrThrow(await queryTurnsOfAnalysis(deps.pool, analysisId)))(),
+            (async () => unwrapOrThrow(await queryActiveRunsByAnalysis(deps.pool, analysisId)))(),
+            (async () => unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId)))(),
+        ]);
+        const profileWorkflowId = profile?.status === "running" ? (profile.workflowId ?? undefined) : undefined;
+        const active = await activeWorkflows([
+            ...records.map((record) => record.workflowId),
+            ...turns.map((turn) => turn.turnId),
+            ...(profileWorkflowId === undefined ? [] : [profileWorkflowId]),
+        ]);
+        const ended = records.filter((record) => !active.has(record.workflowId)).map((record) => record.workflowId);
+        if (ended.length > 0) {
+            const cleared = await clearPauses(deps.pool, ended);
+            if (cleared.isErr())
+                logger.warn("the rows of ended pauses did not clear", { op: cleared.error.op, workflows: ended.length });
+        }
+        const waitingOf = new Map();
+        for (const record of records) {
+            if (!active.has(record.workflowId))
+                continue;
+            waitingOf.set(record.workId, [...(waitingOf.get(record.workId) ?? []), workflowOf(record)]);
+        }
+        const work = new Map();
+        const add = (workId, kind, threadId) => {
+            if (work.has(workId))
+                return;
+            work.set(workId, { workId, kind, analysisId, threadId, waiting: waitingOf.get(workId) ?? [] });
+        };
+        // A claim can outlive its turn, thus a turn is active while its workflow is. A `running` run is active while
+        // its row is, because the run canceler also converges a row whose workflow ended.
+        for (const turn of turns)
+            if (active.has(turn.turnId))
+                add(turn.turnId, "turn", turn.threadId);
+        for (const run of runs)
+            add(run.runId, "run", run.threadId ?? undefined);
+        if (profileWorkflowId !== undefined && active.has(profileWorkflowId))
+            add(profileWorkflowId, "profile", undefined);
+        for (const record of records)
+            if (active.has(record.workflowId))
+                add(record.workId, record.workKind, record.threadId);
+        return [...work.values()];
+    }
+    return {
+        list,
+        async stop(session, workId) {
+            const work = (await list(session.scope.analysisId)).find((candidate) => candidate.workId === workId);
+            if (work === undefined)
+                return { kind: "not_found" };
+            switch (work.kind) {
+                case "turn":
+                    await deps.stopTurn(workId);
+                    break;
+                case "run": {
+                    const { outcome, converged } = await deps.runCanceler.cancel(workId, { ...session, provenance: WORK_STOP_PROVENANCE });
+                    // A run that ended before the cancel converged nothing, and needs nothing.
+                    if (outcome === "canceled" && !(converged.steps && converged.charge && converged.mandate)) {
+                        logger.warn("the stop of a run did not converge", { workId, ...converged });
+                    }
+                    break;
+                }
+                case "profile":
+                    await deps.stopProfile(work.analysisId, workId);
+                    break;
+                default: {
+                    const exhaustive = work.kind;
+                    throw new Error(`unknown work kind: ${String(exhaustive)}`);
+                }
+            }
+            logger.info("work stopped", { workId, kind: work.kind });
+            return { kind: "stopped", work };
+        },
+        async resume(session, workId) {
+            const records = unwrapOrThrow(await queryPausesOfWork(deps.pool, session.scope.analysisId, workId));
+            if (records.length === 0)
+                return { kind: "not_found" };
+            // Each workflow of one work holds the same run credential, thus one renewal covers the work.
+            const runSession = records.find((record) => record.runSession !== undefined)?.runSession;
+            if (runSession !== undefined) {
+                const renewed = await passGate("RunAuthorizer.renew", deps.runAuthorizer.renew(runSession, session.auth));
+                if (renewed.isErr()) {
+                    logger.warn("work resume refused", { workId, reason: renewed.error.reason });
+                    return { kind: "refused", reason: renewed.error.reason };
+                }
+            }
+            if (records.some((record) => record.workKind === "turn"))
+                turnCredentials.put(workId, session.auth);
+            // One send for each waiting workflow of the work. The key of the send is the topic of its pause, thus a
+            // second resume of the same pause sends nothing new.
+            await Promise.all(records.map((record) => DBOS.send(record.workflowId, RESUME_MESSAGE, record.topic, record.topic)));
+            logger.info("work resumed", { workId, workflows: records.length });
+            return { kind: "resumed", workflows: records.length };
+        },
+        async hold(session, workId) {
+            const records = unwrapOrThrow(await queryPausesOfWork(deps.pool, session.scope.analysisId, workId));
+            if (records.length === 0)
+                return { kind: "not_found" };
+            const retrying = records.filter((record) => record.state === "retrying");
+            // The key of the send names the pause, thus a second hold of the same pause sends nothing new.
+            await Promise.all(retrying.map((record) => DBOS.send(record.workflowId, HOLD_MESSAGE, record.topic, `${record.topic}:hold`)));
+            logger.info("work held", { workId, workflows: retrying.length });
+            return { kind: "held", workflows: retrying.length };
+        },
+    };
+}

package/dist/auth/local-auth-context.d.ts

@@ -12,8 +12,6 @@
 import type { AuthContext } from "./types.js";
 /**
  * Build the trivial opaque `auth` value an OSS session constructor stores.
- * Returned as `AuthContext` so callers stay credential-blind. The cast bridges
- * the empty literal to the phantom-branded interface; the brand is an optional
- * `never`, so no real field is fabricated.
+ * Returned as `AuthContext` so callers stay credential-blind.
  */
 export declare function makeLocalAuth(): AuthContext;

package/dist/auth/local-auth-context.js

@@ -11,9 +11,7 @@
  */
 /**
  * Build the trivial opaque `auth` value an OSS session constructor stores.
- * Returned as `AuthContext` so callers stay credential-blind. The cast bridges
- * the empty literal to the phantom-branded interface; the brand is an optional
- * `never`, so no real field is fabricated.
+ * Returned as `AuthContext` so callers stay credential-blind.
  */
 export function makeLocalAuth() {
     return {};

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

@@ -3,7 +3,7 @@
  *
  * Issues a durable `RunSession` straight from the async-edge input: no remote
  * authorization, no credential read. It owns nothing revocable (it mints no
- * jti), so `revoke` and `revokeByJti` are no-ops. The opaque caller `auth` is
+ * reference), so `revoke`, `revokeByMandateId`, `suspend`, and `renew` are no-ops. The opaque caller `auth` is
  * forwarded untouched — local code never
  * inspects it (no `getAuth`).
  */

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

@@ -3,7 +3,7 @@
  *
  * Issues a durable `RunSession` straight from the async-edge input: no remote
  * authorization, no credential read. It owns nothing revocable (it mints no
- * jti), so `revoke` and `revokeByJti` are no-ops. The opaque caller `auth` is
+ * reference), so `revoke`, `revokeByMandateId`, `suspend`, and `renew` are no-ops. The opaque caller `auth` is
  * forwarded untouched — local code never
  * inspects it (no `getAuth`).
  */
@@ -18,9 +18,11 @@ export function createLocalRunAuthorizer() {
                 runFrame: frame,
                 auth,
             };
-            return okAsync({ runSession, ownsMandate: false }); // oss-core-managed-ok
+            return okAsync(runSession);
         },
         revoke: () => okAsync(undefined),
-        revokeByJti: () => okAsync(undefined),
+        revokeByMandateId: () => okAsync(undefined), // oss-core-managed-ok
+        suspend: () => okAsync(undefined),
+        renew: () => okAsync(undefined),
     };
 }