@inflexa-ai/harness 0.31.1 → 0.33.0

package/dist/tools/report-authoring/authoring-tools.js

@@ -19,7 +19,9 @@
 import { err, ok } from "neverthrow";
 import { basename } from "node:path";
 import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
@@ -299,6 +301,23 @@ function addedSubject(kind, block) {
 function holderIdOf(document, blockId) {
     return locate(document, blockId)?.parent?.id;
 }
+/**
+ * The event of one block act, or `undefined` when the document holds no block of that id.
+ *
+ * The kind rides beside the id, thus a reader of the record sees what the act touched and it needs no
+ * document of its own. The kind comes out of the document that holds the block after the act: the next
+ * document for an add, a change, and a move, and the previous one for a remove.
+ *
+ * A lookup of a landed operation always finds its block. The absent arm keeps the read total, and it drops
+ * the event rather than state a kind that no block carries.
+ */
+function blockActOf(type, scope, document, blockId) {
+    const kind = locate(document, blockId)?.block.kind;
+    if (kind === undefined) {
+        return undefined;
+    }
+    return { type, analysisId: scope.analysisId, threadId: scope.threadId, blockId, blockKind: kind };
+}
 /** Read the child order of one container out of a document. */
 function containerIn(document, parentId) {
     if (parentId === undefined) {
@@ -326,8 +345,12 @@ const AUTHORING_EXECUTION_MODE = "inline";
  * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
  * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
  * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
+ *
+ * A landed mutation emits one observation. The emit sits after the persist, thus a refused operation and a
+ * failed persist each emit nothing.
  */
-export function createReportAuthoringTools(gateway) {
+export function createReportAuthoringTools(gateway, deps = {}) {
+    const observe = bindSessionEmit(deps.provenance, (deps.logger ?? createNoopLogger()).named("report-authoring"));
     /**
      * Resolve the thread of the call, and load its state.
      *
@@ -346,8 +369,13 @@ export function createReportAuthoringTools(gateway) {
      *
      * The persist is a compare-and-swap against the token that the load read. A concurrent turn that landed
      * first turns the persist into a conflict, and the tool refuses with `stale-state`.
+     *
+     * `event` is the observation of the operation, and it emits after the persist landed. Thus one site owns
+     * the rule, and a refusal, a conflict, and a persist fault each emit nothing. It reads the two documents
+     * for the same reason that `holders` does: a removed block sits in the first alone, and an added block
+     * sits in the second alone. A caller that cannot name the block of its own operation gives no event.
      */
-    const land = async (threadId, token, previous, result, holders) => {
+    const land = async (threadId, token, previous, result, holders, event) => {
         if (result.isErr()) {
             return { applied: false, refusal: result.error };
         }
@@ -362,6 +390,10 @@ export function createReportAuthoringTools(gateway) {
         if (persisted.outcome === "failed") {
             return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
         }
+        const observed = event(previous, next);
+        if (observed !== undefined) {
+            observe(observed);
+        }
         // A move inside one container names the same holder two times.
         const unique = [...new Set(holders(previous, next))];
         return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
@@ -390,14 +422,17 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
             const block = decodeBlockPayload(input.block);
             const addedId = readId(block);
-            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)]));
+            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)], 
+            // The grammar requires an id on the payload, thus a landed add always names one. A
+            // payload with no id reaches the core, which refuses it, and no event is due.
+            (_previous, next) => (addedId === undefined ? undefined : blockActOf("add-block", { analysisId, threadId }, next, addedId))));
         },
     });
     const change_block = defineTool({
@@ -413,14 +448,15 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const operation = toChangeOperation(input);
             if (operation.isErr()) {
                 return ok(refuse(operation.error));
             }
-            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [
-                holderIdOf(next, input.targetId),
-            ]));
+            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [holderIdOf(next, input.targetId)], 
+            // A change is permitted to change the kind, thus the event states the kind that the
+            // document holds after the act.
+            (_previous, next) => blockActOf("change-block", { analysisId, threadId }, next, input.targetId)));
         },
     });
     const remove_block = defineTool({
@@ -434,10 +470,11 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [
-                holderIdOf(previous, input.targetId),
-            ]));
+            const { threadId, analysisId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [holderIdOf(previous, input.targetId)], 
+            // The next document holds no removed block, thus the event states the kind that the
+            // previous one carried.
+            (previous) => blockActOf("remove-block", { analysisId, threadId }, previous, input.targetId)));
         },
     });
     const move_block = defineTool({
@@ -452,12 +489,12 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
+            const { threadId, analysisId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
-            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)]));
+            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)], (_previous, next) => blockActOf("move-block", { analysisId, threadId }, next, input.targetId)));
         },
     });
     const set_title = defineTool({
@@ -473,8 +510,13 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok(refuse(opened.error));
             }
-            const { threadId, state, token } = opened.value;
-            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => []));
+            const { threadId, analysisId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => [], () => ({
+                type: "set-title",
+                analysisId,
+                threadId,
+                title: input.title,
+            })));
         },
     });
     const read_outline = defineTool({

package/dist/tools/report-session/derive-table.d.ts

@@ -42,6 +42,7 @@ import type { DerivationSource, ReportSessionStateStore } from "../../state/repo
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 /** The input of one derivation: the script, the declared pinned inputs, and the name of the output file. */
 declare const deriveTableInput: z.ZodObject<{
     script: z.ZodString;
@@ -114,6 +115,8 @@ export interface DeriveTableToolDeps {
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     readonly runDerivation?: DeriveTableRunner;
     readonly runAuthorizer?: RunAuthorizer;
+    /** The provenance seam; an unbound session emit emits nothing and the derivation runs the same. */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /** The synthetic run id and step id of one derivation. Both are constants, and neither names a run row. */

package/dist/tools/report-session/derive-table.js

@@ -45,6 +45,7 @@ import { generateExecutionId } from "../../sandbox/execution-id.js";
 import { isSafeId, reportSessionDerivedDir, toSandboxPath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 import { readHeaderColumns } from "./list-artifacts.js";
 /** The input of one derivation: the script, the declared pinned inputs, and the name of the output file. */
 const deriveTableInput = z.object({
@@ -128,6 +129,7 @@ export function describeExecFailure(result) {
  */
 export function createDeriveTableTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table");
+    const observe = bindSessionEmit(deps.provenance, logger);
     const { runDerivation, runAuthorizer } = deps;
     return defineTool({
         id: "derive_table",
@@ -252,6 +254,19 @@ export function createDeriveTableTool(deps) {
                     outputName: input.output,
                     logger,
                 });
+                // The record of the derivation lands before this point, thus the event states a table that
+                // the session already holds as evidence. Each other arm derived nothing.
+                if (result.outcome === "derived") {
+                    observe({
+                        type: "run-derivation",
+                        analysisId,
+                        threadId,
+                        outputPath: result.path,
+                        outputHash: result.hash,
+                        scriptHash: result.scriptHash,
+                        sources: result.sources,
+                    });
+                }
                 return ok(result);
             }
             finally {

package/dist/tools/report-session/preview-report.d.ts

@@ -7,10 +7,12 @@
  * and renders the page.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
- * them beside the figures. It also writes the script of each derivation that the document references, from
- * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
- * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
- * wrote stays, and each other file goes.
+ * them beside the figures. The tool asks the optional provenance source for the frozen document of the
+ * analysis first, and the renderer turns the opaque text into data assets of the same kind. It also writes
+ * the script of each derivation that the document references, from the text of the durable record. The
+ * shipped libraries and fonts stage under `assets/deps/`, and each report-side file at the root of
+ * `assets/`. The stage is authoritative over that root: what this preview wrote stays, and each other file
+ * goes.
  *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
@@ -45,6 +47,7 @@ import { type BridgeMismatch } from "../../report-render/value-bridge.js";
 import type { RenderProblem } from "../../report-render/types.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type MakeSessionPagePublisher } from "./session-page-publisher.js";
 /** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
 declare const previewReportInput: z.ZodObject<{}, z.core.$strip>;
@@ -135,6 +138,12 @@ export interface PreviewReportToolDeps {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly resolvePageAsset?: ResolvePageAsset;
     readonly makeSessionPages?: MakeSessionPagePublisher;
+    /**
+     * The provenance seam. An unbound session emit emits nothing and the render runs the same. An unbound
+     * document read, and a read that holds no document for the analysis, both give absence, and the page
+     * then carries no provenance asset.
+     */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

package/dist/tools/report-session/preview-report.js

@@ -7,10 +7,12 @@
  * and renders the page.
  *
  * The renderer writes no file. It gives the page and the data asset of each table, and this tool stages
- * them beside the figures. It also writes the script of each derivation that the document references, from
- * the text of the durable record. The shipped libraries and fonts stage under `assets/deps/`, and each
- * report-side file at the root of `assets/`. The stage is authoritative over that root: what this preview
- * wrote stays, and each other file goes.
+ * them beside the figures. The tool asks the optional provenance source for the frozen document of the
+ * analysis first, and the renderer turns the opaque text into data assets of the same kind. It also writes
+ * the script of each derivation that the document references, from the text of the durable record. The
+ * shipped libraries and fonts stage under `assets/deps/`, and each report-side file at the root of
+ * `assets/`. The stage is authoritative over that root: what this preview wrote stays, and each other file
+ * goes.
  *
  * The page and its staged assets land in `report-sessions/{threadId}/` under the workspace root. That
  * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
@@ -55,6 +57,7 @@ import { ASSETS_DIR, DEPS_DIR, derivationScriptName, PAGE_ASSETS, stagedSource,
 import { renderReportPage } from "../../report-render/render.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindReadExport, bindSessionEmit } from "../../provenance/seam.js";
 import { describeSessionPageMintFailure } from "./session-page-publisher.js";
 /** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
 const previewReportInput = z.object({});
@@ -383,6 +386,8 @@ async function mintAccess(makeSessionPages, analysisId, threadId, auth, logger)
  */
 export function createPreviewReportTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("preview-report");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    const readProvenance = bindReadExport(deps.provenance, logger);
     const resolvePageAsset = deps.resolvePageAsset ?? resolvePageAssetFromInstallation;
     return defineTool({
         id: "preview_report",
@@ -438,7 +443,15 @@ export function createPreviewReportTool(deps) {
             // relative links of its entry, thus the renderer states them and it stages nothing.
             const used = referencedDerivations(document, derivations);
             const sessionDir = reportSessionDir(threadId);
-            const rendered = renderReportPage(document, bridged.value, snapshot.citationRecords, used.map((record) => chainOf(record, sessionDir)));
+            // The provenance is the frozen document of the analysis. It rides the render as opaque text, thus
+            // the renderer moves it into a data asset and no part of this path reads a field of it. Absence
+            // gives a page with no provenance asset, and each other part of the render is unchanged.
+            const provenance = await readProvenance(analysisId);
+            const rendered = renderReportPage(document, bridged.value, {
+                records: snapshot.citationRecords,
+                derivations: used.map((record) => chainOf(record, sessionDir)),
+                provenance,
+            });
             if (rendered.isErr()) {
                 return ok({ outcome: "render-problems", problems: rendered.error });
             }
@@ -471,7 +484,8 @@ export function createPreviewReportTool(deps) {
             // The page shows the draft that the finish read. The stamp records that draft, thus the eyes
             // copy this hash and the record compares against it. A failed stamp is a transient store fault,
             // and the page stays on disk. The agent runs the preview again to stamp the marker.
-            const stamped = await deps.gateway.stampRendered(threadId, computeDraftHash(draft));
+            const renderedHash = computeDraftHash(draft);
+            const stamped = await deps.gateway.stampRendered(threadId, renderedHash);
             if (stamped.outcome !== "stamped") {
                 const detail = stamped.outcome === "failed" ? stamped.detail : "the session state row is absent";
                 logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
@@ -483,6 +497,9 @@ export function createPreviewReportTool(deps) {
                 type: "data-report-rendered",
                 data: { id: randomUUID(), renderedAt: new Date().toISOString(), title: document.title },
             });
+            // The event rides the rendered arm alone, the same as the part above. The hash is the hash of
+            // the draft that the page shows, thus a consumer ties the page to the document that made it.
+            observe({ type: "preview", analysisId, threadId, pagePath: written.value, documentHash: renderedHash });
             const access = await mintAccess(deps.makeSessionPages, analysisId, threadId, ctx.session.auth, logger);
             return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}) });
         },

package/dist/tools/report-session/record-version.d.ts

@@ -39,6 +39,7 @@ import type { ReportVersionStore } from "../../state/report-versions.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
 declare const recordVersionInput: z.ZodObject<{}, z.core.$strip>;
 export type RecordVersionInput = z.infer<typeof recordVersionInput>;
@@ -101,6 +102,8 @@ export interface RecordVersionToolDeps {
         analysisId: string;
         auth: AuthContext;
     }) => ReferenceResolver;
+    /** The provenance seam; an unbound session emit emits nothing and the record runs the same. */
+    readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
 }
 /**

package/dist/tools/report-session/record-version.js

@@ -42,6 +42,7 @@ import { validateReport } from "../../report-model/validate.js";
 import { reportSessionDerivedDir, resolveWorkspacePath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
 const recordVersionInput = z.object({});
 /** A short account of a record refusal, for the detail of a transient failure. */
@@ -122,6 +123,7 @@ async function pruneUnusedDerivations(args) {
  */
 export function createRecordVersionTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("record-report-version");
+    const observe = bindSessionEmit(deps.provenance, logger);
     return defineTool({
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
@@ -203,9 +205,11 @@ export function createRecordVersionTool(deps) {
                 parentSeq: thread.value.parentSeq,
             });
             if (recorded.isOk()) {
-                // The version stands from here. The prune reclaims the bytes of each derivation that the
-                // recorded document ignores, and it decides nothing about the outcome. It runs on each
-                // record, thus an output that an amend unbound goes at the next record.
+                // The version stands from here, thus the event states a version that a reader can open.
+                observe({ type: "record-version", analysisId, threadId, versionId: recorded.value.versionId, replaced: recorded.value.outcome === "replaced" });
+                // The prune reclaims the bytes of each derivation that the recorded document ignores, and it
+                // decides nothing about the outcome. It runs on each record, thus an output that an amend
+                // unbound goes at the next record.
                 await pruneUnusedDerivations({
                     resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
                     analysisId,

package/dist/tools/research/generate-plan.js

@@ -677,7 +677,13 @@ function buildPlannerSearchTools(deps) {
         // collection of the reference store, or one package name that a step is
         // about to import.
         createListAvailableRefsTool(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath }),
-        createListAvailablePackagesTool(deps.packagesFile === undefined ? {} : { packagesFile: deps.packagesFile }),
+        // The planner is a conversation surface, thus the pool-scope reader binds
+        // when the embedder gives one, and the answer names what the store HOLDS.
+        createListAvailablePackagesTool({
+            ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+            ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+            ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+        }),
     ];
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
@@ -804,7 +810,11 @@ export function createGeneratePlanTool(deps) {
             // not optional planner lookups. Read both inventories host-side before
             // the loop and put their rendered content in the planner's seed.
             const listAvailableRefs = createListAvailableRefsTool(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath });
-            const listAvailablePackages = createListAvailablePackagesTool(deps.packagesFile === undefined ? {} : { packagesFile: deps.packagesFile });
+            const listAvailablePackages = createListAvailablePackagesTool({
+                ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+                ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+                ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+            });
             // A path-separator query matches every reference path and selects the
             // tool's recursive leaf scan, so the seed contains usable file paths,
             // not only top-level directory summaries.

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

@@ -2,6 +2,7 @@
  * Sandbox barrel — sandbox-environment introspection (available lib-store
  * packages and reference datasets). Consumed by sandbox agents.
  */
+export * from "./link-packages.js";
 export * from "./list-available-packages.js";
 export * from "./list-available-refs.js";
 export * from "./report-blocker.js";

package/dist/tools/sandbox/index.js

@@ -2,6 +2,7 @@
  * Sandbox barrel — sandbox-environment introspection (available lib-store
  * packages and reference datasets). Consumed by sandbox agents.
  */
+export * from "./link-packages.js";
 export * from "./list-available-packages.js";
 export * from "./list-available-refs.js";
 export * from "./report-blocker.js";

package/dist/tools/sandbox/link-packages.d.ts

@@ -0,0 +1,27 @@
+/**
+ * link_packages — extend the farm of the analysis with host-staged packages.
+ *
+ * The tool is the agent face of the `ExtendAnalysisFarm` seam. It exists only
+ * when the embedder binds the seam (the harness-sandbox-agents spec): the
+ * composition adds it to the always-on substrate, and no `meta.tools`
+ * allowlist names it. The realization of the embedder links what the host
+ * staged — the tool never installs, downloads, or acquires anything. A link
+ * is live in a container that already runs, because the farm rides a bind
+ * mount.
+ */
+import type { ExtendAnalysisFarm, PackageRequestOutcome } from "../../sandbox/types.js";
+export interface LinkPackagesDeps {
+    readonly extendAnalysisFarm: ExtendAnalysisFarm;
+    readonly analysisId: string;
+}
+/** The tool result: one outcome per requested package, index-aligned. */
+export interface LinkPackagesResult {
+    readonly outcomes: readonly PackageRequestOutcome[];
+}
+export declare function createLinkPackagesTool(deps: LinkPackagesDeps): import("../define-tool.js").Tool<{
+    packages: {
+        name: string;
+        version?: string | undefined;
+        ecosystem?: "r" | "python" | undefined;
+    }[];
+}, LinkPackagesResult>;

package/dist/tools/sandbox/link-packages.js

@@ -0,0 +1,52 @@
+/**
+ * link_packages — extend the farm of the analysis with host-staged packages.
+ *
+ * The tool is the agent face of the `ExtendAnalysisFarm` seam. It exists only
+ * when the embedder binds the seam (the harness-sandbox-agents spec): the
+ * composition adds it to the always-on substrate, and no `meta.tools`
+ * allowlist names it. The realization of the embedder links what the host
+ * staged — the tool never installs, downloads, or acquires anything. A link
+ * is live in a container that already runs, because the farm rides a bind
+ * mount.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+export function createLinkPackagesTool(deps) {
+    return defineTool({
+        id: "link_packages",
+        description: "Link host-staged packages into the farm of this analysis, so an import that failed works without a restart. " +
+            "This tool links what the host already staged — it NEVER installs, downloads, or acquires anything. " +
+            "Pass each module name verbatim, exactly as the import names it. " +
+            "One outcome comes back per request: `linked` (the pool held it, and it is importable now), " +
+            "`present` (the farm held it already), " +
+            "`absent` (the pool does not hold it — a real answer, and `acquisitionPossible` states whether the host can acquire that ecosystem; report the package as missing, do not retry), " +
+            "`collision` (the request resolves to two store directories — terminal for that package; the `detail` names the two pins and the packages that need each; report it and continue without it), " +
+            "or `unavailable` (the link pass itself could not answer — the `reason` says why; it says nothing about the package's presence, so report the reason and do not re-request packages).",
+        inputSchema: z.object({
+            packages: z
+                .array(z.object({
+                name: z.string().min(1).describe("The module or package name, verbatim."),
+                version: z.string().optional().describe("One exact version, when the requirement pins one."),
+                ecosystem: z.enum(["python", "r"]).optional().describe("The ecosystem, when the bare name is ambiguous."),
+            }))
+                .min(1)
+                .max(50)
+                .describe("The packages to link into the farm."),
+        }),
+        describeCall: ({ packages }) => packages.map((p) => p.name).join(", "),
+        execute: async (input) => {
+            // A realization throw reads as `unavailable` per request. The loop
+            // would render the throw as a raw tool error, and a raw driver
+            // message teaches the agent nothing that `reason` does not.
+            try {
+                const outcomes = await deps.extendAnalysisFarm(deps.analysisId, input.packages);
+                return ok({ outcomes });
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                return ok({ outcomes: input.packages.map((request) => ({ kind: "unavailable", name: request.name, reason })) });
+            }
+        },
+    });
+}

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -1,40 +1,48 @@
 /**
- * listAvailablePackages — query the R/Python/CLI/Node packages available in the
- * sandbox.
+ * listAvailablePackages — query the R/Python/CLI/Node packages of the
+ * environment, from the inventory source the embedder binds.
  *
- * The data source is the store's `packages.txt`, assembled by the library-store
- * build (see the lib-store-build spec) and read from wherever the HOST can see
- * it — the container path when the host mounts the same store, an injected path
- * when it does not. Its shape is fixed by the
- * producers (`scripts/lib-store-common.sh`, `images/sandbox-python/inflexa-libs-refresh`):
- * two `#` advisory lines, then one `## <Section>` heading per language track
- * followed by that track's packages as a single comma-separated line.
+ * Two sources exist, one per vantage. A SANDBOX agent reads the
+ * `inflexa.lock` of the mounted farm — what a step can import right now —
+ * from wherever the HOST can see it: the farm container path when the host
+ * mounts the same farm, an injected path when it does not. A CONVERSATION or
+ * planning surface reads the pool-scope inventory (`readPoolInventory`) —
+ * everything the store holds, whether or not a farm links it yet — because
+ * the ask flow marks the packages the POOL does not hold, and the farm of a
+ * new analysis is empty. The baked image inventory fragment
+ * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
+ * report when the host can read one. The fragment keeps the section format:
  *
- *     # Available packages in the sandbox environment.
- *     # Do NOT attempt to install packages — ...
+ *     ## System tools (CLI)
+ *     samtools, bcftools, ...
  *
- *     ## R (CRAN)
- *     Seurat, dplyr, ggplot2, ...
- *
- *     ## Python (pip)
- *     anndata, scanpy, ...
- *
- * The file carries **names only — there are no version strings in it**, so this
- * tool reports presence and language track and cannot report a version.
+ * Each entry renders as `name==version` where the source pins a version, and
+ * a targeted `names` lookup also carries the store directory and the full
+ * content hash where the source records them. A full listing carries no
+ * hashes — a thousand rows of sha256 would bury the signal.
  */
-import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
-/** One language track of the store, in `packages.txt` section order. */
-export interface Section {
-    /** The section heading verbatim, e.g. `R (CRAN)`, `Python (pip)`. */
-    readonly title: string;
-    readonly packages: readonly string[];
-}
-/** One `names` lookup: present + canonical spelling + track, or absent. */
+import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
+import { type FarmLock } from "../../sandbox/farm.js";
+/**
+ * Group the lock packages into sections, one per track, in a stable order:
+ * the known tracks first, then an unknown track at its first occurrence.
+ * Each entry keeps the lock's version, store directory, and hash, so the
+ * targeted `names` path can report the exact store identity.
+ */
+export declare function lockSections(lock: FarmLock): Section[];
+/** One package entry of a section, with the store identity where the source records it. */
+export type SectionPackage = PoolInventoryPackage;
+/** One language track of the store, in `packages.txt` section order. The seam shape and the render shape are one. */
+export type Section = PoolInventorySection;
+/** One `names` lookup: present + canonical spelling + track + store identity, or absent. */
 export type CheckedPackage = {
     readonly requested: string;
     readonly present: true;
     readonly name: string;
     readonly section: string;
+    readonly version?: string;
+    readonly storeDir?: string;
+    readonly hash?: string;
 } | {
     readonly requested: string;
     readonly present: false;
@@ -76,11 +84,23 @@ export interface PackagesQuery {
  * is only the file read plus this call.
  */
 export declare function queryPackages(sections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
-export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "packagesFile">;
-/** Create the package inventory over a host-readable `packages.txt`. */
+export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> & {
+    /**
+     * True when the composition also attaches the `link_packages` tool. The
+     * framing sentence must not close the world on the farm then: a package
+     * absent from the farm lock can still link in from the pool.
+     */
+    readonly linkToolPresent?: boolean;
+};
+/**
+ * Create the package inventory over the bound source: the pool-scope reader
+ * when the embedder binds one (a conversation or planning surface), the
+ * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
+ * fragment merges into either report.
+ */
 export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
     names?: string[] | undefined;
     query?: string | undefined;
-    language?: "r" | "python" | "cli" | "node" | undefined;
+    language?: "r" | "python" | "node" | "cli" | undefined;
     limit?: number | undefined;
 }, PackagesResult>;