subrouter-cli 0.0.0-stage → 0.1.0

package/src/sessions.ts

@@ -0,0 +1,58 @@
+// sessions.ts — append-only session transcripts under ~/.config/subrouter-cli/sessions/.
+// A markdown log for humans plus a JSONL transcript (one line per completed turn) shaped
+// for a future --resume. Message content goes to files only, never stdout/stderr.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir } from './config.ts';
+import type { ChatMessage, StopReason, TokenUsage } from './types.ts';
+
+export interface Session {
+  id: string;
+  mdPath: string;
+  jsonlPath: string;
+}
+
+export function sessionsDir(): string {
+  return path.join(configDir(), 'sessions');
+}
+
+function stamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+/** Create a new session transcript (files are chmod 600 like the config). */
+export function startSession(dir = sessionsDir()): Session {
+  fs.mkdirSync(dir, { recursive: true });
+  const id = `sess-${stamp()}`;
+  const session: Session = {
+    id,
+    mdPath: path.join(dir, `${id}.md`),
+    jsonlPath: path.join(dir, `${id}.jsonl`),
+  };
+  fs.appendFileSync(session.mdPath, `# sub session ${id}\n\nstarted: ${new Date().toISOString()}\n\n`);
+  fs.appendFileSync(session.jsonlPath, '');
+  fs.chmodSync(session.mdPath, 0o600);
+  fs.chmodSync(session.jsonlPath, 0o600);
+  return session;
+}
+
+/** Append a markdown block to the session log. */
+export function appendMarkdown(session: Session, block: string): void {
+  fs.appendFileSync(session.mdPath, block + '\n');
+}
+
+export interface TurnRecord {
+  type: 'turn';
+  ts: string;
+  model: string;
+  stopReason: StopReason;
+  rounds: number;
+  usage?: TokenUsage;
+  messages: ChatMessage[];
+}
+
+/** Append one JSON record to the transcript (one line per record). */
+export function appendRecord(session: Session, record: unknown): void {
+  fs.appendFileSync(session.jsonlPath, JSON.stringify(record) + '\n');
+}

package/src/sse.ts

@@ -0,0 +1,64 @@
+// Dialect-blind SSE frame parser over a fetch body stream.
+// Handles lines split across chunk boundaries, multi-line data, event: names, and
+// CRLF endings. [DONE] and message_stop are handled by the callers/adapters.
+
+export interface SseFrame {
+  data: string;
+  event?: string;
+}
+
+export async function* sseFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<SseFrame, void, unknown> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let pending = '';
+  let dataParts: string[] = [];
+  let eventName: string | undefined;
+
+  const finishFrame = (): SseFrame | null => {
+    if (dataParts.length === 0) return null;
+    const frame: SseFrame = { data: dataParts.join('\n') };
+    if (eventName) frame.event = eventName;
+    dataParts = [];
+    eventName = undefined;
+    return frame;
+  };
+
+  // One complete line. Returns a finished frame, or null.
+  const processLine = (line: string): SseFrame | null => {
+    if (line.startsWith('data:')) {
+      const payload = line.slice(5).trimStart().replace(/\r$/, '');
+      if (payload) dataParts.push(payload); // empty payloads are heartbeats — skip
+      return null;
+    }
+    if (line.startsWith('event:')) {
+      eventName = line.slice(6).trim();
+      return null;
+    }
+    if (line === '' || line === '\r') {
+      return finishFrame(); // only a truly blank line terminates a frame
+    }
+    return null; // comments (": keepalive") and id:/retry: fields are ignored
+  };
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      pending += decoder.decode(value, { stream: !done });
+      const lines = pending.split('\n');
+      if (done) {
+        pending = ''; // every line is complete at EOF
+      } else {
+        pending = lines.pop() ?? ''; // keep the trailing partial line
+      }
+      for (const line of lines) {
+        const frame = processLine(line);
+        if (frame) yield frame;
+      }
+      if (done) break;
+    }
+    const leftover = finishFrame(); // a final data line with no blank terminator
+    if (leftover) yield leftover;
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/terminal.ts

@@ -0,0 +1,228 @@
+import { spawn } from 'node:child_process';
+import { stripVTControlCharacters } from 'node:util';
+
+export const MAX_COMMAND_BYTES = 16 * 1024;
+export const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+export const MAX_COMMAND_TIMEOUT_MS = 300_000;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const KILL_GRACE_MS = 200;
+
+export interface CommandResult {
+  status: 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'output_limit' | 'spawn_error';
+  exit_code: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+  truncated: boolean;
+}
+
+export function validateCommand(command: unknown, timeoutMs: unknown, redactValues: string[] = []): { command: string; timeoutMs: number } {
+  if (typeof command !== 'string' || !command.trim() || command.includes('\0')) {
+    throw new Error('Command must be a nonblank string without NUL characters.');
+  }
+  if (Buffer.byteLength(command, 'utf8') > MAX_COMMAND_BYTES) throw new Error('Command exceeds the 16 KiB limit.');
+  if (redactValues.some(value => value.length > 0 && command.includes(value))) {
+    throw new Error('Command contains a protected value.');
+  }
+  const timeout = timeoutMs === undefined ? DEFAULT_COMMAND_TIMEOUT_MS : timeoutMs;
+  if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 1 || timeout > MAX_COMMAND_TIMEOUT_MS) {
+    throw new Error('Command timeout must be an integer from 1 to 300000 milliseconds.');
+  }
+  return { command, timeoutMs: timeout };
+}
+
+// Escape backslashes too, so actual control characters and literal "\\u001b"
+// remain distinguishable in approval text. Printable Unicode stays readable.
+export function escapeTerminalText(text: string): string {
+  return text.replace(/[\\\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/gu, char => {
+    if (char === '\\') return '\\\\';
+    if (char === '\n') return '\\n';
+    if (char === '\r') return '\\r';
+    if (char === '\t') return '\\t';
+    const code = char.codePointAt(0)!;
+    return code <= 0xffff ? `\\u${code.toString(16).padStart(4, '0')}` : `\\u{${code.toString(16)}}`;
+  });
+}
+
+function commandEnvironment(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { TERM: 'dumb' };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (/^(?:PATH|HOME|USER|LOGNAME|TMPDIR|LANG|LC_ALL|LC_CTYPE|LC_COLLATE|LC_MESSAGES|LC_MONETARY|LC_NUMERIC|LC_TIME)$/.test(key) && value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+function stripControls(text: string): string {
+  // Include string controls (OSC/DCS/APC/PM/SOS), including unfinished ones.
+  text = text.replace(/(?:\x1b[\]PX^_]|[\u0090\u0098\u009d\u009e\u009f])[\s\S]*?(?:\x07|\x1b\\|\u009c|$)/g, '');
+  return stripVTControlCharacters(text).replace(/[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/gu, char => char === '\n' || char === '\t' ? char : '');
+}
+
+function redact(text: string, values: string[], truncated: boolean): string {
+  // Mark all matches against the original text, including overlapping keys.
+  const spans: [number, number][] = [];
+  for (const value of values) {
+    if (!value) continue;
+    let start = text.indexOf(value);
+    while (start !== -1) {
+      spans.push([start, start + value.length]);
+      start = text.indexOf(value, start + 1);
+    }
+    if (truncated) {
+      for (let length = Math.min(value.length - 1, text.length); length > 0; length--) {
+        if (text.endsWith(value.slice(0, length))) {
+          spans.push([text.length - length, text.length]);
+          break;
+        }
+      }
+    }
+  }
+  spans.sort((a, b) => a[0] - b[0]);
+  let output = '', position = 0;
+  for (let i = 0; i < spans.length; i++) {
+    const [start, end] = spans[i]!;
+    if (start < position) continue;
+    let mergedEnd = end;
+    while (i + 1 < spans.length && spans[i + 1]![0] <= mergedEnd) mergedEnd = Math.max(mergedEnd, spans[++i]![1]);
+    output += text.slice(position, start) + '[REDACTED]';
+    position = mergedEnd;
+  }
+  return output + text.slice(position);
+}
+
+export function sanitizeCommandOutput(text: string, redactValues: string[] = [], truncated = false): string {
+  // Normalize both output and protected values before matching, so injected
+  // controls cannot break a match or expose overlapping protected values.
+  return redact(stripControls(text), [...redactValues, ...redactValues.map(stripControls)], truncated);
+}
+
+function safeOutput(buffers: Buffer[], values: string[], truncated: boolean): string {
+  // Streaming decode omits an incomplete final UTF-8 sequence instead of adding
+  // a replacement character when the byte cap bisects a code point.
+  const text = new TextDecoder().decode(Buffer.concat(buffers), { stream: truncated });
+  return sanitizeCommandOutput(text, values, truncated);
+}
+
+export function executeCommand(options: {
+  command: string;
+  cwd: string;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  redactValues?: string[];
+}): Promise<CommandResult> {
+  return new Promise(resolve => {
+    const values = options.redactValues ?? [];
+    const empty = (status: CommandResult['status'], stderr = ''): CommandResult => ({ status, exit_code: null, signal: null, stdout: '', stderr: sanitizeCommandOutput(stderr, values), truncated: false });
+    if (options.signal?.aborted) { resolve(empty('cancelled')); return; }
+    try {
+      validateCommand(options.command, options.timeoutMs, values);
+    } catch (error) {
+      resolve(empty('spawn_error', sanitizeCommandOutput(error instanceof Error ? error.message : 'Invalid command.', values)));
+      return;
+    }
+
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn('/bin/zsh', ['-f', '-c', options.command], {
+        cwd: options.cwd, env: commandEnvironment(), detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      resolve(empty('spawn_error', 'Could not start command.'));
+      return;
+    }
+
+    const stdout: Buffer[] = [], stderr: Buffer[] = [];
+    let bytes = 0, truncated = false, settled = false, exited = false, cleanupStarted = false, cleanupDone = false;
+    let status: CommandResult['status'] | undefined;
+    let exitCode: number | null = null, exitSignal: string | null = null;
+    let deadline: ReturnType<typeof setTimeout> | undefined;
+    let escalation: ReturnType<typeof setTimeout> | undefined;
+    let fallback: ReturnType<typeof setTimeout> | undefined;
+
+    // Detached zsh owns its process group. This is cleanup, not an OS sandbox:
+    // descendants that deliberately leave the group are outside this guarantee.
+    function signalGroup(signal: NodeJS.Signals): void {
+      if (!child.pid) return;
+      try { process.kill(-child.pid, signal); } catch { /* ESRCH is already cleaned up. */ }
+    }
+    function finish(): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline); clearTimeout(escalation); clearTimeout(fallback);
+      options.signal?.removeEventListener('abort', onAbort);
+      child.removeListener('error', onError);
+      child.removeListener('exit', onExit);
+      child.removeListener('close', onClose);
+      child.stdout?.removeListener('data', onStdout);
+      child.stderr?.removeListener('data', onStderr);
+      // Escaped descendants can hold pipes forever; never wait indefinitely for close.
+      child.stdout?.destroy(); child.stderr?.destroy();
+      child.unref();
+      resolve({ status: status ?? 'spawn_error', exit_code: exitCode, signal: exitSignal,
+        stdout: safeOutput(stdout, values, truncated), stderr: safeOutput(stderr, values, truncated), truncated });
+    }
+    function cleanup(): void {
+      if (cleanupStarted) return;
+      cleanupStarted = true;
+      clearTimeout(deadline);
+      signalGroup('SIGTERM');
+      // Do not cancel escalation on shell exit/pipe close: group children may remain.
+      escalation = setTimeout(() => {
+        signalGroup('SIGKILL');
+        cleanupDone = true;
+        if (exited) finish();
+        else fallback = setTimeout(finish, 100);
+      }, KILL_GRACE_MS);
+    }
+    function stop(reason: CommandResult['status']): void {
+      if (settled || (status !== undefined && !(reason === 'output_limit' && (status === 'completed' || status === 'failed')))) return;
+      status = reason;
+      cleanup();
+    }
+    function collect(chunk: Buffer, destination: Buffer[]): void {
+      if (settled) return;
+      const available = MAX_OUTPUT_BYTES - bytes;
+      if (available > 0) {
+        const captured = Buffer.from(chunk.subarray(0, available));
+        destination.push(captured);
+        bytes += captured.length;
+      }
+      if (chunk.length > available) {
+        truncated = true;
+        stop('output_limit');
+      }
+    }
+    function onStdout(chunk: Buffer): void { collect(chunk, stdout); }
+    function onStderr(chunk: Buffer): void { collect(chunk, stderr); }
+    function onAbort(): void { stop('cancelled'); }
+    function onError(): void {
+      // Spawn diagnostics can contain cwd or command text; keep them generic.
+      if (settled) return;
+      status ??= 'spawn_error';
+      if (!child.pid) {
+        stderr.push(Buffer.from('Could not start command.'));
+        finish(); return;
+      }
+      cleanup();
+    }
+    function onExit(code: number | null, signal: NodeJS.Signals | null): void {
+      exited = true; exitCode = code; exitSignal = signal;
+      status ??= code === 0 ? 'completed' : 'failed';
+      cleanup();
+      if (cleanupDone) finish();
+    }
+    function onClose(): void {
+      // close follows exit, but is not guaranteed while descendants hold pipes.
+      if (exited && cleanupDone) finish();
+    }
+    child.stdout?.on('data', onStdout);
+    child.stderr?.on('data', onStderr);
+    child.on('error', onError);
+    child.on('exit', onExit);
+    child.on('close', onClose);
+    deadline = setTimeout(() => stop('timed_out'), options.timeoutMs);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    // Covers cancellation between the pre-spawn check and listener registration.
+    if (options.signal?.aborted) onAbort();
+  });
+}

package/src/token.ts

@@ -0,0 +1,36 @@
+// token.ts — context budget estimation for the agent loop.
+// chars/4 is the rough estimate; the exact path (anthropic count_tokens) is injected
+// by the caller per dialect and always falls back to the estimate on failure.
+
+import type { ChatMessage, ToolDefinition } from './types.ts';
+
+/** Rough token estimate: ~4 characters per token. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export function estimateTotal(texts: string[]): number {
+  return texts.reduce((sum, t) => sum + estimateTokens(t), 0);
+}
+
+export interface BudgetWarnings {
+  warn80: boolean;
+  warn95: boolean;
+}
+
+/** 80%/95% context-window thresholds — the caller owns the "already warned" state. */
+export function checkBudget(totalTokens: number, contextTokens: number): BudgetWarnings {
+  return {
+    warn80: totalTokens >= contextTokens * 0.8,
+    warn95: totalTokens >= contextTokens * 0.95,
+  };
+}
+
+/**
+ * Exact token count via POST /v1/messages/count_tokens. Advisory: any failure must be
+ * caught by the caller and replaced with the estimate — a broken counter never blocks a
+ * turn.
+ */
+export interface TokenCounter {
+  countTokens(model: string, system: string, messages: ChatMessage[], tools?: ToolDefinition[]): Promise<number>;
+}

package/src/toolpreview.ts

@@ -0,0 +1,54 @@
+// Decode only completed JSON string characters while file-tool arguments stream.
+// This never executes a tool; it is a preview of the pending write/edit request.
+function stringField(json: string, key: string): string {
+  const match = new RegExp(`"${key}"\\s*:\\s*"`).exec(json);
+  if (!match) return '';
+  let text = '';
+  for (let i = match.index + match[0].length; i < json.length; i++) {
+    const c = json[i];
+    if (c === '"') break;
+    if (c !== '\\') { text += c; continue; }
+    const escaped = json[++i];
+    if (escaped === undefined) break;
+    if (escaped === 'u') {
+      const hex = json.slice(i + 1, i + 5);
+      if (!/^[\da-f]{4}$/i.test(hex)) break;
+      text += String.fromCharCode(parseInt(hex, 16));
+      i += 4;
+    } else {
+      const escapes: Record<string, string> = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', '"': '"', '\\': '\\', '/': '/' };
+      if (!(escaped in escapes)) break;
+      text += escapes[escaped];
+    }
+  }
+  return text;
+}
+
+export function toolPreview(name: string, json: string): { title: string; lines: string[] } | undefined {
+  if (name === 'run_command') return { title: 'Terminal command', lines: ['separate approval unless authorized by auto or absolute mode', 'not sandboxed · access to machine and network'] };
+  if (name === 'copy_path' || name === 'move_path') {
+    const source = stringField(json, 'source') || '…';
+    const destination = stringField(json, 'destination') || '…';
+    return { title: `${name === 'copy_path' ? 'Copy' : 'Move'}(${source})`, lines: [`from ${source}`, `to   ${destination}`, 'existing destinations are never overwritten'] };
+  }
+  if (name === 'make_dir' || name === 'remove_path') {
+    const path = stringField(json, 'path') || '…';
+    return { title: `${name === 'make_dir' ? 'Create directory' : 'Recoverable removal'}(${path})`, lines: [name === 'make_dir' ? 'creates missing parents' : 'kept in project recovery storage; can be restored'] };
+  }
+  if (name === 'restore_file') {
+    const id = stringField(json, 'recovery_id') || '…';
+    const destination = stringField(json, 'destination') || 'original path';
+    return { title: `Restore(${id})`, lines: [`to ${destination}`, 'existing destinations are never overwritten'] };
+  }
+  if (name !== 'write_file' && name !== 'edit_file') return undefined;
+  const path = stringField(json, 'path') || 'file';
+  const value = stringField(json, name === 'write_file' ? 'content' : 'new_string');
+  const old = name === 'edit_file' ? stringField(json, 'old_string') : '';
+  const added = value ? value.split('\n') : [];
+  const removed = old ? old.split('\n') : [];
+  const count = `${added.length ? '+' + added.length : ''}${removed.length ? ' −' + removed.length : ''}`.trim();
+  const title = `${name === 'write_file' ? 'Write' : 'Update'}(${path})${count ? ' · ' + count + ' lines' : ''}`;
+  const changes = [...removed.map((line) => '− ' + line), ...added.map((line) => '+ ' + line)];
+  const lines = changes.length > 6 ? ['… earlier lines', ...changes.slice(-5)] : changes;
+  return { title, lines };
+}