comisai 1.0.25 → 1.0.26

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

@@ -10,6 +10,7 @@
  * @module
  */
 import { ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { getModels, getProviders } from "@mariozechner/pi-ai";
 /**
  * Create a ModelRegistry from an AuthStorage instance.
  *
@@ -27,6 +28,18 @@ export function createModelRegistryAdapter(authStorage) {
  * proxies (NVIDIA NIM, Together, ollama, lm-studio, etc.) work without
  * code changes.
  */
+/**
+ * Provider types that can register without an API key.
+ *
+ * Ollama (and similar local inference servers) do not require authentication
+ * by default. When a provider entry has a type in this set and no apiKeyName
+ * is configured (or the named secret is missing), registration proceeds with
+ * the "ollama-no-auth" sentinel instead of being skipped.
+ *
+ * The sentinel reaches the wire as `Authorization: Bearer ollama-no-auth`.
+ * Ollama ignores Authorization unless `OLLAMA_API_KEY` is set server-side.
+ */
+const KEYLESS_PROVIDER_TYPES = new Set(["ollama"]);
 const PROVIDER_TYPE_TO_API = {
     openai: "openai-completions",
     groq: "openai-completions",
@@ -39,6 +52,18 @@ const PROVIDER_TYPE_TO_API = {
     anthropic: "anthropic-messages",
     google: "google-generative-ai",
 };
+const _builtInProviders = new Set(getProviders());
+function getBuiltInBaseUrl(type) {
+    if (!_builtInProviders.has(type))
+        return undefined;
+    const models = getModels(type);
+    return models[0]?.baseUrl;
+}
+function getBuiltInModelIds(type) {
+    if (!_builtInProviders.has(type))
+        return new Set();
+    return new Set(getModels(type).map((m) => m.id));
+}
 /**
  * Register YAML `providers.entries.*` with pi-coding-agent's ModelRegistry.
  *
@@ -50,50 +75,66 @@ const PROVIDER_TYPE_TO_API = {
  * 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 function registerCustomProviders(registry, entries, secretManager, logger) {
     let registered = 0;
+    const providerAliases = new Map();
     for (const [providerName, entry] of Object.entries(entries)) {
         if (!entry.enabled) {
             logger.debug({ providerName }, "Custom provider skipped (disabled)");
             continue;
         }
-        const hasModels = entry.models.length > 0;
+        const builtInIds = getBuiltInModelIds(entry.type);
+        const isBuiltInType = builtInIds.size > 0;
+        if (isBuiltInType && providerName !== entry.type) {
+            providerAliases.set(providerName, entry.type);
+        }
+        const customModels = isBuiltInType
+            ? entry.models.filter((m) => !builtInIds.has(m.id))
+            : [...entry.models];
+        if (isBuiltInType && customModels.length < entry.models.length) {
+            const skipped = entry.models.length - customModels.length;
+            logger.debug({ providerName, type: entry.type, skipped, remaining: customModels.length }, "Skipped built-in models already in pi SDK catalog");
+        }
+        const hasModels = customModels.length > 0;
         const hasBaseUrlOverride = !!entry.baseUrl;
         if (!hasModels && !hasBaseUrlOverride) {
-            logger.debug({ providerName }, "Custom provider skipped (no models and no baseUrl override)");
+            logger.debug({ providerName }, "Custom provider skipped (no custom models and no baseUrl override)");
             continue;
         }
         const apiKey = entry.apiKeyName ? secretManager.get(entry.apiKeyName) : undefined;
-        if (hasModels && !apiKey) {
+        const isKeylessType = KEYLESS_PROVIDER_TYPES.has(entry.type);
+        if (hasModels && !apiKey && !isKeylessType) {
             logger.warn({
                 providerName,
                 apiKeyName: entry.apiKeyName,
-                hint: "Set the named secret in ~/.comis/.env or remove the provider entry from config.yaml",
+                hint: "Set the named secret in ~/.comis/.env, omit apiKeyName for type='ollama', or remove the provider entry from config.yaml",
                 errorKind: "config",
             }, "Custom provider has models but no API key -- skipping registration");
             continue;
         }
         const api = PROVIDER_TYPE_TO_API[entry.type] ?? "openai-completions";
         const headersResolved = Object.keys(entry.headers).length > 0 ? entry.headers : undefined;
+        const resolvedApiKey = apiKey ?? (isKeylessType ? "ollama-no-auth" : undefined);
+        if (resolvedApiKey === "ollama-no-auth") {
+            logger.debug({
+                providerName,
+                hint: "Using keyless sentinel for type='ollama'. If your Ollama server requires an OLLAMA_API_KEY, set the provider's apiKeyName explicitly via providers_manage update.",
+            }, "Custom provider registered with keyless sentinel");
+        }
         try {
             registry.registerProvider(providerName, {
                 api,
-                baseUrl: entry.baseUrl || undefined,
-                apiKey,
+                baseUrl: entry.baseUrl || getBuiltInBaseUrl(entry.type),
+                apiKey: resolvedApiKey,
                 headers: headersResolved,
-                // pi's ProviderModelConfig requires concrete values for name/cost/
-                // contextWindow/maxTokens. Comis's UserModelSchema lets users omit
-                // these (defaults to optional/undefined), so we fill in zeros and
-                // a generous default context window. Cost is informational only
-                // and our CostTracker uses pi-ai's own catalog where it can.
                 models: hasModels
-                    ? entry.models.map((m) => ({
+                    ? customModels.map((m) => ({
                         id: m.id,
                         name: m.name ?? m.id,
                         contextWindow: m.contextWindow ?? 128_000,
@@ -114,7 +155,7 @@ export function registerCustomProviders(registry, entries, secretManager, logger
                 providerName,
                 api,
                 baseUrl: entry.baseUrl,
-                modelCount: entry.models.length,
+                modelCount: customModels.length,
             }, "Custom provider registered with pi ModelRegistry");
         }
         catch (error) {
@@ -126,7 +167,7 @@ export function registerCustomProviders(registry, entries, secretManager, logger
             }, "Custom provider registration failed");
         }
     }
-    return registered;
+    return { registered, providerAliases };
 }
 /**
  * Resolve the initial model for an agent session.
@@ -139,11 +180,15 @@ export function registerCustomProviders(registry, entries, secretManager, logger
  * @param config - Agent model configuration (provider + model ID)
  * @param allowlist - Optional model allowlist for enforcement
  */
-export async function resolveInitialModel(registry, config, allowlist) {
-    // Try to find the exact model in the registry
-    const model = registry.find(config.provider, config.model);
+export async function resolveInitialModel(registry, config, allowlist, providerAliases) {
+    let model = registry.find(config.provider, config.model);
+    if (!model && providerAliases) {
+        const builtInName = providerAliases.get(config.provider);
+        if (builtInName) {
+            model = registry.find(builtInName, config.model);
+        }
+    }
     if (!model) {
-        // Try to find any available model from the requested provider
         const available = registry.getAvailable();
         const providerModel = available.find((m) => m.provider === config.provider);
         if (!providerModel) {
@@ -154,7 +199,6 @@ export async function resolveInitialModel(registry, config, allowlist) {
                     `Available models: ${available.map((m) => `${m.provider}/${m.id}`).join(", ") || "none"}`,
             };
         }
-        // Found a provider model but not the exact ID -- return it with a note
         return {
             model: undefined,
             thinkingLevel: "off",

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

@@ -31,8 +31,6 @@ export interface ExecutionPlan {
     steps: PlanStep[];
     /** Number of steps marked "done". */
     completedCount: number;
-    /** Whether the completeness nudge has been injected. */
-    nudged: boolean;
     /** Timestamp of plan creation. */
     createdAtMs: number;
 }

package/node_modules/@comis/agent/dist/session/comis-session-manager.d.ts

@@ -104,6 +104,16 @@ export interface ComisSessionManager {
      * Fire-and-forget -- metadata write failure must not affect execution.
      */
     writeSessionMetadata(sessionKey: SessionKey, metadata: SessionMetadata): void;
+    /**
+     * 260428-iag: Resolve the absolute JSONL session file path for a session key.
+     *
+     * Thin synchronous wrapper around `sessionKeyToPath(sessionKey, deps.sessionBaseDir)`
+     * that exposes the path resolver to the wire-edge diagnostic in pi-event-bridge.
+     * Pure delegation -- no I/O, no logging, no side effects. Path composition is
+     * delegated to `sessionKeyToPath`, which uses `safePath` for traversal-safe
+     * resolution.
+     */
+    getSessionPath(sessionKey: SessionKey): string;
 }
 /**
  * Create a ComisSessionManager that manages session lifecycle with write locks.

package/node_modules/@comis/agent/dist/session/comis-session-manager.js

@@ -70,6 +70,11 @@ export function createComisSessionManager(deps) {
                 catch { /* non-empty or already gone */ }
             }, { retries: 10, retryMinTimeout: 500 });
         },
+        getSessionPath(sessionKey) {
+            // 260428-iag wire-edge diagnostic: pure delegation to sessionKeyToPath
+            // (which uses safePath internally). No I/O, no logging.
+            return sessionKeyToPath(sessionKey, deps.sessionBaseDir);
+        },
         writeSessionMetadata(sessionKey, metadata) {
             const sessionPath = sessionKeyToPath(sessionKey, deps.sessionBaseDir);
             const metadataPath = sessionPath.replace(/\.jsonl$/, "_session-metadata.json");

package/node_modules/@comis/agent/dist/spawn/pi-mono-adapters.js

@@ -50,5 +50,12 @@ export function createEphemeralComisSessionManager(cwd) {
         writeSessionMetadata() {
             // No-op: no companion file for in-memory sessions
         },
+        getSessionPath() {
+            // 260428-iag wire-edge diagnostic: ephemeral sub-agent sessions never
+            // persist a JSONL file, so there is no path to return. Empty string
+            // signals "no persisted file"; the bridge's wire-diff hook short-circuits
+            // when jsonlPath.length === 0.
+            return "";
+        },
     };
 }

package/node_modules/@comis/agent/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/agent",
   "private": true,
-  "version": "1.0.25",
+  "version": "1.0.26",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "AI agent executor, budget control, and session management for Comis",

package/node_modules/@comis/channels/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/channels",
   "private": true,
-  "version": "1.0.25",
+  "version": "1.0.26",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Chat platform adapters — Discord, Telegram, Slack, WhatsApp, Signal, iMessage, IRC, LINE",

package/node_modules/@comis/cli/dist/client/rpc-client.js

@@ -127,8 +127,13 @@ function resolveFromConfig() {
                 token = undefined;
             }
         }
+        // gateway.host is a *bind* address. As a *connect* host, the wildcard
+        // values (0.0.0.0 / ::) aren't valid — remap to loopback so the CLI
+        // can reach a daemon that's binding all interfaces (the default for
+        // LAN / Docker deployments).
+        const connectHost = host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
         const protocol = tls ? "wss" : "ws";
-        return { url: `${protocol}://${host}:${port}/ws`, token, tls };
+        return { url: `${protocol}://${connectHost}:${port}/ws`, token, tls };
     }
     catch {
         return { url: FALLBACK_GATEWAY_URL, token: undefined, tls: false };

package/node_modules/@comis/cli/dist/commands/doctor.js

@@ -76,12 +76,14 @@ function buildDoctorContext(configPaths) {
     }
     const dataDir = config?.dataDir || os.homedir() + "/.comis";
     const daemonPidFile = dataDir + "/daemon.pid";
-    // Resolve gateway URL from config
+    // Resolve gateway URL from config. gw.host is a *bind* address; remap
+    // wildcards to loopback so the connectivity probe targets a real address.
     let gatewayUrl;
     if (config?.gateway) {
         const gw = config.gateway;
-        const host = gw.host || "127.0.0.1";
-        const port = gw.port || 3000;
+        const bindHost = gw.host || "127.0.0.1";
+        const host = bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost === "::" ? "::1" : bindHost;
+        const port = gw.port || 4766;
         const protocol = gw.tls ? "https" : "http";
         gatewayUrl = `${protocol}://${host}:${port}`;
     }

package/node_modules/@comis/cli/dist/commands/health.js

@@ -75,11 +75,14 @@ function buildHealthContext(configPaths) {
     }
     const dataDir = config?.dataDir || os.homedir() + "/.comis";
     const daemonPidFile = dataDir + "/daemon.pid";
+    // gw.host is a *bind* address; remap wildcards to loopback so the
+    // connectivity probe targets a real address.
     let gatewayUrl;
     if (config?.gateway) {
         const gw = config.gateway;
-        const host = gw.host || "127.0.0.1";
-        const port = gw.port || 3000;
+        const bindHost = gw.host || "127.0.0.1";
+        const host = bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost === "::" ? "::1" : bindHost;
+        const port = gw.port || 4766;
         const protocol = gw.tls ? "https" : "http";
         gatewayUrl = `${protocol}://${host}:${port}`;
     }

package/node_modules/@comis/cli/dist/wizard/json-output.js

@@ -34,13 +34,17 @@ export function buildJsonOutput(state, opts) {
     let gatewayUrl;
     let gatewayToken;
     if (state.gateway) {
-        const bindIp = state.gateway.bindMode === "loopback"
+        // For LAN mode the daemon binds 0.0.0.0, but the printed URL is
+        // a *connect* hint — surface 127.0.0.1 (the only address every
+        // local caller can reach). External clients use the host's public
+        // IP/hostname; surfacing 0.0.0.0 here would just be misleading.
+        const connectIp = state.gateway.bindMode === "loopback"
             ? "127.0.0.1"
             : state.gateway.bindMode === "lan"
-                ? "0.0.0.0"
+                ? "127.0.0.1"
                 : state.gateway.customIp ?? "127.0.0.1";
         const port = state.gateway.port ?? 4766;
-        gatewayUrl = `ws://${bindIp}:${port}`;
+        gatewayUrl = `ws://${connectIp}:${port}`;
         // Only include token when auth method is token
         if (state.gateway.authMethod === "token" && state.gateway.token) {
             gatewayToken = state.gateway.token;

package/node_modules/@comis/cli/dist/wizard/steps/11-daemon-start.js

@@ -18,6 +18,7 @@ import { existsSync, mkdirSync, writeFileSync, openSync, closeSync, accessSync,
 import * as os from "node:os";
 import { promisify } from "node:util";
 import { safePath } from "@comis/core";
+import { isDocker } from "@comis/infra";
 const exec = promisify(execFile);
 import { updateState, sectionSeparator, success as themeSuccess, error as themeError, } from "../index.js";
 // ---------- Constants ----------
@@ -76,6 +77,45 @@ async function waitForReady(host, port) {
     }
     return false;
 }
+/**
+ * Poll the gateway through a stop/start cycle.
+ *
+ * Used after signalling the in-container daemon for a Docker-managed
+ * restart: first waits for the gateway to go down (proving the signal
+ * landed and the container is exiting), then for a fresh gateway to
+ * come back (proving Docker's restart policy respawned the container).
+ * Returns false if either phase times out.
+ */
+async function waitForRestart(host, port) {
+    const url = `http://${host}:${port}/health`;
+    const probe = async () => {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 1500);
+            const res = await fetch(url, { signal: controller.signal });
+            clearTimeout(timer);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Phase 1: wait for the gateway to disappear (signal landed).
+    const downDeadline = Date.now() + 5_000;
+    while (Date.now() < downDeadline) {
+        if (!(await probe()))
+            break;
+        await new Promise((r) => setTimeout(r, READY_POLL_MS));
+    }
+    // Phase 2: wait for the gateway to come back (container restarted).
+    const upDeadline = Date.now() + READY_TIMEOUT_MS;
+    while (Date.now() < upDeadline) {
+        if (await probe())
+            return true;
+        await new Promise((r) => setTimeout(r, READY_POLL_MS));
+    }
+    return false;
+}
 /**
  * Run subsystem health checks and display results.
  *
@@ -196,6 +236,42 @@ async function runHealthCheck(state, prompter, gatewayHost, gatewayPort) {
         }
     }
 }
+/**
+ * Find the comis daemon PID inside the container.
+ *
+ * Scans /proc for processes whose parent is PID 1 and whose cmdline
+ * contains "daemon.js". Used to signal the container's daemon for a
+ * Docker-native restart instead of spawning a sibling.
+ */
+async function findContainerDaemonPid() {
+    try {
+        const { readdirSync, readFileSync } = await import("node:fs");
+        for (const entry of readdirSync("/proc")) {
+            if (!/^\d+$/.test(entry))
+                continue;
+            const pid = Number(entry);
+            if (pid === 1 || pid === process.pid)
+                continue;
+            let cmdline;
+            let ppid;
+            try {
+                cmdline = readFileSync(`/proc/${entry}/cmdline`, "utf-8");
+                const status = readFileSync(`/proc/${entry}/status`, "utf-8");
+                ppid = (/^PPid:\s*(\d+)/m.exec(status)?.[1]) ?? "";
+            }
+            catch {
+                continue;
+            }
+            if (ppid !== "1")
+                continue;
+            if (!cmdline.includes("daemon.js"))
+                continue;
+            return pid;
+        }
+    }
+    catch { /* /proc not accessible */ }
+    return undefined;
+}
 async function detectServiceManager() {
     if (!existsSync("/run/systemd/system"))
         return "direct";
@@ -351,6 +427,60 @@ export const daemonStartStep = {
             return updateState(state, {});
         }
         // 4. Direct-spawn fallback (no systemd)
+        // Docker branch: the daemon is the container's PID 1 process tree.
+        // Spawning a sibling produces EADDRINUSE; killing PID 1 directly via
+        // pid-file (which the container daemon doesn't write) is a no-op.
+        // Signal the actual daemon process so dumb-init exits and Docker's
+        // restart policy brings the container back with the new config.
+        if (isDocker()) {
+            const dockerSpinner = prompter.spinner();
+            if (choice === "restart" || daemonRunning) {
+                dockerSpinner.start("Signalling container daemon to restart...");
+                const targetPid = await findContainerDaemonPid();
+                if (targetPid) {
+                    // 260428-qrn: Prime the user BEFORE the SIGTERM so they have a
+                    // breadcrumb pointing at the missing `--restart unless-stopped`
+                    // flag. This is a heads-up, not an abort -- the existing
+                    // waitForRestart detector still handles the failure path below.
+                    prompter.log.warn("Restarting daemon via SIGTERM. The container must have been started with `--restart unless-stopped` (or equivalent compose `restart: unless-stopped`). If the container exits and stays exited, run `docker restart <container-name>` from your host.");
+                    try {
+                        process.kill(targetPid, "SIGTERM");
+                    }
+                    catch { /* already gone */ }
+                    // Wait for the gateway to disappear, then for it to come back
+                    // (Docker restart policy respawns the container).
+                    const restarted = await waitForRestart(host, port);
+                    if (restarted) {
+                        dockerSpinner.stop("Daemon restarted via container restart policy");
+                    }
+                    else {
+                        dockerSpinner.stop("Daemon stopped, but the container did not auto-restart");
+                        prompter.log.warn("Run `docker restart <container>` (or `docker start <container>` if it exited) to apply the new config.");
+                        return updateState(state, {});
+                    }
+                }
+                else {
+                    dockerSpinner.stop("Could not find the container daemon process");
+                    prompter.log.warn("Run `docker restart <container>` to apply the new configuration.");
+                    return updateState(state, {});
+                }
+            }
+            else {
+                // Daemon wasn't running and we're inside a container — Docker
+                // launches the daemon itself; nothing for the wizard to do here.
+                dockerSpinner.start("Waiting for container daemon...");
+                const ready = await waitForReady(host, port);
+                dockerSpinner.stop(ready ? "Daemon ready" : "Daemon not yet responding");
+                if (!ready) {
+                    prompter.log.warn("Start the container with `docker start <container>` if it isn't already running.");
+                    return updateState(state, {});
+                }
+            }
+            if (!state.skipHealth) {
+                await runHealthCheck(state, prompter, host, port);
+            }
+            return updateState(state, {});
+        }
         // Stop existing daemon before restart
         if (choice === "restart") {
             const stopSpinner = prompter.spinner();

package/node_modules/@comis/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/cli",
   "private": true,
-  "version": "1.0.25",
+  "version": "1.0.26",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Command-line interface for the Comis AI agent platform",

package/node_modules/@comis/core/dist/config/immutable-keys.d.ts

@@ -25,8 +25,8 @@ export declare const MUTABLE_CONFIG_OVERRIDES: readonly string[];
  * path segments, the path is considered a match (equal to or a child of the
  * pattern).
  *
- * @param fullPath - Full dot-notation config path (e.g., "agents.default.persona.name")
- * @param pattern - Override pattern with `*` wildcards (e.g., "agents.*.persona")
+ * @param fullPath - Full dot-notation config path (e.g., "agents.default.maxSteps")
+ * @param pattern - Override pattern with `*` wildcards (e.g., "agents.*.maxSteps")
  * @returns true if the path matches or is a child of the pattern
  */
 export declare function matchesOverridePattern(fullPath: string, pattern: string): boolean;

package/node_modules/@comis/core/dist/config/immutable-keys.js

@@ -22,7 +22,12 @@ export const MUTABLE_CONFIG_OVERRIDES = [
     "agents.*.skills.watchDebounceMs",
     "agents.*.skills.discoveryPaths",
     "agents.*.maxSteps",
-    "agents.*.persona",
+    // 260428-rrr Bug A: removed dead "agents.*.persona" entry. PerAgentConfigSchema
+    // is z.strictObject and has no `persona` field, so the override could never
+    // produce a successful patch -- it only leaked a misleading capability hint
+    // to LLMs (formatRedirectHint emitted "you can also patch agents.<id>.persona")
+    // which the LLM echoed back as `persona:` in agents_manage.create config,
+    // triggering Zod unrecognized_keys rejection.
     "agents.*.promptTimeout.promptTimeoutMs", // Allow runtime tuning
     "agents.*.promptTimeout.retryPromptTimeoutMs", // Allow runtime tuning
     "agents.*.operationModels", // Allow runtime model tiering tuning
@@ -39,8 +44,8 @@ export const MUTABLE_CONFIG_OVERRIDES = [
  * path segments, the path is considered a match (equal to or a child of the
  * pattern).
  *
- * @param fullPath - Full dot-notation config path (e.g., "agents.default.persona.name")
- * @param pattern - Override pattern with `*` wildcards (e.g., "agents.*.persona")
+ * @param fullPath - Full dot-notation config path (e.g., "agents.default.maxSteps")
+ * @param pattern - Override pattern with `*` wildcards (e.g., "agents.*.maxSteps")
  * @returns true if the path matches or is a child of the pattern
  */
 export function matchesOverridePattern(fullPath, pattern) {

package/node_modules/@comis/core/dist/config/managed-sections.d.ts

@@ -35,6 +35,29 @@ export interface ManagedSectionRedirect {
      * already present in config.
      */
     fullyManaged: boolean;
+    /**
+     * Compact schema fragment so the LLM can call the tool without a separate
+     * discover_tools round-trip. Populated when the action enum + required
+     * fields fit in < 20 lines of hint text. Verified against the tool's
+     * TypeBox parameter schema as of this commit.
+     *
+     * Bug B (260428-gj6): production trace c7b91328 showed the agent burning
+     * ~30s × 4 LLM calls re-loading the agents_manage schema after an
+     * immutable-path rejection. Surfacing the fragment inline closes that
+     * round-trip tax.
+     */
+    schemaFragment?: {
+        /** Valid `action` enum values (pinned to the tool's TypeBox Union literals). */
+        actions: readonly string[];
+        /**
+         * Required field names per action -- only entries that are strictly
+         * required by the tool's handler (omitting Type.Optional fields with
+         * sensible defaults). Omit the whole property when no action has
+         * required-beyond-action fields (e.g., channels_manage operates on
+         * existing entries only).
+         */
+        requiredByAction?: Record<string, readonly string[]>;
+    };
 }
 /**
  * Registered managed sections.
@@ -55,10 +78,26 @@ export declare function getManagedSectionRedirect(section: string | undefined, k
 /**
  * Format an LLM-readable hint for an immutability rejection.
  *
- * The output uses an explicit two-step "Recovery:" framing because smaller
- * models (Haiku 4.5, Gemini Flash, GPT-OSS-20b) parse numbered steps more
- * reliably than prose. The example call is JSON-stringified compactly so it
- * can be copy-pasted into the next tool invocation.
+ * Output is a single-step "Recovery: call <tool>(<example>)." line: the
+ * dedicated `*_manage` tool auto-loads on first direct invocation under
+ * every supported provider path:
+ *
+ * - Anthropic Sonnet/Opus 4.x: request-body-injector strips client-side
+ *   `discover_tools` from the payload and marks deferred tools
+ *   `defer_loading: true`; calling the tool by name auto-loads it.
+ * - Anthropic Haiku / OpenAI / xAI / Google: tools surface via the
+ *   client-side `discover_tools` corpus, but a stub-filter wraps deferred
+ *   entries so that calling the tool by name still works first try (the
+ *   stub forwards to the real tool and registers it as discovered).
+ *
+ * Naming `discover_tools` in the hint actively misleads Anthropic
+ * Sonnet/Opus 4.x because that tool is not in their payload (260428-oyc
+ * production repro: agent saw "Recovery: (1) call discover_tools(...)" and
+ * gave up, reporting "I don't have a discover_tools function"). The
+ * single-step framing works on every provider.
+ *
+ * The example call is JSON-stringified compactly so it can be copy-pasted
+ * verbatim into the next tool invocation.
  *
  * @param redirect - The matched managed-section entry
  * @param mutablePaths - Optional override paths for in-place patching of