@gotcos/glasses-server 6.1.0

package/server/routes/openai-compat.ts

@@ -0,0 +1,446 @@
+// OpenAI-compatible /v1/chat/completions endpoint
+// Adapter for Even Realities "Add Agent" and any OpenAI-compatible client.
+// Accepts standard OpenAI format, routes through COS model-router, returns OpenAI format.
+// Supports both streaming (SSE) and non-streaming responses.
+
+import { Router } from 'express'
+import { preWarmCLI, logLatency } from '../lib/claude-bridge.js'
+import { callModelStreaming } from '../lib/model-router.js'
+import { normalizeModelPreference, type ModelPreference } from '../../shared/model-preference.js'
+import { tryInstantResponse } from '../lib/response-cache.js'
+import crypto from 'node:crypto'
+
+export const openaiCompatRouter = Router()
+
+// ─── Dedup guard — prevent Even from doubling server load ───
+// Maps query text → { promise, timestamp } for in-flight requests.
+// If the same query arrives within 2s of a pending request, reuse the result.
+const inflightQueries = new Map<string, { promise: Promise<string>; timestamp: number }>()
+const DEDUP_WINDOW_MS = 2000
+
+function cleanupInflight() {
+  const now = Date.now()
+  for (const [key, entry] of inflightQueries) {
+    if (now - entry.timestamp > 30000) inflightQueries.delete(key) // 30s max
+  }
+}
+
+// ─── Daily persistent session ───
+// Session persists across all G2 queries for the entire day, building context
+// as the user explores concepts, checks facts, follows threads.
+// Auto-resets at midnight to prevent context rot.
+// Say "reset session" or "new session" to force reset.
+let g2SessionId: string | undefined = undefined
+let g2SessionDate: string | undefined = undefined  // YYYY-MM-DD of current session
+
+function getOrResetG2Session(): string | undefined {
+  const today = new Date().toISOString().slice(0, 10)
+  if (g2SessionDate !== today) {
+    // New day — reset session to prevent context rot
+    g2SessionId = undefined
+    g2SessionDate = today
+    console.log(`[g2] Daily session reset (${today})`)
+    // Lazy pre-warm: fire-and-forget so next query has a warm CLI session
+    preWarmCLI().catch(() => {})
+  }
+  return g2SessionId
+}
+
+function shouldResetSession(query: string): boolean {
+  return /\b(reset session|new session|fresh start|clear context|start over)\b/i.test(query)
+}
+
+// Optional: validate Bearer token against COS_API_TOKEN
+function validateAuth(req: any, res: any): boolean {
+  const cosToken = process.env.COS_API_TOKEN
+  if (!cosToken) return true // No token configured = open access
+
+  const auth = req.headers['authorization']
+  if (!auth || !auth.startsWith('Bearer ')) {
+    res.status(401).json({ error: { message: 'Missing Bearer token', type: 'invalid_request_error' } })
+    return false
+  }
+
+  const token = auth.slice(7)
+  if (token !== cosToken) {
+    res.status(401).json({ error: { message: 'Invalid token', type: 'invalid_request_error' } })
+    return false
+  }
+
+  return true
+}
+
+// Resolve model from OpenAI-compatible model ids. Defaults to Haiku for
+// "Hey Even" speed; Opus/Sonnet/Haiku/Codex High can be explicitly selected.
+function resolveModel(model?: string, _query?: string): ModelPreference {
+  const normalized = normalizeModelPreference(model)
+  if (normalized) return normalized
+  if (model === 'cos-opus') return 'opus'
+  if (model === 'cos-sonnet') return 'sonnet'
+  if (model === 'cos-haiku') return 'haiku'
+  if (model === 'cos-codex-high' || model === 'cos-codex') return 'codex-high'
+  return normalizeModelPreference(process.env.COS_G2_DEFAULT_MODEL) ?? 'haiku'
+}
+
+const MODEL_NAMES: Record<ModelPreference, string> = {
+  opus: 'cos-opus',
+  sonnet: 'cos-sonnet',
+  haiku: 'cos-haiku',
+  'codex-high': 'cos-codex-high',
+}
+
+// Extract the user's latest message from the OpenAI messages array
+function extractUserQuery(messages: Array<{ role: string; content: string }>): string {
+  // Find the last user message
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'user' && messages[i].content) {
+      return messages[i].content
+    }
+  }
+  return ''
+}
+
+openaiCompatRouter.post('/v1/chat/completions', async (req, res) => {
+  if (!validateAuth(req, res)) return
+
+  const { messages, stream, model } = req.body
+
+  if (!messages || !Array.isArray(messages) || messages.length === 0) {
+    return res.status(400).json({
+      error: { message: 'messages array required', type: 'invalid_request_error' },
+    })
+  }
+
+  let query = extractUserQuery(messages)
+  if (!query) {
+    return res.status(400).json({
+      error: { message: 'No user message found', type: 'invalid_request_error' },
+    })
+  }
+
+
+  // Log request entry — tells us if Even sends stream: true or false
+  console.log(`[g2] Request: stream=${!!stream}, query="${query.slice(0, 50)}"`)
+
+  const requestReceivedAt = Date.now()
+  const resolvedModel = resolveModel(model, query)
+  const completionId = `chatcmpl-${crypto.randomUUID().slice(0, 12)}`
+  const timestamp = Math.floor(Date.now() / 1000)
+  const responseModel = MODEL_NAMES[resolvedModel]
+
+  // ── Predictive response cache — bypass Claude for common queries ──
+  const cached = tryInstantResponse(query)
+  if (cached) {
+    const ttfb = Date.now() - requestReceivedAt
+    logLatency({
+      timestamp: new Date().toISOString(),
+      query: query.slice(0, 50),
+      ttfb_ms: ttfb,
+      total_ms: ttfb,
+      model: 'cache',
+      resumed: false,
+      contextInjected: false,
+      cacheHit: true,
+    })
+    console.log(`[g2] Cache hit (${cached.pattern}): "${query}" → ${ttfb}ms`)
+
+    if (stream) {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    'Access-Control-Allow-Origin': '*',
+      })
+      res.flushHeaders()
+      const chunk = {
+        id: completionId,
+        object: 'chat.completion.chunk',
+        created: timestamp,
+        model: responseModel,
+        choices: [{ index: 0, delta: { content: cached.text }, finish_reason: null }],
+      }
+      res.write(`data: ${JSON.stringify(chunk)}\n\n`)
+      const finalChunk = {
+        id: completionId,
+        object: 'chat.completion.chunk',
+        created: timestamp,
+        model: responseModel,
+        choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+      }
+      res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
+      res.write('data: [DONE]\n\n')
+      res.end()
+      return
+    }
+
+    // Non-streaming cache response
+    return res.json({
+      id: completionId,
+      object: 'chat.completion',
+      created: timestamp,
+      model: responseModel,
+      choices: [{
+        index: 0,
+        message: { role: 'assistant', content: cached.text },
+        finish_reason: 'stop',
+      }],
+      usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    })
+  }
+
+  // ── Dedup guard — if same query is already in-flight within 2s, reuse result ──
+  cleanupInflight()
+  const dedupKey = `${resolvedModel}:${query.trim().toLowerCase()}`
+  const inflight = inflightQueries.get(dedupKey)
+  if (inflight && (Date.now() - inflight.timestamp) < DEDUP_WINDOW_MS) {
+    console.log(`[g2] Dedup hit: "${query.slice(0, 50)}" (waiting for in-flight result)`)
+    try {
+      const dedupResult = await inflight.promise
+      logLatency({
+        timestamp: new Date().toISOString(),
+        query: query.slice(0, 50),
+        ttfb_ms: Date.now() - requestReceivedAt,
+        total_ms: Date.now() - requestReceivedAt,
+        model: resolvedModel,
+        resumed: false,
+        contextInjected: false,
+        cacheHit: false,
+        deduped: true,
+      })
+      if (stream) {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection': 'keep-alive',
+          'X-Accel-Buffering': 'no',
+    'Access-Control-Allow-Origin': '*',
+        })
+        res.flushHeaders()
+        const chunk = {
+          id: completionId,
+          object: 'chat.completion.chunk',
+          created: timestamp,
+          model: responseModel,
+          choices: [{ index: 0, delta: { content: dedupResult }, finish_reason: null }],
+        }
+        res.write(`data: ${JSON.stringify(chunk)}\n\n`)
+        res.write(`data: ${JSON.stringify({ id: completionId, object: 'chat.completion.chunk', created: timestamp, model: responseModel, choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`)
+        res.write('data: [DONE]\n\n')
+        res.end()
+        return
+      }
+      return res.json({
+        id: completionId,
+        object: 'chat.completion',
+        created: timestamp,
+        model: responseModel,
+        choices: [{ index: 0, message: { role: 'assistant', content: dedupResult }, finish_reason: 'stop' }],
+        usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+      })
+    } catch {
+      // Original request failed — fall through to make a fresh request
+    }
+  }
+
+  // Register this query as in-flight for dedup
+  let resolveInflight: (text: string) => void
+  let rejectInflight: (err: any) => void
+  const inflightPromise = new Promise<string>((res, rej) => { resolveInflight = res; rejectInflight = rej })
+  inflightQueries.set(dedupKey, { promise: inflightPromise, timestamp: Date.now() })
+
+  // ── Streaming response (SSE) ──
+  if (stream) {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    'Access-Control-Allow-Origin': '*',
+    })
+    res.flushHeaders()
+
+    // Immediate keepalive — prevents ER app timeout while Claude processes
+    res.write(': keepalive\n\n')
+
+    let done = false
+    let firstChunkLogged = false
+    let actualTtfbMs = -1  // Captured at first chunk arrival
+
+    // Check for session reset command
+    if (shouldResetSession(query)) {
+      g2SessionId = undefined
+      g2SessionDate = new Date().toISOString().slice(0, 10)
+      console.log(`[g2] Manual session reset`)
+    }
+
+    const currentSessionId = getOrResetG2Session()
+
+    // Pass query directly — conciseness instruction is in the system prompt now
+    try {
+      const returnedSid = await callModelStreaming(query, currentSessionId, {
+        onChunk: (text) => {
+          if (!done) {
+            if (!firstChunkLogged) {
+              firstChunkLogged = true
+              actualTtfbMs = Date.now() - requestReceivedAt
+              console.log(`[g2] TTFB: ${actualTtfbMs}ms (${resolvedModel}, session: ${currentSessionId ? 'resumed' : 'new'})`)
+            }
+            const chunk = {
+              id: completionId,
+              object: 'chat.completion.chunk',
+              created: timestamp,
+              model: responseModel,
+              choices: [{ index: 0, delta: { content: text }, finish_reason: null }],
+            }
+            res.write(`data: ${JSON.stringify(chunk)}\n\n`)
+          }
+        },
+        onDone: (fullText) => {
+          if (!done) {
+            done = true
+            resolveInflight!(fullText || '')
+            inflightQueries.delete(dedupKey)
+            logLatency({
+              timestamp: new Date().toISOString(),
+              query: query.slice(0, 50),
+              ttfb_ms: actualTtfbMs,
+              total_ms: Date.now() - requestReceivedAt,
+              model: resolvedModel,
+              resumed: !!currentSessionId,
+              contextInjected: /\b(schedule|calendar|meeting|task|tasks|today|tomorrow|next meeting|who do i meet|what's next)\b/i.test(query),
+              cacheHit: false,
+              stream_requested: true,
+            })
+            // Final chunk with finish_reason
+            const finalChunk = {
+              id: completionId,
+              object: 'chat.completion.chunk',
+              created: timestamp,
+              model: responseModel,
+              choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+            }
+            res.write(`data: ${JSON.stringify(finalChunk)}\n\n`)
+            res.write('data: [DONE]\n\n')
+            res.end()
+          }
+        },
+        onError: (error) => {
+          if (!done) {
+            done = true
+            rejectInflight!(new Error(error))
+            inflightQueries.delete(dedupKey)
+            const errChunk = {
+              id: completionId,
+              object: 'chat.completion.chunk',
+              created: timestamp,
+              model: responseModel,
+              choices: [{ index: 0, delta: { content: `Error: ${error}` }, finish_reason: 'stop' }],
+            }
+            res.write(`data: ${JSON.stringify(errChunk)}\n\n`)
+            res.write('data: [DONE]\n\n')
+            res.end()
+          }
+        },
+        onToolStatus: (status) => {
+          if (!done) {
+            // SSE comment — invisible to JSON parsers but keeps connection alive
+            res.write(`: ${status}\n\n`)
+          }
+        },
+        onStart: () => {},
+      }, resolvedModel, undefined, undefined, undefined, { lightweight: true })
+      // Persist session ID for multi-turn context on subsequent G2 queries
+      g2SessionId = returnedSid
+    } catch (err: any) {
+      if (!done) {
+        done = true
+        rejectInflight!(err)
+        inflightQueries.delete(dedupKey)
+        res.write(`data: ${JSON.stringify({ error: { message: err.message } })}\n\n`)
+        res.write('data: [DONE]\n\n')
+        res.end()
+      }
+    }
+
+    req.on('close', () => { done = true })
+    return
+  }
+
+  // ── Non-streaming response ──
+  // Check for session reset command
+  if (shouldResetSession(query)) {
+    g2SessionId = undefined
+    g2SessionDate = new Date().toISOString().slice(0, 10)
+    console.log(`[g2] Manual session reset (non-stream)`)
+  }
+
+  const currentSessionIdNS = getOrResetG2Session()
+
+  try {
+    const fullText = await new Promise<string>((resolve, reject) => {
+      let result = ''
+      let nsFirstChunkMs = -1
+      callModelStreaming(query, currentSessionIdNS, {
+        onChunk: (text) => {
+          if (nsFirstChunkMs < 0) nsFirstChunkMs = Date.now() - requestReceivedAt
+          result += text
+        },
+        onDone: (fullText) => {
+          const text = fullText || result
+          resolveInflight!(text)
+          inflightQueries.delete(dedupKey)
+          logLatency({
+            timestamp: new Date().toISOString(),
+            query: query.slice(0, 50),
+            ttfb_ms: nsFirstChunkMs,
+            total_ms: Date.now() - requestReceivedAt,
+            model: resolvedModel,
+            resumed: !!currentSessionIdNS,
+            contextInjected: /\b(schedule|calendar|meeting|task|tasks|today|tomorrow)\b/i.test(query),
+            cacheHit: false,
+            stream_requested: false,
+          })
+          resolve(text)
+        },
+        onError: (error) => {
+          rejectInflight!(new Error(error))
+          inflightQueries.delete(dedupKey)
+          reject(new Error(error))
+        },
+        onToolStatus: () => {},
+        onStart: () => {},
+      }, resolvedModel, undefined, undefined, undefined, { lightweight: true }).then(sid => { g2SessionId = sid })
+    })
+
+    res.json({
+      id: completionId,
+      object: 'chat.completion',
+      created: timestamp,
+      model: responseModel,
+      choices: [{
+        index: 0,
+        message: { role: 'assistant', content: fullText },
+        finish_reason: 'stop',
+      }],
+      usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    })
+  } catch (err: any) {
+    res.status(500).json({
+      error: { message: err.message, type: 'server_error' },
+    })
+  }
+})
+
+// GET /v1/models — required by some clients for model discovery
+openaiCompatRouter.get('/v1/models', (_req, res) => {
+  res.json({
+    object: 'list',
+    data: [
+	      { id: 'cos-opus', object: 'model', created: 1709251200, owned_by: 'cos' },
+	      { id: 'cos-sonnet', object: 'model', created: 1709251200, owned_by: 'cos' },
+	      { id: 'cos-haiku', object: 'model', created: 1709251200, owned_by: 'cos' },
+	      { id: 'cos-codex-high', object: 'model', created: 1709251200, owned_by: 'cos' },
+	    ],
+	  })
+	})

package/server/routes/openai-key.ts

@@ -0,0 +1,121 @@
+// OpenAI key management endpoints — phone-side Settings panel writes the key
+// here so users never have to edit a .env file or rerun the wizard.
+//
+// Wire-protocol contract: the key is push-only. The phone POSTs it to /set;
+// the server validates against OpenAI, persists to server/data/openai-key.json,
+// and from then on only ever returns metadata (hasKey/source/savedAt/...). The
+// raw key value is never echoed back to any client. Same intent as the
+// existing /api/tts/* contract that the OPENAI_API_KEY must never reach the
+// client.
+//
+// Resolution priority is enforced upstream by openai-key.ts:
+//   env > server/data/openai-key.json > COS scripts .env regex
+// So saving via Settings is a no-op when an env-level OPENAI_API_KEY exists.
+// /status reflects that honestly so the UI can render "Active (env)" instead
+// of pretending the saved value is in use.
+
+import { Router } from 'express'
+import { existsSync, mkdirSync, unlinkSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { errMsg } from '../lib/utils.js'
+import { atomicWriteFileSync } from '../lib/atomic-fs.js'
+import { KEY_FILE_PATH, clearCachedKey, getKeyStatus } from '../lib/openai-key.js'
+
+export const openaiKeyRouter = Router()
+
+/** Validate a candidate key by listing models. The /v1/models endpoint is
+ *  cheap (returns ~50 model IDs in JSON), supported by every OpenAI-compatible
+ *  proxy, and returns 401 on a bad key — so a successful 200 confirms the key
+ *  works for our usage without billing anything. */
+async function validateKey(key: string): Promise<{ ok: true } | { ok: false; status: number; reason: string }> {
+  try {
+    const res = await fetch('https://api.openai.com/v1/models', {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(8_000),
+    })
+    if (res.ok) return { ok: true }
+    const body = await res.text().catch(() => '')
+    return {
+      ok: false,
+      status: res.status,
+      reason: body.slice(0, 200) || `OpenAI returned ${res.status}`,
+    }
+  } catch (err) {
+    return { ok: false, status: 0, reason: errMsg(err) }
+  }
+}
+
+// POST /api/openai-key/set — body { key }. Validates against OpenAI then
+// writes server/data/openai-key.json. Returns metadata only.
+openaiKeyRouter.post('/openai-key/set', async (req, res) => {
+  try {
+    const raw = req.body?.key
+    if (typeof raw !== 'string') {
+      return res.status(400).json({ error: 'key is required (string)' })
+    }
+    const key = raw.trim()
+    if (!key) {
+      return res.status(400).json({ error: 'key is empty after trim' })
+    }
+    // Light shape check — sk- prefix is the historical OpenAI convention but
+    // proxies (Azure, third-party gateways) use other prefixes too. Length is
+    // the safer guard. We rely on the live /v1/models call to reject bad keys.
+    if (key.length < 16 || key.length > 512) {
+      return res.status(400).json({ error: 'key length looks wrong (expected 16-512 chars)' })
+    }
+
+    const validation = await validateKey(key)
+    if (!validation.ok) {
+      return res.status(400).json({
+        error: `validation failed: ${validation.reason}`,
+        upstreamStatus: validation.status,
+      })
+    }
+
+    const now = new Date().toISOString()
+    const payload = JSON.stringify({ key, savedAt: now, validatedAt: now }, null, 2)
+
+    // Ensure parent dir exists (server/data/ is gitignored but may not exist
+    // on a fresh checkout that's never run a budget write).
+    const parent = dirname(KEY_FILE_PATH)
+    if (!existsSync(parent)) mkdirSync(parent, { recursive: true })
+
+    atomicWriteFileSync(KEY_FILE_PATH, payload)
+    clearCachedKey()
+
+    const status = getKeyStatus()
+    return res.json({
+      ok: true,
+      validatedAt: now,
+      // Echo back the resolved source — if env is set, source will still be
+      // 'env' here (env wins over the file we just wrote). The client uses
+      // this to surface "Saved (but env override is active)" when relevant.
+      activeSource: status.source,
+    })
+  } catch (err) {
+    return res.status(500).json({ error: errMsg(err) })
+  }
+})
+
+// GET /api/openai-key/status — { hasKey, source, savedAt?, validatedAt? }.
+// Never returns the key value.
+openaiKeyRouter.get('/openai-key/status', (_req, res) => {
+  try {
+    return res.json(getKeyStatus())
+  } catch (err) {
+    return res.status(500).json({ error: errMsg(err) })
+  }
+})
+
+// DELETE /api/openai-key — removes server/data/openai-key.json. The env or
+// scripts-env source (if set) takes over on the next resolve.
+openaiKeyRouter.delete('/openai-key', (_req, res) => {
+  try {
+    if (existsSync(KEY_FILE_PATH)) unlinkSync(KEY_FILE_PATH)
+    clearCachedKey()
+    return res.json({ ok: true, ...getKeyStatus() })
+  } catch (err) {
+    return res.status(500).json({ error: errMsg(err) })
+  }
+})

package/server/routes/query.ts

@@ -0,0 +1,121 @@
+// POST /api/query — streaming SSE endpoint for Claude queries
+// Returns text/event-stream with chunk, done, and error events
+
+import { Router } from 'express'
+import { callModelStreaming } from '../lib/model-router.js'
+import { emitDisplay } from '../lib/display-bus.js'
+import { errMsg } from '../lib/utils.js'
+import { normalizeModelPreference } from '../../shared/model-preference.js'
+
+const TOOL_STATUS_MESSAGES: Record<string, string> = {
+  WebSearch: 'Searching web...',
+  WebFetch: 'Reading page...',
+  Read: 'Analyzing photo...',
+}
+
+export const queryRouter = Router()
+
+queryRouter.post('/query', async (req, res) => {
+  const { query, sessionId, model, image, images, reference, globalMsgNum } = req.body
+
+  // Normalize: accept `images` array or legacy `image` string
+  let validImages: string[] | undefined
+  if (Array.isArray(images) && images.length > 0) {
+    // Filter to valid non-empty strings, cap at 5
+    validImages = images.filter((img: unknown) => typeof img === 'string' && img.length > 0).slice(0, 5)
+    if (validImages.length === 0) validImages = undefined
+  } else if (typeof image === 'string' && image.length > 0) {
+    // Backward compat: wrap single image as array
+    validImages = [image]
+  }
+
+  const resolvedQuery = typeof query === 'string' ? query : ''
+
+  // Vision queries can have an empty query (default to "describe what you see")
+  if ((!resolvedQuery || typeof resolvedQuery !== 'string') && !validImages) {
+    return res.status(400).json({ error: 'query string or image required' })
+  }
+
+  // Validate model if provided
+  const validModel = normalizeModelPreference(model)
+
+  // Validate globalMsgNum if provided
+  const validGlobalMsgNum = typeof globalMsgNum === 'number' && globalMsgNum > 0
+    ? globalMsgNum : undefined
+
+  // Set up SSE headers
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no',  // Disable nginx buffering if proxied
+    'Access-Control-Allow-Origin': '*',  // Even Hub WebView loads from file://
+  })
+
+  // Flush headers immediately
+  res.flushHeaders()
+  res.write(': keepalive\n\n')
+
+  let done = false
+  const abortController = new AbortController()
+  res.on('close', () => {
+    if (!done) abortController.abort()
+    done = true
+  })
+
+  try {
+    const sid = await callModelStreaming(resolvedQuery || '', sessionId, {
+      onStart: (model, sid, cliSessionId, metadata) => {
+        if (!done) {
+          const payload = { model, sessionId: sid, cliSessionId, ...metadata }
+          res.write(`event: start\ndata: ${JSON.stringify(payload)}\n\n`)
+          emitDisplay({ type: 'start', data: payload })
+        }
+      },
+      onChunk: (text) => {
+        if (!done) {
+          res.write(`event: chunk\ndata: ${JSON.stringify({ text })}\n\n`)
+          emitDisplay({ type: 'chunk', data: { text } })
+        }
+      },
+      onToolStatus: (toolName) => {
+        if (!done) {
+          const message = TOOL_STATUS_MESSAGES[toolName] ?? (/\s|\.{3}$/.test(toolName) ? toolName : `Using ${toolName}...`)
+          res.write(`event: tool_status\ndata: ${JSON.stringify({ message })}\n\n`)
+          emitDisplay({ type: 'tool_status', data: { message } })
+        }
+      },
+      onDone: (fullText, model, cliSessionId, metadata) => {
+        if (!done) {
+          done = true
+          const payload = { text: fullText, sessionId: sid, model, cliSessionId, ...metadata }
+          res.write(`event: done\ndata: ${JSON.stringify(payload)}\n\n`)
+          emitDisplay({ type: 'done', data: payload })
+          res.end()
+        }
+      },
+      onError: (error) => {
+        if (!done) {
+          done = true
+          res.write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`)
+          emitDisplay({ type: 'error', data: { error } })
+          res.end()
+        }
+      },
+    }, validModel, validImages,
+      // Pass reference if provided (for "recall message N" feature)
+      reference && typeof reference === 'object' && reference.query && reference.response
+        ? { query: String(reference.query), response: String(reference.response) }
+        : undefined,
+      validGlobalMsgNum,
+      { abortSignal: abortController.signal },
+    )
+  } catch (err: unknown) {
+    if (!done) {
+      done = true
+      res.write(`event: error\ndata: ${JSON.stringify({ error: errMsg(err) })}\n\n`)
+      res.end()
+    }
+  }
+
+})