@aiworker/web 1.22.0 → 1.23.0

package/server/lib/small-model/DOCUMENTATION.md.bak

@@ -1,212 +0,0 @@
-# Small Model
-
-Server-side direct LLM calls that reuse the user's existing OpenCode provider
-logins (`~/.local/share/opencode/auth.json`). OpenCode uses a "small model"
-internally (titles, summaries) but does not expose it through the SDK or
-plugins — this module replicates that mechanism as an AiWorker runtime API.
-
-## Security boundary
-
-Credentials never leave the server process. The client sends only a prompt;
-auth resolution, OAuth refresh, and provider dispatch all happen server-side.
-Routes live under `/api/*` and are gated by the ui-auth middleware like every
-other runtime API.
-
-## Files
-
-- `index.js` — orchestration: `generateSmallModelText()` / `describeSmallModel()`.
-- `runtime-providers.js` — provider state that exists only inside the running
-  OpenCode process. A plugin registers its provider from the `config` hook and
-  supplies the credential from its `auth` loader, so neither reaches
-  `opencode.json` nor `auth.json`; `GET /provider` is the only place they
-  become visible. The module caches one snapshot (30s TTL, shared in-flight
-  request) and answers `null` — never an empty provider list — when OpenCode is
-  unreachable, so a momentary outage cannot retract providers. It is wired once
-  from `server/index.js` and reset on OpenCode restart, which reloads plugins
-  and can move their ports and keys.
-- `resolve.js` — model selection, mirroring OpenCode's `getSmallModel` chain:
-  0. AiWorker's own settings override (Settings → Sessions → Small Model):
-     when `smallModelUseDefault` is `false`, `smallModelOverride`
-     (`provider/model`) outranks everything below. Sanitized in
-     `settings-helpers.js` (server), `persistence.ts` (client), and
-     `bridge-settings-runtime.ts` (VS Code).
-  1. `small_model` from the merged OpenCode config layers (`provider/model`).
-  2. Family-priority scan (`gemini-flash` → `gpt-nano` → `claude-haiku`)
-     **within the session's provider first** (`preferredProviderID`, like
-     OpenCode resolves within the current provider), then over the other
-     providers with a usable auth entry, newest `release_date` first.
-  3. GitHub Copilot hidden utility models (`gpt-*-nano/mini`) — these never
-     appear in the catalog, so they participate as the `gpt-nano` family entry
-     and as a final utility fallback.
-  4. Last resort: the session's own model (`preferredModelID`) when no small
-     model resolves anywhere — costlier, but always valid.
-- Input clamp: the prompt is measured against the resolved model's catalog
-  `limit.context` (minus an output reserve, ~4 chars/token estimate;
-  conservative default when the model is not in the catalog). `onOverflow`
-  decides what an oversized prompt means:
-  - `truncate` (default) clips the tail and reports `inputTruncated: true`.
-    Correct for callers that degrade gracefully (summaries, commit messages).
-  - `error` throws a `413` with `code: 'context-too-small'` plus
-    `requiredChars`/`availableChars`. Correct for callers whose output would be
-    quietly wrong on a clipped input, so they can ask the user for a roomier
-    model instead of returning confident nonsense.
-- Structured output: pass `responseSchema` (a JSON Schema) to get
-  schema-shaped JSON back as `text`. Wire support differs per format —
-  `response_format: {type: 'json_schema'}` for OpenAI-compatible chat,
-  `text.format` for the Responses API, a forced single tool call for the
-  Anthropic messages API, and `generationConfig.responseSchema` for Google
-  (whose OpenAPI-flavored dialect drops unknown JSON Schema keywords). The
-  ChatGPT-plan codex backend has no equivalent and rejects a schema request
-  with `code: 'structured-output-unsupported'` rather than silently returning
-  prose.
-- Output budget: `maxOutputTokens` is capped at the catalog's `limit.output` for
-  the model, and the **same number** is reserved from the input allowance. The
-  two must not drift — a caller that asks for a large answer while the reserve
-  stays at the default overruns the context, and the failure looks like a
-  truncation bug rather than a budgeting one. `describeSmallModel` takes
-  `outputReserveTokens` so readiness checks agree with what generation will do.
-  It may be a **function** of `{ contextTokens, outputTokenLimit }` for callers
-  that want as much answer room as the resolved model allows — they cannot name
-  a number before knowing which model they got. The resolved value comes back as
-  `outputTokens`, which is what the caller should then request, so the reserve
-  and the request are the same number by construction.
-- Reasoning models can spend the entire output budget thinking and return
-  nothing. That case (empty content with `finish_reason: 'length'`, or content
-  empty while `reasoning_content` is populated) throws with
-  `code: 'output-exhausted'` so callers can offer a different model instead of
-  showing a transport error.
-- `timeoutMs` overrides the 60s default per call; `signal` lets a caller abort
-  a request that is no longer wanted. Both apply to every wire format.
-- `describeSmallModel()` additionally reports `inputCharBudget`,
-  `contextTokens`, `contextKnown`, `structuredOutput`, and `hasLogin`. The last
-  is whether the resolved provider has a usable credential (`auth.json` or
-  config `provider.<id>.options.apiKey`) — settings/config overrides can name a
-  provider with none, and callers such as the walkthrough refuse before the
-  request. `structuredOutput` is tri-state: `true`/`false` from the catalog,
-  `null` when the catalog omits the field — which it does for roughly half of
-  all models, aggregators and proxies especially. Callers must treat `null` as
-  "try it", not "unsupported".
-- Missing credentials throw with `statusCode: 401` and
-  `code: 'no-provider-login'` rather than a bare `Error`, so UI callers can show
-  a blocker instead of a raw 500 message.
-- `call.js` — wire formats and per-provider auth, replicating OpenCode's
-  plugin auth loaders:
-  - **GitHub Copilot**: fetches the requested model's authenticated `/models`
-    metadata from `https://api.githubcopilot.com` (or
-    `copilot-api.<enterprise>`) and honors its advertised endpoint, preferring
-    Anthropic-compatible `/v1/messages`, then OpenAI `/responses`, then
-    `/chat/completions`. Models without `supported_endpoints` retain the legacy
-    Chat Completions default; metadata, missing-model, and unsupported-endpoint
-    failures are surfaced instead of guessing. The stored device-OAuth token is
-    used as the bearer with no token exchange or expiry.
-  - **OpenAI OAuth (ChatGPT plan)**: streaming Responses API on
-    `https://chatgpt.com/backend-api/codex/responses` with
-    `ChatGPT-Account-Id`; expired tokens are refreshed against
-    `auth.openai.com` (single-flight) and written back to `auth.json`.
-  - **Anthropic** (`type: api`): `/messages` with `x-api-key`, against
-    `provider.anthropic.options.baseURL` when configured (used as-is, matching
-    `@ai-sdk/anthropic` — no `/v1` is inserted) or `https://api.anthropic.com/v1`
-    otherwise.
-  - **Google** (`type: api`): `generateContent` with `x-goog-api-key`; Gemini 3
-    uses `thinkingLevel`, Gemini 2.x uses `thinkingBudget: 0`, and all other
-    models omit `thinkingConfig` entirely.
-  - Everything else: OpenAI-compatible `/chat/completions` against the
-    provider's base URL, resolved from (1) `provider.<id>.options.baseURL`
-    in the OpenCode config, (2) the hardcoded `https://api.openai.com/v1`
-     endpoint, (3) the endpoint OpenCode resolved at runtime, or (4) the
-    provider's `api` field from the models.dev catalog. The credential follows
-    the same shape: config `options.apiKey`, then the runtime credential, then
-    the auth.json entry. `provider.<id>.options.headers` is sent with the
-    request and overrides the bearer default, so gateways that authenticate on
-    their own header work here exactly as they do in a chat turn. Configured API
-    keys and header values honor OpenCode's `{env:NAME}` and `{file:path}`
-    substitutions; file contents and resolved credentials remain server-side.
-  - The runtime credential is refused for providers listed in
-    `OWN_CREDENTIAL_HANDLING`. Their branches need the stored entry rather than
-    a bearer token: the clearest case is the ChatGPT-plan `openai` login, whose
-    runtime `options.apiKey` is an OAuth access token that `api.openai.com`
-    answers with 401.
-  - `[small-model:diagnostic]` logs record provider/model, input character
-    counts, output budget, thinking toggle, HTTP/finish status, and
-    content/reasoning lengths without logging prompts, response text, or
-    credentials. Goal audit parsing similarly emits
-    `[session-goal:diagnostic]` structural verdict metadata.
-- `catalog.js` — models.dev catalog via the shared in-process cache
-  (`../opencode/models-metadata.js`, also serving
-   `/api/openchamber/models-metadata`).
-- `routes.js` — `GET /api/small-model` (resolution preview) and
-  `POST /api/small-model/generate` (`{ prompt, system?, maxOutputTokens?,
-  model?, directory? }` → `{ text, providerID, modelID, source }`).
-
-## Which providers the pickers may offer
-
-`listAuthenticatedProviders()` answers one question for the Small Model and
-Changes Walkthrough pickers alike: which providers can this module actually
-call. One rule decides it, applied the same way to every provider — **a
-credential we are allowed to use, and an endpoint to send it to.** The
-auth.json scan as before, plus the credential and endpoint OpenCode resolved
-for a plugin provider.
-
-**opencode zen is excluded without a real login.** When the user has no zen
-credential, OpenCode substitutes the sentinel `options.apiKey = "public"` and
-trims its catalog to the free models. Those run on OpenCode's own subsidised
-infrastructure and are meant to be reached through OpenCode, so the sentinel is
-never accepted as a credential — see `ZEN_ANONYMOUS_API_KEY`.
-
-### Why there is no capability probe
-
-A plugin may implement its whole integration inside `options.fetch` —
-rewriting the path, signing the request, translating the payload — and OpenCode
-cannot serialise a function. Such a provider advertises an ordinary base URL
-that answers nothing we know how to ask, and no reported field distinguishes it
-from a plain one.
-
-Asking the endpoint (`GET /models`) does identify that case correctly. It was
-measured against all 166 providers carrying an `api` URL in the models.dev
-catalog, and it also denies six of them — `cloudflare-workers-ai`,
-`infomaniak`, `iflowcn`, `inference`, `kuae-cloud-coding-plan`,
-`thinkingmachines` — which work fine and simply have no `/models` route. At a
-3.6% false-negative rate on providers known to work, the probe removes more
-working models from the picker than broken ones, and a provider that silently
-vanishes explains nothing while one that fails on use says why.
-
-So availability stops at credential and endpoint, and the protocol verdict is
-left to the call. A provider whose protocol lives in a plugin's `fetch` stays
-selectable and fails when used — which is what it did before this resolution
-existed.
-
-Claude Code is refused unconditionally. A plugin can publish an
-OpenAI-compatible endpoint for it, but that endpoint is a façade over the
-Claude Agent SDK, which spawns the Claude Code CLI per request and spends the
-user's Claude subscription rate limit. Paying that for a session title or a
-summary is the wrong trade, so an available endpoint does not lift the
-refusal — the cost is the reason, not the transport.
-
-The result is served as `authenticatedProviders` on `GET /api/small-model`.
-The field name predates the runtime resolution; it now means "callable", which
-is a superset of "has an auth.json entry".
-
-## Registration
-
-Mounted lazily from `feature-routes-runtime.js` (same pattern as quota): the
-module is imported on first request, not at server startup.
-
-## Known limitations
-
-- OpenCode's free models (`opencode/big-pickle`, `*-free`) work without a
-  token only through OpenCode's own server — direct calls are rejected, and
-  piggybacking on their subsidized infra is out of bounds by design. Every
-  resolution step therefore requires a credential we are allowed to use:
-  a session on an unauthenticated `opencode` provider falls through to the
-  global scan (or a clean 404 on a vanilla setup with no logins). The runtime
-  snapshot does not weaken this — OpenCode reports the sentinel
-  `apiKey: "public"` for that state, and this module refuses to read it as a
-  credential.
-
-- Anthropic OAuth (Claude Pro/Max) entries are not supported — OpenCode itself
-  keeps those outside `auth.json` in this generation; only `type: api` keys
-  work for Anthropic.
-- Amazon Bedrock, GitLab, Azure and other credential-chain providers are out
-  of scope; they need more than a key/token (regions, resource names).
-- Responses from the codex backend are collected from the SSE stream; the
-  endpoint itself is non-streaming by design (small utility calls).

package/server/lib/system-prompt/DOCUMENTATION.md.bak

@@ -1,36 +0,0 @@
-# Managed System Prompt Optimizer
-
-## Purpose
-
-This module injects an opt-in OpenCode plugin only when AiWorker launches
-and owns the OpenCode process and `optimizeSystemPrompt` is enabled. The plugin
-replaces OpenCode's built-in behavioral/provider prompt with a short identity
-while preserving the environment, project instructions, MCP instructions,
-skills, conversation history, and separately supplied tools.
-
-## Runtime flow
-
-1. Settings persist `optimizeSystemPrompt` in AiWorker's `settings.json`.
-2. The setting is applied when managed OpenCode restarts.
-3. The runtime materializes the plugin under
-   `<openchamber-data-dir>/system-prompt/` and appends its `file://` URL to
-   `OPENCODE_CONFIG_CONTENT` without replacing existing plugin entries.
-4. The plugin tracks the selected agent through `chat.message`. The transform
-   runs only for sessions using the built-in `build` or `plan` agent.
-5. The transform locates OpenCode's environment boundary and removes only the
-   preceding text. If the boundary is absent, it leaves the prompt unchanged.
-
-## Limitations
-
-OpenCode exposes the assembled prompt rather than structured sections. A custom
-prompt configured by overriding the `build` or `plan` agent occupies the same
-prefix as the built-in provider prompt, so the optimizer also removes that
-override. Other agents are never transformed. The setting is off by default.
-
-Plan-mode restrictions and build-mode transitions are not part of the removed
-prefix. OpenCode injects those as synthetic message reminders after system
-prompt transformation and separately enforces plan restrictions through tool
-permissions.
-
-The plugin is not injected for external OpenCode servers or VS Code's separate
-OpenCode lifecycle.

package/server/lib/terminal/DOCUMENTATION.md.bak

@@ -1,50 +0,0 @@
-# Terminal Subsystem
-
-## Ownership
-
-`runtime.js` owns terminal identity, PTY processes, status, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shells.js` discovers executable shell families and resolves the persisted shell ID without accepting command strings or arguments. Clients own tab arrangement and choose stable terminal IDs. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
-
-## Protocol
-
-`/api/terminal/ws` is the only terminal data transport. It uses v3 binary JSON control frames and is opened through `openRuntimeWebSocket`, preserving direct, Electron proxy, URL-token authentication, and private-relay routing.
-
-- `attach` registers a connection for one terminal. One socket may attach to many terminals.
-- Every attach and reconnect begins with an authoritative `snapshot` containing bounded history and the current sequence.
-- A current socket that closes or errors before its initial `open` invalidates its URL-scoped auth token before retrying, so retries mint a fresh token instead of backing off against a rejected upgrade. Hidden or offline clients wait 60 seconds and wake promptly on visibility/online recovery.
-- `output`, `exit`, and `restarted` carry monotonically increasing per-terminal sequences. Output carries raw live bytes plus replay-safe bytes with terminal query exchanges removed.
-- Attach registers before capturing the snapshot, buffers concurrent events, drops events represented by the snapshot sequence, then enters live delivery.
-- `write` always includes the terminal ID; sockets never have mutable single-terminal binding state.
-- `detach` removes only that attachment.
-- Creation carries the active UI appearance. The PTY sets `COLORFGBG` and answers OSC 10, OSC 11, Mode 2031, and primary-device-attribute queries immediately, including queries emitted before a WebSocket attachment exists. The DA1 fallback prevents Fish from waiting ten seconds for a renderer that cannot observe or answer its startup query. Subscribed TUIs receive a Mode 2031 notification when the appearance changes.
-
-HTTP remains the authenticated command plane for create, resize, appearance updates, restart, close, and force-kill. There is no SSE output or HTTP input compatibility path.
-
-`GET /api/terminal/sessions` enumerates live sessions (optionally filtered by resolved `cwd`) so clients can adopt terminals their local tab projection does not know about — another device, a new browser tab, or cleared storage. `POST /api/terminal/touch` refreshes `lastActivity` for the listed session ids; open clients call it periodically so background tabs, which hold no WebSocket attachment, are not idle-reaped while a client still shows them.
-
-## PTY Lifecycle
-
-- IDs are client-provided or generated with `randomUUID()`.
-- Concurrent creates for one ID are single-flight only when working directory and shell preference match. Existing IDs cannot be reused for another working directory.
-- Dimensions are bounded to 1-1000 columns and 1-500 rows; input is capped at 64 KiB.
-- A client may create before its renderer has mounted. It derives an initial size from the container and font metrics (falling back to 80x24 when unavailable), then sends a resize once Ghostty reports its final dimensions. This allows shell startup and renderer initialization to overlap.
-- PTY children explicitly clear `NODE_CHANNEL_FD`; daemon IPC descriptors are host-private and invalid after PTY descriptor cleanup.
-- PTY children also strip AppImage `ARGV0` (and other host-private shell vars such as `ELECTRON_RUN_AS_NODE`, `BASH_ENV`, `ENV`, `BASH_XTRACEFD`). An exported `ARGV0` makes zsh rewrite argv[0] for every external command, which breaks Python venv detection and other argv[0]/$0 consumers while leaving `/proc/self/exe` correct. On Linux, PTY spawn is wrapped with `env -u ARGV0` because `bun-pty` merges the native OS environ and would otherwise reintroduce `ARGV0` after a JS-only delete.
-- `GET /api/terminal/shells` reports shell IDs available on the active server using the same augmented PATH provided to spawned PTYs, plus whether each executable has a supported login-mode argument. `auto` preserves environment/platform fallback order; an explicit unavailable shell fails creation instead of silently running a different shell. Login mode is opt-in and uses only built-in arguments for known shells. Preference changes affect new sessions and explicit restarts, not running PTYs.
-- PTY data and exit callbacks enter one FIFO queue. Stale callbacks from replaced processes are ignored.
-- Scrollback is retained on the server and capped at 512 KiB with UTF-8-safe trimming. Device-status, device-attribute, cursor-position reply, and color-query exchanges are removed from replay history with incomplete control sequences carried across PTY chunks; live output remains byte-for-byte unchanged.
-- Exited sessions remain attachable until explicit close or idle cleanup.
-- Restarts are serialized per terminal. Each restart spawns and wires the replacement before terminating the old process, retaining the terminal ID.
-- Close uses SIGTERM with bounded SIGKILL escalation. Force-kill, idle cleanup, and runtime shutdown terminate process groups immediately where supported. Removal explicitly sends a fatal scoped closure and evicts client projections even when a PTY backend fails to emit `onExit`; attached terminals are not considered idle.
-
-## Security And Relay
-
-The WebSocket path must remain in both `isUrlAuthWebSocketPath` and relay `ALLOWED_WS_PATHS`. The client must use `getRuntimeUrlResolver().websocket()` and `openRuntimeWebSocket`; direct local URLs or raw browser WebSockets break relay and URL-token authentication.
-
-## Verification
-
-Run:
-
-```sh
-bun test packages/web/server/lib/terminal/runtime.test.js packages/web/server/lib/terminal/terminal-ws-protocol.test.js
-bun test packages/web/server/lib/ui-auth/ui-auth.test.js packages/web/server/lib/relay/cross-compat.test.js
-```

package/server/lib/text/DOCUMENTATION.md.bak

@@ -1,35 +0,0 @@
-# Text Module Documentation
-
-## Purpose
-This module provides shared text transformation helpers that are not owned by a single product surface. It previously proxied model-backed summarization through the opencode.ai Zen provider; that provider is no longer available for this use, so summarization now returns local sanitized/distilled fallback text only.
-
-## Entrypoints and structure
-- `packages/web/server/lib/text/summarization.js`: Shared summarize stub + sanitize helpers. It performs no external model calls.
-
-## Public exports
-
-### Summarization (summarization.js)
-- `summarizeText({ text, threshold, maxLength, zenModel, mode })`: Retired summarization entrypoint retained as an API-compatible stub. `zenModel` is ignored.
-- `sanitizeForTTS(text)`: Sanitizes text for speech output.
-- `sanitizeForNotification(text)`: Sanitizes text for compact notification output.
-- `sanitizeForNote(text)`: Sanitizes text for short note/distillation output.
-
-## Modes
-- `tts`: Speakable summary for TTS flows.
-- `notification`: Short plain-text summary for notification bodies.
-- `note`: Distilled short project-memory note.
-
-## Response contract
-
-### `summarizeText`
-Returns object with:
-- `summary`: Local sanitized/distilled fallback text.
-- `summarized`: Always `false` while the model provider is unavailable.
-- `reason`: Skip reason, usually `Model summarization provider unavailable` for text above threshold.
-- `originalLength`: Optional original text length.
-- `summaryLength`: Optional final summary length.
-
-## Notes for contributors
-- Keep this module neutral. Do not re-couple it to TTS-specific naming or routing.
-- Add new mode semantics here when multiple product surfaces need the same text pipeline.
-- Prefer mode-specific prompt and sanitize behavior over creating duplicated summarizers in unrelated modules.

package/server/lib/tts/DOCUMENTATION.md.bak

@@ -1,147 +0,0 @@
-# TTS Module Documentation
-
-## Purpose
-This module provides server-side Text-to-Speech services using OpenAI's TTS API. The historical shared text summarization endpoint now lives in `packages/web/server/lib/text/` as an API-compatible stub because the previous Zen model provider is unavailable.
-
-## Entrypoints and structure
-- `packages/web/server/lib/tts/index.js`: Public entrypoint imported by `packages/web/server/index.js`.
-- `packages/web/server/lib/tts/routes.js`: Express route registration for `/api/voice/*`, `/api/tts/*`, and `/api/stt/*` endpoints.
-- `packages/web/server/lib/tts/capability-runtime.js`: runtime helper for probing local macOS `say` TTS voice capability.
-- `packages/web/server/lib/tts/service.js`: TTS service implementation with OpenAI integration.
-- `packages/web/server/lib/text/summarization.js`: Shared text summarization stub and sanitization utilities. It performs no external Zen calls.
-- `packages/web/server/lib/tts/stt.js`: STT proxy for OpenAI-compatible transcription endpoints.
-- `packages/web/server/lib/tts/base-url.js`: shared base URL validation and normalization for custom OpenAI-compatible endpoints.
-- `packages/web/server/lib/tts/language-detect.js`: dependency-free language detection for voice selection (`detectTextLanguage`, `pickVoiceForLanguage`, `languageOfLocale`). Used by the macOS `say` route (`language: 'auto'` switches to an installed voice whose locale matches the text; the response carries `X-Speech-Voice` and `X-Speech-Language`) and by the dictation module's local TTS model choice.
-
-## Public exports
-
-### TTS Service (from service.js)
-- `ttsService`: Singleton instance of TTSService class.
-- `TTSService`: TTS service class for OpenAI audio generation.
-- `TTS_VOICES`: Array of supported OpenAI voice identifiers.
-
-### Shared text summarization (re-exported from ../text/summarization.js)
-- `summarizeText({ text, threshold, maxLength, zenModel, mode })`: Retired shared text summarizer retained as a stub. TTS uses `mode: 'tts'`; `zenModel` is ignored.
-- `sanitizeForTTS(text)`: Sanitizes text by removing markdown, URLs, file paths, and other non-speakable content.
-- `sanitizeForNote(text)`: Re-exported for note-mode callers that still import through the TTS surface.
-
-### Capability runtime (capability-runtime.js)
-- `detectSayTtsCapability(processLike)`: probes local `say -v "?"` support and returns `{ available, voices, reason }`.
-
-## Constants
-
-### Voice identifiers
-- `TTS_VOICES`: Array of supported OpenAI voices: `['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse', 'marin', 'cedar']`.
-
-### Summarization defaults
-- No model request timeout is used; the summarization provider is disabled.
-
-### Default values
-- `summarizeText` defaults: `threshold` = 200, `maxLength` = 500, `mode` = 'tts'. `zenModel` is ignored.
-- `generateSpeechStream` defaults: `voice` = 'coral', `model` = 'gpt-4o-mini-tts', `speed` = 1.0.
-- `generateSpeechBuffer` defaults: `voice` = 'coral', `model` = 'gpt-4o-mini-tts', `speed` = 1.0.
-
-## TTSService methods
-
-### `isAvailable()`
-Returns boolean indicating whether OpenAI API key is configured (checks environment variable `OPENAI_API_KEY` or OpenCode auth file).
-
-### `generateSpeechStream(options)`
-Generates speech and returns as a web stream for direct streaming to clients.
-- Options: `text` (required), `voice`, `model`, `speed`, `instructions`, `apiKey`.
-- Returns: `{ stream: ReadableStream, contentType: 'audio/mpeg' }`.
-- Throws: Error if API key not configured or text is empty.
-
-### `generateSpeechBuffer(options)`
-Generates speech and returns as Buffer for caching purposes.
-- Options: `text` (required), `voice`, `model`, `speed`, `instructions`.
-- Returns: Buffer containing MP3 audio data.
-- Throws: Error if API key not configured or text is empty.
-
-## Response contracts
-
-### `summarizeText`
-Returns object with:
-- `summary`: Sanitized or locally distilled fallback text.
-- `summarized`: Always `false` while the model provider is unavailable.
-- `reason`: String explaining why summarization was skipped.
-- `originalLength`: Optional number for original text length.
-- `summaryLength`: Optional number for summarized text length.
-
-The route-level text summarize API is now `/api/text/summarize`.
-
-### `sanitizeForTTS`
-Returns sanitized string with markdown, URLs, file paths, and special characters removed.
-
-### `generateSpeechStream`
-Returns object with:
-- `stream`: ReadableStream of MP3 audio data.
-- `contentType`: Always 'audio/mpeg'.
-
-### `generateSpeechBuffer`
-Returns Buffer containing MP3 audio data.
-
-## API key resolution
-OpenAI API keys are resolved in order:
-1. Environment variable `OPENAI_API_KEY`.
-2. OpenCode auth file (`auth.openai`, `auth.codex`, or `auth.chatgpt`).
-3. Supports both string format (just token) and object format (with `access` or `token` fields).
-
-## Usage in web server
-The TTS module is used by `packages/web/server/index.js` for:
-- Generating speech streams for client playback.
-- Generating speech buffers for caching.
-- Sanitizing text before TTS synthesis. Historical summarization calls now return local fallback text.
-- Sanitizing text to remove non-speakable content.
-
-The historical summarization API is shared with notifications and notes, but currently acts as a no-model fallback/stub.
-
-The server-side TTS approach bypasses mobile Safari's audio context restrictions by generating audio on the server and streaming to clients.
-
-## Notes for contributors
-
-### Adding new TTS features
-1. Add new methods to `packages/web/server/lib/tts/service.js` TTSService class.
-2. Export public functions from `packages/web/server/lib/tts/index.js`.
-3. Follow existing patterns for API key resolution and error handling.
-4. Ensure all text is sanitized before TTS synthesis.
-5. Consider adding new voice options to `TTS_VOICES` constant.
-
-### Text sanitization
-- Always call `sanitizeForTTS` on text before passing to TTS generation.
-- The sanitization removes markdown, code blocks, URLs, file paths, shell commands, and special characters.
-- This prevents the TTS from reading out technical formatting that sounds unnatural.
-
-### Error handling
-- `generateSpeechStream` and `generateSpeechBuffer` throw descriptive errors for missing API keys or empty text.
-- `summarizeText` does not call Zen and returns mode-specific fallback text with `summarized: false`.
-- All errors are logged to console with `[TTSService]` or `[Summarize]` prefix.
-
-### API key management
-- TTSService caches OpenAI client instance and recreates when API key changes.
-- API key changes are detected by comparing with `_lastApiKey` property.
-- This allows dynamic API key updates without server restart.
-
-### Testing
-- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
-- Test API key resolution with environment variable and auth file.
-- Test speech generation with various text lengths and voice options.
-- Test summarization stub behavior above and below threshold.
-- Test sanitization with markdown, URLs, and code blocks.
-- Verify streaming and buffer generation produce valid MP3 audio.
-
-## Verification notes
-
-### Manual verification
-1. Configure OpenAI API key via environment variable or OpenCode settings.
-2. Test `ttsService.isAvailable()` returns true.
-3. Call `ttsService.generateSpeechStream({ text: 'Hello world' })` and verify stream is returned.
-4. Call `ttsService.generateSpeechBuffer({ text: 'Hello world' })` and verify Buffer is returned.
-5. Test `summarizeText` with text above and below threshold.
-6. Test `sanitizeForTTS` with markdown, URLs, and code blocks.
-
-### API endpoint verification
-1. Start web server and access TTS endpoint via client.
-2. Verify audio plays correctly in browser.
-3. Test on mobile Safari to verify bypass of audio context restrictions.
-4. Test with long messages to verify summarization is triggered.

package/server/lib/tunnels/DOCUMENTATION.md.bak

@@ -1,21 +0,0 @@
-# Tunnels Module Documentation
-
-## Purpose
-This module contains tunnel provider orchestration for AiWorker, including provider registry/service wiring, managed remote token config lifecycle, and tunnel HTTP route registration.
-
-## Entrypoints and structure
-- `packages/web/server/lib/tunnels/index.js`: tunnel service orchestration.
-- `packages/web/server/lib/tunnels/executable-search.js`: cross-platform executable discovery, including Windows Store app aliases.
-- `packages/web/server/lib/tunnels/registry.js`: provider registry.
-- `packages/web/server/lib/tunnels/managed-config.js`: managed remote tunnel token/preset persistence runtime.
-- `packages/web/server/lib/tunnels/install-help.js`: provider/platform install command metadata for missing tunnel dependencies.
-- `packages/web/server/lib/tunnels/routes.js`: tunnel API route registration and request orchestration runtime.
-- `packages/web/server/lib/tunnels/types.js`: tunnel constants, normalization, and shared type helpers.
-- `packages/web/server/lib/tunnels/providers/cloudflare.js`: Cloudflare tunnel provider implementation.
-- `packages/web/server/lib/tunnels/providers/ngrok.js`: Ngrok quick tunnel provider implementation.
-
-## Public exports (routes.js)
-- `createTunnelRoutesRuntime(dependencies)`: creates tunnel routes runtime and helpers.
-- Returned API:
-  - `registerRoutes(app)`
-  - `startTunnelWithNormalizedRequest(request)`

package/server/lib/ui-auth/DOCUMENTATION.md.bak

@@ -1,44 +0,0 @@
-# UI Auth Module Documentation
-
-## Purpose
-This module owns AiWorker UI authentication for browser access, including password session auth, WebAuthn passkeys, and trusted-device session handling.
-
-Trusted-device access has one durable credential model: a remote client bearer token stored by `packages/web/server/lib/client-auth/remote-clients.js`. Password, passkey, and Pairing v2 are issuance methods for that credential, not separate credential systems. Issued client tokens are returned once, stored server-side only as hashes, and are later authenticated via `Authorization: Bearer oc_client_...`.
-
-Pairing v2 is implemented by `packages/web/server/lib/client-auth/pairing.js`. It stores short-lived one-time pairing sessions with hashed secrets, exposes create/cancel/redeem routes under `/api/client-auth/pairing/*`, and redeems a valid pairing secret into the same remote client token used by password/passkey trusted-device flows.
-
-## Entrypoints and structure
-- `packages/web/server/lib/ui-auth/ui-auth.js`: UI auth controller runtime, cookie/session issuance, rate limiting, and auth route handlers.
-- `packages/web/server/lib/ui-auth/ui-passkeys.js`: passkey store and WebAuthn registration/authentication verification helpers.
-- `packages/web/server/lib/client-auth/remote-clients.js`: trusted-device client token storage, bearer authentication, last-used tracking, and revocation.
-- `packages/web/server/lib/client-auth/pairing.js`: short-lived Pairing v2 sessions and one-time secret redemption into trusted-device client tokens.
-
-## Public exports (ui-auth.js)
-- `createUiAuth({ password, cookieName, sessionTtlMs, readSettingsFromDiskMigrated })`: creates UI auth controller with methods:
-  - `enabled`
-  - `requireAuth(req, res, next)`
-  - `handleSessionStatus(req, res)`
-  - `handleSessionCreate(req, res)`
-  - `handlePasskeyStatus(req, res)`
-  - `handlePasskeyRegistrationOptions(req, res)`
-  - `handlePasskeyRegistrationVerify(req, res)`
-  - `handlePasskeyAuthenticationOptions(req, res)`
-  - `handlePasskeyAuthenticationVerify(req, res)`
-  - `handlePasskeyList(req, res)`
-  - `handlePasskeyRevoke(req, res)`
-  - `handleResetAuth(req, res)`
-  - `ensureSessionToken(req, res)`
-  - `dispose()`
-
-## Public exports (ui-passkeys.js)
-- `createUiPasskeys({ passwordBinding, readSettingsFromDiskMigrated, storeFile, rpName, challengeTtlMs })`: creates passkey runtime with methods:
-  - `enabled`
-  - `getStatus(req)`
-  - `listPasskeys(req)`
-  - `revokePasskey(req, passkeyId)`
-  - `clearAllPasskeys()`
-  - `beginRegistration(req, { label })`
-  - `finishRegistration(payload)`
-  - `beginAuthentication(req)`
-  - `finishAuthentication(payload)`
-  - `dispose()`