@inflexa-ai/harness 0.42.2 → 0.43.0

package/README.md

@@ -1,6 +1,6 @@
 # @inflexa-ai/harness
 
-`@inflexa-ai/harness` is the host-agnostic agent harness — the `runAgent` loop, durable workflows, the sandbox submit/recv protocol, and the provider interfaces. It is a **library, not a server**: it ships everything that does not depend on a particular host, and an embedder supplies the composition root, transport, and any non-local seam realizations.
+`@inflexa-ai/harness` is the host-agnostic agent harness — the `runAgent` loop, durable workflows, the sandbox submit and poll protocol, and the provider interfaces. It is a **library, not a server**: it ships everything that does not depend on a particular host, and an embedder supplies the composition root, transport, and any non-local seam realizations.
 
 ## Run locally
 
@@ -98,7 +98,7 @@ function pinoAsHarnessLogger(p: pino.Logger, names: readonly string[] = []): Log
 
 Chat is a plain in-process turn. A turn is `runChatTurn`, and the harness stores the opening, each round, and the outcome of the turn. The harness ships no HTTP layer, thus the host owns the route. Compute-heavy work runs as **durable workflows** — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runAgent` primitive runs in both modes; durability and the event sink are injected, so the loop body is identical.
 
-The sandbox protocol is submit-then-retrieve, which is what lets a long run survive a host restart: the host `POST /exec`s a command and retrieves the result over one of two transports — **poll** (the default: the host asks, the sandbox initiates nothing and needs no network egress) or **callback** (opt-in: the sandbox POSTs signed callbacks to an ingress the embedder runs). Both exec endpoints are HMAC signature-authenticated. See the [`harness-sandbox-exec`](./openspec/specs/harness-sandbox-exec/) spec.
+The sandbox protocol is submit-then-poll, which lets a long run survive a host restart. Each exec runs inside one durable step: the host submits the command with `POST /exec`, and then it polls `GET /exec/{execId}?since={cursor}` until the result. A recovered step submits the same exec id again, and the sandbox gives the existing record, thus the command does not run again. The sandbox initiates nothing and has no egress, and confinement keeps each other peer away from its exec port. Refer to the [`harness-sandbox-exec`](./openspec/specs/harness-sandbox-exec/) spec.
 
 ## Further reading
 

package/dist/agents/sandbox/shared.d.ts

@@ -44,14 +44,9 @@ export interface SandboxStepCoords {
     /** Absolute host root of this analysis's workspace tree (resolved at the workflow body). */
     readonly workspaceRoot: string;
     readonly analysisId: string;
-    readonly runId: string;
-    readonly stepId: string;
-    readonly workflowId: string;
     /** Absolute writable artifact directory for this step (e.g. stepWritePrefix(...)). */
     readonly allowedWritePrefix: string;
-    /** Stable per-call function id minter (monotonic; replay-deterministic). */
-    readonly nextFunctionId: () => string;
-    /** Absolute unix-ms deadline for `awaitExec`. */
+    /** Absolute unix-ms deadline of each exec. */
     readonly deadlineMs: () => number;
 }
 /** The shared dependency graph every sandbox agent draws from. */

package/dist/agents/sandbox/shared.js

@@ -40,7 +40,6 @@ import { createReadToolOutputTool } from "../../tools/read-tool-output.js";
 import { createReportBlockerTool } from "../../tools/sandbox/report-blocker.js";
 import { createSubmitFileMetadataTool } from "../../tools/sandbox/submit-file-metadata.js";
 import { toSandboxPath } from "../../workspace/paths.js";
-import { setActiveExecId } from "../../state/index.js";
 import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
 import { createResolveCitationTool } from "../../tools/research/resolve-citation.js";
 /**
@@ -76,9 +75,6 @@ function resolveSandboxTools(deps, tools) {
             analysisId: deps.step.analysisId,
             sandboxClient: deps.sandboxClient,
             sandbox: deps.step.sandbox,
-            workflowId: deps.step.workflowId,
-            stepId: deps.step.stepId,
-            nextFunctionId: deps.step.nextFunctionId,
             deadlineMs: deps.step.deadlineMs,
         }),
         resolveLibraryId: resolveLibraryIdTool,
@@ -116,18 +112,11 @@ function resolveSandboxTools(deps, tools) {
     }
     return resolved;
 }
-function createMarkExecActive(deps) {
-    return (execId) => setActiveExecId(deps.pool, deps.step.runId, deps.step.stepId, execId).match(() => { }, () => { });
-}
 /** Build the workspace mutate + read tools every sandbox agent receives. In
  *  `readOnly` mode the write_file/edit_file pair is omitted; execute_command
  *  and the read tools stay. */
 function buildWorkspaceTools(deps, readOnly) {
     const { step, sandboxClient, workspaceFs, pool, embedding, lineageCollector } = deps;
-    // Registry tagging is a best-effort watchdog backstop (`run-exec.ts` already
-    // swallows a throw here); fold a `DbError` into a no-op so a registry write
-    // failure neither fails the exec nor surfaces as an unhandled rejection.
-    const markExecActive = createMarkExecActive(deps);
     // The agent's writable working directory: relative paths resolve here, and
     // writes are confined here. `allowedWritePrefix` is its host path; the
     // in-sandbox path (the `execute_command` default cwd, see the harness-workspace-tools spec) is the same
@@ -150,12 +139,8 @@ function buildWorkspaceTools(deps, readOnly) {
         createExecuteCommandTool({
             sandboxClient,
             sandbox: step.sandbox,
-            workflowId: step.workflowId,
-            stepId: step.stepId,
-            nextFunctionId: step.nextFunctionId,
             deadlineMs: step.deadlineMs,
             defaultCwd: sandboxWorkingDir,
-            markExecActive,
             ...(lineageCollector ? { lineageCollector, mountRoot: `/${step.analysisId}` } : {}),
         }),
         ...mutateTools,

package/dist/app/chat-turn.js

@@ -6,7 +6,7 @@
 import { unwrapOrThrow } from "../lib/result.js";
 import { finalText, runAgent } from "../loop/run-agent.js";
 import { passthroughStep } from "../loop/run-step.js";
-import { compactionExchangeOf } from "../memory/ai-sdk-message-storage.js";
+import { compactionExchangeOf, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { createConversationDisplayRecorder } from "../memory/conversation-display-recorder.js";
 import { deriveThreadTitle } from "../memory/derive-thread-title.js";
 import { conversationRecordTurn, createThreadHistory } from "../memory/thread-history.js";
@@ -217,6 +217,7 @@ async function runOpenTurn(deps, turn, prepared, agent, params) {
     await flush({
         status: outcome.status,
         ...(outcome.status === "failed" ? { reason: outcome.reason, note: conversationRecordTurn(failureNote(outcome.reason)) } : {}),
+        ...(outcome.status === "aborted" ? { note: interruptionNote() } : {}),
         ...(turnUsage === undefined ? {} : { turnUsage }),
         turnDurationMs: durationMs,
     });
@@ -265,6 +266,17 @@ function failureReasonOf(err) {
         return "The model request failed.";
     return "The turn stopped on an internal error.";
 }
+/**
+ * The note of an aborted turn. Without it, the next turn reads the request of the aborted turn as open, and
+ * its reply also answers that request. The transcript shows the interruption from the turn record, thus the
+ * note has no display.
+ */
+function interruptionNote() {
+    return {
+        modelMessages: [syntheticUserMessage("[The user interrupted the request above. Do not continue it unless the user asks you to.]")],
+        displayMessages: [],
+    };
+}
 function failureNote(reason) {
     return ["[Turn Failed]", `The turn stopped before it finished. Reason: ${reason}`, "The rounds above this note ran, and their results are stored."].join("\n");
 }

package/dist/config/environment-stores.d.ts

@@ -42,9 +42,11 @@ export interface EnvironmentStorePaths {
      * importable inside a sandbox. Omit when the host mounts the farm at the
      * sandbox's own path, which makes the container path correct as-is; a host
      * that reads the farm somewhere else must inject the path, or the
-     * inventory reads as unknown.
+     * inventory reads as unknown. A host that keeps one farm for each analysis
+     * gives a function, and each read resolves the path with the analysis id
+     * of its session.
      */
-    readonly farmLockFile?: string;
+    readonly farmLockFile?: string | ((analysisId: string) => string);
     /**
      * Host path of the image inventory record, `image-packages.json` at the
      * root of the package store — the image-owned tools and Node packages

package/dist/contracts/chat-events.d.ts

@@ -65,6 +65,14 @@ export type ToolCallOutcome = ToolOutcome | "incomplete";
  * when the detail could not be produced.
  */
 export type ToolCallDetail = string;
+/**
+ * A sub-agent loop started a request to its model. Only a sub-agent gives this frame, thus a consumer that
+ * keeps the root frames only (`isRootFrame`) never sees it. A host reads it as "the sub-agent thinks".
+ */
+export interface IterationEvent {
+    type: "iteration";
+    source: EventSource;
+}
 /** A tool call has been dispatched. */
 export interface ToolStartedEvent {
     type: "tool-started";
@@ -133,7 +141,7 @@ export interface ChatErrorEvent {
     source: EventSource;
 }
 /** The discriminated union of all chat-stream events. */
-export type ChatEvent = TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | FinishEvent | ChatErrorEvent;
+export type ChatEvent = TextDeltaEvent | IterationEvent | ToolStartedEvent | ToolFinishedEvent | FinishEvent | ChatErrorEvent;
 /** A `data-*` part as a frame, with the source of its emitter when the emitter stamped one. */
 export type ChatPartFrame = ChatPart & {
     source?: EventSource;

package/dist/contracts/chat-frame.d.ts

@@ -17,9 +17,9 @@ export type ChatPartCheck = {
     readonly error: string;
 };
 /**
- * The frame of one emitted event, or `null` for `iteration` and `done`. A frame of a sub-agent keeps its source, thus a
- * consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`, the source of the root agent.
- * A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
+ * The frame of one emitted event, or `null` for `done` and for an `iteration` of the root agent. A frame of a sub-agent
+ * keeps its source, thus a consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`,
+ * the source of the root agent. A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
  */
 export declare function toChatFrame(event: EmitEvent | ChatStreamEvent | ChatDataPart, fallbackSource: EmitEvent["source"]): ChatFrame | null;
 /**

package/dist/contracts/chat-frame.js

@@ -6,13 +6,16 @@ function toSource(source) {
     return { agentId: source.agentId, callPath: [...source.callPath] };
 }
 /**
- * The frame of one emitted event, or `null` for `iteration` and `done`. A frame of a sub-agent keeps its source, thus a
- * consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`, the source of the root agent.
- * A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
+ * The frame of one emitted event, or `null` for `done` and for an `iteration` of the root agent. A frame of a sub-agent
+ * keeps its source, thus a consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`,
+ * the source of the root agent. A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
  */
 export function toChatFrame(event, fallbackSource) {
     switch (event.type) {
         case "iteration":
+            // The root loop gives none: a consumer of the root frames, for example the first-frame time of a
+            // browser, must not read the start of a model request as output.
+            return event.source.callPath.length > 1 ? { type: "iteration", source: toSource(event.source) } : null;
         case "done":
             return null;
         case "tool-started":
@@ -100,6 +103,8 @@ export function applyChatFrame(messages, frame, assistantId) {
     if (frame.type === "error") {
         return { messages, terminal: { error: frame } };
     }
+    if (frame.type === "iteration")
+        return { messages, terminal: null };
     const partFrame = frame;
     const next = updateAssistant(messages, assistantId, (parts) => applyPartFrame(parts, partFrame));
     return { messages: next, terminal: null };

package/dist/contracts/chat-parts.d.ts

@@ -348,7 +348,10 @@ export interface RunFailedPart {
     runId: string;
     /** Scrubbed error message (no internal details). */
     error: string;
-    /** The suspend reason of the host, carried unread; present only when the run suspended. */
+    /**
+     * The suspend reason of the host, carried unread, when the run suspended.
+     * `canceled` when an external cancel ended the run. Absent for a failure.
+     */
     reason?: string;
 }
 /**

package/dist/contracts/data-profile.d.ts

@@ -345,14 +345,12 @@ export interface DataProfileRecipeStep {
     groupIds: string[];
 }
 /**
- * The comparand identifying WHICH files a profile covered and whether the SAME BYTES
- * were profiled.
+ * The record of WHICH files a profile covered and of the bytes behind them.
  *
  * `digest` is a stable hash over the staged inputs' identities, sizes, and mtimes in a
  * canonical order, so it depends on the set and not on enumeration order. It excludes
- * content hashes deliberately: enumerating those would mean reading every input in full
- * on every parity check. An edit preserving both byte length and mtime is therefore not
- * detected — bounded, and documented.
+ * content hashes deliberately: a content hash means a full read of every input. Two
+ * inputs with the same byte length and mtime therefore give the same digest.
  */
 export interface DataProfileInputSignature {
     count: number;
@@ -413,7 +411,7 @@ export interface DataProfileResult {
     kinds?: DataProfileKind[];
     /** What varies across those sets, on a snapshot of the same era. */
     axes?: DataProfileAxis[];
-    /** The drift comparand. */
+    /** The record of the profiled kept input set. */
     inputSignature?: DataProfileInputSignature;
     /** How much of the scanned tree the kinds describe, on a snapshot of the kinds era. Superseded by `partition`. */
     coverage?: DataProfileCoverage;

package/dist/contracts/index.d.ts

@@ -3,7 +3,7 @@ export type { OrganSystem } from "./organ-system.js";
 export { SEVERITIES, SeveritySchema } from "./severity.js";
 export type { Severity } from "./severity.js";
 export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, AskPart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepUsagePart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, ChildSessionStartedPart, ReportRenderedPart, CompactionPart, ChatPart, } from "./chat-parts.js";
-export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, ChatEvent, ChatFrame, ChatPartFrame, } from "./chat-events.js";
+export type { EventSource, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, ChatEvent, ChatFrame, ChatPartFrame, } from "./chat-events.js";
 export type { TokenUsageRollup } from "./usage.js";
 export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
 export type { DataProfileAxis, DataProfileChecked, DataProfileCompanionCompleteness, DataProfileCoverage, DataProfileDimension, DataProfileFile, DataProfileGroup, DataProfileGroupSlot, DataProfileInputSignature, DataProfileKind, DataProfileLifecycleStatus, DataProfileMemberAnnotation, DataProfileObservation, DataProfileOrganism, DataProfilePartition, DataProfileProbeReport, DataProfileQualityAssessment, DataProfileQuarantine, DataProfileRecipeStep, DataProfileResult, DataProfileSubjectSource, } from "./data-profile.js";