pi-watchdog-supervisor 0.1.0

package/src/index.ts

@@ -0,0 +1,94 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { loadEffectiveConfig } from './config.ts';
+import { registerWatchdogCommands } from './commands.ts';
+import { registerWatchdogTools } from './tools.ts';
+import { createTargetRegistry } from './registry.ts';
+import { getOrCreateStore } from './store.ts';
+import { startCollector, startLlmCollector } from './collector.ts';
+import { createStuckChecker } from './checker.ts';
+import { registerLmDebugWidget } from './lmdebug.ts';
+import {
+  connectSubagents,
+  SUBAGENT_EVENT_CHANNELS,
+  type SubagentsIntegration,
+} from './integrations/gotgenes-subagents.ts';
+
+// This factory runs in the parent session AND in every child session
+// (pi-subagents children always load the parent's extensions).
+export default function watchdogSupervisor(pi: ExtensionAPI) {
+  const { config, warnings } = loadEffectiveConfig(process.cwd());
+  const registry = createTargetRegistry();
+  const store = getOrCreateStore(config.maxEventsPerAgent);
+
+  // Lazy + retry: the subagents extension may publish its service after we load
+  let integration: SubagentsIntegration | undefined;
+  const getIntegration = async () => {
+    if (!integration?.available) {
+      integration = await connectSubagents();
+    }
+    return integration;
+  };
+
+  // Parent side: fires before the child's extensions bind (synchronous dispatch),
+  // so the child instance can recognize itself in session_start below.
+  pi.events.on('subagents:child:session-created', (data) => {
+    const record = typeof data === 'object' && data !== null ? (data as Record<string, unknown>) : undefined;
+    if (record && typeof record.sessionId === 'string') {
+      store.registerChild(
+        record.sessionId,
+        typeof record.parentSessionId === 'string' ? record.parentSessionId : undefined,
+      );
+    }
+  });
+
+  for (const channel of SUBAGENT_EVENT_CHANNELS) {
+    pi.events.on(channel, (data) => {
+      registry.applyEvent(channel, data, Date.now());
+      if (channel === 'subagents:started') {
+        const record = typeof data === 'object' && data !== null ? (data as Record<string, unknown>) : undefined;
+        if (record && typeof record.id === 'string') {
+          store.linkNextAgent(record.id);
+        }
+      }
+    });
+  }
+
+  registerLmDebugWidget(pi, config.debug);
+  registerWatchdogCommands(pi, { config, registry, getIntegration, store });
+  registerWatchdogTools(pi, {
+    store,
+    registry,
+    getIntegration,
+    baseConfig: config,
+    now: () => Date.now(),
+  });
+
+  pi.on('session_start', (_event, ctx) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    // Every session (main or child) collects its own tool + llm events and
+    // self-checks on every LLM round-trip (no timer), so a stuck main session
+    // rescues itself immediately even with no watchdog sub-agent around.
+    const checkStuck = createStuckChecker(pi, store, sessionId, config);
+    startCollector(pi, store, sessionId, config);
+    startLlmCollector(pi, store, sessionId, checkStuck);
+    pi.on('after_provider_response', () => checkStuck());
+    if (!store.getChild(sessionId)) {
+      // Non-child (main) side: receive alerts from watchdog tools running in
+      // child sessions. Last non-child session wins if several exist.
+      store.setAlertSink((message, severity) => {
+        pi.sendMessage(
+          { customType: 'watchdog-alert', content: message, display: true },
+          // 'steer' reaches a looping session; 'nextTurn' would wait for a
+          // user prompt that never comes while the agent is stuck
+          { deliverAs: 'steer', triggerTurn: severity === 'critical' },
+        );
+      });
+    }
+
+    if (ctx.hasUI) {
+      for (const warning of warnings) {
+        ctx.ui.notify(warning, 'warning');
+      }
+    }
+  });
+}

package/src/integrations/gotgenes-subagents.ts

@@ -0,0 +1,45 @@
+import type { SubagentRecordLike } from '../registry.ts';
+
+export type SubagentsIntegration =
+  | {
+      available: true;
+      listAgents: () => SubagentRecordLike[];
+      steer: (agentId: string, message: string) => Promise<boolean>;
+    }
+  | { available: false; reason: string };
+
+// Lifecycle channels emitted by @gotgenes/pi-subagents on pi.events
+export const SUBAGENT_EVENT_CHANNELS = [
+  'subagents:created',
+  'subagents:started',
+  'subagents:completed',
+  'subagents:failed',
+  'subagents:steered',
+  'subagents:compacted',
+] as const;
+
+type ServiceLike = {
+  listAgents: () => SubagentRecordLike[];
+  steer: (agentId: string, message: string) => Promise<boolean>;
+};
+
+export const connectSubagents = async (): Promise<SubagentsIntegration> => {
+  let getService: (() => ServiceLike | undefined) | undefined;
+  try {
+    const mod = (await import('@gotgenes/pi-subagents')) as {
+      getSubagentsService?: () => ServiceLike | undefined;
+    };
+    getService = mod.getSubagentsService;
+  } catch {
+    return { available: false, reason: '@gotgenes/pi-subagents is not installed' };
+  }
+  const service = getService?.();
+  if (!service) {
+    return { available: false, reason: 'subagents service not published (extension not loaded?)' };
+  }
+  return {
+    available: true,
+    listAgents: () => service.listAgents(),
+    steer: (agentId, message) => service.steer(agentId, message),
+  };
+};

package/src/lmdebug.ts

@@ -0,0 +1,128 @@
+// Debug console at the bottom of the pi TUI: shows the latest request sent to
+// the LLM provider (LM Studio) and the latest assistant message received,
+// each with a timestamp and the full message body (newlines preserved, no
+// truncation). Enabled via the `debug` config flag (default false).
+const WIDGET_KEY = 'watchdog-lm-debug';
+
+// Minimal surface used here; satisfied by ExtensionAPI and test fakes
+type PiLike = {
+  on(
+    event: 'before_provider_request',
+    handler: (event: { payload: unknown }, ctx: UiCtxLike) => void,
+  ): void;
+  on(
+    event: 'message_end',
+    handler: (event: { message: unknown }, ctx: UiCtxLike) => void,
+  ): void;
+};
+
+type UiCtxLike = {
+  hasUI: boolean;
+  ui: {
+    setWidget(
+      key: string,
+      content: string[] | undefined,
+      options?: { placement?: 'aboveEditor' | 'belowEditor' },
+    ): void;
+  };
+};
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+// Text from OpenAI-style content: plain string or [{type:'text',text}] parts
+const extractPartsText = (content: unknown): string => {
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return '';
+  }
+  return content
+    .map((part) => {
+      const record = asRecord(part);
+      return typeof record?.text === 'string' ? record.text : '';
+    })
+    .filter((text) => text !== '')
+    .join('\n');
+};
+
+export const describeSentPayload = (payload: unknown): string => {
+  const record = asRecord(payload);
+  const messages = Array.isArray(record?.messages) ? (record.messages as unknown[]) : [];
+  const last = asRecord(messages[messages.length - 1]);
+  if (!last) {
+    return 'no messages in payload';
+  }
+  const role = typeof last.role === 'string' ? last.role : 'unknown';
+  const text = extractPartsText(last.content);
+  // newline before the body so the message starts on its own line
+  return `#${messages.length} ${role}:\n${text || '(no text)'}`;
+};
+
+// Assistant messages only; other roles return undefined
+export const describeAssistantMessage = (message: unknown): string | undefined => {
+  const record = asRecord(message);
+  if (record?.role !== 'assistant' || !Array.isArray(record.content)) {
+    return undefined;
+  }
+  const parts: string[] = [];
+  for (const block of record.content) {
+    const blockRecord = asRecord(block);
+    if (!blockRecord) {
+      continue;
+    }
+    if (blockRecord.type === 'text' && typeof blockRecord.text === 'string') {
+      parts.push(blockRecord.text);
+    } else if (blockRecord.type === 'toolCall') {
+      const name = typeof blockRecord.name === 'string' ? blockRecord.name : 'tool';
+      parts.push(`[toolCall ${name}]`);
+    }
+  }
+  // newline before the body so the message starts on its own line
+  return `assistant:\n${parts.join('\n') || '(no text)'}`;
+};
+
+const formatTime = (now: number): string => {
+  const date = new Date(now);
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+};
+
+export const registerLmDebugWidget = (
+  pi: PiLike,
+  debug: boolean,
+  now: () => number = Date.now,
+): void => {
+  if (!debug) {
+    return;
+  }
+
+  let sentLines: string[] = [];
+  let receivedLines: string[] = [];
+
+  const render = (ctx: UiCtxLike) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+    // blank line between the sent block and the recv block
+    const separator = sentLines.length > 0 && receivedLines.length > 0 ? [''] : [];
+    ctx.ui.setWidget(WIDGET_KEY, [...sentLines, ...separator, ...receivedLines], {
+      placement: 'belowEditor',
+    });
+  };
+
+  pi.on('before_provider_request', (event, ctx) => {
+    sentLines = `▲ sent ${formatTime(now())} ${describeSentPayload(event.payload)}`.split('\n');
+    render(ctx);
+  });
+
+  pi.on('message_end', (event, ctx) => {
+    const description = describeAssistantMessage(event.message);
+    if (!description) {
+      return;
+    }
+    receivedLines = `▼ recv ${formatTime(now())} ${description}`.split('\n');
+    render(ctx);
+  });
+};

package/src/normalize.ts

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+
+const ANSI_PATTERN = /\u001b\[[0-9;]*[A-Za-z]/g;
+
+const stripAnsi = (raw: string): string => raw.replace(ANSI_PATTERN, '');
+
+export const normalizeCommand = (raw: string): string =>
+  stripAnsi(raw).trim().replace(/\s+/g, ' ');
+
+// Normalize an LLM message body for repetition comparison: strip volatile
+// parts (timestamps, dates, UUIDs, long hex ids, digit runs) so two loop
+// iterations that differ only in time/sequence markers hash identically.
+export const normalizeLlmBody = (raw: string): string =>
+  stripAnsi(raw)
+    .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, '<ts>')
+    .replace(/\d{4}[-/]\d{1,2}[-/]\d{1,2}/g, '<date>')
+    .replace(/\b\d{1,2}:\d{2}(?::\d{2})?(?:\s?[AP]M)?\b/gi, '<time>')
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<id>')
+    .replace(/\b[0-9a-f]{8,}\b/gi, '<id>')
+    .replace(/\d+/g, '<n>')
+    .trim()
+    .replace(/\s+/g, ' ');
+
+export type HashOutputOptions = {
+  maxBytes?: number;
+  previewLines: number;
+};
+
+const DEFAULT_MAX_BYTES = 65536;
+
+export const hashOutput = (
+  raw: string,
+  { maxBytes = DEFAULT_MAX_BYTES, previewLines }: HashOutputOptions,
+): { hash: string; preview: string } => {
+  const stripped = stripAnsi(raw);
+  const truncated = stripped.slice(0, maxBytes);
+  const hash = createHash('sha256').update(truncated).digest('hex');
+  const preview = truncated.split('\n').slice(0, previewLines).join('\n');
+  return { hash, preview };
+};

package/src/registry.ts

@@ -0,0 +1,121 @@
+import type { TargetKind, TargetStatus, WatchdogTarget } from './types.ts';
+
+// Local structural type for @gotgenes/pi-subagents records; no direct type import (adapter isolation)
+export type SubagentRecordLike = {
+  id: string;
+  type: string;
+  description: string;
+  status: TargetStatus;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+};
+
+const TARGET_STATUSES: readonly TargetStatus[] = [
+  'queued',
+  'running',
+  'completed',
+  'steered',
+  'aborted',
+  'stopped',
+  'error',
+];
+
+const isTargetStatus = (value: unknown): value is TargetStatus =>
+  TARGET_STATUSES.includes(value as TargetStatus);
+
+export const classifyKind = (type?: string, description?: string): TargetKind => {
+  if (!type && !description) {
+    return 'unknown';
+  }
+  const haystack = `${type ?? ''} ${description ?? ''}`.toLowerCase();
+  return haystack.includes('watchdog') ? 'watchdog' : 'task';
+};
+
+export const toWatchdogTarget = (record: SubagentRecordLike): WatchdogTarget => ({
+  id: record.id,
+  name: record.description,
+  kind: classifyKind(record.type, record.description),
+  status: record.status,
+  toolCallCount: record.toolUses,
+  createdAt: record.startedAt,
+  lastActiveAt: record.completedAt ?? record.startedAt,
+});
+
+// Status implied by each lifecycle channel; steered/compacted only refresh activity
+const CHANNEL_STATUS: Record<string, TargetStatus | undefined> = {
+  'subagents:created': 'queued',
+  'subagents:started': 'running',
+  'subagents:completed': 'completed',
+  'subagents:failed': 'error',
+  'subagents:steered': undefined,
+  'subagents:compacted': undefined,
+};
+
+export const applyEvent = (
+  targets: Map<string, WatchdogTarget>,
+  channel: string,
+  payload: unknown,
+  now: number,
+): Map<string, WatchdogTarget> => {
+  if (typeof payload !== 'object' || payload === null) {
+    return targets;
+  }
+  const data = payload as Record<string, unknown>;
+  if (typeof data.id !== 'string') {
+    return targets;
+  }
+  const existing = targets.get(data.id);
+  const payloadStatus = isTargetStatus(data.status) ? data.status : undefined;
+  const status = payloadStatus ?? CHANNEL_STATUS[channel] ?? existing?.status ?? 'queued';
+  const base: WatchdogTarget = existing ?? {
+    id: data.id,
+    name: typeof data.description === 'string' ? data.description : undefined,
+    kind: classifyKind(
+      typeof data.type === 'string' ? data.type : undefined,
+      typeof data.description === 'string' ? data.description : undefined,
+    ),
+    status,
+    toolCallCount: 0,
+    createdAt: now,
+    lastActiveAt: now,
+  };
+  const next = new Map(targets);
+  next.set(data.id, { ...base, status, lastActiveAt: now });
+  return next;
+};
+
+export const syncFromRecords = (
+  targets: Map<string, WatchdogTarget>,
+  records: SubagentRecordLike[],
+): Map<string, WatchdogTarget> => {
+  const next = new Map(targets);
+  for (const record of records) {
+    const mapped = toWatchdogTarget(record);
+    const existing = next.get(record.id);
+    next.set(record.id, {
+      ...mapped,
+      lastActiveAt: Math.max(mapped.lastActiveAt, existing?.lastActiveAt ?? 0),
+    });
+  }
+  return next;
+};
+
+export type TargetRegistry = {
+  applyEvent: (channel: string, payload: unknown, now: number) => void;
+  syncFromRecords: (records: SubagentRecordLike[]) => void;
+  list: () => WatchdogTarget[];
+};
+
+export const createTargetRegistry = (): TargetRegistry => {
+  let targets = new Map<string, WatchdogTarget>();
+  return {
+    applyEvent: (channel, payload, now) => {
+      targets = applyEvent(targets, channel, payload, now);
+    },
+    syncFromRecords: (records) => {
+      targets = syncFromRecords(targets, records);
+    },
+    list: () => [...targets.values()],
+  };
+};

package/src/store.ts

@@ -0,0 +1,137 @@
+import type { WatchdogConfig, WatchdogEvent } from './types.ts';
+
+export type AlertSeverity = 'info' | 'warning' | 'critical';
+
+export type AlertSink = (message: string, severity: AlertSeverity) => void;
+
+export type WatchdogStore = {
+  registerChild: (sessionId: string, parentSessionId?: string) => void;
+  getChild: (sessionId: string) => { parentSessionId?: string } | undefined;
+  linkAgent: (agentId: string, sessionId: string) => void;
+  linkNextAgent: (agentId: string) => void;
+  resolveTargetKey: (idOrSessionId: string) => string | undefined;
+  resolveAgentId: (idOrSessionId: string) => string | undefined;
+  appendEvent: (sessionId: string, event: Omit<WatchdogEvent, 'id' | 'targetId'>) => void;
+  getEvents: (sessionId: string, limit?: number) => WatchdogEvent[];
+  getLastAlert: (targetId: string) => { at: number; evidenceKey: string } | undefined;
+  recordAlert: (targetId: string, evidenceKey: string, at: number) => void;
+  isPaused: () => boolean;
+  setPaused: (paused: boolean) => void;
+  getRescueMessage: () => string | undefined;
+  setRescueMessage: (message: string) => void;
+  getConfigOverride: () => Partial<WatchdogConfig>;
+  setConfigOverride: (override: Partial<WatchdogConfig>) => void;
+  setAlertSink: (sink: AlertSink) => void;
+  alert: (message: string, severity: AlertSeverity) => boolean;
+};
+
+// Shared across all extension instances in this process (parent and child sessions)
+const STORE_KEY = Symbol.for('pi-watchdog-supervisor:store');
+
+const createStore = (maxEventsPerAgent: number): WatchdogStore => {
+  const children = new Map<string, { parentSessionId?: string }>();
+  const agentToSession = new Map<string, string>();
+  const buffers = new Map<string, WatchdogEvent[]>();
+  const seqs = new Map<string, number>();
+  const alerts = new Map<string, { at: number; evidenceKey: string }>();
+  // FIFO of child sessionIds not yet linked to an agent id.
+  // Heuristic: session-created and started fire adjacently per spawn (in-process,
+  // synchronous), so pairing oldest-unlinked-first is correct for serialized
+  // assembly. A mismatch only affects display linkage, not event collection.
+  const unlinked: string[] = [];
+  // Runtime policy shared across parent and child instances
+  let paused = false;
+  let rescueMessage: string | undefined;
+  let configOverride: Partial<WatchdogConfig> = {};
+  let alertSink: AlertSink | undefined;
+
+  return {
+    registerChild: (sessionId, parentSessionId) => {
+      children.set(sessionId, { parentSessionId });
+      unlinked.push(sessionId);
+    },
+    getChild: (sessionId) => children.get(sessionId),
+    linkAgent: (agentId, sessionId) => {
+      agentToSession.set(agentId, sessionId);
+      const index = unlinked.indexOf(sessionId);
+      if (index !== -1) {
+        unlinked.splice(index, 1);
+      }
+    },
+    linkNextAgent: (agentId) => {
+      const sessionId = unlinked.shift();
+      if (sessionId) {
+        agentToSession.set(agentId, sessionId);
+      }
+    },
+    resolveTargetKey: (idOrSessionId) => {
+      if (children.has(idOrSessionId) || buffers.has(idOrSessionId)) {
+        return idOrSessionId;
+      }
+      return agentToSession.get(idOrSessionId);
+    },
+    resolveAgentId: (idOrSessionId) => {
+      if (agentToSession.has(idOrSessionId)) {
+        return idOrSessionId;
+      }
+      for (const [agentId, sessionId] of agentToSession) {
+        if (sessionId === idOrSessionId) {
+          return agentId;
+        }
+      }
+      return undefined;
+    },
+    appendEvent: (sessionId, event) => {
+      const seq = (seqs.get(sessionId) ?? 0) + 1;
+      seqs.set(sessionId, seq);
+      const buffer = buffers.get(sessionId) ?? [];
+      buffer.push({ ...event, id: `${sessionId}-${seq}`, targetId: sessionId });
+      if (buffer.length > maxEventsPerAgent) {
+        buffer.splice(0, buffer.length - maxEventsPerAgent);
+      }
+      buffers.set(sessionId, buffer);
+    },
+    getEvents: (sessionId, limit) => {
+      const buffer = buffers.get(sessionId) ?? [];
+      return limit === undefined ? [...buffer] : buffer.slice(-limit);
+    },
+    getLastAlert: (targetId) => alerts.get(targetId),
+    recordAlert: (targetId, evidenceKey, at) => {
+      alerts.set(targetId, { at, evidenceKey });
+    },
+    isPaused: () => paused,
+    setPaused: (next) => {
+      paused = next;
+    },
+    getRescueMessage: () => rescueMessage,
+    setRescueMessage: (message) => {
+      rescueMessage = message;
+    },
+    getConfigOverride: () => ({ ...configOverride }),
+    setConfigOverride: (override) => {
+      configOverride = { ...configOverride, ...override };
+    },
+    setAlertSink: (sink) => {
+      alertSink = sink;
+    },
+    alert: (message, severity) => {
+      if (!alertSink) {
+        return false;
+      }
+      alertSink(message, severity);
+      return true;
+    },
+  };
+};
+
+export const getOrCreateStore = (maxEventsPerAgent: number): WatchdogStore => {
+  const holder = globalThis as Record<symbol, unknown>;
+  if (!holder[STORE_KEY]) {
+    holder[STORE_KEY] = createStore(maxEventsPerAgent);
+  }
+  return holder[STORE_KEY] as WatchdogStore;
+};
+
+export const resetStoreForTest = (): void => {
+  delete (globalThis as Record<symbol, unknown>)[STORE_KEY];
+};