comisai 1.0.25 → 1.0.27

package/node_modules/@comis/agent/dist/executor/post-batch-continuation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Post-batch continuation handler (L4 silent-termination recovery).
+ *
+ * When the LLM emits an empty final assistant turn (zero text + zero thinking +
+ * zero tool calls) following a successful tool batch within the same execution
+ * window, this handler fires a directive `session.followUp()` with multi-shot
+ * retry. Replaces the legacy SEP one-shot `generateCompletenessNudge` (whose
+ * enforcement role is now superseded; SEP plan extraction + step counting
+ * remain intact for observability).
+ *
+ * @module
+ */
+import { type Result } from "@comis/shared";
+import type { ComisLogger } from "@comis/infra";
+/** Configuration for the post-batch continuation handler. */
+export interface ContinuationConfig {
+    /** Master toggle. When false, handler returns
+     *  `{recovered: false, outcome: "disabled"}` without calling followUp. */
+    enabled: boolean;
+    /** Maximum directive followUp attempts before falling through to L3
+     *  synthesis. Range 0..5; 0 is treated as disabled. */
+    maxRetries: number;
+}
+/** Outcome returned by the handler. */
+export interface ContinuationOutcome {
+    recovered: boolean;
+    /** Recovered visible text from the followed-up assistant turn (only set
+     *  when `recovered === true`). */
+    response?: string;
+    /** Number of followUp attempts actually made (0 when handler did not fire). */
+    attempts: number;
+    /** Terminal outcome:
+     *  - `recovered`           — followUp produced visible text on some attempt
+     *  - `still_empty`         — followUp ran but produced no visible text
+     *                           (single-attempt diagnostic; not a terminal flag)
+     *  - `max_attempts_exhausted` — all `maxRetries` attempts produced empty
+     *  - `disabled`            — config.enabled = false OR maxRetries = 0
+     *  - `no_match`            — empty-after-tool-batch pattern not detected */
+    outcome: "recovered" | "still_empty" | "max_attempts_exhausted" | "disabled" | "no_match";
+    priorToolCallCount: number;
+    priorToolNames: string[];
+}
+/** Error variant — only ever returned when `session.followUp` rejects. */
+export type ContinuationError = {
+    kind: "followup_error";
+    cause: unknown;
+};
+/** Dependencies passed in by the executor wire-in site. */
+export interface RunPostBatchContinuationDeps {
+    /** Live session — invoked via `followUp(text)` to issue the directive. */
+    session: {
+        followUp(text: string): Promise<unknown>;
+        messages?: unknown[];
+    };
+    /** Session messages — passed explicitly per the canonical
+     *  `(session as any).messages ?? []` pattern at executor-prompt-runner.ts:797. */
+    messages: unknown[];
+    config: ContinuationConfig;
+    logger: ComisLogger;
+    agentId?: string;
+    /** Read visible text from the latest assistant turn (post-followUp). */
+    getVisibleAssistantText: (session: any) => string;
+}
+/**
+ * Run the post-batch continuation handler. Returns a `Result` so callers can
+ * distinguish a clean outcome (any `ContinuationOutcome.outcome` value) from
+ * a true error (followUp rejected).
+ *
+ * Detection (pure inspection, no throw):
+ *   1. Walk `messages` to find the most recent user-role index (lower bound).
+ *   2. The last message must be assistant with NO visible text, NO thinking
+ *      blocks, and NO tool_use/toolCall blocks.
+ *   3. Within `[lowerBound, messages.length)`, count assistant turns whose
+ *      content includes tool_use/toolCall blocks; collect tool names where
+ *      `block.name` is a string.
+ *   4. Fire when (2) AND (≥1 tool call from step 3); else `no_match`.
+ *
+ * `session.followUp` errors are caught and propagated as
+ * `Result<_, ContinuationError>` per AGENTS.md §2.1 + the
+ * `executor-prompt-runner.ts:931` precedent.
+ */
+export declare function runPostBatchContinuation(deps: RunPostBatchContinuationDeps): Promise<Result<ContinuationOutcome, ContinuationError>>;

package/node_modules/@comis/agent/dist/executor/post-batch-continuation.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Post-batch continuation handler (L4 silent-termination recovery).
+ *
+ * When the LLM emits an empty final assistant turn (zero text + zero thinking +
+ * zero tool calls) following a successful tool batch within the same execution
+ * window, this handler fires a directive `session.followUp()` with multi-shot
+ * retry. Replaces the legacy SEP one-shot `generateCompletenessNudge` (whose
+ * enforcement role is now superseded; SEP plan extraction + step counting
+ * remain intact for observability).
+ *
+ * @module
+ */
+import { fromPromise, ok, err } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const MODULE = "agent.executor.post-batch-continuation";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function isToolCallBlock(block) {
+    return block?.type === "toolCall" || block?.type === "tool_use";
+}
+function isThinkingBlock(block) {
+    return block?.type === "thinking";
+}
+function hasVisibleTextBlock(content) {
+    if (!Array.isArray(content))
+        return false;
+    for (const block of content) {
+        if (block?.type === "text" &&
+            typeof block.text === "string" &&
+            block.text.trim().length > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasThinkingBlock(content) {
+    if (!Array.isArray(content))
+        return false;
+    return content.some(isThinkingBlock);
+}
+function hasToolCallBlock(content) {
+    if (!Array.isArray(content))
+        return false;
+    return content.some(isToolCallBlock);
+}
+function findLastUserIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === "user")
+            return i; // eslint-disable-line security/detect-object-injection
+    }
+    return 0;
+}
+function buildDirective(priorToolCallCount, priorToolNames) {
+    const toolList = priorToolNames.join(", ");
+    return (`[comis: post-batch continuation — your last turn was empty after ${priorToolCallCount} successful tool calls]\n` +
+        `You completed ${priorToolCallCount} tool calls (toolNames: [${toolList}]). Your previous turn produced no text, thinking, or new tool calls. The conversation is incomplete.\n\n` +
+        `You MUST either:\n` +
+        `  (a) Provide a brief summary of what you accomplished AND continue with the next step from your plan, OR\n` +
+        `  (b) Explicitly state "task complete" with reasoning for stopping (e.g., "All N agents created and ROLE.md customized — the user can now use them").\n\n` +
+        `Do NOT emit empty turns. If you have nothing else to do, say so explicitly.`);
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/**
+ * Run the post-batch continuation handler. Returns a `Result` so callers can
+ * distinguish a clean outcome (any `ContinuationOutcome.outcome` value) from
+ * a true error (followUp rejected).
+ *
+ * Detection (pure inspection, no throw):
+ *   1. Walk `messages` to find the most recent user-role index (lower bound).
+ *   2. The last message must be assistant with NO visible text, NO thinking
+ *      blocks, and NO tool_use/toolCall blocks.
+ *   3. Within `[lowerBound, messages.length)`, count assistant turns whose
+ *      content includes tool_use/toolCall blocks; collect tool names where
+ *      `block.name` is a string.
+ *   4. Fire when (2) AND (≥1 tool call from step 3); else `no_match`.
+ *
+ * `session.followUp` errors are caught and propagated as
+ * `Result<_, ContinuationError>` per AGENTS.md §2.1 + the
+ * `executor-prompt-runner.ts:931` precedent.
+ */
+export async function runPostBatchContinuation(deps) {
+    const { session, messages, config, logger, agentId, getVisibleAssistantText } = deps;
+    // Step 1: disable check.
+    if (!config.enabled || config.maxRetries === 0) {
+        logger.info({ module: MODULE, agentId, decision: "skip", reason: "disabled" }, "Post-batch continuation skipped");
+        return ok({
+            recovered: false,
+            attempts: 0,
+            outcome: "disabled",
+            priorToolCallCount: 0,
+            priorToolNames: [],
+        });
+    }
+    // Step 2: detection — last message must be empty assistant turn.
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    const msgs = messages;
+    if (!Array.isArray(msgs) || msgs.length === 0) {
+        logger.info({ module: MODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
+        return ok({
+            recovered: false,
+            attempts: 0,
+            outcome: "no_match",
+            priorToolCallCount: 0,
+            priorToolNames: [],
+        });
+    }
+    const last = msgs[msgs.length - 1];
+    const lastIsAssistant = last?.role === "assistant";
+    const lastIsEmpty = lastIsAssistant &&
+        !hasVisibleTextBlock(last.content) &&
+        !hasThinkingBlock(last.content) &&
+        !hasToolCallBlock(last.content);
+    if (!lastIsEmpty) {
+        logger.info({ module: MODULE, agentId, decision: "skip", reason: "non_empty_final" }, "Post-batch continuation skipped");
+        return ok({
+            recovered: false,
+            attempts: 0,
+            outcome: "no_match",
+            priorToolCallCount: 0,
+            priorToolNames: [],
+        });
+    }
+    // Step 3: collect tool calls within the current execution window.
+    const lowerBound = findLastUserIndex(msgs);
+    let priorToolCallCount = 0;
+    const priorToolNamesSet = new Set();
+    for (let i = lowerBound; i < msgs.length; i++) {
+        const m = msgs[i]; // eslint-disable-line security/detect-object-injection
+        if (m?.role !== "assistant" || !Array.isArray(m.content))
+            continue;
+        for (const block of m.content) {
+            if (isToolCallBlock(block)) {
+                priorToolCallCount++;
+                if (typeof block?.name === "string")
+                    priorToolNamesSet.add(block.name);
+            }
+        }
+    }
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+    const priorToolNames = [...priorToolNamesSet];
+    if (priorToolCallCount === 0) {
+        logger.info({ module: MODULE, agentId, decision: "skip", reason: "no_tool_calls" }, "Post-batch continuation skipped");
+        return ok({
+            recovered: false,
+            attempts: 0,
+            outcome: "no_match",
+            priorToolCallCount: 0,
+            priorToolNames: [],
+        });
+    }
+    // Step 4: decision-log fire.
+    logger.info({
+        module: MODULE,
+        agentId,
+        decision: "fire",
+        reason: "empty_after_tool_batch",
+        priorToolCallCount,
+        priorToolNames,
+        maxAttempts: config.maxRetries,
+    }, "Post-batch continuation firing");
+    // Step 5: directive multi-shot retry loop.
+    const directive = buildDirective(priorToolCallCount, priorToolNames);
+    for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+        const followUpResult = await fromPromise(session.followUp(directive));
+        if (!followUpResult.ok) {
+            return err({ kind: "followup_error", cause: followUpResult.error });
+        }
+        const text = getVisibleAssistantText(session);
+        const outcomeForLog = text && text.length > 0 ? "recovered" : "still_empty";
+        logger.info({
+            module: MODULE,
+            agentId,
+            attempt,
+            maxAttempts: config.maxRetries,
+            priorToolCallCount,
+            priorToolNames,
+            outcome: outcomeForLog,
+        }, "Post-batch continuation attempt");
+        if (text && text.length > 0) {
+            return ok({
+                recovered: true,
+                response: text,
+                attempts: attempt,
+                outcome: "recovered",
+                priorToolCallCount,
+                priorToolNames,
+            });
+        }
+    }
+    // Step 6: max retries exhausted.
+    return ok({
+        recovered: false,
+        attempts: config.maxRetries,
+        outcome: "max_attempts_exhausted",
+        priorToolCallCount,
+        priorToolNames,
+    });
+}

package/node_modules/@comis/agent/dist/executor/stream-wrappers/request-body-injector.js

@@ -17,6 +17,7 @@ import { createAccumulativeLatch } from "../session-latch.js";
 import { MIN_CACHEABLE_TOKENS, DEFAULT_MIN_CACHEABLE_TOKENS, CHARS_PER_TOKEN_RATIO, CHARS_PER_TOKEN_RATIO_STRUCTURED, CACHE_LOOKBACK_WINDOW } from "../../context-engine/index.js";
 import { estimateContextChars } from "../../safety/token-estimator.js";
 import { computeHash, djb2 } from "../cache-break-detection.js";
+import { supportsToolSearch } from "../tool-deferral.js";
 // ---------------------------------------------------------------------------
 // Tool schema caches extracted to tool-schema-cache.ts (leaf module).
 // Re-exported here for backward compatibility with existing consumers.
@@ -208,15 +209,6 @@ export function addCacheControlToLastBlock(message, retention) {
     // Edge case: no cacheable block found -- place on last block as fallback
     content[content.length - 1].cache_control = cacheControl;
 }
-/** DEFER-TOOL: Check if a model supports Anthropic's tool search (defer_loading).
- *  Supported: Sonnet 4.x+, Opus 4.x+. NOT supported: Haiku. */
-function supportsToolSearch(modelId) {
-    const lower = modelId.toLowerCase();
-    if (lower.includes("haiku"))
-        return false;
-    // Sonnet 4.x and Opus 4.x support tool search
-    return lower.includes("sonnet") || lower.includes("opus");
-}
 /**
  * Place exactly 1 cache_control marker on the second-to-last user message.
  * The SDK already places one on the last user message, so we target second-to-last

package/node_modules/@comis/agent/dist/executor/tool-deferral.d.ts

@@ -100,6 +100,20 @@ export declare function resolveModelTier(contextWindow: number): ModelTier;
  * Small models benefit from deterministic tool selection (0.0).
  */
 export declare function resolveToolCallingTemperature(modelTier: ModelTier): number;
+/**
+ * Anthropic models that support server-side tool_search_tool_regex
+ * (defer_loading). Sonnet 4.x+, Opus 4.x+; NOT Haiku.
+ *
+ * When this returns true, request-body-injector strips client-side
+ * `discover_tools` from the API payload and appends `tool_search_tool_regex`
+ * instead -- so any model-facing teaching string about `discover_tools`
+ * contradicts the actual tool list and must be suppressed (260428-oyc).
+ *
+ * Lowercase-normalize so provider-prefixed model ids
+ * (`anthropic/claude-sonnet-4`, `bedrock/anthropic.claude-opus-4`) resolve
+ * correctly.
+ */
+export declare function supportsToolSearch(modelId: string): boolean;
 /**
  * Extract recently-used tool names from session history messages.
  * Looks at the most recent N assistant messages for tool_use blocks.
@@ -119,12 +133,33 @@ export declare function resolveToolDescription(tool: ToolDefinition): string;
 /**
  * Build a `<deferred-tools>` XML block for dynamic preamble injection.
  * Lists deferred tool names and descriptions so the LLM knows what's
- * available behind discover_tools.
+ * available behind a discovery mechanism.
+ *
+ * The third line (the instruction line) is conditional on `useToolSearch`:
+ *
+ * - `useToolSearch=false` (default, every non-Anthropic provider + Haiku):
+ *   teaches the model to call the client-side `discover_tools` tool, which
+ *   IS present in those payloads.
+ *
+ * - `useToolSearch=true` (Anthropic Sonnet/Opus 4.x): the API payload no
+ *   longer contains a client-side `discover_tools` tool -- the
+ *   request-body-injector replaces it with the server-side
+ *   `tool_search_tool_regex` and marks deferred tools `defer_loading: true`,
+ *   meaning Anthropic auto-loads them on first direct invocation. The
+ *   teaching string therefore points at direct invocation + tool-search by
+ *   regex, never at `discover_tools`. Without this conditional, the model
+ *   reads its own preamble ("call discover_tools") against a tool list that
+ *   doesn't contain that tool and gives up (260428-oyc production repro).
  *
  * @param entries - Deferred tool entries (remaining after discovery re-inclusion)
+ * @param options - Optional flags. `useToolSearch=true` switches the third
+ *   line to the tool-search-aware variant. Defaults to false (backward-
+ *   compatible with the discover_tools teaching).
  * @returns XML block string, or empty string when no entries
  */
-export declare function buildDeferredToolsContext(entries: DeferredToolEntry[]): string;
+export declare function buildDeferredToolsContext(entries: DeferredToolEntry[], options?: {
+    useToolSearch?: boolean;
+}): string;
 /**
  * Apply unified tool deferral: rule-based, budget-based, small-model,
  * lifecycle merge, and operator overrides.

package/node_modules/@comis/agent/dist/executor/tool-deferral.js

@@ -95,6 +95,25 @@ export function resolveModelTier(contextWindow) {
 export function resolveToolCallingTemperature(modelTier) {
     return modelTier === "small" ? 0.0 : 0.1;
 }
+/**
+ * Anthropic models that support server-side tool_search_tool_regex
+ * (defer_loading). Sonnet 4.x+, Opus 4.x+; NOT Haiku.
+ *
+ * When this returns true, request-body-injector strips client-side
+ * `discover_tools` from the API payload and appends `tool_search_tool_regex`
+ * instead -- so any model-facing teaching string about `discover_tools`
+ * contradicts the actual tool list and must be suppressed (260428-oyc).
+ *
+ * Lowercase-normalize so provider-prefixed model ids
+ * (`anthropic/claude-sonnet-4`, `bedrock/anthropic.claude-opus-4`) resolve
+ * correctly.
+ */
+export function supportsToolSearch(modelId) {
+    const lower = modelId.toLowerCase();
+    if (lower.includes("haiku"))
+        return false;
+    return lower.includes("sonnet") || lower.includes("opus");
+}
 // ---------------------------------------------------------------------------
 // Recently-used tool extraction
 // ---------------------------------------------------------------------------
@@ -148,14 +167,34 @@ export function resolveToolDescription(tool) {
 /**
  * Build a `<deferred-tools>` XML block for dynamic preamble injection.
  * Lists deferred tool names and descriptions so the LLM knows what's
- * available behind discover_tools.
+ * available behind a discovery mechanism.
+ *
+ * The third line (the instruction line) is conditional on `useToolSearch`:
+ *
+ * - `useToolSearch=false` (default, every non-Anthropic provider + Haiku):
+ *   teaches the model to call the client-side `discover_tools` tool, which
+ *   IS present in those payloads.
+ *
+ * - `useToolSearch=true` (Anthropic Sonnet/Opus 4.x): the API payload no
+ *   longer contains a client-side `discover_tools` tool -- the
+ *   request-body-injector replaces it with the server-side
+ *   `tool_search_tool_regex` and marks deferred tools `defer_loading: true`,
+ *   meaning Anthropic auto-loads them on first direct invocation. The
+ *   teaching string therefore points at direct invocation + tool-search by
+ *   regex, never at `discover_tools`. Without this conditional, the model
+ *   reads its own preamble ("call discover_tools") against a tool list that
+ *   doesn't contain that tool and gives up (260428-oyc production repro).
  *
  * @param entries - Deferred tool entries (remaining after discovery re-inclusion)
+ * @param options - Optional flags. `useToolSearch=true` switches the third
+ *   line to the tool-search-aware variant. Defaults to false (backward-
+ *   compatible with the discover_tools teaching).
  * @returns XML block string, or empty string when no entries
  */
-export function buildDeferredToolsContext(entries) {
+export function buildDeferredToolsContext(entries, options) {
     if (entries.length === 0)
         return "";
+    const useToolSearch = options?.useToolSearch === true;
     // Separate MCP tools (group by server) from non-MCP tools (individual listing)
     const mcpByServer = new Map();
     const nonMcpEntries = [];
@@ -181,10 +220,13 @@ export function buildDeferredToolsContext(entries) {
         const shortNames = tools.map(t => t.name.startsWith(prefix) ? t.name.slice(prefix.length) : t.name);
         lines.push(`[${server}] (${tools.length} tools): ${shortNames.join(", ")}`);
     }
+    const instruction = useToolSearch
+        ? "These tools auto-load on first invocation -- call them directly by name with the right arguments. To preview a tool's schema before calling, use tool_search_tool_regex with a regex matching the tool name (e.g., tool_search_tool_regex(pattern: \"agents_manage\"))."
+        : "Call discover_tools to search by keyword or server name (e.g., discover_tools(\"yfinance\")).";
     return [
         "<deferred-tools>",
         "The following tools are available but not loaded.",
-        "Call discover_tools to search by keyword or server name (e.g., discover_tools(\"yfinance\")).",
+        instruction,
         "",
         ...lines,
         "</deferred-tools>",

package/node_modules/@comis/agent/dist/executor/tool-parallelism.js

@@ -41,7 +41,6 @@ export const READ_ONLY_TOOLS = new Set([
     "sessions_list",
     "session_status",
     "sessions_history",
-    "agents_list",
     // Context reads
     "ctx_search",
     "ctx_inspect",

package/node_modules/@comis/agent/dist/executor/types.d.ts

@@ -59,14 +59,23 @@ export interface ExecutionResult {
         /** Stop reason from tracker (budget_reached | diminishing_returns | max_continuations | under_budget). */
         stopReason: string;
     };
-    /** Silent Execution Planner metrics (undefined if SEP inactive). */
+    /** Silent Execution Planner metrics (undefined if SEP inactive).
+     *  SEP is observability-only post-L4: plan extraction + step counting
+     *  remain; the legacy enforcement nudge was replaced by the post-batch
+     *  continuation handler. */
     plannerMetrics?: {
         stepsPlanned: number;
         stepsCompleted: number;
         stepsSkipped: number;
-        nudgeTriggered: boolean;
         planExtractionTurn: number;
     };
+    /** Post-batch continuation handler outcome (undefined when handler did
+     *  not run, e.g., guardrail failed before reaching it). */
+    continuationMetrics?: {
+        fired: boolean;
+        attempts: number;
+        outcome: "recovered" | "still_empty" | "max_attempts_exhausted" | "disabled" | "no_match";
+    };
 }
 /** Optional overrides for per-execution behavior (e.g., sub-agent isolation). */
 export interface ExecutionOverrides {

package/node_modules/@comis/agent/dist/index.d.ts

@@ -52,6 +52,8 @@ export { createOAuthTokenManager } from "./model/oauth-token-manager.js";
 export type { OAuthTokenManager, OAuthTokenManagerDeps, OAuthError } from "./model/oauth-token-manager.js";
 export { createAuthUsageTracker } from "./model/auth-usage-tracker.js";
 export type { AuthUsageTracker, ProfileStats, ProfileUsageInput } from "./model/auth-usage-tracker.js";
+export { createLastKnownModelTracker } from "./model/last-known-model.js";
+export type { LastKnownModelTracker, LastKnownModelEntry } from "./model/last-known-model.js";
 export { createMessageRouter, resolveAgent } from "./routing/message-router.js";
 export type { MessageRouter } from "./routing/message-router.js";
 export { createSessionLifecycle } from "./session/session-lifecycle.js";
@@ -136,7 +138,7 @@ export type { PiEventBridgeDeps, PiEventBridgeResult } from "./bridge/pi-event-b
 export { createAuthStorageAdapter, DEFAULT_PROVIDER_KEYS } from "./model/auth-storage-adapter.js";
 export type { AuthStorageAdapterOptions } from "./model/auth-storage-adapter.js";
 export { createModelRegistryAdapter, registerCustomProviders, resolveInitialModel } from "./model/model-registry-adapter.js";
-export type { CustomProviderRegistration, CustomProviderLogger } from "./model/model-registry-adapter.js";
+export type { CustomProviderRegistration, CustomProviderLogger, RegisterCustomProvidersResult } from "./model/model-registry-adapter.js";
 export { sessionKeyToPath, pathToSessionKey } from "./session/session-key-mapper.js";
 export { detectBrokenFollowThrough, FOLLOW_THROUGH_PATTERNS } from "./safety/response-safety-checks.js";
 export type { FollowThroughResult } from "./safety/response-safety-checks.js";

package/node_modules/@comis/agent/dist/index.js

@@ -44,6 +44,8 @@ export { createModelScanner } from "./model/model-scanner.js";
 export { createOAuthTokenManager } from "./model/oauth-token-manager.js";
 // Auth usage tracker (from 62-05)
 export { createAuthUsageTracker } from "./model/auth-usage-tracker.js";
+// Last-known-working model tracker (auth-failure fallback)
+export { createLastKnownModelTracker } from "./model/last-known-model.js";
 // Routing
 export { createMessageRouter, resolveAgent } from "./routing/message-router.js";
 // Session lifecycle (renamed from session-manager.ts)

package/node_modules/@comis/agent/dist/model/last-known-model.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Last-known-working model tracker.
+ *
+ * Tracks the most recent successfully-used model per agent across the daemon.
+ * When all configured fallbacks fail with auth errors (401/403), the retry
+ * pipeline can query this tracker for a model that recently worked -- either
+ * for the same agent or any other agent on the daemon.
+ *
+ * Follows the closure-over-mutable-state factory pattern (no classes),
+ * matching createProviderHealthMonitor.
+ *
+ * @module
+ */
+/** A record of a model that successfully completed a prompt. */
+export interface LastKnownModelEntry {
+    provider: string;
+    model: string;
+    timestamp: number;
+}
+/** Tracker interface for last-known-working model queries. */
+export interface LastKnownModelTracker {
+    /** Record a successful model completion for an agent. */
+    recordSuccess(agentId: string, provider: string, model: string): void;
+    /** Get the last-known-working model for a specific agent. */
+    getLastKnown(agentId: string): LastKnownModelEntry | undefined;
+    /** Get any successful model from ANY agent (daemon-wide).
+     *  Optionally exclude a specific provider (useful when that provider is failing). */
+    getAnyKnown(excludeProvider?: string): LastKnownModelEntry | undefined;
+}
+/**
+ * Create a last-known-working model tracker.
+ *
+ * Uses closure over mutable state (no classes) following the
+ * provider-health-monitor pattern. All operations are synchronous.
+ */
+export declare function createLastKnownModelTracker(): LastKnownModelTracker;

package/node_modules/@comis/agent/dist/model/last-known-model.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Last-known-working model tracker.
+ *
+ * Tracks the most recent successfully-used model per agent across the daemon.
+ * When all configured fallbacks fail with auth errors (401/403), the retry
+ * pipeline can query this tracker for a model that recently worked -- either
+ * for the same agent or any other agent on the daemon.
+ *
+ * Follows the closure-over-mutable-state factory pattern (no classes),
+ * matching createProviderHealthMonitor.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a last-known-working model tracker.
+ *
+ * Uses closure over mutable state (no classes) following the
+ * provider-health-monitor pattern. All operations are synchronous.
+ */
+export function createLastKnownModelTracker() {
+    const entries = new Map();
+    return {
+        recordSuccess(agentId, provider, model) {
+            entries.set(agentId, {
+                provider,
+                model,
+                timestamp: Date.now(),
+            });
+        },
+        getLastKnown(agentId) {
+            return entries.get(agentId);
+        },
+        getAnyKnown(excludeProvider) {
+            let best;
+            for (const entry of entries.values()) {
+                if (excludeProvider && entry.provider === excludeProvider)
+                    continue;
+                if (!best || entry.timestamp > best.timestamp) {
+                    best = entry;
+                }
+            }
+            return best;
+        },
+    };
+}

package/node_modules/@comis/agent/dist/model/model-registry-adapter.d.ts

@@ -58,6 +58,18 @@ export interface CustomProviderLogger {
     warn(obj: Record<string, unknown>, msg: string): void;
     debug(obj: Record<string, unknown>, msg: string): void;
 }
+/** Result of custom provider registration. */
+export interface RegisterCustomProvidersResult {
+    /** Number of provider entries successfully registered. */
+    registered: number;
+    /**
+     * Comis provider name → built-in pi SDK provider name.
+     * Populated when a YAML entry's `type` matches a built-in provider but the
+     * entry's key (comis name) differs. Lets model resolution fall back to the
+     * built-in catalog: `registry.find("gemini", id)` fails → try `registry.find("google", id)`.
+     */
+    providerAliases: Map<string, string>;
+}
 /**
  * Register YAML `providers.entries.*` with pi-coding-agent's ModelRegistry.
  *
@@ -69,13 +81,13 @@ export interface CustomProviderLogger {
  * Per-entry behavior:
  *   - Skipped if `enabled === false`.
  *   - Skipped if no models declared and no `baseUrl` override.
+ *   - Models that already exist in the built-in pi SDK catalog for the
+ *     entry's `type` are filtered out (no redundant registration).
  *   - On `registerProvider` error (missing baseUrl, missing apiKey, etc.),
  *     a WARN is logged and the loop continues -- one bad entry must not
  *     prevent the daemon from starting.
- *
- * @returns Number of entries successfully registered.
  */
-export declare function registerCustomProviders(registry: ModelRegistry, entries: Record<string, CustomProviderRegistration>, secretManager: SecretManager, logger: CustomProviderLogger): number;
+export declare function registerCustomProviders(registry: ModelRegistry, entries: Record<string, CustomProviderRegistration>, secretManager: SecretManager, logger: CustomProviderLogger): RegisterCustomProvidersResult;
 /**
  * Resolve the initial model for an agent session.
  *
@@ -90,4 +102,4 @@ export declare function registerCustomProviders(registry: ModelRegistry, entries
 export declare function resolveInitialModel(registry: ModelRegistry, config: {
     provider: string;
     model: string;
-}, allowlist?: ModelAllowlist): Promise<InitialModelResult>;
+}, allowlist?: ModelAllowlist, providerAliases?: Map<string, string>): Promise<InitialModelResult>;