@monotykamary/pi-supervisor 0.5.9

package/src/compaction/normalize.ts

@@ -0,0 +1,73 @@
+import type { Message } from '@earendil-works/pi-ai';
+import type { NormalizedBlock } from './types';
+import { textOf } from './content';
+import { sanitize } from './sanitize';
+
+const normalizeOne = (msg: Message, msgIndex: number): NormalizedBlock[] => {
+  if (msg.role === 'user') {
+    const blocks: NormalizedBlock[] = [];
+    const text = sanitize(textOf(msg.content));
+    if (text) blocks.push({ kind: 'user', text, sourceIndex: msgIndex });
+    if (msg.content && typeof msg.content !== 'string') {
+      for (const part of msg.content) {
+        if (part.type === 'image') {
+          blocks.push({ kind: 'user', text: `[image: ${part.mimeType}]`, sourceIndex: msgIndex });
+        }
+      }
+    }
+    return blocks.length > 0 ? blocks : [{ kind: 'user', text: '', sourceIndex: msgIndex }];
+  }
+
+  if ((msg as any).role === 'bashExecution') {
+    const cmd = (msg as any).command ?? '';
+    const out = (msg as any).output ?? '';
+    const exit = (msg as any).exitCode;
+    return [{ kind: 'bash', command: cmd, output: out, exitCode: exit, sourceIndex: msgIndex }];
+  }
+
+  if (msg.role === 'toolResult') {
+    return [
+      {
+        kind: 'tool_result',
+        name: msg.toolName,
+        text: sanitize(textOf(msg.content)),
+        isError: msg.isError,
+        sourceIndex: msgIndex,
+      },
+    ];
+  }
+
+  if (msg.role === 'assistant') {
+    if (!msg.content) return [];
+    if (typeof msg.content === 'string') {
+      return [{ kind: 'assistant', text: sanitize(msg.content), sourceIndex: msgIndex }];
+    }
+
+    const blocks: NormalizedBlock[] = [];
+    for (const part of msg.content) {
+      if (part.type === 'text') {
+        blocks.push({ kind: 'assistant', text: sanitize(part.text), sourceIndex: msgIndex });
+      } else if (part.type === 'thinking') {
+        blocks.push({
+          kind: 'thinking',
+          text: sanitize(part.thinking),
+          redacted: part.redacted ?? false,
+          sourceIndex: msgIndex,
+        });
+      } else if (part.type === 'toolCall') {
+        blocks.push({
+          kind: 'tool_call',
+          name: part.name,
+          args: part.arguments,
+          sourceIndex: msgIndex,
+        });
+      }
+    }
+    return blocks;
+  }
+
+  return [];
+};
+
+export const normalize = (messages: Message[]): NormalizedBlock[] =>
+  messages.flatMap((msg, i) => normalizeOne(msg, i));

package/src/compaction/sanitize.ts

@@ -0,0 +1,5 @@
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]/g;
+const CTRL_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+
+export const sanitize = (text: string): string =>
+  text.replace(/\r\n/g, '\n').replace(/\r/g, '\n').replace(ANSI_RE, '').replace(CTRL_RE, '');

package/src/compaction/sections.ts

@@ -0,0 +1,19 @@
+import type { TranscriptEntry } from './brief';
+import type { SymbolRef } from './extract/shared-symbols';
+
+export interface SectionData {
+  sessionGoal: string[];
+  outstandingContext: string[];
+  filesAndChanges: string[];
+  commits: string[];
+  userPreferences: string[];
+  /** Exported signatures from modified/read files */
+  typeCatalog: string[];
+  /** Symbol-level changes (function/type/class names per file) */
+  symbolChanges: SymbolRef[];
+  /** Per-turn one-liner summaries for the HCA zone (heaviest compression, oldest turns) */
+  turnSummaries: string[];
+  briefTranscript: string;
+  /** Structured transcript entries (verbose object format) */
+  transcriptEntries: TranscriptEntry[];
+}

package/src/compaction/skill-collapse.ts

@@ -0,0 +1,35 @@
+/** Shared skill-tag collapse utilities */
+
+const SKILL_TAG_RE = /^-?\s*<skill\s+name="([^"]+)"/;
+const SKILL_CLOSE_RE = /^-?\s*<\/skill>/;
+
+/** Collapse skill tags in an array of lines — dedup by name, drop all content inside block */
+export const collapseSkillLines = (lines: string[]): string[] => {
+  const result: string[] = [];
+  const seenSkills = new Set<string>();
+  let insideSkill = false;
+
+  for (const line of lines) {
+    const skillMatch = line.match(SKILL_TAG_RE);
+    if (skillMatch) {
+      insideSkill = true;
+      const name = skillMatch[1];
+      if (!seenSkills.has(name)) {
+        seenSkills.add(name);
+        result.push(`[skill: ${name}]`);
+      }
+      continue;
+    }
+    if (insideSkill) {
+      if (SKILL_CLOSE_RE.test(line)) insideSkill = false;
+      continue;
+    }
+    result.push(line);
+  }
+  return result;
+};
+
+/** Collapse <skill name="X" ...>...</skill> blocks in raw text */
+const SKILL_BLOCK_RE = /<skill\s+name="([^"]+)"[^>]*>[\s\S]*?(?:<\/skill>|$)/g;
+export const collapseSkillText = (text: string): string =>
+  text.replace(SKILL_BLOCK_RE, (_, name) => `[skill: ${name}]`);

package/src/compaction/tool-args.ts

@@ -0,0 +1,14 @@
+export const extractPath = (args: Record<string, unknown>): string | null => {
+  for (const key of ['path', 'file_path', 'filePath', 'file']) {
+    if (typeof args[key] === 'string') return args[key] as string;
+  }
+  return null;
+};
+
+export const summarizeToolArgs = (args: Record<string, unknown>): string => {
+  const path = extractPath(args);
+  if (path) return `path=${path}`;
+  if (typeof args.command === 'string') return `command=${args.command}`;
+  if (typeof args.query === 'string') return `query=${args.query}`;
+  return Object.keys(args).join(', ');
+};

package/src/compaction/types.ts

@@ -0,0 +1,26 @@
+import type { Message } from '@earendil-works/pi-ai';
+
+export interface FileOps {
+  readFiles?: string[];
+  modifiedFiles?: string[];
+  createdFiles?: string[];
+}
+
+/** Pre-computed look-ahead index: maps tool_call index → nearest tool_result block. */
+export interface ToolResultIndex {
+  get(callIndex: number): Extract<NormalizedBlock, { kind: 'tool_result' }> | null;
+}
+
+export type NormalizedBlock =
+  | { kind: 'user'; text: string; sourceIndex?: number }
+  | { kind: 'assistant'; text: string; sourceIndex?: number }
+  | { kind: 'tool_call'; name: string; args: Record<string, unknown>; sourceIndex?: number }
+  | { kind: 'tool_result'; name: string; text: string; isError: boolean; sourceIndex?: number }
+  | {
+      kind: 'bash';
+      command: string;
+      output: string;
+      exitCode: number | undefined;
+      sourceIndex?: number;
+    }
+  | { kind: 'thinking'; text: string; redacted: boolean; sourceIndex?: number };

package/src/core/analyzer.ts

@@ -0,0 +1,58 @@
+/**
+ * Main analyzer - orchestrates supervisor analysis using compaction-based context.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { SteeringDecision, SupervisorState } from '../types.js';
+import { callSupervisorModel } from '../session/client.js';
+import { loadSystemPrompt } from './prompt-loader.js';
+import {
+  buildCompactionSummary,
+  extractMessages,
+  formatForSupervisor,
+} from '../compaction/index.js';
+import { buildUserPrompt } from './prompt-builder.js';
+
+/**
+ * Analyze the current conversation and return a steering decision.
+ * Falls back to { action: "steer" } when the agent is idle to prevent it from staying stuck.
+ */
+export async function analyze(
+  ctx: ExtensionContext,
+  state: SupervisorState,
+  agentIsIdle: boolean,
+  ineffectivePattern?: { detected: boolean; similarCount: number; secondsSinceLastSteer: number },
+  signal?: AbortSignal,
+  onDelta?: (accumulated: string) => void
+): Promise<SteeringDecision> {
+  const { prompt: systemPrompt } = loadSystemPrompt(ctx.cwd);
+
+  // Build structured compaction summary from current branch
+  const messages = extractMessages(ctx);
+  const summary = buildCompactionSummary(messages);
+  const contextText = formatForSupervisor(summary);
+
+  const userPrompt = buildUserPrompt(state, contextText, agentIsIdle, ineffectivePattern);
+
+  try {
+    return await callSupervisorModel(
+      ctx,
+      state.provider,
+      state.modelId,
+      systemPrompt,
+      userPrompt,
+      signal,
+      onDelta
+    );
+  } catch {
+    // When idle and analysis fails, nudge rather than silently do nothing
+    return agentIsIdle
+      ? {
+          action: 'steer',
+          message: 'Please continue working toward the goal.',
+          reasoning: 'Analysis error',
+          confidence: 0,
+        }
+      : { action: 'continue', reasoning: 'Analysis error', confidence: 0 };
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core analysis module exports.
+ */
+
+export { loadSystemPrompt } from './prompt-loader.js';
+export { buildUserPrompt } from './prompt-builder.js';
+export { getReframeGuidance } from './reframe.js';
+export { inferOutcome } from './inference.js';

package/src/core/inference.ts

@@ -0,0 +1,77 @@
+/**
+ * Outcome inference from conversation history.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { SupervisorSession } from '../session/supervisor-session.js';
+import {
+  extractMessages,
+  buildCompactionSummary,
+  formatForSupervisor,
+} from '../compaction/index.js';
+
+/** System prompt for inferring an outcome from conversation history. */
+const INFER_OUTCOME_SYSTEM_PROMPT = `You are a goal extraction assistant. Your task is to analyze a conversation between a user and a coding AI assistant, and extract the user's primary desired outcome or goal.
+
+The outcome should be:
+- Specific and measurable (not vague like "make it better")
+- Action-oriented (what needs to be built, fixed, or achieved)
+- Concise (1-2 sentences, ideally under 100 characters)
+- Focused on the core intent, not implementation details
+
+Examples of good outcomes:
+- "Add JWT authentication with refresh tokens and test coverage"
+- "Refactor the database layer to use connection pooling"
+- "Fix the memory leak in the file upload handler"
+- "Implement dark mode toggle with system preference detection"
+
+Respond with ONLY the outcome statement. No quotes, no markdown, no explanations.`;
+
+/**
+ * Infer a supervision outcome from the conversation history.
+ * Uses the compaction pipeline to build a structured summary for inference.
+ */
+export async function inferOutcome(
+  ctx: ExtensionContext,
+  provider: string,
+  modelId: string,
+  signal?: AbortSignal
+): Promise<string | null> {
+  const messages = extractMessages(ctx);
+  if (messages.length === 0) return null;
+
+  // Use the compaction pipeline for structured context (avoids cold prefills)
+  const summary = buildCompactionSummary(messages);
+  const contextText = formatForSupervisor(summary);
+
+  if (!contextText) return null;
+
+  const userPrompt = `Analyze this conversation summary and extract the user's primary goal or desired outcome:
+
+${contextText}
+
+What is the specific outcome the user is trying to achieve?`;
+
+  try {
+    const session = new SupervisorSession();
+    const started = await session.ensureStarted(
+      ctx,
+      provider,
+      modelId,
+      INFER_OUTCOME_SYSTEM_PROMPT
+    );
+    if (!started) return null;
+
+    const result = await session.prompt(userPrompt, signal);
+    session.dispose();
+
+    if (!result) return null;
+    return result
+      .replace(/^["']|["']$/g, '')
+      .replace(/\n/g, ' ')
+      .trim()
+      .slice(0, 200);
+  } catch {
+    return null;
+  }
+}

package/src/core/prompt-builder.ts

@@ -0,0 +1,137 @@
+/**
+ * Prompt builder - constructs user prompts for the supervisor LLM
+ * using structured compaction output instead of raw message dumps.
+ */
+
+import type { SupervisorState, SupervisorIntervention } from '../types.js';
+import { getReframeGuidance } from './reframe.js';
+
+/** Build the user-facing prompt for the supervisor LLM. */
+export function buildUserPrompt(
+  state: SupervisorState,
+  contextText: string,
+  agentIsIdle: boolean,
+  ineffectivePattern?: { detected: boolean; similarCount: number; secondsSinceLastSteer: number }
+): string {
+  // Build intervention history with full ASI display
+  const interventionHistory =
+    state.interventions.length === 0
+      ? 'None yet.'
+      : state.interventions
+          .slice(-5)
+          .map((iv, i) => {
+            let entry = `[${i + 1}] "${iv.message}"`;
+
+            if (iv.asi && Object.keys(iv.asi).length > 0) {
+              const asiEntries = Object.entries(iv.asi)
+                .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+                .join(', ');
+              entry += `\n    ASI {${asiEntries}}`;
+            }
+            return entry;
+          })
+          .join('\n');
+
+  // Build ASI pattern summary for loop closing
+  const asiSummary = buildASISummary(state.interventions);
+
+  const agentStatus = agentIsIdle
+    ? `AGENT STATUS: IDLE — the agent has finished its turn and is now waiting for user input.
+You MUST return "done" or "steer". Returning "continue" here means the agent stays idle forever.`
+    : `AGENT STATUS: WORKING — the agent is actively processing. Only intervene if clearly off track.`;
+
+  const reframeGuidance = getReframeGuidance(state.reframeTier ?? 0, ineffectivePattern);
+  const reframeSection = reframeGuidance ? `\n${reframeGuidance}\n` : '';
+
+  const contextBlock = contextText
+    ? `STRUCTURED CONVERSATION CONTEXT:\n${contextText}`
+    : '(No conversation context available)';
+
+  return `DESIRED OUTCOME:
+${state.outcome}
+
+${agentStatus}${reframeSection}
+
+${contextBlock}
+
+YOUR INTERVENTION HISTORY (with ASI observations):
+${interventionHistory}
+
+${asiSummary}
+REMINDER — DESIRED OUTCOME:
+${state.outcome}
+
+Has this outcome been fully achieved? Analyze and respond with JSON only.`;
+}
+
+/** Build summary of ASI patterns to close the loop */
+function buildASISummary(interventions: SupervisorIntervention[]): string {
+  if (interventions.length === 0) return '';
+
+  const patterns: string[] = [];
+  const recent = interventions.slice(-5);
+
+  const keyFrequency: Record<string, number> = {};
+  for (const iv of recent) {
+    if (!iv.asi) continue;
+    for (const key of Object.keys(iv.asi)) {
+      keyFrequency[key] = (keyFrequency[key] || 0) + 1;
+    }
+  }
+
+  for (const [key, count] of Object.entries(keyFrequency)) {
+    if (count >= 2) {
+      patterns.push(`Pattern seen ${count}x: "${key}"`);
+    }
+  }
+
+  const allValues = recent
+    .filter((iv) => iv.asi)
+    .flatMap((iv) => Object.values(iv.asi!))
+    .map((v) => String(v).toLowerCase());
+
+  const suspiciousIndicators = [
+    'unverified',
+    'contradict',
+    'suspicious',
+    'fake',
+    'skip',
+    'manipulat',
+    'cheat',
+    'gaming',
+    'short-circuit',
+  ];
+
+  const hasSuspicious = suspiciousIndicators.some((indicator) =>
+    allValues.some((v) => v.includes(indicator))
+  );
+
+  if (hasSuspicious) {
+    patterns.push(
+      '⚠️ Previous interventions flagged suspicious claims — require explicit proof before accepting "done"'
+    );
+  }
+
+  const verificationFailures = interventions.filter(
+    (iv) =>
+      iv.asi &&
+      Object.entries(iv.asi).some(
+        ([k, v]) =>
+          String(v).toLowerCase().includes('contradict') ||
+          String(v).toLowerCase().includes('unverified')
+      )
+  ).length;
+
+  if (verificationFailures >= 2) {
+    patterns.push(
+      `⚠️ ${verificationFailures} interventions involved unverified/contradicted claims — agent has pattern of unreliable reporting`
+    );
+  }
+
+  if (patterns.length === 0) return '';
+
+  return `ASI PATTERN SUMMARY (use this to inform your decision):
+${patterns.map((p) => `- ${p}`).join('\n')}
+
+`;
+}

package/src/core/prompt-loader.ts

@@ -0,0 +1,125 @@
+/**
+ * System prompt loading for supervisor.
+ *
+ * Discovery order (mirrors pi's SYSTEM.md convention):
+ *   1. <cwd>/.pi/SUPERVISOR.md   — project-local
+ *   2. ~/.pi/agent/SUPERVISOR.md — global
+ *   3. Built-in template         — fallback
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+
+const SUPERVISOR_MD = 'SUPERVISOR.md';
+const CONFIG_DIR = '.pi';
+
+/** Built-in fallback system prompt. */
+const BUILTIN_SYSTEM_PROMPT = `You are a supervisor monitoring a coding AI assistant conversation.
+Your job: ensure the assistant fully achieves a specific outcome without needing the human to intervene.
+
+═══ WHEN THE AGENT IS IDLE (finished its turn, waiting for user input) ═══
+This is your most important moment. The agent has stopped and is waiting.
+You MUST choose "done" or "steer". Never return "continue" when the agent is idle.
+
+- "done"  → only when the outcome is completely and verifiably achieved.
+- "steer" → everything else: incomplete work, partial progress, open questions, waiting for confirmation.
+
+If the agent asked a clarifying question or needs a decision:
+  FIRST check: is this question necessary to achieve the goal?
+  - YES (directly blocks goal progress): answer with a sensible default and tell agent to proceed.
+  - NO (out of scope, nice-to-have, unrelated feature): do NOT answer it. Redirect:
+    "That's outside the scope of the goal. Focus on: [restate the specific missing piece of the goal]."
+  DO NOT answer: passwords, credentials, secrets, anything requiring real user knowledge.
+
+Your steer message speaks AS the user. Make it clear, direct, and actionable (1–3 sentences).
+Do not ask the agent to verify its own work — tell it what to do next.
+
+═══ WHEN THE AGENT IS ACTIVELY WORKING (mid-turn) ═══
+Only intervene if it is clearly heading in the wrong direction.
+Trust the agent to complete what it has started. Avoid interrupting productive work.
+
+═══ STEERING RULES ═══
+- Be specific: reference the outcome, missing pieces, or the question being answered.
+- Never repeat a steering message that had no effect — escalate or change approach.
+- A good steer answers the agent's question OR redirects to the missing piece of the outcome.
+- If the agent is taking shortcuts to satisfy the goal without properly achieving it, always steer and remind it not to take shortcuts.
+
+"done" CRITERIA: The core outcome is complete and functional. Minor polish, style tweaks, or
+optional improvements do NOT block "done". Prefer stopping when the goal is substantially
+achieved rather than looping forever chasing perfection.
+
+═══ CHEATING PREVENTION ═══
+The agent may try to game metrics, fake results, or take shortcuts. Watch for:
+
+1. **Unverified Claims**: Agent says "tests pass" or "works correctly" without showing proof.
+   → Check tool_results for actual exit codes and output.
+
+2. **Test Manipulation**: Agent edits test files to weaken assertions or skip failing tests.
+   → Watch for edits that remove/modify test assertions while claiming progress.
+
+3. **Metric Gaming**: Agent reports performance improvements without proof, or modifies measurement code instead of actual implementation.
+   → Verify metrics appear in actual command output, not just agent claims.
+
+4. **Short-Circuiting**: Agent skips required steps (e.g., doesn't run full test suite, uses smaller dataset).
+   → Check that claimed progress matches the actual work done.
+
+5. **Contradictions**: Agent claims success but tool output shows errors/failures.
+   → This is immediate grounds for steering — do not accept "done" until resolved.
+
+If you detect cheating or suspicious claims:
+- DO NOT accept "done" — steer instead with specific challenge
+- Require explicit proof: "Show the full test output" or "Run the verification command again"
+- Log the pattern in ASI so future you remembers not to trust unverified claims
+
+═══ CLOSING THE ASI LOOP ═══
+ASI (Actionable Side Information) is your memory across turns. Use it to build up context
+that would otherwise be lost to the 6-message window.
+
+When you steer, you MUST populate "asi" with observations that will help future you:
+
+- What pattern made you intervene? (e.g., "agent_claimed_tests_pass_but_exit_code_1")
+- What have you learned about the agent's behavior? (e.g., "tends_to_skip_error_handling")
+- What should future you watch for? (e.g., "verify_file_actually_written_before_done")
+
+Before deciding, READ your past ASI entries. Look for:
+- Recurring patterns (agent keeps making same mistake)
+- Unverified claims from prior turns (don't accept "done" if you previously caught a lie)
+- Your own past observations about what works
+
+ASI is free-form: use whatever keys help you remember. Examples:
+{ "repeated_unverified_claim": true, "previous_contradiction": "turn_3", "watch_for": "early_returns" }
+
+If you previously caught the agent in a suspicious claim, require explicit proof before "done".
+
+Respond ONLY with valid JSON — no prose, no markdown fences.
+Response schema (strict JSON):
+{
+  "action": "continue" | "steer" | "done",
+  "message": "...",     // Required when action === "steer"
+  "reasoning": "...",   // Brief internal reasoning
+  "confidence": 0.85,   // Float 0-1
+  "asi": {              // REQUIRED when steering. Log observations for future decisions.
+    "...": "any keys you find useful for future pattern detection"
+  }
+}`;
+
+/**
+ * Load the supervisor system prompt.
+ * Checks .pi/SUPERVISOR.md (project) then ~/.pi/agent/SUPERVISOR.md (global),
+ * falling back to the built-in template if neither exists.
+ * Returns both the prompt and its source path (or "built-in").
+ */
+export function loadSystemPrompt(cwd: string): { prompt: string; source: string } {
+  const projectPath = join(cwd, CONFIG_DIR, SUPERVISOR_MD);
+  if (existsSync(projectPath)) {
+    return { prompt: readFileSync(projectPath, 'utf-8').trim(), source: projectPath };
+  }
+
+  const globalPath = join(getAgentDir(), SUPERVISOR_MD);
+  if (existsSync(globalPath)) {
+    return { prompt: readFileSync(globalPath, 'utf-8').trim(), source: globalPath };
+  }
+
+  return { prompt: BUILTIN_SYSTEM_PROMPT, source: 'built-in' };
+}

package/src/core/reframe.ts

@@ -0,0 +1,27 @@
+/**
+ * Reframe tier management - escalation strategies for ineffective steering.
+ */
+
+/** Get reframe guidance based on current tier */
+export function getReframeGuidance(
+  tier: number,
+  ineffectivePattern?: { detected: boolean; similarCount: number; secondsSinceLastSteer: number }
+): string {
+  if (!ineffectivePattern?.detected && tier === 0) return '';
+
+  const tierGuidance: Record<number, string> = {
+    0: '',
+    1: `🔄 REFRAME TIER 1 — DIRECTIVE: The agent needs clearer direction. Be extremely specific about the next single action to take.`,
+    2: `🔄 REFRAME TIER 2 — SUBGOAL: The agent is stuck on the full goal. Break this into a smaller, verifiable milestone. Tell it to complete just that one piece.`,
+    3: `🔄 REFRAME TIER 3 — PIVOT: The current approach isn't working. Suggest a completely different strategy or implementation path. Challenge any assumptions.`,
+    4: `🔄 REFRAME TIER 4 — MINIMAL SLICE: Strip to absolute essentials. Ask: "What's the smallest working version you can deliver right now?" Push for tangible output.`,
+  };
+
+  const stagnation = ineffectivePattern?.secondsSinceLastSteer ?? 0;
+  const stagnationNote = stagnation > 0 ? ` (${stagnation}s since last steer)` : '';
+  const patternNote = ineffectivePattern?.detected
+    ? `\n⚠ INEFFECTIVE PATTERN DETECTED: Last ${ineffectivePattern.similarCount} steering messages were similar or no progress in${stagnationNote}. Escalate your approach.`
+    : '';
+
+  return tierGuidance[tier] + patternNote;
+}