@inflexa-ai/harness 0.14.2 → 0.15.0

package/dist/loop/run-agent.js

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { jsonSchema, tool as aiTool } from "ai";
+import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
@@ -8,7 +10,9 @@ import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/p
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
 import { isToolError } from "../tools/define-tool.js";
-import { addChatUsage, recordAgentRun } from "./metrics.js";
+import { addChatUsage, hasReportedUsage, recordAgentRun } from "./metrics.js";
+import { computeDetail } 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.";
 export const DEFAULT_STEP_NAME_FORMATTER = {
@@ -50,6 +54,11 @@ export async function runAgent(agent, initial, session, opts) {
     // answer that cannot come.
     const unavailableAsk = new UnavailableAsk();
     const ask = opts.ask ?? ((request) => unavailableAsk.ask(request));
+    // A run handed no accumulator is the turn's root: it creates the one every
+    // descendant loop folds into, and it is the only loop entitled to report a
+    // turn total. Descendants receive the root's object and mutate it in place.
+    const turnUsage = opts.turnUsage ?? {};
+    const isTurnRoot = opts.turnUsage === undefined;
     const toolCtx = (tu) => ({
         invocationId: tu.toolCallId,
         session,
@@ -57,6 +66,7 @@ export async function runAgent(agent, initial, session, opts) {
         emit,
         runStep: (name, fn) => runStep(`${formatStepName.tool(tu.toolName, tu.toolCallId)}:${name}`, fn),
         ask,
+        turnUsage,
     });
     let iterations = 0;
     let truncationRecoveries = 0;
@@ -77,6 +87,44 @@ export async function runAgent(agent, initial, session, opts) {
     const logFinish = (level, reason, cappedOut) => {
         log[level]("run finished", { iterations, reason, cappedOut, truncationRecoveries, toolCalls: toolCallCount, toolErrors: toolErrorCount, usage });
     };
+    const usageRecorder = opts.usageRecorder ?? createNoopUsageRecorder();
+    /**
+     * Fold one completed call into both rollups and hand it to the recorder.
+     * Called at the fold point, with the reply in hand — before any branch that
+     * can end the run — so a call that completed is accounted for even when the
+     * run later aborts or dies.
+     *
+     * A call that reported nothing produces no record. Model ids are identity,
+     * not usage: a reply carrying only `requestedModelId`/`servedModelId` still
+     * reported nothing to account for, so it is folded (to no effect) and left
+     * out of the ledger rather than entered as an all-absent record.
+     *
+     * Delivery is bare — no `await`, no `try` — because the `UsageRecorder`
+     * contract forbids `record` to throw or block.
+     */
+    const accountForCall = (reply, stepName) => {
+        addChatUsage(usage, reply.usage);
+        addChatUsage(turnUsage, reply.usage);
+        const reported = reply.usage;
+        if (reported === undefined || !hasReportedUsage(reported))
+            return;
+        usageRecorder.record({
+            recordKey: recordKeyFor(session, opts.invocationId, stepName),
+            agentId: source.agentId,
+            callPath: source.callPath,
+            scope: session.scope,
+            ...(session.runFrame?.runId === undefined ? {} : { runId: session.runFrame.runId }),
+            ...(session.runFrame?.stepId === undefined ? {} : { stepId: session.runFrame.stepId }),
+            ...(reply.requestedModelId === undefined ? {} : { requestedModelId: reply.requestedModelId }),
+            ...(reply.servedModelId === undefined ? {} : { servedModelId: reply.servedModelId }),
+            usage: reported,
+        });
+    };
+    /** The rollups this loop stamps on its finish — each absent when nothing reported. */
+    const finishUsage = () => ({
+        ...(hasReportedUsage(usage) ? { usage: { ...usage } } : {}),
+        ...(isTurnRoot && hasReportedUsage(turnUsage) ? { turnUsage: { ...turnUsage } } : {}),
+    });
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
     // is itself what the surface renders, so the turn ends the moment a denial
@@ -86,8 +134,19 @@ export async function runAgent(agent, initial, session, opts) {
         await emit({ type: "iteration", source, index: i, final: true });
         recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
         logFinish("warn", "denied", false);
-        return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries } };
+        return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries, ...finishUsage() } };
     };
+    /**
+     * The call details for one dispatch round, positionally aligned with `calls`.
+     *
+     * 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.
+     */
+    const roundDetails = (calls) => calls.map((tu) => {
+        const tool = toolsById.get(tu.toolName);
+        return tool === undefined ? undefined : computeDetail(tool, tu.input, log);
+    });
     /**
      * Fold one dispatch round into the run's counters and the event sink, returning the
      * tools whose results the model will read as errors.
@@ -97,17 +156,20 @@ 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.
      */
-    const settleRound = async (calls, results) => {
+    const settleRound = async (calls, results, details) => {
         const errored = [];
         for (let idx = 0; idx < calls.length; idx++) {
             const tu = calls[idx];
-            const isError = isErrorOutput(results[idx]);
+            const outcome = outcomeOf(results[idx]);
             toolCallCount++;
-            if (isError) {
+            // A denial counts here with the errors: the model reads it as a result
+            // it did not get to act on, which is what these counters describe. The
+            // event keeps the two apart for the user-facing surface.
+            if (outcome !== "ok") {
                 toolErrorCount++;
                 errored.push(tu.toolName);
             }
-            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, isError });
+            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, outcome, ...detailField(details[idx]) });
         }
         return errored;
     };
@@ -125,8 +187,9 @@ export async function runAgent(agent, initial, session, opts) {
             ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
             providerOptions,
         };
-        const reply = await resultStep(runStep)(formatStepName.llm(i), () => provider.chat(request, session, signal));
-        addChatUsage(usage, reply.usage);
+        const llmStepName = formatStepName.llm(i);
+        const reply = await resultStep(runStep)(llmStepName, () => provider.chat(request, session, signal));
+        accountForCall(reply, llmStepName);
         if (reply.finishReason === "aborted") {
             // An interrupted turn keeps whatever the model produced before the cut, but
             // never an empty shell: a partial with no content adds no message, so a
@@ -159,11 +222,12 @@ export async function runAgent(agent, initial, session, opts) {
             }
             const trailing = toolCalls[toolCalls.length - 1];
             const earlier = toolCalls.slice(0, -1);
-            for (const tu of earlier) {
-                await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
+            const earlierDetails = roundDetails(earlier);
+            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 = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-            const errored = await settleRound(earlier, results);
+            const errored = await settleRound(earlier, results, earlierDetails);
             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
@@ -184,15 +248,16 @@ export async function runAgent(agent, initial, session, opts) {
             await emit({ type: "iteration", source, index: i, final: true });
             recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
             logFinish("info", reply.finishReason, false);
-            return { messages, finish: { reason: reply.finishReason, cappedOut: false, truncationRecoveries } };
+            return { messages, finish: { reason: reply.finishReason, cappedOut: false, truncationRecoveries, ...finishUsage() } };
         }
         await emit({ type: "iteration", source, index: i, final: false });
         log.debug("iteration", { iteration: i, tools: toolCalls.map((t) => t.toolName) });
-        for (const tu of toolCalls) {
-            await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
+        const details = roundDetails(toolCalls);
+        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 = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-        const errored = await settleRound(toolCalls, results);
+        const errored = await settleRound(toolCalls, results, details);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
@@ -207,8 +272,9 @@ export async function runAgent(agent, initial, session, opts) {
     // rewrites the whole prefix from scratch. It still carries the cache options
     // because it is the one call whose write is pure waste, and the
     // cache_write_tokens counter is what makes that waste visible.
-    const wrapUp = await resultStep(runStep)(formatStepName.llm(agent.maxIterations), () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none", providerOptions }, session, signal));
-    addChatUsage(usage, wrapUp.usage);
+    const wrapUpStepName = formatStepName.llm(agent.maxIterations);
+    const wrapUp = await resultStep(runStep)(wrapUpStepName, () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none", providerOptions }, session, signal));
+    accountForCall(wrapUp, wrapUpStepName);
     if (wrapUp.finishReason === "aborted") {
         // An abort during the tool-less wrap-up is still the user cutting the turn — the
         // same event the in-loop path handles — so it gets the identical treatment: keep a
@@ -222,13 +288,65 @@ export async function runAgent(agent, initial, session, opts) {
         await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
         recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
         logFinish("warn", "aborted", true);
-        return { messages, finish: { reason: "aborted", cappedOut: true, truncationRecoveries } };
+        return { messages, finish: { reason: "aborted", cappedOut: true, truncationRecoveries, ...finishUsage() } };
     }
     messages.push(wrapUp.message);
     await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
     recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
     logFinish("warn", "max_iterations", true);
-    return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries } };
+    return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries, ...finishUsage() } };
+}
+/**
+ * Delimiter joining the call path into one key segment.
+ *
+ * Deliberately not the `:` that separates the key's segments, so a call path
+ * can never be read as one: agent ids are kebab-case identifiers, run ids are
+ * UUIDs or the profiler's `data-profile` literal, step ids are path-safe plan
+ * ids (`T1S1`, `synthesis`, `profile`), tool-call ids are provider-issued
+ * opaque tokens, and the loop's step names are `llm-{n}` / `tool-{name}-{id}`
+ * with an optional `salvage:` prefix — none of them can contain `>`.
+ */
+const CALL_PATH_DELIMITER = ">";
+/**
+ * Idempotency key for one call's usage record:
+ * `{runId}[:{stepId}]:{callPath}[:{invocationId}]:{stepName}`.
+ *
+ * Every component is a fact the same call carries again on every replay, so a
+ * re-executed body re-fires `record` with the byte-identical key and an
+ * upserting sink counts the call once. Each earns its place by a collision it
+ * alone resolves:
+ *
+ * - `stepId` — `executeAnalysis` runs one child workflow per step under a
+ *   single shared `runId`, and each step's loop names its first call `llm-0`.
+ * - `callPath` — a step name is unique only within ONE loop invocation (every
+ *   `runAgent` restarts its names at `llm-0`), and several loops routinely run
+ *   under one frame: a step's post-step describer and its summary writer share
+ *   `{runId, stepId}`, and the run-synthesis loop shares a bare `{runId}` with
+ *   the sub-agents its tools run. The provenance path is what separates those
+ *   agent chains.
+ * - `invocationId` — the same sub-agent dispatched twice in one round has an
+ *   identical call path, so only the dispatching tool-call id tells the two
+ *   child loops apart. It is replay-stable by the harness-tools contract: a
+ *   redelivered call carries the id it was issued under.
+ * - `stepName` — the loop's own deterministic name, reused rather than
+ *   re-derived. Minting a second *naming* scheme here would create two things
+ *   that must agree about what "the same call" is, and they would drift.
+ *
+ * Outside a `RunFrame` there is no replay to be safe against (the HTTP chat
+ * path runs a call exactly once), so a fresh id is enough and is what keeps two
+ * calls in one turn distinct.
+ */
+function recordKeyFor(session, invocationId, stepName) {
+    const frame = session.runFrame;
+    if (frame === undefined)
+        return randomUUID();
+    return [
+        frame.runId,
+        ...(frame.stepId === undefined ? [] : [frame.stepId]),
+        session.provenance.callPath.join(CALL_PATH_DELIMITER),
+        ...(invocationId === undefined ? [] : [invocationId]),
+        stepName,
+    ].join(":");
 }
 function toolCallParts(message) {
     if (typeof message.content === "string")
@@ -357,8 +475,8 @@ function isAskRejected(err) {
 }
 /**
  * Map a rejected approval to a model-visible `execution-denied` tool result. The
- * prose is the model's only account of the denial; `isErrorOutput` already
- * treats `execution-denied` as an error result.
+ * prose is the model's only account of the denial; `outcomeOf` reports it as
+ * `denied`, distinct from a fault.
  */
 function deniedResult(toolCall, feedback) {
     const reason = feedback === undefined || feedback.length === 0
@@ -371,8 +489,16 @@ function deniedResult(toolCall, feedback) {
         output: { type: "execution-denied", reason },
     };
 }
-function isErrorOutput(result) {
-    return result.output.type === "error-text" || result.output.type === "error-json" || result.output.type === "execution-denied";
+function outcomeOf(result) {
+    return toolOutcomeForOutputType(result.output.type);
+}
+/**
+ * The optional `detail` field, present only when there is one. Spread rather
+ * than assigned so an undescribed call emits an event with no `detail` key at
+ * all, which is what the contract promises: absent, never empty.
+ */
+function detailField(detail) {
+    return detail === undefined ? {} : { detail };
 }
 function hasDenial(results) {
     return results.some((r) => r.output.type === "execution-denied");

package/dist/loop/run-to-terminal.d.ts

@@ -33,7 +33,9 @@ export declare const DEFAULT_SALVAGE_ITERATIONS = 3;
  * first run that ended `max_iterations` spent its whole budget failing to submit,
  * while one that ended `stop` gave up on prose after a single turn. Those call for
  * opposite responses, and the returned `RunAgentResult` carries only the second
- * run's finish, which is the same for either.
+ * run's finish, which is the same for either. Its token rollups are the sole
+ * exception — those are summed across both attempts, since they measure the run
+ * rather than diagnose it.
  */
 export interface SalvageRecord {
     /** How the FIRST run ended — the reason a salvage was needed at all. */
@@ -59,6 +61,7 @@ export interface TerminalSalvage {
 /**
  * Drive `agent` to its terminal tool, salvaging once if it doesn't get there.
  * Returns the salvage run's result when a salvage occurred (its message array
- * already includes the first run's), otherwise the first run's result.
+ * already includes the first run's, and its token rollups are summed across both
+ * attempts), otherwise the first run's result.
  */
 export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunToTerminalResult>;

package/dist/loop/run-to-terminal.js

@@ -21,6 +21,7 @@
  * run's — replaying them would silently return the first run's cached results.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { addChatUsage } from "./metrics.js";
 import { DEFAULT_STEP_NAME_FORMATTER, runAgent } from "./run-agent.js";
 /** Default salvage budget: one submit plus a validation-fix retry or two. */
 export const DEFAULT_SALVAGE_ITERATIONS = 3;
@@ -33,7 +34,8 @@ function salvageStepNames(base) {
 /**
  * Drive `agent` to its terminal tool, salvaging once if it doesn't get there.
  * Returns the salvage run's result when a salvage occurred (its message array
- * already includes the first run's), otherwise the first run's result.
+ * already includes the first run's, and its token rollups are summed across both
+ * attempts), otherwise the first run's result.
  */
 export async function runToTerminal(agent, initial, session, opts, salvage) {
     const first = await runAgent(agent, initial, session, opts);
@@ -63,5 +65,37 @@ export async function runToTerminal(agent, initial, session, opts, salvage) {
         formatStepName: salvageStepNames(opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER),
     };
     const salvaged = await runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
-    return { ...salvaged, salvage: { firstFinish: first.finish, finish: salvaged.finish } };
+    // The continuation is the same logical run as the first attempt — its
+    // message array already carries the first run's — so its rollups must too,
+    // or the caller reads the salvage turn's tokens as the whole cost.
+    //
+    // `salvage` deliberately keeps each attempt's OWN finish, unsummed: it is the
+    // per-attempt diagnosis, not a second accounting of the same tokens. The two
+    // views are therefore NOT additive — `finish` is the run's total and already
+    // covers everything `salvage.firstFinish` and `salvage.finish` report.
+    return {
+        ...salvaged,
+        finish: {
+            ...salvaged.finish,
+            ...sumUsage("usage", first.finish, salvaged.finish),
+            ...sumUsage("turnUsage", first.finish, salvaged.finish),
+        },
+        salvage: { firstFinish: first.finish, finish: salvaged.finish },
+    };
+}
+/**
+ * Sum one rollup field across the two runs, keeping it absent when neither
+ * reported. Both runs are roots or neither is — `runToTerminal` forwards its
+ * caller's options unchanged — so summing `turnUsage` never mixes a turn total
+ * with a bare own-rollup.
+ */
+function sumUsage(field, first, second) {
+    const a = first[field];
+    const b = second[field];
+    if (a === undefined && b === undefined)
+        return {};
+    const total = {};
+    addChatUsage(total, a);
+    addChatUsage(total, b);
+    return { [field]: total };
 }

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

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ *
+ * Two rules make this the only place that matters:
+ *
+ * 1. **The detail is a diagnostic and must never fail a call.** A hook that
+ *    throws, returns a non-string, or returns nothing usable yields no detail
+ *    and the tool dispatches unchanged.
+ * 2. **Normalization is not delegated to tool authors.** Thirty authors would
+ *    each get the line breaks, the control characters, the secret redaction, and
+ *    the length cap slightly wrong. Here it is one auditable path.
+ */
+import type { ToolCallDetail } from "../contracts/chat-events.js";
+import type { Logger } from "../lib/logger.js";
+import type { Tool } from "../tools/define-tool.js";
+export type { ToolCallDetail };
+/**
+ * The length cap, in characters. A full workspace path with a line range fits
+ * comfortably; a `write_file` content field does not, which is the point — a
+ * hook author who returns a payload cannot push it to a host through this
+ * channel.
+ */
+export declare const DETAIL_MAX_LENGTH = 120;
+/**
+ * Normalize whatever a hook returned into an emittable detail, or `undefined`.
+ *
+ * In order: reject anything that is not a usable string, strip control
+ * characters, collapse to one line, redact secrets, then cap the length.
+ *
+ * The control-character strip is the harness's existing `normalizeUnicode`,
+ * which is also what the chat route applies to user prose — a detail is
+ * rendered by a host, so a terminal escape sequence in it is an injection.
+ * Redaction runs before the cap, so a secret cannot survive by being cut in
+ * half, and after the strip, so an embedded control byte cannot break a pattern.
+ */
+export declare function normalizeDetail(raw: unknown): ToolCallDetail | undefined;
+/**
+ * Compute a tool call's detail, best-effort.
+ *
+ * `rawInput` is unvalidated model output: the loop emits `tool-started` before
+ * `dispatchTools` parses anything, so the value here has satisfied no schema
+ * yet. The hook declares its parameter as `z.infer<Schema>`, so it is called
+ * ONLY on a successful `safeParse` — without that, the declared type would be a
+ * lie and author-written code would run over arbitrary shapes.
+ *
+ * A call the loop repairs later (`repairToolInput`) therefore emits no detail.
+ * That is accepted: repair is a rare recovery path, and computing the detail a
+ * 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;

package/dist/loop/tool-detail.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ *
+ * Two rules make this the only place that matters:
+ *
+ * 1. **The detail is a diagnostic and must never fail a call.** A hook that
+ *    throws, returns a non-string, or returns nothing usable yields no detail
+ *    and the tool dispatches unchanged.
+ * 2. **Normalization is not delegated to tool authors.** Thirty authors would
+ *    each get the line breaks, the control characters, the secret redaction, and
+ *    the length cap slightly wrong. Here it is one auditable path.
+ */
+import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
+/**
+ * The length cap, in characters. A full workspace path with a line range fits
+ * comfortably; a `write_file` content field does not, which is the point — a
+ * hook author who returns a payload cannot push it to a host through this
+ * channel.
+ */
+export const DETAIL_MAX_LENGTH = 120;
+/**
+ * Cap `text` at `max` CODE POINTS, not UTF-16 units.
+ *
+ * `String.prototype.slice` cuts at a fixed unit index, which can land between the
+ * two halves of a surrogate pair and emit a lone surrogate — a terminal paints
+ * that as a replacement character, so the cap would corrupt the very tail it is
+ * supposed to merely shorten. Iterating the string yields whole code points.
+ *
+ * Code points, not display columns, is the right unit here: this cap is a safety
+ * valve against a runaway hook, so its job is to bound the payload. A column
+ * measurement would claim knowledge of the renderer's font metrics that the
+ * harness does not have — the host measures columns, because only the host knows
+ * how wide its own line is.
+ */
+function capCodePoints(text, max) {
+    const points = Array.from(text);
+    return points.length <= max ? text : points.slice(0, max).join("").trimEnd();
+}
+/**
+ * Normalize whatever a hook returned into an emittable detail, or `undefined`.
+ *
+ * In order: reject anything that is not a usable string, strip control
+ * characters, collapse to one line, redact secrets, then cap the length.
+ *
+ * The control-character strip is the harness's existing `normalizeUnicode`,
+ * which is also what the chat route applies to user prose — a detail is
+ * rendered by a host, so a terminal escape sequence in it is an injection.
+ * Redaction runs before the cap, so a secret cannot survive by being cut in
+ * half, and after the strip, so an embedded control byte cannot break a pattern.
+ */
+export function normalizeDetail(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    // `normalizeUnicode` leaves tab, newline and carriage return in place (they
+    // are legitimate whitespace in prose); the collapse below is what turns them
+    // into the single line this contract promises.
+    const oneLine = normalizeUnicode(raw).replace(/\s+/g, " ").trim();
+    if (oneLine.length === 0)
+        return undefined;
+    const capped = capCodePoints(redactSecrets(oneLine), DETAIL_MAX_LENGTH);
+    return capped.length === 0 ? undefined : capped;
+}
+/**
+ * Compute a tool call's detail, best-effort.
+ *
+ * `rawInput` is unvalidated model output: the loop emits `tool-started` before
+ * `dispatchTools` parses anything, so the value here has satisfied no schema
+ * yet. The hook declares its parameter as `z.infer<Schema>`, so it is called
+ * ONLY on a successful `safeParse` — without that, the declared type would be a
+ * lie and author-written code would run over arbitrary shapes.
+ *
+ * A call the loop repairs later (`repairToolInput`) therefore emits no detail.
+ * That is accepted: repair is a rare recovery path, and computing the detail a
+ * second time from the repaired value costs more than the case is worth.
+ */
+export function computeDetail(tool, rawInput, log) {
+    const describeCall = tool.describeCall;
+    if (describeCall === undefined)
+        return undefined;
+    try {
+        // The parse is INSIDE the guard, not before it. `safeParse` returns an
+        // error for a rejected value but THROWS for a schema it cannot run
+        // synchronously: an async refinement raises "Encountered Promise during
+        // synchronous parse", and a refinement whose predicate throws raises
+        // whatever it threw. Refinements survive `defineTool` because
+        // `z.toJSONSchema` ignores them, so such a schema reaches here intact —
+        // and a tool list is open, since an embedder contributes its own through
+        // the host-tools seam. Outside the guard that throw would escape the loop
+        // and kill the turn. A description must never be able to fail a call.
+        const parsed = tool.inputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return undefined;
+        return normalizeDetail(describeCall(parsed.data));
+    }
+    catch (err) {
+        // `debug`, not `warn`: a broken description is a cosmetic defect in one
+        // tool, and the turn it happened in succeeded.
+        log.debug("describeCall failed", { tool: tool.id, ...log.errorFields(err) });
+        return undefined;
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * One classification of how a tool call ended, shared by every surface that
+ * reports it.
+ *
+ * The live loop reads it off the `ToolResultPart` it just built; the reload
+ * converter reads it off the same part after a round trip through storage. They
+ * resolve through this function so a reloaded call cannot report an outcome the
+ * live call never had — the defect this replaces was exactly that, with reload
+ * reporting success for every call because it never looked at the result at all.
+ */
+import type { ToolOutcome } from "../contracts/chat-events.js";
+export type { ToolOutcome };
+/**
+ * Classify a tool result's output type.
+ *
+ * `execution-denied` is the user's own decision and stays distinct from a fault.
+ * `error-text` / `error-json` are the model-visible error results the loop
+ * builds from a thrown failure, an `err(ToolError)`, or rejected input.
+ * Everything else — including an expected "not found" data variant — is `ok`.
+ */
+export declare function toolOutcomeForOutputType(outputType: string): ToolOutcome;

package/dist/loop/tool-outcome.js

@@ -0,0 +1,25 @@
+/**
+ * One classification of how a tool call ended, shared by every surface that
+ * reports it.
+ *
+ * The live loop reads it off the `ToolResultPart` it just built; the reload
+ * converter reads it off the same part after a round trip through storage. They
+ * resolve through this function so a reloaded call cannot report an outcome the
+ * live call never had — the defect this replaces was exactly that, with reload
+ * reporting success for every call because it never looked at the result at all.
+ */
+/**
+ * Classify a tool result's output type.
+ *
+ * `execution-denied` is the user's own decision and stays distinct from a fault.
+ * `error-text` / `error-json` are the model-visible error results the loop
+ * builds from a thrown failure, an `err(ToolError)`, or rejected input.
+ * Everything else — including an expected "not found" data variant — is `ok`.
+ */
+export function toolOutcomeForOutputType(outputType) {
+    if (outputType === "execution-denied")
+        return "denied";
+    if (outputType === "error-text" || outputType === "error-json")
+        return "error";
+    return "ok";
+}

package/dist/loop/types.d.ts

@@ -8,6 +8,7 @@
  * The loop body itself knows nothing about DBOS, HTTP, or memory.
  */
 import type { ModelMessage } from "ai";
+import type { ToolCallDetail, ToolOutcome } from "../contracts/chat-events.js";
 import type { ChatStreamEvent } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
 /**
@@ -61,12 +62,25 @@ export type EmitEvent = {
     readonly toolUseId: string;
     readonly name: string;
     readonly input: unknown;
+    /**
+     * One line naming what this call is doing, from the tool's own
+     * `describeCall` hook. Absent — never empty — when the tool declares no
+     * hook or the detail could not be produced (see `tool-detail.ts`).
+     */
+    readonly detail?: ToolCallDetail;
 } | {
     readonly type: "tool-finished";
     readonly source: EventSource;
     readonly toolUseId: string;
     readonly name: string;
-    readonly isError: boolean;
+    /**
+     * How the call ended. Three states rather than an error boolean: a
+     * denial is the user's decision, not a fault, and the loop already
+     * treats the two differently in control flow.
+     */
+    readonly outcome: ToolOutcome;
+    /** The same detail the matching `tool-started` carried. */
+    readonly detail?: ToolCallDetail;
 };
 /**
  * A UI presentation event a tool streams to chat — an AI-SDK `data-*`