@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/tools/define-tool.d.ts

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`, `turnUsage`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `ask`, `turnUsage`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
@@ -19,7 +19,7 @@ import type { Result } from "neverthrow";
 import { z } from "zod";
 import type { AgentSession } from "../auth/types.js";
 import type { AgentRunUsage } from "../loop/metrics.js";
-import type { EmitFn, RunStep } from "../loop/types.js";
+import type { EmitFn } from "../loop/types.js";
 import type { AskApproval, AskRequest } from "./approval/contract.js";
 export type { EmitFn };
 /**
@@ -35,7 +35,13 @@ export interface ToolError {
     readonly retryable: boolean;
     readonly cause?: unknown;
 }
-export type ToolExecutionMode = "step" | "workflow" | "inline";
+/**
+ * How the loop runs a tool call. `step` (the default) wraps the whole call in
+ * one durable step, thus a replay returns the cached result and never runs the
+ * body again. `inline` runs the call with no step, for a tool whose effects are
+ * not durable work.
+ */
+export type ToolExecutionMode = "step" | "inline";
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export declare function isToolError(value: unknown): value is ToolError;
 /**
@@ -78,13 +84,37 @@ export declare function withToolResultImages<T extends object>(value: T, images:
  * in the same shape.
  */
 export declare function readToolResultImages(value: unknown): ToolResultImage[];
+/**
+ * The reserved key that carries the call record on a tool ok value.
+ *
+ * A call record is what a call leaves for process-local state, for example the
+ * lineage collector of a sandbox step. A replay returns the cached result of a
+ * step-mode call and never runs its body, thus a side effect of the body on
+ * such state is lost on recovery. The record goes into the cached dispatch
+ * instead, and the loop hands it to `foldCallRecord` after the call settles, on
+ * the first run and on each replay alike.
+ *
+ * It is a symbol, thus `JSON.stringify` omits it and the model never reads it.
+ * The record itself must be plain JSON, because the step cache serializes it.
+ */
+export declare const toolCallRecordKey: unique symbol;
+/** A tool ok value that carries a call record under the reserved key. */
+export type WithToolCallRecord<T, R> = T & {
+    readonly [toolCallRecordKey]: R;
+};
+/** The type of the call record that a tool ok type carries. A variant with no record contributes nothing. */
+export type ToolCallRecordOf<Output> = Output extends {
+    readonly [toolCallRecordKey]: infer R;
+} ? R : never;
+/** Attach a call record to a tool ok value. The value keeps its own fields. */
+export declare function withToolCallRecord<T extends object, R>(value: T, record: R): WithToolCallRecord<T, R>;
+/** Read the call record that a tool ok value carries, or `undefined` when it carries none. */
+export declare function readToolCallRecord(value: unknown): unknown;
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
  * dependencies (see the harness-durable-runtime spec) — invocation identity,
- * `session`, `signal`, `emit`, the `runStep`
- * durability seam (`passthroughStep` in chat, `DBOS.runStep` in workflows) a
- * tool uses to wrap its own durable work, the `ask` user-approval seam, and the
- * turn's usage accumulator a sub-agent-running tool hands to its child loop.
+ * `session`, `signal`, `emit`, the `ask` user-approval seam, and the turn's
+ * usage accumulator a sub-agent-running tool hands to its child loop.
  */
 export interface ToolContext {
     /** Stable identity of this AI SDK tool call. Redelivery preserves it; a new
@@ -93,11 +123,6 @@ export interface ToolContext {
     readonly session: AgentSession;
     readonly signal: AbortSignal;
     readonly emit: EmitFn;
-    /**
-     * Wrap durable work in a replay-cached step. The loop namespaces the name
-     * under the tool's own step name, so a tool just passes a short local label.
-     */
-    readonly runStep: RunStep;
     /**
      * Pause for an explicit user decision on a concrete action. Resolves with the
      * approval (`once`/`always`) or throws `AskRejectedError` on denial. Resolves
@@ -117,7 +142,7 @@ export interface ToolContext {
 }
 /**
  * A packaged tool: identity, the Zod input contract, the emitted AI SDK input
- * schema, execution mode, the optional call-description hook, and the executor.
+ * schema, execution mode, the optional hooks, and the executor.
  */
 export interface Tool<Input = unknown, Output = unknown> {
     readonly id: string;
@@ -129,6 +154,11 @@ export interface Tool<Input = unknown, Output = unknown> {
     describeCall?(input: Input): string;
     /** See {@link ToolDefinition.describeResult}. Absent when the tool declares none. */
     describeResult?(input: Input, result: Output): string;
+    /**
+     * See {@link ToolDefinition.foldCallRecord}. The record arrives untyped: the
+     * loop passes back only what the `execute` of the same tool attached.
+     */
+    foldCallRecord?(record: unknown): void;
     execute(input: Input, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 export interface ToolDefinition<Schema extends z.ZodType, Output> {
@@ -199,6 +229,19 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * The hook never reaches the model.
      */
     readonly describeResult?: (input: z.infer<Schema>, result: Output) => string;
+    /**
+     * Fold the call record of one settled call into process-local state. The
+     * record is the one that `execute` attached with `withToolCallRecord`.
+     *
+     * The loop runs the hook after the round settles, in the order of the tool
+     * calls, on the first run and on each replay alike. Thus state that a
+     * replay rebuilds from scratch sees the same records in the same order. A
+     * call whose ok value carries no record, and a failed call, never reach it.
+     *
+     * The hook is synchronous. It must never fail a call: the call has settled,
+     * and its result may already be cached. The loop logs a throw and goes on.
+     */
+    readonly foldCallRecord?: (record: ToolCallRecordOf<Output>) => void;
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -8,7 +8,7 @@
  * captures its deps and calls `defineTool`.
  *
  * `ToolContext` carries only request-scoped values every tool may need
- * (`invocationId`, `session`, `signal`, `emit`, `runStep`, `ask`, `turnUsage`) — no pool, no sandbox, no
+ * (`invocationId`, `session`, `signal`, `emit`, `ask`, `turnUsage`) — no pool, no sandbox, no
  * logger. The error contract: an expected
  * outcome ("not found", "no results") stays in the ok channel as a data
  * variant (`ok({ found: false })`); an unexpected failure is an `err(ToolError)`
@@ -62,6 +62,30 @@ export function readToolResultImages(value) {
     const entries = Array.isArray(carried) ? carried : [carried];
     return entries.filter(isToolResultImage);
 }
+/**
+ * The reserved key that carries the call record on a tool ok value.
+ *
+ * A call record is what a call leaves for process-local state, for example the
+ * lineage collector of a sandbox step. A replay returns the cached result of a
+ * step-mode call and never runs its body, thus a side effect of the body on
+ * such state is lost on recovery. The record goes into the cached dispatch
+ * instead, and the loop hands it to `foldCallRecord` after the call settles, on
+ * the first run and on each replay alike.
+ *
+ * It is a symbol, thus `JSON.stringify` omits it and the model never reads it.
+ * The record itself must be plain JSON, because the step cache serializes it.
+ */
+export const toolCallRecordKey = Symbol("toolCallRecord");
+/** Attach a call record to a tool ok value. The value keeps its own fields. */
+export function withToolCallRecord(value, record) {
+    return { ...value, [toolCallRecordKey]: record };
+}
+/** Read the call record that a tool ok value carries, or `undefined` when it carries none. */
+export function readToolCallRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    return value[toolCallRecordKey];
+}
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level
  * `"type": "object"` — model tool calling rejects anything else. A `z.discriminatedUnion`
@@ -95,6 +119,9 @@ export function defineTool(def) {
         // declares no result hook carries no key, thus "has a hook" is one
         // property check on either side.
         ...(typeof def.describeResult === "function" ? { describeResult: def.describeResult } : {}),
+        // The loop passes back only a record that this tool's `execute`
+        // attached, thus the record has the declared type.
+        ...(typeof def.foldCallRecord === "function" ? { foldCallRecord: def.foldCallRecord } : {}),
         execute: def.execute,
     };
 }

package/dist/tools/execute-analysis.js

@@ -274,7 +274,7 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
  * would pay a file read on every ad hoc launch to learn nothing — while the
  * router, with no resolution, already keeps every entry that parses.
  */
-function adHocPackageResolver(deps) {
+function adHocPackageResolver(deps, analysisId) {
     if (!deps.farmLockFile && !deps.imagePackagesFile && !deps.readPoolInventory)
         return undefined;
     const inventory = {
@@ -283,7 +283,7 @@ function adHocPackageResolver(deps) {
         ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
     };
     return async (names) => {
-        const read = await readInventorySections(inventory);
+        const read = await readInventorySections(inventory, analysisId);
         // An inventory that cannot answer must not drop a name: the router
         // keeps every parsed entry, and the link pass judges at launch.
         if (read.kind === "unavailable")
@@ -296,7 +296,7 @@ async function persistedAdHocPlan(deps, args) {
     const existing = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
     if (existing)
         return validateStoredPlan(existing, args.planId);
-    const resolvePackages = adHocPackageResolver(deps);
+    const resolvePackages = adHocPackageResolver(deps, args.analysisId);
     const route = await routeAdHocRequest({
         provider: deps.utilityProvider,
         model: deps.utilityModel,