@kb-labs/agent-cli 0.5.0

package/dist/index.js

@@ -0,0 +1,473 @@
+import { combinePermissions, kbPlatformPreset, defineCommandFlags } from '@kb-labs/sdk';
+import { AGENTS_WS_CHANNELS, AGENTS_ROUTES, AGENTS_WS_BASE_PATH, AGENTS_BASE_PATH } from '@kb-labs/agent-contracts';
+
+// src/manifest.ts
+var runFlags = {
+  task: {
+    type: "string",
+    description: "Task description"
+  },
+  mode: {
+    type: "string",
+    description: "Agent mode: execute (default), plan, edit, debug",
+    default: "execute"
+  },
+  "session-id": {
+    type: "string",
+    description: "Session ID (auto-generated if not provided)"
+  },
+  complexity: {
+    type: "string",
+    description: "Task complexity (for plan mode): simple, medium, complex"
+  },
+  approve: {
+    type: "boolean",
+    description: "Auto-approve generated plan (supported with --mode=plan)",
+    default: false
+  },
+  execute: {
+    type: "boolean",
+    description: "After plan is approved, immediately execute it (use with --mode=plan --approve)",
+    default: false
+  },
+  files: {
+    type: "array",
+    description: "Target files (for edit mode)"
+  },
+  trace: {
+    type: "string",
+    description: "Trace file path (for debug mode)"
+  },
+  "dry-run": {
+    type: "boolean",
+    description: "Preview changes without applying (for edit mode)",
+    default: false
+  },
+  verbose: {
+    type: "boolean",
+    description: "Verbose output",
+    default: false
+  },
+  debug: {
+    type: "boolean",
+    description: "Enable debug mode: emit full prompts and responses as llm:debug events",
+    default: false
+  },
+  timeout: {
+    type: "number",
+    description: "Abort agent execution after this many seconds (exit code 124). No timeout by default."
+  },
+  budget: {
+    type: "number",
+    description: "Override token budget (e.g. 300000 for heavy tasks). Overrides config value."
+  },
+  json: {
+    type: "boolean",
+    description: "Output structured JSON result instead of human-readable output."
+  }
+};
+var pluginPermissions = combinePermissions().with(kbPlatformPreset).withFs({
+  mode: "readWrite",
+  allow: [".agent-memory/**", "**/*"]
+  // Allow filesystem operations in working dir
+}).withPlatform({
+  llm: true,
+  // Full LLM access for agent execution
+  cache: ["agent:"],
+  // Cache namespace prefix
+  analytics: true
+  // Track agent usage
+}).withQuotas({
+  timeoutMs: 18e5,
+  // 30 min for complex tasks
+  memoryMb: 1024
+}).build();
+var manifest = {
+  schema: "kb.plugin/3",
+  id: "@kb-labs/agent",
+  version: "0.1.0",
+  display: {
+    name: "Agent System",
+    description: "Autonomous agent system with LLM tool calling, task orchestration, and tier escalation.",
+    tags: ["agent", "autonomous", "llm", "orchestration"]
+  },
+  // Configuration lives under kb.config.json -> agents
+  configSection: "agents",
+  platform: {
+    requires: ["llm"],
+    optional: ["cache", "analytics", "logger"]
+  },
+  cli: {
+    commands: [
+      {
+        id: "agent:run",
+        group: "agent",
+        describe: "Run agent with specified mode (execute/plan/edit/debug)",
+        longDescription: "Unified agent command with multiple modes: execute (default) - run task immediately, plan - generate execution plan without running, edit - modify existing files, debug - analyze errors with trace context. Supports filesystem, search, shell, memory, and user interaction tools.",
+        handler: "./cli/commands/run.js#default",
+        handlerPath: "./cli/commands/run.js",
+        flags: defineCommandFlags(runFlags),
+        examples: [
+          'kb agent run --task="Create analytics system"',
+          'kb agent run --mode=plan --task="Add auth" --complexity=complex',
+          'kb agent run --mode=plan --task="Add auth" --approve',
+          'kb agent run --mode=plan --task="Add auth" --approve --execute',
+          'kb agent run --mode=edit --task="Fix bug" --files src/auth.ts',
+          'kb agent run --mode=debug --task="Why crash?" --trace .kb/traces/trace-123.json',
+          'kb agent run --task="Refactor auth module" --timeout=120'
+        ]
+      },
+      // Trace debugging commands (AI-friendly)
+      {
+        id: "agent:trace:stats",
+        group: "agent",
+        describe: "Show trace statistics with cost and performance metrics",
+        longDescription: "Analyze trace file to show comprehensive statistics: iterations, LLM calls, token usage, tool usage, timing, and cost. Supports --json flag for AI agent consumption.",
+        handler: "./cli/commands/trace-stats.js#default",
+        handlerPath: "./cli/commands/trace-stats.js",
+        flags: defineCommandFlags({
+          "task-id": { type: "string", description: "Task ID or trace filename" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent trace stats --task-id=task-2026-01-29",
+          "kb agent trace stats --task-id=task-123 --json"
+        ]
+      },
+      {
+        id: "agent:trace:filter",
+        group: "agent",
+        describe: "Filter trace events by type for debugging",
+        longDescription: "Filter trace events by type (llm:call, tool:execution, error:captured, etc.). Use this to debug specific aspects of agent execution. Supports --json flag for programmatic access.",
+        handler: "./cli/commands/trace-filter.js#default",
+        handlerPath: "./cli/commands/trace-filter.js",
+        flags: defineCommandFlags({
+          "task-id": { type: "string", description: "Task ID or trace filename" },
+          type: { type: "string", description: "Event type to filter (llm:call, tool:execution, etc.)" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent trace filter --task-id=task-123 --type=llm:call",
+          "kb agent trace filter --task-id=task-123 --type=error:captured --json"
+        ]
+      },
+      {
+        id: "agent:trace:iteration",
+        group: "agent",
+        describe: "View all events for a specific iteration",
+        longDescription: "Show all trace events for a specific iteration number. Useful for debugging what happened in a particular loop iteration. Includes summary statistics and event timeline.",
+        handler: "./cli/commands/trace-iteration.js#default",
+        handlerPath: "./cli/commands/trace-iteration.js",
+        flags: defineCommandFlags({
+          "task-id": { type: "string", description: "Task ID or trace filename" },
+          iteration: { type: "number", description: "Iteration number (1-based)" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent trace iteration --task-id=task-123 --iteration=3",
+          "kb agent trace iteration --task-id=task-123 --iteration=5 --json"
+        ]
+      },
+      {
+        id: "agent:trace:context",
+        group: "agent",
+        describe: "View what the LLM sees at each iteration \u2014 context window, truncations, responses",
+        longDescription: "Shows the full context timeline for debugging agent behavior. For each LLM call: what messages are in the sliding window, what was truncated/dropped, and what the LLM responded with.",
+        handler: "./cli/commands/trace-context.js#default",
+        handlerPath: "./cli/commands/trace-context.js",
+        flags: defineCommandFlags({
+          "task-id": { type: "string", description: "Task ID or trace filename" },
+          iteration: { type: "number", description: "Filter to specific iteration" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent trace context --task-id=task-123",
+          "kb agent trace context --task-id=task-123 --iteration=3",
+          "kb agent trace context --task-id=task-123 --json"
+        ]
+      },
+      {
+        id: "agent:trace:diagnose",
+        group: "agent",
+        describe: 'Quick diagnostic analysis \u2014 answers "what went wrong?" in one command',
+        longDescription: "Comprehensive diagnostic report for agent execution. Analyzes errors, context window health (drops, truncations), tool failures, LLM reasoning text, loop detection, and quality indicators. One command to understand any agent issue.",
+        handler: "./cli/commands/trace-diagnose.js#default",
+        handlerPath: "./cli/commands/trace-diagnose.js",
+        flags: defineCommandFlags({
+          "task-id": { type: "string", description: "Task ID or trace filename" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent trace diagnose --task-id=task-123",
+          "kb agent trace diagnose --task-id=task-123 --json"
+        ]
+      },
+      {
+        id: "agent:quality:report",
+        group: "agent",
+        describe: "Show quality control report for recent agent runs",
+        longDescription: "Aggregates agent KPI telemetry from analytics buffer and shows quality, token usage, tool efficiency, drift, and regression alerts. Useful for continuous quality control and cost/performance monitoring.",
+        handler: "./cli/commands/quality-report.js#default",
+        handlerPath: "./cli/commands/quality-report.js",
+        flags: defineCommandFlags({
+          days: { type: "number", description: "Lookback period in days", default: 1 },
+          limit: { type: "number", description: "Max KPI runs to analyze", default: 200 },
+          "session-id": { type: "string", description: "Filter by session ID" },
+          json: { type: "boolean", description: "Output JSON for automation", default: false }
+        }),
+        examples: [
+          "kb agent quality report",
+          "kb agent quality report --days=7",
+          "kb agent quality report --session-id=session-123",
+          "kb agent quality report --days=3 --json"
+        ]
+      },
+      // File change history commands
+      {
+        id: "agent:history",
+        group: "agent",
+        describe: "Show file change history for agent sessions",
+        longDescription: "View file changes made by agents during execution. Filter by session, file, or agent. Shows timestamps, operations, and change metadata.",
+        handler: "./cli/commands/history.js#default",
+        handlerPath: "./cli/commands/history.js",
+        flags: defineCommandFlags({
+          "session-id": { type: "string", description: "Session ID to filter by" },
+          file: { type: "string", description: "File path to filter by" },
+          "agent-id": { type: "string", description: "Agent ID to filter by" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent history",
+          "kb agent history --session-id=session-123",
+          "kb agent history --file=src/index.ts",
+          "kb agent history --agent-id=agent-abc --json"
+        ]
+      },
+      {
+        id: "agent:diff",
+        group: "agent",
+        describe: "Show diff for specific file change",
+        longDescription: "Display line-by-line diff for a specific file change. Shows additions, deletions, and modifications with context.",
+        handler: "./cli/commands/diff.js#default",
+        handlerPath: "./cli/commands/diff.js",
+        flags: defineCommandFlags({
+          "change-id": { type: "string", description: "Change ID to show diff for" },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent diff --change-id=change-abc123",
+          "kb agent diff --change-id=change-abc123 --json"
+        ]
+      },
+      {
+        id: "agent:rollback",
+        group: "agent",
+        describe: "Rollback file changes made by agents",
+        longDescription: "Rollback file changes made by agents. Supports rollback by change ID, file path, agent ID, session, or timestamp. Use --dry-run to preview changes before applying.",
+        handler: "./cli/commands/rollback.js#default",
+        handlerPath: "./cli/commands/rollback.js",
+        flags: defineCommandFlags({
+          "change-id": { type: "string", description: "Change ID to rollback" },
+          file: { type: "string", description: "File path to rollback all changes for" },
+          "agent-id": { type: "string", description: "Agent ID to rollback all changes by" },
+          "session-id": { type: "string", description: "Session ID to rollback all changes in" },
+          after: { type: "string", description: "Rollback all changes after timestamp (ISO 8601)" },
+          force: { type: "boolean", description: "Force rollback even with conflicts", default: false },
+          "dry-run": { type: "boolean", description: "Preview rollback without applying", default: false },
+          json: { type: "boolean", description: "Output JSON for AI agents", default: false }
+        }),
+        examples: [
+          "kb agent rollback --change-id=change-abc123",
+          "kb agent rollback --file=src/index.ts --dry-run",
+          "kb agent rollback --agent-id=agent-abc",
+          "kb agent rollback --session-id=session-123",
+          'kb agent rollback --after="2026-02-16T10:00:00Z" --json'
+        ]
+      }
+    ]
+  },
+  capabilities: [],
+  permissions: pluginPermissions,
+  // REST API for Agent UI
+  rest: {
+    basePath: AGENTS_BASE_PATH,
+    defaults: {
+      timeoutMs: 18e5
+      // 30 min for long-running tasks
+    },
+    routes: [
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.RUN,
+        description: "Start a new agent run",
+        handler: "./rest/handlers/run-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.RUN_STATUS,
+        description: "Get status of a run",
+        handler: "./rest/handlers/status-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.CORRECT,
+        description: "Send correction to running agent(s)",
+        handler: "./rest/handlers/correct-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.STOP,
+        description: "Stop a running agent",
+        handler: "./rest/handlers/stop-handler.js",
+        security: ["none"]
+      },
+      // Session management routes
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSIONS_LIST,
+        description: "List all sessions",
+        handler: "./rest/handlers/list-sessions-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_GET,
+        description: "Get session details",
+        handler: "./rest/handlers/get-session-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_CREATE,
+        description: "Create a new session",
+        handler: "./rest/handlers/create-session-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_TURNS,
+        description: "Get session turns (turn-based UI)",
+        handler: "./rest/handlers/get-session-turns-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_PLAN_GET,
+        description: "Get current session plan",
+        handler: "./rest/handlers/get-session-plan-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_PLAN_APPROVE,
+        description: "Approve current session plan",
+        handler: "./rest/handlers/approve-session-plan-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_PLAN_EXECUTE,
+        description: "Execute approved session plan",
+        handler: "./rest/handlers/execute-session-plan-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_PLAN_SPEC,
+        description: "Generate detailed spec from approved plan",
+        handler: "./rest/handlers/generate-spec-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_PLAN_SPEC_GET,
+        description: "Get current session spec",
+        handler: "./rest/handlers/get-spec-handler.js",
+        security: ["none"]
+      },
+      // File change history routes (rollback & approve)
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_CHANGES,
+        description: "List file changes for session (optionally filtered by runId)",
+        handler: "./rest/handlers/list-file-changes-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "GET",
+        path: AGENTS_ROUTES.SESSION_CHANGE_DIFF,
+        description: "Get unified diff for a specific file change",
+        handler: "./rest/handlers/get-file-diff-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_ROLLBACK,
+        description: "Rollback file changes for a session/run",
+        handler: "./rest/handlers/rollback-handler.js",
+        security: ["none"]
+      },
+      {
+        method: "POST",
+        path: AGENTS_ROUTES.SESSION_APPROVE,
+        description: "Approve file changes for a session/run",
+        handler: "./rest/handlers/approve-handler.js",
+        security: ["none"]
+      }
+    ]
+  },
+  // WebSocket for real-time event streaming
+  ws: {
+    basePath: AGENTS_WS_BASE_PATH,
+    defaults: {
+      auth: "none",
+      idleTimeoutMs: 36e5
+      // 1 hour
+    },
+    channels: [
+      {
+        path: AGENTS_WS_CHANNELS.SESSION_STREAM,
+        description: "Persistent session stream (all runs in session)",
+        handler: "./ws/session-stream-handler.js",
+        auth: "none"
+      }
+    ]
+  },
+  artifacts: [
+    {
+      id: "agent.memory.json",
+      pathTemplate: ".agent-memory/memory.json",
+      description: "Persistent agent memory (facts, sessions, project context)."
+    }
+  ],
+  studio: {
+    version: 2,
+    remoteName: "agentPlugin",
+    pages: [
+      {
+        id: "agent.overview",
+        title: "Agent",
+        icon: "RobotOutlined",
+        route: "/p/agent",
+        entry: "./AgentsPage",
+        order: 1
+      }
+    ],
+    menus: [
+      {
+        id: "agent",
+        label: "Agent",
+        icon: "RobotOutlined",
+        target: "agent.overview",
+        order: 30
+      }
+    ]
+  }
+};
+
+export { manifest };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/manifest.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * KB Labs Agent Plugin - Manifest V3\n */\n\nimport {\n  combinePermissions,\n  kbPlatformPreset,\n  defineCommandFlags,\n} from '@kb-labs/sdk';\nimport {\n  AGENTS_BASE_PATH,\n  AGENTS_WS_BASE_PATH,\n  AGENTS_ROUTES,\n  AGENTS_WS_CHANNELS,\n} from '@kb-labs/agent-contracts';\n\n/**\n * Command flags for agent:run (unified command with modes)\n */\nconst runFlags = {\n  task: {\n    type: 'string',\n    description: 'Task description',\n  },\n  mode: {\n    type: 'string',\n    description: 'Agent mode: execute (default), plan, edit, debug',\n    default: 'execute',\n  },\n  'session-id': {\n    type: 'string',\n    description: 'Session ID (auto-generated if not provided)',\n  },\n  complexity: {\n    type: 'string',\n    description: 'Task complexity (for plan mode): simple, medium, complex',\n  },\n  approve: {\n    type: 'boolean',\n    description: 'Auto-approve generated plan (supported with --mode=plan)',\n    default: false,\n  },\n  execute: {\n    type: 'boolean',\n    description: 'After plan is approved, immediately execute it (use with --mode=plan --approve)',\n    default: false,\n  },\n  files: {\n    type: 'array',\n    description: 'Target files (for edit mode)',\n  },\n  trace: {\n    type: 'string',\n    description: 'Trace file path (for debug mode)',\n  },\n  'dry-run': {\n    type: 'boolean',\n    description: 'Preview changes without applying (for edit mode)',\n    default: false,\n  },\n  verbose: {\n    type: 'boolean',\n    description: 'Verbose output',\n    default: false,\n  },\n  debug: {\n    type: 'boolean',\n    description: 'Enable debug mode: emit full prompts and responses as llm:debug events',\n    default: false,\n  },\n  timeout: {\n    type: 'number',\n    description: 'Abort agent execution after this many seconds (exit code 124). No timeout by default.',\n  },\n  budget: {\n    type: 'number',\n    description: 'Override token budget (e.g. 300000 for heavy tasks). Overrides config value.',\n  },\n  json: {\n    type: 'boolean',\n    description: 'Output structured JSON result instead of human-readable output.',\n  },\n} as const;\n\n/**\n * Plugin permissions\n */\nconst pluginPermissions = combinePermissions()\n  .with(kbPlatformPreset)\n  .withFs({\n    mode: 'readWrite',\n    allow: ['.agent-memory/**', '**/*'], // Allow filesystem operations in working dir\n  })\n  .withPlatform({\n    llm: true,  // Full LLM access for agent execution\n    cache: ['agent:'], // Cache namespace prefix\n    analytics: true,  // Track agent usage\n  })\n  .withQuotas({\n    timeoutMs: 1800000, // 30 min for complex tasks\n    memoryMb: 1024,\n  })\n  .build();\n\nexport const manifest = {\n  schema: 'kb.plugin/3',\n  id: '@kb-labs/agent',\n  version: '0.1.0',\n\n  display: {\n    name: 'Agent System',\n    description: 'Autonomous agent system with LLM tool calling, task orchestration, and tier escalation.',\n    tags: ['agent', 'autonomous', 'llm', 'orchestration'],\n  },\n\n  // Configuration lives under kb.config.json -> agents\n  configSection: 'agents',\n\n  platform: {\n    requires: ['llm'],\n    optional: ['cache', 'analytics', 'logger'],\n  },\n\n  cli: {\n    commands: [\n      {\n        id: 'agent:run',\n        group: 'agent',\n        describe: 'Run agent with specified mode (execute/plan/edit/debug)',\n        longDescription:\n          'Unified agent command with multiple modes: ' +\n          'execute (default) - run task immediately, ' +\n          'plan - generate execution plan without running, ' +\n          'edit - modify existing files, ' +\n          'debug - analyze errors with trace context. ' +\n          'Supports filesystem, search, shell, memory, and user interaction tools.',\n\n        handler: './cli/commands/run.js#default',\n        handlerPath: './cli/commands/run.js',\n\n        flags: defineCommandFlags(runFlags),\n\n        examples: [\n          'kb agent run --task=\"Create analytics system\"',\n          'kb agent run --mode=plan --task=\"Add auth\" --complexity=complex',\n          'kb agent run --mode=plan --task=\"Add auth\" --approve',\n          'kb agent run --mode=plan --task=\"Add auth\" --approve --execute',\n          'kb agent run --mode=edit --task=\"Fix bug\" --files src/auth.ts',\n          'kb agent run --mode=debug --task=\"Why crash?\" --trace .kb/traces/trace-123.json',\n          'kb agent run --task=\"Refactor auth module\" --timeout=120',\n        ],\n      },\n      // Trace debugging commands (AI-friendly)\n      {\n        id: 'agent:trace:stats',\n        group: 'agent',\n        describe: 'Show trace statistics with cost and performance metrics',\n        longDescription:\n          'Analyze trace file to show comprehensive statistics: ' +\n          'iterations, LLM calls, token usage, tool usage, timing, and cost. ' +\n          'Supports --json flag for AI agent consumption.',\n\n        handler: './cli/commands/trace-stats.js#default',\n        handlerPath: './cli/commands/trace-stats.js',\n\n        flags: defineCommandFlags({\n          'task-id': { type: 'string', description: 'Task ID or trace filename' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent trace stats --task-id=task-2026-01-29',\n          'kb agent trace stats --task-id=task-123 --json',\n        ],\n      },\n      {\n        id: 'agent:trace:filter',\n        group: 'agent',\n        describe: 'Filter trace events by type for debugging',\n        longDescription:\n          'Filter trace events by type (llm:call, tool:execution, error:captured, etc.). ' +\n          'Use this to debug specific aspects of agent execution. ' +\n          'Supports --json flag for programmatic access.',\n\n        handler: './cli/commands/trace-filter.js#default',\n        handlerPath: './cli/commands/trace-filter.js',\n\n        flags: defineCommandFlags({\n          'task-id': { type: 'string', description: 'Task ID or trace filename' },\n          type: { type: 'string', description: 'Event type to filter (llm:call, tool:execution, etc.)' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent trace filter --task-id=task-123 --type=llm:call',\n          'kb agent trace filter --task-id=task-123 --type=error:captured --json',\n        ],\n      },\n      {\n        id: 'agent:trace:iteration',\n        group: 'agent',\n        describe: 'View all events for a specific iteration',\n        longDescription:\n          'Show all trace events for a specific iteration number. ' +\n          'Useful for debugging what happened in a particular loop iteration. ' +\n          'Includes summary statistics and event timeline.',\n\n        handler: './cli/commands/trace-iteration.js#default',\n        handlerPath: './cli/commands/trace-iteration.js',\n\n        flags: defineCommandFlags({\n          'task-id': { type: 'string', description: 'Task ID or trace filename' },\n          iteration: { type: 'number', description: 'Iteration number (1-based)' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent trace iteration --task-id=task-123 --iteration=3',\n          'kb agent trace iteration --task-id=task-123 --iteration=5 --json',\n        ],\n      },\n      {\n        id: 'agent:trace:context',\n        group: 'agent',\n        describe: 'View what the LLM sees at each iteration — context window, truncations, responses',\n        longDescription:\n          'Shows the full context timeline for debugging agent behavior. ' +\n          'For each LLM call: what messages are in the sliding window, ' +\n          'what was truncated/dropped, and what the LLM responded with.',\n\n        handler: './cli/commands/trace-context.js#default',\n        handlerPath: './cli/commands/trace-context.js',\n\n        flags: defineCommandFlags({\n          'task-id': { type: 'string', description: 'Task ID or trace filename' },\n          iteration: { type: 'number', description: 'Filter to specific iteration' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent trace context --task-id=task-123',\n          'kb agent trace context --task-id=task-123 --iteration=3',\n          'kb agent trace context --task-id=task-123 --json',\n        ],\n      },\n      {\n        id: 'agent:trace:diagnose',\n        group: 'agent',\n        describe: 'Quick diagnostic analysis — answers \"what went wrong?\" in one command',\n        longDescription:\n          'Comprehensive diagnostic report for agent execution. ' +\n          'Analyzes errors, context window health (drops, truncations), ' +\n          'tool failures, LLM reasoning text, loop detection, and quality indicators. ' +\n          'One command to understand any agent issue.',\n\n        handler: './cli/commands/trace-diagnose.js#default',\n        handlerPath: './cli/commands/trace-diagnose.js',\n\n        flags: defineCommandFlags({\n          'task-id': { type: 'string', description: 'Task ID or trace filename' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent trace diagnose --task-id=task-123',\n          'kb agent trace diagnose --task-id=task-123 --json',\n        ],\n      },\n      {\n        id: 'agent:quality:report',\n        group: 'agent',\n        describe: 'Show quality control report for recent agent runs',\n        longDescription:\n          'Aggregates agent KPI telemetry from analytics buffer and shows ' +\n          'quality, token usage, tool efficiency, drift, and regression alerts. ' +\n          'Useful for continuous quality control and cost/performance monitoring.',\n\n        handler: './cli/commands/quality-report.js#default',\n        handlerPath: './cli/commands/quality-report.js',\n\n        flags: defineCommandFlags({\n          days: { type: 'number', description: 'Lookback period in days', default: 1 },\n          limit: { type: 'number', description: 'Max KPI runs to analyze', default: 200 },\n          'session-id': { type: 'string', description: 'Filter by session ID' },\n          json: { type: 'boolean', description: 'Output JSON for automation', default: false },\n        }),\n\n        examples: [\n          'kb agent quality report',\n          'kb agent quality report --days=7',\n          'kb agent quality report --session-id=session-123',\n          'kb agent quality report --days=3 --json',\n        ],\n      },\n      // File change history commands\n      {\n        id: 'agent:history',\n        group: 'agent',\n        describe: 'Show file change history for agent sessions',\n        longDescription:\n          'View file changes made by agents during execution. ' +\n          'Filter by session, file, or agent. Shows timestamps, operations, and change metadata.',\n\n        handler: './cli/commands/history.js#default',\n        handlerPath: './cli/commands/history.js',\n\n        flags: defineCommandFlags({\n          'session-id': { type: 'string', description: 'Session ID to filter by' },\n          file: { type: 'string', description: 'File path to filter by' },\n          'agent-id': { type: 'string', description: 'Agent ID to filter by' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent history',\n          'kb agent history --session-id=session-123',\n          'kb agent history --file=src/index.ts',\n          'kb agent history --agent-id=agent-abc --json',\n        ],\n      },\n      {\n        id: 'agent:diff',\n        group: 'agent',\n        describe: 'Show diff for specific file change',\n        longDescription:\n          'Display line-by-line diff for a specific file change. ' +\n          'Shows additions, deletions, and modifications with context.',\n\n        handler: './cli/commands/diff.js#default',\n        handlerPath: './cli/commands/diff.js',\n\n        flags: defineCommandFlags({\n          'change-id': { type: 'string', description: 'Change ID to show diff for' },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent diff --change-id=change-abc123',\n          'kb agent diff --change-id=change-abc123 --json',\n        ],\n      },\n      {\n        id: 'agent:rollback',\n        group: 'agent',\n        describe: 'Rollback file changes made by agents',\n        longDescription:\n          'Rollback file changes made by agents. ' +\n          'Supports rollback by change ID, file path, agent ID, session, or timestamp. ' +\n          'Use --dry-run to preview changes before applying.',\n\n        handler: './cli/commands/rollback.js#default',\n        handlerPath: './cli/commands/rollback.js',\n\n        flags: defineCommandFlags({\n          'change-id': { type: 'string', description: 'Change ID to rollback' },\n          file: { type: 'string', description: 'File path to rollback all changes for' },\n          'agent-id': { type: 'string', description: 'Agent ID to rollback all changes by' },\n          'session-id': { type: 'string', description: 'Session ID to rollback all changes in' },\n          after: { type: 'string', description: 'Rollback all changes after timestamp (ISO 8601)' },\n          force: { type: 'boolean', description: 'Force rollback even with conflicts', default: false },\n          'dry-run': { type: 'boolean', description: 'Preview rollback without applying', default: false },\n          json: { type: 'boolean', description: 'Output JSON for AI agents', default: false },\n        }),\n\n        examples: [\n          'kb agent rollback --change-id=change-abc123',\n          'kb agent rollback --file=src/index.ts --dry-run',\n          'kb agent rollback --agent-id=agent-abc',\n          'kb agent rollback --session-id=session-123',\n          'kb agent rollback --after=\"2026-02-16T10:00:00Z\" --json',\n        ],\n      },\n    ],\n  },\n\n  capabilities: [],\n\n  permissions: pluginPermissions,\n\n  // REST API for Agent UI\n  rest: {\n    basePath: AGENTS_BASE_PATH,\n    defaults: {\n      timeoutMs: 1800000, // 30 min for long-running tasks\n    },\n    routes: [\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.RUN,\n        description: 'Start a new agent run',\n        handler: './rest/handlers/run-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.RUN_STATUS,\n        description: 'Get status of a run',\n        handler: './rest/handlers/status-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.CORRECT,\n        description: 'Send correction to running agent(s)',\n        handler: './rest/handlers/correct-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.STOP,\n        description: 'Stop a running agent',\n        handler: './rest/handlers/stop-handler.js',\n        security: ['none'],\n      },\n      // Session management routes\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSIONS_LIST,\n        description: 'List all sessions',\n        handler: './rest/handlers/list-sessions-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_GET,\n        description: 'Get session details',\n        handler: './rest/handlers/get-session-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_CREATE,\n        description: 'Create a new session',\n        handler: './rest/handlers/create-session-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_TURNS,\n        description: 'Get session turns (turn-based UI)',\n        handler: './rest/handlers/get-session-turns-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_PLAN_GET,\n        description: 'Get current session plan',\n        handler: './rest/handlers/get-session-plan-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_PLAN_APPROVE,\n        description: 'Approve current session plan',\n        handler: './rest/handlers/approve-session-plan-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_PLAN_EXECUTE,\n        description: 'Execute approved session plan',\n        handler: './rest/handlers/execute-session-plan-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_PLAN_SPEC,\n        description: 'Generate detailed spec from approved plan',\n        handler: './rest/handlers/generate-spec-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_PLAN_SPEC_GET,\n        description: 'Get current session spec',\n        handler: './rest/handlers/get-spec-handler.js',\n        security: ['none'],\n      },\n      // File change history routes (rollback & approve)\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_CHANGES,\n        description: 'List file changes for session (optionally filtered by runId)',\n        handler: './rest/handlers/list-file-changes-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'GET',\n        path: AGENTS_ROUTES.SESSION_CHANGE_DIFF,\n        description: 'Get unified diff for a specific file change',\n        handler: './rest/handlers/get-file-diff-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_ROLLBACK,\n        description: 'Rollback file changes for a session/run',\n        handler: './rest/handlers/rollback-handler.js',\n        security: ['none'],\n      },\n      {\n        method: 'POST',\n        path: AGENTS_ROUTES.SESSION_APPROVE,\n        description: 'Approve file changes for a session/run',\n        handler: './rest/handlers/approve-handler.js',\n        security: ['none'],\n      },\n    ],\n  },\n\n  // WebSocket for real-time event streaming\n  ws: {\n    basePath: AGENTS_WS_BASE_PATH,\n    defaults: {\n      auth: 'none',\n      idleTimeoutMs: 3600000, // 1 hour\n    },\n    channels: [\n      {\n        path: AGENTS_WS_CHANNELS.SESSION_STREAM,\n        description: 'Persistent session stream (all runs in session)',\n        handler: './ws/session-stream-handler.js',\n        auth: 'none',\n      },\n    ],\n  },\n\n  artifacts: [\n    {\n      id: 'agent.memory.json',\n      pathTemplate: '.agent-memory/memory.json',\n      description: 'Persistent agent memory (facts, sessions, project context).',\n    },\n  ],\n\n  studio: {\n    version: 2 as const,\n    remoteName: 'agentPlugin',\n    pages: [\n      {\n        id: 'agent.overview',\n        title: 'Agent',\n        icon: 'RobotOutlined',\n        route: '/p/agent',\n        entry: './AgentsPage',\n        order: 1,\n      },\n    ],\n    menus: [\n      {\n        id: 'agent',\n        label: 'Agent',\n        icon: 'RobotOutlined',\n        target: 'agent.overview',\n        order: 30,\n      },\n    ],\n  },\n};\n"]}