@inflexa-ai/harness 0.18.0 → 0.19.0

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

@@ -0,0 +1,56 @@
+/**
+ * The Report Builder agent -- the agent that talks to the user on a report thread.
+ *
+ * `createReportSessionAgent` is the composition root of the report path. It gets
+ * the shared deps one time, and it hands each tool exactly what it needs. The
+ * authoring tools and the preview tool bind to the session-state gateway, thus one
+ * assembled definition serves every thread, and the per-session state stays behind
+ * the tool boundary.
+ *
+ * The roster is read-only toward the analysis. It holds the workspace read tools,
+ * the workspace search, the run inspection, and the data-profile inspection. It
+ * holds no planner, no run launcher, no working-memory write, and no sandbox
+ * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
+ * roster omits those tools, and no runtime guard blocks them.
+ *
+ * The definition carries no per-session value. The system prompt composes through
+ * `composeSystemPrompt` with the identity part and the conversational part, the
+ * same composition as the conversation agent. Thus the prompt prefix stays constant
+ * across threads, and the provider cache reuses it.
+ */
+import type { Pool } from "pg";
+import type { AgentDefinition } from "../loop/types.js";
+import type { EmbeddingProvider } from "../providers/types.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { Logger } from "../lib/logger.js";
+import type { ReferenceResolver } from "../report-model/reference-resolver.js";
+import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+/** Canonical agent id -- distinct from the id of the old templating agent. */
+export declare const REPORT_SESSION_AGENT_ID: "report-session";
+/**
+ * The shared dependencies of the report agent. The gateway binds the per-session
+ * state to the thread, thus every tool that touches the state gets the same
+ * gateway. The resolver is optional, because a resolver realization can be absent,
+ * and the preview tool degrades as data when it is.
+ */
+export interface ReportSessionAgentDeps {
+    /** Model id -- the provenance and metric label. The provider owns the wire model. */
+    readonly model: string;
+    /** Postgres pool -- workspace index, run inspection, and data-profile inspection. */
+    readonly pool: Pool;
+    /** Embedding seam -- workspace semantic search. */
+    readonly embedding: EmbeddingProvider;
+    /** Workspace filesystem read seam -- the four read tools. */
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Session-state gateway -- the authoring tools and the preview tool bind to it. */
+    readonly gateway: ReportSessionStateGateway;
+    /** Workspace-root resolution seam -- the preview tool resolves the page root per call. */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Reference-resolution seam -- absent until a realization lands; the preview tool degrades as data. */
+    readonly resolver?: ReferenceResolver;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
+}
+/** Build the report `AgentDefinition` with every tool bound to its deps. */
+export declare function createReportSessionAgent(deps: ReportSessionAgentDeps): AgentDefinition;

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

@@ -0,0 +1,72 @@
+/**
+ * The Report Builder agent -- the agent that talks to the user on a report thread.
+ *
+ * `createReportSessionAgent` is the composition root of the report path. It gets
+ * the shared deps one time, and it hands each tool exactly what it needs. The
+ * authoring tools and the preview tool bind to the session-state gateway, thus one
+ * assembled definition serves every thread, and the per-session state stays behind
+ * the tool boundary.
+ *
+ * The roster is read-only toward the analysis. It holds the workspace read tools,
+ * the workspace search, the run inspection, and the data-profile inspection. It
+ * holds no planner, no run launcher, no working-memory write, and no sandbox
+ * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
+ * roster omits those tools, and no runtime guard blocks them.
+ *
+ * The definition carries no per-session value. The system prompt composes through
+ * `composeSystemPrompt` with the identity part and the conversational part, the
+ * same composition as the conversation agent. Thus the prompt prefix stays constant
+ * across threads, and the provider cache reuses it.
+ */
+import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
+import { createPreviewReportTool } from "../tools/report-session/preview-report.js";
+import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
+import { createInspectDataProfileTool, createInspectRunTool } from "../tools/research/index.js";
+import { reportSessionPrompt } from "../prompts/report-session.js";
+import { composeSystemPrompt } from "./system-prompt.js";
+/** Canonical agent id -- distinct from the id of the old templating agent. */
+export const REPORT_SESSION_AGENT_ID = "report-session";
+/**
+ * Runaway guard. A report turn drives many small tool calls, thus it needs the
+ * same headroom as the conversation agent.
+ */
+const REPORT_SESSION_MAX_ITERATIONS = 50;
+/** Build the report `AgentDefinition` with every tool bound to its deps. */
+export function createReportSessionAgent(deps) {
+    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, resolver, logger } = deps;
+    const authoring = createReportAuthoringTools(gateway);
+    const tools = [
+        // The read surface toward the analysis. It roams the tree read-only.
+        createReadFileTool(workspaceFs),
+        createListFilesTool(workspaceFs),
+        createFileStatTool(workspaceFs),
+        createGrepTool(workspaceFs),
+        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,
+        authoring.finish_draft,
+        // The render-and-preview tool. It resolves the page root per call.
+        createPreviewReportTool({
+            gateway,
+            resolveWorkspaceRoot,
+            ...(resolver ? { resolver } : {}),
+            ...(logger ? { logger } : {}),
+        }),
+    ];
+    return {
+        id: REPORT_SESSION_AGENT_ID,
+        systemPrompt: composeSystemPrompt(reportSessionPrompt, { identity: true, conversational: true }),
+        model,
+        tools,
+        maxIterations: REPORT_SESSION_MAX_ITERATIONS,
+    };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * The report session-state runtime -- the durable realization of the session-state
+ * gateway, and the idempotent operation that anchors one report session.
+ *
+ * The runtime binds three parts: the session-state store, the thread store, and
+ * the pin. The tool layer speaks the gateway, and the gateway speaks a plain
+ * discriminated value. Thus the neverthrow of the store stays inside this module,
+ * and it never crosses the tool boundary.
+ *
+ * `ensureSessionState` makes sure that the row of a thread exists. The first run
+ * resolves the analysis of the thread, pins the snapshot, and writes the row. A
+ * later run reads the row and pins nothing. The store insert-if-absent keeps two
+ * concurrent first runs to one row. A pin failure writes no row and returns as
+ * typed data, thus a later run pins again.
+ *
+ * The gateway `load` runs the same operation, thus a tool call never arrives
+ * before the state exists. A fresh row holds the snapshot and no document yet.
+ * Thus `load` gives the empty draft with the stored snapshot, because the pin
+ * writes the snapshot first and the document lands later.
+ *
+ * A store fault, an absent thread, and a pin failure each ride the failed arm
+ * with a short detail. The diagnostic goes to the injected `Logger`, never to the
+ * detail alone.
+ *
+ * The gateway load separates a permanent condition from a transient one. An absent
+ * thread and a wrong thread type are permanent, and a store or pin fault is
+ * transient. The persist is a compare-and-swap against the prior document that the
+ * load read, thus two concurrent turns cannot both land.
+ */
+import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
+import { type ReportSessionState as StoredSessionState } from "../state/report-session-state.js";
+import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+/**
+ * How a failed anchor ends. `absent-thread` and `wrong-thread-type` are permanent
+ * conditions, and `unavailable` is a transient store or pin fault. The gateway load
+ * carries the distinction, thus the tool tells a permanent refusal from a transient one.
+ */
+export type EnsureFailureKind = "absent-thread" | "wrong-thread-type" | "unavailable";
+/**
+ * The outcome of the anchor operation. `ready` carries the durable row, whose
+ * document is `null` until the first document lands. `failed` names the cause as a
+ * short detail and a kind, and the runtime logs the diagnostic beside it.
+ */
+export type EnsureSessionStateResult = {
+    outcome: "ready";
+    state: StoredSessionState;
+} | {
+    outcome: "failed";
+    kind: EnsureFailureKind;
+    detail: string;
+};
+export interface ReportSessionRuntimeDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * The report session-state runtime. The gateway serves the authoring tools, and
+ * `ensureSessionState` anchors the session. The serving path of a report turn runs
+ * `ensureSessionState` at the turn start, and the gateway `load` runs it too, thus
+ * a tool call cannot arrive before the state exists.
+ */
+export interface ReportSessionRuntime {
+    readonly gateway: ReportSessionStateGateway;
+    ensureSessionState(threadId: string): Promise<EnsureSessionStateResult>;
+}
+/**
+ * Build the report session-state runtime bound to a Postgres pool. The factory
+ * closure captures the pool and constructs the session-state store and the thread
+ * store from it, the same way the chat-turn preparation does.
+ */
+export declare function createReportSessionRuntime(deps: ReportSessionRuntimeDeps): ReportSessionRuntime;

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

@@ -0,0 +1,157 @@
+/**
+ * The report session-state runtime -- the durable realization of the session-state
+ * gateway, and the idempotent operation that anchors one report session.
+ *
+ * The runtime binds three parts: the session-state store, the thread store, and
+ * the pin. The tool layer speaks the gateway, and the gateway speaks a plain
+ * discriminated value. Thus the neverthrow of the store stays inside this module,
+ * and it never crosses the tool boundary.
+ *
+ * `ensureSessionState` makes sure that the row of a thread exists. The first run
+ * resolves the analysis of the thread, pins the snapshot, and writes the row. A
+ * later run reads the row and pins nothing. The store insert-if-absent keeps two
+ * concurrent first runs to one row. A pin failure writes no row and returns as
+ * typed data, thus a later run pins again.
+ *
+ * The gateway `load` runs the same operation, thus a tool call never arrives
+ * before the state exists. A fresh row holds the snapshot and no document yet.
+ * Thus `load` gives the empty draft with the stored snapshot, because the pin
+ * writes the snapshot first and the document lands later.
+ *
+ * A store fault, an absent thread, and a pin failure each ride the failed arm
+ * with a short detail. The diagnostic goes to the injected `Logger`, never to the
+ * detail alone.
+ *
+ * The gateway load separates a permanent condition from a transient one. An absent
+ * thread and a wrong thread type are permanent, and a store or pin fault is
+ * transient. The persist is a compare-and-swap against the prior document that the
+ * load read, thus two concurrent turns cannot both land.
+ */
+import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
+import { createThreadStore } from "../memory/thread-store.js";
+import { pinReportSnapshot } from "../report-model/pin-snapshot.js";
+import { createReportSessionStateStore } from "../state/report-session-state.js";
+/** The empty draft of a fresh session. The pin writes the snapshot first, thus the document is empty here. */
+const EMPTY_DRAFT = { title: "", sections: [] };
+/**
+ * Build the report session-state runtime bound to a Postgres pool. The factory
+ * closure captures the pool and constructs the session-state store and the thread
+ * store from it, the same way the chat-turn preparation does.
+ */
+export function createReportSessionRuntime(deps) {
+    const { pool } = deps;
+    const log = (deps.logger ?? createNoopLogger()).named("report-session-runtime");
+    const store = createReportSessionStateStore({ pool, logger: deps.logger });
+    const threads = createThreadStore(pool);
+    /**
+     * A store read or write fault, as a failed outcome. `corrupt_session_state`
+     * names the part that cannot parse. A `DbError` carries its cause to the log.
+     * The identifiers ride as structured fields, never in the message.
+     */
+    function storeFault(threadId, error) {
+        if (error.type === "corrupt_session_state") {
+            log.error("the stored session state cannot parse", { threadId, part: error.part });
+            return { outcome: "failed", kind: "unavailable", detail: `the stored ${error.part} of the session state cannot parse` };
+        }
+        log.error("the session-state store failed", { threadId, ...log.errorFields(error.cause) });
+        return { outcome: "failed", kind: "unavailable", detail: describeDbError(error) };
+    }
+    /**
+     * Pin the snapshot and write the row. A pin failure writes no row, thus a
+     * later run pins again. The write is insert-if-absent, thus two concurrent
+     * first runs make one row and both read the winner back.
+     */
+    async function pinAndWrite(threadId, analysisId) {
+        const pinned = await pinReportSnapshot(pool, analysisId);
+        if (pinned.isErr()) {
+            log.error("the snapshot pin failed", { threadId, analysisId, ...log.errorFields(pinned.error.cause) });
+            return { outcome: "failed", kind: "unavailable", detail: "the artifact ledger read failed" };
+        }
+        const written = await store.writeSnapshot({ threadId, analysisId, snapshot: pinned.value });
+        return written.match((row) => ({ outcome: "ready", state: row }), (error) => storeFault(threadId, error));
+    }
+    async function ensureSessionState(threadId) {
+        const read = await store.readState(threadId);
+        if (read.isErr()) {
+            return storeFault(threadId, read.error);
+        }
+        if (read.value !== null) {
+            // The row exists, thus the anchor holds and the pin stays single.
+            return { outcome: "ready", state: read.value };
+        }
+        const thread = await threads.getThread(threadId);
+        if (thread.isErr()) {
+            log.error("the thread read failed", { threadId, ...log.errorFields(thread.error.cause) });
+            return { outcome: "failed", kind: "unavailable", detail: describeDbError(thread.error) };
+        }
+        if (thread.value === null) {
+            // The pin needs the analysis of the thread. An absent thread names none, and
+            // the absence is a permanent condition.
+            log.error("the thread resolves to no analysis", { threadId });
+            return { outcome: "failed", kind: "absent-thread", detail: "the thread names no analysis" };
+        }
+        if (thread.value.threadType !== "report") {
+            // The session anchors a report thread only. A conversation thread carries no report session,
+            // thus a wrong type writes no row and the detail names the type. The wrong type is permanent.
+            log.error("the thread is not a report thread", { threadId, threadType: thread.value.threadType });
+            return { outcome: "failed", kind: "wrong-thread-type", detail: `the thread is a ${thread.value.threadType} thread, not a report thread` };
+        }
+        return pinAndWrite(threadId, thread.value.analysisId);
+    }
+    /**
+     * Map the durable row onto the gateway load. A fresh row holds the snapshot and
+     * no document, thus the load gives the empty draft. The found load carries the
+     * stored analysis and the prior document as the concurrency token. A row with no
+     * snapshot cannot serve a tool, because the pin writes the snapshot first.
+     */
+    function toLoad(state) {
+        if (state.snapshot === null) {
+            log.error("the session-state row holds no snapshot", { threadId: state.threadId });
+            return { outcome: "failed", detail: "the session state holds no snapshot" };
+        }
+        return {
+            outcome: "found",
+            state: { document: state.document ?? EMPTY_DRAFT, snapshot: state.snapshot },
+            analysisId: state.analysisId,
+            token: state.document,
+        };
+    }
+    const gateway = {
+        async load(threadId) {
+            const ensured = await ensureSessionState(threadId);
+            if (ensured.outcome === "failed") {
+                switch (ensured.kind) {
+                    case "absent-thread":
+                        return { outcome: "absent" };
+                    case "wrong-thread-type":
+                        return { outcome: "wrong-type", detail: ensured.detail };
+                    case "unavailable":
+                        return { outcome: "failed", detail: ensured.detail };
+                }
+            }
+            return toLoad(ensured.state);
+        },
+        async persist(threadId, document, expected) {
+            const result = await store.persistDocument({ threadId, document, expected });
+            return result.match((outcome) => {
+                switch (outcome) {
+                    case "persisted":
+                        return { outcome: "persisted" };
+                    case "conflict":
+                        // A concurrent turn landed first. The turn refuses and reads the state again.
+                        return { outcome: "conflict" };
+                    case "absent":
+                        // The pin writes the row first. A persist that finds no row means the
+                        // pin-first invariant broke.
+                        log.error("the session-state persist matched no row", { threadId });
+                        return { outcome: "failed", detail: "no report session state row exists to persist the document" };
+                }
+            }, (error) => {
+                log.error("the session-state persist failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+    };
+    return { gateway, ensureSessionState };
+}

package/dist/memory/thread-store.d.ts

@@ -22,10 +22,10 @@
  * row and the thread reads as it did; a listing widened with `includeArchived`
  * is the only way to obtain the id it takes, so the recovery is reachable by a
  * host that holds no thread ids it obtained elsewhere.
- * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata rows of the whole subtree in one transaction, so a failure partway
- * leaves both — never a thread stripped of its transcript, nor a transcript
- * with nothing naming it. It is the thread-scoped member of this package's
+ * `purgeThread` is not recoverable: it removes the `messages` rows, the report
+ * session-state rows, and the metadata rows of the whole subtree in one
+ * transaction, so a failure partway leaves them all — never a thread stripped of
+ * its transcript, nor a transcript with nothing naming it. It is the thread-scoped member of this package's
  * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
  * persisted footprint, `purgeThread` one subtree's.
  *

package/dist/memory/thread-store.js

@@ -22,10 +22,10 @@
  * row and the thread reads as it did; a listing widened with `includeArchived`
  * is the only way to obtain the id it takes, so the recovery is reachable by a
  * host that holds no thread ids it obtained elsewhere.
- * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata rows of the whole subtree in one transaction, so a failure partway
- * leaves both — never a thread stripped of its transcript, nor a transcript
- * with nothing naming it. It is the thread-scoped member of this package's
+ * `purgeThread` is not recoverable: it removes the `messages` rows, the report
+ * session-state rows, and the metadata rows of the whole subtree in one
+ * transaction, so a failure partway leaves them all — never a thread stripped of
+ * its transcript, nor a transcript with nothing naming it. It is the thread-scoped member of this package's
  * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
  * persisted footprint, `purgeThread` one subtree's.
  *
@@ -262,10 +262,10 @@ export function createThreadStore(pool) {
          WHERE thread_id = $1 AND deleted_at IS NOT NULL`, [threadId])).map(() => undefined);
     }
     function purgeThread(threadId) {
-        // One transaction for both statements: `messages` is attributable to an
+        // One transaction for every statement: `messages` is attributable to an
         // analysis only by joining through `cortex_analysis_threads`, so a metadata
         // row removed without its messages strands them beyond the reach of any
-        // later reclamation. Either the pair goes or neither does.
+        // later reclamation. Either the whole set goes or none of it does.
         //
         // The explicit message delete must reach the same depth the database
         // cascade reaches. The cascade on `parent_thread_id` removes a
@@ -274,11 +274,20 @@ export function createThreadStore(pool) {
         // would strand a grandchild's transcript exactly as a bare cascade strands
         // a child's.
         //
-        // Messages go first: the walk both statements share reads the very rows
-        // the second one removes, so the reverse order would leave the subtree
-        // unresolvable by the time its transcripts were named.
+        // The session state of a report thread goes the same way, and for the same
+        // reason: `cortex_report_session_state` carries no foreign key to
+        // `cortex_analysis_threads` either, so the cascade cannot reach it. Its row
+        // holds a whole draft document, and a purged thread can never be composed
+        // again, so a row left behind is dead weight until the analysis purge runs.
+        //
+        // Messages go first, and the thread rows go last: the walk every statement
+        // shares reads the very rows the last one removes. Thus a thread delete before
+        // the others leaves the subtree unresolvable before a later statement names its
+        // transcripts and its drafts.
         return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query(`${SUBTREE_CTE}
          DELETE FROM messages WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId]))
+            .andThen(() => tryMutation("thread-store.purgeThread.reportSessionState", () => client.query(`${SUBTREE_CTE}
+         DELETE FROM cortex_report_session_state WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query(`${SUBTREE_CTE}
          DELETE FROM cortex_analysis_threads WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             .map(() => undefined));

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

@@ -0,0 +1 @@
+export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user, one block at a time, 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.\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 reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, its\n  per-file types. Read it when you must state a fact about the data itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one section, or one atom inside a section. You choose the id,\n  and it is unique in the draft. A section holds atoms. An atom is one piece of\n  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a\n  claim. The block schema of `add_block` gives every kind and its fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nBuild the report as a shape first, then fill each section. Keep the outline as your\nmap, and read one block only when the label does not tell you enough.\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\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap, or the finished document. Read\nthe gaps, repair the draft, and finish again.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Do NOT\n\n- **Transcribe a number from memory.** Every metric, every table cell, and every\n  figure binds to a reference that resolves against the pinned evidence.\n- **Start a run, or change the analysis.** You read the analysis; you never run it\n  and never write to it. You hold no tool that does either, and that is by design.\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- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot\n  of this session alone. Do not cite an artifact that the snapshot does not hold.\n- **Rebuild when one amend serves.** One feedback is one block change. Change, move,\n  or remove that block by its id, and do not re-author the report.\n- **Leave a gap unread.** When `finish_draft` or `preview_report` reports a gap or\n  an unresolved reference, repair it. Do not present a report that does not finish.\n";

package/dist/prompts/report-session.js

@@ -0,0 +1,89 @@
+export const reportSessionPrompt = `# Report Builder
+
+You compose a scientific report for the user, one block at a time, and you ground
+every claim in the analysis. The user talks with you across the whole session, and
+you build the report through that conversation. You author the structure and the
+prose; each number and each figure comes from the evidence, never from memory.
+
+## What You Were Handed Is Authoritative
+
+The conversation already carries the task: which analysis, which audience, and the
+findings the user cares about. Start from what is in front of you. Reach for a read
+tool only where the context is thin, and reach in a targeted way:
+
+- \`inspect_data_profile\` — what the dataset is: its design, its organism, its
+  per-file types. Read it when you must state a fact about the data itself.
+- \`inspect_run\` — what a run produced, and where its outputs are. Read it when you
+  must ground a claim in a run's results.
+- \`workspace_search\` — the ranked files that nothing in the conversation named. It
+  gives descriptions and metadata, not contents.
+- \`read_file\`, \`list_files\`, \`file_stat\`, \`grep\` — the contents, the listing, and
+  the size of a file that a search or a run pointed you at.
+
+Do not orient again when a prior turn already read what you need — its results are
+still in your context. To reach further is targeted, not a fresh sweep.
+
+## Compose from Typed Blocks
+
+A report is a tree of typed blocks, and you build it with the authoring tools:
+
+- \`set_title\` — name the whole report. A draft starts with none, and it needs one.
+- \`add_block\` — add one section, or one atom inside a section. You choose the id,
+  and it is unique in the draft. A section holds atoms. An atom is one piece of
+  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a
+  claim. The block schema of \`add_block\` gives every kind and its fields.
+- \`read_outline\` — the primary view of the draft: each id, each kind, each depth,
+  and a short label. Read the outline, not the whole draft, to see where you are.
+- \`read_block\` — one block in full, when its outline label is not enough.
+
+Build the report as a shape first, then fill each section. Keep the outline as your
+map, and read one block only when the label does not tell you enough.
+
+## Ground Every Claim
+
+Each number, each table, each figure, and each citation binds to a reference, and a
+reference points at the pinned evidence of this session. The evidence is frozen at
+the start of the session, thus a later run does not change what a reference
+resolves to. Bind every value. Never transcribe a number that you remember.
+
+\`finish_draft\` checks the whole draft against the schema, the id rule, and the
+structural tier. It returns each completeness gap, or the finished document. Read
+the gaps, repair the draft, and finish again.
+
+## Revise on Feedback
+
+When the user asks for a change, amend the one block that must change:
+
+- \`change_block\` — replace one atom, or retitle one section, by its id.
+- \`move_block\` — move one block to a new place by its id.
+- \`remove_block\` — remove one block, and its subtree, by its id.
+
+Name the block by the id that the outline gives, and amend that block alone. Do not
+rebuild the report to make one change.
+
+## Preview
+
+\`preview_report\` renders the current draft to a page and gives back where it
+landed, so the user can see the report. It finishes the draft first: an incomplete
+draft comes back as a gap list, and no page renders. On a pass it resolves each
+reference and stages each bound figure beside the page. When a reference does not
+resolve, it names the block, and you repair that binding. When the tool reports that
+the reference resolver is absent, tell the user, and do not preview again. Preview
+when the draft is ready to show, or when you want to confirm that each reference
+resolves.
+
+## Do NOT
+
+- **Transcribe a number from memory.** Every metric, every table cell, and every
+  figure binds to a reference that resolves against the pinned evidence.
+- **Start a run, or change the analysis.** You read the analysis; you never run it
+  and never write to it. You hold no tool that does either, and that is by design.
+- **Invent a path.** Name a file by what a search or a run gave you. Never guess a
+  location, and never hardcode one.
+- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot
+  of this session alone. Do not cite an artifact that the snapshot does not hold.
+- **Rebuild when one amend serves.** One feedback is one block change. Change, move,
+  or remove that block by its id, and do not re-author the report.
+- **Leave a gap unread.** When \`finish_draft\` or \`preview_report\` reports a gap or
+  an unresolved reference, repair it. Do not present a report that does not finish.
+`;

package/dist/providers/ai-sdk.d.ts

@@ -32,6 +32,16 @@ export interface AiSdkProviderDeps {
     readonly logger?: Logger;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /** The retry limit of the harness envelope. Defaults to {@link RETRY_MAX_RETRIES}. */
+    readonly maxRetries?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in milliseconds.
+     * The provider hands the value to the SDK as the bound for each gap between
+     * two content chunks of a stream. The value also names itself in the error of
+     * a stream that the bound stopped. When the field is absent, the provider
+     * hands the SDK no bound.
+     */
+    readonly requestTimeoutMs?: number;
 }
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
@@ -52,6 +62,27 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
 } | {
     readonly kind: "openai-compatible";
     readonly name: string;
@@ -62,6 +93,27 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
 };
 export interface ConfiguredAiSdkProviderDeps {
     readonly config: AiSdkProviderConfig;
@@ -78,11 +130,36 @@ export interface ConfiguredAiSdkProviderDeps {
  */
 export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDelay: number, random?: () => number): number;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
+/**
+ * Wrap a fetch so that the wait until the response starts does not exceed
+ * `requestTimeoutMs`. The wrapper arms one timer for each fetch call. The timer
+ * runs from the send until the fetch promise settles, and the headers of the
+ * response settle it. On expiry the wrapper aborts a dedicated controller with a
+ * `RequestTimeoutError` reason, and it composes that controller with the caller
+ * signal through `AbortSignal.any`. Thus the caller signal keeps its normal
+ * effect, and a caller abort stays a cancellation.
+ *
+ * The guard bounds the response start only. The SDK bounds each later gap of a
+ * streamed body with its own `chunkMs` setting, thus no timer of the wrapper
+ * survives the headers. Thus a stream with steady content does not trip the
+ * guard, whatever its total length. One fetch call is one attempt, because the
+ * SDK retries are off, thus the window is per attempt.
+ *
+ * When the field is absent, `createConfiguredAiSdkProvider` installs no wrapper,
+ * and the behavior stays byte-identical.
+ */
+export declare function wrapFetchWithRequestTimeout(fetchImpl: FetchLike, requestTimeoutMs: number): FetchLike;
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it
  * is never passed per `ChatRequest`), so N models require N provider
  * instances over one shared connection configuration — one instance serves the
  * single model it was built with.
+ *
+ * When the config sets `requestTimeoutMs`, the provider wraps the effective fetch
+ * (`config.fetch ?? globalThis.fetch`) with the response-start guard, it hands
+ * the value to the stream call as the SDK chunk bound, and it advertises the
+ * value on the returned instance. When the field is absent, it installs no
+ * wrapper, it hands the SDK no bound, and it advertises no value.
  */
 export declare function createConfiguredAiSdkProvider(deps: ConfiguredAiSdkProviderDeps): ChatProvider;