comisai 1.0.34 → 1.0.36

package/node_modules/@comis/daemon/dist/wiring/setup-background-completion-runner.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background completion runner wiring for daemon startup.
+ *
+ * Subscribes the runner to background_task:{completed,failed} events after
+ * the notification service has been wired (so fallbackNotifyFn is live),
+ * and returns a shutdown handle for the daemon's system:shutdown sequence
+ * to await before tearing down the executor.
+ *
+ * Per AGENTS §2.4: composition root + factories. This wiring lives in
+ * @comis/daemon (composition root); the actual factory body is in
+ * @comis/agent.
+ *
+ * @module
+ */
+import { createBackgroundCompletionRunner, } from "@comis/agent";
+/**
+ * Wire the background completion runner from daemon-level dependencies.
+ * Call this AFTER setupNotifications so fallbackNotifyFn is wired.
+ */
+export function setupBackgroundCompletionRunner(deps) {
+    const runner = createBackgroundCompletionRunner({
+        eventBus: deps.eventBus,
+        getExecutor: deps.getExecutor,
+        sessionStore: deps.sessionStore,
+        taskManager: deps.taskManager,
+        fallbackNotifyFn: deps.fallbackNotifyFn,
+        maxBackgroundHops: deps.maxBackgroundHops,
+        logger: deps.logger,
+    });
+    return { runner };
+}

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

@@ -19,9 +19,16 @@ export interface SetupBackgroundTasksDeps {
 }
 /**
  * Wire the background task subsystem from daemon-level dependencies.
- * Creates BackgroundTaskManager with file-based persistence, recovers
- * incomplete tasks from the previous daemon run (marking them failed),
- * and starts an hourly cleanup timer for stale completed/failed tasks.
+ * Creates BackgroundTaskManager with file-based persistence and starts
+ * an hourly cleanup timer for stale completed/failed tasks.
+ *
+ * Note: startup recovery (marking interrupted tasks as failed) is
+ * INTENTIONALLY deferred to daemon.ts. The daemon calls it AFTER
+ * `setupBackgroundCompletionRunner` has subscribed to
+ * background_task:{completed,failed}. If recovery fires before the runner
+ * subscribes, the synthesized failure events for restart-interrupted tasks
+ * land in an empty handler set and the user never sees the recovery
+ * announcement.
  * @param deps - Daemon-level dependencies
  * @returns BackgroundTasksContext with manager instance
  */

package/node_modules/@comis/daemon/dist/wiring/setup-background-tasks.js

@@ -9,9 +9,16 @@ import { createBackgroundTaskManager } from "@comis/agent";
 import { safePath } from "@comis/core";
 /**
  * Wire the background task subsystem from daemon-level dependencies.
- * Creates BackgroundTaskManager with file-based persistence, recovers
- * incomplete tasks from the previous daemon run (marking them failed),
- * and starts an hourly cleanup timer for stale completed/failed tasks.
+ * Creates BackgroundTaskManager with file-based persistence and starts
+ * an hourly cleanup timer for stale completed/failed tasks.
+ *
+ * Note: startup recovery (marking interrupted tasks as failed) is
+ * INTENTIONALLY deferred to daemon.ts. The daemon calls it AFTER
+ * `setupBackgroundCompletionRunner` has subscribed to
+ * background_task:{completed,failed}. If recovery fires before the runner
+ * subscribes, the synthesized failure events for restart-interrupted tasks
+ * land in an empty handler set and the user never sees the recovery
+ * announcement.
  * @param deps - Daemon-level dependencies
  * @returns BackgroundTasksContext with manager instance
  */
@@ -21,8 +28,7 @@ export function setupBackgroundTasks(deps) {
         eventBus: deps.eventBus,
         logger: deps.logger,
     });
-    // Mark incomplete tasks from previous daemon run as failed
-    manager.recoverOnStartup();
+    // Startup recovery is deferred to daemon.ts (after the completion runner subscribes).
     // Periodic cleanup of stale completed/failed tasks (24h TTL)
     const cleanupInterval = setInterval(() => manager.cleanup(), 3_600_000); // every hour
     cleanupInterval.unref(); // don't keep daemon alive for cleanup

package/node_modules/@comis/daemon/dist/wiring/setup-channels.js

@@ -96,7 +96,7 @@ export async function setupChannels(deps) {
                 return;
             }
             const workspacePath = deps.workspaceDirs?.get(agentId) ?? "";
-            const reviewLogger = logger.child({ agentId, module: "memory-review" });
+            const reviewLogger = logger.child({ agentId, submodule: "memory-review" });
             const reviewResult = await runMemoryReview({
                 agentId,
                 tenantId: deps.tenantId ?? container.config.tenantId ?? "default",
@@ -142,6 +142,25 @@ export async function setupChannels(deps) {
             // Extract session strategy from event payload (defaults: fresh, 3 turns)
             const sessionStrategy = payload.sessionStrategy ?? "fresh";
             const maxHistoryTurns = payload.maxHistoryTurns ?? 3;
+            // Cadence-aware cache-waste guard: rolling/accumulate strategies on long cadences
+            // guarantee cache-write waste because the prompt cache TTL is short (5 min for "cron"
+            // operations — see OPERATION_CACHE_DEFAULTS.cron in @comis/agent). Threshold = 2x TTL
+            // so we don't warn on borderline-useful 6-9 min cadences. Operator intent is preserved
+            // (no auto-downgrade) — this is informational only. Scoped to schedule.kind === "every"
+            // because cron-expression cadence is not threaded through the event payload.
+            const CRON_CACHE_TTL_2X_MS = 600_000;
+            if (sessionStrategy !== "fresh" &&
+                payload.cadenceMs !== undefined &&
+                payload.cadenceMs > CRON_CACHE_TTL_2X_MS) {
+                logger.warn({
+                    jobName,
+                    agentId: payload.agentId,
+                    sessionStrategy,
+                    cadenceMs: payload.cadenceMs,
+                    hint: "Cadence exceeds cache TTL by 2x; rolling/accumulate guarantees per-tick cache-write waste. Set sessionStrategy:'fresh' unless cross-tick session memory is essential.",
+                    errorKind: "config",
+                }, "Cron sessionStrategy may waste cache writes at this cadence");
+            }
             // Resolve cron operation model via 5-level priority chain
             const agentConfig = agents[payload.agentId];
             let cronOverrides;

package/node_modules/@comis/daemon/dist/wiring/setup-cross-session.js

@@ -581,7 +581,7 @@ export function setupCrossSession(deps) {
         maxAgeMs: 3_600_000,
         maxEntries: 100,
         eventBus: container.eventBus,
-        logger: deps.logger?.child({ module: "dead-letter-queue" }),
+        logger: deps.logger?.child({ submodule: "dead-letter-queue" }),
     });
     // Create announcement batcher for coalescing near-simultaneous sub-agent completions
     const announcementBatcher = createAnnouncementBatcher({

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

@@ -5,8 +5,9 @@
  * Queue two-phase lifecycle resolves the circular dependency between the
  * queue and channel adapters:
  *   1. setupDeliveryQueue() creates the adapter immediately (before setupChannels).
- *   2. drainAndStartPrune() runs drain + starts prune timer AFTER setupChannels
- *      populates channelAdapters.
+ *   2. drainAndStart() recovers in_flight rows, runs startup drain, then starts
+ *      both the recurring drain timer and the prune timer AFTER
+ *      setupChannels populates channelAdapters.
  * Crash-Safe Delivery Queue.
  * Session Mirroring.
  * @module setup-delivery — Delivery subsystem wiring (queue + mirror)
@@ -18,9 +19,9 @@ import type { PluginRegistry } from "@comis/core";
 export interface DeliveryQueueResult {
     /** The delivery queue adapter (real or no-op), available immediately. */
     deliveryQueue: DeliveryQueuePort;
-    /** Runs startup drain then starts periodic prune timer. Call AFTER setupChannels. */
-    drainAndStartPrune: () => Promise<void>;
-    /** Clears the prune interval timer (call on shutdown). */
+    /** Recovers in_flight rows, runs startup drain, then starts the recurring drain + prune timers. Call AFTER setupChannels. */
+    drainAndStart: () => Promise<void>;
+    /** Clears the recurring drain interval AND the prune interval (call on shutdown). */
     shutdown: () => void;
 }
 export declare function setupDeliveryQueue(deps: {
@@ -31,6 +32,14 @@ export declare function setupDeliveryQueue(deps: {
     logger: ComisLogger;
     channelAdapters: Map<string, DeliveryAdapter>;
 }): Promise<DeliveryQueueResult>;
+export declare function drainDeliveryQueue(deps: {
+    deliveryQueue: DeliveryQueuePort;
+    channelAdapters: Map<string, DeliveryAdapter>;
+    eventBus: TypedEventBus;
+    logger: ComisLogger;
+    drainBudgetMs: number;
+    defaultMaxAttempts: number;
+}): Promise<void>;
 export interface DeliveryMirrorResult {
     /** The delivery mirror adapter (real or no-op), available immediately. */
     deliveryMirror: DeliveryMirrorPort;

package/node_modules/@comis/daemon/dist/wiring/setup-delivery.js

@@ -6,8 +6,9 @@
  * Queue two-phase lifecycle resolves the circular dependency between the
  * queue and channel adapters:
  *   1. setupDeliveryQueue() creates the adapter immediately (before setupChannels).
- *   2. drainAndStartPrune() runs drain + starts prune timer AFTER setupChannels
- *      populates channelAdapters.
+ *   2. drainAndStart() recovers in_flight rows, runs startup drain, then starts
+ *      both the recurring drain timer and the prune timer AFTER
+ *      setupChannels populates channelAdapters.
  * Crash-Safe Delivery Queue.
  * Session Mirroring.
  * @module setup-delivery — Delivery subsystem wiring (queue + mirror)
@@ -15,7 +16,7 @@
 import { createNoOpDeliveryQueue, createNoOpDeliveryMirror } from "@comis/core";
 import { createSqliteDeliveryQueue, createSqliteDeliveryMirror } from "@comis/memory";
 import { isPermanentError, computeQueueBackoff } from "@comis/channels";
-import { ok } from "@comis/shared";
+import { ok, suppressError } from "@comis/shared";
 import { createHash } from "node:crypto";
 // ---------------------------------------------------------------------------
 // Setup function
@@ -28,28 +29,56 @@ export async function setupDeliveryQueue(deps) {
         logger.debug("Delivery queue disabled by config");
         return {
             deliveryQueue: createNoOpDeliveryQueue(),
-            drainAndStartPrune: async () => { },
+            drainAndStart: async () => { },
             shutdown: () => { },
         };
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- db is better-sqlite3 Database; typed as unknown to avoid cross-package type dependency
-    const deliveryQueue = createSqliteDeliveryQueue(db);
+    const deliveryQueue = createSqliteDeliveryQueue(db, eventBus);
     logger.info({ maxQueueDepth: queueConfig.maxQueueDepth, defaultMaxAttempts: queueConfig.defaultMaxAttempts }, "Delivery queue enabled");
     let pruneInterval;
-    // 2. Startup drain + 3. Periodic prune (deferred until channelAdapters populated)
-    const drainAndStartPrune = async () => {
-        // --- Drain ---
+    let drainInterval;
+    // Single-tick gate: in-flight Promise prevents overlapping ticks.
+    let draining = null;
+    // Inner helper: one drain pass. Reused by startup drain AND each recurring tick.
+    const runOneDrainPass = async () => {
+        await drainDeliveryQueue({
+            deliveryQueue,
+            channelAdapters,
+            eventBus,
+            logger,
+            drainBudgetMs: queueConfig.drainBudgetMs,
+            defaultMaxAttempts: queueConfig.defaultMaxAttempts,
+        });
+    };
+    // 2. Startup drain + recurring drain timer + prune timer (deferred until channelAdapters populated)
+    const drainAndStart = async () => {
+        // --- Step 1: Recover in_flight rows. ---
+        // Runs UNCONDITIONALLY -- independent of drainOnStartup policy. An 'in_flight'
+        // row from a prior crash is a correctness bug regardless of the drain policy.
+        const recoverResult = await deliveryQueue.recoverInFlight();
+        if (!recoverResult.ok) {
+            logger.warn({ err: recoverResult.error, hint: "Could not recover in_flight rows on startup; messages may stall until next restart", errorKind: "internal" }, "Delivery queue: recoverInFlight failed");
+        }
+        else if (recoverResult.value > 0) {
+            logger.info({ recovered: recoverResult.value }, "Delivery queue: recovered in_flight rows to pending");
+        }
+        // --- Step 2: Startup drain (existing behavior, unchanged). ---
         if (queueConfig.drainOnStartup) {
-            await drainDeliveryQueue({
-                deliveryQueue,
-                channelAdapters,
-                eventBus,
-                logger,
-                drainBudgetMs: queueConfig.drainBudgetMs,
-                defaultMaxAttempts: queueConfig.defaultMaxAttempts,
-            });
+            await runOneDrainPass();
         }
-        // --- Prune timer ---
+        // --- Step 3: Recurring drain timer. ---
+        drainInterval = setInterval(() => {
+            if (draining)
+                return; // single-tick gate
+            draining = runOneDrainPass().finally(() => { draining = null; });
+            // Fire-and-forget: failures inside drainDeliveryQueue are already logged
+            // and do not propagate (it never throws). suppressError satisfies the
+            // no-floating-promise lint without altering semantics.
+            suppressError(draining, "delivery queue recurring drain tick");
+        }, queueConfig.drainIntervalMs);
+        drainInterval.unref();
+        // --- Step 4: Prune timer (existing behavior, unchanged). ---
         pruneInterval = setInterval(async () => {
             const result = await deliveryQueue.pruneExpired();
             if (result.ok && result.value > 0) {
@@ -59,17 +88,21 @@ export async function setupDeliveryQueue(deps) {
         pruneInterval.unref();
     };
     const shutdown = () => {
+        if (drainInterval) {
+            clearInterval(drainInterval);
+            drainInterval = undefined;
+        }
         if (pruneInterval) {
             clearInterval(pruneInterval);
             pruneInterval = undefined;
         }
     };
-    return { deliveryQueue, drainAndStartPrune, shutdown };
+    return { deliveryQueue, drainAndStart, shutdown };
 }
 // ---------------------------------------------------------------------------
 // Drain implementation
 // ---------------------------------------------------------------------------
-async function drainDeliveryQueue(deps) {
+export async function drainDeliveryQueue(deps) {
     const { deliveryQueue, channelAdapters, eventBus, logger, drainBudgetMs, defaultMaxAttempts } = deps;
     const drainStart = Date.now();
     const deadline = drainStart + drainBudgetMs;

package/node_modules/@comis/daemon/dist/wiring/setup-schedulers.js

@@ -108,6 +108,10 @@ export async function setupSchedulers(deps) {
                         payloadKind: job.payload.kind,
                         sessionStrategy: job.sessionStrategy,
                         maxHistoryTurns: job.maxHistoryTurns,
+                        // Cadence is a literal number only for kind === "every"; cron-expression
+                        // schedules would require parsing the expression to estimate a cadence,
+                        // which is out of scope. Consumers must treat undefined as "unknown".
+                        cadenceMs: job.schedule.kind === "every" ? job.schedule.everyMs : undefined,
                         cronJobModel: job.payload.kind === "agent_turn" ? job.payload.model : undefined,
                         cacheRetention: job.cacheRetention,
                         toolPolicy: job.toolPolicy,

package/node_modules/@comis/daemon/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/daemon",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.36",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Background daemon and orchestrator for the Comis platform",

package/node_modules/@comis/gateway/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { RpcAdapterDeps } from "./rpc/rpc-adapters.js";
 export { WsConnectionManager } from "./rpc/ws-handler.js";
 export { createMappedWebhookEndpoint } from "./webhook/webhook-endpoint.js";
 export { getPresetMappings } from "./webhook/webhook-presets.js";
+export { createOAuthCallbackRoute, insertPendingFlow, PENDING_FLOW_TIMEOUT_MS, } from "./oauth/oauth-callback-route.js";
+export type { OAuthCallbackDeps, PendingFlow, } from "./oauth/oauth-callback-route.js";
 export { createMediaRoutes } from "./web/index.js";
 export { createOpenaiCompletionsRoute } from "./openai/index.js";
 export { createOpenaiModelsRoute } from "./openai/index.js";

package/node_modules/@comis/gateway/dist/index.js

@@ -16,6 +16,8 @@ export { WsConnectionManager } from "./rpc/ws-handler.js";
 // Webhook
 export { createMappedWebhookEndpoint } from "./webhook/webhook-endpoint.js";
 export { getPresetMappings } from "./webhook/webhook-presets.js";
+// OAuth callback route exports
+export { createOAuthCallbackRoute, insertPendingFlow, PENDING_FLOW_TIMEOUT_MS, } from "./oauth/oauth-callback-route.js";
 // Web -- media routes
 export { createMediaRoutes } from "./web/index.js";
 // OpenAI compatibility endpoints

package/node_modules/@comis/gateway/dist/oauth/oauth-callback-route.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OAuth callback route for the Comis gateway.
+ *
+ * Mounted at `GET /callback/:provider` via `app.route("/oauth", subApp)`. The
+ * handler validates code+state, looks up the state in the in-memory pending-
+ * flow map, verifies path-vs-flow provider match, deletes the entry BEFORE
+ * the token exchange (one-time-use invariant), exchanges the code at
+ * auth.openai.com/oauth/token, resolves identity via
+ * resolveCodexAuthIdentity, persists via OAuthCredentialStorePort.set, emits
+ * auth:profile_bootstrapped, and returns a static "Login Successful" HTML
+ * page (200) on success or a "Login Failed" HTML page (400/500) on failure.
+ *
+ * HTTP method is GET, NOT POST (OAuth servers always redirect with GET).
+ * Logging discipline (CLAUDE.md): submodule: "oauth-callback"
+ * on every line; NEVER log code/state/verifier/access/refresh values.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import type { OAuthCredentialStorePort, TypedEventBus } from "@comis/core";
+import type { GatewayLogger } from "../server/hono-server.js";
+/** 5-minute pending-flow expiry. Exported for test parity. */
+export declare const PENDING_FLOW_TIMEOUT_MS: number;
+/**
+ * Pending-flow entry stored in the in-memory map keyed by `state`.
+ * Created by insertPendingFlow at flow-initiation time; consumed by the
+ * /callback/:provider handler on a successful state-match.
+ */
+export interface PendingFlow {
+    /** PKCE code_verifier generated at flow initiation. */
+    verifier: string;
+    /** "openai-codex" — used for path-vs-flow provider validation. */
+    provider: string;
+    /** Date.now() at insertion time. */
+    createdAt: number;
+    /**
+     * Cleanup timer reference. The handler clearTimeout(timer) on consume;
+     * the auto-expiry path (PENDING_FLOW_TIMEOUT_MS) deletes the entry.
+     */
+    timer: ReturnType<typeof setTimeout>;
+}
+/** Dependencies for createOAuthCallbackRoute. */
+export interface OAuthCallbackDeps {
+    readonly credentialStore: OAuthCredentialStorePort;
+    readonly eventBus: TypedEventBus;
+    readonly logger: GatewayLogger;
+    /** State -> PendingFlow map; mutated by handler + insertPendingFlow. */
+    readonly pendingFlows: Map<string, PendingFlow>;
+}
+/**
+ * Seed the pending-flow map with a new state -> PendingFlow entry, scheduling
+ * a 5-minute auto-delete cleanup timer.
+ *
+ * The caller is responsible for generating `state` via crypto.randomBytes(16)
+ * — never hand-roll a PRNG.
+ */
+export declare function insertPendingFlow(map: Map<string, PendingFlow>, state: string, flow: Omit<PendingFlow, "timer">, logger: GatewayLogger): void;
+/**
+ * Create the OAuth callback Hono sub-app.
+ *
+ * Mount via:
+ *   const app = new Hono();
+ *   app.route("/oauth", createOAuthCallbackRoute(deps));
+ * Resulting URL: GET /oauth/callback/:provider
+ */
+export declare function createOAuthCallbackRoute(deps: OAuthCallbackDeps): Hono;

package/node_modules/@comis/gateway/dist/oauth/oauth-callback-route.js

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OAuth callback route for the Comis gateway.
+ *
+ * Mounted at `GET /callback/:provider` via `app.route("/oauth", subApp)`. The
+ * handler validates code+state, looks up the state in the in-memory pending-
+ * flow map, verifies path-vs-flow provider match, deletes the entry BEFORE
+ * the token exchange (one-time-use invariant), exchanges the code at
+ * auth.openai.com/oauth/token, resolves identity via
+ * resolveCodexAuthIdentity, persists via OAuthCredentialStorePort.set, emits
+ * auth:profile_bootstrapped, and returns a static "Login Successful" HTML
+ * page (200) on success or a "Login Failed" HTML page (400/500) on failure.
+ *
+ * HTTP method is GET, NOT POST (OAuth servers always redirect with GET).
+ * Logging discipline (CLAUDE.md): submodule: "oauth-callback"
+ * on every line; NEVER log code/state/verifier/access/refresh values.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import { resolveCodexAuthIdentity, rewriteOAuthError, redactEmailForLog, } from "@comis/agent";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** 5-minute pending-flow expiry. Exported for test parity. */
+export const PENDING_FLOW_TIMEOUT_MS = 5 * 60_000;
+/** OpenAI Codex token endpoint — same as oauth-token-manager.ts:301. */
+const OPENAI_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** Public OpenAI Codex client_id (NOT a comis secret — per pi-ai source). */
+const OPENAI_CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+/** Redirect URI matches pi-ai device-callback convention. */
+const OPENAI_CODEX_DEVICE_CALLBACK_URL = "https://auth.openai.com/deviceauth/callback";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function oauthSuccessHtml(message) {
+    return [
+        "<!DOCTYPE html>",
+        '<html><head><meta charset="utf-8"><title>Login Successful</title>',
+        "<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:8em auto;padding:2em;text-align:center;color:#222}h1{color:#0a7d2c}</style>",
+        "</head><body><h1>Login Successful</h1>",
+        `<p>${escapeHtml(message)}</p>`,
+        "<p>You can close this window.</p>",
+        "</body></html>",
+    ].join("");
+}
+function oauthErrorHtml(message) {
+    return [
+        "<!DOCTYPE html>",
+        '<html><head><meta charset="utf-8"><title>Login Failed</title>',
+        "<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:8em auto;padding:2em;text-align:center;color:#222}h1{color:#b00020}</style>",
+        "</head><body><h1>Login Failed</h1>",
+        `<p>${escapeHtml(message)}</p>`,
+        "</body></html>",
+    ].join("");
+}
+/**
+ * Exchange an authorization_code at OpenAI's /oauth/token endpoint.
+ *
+ * Mirrors refreshOpenAICodexTokenLocal (oauth-token-manager.ts:298-385) but
+ * uses grant_type=authorization_code with code + code_verifier. Throws on
+ * non-OK status; the public boundary catches and routes through
+ * rewriteOAuthError.
+ */
+async function exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: params.code,
+        redirect_uri: OPENAI_CODEX_DEVICE_CALLBACK_URL,
+        client_id: OPENAI_CODEX_CLIENT_ID,
+        code_verifier: params.verifier,
+    });
+    const response = await fetch(OPENAI_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    if (!response.ok) {
+        let bodyText = "";
+        try {
+            bodyText = await response.text();
+        }
+        catch {
+            /* defensive — body read may fail */
+        }
+        // Surface the wire error verbatim so rewriteOAuthError can detect
+        // invalid_grant / unsupported_country_region_territory substrings.
+        throw new Error(`OAuth token exchange failed: HTTP ${response.status} ${bodyText}`);
+    }
+    const json = (await response.json());
+    return {
+        access: json.access_token,
+        refresh: json.refresh_token,
+        expires: Date.now() + json.expires_in * 1000,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public boundary
+// ---------------------------------------------------------------------------
+/**
+ * Seed the pending-flow map with a new state -> PendingFlow entry, scheduling
+ * a 5-minute auto-delete cleanup timer.
+ *
+ * The caller is responsible for generating `state` via crypto.randomBytes(16)
+ * — never hand-roll a PRNG.
+ */
+export function insertPendingFlow(map, state, flow, logger) {
+    const timer = setTimeout(() => {
+        map.delete(state);
+        logger.debug({ provider: flow.provider, submodule: "oauth-callback" }, "Pending OAuth flow expired");
+    }, PENDING_FLOW_TIMEOUT_MS);
+    map.set(state, { ...flow, timer });
+}
+/**
+ * Create the OAuth callback Hono sub-app.
+ *
+ * Mount via:
+ *   const app = new Hono();
+ *   app.route("/oauth", createOAuthCallbackRoute(deps));
+ * Resulting URL: GET /oauth/callback/:provider
+ */
+export function createOAuthCallbackRoute(deps) {
+    const app = new Hono();
+    app.get("/callback/:provider", async (c) => {
+        const provider = c.req.param("provider");
+        const code = c.req.query("code");
+        const state = c.req.query("state");
+        if (!state || !code) {
+            return c.html(oauthErrorHtml("Missing code or state parameter"), 400);
+        }
+        const flow = deps.pendingFlows.get(state);
+        if (!flow) {
+            // No log — stale browser tab is a benign user error (debug-level
+            // logging acceptable but not required by tests; keep silent here).
+            return c.html(oauthErrorHtml("Invalid or expired state"), 400);
+        }
+        if (flow.provider !== provider) {
+            // Preserve the entry — the legitimate provider's callback may still
+            // arrive.
+            return c.html(oauthErrorHtml("Provider mismatch"), 400);
+        }
+        // One-time-use: cancel the timer + remove the entry BEFORE the
+        // exchange so even a failed exchange does not leave a reusable state.
+        clearTimeout(flow.timer);
+        deps.pendingFlows.delete(state);
+        try {
+            const tokens = await exchangeAuthorizationCode({
+                code,
+                verifier: flow.verifier,
+            });
+            const identity = resolveCodexAuthIdentity({
+                accessToken: tokens.access,
+            });
+            const identityKey = identity.email ?? identity.profileName;
+            if (!identityKey) {
+                // Treat as identity_decode_failed; rewriteOAuthError will route
+                // the substring "Failed to extract accountId" to the right code.
+                throw new Error("Failed to extract accountId — identity decode failed");
+            }
+            const profileId = `${provider}:${identityKey}`;
+            const profile = {
+                provider,
+                profileId,
+                access: tokens.access,
+                refresh: tokens.refresh,
+                expires: tokens.expires,
+                email: identity.email,
+                displayName: identity.profileName,
+                version: 1,
+            };
+            const writeResult = await deps.credentialStore.set(profileId, profile);
+            if (!writeResult.ok) {
+                throw new Error(`Failed to persist OAuth profile: ${writeResult.error.message}`);
+            }
+            const identityForEvent = redactEmailForLog(identity.email) ??
+                identity.profileName ??
+                identityKey;
+            deps.eventBus.emit("auth:profile_bootstrapped", {
+                provider,
+                profileId,
+                identity: identityForEvent,
+                timestamp: Date.now(),
+            });
+            deps.logger.info({
+                provider,
+                profileId,
+                identity: identityForEvent,
+                submodule: "oauth-callback",
+            }, "Gateway OAuth callback success");
+            return c.html(oauthSuccessHtml("Login successful — you can close this window and return to Comis."));
+        }
+        catch (caught) {
+            const rewritten = rewriteOAuthError(caught);
+            deps.logger.warn({
+                provider,
+                errorKind: rewritten.errorKind,
+                hint: rewritten.hint,
+                submodule: "oauth-callback",
+            }, "OAuth callback exchange failed");
+            return c.html(oauthErrorHtml(rewritten.userMessage), 500);
+        }
+    });
+    return app;
+}

package/node_modules/@comis/gateway/dist/server/hono-server.d.ts

@@ -7,6 +7,8 @@ import type { HmacAlgorithm } from "../webhook/hmac-verifier.js";
 import { type TokenStore } from "../auth/token-auth.js";
 import { WsConnectionManager } from "../rpc/ws-handler.js";
 import { type WebhookHandler } from "../webhook/webhook-endpoint.js";
+import { type PendingFlow } from "../oauth/oauth-callback-route.js";
+import type { OAuthCredentialStorePort } from "@comis/core";
 /**
  * Logger interface for gateway server (minimal pino-compatible).
  */
@@ -41,6 +43,18 @@ export interface GatewayServerDeps {
         algorithm?: HmacAlgorithm;
         headerName?: string;
     };
+    /**
+     * Optional OAuth callback deps. When provided, the gateway mounts
+     * GET /oauth/callback/:provider for browser-redirect OAuth flows
+     * (web-UI-initiated logins). Pending-flow map is owned by the caller
+     * (e.g., setup-gateway.ts) so daemon restart cleanly drops all in-flight
+     * states.
+     */
+    readonly oauthCallbackDeps?: {
+        credentialStore: OAuthCredentialStorePort;
+        eventBus: TypedEventBus;
+        pendingFlows: Map<string, PendingFlow>;
+    };
     /** Optional hook runner for lifecycle hooks (no-op when absent) */
     readonly hookRunner?: HookRunner;
     /** Optional web dashboard deps (mount REST/SSE/static when provided) */