@inflexa-ai/harness 0.46.2 → 0.47.0

package/dist/tools/bio/search-gene.js

@@ -29,6 +29,22 @@ const NON_SYMBOL_PATTERNS = [/^ENSG\d{11}$/, /^HGNC:\d+$/, /^CHEMBL\d+$/, /^[A-Z
 function isSymbol(identifier) {
     return !NON_SYMBOL_PATTERNS.some((pattern) => pattern.test(identifier));
 }
+const SearchGeneOutputSchema = z.object({
+    genes: z.array(z.object({
+        symbol: z.string(),
+        id: z.string().describe("The Ensembl gene id (ENSG…), the key of the other gene lookups."),
+        displayName: z.string(),
+        description: z.string(),
+        biotype: z.string(),
+        start: z.number(),
+        end: z.number(),
+        strand: z.number(),
+        assemblyName: z.string(),
+        seqRegionName: z.string(),
+    })),
+    resolvedFrom: z.array(z.object({ input: z.string(), symbol: z.string() })),
+    notFound: z.array(z.string()),
+});
 export const searchGeneTool = defineTool({
     id: "search_gene",
     description: "Resolve gene identifiers against Ensembl — the identifier step other tools depend on. Per gene: Ensembl gene ID (ENSG…), coordinates, strand, " +
@@ -41,6 +57,7 @@ export const searchGeneTool = defineTool({
         "non-human `species` looks the ortholog up by the human approved symbol.\n" +
         "notFound is valid no-data (a deprecated, aliased or mistyped identifier, or one this species has no gene for) — report it and continue, do not " +
         "retry unchanged.",
+    outputSchema: SearchGeneOutputSchema,
     inputSchema: z.object({
         identifiers: z
             .array(z.string())

package/dist/tools/bio/search-geo-datasets.js

@@ -70,6 +70,18 @@ export function mapGeoDatasets(ids, summary) {
     }
     return datasets;
 }
+const SearchGeoDatasetsOutputSchema = z.object({
+    totalFound: z.number(),
+    datasets: z.array(z.object({
+        accession: z.string(),
+        title: z.string(),
+        summary: z.string(),
+        platform: z.string().nullable(),
+        sampleCount: z.number().nullable(),
+        organism: z.string().nullable(),
+        pubmedIds: z.array(z.union([z.string(), z.number()])),
+    })),
+});
 export const searchGeoDatasetsTool = defineTool({
     id: "search_geo_datasets",
     description: "Search the NCBI Gene Expression Omnibus (GEO) — the public functional-genomics repository of the U.S. National Library of Medicine — for " +
@@ -80,6 +92,7 @@ export const searchGeoDatasetsTool = defineTool({
         "HARD CAVEAT: this tool returns metadata only, and sandbox containers have no network — never plan an in-sandbox step that downloads a GEO dataset. " +
         "Bringing the data itself in is a capability of the surrounding environment, not of this tool: consult the tools you actually have rather than assuming it is possible or that it is not. " +
         "An empty datasets array is a valid 'nothing matched' — do not retry the identical query.",
+    outputSchema: SearchGeoDatasetsOutputSchema,
     inputSchema: z.object({
         query: z
             .string()

package/dist/tools/bio/search-regulatory-approvals.js

@@ -105,7 +105,7 @@ export function createSearchRegulatoryApprovalsTool(deps) {
             "ANDA), emaProductNumber, ndc (product or package code) or splSetId.\n" +
             "status 'not_found' is a valid no-data answer and status 'ambiguous' lists the candidate amassIds of an identifier that matches more " +
             "than one record — call 'details' again with one of them. An empty search is also valid no-data. Do not retry any of these unchanged.\n" +
-            "Requires AMASS_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without " +
+            "Requires AMASS_API_KEY — a missing key fails terminally: do NOT retry; state that the key is not configured, and proceed without " +
             "Amass regulatory data. Every call spends the user's Amass credits.",
         inputSchema,
         describeCall: "none",

package/dist/tools/define-tool.d.ts

@@ -128,6 +128,13 @@ export type ToolContext = {
      * no child agent ignores it.
      */
     readonly turnUsage?: AgentRunUsage;
+    /**
+     * The script that makes this call, when `run_script` makes it. A tool that records how its output was made
+     * keeps the code, for example the derivation record of a report session. Absent for a call of the model.
+     */
+    readonly script?: {
+        readonly code: string;
+    };
 };
 /** What the approval hook of a tool reads of its call. */
 export type ToolApprovalContext = {
@@ -143,6 +150,10 @@ export type Tool<Input = unknown, Output = unknown> = {
     readonly description: string;
     readonly inputSchema: z.ZodType<Input>;
     readonly jsonSchema: Record<string, unknown>;
+    /** See {@link ToolDefinition.outputSchema}. Absent when the tool declares none. */
+    readonly outputSchema?: z.ZodType;
+    /** The JSON Schema of {@link outputSchema}. */
+    readonly outputJsonSchema?: Record<string, unknown>;
     /** See {@link ToolDefinition.describeCall}. Absent when the tool declares none. */
     describeCall?(input: Input): string | undefined;
     /** See {@link ToolDefinition.describeResult}. Absent when the tool declares none. */
@@ -156,12 +167,19 @@ export type Tool<Input = unknown, Output = unknown> = {
     approval?(input: Input, ctx: ToolApprovalContext): AskRequest | undefined | Promise<AskRequest | undefined>;
     /** See {@link ToolDefinition.startsWorkflow}. */
     readonly startsWorkflow?: boolean;
+    /** See {@link ToolDefinition.ownStep}. */
+    readonly ownStep?: boolean;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 };
-export type ToolDefinition<Schema extends z.ZodType<z.output<Schema>>, Output> = {
+export type ToolDefinition<Schema extends z.ZodType<z.output<Schema>>, Output, OutputSchema extends z.ZodType = z.ZodType> = {
     readonly id: string;
     readonly description: string;
     readonly inputSchema: Schema;
+    /**
+     * The shape of the ok value. A script reads the value as data, thus `run_script` shows this type in the signature
+     * of the tool. The value of `execute` must hold each field of the schema, and it can hold more.
+     */
+    readonly outputSchema?: OutputSchema;
     /**
      * One line that names what THIS call does — the call-time counterpart of
      * `description`. `description` self-describes the tool at attach time, so an
@@ -251,6 +269,11 @@ export type ToolDefinition<Schema extends z.ZodType<z.output<Schema>>, Output> =
      * child before its first `await`, thus the parallel calls of one reply keep their order on a replay.
      */
     readonly startsWorkflow?: boolean;
+    /**
+     * The call must be one durable step of its own, for example an exec whose id comes from its step. Each call of
+     * a script runs inside the one step of the script, thus `withRunScript` refuses such a tool as a script tool.
+     */
+    readonly ownStep?: boolean;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 };
 /**
@@ -260,4 +283,4 @@ export type ToolDefinition<Schema extends z.ZodType<z.output<Schema>>, Output> =
  * the first LLM call). Union-shaped inputs must be modelled as a flat object
  * with a discriminator field.
  */
-export declare function defineTool<Schema extends z.ZodType<z.output<Schema>>, Output>(def: ToolDefinition<Schema, Output>): Tool<z.infer<Schema>, Output>;
+export declare function defineTool<Schema extends z.ZodType<z.output<Schema>>, Output extends z.output<OutputSchema>, OutputSchema extends z.ZodType = z.ZodType>(def: ToolDefinition<Schema, Output, OutputSchema>): Tool<z.infer<Schema>, Output>;

package/dist/tools/define-tool.js

@@ -111,13 +111,15 @@ export function defineTool(def) {
             `top-level "type" — model the input as a flat object with a ` +
             `discriminator field instead.`);
     }
-    const packaged = {
+    let packaged = {
         id: def.id,
         description: def.description,
         inputSchema: def.inputSchema,
         jsonSchema,
         execute: def.execute.bind(def),
     };
+    if (def.outputSchema !== undefined)
+        packaged = { ...packaged, outputSchema: def.outputSchema, outputJsonSchema: outputJsonSchemaOf(def.outputSchema) };
     if (typeof def.foldCallRecord === "function")
         packaged.foldCallRecord = def.foldCallRecord.bind(def);
     if (typeof def.approval === "function")
@@ -133,7 +135,15 @@ export function defineTool(def) {
     // property check on either side.
     if (def.describeResult !== undefined)
         packaged.describeResult = def.describeResult;
+    if (def.ownStep === true)
+        packaged = { ...packaged, ownStep: true };
     if (def.startsWorkflow === true)
         return { ...packaged, startsWorkflow: true };
     return packaged;
 }
+/** The JSON Schema of an ok value, as a reader of the value sees it. */
+function outputJsonSchemaOf(schema) {
+    const json = z.toJSONSchema(schema, { io: "output", unrepresentable: "any" });
+    delete json.$schema;
+    return json;
+}

package/dist/tools/display/show-user.js

@@ -41,7 +41,7 @@ const ShowUserInputSchema = z.object({
     dataPath: z
         .string()
         .optional()
-        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names (read only its header) and omit `dataset.source` from the spec — the rows are never pulled through the context window. The tool checks the shape of the path only, not that the file exists; a wrong path fails only when the card renders. If the data is not chart-ready (needs aggregation, filtering, reshaping), do that in a sandbox step that writes a chart-ready CSV. Inline `dataset.source` is only for a handful of numbers you just computed in conversation that exist nowhere as an artifact."),
+        .describe("echart only: analysis-rooted CSV artifact path (e.g. 'runs/run-abc/step-2/output/de-summary.csv') the host loads as the ECharts `dataset.source` at render time. Author `encode`/dimensions against the CSV's column names (read only its header) and omit `dataset.source` from the spec — the rows are never pulled through the context window. The tool checks the shape of the path only, not that the file exists; a wrong path fails only when the card renders. If the data is not chart-ready (it needs an aggregate, a filter, or a reshape), make a chart-ready CSV with `run_script` (`read_table`, then `write_derived`), and pass its path. Inline `dataset.source` is only for a handful of numbers you just computed in conversation that exist nowhere as an artifact."),
     body: z.string().optional().describe("Markdown content to render (kind=markdown)"),
     code: z.string().optional().describe("Code content (kind=code)"),
     language: z.string().optional().describe("Language identifier, e.g. r, python, bash (kind=code)"),

package/dist/tools/execute-analysis.d.ts

@@ -9,7 +9,6 @@ import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
-import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import type { Logger } from "../lib/logger.js";
@@ -33,7 +32,6 @@ export type ExecuteAnalysisToolDeps = Pick<EnvironmentStorePaths, "farmLockFile"
     readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
     readonly runAuthorizer: RunAuthorizer;
     readonly runLauncher: RunLauncher;
-    readonly resourcePolicy?: ResourcePolicy;
     readonly utilityProvider: ChatProvider;
     readonly utilityModel: string;
     readonly logger?: Logger;
@@ -78,7 +76,7 @@ export declare class PlanReferencesMissingError extends Error {
     constructor(missing: string[], unavailable?: string | undefined);
 }
 /** The deps that start the run of a stored plan. */
-export type LaunchPlanRunDeps = Pick<ExecuteAnalysisToolDeps, "pool" | "executeAnalysisWorkflow" | "runAuthorizer" | "runLauncher" | "resourcePolicy" | "extendAnalysisFarm" | "refStorePath" | "logger">;
+export type LaunchPlanRunDeps = Pick<ExecuteAnalysisToolDeps, "pool" | "executeAnalysisWorkflow" | "runAuthorizer" | "runLauncher" | "extendAnalysisFarm" | "refStorePath" | "logger">;
 /**
  * The run of a stored plan. `started` is false when this call started nothing: `runId` then names the
  * active run of the plan, or the newest run of the plan when the view of the caller was stale.

package/dist/tools/execute-analysis.js

@@ -51,20 +51,20 @@ const inputSchema = z
 });
 export class PlanNotFoundError extends Error {
     constructor(planId) {
-        super(`Plan ${planId} not found for this analysis`);
+        super(`Plan ${planId} not found for this analysis. Generate a new plan; a retry of this planId fails the same way.`);
         this.name = "PlanNotFoundError";
     }
 }
 export class PlanMalformedError extends Error {
     constructor(planId) {
-        super(`Plan ${planId} is malformed`);
+        super(`Plan ${planId} is malformed. Generate a new plan; a retry of this planId fails the same way.`);
         this.name = "PlanMalformedError";
     }
 }
 export class PlanValidationError extends Error {
     errors;
     constructor(planId, errors) {
-        super(`Plan ${planId} failed validation: ${errors.length} error(s)`);
+        super(`Plan ${planId} failed validation: ${errors.length} error(s). Generate a new plan; a retry of this planId fails the same way.`);
         this.errors = errors;
         this.name = "PlanValidationError";
     }
@@ -243,25 +243,6 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, planId, plan) {
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
 }
-/**
- * The resources of each step. `validatePlan` refuses a step without them, thus
- * a missing entry here means that the two readers disagree.
- */
-function stepResources(planId, plan) {
-    const byStepId = {};
-    for (const step of plan.steps) {
-        if (!step.resources) {
-            return err({
-                type: "plan_invalid",
-                planId,
-                malformed: false,
-                errors: [`Step "${step.id}" has no resources — validation should have rejected it`],
-            });
-        }
-        byStepId[step.id] = step.resources;
-    }
-    return ok(byStepId);
-}
 function workflowInput(planId, plan, args) {
     return {
         analysisId: args.analysisId,
@@ -270,10 +251,8 @@ function workflowInput(planId, plan, args) {
         threadId: args.threadId,
         steps: plan.steps.map((step) => ({ id: step.id, depends_on: step.depends_on })),
         planStepById: Object.fromEntries(plan.steps.map((step) => [step.id, step])),
+        request: plan.request,
         agentByStepId: Object.fromEntries(plan.steps.map((step) => [step.id, step.agent ?? "unknown"])),
-        resourcesByStepId: args.resourcesByStepId,
-        timeoutByStepId: Object.fromEntries(plan.steps.flatMap((step) => (step.timeout === undefined ? [] : [[step.id, step.timeout]]))),
-        budget: args.budget,
         runSession: args.runSession,
         synthesisEnabled: args.synthesisEnabled,
     };
@@ -349,7 +328,6 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
                 packages: [...route.packages],
                 depends_on: [],
                 status: "pending",
-                resources: route.resources,
                 agent: route.agentId,
                 capability: route.capability,
                 maxSteps: meta?.defaultMaxSteps ?? DEFAULT_SANDBOX_MAX_STEPS,
@@ -394,7 +372,6 @@ async function persistedAdHocPlan(deps, args) {
         provider: deps.utilityProvider,
         model: deps.utilityModel,
         pool: deps.pool,
-        resourcePolicy: deps.resourcePolicy,
         logger: deps.logger,
         resolvePackages,
         usageRecorder: deps.usageRecorder,
@@ -426,9 +403,6 @@ async function launchReservedRun(deps, args) {
     const { session, planId, plan } = args;
     const analysisId = session.scope.analysisId;
     const threadId = session.scope.threadId ?? null;
-    const resources = stepResources(planId, plan);
-    if (resources.isErr())
-        return err(resources.error);
     // Reference data first: it is a read, so it costs nothing to learn before the farm link
     // writes. Both passes come before the run reserves anything, thus a miss of either leaves no
     // run row and no revoked authorization behind.
@@ -466,9 +440,7 @@ async function launchReservedRun(deps, args) {
         analysisId,
         threadId,
         runSession,
-        budget: deps.resourcePolicy?.budget,
         synthesisEnabled: args.mode === "plan",
-        resourcesByStepId: resources.value,
     });
     try {
         await deps.runLauncher.launch(deps.executeAnalysisWorkflow, { workflowId: runId }, wfInput);
@@ -649,7 +621,7 @@ export function createExecuteAnalysisTool(deps) {
         description: "Launch analysis computation asynchronously. Use mode=plan with the planId only after the user approved that stored plan. " +
             "Use mode=adhoc with the user's exact targeted computational request when they explicitly asked to run/compute/test/compare it; " +
             "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
-            "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn. " +
+            "Returns runId with status=in_progress; inspect results on a later turn. " +
             "A plan that already has an active run returns that run, so a second run of one plan does not start. " +
             "The launch fails with an error, and no run starts, when the plan is not found or fails validation, when a package of the plan cannot link, or when the run is not authorized.",
         inputSchema,

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

@@ -9,5 +9,4 @@ export { createPreviewReportTool, type PreviewReportInput, type PreviewReportRes
 export { createExaminePageTool, type CaptureCoverage, type CapturePage, type ExaminedTile, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
 export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageGrant, type SessionPageMintFailure, type SessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
-export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";
 export { createListPinnedArtifactsTool, type ListPinnedArtifactsInput, type ListPinnedArtifactsResult, type ListPinnedArtifactsToolDeps, type PinnedArtifact, type PinnedCitation, } from "./list-artifacts.js";

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

@@ -9,5 +9,4 @@ export { createPreviewReportTool, } from "./preview-report.js";
 export { createExaminePageTool, } from "./examine-page.js";
 export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool } from "./record-version.js";
-export { createDeriveTableTool } from "./derive-table.js";
 export { createListPinnedArtifactsTool, } from "./list-artifacts.js";

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

@@ -0,0 +1,30 @@
+/**
+ * The script tools of a report session: `read_table` over the pinned evidence, and `write_derived`, which pins a
+ * derived table to the session.
+ *
+ * A script reshapes the evidence into the table that a block binds: a join, a pivot, or an aggregate. The script
+ * runs in the VM of `run_script`, thus a derivation starts no container. A table over 16 MiB does not derive.
+ *
+ * `read_table` reads only a member of the served snapshot, and it refuses bytes whose hash is not the pinned hash.
+ * `write_derived` keeps the rules of a session derivation: the output lands under the derived directory of the session,
+ * each declared input must be a member, a name that the session holds is refused, and the record chains the
+ * table to its inputs and to the code of the script. A rerun of a call whose record landed gives that record
+ * back, and it emits the derivation again.
+ */
+import type { Logger } from "../../lib/logger.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
+import type { ReportSessionStateStore } from "../../state/report-session-state.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway } from "../report-authoring/authoring-tools.js";
+export type ReportScriptToolsDeps = {
+    readonly gateway: ReportSessionStateGateway;
+    readonly workspaceFs: WorkspaceFilesystem;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
+    readonly provenance?: ProvenanceSeam;
+    readonly logger?: Logger;
+};
+/** The script tools of a report session. */
+export declare function createReportScriptTools(deps: ReportScriptToolsDeps): Tool[];

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

@@ -0,0 +1,177 @@
+/**
+ * The script tools of a report session: `read_table` over the pinned evidence, and `write_derived`, which pins a
+ * derived table to the session.
+ *
+ * A script reshapes the evidence into the table that a block binds: a join, a pivot, or an aggregate. The script
+ * runs in the VM of `run_script`, thus a derivation starts no container. A table over 16 MiB does not derive.
+ *
+ * `read_table` reads only a member of the served snapshot, and it refuses bytes whose hash is not the pinned hash.
+ * `write_derived` keeps the rules of a session derivation: the output lands under the derived directory of the session,
+ * each declared input must be a member, a name that the session holds is refused, and the record chains the
+ * table to its inputs and to the code of the script. A rerun of a call whose record landed gives that record
+ * back, and it emits the derivation again.
+ */
+import { join } from "node:path";
+import { ok, err } from "neverthrow";
+import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { computeSha256 } from "../../lib/fs-helpers.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
+import { snapshotEntry } from "../../report-model/reference-resolver.js";
+import { isSafeId, reportSessionDerivedDir } from "../../workspace/paths.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { ReadTableOutputSchema, readTableRows, rowsText } from "../script/file-tools.js";
+import { DERIVED_FILE_CAP_BYTES } from "../script/scratch.js";
+import { confinedWrite } from "../workspace/mutator.js";
+function refused(error) {
+    return err({ error, retryable: false });
+}
+const readTableInput = z.object({
+    path: z.string().min(1).describe("The path of a pinned artifact or of a derived table of this session, as `list_pinned_artifacts` gives it."),
+    columns: z.array(z.string()).min(1).optional().describe("Keep only these columns. Absent: each column."),
+});
+function createReadTableTool(deps) {
+    return defineTool({
+        id: "read_table",
+        description: "Read one table of the pinned evidence as rows: CSV, TSV, JSON (an array of flat objects), or parquet, up to 16 MiB. " +
+            "Each row is an object keyed by column, and a cell that holds a plain number reads as a number. " +
+            "A larger table does not derive; tell the user which table is absent.",
+        inputSchema: readTableInput,
+        outputSchema: ReadTableOutputSchema,
+        describeCall: ({ path }) => path,
+        describeResult: (_input, result) => `${String(result.rowCount)} rows`,
+        execute: async ({ path, columns }, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr())
+                return refused(opened.error.detail);
+            const entry = snapshotEntry(opened.value.state.snapshot, path);
+            if (entry === undefined)
+                return refused(`the pinned evidence of this session holds no artifact at ${path}; list_pinned_artifacts gives the paths`);
+            const table = await readTableRows({
+                workspaceFs: deps.workspaceFs,
+                session: ctx.session,
+                path,
+                columns,
+                tooLarge: "a larger table does not derive",
+            });
+            if (table.isErr())
+                return refused(table.error);
+            const hash = computeSha256(table.value.content);
+            if (hash !== entry.hash)
+                return refused(`${path} changed after the session pinned it, thus its bytes are not the evidence of this session`);
+            const { rows } = table.value;
+            return ok(withToolCallRecord({ path, columns: table.value.columns, rowCount: rows.length, rows }, { reads: [{ path, hash }] }));
+        },
+    });
+}
+const writeDerivedInput = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe("The file name of the table, with no directory, for example 'yield_by_group.csv'. The extension picks the format: .csv, .tsv, or .json."),
+    rows: z
+        .array(z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])))
+        .describe("The rows of the table, each an object keyed by column."),
+    inputs: z.array(z.string()).min(1).describe("The path of each pinned table that the script read for this table. The record pins the hash of each one."),
+});
+const DerivedOutputSchema = z.object({ path: z.string(), hash: z.string(), columns: z.array(z.string()).readonly() });
+function derivedOutput(record, size, columns) {
+    return withToolCallRecord({ path: record.outputPath, hash: record.outputHash, columns }, { writes: [{ path: record.outputPath, hash: record.outputHash, size }] });
+}
+function createWriteDerivedTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("report-write-derived");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    const observeDerived = (analysisId, threadId, record) => {
+        observe({
+            type: "run-derivation",
+            analysisId,
+            threadId,
+            outputPath: record.outputPath,
+            outputHash: record.outputHash,
+            scriptHash: record.scriptHash,
+            sources: record.sources.map((source) => ({ path: source.path, hash: source.hash })),
+        });
+    };
+    return defineTool({
+        id: "write_derived",
+        description: "Pin one derived table to this session, and give its path for a block to bind. " +
+            "Name each pinned table that the script read in `inputs`. A name that this session already holds is refused, thus a second derivation of one table takes a new name.",
+        inputSchema: writeDerivedInput,
+        outputSchema: DerivedOutputSchema,
+        describeCall: ({ name }) => name,
+        describeResult: (_input, result) => result.path,
+        execute: async ({ name, rows, inputs }, ctx) => {
+            if (ctx.script === undefined)
+                return refused("write_derived runs inside a script only");
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr())
+                return refused(opened.error.detail);
+            const { threadId, analysisId, state, derivations } = opened.value;
+            const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+            // A rerun of a call whose record landed gives that record back. The membership holds the output of
+            // the record by now, thus the name test below would refuse the call its own table.
+            const recorded = derivations.find((record) => record.toolCallId === ctx.invocationId);
+            if (recorded !== undefined) {
+                observeDerived(analysisId, threadId, recorded);
+                return ok(derivedOutput(recorded, Buffer.byteLength(rowsText(name, rows) ?? "", "utf8"), columns));
+            }
+            if (!isSafeId(name))
+                return refused("the name is one file name, with no directory, no separator, and no traversal");
+            const text = rowsText(name, rows);
+            if (text === undefined)
+                return refused(`${name} names no table format: end the name in .csv, .tsv, or .json`);
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (bytes > DERIVED_FILE_CAP_BYTES)
+                return refused(`the table is ${String(bytes)} bytes, and the cap of a derived table is ${String(DERIVED_FILE_CAP_BYTES)} bytes`);
+            const sources = [];
+            for (const path of new Set(inputs)) {
+                const entry = snapshotEntry(state.snapshot, path);
+                if (entry === undefined)
+                    return refused(`the pinned evidence of this session holds no artifact at ${path}`);
+                sources.push({ path, hash: entry.hash });
+            }
+            const dir = reportSessionDerivedDir(threadId);
+            const outputPath = `${dir}/${name}`;
+            if (snapshotEntry(state.snapshot, outputPath) !== undefined) {
+                return refused(`the evidence of this session already holds ${outputPath}, thus this table takes a new name`);
+            }
+            const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
+            const landed = await confinedWrite({
+                workspaceRoot,
+                analysisId,
+                workingDir: join(workspaceRoot, dir),
+                path: name,
+                content: text,
+                invocationId: ctx.invocationId,
+                beforeLand: undefined,
+                refuseStagedInputs: true,
+            });
+            if (landed.status !== "ok")
+                return refused(`the write of ${outputPath} was refused (${landed.status})`);
+            const record = {
+                outputPath,
+                outputHash: computeSha256(landed.bytes),
+                sources,
+                scriptHash: computeSha256(Buffer.from(ctx.script.code, "utf8")),
+                script: ctx.script.code,
+                toolCallId: ctx.invocationId,
+            };
+            const appended = await deps.derivations.appendDerivation(threadId, record);
+            if (appended.isErr()) {
+                logger.error("the derivation record did not land", { threadId, ...logger.errorFields(appended.error.cause) });
+                return err({ error: "the derivation record did not land, thus the table is not evidence of this session", retryable: true });
+            }
+            if (appended.value === "duplicate")
+                return refused(`another turn recorded ${outputPath} first, thus this table takes a new name`);
+            if (appended.value === "absent")
+                return refused("no report session state row exists to hold the derivation");
+            observeDerived(analysisId, threadId, record);
+            return ok(derivedOutput(record, landed.bytes.length, columns));
+        },
+    });
+}
+/** The script tools of a report session. */
+export function createReportScriptTools(deps) {
+    return [createReadTableTool(deps), createWriteDerivedTool(deps)];
+}

package/dist/tools/research/generate-analogy-report.d.ts

@@ -1,13 +1,11 @@
 /**
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
- * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runWithSalvage`. The result reaches the wrapper through one of two
- * submit tools because the output envelope is a union and `defineTool` takes
- * only a top-level object. Neither tool ends the run: the wrapper selects the
- * last accepted report from the recorded calls, else the first blocker. A run
- * with no outcome gets one salvage request, then an `extraction-failed`
- * envelope, so the frontend never renders raw prose.
+ * An inline harness `AgentDefinition` driven by `runWithSalvage`. The reasoner records its report in parts: the
+ * problem with its planned analogies, then each analogy when its search is done. A provider filter can stop a reply in
+ * the middle of a call, and a cut call is lost whole, thus a small part loses little. The wrapper assembles the report
+ * from the last accepted record of each part, else it gives the first blocker. A run with no outcome gets one salvage
+ * request, then an `extraction-failed` envelope, so the frontend never renders raw prose.
  */
 import { z } from "zod";
 import { type AnalogyReport } from "@inflexa-ai/harness/contracts/analogy-report.js";
@@ -15,12 +13,17 @@ import type { Logger } from "../../lib/logger.js";
 import { type LoopStep } from "../../loop/run-loop.js";
 import type { SubAgentRegistrar } from "../../loop/sub-agent.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
+import type { AgentDefinition } from "../../loop/types.js";
+import type { ScriptRuntime } from "../script/run-script.js";
 import type { ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
-/** The last report of a run that its call accepted. The input schema of the tool checked it. */
-export declare function acceptedReportOf(steps: readonly LoopStep[]): AnalogyReport | undefined;
+/**
+ * The report that a run recorded, or nothing when it recorded no problem. The analogies keep the planned order, and a
+ * recorded analogy that the plan does not name follows them. A planned analogy with no record is not loaded.
+ */
+export declare function assembledReportOf(steps: readonly LoopStep[]): AnalogyReport | undefined;
 export declare const generateAnalogyReportInputSchema: z.ZodObject<{
     problem: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
@@ -49,6 +52,10 @@ export type GenerateAnalogyReportDeps = {
     readonly toolOutputStore?: ToolOutputStore;
     /** Logging seam; omitted falls back to no-op. Logs the salvage warning and an accounting error of the reasoner loop. */
     readonly logger?: Logger;
+    /** Where the VM of `run_script` comes from. See {@link ScriptRuntime}. */
+    readonly scriptRuntime?: ScriptRuntime;
 };
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
+/** The analogical reasoner: its searches run in a script, and it records its report and a blocker directly. */
+export declare function analogyAgentOf(deps: Pick<GenerateAnalogyReportDeps, "bioKeys" | "model" | "toolOutputStore" | "scriptRuntime">): AgentDefinition;
 export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps, registerSubAgent: SubAgentRegistrar): Tool;