zyndo 0.1.0

package/dist/sellerDaemon.js

@@ -0,0 +1,336 @@
+// ---------------------------------------------------------------------------
+// Seller daemon — poll for tasks, run agent loop, deliver results
+// ---------------------------------------------------------------------------
+import { connect, reconnect, heartbeat, pollEvents, acceptTask, deliverTask, sendTaskMessage, getTaskMessages, getTaskDetail } from './connection.js';
+import { runAgentLoop } from './agentLoop.js';
+import { createAnthropicProvider } from './providers/anthropic.js';
+import { createOpenAIProvider } from './providers/openai.js';
+import { createOllamaProvider } from './providers/ollama.js';
+import { runClaudeCodeTask } from './providers/claudeCode.js';
+import { createReadFileTool } from './tools/readFile.js';
+import { createWriteFileTool } from './tools/writeFile.js';
+import { createBashTool } from './tools/bash.js';
+import { createGlobTool } from './tools/glob.js';
+import { createGrepTool } from './tools/grep.js';
+import { createAskBuyerTool } from './tools/askBuyer.js';
+import { loadState, saveState, deleteState, loadSession, saveSession } from './state.js';
+const POLL_INTERVAL_MS = 25_000;
+const HEARTBEAT_INTERVAL_MS = 45_000;
+const defaultLogger = {
+    info: (msg) => process.stdout.write(`[zyndo] ${msg}\n`),
+    error: (msg) => process.stderr.write(`[zyndo] ERROR: ${msg}\n`)
+};
+// ---------------------------------------------------------------------------
+// Provider factory
+// ---------------------------------------------------------------------------
+function createProvider(name, model, apiKey) {
+    switch (name) {
+        case 'anthropic': return createAnthropicProvider(apiKey ?? '', model);
+        case 'openai': return createOpenAIProvider(apiKey ?? '', model);
+        case 'ollama': return createOllamaProvider(model);
+        case 'claude-code': throw new Error('createProvider should not be called for claude-code provider.');
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+function loadTools(allowedTools, workingDirectory) {
+    const allTools = {
+        read_file: () => createReadFileTool(workingDirectory),
+        write_file: () => createWriteFileTool(workingDirectory),
+        bash: () => createBashTool(workingDirectory),
+        glob: () => createGlobTool(workingDirectory),
+        grep: () => createGrepTool(workingDirectory),
+        ask_buyer: () => createAskBuyerTool()
+    };
+    return allowedTools
+        .filter((name) => allTools[name] !== undefined)
+        .map((name) => allTools[name]());
+}
+// ---------------------------------------------------------------------------
+// Start daemon
+// ---------------------------------------------------------------------------
+export async function startSellerDaemon(config, opts) {
+    const logger = opts?.logger ?? defaultLogger;
+    const signal = opts?.signal;
+    // Try to reconnect as the same agent from a previous session
+    let session;
+    const previousSession = loadSession();
+    if (previousSession !== undefined) {
+        logger.info(`Found previous session (agentId=${previousSession.agentId}), reconnecting...`);
+        try {
+            const tempSession = {
+                agentId: previousSession.agentId,
+                token: '',
+                reconnectToken: previousSession.reconnectToken,
+                bridgeUrl: config.bridgeUrl
+            };
+            session = await reconnect(tempSession, {
+                role: 'seller',
+                name: config.name,
+                description: config.description
+            });
+            logger.info(`Reconnected: agentId=${session.agentId} (same identity preserved)`);
+        }
+        catch {
+            logger.info('Previous session expired, creating new registration...');
+        }
+    }
+    // Fresh connect if no previous session or reconnect failed
+    if (session === undefined) {
+        logger.info(`Connecting as seller "${config.name}"...`);
+        session = await connect(config.bridgeUrl, config.apiKey, {
+            role: 'seller',
+            name: config.name,
+            description: config.description,
+            skills: [...config.skills],
+            categories: [...config.categories],
+            maxConcurrentTasks: config.maxConcurrentTasks
+        });
+        logger.info(`Connected: agentId=${session.agentId}`);
+    }
+    // Persist session for future restarts
+    saveSession(session.agentId, session.reconnectToken);
+    let lastEventId = 0;
+    let lastHeartbeat = Date.now();
+    const activeTasks = new Set();
+    while (signal === undefined || !signal.aborted) {
+        try {
+            // Heartbeat
+            if (Date.now() - lastHeartbeat >= HEARTBEAT_INTERVAL_MS) {
+                try {
+                    await heartbeat(session);
+                    lastHeartbeat = Date.now();
+                }
+                catch {
+                    logger.info('Heartbeat failed, attempting reconnect...');
+                    try {
+                        session = await reconnect(session, { role: 'seller', name: config.name, description: config.description });
+                        saveSession(session.agentId, session.reconnectToken);
+                        logger.info('Reconnected successfully.');
+                        lastHeartbeat = Date.now();
+                    }
+                    catch (reconnectError) {
+                        logger.error(`Reconnect failed: ${reconnectError instanceof Error ? reconnectError.message : String(reconnectError)}`);
+                        break;
+                    }
+                }
+            }
+            // Poll events
+            const events = await pollEvents(session, lastEventId);
+            let minDeferredEventId;
+            for (const event of events) {
+                if (event.type === 'task.assigned') {
+                    const taskId = event.payload.taskId;
+                    if (activeTasks.has(taskId)) {
+                        if (event.eventId > lastEventId)
+                            lastEventId = event.eventId;
+                        continue;
+                    }
+                    if (activeTasks.size >= config.maxConcurrentTasks) {
+                        logger.info(`Task ${taskId}: at capacity (${activeTasks.size}/${config.maxConcurrentTasks}), deferring.`);
+                        // Don't advance cursor past deferred tasks so they are retried
+                        if (minDeferredEventId === undefined || event.eventId < minDeferredEventId) {
+                            minDeferredEventId = event.eventId;
+                        }
+                        continue;
+                    }
+                    activeTasks.add(taskId);
+                    if (event.eventId > lastEventId)
+                        lastEventId = event.eventId;
+                    logger.info(`Task assigned: ${taskId} (active: ${activeTasks.size}/${config.maxConcurrentTasks})`);
+                    handleTask(session, taskId, config, logger)
+                        .catch((err) => {
+                        logger.error(`Task ${taskId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    })
+                        .finally(() => activeTasks.delete(taskId));
+                }
+                else {
+                    // Non-task-assigned events always advance the cursor
+                    if (event.eventId > lastEventId)
+                        lastEventId = event.eventId;
+                }
+                if (event.type === 'task.message.received') {
+                    const taskId = event.payload.taskId;
+                    if (activeTasks.has(taskId))
+                        continue; // Task handler is already running
+                    activeTasks.add(taskId);
+                    logger.info(`Message received for task: ${taskId}`);
+                    handleBuyerMessage(session, taskId, config, logger)
+                        .catch((err) => {
+                        logger.error(`Message handling for ${taskId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    })
+                        .finally(() => activeTasks.delete(taskId));
+                }
+                if (event.type === 'task.revision.requested') {
+                    const taskId = event.payload.taskId;
+                    const feedback = event.payload.feedback ?? '';
+                    if (activeTasks.has(taskId))
+                        continue;
+                    activeTasks.add(taskId);
+                    logger.info(`Revision requested for task: ${taskId}`);
+                    handleRevision(session, taskId, feedback, config, logger)
+                        .catch((err) => {
+                        logger.error(`Revision for ${taskId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    })
+                        .finally(() => activeTasks.delete(taskId));
+                }
+                // Clean up state on terminal events
+                if (event.type === 'task.completed' || event.type === 'task.rejected' || event.type === 'task.failed' || event.type === 'task.canceled') {
+                    const taskId = event.payload.taskId;
+                    if (taskId !== undefined)
+                        deleteState(taskId);
+                }
+            }
+            // Cap cursor below deferred events so they are retried next poll
+            if (minDeferredEventId !== undefined && lastEventId >= minDeferredEventId) {
+                lastEventId = minDeferredEventId - 1;
+            }
+        }
+        catch (error) {
+            logger.error(`Poll error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+    logger.info('Daemon stopped.');
+}
+// ---------------------------------------------------------------------------
+// Task handler
+// ---------------------------------------------------------------------------
+async function handleTask(session, taskId, config, logger) {
+    await acceptTask(session, taskId);
+    logger.info(`Task ${taskId}: accepted, starting work...`);
+    // Get task context from task detail first, then messages as supplement
+    const detail = await getTaskDetail(session, taskId);
+    const taskContext = detail?.context ?? '';
+    const messages = await getTaskMessages(session, taskId);
+    const messageContext = messages.map((m) => m.content).join('\n');
+    const context = taskContext || messageContext || 'Task assigned. No additional context provided.';
+    const result = config.provider === 'claude-code'
+        ? await runClaudeCodeTask(context, config, logger)
+        : await runAgentLoop(createProvider(config.provider, config.model, config.providerApiKey), loadTools(config.allowedTools, config.workingDirectory), context, { systemPrompt: config.systemPrompt, taskId });
+    if (result.timedOut === true) {
+        logger.error(`Task ${taskId}: agent timed out or errored, notifying buyer.`);
+        await sendTaskMessage(session, taskId, 'info', 'The seller agent encountered a timeout processing this task. Please allow more time or simplify the request. The task remains assigned.');
+        saveState({ taskId, messages: [], claudeCodeContext: context, originalContext: context });
+        return;
+    }
+    if (result.paused) {
+        logger.info(`Task ${taskId}: paused, asking buyer: "${result.pendingQuestion?.slice(0, 100)}..."`);
+        saveState({ taskId, messages: [], claudeCodeContext: context, pendingQuestion: result.pendingQuestion });
+        await sendTaskMessage(session, taskId, 'question', result.pendingQuestion ?? 'Could you clarify?');
+        return;
+    }
+    logger.info(`Task ${taskId}: delivering result (${result.output.length} chars)`);
+    await deliverTask(session, taskId, result.output);
+    // Preserve state for potential revision — only deleted on terminal events
+    saveState({ taskId, messages: [], claudeCodeContext: context, originalContext: context, lastDelivery: result.output });
+}
+// ---------------------------------------------------------------------------
+// Revision handler
+// ---------------------------------------------------------------------------
+async function handleRevision(session, taskId, feedback, config, logger) {
+    const savedState = loadState(taskId);
+    // Use original task context (not compounded revision context) to avoid quadratic growth
+    const originalContext = savedState?.originalContext ?? savedState?.claudeCodeContext ?? '';
+    const lastDelivery = savedState?.lastDelivery ?? '';
+    const truncatedDelivery = lastDelivery.length > 10_000
+        ? lastDelivery.slice(0, 10_000) + `\n... [truncated, original was ${lastDelivery.length} chars]`
+        : lastDelivery;
+    const revisionContext = [
+        originalContext,
+        '',
+        '[Your previous delivery]:',
+        truncatedDelivery,
+        '',
+        '[Buyer revision request]:',
+        feedback,
+        '',
+        'Revise your work based on the buyer feedback above. Output the complete updated deliverable.'
+    ].join('\n');
+    const result = config.provider === 'claude-code'
+        ? await runClaudeCodeTask(revisionContext, config, logger)
+        : await runAgentLoop(createProvider(config.provider, config.model, config.providerApiKey), loadTools(config.allowedTools, config.workingDirectory), revisionContext, { systemPrompt: config.systemPrompt, taskId });
+    if (result.timedOut === true) {
+        logger.error(`Task ${taskId}: revision timed out, notifying buyer.`);
+        await sendTaskMessage(session, taskId, 'info', 'The seller agent timed out while working on the revision. Please allow more time or simplify the request.');
+        saveState({ taskId, messages: [], claudeCodeContext: revisionContext, originalContext });
+        return;
+    }
+    if (result.paused) {
+        logger.info(`Task ${taskId}: revision paused, asking buyer...`);
+        saveState({ taskId, messages: [], claudeCodeContext: revisionContext, originalContext, pendingQuestion: result.pendingQuestion });
+        await sendTaskMessage(session, taskId, 'question', result.pendingQuestion ?? 'Could you clarify?');
+        return;
+    }
+    logger.info(`Task ${taskId}: delivering revision (${result.output.length} chars)`);
+    await deliverTask(session, taskId, result.output);
+    saveState({ taskId, messages: [], claudeCodeContext: revisionContext, originalContext, lastDelivery: result.output });
+}
+// ---------------------------------------------------------------------------
+// Buyer message handler (resume paused loop)
+// ---------------------------------------------------------------------------
+function buildResumedContext(priorContext, priorQuestion, buyerAnswer) {
+    return [
+        priorContext,
+        '',
+        `[You previously asked the buyer]: ${priorQuestion ?? '(question not recorded)'}`,
+        `[Buyer answered]: ${buyerAnswer}`,
+        '',
+        'Continue the task with this new information.'
+    ].join('\n');
+}
+async function handleBuyerMessage(session, taskId, config, logger) {
+    const savedState = loadState(taskId);
+    if (savedState === undefined) {
+        logger.info(`Task ${taskId}: no saved state found, ignoring message.`);
+        return;
+    }
+    // Post-delivery message: buyer sent a message after receiving delivery.
+    // Guide them to use zyndo_request_revision for the formal revision flow.
+    if (savedState.lastDelivery !== undefined && savedState.pendingQuestion === undefined) {
+        logger.info(`Task ${taskId}: buyer sent message after delivery, guiding to zyndo_request_revision.`);
+        await sendTaskMessage(session, taskId, 'info', 'I received your message. To get a revised delivery, please use the revision action (zyndo_request_revision) with your feedback. I will then rework and re-deliver.');
+        return;
+    }
+    const messages = await getTaskMessages(session, taskId);
+    const lastMessage = messages[messages.length - 1];
+    if (lastMessage === undefined)
+        return;
+    logger.info(`Task ${taskId}: resuming with buyer's answer.`);
+    let result;
+    if (config.provider === 'claude-code') {
+        const enrichedContext = buildResumedContext(savedState.claudeCodeContext ?? '', savedState.pendingQuestion, lastMessage.content);
+        result = await runClaudeCodeTask(enrichedContext, config, logger);
+    }
+    else {
+        if (savedState.pendingToolCallId === undefined) {
+            logger.info(`Task ${taskId}: no pending tool call, ignoring.`);
+            return;
+        }
+        result = await runAgentLoop(createProvider(config.provider, config.model, config.providerApiKey), loadTools(config.allowedTools, config.workingDirectory), lastMessage.content, { systemPrompt: config.systemPrompt, taskId });
+    }
+    if (result.timedOut === true) {
+        logger.error(`Task ${taskId}: message-resume timed out, notifying buyer.`);
+        await sendTaskMessage(session, taskId, 'info', 'The seller agent timed out while processing your response. Please allow more time or simplify the request.');
+        return;
+    }
+    if (result.paused) {
+        logger.info(`Task ${taskId}: paused again, asking buyer: "${result.pendingQuestion?.slice(0, 100)}..."`);
+        const updatedContext = config.provider === 'claude-code'
+            ? buildResumedContext(savedState.claudeCodeContext ?? '', savedState.pendingQuestion, lastMessage.content)
+            : savedState.claudeCodeContext ?? '';
+        saveState({ taskId, messages: [], claudeCodeContext: updatedContext, pendingQuestion: result.pendingQuestion });
+        await sendTaskMessage(session, taskId, 'question', result.pendingQuestion ?? 'Could you clarify?');
+        return;
+    }
+    logger.info(`Task ${taskId}: delivering result (${result.output.length} chars)`);
+    await deliverTask(session, taskId, result.output);
+    const resumedContext = config.provider === 'claude-code'
+        ? buildResumedContext(savedState.claudeCodeContext ?? '', savedState.pendingQuestion, lastMessage.content)
+        : savedState.claudeCodeContext ?? '';
+    saveState({ taskId, messages: [], claudeCodeContext: resumedContext, lastDelivery: result.output });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/state.d.ts

@@ -0,0 +1,21 @@
+import type { Message } from './providers/types.js';
+export type ConversationState = Readonly<{
+    taskId: string;
+    messages: ReadonlyArray<Message>;
+    pendingToolCallId?: string;
+    claudeCodeContext?: string;
+    pendingQuestion?: string;
+    lastDelivery?: string;
+    originalContext?: string;
+}>;
+export declare function saveState(state: ConversationState): void;
+export declare function loadState(taskId: string): ConversationState | undefined;
+export declare function deleteState(taskId: string): void;
+export type PersistedSession = Readonly<{
+    agentId: string;
+    reconnectToken: string;
+    savedAt: string;
+}>;
+export declare function saveSession(agentId: string, reconnectToken: string): void;
+export declare function loadSession(): PersistedSession | undefined;
+export declare function clearSession(): void;

package/dist/state.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Conversation state persistence — save/load to disk
+// ---------------------------------------------------------------------------
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveConfigDir } from './config.js';
+function getBaseDir() {
+    return resolveConfigDir().dir;
+}
+const STATE_DIR = resolve(getBaseDir(), 'state');
+function sanitizeTaskId(taskId) {
+    return taskId.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+function stateFilePath(taskId) {
+    return resolve(STATE_DIR, `task-${sanitizeTaskId(taskId)}.json`);
+}
+export function saveState(state) {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(stateFilePath(state.taskId), JSON.stringify(state, null, 2), 'utf-8');
+}
+export function loadState(taskId) {
+    const path = stateFilePath(taskId);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function deleteState(taskId) {
+    const path = stateFilePath(taskId);
+    if (existsSync(path)) {
+        unlinkSync(path);
+    }
+}
+function getSessionFile() {
+    return resolve(getBaseDir(), 'session.json');
+}
+export function saveSession(agentId, reconnectToken) {
+    const baseDir = getBaseDir();
+    mkdirSync(baseDir, { recursive: true });
+    const data = { agentId, reconnectToken, savedAt: new Date().toISOString() };
+    writeFileSync(getSessionFile(), JSON.stringify(data, null, 2), 'utf-8');
+}
+export function loadSession() {
+    if (!existsSync(getSessionFile()))
+        return undefined;
+    try {
+        const raw = readFileSync(getSessionFile(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearSession() {
+    if (existsSync(getSessionFile())) {
+        unlinkSync(getSessionFile());
+    }
+}

package/dist/tools/askBuyer.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createAskBuyerTool(): Tool;

package/dist/tools/askBuyer.js

@@ -0,0 +1,19 @@
+export function createAskBuyerTool() {
+    return {
+        name: 'ask_buyer',
+        description: 'Ask the buyer a question. This pauses the agent loop and sends the question to the buyer. The agent will resume when the buyer responds.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'The question to ask the buyer' }
+            },
+            required: ['question']
+        },
+        async execute(input) {
+            return {
+                output: input.question,
+                pause: true
+            };
+        }
+    };
+}

package/dist/tools/bash.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createBashTool(workingDirectory: string): Tool;

package/dist/tools/bash.js

@@ -0,0 +1,35 @@
+import { execSync } from 'node:child_process';
+export function createBashTool(workingDirectory) {
+    return {
+        name: 'bash',
+        description: 'Execute a shell command and return its output. Use for running tests, builds, git commands, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'The shell command to execute' },
+                timeout: { type: 'number', description: 'Timeout in milliseconds (default: 120000)' }
+            },
+            required: ['command']
+        },
+        async execute(input) {
+            try {
+                const timeout = typeof input.timeout === 'number' ? input.timeout : 120_000;
+                const output = execSync(input.command, {
+                    cwd: workingDirectory,
+                    timeout,
+                    encoding: 'utf-8',
+                    maxBuffer: 10 * 1024 * 1024,
+                    stdio: ['pipe', 'pipe', 'pipe']
+                });
+                return { output: output.slice(0, 50_000) };
+            }
+            catch (error) {
+                const execError = error;
+                const stdout = execError.stdout ?? '';
+                const stderr = execError.stderr ?? '';
+                const combined = `${stdout}\n${stderr}`.trim().slice(0, 50_000);
+                return { output: combined || (execError.message ?? 'Command failed'), isError: true };
+            }
+        }
+    };
+}

package/dist/tools/glob.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createGlobTool(workingDirectory: string): Tool;

package/dist/tools/glob.js

@@ -0,0 +1,28 @@
+import { execSync } from 'node:child_process';
+export function createGlobTool(workingDirectory) {
+    return {
+        name: 'glob',
+        description: 'Find files matching a glob pattern. Returns matching file paths.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Glob pattern (e.g., "**/*.ts", "src/**/*.test.ts")' }
+            },
+            required: ['pattern']
+        },
+        async execute(input) {
+            try {
+                const pattern = input.pattern;
+                const output = execSync(`find . -path './${pattern}' -type f 2>/dev/null | head -100`, {
+                    cwd: workingDirectory,
+                    encoding: 'utf-8',
+                    timeout: 10_000
+                });
+                return { output: output.trim() || 'No files found matching pattern.' };
+            }
+            catch {
+                return { output: 'No files found matching pattern.' };
+            }
+        }
+    };
+}

package/dist/tools/grep.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createGrepTool(workingDirectory: string): Tool;

package/dist/tools/grep.js

@@ -0,0 +1,36 @@
+import { execSync } from 'node:child_process';
+function escapeShellArg(arg) {
+    return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+export function createGrepTool(workingDirectory) {
+    return {
+        name: 'grep',
+        description: 'Search file contents for a pattern. Returns matching lines with file paths and line numbers.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Search pattern (regex supported)' },
+                glob: { type: 'string', description: 'Glob filter for files (e.g., "*.ts")' },
+                context: { type: 'number', description: 'Lines of context around each match' }
+            },
+            required: ['pattern']
+        },
+        async execute(input) {
+            try {
+                const pattern = escapeShellArg(input.pattern);
+                const glob = typeof input.glob === 'string' ? `--include=${escapeShellArg(input.glob)}` : '';
+                const context = typeof input.context === 'number' ? `-C ${Math.min(Math.max(0, input.context), 20)}` : '';
+                const cmd = `grep -rn ${context} ${glob} ${pattern} . 2>/dev/null | head -100`;
+                const output = execSync(cmd, {
+                    cwd: workingDirectory,
+                    encoding: 'utf-8',
+                    timeout: 10_000
+                });
+                return { output: output.trim() || 'No matches found.' };
+            }
+            catch {
+                return { output: 'No matches found.' };
+            }
+        }
+    };
+}

package/dist/tools/pathSafety.d.ts

@@ -0,0 +1 @@
+export declare function resolveSafe(workingDirectory: string, userPath: string): string;

package/dist/tools/pathSafety.js

@@ -0,0 +1,9 @@
+import { resolve } from 'node:path';
+export function resolveSafe(workingDirectory, userPath) {
+    const base = resolve(workingDirectory);
+    const resolved = resolve(workingDirectory, userPath);
+    if (resolved !== base && !resolved.startsWith(base + '/')) {
+        throw new Error(`Path escapes working directory: ${userPath}`);
+    }
+    return resolved;
+}

package/dist/tools/readFile.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createReadFileTool(workingDirectory: string): Tool;

package/dist/tools/readFile.js

@@ -0,0 +1,35 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveSafe } from './pathSafety.js';
+export function createReadFileTool(workingDirectory) {
+    return {
+        name: 'read_file',
+        description: 'Read the contents of a file. Returns the file contents as text.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to the file (relative to working directory)' },
+                offset: { type: 'number', description: 'Line number to start reading from (0-based)' },
+                limit: { type: 'number', description: 'Maximum number of lines to read' }
+            },
+            required: ['path']
+        },
+        async execute(input) {
+            try {
+                const filePath = resolveSafe(workingDirectory, input.path);
+                if (!existsSync(filePath)) {
+                    return { output: `File not found: ${input.path}`, isError: true };
+                }
+                let content = readFileSync(filePath, 'utf-8');
+                const lines = content.split('\n');
+                const offset = typeof input.offset === 'number' ? input.offset : 0;
+                const limit = typeof input.limit === 'number' ? input.limit : lines.length;
+                const sliced = lines.slice(offset, offset + limit);
+                content = sliced.map((line, i) => `${offset + i + 1}\t${line}`).join('\n');
+                return { output: content };
+            }
+            catch (error) {
+                return { output: `Error reading file: ${error instanceof Error ? error.message : String(error)}`, isError: true };
+            }
+        }
+    };
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from '../providers/types.js';
+export type ToolResult = Readonly<{
+    output: string;
+    isError?: boolean;
+    pause?: boolean;
+}>;
+export type Tool = ToolDefinition & Readonly<{
+    execute: (input: Record<string, unknown>) => Promise<ToolResult>;
+}>;

package/dist/tools/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Tool interface for the agent loop
+// ---------------------------------------------------------------------------
+export {};

package/dist/tools/writeFile.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare function createWriteFileTool(workingDirectory: string): Tool;