@inflexa-ai/harness 0.46.2 → 0.48.0

package/README.md

@@ -50,7 +50,7 @@ No embedder drives the agent loop. A host opens a chat turn with the `open` of `
 
 A failure that a person or time can repair pauses a turn, a run, or a data profile, and the work does not fail. Examples are a billing refusal of the host, a provider outage, and a missing credential. A host lists the active work of an analysis with `CoreRuntime.work`. It stops a work in each state, and it resumes or holds paused work.
 
-`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **four capability seams** an embedder wires — `RunAuthorizer`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all four ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface. Two optional hooks go into the component that uses their values: `resolveRequestHeaders` into each provider, and `resolveSandboxLabels` into the sandbox client config.
+`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **four capability seams** an embedder wires — `RunAuthorizer`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all four ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface. Two optional hooks go into the component that uses their values: `resolveRequestHeaders` into each provider, and `resolveSandboxLabels` into the sandbox client config. A third, `syncSessionFile`, goes into `assembleCoreRuntime`: it receives each file that a chat thread or a report session writes outside a run.
 
 ## Logging
 
@@ -101,7 +101,7 @@ function pinoAsHarnessLogger(p: pino.Logger, names: readonly string[] = []): Log
 
 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.
+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. A consumer holds a sandbox through a lease: the step agent acquires a size with `acquire_sandbox`, and a detached lease workflow owns the machine, its admission against one budget, its idle removal, and its teardown. Refer to the [`sandbox-leases`](./openspec/specs/sandbox-leases/) spec.
 
 ## Further reading
 

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

@@ -26,7 +26,6 @@
 import type { Pool } from "pg";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import type { EnsureSessionStateResult } from "../app/report-session-runtime.js";
-import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { ChromeConfig } from "../lib/chrome.js";
 import type { AcquireEyes } from "../lib/eyes.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
@@ -43,10 +42,12 @@ import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
+import type { SyncSessionFile } from "../workspace/session-files.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
 import { type WebSearchEngine } from "../tools/research/web-search.js";
+import type { ScriptRuntime } from "../tools/script/run-script.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 /**
@@ -143,12 +144,10 @@ export type ConversationAgentDeps = EnvironmentStorePaths & {
      */
     readonly provenance?: ProvenanceSeam;
     /**
-     * Host resource policy — per-step ceilings + machine budget. `generate_plan`
-     * states the ceilings to the planner and validates against them;
-     * `execute_analysis` snapshots the budget into the workflow input. Absent,
-     * planning guidance and scheduling keep their legacy behavior.
+     * The host copy of each file that the agent writes: a derived file or a script of `run_script`, owned by the
+     * thread, and a `write_file` or `edit_file` write, owned by the analysis. See `SyncSessionFile`.
      */
-    readonly resourcePolicy?: ResourcePolicy;
+    readonly syncSessionFile?: SyncSessionFile;
     /**
      * Embedder-contributed conversation-tool seam — additional tools the host
      * supplies, appended after the built-in roster. The harness stays agnostic to
@@ -156,6 +155,8 @@ export type ConversationAgentDeps = EnvironmentStorePaths & {
      * built-in tool.
      */
     readonly hostTools?: readonly Tool[];
+    /** Where the VM of `run_script` comes from. A bundled host gives the embedded paths; see `ScriptRuntime`. */
+    readonly scriptRuntime?: ScriptRuntime;
     /**
      * The farm-extension seam of the embedder. When it is bound,
      * `execute_analysis` links the packages of the plan into the farm of the

package/dist/agents/conversation-agent.js

@@ -44,6 +44,9 @@ 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";
+import { createScriptFileTools } from "../tools/script/file-tools.js";
+import { createScriptScratch } from "../tools/script/scratch.js";
+import { conversationSessionDir } from "../workspace/paths.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. */
@@ -52,7 +55,7 @@ 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, webSearch, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, toolOutputStore, citationResolver, webSearch, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { logger: deps.logger });
@@ -63,9 +66,22 @@ export function createConversationAgent(deps) {
     const mutator = createSessionWorkspaceMutator({
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
         provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
         logger: deps.logger,
     });
-    const tools = [
+    // The scratch directory of each conversation: the scripts of `run_script`, and the files that they derive.
+    const scriptScratch = createScriptScratch({
+        resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
+        sessionDir: conversationSessionDir,
+        provenance: deps.provenance,
+        syncSessionFile: deps.syncSessionFile,
+        logger: deps.logger,
+    });
+    // The lookups and the light work on tables run in a script (`run_script`). Each tool asks no approval, and a
+    // script writes only into the scratch directory of its conversation.
+    const scriptTools = [
+        // Tables of the workspace in, derived files and chart files out.
+        ...createScriptFileTools({ workspaceFs, resolveWorkspaceRoot: deps.resolveWorkspaceRoot, scratch: scriptScratch }),
         // Identifier resolution — the ENSG most other bio tools key off, and the
         // UniProt accession that the structure tools take.
         searchGeneTool,
@@ -112,6 +128,8 @@ export function createConversationAgent(deps) {
         targetSafetyTool,
         // EPA CompTox (toxcast / hazard / chemical / exposure behind one dataset).
         chemDb.comptox,
+    ];
+    const tools = [
         // What reference data this install actually holds. The conversation agent is
         // where provisioning is decided — an embedder may give it a way to install more,
         // and a host that does asks the user to approve the download. Deciding that
@@ -140,10 +158,11 @@ export function createConversationAgent(deps) {
         createGeneratePlanTool({
             conversation: { provider, model },
             pool,
-            resourcePolicy,
             usageRecorder,
             toolOutputStore,
             bioKeys,
+            workspace: { workspaceFs, pool, embedding, resolveWorkspaceRoot: deps.resolveWorkspaceRoot },
+            scriptRuntime: deps.scriptRuntime,
             knowledge: deps.knowledge,
             refStorePath,
             farmLockFile,
@@ -156,7 +175,6 @@ export function createConversationAgent(deps) {
             executeAnalysisWorkflow,
             runAuthorizer,
             runLauncher,
-            resourcePolicy,
             utilityProvider,
             utilityModel,
             farmLockFile,
@@ -193,6 +211,7 @@ export function createConversationAgent(deps) {
             usageRecorder,
             toolOutputStore,
             logger: deps.logger,
+            scriptRuntime: deps.scriptRuntime,
         }, deps.registerSubAgent),
         // Workspace semantic search + raw read/grep over the read seam.
         createWorkspaceSearchTool(pool, embedding),
@@ -219,6 +238,9 @@ export function createConversationAgent(deps) {
         systemPrompt: composeSystemPrompt(conversationPrompt, { identity: true, conversational: true }),
         model,
         tools,
+        scriptTools,
+        scriptRuntime: deps.scriptRuntime,
+        scriptScratch,
         maxIterations: CONVERSATION_MAX_ITERATIONS,
         compaction: CONVERSATION_COMPACTION,
     };

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

@@ -11,11 +11,12 @@
  * 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.
+ * roster omits those tools, and no runtime guard blocks them. No tool runs a
+ * container.
  *
- * The derivation tool is the one tool that runs a container, and it changes no
- * analysis either. It mints no run id, it registers no artifact, and it writes under
- * the directory of the session alone.
+ * A derivation of a table runs in a script (`run_script`), and it changes no
+ * analysis: it mints no run id, it registers no artifact, and it writes under the
+ * directory of the session alone.
  *
  * The definition carries no per-session value. The system prompt composes through
  * `composeSystemPrompt` with the identity part and the conversational part, the
@@ -26,11 +27,10 @@ import type { Pool } from "pg";
 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 { SandboxClient } from "../sandbox/client.js";
 import type { ReportSessionStateStore } from "../state/report-session-state.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 ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ChromeConfig } from "../lib/chrome.js";
 import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
@@ -39,7 +39,9 @@ import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
+import type { SyncSessionFile } from "../workspace/session-files.js";
 import { type MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
+import type { ScriptRuntime } from "../tools/script/run-script.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
 /**
@@ -68,14 +70,8 @@ export type ReportSessionAgentDeps = {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Append-only version store -- the record tool gates the whole document first, then records one version. */
     readonly store: ReportVersionStore;
-    /** Derivation ledger -- the derivation tool appends one record for each derived table. */
+    /** Derivation ledger -- `write_derived` appends one record for each derived table. */
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
-    /**
-     * 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 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. */
@@ -118,16 +114,20 @@ export type ReportSessionAgentDeps = {
     readonly resolvePageUrl?: ResolvePageUrl;
     /**
      * The provenance seam -- the acts of the session as typed events, and the frozen document of the
-     * analysis as opaque bytes. The tools that change the draft, derive a table, preview the page, and
+     * analysis as opaque bytes. The tools that change the draft, preview the page, and
      * record a version each emit through the session member, thus one bound member carries the whole
      * session. The preview asks the read member before each render, and the page then carries the
      * document. An unbound member emits nothing, or gives absence, and every tool acts the same.
      */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that the session writes. See `SyncSessionFile`. */
+    readonly syncSessionFile?: SyncSessionFile;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** Adds `read_tool_output`. The loop of a report turn must keep its texts in the same store. */
     readonly toolOutputStore?: ToolOutputStore;
+    /** Where the VM of `run_script` comes from. A bundled host gives the embedded paths; see `ScriptRuntime`. */
+    readonly scriptRuntime?: ScriptRuntime;
 };
 /** 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

@@ -11,11 +11,12 @@
  * 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.
+ * roster omits those tools, and no runtime guard blocks them. No tool runs a
+ * container.
  *
- * The derivation tool is the one tool that runs a container, and it changes no
- * analysis either. It mints no run id, it registers no artifact, and it writes under
- * the directory of the session alone.
+ * A derivation of a table runs in a script (`run_script`), and it changes no
+ * analysis: it mints no run id, it registers no artifact, and it writes under the
+ * directory of the session alone.
  *
  * The definition carries no per-session value. The system prompt composes through
  * `composeSystemPrompt` with the identity part and the conversational part, the
@@ -23,16 +24,20 @@
  * across threads, and the provider cache reuses it.
  */
 import { createReadToolOutputTool } from "../tools/read-tool-output.js";
+import { reportSessionDir } from "../workspace/paths.js";
+import { createDocumentTools, createReadPdfTool } from "../tools/script/file-tools.js";
 import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
-import { createDeriveTableTool, createExaminePageTool, createListPinnedArtifactsTool, createPreviewReportTool, createRecordVersionTool, } from "../tools/report-session/index.js";
+import { createExaminePageTool, createListPinnedArtifactsTool, createPreviewReportTool, createRecordVersionTool, } from "../tools/report-session/index.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";
+import { createReportScriptTools } from "../tools/report-session/script-tools.js";
+import { createScriptScratch } from "../tools/script/scratch.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export const REPORT_SESSION_AGENT_ID = "report-session";
 /**
- * Runaway guard. A full session — orient, derive, compose each section, preview,
+ * Runaway guard. A full session — orient, compose each section, preview,
  * look, record — drives more small tool calls than a conversation turn, thus it
  * gets the headroom of the report runner (REPORT_AGENT_MAX_STEPS).
  */
@@ -50,7 +55,7 @@ export const REPORT_SESSION_PROVIDER_OPTIONS = {
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, sandboxClient, makeSessionPages, resolvePageUrl, provenance } = deps;
+    const { derivations, makeSessionPages, resolvePageUrl, provenance, syncSessionFile } = deps;
     // The seam rides into each tool that lands an act of the session, thus the composition binds it one
     // time and no tool reads a second source.
     const observation = provenance ? { provenance } : {};
@@ -65,15 +70,7 @@ export function createReportSessionAgent(deps) {
         createWorkspaceSearchTool(pool, embedding),
         createInspectRunTool(pool),
         createInspectDataProfileTool(pool),
-        // The composition surface. Each authoring tool binds to the gateway, thus
-        // two threads never share one draft.
-        authoring.add_block,
-        authoring.change_block,
-        authoring.remove_block,
-        authoring.move_block,
-        authoring.set_title,
-        authoring.read_outline,
-        authoring.read_block,
+        // The gate of the draft. The edits of the draft are script tools below.
         authoring.finish_draft,
         // The orientation source of the pinned evidence. It reads the snapshot of the
         // thread, and it resolves the workspace root per call for the header columns.
@@ -82,16 +79,6 @@ export function createReportSessionAgent(deps) {
             resolveWorkspaceRoot,
             logger,
         }),
-        // The derivation tool. It reshapes the pinned evidence into one table under the
-        // session directory, on the sandbox rails of the value tier.
-        createDeriveTableTool({
-            gateway,
-            resolveWorkspaceRoot,
-            derivations,
-            sandboxClient,
-            ...observation,
-            logger,
-        }),
         // The render-and-preview tool. It resolves the page root per call.
         createPreviewReportTool({
             gateway,
@@ -126,11 +113,38 @@ export function createReportSessionAgent(deps) {
             logger,
         }),
     ];
+    // A derivation of a table of up to the read cap runs in a script, thus it starts no container. The scripts
+    // of a session stay beside its page.
+    const scriptScratch = createScriptScratch({ resolveWorkspaceRoot, sessionDir: reportSessionDir, provenance, syncSessionFile, logger });
+    // A PDF of the report is a document that a script builds from the content of the session, not a print of the
+    // page. Its images come from the directory of the session alone, thus no unpinned file reaches it.
+    const scriptTools = [
+        // The edits of the draft. Each binds to the gateway, thus two threads never share one draft, and a script
+        // builds a section in one call. A refused edit comes back as data, thus the script reads `applied`.
+        authoring.add_block,
+        authoring.change_block,
+        authoring.remove_block,
+        authoring.move_block,
+        authoring.set_title,
+        authoring.read_outline,
+        authoring.read_block,
+        ...createReportScriptTools({ gateway, workspaceFs, resolveWorkspaceRoot, derivations, provenance, syncSessionFile, logger }),
+        createReadPdfTool({ workspaceFs, resolveWorkspaceRoot }),
+        ...createDocumentTools({
+            workspaceFs,
+            resolveWorkspaceRoot,
+            scratch: scriptScratch,
+            imageScope: (session) => (session.scope.threadId === undefined ? undefined : reportSessionDir(session.scope.threadId)),
+        }),
+    ];
     return {
         id: REPORT_SESSION_AGENT_ID,
         systemPrompt: composeSystemPrompt(reportSessionPrompt, { identity: true, conversational: true }),
         model,
         tools,
+        scriptTools,
+        scriptRuntime: deps.scriptRuntime,
+        scriptScratch,
         maxIterations: REPORT_SESSION_MAX_ITERATIONS,
         compaction: REPORT_SESSION_COMPACTION,
         providerOptions: REPORT_SESSION_PROVIDER_OPTIONS,

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

@@ -10,7 +10,7 @@
  * `allowedWritePrefix` through the host-side `WorkspaceMutator` —,
  * the workspace read tools (`read_file`, `grep`) over the shared
  * `WorkspaceFilesystem`, `inspect_data_profile` over the shared `Pool`, and the
- * bio/literature/context7/run-inspection tools its `meta.tools` allowlist names.
+ * bio/literature/context7 tools its `meta.tools` allowlist names.
  *
  * Tool resolution is a single registry lookup — every name in `meta.tools`
  * must map to a concrete `Tool`; unknown names throw at composition time
@@ -20,8 +20,8 @@ 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";
-import type { SandboxClient } from "../../sandbox/client.js";
-import type { ExtendAnalysisFarm, SandboxRef } from "../../sandbox/types.js";
+import type { BoundLease } from "../../sandbox/leases.js";
+import type { ExtendAnalysisFarm, ToolchainSource } 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";
@@ -31,9 +31,10 @@ 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";
+import type { ScriptRuntime } from "../../tools/script/run-script.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
- * library docs, run inspection, and the knowledge template. Spread into each
+ * library docs, 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.
  *
@@ -47,14 +48,13 @@ import { type KnowledgeClient, type TemplateBinding } from "../../tools/knowledg
 export declare const BASE_SANDBOX_TOOLS: readonly SandboxToolName[];
 /** Per-step coordinates the composition root threads through every mutate tool. */
 export type SandboxStepCoords = {
-    readonly sandbox: SandboxRef;
+    /** The lease of the step. `acquire_sandbox` and `release_sandbox` drive it, and each command runs on it. */
+    readonly lease: BoundLease;
     /** Absolute host root of this analysis's workspace tree (resolved at the workflow body). */
     readonly workspaceRoot: string;
     readonly analysisId: string;
     /** Absolute writable artifact directory for this step (e.g. stepWritePrefix(...)). */
     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
@@ -68,14 +68,16 @@ export type SandboxAgentDeps = EnvironmentStorePaths & {
     readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Querier;
-    readonly sandboxClient: SandboxClient;
+    /** The toolchain of the sandboxes, as the sandbox client declares it. The orient-core prompt keys on it. */
+    readonly toolchainSource: ToolchainSource;
     readonly workspaceFs: WorkspaceFilesystem;
     /** Embedding provider for in-sandbox semantic `workspace_search`. Omit to skip that tool. */
     readonly embedding?: EmbeddingProvider;
     /**
      * Step-scoped lineage collector fed by each `execute_command`'s
-     * `ExecResult.provenance` frame. Records the input/script edges post-step
-     * registration translates into provenance parents.
+     * `ExecResult.provenance` frame, and by the reads of `read_file`, `grep`, and
+     * `read_pdf`. Records the input/script edges post-step registration
+     * translates into provenance parents.
      */
     readonly lineageCollector?: LineageCollector;
     /** Model id provenance label — the provider owns the wire model. */
@@ -103,8 +105,9 @@ export type SandboxAgentDeps = EnvironmentStorePaths & {
     readonly toolOutputStore?: ToolOutputStore;
     /**
      * The farm-extension seam of the embedder. When it is bound, every
-     * sandbox agent gets the `link_packages` tool in its always-on substrate,
-     * and the package-link prompt layer appends. Without it, neither exists.
+     * sandbox agent gets the `link_packages` tool in its always-on substrate.
+     * The system prompt is the same with and without it: the descriptions of
+     * `link_packages` and `list_available_packages` carry the link rules.
      */
     readonly extendAnalysisFarm?: ExtendAnalysisFarm;
     /**
@@ -114,6 +117,8 @@ export type SandboxAgentDeps = EnvironmentStorePaths & {
      * of the open-source host and never an error.
      */
     readonly knowledge?: KnowledgeClient;
+    /** Where the VM of `run_script` comes from, for the lookups of the agent. */
+    readonly scriptRuntime?: ScriptRuntime;
 };
 /** Per-agent override for the prompt composition and tool surface. */
 export type SandboxAgentPromptOptions = {
@@ -138,7 +143,7 @@ export type SandboxAgentPromptOptions = {
  *
  * The composed `systemPrompt` is a **pure function of the agent type** — nothing
  * from `deps.step` reaches it, so two steps of one run, and two runs of one
- * analysis, send a byte-identical ~20k-char prefix that the provider's prompt
+ * analysis, send a byte-identical prefix that the provider's prompt
  * cache can actually reuse. Keep it that way: a single interpolated id or path
  * makes every step's prefix unique again, and each step pays a full cache write
  * and reads nothing back. Per-step values belong in the step's briefing (its

package/dist/agents/sandbox/shared.js

@@ -10,21 +10,20 @@
  * `allowedWritePrefix` through the host-side `WorkspaceMutator` —,
  * the workspace read tools (`read_file`, `grep`) over the shared
  * `WorkspaceFilesystem`, `inspect_data_profile` over the shared `Pool`, and the
- * bio/literature/context7/run-inspection tools its `meta.tools` allowlist names.
+ * bio/literature/context7 tools its `meta.tools` allowlist names.
  *
  * Tool resolution is a single registry lookup — every name in `meta.tools`
  * 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 { createEditIntentStore } from "../../state/edit-intents.js";
-import { sandboxOrientCorePromptFor, sandboxPackageLinkPrompt, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
+import { createWorkspaceReadLineage } from "../../provenance/workspace-reads.js";
+import { sandboxOrientCorePromptFor, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
 import { composeSystemPrompt } from "../system-prompt.js";
 // Sandbox-environment introspection, plus the farm-extension seam face.
 import { createLinkPackagesTool, createListAvailablePackagesTool, createListAvailableRefsTool } from "../../tools/sandbox/index.js";
 // Context7 docs (pure leaves).
 import { queryDocsTool, resolveLibraryIdTool } from "../../tools/research/context7-docs.js";
-// Run-inspection (dependency-bearing).
-import { createInspectRunTool } from "../../tools/research/inspect-run.js";
 // Data-profile retrieval (dependency-bearing) — always-on, see `createSandboxAgent`.
 import { createInspectDataProfileTool } from "../../tools/research/inspect-data-profile.js";
 // Bio leaf tools.
@@ -38,15 +37,17 @@ import { createEditFileTool, createExecuteCommandTool, createWorkspaceMutator, c
 // Skills (declared per agent via meta.skills).
 import { createSkillTools } from "../../tools/sandbox/skills.js";
 import { createReadToolOutputTool } from "../../tools/read-tool-output.js";
+import { createAcquireSandboxTool, createReleaseSandboxTool } from "../../tools/sandbox/lease-tools.js";
 import { createReportBlockerTool } from "../../tools/sandbox/report-blocker.js";
 import { createSubmitFileMetadataTool } from "../../tools/sandbox/submit-file-metadata.js";
 import { toSandboxPath } from "../../workspace/paths.js";
 import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
 import { createResolveCitationTool } from "../../tools/research/resolve-citation.js";
 import { createKnowledgeTemplateTool } from "../../tools/knowledge/index.js";
+import { createReadPdfTool } from "../../tools/script/file-tools.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
- * library docs, run inspection, and the knowledge template. Spread into each
+ * library docs, 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.
  *
@@ -62,9 +63,13 @@ export const BASE_SANDBOX_TOOLS = [
     "listAvailableRefs",
     "resolveLibraryId",
     "queryDocs",
-    "inspectRun",
     "knowledgeTemplate",
 ];
+/**
+ * The tools of the allowlist that stay direct: the environment of the step. Each other tool of the allowlist is a
+ * lookup of an outside source, and it runs in `run_script`.
+ */
+const DIRECT_ALLOWLIST_TOOLS = new Set(["list_available_packages", "list_available_refs", "scan_inputs", "knowledge_template"]);
 /**
  * Resolve `meta.tools` into the bio/research tools record. The workspace
  * read/mutate tools and `inspect_data_profile` are added by `createSandboxAgent`
@@ -89,13 +94,10 @@ function resolveSandboxTools(deps, tools, mutator) {
         scanInputs: createScanInputsTool({
             workspaceFs: deps.workspaceFs,
             analysisId: deps.step.analysisId,
-            sandboxClient: deps.sandboxClient,
-            sandbox: deps.step.sandbox,
-            deadlineMs: deps.step.deadlineMs,
+            lease: deps.step.lease,
         }),
         resolveLibraryId: resolveLibraryIdTool,
         queryDocs: queryDocsTool,
-        inspectRun: createInspectRunTool(deps.pool),
         pubmed: ncbi.pubmed,
         resolve_citation: deps.citationResolver === undefined ? undefined : createResolveCitationTool(deps.citationResolver),
         searchGene: searchGeneTool,
@@ -146,8 +148,8 @@ function resolveSandboxTools(deps, tools, mutator) {
 /** Build the workspace mutate + read tools every sandbox agent receives. In
  *  `readOnly` mode the write_file/edit_file pair is omitted; execute_command
  *  and the read tools stay. */
-function buildWorkspaceTools(deps, readOnly) {
-    const { step, sandboxClient, workspaceFs, pool, embedding, lineageCollector } = deps;
+function buildWorkspaceTools(deps, readOnly, readLineage) {
+    const { step, workspaceFs, pool, embedding, lineageCollector } = deps;
     // The agent's writable working directory: relative paths resolve here, and
     // writes are confined here. `allowedWritePrefix` is its host path; the
     // in-sandbox path (the `execute_command` default cwd, see the harness-workspace-tools spec) is the same
@@ -170,10 +172,10 @@ function buildWorkspaceTools(deps, readOnly) {
         ]
         : [];
     const tools = [
+        createAcquireSandboxTool(step.lease),
+        createReleaseSandboxTool(step.lease),
         createExecuteCommandTool({
-            sandboxClient,
-            sandbox: step.sandbox,
-            deadlineMs: step.deadlineMs,
+            lease: step.lease,
             defaultCwd: sandboxWorkingDir,
             lineageCollector,
             mountRoot: `/${step.analysisId}`,
@@ -181,10 +183,10 @@ function buildWorkspaceTools(deps, readOnly) {
             mutator,
         }),
         ...mutateTools,
-        createReadFileTool(workspaceFs, hostWorkingDir),
+        createReadFileTool(workspaceFs, hostWorkingDir, readLineage),
         createListFilesTool(workspaceFs, hostWorkingDir),
         createFileStatTool(workspaceFs, hostWorkingDir),
-        createGrepTool(workspaceFs, hostWorkingDir),
+        createGrepTool(workspaceFs, hostWorkingDir, readLineage),
         ...(embedding ? [createWorkspaceSearchTool(pool, embedding)] : []),
     ];
     return { tools, mutator };
@@ -200,7 +202,7 @@ function buildWorkspaceTools(deps, readOnly) {
  *
  * The composed `systemPrompt` is a **pure function of the agent type** — nothing
  * from `deps.step` reaches it, so two steps of one run, and two runs of one
- * analysis, send a byte-identical ~20k-char prefix that the provider's prompt
+ * analysis, send a byte-identical prefix that the provider's prompt
  * cache can actually reuse. Keep it that way: a single interpolated id or path
  * makes every step's prefix unique again, and each step pays a full cache write
  * and reads nothing back. Per-step values belong in the step's briefing (its
@@ -210,20 +212,27 @@ function buildWorkspaceTools(deps, readOnly) {
 export function createSandboxAgent(deps, meta, body, opts = {}) {
     const appendStandards = opts.appendAnalysisStepStandards ?? true;
     // The layer order is fixed by the harness-sandbox-agents spec: the agent
-    // body, the orient core keyed on the toolchain of the sandbox client, the
-    // package-link layer only when the seam is bound, then the step standards.
+    // body, the orient core keyed on the toolchain of the sandbox client, then
+    // the step standards.
     // The client is the one declaration: the environment it provisions and the
     // text that describes it come from the same value, thus a bag cannot
     // describe a toolchain the sandbox does not have.
-    const sandboxLayer = [
-        sandboxOrientCorePromptFor(deps.sandboxClient.toolchainSource),
-        ...(deps.extendAnalysisFarm ? [sandboxPackageLinkPrompt] : []),
-        ...(appendStandards ? [sandboxAnalysisStepStandardsPrompt] : []),
-    ];
+    const sandboxLayer = [sandboxOrientCorePromptFor(deps.toolchainSource), ...(appendStandards ? [sandboxAnalysisStepStandardsPrompt] : [])];
     const agentBody = [body, ...sandboxLayer].map((s) => s.trim()).join("\n\n");
     const systemPrompt = composeSystemPrompt(agentBody);
     const skillTools = deps.skillsDir ? Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: meta.skills })) : [];
-    const workspace = buildWorkspaceTools(deps, opts.readOnly ?? false);
+    // The working directory is the one of the read tools, thus a relative path resolves to the same file.
+    const readLineage = deps.lineageCollector
+        ? createWorkspaceReadLineage({
+            collector: deps.lineageCollector,
+            workspaceRoot: deps.step.workspaceRoot,
+            analysisId: deps.step.analysisId,
+            workingDir: deps.step.allowedWritePrefix,
+            logger: deps.logger,
+        })
+        : undefined;
+    const workspace = buildWorkspaceTools(deps, opts.readOnly ?? false, readLineage);
+    const allowlisted = resolveSandboxTools(deps, meta.tools, workspace.mutator);
     const tools = [
         ...workspace.tools,
         ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
@@ -238,7 +247,7 @@ export function createSandboxAgent(deps, meta, body, opts = {}) {
         // seam (the harness-sandbox-agents spec).
         ...(deps.extendAnalysisFarm ? [createLinkPackagesTool({ extendAnalysisFarm: deps.extendAnalysisFarm, analysisId: deps.step.analysisId })] : []),
         ...skillTools,
-        ...resolveSandboxTools(deps, meta.tools, workspace.mutator),
+        ...allowlisted.filter((tool) => DIRECT_ALLOWLIST_TOOLS.has(tool.id)),
         ...(deps.reportsBlocker === true ? [createReportBlockerTool()] : []),
         ...(deps.fileMetadata ? [createSubmitFileMetadataTool(deps.fileMetadata)] : []),
     ];
@@ -247,6 +256,12 @@ export function createSandboxAgent(deps, meta, body, opts = {}) {
         systemPrompt,
         model: deps.model,
         tools,
+        // A paper of the analysis is a PDF, and each step can need it, thus each agent reads PDFs in a script.
+        scriptTools: [
+            ...allowlisted.filter((tool) => !DIRECT_ALLOWLIST_TOOLS.has(tool.id)),
+            createReadPdfTool({ workspaceFs: deps.workspaceFs, resolveWorkspaceRoot: () => Promise.resolve(deps.step.workspaceRoot), lineage: readLineage }),
+        ],
+        scriptRuntime: deps.scriptRuntime,
         maxIterations: meta.defaultMaxSteps ?? SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS,
     };
 }