ikie-cli 0.1.0

package/dist/agent.js

@@ -0,0 +1,634 @@
+import chalk from 'chalk';
+import { TOOL_DEFS, SAFE_TOOLS, formatToolArgs, executeTool } from './tools.js';
+import { renderMarkdown, extractThinkTags } from './renderer.js';
+import { c, toolLine, permissionPrompt, toolSuccessLine, toolErrorLine, InlineSpinner } from './theme.js';
+export function estimateTokens(chars) {
+    return Math.max(1, Math.round(chars / 4));
+}
+/**
+ * Safely restore previously-saved stdin listeners after a raw-mode interaction
+ * (permission prompt, ask_user, theme picker, agent turn).
+ *
+ * Re-adding 'keypress' listeners makes Node's readline re-attach its OWN 'data'
+ * decoder via emitKeypressEvents' `newListener` hook. The REPL already forwards
+ * raw bytes to that decoder manually, so a freshly auto-attached decoder is a
+ * duplicate — and two decoders for the same bytes double-echo every keystroke.
+ * To avoid that, we add keypress listeners first, then reset the 'data' listener
+ * set to EXACTLY the saved set, dropping any stray decoder.
+ */
+export function restoreStdinListeners(savedDataListeners, savedKeypressListeners) {
+    for (const fn of savedKeypressListeners) {
+        process.stdin.on('keypress', fn);
+    }
+    process.stdin.removeAllListeners('data');
+    for (const fn of savedDataListeners) {
+        process.stdin.on('data', fn);
+    }
+}
+const requestTimestamps = [];
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function printResponse(text, indentStr = '  ') {
+    const indent = (s) => s.split('\n').map(l => indentStr + l).join('\n');
+    const { response } = extractThinkTags(text);
+    if (response.trim()) {
+        process.stdout.write(indent(renderMarkdown(response)) + '\n');
+    }
+}
+function toolPhaseLabel(name) {
+    switch (name) {
+        case 'write_file': return 'Writing file';
+        case 'edit_file': return 'Editing file';
+        case 'read_file': return 'Reading';
+        case 'bash': return 'Preparing command';
+        case 'spawn_agent': return 'Spawning agent';
+        case 'list_dir': return 'Listing directory';
+        case 'search_files': return 'Searching';
+        case 'grep': return 'Searching';
+        default: return `Preparing ${name}`;
+    }
+}
+export class Agent {
+    client;
+    config;
+    conversation = [];
+    systemPrompt;
+    sessionAllowList = new Set();
+    sessionDenyList = new Set();
+    depth;
+    indent;
+    activeTurnStats = null;
+    activeChangedFiles = new Set();
+    lastTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
+    constructor(client, config, systemPrompt, depth = 0) {
+        this.client = client;
+        this.config = config;
+        this.systemPrompt = systemPrompt;
+        this.depth = depth;
+        this.indent = '  '.repeat(depth + 1);
+    }
+    clearConversation() {
+        this.conversation = [];
+    }
+    getConversation() {
+        return this.conversation;
+    }
+    setConversation(messages) {
+        this.conversation = [...messages];
+    }
+    getLastTurnStats() {
+        return { ...this.lastTurnStats };
+    }
+    async send(userMessage, opts = {}) {
+        this.activeTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
+        this.activeChangedFiles = new Set();
+        this.conversation.push({ role: 'user', content: userMessage });
+        try {
+            await this.runLoop(opts);
+        }
+        finally {
+            this.lastTurnStats = this.activeTurnStats
+                ? { ...this.activeTurnStats, filesChanged: this.activeChangedFiles.size }
+                : { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
+            this.activeTurnStats = null;
+            this.activeChangedFiles = new Set();
+        }
+    }
+    recordChangedFile(name, input, result) {
+        if (name !== 'write_file' && name !== 'edit_file')
+            return;
+        if (result.startsWith('Error'))
+            return;
+        const path = input.path;
+        if (typeof path === 'string' && path.trim())
+            this.activeChangedFiles.add(path);
+    }
+    // ── Tool call grouping ────────────────────────────────────────────────────
+    groupToolCalls(calls) {
+        const groups = [];
+        for (const tc of calls) {
+            const last = groups[groups.length - 1];
+            if (last && last[0].name === tc.name) {
+                last.push(tc);
+            }
+            else {
+                groups.push([tc]);
+            }
+        }
+        return groups;
+    }
+    formatGroupSummary(name, inputs) {
+        switch (name) {
+            case 'read_file': {
+                const paths = [...new Set(inputs.map(i => String(i.path ?? '')))];
+                const mins = [];
+                const maxs = [];
+                for (const i of inputs) {
+                    mins.push(Number(i.start_line ?? 1));
+                    if (i.end_line != null)
+                        maxs.push(Number(i.end_line));
+                }
+                const lo = Math.min(...mins);
+                const hi = maxs.length ? Math.max(...maxs) : '?';
+                const pathStr = paths.length === 1 ? `"${paths[0]}"` : `${paths.length} files`;
+                return `${pathStr} lines ${lo}-${hi}`;
+            }
+            case 'bash': {
+                const first = String(inputs[0]?.command ?? '').slice(0, 40);
+                return inputs.length > 1 ? `${first}… (+${inputs.length - 1} more)` : first;
+            }
+            case 'write_file': {
+                const paths = inputs.map(i => String(i.path ?? '(?)'));
+                return paths.length <= 3 ? paths.map(p => `"${p}"`).join(', ') : `${paths.length} files`;
+            }
+            default:
+                return `${inputs.length} calls`;
+        }
+    }
+    // ── Main agent loop ───────────────────────────────────────────────────────
+    async runLoop(opts) {
+        while (true) {
+            if (opts.signal?.aborted)
+                break;
+            const { assistantMsg, toolCalls, finishReason } = await this.callModel(opts);
+            this.conversation.push(assistantMsg);
+            if (opts.signal?.aborted)
+                break;
+            if (finishReason !== 'tool_calls' || !toolCalls.length)
+                break;
+            const groups = this.groupToolCalls(toolCalls);
+            for (const group of groups) {
+                if (opts.signal?.aborted)
+                    break;
+                const inputs = group.map(tc => {
+                    try {
+                        return JSON.parse(tc.argsStr || '{}');
+                    }
+                    catch {
+                        return {};
+                    }
+                });
+                if (group.length === 1) {
+                    if (this.activeTurnStats)
+                        this.activeTurnStats.toolCalls++;
+                    process.stdout.write(`\n${this.indent}${toolLine(group[0].name, formatToolArgs(group[0].name, inputs[0])).trimStart()}\n`);
+                    const result = await this.handleToolCall(group[0].name, group[0].id, inputs[0], opts);
+                    this.conversation.push({ role: 'tool', tool_call_id: group[0].id, content: result });
+                }
+                else {
+                    if (this.activeTurnStats)
+                        this.activeTurnStats.toolCalls += group.length;
+                    const summary = this.formatGroupSummary(group[0].name, inputs);
+                    process.stdout.write(`\n${this.indent}${toolLine(`${group[0].name} ×${group.length}`, summary).trimStart()}\n`);
+                    if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(group[0].name)) {
+                        const allowed = await this.checkPermission(group[0].name, inputs[0]);
+                        if (!allowed) {
+                            for (const tc of group) {
+                                this.conversation.push({
+                                    role: 'tool', tool_call_id: tc.id,
+                                    content: `Tool execution denied by user: ${tc.name}`,
+                                });
+                            }
+                            continue;
+                        }
+                    }
+                    const t0 = Date.now();
+                    let errors = 0;
+                    for (let i = 0; i < group.length; i++) {
+                        if (opts.signal?.aborted)
+                            break;
+                        const tc = group[i];
+                        if (tc.name === 'spawn_agent') {
+                            const result = await this.runSubagent(inputs[i], opts);
+                            this.conversation.push({ role: 'tool', tool_call_id: tc.id, content: result });
+                        }
+                        else {
+                            try {
+                                const result = await executeTool(tc.name, inputs[i]);
+                                if (result.startsWith('Error'))
+                                    errors++;
+                                this.recordChangedFile(tc.name, inputs[i], result);
+                                this.conversation.push({ role: 'tool', tool_call_id: tc.id, content: result });
+                            }
+                            catch (err) {
+                                errors++;
+                                this.conversation.push({ role: 'tool', tool_call_id: tc.id, content: `Tool error: ${err}` });
+                            }
+                        }
+                    }
+                    const ms = Date.now() - t0;
+                    const lineStr = errors === 0
+                        ? toolSuccessLine(ms, `Executed ${group.length} operations`)
+                        : toolErrorLine(`${errors} of ${group.length} operations failed`);
+                    process.stdout.write(`${this.indent}${lineStr}\n`);
+                }
+            }
+            process.stdout.write('\n');
+        }
+    }
+    // ── Model calls ───────────────────────────────────────────────────────────
+    async callModel(opts) {
+        try {
+            return await this.callModelStreaming(opts);
+        }
+        catch (err) {
+            if (opts.signal?.aborted)
+                throw err;
+            return await this.callModelNonStreaming(opts);
+        }
+    }
+    buildParams() {
+        const tools = this.depth >= 1
+            ? TOOL_DEFS.filter(t => t.function.name !== 'spawn_agent')
+            : TOOL_DEFS;
+        return {
+            model: this.config.model,
+            max_tokens: this.config.maxTokens,
+            temperature: this.config.temperature,
+            top_p: this.config.topP,
+            top_k: this.config.topK,
+            presence_penalty: this.config.presencePenalty,
+            frequency_penalty: this.config.frequencyPenalty,
+            messages: [
+                { role: 'system', content: this.systemPrompt },
+                ...this.conversation,
+            ],
+            tools,
+            tool_choice: 'auto',
+        };
+    }
+    async throttleModelRequest() {
+        const rpm = Math.max(1, Math.floor(this.config.requestsPerMinute || 10));
+        const prune = () => {
+            const now = Date.now();
+            while (requestTimestamps.length && now - requestTimestamps[0] >= 60_000) {
+                requestTimestamps.shift();
+            }
+        };
+        prune();
+        if (requestTimestamps.length >= rpm) {
+            const waitMs = Math.max(0, 60_000 - (Date.now() - requestTimestamps[0]) + 25);
+            process.stdout.write(`\n${this.indent}${c.muted(`Rate limit: waiting ${(waitMs / 1000).toFixed(1)}s (${rpm} rpm)`)}`);
+            await sleep(waitMs);
+            process.stdout.write('\r\x1b[2K');
+            prune();
+        }
+        requestTimestamps.push(Date.now());
+    }
+    async callModelStreaming(opts) {
+        const spinner = new InlineSpinner('Working', opts.startedAt);
+        spinner.start();
+        const requestOpts = opts.signal ? { signal: opts.signal } : undefined;
+        let stream;
+        try {
+            if (this.activeTurnStats)
+                this.activeTurnStats.modelCalls++;
+            await this.throttleModelRequest();
+            stream = await this.client.chat.completions.create({
+                ...this.buildParams(),
+                stream: true,
+            }, requestOpts);
+        }
+        catch (err) {
+            spinner.stop();
+            throw err;
+        }
+        let textContent = '';
+        let thinkingContent = '';
+        let totalArgsChars = 0;
+        let finishReason = 'stop';
+        let phase = 'Working';
+        const toolCallsMap = new Map();
+        try {
+            for await (const chunk of stream) {
+                if (opts.signal?.aborted)
+                    break;
+                const choice = chunk.choices[0];
+                if (!choice)
+                    continue;
+                const { delta, finish_reason } = choice;
+                if (finish_reason)
+                    finishReason = finish_reason;
+                const raw = delta;
+                if (typeof raw.reasoning_content === 'string' && raw.reasoning_content) {
+                    thinkingContent += raw.reasoning_content;
+                    phase = 'Working';
+                }
+                if (delta.content) {
+                    textContent += delta.content;
+                    phase = 'Generating';
+                }
+                if (delta.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index;
+                        if (!toolCallsMap.has(idx)) {
+                            toolCallsMap.set(idx, {
+                                id: tc.id ?? `call_${idx}`,
+                                name: tc.function?.name ?? '',
+                                argsStr: tc.function?.arguments ?? '',
+                            });
+                            if (tc.function?.name) {
+                                phase = toolPhaseLabel(tc.function.name);
+                            }
+                            if (tc.function?.arguments)
+                                totalArgsChars += tc.function.arguments.length;
+                        }
+                        else {
+                            const acc = toolCallsMap.get(idx);
+                            if (tc.id)
+                                acc.id = tc.id;
+                            if (tc.function?.name && !acc.name) {
+                                acc.name = tc.function.name;
+                                phase = toolPhaseLabel(tc.function.name);
+                            }
+                            if (tc.function?.arguments) {
+                                acc.argsStr += tc.function.arguments;
+                                totalArgsChars += tc.function.arguments.length;
+                            }
+                        }
+                    }
+                }
+                const totalTokens = estimateTokens(thinkingContent.length + textContent.length + totalArgsChars);
+                spinner.updateLabel(`${phase} (${totalTokens.toLocaleString()} tokens)`);
+            }
+        }
+        catch (err) {
+            if (opts.signal?.aborted) {
+                // user cancelled — swallow
+            }
+            else {
+                throw err;
+            }
+        }
+        finally {
+            spinner.stop();
+        }
+        if (textContent) {
+            printResponse(textContent, this.indent);
+        }
+        const toolCalls = [...toolCallsMap.values()];
+        const assistantMsg = {
+            role: 'assistant',
+            content: textContent || null,
+            ...(toolCalls.length ? {
+                tool_calls: toolCalls.map(tc => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: { name: tc.name, arguments: tc.argsStr },
+                })),
+            } : {}),
+        };
+        return { assistantMsg, toolCalls, finishReason };
+    }
+    async callModelNonStreaming(opts) {
+        const spinner = new InlineSpinner('Working', opts.startedAt);
+        spinner.start();
+        const requestOpts = opts.signal ? { signal: opts.signal } : undefined;
+        let resp;
+        try {
+            if (this.activeTurnStats)
+                this.activeTurnStats.modelCalls++;
+            await this.throttleModelRequest();
+            resp = await this.client.chat.completions.create({
+                ...this.buildParams(),
+            }, requestOpts);
+        }
+        finally {
+            spinner.stop();
+        }
+        const choice = resp.choices[0];
+        const msg = choice.message;
+        const finishReason = choice.finish_reason ?? 'stop';
+        const textContent = msg.content ?? '';
+        if (textContent) {
+            printResponse(textContent, this.indent);
+        }
+        const toolCalls = (msg.tool_calls ?? []).map(tc => ({
+            id: tc.id, name: tc.function.name, argsStr: tc.function.arguments,
+        }));
+        const assistantMsg = {
+            role: 'assistant',
+            content: textContent || null,
+            ...(toolCalls.length ? {
+                tool_calls: (msg.tool_calls ?? []).map(tc => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: tc.function,
+                })),
+            } : {}),
+        };
+        return { assistantMsg, toolCalls, finishReason };
+    }
+    // ── Tool execution ────────────────────────────────────────────────────────
+    async handleToolCall(name, id, input, opts) {
+        if (name === 'spawn_agent') {
+            return this.runSubagent(input, opts);
+        }
+        if (name === 'ask_user') {
+            return this.askUser(input);
+        }
+        if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(name)) {
+            const allowed = await this.checkPermission(name, input);
+            if (!allowed)
+                return `Tool execution denied by user: ${name}`;
+        }
+        const t0 = Date.now();
+        try {
+            const result = await executeTool(name, input);
+            this.recordChangedFile(name, input, result);
+            const ms = Date.now() - t0;
+            const preview = result.split('\n')[0].slice(0, 80);
+            process.stdout.write(`${this.indent}${toolSuccessLine(ms, preview)}\n`);
+            return result;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stdout.write(`${this.indent}${toolErrorLine(msg)}\n`);
+            return msg;
+        }
+    }
+    async askUser(input) {
+        const question = (input.question ?? '').trim();
+        if (!question)
+            return 'Error: ask_user requires a question.';
+        process.stdout.write(`\n${this.indent}${c.info('[?]')} ${c.white.bold(question)}\n` +
+            `${this.indent}${c.primary('╰─❯')} `);
+        return new Promise((resolve) => {
+            if (!process.stdin.isTTY) {
+                process.stdout.write(chalk.dim('(non-interactive, skipping)\n'));
+                resolve('(no answer — non-interactive mode)');
+                return;
+            }
+            const savedDataListeners = process.stdin.rawListeners('data').slice();
+            const savedKeypressListeners = process.stdin.rawListeners('keypress').slice();
+            process.stdin.removeAllListeners('data');
+            process.stdin.removeAllListeners('keypress');
+            const wasRaw = process.stdin.isRaw ?? false;
+            if (wasRaw)
+                process.stdin.setRawMode(false);
+            const readline = require('readline');
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+            rl.on('line', (answer) => {
+                rl.close();
+                if (wasRaw)
+                    process.stdin.setRawMode(true);
+                restoreStdinListeners(savedDataListeners, savedKeypressListeners);
+                const trimmed = answer.trim();
+                resolve(trimmed || '(no answer)');
+            });
+        });
+    }
+    // ── Subagent ──────────────────────────────────────────────────────────────
+    async runSubagent(input, opts) {
+        if (this.depth >= 2) {
+            return 'Error: subagents cannot spawn further subagents (max depth reached).';
+        }
+        const task = (input.task ?? '').trim();
+        if (!task)
+            return 'Error: spawn_agent requires a "task" describing what to do.';
+        const label = task.length > 64 ? task.slice(0, 64) + '…' : task;
+        process.stdout.write(`\n${this.indent}${c.primary('◆')} ${c.primary.bold('subagent')} ${c.muted('»')} ${c.white(label)}\n`);
+        const subPrompt = SUBAGENT_FRAMING + '\n\n' + this.systemPrompt;
+        const sub = new Agent(this.client, this.config, subPrompt, this.depth + 1);
+        const message = input.context
+            ? `Context from the main agent:\n${input.context}\n\nYour task: ${task}`
+            : `Your task: ${task}`;
+        try {
+            await sub.send(message, { autoApprove: true, signal: opts.signal });
+        }
+        catch (err) {
+            process.stdout.write(`${this.indent}${c.error('✗')} ${c.muted('subagent failed')}\n`);
+            return `Subagent error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        const result = sub.getLastAssistantText();
+        process.stdout.write(`${this.indent}${c.success('✓')} ${c.muted('subagent done')}\n\n`);
+        return result || '(subagent completed but produced no summary)';
+    }
+    getLastAssistantText() {
+        for (let i = this.conversation.length - 1; i >= 0; i--) {
+            const m = this.conversation[i];
+            if (m.role === 'assistant' && typeof m.content === 'string' && m.content.trim()) {
+                return m.content;
+            }
+        }
+        return '';
+    }
+    // ── Permission prompt ─────────────────────────────────────────────────────
+    async checkPermission(toolName, input) {
+        if (this.sessionDenyList.has(toolName))
+            return false;
+        if (this.sessionAllowList.has(toolName))
+            return true;
+        process.stdout.write(permissionPrompt(toolName, formatToolArgs(toolName, input)));
+        return new Promise((resolve) => {
+            if (!process.stdin.isTTY) {
+                process.stdout.write(chalk.dim('(non-interactive, denying)\n'));
+                resolve(false);
+                return;
+            }
+            const wasRaw = process.stdin.isRaw ?? false;
+            const savedDataListeners = process.stdin.rawListeners('data').slice();
+            const savedKeypressListeners = process.stdin.rawListeners('keypress').slice();
+            process.stdin.removeAllListeners('data');
+            process.stdin.removeAllListeners('keypress');
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            const onData = (data) => {
+                process.stdin.removeListener('data', onData);
+                // Restore raw mode to what it was (keeps REPL's ESC handler working)
+                process.stdin.setRawMode(wasRaw);
+                restoreStdinListeners(savedDataListeners, savedKeypressListeners);
+                // Only pause if nobody else was listening (no REPL ESC handler)
+                if (!savedDataListeners.length) {
+                    process.stdin.pause();
+                }
+                const key = data.toString().toLowerCase();
+                if (key === 'y' || key === '\r' || key === '\n') {
+                    process.stdout.write(chalk.green('y\n'));
+                    resolve(true);
+                }
+                else if (key === 'a') {
+                    process.stdout.write(chalk.blue('a (always)\n'));
+                    this.sessionAllowList.add(toolName);
+                    resolve(true);
+                }
+                else if (key === '!') {
+                    process.stdout.write(chalk.dim('! (always deny)\n'));
+                    this.sessionDenyList.add(toolName);
+                    resolve(false);
+                }
+                else {
+                    process.stdout.write(chalk.red('n\n'));
+                    resolve(false);
+                }
+            };
+            process.stdin.on('data', onData);
+        });
+    }
+}
+export const SUBAGENT_FRAMING = `You are a focused sub-agent spawned by Ikie to autonomously complete ONE specific task.
+Work independently — do not ask the user questions. Use your tools to gather what you
+need, do the work, and verify it. When finished, your FINAL message must be a concise
+summary of what you did and any key results (paths changed, findings, answers). That
+summary is the only thing returned to the main agent, so make it self-contained.`;
+export function buildSystemPrompt(projectContext, memoryContext) {
+    const parts = [
+        `You are Ikie, an expert agentic coding assistant running in the terminal.
+
+## Identity
+Your name is Ikie. If asked what you are, who made you, or what model powers you,
+say you are Ikie, a terminal coding assistant. Never claim or imply that you are
+Claude, ChatGPT, GPT, Gemini, Llama, or any other named model or company's assistant.
+Do not speculate about your underlying model.
+
+You help developers write, debug, understand, and refactor code. You work autonomously
+using your tools to accomplish tasks. Be direct, concise, and practical.
+
+## Working Style
+- ALWAYS provide complete, valid arguments to tools. Never omit required fields like \`path\`.
+- When creating files, use the FULL file path (relative or absolute) — not just a filename.
+- Read files before editing them
+- Prefer \`edit_file\` over \`write_file\` for modifications (surgical edits > full rewrites)
+- Run tests or sanity checks after making meaningful changes
+- For complex tasks, break them down and tackle one step at a time
+- Acknowledge errors and self-correct; don't pretend failures didn't happen
+- When writing large files, write the COMPLETE content. Never truncate or use placeholders.
+- For long-running servers/processes, use \`nohup cmd &\` or \`setsid cmd\` so they survive after the session.
+
+## Approach
+- Understand before acting: read the relevant files and explore the structure
+  instead of guessing. A few targeted reads beat one wrong edit.
+- For multi-step work, form a short plan, then execute it step by step and adapt
+  as you learn. Keep momentum — don't stall on decisions you can reverse later.
+- Verify your work: after edits, re-read the changed regions and run the build,
+  tests, or linter. Fix what you broke before you call a task done.
+- Delegate isolated or parallelizable investigation to \`spawn_agent\` to stay focused.
+- Be concise: explain what you did and why in a sentence or two, and show
+  code/results rather than narrating. Use \`ask_user\` only when genuinely blocked.
+- Never leave a task half-finished or claim a success you have not verified.
+
+## Tools Available
+- \`read_file\`: Read any file, optionally with line range
+- \`write_file\`: Create new files or full rewrites
+- \`edit_file\`: Replace exact strings (preferred for modifications)
+- \`bash\`: Run shell commands (build, test, git, etc.). Commands ending with & run detached in background.
+- \`list_dir\`: Explore directory structure
+- \`search_files\`: Find files by glob pattern
+- \`grep\`: Search file contents by regex
+- \`memory_write\`: Persist important notes across sessions
+- \`ask_user\`: Ask the user a clarifying question when you need more info to proceed.
+  The user's answer is returned as the tool result. Use sparingly — only when genuinely
+  unsure. Don't ask for confirmation on safe operations.
+- \`spawn_agent\`: Delegate a self-contained subtask to a focused sub-agent. Use this
+  to parallelize or isolate work — e.g. "investigate how auth is implemented and report
+  back", or "write and run tests for module X". The sub-agent has the same tools (except
+  it cannot spawn further sub-agents) and returns a summary. Give it a clear, complete
+  \`task\` and any needed \`context\`, since it does not see this conversation.`,
+    ];
+    if (projectContext)
+        parts.push(`## Project Context\n${projectContext}`);
+    if (memoryContext)
+        parts.push(`## Memory\n${memoryContext}`);
+    return parts.join('\n\n');
+}

package/dist/attachments.d.ts

@@ -0,0 +1,33 @@
+export interface ImageAttachment {
+    id: number;
+    path: string;
+    name: string;
+    mime: string;
+    bytes: number;
+}
+export type UserContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+export declare function isImagePath(path: string): boolean;
+export declare function loadImageAttachment(path: string, id: number): ImageAttachment;
+/**
+ * Load image from clipboard (cross-platform)
+ * Windows: PowerShell
+ * macOS: osascript (AppleScript)
+ * Linux: xclip (X11) or wl-paste (Wayland)
+ */
+export declare function loadClipboardImageAttachment(id: number): ImageAttachment;
+/**
+ * Check if clipboard contains an image (non-throwing)
+ * Returns true if clipboard has an image, false otherwise
+ */
+export declare function hasClipboardImage(): boolean;
+export declare function imageToContentPart(image: ImageAttachment): UserContentPart;
+export declare function buildUserContent(text: string, images: ImageAttachment[]): string | UserContentPart[];
+export declare function formatBytes(bytes: number): string;