pi-watchdog-supervisor 0.1.0

package/src/collector.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto';
+import type { WatchdogConfig, WatchdogEventType } from './types.ts';
+import type { WatchdogStore } from './store.ts';
+import { hashOutput, normalizeCommand, normalizeLlmBody } from './normalize.ts';
+
+// Minimal event surface used by the collector; satisfied by ExtensionAPI's
+// tool_call / tool_result overloads and by test fakes
+type PiLike = {
+  on(event: 'tool_call', handler: (event: unknown) => void): void;
+  on(event: 'tool_result', handler: (event: unknown) => void): void;
+};
+
+const EDIT_TOOL_NAMES = new Set(['edit', 'write', 'patch', 'multi_edit']);
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+// commandKey: bash command when present, otherwise toolName + first string input value.
+// Edit-family keys also include a hash of the full input, so re-running the exact
+// same edit shares a key (loop signal) while a different edit to the same file
+// gets a new key (progress).
+const extractCommandKey = (toolName: string, input: Record<string, unknown>): string => {
+  if (typeof input.command === 'string') {
+    return normalizeCommand(input.command);
+  }
+  const firstString = Object.values(input).find((value) => typeof value === 'string');
+  const base = normalizeCommand(firstString ? `${toolName} ${firstString}` : toolName);
+  if (EDIT_TOOL_NAMES.has(toolName.toLowerCase())) {
+    const inputHash = createHash('sha256').update(JSON.stringify(input)).digest('hex').slice(0, 12);
+    return `${base} #${inputHash}`;
+  }
+  return base;
+};
+
+const extractResultText = (content: unknown): string => {
+  if (!Array.isArray(content)) {
+    return '';
+  }
+  return content
+    .map((item) => {
+      const record = asRecord(item);
+      return record && record.type === 'text' && typeof record.text === 'string'
+        ? record.text
+        : '';
+    })
+    .filter((text) => text !== '')
+    .join('\n');
+};
+
+export const startCollector = (
+  pi: PiLike,
+  store: WatchdogStore,
+  sessionId: string,
+  config: WatchdogConfig,
+): (() => void) => {
+  let active = true;
+
+  pi.on('tool_call', (event) => {
+    if (!active) {
+      return;
+    }
+    const data = asRecord(event);
+    const input = asRecord(data?.input);
+    if (!data || typeof data.toolName !== 'string' || !input) {
+      return;
+    }
+    const commandKey = extractCommandKey(data.toolName, input);
+    const type: WatchdogEventType = EDIT_TOOL_NAMES.has(data.toolName.toLowerCase())
+      ? 'edit'
+      : 'tool_call';
+    store.appendEvent(sessionId, {
+      at: Date.now(),
+      type,
+      summary: `${data.toolName}: ${commandKey}`,
+      commandKey,
+    });
+  });
+
+  pi.on('tool_result', (event) => {
+    if (!active) {
+      return;
+    }
+    const data = asRecord(event);
+    if (!data || typeof data.toolName !== 'string') {
+      return;
+    }
+    const input = asRecord(data.input) ?? {};
+    const commandKey = extractCommandKey(data.toolName, input);
+    const { hash, preview } = hashOutput(extractResultText(data.content), {
+      previewLines: config.maxPreviewLines,
+    });
+    store.appendEvent(sessionId, {
+      at: Date.now(),
+      type: 'tool_result',
+      summary: `${data.toolName} result${data.isError === true ? ' (error)' : ''}`,
+      commandKey,
+      outputHash: hash,
+      outputPreview: preview,
+    });
+  });
+
+  return () => {
+    active = false;
+  };
+};
+
+// Minimal event surface for the LLM-level collector (same sources as the
+// lm-debug widget: provider request payload + finalized assistant message)
+type LlmPiLike = {
+  on(event: 'before_provider_request', handler: (event: unknown) => void): void;
+  on(event: 'message_end', handler: (event: unknown) => void): void;
+};
+
+const SNIPPET_LEN = 100;
+
+const toSnippet = (raw: string): string => {
+  const flat = raw.replace(/\s+/g, ' ').trim();
+  return flat.length > SNIPPET_LEN ? `${flat.slice(0, SNIPPET_LEN)}…` : flat;
+};
+
+// Text from OpenAI-style content: plain string or parts with text fields
+const extractPayloadText = (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');
+};
+
+// Body of the newest message sent to the provider. The full payload always
+// grows with the context, so only the last message (the per-turn delta) is
+// comparable across loop iterations.
+export const extractSentBody = (payload: unknown): string | undefined => {
+  const record = asRecord(payload);
+  const messages = Array.isArray(record?.messages) ? (record.messages as unknown[]) : [];
+  const last = asRecord(messages[messages.length - 1]);
+  if (!last) {
+    return undefined;
+  }
+  const role = typeof last.role === 'string' ? last.role : 'unknown';
+  return `${role}: ${extractPayloadText(last.content)}`;
+};
+
+// Body of a finalized assistant message: text + thinking + tool calls
+// (name and arguments — a loop usually re-issues the identical call)
+export const extractAssistantBody = (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 === 'thinking' && typeof blockRecord.thinking === 'string') {
+      parts.push(blockRecord.thinking);
+    } else if (blockRecord.type === 'toolCall') {
+      const name = typeof blockRecord.name === 'string' ? blockRecord.name : 'tool';
+      parts.push(`toolCall ${name} ${JSON.stringify(blockRecord.arguments ?? {})}`);
+    }
+  }
+  return parts.join('\n');
+};
+
+export const startLlmCollector = (
+  pi: LlmPiLike,
+  store: WatchdogStore,
+  sessionId: string,
+  // Invoked right after each llm event is appended — the hook for the
+  // event-driven stuck check
+  onEvent?: () => void,
+): (() => void) => {
+  let active = true;
+
+  const append = (type: 'llm_input' | 'llm_output', body: string) => {
+    const normalized = normalizeLlmBody(body);
+    store.appendEvent(sessionId, {
+      at: Date.now(),
+      type,
+      summary: `${type}: ${toSnippet(normalized)}`,
+      commandKey: type,
+      outputHash: createHash('sha256').update(normalized).digest('hex'),
+      outputPreview: toSnippet(normalized),
+    });
+    onEvent?.();
+  };
+
+  pi.on('before_provider_request', (event) => {
+    if (!active) {
+      return;
+    }
+    const body = extractSentBody(asRecord(event)?.payload);
+    if (body !== undefined) {
+      append('llm_input', body);
+    }
+  });
+
+  pi.on('message_end', (event) => {
+    if (!active) {
+      return;
+    }
+    const body = extractAssistantBody(asRecord(event)?.message);
+    if (body !== undefined) {
+      append('llm_output', body);
+    }
+  });
+
+  return () => {
+    active = false;
+  };
+};

package/src/commands.ts

@@ -0,0 +1,159 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from '@earendil-works/pi-coding-agent';
+import type { WatchdogConfig, WatchdogEvent, WatchdogTarget } from './types.ts';
+import type { TargetRegistry } from './registry.ts';
+import type { WatchdogStore } from './store.ts';
+import { mergeConfig } from './config.ts';
+import { detectStuck } from './detector.ts';
+import type { SubagentsIntegration } from './integrations/gotgenes-subagents.ts';
+
+type WatchdogRuntime = {
+  config: WatchdogConfig;
+  registry: TargetRegistry;
+  getIntegration: () => Promise<SubagentsIntegration>;
+  store: WatchdogStore;
+};
+
+const SUBCOMMANDS = 'status | config | set rescueMessage <msg> | pause | resume | inspect <targetId>';
+
+const formatTargets = (
+  targets: WatchdogTarget[],
+  store: WatchdogStore,
+  config: WatchdogConfig,
+): string => {
+  if (targets.length === 0) {
+    return '  (none)';
+  }
+  return targets
+    .map((target) => {
+      const key = store.resolveTargetKey(target.id);
+      const events = key ? store.getEvents(key) : [];
+      const analysis =
+        events.length > 0
+          ? detectStuck(events, config, Date.now(), store.getLastAlert(key ?? '')?.at ?? 0)
+          : undefined;
+      return [
+        `  [${target.kind}]`.padEnd(13),
+        target.id.padEnd(10),
+        target.status.padEnd(10),
+        `tools=${target.toolCallCount}`.padEnd(10),
+        `last=${new Date(target.lastActiveAt).toISOString()}`,
+        events.length > 0 ? `events=${events.length}` : '',
+        target.name ? `"${target.name}"` : '',
+        analysis?.likelyStuck ? `!! likely stuck (${analysis.confidence})` : '',
+      ]
+        .join(' ')
+        .trimEnd();
+    })
+    .join('\n');
+};
+
+const formatEvent = (event: WatchdogEvent): string => {
+  const time = new Date(event.at).toISOString().slice(11, 19);
+  const hash = event.outputHash ? ` [${event.outputHash.slice(0, 8)}]` : '';
+  return `  ${time} ${event.type.padEnd(11)} ${event.summary}${hash}`;
+};
+
+const output = (ctx: ExtensionCommandContext, message: string) => {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, 'info');
+  } else {
+    console.log(message);
+  }
+};
+
+export const registerWatchdogCommands = (pi: ExtensionAPI, runtime: WatchdogRuntime) => {
+  pi.registerCommand('watchdog', {
+    description: 'Watchdog supervisor: status, config, pause/resume, rescue message',
+    handler: async (args, ctx) => {
+      const [subcommand, ...rest] = args.trim().split(/\s+/);
+      switch (subcommand) {
+        case 'status': {
+          const { config, registry, getIntegration, store } = runtime;
+          const header = [
+            'watchdog-supervisor loaded',
+            `enabled=${config.enabled}`,
+            `paused=${store.isPaused()}`,
+            `alertMode=${config.alertMode}`,
+          ].join(' | ');
+          const integration = await getIntegration();
+          if (!integration.available) {
+            output(
+              ctx,
+              `${header}\ntargets: unavailable — install @gotgenes/pi-subagents (${integration.reason})`,
+            );
+            break;
+          }
+          registry.syncFromRecords(integration.listAgents());
+          const targets = registry.list();
+          output(
+            ctx,
+            `${header}\ntargets (${targets.length}):\n${formatTargets(targets, runtime.store, config)}`,
+          );
+          break;
+        }
+        case 'config': {
+          const merged = mergeConfig(runtime.config, runtime.store.getConfigOverride());
+          const effective = {
+            ...merged,
+            rescueMessage: runtime.store.getRescueMessage() ?? merged.rescueMessage,
+          };
+          output(ctx, JSON.stringify(effective, null, 2));
+          break;
+        }
+        case 'set': {
+          const [key, ...messageParts] = rest;
+          const message = messageParts.join(' ');
+          if (key !== 'rescueMessage' || message === '') {
+            output(ctx, 'Usage: /watchdog set rescueMessage <message>');
+            break;
+          }
+          runtime.store.setRescueMessage(message);
+          output(ctx, 'rescueMessage updated for this session');
+          break;
+        }
+        case 'pause':
+          runtime.store.setPaused(true);
+          output(ctx, 'watchdog alerting paused');
+          break;
+        case 'resume':
+          runtime.store.setPaused(false);
+          output(ctx, 'watchdog alerting resumed');
+          break;
+        case 'inspect': {
+          const [targetId] = rest;
+          if (!targetId) {
+            output(ctx, 'Usage: /watchdog inspect <targetId>');
+            break;
+          }
+          const key = runtime.store.resolveTargetKey(targetId);
+          if (!key) {
+            output(ctx, `Unknown target: ${targetId}`);
+            break;
+          }
+          const events = runtime.store.getEvents(key, 20);
+          if (events.length === 0) {
+            output(ctx, `No events recorded for ${targetId}`);
+            break;
+          }
+          const analysis = detectStuck(
+            runtime.store.getEvents(key),
+            runtime.config,
+            Date.now(),
+            runtime.store.getLastAlert(key)?.at ?? 0,
+          );
+          output(
+            ctx,
+            `events for ${targetId} (latest ${events.length}):\n${events.map(formatEvent).join('\n')}\n` +
+              `analysis: likelyStuck=${analysis.likelyStuck} confidence=${analysis.confidence} reasons=[${analysis.reasons.join('; ')}]`,
+          );
+          break;
+        }
+        default:
+          output(ctx, `Unknown subcommand. Available: ${SUBCOMMANDS}`);
+      }
+    },
+  });
+};

package/src/config.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { WatchdogConfig } from './types.ts';
+
+export const DEFAULT_CONFIG: WatchdogConfig = {
+  enabled: true,
+  rescueMessage:
+    'The AI agent might be stuck. Stop repeating the current actions, then resume the task.',
+  llmRepeatThreshold: 3,
+  idleNoProgressSec: 0, // 0 = idle_no_progress detection disabled
+  cooldownSec: 0, // 0 = no cooldown; -1 = same evidence alerts once; >0 = seconds
+  maxPreviewLines: 20,
+  maxEventsPerAgent: 200,
+  alertMode: 'main_only',
+  steerDryRunDefault: null, // null = built-in safe default (dry-run)
+  debug: false, // show the lm-debug console (full sent/received messages)
+};
+
+export const getConfigPaths = (projectDir: string) => ({
+  globalPath: join(homedir(), '.pi', 'agent', 'watchdog-supervisor', 'config.json'),
+  projectPath: join(projectDir, '.pi', 'watchdog-supervisor.json'),
+});
+
+export const loadConfigFile = (
+  path: string,
+): { config: Partial<WatchdogConfig> | null; warning?: string } => {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    // missing file is not an error
+    return { config: null };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { config: null, warning: `Invalid JSON in ${path}; file ignored` };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { config: null, warning: `Expected a JSON object in ${path}; file ignored` };
+  }
+  return { config: pickKnownConfig(parsed as Record<string, unknown>) };
+};
+
+// Keep only WatchdogConfig fields; drop unknown keys
+export const pickKnownConfig = (raw: Record<string, unknown>): Partial<WatchdogConfig> => {
+  const config: Partial<WatchdogConfig> = {};
+  for (const key of Object.keys(DEFAULT_CONFIG) as Array<keyof WatchdogConfig>) {
+    if (key in raw) {
+      (config as Record<string, unknown>)[key] = raw[key];
+    }
+  }
+  return config;
+};
+
+export const mergeConfig = (
+  ...parts: Array<Partial<WatchdogConfig> | null | undefined>
+): WatchdogConfig => {
+  const merged: WatchdogConfig = { ...DEFAULT_CONFIG };
+  for (const part of parts) {
+    if (part) {
+      Object.assign(merged, part);
+    }
+  }
+  return merged;
+};
+
+export const loadEffectiveConfig = (
+  projectDir: string,
+): { config: WatchdogConfig; warnings: string[] } => {
+  const { globalPath, projectPath } = getConfigPaths(projectDir);
+  const globalResult = loadConfigFile(globalPath);
+  const projectResult = loadConfigFile(projectPath);
+  const warnings = [globalResult.warning, projectResult.warning].filter(
+    (warning): warning is string => warning !== undefined,
+  );
+  return { config: mergeConfig(globalResult.config, projectResult.config), warnings };
+};

package/src/detector.ts

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import type {
+  StuckAnalysis,
+  StuckEvidence,
+  WatchdogConfig,
+  WatchdogEvent,
+} from './types.ts';
+
+const RECENT_ACTIVITY_MS = 60_000;
+const MIN_TOOL_EVENTS_FOR_IDLE = 5;
+
+// Longest run of consecutive identical normalized-body hashes among events of
+// one LLM type, ignoring events at or before sinceAt. Consecutive (rather than
+// total) keeps ordinary re-visits of an earlier message from counting as a
+// loop; sinceAt resets the counter after an alert so a historical run does not
+// keep re-triggering once the agent has recovered.
+const longestIdenticalRun = (
+  events: WatchdogEvent[],
+  type: 'llm_input' | 'llm_output',
+  sinceAt: number,
+): { length: number; hash?: string } => {
+  let best = 0;
+  let bestHash: string | undefined;
+  let current = 0;
+  let currentHash: string | undefined;
+  for (const event of events) {
+    if (event.type !== type || !event.outputHash || event.at <= sinceAt) {
+      continue;
+    }
+    current = event.outputHash === currentHash ? current + 1 : 1;
+    currentHash = event.outputHash;
+    if (current > best) {
+      best = current;
+      bestHash = currentHash;
+    }
+  }
+  return { length: best, hash: bestHash };
+};
+
+const detectIdleNoProgress = (
+  events: WatchdogEvent[],
+  config: WatchdogConfig,
+  now: number,
+): boolean => {
+  // idleNoProgressSec <= 0 disables this rule
+  if (config.idleNoProgressSec <= 0 || events.length === 0) {
+    return false;
+  }
+  const last = events[events.length - 1];
+  if (now - last.at >= RECENT_ACTIVITY_MS) {
+    return false;
+  }
+  const idleMs = config.idleNoProgressSec * 1000;
+  const lastEdit = [...events].reverse().find((event) => event.type === 'edit');
+  const progressCutoff = lastEdit ? lastEdit.at : events[0].at;
+  if (lastEdit && now - lastEdit.at < idleMs) {
+    return false;
+  }
+  if (!lastEdit && now - events[0].at < idleMs) {
+    return false;
+  }
+  const toolEvents = events.filter(
+    (event) =>
+      (event.type === 'tool_call' || event.type === 'tool_result') && event.at >= progressCutoff,
+  );
+  return toolEvents.length >= MIN_TOOL_EVENTS_FOR_IDLE;
+};
+
+export const detectStuck = (
+  events: WatchdogEvent[],
+  config: WatchdogConfig,
+  now: number,
+  // Only events after this timestamp count toward llm repetition — pass the
+  // last alert time so the counter resets after each alert
+  sinceAt = 0,
+): StuckAnalysis => {
+  const evidence: StuckEvidence[] = [];
+  const reasons: string[] = [];
+  const triggers: string[] = [];
+
+  // LLM-level repetition: same normalized message body (timestamps, ids and
+  // digit runs stripped) recurring back-to-back. llmRepeatThreshold <= 0
+  // disables this rule.
+  if (config.llmRepeatThreshold > 0) {
+    const rules = [
+      { type: 'llm_input', evidenceType: 'repeated_llm_input', label: 'input sent to the LLM' },
+      { type: 'llm_output', evidenceType: 'repeated_llm_output', label: 'LLM output' },
+    ] as const;
+    for (const rule of rules) {
+      const run = longestIdenticalRun(events, rule.type, sinceAt);
+      if (run.length >= config.llmRepeatThreshold && run.hash) {
+        evidence.push({
+          type: rule.evidenceType,
+          summary: `llm message repeated ${run.length} times: same ${rule.label} body (hash ${run.hash.slice(0, 8)})`,
+        });
+        reasons.push(`the same ${rule.label} recurred ${run.length} times in a row`);
+        triggers.push(`${rule.type}:${run.hash}`);
+      }
+    }
+  }
+
+  if (detectIdleNoProgress(events, config, now)) {
+    evidence.push({
+      type: 'idle_no_progress',
+      summary: `no edit for >= ${config.idleNoProgressSec}s while tools keep running`,
+    });
+    reasons.push('tools keep running but nothing has been edited');
+    triggers.push('idle_no_progress');
+  }
+
+  const likelyStuck = evidence.length > 0;
+  const distinctTypes = new Set(evidence.map((item) => item.type)).size;
+  const evidenceKey = likelyStuck
+    ? createHash('sha256')
+        .update(
+          `${[...new Set(evidence.map((item) => item.type))].sort().join(',')}|${[...triggers].sort().join(',')}`,
+        )
+        .digest('hex')
+        .slice(0, 16)
+    : '';
+
+  return {
+    likelyStuck,
+    confidence: distinctTypes >= 2 ? 'high' : distinctTypes === 1 ? 'medium' : 'low',
+    reasons,
+    evidence,
+    evidenceKey,
+  };
+};
+
+export const shouldAlert = (
+  lastAlert: { at: number; evidenceKey: string } | undefined,
+  analysis: StuckAnalysis,
+  now: number,
+  cooldownSec: number,
+): boolean => {
+  if (!analysis.likelyStuck) {
+    return false;
+  }
+  if (!lastAlert) {
+    return true;
+  }
+  // cooldownSec === 0: no cooldown, alert on every check that meets the threshold
+  if (cooldownSec === 0) {
+    return true;
+  }
+  // cooldownSec < 0: infinite cooldown, same evidence alerts only once
+  const inCooldown = cooldownSec < 0 || now - lastAlert.at < cooldownSec * 1000;
+  return !(inCooldown && analysis.evidenceKey === lastAlert.evidenceKey);
+};