@polylogicai/polycode 1.1.0

package/lib/compiler.mjs

@@ -0,0 +1,166 @@
+// lib/compiler.mjs
+// Builds a bounded context window for the agent loop from the session log.
+// Two-phase: an optional high-quality model selects which log rows are most
+// relevant to the current turn, and a deterministic assembler composes them
+// into the final prompt. The prompt is then scrubbed for secrets before any
+// network call.
+//
+// polycode is inspired by Claude Code's public architecture at docs.claude.com.
+// polycode is not affiliated with Anthropic. No Claude Code code or system
+// prompts are copied. This file consumes the Anthropic Claude SDK as a paid
+// API client if an ANTHROPIC_API_KEY is available; otherwise it falls back to
+// a pure-Node selection path.
+
+import Anthropic from '@anthropic-ai/sdk';
+import { loadAnthropicKeys } from './inference-router.mjs';
+
+const COMPILER_MODEL = 'claude-haiku-4-5-20251001';
+const COMPILER_MAX_TOKENS = 600;
+const SUMMARY_ROW_LIMIT = 400;
+
+const COMPILER_SYSTEM_PROMPT = `You are a context selection helper. You receive a summary of a user's append-only session log (each row has an index, a type, and a short preview) and the user's current message. Your job is to return a JSON list of the row indices most relevant to the current message. You never write prose.
+
+Selection rules:
+- Prefer rows that reference entities, decisions, file paths, or numbers in the current message.
+- Prefer rows with VERIFIED outcome over REFUTED or PENDING.
+- Include the active intent row if it clarifies what the user is working on.
+- Cap your selection at 8 rows. Fewer is better.
+- If the current message asks about a specific prior turn or file, pull the rows that mention it directly.
+- Output JSON only, no prose, no backticks, no explanation. Schema: {"relevant_rows": [integer, ...]}.`;
+
+function buildCanonSummary(canon) {
+  const rows = [];
+  const all = canon.tail(SUMMARY_ROW_LIMIT);
+  for (const r of all) {
+    if (r.type === 'session_start' || r.type === 'session_end' || r.type === 'compile_result' || r.type === 'fidelity_check') continue;
+    const preview = r.type === 'witnessed_commitment'
+      ? `${r.payload?.verdict || '?'} ${String(r.payload?.claim || '').slice(0, 140)}`
+      : r.type === 'user_turn'
+        ? String(r.payload?.message || '').slice(0, 140)
+        : r.type === 'user_intent'
+          ? `intent: ${String(r.payload?.text || '').slice(0, 140)}`
+          : JSON.stringify(r.payload).slice(0, 140);
+    rows.push(`#${r.row_index} ${r.type}: ${preview}`);
+  }
+  return rows.join('\n');
+}
+
+async function selectRelevantRows(canon, userMessage) {
+  const keys = loadAnthropicKeys();
+  if (keys.length === 0) return { selected: null, usage: null, provider: null };
+
+  const summary = buildCanonSummary(canon);
+  const userContent = `Canon summary (${canon.size()} total rows; last ${Math.min(SUMMARY_ROW_LIMIT, canon.size())} shown):\n${summary}\n\nCurrent user message:\n${userMessage}\n\nOutput JSON only.`;
+
+  let lastError = null;
+  for (const { role, key } of keys) {
+    try {
+      const client = new Anthropic({ apiKey: key });
+      const response = await client.messages.create({
+        model: COMPILER_MODEL,
+        max_tokens: COMPILER_MAX_TOKENS,
+        system: COMPILER_SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: userContent }],
+      });
+      const text = response.content?.[0]?.text || '';
+      const match = text.match(/\{[\s\S]*?\}/);
+      if (match) {
+        try {
+          const parsed = JSON.parse(match[0]);
+          if (Array.isArray(parsed.relevant_rows)) {
+            return { selected: parsed.relevant_rows, usage: response.usage, provider: `anthropic-haiku-4.5:${role}` };
+          }
+        } catch {
+          // fall through to next key
+        }
+      }
+    } catch (err) {
+      lastError = err;
+    }
+  }
+
+  return { selected: null, usage: null, provider: null, error: lastError?.message || 'no anthropic key responded' };
+}
+
+export async function compilePacket(canon, userMessage, cwd) {
+  const selection = await selectRelevantRows(canon, userMessage);
+  const selectedIndices = new Set(selection.selected || []);
+
+  // Pure-Node Phase B: assemble the packet deterministically.
+  const intent = canon.activeIntent();
+  const rowsToInclude = [];
+
+  if (intent) rowsToInclude.push(intent);
+
+  const all = canon.tail(SUMMARY_ROW_LIMIT);
+  for (const r of all) {
+    if (selectedIndices.has(r.row_index)) rowsToInclude.push(r);
+  }
+
+  if (rowsToInclude.length <= (intent ? 1 : 0)) {
+    // Fallback: no LLM selection (key unavailable or parse failure). Use the last
+    // few canon rows by intent scope, same shape as the v1.0.0 pure-Node query.
+    const fallback = intent && intent.payload?.intent_id
+      ? canon.queryByIntent(intent.payload.intent_id, 10)
+      : canon.tail(6);
+    for (const r of fallback) {
+      if (r.type !== 'session_start' && r.type !== 'session_end') rowsToInclude.push(r);
+    }
+  }
+
+  const seen = new Set();
+  const uniqueRows = [];
+  for (const r of rowsToInclude) {
+    if (!seen.has(r.row_index)) {
+      seen.add(r.row_index);
+      uniqueRows.push(r);
+    }
+  }
+  uniqueRows.sort((a, b) => a.row_index - b.row_index);
+
+  const lines = [];
+  lines.push(`[polycode compile-packet · compiler: ${selection.provider || 'pure-node-fallback'}]`);
+  lines.push(`working_directory: ${cwd || process.cwd()}`);
+  lines.push(`canon_size: ${canon.size()} rows`);
+  lines.push(`canon_last_hash: ${canon.lastHash().slice(0, 16)}...`);
+
+  if (intent) {
+    lines.push('');
+    lines.push(`ACTIVE INTENT (${intent.payload.intent_id}):`);
+    lines.push(`  ${String(intent.payload.text || '').slice(0, 500)}`);
+  }
+
+  const nonIntentRows = uniqueRows.filter((r) => r.type !== 'user_intent');
+  if (nonIntentRows.length > 0) {
+    lines.push('');
+    lines.push(`SELECTED CANON ROWS (${nonIntentRows.length}, compiler-selected by relevance):`);
+    for (const r of nonIntentRows) {
+      const p = r.payload || {};
+      if (r.type === 'witnessed_commitment') {
+        const verdict = p.verdict || 'PENDING';
+        const claim = String(p.claim || '').slice(0, 280);
+        const tool = p.tool_name ? ` [tool=${p.tool_name}]` : '';
+        lines.push(`  #${r.row_index} [${verdict}]${tool} ${claim}`);
+        if (p.tool_result_snippet) {
+          lines.push(`      result: ${String(p.tool_result_snippet).slice(0, 160).replace(/\n/g, ' ')}`);
+        }
+      } else if (r.type === 'user_turn') {
+        lines.push(`  #${r.row_index} user: ${String(p.message || '').slice(0, 280)}`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('CURRENT USER MESSAGE:');
+  lines.push(userMessage);
+
+  const prompt = lines.join('\n');
+  return {
+    prompt,
+    estimatedTokens: Math.ceil(prompt.length / 4),
+    selectedRows: selection.selected || [],
+    compilerProvider: selection.provider || 'pure-node-fallback',
+    compilerUsage: selection.usage || null,
+    fallback: !selection.selected,
+  };
+}

package/lib/context-builder.mjs

@@ -0,0 +1,79 @@
+// lib/context-builder.mjs
+// The key invention: build a MINIMAL prompt from structural canon queries.
+// The model never sees the full history. It sees only:
+//   - Active intent (one row)
+//   - Last N user turns within active intent
+//   - Last N witnessed commitments within active intent
+//   - Current user message
+// The size of the resulting prompt is O(1) in the size of the canon, not O(N).
+// That is the architectural proof that agents do not need context windows that
+// grow with their history. State lives in the canon. The window stays bounded.
+//
+// This is what lets polycode operate indefinitely on a free 128k model while
+// remaining coherent across thousands of prior commitments.
+
+const DEFAULT_N_TURNS = 4;
+const DEFAULT_N_COMMITMENTS = 5;
+const MAX_TURN_SNIPPET_BYTES = 600;
+const MAX_COMMITMENT_SNIPPET_BYTES = 300;
+
+function truncate(str, n) {
+  const s = String(str || '');
+  if (s.length <= n) return s;
+  return s.slice(0, n) + '...';
+}
+
+export function buildContext(canon, userMessage, cwd) {
+  const intent = canon.activeIntent();
+  const intentId = intent?.payload?.intent_id || null;
+
+  const recentIntentRows = intentId ? canon.queryByIntent(intentId, 40) : [];
+  const recentTurns = recentIntentRows.filter((r) => r.type === 'user_turn').slice(-DEFAULT_N_TURNS);
+  const recentCommits = recentIntentRows.filter((r) => r.type === 'witnessed_commitment').slice(-DEFAULT_N_COMMITMENTS);
+
+  const lines = [];
+  lines.push(`[polycode structural canon query, not full history]`);
+  lines.push(`working_directory: ${cwd || process.cwd()}`);
+  lines.push(`canon_size: ${canon.size()} rows`);
+  lines.push(`canon_last_hash: ${canon.lastHash().slice(0, 16)}...`);
+
+  if (intent) {
+    lines.push('');
+    lines.push(`ACTIVE INTENT (${intent.payload.intent_id}):`);
+    lines.push(`  ${truncate(intent.payload.text, 400)}`);
+  }
+
+  if (recentTurns.length > 0) {
+    lines.push('');
+    lines.push(`RECENT USER TURNS within active intent (last ${recentTurns.length}):`);
+    for (const r of recentTurns) {
+      lines.push(`  - ${truncate(r.payload?.message, MAX_TURN_SNIPPET_BYTES)}`);
+    }
+  }
+
+  if (recentCommits.length > 0) {
+    lines.push('');
+    lines.push(`RECENT WITNESSED COMMITMENTS within active intent (last ${recentCommits.length}):`);
+    for (const r of recentCommits) {
+      const p = r.payload || {};
+      const claim = truncate(p.claim, MAX_COMMITMENT_SNIPPET_BYTES);
+      const verdict = p.verdict || 'PENDING';
+      lines.push(`  [${verdict}] ${claim}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('CURRENT USER MESSAGE:');
+  lines.push(userMessage);
+
+  const prompt = lines.join('\n');
+  const estimatedTokens = Math.ceil(prompt.length / 4);
+
+  return {
+    prompt,
+    estimatedTokens,
+    intentId,
+    nTurns: recentTurns.length,
+    nCommits: recentCommits.length,
+  };
+}

package/lib/hooks.mjs

@@ -0,0 +1,118 @@
+// lib/hooks.mjs
+// polycode hook executor. Matches the public Claude Code hook contract
+// published at docs.claude.com so hook scripts written for Claude Code run
+// unchanged in polycode. This is a compatibility affordance, not a code
+// dependency on Claude Code.
+//
+// Hook events (from the public spec):
+//   - SessionStart       (matchers: startup, resume, clear, compact)
+//   - UserPromptSubmit   (before the prompt is processed)
+//   - PreToolUse         (before tool execution; can block or modify)
+//   - PostToolUse        (after tool succeeds)
+//   - Stop               (turn complete)
+//   - PreCompact         (before context compaction)
+//   - SessionEnd         (session terminates)
+//   - SubagentStop       (subagent finished)
+//   - Notification       (alerts, permission prompts, idle prompts)
+//
+// Hook scripts live under POLYCODE_HOOK_DIR (default ~/.polycode/hooks/)
+// keyed by event name. They receive the event JSON on stdin and can
+// return JSON on stdout to block or modify the event.
+//
+// Example ~/.polycode/hooks/PreToolUse.sh:
+//   #!/bin/bash
+//   read -r event
+//   tool=$(echo "$event" | jq -r .tool_name)
+//   if [ "$tool" = "bash" ]; then
+//     # Block any bash call with "rm -rf"
+//     cmd=$(echo "$event" | jq -r .tool_input.command)
+//     if echo "$cmd" | grep -q "rm -rf"; then
+//       echo '{"action":"block","reason":"rm -rf is not allowed"}'
+//       exit 0
+//     fi
+//   fi
+//   echo '{"action":"allow"}'
+
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+const HOOK_EVENTS = new Set([
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'PreCompact',
+  'SessionEnd',
+  'SubagentStop',
+  'Notification',
+]);
+
+const HOOK_TIMEOUT_MS = 10_000;
+
+export async function fireHook(eventName, payload, hookDir) {
+  if (!HOOK_EVENTS.has(eventName)) {
+    return { action: 'allow', reason: 'unknown event' };
+  }
+  if (!hookDir || !existsSync(hookDir)) {
+    return { action: 'allow', reason: 'no hook dir' };
+  }
+
+  const candidates = [
+    join(hookDir, eventName),
+    join(hookDir, `${eventName}.sh`),
+    join(hookDir, `${eventName}.mjs`),
+    join(hookDir, `${eventName}.js`),
+  ];
+
+  const hookPath = candidates.find((p) => existsSync(p) && statSync(p).isFile());
+  if (!hookPath) return { action: 'allow', reason: 'no hook script' };
+
+  const isShell = hookPath.endsWith('.sh') || !hookPath.includes('.');
+  const isNode = hookPath.endsWith('.mjs') || hookPath.endsWith('.js');
+
+  return new Promise((resolveHook) => {
+    let child;
+    try {
+      child = isNode
+        ? spawn('node', [hookPath], { stdio: ['pipe', 'pipe', 'pipe'] })
+        : spawn('sh', [hookPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolveHook({ action: 'allow', reason: `spawn failed: ${err.message}` });
+      return;
+    }
+
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+    }, HOOK_TIMEOUT_MS);
+
+    child.stdout.on('data', (b) => { stdoutBuf += b.toString(); });
+    child.stderr.on('data', (b) => { stderrBuf += b.toString(); });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolveHook({ action: 'allow', reason: `hook exit ${code}: ${stderrBuf.slice(0, 200)}` });
+        return;
+      }
+      const trimmed = stdoutBuf.trim();
+      if (!trimmed) {
+        resolveHook({ action: 'allow' });
+        return;
+      }
+      try {
+        resolveHook(JSON.parse(trimmed));
+      } catch {
+        resolveHook({ action: 'allow', reason: 'hook output not JSON' });
+      }
+    });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}
+
+export { HOOK_EVENTS };

package/lib/inference-router.mjs

@@ -0,0 +1,67 @@
+// lib/inference-router.mjs
+// Provider key loader. Reads GROQ_API_KEY and optional ANTHROPIC_API_KEY from
+// environment variables or from ~/.polycode/secrets.env (chmod 600 recommended).
+// Keys are never logged, echoed, or written to any session log row.
+//
+// polycode is inspired by Claude Code's public architecture at docs.claude.com.
+// polycode is not affiliated with Anthropic. No Claude Code code or system
+// prompts are copied. Anthropic and Groq are consumed as paid API providers
+// under their public terms of service.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+let ANTHROPIC_KEYS_CACHE = null;
+
+function maskKey(k) {
+  if (!k || k.length < 20) return '[redacted]';
+  return k.slice(0, 10) + '...' + k.slice(-4);
+}
+
+export function loadAnthropicKeys() {
+  if (ANTHROPIC_KEYS_CACHE) return ANTHROPIC_KEYS_CACHE;
+
+  const seen = new Set();
+  const keys = [];
+
+  const secretsPath = join(homedir(), '.polycode', 'secrets.env');
+  if (existsSync(secretsPath)) {
+    try {
+      const content = readFileSync(secretsPath, 'utf8');
+      const primary = content.match(/^ANTHROPIC_API_KEY=(.+)$/m);
+      const backup = content.match(/^ANTHROPIC_API_KEY_BACKUP=(.+)$/m);
+      if (primary) {
+        const k = primary[1].trim().replace(/^['"]|['"]$/g, '');
+        if (!seen.has(k)) { seen.add(k); keys.push({ role: 'primary', key: k }); }
+      }
+      if (backup) {
+        const k = backup[1].trim().replace(/^['"]|['"]$/g, '');
+        if (!seen.has(k)) { seen.add(k); keys.push({ role: 'backup', key: k }); }
+      }
+    } catch {
+      // Ignore parse errors and fall through to environment.
+    }
+  }
+
+  if (process.env.ANTHROPIC_API_KEY && !seen.has(process.env.ANTHROPIC_API_KEY)) {
+    seen.add(process.env.ANTHROPIC_API_KEY);
+    keys.push({ role: 'env-primary', key: process.env.ANTHROPIC_API_KEY });
+  }
+  if (process.env.ANTHROPIC_API_KEY_BACKUP && !seen.has(process.env.ANTHROPIC_API_KEY_BACKUP)) {
+    seen.add(process.env.ANTHROPIC_API_KEY_BACKUP);
+    keys.push({ role: 'env-backup', key: process.env.ANTHROPIC_API_KEY_BACKUP });
+  }
+
+  ANTHROPIC_KEYS_CACHE = keys;
+  return keys;
+}
+
+export function anthropicAvailable() {
+  return loadAnthropicKeys().length > 0;
+}
+
+export function reportKeyStatus() {
+  const keys = loadAnthropicKeys();
+  return keys.map((k) => ({ role: k.role, masked: maskKey(k.key) }));
+}

package/lib/intent.mjs

@@ -0,0 +1,31 @@
+// lib/intent.mjs
+// The Intent plane. Every turn operates within an ACTIVE INTENT, which is a
+// canon row of type 'user_intent' that references the user's goal for the
+// current stretch of turns. The context builder uses the active intent_id to
+// structurally scope canon queries. This is how polycode stays coherent
+// without holding full history in the model's context window.
+
+export function ensureActiveIntent(canon, userMessage) {
+  const active = canon.activeIntent();
+  if (active) return active;
+  const intentId = `intent_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  return canon.append('user_intent', {
+    intent_id: intentId,
+    text: userMessage,
+    created_at: new Date().toISOString(),
+  });
+}
+
+export function rotateIntent(canon, newIntentText) {
+  const intentId = `intent_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  return canon.append('user_intent', {
+    intent_id: intentId,
+    text: newIntentText,
+    created_at: new Date().toISOString(),
+  });
+}
+
+export function currentIntentId(canon) {
+  const active = canon.activeIntent();
+  return active?.payload?.intent_id || null;
+}

package/lib/repl-ui.mjs

@@ -0,0 +1,91 @@
+// lib/repl-ui.mjs
+// Streaming terminal UI with ANSI colors. Zero external deps.
+// The renderer subscribes to events emitted by AgenticLoop.runTurn() and
+// prints each phase with a colored prefix. The verdict pill is rendered
+// when a commitment is recorded.
+
+export const C = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  amber: '\x1b[38;5;214m',
+  gold: '\x1b[38;5;220m',
+  lightAmber: '\x1b[38;5;221m',
+  coolBlue: '\x1b[38;5;74m',
+  coral: '\x1b[38;5;209m',
+  darkMaroon: '\x1b[38;5;88m',
+  navy: '\x1b[38;5;24m',
+  gray: '\x1b[38;5;244m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+function verdictColor(v) {
+  return {
+    VERIFIED: C.amber,
+    SURVIVED: C.lightAmber,
+    PENDING: C.coolBlue,
+    CHALLENGED: C.coral,
+    REFUTED: C.darkMaroon,
+  }[v] || C.gray;
+}
+
+export function verdictPill(v) {
+  return `${verdictColor(v)}[${v}]${C.reset}`;
+}
+
+function phasePrefix(name) {
+  const map = {
+    intent: `${C.amber}. intent${C.reset}`,
+    ground: `${C.lightAmber}. ground${C.reset}`,
+    ground_complete: `${C.lightAmber}. ground${C.reset}`,
+    scrub_blocked: `${C.red}. scrub${C.reset}`,
+    dispatch: `${C.coolBlue}. dispatch${C.reset}`,
+    act: `${C.navy}. act${C.reset}`,
+    record: `${C.gold}. record${C.reset}`,
+    fallback: `${C.gray}. fallback${C.reset}`,
+    error: `${C.red}. error${C.reset}`,
+  };
+  return map[name] || `${C.gray}. ${name}${C.reset}`;
+}
+
+export function createRenderer(stdout) {
+  function line(s) { stdout.write(s + '\n'); }
+
+  function onEvent(ev) {
+    if (ev.phase === 'intent') {
+      line(`${phasePrefix('intent')} ${C.dim}active intent resolved${C.reset}`);
+    } else if (ev.phase === 'ground_complete') {
+      const compiler = ev.compilerProvider || 'pure-node';
+      const rows = ev.selectedRows || 0;
+      const fallback = ev.fallback ? ' (fallback)' : '';
+      line(`${phasePrefix('ground')} ${C.dim}compile-packet: ~${ev.estimatedTokens} tokens . ${compiler}${fallback} . ${rows} rows selected${C.reset}`);
+    } else if (ev.phase === 'scrub_blocked') {
+      line(`${phasePrefix('scrub_blocked')} ${C.red}secret bleed blocked: ${(ev.findings || []).map((f) => f.pattern).join(', ')}${C.reset}`);
+    } else if (ev.phase === 'dispatch') {
+      line(`${phasePrefix('dispatch')} ${C.dim}iteration ${ev.iteration}${C.reset}`);
+    } else if (ev.phase === 'fallback') {
+      line(`${phasePrefix('fallback')} ${C.dim}${ev.to}: ${String(ev.reason || '').slice(0, 80)}${C.reset}`);
+    } else if (ev.phase === 'act' && ev.kind === 'message') {
+      const content = String(ev.content || '').trim();
+      if (content) line(`${C.cyan}${content}${C.reset}`);
+    } else if (ev.phase === 'act' && ev.kind === 'tool_call') {
+      const preview = JSON.stringify(ev.args || {}).slice(0, 140);
+      line(`${phasePrefix('act')} ${C.bold}${ev.name}${C.reset}(${C.dim}${preview}${C.reset})`);
+    } else if (ev.phase === 'act' && ev.kind === 'tool_result') {
+      const preview = String(ev.result || '').slice(0, 200).replace(/\n/g, ' ');
+      line(`${phasePrefix('act')} ${C.dim}-> ${preview}${C.reset}`);
+    } else if (ev.phase === 'record') {
+      const c = ev.commitment;
+      const pill = verdictPill(c.verdict);
+      const hash = c.row?.row_hash?.slice(0, 8) || '????????';
+      const delta = c.trustDelta >= 0 ? `+${c.trustDelta}` : `${c.trustDelta}`;
+      line(`${phasePrefix('record')} ${pill} ${C.dim}block #${hash} . delta_N=${delta}${C.reset}`);
+    } else if (ev.phase === 'error') {
+      line(`${phasePrefix('error')} ${C.red}${ev.message}${C.reset}`);
+    }
+  }
+
+  return { onEvent, C, verdictPill };
+}

package/lib/slash-commands.mjs

@@ -0,0 +1,83 @@
+// lib/slash-commands.mjs
+// Slash command dispatcher for the interactive REPL. Each command is a pure
+// function over (canon, args, state, stdout). The dispatcher returns either
+// {continue: true} or {exit: true}.
+
+import { C } from './repl-ui.mjs';
+import { rotateIntent } from './intent.mjs';
+
+export const SLASH_HELP = `
+${C.bold}polycode commands${C.reset}
+  /help                       Show this help
+  /log                        Show session log path, row count, and last hash
+  /replay <n>                 Print the last N session log rows
+  /verify                     Verify session log SHA-256 chain integrity
+  /intent                     Show the active intent
+  /intent <text>              Set a new active intent
+  /clear                      Clear the screen (session log is untouched)
+  /exit, /quit                Leave polycode
+`;
+
+export async function dispatchSlash(line, { canon, state, stdout }) {
+  const [cmd, ...rest] = line.slice(1).split(/\s+/);
+  const args = rest.join(' ');
+
+  switch (cmd) {
+    case 'help':
+      stdout.write(SLASH_HELP + '\n');
+      return { continue: true };
+
+    case 'log':
+    case 'history':
+    case 'canon': {
+      stdout.write(`${C.amber}session log${C.reset}: ${canon.size()} rows, last ${canon.lastHash().slice(0, 16)}...\n`);
+      stdout.write(`${C.dim}path: ${canon.path}${C.reset}\n`);
+      return { continue: true };
+    }
+
+    case 'intent': {
+      if (!args) {
+        const cur = canon.activeIntent();
+        if (cur) stdout.write(`${C.amber}active intent${C.reset}: ${cur.payload.text}\n`);
+        else stdout.write(`${C.dim}no active intent${C.reset}\n`);
+        return { continue: true };
+      }
+      const row = rotateIntent(canon, args);
+      stdout.write(`${C.amber}intent set${C.reset}: ${row.payload.intent_id}\n`);
+      return { continue: true };
+    }
+
+    case 'replay': {
+      const n = Number(args) || 5;
+      const rows = canon.tail(n);
+      for (const r of rows) {
+        const kind = r.type.padEnd(22);
+        const snippet = JSON.stringify(r.payload).slice(0, 140);
+        stdout.write(`${C.dim}#${r.row_index} ${kind} ${snippet}${C.reset}\n`);
+      }
+      return { continue: true };
+    }
+
+    case 'verify': {
+      const r = canon.verify();
+      if (r.valid) {
+        stdout.write(`${C.amber}session log verified${C.reset}: ${r.rows} rows, last ${r.last_hash.slice(0, 16)}...\n`);
+      } else {
+        stdout.write(`${C.red}session log broken${C.reset}: ${r.reason}\n`);
+      }
+      return { continue: true };
+    }
+
+    case 'clear':
+      stdout.write('\x1b[2J\x1b[H');
+      return { continue: true };
+
+    case 'exit':
+    case 'quit':
+      return { exit: true };
+
+    default:
+      stdout.write(`${C.red}unknown command${C.reset}: /${cmd}. Type /help for commands.\n`);
+      return { continue: true };
+  }
+}