attocode 0.2.3 → 0.2.5

package/dist/src/integrations/agents/agent-registry.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Lesson 25: Extensible Agent Registry
+ *
+ * Allows users to define custom agents that can be spawned on demand.
+ * Supports:
+ * - Built-in agents (researcher, coder, reviewer, architect)
+ * - User-defined agents from .agents/ directory (YAML/JSON)
+ * - Hot-reload of agent definitions
+ * - NL-based agent selection
+ */
+import type { LLMProvider, ToolDefinition } from '../../types.js';
+/**
+ * Agent definition - describes a spawnable agent.
+ */
+export interface AgentDefinition {
+    name: string;
+    description: string;
+    systemPrompt: string;
+    tools?: string[];
+    model?: 'fast' | 'balanced' | 'quality' | string;
+    maxTokenBudget?: number;
+    maxIterations?: number;
+    timeout?: number;
+    capabilities?: string[];
+    tags?: string[];
+    /** Control MCP tool access: true = all MCP tools (default), false = none, string[] = specific names */
+    allowMcpTools?: boolean | string[];
+    /** Optional named policy profile */
+    policyProfile?: string;
+    /** Optional explicit task type hint for policy/tool resolution */
+    taskType?: string;
+    /** Optional idle timeout override in ms (time without tool calls before kill) */
+    idleTimeout?: number;
+    /** Optional economics tuning overrides for doom loop/exploration thresholds */
+    economicsTuning?: import('../budget/economics.js').EconomicsTuning;
+    /** Optional budget enforcement mode override ('strict' | 'doomloop_only') */
+    enforcementMode?: 'strict' | 'doomloop_only';
+}
+/**
+ * Agent source type for display and management.
+ */
+export type AgentSourceType = 'builtin' | 'user' | 'project' | 'legacy';
+/**
+ * Loaded agent with source info.
+ */
+export interface LoadedAgent extends AgentDefinition {
+    source: AgentSourceType;
+    filePath?: string;
+    loadedAt: Date;
+}
+/**
+ * Agent spawn options.
+ */
+export interface SpawnOptions {
+    task: string;
+    provider: LLMProvider;
+    tools: ToolDefinition[];
+    onProgress?: (message: string) => void;
+}
+/**
+ * Agent spawn result.
+ */
+export interface SpawnResult {
+    success: boolean;
+    output: string;
+    metrics: {
+        tokens: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        duration: number;
+        toolCalls: number;
+    };
+    /** Structured closure report (populated when subagent wraps up properly) */
+    structured?: StructuredClosureReport;
+    /** Reference ID in SubagentOutputStore for retrieving full output */
+    outputStoreId?: string;
+    /** Actual file paths modified by the subagent (from economics tracker) */
+    filesModified?: string[];
+}
+/**
+ * Structured closure report from a subagent.
+ * Populated when a subagent produces a wrapup summary (graceful timeout or normal completion).
+ */
+export interface StructuredClosureReport {
+    findings: string[];
+    actionsTaken: string[];
+    failures: string[];
+    remainingWork: string[];
+    exitReason: 'completed' | 'timeout_graceful' | 'timeout_hard' | 'cancelled' | 'budget_exceeded' | 'error';
+    suggestedNextSteps?: string[];
+}
+/**
+ * Registry events.
+ */
+export type RegistryEvent = {
+    type: 'agent.loaded';
+    name: string;
+    source: string;
+} | {
+    type: 'agent.reloaded';
+    name: string;
+} | {
+    type: 'agent.removed';
+    name: string;
+} | {
+    type: 'agent.error';
+    name: string;
+    error: string;
+} | {
+    type: 'agent.spawned';
+    name: string;
+    task: string;
+} | {
+    type: 'agent.completed';
+    name: string;
+    success: boolean;
+};
+export type RegistryEventListener = (event: RegistryEvent) => void;
+/**
+ * Default agent directories with priority hierarchy:
+ * built-in < ~/.attocode/ < .attocode/ (later entries override earlier)
+ *
+ * Legacy paths (.agents/) are included for backward compatibility.
+ */
+export declare function getDefaultAgentDirectories(): string[];
+/**
+ * Get the directory where new agents should be created.
+ * Prefers .attocode/agents/ in the project root.
+ */
+export declare function getAgentCreationDirectory(): string;
+/**
+ * Get the user-level agent directory.
+ */
+export declare function getUserAgentDirectory(): string;
+/**
+ * Determine the source type of an agent based on its path.
+ */
+export declare function getAgentSourceType(agentPath: string): AgentSourceType;
+/**
+ * Get a human-readable location string for an agent.
+ */
+export declare function getAgentLocationDisplay(agent: LoadedAgent): string;
+/**
+ * AgentRegistry manages agent definitions and spawning.
+ */
+export declare class AgentRegistry {
+    private agents;
+    private listeners;
+    private watchController?;
+    private baseDir;
+    constructor(baseDir?: string);
+    /**
+     * Load user-defined agents from all configured directories.
+     * Loads in priority order: user-level, project-level, legacy.
+     * Later entries with the same name override earlier ones.
+     */
+    loadUserAgents(): Promise<void>;
+    /**
+     * Find an agent definition file in a directory.
+     */
+    private findAgentFileInDir;
+    /**
+     * Load an agent from a file.
+     */
+    private loadAgentFile;
+    /**
+     * Simple YAML parser for basic agent definitions.
+     */
+    private parseSimpleYaml;
+    /**
+     * Watch .agents/ directory for changes.
+     */
+    startWatching(): void;
+    /**
+     * Stop watching for changes.
+     */
+    stopWatching(): void;
+    /**
+     * Get an agent by name.
+     */
+    getAgent(name: string): LoadedAgent | undefined;
+    /**
+     * Get all agents.
+     */
+    getAllAgents(): LoadedAgent[];
+    /**
+     * Get agents by source.
+     */
+    getAgentsBySource(source: 'builtin' | 'user'): LoadedAgent[];
+    /**
+     * Find agents matching a query (for NL routing).
+     */
+    findMatchingAgents(query: string, limit?: number): LoadedAgent[];
+    /**
+     * Register a runtime agent.
+     */
+    registerAgent(definition: AgentDefinition): void;
+    /**
+     * Unregister an agent.
+     */
+    unregisterAgent(name: string): boolean;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: RegistryEventListener): () => void;
+    /**
+     * Emit an event.
+     */
+    private emit;
+    /**
+     * Cleanup.
+     */
+    cleanup(): void;
+}
+/**
+ * Create an agent registry and load user agents.
+ */
+export declare function createAgentRegistry(baseDir?: string): Promise<AgentRegistry>;
+/**
+ * Filter tools based on agent's tool whitelist and MCP access policy.
+ * MCP tool access is controlled by `allowMcpTools`:
+ *   - true (default): all MCP tools pass through
+ *   - false: no MCP tools
+ *   - string[]: only specified MCP tool names
+ */
+export declare function filterToolsForAgent(agent: AgentDefinition, allTools: ToolDefinition[]): ToolDefinition[];
+/**
+ * Get a formatted list of agents for display.
+ */
+export declare function formatAgentList(agents: LoadedAgent[]): string;
+/**
+ * Get an agent scaffold template in YAML format.
+ */
+export declare function getAgentScaffold(name: string, options?: {
+    description?: string;
+    model?: 'fast' | 'balanced' | 'quality';
+    capabilities?: string[];
+    tools?: string[];
+}): string;
+/**
+ * Result of creating an agent scaffold.
+ */
+export interface AgentScaffoldResult {
+    success: boolean;
+    path?: string;
+    error?: string;
+}
+/**
+ * Create an agent scaffold in the .attocode/agents/ directory.
+ */
+export declare function createAgentScaffold(name: string, options?: {
+    description?: string;
+    model?: 'fast' | 'balanced' | 'quality';
+    capabilities?: string[];
+    tools?: string[];
+    userLevel?: boolean;
+}): Promise<AgentScaffoldResult>;
+/**
+ * Get statistics about loaded agents by source.
+ */
+export declare function getAgentStats(agents: LoadedAgent[]): Record<AgentSourceType, number>;
+//# sourceMappingURL=agent-registry.d.ts.map

package/dist/src/integrations/agents/agent-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.d.ts","sourceRoot":"","sources":["../../../../src/integrations/agents/agent-registry.ts"],"names":[],"mappings":"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"}