@narumitw/pi-inspect 0.0.0-stage → 0.1.0

package/src/projection.ts

@@ -0,0 +1,361 @@
+import {
+  getCurrentSystemMessage,
+  getCurrentSystemPrompt,
+  getCurrentTools,
+  getInitialSystemMessage,
+} from "@earendil-works/pi-ai";
+import {
+  buildSessionProjection,
+  type ExtensionContext,
+  parseSkillBlock,
+  type SessionEntry,
+  type ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+
+import { ancestry } from "./ancestry.js";
+import type { Collector } from "./collector.js";
+import { sessionContext } from "./context.js";
+import { correlatedCalls } from "./correlation.js";
+import { EntryIndex } from "./entry-index.js";
+import { identityIssue, recordedLeaf } from "./identity.js";
+import type { BranchView, ContextComposition, DetailView, EntrySummary, SkillView, Snapshot } from "./model.js";
+import { nativeProjection } from "./native-projection.js";
+import { capture, displayText, readSessionId, readSessionName } from "./privacy.js";
+import { systemReplayIssue } from "./system-message.js";
+
+export function summarize(entry: SessionEntry, label?: string): EntrySummary {
+  const issue = identityIssue(entry);
+  if (issue) throw new Error(issue);
+  const message = entry.type === "message" ? entry.message : undefined;
+  const kind = displayText(message ? message.role : entry.type).slice(0, 512);
+  const value = message && "content" in message ? message.content : entry;
+  const preview = capture(value, 180).value;
+  const name =
+    entry.type === "custom" || entry.type === "custom_message"
+      ? entry.customType
+      : entry.type === "model_change"
+        ? entry.modelId
+        : entry.type === "thinking_level_change"
+          ? entry.thinkingLevel
+          : message?.role === "assistant"
+            ? message.model
+            : message?.role === "toolResult"
+              ? message.toolName
+              : undefined;
+  const displayName = typeof name === "string" ? displayText(name) : undefined;
+  return {
+    id: entry.id,
+    parentId: entry.parentId,
+    kind,
+    timestamp: entry.timestamp,
+    name: displayName?.slice(0, 512),
+    nameTruncated: displayName !== undefined && displayName.length > 512 ? true : undefined,
+    tokens:
+      message?.role === "assistant" && Number.isFinite(message.usage?.totalTokens)
+        ? message.usage?.totalTokens
+        : undefined,
+    status:
+      message?.role === "toolResult" && typeof message.isError === "boolean"
+        ? message.isError
+          ? "error"
+          : "success"
+        : message?.role === "assistant" && message.stopReason === "error"
+          ? "error"
+          : message?.role === "assistant" && message.stopReason === "aborted"
+            ? "cancelled"
+            : undefined,
+    toolCallId: message?.role === "toolResult" ? message.toolCallId : undefined,
+    label: displayText(
+      typeof label === "string" ? label : typeof preview === "string" ? preview : JSON.stringify(preview),
+    ).slice(0, 180),
+  };
+}
+
+export function snapshot(
+  manager: ReadonlySessionManager,
+  collector: Collector,
+  generation: string,
+  revision: number,
+  prompt: string,
+  tools: ToolInfo[],
+  active: string[],
+  skills: SkillView[],
+  index = new EntryIndex(manager.getEntries()),
+  observedContext?: ContextComposition,
+): Snapshot {
+  const entries = index.entries;
+  const owning = new Map<string, { id: string; ids: Set<string> }>();
+  const invalidEntries: NonNullable<Snapshot["invalidEntries"]> = [];
+  let invalidEntryCount = 0;
+  const nodes: EntrySummary[] = [];
+  const leafId = recordedLeaf(manager, index.duplicates);
+  const reserved = new Set(leafId ? ancestry(manager, leafId, index).path.map((entry) => entry.id) : []);
+  let remaining = 10000 - reserved.size;
+  const included = entries.flatMap((entry, ordinal) =>
+    reserved.has(entry.id) || remaining-- > 0 ? [{ entry, ordinal }] : [],
+  );
+  for (const { ordinal, entry } of included) {
+    const reason = index.duplicates.has(entry.id) ? "duplicate entry id" : identityIssue(entry);
+    if (reason) {
+      invalidEntryCount++;
+      if (invalidEntries.length < 20) invalidEntries.push({ index: ordinal, reason, raw: capture(entry, 2048) });
+      continue;
+    }
+    const source =
+      entry.type === "message" && entry.message.role === "assistant"
+        ? {
+            id: entry.id,
+            ids: new Set(
+              (Array.isArray(entry.message.content) ? entry.message.content : [])
+                .filter((block) => block.type === "toolCall")
+                .map((block) => block.id),
+            ),
+          }
+        : entry.parentId
+          ? owning.get(entry.parentId)
+          : undefined;
+    if (source) owning.set(entry.id, source);
+    const label = manager.getLabel(entry.id);
+    if (label !== undefined && typeof label !== "string") {
+      invalidEntryCount++;
+      if (invalidEntries.length < 20)
+        invalidEntries.push({
+          index: ordinal,
+          reason: "non-string resolved label",
+          raw: capture({ entry, label }, 2048),
+        });
+    }
+    const node = summarize(entry, label);
+    if (node.toolCallId && source?.ids.has(node.toolCallId)) node.toolAnchor = source.id;
+    nodes.push(node);
+  }
+  return {
+    protocol: 1,
+    generation,
+    revision,
+    sessionId: readSessionId(manager),
+    ...readSessionName(manager),
+    leafId,
+    totalEntries: entries.length,
+    nodes,
+    incomplete: entries.length > 10000 || tools.length > 256 || skills.length > 256 || invalidEntryCount > 0,
+    invalidEntryCount,
+    invalidEntries,
+    context: observedContext ?? sessionContext(manager, index),
+    currentPrompt: capture(prompt, 65536),
+    tools: tools.slice(0, 256).map((t) => ({
+      name: displayText(t.name),
+      description: displayText(t.description).slice(0, 512),
+      exposure: t.exposure,
+      active: active.includes(t.name),
+      callable:
+        t.exposure === "codemode" || t.exposure === "deferred" || (t.exposure === "direct" && active.includes(t.name)),
+      namespace: t.namespace ? displayText(t.namespace.name) : undefined,
+      schema: capture(t.parameters, 2048),
+    })),
+    skills: skills.slice(0, 256).map((s) => ({
+      name: displayText(s.name),
+      path: displayText(s.path),
+      description: displayText(s.description).slice(0, 512),
+    })),
+    calls: collector.list(),
+    droppedCalls: collector.dropped,
+    invalidCallEvents: collector.invalidEvents,
+    captureStartedAt: collector.startedAt,
+  };
+}
+
+export function branch(
+  manager: ReadonlySessionManager,
+  leafId: string,
+  offset: number,
+  skills: SkillView[],
+  index = new EntryIndex(manager.getEntries()),
+): BranchView {
+  if (!index.byId.has(leafId)) throw new Error("Unknown entry");
+  const walked = ancestry(manager, leafId, index);
+  const { path } = walked;
+  const projection = walked.issue ? undefined : buildSessionProjection(path, leafId);
+  const target = index.get(leafId);
+  const previousView = !walked.issue && target?.parentId ? nativeProjection(path, target.parentId) : undefined;
+  const previous = previousView?.projection?.messages ?? [];
+  const issue = walked.issue ?? (projection && systemReplayIssue(projection.messages)) ?? systemReplayIssue(previous);
+  if (issue || !projection) {
+    const unavailable = capture(`[unavailable: ${issue}]`);
+    return {
+      leafId,
+      ancestryIssue: issue,
+      entries: path
+        .slice(offset, offset + 50)
+        .filter((entry) => !identityIssue(entry))
+        .map((entry) => summarize(entry, manager.getLabel(entry.id))),
+      total: path.length,
+      offset,
+      prompt: unavailable,
+      previousPrompt: unavailable,
+      sections: unavailable,
+      declaredTools: unavailable,
+      promptUpdates: unavailable,
+      projection: unavailable,
+      skillEvidence: unavailable,
+    };
+  }
+  const historicalSystem = getCurrentSystemMessage(projection.messages);
+  const evidence: { name: string; state: string; entryId: string }[] = [];
+  const callPaths = new Map<string, string>();
+  const byPath = new Map(skills.map((skill) => [skill.path, skill]));
+  let scanned = 0;
+  let evidenceIncomplete = false;
+  function spend(): boolean {
+    if (++scanned <= 2048 && evidence.length < 256) return true;
+    evidenceIncomplete = true;
+    return false;
+  }
+  evidenceLoop: for (const entry of path) {
+    if (identityIssue(entry)) continue;
+    if (entry.type !== "message") continue;
+    const m = entry.message;
+    if (m.role === "assistant") {
+      callPaths.clear();
+      const duplicateIds = new Set<string>();
+      const encountered = new Set<string>();
+      for (const block of Array.isArray(m.content) ? m.content : []) {
+        if (!spend()) break evidenceLoop;
+        if (block.type === "toolCall") {
+          if (encountered.has(block.id)) duplicateIds.add(block.id);
+          encountered.add(block.id);
+        }
+        if (
+          block.type === "toolCall" &&
+          block.name === "read" &&
+          typeof block.arguments?.path === "string" &&
+          block.arguments.path.length <= 8192
+        ) {
+          callPaths.set(block.id, block.arguments.path);
+        }
+      }
+      for (const id of duplicateIds) callPaths.delete(id);
+    }
+    if (m.role === "user" && typeof m.content === "string") {
+      if (!spend()) break;
+      if (m.content.length > 8192) {
+        evidenceIncomplete = true;
+        continue;
+      }
+      const invoked = parseSkillBlock(m.content);
+      if (invoked) evidence.push({ name: invoked.name, state: "explicitly invoked", entryId: entry.id });
+    }
+    if (m.role === "toolResult" && m.isError === false) {
+      if (!spend()) break;
+      const path = callPaths.get(m.toolCallId);
+      const skill = path ? byPath.get(path) : undefined;
+      if (skill) evidence.push({ name: skill.name, state: "successfully read", entryId: entry.id });
+      // Public bounded nested metadata provides names/arguments/status, never child results.
+      for (const call of Array.isArray(m.nestedCalls?.calls) ? m.nestedCalls.calls : []) {
+        if (!spend()) break evidenceLoop;
+        if (!call || typeof call !== "object" || call.name !== "read" || call.status !== "ok") continue;
+        const nestedPath = call.arguments?.path;
+        const skill = typeof nestedPath === "string" && nestedPath.length <= 8192 ? byPath.get(nestedPath) : undefined;
+        if (skill) {
+          evidence.push({ name: skill.name, state: "successfully read (nested metadata)", entryId: entry.id });
+        }
+      }
+    }
+  }
+  const capturedEvidence = capture(evidence);
+  capturedEvidence.truncated ||= evidenceIncomplete;
+  return {
+    leafId,
+    entries: path
+      .slice(offset, offset + 50)
+      .filter((entry) => !identityIssue(entry))
+      .map((e) => summarize(e, manager.getLabel(e.id))),
+    total: path.length,
+    offset,
+    prompt: capture(
+      historicalSystem ? getCurrentSystemPrompt(projection.messages) : "[unavailable: no stored system prompt]",
+      65536,
+    ),
+    previousPrompt: capture(
+      previousView?.issue
+        ? `[unavailable: ${previousView.issue}]`
+        : getCurrentSystemMessage(previous)
+          ? getCurrentSystemPrompt(previous)
+          : "[unavailable: no stored system prompt]",
+      65536,
+    ),
+    sections: capture(historicalSystem?.sections),
+    declaredTools: capture(
+      getInitialSystemMessage(projection.messages)
+        ? getCurrentTools(projection.messages).map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+          }))
+        : "[unavailable: no initial system/tool checkpoint]",
+    ),
+    promptUpdates: capture(
+      path
+        .filter((e) => e.type === "message" && e.message.role === "system")
+        .map((e) => ({ id: e.id, message: e.type === "message" ? e.message : null })),
+    ),
+    projection: capture(
+      projection.entries.map((e) => ({ id: e.sourceEntry.id, messages: e.messages })),
+      65536,
+    ),
+    skillEvidence: capturedEvidence,
+  };
+}
+
+export function detail(
+  manager: ReadonlySessionManager,
+  id: string,
+  leafId: string,
+  collector: Collector,
+  index = new EntryIndex(manager.getEntries()),
+): DetailView {
+  if (index.duplicates.has(id) || index.duplicates.has(leafId)) throw new Error("Ambiguous duplicate entry id");
+  const entry = index.get(id);
+  if (!entry || !index.get(leafId)) throw new Error("Unknown entry");
+  const selected = ancestry(manager, id, index);
+  const leaf = id === leafId ? selected : ancestry(manager, leafId, index);
+  const issue = selected.issue ?? leaf.issue;
+  if (issue)
+    return {
+      ancestryIssue: issue,
+      raw: capture(entry, 65536),
+      projected: capture(`[unavailable: ${issue}]`),
+      calls: [],
+    };
+  const projected = buildSessionProjection(leaf.path, leafId).entries.find((e) => e.sourceEntry.id === id);
+  const ids = new Set<string>();
+  if (entry.type === "message") {
+    const m = entry.message;
+    if (m.role === "assistant" && !identityIssue(entry))
+      for (const b of Array.isArray(m.content) ? m.content : []) if (b.type === "toolCall") ids.add(b.id);
+    if (m.role === "toolResult") ids.add(m.toolCallId);
+  }
+  const toolAnchor =
+    entry.type === "message" && entry.message.role === "assistant"
+      ? entry.id
+      : selected.path
+          .slice()
+          .reverse()
+          .find(
+            (candidate) =>
+              candidate.type === "message" &&
+              !identityIssue(candidate) &&
+              candidate.message.role === "assistant" &&
+              (Array.isArray(candidate.message.content) ? candidate.message.content : []).some(
+                (block) => block.type === "toolCall" && ids.has(block.id),
+              ),
+          )?.id;
+  return {
+    toolAnchor,
+    raw: capture(entry, 65536),
+    projected: capture(projected?.messages),
+    calls: correlatedCalls(ids, toolAnchor, collector.list()),
+  };
+}

package/src/server.ts

@@ -0,0 +1,202 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createServer, type ServerResponse } from "node:http";
+import type { Socket } from "node:net";
+
+export interface ViewerServer {
+  url: string;
+  token: string;
+  origin: string;
+  invalidate(revision: number): void;
+  close(): Promise<void>;
+}
+export interface ServerOptions {
+  generation: string;
+  signal: AbortSignal;
+  snapshot(): unknown;
+  branch(id: string, offset: number): unknown;
+  detail(id: string, leaf: string): unknown;
+  assets?: Map<string, { type: string; body: string | Buffer }>;
+}
+export function sendRevision(response: { write(frame: string): boolean; destroy(): void }, frame: string): void {
+  // No extension-owned queue: close a backpressured client; reconnect fetches a fresh snapshot.
+  if (!response.write(frame)) response.destroy();
+}
+export async function startServer(options: ServerOptions): Promise<ViewerServer> {
+  const assets =
+    options.assets ??
+    new Map([
+      [
+        "/",
+        {
+          type: "text/html; charset=utf-8",
+          body: await readFile(new URL("../dist/index.html", import.meta.url), { signal: options.signal }),
+        },
+      ],
+      [
+        "/app.js",
+        {
+          type: "text/javascript; charset=utf-8",
+          body: await readFile(new URL("../dist/app.js", import.meta.url), { signal: options.signal }),
+        },
+      ],
+      [
+        "/app.css",
+        {
+          type: "text/css; charset=utf-8",
+          body: await readFile(new URL("../dist/app.css", import.meta.url), { signal: options.signal }),
+        },
+      ],
+    ]);
+  options.signal.throwIfAborted();
+  const token = randomBytes(32).toString("base64url");
+  const clients = new Set<ServerResponse>();
+  const sockets = new Set<Socket>();
+  let closed = false;
+  let origin = "";
+  let revision = 0;
+  let closing: Promise<void> | undefined;
+  const frame = () =>
+    `id: ${revision}\ndata: ${JSON.stringify({ protocol: 1, generation: options.generation, revision })}\n\n`;
+  const server = createServer((req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    res.setHeader(
+      "Content-Security-Policy",
+      "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+    );
+    const fail = (status: number, message: string) => {
+      res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(message);
+    };
+    if (closed || options.signal.aborted) return fail(410, "Session closed");
+    if (
+      req.headers.host !== origin.slice("http://".length) ||
+      (req.headers.origin !== undefined && req.headers.origin !== origin) ||
+      req.headers["sec-fetch-site"] === "cross-site"
+    )
+      return fail(403, "Forbidden");
+    if (req.method !== "GET") return fail(405, "Read-only viewer");
+    let url: URL;
+    try {
+      url = new URL(req.url ?? "/", origin);
+    } catch {
+      return fail(400, "Invalid URL");
+    }
+    if (url.origin !== origin) return fail(403, "Forbidden");
+    const asset = assets.get(url.pathname);
+    if (asset && !url.search) {
+      res.writeHead(200, { "Content-Type": asset.type });
+      // Generation is a public epoch identifier, not a credential. Encoding keeps the HTML boundary inert.
+      const body =
+        url.pathname === "/"
+          ? asset.body
+              .toString()
+              .replace(
+                "<head>",
+                `<head><meta name="inspector-generation" content="${encodeURIComponent(options.generation)}">`,
+              )
+          : asset.body;
+      res.end(body);
+      return;
+    }
+    if (!url.pathname.startsWith("/api/")) return fail(404, "Not found");
+    const provided = req.headers["x-inspector-token"];
+    if (
+      typeof provided !== "string" ||
+      Buffer.byteLength(provided) !== Buffer.byteLength(token) ||
+      !timingSafeEqual(Buffer.from(provided), Buffer.from(token))
+    )
+      return fail(401, "Unauthorized");
+    if (url.searchParams.get("generation") !== options.generation) return fail(409, "Session generation changed");
+    if (url.pathname === "/api/events") {
+      if (clients.size >= 8) return fail(429, "Too many viewers");
+      res.writeHead(200, { "Content-Type": "text/event-stream", Connection: "keep-alive" });
+      clients.add(res);
+      res.on("close", () => clients.delete(res));
+      sendRevision(res, frame());
+      return;
+    }
+    try {
+      let result: unknown;
+      if (url.pathname === "/api/snapshot") result = options.snapshot();
+      else if (url.pathname === "/api/branch") {
+        const offset = url.searchParams.get("offset") ?? "0";
+        if (!/^\d{1,8}$/.test(offset)) return fail(400, "Invalid offset");
+        result = options.branch(url.searchParams.get("leaf") ?? "", Number(offset));
+      } else if (url.pathname === "/api/detail") {
+        result = options.detail(url.searchParams.get("id") ?? "", url.searchParams.get("leaf") ?? "");
+      } else return fail(404, "Not found");
+      res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify(result));
+    } catch {
+      fail(400, "Unavailable session data");
+    }
+  });
+  server.requestTimeout = 10000;
+  server.headersTimeout = 10000;
+  server.maxHeadersCount = 32;
+  server.on("connection", (socket) => {
+    if (sockets.size >= 32) {
+      socket.destroy();
+      return;
+    }
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+  });
+  const close = (): Promise<void> => {
+    if (closing) return closing;
+    closed = true;
+    options.signal.removeEventListener("abort", abort);
+    for (const client of clients) client.destroy();
+    clients.clear();
+    for (const socket of sockets) socket.destroy();
+    closing = new Promise((resolve) => server.close(() => resolve()));
+    return closing;
+  };
+  const abort = () => {
+    void close();
+  };
+  // Register before listen, and recheck after readiness to cover abort during startup.
+  options.signal.addEventListener("abort", abort, { once: true });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const cancelled = () => reject(new Error("Server startup cancelled"));
+      options.signal.addEventListener("abort", cancelled, { once: true });
+      const failed = (error: Error) => {
+        options.signal.removeEventListener("abort", cancelled);
+        reject(error);
+      };
+      server.once("error", failed);
+      server.listen({ port: 0, host: "127.0.0.1", signal: options.signal }, () => {
+        options.signal.removeEventListener("abort", cancelled);
+        server.removeListener("error", failed);
+        resolve();
+      });
+    });
+    options.signal.throwIfAborted();
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await close();
+    throw new Error("No loopback address");
+  }
+  origin = `http://127.0.0.1:${address.port}`;
+  return {
+    token,
+    origin,
+    url: `${origin}/#${token}`,
+    invalidate(next) {
+      if (!closed) {
+        revision = next;
+        for (const res of clients) sendRevision(res, frame());
+      }
+    },
+    close,
+  };
+}

package/src/system-message.ts

@@ -0,0 +1,117 @@
+// Native historical replay is allowed only within this cumulative input budget.
+export const SYSTEM_REPLAY_CHARACTERS = 1_048_576;
+export const SYSTEM_REPLAY_TOOL_DELTAS = 2048;
+
+export function systemReplayIssue(messages: readonly unknown[]): string | undefined {
+  let remaining = SYSTEM_REPLAY_CHARACTERS;
+  let deltas = SYSTEM_REPLAY_TOOL_DELTAS;
+  let nodes = 16_384;
+  const seen = new WeakSet<object>();
+  // Count raw lengths without serializing, sanitizing, or materializing large metadata.
+  function declaration(value: unknown, depth = 0): boolean {
+    if (--nodes < 0 || depth > 32) return false;
+    if (typeof value === "string") {
+      remaining -= value.length;
+      return remaining >= 0;
+    }
+    if (!value || typeof value !== "object" || seen.has(value)) return true;
+    seen.add(value);
+    if (Array.isArray(value) && value.length > nodes) return false;
+    for (const key in value) {
+      if (!Object.hasOwn(value, key)) continue;
+      remaining -= key.length + 2;
+      if (remaining < 0) return false;
+      const property = Object.getOwnPropertyDescriptor(value, key);
+      if (property?.get || property?.set || !declaration(property?.value, depth + 1)) return false;
+    }
+    return true;
+  }
+  for (const value of messages) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const m = value as Record<string, unknown>;
+    if (m.role !== "system") continue;
+    for (const [kind, delta] of [
+      ["added", m.toolsAdded],
+      ["removed", m.toolsRemoved],
+    ] as const) {
+      if (!Array.isArray(delta)) continue;
+      deltas -= delta.length;
+      if (deltas < 0) return "system tool replay exceeds 2,048 cumulative delta budget";
+      for (const tool of delta) {
+        if (
+          !declaration(
+            kind === "added"
+              ? { name: tool.name, description: tool.description, parameters: tool.parameters }
+              : { name: tool.name },
+          )
+        )
+          return "system tool replay exceeds metadata character/node/depth budget";
+      }
+    }
+    remaining -= 2; // Bound join separators even for empty fragments.
+    if (typeof m.content === "string") remaining -= m.content.length;
+    else if (Array.isArray(m.content)) {
+      remaining -= m.content.length; // Also bound native filter/map work and block separators.
+      if (remaining < 0) return "system replay exceeds 1,048,576-character input budget";
+      for (const block of m.content) {
+        if (block?.type === "text" && typeof block.text === "string") remaining -= block.text.length;
+        if (remaining < 0) return "system replay exceeds 1,048,576-character input budget";
+      }
+    }
+    if (remaining < 0) return "system replay exceeds 1,048,576-character input budget";
+    if (m.sections && typeof m.sections === "object") {
+      for (const [key, part] of Object.entries(m.sections)) {
+        remaining -= key.length + 2 + (typeof part === "string" ? part.length : 0);
+        if (remaining < 0) return "system replay exceeds 1,048,576-character input budget";
+      }
+    }
+  }
+  return undefined;
+}
+
+// Validate the fields consumed by Pi AI's system-prompt/tool replay. Checkpoints
+// are injected directly; ordinary session messages are normalized by the caller.
+export function systemMessageIssue(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "malformed system-message envelope";
+  const m = value as Record<string, unknown>;
+  if (m.role !== "system") return "malformed system-message role";
+  if (Array.isArray(m.content) && m.content.length > 2048) return "system content exceeds 2,048-block budget";
+  if (
+    typeof m.content !== "string" &&
+    (!Array.isArray(m.content) ||
+      m.content.some(
+        (block) =>
+          !block ||
+          typeof block !== "object" ||
+          Array.isArray(block) ||
+          (block.type === "text" && typeof block.text !== "string"),
+      ))
+  )
+    return "malformed system-message content";
+  if (
+    m.sections != null &&
+    (typeof m.sections !== "object" ||
+      Array.isArray(m.sections) ||
+      Object.values(m.sections).some((part) => part !== null && typeof part !== "string"))
+  )
+    return "malformed system-message sections";
+  for (const delta of [m.toolsAdded, m.toolsRemoved]) {
+    if (Array.isArray(delta) && delta.length > SYSTEM_REPLAY_TOOL_DELTAS)
+      return "system tool delta exceeds 2,048-entry budget";
+    if (
+      delta != null &&
+      (!Array.isArray(delta) ||
+        delta.some(
+          (tool) =>
+            !tool ||
+            typeof tool !== "object" ||
+            Array.isArray(tool) ||
+            typeof tool.name !== "string" ||
+            !tool.name.length ||
+            tool.name.length > 512,
+        ))
+    )
+      return "malformed system-message tool delta";
+  }
+  return undefined;
+}