agentfootprint-lens 0.38.0 → 0.40.0

package/README.md

@@ -68,6 +68,28 @@ Swap `mock(...)` for `anthropic(...)` / `openai(...)` / `ollama(...)` from
 
 ---
 
+## Doors
+
+Two subpath imports name the lens you are mounting. They are additions —
+everything behind them is also on the root barrel, and the root barrel never
+changes.
+
+| import | the job |
+|---|---|
+| `agentfootprint-lens/why` | Replay a recording as the agent's own milestones. `<WhyLens recording={...} />` takes the recording straight (`recordRun()`'s `{ snapshot, events, structure }`, or the `persistRecording` envelope), validates it at mount, and mounts the shipped `<Lens>` shell on the milestone axis — plus the axis helpers (`scrubAxisFor`, `stepForCommitIdx`, `stepForRuntimeStageId`) for hosts holding one cursor across views. |
+| `agentfootprint-lens/skillgraph` | Debug how a run routed through its skills. `<SkillGraphDebugger recorder={...} />` plus its headless selectors (`selectSkillRoute`, `selectSkillBeats`, `selectSkillTopology`, `selectSkillFrameContext`, `stepForRuntimeStageId`). |
+
+The axis model in three sentences: one run leaves one causal trace, and each
+lens replays one AXIS of it — the Why reading scrubs the milestones, the Flow
+reading scrubs every committed stage, the skill door scrubs the routing stops.
+The cursor and the commentary are shared: a position travels between axes by
+its commit index (`scrubAxisFor` + `stepForCommitIdx`), never by copying a
+step number from one ruler to another. Hand a door the wrong thing and it
+says so on screen — what it received and where to go — instead of rendering
+a blank panel.
+
+---
+
 ## What you actually see
 
 The default view (`view="engineer"`) is one screen:
@@ -505,9 +527,12 @@ pane.
 
 ## Scrubbing by group — the active group is a named place
 
-One causal trace, replayed at two zoom levels. On the **per-step** ruler each
-commit is a stop; on the **grouped** ruler each boundary is a stop, and ◀ ▶ moves
-a whole group at a time.
+One causal trace, replayed at two zoom levels. On the **per-step** ruler every
+executed stage is a stop — the commit trace itself, nothing skippable, so the
+ruler's count is the run's stage count. On the **grouped** ruler the stops are
+the agent's milestones (iteration, context, LLM turn, route, tool call), drawn
+as labelled iteration bands; ◀ ▶ still move one stop at a time, and clicking a
+band jumps to its first stop.
 
 The chart used to paint both the same way, and that was wrong for the second one.
 A stage's styling is by TYPE — the LLM call carries a hero emphasis (accent

package/dist/chunk-2JAWSPNG.js

@@ -0,0 +1,73 @@
+// src/core/selectors/selectAgentInstances.ts
+function selectAgentInstances(graph) {
+  const allBoundaries = graph.nodes.filter((n) => n.isPrimitiveBoundary === true);
+  if (allBoundaries.length === 0) {
+    const rootSubflow = graph.nodes.find((n) => n.kind === "subflow");
+    const primitiveKind = rootSubflow?.primitiveKind;
+    return [
+      {
+        groupId: "agent-root",
+        llmId: "stage-llm-root",
+        toolId: "stage-tool-root",
+        label: primitiveKind ?? "Runner",
+        subflowPath: [],
+        ...primitiveKind ? { primitiveKind } : {}
+      }
+    ];
+  }
+  const boundaries = allBoundaries.filter(
+    (b) => !allBoundaries.some(
+      (other) => other !== b && isStrictDescendant(other.subflowPath, b.subflowPath)
+    )
+  );
+  return boundaries.map((b) => ({
+    groupId: `agent-group-${b.id}`,
+    llmId: `stage-llm-${b.id}`,
+    toolId: `stage-tool-${b.id}`,
+    label: b.label,
+    subflowPath: b.subflowPath,
+    ...b.primitiveKind ? { primitiveKind: b.primitiveKind } : {}
+  }));
+}
+function isStrictDescendant(child, parent) {
+  if (child.length <= parent.length) return false;
+  for (let i = 0; i < parent.length; i++) {
+    if (child[i] !== parent[i]) return false;
+  }
+  return true;
+}
+
+// src/core/selectors/selectStepAgentName.ts
+function cleanLabel(label) {
+  return label.replace(/^step-/, "");
+}
+function selectStepAgentName(step, agents) {
+  if (agents.length < 2) return void 0;
+  const stepPath = step.subflowPath ?? [];
+  if (stepPath.length === 0) return void 0;
+  let best;
+  let bestDepth = -1;
+  for (const agent of agents) {
+    const ap = agent.subflowPath;
+    if (ap.length === 0) continue;
+    if (!isPrefix(ap, stepPath)) continue;
+    if (ap.length > bestDepth) {
+      best = agent;
+      bestDepth = ap.length;
+    }
+  }
+  return best ? cleanLabel(best.label) : void 0;
+}
+function isPrefix(prefix, path) {
+  if (prefix.length > path.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (prefix[i] !== path[i]) return false;
+  }
+  return true;
+}
+
+export {
+  selectAgentInstances,
+  selectStepAgentName
+};
+//# sourceMappingURL=chunk-2JAWSPNG.js.map

package/dist/chunk-2JAWSPNG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/selectors/selectAgentInstances.ts","../src/core/selectors/selectStepAgentName.ts"],"sourcesContent":["/**\n * `selectAgentInstances` — derive AgentInstance[] from a StepGraph.\n *\n * Pattern: pure function over the `isPrimitiveBoundary` flag that\n *          agentfootprint sets on every subflow StepNode whose root\n *          description carries a known `<Kind>:` prefix (Agent /\n *          LLMCall / Sequence / Parallel / Conditional / Loop).\n *          Single-primitive runs produce one synthetic root instance;\n *          composed runs produce one per primitive subflow.\n * Role:    Feeds the top-level agent-grouping layer in Lens (one\n *          container per primitive instance). Framework-agnostic.\n *\n * Naming: kept as `selectAgentInstances` for backwards compatibility —\n * \"Agent\" here means \"an outlined container in the run-tree view,\" not\n * specifically \"ReAct agent.\" The narrow flag (`isAgentBoundary`)\n * remains available on each StepNode for callers that care about the\n * distinction (cost / iteration attribution).\n */\n\nimport type { StepGraph } from 'agentfootprint/observe';\nimport type { AgentInstance } from './types.js';\n\n/**\n * Produce one AgentInstance per primitive boundary in the graph.\n *\n * Derivation:\n *   - If ANY StepNode has `isPrimitiveBoundary === true`, use those.\n *     Their `id` becomes the instance's `subflowPath` root segment.\n *   - Otherwise, synthesize a single root instance covering the run.\n *     Matches the common case of a standalone primitive run (e.g., a\n *     standalone LLMCall whose chart has no top-level subflow).\n *\n * Each instance carries a `primitiveKind` (when the StepGraph supplies\n * one) so the renderer picks the correct icon + subtitle:\n *   - Agent boundary       → `'Agent'`       → `'🤖 Agent · ReAct loop'`\n *   - LLMCall boundary     → `'LLMCall'`     → `'📡 LLMCall · one-shot'`\n *   - Sequence boundary    → `'Sequence'`    → `'➡️ Sequence · pipeline'`\n *   - Parallel boundary    → `'Parallel'`    → `'🔀 Parallel · fan-out'`\n *   - Conditional boundary → `'Conditional'` → `'🪧 Conditional · route'`\n *   - Loop boundary        → `'Loop'`        → `'🔁 Loop · iterate'`\n *\n * IDs are stable within a run — safe to use as React keys.\n */\nexport function selectAgentInstances(graph: StepGraph): AgentInstance[] {\n  const allBoundaries = graph.nodes.filter((n) => n.isPrimitiveBoundary === true);\n  if (allBoundaries.length === 0) {\n    // Synthetic root — peek at the first subflow node's `primitiveKind`\n    // so we can label the container by what's actually running, not a\n    // hardcoded `'Agent'`. Falls back to `'Runner'` when the graph\n    // carries no taxonomy metadata.\n    const rootSubflow = graph.nodes.find((n) => n.kind === 'subflow');\n    const primitiveKind = rootSubflow?.primitiveKind;\n    return [\n      {\n        groupId: 'agent-root',\n        llmId: 'stage-llm-root',\n        toolId: 'stage-tool-root',\n        label: primitiveKind ?? 'Runner',\n        subflowPath: [],\n        ...(primitiveKind ? { primitiveKind } : {}),\n      },\n    ];\n  }\n\n  // LEAF-filter: keep only the DEEPEST primitive boundaries — the ones\n  // that actually do work. Drop composition wrappers (Sequence /\n  // Parallel / Conditional / Loop) when at least one of their children\n  // is itself a primitive boundary, since the children fully describe\n  // the run.\n  //\n  // Examples:\n  //   Sequence(LLMCall a, LLMCall b)        → [a, b]    (Sequence dropped)\n  //   Parallel(LLMCall x, LLMCall y, LLMCall z) → [x, y, z] (Parallel dropped)\n  //   Conditional(when a / otherwise b)     → [a] OR [b] (only the chosen\n  //                                                       runs has events;\n  //                                                       boundaries with\n  //                                                       no descendants\n  //                                                       in graph.nodes\n  //                                                       fall through)\n  //   Loop(body)                            → [body]   (Loop dropped — the\n  //                                                     body is the unit of\n  //                                                     work)\n  //   Standalone Agent / LLMCall / RAG run  → [self]   (no nested primitive,\n  //                                                     so it's already a leaf)\n  const boundaries = allBoundaries.filter((b) =>\n    !allBoundaries.some(\n      (other) =>\n        other !== b &&\n        isStrictDescendant(other.subflowPath, b.subflowPath),\n    ),\n  );\n\n  return boundaries.map((b) => ({\n    groupId: `agent-group-${b.id}`,\n    llmId: `stage-llm-${b.id}`,\n    toolId: `stage-tool-${b.id}`,\n    label: b.label,\n    subflowPath: b.subflowPath,\n    ...(b.primitiveKind ? { primitiveKind: b.primitiveKind } : {}),\n  }));\n}\n\n/** True iff `child` is strictly deeper than `parent` (parent is a proper\n *  prefix of child). Used to detect \"is this boundary nested inside another\n *  boundary\" so we can drop the wrapper. */\nfunction isStrictDescendant(\n  child: readonly string[],\n  parent: readonly string[],\n): boolean {\n  if (child.length <= parent.length) return false;\n  for (let i = 0; i < parent.length; i++) {\n    if (child[i] !== parent[i]) return false;\n  }\n  return true;\n}\n","/**\n * `selectStepAgentName` — pick the human-friendly agent name a step\n * \"belongs to\" in a multi-agent run.\n *\n * Pattern: walk the agent list, prefix-match the step's `subflowPath`,\n *          and return the deepest matching agent's label. Used to\n *          enrich step labels in multi-agent contexts so callers can\n *          render \"user → classify\" instead of generic \"user → llm\".\n *\n * Returns `undefined` for single-agent runs (caller falls back to the\n * step's own label) and for steps that don't lift to any agent (root\n * synthetic nodes, the User actor, etc.).\n */\n\nimport type { StepNode } from \"agentfootprint/observe\";\nimport type { AgentInstance } from \"./types.js\";\n\n/**\n * Strip `'step-'` prefix that Sequence stages get from the runtime\n * (so `'step-classify'` reads as `'classify'`). Matches the breadcrumb\n * convention in Lens.tsx and the `extractAgentName` humanizer\n * convention from agentfootprint v2.14.4.\n */\nfunction cleanLabel(label: string): string {\n  return label.replace(/^step-/, \"\");\n}\n\n/**\n * Find the agent whose `subflowPath` is the deepest prefix of the\n * step's `subflowPath`. Returns the cleaned label of that agent or\n * `undefined` when no agent matches (or only ONE agent exists, in\n * which case the caller already shows the agent in the container\n * header and prefixing every step would be redundant).\n */\nexport function selectStepAgentName(\n  step: StepNode,\n  agents: readonly AgentInstance[],\n): string | undefined {\n  if (agents.length < 2) return undefined;\n  const stepPath = step.subflowPath ?? [];\n  if (stepPath.length === 0) return undefined;\n\n  let best: AgentInstance | undefined;\n  let bestDepth = -1;\n  for (const agent of agents) {\n    const ap = agent.subflowPath;\n    if (ap.length === 0) continue;\n    if (!isPrefix(ap, stepPath)) continue;\n    if (ap.length > bestDepth) {\n      best = agent;\n      bestDepth = ap.length;\n    }\n  }\n  return best ? cleanLabel(best.label) : undefined;\n}\n\nfunction isPrefix(prefix: readonly string[], path: readonly string[]): boolean {\n  if (prefix.length > path.length) return false;\n  for (let i = 0; i < prefix.length; i++) {\n    if (prefix[i] !== path[i]) return false;\n  }\n  return true;\n}\n"],"mappings":";AA2CO,SAAS,qBAAqB,OAAmC;AACtE,QAAM,gBAAgB,MAAM,MAAM,OAAO,CAAC,MAAM,EAAE,wBAAwB,IAAI;AAC9E,MAAI,cAAc,WAAW,GAAG;AAK9B,UAAM,cAAc,MAAM,MAAM,KAAK,CAAC,MAAM,EAAE,SAAS,SAAS;AAChE,UAAM,gBAAgB,aAAa;AACnC,WAAO;AAAA,MACL;AAAA,QACE,SAAS;AAAA,QACT,OAAO;AAAA,QACP,QAAQ;AAAA,QACR,OAAO,iBAAiB;AAAA,QACxB,aAAa,CAAC;AAAA,QACd,GAAI,gBAAgB,EAAE,cAAc,IAAI,CAAC;AAAA,MAC3C;AAAA,IACF;AAAA,EACF;AAsBA,QAAM,aAAa,cAAc;AAAA,IAAO,CAAC,MACvC,CAAC,cAAc;AAAA,MACb,CAAC,UACC,UAAU,KACV,mBAAmB,MAAM,aAAa,EAAE,WAAW;AAAA,IACvD;AAAA,EACF;AAEA,SAAO,WAAW,IAAI,CAAC,OAAO;AAAA,IAC5B,SAAS,eAAe,EAAE,EAAE;AAAA,IAC5B,OAAO,aAAa,EAAE,EAAE;AAAA,IACxB,QAAQ,cAAc,EAAE,EAAE;AAAA,IAC1B,OAAO,EAAE;AAAA,IACT,aAAa,EAAE;AAAA,IACf,GAAI,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,IAAI,CAAC;AAAA,EAC9D,EAAE;AACJ;AAKA,SAAS,mBACP,OACA,QACS;AACT,MAAI,MAAM,UAAU,OAAO,OAAQ,QAAO;AAC1C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,QAAI,MAAM,CAAC,MAAM,OAAO,CAAC,EAAG,QAAO;AAAA,EACrC;AACA,SAAO;AACT;;;AC3FA,SAAS,WAAW,OAAuB;AACzC,SAAO,MAAM,QAAQ,UAAU,EAAE;AACnC;AASO,SAAS,oBACd,MACA,QACoB;AACpB,MAAI,OAAO,SAAS,EAAG,QAAO;AAC9B,QAAM,WAAW,KAAK,eAAe,CAAC;AACtC,MAAI,SAAS,WAAW,EAAG,QAAO;AAElC,MAAI;AACJ,MAAI,YAAY;AAChB,aAAW,SAAS,QAAQ;AAC1B,UAAM,KAAK,MAAM;AACjB,QAAI,GAAG,WAAW,EAAG;AACrB,QAAI,CAAC,SAAS,IAAI,QAAQ,EAAG;AAC7B,QAAI,GAAG,SAAS,WAAW;AACzB,aAAO;AACP,kBAAY,GAAG;AAAA,IACjB;AAAA,EACF;AACA,SAAO,OAAO,WAAW,KAAK,KAAK,IAAI;AACzC;AAEA,SAAS,SAAS,QAA2B,MAAkC;AAC7E,MAAI,OAAO,SAAS,KAAK,OAAQ,QAAO;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,QAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAG,QAAO;AAAA,EACpC;AACA,SAAO;AACT;","names":[]}