@amodalai/runtime 0.1.25 → 0.2.0

package/dist/src/api/create-agent.js

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { loadRepo, McpManager } from '@amodalai/core';
+import { StandaloneSessionManager } from '../session/manager.js';
+import { buildSessionComponents } from '../session/session-builder.js';
+import { LocalToolExecutor } from '../agent/tool-executor-local.js';
+import { buildMcpConfigs } from '../agent/mcp-config.js';
+import { createPGLiteStoreBackend } from '../stores/pglite-store-backend.js';
+import { createLogger } from '../logger.js';
+import { SessionError } from '../errors.js';
+import { LOCAL_APP_ID } from '../constants.js';
+const MCP_STARTUP_TIMEOUT_MS = 30_000;
+// ---------------------------------------------------------------------------
+// createAgent
+// ---------------------------------------------------------------------------
+/**
+ * Create a running agent from a repo path or pre-loaded bundle.
+ *
+ * This is the main entry point for programmatic use of the Amodal runtime.
+ * It loads the agent configuration, initializes stores, MCP connections,
+ * and the session manager, then returns an Agent handle for creating
+ * sessions and streaming messages.
+ */
+export async function createAgent(config) {
+    const logger = config.logger ?? createLogger({ component: 'agent' });
+    // Load bundle
+    const bundle = config.bundle ?? await loadRepo({ localPath: config.repoPath });
+    // Store backend
+    let storeBackend = config.storeBackend ?? null;
+    if (!storeBackend && bundle.stores.length > 0 && config.repoPath) {
+        const dataDir = `${config.repoPath}/.amodal/store-data`;
+        storeBackend = await createPGLiteStoreBackend(bundle.stores, dataDir);
+    }
+    // Tool executor
+    const toolExecutor = bundle.tools.length > 0 ? new LocalToolExecutor() : undefined;
+    // MCP — with timeout to prevent hanging on broken MCP servers
+    let mcpManager = config.mcpManager ?? null;
+    if (!mcpManager) {
+        const mcpConfigs = buildMcpConfigs(bundle);
+        if (Object.keys(mcpConfigs).length > 0) {
+            const manager = new McpManager();
+            try {
+                await Promise.race([
+                    manager.startServers(mcpConfigs),
+                    new Promise((_, reject) => {
+                        setTimeout(() => reject(new Error('MCP startup timed out')), MCP_STARTUP_TIMEOUT_MS);
+                    }),
+                ]);
+                if (manager.connectedCount > 0) {
+                    mcpManager = manager;
+                    logger.info('mcp_initialized', { servers: manager.connectedCount });
+                }
+            }
+            catch (err) {
+                logger.warn('mcp_startup_failed', { error: err instanceof Error ? err.message : String(err) });
+                // Continue without MCP — agent still works for non-MCP tools
+            }
+        }
+    }
+    // Session manager
+    const sessionManager = new StandaloneSessionManager({
+        logger,
+        ttlMs: config.sessionTtlMs,
+    });
+    sessionManager.start();
+    // Build components once (reused for each session)
+    const components = buildSessionComponents({
+        bundle,
+        storeBackend,
+        mcpManager,
+        logger,
+        toolExecutor,
+    });
+    return {
+        createSession(opts) {
+            const session = sessionManager.create({
+                tenantId: opts?.tenantId ?? LOCAL_APP_ID,
+                userId: opts?.userId ?? 'api',
+                provider: components.provider,
+                toolRegistry: components.toolRegistry,
+                permissionChecker: components.permissionChecker,
+                systemPrompt: components.systemPrompt,
+                userRoles: opts?.userRoles ?? components.userRoles,
+                toolContextFactory: components.toolContextFactory,
+            });
+            return createAgentSession(sessionManager, session.id, components);
+        },
+        async resumeSession(sessionId) {
+            const existing = sessionManager.get(sessionId);
+            if (existing) {
+                return createAgentSession(sessionManager, existing.id, components);
+            }
+            return null;
+        },
+        getSystemPrompt() {
+            return components.systemPrompt;
+        },
+        getBundle() {
+            return bundle;
+        },
+        async shutdown() {
+            await sessionManager.shutdown();
+            if (mcpManager) {
+                await mcpManager.shutdown();
+            }
+            if (storeBackend) {
+                await storeBackend.close();
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// AgentSession wrapper
+// ---------------------------------------------------------------------------
+function createAgentSession(sessionManager, sessionId, components) {
+    const session = sessionManager.get(sessionId);
+    if (!session) {
+        throw new SessionError(`Session "${sessionId}" not found`, {
+            sessionId,
+            context: { operation: 'createAgentSession' },
+        });
+    }
+    return {
+        get id() { return sessionId; },
+        get session() { return session; },
+        async *stream(message, opts) {
+            yield* sessionManager.runMessage(sessionId, message, {
+                signal: opts?.signal,
+                buildToolContext: components.toolContextFactory,
+            });
+        },
+    };
+}
+//# sourceMappingURL=create-agent.js.map

package/dist/src/api/create-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-agent.js","sourceRoot":"","sources":["../../../src/api/create-agent.ts"],"names":[],"mappings":"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"}

package/dist/src/api/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Public API types for the Amodal runtime.
+ *
+ * These are the only types ISV consumers should depend on.
+ * Internal types (state machine, tool registry internals, etc.)
+ * are not exported from the public API.
+ */
+import type { AgentBundle, StoreBackend } from '@amodalai/types';
+import type { McpManager } from '@amodalai/core';
+import type { LLMProvider, ProviderConfig } from '../providers/types.js';
+import type { Session } from '../session/types.js';
+import type { SSEEvent } from '../types.js';
+import type { StreamHooks } from '../session/stream-hooks.js';
+import type { Logger } from '../logger.js';
+/** Configuration for creating an agent. */
+export interface AgentConfig {
+    /** Path to the agent repo (local mode). */
+    repoPath?: string;
+    /** Pre-loaded agent bundle (alternative to repoPath). */
+    bundle?: AgentBundle;
+    /** LLM provider override (default: created from bundle model config). */
+    provider?: LLMProvider;
+    /** Provider config override (default: from bundle model config). */
+    providerConfig?: ProviderConfig;
+    /** Custom store backend (default: PGLite in .amodal/store-data). */
+    storeBackend?: StoreBackend;
+    /** MCP manager (default: created from bundle MCP configs). */
+    mcpManager?: McpManager;
+    /** Logger (default: built-in structured logger). */
+    logger?: Logger;
+    /** Session TTL in milliseconds (default: 30 minutes). */
+    sessionTtlMs?: number;
+    /** Stream hooks for audit logging, usage reporting, and persistence. */
+    streamHooks?: StreamHooks;
+}
+/** A running agent instance. */
+export interface Agent {
+    /** Create a new chat session. */
+    createSession(opts?: {
+        tenantId?: string;
+        userId?: string;
+        userRoles?: string[];
+    }): AgentSession;
+    /** Resume an existing session by ID. Returns null if not found. */
+    resumeSession(sessionId: string): Promise<AgentSession | null>;
+    /** Get the agent's compiled system prompt. */
+    getSystemPrompt(): string;
+    /** Get the agent bundle. */
+    getBundle(): AgentBundle;
+    /** Shut down the agent (close store, MCP, cleanup). */
+    shutdown(): Promise<void>;
+}
+/** A chat session — send messages and receive SSE events. */
+export interface AgentSession {
+    /** Session ID. */
+    readonly id: string;
+    /** Send a message and stream SSE events back. */
+    stream(message: string, opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SSEEvent>;
+    /** The underlying session object (for advanced use). */
+    readonly session: Session;
+}

package/dist/src/api/types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/config.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ModelConfig, AmodalConfigSchema } from '@amodalai/core';
+import type { z } from 'zod';
+/** The raw amodal.json shape (Zod-inferred, NOT the AmodalConfig class wrapper) */
+type RepoConfig = z.infer<typeof AmodalConfigSchema>;
+import { LogLevel } from './logger.js';
+export type { ModelConfig } from '@amodalai/core';
+export interface AgentConfig {
+    /** Agent name from amodal.json */
+    readonly name: string;
+    /** Agent version */
+    readonly version: string;
+    /** Agent description */
+    readonly description?: string;
+    /** Standing instructions for the LLM (userContext from amodal.json) */
+    readonly userContext?: string;
+    /** Custom base system prompt (overrides default) */
+    readonly basePrompt?: string;
+    /** Subagent names to disable */
+    readonly disabledSubagents: string[];
+    /** Primary model configuration */
+    readonly primaryModel: ModelConfig;
+    /** Secondary model for simple tasks (optional) */
+    readonly simpleModel?: ModelConfig;
+    /** Advanced model for complex reasoning (optional) */
+    readonly advancedModel?: ModelConfig;
+    /** All models keyed by role name */
+    readonly models: Record<string, ModelConfig>;
+    /** Store backend configuration */
+    readonly stores: {
+        readonly backend: 'pglite' | 'postgres';
+        readonly dataDir: string;
+        readonly postgresUrl?: string;
+    };
+    /** MCP server configurations */
+    readonly mcpServers: Record<string, McpServerConfig>;
+    /** Sandbox/shell execution settings */
+    readonly sandbox: {
+        readonly shellExec: boolean;
+        readonly maxTimeout: number;
+        readonly template?: string;
+    };
+    /** Platform integration (optional) */
+    readonly platform?: {
+        readonly projectId: string;
+        readonly apiKey: string;
+    };
+    /** Webhook secret for proactive automations */
+    readonly webhookSecret?: string;
+    /** Log level */
+    readonly logLevel: LogLevel;
+    /** Repo path (absolute) */
+    readonly repoPath: string;
+    /** Raw amodal.json (for consumers that need fields not in this interface) */
+    readonly raw: RepoConfig;
+}
+export interface McpServerConfig {
+    transport: 'stdio' | 'sse' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    trust?: boolean;
+}
+export interface ConfigOverrides {
+    /** Override log level */
+    logLevel?: LogLevel;
+    /** Override primary model */
+    primaryModel?: Partial<ModelConfig>;
+    /** Override store backend */
+    storeBackend?: 'pglite' | 'postgres';
+    /** Override store data directory */
+    storeDataDir?: string;
+    /** Override postgres URL */
+    postgresUrl?: string;
+}
+export interface LoadConfigOptions {
+    /** Path to the agent repo root (must contain .amodal/ or amodal.json) */
+    repoPath: string;
+    /** Runtime overrides from createAgent() */
+    overrides?: ConfigOverrides;
+}
+/**
+ * Load, validate, and return the unified agent config.
+ *
+ * Reads amodal.json from the repo, resolves env: references,
+ * applies environment variable overrides, applies runtime overrides,
+ * and validates the result. Throws ConfigError with actionable
+ * messages on any failure.
+ */
+export declare function loadConfig(opts: LoadConfigOptions): AgentConfig;

package/dist/src/config.js

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Unified runtime configuration.
+ *
+ * Consolidates amodal.json, environment variables, and runtime overrides
+ * into a single typed, validated config object. Replaces the split between
+ * core's AmodalConfig schema and the upstream gemini-cli-core Config wrapper.
+ *
+ * Config precedence (highest to lowest):
+ * 1. Runtime overrides (passed to createAgent() by ISVs)
+ * 2. Environment variables
+ * 3. amodal.json in the agent repo
+ * 4. Sensible defaults
+ *
+ * @example
+ * ```ts
+ * import { loadConfig } from './config.js';
+ *
+ * const config = loadConfig({
+ *   repoPath: '/path/to/agent',
+ *   overrides: { logLevel: 'debug' },
+ * });
+ * ```
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseConfigJson } from '@amodalai/core';
+import { ConfigError } from './errors.js';
+import { LogLevel } from './logger.js';
+/** Parse log level from string — duplicated here to avoid circular dep with logger.ts */
+function parseLogLevelStr(value) {
+    switch (value?.toLowerCase()) {
+        case 'trace': return LogLevel.TRACE;
+        case 'debug': return LogLevel.DEBUG;
+        case 'info': return LogLevel.INFO;
+        case 'warn': return LogLevel.WARN;
+        case 'error': return LogLevel.ERROR;
+        case 'fatal': return LogLevel.FATAL;
+        case 'none': return LogLevel.NONE;
+        case undefined: return LogLevel.INFO;
+        default: return LogLevel.INFO;
+    }
+}
+/**
+ * Known provider API key environment variable names.
+ */
+/** Default sandbox timeout in ms when not specified in amodal.json. */
+const DEFAULT_SANDBOX_TIMEOUT_MS = 30_000;
+/**
+ * Known provider API key environment variable names.
+ */
+const PROVIDER_ENV_KEYS = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    google: 'GOOGLE_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+    groq: 'GROQ_API_KEY',
+    mistral: 'MISTRAL_API_KEY',
+    xai: 'XAI_API_KEY',
+    bedrock: 'AWS_ACCESS_KEY_ID', // Bedrock uses AWS credential chain
+};
+/**
+ * Load, validate, and return the unified agent config.
+ *
+ * Reads amodal.json from the repo, resolves env: references,
+ * applies environment variable overrides, applies runtime overrides,
+ * and validates the result. Throws ConfigError with actionable
+ * messages on any failure.
+ */
+export function loadConfig(opts) {
+    const { repoPath, overrides } = opts;
+    // 1. Find and read amodal.json
+    const configPath = findConfigFile(repoPath);
+    if (!configPath) {
+        throw new ConfigError('Config file not found', {
+            key: 'amodal.json',
+            suggestion: `Create an amodal.json in ${repoPath} or run 'amodal init' to scaffold a new agent.`,
+        });
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch (err) {
+        throw new ConfigError(`Cannot read config file: ${configPath}`, {
+            key: 'amodal.json',
+            suggestion: 'Check file permissions.',
+            cause: err,
+        });
+    }
+    // 2. Parse and validate (core's parseConfigJson handles Zod + env: resolution)
+    let repoConfig;
+    try {
+        repoConfig = parseConfigJson(raw);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('not set')) {
+            // Extract the env var name from the error message
+            const match = err.message.match(/"(\w+)" is not set/);
+            const varName = match?.[1] ?? 'UNKNOWN';
+            throw new ConfigError(`Environment variable "${varName}" is not set`, {
+                key: `env:${varName}`,
+                suggestion: `Set ${varName} in your .env file or environment. This is referenced in amodal.json.`,
+            });
+        }
+        throw new ConfigError(err instanceof Error ? err.message : String(err), {
+            key: 'amodal.json',
+            suggestion: 'Check your amodal.json for syntax errors or invalid values.',
+            cause: err,
+        });
+    }
+    // 3. Validate provider API key is available
+    validateProviderKey(repoConfig.models.main);
+    // 4. Build the unified config
+    const storeDataDir = overrides?.storeDataDir
+        ?? repoConfig.stores?.dataDir
+        ?? join(repoPath, '.amodal', 'store-data');
+    const storeBackend = overrides?.storeBackend ?? repoConfig.stores?.backend ?? 'pglite';
+    let postgresUrl = overrides?.postgresUrl ?? repoConfig.stores?.postgresUrl;
+    if (postgresUrl && postgresUrl.startsWith('env:')) {
+        const envVar = postgresUrl.slice(4);
+        postgresUrl = process.env[envVar];
+        if (!postgresUrl && storeBackend === 'postgres') {
+            throw new ConfigError(`Postgres URL environment variable "${envVar}" is not set`, {
+                key: 'stores.postgresUrl',
+                suggestion: `Set ${envVar} in your .env file. Required when stores.backend is 'postgres'.`,
+            });
+        }
+    }
+    const logLevel = overrides?.logLevel
+        ?? parseLogLevelStr(process.env['LOG_LEVEL'])
+        ?? LogLevel.INFO;
+    const mcpServers = {};
+    if (repoConfig.mcp?.servers) {
+        for (const [name, server] of Object.entries(repoConfig.mcp.servers)) {
+            mcpServers[name] = server;
+        }
+    }
+    const config = {
+        name: repoConfig.name,
+        version: repoConfig.version,
+        description: repoConfig.description,
+        userContext: repoConfig.userContext,
+        basePrompt: repoConfig.basePrompt,
+        disabledSubagents: repoConfig.disabledSubagents ?? [],
+        primaryModel: applyModelOverrides(repoConfig.models.main, overrides?.primaryModel),
+        simpleModel: repoConfig.models.simple,
+        advancedModel: repoConfig.models.advanced,
+        models: {
+            main: applyModelOverrides(repoConfig.models.main, overrides?.primaryModel),
+            ...(repoConfig.models.simple && { simple: repoConfig.models.simple }),
+            ...(repoConfig.models.advanced && { advanced: repoConfig.models.advanced }),
+        },
+        stores: {
+            backend: storeBackend,
+            dataDir: storeDataDir,
+            postgresUrl,
+        },
+        mcpServers,
+        sandbox: {
+            shellExec: repoConfig.sandbox?.shellExec ?? false,
+            maxTimeout: repoConfig.sandbox?.maxTimeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,
+            template: repoConfig.sandbox?.template,
+        },
+        platform: repoConfig.platform,
+        webhookSecret: repoConfig.proactive?.webhook,
+        logLevel,
+        repoPath,
+        raw: repoConfig,
+    };
+    return config;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function findConfigFile(repoPath) {
+    // Check both locations: root amodal.json and .amodal/config.json
+    const candidates = [
+        join(repoPath, 'amodal.json'),
+        join(repoPath, '.amodal', 'config.json'),
+    ];
+    return candidates.find((p) => existsSync(p));
+}
+function validateProviderKey(model) {
+    // If explicit credentials are provided, skip env var check
+    if (model.credentials && Object.keys(model.credentials).length > 0) {
+        return;
+    }
+    const provider = model.provider;
+    const envKey = PROVIDER_ENV_KEYS[provider];
+    if (!envKey) {
+        // Unknown provider — if they have a baseUrl, it's OpenAI-compatible and needs OPENAI_API_KEY
+        if (model.baseUrl) {
+            const key = model.credentials?.['OPENAI_API_KEY'] ?? process.env['OPENAI_API_KEY'];
+            if (!key) {
+                throw new ConfigError(`OpenAI-compatible provider "${provider}" requires an API key`, {
+                    key: 'models.main.credentials',
+                    suggestion: `Set OPENAI_API_KEY in your environment or add credentials.OPENAI_API_KEY to the model config.`,
+                });
+            }
+        }
+        return;
+    }
+    const key = process.env[envKey];
+    if (!key) {
+        throw new ConfigError(`Provider API key not found`, {
+            key: `models.main.provider (${provider})`,
+            suggestion: `Set ${envKey} in your .env file or environment.\n  Checked: amodal.json → models.main.credentials\n  Checked: env → ${envKey}`,
+        });
+    }
+}
+function applyModelOverrides(base, overrides) {
+    if (!overrides)
+        return base;
+    return { ...base, ...overrides };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKvC,yFAAyF;AACzF,SAAS,gBAAgB,CAAC,KAAyB;IACjD,QAAQ,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;QAC7B,KAAK,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,KAAK,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,KAAK,MAAM,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC;QAClC,KAAK,MAAM,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC;QAClC,KAAK,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,KAAK,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,KAAK,MAAM,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC;QAClC,KAAK,SAAS,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC;QACrC,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,uEAAuE;AACvE,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAE1C;;GAEG;AACH,MAAM,iBAAiB,GAA2B;IAChD,SAAS,EAAE,mBAAmB;IAC9B,MAAM,EAAE,gBAAgB;IACxB,MAAM,EAAE,gBAAgB;IACxB,QAAQ,EAAE,kBAAkB;IAC5B,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,iBAAiB;IAC1B,GAAG,EAAE,aAAa;IAClB,OAAO,EAAE,mBAAmB,EAAE,oCAAoC;CACnE,CAAC;AAuGF;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAErC,+BAA+B;IAC/B,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,WAAW,CACnB,uBAAuB,EACvB;YACE,GAAG,EAAE,aAAa;YAClB,UAAU,EAAE,4BAA4B,QAAQ,gDAAgD;SACjG,CACF,CAAC;IACJ,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,4BAA4B,UAAU,EAAE,EACxC;YACE,GAAG,EAAE,aAAa;YAClB,UAAU,EAAE,yBAAyB;YACrC,KAAK,EAAE,GAAG;SACX,CACF,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,IAAI,UAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5D,kDAAkD;YAClD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;YACxC,MAAM,IAAI,WAAW,CACnB,yBAAyB,OAAO,cAAc,EAC9C;gBACE,GAAG,EAAE,OAAO,OAAO,EAAE;gBACrB,UAAU,EAAE,OAAO,OAAO,uEAAuE;aAClG,CACF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,WAAW,CACnB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAChD;YACE,GAAG,EAAE,aAAa;YAClB,UAAU,EAAE,6DAA6D;YACzE,KAAK,EAAE,GAAG;SACX,CACF,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE5C,8BAA8B;IAC9B,MAAM,YAAY,GAAG,SAAS,EAAE,YAAY;WACvC,UAAU,CAAC,MAAM,EAAE,OAAO;WAC1B,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAE7C,MAAM,YAAY,GAAG,SAAS,EAAE,YAAY,IAAI,UAAU,CAAC,MAAM,EAAE,OAAO,IAAI,QAAQ,CAAC;IAEvF,IAAI,WAAW,GAAG,SAAS,EAAE,WAAW,IAAI,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC;IAC3E,IAAI,WAAW,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACpC,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,WAAW,IAAI,YAAY,KAAK,UAAU,EAAE,CAAC;YAChD,MAAM,IAAI,WAAW,CACnB,sCAAsC,MAAM,cAAc,EAC1D;gBACE,GAAG,EAAE,oBAAoB;gBACzB,UAAU,EAAE,OAAO,MAAM,iEAAiE;aAC3F,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,EAAE,QAAQ;WAC/B,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;WAC1C,QAAQ,CAAC,IAAI,CAAC;IAEnB,MAAM,UAAU,GAAoC,EAAE,CAAC;IACvD,IAAI,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACpE,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAgB;QAC1B,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,IAAI,EAAE;QAErD,YAAY,EAAE,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC;QAClF,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM;QACrC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ;QACzC,MAAM,EAAE;YACN,IAAI,EAAE,mBAAmB,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC;YAC1E,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACrE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;SAC5E;QAED,MAAM,EAAE;YACN,OAAO,EAAE,YAAY;YACrB,OAAO,EAAE,YAAY;YACrB,WAAW;SACZ;QAED,UAAU;QAEV,OAAO,EAAE;YACP,SAAS,EAAE,UAAU,CAAC,OAAO,EAAE,SAAS,IAAI,KAAK;YACjD,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,IAAI,0BAA0B;YACxE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ;SACvC;QAED,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,aAAa,EAAE,UAAU,CAAC,SAAS,EAAE,OAAO;QAC5C,QAAQ;QACR,QAAQ;QACR,GAAG,EAAE,UAAU;KAChB,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,cAAc,CAAC,QAAgB;IACtC,iEAAiE;IACjE,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC7B,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,aAAa,CAAC;KACzC,CAAC;IACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAkB;IAC7C,2DAA2D;IAC3D,IAAI,KAAK,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnE,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAE3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,6FAA6F;QAC7F,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACnF,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,WAAW,CACnB,+BAA+B,QAAQ,uBAAuB,EAC9D;oBACE,GAAG,EAAE,yBAAyB;oBAC9B,UAAU,EAAE,+FAA+F;iBAC5G,CACF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO;IACT,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,WAAW,CACnB,4BAA4B,EAC5B;YACE,GAAG,EAAE,yBAAyB,QAAQ,GAAG;YACzC,UAAU,EAAE,OAAO,MAAM,0GAA0G,MAAM,EAAE;SAC5I,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAC1B,IAAiB,EACjB,SAAgC;IAEhC,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,EAAE,CAAC;AACnC,CAAC"}

package/dist/src/{agent/custom-tools-e2e.test.d.ts → config.test.d.ts}

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2025 Amodal Labs, Inc.
+ * Copyright 2026 Amodal Labs, Inc.
  * SPDX-License-Identifier: MIT
  */
 export {};