@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/tools/sandbox/report-blocker.d.ts

@@ -1,14 +1,19 @@
 /**
- * `report_blocker` — a step agent's honest exit when it cannot fulfil its
- * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
- * its persisted files, so a clean end-of-turn after writing them is the
- * implicit success. Calling `report_blocker` is the alternative to
- * improvising an inline result the harness would launder into a green run.
+ * `report_blocker` — an agent's honest exit when it cannot fulfil the loop it
+ * is driving (see the harness-sandbox-agents spec). There is no `submit`/`done`
+ * tool on a sandbox step: a step's deliverable is its persisted files, so a
+ * clean end-of-turn after writing them is the implicit success. Calling
+ * `report_blocker` is the alternative to improvising an inline result the
+ * harness would launder into a green run.
  *
- * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
- * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
- * after `runAgent`. The tool only records the reason and tells the agent to
- * stop — the body decides the terminal status.
+ * This module is the canonical home of the tool. Three loops offer it — the
+ * sandbox step agent, the planner (`tools/research/generate-plan.ts`) and the
+ * run synthesizer (`execution/run-synthesis.ts`) — and all three share one id,
+ * one input schema and one terminal contract via `createReportBlockerToolFor`.
+ * What differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose and its own capture closure. The tool
+ * records the reason and tells the agent to stop; the driving body reads its
+ * own outcome cell after the loop and decides the terminal status.
  */
 import { type Tool } from "../define-tool.js";
 export interface BlockerOutcome {
@@ -20,4 +25,29 @@ export interface BlockerHolder {
     outcome: BlockerOutcome | null;
 }
 export declare function createBlockerHolder(): BlockerHolder;
+export interface ReportBlockerDeps {
+    /**
+     * The calling loop's blocker-capture side effect — writes the outcome into
+     * whatever cell that body reads after its loop. Invoked on every call; the
+     * closure owns the first-call-wins guard, because only the call site knows
+     * what else may already have terminated its loop.
+     */
+    readonly record: (outcome: BlockerOutcome) => void;
+    /**
+     * What a blocker means in THIS loop: which loop the call ends and the
+     * conditions that warrant it. Composed into the shared terminal contract,
+     * so a description can never promise a loop this instance does not end.
+     */
+    readonly blockedWhen: string;
+}
+/**
+ * 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
+ * site supplies only the per-loop meaning and the capture closure.
+ */
+export declare function createReportBlockerToolFor(deps: ReportBlockerDeps): Tool;
+/**
+ * The sandbox step agent's `report_blocker`, bound to the step body's holder.
+ * A blocker here ends the step with no deliverables and a blocked reason.
+ */
 export declare function createReportBlockerTool(holder: BlockerHolder): Tool;

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

@@ -1,14 +1,19 @@
 /**
- * `report_blocker` — a step agent's honest exit when it cannot fulfil its
- * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
- * its persisted files, so a clean end-of-turn after writing them is the
- * implicit success. Calling `report_blocker` is the alternative to
- * improvising an inline result the harness would launder into a green run.
+ * `report_blocker` — an agent's honest exit when it cannot fulfil the loop it
+ * is driving (see the harness-sandbox-agents spec). There is no `submit`/`done`
+ * tool on a sandbox step: a step's deliverable is its persisted files, so a
+ * clean end-of-turn after writing them is the implicit success. Calling
+ * `report_blocker` is the alternative to improvising an inline result the
+ * harness would launder into a green run.
  *
- * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
- * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
- * after `runAgent`. The tool only records the reason and tells the agent to
- * stop — the body decides the terminal status.
+ * This module is the canonical home of the tool. Three loops offer it — the
+ * sandbox step agent, the planner (`tools/research/generate-plan.ts`) and the
+ * run synthesizer (`execution/run-synthesis.ts`) — and all three share one id,
+ * one input schema and one terminal contract via `createReportBlockerToolFor`.
+ * What differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose and its own capture closure. The tool
+ * records the reason and tells the agent to stop; the driving body reads its
+ * own outcome cell after the loop and decides the terminal status.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -16,20 +21,20 @@ import { defineTool } from "../define-tool.js";
 export function createBlockerHolder() {
     return { outcome: null };
 }
-export function createReportBlockerTool(holder) {
+/** The one input every `report_blocker` takes, wherever it is offered. */
+const ReportBlockerInputSchema = z.object({ reason: z.string().min(1) });
+/**
+ * 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
+ * site supplies only the per-loop meaning and the capture closure.
+ */
+export function createReportBlockerToolFor(deps) {
     return defineTool({
         id: "report_blocker",
-        description: "Terminal. Call this when you cannot fulfil the step — required inputs " +
-            "are missing or unreadable, the requested analysis is infeasible with " +
-            "the available data/packages, or you cannot produce the persisted " +
-            "deliverables (scripts, output files, figures). Pass a clear reason. Do " +
-            "NOT improvise an inline result and narrate it; if you cannot persist " +
-            "real output files, report a blocker. Stop after calling.",
-        inputSchema: z.object({ reason: z.string().min(1) }),
+        description: `Terminal. ${deps.blockedWhen} Pass a clear reason. Stop immediately after calling — take no further actions.`,
+        inputSchema: ReportBlockerInputSchema,
         execute: async (input) => {
-            if (holder.outcome === null) {
-                holder.outcome = { kind: "blocker", reason: input.reason };
-            }
+            deps.record({ kind: "blocker", reason: input.reason });
             return ok({
                 recorded: true,
                 message: "Blocker recorded. You are done — stop now and do not take further actions.",
@@ -37,3 +42,21 @@ export function createReportBlockerTool(holder) {
         },
     });
 }
+/**
+ * The sandbox step agent's `report_blocker`, bound to the step body's holder.
+ * A blocker here ends the step with no deliverables and a blocked reason.
+ */
+export function createReportBlockerTool(holder) {
+    return createReportBlockerToolFor({
+        record: (outcome) => {
+            if (holder.outcome === null)
+                holder.outcome = outcome;
+        },
+        blockedWhen: "Ends this analysis step with no deliverables. Call it when you cannot " +
+            "fulfil the step — required inputs are missing or unreadable, the " +
+            "requested analysis is infeasible with the available data/packages, or " +
+            "you cannot produce the persisted deliverables (scripts, output files, " +
+            "figures). Do NOT improvise an inline result and narrate it: if you " +
+            "cannot persist real output files, report a blocker.",
+    });
+}

package/dist/tools/workspace/execute-command.d.ts

@@ -22,7 +22,10 @@
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { SandboxRef } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
+import type { Logger } from "../../lib/logger.js";
 export interface ExecuteCommandDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly sandboxClient: SandboxClient;
     /** Live sandbox handle for the step. Created once per step at composition root. */
     readonly sandbox: SandboxRef;

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

@@ -26,6 +26,7 @@ import { defineTool } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
 import { boundExecResult } from "./result-bounds.js";
 import { runSandboxExec } from "./run-exec.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
 const ExecuteCommandInputSchema = z.object({
     command: z
         .array(z.string().min(1))
@@ -86,7 +87,8 @@ export function createExecuteCommandTool(deps) {
                     });
                 }
                 catch (err) {
-                    console.warn(`[execute_command] provenance frame handling failed (non-fatal) for ${execId}: ${err instanceof Error ? err.message : err}`);
+                    const logger = (deps.logger ?? createNoopLogger()).named("execute_command");
+                    logger.warn("provenance frame handling failed (non-fatal)", { execId, ...logger.errorFields(err) });
                 }
             }
             return ok({ status: "ok", ...boundExecResult(result) });

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

@@ -19,8 +19,7 @@ const ReadFileInputSchema = z.object({
         .min(1)
         .describe("Workspace path. Relative paths resolve against your working directory; " +
         "an absolute '/<analysisId>/...' path is resolved against the analysis " +
-        "root (use absolute to read input data, the data profile, or other " +
-        "steps' outputs)."),
+        "root (use absolute to read input data or other steps' outputs)."),
     headLines: z
         .number()
         .int()
@@ -28,7 +27,7 @@ const ReadFileInputSchema = z.object({
         .max(10_000)
         .optional()
         .describe("Read only the first N lines (head). Use for inspecting CSV/TSV " +
-        "headers, profile summaries, or the top of any large file. Mutually " +
+        "headers, step summaries, or the top of any large file. Mutually " +
         "exclusive with tailLines."),
     tailLines: z
         .number()
@@ -42,8 +41,8 @@ export function createReadFileTool(fs, workingDir) {
     return defineTool({
         id: "read_file",
         description: "Read a workspace file: input data, prior-run outputs, current-run " +
-            "outputs, step summaries, run syntheses, or the data profile. Returns " +
-            "the file content as UTF-8 text. Output is capped at " +
+            "outputs, step summaries, or run syntheses. Returns the file content " +
+            "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. Missing paths and " +

package/dist/tools/workspace/run-exec.d.ts

@@ -1,10 +1,10 @@
 /**
- * Internal helper used by the three mutate tools to drive one sandbox exec
+ * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
  * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint — the contract `execute_command` makes structural is that
- * `write_file` / `edit_file` are layered on top of it, not parallel side
- * paths into sandbox-server.
+ * one chokepoint. `write_file` / `edit_file` are layered on the workspace
+ * mutator and environment introspection tools such as `list_available_refs`
+ * use this same replay-safe submit/await path rather than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
  * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.

package/dist/tools/workspace/run-exec.js

@@ -1,10 +1,10 @@
 /**
- * Internal helper used by the three mutate tools to drive one sandbox exec
+ * Internal helper used by dependency-bearing tools to drive one sandbox exec
  * through the `SandboxClient`. Centralises the submit/await pair, exec-id
  * derivation, and intermediate-event forwarding so all three tools share
- * one chokepoint — the contract `execute_command` makes structural is that
- * `write_file` / `edit_file` are layered on top of it, not parallel side
- * paths into sandbox-server.
+ * one chokepoint. `write_file` / `edit_file` are layered on the workspace
+ * mutator and environment introspection tools such as `list_available_refs`
+ * use this same replay-safe submit/await path rather than a parallel protocol.
  *
  * Not a registered tool — `defineTool` is called by the user-facing tools
  * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.

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

@@ -20,19 +20,23 @@ const ShowFileInputSchema = z.object({
     title: z.string().optional().describe("Group heading shown above the card or gallery"),
     files: z
         .array(z.object({
-        path: z.string().describe("Analysis-rooted file path (e.g., 'runs/run-abc/step-1/figures/volcano.png')"),
+        path: z.string().describe("Analysis-rooted file path — no leading slash, no `..` (e.g., 'runs/run-abc/step-1/figures/volcano.png')"),
         caption: z.string().optional().describe("One-sentence context rendered beside this file"),
     }))
         .min(1)
         .max(MAX_FILES)
-        .describe(`1 to ${MAX_FILES} files; multiple files render as a gallery`),
+        .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.`),
 });
 export const showFileTool = defineTool({
     id: "show_file",
-    description: "Display one or more existing analysis artifacts (images, CSVs, PDFs, notebooks, logs) in chat by path. " +
-        "Paths must be analysis-rooted (no leading slash, no `..`). Up to 10 files per call — multiple render as a gallery. " +
-        "Do NOT read a file and paste its bytes elsewhere; this tool references the file directly. " +
-        "File content is fetched when the user views the card — you do not need to provide it.",
+    description: "Display EXISTING analysis artifacts in chat by path — images, CSVs, PDFs, notebooks, logs. " +
+        "The card references the file directly and its content is fetched when the user views it: you never read, " +
+        "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 " +
+        "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",
     inputSchema: ShowFileInputSchema,
     execute: async (input, ctx) => {
         const card = buildFileReferenceCardData(input);

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

@@ -18,13 +18,19 @@ const PLAN_ID_REGEX = /^pln-[a-f0-9]{8}$/;
 export function createShowPlanTool(pool) {
     return defineTool({
         id: "show_plan",
-        description: "Display a previously generated plan in chat by its planId. " +
-            "Use when the user asks to see a plan again, or to reference a historical plan. " +
-            "Get planIds from `inspect-run` (each run carries its planId) or `generatePlan` (newly created). " +
-            "The plan content is embedded in the chat part so the UI renders it directly.",
+        description: "Display a STORED plan in chat by its planId. The plan is loaded from storage and embedded in the card, " +
+            "so the UI renders it directly. Use it to present the plan `generate_plan` just produced, and when the user " +
+            "asks to see an earlier plan again. " +
+            "Pick this tool by what you are referencing, not by how the output looks: " +
+            "NOT for a plan you are drafting in conversation (that is `generate_plan`), NOT for other synthesized content " +
+            "(`show_user`), NOT for analysis files (`show_file`). Never re-type a plan's steps into a `show_user` markdown " +
+            "card — that renders a second, divergent copy of the same plan.",
         inputSchema: z.object({
-            planId: z.string().regex(PLAN_ID_REGEX, "planId must match pln-<8hex>").describe("Plan ID from generatePlan or inspect-run"),
-            title: z.string().optional().describe("Optional display heading"),
+            planId: z
+                .string()
+                .regex(PLAN_ID_REGEX, "planId must match pln-<8hex>")
+                .describe("Plan ID (`pln-<8hex>`) from `generate_plan` (newly created) or `inspect_run` (each run carries the planId it ran)"),
+            title: z.string().optional().describe("Optional card heading; defaults to the plan's own title"),
         }),
         execute: async ({ planId, title }, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;

package/dist/tools/workspace/workspace-search.d.ts

@@ -15,7 +15,7 @@ import type { EmbeddingProvider } from "../../providers/types.js";
 export declare function createWorkspaceSearchTool(pool: Pool, embedding: EmbeddingProvider): import("../define-tool.js").Tool<{
     query: string;
     limit: number;
-    type?: "output" | "input" | "summary" | "synthesis" | undefined;
+    type?: "output" | "input" | "synthesis" | "summary" | undefined;
 }, {
     results: {
         id: string;

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

@@ -32,13 +32,19 @@ function indexName(analysisId) {
 export function createWorkspaceSearchTool(pool, embedding) {
     return defineTool({
         id: "workspace_search",
-        description: "Semantic search over the analysis workspace — input data, analysis " +
-            "outputs, step summaries, run syntheses, and the data profile. Returns " +
-            "ranked file paths with descriptions and metadata; read a file " +
-            "separately to see its contents. Optionally filter by entry type.",
+        description: "Semantic search over the analysis workspace. Returns ranked file paths " +
+            "with descriptions and metadata; read a file separately to see its " +
+            "contents. Indexed entries are exactly four types, and `type` restricts " +
+            'results to one of them: "input" (staged input data files — their ' +
+            'descriptions come from the data profiler), "output" (files a step ' +
+            'produced), "summary" (a step\'s summary), "synthesis" (a run\'s ' +
+            "literature-grounded synthesis).",
         inputSchema: z.object({
             query: z.string().min(1).describe("What to search for, in natural language"),
-            type: z.enum(["input", "output", "summary", "synthesis"]).optional().describe("Restrict results to one workspace entry type"),
+            type: z
+                .enum(["input", "output", "summary", "synthesis"])
+                .optional()
+                .describe('Restrict results to one entry type: "input", "output", "summary", or "synthesis"'),
             limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
         }),
         execute: async ({ query, type, limit }, ctx) => {

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

@@ -20,6 +20,10 @@
  *     - dispatch every `scheduleReady(plan, completedSet, startedSet)` via
  *       `DBOS.startWorkflow` with deterministic child id
  *       `"${parent.workflowID}-${N}"` (N is the step's stable index)
+ *     - compose each child's seed prompt HERE, at dispatch (`composeStepSeed`,
+ *       inside a durable step): the moment a step is dispatched is the first
+ *       moment its dependencies' results exist, so this is the only place the
+ *       seed can name them
  *     - each child input is `forStep(input.runSession, stepId)` for the
  *       session field
  *     - emit `data-dag-state` (reconciling by id) on every dispatch +
@@ -53,6 +57,8 @@ import type { Pool } from "pg";
 import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { Logger } from "../lib/logger.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";
 import type { RunCharge } from "../billing/run-charge.js";
@@ -76,8 +82,15 @@ export interface ExecuteAnalysisInput {
     readonly steps: readonly PlanStep[];
     /** Optional thread id for cortex_runs.thread_id (UI breadcrumb only). */
     readonly threadId?: string | null;
-    /** Per-step prompt body the child workflow forwards to its agent. */
-    readonly promptByStepId: Readonly<Record<string, string>>;
+    /**
+     * The plan's steps, keyed by id — the instruction DATA each step's seed is
+     * composed FROM, not a pre-rendered prompt string. The seed itself is
+     * composed per step at dispatch (`composeStepSeed`), because that is the
+     * first moment a step's dependencies have produced anything to tell it
+     * about. Snapshotted here at the async edge so the body never re-reads the
+     * plan row (a mid-run plan edit cannot change a running run's instructions).
+     */
+    readonly planStepById: Readonly<Record<string, AnalysisStep>>;
     /** Per-step agent id (sandbox catalog entry). */
     readonly agentByStepId: Readonly<Record<string, string>>;
     /** Per-step planner-estimated sandbox resource request. */
@@ -194,6 +207,8 @@ export type RunProvenanceEvent = {
  * embedder, model, keys, roots) the in-body synthesis needs.
  */
 export interface ExecuteAnalysisDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     /** Chat provider for the in-body literature-grounded synthesis. */
     readonly provider: ChatProvider;
@@ -229,8 +244,9 @@ export interface ExecuteAnalysisDeps {
 }
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
- * level computation; the rest comes from `ExecuteAnalysisInput`. The body
- * fills in `runSession` via `forStep` after this returns. Exported for the
+ * level computation and the seed (`prompt`, composed by `composeStepSeed` at
+ * dispatch); the rest comes from `ExecuteAnalysisInput`. The body fills in
+ * `runSession` via `forStep` after this returns. Exported for the
  * projection/timeout-propagation tests.
  */
 export declare function buildChildInput(args: {
@@ -239,7 +255,33 @@ export declare function buildChildInput(args: {
     level: number;
     runId: string;
     workflowId: string;
+    prompt: string;
 }): Omit<SandboxStepInput, "runSession">;
+/**
+ * Compose one step's seed — the user-content message its agent opens on.
+ *
+ * The composition point is the design: the scheduler calls this at the instant
+ * it dispatches a step, which is the first instant at which every one of that
+ * step's dependencies has *finished* and written its results down. A seed
+ * 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 declare function composeStepSeed(args: {
+    input: ExecuteAnalysisInput;
+    stepId: string;
+    runId: string;
+    deps: ExecuteAnalysisDeps;
+}): Promise<string>;
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is