@nodes/agent 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# @nodes/agent
+
+Autonomous AI agent runtime for Nodes platform.
+
+**Status: WIP — API may change.**
+
+## Install
+
+```bash
+npm install @nodes/agent
+```
+
+## Usage
+
+```bash
+NODES_URL=https://nodes.ws \
+NODES_API_KEY=... \
+NODES_AGENT=org/my-agent \
+GATEWAY_API_KEY=... \
+nodes
+```
+
+### Modes
+
+- `nodes` — Interactive chat
+- `nodes --tick` — Single autonomous execution
+- `nodes --serve` — Expose local tools as MCP server

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createRequire } from 'module';
+import { NodesClient } from '@nodes/sdk';
+import { runOnce, interactive } from './core/loop.js';
+import { interactiveTUI } from './core/tui-chat.js';
+import { serve } from './core/serve.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const { values } = parseArgs({
+    options: {
+        prompt: { type: 'string', short: 'p' },
+        node: { type: 'string', short: 'n' },
+        serve: { type: 'boolean' },
+        simple: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+    },
+    strict: false,
+});
+if (values.help) {
+    console.log(`
+nodes — Autonomous AI agent for Nodes
+
+Usage:
+  nodes                        Start in interactive mode (new chat)
+  nodes -n <nodeId>            Resume interactive chat on existing node
+  nodes -p "prompt"            Run a single prompt and exit
+  nodes -p "prompt" -n <id>    Run prompt in existing chat and exit
+  nodes --serve                Start MCP server (exposes local tools)
+  nodes --simple               Use simple readline UI (no TUI)
+  nodes --help                 Show this help
+
+Environment:
+  NODES_URL              Nodes instance URL (default: https://nodes.ws)
+  NODES_API_KEY          API key for authentication
+  NODES_AGENT            Agent slug (e.g. "nodes/my-agent") or user ID
+  PORT                   MCP server port (default: 8788, --serve only)
+`);
+    process.exit(0);
+}
+if (values.version) {
+    console.log(`nodes ${pkg.version}`);
+    process.exit(0);
+}
+// --serve doesn't require Nodes credentials (purely local MCP server)
+if (values.serve) {
+    serve().catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+else {
+    // All other modes require Nodes connection
+    const url = process.env.NODES_URL || 'https://nodes.ws';
+    const apiKey = process.env.NODES_API_KEY || '';
+    const agent = process.env.NODES_AGENT || '';
+    if (!apiKey) {
+        console.error('Error: NODES_API_KEY is required.');
+        process.exit(1);
+    }
+    if (!agent) {
+        console.error('Error: NODES_AGENT is required (agent slug or user ID).');
+        process.exit(1);
+    }
+    // Extract userId from user-scoped token (nodes_<userId>_<secret>)
+    const tokenMatch = apiKey.match(/^nodes_([a-f0-9]{24})_[a-f0-9]{32}$/);
+    const userId = tokenMatch?.[1];
+    const prompt = values.prompt;
+    const nodeId = values.node;
+    const nodes = new NodesClient({ url, apiKey, agent });
+    const config = { nodes, agent, userId, prompt, nodeId };
+    if (prompt) {
+        // One-shot mode
+        runOnce(config)
+            .then((result) => {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(0);
+        })
+            .catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        })
+            .finally(() => nodes.disconnect());
+    }
+    else {
+        if (values.simple) {
+            // Simple readline mode
+            process.on('SIGINT', async () => {
+                console.log('\nGoodbye.');
+                await nodes.disconnect();
+                process.exit(0);
+            });
+            interactive(config).catch((err) => {
+                console.error(err.message);
+                process.exit(1);
+            });
+        }
+        else {
+            // TUI mode (default) — handles its own SIGINT
+            interactiveTUI(config).catch((err) => {
+                console.error(err.message);
+                process.exit(1);
+            });
+        }
+    }
+}

package/dist/core/loop.d.ts

@@ -0,0 +1,70 @@
+import { type UIMessage, type LanguageModel } from 'ai';
+import { NodesClient } from '@nodes/sdk';
+export interface AgentConfig {
+    nodes: NodesClient;
+    /** Agent slug (e.g. "nodes/my-agent") or user ID */
+    agent: string;
+    model?: string;
+    /** Human user ID — extracted from user-scoped API key (nodes_<userId>_<secret>) */
+    userId?: string;
+    /** One-shot prompt — run and exit */
+    prompt?: string;
+    /** Existing chat node ID to resume */
+    nodeId?: string;
+}
+export interface AgentEnv {
+    modelId: string;
+    model: LanguageModel;
+    provider: string;
+    allTools: Record<string, any>;
+    systemPrompt: string;
+    chatsNodeId?: string;
+    agentName: string;
+}
+export declare function loadAgentEnv(config: AgentConfig): Promise<AgentEnv>;
+export interface TurnOptions {
+    prompt?: string;
+    messages?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    abortSignal?: AbortSignal;
+    onTextDelta?: (delta: string) => void;
+    onReasoningDelta?: (delta: string) => void;
+    onToolCallStart?: (toolName: string, args: unknown) => void;
+    onToolCall?: (toolName: string, args: unknown, result: unknown) => void;
+}
+interface UsageMetadata {
+    provider?: string;
+    model?: string;
+    totalUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        reasoningTokens?: number;
+        cachedInputTokens?: number;
+    };
+    timings?: {
+        totalMs?: number;
+    };
+}
+interface TurnResult {
+    text: string;
+    toolCalls: number;
+    parts: UIMessage['parts'];
+    metadata: UsageMetadata;
+}
+export declare function runTurn(env: AgentEnv, options: TurnOptions): Promise<TurnResult>;
+export declare function runOnce(config: AgentConfig): Promise<{
+    ok: boolean;
+    error: string;
+    chatNodeId?: undefined;
+    toolCalls?: undefined;
+} | {
+    ok: boolean;
+    chatNodeId: string;
+    toolCalls: number;
+    error?: undefined;
+}>;
+export declare function interactive(config: AgentConfig): Promise<void>;
+export {};

package/dist/core/loop.js

@@ -0,0 +1,253 @@
+import { streamText, hasToolCall, stepCountIs, readUIMessageStream } from 'ai';
+import { localTools } from './tools.js';
+import { loadRemoteTools } from './remote-tools.js';
+import { resolveModel } from './providers.js';
+const DEFAULT_MAX_STEPS = 50;
+const MAX_STEPS = Number(process.env.MAX_STEPS) || DEFAULT_MAX_STEPS;
+const stopWhen = [hasToolCall('ai_end'), hasToolCall('ai_buttons'), stepCountIs(MAX_STEPS)];
+export async function loadAgentEnv(config) {
+    const { nodes, agent } = config;
+    const agentInfo = await nodes.ai.readAgent(agent, { include: ['systemPrompt'] });
+    const provider = agentInfo.ai?.provider || 'gateway';
+    const modelId = config.model || agentInfo.ai?.model || 'google/gemini-2.5-flash';
+    const model = resolveModel(provider, modelId);
+    const remoteTools = await loadRemoteTools(nodes, agentInfo.id);
+    const allTools = { ...localTools, ...remoteTools };
+    const systemPrompt = agentInfo.systemPrompt || 'You are a helpful AI agent.';
+    return {
+        modelId,
+        model,
+        provider,
+        allTools,
+        systemPrompt,
+        chatsNodeId: agentInfo.ai?.chatsNode,
+        agentName: agentInfo.name,
+    };
+}
+export async function runTurn(env, options) {
+    const startMs = Date.now();
+    const result = streamText({
+        model: env.model,
+        system: env.systemPrompt,
+        tools: env.allTools,
+        stopWhen,
+        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        ...(options.messages
+            ? { messages: options.messages }
+            : { prompt: options.prompt || '' }),
+    });
+    // Use native AI SDK UIMessage stream — same format the Nodes UI uses
+    const uiStream = readUIMessageStream({ stream: result.toUIMessageStream() });
+    let message;
+    let prevTextLen = 0;
+    let prevReasoningLen = 0;
+    const seenToolStarts = new Set();
+    const seenToolResults = new Set();
+    for await (const snapshot of uiStream) {
+        message = snapshot;
+        // Stream text deltas
+        const textParts = snapshot.parts.filter(p => p.type === 'text');
+        const currentText = textParts.map(p => p.text).join('');
+        if (currentText.length > prevTextLen) {
+            options.onTextDelta?.(currentText.slice(prevTextLen));
+            prevTextLen = currentText.length;
+        }
+        // Stream reasoning deltas
+        if (options.onReasoningDelta) {
+            const reasoningParts = snapshot.parts.filter(p => p.type === 'reasoning');
+            const currentReasoning = reasoningParts.map(p => p.text).join('');
+            if (currentReasoning.length > prevReasoningLen) {
+                options.onReasoningDelta(currentReasoning.slice(prevReasoningLen));
+                prevReasoningLen = currentReasoning.length;
+            }
+        }
+        // Detect tool starts and completions
+        for (const part of snapshot.parts) {
+            const p = part;
+            if (!p.type.startsWith('tool-') || !p.toolCallId)
+                continue;
+            // Tool START (any state before output-available)
+            if (!seenToolStarts.has(p.toolCallId) && p.state !== 'output-available') {
+                seenToolStarts.add(p.toolCallId);
+                options.onToolCallStart?.(p.type.replace('tool-', ''), p.input);
+            }
+            // Tool COMPLETE
+            if (p.state === 'output-available' && !seenToolResults.has(p.toolCallId)) {
+                seenToolResults.add(p.toolCallId);
+                options.onToolCall?.(p.type.replace('tool-', ''), p.input, p.output);
+            }
+        }
+    }
+    const totalMs = Date.now() - startMs;
+    const usage = await result.totalUsage;
+    const parts = message?.parts || [];
+    const fullText = parts
+        .filter(p => p.type === 'text')
+        .map(p => p.text)
+        .join('');
+    const toolCalls = parts.filter(p => p.type.startsWith('tool-')).length;
+    return {
+        text: fullText,
+        toolCalls,
+        parts,
+        metadata: {
+            provider: env.provider,
+            model: env.modelId,
+            totalUsage: {
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                totalTokens: usage.totalTokens,
+                reasoningTokens: usage.outputTokenDetails?.reasoningTokens,
+                cachedInputTokens: usage.inputTokenDetails?.cacheReadTokens,
+            },
+            timings: { totalMs },
+        },
+    };
+}
+// --- One-shot mode (-p "prompt") ---
+export async function runOnce(config) {
+    const { nodes, prompt } = config;
+    if (!prompt) {
+        console.error('Error: prompt is required for one-shot mode (-p "prompt").');
+        return { ok: false, error: 'No prompt provided' };
+    }
+    console.log('Loading agent config...');
+    const env = await loadAgentEnv(config);
+    if (!env.chatsNodeId) {
+        console.error('No chatsNode on agent. Open agent in UI first to initialize.');
+        return { ok: false, error: 'No chatsNode found on agent AI side' };
+    }
+    console.log(`Agent: "${env.agentName}" | Model: ${env.modelId} | Tools: ${Object.keys(env.allTools).length}`);
+    // Create or reuse chat + write user message
+    const userResult = await nodes.chat.write({
+        ...(config.nodeId ? { nodeId: config.nodeId } : { parentId: env.chatsNodeId }),
+        role: 'user',
+        text: prompt,
+        ...(config.userId ? { createdBy: config.userId } : {}),
+    });
+    if (!userResult?.chatNodeId) {
+        console.error('Failed to create chat:', userResult?.error);
+        return { ok: false, error: userResult?.error || 'Failed to create chat' };
+    }
+    console.log(`Chat: ${userResult.chatNodeId}`);
+    // Load history if resuming existing chat
+    const messages = [];
+    if (config.nodeId) {
+        try {
+            const history = await nodes.chat.read(config.nodeId);
+            if (history?.docs) {
+                for (const doc of history.docs) {
+                    const msg = doc;
+                    const role = msg.sides?.message?.role;
+                    const text = msg.sides?.message?.parts?.filter(p => p.type === 'text').map(p => p.text || '').join('') || '';
+                    if (role && (role === 'user' || role === 'assistant') && text) {
+                        messages.push({ role, content: text });
+                    }
+                }
+                console.log(`Loaded ${messages.length} messages from history`);
+            }
+        }
+        catch (err) {
+            console.warn('Could not load chat history:', err.message);
+        }
+    }
+    // Add current prompt
+    messages.push({ role: 'user', content: prompt });
+    // Run turn
+    const turn = await runTurn(env, {
+        messages,
+        onTextDelta: (delta) => process.stdout.write(delta),
+        onToolCall: (name) => console.log(`\n  [tool: ${name}]`),
+    });
+    if (turn.text)
+        process.stdout.write('\n');
+    console.log(`\nDone. ${turn.text.length} chars, ${turn.toolCalls} tool calls.`);
+    // Save assistant message to Nodes (with usage metadata for billing)
+    await nodes.chat.write({
+        nodeId: userResult.chatNodeId,
+        role: 'assistant',
+        text: turn.text,
+        parts: turn.parts,
+        _metadata: turn.metadata,
+    });
+    return { ok: true, chatNodeId: userResult.chatNodeId, toolCalls: turn.toolCalls };
+}
+// --- Interactive mode ---
+export async function interactive(config) {
+    const { nodes } = config;
+    const readline = await import('readline');
+    console.log('Loading agent config...');
+    const env = await loadAgentEnv(config);
+    if (!env.chatsNodeId) {
+        console.error('No chatsNode on agent. Open agent in UI first to initialize.');
+        return;
+    }
+    console.log(`Agent: "${env.agentName}" | Model: ${env.modelId} | Tools: ${Object.keys(env.allTools).length}`);
+    const messages = [];
+    let chatNodeId = config.nodeId;
+    // Resume existing chat — load history
+    if (chatNodeId) {
+        try {
+            const history = await nodes.chat.read(chatNodeId);
+            if (history?.docs) {
+                for (const doc of history.docs) {
+                    const msg = doc;
+                    const role = msg.sides?.message?.role;
+                    const text = msg.sides?.message?.parts?.filter(p => p.type === 'text').map(p => p.text || '').join('') || '';
+                    if (role && (role === 'user' || role === 'assistant') && text) {
+                        messages.push({ role, content: text });
+                    }
+                }
+                console.log(`Resumed chat ${chatNodeId} (${messages.length} messages)`);
+            }
+        }
+        catch (err) {
+            console.warn('Could not load chat history:', err.message);
+        }
+    }
+    console.log('Type your message. Ctrl+C to exit.\n');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = () => new Promise((resolve) => {
+        rl.question('> ', (answer) => resolve(answer));
+    });
+    while (true) {
+        const input = await ask();
+        if (!input.trim())
+            continue;
+        // Sync user message to Nodes (creates chat on first message)
+        const userResult = await nodes.chat.write({
+            ...(chatNodeId ? { nodeId: chatNodeId } : { parentId: env.chatsNodeId }),
+            role: 'user',
+            text: input,
+            ...(config.userId ? { createdBy: config.userId } : {}),
+        });
+        if (!userResult?.chatNodeId) {
+            console.error('Failed to sync user message:', userResult?.error);
+        }
+        else {
+            chatNodeId = userResult.chatNodeId;
+        }
+        messages.push({ role: 'user', content: input });
+        const turn = await runTurn(env, {
+            messages,
+            onTextDelta: (delta) => process.stdout.write(delta),
+            onToolCall: (name, _args, result) => {
+                const preview = JSON.stringify(result).slice(0, 120);
+                console.log(`\n  [tool: ${name}] ${preview}${JSON.stringify(result).length > 120 ? '...' : ''}`);
+            },
+        });
+        if (turn.text)
+            process.stdout.write('\n\n');
+        // Sync assistant message to Nodes (with usage metadata for billing)
+        if (chatNodeId) {
+            await nodes.chat.write({
+                nodeId: chatNodeId,
+                role: 'assistant',
+                text: turn.text,
+                parts: turn.parts,
+                _metadata: turn.metadata,
+            });
+        }
+        messages.push({ role: 'assistant', content: turn.text || '(tool calls only)' });
+    }
+}

package/dist/core/providers.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageModel } from 'ai';
+export declare function resolveModel(provider: string, modelId: string): LanguageModel;

package/dist/core/providers.js

@@ -0,0 +1,17 @@
+import { createGateway } from '@ai-sdk/gateway';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+export function resolveModel(provider, modelId) {
+    switch (provider) {
+        case 'openai':
+            return createOpenAI({ apiKey: process.env.OPENAI_API_KEY }).languageModel(modelId);
+        case 'anthropic':
+            return createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }).languageModel(modelId);
+        case 'google':
+            return createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY }).languageModel(modelId);
+        case 'gateway':
+        default:
+            return createGateway({ apiKey: process.env.GATEWAY_API_KEY }).languageModel(modelId);
+    }
+}

package/dist/core/remote-tools.d.ts

@@ -0,0 +1,6 @@
+import type { NodesClient } from '@nodes/sdk';
+/**
+ * Fetch agent's Nodes tools and convert to AI SDK tool format.
+ * Each tool's execute calls back to Nodes via MCP.
+ */
+export declare function loadRemoteTools(nodes: NodesClient, agentId: string): Promise<Record<string, import("ai").Tool<never, never>>>;

package/dist/core/remote-tools.js

@@ -0,0 +1,22 @@
+import { tool, jsonSchema } from 'ai';
+/**
+ * Fetch agent's Nodes tools and convert to AI SDK tool format.
+ * Each tool's execute calls back to Nodes via MCP.
+ */
+export async function loadRemoteTools(nodes, agentId) {
+    const { tools: toolDefs } = await nodes.agents.tools(agentId);
+    const tools = {};
+    for (const def of toolDefs) {
+        const schema = def.inputSchema || { type: 'object', properties: {} };
+        // @ts-expect-error AI SDK tool() overload resolution
+        tools[def.name] = tool({
+            description: def.description,
+            parameters: jsonSchema(schema),
+            // @ts-expect-error AI SDK tool() overload resolution
+            execute: async (args) => {
+                return nodes.callTool(def.name, args);
+            },
+        });
+    }
+    return tools;
+}

package/dist/core/serve.d.ts

@@ -0,0 +1,5 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+export interface ServeOptions {
+    port?: number;
+}
+export declare function serve(options?: ServeOptions): Promise<import("http").Server<typeof IncomingMessage, typeof ServerResponse>>;

package/dist/core/serve.js

@@ -0,0 +1,113 @@
+import { createRequire } from 'module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { execBash, execReadFile, execWriteFile } from './tools.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+export async function serve(options = {}) {
+    const port = options.port || Number(process.env.PORT) || 8788;
+    // Create MCP server
+    const mcp = new McpServer({
+        name: 'nodes-agent',
+        version: pkg.version,
+    });
+    // --- Local tools (shared logic from tools.ts) ---
+    mcp.tool('bash', 'Execute a bash command and return stdout/stderr', {
+        command: z.string().describe('The bash command to execute'),
+        cwd: z.string().optional().describe('Working directory'),
+    }, async ({ command, cwd }) => {
+        const result = await execBash(command, cwd);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    mcp.tool('read_file', 'Read a file from the filesystem', {
+        path: z.string().describe('Absolute or relative file path'),
+    }, async ({ path }) => {
+        const result = execReadFile(path);
+        const isError = 'error' in result;
+        return { content: [{ type: 'text', text: isError ? JSON.stringify(result) : result.content }], isError };
+    });
+    mcp.tool('write_file', 'Write content to a file (creates directories if needed)', {
+        path: z.string().describe('Absolute or relative file path'),
+        content: z.string().describe('File content to write'),
+    }, async ({ path, content }) => {
+        const result = execWriteFile(path, content);
+        const isError = 'error' in result;
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], isError };
+    });
+    // --- Transport ---
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless
+    });
+    await mcp.connect(transport);
+    // --- Auth ---
+    const apiKey = process.env.AGENT_API_KEY || '';
+    if (!apiKey) {
+        console.warn('[serve] WARNING: AGENT_API_KEY not set — server is open to anyone!');
+    }
+    function checkAuth(req) {
+        if (!apiKey)
+            return true; // no key configured = open
+        const authHeader = req.headers.authorization;
+        if (!authHeader?.startsWith('Bearer '))
+            return false;
+        return authHeader.slice(7) === apiKey;
+    }
+    // --- HTTP server ---
+    const httpServer = createServer(async (req, res) => {
+        // CORS for browser-based MCP clients
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, mcp-session-id');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Route /mcp to the transport
+        const url = new URL(req.url || '/', `http://localhost:${port}`);
+        if (url.pathname === '/mcp') {
+            if (!checkAuth(req)) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized' }));
+                return;
+            }
+            // Parse JSON body for POST
+            if (req.method === 'POST') {
+                const chunks = [];
+                for await (const chunk of req)
+                    chunks.push(chunk);
+                let body;
+                try {
+                    body = JSON.parse(Buffer.concat(chunks).toString());
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                    return;
+                }
+                await transport.handleRequest(req, res, body);
+            }
+            else {
+                await transport.handleRequest(req, res);
+            }
+            return;
+        }
+        // Health check
+        if (url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', name: 'nodes-agent', version: pkg.version }));
+            return;
+        }
+        res.writeHead(404);
+        res.end('Not found');
+    });
+    httpServer.listen(port, () => {
+        console.log(`[serve] Nodes Agent MCP server listening on http://0.0.0.0:${port}/mcp`);
+        console.log(`[serve] Health check: http://localhost:${port}/health`);
+        console.log(`[serve] Tools: bash, read_file, write_file`);
+        console.log(`[serve] Auth: ${apiKey ? 'Bearer token required' : 'OPEN (no AGENT_API_KEY set)'}`);
+    });
+    return httpServer;
+}

package/dist/core/tools.d.ts

@@ -0,0 +1,48 @@
+export declare function execBash(command: string, cwd?: string): Promise<{
+    stdout: string;
+    stderr?: string;
+    exitCode: number;
+}>;
+export declare function execReadFile(path: string): {
+    content: string;
+    error?: undefined;
+} | {
+    error: string;
+    content?: undefined;
+};
+export declare function execWriteFile(path: string, content: string): {
+    success: boolean;
+    error?: undefined;
+} | {
+    error: string;
+    success?: undefined;
+};
+export declare const localTools: {
+    bash: import("ai").Tool<{
+        command: string;
+        cwd?: string;
+    }, {
+        stdout: string;
+        stderr?: string;
+        exitCode: number;
+    }>;
+    read_file: import("ai").Tool<{
+        path: string;
+    }, {
+        content: string;
+        error?: undefined;
+    } | {
+        error: string;
+        content?: undefined;
+    }>;
+    write_file: import("ai").Tool<{
+        path: string;
+        content: string;
+    }, {
+        success: boolean;
+        error?: undefined;
+    } | {
+        error: string;
+        success?: undefined;
+    }>;
+};

package/dist/core/tools.js

@@ -0,0 +1,81 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'child_process';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+const MAX_OUTPUT = 30_000;
+function truncate(output) {
+    if (output.length <= MAX_OUTPUT)
+        return output;
+    return output.slice(0, MAX_OUTPUT) + `\n\n[truncated: ${output.length - MAX_OUTPUT} characters removed]`;
+}
+// --- Shared execution logic ---
+export function execBash(command, cwd) {
+    return new Promise((resolve) => {
+        exec(command, {
+            cwd: cwd || process.cwd(),
+            encoding: 'utf-8',
+            timeout: 60_000,
+            maxBuffer: 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                resolve({
+                    stdout: truncate(stdout || ''),
+                    stderr: truncate(stderr || ''),
+                    exitCode: error.code != null ? (typeof error.code === 'number' ? error.code : 1) : 1,
+                });
+            }
+            else {
+                resolve({ stdout: truncate(stdout), exitCode: 0 });
+            }
+        });
+    });
+}
+export function execReadFile(path) {
+    try {
+        const content = readFileSync(path, 'utf-8');
+        return { content };
+    }
+    catch (err) {
+        return { error: err.message };
+    }
+}
+export function execWriteFile(path, content) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content, 'utf-8');
+        return { success: true };
+    }
+    catch (err) {
+        return { error: err.message };
+    }
+}
+// --- AI SDK tool wrappers ---
+export const localTools = {
+    bash: tool({
+        description: 'Execute a bash command and return stdout/stderr',
+        parameters: z.object({
+            command: z.string().describe('The bash command to execute'),
+            cwd: z.string().optional().describe('Working directory'),
+        }),
+        // @ts-expect-error AI SDK tool() overload resolution
+        execute: async ({ command, cwd }) => execBash(command, cwd),
+    }),
+    read_file: tool({
+        description: 'Read a file from the filesystem',
+        parameters: z.object({
+            path: z.string().describe('Absolute or relative file path'),
+        }),
+        // @ts-expect-error AI SDK tool() overload resolution
+        execute: async ({ path }) => execReadFile(path),
+    }),
+    write_file: tool({
+        description: 'Write content to a file (creates directories if needed)',
+        parameters: z.object({
+            path: z.string().describe('Absolute or relative file path'),
+            content: z.string().describe('File content to write'),
+        }),
+        // @ts-expect-error AI SDK tool() overload resolution
+        execute: async ({ path, content }) => execWriteFile(path, content),
+    }),
+};

package/dist/core/tui-chat.d.ts

@@ -0,0 +1,2 @@
+import { type AgentConfig } from './loop.js';
+export declare function interactiveTUI(config: AgentConfig): Promise<void>;

package/dist/core/tui-chat.js

@@ -0,0 +1,324 @@
+import { createRequire } from 'module';
+import { ProcessTerminal, TUI, Container, Editor, Markdown, Loader, Text, Spacer, Box, matchesKey } from '@mariozechner/pi-tui';
+import pc from 'picocolors';
+import { loadAgentEnv, runTurn } from './loop.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+// --- Background color helpers (24-bit ANSI) ---
+function bgHex(hex) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return (text) => `\x1b[48;2;${r};${g};${b}m${text}\x1b[49m`;
+}
+const toolSuccessBg = bgHex('#283228');
+const toolErrorBg = bgHex('#3c2828');
+const toolPendingBg = bgHex('#282832');
+const userMsgBg = bgHex('#343541');
+// --- Editor theme ---
+const selectListTheme = {
+    selectedPrefix: pc.cyan,
+    selectedText: pc.bold,
+    description: pc.dim,
+    scrollInfo: pc.dim,
+    noMatch: pc.dim,
+};
+const editorTheme = {
+    borderColor: pc.dim,
+    selectList: selectListTheme,
+};
+function toolHeader(name, args) {
+    const a = (args && typeof args === 'object' ? args : {});
+    if (name === 'bash')
+        return pc.bold(`$ ${String(a.command || '...')}`);
+    if (name === 'read_file')
+        return pc.bold('read ') + pc.cyan(String(a.path || '...'));
+    if (name === 'write_file')
+        return pc.bold('write ') + pc.cyan(String(a.path || '...'));
+    const argPairs = Object.entries(a)
+        .map(([k, v]) => {
+        const val = typeof v === 'string' ? (v.length > 60 ? v.slice(0, 60) + '...' : v) : JSON.stringify(v);
+        return `${pc.dim(k)}: ${val}`;
+    })
+        .join('  ');
+    return pc.bold(name) + (argPairs ? '  ' + argPairs : '');
+}
+function toolOutput(name, args, result) {
+    const r = (result && typeof result === 'object' ? result : {});
+    if (name === 'bash') {
+        const stdout = String(r.stdout || '');
+        const stderr = String(r.stderr || '');
+        const output = (stdout + (stderr ? `\n${stderr}` : '')).trim();
+        if (!output)
+            return null;
+        const lines = output.split('\n');
+        const preview = lines.slice(0, 5).map(l => pc.dim(l)).join('\n');
+        const suffix = lines.length > 5 ? pc.dim(`\n... (${lines.length - 5} more lines)`) : '';
+        return preview + suffix;
+    }
+    if (name === 'read_file' || name === 'write_file')
+        return null;
+    const resultStr = JSON.stringify(result);
+    if (!resultStr || resultStr === '{}')
+        return null;
+    const preview = resultStr.length > 200 ? resultStr.slice(0, 200) + '...' : resultStr;
+    return pc.dim(preview);
+}
+function rerenderToolBox(entry, expanded) {
+    const r = (entry.result && typeof entry.result === 'object' ? entry.result : {});
+    const isError = entry.result != null && ('error' in r || ('exitCode' in r && r.exitCode !== 0));
+    const bg = entry.result == null ? toolPendingBg : isError ? toolErrorBg : toolSuccessBg;
+    entry.box.setBgFn(bg);
+    // Clear and rebuild children
+    while (entry.box.children.length > 0)
+        entry.box.removeChild(entry.box.children[0]);
+    entry.box.addChild(new Text(toolHeader(entry.name, entry.args), 0, 0));
+    if (expanded && entry.result != null) {
+        const output = toolOutput(entry.name, entry.args, entry.result);
+        if (output)
+            entry.box.addChild(new Text('\n' + output, 0, 0));
+    }
+}
+// --- Markdown theme using picocolors ---
+const theme = {
+    heading: pc.bold,
+    link: pc.cyan,
+    linkUrl: pc.dim,
+    code: pc.yellow,
+    codeBlock: pc.dim,
+    codeBlockBorder: pc.dim,
+    quote: pc.italic,
+    quoteBorder: pc.dim,
+    hr: pc.dim,
+    listBullet: pc.cyan,
+    bold: pc.bold,
+    italic: pc.italic,
+    strikethrough: pc.strikethrough,
+    underline: pc.underline,
+};
+async function loadChatHistory(nodes, chatNodeId) {
+    const messages = [];
+    const history = await nodes.chat.read(chatNodeId);
+    if (history?.docs) {
+        for (const doc of history.docs) {
+            const msg = doc;
+            const role = msg.sides?.message?.role;
+            const text = msg.sides?.message?.parts?.filter(p => p.type === 'text').map(p => p.text || '').join('') || '';
+            if (role && (role === 'user' || role === 'assistant') && text) {
+                messages.push({ role, content: text });
+            }
+        }
+    }
+    return messages;
+}
+// --- TUI interactive mode ---
+export async function interactiveTUI(config) {
+    const { nodes } = config;
+    // Start TUI immediately — show banner while loading
+    const terminal = new ProcessTerminal();
+    const tui = new TUI(terminal);
+    const version = new Text(pc.bold(pc.cyan('nodes')) + pc.dim(` v${pkg.version}`), 1, 0);
+    const info = new Text(pc.dim('loading...'), 1, 0);
+    const keybindings = new Text(pc.dim('ctrl+c') + pc.gray(' exit/stop') + '  ' +
+        pc.dim('tab') + pc.gray(' expand tools'), 1, 0);
+    const chat = new Container();
+    const editor = new Editor(tui, editorTheme);
+    tui.addChild(version);
+    tui.addChild(info);
+    tui.addChild(keybindings);
+    tui.addChild(new Spacer(1));
+    tui.addChild(chat);
+    tui.addChild(editor);
+    tui.setFocus(editor);
+    // State
+    let abortController;
+    let toolsExpanded = false;
+    const toolEntries = [];
+    const cleanup = () => {
+        tui.stop();
+        nodes.disconnect().catch(() => { });
+        process.exit(0);
+    };
+    tui.addInputListener((data) => {
+        // Ctrl+C: abort if processing, exit otherwise
+        if (data === '\x03' || matchesKey(data, 'ctrl+c')) {
+            const ac = abortController;
+            if (ac) {
+                ac.abort();
+                return { consume: true };
+            }
+            cleanup();
+            return { consume: true };
+        }
+        // Tab: toggle tool expand/collapse
+        if (matchesKey(data, 'tab')) {
+            toolsExpanded = !toolsExpanded;
+            for (const entry of toolEntries) {
+                rerenderToolBox(entry, toolsExpanded);
+            }
+            tui.requestRender();
+            return { consume: true };
+        }
+        return undefined;
+    });
+    tui.start();
+    // Load config in background
+    const env = await loadAgentEnv(config);
+    if (!env.chatsNodeId) {
+        info.setText(pc.red('No chatsNode on agent. Open agent in UI first to initialize.'));
+        tui.requestRender();
+        return;
+    }
+    info.setText(pc.dim(`${env.agentName} · ${env.modelId} · ${Object.keys(env.allTools).length} tools`));
+    tui.requestRender();
+    // State
+    const messages = [];
+    let chatNodeId = config.nodeId;
+    // Resume existing chat
+    if (chatNodeId) {
+        try {
+            const loaded = await loadChatHistory(nodes, chatNodeId);
+            messages.push(...loaded);
+            for (const msg of loaded) {
+                chat.addChild(new Spacer(1));
+                if (msg.role === 'user') {
+                    chat.addChild(new Markdown(msg.content, 1, 1, theme, { bgColor: userMsgBg }));
+                }
+                else {
+                    chat.addChild(new Markdown(msg.content, 0, 0, theme));
+                }
+            }
+            tui.requestRender();
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Handle submit
+    editor.onSubmit = (text) => {
+        handleSubmit(text).catch((err) => {
+            chat.addChild(new Text(pc.red(`Error: ${err.message}`), 0, 0));
+            abortController = undefined;
+            tui.requestRender();
+        });
+    };
+    async function handleSubmit(text) {
+        if (!text.trim() || abortController)
+            return;
+        editor.addToHistory(text);
+        editor.setText('');
+        // Show user message
+        chat.addChild(new Spacer(1));
+        chat.addChild(new Markdown(text, 1, 1, theme, { bgColor: userMsgBg }));
+        chat.addChild(new Spacer(1));
+        // Show loader
+        const loader = new Loader(tui, pc.cyan, pc.dim, 'Thinking...');
+        chat.addChild(loader);
+        tui.requestRender();
+        // Sync user message to Nodes
+        const userResult = await nodes.chat.write({
+            ...(chatNodeId ? { nodeId: chatNodeId } : { parentId: env.chatsNodeId }),
+            role: 'user',
+            text,
+            ...(config.userId ? { createdBy: config.userId } : {}),
+        });
+        if (userResult?.chatNodeId)
+            chatNodeId = userResult.chatNodeId;
+        messages.push({ role: 'user', content: text });
+        // Stream response
+        const md = new Markdown('', 0, 0, theme);
+        const reasoningText = new Text('', 1, 0);
+        let accumulated = '';
+        let accumulatedReasoning = '';
+        let reasoningAdded = false;
+        const turnToolEntries = [];
+        const controller = new AbortController();
+        abortController = controller;
+        function removeLoader() {
+            if (chat.children.includes(loader)) {
+                loader.stop();
+                chat.removeChild(loader);
+            }
+        }
+        function insertBeforeLoaderOrMd(component) {
+            const loaderIdx = chat.children.indexOf(loader);
+            const mdIdx = chat.children.indexOf(md);
+            const insertBefore = loaderIdx !== -1 ? loaderIdx : mdIdx !== -1 ? mdIdx : -1;
+            if (insertBefore !== -1) {
+                chat.children.splice(insertBefore, 0, component);
+            }
+            else {
+                chat.addChild(component);
+            }
+        }
+        const turn = await runTurn(env, {
+            messages,
+            abortSignal: controller.signal,
+            onReasoningDelta: (delta) => {
+                accumulatedReasoning += delta;
+                reasoningText.setText(pc.italic(pc.gray(accumulatedReasoning)));
+                if (!reasoningAdded) {
+                    reasoningAdded = true;
+                    removeLoader();
+                    chat.addChild(reasoningText);
+                    chat.addChild(loader);
+                }
+                tui.requestRender();
+            },
+            onTextDelta: (delta) => {
+                accumulated += delta;
+                if (!chat.children.includes(md)) {
+                    removeLoader();
+                    chat.addChild(md);
+                }
+                md.setText(accumulated);
+                tui.requestRender();
+            },
+            onToolCallStart: (name, args) => {
+                const box = new Box(1, 0, toolPendingBg);
+                box.addChild(new Text(toolHeader(name, args), 0, 0));
+                const entry = { name, args, box };
+                turnToolEntries.push(entry);
+                toolEntries.push(entry);
+                insertBeforeLoaderOrMd(box);
+                tui.requestRender();
+            },
+            onToolCall: (_name, args, result) => {
+                // Find matching pending entry (first without result)
+                const entry = turnToolEntries.find(e => !e.result);
+                if (entry) {
+                    entry.args = args;
+                    entry.result = result;
+                    rerenderToolBox(entry, toolsExpanded);
+                }
+                // Re-show loader after tool completes (more tools may follow)
+                if (!chat.children.includes(loader) && !chat.children.includes(md)) {
+                    chat.addChild(loader);
+                }
+                tui.requestRender();
+            },
+        });
+        // Ensure loader is cleaned up
+        removeLoader();
+        if (accumulated && !chat.children.includes(md))
+            chat.addChild(md);
+        // Show aborted indicator
+        if (controller.signal.aborted) {
+            chat.addChild(new Text(pc.dim('(aborted)'), 1, 0));
+        }
+        chat.addChild(new Spacer(1));
+        // Sync assistant message to Nodes
+        if (chatNodeId && turn.text) {
+            await nodes.chat.write({
+                nodeId: chatNodeId,
+                role: 'assistant',
+                text: turn.text,
+                parts: turn.parts,
+                _metadata: turn.metadata,
+            });
+        }
+        messages.push({ role: 'assistant', content: turn.text || '(tool calls only)' });
+        abortController = undefined;
+        tui.requestRender();
+    }
+}

package/dist/core/ui.d.ts

@@ -0,0 +1,12 @@
+export declare const c: {
+    dim: import("picocolors/types").Formatter;
+    bold: import("picocolors/types").Formatter;
+    cyan: import("picocolors/types").Formatter;
+    green: import("picocolors/types").Formatter;
+    yellow: import("picocolors/types").Formatter;
+    red: import("picocolors/types").Formatter;
+    magenta: import("picocolors/types").Formatter;
+};
+export declare function spinner(message: string): {
+    stop(finalMessage?: string): void;
+};

package/dist/core/ui.js

@@ -0,0 +1,27 @@
+import pc from 'picocolors';
+// --- Colors ---
+export const c = {
+    dim: pc.dim,
+    bold: pc.bold,
+    cyan: pc.cyan,
+    green: pc.green,
+    yellow: pc.yellow,
+    red: pc.red,
+    magenta: pc.magenta,
+};
+// --- Spinner ---
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export function spinner(message) {
+    let i = 0;
+    const id = setInterval(() => {
+        process.stderr.write(`\r${c.cyan(FRAMES[i++ % FRAMES.length])} ${c.dim(message)}`);
+    }, 80);
+    return {
+        stop(finalMessage) {
+            clearInterval(id);
+            process.stderr.write(`\r\x1b[2K`); // clear line
+            if (finalMessage)
+                console.error(finalMessage);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { runOnce, interactive } from './core/loop.js';
+export { localTools } from './core/tools.js';
+export type { AgentConfig } from './core/loop.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { runOnce, interactive } from './core/loop.js';
+export { localTools } from './core/tools.js';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nodes/agent",
+  "version": "0.0.1",
+  "description": "Autonomous AI agent runtime for Nodes",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nodes": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "3.0.47",
+    "@ai-sdk/gateway": "3.0.46",
+    "@ai-sdk/google": "3.0.31",
+    "@ai-sdk/openai": "3.0.33",
+    "@mariozechner/pi-tui": "^0.55.0",
+    "@modelcontextprotocol/sdk": "1.23.0",
+    "ai": "6.0.86",
+    "picocolors": "^1.1.1",
+    "zod": "3.25.76",
+    "@nodes/sdk": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx --env-file=.env src/cli.ts",
+    "prompt": "tsx --env-file=.env src/cli.ts -p",
+    "serve": "tsx --env-file=.env src/cli.ts --serve",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run src/tests/run-once.test.ts"
+  }
+}