Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
56.8 KB
Raw Blame
import type { Request, Response } from 'express'
import { parseIncomingFileReferences } from '../agent/fileReferenceResolver'
import { config } from '../config'
import { ConversationError, ConversationErrorCode } from '../core/errors'
import type { ApprovalDecision } from '../core/extensions/approvalTypes'
import { isTraceContextV1 } from '../core/types'
import { logger } from '../logger'
import { getRuntimeCallerContext } from './edgeRuntimeAuth'
import { badRequest, json } from './httpUtils'
import type {
  ActivitySnapshotHandler,
  ActivityStreamHandler,
  ApprovalHandler,
  CompactionHandler,
  ContextBreakdownHandler,
  CronResultAckHandler,
  CronResultsHandler,
  HostActivityEvent,
  IncomingMessage,
  MessageHandler,
  ModelsListHandler,
  ProgressStreamHandler,
  ProviderMessageAuthorizationHandler,
  ProviderWorkflowApprovalDecision,
  ProviderWorkflowApprovalDecisionHandler,
  ProviderWorkflowApprovalResolve,
  ProviderWorkflowApprovalResolveHandler,
  ProviderWorkflowResultRequest,
  ProviderWorkflowResultRequestHandler,
  SessionMessagesHandler,
  SessionSearchHandler,
  SessionsListHandler,
  SetModelHandler,
  SetTitleHandler,
  StatusHandler,
  TaskResultHandler,
  TelegramWorkflowApprovalVerificationHandler,
  WorkflowApprovalMediumEnrollmentHandler,
  WorkflowApprovalNotificationClaimHandler,
  WorkflowApprovalNotificationTerminalHandler,
} from './types'
import type { RuntimeCallerContext } from './types'
import { decodeSessionsCursor, sessionsCursorScope } from './wireProjections'

/** Narrows an untrusted body field to the CAS revision the model routes accept,
 *  so the call site needs no cast to drop `unknown`. */
function isNonNegativeSafeInteger(value: unknown): value is number {
  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
}

export type RouteHandlers = {
  messageHandler: MessageHandler | null
  statusHandler: StatusHandler | null
  approvalHandler: ApprovalHandler | null
  providerWorkflowApprovalDecisionHandler: ProviderWorkflowApprovalDecisionHandler | null
  providerWorkflowApprovalResolveHandler: ProviderWorkflowApprovalResolveHandler | null
  providerWorkflowResultRequestHandler: ProviderWorkflowResultRequestHandler | null
  providerMessageAuthorizationHandler: ProviderMessageAuthorizationHandler | null
  workflowApprovalNotificationClaimHandler: WorkflowApprovalNotificationClaimHandler | null
  workflowApprovalNotificationTerminalHandler: WorkflowApprovalNotificationTerminalHandler | null
  workflowApprovalMediumEnrollmentHandler: WorkflowApprovalMediumEnrollmentHandler | null
  telegramWorkflowApprovalVerificationHandler: TelegramWorkflowApprovalVerificationHandler | null
  activitySnapshotHandler: ActivitySnapshotHandler | null
  activityStreamHandler: ActivityStreamHandler | null
  taskResultHandler: TaskResultHandler | null
  cronResultsHandler: CronResultsHandler | null
  cronResultAckHandler: CronResultAckHandler | null
  progressStreamHandler?: ProgressStreamHandler
  sessionsListHandler: SessionsListHandler | null
  sessionMessagesHandler: SessionMessagesHandler | null
  contextBreakdownHandler?: ContextBreakdownHandler | null
  sessionSearchHandler?: SessionSearchHandler | null
  compactionHandler?: CompactionHandler | null
  modelsListHandler?: ModelsListHandler | null
  setModelHandler?: SetModelHandler | null
  setTitleHandler?: SetTitleHandler | null
}

function isSessionOwnershipError(error: unknown): boolean {
  return (
    error instanceof ConversationError && error.code === ConversationErrorCode.OwnershipMismatch
  )
}

function parseSessionsCursorParam(
  cursor: unknown,
  expectedScope: string
): string | undefined | null {
  if (cursor === undefined) return undefined
  if (typeof cursor !== 'string' || cursor.length > 2048) return null
  return decodeSessionsCursor(cursor, expectedScope) ? cursor : null
}

function parseUnsignedIntegerParam(value: unknown): number | undefined | null {
  if (value === undefined) return undefined
  if (typeof value !== 'string' || !/^\d+$/.test(value)) return null
  const parsed = Number(value)
  return Number.isSafeInteger(parsed) ? parsed : null
}

function hasBracketedQueryVariant(query: Request['query'], names: string[]): boolean {
  return Object.keys(query).some(key => names.some(name => key.startsWith(`${name}[`)))
}

// Server-side hard caps on client-supplied page sizes. The proxy applies its
// own caps at the edge; these are the host's independent enforcement (the two
// services share no package, so each names its own constants).
const SESSIONS_LIMIT_CAP = 100
const MESSAGES_LIMIT_CAP = 200

function isSafeRouteSegment(value: string): boolean {
  return (
    value.length > 0 &&
    value !== '.' &&
    value !== '..' &&
    value.length <= 500 &&
    !/[/\\\u0000-\u001f\u007f]/.test(value)
  )
}

function isSafeAgentRouteSegment(value: string): boolean {
  return isSafeRouteSegment(value) && value.length <= 200 && !value.includes(':')
}

function channelRuntimeSourceMismatch(
  caller: RuntimeCallerContext | undefined,
  source: { channelType?: string; channelId?: string; sender?: string }
): boolean {
  if (
    caller?.caller !== 'channel-reader' &&
    caller?.caller !== 'workflow-approval-request-reader'
  ) {
    return false
  }
  return (
    caller.channelType !== source.channelType ||
    caller.channelId !== source.channelId ||
    caller.sender !== source.sender
  )
}

export function runtimeApiInfo() {
  return {
    name: 'MCP Host',
    description: 'AI agent service with message queue and state machine',
    version: '1.0.0',
    endpoints: {
      'GET /v1/runtime': 'Runtime API information page',
      'GET /v1/runtime/health': 'Health check endpoint',
      'GET /v1/runtime/live': 'Liveness check endpoint',
      'GET /metrics': 'Prometheus metrics endpoint',
      'GET /v1/runtime/status': 'Get agent and queue status (includes pendingApprovals)',
      'GET /v1/runtime/activity': 'Get host activity timeline snapshot',
      'GET /v1/runtime/activity/stream': 'Read-only host activity stream (SSE)',
      'POST /v1/runtime/messages': 'Submit a message for processing',
      'POST /v1/runtime/provider-messages/authorize':
        'Authorize a provider message against current identity and channel access',
      'POST /v1/runtime/approvals/approve': 'Approve a pending tool execution',
      'POST /v1/runtime/approvals/deny': 'Deny a pending tool execution',
      'POST /v1/runtime/workflow-approvals/decide':
        'Submit a provider-originated workflow approval decision',
      'POST /v1/runtime/workflow-approvals/resolve':
        'Resolve a provider-originated pending workflow approval through the host',
      'POST /v1/runtime/workflow-results/latest':
        'Download the latest workflow result artifact for a verified provider conversation',
      'POST /v1/runtime/workflow-approval-notifications/claim':
        'Claim workflow approval notifications through the host',
      'POST /v1/runtime/workflow-approval-notifications/deliveries/:id/:action':
        'Ack or fail workflow approval notification delivery through the host',
      'POST /v1/runtime/workflow-approval-mediums/telegram/challenges/confirm-provider-event':
        'Confirm a Telegram workflow approval verification challenge through the host',
      'GET /v1/runtime/tasks/:taskId/progress/stream': 'Task-scoped progress event stream (SSE)',
      'GET /v1/runtime/tasks/:id/result': 'Poll for task result after approval',
      'GET /v1/runtime/cron/results': 'Get pending cron task results for delivery',
      'DELETE /v1/runtime/cron/results/:id': 'Acknowledge cron result delivery',
      'GET /v1/runtime/sessions': 'List active sessions for the authenticated user',
      'GET /v1/runtime/sessions/:agent/:chatId/messages': 'Get message history for a session',
      'PATCH /v1/runtime/sessions/:agent/:chatId/name':
        'Rename a session (server-authoritative title)',
      'GET /v1/runtime/sessions/search':
        'Full-text search across past messages of the authenticated user',
      'GET /v1/runtime/models': 'List selectable models for the session (per-session selection)',
      'POST /v1/runtime/model': 'Set the per-session model (applies next task)',
      'POST /v1/runtime/compact':
        'Force compaction for a session with optional focus topic (operator-only)',
    },
    rpcCounterparts: {
      'GET /v1/runtime/status': 'onStatus(handler)',
      'GET /v1/runtime/activity': 'onActivitySnapshot(handler)',
      'GET /v1/runtime/activity/stream': 'onActivityStream(handler)',
      'POST /v1/runtime/messages': 'onMessage(handler)',
      'POST /v1/runtime/provider-messages/authorize': 'onProviderMessageAuthorization(handler)',
      'POST /v1/runtime/approvals/approve': 'onApproval(handler)',
      'POST /v1/runtime/approvals/deny': 'onApproval(handler)',
      'POST /v1/runtime/workflow-approvals/decide': 'onProviderWorkflowApprovalDecision(handler)',
      'POST /v1/runtime/workflow-approvals/resolve': 'onProviderWorkflowApprovalResolve(handler)',
      'POST /v1/runtime/workflow-results/latest': 'onProviderWorkflowResultRequest(handler)',
      'POST /v1/runtime/workflow-approval-notifications/claim':
        'onWorkflowApprovalNotificationClaim(handler)',
      'POST /v1/runtime/workflow-approval-notifications/deliveries/:id/:action':
        'onWorkflowApprovalNotificationTerminal(handler)',
      'POST /v1/runtime/workflow-approval-mediums/telegram/challenges/confirm-provider-event':
        'onTelegramWorkflowApprovalVerification(handler)',
      'GET /v1/runtime/tasks/:taskId/progress/stream': 'onProgressStream(handler)',
      'GET /v1/runtime/tasks/:id/result': 'onTaskResult(handler)',
      'GET /v1/runtime/cron/results': 'onCronResults(handler)',
      'DELETE /v1/runtime/cron/results/:id': 'onCronResultAck(handler)',
      'GET /v1/runtime/sessions': 'onSessionsList(handler)',
      'GET /v1/runtime/sessions/:agent/:chatId/messages': 'onSessionMessages(handler)',
      'PATCH /v1/runtime/sessions/:agent/:chatId/name': 'onSetTitle(handler)',
      'GET /v1/runtime/sessions/search': 'onSessionSearch(handler)',
      'GET /v1/runtime/models': 'onModelsList(handler)',
      'POST /v1/runtime/model': 'onSetModel(handler)',
      'POST /v1/runtime/compact': 'onCompaction(handler)',
    },
  }
}

/**
 * T1.1 — POST /v1/runtime/compact. Force compaction for a single session.
 * Wraps the injected handler and translates the discriminated `CompactionResult`
 * into HTTP status codes. Authz via `requireScope('host:compaction:invoke')`
 * is applied at the server layer.
 */
export async function handleCompactionRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.compactionHandler) {
      json(res, 501, { error: 'Compaction handler not configured' })
      return
    }
    const body = (req.body as Record<string, unknown>) || {}
    const queryFocus = typeof req.query.focus === 'string' ? req.query.focus : undefined
    const bodyFocus = typeof body.focus === 'string' ? body.focus : undefined
    const sessionKey = typeof body.sessionKey === 'string' ? body.sessionKey.trim() : ''
    const useMainLlm = typeof body.useMainLlm === 'boolean' ? body.useMainLlm : undefined

    if (!sessionKey) {
      badRequest(res, 'sessionKey required')
      return
    }

    const focus = (queryFocus || bodyFocus)?.trim() || undefined
    const result = await handlers.compactionHandler({ sessionKey, focus, useMainLlm })

    switch (result.kind) {
      case 'ok':
        json(res, 200, {
          ok: true,
          before: result.before,
          after: result.after,
          focus: result.focus,
        })
        return
      case 'not_found':
        json(res, 404, { error: 'session not found' })
        return
      case 'pending_approval':
        json(res, 409, { error: 'cannot compact while approval pending' })
        return
      case 'session_busy':
        json(res, 409, { error: 'session is currently busy — retry once idle' })
        return
      case 'error':
        json(res, 500, { error: result.message })
        return
      default: {
        const _exhaustive: never = result
        void _exhaustive
        json(res, 500, { error: 'unknown compaction result' })
      }
    }
  } catch (error) {
    logger.error({ err: error }, '[Server] Error during compaction')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

export async function handleStatusRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.statusHandler) {
      json(res, 200, { status: 'ok', message: 'Status handler not configured' })
      return
    }

    const status = await handlers.statusHandler()
    json(res, 200, status)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error getting status')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

export async function handleMessageRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const message = req.body as IncomingMessage

    if (typeof message?.content !== 'string') {
      badRequest(res, 'content must be a string')
      return
    }

    if (message?.traceContext != null && !isTraceContextV1(message.traceContext)) {
      badRequest(res, 'Invalid traceContext')
      return
    }

    // Identity invariant for the desktop / rpc channel: the sender MUST be the
    // trusted rpc-proxy edge user, regardless of what the body claims.
    // rpc-proxy already does this; re-enforcing here is defense-in-depth for
    // the direct rpc-proxy -> mcp-host hop after removing forwarded JWT.
    //
    if (message?.channelType === 'rpc') {
      const caller = getRuntimeCallerContext(req)
      if (caller?.caller === 'rpc-proxy' && caller.userId) {
        message.sender = caller.userId
        if (caller.teamId) {
          message.metadata = { ...(message.metadata ?? {}), teamId: caller.teamId }
        }
      } else {
        json(res, 401, { error: 'Missing rpc edge caller context' })
        return
      }
    } else {
      const caller = getRuntimeCallerContext(req)
      if (
        caller?.caller !== 'channel-reader' &&
        caller?.caller !== 'workflow-approval-request-reader'
      ) {
        json(res, 403, { error: 'Runtime edge source mismatch' })
        return
      }
      if (
        channelRuntimeSourceMismatch(caller, {
          channelType: message.channelType,
          channelId: message.channelId,
          sender: message.sender,
        })
      ) {
        json(res, 403, { error: 'Runtime edge source mismatch' })
        return
      }
    }

    // Issue #666 — after the caller checks, so an unauthenticated request learns
    // nothing about the reference limit. A malformed reference or an unknown schema version refuses
    // the whole message: the turn must not run without the file it names. The
    // refusal is a 200 `MessageResponse`, like every other admission refusal,
    // so rpc-proxy relays its code instead of reporting a failed upstream.
    const fileReferences = parseIncomingFileReferences(
      message.fileReferences,
      config.fileReferenceMaxCount
    )
    if (!fileReferences.ok) {
      json(res, 200, {
        success: false,
        error: {
          code: fileReferences.code,
          message: fileReferences.message,
          retryable: false,
          provider: 'unknown',
        },
      })
      return
    }
    message.fileReferences = fileReferences.references.length
      ? fileReferences.references
      : undefined

    logger.info(
      { channelType: message.channelType, sender: message.sender },
      '[Server] Received message'
    )

    if (!handlers.messageHandler) {
      json(res, 500, { success: false, error: 'No message handler configured' })
      return
    }

    const isAsync = req.query.async === 'true'
    // Await BOTH branches. `executeAsync()` returns its ack (`{ taskId, ... }`)
    // synchronously, so awaiting it is a no-op and the background task still
    // runs fire-and-forget. But the piggybacked-model path wraps the handler in
    // an async IIFE (it must persist `message.model` before enqueue), so the
    // async branch can return a Promise; without this await `json()` would
    // `JSON.stringify` a Promise to `{}` and drop `taskId`.
    const response = await handlers.messageHandler(message, isAsync ? { async: true } : undefined)
    json(res, 200, response)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error processing message')
    if (isSessionOwnershipError(error)) {
      json(res, 403, { success: false, error: 'session access denied' })
      return
    }
    json(res, 500, {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    })
  }
}

export async function handleActivityRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.activitySnapshotHandler) {
      json(res, 501, { hostRef: 'unknown', version: '1.0', items: [], nextCursor: null })
      return
    }
    const limitRaw = String(req.query.limit || '50')
    const limit = Number(limitRaw)
    if (!Number.isFinite(limit) || limit <= 0) {
      badRequest(res, 'limit must be a positive number')
      return
    }
    const sinceEventId =
      typeof req.query.sinceEventId === 'string' ? req.query.sinceEventId : undefined
    const snapshot = await handlers.activitySnapshotHandler(limit, sinceEventId)
    json(res, 200, snapshot)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error getting activity snapshot')
    json(res, 500, { error: 'Activity unavailable' })
  }
}

function writeSseEvent(res: Response, eventName: string, data: unknown): void {
  res.write(`event: ${eventName}\n`)
  res.write(`data: ${JSON.stringify(data)}\n\n`)
}

export async function handleActivityStreamRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  if (!handlers.activityStreamHandler) {
    json(res, 501, { error: 'Activity stream unavailable' })
    return
  }

  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache, no-transform')
  res.setHeader('Connection', 'keep-alive')
  res.flushHeaders()

  let unsubscribe: (() => void) | null = null
  const cleanup = (reason: string) => {
    if (unsubscribe) {
      unsubscribe()
      unsubscribe = null
    }
    writeSseEvent(res, 'closed', { reason })
    res.end()
  }

  try {
    const registration = handlers.activityStreamHandler((event: HostActivityEvent) => {
      writeSseEvent(res, 'activity', event)
    })
    unsubscribe = registration.unsubscribe
    writeSseEvent(res, 'open', { hostRef: registration.hostRef, ts: new Date().toISOString() })

    const keepalive = setInterval(() => {
      res.write(': keepalive\n\n')
    }, 15000)

    req.on('close', () => {
      clearInterval(keepalive)
      if (unsubscribe) unsubscribe()
    })
  } catch {
    writeSseEvent(res, 'error', { message: 'Activity stream unavailable' })
    cleanup('upstream_unavailable')
  }
}

/**
 * IronClaw invariant #2 (P.3 §4.4): the resume after approve is fire-and-forget
 * inside `AgentStateMachine.handleApproval` (stateMachine.ts:346). If the
 * resume fails with `approval_expired` (spillover refs gone), this endpoint
 * still returns 200 OK with `{ success: true }`. The user-visible error
 * surfaces via the SSE `task:failed` event with `error.code = 'approval_expired'`
 * → ChannelDispatcher routes it back to Telegram/Slack/Email/Desktop.
 *
 * Returning 410 here would force callers to wait minutes for the resume
 * (re-execution of the remaining batch after the approved tool) before
 * acknowledging the click — not worth the latency.
 */
export async function handleApprovalRoute(
  req: Request,
  res: Response,
  approved: boolean,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.approvalHandler) {
      json(res, 501, { success: false, error: 'Approval handler not configured' })
      return
    }

    const parsed = req.body as Record<string, unknown>
    const caller = getRuntimeCallerContext(req)

    if (caller?.caller === 'rpc-proxy' && !caller.userId) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }

    const userId =
      caller?.caller === 'rpc-proxy' ? caller.userId : (parsed.userId as string | undefined)
    const requestId = parsed.requestId as string | undefined
    if (!userId || !requestId) {
      badRequest(res, 'Missing userId or requestId')
      return
    }

    let channelType = parsed.channelType as string | undefined
    let channelId = parsed.channelId as string | undefined
    if (caller?.caller === 'rpc-proxy') {
      channelType = 'rpc'
      channelId = caller.hostRef
    } else {
      if (
        channelRuntimeSourceMismatch(caller, {
          channelType,
          channelId,
          sender: userId,
        })
      ) {
        json(res, 403, { error: 'Runtime edge source mismatch' })
        return
      }
    }

    const decision: ApprovalDecision = {
      userId,
      requestId,
      approved,
      alwaysApprove: approved ? (parsed.alwaysApprove as boolean) || false : false,
      channelType,
      channelId,
    }

    logger.info(
      { detail: approved ? 'Approval' : 'Denial', userId: userId, requestId: requestId },
      '[Server] from for request'
    )
    const result = await handlers.approvalHandler(decision)
    json(res, 200, result)
  } catch (error) {
    logger.error(
      { detail: approved ? 'approval' : 'denial', err: error },
      '[Server] Error handling approval decision'
    )
    json(res, 500, {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    })
  }
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

function isProviderIdentity(
  value: unknown
): value is ProviderWorkflowApprovalDecision['providerIdentity'] {
  if (!value || typeof value !== 'object') return false
  const record = value as Record<string, unknown>
  const hasRequiredIdentity =
    (record.medium === 'telegram' || record.medium === 'slack' || record.medium === 'teams') &&
    typeof record.providerUserId === 'string' &&
    record.providerUserId.trim().length > 0 &&
    typeof record.providerChannelId === 'string' &&
    record.providerChannelId.trim().length > 0 &&
    typeof record.providerEventId === 'string' &&
    record.providerEventId.trim().length > 0
  if (!hasRequiredIdentity) return false
  if (
    record.providerChannelType !== undefined &&
    record.providerChannelType !== null &&
    (typeof record.providerChannelType !== 'string' ||
      record.providerChannelType.trim().length === 0)
  ) {
    return false
  }
  if (record.medium === 'slack' || record.medium === 'teams') {
    return (
      typeof record.providerWorkspaceId === 'string' && record.providerWorkspaceId.trim().length > 0
    )
  }
  return true
}

function isProviderResolveIdentity(
  value: unknown
): value is ProviderWorkflowApprovalResolve['providerIdentity'] {
  if (!value || typeof value !== 'object') return false
  const record = value as Record<string, unknown>
  const hasRequiredIdentity =
    (record.medium === 'telegram' || record.medium === 'slack' || record.medium === 'teams') &&
    typeof record.providerUserId === 'string' &&
    record.providerUserId.trim().length > 0 &&
    typeof record.providerChannelId === 'string' &&
    record.providerChannelId.trim().length > 0
  if (!hasRequiredIdentity) return false
  if (record.medium === 'slack' || record.medium === 'teams') {
    return (
      typeof record.providerWorkspaceId === 'string' && record.providerWorkspaceId.trim().length > 0
    )
  }
  return true
}

export async function handleProviderMessageAuthorizationRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.providerMessageAuthorizationHandler) {
      json(res, 501, { authorized: false, error: 'Provider authorization is not configured' })
      return
    }
    const parsed = req.body as Record<string, unknown>
    if (!isProviderResolveIdentity(parsed.providerIdentity)) {
      badRequest(res, 'providerIdentity is required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: parsed.providerIdentity.medium,
        channelId: parsed.providerIdentity.providerChannelId,
        sender: parsed.providerIdentity.providerUserId,
      })
    ) {
      json(res, 403, { authorized: false, error: 'Runtime edge source mismatch' })
      return
    }
    const result = await handlers.providerMessageAuthorizationHandler({
      providerIdentity: parsed.providerIdentity,
    })
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error authorizing provider message')
    json(res, 500, { authorized: false, error: 'Provider authorization unavailable' })
  }
}

export async function handleProviderWorkflowApprovalDecisionRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.providerWorkflowApprovalDecisionHandler) {
      json(res, 501, { success: false, error: 'Provider decision handler not configured' })
      return
    }

    const parsed = req.body as Record<string, unknown>
    const approvalRequestId =
      typeof parsed.approvalRequestId === 'string' ? parsed.approvalRequestId.trim() : ''
    if (!UUID_RE.test(approvalRequestId)) {
      badRequest(res, 'Invalid approvalRequestId format')
      return
    }
    if (parsed.decision !== 'approve' && parsed.decision !== 'deny') {
      badRequest(res, "decision must be 'approve' or 'deny'")
      return
    }
    if (!isProviderIdentity(parsed.providerIdentity)) {
      badRequest(res, 'providerIdentity is required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: parsed.providerIdentity.medium,
        channelId: parsed.providerIdentity.providerChannelId,
        sender: parsed.providerIdentity.providerUserId,
      })
    ) {
      json(res, 403, { error: 'Runtime edge source mismatch' })
      return
    }
    const note = parsed.note === undefined || parsed.note === null ? null : String(parsed.note)
    if (note && note.length > 1000) {
      badRequest(res, 'note exceeds maximum length of 1000 characters')
      return
    }

    const result = await handlers.providerWorkflowApprovalDecisionHandler({
      approvalRequestId,
      decision: parsed.decision,
      providerIdentity: parsed.providerIdentity,
      note,
    })
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error handling provider workflow approval decision')
    json(res, 500, {
      success: false,
      error: 'Provider workflow approval decision unavailable',
    })
  }
}

export async function handleProviderWorkflowApprovalResolveRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.providerWorkflowApprovalResolveHandler) {
      json(res, 501, { error: 'Provider approval resolve handler not configured' })
      return
    }

    const parsed = req.body as Record<string, unknown>
    const recipeName = typeof parsed.recipeName === 'string' ? parsed.recipeName.trim() : ''
    if (!recipeName) {
      badRequest(res, 'recipeName is required')
      return
    }
    if (!isProviderResolveIdentity(parsed.providerIdentity)) {
      badRequest(res, 'providerIdentity is required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: parsed.providerIdentity.medium,
        channelId: parsed.providerIdentity.providerChannelId,
        sender: parsed.providerIdentity.providerUserId,
      })
    ) {
      json(res, 403, { error: 'Runtime edge source mismatch' })
      return
    }

    const result = await handlers.providerWorkflowApprovalResolveHandler({
      recipeName,
      providerIdentity: parsed.providerIdentity,
    })
    if (result.status === 'found') {
      json(res, 200, { approvalRequestId: result.approvalRequestId })
      return
    }
    if (result.status === 'not_found') {
      json(res, 404, { error: 'pending_workflow_approval_not_found' })
      return
    }
    if (result.status === 'ambiguous') {
      json(res, 409, { error: 'pending_workflow_approval_ambiguous' })
      return
    }
    json(res, 502, { error: result.error })
  } catch (error) {
    logger.error({ err: error }, '[Server] Error resolving provider workflow approval')
    json(res, 500, {
      error: 'Provider workflow approval resolve unavailable',
    })
  }
}

function isWorkflowResultSource(value: unknown): value is ProviderWorkflowResultRequest['source'] {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
  const source = value as Record<string, unknown>
  return (
    (source.channelType === 'telegram' ||
      source.channelType === 'slack' ||
      source.channelType === 'teams') &&
    typeof source.channelId === 'string' &&
    source.channelId.trim().length > 0 &&
    typeof source.sender === 'string' &&
    source.sender.trim().length > 0 &&
    typeof source.messageId === 'string' &&
    source.messageId.trim().length > 0 &&
    typeof source.timestamp === 'string' &&
    source.timestamp.trim().length > 0 &&
    (source.threadId === undefined || typeof source.threadId === 'string')
  )
}

export async function handleProviderWorkflowResultRequestRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.providerWorkflowResultRequestHandler) {
      json(res, 501, { success: false, error: 'Provider workflow result handler not configured' })
      return
    }

    const parsed = req.body as Record<string, unknown>
    const workflowName = typeof parsed.workflowName === 'string' ? parsed.workflowName.trim() : ''
    const workflowRunId =
      typeof parsed.workflowRunId === 'string' ? parsed.workflowRunId.trim() : ''
    const artifactName = typeof parsed.artifactName === 'string' ? parsed.artifactName.trim() : ''
    if (!workflowName && !workflowRunId) {
      badRequest(res, 'workflowName or workflowRunId is required')
      return
    }
    if (workflowName && workflowRunId) {
      badRequest(res, 'workflowName and workflowRunId are mutually exclusive')
      return
    }
    if (artifactName && !workflowRunId) {
      badRequest(res, 'artifactName requires workflowRunId')
      return
    }
    if (
      workflowRunId &&
      !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(workflowRunId)
    ) {
      badRequest(res, 'workflowRunId must be a UUID')
      return
    }
    if (!isProviderResolveIdentity(parsed.providerIdentity)) {
      badRequest(res, 'providerIdentity is required')
      return
    }
    if (!isWorkflowResultSource(parsed.source)) {
      badRequest(res, 'source is required')
      return
    }
    if (
      parsed.providerIdentity.medium !== parsed.source.channelType ||
      parsed.providerIdentity.providerChannelId !== parsed.source.channelId ||
      parsed.providerIdentity.providerUserId !== parsed.source.sender
    ) {
      json(res, 403, { success: false, error: 'Provider identity/source mismatch' })
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: parsed.source.channelType,
        channelId: parsed.source.channelId,
        sender: parsed.source.sender,
      })
    ) {
      json(res, 403, { success: false, error: 'Runtime edge source mismatch' })
      return
    }

    const result = await handlers.providerWorkflowResultRequestHandler(
      {
        ...(workflowName ? { workflowName } : {}),
        ...(workflowRunId ? { workflowRunId } : {}),
        ...(artifactName ? { artifactName } : {}),
        providerIdentity: parsed.providerIdentity,
        source: parsed.source,
      },
      getRuntimeCallerContext(req)
    )
    json(res, result.success ? 200 : 403, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error handling provider workflow result request')
    json(res, 500, {
      success: false,
      error: 'Provider workflow result request unavailable',
    })
  }
}

function bodyRecord(body: unknown): Record<string, unknown> {
  return body && typeof body === 'object' && !Array.isArray(body)
    ? (body as Record<string, unknown>)
    : {}
}

function stringArray(value: unknown): string[] {
  return Array.isArray(value)
    ? value.map(item => (typeof item === 'string' ? item.trim() : '')).filter(Boolean)
    : []
}

function nullableString(value: unknown): string | null {
  return typeof value === 'string' && value.trim() ? value.trim() : null
}

type TelegramRouteProviderTarget = {
  hostRef: string
  communicationChannelNamespace: string
  communicationChannelName: string
  providerBotId?: string
  providerBotUsername?: string
}

function normalizeTelegramRouteProviderTarget(value: unknown): TelegramRouteProviderTarget | null {
  const providerTarget = bodyRecord(value)
  const hostRef = nullableString(providerTarget.hostRef)
  const communicationChannelNamespace = nullableString(providerTarget.communicationChannelNamespace)
  const communicationChannelName = nullableString(providerTarget.communicationChannelName)
  if (!hostRef || !communicationChannelNamespace || !communicationChannelName) return null
  const providerBotId = nullableString(providerTarget.providerBotId)
  const providerBotUsername = nullableString(providerTarget.providerBotUsername)
  return {
    hostRef,
    communicationChannelNamespace,
    communicationChannelName,
    ...(providerBotId ? { providerBotId } : {}),
    ...(providerBotUsername ? { providerBotUsername } : {}),
  }
}

export async function handleWorkflowApprovalNotificationClaimRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.workflowApprovalNotificationClaimHandler) {
      json(res, 501, {
        deliveries: [],
        error: 'Workflow approval notification handler not configured',
      })
      return
    }
    const body = bodyRecord(req.body)
    const medium = nullableString(body.medium)
    if (medium !== 'telegram' && medium !== 'slack' && medium !== 'teams') {
      badRequest(res, 'medium is required')
      return
    }
    const providerChannelIds = stringArray(body.providerChannelIds)
    if (providerChannelIds.length === 0) {
      badRequest(res, 'providerChannelIds are required')
      return
    }
    const hostRef = nullableString(body.hostRef)
    if (!hostRef) {
      badRequest(res, 'hostRef is required')
      return
    }
    const limit = Number(body.limit ?? 10)
    const result = await handlers.workflowApprovalNotificationClaimHandler({
      medium,
      providerChannelIds,
      providerWorkspaceId: nullableString(body.providerWorkspaceId),
      hostRef,
      limit: Number.isFinite(limit) ? Math.max(1, Math.min(50, Math.floor(limit))) : 10,
    })
    if ('error' in result) {
      json(res, 502, { deliveries: [], error: result.error })
      return
    }
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error claiming workflow approval notifications')
    json(res, 500, { deliveries: [], error: 'Workflow approval notifications unavailable' })
  }
}

export async function handleWorkflowApprovalNotificationTerminalRoute(
  req: Request,
  res: Response,
  id: string,
  action: 'ack' | 'fail',
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.workflowApprovalNotificationTerminalHandler) {
      json(res, 501, { error: 'Workflow approval notification terminal handler not configured' })
      return
    }
    const body = bodyRecord(req.body)
    const medium = nullableString(body.medium)
    const providerUserId = nullableString(body.providerUserId)
    const providerChannelId = nullableString(body.providerChannelId)
    const hostRef = nullableString(body.hostRef)
    if (medium !== 'telegram' && medium !== 'slack' && medium !== 'teams') {
      badRequest(res, 'medium is required')
      return
    }
    if (!providerUserId || !providerChannelId || !hostRef) {
      badRequest(res, 'provider identity and hostRef are required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: medium,
        channelId: providerChannelId,
        sender: providerUserId,
      })
    ) {
      json(res, 403, { error: 'Runtime edge source mismatch' })
      return
    }
    const result = await handlers.workflowApprovalNotificationTerminalHandler(id, action, {
      medium,
      providerUserId,
      providerChannelId,
      providerWorkspaceId: nullableString(body.providerWorkspaceId),
      hostRef,
    })
    if (!result.ok) {
      json(res, 502, { error: result.error ?? 'notification delivery update failed' })
      return
    }
    res.status(204).end()
  } catch (error) {
    logger.error({ err: error }, '[Server] Error updating workflow approval notification')
    json(res, 500, { error: 'Workflow approval notification update unavailable' })
  }
}

export async function handleWorkflowApprovalMediumEnrollmentRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.workflowApprovalMediumEnrollmentHandler) {
      json(res, 501, {
        ok: false,
        error: 'Workflow approval medium enrollment handler not configured',
      })
      return
    }
    const body = bodyRecord(req.body)
    const nonce = nullableString(body.nonce)
    const medium = nullableString(body.medium)
    const providerUserId = nullableString(body.providerUserId)
    const providerChannelId = nullableString(body.providerChannelId)
    const communicationChannelRef = nullableString(body.communicationChannelRef)
    if (!nonce || (medium !== 'telegram' && medium !== 'slack' && medium !== 'teams')) {
      badRequest(res, 'nonce and medium are required')
      return
    }
    if (!providerUserId || !providerChannelId) {
      badRequest(res, 'provider identity is required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: medium,
        channelId: providerChannelId,
        sender: providerUserId,
      })
    ) {
      json(res, 403, { error: 'Runtime edge source mismatch' })
      return
    }
    const result = await handlers.workflowApprovalMediumEnrollmentHandler({
      nonce,
      medium,
      providerUserId,
      providerWorkspaceId: nullableString(body.providerWorkspaceId),
      providerChannelId,
      providerChannelType: nullableString(body.providerChannelType),
      serviceUrl: nullableString(body.serviceUrl),
      communicationChannelRef,
    })
    json(res, result.ok ? 200 : 409, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error confirming workflow approval medium enrollment')
    json(res, 500, { ok: false, error: 'Workflow approval medium enrollment unavailable' })
  }
}

export async function handleTelegramWorkflowApprovalVerificationRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.telegramWorkflowApprovalVerificationHandler) {
      json(res, 501, { ok: false, error: 'Telegram verification handler not configured' })
      return
    }
    const body = bodyRecord(req.body)
    const code = nullableString(body.code)
    const providerUserId = nullableString(body.providerUserId)
    const providerChannelId = nullableString(body.providerChannelId)
    const providerChannelType = nullableString(body.providerChannelType)
    const primaryProviderTarget = normalizeTelegramRouteProviderTarget(body.providerTarget)
    const providerTargets = [
      primaryProviderTarget,
      ...(Array.isArray(body.providerTargets)
        ? body.providerTargets.map(candidate => normalizeTelegramRouteProviderTarget(candidate))
        : []),
    ].filter((target): target is TelegramRouteProviderTarget => target !== null)
    if (!code || !providerUserId || !providerChannelId || !providerChannelType) {
      badRequest(res, 'telegram provider verification fields are required')
      return
    }
    if (!primaryProviderTarget) {
      badRequest(res, 'providerTarget is required')
      return
    }
    if (
      channelRuntimeSourceMismatch(getRuntimeCallerContext(req), {
        channelType: 'telegram',
        channelId: providerChannelId,
        sender: providerUserId,
      })
    ) {
      json(res, 403, { error: 'Runtime edge source mismatch' })
      return
    }
    const result = await handlers.telegramWorkflowApprovalVerificationHandler({
      code,
      providerUserId,
      providerChannelId,
      providerChannelType,
      providerTarget: primaryProviderTarget,
      providerTargets,
    })
    json(res, result.ok ? 200 : 409, result)
  } catch (error) {
    logger.error(
      { err: error },
      '[Server] Error confirming Telegram workflow approval verification'
    )
    json(res, 500, { ok: false, error: 'Telegram workflow approval verification unavailable' })
  }
}

export async function handleTaskResultRoute(
  req: Request,
  res: Response,
  taskId: string,
  handlers: RouteHandlers
): Promise<void> {
  try {
    if (!handlers.taskResultHandler) {
      json(res, 501, { success: false, error: 'Task result handler not configured' })
      return
    }

    const result = await handlers.taskResultHandler(taskId, getRuntimeCallerContext(req))
    if (result === null) {
      json(res, 404, { error: 'Task not found' })
      return
    }
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error getting task result')
    json(res, 500, {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    })
  }
}

export function handleCronResultsRoute(req: Request, res: Response, handlers: RouteHandlers): void {
  if (!handlers.cronResultsHandler) {
    json(res, 501, { results: [] })
    return
  }

  const results = handlers.cronResultsHandler(getRuntimeCallerContext(req))
  json(res, 200, { results })
}

export function handleCronResultAckRoute(
  req: Request,
  res: Response,
  taskId: string,
  handlers: RouteHandlers
): void {
  if (!handlers.cronResultAckHandler) {
    json(res, 501, { success: false, error: 'Handler not configured' })
    return
  }

  const deleted = handlers.cronResultAckHandler(taskId, getRuntimeCallerContext(req))
  json(res, 200, { success: deleted })
}

export async function handleSessionsListRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    if (hasBracketedQueryVariant(req.query, ['agent', 'cursor', 'limit'])) {
      badRequest(res, 'Invalid session pagination query')
      return
    }
    if (req.query.agent !== undefined && typeof req.query.agent !== 'string') {
      badRequest(res, 'Invalid session agent')
      return
    }
    const agent = typeof req.query.agent === 'string' ? req.query.agent.trim() : undefined
    if (agent !== undefined && !isSafeAgentRouteSegment(agent)) {
      badRequest(res, 'Invalid session agent')
      return
    }
    const cursor = parseSessionsCursorParam(
      req.query.cursor,
      sessionsCursorScope(caller.userId, agent)
    )
    if (cursor === null) {
      badRequest(res, 'Invalid sessions cursor')
      return
    }
    const rawLimit = parseUnsignedIntegerParam(req.query.limit)
    if (rawLimit === null || (rawLimit !== undefined && rawLimit < 1)) {
      badRequest(res, 'limit must be a positive integer')
      return
    }
    if (!handlers.sessionsListHandler) {
      json(res, 501, { error: 'Sessions handler not configured' })
      return
    }
    const limit =
      rawLimit === undefined ? (cursor ? 50 : undefined) : Math.min(rawLimit, SESSIONS_LIMIT_CAP)
    const result = await handlers.sessionsListHandler(caller.userId, { agent, limit, cursor })
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error listing sessions')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

/**
 * T3.1 — GET /v1/runtime/sessions/search. Authenticated full-text search over
 * the JWT-derived user's history. `userSub` comes from the verified token;
 * caller-supplied `?user=` is silently ignored.
 *
 * Status codes:
 *   - 200: results returned (possibly empty).
 *   - 400: missing `q`.
 *   - 401: missing/invalid auth.
 *   - 501: search handler not wired (memory mode / feature OFF).
 *   - 500: backend error (SQL failure, e.g. malformed FTS5 expression).
 */
export async function handleSessionSearchRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const auth = (req as Request & { auth?: { sub: string } }).auth
    if (!auth?.sub) {
      json(res, 401, { error: 'Missing token' })
      return
    }
    if (!handlers.sessionSearchHandler) {
      json(res, 501, { error: 'Session search handler not configured' })
      return
    }

    const q = typeof req.query.q === 'string' ? req.query.q.trim() : ''
    if (!q) {
      badRequest(res, 'q is required')
      return
    }

    const scope =
      req.query.scope === 'all_channels' ? ('all_channels' as const) : ('this_channel' as const)
    const since = typeof req.query.since === 'string' ? req.query.since : undefined
    const channelType = typeof req.query.channel === 'string' ? req.query.channel : undefined

    const limitRaw = Number(req.query.limit ?? 20)
    const limit = Math.min(Math.max(Number.isFinite(limitRaw) ? Math.floor(limitRaw) : 20, 1), 50)

    const result = await handlers.sessionSearchHandler({
      userSub: auth.sub,
      query: q,
      scope,
      channelType,
      since,
      limit,
    })
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error searching sessions')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

export async function handleSessionMessagesRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    const agent = String(req.params.agent || '').trim()
    const chatId = String(req.params.chatId || '').trim()
    if (!isSafeAgentRouteSegment(agent) || !isSafeRouteSegment(chatId)) {
      badRequest(res, 'Invalid agent or chatId')
      return
    }
    const invalidQueryShape = ['limit', 'beforeTurn', 'afterTurn'].some(
      key => req.query[key] !== undefined && typeof req.query[key] !== 'string'
    )
    if (
      invalidQueryShape ||
      hasBracketedQueryVariant(req.query, ['limit', 'beforeTurn', 'afterTurn'])
    ) {
      badRequest(res, 'pagination parameters must be specified once')
      return
    }
    const rawLimit = parseUnsignedIntegerParam(req.query.limit)
    const rawBeforeTurn = parseUnsignedIntegerParam(req.query.beforeTurn)
    const rawAfterTurn = parseUnsignedIntegerParam(req.query.afterTurn)
    if (rawBeforeTurn === null || (rawBeforeTurn !== undefined && rawBeforeTurn < 1)) {
      badRequest(res, 'beforeTurn must be a positive integer')
      return
    }
    if (rawAfterTurn === null || (rawAfterTurn !== undefined && rawAfterTurn < 0)) {
      badRequest(res, 'afterTurn must be a non-negative integer')
      return
    }
    if (rawBeforeTurn !== undefined && rawAfterTurn !== undefined) {
      badRequest(res, 'beforeTurn and afterTurn are mutually exclusive')
      return
    }
    if (rawLimit === null || (rawLimit !== undefined && rawLimit < 1)) {
      badRequest(res, 'limit must be a positive integer')
      return
    }
    if (!handlers.sessionMessagesHandler) {
      json(res, 501, { error: 'Sessions handler not configured' })
      return
    }
    const limit =
      rawLimit === undefined
        ? rawBeforeTurn !== undefined || rawAfterTurn !== undefined
          ? 80
          : undefined
        : Math.min(rawLimit, MESSAGES_LIMIT_CAP)
    const beforeTurn = rawBeforeTurn
    const afterTurn = rawAfterTurn
    const result = await handlers.sessionMessagesHandler(caller.userId, agent, chatId, {
      limit,
      beforeTurn,
      afterTurn,
    })
    if (result === null) {
      // Same body regardless of "never existed" vs "belongs to someone else" — enumeration-defense.
      json(res, 404, { error: 'session not found' })
      return
    }
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error fetching session messages')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

export async function handleContextBreakdownRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    // AUTH INVARIANT (load-bearing): the userSub is derived from the verified
    // rpc-proxy edge caller, NEVER from a client param/query/body. The session
    // key is built server-side as `${userSub}:rpc:${agent}:${chatId}`, so a
    // caller cannot construct another user's key. See F1.5 of the plan.
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    const agent = String(req.params.agent || '').trim()
    const chatId = String(req.params.chatId || '').trim()
    if (!isSafeAgentRouteSegment(agent) || !isSafeRouteSegment(chatId)) {
      badRequest(res, 'Invalid agent or chatId')
      return
    }
    if (!handlers.contextBreakdownHandler) {
      json(res, 501, { error: 'Sessions handler not configured' })
      return
    }
    const result = await handlers.contextBreakdownHandler(caller.userId, agent, chatId)
    if (result === null) {
      // Same body regardless of "never existed" vs "belongs to someone else" — enumeration-defense.
      json(res, 404, { error: 'session not found' })
      return
    }
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error fetching context breakdown')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

/**
 * R2 — GET /v1/runtime/models. Read-only projection of the in-memory allowlist
 * for the Host's provider, plus the per-session selection when `?chatId=` is
 * passed. `runtimeEdgeGuard(['rpc-proxy'])` at the server layer guarantees a
 * verified edge user + hostRef; the session lookup is scoped server-side to
 * `${userId}:rpc:${hostRef}:${chatId}` (anti-enumeration, same as /messages).
 */
export async function handleModelsListRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId || !caller.hostRef) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    if (!handlers.modelsListHandler) {
      json(res, 501, { error: 'Models handler not configured' })
      return
    }
    const chatId = typeof req.query.chatId === 'string' ? req.query.chatId.trim() : ''
    const result = await handlers.modelsListHandler(
      caller.userId,
      caller.hostRef,
      chatId || undefined
    )
    json(res, 200, result)
  } catch (error) {
    logger.error({ err: error }, '[Server] Error listing models')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

/**
 * R2 — POST /v1/runtime/model `{ chatId, model }`. `chatId` is MANDATORY (no
 * global model switch in v1). Validates `model ∈ allowlist` (403
 * `model_not_allowed`, degraded → only the Host default), persists the session
 * selection and responds `{ effective:'next-task', provider, model }`.
 */
export async function handleSetModelRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId || !caller.hostRef) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    if (!handlers.setModelHandler) {
      json(res, 501, { error: 'Set model handler not configured' })
      return
    }
    const body = (req.body as Record<string, unknown>) || {}
    const chatId = typeof body.chatId === 'string' ? body.chatId.trim() : ''
    const model = typeof body.model === 'string' ? body.model.trim() : ''
    if (!chatId) {
      badRequest(res, 'chatId is required')
      return
    }
    if (!model) {
      badRequest(res, 'model is required')
      return
    }
    const expectedRevision = body.expectedRevision
    if (expectedRevision !== undefined && !isNonNegativeSafeInteger(expectedRevision)) {
      badRequest(res, 'expectedRevision must be a non-negative integer')
      return
    }
    const result = await handlers.setModelHandler(
      caller.userId,
      caller.hostRef,
      chatId,
      model,
      expectedRevision
    )
    if (!result.ok) {
      json(res, result.reason === 'model_selection_conflict' ? 409 : 403, {
        error: result.reason,
        provider: result.provider,
        model: result.model,
        ...(result.modelSelectionRevision === undefined
          ? {}
          : { modelSelectionRevision: result.modelSelectionRevision }),
      })
      return
    }
    json(res, 200, {
      effective: 'next-task',
      provider: result.provider,
      model: result.model,
      ...(result.modelSelectionRevision === undefined
        ? {}
        : { modelSelectionRevision: result.modelSelectionRevision }),
    })
  } catch (error) {
    logger.error({ err: error }, '[Server] Error setting model')
    if (isSessionOwnershipError(error)) {
      json(res, 403, { error: 'session access denied' })
      return
    }
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

/**
 * Spec 15 Fase B — PATCH /v1/runtime/sessions/:agent/:chatId/name `{ title }`.
 * Overwrites the session title from an explicit user rename. `:agent`/`:chatId`
 * come from the path (same key derivation as the read routes); the title comes
 * from the body and is sanitized + validated by the shared core. Uniform 404 for
 * missing / foreign / channel sessions (anti-enumeration). The raw title is NEVER
 * logged — user content (§5).
 */
export async function handleSetTitleRoute(
  req: Request,
  res: Response,
  handlers: RouteHandlers
): Promise<void> {
  try {
    const caller = getRuntimeCallerContext(req)
    if (caller?.caller !== 'rpc-proxy' || !caller.userId) {
      json(res, 401, { error: 'Missing rpc edge caller context' })
      return
    }
    const agent = String(req.params.agent || '').trim()
    const chatId = String(req.params.chatId || '').trim()
    if (!isSafeAgentRouteSegment(agent) || !isSafeRouteSegment(chatId)) {
      badRequest(res, 'Invalid agent or chatId')
      return
    }
    if (!handlers.setTitleHandler) {
      json(res, 501, { error: 'Set title handler not configured' })
      return
    }
    const body = (req.body as Record<string, unknown>) || {}
    // All title-validity logic (sanitize, non-empty, cap) lives in the core so
    // it stays single-sourced (D4); a non-string body.title becomes '' → invalid.
    const rawTitle = typeof body.title === 'string' ? body.title : ''
    const result = await handlers.setTitleHandler(caller.userId, agent, chatId, rawTitle)
    if (!result.ok) {
      if (result.reason === 'not_found') {
        json(res, 404, { error: 'session not found' })
        return
      }
      json(res, 400, { error: 'invalid title' })
      return
    }
    json(res, 200, { ok: true, title: result.title })
  } catch (error) {
    logger.error({ err: error }, '[Server] Error setting session title')
    json(res, 500, { error: error instanceof Error ? error.message : 'Unknown error' })
  }
}

export async function handleProgressStreamRoute(
  req: Request,
  res: Response,
  taskId: string,
  handlers: RouteHandlers
): Promise<void> {
  if (!handlers.progressStreamHandler) {
    json(res, 501, { error: 'Progress stream unavailable' })
    return
  }

  // SSE headers FIRST (before subscription to avoid race)
  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache, no-transform')
  res.setHeader('Connection', 'keep-alive')
  res.flushHeaders()

  // Send a waiting event so the client knows the connection is alive while we
  // wait for the reporter to become available (the agent may not have dequeued
  // the task yet).
  writeSseEvent(res, 'waiting', { taskId, ts: new Date().toISOString() })

  // The handler may return a Promise (async wait for reporter) or synchronously
  const registrationOrPromise = handlers.progressStreamHandler(
    taskId,
    event => {
      writeSseEvent(res, event.type, event.data)
    },
    getRuntimeCallerContext(req)
  )
  const registration = await Promise.resolve(registrationOrPromise)

  if (!registration) {
    writeSseEvent(res, 'error', { message: 'task_not_found_or_expired' })
    res.end()
    return
  }

  writeSseEvent(res, 'open', { taskId, ts: new Date().toISOString() })

  const keepalive = setInterval(() => {
    res.write(': keepalive\n\n')
  }, 15_000)

  req.on('close', () => {
    clearInterval(keepalive)
    registration.unsubscribe()
  })
}