@inflexa-ai/harness 0.47.0 → 0.48.1

package/README.md

@@ -50,7 +50,7 @@ No embedder drives the agent loop. A host opens a chat turn with the `open` of `
 
 A failure that a person or time can repair pauses a turn, a run, or a data profile, and the work does not fail. Examples are a billing refusal of the host, a provider outage, and a missing credential. A host lists the active work of an analysis with `CoreRuntime.work`. It stops a work in each state, and it resumes or holds paused work.
 
-`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **four capability seams** an embedder wires — `RunAuthorizer`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all four ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface. Two optional hooks go into the component that uses their values: `resolveRequestHeaders` into each provider, and `resolveSandboxLabels` into the sandbox client config.
+`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **four capability seams** an embedder wires — `RunAuthorizer`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all four ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface. Two optional hooks go into the component that uses their values: `resolveRequestHeaders` into each provider, and `resolveSandboxLabels` into the sandbox client config. A third, `syncSessionFile`, goes into `assembleCoreRuntime`: it receives each file that a chat thread or a report session writes outside a run.
 
 ## Logging
 

package/dist/agents/conversation-agent.d.ts

@@ -42,6 +42,7 @@ import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
+import type { SyncSessionFile } from "../workspace/session-files.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
@@ -142,6 +143,11 @@ export type ConversationAgentDeps = EnvironmentStorePaths & {
      * `write-file` session event for each successful write.
      */
     readonly provenance?: ProvenanceSeam;
+    /**
+     * The host copy of each file that the agent writes: a derived file or a script of `run_script`, owned by the
+     * thread, and a `write_file` or `edit_file` write, owned by the analysis. See `SyncSessionFile`.
+     */
+    readonly syncSessionFile?: SyncSessionFile;
     /**
      * Embedder-contributed conversation-tool seam — additional tools the host
      * supplies, appended after the built-in roster. The harness stays agnostic to

package/dist/agents/conversation-agent.js

@@ -66,6 +66,7 @@ export function createConversationAgent(deps) {
     const mutator = createSessionWorkspaceMutator({
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
         provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
         logger: deps.logger,
     });
     // The scratch directory of each conversation: the scripts of `run_script`, and the files that they derive.
@@ -73,6 +74,7 @@ export function createConversationAgent(deps) {
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
         sessionDir: conversationSessionDir,
         provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
         logger: deps.logger,
     });
     // The lookups and the light work on tables run in a script (`run_script`). Each tool asks no approval, and a

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

@@ -39,6 +39,7 @@ 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 { ProvenanceSeam } from "../provenance/seam.js";
+import type { SyncSessionFile } from "../workspace/session-files.js";
 import { type MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
 import type { ScriptRuntime } from "../tools/script/run-script.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
@@ -119,6 +120,8 @@ export type ReportSessionAgentDeps = {
      * document. An unbound member emits nothing, or gives absence, and every tool acts the same.
      */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that the session writes. See `SyncSessionFile`. */
+    readonly syncSessionFile?: SyncSessionFile;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** Adds `read_tool_output`. The loop of a report turn must keep its texts in the same store. */

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

@@ -55,7 +55,7 @@ export const REPORT_SESSION_PROVIDER_OPTIONS = {
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, makeSessionPages, resolvePageUrl, provenance } = deps;
+    const { derivations, makeSessionPages, resolvePageUrl, provenance, syncSessionFile } = deps;
     // The seam rides into each tool that lands an act of the session, thus the composition binds it one
     // time and no tool reads a second source.
     const observation = provenance ? { provenance } : {};
@@ -70,15 +70,7 @@ export function createReportSessionAgent(deps) {
         createWorkspaceSearchTool(pool, embedding),
         createInspectRunTool(pool),
         createInspectDataProfileTool(pool),
-        // The composition surface. Each authoring tool binds to the gateway, thus
-        // two threads never share one draft.
-        authoring.add_block,
-        authoring.change_block,
-        authoring.remove_block,
-        authoring.move_block,
-        authoring.set_title,
-        authoring.read_outline,
-        authoring.read_block,
+        // The gate of the draft. The edits of the draft are script tools below.
         authoring.finish_draft,
         // The orientation source of the pinned evidence. It reads the snapshot of the
         // thread, and it resolves the workspace root per call for the header columns.
@@ -123,11 +115,20 @@ export function createReportSessionAgent(deps) {
     ];
     // A derivation of a table of up to the read cap runs in a script, thus it starts no container. The scripts
     // of a session stay beside its page.
-    const scriptScratch = createScriptScratch({ resolveWorkspaceRoot, sessionDir: reportSessionDir, provenance, logger });
+    const scriptScratch = createScriptScratch({ resolveWorkspaceRoot, sessionDir: reportSessionDir, provenance, syncSessionFile, logger });
     // A PDF of the report is a document that a script builds from the content of the session, not a print of the
     // page. Its images come from the directory of the session alone, thus no unpinned file reaches it.
     const scriptTools = [
-        ...createReportScriptTools({ gateway, workspaceFs, resolveWorkspaceRoot, derivations, provenance, logger }),
+        // The edits of the draft. Each binds to the gateway, thus two threads never share one draft, and a script
+        // builds a section in one call. A refused edit comes back as data, thus the script reads `applied`.
+        authoring.add_block,
+        authoring.change_block,
+        authoring.remove_block,
+        authoring.move_block,
+        authoring.set_title,
+        authoring.read_outline,
+        authoring.read_block,
+        ...createReportScriptTools({ gateway, workspaceFs, resolveWorkspaceRoot, derivations, provenance, syncSessionFile, logger }),
         createReadPdfTool({ workspaceFs, resolveWorkspaceRoot }),
         ...createDocumentTools({
             workspaceFs,

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export type { BioToolKeys } from "./tools/bio/keys.js";
 export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
 export type { RunAuthorizer, AuthorizeRunInput, RevokeByMandateRef } from "./execution/run-authorizer.js";
 export type { GateFailure, NoticeFailure } from "./lib/hooks.js";
+export type { SessionFileOwner, SessionFileWrite, SyncSessionFile } from "./workspace/session-files.js";
 export type { RequestHeaders, ResolveRequestHeaders } from "./providers/request-headers.js";
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
 export type { RunCharge, RunChargeOutcome } from "./billing/run-charge.js";
@@ -189,11 +190,12 @@ export { planGraphOf } from "./workflows/plan/graph.js";
 export { planPartOf } from "./memory/card-builders.js";
 export { validatePlan } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
-export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
-export type { UpsertPlanInput, PlanRecord } from "./state/plans.js";
+export { upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./state/plans.js";
+export type { UpsertPlanInput, PlanRecord, PlanPage, PlanPageEntry } from "./state/plans.js";
 export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export type { InsertRunInput, RunReservation } from "./state/runs.js";
-export { queryStepsByRun } from "./state/step-executions.js";
+export { queryStepsByRun, countStepsByRuns } from "./state/step-executions.js";
+export type { RunStepCounts } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus, TerminalRunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";

package/dist/index.js

@@ -293,9 +293,10 @@ export { validatePlan } from "./schemas/validate-plan.js";
 // Plan + run + step ledgers around a trigger. `upsertPlan` takes a
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
-export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
+export { upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./state/plans.js";
 export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, markRunCanceledIfActive, queryRun, queryRunsByAnalysis, countRunsByAnalysis, queryRunIdsByPlan, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
-export { queryStepsByRun } from "./state/step-executions.js";
+// The step ledger reads of a run, and the step counts of each run of a list in one statement.
+export { queryStepsByRun, countStepsByRuns } from "./state/step-executions.js";
 // Host-neutral reference-data catalog and shared installation receipts. Each
 // artifact names the third-party upstream it is fetched from; embedders own all
 // transfer/storage behavior but never choose a different source.

package/dist/lib/hooks.d.ts

@@ -50,7 +50,7 @@ export type NoticeFailure = {
     readonly reason: string;
 };
 export type GateName = "RunAuthorizer.authorize" | "RunAuthorizer.renew" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
-export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByMandateId" | "RunAuthorizer.suspend" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record" | "notifyDataProfileSettled";
+export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByMandateId" | "RunAuthorizer.suspend" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record" | "notifyDataProfileSettled" | "syncSessionFile";
 export type GateRefusal = {
     readonly kind: "failed";
     readonly gate: GateName;

package/dist/loop/chat-stream.js

@@ -116,7 +116,8 @@ export function createTurnStreamWriter(rootSource, observe) {
             return;
         // A tool step gives its frames to the library, which checkpoints each one that is not progress.
         if (DBOS.isInStep()) {
-            toolWriter().write(chunkOfFrame(frame, isProgressFrame(frame)));
+            const liveOnly = "transient" in event && event.transient === true;
+            toolWriter().write(chunkOfFrame(frame, liveOnly || isProgressFrame(frame)));
             return;
         }
         await write(frame);

package/dist/loop/types.d.ts

@@ -130,6 +130,11 @@ export type ChatDataPart = {
      * routing envelopes).
      */
     readonly source?: EventSource;
+    /**
+     * Live only. Inside a tool step the chat stream writes the part as progress: a live reader gets it, and the step
+     * does not checkpoint it. Give it to a copy that a later part of the same reconciling id replaces.
+     */
+    readonly transient?: boolean;
 };
 /**
  * The flat event sink. One function reference flows unchanged through

package/dist/prompts/report-session.d.ts

@@ -1 +1 @@
-export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user from typed blocks, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\nYou read the analysis, and you hold no tool that runs it or changes it.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and in a targeted way: `inspect_data_profile`\nfor a fact about the dataset, `inspect_run` for what a run produced,\n`workspace_search` for a file that nothing named, and `read_file`,\n`list_files`, `file_stat`, and `grep` for a file that a search or a run\npointed you at. The results of a prior turn are still in your context.\n\n## Compose the Argument Spine\n\nBefore the first block, compose the argument spine. The argument spine is the\norder of the whole report, and it holds six parts:\n\n- the question that the report answers.\n- the approach that answers the question.\n- the findings, in order of strength.\n- the negative result, in its honest place.\n- the interpretation that the findings give together.\n- the limits of the evidence.\n\nThe argument spine gives the flow of a paper. It never gives the chapter names of\none. Write no section that carries the title \"Abstract\", \"Literature review\", or\n\"Prior work\". Name each section for what that section says.\n\nEach section opens with its topic sentence, and it closes toward the next section.\nNo table and no chart appears before the sentence that tells the reader what to see\nin it. The evidence illustrates the prose, thus it never replaces the prose.\n\nName a gene set in reader words. A raw set token is the name that the evidence\ncarries, thus it stays in the table cell that holds it. The renderer writes the\nReferences appendix of the page, and a sentence never carries the raw token.\n\nThe summary is the argument spine again, in short form.\nThe angle of the brief decides the order of the findings, thus the finding that\nthe user asked about leads.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks: sections that hold atoms. You build it with\n`set_title` (a draft needs one), `add_block`, whose block schema gives each kind\nand its fields, `read_outline`, your map of the draft, and `read_block`, one block\nin full.\n\nThe argument spine gives the order of the sections. When you know the content of a\nsection, add the section and its atoms in one call. Add an empty section only when\nits content waits for a derivation. Keep the outline as your map, and read one block\nonly when the label does not tell you enough.\n\nA metric binds a numeric cell, and never a text one. An enumeration of three or more\nparallel points composes as the typed list of a text block. Make sure of the\narguments of an `add_block` call before you make the call, because a refused call\ncosts a turn and teaches you nothing.\n\nPrefer a chart block when a table artifact holds the data. `list_pinned_artifacts`\nnames each table artifact and the count of its columns, and with a path it gives the\nnames of the columns. Thus it shows what a chart can plot.\nReach for a figure image only when no table carries the data. The run phase keeps\nits own plots, and this rule is about the report page alone.\n\nA figure image often shows what a derivable table can carry. Derive that table and\nbind the chart when it does. The test is the pinned evidence, and never the picture.\nA pinned ranked-set table takes the horizontal bar. Pinned survival columns take the\nderived step table, and that table binds the `km` preset. Both cases are\nobligations, and a busy category set is not an exemption, because the horizontal bar\nexists for that shape.\n\nA figure block is the last choice. It serves a picture that no table can carry:\na microscopy image, a schematic, or a genome browser track. Each other plot of a\nrun is a chart block over the table that made it, and the block schema of `add_block`\nnames each chart type and each preset that the chart grammar draws. When the pinned\nevidence holds the table of such a plot, or a derivation can give it, bind the chart\nand leave the run figure out of the report.\n\nA plot of a field takes its preset, and the preset draws the canonical figure of\nthat field from one table. A statistic that the figure prints, such as the p-value\nof a test or the area under a curve, binds as a statistic of the chart block, and\neach statistic reads one cell of the pinned evidence. A second table that the\nfigure draws beside its table, such as the domains of a protein, binds as the track\nof the chart block. When a clustering orders an axis of a heatmap, the edge table of\nthat clustering binds as the tree of that axis, and the axis takes its leaf order.\n\nA run writes statistical tables, and not plot-ready ones. When a real reshaping\nstands between the evidence and the block, derive the table in `run_script`:\n`read_table` reads a pinned table, and `write_derived` pins the result to this\nsession with the inputs that the script read. A join of two tables,\na pivot, and an aggregate are such reshaping. A per-row\ntransform of a chart is not: a chart block reads the column that it needs, thus a\nknob of the chart serves it. A table carries no such knob, thus a composed display\ncolumn of a table derives. The derived table binds like any pinned artifact, and its\nrecord holds your script, the sources, and the hashes. When an input is over the\n16 MiB that a script reads, tell the user which table is absent.\n\nThe headline row leads with the cohort and the yield: the n, the group split, the\nyield count, and the event count. A value that carries a caveat is not a headline.\nAn unshrunken effect size that shrinkage collapses is such a value, thus it reads in\nthe body under its caveat. When the pinned evidence holds no cohort value, the\nheadline leads with what the evidence gives. Tell the user which value is absent.\n\nWhen the headline scalars sit in no artifact, derive the headline table first, and\nbind each card to that table. A cohort summary is one aggregate over the pinned\nevidence. Report an absent value only when the derivation cannot give it.\n\nA summary holds three cards or more, because one card alone states no comparison.\nWhen the pinned evidence gives fewer, name the reason to the user.\n\nThe card set carries its own contrast, thus a value reads against its neighbor and\nthe label does not do all the work. Round a number in the prose to the short form.\nThe look then shows a number that does not agree with its card.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\nNever write a zero p-value into a sentence. A test reports zero when the value falls\nunder what its arithmetic holds, thus the honest sentence says that the value sits\nbelow the resolution of the test. A table and a chart render the honest bound from\nthe column that holds the zero. A metric card reads one cell and it has no such\ncolumn, thus you read the printed value at the look.\n\nQuote a number as the page prints it. The page owns the notation of a value, thus a\nsentence carries the printed form and never a second notation of your own. The look\nthen confirms that the sentence and the card agree.\n\n`list_pinned_artifacts` is the orientation source for that evidence. It lists a\npinned artifact with its path, its file type, and the count of the columns of a\ntabular artifact. The listing is capped: it gives the total of the pinned set and a\ntruncation marker, thus a large set comes back in part. Read it before you bind a\nblock, and take the path from what it gives. Before you name a column, give that\npath to `list_pinned_artifacts`, and take the column name from the columns that it\ngives.\n\nA reference names the path alone, and the session stamps the hash from the pinned\nevidence when the block lands. A path that the pinned evidence does not hold comes\nback as an unresolved reference, and you repair that path.\n\nA whole-table binding carries its own declarations. Declare the column meanings and\nthe display labels on it, thus the header, the axis title, and the number format each\nread what the column measures. Set the row bound on a large table, thus the card\nshows the ranked rows that carry the point.\n\nThe row bound has two sizes. A tight bound serves an evidence table that carries one\npoint. A wide bound serves a browsable table that the reader scans. The data rides an\nasset, thus a wide bound costs the page nothing.\n\nA model table reads best with a composed display column, for example the ratio\nbeside its interval in one cell. Such a column is a small derivation, and you offer\nit to the user.\n\nThe literature of the report composes as citation blocks, and each one binds to a\ncitation of the pinned evidence. `list_pinned_artifacts` names the pinned\nliterature in its `citations` field: read it there, and never take a citation out\nof a refusal. A citation that the pinned evidence does not hold does not resolve.\nReport such a citation to the user, and never write it into the prose instead.\n\nBuild no References section of your own. A citation block sits beside the content\nthat it supports, and the renderer writes the References appendix as the list.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap or a pass, and each advisory\nwarning. `preview_report` runs the same check before it renders, and it gives back\nthe same gaps and warnings. Thus, when you preview next, do not call\n`finish_draft` first. Repair each gap that a check gives back.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change with\n`change_block`, `move_block`, or `remove_block`, by the id that the outline\ngives. Do not rebuild the report to make one change.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page, after the same check as\n  `finish_draft`. Repair each gap and each reference that does not resolve. When\n  the tool reports that the reference resolver is absent, tell the user, and do not\n  preview again.\n- `examine_page` opens the rendered page in a real browser. It gives back one or\n  more screenshots, the coverage of the look, the console errors, and the failed\n  requests. The coverage names what the pictures hold. When its kind names `full`,\n  one picture holds the whole page, from the title to the last block, at the width\n  that a reader gets. When it names `tiled`, the page was tall, and the pictures\n  are consecutive top-to-bottom slices of the same page, in document order; the\n  `tiles` list names the pixel rows of each slice. Read the slices as one page.\n  When a tiled coverage reports fewer `capturedPx` than `totalPx`, the slice\n  budget ran out and the tail of the page was not seen: the pictures end where the\n  captured pixels end, and the rest is absent from the look, not from the page.\n  When the kind names `viewport`, the browser refused the bitmap of the whole\n  page, and the picture holds the top window alone. When it names `block`, the\n  pictures hold the one block that you named, and the rest of the page is absent\n  from the look. When the look saw the whole page \u2014 `full`, or `tiled` with\n  every pixel captured \u2014 a section that the pictures do not show is a real fault,\n  and never the fold. Judge what the pictures show. Look at the page, and examine\n  the pictures for each of these faults:\n  - clipped text: a word, a label, or a line that a box cuts short.\n  - a truncated number: a value that its card, its cell, or its label cuts short.\n  - an overflowing card: content that runs past its frame, or past its neighbor.\n  - a raw column name on an axis, in a legend, or in a table header. A reader reads\n    a written label, not the name that the evidence carries.\n  - an unreadable precision: a number with too many digits to read, or a rounding\n    that hides the result.\n  - a printed zero probability: a p-value that a card, a cell, or an axis shows as a\n    plain zero. A probability that the test could not resolve is never zero.\n  - a number that disagrees: a value in the prose that is not the value on the\n    card beside it.\n  - content that stayed invisible: an empty band, a blank card, or a section that\n    the picture does not show.\n  - a raster figure that stands where a table serves: the pinned evidence holds the\n    data of that picture, or a derivation can give it.\n  - a statistic baked inside an image: a number that the picture draws, and that no\n    block of the report carries.\n  - a caption that promises what the plot does not show.\n\n  A found fault is a repair, and never a note. Never describe such a fault to the\n  user in place of the repair.\n- Repair each fault that the look shows. A named fault of the checklist, an absent\n  chart, and a failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version,\n  and each record replaces it.\n\nAfter the first preview that passes, look at the whole page one time. Make each\nrepair that this look shows before you look again. Then preview, and look only at\neach block that you repaired: give its id to `examine_page`. The record accepts a\nlook at one block of the current page. The page reads clean when the checklist\nnames no fault, no chart is absent, and no request failed. When the page reads\nclean, record.\n\nThe record loop has no bound. An amend is the whole set of changes of one user\nrequest. Make the whole amend first. Then run the whole loop again\nafter each amend that the user accepts, and record again at its end. Thus the\nstored version is always the page that the user reads.\n\nA user can ask for the report as a PDF. A PDF is a document of its own, and no\nprint of the page: build it in `run_script` from the content of the session, with\n`render_chart` for each chart and `export_pdf` for the document.\n\n## Do NOT\n\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Probe for a hash.** Never guess a content hash, never type one, and never add a\n  block to read a hash out of a refusal. A reference names the path, and the session\n  stamps the hash.\n- **Use a run figure for a plot that a chart draws.** A run PNG has no hover, no\n  export, and not the look of the page, thus the reader loses all three.\n- **Repair a block that the pictures could not show.** The coverage of the look\n  names what the pictures hold. Judge what you saw, and leave the rest of\n  the draft as it stands.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. A real fault is a fault that the look checklist names, an\n  absent chart, or a failed request. A matter of taste is not a fault, thus it starts\n  no repair and no new look.\n";
+export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user from typed blocks, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\nYou read the analysis, and you hold no tool that runs it or changes it.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and in a targeted way: `inspect_data_profile`\nfor a fact about the dataset, `inspect_run` for what a run produced,\n`workspace_search` for a file that nothing named, and `read_file`,\n`list_files`, `file_stat`, and `grep` for a file that a search or a run\npointed you at. The results of a prior turn are still in your context.\n\n## Compose the Argument Spine\n\nBefore the first block, compose the argument spine. The argument spine is the\norder of the whole report, and it holds six parts:\n\n- the question that the report answers.\n- the approach that answers the question.\n- the findings, in order of strength.\n- the negative result, in its honest place.\n- the interpretation that the findings give together.\n- the limits of the evidence.\n\nThe argument spine gives the flow of a paper. It never gives the chapter names of\none. Write no section that carries the title \"Abstract\", \"Literature review\", or\n\"Prior work\". Name each section for what that section says.\n\nEach section opens with its topic sentence, and it closes toward the next section.\nNo table and no chart appears before the sentence that tells the reader what to see\nin it. The evidence illustrates the prose, thus it never replaces the prose.\n\nName a gene set in reader words. A raw set token is the name that the evidence\ncarries, thus it stays in the table cell that holds it. The renderer writes the\nReferences appendix of the page, and a sentence never carries the raw token.\n\nThe summary is the argument spine again, in short form.\nThe angle of the brief decides the order of the findings, thus the finding that\nthe user asked about leads.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks: sections that hold atoms. You build it in\n`run_script` with `set_title` (a draft needs one), `add_block`, whose block\nschema gives each kind and its fields, `read_outline`, your map of the draft, and\n`read_block`, one block in full. Each edit gives `applied`, and a refused edit\ngives its refusal and lands nothing. Thus a script reads `applied` before an edit\nthat builds on an earlier one.\n\nThe argument spine gives the order of the sections. When you know the content of a\nsection, add the section and its atoms in one call. Add an empty section only when\nits content waits for a derivation. Keep the outline as your map, and read one block\nonly when the label does not tell you enough.\n\nA metric binds a numeric cell, and never a text one. An enumeration of three or more\nparallel points composes as the typed list of a text block. Make sure of the\narguments of an `add_block` call before you make the call, because a refused call\nlands nothing and costs a turn.\n\nPrefer a chart block when a table artifact holds the data. `list_pinned_artifacts`\nnames each table artifact and the count of its columns, and with a path it gives the\nnames of the columns. Thus it shows what a chart can plot.\nReach for a figure image only when no table carries the data. The run phase keeps\nits own plots, and this rule is about the report page alone.\n\nA figure image often shows what a derivable table can carry. Derive that table and\nbind the chart when it does. The test is the pinned evidence, and never the picture.\nA pinned ranked-set table takes the horizontal bar. Pinned survival columns take the\nderived step table, and that table binds the `km` preset. Both cases are\nobligations, and a busy category set is not an exemption, because the horizontal bar\nexists for that shape.\n\nA figure block is the last choice. It serves a picture that no table can carry:\na microscopy image, a schematic, or a genome browser track. Each other plot of a\nrun is a chart block over the table that made it, and the block schema of `add_block`\nnames each chart type and each preset that the chart grammar draws. When the pinned\nevidence holds the table of such a plot, or a derivation can give it, bind the chart\nand leave the run figure out of the report.\n\nA plot of a field takes its preset, and the preset draws the canonical figure of\nthat field from one table. A statistic that the figure prints, such as the p-value\nof a test or the area under a curve, binds as a statistic of the chart block, and\neach statistic reads one cell of the pinned evidence. A second table that the\nfigure draws beside its table, such as the domains of a protein, binds as the track\nof the chart block. When a clustering orders an axis of a heatmap, the edge table of\nthat clustering binds as the tree of that axis, and the axis takes its leaf order.\n\nA run writes statistical tables, and not plot-ready ones. When a real reshaping\nstands between the evidence and the block, derive the table in `run_script`:\n`read_table` reads a pinned table, and `write_derived` pins the result to this\nsession with the inputs that the script read. A join of two tables,\na pivot, and an aggregate are such reshaping. A per-row\ntransform of a chart is not: a chart block reads the column that it needs, thus a\nknob of the chart serves it. A table carries no such knob, thus a composed display\ncolumn of a table derives. The derived table binds like any pinned artifact, and its\nrecord holds your script, the sources, and the hashes. When an input is over the\n16 MiB that a script reads, tell the user which table is absent.\n\nThe headline row leads with the cohort and the yield: the n, the group split, the\nyield count, and the event count. A value that carries a caveat is not a headline.\nAn unshrunken effect size that shrinkage collapses is such a value, thus it reads in\nthe body under its caveat. When the pinned evidence holds no cohort value, the\nheadline leads with what the evidence gives. Tell the user which value is absent.\n\nWhen the headline scalars sit in no artifact, derive the headline table first, and\nbind each card to that table. A cohort summary is one aggregate over the pinned\nevidence. Report an absent value only when the derivation cannot give it.\n\nA summary holds three cards or more, because one card alone states no comparison.\nWhen the pinned evidence gives fewer, name the reason to the user.\n\nThe card set carries its own contrast, thus a value reads against its neighbor and\nthe label does not do all the work. Round a number in the prose to the short form.\nThe look then shows a number that does not agree with its card.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\nNever write a zero p-value into a sentence. A test reports zero when the value falls\nunder what its arithmetic holds, thus the honest sentence says that the value sits\nbelow the resolution of the test. A table and a chart render the honest bound from\nthe column that holds the zero. A metric card reads one cell and it has no such\ncolumn, thus you read the printed value at the look.\n\nQuote a number as the page prints it. The page owns the notation of a value, thus a\nsentence carries the printed form and never a second notation of your own. The look\nthen confirms that the sentence and the card agree.\n\n`list_pinned_artifacts` is the orientation source for that evidence. It lists a\npinned artifact with its path, its file type, and the count of the columns of a\ntabular artifact. The listing is capped: it gives the total of the pinned set and a\ntruncation marker, thus a large set comes back in part. Read it before you bind a\nblock, and take the path from what it gives. Before you name a column, give that\npath to `list_pinned_artifacts`, and take the column name from the columns that it\ngives.\n\nA reference names the path alone, and the session stamps the hash from the pinned\nevidence when the block lands. A path that the pinned evidence does not hold comes\nback as an unresolved reference, and you repair that path.\n\nA whole-table binding carries its own declarations. Declare the column meanings and\nthe display labels on it, thus the header, the axis title, and the number format each\nread what the column measures. Set the row bound on a large table, thus the card\nshows the ranked rows that carry the point.\n\nThe row bound has two sizes. A tight bound serves an evidence table that carries one\npoint. A wide bound serves a browsable table that the reader scans. The data rides an\nasset, thus a wide bound costs the page nothing.\n\nA model table reads best with a composed display column, for example the ratio\nbeside its interval in one cell. Such a column is a small derivation, and you offer\nit to the user.\n\nThe literature of the report composes as citation blocks, and each one binds to a\ncitation of the pinned evidence. `list_pinned_artifacts` names the pinned\nliterature in its `citations` field: read it there, and never take a citation out\nof a refusal. A citation that the pinned evidence does not hold does not resolve.\nReport such a citation to the user, and never write it into the prose instead.\n\nBuild no References section of your own. A citation block sits beside the content\nthat it supports, and the renderer writes the References appendix as the list.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap or a pass, and each advisory\nwarning. `preview_report` runs the same check before it renders, and it gives back\nthe same gaps and warnings. Thus, when you preview next, do not call\n`finish_draft` first. Repair each gap that a check gives back.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change with\n`change_block`, `move_block`, or `remove_block`, by the id that the outline\ngives. Do not rebuild the report to make one change.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page, after the same check as\n  `finish_draft`. Repair each gap and each reference that does not resolve. When\n  the tool reports that the reference resolver is absent, tell the user, and do not\n  preview again.\n- `examine_page` opens the rendered page in a real browser. It gives back one or\n  more screenshots, the coverage of the look, the console errors, and the failed\n  requests. The coverage names what the pictures hold. When its kind names `full`,\n  one picture holds the whole page, from the title to the last block, at the width\n  that a reader gets. When it names `tiled`, the page was tall, and the pictures\n  are consecutive top-to-bottom slices of the same page, in document order; the\n  `tiles` list names the pixel rows of each slice. Read the slices as one page.\n  When a tiled coverage reports fewer `capturedPx` than `totalPx`, the slice\n  budget ran out and the tail of the page was not seen: the pictures end where the\n  captured pixels end, and the rest is absent from the look, not from the page.\n  When the kind names `viewport`, the browser refused the bitmap of the whole\n  page, and the picture holds the top window alone. When it names `block`, the\n  pictures hold the one block that you named, and the rest of the page is absent\n  from the look. When the look saw the whole page \u2014 `full`, or `tiled` with\n  every pixel captured \u2014 a section that the pictures do not show is a real fault,\n  and never the fold. Judge what the pictures show. Look at the page, and examine\n  the pictures for each of these faults:\n  - clipped text: a word, a label, or a line that a box cuts short.\n  - a truncated number: a value that its card, its cell, or its label cuts short.\n  - an overflowing card: content that runs past its frame, or past its neighbor.\n  - a raw column name on an axis, in a legend, or in a table header. A reader reads\n    a written label, not the name that the evidence carries.\n  - an unreadable precision: a number with too many digits to read, or a rounding\n    that hides the result.\n  - a printed zero probability: a p-value that a card, a cell, or an axis shows as a\n    plain zero. A probability that the test could not resolve is never zero.\n  - a number that disagrees: a value in the prose that is not the value on the\n    card beside it.\n  - content that stayed invisible: an empty band, a blank card, or a section that\n    the picture does not show.\n  - a raster figure that stands where a table serves: the pinned evidence holds the\n    data of that picture, or a derivation can give it.\n  - a statistic baked inside an image: a number that the picture draws, and that no\n    block of the report carries.\n  - a caption that promises what the plot does not show.\n\n  A found fault is a repair, and never a note. Never describe such a fault to the\n  user in place of the repair.\n- Repair each fault that the look shows. A named fault of the checklist, an absent\n  chart, and a failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version,\n  and each record replaces it.\n\nAfter the first preview that passes, look at the whole page one time. Make each\nrepair that this look shows before you look again. Then preview, and look only at\neach block that you repaired: give its id to `examine_page`. The record accepts a\nlook at one block of the current page. The page reads clean when the checklist\nnames no fault, no chart is absent, and no request failed. When the page reads\nclean, record.\n\nThe record loop has no bound. An amend is the whole set of changes of one user\nrequest. Make the whole amend first. Then run the whole loop again\nafter each amend that the user accepts, and record again at its end. Thus the\nstored version is always the page that the user reads.\n\nA user can ask for the report as a PDF. A PDF is a document of its own, and no\nprint of the page: build it in `run_script` from the content of the session, with\n`render_chart` for each chart and `export_pdf` for the document.\n\n## Do NOT\n\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Probe for a hash.** Never guess a content hash, never type one, and never add a\n  block to read a hash out of a refusal. A reference names the path, and the session\n  stamps the hash.\n- **Use a run figure for a plot that a chart draws.** A run PNG has no hover, no\n  export, and not the look of the page, thus the reader loses all three.\n- **Repair a block that the pictures could not show.** The coverage of the look\n  names what the pictures hold. Judge what you saw, and leave the rest of\n  the draft as it stands.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. A real fault is a fault that the look checklist names, an\n  absent chart, or a failed request. A matter of taste is not a fault, thus it starts\n  no repair and no new look.\n";

package/dist/prompts/report-session.js

@@ -46,10 +46,12 @@ the user asked about leads.
 
 ## Compose from Typed Blocks
 
-A report is a tree of typed blocks: sections that hold atoms. You build it with
-\`set_title\` (a draft needs one), \`add_block\`, whose block schema gives each kind
-and its fields, \`read_outline\`, your map of the draft, and \`read_block\`, one block
-in full.
+A report is a tree of typed blocks: sections that hold atoms. You build it in
+\`run_script\` with \`set_title\` (a draft needs one), \`add_block\`, whose block
+schema gives each kind and its fields, \`read_outline\`, your map of the draft, and
+\`read_block\`, one block in full. Each edit gives \`applied\`, and a refused edit
+gives its refusal and lands nothing. Thus a script reads \`applied\` before an edit
+that builds on an earlier one.
 
 The argument spine gives the order of the sections. When you know the content of a
 section, add the section and its atoms in one call. Add an empty section only when
@@ -59,7 +61,7 @@ only when the label does not tell you enough.
 A metric binds a numeric cell, and never a text one. An enumeration of three or more
 parallel points composes as the typed list of a text block. Make sure of the
 arguments of an \`add_block\` call before you make the call, because a refused call
-costs a turn and teaches you nothing.
+lands nothing and costs a turn.
 
 Prefer a chart block when a table artifact holds the data. \`list_pinned_artifacts\`
 names each table artifact and the count of its columns, and with a path it gives the

package/dist/runtime/assemble.d.ts

@@ -36,6 +36,7 @@ import type { CitationResolver } from "../citations/types.js";
 import type { AuthContext, Identity } from "../auth/types.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
+import type { SyncSessionFile } from "../workspace/session-files.js";
 import { type AskGateway } from "../tools/approval/gateway.js";
 import type { MakeSessionPagePublisher, ResolvePageAsset, ResolvePageUrl } from "../tools/report-session/index.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -80,9 +81,9 @@ export type RegisteredWorkflows = {
 };
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, the
- * usage recorder, the report-session anchor, the eyes, and the tool output store.
- * `assembleCoreRuntime` supplies each of those itself. Thus a caller cannot wire
- * one of these six values:
+ * usage recorder, the report-session anchor, the eyes, the tool output store, and the
+ * file sync. `assembleCoreRuntime` supplies each of those itself. Thus a caller cannot wire
+ * one of these values:
  *
  * - a stale callable
  * - a policy that diverges from the one the workflows see
@@ -90,12 +91,13 @@ export type RegisteredWorkflows = {
  * - an anchor over a different session runtime
  * - a seam that only half the agent tree looks through
  * - a store that only half the agent tree keeps its texts in
+ * - a file sync that only half the agent tree writes through
  *
  * The assembly resolves the eyes one time, from `CoreRuntimeDeps.eyes` and the
  * chrome config. A caller that bound the eyes here would give the conversation
  * agent a seam that the report agent never sees.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes" | "toolOutputStore" | "registerSubAgent">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "usageRecorder" | "citationResolver" | "anchorReportSession" | "eyes" | "toolOutputStore" | "registerSubAgent" | "syncSessionFile">;
 /**
  * What binds one reference resolver: the analysis whose pinned artifacts it reads, and the identity and the
  * auth of the tool call that reads them. A resolver serves one analysis, thus the report tools build one for
@@ -197,6 +199,13 @@ export type CoreRuntimeDeps = {
      * which an embedder calls on its own. Thus that composition binds the seam there as well.
      */
     readonly provenance?: ProvenanceSeam;
+    /**
+     * The host copy of each file that a chat thread or a report session writes outside a run. A host that keeps the
+     * files of an analysis in its own store binds it, and each write reaches it with its bytes and its owner: the
+     * thread for the scratch files of a session, and the analysis for a `write_file` or `edit_file` write. Absent,
+     * the files stay in the workspace tree alone, which is the whole local path.
+     */
+    readonly syncSessionFile?: SyncSessionFile;
     /**
      * The credential of a chat turn that this process did not open, for example a turn that a recovery runs after a
      * restart. The workflow input of a turn holds no credential. Absent, or `undefined` for a turn: the turn pauses

package/dist/runtime/assemble.js

@@ -163,6 +163,7 @@ export function assembleCoreRuntime(deps) {
         // The start tool passes it to the spawn, which emits the creation of a
         // report session. The same seam reaches the report agent below.
         provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
         registerSubAgent: registerPausingSubAgent,
     });
     // The report agent is a singleton over the conversation deps, the same way the
@@ -204,6 +205,7 @@ export function assembleCoreRuntime(deps) {
         makeSessionPages: deps.makeSessionPagePublisher,
         resolvePageUrl: deps.resolveReportPageUrl,
         provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
         logger: conversation.logger,
         toolOutputStore,
         scriptRuntime: conversation.scriptRuntime,

package/dist/runtime/dbos.d.ts

@@ -98,6 +98,12 @@ export type WorkflowSchedule = {
  * schedule of this list. A second call with the same name replaces the first.
  */
 export declare function scheduleWorkflow(schedule: WorkflowSchedule): void;
+/**
+ * Store each schedule of {@link scheduleWorkflow} in the system database, and delete each stored schedule of this
+ * application that no code registers. DBOS only upserts, thus a schedule of a removed workflow fires on each tick and
+ * finds no function. Each schedule of the harness goes through `scheduleWorkflow`.
+ */
+export declare function applyWorkflowSchedules(): Promise<void>;
 /**
  * Launch DBOS. Idempotent — a second call is a no-op so tests that drive
  * the harness twice (or accidentally double-import) don't re-launch.

package/dist/runtime/dbos.js

@@ -130,6 +130,19 @@ const pendingSchedules = new Map();
 export function scheduleWorkflow(schedule) {
     pendingSchedules.set(schedule.scheduleName, schedule);
 }
+/**
+ * Store each schedule of {@link scheduleWorkflow} in the system database, and delete each stored schedule of this
+ * application that no code registers. DBOS only upserts, thus a schedule of a removed workflow fires on each tick and
+ * finds no function. Each schedule of the harness goes through `scheduleWorkflow`.
+ */
+export async function applyWorkflowSchedules() {
+    if (pendingSchedules.size > 0)
+        await DBOS.applySchedules([...pendingSchedules.values()]);
+    for (const stored of await DBOS.listSchedules()) {
+        if (!pendingSchedules.has(stored.scheduleName))
+            await DBOS.deleteSchedule(stored.scheduleName);
+    }
+}
 let resultRecipesRegistered = false;
 /**
  * DBOS refuses a registration after the launch, and the registry of SuperJSON
@@ -160,8 +173,7 @@ export async function launchDbos({ config, logger: injected }) {
     registerResultSerialization();
     const start = performance.now();
     await DBOS.launch();
-    if (pendingSchedules.size > 0)
-        await DBOS.applySchedules([...pendingSchedules.values()]);
+    await applyWorkflowSchedules();
     state.launched = true;
     state.recoveryStarted = true;
     logger.info("launched", {

package/dist/state/artifacts.d.ts

@@ -86,6 +86,8 @@ export type ArtifactPageQuery = {
     q?: string;
     /** The whole path, with case. It selects the one row of that path. */
     path?: string;
+    /** The role of the row. `step_output` selects the rows that the grouped run count of {@link countArtifactsByRuns} counts. */
+    role?: ArtifactRole;
     /**
      * Extensions in lower case, with no dot. A row is selected when the extension of its path is a member. A row with
      * no extension never matches, and an empty list selects each row. The read compares the members as they are.
@@ -125,7 +127,8 @@ export type ArtifactPage = {
  * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
  * row to carry it. `total` is the sum of the groups.
  *
- * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included, unless the `role`
+ * filter selects one role. `total` and `extensionCounts` follow the filters. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.
  */
 export declare function queryArtifactPage(pool: Querier, analysisId: string, query: ArtifactPageQuery): ResultAsync<ArtifactPage, DbError>;

package/dist/state/artifacts.js

@@ -193,7 +193,8 @@ const EXTENSION_SQL = `lower(substring(regexp_replace(path, '^.*/', '') from '^.
  * select, grouped by extension, and the page. The count is a separate statement because a page past the end has no
  * row to carry it. `total` is the sum of the groups.
  *
- * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included. The cost
+ * Every row of the analysis is a member, an `input` row and a row with `unrecoverable_at` included, unless the `role`
+ * filter selects one role. `total` and `extensionCounts` follow the filters. The cost
  * grows with the ledger of the one analysis, because the count reads each filtered row.
  */
 export function queryArtifactPage(pool, analysisId, query) {
@@ -215,6 +216,8 @@ export function queryArtifactPage(pool, analysisId, query) {
             conditions.push(`strpos(lower(path), lower(${bind(query.q)}::text)) > 0`);
         if (query.path !== undefined)
             conditions.push(`path = ${bind(query.path)}`);
+        if (query.role !== undefined)
+            conditions.push(`role = ${bind(query.role)}`);
         if (query.extensions !== undefined && query.extensions.length > 0) {
             conditions.push(`${EXTENSION_SQL} = ANY(${bind([...query.extensions])}::text[])`);
         }

package/dist/state/index.d.ts

@@ -14,10 +14,10 @@ export type { RegisterArtifactInput, ArtifactOrigin, InputArtifactMeta, StepArti
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
-export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
-export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
-export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
-export type { InsertPlanInput, UpsertPlanInput, PlanRecord, PlanRowQuerier } from "./plans.js";
+export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun, countStepsByRuns, } from "./step-executions.js";
+export type { InsertStepExecutionInput, RunStepCounts, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./plans.js";
+export type { InsertPlanInput, UpsertPlanInput, PlanRecord, PlanRowQuerier, PlanPage, PlanPageEntry } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileTerminalWrite, DataProfileResult, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileDimension, DataProfileGroup, DataProfileGroupSlot, DataProfileFile, DataProfileMemberAnnotation, DataProfileObservation, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileKind, DataProfileAxis, DataProfileInputSignature, DataProfileCoverage, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";

package/dist/state/index.js

@@ -11,8 +11,8 @@ export { upsertAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, queryArtifactOrigins, countArtifactsByRuns, } from "./artifacts.js";
 export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
-export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
-export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
+export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun, countStepsByRuns, } from "./step-executions.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord, queryPlanPage } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id

package/dist/state/plans.d.ts

@@ -94,3 +94,30 @@ export type PlanRecord = {
 export declare function loadPlanRecord(pool: PlanRowQuerier, planId: string, opts: {
     analysisId: string;
 }): ResultAsync<PlanRecord | null, DbError>;
+/** One plan of {@link queryPlanPage}. */
+export type PlanPageEntry = {
+    planId: string;
+    createdAt: string;
+    /** The `title` of the stored document when it is a string, as the document holds it, else `null`. */
+    title: string | null;
+    parentPlanId: string | null;
+    /** The newest plan of the same analysis that names this plan as its parent. */
+    supersededBy: string | null;
+    /** The newest run of the plan, in the order of {@link queryRunIdsByPlan}, or `null` for a plan with no run. */
+    newestRunId: string | null;
+};
+/** One page of the plans of an analysis, and the exact count of them. */
+export type PlanPage = {
+    entries: PlanPageEntry[];
+    total: number;
+};
+/**
+ * One page of the plans of an analysis, newest first, in two statements: the count of the plans and the page. The
+ * count is a separate statement because a page past the end has no row to carry it. The order is the one of
+ * `supersededBy`: the creation time, then the highest plan id. The page gives the title of the document, not the
+ * document, because a page holds up to 200 plans.
+ */
+export declare function queryPlanPage(pool: Querier, analysisId: string, opts: {
+    limit: number;
+    offset: number;
+}): ResultAsync<PlanPage, DbError>;

package/dist/state/plans.js

@@ -117,6 +117,13 @@ const PlanRecordRowSchema = z.object({
     created_at: z.string(),
     superseded_by: z.string().nullable(),
 });
+/**
+ * The `superseded_by` column of a plan read: the newest plan of the same analysis that names the plan as its parent.
+ * The text refers to the plan row of the outer query as `p`.
+ */
+const SUPERSEDED_BY_SQL = `(SELECT c.plan_id FROM cortex_plans c
+                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
+                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by`;
 /**
  * Analysis-scoped read of one plan with its parent and the newest plan that
  * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
@@ -129,9 +136,7 @@ export function loadPlanRecord(pool, planId, opts) {
     return tryQuery("plans.loadPlanRecord", async () => {
         const result = await pool.query({
             text: `SELECT p.plan, p.parent_plan_id, p.created_at,
-                     (SELECT c.plan_id FROM cortex_plans c
-                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
-                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by
+                     ${SUPERSEDED_BY_SQL}
                 FROM cortex_plans p
                WHERE p.plan_id = $1 AND p.analysis_id = $2`,
             values: [planId, opts.analysisId],
@@ -143,3 +148,52 @@ export function loadPlanRecord(pool, planId, opts) {
         return { planId, plan: row.plan, parentPlanId: row.parent_plan_id, supersededBy: row.superseded_by, createdAt: row.created_at };
     });
 }
+const PlanPageRowSchema = z.object({
+    plan_id: z.string(),
+    created_at: z.string(),
+    title: z.string().nullable(),
+    parent_plan_id: z.string().nullable(),
+    superseded_by: z.string().nullable(),
+    newest_run_id: z.string().nullable(),
+});
+/**
+ * One page of the plans of an analysis, newest first, in two statements: the count of the plans and the page. The
+ * count is a separate statement because a page past the end has no row to carry it. The order is the one of
+ * `supersededBy`: the creation time, then the highest plan id. The page gives the title of the document, not the
+ * document, because a page holds up to 200 plans.
+ */
+export function queryPlanPage(pool, analysisId, opts) {
+    return tryQuery("plans.queryPlanPage", async () => {
+        const countResult = await pool.query({
+            text: "SELECT COUNT(*)::int AS total FROM cortex_plans WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        const rowsResult = await pool.query({
+            text: `SELECT p.plan_id, p.created_at, p.parent_plan_id,
+                     CASE WHEN jsonb_typeof(p.plan->'title') = 'string' THEN p.plan->>'title' END AS title,
+                     ${SUPERSEDED_BY_SQL},
+                     (SELECT r.run_id FROM cortex_runs r
+                       WHERE r.analysis_id = p.analysis_id AND r.plan_id = p.plan_id
+                       ORDER BY r.started_at DESC, r.run_id DESC LIMIT 1) AS newest_run_id
+                FROM cortex_plans p
+               WHERE p.analysis_id = $1
+               ORDER BY p.created_at DESC, p.plan_id DESC
+               LIMIT $2 OFFSET $3`,
+            values: [analysisId, opts.limit, opts.offset],
+        });
+        return {
+            entries: rowsResult.rows.map((raw) => {
+                const row = PlanPageRowSchema.parse(raw);
+                return {
+                    planId: row.plan_id,
+                    createdAt: row.created_at,
+                    title: row.title,
+                    parentPlanId: row.parent_plan_id,
+                    supersededBy: row.superseded_by,
+                    newestRunId: row.newest_run_id,
+                };
+            }),
+            total: countResult.rows[0]?.total ?? 0,
+        };
+    });
+}

package/dist/state/step-executions.d.ts

@@ -94,3 +94,16 @@ export declare function sweepPendingStepExecutions(pool: Querier, runId: string)
  */
 export declare function cancelRunningStepExecutions(pool: Querier, runId: string, reason: string): ResultAsync<void, DbError>;
 export declare function queryStepsByRun(pool: StepRowQuerier, runId: string): ResultAsync<StepExecutionRow[], DbError>;
+/** The step counts of one run, from {@link countStepsByRuns}. */
+export type RunStepCounts = {
+    runId: string;
+    doneSteps: number;
+    runningSteps: number;
+    totalSteps: number;
+};
+/**
+ * The step counts of each run of a list, in one statement. `totalSteps` counts each row, the `synthesis` row
+ * included, and `doneSteps` counts the `completed` rows: the rule of the analysis summary reads. A step that
+ * waits counts in `totalSteps` only. A run with no row has no entry, and a caller reads it as 0.
+ */
+export declare function countStepsByRuns(pool: Querier, analysisId: string, runIds: readonly string[]): ResultAsync<RunStepCounts[], DbError>;