Skip to content

Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World

5.6 KB
Raw Blame
/**
 * What a tool call did, in words: the transcript's tool rows show this
 * instead of the call's raw arguments (those stay in the event log and
 * behind "Show Raw"). One shape per family of tools, whatever each harness
 * calls them: Pi's and fx's `bash` / `write_file`, Claude Code's `Bash` /
 * `Write`, Codex's `shell`, OpenCode's `bash` / `write`.
 */

export type ToolKind = 'command' | 'write' | 'read' | 'edit' | 'doc' | 'other';

export interface ToolSummary {
  kind: ToolKind;
  /** The command, or the sentence ("Wrote notes.md (77 bytes)"). */
  text: string;
  /** The file it touched, relative to the session's workspace. */
  path?: string;
  /** A document tool that reads (`read_todos`): its row shows what it read. */
  reads?: boolean;
}

const COMMAND = new Set(['bash', 'shell', 'exec_command', 'run_on_machine', 'sandbox_exec', 'run_command']);
const WRITE = new Set(['write_file', 'write', 'create_file']);
const READ = new Set(['read_file', 'read', 'view']);
const EDIT = new Set(['edit_file', 'edit', 'str_replace', 'multiedit', 'apply_patch']);

const str = (v: unknown) => (typeof v === 'string' ? v : undefined);

/**
 * A path as the session sees it: anything up to and including a
 * `workspace/` directory goes (the server's own path to the session's
 * workspace, or the sandbox's `/workspace`).
 */
export function workspacePath(path: string, cwd?: string): string {
  let p = path;
  if (cwd && p.startsWith(`${cwd.replace(/\/$/, '')}/`)) p = p.slice(cwd.replace(/\/$/, '').length + 1);
  const at = p.lastIndexOf('/workspace/');
  if (at >= 0) p = p.slice(at + '/workspace/'.length);
  else if (p.startsWith('workspace/')) p = p.slice('workspace/'.length);
  return p || '.';
}

/** A command as it was typed: Codex wraps each in `/bin/bash -lc '…'`. */
export function unwrapCommand(command: string): string {
  const m = /^\/bin\/(?:ba|z)?sh\s+-l?c\s+(['"])([\s\S]*)\1$/.exec(command.trim());
  return (m ? m[2]! : command).replace(/'\\''/g, "'");
}

/** Strip workspace prefixes from any absolute path inside a command or message. */
export const relativizePaths = (text: string) => text.replace(/(?:\/[\w.@+-]+)*\/workspace\//g, '');

const bytes = (s: string) => new TextEncoder().encode(s).length;

export function toolSummary(name: string, input: unknown): ToolSummary {
  const n = name.toLowerCase();
  const args = (input ?? {}) as Record<string, unknown>;
  const cwd = str(args.cwd) ?? str(args.workdir);
  const pathArg = str(args.path) ?? str(args.file_path) ?? str(args.filePath) ?? str(args.filename);
  const path = pathArg ? workspacePath(pathArg, cwd) : undefined;
  if (COMMAND.has(n)) {
    // fx's shell nests its command in `request` ({ action: 'run', command }).
    const request = (args.request ?? {}) as Record<string, unknown>;
    const raw = Array.isArray(args.command) ? args.command.map(String).join(' ') : (str(args.command) ?? str(args.cmd) ?? str(request.command) ?? '');
    return { kind: 'command', text: relativizePaths(unwrapCommand(raw)) };
  }
  if (WRITE.has(n) && path) {
    const content = str(args.content) ?? str(args.text) ?? '';
    return { kind: 'write', text: `Wrote ${path} (${bytes(content)} bytes)`, path };
  }
  if (READ.has(n) && path) return { kind: 'read', text: `Read ${path}`, path };
  if (EDIT.has(n) && path) return { kind: 'edit', text: `Edited ${path}`, path };
  // A document's tools (harness-world-hands docTools): read_<name>, update_<name>.
  const doc = /^(read|update)_([a-z]\w*)$/.exec(n);
  if (doc && !path) {
    const what = doc[2]!.replace(/_/g, ' ');
    if (doc[1] === 'read') return { kind: 'doc', text: `Read ${what}`, reads: true };
    const items = itemsOf(args.value);
    return { kind: 'doc', text: items ? `Set ${what}: ${items.length ? items.join(', ') : '(empty)'}` : `Updated ${what}` };
  }
  return { kind: 'other', text: compactArgs(args) };
}

/** A list document's items (`{ items: string[] }`, or that as JSON text). */
function itemsOf(value: unknown): string[] | undefined {
  let v = value;
  if (typeof v === 'string') {
    try {
      v = JSON.parse(v);
    } catch {
      return undefined;
    }
  }
  const items = (v as { items?: unknown } | null)?.items;
  return Array.isArray(items) && items.every((i) => typeof i === 'string') ? (items as string[]) : undefined;
}

/** What a document read returned (`{ revision, value }`): a list's items one per line, else the JSON as it came. */
export function docText(out: string): string {
  try {
    const parsed = JSON.parse(out) as { value?: unknown };
    const items = itemsOf(parsed?.value);
    if (items) return items.length ? items.join('\n') : '(empty)';
  } catch {}
  return out;
}

/** Other tools: their arguments, short (`to: alice@example.com, amount_usd: 5`). */
export function compactArgs(args: Record<string, unknown>): string {
  const parts: string[] = [];
  for (const [k, v] of Object.entries(args)) {
    if (v === undefined || v === null || k === 'description') continue;
    const s = typeof v === 'string' ? relativizePaths(v) : JSON.stringify(v);
    parts.push(`${k}: ${s.length > 80 ? `${s.slice(0, 79)}…` : s}`);
  }
  return parts.join(', ');
}

/** A shell tool's exit code, out of its result or its error ("exit code 127", "exit code: 1"). */
export function exitCode(text: string | undefined): number | undefined {
  const m = /exit(?:ed)?(?: with)? code:?\s*(-?\d+)/i.exec(text ?? '');
  return m ? Number(m[1]) : undefined;
}

/** What a tool row shows of its result: a command's output and a file it read; a write's or an edit's echo is noise. */
export const showsOutput = (kind: ToolKind) => kind === 'command' || kind === 'read' || kind === 'other';