@inflexa-ai/harness 0.41.0 → 0.41.1

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

@@ -34,6 +34,8 @@ 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`. " +
+        "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 — 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 " +
         "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",

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

package/dist/workflows/execute-analysis.js

@@ -82,7 +82,7 @@ import { unwrapOrThrow } from "../lib/result.js";
 import { countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, queryStepsByRun, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { addChatUsage, hasReportedUsage } from "../loop/metrics.js";
 import { SYNTHESIS_AGENT_ID, loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
-import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing } from "../prompts/briefing.js";
+import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing, emptyStepMemory } from "../prompts/briefing.js";
 import { SYNTHESIS_STEP_ID, runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
 import { isChatDataPart } from "../sandbox/sandbox-step-translate.js";
 import { synthesizeRun } from "../app/synthesize-run.js";
@@ -220,17 +220,30 @@ export 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
  * unwrapped from the workflow body.
  */
 export async function composeStepSeed(args) {
+    return composeStepBriefing(await gatherStepPackage(args));
+}
+/**
+ * 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 async function gatherStepPackage(args) {
     const { input, stepId, runId, deps } = args;
     const step = input.planStepById[stepId];
     if (!step) {
@@ -246,9 +259,19 @@ export async function composeStepSeed(args) {
         analysisId,
         workingDir: toSandboxPath(workspaceRoot, analysisId, stepWritePrefix({ workspaceRoot, runId, stepId })),
     };
-    // A DB failure here throws (house rules): a swallowed error would be frozen
-    // into the checkpointed seed and served to every replay of this step.
     const profile = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
+    // A failed memory read leaves the section out: the step runs without the copy of the memory, not without a seed.
+    const memoryRead = await deps.workingMemory.load(analysisId);
+    if (memoryRead.isErr()) {
+        const log = (deps.logger ?? createNoopLogger()).named("executeAnalysis.seed");
+        log.warn("the working-memory read failed, thus the seed has no memory section", {
+            analysisId,
+            stepId,
+            error: describeDbError(memoryRead.error),
+            ...log.errorFields(memoryRead.error.cause),
+        });
+    }
+    const memory = memoryRead.isOk() ? memoryRead.value : emptyStepMemory();
     const upstream = await collectUpstreamHandoffs({
         analysisId,
         runId,
@@ -257,12 +280,13 @@ export async function composeStepSeed(args) {
         agentByStepId: input.agentByStepId,
         pool: deps.pool,
     });
-    return composeStepBriefing({
+    return {
         step,
         workspace,
         profile: profile?.result ?? null,
         upstream,
-    });
+        memory: { goal: memory.goal, constraints: memory.constraints },
+    };
 }
 /**
  * Gather what each completed dependency produced. Dependency order is the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.41.0",
+    "version": "0.41.1",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",