@narumitw/pi-inspect 0.0.0-stage → 0.2.0

package/docs/viewer.md

@@ -0,0 +1,74 @@
+# Viewer reference
+
+Detailed views, data provenance, bounds and security for `pi-inspect`.
+
+## Views and data provenance
+
+**Context composition is the primary view.** A warm off-white document layout uses muted, consistent system/developer, user, assistant, tool-call, tool-result and neutral colors. Each ordered message or supported content block is an expandable row; assistant thinking/text/tool calls remain distinct. Desktop details place source metadata beside content, with lightweight structured/metadata/raw accordions. Copy acts on captured display data; the raw message and original role remain available. Missing segment token sizes are explicitly unavailable: persisted assistant totalTokens is usage, not the size of an individual context block.
+
+A narrow right-hand minimap summarizes the same filtered segment sequence in up to 160 contiguous buckets, with category proportions and the actual viewport region. Clicking a bucket jumps/focuses its first segment. Variable-height virtualization renders the viewport plus five-row overscan on each side; measured heights and source-ID anchoring preserve older scroll while expanding or appending. Search covers available bounded captured message content, not uncaptured data. Category filters and source-mode navigation retain row expansion; keyboard ArrowUp/ArrowDown/Home/End navigate and Enter/Space or Left/Right control disclosure. Light is the default; dark and responsive inline details remain available.
+
+**Source distinction is explicit.** After consent, context_with_system observes Pi messages after conversation-only context handlers and prompt/tool restoration. It returns nothing and does not modify the event. The primary view labels this as the last observed Pi-stage context, including its leaf/time when available; later context_with_system hooks, provider conversion and payload hooks can still differ. The advanced provider-payload copy is an independently timestamped hook-stage observation, not a guaranteed final transport body. Public callbacks have no request identity proving turn ownership: cache-warming and retry bodies may appear, so they are never attributed to the context leaf or observation time. Until a request is observed, the native active-leaf projection is labeled session-derived, not exact model input. Compaction/context edits use native Pi semantics, not the full session log. Session events and execution events are never silently appended to context.
+
+**Context and Session have independent selection and reading state.** Context is full-width: it never shows Session filters, event Details, or an execution list. Current runtime prompt, tool schemas/exposure/active/callable state, and currently advertised skills are available under **Current runtime information**, not mixed into historical event evidence. This information may not yet have been sent to a model. Inventory cards mount only while their enclosing disclosures are open; closed schema/Data bodies do not mount recursive JSON or text previews, while bounded Copy remains available. JSON object disclosure state is retained within the existing bounded scope cache.
+
+**Session** answers what happened, with one primary navigation area and a content-first **Details** panel. **History** defaults to List and follows the active branch; entries are ordered by recorded ancestry, not timestamps, and grouped by user turn. Entries before the first user turn have their own group. Groups are reading aids, not execution parentage. User/assistant/tool summaries come from bounded redacted content; truncation is labeled. Missing leaves/parents and cycles produce explicit partial-history notices, never repaired links.
+
+**Show internal events** includes generic Pi bookkeeping: custom state entries, labels, session metadata, and usage entries. Classification uses the original entry type, not a private extension name or message role; model-visible custom messages, including legacy messages with role `custom`, remain visible. Errors, compaction, branch summaries, system/context changes, model/thinking changes, and unknown types are not silently hidden. Matching hidden internal records are counted, excluding selected records retained visibly by the navigation exception. History searches show direct matches without every ancestor. Search covers the bounded summary/label inventory, not uncaptured full entry content.
+
+**Branch view** replaces the duplicate sidebar tree. It retains actual session-entry `parentId` links and access to off-branch entries. Its filters retain actual ancestors, visibly marked as context; child counts are visible counts, not persisted totals. **History at selected entry** explicitly changes the browser's history scope; **Follow active branch** restores automatic active-leaf tracking. Neither changes Pi's leaf. A selection outside the displayed branch is explicitly labeled. Related-entry navigation can reveal an entry outside filters without clearing them; changing filters ends that exception.
+
+Clicking a log row selects it without changing disclosure; its chevron toggles disclosure without selecting. Enter selects, Space toggles, ArrowUp/ArrowDown move focus, ArrowRight expands or enters a child in Branch view, and ArrowLeft collapses or moves to the recorded parent. Multiple rows can be expanded; collapsing a parent retains descendant expansion state. Inline Overview/Content/Raw/Metadata sections lazily load bounded recorded text/output, tool arguments, usage, and structured JSON. Complete inspection is available in Details.
+
+History and Branch pages contain at most 50 visible rows, with one visible keyboard tab target; ArrowUp/ArrowDown can cross pages. Branch ancestry traversal is iterative and uncapped by visual depth: page-local/scaled indentation preserves absolute ARIA levels and original parents. Initial reveal does not fetch every ancestor's details. Session filters and Details are collapsible, resizable desktop panes; pointer dragging and focused-separator ArrowLeft/ArrowRight/Home/End resize them. Cancellation, Escape, blur and unmount release drag listeners. Narrow layouts use focus-trapped Dialog drawers with Escape dismissal and focus restoration. Entry selection opens Details; headers expose these controls only in Session. View choices, filters, widths, and disclosure are ephemeral, not saved settings.
+
+Entry and branch failures have separate visible retries; unavailable historical checkpoints remain distinct from request failures. Live snapshots do not clear a failed selected-branch alert. Inline loads use four concurrent requests and a 64-entry immutable historical-detail cache; collapse, inactive views, disposal, and terminal session failures cancel owned requests. Historical section JSON disclosure is isolated by entry/section scope within a bounded 128-scope cache. Existing capture bounds still apply; UI expansion cannot recover omitted data.
+Malformed entry/parent IDs, non-string type/role/timestamp fields and all duplicated entry identities are excluded from navigation without manufacturing replacement IDs. Duplicate ancestor/detail identities are explicitly unavailable rather than selecting the last indexed occurrence. The overview labels the count and exposes up to 20 indexed raw diagnostic samples, each bounded to 2 KiB-equivalent characters; source entries are unchanged. Invalid leaf identities cannot become a browser selection or captured transcript anchor.
+
+A session-owned structural index is rebuilt on structural changes and released on stop/replacement. Inline requests reuse it and project only their validated ancestor path, not every off-branch entry; valid context-edit/compaction replay remains the native Pi result.
+
+Before historical replay, ancestry is validated with a visited set and a 10,000-entry inspection budget. Recorded parent cycles, missing parents or a budget overflow keep the raw entry and original parent links visible but mark projection unavailable; the inspector never asks Pi to traverse those malformed paths or mutates the session to repair them.
+
+The compact overview distinguishes persisted entries, indexed assistant messages/tokens/log errors and captured calls. Recorded span is the indexed log timestamp range, not execution duration. Tokens are persisted assistant `totalTokens`, excluding compaction/auxiliary usage; inline input/output bars appear only when recorded usage supplies both values, with cache excluded explicitly. Missing metrics are omitted or neutral. No model durations, transport latency, p95 or request totals are invented.
+
+Each captured execution has a unique `occurrenceId`; `id` remains the provider/native raw tool-call ID. Repeated raw IDs retain separate history and occurrence-parent links. Transcript correlation requires the recorded owning-assistant anchor, not raw ID alone; overlapping invalid IDs are explicitly marked unavailable rather than assigning an ambiguous result. Evicting a selected occurrence returns selection to its remembered recorded anchor (or current leaf).
+
+**Captured executions** is an explicit Session view, not a drawer attached to Context. Running/error counts remain visible in Session navigation without switching the user's view on arrival. Rows use occurrence-parent relationships; chevrons expand child navigation only. Arguments, results, relationships, correlation availability, reported duration and observed times appear once in the selection-owned Details panel. Root calls have no recorded parent; unresolved or invalid parent evidence is labeled unavailable. Correlation requires a recorded anchor and unambiguous IDs, not merely the absence of an error flag. Related execution buttons navigate real parent/child occurrences; **Inspect recorded anchor** returns to Branch view only when that anchor is represented. Eviction returns selection to its represented remembered anchor or current leaf; it switches Captured executions to Branch view but preserves History when already reading it.
+
+Timeline is an optional shared-axis view. Log timestamps are points, not duration spans. `observedStartedAt`/`observedEndedAt` are wall-clock samples taken on entry to this collector\'s actual start/end callbacks, after activation; their intervals are labeled observations, not provider transport timing. Public `durationMs` remains the separate monotonic time spent in `execute()`, absent if it did not run. Missing starts are never synthesized from durations; update/end-only, running or reversed-clock records do not become closed spans. Earlier callbacks or framework work can separate observation intervals from reported execution durations.
+
+**Details** defaults to Content: literal recorded message blocks, thinking, tool arguments/results, or internal-event payload. Metadata and Raw JSON are secondary; historical Prompt/Tools/Context/Skills/Codemode remain accessible in a horizontally scrollable tab strip. Live executions disable historical transcript tabs; their recorded anchor can be inspected separately. Inapplicable selections fall back to Content. Historical prompt sections, updates, previous-node diffs, declared tools, selected-entry contribution, and skill-read evidence never borrow the current runtime inventory as historical evidence. Full IDs remain in metadata/copy while identity headings use short IDs. Technical JSON can scroll within the pane without page-wide overflow.
+
+**View branch context**, in Details' Context tab, opens the same composition reader with a **Session-derived preview** identity and selected leaf. Native Pi compaction/context edits apply, but request-local hooks and provider serialization remain unknown: this is not a captured historical request. Missing checkpoints or invalid ancestry remain explicitly unavailable. The preview has no unrelated provider observation or current runtime inventory. **Back to last observed context** restores the observed reader and its independent search/disclosure/scroll state.
+
+| Capability | Location | Provenance / limitation |
+| --- | --- | --- |
+| Ordered model input, search, minimap, inline message/metadata/raw/copy | Context | Last observed Pi context; explicit session-derived active-leaf fallback until observed |
+| Current prompt, tools/MCP schemas and exposure, advertised skills | Context → Current runtime information | Current inventory, not historical request evidence; active ≠ provider-visible; MCP connection/auth state unavailable |
+| Provider payload | Context → Advanced independent provider observation | Independent time; request/leaf association unavailable, including warming/retries |
+| Conversation turns, summaries, internal entries, List/Timeline | Session → History | Selected branch ancestry; original entries unchanged; up to 50 visible rows per page |
+| Roots, branches, labels, unknown/malformed ancestry | Session → Branch view and overview diagnostics | Up to 10,000 nodes reserving active ancestry; original parent relationships, not call parentage |
+| Historical prompt, sections, updates, previous-node diff | Details → Prompt | Pi replay from stored checkpoints; missing historical checkpoints unavailable |
+| Historical declared tools and skill invocation/read evidence | Details → Tools / Skills | Branch-local stored evidence; old catalogs and model compliance unknown |
+| Branch projection and selected-entry contribution | Details → Context → View branch context | Explicit native session-derived preview, not final HTTP input |
+| Script source, printed output, persisted nested metadata | Details → Codemode and Raw | Historical child results are not saved by Pi; discovery/model helpers unavailable unless printed |
+| Live nested arguments/results, statuses, occurrence IDs, observed intervals | Session → Captured executions → Details | Session-wide public execution events; no invented Promise graph or request association |
+
+Timeline uses log timestamps as points and observed execution callbacks as intervals, never invented model/transport spans. History/List and History/Timeline show the same branch scope. The timing axis includes the indexed session and captured observations for comparison; it does not infer execution causality from adjacent log rows.
+Live results come from public `tool_execution_end` events, after the runtime's tool-result transformation pipeline (verified with a real nested call and a transforming hook). Partial updates are provisional. Unknown tools, schema failures, and permission blocks still have nested execution events. Direct transcript results remain authoritative persisted history. The inspector observes only: its context_with_system and before_provider_request handlers return nothing and never mutate messages or payloads; it registers no result-transforming handler.
+
+Codemode discovery helpers (`searchTools`, `describeTool`, `describeNamespace`, catalog helpers), sandbox local variables, and internal Promise scheduling are not normal child-tool events. `models.classify` and `models.generateImages` are also not normal nested tools: their complete input/output is unavailable unless printed. The generic Raw tab can show documented persisted metadata but the inspector never imports another extension or depends on private codemode implementation types.
+
+## Bounds and security
+
+- The server binds only `127.0.0.1` on a random port, checks Host and Origin, rejects cross-site requests and non-GET methods, and authenticates every data/SSE request with a random per-session token and generation.
+- The URL is at most 68 characters and printed on its own line for manual opening. Its fragment contains the full 256-bit token in Base64url, not a query or HTTP request; the data-free HTML supplies the public generation identifier. Legacy token/generation fragments remain supported. The browser keeps credentials in memory, attempts to save them in origin-scoped sessionStorage, and removes the fragment from history. Storage getter/read/write failures do not block a valid compact or legacy private URL; without saved credentials, fragment-free reloads require reopening from Pi. The launch notification necessarily contains the private credential URL for manual opening; it is not an API key. No request logs are written.
+- A data-free shell and bundled JS/CSS are publicly readable on that loopback port; session data requires authentication. There is no CORS grant, arbitrary file read, attachment path endpoint, or upstream credential/header/environment API.
+- Structured previews use native object/array disclosure. JSON text and plain content are literal with line numbers and bounded coloring (at most 1,000 lines and 512 colored tokens); long lines fall back to plain text. Copy acts only on the bounded redacted display value, including lines omitted by the local preview cap, and reports success or denial. Pending clipboard feedback is ignored after its owning component is disposed; the browser clipboard API itself cannot be aborted.
+- CSP blocks remote scripts, connections, frames, fonts, and images. Tool text and Markdown are shown literally, not as executable HTML. Only small validated PNG/JPEG/GIF/WebP base64 blocks can render as images; SVG, remote images, opaque signatures, and large image payloads are omitted. No filesystem attachment is opened automatically.
+- The collector keeps 128 records, at most 8 KiB-equivalent argument characters and 32 KiB-equivalent result characters per call, with depth/node limits. Tool schemas are bounded, inventory limits are 256 tools/skills, prompt/raw/projection fields are bounded to 64 KiB-equivalent characters, and evictions/truncation are visible. These are character/traversal budgets, not exact serialized-byte caps; JSON overhead adds size.
+- Context observation is consent-gated, in-memory and discarded on stop/replacement/reload/shutdown. It captures at most 4,000 segments, up to 8 KiB-equivalent characters per message and approximately 1 MiB-equivalent serialized message characters overall; provider-payload copies use 64 KiB-equivalent characters. Bounds, omitted content and source-stage limitations are labeled. Expanded Raw/Copy can reveal all captured text beyond local preview limits, but cannot recover content excluded by capture bounds.
+- SSE sends revision invalidations rather than result payloads. Notifications and intermediate partial copies are sampled/coalesced to at most one per 250 ms; final results are always captured. Live-only requests reuse the static snapshot rather than re-summarizing history. An owned 1-second reconciliation checks the public SDK entry count (when exposed), leaf/name and bounded public tool metadata for actions without extension change events, without rebuilding context projections or copying idle history on SDK managers. Readonly adapters lacking that public count method fall back to getEntries. At most eight stream clients and 32 sockets are accepted. A backpressured stream is closed, and reconnect triggers a fresh snapshot. Viewer-capacity responses (429), transient server failures and offline transport retry after one second. Snapshot request failures also retry with an owned one-second timer even when SSE is quiet; authentication/closed-session/generation responses do not retry. Authentication, closed-session, generation and protocol failures stop the connection and require reopening from Pi. Pending fetches, readers, reconnect timers, reconciliation/coalescing timers, browser-launch tasks, and session resources are cancelled on their owning boundary.
+- Tokens do not defend against a malicious process running as your local user. Redaction is not a secrecy guarantee. Do not expose the port remotely or assume this is a multi-user service.
+
+Entry IDs, parent IDs, timestamps and tool-result IDs over 512 characters are rejected, not truncated; malformed labels, session names, assistant/tool-call envelopes and context-edit replacements remain bounded raw diagnostics. Missing or empty session names preserve Pi’s title-clear semantics. Ordinary message entries retain Pi’s legacy missing/null-content normalization; checkpoint-owned system messages use strict replay validation. Historical current/previous system replay is preflighted against a cumulative 1 MiB input-character budget before native concatenation; over-budget previews are explicitly unavailable while bounded Raw evidence remains accessible. Tool replay also allows at most 2,048 cumulative additions/removals, with declaration traversal bounded to 16,384 nodes and depth 32 inside the shared character budget. Live own IDs and tool-name inputs must be non-empty strings of at most 512 characters; rejected events are counted as omitted with unavailable correlation, not rewritten. Invalid parent IDs and anchors are omitted with explicit unavailable relationships. When a bounded refresh omits a selected entry, the preview falls back to a represented entry without moving Pi’s leaf. Credential classification includes camelCase/acronym suffixes without masking metric keys. Search queries strip terminal controls before a 512-character bound and normalize once per filter update. Responsive mode depends only on viewport width, with side widths constrained to preserve the central workspace. Explicit filter resets start at the source top even when the matching IDs do not change.

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@narumitw/pi-inspect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Read-only browser inspector for Pi session context and live tool calls.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "session",
+    "inspector",
+    "context",
+    "observability"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "npm run build && biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "test:browser": "playwright test --config playwright.config.ts",
+    "smoke": "node scripts/smoke.mjs",
+    "smoke:git-install": "node scripts/git-install-smoke.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@radix-ui/colors": "3.0.0",
+    "@radix-ui/react-collapsible": "1.1.20",
+    "@radix-ui/react-icons": "1.3.2",
+    "@radix-ui/themes": "3.3.0",
+    "esbuild": "0.28.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@playwright/test": "1.63.0",
+    "@types/node": "26.6.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "typebox": "1.3.36",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/narumiruna/pi-extensions",
+    "directory": "packages/pi-inspect"
+  }
+}

package/src/ancestry.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { EntryIndex } from "./entry-index.js";
+import { structuralIssue } from "./identity.js";
+import { nativeProjection } from "./native-projection.js";
+
+// Pi's native projection walks parent links without cycle detection; validate before invoking it.
+export function ancestry(
+  manager: ExtensionContext["sessionManager"],
+  id: string,
+  index = new EntryIndex(manager.getEntries()),
+): { path: SessionEntry[]; issue?: string } {
+  const path: SessionEntry[] = [];
+  const seen = new Set<string>();
+  if (index.duplicates.has(id)) return { path: [], issue: "duplicate entry id" };
+  let current = index.get(id);
+  while (current) {
+    const issue = structuralIssue(current);
+    if (issue) return { path: path.reverse(), issue };
+    if (seen.has(current.id)) return { path: path.reverse(), issue: "recorded parent cycle" };
+    if (path.length >= 10000)
+      return { path: path.reverse(), issue: "ancestry exceeds the 10,000-entry inspection budget" };
+    seen.add(current.id);
+    path.push(current);
+    const parent = current.parentId;
+    if (parent && index.duplicates.has(parent)) return { path: path.reverse(), issue: "duplicate ancestor id" };
+    current = parent ? index.get(parent) : undefined;
+    if (parent && !current) return { path: path.reverse(), issue: "missing recorded parent" };
+  }
+  path.reverse();
+  return { path, issue: nativeProjection(path, id).issue };
+}

package/src/collector.ts

@@ -0,0 +1,143 @@
+import type {
+  ToolExecutionEndEvent,
+  ToolExecutionStartEvent,
+  ToolExecutionUpdateEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { Call } from "./model.js";
+import { capture, displayText } from "./privacy.js";
+
+function validIdentity(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 512;
+}
+
+export class Collector {
+  readonly startedAt = Date.now();
+  private calls = new Map<string, Call>();
+  private partialAt = new Map<string, number>();
+  private sequence = 0;
+  dropped = 0;
+  invalidEvents = 0;
+  private admit(event: { toolCallId: string; toolName: string }): boolean {
+    if (validIdentity(event.toolCallId) && validIdentity(event.toolName)) return true;
+    this.invalidEvents++;
+    return false;
+  }
+  private fenceParent(call: Call, parent: unknown): boolean {
+    if (parent !== undefined && !validIdentity(parent)) {
+      const changed =
+        call.parentUnavailable !== "Invalid or over-budget parent ID; relationship unavailable" ||
+        call.parentOccurrenceId !== undefined;
+      call.parentId = undefined;
+      call.parentOccurrenceId = undefined;
+      call.parentUnavailable = "Invalid or over-budget parent ID; relationship unavailable";
+      return changed;
+    }
+    return false;
+  }
+  constructor(private readonly maxCalls = 128) {}
+  private create(
+    event: { toolCallId: string; parentToolCallId?: string; toolName: string },
+    args: unknown,
+    anchor: string | null,
+  ): Call {
+    const parentId = validIdentity(event.parentToolCallId) ? event.parentToolCallId : undefined;
+    const parent = parentId ? this.active(parentId) : undefined;
+    const ambiguousParent =
+      event.parentToolCallId !== undefined &&
+      this.list().filter((item) => item.id === event.parentToolCallId && item.status === "running").length > 1;
+    const call: Call = {
+      id: event.toolCallId,
+      occurrenceId: `call-${++this.sequence}`,
+      parentId,
+      parentUnavailable: ambiguousParent ? "Overlapping running parent IDs; relationship unavailable" : undefined,
+      parentOccurrenceId: parent?.status === "running" ? parent.occurrenceId : undefined,
+      name: displayText(event.toolName),
+      status: "running",
+      args: capture(args, 8192),
+      branchAnchor: parent?.status === "running" ? parent.branchAnchor : validIdentity(anchor) ? anchor : null,
+      correlationUnavailable: anchor !== null && !validIdentity(anchor) ? true : undefined,
+    };
+    this.fenceParent(call, event.parentToolCallId);
+    this.calls.set(call.occurrenceId, call);
+    while (this.calls.size > this.maxCalls) {
+      const first = this.calls.keys().next().value;
+      if (first === undefined) break;
+      this.calls.delete(first);
+      this.partialAt.delete(first);
+      this.dropped++;
+    }
+    return call;
+  }
+  private active(rawId: string): Call | undefined {
+    const running = this.list().filter((call) => call.id === rawId && call.status === "running");
+    if (running.length > 1) {
+      for (const call of running) call.correlationUnavailable = true;
+      return undefined;
+    }
+    return running[0];
+  }
+  start(event: ToolExecutionStartEvent, anchor: string | null): void {
+    if (!this.admit(event)) return;
+    const now = Date.now();
+    const call = this.create(event, event.args, anchor);
+    call.observedStartedAt = now;
+    if (
+      this.list().filter((parent) => parent.id === call.id && parent.branchAnchor === call.branchAnchor).length === 1
+    ) {
+      for (const child of this.calls.values())
+        if (
+          child.parentId === call.id &&
+          !child.parentOccurrenceId &&
+          !child.parentUnavailable &&
+          child.status === "running" &&
+          child.branchAnchor === call.branchAnchor
+        )
+          child.parentOccurrenceId = call.occurrenceId;
+    }
+    const occurrences = this.list().filter((item) => item.id === call.id && item.branchAnchor === call.branchAnchor);
+    if (occurrences.length > 1) {
+      for (const occurrence of occurrences) occurrence.correlationUnavailable = true;
+      for (let i = 0; i < this.calls.size; i++)
+        for (const child of this.calls.values())
+          if (child.parentOccurrenceId && this.calls.get(child.parentOccurrenceId)?.correlationUnavailable)
+            child.correlationUnavailable = true;
+    }
+    this.active(event.toolCallId); // Explicitly mark overlapping reused IDs as ambiguous, never misroute their results.
+  }
+  update(event: ToolExecutionUpdateEvent, anchor: string | null): boolean {
+    if (!this.admit(event)) return true; // Publish the new unavailable-event counter.
+    const now = Date.now();
+    let call = this.active(event.toolCallId);
+    if (!call && this.list().some((call) => call.id === event.toolCallId && call.status === "running")) return false;
+    call ??= this.create(event, event.args, anchor);
+    const parentChanged = this.fenceParent(call, event.parentToolCallId);
+    if (now - (this.partialAt.get(call.occurrenceId) ?? -Infinity) < 250) return parentChanged;
+    this.partialAt.set(call.occurrenceId, now);
+    call.result = capture(event.partialResult);
+    return true;
+  }
+  end(event: ToolExecutionEndEvent, anchor: string | null): void {
+    if (!this.admit(event)) return;
+    const now = Date.now();
+    const running = this.list().filter((call) => call.id === event.toolCallId && call.status === "running");
+    const call = this.active(event.toolCallId) ?? this.create(event, "[not captured]", anchor);
+    if (running.length > 1) {
+      call.correlationUnavailable = true;
+      call.parentOccurrenceId = undefined;
+    }
+    this.fenceParent(call, event.parentToolCallId);
+    call.status = event.isError ? "error" : "ok";
+    call.durationMs =
+      typeof event.durationMs === "number" && Number.isFinite(event.durationMs) && event.durationMs >= 0
+        ? event.durationMs
+        : undefined;
+    call.observedEndedAt = now;
+    call.result = capture(event.result);
+  }
+  settle(): void {
+    for (const call of this.calls.values()) if (call.status === "running") call.status = "unfinished";
+  }
+  list(): Call[] {
+    return [...this.calls.values()];
+  }
+}

package/src/context.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { buildSessionProjection, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ancestry } from "./ancestry.js";
+import type { EntryIndex } from "./entry-index.js";
+import { recordedLeaf } from "./identity.js";
+import type { ContextComposition, ContextSegment, Json } from "./model.js";
+import { capture } from "./privacy.js";
+
+function object(value: Json | undefined): Record<string, Json> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+export function captureContext(
+  input: readonly unknown[],
+  source: ContextComposition["source"],
+  leafId: string | null,
+): ContextComposition {
+  const result: ContextComposition = {
+    source,
+    leafId,
+    totalMessages: input.length,
+    messages: [],
+    segments: [],
+    incomplete: false,
+  };
+  const occurrences = new Map<string, number>();
+  let budget = 1048576;
+  for (const message of input) {
+    if (result.segments.length >= 4000 || budget <= 64) {
+      result.incomplete = true;
+      break;
+    }
+    const raw = capture(message, Math.min(8192, budget));
+    const encoded = JSON.stringify(raw);
+    budget -= encoded.length;
+    result.incomplete ||= raw.truncated;
+    const data = object(raw.value);
+    const role = typeof data?.role === "string" ? data.role : "unknown";
+    const index = result.messages.length;
+    result.messages.push(raw);
+    const hash = createHash("sha256").update(encoded).digest("hex").slice(0, 20);
+    const occurrence = occurrences.get(hash) ?? 0;
+    occurrences.set(hash, occurrence + 1);
+    const content = data?.content === "" && data?.sections ? data.sections : data?.content;
+    const blocks = Array.isArray(content) && content.length ? content : [content ?? data?.sections ?? raw.value];
+    for (const [blockIndex, block] of blocks.entries()) {
+      if (result.segments.length >= 4000) {
+        result.incomplete = true;
+        break;
+      }
+      const item = object(block);
+      const kind = typeof item?.type === "string" ? item.type : role;
+      const category: ContextSegment["category"] =
+        role === "system" || role === "developer"
+          ? "system"
+          : role === "user"
+            ? "user"
+            : role === "toolResult" || role === "tool"
+              ? "toolResult"
+              : role === "assistant" && kind === "toolCall"
+                ? "toolCall"
+                : role === "assistant"
+                  ? "assistant"
+                  : "other";
+      const preview = item?.name ?? item?.text ?? item?.thinking ?? block;
+      const timestamp =
+        typeof data?.timestamp === "string"
+          ? data.timestamp
+          : typeof data?.timestamp === "number" &&
+              Number.isFinite(data.timestamp) &&
+              Math.abs(data.timestamp) < 8640000000000000
+            ? new Date(data.timestamp).toISOString()
+            : undefined;
+      result.segments.push({
+        id: `${source}-${hash}-${occurrence}-${blockIndex}`,
+        position: result.segments.length + 1,
+        messageIndex: index,
+        ...(Array.isArray(content) && content.length ? { blockIndex } : {}),
+        role,
+        kind,
+        category,
+        preview: (typeof preview === "string" ? preview : JSON.stringify(preview)).slice(0, 240),
+        ...(timestamp ? { timestamp } : {}),
+      });
+    }
+  }
+  result.incomplete ||= result.messages.length < input.length;
+  return result;
+}
+export function sessionContext(manager: ExtensionContext["sessionManager"], index: EntryIndex): ContextComposition {
+  const leafId = recordedLeaf(manager, index.duplicates);
+  const validation = leafId ? ancestry(manager, leafId, index) : { path: [], issue: "No unambiguous active leaf" };
+  if (validation.issue)
+    return {
+      source: "session-derived",
+      leafId,
+      totalMessages: 0,
+      messages: [],
+      segments: [],
+      incomplete: true,
+      unavailable: validation.issue,
+    };
+  try {
+    return captureContext(buildSessionProjection(validation.path, leafId).messages, "session-derived", leafId);
+  } catch {
+    return {
+      source: "session-derived",
+      leafId,
+      totalMessages: 0,
+      messages: [],
+      segments: [],
+      incomplete: true,
+      unavailable: "Native context projection unavailable",
+    };
+  }
+}

package/src/correlation.ts

@@ -0,0 +1,27 @@
+import type { Call } from "./model.js";
+
+// Occurrence IDs form the captured execution graph. Raw IDs are only used with an owning assistant anchor.
+export function correlatedCalls(rawIds: Set<string>, anchor: string | undefined, all: Call[]): Call[] {
+  if (!anchor) return [];
+  const multiplicity = new Map<string, number>();
+  for (const call of all)
+    if (call.branchAnchor === anchor) multiplicity.set(call.id, (multiplicity.get(call.id) ?? 0) + 1);
+  const ids = new Set(
+    all
+      .filter(
+        (call) =>
+          (rawIds.has(call.id) ||
+            (call.parentId !== undefined &&
+              rawIds.has(call.parentId) &&
+              (!call.parentOccurrenceId || !all.some((parent) => parent.occurrenceId === call.parentOccurrenceId)))) &&
+          call.branchAnchor === anchor &&
+          (!call.parentOccurrenceId || !all.some((parent) => parent.occurrenceId === call.parentOccurrenceId)) &&
+          !call.correlationUnavailable &&
+          (multiplicity.get(call.id) ?? 0) < 2,
+      )
+      .map((call) => call.occurrenceId),
+  );
+  for (let i = 0; i < all.length; i++)
+    for (const call of all) if (call.parentOccurrenceId && ids.has(call.parentOccurrenceId)) ids.add(call.occurrenceId);
+  return all.filter((call) => ids.has(call.occurrenceId));
+}

package/src/entry-index.ts

@@ -0,0 +1,17 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+// Rebuilt only at structural boundaries, never once per inline request.
+export class EntryIndex {
+  readonly byId = new Map<string, SessionEntry>();
+  readonly duplicates = new Set<string>();
+  constructor(readonly entries: SessionEntry[]) {
+    for (const entry of entries)
+      if (typeof entry?.id === "string") {
+        if (this.byId.has(entry.id)) this.duplicates.add(entry.id);
+        this.byId.set(entry.id, entry);
+      }
+  }
+  get(id: string): SessionEntry | undefined {
+    return this.duplicates.has(id) ? undefined : this.byId.get(id);
+  }
+}

package/src/entry-summary.ts

@@ -0,0 +1,34 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { Json } from "./model.js";
+import { capture } from "./privacy.js";
+
+/** Summarize only an already redacted, bounded display copy. */
+export function readableSummary(entry: SessionEntry): { summary: string; summaryTruncated?: true } {
+  const source =
+    entry.type === "message"
+      ? "content" in entry.message
+        ? entry.message.content
+        : undefined
+      : entry.type === "custom_message"
+        ? entry.content
+        : entry.type === "compaction" || entry.type === "branch_summary"
+          ? entry.summary
+          : undefined;
+  if (source === undefined || source === null) return { summary: "" };
+  const captured = capture(source, 1024);
+  const text = (value: Json): string => {
+    if (typeof value === "string") return value;
+    if (!value || typeof value !== "object") return "";
+    if (Array.isArray(value)) return value.map(text).filter(Boolean).join(" · ");
+    if (typeof value.text === "string") return value.text;
+    if (value.type === "thinking") return "Thinking";
+    if (value.type === "image") return "Image";
+    if (value.type === "toolCall") return `${value.name ?? "Tool call"} ${JSON.stringify(value.arguments ?? {})}`;
+    return "";
+  };
+  const summary = text(captured.value).replace(/\s+/g, " ").trim();
+  return {
+    summary: summary.slice(0, 180),
+    summaryTruncated: captured.truncated || summary.length > 180 ? true : undefined,
+  };
+}