@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/client-web/src/i18n-pair-view.ts

@@ -0,0 +1,194 @@
+export type I18nPairStatusState = "idle" | "running" | "completed" | "failed" | "cancelled" | "unknown";
+
+export interface I18nPairPanelView {
+  readonly status: { readonly state: I18nPairStatusState; readonly at: string | null; readonly error: string | null };
+  readonly report: {
+    readonly base: string;
+    readonly target: string;
+    readonly baseKeys: number;
+    readonly targetKeys: number;
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+    readonly missingTotal: number;
+    readonly extraTotal: number;
+    readonly truncated: boolean;
+  } | null;
+  readonly malformed: boolean;
+  readonly limits: typeof defaults;
+}
+
+const visibleKeysPerSide = 50;
+const maxStatusErrorCharacters = 2_000;
+const visibleStatusErrorCharacters = 500;
+const defaults = {
+  fileBytes: 4_194_304,
+  depth: 128,
+  keysPerFile: 50_000,
+  flattenedKeyLength: 2_048,
+  pathLength: 4_096,
+  panelKeysPerSide: 100,
+} as const;
+const rootKeys = new Set(["status", "report", "limits"]);
+const statusKeys = new Set(["state", "at", "error"]);
+const reportKeys = new Set(["base", "target", "baseKeys", "targetKeys", "missing", "extra", "missingTotal", "extraTotal", "truncated"]);
+const limitKeys = new Set(Object.keys(defaults));
+const unsafeUnicode = /[\p{Cc}\p{Cf}\p{Cs}]/u;
+
+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 hasExactly(source: Record<string, unknown>, keys: ReadonlySet<string>): boolean {
+  const own = Object.keys(source);
+  return own.length === keys.size && own.every((key) => keys.has(key));
+}
+
+function safeInteger(value: unknown, maximum: number): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : undefined;
+}
+
+function safeText(value: unknown, maximum: number, allowEmpty = false): string | undefined {
+  if (typeof value !== "string" || (!allowEmpty && value.length === 0) || value !== value.trim() || unsafeUnicode.test(value)) return undefined;
+  if ([...value].length > maximum || new TextEncoder().encode(value).byteLength > maximum) return undefined;
+  return value;
+}
+
+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 stringArray(value: unknown): string[] | undefined {
+  try {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) return undefined;
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    const length: unknown = lengthDescriptor !== undefined && "value" in lengthDescriptor ? lengthDescriptor.value : undefined;
+    if (!Number.isSafeInteger(length) || (length as number) < 0 || (length as number) > defaults.panelKeysPerSide) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (
+      Reflect.ownKeys(descriptors).some((key) => key !== "length" && (typeof key !== "string" || !/^\d+$/u.test(key))) ||
+      Object.values(descriptors).some((descriptor) => !("value" in descriptor))
+    )
+      return undefined;
+    const output: string[] = [];
+    for (let index = 0; index < (length as number); index += 1) {
+      const descriptor = descriptors[String(index)];
+      const item: unknown = descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+      const text = safeText(item, defaults.flattenedKeyLength, true);
+      if (text === undefined) return undefined;
+      output.push(text);
+    }
+    return output;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusView(value: unknown): I18nPairPanelView["status"] | undefined {
+  const source = ownDataRecord(value, statusKeys);
+  if (source === undefined) return undefined;
+  if (source.state === "idle" && hasExactly(source, new Set(["state"]))) return { state: "idle", at: null, error: null };
+  if (source.state === "running" && hasExactly(source, new Set(["state"]))) return { state: "running", at: null, error: null };
+  const at = timestamp(source.at);
+  if (source.state === "completed" && at !== undefined && hasExactly(source, new Set(["state", "at"]))) return { state: "completed", at, error: null };
+  if ((source.state === "failed" || source.state === "cancelled") && at !== undefined && hasExactly(source, statusKeys)) {
+    const error = safeText(source.error, maxStatusErrorCharacters);
+    if (error !== undefined) return { state: source.state, at, error: [...error].slice(0, visibleStatusErrorCharacters).join("") };
+  }
+  return undefined;
+}
+
+function reportView(value: unknown): I18nPairPanelView["report"] | undefined {
+  const source = ownDataRecord(value, reportKeys);
+  if (source === undefined || !hasExactly(source, reportKeys)) return undefined;
+  const base = safeText(source.base, defaults.pathLength);
+  const target = safeText(source.target, defaults.pathLength);
+  const baseKeys = safeInteger(source.baseKeys, defaults.keysPerFile);
+  const targetKeys = safeInteger(source.targetKeys, defaults.keysPerFile);
+  const missing = stringArray(source.missing);
+  const extra = stringArray(source.extra);
+  const missingTotal = safeInteger(source.missingTotal, defaults.keysPerFile);
+  const extraTotal = safeInteger(source.extraTotal, defaults.keysPerFile);
+  if (
+    base === undefined ||
+    target === undefined ||
+    baseKeys === undefined ||
+    targetKeys === undefined ||
+    missing === undefined ||
+    extra === undefined ||
+    missingTotal === undefined ||
+    extraTotal === undefined ||
+    typeof source.truncated !== "boolean"
+  )
+    return undefined;
+  const expectedMissingLength = Math.min(missingTotal, defaults.panelKeysPerSide);
+  const expectedExtraLength = Math.min(extraTotal, defaults.panelKeysPerSide);
+  const expectedTruncated = expectedMissingLength < missingTotal || expectedExtraLength < extraTotal;
+  if (
+    missing.length !== expectedMissingLength ||
+    extra.length !== expectedExtraLength ||
+    source.truncated !== expectedTruncated ||
+    missingTotal > baseKeys ||
+    extraTotal > targetKeys ||
+    baseKeys - missingTotal !== targetKeys - extraTotal ||
+    new Set(missing).size !== missing.length ||
+    new Set(extra).size !== extra.length ||
+    missing.some((key) => extra.includes(key))
+  )
+    return undefined;
+  return {
+    base,
+    target,
+    baseKeys,
+    targetKeys,
+    missing: missing.slice(0, visibleKeysPerSide),
+    extra: extra.slice(0, visibleKeysPerSide),
+    missingTotal,
+    extraTotal,
+    truncated: expectedTruncated || missing.length > visibleKeysPerSide || extra.length > visibleKeysPerSide,
+  };
+}
+
+function validLimits(value: unknown): boolean {
+  const source = ownDataRecord(value, limitKeys);
+  return source !== undefined && hasExactly(source, limitKeys) && Object.entries(defaults).every(([key, expected]) => source[key] === expected);
+}
+
+function malformedView(): I18nPairPanelView {
+  return {
+    status: { state: "unknown", at: null, error: null },
+    report: null,
+    malformed: true,
+    limits: { ...defaults },
+  };
+}
+
+export function i18nPairPanelView(data: unknown): I18nPairPanelView {
+  const source = ownDataRecord(data, rootKeys);
+  if (source === undefined || !hasExactly(source, rootKeys) || !validLimits(source.limits)) return malformedView();
+  const status = statusView(source.status);
+  if (status === undefined) return malformedView();
+  const report = source.report === null ? null : reportView(source.report);
+  if (report === undefined || (status.state === "idle" && report !== null) || (status.state === "completed" && report === null)) return malformedView();
+  return { status, report, malformed: false, limits: { ...defaults } };
+}

package/packages/client-web/src/mcp-client-view.ts

@@ -0,0 +1,122 @@
+const visibleTools = 12;
+const visibleResources = 8;
+const visiblePrompts = 8;
+const visibleServers = 12;
+const defaults = {
+  responseBytes: 1_048_576,
+  commandArgs: 32,
+  argumentBytes: 4_096,
+  toolArgumentsBytes: 65_536,
+  toolArgumentDepth: 32,
+  requestTimeoutMs: 30_000,
+  panelItems: 20,
+  inventoryItems: 1_000,
+  paginationPages: 100,
+  stderrBytes: 8_192,
+  managedServers: 128,
+} as const;
+const serverStatuses = new Set(["running", "stopping", "stopped"]);
+
+function positive(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
+}
+
+function count(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= fallback ? Math.trunc(value) : fallback;
+}
+
+function string(value: unknown, maximum: number): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value.slice(0, maximum) : undefined;
+}
+
+function tool(value: unknown) {
+  const record = ownRecord(value);
+  if (record === undefined) return undefined;
+  const name = string(record.name, 512);
+  if (name === undefined) return undefined;
+  const description = string(record.description, 500);
+  return { name, ...(description === undefined ? {} : { description }) };
+}
+
+function resource(value: unknown) {
+  const record = ownRecord(value);
+  if (record === undefined) return undefined;
+  const uri = string(record.uri, 4_096);
+  if (uri === undefined) return undefined;
+  const name = string(record.name, 512);
+  const mimeType = string(record.mimeType, 256);
+  return { uri, ...(name === undefined ? {} : { name }), ...(mimeType === undefined ? {} : { mimeType }) };
+}
+
+function prompt(value: unknown) {
+  const record = ownRecord(value);
+  if (record === undefined) return undefined;
+  const name = string(record.name, 512);
+  if (name === undefined) return undefined;
+  const description = string(record.description, 500);
+  return { name, ...(description === undefined ? {} : { description }) };
+}
+
+function server(value: unknown) {
+  const record = ownRecord(value);
+  if (record === undefined) return undefined;
+  const id = string(record.id, 64);
+  if (id === undefined) return undefined;
+  const status = typeof record.status === "string" && serverStatuses.has(record.status) ? record.status : "unknown";
+  const startedAt = typeof record.startedAt === "number" && Number.isFinite(record.startedAt) && record.startedAt >= 0 ? Math.trunc(record.startedAt) : 0;
+  return { id, status, startedAt };
+}
+
+function items<T>(raw: unknown, visible: number, normalize: (value: unknown) => T | undefined): { values: T[]; clipped: boolean; rawLength: number } {
+  const source = ownArray(raw, visible + 2) ?? [];
+  const inspected = source;
+  const values = inspected
+    .map(normalize)
+    .filter((value): value is T => value !== undefined)
+    .slice(0, visible);
+  return { values, clipped: source.length > visible || source.length !== values.length, rawLength: source.length };
+}
+
+function inventory(raw: unknown, shown: number, clipped: boolean) {
+  const source = ownRecord(raw) ?? {};
+  const total = count(source.total, shown);
+  return { total, shown, truncated: source.truncated === true || clipped || total > shown };
+}
+
+export function mcpClientPanelView(data: unknown) {
+  const source = ownRecord(data) ?? {};
+  const normalizedTools = items(source.tools, visibleTools, tool);
+  const normalizedResources = items(source.resources, visibleResources, resource);
+  const normalizedPrompts = items(source.prompts, visiblePrompts, prompt);
+  const normalizedServers = items(source.servers, visibleServers, server);
+  const rawInventory = ownRecord(source.inventory) ?? {};
+  const rawLimits = ownRecord(source.limits) ?? {};
+  return {
+    server: source.server === null ? null : (string(source.server, 4_096) ?? null),
+    tools: normalizedTools.values,
+    resources: normalizedResources.values,
+    prompts: normalizedPrompts.values,
+    lastCall: source.lastCall === null ? null : (string(source.lastCall, 512) ?? null),
+    servers: normalizedServers.values,
+    inventory: {
+      tools: inventory(rawInventory.tools, normalizedTools.values.length, normalizedTools.clipped),
+      resources: inventory(rawInventory.resources, normalizedResources.values.length, normalizedResources.clipped),
+      prompts: inventory(rawInventory.prompts, normalizedPrompts.values.length, normalizedPrompts.clipped),
+      servers: inventory(rawInventory.servers, normalizedServers.values.length, normalizedServers.clipped),
+    },
+    limits: {
+      responseBytes: positive(rawLimits.responseBytes, defaults.responseBytes),
+      commandArgs: positive(rawLimits.commandArgs, defaults.commandArgs),
+      argumentBytes: positive(rawLimits.argumentBytes, defaults.argumentBytes),
+      toolArgumentsBytes: positive(rawLimits.toolArgumentsBytes, defaults.toolArgumentsBytes),
+      toolArgumentDepth: positive(rawLimits.toolArgumentDepth, defaults.toolArgumentDepth),
+      requestTimeoutMs: positive(rawLimits.requestTimeoutMs, defaults.requestTimeoutMs),
+      panelItems: positive(rawLimits.panelItems, defaults.panelItems),
+      inventoryItems: positive(rawLimits.inventoryItems, defaults.inventoryItems),
+      paginationPages: positive(rawLimits.paginationPages, defaults.paginationPages),
+      stderrBytes: positive(rawLimits.stderrBytes, defaults.stderrBytes),
+      managedServers: positive(rawLimits.managedServers, defaults.managedServers),
+    },
+  };
+}
+import { ownArray, ownRecord } from "./panel-safe.js";

package/packages/client-web/src/modlens-view.ts

@@ -0,0 +1,210 @@
+export type ModlensModeView = "native" | "evidence";
+
+export interface ModlensImageView {
+  readonly mode: ModlensModeView;
+  readonly path: string;
+  readonly mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+  readonly bytes: number;
+  readonly cached: boolean;
+  readonly at: string;
+}
+
+export type ModlensStatusView =
+  | { readonly state: "idle" }
+  | { readonly state: "running"; readonly mode: ModlensModeView; readonly path: string; readonly at: string }
+  | ({ readonly state: "completed" } & ModlensImageView)
+  | {
+      readonly state: "failed" | "cancelled";
+      readonly mode: ModlensModeView;
+      readonly path: string;
+      readonly at: string;
+      readonly error: string;
+    };
+
+export interface ModlensPanelView {
+  readonly attached: boolean;
+  readonly image: ModlensImageView | null;
+  readonly status: ModlensStatusView;
+  readonly supportedTypes: readonly string[];
+  readonly limits: {
+    readonly imageBytes: number;
+    readonly pathCharacters: number;
+    readonly promptCharacters: number;
+    readonly evidenceBytes: number;
+    readonly agentTextBytes: number;
+    readonly timeoutMs: number;
+    readonly cacheEntries: number;
+  };
+  readonly truncated: boolean;
+}
+
+const supportedTypes = ["png", "jpeg", "jpg", "gif", "webp"] as const;
+const supportedTypeSet = new Set<string>(supportedTypes);
+const supportedMimeTypes = new Set<string>(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+const maxErrorCharacters = 2_000;
+const defaults = {
+  imageBytes: 10_485_760,
+  pathCharacters: 4_096,
+  promptCharacters: 4_000,
+  evidenceBytes: 524_288,
+  agentTextBytes: 131_072,
+  timeoutMs: 180_000,
+  cacheEntries: 64,
+};
+const minimumTimeoutMs = 1_000;
+const maximumTimeoutMs = 300_000;
+
+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 cleanedText(value: unknown, maximum: number): { value: string | undefined; altered: boolean } {
+  if (typeof value !== "string") return { value: undefined, altered: true };
+  const sample = value.slice(0, maximum * 2 + 1);
+  const cleaned = sample
+    .replaceAll(/[\p{Cc}\p{Cf}]+/gu, " ")
+    .trim()
+    .slice(0, maximum);
+  return { value: cleaned === "" ? undefined : cleaned, altered: cleaned !== value };
+}
+
+function canonicalTimestamp(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    return new Date(value).toISOString() === value ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function imageMetadata(value: unknown, extraKeys: readonly string[] = []): { image: ModlensImageView | null; altered: boolean } {
+  const source = ownDataRecord(value);
+  if (source === undefined) return { image: null, altered: value !== null };
+  const mode = source.mode === "native" || source.mode === "evidence" ? source.mode : undefined;
+  const path = cleanedText(source.path, defaults.pathCharacters);
+  const mimeType =
+    typeof source.mimeType === "string" && supportedMimeTypes.has(source.mimeType) ? (source.mimeType as ModlensImageView["mimeType"]) : undefined;
+  const bytes =
+    typeof source.bytes === "number" && Number.isSafeInteger(source.bytes) && source.bytes >= 0 && source.bytes <= defaults.imageBytes
+      ? source.bytes
+      : undefined;
+  const cached = typeof source.cached === "boolean" && !(mode === "native" && source.cached) ? source.cached : undefined;
+  const at = canonicalTimestamp(source.at);
+  const expectedKeys = new Set(["mode", "path", "mimeType", "bytes", "cached", "at", ...extraKeys]);
+  const altered = path.altered || Object.keys(source).some((key) => !expectedKeys.has(key));
+  if (mode === undefined || path.value === undefined || mimeType === undefined || bytes === undefined || cached === undefined || at === undefined)
+    return { image: null, altered: true };
+  return { image: { mode, path: path.value, mimeType, bytes, cached, at }, altered };
+}
+
+function statusView(value: unknown): { status: ModlensStatusView; altered: boolean } {
+  const source = ownDataRecord(value);
+  if (source === undefined) return { status: { state: "idle" }, altered: true };
+  if (source.state === "idle") return { status: { state: "idle" }, altered: Object.keys(source).some((key) => key !== "state") };
+  if (source.state === "completed") {
+    const parsed = imageMetadata(source, ["state"]);
+    return parsed.image === null ? { status: { state: "idle" }, altered: true } : { status: { state: "completed", ...parsed.image }, altered: parsed.altered };
+  }
+  if (source.state !== "running" && source.state !== "failed" && source.state !== "cancelled") return { status: { state: "idle" }, altered: true };
+  const mode = source.mode === "native" || source.mode === "evidence" ? source.mode : undefined;
+  const path = cleanedText(source.path, defaults.pathCharacters);
+  const at = canonicalTimestamp(source.at);
+  if (mode === undefined || path.value === undefined || at === undefined) return { status: { state: "idle" }, altered: true };
+  if (source.state === "running") {
+    const altered = path.altered || Object.keys(source).some((key) => !new Set(["state", "mode", "path", "at"]).has(key));
+    return { status: { state: "running", mode, path: path.value, at }, altered };
+  }
+  const error = cleanedText(source.error, maxErrorCharacters);
+  if (error.value === undefined) return { status: { state: "idle" }, altered: true };
+  const altered = path.altered || error.altered || Object.keys(source).some((key) => !new Set(["state", "mode", "path", "at", "error"]).has(key));
+  return { status: { state: source.state, mode, path: path.value, at, error: error.value }, altered };
+}
+
+function exactSupportedTypes(value: unknown): boolean {
+  try {
+    if (!Array.isArray(value)) return false;
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    if (lengthDescriptor === undefined || !("value" in lengthDescriptor) || lengthDescriptor.value !== supportedTypes.length) return false;
+    const seen = new Set<string>();
+    for (let index = 0; index < supportedTypes.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (descriptor === undefined || !("value" in descriptor) || typeof descriptor.value !== "string" || !supportedTypeSet.has(descriptor.value)) return false;
+      seen.add(descriptor.value);
+    }
+    return seen.size === supportedTypes.length;
+  } catch {
+    return false;
+  }
+}
+
+export function modlensPanelView(data: unknown): ModlensPanelView {
+  const source = ownDataRecord(data);
+  if (source === undefined) {
+    return {
+      attached: false,
+      image: null,
+      status: { state: "idle" },
+      supportedTypes: [...supportedTypes],
+      limits: { ...defaults },
+      truncated: true,
+    };
+  }
+  const parsedImage = imageMetadata(source.image);
+  const parsedStatus = statusView(source.status);
+  const completedStatusMatchesImage =
+    parsedStatus.status.state !== "completed" ||
+    (parsedImage.image !== null &&
+      parsedStatus.status.mode === parsedImage.image.mode &&
+      parsedStatus.status.path === parsedImage.image.path &&
+      parsedStatus.status.mimeType === parsedImage.image.mimeType &&
+      parsedStatus.status.bytes === parsedImage.image.bytes &&
+      parsedStatus.status.cached === parsedImage.image.cached &&
+      parsedStatus.status.at === parsedImage.image.at);
+  const rawLimits = ownDataRecord(source.limits);
+  const timeoutMs =
+    rawLimits !== undefined &&
+    typeof rawLimits.timeoutMs === "number" &&
+    Number.isSafeInteger(rawLimits.timeoutMs) &&
+    rawLimits.timeoutMs >= minimumTimeoutMs &&
+    rawLimits.timeoutMs <= maximumTimeoutMs
+      ? rawLimits.timeoutMs
+      : defaults.timeoutMs;
+  const fixedLimitKeys = ["imageBytes", "pathCharacters", "promptCharacters", "evidenceBytes", "agentTextBytes", "cacheEntries"] as const;
+  const limitsAltered =
+    rawLimits === undefined ||
+    fixedLimitKeys.some((key) => rawLimits[key] !== defaults[key]) ||
+    Object.keys(rawLimits).some((key) => ![...fixedLimitKeys, "timeoutMs"].includes(key)) ||
+    timeoutMs !== rawLimits.timeoutMs;
+  const attached = parsedImage.image !== null;
+  const expectedRootKeys = new Set(["attached", "image", "status", "supportedTypes", "limits"]);
+  const truncated =
+    parsedImage.altered ||
+    parsedStatus.altered ||
+    !completedStatusMatchesImage ||
+    limitsAltered ||
+    !exactSupportedTypes(source.supportedTypes) ||
+    source.attached !== attached ||
+    Object.keys(source).some((key) => !expectedRootKeys.has(key));
+  return {
+    attached,
+    image: parsedImage.image,
+    status: parsedStatus.status,
+    supportedTypes: [...supportedTypes],
+    limits: { ...defaults, timeoutMs },
+    truncated,
+  };
+}

package/packages/client-web/src/openpets-view.ts

@@ -0,0 +1,67 @@
+import { ownRecord } from "./panel-safe.js";
+
+export type OpenPetsMood = "idle" | "focused" | "happy" | "concerned";
+
+const defaults = { nameCharacters: 128, recoveryEntries: 10_000, persistenceErrorCharacters: 2_000 } as const;
+const moods = new Set<OpenPetsMood>(["idle", "focused", "happy", "concerned"]);
+const events = new Set(["session_start", "agent_start", "agent_end", "tool_execution_end", "feed", "play", "set_mood"]);
+
+function limit(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= fallback ? value : fallback;
+}
+
+function nonNegativeInteger(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? 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;
+  }
+}
+
+export function openPetsPanelView(data: unknown) {
+  const source = ownRecord(data) ?? {};
+  const rawLimits = ownRecord(source.limits) ?? {};
+  const limits = {
+    nameCharacters: limit(rawLimits.nameCharacters, defaults.nameCharacters),
+    recoveryEntries: limit(rawLimits.recoveryEntries, defaults.recoveryEntries),
+    persistenceErrorCharacters: limit(rawLimits.persistenceErrorCharacters, defaults.persistenceErrorCharacters),
+  };
+  const rawRecovery = ownRecord(source.recovery) ?? {};
+  const sessionEntries = nonNegativeInteger(rawRecovery.sessionEntries);
+  const scanned = Math.min(sessionEntries, limits.recoveryEntries, nonNegativeInteger(rawRecovery.scanned));
+  const rawPersistence = ownRecord(source.persistence) ?? {};
+  const attempts = nonNegativeInteger(rawPersistence.attempts);
+  const name = boundedString(source.name, limits.nameCharacters);
+  const mood = typeof source.mood === "string" && moods.has(source.mood as OpenPetsMood) ? (source.mood as OpenPetsMood) : "idle";
+  const lastEvent = typeof source.lastEvent === "string" && events.has(source.lastEvent) ? source.lastEvent : "session_start";
+  const energy = typeof source.energy === "number" && Number.isSafeInteger(source.energy) && source.energy >= 0 && source.energy <= 100 ? source.energy : 80;
+  return {
+    name: name || "Pi",
+    mood,
+    energy,
+    interactions: nonNegativeInteger(source.interactions),
+    lastEvent,
+    updatedAt: timestamp(source.updatedAt),
+    recovery: {
+      sessionEntries,
+      scanned,
+      truncated: rawRecovery.truncated === true || sessionEntries > scanned,
+      restored: rawRecovery.restored === true,
+    },
+    persistence: {
+      attempts,
+      failures: Math.min(attempts, nonNegativeInteger(rawPersistence.failures)),
+      lastError: boundedString(rawPersistence.lastError, limits.persistenceErrorCharacters) || null,
+    },
+    limits,
+  };
+}

package/packages/client-web/src/panel-safe.ts

@@ -0,0 +1,47 @@
+/** Read only own data properties from an untrusted panel payload. */
+export function ownRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value) as Record<string, PropertyDescriptor | undefined>;
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string")) return undefined;
+    const result = Object.create(null) as Record<string, unknown>;
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (descriptor === undefined || !("value" in descriptor)) return undefined;
+      result[key] = descriptorValue(descriptor);
+    }
+    return result;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Return a bounded dense array containing only own data properties. */
+export function ownArray(value: unknown, maximum = Number.MAX_SAFE_INTEGER): unknown[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Array.prototype && prototype !== null) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value) as Record<string, PropertyDescriptor | undefined>;
+    const lengthDescriptor = descriptors.length;
+    const lengthValue = descriptorValue(lengthDescriptor);
+    if (typeof lengthValue !== "number" || !Number.isSafeInteger(lengthValue) || lengthValue < 0) return undefined;
+    const length = lengthValue;
+    if (length > maximum) return Array.from({ length: maximum }, (_, index) => descriptorValue(descriptors[String(index)]));
+    if (Reflect.ownKeys(descriptors).some((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/u.test(key)))) return undefined;
+    const result: unknown[] = [];
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = descriptors[String(index)];
+      if (descriptor === undefined || !("value" in descriptor)) return undefined;
+      result.push(descriptorValue(descriptor));
+    }
+    return result;
+  } catch {
+    return undefined;
+  }
+}
+
+function descriptorValue(descriptor: PropertyDescriptor | undefined): unknown {
+  return descriptor !== undefined && "value" in descriptor ? (descriptor.value as unknown) : undefined;
+}