comisai 1.0.34 → 1.0.37

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

@@ -3,7 +3,7 @@
  * Handles model catalog query methods:
  *   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)
+ *   models.list_providers -- Live native pi-ai catalog provider list
  * All handlers are read-only -- no approval gate required.
  * @module
  */

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

@@ -4,7 +4,7 @@
  * Handles model catalog query methods:
  *   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)
+ *   models.list_providers -- Live native pi-ai catalog provider list
  * All handlers are read-only -- no approval gate required.
  * @module
  */
@@ -64,7 +64,7 @@ export function createModelHandlers(deps) {
             };
         },
         // -----------------------------------------------------------------------
-        // List native pi-ai catalog providers (Layer 1F -- 260430-vwt)
+        // List native pi-ai catalog providers
         //
         // Live self-discovery for the agent: returns the de-duplicated, sorted
         // list of provider names from the pi-ai native catalog. Pairs with the

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

@@ -196,20 +196,17 @@ export function createProviderHandlers(deps) {
                 throw new Error(`Provider already exists: ${providerId}`);
             }
             const config = params.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.
+            // 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.
             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.
+            // 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
@@ -260,8 +257,8 @@ 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
+            // 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;

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

@@ -185,6 +185,7 @@ export interface RpcDispatchDeps {
     globalHeartbeatConfig?: Record<string, unknown>;
     notificationService?: import("../notification/notification-service.js").NotificationService;
     imageHandlerDeps?: ImageHandlerDeps;
+    oauthCredentialStore?: import("@comis/core").OAuthCredentialStorePort;
 }
 /**
  * Classify an RPC error message for structured logging.

package/node_modules/@comis/daemon/dist/rpc/rpc-dispatch.js

@@ -71,7 +71,17 @@ export function createRpcDispatch(deps) {
         ...createSessionHandlers(deps),
         ...createMessageHandlers(deps),
         ...createMediaHandlers(deps),
-        ...createConfigHandlers(deps),
+        // Thread the daemon-level OAuth credential store into config.patch's
+        // credential guard so model/provider patches on OAuth-only providers
+        // (e.g. openai-codex) can resolve via Source C
+        // (agents.<id>.oauthProfiles -> ~/.comis/auth-profiles.json). Explicit
+        // pass-through mirrors the createAgentHandlers wiring below; do not
+        // simplify back to `...createConfigHandlers(deps)` (the structural-typing
+        // inheritance is fragile to future deps-shape narrowing).
+        ...createConfigHandlers({
+            ...deps,
+            oauthCredentialStore: deps.oauthCredentialStore,
+        }),
         ...createEnvHandlers(deps),
         ...createBrowserHandlers(deps),
         ...createSubagentHandlers(deps),
@@ -90,6 +100,14 @@ export function createRpcDispatch(deps) {
             ...deps,
             secretManager: deps.container?.secretManager,
             providerEntries: deps.container.config.providers.entries,
+            // Thread the daemon-level OAuth credential store into agents.update
+            // so the oauthProfiles existence check can run via has(). When unset
+            // (e.g. unwired test setups) the validation block in agent-handlers
+            // becomes a no-op.
+            oauthCredentialStore: deps.oauthCredentialStore,
+            // Resolves `provider: "default"` to `models.defaultProvider` in the
+            // credential check, mirroring `resolveAgentModel` runtime resolution.
+            modelsConfig: deps.container.config.models,
             persistDeps: {
                 container: deps.container,
                 configPaths: deps.configPaths,
@@ -135,7 +153,14 @@ export function createRpcDispatch(deps) {
                 logger: deps.logger,
             },
         }),
-        ...createMcpHandlers({ mcpClientManager: deps.mcpClientManager, logger: deps.logger }),
+        ...createMcpHandlers({
+            mcpClientManager: deps.mcpClientManager,
+            logger: deps.logger,
+            // Threaded for env-ref validation on mcp.connect. Same pattern as
+            // agent/provider handlers above. When undefined the validator becomes
+            // a no-op.
+            secretManager: deps.container?.secretManager,
+        }),
         ...createDaemonHandlers({ logLevelManager: deps.logLevelManager }),
         // Workspace file management handlers
         ...createWorkspaceHandlers({

package/node_modules/@comis/daemon/dist/setup-docker-restart-warn.js

@@ -25,6 +25,5 @@ export function emitDockerRestartPolicyWarn(logger, opts = {}) {
     logger.warn({
         hint: "Wizard 'Restart' actions, gateway.restart, gateway.env_set, and gateway.patch on restart-triggering paths all require the container to have --restart unless-stopped (or compose restart: unless-stopped). Verify from your host with: docker inspect <name> --format '{{.HostConfig.RestartPolicy.Name}}'",
         errorKind: "config",
-        module: "daemon",
     }, "Running in Docker — restart policy required for config-reload operations");
 }

package/node_modules/@comis/daemon/dist/sub-agent-runner.d.ts

@@ -139,6 +139,24 @@ export interface SubAgentRunnerDeps {
             abort(): Promise<void>;
         } | undefined;
     };
+    /**
+     * Optional composite-key resolver (R3, B37). When provided, supersedes
+     * `activeRunRegistry.get(sessionKey)` for production aborts: the resolver
+     * accepts `{ agentId, channelType, channelId }` so multi-agent /
+     * multi-channel sessions are distinguishable. Locally re-declared to a
+     * structural minimum (avoids a daemon -> agent type-only import cycle in
+     * this leaf module). The daemon wires it via
+     * `createBackgroundSessionResolver({activeRunRegistry})`.
+     */
+    sessionResolver?: {
+        resolveActiveSession(key: {
+            agentId: string;
+            channelType: string;
+            channelId: string;
+        }): {
+            abort(): Promise<void>;
+        } | undefined;
+    };
     /** Optional result condenser for compressing subagent output */
     resultCondenser?: {
         condense(params: {

package/node_modules/@comis/daemon/dist/sub-agent-runner.js

@@ -22,6 +22,34 @@ import { classifyAbortReason, buildAnnouncementMessage, deliverAnnouncement, del
  *  Parent agents may call slow tools (image generation at 120s, web search, etc.)
  *  in response to announcements. 30s caused premature fallback + duplicate delivery. */
 export const ANNOUNCE_PARENT_TIMEOUT_MS = 300_000;
+/**
+ * Build the composite-key triple from a SubAgentRun for resolver lookups
+ * (R3, B37). Sub-agent runs only carry a formatted `sessionKey` string +
+ * `agentId` + optional announce-channel context, so:
+ *   - agentId    -> run.agentId
+ *   - channelType-> run.announceChannelType ?? "sub-agent"
+ *   - channelId  -> run.announceChannelId
+ *                   ?? parseFormattedSessionKey(run.sessionKey)?.channelId
+ *                   ?? run.sessionKey  (last-resort: the formatted key
+ *                                       itself; never empty so the
+ *                                       resolver's empty-field guard
+ *                                       does not trip)
+ *
+ * The "sub-agent" channelType fallback acknowledges that production
+ * SubAgentRun does not carry the original inbound channelType -- the
+ * abort path is best-effort regardless (the SDK session may already be
+ * in cleanup), so a no-op when the resolver does not find a handle is
+ * acceptable. There is a runtime semantic gap (deviation: composite-key
+ * triple vs registered formatted-key shape).
+ */
+function deriveCompositeForRun(run) {
+    const parsed = parseFormattedSessionKey(run.sessionKey);
+    return {
+        agentId: run.agentId,
+        channelType: run.announceChannelType ?? "sub-agent",
+        channelId: run.announceChannelId ?? parsed?.channelId ?? run.sessionKey,
+    };
+}
 // Re-export extracted result processor types and functions for backward compatibility
 export { classifyAbortReason, buildAnnouncementMessage, deliverFailureNotification, sweepResultFiles, persistFailureRecord, validateOutputs } from "./sub-agent-result-processor.js";
 // ---------------------------------------------------------------------------
@@ -181,9 +209,9 @@ export function createSubAgentRunner(deps) {
                     runtimeMs: runningDurationMs,
                 }, deps.logger), "ghost-sweep-failure-record");
             }
-            // Abort SDK session (best-effort)
-            if (deps.activeRunRegistry) {
-                const handle = deps.activeRunRegistry.get(run.sessionKey);
+            // Abort SDK session (best-effort, R3 / B37 -- composite-key resolver)
+            if (deps.sessionResolver) {
+                const handle = deps.sessionResolver.resolveActiveSession(deriveCompositeForRun(run));
                 if (handle) {
                     // eslint-disable-next-line no-restricted-syntax -- intentional fire-and-forget
                     handle.abort().catch(() => { });
@@ -1000,9 +1028,12 @@ export function createSubAgentRunner(deps) {
                     runtimeMs,
                 }, deps.logger), "watchdog-failure-record");
             }
-            // Abort SDK session (keyed by sessionKey, NOT runId)
-            if (deps.activeRunRegistry) {
-                const handle = deps.activeRunRegistry.get(run.sessionKey);
+            // Abort SDK session via composite-key resolver (R3 / B37). The
+            // previous lookup keyed on the formatted sessionKey only; the
+            // resolver makes the `(agentId, channelType, channelId)` triple
+            // explicit so multi-agent collisions are distinguishable.
+            if (deps.sessionResolver) {
+                const handle = deps.sessionResolver.resolveActiveSession(deriveCompositeForRun(run));
                 if (handle) {
                     handle.abort().catch((abortErr) => {
                         deps.logger?.debug({ runId, err: abortErr }, "Watchdog SDK abort best-effort failed");
@@ -1133,9 +1164,10 @@ export function createSubAgentRunner(deps) {
                 runtimeMs: run.completedAt - run.startedAt,
             }, deps.logger), "kill-failure-record");
         }
-        // Abort the in-flight SDK session to stop LLM API calls (best-effort)
-        if (deps.activeRunRegistry) {
-            const handle = deps.activeRunRegistry.get(run.sessionKey);
+        // Abort the in-flight SDK session via composite-key resolver
+        // (R3 / B37, best-effort).
+        if (deps.sessionResolver) {
+            const handle = deps.sessionResolver.resolveActiveSession(deriveCompositeForRun(run));
             if (handle) {
                 handle.abort().catch((abortErr) => {
                     deps.logger?.debug({ runId, err: abortErr }, "Sub-agent SDK abort best-effort failed");

package/node_modules/@comis/daemon/dist/wiring/index.d.ts

@@ -17,3 +17,7 @@ export { setupGateway, type GatewayDeps, type GatewayResult, setupRpcBridge, typ
 export { setupDeliveryQueue, type DeliveryQueueResult, setupDeliveryMirror, type DeliveryMirrorResult } from "./setup-delivery.js";
 export { setupNotifications, type NotificationContext } from "./setup-notifications.js";
 export { setupBackgroundTasks, type BackgroundTasksContext } from "./setup-background-tasks.js";
+export { setupBackgroundCompletionRunner } from "./setup-background-completion-runner.js";
+export type { BackgroundCompletionRunnerContext, SetupBackgroundCompletionRunnerDeps, } from "./setup-background-completion-runner.js";
+export { setupOutputRetention, validateOutputRetentionConfig, } from "./setup-output-retention.js";
+export type { SetupOutputRetentionDeps, SetupOutputRetentionHandle, } from "./setup-output-retention.js";

package/node_modules/@comis/daemon/dist/wiring/index.js

@@ -16,3 +16,5 @@ export { setupGateway, setupRpcBridge } from "./setup-gateway.js";
 export { setupDeliveryQueue, setupDeliveryMirror } from "./setup-delivery.js";
 export { setupNotifications } from "./setup-notifications.js";
 export { setupBackgroundTasks } from "./setup-background-tasks.js";
+export { setupBackgroundCompletionRunner } from "./setup-background-completion-runner.js";
+export { setupOutputRetention, validateOutputRetentionConfig, } from "./setup-output-retention.js";

package/node_modules/@comis/daemon/dist/wiring/oauth-preflight.d.ts

@@ -0,0 +1,21 @@
+import type { ComisLogger } from "@comis/infra";
+import type { PerAgentConfig } from "@comis/core";
+/**
+ * Returns `true` iff at least one agent's `provider` is recognised by pi-ai's
+ * `getOAuthProvider` as an OAuth-using provider.
+ *
+ * Single-source-of-truth check — avoids drift with pi-ai's provider catalogue.
+ * When this returns `false`, the daemon skips the preflight entirely (zero
+ * outbound probes during boot for OAuth-less deployments).
+ */
+export declare function hasAnyOAuthAgent(agents: Record<string, PerAgentConfig>): boolean;
+/**
+ * Run the OAuth TLS preflight and emit a single structured log line if it
+ * fails. Never throws — `runOAuthTlsPreflight` returns a discriminated union
+ * and this function only reads-and-logs.
+ *
+ * Caller is expected to invoke this fire-and-forget (`void`) AFTER the
+ * `"Comis daemon started"` banner so the daemon already counts as healthy
+ * to PM2/systemd by the time the probe resolves.
+ */
+export declare function emitOAuthTlsPreflightWarn(logger: ComisLogger): Promise<void>;

package/node_modules/@comis/daemon/dist/wiring/oauth-preflight.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Boot-time OAuth TLS preflight wiring.
+ *
+ * Two helpers exposed for the daemon entry point:
+ *
+ *   1. `hasAnyOAuthAgent(agents)` — runtime gate. Returns `true` iff at least
+ *      one entry in the per-agent map declares a `provider` value that
+ *      pi-ai's `getOAuthProvider` recognises as an OAuth provider. Used to
+ *      skip the entire preflight (and any outbound network probe) when no
+ *      OAuth-using agent is configured.
+ *
+ *   2. `emitOAuthTlsPreflightWarn(logger)` — fire-and-forget. Calls
+ *      `runOAuthTlsPreflight({ timeoutMs: 4000 })` from `@comis/agent`
+ *      and surfaces the result via Pino:
+ *        - `kind: "tls-cert"` → exactly one WARN with module + errorKind +
+ *          distro-aware install hint + OpenSSL `code` + raw `message`.
+ *        - `kind: "network"` → a single DEBUG (no WARN — transient failures
+ *          should not pollute the boot path).
+ *        - `{ ok: true }` → silent (operators do not want noise on boot).
+ *
+ * The 4000 ms timeout is intentionally tighter than the CLI doctor variant's
+ * 5000 ms — boot must stay under PM2 / systemd watchdog windows even on the
+ * worst case.
+ *
+ * Distro detection (`/etc/os-release` parser + 5-distro install-hint switch)
+ * is duplicated inline from `packages/cli/src/doctor/checks/oauth-health.ts`.
+ * Per AGENTS.md §2.3 rule of three, two callers do not yet justify a shared
+ * helper. If a third caller appears, extract the pair to
+ * `packages/agent/src/model/oauth-os-release.ts`.
+ *
+ * Per AGENTS.md §2.4 the logger is injected — no `@comis/infra` import.
+ *
+ * @module
+ */
+import { readFile } from "node:fs/promises";
+import { runOAuthTlsPreflight } from "@comis/agent";
+import { getOAuthProvider } from "@mariozechner/pi-ai/oauth";
+/** Boot-tighter timeout — keeps the preflight inside PM2/systemd watchdog windows. */
+const PREFLIGHT_TIMEOUT_MS = 4000;
+/** Pino `module` field — operators grep on this to isolate preflight logs. */
+const MODULE_NAME = "oauth-tls-preflight";
+/**
+ * Returns `true` iff at least one agent's `provider` is recognised by pi-ai's
+ * `getOAuthProvider` as an OAuth-using provider.
+ *
+ * Single-source-of-truth check — avoids drift with pi-ai's provider catalogue.
+ * When this returns `false`, the daemon skips the preflight entirely (zero
+ * outbound probes during boot for OAuth-less deployments).
+ */
+export function hasAnyOAuthAgent(agents) {
+    return Object.values(agents).some((agent) => Boolean(getOAuthProvider(agent.provider)));
+}
+/**
+ * Parses `/etc/os-release` into `{ id, idLike }`. Returns `null` on read
+ * error (missing file, permission denied, malformed contents).
+ *
+ * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
+ * AGENTS.md §2.3 deferral rationale.
+ */
+async function readOsRelease(path = "/etc/os-release") {
+    try {
+        const text = await readFile(path, "utf-8");
+        const map = new Map();
+        for (const line of text.split("\n")) {
+            const m = line.match(/^([A-Z_]+)=(.*)$/);
+            if (m)
+                map.set(m[1], m[2].replace(/^"|"$/g, ""));
+        }
+        const id = map.get("ID") ?? "";
+        const idLike = (map.get("ID_LIKE") ?? "").split(/\s+/).filter(Boolean);
+        return { id, idLike };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Produces a distro-aware install command for the system CA bundle.
+ *
+ * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
+ * AGENTS.md §2.3 deferral rationale.
+ */
+function caCertificatesInstallHint(os) {
+    if (!os)
+        return "Install ca-certificates via your distro's package manager and retry";
+    const idChain = [os.id, ...os.idLike];
+    if (idChain.includes("alpine"))
+        return "apk add ca-certificates && update-ca-certificates";
+    if (idChain.includes("debian") || idChain.includes("ubuntu")) {
+        return "sudo apt-get install -y ca-certificates && sudo update-ca-certificates";
+    }
+    if (idChain.includes("fedora") || idChain.includes("rhel") || idChain.includes("centos")) {
+        return "sudo dnf install -y ca-certificates && sudo update-ca-trust";
+    }
+    if (idChain.includes("arch"))
+        return "sudo pacman -S ca-certificates && sudo trust extract-compat";
+    if (idChain.includes("suse") || idChain.includes("opensuse")) {
+        return "sudo zypper install ca-certificates && sudo update-ca-certificates";
+    }
+    return "Install ca-certificates via your distro's package manager and retry";
+}
+/**
+ * Run the OAuth TLS preflight and emit a single structured log line if it
+ * fails. Never throws — `runOAuthTlsPreflight` returns a discriminated union
+ * and this function only reads-and-logs.
+ *
+ * Caller is expected to invoke this fire-and-forget (`void`) AFTER the
+ * `"Comis daemon started"` banner so the daemon already counts as healthy
+ * to PM2/systemd by the time the probe resolves.
+ */
+export async function emitOAuthTlsPreflightWarn(logger) {
+    const result = await runOAuthTlsPreflight({ timeoutMs: PREFLIGHT_TIMEOUT_MS });
+    if (result.ok)
+        return;
+    if (result.kind === "tls-cert") {
+        const os = await readOsRelease();
+        const hint = caCertificatesInstallHint(os);
+        logger.warn({
+            submodule: MODULE_NAME,
+            errorKind: "oauth_tls_cert",
+            hint,
+            code: result.code,
+            message: result.message,
+        }, "OAuth TLS preflight failed: system CA bundle cannot validate auth.openai.com");
+        return;
+    }
+    // kind === "network" — transient outage / DNS / firewall. DEBUG only.
+    logger.debug({
+        submodule: MODULE_NAME,
+        errorKind: "oauth_tls_network",
+        message: result.message,
+    }, "OAuth TLS preflight network failure (skipping WARN — likely transient)");
+}

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

@@ -3,13 +3,23 @@
  * dependencies (circuit breaker, budget guard, cost tracker, step counter),
  * and PiExecutor creation.
  * All agents use PiExecutor (pi-coding-agent AgentSession wrapper).
+ *
+ * The live ToolCapabilityPort adapter is constructed inside setupSingleAgent
+ * (this function), NOT at a higher composition site (daemon.ts). Rationale:
+ * skillRegistry is per-agent and the skill-allow/deny precedence chain is
+ * per-agent; a daemon-global adapter cannot satisfy this without breaking
+ * the port interface (would require adding agentId to every method). The
+ * per-agent port is exposed via AgentsResult.toolCapabilityPorts and threaded
+ * into setupTools via the getCapabilityPortForAgent closure on ToolsDeps.
+ *
  * @module
  */
-import { type AppContainer, type InjectionRateLimiter, type PerAgentConfig } from "@comis/core";
+import { type AppContainer, type InjectionRateLimiter, type OAuthCredentialStorePort, type SecretsCrypto, type PerAgentConfig, type ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
+import type Database from "better-sqlite3";
 import type { SqliteMemoryAdapter, createSessionStore } from "@comis/memory";
 import { createBudgetGuard, createCostTracker, createStepCounter, createSessionLifecycle, createComisSessionManager, type AgentExecutor, type ActiveRunRegistry, type ProviderHealthMonitor, type LastKnownModelTracker } from "@comis/agent";
-import { type SkillRegistry, type SkillWatcherHandle } from "@comis/skills";
+import { type SkillRegistry, type SkillWatcherHandle, type McpClientManager } from "@comis/skills";
 type PiSessionAdapter = ReturnType<typeof createComisSessionManager>;
 /** Shared dependencies computed once before the agent loop and passed to each
  *  setupSingleAgent() call. Exposed on AgentsResult so daemon.ts can capture
@@ -59,6 +69,38 @@ export interface SingleAgentDeps {
     backgroundTaskManager?: import("@comis/agent").BackgroundTaskManager;
     /** Callback to send completion notifications for background tasks. */
     backgroundNotifyFn?: import("@comis/agent").NotifyFn;
+    /**
+     * SecretsCrypto engine bound to SECRETS_MASTER_KEY. Defined when the daemon
+     * was started with a valid master key (encrypted-secrets mode). Required
+     * when `appConfig.oauth.storage === "encrypted"` — selectOAuthCredentialStore
+     * fails fast with an operator hint when missing.
+     */
+    secretsCrypto?: SecretsCrypto;
+    /**
+     * Shared better-sqlite3 handle to secrets.db (the SqliteSecretStoreHandle.db
+     * field, plumbed through from daemon.ts after createSqliteSecretStore).
+     * Required when `appConfig.oauth.storage === "encrypted"` so the OAuth
+     * profile adapter can share the existing connection rather than opening a
+     * second handle to the same DB file — eliminates the dual-handle lifecycle
+     * hazards: close-order, schema-init double-execution, prepared-statement
+     * cache fragmentation.
+     */
+    secretsDb?: Database.Database;
+    /**
+     * The daemon-level OAuthCredentialStore handle. Constructed ONCE in
+     * setupAgents() and passed down to every per-agent setupSingleAgent call
+     * AND surfaced on AgentsResult so daemon.ts can thread it into
+     * RpcDispatchDeps for `agents.update` existence checks. Single shared
+     * handle (file backend is stateless on a shared path; encrypted backend
+     * shares the secretsDb connection).
+     */
+    oauthCredentialStore: OAuthCredentialStorePort;
+    /**
+     * Daemon-global MCP client manager. Live-runtime view consumed by the
+     * per-agent ToolCapabilityPort adapter constructed inside setupSingleAgent.
+     * Threaded from daemon.ts; setupMcp runs before setupAgents.
+     */
+    mcpClientManager: McpClientManager;
 }
 /** Per-agent outputs from setupSingleAgent(), matching the Maps in AgentsResult. */
 export interface SingleAgentResult {
@@ -70,6 +112,12 @@ export interface SingleAgentResult {
     piSessionAdapter: PiSessionAdapter;
     skillWatcherHandle?: SkillWatcherHandle;
     skillRegistry: SkillRegistry;
+    /**
+     * Per-agent live ToolCapabilityPort. Constructed via
+     * createToolCapabilityAdapter using this agent's skillRegistry and the
+     * daemon-global mcpClientManager.
+     */
+    toolCapabilityPort: ToolCapabilityPort;
 }
 /** All services produced by the per-agent executor setup phase. */
 export interface AgentsResult {
@@ -97,12 +145,25 @@ export interface AgentsResult {
     skillWatcherHandles: Map<string, SkillWatcherHandle>;
     /** Per-agent skill registries for skills.list RPC method. */
     skillRegistries: Map<string, SkillRegistry>;
+    /**
+     * Per-agent ToolCapabilityPort instances. Consumed by setupTools via the
+     * getCapabilityPortForAgent closure on ToolsDeps; mutated by hot-add /
+     * hot-remove in daemon.ts to keep the parallel map consistent with
+     * skillRegistries.
+     */
+    toolCapabilityPorts: Map<string, ToolCapabilityPort>;
     /** Periodic lock cleanup timer (cleared on shutdown). */
     lockCleanupTimer: ReturnType<typeof setInterval>;
     /** Shared single-agent dependencies for hot-add closure capture. */
     singleAgentDeps: SingleAgentDeps;
     /** Global provider health monitor for daemon-level health metrics */
     providerHealth: ProviderHealthMonitor;
+    /**
+     * Daemon-level OAuthCredentialStore handle. Threaded into
+     * RpcDispatchDeps so agents.update can validate oauthProfiles patches
+     * via has().
+     */
+    oauthCredentialStore: OAuthCredentialStorePort;
 }
 /**
  * Set up a single agent's executor and all supporting services.
@@ -162,6 +223,24 @@ export declare function setupAgents(deps: {
     backgroundTaskManager?: import("@comis/agent").BackgroundTaskManager;
     /** Callback to send completion notifications for background tasks. */
     backgroundNotifyFn?: import("@comis/agent").NotifyFn;
+    /**
+     * SecretsCrypto engine bound to SECRETS_MASTER_KEY. Defined when daemon
+     * was started with a valid master key. Required for
+     * `appConfig.oauth.storage === "encrypted"` mode.
+     */
+    secretsCrypto?: SecretsCrypto;
+    /**
+     * Shared better-sqlite3 handle to secrets.db. Plumbed from daemon.ts where
+     * createSqliteSecretStore now exposes its db field. Required for
+     * `appConfig.oauth.storage === "encrypted"` mode.
+     */
+    secretsDb?: Database.Database;
+    /**
+     * Daemon-global MCP client manager. setupSingleAgent constructs a
+     * per-agent ToolCapabilityPort adapter that closes over this manager.
+     * daemon.ts threads it in after running setupMcp before setupAgents.
+     */
+    mcpClientManager: McpClientManager;
 }): Promise<AgentsResult>;
 /**
  * Resolve "default" model/provider placeholders to concrete values from the