@inflexa-ai/harness 0.45.0 → 0.46.0

package/README.md

@@ -1,6 +1,6 @@
 # @inflexa-ai/harness
 
-`@inflexa-ai/harness` is the host-agnostic agent harness — the `runAgent` loop, durable workflows, the sandbox submit and poll protocol, and the provider interfaces. It is a **library, not a server**: it ships everything that does not depend on a particular host, and an embedder supplies the composition root, transport, and any non-local seam realizations.
+`@inflexa-ai/harness` is the host-agnostic agent harness — the agent loop on the AI SDK, durable workflows, the sandbox submit and poll protocol, and the provider interfaces. It is a **library, not a server**: it ships everything that does not depend on a particular host, and an embedder supplies the composition root, transport, and any non-local seam realizations.
 
 ## Run locally
 
@@ -42,11 +42,14 @@ import {
     createNoopLogger,               // Logger — discards (the fallback when none is wired)
     defaultErrorFields,             // the shipped `Logger.errorFields` mapping
     defineTool,
-    runAgent,
     makeLocalAuth,
 } from "@inflexa-ai/harness";
 ```
 
+No embedder drives the agent loop. A host opens a chat turn with the `open` of `CoreRuntime.chatTurns`, and it reads the frames of the turn with `read`. The harness runs the turn as a durable workflow, and it makes the model, the usage recorder, and the approval binding of the turn from its runtime. A test of an embedder gets a scripted model (`scriptedModel`) and the chat turns of a runtime with no workflow engine (`inProcessChatTurns`) from the test kit `@inflexa-ai/harness/testing`.
+
+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.
 
 ## Logging
@@ -96,7 +99,7 @@ function pinoAsHarnessLogger(p: pino.Logger, names: readonly string[] = []): Log
 
 ## How it executes
 
-Chat is a plain in-process turn. A turn is `runChatTurn`, and the harness stores the opening, each round, and the outcome of the turn. The harness ships no HTTP layer, thus the host owns the route. Compute-heavy work runs as **durable workflows** — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runAgent` primitive runs in both modes; durability and the event sink are injected, so the loop body is identical.
+A chat turn is a **durable workflow**. The harness stores the opening, each round, and the outcome of the turn, and a recovery continues a turn from its checkpoints. The harness ships no HTTP layer, thus the host owns the route. Compute-heavy work runs as durable workflows too — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runLoop` primitive runs in each workflow, and each model call and each tool call is a durable step.
 
 The sandbox protocol is submit-then-poll, which lets a long run survive a host restart. Each exec runs inside one durable step: the host submits the command with `POST /exec`, and then it polls `GET /exec/{execId}?since={cursor}` until the result. A recovered step submits the same exec id again, and the sandbox gives the existing record, thus the command does not run again. The sandbox initiates nothing and has no egress, and confinement keeps each other peer away from its exec port. Refer to the [`harness-sandbox-exec`](./openspec/specs/harness-sandbox-exec/) spec.
 

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

@@ -5,7 +5,7 @@
  * (see the harness-durable-runtime spec): it receives the shared deps once — `ChatProvider`, `Pool`,
  * `EmbeddingProvider`, the model id — and hands each tool exactly what it
  * needs. Pure leaf tools take nothing; dependency-bearing tools get their
- * factory inputs. By the time `runAgent` sees a tool it is fully dep-bound;
+ * factory inputs. By the time `runLoop` sees a tool it is fully dep-bound;
  * the wiring lines below *are* the dependency graph, made visible.
  *
  * The system prompt is static composition — SOUL kernel + SOUL conversational
@@ -31,12 +31,14 @@ import type { ChromeConfig } from "../lib/chrome.js";
 import type { AcquireEyes } from "../lib/eyes.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { AgentDefinition } from "../loop/types.js";
+import type { SubAgentRegistrar } from "../loop/sub-agent.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
 import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type BioToolKeys } from "../tools/bio/keys.js";
+import type { KnowledgeClient } from "../tools/knowledge/index.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
@@ -44,6 +46,7 @@ import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
+import { type WebSearchEngine } from "../tools/research/web-search.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 /**
@@ -52,7 +55,7 @@ export declare const CONVERSATION_AGENT_ID: "conversation-agent";
  * what is importable that a sandbox agent has — read host-side, so answering
  * "does this environment have X?" costs a lookup rather than a container.
  */
-export interface ConversationAgentDeps extends EnvironmentStorePaths {
+export type ConversationAgentDeps = EnvironmentStorePaths & {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /**
@@ -63,10 +66,17 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
     readonly usageRecorder?: UsageRecorder;
     /** Adds `read_tool_output`, and each loop-driving tool gives the same store to its sub-agent. */
     readonly toolOutputStore?: ToolOutputStore;
+    /** The web-search engine the embedder injected; set, `web_search` attaches, absent it does not. `web_fetch` attaches either way. */
+    readonly webSearch?: WebSearchEngine;
     /** Shared host-side bibliographic verification service. */
     readonly citationResolver: CitationResolver;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */
     readonly provider: ChatProvider;
+    /**
+     * Makes the function of each sub-agent of the agent: the planner and the analogy reporter. The assembly gives
+     * `registerSubAgent`, thus a sub-agent of a turn workflow runs as a child workflow. A test gives `inProcessSubAgent`.
+     */
+    readonly registerSubAgent: SubAgentRegistrar;
     /** Postgres pool — plan persistence, run inspection, workspace index, working memory. */
     readonly pool: Pool;
     /** Embedding seam — workspace semantic search. */
@@ -107,6 +117,12 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
     readonly runLauncher: RunLauncher;
     /** API keys for the external bio/chem data sources. */
     readonly bioKeys: BioToolKeys;
+    /**
+     * The knowledge service client, for the planner that `generate_plan` drives.
+     * Absent, the planner attaches no knowledge tool. The conversation agent
+     * itself gets `knowledge_recommend` through `hostTools`, from the embedder.
+     */
+    readonly knowledge?: KnowledgeClient;
     /** Skills root. No tool of the roster reads it. */
     readonly skillsDir: string;
     /** Headless-Chrome config for report snapshot/preview rendering. */
@@ -147,6 +163,6 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * it, the link pass returns at once.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
-}
+};
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export declare function createConversationAgent(deps: ConversationAgentDeps): AgentDefinition;

package/dist/agents/conversation-agent.js

@@ -5,7 +5,7 @@
  * (see the harness-durable-runtime spec): it receives the shared deps once — `ChatProvider`, `Pool`,
  * `EmbeddingProvider`, the model id — and hands each tool exactly what it
  * needs. Pure leaf tools take nothing; dependency-bearing tools get their
- * factory inputs. By the time `runAgent` sees a tool it is fully dep-bound;
+ * factory inputs. By the time `runLoop` sees a tool it is fully dep-bound;
  * the wiring lines below *are* the dependency graph, made visible.
  *
  * The system prompt is static composition — SOUL kernel + SOUL conversational
@@ -25,6 +25,7 @@
  */
 import { createReadToolOutputTool } from "../tools/read-tool-output.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
+import { createEditIntentStore } from "../state/edit-intents.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
@@ -36,10 +37,13 @@ import { createEditFileTool, createFileStatTool, createGrepTool, createListFiles
 import { showUserTool } from "../tools/display/index.js";
 import { createUpdateWorkingMemoryTool } from "../tools/memory/index.js";
 import { createListAvailablePackagesTool } from "../tools/sandbox/list-available-packages.js";
+import { createInspectCapabilityDataTool } from "../tools/capability-data.js";
 import { createListAvailableRefsTool } from "../tools/sandbox/list-available-refs.js";
 import { createExecuteAnalysisTool } from "../tools/execute-analysis.js";
 import { createStartReportSessionTool } from "../tools/start-report-session.js";
 import { createResolveCitationTool } from "../tools/research/resolve-citation.js";
+import { createWebFetchTool } from "../tools/research/web-fetch.js";
+import { createWebSearchTool } from "../tools/research/web-search.js";
 /** Canonical agent id — the single source of truth. */
 export const CONVERSATION_AGENT_ID = "conversation-agent";
 /** Runaway guard — heavy tool-driving turns need generous headroom. */
@@ -48,18 +52,18 @@ const CONVERSATION_MAX_ITERATIONS = 200;
 const CONVERSATION_COMPACTION = { turnStartBudget: 150_000, budget: 200_000 };
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, toolOutputStore, citationResolver, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, toolOutputStore, citationResolver, webSearch, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
-    const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
+    const chemDb = createChemDbTools(bioKeys, { logger: deps.logger });
     const amass = createAmassTools(bioKeys);
     // The write path of this agent: coordinates resolve per call from the
     // session's analysis scope, the write prefix is the analysis root, and
     // every successful write emits a `write-file` provenance session event.
     const mutator = createSessionWorkspaceMutator({
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
-        ...(deps.provenance ? { provenance: deps.provenance } : {}),
-        ...(deps.logger ? { logger: deps.logger } : {}),
+        provenance: deps.provenance,
+        logger: deps.logger,
     });
     const tools = [
         // Identifier resolution — the ENSG most other bio tools key off, and the
@@ -79,8 +83,13 @@ export function createConversationAgent(deps) {
         createResolveCitationTool(citationResolver),
         // Literature outside PubMed. A question about a method, a model or a
         // preprint has no MEDLINE record, thus PubMed alone cannot answer it.
-        createSearchSemanticScholarTool({ ...(bioKeys.semanticScholar === undefined ? {} : { apiKey: bioKeys.semanticScholar }) }),
+        createSearchSemanticScholarTool({ apiKey: bioKeys.semanticScholar }),
         searchArxivTool,
+        // The web step of research — the injected web-search engine (the CLI runs
+        // SearXNG and binds its realization), then the guarded page fetch that
+        // reads what the search found.
+        ...(webSearch ? [createWebSearchTool({ engine: webSearch })] : []),
+        createWebFetchTool({ toolOutputStore }),
         // ChEMBL (compounds / drug / mechanism / bioactivity / targets behind one action).
         chemblTool,
         // PubChem (compound / crossrefs / assays behind one action).
@@ -108,16 +117,21 @@ export function createConversationAgent(deps) {
         // and a host that does asks the user to approve the download. Deciding that
         // blind is how a user gets asked to download something already installed, or
         // told nothing is missing when it is; this is the only tool that can tell.
-        createListAvailableRefsTool({ ...(refStorePath ? { refStorePath } : {}) }),
+        createListAvailableRefsTool({ refStorePath }),
+        // Which datasets a specialist capability cannot run without. `list_available_refs` answers
+        // what the store HOLDS; this answers what a capability WANTS, which no prompt may name and
+        // only a skill otherwise records — and a skill is read by a step agent, not here. Without
+        // it this agent meets an absent source as a dead end and designs around it.
+        createInspectCapabilityDataTool({ refStorePath }),
         // What the STORE holds, pool-scope where the embedder binds the reader:
         // the ask flow of this agent marks the packages the pool does not hold,
         // and the farm of a new analysis is empty — a farm view here would read
         // every pool package as absent. The farm-lock fallback keeps a host
         // with no pool reader on the old answer.
         createListAvailablePackagesTool({
-            ...(farmLockFile ? { farmLockFile } : {}),
-            ...(imagePackagesFile ? { imagePackagesFile } : {}),
-            ...(readPoolInventory ? { readPoolInventory } : {}),
+            farmLockFile,
+            imagePackagesFile,
+            readPoolInventory,
         }),
         // Execution.
         createInspectRunTool(pool),
@@ -128,14 +142,15 @@ export function createConversationAgent(deps) {
             pool,
             resourcePolicy,
             usageRecorder,
-            ...(toolOutputStore ? { toolOutputStore } : {}),
+            toolOutputStore,
             bioKeys,
-            ...(refStorePath ? { refStorePath } : {}),
-            ...(farmLockFile ? { farmLockFile } : {}),
-            ...(imagePackagesFile ? { imagePackagesFile } : {}),
-            ...(readPoolInventory ? { readPoolInventory } : {}),
-            ...(deps.logger ? { logger: deps.logger } : {}),
-        }),
+            knowledge: deps.knowledge,
+            refStorePath,
+            farmLockFile,
+            imagePackagesFile,
+            readPoolInventory,
+            logger: deps.logger,
+        }, deps.registerSubAgent),
         createExecuteAnalysisTool({
             pool,
             executeAnalysisWorkflow,
@@ -144,12 +159,16 @@ export function createConversationAgent(deps) {
             resourcePolicy,
             utilityProvider,
             utilityModel,
-            ...(farmLockFile ? { farmLockFile } : {}),
-            ...(imagePackagesFile ? { imagePackagesFile } : {}),
-            ...(readPoolInventory ? { readPoolInventory } : {}),
-            ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
-            ...(deps.logger ? { logger: deps.logger } : {}),
-            ...(usageRecorder ? { usageRecorder } : {}),
+            farmLockFile,
+            imagePackagesFile,
+            readPoolInventory,
+            // The pre-launch pass resolves the declared reference data of a capability against the
+            // store. Without this path it would read the CONTAINER path, which no host holds, and
+            // refuse every launch of a plan that declares one.
+            refStorePath,
+            extendAnalysisFarm: deps.extendAnalysisFarm,
+            logger: deps.logger,
+            usageRecorder,
         }),
         // The one report path. The tool starts a report thread as a child of the
         // conversation, and the user composes the report there with the Report
@@ -158,9 +177,9 @@ export function createConversationAgent(deps) {
             pool,
             chrome,
             anchorSession: deps.anchorReportSession,
-            ...(deps.eyes ? { eyes: deps.eyes } : {}),
-            ...(deps.provenance ? { provenance: deps.provenance } : {}),
-            ...(deps.logger ? { logger: deps.logger } : {}),
+            eyes: deps.eyes,
+            provenance: deps.provenance,
+            logger: deps.logger,
         }),
         // Display.
         showUserTool,
@@ -172,9 +191,9 @@ export function createConversationAgent(deps) {
             model,
             bioKeys,
             usageRecorder,
-            ...(toolOutputStore ? { toolOutputStore } : {}),
-            ...(deps.logger ? { logger: deps.logger } : {}),
-        }),
+            toolOutputStore,
+            logger: deps.logger,
+        }, deps.registerSubAgent),
         // Workspace semantic search + raw read/grep over the read seam.
         createWorkspaceSearchTool(pool, embedding),
         createReadFileTool(workspaceFs),
@@ -188,7 +207,7 @@ export function createConversationAgent(deps) {
         // a symlink escape stay refused. No sandbox is involved — the mutator
         // writes host-side, exactly as it does for a sandbox agent.
         createWriteFileTool({ mutator }),
-        createEditFileTool({ mutator, workspaceFilesystem: workspaceFs }),
+        createEditFileTool({ mutator, workspaceFilesystem: workspaceFs, intents: createEditIntentStore(pool) }),
         // Working memory.
         createUpdateWorkingMemoryTool(workingMemory, pool),
         // Host-contributed tools ride the same context and dispatch path as the

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

@@ -23,13 +23,12 @@
  * across threads, and the provider cache reuses it.
  */
 import type { Pool } from "pg";
-import type { AuthContext } from "../auth/types.js";
-import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { AuthContext, Identity } from "../auth/types.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { AgentDefinition } from "../loop/types.js";
-import type { DeriveTableRunner } from "../tools/report-session/derive-table.js";
+import type { SandboxClient } from "../sandbox/client.js";
 import type { ReportSessionStateStore } from "../state/report-session-state.js";
-import type { EmbeddingProvider } from "../providers/types.js";
+import type { EmbeddingProvider, ProviderOptions } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ChromeConfig } from "../lib/chrome.js";
@@ -43,13 +42,18 @@ import type { ProvenanceSeam } from "../provenance/seam.js";
 import { type MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
+/**
+ * One tool call for each reply. Each authoring tool edits the one draft of the thread, and the calls of
+ * one reply run at the same time, thus two edits in one round can land in either order.
+ */
+export declare const REPORT_SESSION_PROVIDER_OPTIONS: ProviderOptions;
 /**
  * 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 factory is optional, because a resolver realization can be
  * absent, and the preview tool and the record tool degrade as data when it is.
  */
-export interface ReportSessionAgentDeps {
+export type 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. */
@@ -67,16 +71,11 @@ export interface ReportSessionAgentDeps {
     /** Derivation ledger -- the derivation tool appends one record for each derived table. */
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     /**
-     * Derivation-exec seam -- the derivation tool runs one ephemeral container for each derived table, and
-     * the composition realizes this seam over a registered workflow. Omitted, the tool reports that the
-     * composition gives no sandbox, and it derives nothing.
-     */
-    readonly runDerivation?: DeriveTableRunner;
-    /**
-     * Run-authorization seam -- the derivation tool authorizes the exec and revokes on every terminal path.
-     * Omitted, the tool derives nothing, the same as an absent sandbox client.
+     * Sandbox client -- the derivation tool runs one ephemeral container for each derived table, inside the
+     * step of its call. Omitted, the tool reports that the composition gives no sandbox, and it derives
+     * nothing.
      */
-    readonly runAuthorizer?: RunAuthorizer;
+    readonly sandboxClient?: SandboxClient;
     /** Thread store -- the record tool reads the anchor of the report thread, and the preview tool names it. */
     readonly threads: Pick<ThreadStore, "getThread" | "setAutoTitle">;
     /** Headless-Chrome config -- the eyes tool opens the rendered page. */
@@ -93,6 +92,7 @@ export interface ReportSessionAgentDeps {
      */
     readonly makeResolver?: (scope: {
         analysisId: string;
+        identity: Identity;
         auth: AuthContext;
     }) => Promise<ReferenceResolver>;
     /**
@@ -128,6 +128,6 @@ export interface ReportSessionAgentDeps {
     readonly logger?: Logger;
     /** Adds `read_tool_output`. The loop of a report turn must keep its texts in the same store. */
     readonly toolOutputStore?: ToolOutputStore;
-}
+};
 /** 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

@@ -39,14 +39,22 @@ export const REPORT_SESSION_AGENT_ID = "report-session";
 const REPORT_SESSION_MAX_ITERATIONS = 200;
 /** A session is one long turn that holds page captures, thus it compacts only during the turn, at a higher budget. */
 const REPORT_SESSION_COMPACTION = { budget: 250_000 };
+/**
+ * One tool call for each reply. Each authoring tool edits the one draft of the thread, and the calls of
+ * one reply run at the same time, thus two edits in one round can land in either order.
+ */
+export const REPORT_SESSION_PROVIDER_OPTIONS = {
+    anthropic: { disableParallelToolUse: true },
+    openai: { parallelToolCalls: false },
+};
 /** 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, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl, provenance } = deps;
+    const { derivations, sandboxClient, makeSessionPages, resolvePageUrl, provenance } = 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 } : {};
-    const authoring = createReportAuthoringTools(gateway, { ...observation, ...(logger ? { logger } : {}) });
+    const authoring = createReportAuthoringTools(gateway, { ...observation, logger });
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
         createReadFileTool(workspaceFs),
@@ -72,7 +80,7 @@ export function createReportSessionAgent(deps) {
         createListPinnedArtifactsTool({
             gateway,
             resolveWorkspaceRoot,
-            ...(logger ? { logger } : {}),
+            logger,
         }),
         // The derivation tool. It reshapes the pinned evidence into one table under the
         // session directory, on the sandbox rails of the value tier.
@@ -80,32 +88,31 @@ export function createReportSessionAgent(deps) {
             gateway,
             resolveWorkspaceRoot,
             derivations,
-            ...(runDerivation ? { runDerivation } : {}),
-            ...(runAuthorizer ? { runAuthorizer } : {}),
+            sandboxClient,
             ...observation,
-            ...(logger ? { logger } : {}),
+            logger,
         }),
         // The render-and-preview tool. It resolves the page root per call.
         createPreviewReportTool({
             gateway,
             resolveWorkspaceRoot,
             threads,
-            ...(makeResolver ? { makeResolver } : {}),
-            ...(resolvePageAsset ? { resolvePageAsset } : {}),
-            ...(makeSessionPages ? { makeSessionPages } : {}),
+            makeResolver,
+            resolvePageAsset,
+            makeSessionPages,
             // The preview is the one site that carries the document into the page, thus the read member
             // reaches this tool alone.
             ...observation,
-            ...(logger ? { logger } : {}),
+            logger,
         }),
         // The eyes tool. It opens the rendered page in headless Chrome.
         createExaminePageTool({
             gateway,
             resolveWorkspaceRoot,
             chrome,
-            ...(eyes ? { eyes } : {}),
-            ...(resolvePageUrl ? { resolvePageUrl } : {}),
-            ...(logger ? { logger } : {}),
+            eyes,
+            resolvePageUrl,
+            logger,
         }),
         // The record tool. It gates the whole document, records one version, then prunes each
         // derived table that the recorded document does not bind.
@@ -114,9 +121,9 @@ export function createReportSessionAgent(deps) {
             store,
             threads,
             resolveWorkspaceRoot,
-            ...(makeResolver ? { makeResolver } : {}),
+            makeResolver,
             ...observation,
-            ...(logger ? { logger } : {}),
+            logger,
         }),
     ];
     return {
@@ -126,5 +133,6 @@ export function createReportSessionAgent(deps) {
         tools,
         maxIterations: REPORT_SESSION_MAX_ITERATIONS,
         compaction: REPORT_SESSION_COMPACTION,
+        providerOptions: REPORT_SESSION_PROVIDER_OPTIONS,
     };
 }

package/dist/agents/sandbox/index.d.ts

@@ -26,6 +26,6 @@ export { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
 export declare const SANDBOX_AGENT_META: Readonly<Record<string, AgentMeta>>;
 /**
  * Build every sandbox `AgentDefinition` from the shared deps. The returned
- * record's keys are the agent ids; `runAgent` consumes each value.
+ * record's keys are the agent ids; `runLoop` consumes each value.
  */
 export declare function createSandboxAgents(deps: SandboxAgentDeps): Record<string, AgentDefinition>;

package/dist/agents/sandbox/index.js

@@ -64,7 +64,7 @@ export const SANDBOX_AGENT_META = {
 };
 /**
  * Build every sandbox `AgentDefinition` from the shared deps. The returned
- * record's keys are the agent ids; `runAgent` consumes each value.
+ * record's keys are the agent ids; `runLoop` consumes each value.
  */
 export function createSandboxAgents(deps) {
     return {

package/dist/agents/sandbox/shared.d.ts

@@ -16,7 +16,7 @@
  * must map to a concrete `Tool`; unknown names throw at composition time
  * so misconfigured agents fail at startup, not at the first LLM call.
  */
-import type { Pool } from "pg";
+import type { Querier } from "../../state/db.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
 import type { AgentDefinition } from "../../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
@@ -25,21 +25,28 @@ import type { ExtendAnalysisFarm, SandboxRef } from "../../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { ProvenanceCollector as LineageCollector } from "../../provenance/collector.js";
 import { type BioToolKeys } from "../../tools/bio/keys.js";
-import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
 import { type FileMetadataCell } from "../../tools/sandbox/submit-file-metadata.js";
 import type { AgentMeta, SandboxToolName } from "./types.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import type { Logger } from "../../lib/logger.js";
 import type { CitationResolver } from "../../citations/types.js";
+import { type KnowledgeClient, type TemplateBinding } from "../../tools/knowledge/index.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
- * library docs, and run inspection. Spread into each agent's
- * `meta.tools` so planner-facing metadata and the resolved tool record
+ * library docs, run inspection, and the knowledge template. Spread into each
+ * agent's `meta.tools` so planner-facing metadata and the resolved tool record
  * stay in sync. Keep minimal — only tools every agent genuinely needs.
+ *
+ * The knowledge template is here, not on a specialist, because the template
+ * follows the step: the planner binds a template to a step from the
+ * recommendation and routes that step to whichever specialist owns its data
+ * object. The tool acts only on the template the step grounding names, thus
+ * a step without a template costs nothing, and it attaches only when the
+ * embedder binds a knowledge client (see the registry below).
  */
 export declare const BASE_SANDBOX_TOOLS: readonly SandboxToolName[];
 /** Per-step coordinates the composition root threads through every mutate tool. */
-export interface SandboxStepCoords {
+export type SandboxStepCoords = {
     readonly sandbox: SandboxRef;
     /** Absolute host root of this analysis's workspace tree (resolved at the workflow body). */
     readonly workspaceRoot: string;
@@ -48,13 +55,19 @@ export interface SandboxStepCoords {
     readonly allowedWritePrefix: string;
     /** Absolute unix-ms deadline of each exec. */
     readonly deadlineMs: () => number;
-}
+    /**
+     * The plan settings bound to the template of this step, from the durable
+     * step input. Reaches `knowledge_template` alone. Absent when the step
+     * grounds on no template, or when the host bound nothing.
+     */
+    readonly templateBinding?: TemplateBinding;
+};
 /** The shared dependency graph every sandbox agent draws from. */
-export interface SandboxAgentDeps extends EnvironmentStorePaths {
+export type SandboxAgentDeps = EnvironmentStorePaths & {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly provider: ChatProvider;
-    readonly pool: Pool;
+    readonly pool: Querier;
     readonly sandboxClient: SandboxClient;
     readonly workspaceFs: WorkspaceFilesystem;
     /** Embedding provider for in-sandbox semantic `workspace_search`. Omit to skip that tool. */
@@ -76,12 +89,11 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
     /** Shared resolver. Required only when `meta.tools` declares `resolve_citation`. */
     readonly citationResolver?: CitationResolver;
     /**
-     * Per-run blocker cell (see the harness-sandbox-agents spec). When present, the agent gets a
-     * `report_blocker` tool that records `{ kind: "blocker", reason }` into it;
-     * the sandbox-step body reads the blocker from the transcript, falling back to
-     * the cell. Omit for agents that have no terminal status to declare (such as the data profiler).
+     * The agent gets a `report_blocker` tool (see the harness-sandbox-agents spec), and the
+     * sandbox-step body selects the blocker from the recorded calls of the run. Omit for agents that
+     * have no terminal status to declare (such as the data profiler).
      */
-    readonly blockerHolder?: BlockerHolder;
+    readonly reportsBlocker?: boolean;
     /**
      * When present, the agent declares `submit_file_metadata` from its first request so the
      * tool list stays stable across continuations; the task masks it, the continuation unmasks it.
@@ -95,9 +107,16 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
      * and the package-link prompt layer appends. Without it, neither exists.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
-}
+    /**
+     * The knowledge service client. Bound, an agent that declares
+     * `knowledgeTemplate` gets the tool, over the same mutator as `write_file`.
+     * Absent, the declaration resolves to nothing, which is the default state
+     * of the open-source host and never an error.
+     */
+    readonly knowledge?: KnowledgeClient;
+};
 /** Per-agent override for the prompt composition and tool surface. */
-export interface SandboxAgentPromptOptions {
+export type SandboxAgentPromptOptions = {
     /** Append `sandboxAnalysisStepStandardsPrompt`. Defaults to true. */
     readonly appendAnalysisStepStandards?: boolean;
     /**
@@ -107,7 +126,7 @@ export interface SandboxAgentPromptOptions {
      * exists outside container-local `/tmp`. Defaults to false.
      */
     readonly readOnly?: boolean;
-}
+};
 /**
  * Build one sandbox `AgentDefinition`. The system prompt is composed once
  * (SOUL execution core + agent body + sandbox standards) — no processors, and