zoe-agent 0.3.1

package/dist/core/provider-config.js

@@ -0,0 +1,273 @@
+/**
+ * Zoe Core — Provider Configuration Types & Mutation
+ *
+ * Types, singleton management, config mutation functions, and file-based resolution.
+ * Extracted from provider-resolver.ts for single-responsibility.
+ */
+import { createProvider } from "../providers/factory.js";
+import { DEFAULT_MODELS, PROVIDER_ENV_KEYS, resolveApiKey, resolveBaseUrl, resolveDefaultType, resolveDefaultModel, } from "./provider-env.js";
+import { applyEnvOverrides, loadMergedConfig, resolveActiveProviderType, } from "./config.js";
+/**
+ * Module-level singleton that holds multi-provider configuration.
+ */
+let providerConfig = null;
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Creates a single provider configuration object.
+ * Useful for building `MultiProviderConfig` declaratively.
+ */
+export function provider(type, apiKey, options) {
+    return {
+        type,
+        apiKey,
+        ...options,
+    };
+}
+/**
+ * Stores multi-provider configuration globally.
+ * Can be called once at application startup.
+ */
+export function configureProviders(config) {
+    providerConfig = config;
+}
+/**
+ * Returns the raw configuration for a given provider type.
+ * Falls back to environment variables when no explicit config is set.
+ *
+ * @param type - Provider type. If omitted, uses the default provider.
+ * @returns Resolved provider configuration with apiKey, model, and optional baseUrl.
+ * @throws Error if the provider is not configured and no env var is available.
+ */
+export function getProviderConfig(type) {
+    const resolvedType = type ?? getDefaultProviderType();
+    // 1. Check explicit config first
+    if (providerConfig) {
+        const entry = providerConfig[resolvedType];
+        if (entry && "apiKey" in entry) {
+            const cfg = entry;
+            return {
+                type: resolvedType,
+                apiKey: cfg.apiKey,
+                model: cfg.model ?? resolveDefaultModel(resolvedType),
+                baseUrl: cfg.baseUrl,
+            };
+        }
+    }
+    // 2. Fall back to environment variables
+    const apiKey = resolveApiKey(resolvedType);
+    if (!apiKey) {
+        const envHint = PROVIDER_ENV_KEYS[resolvedType].apiKey;
+        throw new Error(`No provider is configured. Pass \`provider\` to generateText/createAgent/streamText, ` +
+            `call \`configureProviders(loadProviderConfig())\` at startup, or set the ${envHint} env var.`);
+    }
+    return {
+        type: resolvedType,
+        apiKey,
+        model: resolveDefaultModel(resolvedType),
+        baseUrl: resolveBaseUrl(resolvedType),
+    };
+}
+/**
+ * Resolves which provider type is the default.
+ * Checks explicit config, then LLM_PROVIDER env var, then falls back to "openai".
+ */
+export function getDefaultProviderType() {
+    if (providerConfig?.default) {
+        return providerConfig.default;
+    }
+    return resolveDefaultType();
+}
+/**
+ * Returns the default configured provider type (alias for getDefaultProviderType).
+ */
+export function getDefaultProvider() {
+    return getDefaultProviderType();
+}
+/**
+ * Creates and returns an LLMProvider instance using the existing factory.
+ * If type is omitted, uses the default provider.
+ *
+ * @param type - Provider type. If omitted, uses the default provider.
+ * @param modelOverride - When set, overrides the resolved model before creating the provider.
+ * @returns The initialized LLMProvider and the resolved model name.
+ */
+export async function getProvider(type, modelOverride) {
+    const config = getProviderConfig(type);
+    const factoryConfig = {
+        type: config.type,
+        apiKey: config.apiKey,
+        model: modelOverride ?? config.model,
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+    };
+    const llmProvider = await createProvider(factoryConfig);
+    return {
+        provider: llmProvider,
+        model: modelOverride ?? config.model,
+    };
+}
+// ── CLI-specific functions ───────────────────────────────────────────
+/**
+ * Resolves provider configuration from legacy AppConfig (CLI format).
+ * This handles both old-style top-level config and new models map format.
+ */
+export function resolveProviderConfigFromApp(config, providerType) {
+    const modelConfig = config.models?.[providerType];
+    if (!modelConfig)
+        return null;
+    const apiKey = ("apiKey" in modelConfig) ? modelConfig.apiKey : config.apiKey;
+    if (!apiKey)
+        return null;
+    const model = "model" in modelConfig ? modelConfig.model : config.model || DEFAULT_MODELS[providerType];
+    const baseUrl = "baseUrl" in modelConfig ? modelConfig.baseUrl : config.baseUrl;
+    return { type: providerType, apiKey, model, baseUrl };
+}
+// ── CLI-config bridge ────────────────────────────────────────────────
+/**
+ * Load CLI-style config (~/.zoe/setting.json + .zoe/setting.json + env
+ * overrides) and translate it to a MultiProviderConfig suitable for
+ * `configureProviders()`.
+ *
+ * When `app` is provided, uses that config directly (callers that have already
+ * loaded and mutated their AppConfig should pass it here). Otherwise reads
+ * fresh from disk via `loadMergedConfig()` + `applyEnvOverrides()`.
+ *
+ * @returns MultiProviderConfig if any provider has a configured apiKey, null otherwise.
+ *          Callers should check for null before passing to configureProviders().
+ */
+export function loadProviderConfig(app, cliProvider) {
+    const appConfig = app ?? applyEnvOverrides(loadMergedConfig());
+    const multi = {};
+    const types = [
+        "openai",
+        "anthropic",
+        "glm",
+        "openai-compatible",
+    ];
+    for (const t of types) {
+        const entry = appConfig.models?.[t];
+        if (entry && "apiKey" in entry && entry.apiKey) {
+            multi[t] = entry;
+        }
+    }
+    const collected = Object.keys(multi);
+    if (collected.length === 0)
+        return null;
+    // Derive `default`: CLI flag → config.provider → resolveActiveProviderType(),
+    // but only if that provider was actually collected above. Otherwise fall back
+    // to the first collected entry so `default` always points at a real provider.
+    const candidate = cliProvider ??
+        appConfig.provider ??
+        resolveActiveProviderType(appConfig);
+    multi.default = collected.includes(candidate) ? candidate : collected[0];
+    return multi;
+}
+// ── Config-file resolution ───────────────────────────────────────────
+/**
+ * Resolves provider configuration from a config file object.
+ * Supports both legacy AppConfig format and new MultiProviderConfig format.
+ */
+export function resolveFromConfigFile(config, type) {
+    // First, try to treat it as MultiProviderConfig (new format)
+    if (config.models || config.default) {
+        const multiConfig = config;
+        const resolvedType = type ?? multiConfig.default ?? "openai";
+        const entry = multiConfig[resolvedType];
+        if (entry && "apiKey" in entry) {
+            return {
+                type: resolvedType,
+                apiKey: entry.apiKey,
+                model: entry.model ?? DEFAULT_MODELS[resolvedType],
+                baseUrl: "baseUrl" in entry ? entry.baseUrl : undefined,
+            };
+        }
+    }
+    // Fall back to legacy AppConfig format
+    if (config.apiKey || config.models) {
+        const appConfig = migrateLegacyConfig(config);
+        return resolveFromConfigFile(appConfig, type);
+    }
+    return null;
+}
+/**
+ * Migrates legacy top-level config to the new models map format.
+ */
+export function migrateLegacyConfig(config) {
+    const result = {};
+    // If config already has models map, it's not legacy
+    if (config.models) {
+        return config;
+    }
+    // Migrate top-level provider config
+    const providerType = config.provider || "openai";
+    if (config.apiKey) {
+        result[providerType] = {
+            apiKey: config.apiKey,
+            ...(config.model ? { model: config.model } : {}),
+            ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+        };
+    }
+    result.default = providerType;
+    return result;
+}
+// ── Provider mutation functions ──────────────────────────────────────
+/**
+ * Adds or updates a provider configuration.
+ * Modifies the global providerConfig singleton.
+ */
+export function addProvider(type, config) {
+    if (!providerConfig) {
+        providerConfig = { default: type };
+    }
+    // For openai-compatible, baseUrl is required
+    if (type === "openai-compatible" && !config.baseUrl) {
+        throw new Error('Provider "openai-compatible" requires a baseUrl.');
+    }
+    providerConfig[type] = config;
+}
+/**
+ * Updates an existing provider configuration.
+ * Only updates the specified fields, preserving others.
+ */
+export function updateProviderConfig(type, updates) {
+    if (!providerConfig?.[type]) {
+        throw new Error(`Provider "${type}" is not configured. Use addProvider() first.`);
+    }
+    const existing = providerConfig[type];
+    providerConfig[type] = {
+        ...existing,
+        ...updates,
+    };
+}
+/**
+ * Removes a provider configuration.
+ */
+export function removeProvider(type) {
+    if (!providerConfig) {
+        return;
+    }
+    delete providerConfig[type];
+    // If we removed the default, switch to another available provider
+    if (providerConfig.default === type) {
+        const remaining = Object.keys(providerConfig).filter(k => k !== "default");
+        if (remaining.length > 0) {
+            providerConfig.default = remaining[0];
+        }
+    }
+}
+/**
+ * Saves the current provider configuration to a file.
+ */
+export async function saveConfig(configPath) {
+    if (!providerConfig) {
+        throw new Error("No provider configuration to save. Call configureProviders() first.");
+    }
+    const fs = await import("fs");
+    const path = await import("path");
+    const os = await import("os");
+    const targetPath = configPath ?? path.join(os.homedir(), ".zoerc.json");
+    const dir = path.dirname(targetPath);
+    // Ensure directory exists
+    await fs.promises.mkdir(dir, { recursive: true });
+    // Write config file
+    await fs.promises.writeFile(targetPath, JSON.stringify(providerConfig, null, 2), "utf-8");
+}

package/dist/core/provider-env.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Zoe Core — Provider Environment Resolution
+ *
+ * Environment variable helpers, default models, and env-based resolution.
+ * Extracted from provider-resolver.ts for single-responsibility.
+ */
+import { DEFAULT_MODELS } from "../models-catalog.js";
+import type { MultiProviderConfig, ProviderType } from "./types.js";
+export { DEFAULT_MODELS };
+export declare const PROVIDER_ENV_KEYS: Record<ProviderType, {
+    apiKey: string;
+    baseUrl?: string;
+}>;
+export declare function env(name: string): string | undefined;
+export declare function resolveApiKey(type: ProviderType): string | undefined;
+export declare function resolveBaseUrl(type: ProviderType): string | undefined;
+export declare function resolveDefaultType(): ProviderType;
+export declare function resolveDefaultModel(type: ProviderType): string;
+/**
+ * Resolve a GLM model alias or model name to the actual model identifier.
+ *
+ * Looks up the model in the GLM_MODEL_MAP (e.g. "haiku" -> "glm-4.5-air",
+ * "sonnet" -> "glm-4.7", "opus" -> "glm-5.1"). If the model is not found in
+ * the map, it is returned unchanged.
+ *
+ * @param model - Model name or alias to resolve.
+ * @returns The resolved model identifier.
+ */
+export declare function resolveGLMModel(model: string): string;
+/**
+ * Scans environment variables and builds a MultiProviderConfig from them.
+ * This replaces the server's `initializeProvidersFromEnv()` function.
+ *
+ * Note: This function only RETURNS the config. To actually configure providers,
+ * call `configureProviders(resolveFromEnv())`.
+ *
+ * @returns MultiProviderConfig if any env vars are set, null otherwise.
+ */
+export declare function resolveFromEnv(): MultiProviderConfig | null;

package/dist/core/provider-env.js

@@ -0,0 +1,142 @@
+/**
+ * Zoe Core — Provider Environment Resolution
+ *
+ * Environment variable helpers, default models, and env-based resolution.
+ * Extracted from provider-resolver.ts for single-responsibility.
+ */
+import { GLM_MODEL_MAP } from "../providers/factory.js";
+import { DEFAULT_MODELS } from "../models-catalog.js";
+// ── Default models per provider ──────────────────────────────────────
+export { DEFAULT_MODELS };
+// ── Env var keys per provider ────────────────────────────────────────
+export const PROVIDER_ENV_KEYS = {
+    openai: { apiKey: "OPENAI_API_KEY" },
+    anthropic: { apiKey: "ANTHROPIC_API_KEY" },
+    glm: { apiKey: "GLM_API_KEY" },
+    "openai-compatible": {
+        apiKey: "OPENAI_COMPAT_API_KEY",
+        baseUrl: "OPENAI_COMPAT_BASE_URL",
+    },
+};
+// ── Internal helpers ─────────────────────────────────────────────────
+export function env(name) {
+    return process.env[name];
+}
+export function resolveApiKey(type) {
+    // Per-provider env var takes priority
+    const envKeys = PROVIDER_ENV_KEYS[type];
+    if (envKeys.apiKey) {
+        const key = env(envKeys.apiKey);
+        if (key)
+            return key;
+    }
+    // Backward compat: check deprecated env vars
+    if (type === "openai-compatible") {
+        const legacy = env("ZOE_API_KEY");
+        if (legacy) {
+            console.warn("[zoe] ZOE_API_KEY is deprecated. Use OPENAI_COMPAT_API_KEY instead.");
+            return legacy;
+        }
+    }
+    return undefined;
+}
+export function resolveBaseUrl(type) {
+    const envKeys = PROVIDER_ENV_KEYS[type];
+    if (envKeys.baseUrl) {
+        const url = env(envKeys.baseUrl);
+        if (url)
+            return url;
+    }
+    // Backward compat: check deprecated env var for openai-compatible
+    if (type === "openai-compatible") {
+        const legacy = env("OPENAI_BASE_URL");
+        if (legacy) {
+            console.warn("[zoe] OPENAI_BASE_URL is deprecated. Use OPENAI_COMPAT_BASE_URL instead.");
+            return legacy;
+        }
+    }
+    return undefined;
+}
+export function resolveDefaultType() {
+    const fromEnv = env("LLM_PROVIDER") ?? env("ZOE_PROVIDER");
+    if (fromEnv &&
+        (fromEnv === "openai" ||
+            fromEnv === "anthropic" ||
+            fromEnv === "glm" ||
+            fromEnv === "openai-compatible")) {
+        return fromEnv;
+    }
+    return "openai";
+}
+export function resolveDefaultModel(type) {
+    return env("LLM_MODEL") ?? env("ZOE_MODEL") ?? DEFAULT_MODELS[type];
+}
+// ── GLM model alias resolution ───────────────────────────────────────
+/**
+ * Resolve a GLM model alias or model name to the actual model identifier.
+ *
+ * Looks up the model in the GLM_MODEL_MAP (e.g. "haiku" -> "glm-4.5-air",
+ * "sonnet" -> "glm-4.7", "opus" -> "glm-5.1"). If the model is not found in
+ * the map, it is returned unchanged.
+ *
+ * @param model - Model name or alias to resolve.
+ * @returns The resolved model identifier.
+ */
+export function resolveGLMModel(model) {
+    return GLM_MODEL_MAP[model] ?? model;
+}
+// ── Full env-based resolution ────────────────────────────────────────
+/**
+ * Scans environment variables and builds a MultiProviderConfig from them.
+ * This replaces the server's `initializeProvidersFromEnv()` function.
+ *
+ * Note: This function only RETURNS the config. To actually configure providers,
+ * call `configureProviders(resolveFromEnv())`.
+ *
+ * @returns MultiProviderConfig if any env vars are set, null otherwise.
+ */
+export function resolveFromEnv() {
+    const config = {};
+    if (process.env.OPENAI_API_KEY) {
+        config.openai = {
+            apiKey: process.env.OPENAI_API_KEY,
+            model: process.env.OPENAI_MODEL ?? DEFAULT_MODELS.openai,
+        };
+    }
+    if (process.env.ANTHROPIC_API_KEY) {
+        config.anthropic = {
+            apiKey: process.env.ANTHROPIC_API_KEY,
+            model: process.env.ANTHROPIC_MODEL ?? DEFAULT_MODELS.anthropic,
+        };
+    }
+    if (process.env.GLM_API_KEY) {
+        config.glm = {
+            apiKey: process.env.GLM_API_KEY,
+            model: process.env.GLM_MODEL ?? DEFAULT_MODELS.glm,
+        };
+    }
+    const compatApiKey = process.env.OPENAI_COMPAT_API_KEY || process.env.ZOE_API_KEY;
+    const compatBaseUrl = process.env.OPENAI_COMPAT_BASE_URL || process.env.OPENAI_BASE_URL;
+    if (compatApiKey && compatBaseUrl) {
+        if (process.env.ZOE_API_KEY && !process.env.OPENAI_COMPAT_API_KEY) {
+            console.warn("[zoe] ZOE_API_KEY is deprecated. Use OPENAI_COMPAT_API_KEY instead.");
+        }
+        if (process.env.OPENAI_BASE_URL && !process.env.OPENAI_COMPAT_BASE_URL) {
+            console.warn("[zoe] OPENAI_BASE_URL is deprecated. Use OPENAI_COMPAT_BASE_URL instead.");
+        }
+        config["openai-compatible"] = {
+            apiKey: compatApiKey,
+            baseUrl: compatBaseUrl,
+            model: process.env.OPENAI_COMPAT_MODEL ?? process.env.LLM_MODEL ?? process.env.ZOE_MODEL ?? DEFAULT_MODELS['openai-compatible'],
+        };
+    }
+    if (Object.keys(config).length > 0) {
+        const defaultProvider = (process.env.LLM_PROVIDER ?? process.env.ZOE_PROVIDER) ??
+            (config.openai ? "openai" : Object.keys(config)[0]);
+        return {
+            ...config,
+            default: defaultProvider,
+        };
+    }
+    return null;
+}

package/dist/core/provider-resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Zoe Core — Unified Provider Resolver
+ *
+ * Re-export hub. All logic has been split into:
+ *   - provider-env.ts    — env var helpers, defaults, resolveFromEnv(), resolveGLMModel()
+ *   - provider-config.ts — types, singleton, mutation, getProvider(), resolveFromConfigFile()
+ *
+ * This file preserves all existing import paths. No consumer changes needed.
+ */
+export { DEFAULT_MODELS, PROVIDER_ENV_KEYS, resolveFromEnv, resolveGLMModel, } from "./provider-env.js";
+export type { ResolvedProviderConfig, AppConfig } from "./provider-config.js";
+export { provider, configureProviders, loadProviderConfig, getProviderConfig, getDefaultProviderType, getDefaultProvider, getProvider, resolveProviderConfigFromApp, resolveFromConfigFile, migrateLegacyConfig, addProvider, updateProviderConfig, removeProvider, saveConfig, } from "./provider-config.js";

package/dist/core/provider-resolver.js

@@ -0,0 +1,12 @@
+/**
+ * Zoe Core — Unified Provider Resolver
+ *
+ * Re-export hub. All logic has been split into:
+ *   - provider-env.ts    — env var helpers, defaults, resolveFromEnv(), resolveGLMModel()
+ *   - provider-config.ts — types, singleton, mutation, getProvider(), resolveFromConfigFile()
+ *
+ * This file preserves all existing import paths. No consumer changes needed.
+ */
+// ── From provider-env.ts ─────────────────────────────────────────────
+export { DEFAULT_MODELS, PROVIDER_ENV_KEYS, resolveFromEnv, resolveGLMModel, } from "./provider-env.js";
+export { provider, configureProviders, loadProviderConfig, getProviderConfig, getDefaultProviderType, getDefaultProvider, getProvider, resolveProviderConfigFromApp, resolveFromConfigFile, migrateLegacyConfig, addProvider, updateProviderConfig, removeProvider, saveConfig, } from "./provider-config.js";

package/dist/core/session-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Zoe SDK — Session persistence
+ *
+ * Provides composable persistence backends for storing conversation history.
+ * Built-in "file" and "memory" backends are registered by default. Custom
+ * backends (Redis, SQLite, etc.) can be registered via `registerBackend()`.
+ *
+ * Legacy `SessionStore`-based API is preserved for backward compatibility.
+ */
+import type { Message, PersistenceBackend, PersistenceConfig, ProviderType, SessionData, SessionStore } from "./types.js";
+/**
+ * File-backed persistence backend. Each session is stored as a JSON file
+ * at `{basePath}/{sessionId}.json`.
+ */
+export declare class FilePersistenceBackend implements PersistenceBackend {
+    readonly __persistenceBackend: true;
+    private basePath;
+    constructor(basePath: string);
+    private filePath;
+    private ensureDir;
+    save(id: string, data: SessionData): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    delete(id: string): Promise<void>;
+    list(): Promise<string[]>;
+    private loadFromDisk;
+}
+/**
+ * In-memory persistence backend backed by a Map. Useful for testing.
+ */
+export declare class MemoryPersistenceBackend implements PersistenceBackend {
+    readonly __persistenceBackend: true;
+    private store;
+    save(id: string, data: SessionData): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    delete(id: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+export type BackendFactory = (config: PersistenceConfig) => PersistenceBackend;
+/**
+ * Register a custom persistence backend factory.
+ *
+ * @param type    Unique backend identifier (e.g., "redis", "sqlite")
+ * @param factory Factory function that creates a `PersistenceBackend` from config
+ */
+export declare function registerBackend(type: string, factory: BackendFactory): void;
+/**
+ * Create a persistence backend from a config object.
+ * Uses the `type` field to look up the registered factory.
+ *
+ * @throws Error if `type` is not registered
+ */
+export declare function createPersistenceBackend(config: PersistenceConfig): PersistenceBackend;
+/**
+ * Persist a session's messages to the backend.
+ *
+ * Single source of truth for the save step shared by all adapters (SDK, CLI,
+ * Server). The backend owns `createdAt` (assigns it on first save, preserves
+ * it on overwrite — see FilePersistenceBackend / MemoryPersistenceBackend) and
+ * merges optional `provider`/`model`/`metadata` fields, so callers only pass
+ * what they know. Adapters that don't track provider/model (the SDK) omit them
+ * and the persisted values are left untouched.
+ */
+export declare function persistSession(backend: PersistenceBackend, sessionId: string, messages: Message[], opts?: {
+    provider?: ProviderType;
+    model?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * @deprecated Use `createPersistenceBackend({ type: "file", path })` instead.
+ */
+export declare function createSessionStore(path?: string): SessionStore;
+/**
+ * @deprecated Use `createPersistenceBackend({ type: "memory" })` instead.
+ */
+export declare function createMemoryStore(): SessionStore;