comisai 1.0.28 → 1.0.31

package/node_modules/@comis/daemon/dist/rpc/credential-resolver.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pre-write credential validator for agent provider/model patches.
+ *
+ * When a patch sets agents.<id>.provider, verify the API key is resolvable
+ * from one of the sources pi-coding-agent will consult at runtime. Reject
+ * fail-loud with an actionable error if no source resolves.
+ *
+ * Resolution chain (matches pi-coding-agent runtime semantics):
+ *   1. KEYLESS_PROVIDER_TYPES.has(entry.type) — ollama / lm-studio
+ *   2. providers.entries.<provider>.apiKeyName → secretManager.has(...)
+ *   3. pi-ai's getEnvApiKey(provider) — canonical env + OAuth + ADC + AWS
+ *
+ * @module
+ */
+import { getEnvApiKey } from "@mariozechner/pi-ai";
+/**
+ * Provider types that don't need an API key. Mirrors agent's
+ * KEYLESS_PROVIDER_TYPES at model-registry-adapter.ts:60 — extended here to
+ * include lm-studio (the agent-side may also extend in a follow-up; the
+ * tool guide already documents lm-studio as keyless).
+ */
+const KEYLESS_PROVIDER_TYPES = new Set(["ollama", "lm-studio"]);
+export function resolveProviderCredential(targetProvider, deps) {
+    if (!targetProvider || typeof targetProvider !== "string") {
+        return {
+            ok: false,
+            reason: `Invalid provider value: must be a non-empty string (got ${JSON.stringify(targetProvider)})`,
+        };
+    }
+    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, ProviderEntry> read; targetProvider validated above
+    const entry = deps.providerEntries?.[targetProvider];
+    // 1. Keyless types
+    if (entry && KEYLESS_PROVIDER_TYPES.has(entry.type)) {
+        return { ok: true, source: "keyless" };
+    }
+    // 2. Source A: providers.entries with secret-manager-resolvable apiKeyName
+    if (entry?.apiKeyName && deps.secretManager?.has(entry.apiKeyName)) {
+        return { ok: true, source: "providers_entry" };
+    }
+    // 3. Source B: pi-ai canonical env / OAuth / ADC chain
+    if (getEnvApiKey(targetProvider)) {
+        return { ok: true, source: "env_canonical" };
+    }
+    return { ok: false, reason: buildRejectionMessage(targetProvider, entry) };
+}
+function buildRejectionMessage(targetProvider, entry) {
+    const lines = [];
+    lines.push(`Cannot set agent provider to "${targetProvider}": no API key found.`);
+    if (entry?.apiKeyName) {
+        lines.push(`The configured providers.entries.${targetProvider}.apiKeyName is "${entry.apiKeyName}", but that name is not in env.`);
+        lines.push(`Recovery:`);
+        lines.push(`  Run gateway({action:"env_set", env_key:"${entry.apiKeyName}", env_value:"<key>"}) to store the key, then retry this patch.`);
+        lines.push(`  Run gateway({action:"env_list", filter:"${targetProvider.toUpperCase()}*"}) to see what's already configured.`);
+    }
+    else {
+        const canonical = canonicalEnvKeyHint(targetProvider);
+        lines.push(`No providers.entries.${targetProvider} exists, and the canonical env key${canonical ? ` (${canonical})` : ""} is not set.`);
+        lines.push(`Recovery options (pick one):`);
+        lines.push(canonical
+            ? `  (a) Run gateway({action:"env_set", env_key:"${canonical}", env_value:"<key>"}) to store the key, then retry this patch.`
+            : `  (a) Run gateway({action:"env_list", filter:"${targetProvider.toUpperCase()}*"}) to find the env name, then env_set it.`);
+        lines.push(`  (b) Run providers_manage({action:"create", provider_id:"${targetProvider}", config:{apiKeyName:"<KEY_NAME>", models:[{id:"<model_id>"}]}}) referencing an apiKeyName that already exists in env.`);
+        lines.push(`Always run gateway({action:"env_list", filter:"${targetProvider.toUpperCase()}*"}) FIRST to check before asking the user.`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Best-effort hint at the canonical env key name for a provider, for use in
+ * error messages. Returns undefined when pi-ai doesn't have a canonical
+ * mapping (custom providers must use providers.entries).
+ *
+ * Note: this duplicates pi-ai's internal envMap (env-api-keys.js) for
+ * messaging only — not used for resolution. The actual check uses
+ * getEnvApiKey() which always wins. Acceptable to be slightly out-of-sync
+ * with pi-ai upgrades: hint quality only, never load-bearing.
+ */
+function canonicalEnvKeyHint(provider) {
+    const knownMap = {
+        openai: "OPENAI_API_KEY",
+        "azure-openai-responses": "AZURE_OPENAI_API_KEY",
+        google: "GEMINI_API_KEY",
+        groq: "GROQ_API_KEY",
+        cerebras: "CEREBRAS_API_KEY",
+        xai: "XAI_API_KEY",
+        openrouter: "OPENROUTER_API_KEY",
+        "vercel-ai-gateway": "AI_GATEWAY_API_KEY",
+        zai: "ZAI_API_KEY",
+        mistral: "MISTRAL_API_KEY",
+        minimax: "MINIMAX_API_KEY",
+        "minimax-cn": "MINIMAX_CN_API_KEY",
+        huggingface: "HF_TOKEN",
+        opencode: "OPENCODE_API_KEY",
+        "kimi-coding": "KIMI_API_KEY",
+        anthropic: "ANTHROPIC_API_KEY",
+    };
+    // eslint-disable-next-line security/detect-object-injection -- read of static const map indexed by validated provider string
+    return knownMap[provider];
+}

package/node_modules/@comis/daemon/dist/rpc/message-handlers.d.ts

@@ -31,6 +31,11 @@ export interface MessageHandlerDeps {
     onGatewayAttachment?: (channelId: string, marker: string) => void;
     /** Delivery queue for crash-safe persistence */
     deliveryQueue?: import("@comis/core").DeliveryQueuePort;
+    /** Resolves daemon NormalizedMessage.id UUIDs to platform-native message
+     *  ids for delete/edit/react handlers. Optional — when absent, message_id
+     *  passes through unchanged (which fails on Telegram for inbound UUIDs but
+     *  works for native ids returned by message.send). */
+    inboundMessageIdResolver?: import("../wiring/inbound-message-id-resolver.js").InboundMessageIdResolver;
 }
 /**
  * Create message and platform-action RPC handlers.

package/node_modules/@comis/daemon/dist/rpc/message-handlers.js

@@ -14,6 +14,27 @@ import { relative } from "node:path";
 import { deliverToChannel, formatForChannel } from "@comis/channels";
 import { resolveAdapter, authorizeChannelAccess } from "../wiring/daemon-utils.js";
 // ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Translate the agent's `message_id` argument to the platform-native id when
+ * it matches a recently-received inbound message UUID. Returns the original
+ * value when no match (already-native id from message.send, expired UUID,
+ * cross-channel mismatch). Always returns a string.
+ */
+function resolveMessageId(resolver, messageId, channelType, channelId) {
+    if (!resolver)
+        return messageId;
+    const record = resolver.resolve(messageId);
+    if (!record)
+        return messageId;
+    if (record.channelType !== channelType)
+        return messageId;
+    if (record.channelId !== channelId)
+        return messageId;
+    return record.nativeId;
+}
+// ---------------------------------------------------------------------------
 // Capability guard — maps RPC methods to ChannelCapability feature flags.
 // When channelPlugins is provided, unsupported actions are rejected before
 // reaching the adapter, saving a tool call and producing a clear error.
@@ -79,7 +100,7 @@ export function createMessageHandlers(deps) {
             const channelType = params.channel_type;
             const channelId = params.channel_id;
             const text = params.text;
-            const messageId = params.message_id;
+            const messageId = resolveMessageId(deps.inboundMessageIdResolver, params.message_id, channelType, channelId);
             authorizeChannelAccess(params._originChannelId, channelId, params._trustLevel);
             const adapter = resolveAdapter(channelType, deps.adaptersByType);
             const extra = {
@@ -103,7 +124,7 @@ export function createMessageHandlers(deps) {
             const channelType = params.channel_type;
             assertCapability("message.react", channelType, deps.channelPlugins);
             const channelId = params.channel_id;
-            const messageId = params.message_id;
+            const messageId = resolveMessageId(deps.inboundMessageIdResolver, params.message_id, channelType, channelId);
             const emoji = params.emoji;
             authorizeChannelAccess(params._originChannelId, channelId, params._trustLevel);
             const adapter = resolveAdapter(channelType, deps.adaptersByType);
@@ -118,7 +139,7 @@ export function createMessageHandlers(deps) {
             const channelType = params.channel_type;
             assertCapability("message.edit", channelType, deps.channelPlugins);
             const channelId = params.channel_id;
-            const messageId = params.message_id;
+            const messageId = resolveMessageId(deps.inboundMessageIdResolver, params.message_id, channelType, channelId);
             const text = params.text;
             authorizeChannelAccess(params._originChannelId, channelId, params._trustLevel);
             const adapter = resolveAdapter(channelType, deps.adaptersByType);
@@ -132,7 +153,7 @@ export function createMessageHandlers(deps) {
             const channelType = params.channel_type;
             assertCapability("message.delete", channelType, deps.channelPlugins);
             const channelId = params.channel_id;
-            const messageId = params.message_id;
+            const messageId = resolveMessageId(deps.inboundMessageIdResolver, params.message_id, channelType, channelId);
             authorizeChannelAccess(params._originChannelId, channelId, params._trustLevel);
             const adapter = resolveAdapter(channelType, deps.adaptersByType);
             const result = await adapter.deleteMessage(channelId, messageId);

package/node_modules/@comis/daemon/dist/rpc/model-handlers.d.ts

@@ -1,9 +1,10 @@
 /**
  * Model management RPC handler module.
  * Handles model catalog query methods:
- *   models.list -- List available models (optionally filtered by provider)
- *   models.test -- Check provider configuration and catalog status
- * Both handlers are read-only -- no approval gate required.
+ *   models.list           -- List available models (optionally filtered by provider)
+ *   models.test           -- Check provider configuration and catalog status
+ *   models.list_providers -- Live native pi-ai catalog provider list (Layer 1F)
+ * All handlers are read-only -- no approval gate required.
  * @module
  */
 import type { ModelCatalog } from "@comis/agent";

package/node_modules/@comis/daemon/dist/rpc/model-handlers.js

@@ -2,11 +2,13 @@
 /**
  * Model management RPC handler module.
  * Handles model catalog query methods:
- *   models.list -- List available models (optionally filtered by provider)
- *   models.test -- Check provider configuration and catalog status
- * Both handlers are read-only -- no approval gate required.
+ *   models.list           -- List available models (optionally filtered by provider)
+ *   models.test           -- Check provider configuration and catalog status
+ *   models.list_providers -- Live native pi-ai catalog provider list (Layer 1F)
+ * All handlers are read-only -- no approval gate required.
  * @module
  */
+import { getProviders } from "@mariozechner/pi-ai";
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -62,6 +64,22 @@ export function createModelHandlers(deps) {
             };
         },
         // -----------------------------------------------------------------------
+        // List native pi-ai catalog providers (Layer 1F -- 260430-vwt)
+        //
+        // Live self-discovery for the agent: returns the de-duplicated, sorted
+        // list of provider names from the pi-ai native catalog. Pairs with the
+        // tool-descriptions auto-promote guidance so the agent can verify
+        // which provider_id values trigger promotion in providers.create.
+        // -----------------------------------------------------------------------
+        "models.list_providers": async (params) => {
+            const trustLevel = params._trustLevel;
+            if (trustLevel !== "admin") {
+                throw new Error("Admin access required");
+            }
+            const providers = [...new Set(getProviders())].sort();
+            return { providers, count: providers.length };
+        },
+        // -----------------------------------------------------------------------
         // Test provider configuration and availability
         // -----------------------------------------------------------------------
         "models.test": async (params) => {

package/node_modules/@comis/daemon/dist/rpc/provider-handlers.js

@@ -16,6 +16,8 @@
  * @module
  */
 import { ProviderEntrySchema } from "@comis/core";
+import { getModels, getProviders } from "@mariozechner/pi-ai";
+import { checkBuiltInProviderRedundancy } from "./builtin-provider-guard.js";
 import { persistToConfig } from "./persist-to-config.js";
 import { probeProviderAuth } from "./probe-provider-auth.js";
 // ---------------------------------------------------------------------------
@@ -68,6 +70,48 @@ function formatReferenceMessage(refs) {
     }
     return parts.join("; ");
 }
+/**
+ * Auto-promote a Partial<ProviderEntry> when the `providerId` matches a
+ * native pi-ai catalog entry AND the user has not expressed clear intent
+ * to deviate from the native shape.
+ *
+ * The agent's tool guide currently shows `type:"openai"` as the example
+ * for any OpenAI-compatible provider. Without promotion, registering
+ * "openrouter" by name with that example shape lands a `type:"openai"`
+ * entry that bypasses the OpenRouter native catalog (no costs, wrong
+ * context window, single explicit model).
+ *
+ * Promotion fires when:
+ *   1. providerId is in the live pi-ai native catalog, AND
+ *   2. config.type is missing or set to "openai" (the passthrough sentinel), AND
+ *   3. config.baseUrl is missing or matches the native catalog's baseUrl.
+ *
+ * Conservatism: a user pointing at a custom proxy whose URL differs from
+ * the native one keeps their explicit `type:"openai"` shape -- the URL
+ * mismatch is the opt-out signal.
+ *
+ * Logged at INFO with the original_type / promoted_type so operators can
+ * see which entries were rewritten on the way in.
+ */
+function normalizeProviderEntry(providerId, config, logger) {
+    const native = new Set(getProviders());
+    if (!native.has(providerId))
+        return config;
+    const catalog = getModels(providerId);
+    const nativeBaseUrl = catalog[0]?.baseUrl;
+    const isPassthroughType = !config.type || config.type === "openai";
+    const userBaseUrlMatchesNative = !config.baseUrl || config.baseUrl === nativeBaseUrl;
+    if (isPassthroughType && userBaseUrlMatchesNative) {
+        logger?.info({
+            providerId,
+            original_type: config.type,
+            promoted_type: providerId,
+            hint: "Auto-promoted to native pi-ai catalog provider",
+        }, "providers.create: type promoted to native");
+        return { ...config, type: providerId };
+    }
+    return config;
+}
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -152,7 +196,22 @@ export function createProviderHandlers(deps) {
                 throw new Error(`Provider already exists: ${providerId}`);
             }
             const config = params.config ?? {};
-            const parsedConfig = ProviderEntrySchema.parse(config);
+            // 260501-gyy: reject redundant catalog-shadowing entries before
+            // promotion / probe / persist. A built-in provider with a catalog
+            // (or absent) baseUrl is structurally redundant -- pi-ai's dynamic
+            // catalog already provides its model list. Production trace
+            // 2026-05-01 08:53 showed an LLM agent creating
+            // providers.entries.openrouter with an invented model id, leading
+            // to a downstream 404.
+            const guardResult = checkBuiltInProviderRedundancy(providerId, config);
+            if (!guardResult.ok) {
+                throw new Error(guardResult.reason);
+            }
+            // Layer 1C (260430-vwt): auto-promote type to native catalog name
+            // when the providerId matches a pi-ai catalog entry AND the user has
+            // not opted out via a custom baseUrl.
+            const normalizedConfig = normalizeProviderEntry(providerId, config, deps.persistDeps?.logger);
+            const parsedConfig = ProviderEntrySchema.parse(normalizedConfig);
             // Probe provider API key before committing config
             if (parsedConfig.apiKeyName && deps.secretManager) {
                 const apiKey = deps.secretManager.get(parsedConfig.apiKeyName);
@@ -164,11 +223,15 @@ export function createProviderHandlers(deps) {
                 }
             }
             deps.providerEntries[providerId] = parsedConfig;
-            // Best-effort persistence to config.yaml
+            // Best-effort persistence to config.yaml. Persist the normalized
+            // config (post-Layer-1C promotion) so the YAML reflects the
+            // promoted type -- otherwise the daemon would re-promote on every
+            // restart, or worse, the persisted type:"openai" would override the
+            // runtime promoted type on subsequent loads.
             if (deps.persistDeps) {
                 const ctx = params._context;
                 const persistResult = await persistToConfig(deps.persistDeps, {
-                    patch: { providers: { entries: { [providerId]: config } } },
+                    patch: { providers: { entries: { [providerId]: normalizedConfig } } },
                     actionType: "providers.create",
                     entityId: providerId,
                     actingUser: ctx?.userId ?? params._agentId,
@@ -197,12 +260,25 @@ export function createProviderHandlers(deps) {
             // Capture user-provided fields BEFORE merge -- persistToConfig does deepMerge internally,
             // so we only persist the user's partial patch (not the fully merged config).
             const userPatch = params.config ? structuredClone(params.config) : {};
+            // Layer 1C (260430-vwt): on update, only auto-promote when the user
+            // is actively changing the `type` field. If `type` is absent from
+            // the patch, the user is editing other fields and we must not
+            // rewrite their existing type silently.
+            let normalizedPatch = config;
+            if (config.type !== undefined) {
+                normalizedPatch = normalizeProviderEntry(providerId, config, deps.persistDeps?.logger);
+                // Mirror the promotion into both the in-memory merge and the persisted patch
+                // so the YAML matches the runtime view.
+                if (normalizedPatch.type !== config.type) {
+                    userPatch.type = normalizedPatch.type;
+                }
+            }
             // Headers: shallow merge per-key (preserve existing keys, overlay new ones)
-            if (config.headers && existing.headers) {
-                config.headers = { ...existing.headers, ...config.headers };
+            if (normalizedPatch.headers && existing.headers) {
+                normalizedPatch.headers = { ...existing.headers, ...normalizedPatch.headers };
             }
             // models[] and capabilities: replaced wholesale via spread (no merge needed)
-            const merged = { ...existing, ...config };
+            const merged = { ...existing, ...normalizedPatch };
             const parsedConfig = ProviderEntrySchema.parse(merged);
             deps.providerEntries[providerId] = parsedConfig;
             // Best-effort persistence to config.yaml -- persist userPatch NOT merged config

package/node_modules/@comis/daemon/dist/rpc/rpc-dispatch.d.ts

@@ -77,6 +77,10 @@ export interface RpcDispatchDeps {
         };
     };
     adaptersByType: Map<string, ChannelPort>;
+    /** Resolves daemon NormalizedMessage.id UUIDs back to platform-native
+     *  message ids for message.delete/edit/react. Optional for backward compat
+     *  with daemon configs that disable channel adapters entirely. */
+    inboundMessageIdResolver?: import("../wiring/inbound-message-id-resolver.js").InboundMessageIdResolver;
     visionRegistry?: Map<string, VisionProvider>;
     mediaConfig: {
         imageAnalysis: {

package/node_modules/@comis/daemon/dist/wiring/inbound-message-id-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolves daemon-internal `NormalizedMessage.id` UUIDs to platform-native
+ * message ids (e.g. Telegram's integer `message_id`) for inbound messages.
+ *
+ * The agent's tools see `message_id` as the daemon UUID (from session
+ * preamble metadata), but channel adapters need the platform-native id when
+ * calling APIs like `bot.api.deleteMessage`. Without translation, those calls
+ * fail with `400: Bad Request: message identifier is not specified` (Telegram
+ * rejects `Number("e60f9634-...")` → `NaN`).
+ *
+ * Populated lazily on inbound via `record(msg, channelType)`. The native id
+ * is read from `msg.metadata[metaKey]` where metaKey comes from the
+ * per-channel `replyToMetaKey` capability. Backed by a TTL cache so stale
+ * entries don't accumulate.
+ *
+ * @module
+ */
+import type { NormalizedMessage } from "@comis/core";
+/** A single resolved inbound message record. */
+export interface InboundIdRecord {
+    channelType: string;
+    channelId: string;
+    nativeId: string;
+}
+/** UUID → native message-id resolver for cross-channel inbound messages. */
+export interface InboundMessageIdResolver {
+    /** Record an inbound message's UUID → native id mapping. No-op if the
+     *  channel has no registered metadata key or the metadata is missing. */
+    record(msg: NormalizedMessage, channelType: string): void;
+    /** Look up native id by daemon UUID. Returns undefined if not found. */
+    resolve(uuid: string): InboundIdRecord | undefined;
+}
+/** Options for the resolver factory. */
+export interface InboundMessageIdResolverOpts {
+    /** Per-channel metadata key carrying the native id, e.g. {"telegram": "telegramMessageId"}. */
+    metaKeyByChannel: Map<string, string>;
+    /** Time-to-live in ms for cached entries. Defaults to 1 h. */
+    ttlMs?: number;
+    /** Max entries before LRU eviction. Defaults to 10_000. */
+    maxEntries?: number;
+}
+/**
+ * Create an inbound-message-id resolver backed by a TTL cache.
+ *
+ * @param opts Configuration including the per-channel metadata key map.
+ * @returns A resolver that records on inbound and resolves UUIDs on lookup.
+ */
+export declare function createInboundMessageIdResolver(opts: InboundMessageIdResolverOpts): InboundMessageIdResolver;

package/node_modules/@comis/daemon/dist/wiring/inbound-message-id-resolver.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Resolves daemon-internal `NormalizedMessage.id` UUIDs to platform-native
+ * message ids (e.g. Telegram's integer `message_id`) for inbound messages.
+ *
+ * The agent's tools see `message_id` as the daemon UUID (from session
+ * preamble metadata), but channel adapters need the platform-native id when
+ * calling APIs like `bot.api.deleteMessage`. Without translation, those calls
+ * fail with `400: Bad Request: message identifier is not specified` (Telegram
+ * rejects `Number("e60f9634-...")` → `NaN`).
+ *
+ * Populated lazily on inbound via `record(msg, channelType)`. The native id
+ * is read from `msg.metadata[metaKey]` where metaKey comes from the
+ * per-channel `replyToMetaKey` capability. Backed by a TTL cache so stale
+ * entries don't accumulate.
+ *
+ * @module
+ */
+import { createTTLCache } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an inbound-message-id resolver backed by a TTL cache.
+ *
+ * @param opts Configuration including the per-channel metadata key map.
+ * @returns A resolver that records on inbound and resolves UUIDs on lookup.
+ */
+export function createInboundMessageIdResolver(opts) {
+    const ttlMs = opts.ttlMs ?? 60 * 60 * 1000;
+    const maxEntries = opts.maxEntries ?? 10_000;
+    const cache = createTTLCache({ ttlMs, maxEntries });
+    return {
+        record(msg, channelType) {
+            const metaKey = opts.metaKeyByChannel.get(channelType);
+            if (!metaKey)
+                return;
+            const meta = msg.metadata;
+            // metaKey comes from our internal channelCapabilities map (set at adapter
+            // bootstrap, not user-controlled), so dynamic access is safe.
+            // eslint-disable-next-line security/detect-object-injection
+            const raw = meta?.[metaKey];
+            if (raw == null)
+                return;
+            const nativeId = typeof raw === "number"
+                ? String(raw)
+                : typeof raw === "string"
+                    ? raw
+                    : null;
+            if (nativeId == null || nativeId.length === 0)
+                return;
+            cache.set(msg.id, { channelType, channelId: msg.channelId, nativeId });
+        },
+        resolve(uuid) {
+            return cache.get(uuid);
+        },
+    };
+}

package/node_modules/@comis/daemon/dist/wiring/setup-agents.d.ts

@@ -164,12 +164,24 @@ export declare function setupAgents(deps: {
     backgroundNotifyFn?: import("@comis/agent").NotifyFn;
 }): Promise<AgentsResult>;
 /**
- * Resolve "default" model/provider placeholders to global defaults.
- * Called once per agent at daemon startup so executors always receive concrete values.
- * Resolution order for model:
- *   1. modelsConfig.defaultModel (from YAML models.defaultModel)
- *   2. DEFAULT_MODEL_PER_PROVIDER[resolvedProvider]
- *   3. DEFAULT_MODEL_PER_PROVIDER["anthropic"] (ultimate fallback)
+ * Resolve "default" model/provider placeholders to concrete values from the
+ * pi-ai catalog. Called once per agent at daemon startup so executors always
+ * receive concrete values.
+ *
+ * Resolution sources, in priority order:
+ *   1. Per-agent explicit value (agentConfig.model / .provider not "default")
+ *   2. YAML models.defaultModel / models.defaultProvider (operator override)
+ *   3. Catalog heuristic for provider: most-populated native pi-ai provider
+ *      (e.g. openrouter at 249 models > anthropic at 23). Single source of
+ *      truth — no env var, no hardcoded FALLBACK_PROVIDER. If users want
+ *      a specific default, they set models.defaultProvider in YAML.
+ *   4. Catalog heuristic for model: resolveOperationDefaults(provider).mid
+ *      (mid-tier cost), falling back to getModels(provider)[0].id.
+ *
+ * Throws when the pi-ai catalog is empty (zero providers / zero models for
+ * the resolved provider) — the caller is asking for a default and we can't
+ * synthesize one. Operators can recover by setting models.defaultProvider /
+ * models.defaultModel explicitly.
  */
 export declare function resolveAgentModel(agentConfig: {
     model: string;