Skip to content

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

TypeScript
25.3 KB
Raw Blame
/**
 * R2 — one selectable model in the `GET /v1/runtime/models` projection. Mirrors
 * the enabled allowlist entry for the Host's provider; `models` is `[hostDefault]`
 * (name only) when the allowlist is unavailable (`degraded`).
 */
import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { FileReferenceResolution } from '../agent/fileReferenceResolver'
import type { ModelWireEntry } from '../config/modelResolution.js'
import type { ApprovalDecision } from '../core/extensions/approvalTypes'
import type { Attachment, TraceContextV1 } from '../core/types'
import type { McpServerStatusEntry } from '../mcp/serverStatus'
import type { ApprovalInputPreview } from '../progress/types'
import type { TaskError } from '../queue/types'

export interface ProviderIdentity {
  medium: 'telegram' | 'slack' | 'teams'
  providerUserId: string
  providerWorkspaceId?: string | null
  providerChannelId: string
  providerChannelType?: string | null
  providerEventId?: string
  providerTarget?: {
    hostRef: string
    communicationChannelNamespace: string
    communicationChannelName: string
    providerBotId?: string | null
    providerBotUsername?: string | null
  }
}

export interface ProviderDecisionIdentity extends ProviderIdentity {
  providerEventId: string
}

export interface IncomingMessage {
  content: string
  channelType: 'telegram' | 'email' | 'slack' | 'teams' | 'rpc'
  channelId: string
  sender: string
  timestamp: string
  messageId: string
  hostRef: string
  threadId?: string
  attachments?: Attachment[]
  metadata?: Record<string, unknown>
  providerIdentity?: ProviderIdentity
  traceContext?: TraceContextV1 | null
  /**
   * R2 — optional per-session model that rides WITH the message. Because a
   * suspended Host (replicas=0) cannot serve `POST /v1/runtime/model`, the
   * desktop piggybacks the user's pick here so it is applied to THIS task when
   * the message wakes the Host. Only honoured for the `rpc` channel; a
   * non-allowlisted value is ignored (fail-open on the message).
   */
  model?: string
  /** Optional CAS base for a visual message's explicit model selection. */
  modelSelectionRevision?: number
  /** Server-owned immutable visual selection; incoming callers cannot set it. */
  imageModel?: { provider: string; model: string }
  /**
   * Issue #666 — structured references to files the user picked (Global
   * Files). The route validates them; admission resolves each against gfsc.
   */
  fileReferences?: FileReferenceV1[]
  /** Server-owned: admission's resolution of `fileReferences`; callers cannot set it. */
  fileReferenceResolutions?: FileReferenceResolution[]
}

export type RuntimeCallerKind = 'rpc-proxy' | 'channel-reader' | 'workflow-approval-request-reader'

export interface RuntimeCallerContext {
  caller: RuntimeCallerKind
  hostRef?: string
  requestId?: string
  userId?: string
  teamId?: string
  channelType?: string
  channelId?: string
  sender?: string
}

export interface MessageResponse {
  success: boolean
  status?: 'completed' | 'waiting_approval' | 'pending'
  response?: string
  attachments?: Attachment[]
  error?: TaskError
  model?: string
  taskId?: string
  /**
   * Issue #666 — ids of every incoming attachment (images and files) the Host
   * validated and handed to the task, on the sync response and on the
   * `?async=true` ack. Absent on a text-only message and on every refusal. A
   * client that sent files and gets a success without its ids is talking to a
   * Host that cannot read file attachments.
   */
  acceptedAttachmentIds?: string[]
  /**
   * Issue #666 — ids of every structured file reference the Host resolved and
   * listed in the turn, whatever its availability. Absent when the message
   * carried none and on every refusal.
   */
  acceptedFileReferenceIds?: string[]
  /**
   * Issue #654 — the session's model-selection revision after the Host accepted
   * a piggybacked `model`, or the winning revision on a CAS conflict.
   *
   * The send IS the write, so its result must travel back on the same response:
   * `POST /v1/runtime/model` is unreachable on a suspended Host, which is why
   * the selection rides the message in the first place.
   *
   * Present when:
   *  - the piggybacked `model` was written: the new revision (the previous
   *    one + 1). A text-only message always writes, even the Host default;
   *  - an IMAGE message's `model` already WAS the effective model (the explicit
   *    selection, or the Host default when there is none): nothing is written
   *    and this is the unchanged current revision. The image carries the model
   *    the client displays, which is not a user pick, so it must not pin it;
   *  - an image message's `modelSelectionRevision` was stale: the winning
   *    revision, with `LLM_MODEL_SELECTION_CONFLICT`.
   *
   * Absent when the message carried no `model`, when the `modelSelectionRevision`
   * itself was invalid, when an image message was refused because the requested
   * model cannot read images (`LLM_IMAGE_INPUT_*`; the selection is NOT written,
   * so the revision the client holds is still current), or when the selection
   * was rejected. (During a boot fallback the task runs on another pair; if THAT
   * pair refuses the image, the requested selection was already written and the
   * refusal carries its new revision.) Absent on a successful ack after a piggyback means the Host
   * IGNORED the selection.
   */
  modelSelectionRevision?: number
  usage?: {
    promptTokens: number
    completionTokens: number
    totalTokens: number
  }
  approval?: {
    taskId: string
    requestId: string
    userId: string
    notification: string
    // U5 — connect_required discriminator, mirrored from the SSE `suspended`
    // event so a REST poll rebuilds the connect suspension. Absent reason ⇒
    // generic approval (back-compat). mcpServerName set iff
    // reason==='connect_required'.
    reason?: 'approval_required' | 'connect_required'
    mcpServerName?: string
  }
}

export interface StatusResponse {
  agent: {
    state: string
    currentTaskId: string | null
    tasksProcessed: number
    tasksSucceeded: number
    tasksFailed: number
    uptime: number
  }
  queue: {
    pending: number
    processing: number
    completed: number
    failed: number
  }
  cronJobs: number
  pendingApprovals?: Array<{
    requestId: string
    userId: string
    toolName: string
    parameters: Record<string, unknown>
    description: string
    since: string
    // U5 — connect_required discriminator, mirrored from the underlying
    // PendingApproval. Absent reason ⇒ generic approval (back-compat).
    reason?: 'approval_required' | 'connect_required'
    mcpServerName?: string
  }>
  /**
   * Per-MCP-server health snapshot (spec §4.2). Omitted by older mcp-host
   * builds; consumers MUST treat absence as "unknown for every server".
   */
  mcpServers?: McpServerStatusEntry[]
  /**
   * When set, the Host is degraded and refusing new tasks. Consumers should
   * surface this in status banners and disable the chat composer while it
   * is non-null. Currently the only reason emitted is `llm_key_missing`,
   * raised when the referenced LLM Secret is missing or lacks the
   * provider-matching key.
   */
  degraded?: {
    reason: 'llm_key_missing'
    message: string
  } | null
  /**
   * R2 — the Host's configured (default) provider + model. Optional for
   * forward/backward compat (older builds omit it; consumers treat absence as
   * "unknown"). This is the Host DEFAULT, not a per-session selection — the
   * per-session model is served by `GET /v1/runtime/models`.
   */
  model?: {
    provider: string
    name: string
  }
  /**
   * R5 — the provider/model pair currently SERVING the Host. Present only when a
   * failover policy is configured; `fallback: true` means a configured fallback
   * entry is serving (the desktop shows an "operating with fallback" badge). On
   * lazy recovery the engine flips `fallback` back to false. Optional for
   * forward/backward compat (older builds / no-policy Hosts omit it).
   *
   * `name` is a DELIBERATE alias of the served model (it mirrors the field name
   * of `StatusResponse.model.name`, not the engine's `ModelPair.model`), so the
   * desktop reads the same `.name` shape for the default model and the served
   * pair.
   */
  servedBy?: {
    provider: string
    name: string
    fallback: boolean
  }
}

export type HostActivitySeverity = 'info' | 'warn' | 'error'

export type HostActivityType =
  | 'task.queued'
  | 'task.started'
  | 'task.completed'
  | 'task.failed'
  | 'llm.requested'
  | 'llm.responded'
  | 'llm.failed'
  | 'tool.call.started'
  | 'tool.call.completed'
  | 'tool.call.failed'
  | 'approval.requested'
  | 'approval.approved'
  | 'approval.denied'
  | 'safety.input_blocked'
  | 'safety.output_sanitized'
  | 'queue.depth.changed'
  | 'agent.state.changed'
  // IronClaw invariant #1 (P.3): emitted whenever PressureContextManager.manage()
  // is bypassed by the loop because the conversation has a pending_approval.
  | 'compaction.skipped'
  // T1.4: emitted exactly once per task when consecutive compactions stop
  // yielding token savings and the manager switches to backoff.
  | 'compaction.thrashing'
  // T1.2: emitted whenever pre-prune (deterministic LLM-free compaction)
  // ran and reclaimed tokens. `meta` carries pre/post token counts and the
  // list of passes that actually mutated something.
  | 'compaction.pre_prune_executed'

export interface HostActivityEvent {
  version: '1.0'
  eventId: string
  hostRef: string
  ts: string
  taskId?: string
  type: HostActivityType
  title: string
  severity: HostActivitySeverity
  meta: Record<string, unknown>
  redactions: string[]
}

export interface HostActivitySnapshotResponse {
  hostRef: string
  version: '1.0'
  items: HostActivityEvent[]
  nextCursor: string | null
}

export type MessageHandler = (
  message: IncomingMessage,
  options?: { async?: boolean }
) => MessageResponse | Promise<MessageResponse>
export type StatusHandler = () => Promise<StatusResponse>
export type ActivitySnapshotHandler = (
  limit: number,
  sinceEventId?: string
) => Promise<HostActivitySnapshotResponse>
export type ActivityStreamHandler = (onEvent: (event: HostActivityEvent) => void) => {
  hostRef: string
  unsubscribe: () => void
}
export type ApprovalHandler = (
  decision: ApprovalDecision
) => Promise<{ success: boolean; error?: string }>
export interface ProviderWorkflowApprovalDecision {
  approvalRequestId: string
  decision: 'approve' | 'deny'
  providerIdentity: ProviderDecisionIdentity
  note?: string | null
}
export interface ProviderWorkflowApprovalResolve {
  recipeName: string
  providerIdentity: ProviderIdentity
}
export interface ProviderWorkflowResultRequest {
  workflowName?: string
  workflowRunId?: string
  artifactName?: string
  providerIdentity: ProviderIdentity
  source: {
    channelType: 'telegram' | 'slack' | 'teams'
    channelId: string
    sender: string
    messageId: string
    timestamp: string
    threadId?: string
  }
}
export interface ProviderMessageAuthorization {
  providerIdentity: ProviderIdentity
}
export type WorkflowApprovalNotificationMedium = 'telegram' | 'slack' | 'teams'
export interface WorkflowApprovalNotificationClaim {
  medium: WorkflowApprovalNotificationMedium
  providerChannelIds: string[]
  providerWorkspaceId?: string | null
  hostRef: string
  limit: number
}
export type WorkflowApprovalNotificationDelivery = {
  id: string
  medium: WorkflowApprovalNotificationMedium
  providerUserId: string
  providerWorkspaceId?: string | null
  providerChannelId: string
  attempts: number
  eventType: 'approval.requested' | 'approval.updated' | 'workflow.run.completed'
  payload: Record<string, unknown>
}
export interface WorkflowApprovalNotificationTerminal {
  medium: WorkflowApprovalNotificationMedium
  providerUserId: string
  providerChannelId: string
  providerWorkspaceId?: string | null
  hostRef: string
}
export interface TelegramWorkflowApprovalVerification {
  code: string
  providerUserId: string
  providerChannelId: string
  providerChannelType: string
  providerTarget: {
    hostRef: string
    communicationChannelNamespace: string
    communicationChannelName: string
    providerBotId?: string | null
    providerBotUsername?: string | null
  }
  providerTargets?: Array<{
    hostRef: string
    communicationChannelNamespace: string
    communicationChannelName: string
    providerBotId?: string | null
    providerBotUsername?: string | null
  }>
}
export interface WorkflowApprovalMediumEnrollment {
  nonce: string
  medium: 'telegram' | 'slack' | 'teams'
  providerUserId: string
  providerWorkspaceId?: string | null
  providerChannelId: string
  providerChannelType?: string | null
  serviceUrl?: string | null
  communicationChannelRef?: string | null
}
export type WorkflowApprovalMediumEnrollmentHandler = (
  input: WorkflowApprovalMediumEnrollment
) => Promise<{ ok: boolean; error?: string; account?: unknown }>
export type ProviderWorkflowApprovalDecisionHandler = (
  decision: ProviderWorkflowApprovalDecision
) => Promise<{
  success: boolean
  duplicate?: boolean
  status?: string
  run?: Record<string, unknown> | null
  error?: string
}>
export type ProviderWorkflowApprovalResolveHandler = (
  input: ProviderWorkflowApprovalResolve
) => Promise<
  | { status: 'found'; approvalRequestId: string }
  | { status: 'not_found' }
  | { status: 'ambiguous' }
  | { status: 'error'; error: string }
>
export type ProviderWorkflowResultRequestHandler = (
  input: ProviderWorkflowResultRequest,
  caller?: RuntimeCallerContext
) => Promise<MessageResponse>
export type ProviderMessageAuthorizationHandler = (
  input: ProviderMessageAuthorization
) => Promise<{ authorized: boolean; reason?: 'unresolved' | 'error' }>
export type WorkflowApprovalNotificationClaimHandler = (
  input: WorkflowApprovalNotificationClaim
) => Promise<{ deliveries: WorkflowApprovalNotificationDelivery[] } | { error: string }>
export type WorkflowApprovalNotificationTerminalHandler = (
  id: string,
  action: 'ack' | 'fail',
  input: WorkflowApprovalNotificationTerminal
) => Promise<{ ok: boolean; error?: string }>
export type TelegramWorkflowApprovalVerificationHandler = (
  input: TelegramWorkflowApprovalVerification
) => Promise<{ ok: true; accountId: string } | { ok: false; error: string }>
export type TaskResultHandler = (
  taskId: string,
  caller?: RuntimeCallerContext
) => Promise<MessageResponse | null>
export type CronResultsHandler = (caller?: RuntimeCallerContext) => Array<{
  id: string
  origin: { channelType: string; channelId: string; sender: string }
  response: string
  attachments?: Attachment[]
  cronJobId: string
  cronJobName: string
  timestamp: Date
  status?: 'completed' | 'waiting_approval'
  approval?: { taskId: string; requestId: string; userId: string }
}>
export type CronResultAckHandler = (taskId: string, caller?: RuntimeCallerContext) => boolean
export type ProgressStreamHandler = (
  taskId: string,
  onEvent: (event: import('../progress/types.js').ProgressEvent) => void,
  caller?: RuntimeCallerContext
) => { unsubscribe: () => void } | null | Promise<{ unsubscribe: () => void } | null>

/**
 * Result of a cancel attempt.
 *
 * - `cancelled`: task was pending/processing and has been cancelled
 * - `already_terminal`: task existed but was already completed/failed/cancelled (idempotent no-op)
 * - `not_found`: task not found in any state
 */
export type CancelResult = 'cancelled' | 'already_terminal' | 'not_found'

/**
 * Handler for POST /v1/runtime/tasks/:taskId/cancel.
 *
 * Receives the taskId, an optional requesterUserId (from request body,
 * mirrors approve/deny pattern), and returns whether the task was found
 * and cancelled, was already in a terminal state, or was not found at all.
 *
 * Ownership check: if the record carries a submittedBy identity AND
 * requesterUserId is provided AND they differ,
 * the handler returns 'not_found' (not 403 — don't leak task existence).
 * Fail-open when either side is absent for back-compat.
 */
export type CancelHandler = (
  taskId: string,
  requesterUserId?: string
) => CancelResult | Promise<CancelResult>

/**
 * T1.1 — POST /v1/runtime/compact. Operator-triggered compaction with an
 * optional focus topic. The handler is responsible for:
 *   - resolving the sessionKey to a Conversation,
 *   - rejecting when an approval is pending (IronClaw invariant #1),
 *   - constructing or reusing a PressureContextManager,
 *   - emitting `context:compacted` on success.
 *
 * The endpoint translates the discriminated result into HTTP status codes:
 *   `ok` → 200, `not_found` → 404, `pending_approval` → 409,
 *   `session_busy` → 409, `error` → 500.
 */
export type CompactionResult =
  | {
      kind: 'ok'
      before: number
      after: number
      focus: string | null
    }
  | { kind: 'not_found' }
  | { kind: 'pending_approval' }
  | { kind: 'session_busy' }
  | { kind: 'error'; message: string }

export type CompactionHandler = (request: {
  sessionKey: string
  focus?: string
  useMainLlm?: boolean
}) => Promise<CompactionResult>

/**
 * T3.1 — Handler for GET /v1/runtime/sessions/search.
 * `userSub` is the verified JWT identity; callers MUST derive it from the
 * request's `auth.sub`, never from query params. The handler reuses the same
 * `SessionSearchService` that drives the native tool, so the result shape is
 * identical across both surfaces.
 */
export interface SessionSearchRequest {
  userSub: string
  query: string
  scope: 'this_channel' | 'all_channels'
  channelType?: string
  since?: string
  limit: number
}

export interface SessionSearchResponse {
  results: Array<{
    snippet: string
    session_id: string
    timestamp: string
    channel: string
    role: string
  }>
  total: number
}

export type SessionSearchHandler = (
  request: SessionSearchRequest
) => SessionSearchResponse | Promise<SessionSearchResponse>

/**
 * D.1 — session liveness exposed to the desktop. `state` drives sidebar badges;
 * `activeTaskId` is the task to re-subscribe to (present when state ≠ idle);
 * `pendingApproval` lets the client render the approve button without waiting
 * for the SSE. NOTE: `tool_name` is intentionally NOT exposed (security patch
 * P1-1) — only the human-readable `displayName` derived server-side.
 */
/**
 * Lifetime token totals for a session, surfaced to the desktop. `cacheRead` /
 * `cacheWrite` are present ONLY when the model reports cache info (Anthropic);
 * absent for providers that don't (OpenAI / zai / bailian) so the UI shows the
 * 2-figure or 4-figure breakdown accordingly.
 */
export interface SessionTokensWire {
  input: number
  output: number
  cacheRead?: number
  cacheWrite?: number
}

export interface SessionStateWire {
  state: 'idle' | 'processing' | 'awaiting_approval'
  activeTaskId?: string
  pendingApproval?: {
    requestId: string
    displayName: string
    // U5 — connect_required discriminator, projected on the REST rejoin snapshot
    // so a reconnecting desktop rebuilds a "Connect <server>" suspension. Absent
    // reason ⇒ generic approval (back-compat). Set by `sessionRouteHandlers`.
    reason?: 'approval_required' | 'connect_required'
    mcpServerName?: string
    inputPreview?: ApprovalInputPreview
  }
  /** Lifetime token totals; omitted when the session has had no LLM call yet. */
  tokens?: SessionTokensWire
}

/**
 * Handler for GET /v1/runtime/sessions — list this user's desktop conversations.
 * Receives the authenticated user's sub (canonical user ID) and returns a list
 * suitable for the sidebar.
 */
export type SessionsListItem = {
  agent: string
  chatId: string
  turnCount: number
  messageCount?: number
  lastActivityAt: string
  /** Server-authoritative session title (spec 15); omitted when unset. */
  title?: string
} & SessionStateWire

export type SessionsListQuery = {
  agent?: string
  limit?: number
  cursor?: string
}

export type SessionsListResult = {
  items: SessionsListItem[]
  nextCursor?: string
}

export type SessionsListHandler = (
  userSub: string,
  query: SessionsListQuery
) => SessionsListResult | Promise<SessionsListResult>

/**
 * A single tool call within a turn, projected for the desktop progress stepper
 * (the "More details · N tools" view) so it survives a reload / cold-load. Mirrors
 * the minimal subset the live SSE `tool_complete` exposes — NEVER the raw
 * arguments or tool output (P1-1): `displayName` is derived server-side via
 * `getDisplayName`, and `errorSummary` is redacted at projection time (secret-scrub
 * + stack/path strip + truncate), matching the live SSE path.
 */
export type TurnToolStepWire = {
  toolName: string
  displayName: string
  state: 'completed' | 'error'
  durationMs?: number
  errorSummary?: string
}

/**
 * Handler for GET /v1/runtime/sessions/:agent/:chatId/messages — transcript for one session.
 * Returns null if the session does not exist for this user (which the route translates to 404).
 */

export type SessionMessagesResult = {
  agent: string
  chatId: string
  totalTurns: number
  oldestTurnNumber?: number
  latestTurnNumber?: number
  /** True only when older turns exist before the returned non-empty window. */
  hasMoreBefore: boolean
  /** True only when newer turns exist after the returned non-empty window. */
  hasMoreAfter: boolean
  turns: Array<{
    number: number
    user_input: string
    response?: string
    started_at: string
    completed_at?: string
    /** Per-turn token usage; omitted for a turn with no recorded LLM usage. */
    tokens?: SessionTokensWire
    /** Tools used in the turn; omitted when the turn made no tool calls. */
    tool_steps?: TurnToolStepWire[]
  }>
} & SessionStateWire

export type SessionMessagesQuery = {
  limit?: number
  beforeTurn?: number
  afterTurn?: number
}

export type SessionMessagesHandler = (
  userSub: string,
  agent: string,
  chatId: string,
  query: SessionMessagesQuery
) => SessionMessagesResult | null | Promise<SessionMessagesResult | null>

/**
 * Snapshot of the prompt composition sent in the last turn, surfaced to the
 * desktop on-demand. `cacheHitRate` is present ONLY when the model reported
 * cache info (`cacheTokensReported` — Anthropic); absent otherwise (#11).
 * See `.specs/mcp-session-persistence/context-window-breakdown-plan.md`.
 */
export interface ContextBreakdownWire {
  buckets: { messages: number; systemTools: number; metaContext: number; systemPrompt: number }
  totalInputTokens: number
  maxTokens: number
  /** totalInputTokens / maxTokens (0 when maxTokens is 0). */
  fillRatio: number
  /** cache_read / (cache_read + input); only when cacheTokensReported (#11). */
  cacheHitRate?: number
  /**
   * Turn-granular staleness marker: the 1-based conversation turn (including the
   * in-flight one) during which the snapshot was last captured. Not per-LLM-call
   * — it stays constant across the multiple captures within a turn. See
   * `ContextBreakdown.capturedAtTurn` in core/types.ts.
   */
  capturedAtTurn: number
}

/**
 * Handler for GET /v1/runtime/sessions/:agent/:chatId/context-breakdown.
 * Returns `{ breakdown: null }` when the session has no snapshot yet, and
 * (like the messages handler) `null` when the session does not exist for this
 * user — which the route translates to the SAME 404 (anti-enumeration).
 */
export type ContextBreakdownResult = { breakdown: ContextBreakdownWire | null }

export type ContextBreakdownHandler = (
  userSub: string,
  agent: string,
  chatId: string
) => ContextBreakdownResult | null | Promise<ContextBreakdownResult | null>

export type RuntimeModelEntry = ModelWireEntry

/**
 * Result of `GET /v1/runtime/models?chatId=…`. `sessionModel` is the session's
 * saved-and-still-allowed selection (null when unset or when it fell back);
 * `sessionModelBlocked` carries the stale saved model when it is no longer
 * allowed. `degraded` → allowlist unavailable, `models` collapses to the Host
 * default. `hostDefault` is the Host-configured default model.
 */
export interface ModelsListResult {
  provider: string
  hostDefault: string
  sessionModel: string | null
  modelSelectionRevision?: number
  sessionModelBlocked?: string
  degraded: boolean
  models: RuntimeModelEntry[]
}

export type ModelsListHandler = (
  userSub: string,
  hostRef: string,
  chatId: string | undefined
) => ModelsListResult | Promise<ModelsListResult>

/**
 * Result of `POST /v1/runtime/model`. `ok` → 200 `{ effective:'next-task', … }`;
 * `model_not_allowed` → 403. The route owns the 400 (missing chatId/model).
 */
export type SetModelResult =
  | { ok: true; provider: string; model: string; modelSelectionRevision?: number }
  | {
      ok: false
      reason: 'model_not_allowed' | 'model_selection_conflict'
      provider: string
      model: string
      modelSelectionRevision?: number
    }

export type SetModelHandler = (
  userSub: string,
  hostRef: string,
  chatId: string,
  model: string,
  expectedRevision?: number
) => SetModelResult | Promise<SetModelResult>

/**
 * Result of `PATCH /v1/runtime/sessions/:agent/:chatId/name` (spec 15 Fase B).
 * `ok` → 200 `{ ok:true, title }` (the server's sanitized canonical title, which
 * the client adopts). `invalid_title` → 400 (empty after sanitize, or over the
 * 120-code-point / 512-byte cap). `not_found` → **uniform 404** for a session
 * that does not exist, is owned by another user, OR is a channel session (not
 * renamable) — no cross-user existence oracle.
 */
export type SetTitleResult =
  | { ok: true; title: string }
  | { ok: false; reason: 'invalid_title' | 'not_found' }

export type SetTitleHandler = (
  userSub: string,
  agent: string,
  chatId: string,
  title: string
) => SetTitleResult | Promise<SetTitleResult>