zoe-agent 0.3.1

package/dist/core/session-store.js

@@ -0,0 +1,245 @@
+/**
+ * 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 { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ── Session ID validation ───────────────────────────────────────────────
+const SESSION_ID_RE = /^[a-zA-Z0-9-]+$/;
+function validateSessionId(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId)) {
+        throw new Error(`Invalid session ID "${sessionId}". Only alphanumeric characters and dashes are allowed.`);
+    }
+}
+// ── Default path ────────────────────────────────────────────────────────
+function defaultSessionPath() {
+    return join(homedir(), ".zoe", "sessions");
+}
+// ── File-based PersistenceBackend ───────────────────────────────────────
+/**
+ * File-backed persistence backend. Each session is stored as a JSON file
+ * at `{basePath}/{sessionId}.json`.
+ */
+export class FilePersistenceBackend {
+    __persistenceBackend = true;
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+    filePath(id) {
+        return join(this.basePath, `${id}.json`);
+    }
+    async ensureDir() {
+        await fs.mkdir(this.basePath, { recursive: true });
+    }
+    async save(id, data) {
+        validateSessionId(id);
+        await this.ensureDir();
+        const existing = await this.loadFromDisk(id);
+        const now = Date.now();
+        const full = existing
+            ? {
+                id,
+                messages: data.messages,
+                createdAt: existing.createdAt,
+                updatedAt: now,
+                provider: data.provider ?? existing.provider,
+                model: data.model ?? existing.model,
+                metadata: data.metadata ?? existing.metadata,
+            }
+            : {
+                id,
+                messages: data.messages,
+                createdAt: now,
+                updatedAt: now,
+                provider: data.provider,
+                model: data.model,
+                metadata: data.metadata,
+            };
+        const filePath = this.filePath(id);
+        const tmpPath = filePath + ".tmp." + Date.now();
+        try {
+            await fs.writeFile(tmpPath, JSON.stringify(full, null, 2), "utf-8");
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (err) {
+            // Clean up orphaned temp file on rename failure (e.g. cross-device move)
+            try {
+                await fs.unlink(tmpPath);
+            }
+            catch { /* best effort */ }
+            throw err;
+        }
+    }
+    async load(id) {
+        return this.loadFromDisk(id);
+    }
+    async delete(id) {
+        validateSessionId(id);
+        try {
+            await fs.unlink(this.filePath(id));
+        }
+        catch {
+            // File doesn't exist — nothing to delete
+        }
+    }
+    async list() {
+        await this.ensureDir();
+        const entries = await fs.readdir(this.basePath);
+        return entries
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => name.slice(0, -".json".length));
+    }
+    async loadFromDisk(id) {
+        try {
+            const raw = await fs.readFile(this.filePath(id), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ── In-memory PersistenceBackend ────────────────────────────────────────
+/**
+ * In-memory persistence backend backed by a Map. Useful for testing.
+ */
+export class MemoryPersistenceBackend {
+    __persistenceBackend = true;
+    store = new Map();
+    async save(id, data) {
+        validateSessionId(id);
+        const existing = this.store.get(id);
+        const now = Date.now();
+        this.store.set(id, {
+            id,
+            messages: data.messages,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            provider: data.provider ?? existing?.provider,
+            model: data.model ?? existing?.model,
+            metadata: data.metadata ?? existing?.metadata,
+        });
+    }
+    async load(id) {
+        return this.store.get(id) ?? null;
+    }
+    async delete(id) {
+        this.store.delete(id);
+    }
+    async list() {
+        return Array.from(this.store.keys());
+    }
+}
+const registry = new Map();
+// Register built-in backends
+registry.set("file", (config) => new FilePersistenceBackend(config.path ?? defaultSessionPath()));
+registry.set("memory", () => new MemoryPersistenceBackend());
+/**
+ * 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 function registerBackend(type, factory) {
+    registry.set(type, factory);
+}
+/**
+ * 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 function createPersistenceBackend(config) {
+    const factory = registry.get(config.type);
+    if (!factory) {
+        throw new Error(`Unknown persistence backend type "${config.type}". Registered types: ${Array.from(registry.keys()).join(", ")}`);
+    }
+    return factory(config);
+}
+// ── Save orchestration ──────────────────────────────────────────────────
+/**
+ * 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 async function persistSession(backend, sessionId, messages, opts) {
+    await backend.save(sessionId, {
+        id: sessionId,
+        messages,
+        // createdAt is required by the SessionData type but ignored by the
+        // backends — they assign it on first save and preserve it on overwrite.
+        updatedAt: Date.now(),
+        provider: opts?.provider,
+        model: opts?.model,
+        metadata: opts?.metadata,
+    });
+}
+// ── Deprecated legacy API ───────────────────────────────────────────────
+/**
+ * @deprecated Use `FilePersistenceBackend` or `createPersistenceBackend({ type: "file", path })` instead.
+ */
+class FileSessionStore {
+    backend;
+    constructor(basePath) {
+        this.backend = new FilePersistenceBackend(basePath);
+    }
+    async save(sessionId, messages) {
+        await this.backend.save(sessionId, { id: sessionId, messages, createdAt: Date.now(), updatedAt: Date.now() });
+    }
+    async load(sessionId) {
+        const data = await this.backend.load(sessionId);
+        return data?.messages ?? null;
+    }
+    async delete(sessionId) {
+        await this.backend.delete(sessionId);
+    }
+    async list() {
+        return this.backend.list();
+    }
+}
+/**
+ * @deprecated Use `MemoryPersistenceBackend` or `createPersistenceBackend({ type: "memory" })` instead.
+ */
+class MemorySessionStore {
+    backend;
+    constructor() {
+        this.backend = new MemoryPersistenceBackend();
+    }
+    async save(sessionId, messages) {
+        await this.backend.save(sessionId, { id: sessionId, messages, createdAt: Date.now(), updatedAt: Date.now() });
+    }
+    async load(sessionId) {
+        const data = await this.backend.load(sessionId);
+        return data?.messages ?? null;
+    }
+    async delete(sessionId) {
+        await this.backend.delete(sessionId);
+    }
+    async list() {
+        return this.backend.list();
+    }
+}
+/**
+ * @deprecated Use `createPersistenceBackend({ type: "file", path })` instead.
+ */
+export function createSessionStore(path) {
+    return new FileSessionStore(path ?? defaultSessionPath());
+}
+/**
+ * @deprecated Use `createPersistenceBackend({ type: "memory" })` instead.
+ */
+export function createMemoryStore() {
+    return new MemorySessionStore();
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Zoe Core — Settings Manager
+ *
+ * Single source of truth for reading, writing, validating, and persisting
+ * settings. Adapters (CLI, SDK, Server) delegate to this class.
+ */
+import { ZoeError } from './errors.js';
+import { SettingsCategory } from './settings-schema.js';
+export declare class SettingsError extends ZoeError {
+    constructor(message: string, code?: string);
+}
+export interface SettingValue {
+    value: unknown;
+    origin: string;
+    masked: boolean;
+}
+export interface SettingEntry extends SettingValue {
+    dotKey: string;
+    category: SettingsCategory;
+    restartRequired: boolean;
+    label: string;
+}
+export interface SettingsManagerOptions {
+    config: Record<string, any>;
+    projectConfigPath?: string;
+    globalConfigPath?: string;
+    projectConfig?: Record<string, any>;
+    globalConfig?: Record<string, any>;
+}
+export declare class SettingsManager {
+    private config;
+    private projectConfigPath?;
+    private globalConfigPath?;
+    private projectConfig;
+    private globalConfig;
+    private listeners;
+    constructor(options: SettingsManagerOptions);
+    get(dotKey: string): SettingValue;
+    list(): SettingEntry[];
+    listByCategory(): Record<string, SettingEntry[]>;
+    set(dotKey: string, rawValue: string): Promise<void>;
+    reset(dotKey: string): Promise<void>;
+    resetAll(): Promise<void>;
+    onChange(callback: (changedKeys: string[]) => void): () => void;
+    private emitChange;
+    private validateValue;
+    private resolveConfigOrigin;
+    private parseEnvValue;
+    private resolveWriteTarget;
+    private readConfigFile;
+    private persist;
+    private getValueByPath;
+    private applyValueToConfig;
+    private removeValueFromConfig;
+    private hasPath;
+    private maskValue;
+}

package/dist/core/settings-manager.js

@@ -0,0 +1,359 @@
+/**
+ * Zoe Core — Settings Manager
+ *
+ * Single source of truth for reading, writing, validating, and persisting
+ * settings. Adapters (CLI, SDK, Server) delegate to this class.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { ZoeError } from './errors.js';
+import { SETTINGS_MAP, SETTINGS_SCHEMA, ENV_VAR_MAP, isSecretField, } from './settings-schema.js';
+// ── Settings Error ────────────────────────────────────────────────────────
+export class SettingsError extends ZoeError {
+    constructor(message, code = 'SETTINGS_ERROR') {
+        super(message, code, false);
+        this.name = 'SettingsError';
+    }
+}
+// ── SettingsManager ───────────────────────────────────────────────────────
+export class SettingsManager {
+    config;
+    projectConfigPath;
+    globalConfigPath;
+    projectConfig;
+    globalConfig;
+    listeners = [];
+    constructor(options) {
+        this.config = { ...options.config };
+        this.projectConfigPath = options.projectConfigPath;
+        this.globalConfigPath = options.globalConfigPath;
+        this.projectConfig = options.projectConfig ?? {};
+        this.globalConfig = options.globalConfig ?? {};
+    }
+    // ── Read ───────────────────────────────────────────────────────────────
+    get(dotKey) {
+        const entry = SETTINGS_MAP.get(dotKey);
+        if (!entry) {
+            throw new SettingsError(`Unknown setting: ${dotKey}. Use /settings list to see available keys.`, 'SETTINGS_INVALID_KEY');
+        }
+        const schema = SETTINGS_SCHEMA.get(dotKey);
+        const secret = isSecretField(dotKey);
+        // Check env var first (empty string = not explicitly set → fall through to default)
+        const envVar = ENV_VAR_MAP.get(dotKey);
+        if (envVar && process.env[envVar]) {
+            const raw = this.parseEnvValue(process.env[envVar], schema);
+            const value = secret && raw != null ? this.maskValue(String(raw)) : raw;
+            return { value, origin: `env: ${envVar}`, masked: secret };
+        }
+        // Check config, falling back to schema default
+        const raw = this.getValueByPath(this.config, entry.configPath);
+        const effectiveValue = raw ?? schema?.default;
+        const value = secret && effectiveValue != null ? this.maskValue(String(effectiveValue)) : effectiveValue;
+        const origin = raw !== undefined && raw !== null
+            ? this.resolveConfigOrigin(entry.configPath)
+            : schema?.default !== undefined ? 'default' : 'default';
+        return { value, origin, masked: secret };
+    }
+    list() {
+        const results = [];
+        for (const [dotKey, mapEntry] of SETTINGS_MAP) {
+            const schema = SETTINGS_SCHEMA.get(dotKey);
+            const { value, origin, masked } = this.get(dotKey);
+            results.push({
+                dotKey,
+                value,
+                origin,
+                masked,
+                category: mapEntry.category,
+                restartRequired: schema?.restartRequired ?? false,
+                label: mapEntry.label,
+            });
+        }
+        return results;
+    }
+    listByCategory() {
+        const result = {};
+        for (const entry of this.list()) {
+            if (!result[entry.category])
+                result[entry.category] = [];
+            result[entry.category].push(entry);
+        }
+        return result;
+    }
+    // ── Write ──────────────────────────────────────────────────────────────
+    async set(dotKey, rawValue) {
+        const mapEntry = SETTINGS_MAP.get(dotKey);
+        if (!mapEntry) {
+            throw new SettingsError(`Unknown setting: ${dotKey}. Use /settings list to see available keys.`, 'SETTINGS_INVALID_KEY');
+        }
+        const schema = SETTINGS_SCHEMA.get(dotKey);
+        const value = this.validateValue(dotKey, rawValue, schema);
+        // Determine write target
+        const writePath = this.resolveWriteTarget(dotKey);
+        if (!writePath) {
+            throw new SettingsError('No config file path available for writing.', 'SETTINGS_WRITE_FAILED');
+        }
+        // Check env var override
+        const envVar = ENV_VAR_MAP.get(dotKey);
+        if (envVar && process.env[envVar]) {
+            console.warn(`Note: This key is overridden by env var ${envVar}. Saving to config. The env var takes precedence until unset.`);
+        }
+        // Read current file, apply change, write
+        const fileConfig = await this.readConfigFile(writePath);
+        this.applyValueToConfig(fileConfig, mapEntry.configPath, value);
+        await this.persist(writePath, fileConfig);
+        // Update in-memory
+        this.applyValueToConfig(this.config, mapEntry.configPath, value);
+        this.emitChange([dotKey]);
+    }
+    async reset(dotKey) {
+        const mapEntry = SETTINGS_MAP.get(dotKey);
+        if (!mapEntry) {
+            throw new SettingsError(`Unknown setting: ${dotKey}. Use /settings list to see available keys.`, 'SETTINGS_INVALID_KEY');
+        }
+        const envVar = ENV_VAR_MAP.get(dotKey);
+        if (envVar && process.env[envVar]) {
+            throw new SettingsError(`Cannot reset: this value is set by env var ${envVar}. Unset the environment variable to use the default.`, 'SETTINGS_WRITE_FAILED');
+        }
+        const writePath = this.resolveWriteTarget(dotKey);
+        if (!writePath) {
+            throw new SettingsError('No config file path available for writing.', 'SETTINGS_WRITE_FAILED');
+        }
+        const fileConfig = await this.readConfigFile(writePath);
+        this.removeValueFromConfig(fileConfig, mapEntry.configPath);
+        await this.persist(writePath, fileConfig);
+        // Reset in-memory to default
+        const schema = SETTINGS_SCHEMA.get(dotKey);
+        if (schema?.default !== undefined) {
+            this.applyValueToConfig(this.config, mapEntry.configPath, schema.default);
+        }
+        else {
+            this.removeValueFromConfig(this.config, mapEntry.configPath);
+        }
+        this.emitChange([dotKey]);
+    }
+    async resetAll() {
+        const writePath = this.projectConfigPath ?? this.globalConfigPath;
+        if (!writePath)
+            return;
+        await this.persist(writePath, {});
+        // Rebuild config from env vars (preserving env overrides)
+        const rebuilt = {};
+        for (const [dotKey, envVar] of ENV_VAR_MAP) {
+            const val = process.env[envVar];
+            if (val != null) {
+                const entry = SETTINGS_MAP.get(dotKey);
+                if (entry)
+                    this.applyValueToConfig(rebuilt, entry.configPath, val);
+            }
+        }
+        this.config = rebuilt;
+        this.emitChange(['*']);
+    }
+    // ── Events ─────────────────────────────────────────────────────────────
+    onChange(callback) {
+        this.listeners.push(callback);
+        return () => {
+            this.listeners = this.listeners.filter(l => l !== callback);
+        };
+    }
+    // ── Internals ──────────────────────────────────────────────────────────
+    emitChange(changedKeys) {
+        for (const listener of this.listeners) {
+            try {
+                listener(changedKeys);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    validateValue(dotKey, raw, schema) {
+        if (!schema)
+            return raw;
+        switch (schema.type) {
+            case 'number': {
+                const num = Number(raw);
+                if (isNaN(num)) {
+                    throw new SettingsError(`${dotKey} must be a number. Got: "${raw}"`, 'SETTINGS_VALIDATION_FAILED');
+                }
+                if (schema.min !== undefined && num < schema.min) {
+                    throw new SettingsError(`${dotKey} must be >= ${schema.min}. Got: ${num}`, 'SETTINGS_VALIDATION_FAILED');
+                }
+                if (schema.max !== undefined && num > schema.max) {
+                    throw new SettingsError(`${dotKey} must be <= ${schema.max}. Got: ${num}`, 'SETTINGS_VALIDATION_FAILED');
+                }
+                return num;
+            }
+            case 'boolean': {
+                const lower = raw.toLowerCase();
+                if (lower === 'true' || lower === '1')
+                    return true;
+                if (lower === 'false' || lower === '0')
+                    return false;
+                throw new SettingsError(`${dotKey} must be true or false. Got: "${raw}"`, 'SETTINGS_VALIDATION_FAILED');
+            }
+            case 'enum': {
+                if (!schema.enumValues?.includes(raw)) {
+                    throw new SettingsError(`${dotKey} must be one of: ${schema.enumValues?.join(', ')}. Got: "${raw}"`, 'SETTINGS_VALIDATION_FAILED');
+                }
+                return raw;
+            }
+            case 'string': {
+                // URL validation for baseUrl/webhook fields
+                if (dotKey.includes('baseUrl') || dotKey.includes('.webhook')) {
+                    try {
+                        const parsed = new URL(raw);
+                        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                            throw new SettingsError(`${dotKey} must be a valid URL starting with http:// or https://.`, 'SETTINGS_VALIDATION_FAILED');
+                        }
+                        if (parsed.username || parsed.password) {
+                            throw new SettingsError(`${dotKey} must not contain embedded credentials.`, 'SETTINGS_VALIDATION_FAILED');
+                        }
+                    }
+                    catch (e) {
+                        if (e instanceof SettingsError)
+                            throw e;
+                        throw new SettingsError(`${dotKey} must be a valid URL starting with http:// or https://.`, 'SETTINGS_VALIDATION_FAILED');
+                    }
+                }
+                // Hostname validation
+                if (dotKey === 'smtp.host') {
+                    if (!/^[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?$/.test(raw)) {
+                        throw new SettingsError(`${dotKey} must be a valid hostname.`, 'SETTINGS_VALIDATION_FAILED');
+                    }
+                }
+                return raw;
+            }
+            default:
+                return raw;
+        }
+    }
+    resolveConfigOrigin(configPath) {
+        if (this.hasPath(this.projectConfig, configPath))
+            return 'project config';
+        if (this.hasPath(this.globalConfig, configPath))
+            return 'global config';
+        return 'default';
+    }
+    parseEnvValue(raw, schema) {
+        const val = raw ?? '';
+        if (!schema)
+            return val;
+        switch (schema.type) {
+            case 'boolean':
+                return val.toLowerCase() === 'true' || val === '1';
+            case 'number':
+                return Number(val);
+            default:
+                return val;
+        }
+    }
+    resolveWriteTarget(dotKey) {
+        const envVar = ENV_VAR_MAP.get(dotKey);
+        if (envVar && process.env[envVar]) {
+            // Write to project config when env var overrides
+            return this.projectConfigPath ?? this.globalConfigPath;
+        }
+        // Write to whichever config file currently owns the key
+        const entry = SETTINGS_MAP.get(dotKey);
+        if (!entry)
+            return this.projectConfigPath ?? this.globalConfigPath;
+        if (this.hasPath(this.projectConfig, entry.configPath) && this.projectConfigPath) {
+            return this.projectConfigPath;
+        }
+        if (this.hasPath(this.globalConfig, entry.configPath) && this.globalConfigPath) {
+            return this.globalConfigPath;
+        }
+        // New key — prefer project config if it exists
+        return this.projectConfigPath ?? this.globalConfigPath;
+    }
+    async readConfigFile(filePath) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
+    async persist(configPath, data) {
+        try {
+            const dir = path.dirname(configPath);
+            await fs.mkdir(dir, { recursive: true });
+            // Backup existing file
+            try {
+                await fs.rename(configPath, configPath + '.bak');
+            }
+            catch { /* no existing file to back up */ }
+            // Atomic write via temp file
+            const tmpPath = configPath + `.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+            await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+            await fs.rename(tmpPath, configPath);
+        }
+        catch (e) {
+            console.warn(`Warning: could not save to ${configPath}: ${e.message}. Change applied in-memory only.`);
+        }
+    }
+    getValueByPath(obj, pathParts) {
+        let current = obj;
+        for (const part of pathParts) {
+            if (current == null || typeof current !== 'object')
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    applyValueToConfig(obj, pathParts, value) {
+        if (pathParts.length === 0)
+            return;
+        // Deep merge for models map
+        if (pathParts[0] === 'models' && pathParts.length === 3) {
+            if (!obj.models)
+                obj.models = {};
+            const provider = pathParts[1];
+            if (!obj.models[provider])
+                obj.models[provider] = {};
+            obj.models[provider][pathParts[2]] = value;
+            return;
+        }
+        // Standard path
+        let current = obj;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            if (current[pathParts[i]] == null || typeof current[pathParts[i]] !== 'object') {
+                current[pathParts[i]] = {};
+            }
+            current = current[pathParts[i]];
+        }
+        current[pathParts[pathParts.length - 1]] = value;
+    }
+    removeValueFromConfig(obj, pathParts) {
+        if (pathParts.length === 0)
+            return;
+        if (pathParts.length === 1) {
+            delete obj[pathParts[0]];
+            return;
+        }
+        let current = obj;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            if (current[pathParts[i]] == null)
+                return;
+            current = current[pathParts[i]];
+        }
+        delete current[pathParts[pathParts.length - 1]];
+    }
+    hasPath(obj, pathParts) {
+        let current = obj;
+        for (const part of pathParts) {
+            if (current == null || typeof current !== 'object')
+                return false;
+            if (!(part in current))
+                return false;
+            current = current[part];
+        }
+        return true;
+    }
+    maskValue(value) {
+        if (!value || value.length < 8)
+            return '******';
+        return `${value.slice(0, 3)}...${value.slice(-4)}`;
+    }
+}