zoe-agent 0.3.1

package/dist/gateway/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Zoe Gateway — Type definitions
+ *
+ * Types for MCP targets, REST targets, audit records, and gateway config.
+ * Reuses Zoe's existing ToolModule and ToolDefinition from src/tools/interface.ts.
+ */
+export type AuthType = 'none' | 'header' | 'bearer' | 'query' | 'basic';
+export type McpTransportType = 'stdio' | 'sse' | 'http';
+export interface RestTarget {
+    kind: 'rest';
+    baseUrl: string;
+    description: string;
+    auth: {
+        type: AuthType;
+        name?: string;
+        credentialRef?: string;
+    };
+    defaultHeaders: Record<string, string>;
+    operations: Array<{
+        opId: string;
+        method: string;
+        path: string;
+        summary: string;
+    }>;
+    tags: string[];
+    enabled: boolean;
+}
+export interface McpTarget {
+    kind: 'mcp';
+    transport: McpTransportType;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    auth?: {
+        type: AuthType;
+        name?: string;
+        credentialRef?: string;
+    };
+    description: string;
+    tags: string[];
+    enabled: boolean;
+    capabilities?: {
+        tools?: any[];
+        resources?: any[];
+        prompts?: any[];
+    };
+}
+export type Target = RestTarget | McpTarget;
+export interface AuditRecord {
+    timestamp: number;
+    agent: string;
+    target: string;
+    operation: string;
+    status: string;
+    durationMs: number;
+    success: boolean;
+}
+export interface GatewayHooks {
+    onAudit?: (record: AuditRecord) => void | Promise<void>;
+    onSamplingRequest?: (params: any) => Promise<any>;
+}
+export interface GatewayConfig {
+    enabled: boolean;
+    semanticTopK: number;
+    defaultRateLimitPerMin: number;
+    maxAuditLogsInMemory: number;
+}

package/dist/gateway/types.js

@@ -0,0 +1,7 @@
+/**
+ * Zoe Gateway — Type definitions
+ *
+ * Types for MCP targets, REST targets, audit records, and gateway config.
+ * Reuses Zoe's existing ToolModule and ToolDefinition from src/tools/interface.ts.
+ */
+export {};

package/dist/models-catalog.js

@@ -0,0 +1,46 @@
+const M = (id, name, contextWindow, input, output) => ({
+    id, name, contextWindow, pricing: { input, output },
+});
+export const MODEL_CATALOG = {
+    'openai-compatible': [], // No curated list — user provides their own model name
+    openai: [
+        M('gpt-5.4', 'GPT-5.4', 256000, 2.5, 10),
+        M('gpt-5.4-pro', 'GPT-5.4 Pro', 256000, 5, 20),
+        M('gpt-5.4-mini', 'GPT-5.4 Mini', 128000, 0.15, 0.6),
+        M('gpt-5.4-nano', 'GPT-5.4 Nano', 128000, 0.05, 0.2),
+        M('gpt-5.3-instant', 'GPT-5.3 Instant', 128000, 0.5, 2),
+        M('gpt-5.3-codex', 'GPT-5.3 Codex', 256000, 2, 8),
+        M('o3', 'o3', 200000, 5, 15),
+        M('o3-mini', 'o3 Mini', 200000, 1, 4),
+    ],
+    anthropic: [
+        M('claude-sonnet-4-6-20260320', 'Claude Sonnet 4.6', 200000, 3, 15),
+        M('claude-opus-4-6-20260320', 'Claude Opus 4.6', 200000, 15, 75),
+        M('claude-haiku-4-5-20251001', 'Claude Haiku 4.5', 200000, 0.8, 4),
+    ],
+    glm: [
+        M('haiku', 'GLM-4.5 Air', 128000, 0.5, 1.5),
+        M('sonnet', 'GLM-4.7', 128000, 1, 3),
+        M('opus', 'GLM-5.1', 128000, 2, 6),
+    ],
+};
+export const CUSTOM_MODEL_VALUE = '__custom__';
+/**
+ * Default model ID for each provider.
+ * Single source of truth — all other files import from here.
+ */
+export const DEFAULT_MODELS = {
+    openai: 'gpt-5.4',
+    anthropic: 'claude-sonnet-4-6-20260320',
+    glm: 'opus',
+    'openai-compatible': 'gpt-5.4',
+};
+/** Look up a model's metadata (context window + pricing) by id, across providers. */
+export function getModelMeta(id) {
+    for (const list of Object.values(MODEL_CATALOG)) {
+        const found = list.find((m) => m.id === id);
+        if (found)
+            return found;
+    }
+    return undefined;
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,22 @@
+import { ProviderMessage, ProviderResponse, LLMProvider, ChatOptions, StreamDelta } from './types.js';
+import type { ToolDefinition } from '../tools/interface.js';
+export declare class AnthropicProvider implements LLMProvider {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string, options?: {
+        baseURL?: string;
+        timeout?: number;
+    });
+    /**
+     * Translate Zoe messages + tools into Anthropic's request shape. Shared by
+     * `chat()` and `chatStream()` so the (non-trivial) translation lives once.
+     */
+    private buildRequest;
+    chat(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): Promise<ProviderResponse>;
+    /**
+     * Stream the response via Anthropic's message stream. Text blocks yield
+     * `text_delta`; tool_use blocks yield `tool_call_begin` (on block start) then
+     * `tool_call_delta` for each `input_json_delta` fragment, keyed by block index.
+     */
+    chatStream(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): AsyncIterable<StreamDelta>;
+}

package/dist/providers/anthropic.js

@@ -0,0 +1,148 @@
+import Anthropic from '@anthropic-ai/sdk';
+export class AnthropicProvider {
+    client;
+    model;
+    constructor(apiKey, model, options) {
+        this.client = new Anthropic({
+            apiKey,
+            baseURL: options?.baseURL,
+            timeout: options?.timeout,
+        });
+        this.model = model;
+    }
+    /**
+     * Translate Zoe messages + tools into Anthropic's request shape. Shared by
+     * `chat()` and `chatStream()` so the (non-trivial) translation lives once.
+     */
+    buildRequest(messages, tools) {
+        const systemParts = [];
+        const nonSystem = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                if (msg.content)
+                    systemParts.push(msg.content);
+            }
+            else {
+                nonSystem.push(msg);
+            }
+        }
+        const anthropicMessages = [];
+        for (const msg of nonSystem) {
+            if (msg.role === 'assistant' && msg.tool_calls?.length) {
+                const content = [];
+                if (msg.content)
+                    content.push({ type: 'text', text: msg.content });
+                for (const tc of msg.tool_calls) {
+                    content.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.name,
+                        input: JSON.parse(tc.arguments),
+                    });
+                }
+                anthropicMessages.push({ role: 'assistant', content });
+            }
+            else if (msg.role === 'tool') {
+                anthropicMessages.push({
+                    role: 'user',
+                    content: [{
+                            type: 'tool_result',
+                            tool_use_id: msg.tool_call_id,
+                            content: msg.content ?? '',
+                        }],
+                });
+            }
+            else {
+                anthropicMessages.push({
+                    role: msg.role,
+                    content: msg.content ?? '',
+                });
+            }
+        }
+        const anthropicTools = tools.map((t) => ({
+            name: t.function.name,
+            description: t.function.description,
+            input_schema: t.function.parameters,
+        }));
+        return {
+            system: systemParts.length ? systemParts.join('\n') : undefined,
+            anthropicMessages,
+            anthropicTools,
+        };
+    }
+    async chat(messages, tools, options) {
+        const { system, anthropicMessages, anthropicTools } = this.buildRequest(messages, tools);
+        const response = await this.client.messages.create({
+            model: this.model,
+            max_tokens: 16384,
+            system,
+            messages: anthropicMessages,
+            tools: anthropicTools,
+        }, { signal: options?.signal });
+        // Translate response
+        let content;
+        const toolCalls = [];
+        for (const block of response.content) {
+            if (block.type === 'text') {
+                content = content ? content + block.text : block.text;
+            }
+            else if (block.type === 'tool_use') {
+                toolCalls.push({
+                    id: block.id,
+                    name: block.name,
+                    arguments: JSON.stringify(block.input),
+                });
+            }
+        }
+        return {
+            content: content || undefined,
+            tool_calls: toolCalls.length ? toolCalls : undefined,
+        };
+    }
+    /**
+     * Stream the response via Anthropic's message stream. Text blocks yield
+     * `text_delta`; tool_use blocks yield `tool_call_begin` (on block start) then
+     * `tool_call_delta` for each `input_json_delta` fragment, keyed by block index.
+     */
+    async *chatStream(messages, tools, options) {
+        const { system, anthropicMessages, anthropicTools } = this.buildRequest(messages, tools);
+        const stream = this.client.messages.stream({
+            model: this.model,
+            max_tokens: 16384,
+            system,
+            messages: anthropicMessages,
+            tools: anthropicTools,
+        }, { signal: options?.signal });
+        for await (const event of stream) {
+            if (event.type === 'content_block_start' && event.content_block.type === 'tool_use') {
+                yield {
+                    type: 'tool_call_begin',
+                    index: event.index,
+                    id: event.content_block.id,
+                    name: event.content_block.name,
+                };
+            }
+            else if (event.type === 'content_block_delta') {
+                if (event.delta.type === 'text_delta') {
+                    yield { type: 'text_delta', content: event.delta.text };
+                }
+                else if (event.delta.type === 'input_json_delta') {
+                    yield { type: 'tool_call_delta', index: event.index, argumentsDelta: event.delta.partial_json };
+                }
+            }
+            else if (event.type === 'message_delta' && event.usage) {
+                const inputTokens = event.usage.input_tokens ?? 0;
+                const outputTokens = event.usage.output_tokens ?? 0;
+                yield {
+                    type: 'finish',
+                    usage: {
+                        promptTokens: inputTokens,
+                        completionTokens: outputTokens,
+                        totalTokens: inputTokens + outputTokens,
+                        cost: 0,
+                    },
+                };
+            }
+        }
+    }
+}

package/dist/providers/factory.d.ts

@@ -0,0 +1,10 @@
+import { ProviderType, LLMProvider } from './types.js';
+export interface ProviderConfig {
+    type: ProviderType;
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+export declare const GLM_MODEL_MAP: Record<string, string>;
+export declare function createProvider(config: ProviderConfig): Promise<LLMProvider>;

package/dist/providers/factory.js

@@ -0,0 +1,25 @@
+export const GLM_MODEL_MAP = {
+    haiku: 'glm-4.5-air',
+    sonnet: 'glm-4.7',
+    opus: 'glm-5.1',
+};
+export async function createProvider(config) {
+    switch (config.type) {
+        case 'openai': {
+            const { OpenAIProvider } = await import('./openai.js');
+            return new OpenAIProvider(config.apiKey, config.model, 'https://api.openai.com/v1');
+        }
+        case 'openai-compatible': {
+            const { OpenAIProvider } = await import('./openai.js');
+            return new OpenAIProvider(config.apiKey, config.model, config.baseUrl);
+        }
+        case 'anthropic': {
+            const { AnthropicProvider } = await import('./anthropic.js');
+            return new AnthropicProvider(config.apiKey, config.model);
+        }
+        case 'glm': {
+            const { AnthropicProvider } = await import('./anthropic.js');
+            return new AnthropicProvider(config.apiKey, GLM_MODEL_MAP[config.model] || config.model, { baseURL: 'https://api.z.ai/api/anthropic', timeout: 3000000 });
+        }
+    }
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,15 @@
+import { ProviderMessage, ProviderResponse, LLMProvider, ChatOptions, StreamDelta } from './types.js';
+import type { ToolDefinition } from '../tools/interface.js';
+export declare class OpenAIProvider implements LLMProvider {
+    private client;
+    private model;
+    constructor(apiKey: string, model: string, baseURL?: string);
+    chat(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): Promise<ProviderResponse>;
+    /**
+     * Stream the response using the OpenAI SDK's native streaming. Maps chunks to
+     * `StreamDelta`s: text deltas, tool-call begin (id+name on the first chunk)
+     * and argument fragments (subsequent chunks, keyed by `index`), and a final
+     * `finish` with usage (when `stream_options.include_usage` is set).
+     */
+    chatStream(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): AsyncIterable<StreamDelta>;
+}

package/dist/providers/openai.js

@@ -0,0 +1,71 @@
+import { OpenAI } from 'openai';
+export class OpenAIProvider {
+    client;
+    model;
+    constructor(apiKey, model, baseURL) {
+        this.client = new OpenAI({ apiKey, baseURL });
+        this.model = model;
+    }
+    async chat(messages, tools, options) {
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            messages: messages,
+            tools: tools,
+        }, { signal: options?.signal });
+        const message = response.choices[0]?.message;
+        if (!message)
+            return {};
+        return {
+            content: message.content ?? undefined,
+            tool_calls: message.tool_calls
+                ?.filter((tc) => tc.type === 'function')
+                .map((tc) => ({
+                id: tc.id,
+                name: tc.function.name,
+                arguments: tc.function.arguments,
+            })),
+        };
+    }
+    /**
+     * Stream the response using the OpenAI SDK's native streaming. Maps chunks to
+     * `StreamDelta`s: text deltas, tool-call begin (id+name on the first chunk)
+     * and argument fragments (subsequent chunks, keyed by `index`), and a final
+     * `finish` with usage (when `stream_options.include_usage` is set).
+     */
+    async *chatStream(messages, tools, options) {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages: messages,
+            tools: tools,
+            stream: true,
+            stream_options: { include_usage: true },
+        }, { signal: options?.signal });
+        for await (const chunk of stream) {
+            const delta = chunk.choices[0]?.delta;
+            if (delta?.content) {
+                yield { type: 'text_delta', content: delta.content };
+            }
+            if (delta?.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    if (tc.function?.name) {
+                        yield { type: 'tool_call_begin', index: tc.index, id: tc.id ?? '', name: tc.function.name };
+                    }
+                    if (tc.function?.arguments) {
+                        yield { type: 'tool_call_delta', index: tc.index, argumentsDelta: tc.function.arguments };
+                    }
+                }
+            }
+            if (chunk.usage) {
+                yield {
+                    type: 'finish',
+                    usage: {
+                        promptTokens: chunk.usage.prompt_tokens,
+                        completionTokens: chunk.usage.completion_tokens,
+                        totalTokens: chunk.usage.total_tokens,
+                        cost: 0,
+                    },
+                };
+            }
+        }
+    }
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,48 @@
+export type { ProviderType } from "../core/types.js";
+import type { ToolDefinition } from '../tools/interface.js';
+import type { Usage } from '../core/types.js';
+export interface ProviderMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string;
+    tool_calls?: ProviderToolCall[];
+    tool_call_id?: string;
+}
+export interface ProviderToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface ProviderResponse {
+    content?: string;
+    tool_calls?: ProviderToolCall[];
+}
+export interface ChatOptions {
+    signal?: AbortSignal;
+}
+/**
+ * A single chunk from a streaming model response. Providers split a response
+ * across many deltas — text arrives token-by-token, and a tool call's JSON
+ * arguments usually arrive fragmented. `runAgentLoop` reassembles these via
+ * `StreamingResponseAccumulator`.
+ */
+export type StreamDelta = {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'tool_call_begin';
+    index: number;
+    id: string;
+    name: string;
+} | {
+    type: 'tool_call_delta';
+    index: number;
+    argumentsDelta: string;
+} | {
+    type: 'finish';
+    usage?: Usage;
+};
+export interface LLMProvider {
+    chat(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): Promise<ProviderResponse>;
+    /** Optional streaming variant. Absent → callers fall back to `chat()`. */
+    chatStream?(messages: ProviderMessage[], tools: ToolDefinition[], options?: ChatOptions): AsyncIterable<StreamDelta>;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/skills/args.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dynamic argument parsing and template substitution for skills.
+ *
+ * Supports:
+ * - $1, $2, ... — positional arguments
+ * - $ALL — all arguments as a single string
+ * - $COUNT — number of arguments
+ * - $FIRST — first argument
+ * - $LAST — last argument
+ */
+export interface ParsedArgs {
+    positional: string[];
+    raw: string;
+}
+/**
+ * Parse a user input string into a skill name and arguments.
+ * Handles quoted strings for multi-word arguments.
+ *
+ * @example
+ * parseInvocation('/docker-ops build myapp:1.2.0 --no-cache')
+ * // => { skillName: 'docker-ops', args: { positional: ['build', 'myapp:1.2.0', '--no-cache'], raw: 'build myapp:1.2.0 --no-cache' } }
+ */
+export declare function parseInvocation(input: string): {
+    skillName: string;
+    args: ParsedArgs;
+} | null;
+/**
+ * Substitute template variables in a skill body with actual arguments.
+ *
+ * Supported variables:
+ * - $1, $2, ..., $N — positional arguments (1-indexed)
+ * - $ALL — all arguments joined as a string
+ * - $COUNT — number of arguments
+ * - $FIRST — first argument (same as $1)
+ * - $LAST — last argument
+ */
+export declare function substituteArgs(body: string, args: ParsedArgs): string;

package/dist/skills/args.js

@@ -0,0 +1,99 @@
+/**
+ * Dynamic argument parsing and template substitution for skills.
+ *
+ * Supports:
+ * - $1, $2, ... — positional arguments
+ * - $ALL — all arguments as a single string
+ * - $COUNT — number of arguments
+ * - $FIRST — first argument
+ * - $LAST — last argument
+ */
+/**
+ * Parse a user input string into a skill name and arguments.
+ * Handles quoted strings for multi-word arguments.
+ *
+ * @example
+ * parseInvocation('/docker-ops build myapp:1.2.0 --no-cache')
+ * // => { skillName: 'docker-ops', args: { positional: ['build', 'myapp:1.2.0', '--no-cache'], raw: 'build myapp:1.2.0 --no-cache' } }
+ */
+export function parseInvocation(input) {
+    if (!input.startsWith('/') || input.length < 2)
+        return null;
+    const body = input.slice(1);
+    const firstSpace = body.search(/\s/);
+    if (firstSpace === -1) {
+        return { skillName: body, args: { positional: [], raw: '' } };
+    }
+    const skillName = body.slice(0, firstSpace);
+    const argsRaw = body.slice(firstSpace + 1).trim();
+    return {
+        skillName,
+        args: {
+            positional: splitArgs(argsRaw),
+            raw: argsRaw,
+        },
+    };
+}
+/**
+ * Split argument string respecting quoted strings.
+ */
+function splitArgs(input) {
+    const args = [];
+    let current = '';
+    let inQuote = false;
+    let quoteChar = '';
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (inQuote) {
+            if (ch === quoteChar) {
+                inQuote = false;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            inQuote = true;
+            quoteChar = ch;
+        }
+        else if (ch === ' ') {
+            if (current) {
+                args.push(current);
+                current = '';
+            }
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current)
+        args.push(current);
+    return args;
+}
+/**
+ * Substitute template variables in a skill body with actual arguments.
+ *
+ * Supported variables:
+ * - $1, $2, ..., $N — positional arguments (1-indexed)
+ * - $ALL — all arguments joined as a string
+ * - $COUNT — number of arguments
+ * - $FIRST — first argument (same as $1)
+ * - $LAST — last argument
+ */
+export function substituteArgs(body, args) {
+    let result = body;
+    // $ALL — all arguments as a single string
+    result = result.replace(/\$ALL\b/g, args.raw);
+    // $COUNT — number of arguments
+    result = result.replace(/\$COUNT\b/g, String(args.positional.length));
+    // $FIRST — first argument
+    result = result.replace(/\$FIRST\b/g, args.positional[0] || '');
+    // $LAST — last argument
+    result = result.replace(/\$LAST\b/g, args.positional[args.positional.length - 1] || '');
+    // $N — positional arguments (must process AFTER $ALL, $COUNT etc. to avoid conflicts)
+    // Replace from highest index down to avoid $10 being matched as $1
+    for (let i = args.positional.length; i >= 1; i--) {
+        result = result.replace(new RegExp(`\\$${i}\\b`, 'g'), args.positional[i - 1]);
+    }
+    return result;
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,11 @@
+export type { Skill, SkillFrontmatter, SkillMetadata, SkillRegistry, SkillModelConfig, TruncationResult } from './types.js';
+export { parseSkillFile, parseFrontmatter } from './parser.js';
+export { discoverSkills, getSkillPaths } from './loader.js';
+export { DefaultSkillRegistry } from './registry.js';
+export { parseInvocation, substituteArgs } from './args.js';
+export type { ParsedArgs } from './args.js';
+export { resolveReferences } from './resolver.js';
+export { limitSkillBody, getSkillBodyLimits } from './types.js';
+import { SkillRegistry } from './types.js';
+export declare function initializeSkillRegistry(cwd: string): Promise<SkillRegistry>;
+export declare function getSkillRegistry(): SkillRegistry | null;

package/dist/skills/index.js

@@ -0,0 +1,23 @@
+export { parseSkillFile, parseFrontmatter } from './parser.js';
+export { discoverSkills, getSkillPaths } from './loader.js';
+export { DefaultSkillRegistry } from './registry.js';
+export { parseInvocation, substituteArgs } from './args.js';
+export { resolveReferences } from './resolver.js';
+export { limitSkillBody, getSkillBodyLimits } from './types.js';
+import { discoverSkills } from './loader.js';
+import { DefaultSkillRegistry } from './registry.js';
+let registry = null;
+export async function initializeSkillRegistry(cwd) {
+    const skills = await discoverSkills(cwd);
+    registry = new DefaultSkillRegistry(skills);
+    if (process.env.ZOE_SKILLS_DEBUG) {
+        console.log(`[SKILLS] Loaded ${skills.length} skills`);
+        for (const s of skills) {
+            console.log(`[SKILLS]   - ${s.name} from ${s.source}`);
+        }
+    }
+    return registry;
+}
+export function getSkillRegistry() {
+    return registry;
+}

package/dist/skills/loader.d.ts

@@ -0,0 +1,3 @@
+import { Skill } from './types.js';
+export declare function getSkillPaths(cwd: string): string[];
+export declare function discoverSkills(cwd: string): Promise<Skill[]>;