agentfootprint-lens 0.42.0 → 0.44.0

package/README.md

@@ -111,6 +111,20 @@ Lens watches agentfootprint's typed event stream — `agentfootprint.agent.*`,
 of the 65-type registry. You never wire events yourself; `recorder.observe()`
 subscribes to all of them.
 
+**A long tool call is no longer a silence.** When a tool reports from inside
+its own `execute` with `ctx.progress(payload)` (agentfootprint 9.52+), each
+report lands in the stream between that call's start and its end:
+
+```
+`walk_graph` reported progress (iteration 1): {"hop":1,"of":3,"node":"svc-a"}
+```
+
+The three identity fields are stamped by the framework, so the line states them
+as facts. The payload is the tool author's own data — the Lens shows a preview
+of it rather than guessing at a shape it was never promised, and says so when
+it had to cut one short. A tool that never calls `ctx.progress` files nothing,
+and nothing here invents a report it did not make.
+
 ---
 
 ## Multiple watchers, one agent
@@ -586,6 +600,83 @@ a Vue or CLI shell.
 
 ---
 
+## Scrubbing without dead air — snap stops
+
+Sharing an axis is not the same as sharing a stride.
+
+A view mounted inside the lens scrubs the **host's** axis — that is the
+one-cursor law working correctly. But the host's axis is the *run's*. A
+four-tool turn puts 73 stops on it, and a view like the Skill Graph changes at
+eight of them: 65 presses of ◀ ▶ walk framework stages that change nothing in
+its picture. The scrubbing is not wrong, it is **dead air**.
+
+The fix that must not be taken is a second slider with its own numbers. Two
+transports over one run is the drift this package refuses. So pass `snapSteps` —
+an ascending list of positions on the axis the transport **already has** — and
+only the step buttons' landing set narrows:
+
+```tsx
+<TimeTravel
+  total={73}
+  focusSeq={step}
+  onFocusChange={setStep}
+  isLive={false}
+  // ◀ ▶ and ← → now land only here. Everything else is untouched.
+  snapSteps={[0, 9, 17, 31, 44, 58, 72]}
+/>
+```
+
+What stays true when it is set:
+
+- **the drag track and the step strip keep the full axis** — every position is
+  still reachable, just not by ◀ ▶;
+- **Home / End still go to the axis endpoints**, because they are jumps, not
+  steps (band clicks and strip clicks are jumps too, and also unaffected);
+- **a position between two stops is disclosed, never rounded down.** Drag to a
+  step no stop covers and the readout says so — `between stops 2 and 3 of 4 ·
+  8 / 12` — because with the buttons narrowed, that is a position they cannot
+  reproduce and the reader has to be told;
+- **nothing is stored.** The position is still the host's `step`, and every
+  move still leaves through `onFocusChange(step)`.
+
+Entries the axis cannot hold (negative, past the end, non-integer) are ignored —
+a stop the axis does not have is not a stop. An empty list, or one whose entries
+are all off-axis, behaves exactly as passing nothing.
+
+`snapSteps` is orthogonal to `bands`: bands **group** the axis, snaps narrow the
+unit of **movement** along it. Set both and the readout names all three truths —
+`Iteration 2 · stop 3 of 4 · 10 / 12`.
+
+`<SkillGraphDebugger>` forwards the same prop to the transport it mounts, so a
+host can hand it the steps its routing picture actually changes at:
+
+```tsx
+import { selectSkillBeats, selectSkillRoute, stepForRuntimeStageId } from 'agentfootprint-lens/skillgraph';
+
+const beats = selectSkillBeats({ route: selectSkillRoute({ log: recorder.selectEventLog() }) });
+const snapSteps = [
+  ...new Set(
+    beats
+      .map((b) => (b.runtimeStageId !== undefined ? stepForRuntimeStageId(positions, b.runtimeStageId) : -1))
+      .filter((s) => s >= 0),
+  ),
+].sort((a, b) => a - b);
+
+<SkillGraphDebugger step={step} totalSteps={totalSteps} onStepChange={onNavigate} snapSteps={snapSteps} … />
+```
+
+The host builds the list because the host owns the axis. On the debugger the
+prop is **ignored when it is scrubbing its own routing stops** (no `step` /
+`totalSteps`) — every routing stop already changes the picture, so there is
+nothing to narrow.
+
+Headless: `snapPositionOf`, `nextSnapStep` and `prevSnapStep` on
+`agentfootprint-lens/core` are the pure queries behind it — the same
+at-or-before resolution (with its `exact` flag) and the same strict
+next/previous laws, for a shell that draws its own transport.
+
+---
+
 ## Driving the cursor from your app
 
 **Omitting these props keeps the lens self-driving.** It holds the position

package/dist/{chunk-VKBQYD6I.js → chunk-5YSPWSLW.js}

@@ -1,7 +1,7 @@
 import {
   formatBytes,
   structureGraphFromRunner
-} from "./chunk-JE37MDVV.js";
+} from "./chunk-CGR5VFJU.js";
 
 // src/core/buildStepGraphFromSnapshot.ts
 function buildStepGraphFromSnapshot(snapshot) {
@@ -1189,4 +1189,4 @@ export {
   decisionSentence,
   isConsentDecision
 };
-//# sourceMappingURL=chunk-VKBQYD6I.js.map
+//# sourceMappingURL=chunk-5YSPWSLW.js.map

package/dist/{chunk-JE37MDVV.js → chunk-CGR5VFJU.js}

@@ -3,7 +3,7 @@ import {
   humanizeRouteConflict,
   humanizeSkillRejected,
   humanizeTurnRouted
-} from "./chunk-VBRT372Q.js";
+} from "./chunk-LCIEJYZG.js";
 import {
   selectAgentInstances
 } from "./chunk-2JAWSPNG.js";
@@ -1464,6 +1464,36 @@ function humanizeEvidenceChecked(p) {
   }
 }
 
+// src/core/humanizeToolProgress.ts
+var PREVIEW_LIMIT = 120;
+function previewProgressPayload(payload) {
+  if (payload === void 0) return null;
+  let text;
+  if (typeof payload === "string") {
+    text = payload;
+  } else {
+    try {
+      const json = JSON.stringify(payload);
+      if (json === void 0) return null;
+      text = json;
+    } catch {
+      return "(payload could not be shown)";
+    }
+  }
+  if (text.length <= PREVIEW_LIMIT) return text;
+  return `${text.slice(0, PREVIEW_LIMIT)}\u2026 (truncated; ${text.length - PREVIEW_LIMIT} more chars)`;
+}
+function humanizeToolProgress(payload) {
+  const tool = payload.toolName !== void 0 ? `\`${payload.toolName}\`` : "A tool";
+  const iter = typeof payload.iteration === "number" && payload.iteration > 0 ? ` (iteration ${payload.iteration})` : "";
+  const preview = previewProgressPayload(payload.payload);
+  return preview === null ? `${tool} reported progress${iter}.` : `${tool} reported progress${iter}: ${preview}`;
+}
+function humanizeToolProgressTeaching(payload) {
+  const tool = payload.toolName !== void 0 ? `The \`${payload.toolName}\` tool` : "A tool";
+  return `${tool} reported progress while it was still running.`;
+}
+
 // src/core/humanizeArtifacts.ts
 var ticket = (ref, kind, bytes) => `${ref ?? "art_?"} [${kind ?? "?"} \xB7 ${formatBytes(bytes ?? 0)}]`;
 function humanizeArtifactMinted(p) {
@@ -1552,6 +1582,12 @@ var defaultHumanizer = (event) => {
       return `Model replied in ${event.payload.durationMs}ms (${event.payload.usage.input}+${event.payload.usage.output} tokens, ${event.payload.toolCallCount} tool calls, stop: ${event.payload.stopReason}).`;
     case "agentfootprint.stream.tool_start":
       return `Calling tool "${event.payload.toolName}" with ${JSON.stringify(event.payload.args)}.`;
+    // One report from INSIDE a still-running tool call (agentfootprint
+    // 9.52.0). It arrives between this call's tool_start and its tool_end, so
+    // the stream reads as the call speaking mid-flight. See humanizeToolProgress
+    // for why the author's payload is previewed rather than interpreted.
+    case "agentfootprint.stream.tool_progress":
+      return humanizeToolProgress(event.payload);
     case "agentfootprint.stream.tool_end":
       return `Tool "${event.payload.toolCallId}" returned in ${event.payload.durationMs}ms${event.payload.error === true ? " (error)" : ""}.`;
     case "agentfootprint.stream.token":
@@ -1626,6 +1662,9 @@ function makeTeachingHumanizer(options = {}) {
   const templates = options.commentaryTemplates ? { ...defaultCommentaryTemplates, ...options.commentaryTemplates } : defaultCommentaryTemplates;
   const ctx = { appName, getToolDescription };
   return (event) => {
+    if (event.type === "agentfootprint.stream.tool_progress") {
+      return humanizeToolProgressTeaching(event.payload);
+    }
     const key = selectCommentaryKey(event);
     if (key === null) return null;
     if (key === void 0) return defaultHumanizer(event);
@@ -2765,4 +2804,4 @@ export {
   structureGraphFromSpec,
   cursorProvenance
 };
-//# sourceMappingURL=chunk-JE37MDVV.js.map
+//# sourceMappingURL=chunk-CGR5VFJU.js.map