@bahulam/code 0.1.24 → 0.1.26

package/src/core/request-retry.mjs

@@ -0,0 +1,106 @@
+/**
+ * Shared retry policy for one-shot model HTTP requests.
+ *
+ * Streaming /api/execute has its own event-id resume protocol in
+ * stream-client.mjs. This helper is for npm-owned local/direct model calls
+ * where the request must finish before the agent loop can continue.
+ */
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+const NETWORK_CODES = new Set([
+  'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ETIMEDOUT',
+  'EAI_AGAIN', 'ENETUNREACH', 'ENETDOWN', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+function numberEnv(name, fallback) {
+  const value = Number.parseInt(process.env[name] || '', 10);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+export function isNetworkError(error) {
+  const code = error?.cause?.code || error?.code;
+  return error?.name === 'AbortError'
+    || NETWORK_CODES.has(String(code || '').toUpperCase())
+    || /fetch failed|network|socket|timed out|timeout|connection reset|connection refused/i.test(String(error?.message || ''));
+}
+
+export function isRetryableStatus(status) {
+  return RETRYABLE_STATUS.has(Number(status));
+}
+
+function retryDelay(attempt, base, max) {
+  const exponential = Math.min(max, base * (2 ** Math.max(0, attempt - 1)));
+  return Math.min(max, Math.round(exponential * (0.8 + Math.random() * 0.4)));
+}
+
+function wait(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export class RequestError extends Error {
+  constructor(message, { status = null, code = 'request_error', retryable = false, attempts = 1, cause = null } = {}) {
+    super(message, { cause: cause || undefined });
+    this.name = 'RequestError';
+    this.status = status;
+    this.code = code;
+    this.retryable = retryable;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Fetch with bounded retry for transient transport/server failures.
+ * 401/403 and all other non-retryable 4xx responses return immediately.
+ */
+export async function fetchWithRetry(url, options = {}, {
+  fetchImpl = globalThis.fetch,
+  maxRetries = numberEnv('BAHULAM_REQUEST_MAX_RETRIES', 2),
+  baseDelayMs = numberEnv('BAHULAM_REQUEST_RETRY_BASE_MS', 500),
+  maxDelayMs = numberEnv('BAHULAM_REQUEST_RETRY_MAX_MS', 8000),
+  onRetry = null,
+} = {}) {
+  const retries = Math.max(0, Number(maxRetries) || 0);
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    let response;
+    try {
+      response = await fetchImpl(url, options);
+    } catch (error) {
+      if (!isNetworkError(error) || attempt > retries + 1) {
+        throw new RequestError(
+          `Network request failed after ${attempt} attempt${attempt === 1 ? '' : 's'}: ${error?.message || error}`,
+          { code: 'network_error', retryable: true, attempts: attempt, cause: error },
+        );
+      }
+      const delayMs = retryDelay(attempt, baseDelayMs, maxDelayMs);
+      onRetry?.({ attempt, delayMs, reason: 'network', error });
+      await wait(delayMs);
+      continue;
+    }
+
+    if (!isRetryableStatus(response.status) || attempt > retries + 1) {
+      return response;
+    }
+
+    // Release the failed response before retrying. The final response remains
+    // available to the caller for its normal provider-specific error body.
+    try { response.body?.cancel?.(); } catch {}
+    const delayMs = retryDelay(attempt, baseDelayMs, maxDelayMs);
+    onRetry?.({ attempt, delayMs, reason: `http_${response.status}`, status: response.status });
+    await wait(delayMs);
+  }
+}
+
+export function requestErrorData(error, { phase = 'model', provider = null } = {}) {
+  return {
+    message: error?.message || String(error),
+    code: error?.code || (error?.status ? `http_${error.status}` : 'request_error'),
+    phase,
+    provider,
+    status: error?.status ?? null,
+    retryable: error?.retryable === true || isRetryableStatus(error?.status),
+    attempts: error?.attempts || 1,
+  };
+}

package/src/core/tool-error.mjs

@@ -0,0 +1,155 @@
+/**
+ * Structured tool errors.
+ *
+ * Plugin tool handlers used to return { success: false, output: "<msg>" }
+ * and thrown errors got wrapped the same way — the message became a
+ * blob the agent had to re-read to figure out what went wrong.
+ *
+ * This module standardizes the envelope so the trace UI can filter and
+ * the agent can self-correct on the next turn without re-parsing prose.
+ *
+ * Handler patterns
+ * ----------------
+ *
+ * Return a structured error explicitly:
+ *
+ *   import { toolError } from '../../src/core/tool-error.mjs';
+ *   if (!scene) return toolError('MISSING_SCENE', `Scene "${slug}" not found.`,
+ *                                'Call create_scene(name="<slug>") first.');
+ *
+ * OR throw a ToolError:
+ *
+ *   throw new ToolError('INVALID_ARGS', 'position must be [x,y,z]', 'Pass a length-3 array.');
+ *
+ * OR throw a plain Error — normalizeToolResult wraps it as { code: 'UNKNOWN' }
+ * so nothing crashes the executor.
+ *
+ * Error codes (extend freely; keep short, SCREAMING_SNAKE_CASE)
+ * ---
+ *   INVALID_ARGS       — schema violation or missing required field
+ *   MISSING_RESOURCE   — referenced id (node, ref, section, ...) not found
+ *   IO                 — filesystem or network operation failed
+ *   PROVIDER_UNAVAILABLE — external provider missing key or offline
+ *   PROVIDER_ERROR     — external provider returned an error response
+ *   STATE_ERROR        — plugin state DB read/write failure
+ *   RATE_LIMITED       — provider or platform rate limit hit
+ *   TIMEOUT            — operation exceeded its deadline
+ *   UNKNOWN            — thrown Error that wasn't a ToolError (fallback)
+ */
+
+export class ToolError extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.name = 'ToolError';
+    this.code = String(code || 'UNKNOWN');
+    this.hint = hint ? String(hint) : null;
+  }
+}
+
+/**
+ * Build a structured error envelope suitable for `return`-ing from a
+ * plugin tool handler. Never throws.
+ */
+export function toolError(code, message, hint) {
+  return {
+    success: false,
+    output: String(message || ''),
+    error: {
+      code: String(code || 'UNKNOWN'),
+      message: String(message || ''),
+      ...(hint ? { hint: String(hint) } : {}),
+    },
+  };
+}
+
+/**
+ * Normalize an arbitrary handler return value or thrown error into the
+ * canonical shape:
+ *
+ *   Success:  { success: true,  output, _tool, _plugin }
+ *   Failure:  { success: false, output, error: { code, message, hint?, stack? },
+ *               _tool, _plugin }
+ *
+ * `stack` is only attached in DEBUG mode so the trace export can show
+ * it without leaking noise into normal responses.
+ *
+ * `traceId` is optional; when provided by the caller it's forwarded so
+ * export / logs can join back to the trace row.
+ */
+export function normalizeToolResult({ tool, plugin, traceId }, result, thrown) {
+  const meta = {
+    _tool: tool,
+    ...(plugin ? { _plugin: plugin } : {}),
+    ...(traceId ? { _trace_id: traceId } : {}),
+  };
+
+  if (thrown) {
+    const err = thrown instanceof ToolError
+      ? { code: thrown.code, message: thrown.message, ...(thrown.hint ? { hint: thrown.hint } : {}) }
+      : { code: 'UNKNOWN', message: String(thrown?.message || thrown) };
+    if (process.env.DEBUG && thrown?.stack) err.stack = String(thrown.stack).split('\n').slice(0, 6).join('\n');
+    const outputText = [`[${err.code}] ${err.message}`, err.hint ? `(hint: ${err.hint})` : ''].filter(Boolean).join(' ');
+    return { success: false, output: outputText, error: err, ...meta };
+  }
+
+  if (!result || typeof result !== 'object') {
+    return { success: true, output: result, ...meta };
+  }
+
+  if (result.success !== false) {
+    return { success: true, output: result.output ?? result, ...meta };
+  }
+
+  // success === false — extract structured error if present, else synthesize one
+  const err = result.error && typeof result.error === 'object'
+    ? {
+        code: String(result.error.code || 'UNKNOWN'),
+        message: String(result.error.message || result.output || 'Tool call failed.'),
+        ...(result.error.hint ? { hint: String(result.error.hint) } : {}),
+      }
+    : {
+        code: 'UNKNOWN',
+        message: typeof result.output === 'string' ? result.output : JSON.stringify(result.output ?? 'Tool call failed.'),
+      };
+
+  // The agent reads `output` on the next turn — make it self-contained so
+  // the LLM doesn't need to re-parse. Format: [CODE] message (hint: ...)
+  const rawOutput = typeof result.output === 'string' && result.output.trim()
+    ? result.output
+    : err.message;
+  const alreadyHasCode = rawOutput.startsWith(`[${err.code}]`);
+  const alreadyHasHint = err.hint && rawOutput.toLowerCase().includes(String(err.hint).toLowerCase());
+  const outputText = [
+    alreadyHasCode ? rawOutput : `[${err.code}] ${rawOutput}`,
+    err.hint && !alreadyHasHint ? `(hint: ${err.hint})` : '',
+  ].filter(Boolean).join(' ');
+  return { success: false, output: outputText, error: err, ...meta };
+}
+
+/**
+ * Format an error envelope as a short one-line summary for logs and
+ * compact trace rows.
+ */
+export function formatErrorSummary(err) {
+  if (!err) return '';
+  const code = err.code || 'UNKNOWN';
+  const msg = String(err.message || '').replace(/\s+/g, ' ').slice(0, 240);
+  return `[${code}] ${msg}${err.hint ? ` — hint: ${String(err.hint).slice(0, 140)}` : ''}`;
+}
+
+/**
+ * Build a compact hint the next agent turn can consume so it can
+ * self-correct without re-reading a raw stack trace.
+ *
+ * Example:
+ *   "Previous tool call `create_node` failed. [MISSING_RESOURCE] Node
+ *    'chair_99' not found. Hint: call get_scene(slug='cafe') to see
+ *    current node ids."
+ */
+export function buildNextTurnHint({ tool, error }) {
+  if (!error) return '';
+  const parts = [`Previous tool call \`${tool || 'unknown'}\` failed.`];
+  parts.push(`[${error.code || 'UNKNOWN'}] ${error.message || ''}`.trim());
+  if (error.hint) parts.push(`Hint: ${error.hint}`);
+  return parts.join(' ');
+}

package/src/core/usage-normalization.mjs

@@ -0,0 +1,32 @@
+/**
+ * Normalize provider/gateway usage into the npm agent's canonical shape.
+ *
+ * Providers use prompt_tokens/completion_tokens, Anthropic-style callers use
+ * input_tokens/output_tokens, and remote complete events use total_* fields.
+ * Keeping this conversion here prevents each runtime mode from drifting.
+ */
+export function normalizeUsage(usage) {
+    if (!usage) return null;
+
+    const input = usage.input_tokens
+        ?? usage.total_input_tokens
+        ?? usage.prompt_tokens
+        ?? 0;
+    const output = usage.output_tokens
+        ?? usage.total_output_tokens
+        ?? usage.completion_tokens
+        ?? 0;
+    const promptDetails = usage.prompt_tokens_details || {};
+
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        cache_read_input_tokens: usage.cache_read_input_tokens
+            ?? usage.cache_read_tokens
+            ?? promptDetails.cached_tokens
+            ?? 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens
+            ?? usage.cache_creation_tokens
+            ?? 0,
+    };
+}

package/src/local-service/agent-relay.mjs

@@ -110,6 +110,13 @@ export class LocalAgentRelay {
     this.flushingFollowups = false;
     this.cancellationRequested = false;
     this.cancellationEventEmitted = false;
+    // Background-job nudge bookkeeping. See _onBackgroundJobFinished.
+    this._bgUnsubscribe = null;
+    this._bgNotifiedJobIds = new Set();
+    // Trace: per-call_id start-time cache for computing duration on tool_result.
+    // Keyed by call_id | request_id. Cleaned up on tool_result.
+    this._pendingToolCalls = new Map();
+    this._traceSeq = 0;
   }
 
   async listHistorySessions() {
@@ -126,6 +133,24 @@ export class LocalAgentRelay {
     return this._historySnapshot();
   }
 
+  /**
+   * Return full trace entries (unelided args/output/errors) for
+   * /api/trace/export. One entry per tool call. Pass includeTurns=true
+   * to also include user/assistant turns so exports can be correlated.
+   */
+  fullTrace({ includeTurns = false } = {}) {
+    const trace = fullTraceEntries(this.displayHistory);
+    if (!includeTurns) return trace;
+    const turns = this.displayHistory
+      .filter(e => e?.role === 'user' || e?.role === 'assistant')
+      .map(e => ({
+        role: e.role,
+        timestamp: e.timestamp || null,
+        content: typeof e.content === 'string' ? e.content : JSON.stringify(e.content ?? ''),
+      }));
+    return { turns, trace };
+  }
+
   async startNewHistory() {
     if (this.running) {
       const err = new Error('A local agent turn is already running for this workspace');
@@ -137,6 +162,8 @@ export class LocalAgentRelay {
     this.turnCount = 0;
     this.displayHistory = [];
     this.agentHistory = [];
+    this._pendingToolCalls.clear();
+    this._traceSeq = 0;
     this.jsonlWriter = null;
     if (this.client) {
       this.client.sessionId = null;
@@ -288,6 +315,7 @@ export class LocalAgentRelay {
           const data = event.data || {};
           turnHistory.addToolUse(data);
           writer.accumulateToolCall(data.call_id || data.request_id, data.tool || data.name, data.args || data.input);
+          this._traceRecordCall(data);
         }
 
         if (event.type === 'tool_done' || event.type === 'tool_result') {
@@ -299,6 +327,7 @@ export class LocalAgentRelay {
             data.success === false || data.is_error,
             data,
           );
+          this._traceRecordResult(data);
         }
 
         if (event.type === 'complete') {
@@ -471,10 +500,41 @@ export class LocalAgentRelay {
       err.code = 'BAD_REQUEST';
       throw err;
     }
+    // Promote-on-idle: if no turn is currently running, treat the
+    // follow-up as a fresh instruction and start a new turn. Fixes the
+    // "cancelled + typed continue → task ended, task wont resume" gap
+    // where the last turn was cancelled (or the last tool call was a
+    // fire-and-forget background job) and the client still routes input
+    // through the follow-up channel.
     if (!this.running || !this.client) {
-      const err = new Error('No running agent turn to follow up');
-      err.code = 'CONFLICT';
-      throw err;
+      const promotedId = `promoted-followup-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+      // Best-effort acknowledgement so panels can show "picked up where
+      // you left off" instead of a silent restart.
+      try {
+        this.emit('agent_followup_promoted', {
+          intervention_id: promotedId,
+          instruction: text.slice(0, 500),
+          reason: this.running ? 'client-not-initialized' : 'no-running-turn',
+        });
+      } catch { /* SSE failure must never block promotion */ }
+      // Fire and await runTurn; caller's HTTP handler expects a JSON
+      // reply, and we want to signal the promoted status regardless of
+      // how long the new turn takes to spin up.
+      const started = this.runTurn({ prompt: text }).catch((err) => {
+        try {
+          this.emit('agent_error', { turn_id: null, message: `promoted follow-up failed: ${err.message || String(err)}` });
+        } catch { /* ok */ }
+      });
+      // Do not block: return acknowledgement synchronously so the
+      // client can render immediately; the new turn's events stream
+      // over SSE as they normally do.
+      void started;
+      return {
+        ok: true,
+        status: 'promoted_to_new_turn',
+        intervention_id: promotedId,
+        task_id: null,
+      };
     }
 
     const item = {
@@ -532,6 +592,83 @@ export class LocalAgentRelay {
     }
   }
 
+  /**
+   * Background-task nudge — called by backgroundTasks.onExit when any
+   * shell-spawned job finishes. Filters:
+   *
+   *   - Skips jobs that declared an explicit `on_complete` target
+   *     (the caller opted into a specific trigger; nudging would be a
+   *     double dispatch).
+   *   - Skips user-killed jobs (killing signals "I'm done with it").
+   *   - Skips jobs whose cwd is outside this workspace (defensive —
+   *     lets the singleton be shared across processes without cross-talk).
+   *   - Idempotent: each job id nudges at most once.
+   *
+   * Routing:
+   *   - If a turn is running: append to pendingFollowups so the current
+   *     agent turn picks it up naturally at the next event tick.
+   *   - If idle: promote to a fresh runTurn — same path as the
+   *     followup-promote branch, so client behavior is uniform.
+   */
+  _onBackgroundJobFinished(jobDesc) {
+    if (!jobDesc || !jobDesc.id) return;
+    if (this._bgNotifiedJobIds.has(jobDesc.id)) return;
+    if (jobDesc.on_complete) return;
+    if (jobDesc.status === 'killed') return;
+    const ownRoot = this.session?.root_path || '';
+    const jobCwd = jobDesc.cwd || '';
+    if (ownRoot && jobCwd && !jobCwd.startsWith(ownRoot)) return;
+    this._bgNotifiedJobIds.add(jobDesc.id);
+
+    const instruction = this._buildBackgroundJobNudge(jobDesc);
+
+    try {
+      this.emit('agent_background_job_finished', {
+        job_id: jobDesc.id,
+        status: jobDesc.status,
+        exit_code: jobDesc.exit_code,
+        duration_s: jobDesc.duration_s,
+        command: (jobDesc.command || '').slice(0, 240),
+        will_nudge: true,
+      });
+    } catch { /* SSE failure must never block the nudge */ }
+
+    const idempotencyKey = `bg-nudge-${jobDesc.id}`;
+    if (this.running && this.client) {
+      this.pendingFollowups.push({
+        instruction,
+        role: 'user',
+        messageType: 'background_job_nudge',
+        priority: 'normal',
+        idempotencyKey,
+      });
+      // If the runtime is already draining events, flush now; else the
+      // next tool_result cycle will do it.
+      this._flushQueuedFollowups().catch(() => { /* best-effort */ });
+      return;
+    }
+    // Idle — promote a fresh turn.
+    this.runTurn({ prompt: instruction }).catch((err) => {
+      try { this.emit('agent_error', { turn_id: null, message: `bg nudge turn failed: ${err.message || String(err)}` }); }
+      catch { /* ok */ }
+    });
+  }
+
+  _buildBackgroundJobNudge(job) {
+    const tailLines = String(job.tail || '').split('\n').slice(-20).join('\n');
+    const parts = [
+      `Background job \`${job.id}\` finished (status=${job.status}, exit=${job.exit_code}, duration ${job.duration_s}s).`,
+      `Command: ${job.command}`,
+    ];
+    if (tailLines) {
+      parts.push('Recent output:\n```\n' + tailLines + '\n```');
+    } else {
+      parts.push('(no output captured)');
+    }
+    parts.push('Continue from here.');
+    return parts.join('\n\n');
+  }
+
   async _sendFollowupNow(item) {
     const result = await this.client.sendIntervention(item.instruction, {
       idempotencyKey: item.idempotencyKey,
@@ -600,6 +737,21 @@ export class LocalAgentRelay {
       process.chdir(this.session.root_path);
     }
 
+    // Background-task nudge: subscribe once so a `shell {run_in_background:true}`
+    // that finishes AFTER the user cancelled the turn (or after the turn
+    // that started it completed) doesn't die in silence. See
+    // _onBackgroundJobFinished for the routing rules.
+    if (!this._bgUnsubscribe) {
+      const { backgroundTasks } = await import('../core/background-tasks.mjs');
+      this._bgUnsubscribe = backgroundTasks.onExit((jobDesc) => {
+        try { this._onBackgroundJobFinished(jobDesc); }
+        catch (err) {
+          try { this.emit('agent_error', { turn_id: null, message: `bg nudge handler failed: ${err.message || String(err)}` }); }
+          catch { /* ok */ }
+        }
+      });
+    }
+
     const { PluginRegistry } = await import('../plugins/registry.mjs');
     const activePlugins = activePluginNamesFromSession(this.session);
     const pluginDirs = pluginScanDirsFromSession(this.session);
@@ -826,6 +978,68 @@ export class LocalAgentRelay {
     return lines.join('\n');
   }
 
+  // ── Trace ────────────────────────────────────────────────────────
+  // Two entry points fire for every tool: _traceRecordCall on
+  // tool_call / tool_request, _traceRecordResult on tool_result /
+  // tool_done. Together they populate displayHistory with role:'tool'
+  // rows carrying { id, ts, tool, plugin, args, status, output, error?,
+  // duration_ms, sub_agent?, call_id, parent_id?, kind }. The compact
+  // view is derived from these; the full data is written verbatim to
+  // the transcript writer for /api/trace/export.
+
+  _traceRecordCall(data) {
+    const callId = data.call_id || data.request_id || data.tool_id || `call_${++this._traceSeq}`;
+    const startTs = Date.now();
+    this._pendingToolCalls.set(callId, {
+      startTs,
+      tool: data.tool || data.name || '',
+      plugin: data.plugin || data._plugin || null,
+      args: data.args || data.input || {},
+      sub_agent: data.sub_agent || null,
+      parent_id: data.parent_id || data.parent_call_id || null,
+    });
+  }
+
+  _traceRecordResult(data) {
+    const callId = data.call_id || data._callId || data.request_id || data.id || data.tool_use_id;
+    const pending = callId ? this._pendingToolCalls.get(callId) : null;
+    if (callId) this._pendingToolCalls.delete(callId);
+
+    const startTs = pending?.startTs || Date.now();
+    const endTs = Date.now();
+    const durationMs = data.duration_ms || (endTs - startTs);
+    const isError = data.success === false || data.is_error === true || Boolean(data.error);
+
+    // Prefer the structured error envelope from normalizeToolResult if present.
+    const errEnvelope = data.error && typeof data.error === 'object' && data.error.code
+      ? {
+          code: String(data.error.code || 'UNKNOWN'),
+          message: String(data.error.message || data.output || ''),
+          ...(data.error.hint ? { hint: String(data.error.hint) } : {}),
+          ...(process.env.DEBUG && data.error.stack ? { stack: String(data.error.stack) } : {}),
+        }
+      : (isError
+          ? { code: 'UNKNOWN', message: typeof data.output === 'string' ? data.output : (data.message || 'Tool call failed.') }
+          : null);
+
+    this.displayHistory.push({
+      role: 'tool',
+      kind: isError ? 'error' : 'result',
+      tool: pending?.tool || data.tool || data.name || '',
+      plugin: pending?.plugin || data.plugin || data._plugin || null,
+      call_id: callId || null,
+      parent_id: pending?.parent_id || null,
+      sub_agent: pending?.sub_agent || data.sub_agent || null,
+      args: pending?.args || data.args || {},
+      output: data.output ?? data.result ?? data.message ?? '',
+      error: errEnvelope,
+      status: isError ? 'error' : 'ok',
+      duration_ms: durationMs,
+      timestamp: new Date(endTs).toISOString(),
+      order: this.displayHistory.length,
+    });
+  }
+
   _historySnapshot() {
     return {
       ok: true,
@@ -1040,15 +1254,73 @@ function browserMessages(history = []) {
     }));
 }
 
-function browserTraceItems(history = []) {
+// Compact trace summary for the panel — full data lives on the
+// history entry itself (available via /api/trace/export).
+//
+// Handles two entry shapes:
+//   1. Live entries pushed by _traceRecordResult (single row per round-trip,
+//      with kind: 'result'|'error', args, output, error, duration_ms).
+//   2. Resume entries built by local-store.buildResumeHistory (separate
+//      rows per tool_call and tool_result, with kind: 'call'|'result',
+//      only `content` populated).
+//
+// The `type` field preserves the historical `history_tool_<kind>` shape
+// so consumers can distinguish call vs. result vs. error rows without
+// knowing which pipeline produced them.
+export function browserTraceItems(history = []) {
+  return history
+    .filter((entry) => entry?.role === 'tool')
+    .map((entry) => {
+      const kind = entry.kind || (entry.status === 'error' ? 'error' : 'result');
+      const isLive = entry.call_id != null || entry.args !== undefined || entry.error !== undefined;
+      const base = {
+        type: `history_tool_${kind}`,
+        timestamp: entry.timestamp || null,
+        tool: entry.tool || null,
+        kind,
+      };
+      if (!isLive) {
+        // Resume entry — surface content as-is for backward compat.
+        return { ...base, content: typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content || '') };
+      }
+      return {
+        ...base,
+        id: entry.call_id || null,
+        parent_id: entry.parent_id || null,
+        plugin: entry.plugin || null,
+        status: entry.status || (kind === 'error' ? 'error' : 'ok'),
+        duration_ms: entry.duration_ms ?? null,
+        args_summary: elide(typeof entry.args === 'string' ? entry.args : JSON.stringify(entry.args ?? {}), 320),
+        output_summary: elide(typeof entry.output === 'string' ? entry.output : JSON.stringify(entry.output ?? ''), 320),
+        error: entry.error
+          ? { code: entry.error.code, message: elide(entry.error.message, 220), hint: entry.error.hint || null }
+          : null,
+        sub_agent: entry.sub_agent || null,
+      };
+    });
+}
+
+function elide(text, max = 320) {
+  const s = typeof text === 'string' ? text : JSON.stringify(text ?? '');
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+// Full trace entries (unelided) for /api/trace/export.
+export function fullTraceEntries(history = []) {
   return history
     .filter((entry) => entry?.role === 'tool')
     .map((entry) => ({
-      type: `history_tool_${entry.kind || 'event'}`,
+      id: entry.call_id || null,
+      parent_id: entry.parent_id || null,
       timestamp: entry.timestamp || null,
       tool: entry.tool || null,
-      kind: entry.kind || null,
-      content: typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content || ''),
+      plugin: entry.plugin || null,
+      status: entry.status || (entry.kind === 'error' ? 'error' : 'ok'),
+      duration_ms: entry.duration_ms ?? null,
+      args: entry.args ?? null,
+      output: entry.output ?? null,
+      error: entry.error || null,
+      sub_agent: entry.sub_agent || null,
     }));
 }