@narumitw/pi-inspect 0.0.0-stage → 0.1.0

package/src/feed.ts

@@ -0,0 +1,145 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Collector } from "./collector.js";
+import { captureContext } from "./context.js";
+import { EntryIndex } from "./entry-index.js";
+import { recordedLeaf } from "./identity.js";
+import type { ContextComposition, SkillView, Snapshot } from "./model.js";
+import { capture, displayText, readSessionName } from "./privacy.js";
+import { snapshot } from "./projection.js";
+
+export class SessionFeed {
+  private dirty = true;
+  private observed?: ContextComposition;
+  private providerObservation?: Snapshot["providerObservation"];
+  observeContext(messages: readonly unknown[]): void {
+    if (this.closed || this.options.signal.aborted) return;
+    this.observed = captureContext(
+      messages,
+      "observed-pi-context",
+      recordedLeaf(this.options.context().sessionManager, this.index().duplicates),
+    );
+    this.observed.observedAt = Date.now();
+    this.changed(false);
+  }
+  observePayload(payload: unknown): void {
+    if (this.closed || this.options.signal.aborted) return;
+    // No public request identity associates this callback with a turn; warming/retries use it too.
+    this.providerObservation = { observedAt: Date.now(), data: capture(payload, 65536) };
+    this.changed(false);
+  }
+  private indexed?: EntryIndex;
+  private closed = false;
+  index(): EntryIndex {
+    if (this.closed || this.options.signal.aborted) throw new Error("Inspector stopped");
+    if (!this.indexed) this.indexed = new EntryIndex(this.options.context().sessionManager.getEntries());
+    return this.indexed;
+  }
+  private cached?: Snapshot;
+  private revision = 0;
+  private stamp = "";
+  private notification?: ReturnType<typeof setTimeout>;
+  private poll?: ReturnType<typeof setInterval>;
+  constructor(
+    private readonly options: {
+      pi: ExtensionAPI;
+      context(): ExtensionContext;
+      collector: Collector;
+      skills: SkillView[];
+      generation: string;
+      signal: AbortSignal;
+      invalidate(revision: number): void;
+    },
+  ) {}
+  private stateStamp(): string {
+    const ctx = this.options.context();
+    const manager = ctx.sessionManager;
+    const tools = this.options.pi.getAllTools();
+    // Public SDK method, omitted from the current ReadonlySessionManager type; readonly adapters may lack it.
+    const counted = manager as typeof manager & { getEntryCount?: () => number };
+    const count = typeof counted.getEntryCount === "function" ? counted.getEntryCount() : manager.getEntries().length;
+    return JSON.stringify({
+      count,
+      leaf: recordedLeaf(manager),
+      name: readSessionName(manager),
+      active: this.options.pi.getActiveTools(),
+      toolCount: tools.length,
+      tools: tools.slice(0, 256).map((tool) => ({
+        name: tool.name,
+        exposure: tool.exposure,
+        namespace: tool.namespace?.name,
+        description: displayText(tool.description).slice(0, 512),
+        schema: capture(tool.parameters, 2048),
+      })),
+    });
+  }
+  start(): void {
+    if (this.options.signal.aborted || this.poll) return;
+    this.stamp = this.stateStamp();
+    this.poll = setInterval(() => {
+      if (this.options.signal.aborted) return;
+      try {
+        const next = this.stateStamp();
+        if (next !== this.stamp) {
+          this.stamp = next;
+          this.changed(true);
+        }
+      } catch {
+        this.changed(true);
+      } // Context failures must not escape a timer callback.
+    }, 1000);
+    this.options.signal.addEventListener("abort", this.close, { once: true });
+  }
+  changed(structural: boolean): void {
+    if (this.options.signal.aborted) return;
+    if (structural) {
+      this.dirty = true;
+      this.indexed = undefined;
+    }
+    if (!this.notification)
+      this.notification = setTimeout(() => {
+        this.notification = undefined;
+        if (!this.options.signal.aborted) this.options.invalidate(++this.revision);
+      }, 250);
+  }
+  snapshot(): Snapshot {
+    if (this.closed || this.options.signal.aborted) throw new Error("Inspector stopped");
+    if (!this.cached || this.dirty) {
+      const ctx = this.options.context();
+      this.cached = snapshot(
+        ctx.sessionManager,
+        this.options.collector,
+        this.options.generation,
+        this.revision,
+        ctx.getSystemPrompt(),
+        this.options.pi.getAllTools(),
+        this.options.pi.getActiveTools(),
+        this.options.skills,
+        this.index(),
+        this.observed,
+      );
+      this.cached.calls = []; // Do not retain evicted live results inside the static cache.
+      this.dirty = false;
+    }
+    return {
+      ...this.cached,
+      revision: this.revision,
+      context: this.observed ?? this.cached.context,
+      providerObservation: this.providerObservation,
+      calls: this.options.collector.list(),
+      droppedCalls: this.options.collector.dropped,
+      invalidCallEvents: this.options.collector.invalidEvents,
+    };
+  }
+  close = (): void => {
+    this.closed = true;
+    clearTimeout(this.notification);
+    clearInterval(this.poll);
+    this.notification = undefined;
+    this.poll = undefined;
+    this.options.signal.removeEventListener("abort", this.close);
+    this.cached = undefined;
+    this.indexed = undefined;
+    this.observed = undefined;
+    this.providerObservation = undefined;
+  };
+}

package/src/identity.ts

@@ -0,0 +1,112 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { systemMessageIssue } from "./system-message.js";
+
+export const MESSAGE_BLOCKS = 2048;
+
+export function structuralIssue(entry: SessionEntry | undefined): string | undefined {
+  if (typeof entry?.id !== "string" || !entry.id.length) return "missing, empty or non-string entry id";
+  if (entry.id.length > 512) return "over-budget entry id";
+  if (typeof entry.parentId === "string" && entry.parentId.length > 512) return "over-budget parent id";
+  if (entry.type === "label" && entry.label !== undefined && typeof entry.label !== "string")
+    return "non-string stored label";
+  if (entry.parentId !== null && (typeof entry.parentId !== "string" || !entry.parentId.length))
+    return "missing, empty or non-string parent id";
+  if (entry.type === "session_info" && entry.name !== undefined && typeof entry.name !== "string")
+    return "non-string stored session name";
+  if (typeof entry.type !== "string" || !entry.type.length) return "missing, empty or non-string entry type";
+  if (entry.type === "message" && (typeof entry.message?.role !== "string" || !entry.message.role.length))
+    return "missing, empty or non-string message role";
+  if (typeof entry.timestamp !== "string") return "non-string entry timestamp";
+  if (entry.timestamp.length > 512) return "over-budget entry timestamp";
+  return undefined;
+}
+
+export function identityIssue(entry: SessionEntry | undefined): string | undefined {
+  const structure = structuralIssue(entry);
+  if (structure || !entry) return structure;
+  if (
+    entry.type === "message" &&
+    "content" in entry.message &&
+    Array.isArray(entry.message.content) &&
+    entry.message.content.length > MESSAGE_BLOCKS
+  )
+    return "message content exceeds 2,048-block budget";
+  if (entry.type === "message" && entry.message.role === "system") {
+    // Native sessionEntryToContextMessages restores legacy missing/null content.
+    const m = entry.message;
+    const issue = systemMessageIssue(m.content == null ? { ...m, content: "" } : m);
+    if (issue) return issue;
+  }
+  if (entry.type === "compaction" && entry.systemMessage) {
+    const issue = systemMessageIssue(entry.systemMessage);
+    if (issue) return `checkpoint: ${issue}`;
+  }
+  if (
+    entry.type === "message" &&
+    entry.message.role === "assistant" &&
+    entry.message.content != null &&
+    (!Array.isArray(entry.message.content) ||
+      Array.from(entry.message.content).some((block) => !block || typeof block !== "object" || Array.isArray(block)))
+  )
+    return "malformed assistant content block or envelope";
+  if (
+    entry.type === "message" &&
+    entry.message.role === "assistant" &&
+    Array.isArray(entry.message.content) &&
+    entry.message.content.some(
+      (block) =>
+        block.type === "toolCall" &&
+        (!block.arguments ||
+          typeof block.arguments !== "object" ||
+          Array.isArray(block.arguments) ||
+          typeof block.id !== "string" ||
+          !block.id.length ||
+          block.id.length > 512 ||
+          typeof block.name !== "string" ||
+          !block.name.length ||
+          block.name.length > 512),
+    )
+  )
+    return "malformed tool-call envelope";
+  if (entry.type === "context_edit") {
+    if (typeof entry.targetId !== "string" || !entry.targetId.length || entry.targetId.length > 512)
+      return "malformed context-edit target id";
+    const value = entry.replacement;
+    if (Array.isArray(value?.content) && value.content.length > MESSAGE_BLOCKS)
+      return "context-edit content exceeds 2,048-block budget";
+    if (
+      value !== null &&
+      (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !("content" in value) ||
+        (typeof value.content !== "string" && !Array.isArray(value.content)) ||
+        (Array.isArray(value.content) &&
+          value.content.some((block) => !block || typeof block !== "object" || Array.isArray(block))))
+    )
+      return "malformed context-edit replacement";
+  }
+  if (
+    entry.type === "message" &&
+    entry.message.role === "toolResult" &&
+    (typeof entry.message.toolCallId !== "string" ||
+      !entry.message.toolCallId.length ||
+      entry.message.toolCallId.length > 512)
+  )
+    return "malformed or over-budget tool-result id";
+  return undefined;
+}
+
+export function recordedLeaf(
+  manager: ExtensionContext["sessionManager"],
+  duplicates?: ReadonlySet<string>,
+): string | null {
+  const leaf = manager.getLeafId();
+  return typeof leaf === "string" &&
+    leaf.length > 0 &&
+    leaf.length <= 512 &&
+    !duplicates?.has(leaf) &&
+    !identityIssue(manager.getEntry(leaf))
+    ? leaf
+    : null;
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { registerInspector as default } from "./extension.js";

package/src/model.ts

@@ -0,0 +1,113 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export interface Capture {
+  value: Json;
+  truncated: boolean;
+}
+export interface EntrySummary {
+  id: string;
+  parentId: string | null;
+  kind: string;
+  label: string;
+  timestamp: string;
+  name?: string;
+  nameTruncated?: boolean;
+  tokens?: number;
+  status?: "success" | "error" | "cancelled";
+  toolCallId?: string;
+  toolAnchor?: string;
+}
+export interface Call {
+  id: string;
+  occurrenceId: string;
+  parentOccurrenceId?: string;
+  parentUnavailable?: string;
+  correlationUnavailable?: boolean;
+  parentId?: string;
+  name: string;
+  status: "running" | "ok" | "error" | "unfinished";
+  args: Capture;
+  result?: Capture;
+  durationMs?: number;
+  observedStartedAt?: number;
+  observedEndedAt?: number;
+  branchAnchor: string | null;
+}
+export interface ToolView {
+  name: string;
+  description: string;
+  exposure: string;
+  active: boolean;
+  callable: boolean;
+  namespace?: string;
+  schema: Capture;
+}
+export interface SkillView {
+  name: string;
+  path: string;
+  description: string;
+}
+export interface ContextSegment {
+  id: string;
+  position: number;
+  messageIndex: number;
+  blockIndex?: number;
+  role: string;
+  kind: string;
+  category: "system" | "user" | "assistant" | "toolCall" | "toolResult" | "other";
+  preview: string;
+  timestamp?: string;
+}
+export interface ContextComposition {
+  source: "observed-pi-context" | "session-derived";
+  leafId: string | null;
+  observedAt?: number;
+  totalMessages: number;
+  messages: Capture[];
+  segments: ContextSegment[];
+  incomplete: boolean;
+  unavailable?: string;
+}
+export interface Snapshot {
+  protocol: 1;
+  generation: string;
+  revision: number;
+  sessionId: string;
+  name: string;
+  nameTruncated?: boolean;
+  leafId: string | null;
+  totalEntries: number;
+  nodes: EntrySummary[];
+  incomplete: boolean;
+  invalidEntryCount?: number;
+  invalidEntries?: { index: number; reason: string; raw: Capture }[];
+  context?: ContextComposition;
+  providerObservation?: { observedAt: number; data: Capture };
+  currentPrompt: Capture;
+  tools: ToolView[];
+  skills: SkillView[];
+  calls: Call[];
+  droppedCalls: number;
+  invalidCallEvents?: number;
+  captureStartedAt: number;
+}
+export interface BranchView {
+  ancestryIssue?: string;
+  leafId: string;
+  entries: EntrySummary[];
+  total: number;
+  offset: number;
+  prompt: Capture;
+  previousPrompt: Capture;
+  sections: Capture;
+  declaredTools: Capture;
+  promptUpdates: Capture;
+  projection: Capture;
+  skillEvidence: Capture;
+}
+export interface DetailView {
+  ancestryIssue?: string;
+  toolAnchor?: string;
+  raw: Capture;
+  projected: Capture;
+  calls: Call[];
+}

package/src/native-projection.ts

@@ -0,0 +1,28 @@
+import { buildContextEntries, buildSessionProjection, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { identityIssue } from "./identity.js";
+
+// Parent/role structure has already been validated. Native selection drops old
+// summaries/checkpoints and applies edits before content-envelope validation.
+export function nativeProjection(path: SessionEntry[], leaf: string | null) {
+  const contextEntries = buildContextEntries(path, leaf);
+  if (contextEntries[0]?.type === "compaction") {
+    const issue = identityIssue(contextEntries[0]);
+    if (issue) return { issue };
+  }
+  const edits = new Map(
+    contextEntries.filter((entry) => entry.type === "context_edit").map((entry) => [entry.targetId, entry]),
+  );
+  for (const entry of edits.values()) {
+    if (entry.type === "context_edit") {
+      const issue = identityIssue(entry);
+      if (issue) return { issue };
+    }
+  }
+  const projection = buildSessionProjection(path, leaf);
+  for (const projected of projection.entries)
+    for (const message of projected.messages) {
+      const issue = identityIssue({ ...projected.sourceEntry, type: "message", message } as SessionEntry);
+      if (issue) return { issue };
+    }
+  return { projection };
+}

package/src/privacy.ts

@@ -0,0 +1,136 @@
+import { stripVTControlCharacters } from "node:util";
+import type { Capture, Json } from "./model.js";
+
+const secretKey =
+  /^(authorization|proxy.authorization|cookie|set.cookie|password|passwd|secret|client[_-]?secret|secret[_-]?key|private[_-]?key|token|api[_-]?key|access[_-]?token|refresh[_-]?token|session[_-]?token|credentials|env|headers)$|(?:^|[_-])(?:api[_-]?key|(?:access|refresh|session)[_-]?token|token|client[_-]?secret|secret[_-]?key|private[_-]?key|password|passwd|secret)$/i;
+
+// Display-only: original session entries and event objects are never modified.
+export function displayText(text: string): string {
+  return (
+    stripVTControlCharacters(text)
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: Display sanitation intentionally removes C0/C1 controls, preserving tab and newline.
+      .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "")
+      .replace(/\bBearer\s+[A-Za-z0-9._~+/-]+/gi, "Bearer [redacted]")
+  );
+}
+
+export function sessionName(raw: unknown): { name: string; nameTruncated?: true } {
+  const clean = typeof raw === "string" ? displayText(raw) : "[unavailable: non-string session name]";
+  return { name: clean.slice(0, 512), nameTruncated: clean.length > 512 ? true : undefined };
+}
+
+export function readSessionName(manager: { getSessionName(): string | undefined }): {
+  name: string;
+  nameTruncated?: true;
+} {
+  try {
+    return sessionName(manager.getSessionName() ?? "Current session");
+  } catch {
+    return { name: "[unavailable: invalid stored session name]" };
+  }
+}
+
+export function readSessionId(manager: { getSessionId(): string }): string {
+  try {
+    const id = manager.getSessionId();
+    if (typeof id !== "string" || !id.length || id.length > 512)
+      return "[unavailable: invalid or over-budget session ID]";
+    return displayText(id) || "[unavailable: blank session ID]";
+  } catch {
+    return "[unavailable: invalid session ID]";
+  }
+}
+
+// Bound traversal before serialization: huge strings, arrays, cycles and deep objects are safe.
+export function capture(input: unknown, maxChars = 32768): Capture {
+  let budget = maxChars;
+  let nodes = 0;
+  let truncated = false;
+  const seen = new WeakSet<object>();
+  function text(value: string): string {
+    const clean = displayText(value);
+    const length = Math.min(clean.length, Math.max(0, budget));
+    budget -= length;
+    if (length < clean.length) truncated = true;
+    return clean.slice(0, length);
+  }
+  function visit(value: unknown, depth: number): Json {
+    if (++nodes > 2048 || depth > 12 || budget <= 0) {
+      truncated = true;
+      return "[truncated]";
+    }
+    budget -= 8;
+    if (value === null || value === undefined) return null;
+    if (typeof value === "string") return text(value);
+    if (typeof value === "boolean") return value;
+    if (typeof value === "number") return Number.isFinite(value) ? value : String(value);
+    if (typeof value !== "object") {
+      truncated = true;
+      return `[unsupported ${typeof value}]`;
+    }
+    if (seen.has(value)) {
+      truncated = true;
+      return "[circular]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+      const result: Json[] = [];
+      for (let index = 0; index < value.length; index++) {
+        if (budget <= 0 || nodes >= 2048) {
+          truncated = true;
+          break;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor?.get || descriptor?.set) {
+          truncated = true;
+          result.push("[accessor omitted]");
+        } else result.push(visit(descriptor?.value, depth + 1));
+      }
+      seen.delete(value);
+      return result;
+    }
+    const record = value as Record<string, unknown>;
+    const type = Object.getOwnPropertyDescriptor(record, "type")?.value;
+    const mimeType = Object.getOwnPropertyDescriptor(record, "mimeType")?.value;
+    const data = Object.getOwnPropertyDescriptor(record, "data")?.value;
+    const raster =
+      type === "image" &&
+      typeof mimeType === "string" &&
+      /^(image\/(png|jpeg|gif|webp))$/.test(mimeType) &&
+      typeof data === "string" &&
+      data.length <= Math.min(16384, Math.max(0, budget / 2)) &&
+      /^[A-Za-z0-9+/]*={0,2}$/.test(data);
+    const result: Record<string, Json> = Object.create(null);
+    for (const key in record) {
+      if (!Object.hasOwn(record, key)) continue;
+      if (budget <= 0 || nodes >= 2048) {
+        truncated = true;
+        break;
+      }
+      // Image bytes and opaque provider replay signatures are not useful as raw JSON.
+      const cleanKey = displayText(key);
+      const name = text(cleanKey.slice(0, 256));
+      if (cleanKey.length > 256) truncated = true;
+      const descriptor = Object.getOwnPropertyDescriptor(record, key);
+      if (descriptor?.get || descriptor?.set) {
+        truncated = true;
+        result[name] = "[accessor omitted]";
+        continue;
+      }
+      const classifiedKey = cleanKey.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z])([A-Z][a-z])/g, "$1_$2");
+      result[name] =
+        secretKey.test(classifiedKey) || /(?:^|[_-])secret[_-]?access[_-]?key$/i.test(classifiedKey)
+          ? "[redacted]"
+          : key === "data" && type === "image"
+            ? raster
+              ? text(data as string)
+              : "[opaque or oversized data omitted]"
+            : /^(thinkingSignature|thoughtSignature|textSignature)$/.test(key)
+              ? "[opaque data omitted]"
+              : visit(descriptor?.value, depth + 1);
+    }
+    seen.delete(value);
+    return result;
+  }
+  return { value: visit(input, 0), truncated };
+}