@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/client-web/src/context-doctor-view.ts

@@ -0,0 +1,140 @@
+const defaults = {
+  scannedMessages: 10_000,
+  jsonDepth: 64,
+  jsonNodesPerMessage: 10_000,
+  jsonNodesPerAudit: 100_000,
+  errorCharacters: 2_000,
+  recommendationCharacters: 500,
+  displayRecommendations: 4,
+  warnPercent: 75,
+  maxMessageBytes: 64 * 1024,
+  messageCount: 4_294_967_295,
+} as const;
+
+function dataProperty(value: unknown, key: PropertyKey): unknown {
+  if (value === null || typeof value !== "object") return undefined;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+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 nullableCount(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function boundedText(value: unknown, maximum: number): string {
+  return typeof value === "string" ? value.slice(0, maximum).replaceAll("\0", "�") : "";
+}
+
+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 arrayLength(value: readonly unknown[]): number {
+  const length = dataProperty(value, "length");
+  return typeof length === "number" && Number.isSafeInteger(length) && length >= 0 ? length : 0;
+}
+
+type CompactionStatus = "idle" | "queued" | "running" | "completed" | "failed" | "cancelled" | "unknown";
+
+function compactionView(value: unknown, errorCharacters: number) {
+  const rawStatus = dataProperty(value, "status");
+  const status: CompactionStatus =
+    rawStatus === "idle" ||
+    rawStatus === "queued" ||
+    rawStatus === "running" ||
+    rawStatus === "completed" ||
+    rawStatus === "failed" ||
+    rawStatus === "cancelled"
+      ? rawStatus
+      : "unknown";
+  const error = status === "failed" || status === "cancelled" ? boundedText(dataProperty(value, "error"), errorCharacters) || null : null;
+  return {
+    status,
+    error,
+    requestedAt: timestamp(dataProperty(value, "requestedAt")),
+    startedAt: timestamp(dataProperty(value, "startedAt")),
+    finishedAt: timestamp(dataProperty(value, "finishedAt")),
+  };
+}
+
+export function contextDoctorPanelView(data: unknown) {
+  const rawLimits = dataProperty(data, "limits");
+  const limits = {
+    scannedMessages: limit(dataProperty(rawLimits, "scannedMessages"), defaults.scannedMessages),
+    jsonDepth: limit(dataProperty(rawLimits, "jsonDepth"), defaults.jsonDepth),
+    jsonNodesPerMessage: limit(dataProperty(rawLimits, "jsonNodesPerMessage"), defaults.jsonNodesPerMessage),
+    jsonNodesPerAudit: limit(dataProperty(rawLimits, "jsonNodesPerAudit"), defaults.jsonNodesPerAudit),
+    errorCharacters: limit(dataProperty(rawLimits, "errorCharacters"), defaults.errorCharacters),
+    recommendationCharacters: defaults.recommendationCharacters,
+    displayRecommendations: defaults.displayRecommendations,
+  };
+  const rawStatus = dataProperty(data, "status");
+  const status = rawStatus === "ok" || rawStatus === "warning" ? rawStatus : "unknown";
+  const rawUsagePercent = dataProperty(data, "usagePercent");
+  const usagePercent = typeof rawUsagePercent === "number" && Number.isFinite(rawUsagePercent) && rawUsagePercent >= 0 ? rawUsagePercent : null;
+  const messageCount = count(dataProperty(data, "messageCount"), defaults.messageCount);
+  const scannedMessages = count(dataProperty(data, "scannedMessages"), Math.min(messageCount, limits.scannedMessages));
+  const oversizedMessages = count(dataProperty(data, "oversizedMessages"), scannedMessages);
+  const uninspectableMessages = count(dataProperty(data, "uninspectableMessages"), oversizedMessages);
+  const toolErrors = count(dataProperty(data, "toolErrors"), scannedMessages);
+  const rawWarnPercent = dataProperty(data, "warnPercent");
+  const warnPercent =
+    typeof rawWarnPercent === "number" && Number.isFinite(rawWarnPercent) && rawWarnPercent >= 1 && rawWarnPercent <= 100
+      ? rawWarnPercent
+      : defaults.warnPercent;
+  const maxMessageBytes = limit(dataProperty(data, "maxMessageBytes"), 1024 * 1024);
+  const normalizedMaxMessageBytes =
+    maxMessageBytes === 1024 * 1024 && dataProperty(data, "maxMessageBytes") !== 1024 * 1024 ? defaults.maxMessageBytes : maxMessageBytes;
+
+  const rawRecommendations = dataProperty(data, "recommendations");
+  const recommendations: string[] = [];
+  let recommendationsTruncated = false;
+  if (Array.isArray(rawRecommendations)) {
+    const length = arrayLength(rawRecommendations);
+    for (let index = 0; index < Math.min(length, limits.displayRecommendations); index += 1) {
+      const recommendation = boundedText(dataProperty(rawRecommendations, String(index)), limits.recommendationCharacters);
+      if (recommendation === "") {
+        recommendationsTruncated = true;
+        continue;
+      }
+      recommendations.push(recommendation);
+    }
+    recommendationsTruncated ||= length > recommendations.length;
+  }
+
+  return {
+    status,
+    usagePercent,
+    tokens: nullableCount(dataProperty(data, "tokens")),
+    contextWindow: nullableCount(dataProperty(data, "contextWindow")),
+    messageCount,
+    scannedMessages,
+    messagesTruncated: dataProperty(data, "messagesTruncated") === true || messageCount > scannedMessages,
+    oversizedMessages,
+    uninspectableMessages,
+    toolErrors,
+    warnPercent,
+    maxMessageBytes: normalizedMaxMessageBytes,
+    recommendations,
+    recommendationsTruncated,
+    compaction: compactionView(dataProperty(data, "compaction"), limits.errorCharacters),
+    limits,
+  };
+}

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

@@ -0,0 +1,125 @@
+export interface ContextInsightsEventView {
+  readonly type: string;
+  readonly at: number | null;
+}
+
+export interface ContextInsightsPanelView {
+  readonly tokens: number | null;
+  readonly contextWindow: number | null;
+  readonly percent: number | null;
+  readonly messages: number;
+  readonly scannedMessages: number;
+  readonly messagesTruncated: boolean;
+  readonly events: number;
+  readonly compactions: number;
+  readonly composition: {
+    readonly user: number;
+    readonly assistant: number;
+    readonly toolResult: number;
+    readonly system: number;
+    readonly other: number;
+  };
+  readonly recentEvents: readonly ContextInsightsEventView[];
+  readonly recentEventsTruncated: boolean;
+  readonly limits: {
+    readonly scannedMessages: number;
+    readonly retainedEvents: number;
+    readonly displayedEvents: number;
+    readonly eventTypeCharacters: number;
+  };
+}
+
+const limits = {
+  scannedMessages: 10_000,
+  retainedEvents: 50,
+  displayedEvents: 6,
+  eventTypeCharacters: 128,
+} as const;
+const maxReportedCount = 4_294_967_295;
+const maxDateMilliseconds = 8_640_000_000_000_000;
+
+function dataProperty(value: unknown, key: PropertyKey): unknown {
+  if (typeof value !== "object" || value === null) return undefined;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function count(value: unknown, maximum = maxReportedCount): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : 0;
+}
+
+function nullableCount(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function percent(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function eventType(value: unknown): string {
+  if (typeof value !== "string") return "unknown";
+  const normalized = value.trim().replaceAll("\0", "�");
+  return normalized === "" ? "unknown" : normalized.slice(0, limits.eventTypeCharacters);
+}
+
+function eventTimestamp(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maxDateMilliseconds ? value : null;
+}
+
+function arrayLength(value: unknown): number {
+  if (!Array.isArray(value)) return 0;
+  return count(dataProperty(value, "length"), maxReportedCount);
+}
+
+function normalizedComposition(value: unknown, scannedMessages: number): ContextInsightsPanelView["composition"] {
+  const composition = {
+    user: count(dataProperty(value, "user"), scannedMessages),
+    assistant: count(dataProperty(value, "assistant"), scannedMessages),
+    toolResult: count(dataProperty(value, "toolResult"), scannedMessages),
+    system: count(dataProperty(value, "system"), scannedMessages),
+    other: count(dataProperty(value, "other"), scannedMessages),
+  };
+  const total = Object.values(composition).reduce((sum, item) => sum + item, 0);
+  return total === scannedMessages ? composition : { user: 0, assistant: 0, toolResult: 0, system: 0, other: scannedMessages };
+}
+
+function normalizedEvents(value: unknown): { events: ContextInsightsEventView[]; truncated: boolean } {
+  let rawLength: number;
+  try {
+    rawLength = arrayLength(value);
+  } catch {
+    return { events: [], truncated: false };
+  }
+  const retained = Math.min(rawLength, limits.retainedEvents);
+  const events: ContextInsightsEventView[] = [];
+  for (let offset = 0; offset < Math.min(retained, limits.displayedEvents); offset += 1) {
+    const index = rawLength - offset - 1;
+    const event = dataProperty(value, String(index));
+    events.push({ type: eventType(dataProperty(event, "type")), at: eventTimestamp(dataProperty(event, "at")) });
+  }
+  return { events, truncated: rawLength > events.length };
+}
+
+export function contextInsightsPanelView(data: unknown): ContextInsightsPanelView {
+  const messages = count(dataProperty(data, "messages"));
+  const scannedMessages = count(dataProperty(data, "scannedMessages"), Math.min(messages, limits.scannedMessages));
+  const recent = normalizedEvents(dataProperty(data, "recentEvents"));
+  return {
+    tokens: nullableCount(dataProperty(data, "tokens")),
+    contextWindow: nullableCount(dataProperty(data, "contextWindow")),
+    percent: percent(dataProperty(data, "percent")),
+    messages,
+    scannedMessages,
+    messagesTruncated: dataProperty(data, "messagesTruncated") === true || messages > scannedMessages,
+    events: count(dataProperty(data, "events")),
+    compactions: count(dataProperty(data, "compactions")),
+    composition: normalizedComposition(dataProperty(data, "composition"), scannedMessages),
+    recentEvents: recent.events,
+    recentEventsTruncated: recent.truncated,
+    limits,
+  };
+}

package/packages/client-web/src/cost-meter-view.ts

@@ -0,0 +1,63 @@
+export interface CostMeterHistoryItem {
+  readonly sessionId: string;
+  readonly utcDate: string;
+  readonly dailyCost: number;
+  readonly sessionCost: number;
+  readonly tokens: number;
+  readonly messages: number;
+}
+
+export interface CostMeterPanelView {
+  readonly dayBasis: "UTC";
+  readonly entryLimit: number | null;
+  readonly lastError: string | null;
+  readonly entries: readonly CostMeterHistoryItem[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNonNegative(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function historyItem(value: unknown): CostMeterHistoryItem | undefined {
+  if (!isRecord(value)) return undefined;
+  if (
+    typeof value.sessionId !== "string" ||
+    value.sessionId.trim() === "" ||
+    value.sessionId.length > 512 ||
+    !finiteNonNegative(value.cost) ||
+    !finiteNonNegative(value.sessionCost) ||
+    !Number.isSafeInteger(value.tokens) ||
+    (value.tokens as number) < 0 ||
+    !Number.isSafeInteger(value.messages) ||
+    (value.messages as number) < 0 ||
+    typeof value.recordedAt !== "string" ||
+    !Number.isFinite(Date.parse(value.recordedAt))
+  )
+    return undefined;
+  return {
+    sessionId: value.sessionId,
+    utcDate: new Date(value.recordedAt).toISOString().slice(0, 10),
+    dailyCost: value.cost,
+    sessionCost: value.sessionCost,
+    tokens: value.tokens as number,
+    messages: value.messages as number,
+  };
+}
+
+export function costMeterPanelView(data: unknown): CostMeterPanelView {
+  const source = isRecord(data) ? data : {};
+  const entryLimit =
+    Number.isSafeInteger(source.entryLimit) && (source.entryLimit as number) >= 1 && (source.entryLimit as number) <= 2_000
+      ? (source.entryLimit as number)
+      : null;
+  const lastError = typeof source.lastError === "string" && source.lastError.trim() !== "" ? source.lastError.slice(0, 2_048) : null;
+  const entries = (Array.isArray(source.entries) ? source.entries.slice(0, 20) : [])
+    .map(historyItem)
+    .filter((entry): entry is CostMeterHistoryItem => entry !== undefined)
+    .slice(0, 5);
+  return { dayBasis: "UTC", entryLimit, lastError, entries };
+}

package/packages/client-web/src/dependency-checker-view.ts

@@ -0,0 +1,215 @@
+export interface DependencyConflictView {
+  readonly name: string;
+  readonly constraints: readonly string[];
+}
+
+export interface DependencyCheckerPanelView {
+  readonly manifest: string;
+  readonly ecosystem: "npm" | "python";
+  readonly declared: number;
+  readonly installed: number;
+  readonly scanLimit: number;
+  readonly missingCount: number;
+  readonly optionalMissingCount: number;
+  readonly invalidCount: number;
+  readonly conflictCount: number;
+  readonly unresolvedCount: number;
+  readonly missing: readonly string[];
+  readonly optionalMissing: readonly string[];
+  readonly invalid: readonly string[];
+  readonly conflicts: readonly DependencyConflictView[];
+  readonly unresolved: readonly DependencyConflictView[];
+  readonly truncated: boolean;
+}
+
+const limits = {
+  declarations: 2_000,
+  manifestCharacters: 1_024,
+  itemCharacters: 256,
+  conflictConstraints: 64,
+  visibleItems: 20,
+  visibleConflicts: 6,
+  visibleConstraints: 8,
+};
+
+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 ownDataArray(value: unknown, maximum: number): { values: unknown[]; altered: boolean } | undefined {
+  try {
+    if (!Array.isArray(value)) return undefined;
+    const length = Object.getOwnPropertyDescriptor(value, "length");
+    if (length === undefined || !("value" in length) || !Number.isSafeInteger(length.value) || length.value < 0) return undefined;
+    const count = Math.min(length.value as number, maximum);
+    const values: unknown[] = [];
+    for (let index = 0; index < count; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (descriptor === undefined || !("value" in descriptor)) return undefined;
+      values.push(descriptor.value);
+    }
+    return { values, altered: length.value > maximum };
+  } catch {
+    return undefined;
+  }
+}
+
+function expectedKeys(source: Record<string, unknown>, keys: readonly string[]): boolean {
+  const expected = new Set(keys);
+  return Object.keys(source).every((key) => expected.has(key));
+}
+
+function boundedCount(value: unknown, maximum: number): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : undefined;
+}
+
+function cleanedText(value: unknown, maximum: number): { value: string | undefined; altered: boolean } {
+  if (typeof value !== "string") return { value: undefined, altered: true };
+  const sanitized = value.replaceAll(/[\p{Cc}\p{Cf}\p{Cs}]+/gu, " ").trim();
+  const codePoints = [...sanitized];
+  const cleaned = codePoints.length > maximum ? codePoints.slice(0, maximum).join("") : sanitized;
+  return { value: cleaned === "" ? undefined : cleaned, altered: cleaned !== value };
+}
+
+function textList(value: unknown): { values: string[]; altered: boolean } {
+  const parsed = ownDataArray(value, limits.declarations);
+  if (parsed === undefined) return { values: [], altered: true };
+  const values: string[] = [];
+  let altered = parsed.altered;
+  for (const item of parsed.values) {
+    const text = cleanedText(item, limits.itemCharacters);
+    altered ||= text.altered;
+    if (text.value === undefined) altered = true;
+    else values.push(text.value);
+  }
+  return { values, altered };
+}
+
+function conflictList(value: unknown): { values: DependencyConflictView[]; altered: boolean } {
+  const parsed = ownDataArray(value, limits.declarations);
+  if (parsed === undefined) return { values: [], altered: true };
+  const values: DependencyConflictView[] = [];
+  let altered = parsed.altered;
+  for (const item of parsed.values) {
+    const source = ownDataRecord(item);
+    if (source === undefined) {
+      altered = true;
+      continue;
+    }
+    const name = cleanedText(source.name, limits.itemCharacters);
+    const constraints = ownDataArray(source.constraints, limits.conflictConstraints);
+    if (name.value === undefined || constraints === undefined) {
+      altered = true;
+      continue;
+    }
+    const parsedConstraints: string[] = [];
+    altered ||= name.altered || constraints.altered || !expectedKeys(source, ["name", "constraints"]);
+    for (const constraint of constraints.values) {
+      const text = cleanedText(constraint, limits.itemCharacters);
+      altered ||= text.altered;
+      if (text.value === undefined) altered = true;
+      else parsedConstraints.push(text.value);
+    }
+    if (parsedConstraints.length === 0) {
+      altered = true;
+      continue;
+    }
+    if (parsedConstraints.length > limits.visibleConstraints) altered = true;
+    values.push({ name: name.value, constraints: parsedConstraints.slice(0, limits.visibleConstraints) });
+  }
+  return { values, altered };
+}
+
+function valuesAreUnique(values: readonly string[]): boolean {
+  return new Set(values).size === values.length;
+}
+
+export function dependencyCheckerPanelView(data: unknown): DependencyCheckerPanelView {
+  const root = ownDataRecord(data);
+  const report = root === undefined ? undefined : ownDataRecord(root.report);
+  const source = report ?? {};
+  const manifest = cleanedText(source.manifest, limits.manifestCharacters);
+  const missing = textList(source.missing);
+  const optionalMissing = textList(source.optionalMissing);
+  const invalid = textList(source.invalid);
+  const conflicts = conflictList(source.conflicts);
+  const unresolved = conflictList(source.unresolved);
+  const declared = boundedCount(source.declared, limits.declarations);
+  const installed = boundedCount(source.installed, limits.declarations);
+  const issueCount = missing.values.length + optionalMissing.values.length + invalid.values.length;
+  const recordsDistinct =
+    valuesAreUnique([...missing.values, ...optionalMissing.values]) &&
+    valuesAreUnique([...conflicts.values.map((conflict) => conflict.name), ...unresolved.values.map((conflict) => conflict.name)]);
+  let countsValid = false;
+  if (
+    declared !== undefined &&
+    installed !== undefined &&
+    installed <= declared &&
+    conflicts.values.length <= declared &&
+    unresolved.values.length <= declared
+  ) {
+    if (source.ecosystem === "npm") countsValid = installed + issueCount === declared;
+    else if (source.ecosystem === "python")
+      countsValid =
+        optionalMissing.values.length === 0 && installed + missing.values.length === declared && declared + invalid.values.length <= limits.declarations;
+  }
+  const classifiedCount = missing.values.length + optionalMissing.values.length + (source.ecosystem === "python" ? 0 : invalid.values.length);
+  const safeDeclared =
+    countsValid && declared !== undefined
+      ? declared
+      : Math.min(limits.declarations, Math.max(classifiedCount, conflicts.values.length, unresolved.values.length));
+  const safeInstalled = countsValid && installed !== undefined ? installed : 0;
+  const contractAltered =
+    root === undefined ||
+    report === undefined ||
+    !expectedKeys(root, ["report"]) ||
+    !expectedKeys(source, ["manifest", "ecosystem", "declared", "installed", "scanLimit", "missing", "optionalMissing", "invalid", "conflicts", "unresolved"]);
+  return {
+    manifest: manifest.value ?? "package.json",
+    ecosystem: source.ecosystem === "python" ? "python" : "npm",
+    declared: safeDeclared,
+    installed: safeInstalled,
+    scanLimit: limits.declarations,
+    missingCount: missing.values.length,
+    optionalMissingCount: optionalMissing.values.length,
+    invalidCount: invalid.values.length,
+    conflictCount: conflicts.values.length,
+    unresolvedCount: unresolved.values.length,
+    missing: missing.values.slice(0, limits.visibleItems),
+    optionalMissing: optionalMissing.values.slice(0, limits.visibleItems),
+    invalid: invalid.values.slice(0, limits.visibleItems),
+    conflicts: conflicts.values.slice(0, limits.visibleConflicts),
+    unresolved: unresolved.values.slice(0, limits.visibleConflicts),
+    truncated:
+      contractAltered ||
+      manifest.altered ||
+      (source.ecosystem !== "npm" && source.ecosystem !== "python") ||
+      !countsValid ||
+      source.scanLimit !== limits.declarations ||
+      !recordsDistinct ||
+      missing.altered ||
+      optionalMissing.altered ||
+      invalid.altered ||
+      conflicts.altered ||
+      unresolved.altered ||
+      missing.values.length > limits.visibleItems ||
+      optionalMissing.values.length > limits.visibleItems ||
+      invalid.values.length > limits.visibleItems ||
+      conflicts.values.length > limits.visibleConflicts ||
+      unresolved.values.length > limits.visibleConflicts,
+  };
+}