comisai 1.0.42 → 1.0.44

package/node_modules/@comis/daemon/dist/api/types.d.ts

@@ -14,11 +14,11 @@
  *
  * @module
  */
-import type { ChannelPort, VisionProvider, TTSPort, VisionScopeRule, TtsOutputFormat, TtsAutoMode, AppContainer, PerAgentConfig, ProviderEntry, MemoryWriteValidationResult, SecretStorePort, ExecGitFn, ContextStorePort } from "@comis/core";
+import type { ChannelPort, VisionProvider, TTSPort, VisionScopeRule, TtsOutputFormat, TtsAutoMode, AppContainer, PerAgentConfig, ProviderEntry, MemoryWriteValidationResult, SecretStorePort, ExecGitFn, MutableSecretManager } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { MemoryApi, SqliteMemoryAdapter, createEmbeddingQueue } from "@comis/memory";
 import type { CronScheduler, ExecutionTracker, WakeCoalescer, PerAgentHeartbeatRunner } from "@comis/scheduler";
-import type { BrowserService, LinkRunner, McpClientManager } from "@comis/skills";
+import type { BrowserService, LinkRunner, McpClientManager, TokenStore } from "@comis/skills";
 import type { createCostTracker, createStepCounter, createSubAgentRunner } from "@comis/agent";
 import type { ModelCatalog } from "@comis/core";
 import type { createCrossSessionSender } from "@comis/orchestrator";
@@ -64,10 +64,13 @@ export interface SessionsApiDeps {
     };
     crossSessionSender: ReturnType<typeof createCrossSessionSender>;
     subAgentRunner: ReturnType<typeof createSubAgentRunner>;
+    resolveRootRunId?: (sessionKey: import("@comis/core").SessionKey) => string;
     securityConfig: {
         agentToAgent?: {
             enabled?: boolean;
             waitTimeoutMs: number;
+            subAgentToolGroups?: string[];
+            steerInject?: boolean;
         };
     };
     tenantId: string;
@@ -79,6 +82,50 @@ export interface SessionsApiDeps {
     approvalGate?: import("@comis/core").ApprovalGate;
     /** Optional LLM summarizer for session search results. */
     summarizeSession?: (messages: unknown[], query: string) => Promise<string | null>;
+    /** Optional DeliveryQueuePort for the session.history handler's
+     *  deliveryStatus join. Absent in deployments that have no delivery queue
+     *  (no channel adapters) -- the handler then reports every message as
+     *  confirmed (nothing pending to mark). The MCP resources/read surface
+     *  consumes the derived field to filter to CONFIRMED-only messages, but the
+     *  field is also useful to the dashboard / observers. */
+    deliveryQueue?: import("@comis/core").DeliveryQueuePort;
+    /** LCD lossless-store write+run surface — `session.reset_conversation` (164-06)
+     *  calls `deleteConversationLcd` in `runOnConversation` to clear lcd_* rows.
+     *  Optional: the handler fails-closed (throws "LCD store not available") when
+     *  absent, never a silent 0 count. Same instance as MemoryApiDeps; the copy here
+     *  lets session-archive.ts access it without widening to the full MemoryApiDeps slice. */
+    lcdStore?: import("@comis/core").ContextStorePort;
+    /** MemoryPort for session-archive --memory reset (DIST-05). The concrete
+     *  adapter is SqliteMemoryAdapter (which implements MemoryPort) — it is the
+     *  SAME object as MemoryApiDeps.memoryAdapter, threaded onto this slice at the
+     *  composition root (daemon.ts) so the session.reset_conversation handler can
+     *  call `deleteBySessionKey` without widening to the full MemoryApiDeps slice.
+     *  Optional so existing handler tests construct deps without it; when absent the
+     *  --memory flag logs a not-available WARN and clears LCD + sessionStore only. */
+    memoryPort?: import("@comis/core").MemoryPort;
+    /** MemoryConsolidationStore for --memory consolidated-observation unlink /
+     *  --purge-derived (DIST-05). The SAME instance as MemoryApiDeps.consolidationStore.
+     *  Optional for the same handler-test reason; absent ⇒ the unlink/purge steps are
+     *  skipped (the by-session memory delete itself still runs). */
+    consolidationStore?: import("@comis/core").MemoryConsolidationStore;
+    /** Runtime-layer (L3) destroy for `session.reset_conversation` — live finding
+     *  2026-06-11: clearing LCD + sessionStore alone resurrects (the surviving pi
+     *  runtime JSONL re-ingests wholesale via the lcd-ingest epoch rebase). Wired
+     *  at the composition root from `createConversationReset(...).destroyRuntimeSession`
+     *  bound to the default agent. Returns true when an adapter destroy ran.
+     *  Optional: absent ⇒ the handler reports `runtimeSessionDestroyed: false`
+     *  and WARNs with the resurrection consequence (honest degradation). */
+    destroyRuntimeSession?: (formattedSessionKey: string) => Promise<boolean>;
+    /** Executor session-scoped state cleanup (175-REVIEW CR-02): wired at the
+     *  composition root (daemon.ts) to @comis/agent's clearSessionState — the
+     *  single authoritative path that drops the per-key tool-schema snapshots,
+     *  the GBNF-02 strip-retry once-gate, JIT-guide delivery, cache latches,
+     *  etc. session.reset_conversation / session.delete call it so a reset or
+     *  recreated session does not inherit the old key's executor state (the
+     *  strip once-gate would otherwise terminal-fail the "fresh" session's
+     *  first grammar-400 with zero repair attempts). Optional so existing
+     *  handler tests construct deps without it; absent ⇒ skipped. */
+    clearAgentSessionState?: (formattedSessionKey: string) => void;
 }
 /**
  * Dependencies for memory-handlers + context-handlers
@@ -101,28 +148,72 @@ export interface MemoryApiDeps {
     /** memory-handlers reads deps.logger.warn/info; context-handlers reads
      *  deps.logger.info/warn. Required (matches other slices for multi-extends parity). */
     logger: ComisLogger;
-    contextStore?: ContextStorePort;
-    contextEngineConfig?: {
-        maxRecallsPerDay: number;
-        maxExpandTokens: number;
-        recallTimeoutMs: number;
-    };
-    /** context-handlers reads deps.store. Aliases contextStore. */
-    store?: ContextStorePort;
-    /** context-handlers reads deps.config (recall-quota / token-cap / timeout). Aliases contextEngineConfig. */
-    config?: {
-        maxRecallsPerDay: number;
-        maxExpandTokens: number;
-        recallTimeoutMs: number;
-    };
-    /** context-handlers reads deps.resolveConversationId. */
-    resolveConversationId?: (sessionKey: string) => string | undefined;
-    /** context-handlers reads deps.rpcCall for ctx_recall -> session.spawn self-dispatch. */
-    rpcCall?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
     /** Embedding cache stats accessor for memory.embeddingCache RPC */
     embeddingCacheStats?: () => import("@comis/memory").EmbeddingCacheStats;
     /** Embedding circuit breaker state accessor for memory persistence operations. */
     embeddingCircuitBreakerState?: () => import("@comis/agent").CircuitState;
+    /** Consolidation store — the `memory.observations` handler reads provenance
+     *  via `listObservations(agentId, tenantId, limit)` (scoped). Same port type
+     *  setup-memory builds; optional so existing handler tests construct deps
+     *  without it. */
+    consolidationStore?: import("@comis/core").MemoryConsolidationStore;
+    /** Entity store — the `memory.entities` handler reads the entity graph via
+     *  `listEntities(agentId, tenantId, limit)` (scoped). Optional for the
+     *  same backward-compat reason. */
+    entityStore?: import("@comis/core").MemoryEntityStore;
+    /** Live in-process recall counters. The `memory.recall_stats`
+     *  handler reads `snapshot()`; wired from `wireRecallCounters(eventBus)` at
+     *  the composition root. Optional — when unset the handler returns zeroed
+     *  counters (the gauge is process-lifetime, resets on restart). */
+    recallCounters?: {
+        snapshot: () => import("@comis/observability").RecallCountersSnapshot;
+    };
+    /** Data directory (e.g. ~/.comis) for the `memory.recall_trace` JSONL read.
+     *  The handler resolves `<dataDir>/logs/recall-trace.jsonl` via
+     *  `resolveRecallTraceFilePath`. Optional — mirrors ObservabilityApiDeps.dataDir;
+     *  defaults to ~/.comis at handler-construction time when omitted. */
+    dataDir?: string;
+    /** The diagnostics.recallTrace.enabled gate (live finding 2026-06-11) — the
+     *  `memory.recall_trace` handler reports it as `tracingEnabled` and, on an
+     *  empty result, hints WHY (recorder disabled vs no matching traces yet)
+     *  instead of a silent `{records: []}`. Optional — absent reads as false
+     *  (the schema default for the opt-in recorder). */
+    recallTraceEnabled?: boolean;
+    /** The INJECTED query-time dialectic synthesis seam (the `createDialecticSeam`
+     *  output, built + injected from a cheap resolved model + key). The
+     *  `memory.ask` handler calls it ONLY on the non-empty-recall path (empty recall ⇒
+     *  abstain in CODE without the seam call). Optional so existing handler tests construct
+     *  deps without it; the handler abstains gracefully when absent (no key / not wired). */
+    dialecticSeam?: (agentId: string, question: string, groundingText: string) => Promise<import("@comis/agent").DialecticParsed>;
+    /** A per-agent recall factory returning the FULL `createMemoryRecall` orchestrator built
+     *  with the daemon's store set + the INVOKING agent's RagConfig (re-reads the calling
+     *  agent's `rag`, not the default agent's). The `memory.ask` handler runs THIS over the
+     *  question — NOT `deps.memoryApi.search` (which bypasses the trust filter). Injecting the
+     *  builder keeps the 8-store deps off this slice. Optional so existing handler tests construct
+     *  deps without it; the handler abstains when absent. */
+    buildDialecticRecall?: (agentId: string) => import("@comis/agent").MemoryRecall;
+    /** The per-agent dialectic grounding-set HARD ceiling resolver (`dialectic.maxRecall`, default
+     *  10) — the DoS bound on the synthesis LLM input. The `memory.ask` handler calls
+     *  it with the INVOKING agentId and clamps the caller-controlled `limit` to `[1, ceiling]`: a
+     *  huge/negative `limit` can never flood the prompt or negative-slice the grounding. A function
+     *  (not a scalar) so each agent's OWN bound is honored. Optional so existing handler tests omit
+     *  it; the handler falls back to the schema default (10) when absent. */
+    dialecticMaxRecall?: (agentId: string) => number;
+    /** Suspicious-pattern telemetry callback for the dialectic grounding — surfaced to
+     *  `wrapExternalContent` so a detected injection in recalled content is reported (the SAME
+     *  hook rag-retriever threads). Optional; absent ⇒ no telemetry (sanitization still runs). */
+    onSuspiciousContent?: import("@comis/core").WrapExternalContentOptions["onSuspiciousContent"];
+    /** LCD lossless-store read surface — the `context.tree` handler resolves a
+     *  conversation's context_items + summaries via `getContextItems` /
+     *  `getSummaries` (R4 agent+tenant scoped). The SAME ContextStorePort
+     *  setup-memory builds (`lcdStore`). Optional so existing handler tests build
+     *  deps without it; the context.* handlers fail-closed (empty result) when absent. */
+    lcdStore?: import("@comis/core").ContextStorePort;
+    /** LCD operator-browse read surface — the `context.conversations` handler
+     *  enumerates the agent's distinct conversations via `listConversations`
+     *  (R4 agent+tenant scoped). Built by setup-memory (`createLcdBrowseStore`).
+     *  Optional for the same handler-test reason; absent ⇒ empty result. */
+    contextBrowse?: import("@comis/core").ContextBrowsePort;
 }
 /**
  * Dependencies for channel-handlers + message-handlers
@@ -130,9 +221,8 @@ export interface MemoryApiDeps {
  */
 export interface ChannelsApiDeps {
     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. */
+    /** Resolves daemon NormalizedMessage.id UUIDs back to platform-native message
+     *  ids for message.delete/edit/react. Optional when channel adapters are disabled. */
     inboundMessageIdResolver?: import("../wiring/inbound-message-id-resolver.js").InboundMessageIdResolver;
     channelConfig: Record<string, {
         enabled: boolean;
@@ -143,13 +233,10 @@ export interface ChannelsApiDeps {
     mediaDir?: string;
     onGatewayAttachment?: (channelId: string, marker: string) => void;
     deliveryQueue?: import("@comis/core").DeliveryQueuePort;
-    /** DeliveryService constructed once at the daemon composition root
-     *  (setup-channels.ts). Passed through to createMessageHandlers so
-     *  `message.send` / `message.reply` use the method form
-     *  `deps.deliveryService.deliverToChannel(...)`. */
+    /** DeliveryService constructed once at the composition root (setup-channels.ts); createMessageHandlers calls `deps.deliveryService.deliverToChannel(...)`. */
     deliveryService: import("@comis/core").DeliveryService;
     healthMonitor?: import("@comis/channels").ChannelHealthMonitor;
-    channelPlugins?: Map<string, import("@comis/core").ChannelPluginPort>;
+    channelPlugins: Map<string, import("@comis/core").ChannelPluginPort>;
     /** message-handlers reads deps.defaultAgentId, deps.defaultWorkspaceDir,
      *  deps.workspaceDirs, deps.logger. channel-handlers reads deps.persistDeps. */
     defaultAgentId: string;
@@ -157,6 +244,12 @@ export interface ChannelsApiDeps {
     workspaceDirs: Map<string, string>;
     logger: ComisLogger;
     persistDeps?: PersistToConfigDeps;
+    /** Phase 213 (QUOTA-01/02): the bounded-autonomy service. message.send/reply/react consult `tryOutward` (origin/grant/per-hour/volume) before deliver. Optional; absent ⇒ inert. A daemon-initiated send (no `_agentId`) is never gated. */
+    boundedAutonomy?: import("../autonomy/bounded-autonomy.js").BoundedAutonomy;
+    /** Phase 216 ONCE-01/02: tree-stable rootRunId resolver (same as SessionsApiDeps.resolveRootRunId, already spread into the flat dispatch deps). message.send/reply/react derive the outward-ledger idempotency key from it; absent ⇒ the wrap is a pass-through. */
+    resolveRootRunId?: (sessionKey: import("@comis/core").SessionKey) => string;
+    /** Phase 216 ONCE-01: the three-state outward ledger; absent ⇒ no exactly-once wrap (older/non-autonomy daemon) */
+    outwardLedger?: import("@comis/core").OutwardSendLedgerPort;
 }
 /**
  * Dependencies for agent-handlers + model-handlers + provider-handlers
@@ -164,8 +257,10 @@ export interface ChannelsApiDeps {
  */
 export interface AgentsApiDeps {
     suspendedAgents: Set<string>;
-    /** Hot-add callback passed through to agent handlers for runtime agent creation without restart. */
-    hotAdd?: (agentId: string, config: PerAgentConfig) => Promise<void>;
+    /** Hot-add callback passed through to agent handlers for runtime agent creation without restart.
+     *  `rawRerankEnabled` is the RAW (pre-Zod-default) rag.rerank.enabled from the RPC input so the
+     *  hot-added agent's effective-rerank precedence distinguishes unset from explicit-off. */
+    hotAdd?: (agentId: string, config: PerAgentConfig, rawRerankEnabled?: boolean | undefined) => Promise<void>;
     /** Hot-remove callback passed through to agent handlers for runtime agent deletion without restart. */
     hotRemove?: (agentId: string) => Promise<void>;
     modelCatalog: ModelCatalog;
@@ -191,6 +286,7 @@ export interface AgentsApiDeps {
 /**
  * Dependencies for cron-handlers + graph-handlers + heartbeat-handlers + subagent-handlers
  * (cron.list/run, graph.list/run, heartbeat.list/run, subagent.list).
+ * @optional-field-count: 14 — daemon-internal orchestration-plane slice; every optional gates on a daemon-global resource (graph coordinator, heartbeat runner, leaseManager/durableRuns, the Phase-217 autonomy plane denialBreaker/evictRegistry/escalate). daemon.ts supplies each from the cap-endpoint handle or config; a non-autonomy boot leaves them absent (byte-identical pre-217). Keep until a structural slice split.
  */
 export interface OrchestratorApiDeps {
     getAgentCronScheduler: (agentId: string) => CronScheduler;
@@ -199,9 +295,7 @@ export interface OrchestratorApiDeps {
     wakeCoalescer: WakeCoalescer;
     graphCoordinator?: import("../graph/graph-coordinator.js").GraphCoordinator;
     namedGraphStore?: import("@comis/memory").NamedGraphStore;
-    /** Node type registry for driver config validation. The legacy GraphHandlerDeps
-     *  declared an inline shape; the @comis/scheduler / graph-local
-     *  NodeTypeRegistry type is structurally compatible. */
+    /** Node type registry for driver config validation (structurally compatible with the graph-local / @comis/scheduler NodeTypeRegistry). */
     nodeTypeRegistry?: import("../graph/node-type-registry.js").NodeTypeRegistry;
     perAgentRunner?: PerAgentHeartbeatRunner;
     globalHeartbeatConfig?: Record<string, unknown>;
@@ -218,15 +312,23 @@ export interface OrchestratorApiDeps {
         agentToAgent?: {
             enabled?: boolean;
             waitTimeoutMs: number;
+            subAgentToolGroups?: string[];
+            steerInject?: boolean;
         };
     };
-    /** graph / subagent handlers read deps.logger.info/warn. Required
-     *  (matches other slices for multi-extends parity; DaemonApiDeps.logger is required). */
+    /** graph / subagent handlers read deps.logger.info/warn. Required (multi-extends parity; DaemonApiDeps.logger is required). */
     logger: ComisLogger;
     /** graph-handlers reads deps.dataDir for graph-runs output. */
     dataDir?: string;
-    /** subagent-handlers reads deps.subAgentRunner.list/kill/steer. */
+    /** subagent-handlers reads deps.subAgentRunner.list/kill/steer; autonomy-handlers (213-06) reads killByRootRun for run.kill. */
     subAgentRunner: ReturnType<typeof createSubAgentRunner>;
+    /** autonomy-handlers (213-06 REVOKE-01/03) revoke fan-outs. Optional: Plan 07 wires it; absent ⇒ handlers not registered. */ leaseManager?: import("@comis/infra").LeaseManager;
+    /** Phase 216 DUR-03: the durable-run store — autonomy-handlers ALSO calls invalidateForRevoke(rootRunId) on lease.revoke/run.kill so a restart cannot resume pre-revoke caps. Optional; absent ⇒ the persisted record is not poisoned (only matters when durability is enabled, which is when Plan 07 wires it). */ durableRuns?: import("@comis/core").DurableRunPort;
+    denialBreaker?: import("../autonomy/denial-breaker.js").DenialBreaker;
+    evictRegistry?: import("../autonomy/evict-registry.js").EvictRegistry;
+    escalate?: import("../autonomy/durable-resume-engine.js").NotifyFn;
+    eventBus?: AppContainer["eventBus"];
+    getProviderCapabilityClass?: (provider: string | undefined) => import("@comis/agent").CapabilityClass | undefined;
 }
 /**
  * Dependencies for workspace-handlers + browser-handlers + approval-handlers
@@ -265,6 +367,33 @@ export interface WorkspaceApiDeps {
     eventBus?: AppContainer["eventBus"];
     /** mcp-handlers reads deps.secretManager?.has for env-ref validation. */
     secretManager?: import("@comis/core").SecretManager;
+    /** mcp-handlers reads deps.secretStore for static-secret header extraction.
+     *  Always wired (selectSecretStore returns a store for all modes).
+     *  Same shape as AuthApiDeps.secretStore / ConfigApiDeps.secretStore
+     *  so the ApiDispatchDeps multi-extends remains well-formed. */
+    secretStore: SecretStorePort;
+    /** mcp-handlers reads deps.persistDeps for YAML writes via persistMcpServers.
+     *  Same shape as ChannelsApiDeps.persistDeps / AgentsApiDeps.persistDeps /
+     *  OrchestratorApiDeps.persistDeps so the ApiDispatchDeps multi-extends
+     *  remains well-formed. */
+    persistDeps?: PersistToConfigDeps;
+    /**
+     * Factory for the per-server MCP-OAuth token store. mcp-handlers reads
+     * this to check whether a token already exists for an `auth:"oauth"`
+     * server before attempting `manager.connect` — when no token is present
+     * yet, the daemon short-circuits to `needs_oauth_login` instead of
+     * driving the SDK's DCR with empty `redirect_uris`. Same shape as
+     * `McpOauthHandlerDeps.createTokenStore` so both handlers can share one
+     * process-wide token-store factory. Optional — undefined skips the
+     * pre-check (existing tests construct deps without it).
+     *
+     * The factory itself MAY return undefined: in `env` storage mode
+     * `selectMcpTokenStore` yields no writable store, so the daemon's pass-through
+     * (`() => boot.mcpTokenStore`) returns undefined. Consumers MUST guard the
+     * returned value (treat undefined as "no token store" / fail loudly) rather
+     * than dereferencing it.
+     */
+    createTokenStore?: () => TokenStore | undefined;
 }
 /**
  * Dependencies for config-handlers + env-handlers
@@ -274,6 +403,14 @@ export interface ConfigApiDeps {
     container: AppContainer;
     configPaths: string[];
     defaultConfigPaths: string[];
+    /**
+     * Daemon build version (`packages/daemon/package.json`), surfaced on the
+     * `gateway.status` RPC response so `comis doctor`'s version-skew check can
+     * detect a stale CLI talking to a newer daemon. Read once at boot
+     * (`setupLogging`) and threaded here via the dispatch deps; "unknown" if the
+     * package read failed.
+     */
+    daemonVersion: string;
     configGitManager?: import("@comis/core").ConfigGitManager;
     configWebhook?: {
         url?: string;
@@ -289,17 +426,33 @@ export interface ConfigApiDeps {
      *  AgentsApiDeps.oauthCredentialStore + AuthApiDeps.oauthCredentialStore so the
      *  ApiDispatchDeps multi-extends remains well-formed. */
     oauthCredentialStore?: import("@comis/core").OAuthCredentialStorePort;
-    /** env-handlers reads deps.secretStore for the encrypted-secret
-     *  write path. Same shape as AuthApiDeps.secretStore so the ApiDispatchDeps
-     *  multi-extends remains well-formed. */
-    secretStore?: SecretStorePort;
+    /** env-handlers reads deps.secretStore for the secret write path.
+     *  Always wired (selectSecretStore returns a store for all modes).
+     *  Same shape as AuthApiDeps.secretStore so the ApiDispatchDeps multi-extends remains well-formed. */
+    secretStore: SecretStorePort;
+    /** Daemon-owned write handle over the shared SecretManager backing Map.
+     *  Used by env-handlers to upsert new-name writes live (additive no-restart).
+     *  MUST NOT appear on AppContainer. Required — always wired at the composition root. */
+    mutableSecretManager: MutableSecretManager;
+    /**
+     * When `false`, config-handlers skip the config-audit JSONL append
+     * at the config.patch RPC handler call sites (config-write.ts:124,
+     * 390). Default-true semantics — when `undefined`, the audit hook
+     * runs. Wired from
+     * `container.config.diagnostics?.configAudit?.enabled !== false`
+     * at the rpc-dispatch.ts composition root.
+     */
+    auditEnabled?: boolean;
 }
 /**
  * Dependencies for auth-handlers + secrets-handlers + token-handlers
  * (auth.oauth.list/connect, secrets.get/set, tokens.list/create/revoke).
  */
 export interface AuthApiDeps {
-    secretStore?: SecretStorePort;
+    secretStore: SecretStorePort;
+    /** Daemon-owned write handle over the shared SecretManager backing Map.
+     *  Used by secrets-handlers to upsert/remove live (additive no-restart). Required. */
+    mutableSecretManager: MutableSecretManager;
     tokenRegistry: {
         list(): Array<{
             id: string;
@@ -350,6 +503,18 @@ export interface AuthApiDeps {
  * Dependencies for media-handlers + image-handlers
  * (media.transcribe/extract_document/tts, image.generate).
  */
+/** OBS-03 (196): the boot-resolved voice (STT/TTS) selection threaded to the
+ *  daemon RPC handlers for the trajectory emit — `provider`/`keyless`/`source` rung
+ *  + the collected `onSkip` reasons (the OBS-03 selection observability). Resolved
+ *  ONCE at boot by `setupMedia` from the SAME `SttSelection`/`TtsSelection` the
+ *  adapter construction used (no second source of truth). Optional — a selector-less
+ *  boot leaves it undefined and the handler derives provider+keyless from config. */
+export interface ResolvedVoiceSelection {
+    provider: string;
+    keyless: boolean;
+    source: "explicit" | "keyless-local" | "follow-main-key" | "fallback";
+    onSkip?: string[];
+}
 export interface MediaApiDeps {
     visionRegistry?: Map<string, VisionProvider>;
     mediaConfig: {
@@ -361,6 +526,13 @@ export interface MediaApiDeps {
             defaultScopeAction: "allow" | "deny";
             defaultProvider?: string;
         };
+        /** OBS-03 (196): the STT (transcription) config slice. The runtime object is the
+         *  full `integrations.media` config, so this is already present; declared here so
+         *  `media.test.stt` reports the STT provider (the :595 reads-TTS RED-proof fix). */
+        transcription: {
+            provider?: string;
+            model?: string;
+        };
         tts: {
             provider?: string;
             autoMode: TtsAutoMode;
@@ -385,7 +557,109 @@ export interface MediaApiDeps {
         logger: ComisLogger;
         /** Direct channel delivery -- resolve adapter by channel type. */
         getChannelAdapter: (channelType: string) => Pick<import("@comis/core").ChannelPort, "sendAttachment"> | undefined;
+        /** RES-01: resolve the agent's main provider in lockstep with the
+         *  completion path (I4 — delegates to the same resolveAgentModel). The
+         *  handler uses this only for observability + lockstep verification; the
+         *  provider INSTANCE is selected at wiring time (setup-image-provider.ts),
+         *  never re-derived here (no second source of truth). */
+        resolveAgentMainProvider: (agentId: string) => {
+            providerId: string;
+        };
+        /** IN-01 (185): resolve a `reference_image` workspace file path under the
+         *  caller's agent dir (safePath confinement). Mirror MediaApiDeps:572-573. */
+        workspaceDirs: Map<string, string>;
+        defaultWorkspaceDir: string;
+        /** DEL-01 (186): the per-agent persistence getter. Persists the generated
+         *  image buffer to the agent's confined workspace (`~/.comis/workspace/media/
+         *  photos/`) via MediaPersistenceService — replacing the ephemeral tmpdir
+         *  write+delete. The agentId resolves the workspace inside the getter
+         *  (mirrors the screenshot precedent at setup-tools.ts:305). Never throws —
+         *  returns `err` on a persistence failure so the handler falls through to the
+         *  base64 fallback. `PersistedFile` is on the `@comis/skills/tools` subpath
+         *  (NOT the bare barrel — the proven import path, setup-tools.ts:69). */
+        persist: (agentId: string, buffer: Buffer, opts: {
+            mediaKind: "image";
+            mimeType: string;
+        }) => Promise<import("@comis/shared").Result<import("@comis/skills/tools").PersistedFile, Error>>;
+        /** OBS-04 (186): the per-session trajectory recorder registry. The handler
+         *  resolves the recorder by `_callerSessionKey` and direct-emits the 4
+         *  image.* lifecycle events via `getRecorder(sessionKey)?.recordEvent(...)`
+         *  (the comis-session-manager.ts:298 precedent — the daemon RPC context has
+         *  NO eventBus bridge). Optional: `getRecorder?.()` no-ops to a non-crash on
+         *  a boot mode without a registry, and a null recorder is skipped. Read off
+         *  the BootContext `c.trajectoryRegistry` (already a field). */
+        trajectoryRegistry?: import("@comis/observability").SessionTrajectoryHandleRegistry;
+        /** SEC-02 (186): the per-agent/hour USD cost ceiling. Optional — undefined
+         *  when `integrations.media.imageGeneration.maxCostPerHourUsd` is unset, in
+         *  which case the ceiling check is skipped and only the count rate limit
+         *  applies (no regression). When present, the handler pre-checks
+         *  `canSpend(agentId)` BEFORE provider.execute (block with quota_exceeded)
+         *  and `record(agentId, costUsd)` AFTER a successful generation. The count
+         *  rate limiter (maxPerHour) is RETAINED and orthogonal. Constructed in
+         *  buildImageGenBundle (main-helpers.ts), gated on maxCostPerHourUsd. */
+        costLimiter?: import("./image-cost-limiter.js").ImageCostLimiter;
+        /** OBS-03 (186, optional secondary): the typed event bus. After a successful
+         *  generation with a non-zero costUsd the handler emits a synthetic
+         *  `observability:token_usage` (tokens all 0, cost.total = costUsd) so the
+         *  image cost reaches sharedCostTracker + the token_usage SQLite table +
+         *  billing — the BINDING OBS-03 assertion is the trajectory `image.generated`
+         *  cost-carry (Route a), this is the secondary. Same shape as the
+         *  MemoryApiDeps / WorkspaceApiDeps eventBus so the slices unify. */
+        eventBus?: AppContainer["eventBus"];
+    };
+    videoHandlerDeps?: import("./video-handler-deps.js").VideoHandlerDepsShape;
+    /** Video status deps (Phase 189 / Plan 03 — JOB-04). The READ side of the
+     *  async lifecycle: `video.status` reads the agent-scoped job store the poller
+     *  writes. Lives in the same sibling leaf module (`./video-handler-deps.ts`) to
+     *  keep THIS file under the 800-line cap; the dispatcher passes it through to
+     *  createVideoStatusHandlers. */
+    videoStatusHandlerDeps?: import("./video-handler-deps.js").VideoStatusHandlerDepsShape;
+    /** VIS-01 (187): resolve the agent's MAIN provider id in lockstep with the
+     *  completion path (I4) — used for the obs label + the resolveVisionPath
+     *  input. The provider INSTANCE/creds are resolved inside mainProviderVision
+     *  (no second source of truth — the 183 firewall). Top-level (the vision
+     *  handlers read `deps.X` directly, unlike image's nested imageHandlerDeps).
+     *  Optional — absent on a boot mode without vision wiring → the handler treats
+     *  the main as "unknown" (not vision-capable) and falls to the registry. */
+    resolveAgentMainProvider?: (agentId: string) => {
+        providerId: string;
+    };
+    /** VIS-01 (187): resolve the agent's MAIN model id, the SAME way
+     *  buildMediaVisionBundle resolves it (the single resolveAgentModel source of
+     *  truth). The handler-side vision gate computes `isVisionCapable(getModel(
+     *  main.providerId, mainModelIdFor(agentId)))` to short-circuit a non-vision
+     *  main WITHOUT an LLM call (the setup-channels-media.ts:135 try/catch dance).
+     *  Optional/undefined → the gate is conservative (not vision-capable). */
+    mainModelIdFor?: (agentId: string) => string | undefined;
+    /** VIS-01 (187): the main-provider vision bridge — ONE bounded completeSimple
+     *  over a multimodal [text,image] message on the agent's MAIN model, reusing
+     *  the main creds (no separate vision key). Returns the description + optional
+     *  costUsd, or an honest err (errorKind). The handler tries this FIRST when
+     *  isVisionCapable + creds; never re-derives selection. Optional — absent on a
+     *  boot mode without vision wiring → the handler falls to the registry. */
+    mainProviderVision?: {
+        describeImage(buffer: Buffer, prompt: string, mimeType: string, agentId: string): Promise<import("@comis/shared").Result<import("@comis/core").VisionResult & {
+            costUsd?: number;
+        }, Error>>;
     };
+    /** VIS-04 (187, Plan 03 fills the emits): the per-session trajectory recorder
+     *  registry — the handler resolves getRecorder(_callerSessionKey) and direct-
+     *  emits the media.vision.* lifecycle (the comis-session-manager.ts:298
+     *  precedent — no eventBus bridge in the daemon RPC context). Declared now;
+     *  the emits land in Plan 03. */
+    trajectoryRegistry?: import("@comis/observability").SessionTrajectoryHandleRegistry;
+    /** OBS-03 (196): the boot-resolved voice selections the daemon voice handlers
+     *  thread onto the `media.stt.*`/`media.tts.*` trajectory via `wireVoiceObs`.
+     *  Optional — undefined on a selector-less boot (handler derives from config). */
+    voiceSelection?: {
+        stt?: ResolvedVoiceSelection;
+        tts?: ResolvedVoiceSelection;
+    };
+    /** OBS-04 (196): the obs store the voice obs inserts a `voice_degraded`
+     *  health_signal row into on a STT/TTS failure (feeds the `comis fleet`
+     *  voice_health finding). Same instance as `ObservabilityApiDeps.obsStore`;
+     *  declared here so the voice handlers' deps slice can read it. Optional. */
+    obsStore?: import("@comis/memory").ObservabilityStore;
     /** media-handlers reads deps.workspaceDirs / deps.defaultWorkspaceDir
      *  / deps.defaultAgentId for STT / vision / link-processing file paths.
      *  Same shape as ChannelsApiDeps + WorkspaceApiDeps for ApiDispatchDeps multi-extends parity. */
@@ -397,8 +671,9 @@ export interface MediaApiDeps {
     logger: ComisLogger;
 }
 /**
- * Dependencies for obs-handlers
- * (obs.usage/billing/diagnostics/budget).
+ * Dependencies for obs-handlers (obs.usage/billing/diagnostics/budget/spend).
+ * @optional-field-count: 14 — a composition-root deps bag; each optional field is a
+ * distinct obs source present iff wired (absent ⇒ honest-degrade). +1 per new source (spendSnapshot 179; durableRuns 220-03 autonomy).
  */
 export interface ObservabilityApiDeps {
     diagnosticCollector: DiagnosticCollector;
@@ -412,33 +687,60 @@ export interface ObservabilityApiDeps {
             perDay: number;
         };
     }>;
+    /** WEBUI-02 (179-04): reader for the LIVE daemon-wide spend the kill-switch enforces (locked
+     *  A1 — `getSnapshot()`, NOT the lagging SQL) + the ceilings, so `obs.spend.snapshot` computes
+     *  headroom = ceiling − spend (the `budgetGuards` precedent). Absent ⇒ off → `enabled:false`. @optional-field */
+    spendSnapshot?: () => {
+        perAgent: ReadonlyMap<string, number>;
+        perTenant: ReadonlyMap<string, number>;
+        global: number;
+        ceilings: {
+            perAgentUsd: number | null;
+            perTenantUsd: number | null;
+            daemonGlobalUsd: number | null;
+        };
+    };
     obsStore?: import("@comis/memory").ObservabilityStore;
     startupTimestamp?: number;
     sharedCostTracker?: {
         reset(): number;
     };
     contextPipelineCollector?: import("../observability/context-pipeline-collector.js").ContextPipelineCollector;
-    /** obs-handlers emits `observability:reset` on obs.reset. Same
-     *  shape as MemoryApiDeps.eventBus / WorkspaceApiDeps.eventBus so the
-     *  ApiDispatchDeps multi-extends remains well-formed. */
+    /** obs-handlers emits `observability:reset` on obs.reset. (Shapes below mirror the
+     *  matching MemoryApiDeps/WorkspaceApiDeps/AgentsApiDeps slices so the ApiDispatchDeps
+     *  multi-extends stays well-formed.) */
     eventBus?: AppContainer["eventBus"];
-    /** obs-handlers reads deps.agents?.[id]?.budgets for budget
-     *  snapshot RPCs. Same shape as AgentsApiDeps.agents / OrchestratorApiDeps.agents
-     *  / WorkspaceApiDeps.agents so the ApiDispatchDeps multi-extends remains
-     *  well-formed. obs-handlers tolerates the broader PerAgentConfig record
-     *  structurally (only `.budgets?` is read). */
+    /** obs-handlers reads deps.agents?.[id]?.budgets for budget snapshot RPCs (tolerates
+     *  the broader PerAgentConfig structurally — only `.budgets?` is read). */
     agents: Record<string, PerAgentConfig>;
-    /** obs-handlers exposes embedding cache stats via the
-     *  memory.embeddingCache RPC. Same shape as MemoryApiDeps.embeddingCacheStats
-     *  so the ApiDispatchDeps multi-extends remains well-formed. */
+    /** obs-handlers exposes embedding cache stats via the memory.embeddingCache RPC. */
     embeddingCacheStats?: () => import("@comis/memory").EmbeddingCacheStats;
-    /** obs-handlers exposes embedding circuit breaker state.
-     *  Same shape as MemoryApiDeps.embeddingCircuitBreakerState so the
-     *  ApiDispatchDeps multi-extends remains well-formed. */
+    /** obs-handlers exposes embedding circuit breaker state. */
     embeddingCircuitBreakerState?: () => import("@comis/agent").CircuitState;
     /** obs-handlers reads deps.tokenTracker for cache stats RPC.
      *  Only used by obs-handlers; no cross-slice collision. */
     tokenTracker?: import("../observability/token-tracker.js").TokenTracker;
+    /** Directory containing session-index.YYYY-MM-DD.jsonl files (obs.trace.* handlers).
+     *  Defaults to $HOME/.comis at handler-construction time when omitted; optional so
+     *  existing handler tests can pass {} for deps. */
+    dataDir?: string;
+    /**
+     * Injected ClockPort for obs.fleet.health's `sinceHours` -> `sinceMs`
+     * conversion (the globals gate forbids Date.now()/new Date() in the
+     * handler/assembler). Populated by `buildRpcDispatchDeps` in daemon.ts
+     * (Phase 161-02) from `boot.clock`. Optional preserves existing handler
+     * tests that pass {} for deps; the fleet handler asserts `deps.clock!`
+     * because 161-02 always populates it, and the fleet tests inject a fakeClock.
+     */
+    clock?: import("@comis/core").ClockPort;
+    /** FLEET-01/02/04 (220-03): the durable-run store the fleet assembler reads (`countByStatus`) for the autonomy block. Soft-fail (obsStore? precedent): absent ⇒ the block is OMITTED (offline CLI / non-durability boot). Wired on the SAME object as obsStore/clock by buildRpcDispatchDeps (daemon.ts:893). @optional-field */ durableRuns?: import("@comis/core").DurableRunPort;
+    /**
+     * DI seam for the bundle pipeline.
+     * Tests inject a stub that returns ok({ bundleDir: "/tmp/bundle", ... }).
+     * Production wires the real exportTrajectoryBundle from @comis/observability.
+     * Optional preserves backward compatibility.
+     */
+    exportTrajectoryBundle?: typeof import("@comis/observability").exportTrajectoryBundle;
 }
 /**
  * Dependencies for daemon-handlers

package/node_modules/@comis/daemon/dist/api/veo-adapter.d.ts

@@ -0,0 +1,19 @@
+import type { VideoGenerationPort } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+/** Options bounding the result download (WR-01). Copied from fal-adapter.ts. */
+export interface VideoFetchResultOpts {
+    signal?: AbortSignal;
+    maxBytes?: number;
+}
+/**
+ * Create a Google Veo video-generation adapter over `@google/genai`.
+ *
+ * @param opts - `apiKey` (passed ONLY to `new GoogleGenAI` + the `&key=` download
+ *               URL, never logged), an optional `model` override, and an optional
+ *               logger (used for `{ model, jobId, step }` shapes only).
+ */
+export declare function createVeoVideoAdapter(opts: {
+    apiKey: string;
+    model?: string;
+    logger?: ComisLogger;
+}): VideoGenerationPort;