@aragon-agent/core 0.1.3

package/dist/index.js

@@ -0,0 +1,63 @@
+/**
+ * Agent core — barrel export.
+ *
+ * This is the single entry point for importing agent-core functionality.
+ * Other tasks will expand this file as more modules are added (engine, tools,
+ * sandbox).
+ */
+export { THINKING_BUDGET } from './llm/types.js';
+export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
+export { parseSSEStream, consumeStream, } from './llm/stream-utils.js';
+// ---------------------------------------------------------------------------
+// Provider registry
+// ---------------------------------------------------------------------------
+export { ProviderRegistry, initProviders, getProviderRegistry, setProviderRegistry, streamLLM, completeLLM, } from './llm/providers/index.js';
+// ---------------------------------------------------------------------------
+// Individual providers (for direct use when needed)
+// ---------------------------------------------------------------------------
+export { AnthropicProvider } from './llm/providers/anthropic.js';
+export { OpenAIProvider } from './llm/providers/openai.js';
+export { GoogleProvider } from './llm/providers/google.js';
+// ---------------------------------------------------------------------------
+// Model registry
+// ---------------------------------------------------------------------------
+export { ModelRegistry, getModelRegistry, setModelRegistry, } from './llm/model-registry.js';
+export { textResult, errorResult, imageResult, multiResult, defineTool, } from './tools/helpers.js';
+export { ToolRegistry } from './tools/registry.js';
+export { ToolParamValidator, ToolValidationError, formatValidationErrors, } from './tools/validator.js';
+export { ToolExecutor } from './tools/executor.js';
+// ---------------------------------------------------------------------------
+// Skills — progressive-disclosure skill system
+//
+// Pure logic only (D1): parsing, validation, registry, budgeting, rendering and
+// the Level 2 tool factory. All filesystem / network / process work lives in the
+// CLI and reaches this module through the injected `SkillHost` port, which is
+// what keeps this package free of `node:*` imports.
+// ---------------------------------------------------------------------------
+export { SkillRegistry } from './skills/skill-registry.js';
+export { parseFrontmatter } from './skills/frontmatter.js';
+export { validateSkillFrontmatter, validateStagedSkill } from './skills/validate.js';
+export { renderSkillCatalog, renderSkillBody, renderSkillInvocation, renderSkillFindResults, rankCatalogRecords, applySkillArguments, suggestSkillNames, sanitizeForPromptBlock, } from './skills/disclosure.js';
+export { createSkillTool } from './skills/skill-tool.js';
+export { createSkillFindTool } from './skills/skill-find-tool.js';
+// The turn-scoped tool ceiling (§5). Only the two entry points the host needs to
+// decide and to judge a call; the alias tables and the rendering helpers stay on
+// the `./skills` subpath, matching the existing split of this barrel.
+export { computeToolPolicy, evaluateToolCall } from './skills/tool-policy.js';
+export { 
+// Every budget below is measured in UTF-8 BYTES (D19).
+SKILL_CATALOG_MAX_BYTES, SKILL_BODY_MAX_BYTES, SKILL_RESULT_MAX_BYTES, ALWAYS_SKILLS_MAX_BYTES, SKILL_MD_MAX_BYTES, SKILL_DESC_LINE_MAX, SKILL_FILES_MAX, SKILL_FIND_MAX_BYTES, SKILL_NAME_PATTERN, } from './skills/constants.js';
+// ---------------------------------------------------------------------------
+// Agent engine
+// ---------------------------------------------------------------------------
+export { Agent } from './engine/agent.js';
+export { MessageManager } from './engine/message-manager.js';
+export { MessageQueueManager } from './engine/steering.js';
+export { IdleWatchdog } from './engine/watchdog.js';
+// Sandbox exports are NOT re-exported here — isolated-vm is incompatible with Electron's V8.
+// Import directly from './sandbox/*.js' when needed (lazy loading only).
+// ---------------------------------------------------------------------------
+// AragonAgent — published brand alias of the engine's `Agent` class.
+// The original `Agent` name is preserved above; consumers may use either.
+// ---------------------------------------------------------------------------
+export { Agent as AragonAgent } from './engine/agent.js';

package/dist/llm/model-registry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Model registry — static builtin model metadata + runtime API discovery with
+ * caching.
+ *
+ * The builtin lists are migrated from `src/lib/model-options.ts` and the
+ * discovery logic mirrors `server/services/model-detection.ts`, but uses the
+ * new LLMProvider interface for API queries.
+ */
+import type { ModelInfo } from './types.js';
+import type { ProviderRegistry } from './providers/index.js';
+export declare class ModelRegistry {
+    /** Static/builtin models keyed by provider id. */
+    private readonly builtinModels;
+    /** API-discovered models cache keyed by `${providerId}:${baseUrl}`. */
+    private readonly discoveryCache;
+    /** Optional reference to the provider registry for API discovery. */
+    private providerRegistry;
+    constructor(providerRegistry?: ProviderRegistry);
+    /** Register (or replace) the builtin model list for a provider. */
+    registerBuiltinModels(providerId: string, models: ModelInfo[]): void;
+    /** Retrieve the static builtin models for a provider. */
+    getModels(providerId: string): ModelInfo[];
+    /** Look up a specific model by provider + model id. */
+    getModel(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * Discover models from the provider's API.  Results are cached for 5 min.
+     *
+     * Falls back to an empty array on failure — never throws.
+     */
+    discoverModels(providerId: string, apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+    /** Invalidate the discovery cache for a provider (or all). */
+    clearCache(providerId?: string): void;
+    /**
+     * Build a runtime ModelInfo for a model that isn't in the registry.
+     *
+     * Uses sensible defaults — callers can override specific fields.
+     */
+    buildRuntimeModel(providerId: string, modelId: string, overrides?: Partial<ModelInfo>): ModelInfo;
+    /** Set or replace the provider registry reference. */
+    setProviderRegistry(registry: ProviderRegistry): void;
+    private registerDefaults;
+}
+/**
+ * Get (or lazily create) the global singleton model registry.
+ */
+export declare function getModelRegistry(): ModelRegistry;
+/**
+ * Replace the global singleton (useful for testing or re-initialization
+ * with a provider registry reference).
+ */
+export declare function setModelRegistry(registry: ModelRegistry): void;

package/dist/llm/model-registry.js

@@ -0,0 +1,277 @@
+/**
+ * Model registry — static builtin model metadata + runtime API discovery with
+ * caching.
+ *
+ * The builtin lists are migrated from `src/lib/model-options.ts` and the
+ * discovery logic mirrors `server/services/model-detection.ts`, but uses the
+ * new LLMProvider interface for API queries.
+ */
+/** Cache TTL: 5 minutes. */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// ModelRegistry
+// ---------------------------------------------------------------------------
+export class ModelRegistry {
+    /** Static/builtin models keyed by provider id. */
+    builtinModels = new Map();
+    /** API-discovered models cache keyed by `${providerId}:${baseUrl}`. */
+    discoveryCache = new Map();
+    /** Optional reference to the provider registry for API discovery. */
+    providerRegistry;
+    constructor(providerRegistry) {
+        this.providerRegistry = providerRegistry;
+        this.registerDefaults();
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /** Register (or replace) the builtin model list for a provider. */
+    registerBuiltinModels(providerId, models) {
+        this.builtinModels.set(providerId, models);
+    }
+    /** Retrieve the static builtin models for a provider. */
+    getModels(providerId) {
+        return this.builtinModels.get(providerId) || [];
+    }
+    /** Look up a specific model by provider + model id. */
+    getModel(providerId, modelId) {
+        const models = this.builtinModels.get(providerId);
+        return models?.find((m) => m.id === modelId);
+    }
+    /**
+     * Discover models from the provider's API.  Results are cached for 5 min.
+     *
+     * Falls back to an empty array on failure — never throws.
+     */
+    async discoverModels(providerId, apiKey, baseUrl) {
+        const cacheKey = `${providerId}:${baseUrl || ''}`;
+        const cached = this.discoveryCache.get(cacheKey);
+        if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+            return cached.models;
+        }
+        if (!this.providerRegistry)
+            return [];
+        const provider = this.providerRegistry.get(providerId);
+        if (!provider)
+            return [];
+        try {
+            const models = await provider.listModels(apiKey, baseUrl);
+            this.discoveryCache.set(cacheKey, { models, timestamp: Date.now() });
+            return models;
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Invalidate the discovery cache for a provider (or all). */
+    clearCache(providerId) {
+        if (providerId) {
+            for (const key of this.discoveryCache.keys()) {
+                if (key.startsWith(`${providerId}:`)) {
+                    this.discoveryCache.delete(key);
+                }
+            }
+        }
+        else {
+            this.discoveryCache.clear();
+        }
+    }
+    /**
+     * Build a runtime ModelInfo for a model that isn't in the registry.
+     *
+     * Uses sensible defaults — callers can override specific fields.
+     */
+    buildRuntimeModel(providerId, modelId, overrides) {
+        return {
+            id: modelId,
+            name: modelId,
+            provider: providerId,
+            contextWindow: 128_000,
+            maxOutputTokens: 16_384,
+            supportsThinking: false,
+            supportsTools: true,
+            supportsImages: false,
+            cost: { input: 0, output: 0 },
+            ...overrides,
+        };
+    }
+    /** Set or replace the provider registry reference. */
+    setProviderRegistry(registry) {
+        this.providerRegistry = registry;
+    }
+    // -----------------------------------------------------------------------
+    // Default builtin models (migrated from src/lib/model-options.ts)
+    // -----------------------------------------------------------------------
+    registerDefaults() {
+        this.builtinModels.set('anthropic', ANTHROPIC_MODELS);
+        this.builtinModels.set('openai', OPENAI_MODELS);
+        this.builtinModels.set('google', GOOGLE_MODELS);
+        this.builtinModels.set('xai', XAI_MODELS);
+        this.builtinModels.set('groq', GROQ_MODELS);
+    }
+}
+// ---------------------------------------------------------------------------
+// Builtin model lists
+// ---------------------------------------------------------------------------
+const ANTHROPIC_MODELS = [
+    {
+        id: 'claude-sonnet-4-5-20250929',
+        name: 'Claude Sonnet 4.5',
+        provider: 'anthropic',
+        contextWindow: 200_000,
+        maxOutputTokens: 8192,
+        supportsThinking: true,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    },
+    {
+        id: 'claude-opus-4-6',
+        name: 'Claude Opus 4.6',
+        provider: 'anthropic',
+        contextWindow: 200_000,
+        maxOutputTokens: 32_000,
+        supportsThinking: true,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    },
+    {
+        id: 'claude-haiku-4-5-20251001',
+        name: 'Claude Haiku 4.5',
+        provider: 'anthropic',
+        contextWindow: 200_000,
+        maxOutputTokens: 8192,
+        supportsThinking: true,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 },
+    },
+];
+const OPENAI_MODELS = [
+    {
+        id: 'gpt-4o',
+        name: 'GPT-4o',
+        provider: 'openai',
+        contextWindow: 128_000,
+        maxOutputTokens: 16_384,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 2.5, output: 10 },
+    },
+    {
+        id: 'gpt-4o-mini',
+        name: 'GPT-4o Mini',
+        provider: 'openai',
+        contextWindow: 128_000,
+        maxOutputTokens: 16_384,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 0.15, output: 0.6 },
+    },
+    {
+        id: 'o1',
+        name: 'o1',
+        provider: 'openai',
+        contextWindow: 200_000,
+        maxOutputTokens: 100_000,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 15, output: 60 },
+    },
+    {
+        id: 'o1-mini',
+        name: 'o1 Mini',
+        provider: 'openai',
+        contextWindow: 128_000,
+        maxOutputTokens: 65_536,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: false,
+        cost: { input: 3, output: 12 },
+    },
+];
+const GOOGLE_MODELS = [
+    {
+        id: 'gemini-1.5-pro',
+        name: 'Gemini 1.5 Pro',
+        provider: 'google',
+        contextWindow: 2_097_152,
+        maxOutputTokens: 8192,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 1.25, output: 5 },
+    },
+    {
+        id: 'gemini-1.5-flash',
+        name: 'Gemini 1.5 Flash',
+        provider: 'google',
+        contextWindow: 1_048_576,
+        maxOutputTokens: 8192,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: true,
+        cost: { input: 0.075, output: 0.3 },
+    },
+];
+const XAI_MODELS = [
+    {
+        id: 'grok-2',
+        name: 'Grok-2',
+        provider: 'xai',
+        contextWindow: 131_072,
+        maxOutputTokens: 8192,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: false,
+        cost: { input: 2, output: 10 },
+    },
+];
+const GROQ_MODELS = [
+    {
+        id: 'llama-3.1-70b-versatile',
+        name: 'Llama 3.1 70B',
+        provider: 'groq',
+        contextWindow: 131_072,
+        maxOutputTokens: 8192,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: false,
+        cost: { input: 0.59, output: 0.79 },
+    },
+    {
+        id: 'mixtral-8x7b-32768',
+        name: 'Mixtral 8x7B',
+        provider: 'groq',
+        contextWindow: 32_768,
+        maxOutputTokens: 8192,
+        supportsThinking: false,
+        supportsTools: true,
+        supportsImages: false,
+        cost: { input: 0.24, output: 0.24 },
+    },
+];
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let _singleton;
+/**
+ * Get (or lazily create) the global singleton model registry.
+ */
+export function getModelRegistry() {
+    if (!_singleton) {
+        _singleton = new ModelRegistry();
+    }
+    return _singleton;
+}
+/**
+ * Replace the global singleton (useful for testing or re-initialization
+ * with a provider registry reference).
+ */
+export function setModelRegistry(registry) {
+    _singleton = registry;
+}

package/dist/llm/provider.d.ts

@@ -0,0 +1,72 @@
+/**
+ * LLM Provider interface, request types, and error classification.
+ */
+import type { AssistantMessage, Message, ModelInfo, StreamEvent, ThinkingLevel, ToolDefinition } from './types.js';
+export interface LLMRequest {
+    /** Model identifier, e.g. 'claude-sonnet-4-5-20250929'. */
+    model: string;
+    /** Conversation messages. */
+    messages: Message[];
+    /** System prompt — injected provider-appropriately (system field, system message, etc.). */
+    systemPrompt?: string;
+    /** Tool schemas the model may invoke. */
+    tools?: ToolDefinition[];
+    /** Provider API key. */
+    apiKey: string;
+    /** Override the default API base URL. */
+    baseUrl?: string;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    temperature?: number;
+    maxTokens?: number;
+    /** Anthropic extended thinking level. Ignored by non-Anthropic providers. */
+    thinkingLevel?: ThinkingLevel;
+    /** Explicit thinking budget (tokens).  Overrides thinkingLevel if both are set. */
+    thinkingBudget?: number;
+    stopSequences?: string[];
+}
+export interface LLMProvider {
+    /** Unique provider identifier, e.g. 'anthropic', 'openai', 'google'. */
+    readonly id: string;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Default base URL for this provider's API. */
+    readonly defaultBaseUrl: string;
+    /**
+     * Stream a completion from the model.
+     *
+     * The returned iterator yields {@link StreamEvent} items and MUST terminate
+     * with either a `done` or an `error` event.
+     */
+    stream(request: LLMRequest): AsyncIterableIterator<StreamEvent>;
+    /**
+     * Non-streaming completion — internally consumes the stream and returns the
+     * final assembled {@link AssistantMessage}.
+     */
+    complete(request: LLMRequest): Promise<AssistantMessage>;
+    /**
+     * List models available under the given API key.
+     *
+     * Implementations should apply a reasonable timeout (15 s) and return an
+     * empty array on failure rather than throwing.
+     */
+    listModels(apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+}
+export type LLMErrorType = 'auth_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'context_overflow' | 'network_error' | 'timeout' | 'server_error' | 'unknown';
+export declare class LLMError extends Error {
+    readonly provider: string;
+    readonly errorType: LLMErrorType;
+    readonly retryable: boolean;
+    readonly statusCode?: number | undefined;
+    readonly raw?: unknown | undefined;
+    constructor(message: string, provider: string, errorType: LLMErrorType, retryable: boolean, statusCode?: number | undefined, raw?: unknown | undefined);
+}
+/**
+ * Classify an HTTP status code into an {@link LLMErrorType} and determine
+ * whether the request is retryable.
+ */
+export declare function classifyHttpError(statusCode: number, body: string, provider: string): LLMError;
+/**
+ * Wrap a network-level fetch error (DNS, TLS, abort, etc.) into an LLMError.
+ */
+export declare function wrapFetchError(err: unknown, provider: string): LLMError;

package/dist/llm/provider.js

@@ -0,0 +1,77 @@
+/**
+ * LLM Provider interface, request types, and error classification.
+ */
+export class LLMError extends Error {
+    provider;
+    errorType;
+    retryable;
+    statusCode;
+    raw;
+    constructor(message, provider, errorType, retryable, statusCode, raw) {
+        super(message);
+        this.provider = provider;
+        this.errorType = errorType;
+        this.retryable = retryable;
+        this.statusCode = statusCode;
+        this.raw = raw;
+        this.name = 'LLMError';
+    }
+}
+/**
+ * Classify an HTTP status code into an {@link LLMErrorType} and determine
+ * whether the request is retryable.
+ */
+export function classifyHttpError(statusCode, body, provider) {
+    let errorType;
+    let retryable;
+    switch (statusCode) {
+        case 400:
+            // Check for context overflow indicators
+            if (/context|token|length/i.test(body)) {
+                errorType = 'context_overflow';
+                retryable = false;
+            }
+            else {
+                errorType = 'invalid_request';
+                retryable = false;
+            }
+            break;
+        case 401:
+        case 403:
+            errorType = 'auth_error';
+            retryable = false;
+            break;
+        case 429:
+            errorType = 'rate_limit';
+            retryable = true;
+            break;
+        case 529:
+            errorType = 'overloaded';
+            retryable = true;
+            break;
+        default:
+            if (statusCode >= 500) {
+                errorType = 'server_error';
+                retryable = true;
+            }
+            else {
+                errorType = 'unknown';
+                retryable = false;
+            }
+    }
+    // Truncate body for the error message to avoid huge payloads
+    const truncated = body.length > 300 ? body.slice(0, 300) + '...' : body;
+    return new LLMError(`${provider} API error ${statusCode}: ${truncated}`, provider, errorType, retryable, statusCode, body);
+}
+/**
+ * Wrap a network-level fetch error (DNS, TLS, abort, etc.) into an LLMError.
+ */
+export function wrapFetchError(err, provider) {
+    if (err instanceof LLMError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof Error && err.name === 'AbortError') {
+        return new LLMError(`${provider} request aborted: ${message}`, provider, 'timeout', true);
+    }
+    return new LLMError(`${provider} network error: ${message}`, provider, 'network_error', true, undefined, err);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Anthropic Messages API adapter.
+ *
+ * Converts the universal LLM types to/from Anthropic's wire format and maps
+ * SSE events to the unified StreamEvent protocol.
+ *
+ * Supports:
+ * - Streaming via `POST /v1/messages` with `stream: true`
+ * - Extended thinking (thinking_start / thinking_delta)
+ * - Tool use (content_block_start type=tool_use → tool_call_*)
+ * - Multimodal user messages (text + image)
+ * - Model list via `GET /v1/models`
+ */
+import type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
+import type { LLMProvider, LLMRequest } from '../provider.js';
+export declare class AnthropicProvider implements LLMProvider {
+    readonly id = "anthropic";
+    readonly displayName = "Anthropic";
+    readonly defaultBaseUrl = "https://api.anthropic.com";
+    stream(request: LLMRequest): AsyncIterableIterator<StreamEvent>;
+    complete(request: LLMRequest): Promise<AssistantMessage>;
+    listModels(apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+}