zoe-agent 0.3.1

package/dist/adapters/cli/commands/compact.js

@@ -0,0 +1,96 @@
+/**
+ * /compact command handler for Zoe CLI.
+ *
+ * Summarizes the conversation to reduce token usage while preserving
+ * key context needed to continue the session.
+ *
+ * Aliases: /compress
+ *
+ * Uses an `ora` spinner (stdout), so it is marked `interactive` and the TUI
+ * defers it — run it in the readline REPL.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { runAgentLoop } from '../../../core/agent-loop.js';
+import { generateId, now } from '../../../core/message-convert.js';
+import { createHookExecutor } from '../../../core/hooks.js';
+import { buildSystemPrompt } from '../system-prompts.js';
+export const compactHandler = async (ctx) => {
+    const { agent, args } = ctx;
+    const spinner = ora('Compacting...').start();
+    try {
+        const allMessages = agent.getMessages();
+        // Separate system prompt from conversation messages
+        const systemMessage = allMessages.find((m) => m.role === 'system');
+        const conversationMessages = allMessages.filter((m) => m.role !== 'system');
+        if (conversationMessages.length === 0) {
+            return { output: chalk.yellow('Nothing to compact — conversation is empty.') };
+        }
+        // Build the summarization instruction
+        const focusHint = args.trim();
+        const summaryInstruction = `Summarize this conversation concisely. Preserve key decisions, code changes, and context needed to continue.${focusHint ? ` ${focusHint}` : ''}`;
+        // Create a temporary messages array for the summarization call
+        const summaryMessages = [
+            {
+                id: generateId(),
+                role: 'system',
+                content: summaryInstruction,
+                timestamp: now(),
+            },
+            // Flatten all non-system messages into a single user message for context
+            {
+                id: generateId(),
+                role: 'user',
+                content: conversationMessages
+                    .map((m) => `[${m.role}]: ${m.content}`)
+                    .join('\n\n'),
+                timestamp: now(),
+            },
+        ];
+        let result;
+        try {
+            result = await runAgentLoop({
+                provider: agent.getProvider(),
+                model: agent.getModel(),
+                messages: summaryMessages,
+                toolDefs: [], // no tools during summarization
+                maxSteps: 1,
+                hooks: createHookExecutor(),
+            });
+        }
+        catch (error) {
+            return { output: chalk.red(`Compaction failed: ${error.message}`) };
+        }
+        if (result.error) {
+            return { output: chalk.red(`Compaction failed: ${result.error.message}`) };
+        }
+        // Extract the summary text from the result messages
+        const assistantMessage = result.messages.find((m) => m.role === 'assistant');
+        const summaryText = assistantMessage?.content ?? 'Conversation history was compacted.';
+        // Replace agent messages: [system_prompt, summary]
+        const newMessages = systemMessage
+            ? [systemMessage]
+            : [
+                {
+                    id: generateId(),
+                    role: 'system',
+                    content: buildSystemPrompt(),
+                    timestamp: now(),
+                },
+            ];
+        newMessages.push({
+            id: generateId(),
+            role: 'assistant',
+            content: `[Conversation Summary]\n${summaryText}`,
+            timestamp: now(),
+        });
+        agent.setMessages(newMessages);
+        return { output: chalk.green('Conversation compacted. Token usage reduced.') };
+    }
+    catch (error) {
+        return { output: chalk.red(`Compaction error: ${error.message}`) };
+    }
+    finally {
+        spinner.stop();
+    }
+};

package/dist/adapters/cli/commands/exit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * /exit command handler for Zoe CLI.
+ *
+ * Aliases: /quit
+ */
+import type { CommandHandler } from './registry.js';
+export declare const exitHandler: CommandHandler;

package/dist/adapters/cli/commands/exit.js

@@ -0,0 +1,9 @@
+/**
+ * /exit command handler for Zoe CLI.
+ *
+ * Aliases: /quit
+ */
+import chalk from 'chalk';
+export const exitHandler = async () => {
+    return { exit: true, output: chalk.cyan('Goodbye!') };
+};

package/dist/adapters/cli/commands/gateway.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zoe CLI — /gateway slash command
+ *
+ * Full management commands for the gateway subsystem.
+ * Receives the MCPGateway instance from the REPL when gateway is enabled.
+ */
+export declare function createGatewayCommandHandler(gatewayInstance: any): (args: string) => Promise<string>;

package/dist/adapters/cli/commands/gateway.js

@@ -0,0 +1,152 @@
+/**
+ * Zoe CLI — /gateway slash command
+ *
+ * Full management commands for the gateway subsystem.
+ * Receives the MCPGateway instance from the REPL when gateway is enabled.
+ */
+import chalk from 'chalk';
+export function createGatewayCommandHandler(gatewayInstance) {
+    return async (args) => {
+        if (!gatewayInstance) {
+            return chalk.yellow('Gateway is not enabled. Set gateway.enabled=true in settings and restart.');
+        }
+        const parts = args.trim().split(/\s+/);
+        const subcommand = parts[0] ?? 'help';
+        switch (subcommand) {
+            case 'help':
+                return [
+                    'Gateway management commands:',
+                    '  /gateway list              - List all targets and their status',
+                    '  /gateway add <name> <json> - Register a new target (JSON config)',
+                    '  /gateway remove <name>     - Unregister a target',
+                    '  /gateway toggle <name>     - Toggle a target on/off',
+                    '  /gateway routes            - List routing rules',
+                    '  /gateway routes add <pattern> <target> [priority] - Add route',
+                    '  /gateway routes remove <pattern> <target> - Remove route',
+                    '  /gateway credentials       - List credential keys',
+                    '  /gateway credentials set <key> <value> - Set a credential',
+                    '  /gateway audit [target] [limit] - View audit logs',
+                    '  /gateway usage             - Show usage stats',
+                ].join('\n');
+            case 'list': {
+                const targets = gatewayInstance.getTargets();
+                const entries = Object.entries(targets);
+                if (entries.length === 0)
+                    return 'No gateway targets registered.';
+                return entries.map(([name, t]) => {
+                    const status = t.enabled ? chalk.green('enabled') : chalk.red('disabled');
+                    if (t.kind === 'mcp') {
+                        const tools = t.capabilities?.tools?.length ?? 0;
+                        return `  ${name} (${status}, MCP/${t.transport}): ${tools} tools — ${t.description}`;
+                    }
+                    return `  ${name} (${status}, REST ${t.baseUrl}): ${t.operations.length} ops — ${t.description}`;
+                }).join('\n');
+            }
+            case 'add': {
+                const name = parts[1];
+                const jsonStr = parts.slice(2).join(' ');
+                if (!name || !jsonStr)
+                    return 'Usage: /gateway add <name> <json-config>';
+                let target;
+                try {
+                    target = JSON.parse(jsonStr);
+                }
+                catch {
+                    return 'Error: Invalid JSON configuration.';
+                }
+                if (!['mcp', 'rest'].includes(target.kind)) {
+                    return 'Error: config.kind must be "mcp" or "rest".';
+                }
+                target.enabled = true;
+                try {
+                    await gatewayInstance.registerTarget(name, target, true);
+                    return `Target "${name}" registered.`;
+                }
+                catch (e) {
+                    return `Error: ${e.message}`;
+                }
+            }
+            case 'remove': {
+                const name = parts[1];
+                if (!name)
+                    return 'Usage: /gateway remove <name>';
+                const ok = await gatewayInstance.unregisterTarget(name);
+                return ok ? `Target "${name}" removed.` : `Target "${name}" not found.`;
+            }
+            case 'toggle': {
+                const name = parts[1];
+                if (!name)
+                    return 'Usage: /gateway toggle <name>';
+                const targets = gatewayInstance.getTargets();
+                const current = targets[name];
+                if (!current)
+                    return `Target "${name}" not found.`;
+                const newState = !current.enabled;
+                const ok = await gatewayInstance.toggleTarget(name, newState);
+                return ok ? `Target "${name}" ${newState ? 'enabled' : 'disabled'}.` : `Failed to toggle "${name}".`;
+            }
+            case 'routes': {
+                const routesSub = parts[1];
+                if (routesSub === 'add') {
+                    const pattern = parts[2];
+                    const target = parts[3];
+                    const priority = parseInt(parts[4] ?? '0', 10);
+                    if (!pattern || !target)
+                        return 'Usage: /gateway routes add <pattern> <target> [priority]';
+                    await gatewayInstance.addRoute(pattern, target, priority);
+                    return `Route added: "${pattern}" -> ${target} (priority ${priority}).`;
+                }
+                if (routesSub === 'remove') {
+                    const pattern = parts[2];
+                    const target = parts[3];
+                    if (!pattern || !target)
+                        return 'Usage: /gateway routes remove <pattern> <target>';
+                    await gatewayInstance.removeRoute(pattern, target);
+                    return `Route removed: "${pattern}" -> ${target}.`;
+                }
+                // List routes
+                const routes = gatewayInstance.getRoutes();
+                if (routes.length === 0)
+                    return 'No routing rules configured.';
+                return routes.map((r) => `  "${r.pattern}" -> ${r.target} (priority ${r.priority})`).join('\n');
+            }
+            case 'credentials': {
+                const credSub = parts[1];
+                if (credSub === 'set') {
+                    const key = parts[2];
+                    const value = parts.slice(3).join(' ');
+                    if (!key || !value)
+                        return 'Usage: /gateway credentials set <key> <value>';
+                    await gatewayInstance.setCredential(key, value);
+                    return `Credential "${key}" set.`;
+                }
+                // List credential keys
+                const keys = gatewayInstance.listCredentialKeys();
+                if (keys.length === 0)
+                    return 'No credentials stored.';
+                return `Stored credential keys:\n  ${keys.join('\n  ')}`;
+            }
+            case 'audit': {
+                const targetFilter = parts[1];
+                const limit = parseInt(parts[2] ?? '10', 10);
+                const logs = gatewayInstance.getAuditLogs(targetFilter && !targetFilter.match(/^\d+$/) ? targetFilter : undefined, limit);
+                if (logs.length === 0)
+                    return 'No audit logs found.';
+                return logs.map((l) => {
+                    const ts = new Date(l.timestamp).toISOString();
+                    const status = l.success ? 'OK' : 'FAIL';
+                    return `  [${ts}] ${l.agent} -> ${l.target} ${l.operation} (${status}, ${l.durationMs}ms)`;
+                }).join('\n');
+            }
+            case 'usage': {
+                const summary = gatewayInstance.getUsageSummary();
+                const entries = Object.entries(summary);
+                if (entries.length === 0)
+                    return 'No gateway usage recorded.';
+                return entries.map(([name, stats]) => `  ${name}: ${stats.calls} calls, ${stats.errors} errors`).join('\n');
+            }
+            default:
+                return `Unknown gateway subcommand: ${subcommand}. Type /gateway help for available commands.`;
+        }
+    };
+}

package/dist/adapters/cli/commands/help.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `/help` slash command handler.
+ *
+ * Displays available commands and loaded skills.
+ * Use `--all` to include hidden commands and aliases.
+ */
+import type { CommandHandler, CommandRegistry } from './registry.js';
+import type { SkillRegistry } from '../../../skills/types.js';
+export declare function createHelpHandler(registry: CommandRegistry, skillRegistry?: SkillRegistry | null): CommandHandler;

package/dist/adapters/cli/commands/help.js

@@ -0,0 +1,12 @@
+/**
+ * `/help` slash command handler.
+ *
+ * Displays available commands and loaded skills.
+ * Use `--all` to include hidden commands and aliases.
+ */
+export function createHelpHandler(registry, skillRegistry) {
+    return async (ctx) => {
+        const showAll = ctx.args.trim() === '--all';
+        return { output: registry.help(showAll, skillRegistry ?? ctx.agent.getSkillRegistry()) };
+    };
+}

package/dist/adapters/cli/commands/models.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Zoe CLI — /models Command Handler
+ *
+ * In non-interactive mode, lists configured providers (returns output).
+ * In interactive mode, launches the provider/model wizard (owns stdin) — the
+ * TUI defers this command.
+ */
+import { Agent } from '../agent.js';
+import type { CommandHandler } from './registry.js';
+export declare function modelsHandler(agent: Agent, config: any, activeProviderType: string): CommandHandler;

package/dist/adapters/cli/commands/models.js

@@ -0,0 +1,32 @@
+/**
+ * Zoe CLI — /models Command Handler
+ *
+ * In non-interactive mode, lists configured providers (returns output).
+ * In interactive mode, launches the provider/model wizard (owns stdin) — the
+ * TUI defers this command.
+ */
+import chalk from 'chalk';
+import { handleModelsCommand } from '../setup.js';
+import { isNonInteractive } from '../docker-utils.js';
+export function modelsHandler(agent, config, activeProviderType) {
+    const handler = async () => {
+        if (isNonInteractive()) {
+            const configured = Object.keys(config.models || {}).filter((k) => config.models?.[k]?.apiKey);
+            if (configured.length === 0) {
+                return { output: chalk.yellow('No providers configured. Set API key env vars to add providers.') };
+            }
+            const lines = [chalk.bold.cyan('Configured Providers:')];
+            for (const p of configured) {
+                const model = config.models?.[p]?.model || 'unknown';
+                const marker = p === activeProviderType ? chalk.green(' (active)') : '';
+                lines.push(`  ${p} (${model})${marker}`);
+            }
+            lines.push(chalk.dim('\nUse --provider <name> flag or LLM_PROVIDER env var to switch.'));
+            return { output: lines.join('\n') };
+        }
+        // Interactive wizard — owns stdout/stdin; the TUI defers this command.
+        await handleModelsCommand(agent, config, activeProviderType);
+        return {};
+    };
+    return handler;
+}

package/dist/adapters/cli/commands/registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Slash Command Registry for Zoe CLI.
+ *
+ * Flat namespace of `/command` handlers with alias support.
+ *
+ * Consistent contract: every handler returns a `CommandResult` describing what
+ * to render (`output`) and whether to terminate (`exit`). Handlers never write
+ * to stdout directly — the adapter renders the result (readline prints it; the
+ * TUI appends it to the feed). Lookup order: exact match → alias → skill
+ * invocation → unknown.
+ *
+ * `interactive` marks handlers that take over stdin/stdout themselves (inquirer
+ * wizards, ora spinners). They keep working in the readline REPL but cannot run
+ * under the TUI's stdin ownership — the TUI defers them.
+ */
+import type { Agent } from '../agent.js';
+import type { SkillRegistry } from '../../../skills/types.js';
+export interface CommandContext {
+    agent: Agent;
+    args: string;
+    config: any;
+}
+/**
+ * A handler's outcome. `output` is the text the adapter renders (undefined if
+ * the handler produced none). `exit` signals the session should terminate.
+ */
+export interface CommandResult {
+    output?: string;
+    exit?: boolean;
+}
+export type CommandHandler = (ctx: CommandContext) => Promise<CommandResult>;
+export interface CommandEntry {
+    name: string;
+    handler: CommandHandler;
+    description: string;
+    aliases: string[];
+    hidden?: boolean;
+    /** Handler owns stdin/stdout (inquirer/ora) — TUI-deferred, readline-only. */
+    interactive?: boolean;
+}
+export type DispatchStatus = 'handled' | 'fallthrough' | 'exit';
+export interface DispatchResult {
+    status: DispatchStatus;
+    output?: string;
+}
+export declare class CommandRegistry {
+    private commands;
+    private aliasMap;
+    register(name: string, handler: CommandHandler, options: {
+        description: string;
+        aliases?: string[];
+        hidden?: boolean;
+        interactive?: boolean;
+    }): void;
+    /** Resolve a raw input string to its command entry (exact or alias), or null. */
+    resolveCommand(input: string): CommandEntry | null;
+    /**
+     * Dispatch a raw user input string. Handlers return their output; the caller
+     * renders it. Returns `fallthrough` for non-commands and unmatched skills.
+     */
+    dispatch(input: string, ctx: CommandContext, skillRegistry: SkillRegistry | null): Promise<DispatchResult>;
+    /**
+     * Generate help text.
+     * @param showAll If true, include hidden commands and aliases.
+     * @param skillRegistry If provided, list loaded skills.
+     */
+    help(showAll?: boolean, skillRegistry?: SkillRegistry | null): string;
+    /** Get all registered command entries. */
+    getAll(): CommandEntry[];
+}

package/dist/adapters/cli/commands/registry.js

@@ -0,0 +1,111 @@
+/**
+ * Slash Command Registry for Zoe CLI.
+ *
+ * Flat namespace of `/command` handlers with alias support.
+ *
+ * Consistent contract: every handler returns a `CommandResult` describing what
+ * to render (`output`) and whether to terminate (`exit`). Handlers never write
+ * to stdout directly — the adapter renders the result (readline prints it; the
+ * TUI appends it to the feed). Lookup order: exact match → alias → skill
+ * invocation → unknown.
+ *
+ * `interactive` marks handlers that take over stdin/stdout themselves (inquirer
+ * wizards, ora spinners). They keep working in the readline REPL but cannot run
+ * under the TUI's stdin ownership — the TUI defers them.
+ */
+import chalk from 'chalk';
+// ── Registry ───────────────────────────────────────────────────────────
+export class CommandRegistry {
+    commands = new Map();
+    aliasMap = new Map(); // alias → canonical name
+    register(name, handler, options) {
+        const entry = {
+            name,
+            handler,
+            description: options.description,
+            aliases: options.aliases ?? [],
+            hidden: options.hidden,
+            interactive: options.interactive,
+        };
+        this.commands.set(name, entry);
+        for (const alias of entry.aliases) {
+            this.aliasMap.set(alias, name);
+        }
+    }
+    /** Resolve a raw input string to its command entry (exact or alias), or null. */
+    resolveCommand(input) {
+        const trimmed = input.trim();
+        if (!trimmed.startsWith('/'))
+            return null;
+        const withoutSlash = trimmed.slice(1);
+        const spaceIdx = withoutSlash.indexOf(' ');
+        const cmdName = (spaceIdx === -1 ? withoutSlash : withoutSlash.slice(0, spaceIdx)).toLowerCase();
+        return this.commands.get(cmdName) ?? this.commands.get(this.aliasMap.get(cmdName) ?? '') ?? null;
+    }
+    /**
+     * Dispatch a raw user input string. Handlers return their output; the caller
+     * renders it. Returns `fallthrough` for non-commands and unmatched skills.
+     */
+    async dispatch(input, ctx, skillRegistry) {
+        const entry = this.resolveCommand(input);
+        if (entry) {
+            const withoutSlash = input.trim().slice(1);
+            const spaceIdx = withoutSlash.indexOf(' ');
+            const args = spaceIdx === -1 ? '' : withoutSlash.slice(spaceIdx + 1);
+            const result = await entry.handler({ ...ctx, args });
+            return { status: result.exit ? 'exit' : 'handled', output: result.output };
+        }
+        // Skill invocation — delegate to caller (skill name with no matching command)
+        const trimmed = input.trim();
+        if (trimmed.startsWith('/')) {
+            const cmdName = trimmed.slice(1).split(/\s+/)[0]?.toLowerCase() ?? '';
+            if (skillRegistry && cmdName.length > 1) {
+                return { status: 'fallthrough' };
+            }
+        }
+        // Unknown command
+        const unknownName = trimmed.slice(1).split(/\s+/)[0] ?? '';
+        return {
+            status: 'handled',
+            output: `${chalk.yellow(`Unknown command: ${unknownName}`)}\n${chalk.dim('Type /help for available commands.')}`,
+        };
+    }
+    /**
+     * Generate help text.
+     * @param showAll If true, include hidden commands and aliases.
+     * @param skillRegistry If provided, list loaded skills.
+     */
+    help(showAll, skillRegistry) {
+        const lines = [];
+        lines.push(chalk.bold.cyan('Available Commands:'));
+        lines.push('');
+        for (const entry of this.commands.values()) {
+            if (entry.hidden && !showAll)
+                continue;
+            const aliasStr = entry.aliases.length > 0
+                ? chalk.dim(` (${entry.aliases.join(', ')})`)
+                : '';
+            lines.push(`  ${chalk.green(`/${entry.name}`)}${aliasStr}  — ${entry.description}`);
+        }
+        if (skillRegistry && skillRegistry.getAll().length > 0) {
+            lines.push('');
+            lines.push(chalk.bold.cyan('Loaded Skills:'));
+            lines.push(chalk.dim('  Use /<skill-name> [args] to invoke'));
+            for (const s of skillRegistry.getAll()) {
+                const desc = s.description.split('\n')[0];
+                lines.push(`  ${chalk.green(`/${s.name}`)}  — ${desc}`);
+            }
+        }
+        if (!showAll) {
+            lines.push('');
+            lines.push(chalk.dim('Use /help --all to see aliases and hidden commands.'));
+        }
+        lines.push('');
+        lines.push(chalk.dim('Prefixes: @path (file injection)  !shell (shell passthrough)'));
+        return lines.join('\n');
+    }
+    /** Get all registered command entries. */
+    getAll() {
+        return [...this.commands.values()];
+    }
+}

package/dist/adapters/cli/commands/settings-utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Zoe CLI — Settings Display Utilities
+ *
+ * Pure formatting functions for settings display.
+ * Render functions produce bordered ASCII boxes for the wizard TUI.
+ */
+import { SettingsCategory } from '../../../core/settings-schema.js';
+import type { SettingsManager } from '../../../core/settings-manager.js';
+export declare function formatSettingValue(value: unknown, secret: boolean): string;
+export declare function maskValue(value: string): string;
+export declare function getOriginLabel(dotKey: string, projectConfig?: Record<string, any>, globalConfig?: Record<string, any>): string;
+export interface SettingRow {
+    dotKey: string;
+    value: string;
+    origin: string;
+    category: string;
+    restartRequired: boolean;
+}
+export declare function formatSettingTable(settings: SettingRow[]): string;
+/**
+ * Render the bordered header box for Level 1 (category menu).
+ * Shows current provider, model, permissions, and auto-confirm.
+ */
+export declare function renderWizardHeader(manager: SettingsManager): string;
+/**
+ * Render the aligned settings list for Level 2 (category drilldown).
+ * 3-column layout: label, value, origin.
+ */
+export declare function renderSettingsList(keys: string[], manager: SettingsManager): string;
+/**
+ * Render the bordered mini-form for Level 3 (setting edit).
+ * Shows setting name, current value, source, and type.
+ */
+export declare function renderSettingForm(dotKey: string, manager: SettingsManager): string;
+/**
+ * Render the category status label for the Level 1 menu.
+ */
+export declare function renderCategoryStatus(categoryKey: SettingsCategory, manager: SettingsManager): string;