Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.8 KB
Raw Blame
/**
 * Render a subagent conversation to markdown.
 *
 * Two inputs:
 *  - subagent_messages rows (persisted Anthropic message-block arrays)
 *  - subagent_tool_executions rows (two-phase tool ledger — used to show
 *    tool outputs alongside the model's tool_use calls)
 *
 * The output is suitable for:
 *  - an attachment on the completed subagent job row
 *  - inline display in `gbrain agent logs <job>` after the heartbeat stream
 *  - committing as a brain page under wiki/agents/<subagentId>/transcript-*
 *
 * Does NOT redact anything — the caller writes to a location they control.
 * For PII-sensitive deployments, pass through a sanitizer before persisting.
 */

import type { BrainEngine } from '../engine.ts';
import type { ContentBlock } from './types.ts';

export interface SubagentMessageRow {
  id: number;
  job_id: number;
  message_idx: number;
  role: 'user' | 'assistant';
  content_blocks: ContentBlock[];
  tokens_in: number | null;
  tokens_out: number | null;
  tokens_cache_read: number | null;
  tokens_cache_create: number | null;
  model: string | null;
  ended_at: Date;
}

export interface SubagentToolExecRow {
  id: number;
  job_id: number;
  message_idx: number;
  /** D11 stable ordinal (per-turn tool-call position). NULL on legacy rows. */
  ordinal: number | null;
  tool_use_id: string;
  tool_name: string;
  input: unknown;
  status: 'pending' | 'complete' | 'failed';
  output: unknown;
  error: string | null;
}

/** Fetch both row sets for a job in one shot. */
export async function loadTranscriptRows(
  engine: BrainEngine,
  jobId: number,
): Promise<{ messages: SubagentMessageRow[]; tools: SubagentToolExecRow[] }> {
  const msgRows = await engine.executeRaw<Record<string, unknown>>(
    `SELECT id, job_id, message_idx, role, content_blocks, tokens_in, tokens_out,
            tokens_cache_read, tokens_cache_create, model, ended_at
       FROM subagent_messages
      WHERE job_id = $1
      ORDER BY message_idx ASC`,
    [jobId],
  );
  const toolRows = await engine.executeRaw<Record<string, unknown>>(
    `SELECT id, job_id, message_idx, ordinal, tool_use_id, tool_name, input, status, output, error
       FROM subagent_tool_executions
      WHERE job_id = $1
      ORDER BY id ASC`,
    [jobId],
  );
  return {
    messages: msgRows.map(normalizeMessage),
    tools: toolRows.map(normalizeTool),
  };
}

function normalizeMessage(row: Record<string, unknown>): SubagentMessageRow {
  const blocks = row.content_blocks;
  const parsedBlocks: ContentBlock[] = typeof blocks === 'string'
    ? (JSON.parse(blocks) as ContentBlock[])
    : (blocks as ContentBlock[]) ?? [];
  return {
    id: row.id as number,
    job_id: row.job_id as number,
    message_idx: row.message_idx as number,
    role: row.role as 'user' | 'assistant',
    content_blocks: parsedBlocks,
    tokens_in: (row.tokens_in as number) ?? null,
    tokens_out: (row.tokens_out as number) ?? null,
    tokens_cache_read: (row.tokens_cache_read as number) ?? null,
    tokens_cache_create: (row.tokens_cache_create as number) ?? null,
    model: (row.model as string) ?? null,
    ended_at: new Date(row.ended_at as string),
  };
}

function normalizeTool(row: Record<string, unknown>): SubagentToolExecRow {
  const input = typeof row.input === 'string' ? JSON.parse(row.input) : row.input;
  const output = row.output == null
    ? null
    : (typeof row.output === 'string' ? JSON.parse(row.output) : row.output);
  return {
    id: row.id as number,
    job_id: row.job_id as number,
    message_idx: row.message_idx as number,
    ordinal: (row.ordinal as number | null) ?? null,
    tool_use_id: row.tool_use_id as string,
    tool_name: row.tool_name as string,
    input,
    status: row.status as 'pending' | 'complete' | 'failed',
    output,
    error: (row.error as string) ?? null,
  };
}

export interface RenderTranscriptOpts {
  /** Trim long tool outputs in the markdown. Default: 4 KiB per output. */
  maxOutputBytes?: number;
}

/**
 * Render messages + tool executions to markdown. Message order is
 * authoritative; tool rows are spliced under their owning assistant message
 * by (message_idx, tool_use_id) — raw provider ids may repeat across turns.
 */
export function renderTranscript(
  messages: SubagentMessageRow[],
  tools: SubagentToolExecRow[],
  opts: RenderTranscriptOpts = {},
): string {
  const maxOut = opts.maxOutputBytes ?? 4096;
  // Keyed by (message_idx, tool_use_id) — raw provider tool_use_ids may
  // repeat across turns (#4155: replay-style providers like claude-cli reuse
  // the same short id on every turn), so tool_use_id alone would collapse
  // distinct executions onto one row and mis-attribute status/output.
  const toolByMsgAndId = new Map<string, SubagentToolExecRow>(
    tools.map(t => [`${t.message_idx}:${t.tool_use_id}`, t]),
  );
  // Ordinal-first resolution for stamped rows: within one turn a raw id can
  // even repeat (the composite id map is last-write-wins for that shape);
  // the persisted D11 ordinal equals the tool_use block position, which is
  // exact.
  const toolByMsgAndOrdinal = new Map<string, SubagentToolExecRow>();
  for (const t of tools) {
    if (t.ordinal != null) toolByMsgAndOrdinal.set(`${t.message_idx}:${t.ordinal}`, t);
  }

  const out: string[] = [];
  out.push('# Subagent transcript', '');
  if (messages.length === 0) {
    out.push('_(no messages)_');
    return out.join('\n');
  }

  const first = messages[0]!;
  out.push(`- job_id: ${first.job_id}`);
  out.push(`- messages: ${messages.length}`);
  if (first.model) out.push(`- model: ${first.model}`);
  out.push('');

  // tool_result blocks live in the user message FOLLOWING the owning
  // assistant message; track the nearest preceding assistant idx so their
  // ownership check uses that turn's composite key (a job-wide id set would
  // wrongly suppress a result whose own turn has no execution row when a
  // DIFFERENT turn reused the id).
  let prevAssistantIdx: number | null = null;

  for (const msg of messages) {
    out.push(`## Message ${msg.message_idx} — ${msg.role}`);
    if (msg.tokens_in != null || msg.tokens_out != null) {
      const parts: string[] = [];
      if (msg.tokens_in) parts.push(`in=${msg.tokens_in}`);
      if (msg.tokens_out) parts.push(`out=${msg.tokens_out}`);
      if (msg.tokens_cache_read) parts.push(`cache_read=${msg.tokens_cache_read}`);
      if (msg.tokens_cache_create) parts.push(`cache_create=${msg.tokens_cache_create}`);
      if (parts.length > 0) out.push(`> tokens: ${parts.join(' ')}`);
    }
    out.push('');

    // Ids repeated WITHIN this message make the (message_idx, raw id) key
    // ambiguous — resolution for those falls to the stamped ordinal only.
    const idCounts = new Map<string, number>();
    for (const b of msg.content_blocks) {
      if (b.type === 'tool_use' && typeof b.id === 'string') {
        idCounts.set(b.id, (idCounts.get(b.id) ?? 0) + 1);
      }
    }
    let toolUseOrdinal = 0; // tool_use block position within this message
    for (const block of msg.content_blocks) {
      const blockOrdinal = block.type === 'tool_use' ? toolUseOrdinal++ : -1;
      const idIsUniqueInMsg = !(block.type === 'tool_use' && typeof block.id === 'string'
        && (idCounts.get(block.id) ?? 0) > 1);
      renderBlock(block, msg.message_idx, blockOrdinal, idIsUniqueInMsg, prevAssistantIdx, toolByMsgAndId, toolByMsgAndOrdinal, maxOut, out);
    }
    out.push('');
    if (msg.role === 'assistant') prevAssistantIdx = msg.message_idx;
  }

  return out.join('\n').replace(/\n{3,}/g, '\n\n');
}

function renderBlock(
  block: ContentBlock,
  messageIdx: number,
  /** tool_use block position within the message (-1 for non-tool_use blocks). */
  blockOrdinal: number,
  /** false when this tool_use block's id repeats within the message. */
  idIsUniqueInMsg: boolean,
  prevAssistantIdx: number | null,
  toolByMsgAndId: Map<string, SubagentToolExecRow>,
  toolByMsgAndOrdinal: Map<string, SubagentToolExecRow>,
  maxOutputBytes: number,
  out: string[],
): void {
  if (block.type === 'text' && typeof block.text === 'string') {
    out.push(block.text);
    out.push('');
    return;
  }

  if (block.type === 'tool_use') {
    const name = typeof block.name === 'string' ? block.name : '<unknown>';
    const inputStr = safeJson(block.input, 2);
    out.push(`**tool_use** \`${name}\` (id=\`${block.id ?? '?'}\`)`);
    out.push('```json', inputStr, '```');
    // Execution rows are written with the OWNING assistant message's idx.
    // Resolve by the stamped (message_idx, ordinal) first — validated by the
    // raw id — then by (message_idx, raw id) for legacy rows.
    const stamped = toolByMsgAndOrdinal.get(`${messageIdx}:${blockOrdinal}`);
    const toolRow = (stamped && typeof block.id === 'string' && stamped.tool_use_id === block.id)
      ? stamped
      : (idIsUniqueInMsg && block.id && typeof block.id === 'string'
        ? toolByMsgAndId.get(`${messageIdx}:${block.id}`)
        : undefined);
    if (toolRow) {
      out.push(`→ status: **${toolRow.status}**`);
      if (toolRow.status === 'complete') {
        out.push('```json', truncate(safeJson(toolRow.output, 2), maxOutputBytes), '```');
      } else if (toolRow.status === 'failed') {
        out.push(`> error: ${toolRow.error ?? '(no error text)'}`);
      } else if (toolRow.status === 'pending') {
        out.push('> pending (no resolution recorded yet)');
      }
    }
    out.push('');
    return;
  }

  if (block.type === 'tool_result') {
    // Most tool_result blocks live inside user messages echoing back the
    // assistant's tool_use. We skip them here because the owning tool_use
    // block already rendered the execution row. Ownership is checked against
    // the nearest PRECEDING assistant turn's key — raw ids may repeat across
    // turns, so a job-wide id match could suppress a result whose own turn
    // has no execution row. If no owning row exists (rare), dump it raw.
    const owned = prevAssistantIdx !== null
      && typeof block.tool_use_id === 'string'
      && toolByMsgAndId.has(`${prevAssistantIdx}:${block.tool_use_id}`);
    if (!owned) {
      out.push('**tool_result** (no matching tool_use in this transcript)');
      out.push('```json', truncate(safeJson(block.content, 2), maxOutputBytes), '```');
      out.push('');
    }
    return;
  }

  // Unknown block type — dump as a fenced JSON block for diagnostics.
  out.push(`**${block.type}**`);
  out.push('```json', truncate(safeJson(block, 2), maxOutputBytes), '```');
  out.push('');
}

function safeJson(value: unknown, indent = 0): string {
  try {
    return JSON.stringify(value, null, indent);
  } catch {
    return String(value);
  }
}

function truncate(s: string, maxBytes: number): string {
  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;
  // Slice bytewise via Buffer so we don't split a multibyte char awkwardly.
  const buf = Buffer.from(s, 'utf8').slice(0, maxBytes);
  return buf.toString('utf8') + `\n... [truncated at ${maxBytes} bytes]`;
}