Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

11.1 KB
Raw Blame
/**
 * Tool blocks for the Mercury Code transcript.
 *
 * Every finished tool call leaves one persistent block in scrollback, so the
 * transcript reads as what the agent actually did, in order:
 *
 *   ● Update(src/auth/session.ts)
 *     ⎿  1 addition, 1 removal
 *          -  const ttl = 3600;
 *          +  const ttl = config.sessionTtl ?? 3600;
 *
 * This module only builds the data (pure, testable); mercury-transcript.ts
 * turns it into rows and App.tsx styles them.
 */
import { fenceLangForPath } from '../utils/file-preview.js';
import { formatToolResult } from '../utils/tool-label.js';

export interface ToolBlock {
  /** Raw tool name (read_file, run_command, …). */
  name: string;
  /** Verb shown in bold: Read, Update, Bash, … */
  title: string;
  /** Argument shown in parentheses: a path, a command, a URL. */
  target: string;
  status: 'done' | 'error';
  /** One-line outcome shown after the ⎿ elbow. */
  summary: string;
  /** Optional excerpt under the summary: a diff, file head, or command output. */
  body?: { lang: string; lines: string[] };
}

/** Tools whose work is already shown elsewhere in the TUI (choice prompt,
 * permission prompt) — no transcript block. */
const HIDDEN_TOOLS: ReadonlySet<string> = new Set([
  'ask_user', 'approve_scope', 'approve_command',
]);

export function isTranscriptTool(toolName: string): boolean {
  return !HIDDEN_TOOLS.has(toolName);
}

/** Diff rows shown for an edit before collapsing to "… +N lines". */
export const TOOL_DIFF_MAX_LINES = 20;
/** Head rows of a written/created file. */
export const TOOL_WRITE_MAX_LINES = 8;
/** Tail rows of command output (errors and test summaries live at the end). */
export const TOOL_OUTPUT_MAX_LINES = 6;
/** Rows kept for an expanded (ctrl+o) block. */
export const TOOL_EXPAND_MAX_LINES = 2000;
/** Hint on collapsed excerpts: the expand key. */
export const EXPAND_HINT = 'ctrl+o to expand';

const TITLES: Record<string, string> = {
  read_file: 'Read',
  write_file: 'Write',
  create_file: 'Create',
  edit_file: 'Update',
  delete_file: 'Delete',
  list_dir: 'List',
  run_command: 'Bash',
  cd: 'Cd',
  fetch_url: 'Fetch',
  delegate_task: 'Agent',
  use_skill: 'Skill',
  search_memory: 'Recall',
  save_memory: 'Remember',
  forget_memory: 'Forget',
  confirm_belief: 'Confirm',
  correct_belief: 'Correct',
  update_plan: 'Plan',
};

function titleFor(toolName: string): string {
  if (TITLES[toolName]) return TITLES[toolName];
  if (toolName.startsWith('git_')) return 'Git';
  // github_api → Github api, create_pr → Create pr
  const words = toolName.replace(/_/g, ' ');
  return words.charAt(0).toUpperCase() + words.slice(1);
}

/** Show paths relative to the project root; anything else as given. */
export function displayPath(path: string, cwd?: string): string {
  const p = path.replace(/\\/g, '/');
  if (cwd) {
    const root = cwd.replace(/\\/g, '/').replace(/\/$/, '');
    if (p === root) return '.';
    if (p.startsWith(`${root}/`)) return p.slice(root.length + 1);
  }
  return p;
}

function oneLine(text: string, max = 80): string {
  const line = text.replace(/\s+/g, ' ').trim();
  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
}

function targetFor(toolName: string, args: Record<string, any>, cwd?: string): string {
  if (typeof args.path === 'string' && args.path) return displayPath(args.path, cwd);
  if (toolName === 'run_command' && typeof args.command === 'string') return oneLine(args.command);
  if (typeof args.url === 'string') return oneLine(args.url);
  if (typeof args.task === 'string') return oneLine(args.task, 60);
  if (typeof args.name === 'string') return oneLine(args.name);
  if (typeof args.query === 'string') return oneLine(args.query, 60);
  if (toolName.startsWith('git_')) return toolName.slice(4);
  return '';
}

function resultText(result: unknown): string {
  if (result == null) return '';
  if (typeof result === 'string') return result;
  if (result instanceof Error) return `Error: ${result.message}`;
  const r = result as any;
  if (typeof r.result === 'string') return r.result;
  if (typeof r.message === 'string' && r.name) return `Error: ${r.message}`;
  try {
    return JSON.stringify(result);
  } catch {
    return String(result);
  }
}

function lineCount(text: string): number {
  if (text.length === 0) return 0;
  return text.replace(/\n$/, '').split('\n').length;
}

function plural(n: number, word: string): string {
  return `${n} ${word}${n === 1 ? '' : 's'}`;
}

/**
 * Line diff of an edit: common leading/trailing lines are trimmed down to
 * one line of context each side, so an edit touching one line inside a
 * 20-line `old_string` shows as one -/+ pair instead of 20 of each.
 */
export function editDiffLines(oldStr: string, newStr: string): { lines: string[]; added: number; removed: number } {
  const a = oldStr.length > 0 ? oldStr.split('\n') : [];
  const b = newStr.length > 0 ? newStr.split('\n') : [];
  let pre = 0;
  while (pre < a.length && pre < b.length && a[pre] === b[pre]) pre++;
  let suf = 0;
  while (suf < a.length - pre && suf < b.length - pre && a[a.length - 1 - suf] === b[b.length - 1 - suf]) suf++;
  const removed = a.slice(pre, a.length - suf);
  const added = b.slice(pre, b.length - suf);
  const lines: string[] = [];
  if (pre > 0) lines.push(` ${a[pre - 1]}`);
  for (const l of removed) lines.push(`-${l}`);
  for (const l of added) lines.push(`+${l}`);
  if (suf > 0) lines.push(` ${a[a.length - suf]}`);
  return { lines, added: added.length, removed: removed.length };
}

function capHead(lines: string[], max: number): string[] {
  if (lines.length <= max) return lines;
  return [...lines.slice(0, max), `… +${lines.length - max} lines (${EXPAND_HINT})`];
}

function capTail(lines: string[], max: number): string[] {
  if (lines.length <= max) return lines;
  return [`… ${lines.length - max} earlier lines (${EXPAND_HINT})`, ...lines.slice(-max)];
}

/** Plan checklist rows: ☒ done, ▶ active, ☐ pending. */
function planRows(steps: unknown): string[] {
  if (!Array.isArray(steps)) return [];
  const mark: Record<string, string> = { done: '☒', active: '▶', pending: '☐' };
  return steps
    .filter((st: any) => typeof st?.label === 'string' && mark[st?.status])
    .slice(0, 20)
    .map((st: any) => `${mark[st.status]} ${oneLine(st.label, 100)}`);
}

/** Split run_command's result text into exit code + output lines. */
function parseCommandResult(text: string): { exitCode: number | null; output: string[] } {
  const exit = /^Command exited with code (\d+)/.exec(text);
  let body = text;
  let exitCode: number | null = null;
  if (exit) {
    exitCode = Number(exit[1]);
    body = text.slice(exit[0].length).replace(/^\nOutput: /, '').replace(/\nError: /, '\n');
  }
  const output = body.trim() === '(no output)' ? [] : body.replace(/\s+$/, '').split('\n').filter((l, i, all) => l.trim() !== '' || (i > 0 && i < all.length - 1));
  return { exitCode, output };
}

/**
 * Tool failures follow one convention: the result STARTS with the marker.
 * (execute-guard's isFailedToolResult matches anywhere in the head, which is
 * right for its job but would paint a read of any file mentioning "error:"
 * as failed.)
 */
const FAILED_PREFIX_RE = /^(error\b|⚠|command failed|command exited with code)/i;

export interface ToolBlockInput {
  toolName: string;
  args: Record<string, any>;
  result: unknown;
  /** The SDK reported the call as failed (threw). */
  isError: boolean;
  /** Project root, to show paths relative to it. */
  cwd?: string;
}

export interface ToolBlockDetail {
  block: ToolBlock;
  /** The uncollapsed excerpt, when `block.body` had to collapse it. */
  full?: { lang: string; lines: string[] };
}

export function buildToolBlock(input: ToolBlockInput): ToolBlock {
  return buildToolBlockDetail(input).block;
}

export function buildToolBlockDetail(input: ToolBlockInput): ToolBlockDetail {
  let full: ToolBlockDetail['full'];
  // Collapse `lines` into the block body; keep the whole thing for ctrl+o.
  const body = (lang: string, lines: string[], cap: (l: string[], max: number) => string[], max: number) => {
    if (lines.length > max) {
      // Heads keep the start, tails keep the end — same side the excerpt shows.
      const kept = cap === capTail ? lines.slice(-TOOL_EXPAND_MAX_LINES) : lines.slice(0, TOOL_EXPAND_MAX_LINES);
      full = { lang, lines: kept };
    }
    return { lang, lines: cap(lines, max) };
  };
  const block = buildBlock(input, body);
  return full ? { block, full } : { block };
}

type BodyFn = (lang: string, lines: string[], cap: (l: string[], max: number) => string[], max: number) => { lang: string; lines: string[] };

function buildBlock(input: ToolBlockInput, body: BodyFn): ToolBlock {
  const { toolName, cwd } = input;
  const args = input.args ?? {};
  const text = resultText(input.result);
  const failed = input.isError || FAILED_PREFIX_RE.test(text.trimStart());
  const block: ToolBlock = {
    name: toolName,
    title: titleFor(toolName),
    target: targetFor(toolName, args, cwd),
    status: failed ? 'error' : 'done',
    summary: '',
  };

  if (toolName === 'run_command') {
    const { exitCode, output } = parseCommandResult(text);
    if (exitCode != null) block.status = 'error';
    const timedOut = text.startsWith('⏱');
    if (failed && exitCode == null && !timedOut) {
      block.summary = oneLine(text.split('\n')[0], 120);
      return block;
    }
    block.summary = timedOut
      ? oneLine(text.split('\n')[0], 120)
      : exitCode != null
        ? `Exit code ${exitCode}`
        : output.length === 0 ? '(no output)' : plural(output.length, 'line');
    if (output.length > 0 && !timedOut) block.body = body('', output, capTail, TOOL_OUTPUT_MAX_LINES);
    return block;
  }

  // Failures: the first line of the error is the whole story.
  if (failed) {
    block.summary = oneLine(text.split('\n')[0] || 'failed', 120);
    return block;
  }

  switch (toolName) {
    case 'read_file':
      block.summary = `Read ${plural(lineCount(text), 'line')}`;
      break;
    case 'edit_file': {
      const diff = editDiffLines(String(args.old_string ?? ''), String(args.new_string ?? ''));
      block.summary = `${plural(diff.added, 'addition')}, ${plural(diff.removed, 'removal')}`;
      if (diff.lines.length > 0) block.body = body('diff', diff.lines, capHead, TOOL_DIFF_MAX_LINES);
      break;
    }
    case 'write_file':
    case 'create_file': {
      const content = typeof args.content === 'string' ? args.content : '';
      const n = lineCount(content);
      block.summary = `${toolName === 'create_file' ? 'Created' : 'Wrote'} ${plural(n, 'line')}`;
      if (n > 0) {
        const lang = typeof args.path === 'string' ? fenceLangForPath(args.path) : '';
        block.body = body(lang || 'text', content.replace(/\n$/, '').split('\n'), capHead, TOOL_WRITE_MAX_LINES);
      }
      break;
    }
    case 'delete_file':
      block.summary = 'Deleted';
      break;
    case 'update_plan': {
      const rows = planRows(args.steps);
      const done = rows.filter((r) => r.startsWith('☒')).length;
      block.summary = `${done}/${rows.length} done`;
      if (rows.length > 0) block.body = { lang: 'plan', lines: rows };
      break;
    }
    default:
      block.summary = formatToolResult(toolName, text) || 'Done';
  }
  return block;
}