---
name: web-channel
description: >
  Web interface channel: the IClientTransportPort WebSocket transport, access token and origin
  check, authenticated connections, web conversations (store, history, entry mapping, turn state),
  stateless agent configuration, structured question answers, the artifacts.* commands of each conversation board, the skills.* commands, agent CLI login
  (auth.* commands and events), uploads, file search, /health and the WEB_* variables. Use when working with the web module, WebSocket connections, the
  access token or web conversations.
---

# Web channel

> **Maintaining this skill**
>
> Update this document whenever any rule described here changes. The criterion is not
> *which* rule — it is the nature of the change: a transport, authentication, origin or
> serving rule changed → update; a technical refactor that preserves the described behavior →
> leave it alone.

The `WebModule` lives in `packages/server/src/modules/web/`. Anyone who can talk to its socket runs
agents with full autonomy on the host, so every rule below exists to keep that socket reachable only
by the owner. The message contract is the `@agent-remote-control/protocol` package.

## Transport port

- `IClientTransportPort` (`onConnection`) and `IClientConnection` (`send`, `onMessage`, `onClose`,
  `close`) hide the technology, so a WebRTC DataChannel can replace WebSocket.
- `onMessage` delivers parsed JSON, or the raw value when the payload is not JSON. The transport only
  serializes `ServerEvent`; validating commands belongs to the handler through `parseClientCommand`.
- `WsClientTransportAdapter` uses `ws` with `WebSocketServer({ noServer: true })` attached to the
  `upgrade` event of the Nest HTTP server. It accepts the path `/ws` only and destroys the socket of any
  other upgrade. It enforces a 256 KiB payload limit and closes the server on module destroy.

## Origin check

- The upgrade is accepted when the `Origin` host equals the request `Host`, or when the origin is listed
  in `WEB_ALLOWED_ORIGINS` (comma-separated, compared without a trailing slash).
- A missing or malformed `Origin` is rejected. Rejection answers `403` and destroys the socket.
- When the web app reaches the server directly (no proxy), its origin goes in `WEB_ALLOWED_ORIGINS`.

## Access token and auth gate

- `WebAccessTokenService` takes the token from `WEB_ACCESS_TOKEN`, otherwise from
  `<DATA_DIR>/web/access-token`, generated once with `randomBytes(24).toString('base64url')` and file
  mode `0o600`. `verify` compares with `timingSafeEqual` and returns false on a length mismatch.
- On bootstrap it logs `Web interface access token: <token>`.
- `WebConnectionHandler` waits at most 5 s for an `auth` command on each connection. A wrong token, any
  other first command or a timeout sends `auth.failed` and closes with code `4401`. Commands from a
  connection that has not authenticated are never routed.
- A correct token sends `auth.ok` and registers the connection in `WebConnectionRegistryService`, which
  removes it on close and offers `broadcast(event)`.
- Invalid commands from an authenticated connection answer an `error` event.

## Conversations

- Ids are `web-<randomUUID()>` so they never collide with Discord ids in the shared session store. The web
  channel owns its history through `IConversationStorePort`; Discord keeps its own.
- `WebConnectionHandler` routes authenticated commands. `conversation.list` and `conversation.history`
  answer the requester only; `conversation.create` answers the requester with `conversation.created` and
  broadcasts `conversation.updated` to the other connections.
- `conversation.rename { conversationId, title }` (`RenameConversationUseCase`, title trimmed, up to
  `MAX_CONVERSATION_TITLE_LENGTH`) and `conversation.archive { conversationId, archived }`
  (`ArchiveConversationUseCase`, stamping or clearing `archivedAt`) publish `conversation.updated` to every
  connection, the requester included; neither is activity, so `updatedAt` and the place in the list stay. An
  archived conversation still opens and takes messages.
- Every command carrying a `conversationId` for an unknown conversation answers an `error` event before reaching a use case.
- `message.send` returns immediately while the turn streams: `SendConversationMessageUseCase` never rejects,
  records the `user_message` and runs the turn as the CEO only when the conversation is configured.
- Turn callbacks become entries with stable ids (`thought:<turnId>:<role>:<id>`, `tool:<turnId>:<role>:<toolCallId>`,
  `delegation:<delegationId>:<phase>`) so the store and the client upsert by id. `ConversationEntryService` builds
  every entry and owns the clock and the random ids.
- The conversation state (`running`, `queued`, `idle`) belongs to the conversation, not to a turn, and is
  published only when it changes. `WebConversationEventsService` broadcasts each entry before persisting it, and
  keeps the CEO's response being written as an in-memory draft (`conversation.draft`), never stored.
- `JsonConversationStoreAdapter` writes `<DATA_DIR>/web/conversations.json` and
  `<DATA_DIR>/web/history/<id>.json` atomically (temporary file, then rename), debounced by 1 s per file,
  and flushes at the end of every turn and on module destroy. An id reaches a file path only after it is
  found among the known conversations. Files that do not match the protocol schemas are ignored.

Read [references/turns-and-entries.md](references/turns-and-entries.md) before changing `message.send`,
`turn.cancel`, message attachments, the callback-to-entry mapping, entry ids, the conversation state or the draft.

## Command areas

Each area has a reference with the exact commands, events, limits and edge cases. Read it before changing that area.

- **Questions**: `question.answer` with an option or a text (with attachments), the server closing questions
  (`closed: true`), and restoring questions and interrupted work after a restart (`work.resume`,
  `conversation.interrupted`). Read [references/questions.md](references/questions.md).
- **Board**: the `artifacts.*`/`artifact.*` commands over `IArtifactsPort` acting as the web user, the
  `artifact.result` answers, the `artifact.updated`/`artifact.deleted` broadcasts and `projects.list`. Read
  [references/board.md](references/board.md).
- **Skills**: `skills.list`, `skill.get` and `skill.delete` over `IAgentSkillsPort`; the web never writes a skill.
  Read [references/skills.md](references/skills.md).
- **Agents**: the stateless configuration API (`agents.list`, `models.list`, `efforts.list`, `profiles.get`,
  `profiles.set`), the cached `quota.get` and `auth.status` queries that answer `quota.failed`/`auth.status.failed`
  (never `error`), and the CLI login (`auth.login`, `auth.input`, `auth.cancel`) broadcast to every connection.
  Read [references/agents.md](references/agents.md).
- **Composer**: `prompts.history`, the per-connection `files.search` session for `@` mentions and the framed
  `upload.*` protocol into `.arc-uploads/<conversationId>/`. Read [references/composer-commands.md](references/composer-commands.md).

## Health

`GET /health` belongs to `AppController`.

## Serving the web app

`WebStaticModule` (imported by `WebModule`) configures `ServeStaticModule` from `WEB_STATIC_DIR`: when it
is set, the server serves that directory (the build of `packages/web`) on `PORT` and answers every other
`GET` with its `index.html`, so the client-side routes of React Router resolve. The page and `/ws` then share
one origin. When it is empty nothing is served. `SERVER_ROUTES` in `web-static.module.ts` lists the paths the
server answers itself (`/health`, `/ws`); a new HTTP route of the server is added there, or the fallback
shadows it. The Docker image sets `WEB_STATIC_DIR`.

Without it, the web app is a separate app (Vite dev server or preview locally, any static host otherwise)
that reaches the server through the WebSocket, so its origin must be listed in `WEB_ALLOWED_ORIGINS` unless
a proxy in front of both makes the upgrade same-origin.

## Environment

`WEB_ENABLED` (default `true`; `false` leaves `WebModule` out of `AppModule`), `WEB_ACCESS_TOKEN`,
`WEB_ALLOWED_ORIGINS` and `WEB_STATIC_DIR`. The agent login commands follow `AGENT_AUTH_ENABLED`, `AGENT_AUTH_LOGIN_TIMEOUT_MS` and
`AGENT_AUTH_STATUS_TIMEOUT_MS`.
