@inflexa-ai/harness 0.41.0 → 0.41.2

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

@@ -393,9 +393,14 @@ export function createPreviewReportTool(deps) {
     const resolvePageAsset = deps.resolvePageAsset ?? resolvePageAssetFromInstallation;
     return defineTool({
         id: "preview_report",
-        description: "Render the current draft to a self-contained HTML page, and give back the page path. " +
+        description: "Render the current draft to an HTML page in the session directory, and give back the page path. " +
+            "The page loads its figures, table data, and libraries from an assets directory that the tool stages beside it. " +
             "The tool finishes the draft first: an incomplete draft gives back the gap list, and no page renders. " +
             "On a pass it resolves each reference, stages each bound image beside the page, and writes the page. " +
+            "An unresolved reference gives back the block and the binding to repair. " +
+            "The outcome resolver-unavailable means that this host gives no reference resolver, and a repeat gives the same outcome. " +
+            "A rendered page carries pagePath, and access when the host serves the page: a URL with its expiry, or the reason that no URL was granted. " +
+            "The render marks the page that examine_page looks at next. " +
             "Use it to see the report, and to confirm that each reference resolves.",
         inputSchema: previewReportInput,
         executionMode: "inline",

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

@@ -128,7 +128,8 @@ export function createRecordVersionTool(deps) {
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
             "resolves each reference, matches each chart encoding, and matches each assert. An incomplete draft gives back the gap list, " +
-            "and a failed reference gives back the block that broke. The tool records a version only after the eyes look at the current page. " +
+            "and a failed reference gives back the block that broke. The tool records a version only after examine_page looked at the page of the current draft: " +
+            "with no look it gives back never-seen, and after an edit since the look it gives back stale-look. " +
             "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
             "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
         inputSchema: recordVersionInput,

package/dist/tools/research/context7-docs.js

@@ -43,7 +43,10 @@ function renderSnippets(snippets) {
 }
 export const resolveLibraryIdTool = defineTool({
     id: "resolve_library_id",
-    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE `query_docs` to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
+    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to the Context7 library ID that `query_docs` needs. " +
+        "Returns the single best match as {found: true, libraryId, name, description}, or {found: false} when Context7 holds no library for the name. " +
+        "`query` ranks the candidates and only the top one comes back, thus make sure that `name` is the package you meant. " +
+        "A failed Context7 request returns an error result.",
     inputSchema: z.object({
         libraryName: z.string().describe("Package or library name to search for (e.g., 'scanpy', 'pysam', 'lifelines')."),
         query: z.string().describe("What you need help with — used to rank results by relevance (e.g., 'how to run differential expression')."),
@@ -69,7 +72,10 @@ export const resolveLibraryIdTool = defineTool({
 });
 export const queryDocsTool = defineTool({
     id: "query_docs",
-    description: "Query up-to-date documentation and code examples for a library. You must call `resolve_library_id` first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
+    description: "Query up-to-date documentation and code examples for a library. The libraryId comes from `resolve_library_id`. " +
+        "Returns {found: true, documentation}: Markdown snippets, each with a title, a source id, a description, and code blocks. " +
+        "Returns {found: false} when Context7 holds no library at that ID or no snippet for the query. A failed Context7 request returns an error result. " +
+        "Use this to verify function signatures, parameters, and usage patterns before writing code.",
     inputSchema: z.object({
         libraryId: z.string().describe("Context7 library ID exactly as `resolve_library_id` gave it — an owner and a library, for example '/scverse/scanpy'."),
         query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),

package/dist/tools/research/generate-analogy-report.js

@@ -39,7 +39,7 @@ function createSubmitAnalogyReportTool(cell) {
             "relations, and key terms of phase 1, and each analogy with its " +
             "coverage and its cited solutions from phase 2. Call it one time with " +
             "the full report. If it rejects the report, correct the fields that it " +
-            "names and call it again. Stop immediately after an accepted call.",
+            "names and call it again. An accepted call ends the run.",
         inputSchema: AnalogyReportSchema,
         describeCall: "none",
         execute: async (report) => {
@@ -47,7 +47,7 @@ function createSubmitAnalogyReportTool(cell) {
             cell.outcome = { kind: "report", report };
             return ok({
                 recorded: true,
-                message: "Report recorded. You are done — stop now and do not take further actions.",
+                message: "Report recorded.",
             });
         },
     });
@@ -135,25 +135,25 @@ export function createGenerateAnalogyReportTool(deps) {
         description: "Idea-generation engine. Extracts structural analogies for an open-ended " +
             "scientific problem and returns real, cited solutions from other fields " +
             "(control theory, ML, ecology, logistics, economics…).\n" +
-            "WHEN: any exploratory or hypothesis-generation turn — 'what could we do " +
-            "about X', 'what should we try', 'how could we approach this', 'we're " +
-            "stuck', 'brainstorm ideas', 'are there precedents outside biology'. The " +
-            "trigger is exploratory INTENT, not the words 'analogy' or 'cross-domain' " +
-            "— users rarely name it, so infer it and reach for the tool proactively.\n" +
+            "WHEN: an exploratory or hypothesis-generation turn — the user asks how " +
+            "to approach a problem, what to try, or whether precedents exist outside " +
+            "biology. The intent decides, whether or not the user names analogy or " +
+            "cross-domain search.\n" +
             "NOT for: in-domain literature review (use `pubmed` and the other " +
             "bio-lookup tools), single-gene factual lookup (use `search_gene`), or " +
             "execution-mode turns where the user just wants the next step done. It " +
-            "drives a multi-step research sub-agent over live literature search, so " +
-            "it is slow — never spend it on a fact you could look up.\n" +
+            "drives a multi-step research sub-agent (up to 40 model turns) over live " +
+            "literature search, so it is slow; a fact that one lookup answers does " +
+            "not need it.\n" +
             "RETURNS an AnalogyReport envelope the UI renders as an inline card. An " +
             "analogy the search could not fill carries a `coverage` tag " +
             "(`queried_no_data` | `search_failed` | `not_loaded`) with an empty " +
-            "`solutions` array — informational, NOT an error. A top-level `error` " +
-            "field means no report was produced: on `error.kind === " +
-            '"extraction-failed"` do NOT retry with the same or a similar problem ' +
-            "statement (the wrapper already salvaged the run one time — you would " +
-            "burn latency on the same failure). Surface the message and ask the " +
-            "user to narrow the problem.",
+            "`solutions` array — a partial result, not an error. A top-level `error` " +
+            'field with `kind: "extraction-failed"` means no report was produced: the ' +
+            "sub-agent found the problem empty or incoherent, failed, or ended with " +
+            "no report after one corrective request. `error.message` gives the cause. " +
+            "A retry with the same or a similar problem statement meets the same " +
+            "failure, thus surface the message and ask the user to narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
         describeCall: "none",
         execute: async (input, ctx) => {

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

@@ -340,7 +340,8 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
-            "success returns {accepted: true, planId} — STOP after this. On " +
+            "success returns {accepted: true, planId}, and an accepted call ends " +
+            "the planning session. On " +
             "rejection returns {accepted: false, issues} — fix and call again, " +
             "or switch to report_blocker if the plan cannot be made valid. This " +
             "arg schema is the authoritative plan contract.",
@@ -421,11 +422,12 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
     const requestClarificationTool = defineTool({
         id: "request_clarification",
         description: "Terminal. Use when a specific fact you need is missing from the " +
-            "input and cannot be inferred. Pass a short question and optional " +
-            "context. Stop after calling.",
+            "input and cannot be inferred. The question reaches the user through " +
+            "the conversation agent. A call ends the planning session with no " +
+            "plan saved.",
         inputSchema: z.object({
-            question: z.string().min(1),
-            questionContext: z.string().optional(),
+            question: z.string().min(1).describe("One short question that names each missing fact, and the step that needs it."),
+            questionContext: z.string().optional().describe("Optional context: why the plan needs the fact, and what the inputs already say about it."),
         }),
         describeCall: "none",
         execute: async (input) => {
@@ -698,8 +700,11 @@ export function createGeneratePlanTool(deps) {
             "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
             "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
             "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
-            "Returns a structured plan ready for show_plan and execute_analysis plan mode, or a clarification question if " +
-            "the planner is missing something it cannot infer.",
+            "The planner is a multi-step sub-agent, thus a call can take many minutes. " +
+            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved and ready for show_plan and " +
+            "execute_analysis plan mode, and this call neither shows nor runs it; `clarification_needed` with {question, questionContext?} " +
+            "when the planner is missing a fact it cannot infer; or `error` with {error} when no plan was saved (the planner reported " +
+            "a blocker, the save failed, the call timed out or was cancelled, or parentPlanId is not a plan of this analysis).",
         inputSchema: z.object({
             researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
             analystNotes: z

package/dist/tools/research/inspect-data-profile.js

@@ -93,13 +93,14 @@ const FAILURE_SCOPE_NOTE = "This records an earlier attempt; this row cannot est
 export function createInspectDataProfileTool(pool) {
     return defineTool({
         id: "inspect_data_profile",
-        description: "Read this analysis's data profile — the AUTHORITATIVE record of what the input dataset is: " +
+        description: "Read this analysis's data profile — the authoritative record of what the input dataset is: " +
             "organism and taxon id, scientific domain and subtype, tissue, cell type, condition, experimental design, " +
-            "dataset-wide caveats, public accessions, the GROUPS of file the dataset is made of, the DIMENSIONS that vary " +
+            "dataset-wide caveats, public accessions, the groups of files the dataset is made of, the dimensions that vary " +
             "across it with the evidence behind each, and the file census (kept, unclassified, quarantined). " +
-            "There is NO data-profile file in the workspace — this tool is the only way to read it. Do not search for one, " +
+            "There is no data-profile file in the workspace — this tool is the only way to read it. Do not search for one, " +
             "and do not rediscover these facts by listing or reading the raw input files. " +
-            "Call it before you reason about the data (planning, writing analysis code, interpreting results). " +
+            "Call it when a question about the data (for planning, analysis code, or interpretation) is not answered by what " +
+            "you already hold; a step briefing already carries a projection of this profile. " +
             "scope:'overview' (the default) returns the dataset-level orientation plus the partition accounting — how many " +
             "files were kept, how many landed in no group, how many were quarantined — and how many members are described " +
             "individually. That last figure and the dataset's file count differ on purpose: a large dataset is described by " +
@@ -110,10 +111,11 @@ export function createInspectDataProfileTool(pool) {
             "scope:'files' returns the individually annotated members, paged: page (1-based, default 1) and pageSize (default 20, max 100), " +
             "always with the true total and hasMore, so you can see exactly what you have not read yet. " +
             "For the paths of files no record describes, use scope:'groups' for the structure and list the workspace tree for the paths. " +
+            "The file paths of scope:'files' and the display patterns of scope:'groups' are rooted at /{analysisId}/, thus they resolve from any working directory. " +
             "The state field says what you got: 'ready'; 'stale' (a profile is returned but may not describe the current " +
             "inputs — staleReason says why); 'pending' (profiling is still running); 'failed'; or 'absent' (never profiled, " +
             "or the analysis has no input files). " +
-            "A 'failed' state reports a PAST attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
+            "A 'failed' state reports a past attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
             "input files you are holding now, and this tool cannot tell you whether that attempt covered them. Compare failedAt " +
             "against when the input set last changed before you conclude anything: if the data moved since, say the profile " +
             "needs re-running rather than diagnosing the data itself.",

package/dist/tools/research/inspect-run.js

@@ -97,9 +97,13 @@ const inputSchema = z
 export function createInspectRunTool(pool, clock = systemClock) {
     return defineTool({
         id: "inspect_run",
-        description: "Inspect workflow runs for this analysis. Without a runId, returns an active-first paged list (running, suspended, then terminal history). " +
-            "With a runId, returns an explicit inspectionState and advertises output paths only after the run is terminal. " +
+        description: "Inspect workflow runs for this analysis. A run never posts its completion into the conversation; this tool is how you read it. " +
+            "Without a runId, returns an active-first paged list (running, suspended, then terminal history) with total and hasMore. " +
+            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the run does not progress until it is resumed); " +
+            "or terminal (run.status completed, partial, failed, or canceled). " +
+            "Output paths appear only on a terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
+            "A wait on the run that the caller itself runs inside returns at once with selfWaitPrevented. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
         inputSchema,
         // The two calls do different work: one inspects a named run, the other

package/dist/tools/research/literature-reviewer.js

@@ -58,12 +58,17 @@ export function createLiteratureReviewerTool(deps) {
     };
     return defineTool({
         id: "literature_reviewer",
-        description: "Delegate batch literature/biology research: looking up multiple " +
-            "genes or pathways, validating findings against published knowledge, " +
-            "or building evidence profiles. Pass a self-contained brief — the " +
-            "reviewer has no access to this conversation. Returns a structured " +
-            "evidence report. Do NOT delegate simple single-gene lookups; handle " +
-            "those directly with your own bio-lookup tools.",
+        description: "Delegate batch literature/biology research to a sub-agent: looking up " +
+            "multiple genes or pathways, validating findings against published " +
+            "knowledge, or building evidence profiles. The reviewer holds gene, " +
+            "protein, annotation, interaction, PubMed, citation-verification, " +
+            "drug-gene and preclinical-profile lookups. It cannot see this " +
+            "conversation, the workspace, or the analysis files, thus pass a " +
+            "self-contained brief. One call runs a multi-step research loop of up " +
+            "to 30 model turns. Returns {report}: a Markdown evidence report with " +
+            "an evidence summary per target, cross-target patterns, and key " +
+            "references with PMIDs. A run that ends with no report returns a " +
+            "retryable error that names the finish reason.",
         inputSchema: z.object({
             brief: z
                 .string()

package/dist/tools/research/search-arxiv.js

@@ -20,7 +20,8 @@ export const searchArxivTool = defineTool({
         categories: z
             .array(z.string())
             .optional()
-            .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). ' + "Combined with the query using AND."),
+            .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). A paper matches when it carries any one of them, ' +
+            "and that filter is combined with the query using AND."),
         limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
     }),
     describeCall: "none",

package/dist/tools/research/search-github-repos.js

@@ -54,10 +54,16 @@ export function createSearchGithubReposTool(deps) {
     return defineTool({
         id: "search_github_repos",
         description: "Search GitHub for code repositories matching a free-text query, " +
-            "optionally filtered by programming language. Returns URL, full " +
+            "optionally filtered by programming language. Results are sorted by " +
+            "star count, highest first, not by relevance. Returns URL, full " +
             "name (owner/repo), description, star count, primary language, " +
-            "and last-updated timestamp. Use to find implementations of " +
-            "cross-domain methods cited in analogical-reasoning results.",
+            "and last-updated timestamp; description and language are absent " +
+            "when GitHub holds none. Use to find a published implementation of " +
+            "a method or a pipeline.\n" +
+            "ABSENCE IS NORMAL: an empty repos array means no repository matched, " +
+            "and `success: false` with an `error` string means GitHub could not be " +
+            "reached or refused the request (the low unauthenticated rate limit " +
+            "lands here). Report either one and continue, do not retry unchanged.",
         inputSchema: z.object({
             query: z
                 .string()

package/dist/tools/sandbox/list-available-refs.js

@@ -61,7 +61,7 @@ const ListAvailableRefsInputSchema = z.object({
         .string()
         .max(MAX_INPUT_PATH_BYTES)
         .optional()
-        .describe('Shorthand for a top-level group to inspect (e.g. "atlas_singlecell", "msigdb"); the groups present come back in `categories`. Ignored when `path` is given.'),
+        .describe("The name of a top-level directory of the store to inspect, the same as `path` with one segment. A label in `categories` that is not a directory reads as `not_found`; pass such a label as `query`. Ignored when `path` is given."),
     query: z
         .string()
         .optional()
@@ -512,7 +512,8 @@ export function createListAvailableRefsTool(deps) {
             "Results are ALWAYS bounded — prefer a targeted query over a full dump: " +
             '`query` is the main entry point, a case-insensitive substring filter over each entry\'s path and its dataset/title/category/organism/format/contents labels (e.g. "regulon", "hallmark", "mouse"); ' +
             "`path` inspects one directory beneath /mnt/refs (a returned path, or store-relative) — drill in with it when a listing is truncated; " +
-            '`category` is shorthand for a top-level group (e.g. "pathways", "regulatory-networks"), and the groups present come back in `categories`; ' +
+            '`categories` in the response lists the top-level directory names and the dataset group labels (for example "pathways") present; ' +
+            "pass a group label as `query`, because `category` inspects a top-level directory by name and a label that is not a directory reads as `not_found`; " +
             "`limit` caps the entries returned. The response carries `returned`, `total`, and `hasMore`, so truncation is never silent. " +
             "An empty result means the dataset is absent right now — not that it is unobtainable. Say so; never guess a path, and never silently substitute a different dataset. " +
             "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path, and whatever is added shows up on a later call.",

package/dist/tools/sandbox/report-blocker.js

@@ -28,7 +28,12 @@ export function createBlockerHolder() {
     return { outcome: null };
 }
 /** The one input every `report_blocker` takes, wherever it is offered. */
-const ReportBlockerInputSchema = z.object({ reason: z.string().min(1) });
+const ReportBlockerInputSchema = z.object({
+    reason: z
+        .string()
+        .min(1)
+        .describe("What blocks the work, stated as a fact: the missing or unreadable input, or the capability that is not available, and what you tried."),
+});
 /**
  * Build the `report_blocker` tool for one loop. The id, the input schema and
  * the terminal contract ("pass a reason, then stop") are fixed here; the call

package/dist/tools/sandbox/skills.js

@@ -48,8 +48,10 @@ export function createSkillTools(deps) {
         id: "skill_search",
         description: "Search your skills (method decision trees, API references, worked " +
             "examples) by keyword. Start here when picking a method or verifying an " +
-            "API detail. Returns matching skill files with a line snippet — then " +
-            "`skill_read` the file. No matches returns a data variant.",
+            "API detail. The query splits on whitespace into words, and each word matches as a " +
+            "case-insensitive substring. Returns one entry per matching skill file — its skill, its path, " +
+            "and the first line that holds a query word — ranked by how many distinct query words the file " +
+            "holds. Then `skill_read` the file. No matches returns a data variant.",
         inputSchema: z.object({
             query: z.string().min(1).describe("Keywords to match (e.g. 'PyDESeq2 contrast syntax')."),
             topK: z.number().int().min(1).max(MAX_TOP_K).optional().describe(`Max results to return. Defaults to ${DEFAULT_TOP_K}.`),

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

@@ -127,7 +127,10 @@ export function createStartReportSessionTool(deps) {
             "Keep the whole brief under approximately 2000 tokens. " +
             "When the conversation holds no user turn of new work after the last report session, the tool " +
             "starts nothing and it names that session. The ask that started that session is not new work. " +
-            "Then tell the user to continue in that chat.",
+            "Then tell the user to continue in that chat. " +
+            "The result `outcome` is `started` or `existing-session` with the `threadId` of the report chat. " +
+            "`no_browser` means that this deployment has no browser for the report agent, thus no report session can start; tell the user. " +
+            "`refused`, `parent_not_found`, `parent_not_a_conversation`, and `failed` mean that nothing started, and `detail` gives the reason where there is one.",
         inputSchema: startReportSessionInput,
         executionMode: "inline",
         describeCall: "none",

package/dist/tools/workspace/edit-file.js

@@ -116,9 +116,10 @@ export function createEditFileTool(deps) {
             "(default), old_string must occur exactly once. For a bulk pattern " +
             "edit set regex=true: old_string is a JS regex, new_string may use $1 " +
             "references, and exactly one of replace_all=true or expected_matches " +
-            "gates the write. Returns `out_of_prefix` / `out_of_scope` / " +
-            "`file_not_found` / `not_found` / `not_unique` / `match_count_mismatch` " +
-            "data variants — never throws on expected outcomes.",
+            "gates the write. Returns `out_of_prefix` / `out_of_scope` / `symlink_denied` / " +
+            "`file_not_found` / `not_found` / `not_unique` / `match_count_mismatch` / " +
+            "`invalid_pattern` / `invalid_arguments` data variants — never throws on expected outcomes. " +
+            "A data variant other than `ok` writes nothing.",
         inputSchema: EditFileInputSchema,
         // The path only. The replaced text is file content, not a description.
         describeCall: ({ path }) => path,

package/dist/tools/workspace/execute-command.js

@@ -61,11 +61,12 @@ export function createExecuteCommandTool(deps) {
             `tools don't express. stdout and stderr are each capped at ${EXEC_STREAM_BYTE_CAP / (1024 * 1024)} MiB; the end ` +
             "of a longer stream is dropped, and the result carries its truncation flag. A long result comes back as an " +
             "excerpt of its start and its end, with a reference to read the rest when the harness keeps it. " +
-            "Failures are returned as data, " +
-            "not thrown. stdout/stderr are EPHEMERAL and are NOT a deliverable — use " +
-            "this to confirm a command ran, not to produce results. Do NOT compute " +
-            "analysis results via 'python -c' / inline one-liners and read them from " +
-            "stdout; that work is lost. Write a script and persist its outputs to output/.",
+            "Failures are returned as data, not thrown: `status` is `ok` whenever the call completed, so read " +
+            "`exitCode` for the outcome of the command. `timedOut: true` means the timeout stopped the command, and a " +
+            "`syntheticFailure` with `exitCode: null` means the sandbox died under the command (its reason names an " +
+            "out-of-memory kill). stdout and stderr are not a deliverable: they are ephemeral, " +
+            "so use them to confirm that a command ran. A result that you compute with 'python -c' or an inline " +
+            "one-liner and read from stdout is lost. Write a script and persist its outputs to output/.",
         inputSchema: ExecuteCommandInputSchema,
         // The script is what a reader recognises, and it survives a long
         // invocation whose flags would otherwise push it past the length cap.

package/dist/tools/workspace/grep.js

@@ -21,7 +21,8 @@ const GrepInputSchema = z.object({
     pattern: z
         .string()
         .min(1)
-        .describe("Regular expression to match. Anchored per line; case-sensitive unless " + "`ignoreCase` is true."),
+        .describe("JavaScript regular expression, tested against each line separately. It matches anywhere in the line " +
+        "unless you add `^` or `$`; case-sensitive unless `ignoreCase` is true."),
     path: z
         .string()
         .min(1)
@@ -31,12 +32,13 @@ const GrepInputSchema = z.object({
 export function createGrepTool(fs, workingDir) {
     return defineTool({
         id: "grep",
-        description: "Regex search over workspace files (input data, prior runs, step " +
-            "outputs, summaries, syntheses, data profile). Pass a file or a " +
-            "directory path; directories are walked recursively. Results are " +
-            `capped at ${DEFAULT_MAX_MATCHES} matches and ${DEFAULT_MAX_MATCH_BYTES} ` +
-            "bytes per line — narrow your path or pattern if you hit the cap. " +
-            "No matches and out-of-scope paths return data variants, not errors.",
+        description: "Regex search over the text files of the workspace (input data, prior runs, step " +
+            "outputs, summaries, syntheses). Pass a file or a " +
+            `directory path; directories are walked recursively, to a depth of ${MAX_DIR_DEPTH}. Results are ` +
+            `capped at ${DEFAULT_MAX_MATCHES} matches, and each preview at ${DEFAULT_MAX_MATCH_BYTES} characters of its line. ` +
+            `Only the first ${MAX_GREP_FILE_BYTES / (1024 * 1024)} MiB of each file is searched, and a file with a NUL byte ` +
+            "in its first KiB is skipped as binary. A `truncated` status means the match cap or the file cap cut the search; " +
+            "narrow your path or pattern. No matches, missing paths, and out-of-scope paths return data variants, not errors.",
         inputSchema: GrepInputSchema,
         // Both fields, because either alone loses the call: the same pattern over
         // two trees and two patterns over one tree are both ordinary sequences.

package/dist/tools/workspace/list-files.js

@@ -20,7 +20,7 @@ export function createListFilesTool(fs, workingDir) {
     return defineTool({
         id: "list_files",
         description: "List the entries (files and directories, with file sizes) in a directory of the analysis's " +
-            "own workspace tree. Faster than `ls` via execute_command. Its scope is that tree and nothing " +
+            "own workspace tree. It reads the tree directly and runs no sandbox command. It does not recurse. Its scope is that tree and nothing " +
             "else: it never reaches a directory outside the analysis, including the host process's current " +
             "working directory. Missing and out-of-scope paths return a data variant, not an error.",
         inputSchema: ListFilesInputSchema,

package/dist/tools/workspace/read-file.js

@@ -57,7 +57,8 @@ export function createReadFileTool(fs, workingDir) {
             "as UTF-8 text. Output is capped at " +
             `${DEFAULT_MAX_BYTES} bytes; pass headLines or tailLines to read a ` +
             "specific window of a large file (typical for bio CSV/TSV/log files). " +
-            "Oversize reads come back truncated with a marker. This tool is for " +
+            "An oversize read returns status `truncated` with the bytes that fit (the start of the file, or " +
+            "the end for tailLines), `totalSize`, and `returnedBytes`. This tool is for " +
             "text; a binary file (one holding NUL bytes, e.g. a .gz or image) comes " +
             "back as a `binary` data variant rather than decoded garbage. Missing " +
             "paths and paths outside the analysis tree return a data variant — not an error.",

package/dist/tools/workspace/scan-inputs.js

@@ -23,7 +23,9 @@ export function createScanInputsTool(deps) {
             "the shapes its filenames form (sets of files whose names differ only at marked positions), " +
             "the distinct values each varying position takes, how those positions co-occur, value overlap " +
             "between shapes, and the files that share structure with nothing else. " +
-            "Deterministic — no model, no per-file decoding — so it costs the same on three files as on three thousand. " +
+            "It also reads the header of one member file for each shape (magic bytes, a preamble, a header row, or a container index). " +
+            "Deterministic — no model — and the manifest it returns is bounded, so it costs the same context on three files as on three thousand. " +
+            "The walk stops at a ceiling of files; a manifest marked INCOMPLETE describes part of the subtree, so scan a narrower path. " +
             "Your briefing already carries a scan of the whole input tree; call this to look at a subtree more closely, " +
             "or to check a grouping you are unsure about. " +
             "It reports observations only: which files are one KIND of data, and what a varying position MEANS, are yours to decide.",

package/dist/tools/workspace/show-file.js

@@ -25,7 +25,7 @@ const ShowFileInputSchema = z.object({
     }))
         .min(1)
         .max(MAX_FILES)
-        .describe(`The related set of files to show together, 1 to ${MAX_FILES} per call; multiple render as ONE gallery card. Pass a related set in a single call — do not make one call per figure.`),
+        .describe(`The files to show together, 1 to ${MAX_FILES} per call; multiple render as ONE gallery card. Pass all the figures that one prose section discusses in a single call. Figures for different sections go in separate calls.`),
 });
 export const showFileTool = defineTool({
     id: "show_file",
@@ -34,8 +34,11 @@ export const showFileTool = defineTool({
         "inline, or paste the bytes. Pick this tool by what you are referencing, not by how the output looks: " +
         "NOT for content you synthesized (a chart, a table, a snippet you invented — use `show_user`), NOT for a stored plan (`show_plan`). " +
         "Paths are analysis-rooted (no leading slash, no `..`); discover them with `workspace_search` or `list_files`. " +
-        "Up to 10 files per call — pass a related set in ONE call and they render as a gallery, rather than one call per figure. " +
-        "Cards render in call order, so to interleave figures with prose alternate `show_user(markdown)` and `show_file` calls " +
+        "The tool checks the shape of each path only, not that the file exists, so a wrong path fails only when the user views the card; " +
+        "`shown: false` with `invalid_path` means a path has a leading slash or a `..` segment. " +
+        "Up to 10 files per call, rendered as one gallery — pass all the figures that one prose section discusses in ONE call. " +
+        "Cards render in call order, so to put figures next to their prose, emit `show_user(markdown)` sections and `show_file` " +
+        "calls in one batch, in reading order: a section, then the `show_file` for its figures, then the next section " +
         "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",
     inputSchema: ShowFileInputSchema,
     // `.min(1)` on `files` makes index 0 total after the parse.

package/dist/tools/workspace/workspace-search.js

@@ -53,7 +53,9 @@ export function createWorkspaceSearchTool(pool, embedding) {
     return defineTool({
         id: "workspace_search",
         description: "Semantic search over the analysis workspace. Returns ranked entries with descriptions " +
-            "and metadata; read a file separately to see its contents. `type` restricts results to one " +
+            "and metadata; read a file separately to see its contents. The nearest entries always come back, up to " +
+            "`limit`, with no relevance cut: `score` is the cosine similarity to the query, and a low score is a weak match, " +
+            "not a hit. An empty `results` list means that nothing of that type is indexed yet. `type` restricts results to one " +
             'entry type: "input-group" (a GROUP of input data the data profiler declared, carrying its ' +
             'derived count, its display pattern, and its slots), "input-dimension" (something that VARIES ' +
             "across the dataset — subject, timepoint, batch — with the observations evidencing it), " +

package/dist/tools/workspace/write-file.js

@@ -25,9 +25,11 @@ export function createWriteFileTool(deps) {
         // body runs unwrapped in the workflow body (see the harness-tools spec).
         executionMode: "workflow",
         description: "Write a UTF-8 text file in your working directory. Relative paths " +
-            "resolve against it; a path outside it returns an `out_of_prefix` data " +
-            "variant (no I/O), and one escaping the analysis tree returns " +
-            "`out_of_scope`.",
+            "resolve against it. The write replaces an existing file whole, and it makes " +
+            "missing parent directories. On success it returns `status: ok`, the absolute " +
+            "'/<analysisId>/...' path, and `bytesWritten`. A path outside the working directory " +
+            "returns an `out_of_prefix` data variant (no I/O), one escaping the analysis tree returns " +
+            "`out_of_scope`, and a symbolic link on the path returns `symlink_denied`.",
         inputSchema: WriteFileInputSchema,
         // The path only. `content` is a whole file and must never ride a display
         // channel, which the emit-site length cap enforces regardless.

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

@@ -76,6 +76,8 @@ import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.js";
+import { type StepBriefing } from "../prompts/briefing.js";
+import type { WorkingMemoryStore } from "../memory/working-memory.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -248,6 +250,11 @@ export interface ExecuteAnalysisDeps {
     readonly usageRecorder?: UsageRecorder;
     /** The store of the loops of the run synthesis and of their read tools. */
     readonly toolOutputStore?: ToolOutputStore;
+    /**
+     * The working memory of the analysis. The body only reads it: each step seed
+     * carries the goal and the constraints as they are at the dispatch of that step.
+     */
+    readonly workingMemory: WorkingMemoryStore;
     /**
      * The provenance seam of the composition. The body reads its run emit member,
      * and it reads no other member.
@@ -309,11 +316,6 @@ export declare function buildChildInput(args: {
  * rendered any earlier (at plan submission, say) cannot mention them, and the
  * agent is left to rediscover its own upstream.
  *
- * Everything read here is durable state written by an already-settled child
- * (`output/summary.md`, `cortex_artifacts`) or by the profiler
- * (`cortex_analysis_state`) — never live in-flight state, which would not
- * reproduce.
- *
  * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
  * checkpointed and a replay returns it verbatim — the DB and disk are not read
  * again and cannot drift the seed under a recovered run. Never call it
@@ -325,6 +327,27 @@ export declare function composeStepSeed(args: {
     runId: string;
     deps: ExecuteAnalysisDeps;
 }): Promise<string>;
+/**
+ * Do every read of one step's package and give the data its seed is rendered
+ * from. All reads live here, so `composeStepBriefing` stays a pure renderer.
+ *
+ * Everything read is durable state: written by an already-settled child
+ * (`output/summary.md`, `cortex_artifacts`), by the profiler
+ * (`cortex_analysis_state`), or by the conversation agent
+ * (`cortex_working_memory`). The working memory is the one read that can
+ * change while the run is live — it is read per dispatch, not once per run,
+ * so an edit during a run reaches each later step, and two steps of one run
+ * can carry different copies.
+ *
+ * A read failure throws (house rules): a swallowed error would be frozen into
+ * the checkpointed seed and served to every replay of this step.
+ */
+export declare function gatherStepPackage(args: {
+    input: ExecuteAnalysisInput;
+    stepId: string;
+    runId: string;
+    deps: ExecuteAnalysisDeps;
+}): Promise<StepBriefing>;
 /**
  * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
  * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps