zoe-agent 0.3.1

package/dist/core/settings-schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Zoe Core — Settings Schema
+ *
+ * Static data structures mapping all user-visible settings to their
+ * AppConfig paths, validation rules, env var overrides, and metadata.
+ */
+export type SettingsCategory = 'providers' | 'permissions' | 'tools' | 'notifications' | 'skills' | 'gateway' | 'sessions';
+export interface SettingsMapEntry {
+    dotKey: string;
+    configPath: string[];
+    category: SettingsCategory;
+    label: string;
+}
+export interface SettingsSchemaEntry {
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    secret: boolean;
+    enumValues?: string[];
+    min?: number;
+    max?: number;
+    default?: string | number | boolean;
+    restartRequired: boolean;
+    envVar?: string;
+}
+export declare const SETTINGS_CATEGORIES: {
+    key: SettingsCategory;
+    label: string;
+    description: string;
+}[];
+export declare const SETTINGS_MAP: Map<string, SettingsMapEntry>;
+export declare const CONFIG_PATH_TO_DOTKEY: Map<string, string>;
+export declare const SETTINGS_SCHEMA: Map<string, SettingsSchemaEntry>;
+export declare const ENV_VAR_MAP: Map<string, string>;
+export declare function getSettingEntry(dotKey: string): SettingsMapEntry | undefined;
+export declare function getSettingSchema(dotKey: string): SettingsSchemaEntry | undefined;
+export declare function getDotKeyForConfigPath(path: string[]): string | undefined;
+export declare function isSecretField(dotKey: string): boolean;
+export declare function isRestartRequired(dotKey: string): boolean;
+export declare function getSettingsByCategory(category: SettingsCategory): string[];

package/dist/core/settings-schema.js

@@ -0,0 +1,171 @@
+/**
+ * Zoe Core — Settings Schema
+ *
+ * Static data structures mapping all user-visible settings to their
+ * AppConfig paths, validation rules, env var overrides, and metadata.
+ */
+import { DEFAULT_MODELS } from "../models-catalog.js";
+// ── Categories ─────────────────────────────────────────────────────────
+export const SETTINGS_CATEGORIES = [
+    {
+        key: 'providers',
+        label: 'Providers & Models',
+        description: 'LLM provider configuration (API keys, models, base URLs)',
+    },
+    {
+        key: 'permissions',
+        label: 'Permissions & Safety',
+        description: 'Permission level and auto-confirm settings',
+    },
+    {
+        key: 'tools',
+        label: 'Tools & Integrations',
+        description: 'Image generation, SMTP email, and web search settings',
+    },
+    {
+        key: 'notifications',
+        label: 'Notifications',
+        description: 'Feishu, DingTalk, and WeCom webhook settings',
+    },
+    {
+        key: 'skills',
+        label: 'Skills',
+        description: 'Skill system configuration (reserved for future use)',
+    },
+    {
+        key: 'gateway',
+        label: 'Gateway',
+        description: 'MCP gateway, REST proxy, and OpenAPI adapter settings',
+    },
+    {
+        key: 'sessions',
+        label: 'Sessions',
+        description: 'Session persistence and cleanup settings',
+    },
+];
+// ── Settings Map ───────────────────────────────────────────────────────
+const entries = [
+    // Providers
+    ['providers.openai.apiKey', { dotKey: 'providers.openai.apiKey', configPath: ['models', 'openai', 'apiKey'], category: 'providers', label: 'OpenAI API Key' }],
+    ['providers.openai.model', { dotKey: 'providers.openai.model', configPath: ['models', 'openai', 'model'], category: 'providers', label: 'OpenAI Model' }],
+    ['providers.anthropic.apiKey', { dotKey: 'providers.anthropic.apiKey', configPath: ['models', 'anthropic', 'apiKey'], category: 'providers', label: 'Anthropic API Key' }],
+    ['providers.anthropic.model', { dotKey: 'providers.anthropic.model', configPath: ['models', 'anthropic', 'model'], category: 'providers', label: 'Anthropic Model' }],
+    ['providers.glm.apiKey', { dotKey: 'providers.glm.apiKey', configPath: ['models', 'glm', 'apiKey'], category: 'providers', label: 'GLM API Key' }],
+    ['providers.glm.model', { dotKey: 'providers.glm.model', configPath: ['models', 'glm', 'model'], category: 'providers', label: 'GLM Model' }],
+    ['providers.openai-compat.apiKey', { dotKey: 'providers.openai-compat.apiKey', configPath: ['models', 'openai-compatible', 'apiKey'], category: 'providers', label: 'OpenAI-Compatible API Key' }],
+    ['providers.openai-compat.baseUrl', { dotKey: 'providers.openai-compat.baseUrl', configPath: ['models', 'openai-compatible', 'baseUrl'], category: 'providers', label: 'OpenAI-Compatible Base URL' }],
+    ['providers.openai-compat.model', { dotKey: 'providers.openai-compat.model', configPath: ['models', 'openai-compatible', 'model'], category: 'providers', label: 'OpenAI-Compatible Model' }],
+    ['provider', { dotKey: 'provider', configPath: ['provider'], category: 'providers', label: 'Active Provider' }],
+    // Image
+    ['image.apiKey', { dotKey: 'image.apiKey', configPath: ['imageApiKey'], category: 'tools', label: 'Image Generation API Key' }],
+    ['image.baseUrl', { dotKey: 'image.baseUrl', configPath: ['imageBaseUrl'], category: 'tools', label: 'Image Generation Base URL' }],
+    ['image.model', { dotKey: 'image.model', configPath: ['imageModel'], category: 'tools', label: 'Image Generation Model' }],
+    ['image.size', { dotKey: 'image.size', configPath: ['imageSize'], category: 'tools', label: 'Image Size' }],
+    ['image.quality', { dotKey: 'image.quality', configPath: ['imageQuality'], category: 'tools', label: 'Image Quality' }],
+    ['image.style', { dotKey: 'image.style', configPath: ['imageStyle'], category: 'tools', label: 'Image Style' }],
+    ['image.n', { dotKey: 'image.n', configPath: ['imageN'], category: 'tools', label: 'Image Count' }],
+    // SMTP
+    ['smtp.host', { dotKey: 'smtp.host', configPath: ['smtpHost'], category: 'tools', label: 'SMTP Host' }],
+    ['smtp.port', { dotKey: 'smtp.port', configPath: ['smtpPort'], category: 'tools', label: 'SMTP Port' }],
+    ['smtp.user', { dotKey: 'smtp.user', configPath: ['smtpUser'], category: 'tools', label: 'SMTP Username' }],
+    ['smtp.pass', { dotKey: 'smtp.pass', configPath: ['smtpPass'], category: 'tools', label: 'SMTP Password' }],
+    ['smtp.from', { dotKey: 'smtp.from', configPath: ['smtpFrom'], category: 'tools', label: 'SMTP From Address' }],
+    // Search
+    ['search.tavilyApiKey', { dotKey: 'search.tavilyApiKey', configPath: ['tavilyApiKey'], category: 'tools', label: 'Tavily API Key' }],
+    // Notifications
+    ['notifications.feishu.webhook', { dotKey: 'notifications.feishu.webhook', configPath: ['feishuWebhook'], category: 'notifications', label: 'Feishu Webhook URL' }],
+    ['notifications.feishu.keyword', { dotKey: 'notifications.feishu.keyword', configPath: ['feishuKeyword'], category: 'notifications', label: 'Feishu Keyword' }],
+    ['notifications.dingtalk.webhook', { dotKey: 'notifications.dingtalk.webhook', configPath: ['dingtalkWebhook'], category: 'notifications', label: 'DingTalk Webhook URL' }],
+    ['notifications.dingtalk.keyword', { dotKey: 'notifications.dingtalk.keyword', configPath: ['dingtalkKeyword'], category: 'notifications', label: 'DingTalk Keyword' }],
+    ['notifications.wecom.webhook', { dotKey: 'notifications.wecom.webhook', configPath: ['wecomWebhook'], category: 'notifications', label: 'WeCom Webhook URL' }],
+    ['notifications.wecom.keyword', { dotKey: 'notifications.wecom.keyword', configPath: ['wecomKeyword'], category: 'notifications', label: 'WeCom Keyword' }],
+    // Permissions
+    ['agent.permissionLevel', { dotKey: 'agent.permissionLevel', configPath: ['permissionLevel'], category: 'permissions', label: 'Permission Level' }],
+    ['agent.autoConfirm', { dotKey: 'agent.autoConfirm', configPath: ['autoConfirm'], category: 'permissions', label: 'Auto-Confirm All Tools' }],
+    // Gateway
+    ['gateway.enabled', { dotKey: 'gateway.enabled', configPath: ['gatewayEnabled'], category: 'gateway', label: 'Gateway Enabled' }],
+    ['gateway.semanticTopK', { dotKey: 'gateway.semanticTopK', configPath: ['gatewaySemanticTopK'], category: 'gateway', label: 'Semantic Injection Top-K' }],
+    ['gateway.defaultRateLimitPerMin', { dotKey: 'gateway.defaultRateLimitPerMin', configPath: ['gatewayRateLimit'], category: 'gateway', label: 'Gateway Rate Limit (per min)' }],
+    ['gateway.maxAuditLogs', { dotKey: 'gateway.maxAuditLogs', configPath: ['gatewayMaxAuditLogs'], category: 'gateway', label: 'Max Audit Log Records' }],
+    // Sessions
+    ['sessions.maxAgeDays', { dotKey: 'sessions.maxAgeDays', configPath: ['sessions', 'maxAgeDays'], category: 'sessions', label: 'Max Session Age (days)' }],
+];
+export const SETTINGS_MAP = new Map(entries);
+// ── Reverse lookup ─────────────────────────────────────────────────────
+export const CONFIG_PATH_TO_DOTKEY = new Map(entries.map(([, entry]) => [entry.configPath.join('.'), entry.dotKey]));
+// ── Settings Schema ────────────────────────────────────────────────────
+const schemaEntries = [
+    // Providers
+    ['providers.openai.apiKey', { type: 'string', secret: true, restartRequired: true, envVar: 'OPENAI_API_KEY' }],
+    ['providers.openai.model', { type: 'string', secret: false, default: DEFAULT_MODELS.openai, restartRequired: false, envVar: 'OPENAI_MODEL' }],
+    ['providers.anthropic.apiKey', { type: 'string', secret: true, restartRequired: true, envVar: 'ANTHROPIC_API_KEY' }],
+    ['providers.anthropic.model', { type: 'string', secret: false, default: DEFAULT_MODELS.anthropic, restartRequired: false, envVar: 'ANTHROPIC_MODEL' }],
+    ['providers.glm.apiKey', { type: 'string', secret: true, restartRequired: true, envVar: 'GLM_API_KEY' }],
+    ['providers.glm.model', { type: 'string', secret: false, default: DEFAULT_MODELS.glm, restartRequired: false, envVar: 'GLM_MODEL' }],
+    ['providers.openai-compat.apiKey', { type: 'string', secret: true, restartRequired: true, envVar: 'OPENAI_COMPAT_API_KEY' }],
+    ['providers.openai-compat.baseUrl', { type: 'string', secret: false, restartRequired: true, envVar: 'OPENAI_COMPAT_BASE_URL' }],
+    ['providers.openai-compat.model', { type: 'string', secret: false, default: DEFAULT_MODELS['openai-compatible'], restartRequired: false, envVar: 'OPENAI_MODEL' }],
+    ['provider', { type: 'enum', secret: false, enumValues: ['openai', 'openai-compatible', 'anthropic', 'glm'], default: 'openai-compatible', restartRequired: true, envVar: 'LLM_PROVIDER' }],
+    // Image
+    ['image.apiKey', { type: 'string', secret: true, restartRequired: false }],
+    ['image.baseUrl', { type: 'string', secret: false, restartRequired: false }],
+    ['image.model', { type: 'string', secret: false, default: 'dall-e-3', restartRequired: false }],
+    ['image.size', { type: 'string', secret: false, default: '1024x1024', restartRequired: false }],
+    ['image.quality', { type: 'enum', secret: false, enumValues: ['standard', 'hd'], default: 'standard', restartRequired: false }],
+    ['image.style', { type: 'enum', secret: false, enumValues: ['vivid', 'natural'], default: 'vivid', restartRequired: false }],
+    ['image.n', { type: 'number', secret: false, default: 1, min: 1, max: 10, restartRequired: false }],
+    // SMTP
+    ['smtp.host', { type: 'string', secret: false, restartRequired: false, envVar: 'SMTP_HOST' }],
+    ['smtp.port', { type: 'string', secret: false, restartRequired: false, envVar: 'SMTP_PORT' }],
+    ['smtp.user', { type: 'string', secret: false, restartRequired: false, envVar: 'SMTP_USER' }],
+    ['smtp.pass', { type: 'string', secret: true, restartRequired: false, envVar: 'SMTP_PASS' }],
+    ['smtp.from', { type: 'string', secret: false, restartRequired: false }],
+    // Search
+    ['search.tavilyApiKey', { type: 'string', secret: true, restartRequired: false, envVar: 'TAVILY_API_KEY' }],
+    // Notifications
+    ['notifications.feishu.webhook', { type: 'string', secret: true, restartRequired: false, envVar: 'FEISHU_WEBHOOK' }],
+    ['notifications.feishu.keyword', { type: 'string', secret: false, restartRequired: false, envVar: 'FEISHU_KEYWORD' }],
+    ['notifications.dingtalk.webhook', { type: 'string', secret: true, restartRequired: false, envVar: 'DINGTALK_WEBHOOK' }],
+    ['notifications.dingtalk.keyword', { type: 'string', secret: false, restartRequired: false, envVar: 'DINGTALK_KEYWORD' }],
+    ['notifications.wecom.webhook', { type: 'string', secret: true, restartRequired: false, envVar: 'WECOM_WEBHOOK' }],
+    ['notifications.wecom.keyword', { type: 'string', secret: false, restartRequired: false, envVar: 'WECOM_KEYWORD' }],
+    // Agent
+    ['agent.permissionLevel', { type: 'enum', secret: false, enumValues: ['strict', 'moderate', 'permissive'], default: 'moderate', restartRequired: false, envVar: 'ZOE_PERMISSION' }],
+    ['agent.autoConfirm', { type: 'boolean', secret: false, default: false, restartRequired: false }],
+    // Gateway
+    ['gateway.enabled', { type: 'boolean', secret: false, default: true, restartRequired: true, envVar: 'ZOE_GATEWAY_ENABLED' }],
+    ['gateway.semanticTopK', { type: 'number', secret: false, default: 3, min: 1, max: 10, restartRequired: false }],
+    ['gateway.defaultRateLimitPerMin', { type: 'number', secret: false, default: 60, min: 0, restartRequired: false, envVar: 'ZOE_GATEWAY_RATE_LIMIT' }],
+    ['gateway.maxAuditLogs', { type: 'number', secret: false, default: 1000, min: 10, max: 10000, restartRequired: false }],
+    // Sessions
+    ['sessions.maxAgeDays', { type: 'number', secret: false, default: 30, min: 0, restartRequired: false }],
+];
+export const SETTINGS_SCHEMA = new Map(schemaEntries);
+// ── Env Var Map ────────────────────────────────────────────────────────
+export const ENV_VAR_MAP = new Map(schemaEntries
+    .filter(([, s]) => s.envVar !== undefined)
+    .map(([dotKey, s]) => [dotKey, s.envVar]));
+// ── Helpers ────────────────────────────────────────────────────────────
+export function getSettingEntry(dotKey) {
+    return SETTINGS_MAP.get(dotKey);
+}
+export function getSettingSchema(dotKey) {
+    return SETTINGS_SCHEMA.get(dotKey);
+}
+export function getDotKeyForConfigPath(path) {
+    return CONFIG_PATH_TO_DOTKEY.get(path.join('.'));
+}
+export function isSecretField(dotKey) {
+    return SETTINGS_SCHEMA.get(dotKey)?.secret ?? false;
+}
+export function isRestartRequired(dotKey) {
+    return SETTINGS_SCHEMA.get(dotKey)?.restartRequired ?? false;
+}
+export function getSettingsByCategory(category) {
+    const keys = [];
+    for (const entry of SETTINGS_MAP.values()) {
+        if (entry.category === category)
+            keys.push(entry.dotKey);
+    }
+    return keys;
+}

package/dist/core/skill-catalog.d.ts

@@ -0,0 +1,6 @@
+import type { SkillMetadata } from './types.js';
+/**
+ * Build a skill catalog string suitable for appending to the system prompt.
+ * Returns an empty string when no skills are available.
+ */
+export declare function buildSkillCatalog(metadata: SkillMetadata[]): string;

package/dist/core/skill-catalog.js

@@ -0,0 +1,17 @@
+/**
+ * Build a skill catalog string suitable for appending to the system prompt.
+ * Returns an empty string when no skills are available.
+ */
+export function buildSkillCatalog(metadata) {
+    if (metadata.length === 0)
+        return '';
+    const lines = metadata.map(s => {
+        const tags = s.tags.length > 0 ? ` [${s.tags.join(', ')}]` : '';
+        return `- ${s.name}: ${s.description}${tags}`;
+    });
+    return [
+        'AVAILABLE SKILLS (activate with use_skill tool):',
+        ...lines,
+        'When a user request matches a skill, call use_skill with the skill name.',
+    ].join('\n');
+}

package/dist/core/skill-invoker.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Skill Invoker — Central orchestrator for skill invocation flow.
+ *
+ * This module consolidates the skill invocation logic that was previously
+ * scattered across the CLI (src/index.ts) and agent (src/agent.ts).
+ *
+ * Invocation flow:
+ * 1. Parse input → extract skill name and arguments
+ * 2. Registry lookup → resolve skill metadata
+ * 3. @path resolution → inline file references
+ * 4. Prompt construction → build the final prompt
+ * 5. Return result with provider switching metadata
+ *
+ * The invoker does NOT handle provider switching itself — it returns
+ * metadata so the adapter can decide whether to switch.
+ */
+import { type SkillRegistry } from '../skills/types.js';
+import { type SkillMetadata } from './types.js';
+import type { LLMProvider } from '../providers/types.js';
+/**
+ * Result of a skill invocation.
+ *
+ * Contains the constructed prompt along with metadata about
+ * whether the skill has a preferred provider/model configuration.
+ */
+export interface SkillInvocationResult {
+    /** The constructed prompt to send to the agent */
+    prompt: string;
+    /** Resolved skill metadata */
+    skill: SkillMetadata;
+    /** Whether the skill has a preferredProvider that needs switching */
+    providerSwitchNeeded: boolean;
+    /** The preferred provider type (if any) */
+    preferredProvider?: string;
+    /** The preferred model (if any) */
+    preferredModel?: string;
+}
+/**
+ * Invoke a skill by name with the provided arguments.
+ *
+ * This function orchestrates the complete skill invocation flow:
+ * 1. Parses the input to extract skill name and arguments
+ * 2. Looks up the skill in the registry
+ * 3. Substitutes arguments into the skill body
+ * 4. Resolves @path references
+ * 5. Constructs the final prompt
+ * 6. Returns metadata about provider switching if needed
+ *
+ * @param options - Invocation options
+ * @param options.input - Raw "/skillname args" input from user
+ * @param options.registry - The skill registry to look up skills from
+ * @param options.skillsPath - Optional path for @path resolution (defaults to cwd)
+ * @returns SkillInvocationResult or null if no skill matches
+ *
+ * @example
+ * ```ts
+ * const result = await invokeSkill({
+ *   input: '/code-review src/app.ts',
+ *   registry: skillRegistry,
+ * });
+ *
+ * if (result) {
+ *   if (result.providerSwitchNeeded) {
+ *     await switchProvider(result.preferredProvider!, result.preferredModel!);
+ *   }
+ *   await agent.chat(result.prompt);
+ * }
+ * ```
+ */
+export declare function invokeSkill(options: {
+    input: string;
+    registry: SkillRegistry;
+    skillsPath?: string;
+}): Promise<SkillInvocationResult | null>;
+/**
+ * Configuration for creating a skill provider switcher.
+ */
+export interface ProviderSwitcherConfig {
+    /** The current active provider */
+    provider: LLMProvider;
+    /** The current active model name */
+    model: string;
+    /** Available model configurations keyed by provider type */
+    models: Record<string, {
+        apiKey: string;
+        baseUrl?: string;
+        model: string;
+    }>;
+}
+/**
+ * A switcher that temporarily changes the active provider/model based on
+ * skill preferences and can restore the original when done.
+ */
+export interface SkillProviderSwitcher {
+    /** Switch provider if the skill requires it. Returns true if switched. */
+    switchIfNeeded(skillResult: SkillInvocationResult): Promise<boolean>;
+    /** Restore the original provider/model. */
+    restore(): void;
+    /** The current active provider. */
+    readonly activeProvider: LLMProvider;
+    /** The current active model name. */
+    readonly activeModel: string;
+}
+/**
+ * Create a skill provider switcher that captures the original provider/model
+ * state and can temporarily switch based on skill preferences.
+ *
+ * The switcher gracefully handles errors — if provider creation fails,
+ * `switchIfNeeded` returns `false` instead of throwing.
+ *
+ * @example
+ * ```ts
+ * const switcher = createSkillProviderSwitcher({
+ *   provider: currentProvider,
+ *   model: 'gpt-4',
+ *   models: config.models,
+ * });
+ *
+ * const switched = await switcher.switchIfNeeded(skillResult);
+ * try {
+ *   await agent.chat(skillResult.prompt);
+ * } finally {
+ *   if (switched) switcher.restore();
+ * }
+ * ```
+ */
+export declare function createSkillProviderSwitcher(config: ProviderSwitcherConfig): SkillProviderSwitcher;

package/dist/core/skill-invoker.js

@@ -0,0 +1,182 @@
+/**
+ * Skill Invoker — Central orchestrator for skill invocation flow.
+ *
+ * This module consolidates the skill invocation logic that was previously
+ * scattered across the CLI (src/index.ts) and agent (src/agent.ts).
+ *
+ * Invocation flow:
+ * 1. Parse input → extract skill name and arguments
+ * 2. Registry lookup → resolve skill metadata
+ * 3. @path resolution → inline file references
+ * 4. Prompt construction → build the final prompt
+ * 5. Return result with provider switching metadata
+ *
+ * The invoker does NOT handle provider switching itself — it returns
+ * metadata so the adapter can decide whether to switch.
+ */
+import { parseInvocation, substituteArgs } from '../skills/args.js';
+import { limitSkillBody } from '../skills/types.js';
+import { resolveReferences } from '../skills/resolver.js';
+import { createProvider } from '../providers/factory.js';
+/**
+ * Invoke a skill by name with the provided arguments.
+ *
+ * This function orchestrates the complete skill invocation flow:
+ * 1. Parses the input to extract skill name and arguments
+ * 2. Looks up the skill in the registry
+ * 3. Substitutes arguments into the skill body
+ * 4. Resolves @path references
+ * 5. Constructs the final prompt
+ * 6. Returns metadata about provider switching if needed
+ *
+ * @param options - Invocation options
+ * @param options.input - Raw "/skillname args" input from user
+ * @param options.registry - The skill registry to look up skills from
+ * @param options.skillsPath - Optional path for @path resolution (defaults to cwd)
+ * @returns SkillInvocationResult or null if no skill matches
+ *
+ * @example
+ * ```ts
+ * const result = await invokeSkill({
+ *   input: '/code-review src/app.ts',
+ *   registry: skillRegistry,
+ * });
+ *
+ * if (result) {
+ *   if (result.providerSwitchNeeded) {
+ *     await switchProvider(result.preferredProvider!, result.preferredModel!);
+ *   }
+ *   await agent.chat(result.prompt);
+ * }
+ * ```
+ */
+export async function invokeSkill(options) {
+    const { input, registry, skillsPath } = options;
+    // Step 1: Parse the input to extract skill name and arguments
+    const parsed = parseInvocation(input);
+    if (!parsed) {
+        return null;
+    }
+    const { skillName, args } = parsed;
+    // Step 2: Registry lookup
+    const skill = registry.get(skillName);
+    if (!skill) {
+        return null;
+    }
+    // Step 3: Get the skill body
+    const skillBody = await registry.getBody(skillName);
+    if (!skillBody) {
+        return null;
+    }
+    // Step 4: Substitute arguments into skill body
+    const substitutedBody = substituteArgs(skillBody, args);
+    // Step 5: Resolve @path references in the query
+    let resolvedQuery = args.raw;
+    if (args.raw.includes('@')) {
+        try {
+            resolvedQuery = await resolveReferences(args.raw, skillsPath);
+        }
+        catch {
+            // Resolver failed, use raw args
+        }
+    }
+    // Step 6: Enforce body size limits (truncate if necessary)
+    const { body: limitedBody, truncated, originalTokenEstimate, finalTokenEstimate } = limitSkillBody(substitutedBody);
+    if (truncated) {
+        console.warn(`[SKILLS] Skill "${skillName}" body truncated: ` +
+            `${originalTokenEstimate} -> ${finalTokenEstimate} estimated tokens.`);
+    }
+    // Step 7: Construct the final prompt
+    const prompt = resolvedQuery
+        ? `[Skill: ${skill.name} activated]\n\n${limitedBody}\n\nUser request: ${resolvedQuery}`
+        : `[Skill: ${skill.name} activated]\n\n${limitedBody}\n\nSkill loaded. What would you like me to do?`;
+    // Step 8: Extract provider switching metadata
+    const extendedSkill = skill;
+    const modelConfig = extendedSkill.frontmatter?.model;
+    const providerSwitchNeeded = !!modelConfig?.provider;
+    return {
+        prompt,
+        skill: {
+            name: skill.name,
+            description: skill.description,
+            tags: skill.tags,
+        },
+        providerSwitchNeeded,
+        preferredProvider: modelConfig?.provider,
+        preferredModel: modelConfig?.model,
+    };
+}
+/**
+ * Create a skill provider switcher that captures the original provider/model
+ * state and can temporarily switch based on skill preferences.
+ *
+ * The switcher gracefully handles errors — if provider creation fails,
+ * `switchIfNeeded` returns `false` instead of throwing.
+ *
+ * @example
+ * ```ts
+ * const switcher = createSkillProviderSwitcher({
+ *   provider: currentProvider,
+ *   model: 'gpt-4',
+ *   models: config.models,
+ * });
+ *
+ * const switched = await switcher.switchIfNeeded(skillResult);
+ * try {
+ *   await agent.chat(skillResult.prompt);
+ * } finally {
+ *   if (switched) switcher.restore();
+ * }
+ * ```
+ */
+export function createSkillProviderSwitcher(config) {
+    let activeProvider = config.provider;
+    let activeModel = config.model;
+    let originalProvider = null;
+    let originalModel = null;
+    return {
+        get activeProvider() {
+            return activeProvider;
+        },
+        get activeModel() {
+            return activeModel;
+        },
+        async switchIfNeeded(skillResult) {
+            if (!skillResult.providerSwitchNeeded)
+                return false;
+            if (!skillResult.preferredProvider || !skillResult.preferredModel)
+                return false;
+            const providerType = skillResult.preferredProvider;
+            const providerModelConfig = config.models[providerType];
+            if (!providerModelConfig?.apiKey)
+                return false;
+            try {
+                const newProvider = await createProvider({
+                    type: providerType,
+                    apiKey: providerModelConfig.apiKey,
+                    model: skillResult.preferredModel,
+                    baseUrl: providerModelConfig.baseUrl,
+                });
+                // Capture originals before overwriting (only on first switch)
+                if (!originalProvider) {
+                    originalProvider = activeProvider;
+                    originalModel = activeModel;
+                }
+                activeProvider = newProvider;
+                activeModel = skillResult.preferredModel;
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        restore() {
+            if (originalProvider) {
+                activeProvider = originalProvider;
+                activeModel = originalModel ?? activeModel;
+                originalProvider = null;
+                originalModel = null;
+            }
+        },
+    };
+}

package/dist/core/stream-accumulator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * StreamingResponseAccumulator — reassembles a complete `ProviderResponse`
+ * ({ content, tool_calls }) from a stream of `StreamDelta`s.
+ *
+ * Provider streams frequently split a tool call's JSON `arguments` across many
+ * deltas; this buffers each tool call by index and concatenates the fragments,
+ * so `runAgentLoop` receives well-formed, complete tool calls to execute.
+ */
+import type { ProviderResponse } from '../providers/types.js';
+import type { Usage } from './types.js';
+export declare class StreamingResponseAccumulator {
+    private text;
+    private toolCalls;
+    private usage;
+    appendText(delta: string): void;
+    beginToolCall(index: number, id: string, name: string): void;
+    appendToolCallArgs(index: number, argsDelta: string): void;
+    setUsage(usage: Usage): void;
+    getUsage(): Usage | undefined;
+    toResponse(): ProviderResponse;
+}

package/dist/core/stream-accumulator.js

@@ -0,0 +1,51 @@
+/**
+ * StreamingResponseAccumulator — reassembles a complete `ProviderResponse`
+ * ({ content, tool_calls }) from a stream of `StreamDelta`s.
+ *
+ * Provider streams frequently split a tool call's JSON `arguments` across many
+ * deltas; this buffers each tool call by index and concatenates the fragments,
+ * so `runAgentLoop` receives well-formed, complete tool calls to execute.
+ */
+export class StreamingResponseAccumulator {
+    text = '';
+    toolCalls = new Map();
+    usage;
+    appendText(delta) {
+        this.text += delta;
+    }
+    beginToolCall(index, id, name) {
+        const existing = this.toolCalls.get(index);
+        if (existing) {
+            existing.id = id || existing.id;
+            existing.name = name || existing.name;
+        }
+        else {
+            this.toolCalls.set(index, { index, id, name, argumentsBuffer: '' });
+        }
+    }
+    appendToolCallArgs(index, argsDelta) {
+        const tc = this.toolCalls.get(index);
+        if (tc) {
+            tc.argumentsBuffer += argsDelta;
+        }
+        else {
+            // delta arrived before begin — create a placeholder at this index
+            this.toolCalls.set(index, { index, id: '', name: '', argumentsBuffer: argsDelta });
+        }
+    }
+    setUsage(usage) {
+        this.usage = usage;
+    }
+    getUsage() {
+        return this.usage;
+    }
+    toResponse() {
+        const tool_calls = [...this.toolCalls.values()]
+            .sort((a, b) => a.index - b.index)
+            .map((tc) => ({ id: tc.id, name: tc.name, arguments: tc.argumentsBuffer }));
+        return {
+            content: this.text || undefined,
+            tool_calls: tool_calls.length > 0 ? tool_calls : undefined,
+        };
+    }
+}