@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/client-web/src/readme-gen-view.ts

@@ -0,0 +1,145 @@
+export type ReadmeGenOperation = "report" | "write";
+export type ReadmeGenStatusState = "idle" | "running" | "completed" | "failed" | "cancelled" | "unknown";
+
+export interface ReadmeGenPanelView {
+  readonly generated: { readonly name: string; readonly scripts: number; readonly plugins: number } | null;
+  readonly lastWrite: { readonly path: string; readonly bytes: number; readonly overwritten: boolean } | null;
+  readonly status: {
+    readonly state: ReadmeGenStatusState;
+    readonly operation: ReadmeGenOperation | null;
+    readonly at: string | null;
+    readonly error: string | null;
+  };
+  readonly malformed: boolean;
+  readonly limits: {
+    readonly nameCharacters: number;
+    readonly pathCharacters: number;
+    readonly scripts: number;
+    readonly plugins: number;
+    readonly errorCharacters: number;
+  };
+}
+
+const limits = { nameCharacters: 256, pathCharacters: 512, scripts: 256, plugins: 256, errorCharacters: 2_000 } as const;
+const maxMarkdownBytes = 1024 * 1024;
+const rootKeys = new Set(["generated", "name", "scripts", "plugins", "lastWrite", "status"]);
+const writeKeys = new Set(["path", "bytes", "overwritten"]);
+const statusKeys = new Set(["state", "operation", "at", "error"]);
+
+function ownDataRecord(value: unknown, allowed: ReadonlySet<string>): Record<string, unknown> | undefined {
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !allowed.has(key))) return undefined;
+    const output = Object.create(null) as Record<string, unknown>;
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (!("value" in descriptor)) return undefined;
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch {
+    return undefined;
+  }
+}
+
+function count(value: unknown, maximum: number): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : undefined;
+}
+
+function timestamp(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 64) return undefined;
+  const milliseconds = Date.parse(value);
+  if (!Number.isFinite(milliseconds)) return undefined;
+  try {
+    return new Date(milliseconds).toISOString() === value ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function safeName(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || [...value].length > limits.nameCharacters) return undefined;
+  if (new TextEncoder().encode(value).byteLength > 512 || /[\p{Cc}\p{Cf}\p{Cs}]/u.test(value)) return undefined;
+  return value;
+}
+
+function safePath(value: unknown): string | undefined {
+  if (typeof value !== "string" || value === "" || value !== value.trim() || [...value].length > limits.pathCharacters) return undefined;
+  if (new TextEncoder().encode(value).byteLength > limits.pathCharacters || /[\\\p{Cc}\p{Cf}\p{Cs}]/u.test(value)) return undefined;
+  const segments = value.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment !== segment.trim())) return undefined;
+  const fileName = segments.at(-1);
+  return fileName !== undefined && /^README(?:[._-][^/]*)?\.md$/iu.test(fileName) ? value : undefined;
+}
+
+function statusView(value: unknown): ReadmeGenPanelView["status"] | undefined {
+  const source = ownDataRecord(value, statusKeys);
+  if (source === undefined) return undefined;
+  const state = source.state;
+  const operation = source.operation;
+  const at = source.at;
+  const error = source.error;
+  const hasOperation = Object.hasOwn(source, "operation");
+  const hasAt = Object.hasOwn(source, "at");
+  const hasError = Object.hasOwn(source, "error");
+  if (state === "idle" && !hasOperation && !hasAt && !hasError) return { state, operation: null, at: null, error: null };
+  if (state === "running" && (operation === "report" || operation === "write") && !hasAt && !hasError) return { state, operation, at: null, error: null };
+  const normalizedAt = timestamp(at);
+  if (state === "completed" && (operation === "report" || operation === "write") && normalizedAt !== undefined && !hasError)
+    return { state, operation, at: normalizedAt, error: null };
+  if (
+    (state === "failed" || state === "cancelled") &&
+    (operation === "report" || operation === "write") &&
+    normalizedAt !== undefined &&
+    typeof error === "string" &&
+    error.length > 0 &&
+    error.length <= limits.errorCharacters &&
+    !/[\p{Cc}\p{Cf}\p{Cs}]/u.test(error)
+  )
+    return { state, operation, at: normalizedAt, error };
+  return undefined;
+}
+
+function malformedView(): ReadmeGenPanelView {
+  return {
+    generated: null,
+    lastWrite: null,
+    status: { state: "unknown", operation: null, at: null, error: null },
+    malformed: true,
+    limits: { ...limits },
+  };
+}
+
+export function readmeGenPanelView(data: unknown): ReadmeGenPanelView {
+  const source = ownDataRecord(data, rootKeys);
+  if (source === undefined || typeof source.generated !== "boolean") return malformedView();
+  const status = statusView(source.status);
+  if (status === undefined) return malformedView();
+
+  let generated: ReadmeGenPanelView["generated"] = null;
+  if (source.generated) {
+    const name = safeName(source.name);
+    const scripts = count(source.scripts, limits.scripts);
+    const plugins = count(source.plugins, limits.plugins);
+    if (name === undefined || scripts === undefined || plugins === undefined) return malformedView();
+    generated = { name, scripts, plugins };
+  } else if (Object.hasOwn(source, "name") || Object.hasOwn(source, "scripts") || Object.hasOwn(source, "plugins")) {
+    return malformedView();
+  }
+
+  let lastWrite: ReadmeGenPanelView["lastWrite"] = null;
+  if (source.lastWrite !== null) {
+    const write = ownDataRecord(source.lastWrite, writeKeys);
+    const path = safePath(write?.path);
+    const bytes = count(write?.bytes, maxMarkdownBytes);
+    const overwritten = write?.overwritten;
+    if (write === undefined || path === undefined || bytes === undefined || typeof overwritten !== "boolean") return malformedView();
+    lastWrite = { path, bytes, overwritten };
+  }
+
+  if ((!source.generated && lastWrite !== null) || (status.state === "idle" && (source.generated || lastWrite !== null))) return malformedView();
+  if (status.state === "completed" && (!source.generated || (status.operation === "write" && lastWrite === null))) return malformedView();
+  return { generated, lastWrite, status, malformed: false, limits: { ...limits } };
+}

package/packages/client-web/src/recall-unread-view.ts

@@ -0,0 +1,105 @@
+const defaults = {
+  directoryEntries: 4_096,
+  sessionBytes: 4_194_304,
+  sessions: 100,
+  allowedSessions: 500,
+  readConcurrency: 8,
+  contentParts: 1_000,
+  previewCharacters: 500,
+  panelItems: 50,
+  toolItems: 100,
+  queryCharacters: 120,
+  sessionIdCharacters: 256,
+  sessionNameCharacters: 256,
+  sessionPathCharacters: 4_096,
+  statusErrorCharacters: 2_000,
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function limit(value: unknown, fallback: number, maximum = fallback): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= maximum ? value : fallback;
+}
+
+function count(value: unknown, maximum: number): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : 0;
+}
+
+function text(value: unknown, maximum: number, fallback = ""): string {
+  if (typeof value !== "string") return fallback;
+  return value.replaceAll("\0", "�").slice(0, maximum) || fallback;
+}
+
+function timestamp(value: unknown): string | null {
+  if (typeof value !== "string" || value.length > 64) return null;
+  try {
+    return new Date(value).toISOString() === value ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function status(value: unknown, errorLimit: number) {
+  if (!isRecord(value)) return { state: "idle" as const, at: null, error: null };
+  const state = value.state === "running" || value.state === "completed" || value.state === "failed" || value.state === "cancelled" ? value.state : "idle";
+  const at = timestamp(value.at);
+  if ((state === "completed" || state === "failed" || state === "cancelled") && at === null) return { state: "idle" as const, at: null, error: null };
+  const error = state === "failed" || state === "cancelled" ? text(value.error, errorLimit) || null : null;
+  return { state, at, error };
+}
+
+export function recallUnreadPanelView(data: unknown) {
+  const source = isRecord(data) ? data : {};
+  const rawLimits = isRecord(source.limits) ? source.limits : {};
+  const allowedSessions = limit(rawLimits.allowedSessions, defaults.allowedSessions);
+  const limits = {
+    directoryEntries: limit(rawLimits.directoryEntries, defaults.directoryEntries),
+    sessionBytes: limit(rawLimits.sessionBytes, defaults.sessionBytes),
+    sessions: limit(rawLimits.sessions, Math.min(defaults.sessions, allowedSessions), allowedSessions),
+    allowedSessions,
+    readConcurrency: limit(rawLimits.readConcurrency, defaults.readConcurrency),
+    contentParts: limit(rawLimits.contentParts, defaults.contentParts),
+    previewCharacters: limit(rawLimits.previewCharacters, defaults.previewCharacters),
+    panelItems: limit(rawLimits.panelItems, defaults.panelItems),
+    toolItems: limit(rawLimits.toolItems, defaults.toolItems),
+    queryCharacters: limit(rawLimits.queryCharacters, defaults.queryCharacters),
+    sessionIdCharacters: limit(rawLimits.sessionIdCharacters, defaults.sessionIdCharacters),
+    sessionNameCharacters: limit(rawLimits.sessionNameCharacters, defaults.sessionNameCharacters),
+    sessionPathCharacters: limit(rawLimits.sessionPathCharacters, defaults.sessionPathCharacters),
+    statusErrorCharacters: limit(rawLimits.statusErrorCharacters, defaults.statusErrorCharacters),
+  };
+  const items = (Array.isArray(source.items) ? source.items : []).slice(0, limits.panelItems).map((value) => {
+    const item = isRecord(value) ? value : {};
+    const id = text(item.id, limits.sessionIdCharacters, "unknown");
+    return {
+      id,
+      path: text(item.path, limits.sessionPathCharacters),
+      cwd: text(item.cwd, limits.sessionPathCharacters),
+      name: text(item.name, limits.sessionNameCharacters, id),
+      modified: timestamp(item.modified),
+      messageCount: count(item.messageCount, limits.sessionBytes),
+      message: text(item.message, limits.previewCharacters),
+    };
+  });
+  const rawInventory = isRecord(source.inventory) ? source.inventory : {};
+  return {
+    scans: count(source.scans, Number.MAX_SAFE_INTEGER),
+    total: count(source.total, limits.sessions),
+    items,
+    status: status(source.status, limits.statusErrorCharacters),
+    inventory: {
+      available: count(rawInventory.available, limits.directoryEntries),
+      candidates: count(rawInventory.candidates, limits.directoryEntries),
+      scanned: count(rawInventory.scanned, limits.sessions),
+      unread: count(rawInventory.unread, limits.sessions),
+      shown: count(rawInventory.shown, limits.panelItems),
+      truncated: rawInventory.truncated === true,
+      discoveryTruncated: rawInventory.discoveryTruncated === true,
+      scanTruncated: rawInventory.scanTruncated === true,
+      displayTruncated: rawInventory.displayTruncated === true,
+    },
+    limits,
+  };
+}

package/packages/client-web/src/session-bridge-view.ts

@@ -0,0 +1,118 @@
+import { ownArray, ownRecord } from "./panel-safe.js";
+
+const defaults = {
+  packageBytes: 262_144,
+  packageCharacters: 262_144,
+  messages: 100,
+  messageCharacters: 16_000,
+  totalMessageCharacters: 64_000,
+  contentParts: 1_000,
+  attachments: 100,
+  attachmentMarkerCharacters: 256,
+  sessionIdCharacters: 256,
+  cwdCharacters: 4_096,
+  modelFieldCharacters: 256,
+  previewTextCharacters: 1_000,
+  previewListItems: 8,
+  duplicateScanEntries: 10_000,
+  operationErrorCharacters: 2_000,
+} as const;
+
+function limit(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= fallback ? value : fallback;
+}
+
+function boundedString(value: unknown, maximum: number): string {
+  return typeof value === "string" ? value.slice(0, maximum) : "";
+}
+
+function timestamp(value: unknown): string | null {
+  if (typeof value !== "string" || value.length > 64) return null;
+  try {
+    return new Date(value).toISOString() === value ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function boundedCount(value: unknown, maximum: number): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : null;
+}
+
+function preview(value: unknown, textLimit: number, listLimit: number) {
+  const source = ownRecord(value) ?? {};
+  const list = (input: unknown): string[] =>
+    (ownArray(input, listLimit) ?? [])
+      .slice(0, listLimit)
+      .map((item) => boundedString(item, textLimit))
+      .filter((item) => item !== "");
+  return {
+    goal: boundedString(source.goal, textLimit),
+    currentState: boundedString(source.currentState, textLimit),
+    decisions: list(source.decisions),
+    keyFiles: list(source.keyFiles),
+    nextStep: boundedString(source.nextStep, textLimit),
+  };
+}
+
+function bridgeSource(value: unknown, limits: typeof defaults) {
+  const source = ownRecord(value);
+  if (source === undefined) return null;
+  const sessionId = boundedString(source.sessionId, limits.sessionIdCharacters);
+  const cwd = boundedString(source.cwd, limits.cwdCharacters);
+  if (sessionId === "" || cwd === "") return null;
+  let model: { provider: string; modelId: string } | undefined;
+  const rawModel = ownRecord(source.model);
+  if (rawModel !== undefined) {
+    const provider = boundedString(rawModel.provider, limits.modelFieldCharacters);
+    const modelId = boundedString(rawModel.modelId, limits.modelFieldCharacters);
+    if (provider !== "" && modelId !== "") model = { provider, modelId };
+  }
+  return { sessionId, cwd, ...(model === undefined ? {} : { model }) };
+}
+
+function operationStatus(value: unknown, errorLimit: number) {
+  const source = ownRecord(value);
+  if (source === undefined) return { state: "idle" as const, operation: null, at: null, error: null };
+  const state =
+    source.state === "idle" || source.state === "running" || source.state === "completed" || source.state === "failed" || source.state === "cancelled"
+      ? source.state
+      : "idle";
+  const operation = source.operation === "export" || source.operation === "preview" || source.operation === "import" ? source.operation : null;
+  const at = timestamp(source.at);
+  if (state !== "idle" && operation === null) return { state: "idle" as const, operation: null, at: null, error: null };
+  if ((state === "completed" || state === "failed" || state === "cancelled") && at === null)
+    return { state: "idle" as const, operation: null, at: null, error: null };
+  const error = state === "failed" || state === "cancelled" ? boundedString(source.error, errorLimit) || null : null;
+  return { state, operation, at, error };
+}
+
+export function sessionBridgePanelView(data: unknown) {
+  const source = ownRecord(data) ?? {};
+  const rawLimits = ownRecord(source.limits) ?? {};
+  const limits = Object.fromEntries(Object.entries(defaults).map(([key, fallback]) => [key, limit(rawLimits[key], fallback)])) as unknown as typeof defaults;
+  const rawLatest = ownRecord(source.latest);
+  const direction = rawLatest?.direction === "export" || rawLatest?.direction === "import" ? rawLatest.direction : undefined;
+  const latestSessionId = boundedString(rawLatest?.sessionId, limits.sessionIdCharacters);
+  const latestMessages = boundedCount(rawLatest?.messages, limits.messages);
+  const latestAttachments = boundedCount(rawLatest?.attachments, limits.attachments);
+  const latestAt = timestamp(rawLatest?.at);
+  const latest =
+    direction === undefined || latestSessionId === "" || latestMessages === null || latestAttachments === null || latestAt === null
+      ? null
+      : { direction, sessionId: latestSessionId, messages: latestMessages, attachments: latestAttachments, at: latestAt };
+  const rawLatestPreviewCandidate = ownRecord(source.latestPreview);
+  const rawLatestPreview =
+    rawLatestPreviewCandidate !== undefined && ownRecord(rawLatestPreviewCandidate.preview) !== undefined ? rawLatestPreviewCandidate : undefined;
+  const latestSource = bridgeSource(rawLatestPreview?.source, limits);
+  const selectedPreview = rawLatestPreview === undefined ? source.currentPreview : rawLatestPreview.preview;
+  return {
+    latest,
+    source: rawLatestPreview === undefined ? null : latestSource,
+    preview: preview(selectedPreview, limits.previewTextCharacters, limits.previewListItems),
+    previewAt: rawLatestPreview === undefined ? null : timestamp(rawLatestPreview.at),
+    status: operationStatus(source.status, limits.operationErrorCharacters),
+    formatVersion: 1 as const,
+    limits,
+  };
+}

package/packages/client-web/src/session-insights-view.ts

@@ -0,0 +1,205 @@
+export type SessionInsightsCompactionStatus = "idle" | "queued" | "running" | "completed" | "failed" | "cancelled" | "unknown";
+
+export interface SessionInsightsReportView {
+  readonly sessionId: string;
+  readonly userMessages: number;
+  readonly assistantMessages: number;
+  readonly toolCalls: number;
+  readonly toolResults: number;
+  readonly totalMessages: number;
+  readonly tokens: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+  };
+  readonly cost: number;
+  readonly contextUsage: {
+    readonly tokens: number | null;
+    readonly contextWindow: number;
+    readonly percent: number | null;
+  } | null;
+}
+
+export interface SessionInsightsCompactionView {
+  readonly status: SessionInsightsCompactionStatus;
+  readonly requestedAt: string | null;
+  readonly startedAt: string | null;
+  readonly finishedAt: string | null;
+  readonly error: string | null;
+}
+
+export interface SessionInsightsPanelView {
+  readonly report: SessionInsightsReportView | null;
+  readonly compaction: SessionInsightsCompactionView;
+  readonly malformed: boolean;
+  readonly limits: {
+    readonly sessionIdCharacters: number;
+    readonly errorCharacters: number;
+  };
+}
+
+const fixedLimits = { sessionIdCharacters: 512, errorCharacters: 2_000 } as const;
+const maxCost = 1_000_000_000;
+
+function unknownCompaction(): SessionInsightsCompactionView {
+  return { status: "unknown", requestedAt: null, startedAt: null, finishedAt: null, error: null };
+}
+
+function ownDataRecord(value: unknown): Record<string, unknown> | undefined {
+  try {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) return undefined;
+    const output = Object.create(null) as Record<string, unknown>;
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (!("value" in descriptor)) return undefined;
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch {
+    return undefined;
+  }
+}
+
+function count(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function reportView(source: Record<string, unknown>): SessionInsightsReportView | undefined {
+  const sessionId = source.sessionId;
+  const tokens = ownDataRecord(source.tokens);
+  const userMessages = count(source.userMessages);
+  const assistantMessages = count(source.assistantMessages);
+  const toolCalls = count(source.toolCalls);
+  const toolResults = count(source.toolResults);
+  const totalMessages = count(source.totalMessages);
+  const input = count(tokens?.input);
+  const output = count(tokens?.output);
+  const cacheRead = count(tokens?.cacheRead);
+  const cacheWrite = count(tokens?.cacheWrite);
+  const total = count(tokens?.total);
+  const cost = source.cost;
+  if (
+    typeof sessionId !== "string" ||
+    sessionId.length === 0 ||
+    sessionId.length > fixedLimits.sessionIdCharacters ||
+    /[\0\p{Cc}]/u.test(sessionId) ||
+    tokens === undefined ||
+    userMessages === undefined ||
+    assistantMessages === undefined ||
+    toolCalls === undefined ||
+    toolResults === undefined ||
+    totalMessages === undefined ||
+    !Number.isSafeInteger(userMessages + assistantMessages + toolResults) ||
+    userMessages + assistantMessages + toolResults > totalMessages ||
+    input === undefined ||
+    output === undefined ||
+    cacheRead === undefined ||
+    cacheWrite === undefined ||
+    total === undefined ||
+    !Number.isSafeInteger(input + output + cacheRead + cacheWrite) ||
+    total !== input + output + cacheRead + cacheWrite ||
+    typeof cost !== "number" ||
+    !Number.isFinite(cost) ||
+    cost < 0 ||
+    cost > maxCost
+  )
+    return undefined;
+
+  let contextUsage: SessionInsightsReportView["contextUsage"] = null;
+  if (source.contextUsage !== null) {
+    const usage = ownDataRecord(source.contextUsage);
+    const usageTokens = usage?.tokens;
+    const contextWindow = count(usage?.contextWindow);
+    const percent = usage?.percent;
+    const tokensValid = usageTokens === null || count(usageTokens) !== undefined;
+    const percentValid = percent === null || (typeof percent === "number" && Number.isFinite(percent) && percent >= 0);
+    const nullabilityMatches = (usageTokens === null) === (percent === null);
+    const expectedPercent = typeof usageTokens === "number" && contextWindow !== undefined && contextWindow > 0 ? (usageTokens / contextWindow) * 100 : null;
+    const percentMatches =
+      expectedPercent === null ||
+      (typeof percent === "number" && Math.abs(percent - expectedPercent) <= Math.max(1e-9, Math.abs(expectedPercent) * Number.EPSILON * 8));
+    if (usage === undefined || !tokensValid || contextWindow === undefined || contextWindow <= 0 || !percentValid || !nullabilityMatches || !percentMatches)
+      return undefined;
+    contextUsage = { tokens: usageTokens as number | null, contextWindow, percent };
+  }
+
+  return {
+    sessionId,
+    userMessages,
+    assistantMessages,
+    toolCalls,
+    toolResults,
+    totalMessages,
+    tokens: { input, output, cacheRead, cacheWrite, total },
+    cost,
+    contextUsage,
+  };
+}
+
+function timestamp(value: unknown): string | null {
+  if (typeof value !== "string" || value.length > 64) return null;
+  const milliseconds = Date.parse(value);
+  if (!Number.isFinite(milliseconds)) return null;
+  try {
+    return new Date(milliseconds).toISOString() === value ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function compactionView(source: Record<string, unknown>): SessionInsightsCompactionView | undefined {
+  const status = source.status;
+  const requestedAt = timestamp(source.requestedAt);
+  const startedAt = timestamp(source.startedAt);
+  const finishedAt = timestamp(source.finishedAt);
+  const error = source.error;
+  const hasRequestedAt = source.requestedAt !== undefined;
+  const hasStartedAt = source.startedAt !== undefined;
+  const hasFinishedAt = source.finishedAt !== undefined;
+  const hasError = source.error !== undefined;
+  const ordered =
+    requestedAt !== null &&
+    (startedAt === null || Date.parse(requestedAt) <= Date.parse(startedAt)) &&
+    (finishedAt === null || Date.parse(startedAt ?? requestedAt) <= Date.parse(finishedAt));
+  const validError = typeof error === "string" && error.length > 0 && error.length <= fixedLimits.errorCharacters && !error.includes("\0") ? error : null;
+
+  if (status === "idle" && !hasRequestedAt && !hasStartedAt && !hasFinishedAt && !hasError)
+    return { status, requestedAt: null, startedAt: null, finishedAt: null, error: null };
+  if (status === "queued" && hasRequestedAt && !hasStartedAt && !hasFinishedAt && !hasError && ordered)
+    return { status, requestedAt, startedAt: null, finishedAt: null, error: null };
+  if (status === "running" && hasRequestedAt && hasStartedAt && !hasFinishedAt && !hasError && ordered)
+    return { status, requestedAt, startedAt, finishedAt: null, error: null };
+  if (status === "completed" && hasRequestedAt && hasStartedAt && hasFinishedAt && !hasError && ordered)
+    return { status, requestedAt, startedAt, finishedAt, error: null };
+  if (
+    (status === "failed" || status === "cancelled") &&
+    hasRequestedAt &&
+    hasFinishedAt &&
+    (!hasStartedAt || startedAt !== null) &&
+    ordered &&
+    validError !== null
+  )
+    return { status, requestedAt, startedAt, finishedAt, error: validError };
+  return unknownCompaction();
+}
+
+export function sessionInsightsPanelView(data: unknown): SessionInsightsPanelView {
+  const source = ownDataRecord(data);
+  if (source === undefined) return { report: null, compaction: unknownCompaction(), malformed: true, limits: { ...fixedLimits } };
+  const report = reportView(source);
+  const compactionSource = ownDataRecord(source.compaction);
+  if (report === undefined || compactionSource === undefined)
+    return { report: null, compaction: unknownCompaction(), malformed: true, limits: { ...fixedLimits } };
+  const compaction = compactionView(compactionSource);
+  return {
+    report,
+    compaction: compaction ?? unknownCompaction(),
+    malformed: compaction === undefined || compaction.status === "unknown",
+    limits: { ...fixedLimits },
+  };
+}

package/packages/client-web/src/skill-guard-view.ts

@@ -0,0 +1,94 @@
+const defaults = {
+  queryCharacters: 120,
+  skillBytes: 131_072,
+  skills: 50,
+  panelReports: 20,
+  nameCharacters: 64,
+  sourceCharacters: 128,
+  pathCharacters: 4_096,
+  statusErrorCharacters: 2_000,
+  findingsPerSkill: 6,
+  findingCodeCharacters: 64,
+  findingMessageCharacters: 256,
+  score: 28,
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function limit(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= fallback ? value : fallback;
+}
+
+function count(value: unknown, maximum: number): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : 0;
+}
+
+function boundedString(value: unknown, maximum: number, fallback = ""): string {
+  if (typeof value !== "string") return fallback;
+  return value.replaceAll("\0", "�").slice(0, maximum) || fallback;
+}
+
+function timestamp(value: unknown): string | null {
+  if (typeof value !== "string" || value.length > 64) return null;
+  try {
+    return new Date(value).toISOString() === value ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function scanStatus(value: unknown, errorLimit: number) {
+  if (!isRecord(value)) return { state: "idle" as const, at: null, error: null };
+  const state = value.state === "running" || value.state === "completed" || value.state === "failed" || value.state === "cancelled" ? value.state : "idle";
+  const at = timestamp(value.at);
+  if ((state === "completed" || state === "failed" || state === "cancelled") && at === null) return { state: "idle" as const, at: null, error: null };
+  const error = state === "failed" || state === "cancelled" ? boundedString(value.error, errorLimit) || null : null;
+  return { state, at, error };
+}
+
+export function skillGuardPanelView(data: unknown) {
+  const source = isRecord(data) ? data : {};
+  const rawLimits = isRecord(source.limits) ? source.limits : {};
+  const limits = Object.fromEntries(Object.entries(defaults).map(([key, fallback]) => [key, limit(rawLimits[key], fallback)])) as unknown as typeof defaults;
+  const reports = (Array.isArray(source.reports) ? source.reports : []).slice(0, limits.panelReports).map((value) => {
+    const report = isRecord(value) ? value : {};
+    const risk = report.risk === "safe" || report.risk === "review" || report.risk === "blocked" ? report.risk : "review";
+    const findings = (Array.isArray(report.findings) ? report.findings : []).slice(0, limits.findingsPerSkill).map((value) => {
+      const finding = isRecord(value) ? value : {};
+      return {
+        code: boundedString(finding.code, limits.findingCodeCharacters, "finding"),
+        severity: finding.severity === "high" ? ("high" as const) : ("medium" as const),
+        message: boundedString(finding.message, limits.findingMessageCharacters),
+      };
+    });
+    return {
+      name: boundedString(report.name, limits.nameCharacters, "unknown"),
+      risk,
+      score: count(report.score, limits.score),
+      findings,
+      path: boundedString(report.path, limits.pathCharacters),
+      source: boundedString(report.source, limits.sourceCharacters, "unknown"),
+      scannedBytes: count(report.scannedBytes, limits.skillBytes),
+    };
+  });
+  const rawInventory = isRecord(source.inventory) ? source.inventory : {};
+  return {
+    scans: count(source.scans, Number.MAX_SAFE_INTEGER),
+    total: count(source.total, limits.skills),
+    blocked: count(source.blocked, limits.skills),
+    review: count(source.review, limits.skills),
+    reports,
+    status: scanStatus(source.status, limits.statusErrorCharacters),
+    inventory: {
+      available: count(rawInventory.available, Number.MAX_SAFE_INTEGER),
+      scanned: count(rawInventory.scanned, limits.skills),
+      shown: count(rawInventory.shown, limits.panelReports),
+      truncated: rawInventory.truncated === true,
+      scanTruncated: rawInventory.scanTruncated === true,
+      displayTruncated: rawInventory.displayTruncated === true,
+    },
+    limits,
+  };
+}