@aragon-agent/core 0.1.3

package/dist/llm/providers/google.js

@@ -0,0 +1,336 @@
+/**
+ * Google Gemini (Generative AI) adapter.
+ *
+ * Uses `POST /v1beta/models/{model}:streamGenerateContent?alt=sse` for
+ * streaming and maps the chunked response into unified StreamEvents.
+ *
+ * Key differences from Anthropic/OpenAI:
+ * - Tool calls (functionCall) arrive as complete objects in a single chunk,
+ *   not incrementally — so we emit tool_call_start + tool_call_end together.
+ * - System instructions use a dedicated `system_instruction` field.
+ * - The API key is passed as a query parameter, not a header.
+ */
+import { randomUUID } from 'node:crypto';
+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://generativelanguage.googleapis.com';
+// ---------------------------------------------------------------------------
+// Google provider
+// ---------------------------------------------------------------------------
+export class GoogleProvider {
+    id = 'google';
+    displayName = 'Google';
+    defaultBaseUrl = DEFAULT_BASE_URL;
+    // -----------------------------------------------------------------------
+    // stream
+    // -----------------------------------------------------------------------
+    async *stream(request) {
+        const baseUrl = (request.baseUrl || this.defaultBaseUrl).replace(/\/+$/, '');
+        const url = `${baseUrl}/v1beta/models/${request.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(request.apiKey)}`;
+        const body = buildRequestBody(request);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                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;
+        try {
+            for await (const sse of parseSSEStream(response.body, request.signal)) {
+                const raw = sse.data.trim();
+                if (!raw)
+                    continue;
+                let data;
+                try {
+                    data = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                }
+                // Usage metadata
+                const usageMeta = data.usageMetadata;
+                if (usageMeta) {
+                    usage.inputTokens = usageMeta.promptTokenCount ?? usage.inputTokens;
+                    usage.outputTokens = usageMeta.candidatesTokenCount ?? usage.outputTokens;
+                }
+                // Candidates
+                const candidates = data.candidates;
+                if (!candidates || candidates.length === 0)
+                    continue;
+                const candidate = candidates[0];
+                // Finish reason
+                const finishReason = candidate.finishReason;
+                if (finishReason) {
+                    stopReason = mapFinishReason(finishReason);
+                }
+                const content = candidate.content;
+                if (!content)
+                    continue;
+                const parts = content.parts;
+                if (!parts)
+                    continue;
+                for (const part of parts) {
+                    // Text part
+                    if (typeof part.text === 'string') {
+                        textAccumulator += part.text;
+                        yield { type: 'text_delta', delta: part.text };
+                    }
+                    // Function call — arrives complete in a single chunk
+                    const functionCall = part.functionCall;
+                    if (functionCall) {
+                        const toolName = functionCall.name || '';
+                        const args = functionCall.args || {};
+                        const toolCallId = `call_${randomUUID().slice(0, 8)}`;
+                        yield { type: 'tool_call_start', toolCallId, toolName };
+                        yield { type: 'tool_call_end', toolCallId, toolName, args };
+                        contentBlocks.push({
+                            type: 'tool_call',
+                            toolCallId,
+                            toolName,
+                            args,
+                        });
+                    }
+                }
+            }
+            // Flush text
+            if (textAccumulator) {
+                contentBlocks.push({ type: 'text', text: textAccumulator });
+            }
+            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}/v1beta/models?key=${encodeURIComponent(apiKey)}`;
+        try {
+            const res = await fetch(url, {
+                method: 'GET',
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!res.ok)
+                return [];
+            const data = await res.json();
+            return (data.models || [])
+                .filter((m) => {
+                const methods = (m.supportedGenerationMethods || []);
+                return methods.includes('generateContent') || methods.includes('streamGenerateContent');
+            })
+                .map((m) => {
+                const id = String(m.name || '').replace(/^models\//, '');
+                return {
+                    id,
+                    name: String(m.displayName || id),
+                    provider: this.id,
+                    contextWindow: m.inputTokenLimit || 128_000,
+                    maxOutputTokens: m.outputTokenLimit || 8192,
+                    supportsThinking: false,
+                    supportsTools: true,
+                    supportsImages: true,
+                    cost: { input: 0, output: 0 },
+                };
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal: request body builder
+// ---------------------------------------------------------------------------
+function buildRequestBody(request) {
+    const body = {
+        contents: convertMessages(request.messages),
+    };
+    if (request.systemPrompt) {
+        body.system_instruction = {
+            parts: [{ text: request.systemPrompt }],
+        };
+    }
+    if (request.tools && request.tools.length > 0) {
+        body.tools = [
+            {
+                functionDeclarations: request.tools.map(convertToolDefinition),
+            },
+        ];
+    }
+    // Generation config
+    const genConfig = {};
+    if (request.maxTokens) {
+        genConfig.maxOutputTokens = request.maxTokens;
+    }
+    if (request.temperature !== undefined) {
+        genConfig.temperature = request.temperature;
+    }
+    if (request.stopSequences && request.stopSequences.length > 0) {
+        genConfig.stopSequences = request.stopSequences;
+    }
+    if (Object.keys(genConfig).length > 0) {
+        body.generationConfig = genConfig;
+    }
+    return body;
+}
+// ---------------------------------------------------------------------------
+// Internal: message format conversion
+// ---------------------------------------------------------------------------
+function convertMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+        switch (msg.role) {
+            case 'user':
+                result.push({
+                    role: 'user',
+                    parts: typeof msg.content === 'string'
+                        ? [{ text: msg.content }]
+                        : convertContentParts(msg.content),
+                });
+                break;
+            case 'assistant':
+                result.push({
+                    role: 'model',
+                    parts: convertAssistantParts(msg.content),
+                });
+                break;
+            case 'tool_result': {
+                const textContent = typeof msg.content === 'string'
+                    ? msg.content
+                    : msg.content.map((p) => p.type === 'text' ? p.text : '').join('');
+                // Gemini requires the function *name* here, not the call ID.
+                // Look backwards through the conversation for the matching
+                // tool_call block so we can resolve the actual name.
+                const toolName = resolveToolName(messages, msg.toolCallId);
+                result.push({
+                    role: 'function',
+                    parts: [
+                        {
+                            functionResponse: {
+                                name: toolName,
+                                response: {
+                                    content: textContent,
+                                },
+                            },
+                        },
+                    ],
+                });
+                break;
+            }
+        }
+    }
+    return result;
+}
+function convertContentParts(parts) {
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { text: part.text };
+        }
+        return {
+            inlineData: {
+                mimeType: part.mediaType,
+                data: part.data,
+            },
+        };
+    });
+}
+function convertAssistantParts(blocks) {
+    const parts = [];
+    for (const block of blocks) {
+        switch (block.type) {
+            case 'text':
+                parts.push({ text: block.text });
+                break;
+            case 'thinking':
+                // Gemini doesn't have thinking blocks — emit as text
+                parts.push({ text: block.text });
+                break;
+            case 'tool_call':
+                parts.push({
+                    functionCall: {
+                        name: block.toolName,
+                        args: block.args,
+                    },
+                });
+                break;
+        }
+    }
+    return parts;
+}
+function convertToolDefinition(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal: helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a toolCallId back to the function name by scanning the conversation
+ * history for a matching tool_call block in an assistant message.
+ *
+ * Falls back to the toolCallId itself if no match is found (best-effort).
+ */
+function resolveToolName(messages, toolCallId) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role === 'assistant') {
+            for (const block of m.content) {
+                if (block.type === 'tool_call' && block.toolCallId === toolCallId) {
+                    return block.toolName;
+                }
+            }
+        }
+    }
+    return toolCallId;
+}
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'STOP': return 'end_turn';
+        case 'MAX_TOKENS': return 'max_tokens';
+        case 'SAFETY': return 'end_turn';
+        case 'RECITATION': return 'end_turn';
+        default: return 'end_turn';
+    }
+}

package/dist/llm/providers/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Provider registry — manages all registered LLM providers and provides
+ * convenience methods for streaming and completion.
+ */
+import type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
+import type { LLMProvider, LLMRequest } from '../provider.js';
+export declare class ProviderRegistry {
+    private readonly providers;
+    /** Register a provider. Overwrites any existing registration with the same id. */
+    register(provider: LLMProvider): void;
+    /** Retrieve a provider by id. */
+    get(id: string): LLMProvider | undefined;
+    /** Return all registered providers. */
+    getAll(): LLMProvider[];
+    /** Check whether a provider is registered. */
+    has(id: string): boolean;
+    /**
+     * Convenience: stream a completion through the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    stream(providerId: string, request: LLMRequest): AsyncIterableIterator<StreamEvent>;
+    /**
+     * Convenience: non-streaming completion through the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    /**
+     * Convenience: list models from the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    listModels(providerId: string, apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+    /** Get the default base URL for a provider. */
+    getDefaultBaseUrl(providerId: string): string;
+    private resolveProvider;
+}
+/**
+ * Create and populate a {@link ProviderRegistry} with all built-in providers.
+ * Call this once at server startup.
+ */
+export declare function initProviders(): ProviderRegistry;
+/**
+ * Get (or lazily create) the global singleton provider registry.
+ *
+ * Prefer calling `initProviders()` explicitly at startup and passing the
+ * registry around.  This singleton exists as a convenience for modules that
+ * cannot easily receive the registry through dependency injection.
+ */
+export declare function getProviderRegistry(): ProviderRegistry;
+/**
+ * Replace the global singleton (useful for testing).
+ */
+export declare function setProviderRegistry(registry: ProviderRegistry): void;
+/**
+ * Stream a completion — drop-in replacement for `pi-ai` `streamSimple`.
+ *
+ * Uses the global singleton registry.
+ */
+export declare function streamLLM(providerId: string, request: LLMRequest): AsyncIterableIterator<StreamEvent>;
+/**
+ * Non-streaming completion — drop-in replacement for `pi-ai` `completeSimple`.
+ *
+ * Uses the global singleton registry.
+ */
+export declare function completeLLM(providerId: string, request: LLMRequest): Promise<AssistantMessage>;

package/dist/llm/providers/index.js

@@ -0,0 +1,127 @@
+/**
+ * Provider registry — manages all registered LLM providers and provides
+ * convenience methods for streaming and completion.
+ */
+import { LLMError } from '../provider.js';
+import { AnthropicProvider } from './anthropic.js';
+import { OpenAIProvider } from './openai.js';
+import { GoogleProvider } from './google.js';
+// ---------------------------------------------------------------------------
+// ProviderRegistry
+// ---------------------------------------------------------------------------
+export class ProviderRegistry {
+    providers = new Map();
+    /** Register a provider. Overwrites any existing registration with the same id. */
+    register(provider) {
+        this.providers.set(provider.id, provider);
+    }
+    /** Retrieve a provider by id. */
+    get(id) {
+        return this.providers.get(id);
+    }
+    /** Return all registered providers. */
+    getAll() {
+        return Array.from(this.providers.values());
+    }
+    /** Check whether a provider is registered. */
+    has(id) {
+        return this.providers.has(id);
+    }
+    /**
+     * Convenience: stream a completion through the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    stream(providerId, request) {
+        const provider = this.resolveProvider(providerId);
+        return provider.stream(request);
+    }
+    /**
+     * Convenience: non-streaming completion through the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    async complete(providerId, request) {
+        const provider = this.resolveProvider(providerId);
+        return provider.complete(request);
+    }
+    /**
+     * Convenience: list models from the named provider.
+     *
+     * @throws {LLMError} if the provider is not registered.
+     */
+    async listModels(providerId, apiKey, baseUrl) {
+        const provider = this.resolveProvider(providerId);
+        return provider.listModels(apiKey, baseUrl);
+    }
+    /** Get the default base URL for a provider. */
+    getDefaultBaseUrl(providerId) {
+        return this.providers.get(providerId)?.defaultBaseUrl ?? '';
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    resolveProvider(id) {
+        const provider = this.providers.get(id);
+        if (!provider) {
+            throw new LLMError(`Unknown LLM provider: "${id}". Registered providers: ${Array.from(this.providers.keys()).join(', ')}`, id, 'invalid_request', false);
+        }
+        return provider;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create and populate a {@link ProviderRegistry} with all built-in providers.
+ * Call this once at server startup.
+ */
+export function initProviders() {
+    const registry = new ProviderRegistry();
+    registry.register(new AnthropicProvider());
+    registry.register(new OpenAIProvider());
+    registry.register(new GoogleProvider());
+    return registry;
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let _singleton;
+/**
+ * Get (or lazily create) the global singleton provider registry.
+ *
+ * Prefer calling `initProviders()` explicitly at startup and passing the
+ * registry around.  This singleton exists as a convenience for modules that
+ * cannot easily receive the registry through dependency injection.
+ */
+export function getProviderRegistry() {
+    if (!_singleton) {
+        _singleton = initProviders();
+    }
+    return _singleton;
+}
+/**
+ * Replace the global singleton (useful for testing).
+ */
+export function setProviderRegistry(registry) {
+    _singleton = registry;
+}
+// ---------------------------------------------------------------------------
+// Top-level convenience functions (replacements for pi-ai helpers)
+// ---------------------------------------------------------------------------
+/**
+ * Stream a completion — drop-in replacement for `pi-ai` `streamSimple`.
+ *
+ * Uses the global singleton registry.
+ */
+export function streamLLM(providerId, request) {
+    return getProviderRegistry().stream(providerId, request);
+}
+/**
+ * Non-streaming completion — drop-in replacement for `pi-ai` `completeSimple`.
+ *
+ * Uses the global singleton registry.
+ */
+export async function completeLLM(providerId, request) {
+    return getProviderRegistry().complete(providerId, request);
+}

package/dist/llm/providers/openai.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
+import type { LLMProvider, LLMRequest } from '../provider.js';
+export declare class OpenAIProvider implements LLMProvider {
+    readonly id = "openai";
+    readonly displayName = "OpenAI";
+    readonly defaultBaseUrl = "https://api.openai.com/v1";
+    stream(request: LLMRequest): AsyncIterableIterator<StreamEvent>;
+    complete(request: LLMRequest): Promise<AssistantMessage>;
+    listModels(apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+}