@monotykamary/pi-supervisor 0.5.9

package/src/session/client.ts

@@ -0,0 +1,46 @@
+/**
+ * Session client - high-level interface for calling the supervisor model.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { SteeringDecision } from '../types.js';
+import { SupervisorSession } from './supervisor-session.js';
+import { parseDecision, safeContinue } from './response-parser.js';
+
+// Global session manager (one per supervision goal)
+let activeSession: SupervisorSession | null = null;
+
+function getOrCreateSession(): SupervisorSession {
+  if (!activeSession) {
+    activeSession = new SupervisorSession();
+  }
+  return activeSession;
+}
+
+/** Dispose the global supervisor session. */
+export function disposeSession(): void {
+  activeSession?.dispose();
+  activeSession = null;
+}
+
+/**
+ * Run a one-shot supervisor analysis using reusable session.
+ * Returns { action: "continue" } on any failure so the chat is never interrupted.
+ */
+export async function callSupervisorModel(
+  ctx: ExtensionContext,
+  provider: string,
+  modelId: string,
+  systemPrompt: string,
+  userPrompt: string,
+  signal?: AbortSignal,
+  onDelta?: (accumulated: string) => void
+): Promise<SteeringDecision> {
+  const session = getOrCreateSession();
+  const started = await session.ensureStarted(ctx, provider, modelId, systemPrompt);
+  if (!started) return safeContinue('Failed to start supervisor session');
+
+  const text = await session.prompt(userPrompt, signal, onDelta);
+  if (text === null) return safeContinue('Model call failed');
+  return parseDecision(text);
+}

package/src/session/response-parser.ts

@@ -0,0 +1,37 @@
+/**
+ * Response parser for supervisor model decisions.
+ */
+
+import type { SteeringDecision, InterventionASI } from '../types.js';
+
+/**
+ * Parse a supervisor decision from text response.
+ * Handles JSON extraction from markdown code blocks or raw JSON.
+ */
+export function parseDecision(text: string): SteeringDecision {
+  const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/) ?? text.match(/(\{[\s\S]*\})/);
+  const jsonStr = jsonMatch?.[1] ?? text.trim();
+
+  try {
+    const parsed = JSON.parse(jsonStr) as Partial<SteeringDecision>;
+    const action = parsed.action;
+    if (action !== 'continue' && action !== 'steer' && action !== 'done') {
+      return safeContinue('Invalid action in supervisor response');
+    }
+    return {
+      action,
+      message: typeof parsed.message === 'string' ? parsed.message.trim() : undefined,
+      reasoning: typeof parsed.reasoning === 'string' ? parsed.reasoning : '',
+      confidence: typeof parsed.confidence === 'number' ? parsed.confidence : 0.5,
+      asi:
+        parsed.asi && typeof parsed.asi === 'object' ? (parsed.asi as InterventionASI) : undefined,
+    };
+  } catch {
+    return safeContinue('Failed to parse supervisor JSON decision');
+  }
+}
+
+/** Create a safe "continue" decision with a reason. */
+export function safeContinue(reason: string): SteeringDecision {
+  return { action: 'continue', reasoning: reason, confidence: 0 };
+}

package/src/session/supervisor-session.ts

@@ -0,0 +1,102 @@
+/**
+ * SupervisorSession - reusable session for a single supervision goal.
+ * Maintains context window across multiple analyses for token efficiency.
+ */
+
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+} from '@earendil-works/pi-coding-agent';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+export class SupervisorSession {
+  private session: Awaited<ReturnType<typeof createAgentSession>>['session'] | null = null;
+  private model: any = null;
+  private systemPrompt: string = '';
+
+  async ensureStarted(
+    ctx: ExtensionContext,
+    provider: string,
+    modelId: string,
+    systemPrompt: string
+  ): Promise<boolean> {
+    // If model or system prompt changed, need new session
+    const newModel = ctx.modelRegistry.find(provider, modelId);
+    if (!newModel) return false;
+
+    if (this.session && this.model === newModel && this.systemPrompt === systemPrompt) {
+      // Session reusable
+      return true;
+    }
+
+    // Dispose old session if exists
+    this.dispose();
+
+    const loader = new DefaultResourceLoader({
+      cwd: ctx.cwd,
+      agentDir: getAgentDir(),
+      noExtensions: true,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      systemPromptOverride: () => systemPrompt,
+    });
+    await loader.reload();
+
+    try {
+      const result = await createAgentSession({
+        sessionManager: SessionManager.inMemory(),
+        agentDir: getAgentDir(),
+        model: newModel,
+        tools: [],
+        resourceLoader: loader,
+      });
+      this.session = result.session;
+      this.model = newModel;
+      this.systemPrompt = systemPrompt;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async prompt(
+    userPrompt: string,
+    signal?: AbortSignal,
+    onDelta?: (accumulated: string) => void
+  ): Promise<string | null> {
+    if (!this.session) return null;
+
+    const onAbort = () => this.session?.abort();
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    let responseText = '';
+    const unsubscribe = this.session.subscribe((event) => {
+      if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+        responseText += event.assistantMessageEvent.delta;
+        onDelta?.(responseText);
+      }
+    });
+
+    try {
+      await this.session.prompt(userPrompt);
+    } catch {
+      return null;
+    } finally {
+      unsubscribe();
+      signal?.removeEventListener('abort', onAbort);
+    }
+
+    return responseText;
+  }
+
+  dispose(): void {
+    if (this.session) {
+      this.session.dispose();
+      this.session = null;
+    }
+    this.model = null;
+  }
+}

package/src/state/manager.ts

@@ -0,0 +1,133 @@
+/**
+ * SupervisorStateManager — manages in-memory supervisor state and session persistence.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { SupervisorState, SupervisorIntervention, ReframeTier } from '../types.js';
+import { detectIneffectivePattern, type IneffectivePattern } from './patterns.js';
+import {
+  getReframeTier,
+  escalateReframeTier as escalateReframeTierInState,
+  resetReframeTier as resetReframeTierInState,
+} from './reframe.js';
+
+const ENTRY_TYPE = 'supervisor-state';
+
+export class SupervisorStateManager {
+  private state: SupervisorState | null = null;
+  private pi: ExtensionAPI;
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+  }
+
+  start(outcome: string, provider: string, modelId: string): void {
+    this.state = {
+      active: true,
+      outcome,
+      provider,
+      modelId,
+      interventions: [],
+      startedAt: Date.now(),
+      reframeTier: 0,
+      idleSteers: 0,
+    };
+    this.persist();
+  }
+
+  stop(): void {
+    if (!this.state) return;
+    this.state.active = false;
+    this.state.outcome = '';
+    this.persist();
+  }
+
+  isActive(): boolean {
+    return this.state?.active === true;
+  }
+
+  getState(): SupervisorState | null {
+    return this.state;
+  }
+
+  addIntervention(intervention: SupervisorIntervention): void {
+    if (!this.state) return;
+    this.state.interventions.push(intervention);
+    this.persist();
+  }
+
+  incrementIdleSteers(): void {
+    if (!this.state) return;
+    this.state.idleSteers = (this.state.idleSteers ?? 0) + 1;
+  }
+
+  resetIdleSteers(): void {
+    if (!this.state) return;
+    this.state.idleSteers = 0;
+  }
+
+  getIdleSteers(): number {
+    return this.state?.idleSteers ?? 0;
+  }
+
+  setModel(provider: string, modelId: string): void {
+    if (!this.state) return;
+    this.state.provider = provider;
+    this.state.modelId = modelId;
+    this.persist();
+  }
+
+  updateOutcome(outcome: string): void {
+    if (!this.state) return;
+    this.state.outcome = outcome;
+    this.persist();
+  }
+
+  // ---- Reframe tier management ----
+
+  getReframeTier(): ReframeTier {
+    return getReframeTier(this.state);
+  }
+
+  escalateReframeTier(): void {
+    if (!this.state) return;
+    if (escalateReframeTierInState(this.state)) {
+      this.persist();
+    }
+  }
+
+  resetReframeTier(): void {
+    if (!this.state) return;
+    resetReframeTierInState(this.state);
+    this.persist();
+  }
+
+  // ---- Pattern detection ----
+
+  detectIneffectivePattern(): IneffectivePattern {
+    if (!this.state) return { detected: false, similarCount: 0, secondsSinceLastSteer: 0 };
+    return detectIneffectivePattern(this.state);
+  }
+
+  // ---- Persistence ----
+
+  loadFromSession(ctx: ExtensionContext): void {
+    const entries = ctx.sessionManager.getBranch();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      if (entry.type === 'custom' && (entry as any).customType === ENTRY_TYPE) {
+        const loaded = (entry as any).data as SupervisorState;
+        this.state = {
+          ...loaded,
+        };
+        return;
+      }
+    }
+    this.state = null;
+  }
+
+  persist(): void {
+    if (!this.state) return;
+    this.pi.appendEntry(ENTRY_TYPE, this.state);
+  }
+}

package/src/state/mid-run-signals.ts

@@ -0,0 +1,103 @@
+/**
+ * Mid-run signal detection — replaces the blind turn counter with
+ * reactive signals computed from the conversation tail.
+ */
+
+import type { Message } from '@earendil-works/pi-ai';
+import type { NormalizedBlock } from '../compaction/types.js';
+import { normalize } from '../compaction/normalize.js';
+import { filterNoise } from '../compaction/filter-noise.js';
+import { extractPath } from '../compaction/tool-args.js';
+
+export interface MidRunSignal {
+  type: 'tool_error' | 'file_read_loop';
+  detail?: string;
+}
+
+/** How many recent messages to scan for signals. */
+const SIGNAL_WINDOW = 30;
+
+/** Reads of the same file without an edit to that file triggers a loop signal. */
+const FILE_READ_LOOP_THRESHOLD = 5;
+
+const FILE_MUTATION_TOOLS = new Set(['Edit', 'Write', 'edit', 'write', 'MultiEdit']);
+
+const FILE_READ_TOOLS = new Set(['Read', 'read', 'read_file', 'View']);
+
+/**
+ * Detect mid-run signals from the recent conversation tail.
+ * Returns the first signal found (ordered by severity), or null if none.
+ */
+export function detectMidRunSignals(messages: Message[]): MidRunSignal | null {
+  const tail = messages.slice(-SIGNAL_WINDOW);
+  if (tail.length === 0) return null;
+
+  const blocks = filterNoise(normalize(tail));
+  if (blocks.length === 0) return null;
+
+  return checkToolErrors(blocks) ?? checkFileReadLoop(blocks);
+}
+
+/** How many consecutive tool errors (separated by their tool_call) trigger a signal. */
+const CONSECUTIVE_ERROR_THRESHOLD = 5;
+
+function checkToolErrors(blocks: NormalizedBlock[]): MidRunSignal | null {
+  let consecutive = 0;
+  for (let i = blocks.length - 1; i >= Math.max(0, blocks.length - 10); i--) {
+    const b = blocks[i];
+    if (b.kind === 'tool_result' && b.isError) {
+      consecutive++;
+      if (consecutive >= CONSECUTIVE_ERROR_THRESHOLD) {
+        return { type: 'tool_error', detail: `${b.name}: ${b.text.slice(0, 80)}` };
+      }
+    } else if (b.kind === 'tool_call') {
+      // tool_call between error results is expected — skip it
+      continue;
+    } else if (b.kind === 'tool_result') {
+      // A successful result breaks the streak
+      break;
+    } else {
+      // Any other block (user, assistant, bash) breaks the streak
+      break;
+    }
+  }
+  return null;
+}
+
+/** Build a loop-detection key for a read tool call. Includes line range so that
+ *  reading different portions of the same file (pagination) is not treated as a loop. */
+function readLoopKey(args: Record<string, unknown>): string | null {
+  const path = extractPath(args);
+  if (!path) return null;
+  const offset = args['offset'];
+  const limit = args['limit'];
+  if (offset != null || limit != null) {
+    return `${path}:${offset ?? ''}-${limit ?? ''}`;
+  }
+  return path;
+}
+
+function checkFileReadLoop(blocks: NormalizedBlock[]): MidRunSignal | null {
+  const readCounts = new Map<string, number>();
+
+  for (const b of blocks) {
+    if (b.kind !== 'tool_call') continue;
+
+    if (FILE_MUTATION_TOOLS.has(b.name)) {
+      const path = extractPath(b.args);
+      if (path) readCounts.delete(path);
+    } else if (FILE_READ_TOOLS.has(b.name)) {
+      const key = readLoopKey(b.args);
+      if (key) {
+        const count = (readCounts.get(key) ?? 0) + 1;
+        readCounts.set(key, count);
+        if (count >= FILE_READ_LOOP_THRESHOLD) {
+          // Report just the file path for the signal detail
+          return { type: 'file_read_loop', detail: extractPath(b.args)! };
+        }
+      }
+    }
+  }
+
+  return null;
+}

package/src/state/patterns.ts

@@ -0,0 +1,82 @@
+/**
+ * Pattern detection for ineffective steering interventions.
+ * Uses timestamps from intervention records instead of turn counting.
+ */
+
+import type { SupervisorIntervention, SupervisorState } from '../types.js';
+
+export interface IneffectivePattern {
+  detected: boolean;
+  similarCount: number;
+  secondsSinceLastSteer: number;
+}
+
+/** Stagnation threshold: no steer in this many seconds suggests ineffectiveness */
+const STAGNATION_SECS = 60;
+
+/**
+ * Detect if recent interventions show a pattern of ineffectiveness.
+ * Returns similarity info if the last 2+ steering messages are similar,
+ * or if stagnation is detected (no new steer in a while despite active supervision).
+ */
+export function detectIneffectivePattern(
+  state: Pick<SupervisorState, 'interventions' | 'startedAt'>
+): IneffectivePattern {
+  const now = Date.now();
+  const lastSteerTs =
+    state.interventions.length > 0
+      ? state.interventions[state.interventions.length - 1].timestamp
+      : state.startedAt;
+  const secondsSinceLastSteer = Math.round((now - lastSteerTs) / 1000);
+
+  // Stagnation: no new steer action in a while
+  const stagnating = secondsSinceLastSteer >= STAGNATION_SECS;
+
+  const recent = state.interventions.slice(-3);
+  if (recent.length < 2) {
+    return { detected: stagnating, similarCount: recent.length, secondsSinceLastSteer };
+  }
+
+  const messages = recent.map((iv) => iv.message.toLowerCase());
+  let similarCount = 1;
+
+  for (let i = 1; i < messages.length; i++) {
+    if (areMessagesSimilar(messages[i - 1], messages[i])) {
+      similarCount++;
+    }
+  }
+
+  const detected = similarCount >= 2 || stagnating;
+
+  return { detected, similarCount, secondsSinceLastSteer };
+}
+
+function areMessagesSimilar(a: string, b: string): boolean {
+  const normalize = (s: string) => s.replace(/[^\w\s]/g, '').trim();
+  const normA = normalize(a);
+  const normB = normalize(b);
+
+  if (normA === normB) return true;
+
+  const directiveWords = [
+    'focus',
+    'implement',
+    'add',
+    'fix',
+    'create',
+    'build',
+    'need',
+    'should',
+    'must',
+  ];
+  const aDirectives = directiveWords.filter((w) => normA.includes(w));
+  const bDirectives = directiveWords.filter((w) => normB.includes(w));
+
+  const commonDirectives = aDirectives.filter((w) => bDirectives.includes(w));
+  if (commonDirectives.length >= 2) return true;
+
+  const lenRatio = Math.min(normA.length, normB.length) / Math.max(normA.length, normB.length);
+  if (lenRatio > 0.7 && commonDirectives.length >= 1) return true;
+
+  return false;
+}

package/src/state/reframe.ts

@@ -0,0 +1,27 @@
+/**
+ * Reframe tier state management.
+ */
+
+import type { ReframeTier, SupervisorState } from '../types.js';
+
+const MAX_TIER: ReframeTier = 4;
+
+/** Get the current reframe tier from state */
+export function getReframeTier(state: SupervisorState | null): ReframeTier {
+  return state?.reframeTier ?? 0;
+}
+
+/** Escalate reframe tier in state */
+export function escalateReframeTier(state: SupervisorState): boolean {
+  const current = state.reframeTier ?? 0;
+  if (current < MAX_TIER) {
+    state.reframeTier = (current + 1) as ReframeTier;
+    return true;
+  }
+  return false;
+}
+
+/** Reset reframe tier to 0 */
+export function resetReframeTier(state: SupervisorState): void {
+  state.reframeTier = 0;
+}

package/src/subagent-detector.ts

@@ -0,0 +1,94 @@
+/**
+ * Subagent detection via process tree inspection.
+ *
+ * This is extension-agnostic: we don't care HOW subagents were created
+ * (pi-messenger, manual spawn, or other extensions). We just check if
+ * there are child 'pi' processes still running.
+ */
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+export interface SubagentStatus {
+  hasActiveSubagents: boolean;
+  count: number;
+  pids: number[];
+}
+
+/**
+ * Check for child pi processes spawned by the current process.
+ * Works on macOS and Linux via ps. Windows returns false (not implemented).
+ */
+export async function checkChildPiProcesses(): Promise<SubagentStatus> {
+  const platform = process.platform;
+
+  if (platform === 'darwin' || platform === 'linux') {
+    return checkUnixChildProcesses();
+  }
+
+  // Windows: not implemented, assume no subagents
+  return { hasActiveSubagents: false, count: 0, pids: [] };
+}
+
+async function checkUnixChildProcesses(): Promise<SubagentStatus> {
+  try {
+    const ppid = process.pid;
+
+    // Get all pi processes with their parent PID
+    // Format: ppid pid command
+    const { stdout } = await execAsync(`ps -eo ppid,pid,comm | grep -E "\\bpi\\b" || true`);
+
+    const pids: number[] = [];
+
+    for (const line of stdout.trim().split('\n')) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 3) continue;
+
+      const childPpid = parseInt(parts[0], 10);
+      const childPid = parseInt(parts[1], 10);
+      const comm = parts[2];
+
+      // Check if this pi process is our direct child
+      // Also check for grandchildren (subagents spawning subagents)
+      if (childPpid === ppid && comm === 'pi') {
+        pids.push(childPid);
+      }
+    }
+
+    return {
+      hasActiveSubagents: pids.length > 0,
+      count: pids.length,
+      pids,
+    };
+  } catch {
+    return { hasActiveSubagents: false, count: 0, pids: [] };
+  }
+}
+
+/**
+ * Poll until no child pi processes remain or timeout.
+ * Returns true if all subagents completed, false if timeout.
+ */
+export async function waitForSubagents(
+  checkIntervalMs: number = 2000,
+  timeoutMs: number = 60000
+): Promise<{ completed: boolean; finalStatus: SubagentStatus }> {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    const status = await checkChildPiProcesses();
+    if (!status.hasActiveSubagents) {
+      return { completed: true, finalStatus: status };
+    }
+    await sleep(checkIntervalMs);
+  }
+
+  const finalStatus = await checkChildPiProcesses();
+  return { completed: !finalStatus.hasActiveSubagents, finalStatus };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Core types for the pi-supervisor extension.
+ */
+
+/** A single intervention record */
+export interface SupervisorIntervention {
+  message: string;
+  reasoning: string;
+  timestamp: number;
+  asi?: InterventionASI;
+}
+
+/** Reframe tier tracks escalation of intervention strategies */
+export type ReframeTier = 0 | 1 | 2 | 3 | 4;
+
+/** Actionable Side Information — free-form observations from interventions */
+export interface InterventionASI {
+  [key: string]: unknown;
+}
+
+/** Full supervisor state — persisted to session */
+export interface SupervisorState {
+  active: boolean;
+  outcome: string;
+  provider: string;
+  modelId: string;
+  interventions: SupervisorIntervention[];
+  startedAt: number;
+  reframeTier?: ReframeTier;
+  /** Consecutive agent_end steers; reset on done/stop/new supervision */
+  idleSteers?: number;
+  /** Whether we just steered and should verify on next mid-run event */
+}
+
+/** Decision returned by the supervisor LLM */
+export interface SteeringDecision {
+  action: 'continue' | 'steer' | 'done';
+  message?: string;
+  reasoning: string;
+  confidence: number;
+  asi?: InterventionASI;
+}