@inflexa-ai/harness 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Inflexa
+Copyright 2026 Inflexa, Inc.
+
+This product includes software developed by Inflexa, Inc.
+and the Inflexa open-source community.

package/README.md

@@ -0,0 +1,58 @@
+# @inflexa-ai/harness
+
+`@inflexa-ai/harness` is the host-agnostic agent harness — the `runAgent` loop, durable workflows, the sandbox submit/recv 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
+
+Requirements:
+
+- Node.js `>=24` (the runtime; Bun is used only to run tests)
+- Postgres with pgvector (app tables + durable workflow state)
+- a sandbox backend, selected by `SANDBOX_BACKEND` (`docker` | `k8s`)
+- a chat/embedding provider — Anthropic, or any OpenAI-compatible endpoint
+
+```bash
+npm install @inflexa-ai/harness   # or add file:../harness from an in-repo embedder
+
+tsc -p tsconfig.json              # build: emit dist/ from src/ (also `npm run build`)
+bun test                          # run the test suite
+```
+
+The package emits `dist/` from `src/` and publishes only `dist`. Most configuration arrives through dependency objects passed to the composition point — the LLM backend, for instance, is a fully injected provider config (endpoint/key/model or a `LanguageModel` instance), not read from env; helper modules read conventional env vars (`DB_PG_*`, sandbox limits) — see `CONTEXT.md` and the specs for the catalog.
+
+## Public surface
+
+Import the curated, embedder-facing surface from the package root. Every deep subpath (`@inflexa-ai/harness/...`) stays importable for advanced wiring; the barrel is additive.
+
+```ts
+import {
+    assembleCoreRuntime,            // host-neutral composition point
+    createConversationAgent,
+    createAnthropicProvider,        // ChatProvider — Anthropic
+    createConfiguredAiSdkProvider,  // ChatProvider — any OpenAI-compatible endpoint
+    createEmbeddingProvider,
+    createLocalRunAuthorizer,       // RunAuthorizer    seam (local default)
+    createNoopBillingResolver,      // ResolveBilling   seam
+    createNoopRunCharge,            // RunCharge        seam
+    createNoopArtifactRegistry,     // ArtifactRegistry seam
+    UnavailablePreviewPublisher,    // PreviewPublisher seam
+    createDbosRunLauncher,          // shared RunLauncher
+    defineTool,
+    runAgent,
+    makeLocalAuth,
+} from "@inflexa-ai/harness";
+```
+
+`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **five capability seams** an embedder wires — `RunAuthorizer`, `ResolveBilling`, `ArtifactRegistry`, `RunCharge`, `PreviewPublisher` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all five ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface.
+
+## How it executes
+
+Chat is a plain in-process turn (`prepareChatTurn` → `runAgent` → `appendTurn`); the harness ships no HTTP layer, so 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.
+
+The sandbox protocol is submit-then-retrieve, which is what lets a long run survive a host restart: the host `POST /exec`s a command and retrieves the result over one of two transports — **poll** (the default: the host asks, the sandbox initiates nothing and needs no network egress) or **callback** (opt-in: the sandbox POSTs signed callbacks to an ingress the embedder runs). Both exec endpoints are HMAC signature-authenticated. See the [`harness-sandbox-exec`](./openspec/specs/harness-sandbox-exec/) spec.
+
+## Further reading
+
+- [`CONTEXT.md`](./CONTEXT.md) — domain glossary and load-bearing patterns
+- [`openspec/specs/`](./openspec/specs/) — feature specs and the source of truth for architectural decisions
+- [`CLAUDE.md`](./CLAUDE.md) — working conventions, public-interface map, and the seam/session model

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

@@ -0,0 +1,105 @@
+/**
+ * The conversation agent — the harness composition root.
+ *
+ * `createConversationAgent` is the one place dependencies are exploded apart
+ * (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;
+ * the wiring lines below *are* the dependency graph, made visible.
+ *
+ * The system prompt is static composition — SOUL kernel + SOUL conversational
+ * + the conversation prompt — with no processor pipeline.
+ *
+ * `executePlan` is wired here — it launches the DBOS `executeAnalysis` parent
+ * workflow under `workflowId = runId` (the bare run UUID) through the
+ * `RunLauncher` seam and returns the runId (results are pull-only via
+ * `inspectRun` on a later turn). `run_ephemeral`
+ * is wired here too — it mints a run authorization, starts the turn-scoped DBOS
+ * `ephemeral` workflow, and awaits the result inline; chat disconnect cancels
+ * the workflow and it is never recovered. `iterateReport` is wired here too — in-process Nunjucks
+ * rendering driven by the in-process `report-builder` agent (no sandbox);
+ * the 4 custom report tools (`build_report`, `submit_report`,
+ * `preview_snapshot`, `mint_preview_url`) plus the version-fs write tools
+ * (`write_file`, `edit_file`, `read_file`, `mkdir` from `createVersionFsTools`)
+ * are constructed inside the runner so they share closure-captured outcome
+ * state + preview-dir paths.
+ * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
+ * wired here over the `WorkspaceFilesystem` seam.
+ */
+import type { Pool } from "pg";
+import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
+import type { ResourcePolicy } from "../config/resource-limits.js";
+import type { ChromeConfig } from "../lib/chrome.js";
+import type { AgentDefinition } from "../loop/types.js";
+import type { ChatProvider, EmbeddingProvider } from "../providers/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 { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { RunLauncher } from "../execution/run-launcher.js";
+import { type IterateReportDeps } from "../tools/iterate-report.js";
+import type { EphemeralWorkflowInput, EphemeralResult } from "../execution/ephemeral-runner.js";
+/** Canonical agent id — the single source of truth. */
+export declare const CONVERSATION_AGENT_ID: "conversation-agent";
+/** The shared dependencies the composition root explodes apart. */
+export interface ConversationAgentDeps {
+    /** The LLM seam every loop-driving tool runs its sub-agent on. */
+    readonly provider: ChatProvider;
+    /** Postgres pool — plan persistence, run inspection, workspace index, working memory. */
+    readonly pool: Pool;
+    /** Embedding seam — workspace semantic search. */
+    readonly embedding: EmbeddingProvider;
+    /** Workspace filesystem read seam — `read_file` and `grep`. */
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Model id — provenance / metric label; the provider owns the wire model. */
+    readonly model: string;
+    /**
+     * Registered `executeAnalysis` workflow callable — produced by
+     * `registerExecuteAnalysis` (wired by `assembleCoreRuntime`). `executePlan`
+     * launches it through the `RunLauncher` seam to start the run.
+     */
+    readonly executeAnalysisWorkflow: (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+    /**
+     * Registered `ephemeral` workflow — `run_ephemeral` mints a run authorization,
+     * starts it, and awaits the result inline within the chat turn.
+     */
+    readonly ephemeralWorkflow: (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+    /** Workspace-root resolution seam (see workspace/paths.ts). */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /**
+     * Async-edge run-authorization seam — injected, not constructed here.
+     * `execute_plan` and `run_ephemeral` turn the caller's opaque auth into a
+     * durable `RunSession` through it. The managed root injects the platform
+     * realization; the OSS root injects the local one.
+     */
+    readonly runAuthorizer: RunAuthorizer;
+    /**
+     * Durable-run launch seam — `execute_plan` and `run_ephemeral` start their
+     * workflows through it so the durability engine stays out of the tools.
+     */
+    readonly runLauncher: RunLauncher;
+    /**
+     * Preview-publishing seam factory for `iterate_report` — injected, not
+     * constructed here. The managed root closes its platform deps over this; the
+     * OSS root returns the "unavailable" publisher.
+     */
+    readonly createPreviewPublisher: IterateReportDeps["createPreviewPublisher"];
+    /** API keys for the external bio/chem data sources. */
+    readonly bioKeys: BioToolKeys;
+    /** Root templates dir for in-process report rendering (`iterateReport`). */
+    readonly templatesDir: string;
+    /** Skills root; the in-process report-builder gets `report-html` skill tools. */
+    readonly skillsDir: string;
+    /** Headless-Chrome config for report snapshot/preview rendering. */
+    readonly chrome: ChromeConfig;
+    /**
+     * Host resource policy — per-step ceilings + machine budget. `generate_plan`
+     * states the ceilings to the planner and validates against them;
+     * `execute_plan` snapshots the budget into the workflow input. Absent,
+     * planning guidance and scheduling keep their legacy behavior.
+     */
+    readonly resourcePolicy?: ResourcePolicy;
+}
+/** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
+export declare function createConversationAgent(deps: ConversationAgentDeps): AgentDefinition;

package/dist/agents/conversation-agent.js

@@ -0,0 +1,140 @@
+/**
+ * The conversation agent — the harness composition root.
+ *
+ * `createConversationAgent` is the one place dependencies are exploded apart
+ * (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;
+ * the wiring lines below *are* the dependency graph, made visible.
+ *
+ * The system prompt is static composition — SOUL kernel + SOUL conversational
+ * + the conversation prompt — with no processor pipeline.
+ *
+ * `executePlan` is wired here — it launches the DBOS `executeAnalysis` parent
+ * workflow under `workflowId = runId` (the bare run UUID) through the
+ * `RunLauncher` seam and returns the runId (results are pull-only via
+ * `inspectRun` on a later turn). `run_ephemeral`
+ * is wired here too — it mints a run authorization, starts the turn-scoped DBOS
+ * `ephemeral` workflow, and awaits the result inline; chat disconnect cancels
+ * the workflow and it is never recovered. `iterateReport` is wired here too — in-process Nunjucks
+ * rendering driven by the in-process `report-builder` agent (no sandbox);
+ * the 4 custom report tools (`build_report`, `submit_report`,
+ * `preview_snapshot`, `mint_preview_url`) plus the version-fs write tools
+ * (`write_file`, `edit_file`, `read_file`, `mkdir` from `createVersionFsTools`)
+ * are constructed inside the runner so they share closure-captured outcome
+ * state + preview-dir paths.
+ * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
+ * wired here over the `WorkspaceFilesystem` seam.
+ */
+import { createWorkingMemory } from "../memory/working-memory.js";
+import { conversationPrompt } from "../prompts/conversation.js";
+import { composeSystemPrompt } from "./system-prompt.js";
+// Bio-lookup leaf tools (pure — no dependencies).
+import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, searchCompoundsTool, getBioactivityTool, searchTargetsTool, getMechanismTool, getDrugInfoTool, searchPubchemCompoundTool, getPubchemCrossRefsTool, getPubchemAssaysTool, searchOpenTargetsTool, getTargetSafetyTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, searchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
+import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
+// Dependency-bearing tool factories.
+import { createGeneratePlanTool, createLiteratureReviewerTool, createInspectRunTool, createGenerateAnalogyReportTool } from "../tools/research/index.js";
+import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createShowPlanTool, createWorkspaceSearchTool, showFileTool, } from "../tools/workspace/index.js";
+import { showUserTool } from "../tools/display/index.js";
+import { createUpdateWorkingMemoryTool } from "../tools/memory/index.js";
+import { createExecutePlanTool } from "../tools/execute-plan.js";
+import { createRunEphemeralTool } from "../tools/run-ephemeral.js";
+import { createIterateReportTool } from "../tools/iterate-report.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. */
+const CONVERSATION_MAX_ITERATIONS = 50;
+/** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
+export function createConversationAgent(deps) {
+    const { provider, pool, embedding, workspaceFs, model, executeAnalysisWorkflow, ephemeralWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, } = deps;
+    const workingMemory = createWorkingMemory(pool);
+    const ncbi = createNcbiTools(bioKeys);
+    const chemDb = createChemDbTools(bioKeys);
+    const tools = [
+        // Bio-lookup.
+        searchGeneTool,
+        searchPathwayTool,
+        lookupGoTermTool,
+        searchInteractionsTool,
+        ncbi.searchPubMed,
+        ncbi.getArticleDetails,
+        ncbi.getArticleFullText,
+        // ChEMBL.
+        searchCompoundsTool,
+        getBioactivityTool,
+        searchTargetsTool,
+        getMechanismTool,
+        getDrugInfoTool,
+        // PubChem.
+        searchPubchemCompoundTool,
+        getPubchemCrossRefsTool,
+        getPubchemAssaysTool,
+        // Translational medicine.
+        searchOpenTargetsTool,
+        getTargetSafetyTool,
+        searchPharmgkbTool,
+        searchFaersTool,
+        searchClinicalTrialsTool,
+        searchGeoDatasetsTool,
+        searchDgidbTool,
+        // Preclinical.
+        searchBgeeExpressionTool,
+        getImpcKoProfileTool,
+        // Off-target liability.
+        checkSafetyPanelTool,
+        // EPA CompTox.
+        chemDb.searchToxcast,
+        chemDb.searchCtxHazard,
+        chemDb.searchCtxChemical,
+        chemDb.searchCtxExposure,
+        // Execution.
+        createInspectRunTool(pool),
+        createGeneratePlanTool({ provider, pool, model, resourcePolicy }),
+        createExecutePlanTool({
+            pool,
+            executeAnalysisWorkflow,
+            runAuthorizer,
+            runLauncher,
+            resourcePolicy,
+        }),
+        createRunEphemeralTool({
+            workflow: ephemeralWorkflow,
+            runAuthorizer,
+            runLauncher,
+        }),
+        createIterateReportTool({
+            provider,
+            pool,
+            resolveWorkspaceRoot,
+            model,
+            templatesDir,
+            skillsDir,
+            chrome,
+            createPreviewPublisher,
+        }),
+        // Display.
+        showUserTool,
+        createShowPlanTool(pool),
+        showFileTool,
+        // Batch literature/biology research (sub-agent as a loop-driving tool).
+        createLiteratureReviewerTool({ provider, model, bioKeys }),
+        // Cross-domain analogy generation (sub-agent as a loop-driving tool).
+        createGenerateAnalogyReportTool({ provider, model, bioKeys }),
+        // Workspace semantic search + raw read/grep over the read seam.
+        createWorkspaceSearchTool(pool, embedding),
+        createReadFileTool(workspaceFs),
+        createListFilesTool(workspaceFs),
+        createFileStatTool(workspaceFs),
+        createGrepTool(workspaceFs),
+        // Working memory.
+        createUpdateWorkingMemoryTool(workingMemory),
+    ];
+    return {
+        id: CONVERSATION_AGENT_ID,
+        systemPrompt: composeSystemPrompt(conversationPrompt),
+        model,
+        tools,
+        maxIterations: CONVERSATION_MAX_ITERATIONS,
+    };
+}

package/dist/agents/report-builder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Report Builder Agent — in-process templating agent (no sandbox).
+ *
+ * Authors HTML reports via Jinja2 templating. Runs in the Cortex Node
+ * process — file IO is in-process via the `versionFs` tool roster, rendering
+ * is Node-side via Nunjucks (`build_report` tool), and visual validation
+ * uses headless Chrome via the `preview_snapshot` tool.
+ *
+ * The agent receives a complete brief from iterate-report's pre-flight
+ * (assets staged, columns parsed, sections fully composed) and has no
+ * discovery surface — its workspace is rooted at the version directory.
+ *
+ * NOT a sandbox-agent catalog member (per design Decision #2 — not
+ * plannable). The full tool roster is constructed inside the runner so
+ * each tool shares the runner's closure-captured outcome state and
+ * preview-dir paths; this factory just packages the result into a plain
+ * `AgentDefinition`.
+ */
+import type { AgentDefinition } from "../loop/types.js";
+import type { Tool } from "../tools/define-tool.js";
+export declare const REPORT_BUILDER_AGENT_ID = "report-builder";
+export interface CreateReportBuilderAgentDeps {
+    /** Model id — provenance / metric label; the provider owns the wire model. */
+    readonly model: string;
+    /**
+     * Full tool roster — the 4 custom report tools plus the in-process
+     * versionFs surface, all constructed inside the runner so they close
+     * over the iteration's outcome state and preview-dir paths.
+     */
+    readonly tools: readonly Tool[];
+}
+export declare function createReportBuilderAgent(deps: CreateReportBuilderAgentDeps): AgentDefinition;

package/dist/agents/report-builder.js

@@ -0,0 +1,31 @@
+/**
+ * Report Builder Agent — in-process templating agent (no sandbox).
+ *
+ * Authors HTML reports via Jinja2 templating. Runs in the Cortex Node
+ * process — file IO is in-process via the `versionFs` tool roster, rendering
+ * is Node-side via Nunjucks (`build_report` tool), and visual validation
+ * uses headless Chrome via the `preview_snapshot` tool.
+ *
+ * The agent receives a complete brief from iterate-report's pre-flight
+ * (assets staged, columns parsed, sections fully composed) and has no
+ * discovery surface — its workspace is rooted at the version directory.
+ *
+ * NOT a sandbox-agent catalog member (per design Decision #2 — not
+ * plannable). The full tool roster is constructed inside the runner so
+ * each tool shares the runner's closure-captured outcome state and
+ * preview-dir paths; this factory just packages the result into a plain
+ * `AgentDefinition`.
+ */
+import { reportBuilderPrompt } from "../prompts/report-builder.js";
+export const REPORT_BUILDER_AGENT_ID = "report-builder";
+/** Runaway guard — Jinja recovery may take several build/edit cycles. */
+const REPORT_BUILDER_MAX_ITERATIONS = 75;
+export function createReportBuilderAgent(deps) {
+    return {
+        id: REPORT_BUILDER_AGENT_ID,
+        systemPrompt: reportBuilderPrompt,
+        model: deps.model,
+        tools: deps.tools,
+        maxIterations: REPORT_BUILDER_MAX_ITERATIONS,
+    };
+}

package/dist/agents/sandbox/__fixtures__/deps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Test-only `SandboxAgentDeps` builder. Hands every dependency a stub so
+ * `createSandboxAgent` builds without touching Postgres, the network, or
+ * a real sandbox.
+ */
+import type { Pool } from "pg";
+import type { ChatProvider } from "../../../providers/types.js";
+import type { SandboxClient } from "../../../sandbox/client.js";
+import type { WorkspaceFilesystem } from "../../../workspace/filesystem.js";
+import type { SandboxAgentDeps } from "../shared.js";
+export declare function makeFakeSandboxClient(): SandboxClient;
+export declare function makeFakeWorkspaceFs(): WorkspaceFilesystem;
+export declare function makeFakeChatProvider(): ChatProvider;
+export declare function makeFakePool(): Pool;
+export interface MakeDepsOverrides {
+    readonly model?: string;
+    readonly analysisId?: string;
+    readonly runId?: string;
+    readonly stepId?: string;
+    readonly workflowId?: string;
+    readonly allowedWritePrefix?: string;
+}
+export declare function makeFakeSandboxAgentDeps(over?: MakeDepsOverrides): SandboxAgentDeps;