dsh-edge 0.1.0

package/src/edge-credentials.ts

@@ -0,0 +1,56 @@
+/** Read-only upstream credential provider over Cloudflare Worker secrets. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import CredentialProvider, {
+  credentialRef,
+  type CredentialInfo,
+  type CredentialRef,
+  type ResolvedCredential,
+} from '@deepseek-ai/dsh-credentials'
+
+export const EDGE_DEEPSEEK_API_KEY_REF = credentialRef('DEEPSEEK_API_KEY')
+
+export interface EdgeCredentialProviderConfig {
+  /** Read the current deployment secret without copying it into Durable Object storage. */
+  readDeepSeekApiKey(): string | undefined
+}
+
+/** Resolve deployment credentials through the same seam used by upstream providers. */
+export class EdgeCredentialProvider extends CredentialProvider {
+  constructor(
+    ctx: Context,
+    private readonly config: EdgeCredentialProviderConfig,
+  ) {
+    super(ctx)
+  }
+
+  /** Resolve the supported Worker secret for one operation. */
+  override resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+    if (ref !== EDGE_DEEPSEEK_API_KEY_REF) return Promise.resolve(undefined)
+    const value = this.config.readDeepSeekApiKey()?.trim()
+    if (value === undefined || value.length === 0) return Promise.resolve(undefined)
+    return Promise.resolve({ value, source: 'worker-secret' })
+  }
+
+  /** Describe a Worker secret without exposing its value. */
+  override async describe(ref: CredentialRef): Promise<CredentialInfo> {
+    const resolved = await this.resolve(ref)
+    return {
+      configured: resolved !== undefined,
+      ...resolved === undefined ? {} : { source: resolved.source },
+      writable: false,
+    }
+  }
+
+  /** Cloudflare secrets are changed through deployment tooling, not runtime RPCs. */
+  override set(_ref: CredentialRef, _value: string): Promise<void> {
+    return Promise.reject(new Error('dsh-edge credentials are read-only; update the Cloudflare Worker secret.'))
+  }
+
+  /** Cloudflare secrets are changed through deployment tooling, not runtime RPCs. */
+  override unset(_ref: CredentialRef): Promise<void> {
+    return Promise.reject(new Error('dsh-edge credentials are read-only; update the Cloudflare Worker secret.'))
+  }
+}
+
+export default EdgeCredentialProvider

package/src/edge-remotes.ts

@@ -0,0 +1,41 @@
+/** Minimal generated-Remote compatibility required by the upstream Web UI. */
+
+import type { ServerResponse } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { clientRequestSchema } from '@deepseek-ai/dsh-host-apiproxy/api/rpc.schema'
+
+const COMMAND_LIST_PATH = '/api/commands/list'
+
+/**
+ * Handle Edge-owned endpoints on upstream's shared generic `/api` channel.
+ * The Edge preset currently registers no slash commands, so its truthful
+ * catalog is empty; retaining the upstream carrier envelope lets ui-commands
+ * stay mounted without a parallel Edge-only client implementation.
+ */
+export async function handleEdgeRemote(request: Request): Promise<Response | undefined> {
+  const url = new URL(request.url)
+  if (url.pathname !== COMMAND_LIST_PATH) return undefined
+  if (request.method !== 'POST') {
+    return new Response('method not allowed', { status: 405, headers: { allow: 'POST' } })
+  }
+  if (request.headers.get('content-type')?.split(';', 1).at(0)?.trim() !== 'application/json') {
+    return new Response('expected application/json', { status: 415 })
+  }
+
+  let wire: unknown
+  try {
+    wire = await request.json()
+  } catch {
+    return new Response('invalid JSON body', { status: 400 })
+  }
+  const parsed = clientRequestSchema.safeParse(wire)
+  if (!parsed.success || parsed.data.method !== 'commands/list') {
+    return new Response('request path and method do not match', { status: 400 })
+  }
+
+  const body: ServerResponse = {
+    type: 'server-response',
+    rpcId: parsed.data.rpcId,
+    result: { ok: true, value: [] },
+  }
+  return Response.json(body)
+}

package/src/edge-workspace-store.ts

@@ -0,0 +1,339 @@
+/** Cloudflare Durable Object adapter for the upstream workspace domain. */
+
+import type { WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { EdgeApiSessionSummary } from './session-store.ts'
+
+export const EDGE_WORKSPACE_ID = 'edge-workspace' as WorkspaceId
+export const EDGE_WORKSPACE_PATH = '/workspace'
+
+const WORKSPACE_DOMAIN_STATE_KEY = 'dsh-edge:workspace-domain-state:v2'
+const WORKSPACE_RECORD_KEY = 'dsh-edge:workspace-domain-workspaces:edge-workspace:v2'
+
+/** Exact upstream workspace-domain global value, backed by DO storage. */
+interface EdgeWorkspaceDomainState {
+  initialized: boolean
+  workspaceIds: WorkspaceId[]
+  archivedSessionIds: SessionId[]
+}
+
+/** Exact upstream workspaces-table value, backed by DO storage. */
+interface EdgeWorkspaceRecord {
+  path: string
+  title: string
+  sessionIds: SessionId[]
+  createdAt: string
+  updatedAt: string
+}
+
+export class EdgeWorkspaceStoreError extends Error {
+  constructor(
+    readonly code: 'NOT_FOUND' | 'INVALID_PATH' | 'MOVE_INVALID',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'EdgeWorkspaceStoreError'
+  }
+}
+
+/**
+ * Preserve the upstream workspace records/global-state split while replacing
+ * its Node filesystem and storage-domain backends with one DO transaction.
+ */
+export class EdgeWorkspaceStore {
+  private operationTail: Promise<void> = Promise.resolve()
+
+  constructor(private readonly storage: DurableObjectStorage) {}
+
+  list(sessions: readonly EdgeApiSessionSummary[]): Promise<{
+    items: WorkspaceView[]
+    archivedSessionIds: SessionId[]
+  }> {
+    return this.serialize(async () => {
+      const state = await this.readState()
+      if (!state.workspaceIds.includes(EDGE_WORKSPACE_ID)) {
+        return { items: [], archivedSessionIds: state.archivedSessionIds }
+      }
+      const record = await this.readOrCreateRecord(sessions)
+      return {
+        items: [workspaceView(record)],
+        archivedSessionIds: state.archivedSessionIds,
+      }
+    })
+  }
+
+  create(
+    path: string,
+    sessions: readonly EdgeApiSessionSummary[],
+  ): Promise<{ workspace: WorkspaceView; created: boolean }> {
+    return this.serialize(async () => {
+      if (path !== EDGE_WORKSPACE_PATH) {
+        throw new EdgeWorkspaceStoreError(
+          'INVALID_PATH',
+          `Edge workspaces must use ${EDGE_WORKSPACE_PATH}.`,
+        )
+      }
+      const state = await this.readState()
+      if (state.workspaceIds.includes(EDGE_WORKSPACE_ID)) {
+        const record = await this.readOrCreateRecord(sessions)
+        return { workspace: workspaceView(record), created: false }
+      }
+      const now = new Date().toISOString()
+      const record: EdgeWorkspaceRecord = {
+        path: EDGE_WORKSPACE_PATH,
+        title: 'workspace',
+        sessionIds: [],
+        createdAt: now,
+        updatedAt: now,
+      }
+      await this.storage.transaction(async (txn) => {
+        await txn.put(WORKSPACE_RECORD_KEY, record)
+        await txn.put(WORKSPACE_DOMAIN_STATE_KEY, {
+          ...state,
+          workspaceIds: [EDGE_WORKSPACE_ID],
+        } satisfies EdgeWorkspaceDomainState)
+      })
+      return { workspace: workspaceView(record), created: true }
+    })
+  }
+
+  rename(workspaceId: WorkspaceId, title: string, sessions: readonly EdgeApiSessionSummary[]): Promise<{
+    workspace: WorkspaceView
+    changed: boolean
+  }> {
+    return this.serialize(async () => {
+      await this.requireWorkspace(workspaceId)
+      const current = await this.readOrCreateRecord(sessions)
+      if (current.title === title) return { workspace: workspaceView(current), changed: false }
+      const next = { ...current, title, updatedAt: new Date().toISOString() }
+      await this.storage.put(WORKSPACE_RECORD_KEY, next)
+      return { workspace: workspaceView(next), changed: true }
+    })
+  }
+
+  delete(workspaceId: WorkspaceId): Promise<void> {
+    return this.serialize(async () => {
+      const state = await this.requireWorkspace(workspaceId)
+      await this.storage.transaction(async (txn) => {
+        await txn.delete(WORKSPACE_RECORD_KEY)
+        await txn.put(WORKSPACE_DOMAIN_STATE_KEY, {
+          ...state,
+          workspaceIds: [],
+        } satisfies EdgeWorkspaceDomainState)
+      })
+    })
+  }
+
+  insertBefore(workspaceId: WorkspaceId, beforeWorkspaceId?: WorkspaceId): Promise<WorkspaceId[]> {
+    return this.serialize(async () => {
+      const state = await this.requireWorkspace(workspaceId)
+      if (beforeWorkspaceId !== undefined && beforeWorkspaceId !== EDGE_WORKSPACE_ID) {
+        throw new EdgeWorkspaceStoreError(
+          'NOT_FOUND',
+          `Workspace "${beforeWorkspaceId}" is not available in this Edge instance.`,
+        )
+      }
+      return [...state.workspaceIds]
+    })
+  }
+
+  insertSessionBefore(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    beforeSessionId: SessionId | undefined,
+    sessions: readonly EdgeApiSessionSummary[],
+  ): Promise<{ workspace: WorkspaceView; changed: boolean }> {
+    return this.serialize(async () => {
+      await this.requireWorkspace(workspaceId)
+      const current = await this.readOrCreateRecord(sessions)
+      if (!current.sessionIds.includes(sessionId)) {
+        throw new EdgeWorkspaceStoreError(
+          'MOVE_INVALID',
+          `Session "${sessionId}" is not accounted by workspace "${workspaceId}".`,
+        )
+      }
+      if (beforeSessionId !== undefined && !current.sessionIds.includes(beforeSessionId)) {
+        throw new EdgeWorkspaceStoreError(
+          'MOVE_INVALID',
+          `Anchor session "${beforeSessionId}" is not accounted by workspace "${workspaceId}".`,
+        )
+      }
+      if (beforeSessionId === sessionId) {
+        return { workspace: workspaceView(current), changed: false }
+      }
+      const without = current.sessionIds.filter(id => id !== sessionId)
+      const index = beforeSessionId === undefined ? without.length : without.indexOf(beforeSessionId)
+      const sessionIds = [...without.slice(0, index), sessionId, ...without.slice(index)]
+      if (sameIds(sessionIds, current.sessionIds)) {
+        return { workspace: workspaceView(current), changed: false }
+      }
+      const next = { ...current, sessionIds, updatedAt: new Date().toISOString() }
+      await this.storage.put(WORKSPACE_RECORD_KEY, next)
+      return { workspace: workspaceView(next), changed: true }
+    })
+  }
+
+  attachSession(
+    workspaceId: WorkspaceId,
+    sessionId: SessionId,
+    sessions: readonly EdgeApiSessionSummary[],
+  ): Promise<WorkspaceView> {
+    return this.serialize(async () => {
+      await this.requireWorkspace(workspaceId)
+      const current = await this.readOrCreateRecord(sessions)
+      if (current.sessionIds.includes(sessionId)) return workspaceView(current)
+      const next = {
+        ...current,
+        sessionIds: [sessionId, ...current.sessionIds],
+        updatedAt: new Date().toISOString(),
+      }
+      await this.storage.put(WORKSPACE_RECORD_KEY, next)
+      return workspaceView(next)
+    })
+  }
+
+  workspaceForSession(
+    sessionId: SessionId,
+    sessions: readonly EdgeApiSessionSummary[],
+  ): Promise<WorkspaceId | undefined> {
+    return this.serialize(async () => {
+      const state = await this.readState()
+      if (!state.workspaceIds.includes(EDGE_WORKSPACE_ID)) return undefined
+      const current = await this.readOrCreateRecord(sessions)
+      return current.sessionIds.includes(sessionId) ? EDGE_WORKSPACE_ID : undefined
+    })
+  }
+
+  archivedSessionIds(): Promise<SessionId[]> {
+    return this.serialize(async () => [...(await this.readState()).archivedSessionIds])
+  }
+
+  archiveSession(sessionId: SessionId, requireSession: () => Promise<unknown>): Promise<{
+    archivedSessionIds: SessionId[]
+    changed: boolean
+  }> {
+    return this.serialize(async () => {
+      const state = await this.readState()
+      if (state.archivedSessionIds.includes(sessionId)) {
+        return { archivedSessionIds: [...state.archivedSessionIds], changed: false }
+      }
+      await requireSession()
+      const archivedSessionIds = [...state.archivedSessionIds, sessionId]
+      await this.storage.put(WORKSPACE_DOMAIN_STATE_KEY, {
+        ...state,
+        archivedSessionIds,
+      } satisfies EdgeWorkspaceDomainState)
+      return { archivedSessionIds, changed: true }
+    })
+  }
+
+  private async requireWorkspace(workspaceId: WorkspaceId): Promise<EdgeWorkspaceDomainState> {
+    const state = await this.readState()
+    if (workspaceId !== EDGE_WORKSPACE_ID || !state.workspaceIds.includes(workspaceId)) {
+      throw new EdgeWorkspaceStoreError(
+        'NOT_FOUND',
+        `Workspace "${workspaceId}" is not available in this Edge instance.`,
+      )
+    }
+    return state
+  }
+
+  private async readOrCreateRecord(
+    sessions: readonly EdgeApiSessionSummary[],
+  ): Promise<EdgeWorkspaceRecord> {
+    const stored = await this.storage.get(WORKSPACE_RECORD_KEY)
+    if (stored !== undefined) return workspaceRecordFromStorage(stored)
+    const record = defaultWorkspaceRecord(sessions)
+    await this.storage.put(WORKSPACE_RECORD_KEY, record)
+    return record
+  }
+
+  private async readState(): Promise<EdgeWorkspaceDomainState> {
+    const stored = await this.storage.get(WORKSPACE_DOMAIN_STATE_KEY)
+    if (stored === undefined) {
+      return {
+        initialized: true,
+        workspaceIds: [EDGE_WORKSPACE_ID],
+        archivedSessionIds: [],
+      }
+    }
+    return workspaceDomainStateFromStorage(stored)
+  }
+
+  private serialize<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.operationTail.then(operation)
+    this.operationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+}
+
+function defaultWorkspaceRecord(sessions: readonly EdgeApiSessionSummary[]): EdgeWorkspaceRecord {
+  const createdAt = sessions.length === 0
+    ? new Date(0).toISOString()
+    : new Date(Math.min(...sessions.map(session => session.createdAt))).toISOString()
+  const updatedAt = sessions.length === 0
+    ? createdAt
+    : new Date(Math.max(...sessions.map(session => session.updatedAt))).toISOString()
+  return {
+    path: EDGE_WORKSPACE_PATH,
+    title: 'Workspace',
+    sessionIds: sessions.map(session => session.id),
+    createdAt,
+    updatedAt,
+  }
+}
+
+function workspaceView(record: EdgeWorkspaceRecord): WorkspaceView {
+  return { workspaceId: EDGE_WORKSPACE_ID, ...record, sessionIds: [...record.sessionIds] }
+}
+
+function sameIds(left: readonly SessionId[], right: readonly SessionId[]): boolean {
+  return left.length === right.length && left.every((id, index) => id === right[index])
+}
+
+function workspaceDomainStateFromStorage(stored: unknown): EdgeWorkspaceDomainState {
+  if (typeof stored !== 'object' || stored === null || Array.isArray(stored)) {
+    throw new Error('dsh-edge workspace domain state is invalid.')
+  }
+  const value = stored as Record<string, unknown>
+  const workspaceIds = value.workspaceIds
+  const archivedSessionIds = value.archivedSessionIds
+  if (value.initialized !== true
+    || !Array.isArray(workspaceIds)
+    || workspaceIds.some(id => id !== EDGE_WORKSPACE_ID)
+    || new Set(workspaceIds).size !== workspaceIds.length
+    || !Array.isArray(archivedSessionIds)
+    || archivedSessionIds.some(id => typeof id !== 'string' || id.length === 0)
+    || new Set(archivedSessionIds).size !== archivedSessionIds.length
+    || Object.hasOwn(value, 'pendingMutation')) {
+    throw new Error('dsh-edge workspace domain state is invalid.')
+  }
+  return {
+    initialized: true,
+    workspaceIds: workspaceIds.map(() => EDGE_WORKSPACE_ID),
+    archivedSessionIds: archivedSessionIds as SessionId[],
+  }
+}
+
+function workspaceRecordFromStorage(stored: unknown): EdgeWorkspaceRecord {
+  if (typeof stored !== 'object' || stored === null || Array.isArray(stored)) {
+    throw new Error('dsh-edge workspace record is invalid.')
+  }
+  const value = stored as Record<string, unknown>
+  if (value.path !== EDGE_WORKSPACE_PATH
+    || typeof value.title !== 'string'
+    || !Array.isArray(value.sessionIds)
+    || value.sessionIds.some(id => typeof id !== 'string' || id.length === 0)
+    || new Set(value.sessionIds).size !== value.sessionIds.length
+    || typeof value.createdAt !== 'string'
+    || typeof value.updatedAt !== 'string') {
+    throw new Error('dsh-edge workspace record is invalid.')
+  }
+  return {
+    path: EDGE_WORKSPACE_PATH,
+    title: value.title,
+    sessionIds: value.sessionIds as SessionId[],
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+  }
+}

package/src/http.ts

@@ -0,0 +1,212 @@
+/** Shared HTTP parsing, response, and error translation for dsh-edge routes. */
+
+import { assertUsableApiKey, LlmError } from '@deepseek-ai/dsh-llm'
+import { EdgeSessionStoreError } from './session-store.ts'
+import { EdgeWorkspaceRequestError } from './workspace.ts'
+
+const textEncoder = new TextEncoder()
+
+export const MAX_SESSION_CREATE_BODY_BYTES = 8_192
+export const MAX_TURN_BODY_BYTES = 524_288
+export const MAX_WORKSPACE_EXEC_BODY_BYTES = 131_072
+
+/** Invalid caller input with an explicit HTTP response status. */
+export class EdgeHttpError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message)
+  }
+}
+
+/** Consume a request body without retaining bytes beyond its route limit. */
+export async function readBoundedBody(
+  request: Request,
+  maxBytes: number,
+  message: string,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const declared = request.headers.get('content-length')
+  let exceeded = declared !== null && /^\d+$/.test(declared) && Number(declared) > maxBytes
+  if (request.body === null) return new Uint8Array()
+
+  const chunks: Uint8Array[] = []
+  let byteLength = 0
+  const stream = request.body as ReadableStream<Uint8Array>
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const next = await reader.read()
+      if (next.done) break
+      byteLength += next.value.byteLength
+      if (exceeded || byteLength > maxBytes) {
+        exceeded = true
+        chunks.length = 0
+        continue
+      }
+      chunks.push(next.value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  if (exceeded) throw new EdgeHttpError(413, message)
+
+  const body = new Uint8Array(byteLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return body
+}
+
+/** Consume one bounded UTF-8 request body. */
+export async function readBoundedText(
+  request: Request,
+  maxBytes: number,
+  message: string,
+): Promise<string> {
+  const body = await readBoundedBody(request, maxBytes, message)
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(body)
+  } catch {
+    throw new EdgeHttpError(400, 'The request body must contain valid UTF-8.')
+  }
+}
+
+/** Parse a size-bounded JSON object request body. */
+export async function readJsonObject(
+  request: Request,
+  maxBytes: number,
+): Promise<Record<string, unknown>> {
+  try {
+    const source = await readBoundedText(
+      request,
+      maxBytes,
+      `JSON request bodies are limited to ${maxBytes} bytes.`,
+    )
+    const body: unknown = JSON.parse(source)
+    if (!isRecord(body)) {
+      throw new EdgeHttpError(400, 'The request body must be a JSON object.')
+    }
+    return body
+  } catch (error) {
+    if (error instanceof EdgeHttpError) throw error
+    throw new EdgeHttpError(400, 'The request body must contain valid JSON.')
+  }
+}
+
+/** Release an unread request body before returning an early Worker response. */
+export async function discardUnreadRequestBody(request: Request): Promise<void> {
+  if (request.body === null || request.bodyUsed) return
+  await request.body.cancel().catch(() => undefined)
+}
+
+/** Validate a non-empty bounded string field from an HTTP request. */
+export function requireBoundedString(
+  value: unknown,
+  field: string,
+  maxLength: number,
+): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new EdgeHttpError(400, `${field} must be a non-empty string.`)
+  }
+  if (value.length > maxLength) {
+    throw new EdgeHttpError(413, `${field} is limited to ${maxLength} characters.`)
+  }
+  return value
+}
+
+/** Validate a non-empty string field whose wire limit is defined in UTF-8 bytes. */
+export function requireBoundedUtf8String(
+  value: unknown,
+  field: string,
+  maxBytes: number,
+): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new EdgeHttpError(400, `${field} must be a non-empty string.`)
+  }
+  if (textEncoder.encode(value).byteLength > maxBytes) {
+    throw new EdgeHttpError(413, `${field} is limited to ${maxBytes} UTF-8 bytes.`)
+  }
+  return value
+}
+
+/** Resolve the deployment-scoped DeepSeek Worker secret. */
+export function resolveDeepSeekApiKey(configuredKey?: string): string {
+  const apiKey = configuredKey
+  if (apiKey === undefined) {
+    throw new EdgeHttpError(
+      401,
+      'Configure the DEEPSEEK_API_KEY Worker secret.',
+    )
+  }
+  return assertUsableApiKey(
+    apiKey,
+    'dsh-edge',
+    'DEEPSEEK_API_KEY',
+  )
+}
+
+/** Build one JSON response with the development CORS policy. */
+export function jsonResponse(value: unknown, status = 200): Response {
+  return Response.json(value, { status, headers: corsHeaders() })
+}
+
+/** Development-only CORS headers shared by every route. */
+export function corsHeaders(): Record<string, string> {
+  return {
+    'access-control-allow-headers': 'content-type, last-event-id',
+    'access-control-allow-methods': 'GET, PUT, POST, DELETE, OPTIONS',
+    'access-control-allow-origin': '*',
+    'access-control-expose-headers': 'x-dsh-edge-has-more, x-dsh-edge-next-after',
+  }
+}
+
+/** Translate known runtime failures without exposing stacks or credentials. */
+export function errorResponse(error: unknown): Response {
+  if (error instanceof EdgeHttpError || error instanceof EdgeWorkspaceRequestError) {
+    return jsonResponse({ ok: false, error: error.message }, error.status)
+  }
+  if (error instanceof EdgeSessionStoreError) {
+    const status = error.code === 'NOT_FOUND' ? 404 : error.code === 'BUSY' ? 409 : 500
+    return jsonResponse({ ok: false, error: error.message, code: error.code }, status)
+  }
+  if (error instanceof LlmError) {
+    return jsonResponse({
+      ok: false,
+      error: error.message,
+      code: error.code,
+      ...error.failure.status === undefined
+        ? {}
+        : { providerStatus: error.failure.status },
+      ...error.failure.requestId === undefined
+        ? {}
+        : { providerRequestId: error.failure.requestId },
+    }, llmHttpStatus(error.code))
+  }
+  if (isErrorCode(error, 'ENOENT')) {
+    return jsonResponse({ ok: false, error: 'Workspace entry not found.' }, 404)
+  }
+  console.error(error)
+  return jsonResponse({ ok: false, error: 'Internal runtime error.' }, 500)
+}
+
+function llmHttpStatus(code: string): number {
+  if (code === 'AUTH' || code === 'MISSING_CREDENTIAL') return 401
+  if (code === 'INVALID_CREDENTIAL'
+    || code === 'INVALID_REQUEST'
+    || code === 'CONTEXT_WINDOW_EXCEEDED') return 400
+  if (code === 'RATE_LIMIT' || code === 'QUOTA') return 429
+  if (code === 'TIMEOUT') return 504
+  return 502
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+  return typeof error === 'object'
+    && error !== null
+    && 'code' in error
+    && error.code === code
+}