agentfootprint-lens 0.34.0 → 0.36.0

package/README.md

@@ -436,6 +436,131 @@ prose via the default humanizer.
 
 ---
 
+## Answer a paused run with a real component (typed HITL)
+
+agentfootprint 9.24 taught every human-ask door (`askHuman`, the `ask`
+middleware, `defineTool({ checkInComponent })`) to carry an optional typed
+half beside the prose question: `{ componentId, props?, propsRef? }`. The id
+names a component **your screen registered** — ids + props, never markup the
+model wrote, the same no-eval law artifacts follow. Small props ride the ask
+inline; the big half (a 200-option picker's options) rides the **artifact
+store** as a `propsRef` claim ticket, redeemed through the same resolver and
+the same session identity as every other artifact.
+
+`<AwaitingPane>` is the screen's half:
+
+```tsx
+import {
+  AwaitingPane,
+  decisionRequestBody,
+  httpArtifactResolver,
+  registerDecisionComponent,
+} from 'agentfootprint-lens';
+
+// 1. Teach Lens your collectors, once at startup. ('option-picker' ships.)
+registerDecisionComponent({
+  componentId: 'refund-form',
+  component: ({ question, props, data, respond }) => (
+    <MyRefundForm limits={props} rows={data} onSubmit={(answer) => respond(answer)} />
+  ),
+});
+
+// 2. When a reply comes back awaiting, render the pane. The lens does NOT
+//    own the POST — your app does; decisionRequestBody formats the body.
+const resolver = httpArtifactResolver({ url: '/invoke', sessionId });
+<AwaitingPane
+  awaiting={reply.awaiting}
+  resolver={resolver}
+  onDecision={(decision) =>
+    fetch('/invoke', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(decisionRequestBody({ decision, sessionId })),
+    })
+  }
+/>
+```
+
+The person clicks; `onDecision` receives **the structured decision** — the
+option's id, or the approve/decline record (`approveDecision` /
+`declineDecision`, byte-compatible with agentfootprint's check-in
+vocabulary). After answering, the pane renders the decision as one sentence —
+*"Approved by alice@ops — 'verified'."* — which is **display only**: the
+structured decision is the record; the words are a rendering of it.
+
+Nothing on this road dead-ends the human. An unknown `componentId` falls back
+to the prose question plus a plain answer box and *says so*; an expired
+`propsRef` renders the honest placeholder plus the answer box; a crashed
+registered component is caught and stated; a consent gate (`checkIn` /
+middleware `ask`) falls back to Approve/Decline with a required "deciding as"
+field, because an audit record with no actor names nobody.
+
+The headless half is on `agentfootprint-lens/core` — `readAwaitingComponent`
+(era-robust: reads `awaiting.component` and the three `pauseData` homes),
+`approveDecision` / `declineDecision`, `decisionRequestBody`,
+`decisionSentence`, `isConsentAsk` — so a Vue or CLI shell can build the same
+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.
+
+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
+border, tint, glow) and the cursor's one node pulses — so landing on a group of
+six nodes pulled the eye to the LLM box. The group, the thing the ruler had
+actually moved by, never read as the position at all.
+
+Pass `granularity="group"` and it does:
+
+- **one accent for every member.** An LLM call, a tool and a context pill light
+  identically — same tint, same intensity. What a node IS stays legible in its
+  icon and its shape; how loud it is no longer depends on its type.
+- **everything else recedes uniformly** — one dim, not a second ranking.
+- **a boundary is drawn around the members**, from their real measured positions,
+  with the group's **name** on its top edge. Scrubbing group to group animates it
+  (and doesn't, under `prefers-reduced-motion: reduce`).
+
+The name is `groupDisplayName` — the same spelling the WHAT HAPPENED boundary
+list uses. One place, one name.
+
+```tsx
+<Lens recorder={recorder} runner={runner} granularity="group" />
+```
+
+Or, in a shell that owns its own canvas and its own cursor:
+
+```tsx
+import { LensFlow, useChartGroup } from 'agentfootprint-lens';
+
+function WhyLensChart({ recorder, chart, cursorCommitIdx }) {
+  // The group the cursor stands in, as chart node ids. Derived from the
+  // boundary ranges the grouped ruler already computes its stops from —
+  // no extra fetch, no second cursor.
+  const group = useChartGroup(recorder, cursorCommitIdx);
+  return <LensFlow chart={chart} granularity="group" activeGroup={group} />;
+}
+```
+
+`granularity` defaults to `'step'`, and on that path nothing changes: no classes,
+no boundary, the same chart the Flow Lens has always drawn. `'group'` at a commit
+no boundary encloses also renders as `'step'` — a mode with nothing to draw draws
+nothing, rather than boxing the whole chart.
+
+Restyle it with one variable (`--lens-group-accent`, falling back to
+`--fp-group-accent`), or target the classes directly: `.lens-group-node--member`,
+`.lens-group-node--outsider`, `.lens-group-boundary`, `.lens-group-boundary-name`.
+
+Headless: `activeChartGroup({ groups, commits, commitIdx })` on
+`agentfootprint-lens/core` is the pure function behind the hook — same answer for
+a Vue or CLI shell.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -547,6 +672,25 @@ graph in one call. Returns an unsubscribe. Call it once per run.
 | `chart` | `LensFlowProps['chart']?` | Render YOUR graph instead of the derived one. |
 | `stepGraph` | `StepGraph?` | Bring your own step graph; by default Lens uses the recorder's. |
 | `toolChoice` | `ToolChoiceSource?` | Mount the per-iteration tool-choice panel. |
+| `granularity` | `'step' \| 'group'?` | Which ruler is scrubbing the chart. `'group'` paints the cursor's group as a named place. Default `'step'`. See [Scrubbing by group](#scrubbing-by-group--the-active-group-is-a-named-place). |
+
+### `<LensFlow>` — the chart canvas on its own
+
+The chart without the shell, for consumers who own their layout and their
+cursor. Takes `chart`, the runtime overlay, the cursor, and — for the grouped
+ruler — `granularity="group"` plus `activeGroup` (from `useChartGroup`). Every
+other prop is unchanged by group mode.
+
+### `useChartGroup(recorder, commitIdx, options?)` / `activeChartGroup(...)`
+
+The group the cursor stands in, resolved to CHART NODE IDS: the boundary's
+commit range read off the recording, each commit's `runtimeStageId` stripped of
+its `#executionIndex` (the id rule every chart-click and co-active highlight in
+the ecosystem already uses), plus the group's own mount. Returns `undefined`
+when no boundary encloses the cursor. `options.includeRoot` opts into the
+synthetic Run root, which is off by default because a box around the whole chart
+states nothing. `activeChartGroup` is the pure, React-free twin on
+`agentfootprint-lens/core`.
 
 ### `observeRecording(recording, options?)`
 
@@ -613,6 +757,23 @@ The headless half — `httpArtifactResolver`, `storeArtifactResolver`,
 `agentfootprint-lens/core`. See
 [Render an artifact by its ref](#render-an-artifact-by-its-ref).
 
+### `<AwaitingPane>` — answer a paused run with a real component
+
+Takes the `awaiting` payload a served agent replied with (`awaiting`), an
+optional `ArtifactResolver` (`resolver`, only needed when the ask ships a
+`propsRef`), and `onDecision` — which receives the person's STRUCTURED
+decision; your app posts it (`decisionRequestBody` formats the wire body).
+Renders the component registered for the ask's `componentId`
+(`registerDecisionComponent({ componentId, component })`) with `{ question,
+props, data, respond }`; `'option-picker'` ships as a built-in. Unknown id,
+expired ref, failed door and crashed component all state themselves and fall
+back to a live answer surface — never a dead end. After answering it renders
+the decision as one sentence (display only; the structured decision is the
+record). The headless half — `readAwaitingComponent`, `approveDecision` /
+`declineDecision`, `decisionRequestBody`, `decisionSentence`, `isConsentAsk`
+— is on `agentfootprint-lens/core`. See
+[Answer a paused run with a real component](#answer-a-paused-run-with-a-real-component-typed-hitl).
+
 ### Headless core
 
 `agentfootprint-lens/core` is React-free: `LensRecorder`, `ChangeNotifier`,

package/dist/{chunk-ZSOYNKUI.js → chunk-EGU4GZVH.js}

@@ -2296,6 +2296,126 @@ function selectToolChoiceCall(calls, cursorRuntimeStageId, cursorKind) {
   return within ?? prev;
 }
 
+// src/core/group/groupDisplayName.ts
+function groupDisplayName(label) {
+  const named = label.subflowName ?? label.compositionName ?? label.primitiveKind;
+  if (named !== void 0 && named !== "") return named;
+  if (label.type === "run.entry") return "Run";
+  return label.runtimeStageId;
+}
+function groupDisplayNameForLabel(label) {
+  return groupDisplayName(label);
+}
+
+// src/core/group/Group.ts
+function groupContainsCommit(group, commitIdx) {
+  if (commitIdx < group.opensAtCommitIdx) return false;
+  if (group.closesAtCommitIdx === void 0) return true;
+  return commitIdx <= group.closesAtCommitIdx;
+}
+
+// src/core/group/activeChartGroup.ts
+function chartNodeIdOf(runtimeStageId) {
+  const hash = runtimeStageId.lastIndexOf("#");
+  return hash < 0 ? runtimeStageId : runtimeStageId.slice(0, hash);
+}
+function activeChartGroup(args) {
+  const { groups, commits, commitIdx, includeRoot = false } = args;
+  if (!Number.isFinite(commitIdx) || commitIdx < 0) return void 0;
+  let best;
+  for (const group of groups) {
+    if (group.isRoot && !includeRoot) continue;
+    if (!groupContainsCommit(group, commitIdx)) continue;
+    if (best === void 0) {
+      best = group;
+      continue;
+    }
+    if (group.depth > best.depth) best = group;
+    else if (group.depth === best.depth && group.opensAtCommitIdx >= best.opensAtCommitIdx) best = group;
+  }
+  if (best === void 0) return void 0;
+  const memberNodeIds = /* @__PURE__ */ new Set();
+  memberNodeIds.add(chartNodeIdOf(best.runtimeGroupId));
+  const from = Math.max(0, best.opensAtCommitIdx);
+  const to = Math.min(commits.length - 1, best.closesAtCommitIdx ?? commits.length - 1);
+  for (let i = from; i <= to; i++) {
+    const rid = commits[i]?.runtimeStageId;
+    if (rid === void 0 || rid === "") continue;
+    memberNodeIds.add(chartNodeIdOf(rid));
+  }
+  return {
+    runtimeGroupId: best.runtimeGroupId,
+    name: best.name,
+    memberNodeIds,
+    opensAtCommitIdx: best.opensAtCommitIdx,
+    closesAtCommitIdx: best.closesAtCommitIdx,
+    depth: best.depth
+  };
+}
+
+// src/core/group/buildGroups.ts
+function samePath(a, b) {
+  return a.length === b.length && a.every((s, i) => s === b[i]);
+}
+function buildGroups(boundaryIndex) {
+  const all = boundaryIndex.overlapping(0, Number.MAX_SAFE_INTEGER);
+  if (all.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (let i = 0; i < all.length; i++) {
+    const entry = all[i];
+    const label = entry.label;
+    if (seen.has(label.runtimeStageId)) continue;
+    seen.add(label.runtimeStageId);
+    let parentGroupId;
+    if (label.type === "subflow.entry") {
+      const enclosing = boundaryIndex.enclosing(entry.startIdx);
+      const parentPath = label.subflowPath.slice(0, -1);
+      for (let j = enclosing.length - 1; j >= 0; j--) {
+        const cand = enclosing[j].label;
+        if (cand.runtimeStageId === label.runtimeStageId) continue;
+        if (samePath(cand.subflowPath, parentPath)) {
+          parentGroupId = cand.runtimeStageId;
+          break;
+        }
+      }
+      if (parentGroupId === void 0) {
+        for (let j = enclosing.length - 1; j >= 0; j--) {
+          const cand = enclosing[j].label;
+          if (cand.runtimeStageId === label.runtimeStageId) continue;
+          parentGroupId = cand.runtimeStageId;
+          break;
+        }
+      }
+    } else if (label.type === "composition.start") {
+      const enclosing = boundaryIndex.enclosing(entry.startIdx);
+      for (let j = enclosing.length - 1; j >= 0; j--) {
+        const cand = enclosing[j].label;
+        if (cand.runtimeStageId === label.runtimeStageId) continue;
+        parentGroupId = cand.runtimeStageId;
+        break;
+      }
+    }
+    const isRoot = label.type === "run.entry";
+    const name = groupDisplayNameForLabel(label);
+    const compositionKind = label.type === "composition.start" ? label.compositionKind : void 0;
+    result.push({
+      runtimeGroupId: label.runtimeStageId,
+      name,
+      parentGroupId,
+      subflowPath: label.subflowPath,
+      depth: label.depth,
+      opensAtCommitIdx: entry.startIdx,
+      closesAtCommitIdx: entry.endIdx,
+      isRoot,
+      ...compositionKind !== void 0 ? { compositionKind } : {},
+      ...label.slotKind !== void 0 ? { slotKind: label.slotKind } : {},
+      ...label.primitiveKind !== void 0 ? { primitiveKind: label.primitiveKind } : {}
+    });
+  }
+  return result;
+}
+
 // src/core/translate/helpers/makeNodeId.ts
 function makeRootNodeId(kind, id) {
   return `${kind.toLowerCase()}:${id}`;
@@ -3367,6 +3487,91 @@ function artifactPlaceholder(presented) {
   return `${describePresented(presented)} \u2014 expired; re-run to regenerate.`;
 }
 
+// src/core/hitl/decision.ts
+function readAwaitingComponent(awaiting) {
+  if (typeof awaiting !== "object" || awaiting === null) return void 0;
+  const pending = awaiting;
+  const direct = asComponent(pending.component);
+  if (direct) return direct;
+  const bag = pending.pauseData;
+  if (typeof bag !== "object" || bag === null) return void 0;
+  const homes = bag;
+  return asComponent(homes.component) ?? asComponent(
+    typeof homes.checkIn === "object" && homes.checkIn !== null ? homes.checkIn.component : void 0
+  ) ?? asComponent(
+    typeof homes.ask === "object" && homes.ask !== null ? homes.ask.component : void 0
+  );
+}
+function asComponent(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const c = value;
+  if (typeof c.componentId !== "string" || c.componentId.length === 0) return void 0;
+  return value;
+}
+function isConsentAsk(awaiting) {
+  if (typeof awaiting !== "object" || awaiting === null) return false;
+  const pending = awaiting;
+  return typeof pending.checkIn === "object" && pending.checkIn !== null || typeof pending.ask === "object" && pending.ask !== null;
+}
+function approveDecision(input) {
+  return buildConsent(true, input, "approveDecision");
+}
+function declineDecision(input) {
+  return buildConsent(false, input, "declineDecision");
+}
+function buildConsent(approved, input, door) {
+  if (typeof input?.by !== "string" || input.by.trim().length === 0) {
+    throw new Error(
+      `${door} needs \`by\` \u2014 who is deciding (an operator id, an email). The decision is an audit record, and a record with no actor names nobody; it cannot be defaulted.`
+    );
+  }
+  return {
+    approved,
+    by: input.by,
+    at: Date.now(),
+    ...input.note !== void 0 && input.note.length > 0 && { note: input.note }
+  };
+}
+function decisionRequestBody(args) {
+  if (args === null || typeof args !== "object" || !("decision" in args)) {
+    throw new Error(
+      "decisionRequestBody needs `decision` \u2014 the structured answer to the pending ask. Its presence is what distinguishes a resume from a new message on the wire."
+    );
+  }
+  if (args.decision === void 0) {
+    throw new Error(
+      "decisionRequestBody refused `decision: undefined` \u2014 JSON drops the key, the wire would read a NEW MESSAGE, and the pause would sit unanswered while the screen believed it answered. Post the actual decision (`null` is allowed; absence is not)."
+    );
+  }
+  return {
+    input: args.input ?? "",
+    decision: args.decision,
+    ...args.sessionId !== void 0 && { sessionId: args.sessionId }
+  };
+}
+var SENTENCE_JSON_CAP = 120;
+function decisionSentence(decision) {
+  if (isConsentDecision(decision)) {
+    const verb = decision.approved ? "Approved" : "Declined";
+    const note = decision.note !== void 0 ? ` \u2014 "${decision.note}"` : "";
+    return `${verb} by ${decision.by}${note}.`;
+  }
+  if (typeof decision === "string") return `Answered: "${decision}".`;
+  if (decision === null || typeof decision !== "object")
+    return `Answered: ${String(decision)}.`;
+  let json;
+  try {
+    json = JSON.stringify(decision) ?? String(decision);
+  } catch {
+    json = "[unserializable]";
+  }
+  if (json.length > SENTENCE_JSON_CAP) json = `${json.slice(0, SENTENCE_JSON_CAP)}\u2026`;
+  return `Answered with a structured decision: ${json}.`;
+}
+function isConsentDecision(value) {
+  return typeof value === "object" && value !== null && typeof value.approved === "boolean" && typeof value.by === "string";
+}
+
 export {
   ChangeNotifier,
   lensSnapshotRecorder,
@@ -3401,6 +3606,12 @@ export {
   selectCommentaryAt,
   selectCommentaryRanges,
   selectToolChoiceCall,
+  groupDisplayName,
+  groupDisplayNameForLabel,
+  groupContainsCommit,
+  chartNodeIdOf,
+  activeChartGroup,
+  buildGroups,
   makeRootNodeId,
   makeChildNodeId,
   translateAgent,
@@ -3431,6 +3642,13 @@ export {
   readPresentedResult,
   presentedFromEvents,
   describePresented,
-  artifactPlaceholder
+  artifactPlaceholder,
+  readAwaitingComponent,
+  isConsentAsk,
+  approveDecision,
+  declineDecision,
+  decisionRequestBody,
+  decisionSentence,
+  isConsentDecision
 };
-//# sourceMappingURL=chunk-ZSOYNKUI.js.map
+//# sourceMappingURL=chunk-EGU4GZVH.js.map