agim-cli 1.2.45 → 1.2.49

package/dist/core/llm/registry.js

@@ -0,0 +1,160 @@
+// LLM registry — role-based provider lookup, Stage 1.
+//
+// Callers don't know (or care) which concrete backend handles their
+// request; they ask the registry for a *role* ('cheap' for distill /
+// intent-llm, 'evaluator' for future heartbeat) and the registry hands
+// back a configured LlmProvider — or null when nothing is configured,
+// in which case the caller falls back to its CLI agent path.
+//
+// Lifecycle:
+//   - `loadFromConfig(cfg)` is called once at startup from cli.ts; it
+//     instantiates one provider per `llmBackends` entry, filters out
+//     unconfigured backends (no secret), and builds the role index.
+//   - `reload()` re-reads the config + secrets from disk (used by web
+//     "Test connection" and future hot-config reload). Tests use it to
+//     swap out fixtures without restarting bun.
+//   - `getProvider(role)` is the hot path; returns null fast.
+//
+// The registry is intentionally a module-level singleton — the same
+// pattern as `core/registry.ts` (agents). Module-level state is
+// acceptable here because every Stage-1 caller is server-side and
+// agim's process model is single-instance.
+import { logger as rootLogger } from '../logger.js';
+import { OpenAICompatProvider } from './openai-compat-provider.js';
+import { AnthropicProvider } from './anthropic-provider.js';
+import { resolveSecret, loadSecretsFile } from './secrets.js';
+const log = rootLogger.child({ component: 'llm-registry' });
+let state = freshState();
+function freshState() {
+    return {
+        providers: new Map(),
+        roles: new Map(),
+        unconfigured: new Set(),
+        duplicates: new Set(),
+    };
+}
+/**
+ * Build the registry from a validated config. Idempotent — repeated
+ * calls fully replace the previous state. Logs (info / warn) the load
+ * outcome so operators see what landed at startup.
+ */
+export function loadFromConfig(cfg) {
+    const next = freshState();
+    const backends = Array.isArray(cfg.llmBackends)
+        ? cfg.llmBackends
+        : [];
+    // Pre-load secrets file once so each provider construction doesn't
+    // re-read it from disk.
+    const secrets = loadSecretsFile();
+    for (const raw of backends) {
+        const cfg = raw;
+        if (!cfg || typeof cfg !== 'object' || typeof cfg.name !== 'string')
+            continue;
+        if (cfg.enabled === false) {
+            log.debug({ event: 'llm-registry.skip_disabled', name: cfg.name });
+            continue;
+        }
+        if (next.providers.has(cfg.name)) {
+            next.duplicates.add(cfg.name);
+            log.warn({ event: 'llm-registry.duplicate_name', name: cfg.name }, `Duplicate llmBackends entry "${cfg.name}"; last wins`);
+        }
+        const apiKey = resolveSecret(cfg.name, secrets);
+        const provider = buildProvider(cfg, apiKey);
+        if (!provider)
+            continue;
+        if (!provider.isConfigured()) {
+            next.unconfigured.add(cfg.name);
+            log.info({ event: 'llm-registry.unconfigured', name: cfg.name }, `LLM backend "${cfg.name}" has no secret; skipped (caller will fall back to CLI agent)`);
+            continue;
+        }
+        next.providers.set(cfg.name, provider);
+    }
+    const roleMap = cfg.llmRoles;
+    if (roleMap && typeof roleMap === 'object') {
+        for (const [role, backendName] of Object.entries(roleMap)) {
+            if (typeof backendName !== 'string' || !backendName)
+                continue;
+            next.roles.set(role, backendName);
+            if (!next.providers.has(backendName)) {
+                log.warn({ event: 'llm-registry.role_dangling', role, backend: backendName }, `llmRoles.${role} points at "${backendName}" which has no configured backend`);
+            }
+        }
+    }
+    state = next;
+    log.info({
+        event: 'llm-registry.loaded',
+        backends: state.providers.size,
+        roles: state.roles.size,
+        unconfigured: state.unconfigured.size,
+    });
+}
+/**
+ * Get the provider configured for `role`, or null when no usable
+ * backend is wired. Callers should NEVER throw on null — that's how the
+ * registry tells them "fall back to your CLI path".
+ */
+export function getProvider(role) {
+    const backend = state.roles.get(role);
+    if (!backend)
+        return null;
+    return state.providers.get(backend) ?? null;
+}
+/** Look up a provider directly by backend name (mostly for the web
+ *  "Test connection" button and unit tests). */
+export function getProviderByName(name) {
+    return state.providers.get(name) ?? null;
+}
+/** List all configured backends — handy for the web UI roster. */
+export function listProviders() {
+    return Array.from(state.providers.values()).map(p => ({
+        name: p.name,
+        providerType: p.providerType,
+        model: p.model,
+    }));
+}
+/** Test/diagnostic: clear the registry. Used by bun tests so module
+ *  state doesn't leak across cases. */
+export function _resetRegistry() {
+    state = freshState();
+}
+/** Diagnostic snapshot for the cost dashboard's "LLM backends" tile. */
+export function describeRegistry() {
+    return {
+        backends: listProviders(),
+        roles: Object.fromEntries(state.roles),
+        unconfigured: Array.from(state.unconfigured).sort(),
+    };
+}
+function buildProvider(cfg, apiKey) {
+    switch (cfg.provider) {
+        case 'openai-compat':
+            return new OpenAICompatProvider({
+                name: cfg.name,
+                model: cfg.model,
+                apiKey,
+                baseUrl: cfg.baseUrl,
+                providerLabel: cfg.label,
+                extraHeaders: cfg.extraHeaders,
+                defaultTemperature: cfg.temperature,
+                defaultMaxTokens: cfg.maxTokens,
+                retryOnTransient: cfg.retryOnTransient,
+            });
+        case 'anthropic':
+            return new AnthropicProvider({
+                name: cfg.name,
+                model: cfg.model,
+                apiKey,
+                baseUrl: cfg.baseUrl,
+                providerLabel: cfg.label,
+                extraHeaders: cfg.extraHeaders,
+                defaultTemperature: cfg.temperature,
+                defaultMaxTokens: cfg.maxTokens,
+                retryOnTransient: cfg.retryOnTransient,
+            });
+        default:
+            // Future: ollama-native, bedrock, vertex.
+            log.warn({ event: 'llm-registry.unknown_provider', name: cfg.name, provider: cfg.provider }, `Unknown LLM provider "${cfg.provider}" for backend "${cfg.name}"; skipped`);
+            return null;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/llm/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/core/llm/registry.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/secrets.d.ts

@@ -0,0 +1,46 @@
+export declare const LLM_SECRETS_PATH: string;
+interface SecretsFile {
+    version: number;
+    keys: Record<string, string>;
+}
+/** Convert a backend name to the env var suffix. Same rule as the rest
+ *  of the codebase: non-alphanumeric → underscore, uppercased. So
+ *  "deepseek-cheap" → "AGIM_LLM_SECRET_DEEPSEEK_CHEAP". */
+export declare function envKeyForBackend(name: string): string;
+/**
+ * Read the on-disk secrets file (or return an empty SecretsFile if missing / corrupt).
+ * Logs a warning on corrupt files so operators notice — we deliberately
+ * don't throw because callers want the provider to gracefully report
+ * "not configured" rather than crash agim at startup.
+ */
+export declare function loadSecretsFile(): SecretsFile;
+/**
+ * Resolve a single secret for a backend, applying env-var precedence.
+ * Returns undefined when nothing is configured — providers downstream
+ * use this to flip `isConfigured()` off.
+ */
+export declare function resolveSecret(backendName: string, fileSecrets?: SecretsFile): string | undefined;
+/**
+ * Persist a secret. Idempotent — writes the entire file with 0600
+ * perms. Used by the CLI wizard (`agim config llm add`) once we land
+ * Stage 4; Stage 1 ships the helper so tests can exercise it.
+ */
+export declare function saveSecret(backendName: string, apiKey: string): void;
+/** Remove a secret entirely. Safe to call on missing names. */
+export declare function removeSecret(backendName: string): void;
+/** Test helper: list configured backend names (no values). */
+export declare function listConfiguredBackends(): string[];
+/**
+ * One-shot health check used by the CLI wizard + web "test backend"
+ * button. Returns a short reason string when something looks off so the
+ * UI doesn't have to guess. The string is operator-facing; keep it
+ * succinct and actionable.
+ */
+export declare function describeSecretSource(backendName: string): {
+    source: 'env' | 'file' | 'none';
+    envKey: string;
+    filePath: string;
+    perms?: string;
+};
+export {};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/core/llm/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/core/llm/secrets.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,gBAAgB,QAAsC,CAAA;AAEnE,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AASD;;2DAE2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,WAAW,CAmB7C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAQhG;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAMpE;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAKtD;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAoBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG;IACzD,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAaA"}

package/dist/core/llm/secrets.js

@@ -0,0 +1,157 @@
+// LLM secrets store — `~/.agim/llm-secrets.json` with 0600 perms.
+//
+// Why a separate file (not the main config):
+//   - config.json is committed/backed up in many user setups; api keys
+//     belong somewhere we can chmod 0600 without changing user habits.
+//   - Aligns with the same pattern used for `~/.agim/acp-token` and the
+//     web token — secrets live next to their public config but stay in
+//     their own file.
+//
+// File format (intentionally tiny):
+//   {
+//     "version": 1,
+//     "keys": { "<backend-name>": "<api-key>" }
+//   }
+//
+// Lookup precedence (callers go through `resolveSecret`):
+//   1. process.env `AGIM_LLM_SECRET_<UPPER_BACKEND_NAME>` — wins.
+//      Lets systemd unit files / CI / cloud agents inject without
+//      touching the on-disk file. Hyphens in the backend name are
+//      converted to underscores for the env var name.
+//   2. ~/.agim/llm-secrets.json `keys.<backend-name>`.
+//   3. undefined (provider will report isConfigured()=false).
+import { existsSync, readFileSync, writeFileSync, chmodSync, mkdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { AGIM_HOME } from '../agim-paths.js';
+import { logger as rootLogger } from '../logger.js';
+const log = rootLogger.child({ component: 'llm-secrets' });
+export const LLM_SECRETS_PATH = join(AGIM_HOME, 'llm-secrets.json');
+function emptyFile() {
+    // Fresh object every call. Returning a shared `EMPTY` const would let
+    // a caller's mutation (e.g. saveSecret stamping the keys map) leak
+    // back into the next loadSecretsFile() call. Cheap to allocate.
+    return { version: 1, keys: {} };
+}
+/** Convert a backend name to the env var suffix. Same rule as the rest
+ *  of the codebase: non-alphanumeric → underscore, uppercased. So
+ *  "deepseek-cheap" → "AGIM_LLM_SECRET_DEEPSEEK_CHEAP". */
+export function envKeyForBackend(name) {
+    const safe = name.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase();
+    return `AGIM_LLM_SECRET_${safe}`;
+}
+/**
+ * Read the on-disk secrets file (or return an empty SecretsFile if missing / corrupt).
+ * Logs a warning on corrupt files so operators notice — we deliberately
+ * don't throw because callers want the provider to gracefully report
+ * "not configured" rather than crash agim at startup.
+ */
+export function loadSecretsFile() {
+    try {
+        if (!existsSync(LLM_SECRETS_PATH))
+            return emptyFile();
+        const raw = readFileSync(LLM_SECRETS_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.keys || typeof parsed.keys !== 'object') {
+            log.warn({ event: 'llm-secrets.malformed', path: LLM_SECRETS_PATH });
+            return emptyFile();
+        }
+        // Coerce keys to strings; ignore non-string values silently.
+        const clean = {};
+        for (const [k, v] of Object.entries(parsed.keys)) {
+            if (typeof v === 'string' && v.length > 0)
+                clean[k] = v;
+        }
+        return { version: parsed.version === 1 ? 1 : 1, keys: clean };
+    }
+    catch (err) {
+        log.warn({ event: 'llm-secrets.read_failed', err: String(err) });
+        return emptyFile();
+    }
+}
+/**
+ * Resolve a single secret for a backend, applying env-var precedence.
+ * Returns undefined when nothing is configured — providers downstream
+ * use this to flip `isConfigured()` off.
+ */
+export function resolveSecret(backendName, fileSecrets) {
+    if (!backendName)
+        return undefined;
+    const envKey = envKeyForBackend(backendName);
+    const envVal = process.env[envKey];
+    if (envVal && envVal.length > 0)
+        return envVal;
+    const file = fileSecrets ?? loadSecretsFile();
+    const v = file.keys[backendName];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/**
+ * Persist a secret. Idempotent — writes the entire file with 0600
+ * perms. Used by the CLI wizard (`agim config llm add`) once we land
+ * Stage 4; Stage 1 ships the helper so tests can exercise it.
+ */
+export function saveSecret(backendName, apiKey) {
+    if (!backendName)
+        throw new Error('saveSecret: backendName is required');
+    if (!apiKey)
+        throw new Error('saveSecret: apiKey is required (use removeSecret to delete)');
+    const file = loadSecretsFile();
+    file.keys[backendName] = apiKey;
+    _writeFile(file);
+}
+/** Remove a secret entirely. Safe to call on missing names. */
+export function removeSecret(backendName) {
+    const file = loadSecretsFile();
+    if (!(backendName in file.keys))
+        return;
+    delete file.keys[backendName];
+    _writeFile(file);
+}
+/** Test helper: list configured backend names (no values). */
+export function listConfiguredBackends() {
+    return Object.keys(loadSecretsFile().keys).sort();
+}
+function _writeFile(file) {
+    // Ensure the parent directory exists; AGIM_HOME might still be a fresh
+    // install where nothing else has written yet.
+    const dir = dirname(LLM_SECRETS_PATH);
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // Best-effort; if we can't even mkdir, the writeFile below will
+        // throw a clearer error.
+    }
+    const payload = `${JSON.stringify(file, null, 2)}\n`;
+    writeFileSync(LLM_SECRETS_PATH, payload, { encoding: 'utf-8', mode: 0o600 });
+    // writeFileSync's mode is advisory on some filesystems; chmodSync is
+    // the belt-and-suspenders that matches how the bootstrap token writer
+    // does it elsewhere in the codebase.
+    try {
+        chmodSync(LLM_SECRETS_PATH, 0o600);
+    }
+    catch { /* ignore */ }
+}
+/**
+ * One-shot health check used by the CLI wizard + web "test backend"
+ * button. Returns a short reason string when something looks off so the
+ * UI doesn't have to guess. The string is operator-facing; keep it
+ * succinct and actionable.
+ */
+export function describeSecretSource(backendName) {
+    const envKey = envKeyForBackend(backendName);
+    if (process.env[envKey])
+        return { source: 'env', envKey, filePath: LLM_SECRETS_PATH };
+    const file = loadSecretsFile();
+    if (file.keys[backendName]) {
+        let perms;
+        try {
+            const st = statSync(LLM_SECRETS_PATH);
+            perms = `0${(st.mode & 0o777).toString(8)}`;
+        }
+        catch { /* ignore */ }
+        return { source: 'file', envKey, filePath: LLM_SECRETS_PATH, perms };
+    }
+    return { source: 'none', envKey, filePath: LLM_SECRETS_PATH };
+}
+//# sourceMappingURL=secrets.js.map

package/dist/core/llm/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/core/llm/secrets.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/tool-dispatcher.d.ts

@@ -0,0 +1,37 @@
+import type { ToolCallRequest } from './provider-base.js';
+/** Outcome of executing one tool call. Mirrors mcp-client.ToolCallResult
+ *  so dispatchers can pass it through unchanged. */
+export interface DispatcherResult {
+    text: string;
+    isError: boolean;
+    /** Optional dispatcher tag for audit / debug — e.g. 'mcp:filesystem'
+     *  or 'builtin'. Lets the agent loop's audit row distinguish where
+     *  the cost is going. Default empty string. */
+    source?: string;
+}
+/**
+ * Async function the agent loop invokes once per tool call. Signal is
+ * the loop's overall AbortSignal — dispatchers should honor it to
+ * abort in-flight tool work on /stop or timeout.
+ */
+export type ToolDispatcher = (call: ToolCallRequest, signal: AbortSignal) => Promise<DispatcherResult>;
+/**
+ * Build the default dispatcher: every call name beginning with `mcp_`
+ * is routed to the MCP registry; everything else gets a graceful
+ * "tool unknown" error. The agent loop's job is to surface that error
+ * back to the model so it can choose a different tool or give up.
+ */
+export declare function buildMcpDispatcher(): ToolDispatcher;
+/**
+ * Stack dispatchers: the first one that returns a non-"unknown" result
+ * wins. Use this in sub-PR #4 to put built-in tools above MCP, so
+ * `echo` / `time` etc. resolve locally and don't accidentally hit a
+ * server's same-named tool.
+ *
+ * Implementation note: we identify "unknown" by checking `source ===
+ * 'unknown'`. Dispatchers signal "I don't handle this" by returning
+ * isError=true with source='unknown'; everything else (including
+ * domain-level tool errors) is considered handled.
+ */
+export declare function combineDispatchers(...dispatchers: ToolDispatcher[]): ToolDispatcher;
+//# sourceMappingURL=tool-dispatcher.d.ts.map

package/dist/core/llm/tool-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/llm/tool-dispatcher.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGzD;oDACoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB;;mDAE+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAE9B;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CAgBnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,WAAW,EAAE,cAAc,EAAE,GAAG,cAAc,CAmBnF"}

package/dist/core/llm/tool-dispatcher.js

@@ -0,0 +1,85 @@
+// tool-dispatcher — routes a ToolCallRequest to the right executor
+// (Stage 2 sub-PR #3).
+//
+// The agent loop doesn't want to know WHERE each tool lives. It just
+// produces a ToolCallRequest and asks the dispatcher to run it. This
+// keeps the loop testable (stub dispatcher) and lets us add new tool
+// sources (built-in agim tools, sub-agent delegate, remote ACP tools,
+// …) later without touching the loop.
+//
+// Stage 2 sub-PR #3 ships only:
+//   - the dispatcher interface (ToolDispatcher)
+//   - DispatcherResult shape (text + isError; matches mcp-client)
+//   - one concrete implementation: `buildMcpDispatcher()` that routes
+//     every call to mcp-registry. Names not in the MCP roster return
+//     an isError result rather than throwing.
+//   - a `combineDispatchers(...)` helper for future stages that want
+//     to layer built-in tools above MCP.
+//
+// Out of scope here (covered by sub-PR #4):
+//   - built-in tool functions (echo / time / web_search) — they're an
+//     orthogonal feature; once the loop is stable, adding them is one
+//     more dispatcher implementation.
+import { callToolByName as callMcpToolByName, getOwningServer as getMcpOwningServer } from './mcp-registry.js';
+/**
+ * Build the default dispatcher: every call name beginning with `mcp_`
+ * is routed to the MCP registry; everything else gets a graceful
+ * "tool unknown" error. The agent loop's job is to surface that error
+ * back to the model so it can choose a different tool or give up.
+ */
+export function buildMcpDispatcher() {
+    return async (call, signal) => {
+        if (!call.name.startsWith('mcp_')) {
+            return {
+                text: `unknown tool "${call.name}" (dispatcher only handles mcp_*; no built-in fallback registered)`,
+                isError: true,
+                source: 'unknown',
+            };
+        }
+        const r = await callMcpToolByName(call.name, call.arguments, { signal });
+        return {
+            text: r.text,
+            isError: r.isError,
+            source: tagFor(call.name),
+        };
+    };
+}
+/**
+ * Stack dispatchers: the first one that returns a non-"unknown" result
+ * wins. Use this in sub-PR #4 to put built-in tools above MCP, so
+ * `echo` / `time` etc. resolve locally and don't accidentally hit a
+ * server's same-named tool.
+ *
+ * Implementation note: we identify "unknown" by checking `source ===
+ * 'unknown'`. Dispatchers signal "I don't handle this" by returning
+ * isError=true with source='unknown'; everything else (including
+ * domain-level tool errors) is considered handled.
+ */
+export function combineDispatchers(...dispatchers) {
+    return async (call, signal) => {
+        let lastUnknown = null;
+        for (const d of dispatchers) {
+            const r = await d(call, signal);
+            if (r.source === 'unknown') {
+                lastUnknown = r;
+                continue;
+            }
+            return r;
+        }
+        // No dispatcher took it. Surface the last "unknown" message; if
+        // somehow nothing returned, synthesise one.
+        return lastUnknown ?? {
+            text: `unknown tool "${call.name}" (no dispatcher handled it)`,
+            isError: true,
+            source: 'unknown',
+        };
+    };
+}
+/** Map a namespaced MCP tool name back to its owning server for the
+ *  audit `source` tag. Falls back to 'mcp:?' if the registry can't
+ *  identify the owner (shouldn't happen for valid calls). */
+function tagFor(callName) {
+    const server = getMcpOwningServer(callName);
+    return server ? `mcp:${server}` : 'mcp:?';
+}
+//# sourceMappingURL=tool-dispatcher.js.map

package/dist/core/llm/tool-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dispatcher.js","sourceRoot":"","sources":["../../../src/core/llm/tool-dispatcher.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,uBAAuB;AACvB,EAAE;AACF,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,sCAAsC;AACtC,EAAE;AACF,gCAAgC;AAChC,gDAAgD;AAChD,kEAAkE;AAClE,sEAAsE;AACtE,qEAAqE;AACrE,8CAA8C;AAC9C,qEAAqE;AACrE,yCAAyC;AACzC,EAAE;AACF,4CAA4C;AAC5C,sEAAsE;AACtE,sEAAsE;AACtE,sCAAsC;AAGtC,OAAO,EAAE,cAAc,IAAI,iBAAiB,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAuB9G;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC5B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,OAAO;gBACL,IAAI,EAAE,iBAAiB,IAAI,CAAC,IAAI,oEAAoE;gBACpG,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,SAAS;aAClB,CAAA;QACH,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC,CAAA;QACxE,OAAO;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;SAC1B,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAG,WAA6B;IACjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;QAC5B,IAAI,WAAW,GAA4B,IAAI,CAAA;QAC/C,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YAC/B,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC3B,WAAW,GAAG,CAAC,CAAA;gBACf,SAAQ;YACV,CAAC;YACD,OAAO,CAAC,CAAA;QACV,CAAC;QACD,gEAAgE;QAChE,4CAA4C;QAC5C,OAAO,WAAW,IAAI;YACpB,IAAI,EAAE,iBAAiB,IAAI,CAAC,IAAI,8BAA8B;YAC9D,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,SAAS;SAClB,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAED;;6DAE6D;AAC7D,SAAS,MAAM,CAAC,QAAgB;IAC9B,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IAC3C,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;AAC3C,CAAC"}

package/dist/core/memory-consolidate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-consolidate.d.ts","sourceRoot":"","sources":["../../src/core/memory-consolidate.ts"],"names":[],"mappings":"AAkMA;;;GAGG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBxF;AAKD,8EAA8E;AAC9E,wBAAgB,uBAAuB,IAAI,IAAI,CAgB9C;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAK7C"}
+{"version":3,"file":"memory-consolidate.d.ts","sourceRoot":"","sources":["../../src/core/memory-consolidate.ts"],"names":[],"mappings":"AAgNA;;;GAGG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBxF;AAKD,8EAA8E;AAC9E,wBAAgB,uBAAuB,IAAI,IAAI,CAgB9C;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAK7C"}

package/dist/core/memory-consolidate.js

@@ -22,6 +22,7 @@ import { logger as rootLogger } from './logger.js';
 import { registry } from './registry.js';
 import { listRecentFacts, upsertPersona, } from './memory.js';
 import { isMemoryEnabled } from './persona.js';
+import { tryIntrospect } from './llm/index.js';
 const log = rootLogger.child({ component: 'memory-consolidate' });
 const MAX_FACTS_PER_USER = 80; // cap input size to keep prompt cheap
 const PERSONA_TARGET_CHARS = 600; // ~300 tokens give or take
@@ -65,7 +66,7 @@ function buildConsolidationPrompt(facts) {
         '- 矛盾事实保留最新的，标"(目前)"',
         '- 优先 category=profile / preference / goal，category=history 仅写最新',
         '- 用清晰的小段落或要点列出，不要散文式叙述',
-        '- 严格 ≤ ' + PERSONA_TARGET_CHARS + ' 字符',
+        `- 严格 ≤ ${PERSONA_TARGET_CHARS} 字符`,
         '- 输出**纯文本摘要，不要 markdown 围栏，不要任何解释**',
         '',
         '事实列表：',
@@ -78,30 +79,44 @@ async function consolidateOneUser(userKey, agentName) {
     const facts = listRecentFacts(userKey, MAX_FACTS_PER_USER);
     if (facts.length === 0)
         return false;
-    const agent = registry.getAgent(agentName);
-    if (!agent) {
-        log.warn({ event: 'memory.consolidate.agent_missing', agentName, userKey });
-        return false;
-    }
     const prompt = buildConsolidationPrompt(facts);
     let raw = '';
-    try {
-        const gen = agent.sendPrompt(`memory-consolidate-${Date.now()}`, prompt, [], {
-            platform: 'memory-consolidate',
-            userId: userKey,
-        });
-        const deadline = Date.now() + PROMPT_TIMEOUT_MS;
-        for await (const chunk of gen) {
-            raw += chunk;
-            if (Date.now() > deadline)
-                break;
-            if (raw.length > PERSONA_TARGET_CHARS * 4)
-                break; // safety cap
-        }
+    // D+ Stage 1: prefer a configured native LLM backend ('cheap' role).
+    // Falls back to the user's recent CLI agent on no-backend or failure
+    // so historical behaviour is preserved when llmBackends is empty.
+    const nativeResult = await tryIntrospect({
+        role: 'cheap',
+        prompt,
+        timeoutMs: PROMPT_TIMEOUT_MS,
+        temperature: 0.2,
+    });
+    if (nativeResult) {
+        raw = nativeResult.text;
     }
-    catch (err) {
-        log.warn({ event: 'memory.consolidate.agent_failed', userKey, agentName, err: String(err) });
-        return false;
+    else {
+        const agent = registry.getAgent(agentName);
+        if (!agent) {
+            log.warn({ event: 'memory.consolidate.agent_missing', agentName, userKey });
+            return false;
+        }
+        try {
+            const gen = agent.sendPrompt(`memory-consolidate-${Date.now()}`, prompt, [], {
+                platform: 'memory-consolidate',
+                userId: userKey,
+            });
+            const deadline = Date.now() + PROMPT_TIMEOUT_MS;
+            for await (const chunk of gen) {
+                raw += chunk;
+                if (Date.now() > deadline)
+                    break;
+                if (raw.length > PERSONA_TARGET_CHARS * 4)
+                    break; // safety cap
+            }
+        }
+        catch (err) {
+            log.warn({ event: 'memory.consolidate.agent_failed', userKey, agentName, err: String(err) });
+            return false;
+        }
     }
     let summary = raw.trim();
     if (!summary)
@@ -112,7 +127,7 @@ async function consolidateOneUser(userKey, agentName) {
         summary = fence[1].trim();
     if (summary.length > PERSONA_TARGET_CHARS * 2) {
         // Hard truncate at 2x target to avoid runaway summaries.
-        summary = summary.slice(0, PERSONA_TARGET_CHARS * 2) + '…';
+        summary = `${summary.slice(0, PERSONA_TARGET_CHARS * 2)}…`;
     }
     const ok = upsertPersona(userKey, summary);
     if (ok) {