@inflexa-ai/harness 0.44.0 → 0.45.1

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

@@ -17,6 +17,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { noteScriptChange, scriptSha256 } from "./decision-record.js";
 const EditFileInputSchema = z.object({
     path: z
         .string()
@@ -172,6 +173,19 @@ export function createEditFileTool(deps) {
             });
             if (write.status !== "ok")
                 return ok(write);
+            // A rendered script carries a decision record. The edit is a change the curator did not vet, and the
+            // record keeps it with the digest after the change, thus an empty `unvetted_edits` stays a fact.
+            const noted = await noteScriptChange({
+                filesystem: deps.workspaceFilesystem,
+                mutator: deps.mutator,
+                session: ctx.session,
+                ...(deps.workingDir !== undefined ? { workingDir: deps.workingDir } : {}),
+                invocationId: ctx.invocationId,
+                toolName: "edit_file",
+                scriptPath: path,
+                note: `edit_file: ${replaced.replacements} replacement(s)`,
+                sha256: scriptSha256(replaced.content),
+            });
             const lines = replaced.lines;
             return ok(withToolCallRecord({
                 status: "ok",
@@ -179,8 +193,12 @@ export function createEditFileTool(deps) {
                 replacements: replaced.replacements,
                 bytesWritten: write.bytesWritten,
                 ...(lines === undefined ? {} : { lines }),
-            }, write.record));
+                ...(noted.status === "noted" ? { decision_record_noted: true } : {}),
+            }, noted.status === "noted" ? [write.record, noted.write] : [write.record]));
+        },
+        foldCallRecord: (records) => {
+            for (const record of records)
+                deps.mutator.recordWrite(record);
         },
-        foldCallRecord: (record) => deps.mutator.recordWrite(record),
     });
 }

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

@@ -18,12 +18,20 @@
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
  * The frame of each exec rides the call record, and the fold feeds it to the
  * lineage collector of the step.
+ *
+ * A script the command names that carries a decision record is compared
+ * with the digest the record expects before it runs. A difference is a
+ * change that no file tool recorded, and the record gets it with the digest
+ * of the bytes that run, thus the record connects the cited decision to the
+ * code that ran.
  */
 import { type WithToolCallRecord } from "../define-tool.js";
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { ProvenanceFrame, SandboxRef } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
+import type { WorkspaceMutator, WriteRecord } from "./mutator.js";
 import { type BoundedExecResult } from "./result-bounds.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { Logger } from "../../lib/logger.js";
 /** What one exec leaves for the lineage collector of the step. */
 interface ExecCallRecord {
@@ -31,6 +39,8 @@ interface ExecCallRecord {
     readonly exitCode: number | null;
     readonly durationMs: number | null;
     readonly provenance?: ProvenanceFrame;
+    /** The decision-record writes of the script check before the exec, for the mutator. */
+    readonly recordWrites?: readonly WriteRecord[];
 }
 type ExecuteCommandResult = {
     readonly status: "ok";
@@ -58,6 +68,13 @@ export interface ExecuteCommandDeps {
     readonly lineageCollector?: ProvenanceCollector;
     /** Analysis resource mount root (`/{resourceId}`) — strips frame paths to relative. */
     readonly mountRoot?: string;
+    /**
+     * The workspace filesystem and the mutator of the step, for the record check of a
+     * script the command runs. Both absent (a read-only agent), no record is
+     * read or written.
+     */
+    readonly workspaceFilesystem?: WorkspaceFilesystem;
+    readonly mutator?: WorkspaceMutator;
 }
 export declare function createExecuteCommandTool(deps: ExecuteCommandDeps): import("../define-tool.js").Tool<{
     command: string[];

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

@@ -18,12 +18,19 @@
  * `sandbox-provenance-tracking`), and artifact registration reconciles them.
  * The frame of each exec rides the call record, and the fold feeds it to the
  * lineage collector of the step.
+ *
+ * A script the command names that carries a decision record is compared
+ * with the digest the record expects before it runs. A difference is a
+ * change that no file tool recorded, and the record gets it with the digest
+ * of the bytes that run, thus the record connects the cited decision to the
+ * code that ran.
  */
 import { posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
+import { reconcileScriptRecord } from "./decision-record.js";
 import { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
 import { runSandboxExec } from "./run-exec.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
@@ -86,6 +93,23 @@ export function createExecuteCommandTool(deps) {
         describeCall: ({ command }) => scriptToken(command) ?? command.join(" "),
         execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
             const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);
+            // Each script the argv names, as the sandbox resolves it. A relative token resolves against the cwd of the
+            // command, which is a `/{analysisId}/...` path, thus the workspace filesystem resolves it the same way.
+            const recordWrites = [];
+            if (deps.workspaceFilesystem && deps.mutator) {
+                for (const token of command.filter((arg) => SCRIPT_EXTENSIONS.test(arg))) {
+                    const noted = await reconcileScriptRecord({
+                        filesystem: deps.workspaceFilesystem,
+                        mutator: deps.mutator,
+                        session: ctx.session,
+                        invocationId: ctx.invocationId,
+                        toolName: "execute_command",
+                        scriptPath: token.startsWith("/") ? token : posixPath.join(effectiveCwd, token),
+                    });
+                    if (noted.status === "noted")
+                        recordWrites.push(noted.write);
+                }
+            }
             const result = await runSandboxExec({
                 sandboxClient,
                 sandbox,
@@ -97,18 +121,21 @@ export function createExecuteCommandTool(deps) {
                 emit: ctx.emit,
             });
             const bounded = { status: "ok", ...boundExecResult(result) };
-            if (!lineageCollector || !mountRoot)
+            if ((!lineageCollector || !mountRoot) && recordWrites.length === 0)
                 return ok(bounded);
             const record = {
                 command,
                 exitCode: result.exitCode,
                 durationMs: result.durationMs,
                 ...(result.provenance ? { provenance: result.provenance } : {}),
+                ...(recordWrites.length > 0 ? { recordWrites } : {}),
             };
             return ok(withToolCallRecord(bounded, record));
         },
         // Best-effort: a collector failure must never fail the exec.
         foldCallRecord: (record) => {
+            for (const write of record.recordWrites ?? [])
+                deps.mutator?.recordWrite(write);
             if (!lineageCollector || !mountRoot)
                 return;
             try {

package/dist/tools/workspace/index.d.ts

@@ -21,5 +21,6 @@ export * from "./mutator.js";
 export * from "./execute-command.js";
 export * from "./write-file.js";
 export * from "./edit-file.js";
+export * from "./decision-record.js";
 export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
 export type { BoundedExecResult } from "./result-bounds.js";

package/dist/tools/workspace/index.js

@@ -23,4 +23,5 @@ export * from "./mutator.js";
 export * from "./execute-command.js";
 export * from "./write-file.js";
 export * from "./edit-file.js";
+export * from "./decision-record.js";
 export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";

package/dist/tools/workspace/mutator.d.ts

@@ -80,7 +80,7 @@ export type WriteOutcome = {
  * (`inflexa:tool` in the signed document) — the seam records the write without
  * inspecting its caller.
  */
-export type MutateToolName = "write_file" | "edit_file";
+export type MutateToolName = "write_file" | "edit_file" | "knowledge_template" | "execute_command";
 export interface WorkspaceMutatorDeps {
     /** Absolute host root of this analysis's workspace tree — used by the resolver. */
     readonly workspaceRoot: string;

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

@@ -50,20 +50,25 @@
  *       the run before any step starts
  *     - a `suspend` error of a synthesis model request suspends the run in
  *       place of the synthesis failure
- *     - the analysis flips to `suspended_insufficient_funds` in
- *       `collectAndComplete`. The paused parent lands in `CANCELLED`, a
+ *     - the run row and the analysis flip to `suspended_insufficient_funds` in
+ *       `collectAndComplete`. The run status is terminal and does not block a
+ *       new run of the plan. The paused parent lands in `CANCELLED`, a
  *       durably reschedulable state; re-driving it is a future enhancement,
  *       not yet wired here. The reason of the host rides to the run row, the
  *       charge close, the metric, and the terminal part, unread.
  *  5. `synthesizeFindings` (single sequential block, no sandbox)
  *  6. `collectAndComplete` (terminal — runs on ALL paths)
  *     - determine final status from completed/cancelled/failed counts
- *     - update `cortex_runs.status` + `error`, and inside that same step record
- *       the run outcome metric plus the outcome of every settled step whose
- *       child never wrote its own terminal row (a cancelled child, or one that
- *       died before `failStep`)
- *     - close running charge with matching reason
- *     - revoke run authorization via the injected `runAuthorizer` seam
+ *     - update `cortex_runs.status` + `error`. When the write changes the row,
+ *       the same step emits `run_completed` before the commit, records the run
+ *       outcome metric plus the outcome of every settled step whose child never
+ *       wrote its own terminal row (a cancelled child, or one that died before
+ *       `failStep`), closes the running charge with the matching outcome, and
+ *       revokes the run authorization through the injected `runAuthorizer`
+ *     - the write retries with backoff on a failed transaction. When the write is
+ *       refused, or fails on each attempt, close and revoke in their own steps, then
+ *       emit `run_completed`. After a failed write the row stays `running`, so the
+ *       body records its run end as a workflow event for the run canceler
  *     - emit terminal stream part
  *     - WRITES NOTHING to the conversation thread (results are pull-only
  *       via `inspectRun`)
@@ -81,6 +86,8 @@ 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";
+import type { KnowledgeClient } from "../tools/knowledge/client.js";
+import type { TemplateBinding } from "../tools/knowledge/template.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { RunCharge } from "../billing/run-charge.js";
@@ -160,7 +167,7 @@ export interface ExecuteAnalysisInput {
  * path returns — the caller joined an in-flight run, no new workflow was
  * started. Every other variant is a terminal status the parent reached.
  */
-export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled";
+export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds";
 export interface ExecuteAnalysisResult {
     readonly runId: string;
     readonly workflowId: string;
@@ -255,16 +262,27 @@ export interface ExecuteAnalysisDeps {
      * carries the goal and the constraints as they are at the dispatch of that step.
      */
     readonly workingMemory: WorkingMemoryStore;
+    /**
+     * The knowledge client of the composition, when the embedder binds one.
+     * The seed composition reads the contract of the template a grounded step
+     * renders through it, and binds the plan settings to that contract.
+     * Absent, the seed says the contract was not retrieved, and the step agent
+     * learns the slots from the render answers alone.
+     */
+    readonly knowledge?: KnowledgeClient;
     /**
      * The provenance seam of the composition. The body reads its run emit member,
      * and it reads no other member.
      *
-     * The emit is deliberately invoked directly in the workflow body (NOT wrapped
-     * in `DBOS.runStep`) so that body re-execution on DBOS recovery re-fires it —
-     * a cached step would suppress the recovery re-emission, defeating the
-     * point. Idempotency is the consumer's job, achieved via the deterministic
-     * identifiers the events carry, not via step caching. Every call site is
-     * guarded so a throwing observer never fails the run.
+     * `run_started` and `step_completed` are emitted directly in the workflow body
+     * (NOT wrapped in `DBOS.runStep`) so that body re-execution on DBOS recovery
+     * re-fires them — a cached step would suppress the recovery re-emission.
+     * `run_completed` is emitted by the won `persist-final-status` step, or by the
+     * body after that step when the step did not emit in this execution (a refused
+     * or failed write, or a won step served from the DBOS cache), so a recovery
+     * replay still fires it. Idempotency is the consumer's job, achieved via the
+     * deterministic identifiers the events carry, not via step caching. Every call
+     * site is guarded so a throwing observer never fails the run.
      *
      * Events arrive with the run's `RunSession` from durable workflow input — a
      * persisting realization needs its credential, scope, and identity.
@@ -306,6 +324,7 @@ export declare function buildChildInput(args: {
     runId: string;
     workflowId: string;
     prompt: string;
+    templateBinding?: TemplateBinding;
 }): Omit<SandboxStepInput, "runSession">;
 /**
  * Compose one step's seed — the user-content message its agent opens on.
@@ -316,17 +335,26 @@ 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.
  *
- * 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.
+ * The template contract of a grounded step is read with the package, and the
+ * plan settings are bound to it: the seed describes the binding, and the child
+ * input carries it, from one checkpoint. The child fetches nothing.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed seed is
+ * checkpointed and a replay returns it verbatim — the DB, the disk, and the
+ * knowledge service 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>;
+}): Promise<StepSeed>;
+/** What `gatherStepPackage` gives: the data of the seed, and the binding of the plan settings when one holds. */
+export interface StepPackage {
+    readonly briefing: StepBriefing;
+    readonly templateBinding?: TemplateBinding;
+}
 /**
  * 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.
@@ -339,6 +367,9 @@ export declare function composeStepSeed(args: {
  * so an edit during a run reaches each later step, and two steps of one run
  * can carry different copies.
  *
+ * The contract of the template a grounded step renders is read here too, from
+ * the knowledge client, and the plan settings are bound to it.
+ *
  * A read failure throws (house rules): a swallowed error would be frozen into
  * the checkpointed seed and served to every replay of this step.
  */
@@ -347,7 +378,17 @@ export declare function gatherStepPackage(args: {
     stepId: string;
     runId: string;
     deps: ExecuteAnalysisDeps;
-}): Promise<StepBriefing>;
+}): Promise<StepPackage>;
+/**
+ * What `composeStepSeed` checkpoints: the seed, and the binding of the plan
+ * settings to the template of the step when the contract was retrieved and
+ * its served version is the version the plan names. JSON-serialisable, as a
+ * durable step result must be.
+ */
+export interface StepSeed {
+    readonly prompt: string;
+    readonly templateBinding?: TemplateBinding;
+}
 /**
  * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
  * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps