@aiworker/web 1.22.0 → 1.23.0

package/server/index.d.ts.bak

@@ -1,39 +0,0 @@
-import type { Express } from "express";
-import type { Server } from "http";
-
-export interface WebUiServerController {
-  expressApp: Express;
-  httpServer: Server;
-  getPort: () => number | null;
-  getOpenCodePort: () => number | null;
-  isReady: () => boolean;
-  restartOpenCode: () => Promise<void>;
-  stop: (options?: { exitProcess?: boolean }) => Promise<void>;
-}
-
-export interface StartWebUiServerOptions {
-  port?: number;
-  host?: string;
-  attachSignals?: boolean;
-  exitOnShutdown?: boolean;
-  uiPassword?: string | null;
-}
-
-export declare function startWebUiServer(
-  options?: StartWebUiServerOptions
-): Promise<WebUiServerController>;
-
-export declare function gracefulShutdown(options?: { exitProcess?: boolean }): Promise<void>;
-export declare function setupProxy(app: Express): void;
-export declare function restartOpenCode(): Promise<void>;
-export declare function parseArgs(argv?: string[]): {
-  port: number;
-  host?: string;
-  uiPassword: string | null;
-  tryCfTunnel: boolean;
-  tunnelProvider?: string;
-  tunnelMode?: string;
-  tunnelConfigPath?: string | null;
-  tunnelToken?: string;
-  tunnelHostname?: string;
-};

package/server/lib/agent-tool/DOCUMENTATION.md.bak

@@ -1,119 +0,0 @@
-# Managed AiWorker Agent Tool
-
-## Purpose
-
-This module exposes AiWorker to agents as typed OpenCode custom tools. There
-are two, because controlling sessions and driving a page are separate intents
-the user can want independently:
-
-- `aiworker` — projects, sessions, worktrees, and scheduled tasks. Enabled
-  while the persisted `agentControlToolEnabled` setting is not `false`.
-- `aiworker_web` — looking at and interacting with the page in AiWorker's
-  browser panel. Enabled while `agentWebToolEnabled` is not `false`.
-
-Both default to on, are toggled in Settings → General → OpenCode CLI, and apply
-on the next managed OpenCode restart. Each tool carries only its own actions and
-only the parameters those actions use, so turning one off removes its inputs
-from the schema rather than leaving them visible. The plugin is injected only
-when AiWorker launches and owns the OpenCode process, and not at all when
-both settings are `false`.
-
-- The plugin accepts the action's inputs either inside `parameters` or beside
-  `action`, because models produce both shapes; an explicit `parameters` object
-  wins on a conflict. Rejecting the flattened shape turned a call that plainly
-  carried a `url` into "url is required", which reads as a broken tool rather
-  than a malformed call.
-
-## Runtime flow
-
-1. The AiWorker HTTP listener binds and publishes its authoritative port.
-2. `prepareManagedOpenCodeEnv()` materializes the plugin under
-   `<openchamber-data-dir>/agent-tool/` and appends its `file://` URL to
-   `OPENCODE_CONFIG_CONTENT` without replacing existing plugin entries.
-3. A random per-child token and loopback callback URL are added only to the
-   managed OpenCode child environment.
-4. The plugin calls `POST /api/openchamber/agent-tool` with its typed input and
-   OpenCode's authoritative session directory.
-5. The route delegates the fixed action allowlist directly to the shared
-   AiWorker control service. The CLI uses the same service through its
-   authenticated HTTP adapter, so Goal Mode ordering, wait behavior,
-   partial-failure reporting, and scheduled-task contracts have one owner.
-6. Each action definition owns a short presentation title and a separate
-   agent-facing description. The generated schema uses the description to state
-   required inputs or one non-obvious behavior, while completed calls use the
-   short title in native tool metadata.
-
-## Agent context budget
-
-- The tool exposes one shared parameter object rather than repeating parameters
-  in a large per-action union. Action descriptions carry only required inputs,
-  defaults, or one non-obvious semantic detail.
-- Obvious fields rely on their names and JSON types. Parameter descriptions are
-  reserved for formats, dependencies, scope, and behavior that cannot be safely
-  inferred from the field name.
-- Session dispatches do not wait by default. Agents are told to set `wait` only
-  when the user asks or the next step requires the completed result.
-- The tool exposes only agent-relevant actions
-  (`AIWORKER_AGENT_TOOL_ACTIONS`): `schedule.status` stays CLI-only because
-  `schedule.list` already returns scheduler status, and enable/disable are one
-  `schedule.toggle` action driven by the `disabled` boolean.
-- The tool description frames intent: created sessions and scheduled tasks are
-  user-facing work the user follows up with, never a channel for the agent to
-  delegate parts of its own current task.
-- Optional behavior switches (`worktree`, `goal`, `agent`, `variant`, `wait`)
-  state their default and an explicit "only when the user asks" rule so agents
-  do not invent worktrees, goal mode, or waits the user never requested.
-- Detailed combination rules are enforced by the shared control service and
-  returned as actionable usage errors only after an invalid call. Per-action
-  examples and a repeated per-action parameter schema are intentionally omitted.
-
-## Security invariants
-
-- The callback accepts loopback requests only and requires the current
-  per-child bearer token using a timing-safe comparison.
-- The token is never persisted, logged, returned to the UI, or written into
-  the materialized plugin.
-- Inputs map to a fixed action and parameter allowlist. There is no arbitrary
-  CLI, shell, route, or URL forwarding.
-- Session/worktree deletion and project-path registration are not exposed.
-- An aborted tool request propagates an abort signal into the shared service.
-
-## Result contract
-
-Every completed call returns JSON:
-
-```json
-{
-  "schemaVersion": 1,
-  "ok": true,
-  "action": "session.create",
-  "data": {}
-}
-```
-
-Command and operational failures use the same envelope with `ok: false` and
-an `error` object. OpenCode-level cancellation can still produce a native tool
-error state.
-
-## Runtime parity
-
-- Web and Desktop managed OpenCode: injected automatically.
-- External OpenCode selected with `OPENCODE_HOST` or skip-start: not injected,
-  because AiWorker does not control that process environment.
-- VS Code: not injected; the extension owns a separate OpenCode lifecycle.
-- Hosted and Capacitor mobile clients use the server's managed OpenCode tool
-  when connected to such a server; no tool runs in the client runtime.
-
-## The calling tool is part of the request
-
-Each generated tool sends its own name with every callback. Models routinely
-drop the namespace their tool's name appears to supply — `aiworker_memory`
-asked for `memory.read` gets called as `read` — and resolving the bare name
-inside the calling tool's action set makes that unambiguous even where it is not
-globally (`delete` belongs to both schedule and memory).
-
-Resolution never reaches outside the tool that asked: `open` from the memory
-tool fails rather than driving the browser. An unresolvable action answers with
-the actions that tool actually has, because an error that only says
-"unsupported" leaves the model to guess a second wrong name — which is exactly
-what happened before this existed.

package/server/lib/browser-control/DOCUMENTATION.md.bak

@@ -1,50 +0,0 @@
-# Browser Control Broker
-
-## Purpose
-
-This module carries agent browser actions from the server to the client that
-owns the in-app browser view, and the result back. The browser lives in a
-renderer, not in the server process, so the server can never act on a page
-itself; it can only ask and wait.
-
-## Boundaries
-
-- `broker.js` owns request lifetime: it publishes one action through the
-  injected `emitRequest`, holds the pending request, and settles it on a client
-  result, a timeout, or an abort signal. It knows nothing about transports.
-- `routes.js` is the result callback (`POST /api/browser-control/result`). It
-  validates the envelope and hands the outcome to the broker.
-- `../../index.js` supplies `emitRequest`, which writes the request to the
-  AiWorker SSE clients and returns how many were reached.
-- `../openchamber-control/service.js` is the only caller. It maps the
-  `browser.*` actions of the `aiworker_web` tool onto `broker.request()` and
-  owns their parameter validation.
-- The client half is `packages/ui/src/lib/browser/controlClient.ts`, which
-  registers the mounted browser pane as the one responder.
-
-## Invariants
-
-- Capability belongs to the connection, not to configuration. A client declares
-  it can drive a page by opening its event stream with `browser=1`, which only
-  a Chromium host does; the flag lives and dies with that connection, so there
-  is no setting to enable and no restart to remember.
-- `emitRequest` counts only clients that can serve the action. `browser.open`
-  needs any client, because opening a tab is what creates a view; every other
-  action needs a declared-capable one.
-- Exactly one client performs a request. The broadcast reaches everyone who
-  could serve it, so a client claims the request over
-  `POST /api/browser-control/claim` and acts only if granted; the first claim
-  wins and every other client does nothing. Deciding by whose result arrives
-  first would be too late, because by then each of them has already clicked.
-  A claim for a settled request is refused for the same reason.
-- Nobody listening is answered immediately with a 503 describing the
-  environment, never by blocking for the full timeout. A blocked wait followed
-  by a timeout cannot be told apart from a page that hung.
-- A client that accepted a request and then disappeared still times out.
-  Assuming success would report a page interaction that never happened.
-- A result for an unknown request id is accepted with `matched: false`, not an
-  error: a client answering after the timeout has behaved correctly.
-- The result route parses its own body. This server has no global body parser,
-  and a missing one silently turns every answer into an agent-visible timeout.
-- Request payload limits are sized for a page snapshot (visible text plus every
-  interactive element), not for a control message.

package/server/lib/context-obligatory/DOCUMENTATION.md.bak

@@ -1,19 +0,0 @@
-# Context Obligatory Messages
-
-Messages explicitly pinned by the user are stored under
-`session.metadata.aiworker.context_obligatory_messages` as `{ id, createdAt,
-role }`. The UI uses a fresh-read metadata merge when pinning or unpinning.
-
-The server runtime listens for OpenCode's dedicated `session.compacted` event.
-It fetches every pinned message by ID, keeps non-empty text parts, sorts them
-by the stored creation time, and immediately sends one synthetic user part
-through `prompt_async`. OpenCode's session runner serializes this with its own
-post-compaction continuation. Missing individual messages are skipped without
-discarding the remaining context. Ordinary idle events perform no work and
-make no requests.
-
-After a successful send, the runtime merge-writes
-`context_obligatory_last_compaction_message_id`. This cursor prevents a
-replayed compaction event from reinjecting the same summary. The runtime is
-owned by the AiWorker web backend and therefore is not available in
-extension-only VS Code mode.

package/server/lib/dev-tunnel/DOCUMENTATION.md.bak

@@ -1,57 +0,0 @@
-# Dev Server Tunnel
-
-## Purpose
-
-This module carries raw TCP bytes between a desktop client and a dev server
-running on the AiWorker host, so a remote dev server can be opened in the
-browser panel without anything being rewritten.
-
-The page is served from a real origin at the root of its own host. That is the
-whole design: absolute URLs resolve, cookies scope correctly, HMR sockets
-connect, and developer tools behave as they do locally. No HTML, header, or
-URL is inspected or modified, which is what the previous rewriting proxy did
-and what made it fragile per framework.
-
-## Boundaries
-
-- `runtime.js` is the host end: it accepts the WebSocket upgrade at
-  `/api/dev-tunnel`, authenticates it, opens a TCP socket to the requested
-  local port, and pipes the two together.
-- `client.js` is the local end: it binds a loopback listener on the user's
-  machine and pipes each accepted connection through one WebSocket. It lives in
-  this package because it needs a WebSocket client the package already depends
-  on; the desktop shell drives it over IPC.
-- Port discovery is not owned here. `runtime.js` is given the reachable set by
-  the same dev-server discovery the user's own list is built from.
-- The browser panel decides when to tunnel; this module never chooses a target.
-  `packages/ui/src/lib/browser/devTunnel.ts` owns that decision, including for
-  navigations the page starts itself: a tunnelled page that sends the view to
-  another loopback port means a port on the host, not on the user's machine.
-
-## Invariants
-
-- The reachable set is exactly what dev-server discovery offers the user, never
-  "any loopback port". Without that restriction an authenticated client could
-  dial arbitrary local services on the host — databases, admin panels, the
-  OpenCode API — through this socket.
-- Authentication depends on whether the caller is a browser, and this is
-  deliberate rather than a relaxation:
-  - With an `Origin` header the request came from a browser context, and the
-    usual origin allowlist applies unchanged. That check is a CSRF defence: a
-    hostile page can make a browser open a WebSocket carrying ambient cookies,
-    and the origin is what exposes it.
-  - With no `Origin` the request must carry client-token auth. A browser cannot
-    reach this path — the WebSocket API always sends an origin and never lets a
-    page set an `Authorization` header — so this case is the desktop shell.
-- Concurrency is capped per host, not per page, because one page load opens
-  many sockets.
-- A connection that cannot be established fails the socket rather than holding
-  it open; a stalled connect is bounded by an explicit timeout, and so is the
-  WebSocket handshake. While it is pending the local socket is paused and its
-  buffered bytes are capped, so a local process writing into a stalled
-  handshake cannot grow the desktop app's memory.
-- A tunnel that cannot be opened is reported to the panel, never replaced by the
-  plain loopback URL. On a remote instance that substitution would change which
-  machine answers and show local content under a remote address.
-- Closing either end closes the other. A half-open pipe would leave the page
-  waiting on bytes that will never arrive.

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

@@ -1,100 +0,0 @@
-# Dictation module
-
-Server-authoritative speech-to-text for the chat composer, plus local
-text-to-speech. The client streams 16 kHz mono PCM16 chunks (base64) over a
-WebSocket while the user speaks; the server buffers them and transcribes each
-segment exactly once, when the segment is committed.
-
-Transcription is deliberately not incremental. Parakeet is an offline model
-trained on whole utterances, so re-decoding the growing buffer to animate a
-live transcript costs O(n^2) work for a result the final decode replaces. The
-composer shows no text while recording and inserts the full transcript on
-stop.
-
-Local TTS (Kokoro and Piper/VITS via sherpa-onnx OfflineTts) runs in the same
-worker process and is exposed as `POST /api/dictation/tts/speak` (JSON
-`{text, speakerId?, speed?, model?, language?, languageSample?}` → WAV bytes; 503 with
-`reasonCode` while the model is downloading). TTS models live in the same
-catalog/downloader as STT models (`local/model-catalog.js`
-`LOCAL_TTS_MODEL_CATALOG`) and are managed by the same status/download/delete
-routes.
-
-Each TTS catalog entry declares the `languages` it speaks. With
-`language: 'auto'` the service detects the language of `languageSample` — the
-whole message the chunk belongs to, sent by the client with every chunk — or
-of `text` when no sample is given
-(`../tts/language-detect.js`, script plus function-word scoring, no
-dependencies) and keeps the caller's model when it speaks that language;
-otherwise it switches to the catalog model for the language, downloading it on
-first use like any other model, and starts from that model's default speaker
-(`defaultSpeakerByLanguage`) instead of the caller's speaker id. A language no
-catalog model covers keeps the caller's model, so text is always spoken. The
-response carries `X-Speech-Model` and `X-Speech-Language`.
-
-## Ownership
-
-- `runtime.js` — registers `GET /api/dictation/status`,
-  `POST /api/dictation/models/:modelId/download`, and the
-  `/api/dictation/ws` WebSocket endpoint (auth-gated the same way as the
-  terminal WS: UI session token or `oc_url_token`, plus origin check).
-  Created from the startup pipeline (`startup-pipeline-runtime.js`) before
-  the generic OpenCode proxy so routes are not shadowed.
-- `stream-manager.js` — `DictationStreamManager`, one per WS connection.
-  Chunk reordering by `seq` + ack, resampling to the provider rate, segment
-  splitting, silence suppression by PCM peak, partial-transcript
-  concatenation, adaptive finalization timeout.
-- `service.js` — provider resolution and readiness. Providers:
-  - `local` (default): sherpa-onnx Parakeet TDT in a forked worker process.
-    Models auto-download in the background on first use; while missing, the
-    stream fails with `reasonCode: 'model_download_in_progress'` and the
-    status route reports per-model install/download state.
-  - `openai-compatible`: buffered per-segment transcription against any
-    OpenAI-compatible `/v1/audio/transcriptions` endpoint
-    (`openai-compatible-session.js`, reuses `../tts/stt.js`).
-- `local/` — worker process + client (IPC, idle shutdown TTL), sherpa
-  recognizer engine and segment session (one decode per committed segment),
-  model catalog and downloader. The native `sherpa-onnx-node` addon is only
-  ever loaded inside the worker process.
-- `audio.js` — PCM16 helpers: format parsing, peak, WAV wrapping, streaming
-  linear resampler.
-
-## WebSocket protocol (JSON text frames)
-
-Client → server: `start {dictationId, format, options}`,
-`chunk {dictationId, seq, audio}`, `finish {dictationId, finalSeq}`,
-`cancel {dictationId}`, `ping`.
-
-Server → client: `ready`, `ack {ackSeq}`, `partial {text}`,
-`finish_accepted {timeoutMs}`, `final {text}`,
-`error {error, retryable, reasonCode?}`, `pong`.
-
-`options` in `start` carries the client-selected provider config:
-`{ provider: 'local' | 'openai-compatible', language?, localModel?,
-openaiCompatible?: { baseUrl, model, apiKey } }`.
-
-## Segmentation
-
-A dictation is one segment unless it runs long. Past `segmentMinSeconds`
-(60 s) the manager commits on the first silent chunk, so cuts land at a pause
-rather than mid-word; `segmentMaxSeconds` (90 s) is a hard cap for speech with
-no pause in it. Client chunks are ~1 s, so "silent chunk" is roughly a second
-of silence.
-
-The bounds exist because Parakeet is a full-attention conformer: decode cost
-and peak memory grow quadratically with segment length. Measured on Parakeet
-v3 int8 with 2 threads: 60 s took 2.1 s and +90 MB, 180 s took 9.3 s and
-+490 MB, 300 s took 21.3 s and +1.5 GB. Committed segments decode while the
-user is still speaking, so only the tail is left to transcribe on stop.
-
-## Invariants
-
-- Never load `sherpa-onnx-node` in the main server process.
-- Transcription happens on commit only; sessions never emit non-final
-  transcripts. The `partial` messages a client receives are the concatenation
-  of already-committed segments, and exist so a dictation that fails partway
-  can be salvaged instead of losing minutes of speech.
-- The stream manager acks only the highest contiguous seq; the client is
-  expected to retain unacked segments for retry/replay.
-- Silence-only segments (peak < 300) are cleared, never committed, so
-  Whisper-style providers do not hallucinate on silence.
-- Model files live under `~/.config/openchamber/speech-models`.

package/server/lib/event-stream/DOCUMENTATION.md.bak

@@ -1,62 +0,0 @@
-# Event Stream Module Documentation
-
-## Purpose
-This module contains the AiWorker message-stream WebSocket protocol and runtime bridge. It keeps the browser-facing WebSocket transport separate from the upstream OpenCode SSE transport.
-
-## Entrypoints and structure
-- `packages/web/server/lib/event-stream/index.js`: public entrypoint re-exporting protocol and runtime helpers.
-- `packages/web/server/lib/event-stream/global-hub.js`: shared global upstream SSE hub for server-side subscribers and browser WS fan-out.
-- `packages/web/server/lib/event-stream/global-ws-bridge.js`: browser-facing global WS bridge that subscribes clients to the shared global hub.
-- `packages/web/server/lib/event-stream/directory-ws-bridge.js`: browser-facing per-directory WS bridge that owns one scoped upstream reader per connection.
-- `packages/web/server/lib/event-stream/protocol.js`: path constants, SSE envelope parsing, and WebSocket frame serialization helpers.
-- `packages/web/server/lib/event-stream/upstream-reader.js`: reusable upstream SSE reader with event-id tracking, stall recovery, and reconnect handling.
-- `packages/web/server/lib/event-stream/runtime.js`: thin WebSocket server runtime for upgrade handling and path dispatch to the global/directory bridges.
-- `packages/web/server/lib/event-stream/protocol.test.js`: unit tests for protocol helpers.
-- `packages/web/server/lib/event-stream/upstream-reader.test.js`: unit tests for upstream SSE reader behavior.
-- `packages/web/server/lib/event-stream/runtime.test.js`: unit tests for runtime-side broadcaster behavior.
-
-## Public exports
-
-### Protocol helpers
-- `MESSAGE_STREAM_GLOBAL_WS_PATH`: `/api/global/event/ws`
-- `MESSAGE_STREAM_DIRECTORY_WS_PATH`: `/api/event/ws`
-- `MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS`: heartbeat interval for browser-facing WS connections.
-- `parseSseEventEnvelope(block)`: parses an SSE block into `{ eventId, directory, payload }`.
-- `sendMessageStreamWsFrame(socket, payload)`: serializes and sends a JSON WS frame.
-- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId` and `directory`.
-
-### Runtime helpers
-- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
-- `createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent })`: returns a broadcaster that fans out the same synthetic UI event to SSE and WS clients.
-- `createMessageStreamWsRuntime(...)`: mounts the message-stream WS server, upgrade handler, and SSE-to-WS bridge onto the web HTTP server.
-
-### Upstream reader helpers
-- `DEFAULT_UPSTREAM_STALL_TIMEOUT_MS`: default idle timeout before an attached upstream SSE fetch is aborted for reconnect.
-- `DEFAULT_UPSTREAM_RECONNECT_DELAY_MS`: default delay between upstream reconnect attempts.
-- `createUpstreamSseReader(...)`: creates a start/stop reader for OpenCode SSE streams. The reader parses SSE blocks, tracks the latest `Last-Event-ID`, reconnects after closed or stalled upstream streams, and reports events through callbacks.
-
-## Runtime behavior
-- Browser clients connect to the WS endpoints above.
-- AiWorker still fetches OpenCode upstream event streams over SSE.
-- The web server creates one shared global message-stream hub. OpenCode watcher side effects and global WS clients subscribe to that hub, so there is one upstream `/global/event` SSE reader for both server-side processing and browser fan-out.
-- The global hub keeps a bounded replay buffer keyed by SSE `eventId` so reconnecting browser clients can receive buffered events after their requested `Last-Event-ID`.
-- Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
-- If an upstream SSE stream stalls after the browser WS is already ready, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
-- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and can run scoped state repair without requiring the browser WS to close.
-- Health checks are reserved for initial upstream connect failures and explicit upstream-unavailable responses, not for ordinary stall recovery on an already-established stream.
-- Global synthetic events such as `aiworker:session-status`, `aiworker:session-activity`, `aiworker:notification`, and `aiworker:heartbeat` are preserved on the WS path, but heartbeat frames are emitted only while an upstream SSE stream is actively attached.
-- Global UI broadcasts are fan-out capable across both SSE and WS clients.
-- The reusable upstream reader centralizes SSE fetch/parsing/reconnect behavior for the WS runtime and OpenCode watcher. Additional event consumers should move to it only with parity tests for their lifecycle and error semantics.
-- Browser transport concerns live in the WS bridge modules; server-side global stream ownership lives in `global-hub.js`.
-
-## Notes for contributors
-- Keep protocol helpers pure and small so they can be unit tested without spinning up a server.
-- Keep `runtime.js` focused on WebSocket upgrade and endpoint dispatch. Put global browser-client lifecycle in `global-ws-bridge.js`, directory stream lifecycle in `directory-ws-bridge.js`, and upstream stream sharing in `global-hub.js`.
-- Do not change upstream OpenCode transport assumptions here; OpenCode remains SSE-based.
-- Keep global replay bounded; do not turn it into an unbounded event log.
-
-## Testing
-- Run `bun test packages/web/server/lib/event-stream/protocol.test.js`
-- Run `bun test packages/web/server/lib/event-stream/upstream-reader.test.js`
-- Run `bun test packages/web/server/lib/event-stream/runtime.test.js`
-- Run repo validation before finalizing: `bun run type-check`, `bun run lint`, `bun run build`

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

@@ -1,47 +0,0 @@
-# FS Module Documentation
-
-## Purpose
-Own filesystem API behavior for the web server runtime, including workspace-bound file operations, directory listing, reveal, and background command execution jobs.
-
-## Entrypoints and structure
-- `packages/web/server/lib/fs/routes.js`: route registration and runtime-owned state for `/api/fs/*` endpoints.
-- `packages/web/server/lib/fs/search.js`: fuzzy filesystem search runtime used by non-FS routes (for example project icon discovery).
-
-## Public exports
-- `registerFsRoutes(app, dependencies)` from `routes.js`
-  - Registers all filesystem routes:
-    - `GET /api/fs/home`
-    - `POST /api/fs/mkdir`
-    - `GET /api/fs/read`
-    - `GET /api/fs/raw`
-    - `GET /api/fs/serve/:path(*)`
-    - `POST /api/fs/write`
-    - `POST /api/fs/upload`
-    - `POST /api/fs/delete`
-    - `POST /api/fs/rename`
-    - `POST /api/fs/reveal`
-    - `POST /api/fs/exec`
-    - `GET /api/fs/exec/:jobId`
-    - `GET /api/fs/list`
-    - `GET /api/fs/git-dirs` — shallow nested git repository discovery for the
-      Git tab (depth- and visit-capped readdir walk; `.git` directory, file, or
-      symlink marks a repository boundary; junk directories and symlinks are
-      never descended into)
-  - Owns exec job queue state (`execJobs`) and lifecycle/TTL pruning.
-  - Enforces workspace boundary checks with active project + worktree fallback support.
-  - The active project directory is validated with `fs.realpath`, so when the project root is itself a symlink the workspace base no longer matches the paths the client sends. Workspace resolution therefore retries against the raw directory the client requested (`requestedDirectory` from `resolveProjectDirectory`) before falling back to worktree roots. Symlinks are still resolved afterwards, and write/exec routes keep their canonical containment check against the resolved base.
-- `createFsSearchRuntime({ fsPromises, path, spawn, resolveGitBinaryForSpawn })` from `search.js`
-  - Returns `{ searchFilesystemFiles(rootPath, options) }`.
-  - Supports fuzzy matching, hidden-file handling, and optional `git check-ignore` filtering.
-
-## Composition contract with `index.js`
-- `index.js` provides composition-time dependencies only (platform primitives + callbacks such as `resolveProjectDirectory`, `normalizeDirectoryPath`, and `buildAugmentedPath`).
-- `index.js` no longer owns FS route handlers or FS exec job state.
-
-## Notes for contributors
-- Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
-- Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
-- Read-only routes authorize the requested path against the workspace before resolving symlinks. A symlink reached through the workspace may therefore target a file outside it, while a directly requested outside path still requires an exact-path grant. Write routes keep canonical-target boundary checks.
-- If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
-- `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.
-- `POST /api/fs/upload` accepts one `application/octet-stream` body with `path` and optional `overwrite=true` query parameters. The body streams into a same-directory temp file with a 100 MiB default cap configurable through `AIWORKER_FS_UPLOAD_MAX_BYTES`; failed and oversized uploads clean up that temp file. New files commit through an atomic no-replace link, existing files return `409` unless overwrite is explicit, directory targets are rejected, and the destination parent resolves before writing so uploads cannot escape through workspace symlinks.