zoe-agent 0.3.1

package/dist/core/config.js

@@ -0,0 +1,189 @@
+/**
+ * Zoe Core — Config Utilities
+ *
+ * Config loading, merging, and environment overrides.
+ * Chalk-free — suitable for all adapters (CLI, SDK, Server).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { DEFAULT_MODELS } from '../models-catalog.js';
+// ── Constants ──────────────────────────────────────────────────────────
+const GLOBAL_CONFIG_DIR = path.join(os.homedir(), '.zoe');
+const GLOBAL_CONFIG_FILE = path.join(GLOBAL_CONFIG_DIR, 'setting.json');
+const LOCAL_CONFIG_FILE = path.join(process.cwd(), '.zoe', 'setting.json');
+// ── Config path helpers ────────────────────────────────────────────────
+/**
+ * Returns the config file path for the given scope.
+ */
+export function getConfigPath(global) {
+    return global ? GLOBAL_CONFIG_FILE : LOCAL_CONFIG_FILE;
+}
+/**
+ * Returns the config directory path for the given scope.
+ */
+export function getConfigDir(global) {
+    return global ? GLOBAL_CONFIG_DIR : path.join(process.cwd(), '.zoe');
+}
+/**
+ * Returns both global and local config paths.
+ */
+export function getConfigPaths() {
+    return {
+        global: GLOBAL_CONFIG_FILE,
+        local: LOCAL_CONFIG_FILE,
+        globalDir: GLOBAL_CONFIG_DIR,
+    };
+}
+// ── JSON loading ───────────────────────────────────────────────────────
+/**
+ * Load and parse a JSON config file.
+ * Returns `{ config, warning }` — warning is set if parsing failed.
+ */
+export function loadJsonConfig(filePath) {
+    if (fs.existsSync(filePath)) {
+        try {
+            return { config: JSON.parse(fs.readFileSync(filePath, 'utf-8')) };
+        }
+        catch (e) {
+            return {
+                config: {},
+                warning: `Warning: Failed to parse config file at ${filePath}`,
+            };
+        }
+    }
+    return { config: {} };
+}
+// ── Merge & overlay ────────────────────────────────────────────────────
+/**
+ * Load global and local configs and merge them.
+ * Priority: local > global.
+ */
+export function loadMergedConfig() {
+    const global = loadJsonConfig(GLOBAL_CONFIG_FILE);
+    const local = loadJsonConfig(LOCAL_CONFIG_FILE);
+    return { ...global.config, ...local.config };
+}
+/**
+ * Apply environment variable overrides to the merged config.
+ * Env vars take priority over JSON config for tool settings.
+ * Also injects provider API keys from env vars into the models map.
+ */
+export function applyEnvOverrides(config) {
+    // Tool settings
+    if (process.env.SMTP_HOST)
+        config.smtpHost = process.env.SMTP_HOST;
+    if (process.env.SMTP_PORT)
+        config.smtpPort = process.env.SMTP_PORT;
+    if (process.env.SMTP_USER)
+        config.smtpUser = process.env.SMTP_USER;
+    if (process.env.SMTP_PASS)
+        config.smtpPass = process.env.SMTP_PASS;
+    if (process.env.TAVILY_API_KEY)
+        config.tavilyApiKey = process.env.TAVILY_API_KEY;
+    if (process.env.FEISHU_WEBHOOK)
+        config.feishuWebhook = process.env.FEISHU_WEBHOOK;
+    if (process.env.FEISHU_KEYWORD)
+        config.feishuKeyword = process.env.FEISHU_KEYWORD;
+    if (process.env.DINGTALK_WEBHOOK)
+        config.dingtalkWebhook = process.env.DINGTALK_WEBHOOK;
+    if (process.env.DINGTALK_KEYWORD)
+        config.dingtalkKeyword = process.env.DINGTALK_KEYWORD;
+    if (process.env.WECOM_WEBHOOK)
+        config.wecomWebhook = process.env.WECOM_WEBHOOK;
+    if (process.env.WECOM_KEYWORD)
+        config.wecomKeyword = process.env.WECOM_KEYWORD;
+    // Permission level
+    if (process.env.ZOE_PERMISSION) {
+        const val = process.env.ZOE_PERMISSION;
+        if (val === "strict" || val === "moderate" || val === "permissive") {
+            config.permissionLevel = val;
+        }
+    }
+    // Provider API keys — inject into models map from env vars
+    if (!config.models)
+        config.models = {};
+    if (process.env.OPENAI_API_KEY) {
+        config.models.openai = {
+            apiKey: process.env.OPENAI_API_KEY,
+            model: process.env.OPENAI_MODEL || config.models.openai?.model || DEFAULT_MODELS.openai,
+        };
+    }
+    if (process.env.OPENAI_COMPAT_API_KEY) {
+        config.models['openai-compatible'] = {
+            apiKey: process.env.OPENAI_COMPAT_API_KEY,
+            baseUrl: process.env.OPENAI_COMPAT_BASE_URL || process.env.OPENAI_BASE_URL || config.models['openai-compatible']?.baseUrl || 'https://api.openai.com/v1',
+            model: process.env.OPENAI_COMPAT_MODEL || process.env.LLM_MODEL || process.env.ZOE_MODEL || config.models['openai-compatible']?.model || DEFAULT_MODELS['openai-compatible'],
+        };
+    }
+    if (process.env.ANTHROPIC_API_KEY) {
+        config.models.anthropic = {
+            apiKey: process.env.ANTHROPIC_API_KEY,
+            model: process.env.ANTHROPIC_MODEL || config.models.anthropic?.model || DEFAULT_MODELS.anthropic,
+        };
+    }
+    if (process.env.GLM_API_KEY) {
+        config.models.glm = {
+            apiKey: process.env.GLM_API_KEY,
+            model: process.env.GLM_MODEL || config.models.glm?.model || DEFAULT_MODELS.glm,
+        };
+    }
+    return config;
+}
+/**
+ * Auto-migrate legacy config format (top-level apiKey/baseUrl/model) to the
+ * models map format used by the current architecture.
+ */
+export function migrateLegacyFormat(config, options) {
+    if (!config.models && (config.apiKey || process.env.OPENAI_API_KEY)) {
+        config.models = {
+            openai: {
+                apiKey: process.env.OPENAI_API_KEY || config.apiKey || '',
+                model: options?.model || process.env.OPENAI_MODEL || config.model || DEFAULT_MODELS.openai,
+            },
+        };
+        if (!config.provider)
+            config.provider = 'openai';
+    }
+    return config;
+}
+/**
+ * Resolve the active provider type from CLI flags, env vars, and config.
+ * Checks LLM_PROVIDER env var as a standard alias for ZOE_PROVIDER.
+ */
+export function resolveActiveProviderType(config, options) {
+    return (options?.provider ||
+        process.env.LLM_PROVIDER ||
+        process.env.ZOE_PROVIDER ||
+        config.provider ||
+        'openai');
+}
+// ── Save ───────────────────────────────────────────────────────────────
+/**
+ * Save config to disk. If a local config exists, saves there; otherwise global.
+ */
+export function saveConfig(config) {
+    const targetFile = fs.existsSync(path.join(process.cwd(), '.zoe', 'setting.json'))
+        ? LOCAL_CONFIG_FILE
+        : GLOBAL_CONFIG_FILE;
+    writeConfigToPath(config, targetFile);
+}
+/**
+ * Save config to a specific path.
+ * Throws on failure — callers handle error display.
+ */
+export function writeConfigToPath(config, targetFile) {
+    const dir = path.dirname(targetFile);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(targetFile, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+// ── Utility ────────────────────────────────────────────────────────────
+/**
+ * Mask a secret string for display, showing only first 3 and last 4 chars.
+ */
+export function maskSecret(secret) {
+    if (!secret || secret.length < 8)
+        return '******';
+    return `${secret.slice(0, 3)}...${secret.slice(-4)}`;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Zoe Core — Error class hierarchy
+ *
+ * Proper class hierarchy for all Zoe errors.
+ * Each error class carries a `code`, `retryable` flag, and domain-specific
+ * metadata (e.g. `provider`, `tool`, `steps`).
+ */
+/**
+ * Base class for all Zoe errors.
+ *
+ * Carries a machine-readable `code` and a `retryable` flag so callers can
+ * decide whether to retry automatically.
+ */
+export declare class ZoeError extends Error {
+    /** Machine-readable error code, e.g. "PROVIDER_ERROR", "TOOL_FAILED". */
+    code: string;
+    /** Whether the operation that caused this error can be retried. */
+    retryable: boolean;
+    constructor(message: string, code: string, retryable?: boolean);
+}
+/**
+ * Error originating from a provider (LLM API call failure, auth, rate-limit, etc.).
+ */
+export declare class ProviderError extends ZoeError {
+    /** The provider name that produced the error, if known. */
+    provider?: string;
+    constructor(message: string, provider?: string);
+}
+/**
+ * Error from tool execution.
+ */
+export declare class ToolError extends ZoeError {
+    /** The tool name that produced the error, if known. */
+    tool?: string;
+    constructor(message: string, tool?: string);
+}
+/**
+ * Thrown when the agent loop exceeds the configured maximum number of steps.
+ */
+export declare class MaxStepsError extends ZoeError {
+    /** The number of steps that were executed. */
+    steps: number;
+    constructor(steps: number, maxSteps: number);
+}
+/**
+ * Thrown when an operation is aborted (e.g. via AbortSignal).
+ */
+export declare class AbortedError extends ZoeError {
+    constructor(message?: string);
+}
+/**
+ * Error from gateway operations (MCP client, REST proxy, target management).
+ */
+export declare class GatewayError extends ZoeError {
+    /** The target name that produced the error, if known. */
+    target?: string;
+    constructor(message: string, target?: string, retryable?: boolean);
+}

package/dist/core/errors.js

@@ -0,0 +1,88 @@
+/**
+ * Zoe Core — Error class hierarchy
+ *
+ * Proper class hierarchy for all Zoe errors.
+ * Each error class carries a `code`, `retryable` flag, and domain-specific
+ * metadata (e.g. `provider`, `tool`, `steps`).
+ */
+// ── Base error ──────────────────────────────────────────────────────────
+/**
+ * Base class for all Zoe errors.
+ *
+ * Carries a machine-readable `code` and a `retryable` flag so callers can
+ * decide whether to retry automatically.
+ */
+export class ZoeError extends Error {
+    /** Machine-readable error code, e.g. "PROVIDER_ERROR", "TOOL_FAILED". */
+    code;
+    /** Whether the operation that caused this error can be retried. */
+    retryable;
+    constructor(message, code, retryable = false) {
+        super(message);
+        this.name = "ZoeError";
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+// ── Provider errors ─────────────────────────────────────────────────────
+/**
+ * Error originating from a provider (LLM API call failure, auth, rate-limit, etc.).
+ */
+export class ProviderError extends ZoeError {
+    /** The provider name that produced the error, if known. */
+    provider;
+    constructor(message, provider) {
+        super(message, "PROVIDER_ERROR", true);
+        this.name = "ProviderError";
+        this.provider = provider;
+    }
+}
+// ── Tool errors ─────────────────────────────────────────────────────────
+/**
+ * Error from tool execution.
+ */
+export class ToolError extends ZoeError {
+    /** The tool name that produced the error, if known. */
+    tool;
+    constructor(message, tool) {
+        super(message, "TOOL_FAILED", true);
+        this.name = "ToolError";
+        this.tool = tool;
+    }
+}
+// ── Max steps ───────────────────────────────────────────────────────────
+/**
+ * Thrown when the agent loop exceeds the configured maximum number of steps.
+ */
+export class MaxStepsError extends ZoeError {
+    /** The number of steps that were executed. */
+    steps;
+    constructor(steps, maxSteps) {
+        super(`Maximum steps reached (${steps}/${maxSteps})`, "MAX_STEPS", false);
+        this.name = "MaxStepsError";
+        this.steps = steps;
+    }
+}
+// ── Aborted ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when an operation is aborted (e.g. via AbortSignal).
+ */
+export class AbortedError extends ZoeError {
+    constructor(message) {
+        super(message ?? "Operation was aborted", "ABORTED", false);
+        this.name = "AbortedError";
+    }
+}
+// ── Gateway errors ──────────────────────────────────────────────────────
+/**
+ * Error from gateway operations (MCP client, REST proxy, target management).
+ */
+export class GatewayError extends ZoeError {
+    /** The target name that produced the error, if known. */
+    target;
+    constructor(message, target, retryable = true) {
+        super(message, "GATEWAY_ERROR", retryable);
+        this.name = "GatewayError";
+        this.target = target;
+    }
+}

package/dist/core/hooks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Zoe SDK — Hook executor
+ *
+ * Wraps a user-supplied `Hooks` object in a safe executor that:
+ *  - treats missing hooks as no-ops
+ *  - awaits async hooks
+ *  - catches and logs hook errors without failing the main flow
+ */
+import type { Hooks, StepResult, ZoeError, GenerateTextResult } from "./types.js";
+export interface HookExecutor {
+    beforeToolCall(call: {
+        name: string;
+        args: Record<string, unknown>;
+    }): Promise<void>;
+    afterToolCall(result: {
+        name: string;
+        output: string;
+        duration: number;
+    }): Promise<void>;
+    onStep(step: StepResult): Promise<void>;
+    onError(error: ZoeError): Promise<void>;
+    onFinish(result: GenerateTextResult): Promise<void>;
+}
+/**
+ * Create a safe hook executor from an optional `Hooks` object.
+ *
+ * Every method on the returned `HookExecutor` is safe to call even when
+ * the caller provided no hooks — undefined hooks are treated as no-ops,
+ * and any error thrown by a hook is caught, logged, and swallowed so
+ * the main agent loop is never disrupted.
+ *
+ * @param hooks  Optional user-supplied hooks
+ * @returns      A `HookExecutor` whose methods are always safe to invoke
+ */
+export declare function createHookExecutor(hooks?: Hooks): HookExecutor;

package/dist/core/hooks.js

@@ -0,0 +1,49 @@
+/**
+ * Zoe SDK — Hook executor
+ *
+ * Wraps a user-supplied `Hooks` object in a safe executor that:
+ *  - treats missing hooks as no-ops
+ *  - awaits async hooks
+ *  - catches and logs hook errors without failing the main flow
+ */
+/**
+ * Create a safe hook executor from an optional `Hooks` object.
+ *
+ * Every method on the returned `HookExecutor` is safe to call even when
+ * the caller provided no hooks — undefined hooks are treated as no-ops,
+ * and any error thrown by a hook is caught, logged, and swallowed so
+ * the main agent loop is never disrupted.
+ *
+ * @param hooks  Optional user-supplied hooks
+ * @returns      A `HookExecutor` whose methods are always safe to invoke
+ */
+export function createHookExecutor(hooks) {
+    const h = hooks ?? {};
+    async function run(fn, label) {
+        if (fn == null)
+            return;
+        try {
+            await fn();
+        }
+        catch (err) {
+            console.error(`[zoe] ${label} hook error:`, err);
+        }
+    }
+    return {
+        async beforeToolCall(call) {
+            await run(() => h.beforeToolCall?.(call), "beforeToolCall");
+        },
+        async afterToolCall(result) {
+            await run(() => h.afterToolCall?.(result), "afterToolCall");
+        },
+        async onStep(step) {
+            await run(() => h.onStep?.(step), "onStep");
+        },
+        async onError(error) {
+            await run(() => h.onError?.(error), "onError");
+        },
+        async onFinish(result) {
+            await run(() => h.onFinish?.(result), "onFinish");
+        },
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Zoe Core Module
+ *
+ * Central orchestrators and utilities for the Zoe unified architecture.
+ */
+export { invokeSkill, createSkillProviderSwitcher, type SkillInvocationResult, type SkillProviderSwitcher, type ProviderSwitcherConfig, } from './skill-invoker.js';
+export { buildSkillCatalog } from './skill-catalog.js';
+export { runAgentLoop, type AgentLoopOptions, type AgentLoopResult, type AgentLoopError, type ProviderFactory, } from './agent-loop.js';
+export { createHookExecutor, type HookExecutor } from './hooks.js';
+export { StreamManager } from './stream-manager.js';
+export { createSessionStore, createMemoryStore, createPersistenceBackend, persistSession, registerBackend, FilePersistenceBackend, MemoryPersistenceBackend } from './session-store.js';
+export type { BackendFactory } from './session-store.js';
+export { ZoeError, ProviderError, ToolError, MaxStepsError, AbortedError, } from './errors.js';
+export type { ProviderType, MultiProviderConfig, Message, ToolCall, StepResult, Usage, CumulativeUsage, UserToolDefinition, ToolContext, ToolResult, Hooks, GenerateTextOptions, GenerateTextResult, StreamTextOptions, StreamTextResult, AgentCreateOptions, SdkAgent, AgentResponse, SessionStore, SessionData, PersistenceBackend, PersistenceConfig, SkillMetadata, PermissionLevel, ToolRiskCategory, } from './types.js';
+export { provider, configureProviders, getProviderConfig, getDefaultProviderType, getDefaultProvider, getProvider, resolveProviderConfigFromApp, resolveFromEnv, resolveFromConfigFile, migrateLegacyConfig, addProvider, updateProviderConfig, removeProvider, resolveGLMModel, } from './provider-resolver.js';
+export type { ResolvedProviderConfig, AppConfig, } from './provider-resolver.js';
+export { generateId, now, estimateTokens, toZoeError, messageToProviderMessage, providerToolCallToToolCall, providerResponseToMessages, } from './message-convert.js';
+export { CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS, tool, resolveTools, getToolGroup, registerTool, executeTool, getAllToolDefinitions, } from './tool-executor.js';
+export { checkToolPermission, getToolRiskCategory, resolvePermissionLevel, } from './permission.js';
+export { compose, type PipelineContext, type Middleware, } from './middleware.js';
+export { loggingMiddleware, type LoggingOptions } from './middleware/logging.js';
+export { rateLimitMiddleware, type RateLimitOptions } from './middleware/rate-limit.js';
+export { authMiddleware, type AuthOptions } from './middleware/auth.js';

package/dist/core/index.js

@@ -0,0 +1,29 @@
+/**
+ * Zoe Core Module
+ *
+ * Central orchestrators and utilities for the Zoe unified architecture.
+ */
+export { invokeSkill, createSkillProviderSwitcher, } from './skill-invoker.js';
+export { buildSkillCatalog } from './skill-catalog.js';
+export { runAgentLoop, } from './agent-loop.js';
+export { createHookExecutor } from './hooks.js';
+export { StreamManager } from './stream-manager.js';
+export { createSessionStore, createMemoryStore, createPersistenceBackend, persistSession, registerBackend, FilePersistenceBackend, MemoryPersistenceBackend } from './session-store.js';
+// Export error classes (canonical definitions live in ./errors.ts)
+export { ZoeError, ProviderError, ToolError, MaxStepsError, AbortedError, } from './errors.js';
+// ZoeError is also re-exported as a value from types.ts, but the canonical
+// class export comes from ./errors.js above. The `export type` block omits
+// ZoeError intentionally to avoid a duplicate value export.
+// Export provider resolver functions
+export { provider, configureProviders, getProviderConfig, getDefaultProviderType, getDefaultProvider, getProvider, resolveProviderConfigFromApp, resolveFromEnv, resolveFromConfigFile, migrateLegacyConfig, addProvider, updateProviderConfig, removeProvider, resolveGLMModel, } from './provider-resolver.js';
+// Export message conversion helpers
+export { generateId, now, estimateTokens, toZoeError, messageToProviderMessage, providerToolCallToToolCall, providerResponseToMessages, } from './message-convert.js';
+// Export tool executor
+export { CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS, tool, resolveTools, getToolGroup, registerTool, executeTool, getAllToolDefinitions, } from './tool-executor.js';
+// Export permission system
+export { checkToolPermission, getToolRiskCategory, resolvePermissionLevel, } from './permission.js';
+// Export middleware pipeline
+export { compose, } from './middleware.js';
+export { loggingMiddleware } from './middleware/logging.js';
+export { rateLimitMiddleware } from './middleware/rate-limit.js';
+export { authMiddleware } from './middleware/auth.js';

package/dist/core/message-convert.d.ts

@@ -0,0 +1,41 @@
+/** Zoe Core — Message conversion helpers */
+import type { Message, ToolCall } from "./types.js";
+import { ZoeError } from "./errors.js";
+import type { ProviderMessage, ProviderResponse, ProviderToolCall } from "../providers/types.js";
+/**
+ * Generate a unique identifier using crypto.randomUUID().
+ */
+export declare function generateId(): string;
+/**
+ * Get the current Unix timestamp in milliseconds.
+ */
+export declare function now(): number;
+/**
+ * Rough token estimate: ~4 characters per token.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Create a ZoeError from a plain Error or unknown value.
+ * Uses the proper class hierarchy based on the error code.
+ */
+export declare function toZoeError(err: unknown, code: string): ZoeError;
+/**
+ * Convert an SDK Message to ProviderMessage format.
+ */
+export declare function messageToProviderMessage(msg: Message): ProviderMessage;
+/**
+ * Convert a ProviderToolCall to SDK ToolCall format.
+ */
+export declare function providerToolCallToToolCall(tc: ProviderToolCall): ToolCall;
+/**
+ * Convert a ProviderResponse into an array of SDK Message objects.
+ *
+ * A single provider response may contain both text content and tool calls.
+ * This function normalises it into one or more Message objects:
+ *  - An assistant message with text content (and optional toolCalls)
+ *  - If only tool calls with no text, an assistant message with empty content
+ *
+ * @param response - The raw ProviderResponse from the LLM provider.
+ * @returns Array of Message objects representing the response.
+ */
+export declare function providerResponseToMessages(response: ProviderResponse): Message[];

package/dist/core/message-convert.js

@@ -0,0 +1,94 @@
+/** Zoe Core — Message conversion helpers */
+import { ZoeError, ProviderError, ToolError } from "./errors.js";
+/**
+ * Generate a unique identifier using crypto.randomUUID().
+ */
+export function generateId() {
+    return crypto.randomUUID();
+}
+/**
+ * Get the current Unix timestamp in milliseconds.
+ */
+export function now() {
+    return Date.now();
+}
+/**
+ * Rough token estimate: ~4 characters per token.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Create a ZoeError from a plain Error or unknown value.
+ * Uses the proper class hierarchy based on the error code.
+ */
+export function toZoeError(err, code) {
+    const message = err instanceof Error ? err.message : String(err);
+    switch (code) {
+        case "PROVIDER_ERROR":
+            return new ProviderError(message);
+        case "TOOL_FAILED":
+            return new ToolError(message);
+        default:
+            return new ZoeError(message, code, code === "PROVIDER_ERROR");
+    }
+}
+/**
+ * Convert an SDK Message to ProviderMessage format.
+ */
+export function messageToProviderMessage(msg) {
+    const pm = { role: msg.role, content: msg.content };
+    if (msg.toolCalls && msg.toolCalls.length > 0) {
+        pm.tool_calls = msg.toolCalls.map((tc) => ({
+            id: tc.id,
+            name: tc.name,
+            arguments: JSON.stringify(tc.arguments),
+        }));
+    }
+    if (msg.toolCallId) {
+        pm.tool_call_id = msg.toolCallId;
+    }
+    return pm;
+}
+/**
+ * Convert a ProviderToolCall to SDK ToolCall format.
+ */
+export function providerToolCallToToolCall(tc) {
+    let args;
+    try {
+        args = JSON.parse(tc.arguments);
+    }
+    catch {
+        args = { raw: tc.arguments };
+    }
+    return {
+        id: tc.id,
+        name: tc.name,
+        arguments: args,
+    };
+}
+/**
+ * Convert a ProviderResponse into an array of SDK Message objects.
+ *
+ * A single provider response may contain both text content and tool calls.
+ * This function normalises it into one or more Message objects:
+ *  - An assistant message with text content (and optional toolCalls)
+ *  - If only tool calls with no text, an assistant message with empty content
+ *
+ * @param response - The raw ProviderResponse from the LLM provider.
+ * @returns Array of Message objects representing the response.
+ */
+export function providerResponseToMessages(response) {
+    const messages = [];
+    // Build assistant message
+    const toolCalls = response.tool_calls?.map(providerToolCallToToolCall) ?? [];
+    const assistantMsg = {
+        id: generateId(),
+        role: "assistant",
+        content: response.content ?? "",
+        timestamp: now(),
+        ...(toolCalls.length > 0 ? { toolCalls } : {}),
+    };
+    messages.push(assistantMsg);
+    return messages;
+}

package/dist/core/middleware/auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Zoe Middleware — Auth
+ *
+ * Simple, composable auth validation middleware.
+ */
+import type { PipelineContext, Middleware } from "../middleware.js";
+export interface AuthOptions {
+    /** Validate the request context. Throw or return false to reject. */
+    validate: (ctx: PipelineContext) => boolean | Promise<boolean>;
+    /** Error message on rejection (default: "Unauthorized") */
+    errorMessage?: string;
+}
+/**
+ * Create an auth middleware.
+ *
+ * @example
+ * ```ts
+ * const mw = authMiddleware({
+ *   validate: (ctx) => !!ctx.metadata.apiKey,
+ *   errorMessage: "API key required",
+ * });
+ * ```
+ */
+export declare function authMiddleware(options: AuthOptions): Middleware;

package/dist/core/middleware/auth.js

@@ -0,0 +1,28 @@
+/**
+ * Zoe Middleware — Auth
+ *
+ * Simple, composable auth validation middleware.
+ */
+import { ZoeError } from "../errors.js";
+/**
+ * Create an auth middleware.
+ *
+ * @example
+ * ```ts
+ * const mw = authMiddleware({
+ *   validate: (ctx) => !!ctx.metadata.apiKey,
+ *   errorMessage: "API key required",
+ * });
+ * ```
+ */
+export function authMiddleware(options) {
+    const { validate } = options;
+    const errorMessage = options.errorMessage ?? "Unauthorized";
+    return async (ctx, next) => {
+        const allowed = await validate(ctx);
+        if (!allowed) {
+            throw new ZoeError(errorMessage, "UNAUTHORIZED", false);
+        }
+        await next();
+    };
+}