comisai 1.0.42 → 1.0.45

package/node_modules/@comis/daemon/dist/api/image-handlers.js

@@ -25,11 +25,25 @@
  *
  * @module
  */
-import { tmpdir } from "node:os";
-import { randomUUID } from "node:crypto";
-import { writeFile, unlink } from "node:fs/promises";
-import { ImageGenerateContract, safePath, stripInternalFields, systemGetEnv } from "@comis/core";
-import { suppressError } from "@comis/shared";
+import { IMAGE_ERR_TO_LOG, ImageGenerateContract, isValidImageModel, listImageModels, stripInternalFields, systemGetEnv, systemNowMs, } from "@comis/core";
+// IN-01 reference-image resolution (SSRF + path-traversal + size floor) is now a
+// SHARED module reused by video-handlers' SEC-03 `image_url` — extracted verbatim
+// from this file so both handlers resolve through the same guard.
+import { resolveReferenceImage } from "./media-reference-resolver.js";
+/**
+ * Read an operator-facing `hint` off a provider error if it carries one.
+ *
+ * The pi-image-adapter surfaces failures as a typed `ImageGenError` carrying a
+ * knob-naming `hint` (the RES-03 honest-unavailable carrier — see
+ * `pi-image-adapter.ts`). This is a narrow duck-type guard (not an `instanceof`)
+ * so the handler does not import the adapter module — it only forwards a
+ * `string` hint when present. A plain `Error` has no `hint`, so the legacy
+ * `{ success: false, error }` shape is preserved for those paths.
+ */
+function extractImageHint(error) {
+    const hint = error.hint;
+    return typeof hint === "string" && hint.length > 0 ? hint : undefined;
+}
 /**
  * Create image generation RPC handlers.
  * @param deps - Image generation service dependencies
@@ -38,7 +52,69 @@ import { suppressError } from "@comis/shared";
 export function createImageHandlers(deps) {
     return {
         [ImageGenerateContract.method]: async (rawParams) => {
+            // WR-03 (§2.7): capture entry time for the success-path durationMs.
+            // systemNowMs (not Date.now() — the globals gate forbids it).
+            const startMs = systemNowMs();
             const agentId = rawParams._agentId ?? "default";
+            // RES-01 keystone — the handler is no longer provider-blind. Resolve the
+            // agent's main provider in lockstep with the completion path (I4). This
+            // is informational here (obs + lockstep proof); the provider INSTANCE was
+            // already selected at wiring time (setup-image-provider.ts) — do NOT
+            // re-derive selection here (a second source of truth is the v2.20
+            // keyless-summarizer failure class).
+            const main = deps.resolveAgentMainProvider(agentId);
+            deps.logger.debug({ agentId, mainProvider: main.providerId, step: "image_resolve" }, "Image request resolved main provider");
+            // OBS-04 (§2.7): direct-emit the image.* lifecycle to the per-session
+            // trajectory recorder (the daemon RPC context has NO eventBus bridge — the
+            // comis-session-manager.ts:298 precedent). Resolve the recorder by the
+            // dispatcher-injected `_callerSessionKey`. `getRecorder?.()` no-ops to a
+            // non-crash when the registry is absent (a boot mode without one) or
+            // returns null/undefined (env-disabled session) — A1: the recorder is OPEN
+            // during the tool call (the executor turn is awaiting this result). `emit`
+            // records ONLY when a non-null recorder resolved. Payloads are content-free
+            // (ids/labels/costUsd/sizeBytes/outcome/errorKind — never the prompt, the
+            // image bytes, a key, or a raw provider message; T-186-08).
+            const sessionKey = rawParams._callerSessionKey;
+            const recorder = sessionKey && deps.trajectoryRegistry
+                ? deps.trajectoryRegistry.getRecorder?.(sessionKey)
+                : undefined;
+            const emit = (type, data) => {
+                if (recorder != null)
+                    recorder.recordEvent(type, data);
+            };
+            emit("image.requested", { provider: deps.provider.id, mainProvider: main.providerId });
+            // WR-05 (184-REVIEW): `main.providerId` is the CALLER's provider, resolved
+            // PER-REQUEST for obs/lockstep only. But `deps.provider` is a SINGLE
+            // boot-time-selected port built from the DEFAULT agent's OAuth manager +
+            // profiles (main-helpers.ts buildImageGenBundle <- daemon.ts
+            // oauthManagers.get(defaultAgentId)). So a NON-default agent whose main
+            // provider DIFFERS runs the DEFAULT agent's port/credentials — a known,
+            // DOCUMENTED scope boundary (per-agent re-selection + live rotation is a
+            // deferred multi-agent refinement — v2.23 phases 184-186 deliberately kept
+            // boot-time selection behind the two-source firewall; see main-helpers.ts +
+            // setup-image-provider.ts). Until a future phase closes it, make the
+            // divergence OBSERVABLE rather than silent: the per-request obs line names the
+            // caller's provider while execution uses the default's port, which would
+            // otherwise mislead triage. Agents that share the default's provider
+            // (matching ids) are unaffected — the common multi-agent case still works.
+            if (main.providerId !== deps.provider.id &&
+                // "auto"/"unavailable" are selector sentinels, not real provider ids —
+                // a mismatch against them is not a credential misroute.
+                deps.provider.id !== "unavailable" &&
+                main.providerId !== "auto" &&
+                main.providerId.length > 0) {
+                deps.logger.warn({
+                    agentId,
+                    callerProvider: main.providerId,
+                    executedProvider: deps.provider.id,
+                    step: "image_provider_divergence",
+                    errorKind: "precondition",
+                    hint: "This non-default agent's image request runs the DEFAULT agent's " +
+                        "boot-selected provider/credentials. Per-agent re-selection is a " +
+                        "deferred multi-agent refinement; until then set integrations.media." +
+                        "imageGeneration.provider explicitly, or run the image-capable agent as the default.",
+                }, "Image request provider diverges from the boot-selected port (multi-agent misroute risk)");
+            }
             const userParams = stripInternalFields(rawParams);
             const params = ImageGenerateContract.request.parse(userParams);
             const prompt = params.prompt;
@@ -46,41 +122,256 @@ export function createImageHandlers(deps) {
             if (!prompt) {
                 return { success: false, error: "Missing required parameter: prompt" };
             }
-            // Rate limit check
+            // Rate limit check. WR-03 (186-REVIEW): mirror the cost-ceiling block below
+            // — a count rate-limit block is a quota-style guard, so it must be just as
+            // diagnosable. Emit a WARN (closed-union log errorKind + the domain
+            // imageErrorKind + a hint naming maxPerHour) AND a terminal
+            // image.failed{quota_exceeded} before returning, so no classified failure
+            // returns without a logged errorKind + a diagnosable obs record (§2.7), and
+            // the reconstruction never shows an orphan requested-only turn whose
+            // failed-by-default outcome is an artifact rather than a real classification.
             if (!deps.rateLimiter.tryAcquire(agentId)) {
+                const hint = `Image generation rate limit reached (max ${deps.config.maxPerHour} ` +
+                    "per hour); raise integrations.media.imageGeneration.maxPerHour or wait " +
+                    "for the hour window to reset.";
+                deps.logger.warn({
+                    agentId,
+                    step: "image_rate_limit",
+                    errorKind: IMAGE_ERR_TO_LOG.quota_exceeded,
+                    imageErrorKind: "quota_exceeded",
+                    hint,
+                }, "Image generation blocked: per-hour count rate limit reached");
+                emit("image.failed", { errorKind: "quota_exceeded", provider: deps.provider.id });
                 return {
                     success: false,
                     error: `Rate limit exceeded: max ${deps.config.maxPerHour} images per hour`,
                 };
             }
+            // SEC-02 cost-ceiling PRE-check — placed AFTER the count limit (which is
+            // RETAINED), BEFORE provider.execute (the cost is only known after, so the
+            // gate is a pre-check on the ALREADY-accumulated spend + a post-hoc
+            // record below). Optional: undefined when `maxCostPerHourUsd` is unset →
+            // the ceiling is skipped (count-only, no regression). Exceeding the
+            // ceiling blocks with quota_exceeded (OBS-02: a WARN + hint naming the
+            // knob; OBS-04: image.failed{quota_exceeded} so the blocked turn is
+            // diagnosable via `comis explain`), and provider.execute is NOT called.
+            if (deps.costLimiter && !deps.costLimiter.canSpend(agentId)) {
+                const hint = "Image generation cost ceiling reached for this hour; raise " +
+                    "integrations.media.imageGeneration.maxCostPerHourUsd or wait for the " +
+                    "hour window to reset.";
+                // The Pino `errorKind` LOG field is the CLOSED 10-member union (the
+                // log-payload arch gate enforces it) — the domain `quota_exceeded` maps
+                // to `resource` via IMAGE_ERR_TO_LOG (the single vocabularies-meet point,
+                // mirroring pi-image-adapter.ts:153). The domain kind rides the separate
+                // `imageErrorKind` field. The trajectory image.failed below uses the
+                // domain kind directly (it is a content-free event payload, not a log).
+                deps.logger.warn({
+                    agentId,
+                    step: "image_cost_ceiling",
+                    errorKind: IMAGE_ERR_TO_LOG.quota_exceeded,
+                    imageErrorKind: "quota_exceeded",
+                    hint,
+                }, "Image generation blocked: per-hour cost ceiling reached");
+                emit("image.failed", { errorKind: "quota_exceeded", provider: deps.provider.id });
+                return { success: false, error: "Image generation cost ceiling exceeded", hint };
+            }
+            // IN-02 model validation (BEFORE any reference resolution / outbound
+            // call — T-185-11): reject an unknown `model` for the EXECUTING provider
+            // with a hint LISTING the valid models. Strict validation runs ONLY for
+            // providers WITH a non-empty Comis-side list (IMAGE_MODELS_BY_PROVIDER) —
+            // a provider with no list (e.g. openrouter, whose catalog is pi-ai's, not
+            // Comis's) does NOT reject every model (it would otherwise reject valid
+            // openrouter ids). The agent-supplied model then flows to the provider,
+            // which decides. pi-ai's getImageModels is openrouter-only (Pitfall 4),
+            // so the openai/google native lists are the IN-02 source of truth.
+            //
+            // WR-05 (185-REVIEW): validate against `deps.provider.id` — the provider
+            // that will ACTUALLY execute (the boot-selected DEFAULT agent's port) —
+            // NOT the per-request caller's `main.providerId`. In a multi-agent daemon
+            // they can differ (the documented Phase-186 divergence the WARN above
+            // surfaces); validating against the caller would PASS a model valid for
+            // the caller but then fail LATE at the executing SDK (a confusing
+            // late error). Validating against the executor makes the early reject's
+            // reason match reality. Sentinels ("unavailable") + listless providers
+            // (openrouter) have an empty list → no strict reject (Test 8 unchanged).
+            if (params.model) {
+                const executingProvider = deps.provider.id;
+                const known = listImageModels(executingProvider);
+                if (known.length > 0 && !isValidImageModel(executingProvider, params.model)) {
+                    const hint = `Valid models for ${executingProvider}: ${known.join(", ")}`;
+                    // OBS-02 (§2.7): no classified failure returns without a logged
+                    // errorKind + hint. The model-reject is a caller-precondition failure;
+                    // WARN it (with the listing hint) so the rejected turn is diagnosable
+                    // via `comis explain`. The raw model echo stays out of the payload
+                    // (only the safe `error`/`hint` strings carry it back to the caller).
+                    deps.logger.warn({ agentId, errorKind: "precondition", step: "image_model_reject", hint }, "Image generation rejected: unknown model for the executing provider");
+                    return {
+                        success: false,
+                        error: `Unknown model "${params.model}" for provider "${executingProvider}"`,
+                        hint,
+                    };
+                }
+            }
+            // IN-01 reference-image resolution (edit/img2img). Resolve ONLY when a
+            // `reference_image` is supplied; absence keeps the request text-only (no
+            // `referenceImage` field → no openrouter/codex regression). The resolution
+            // reuses the media-handlers SSRF + path-traversal guards (T-185-09/10).
+            let referenceImage;
+            if (params.reference_image) {
+                referenceImage = await resolveReferenceImage(params.reference_image, { workspaceDirs: deps.workspaceDirs, defaultWorkspaceDir: deps.defaultWorkspaceDir }, rawParams._agentId);
+            }
             // Pass safetyChecker from config.
-            // OpenAI enforces safety server-side; safetyChecker config only affects fal.ai's enable_safety_checker param
+            // OpenAI enforces safety server-side; safetyChecker config only affects fal.ai's enable_safety_checker param.
+            // IN-01/IN-02: forward the resolved reference image + the validated model
+            // when present (absence → omitted, so the text-only path is unchanged).
             const result = await deps.provider.execute({
                 prompt,
                 size: params.size ?? deps.config.defaultSize,
                 safetyChecker: deps.config.safetyChecker,
+                ...(referenceImage ? { referenceImage } : {}),
+                ...(params.model ? { model: params.model } : {}),
             });
             if (!result.ok) {
-                return { success: false, error: result.error.message };
+                // OBS-04: record the provider-error failure (errorKind + provider only —
+                // NEVER the raw provider message; T-186-08). The typed ImageGenError
+                // carries the domain `imageErrorKind`; an UNTYPED plain Error has none.
+                // IN-02 (186): the trajectory `errorKind` field speaks ONE vocabulary —
+                // the domain ImageErrorKind family — so the untyped fallback is the
+                // domain `empty_response` (a non-classified, non-image provider failure),
+                // NOT a bare "error" literal outside the ImageErrorKind union. (The closed
+                // 10-member log ErrorKind stays confined to the Pino line via
+                // IMAGE_ERR_TO_LOG; the trajectory event payload is not a log field.)
+                const imageErrorKind = result.error.imageErrorKind;
+                emit("image.failed", {
+                    errorKind: typeof imageErrorKind === "string" ? imageErrorKind : "empty_response",
+                    provider: deps.provider.id,
+                });
+                // RES-03 honest-unavailable: forward the typed error's knob-naming hint
+                // when present (e.g. an image-incapable main provider). The provider
+                // selector (setup-image-provider.ts) returns a port whose execute()
+                // yields an ImageGenError carrying { imageErrorKind, hint } — surface
+                // the hint so the agent gets a remedy, not silence.
+                const hint = extractImageHint(result.error);
+                return hint
+                    ? { success: false, error: result.error.message, hint }
+                    : { success: false, error: result.error.message };
             }
-            // Direct channel delivery via adapter.sendAttachment
-            const channelType = rawParams._callerChannelType;
-            const channelId = rawParams._callerChannelId;
-            if (channelType && channelId) {
-                const adapter = deps.getChannelAdapter(channelType);
-                if (adapter) {
-                    // Write buffer to temp file for sendAttachment (which takes a URL/path)
-                    const ext = result.value.mimeType === "image/png" ? ".png" : ".jpg";
-                    const tempPath = safePath(tmpdir(), `comis-img-${randomUUID()}${ext}`);
-                    await writeFile(tempPath, result.value.buffer);
-                    const attachment = {
-                        type: "image",
-                        url: tempPath,
-                        mimeType: result.value.mimeType,
-                        fileName: `generated-image${ext}`,
-                    };
-                    try {
-                        const sendResult = await adapter.sendAttachment(channelId, attachment);
+            // SEC-02: accumulate the actual cost into the per-agent/hour bucket on a
+            // successful generation (the pre-check above gates the NEXT request). This
+            // fires exactly once per success — placed after the `!result.ok` guard and
+            // before the persist/delivery branches so EVERY success path (delivered,
+            // base64-after-persist, persist-failure base64) accounts the cost the same.
+            // An undefined costUsd records 0 (the limiter clamps it; no crash) — legacy
+            // adapters without the widened ImageGenOutput simply contribute nothing.
+            deps.costLimiter?.record(agentId, result.value.costUsd ?? 0);
+            // WR-02 (186-REVIEW) / OBS-03: emit the synthetic `observability:token_usage`
+            // billing event HERE — after the cost is charged to the limiter, BEFORE the
+            // persist branch — so it fires on EVERY charged generation regardless of
+            // persist outcome (delivered, persist-ok, OR persist-failure base64). It
+            // previously lived inside the persisted-ok `else`, so a persist failure
+            // charged the limiter but UNDER-BILLED (cost-limiter, billing, and the obs
+            // outcome disagreed for the same turn). Tokens are all 0 (no LLM tokens for
+            // an image RPC); every token_usage subscriber SUMS cost.total / tokens.total
+            // (token-tracker.ts:191 guards `> 0`), so a 0-token event is safe (A3 /
+            // T-186-10). Emitted only on a non-zero costUsd.
+            if (deps.eventBus && (result.value.costUsd ?? 0) > 0) {
+                deps.eventBus.emit("observability:token_usage", {
+                    timestamp: systemNowMs(),
+                    traceId: sessionKey ?? "",
+                    agentId,
+                    channelId: rawParams._callerChannelId ?? "",
+                    executionId: "",
+                    provider: result.value.provider ?? deps.provider.id,
+                    model: result.value.model ?? "",
+                    tokens: { prompt: 0, completion: 0, total: 0 },
+                    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: result.value.costUsd ?? 0 },
+                    latencyMs: systemNowMs() - startMs,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    sessionKey: sessionKey ?? "",
+                    savedVsUncached: 0,
+                    cacheEligible: false,
+                    warmupTurn: false,
+                    pendingCacheInvestmentUsd: 0,
+                });
+            }
+            // DEL-01: persist the generated image to the agent's confined workspace
+            // (`~/.comis/workspace/media/photos/`) via MediaPersistenceService BEFORE
+            // any delivery decision — replacing the ephemeral OS temp-file plumbing. The
+            // service detects the MIME, assigns a UUID filename, routes to `photos/`,
+            // enforces the size cap, and confines the path with safePath internally;
+            // the handler hands it only a buffer + mediaKind (T-186-01 — it never
+            // builds a raw path). `persist` NEVER throws — on a failure (e.g. over the
+            // size cap, disk full) it returns `err`, and the handler WARNs and falls
+            // through to the bounded base64 RPC fallback (it does NOT crash and does
+            // NOT attempt channel delivery with a missing file).
+            const persisted = await deps.persist(agentId, result.value.buffer, {
+                mediaKind: "image",
+                mimeType: result.value.mimeType,
+            });
+            if (!persisted.ok) {
+                deps.logger.warn({
+                    agentId,
+                    err: persisted.error,
+                    errorKind: "resource",
+                    hint: "Image generated but persistence failed; returning base64 fallback",
+                    step: "image_persist",
+                }, "Image persistence failed");
+                // WR-02 (186-REVIEW): a persist failure here is a DEGRADED DELIVERY, not a
+                // generation failure. The generation SUCCEEDED, the cost was charged (and
+                // billed above), and the agent IS delivered the image as base64 below — so
+                // the terminal trajectory record is image.generated{outcome:"ok"} carrying
+                // costUsd (OBS-03 Route a), NOT image.failed (which would mis-report a
+                // charged, delivered image as failed and reconstruct the turn as failed in
+                // `comis explain`). `persisted:false` surfaces the missing durable artifact
+                // as a content-free degradation signal. sizeBytes is the raw buffer length
+                // (no PersistedFile). image.failed stays reserved for `!result.ok`.
+                emit("image.generated", {
+                    provider: deps.provider.id,
+                    outcome: "ok",
+                    persisted: false,
+                    ...(result.value.model !== undefined ? { model: result.value.model } : {}),
+                    ...(result.value.costUsd !== undefined ? { costUsd: result.value.costUsd } : {}),
+                    sizeBytes: result.value.buffer.byteLength,
+                });
+                // Fall through to the base64 fallback below (delivered as base64).
+            }
+            else {
+                // OBS-04: the image was generated AND durably persisted — record
+                // image.generated carrying costUsd (OBS-03 Route a — the binding cost the
+                // comis-explain reconstruction reads), model, the durable sizeBytes, and
+                // the ok outcome. `persisted:true` distinguishes it from the WR-02
+                // degraded-delivery branch above. Optional fields ride the widened
+                // ImageGenOutput (186-02) and are omitted when absent (no undefined keys).
+                emit("image.generated", {
+                    provider: deps.provider.id,
+                    outcome: "ok",
+                    persisted: true,
+                    ...(result.value.model !== undefined ? { model: result.value.model } : {}),
+                    ...(result.value.costUsd !== undefined ? { costUsd: result.value.costUsd } : {}),
+                    sizeBytes: persisted.value.sizeBytes,
+                });
+                // Direct channel delivery via adapter.sendAttachment, using the PERSISTED
+                // durable path (DEL-01 — no OS temp-file write, no delete, no cleanup).
+                const channelType = rawParams._callerChannelType;
+                const channelId = rawParams._callerChannelId;
+                if (channelType && channelId) {
+                    const adapter = deps.getChannelAdapter(channelType);
+                    // DEL-02 (capability-driven, NEVER a channel-name list): sendAttachment
+                    // is optional on ChannelPort. When the adapter omits it (today only
+                    // IRC), skip direct delivery and fall through to the base64 fallback —
+                    // never call an undefined method. This is a Class B call site (no
+                    // capability gate runs before image-handlers reaches the adapter).
+                    if (adapter && typeof adapter.sendAttachment === "function") {
+                        const sendAttachment = adapter.sendAttachment.bind(adapter);
+                        const ext = result.value.mimeType === "image/png" ? ".png" : ".jpg";
+                        const attachment = {
+                            type: "image",
+                            url: persisted.value.filePath,
+                            mimeType: result.value.mimeType,
+                            fileName: `generated-image${ext}`,
+                        };
+                        const sendResult = await sendAttachment(channelId, attachment);
                         if (!sendResult.ok) {
                             deps.logger.warn({
                                 channelType,
@@ -92,22 +383,38 @@ export function createImageHandlers(deps) {
                             // Fall through to base64 fallback
                         }
                         else {
-                            // Cleanup temp file after successful send
-                            suppressError(unlink(tempPath), "cleanup temp image file");
                             const deliveredResult = { success: true, delivered: true, mimeType: result.value.mimeType };
                             if (systemGetEnv("NODE_ENV") !== "production") {
                                 ImageGenerateContract.response.parse(deliveredResult);
                             }
+                            // OBS-04: the image reached the channel — record image.delivered
+                            // (channel TYPE + delivered boolean only, never the channel id).
+                            emit("image.delivered", { channelType, delivered: true });
+                            // OBS-01 (§2.7): the FULL completion field set on the
+                            // channel-delivered path. imageProvider = the EXECUTING port
+                            // (deps.provider.id); model/costUsd ride the widened ImageGenOutput
+                            // (OBS-03, Task 1); sizeBytes is the durable PersistedFile size
+                            // (DEL-01). traceId is NOT a payload field — it rides the Pino ALS
+                            // mixin (CLAUDE.md); the RPC producer injects no _traceId.
+                            deps.logger.info({
+                                agentId,
+                                imageProvider: deps.provider.id,
+                                mainProvider: main.providerId,
+                                model: result.value.model,
+                                costUsd: result.value.costUsd,
+                                sizeBytes: persisted.value.sizeBytes,
+                                delivered: true,
+                                mimeType: result.value.mimeType,
+                                durationMs: systemNowMs() - startMs,
+                                step: "image_complete",
+                            }, "Image generation completed");
                             return deliveredResult;
                         }
                     }
-                    finally {
-                        // Best-effort cleanup if not already done
-                        suppressError(unlink(tempPath), "cleanup temp image file");
-                    }
                 }
             }
-            // Fallback: return base64 when no channel adapter available or delivery failed
+            // Fallback: return base64 when persistence failed, no channel adapter is
+            // available, the adapter cannot attach (DEL-02), or delivery failed.
             const fallbackResult = {
                 success: true,
                 imageBase64: result.value.buffer.toString("base64"),
@@ -116,6 +423,22 @@ export function createImageHandlers(deps) {
             if (systemGetEnv("NODE_ENV") !== "production") {
                 ImageGenerateContract.response.parse(fallbackResult);
             }
+            // OBS-01 (§2.7): the FULL completion field set on the base64-fallback path
+            // (persist failed, no channel adapter, the adapter cannot attach, or
+            // delivery failed and fell through). No PersistedFile here, so sizeBytes is
+            // the raw buffer length. traceId rides the ALS mixin (NOT a payload field).
+            deps.logger.info({
+                agentId,
+                imageProvider: deps.provider.id,
+                mainProvider: main.providerId,
+                model: result.value.model,
+                costUsd: result.value.costUsd,
+                sizeBytes: result.value.buffer.byteLength,
+                delivered: false,
+                mimeType: result.value.mimeType,
+                durationMs: systemNowMs() - startMs,
+                step: "image_complete",
+            }, "Image generation completed");
             return fallbackResult;
         },
     };

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

@@ -10,12 +10,13 @@ export { createSubagentHandlers } from "./subagent-handlers.js";
 export { createApprovalHandlers, type ApprovalHandlerDeps } from "./approval-handlers.js";
 export { createAgentHandlers, type AgentHandlerDeps } from "./agent-handlers.js";
 export { createObsHandlers, type ObsHandlerDeps } from "./obs-handlers/index.js";
+export { createCacheHandlers } from "./cache-handlers.js";
 export { createModelHandlers, type ModelHandlerDeps } from "./model-handlers.js";
 export { createChannelHandlers, type ChannelHandlerDeps } from "./channel-handlers.js";
 export { createTokenHandlers, createTokenRegistry, type TokenHandlerDeps, type TokenRegistry } from "./token-handlers.js";
 export { createMcpHandlers, type McpHandlerDeps } from "./mcp-handlers.js";
+export { createMcpOauthHandlers, type McpOauthHandlerDeps } from "./mcp-oauth-handlers.js";
 export { createWorkspaceHandlers, type WorkspaceHandlerDeps } from "./workspace-handlers.js";
-export { createContextHandlers, type ContextHandlerDeps } from "./context-handlers.js";
 export { createDaemonHandlers, type DaemonHandlerDeps } from "./daemon-handlers.js";
 export { createEnvHandlers, type EnvHandlerDeps } from "./env-handlers.js";
 export { createSecretsHandlers, type SecretsHandlerDeps } from "./secrets-handlers.js";

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

@@ -9,12 +9,13 @@ export { createSubagentHandlers } from "./subagent-handlers.js";
 export { createApprovalHandlers } from "./approval-handlers.js";
 export { createAgentHandlers } from "./agent-handlers.js";
 export { createObsHandlers } from "./obs-handlers/index.js";
+export { createCacheHandlers } from "./cache-handlers.js";
 export { createModelHandlers } from "./model-handlers.js";
 export { createChannelHandlers } from "./channel-handlers.js";
 export { createTokenHandlers, createTokenRegistry } from "./token-handlers.js";
 export { createMcpHandlers } from "./mcp-handlers.js";
+export { createMcpOauthHandlers } from "./mcp-oauth-handlers.js";
 export { createWorkspaceHandlers } from "./workspace-handlers.js";
-export { createContextHandlers } from "./context-handlers.js";
 export { createDaemonHandlers } from "./daemon-handlers.js";
 export { createEnvHandlers } from "./env-handlers.js";
 export { createSecretsHandlers } from "./secrets-handlers.js";

package/node_modules/@comis/daemon/dist/api/main-provider-vision.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The VIS-01 keystone: the daemon-side provider-following VISION bridge.
+ *
+ * {@link createMainProviderVision} builds a `describeImage(buffer, prompt,
+ * mimeType, agentId)` seam that routes image analysis through the agent's MAIN
+ * vision-capable model via the pi-ai completion primitive, reusing the main
+ * provider's credentials (no separate vision key — I7).
+ *
+ * It is a near-verbatim mirror of `createDialecticSeam`
+ * (packages/agent/src/memory/memory-dialectic-seam.ts) — the ONE allowed
+ * query-time `completeSimple` seam — with THREE deltas:
+ *   1. the agent's MAIN model (resolved per-agentId via the injected
+ *      `resolveModel`), NOT the cheap cron model;
+ *   2. a multimodal `[TextContent, ImageContent]` user message (the seam uses a
+ *      bare-string user message; pi-ai's `UserMessage.content` accepts
+ *      `string | (TextContent | ImageContent)[]` — VERIFIED pi-ai
+ *      types.d.ts:194, ImageContent:165-169);
+ *   3. it returns a `Result<VisionResult & { costUsd? }, VisionUnavailable>`
+ *      rather than abstaining — every failure branch is an honest `err`
+ *      carrying an {@link ImageErrorKind}, NEVER a throw-out and NEVER a
+ *      misroute to a different provider.
+ *
+ * Why daemon-hosted: `completeSimple`/`getModel` are already a daemon dependency
+ * (graph-coordinator.ts:16, setup-channels-media.ts:35) and the bridge sits next
+ * to the handler wiring + the cred closures. Do NOT host it in `@comis/agent`;
+ * do NOT add `@earendil-works/pi-ai` to `@comis/skills` (the 183 pitfall).
+ *
+ * Security posture (the same discipline as the memory seams + 186 T-186-08):
+ * - ONE bounded `completeSimple` per call — `maxTokens` (the cost cap) + an
+ *   `AbortController` armed by the sanctioned-root `systemSetTimeout` (the
+ *   wall-clock-free abort; the injected `clock` supplies the message timestamp).
+ * - The resolved `apiKey` rides `SimpleStreamOptions.apiKey` ONLY — never
+ *   interpolated into a string, a URL, a log, or the trajectory (T-187-01).
+ * - CONTENT-FREE logging (T-187-02): a failure warns `{ agentId, errorKind,
+ *   hint }` and NOTHING ELSE — the `buffer`, the base64, the `prompt`, the
+ *   `content[]`, and the `response` text are NEVER in the log fields. Pino's
+ *   `apiKey`/`token`/`authorization` redaction is the backstop, not the
+ *   primary control.
+ * - HONEST capability (T-187-03): a missing key, a model-resolution failure, or
+ *   a non-"stop" completion returns `err` — the bridge never silently bills a
+ *   different provider.
+ *
+ * @module
+ */
+import type { ClockPort, ComisLogger, ImageErrorKind, VisionResult } from "@comis/core";
+import { type Result } from "@comis/shared";
+/**
+ * An honest-unavailable vision error. Carries a domain {@link ImageErrorKind}
+ * (reused, not invented) so the Plan 02 handler can read `errorKind` off the
+ * `err` and emit the VIS-04 obs. The hint (the `Error.message`) names the
+ * actionable knob; it never carries image bytes or the prompt.
+ */
+export declare class VisionUnavailable extends Error {
+    readonly errorKind: ImageErrorKind;
+    constructor(errorKind: ImageErrorKind, hint: string);
+}
+/** A successful vision result + the optional cost axis (VIS-04). */
+export type MainProviderVisionResult = VisionResult & {
+    costUsd?: number;
+};
+/** The deps the daemon injects (the model resolver + the cred closures, by value). */
+export interface MainProviderVisionDeps {
+    /**
+     * The I4 lockstep resolver — maps an agentId to its resolved main
+     * `{ provider, modelId }`. In Plan 02's wiring this is
+     * `resolveAgentModel(cfgFor(agentId), config.models)`. Injected so the bridge
+     * stays daemon-testable without the full config.
+     */
+    resolveModel: (agentId: string) => {
+        provider: string;
+        modelId: string;
+    };
+    /**
+     * Resolve the vision API key by PROVIDER (NOT by imagesApi — vision keys are
+     * `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`/`GOOGLE_API_KEY`). The daemon supplies
+     * the SecretManager-backed closure. Returns undefined for an unknown /
+     * key-less provider.
+     */
+    resolveApiKey: (provider: string) => string | undefined;
+    /**
+     * For provider `"openai-codex"`: resolve the bearer via
+     * `oauthManager.getApiKey("openai-codex", { oauthProfiles })` (184 precedent),
+     * unwrapped to `string | undefined`. Injected, optional.
+     */
+    resolveCodexKey?: (provider: string) => Promise<string | undefined>;
+    /** Wall-clock reads — the per-message timestamp. NEVER a wall-clock global. */
+    clock: ClockPort;
+    /** Counts/ids-only logger (failures carry a hint + errorKind, never bodies). */
+    logger: ComisLogger;
+    /** Per-call output bound (the cost axis). Defaults to {@link DEFAULT_MAX_TOKENS}. */
+    maxTokens?: number;
+    /** Hard abort ceiling. Defaults to {@link LLM_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** The bridge handle the handler consumes. */
+export interface MainProviderVision {
+    describeImage(buffer: Buffer, prompt: string, mimeType: string, agentId: string): Promise<Result<MainProviderVisionResult, VisionUnavailable>>;
+}
+/**
+ * Build the provider-following VISION bridge from the daemon-injected deps.
+ *
+ * Returns `{ describeImage }`: it resolves the agent's main `{ provider,
+ * modelId }`, resolves the key (the provider key OR the codex bearer), resolves
+ * the model via the COPIED `getModel` try/catch guard, then issues ONE bounded
+ * `completeSimple` with a multimodal `[text, image]` user message. A missing
+ * key, a model-resolution failure, a thrown/aborted call, or a non-"stop"
+ * completion returns an honest `err(VisionUnavailable)` — the bridge never
+ * throws out and never misroutes.
+ */
+export declare function createMainProviderVision(deps: MainProviderVisionDeps): MainProviderVision;