# @compilr-dev/agents
## Enumerations
### MCPErrorCode
Defined in: [mcp/errors.ts:10](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L10)
Error codes for MCP operations
#### Enumeration Members
| Enumeration Member | Value | Description | Defined in |
| ------ | ------ | ------ | ------ |
| `CONNECTION_FAILED` | `"CONNECTION_FAILED"` | Failed to connect to MCP server | [mcp/errors.ts:14](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L14) |
| `INVALID_CONFIG` | `"INVALID_CONFIG"` | Invalid server configuration | [mcp/errors.ts:26](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L26) |
| `SDK_NOT_INSTALLED` | `"SDK_NOT_INSTALLED"` | MCP SDK is not installed | [mcp/errors.ts:12](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L12) |
| `SERVER_EXISTS` | `"SERVER_EXISTS"` | Server already exists | [mcp/errors.ts:28](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L28) |
| `SERVER_NOT_FOUND` | `"SERVER_NOT_FOUND"` | Server not found in manager | [mcp/errors.ts:16](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L16) |
| `TIMEOUT` | `"TIMEOUT"` | Connection or operation timeout | [mcp/errors.ts:24](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L24) |
| `TOOL_EXECUTION_FAILED` | `"TOOL_EXECUTION_FAILED"` | Tool execution failed | [mcp/errors.ts:20](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L20) |
| `TOOL_NOT_FOUND` | `"TOOL_NOT_FOUND"` | Tool not found on server | [mcp/errors.ts:18](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L18) |
| `TRANSPORT_ERROR` | `"TRANSPORT_ERROR"` | Transport error (stdio/http) | [mcp/errors.ts:22](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/mcp/errors.ts#L22) |
***
### StateErrorCode
Defined in: [state/errors.ts:10](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L10)
Error codes for state management operations.
#### Enumeration Members
| Enumeration Member | Value | Description | Defined in |
| ------ | ------ | ------ | ------ |
| `DESERIALIZATION_FAILED` | `"DESERIALIZATION_FAILED"` | Failed to deserialize string to state | [state/errors.ts:15](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L15) |
| `INVALID_SESSION_ID` | `"INVALID_SESSION_ID"` | Session ID format is invalid | [state/errors.ts:30](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L30) |
| `INVALID_STATE` | `"INVALID_STATE"` | Invalid state structure | [state/errors.ts:27](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L27) |
| `SERIALIZATION_FAILED` | `"SERIALIZATION_FAILED"` | Failed to serialize state to string | [state/errors.ts:12](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L12) |
| `SESSION_NOT_FOUND` | `"SESSION_NOT_FOUND"` | Session not found in storage | [state/errors.ts:18](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L18) |
| `STORAGE_ERROR` | `"STORAGE_ERROR"` | Storage operation failed (I/O, permissions, etc.) | [state/errors.ts:21](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L21) |
| `VERSION_MISMATCH` | `"VERSION_MISMATCH"` | State version mismatch (needs migration) | [state/errors.ts:24](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/errors.ts#L24) |
## Classes
### AbortError
Defined in: [errors.ts:235](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L235)
Error thrown when a request is aborted via AbortSignal.
#### Extends
- [`AgentError`](#agenterror)
#### Constructors
##### Constructor
```ts
new AbortError(message?): AbortError;
```
Defined in: [errors.ts:236](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L236)
###### Parameters
| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `message` | `string` | `'Request was aborted'` |
###### Returns
[`AbortError`](#aborterror)
###### Overrides
[`AgentError`](#agenterror).[`constructor`](#constructor-2)
#### Properties
##### cause?
```ts
readonly optional cause?: Error;
```
Defined in: [errors.ts:17](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L17)
###### Inherited from
[`AgentError`](#agenterror).[`cause`](#cause-1)
***
### Agent
Defined in: [agent.ts:982](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L982)
Agent class - orchestrates LLM interactions with tool use
#### Example
```typescript
const agent = new Agent({
provider: new ClaudeProvider({ apiKey: 'sk-...' }),
systemPrompt: 'You are a helpful assistant.',
});
agent.registerTool(readFileTool);
agent.registerTool(writeFileTool);
const result = await agent.run('Read the contents of package.json');
console.log(result.response);
```
#### Constructors
##### Constructor
```ts
new Agent(config): Agent;
```
Defined in: [agent.ts:1088](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1088)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | [`AgentConfig`](#agentconfig) |
###### Returns
[`Agent`](#agent)
#### Accessors
##### sessionId
###### Get Signature
```ts
get sessionId(): string;
```
Defined in: [agent.ts:1328](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1328)
Get the session ID for this agent instance
###### Returns
`string`
#### Methods
##### ~~addAnchor()~~
```ts
addAnchor(input): Anchor | undefined;
```
Defined in: [agent.ts:1593](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1593)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `input` | [`AnchorInput`](#anchorinput) |
###### Returns
[`Anchor`](#anchor) \| `undefined`
###### Deprecated
Use addPin() instead
##### addGuardrail()
```ts
addGuardrail(input): Guardrail | undefined;
```
Defined in: [agent.ts:1648](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1648)
Add a custom guardrail
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`GuardrailInput`](#guardrailinput) | Guardrail definition |
###### Returns
[`Guardrail`](#guardrail) \| `undefined`
The created guardrail, or undefined if guardrails are not enabled
###### Example
```typescript
agent.addGuardrail({
id: 'no-delete-important',
name: 'Important Files Protection',
description: 'Prevent deletion of important files',
patterns: [/rm.*important/i, /delete.*important/i],
action: 'block',
message: 'Cannot delete files marked as important',
scope: ['bash'],
});
```
##### addPermission()
```ts
addPermission(rule): this;
```
Defined in: [agent.ts:1727](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1727)
Add a permission rule for a tool
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `rule` | [`ToolPermission`](#toolpermission) | Permission rule to add |
###### Returns
`this`
this for chaining
###### Example
```typescript
agent.addPermission({
toolName: 'bash',
level: 'once',
description: 'Execute shell commands',
});
```
##### addPin()
```ts
addPin(input): Anchor | undefined;
```
Defined in: [agent.ts:1478](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1478)
Add a pin (critical information that survives context compaction).
Pins are injected into every LLM call and never get compacted.
Use them for information that must not be forgotten.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`AnchorInput`](#anchorinput) | Pin input (uses AnchorInput type) |
###### Returns
[`Anchor`](#anchor) \| `undefined`
The created pin, or undefined if pins are not enabled
###### Example
```typescript
agent.addPin({
content: 'Team roster: $default, $arch',
priority: 'info',
scope: 'session',
});
```
##### checkpoint()
```ts
checkpoint(metadata?): Promise;
```
Defined in: [agent.ts:2279](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2279)
Save the current state using the configured checkpointer.
Throws if no checkpointer is configured.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `metadata?` | `Partial`\<[`SessionMetadata`](#sessionmetadata)\> | Optional metadata overrides |
###### Returns
`Promise`\<`string`\>
The session ID
###### Example
```typescript
const agent = new Agent({
provider,
checkpointer: new FileCheckpointer('~/.myapp/sessions/'),
});
await agent.run('Hello!');
const sessionId = await agent.checkpoint();
console.log(`Saved as: ${sessionId}`);
```
##### ~~clearAnchors()~~
```ts
clearAnchors(options?): number;
```
Defined in: [agent.ts:1613](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1613)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`AnchorClearOptions`](#anchorclearoptions) |
###### Returns
`number`
###### Deprecated
Use clearPins() instead
##### clearHistory()
```ts
clearHistory(): this;
```
Defined in: [agent.ts:1875](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1875)
Clear conversation history to start fresh
###### Returns
`this`
##### clearPins()
```ts
clearPins(options?): number;
```
Defined in: [agent.ts:1528](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1528)
Clear pins based on criteria
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | [`AnchorClearOptions`](#anchorclearoptions) | Clear options for filtering which pins to remove |
###### Returns
`number`
Number of pins removed
##### clearSessionPermissions()
```ts
clearSessionPermissions(): this;
```
Defined in: [agent.ts:1790](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1790)
Clear all session-level permissions
###### Returns
`this`
##### compact()
```ts
compact(options?): Promise<{
categoryStats?: Record;
filesCreated?: string[];
messagesPreserved: number;
originalTokens: number;
restorationHintsInjected: boolean;
rounds: number;
success: boolean;
summary: string;
summaryTokens: number;
toolResultsRepaired: number;
}>;
```
Defined in: [agent.ts:2049](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2049)
Compact the conversation context to reduce token usage.
This is the recommended way to trigger context compaction externally.
It handles:
1. Summarizing older messages
2. Repairing tool use/result pairing (prevents API errors)
3. Injecting context restoration hints (if file tracking is enabled)
4. Updating the conversation history
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | \{ `emergency?`: `boolean`; `injectRestorationHints?`: `boolean`; `targetUtilization?`: `number`; `useSmartCompaction?`: `boolean`; \} | Compaction options |
| `options.emergency?` | `boolean` | Use emergency mode (more aggressive summarization). Default: auto-detect based on context utilization |
| `options.injectRestorationHints?` | `boolean` | Inject file restoration hints after compaction. Only applies if file tracking is enabled. Default: true (if file tracking is enabled) |
| `options.targetUtilization?` | `number` | Target utilization after compaction (0-1). Default: from context manager config (typically 0.5) |
| `options.useSmartCompaction?` | `boolean` | Use smart category-aware compaction instead of simple summarization. Smart compaction: - Preserves system and recent messages completely - Saves large tool results to files - Summarizes history with LLM Default: true |
###### Returns
`Promise`\<\{
`categoryStats?`: `Record`\<[`ContextCategory`](#contextcategory), \{
`action`: `"preserved"` \| `"compacted"` \| `"summarized"`;
`tokensAfter`: `number`;
`tokensBefore`: `number`;
\}\>;
`filesCreated?`: `string`[];
`messagesPreserved`: `number`;
`originalTokens`: `number`;
`restorationHintsInjected`: `boolean`;
`rounds`: `number`;
`success`: `boolean`;
`summary`: `string`;
`summaryTokens`: `number`;
`toolResultsRepaired`: `number`;
\}\>
Compaction result with statistics
###### Example
```typescript
// Basic compaction
const result = await agent.compact();
console.log(`Reduced from ${result.originalTokens} to ${result.summaryTokens} tokens`);
// Compaction without restoration hints
await agent.compact({ injectRestorationHints: false });
// Emergency compaction (more aggressive)
await agent.compact({ emergency: true });
```
##### createSubAgent()
```ts
createSubAgent(config): this;
```
Defined in: [agent.ts:2463](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2463)
Create and register a sub-agent with isolated context.
Sub-agents are specialized agents that handle discrete tasks independently.
They have their own context window and can have different tools/permissions.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | [`SubAgentConfig`](#subagentconfig) |
###### Returns
`this`
###### Example
```typescript
agent.createSubAgent({
name: 'code-reviewer',
description: 'Reviews code for security and quality issues',
systemPrompt: 'You are a code review specialist...',
tools: [readFileTool], // Restricted tools
contextMode: 'isolated',
});
const result = await agent.runSubAgent('code-reviewer', 'Review src/auth.ts');
```
##### createWithMemory()
```ts
static createWithMemory(
config,
memoryOptions?,
memoryDir?): Promise;
```
Defined in: [agent.ts:1307](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1307)
Create an agent with project memory loaded from files.
This factory method automatically discovers and loads project-specific
instructions from files like CLAUDE.md, GEMINI.md, PROJECT.md, etc.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `config` | `Omit`\<[`AgentConfig`](#agentconfig), `"projectMemory"`\> | Agent configuration |
| `memoryOptions?` | [`ProjectMemoryOptions`](#projectmemoryoptions) | Project memory loading options |
| `memoryDir?` | `string` | Directory to search for memory files (defaults to cwd) |
###### Returns
`Promise`\<[`Agent`](#agent)\>
Agent instance with loaded project memory
###### Example
```typescript
// Load Claude-specific instructions
const agent = await Agent.createWithMemory(
{
provider,
systemPrompt: 'You are a helpful assistant.',
},
{ providers: 'claude' },
'/path/to/project'
);
// Load instructions for multiple providers
const agent = await Agent.createWithMemory(
{ provider },
{ providers: ['claude', 'gemini'], includeGeneric: true }
);
// Access loaded memory
const memory = agent.getProjectMemory();
console.log(`Loaded ${memory?.files.length} memory files`);
```
##### disableGuardrail()
```ts
disableGuardrail(id): boolean;
```
Defined in: [agent.ts:1690](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1690)
Disable a guardrail by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### disposeAllSubAgents()
```ts
disposeAllSubAgents(): void;
```
Defined in: [agent.ts:2739](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2739)
Dispose all sub-agents and release their resources.
Useful for cleanup when the parent agent is done or
to free memory during long-running sessions.
###### Returns
`void`
##### disposeSubAgent()
```ts
disposeSubAgent(name): boolean;
```
Defined in: [agent.ts:2714](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2714)
Dispose a sub-agent and release its resources.
This clears the sub-agent's:
- Conversation history
- Context manager state
- Tool registry
After disposal, the sub-agent must be re-created to use again.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
###### Returns
`boolean`
##### emitCustomEvent()
```ts
emitCustomEvent(config): void;
```
Defined in: [agent.ts:1840](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1840)
Emit a custom event that will be streamed to event handlers.
This allows tools, middleware, and user code to emit custom events
that are streamed alongside built-in agent events.
Inspired by LangGraph's get_stream_writer() pattern.
Addresses issues like LangGraph #6330 (preserve event metadata).
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `config` | [`CustomEventConfig`](#customeventconfig) | Custom event configuration |
###### Returns
`void`
###### Example
```typescript
agent.emitCustomEvent({
name: 'progress',
data: { step: 1, total: 5, message: 'Processing...' },
metadata: { toolName: 'myTool' },
});
```
##### enableGuardrail()
```ts
enableGuardrail(id): boolean;
```
Defined in: [agent.ts:1683](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1683)
Enable a guardrail by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### formatRestorationHints()
```ts
formatRestorationHints(): string;
```
Defined in: [agent.ts:1978](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1978)
Format context restoration hints based on tracked file accesses.
Returns empty string if no files have been accessed or file tracking is disabled.
###### Returns
`string`
##### fromState()
```ts
static fromState(state, options): Agent;
```
Defined in: [agent.ts:2387](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2387)
Create an agent from a serialized AgentState object.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `state` | [`AgentState`](#agentstate) | The serialized agent state |
| `options` | \{ `checkpointer?`: [`Checkpointer`](#checkpointer-1); `onEvent?`: [`AgentEventHandler`](#agenteventhandler); `provider`: [`LLMProvider`](#llmprovider); `systemPrompt?`: `string`; `tools?`: [`Tool`](#tool)\<`object`\>[]; \} | Options for the new agent |
| `options.checkpointer?` | [`Checkpointer`](#checkpointer-1) | - |
| `options.onEvent?` | [`AgentEventHandler`](#agenteventhandler) | - |
| `options.provider` | [`LLMProvider`](#llmprovider) | - |
| `options.systemPrompt?` | `string` | - |
| `options.tools?` | [`Tool`](#tool)\<`object`\>[] | - |
###### Returns
[`Agent`](#agent)
###### Example
```typescript
// Load state from somewhere
const json = await fs.readFile('session.json', 'utf-8');
const state = JSON.parse(json);
// Create agent from state
const agent = Agent.fromState(state, { provider });
await agent.run('Continue...');
```
##### ~~getAnchor()~~
```ts
getAnchor(id): Anchor | undefined;
```
Defined in: [agent.ts:1597](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1597)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
[`Anchor`](#anchor) \| `undefined`
###### Deprecated
Use getPin() instead
##### ~~getAnchorManager()~~
```ts
getAnchorManager(): AnchorManager | undefined;
```
Defined in: [agent.ts:1617](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1617)
###### Returns
[`AnchorManager`](#anchormanager) \| `undefined`
###### Deprecated
Use getPinManager() instead
##### ~~getAnchors()~~
```ts
getAnchors(options?): Anchor[];
```
Defined in: [agent.ts:1601](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1601)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`AnchorQueryOptions`](#anchorqueryoptions) |
###### Returns
[`Anchor`](#anchor)[]
###### Deprecated
Use getPins() instead
##### getBudgetStatus()
```ts
getBudgetStatus(): BudgetStatus | undefined;
```
Defined in: [agent.ts:1415](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1415)
Get budget status.
###### Returns
[`BudgetStatus`](#budgetstatus) \| `undefined`
##### getContextManager()
```ts
getContextManager(): ContextManager | undefined;
```
Defined in: [agent.ts:1923](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1923)
Get the context manager (if configured)
###### Returns
[`ContextManager`](#contextmanager) \| `undefined`
##### getContextStats()
```ts
getContextStats(): ContextStats | undefined;
```
Defined in: [agent.ts:1938](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1938)
Get context statistics
###### Returns
[`ContextStats`](#contextstats-1) \| `undefined`
##### getDeadMessagePruneStats()
```ts
getDeadMessagePruneStats():
| {
errorsPruned: number;
permissionsPruned: number;
prunedCount: number;
tokensSaved: number;
}
| undefined;
```
Defined in: [agent.ts:1954](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1954)
Get dead message pruning statistics (errors pruned, permissions pruned, tokens saved).
###### Returns
\| \{
`errorsPruned`: `number`;
`permissionsPruned`: `number`;
`prunedCount`: `number`;
`tokensSaved`: `number`;
\}
\| `undefined`
##### getFileTracker()
```ts
getFileTracker(): FileAccessTracker | undefined;
```
Defined in: [agent.ts:1970](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1970)
Get the file access tracker (if file tracking is enabled)
###### Returns
[`FileAccessTracker`](#fileaccesstracker) \| `undefined`
##### getGuardrail()
```ts
getGuardrail(id): Guardrail | undefined;
```
Defined in: [agent.ts:1655](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1655)
Get a guardrail by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
[`Guardrail`](#guardrail) \| `undefined`
##### getGuardrailManager()
```ts
getGuardrailManager(): GuardrailManager | undefined;
```
Defined in: [agent.ts:1697](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1697)
Get the guardrail manager (if configured)
###### Returns
[`GuardrailManager`](#guardrailmanager) \| `undefined`
##### getGuardrails()
```ts
getGuardrails(): Guardrail[];
```
Defined in: [agent.ts:1662](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1662)
Get all guardrails
###### Returns
[`Guardrail`](#guardrail)[]
##### getHistory()
```ts
getHistory(): Message[];
```
Defined in: [agent.ts:1886](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1886)
Get the current conversation history
###### Returns
[`Message`](#message-4)[]
##### getModel()
```ts
getModel(): string;
```
Defined in: [agent.ts:1553](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1553)
Get the current model ID for this agent.
###### Returns
`string`
The model ID string (e.g., 'claude-sonnet-4-20250514')
##### getObservationMaskStats()
```ts
getObservationMaskStats():
| {
activeStamps: number;
inputsCompacted: number;
maskedCount: number;
tokensSaved: number;
}
| undefined;
```
Defined in: [agent.ts:1945](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1945)
Get observation masking statistics (tokens saved, observations masked, inputs compacted).
###### Returns
\| \{
`activeStamps`: `number`;
`inputsCompacted`: `number`;
`maskedCount`: `number`;
`tokensSaved`: `number`;
\}
\| `undefined`
##### getPermission()
```ts
getPermission(toolName): ToolPermission | undefined;
```
Defined in: [agent.ts:1742](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1742)
Get a permission rule by tool name
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolName` | `string` |
###### Returns
[`ToolPermission`](#toolpermission) \| `undefined`
##### getPermissionLevel()
```ts
getPermissionLevel(toolName): PermissionLevel;
```
Defined in: [agent.ts:1768](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1768)
Get the effective permission level for a tool
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolName` | `string` |
###### Returns
[`PermissionLevel`](#permissionlevel)
##### getPermissionManager()
```ts
getPermissionManager(): PermissionManager | undefined;
```
Defined in: [agent.ts:1805](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1805)
Get the permission manager (if configured)
###### Returns
[`PermissionManager`](#permissionmanager) \| `undefined`
##### getPermissions()
```ts
getPermissions(): ToolPermission[];
```
Defined in: [agent.ts:1749](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1749)
Get all permission rules
###### Returns
[`ToolPermission`](#toolpermission)[]
##### getPin()
```ts
getPin(id): Anchor | undefined;
```
Defined in: [agent.ts:1489](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1489)
Get a pin by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
[`Anchor`](#anchor) \| `undefined`
##### getPinManager()
```ts
getPinManager(): AnchorManager | undefined;
```
Defined in: [agent.ts:1535](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1535)
Get the pin manager (if configured)
###### Returns
[`AnchorManager`](#anchormanager) \| `undefined`
##### getPins()
```ts
getPins(options?): Anchor[];
```
Defined in: [agent.ts:1496](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1496)
Get all pins, optionally filtered
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`AnchorQueryOptions`](#anchorqueryoptions) |
###### Returns
[`Anchor`](#anchor)[]
##### getProjectMemory()
```ts
getProjectMemory(): ProjectMemory | undefined;
```
Defined in: [agent.ts:1356](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1356)
Get the loaded project memory (if any).
Project memory contains instructions loaded from files like
CLAUDE.md, GEMINI.md, PROJECT.md, etc.
###### Returns
[`ProjectMemory`](#projectmemory-1) \| `undefined`
The loaded project memory, or undefined if none was loaded
###### Example
```typescript
const memory = agent.getProjectMemory();
if (memory) {
console.log(`Loaded ${memory.files.length} instruction files`);
console.log(`Total tokens: ~${memory.estimatedTokens}`);
for (const file of memory.files) {
console.log(` - ${file.relativePath}`);
}
}
```
##### getSessionPermissions()
```ts
getSessionPermissions(): string[];
```
Defined in: [agent.ts:1798](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1798)
Get all tools with session-level permission
###### Returns
`string`[]
##### getStreamWriter()
```ts
getStreamWriter(eventName?): StreamWriter;
```
Defined in: [agent.ts:1866](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1866)
Get a stream writer function for emitting custom events.
This returns a simple function that can be passed to tools or
middleware for streaming progress updates.
###### Parameters
| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `eventName` | `string` | `'stream'` | Name for all events emitted by this writer |
###### Returns
[`StreamWriter`](#streamwriter)
A stream writer function
###### Example
```typescript
const writer = agent.getStreamWriter('myTool');
writer('Starting...', { phase: 'init' });
writer('Processing...', { phase: 'work', progress: 50 });
writer('Done!', { phase: 'complete' });
```
##### getSubAgent()
```ts
getSubAgent(name): Agent | undefined;
```
Defined in: [agent.ts:2686](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2686)
Get a registered sub-agent by name
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
###### Returns
[`Agent`](#agent) \| `undefined`
##### getSubAgentNames()
```ts
getSubAgentNames(): string[];
```
Defined in: [agent.ts:2693](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2693)
Get all registered sub-agent names
###### Returns
`string`[]
##### getToolDefinitions()
```ts
getToolDefinitions(): ToolDefinition[];
```
Defined in: [agent.ts:2829](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2829)
Get all registered tool definitions
###### Returns
`ToolDefinition`[]
##### getToolRegistry()
```ts
getToolRegistry(): ToolRegistry;
```
Defined in: [agent.ts:1931](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1931)
Get the tool registry instance.
Useful for setting up fallback handlers or inspecting registered tools.
###### Returns
[`ToolRegistry`](#toolregistry-1)
##### getTotalInputTokens()
```ts
getTotalInputTokens(): number;
```
Defined in: [agent.ts:1401](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1401)
Get total input tokens used across all LLM calls.
###### Returns
`number`
##### getTotalOutputTokens()
```ts
getTotalOutputTokens(): number;
```
Defined in: [agent.ts:1408](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1408)
Get total output tokens used across all LLM calls.
###### Returns
`number`
##### getTotalTokens()
```ts
getTotalTokens(): number;
```
Defined in: [agent.ts:1394](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1394)
Get total tokens used across all LLM calls.
###### Returns
`number`
##### getUsageStats()
```ts
getUsageStats(): UsageStats | undefined;
```
Defined in: [agent.ts:1387](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1387)
Get usage tracking statistics.
###### Returns
[`UsageStats`](#usagestats) \| `undefined`
Usage statistics or undefined if usage tracking is not enabled
###### Example
```typescript
const stats = agent.getUsageStats();
if (stats) {
console.log(`Total calls: ${stats.totalCalls}`);
console.log(`Total tokens: ${stats.totalTokens}`);
console.log(`Input tokens: ${stats.totalInputTokens}`);
console.log(`Output tokens: ${stats.totalOutputTokens}`);
}
```
##### getUsageSummary()
```ts
getUsageSummary(): string | undefined;
```
Defined in: [agent.ts:1429](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1429)
Get a human-readable usage summary.
###### Returns
`string` \| `undefined`
##### getVerbosityLevel()
```ts
getVerbosityLevel(): VerbosityLevel;
```
Defined in: [agent.ts:1963](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1963)
Get current verbosity level based on context pressure
###### Returns
[`VerbosityLevel`](#verbositylevel-1)
##### grantSessionPermission()
```ts
grantSessionPermission(toolName): this;
```
Defined in: [agent.ts:1775](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1775)
Grant session-level permission for a tool
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolName` | `string` |
###### Returns
`this`
##### ~~hasAnchor()~~
```ts
hasAnchor(id): boolean;
```
Defined in: [agent.ts:1605](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1605)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
###### Deprecated
Use hasPin() instead
##### ~~hasAnchors()~~
```ts
hasAnchors(): boolean;
```
Defined in: [agent.ts:1621](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1621)
###### Returns
`boolean`
###### Deprecated
Use hasPins() instead
##### hasCheckpointer()
```ts
hasCheckpointer(): boolean;
```
Defined in: [agent.ts:2292](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2292)
Check if a checkpointer is configured
###### Returns
`boolean`
##### hasGuardrail()
```ts
hasGuardrail(id): boolean;
```
Defined in: [agent.ts:1669](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1669)
Check if a guardrail exists
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### hasGuardrails()
```ts
hasGuardrails(): boolean;
```
Defined in: [agent.ts:1704](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1704)
Check if guardrails are enabled
###### Returns
`boolean`
##### hasPermissions()
```ts
hasPermissions(): boolean;
```
Defined in: [agent.ts:1812](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1812)
Check if permissions are enabled
###### Returns
`boolean`
##### hasPin()
```ts
hasPin(id): boolean;
```
Defined in: [agent.ts:1503](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1503)
Check if a pin exists
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### hasPins()
```ts
hasPins(): boolean;
```
Defined in: [agent.ts:1542](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1542)
Check if pins are enabled
###### Returns
`boolean`
##### hasProjectMemory()
```ts
hasProjectMemory(): boolean;
```
Defined in: [agent.ts:1363](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1363)
Check if project memory was loaded
###### Returns
`boolean`
##### hasUsageTracking()
```ts
hasUsageTracking(): boolean;
```
Defined in: [agent.ts:1443](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1443)
Check if usage tracking is enabled.
###### Returns
`boolean`
##### isBudgetExceeded()
```ts
isBudgetExceeded(): boolean;
```
Defined in: [agent.ts:1422](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1422)
Check if budget is exceeded.
###### Returns
`boolean`
##### isToolSilent()
```ts
isToolSilent(name): boolean;
```
Defined in: [agent.ts:2836](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2836)
Check if a tool is marked as silent (no spinner or result output)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
###### Returns
`boolean`
##### registerTool()
```ts
registerTool(tool): this;
```
Defined in: [agent.ts:2808](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2808)
Register a tool that the agent can call during conversations.
Tools are functions the LLM can invoke to perform actions like reading
files, running commands, or querying APIs. The LLM sees the tool's name,
description, and parameter schema, then decides when to call it.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tool` | [`Tool`](#tool) | Tool definition created with `defineTool()` |
###### Returns
`this`
The agent instance (for chaining)
###### Example
```typescript
agent.registerTool(defineTool({
name: 'get_weather',
description: 'Get current weather for a city',
parameters: {
type: 'object',
properties: { city: { type: 'string' } },
required: ['city'],
},
execute: async ({ city }) => {
const data = await fetchWeather(city);
return { content: JSON.stringify(data) };
},
}));
```
##### registerTools()
```ts
registerTools(tools): this;
```
Defined in: [agent.ts:2819](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2819)
Register multiple tools at once.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tools` | [`Tool`](#tool)\<`object`\>[] | Array of tool definitions |
###### Returns
`this`
The agent instance (for chaining)
##### ~~removeAnchor()~~
```ts
removeAnchor(id): boolean;
```
Defined in: [agent.ts:1609](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1609)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
###### Deprecated
Use removePin() instead
##### removeGuardrail()
```ts
removeGuardrail(id): boolean;
```
Defined in: [agent.ts:1676](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1676)
Remove a guardrail by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### removePermission()
```ts
removePermission(toolName): boolean;
```
Defined in: [agent.ts:1735](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1735)
Remove a permission rule by tool name
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolName` | `string` |
###### Returns
`boolean`
##### removePin()
```ts
removePin(id): boolean;
```
Defined in: [agent.ts:1512](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1512)
Remove a pin by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
true if pin was removed, false if not found
##### removeSubAgent()
```ts
removeSubAgent(name): boolean;
```
Defined in: [agent.ts:2700](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2700)
Remove a registered sub-agent (alias for disposeSubAgent)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
###### Returns
`boolean`
##### resetUsageTracking()
```ts
resetUsageTracking(): void;
```
Defined in: [agent.ts:1436](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1436)
Reset usage tracking data.
###### Returns
`void`
##### resume()
```ts
static resume(sessionId, options): Promise;
```
Defined in: [agent.ts:2345](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2345)
Resume an agent from a saved session.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | `string` | Session ID to resume |
| `options` | \{ `checkpointer`: [`Checkpointer`](#checkpointer-1); `onEvent?`: [`AgentEventHandler`](#agenteventhandler); `provider`: [`LLMProvider`](#llmprovider); `systemPrompt?`: `string`; `tools?`: [`Tool`](#tool)\<`object`\>[]; \} | Resume options (provider and checkpointer required) |
| `options.checkpointer` | [`Checkpointer`](#checkpointer-1) | - |
| `options.onEvent?` | [`AgentEventHandler`](#agenteventhandler) | - |
| `options.provider` | [`LLMProvider`](#llmprovider) | - |
| `options.systemPrompt?` | `string` | - |
| `options.tools?` | [`Tool`](#tool)\<`object`\>[] | - |
###### Returns
`Promise`\<[`Agent`](#agent)\>
###### Example
```typescript
const checkpointer = new FileCheckpointer('~/.myapp/sessions/');
// Resume a previous session
const agent = await Agent.resume('session_abc123', {
provider: new ClaudeProvider({ apiKey: '...' }),
checkpointer,
});
// Continue the conversation
await agent.run('Continue where we left off...');
```
##### revokeSessionPermission()
```ts
revokeSessionPermission(toolName): boolean;
```
Defined in: [agent.ts:1783](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1783)
Revoke session-level permission for a tool
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolName` | `string` |
###### Returns
`boolean`
##### run()
```ts
run(userMessage, options?): Promise;
```
Defined in: [agent.ts:2874](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2874)
Run the agent with a user message and return the result.
This is the main entry point for agent interaction. The agent will:
1. Add the user message to conversation history
2. Send the conversation to the LLM
3. Execute any tool calls the LLM requests
4. Repeat steps 2-3 until the LLM responds with text (no tool calls)
5. Return the final text response and metadata
Events are emitted throughout the process via the `onEvent` callback
configured at construction time.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `userMessage` | `string` \| [`ContentBlock`](#contentblock)[] | The user's message (string or content blocks for images) |
| `options?` | [`RunOptions`](#runoptions) | Optional run configuration (max iterations, abort signal, etc.) |
###### Returns
`Promise`\<[`AgentRunResult`](#agentrunresult)\>
The agent's response, tool call history, and context stats
###### Examples
```typescript
const result = await agent.run('What files are in this directory?');
console.log(result.response);
console.log(`Used ${result.toolCalls.length} tool calls`);
```
```typescript
// With abort signal
const controller = new AbortController();
const result = await agent.run('Refactor this file', {
signal: controller.signal,
});
```
##### runParallelSubAgents()
```ts
runParallelSubAgents(tasks, options?): Promise;
```
Defined in: [agent.ts:2644](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2644)
Run multiple sub-agents in parallel with proper state isolation.
This method ensures that parallel sub-agents don't share mutable state,
preventing race conditions and state leakage between concurrent runs.
Inspired by LangGraph issue #6446: Parallel subgraphs with shared
state keys cause InvalidUpdateError.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tasks` | \{ `name`: `string`; `task`: `string`; \}[] | Array of {name, task} objects to run in parallel |
| `options?` | [`RunOptions`](#runoptions) | Optional run options applied to all sub-agents |
###### Returns
`Promise`\<[`SubAgentResult`](#subagentresult)[]\>
Array of results in the same order as tasks
###### Example
```typescript
// Run code review and security scan in parallel
const results = await agent.runParallelSubAgents([
{ name: 'code-reviewer', task: 'Review src/auth.ts' },
{ name: 'security-scanner', task: 'Scan src/auth.ts for vulnerabilities' },
]);
```
##### runSubAgent()
```ts
runSubAgent(
name,
task,
options?): Promise;
```
Defined in: [agent.ts:2533](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2533)
Run a sub-agent with a specific task.
The sub-agent executes independently with its own context and returns
the result to the parent agent.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | Name of the registered sub-agent |
| `task` | `string` | Task description for the sub-agent |
| `options?` | [`RunOptions`](#runoptions) | Optional run options |
###### Returns
`Promise`\<[`SubAgentResult`](#subagentresult)\>
##### serialize()
```ts
serialize(): AgentState;
```
Defined in: [agent.ts:2245](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L2245)
Serialize the current agent state to an AgentState object.
This can be used for manual persistence or transferring state.
###### Returns
[`AgentState`](#agentstate)
###### Example
```typescript
const state = agent.serialize();
const json = JSON.stringify(state);
// Store json somewhere...
```
##### setHistory()
```ts
setHistory(messages, options?): Promise;
```
Defined in: [agent.ts:1898](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1898)
Set the conversation history (for manual compaction/restoration)
Also updates the context manager's token count if configured.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `messages` | [`Message`](#message-4)[] | The message history to restore |
| `options?` | \{ `turnCount?`: `number`; \} | Optional restore options |
| `options.turnCount?` | `number` | The turn count to restore (important for compaction) |
###### Returns
`Promise`\<[`Agent`](#agent)\>
##### setModel()
```ts
setModel(modelId): void;
```
Defined in: [agent.ts:1581](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1581)
Change the model for subsequent LLM calls (same provider only).
Takes effect on the next `run()` or `stream()` call — never interrupts
a running turn. Conversation history is preserved (it's provider-agnostic).
Emits a `model_changed` event.
Use this to switch between models within the same provider, e.g.,
Claude Sonnet → Claude Opus for a harder task, then back.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `modelId` | `string` | The new model ID (e.g., 'claude-opus-4-20250514') |
###### Returns
`void`
###### Throws
If modelId is empty or not a string
###### Example
```typescript
console.log(agent.getModel()); // 'claude-sonnet-4-20250514'
agent.setModel('claude-opus-4-20250514');
// Next run() uses Opus
const result = await agent.run('Solve this complex problem');
agent.setModel('claude-sonnet-4-20250514'); // Switch back
```
###### Since
0.5.8
##### setPermissionLevel()
```ts
setPermissionLevel(
toolName,
level,
description?): this;
```
Defined in: [agent.ts:1760](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L1760)
Set the permission level for a tool
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `toolName` | `string` | Tool name or pattern |
| `level` | [`PermissionLevel`](#permissionlevel) | Permission level |
| `description?` | `string` | Optional description |
###### Returns
`this`
##### stream()
```ts
stream(userMessage, options?): AsyncIterable;
```
Defined in: [agent.ts:3970](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/agent.ts#L3970)
Stream the agent's response as events.
Yields `AgentEvent` objects in real time as the agent thinks, calls tools,
and generates text. Use this for building interactive UIs that show
progress as it happens.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `userMessage` | `string` | The user's message |
| `options?` | [`RunOptions`](#runoptions) | Optional run configuration |
###### Returns
`AsyncIterable`\<[`AgentEvent`](#agentevent)\>
An async iterable of agent events
###### Example
```typescript
for await (const event of agent.stream('Explain this code')) {
if (event.type === 'llm_chunk') {
process.stdout.write(event.chunk.text ?? '');
} else if (event.type === 'tool_start') {
console.log(`\nCalling tool: ${event.name}`);
} else if (event.type === 'done') {
console.log('\n\nDone!');
}
}
```
***
### AgentError
Defined in: [errors.ts:14](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L14)
Base error class for all agent-related errors.
#### Extends
- `Error`
#### Extended by
- [`ProviderError`](#providererror)
- [`ToolError`](#toolerror)
- [`ToolLoopError`](#toollooperror)
- [`ValidationError`](#validationerror)
- [`MaxIterationsError`](#maxiterationserror)
- [`AbortError`](#aborterror)
- [`ContextOverflowError`](#contextoverflowerror)
- [`MCPError`](#mcperror)
#### Constructors
##### Constructor
```ts
new AgentError(message, cause?): AgentError;
```
Defined in: [errors.ts:15](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L15)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `message` | `string` |
| `cause?` | `Error` |
###### Returns
[`AgentError`](#agenterror)
###### Overrides
```ts
Error.constructor
```
#### Properties
##### cause?
```ts
readonly optional cause?: Error;
```
Defined in: [errors.ts:17](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L17)
###### Inherited from
```ts
Error.cause
```
***
### AnchorManager
Defined in: [anchors/manager.ts:58](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L58)
AnchorManager - Manages critical information that survives context compaction
#### Example
```typescript
const manager = new AnchorManager({
maxAnchors: 20,
maxTokens: 2000,
persistPath: '~/.myapp/anchors.json',
});
// Add a session anchor
manager.add({
content: 'This session we implemented: edit tool, grep tool',
priority: 'critical',
scope: 'session',
});
// Get formatted anchors for injection into LLM messages
const formatted = manager.format();
```
#### Constructors
##### Constructor
```ts
new AnchorManager(options?): AnchorManager;
```
Defined in: [anchors/manager.ts:68](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L68)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`AnchorManagerOptions`](#anchormanageroptions) |
###### Returns
[`AnchorManager`](#anchormanager)
#### Accessors
##### size
###### Get Signature
```ts
get size(): number;
```
Defined in: [anchors/manager.ts:382](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L382)
Get the current number of anchors
###### Returns
`number`
#### Methods
##### add()
```ts
add(input): Anchor;
```
Defined in: [anchors/manager.ts:118](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L118)
Add a new anchor
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`AnchorInput`](#anchorinput) | Anchor input (id and createdAt auto-generated if not provided) |
###### Returns
[`Anchor`](#anchor)
The created anchor
##### clear()
```ts
clear(options?): number;
```
Defined in: [anchors/manager.ts:249](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L249)
Clear anchors based on criteria
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`AnchorClearOptions`](#anchorclearoptions) |
###### Returns
`number`
##### clearByProject()
```ts
clearByProject(projectId): number;
```
Defined in: [anchors/manager.ts:330](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L330)
Clear all anchors for a specific project
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `projectId` | `string` | The project ID |
###### Returns
`number`
Number of anchors removed
##### format()
```ts
format(): string;
```
Defined in: [anchors/manager.ts:411](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L411)
Format anchors for injection into LLM messages
Groups anchors by priority and formats them for the system message.
###### Returns
`string`
##### get()
```ts
get(id): Anchor | undefined;
```
Defined in: [anchors/manager.ts:164](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L164)
Get an anchor by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
[`Anchor`](#anchor) \| `undefined`
##### getAll()
```ts
getAll(options?): Anchor[];
```
Defined in: [anchors/manager.ts:176](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L176)
Get all anchors, optionally filtered
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`AnchorQueryOptions`](#anchorqueryoptions) |
###### Returns
[`Anchor`](#anchor)[]
##### getByProject()
```ts
getByProject(projectId, options?): Anchor[];
```
Defined in: [anchors/manager.ts:308](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L308)
Get all anchors for a specific project
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `projectId` | `string` | The project ID to filter by |
| `options?` | `Omit`\<[`AnchorQueryOptions`](#anchorqueryoptions), `"projectId"` \| `"globalOnly"`\> | Additional query options (priority, scope, tags) |
###### Returns
[`Anchor`](#anchor)[]
##### getGlobal()
```ts
getGlobal(options?): Anchor[];
```
Defined in: [anchors/manager.ts:320](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L320)
Get all global anchors (those without a projectId)
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | `Omit`\<[`AnchorQueryOptions`](#anchorqueryoptions), `"projectId"` \| `"globalOnly"`\> | Additional query options (priority, scope, tags) |
###### Returns
[`Anchor`](#anchor)[]
##### getProjectIds()
```ts
getProjectIds(): string[];
```
Defined in: [anchors/manager.ts:337](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L337)
Get list of unique project IDs that have anchors
###### Returns
`string`[]
##### getProjectStats()
```ts
getProjectStats(): Map;
```
Defined in: [anchors/manager.ts:364](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L364)
Get anchor counts grouped by project
###### Returns
`Map`\<`string` \| `null`, `number`\>
Map where keys are project IDs (null for global) and values are counts
##### getTotalTokens()
```ts
getTotalTokens(): number;
```
Defined in: [anchors/manager.ts:389](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L389)
Get total tokens used by all anchors
###### Returns
`number`
##### getUtilization()
```ts
getUtilization(): number;
```
Defined in: [anchors/manager.ts:402](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L402)
Get token budget utilization (0-1)
###### Returns
`number`
##### has()
```ts
has(id): boolean;
```
Defined in: [anchors/manager.ts:222](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L222)
Check if an anchor exists
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
##### hasProjectAnchors()
```ts
hasProjectAnchors(projectId): boolean;
```
Defined in: [anchors/manager.ts:350](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L350)
Check if a project has any anchors
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `projectId` | `string` |
###### Returns
`boolean`
##### onEvent()
```ts
onEvent(handler): void;
```
Defined in: [anchors/manager.ts:91](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L91)
Set the event handler for anchor events
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `handler` | [`AnchorEventHandler`](#anchoreventhandler) |
###### Returns
`void`
##### remove()
```ts
remove(id): boolean;
```
Defined in: [anchors/manager.ts:231](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/anchors/manager.ts#L231)
Remove an anchor by ID
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `id` | `string` |
###### Returns
`boolean`
true if anchor was removed, false if not found
***
### ClaudeProvider
Defined in: [providers/claude.ts:186](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L186)
LLM provider for Anthropic's Claude models (Opus, Sonnet, Haiku).
Supports streaming, tool use, prompt caching, extended context (1M tokens),
and token-efficient tool schemas.
#### Examples
```typescript
const provider = new ClaudeProvider({
apiKey: process.env.ANTHROPIC_API_KEY,
model: 'claude-sonnet-4-20250514',
});
const agent = new Agent({
provider,
systemPrompt: 'You are a helpful assistant.',
});
```
```typescript
// Using the factory function
const provider = createClaudeProvider({
apiKey: 'sk-ant-...',
enableExtendedContext: true, // 1M token context
});
```
#### Implements
- [`LLMProvider`](#llmprovider)
#### Constructors
##### Constructor
```ts
new ClaudeProvider(config): ClaudeProvider;
```
Defined in: [providers/claude.ts:197](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L197)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `config` | [`ClaudeProviderConfig`](#claudeproviderconfig) |
###### Returns
[`ClaudeProvider`](#claudeprovider)
#### Properties
##### name
```ts
readonly name: "claude" = 'claude';
```
Defined in: [providers/claude.ts:187](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L187)
Provider identifier (e.g., 'claude', 'openai', 'gemini')
###### Implementation of
[`LLMProvider`](#llmprovider).[`name`](#name-21)
#### Methods
##### chat()
```ts
chat(messages, options?): AsyncIterable;
```
Defined in: [providers/claude.ts:222](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L222)
Send messages and stream the response
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `options?` | [`ChatOptions`](#chatoptions-1) |
###### Returns
`AsyncIterable`\<[`StreamChunk`](#streamchunk)\>
###### Implementation of
[`LLMProvider`](#llmprovider).[`chat`](#chat-13)
##### countTokens()
```ts
countTokens(messages): Promise;
```
Defined in: [providers/claude.ts:341](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L341)
Count tokens in messages using tiktoken (cl100k_base encoding)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
###### Returns
`Promise`\<`number`\>
###### Implementation of
[`LLMProvider`](#llmprovider).[`countTokens`](#counttokens-14)
##### getModel()
```ts
getModel(): string;
```
Defined in: [providers/claude.ts:211](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L211)
Get the current default model ID.
###### Returns
`string`
###### Implementation of
[`LLMProvider`](#llmprovider).[`getModel`](#getmodel-14)
##### setModel()
```ts
setModel(modelId): void;
```
Defined in: [providers/claude.ts:215](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/providers/claude.ts#L215)
Change the default model for subsequent calls. Same provider only.
Takes effect on the next chat() call, not mid-stream.
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `modelId` | `string` | The new model ID (e.g., 'claude-opus-4-20250514') |
###### Returns
`void`
###### Implementation of
[`LLMProvider`](#llmprovider).[`setModel`](#setmodel-14)
***
### CompactJsonSerializer
Defined in: [state/serializer.ts:139](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/serializer.ts#L139)
Compact JSON serializer (no pretty printing).
Useful for storage-constrained environments.
#### Implements
- [`StateSerializer`](#stateserializer)
#### Constructors
##### Constructor
```ts
new CompactJsonSerializer(): CompactJsonSerializer;
```
###### Returns
[`CompactJsonSerializer`](#compactjsonserializer)
#### Properties
##### version
```ts
readonly version: "1.0" = '1.0';
```
Defined in: [state/serializer.ts:140](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/serializer.ts#L140)
Version identifier for migration support
###### Implementation of
[`StateSerializer`](#stateserializer).[`version`](#version-4)
#### Methods
##### deserialize()
```ts
deserialize(data): AgentState;
```
Defined in: [state/serializer.ts:153](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/serializer.ts#L153)
Deserialize string back to agent state
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `data` | `string` |
###### Returns
[`AgentState`](#agentstate)
###### Throws
StateError if data is invalid
###### Implementation of
[`StateSerializer`](#stateserializer).[`deserialize`](#deserialize-2)
##### serialize()
```ts
serialize(state): string;
```
Defined in: [state/serializer.ts:142](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/serializer.ts#L142)
Serialize agent state to string
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `state` | [`AgentState`](#agentstate) |
###### Returns
`string`
###### Implementation of
[`StateSerializer`](#stateserializer).[`serialize`](#serialize-3)
##### validate()
```ts
validate(state): void;
```
Defined in: [state/serializer.ts:181](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/state/serializer.ts#L181)
Validate state before serialization (public interface method).
This is called by checkpointers before saving to prevent corrupted checkpoints.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `state` | [`AgentState`](#agentstate) |
###### Returns
`void`
###### Throws
StateError if state is invalid
###### Implementation of
[`StateSerializer`](#stateserializer).[`validate`](#validate-2)
***
### ContextManager
Defined in: [context/manager.ts:143](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L143)
Manages the agent's context window — tracks token usage, triggers
compaction when the conversation grows too large, and ensures the
agent never exceeds the model's context limit.
The context window is divided into budgets:
- **System prompt** (~15%) — always present, never compacted
- **Anchors/pins** (~10%) — critical info that survives compaction
- **Conversation history** (~75%) — compacted when budget exceeded
When conversation history exceeds its budget, the manager triggers
smart windowing (3-zone compaction): recent messages preserved,
middle messages summarized, old messages dropped.
#### Example
```typescript
const agent = new Agent({
provider,
contextManager: new ContextManager({
maxTokens: 100000,
budgets: { system: 0.15, anchors: 0.10, conversation: 0.75 },
}),
});
```
#### Constructors
##### Constructor
```ts
new ContextManager(options): ContextManager;
```
Defined in: [context/manager.ts:163](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L163)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options` | [`ContextManagerOptions`](#contextmanageroptions) |
###### Returns
[`ContextManager`](#contextmanager)
#### Methods
##### addToCategory()
```ts
addToCategory(category, tokens): void;
```
Defined in: [context/manager.ts:410](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L410)
Add tokens to a category
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `category` | [`ContextCategory`](#contextcategory) |
| `tokens` | `number` |
###### Returns
`void`
##### canAddContent()
```ts
canAddContent(estimatedTokens, category): PreflightResult;
```
Defined in: [context/manager.ts:873](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L873)
Check if content can be added to a category
Returns a pre-flight result with recommendations for action.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `estimatedTokens` | `number` |
| `category` | [`ContextCategory`](#contextcategory) |
###### Returns
[`PreflightResult`](#preflightresult)
##### categorizeMessages()
```ts
categorizeMessages(messages, preserveRecentTurns?): Promise;
```
Defined in: [context/manager.ts:549](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L549)
Categorize all messages by type for smart compaction
This method:
1. Identifies system messages
2. Separates recent messages (last N turns) that should never be compacted
3. Identifies tool results in older messages
4. Classifies remaining older messages as history
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `messages` | [`Message`](#message-4)[] | All messages to categorize |
| `preserveRecentTurns?` | `number` | Number of recent turns to preserve (default: config value) |
###### Returns
`Promise`\<`CategorizedMessages`\>
##### categoryNeedsCompaction()
```ts
categoryNeedsCompaction(category): boolean;
```
Defined in: [context/manager.ts:418](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L418)
Check if a specific category needs compaction
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `category` | [`ContextCategory`](#contextcategory) |
###### Returns
`boolean`
##### checkAndWarn()
```ts
checkAndWarn(): void;
```
Defined in: [context/manager.ts:1302](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L1302)
Check context and emit warning if needed
###### Returns
`void`
##### compact()
```ts
compact(messages, saveToFile): Promise<{
messages: Message[];
result: CompactionResult;
}>;
```
Defined in: [context/manager.ts:1054](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L1054)
Compact old messages by replacing large content with file references
This is a placeholder - actual implementation requires file system access
which will be provided by the Agent or CLI layer.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `saveToFile` | (`content`, `index`) => `Promise`\<`string`\> |
###### Returns
`Promise`\<\{
`messages`: [`Message`](#message-4)[];
`result`: [`CompactionResult`](#compactionresult);
\}\>
##### compactCategory()
```ts
compactCategory(
messages,
category,
saveToFile): Promise<{
messages: Message[];
result: CompactionResult;
}>;
```
Defined in: [context/manager.ts:429](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L429)
Compact only a specific category
This is more targeted than full compaction - only affects messages
in the specified category, leaving others untouched.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `category` | [`ContextCategory`](#contextcategory) |
| `saveToFile` | (`content`, `index`) => `Promise`\<`string`\> |
###### Returns
`Promise`\<\{
`messages`: [`Message`](#message-4)[];
`result`: [`CompactionResult`](#compactionresult);
\}\>
##### countTokens()
```ts
countTokens(messages): Promise;
```
Defined in: [context/manager.ts:205](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L205)
Count tokens in messages using the provider
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
###### Returns
`Promise`\<`number`\>
##### createRestorationHintMessage()
```ts
createRestorationHintMessage(): Message | undefined;
```
Defined in: [context/manager.ts:351](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L351)
Create a system message with context restoration hints.
Returns undefined if no hints are available.
The caller (Agent) is responsible for injecting this message
after compaction or summarization.
###### Returns
[`Message`](#message-4) \| `undefined`
##### estimateTokens()
```ts
estimateTokens(content): number;
```
Defined in: [context/manager.ts:864](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L864)
Estimate tokens for a string content
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `content` | `string` |
###### Returns
`number`
##### filterContent()
```ts
filterContent(content, type): {
content: string;
filtered: boolean;
originalLength: number;
};
```
Defined in: [context/manager.ts:987](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L987)
Filter large content before adding to context
Returns the filtered content and metadata about what was done.
The caller is responsible for saving to file if needed.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `content` | `string` |
| `type` | `"tool_result"` \| `"error"` \| `"file"` |
###### Returns
```ts
{
content: string;
filtered: boolean;
originalLength: number;
}
```
| Name | Type | Defined in |
| ------ | ------ | ------ |
| `content` | `string` | [context/manager.ts:991](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L991) |
| `filtered` | `boolean` | [context/manager.ts:992](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L992) |
| `originalLength` | `number` | [context/manager.ts:993](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L993) |
##### findOverBudgetCategories()
```ts
findOverBudgetCategories(categorized): ContextCategory[];
```
Defined in: [context/manager.ts:623](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L623)
Find which categories are over their budget allocation
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `categorized` | `CategorizedMessages` | Categorized messages from categorizeMessages() |
###### Returns
[`ContextCategory`](#contextcategory)[]
Array of categories that exceed their budget, sorted by how much they exceed
##### formatRestorationHints()
```ts
formatRestorationHints(): string;
```
Defined in: [context/manager.ts:334](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L334)
Format context restoration hints based on current verbosity level.
Returns empty string if no file tracker is configured or no files have been accessed.
###### Returns
`string`
##### getAllBudgets()
```ts
getAllBudgets(): Record;
```
Defined in: [context/manager.ts:389](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L389)
Get budget information for all categories
###### Returns
`Record`\<[`ContextCategory`](#contextcategory), [`CategoryBudgetInfo`](#categorybudgetinfo)\>
##### getCategoryBudget()
```ts
getCategoryBudget(category): CategoryBudgetInfo;
```
Defined in: [context/manager.ts:370](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L370)
Get budget information for a specific category
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `category` | [`ContextCategory`](#contextcategory) |
###### Returns
[`CategoryBudgetInfo`](#categorybudgetinfo)
##### getConfig()
```ts
getConfig(): ContextConfig;
```
Defined in: [context/manager.ts:319](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L319)
Get the current configuration
###### Returns
[`ContextConfig`](#contextconfig)
##### getFileTracker()
```ts
getFileTracker(): FileAccessTracker | undefined;
```
Defined in: [context/manager.ts:326](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L326)
Get the file access tracker (if configured)
###### Returns
[`FileAccessTracker`](#fileaccesstracker) \| `undefined`
##### getMaxTokens()
```ts
getMaxTokens(): number;
```
Defined in: [context/manager.ts:239](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L239)
Get maximum context tokens
###### Returns
`number`
##### getStats()
```ts
getStats(messageCount): ContextStats;
```
Defined in: [context/manager.ts:304](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L304)
Get context statistics
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messageCount` | `number` |
###### Returns
[`ContextStats`](#contextstats-1)
##### getTokenCount()
```ts
getTokenCount(): number;
```
Defined in: [context/manager.ts:225](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L225)
Get current token count (cached)
###### Returns
`number`
##### getTurnCount()
```ts
getTurnCount(): number;
```
Defined in: [context/manager.ts:253](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L253)
Get the current turn count
###### Returns
`number`
##### getUtilization()
```ts
getUtilization(): number;
```
Defined in: [context/manager.ts:232](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L232)
Get context utilization (0.0 - 1.0)
###### Returns
`number`
##### getVerbosityLevel()
```ts
getVerbosityLevel(): VerbosityLevel;
```
Defined in: [context/manager.ts:948](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L948)
Get current verbosity level based on context utilization
Tools should adapt their output based on this level.
###### Returns
[`VerbosityLevel`](#verbositylevel-1)
##### incrementTurn()
```ts
incrementTurn(): void;
```
Defined in: [context/manager.ts:246](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L246)
Increment turn count (call after each assistant response)
###### Returns
`void`
##### isMinimalMode()
```ts
isMinimalMode(): boolean;
```
Defined in: [context/manager.ts:966](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L966)
Check if we're in minimal mode (critical context pressure)
###### Returns
`boolean`
##### needsCompaction()
```ts
needsCompaction(): boolean;
```
Defined in: [context/manager.ts:272](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L272)
Check if compaction is needed
###### Returns
`boolean`
##### needsEmergencySummarization()
```ts
needsEmergencySummarization(): boolean;
```
Defined in: [context/manager.ts:973](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L973)
Check if emergency summarization is needed
###### Returns
`boolean`
##### needsSummarization()
```ts
needsSummarization(): boolean;
```
Defined in: [context/manager.ts:290](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L290)
Check if summarization is needed (more aggressive than compaction)
###### Returns
`boolean`
##### reset()
```ts
reset(): void;
```
Defined in: [context/manager.ts:1323](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L1323)
Reset context manager state (for new conversations)
###### Returns
`void`
##### setTurnCount()
```ts
setTurnCount(count): void;
```
Defined in: [context/manager.ts:260](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L260)
Set the turn count (for restoring from saved state)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `count` | `number` |
###### Returns
`void`
##### shouldFilter()
```ts
shouldFilter(tokenCount): boolean;
```
Defined in: [context/manager.ts:297](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L297)
Check if content should be filtered before adding
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `tokenCount` | `number` |
###### Returns
`boolean`
##### smartCompact()
```ts
smartCompact(messages, options): Promise<{
messages: Message[];
result: SmartCompactionResult;
}>;
```
Defined in: [context/manager.ts:657](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L657)
Smart compaction that respects category budgets
Strategy:
1. System messages: Never compacted (critical for agent behavior)
2. Recent messages: Never compacted (needed for conversation continuity)
3. Tool results: Save large results to files, replace with references
4. History: Summarize with LLM
The method compacts categories in order of how much they exceed their budget.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `options` | `SmartCompactOptions` |
###### Returns
`Promise`\<\{
`messages`: [`Message`](#message-4)[];
`result`: `SmartCompactionResult`;
\}\>
##### summarize()
```ts
summarize(messages, generateSummary): Promise<{
messages: Message[];
result: SummarizationResult;
}>;
```
Defined in: [context/manager.ts:1136](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L1136)
Summarize conversation history
This is a placeholder - actual implementation requires LLM call
which will be orchestrated by the Agent layer.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `generateSummary` | (`messages`) => `Promise`\<`string`\> |
###### Returns
`Promise`\<\{
`messages`: [`Message`](#message-4)[];
`result`: [`SummarizationResult`](#summarizationresult);
\}\>
##### summarizeWithRetry()
```ts
summarizeWithRetry(
messages,
generateSummary,
options?): Promise<{
messages: Message[];
result: SummarizationResult;
}>;
```
Defined in: [context/manager.ts:1201](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L1201)
Summarize with support for multiple rounds and emergency mode
Will perform multiple summarization rounds if needed to reach target utilization.
Throws ContextOverflowError if unable to reduce context sufficiently.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `generateSummary` | (`messages`) => `Promise`\<`string`\> |
| `options?` | \{ `emergency?`: `boolean`; `maxRounds?`: `number`; `targetUtilization?`: `number`; \} |
| `options.emergency?` | `boolean` |
| `options.maxRounds?` | `number` |
| `options.targetUtilization?` | `number` |
###### Returns
`Promise`\<\{
`messages`: [`Message`](#message-4)[];
`result`: [`SummarizationResult`](#summarizationresult);
\}\>
##### updateCategoryUsage()
```ts
updateCategoryUsage(category, tokens): void;
```
Defined in: [context/manager.ts:401](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L401)
Update token usage for a category
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `category` | [`ContextCategory`](#contextcategory) |
| `tokens` | `number` |
###### Returns
`void`
##### updateTokenCount()
```ts
updateTokenCount(messages): Promise;
```
Defined in: [context/manager.ts:217](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/manager.ts#L217)
Update token count for messages
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
###### Returns
`Promise`\<`number`\>
***
### ContextOverflowError
Defined in: [errors.ts:258](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L258)
Error thrown when context window cannot be reduced sufficiently.
This occurs when:
- Multiple summarization rounds fail to reduce context below target
- Content is too large even after aggressive filtering
#### Example
```typescript
throw new ContextOverflowError(
'Unable to reduce context below 90% after 3 summarization rounds',
0.95, // current utilization
3 // rounds attempted
);
```
#### Extends
- [`AgentError`](#agenterror)
#### Constructors
##### Constructor
```ts
new ContextOverflowError(
message,
utilization,
roundsAttempted?): ContextOverflowError;
```
Defined in: [errors.ts:259](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L259)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `message` | `string` |
| `utilization` | `number` |
| `roundsAttempted?` | `number` |
###### Returns
[`ContextOverflowError`](#contextoverflowerror)
###### Overrides
[`AgentError`](#agenterror).[`constructor`](#constructor-2)
#### Properties
##### cause?
```ts
readonly optional cause?: Error;
```
Defined in: [errors.ts:17](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L17)
###### Inherited from
[`AgentError`](#agenterror).[`cause`](#cause-1)
##### roundsAttempted?
```ts
readonly optional roundsAttempted?: number;
```
Defined in: [errors.ts:262](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L262)
##### utilization
```ts
readonly utilization: number;
```
Defined in: [errors.ts:261](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/errors.ts#L261)
***
### DeadMessagePruner
Defined in: [context/dead-message-pruner.ts:83](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L83)
#### Constructors
##### Constructor
```ts
new DeadMessagePruner(config?): DeadMessagePruner;
```
Defined in: [context/dead-message-pruner.ts:93](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L93)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `config?` | `Partial`\<[`PruneConfig`](#pruneconfig)\> |
###### Returns
[`DeadMessagePruner`](#deadmessagepruner)
#### Methods
##### getConfig()
```ts
getConfig(): PruneConfig;
```
Defined in: [context/dead-message-pruner.ts:209](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L209)
Get current configuration (for testing/inspection).
###### Returns
[`PruneConfig`](#pruneconfig)
##### getStats()
```ts
getStats(): PruneStats;
```
Defined in: [context/dead-message-pruner.ts:194](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L194)
###### Returns
[`PruneStats`](#prunestats)
##### prune()
```ts
prune(messages, currentTurn): PruneResult;
```
Defined in: [context/dead-message-pruner.ts:128](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L128)
Prune dead messages in-place. Replaces content of dead tool_result
blocks with short placeholders and clears corresponding tool_use input.
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `messages` | [`Message`](#message-4)[] |
| `currentTurn` | `number` |
###### Returns
[`PruneResult`](#pruneresult)
##### reset()
```ts
reset(): void;
```
Defined in: [context/dead-message-pruner.ts:201](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L201)
Reset all state (stamps and stats). Used when clearing history.
###### Returns
`void`
##### stamp()
```ts
stamp(
toolUseId,
toolName,
input,
isError,
turn): void;
```
Defined in: [context/dead-message-pruner.ts:105](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/context/dead-message-pruner.ts#L105)
Register a tool result for pruning analysis.
Called at the same point as ObservationMasker.stamp().
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `toolUseId` | `string` |
| `toolName` | `string` |
| `input` | `Record`\<`string`, `unknown`\> |
| `isError` | `boolean` |
| `turn` | `number` |
###### Returns
`void`
***
### DefaultToolRegistry
Defined in: [tools/registry.ts:48](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/tools/registry.ts#L48)
Default implementation of ToolRegistry
#### Implements
- [`ToolRegistry`](#toolregistry-1)
#### Constructors
##### Constructor
```ts
new DefaultToolRegistry(options?): DefaultToolRegistry;
```
Defined in: [tools/registry.ts:54](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/tools/registry.ts#L54)
###### Parameters
| Parameter | Type |
| ------ | ------ |
| `options?` | [`ToolRegistryOptions`](#toolregistryoptions) |
###### Returns
[`DefaultToolRegistry`](#defaulttoolregistry)
#### Accessors
##### size
###### Get Signature
```ts
get size(): number;
```
Defined in: [tools/registry.ts:125](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/tools/registry.ts#L125)
Get the number of registered tools
###### Returns
`number`
#### Methods
##### clear()
```ts
clear(): void;
```
Defined in: [tools/registry.ts:232](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/tools/registry.ts#L232)
Clear all registered tools
###### Returns
`void`
##### execute()
```ts
execute(
name,
input,
contextOrTimeout?,
timeoutMs?): Promise;
```
Defined in: [tools/registry.ts:137](https://github.com/scozzola/compilr-dev-agents/blob/1165e943e9e778673268c207af819ac0755d3ce1/src/tools/registry.ts#L137)
Execute a tool by name with given input
###### Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | Tool name |
| `input` | `Record`\<`string`, `unknown`\> | Tool input parameters |
| `contextOrTimeout?` | `number` \| `ToolExecutionContext` | Optional execution context or timeout override |
| `timeoutMs?` | `number` | Optional timeout override (uses default if not provided) |
###### Returns
`Promise`\<[`ToolExecutionResult`](#toolexecutionresult)\>
###### Implementation of
[`ToolRegistry`](#toolregistry-1).[`execute`](#execute-3)
##### get()
```ts
get(name): Tool