beth-copilot 1.0.15 → 1.0.16

package/README.md

@@ -14,102 +14,62 @@ They broke her wings once. They forgot she had claws.
 
 Beth is a **multi-agent AI orchestrator** with a TypeScript runtime, CLI toolchain, MCP integrations, and agent-to-agent (A2A) delegation—all driven by a ruthless coordinator who runs your development team the way Beth Dutton runs Schwartz & Meyer.
 
-She commands seven specialized agents, each with their own expertise, tools, and handoff chains. On top of the GitHub Copilot agent layer, Beth now ships a **TypeScript core engine** with parsed agent/skill schemas, an Azure OpenAI LLM provider, streaming tool-call support, and a CLI that validates your entire installation in one command.
+She commands seven specialized agents, each with their own expertise, tools, and handoff chains. On top of the GitHub Copilot agent layer, Beth ships a **TypeScript core engine** with a full agentic loop: agent routing, conversation context management, tool calling, subagent spawning, and agent-to-agent handoffs—all backed by an Azure OpenAI LLM provider with streaming and retry.
 
-**The system has three execution layers:**
+**The system has four execution layers:**
 
 | Layer | What It Does | Status |
 |-------|-------------|--------|
 | **Copilot Agents** | `.agent.md` definitions running in VS Code Agent Mode | Live |
-| **CLI Toolchain** | `beth init`, `beth doctor`, `beth quickstart` — TypeScript commands with 485 tests | Live |
+| **CLI Toolchain** | `beth init`, `beth doctor`, `beth quickstart` — TypeScript commands | Live |
+| **Orchestration Engine** | Fan-out routing, tool calling loop, subagent spawning, handoffs | Live |
+| **Tool Abstraction** | 6 CLI tools + MCP bridge — uniform interface for all agent capabilities | Live |
 | **LLM Provider** | Azure OpenAI with Entra ID auth, streaming, retry, tool calling | Live |
 
+**814 tests.** 813 pass, 1 skip, 0 fail.
+
 ---
 
 ## Architecture
 
 ```mermaid
 flowchart TB
-    subgraph UI["User Interfaces"]
-        Copilot["VS Code Copilot Chat<br/><i>Agent Mode</i>"]
-        CLI["Beth CLI<br/><i>init · doctor · quickstart</i>"]
+    subgraph Input["Entry Points"]
+        Copilot["VS Code Copilot Chat"]
+        CLI["Beth CLI"]
     end
 
-    subgraph Core["Beth Core Engine — TypeScript"]
-        AgentLoader["Agent Loader<br/><i>Parse .agent.md frontmatter</i>"]
-        SkillLoader["Skill Loader<br/><i>Parse SKILL.md + triggers</i>"]
-        Types["Agent & Skill Types<br/><i>Typed schemas</i>"]
-        PathVal["Path Validation<br/><i>Traversal/injection guard</i>"]
+    subgraph Engine["Orchestration Engine"]
+        Orch["Orchestrator<br/><i>Route → LLM → Tools → Response</i>"]
     end
 
-    subgraph Agents["Specialist Agents (A2A)"]
-        Beth["@Beth<br/><i>Orchestrator</i>"]
+    subgraph Agents["Specialist Agents"]
+        Beth["@Beth"]
         PM["@product-manager"]
-        Researcher["@researcher"]
-        Designer["@ux-designer"]
-        Developer["@developer"]
-        Security["@security-reviewer"]
-        Tester["@tester"]
+        UX["@ux-designer"]
+        Dev["@developer"]
+        Sec["@security-reviewer"]
+        Test["@tester"]
+        Res["@researcher"]
     end
 
-    subgraph Skills["Skills — On-Demand Knowledge"]
-        PRD["PRD Generation"]
-        Framer["Framer Components"]
-        React["React/Next.js<br/>Best Practices"]
-        WebDesign["Web Design<br/>Guidelines"]
-        Shadcn["shadcn/ui"]
-        SecAnalysis["Security Analysis"]
-        AzureOps["Azure Operations"]
-        WebSearch["Web Search"]
+    subgraph Capabilities["Capabilities"]
+        Tools["Tools<br/><i>files · terminal · search · beads</i>"]
+        Skills["Skills<br/><i>PRD · React · shadcn · security</i>"]
+        MCPs["MCP Servers<br/><i>shadcn · Playwright · Azure</i>"]
     end
 
-    subgraph MCP["MCP Servers — Optional"]
-        MCPShadcn["shadcn/ui"]
-        MCPPlaywright["Playwright"]
-        MCPAzure["Azure"]
-        MCPBrave["Brave Search"]
-        MCPDeepWiki["DeepWiki"]
-    end
+    LLM["Azure OpenAI<br/><i>Entra ID · Streaming</i>"]
 
-    subgraph Provider["LLM Provider Layer"]
-        Interface["LLMProviderBase<br/><i>Abstract interface</i>"]
-        Azure["AzureOpenAIProvider<br/><i>Entra ID · Streaming</i>"]
-        Retry["Retry + Backoff<br/><i>Exponential w/ jitter</i>"]
-        Stream["StreamAccumulator<br/><i>Tool call assembly</i>"]
-        Config["Config Loader<br/><i>env → ~/.beth/.env</i>"]
-    end
-
-    subgraph Tracking["Work Tracking"]
-        Beads["beads (bd CLI)<br/><i>Agent coordination</i>"]
-        Backlog["Backlog.md<br/><i>Human changelog</i>"]
-    end
-
-    Copilot --> Beth
-    CLI --> Core
-    Core --> Agents
-    Beth -->|"routes"| PM & Researcher & Designer & Developer & Security & Tester
-
-    PM -.->|"loads"| PRD
-    Designer -.->|"loads"| Framer & WebDesign
-    Developer -.->|"loads"| React & Shadcn
-    Security -.->|"loads"| SecAnalysis
-    Researcher -.->|"loads"| WebSearch
-    Developer -.->|"uses"| MCPShadcn
-    Tester -.->|"uses"| MCPPlaywright
-    Security -.->|"uses"| MCPAzure
-    Researcher -.->|"uses"| MCPBrave
-
-    Azure --> Interface
-    Retry --> Azure
-    Stream --> Azure
-    Config --> Azure
-
-    Beth -.->|"tracks"| Beads
-    Beth -.->|"updates"| Backlog
+    Copilot & CLI --> Orch
+    Orch --> Beth
+    Beth -->|"delegates"| PM & UX & Dev & Sec & Test & Res
+    Orch <-->|"chat"| LLM
+    Orch --> Tools & Skills & MCPs
 
     style Beth fill:#1e3a5f,color:#fff
-    style Core fill:#f0f4f8
-    style Provider fill:#e8f5e9
+    style Engine fill:#fff3e0
+    style Capabilities fill:#e3f2fd
 ```
 
 ---
@@ -126,7 +86,7 @@ flowchart TB
 | **LLM Provider** | Azure OpenAI via `openai` SDK | Entra ID auth (no API keys), streaming + tool calling |
 | **Auth** | `@azure/identity` DefaultAzureCredential | az login, managed identity, VS Code creds |
 | **Frontmatter** | `gray-matter` | Parses `.agent.md` and `SKILL.md` YAML |
-| **Testing** | Node.js built-in test runner | 485 tests — unit, integration, E2E |
+| **Testing** | Node.js built-in test runner | 814 tests — unit, integration, E2E |
 | **Task Tracking** | beads (`bd` CLI) | Dependency-aware issue tracking for agents |
 | **Package Manager** | pnpm | Lockfile committed |
 
@@ -331,6 +291,99 @@ Skills are domain-knowledge modules that agents load automatically when trigger
 
 ---
 
+## Orchestration Engine (Fan-Out Pattern)
+
+The orchestration engine is Beth's brain — the full agentic loop that processes user messages through routing, skill injection, LLM calls, tool execution, and subagent spawning.
+
+```mermaid
+flowchart TB
+    User["User Message"] --> Route["AgentRouter\n@mention · skill match · default"]
+    Route --> Context["ConversationContext\nBuild system prompt + history"]
+    Context --> Skills{"Skill triggers match?"}
+    Skills -->|yes| Inject["Inject skill into system prompt"]
+    Skills -->|no| LLM
+    Inject --> LLM["LLM Call\nAzure OpenAI"]
+    LLM --> Decision{"Response type?"}
+    Decision -->|text| Done["Return response"]
+    Decision -->|tool calls| ToolExec["Execute tools\nvia ToolRegistry"]
+    ToolExec --> SubCheck{"Subagent request?"}
+    SubCheck -->|yes| SubAgent["Spawn child loop\ndepth-limited"]
+    SubCheck -->|no| ToolResult["Return tool result"]
+    SubAgent --> ToolResult
+    ToolResult --> LLM
+    Decision -->|handoff| Handoff["HandoffManager\nContext transfer"]
+    Handoff --> Route
+
+    style User fill:#1e3a5f,color:#fff
+    style LLM fill:#e8f5e9
+    style ToolExec fill:#e3f2fd
+    style SubAgent fill:#fff3e0
+```
+
+**Key capabilities:**
+- **Agent routing** — `@mention` parsing, skill trigger matching, current-agent stickiness
+- **Fan-out tool calling** — Iterative LLM → tool call → result → LLM loop (up to 25 iterations)
+- **Subagent spawning** — Nested agent loops with depth limiting (default: 3 levels deep)
+- **Handoff management** — Context transfer between agents with conversation summaries, ping-pong loop detection
+- **Context window management** — Token-estimated truncation with tool call/result consistency repair
+- **Observer callbacks** — Hook into routing decisions, LLM calls, tool executions, handoffs for logging/UI
+
+```typescript
+// Full orchestrator usage
+import { Orchestrator, createDefaultRegistry } from 'beth-copilot';
+
+const orchestrator = new Orchestrator({
+  agents: loadAgents('.github/agents'),
+  skills: loadSkills('.github/skills'),
+  provider: new AzureOpenAIProvider(config),
+  toolRegistry: createDefaultRegistry(),
+  toolContext: { workingDir: process.cwd(), permissions: { ... } },
+});
+
+const result = await orchestrator.processMessage('Implement the login page');
+// result.response — final text
+// result.agentId — who handled it
+// result.toolCallsExecuted — what tools ran
+// result.subagentResults — any nested agent work
+// result.injectedSkills — skills loaded for this turn
+```
+
+---
+
+## Tool Abstraction Layer
+
+A uniform interface for all agent capabilities — file I/O, terminal, search, beads, subagent spawning, and MCP server tools. Tools expose OpenAI-compatible function calling schemas so the LLM can invoke them directly.
+
+| Tool | What It Does | Key Features |
+|------|-------------|-------------- |
+| **readFile** | Read file contents | Line ranges, path validation, traversal guards |
+| **editFile** | Atomic string replacement | Single-match enforcement, whitespace-safe |
+| **search** | Ripgrep search | Node.js fallback, regex support, file filtering |
+| **terminal** | Execute shell commands | `execFile('/bin/sh')` — no shell injection, timeouts |
+| **beads** | Issue tracking | `bd create`, `bd close`, `bd list` via CLI wrapper |
+| **subagent** | Spawn nested agents | Returns structured result for orchestrator to process |
+| **MCP Bridge** | External tool servers | JSON-RPC 2.0 over stdio, JSONC config, namespaced tools |
+
+```typescript
+import { createDefaultRegistry, ToolRegistry, loadAllMCPTools } from 'beth-copilot';
+
+// Built-in tools
+const registry = createDefaultRegistry();
+// → readFile, editFile, search, terminal, beads, subagent
+
+// Add MCP server tools
+const { tools: mcpTools } = await loadAllMCPTools('.vscode/mcp.json');
+for (const tool of mcpTools) {
+  registry.register(tool); // e.g., mcp_shadcn_listComponents
+}
+
+// Get OpenAI function calling definitions
+const definitions = registry.getDefinitions();
+// Pass to LLM as tools parameter
+```
+
+---
+
 ## LLM Provider Layer
 
 The TypeScript core includes a production-ready provider abstraction for running Beth outside VS Code.
@@ -383,7 +436,7 @@ flowchart LR
 
 ## TypeScript Core
 
-The engine that powers everything. Parses agent and skill definitions, validates configuration, and provides typed APIs.
+The engine that powers everything. Parses agent and skill definitions, manages conversations, routes requests, executes tools, and provides typed APIs for the full agentic loop.
 
 ### Project Structure
 
@@ -392,11 +445,15 @@ beth/
 ├── bin/
 │   └── cli.js                      # CLI entry point (init, doctor, quickstart, help)
 ├── src/
-│   ├── index.ts                    # Barrel exports
+│   ├── index.ts                    # Barrel exports (all public API)
 │   ├── cli/commands/
 │   │   ├── doctor.ts               # System health validation
 │   │   └── quickstart.ts           # Guided setup flow
 │   ├── core/
+│   │   ├── orchestrator.ts         # Agentic loop: route → LLM → tools → response
+│   │   ├── router.ts               # @mention routing, skill matching, agent lookup
+│   │   ├── context.ts              # Conversation state, token truncation, skill injection
+│   │   ├── handoffs.ts             # Agent-to-agent transfers, loop detection
 │   │   ├── agents/
 │   │   │   ├── types.ts            # AgentDefinition, AgentFrontmatter, AgentHandoff
 │   │   │   └── loader.ts           # Parse .agent.md → typed definitions
@@ -405,6 +462,20 @@ beth/
 │   │       └── loader.ts           # Parse SKILL.md, extract triggers, match queries
 │   ├── lib/
 │   │   └── pathValidation.ts       # Traversal/injection guards
+│   ├── tools/
+│   │   ├── interface.ts            # Tool interface + toToolDefinition()
+│   │   ├── types.ts                # ToolError, ToolResult, ToolContext, ToolPermissions
+│   │   ├── registry.ts             # ToolRegistry: register, get, list, getDefinitions
+│   │   ├── cli/
+│   │   │   ├── readFile.ts         # File reading with line ranges
+│   │   │   ├── editFile.ts         # Atomic string replacement
+│   │   │   ├── search.ts           # Ripgrep with Node.js fallback
+│   │   │   ├── terminal.ts         # Secure command execution
+│   │   │   ├── beads.ts            # Issue tracking via bd CLI
+│   │   │   └── subagent.ts         # Agent spawning interface
+│   │   └── mcp/
+│   │       ├── client.ts           # JSON-RPC 2.0 over stdio
+│   │       └── bridge.ts           # JSONC config, tool namespacing
 │   └── providers/
 │       ├── interface.ts            # LLMProviderBase abstract class
 │       ├── azure.ts                # AzureOpenAIProvider (Entra ID, streaming, tools)
@@ -425,17 +496,36 @@ beth/
 
 ### Test Coverage
 
-**485 tests** (484 pass, 1 skip, 0 fail):
+**814 tests** (813 pass, 1 skip, 0 fail):
 
 | Suite | Tests | What It Covers |
 |-------|-------|---------------|
-| Agent loader | 30+ | Frontmatter parsing, validation, code fence stripping, handoffs |
-| Skill loader | 30+ | Trigger extraction, query matching, trigger map building |
+| **Orchestration** | | |
+| Orchestrator | 30+ | Agentic loop, tool calling, subagent spawning, iteration limits |
+| AgentRouter | 30+ | @mention routing, skill matching, agent resolution |
+| ConversationContext | 30+ | Token truncation, skill injection, tool call repair |
+| HandoffManager | 30+ | Context transfer, depth limits, ping-pong detection |
+| **Tools** | | |
+| Tool interface | 20+ | Tool → ToolDefinition conversion, schema validation |
+| ToolRegistry | 20+ | Register, get, list, definitions, duplicate detection |
+| readFile | 30+ | Line ranges, path validation, encoding |
+| editFile | 30+ | String replacement, single-match enforcement |
+| search | 30+ | Ripgrep, Node.js fallback, regex, file filtering |
+| terminal | 30+ | Command execution, timeouts, output capture |
+| beads | 30+ | bd CLI wrapper, create/close/list/ready |
+| subagent | 30+ | Spawn interface, result marking, agent validation |
+| MCP client | 30+ | JSON-RPC 2.0, protocol handshake, tool listing |
+| MCP bridge | 30+ | JSONC parsing, tool namespacing, error handling |
+| Tool suite | 10+ | createDefaultRegistry, integration tests |
+| **Providers** | | |
 | Provider types | 40+ | LLMError codes, ChatMessage shapes, ToolDefinition schemas |
 | Provider retry | 40+ | Exponential backoff, jitter, transient error detection |
 | Provider config | 30+ | Env precedence, dotenv parsing, URL validation |
 | Provider streaming | 40+ | Chunk accumulation, tool call delta assembly |
 | Provider Azure | 30+ | Message mapping, response mapping, error wrapping |
+| **Core & CLI** | | |
+| Agent loader | 30+ | Frontmatter parsing, validation, code fence stripping, handoffs |
+| Skill loader | 30+ | Trigger extraction, query matching, trigger map building |
 | CLI E2E | 52 | Init/doctor pipeline, MCP template validation, help output |
 | Path validation | 33 | Traversal detection, injection prevention, allowlists |
 
@@ -572,6 +662,36 @@ Is it magic? No. It's just competence with very good hair.
 - **GitHub Copilot Chat** in Agent mode
 - [**beads**](https://github.com/steveyegge/beads) for task tracking (`bd` CLI)
 
+### Installing Beads
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+```
+
+**CGO Troubleshooting (Linux/WSL):** Beads uses Dolt (a Git-for-data database) which requires CGO. If `bd init` or `bd doctor` fails with CGO-related errors:
+
+```bash
+# Install C compiler toolchain (required for CGO)
+sudo apt-get update && sudo apt-get install -y build-essential gcc
+
+# Verify CGO is available
+export CGO_ENABLED=1
+go env CGO_ENABLED  # should print 1
+
+# Re-install beads
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+```
+
+**Common beads issues:**
+- `bd: command not found` — Add `~/.local/bin` to your PATH: `export PATH="$HOME/.local/bin:$PATH"`
+- `bd doctor` warnings about metadata — Run `bd doctor --fix` to auto-repair
+- Dolt migration errors — Delete `.beads/` and re-initialize with `bd init`
+
+```bash
+# Verify beads is working
+bd doctor
+```
+
 ### Optional: MCP Servers
 
 See [MCP Integrations](#mcp-integrations) above or [docs/MCP-SETUP.md](docs/MCP-SETUP.md) for setup.

package/bin/cli.js

@@ -733,6 +733,48 @@ async function initializeBeads(cwd) {
   });
 }
 
+/**
+ * Runs `bd doctor` to verify beads configuration health.
+ * 
+ * SECURITY NOTE - shell:true usage:
+ * - bdPath is validated via getBeadsPath() (same as initializeBeads)
+ * - Arguments are HARDCODED ('doctor') - no user input is passed to the shell
+ * - Command injection risk: LOW (bdPath is validated, no user input in args)
+ * 
+ * @returns {Promise<boolean>} True if bd doctor passed
+ */
+async function runBeadsDoctor() {
+  log('\nRunning beads doctor to verify configuration...', COLORS.cyan);
+  
+  const bdPath = getBeadsPath();
+  if (!bdPath) {
+    logWarning('Cannot run beads doctor: bd not found.');
+    return false;
+  }
+  
+  return new Promise((resolve) => {
+    const child = spawn(bdPath, ['doctor'], {
+      stdio: 'inherit',
+      shell: true,
+    });
+    
+    child.on('close', (code) => {
+      if (code === 0) {
+        logSuccess('beads doctor passed!');
+        resolve(true);
+      } else {
+        logWarning('beads doctor reported issues. Run "bd doctor" manually to investigate.');
+        resolve(false);
+      }
+    });
+    
+    child.on('error', () => {
+      logWarning('Failed to run beads doctor. Run "bd doctor" manually.');
+      resolve(false);
+    });
+  });
+}
+
 function showHelp() {
   showBethBannerStatic({ showQuickHelp: false });
   console.log(`${COLORS.bright}Beth${COLORS.reset} - AI Orchestrator for GitHub Copilot
@@ -1048,6 +1090,11 @@ ${COLORS.yellow}╔════════════════════
     logWarning('Skipped beads check (--skip-beads). Beth may not function correctly.');
   }
 
+  // Run bd doctor to verify beads configuration
+  if (!skipBeads && getBeadsPath() && isBeadsInitialized(cwd)) {
+    await runBeadsDoctor();
+  }
+
   // Final verification
   console.log('');
   log('Verifying installation...', COLORS.cyan);

package/dist/core/context.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Conversation Context Manager
+ *
+ * Manages conversation state for agent interactions:
+ * - Message history with role tracking
+ * - Context window management (token estimation + truncation)
+ * - System prompt construction from agent definitions + skills
+ * - Skill injection when trigger phrases match user input
+ *
+ * Each agent session gets its own ConversationContext. When handoffs occur,
+ * a summary can be extracted and injected into the new agent's context.
+ */
+import type { ChatMessage } from '../providers/types.js';
+import type { AgentDefinition } from './agents/types.js';
+import type { SkillDefinition } from './skills/types.js';
+/**
+ * Options for creating a ConversationContext.
+ */
+export interface ConversationContextOptions {
+    /** Maximum tokens for the context window (default: 128000) */
+    maxTokens?: number;
+    /** Tokens reserved for the model's response (default: 4096) */
+    responseReserve?: number;
+    /** Initial conversation history to restore (e.g., from a handoff) */
+    initialMessages?: ChatMessage[];
+}
+/**
+ * Summary of a conversation for handoff purposes.
+ */
+export interface ConversationSummary {
+    /** The agent that was running this conversation */
+    agentId: string;
+    /** Key points from the conversation */
+    summary: string;
+    /** Number of turns in the original conversation */
+    turnCount: number;
+    /** Any tool calls that were made */
+    toolCallSummary: string[];
+}
+/**
+ * Manages conversation state for a single agent session.
+ *
+ * Handles message accumulation, context window enforcement,
+ * and system prompt construction from agent definitions and skills.
+ *
+ * @example
+ * ```typescript
+ * const ctx = new ConversationContext(developerAgent);
+ * ctx.addUserMessage('Implement the login page');
+ *
+ * const messages = ctx.getMessages(); // system + user message
+ * // Send to LLM...
+ *
+ * ctx.addAssistantMessage('I\'ll create the login component...');
+ * ctx.addAssistantToolCalls([{ id: '1', type: 'function', function: { name: 'editFile', arguments: '...' } }]);
+ * ctx.addToolResult('1', 'File updated successfully');
+ * ```
+ */
+export declare class ConversationContext {
+    /** The agent this context belongs to */
+    private readonly agent;
+    /** Conversation messages (excluding system prompt; it's built dynamically) */
+    private messages;
+    /** Skills injected into this context */
+    private injectedSkills;
+    /** Skill content appended to system prompt */
+    private skillContent;
+    /** Context window configuration */
+    private readonly maxTokens;
+    private readonly responseReserve;
+    /** Custom context additions (handoff summaries, etc.) */
+    private additionalContext;
+    constructor(agent: AgentDefinition, options?: ConversationContextOptions);
+    /**
+     * Add a user message to the conversation.
+     */
+    addUserMessage(content: string): void;
+    /**
+     * Add an assistant text response to the conversation.
+     */
+    addAssistantMessage(content: string): void;
+    /**
+     * Add an assistant message with tool calls.
+     */
+    addAssistantToolCalls(toolCalls: ChatMessage['tool_calls'], content?: string): void;
+    /**
+     * Add a tool result message.
+     */
+    addToolResult(toolCallId: string, result: string): void;
+    /**
+     * Get the full message array for sending to the LLM.
+     * Includes the constructed system prompt as the first message.
+     * Applies truncation if context window is exceeded.
+     */
+    getMessages(): ChatMessage[];
+    /**
+     * Get just the conversation messages (without system prompt).
+     */
+    getRawMessages(): ChatMessage[];
+    /**
+     * Get the number of conversation turns (user messages).
+     */
+    getTurnCount(): number;
+    /**
+     * Get estimated token count for the current context.
+     */
+    getEstimatedTokens(): number;
+    /**
+     * Clear the conversation history, keeping injected skills.
+     */
+    clearHistory(): void;
+    /**
+     * Inject a skill's content into the system prompt.
+     * Each skill is only injected once per context.
+     *
+     * @param skill - The skill to inject
+     * @returns true if the skill was injected, false if already present
+     */
+    injectSkill(skill: SkillDefinition): boolean;
+    /**
+     * Check if a skill has been injected.
+     */
+    hasSkill(skillId: string): boolean;
+    /**
+     * Get the IDs of all injected skills.
+     */
+    getInjectedSkillIds(): string[];
+    /**
+     * Add additional context (e.g., handoff summary from previous agent).
+     */
+    addContext(context: string): void;
+    /**
+     * Generate a summary of this conversation for handoff purposes.
+     */
+    getSummary(): ConversationSummary;
+    /**
+     * Get the agent definition this context belongs to.
+     */
+    getAgent(): AgentDefinition;
+    /**
+     * Build the full system prompt from the agent definition + injected content.
+     */
+    buildSystemPrompt(): string;
+    /**
+     * Estimate token count for a string.
+     */
+    private estimateTokens;
+    /**
+     * Estimate token count for a single message including structure overhead.
+     */
+    private estimateMessageTokens;
+    /**
+     * Truncate messages to fit within the token budget.
+     *
+     * Strategy: Keep the most recent messages. Drop oldest messages first,
+     * but never drop tool results that are paired with a tool call in the
+     * retained messages (to avoid orphaned tool call references).
+     *
+     * @param messages - Messages to truncate
+     * @param maxTokens - Maximum tokens available
+     * @returns Truncated message array
+     */
+    private truncateMessages;
+    /**
+     * Remove orphaned tool results (where the corresponding assistant
+     * tool_calls message was truncated) and orphaned tool calls
+     * (where the results were truncated).
+     */
+    private repairToolCallConsistency;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAmBzD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,qEAAqE;IACrE,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAElB,oCAAoC;IACpC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAmB;IAC9B,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IAExC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAqB;IAErC,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAA0B;IAEhD,8CAA8C;IAC9C,OAAO,CAAC,YAAY,CAAgB;IAEpC,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,yDAAyD;IACzD,OAAO,CAAC,iBAAiB,CAAgB;gBAE7B,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAcxE;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQnF;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQvD;;;;OAIG;IACH,WAAW,IAAI,WAAW,EAAE;IAY5B;;OAEG;IACH,cAAc,IAAI,WAAW,EAAE;IAI/B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAU5B;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAY5C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE;IAQ/B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQjC;;OAEG;IACH,UAAU,IAAI,mBAAmB;IA4BjC;;OAEG;IACH,QAAQ,IAAI,eAAe;IAQ3B;;OAEG;IACH,iBAAiB,IAAI,MAAM;IA0B3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IA6CxB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;CAgClC"}