attocode 0.1.0

package/dist/src/modes.js

@@ -0,0 +1,385 @@
+/**
+ * Lesson 25: Agent Modes (OpenCode-inspired)
+ *
+ * Provides different operational modes for the agent:
+ * - Build: Full access to modify files and run commands
+ * - Plan: Read-only mode for exploration and planning
+ * - Review: Read-only mode focused on code review
+ *
+ * Users can switch modes with Tab key or /mode command.
+ *
+ * Usage:
+ *   agent.setMode('plan');
+ *   const currentMode = agent.getMode();
+ */
+/**
+ * Tools that modify the filesystem or execute side effects.
+ * In plan mode with write approval, these are queued instead of executed.
+ */
+export const WRITE_TOOLS = [
+    'write_file',
+    'edit_file',
+    'delete_file',
+    'bash', // Can have side effects
+    'spawn_agent', // Subagents can modify files
+    'run_tests', // Can have side effects
+    'execute_code', // Can have side effects
+];
+/**
+ * Check if a tool is a write operation.
+ */
+export function isWriteTool(toolName) {
+    return WRITE_TOOLS.includes(toolName);
+}
+/**
+ * Analyze bash command to determine if it's a write operation.
+ * Returns true for commands that modify state.
+ */
+export function isBashWriteCommand(command) {
+    const writePatterns = [
+        /\brm\b/, // Remove files
+        /\bmv\b/, // Move/rename files
+        /\bcp\b/, // Copy files
+        /\bmkdir\b/, // Create directories
+        /\btouch\b/, // Create/modify files
+        /\bchmod\b/, // Change permissions
+        /\bchown\b/, // Change ownership
+        /\b(npm|yarn|pnpm)\s+(install|add|remove|uninstall)/i, // Package managers
+        /\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout)/i, // Git write ops
+        /\becho\b.*>/, // Redirect to file
+        /\bcat\b.*>/, // Redirect to file
+        /\btee\b/, // Write to file
+        /\bsed\b.*-i/, // In-place edit
+        /\bawk\b.*-i/, // In-place edit
+        />\s*\S/, // Any redirect
+        /\|\s*tee\b/, // Pipe to tee
+    ];
+    return writePatterns.some(pattern => pattern.test(command));
+}
+// =============================================================================
+// MODE DEFINITIONS
+// =============================================================================
+/**
+ * Read-only tools available in restricted modes.
+ */
+export const READ_ONLY_TOOLS = [
+    'read_file',
+    'list_files',
+    'list_directory',
+    'search',
+    'glob',
+    'grep',
+    'get_file_info',
+    'git_status',
+    'git_log',
+    'git_diff',
+    'lsp_definition',
+    'lsp_references',
+    'lsp_hover',
+];
+/**
+ * All tools (for build mode).
+ */
+export const ALL_TOOLS = '*'; // Special marker for "all tools"
+/**
+ * Mode configurations.
+ */
+export const MODES = {
+    build: {
+        name: 'Build',
+        description: 'Full access to modify files and run commands',
+        availableTools: [ALL_TOOLS],
+        systemPromptAddition: `
+You are in BUILD mode with full access to modify files and run commands.
+- You can create, edit, and delete files
+- You can run shell commands and scripts
+- You can make changes to the codebase
+- Proceed with caution and verify changes before committing
+`,
+        color: '\x1b[32m', // Green
+        icon: '🔨',
+        requireWriteApproval: false,
+        showPlanPrompt: false,
+    },
+    plan: {
+        name: 'Plan',
+        description: 'Exploration mode - writes queued for approval',
+        availableTools: [ALL_TOOLS], // All tools available, but writes are intercepted
+        systemPromptAddition: `
+You are in PLAN mode.
+- You can read files, explore the codebase, and use all tools
+- IMPORTANT: Write operations (file edits, bash commands with side effects) will be QUEUED for user approval
+- The queued changes will be shown to the user as a "pending plan"
+- Focus on understanding the codebase and proposing specific changes
+- Your proposed changes should include clear explanations of WHY each change is needed
+- After you finish exploring, the user can approve, modify, or reject the pending plan
+`,
+        color: '\x1b[34m', // Blue
+        icon: '📋',
+        requireWriteApproval: true,
+        showPlanPrompt: true,
+    },
+    review: {
+        name: 'Review',
+        description: 'Read-only mode focused on code review',
+        availableTools: READ_ONLY_TOOLS,
+        systemPromptAddition: `
+You are in REVIEW mode (read-only).
+- You can read files and analyze code
+- You CANNOT modify files
+- Focus on code quality, bugs, security issues, and best practices
+- Provide specific, actionable feedback
+- Point out both issues and positive patterns
+- Consider maintainability, readability, and performance
+`,
+        color: '\x1b[33m', // Yellow
+        icon: '🔍',
+        requireWriteApproval: false,
+        showPlanPrompt: false,
+    },
+    debug: {
+        name: 'Debug',
+        description: 'Debugging mode with diagnostic tools',
+        availableTools: [...READ_ONLY_TOOLS, 'run_tests', 'execute_code'],
+        systemPromptAddition: `
+You are in DEBUG mode.
+- You can read files and run diagnostic commands
+- You can execute tests and debug scripts
+- Focus on finding and isolating bugs
+- Use a systematic approach: reproduce, isolate, fix
+- Consider adding logging or debugging statements
+`,
+        color: '\x1b[35m', // Magenta
+        icon: '🐛',
+        requireWriteApproval: false,
+        showPlanPrompt: false,
+    },
+};
+// =============================================================================
+// MODE MANAGER
+// =============================================================================
+/**
+ * Manages agent modes and tool filtering.
+ */
+export class ModeManager {
+    currentMode = 'build';
+    eventListeners = new Set();
+    allToolNames = new Set();
+    constructor(tools = []) {
+        // Track all available tool names
+        for (const tool of tools) {
+            this.allToolNames.add(tool.name);
+        }
+    }
+    /**
+     * Get the current mode.
+     */
+    getMode() {
+        return this.currentMode;
+    }
+    /**
+     * Get the current mode configuration.
+     */
+    getModeConfig() {
+        return MODES[this.currentMode];
+    }
+    /**
+     * Set the agent mode.
+     */
+    setMode(mode) {
+        if (mode === this.currentMode)
+            return;
+        const from = this.currentMode;
+        this.currentMode = mode;
+        this.emit({ type: 'mode.changed', from, to: mode });
+    }
+    /**
+     * Cycle to the next mode.
+     */
+    cycleMode() {
+        const modes = ['build', 'plan', 'review', 'debug'];
+        const currentIndex = modes.indexOf(this.currentMode);
+        const nextIndex = (currentIndex + 1) % modes.length;
+        const nextMode = modes[nextIndex];
+        this.setMode(nextMode);
+        return nextMode;
+    }
+    /**
+     * Check if a tool is available in the current mode.
+     */
+    isToolAvailable(toolName) {
+        const config = MODES[this.currentMode];
+        // Build mode has all tools
+        if (config.availableTools.includes(ALL_TOOLS)) {
+            return true;
+        }
+        return config.availableTools.includes(toolName);
+    }
+    /**
+     * Filter tools based on current mode.
+     */
+    filterTools(tools) {
+        const config = MODES[this.currentMode];
+        // Build mode has all tools
+        if (config.availableTools.includes(ALL_TOOLS)) {
+            return tools;
+        }
+        return tools.filter((tool) => {
+            const available = config.availableTools.includes(tool.name);
+            if (!available) {
+                this.emit({ type: 'mode.tool.filtered', tool: tool.name, mode: this.currentMode });
+            }
+            return available;
+        });
+    }
+    /**
+     * Get the system prompt addition for the current mode.
+     */
+    getSystemPromptAddition() {
+        return MODES[this.currentMode].systemPromptAddition;
+    }
+    /**
+     * Get all available modes.
+     */
+    getAllModes() {
+        return Object.keys(MODES);
+    }
+    /**
+     * Get mode info for display.
+     */
+    getModeInfo(mode) {
+        const m = mode ?? this.currentMode;
+        const config = MODES[m];
+        return {
+            name: config.name,
+            icon: config.icon,
+            color: config.color,
+        };
+    }
+    /**
+     * Format mode for terminal display.
+     */
+    formatModePrompt() {
+        const config = MODES[this.currentMode];
+        return `${config.color}${config.icon} ${config.name}\x1b[0m`;
+    }
+    /**
+     * Subscribe to mode events.
+     */
+    subscribe(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /**
+     * Update available tools.
+     */
+    updateTools(tools) {
+        this.allToolNames.clear();
+        for (const tool of tools) {
+            this.allToolNames.add(tool.name);
+        }
+    }
+    /**
+     * Check if the current mode requires write approval.
+     */
+    requiresWriteApproval() {
+        return MODES[this.currentMode].requireWriteApproval;
+    }
+    /**
+     * Check if the current mode should show plan prompts.
+     */
+    shouldShowPlanPrompt() {
+        return MODES[this.currentMode].showPlanPrompt;
+    }
+    /**
+     * Check if a tool call should be intercepted (queued) in current mode.
+     * Returns true if the tool is a write operation and mode requires approval.
+     *
+     * @param toolName - The name of the tool
+     * @param args - The tool arguments (needed to check bash commands)
+     */
+    shouldInterceptTool(toolName, args) {
+        if (!this.requiresWriteApproval()) {
+            return false;
+        }
+        // Check if it's a known write tool
+        if (isWriteTool(toolName)) {
+            // Special case: bash commands need content analysis
+            if (toolName === 'bash' && args?.command) {
+                return isBashWriteCommand(String(args.command));
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Toggle between build and plan modes.
+     * Useful for shift-tab or /plan command.
+     */
+    togglePlanMode() {
+        if (this.currentMode === 'plan') {
+            this.setMode('build');
+            return 'build';
+        }
+        else {
+            this.setMode('plan');
+            return 'plan';
+        }
+    }
+    // Internal methods
+    emit(event) {
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a mode manager.
+ */
+export function createModeManager(tools) {
+    return new ModeManager(tools);
+}
+/**
+ * Format all modes for display.
+ */
+export function formatModeList() {
+    const lines = ['Available modes:'];
+    for (const [key, config] of Object.entries(MODES)) {
+        lines.push(`  ${config.icon} ${key.padEnd(8)} - ${config.description}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Parse mode from string (case-insensitive).
+ */
+export function parseMode(input) {
+    const normalized = input.toLowerCase().trim();
+    if (normalized in MODES) {
+        return normalized;
+    }
+    // Handle aliases
+    const aliases = {
+        'read': 'plan',
+        'readonly': 'plan',
+        'read-only': 'plan',
+        'explore': 'plan',
+        'code-review': 'review',
+        'codereview': 'review',
+        'cr': 'review',
+        'dev': 'build',
+        'development': 'build',
+        'write': 'build',
+        'bug': 'debug',
+        'fix': 'debug',
+    };
+    return aliases[normalized] || null;
+}
+//# sourceMappingURL=modes.js.map

package/dist/src/modes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes.js","sourceRoot":"","sources":["../../src/modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoDH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,YAAY;IACZ,WAAW;IACX,aAAa;IACb,MAAM,EAAY,wBAAwB;IAC1C,aAAa,EAAK,6BAA6B;IAC/C,WAAW,EAAO,wBAAwB;IAC1C,cAAc,EAAI,wBAAwB;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,aAAa,GAAG;QACpB,QAAQ,EAAY,eAAe;QACnC,QAAQ,EAAY,oBAAoB;QACxC,QAAQ,EAAY,aAAa;QACjC,WAAW,EAAS,qBAAqB;QACzC,WAAW,EAAS,sBAAsB;QAC1C,WAAW,EAAS,qBAAqB;QACzC,WAAW,EAAS,mBAAmB;QACvC,qDAAqD,EAAG,mBAAmB;QAC3E,6DAA6D,EAAE,gBAAgB;QAC/E,aAAa,EAAO,mBAAmB;QACvC,YAAY,EAAQ,mBAAmB;QACvC,SAAS,EAAW,gBAAgB;QACpC,aAAa,EAAO,gBAAgB;QACpC,aAAa,EAAO,gBAAgB;QACpC,QAAQ,EAAY,eAAe;QACnC,YAAY,EAAQ,cAAc;KACnC,CAAC;IAEF,OAAO,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW;IACX,YAAY;IACZ,gBAAgB;IAChB,QAAQ;IACR,MAAM;IACN,MAAM;IACN,eAAe;IACf,YAAY;IACZ,SAAS;IACT,UAAU;IACV,gBAAgB;IAChB,gBAAgB;IAChB,WAAW;CACZ,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,iCAAiC;AAE/D;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAkC;IAClD,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,8CAA8C;QAC3D,cAAc,EAAE,CAAC,SAAS,CAAC;QAC3B,oBAAoB,EAAE;;;;;;CAMzB;QACG,KAAK,EAAE,UAAU,EAAE,QAAQ;QAC3B,IAAI,EAAE,IAAI;QACV,oBAAoB,EAAE,KAAK;QAC3B,cAAc,EAAE,KAAK;KACtB;IAED,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,+CAA+C;QAC5D,cAAc,EAAE,CAAC,SAAS,CAAC,EAAE,kDAAkD;QAC/E,oBAAoB,EAAE;;;;;;;;CAQzB;QACG,KAAK,EAAE,UAAU,EAAE,OAAO;QAC1B,IAAI,EAAE,IAAI;QACV,oBAAoB,EAAE,IAAI;QAC1B,cAAc,EAAE,IAAI;KACrB;IAED,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,uCAAuC;QACpD,cAAc,EAAE,eAAe;QAC/B,oBAAoB,EAAE;;;;;;;;CAQzB;QACG,KAAK,EAAE,UAAU,EAAE,SAAS;QAC5B,IAAI,EAAE,IAAI;QACV,oBAAoB,EAAE,KAAK;QAC3B,cAAc,EAAE,KAAK;KACtB;IAED,KAAK,EAAE;QACL,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,sCAAsC;QACnD,cAAc,EAAE,CAAC,GAAG,eAAe,EAAE,WAAW,EAAE,cAAc,CAAC;QACjE,oBAAoB,EAAE;;;;;;;CAOzB;QACG,KAAK,EAAE,UAAU,EAAE,UAAU;QAC7B,IAAI,EAAE,IAAI;QACV,oBAAoB,EAAE,KAAK;QAC3B,cAAc,EAAE,KAAK;KACtB;CACF,CAAC;AAEF,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;GAEG;AACH,MAAM,OAAO,WAAW;IACd,WAAW,GAAc,OAAO,CAAC;IACjC,cAAc,GAA2B,IAAI,GAAG,EAAE,CAAC;IACnD,YAAY,GAAgB,IAAI,GAAG,EAAE,CAAC;IAE9C,YAAY,QAA0B,EAAE;QACtC,iCAAiC;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAe;QACrB,IAAI,IAAI,KAAK,IAAI,CAAC,WAAW;YAAE,OAAO;QAEtC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAExB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,SAAS;QACP,MAAM,KAAK,GAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,MAAM,SAAS,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;QAElC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,QAAgB;QAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAEvC,2BAA2B;QAC3B,IAAI,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAuB;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAEvC,2BAA2B;QAC3B,IAAI,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YAC3B,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5D,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YACrF,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,uBAAuB;QACrB,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,oBAAoB,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAgB,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,IAAgB;QAC1B,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvC,OAAO,GAAG,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,SAAS,CAAC;IAC/D,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAA2B;QACnC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,KAAuB;QACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,qBAAqB;QACnB,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,oBAAoB,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,cAAc,CAAC;IAChD,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,QAAgB,EAAE,IAA8B;QAClE,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,mCAAmC;QACnC,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,oDAAoD;YACpD,IAAI,QAAQ,KAAK,MAAM,IAAI,IAAI,EAAE,OAAO,EAAE,CAAC;gBACzC,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,OAAO,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,mBAAmB;IAEX,IAAI,CAAC,KAAgB;QAC3B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,OAAO,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,KAAK,GAAa,CAAC,kBAAkB,CAAC,CAAC;IAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAE9C,IAAI,UAAU,IAAI,KAAK,EAAE,CAAC;QACxB,OAAO,UAAuB,CAAC;IACjC,CAAC;IAED,iBAAiB;IACjB,MAAM,OAAO,GAA8B;QACzC,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,MAAM;QAClB,WAAW,EAAE,MAAM;QACnB,SAAS,EAAE,MAAM;QACjB,aAAa,EAAE,QAAQ;QACvB,YAAY,EAAE,QAAQ;QACtB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,OAAO;QACd,aAAa,EAAE,OAAO;QACtB,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,OAAO;KACf,CAAC;IAEF,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AACrC,CAAC"}

package/dist/src/observability/tracer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Lesson 19: Tracer
+ *
+ * OpenTelemetry-style distributed tracing for agents.
+ * Tracks operations as spans with parent-child relationships.
+ */
+import type { Span, SpanKind, SpanStatus, SpanAttributeValue, Trace, ObservabilityEventListener } from './types.js';
+/**
+ * Context for propagating trace information.
+ */
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+}
+/**
+ * Get current span context.
+ */
+export declare function getCurrentContext(): SpanContext | undefined;
+/**
+ * Creates and manages spans for distributed tracing.
+ */
+export declare class Tracer {
+    private spans;
+    private traces;
+    private listeners;
+    private serviceName;
+    private sampleRate;
+    constructor(serviceName?: string, sampleRate?: number);
+    /**
+     * Start a new span.
+     */
+    startSpan(name: string, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, SpanAttributeValue>;
+        parent?: SpanContext;
+    }): Span;
+    /**
+     * End a span.
+     */
+    endSpan(span: Span, status?: SpanStatus): void;
+    /**
+     * Mark span as error.
+     */
+    setError(span: Span, error: Error): void;
+    /**
+     * Set span attribute.
+     */
+    setAttribute(span: Span, key: string, value: SpanAttributeValue): void;
+    /**
+     * Set multiple span attributes.
+     */
+    setAttributes(span: Span, attributes: Record<string, SpanAttributeValue>): void;
+    /**
+     * Add an event to a span.
+     */
+    addEvent(span: Span, name: string, attributes?: Record<string, SpanAttributeValue>): void;
+    /**
+     * Wrap an async function with a span.
+     */
+    withSpan<T>(name: string, fn: (span: Span) => Promise<T>, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, SpanAttributeValue>;
+    }): Promise<T>;
+    /**
+     * Wrap a sync function with a span.
+     */
+    withSpanSync<T>(name: string, fn: (span: Span) => T, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, SpanAttributeValue>;
+    }): T;
+    /**
+     * Get a trace by ID.
+     */
+    getTrace(traceId: string): Trace | undefined;
+    /**
+     * Get all traces.
+     */
+    getAllTraces(): Trace[];
+    /**
+     * Get a span by ID.
+     */
+    getSpan(spanId: string): Span | undefined;
+    /**
+     * Get child spans of a span.
+     */
+    getChildSpans(spanId: string): Span[];
+    /**
+     * Clear all traces and spans.
+     */
+    clear(): void;
+    /**
+     * Subscribe to tracer events.
+     */
+    on(listener: ObservabilityEventListener): () => void;
+    /**
+     * Emit an event.
+     */
+    private emit;
+}
+/**
+ * Format a trace as a tree.
+ */
+export declare function formatTraceTree(trace: Trace): string;
+/**
+ * Format span attributes.
+ */
+export declare function formatSpanAttributes(span: Span): string;
+export declare function createTracer(serviceName?: string, sampleRate?: number): Tracer;
+export declare const globalTracer: Tracer;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/src/observability/tracer.d.ts.map

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