@inflexa-ai/harness 0.31.1 → 0.33.0

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

@@ -29,12 +29,14 @@ import type { AcquireEyes } from "../lib/eyes.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
+import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type BioToolKeys } from "../tools/bio/keys.js";
 import type { 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 { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
@@ -111,6 +113,12 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * at a page reads that same answer.
      */
     readonly eyes?: AcquireEyes;
+    /**
+     * The provenance seam. `start_report_session` hands it to its spawn, which
+     * emits the creation of the session at the moment that the child lands. No
+     * other tool of this roster reads it.
+     */
+    readonly provenance?: ProvenanceSeam;
     /**
      * Host resource policy — per-step ceilings + machine budget. `generate_plan`
      * states the ceilings to the planner and validates against them;
@@ -125,6 +133,13 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * built-in tool.
      */
     readonly hostTools?: readonly Tool[];
+    /**
+     * The farm-extension seam of the embedder. When it is bound,
+     * `execute_analysis` links the packages of the plan into the farm of the
+     * analysis before the launch, and a pool miss refuses the launch. Without
+     * it, the link pass returns at once.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
 }
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export declare function createConversationAgent(deps: ConversationAgentDeps): AgentDefinition;

package/dist/agents/conversation-agent.js

@@ -42,7 +42,7 @@ export const CONVERSATION_AGENT_ID = "conversation-agent";
 const CONVERSATION_MAX_ITERATIONS = 200;
 /** 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, packagesFile, usageRecorder, citationResolver, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, citationResolver, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
@@ -86,10 +86,16 @@ export function createConversationAgent(deps) {
         // blind is how a user gets asked to download something already installed, or
         // told nothing is missing when it is; this is the only tool that can tell.
         createListAvailableRefsTool({ ...(refStorePath ? { refStorePath } : {}) }),
-        // What is importable inside a sandbox. Reads the same manifest a sandbox agent
-        // reads, host-side — so "is scanpy available?" is a manifest lookup here rather
-        // than launching analysis computation to run one import.
-        createListAvailablePackagesTool({ ...(packagesFile ? { packagesFile } : {}) }),
+        // What the STORE holds, pool-scope where the embedder binds the reader:
+        // the ask flow of this agent marks the packages the pool does not hold,
+        // and the farm of a new analysis is empty — a farm view here would read
+        // every pool package as absent. The farm-lock fallback keeps a host
+        // with no pool reader on the old answer.
+        createListAvailablePackagesTool({
+            ...(farmLockFile ? { farmLockFile } : {}),
+            ...(imagePackagesFile ? { imagePackagesFile } : {}),
+            ...(readPoolInventory ? { readPoolInventory } : {}),
+        }),
         // Execution.
         createInspectRunTool(pool),
         // The dataset's own record. No file backs it — the DB row is the only copy.
@@ -101,7 +107,9 @@ export function createConversationAgent(deps) {
             usageRecorder,
             bioKeys,
             ...(refStorePath ? { refStorePath } : {}),
-            ...(packagesFile ? { packagesFile } : {}),
+            ...(farmLockFile ? { farmLockFile } : {}),
+            ...(imagePackagesFile ? { imagePackagesFile } : {}),
+            ...(readPoolInventory ? { readPoolInventory } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         createExecuteAnalysisTool({
@@ -112,6 +120,7 @@ export function createConversationAgent(deps) {
             resourcePolicy,
             utilityProvider,
             utilityModel,
+            ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         // The one report path. The tool starts a report thread as a child of the
@@ -122,6 +131,7 @@ export function createConversationAgent(deps) {
             chrome,
             anchorSession: deps.anchorReportSession,
             ...(deps.eyes ? { eyes: deps.eyes } : {}),
+            ...(deps.provenance ? { provenance: deps.provenance } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         // Display.

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

@@ -38,6 +38,7 @@ import type { ThreadStore } from "../memory/thread-store.js";
 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 MakeSessionPagePublisher, type ResolvePageAsset, type ResolvePageUrl } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
@@ -114,6 +115,14 @@ export interface ReportSessionAgentDeps {
      * tool navigates through a `file://` URL of the page path.
      */
     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
+     * 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;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

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

@@ -39,8 +39,11 @@ const REPORT_SESSION_MAX_ITERATIONS = 200;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl } = deps;
-    const authoring = createReportAuthoringTools(gateway);
+    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl, provenance } = deps;
+    // The seam rides into each tool that lands an act of the session, thus the composition binds it one
+    // time and no tool reads a second source.
+    const observation = provenance ? { provenance } : {};
+    const authoring = createReportAuthoringTools(gateway, { ...observation, ...(logger ? { logger } : {}) });
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
         createReadFileTool(workspaceFs),
@@ -75,6 +78,7 @@ export function createReportSessionAgent(deps) {
             derivations,
             ...(runDerivation ? { runDerivation } : {}),
             ...(runAuthorizer ? { runAuthorizer } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The render-and-preview tool. It resolves the page root per call.
@@ -84,6 +88,9 @@ export function createReportSessionAgent(deps) {
             ...(makeResolver ? { makeResolver } : {}),
             ...(resolvePageAsset ? { resolvePageAsset } : {}),
             ...(makeSessionPages ? { makeSessionPages } : {}),
+            // The preview is the one site that carries the document into the page, thus the read member
+            // reaches this tool alone.
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
         // The eyes tool. It opens the rendered page in headless Chrome.
@@ -103,6 +110,7 @@ export function createReportSessionAgent(deps) {
             threads,
             resolveWorkspaceRoot,
             ...(makeResolver ? { makeResolver } : {}),
+            ...observation,
             ...(logger ? { logger } : {}),
         }),
     ];

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

@@ -19,7 +19,7 @@ import type { Pool } from "pg";
 import type { AgentDefinition } from "../../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
 import type { SandboxClient } from "../../sandbox/client.js";
-import type { SandboxRef } from "../../sandbox/types.js";
+import type { ExtendAnalysisFarm, SandboxRef, 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";
@@ -84,6 +84,18 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
      * agents that have no terminal status to declare (such as the data profiler).
      */
     readonly blockerHolder?: BlockerHolder;
+    /**
+     * 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.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
+    /**
+     * The declared toolchain owner. Keys the orient-core environment text.
+     * Absent keeps the legacy text, thus an old embedder keeps its cached
+     * prompt prefix.
+     */
+    readonly toolchainSource?: ToolchainSource;
 }
 /** Per-agent override for the prompt composition and tool surface. */
 export interface SandboxAgentPromptOptions {

package/dist/agents/sandbox/shared.js

@@ -15,10 +15,10 @@
  * 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 { sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
+import { sandboxOrientCorePromptFor, sandboxPackageLinkPrompt, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
 import { composeSystemPrompt } from "../system-prompt.js";
-// Sandbox-environment introspection.
-import { createListAvailablePackagesTool, createListAvailableRefsTool } from "../../tools/sandbox/index.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).
@@ -59,7 +59,13 @@ function resolveSandboxTools(deps, tools) {
         throw new Error('createSandboxAgent: SandboxToolName "resolve_citation" requires a CitationResolver dependency.');
     }
     const registry = {
-        listAvailablePackages: createListAvailablePackagesTool({ ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}) }),
+        listAvailablePackages: createListAvailablePackagesTool({
+            ...(deps.farmLockFile ? { farmLockFile: deps.farmLockFile } : {}),
+            ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+            // The bound seam adds `link_packages` below, and the description of
+            // the listing must then stop at "absent", not at "missing".
+            linkToolPresent: deps.extendAnalysisFarm !== undefined,
+        }),
         listAvailableRefs: createListAvailableRefsTool({ ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}) }),
         scanInputs: createScanInputsTool({
             workspaceFs: deps.workspaceFs,
@@ -182,7 +188,14 @@ function buildWorkspaceTools(deps, readOnly) {
  */
 export function createSandboxAgent(deps, meta, body, opts = {}) {
     const appendStandards = opts.appendAnalysisStepStandards ?? true;
-    const sandboxLayer = appendStandards ? [sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt] : [sandboxOrientCorePrompt];
+    // The layer order is fixed by the harness-sandbox-agents spec: the agent
+    // body, the orient core keyed on the declared toolchain, the package-link
+    // layer only when the seam is bound, then the step standards.
+    const sandboxLayer = [
+        sandboxOrientCorePromptFor(deps.toolchainSource),
+        ...(deps.extendAnalysisFarm ? [sandboxPackageLinkPrompt] : []),
+        ...(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 })) : [];
@@ -194,6 +207,10 @@ export function createSandboxAgent(deps, meta, body, opts = {}) {
         // it has no fallback but to re-derive organism, dimensions, and format from the
         // raw bytes — so every sandbox agent gets it, whatever its meta declares.
         createInspectDataProfileTool(deps.pool),
+        // Always-on when the seam is bound, and never in the `meta.tools`
+        // allowlist — an allowlist entry would break an embedder that binds no
+        // seam (the harness-sandbox-agents spec).
+        ...(deps.extendAnalysisFarm ? [createLinkPackagesTool({ extendAnalysisFarm: deps.extendAnalysisFarm, analysisId: deps.step.analysisId })] : []),
         ...skillTools,
         ...resolveSandboxTools(deps, meta.tools),
         ...(deps.blockerHolder ? [createReportBlockerTool(deps.blockerHolder)] : []),

package/dist/app/chat-turn.d.ts

@@ -16,10 +16,21 @@ import type { Pool } from "pg";
 import { type ThreadType } from "../memory/thread-store.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 export interface PrepareChatTurnDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     readonly pool: Pool;
+    /**
+     * The provenance seam. The turn reads its session emit member, and no other
+     * member. The turn holds the one site that writes the conversation thread of
+     * an analysis, thus it is the one site that can tell the embedder the true
+     * moment of that creation.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each site
+     * of a report session.
+     */
+    readonly provenance?: ProvenanceSeam;
 }
 export interface PrepareChatTurnParams {
     readonly analysisId: string;

package/dist/app/chat-turn.js

@@ -21,6 +21,7 @@ import { loadAnalysisStatus, queryNonTerminalRunsByAnalysis } from "../state/ind
 import { assembleMessages } from "./message-assembly.js";
 import { renderRunActivity, renderRunActivityUnavailable, RUN_ACTIVITY_DETAIL_LIMIT } from "./run-activity.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
@@ -29,6 +30,10 @@ import { createNoopLogger } from "../lib/console-logger.js";
 export async function prepareChatTurn(deps, params) {
     const { pool } = deps;
     const { analysisId, threadId, userInput } = params;
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    // An unbound member gives a call that does nothing, thus the emit below needs
+    // no test of its own.
+    const observe = bindSessionEmit(deps.provenance, logger);
     // Ownership check before any read/write of the thread — a `threadId`
     // owned by a different analysis is indistinguishable from a missing one.
     const store = createThreadStore(pool);
@@ -54,13 +59,24 @@ export async function prepareChatTurn(deps, params) {
                 title: deriveThreadTitle(userInput),
             }));
             threadType = created.threadType;
+            // The row that comes back is not proof that this call wrote it. The read
+            // above hides an archived thread, and the idempotent insert then reads
+            // that same row back. Thus a turn on an archived thread reaches here with
+            // a row that a different site created, and an emit would record a start
+            // that never happened.
+            //
+            // This site writes a live conversation thread and nothing else. An
+            // archived row, or a row of another kind, is therefore one that already
+            // existed. A root session has no parent, thus the event carries none.
+            if (created.deletedAt === null && created.threadType === "conversation") {
+                observe({ type: "create-session", analysisId, threadId, sessionKind: created.threadType });
+            }
         }
         else if (!existing.title || existing.title.length === 0) {
             unwrapOrThrow(await store.updateTitle(threadId, deriveThreadTitle(userInput)));
         }
     }
     catch (err) {
-        const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
         logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
     const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);

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

@@ -66,6 +66,7 @@ import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
 import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
+import { type ProvenanceSeam } from "../provenance/seam.js";
 import type { EnsureSessionStateResult } from "./report-session-runtime.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -192,6 +193,17 @@ export interface ReportSessionSpawnDeps {
      * is idempotent.
      */
     readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    /**
+     * The provenance seam. The spawn reads its session emit member, and no other
+     * member. The spawn is the birth of the session, thus it is the one site that
+     * can tell the embedder the true moment of the ask. A consumer that waits for
+     * the first authoring act reads a later moment, and it reads nothing at all
+     * for a session that stays empty.
+     *
+     * The member is optional and fire-and-forget, the same as it is at each
+     * authoring site.
+     */
+    readonly provenance?: ProvenanceSeam;
     /** Operational logging seam. An omitted logger falls back to the no-op. */
     readonly logger?: Logger;
 }

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

@@ -65,6 +65,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { conversationRecordTurn, createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
+import { bindSessionEmit } from "../provenance/seam.js";
 const _assertDomainError = true;
 /**
  * Whether the composition gives a route to a look at the rendered page. The
@@ -165,6 +166,9 @@ export function createReportSessionSpawn(deps) {
     // The routes are fixed at construction, thus the gate reads one boolean and
     // never a live probe of the sidecar.
     const eyesAvailable = compositionHasEyes(deps);
+    // An unbound member gives a call that does nothing, thus the spawn emits at
+    // one site with no test of its own.
+    const observe = bindSessionEmit(deps.provenance, log);
     /**
      * Write the one seed message of the child and give the child back. The
      * message rides as a record, not as user input: nobody typed it in the child
@@ -250,7 +254,7 @@ export function createReportSessionSpawn(deps) {
         if (!eyesAvailable) {
             return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
         }
-        return store.getThread(parentThreadId).andThen((parent) => {
+        const spawned = store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.
             if (parent === null) {
@@ -288,6 +292,22 @@ export function createReportSessionSpawn(deps) {
                     .andThen((child) => ResultAsync.fromSafePromise(pinSessionSnapshot(child))));
             });
         });
+        // The emit rides the ok channel alone, thus a refusal and a fault tell the
+        // embedder nothing. The child row is on disk at this point, and no
+        // authoring act of the session ran yet.
+        //
+        // The kind comes from the row and not from the input, because the insert
+        // is idempotent and the store tells a caller to read the type back.
+        return spawned.map((child) => {
+            observe({
+                type: "create-session",
+                analysisId: child.analysisId,
+                threadId: child.threadId,
+                sessionKind: child.threadType,
+                parentThreadId,
+            });
+            return child;
+        });
     }
     function listReportSessions(analysisId, paging = {}) {
         return store.listThreads({ analysisId, type: "report", ...paging });

package/dist/config/environment-stores.d.ts

@@ -37,11 +37,59 @@ export interface EnvironmentStorePaths {
      */
     readonly refStorePath?: string;
     /**
-     * Host path of the library store's `packages.txt` — the inventory of what is
-     * importable inside a sandbox. Omit when the host mounts the store at the
+     * Host path of the `inflexa.lock` of the farm — the inventory of what is
+     * importable inside a sandbox. Omit when the host mounts the farm at the
      * sandbox's own path, which makes the container path correct as-is; a host
-     * whose store is baked into the image and never bind-mounted must inject the
-     * path to its own extracted copy, or the inventory reads as unknown.
+     * that reads the farm somewhere else must inject the path, or the
+     * inventory reads as unknown.
      */
-    readonly packagesFile?: string;
+    readonly farmLockFile?: string;
+    /**
+     * Host path of the baked image inventory fragment
+     * (`image-packages.txt`) — the image-owned tools that
+     * `list_available_packages` merges into its report. Omit when the host
+     * cannot read one; a missing fragment merges nothing, and that is a
+     * normal state.
+     */
+    readonly imagePackagesFile?: string;
+    /**
+     * The pool-scope inventory of the package store: every package the pool
+     * holds, whether or not a farm links it yet. Bind it for a conversation
+     * or planning surface — the ask flow marks the packages that the POOL
+     * does not hold, and the farm of a new analysis is empty, which would
+     * read as "everything is absent". Leave it unbound for a sandbox agent,
+     * because a step imports only what its farm links. An `unavailable` read
+     * carries the reason of the embedder — a damaged dependency graph reads
+     * as unavailable WITH its cause, never as an empty pool, because the
+     * cause is what tells the agent the state is structural and not
+     * transient.
+     */
+    readonly readPoolInventory?: () => Promise<PoolInventoryRead>;
+}
+/**
+ * What one pool-scope inventory read produced: the sections, or the reason
+ * the pool cannot answer. There is no empty-on-error shape — an unreadable
+ * pool must stay distinguishable from a pool that holds nothing.
+ */
+export type PoolInventoryRead = {
+    readonly kind: "sections";
+    readonly sections: readonly PoolInventorySection[];
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/** One package entry of an inventory section, with the store identity where the source records it. */
+export interface PoolInventoryPackage {
+    readonly name: string;
+    /** The pinned version, rendered as `name==version`. Absent for an image-fragment tool. */
+    readonly version?: string;
+    /** The content-addressed store directory of the package. */
+    readonly storeDir?: string;
+    /** The full sha256 of the sorted store tree. */
+    readonly hash?: string;
+}
+/** One language-track section of an inventory, as `list_available_packages` renders it. */
+export interface PoolInventorySection {
+    readonly title: string;
+    readonly packages: readonly PoolInventoryPackage[];
 }

package/dist/contracts/report-blocks.d.ts

@@ -200,15 +200,15 @@ export declare const ChartAxesSchema: z.ZodObject<{
     x: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
     y: z.ZodOptional<z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodEnum<{
-            log: "log";
             linear: "linear";
+            log: "log";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -297,15 +297,15 @@ export declare const ChartCompositionSchema: z.ZodObject<{
         x: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
         y: z.ZodOptional<z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             scale: z.ZodOptional<z.ZodEnum<{
-                log: "log";
                 linear: "linear";
+                log: "log";
             }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
@@ -724,15 +724,15 @@ export declare const ChartBlockSchema: z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -1168,15 +1168,15 @@ export declare const ATOM_BLOCK_SCHEMAS: readonly [z.ZodObject<{
             x: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
             y: z.ZodOptional<z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 scale: z.ZodOptional<z.ZodEnum<{
-                    log: "log";
                     linear: "linear";
+                    log: "log";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;

package/dist/contracts/schemas/chat-parts.d.ts

@@ -240,9 +240,9 @@ export declare const StepOutputFileSchema: z.ZodObject<{
     fileType: z.ZodEnum<{
         output: "output";
         summary: "summary";
-        script: "script";
-        figure: "figure";
         log: "log";
+        figure: "figure";
+        script: "script";
         notebook: "notebook";
     }>;
     description: z.ZodString;
@@ -259,9 +259,9 @@ export declare const StepOutputPartSchema: z.ZodObject<{
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;
@@ -597,9 +597,9 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         fileType: z.ZodEnum<{
             output: "output";
             summary: "summary";
-            script: "script";
-            figure: "figure";
             log: "log";
+            figure: "figure";
+            script: "script";
             notebook: "notebook";
         }>;
         description: z.ZodString;

package/dist/index.d.ts

@@ -36,6 +36,9 @@ export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
 export type { MakeSessionPagePublisher, SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
+export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";
+export type { DerivationSource } from "./state/report-session-state.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
@@ -131,6 +134,10 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
+export type { ExtendAnalysisFarm, FarmLocation, FarmResolution, FarmSource, PackageRequest, PackageRequestOutcome, ResolveAnalysisFarm, ToolchainSource, } from "./sandbox/types.js";
+export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
+export type { FarmLock, FarmLockError } from "./sandbox/farm.js";
+export type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventoryRead, PoolInventorySection } from "./config/environment-stores.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export type { MachineBudget, ResourceLimits, ResourcePolicy, ResourceSpec } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
@@ -140,7 +147,7 @@ export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.j
 export { ExecEventMessageSchema } from "./sandbox/types.js";
 export type { ExecEventMessage, DoneMarker } from "./sandbox/types.js";
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
-export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
+export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
 export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";

package/dist/index.js

@@ -47,6 +47,14 @@ export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.j
 // state. The URL seam of the eyes rides beside the publisher factory: a host whose
 // browser cannot reach the workspace tree binds a served URL for the look.
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
+// Seam: the one provenance surface. The embedder records the facts of a run and the acts of a
+// session in the document of the analysis that it owns, and it gives the bytes of that document
+// back for the report page. Thus the seam and its vocabulary belong on the front door: an embedder
+// cannot type its realization without them. The two binders ride beside the types, because an
+// embedder that calls `prepareChatTurn` or one tool factory directly binds the same total forms
+// that the assembly binds. `DerivationSource` rides beside the event union, because the derivation
+// event carries the chain of the derived table.
+export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 // Seam: workflow-ledger reclamation — cancels and deletes an analysis's rows in
@@ -229,6 +237,9 @@ export { createAnalysisPurge } from "./state/purge-analysis.js";
 // the failure a fixed-width comparand exists to prevent.
 export { computeInputSignature } from "./execution/input-signature.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
+// The farm contract: one `inflexa.lock` per farm. An embedder that composes
+// farms writes this shape, and the mount gate reads it — one schema, no copy.
+export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "./sandbox/farm.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
 // Exec-callback ingress building blocks. Delivery goes through

package/dist/prompts/briefing.d.ts

@@ -40,7 +40,7 @@ export declare const STEP_TASK_FIELDS: readonly ["name", "question", "descriptio
  * {@link renderResources} section, because the budget is an execution bound,
  * not a task instruction.
  */
-export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error"];
+export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type", "depends_on", "status", "resources", "agent", "timeout", "maxSteps", "summary", "artifactIds", "error", "packages"];
 /**
  * The step's own instructions. Only `question` is guaranteed present; the
  * remaining task fields are appended as dedicated sections when populated, so a