@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/lib/chrome.js

@@ -1,23 +1,59 @@
 /**
- * Headless Chrome connection — process-lifetime singleton connected to the
- * Chrome sidecar reachable at `CHROME_BROWSER_URL`. Used by the iterate-report
- * preview-snapshot tool for visual validation.
+ * The connection to a headless Chrome endpoint.
  *
- * Connection is lazy and reconnect-on-disconnect; pages are gated through a
- * semaphore so the sidecar isn't overwhelmed by concurrent reports.
+ * Two callers name an endpoint. A composition names a standing sidecar at assembly, and a lease of the eyes
+ * seam names a browser for one look. Thus the module holds one connection for each endpoint, and it holds no
+ * connection for the process.
+ *
+ * A connection is lazy, and an endpoint connects again after a disconnect. Each endpoint also carries its own
+ * page gate. The gate bounds the pages that run at the same time against that one sidecar.
  */
 import puppeteer from "puppeteer-core";
 import { createNoopLogger } from "./console-logger.js";
+/** Whether a value names an endpoint. An absent value and a blank value each name none. */
+function namesEndpoint(browserUrl) {
+    return browserUrl !== undefined && browserUrl.trim().length > 0;
+}
 /**
  * Whether the config names a browser to connect to. A composition with no endpoint has no eyes, and a
  * caller reads that up front instead of failing once for each attempted connection.
+ *
+ * The predicate narrows the config. Thus a caller that reads the endpoint after the gate needs no type
+ * assertion for a field that the gate proved.
  */
 export function hasBrowserUrl(cfg) {
-    return cfg.browserUrl !== undefined && cfg.browserUrl.trim().length > 0;
+    return namesEndpoint(cfg.browserUrl);
+}
+/**
+ * The endpoint of a connection, or the refusal of a config that names none.
+ *
+ * The refusal and {@link hasBrowserUrl} read the same rule. Thus the gate that a caller reads up front is the
+ * gate that the connection applies.
+ */
+function requireBrowserUrl(browserUrl) {
+    if (namesEndpoint(browserUrl))
+        return browserUrl;
+    throw new Error("CHROME_BROWSER_URL is not set — Cortex requires the chrome sidecar to be reachable");
+}
+const connectOverPuppeteer = (browserUrl) => puppeteer.connect({ browserURL: browserUrl });
+let connector = connectOverPuppeteer;
+/**
+ * Replace the connect operation, and give back the restore of the previous one.
+ *
+ * The cache keeps no state that a caller can read, because a connection is the only product of the module.
+ * Thus a real browser is the only other way to drive the cache, and a unit test of the keys needs this seam.
+ *
+ * Two facts make the seam safe. The module reads the binding at each connect, and no module under `src/`
+ * calls the setter. Thus a deployment always runs the connect of puppeteer. The caller restores the previous
+ * binding, thus a replacement never reaches a later file of the same test run.
+ */
+export function setBrowserConnector(next) {
+    const previous = connector;
+    connector = next;
+    return () => {
+        connector = previous;
+    };
 }
-let browser;
-let connecting;
-let semaphore;
 function createSemaphore(max) {
     let active = 0;
     const queue = [];
@@ -42,50 +78,81 @@ function createSemaphore(max) {
         },
     };
 }
-function getSemaphore(maxPages) {
-    if (!semaphore) {
-        const max = maxPages && maxPages > 0 ? maxPages : 4;
-        semaphore = createSemaphore(max);
-    }
-    return semaphore;
+/** The cap on the pages that run at the same time against one endpoint, when a config names none. */
+const DEFAULT_MAX_PAGES = 4;
+/**
+ * The entry of each endpoint that the process reached, keyed by the endpoint URL. A disconnect evicts an
+ * entry, thus a browser that appears for one look leaves nothing behind.
+ *
+ * The eviction is event-driven, and no sweep runs over this map. The socket close of a dead browser raises
+ * the disconnect event, thus a browser that dies in the normal way evicts its own entry. A browser that dies
+ * with no event leaves one entry that nothing removes. The cost is one dead entry for one endpoint URL that
+ * no later look names again.
+ */
+const endpoints = new Map();
+/**
+ * The entry of one endpoint, made on the first call for that endpoint.
+ *
+ * The first caller fixes the cap of the gate. A later caller with a different cap reads the gate that is
+ * already in place, because one endpoint answers to one gate.
+ */
+function entryFor(browserUrl, maxPages) {
+    const existing = endpoints.get(browserUrl);
+    if (existing)
+        return existing;
+    const max = maxPages && maxPages > 0 ? maxPages : DEFAULT_MAX_PAGES;
+    const fresh = { semaphore: createSemaphore(max) };
+    endpoints.set(browserUrl, fresh);
+    return fresh;
 }
 export async function getBrowser(browserUrl, injected) {
     const logger = (injected ?? createNoopLogger()).named("chrome");
-    if (browser && browser.connected)
-        return browser;
-    if (connecting)
-        return connecting;
-    const browserURL = browserUrl;
-    if (!browserURL) {
-        throw new Error("CHROME_BROWSER_URL is not set — Cortex requires the chrome sidecar to be reachable");
-    }
+    const browserURL = requireBrowserUrl(browserUrl);
+    const entry = entryFor(browserURL);
+    if (entry.browser?.connected)
+        return entry.browser;
+    if (entry.connecting)
+        return entry.connecting;
     logger.info("connecting to browser", { browserURL });
-    connecting = puppeteer
-        .connect({ browserURL })
+    entry.connecting = connector(browserURL)
         .then((b) => {
-        browser = b;
+        entry.browser = b;
         b.on("disconnected", () => {
             logger.info("browser disconnected; will reconnect on next request");
-            if (browser === b)
-                browser = undefined;
+            // A reconnect can hold the key again by the time that the dead browser reports. The two
+            // guards keep the eviction on the entry of this browser alone.
+            if (endpoints.get(browserURL) === entry && entry.browser === b)
+                endpoints.delete(browserURL);
         });
         logger.info("connected", { wsEndpoint: b.wsEndpoint() });
         return b;
     })
         .catch((err) => {
         logger.error("failed to connect to browser", logger.errorFields(err));
+        // A failed connect leaves nothing to reuse. The entry goes, thus a run of looks that each name a
+        // new endpoint and each fail cannot grow the map. The two guards match the disconnect listener,
+        // thus a reconnect that already took the key survives.
+        //
+        // A waiter that already holds a slot of the evicted gate keeps running, and a later caller makes
+        // a fresh gate. Thus the page cap of this endpoint can be exceeded for a moment. That is
+        // acceptable, because the connect just failed and no browser exists for either gate to bound.
+        if (endpoints.get(browserURL) === entry && entry.browser === undefined)
+            endpoints.delete(browserURL);
         throw err;
     })
         .finally(() => {
-        connecting = undefined;
+        entry.connecting = undefined;
     });
-    return connecting;
+    return entry.connecting;
 }
 export async function withPage(cfg, fn) {
-    const release = await getSemaphore(cfg.maxPages).acquire();
+    // The gate belongs to one endpoint, thus the endpoint must be known before the gate. A config that names
+    // none refuses here, the same as the connection below refuses it.
+    const browserURL = requireBrowserUrl(cfg.browserUrl);
+    const release = await entryFor(browserURL, cfg.maxPages).semaphore.acquire();
     let context;
     try {
-        const b = await getBrowser(cfg.browserUrl, cfg.logger);
+        const b = await getBrowser(browserURL, cfg.logger);
         context = await b.createBrowserContext();
         const page = await context.newPage();
         return await fn(page, context);

package/dist/lib/eyes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The eyes seam: where a browser comes from for one look at a report page.
+ *
+ * The seam answers that one question, and it answers nothing else. It gives an endpoint for one scope, and
+ * the harness keeps every page behavior: the `file://` navigation, the readiness wait, and the seen stamp.
+ * Thus a host with a standing sidecar and a host that starts a browser for one look share one page
+ * implementation.
+ *
+ * A realization must bound the life of what it provisions. A lease that no release ends must still end at
+ * that bound. A process can die between the acquire and the release, thus no release of a caller prevents
+ * every leak. The release of a caller is hygiene, and it is not the guarantee. This bound is the load-bearing
+ * contract of the seam, and each new realization obeys it.
+ *
+ * A realization must also bound how many browsers it provisions at one time. The page gate of the chrome
+ * module bounds one endpoint alone. Thus a realization that starts a browser at a new endpoint for each look
+ * meets no bound in the harness. Only the realization knows its own resource, and the count bound sits there.
+ *
+ * The seam speaks the throw protocol, the same as the capture seam beside it. A caller that needs a typed
+ * outcome guards the acquire and the release.
+ */
+import { type ChromeConfig } from "./chrome.js";
+/**
+ * What one acquire covers.
+ *
+ * A realization that starts a container mounts the workspace root at the identical host path, because the
+ * page navigation reads a `file://` URL of the host tree. The caller resolves the root already, thus the
+ * scope hands it over and a realization holds no second resolver.
+ */
+export interface EyesScope {
+    readonly analysisId: string;
+    readonly workspaceRoot: string;
+}
+/**
+ * One acquired browser, and the end of the lease.
+ *
+ * `browserUrl` is the endpoint that a capture connects to. `release` ends the lease of the caller. The shape
+ * binds no duration, thus one look and a longer interactive hold read the same.
+ */
+export interface EyesLease {
+    readonly browserUrl: string;
+    release(): Promise<void>;
+}
+/**
+ * The eyes seam. One call gives one lease over one scope.
+ *
+ * The embedder binds a realization at its composition root. The harness reads this type alone, and it never
+ * asks which realization answers.
+ */
+export type AcquireEyes = (scope: EyesScope) => Promise<EyesLease>;
+/**
+ * Make the static realization over a standing sidecar.
+ *
+ * Each look reads the configured endpoint, and the release does nothing, because the realization provisions
+ * nothing. The sidecar stands outside this process. Thus the deployment that runs the sidecar owns its life,
+ * and the no-leak bound of the seam holds with no work here.
+ */
+export declare function createStaticEyes(chrome: ChromeConfig): AcquireEyes;

package/dist/lib/eyes.js

@@ -0,0 +1,45 @@
+/**
+ * The eyes seam: where a browser comes from for one look at a report page.
+ *
+ * The seam answers that one question, and it answers nothing else. It gives an endpoint for one scope, and
+ * the harness keeps every page behavior: the `file://` navigation, the readiness wait, and the seen stamp.
+ * Thus a host with a standing sidecar and a host that starts a browser for one look share one page
+ * implementation.
+ *
+ * A realization must bound the life of what it provisions. A lease that no release ends must still end at
+ * that bound. A process can die between the acquire and the release, thus no release of a caller prevents
+ * every leak. The release of a caller is hygiene, and it is not the guarantee. This bound is the load-bearing
+ * contract of the seam, and each new realization obeys it.
+ *
+ * A realization must also bound how many browsers it provisions at one time. The page gate of the chrome
+ * module bounds one endpoint alone. Thus a realization that starts a browser at a new endpoint for each look
+ * meets no bound in the harness. Only the realization knows its own resource, and the count bound sits there.
+ *
+ * The seam speaks the throw protocol, the same as the capture seam beside it. A caller that needs a typed
+ * outcome guards the acquire and the release.
+ */
+import { hasBrowserUrl } from "./chrome.js";
+/**
+ * Make the static realization over a standing sidecar.
+ *
+ * Each look reads the configured endpoint, and the release does nothing, because the realization provisions
+ * nothing. The sidecar stands outside this process. Thus the deployment that runs the sidecar owns its life,
+ * and the no-leak bound of the seam holds with no work here.
+ */
+export function createStaticEyes(chrome) {
+    // A realization with no endpoint can only fail at the first look, and a look sits deep inside a model
+    // turn. The refusal at construction moves the fault to the boot of the composition, where a programmer
+    // reads it. `getBrowser` in `chrome.ts` refuses the same condition with a throw, thus one absent endpoint
+    // gets one answer at both sites. The assembly constructs this realization behind `hasBrowserUrl` alone,
+    // thus a composition that names no browser never reaches the refusal.
+    if (!hasBrowserUrl(chrome)) {
+        throw new Error("static eyes need a browser endpoint, and the chrome config names none");
+    }
+    const browserUrl = chrome.browserUrl;
+    return async (_scope) => ({
+        browserUrl,
+        release: async () => {
+            // The standing sidecar outlives every look, thus nothing ends here.
+        },
+    });
+}

package/dist/lib/page-capture.d.ts

@@ -10,6 +10,10 @@
  * imports them, thus a rename or a retime reaches the waiter at compile time. A second copy of the wait
  * script would instead degrade every capture to the readiness timeout, and no type would break.
  *
+ * The capture emulates the reduced-motion preference before the navigation. The design source collapses each
+ * transition under that preference, and it starts each reveal in its visible state. Thus the picture shows
+ * the final state, and no element appears mid-fade.
+ *
  * The capture speaks the throw protocol, because the chrome connection does. A caller that needs a typed
  * outcome guards the call.
  */
@@ -22,6 +26,12 @@ export interface FailedRequest {
 /** The picture and the faults of one page capture. */
 export interface PageCapture {
     screenshotBase64: string;
+    /**
+     * What the picture holds. `full` is the whole document, and it is the shape of a capture that passed at
+     * the first attempt. `viewport` appears when the full-page screenshot threw and the retry at the window
+     * passed, thus the picture shows the top window alone and a section below the fold is absent from it.
+     */
+    coverage: "full" | "viewport";
     consoleErrors: string[];
     failedRequests: FailedRequest[];
 }
@@ -41,6 +51,10 @@ export interface CaptureOptions {
 /**
  * Capture one page: the screenshot, the console errors, and the failed requests.
  *
+ * The picture holds the whole document, and not the window alone. Thus a caller can judge a section that a
+ * reader reaches by a scroll. A refused full-page bitmap degrades to the window, and the coverage of the
+ * result names which of the two pictures arrived.
+ *
  * The readiness wait is best-effort. A page that never signals still captures at the readiness budget, thus
  * a broken page gives a picture that shows what broke.
  */

package/dist/lib/page-capture.js

@@ -10,6 +10,10 @@
  * imports them, thus a rename or a retime reaches the waiter at compile time. A second copy of the wait
  * script would instead degrade every capture to the readiness timeout, and no type would break.
  *
+ * The capture emulates the reduced-motion preference before the navigation. The design source collapses each
+ * transition under that preference, and it starts each reveal in its visible state. Thus the picture shows
+ * the final state, and no element appears mid-fade.
+ *
  * The capture speaks the throw protocol, because the chrome connection does. A caller that needs a typed
  * outcome guards the call.
  */
@@ -17,6 +21,14 @@ import { withPage } from "./chrome.js";
 import { PAGE_NAV_TIMEOUT_MS, PAGE_READY_TIMEOUT_MS, THEME_READY_EVENT, THEME_READY_SENTINEL } from "../report-render/page.js";
 /** The budget of the optional selector wait. The wait is best-effort, thus a miss captures the page anyway. */
 const SELECTOR_TIMEOUT_MS = 5_000;
+/**
+ * The window of one capture, in CSS pixels.
+ *
+ * The width clears each breakpoint of the design source. Thus a multi-column band lays out at the width that a
+ * reader gets, and no band collapses to one column because the window was narrow.
+ */
+const VIEWPORT_WIDTH = 1440;
+const VIEWPORT_HEIGHT = 900;
 /**
  * The body of the readiness wait, in the browser context. The sentinel arm resolves a page that dispatched
  * the event before this wait registered, thus a plain listener never blocks forever. The timer arm bounds a
@@ -41,9 +53,42 @@ function waitForThemeReady(sentinel, event, timeout) {
         }, { once: true });
     });
 }
+/** The connection gives base64 text or raw bytes, and a caller of the capture reads base64 text alone. */
+function toBase64(shot) {
+    return typeof shot === "string" ? shot : Buffer.from(shot).toString("base64");
+}
+/**
+ * Take the picture of one settled page, at the whole document or at the window alone.
+ *
+ * The compositor can refuse a full-page bitmap of a tall page while the bitmap of the window is fine. A
+ * degraded picture beats a dead look, thus a refused full page retries one time at the window. A second throw
+ * names a broken browser and not a tall page, thus it propagates to the caller.
+ */
+async function captureShot(page) {
+    try {
+        return { screenshotBase64: toBase64(await page.screenshot({ encoding: "base64", fullPage: true })), coverage: "full" };
+    }
+    catch (refusedFullPage) {
+        try {
+            return { screenshotBase64: toBase64(await page.screenshot({ encoding: "base64" })), coverage: "viewport" };
+        }
+        catch (refusedViewport) {
+            // The two refusals together are the account of a dead look, and the caller reports the second one
+            // alone. Thus the first one rides as the cause, and no reader of that report loses half of it.
+            if (refusedViewport instanceof Error && refusedViewport.cause === undefined) {
+                refusedViewport.cause = refusedFullPage;
+            }
+            throw refusedViewport;
+        }
+    }
+}
 /**
  * Capture one page: the screenshot, the console errors, and the failed requests.
  *
+ * The picture holds the whole document, and not the window alone. Thus a caller can judge a section that a
+ * reader reaches by a scroll. A refused full-page bitmap degrades to the window, and the coverage of the
+ * result names which of the two pictures arrived.
+ *
  * The readiness wait is best-effort. A page that never signals still captures at the readiness budget, thus
  * a broken page gives a picture that shows what broke.
  */
@@ -59,6 +104,12 @@ export function capturePage(chrome, url, options = {}) {
         page.on("requestfailed", (req) => {
             failedRequests.push({ url: req.url(), reason: req.failure()?.errorText ?? "unknown" });
         });
+        // The size is set before the navigation, because a layout resolves at load time. The connection gives
+        // a small default window, and that window collapses each multi-column band of the design.
+        await page.setViewport({ width: VIEWPORT_WIDTH, height: VIEWPORT_HEIGHT });
+        // The preference is active before the navigation, because the page reveals its sections as it loads.
+        // A preference that arrives after the load reaches a page that already runs its transitions.
+        await page.emulateMediaFeatures([{ name: "prefers-reduced-motion", value: "reduce" }]);
         await page.goto(url, { waitUntil: "networkidle2", timeout: PAGE_NAV_TIMEOUT_MS });
         // The two names and the budget ride as arguments, because the browser context has no module scope.
         await page.evaluate(waitForThemeReady, THEME_READY_SENTINEL, THEME_READY_EVENT, PAGE_READY_TIMEOUT_MS).catch(() => {
@@ -73,9 +124,12 @@ export function capturePage(chrome, url, options = {}) {
             const settle = options.waitMs;
             await new Promise((resolve) => setTimeout(resolve, settle));
         }
-        const screenshot = await page.screenshot({ encoding: "base64", fullPage: false });
+        // The picture must show the whole document at the layout that a reader gets. Thus a defect below the
+        // fold is visible, and a question about content that never appeared has an answer.
+        const shot = await captureShot(page);
         return {
-            screenshotBase64: typeof screenshot === "string" ? screenshot : Buffer.from(screenshot).toString("base64"),
+            screenshotBase64: shot.screenshotBase64,
+            coverage: shot.coverage,
             consoleErrors,
             failedRequests,
         };

package/dist/loop/run-agent.js

@@ -11,7 +11,7 @@ import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError, readToolResultImage } from "../tools/define-tool.js";
 import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
-import { computeDetail } from "./tool-detail.js";
+import { computeDetail, computeResultDetail } from "./tool-detail.js";
 import { toolOutcomeForOutputType } from "./tool-outcome.js";
 const TRUNCATED_PROSE_STEER = "Your previous reply was cut off at the output-token limit; continue concisely, or finish via your terminal tool.";
 const TRUNCATED_TOOL_USE_ERROR = "Your previous tool call was cut off at the output-token limit and was not executed. Retry with a smaller payload, writing in incremental pieces.";
@@ -145,7 +145,8 @@ export async function runAgent(agent, initial, session, opts) {
      *
      * Computed once per round and carried onto both the `tool-started` and the
      * `tool-finished` event, so the pair a host renders as one chip cannot show
-     * two different descriptions of the same call.
+     * two different descriptions of the same call. A tool that describes its own
+     * result replaces the second half of that pair with the outcome it produced.
      */
     const roundDetails = (calls) => calls.map((tu) => {
         const tool = toolsById.get(tu.toolName);
@@ -160,11 +161,11 @@ export async function runAgent(agent, initial, session, opts) {
      * it is not a thrown failure, so nothing reports it and the loop simply feeds it
      * back — and a run that ends badly is usually a run whose tool calls were failing.
      *
-     * `details` and `durations` are positionally aligned with `calls`. `dispatchTools`
-     * measures a duration around the call itself, because this sink emits every finish
-     * event only after the whole round settles.
+     * `details`, `resultDetails` and `durations` are positionally aligned with `calls`.
+     * `dispatchTools` measures a duration around the call itself, because this sink emits
+     * every finish event only after the whole round settles.
      */
-    const settleRound = async (calls, results, details, durations) => {
+    const settleRound = async (calls, results, details, resultDetails, durations) => {
         const errored = [];
         for (let idx = 0; idx < calls.length; idx++) {
             const tu = calls[idx];
@@ -183,7 +184,11 @@ export async function runAgent(agent, initial, session, opts) {
                 toolUseId: tu.toolCallId,
                 name: tu.toolName,
                 outcome,
-                ...detailField(details[idx]),
+                // The result detail wins where there is one, and the call detail
+                // stands otherwise. Only the ok branch of a dispatch computes a
+                // result detail, thus an error and a denial reach here with none
+                // and keep the line the `tool-started` carried.
+                ...detailField(resultDetails[idx] ?? details[idx]),
                 ...durationField(durations[idx]),
             });
         }
@@ -242,8 +247,8 @@ export async function runAgent(agent, initial, session, opts) {
             for (const [idx, tu] of earlier.entries()) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
             }
-            const { results, durations } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
-            const errored = await settleRound(earlier, results, earlierDetails, durations);
+            const { results, durations, resultDetails } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
+            const errored = await settleRound(earlier, results, earlierDetails, resultDetails, durations);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             // The trailing call was never dispatched, but it reaches the model as an error
             // result like any other — so it counts, or `toolErrors` reports a cleaner run
@@ -273,8 +278,8 @@ export async function runAgent(agent, initial, session, opts) {
         for (const [idx, tu] of toolCalls.entries()) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
         }
-        const { results, durations } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
-        const errored = await settleRound(toolCalls, results, details, durations);
+        const { results, durations, resultDetails } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool, encoding);
+        const errored = await settleRound(toolCalls, results, details, resultDetails, durations);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
@@ -438,7 +443,7 @@ function appendDeferredImages(messages, results, deferredImages) {
 /**
  * Dispatch one round of tool calls, and measure the time of each call.
  *
- * `results` and `durations` are positionally aligned with `toolUses`.
+ * `results`, `durations` and `resultDetails` are positionally aligned with `toolUses`.
  *
  * Each measurement brackets the same unit that the loop awaits for that call. For a
  * step-mode call that unit is `runStep`, thus the figure includes the durable-step
@@ -451,6 +456,10 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     // says so, thus it agrees with what `settleRound` accepts. Every index is in
     // fact assigned, because the mode partition below covers each call.
     const durations = new Array(toolUses.length);
+    // A hole stays a hole for a call that described no result: an error, a
+    // denial, and a tool with no result hook each leave the index unassigned,
+    // and `settleRound` then reads the call detail.
+    const resultDetails = new Array(toolUses.length);
     const stepTools = [];
     const workflowTools = [];
     const inlineTools = [];
@@ -465,31 +474,53 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
     }
     await Promise.all(stepTools.map(({ tu, idx }) => {
         const startedAt = performance.now();
-        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding)).then((r) => {
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding)).then((settled) => {
             durations[idx] = elapsedMs(startedAt);
-            results[idx] = r;
+            const dispatched = readDispatchedStep(settled);
+            results[idx] = dispatched.result;
+            if (dispatched.detail !== undefined)
+                resultDetails[idx] = dispatched.detail;
         });
     }));
     for (const { tu, idx } of workflowTools) {
         const startedAt = performance.now();
-        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        const dispatched = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        results[idx] = dispatched.result;
+        if (dispatched.detail !== undefined)
+            resultDetails[idx] = dispatched.detail;
         durations[idx] = elapsedMs(startedAt);
     }
     for (const { tu, idx } of inlineTools) {
         const startedAt = performance.now();
-        results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        const dispatched = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError, encoding);
+        results[idx] = dispatched.result;
+        if (dispatched.detail !== undefined)
+            resultDetails[idx] = dispatched.detail;
         durations[idx] = elapsedMs(startedAt);
     }
-    return { results, durations };
+    return { results, durations, resultDetails };
 }
 /** Whole milliseconds since `startedAt`, on the monotonic clock that took that mark. */
 function elapsedMs(startedAt) {
     return Math.round(performance.now() - startedAt);
 }
+/**
+ * Read one settled step-mode dispatch, tolerating the bare result beside the pair.
+ *
+ * A step-mode call goes through `runStep`, which caches what the body returned and hands
+ * that cached value back on a replay. The durable step store therefore holds values that
+ * a DIFFERENT build of this file wrote: a workflow in flight when the shape of the return
+ * widened replays the bare `ToolResultPart` its own run cached, and it never re-enters the
+ * body that would produce the pair. The replay boundary is the whole reason for the test:
+ * a bare value carries no detail, thus the call keeps the line its `tool-started` showed.
+ */
+function readDispatchedStep(settled) {
+    return "result" in settled ? settled : { result: settled };
+}
 async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const tool = toolsById.get(tu.toolName);
     if (tool === undefined) {
-        return errorResult(tu, `unknown tool: ${tu.toolName}`);
+        return { result: errorResult(tu, `unknown tool: ${tu.toolName}`) };
     }
     const parsed = tool.inputSchema.safeParse(tu.input);
     if (parsed.success)
@@ -502,21 +533,25 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError, encoding) {
     const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
     if (repaired?.success === true)
         return execute(tu, tool, repaired.data, ctx, isFatalLoopError, encoding);
-    return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`);
+    return { result: errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`) };
 }
 async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
     try {
         const output = await tool.execute(input, ctx);
         if (output.isErr())
-            return errorResult(tu, toolErrorContent(output.error));
-        return successResult(tu, output.value, encoding);
+            return { result: errorResult(tu, toolErrorContent(output.error)) };
+        // The one place a result description runs: the ok value in hand, the
+        // input already validated, and the guard inside the compute.
+        const detail = computeResultDetail(tool, input, output.value, encoding.log);
+        const result = successResult(tu, output.value, encoding);
+        return detail === undefined ? { result } : { result, detail };
     }
     catch (err) {
         if (isFatalLoopError(err))
             throw err;
         if (isAskRejected(err))
-            return deniedResult(tu, err.feedback);
-        return errorResult(tu, toolErrorContent(err));
+            return { result: deniedResult(tu, err.feedback) };
+        return { result: errorResult(tu, toolErrorContent(err)) };
     }
 }
 /**

package/dist/loop/tool-detail.d.ts

@@ -2,8 +2,10 @@
  * The call detail: one line naming what a tool call is doing.
  *
  * A tool states it through its own `describeCall` hook, colocated with the Zod
- * `inputSchema` the compiler checks it against. Everything else about the
- * detail happens here, once, for every tool: validate, guard, normalize.
+ * `inputSchema` the compiler checks it against, and through its optional
+ * `describeResult` hook, which names what the call produced. Everything else
+ * about the detail happens here, once, for every tool: validate, guard,
+ * normalize.
  *
  * Two rules make this the only place that matters:
  *
@@ -92,3 +94,18 @@ export declare function normalizeDetail(raw: unknown): ToolCallDetail | undefine
  * second time from the repaired value costs more than the case is worth.
  */
 export declare function computeDetail(tool: Tool, rawInput: unknown, log: Logger): ToolCallDetail | undefined;
+/**
+ * Compute a tool call's result detail, best-effort.
+ *
+ * `parsedInput` is the value the dispatch already validated, and `result` is the
+ * ok value the tool returned one line above. Thus neither is re-parsed here: a
+ * second parse of the input would repeat work the dispatch did, and the result
+ * satisfies no schema at all — the tool's own `Output` type is what the hook
+ * declares, and the tool is the author of both.
+ *
+ * The guard is the whole difference from a bare call. A hook that throws, returns
+ * a non-string, or returns nothing usable yields no result detail, and the
+ * finished event falls back on the call detail. A description must never be able
+ * to fail a call that already succeeded.
+ */
+export declare function computeResultDetail(tool: Tool, parsedInput: unknown, result: unknown, log: Logger): ToolCallDetail | undefined;