@aragon-agent/core 0.1.3

package/dist/llm/providers/openai.js

@@ -0,0 +1,353 @@
+/**
+ * OpenAI Chat Completions adapter.
+ *
+ * Handles all OpenAI-compatible APIs: OpenAI, xAI, Groq, DeepSeek, Cerebras,
+ * Mistral, and any custom endpoint that speaks the same wire format.
+ *
+ * Key challenges this adapter solves:
+ * - Tool call argument chunks arrive incrementally — we accumulate and parse
+ *   the full JSON only when the tool call finishes.
+ * - Multiple tool calls can be in-flight in a single completion chunk.
+ * - The `[DONE]` sentinel terminates the SSE stream.
+ */
+import { LLMError, classifyHttpError, wrapFetchError } from '../provider.js';
+import { parseSSEStream } from '../stream-utils.js';
+import { consumeStream } from '../stream-utils.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+const DEFAULT_MAX_TOKENS = 16384;
+// Model ID patterns to filter out non-chat models
+const NON_CHAT_PATTERNS = [
+    /^text-embedding/i,
+    /^text-moderation/i,
+    /^text-search/i,
+    /^text-similarity/i,
+    /^code-search/i,
+    /^whisper/i,
+    /^tts/i,
+    /^dall-e/i,
+    /^davinci/i,
+    /^curie/i,
+    /^babbage/i,
+    /^ada(?![-])/i,
+    /embedding/i,
+    /moderation/i,
+];
+function isChatModel(id) {
+    return !NON_CHAT_PATTERNS.some((pat) => pat.test(id));
+}
+// ---------------------------------------------------------------------------
+// OpenAI provider
+// ---------------------------------------------------------------------------
+export class OpenAIProvider {
+    id = 'openai';
+    displayName = 'OpenAI';
+    defaultBaseUrl = DEFAULT_BASE_URL;
+    // -----------------------------------------------------------------------
+    // stream
+    // -----------------------------------------------------------------------
+    async *stream(request) {
+        const baseUrl = (request.baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
+        const url = `${baseUrl}/chat/completions`;
+        const body = buildRequestBody(request);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${request.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: request.signal,
+            });
+        }
+        catch (err) {
+            yield { type: 'error', error: wrapFetchError(err, this.id) };
+            return;
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            yield { type: 'error', error: classifyHttpError(response.status, text, this.id) };
+            return;
+        }
+        if (!response.body) {
+            yield { type: 'error', error: new LLMError('Response body is null', this.id, 'network_error', true) };
+            return;
+        }
+        // -- Parse SSE events --
+        const usage = { inputTokens: 0, outputTokens: 0 };
+        const contentBlocks = [];
+        let textAccumulator = '';
+        let stopReason;
+        // Accumulate tool calls by index
+        const toolAccumulators = new Map();
+        try {
+            for await (const sse of parseSSEStream(response.body, request.signal)) {
+                const raw = sse.data.trim();
+                // [DONE] sentinel
+                if (raw === '[DONE]')
+                    break;
+                let data;
+                try {
+                    data = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                // Extract usage if present (some providers include it in the final chunk)
+                const usageData = data.usage;
+                if (usageData) {
+                    usage.inputTokens = usageData.prompt_tokens ?? usage.inputTokens;
+                    usage.outputTokens = usageData.completion_tokens ?? usage.outputTokens;
+                }
+                const choices = data.choices;
+                if (!choices || choices.length === 0)
+                    continue;
+                const choice = choices[0];
+                const delta = choice.delta;
+                const finishReason = choice.finish_reason;
+                if (delta) {
+                    // Text content
+                    const content = delta.content;
+                    if (content) {
+                        textAccumulator += content;
+                        yield { type: 'text_delta', delta: content };
+                    }
+                    // Tool calls
+                    const toolCalls = delta.tool_calls;
+                    if (toolCalls) {
+                        for (const tc of toolCalls) {
+                            const idx = tc.index ?? 0;
+                            const fn = tc.function;
+                            let acc = toolAccumulators.get(idx);
+                            if (!acc) {
+                                acc = {
+                                    index: idx,
+                                    toolCallId: tc.id || `call_${idx}`,
+                                    toolName: fn?.name || '',
+                                    argsJson: '',
+                                    started: false,
+                                };
+                                toolAccumulators.set(idx, acc);
+                            }
+                            // Update name if present in this chunk
+                            if (fn?.name) {
+                                acc.toolName = fn.name;
+                            }
+                            // Emit tool_call_start on first encounter
+                            if (!acc.started && acc.toolName) {
+                                acc.started = true;
+                                yield { type: 'tool_call_start', toolCallId: acc.toolCallId, toolName: acc.toolName };
+                            }
+                            // Accumulate argument fragments
+                            if (fn?.arguments) {
+                                const argChunk = fn.arguments;
+                                acc.argsJson += argChunk;
+                                if (acc.started) {
+                                    yield { type: 'tool_call_delta', toolCallId: acc.toolCallId, argsDelta: argChunk };
+                                }
+                            }
+                        }
+                    }
+                }
+                // Finish reason handling
+                if (finishReason) {
+                    stopReason = mapFinishReason(finishReason);
+                }
+            }
+            // Flush text block
+            if (textAccumulator) {
+                contentBlocks.push({ type: 'text', text: textAccumulator });
+            }
+            // Flush tool calls — parse accumulated args JSON
+            for (const acc of toolAccumulators.values()) {
+                let args = {};
+                try {
+                    args = acc.argsJson ? JSON.parse(acc.argsJson) : {};
+                }
+                catch {
+                    args = { __raw: acc.argsJson };
+                }
+                contentBlocks.push({
+                    type: 'tool_call',
+                    toolCallId: acc.toolCallId,
+                    toolName: acc.toolName,
+                    args,
+                });
+                yield { type: 'tool_call_end', toolCallId: acc.toolCallId, toolName: acc.toolName, args };
+            }
+            const message = {
+                role: 'assistant',
+                content: contentBlocks,
+                usage,
+                stopReason,
+            };
+            yield { type: 'done', message, usage };
+        }
+        catch (err) {
+            yield { type: 'error', error: wrapFetchError(err, this.id) };
+        }
+    }
+    // -----------------------------------------------------------------------
+    // complete
+    // -----------------------------------------------------------------------
+    async complete(request) {
+        return consumeStream(this.stream(request));
+    }
+    // -----------------------------------------------------------------------
+    // listModels
+    // -----------------------------------------------------------------------
+    async listModels(apiKey, baseUrl) {
+        const base = (baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
+        const url = `${base}/models`;
+        try {
+            const res = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!res.ok)
+                return [];
+            const data = await res.json();
+            return (data.data || [])
+                .filter((m) => isChatModel(String(m.id || '')))
+                .map((m) => ({
+                id: String(m.id || ''),
+                name: String(m.id || ''),
+                provider: this.id,
+                contextWindow: 128_000,
+                maxOutputTokens: 16_384,
+                supportsThinking: false,
+                supportsTools: true,
+                supportsImages: /gpt-4|o1|o3/i.test(String(m.id)),
+                cost: { input: 0, output: 0 },
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: request body builder
+// ---------------------------------------------------------------------------
+function buildRequestBody(request) {
+    const messages = convertMessages(request.messages, request.systemPrompt);
+    const body = {
+        model: request.model,
+        messages,
+        stream: true,
+        stream_options: { include_usage: true },
+    };
+    if (request.maxTokens) {
+        body.max_tokens = request.maxTokens;
+    }
+    if (request.temperature !== undefined) {
+        body.temperature = request.temperature;
+    }
+    if (request.stopSequences && request.stopSequences.length > 0) {
+        body.stop = request.stopSequences;
+    }
+    if (request.tools && request.tools.length > 0) {
+        body.tools = request.tools.map(convertToolDefinition);
+    }
+    return body;
+}
+// ---------------------------------------------------------------------------
+// Internal: message format conversion
+// ---------------------------------------------------------------------------
+function convertMessages(messages, systemPrompt) {
+    const result = [];
+    // System prompt as the first message
+    if (systemPrompt) {
+        result.push({ role: 'system', content: systemPrompt });
+    }
+    for (const msg of messages) {
+        switch (msg.role) {
+            case 'user':
+                result.push({
+                    role: 'user',
+                    content: typeof msg.content === 'string'
+                        ? msg.content
+                        : convertContentParts(msg.content),
+                });
+                break;
+            case 'assistant':
+                result.push(convertAssistantMessage(msg));
+                break;
+            case 'tool_result':
+                result.push({
+                    role: 'tool',
+                    tool_call_id: msg.toolCallId,
+                    content: typeof msg.content === 'string'
+                        ? msg.content
+                        : JSON.stringify(msg.content),
+                });
+                break;
+        }
+    }
+    return result;
+}
+function convertContentParts(parts) {
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        return {
+            type: 'image_url',
+            image_url: {
+                url: `data:${part.mediaType};base64,${part.data}`,
+            },
+        };
+    });
+}
+function convertAssistantMessage(msg) {
+    const result = { role: 'assistant' };
+    // Extract text content
+    const textParts = msg.content.filter((b) => b.type === 'text');
+    if (textParts.length > 0) {
+        result.content = textParts.map((b) => b.text).join('');
+    }
+    else {
+        result.content = null;
+    }
+    // Extract tool calls
+    const toolCalls = msg.content.filter((b) => b.type === 'tool_call');
+    if (toolCalls.length > 0) {
+        result.tool_calls = toolCalls.map((tc) => ({
+            id: tc.toolCallId,
+            type: 'function',
+            function: {
+                name: tc.toolName,
+                arguments: JSON.stringify(tc.args),
+            },
+        }));
+    }
+    return result;
+}
+function convertToolDefinition(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: helpers
+// ---------------------------------------------------------------------------
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'stop': return 'end_turn';
+        case 'tool_calls': return 'tool_use';
+        case 'length': return 'max_tokens';
+        default: return 'end_turn';
+    }
+}

package/dist/llm/stream-utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SSE stream parser and convenience helpers for LLM streaming.
+ */
+import type { AssistantMessage, StreamEvent } from './types.js';
+export interface SSEEvent {
+    /** The `event:` field value.  Undefined when omitted by the server. */
+    event?: string;
+    /** The concatenated `data:` field value (may span multiple lines). */
+    data: string;
+    /** The `id:` field value. */
+    id?: string;
+}
+/**
+ * Parse a `ReadableStream<Uint8Array>` (typically `Response.body`) into an
+ * async iterator of {@link SSEEvent} objects.
+ *
+ * Handles:
+ * - Multi-line `data:` fields (concatenated with `\n`)
+ * - `event:` and `id:` fields
+ * - Proper `\n\n` event boundary detection
+ * - Graceful abort via `signal`
+ *
+ * The iterator ends when the stream closes or `signal` fires.
+ */
+export declare function parseSSEStream(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterableIterator<SSEEvent>;
+/**
+ * Consume a StreamEvent iterator and return the final AssistantMessage.
+ *
+ * This is the generic "complete" implementation that any provider can use:
+ * it iterates the stream, discards incremental deltas, and returns the
+ * assembled message from the `done` event.
+ */
+export declare function consumeStream(stream: AsyncIterableIterator<StreamEvent>): Promise<AssistantMessage>;

package/dist/llm/stream-utils.js

@@ -0,0 +1,132 @@
+/**
+ * SSE stream parser and convenience helpers for LLM streaming.
+ */
+// ---------------------------------------------------------------------------
+// Generic SSE parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `ReadableStream<Uint8Array>` (typically `Response.body`) into an
+ * async iterator of {@link SSEEvent} objects.
+ *
+ * Handles:
+ * - Multi-line `data:` fields (concatenated with `\n`)
+ * - `event:` and `id:` fields
+ * - Proper `\n\n` event boundary detection
+ * - Graceful abort via `signal`
+ *
+ * The iterator ends when the stream closes or `signal` fires.
+ */
+export async function* parseSSEStream(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    // Set up abort listener to release the reader
+    const onAbort = () => {
+        reader.cancel().catch(() => { });
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        while (true) {
+            if (signal?.aborted)
+                break;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete events separated by \n\n
+            let boundary;
+            while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+                const rawEvent = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const parsed = parseSSEBlock(rawEvent);
+                if (parsed) {
+                    yield parsed;
+                }
+            }
+        }
+        // Flush any trailing data that wasn't terminated by \n\n
+        if (buffer.trim().length > 0) {
+            const parsed = parseSSEBlock(buffer);
+            if (parsed) {
+                yield parsed;
+            }
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+        reader.releaseLock();
+    }
+}
+/**
+ * Parse a single SSE block (the text between two `\n\n` boundaries) into an
+ * {@link SSEEvent}.  Returns `undefined` for comment-only or empty blocks.
+ */
+function parseSSEBlock(block) {
+    let event;
+    let id;
+    const dataLines = [];
+    for (const line of block.split('\n')) {
+        // Comment lines start with ':'
+        if (line.startsWith(':'))
+            continue;
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1) {
+            // Field with no value — treat field name as the value (per SSE spec)
+            continue;
+        }
+        const field = line.slice(0, colonIdx);
+        // Value starts after ':' — strip a single leading space if present
+        let value = line.slice(colonIdx + 1);
+        if (value.startsWith(' ')) {
+            value = value.slice(1);
+        }
+        switch (field) {
+            case 'event':
+                event = value;
+                break;
+            case 'data':
+                dataLines.push(value);
+                break;
+            case 'id':
+                id = value;
+                break;
+            // 'retry' and unknown fields are ignored
+        }
+    }
+    if (dataLines.length === 0 && event === undefined) {
+        return undefined;
+    }
+    return {
+        event,
+        data: dataLines.join('\n'),
+        id,
+    };
+}
+// ---------------------------------------------------------------------------
+// Convenience: streamLLM / completeLLM
+// ---------------------------------------------------------------------------
+// These are re-exported from providers/index.ts where the ProviderRegistry
+// singleton is available.  Declared here as standalone signatures for the
+// module's public API documentation.
+/**
+ * Consume a StreamEvent iterator and return the final AssistantMessage.
+ *
+ * This is the generic "complete" implementation that any provider can use:
+ * it iterates the stream, discards incremental deltas, and returns the
+ * assembled message from the `done` event.
+ */
+export async function consumeStream(stream) {
+    let result;
+    for await (const event of stream) {
+        if (event.type === 'done') {
+            result = event.message;
+        }
+        else if (event.type === 'error') {
+            throw event.error;
+        }
+    }
+    if (!result) {
+        throw new Error('Stream ended without a done event');
+    }
+    return result;
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Core LLM types — provider-agnostic message, content, and streaming types.
+ *
+ * These types form the universal contract between the provider adapters and
+ * the agent engine.  Every provider adapter converts its native wire format
+ * into these types so the rest of the system never touches provider-specific
+ * structures.
+ */
+export interface TextContentPart {
+    type: 'text';
+    text: string;
+}
+export interface ImageContentPart {
+    type: 'image';
+    mediaType: string;
+    data: string;
+}
+export type ContentPart = TextContentPart | ImageContentPart;
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export interface ThinkingBlock {
+    type: 'thinking';
+    text: string;
+    /** Anthropic thinking block signature — required when sending back in conversation history. */
+    signature?: string;
+}
+export interface ToolCallBlock {
+    type: 'tool_call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolCallBlock;
+export interface UserMessage {
+    role: 'user';
+    content: string | ContentPart[];
+    timestamp?: number;
+}
+export interface AssistantMessage {
+    role: 'assistant';
+    content: ContentBlock[];
+    usage?: TokenUsage;
+    stopReason?: StopReason;
+}
+export interface ToolResultMessage {
+    role: 'tool_result';
+    toolCallId: string;
+    content: string | ContentPart[];
+    isError?: boolean;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    cost?: number;
+}
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+/** Map ThinkingLevel to Anthropic budget_tokens values. */
+export declare const THINKING_BUDGET: Record<ThinkingLevel, number>;
+export interface TextDeltaEvent {
+    type: 'text_delta';
+    delta: string;
+}
+export interface ThinkingStartEvent {
+    type: 'thinking_start';
+}
+export interface ThinkingDeltaEvent {
+    type: 'thinking_delta';
+    delta: string;
+}
+export interface ToolCallStartEvent {
+    type: 'tool_call_start';
+    toolCallId: string;
+    toolName: string;
+}
+export interface ToolCallDeltaEvent {
+    type: 'tool_call_delta';
+    toolCallId: string;
+    argsDelta: string;
+}
+export interface ToolCallEndEvent {
+    type: 'tool_call_end';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface DoneEvent {
+    type: 'done';
+    message: AssistantMessage;
+    usage: TokenUsage;
+}
+export interface ErrorEvent {
+    type: 'error';
+    error: Error;
+}
+export type StreamEvent = TextDeltaEvent | ThinkingStartEvent | ThinkingDeltaEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallEndEvent | DoneEvent | ErrorEvent;
+/** JSON Schema object — kept deliberately loose to avoid coupling to a schema lib. */
+export type JSONSchema = Record<string, unknown>;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+}
+export interface ModelCost {
+    /** Cost per 1M input tokens (USD). */
+    input: number;
+    /** Cost per 1M output tokens (USD). */
+    output: number;
+    /** Cost per 1M cache-read tokens (USD). */
+    cacheRead?: number;
+    /** Cost per 1M cache-write tokens (USD). */
+    cacheWrite?: number;
+}
+export interface ModelInfo {
+    id: string;
+    name: string;
+    provider: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    supportsThinking: boolean;
+    supportsTools: boolean;
+    supportsImages: boolean;
+    cost: ModelCost;
+}

package/dist/llm/types.js

@@ -0,0 +1,17 @@
+/**
+ * Core LLM types — provider-agnostic message, content, and streaming types.
+ *
+ * These types form the universal contract between the provider adapters and
+ * the agent engine.  Every provider adapter converts its native wire format
+ * into these types so the rest of the system never touches provider-specific
+ * structures.
+ */
+/** Map ThinkingLevel to Anthropic budget_tokens values. */
+export const THINKING_BUDGET = {
+    off: 0,
+    minimal: 1024,
+    low: 4096,
+    medium: 10240,
+    high: 32768,
+    xhigh: 65536,
+};

package/dist/sandbox/console-capture.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CodeAct Sandbox — Console Capture
+ *
+ * Captures console.log/warn/error/info calls from inside the isolated-vm
+ * sandbox and buffers them on the host side. Uses synchronous ivm.Reference
+ * callbacks (applySync) so console calls behave naturally in sandbox code.
+ */
+import ivm from 'isolated-vm';
+import type { ConsoleEntry } from './types.js';
+/**
+ * ConsoleCapture intercepts console method calls inside an isolated-vm
+ * Context and stores them as ConsoleEntry records on the host.
+ */
+export declare class ConsoleCapture {
+    private entries;
+    /**
+     * Inject console overrides into the given isolated-vm context.
+     *
+     * Replaces globalThis.console with an object whose log/warn/error/info
+     * methods forward arguments (stringified) to the host via a synchronous
+     * ivm.Reference callback.
+     */
+    inject(context: ivm.Context): Promise<void>;
+    /**
+     * Return all captured console entries and clear the internal buffer.
+     * Typically called after each execute() to collect output.
+     */
+    drain(): ConsoleEntry[];
+}