@kb-labs/agent-cli 0.5.0

package/dist/cli/commands/trace-filter.js

@@ -0,0 +1,153 @@
+import { defineCommand, useLogger } from '@kb-labs/sdk';
+import { loadTrace, formatTraceLoadError } from '@kb-labs/agent-tracing';
+
+// src/cli/commands/trace-filter.ts
+var VALID_EVENT_TYPES = [
+  // New format (detailed trace)
+  "iteration:detail",
+  "llm:call",
+  "tool:execution",
+  "memory:snapshot",
+  "decision:point",
+  "synthesis:forced",
+  "error:captured",
+  "prompt:diff",
+  "tool:filter",
+  "context:trim",
+  "stopping:analysis",
+  "llm:validation",
+  // Legacy format (simple trace)
+  "llm_call",
+  "llm_response",
+  "tool_call",
+  "tool_result",
+  "tool_cache_hit",
+  "task_start",
+  "task_end"
+];
+var trace_filter_default = defineCommand({
+  id: "trace:filter",
+  description: "Filter trace events by type for debugging",
+  handler: {
+    async execute(ctx, input) {
+      const logger = useLogger();
+      const flags = input.flags ?? input;
+      const taskId = flags["task-id"] ?? flags.taskId;
+      const eventType = flags.type;
+      if (!eventType) {
+        const err = error("INVALID_EVENT_TYPE", "Missing required --type flag");
+        ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+        return { exitCode: 1, response: err };
+      }
+      if (!VALID_EVENT_TYPES.includes(eventType)) {
+        const err = error(
+          "INVALID_EVENT_TYPE",
+          `Invalid event type: ${eventType}. Valid types: ${VALID_EVENT_TYPES.join(", ")}`
+        );
+        ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+        return { exitCode: 1, response: err };
+      }
+      try {
+        const loaded = await loadTrace(taskId);
+        if (!loaded.ok) {
+          const code = loaded.error.kind === "invalid_task_id" ? "INVALID_TASK_ID" : loaded.error.kind === "not_found" ? "TRACE_NOT_FOUND" : loaded.error.kind === "too_large" ? "FILE_TOO_LARGE" : "CORRUPTED_TRACE";
+          const err = error(code, formatTraceLoadError(loaded.error));
+          ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+          return { exitCode: 1, response: err };
+        }
+        const { events } = loaded;
+        const filtered = events.filter((e) => e.type === eventType);
+        const response = {
+          success: true,
+          command: "trace:filter",
+          taskId: taskId ?? "",
+          data: {
+            taskId: taskId ?? "",
+            eventType,
+            events: filtered,
+            count: filtered.length
+          },
+          summary: {
+            message: `Found ${filtered.length} ${eventType} events`,
+            severity: "info",
+            actionable: false
+          }
+        };
+        if (flags.json) {
+          ctx.ui.write(JSON.stringify(response, null, 2) + "\n");
+        } else {
+          printHumanReadable(ctx, eventType, filtered);
+        }
+        return { exitCode: 0, response };
+      } catch (err) {
+        logger.error("trace:filter error:", err instanceof Error ? err : void 0);
+        const errResponse = error("IO_ERROR", err instanceof Error ? err.message : String(err));
+        ctx.ui.write(JSON.stringify(errResponse, null, 2) + "\n");
+        return { exitCode: 1, response: errResponse };
+      }
+    }
+  }
+});
+function printHumanReadable(ctx, eventType, events) {
+  ctx.ui.write("\n");
+  ctx.ui.write(`\u{1F50D} Filtered Events: ${eventType}
+`);
+  ctx.ui.write(`Found ${events.length} events
+`);
+  ctx.ui.write("\n");
+  if (events.length === 0) {
+    ctx.ui.write("No events found.\n");
+    return;
+  }
+  const showCount = Math.min(10, events.length);
+  ctx.ui.write(`Showing first ${showCount}/${events.length}:
+`);
+  ctx.ui.write("\n");
+  for (let i = 0; i < showCount; i++) {
+    const event = events[i];
+    if (!event) {
+      continue;
+    }
+    ctx.ui.write(`[${event.seq}] ${event.timestamp} (iteration ${event.iteration || "N/A"})
+`);
+    if (event.type === "llm:call") {
+      const e = event;
+      ctx.ui.write(`  Model: ${e.request.model}, Tokens: ${e.response.usage.totalTokens}, Cost: $${e.cost.totalCost.toFixed(6)}
+`);
+    } else if (event.type === "tool:execution") {
+      const e = event;
+      ctx.ui.write(`  Tool: ${e.tool.name}, Success: ${e.output.success}, Duration: ${e.timing.durationMs}ms
+`);
+    } else if (event.type === "error:captured") {
+      const e = event;
+      ctx.ui.write(`  Error: ${e.error.message.substring(0, 100)}
+`);
+    }
+    ctx.ui.write("\n");
+  }
+  if (events.length > showCount) {
+    ctx.ui.write(`... and ${events.length - showCount} more events
+`);
+    ctx.ui.write("Use --json flag to see all events\n");
+  }
+}
+function error(code, message) {
+  return {
+    success: false,
+    command: "trace:filter",
+    taskId: "",
+    error: {
+      code,
+      message
+    },
+    summary: {
+      message,
+      severity: "error",
+      actionable: true
+    }
+  };
+}
+
+export { trace_filter_default as default };
+//# sourceMappingURL=trace-filter.js.map
+//# sourceMappingURL=trace-filter.js.map

package/dist/cli/commands/trace-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/commands/trace-filter.ts"],"names":[],"mappings":"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","file":"trace-filter.js","sourcesContent":["/**\n * agent:trace:filter - Filter trace events by type (AI-friendly)\n *\n * Usage:\n *   pnpm kb agent:trace:filter <taskId> --type=llm:call\n *   pnpm kb agent:trace:filter <taskId> --type=tool:execution --json\n *   pnpm kb agent:trace:filter <taskId> --type=error:captured\n */\n\nimport { defineCommand, useLogger, type PluginContextV3 } from '@kb-labs/sdk';\nimport type {\n  TraceCommandResponse,\n  FilterResponse,\n  TraceErrorCode,\n} from '@kb-labs/agent-contracts';\nimport type { DetailedTraceEntry } from '@kb-labs/agent-contracts';\nimport { loadTrace, formatTraceLoadError } from '@kb-labs/agent-tracing';\n\n// Valid event types (includes both new colon-separated and legacy snake_case formats)\nconst VALID_EVENT_TYPES: string[] = [\n  // New format (detailed trace)\n  'iteration:detail',\n  'llm:call',\n  'tool:execution',\n  'memory:snapshot',\n  'decision:point',\n  'synthesis:forced',\n  'error:captured',\n  'prompt:diff',\n  'tool:filter',\n  'context:trim',\n  'stopping:analysis',\n  'llm:validation',\n  // Legacy format (simple trace)\n  'llm_call',\n  'llm_response',\n  'tool_call',\n  'tool_result',\n  'tool_cache_hit',\n  'task_start',\n  'task_end',\n];\n\ntype TraceFilterInput = {\n  taskId?: string;\n  'task-id'?: string;\n  type?: string;\n  json?: boolean;\n};\n\ntype TraceFilterResult = { exitCode: number; response?: TraceCommandResponse };\n\nexport default defineCommand({\n  id: 'trace:filter',\n  description: 'Filter trace events by type for debugging',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: TraceFilterInput): Promise<TraceFilterResult> {\n      const logger = useLogger();\n      const flags = (input as any).flags ?? input;\n      const taskId = (flags['task-id'] ?? flags.taskId) as string | undefined;\n      const eventType = flags.type as string | undefined;\n\n    if (!eventType) {\n      const err = error('INVALID_EVENT_TYPE', 'Missing required --type flag');\n      ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n      return { exitCode: 1, response: err };\n    }\n\n    if (!VALID_EVENT_TYPES.includes(eventType)) {\n      const err = error(\n        'INVALID_EVENT_TYPE',\n        `Invalid event type: ${eventType}. Valid types: ${VALID_EVENT_TYPES.join(', ')}`\n      );\n      ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n      return { exitCode: 1, response: err };\n    }\n\n    try {\n      const loaded = await loadTrace(taskId);\n      if (!loaded.ok) {\n        const code: TraceErrorCode =\n          loaded.error.kind === 'invalid_task_id' ? 'INVALID_TASK_ID' :\n          loaded.error.kind === 'not_found' ? 'TRACE_NOT_FOUND' :\n          loaded.error.kind === 'too_large' ? 'FILE_TOO_LARGE' :\n          'CORRUPTED_TRACE';\n        const err = error(code, formatTraceLoadError(loaded.error));\n        ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n        return { exitCode: 1, response: err };\n      }\n\n      const { events } = loaded;\n\n      // Filter by type\n      const filtered = events.filter((e) => e.type === eventType);\n\n      // Build response\n      const response: TraceCommandResponse<FilterResponse> = {\n        success: true,\n        command: 'trace:filter',\n        taskId: taskId ?? '',\n        data: {\n          taskId: taskId ?? '',\n          eventType: eventType,\n          events: filtered,\n          count: filtered.length,\n        },\n        summary: {\n          message: `Found ${filtered.length} ${eventType} events`,\n          severity: 'info',\n          actionable: false,\n        },\n      };\n\n      // Output\n      if (flags.json) {\n        ctx.ui.write(JSON.stringify(response, null, 2) + '\\n');\n      } else {\n        printHumanReadable(ctx, eventType, filtered);\n      }\n\n      return { exitCode: 0, response };\n    } catch (err) {\n      logger.error('trace:filter error:', err instanceof Error ? err : undefined);\n      const errResponse = error('IO_ERROR', err instanceof Error ? err.message : String(err));\n      ctx.ui.write(JSON.stringify(errResponse, null, 2) + '\\n');\n      return { exitCode: 1, response: errResponse };\n    }\n    },\n  },\n});\n\n/**\n * Print human-readable output\n */\nfunction printHumanReadable(ctx: PluginContextV3, eventType: string, events: DetailedTraceEntry[]): void {\n  ctx.ui.write('\\n');\n  ctx.ui.write(`🔍 Filtered Events: ${eventType}\\n`);\n  ctx.ui.write(`Found ${events.length} events\\n`);\n  ctx.ui.write('\\n');\n\n  if (events.length === 0) {\n    ctx.ui.write('No events found.\\n');\n    return;\n  }\n\n  // Show first 10 events\n  const showCount = Math.min(10, events.length);\n  ctx.ui.write(`Showing first ${showCount}/${events.length}:\\n`);\n  ctx.ui.write('\\n');\n\n  for (let i = 0; i < showCount; i++) {\n    const event = events[i];\n    if (!event) {continue;}\n\n    ctx.ui.write(`[${event.seq}] ${event.timestamp} (iteration ${(event as any).iteration || 'N/A'})\\n`);\n\n    // Show event-specific summary\n    if (event.type === 'llm:call') {\n      const e = event as any;\n      ctx.ui.write(`  Model: ${e.request.model}, Tokens: ${e.response.usage.totalTokens}, Cost: $${e.cost.totalCost.toFixed(6)}\\n`);\n    } else if (event.type === 'tool:execution') {\n      const e = event as any;\n      ctx.ui.write(`  Tool: ${e.tool.name}, Success: ${e.output.success}, Duration: ${e.timing.durationMs}ms\\n`);\n    } else if (event.type === 'error:captured') {\n      const e = event as any;\n      ctx.ui.write(`  Error: ${e.error.message.substring(0, 100)}\\n`);\n    }\n\n    ctx.ui.write('\\n');\n  }\n\n  if (events.length > showCount) {\n    ctx.ui.write(`... and ${events.length - showCount} more events\\n`);\n    ctx.ui.write('Use --json flag to see all events\\n');\n  }\n}\n\n/**\n * Create error response\n */\nfunction error(code: TraceErrorCode, message: string): TraceCommandResponse {\n  return {\n    success: false,\n    command: 'trace:filter',\n    taskId: '',\n    error: {\n      code,\n      message,\n    },\n    summary: {\n      message,\n      severity: 'error',\n      actionable: true,\n    },\n  };\n}\n"]}

package/dist/cli/commands/trace-iteration.d.ts

@@ -0,0 +1,18 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * agent:trace:iteration - View specific iteration details (AI-friendly)
+ *
+ * Usage:
+ *   pnpm kb agent:trace:iteration <taskId> --iteration=3
+ *   pnpm kb agent:trace:iteration <taskId> --iteration=5 --json
+ */
+type TraceIterationInput = {
+    taskId?: string;
+    'task-id'?: string;
+    iteration?: number;
+    json?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, TraceIterationInput, unknown>;
+
+export { _default as default };

package/dist/cli/commands/trace-iteration.js

@@ -0,0 +1,192 @@
+import { defineCommand, useLogger } from '@kb-labs/sdk';
+import { loadTrace, formatTraceLoadError } from '@kb-labs/agent-tracing';
+
+// src/cli/commands/trace-iteration.ts
+
+// src/cli/commands/trace-event-normalizer.ts
+function normalizeTraceEvents(events) {
+  const out = [];
+  let currentIteration = 0;
+  for (const raw of events) {
+    const type = String(raw.type ?? "");
+    const data = getEventData(raw);
+    const explicitIteration = asNumber(raw.iteration) ?? asNumber(data.iteration);
+    if (type === "iteration:start") {
+      currentIteration = explicitIteration ?? Math.max(1, currentIteration + 1);
+    }
+    const iteration = explicitIteration ?? currentIteration;
+    out.push({ raw, type, data, iteration });
+  }
+  return out;
+}
+function getEventData(event) {
+  const data = event.data;
+  if (data && typeof data === "object") {
+    return data;
+  }
+  return {};
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isFinite(n)) {
+      return n;
+    }
+  }
+  return void 0;
+}
+
+// src/cli/commands/trace-iteration.ts
+var trace_iteration_default = defineCommand({
+  id: "trace:iteration",
+  description: "View all events for a specific iteration",
+  handler: {
+    async execute(ctx, input) {
+      const logger = useLogger();
+      const flags = input.flags ?? input;
+      const taskId = flags["task-id"] ?? flags.taskId;
+      const iteration = typeof flags.iteration === "string" ? parseInt(flags.iteration, 10) : flags.iteration;
+      if (iteration === void 0 || iteration < 1) {
+        const err = error("INVALID_ITERATION", "Missing or invalid --iteration flag (must be >= 1)");
+        ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+        return { exitCode: 1, response: err };
+      }
+      try {
+        const loaded = await loadTrace(taskId);
+        if (!loaded.ok) {
+          const code = loaded.error.kind === "invalid_task_id" ? "INVALID_TASK_ID" : loaded.error.kind === "not_found" ? "TRACE_NOT_FOUND" : loaded.error.kind === "too_large" ? "FILE_TOO_LARGE" : "CORRUPTED_TRACE";
+          const err = error(code, formatTraceLoadError(loaded.error));
+          ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+          return { exitCode: 1, response: err };
+        }
+        const normalized = normalizeTraceEvents(loaded.events);
+        const filtered = normalized.filter((e) => e.iteration === iteration).map((e) => e.raw);
+        if (filtered.length === 0) {
+          const err = error("INVALID_ITERATION", `No events found for iteration ${iteration}`);
+          ctx.ui.write(JSON.stringify(err, null, 2) + "\n");
+          return { exitCode: 1, response: err };
+        }
+        const summary = calculateIterationSummary(filtered);
+        const response = {
+          success: true,
+          command: "trace:iteration",
+          taskId: taskId ?? "",
+          data: {
+            taskId: taskId ?? "",
+            iteration,
+            events: filtered,
+            summary
+          },
+          summary: {
+            message: `Iteration ${iteration}: ${summary.eventCount} events, ${summary.llmCalls} LLM calls, ${summary.toolCalls} tool calls`,
+            severity: summary.errors > 0 ? "warning" : "info",
+            actionable: summary.errors > 0
+          }
+        };
+        if (flags.json) {
+          ctx.ui.write(JSON.stringify(response, null, 2) + "\n");
+        } else {
+          printHumanReadable(ctx, iteration, filtered, summary);
+        }
+        return { exitCode: 0, response };
+      } catch (err) {
+        logger.error("trace:iteration error:", err instanceof Error ? err : void 0);
+        const errResponse = error("IO_ERROR", err instanceof Error ? err.message : String(err));
+        ctx.ui.write(JSON.stringify(errResponse, null, 2) + "\n");
+        return { exitCode: 1, response: errResponse };
+      }
+    }
+  }
+});
+function calculateIterationSummary(events) {
+  const llmEvents = events.filter((e) => {
+    const type = String(e.type ?? "");
+    return type === "llm:start" || type === "llm:call" || type === "llm_call";
+  });
+  const toolEvents = events.filter((e) => {
+    const type = String(e.type ?? "");
+    return type === "tool:start" || type === "tool:execution" || type === "tool_call";
+  });
+  const errorEvents = events.filter((e) => {
+    const type = String(e.type ?? "");
+    return type === "error:captured" || type === "agent:error" || type === "tool:error";
+  });
+  const timestamps = events.map((e) => new Date(e.timestamp).getTime());
+  const durationMs = timestamps.length > 0 ? Math.max(...timestamps) - Math.min(...timestamps) : 0;
+  return {
+    eventCount: events.length,
+    llmCalls: llmEvents.length,
+    toolCalls: toolEvents.length,
+    errors: errorEvents.length,
+    durationMs
+  };
+}
+function printHumanReadable(ctx, iteration, events, summary) {
+  ctx.ui.write("\n");
+  ctx.ui.write(`\u{1F504} Iteration ${iteration}
+`);
+  ctx.ui.write("\n");
+  ctx.ui.write("\u{1F4CA} Summary:\n");
+  ctx.ui.write(`  Total events: ${summary.eventCount}
+`);
+  ctx.ui.write(`  LLM calls: ${summary.llmCalls}
+`);
+  ctx.ui.write(`  Tool calls: ${summary.toolCalls}
+`);
+  ctx.ui.write(`  Errors: ${summary.errors}
+`);
+  ctx.ui.write(`  Duration: ${summary.durationMs}ms
+`);
+  ctx.ui.write("\n");
+  ctx.ui.write("\u{1F4DD} Events Timeline:\n");
+  ctx.ui.write("\n");
+  const grouped = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const existing = grouped.get(event.type) || [];
+    existing.push(event);
+    grouped.set(event.type, existing);
+  }
+  for (const [type, typeEvents] of grouped) {
+    ctx.ui.write(`  ${type}: ${typeEvents.length}
+`);
+    if ((type === "llm:end" || type === "llm:call") && typeEvents.length > 0) {
+      const llmEvent = typeEvents[0];
+      const tokens = llmEvent?.data?.tokensUsed ?? llmEvent?.response?.usage?.totalTokens ?? 0;
+      ctx.ui.write(`    Tokens: ${tokens}
+`);
+    } else if (type === "tool:end" || type === "tool:start" || type === "tool:execution") {
+      const toolNames = typeEvents.map((e) => e?.data?.toolName || e?.tool?.name || "unknown");
+      ctx.ui.write(`    Tools: ${[...new Set(toolNames)].join(", ")}
+`);
+    } else if (type === "error:captured" && typeEvents.length > 0) {
+      const errorEvent = typeEvents[0];
+      ctx.ui.write(`    \u26A0\uFE0F  ${errorEvent.error.message.substring(0, 100)}
+`);
+    }
+  }
+  ctx.ui.write("\n");
+  ctx.ui.write("Use --json flag to see full event details\n");
+}
+function error(code, message) {
+  return {
+    success: false,
+    command: "trace:iteration",
+    taskId: "",
+    error: {
+      code,
+      message
+    },
+    summary: {
+      message,
+      severity: "error",
+      actionable: true
+    }
+  };
+}
+
+export { trace_iteration_default as default };
+//# sourceMappingURL=trace-iteration.js.map
+//# sourceMappingURL=trace-iteration.js.map

package/dist/cli/commands/trace-iteration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/commands/trace-event-normalizer.ts","../../../src/cli/commands/trace-iteration.ts"],"names":[],"mappings":"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","file":"trace-iteration.js","sourcesContent":["import type { DetailedTraceEntry } from '@kb-labs/agent-contracts';\n\nexport type NormalizedTraceEvent = {\n  raw: DetailedTraceEntry;\n  type: string;\n  data: Record<string, unknown>;\n  iteration: number;\n};\n\nexport function normalizeTraceEvents(events: DetailedTraceEntry[]): NormalizedTraceEvent[] {\n  const out: NormalizedTraceEvent[] = [];\n  let currentIteration = 0;\n\n  for (const raw of events) {\n    const type = String((raw as any).type ?? '');\n    const data = getEventData(raw);\n\n    const explicitIteration = asNumber((raw as any).iteration) ?? asNumber(data.iteration);\n    if (type === 'iteration:start') {\n      currentIteration = explicitIteration ?? Math.max(1, currentIteration + 1);\n    }\n\n    const iteration = explicitIteration ?? currentIteration;\n    out.push({ raw, type, data, iteration });\n  }\n\n  return out;\n}\n\nexport function getEventData(event: DetailedTraceEntry): Record<string, unknown> {\n  const data = (event as any).data;\n  if (data && typeof data === 'object') {\n    return data as Record<string, unknown>;\n  }\n  return {};\n}\n\nexport function asNumber(value: unknown): number | undefined {\n  if (typeof value === 'number' && Number.isFinite(value)) {\n    return value;\n  }\n  if (typeof value === 'string') {\n    const n = Number(value);\n    if (Number.isFinite(n)) {\n      return n;\n    }\n  }\n  return undefined;\n}\n","/**\n * agent:trace:iteration - View specific iteration details (AI-friendly)\n *\n * Usage:\n *   pnpm kb agent:trace:iteration <taskId> --iteration=3\n *   pnpm kb agent:trace:iteration <taskId> --iteration=5 --json\n */\n\nimport { defineCommand, useLogger, type PluginContextV3 } from '@kb-labs/sdk';\nimport type {\n  TraceCommandResponse,\n  IterationResponse,\n  TraceErrorCode,\n} from '@kb-labs/agent-contracts';\nimport type { DetailedTraceEntry } from '@kb-labs/agent-contracts';\nimport { loadTrace, formatTraceLoadError } from '@kb-labs/agent-tracing';\nimport { normalizeTraceEvents } from './trace-event-normalizer.js';\n\ntype TraceIterationInput = {\n  taskId?: string;\n  'task-id'?: string;\n  iteration?: number;\n  json?: boolean;\n};\n\ntype TraceIterationResult = { exitCode: number; response?: TraceCommandResponse };\n\nexport default defineCommand({\n  id: 'trace:iteration',\n  description: 'View all events for a specific iteration',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: TraceIterationInput): Promise<TraceIterationResult> {\n      const logger = useLogger();\n      const flags = (input as any).flags ?? input;\n      const taskId = (flags['task-id'] ?? flags.taskId) as string | undefined;\n      const iteration = typeof flags.iteration === 'string' ? parseInt(flags.iteration, 10) : (flags.iteration as number | undefined);\n\n    if (iteration === undefined || iteration < 1) {\n      const err = error('INVALID_ITERATION', 'Missing or invalid --iteration flag (must be >= 1)');\n      ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n      return { exitCode: 1, response: err };\n    }\n\n    try {\n      const loaded = await loadTrace(taskId);\n      if (!loaded.ok) {\n        const code: TraceErrorCode =\n          loaded.error.kind === 'invalid_task_id' ? 'INVALID_TASK_ID' :\n          loaded.error.kind === 'not_found' ? 'TRACE_NOT_FOUND' :\n          loaded.error.kind === 'too_large' ? 'FILE_TOO_LARGE' :\n          'CORRUPTED_TRACE';\n        const err = error(code, formatTraceLoadError(loaded.error));\n        ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n        return { exitCode: 1, response: err };\n      }\n\n      const normalized = normalizeTraceEvents(loaded.events);\n      const filtered = normalized.filter((e) => e.iteration === iteration).map((e) => e.raw);\n\n      if (filtered.length === 0) {\n        const err = error('INVALID_ITERATION', `No events found for iteration ${iteration}`);\n        ctx.ui.write(JSON.stringify(err, null, 2) + '\\n');\n        return { exitCode: 1, response: err };\n      }\n\n      // Calculate summary\n      const summary = calculateIterationSummary(filtered);\n\n      // Build response\n      const response: TraceCommandResponse<IterationResponse> = {\n        success: true,\n        command: 'trace:iteration',\n        taskId: taskId ?? '',\n        data: {\n          taskId: taskId ?? '',\n          iteration,\n          events: filtered,\n          summary,\n        },\n        summary: {\n          message: `Iteration ${iteration}: ${summary.eventCount} events, ${summary.llmCalls} LLM calls, ${summary.toolCalls} tool calls`,\n          severity: summary.errors > 0 ? 'warning' : 'info',\n          actionable: summary.errors > 0,\n        },\n      };\n\n      // Output\n      if (flags.json) {\n        ctx.ui.write(JSON.stringify(response, null, 2) + '\\n');\n      } else {\n        printHumanReadable(ctx, iteration, filtered, summary);\n      }\n\n      return { exitCode: 0, response };\n    } catch (err) {\n      logger.error('trace:iteration error:', err instanceof Error ? err : undefined);\n      const errResponse = error('IO_ERROR', err instanceof Error ? err.message : String(err));\n      ctx.ui.write(JSON.stringify(errResponse, null, 2) + '\\n');\n      return { exitCode: 1, response: errResponse };\n    }\n    },\n  },\n});\n\n/**\n * Calculate iteration summary\n */\nfunction calculateIterationSummary(events: DetailedTraceEntry[]): IterationResponse['summary'] {\n  const llmEvents = events.filter((e) => {\n    const type = String((e as { type?: unknown }).type ?? '');\n    return type === 'llm:start' || type === 'llm:call' || type === 'llm_call';\n  });\n  const toolEvents = events.filter((e) => {\n    const type = String((e as { type?: unknown }).type ?? '');\n    return type === 'tool:start' || type === 'tool:execution' || type === 'tool_call';\n  });\n  const errorEvents = events.filter((e) => {\n    const type = String((e as { type?: unknown }).type ?? '');\n    return type === 'error:captured' || type === 'agent:error' || type === 'tool:error';\n  });\n\n  // Calculate duration (from first to last event timestamp)\n  const timestamps = events.map((e) => new Date(e.timestamp).getTime());\n  const durationMs = timestamps.length > 0 ? Math.max(...timestamps) - Math.min(...timestamps) : 0;\n\n  return {\n    eventCount: events.length,\n    llmCalls: llmEvents.length,\n    toolCalls: toolEvents.length,\n    errors: errorEvents.length,\n    durationMs,\n  };\n}\n\n/**\n * Print human-readable output\n */\nfunction printHumanReadable(\n  ctx: PluginContextV3,\n  iteration: number,\n  events: DetailedTraceEntry[],\n  summary: IterationResponse['summary']\n): void {\n  ctx.ui.write('\\n');\n  ctx.ui.write(`🔄 Iteration ${iteration}\\n`);\n  ctx.ui.write('\\n');\n\n  ctx.ui.write('📊 Summary:\\n');\n  ctx.ui.write(`  Total events: ${summary.eventCount}\\n`);\n  ctx.ui.write(`  LLM calls: ${summary.llmCalls}\\n`);\n  ctx.ui.write(`  Tool calls: ${summary.toolCalls}\\n`);\n  ctx.ui.write(`  Errors: ${summary.errors}\\n`);\n  ctx.ui.write(`  Duration: ${summary.durationMs}ms\\n`);\n  ctx.ui.write('\\n');\n\n  ctx.ui.write('📝 Events Timeline:\\n');\n  ctx.ui.write('\\n');\n\n  // Group events by type for better readability\n  const grouped = new Map<string, DetailedTraceEntry[]>();\n  for (const event of events) {\n    const existing = grouped.get(event.type) || [];\n    existing.push(event);\n    grouped.set(event.type, existing);\n  }\n\n  // Show event counts\n  for (const [type, typeEvents] of grouped) {\n    ctx.ui.write(`  ${type}: ${typeEvents.length}\\n`);\n\n    // Show details for important events\n    if ((type === 'llm:end' || type === 'llm:call') && typeEvents.length > 0) {\n      const llmEvent = typeEvents[0] as any;\n      const tokens = llmEvent?.data?.tokensUsed ?? llmEvent?.response?.usage?.totalTokens ?? 0;\n      ctx.ui.write(`    Tokens: ${tokens}\\n`);\n    } else if (type === 'tool:end' || type === 'tool:start' || type === 'tool:execution') {\n      const toolNames = (typeEvents as any[]).map((e) => e?.data?.toolName || e?.tool?.name || 'unknown');\n      ctx.ui.write(`    Tools: ${[...new Set(toolNames)].join(', ')}\\n`);\n    } else if (type === 'error:captured' && typeEvents.length > 0) {\n      const errorEvent = typeEvents[0] as any;\n      ctx.ui.write(`    ⚠️  ${errorEvent.error.message.substring(0, 100)}\\n`);\n    }\n  }\n\n  ctx.ui.write('\\n');\n  ctx.ui.write('Use --json flag to see full event details\\n');\n}\n\n/**\n * Create error response\n */\nfunction error(code: TraceErrorCode, message: string): TraceCommandResponse {\n  return {\n    success: false,\n    command: 'trace:iteration',\n    taskId: '',\n    error: {\n      code,\n      message,\n    },\n    summary: {\n      message,\n      severity: 'error',\n      actionable: true,\n    },\n  };\n}\n"]}

package/dist/cli/commands/trace-stats.d.ts

@@ -0,0 +1,17 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * agent:trace:stats - Show trace statistics (AI-friendly)
+ *
+ * Usage:
+ *   pnpm kb agent:trace:stats <taskId>
+ *   pnpm kb agent:trace:stats <taskId> --json
+ */
+type TraceStatsInput = {
+    taskId?: string;
+    'task-id'?: string;
+    json?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, TraceStatsInput, unknown>;
+
+export { _default as default };