qlogicagent 0.2.1 → 0.4.0

package/dist/llm/model-catalog.d.ts

@@ -1,53 +0,0 @@
-/**
- * ModelCatalog — remote model directory with disk cache + fallback.
- *
- * Fetches model metadata from models.dev (open community catalog, 4000+ models).
- * Aligned with Hermes agent/models_dev.py caching strategy.
- *
- * Three-layer fallback:
- *   1. In-memory cache (process-level, TTL check against disk mtime)
- *   2. Disk cache (~/.openclaw/cache/model_catalog.json)
- *   3. Remote fetch (https://models.dev/api.json)
- *   4. Stale disk cache (if remote fails)
- *   5. Empty (caller falls back to builtin-providers.ts hardcoded)
- *
- * Non-blocking: first startup without cache returns empty immediately,
- * triggers background async fetch. Agent uses builtin providers until
- * catalog arrives.
- */
-import type { ModelInfo } from "./provider-def.js";
-export declare class ModelCatalog {
-    private cache;
-    private cacheDir;
-    private cacheFile;
-    private ttlMs;
-    private fetching;
-    private lastFetchAttempt;
-    constructor(opts?: {
-        cacheDir?: string;
-        ttlMs?: number;
-    });
-    /**
-     * Get models for a provider. Non-blocking: returns whatever is cached.
-     * Triggers background refresh if stale.
-     */
-    getModels(providerId: string): ModelInfo[];
-    /**
-     * Get a single model by provider + model id.
-     */
-    getModel(providerId: string, modelId: string): ModelInfo | undefined;
-    /**
-     * List all known provider ids from the catalog.
-     */
-    listProviderIds(): string[];
-    /**
-     * Force refresh from remote. Returns true if successful.
-     */
-    refreshCatalog(): Promise<boolean>;
-    private ensureLoaded;
-    private isStale;
-    private loadFromDisk;
-    private saveToDisk;
-    private backgroundFetch;
-    private fetchRemote;
-}

package/dist/llm/model-catalog.js

@@ -1,191 +0,0 @@
-/**
- * ModelCatalog — remote model directory with disk cache + fallback.
- *
- * Fetches model metadata from models.dev (open community catalog, 4000+ models).
- * Aligned with Hermes agent/models_dev.py caching strategy.
- *
- * Three-layer fallback:
- *   1. In-memory cache (process-level, TTL check against disk mtime)
- *   2. Disk cache (~/.openclaw/cache/model_catalog.json)
- *   3. Remote fetch (https://models.dev/api.json)
- *   4. Stale disk cache (if remote fails)
- *   5. Empty (caller falls back to builtin-providers.ts hardcoded)
- *
- * Non-blocking: first startup without cache returns empty immediately,
- * triggers background async fetch. Agent uses builtin providers until
- * catalog arrives.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-// ── Constants ────────────────────────────────────────────────────────────────
-const MODELS_DEV_URL = "https://models.dev/api.json";
-const FETCH_TIMEOUT_MS = 15_000;
-const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const RETRY_TTL_MS = 5 * 60 * 1000; // 5 min after failure
-// ── ModelCatalog class ───────────────────────────────────────────────────────
-export class ModelCatalog {
-    cache = null;
-    cacheDir;
-    cacheFile;
-    ttlMs;
-    fetching = false;
-    lastFetchAttempt = 0;
-    constructor(opts) {
-        this.cacheDir = opts?.cacheDir ?? join(homedir(), ".openclaw", "cache");
-        this.cacheFile = join(this.cacheDir, "model_catalog.json");
-        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-    }
-    /**
-     * Get models for a provider. Non-blocking: returns whatever is cached.
-     * Triggers background refresh if stale.
-     */
-    getModels(providerId) {
-        this.ensureLoaded();
-        const provider = this.cache?.providers.get(providerId);
-        if (!provider)
-            return [];
-        return [...provider.models.values()];
-    }
-    /**
-     * Get a single model by provider + model id.
-     */
-    getModel(providerId, modelId) {
-        this.ensureLoaded();
-        return this.cache?.providers.get(providerId)?.models.get(modelId);
-    }
-    /**
-     * List all known provider ids from the catalog.
-     */
-    listProviderIds() {
-        this.ensureLoaded();
-        return this.cache ? [...this.cache.providers.keys()] : [];
-    }
-    /**
-     * Force refresh from remote. Returns true if successful.
-     */
-    async refreshCatalog() {
-        return this.fetchRemote();
-    }
-    // ── Internal ──────────────────────────────────────────────────
-    ensureLoaded() {
-        if (this.cache && !this.isStale())
-            return;
-        // Try disk cache
-        if (!this.cache) {
-            this.loadFromDisk();
-        }
-        // Trigger background fetch if stale or missing
-        if (!this.cache || this.isStale()) {
-            this.backgroundFetch();
-        }
-    }
-    isStale() {
-        if (!this.cache)
-            return true;
-        return Date.now() - this.cache.fetchedAt > this.ttlMs;
-    }
-    loadFromDisk() {
-        try {
-            if (!existsSync(this.cacheFile))
-                return;
-            const raw = readFileSync(this.cacheFile, "utf8");
-            const parsed = JSON.parse(raw);
-            if (!parsed.fetchedAt || !parsed.data)
-                return;
-            this.cache = {
-                fetchedAt: parsed.fetchedAt,
-                providers: parseModelsDevResponse(parsed.data),
-            };
-        }
-        catch {
-            // Corrupted cache file — ignore
-        }
-    }
-    saveToDisk(data) {
-        try {
-            mkdirSync(this.cacheDir, { recursive: true });
-            const payload = JSON.stringify({ fetchedAt: Date.now(), data }, null, 0);
-            writeFileSync(this.cacheFile, payload, "utf8");
-        }
-        catch {
-            // Disk write failure — non-fatal
-        }
-    }
-    backgroundFetch() {
-        if (this.fetching)
-            return;
-        // Don't retry too soon after a failure
-        if (Date.now() - this.lastFetchAttempt < RETRY_TTL_MS)
-            return;
-        this.fetching = true;
-        this.fetchRemote().finally(() => {
-            this.fetching = false;
-        });
-    }
-    async fetchRemote() {
-        this.lastFetchAttempt = Date.now();
-        try {
-            const response = await fetch(MODELS_DEV_URL, {
-                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-                headers: { Accept: "application/json" },
-            });
-            if (!response.ok) {
-                return false;
-            }
-            const data = await response.json();
-            const providers = parseModelsDevResponse(data);
-            if (providers.size === 0) {
-                return false;
-            }
-            this.cache = { fetchedAt: Date.now(), providers };
-            this.saveToDisk(data);
-            return true;
-        }
-        catch {
-            // Network failure — keep stale cache if any
-            return false;
-        }
-    }
-}
-// ── Parser: models.dev JSON → CatalogProvider map ────────────────────────────
-/**
- * Parse models.dev api.json response.
- * Format: { provider_id: { models: { model_name: { ... } } } }
- */
-function parseModelsDevResponse(data) {
-    const providers = new Map();
-    if (!data || typeof data !== "object")
-        return providers;
-    for (const [providerId, providerData] of Object.entries(data)) {
-        if (!providerData || typeof providerData !== "object")
-            continue;
-        const modelsObj = providerData.models;
-        if (!modelsObj || typeof modelsObj !== "object")
-            continue;
-        const models = new Map();
-        for (const [modelId, modelData] of Object.entries(modelsObj)) {
-            if (!modelData || typeof modelData !== "object")
-                continue;
-            const m = modelData;
-            const limit = m.limit ?? {};
-            const modalities = m.modalities ?? {};
-            const inputMods = Array.isArray(modalities.input) ? modalities.input : [];
-            models.set(modelId, {
-                id: modelId,
-                name: typeof m.name === "string" ? m.name : modelId,
-                contextWindow: typeof limit.context === "number" ? limit.context : 200_000,
-                maxOutput: typeof limit.output === "number" ? limit.output : 8_192,
-                toolCall: m.tool_call === true,
-                reasoning: m.reasoning === true,
-                vision: m.attachment === true || inputMods.includes("image"),
-                costInput: typeof m.cost_input === "number" ? m.cost_input : undefined,
-                costOutput: typeof m.cost_output === "number" ? m.cost_output : undefined,
-            });
-        }
-        if (models.size > 0) {
-            providers.set(providerId, { models });
-        }
-    }
-    return providers;
-}

package/dist/llm/provider-def.d.ts

@@ -1,59 +0,0 @@
-/**
- * ProviderDef — defines how to connect to an LLM provider.
- *
- * Aligned with Hermes `ProviderDef` dataclass pattern:
- *   id + name + transport type + baseUrl + auth config + model list
- *
- * Three-layer merge strategy (Layer 3 > Layer 2 > Layer 1):
- *   Layer 1: builtin-providers.ts hardcoded (fallback)
- *   Layer 2: model-catalog.ts remote (models.dev)
- *   Layer 3: user config (from agent.turn.config)
- */
-export type TransportType = "openai-chat" | "anthropic-messages";
-export type AuthType = "bearer" | "x-api-key" | "none";
-export interface ProviderDef {
-    /** Unique provider id, e.g. "deepseek", "openai", "anthropic" */
-    id: string;
-    /** Display name, e.g. "DeepSeek" */
-    name: string;
-    /** Which transport to use for LLM calls */
-    transport: TransportType;
-    /** API base URL, e.g. "https://api.deepseek.com" */
-    baseUrl: string;
-    /** Env var names for API key (priority order) */
-    apiKeyEnvVars: string[];
-    /** Auth header style */
-    authType: AuthType;
-    /** Is an aggregator (OpenRouter, 硅基) — model ids may have prefix */
-    isAggregator: boolean;
-    /** Recommended default model */
-    defaultModel?: string;
-    /** Known models for this provider */
-    models?: ModelInfo[];
-    /** Extra headers to send with every request (e.g. aggregator-specific) */
-    extraHeaders?: Record<string, string>;
-    /** Whether this provider supports stream_options (default true for openai-chat) */
-    supportsStreamOptions?: boolean;
-    /** Whether to omit temperature when it equals 0 (some providers reject 0) */
-    omitZeroTemperature?: boolean;
-}
-export interface ModelInfo {
-    /** Model id, e.g. "deepseek-chat" */
-    id: string;
-    /** Display name, e.g. "DeepSeek Chat V3" */
-    name: string;
-    /** Context window in tokens */
-    contextWindow: number;
-    /** Max output tokens */
-    maxOutput: number;
-    /** Supports function/tool calling */
-    toolCall: boolean;
-    /** Has reasoning/thinking mode */
-    reasoning: boolean;
-    /** Supports vision (image input) */
-    vision: boolean;
-    /** Cost per 1M input tokens (USD) */
-    costInput?: number;
-    /** Cost per 1M output tokens (USD) */
-    costOutput?: number;
-}

package/dist/llm/provider-def.js

@@ -1,12 +0,0 @@
-/**
- * ProviderDef — defines how to connect to an LLM provider.
- *
- * Aligned with Hermes `ProviderDef` dataclass pattern:
- *   id + name + transport type + baseUrl + auth config + model list
- *
- * Three-layer merge strategy (Layer 3 > Layer 2 > Layer 1):
- *   Layer 1: builtin-providers.ts hardcoded (fallback)
- *   Layer 2: model-catalog.ts remote (models.dev)
- *   Layer 3: user config (from agent.turn.config)
- */
-export {};

package/dist/llm/provider-registry.d.ts

@@ -1,54 +0,0 @@
-/**
- * ProviderRegistry — three-layer merge registry for LLM providers.
- *
- * Layer 1: builtin-providers.ts hardcoded (lowest priority, ~20 providers)
- * Layer 2: model-catalog.ts remote (models.dev — enriches model metadata)
- * Layer 3: user config override (from agent.turn.config — highest priority)
- *
- * Merge strategy: Layer 3 > Layer 2 > Layer 1 (later layers override same-id fields)
- *
- * Aligned with Hermes provider_registry.py.
- */
-import type { ModelInfo, ProviderDef } from "./provider-def.js";
-import { ModelCatalog } from "./model-catalog.js";
-export declare class ProviderRegistry {
-    /** Layer 1: builtin hardcoded providers */
-    private builtins;
-    /** Layer 2: remote model catalog (models.dev) */
-    private catalog;
-    /** Layer 3: user overrides (from agent.turn.config) */
-    private overrides;
-    constructor(opts?: {
-        catalog?: ModelCatalog;
-    });
-    /**
-     * Apply user config override for a provider.
-     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
-     */
-    applyOverride(providerId: string, override: Partial<ProviderDef>): void;
-    /**
-     * Get merged ProviderDef by id (Layer 3 > Layer 1).
-     * Returns undefined if provider not found.
-     * Supports common aliases (e.g., "claude" → "anthropic").
-     */
-    getProvider(id: string): ProviderDef | undefined;
-    /**
-     * List all known provider ids.
-     */
-    listProviders(): ProviderDef[];
-    /**
-     * List models for a specific provider.
-     * Merges: Layer 3 override > Layer 1 builtin > Layer 2 catalog enrichment.
-     */
-    listModels(providerId: string): ModelInfo[];
-    /**
-     * Trigger background refresh of the remote model catalog.
-     */
-    refreshCatalog(): Promise<boolean>;
-    /**
-     * Resolve API key for a provider:
-     *   1. Explicit key (from agent.turn.config)
-     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
-     */
-    resolveApiKey(providerId: string, explicitKey?: string): string | undefined;
-}

package/dist/llm/provider-registry.js

@@ -1,147 +0,0 @@
-/**
- * ProviderRegistry — three-layer merge registry for LLM providers.
- *
- * Layer 1: builtin-providers.ts hardcoded (lowest priority, ~20 providers)
- * Layer 2: model-catalog.ts remote (models.dev — enriches model metadata)
- * Layer 3: user config override (from agent.turn.config — highest priority)
- *
- * Merge strategy: Layer 3 > Layer 2 > Layer 1 (later layers override same-id fields)
- *
- * Aligned with Hermes provider_registry.py.
- */
-import { BUILTIN_PROVIDERS } from "./builtin-providers.js";
-import { ModelCatalog } from "./model-catalog.js";
-// Provider alias map (Hermes-aligned): common user names → canonical ids
-const PROVIDER_ALIASES = {
-    claude: "anthropic",
-    gemini: "google",
-    "x-ai": "xai",
-    "z-ai": "xai",
-    silicon: "siliconflow",
-    "silicon-flow": "siliconflow",
-};
-export class ProviderRegistry {
-    /** Layer 1: builtin hardcoded providers */
-    builtins = new Map();
-    /** Layer 2: remote model catalog (models.dev) */
-    catalog;
-    /** Layer 3: user overrides (from agent.turn.config) */
-    overrides = new Map();
-    constructor(opts) {
-        for (const p of BUILTIN_PROVIDERS) {
-            this.builtins.set(p.id, p);
-        }
-        this.catalog = opts?.catalog ?? new ModelCatalog();
-    }
-    /**
-     * Apply user config override for a provider.
-     * Typically called when agent.turn.config has baseUrl/apiKey overrides.
-     */
-    applyOverride(providerId, override) {
-        this.overrides.set(providerId, {
-            ...this.overrides.get(providerId),
-            ...override,
-        });
-    }
-    /**
-     * Get merged ProviderDef by id (Layer 3 > Layer 1).
-     * Returns undefined if provider not found.
-     * Supports common aliases (e.g., "claude" → "anthropic").
-     */
-    getProvider(id) {
-        const resolvedId = PROVIDER_ALIASES[id] ?? id;
-        const builtin = this.builtins.get(resolvedId);
-        const override = this.overrides.get(resolvedId);
-        if (!builtin && !override)
-            return undefined;
-        if (!builtin && override) {
-            // User defined a custom provider entirely
-            if (!override.id || !override.transport || !override.baseUrl) {
-                return undefined;
-            }
-            return {
-                id: override.id,
-                name: override.name ?? override.id,
-                transport: override.transport,
-                baseUrl: override.baseUrl,
-                apiKeyEnvVars: override.apiKeyEnvVars ?? [],
-                authType: override.authType ?? "bearer",
-                isAggregator: override.isAggregator ?? false,
-                defaultModel: override.defaultModel,
-                models: override.models,
-            };
-        }
-        if (builtin && !override)
-            return builtin;
-        // Merge: override fields take precedence
-        return {
-            ...builtin,
-            ...override,
-            // Merge models: override models replace if provided
-            models: override.models ?? builtin.models,
-        };
-    }
-    /**
-     * List all known provider ids.
-     */
-    listProviders() {
-        const all = new Map();
-        for (const [id, p] of this.builtins) {
-            all.set(id, p);
-        }
-        // Override/custom providers
-        for (const [id] of this.overrides) {
-            const merged = this.getProvider(id);
-            if (merged)
-                all.set(id, merged);
-        }
-        return [...all.values()];
-    }
-    /**
-     * List models for a specific provider.
-     * Merges: Layer 3 override > Layer 1 builtin > Layer 2 catalog enrichment.
-     */
-    listModels(providerId) {
-        const provider = this.getProvider(providerId);
-        const builtinModels = provider?.models ?? [];
-        // Enrich with catalog data (Layer 2): catalog provides updated context windows,
-        // costs, and capability flags; builtin models take precedence for known fields.
-        const catalogModels = this.catalog.getModels(providerId);
-        if (catalogModels.length === 0)
-            return builtinModels;
-        // Build merged model list: builtin first, then catalog models not in builtin
-        const byId = new Map();
-        for (const cm of catalogModels) {
-            byId.set(cm.id, cm);
-        }
-        for (const bm of builtinModels) {
-            // Builtin overrides catalog for same id (builtin has curated values)
-            byId.set(bm.id, bm);
-        }
-        return [...byId.values()];
-    }
-    /**
-     * Trigger background refresh of the remote model catalog.
-     */
-    async refreshCatalog() {
-        return this.catalog.refreshCatalog();
-    }
-    /**
-     * Resolve API key for a provider:
-     *   1. Explicit key (from agent.turn.config)
-     *   2. Environment variables (ProviderDef.apiKeyEnvVars)
-     */
-    resolveApiKey(providerId, explicitKey) {
-        if (explicitKey)
-            return explicitKey;
-        const provider = this.getProvider(providerId);
-        if (!provider)
-            return undefined;
-        for (const envVar of provider.apiKeyEnvVars) {
-            const value = process.env[envVar];
-            if (value?.trim())
-                return value.trim();
-        }
-        return undefined;
-    }
-}

package/dist/llm/transport.d.ts

@@ -1,62 +0,0 @@
-/**
- * LLMTransport — abstract interface for LLM inference calls.
- *
- * Aligned with Hermes `ProviderTransport` ABC:
- *   stream(request, apiKey, signal) → AsyncGenerator<LLMChunk>
- *
- * Two concrete implementations:
- *   - OpenAI Chat Completions (covers 95% of providers)
- *   - Anthropic Messages API
- */
-import type { ChatMessage, ToolDefinition } from "../agent/types.js";
-export interface LLMRequest {
-    model: string;
-    messages: ChatMessage[];
-    tools?: ToolDefinition[];
-    toolChoice?: "auto" | "none" | "required";
-    temperature?: number;
-    maxTokens?: number;
-    reasoning?: {
-        effort: "low" | "medium" | "high";
-    };
-}
-export type LLMChunk = {
-    type: "delta";
-    text: string;
-} | {
-    type: "tool_call_delta";
-    index: number;
-    id?: string;
-    name?: string;
-    arguments: string;
-} | {
-    type: "reasoning_delta";
-    text: string;
-} | {
-    type: "usage";
-    promptTokens: number;
-    completionTokens: number;
-    reasoningTokens?: number;
-} | {
-    type: "done";
-    finishReason: string;
-};
-export interface AccumulatedToolCall {
-    id: string;
-    name: string;
-    arguments: string;
-}
-export interface LLMTransport {
-    /**
-     * Stream an LLM inference request.
-     * apiKey is passed explicitly (from agent.turn.config, not env).
-     */
-    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
-}
-/**
- * Accumulate tool_call_delta chunks into complete ToolCall objects.
- * Modeled after admin-infer-proxy-client's Map<index, toolCall> accumulator.
- */
-export declare function accumulateToolCalls(accumulator: Map<number, AccumulatedToolCall>, chunk: LLMChunk & {
-    type: "tool_call_delta";
-}): void;

package/dist/llm/transport.js

@@ -1,27 +0,0 @@
-/**
- * LLMTransport — abstract interface for LLM inference calls.
- *
- * Aligned with Hermes `ProviderTransport` ABC:
- *   stream(request, apiKey, signal) → AsyncGenerator<LLMChunk>
- *
- * Two concrete implementations:
- *   - OpenAI Chat Completions (covers 95% of providers)
- *   - Anthropic Messages API
- */
-// ── Convenience: aggregate chunks to tool calls ──────────────────────────────
-/**
- * Accumulate tool_call_delta chunks into complete ToolCall objects.
- * Modeled after admin-infer-proxy-client's Map<index, toolCall> accumulator.
- */
-export function accumulateToolCalls(accumulator, chunk) {
-    let tc = accumulator.get(chunk.index);
-    if (!tc) {
-        tc = { id: "", name: "", arguments: "" };
-        accumulator.set(chunk.index, tc);
-    }
-    if (chunk.id)
-        tc.id = chunk.id;
-    if (chunk.name)
-        tc.name += chunk.name;
-    tc.arguments += chunk.arguments;
-}

package/dist/llm/transports/anthropic-messages.d.ts

@@ -1,31 +0,0 @@
-/**
- * Anthropic Messages Transport — SSE streaming for Claude API.
- *
- * POST {baseUrl}/v1/messages with stream: true
- * Auth: x-api-key: {apiKey} + anthropic-version header
- *
- * SSE event types:
- *   message_start, content_block_start, content_block_delta,
- *   content_block_stop, message_delta, message_stop
- *
- * Tool use is via content blocks with type "tool_use" + "input_json_delta".
- *
- * Aligned with Hermes anthropic_messages.py transport.
- */
-import type { LLMChunk, LLMRequest, LLMTransport } from "../transport.js";
-export interface AnthropicTransportConfig {
-    baseUrl: string;
-    /** anthropic-version header (default "2023-06-01") */
-    apiVersion?: string;
-    /** Timeout in ms (default 180_000) */
-    timeoutMs?: number;
-}
-export declare class AnthropicMessagesTransport implements LLMTransport {
-    private baseUrl;
-    private apiVersion;
-    private timeoutMs;
-    constructor(config: AnthropicTransportConfig);
-    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
-    private parseSSEStream;
-    private mapEvent;
-}