subrouter-cli 0.0.0-stage → 0.1.0

package/src/loop.ts

@@ -0,0 +1,201 @@
+// loop.ts — the agent round driver: stream a turn, run tool calls with the permission
+// gate, feed results back, repeat. Dialect-agnostic: it only speaks ChatRequest /
+// AssistantTurn / StreamEvent and an injectable tool executor.
+
+import { dialectFor } from './client.ts';
+import type { EffortLevel } from './effort.ts';
+import { checkBudget, estimateTotal } from './token.ts';
+import type { ChatMessage, ChatRequest, StopReason, StreamEvent, TokenUsage, ToolCall, ToolDefinition, AssistantTurn } from './types.ts';
+
+/** The slice of RouterClient the loop needs — fakes implement this in tests. */
+export interface ChatClient {
+  chat(req: ChatRequest, onEvent: (e: StreamEvent) => void, signal?: AbortSignal): Promise<AssistantTurn>;
+}
+
+export type Approval = 'yes' | 'all' | 'no';
+export type ToolProgressPhase = 'start' | 'running' | 'done' | 'error' | 'denied';
+
+export interface ToolResult {
+  toolCallId: string;
+  content: string;
+  isError?: boolean;
+}
+
+export interface LoopOptions {
+  client: ChatClient;
+  model: string;
+  /** Owned by the caller; the user message must already be appended. */
+  history: ChatMessage[];
+  system: string;
+  tools: ToolDefinition[];
+  execute: (call: ToolCall, signal?: AbortSignal) => Promise<ToolResult>;
+  ask: (call: ToolCall) => Promise<Approval>;
+  autoApprove: boolean;
+  /** Live file permission state; takes precedence over the turn-local approve-all latch. */
+  fileApproval?: () => boolean;
+  maxRounds: number;
+  maxTokens: number;
+  effort?: EffortLevel;
+  /** Model context window for 80%/95% budget warnings; warnings are skipped when absent. */
+  contextTokens?: number;
+  /** Exact token counter (anthropic count_tokens); falls back to the estimate on failure. */
+  countTokens?: (model: string, system: string, messages: ChatMessage[], tools?: ToolDefinition[]) => Promise<number>;
+  signal: AbortSignal;
+  onEvent: (e: StreamEvent) => void;
+  onToolProgress?: (phase: ToolProgressPhase, call: ToolCall, note?: string) => void;
+  onBudget?: (percent: 80 | 95) => void;
+  /** Drain queued user steering only at safe boundaries, never between tool calls/results. */
+  takeSteering?: () => ChatMessage[];
+}
+
+export interface TurnResult {
+  stopReason: StopReason;
+  usage?: TokenUsage;
+  rounds: number;
+}
+
+function abortError(): Error {
+  return new DOMException('The operation was aborted', 'AbortError');
+}
+
+function denialResult(call: ToolCall): ToolResult {
+  return { toolCallId: call.id, content: JSON.stringify({ error: 'Tool call denied by user' }), isError: true };
+}
+
+function budgetTexts(system: string, history: ChatMessage[], tools: ToolDefinition[]): string[] {
+  const texts = [system];
+  for (const m of history) {
+    texts.push(m.content);
+    for (const c of m.toolCalls ?? []) texts.push(c.name + c.argumentsJson);
+  }
+  for (const t of tools) texts.push(t.name + t.description + JSON.stringify(t.parameters));
+  return texts;
+}
+
+export async function runAgentTurn(opts: LoopOptions): Promise<TurnResult> {
+  const dialect = dialectFor(opts.model);
+  const toolByDef = new Map(opts.tools.map((t) => [t.name, t]));
+  let approveAll = opts.autoApprove;
+  let rounds = 0;
+  let warned80 = false;
+  let warned95 = false;
+  let exactFailed = false;
+  let usage: TokenUsage | undefined;
+  const applySteering = (): boolean => {
+    const messages = opts.takeSteering?.() ?? [];
+    opts.history.push(...messages);
+    return messages.length > 0;
+  };
+
+  while (rounds < opts.maxRounds) {
+    if (opts.signal.aborted) throw abortError();
+    applySteering();
+    if (opts.contextTokens && opts.onBudget) {
+      const texts = budgetTexts(opts.system, opts.history, opts.tools);
+      // Rough fallback only: image tokens vary by provider/resolution, not base64 length.
+      const imageAllowance = opts.history.reduce((total, m) => total + (m.role === 'user' ? m.images?.length ?? 0 : 0), 0) * 2048;
+      let total = estimateTotal(texts) + imageAllowance;
+      if (opts.countTokens && !exactFailed) {
+        try {
+          total = await opts.countTokens(opts.model, opts.system, opts.history, opts.tools);
+        } catch {
+          exactFailed = true; // advisory — fall back to the estimate, never retry per turn
+        }
+      }
+      const budget = checkBudget(total, opts.contextTokens);
+      if (budget.warn95 && !warned95) {
+        warned95 = true;
+        warned80 = true;
+        opts.onBudget(95);
+      } else if (budget.warn80 && !warned80) {
+        warned80 = true;
+        opts.onBudget(80);
+      }
+    }
+
+    const req: ChatRequest = {
+      model: opts.model,
+      dialect,
+      messages: [...opts.history], // snapshot — history grows as the round completes
+      system: opts.system,
+      tools: opts.tools,
+      stream: true,
+      maxTokens: opts.maxTokens,
+      effort: opts.effort,
+    };
+    const turn = await opts.client.chat(req, opts.onEvent, opts.signal);
+    if (turn.usage) {
+      usage = {
+        inputTokens: (usage?.inputTokens ?? 0) + turn.usage.inputTokens,
+        outputTokens: (usage?.outputTokens ?? 0) + turn.usage.outputTokens,
+      };
+    }
+    opts.history.push(turn.message);
+
+    const calls = turn.message.toolCalls ?? [];
+    if (turn.stopReason !== 'tool_calls' || calls.length === 0) {
+      if (opts.signal.aborted) throw abortError();
+      if (applySteering()) continue; // a final answer may have received steering while streaming
+      return { stopReason: turn.stopReason, usage, rounds };
+    }
+    rounds++;
+    // File approve-all never authorizes an always-scoped terminal command.
+    const denied = new Set<number>();
+    const beforeExecution: (ToolResult | undefined)[] = [];
+    const cancelled = (call: ToolCall): ToolResult => ({
+      toolCallId: call.id, content: JSON.stringify({ error: 'Tool call cancelled before execution' }), isError: true,
+    });
+    for (const [i, call] of calls.entries()) {
+      if (opts.signal.aborted) { beforeExecution[i] = cancelled(call); continue; }
+      if (call.argumentsInvalid) {
+        beforeExecution[i] = { toolCallId: call.id, content: 'invalid tool arguments', isError: true };
+        continue;
+      }
+      const def = toolByDef.get(call.name);
+      const always = def?.approvalScope === 'always';
+      if (!def?.requiresApproval || (!always && (opts.fileApproval?.() ?? approveAll))) continue;
+      try {
+        const answer = await opts.ask(call);
+        if (opts.signal.aborted) { beforeExecution[i] = cancelled(call); continue; }
+        if (always ? answer !== 'yes' : answer === 'no') {
+          denied.add(i);
+          beforeExecution[i] = denialResult(call);
+        } else if (!always && answer === 'all') {
+          approveAll = true;
+        }
+      } catch (err) {
+        beforeExecution[i] = opts.signal.aborted ? cancelled(call) : {
+          toolCallId: call.id, content: err instanceof Error ? err.message : 'tool approval failed', isError: true,
+        };
+      }
+    }
+
+    for (const call of calls) if (!opts.signal.aborted) opts.onToolProgress?.('start', call);
+    const results = await Promise.all(calls.map(async (call, i) => {
+      if (beforeExecution[i]) return beforeExecution[i]!;
+      if (opts.signal.aborted) return cancelled(call);
+      try { return await opts.execute(call, opts.signal); }
+      catch (err) {
+        return { toolCallId: call.id, content: err instanceof Error ? err.message : 'tool execution failed', isError: true };
+      }
+    }));
+    // Pair every recorded call before propagating abort, including approval cancellation.
+    for (const [i, result] of results.entries()) {
+      const call = calls[i];
+      opts.history.push({
+        role: 'tool',
+        content: result.content,
+        toolCallId: call.id,
+        isError: result.isError,
+      });
+      opts.onToolProgress?.(denied.has(i) ? 'denied' : result.isError ? 'error' : 'done', call, result.isError ? result.content : undefined);
+    }
+    if (opts.signal.aborted) throw abortError();
+  }
+
+  opts.history.push({
+    role: 'assistant',
+    content: '(stopped after too many tool calls)',
+  });
+  return { stopReason: 'length', usage, rounds };
+}

package/src/markdown.ts

@@ -0,0 +1,244 @@
+// markdown.ts — a minimal, dependency-free markdown renderer for the terminal. Streams
+// incrementally (the REPL) or renders a whole string at once (one-shot). Code spans/blocks
+// use the blue accent, headings are violet, list markers are blue, blockquotes are dim.
+// Italic is deliberately unsupported: `*`/`_` collide with identifiers and arithmetic.
+
+import { ui, accent, violet, green, bold, dim } from './ui.ts';
+
+const FENCE = /^\s*([`~]{3,})/;
+const CLOSE_FENCE = /^\s*[`~]{3,}\s*$/;
+
+/** Inline spans within a non-code line: `code`, **bold**, [text](url). Single-pass so
+ *  code spans are never re-interpreted by the later bold/link rules. */
+function renderInline(line: string): string {
+  let out = '';
+  let i = 0;
+  while (i < line.length) {
+    const c = line[i];
+    if (c === '`') {
+      const end = line.indexOf('`', i + 1);
+      if (end !== -1) {
+        out += accent(line.slice(i + 1, end));
+        i = end + 1;
+        continue;
+      }
+    }
+    if (c === '*' && line[i + 1] === '*') {
+      const end = line.indexOf('**', i + 2);
+      if (end !== -1) {
+        out += bold(renderInline(line.slice(i + 2, end)));
+        i = end + 2;
+        continue;
+      }
+    }
+    if (c === '[') {
+      const m = /^\[([^\]]+)\]\(([^)\s]+)\)/.exec(line.slice(i));
+      if (m) {
+        out += accent(m[1]); // drop the URL — it is rarely readable in a terminal
+        i += m[0].length;
+        continue;
+      }
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** One non-code line: headings, blockquotes, task/bullet/numbered lists, else inline. */
+function renderLine(line: string): string {
+  const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+  if (heading) return violet(bold(line));
+  if (/^\s*>\s?/.test(line)) return dim(line);
+  const task = /^(\s*)[-*+]\s+\[([ xX])\]\s+(.*)$/.exec(line);
+  if (task) {
+    const box = task[2].toLowerCase() === 'x' ? '☒' : '☐';
+    return task[1] + (box === '☒' ? green(box + ' ') : accent(box + ' ')) + renderInline(task[3]);
+  }
+  const bullet = /^(\s*)([-*+])\s+(.*)$/.exec(line);
+  if (bullet) return bullet[1] + accent(bullet[2] + ' ') + renderInline(bullet[3]);
+  const num = /^(\s*)(\d+)([.)])\s+(.*)$/.exec(line);
+  if (num) return num[1] + accent(num[2] + num[3] + ' ') + renderInline(num[4]);
+  return renderInline(line);
+}
+
+/** Render a whole markdown string to ANSI (the non-streaming one-shot path). */
+export function renderMarkdown(text: string): string {
+  const out: string[] = [];
+  let fence: string | null = null;
+  for (const line of text.split('\n')) {
+    const open = FENCE.exec(line);
+    if (fence) {
+      if (open && open[1][0] === fence && CLOSE_FENCE.test(line)) {
+        fence = null;
+        out.push(dim(line));
+      } else {
+        out.push(accent(line));
+      }
+      continue;
+    }
+    if (open) {
+      fence = open[1][0];
+      out.push(dim(line));
+      continue;
+    }
+    out.push(renderLine(line));
+  }
+  return out.join('\n');
+}
+
+/**
+ * Append-only streaming renderer. Only ambiguous Markdown prefixes/tokens are held;
+ * ordinary text and opened bold/code spans are visible before a newline arrives.
+ * Styles are self-contained per chunk, so UI updates cannot inherit an open ANSI style.
+ * Unclosed inline delimiters style through the end of their line; no cursor rewrites.
+ */
+export class MarkdownStream {
+  private pending = '';
+  private fence: string | null = null;
+  private mode: 'plain' | 'heading' | 'quote' | 'code' | 'fence' | null = null;
+  private inBold = false;
+  private inCode = false;
+  private started = false;
+  private blankLine = false;
+
+  write(text: string): void {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const complete = i < lines.length - 1;
+      this.pending += lines[i];
+      this.drain(complete);
+      if (complete) {
+        if (this.mode !== null) ui.say(''); // finish the already streamed logical line
+        else this.blankLine = this.started; // defer/drop prose blank gaps
+        this.resetLine();
+      }
+    }
+  }
+
+  flush(): void {
+    if (this.pending || this.mode !== null) this.drain(true);
+    this.resetLine(); // ui.endTurn() owns the final newline
+    this.blankLine = false;
+  }
+
+  private resetLine(): void {
+    this.pending = '';
+    this.mode = null;
+    this.inBold = false;
+    this.inCode = false;
+  }
+
+  private emit(text: string): void {
+    if (!text) return;
+    if (this.blankLine) ui.say('');
+    this.blankLine = false;
+    this.started = true;
+    ui.streamText(text);
+  }
+
+  private drain(final: boolean): void {
+    if (this.mode === null && !this.prefix(final)) return;
+    if (this.mode !== 'plain') {
+      const text = this.pending;
+      this.pending = '';
+      if (!text) return;
+      if (this.mode === 'heading') this.emit(violet(bold(text)));
+      else if (this.mode === 'code') this.emit(accent(text));
+      else this.emit(dim(text));
+      return;
+    }
+
+    let out = '';
+    let i = 0;
+    const style = (text: string): string => {
+      if (this.inCode) text = accent(text);
+      return this.inBold ? bold(text) : text;
+    };
+    while (i < this.pending.length) {
+      const rest = this.pending.slice(i);
+      if (rest[0] === '`') {
+        this.inCode = !this.inCode;
+        i++;
+      } else if (!this.inCode && rest[0] === '*') {
+        if (rest.length === 1 && !final) break; // possibly half of **
+        if (rest.startsWith('**')) {
+          this.inBold = !this.inBold;
+          i += 2;
+        } else {
+          out += style('*');
+          i++;
+        }
+      } else if (!this.inCode && rest[0] === '[') {
+        const link = /^\[([^\]]+)\]\(([^)\s]+)\)/.exec(rest);
+        if (link) {
+          out += style(accent(link[1]));
+          i += link[0].length;
+        } else {
+          // A bounded lookahead keeps links intact without buffering an entire reply
+          // that merely contains an unmatched '['. Later Markdown still gets styled.
+          const possible = /^\[[^\]]*$/.test(rest) || /^\[[^\]]+\](?:\([^\s)]*)?$/.test(rest);
+          if (!final && possible && rest.length < 256) break;
+          out += style('[');
+          i++;
+        }
+      } else {
+        const run = /^[^`*\[]+/.exec(rest);
+        const text = run ? run[0] : rest[0];
+        out += style(text);
+        i += text.length;
+      }
+    }
+    this.pending = this.pending.slice(i);
+    this.emit(out);
+  }
+
+  /** Decide the line style once, holding only prefixes that could change its meaning. */
+  private prefix(final: boolean): boolean {
+    const text = this.pending;
+    const open = FENCE.exec(text);
+    if (this.fence) {
+      if (open && open[1][0] === this.fence && CLOSE_FENCE.test(text)) {
+        if (!final) return false; // a closing fence might still acquire code text
+        this.fence = null;
+        this.mode = 'fence';
+      } else {
+        if (!final && /^\s*([`~]{0,2})$/.test(text)) return false;
+        this.mode = 'code';
+      }
+      return true;
+    }
+    if (!text.trim()) return false; // prose whitespace is deferred until content exists
+    if (open) {
+      this.fence = open[1][0];
+      this.mode = 'fence';
+      return true;
+    }
+    if (/^#{1,6}\s/.test(text)) this.mode = 'heading';
+    else if (/^\s*>/.test(text)) this.mode = 'quote';
+    else {
+      const bullet = /^(\s*)([-*+])\s+/.exec(text);
+      const numbered = /^(\s*)(\d+[.)])\s+/.exec(text);
+      if (bullet) {
+        const rest = text.slice(bullet[0].length);
+        if (!final && text.length < 256 && /^(?:|\[|\[[ xX]|\[[ xX]\])$/.test(rest)) return false;
+        const task = /^\[([ xX])\]\s+/.exec(rest);
+        if (task) {
+          const box = task[1].toLowerCase() === 'x' ? '☒ ' : '☐ ';
+          this.emit(bullet[1] + (task[1].toLowerCase() === 'x' ? green(box) : accent(box)));
+          this.pending = rest.slice(task[0].length);
+        } else {
+          this.emit(bullet[1] + accent(bullet[2] + ' '));
+          this.pending = rest;
+        }
+      } else if (numbered) {
+        this.emit(numbered[1] + accent(numbered[2] + ' '));
+        this.pending = text.slice(numbered[0].length);
+      } else if (!final && text.length < 256 && /^(?:\s*[`~]{1,2}|#{1,6}|\s*[-*+]|\s*\d+[.)]?)$/.test(text)) {
+        return false;
+      }
+      this.mode = 'plain';
+    }
+    return true;
+  }
+}