zoe-agent 0.3.1

package/dist/adapters/cli/config-loader.js

@@ -0,0 +1,48 @@
+/**
+ * Zoe CLI — Config Loader
+ *
+ * Re-exports core config utilities and adds CLI-specific chalk output.
+ */
+import chalk from 'chalk';
+import { loadJsonConfig as coreLoadJsonConfig, loadMergedConfig as coreLoadMergedConfig, applyEnvOverrides, getConfigPath, getConfigDir, getConfigPaths, migrateLegacyFormat, resolveActiveProviderType, saveConfig as coreSaveConfig, writeConfigToPath as coreWriteConfigToPath, maskSecret, } from '../../core/config.js';
+// ── Re-exports (unchanged API for CLI consumers) ───────────────────────
+export { applyEnvOverrides, getConfigPath, getConfigDir, getConfigPaths, migrateLegacyFormat, resolveActiveProviderType, maskSecret, };
+// ── CLI wrappers with chalk output ─────────────────────────────────────
+/**
+ * Load and parse a JSON config file, returning {} on failure.
+ * Logs parse warnings to console with chalk.
+ */
+export function loadJsonConfig(filePath) {
+    const { config, warning } = coreLoadJsonConfig(filePath);
+    if (warning) {
+        console.error(chalk.yellow(warning));
+    }
+    return config;
+}
+/**
+ * Load global and local configs and merge them.
+ * Priority: local > global.
+ */
+export function loadMergedConfig() {
+    // Use the core version directly — it calls coreLoadJsonConfig internally
+    // and doesn't produce warnings the CLI needs to display at this level.
+    return coreLoadMergedConfig();
+}
+/**
+ * Save config to disk. If a local config exists, saves there; otherwise global.
+ */
+export function saveConfig(config) {
+    coreSaveConfig(config);
+}
+/**
+ * Save config to a specific path.
+ * Logs errors to console with chalk.
+ */
+export function writeConfigToPath(config, targetFile) {
+    try {
+        coreWriteConfigToPath(config, targetFile);
+    }
+    catch (e) {
+        console.error(chalk.red(`Failed to save config: ${e.message}`));
+    }
+}

package/dist/adapters/cli/docker-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Zoe CLI — Docker & Non-Interactive Detection
+ *
+ * Utilities for detecting Docker environments and non-interactive TTY contexts.
+ * Used to guard inquirer prompts and readline settings.
+ */
+/**
+ * Detect if the current process is running inside a Docker container.
+ * Checks:
+ *   1. /.dockerenv file existence
+ *   2. /proc/1/cgroup contains "docker" or "containerd"
+ *   3. ZOE_DOCKER env var is "true"
+ */
+export declare function isDockerContainer(): boolean;
+/**
+ * Determine if the CLI is running in a non-interactive context.
+ * Returns true if:
+ *   - stdin is not a TTY
+ *   - --no-interactive flag was passed (ZOE_NO_INTERACTIVE=true)
+ *   - Running inside Docker (unless ZOE_INTERACTIVE=true overrides it)
+ */
+export declare function isNonInteractive(): boolean;
+/**
+ * Check if all required provider API keys are available via environment variables
+ * or the provided config. If so, the setup wizard can be safely skipped.
+ *
+ * Environment variable mappings:
+ *   - openai: OPENAI_API_KEY
+ *   - openai-compatible: OPENAI_COMPAT_API_KEY
+ *   - anthropic: ANTHROPIC_API_KEY
+ *   - glm: GLM_API_KEY
+ *
+ * Also checks LLM_PROVIDER to know which one is needed.
+ */
+export declare function hasRequiredProviderEnv(config: {
+    models?: Record<string, any>;
+}): boolean;

package/dist/adapters/cli/docker-utils.js

@@ -0,0 +1,90 @@
+/**
+ * Zoe CLI — Docker & Non-Interactive Detection
+ *
+ * Utilities for detecting Docker environments and non-interactive TTY contexts.
+ * Used to guard inquirer prompts and readline settings.
+ */
+import * as fs from 'fs';
+/**
+ * Detect if the current process is running inside a Docker container.
+ * Checks:
+ *   1. /.dockerenv file existence
+ *   2. /proc/1/cgroup contains "docker" or "containerd"
+ *   3. ZOE_DOCKER env var is "true"
+ */
+export function isDockerContainer() {
+    // Explicit env var override (used by --docker flag too)
+    if (process.env.ZOE_DOCKER === 'true')
+        return true;
+    try {
+        if (fs.existsSync('/.dockerenv'))
+            return true;
+    }
+    catch {
+        // Filesystem access may fail in restricted environments
+    }
+    try {
+        const cgroup = fs.readFileSync('/proc/1/cgroup', 'utf-8');
+        if (cgroup.includes('docker') || cgroup.includes('containerd'))
+            return true;
+    }
+    catch {
+        // /proc may not exist on non-Linux systems
+    }
+    return false;
+}
+/**
+ * Determine if the CLI is running in a non-interactive context.
+ * Returns true if:
+ *   - stdin is not a TTY
+ *   - --no-interactive flag was passed (ZOE_NO_INTERACTIVE=true)
+ *   - Running inside Docker (unless ZOE_INTERACTIVE=true overrides it)
+ */
+export function isNonInteractive() {
+    // Explicit opt-in to interactive mode overrides everything
+    if (process.env.ZOE_INTERACTIVE === 'true')
+        return false;
+    // Explicit non-interactive flag
+    if (process.env.ZOE_NO_INTERACTIVE === 'true')
+        return true;
+    // No TTY detected
+    if (!process.stdin.isTTY)
+        return true;
+    // Running in Docker without explicit interactive override
+    if (isDockerContainer())
+        return true;
+    return false;
+}
+/**
+ * Check if all required provider API keys are available via environment variables
+ * or the provided config. If so, the setup wizard can be safely skipped.
+ *
+ * Environment variable mappings:
+ *   - openai: OPENAI_API_KEY
+ *   - openai-compatible: OPENAI_COMPAT_API_KEY
+ *   - anthropic: ANTHROPIC_API_KEY
+ *   - glm: GLM_API_KEY
+ *
+ * Also checks LLM_PROVIDER to know which one is needed.
+ */
+export function hasRequiredProviderEnv(config) {
+    const provider = process.env.LLM_PROVIDER || config.models && Object.keys(config.models).find(k => config.models[k]?.apiKey);
+    if (!provider) {
+        return !!(process.env.OPENAI_API_KEY ||
+            process.env.OPENAI_COMPAT_API_KEY ||
+            process.env.ANTHROPIC_API_KEY ||
+            process.env.GLM_API_KEY);
+    }
+    switch (provider) {
+        case 'openai':
+            return !!(process.env.OPENAI_API_KEY || config.models?.[provider]?.apiKey);
+        case 'openai-compatible':
+            return !!(process.env.OPENAI_COMPAT_API_KEY || config.models?.[provider]?.apiKey);
+        case 'anthropic':
+            return !!(process.env.ANTHROPIC_API_KEY || config.models?.[provider]?.apiKey);
+        case 'glm':
+            return !!(process.env.GLM_API_KEY || config.models?.[provider]?.apiKey);
+        default:
+            return !!(config.models?.[provider]?.apiKey);
+    }
+}

package/dist/adapters/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/adapters/cli/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import dotenv from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { isNonInteractive } from './docker-utils.js';
+import { runSetup } from './setup.js';
+import { runChat } from './repl.js';
+import { resolveLaunchMode } from './system-prompts.js';
+// Handle Ctrl+C gracefully
+function handleExit() {
+    console.log(chalk.cyan("\n\nGoodbye! (Interrupted)"));
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+    }
+    process.stdin.pause();
+    process.exit(0);
+}
+process.on('SIGINT', handleExit);
+process.on('SIGTERM', handleExit);
+// Load local env vars (lowest priority of env vars, but env vars override JSON)
+dotenv.config();
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = path.join(__dirname, '..', 'package.json');
+let version = '0.2.2';
+try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    version = pkg.version;
+}
+catch (e) {
+    // Fallback if package.json not found in expected location
+}
+const program = new Command();
+program
+    .name('zoe')
+    .description('A lightweight AI agent CLI tool')
+    .version(version)
+    .option('-m, --model <model>', 'Model to use')
+    .option('-p, --provider <provider>', 'Provider to use (openai-compatible|openai|anthropic|glm)')
+    .option('-n, --no-interactive', 'Exit after processing the initial query (Headless mode)')
+    .option('--docker', 'Docker mode: implies --no-interactive, disables all prompts, uses env vars and config only')
+    .option('-y, --yes', 'Auto-confirm all tool executions (e.g., shell commands)')
+    .option('--headless', 'Bypass permission matrix: auto-approve all tools (for CI/Docker/scripts)')
+    .option('--strict', 'Permission level: auto-approve safe tools only')
+    .option('--moderate', 'Permission level: auto-approve safe + edit + communications (default)')
+    .option('--yolo', 'Permission level: auto-approve all tools')
+    .option('-r, --resume <id>', 'Resume a previous session by id (or "last")');
+program
+    .command('setup')
+    .description('Run the interactive setup wizard to configure API keys')
+    .option('-p, --project', 'Save configuration to project-level (.zoe/setting.json)')
+    .action(async (options) => {
+    // Setup wizard cannot run in non-interactive mode
+    if (isNonInteractive()) {
+        console.log(chalk.yellow('Setup wizard requires an interactive terminal.'));
+        console.log(chalk.dim('Set API keys via environment variables instead:'));
+        console.log(chalk.dim('  OPENAI_API_KEY, ANTHROPIC_API_KEY, GLM_API_KEY'));
+        console.log(chalk.dim('  LLM_PROVIDER (openai-compatible|openai|anthropic|glm)'));
+        console.log(chalk.dim('Or mount a config file at ~/.zoe/setting.json'));
+        process.exit(1);
+    }
+    await runSetup(options);
+});
+program
+    .command('chat [query...]', { isDefault: true })
+    .description('Start the AI agent (default)')
+    .action(async (queryParts) => {
+    const options = program.opts();
+    // Dispatch on the SAME predicate that selects the system prompt, so launch
+    // mode and UI mode can never diverge (FR-001). The TUI is lazy-imported
+    // only in interactive mode; headless / piped / --docker never load React.
+    if (resolveLaunchMode(options) === 'interactive') {
+        const { startTui } = await import('./tui/index.js');
+        await startTui({ queryParts, options });
+    }
+    else {
+        await runChat(queryParts, options);
+    }
+});
+// Apply --docker flag effects early from raw argv (before Commander parses)
+// This ensures isNonInteractive() works correctly during the parse phase
+if (process.argv.includes('--docker')) {
+    process.env.ZOE_DOCKER = 'true';
+    process.env.ZOE_NO_INTERACTIVE = 'true';
+}
+program.parse(process.argv);

package/dist/adapters/cli/repl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zoe CLI — REPL Functions
+ *
+ * Interrupt handling, chat-with-interrupt, and the main runChat loop.
+ * Extracted from index.ts for single-responsibility.
+ */
+import { Agent } from './agent.js';
+import type { ApproveToolFn, PermissionLevel } from '../../core/types.js';
+export interface InterruptHandle {
+    signal: AbortSignal;
+    /** Temporarily disable ESC detection (e.g. during approval prompts) */
+    suspend: () => void;
+    /** Re-enable ESC detection after suspend */
+    resume: () => void;
+    /** Permanently clean up the interrupt handler */
+    teardown: () => void;
+}
+export declare function setupInterrupt(agent: Agent): InterruptHandle;
+/** Build the adapter-level approveTool callback for the CLI. */
+export declare function createCliApproveTool(config: any, handle: InterruptHandle, permissionLevel?: PermissionLevel): ApproveToolFn;
+export declare function chatWithInterrupt(agent: Agent, input: string, config?: any, permissionLevel?: PermissionLevel): Promise<void>;
+export declare function runChat(queryParts: string[], options: any): Promise<void>;

package/dist/adapters/cli/repl.js

@@ -0,0 +1,256 @@
+/**
+ * Zoe CLI — REPL Functions
+ *
+ * Interrupt handling, chat-with-interrupt, and the main runChat loop.
+ * Extracted from index.ts for single-responsibility.
+ */
+import chalk from 'chalk';
+import * as readline from 'node:readline/promises';
+import inquirer from 'inquirer';
+import { bootstrapCliSession } from './bootstrap.js';
+import { buildCommandRegistry } from './commands/build-registry.js';
+export function setupInterrupt(agent) {
+    const signal = agent.createAbortSignal();
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        return {
+            signal,
+            suspend: () => { },
+            resume: () => { },
+            teardown: () => agent.clearAbortController(),
+        };
+    }
+    const ESC = '\x1b';
+    let wasRaw = stdin.isRaw;
+    const onData = (data) => {
+        if (data[0] === ESC.charCodeAt(0)) {
+            agent.abort();
+        }
+    };
+    // Start ESC detection
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', onData);
+    return {
+        signal,
+        suspend: () => {
+            stdin.removeListener('data', onData);
+            if (stdin.isRaw)
+                stdin.setRawMode(false);
+        },
+        resume: () => {
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onData);
+        },
+        teardown: () => {
+            stdin.removeListener('data', onData);
+            if (!wasRaw && stdin.isRaw) {
+                stdin.setRawMode(false);
+            }
+            agent.clearAbortController();
+        },
+    };
+}
+// ── Shell approval mode ──────────────────────────────────────────────
+function getShellApprovalMode(config, newPermissionSystemActive) {
+    if (config?.autoConfirm)
+        return 'auto';
+    // When the new permission system is active, ignore the legacy ZOE_SHELL_APPROVE env var
+    // so it cannot bypass the permission matrix.
+    if (!newPermissionSystemActive) {
+        const envMode = process.env.ZOE_SHELL_APPROVE;
+        if (envMode === 'auto' || envMode === 'true' || envMode === '1')
+            return 'auto';
+        if (envMode === 'deny' || envMode === 'false' || envMode === '0')
+            return 'deny';
+    }
+    if (process.stdin.isTTY)
+        return 'prompt';
+    return 'deny';
+}
+/** Build the adapter-level approveTool callback for the CLI. */
+export function createCliApproveTool(config, handle, permissionLevel) {
+    // New permission system is active when an explicit permission level was resolved
+    const newPermissionSystemActive = permissionLevel !== undefined;
+    return async (call) => {
+        // Display what the tool wants to do
+        if (call.name === 'execute_shell_command') {
+            const cmd = typeof call.args.command === 'string' ? call.args.command : JSON.stringify(call.args.command);
+            const rationale = typeof call.args.rationale === 'string' ? call.args.rationale : '';
+            console.log(chalk.yellow(`\nAI wants to execute: `) + chalk.bold(cmd));
+            if (rationale)
+                console.log(chalk.dim(`Reason: ${rationale}`));
+        }
+        else {
+            console.log(chalk.yellow(`\nAI wants to use tool: `) + chalk.bold(call.name));
+        }
+        const mode = getShellApprovalMode(config, newPermissionSystemActive);
+        if (mode === 'deny') {
+            console.log(chalk.red('Command denied (non-interactive mode).'));
+            console.log(chalk.dim('Set ZOE_SHELL_APPROVE=auto to auto-approve, or use --yes flag.'));
+            return false;
+        }
+        if (mode === 'prompt') {
+            // Suspend ESC handler so inquirer can use stdin normally
+            handle.suspend();
+            try {
+                const { confirm } = await inquirer.prompt([
+                    {
+                        type: 'confirm',
+                        name: 'confirm',
+                        message: 'Do you want to run this command?',
+                        default: false,
+                    },
+                ]);
+                return confirm;
+            }
+            catch {
+                // Prompt cancelled (Ctrl+C or inquirer error)
+                return false;
+            }
+            finally {
+                handle.resume();
+            }
+        }
+        // Auto-approved
+        console.log(chalk.gray(`(Auto-approved: ${config?.autoConfirm ? '--yes flag' : 'ZOE_SHELL_APPROVE=auto'})`));
+        return true;
+    };
+}
+export async function chatWithInterrupt(agent, input, config, permissionLevel) {
+    const handle = setupInterrupt(agent);
+    const approveTool = config ? createCliApproveTool(config, handle, permissionLevel) : undefined;
+    try {
+        await agent.chat(input, handle.signal, approveTool, permissionLevel);
+    }
+    finally {
+        handle.teardown();
+    }
+}
+// ── Main chat runner ─────────────────────────────────────────────────
+export async function runChat(queryParts, options) {
+    if (options.interactive) {
+        console.log(chalk.bold.cyan("Welcome to Zoe Agent CLI"));
+    }
+    const initialQuery = queryParts.join(' ');
+    const ctx = await bootstrapCliSession(options);
+    const { agent, fullConfig, activeProviderType, providerConfig, permissionLevel, gatewayInstance } = ctx;
+    if (options.interactive) {
+        console.log(chalk.green(`Agent initialized with ${activeProviderType} (${providerConfig.model})`));
+        console.log(chalk.gray("Type /help for commands, /exit to leave."));
+    }
+    // @path resolver — hoisted so the initial query resolves at the caller,
+    // not inside Agent.chat() (T022). The resolver is idempotent.
+    const { resolveReferences } = await import('../../skills/resolver.js');
+    // Handle initial query if present
+    if (initialQuery) {
+        if (options.interactive) {
+            console.log(chalk.blue("\nProcessing initial request: ") + chalk.bold(initialQuery));
+        }
+        let resolvedInitial = initialQuery;
+        if (initialQuery.includes('@')) {
+            try {
+                resolvedInitial = await resolveReferences(initialQuery);
+            }
+            catch { /* resolver not available */ }
+        }
+        await chatWithInterrupt(agent, resolvedInitial, fullConfig, permissionLevel);
+        // Headless mode exit
+        if (!options.interactive) {
+            process.exit(0);
+        }
+    }
+    // Main chat loop
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdin.isTTY === true
+    });
+    // Build command registry
+    const cmdRegistry = buildCommandRegistry(agent, fullConfig, activeProviderType, gatewayInstance);
+    // Lazy-loaded modules (hoisted outside the loop to avoid repeated import overhead)
+    const { invokeSkill, createSkillProviderSwitcher } = await import('../../core/skill-invoker.js');
+    try {
+        while (true) {
+            const userInput = await rl.question(chalk.green('?') + ' You > ');
+            // Bare exit/quit (without /)
+            if (userInput.toLowerCase() === 'exit' || userInput.toLowerCase() === 'quit') {
+                console.log(chalk.cyan('Goodbye!'));
+                break;
+            }
+            if (userInput.trim() === '')
+                continue;
+            // Slash commands — dispatch through registry
+            if (userInput.startsWith('/')) {
+                rl.pause();
+                try {
+                    const { status, output } = await cmdRegistry.dispatch(userInput, { agent, args: '', config: fullConfig }, agent.getSkillRegistry());
+                    if (output)
+                        console.log(output);
+                    if (status === 'exit')
+                        break;
+                    if (status === 'handled')
+                        continue;
+                    // 'fallthrough' — try skill invocation
+                    const skillResult = await invokeSkill({ input: userInput, registry: agent.getSkillRegistry() });
+                    if (skillResult) {
+                        console.log(chalk.cyan(`Loading skill: ${skillResult.skill.name}`));
+                        const switcher = createSkillProviderSwitcher({
+                            provider: agent.getProvider(),
+                            model: agent.getModel(),
+                            models: fullConfig.models ?? {},
+                        });
+                        const switched = await switcher.switchIfNeeded(skillResult);
+                        if (switched) {
+                            agent.switchProvider(switcher.activeProvider, switcher.activeModel);
+                        }
+                        try {
+                            await chatWithInterrupt(agent, skillResult.prompt, fullConfig, permissionLevel);
+                        }
+                        finally {
+                            if (switched) {
+                                switcher.restore();
+                                agent.switchProvider(switcher.activeProvider, switcher.activeModel);
+                            }
+                        }
+                        continue;
+                    }
+                    // No matching command or skill
+                    console.log(chalk.yellow(`Unknown command: ${userInput.split(' ')[0]}`));
+                    console.log(chalk.dim('Type /help for available commands.'));
+                }
+                finally {
+                    rl.resume();
+                }
+                continue;
+            }
+            // Resolve @path file references in user input
+            let resolvedInput = userInput;
+            if (userInput.includes('@')) {
+                try {
+                    resolvedInput = await resolveReferences(userInput);
+                }
+                catch { /* resolver not available, use raw input */ }
+            }
+            rl.pause();
+            try {
+                await chatWithInterrupt(agent, resolvedInput, fullConfig, permissionLevel);
+            }
+            finally {
+                rl.resume();
+            }
+        }
+    }
+    catch (err) {
+        if (err.message && (err.message.includes('User force closed') || err.message.includes('Prompt was canceled'))) {
+            console.log(chalk.cyan("\nGoodbye!"));
+        }
+        else {
+            console.error(chalk.red("Error in chat loop:"), err);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/adapters/cli/setup.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zoe CLI — Setup Wizard
+ *
+ * Interactive setup wizard for configuring API keys and providers.
+ * Extracted from index.ts for separation of concerns.
+ */
+import { ProviderType } from '../../providers/types.js';
+import { Agent } from './agent.js';
+import { type AppConfig } from './config-loader.js';
+/**
+ * Run the interactive setup wizard.
+ * @param options.project - If true, save to project-level config instead of global.
+ */
+export declare function runSetup(options?: any): Promise<void>;
+/**
+ * Handle the /models interactive command.
+ * Allows switching, editing, adding, and removing providers at runtime.
+ */
+export declare function handleModelsCommand(agent: Agent, config: AppConfig, activeProvider: ProviderType): Promise<ProviderType>;