comisai 1.0.45 → 1.0.46

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

@@ -26,19 +26,19 @@
  * @module
  */
 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
+// Reference-image resolution (SSRF + path-traversal + size floor) is a
+// SHARED module reused by video-handlers' `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
+ * knob-naming `hint` (the 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.
+ * `string` hint when present. A plain `Error` has no `hint`, so the bare
+ * `{ success: false, error }` shape (no hint key) is preserved for those paths.
  */
 function extractImageHint(error) {
     const hint = error.hint;
@@ -52,28 +52,28 @@ function extractImageHint(error) {
 export function createImageHandlers(deps) {
     return {
         [ImageGenerateContract.method]: async (rawParams) => {
-            // WR-03 (§2.7): capture entry time for the success-path durationMs.
+            // §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).
+            // The handler is not provider-blind: resolve the agent's main provider in
+            // lockstep with the completion path. 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 for provider selection can silently diverge
+            // from the wired port).
             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
+            // §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
+            // returns null/undefined (env-disabled session) — 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).
+            // image bytes, a key, or a raw provider message).
             const sessionKey = rawParams._callerSessionKey;
             const recorder = sessionKey && deps.trajectoryRegistry
                 ? deps.trajectoryRegistry.getRecorder?.(sessionKey)
@@ -83,16 +83,16 @@ export function createImageHandlers(deps) {
                     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
+            // `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
+            // deferred multi-agent refinement; boot-time selection deliberately stays
+            // behind the two-source firewall — see main-helpers.ts +
+            // setup-image-provider.ts). Until that refinement lands, 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
@@ -122,7 +122,7 @@ export function createImageHandlers(deps) {
             if (!prompt) {
                 return { success: false, error: "Missing required parameter: prompt" };
             }
-            // Rate limit check. WR-03 (186-REVIEW): mirror the cost-ceiling block below
+            // Rate limit check: 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
@@ -147,13 +147,13 @@ export function createImageHandlers(deps) {
                     error: `Rate limit exceeded: max ${deps.config.maxPerHour} images per hour`,
                 };
             }
-            // SEC-02 cost-ceiling PRE-check — placed AFTER the count limit (which is
+            // 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
+            // ceiling blocks with quota_exceeded (a WARN + hint naming the
+            // knob, plus 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 " +
@@ -175,31 +175,31 @@ export function createImageHandlers(deps) {
                 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
+            // Model validation (BEFORE any reference resolution / outbound
+            // call): 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.
+            // which decides. pi-ai's getImageModels is openrouter-only,
+            // so the openai/google native lists are the validation source of truth.
             //
-            // WR-05 (185-REVIEW): validate against `deps.provider.id` — the provider
+            // 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
+            // they can differ (the documented 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).
+            // (openrouter) have an empty list → no strict reject.
             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
+                    // §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
@@ -212,17 +212,17 @@ export function createImageHandlers(deps) {
                     };
                 }
             }
-            // IN-01 reference-image resolution (edit/img2img). Resolve ONLY when a
+            // 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).
+            // reuses the media-handlers SSRF + path-traversal guards.
             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.
-            // IN-01/IN-02: forward the resolved reference image + the validated model
+            // 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,
@@ -232,10 +232,10 @@ export function createImageHandlers(deps) {
                 ...(params.model ? { model: params.model } : {}),
             });
             if (!result.ok) {
-                // OBS-04: record the provider-error failure (errorKind + provider only —
-                // NEVER the raw provider message; T-186-08). The typed ImageGenError
+                // Record the provider-error failure (errorKind + provider only —
+                // NEVER the raw provider message). The typed ImageGenError
                 // carries the domain `imageErrorKind`; an UNTYPED plain Error has none.
-                // IN-02 (186): the trajectory `errorKind` field speaks ONE vocabulary —
+                // 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
@@ -246,7 +246,7 @@ export function createImageHandlers(deps) {
                     errorKind: typeof imageErrorKind === "string" ? imageErrorKind : "empty_response",
                     provider: deps.provider.id,
                 });
-                // RES-03 honest-unavailable: forward the typed error's knob-naming hint
+                // 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
@@ -256,24 +256,24 @@ export function createImageHandlers(deps) {
                     ? { success: false, error: result.error.message, hint }
                     : { success: false, error: result.error.message };
             }
-            // SEC-02: accumulate the actual cost into the per-agent/hour bucket on a
+            // 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.
+            // An undefined costUsd records 0 (the limiter clamps it; no crash) —
+            // adapters that report no costUsd on ImageGenOutput simply contribute nothing.
             deps.costLimiter?.record(agentId, result.value.costUsd ?? 0);
-            // WR-02 (186-REVIEW) / OBS-03: emit the synthetic `observability:token_usage`
+            // 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.
+            // persist outcome (delivered, persist-ok, OR persist-failure base64). If it
+            // lived inside the persisted-ok `else`, a persist failure would
+            // charge the limiter but UNDER-BILL (cost-limiter, billing, and the obs
+            // outcome would disagree 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. Emitted only on a non-zero costUsd.
             if (deps.eventBus && (result.value.costUsd ?? 0) > 0) {
                 deps.eventBus.emit("observability:token_usage", {
                     timestamp: systemNowMs(),
@@ -295,12 +295,12 @@ export function createImageHandlers(deps) {
                     pendingCacheInvestmentUsd: 0,
                 });
             }
-            // DEL-01: persist the generated image to the agent's confined workspace
+            // 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
+            // the handler hands it only a buffer + mediaKind (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
@@ -317,11 +317,11 @@ export function createImageHandlers(deps) {
                     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
+                // 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
+                // costUsd, 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
@@ -337,12 +337,12 @@ export function createImageHandlers(deps) {
                 // 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
+                // The image was generated AND durably persisted — record
+                // image.generated carrying costUsd (the binding cost the
                 // comis-explain reconstruction reads), model, the durable sizeBytes, and
-                // the ok outcome. `persisted:true` distinguishes it from the WR-02
+                // the ok outcome. `persisted:true` distinguishes it from the
                 // degraded-delivery branch above. Optional fields ride the widened
-                // ImageGenOutput (186-02) and are omitted when absent (no undefined keys).
+                // ImageGenOutput and are omitted when absent (no undefined keys).
                 emit("image.generated", {
                     provider: deps.provider.id,
                     outcome: "ok",
@@ -352,16 +352,16 @@ export function createImageHandlers(deps) {
                     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).
+                // durable path (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
+                    // 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).
+                    // never call an undefined method. No capability gate runs before
+                    // image-handlers reaches the adapter, so the handler must check itself.
                     if (adapter && typeof adapter.sendAttachment === "function") {
                         const sendAttachment = adapter.sendAttachment.bind(adapter);
                         const ext = result.value.mimeType === "image/png" ? ".png" : ".jpg";
@@ -387,14 +387,14 @@ export function createImageHandlers(deps) {
                             if (systemGetEnv("NODE_ENV") !== "production") {
                                 ImageGenerateContract.response.parse(deliveredResult);
                             }
-                            // OBS-04: the image reached the channel — record image.delivered
+                            // 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
+                            // §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
+                            // (deps.provider.id); model/costUsd ride the widened ImageGenOutput;
+                            // sizeBytes is the durable PersistedFile size.
+                            // traceId is NOT a payload field — it rides the Pino ALS
                             // mixin (CLAUDE.md); the RPC producer injects no _traceId.
                             deps.logger.info({
                                 agentId,
@@ -414,7 +414,7 @@ export function createImageHandlers(deps) {
                 }
             }
             // Fallback: return base64 when persistence failed, no channel adapter is
-            // available, the adapter cannot attach (DEL-02), or delivery failed.
+            // available, the adapter cannot attach, or delivery failed.
             const fallbackResult = {
                 success: true,
                 imageBase64: result.value.buffer.toString("base64"),
@@ -423,7 +423,7 @@ 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
+            // §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).

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

@@ -1,10 +1,10 @@
 /**
- * The VIS-01 keystone: the daemon-side provider-following VISION bridge.
+ * 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).
+ * provider's credentials (no separate vision key).
  *
  * It is a near-verbatim mirror of `createDialecticSeam`
  * (packages/agent/src/memory/memory-dialectic-seam.ts) — the ONE allowed
@@ -23,20 +23,21 @@
  * 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).
+ * do NOT add `@earendil-works/pi-ai` to `@comis/skills` (a dependency-layering
+ * violation).
  *
- * Security posture (the same discipline as the memory seams + 186 T-186-08):
+ * Security posture (the same discipline as the memory seams):
  * - 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,
+ *   interpolated into a string, a URL, a log, or the trajectory.
+ * - CONTENT-FREE logging: 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
+ * - HONEST capability: a missing key, a model-resolution failure, or
  *   a non-"stop" completion returns `err` — the bridge never silently bills a
  *   different provider.
  *
@@ -46,23 +47,23 @@ import type { ClockPort, ComisLogger, ImageErrorKind, VisionResult } from "@comi
 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
+ * (reused, not invented) so the consuming handler can read `errorKind` off the
+ * `err` and emit the failure observability. 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). */
+/** A successful vision result + the optional cost axis. */
 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
+     * The lockstep resolver — maps an agentId to its resolved main
+     * `{ provider, modelId }`. In the daemon wiring this is
      * `resolveAgentModel(cfgFor(agentId), config.models)`. Injected so the bridge
      * stays daemon-testable without the full config.
      */
@@ -79,7 +80,7 @@ export interface MainProviderVisionDeps {
     resolveApiKey: (provider: string) => string | undefined;
     /**
      * For provider `"openai-codex"`: resolve the bearer via
-     * `oauthManager.getApiKey("openai-codex", { oauthProfiles })` (184 precedent),
+     * `oauthManager.getApiKey("openai-codex", { oauthProfiles })`,
      * unwrapped to `string | undefined`. Injected, optional.
      */
     resolveCodexKey?: (provider: string) => Promise<string | undefined>;

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

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * The VIS-01 keystone: the daemon-side provider-following VISION bridge.
+ * 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).
+ * provider's credentials (no separate vision key).
  *
  * It is a near-verbatim mirror of `createDialecticSeam`
  * (packages/agent/src/memory/memory-dialectic-seam.ts) — the ONE allowed
@@ -24,20 +24,21 @@
  * 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).
+ * do NOT add `@earendil-works/pi-ai` to `@comis/skills` (a dependency-layering
+ * violation).
  *
- * Security posture (the same discipline as the memory seams + 186 T-186-08):
+ * Security posture (the same discipline as the memory seams):
  * - 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,
+ *   interpolated into a string, a URL, a log, or the trajectory.
+ * - CONTENT-FREE logging: 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
+ * - HONEST capability: a missing key, a model-resolution failure, or
  *   a non-"stop" completion returns `err` — the bridge never silently bills a
  *   different provider.
  *
@@ -45,15 +46,15 @@
  */
 import { systemSetTimeout, systemClearTimeout, IMAGE_ERR_TO_LOG } from "@comis/core";
 import { ok, err } from "@comis/shared";
-import { completeSimple, getModel } from "@earendil-works/pi-ai";
+import { completeSimple, getModel } from "@earendil-works/pi-ai/compat";
 /** Hard abort ceiling per vision call (mirrors the memory-seam LLM timeout). */
 const LLM_TIMEOUT_MS = 120_000;
 /** Default per-call output bound — a description is short; this caps cost/latency. */
 const DEFAULT_MAX_TOKENS = 1024;
 /**
  * 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
+ * (reused, not invented) so the consuming handler can read `errorKind` off the
+ * `err` and emit the failure observability. The hint (the `Error.message`) names the
  * actionable knob; it never carries image bytes or the prompt.
  */
 export class VisionUnavailable extends Error {
@@ -114,8 +115,8 @@ export function createMainProviderVision(deps) {
     const timeoutMs = deps.timeoutMs ?? LLM_TIMEOUT_MS;
     async function describeImage(buffer, prompt, mimeType, agentId) {
         const { provider, modelId } = resolveModel(agentId);
-        // 1. Resolve the key — reuse the main provider's creds (I7). The provider
-        //    key first; the codex bearer for "openai-codex" (184 precedent).
+        // 1. Resolve the key — reuse the main provider's creds. The provider
+        //    key first; the codex bearer for "openai-codex".
         let apiKey = resolveApiKey(provider);
         if (!apiKey && provider === "openai-codex" && resolveCodexKey) {
             apiKey = await resolveCodexKey(provider);
@@ -153,7 +154,7 @@ export function createMainProviderVision(deps) {
         }
         // 3. ONE bounded completeSimple with the MULTIMODAL message (the keystone).
         const controller = new AbortController();
-        // WR-02: track whether OUR timer was the abort trigger. pi-ai's completeSimple
+        // Track whether OUR timer was the abort trigger. pi-ai's completeSimple
         // RESOLVES (does not reject) on the abort event — the AssistantMessage then
         // carries stopReason:"aborted" and hits the non-"stop" branch below rather
         // than the catch. `timedOut` lets that branch classify a genuine wall-clock
@@ -178,7 +179,7 @@ export function createMainProviderVision(deps) {
                 ],
             }, { apiKey, maxTokens, signal: controller.signal });
             if (response.stopReason !== "stop") {
-                // WR-02: a resolved-with-"aborted" stream means our timer fired (the
+                // A resolved-with-"aborted" stream means our timer fired (the
                 // ONLY abort trigger on this path) — classify it as a timeout, not the
                 // generic empty_response classifyStopReason would otherwise return.
                 const abortedByTimeout = response.stopReason === "aborted" && (timedOut || controller.signal.aborted);
@@ -208,7 +209,7 @@ export function createMainProviderVision(deps) {
             });
         }
         catch (llmErr) {
-            // WR-02: prefer the explicit timedOut flag (our timer fired) and keep
+            // Prefer the explicit timedOut flag (our timer fired) and keep
             // controller.signal.aborted as the fallback — both indicate the bridge's
             // own abort, the only abort trigger on this path.
             const aborted = timedOut || controller.signal.aborted;

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

@@ -81,7 +81,7 @@ export function createMcpHandlers(deps) {
             return result;
         },
         [McpStatusContract.method]: async (rawParams) => {
-            // Bespoke pre-Zod guard — produces the legacy "Missing required
+            // Bespoke pre-Zod guard — produces the user-friendly "Missing required
             // parameter: server_name" UX, which is more actionable than Zod's
             // noisier `.min(1)` error. The contract's `z.string().min(1)` is
             // defense-in-depth.
@@ -124,7 +124,7 @@ export function createMcpHandlers(deps) {
             return result;
         },
         [McpConnectContract.method]: async (rawParams) => {
-            // Bespoke pre-Zod guard for legacy "Missing required parameter:
+            // Bespoke pre-Zod guard for the user-friendly "Missing required parameter:
             // server_name" UX. Contract's .min(1) + enum gating is defense-in-depth.
             const nameRaw = rawParams.server_name;
             if (!nameRaw)
@@ -260,8 +260,8 @@ export function createMcpHandlers(deps) {
             }
             // Build + persist the auth:"oauth" entry and throw the structured
             // needs_oauth_login signal. Used by:
-            //   - Fix 4 pre-check  (token store has no tokens for this server yet)
-            //   - Fix 2 post-fail  (manager.connect surfaced a NeedsOAuthLoginError)
+            //   - the token-aware pre-check  (token store has no tokens for this server yet)
+            //   - the post-fail branch  (manager.connect surfaced a NeedsOAuthLoginError)
             // Without persistence, the subsequent mcp.oauth_login at
             // mcp-oauth-handlers.ts:135 cannot find the entry in
             // container.config.integrations.mcp.servers.
@@ -297,12 +297,12 @@ export function createMcpHandlers(deps) {
                 };
                 throw structured;
             };
-            // Fix 4 — token-aware short-circuit. When auth==="oauth" AND no token
+            // Token-aware short-circuit. When auth==="oauth" AND no token
             // exists yet, manager.connect is doomed (the SDK's DCR runs with
             // redirect_uris=[] — the loopback only exists during mcp.oauth_login — so
-            // a spec provider returns 400, masking the real "run mcp_login" signal).
-            // createTokenStore is undefined in some test harnesses (pre-check no-ops;
-            // Fix 2 below handles it). The mode-selected pass-through is defined but
+            // a spec-compliant provider returns 400, masking the real "run mcp_login"
+            // signal). createTokenStore is undefined in some test harnesses (pre-check
+            // no-ops; the post-fail branch below handles it). The mode-selected pass-through is defined but
             // RETURNS undefined in env mode — read it into a local so that case is
             // treated as "no token" without a deref-of-undefined or a disk fallback.
             if (params.auth === "oauth" && deps.createTokenStore !== undefined) {
@@ -314,7 +314,7 @@ export function createMcpHandlers(deps) {
             }
             const result = await manager.connect(config);
             if (!result.ok) {
-                // Fix 2: when connectServer surfaced a NeedsOAuthLoginError
+                // Post-fail branch: when connectServer surfaced a NeedsOAuthLoginError
                 // (UnauthorizedError / StreamableHTTPError(401)) AND the operator
                 // opted in with auth:"oauth", persist the entry before throwing the
                 // structured signal so mcp_login finds it. mcp-handlers.ts.test.ts
@@ -388,7 +388,7 @@ export function createMcpHandlers(deps) {
             return response;
         },
         [McpDisconnectContract.method]: async (rawParams) => {
-            // Bespoke pre-Zod guard — produces the legacy "Missing required
+            // Bespoke pre-Zod guard — produces the user-friendly "Missing required
             // parameter: server_name" UX. The contract's `.min(1)` is
             // defense-in-depth.
             const nameRaw = rawParams.server_name;
@@ -430,7 +430,7 @@ export function createMcpHandlers(deps) {
             return result;
         },
         [McpTestContract.method]: async (rawParams) => {
-            // Bespoke pre-Zod guards — produce legacy "Missing required
+            // Bespoke pre-Zod guards — produce the user-friendly "Missing required
             // parameter: ..." UX (note the test handler reads `name`, NOT
             // `server_name`). Contract's `.min(1)` + enum gating is
             // defense-in-depth.
@@ -590,7 +590,7 @@ export function createMcpHandlers(deps) {
             }
         },
         [McpReconnectContract.method]: async (rawParams) => {
-            // Bespoke pre-Zod guard — produces the legacy "Missing required
+            // Bespoke pre-Zod guard — produces the user-friendly "Missing required
             // parameter: server_name" UX. The contract's `.min(1)` is
             // defense-in-depth.
             const nameRaw = rawParams.server_name;

package/node_modules/@comis/daemon/dist/api/mcp-header-credential.d.ts

@@ -65,7 +65,7 @@ export interface ProcessHeaderCredentialsOpts {
      * Optional daemon-owned write handle over the shared SecretManager backing Map.
      * When provided, extracted MCP header secrets are live-applied via upsert after
      * secretStore.set succeeds — so broker/exec observe the value on their next request
-     * without a daemon restart (additive no-restart — P4a). Optional chaining guards legacy
+     * without a daemon restart (additive writes are live immediately). Optional chaining guards
      * callers and test setups that don't wire the mutable handle.
      */
     mutableSecretManager?: MutableSecretManager;

package/node_modules/@comis/daemon/dist/api/mcp-header-credential.js

@@ -124,8 +124,8 @@ export function processHeaderCredentials(opts) {
                 `Hint: fix the secret store, then retry.`);
         }
         // Live-apply: upsert into the shared SecretManager Map so broker/exec observe the new
-        // value on their next request without a restart (additive no-restart — P4a).
-        // Optional chaining guards callers (tests, legacy paths) that don't wire the handle.
+        // value on their next request without a restart (additive writes are live immediately).
+        // Optional chaining guards callers (e.g. tests) that don't wire the handle.
         opts.mutableSecretManager?.upsert(varName, headerValue);
         // Rewrite the header value in place to the ${VAR} reference (for persistence).
         // resolvedHeaders already holds the raw value from the initial copy above.