ompclaw 0.3.0

package/docs/guide.md

@@ -0,0 +1,360 @@
+# Operator guide
+
+[Back to the README](../README.md)
+
+`ompclaw` runs one persistent OMP RPC session and exposes it through enabled, authenticated transport adapters. It is a gateway process, not an OMP extension and not a per-chat session launcher. Telegram and WebSocket clients feed the same OMP session.
+
+## Before you start
+
+Use the [user quickstart](../README.md#user-quickstart) for package installation, token-free configuration, private environment file creation, `telegram-allow`, `doctor`, and foreground or service startup.
+
+The following operating assumptions are intentional:
+
+- OMP is version 17.0.0 or newer and is already authenticated for the provider you intend to use.
+- One process owns one gateway state directory and one OMP session.
+- Every incoming transport identity must be bound to a local principal before it is admitted.
+- A token authorizes a WebSocket credential only after that credential's identity resolves to a principal.
+- Telegram uses Bot API long polling. Do not configure a webhook for the same bot token.
+- WebSocket is intended to bind to loopback by default. The only HTTP route is the unauthenticated health response.
+
+## Architecture and persistence
+
+At startup the gateway acquires `ompclaw.lock` in `stateDir`, opens `ompclaw.sqlite`, resolves transport secrets, constructs the OMP runtime, starts OMP, then starts the transport adapters. If another process holds the gateway lock, startup stops before opening the database.
+
+```text
+Telegram long poller  ─┐
+                       ├─ authenticated transport adapter ─┐
+WebSocket client      ─┘                                    │
+                                                            v
+                                                 one OMP RPC session
+                                                            │
+                                                            v
+                                        SQLite state and session checkpoint
+```
+
+The start order prevents an adapter or scheduler from accepting work before the OMP session is available. On shutdown, the scheduler stops first, then adapters stop before OMP, and the state store closes before the lock is released.
+
+The SQLite database is `~/.omp/agent/ompclaw/ompclaw.sqlite` by default. A newly created database is private to its owner. It records:
+
+| Data | Purpose |
+| --- | --- |
+| principals and transport identities | resolve an inbound identity to authorized local roles |
+| conversation bindings | record the exact OMP session path associated with a transport address |
+| adapter checkpoints | store the active OMP session file and Telegram update progress |
+| inbound messages | deduplicate accepted transport messages |
+| pending UI interactions | keep transport UI metadata until completion or expiry |
+| migration markers | make legacy Telegram import idempotent |
+| scheduled jobs | persist one-shot and cron automation, ownership, next run, retry, and outcome state |
+
+SQLite uses foreign keys, full synchronous mode, and immediate transactions for the legacy import. Do not open the database for concurrent writes or share `stateDir` between gateway instances.
+
+## Configuration reference
+
+The configuration is a bounded JSON document. It must be a regular file, not a symlink, and must be no larger than 256 KiB. Unknown keys are rejected. Paths beginning with `~/` expand to the current user's home; relative paths resolve from the directory where the command is run.
+
+The JSON document never contains a token value. It names environment variables that are read from the process environment or an `--env-file`.
+
+### Top-level fields
+
+| Field | Type and default | Meaning |
+| --- | --- | --- |
+| `workspace` | path, current directory | OMP working directory |
+| `stateDir` | path, `~/.omp/agent/ompclaw` | gateway lock, SQLite database, inbox, exports, and checkpoints |
+| `profile` | identifier, `ompclaw` | OMP profile passed to the RPC child |
+| `omp` | object | OMP runtime settings |
+| `transports` | object | enabled transport settings |
+| `automation` | object | optional durable unattended job runner |
+| `learning` | object | optional experimental gateway-scoped memory and managed-skill capture |
+
+### `omp`
+
+| Field | Type and default | Meaning |
+| --- | --- | --- |
+| `command` | string, `omp` | OMP executable |
+| `model` | optional string | initial OMP model selection |
+| `resume` | optional path | exact OMP session path used only when no persisted session checkpoint exists |
+| `sessionDir` | optional path | OMP session directory |
+| `configFiles` | string array, `[]` | OMP configuration files, passed in order |
+| `args` | string array, `[]` | additional OMP arguments, passed in order |
+| `authBrokerTokenFile` | optional path | private auth-broker token file passed to the OMP child |
+| `allowRpcBash` | boolean, `false` | enables `/shell` and `/abortbash` in the gateway command surface |
+| `inheritHarness` | boolean, `false` | requests inherited harness preparation in the RPC runtime configuration |
+| `autoRestart` | boolean, `true` | restart an unexpectedly exited OMP child with bounded backoff |
+
+`authBrokerTokenFile`, when used, must be private in the same way as the environment file. `allowRpcBash` changes the authority available through the gateway. Leave it disabled unless it is a deliberate operational choice.
+
+### Durable automation
+
+Automation is off by default. Enable it explicitly:
+
+```json
+{
+  "automation": {
+    "enabled": true,
+    "pollIntervalMs": 1000,
+    "retryDelayMs": 15000,
+    "maxAttempts": 3
+  }
+}
+```
+
+| Field | Type and default | Meaning |
+| --- | --- | --- |
+| `enabled` | boolean, `false` | register scheduling host tools and start the durable dispatcher |
+| `pollIntervalMs` | integer, `1000` | scan interval from 250 to 60000 milliseconds |
+| `retryDelayMs` | integer, `15000` | base retry delay from 1000 to 3600000 milliseconds |
+| `maxAttempts` | integer, `3` | maximum failed attempts from 1 to 10 before a one-shot job is disabled |
+
+An authenticated operator can ask OMP to schedule a one-shot job at an ISO 8601 time with an explicit UTC offset, or a recurring cron job with an optional IANA timezone. OMP receives `ompclaw_schedule_job`, `ompclaw_update_job`, `ompclaw_list_jobs`, `ompclaw_set_job_enabled`, `ompclaw_delete_job`, and `ompclaw_run_job` host tools. The model never supplies a principal or delivery route. The gateway binds each job to the active server-derived principal, identity, and conversation.
+
+Use `/jobs` to inspect your jobs, `/job_pause <id>` or `/job_resume <id>` to change dispatch, `/job_run <id>` to make a job due immediately, and `/job_delete <id>` to remove it. Job IDs are intentionally exact and principal-scoped.
+
+The scheduler persists the next occurrence before dispatch. A restart recovers every due job from SQLite. Only one OMP turn runs at a time, so a scheduled job that finds the runtime busy is deferred without consuming an attempt. Other failures use bounded linear backoff. A one-shot job is disabled after success or after exhausting retries. A recurring job advances to its next cron occurrence after success or final failure. Job execution is at least once across process crashes, so prompts that mutate external systems should be idempotent.
+
+Scheduled output and OMP interaction requests return to the conversation that created the job. Telegram can receive output while no inbound request is active. WebSocket jobs require the exact authenticated origin to be connected when delivery occurs.
+
+### Experimental learning and profile isolation
+
+Learning is off by default because OMP marks auto-learn as experimental and automatic capture consumes an extra model turn. A private single-operator setup can enable the full loop:
+
+```json
+{
+  "omp": {
+    "inheritHarness": true
+  },
+  "learning": {
+    "enabled": true,
+    "autoCapture": true,
+    "minToolCalls": 5,
+    "memoryModel": "online"
+  }
+}
+```
+
+| Field | Type and default | Meaning |
+| --- | --- | --- |
+| `enabled` | boolean, `false` | enable isolated Mnemopi memory, `learn`, and `manage_skill` |
+| `autoCapture` | boolean, `false` | run OMP's private capture turn after an eligible stop |
+| `minToolCalls` | integer, `5` | minimum tool calls before automatic capture, from 1 to 100 |
+| `memoryModel` | string, `online` | memory extraction model: `online`, `qwen3-1.7b`, `llama3.2:3b`, `gemma-3-1b`, `qwen2.5-1.5b`, or `lfm2-1.2b` |
+
+When enabled, the gateway writes a private generated OMP overlay at `stateDir/omp-learning.json` and stores Mnemopi data under `stateDir/memory`. `online` uses OMP's configured TINY role, then its small online fallback. The other values select local on-device memory models. The active conversation model remains independently selectable through `omp.model` or `/model`.
+
+With `omp.inheritHarness: true`, each gateway start refreshes desktop `skills`, `rules`, `commands`, `agents`, `docs`, and `bin` into read-only snapshots inside the named gateway profile. Root policy and harness configuration files refresh atomically. Symlinked skill directories are materialized so the named profile never points back into the desktop profile. Secret and volatile paths such as `.env*`, dependency directories, virtual environments, logs, caches, and browser profiles are excluded.
+
+OMP-managed skill creation and refinement write to the gateway profile's separate `managed-skills` directory. Gateway memory, managed skills, sessions, credentials, and databases stay isolated, while updated desktop harness content flows into the gateway on restart.
+
+### Telegram transport
+
+A Telegram object is required only when Telegram is configured:
+
+```json
+{
+  "enabled": true,
+  "account": "default",
+  "tokenEnv": "TELEGRAM_BOT_TOKEN"
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `enabled` | whether to start this adapter |
+| `account` | stable local account identifier used in identities and checkpoints |
+| `tokenEnv` | environment variable containing the bot token; it must be `TELEGRAM_BOT_TOKEN` |
+
+Authorizing a user is an explicit local database operation:
+
+```bash
+ompclaw telegram-allow <your-numeric-telegram-user-id> \
+  --config ~/.config/ompclaw/config.json
+```
+
+It creates or updates an `operator` principal and binds the exact Telegram identity for the configured account. To use a custom principal or roles, create it with `principal-add` and bind the Telegram identity with `identity-bind`.
+
+### WebSocket transport
+
+The following loopback configuration is the recommended starting point:
+
+```json
+{
+  "enabled": true,
+  "hostname": "127.0.0.1",
+  "port": 8787,
+  "account": "local",
+  "credentials": [
+    {
+      "tokenEnv": "OMPCLAW_WS_TOKEN",
+      "subject": "local-operator",
+      "channel": "local"
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `enabled` | whether to start the WebSocket server |
+| `hostname` | server bind hostname; use `127.0.0.1` by default |
+| `port` | integer from 0 to 65535; `0` lets Bun choose a port |
+| `account` | stable local account identifier |
+| `credentials` | non-empty list of credential metadata |
+| `credentials[].tokenEnv` | environment variable holding the token; use an `OMPCLAW_...` name |
+| `credentials[].subject` | stable identity subject derived after authentication |
+| `credentials[].channel` | stable delivery channel derived after authentication |
+| `credentials[].thread` | optional stable delivery thread derived after authentication |
+
+Credential metadata is configuration, not client input. Tokens are compared by hash. Each configured token and conversation origin must be unique, and one live connection is allowed for an origin. Bind each credential identity before clients can use it:
+
+```bash
+ompclaw principal-add local-operator \
+  --config ~/.config/ompclaw/config.json
+ompclaw identity-bind websocket local local-operator local-operator \
+  --config ~/.config/ompclaw/config.json
+```
+
+## Secret environment file
+
+Create the environment file outside the repository and make it mode `0600`:
+
+```bash
+cat > ~/.config/ompclaw/ompclaw.env <<'ENV'
+TELEGRAM_BOT_TOKEN=replace-with-telegram-bot-token
+OMPCLAW_WS_TOKEN=replace-with-a-long-random-websocket-token
+ENV
+chmod 600 ~/.config/ompclaw/ompclaw.env
+```
+
+The loader accepts literal `KEY=VALUE` lines, optional `export ` prefixes, comments, and quoted values. Existing process variables take precedence over values in the file. On Unix-like systems it refuses an environment file that is a symlink, not a regular file, not owned by the current user, or readable by group or others.
+
+Before launching OMP, the gateway removes Telegram and gateway transport secret variables from the OMP child environment. Do not rely on that filtering as a reason to store credentials in project files or OMP configuration.
+
+## Start, validate, and service operation
+
+Use `doctor` before the first start and whenever credentials or OMP configuration change:
+
+```bash
+ompclaw doctor \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+`doctor` resolves all enabled transport secrets, opens the SQLite store, verifies Telegram's bot identity and the absence of a webhook when Telegram is enabled, starts a short OMP RPC child, requests session state, then stops that child. A successful run ends with `Doctor: ready`.
+
+Run in the foreground during setup:
+
+```bash
+ompclaw run \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+The process stops cleanly on `SIGINT` or `SIGTERM`. It starts the OMP session first, then the adapters.
+
+For a persistent user service:
+
+```bash
+ompclaw service-install \
+  --config ~/.config/ompclaw/config.json \
+  --env-file ~/.config/ompclaw/ompclaw.env
+```
+
+The installer requires both `--config` and `--env-file` as absolute regular-file paths, requires the environment file to be exactly mode `0600`, verifies that configured secrets resolve, and reports its manager and installed path. It uses launchd label `com.ompclaw` on macOS and user systemd unit `ompclaw.service` on Linux. The environment file is referenced by the service command rather than copied into the service definition.
+
+Remove a user service with:
+
+```bash
+ompclaw service-uninstall \
+  --config ~/.config/ompclaw/config.json
+```
+
+The command reports the stopped and removed service path. Stop the service before making manual database backups or state-directory copies.
+
+### Health and logs
+
+The WebSocket adapter exposes exactly one HTTP response:
+
+```text
+GET /healthz -> 200 {"status":"ok"}
+```
+
+It is a liveness endpoint, not an authenticated API, metrics endpoint, command endpoint, or reverse-proxy control plane. Unknown HTTP paths return `404`. The WebSocket upgrade is `GET /` with the WebSocket upgrade header.
+
+Use service-manager logs and foreground stderr for gateway and OMP failures. Do not include environment file content, session exports, inbox attachment paths, or database rows in a public report.
+
+## Crash recovery and exact-session resume
+
+After an OMP state update and after each successful inbound turn, the gateway records OMP's current `sessionFile` in the `omp/session_file` checkpoint. On the next gateway start it resumes that exact path first. If no checkpoint exists, it uses `omp.resume` when configured. `/switch <exact session path>` asks OMP to switch to the exact path supplied by the operator.
+
+If the OMP child exits unexpectedly and `omp.autoRestart` is true, the gateway notifies the active delivery context and retries startup with delays of 1, 2, 5, 10, then 30 seconds. `autoRestart: false` leaves the gateway offline after the exit.
+
+The checkpoint allows a restarted gateway to resume a completed OMP session. It does not resume a partly executed prompt, an in-flight tool call, a transport connection, or a pending user interaction. Send a new message after recovery when the interrupted result matters.
+
+## Migration from omp-gateway 0.2.x
+
+The OmpClaw rename changes the package, CLI, service identifiers, default profile and state paths, environment prefix, database filenames, and OMP host-tool names. There are no legacy aliases.
+
+1. Stop the old service while the `omp-gateway` command is still installed:
+
+   ```bash
+   omp-gateway service-uninstall \
+     --config ~/.config/omp-gateway/config.json
+   ```
+
+2. Move `~/.config/omp-gateway` to `~/.config/ompclaw` and `~/.omp/agent/gateway` to `~/.omp/agent/ompclaw`.
+3. In the stopped state directory, rename `gateway.sqlite` to `ompclaw.sqlite` and any matching `gateway.sqlite-wal` or `gateway.sqlite-shm` sidecars to the same `ompclaw.sqlite-*` suffixes. Rename `gateway.lock` to `ompclaw.lock` if it remains after the clean stop.
+4. Update the JSON config to use the new state directory. Change `profile` from `gateway` to `ompclaw` only when the old config used the default; keep an explicitly configured custom profile unchanged. Rename `OMP_GATEWAY_*` environment variable names to `OMPCLAW_*`, and rename the environment file if desired.
+5. Install `ompclaw`, run `doctor`, then install the new `com.ompclaw` or `ompclaw.service` user service.
+
+The SQLite schema and stored conversation, principal, scheduler, inbox, and checkpoint records are unchanged. OMP sees the renamed host tools only after the new process starts.
+
+## Migration from standalone omp-telegram RPC state
+
+Migration is for state created by the old standalone `omp-telegram` RPC service. It is not an extension activation step and it does not reuse legacy pairing commands.
+
+1. Stop the old standalone service so only one Telegram poller owns the bot token.
+2. Create the new token-free gateway JSON and private environment file.
+3. Locate the old standalone access-state JSON and RPC-state JSON. Keep backups outside source control.
+4. Run the idempotent importer:
+
+   ```bash
+   ompclaw migrate-telegram <legacy-access-state.json> <legacy-rpc-state.json> \
+     --config ~/.config/ompclaw/config.json
+   ```
+
+5. Run `telegram-allow` if you want to establish or replace the Telegram operator binding explicitly, then run `doctor` and start the gateway.
+
+The importer reads only the two named JSON state files. It does not read or copy an old token environment file. In one SQLite transaction, it imports the legacy Telegram operator as an `operator` principal, binds its default Telegram identity, records the exact OMP session path for its conversation, and imports the Telegram update checkpoint when present. A migration marker makes subsequent invocations report that the state was already migrated.
+
+## Transport behavior
+
+### Telegram
+
+Telegram uses long polling, per-account update checkpointing, and a per-account polling lock. It ignores replayed or already completed updates and advances the durable checkpoint only across the completed update prefix. A failed earlier update is not skipped by a later successful one.
+
+Private chats and forum topics map to stable gateway conversation addresses. Incoming Telegram identity comes from the sender ID. Normal inbound content can include text, captions, reply metadata, supported media as private inbox files, and optional voice transcription when configured by the adapter. Images are passed to OMP as image input when readable; other attachment references are retained in the transport-message prompt.
+
+Telegram supports assistant message creation and editing, reactions, attachments, threads, confirmation buttons, single and multi-select buttons, reply-based text/editor input, notifications, URL buttons, and rendered status surfaces. Interaction responses are bound to the original address and authorized principal. An expired, moved, or cross-user control is rejected.
+
+### WebSocket
+
+WebSocket is a versioned, authenticated transport. Connect to the configured endpoint, send an `authenticate` frame first, wait for `ready`, then send messages or UI responses. The server derives identity, account, channel, and optional thread from the credential configuration. A client cannot set those fields.
+
+The server accepts a connection at `GET /` only after HTTP WebSocket upgrade. It requires authentication within 10 seconds by default. Invalid, missing, duplicate, or unbound credentials are rejected and the socket closes with a policy error. See the full frame contract in the [RPC and transport reference](rpc-service.md#websocket-protocol-v1).
+
+## Operational limitations
+
+- One gateway process owns one OMP session, one scheduler, and one SQLite writer. This is not a worker pool or a distributed multi-writer system.
+- Interactive and scheduled work serialize through the same OMP runtime. A due job waits while another turn is active. A different interactive conversation receives a busy response while another turn is active.
+- Job dispatch is at least once across gateway or host crashes. External side effects require idempotent prompts or downstream deduplication.
+- In-flight OMP work is not resumable after a process or child crash. Completed session and scheduled-job state remain durable.
+- One Telegram bot token has one long poller. Do not run multiple pollers or mix long polling with a Telegram webhook.
+- WebSocket delivery requires the authenticated client for the exact configured origin to remain connected. The gateway does not queue delivery for a disconnected WebSocket client.
+- HTTP is health-only. There is no HTTP prompt, scheduler, database, or unauthenticated transport API.
+- Experimental auto-capture uses extra provider tokens and can create or refine gateway-profile managed skills. Review that profile before relying on learned behavior for consequential automation.
+
+## Further reference
+
+- [README quickstart](../README.md)
+- [RPC and transport reference](rpc-service.md)
+- [Security policy](../SECURITY.md)
+- [Upstream attribution](../NOTICE)

package/docs/rpc-service.md

@@ -0,0 +1,240 @@
+# RPC and transport reference
+
+[Back to the operator guide](guide.md) · [Back to the README](../README.md)
+
+`ompclaw` presents one persistent OMP RPC session through authenticated transport adapters. It is not an HTTP RPC server. HTTP is limited to the WebSocket adapter's health endpoint. The OMP child uses its RPC UI mode; Telegram and WebSocket clients receive the gateway-level behavior described here.
+
+## Session and delivery model
+
+The runtime starts one OMP child with `--mode rpc-ui`, the configured workspace and profile, and a persisted session path when one exists. It subscribes to OMP subagent progress, registers the gateway host tools, and asks OMP for session state.
+
+An inbound message or scheduled job establishes an active delivery context containing the authenticated principal and the exact transport address. Streamed updates, final assistant text, OMP UI, command output, host-tool delivery, and unexpected-exit notifications go only to that context. A message from a different authenticated conversation during an active turn receives a busy response. It does not join the active turn or receive its output. Due scheduled work defers while the runtime is busy.
+
+Assistant updates are lossless and ordered at the gateway boundary. A first visible assistant update creates an outbound message; later visible updates edit that same receipt when the transport supports it. A terminal OMP response delivers the final visible assistant text and clears the active delivery context. Thinking and tool-call blocks are not forwarded as assistant text.
+
+## Gateway command matrix
+
+Send these commands as a slash command in an authenticated conversation. Any other available OMP slash command is forwarded to the OMP session. Commands that take an argument show their usage when the argument is absent or invalid.
+
+| Command | OMP action and gateway result |
+| --- | --- |
+| `/status` | refresh and report OMP streaming or compaction state, exact session name or ID, model, thinking, fast mode, message and queue counts, context usage, current tool, tracked subagents, UI display state, and last error |
+| `/stop` | send OMP `abort` for the current run |
+| `/new` | request an OMP `new_session` and clear the active delivery context when complete |
+| `/steer <message>` | send OMP `steer` with a correction |
+| `/followup <message>` | send OMP `follow_up` to queue work after the current turn |
+| `/compact [instructions]` | compact OMP context, optionally with custom instructions, then refresh state |
+| `/model` | list current and available `provider/model-id` values |
+| `/model <provider>/<model-id>` | send OMP `set_model` and refresh state |
+| `/thinking` | show the current reasoning level and accepted levels |
+| `/thinking <inherit|off|minimal|low|medium|high|xhigh|max|auto>` | send OMP `set_thinking_level` and refresh state |
+| `/fast [on|off]` | show or set OMP fast mode |
+| `/queue` | show OMP steering, follow-up, and interrupt policy |
+| `/queue steering <all|one-at-a-time>` | set OMP steering policy |
+| `/queue follow <all|one-at-a-time>` | set OMP follow-up policy |
+| `/queue interrupt <immediate|wait>` | set OMP interrupt policy |
+| `/stats` | request OMP session statistics |
+| `/todos` | show the current OMP todo phases from session state |
+| `/subagents` | request and show active or recent OMP subagents |
+| `/commands` | request and show available OMP slash commands |
+| `/history [1-50]` | request messages and show the requested recent visible summaries; default is 12 |
+| `/branch` | list recent OMP branch points |
+| `/branch <entry-id>` | ask OMP to branch from the exact entry ID |
+| `/name <session name>` | set the OMP session name and refresh state |
+| `/handoff [instructions]` | hand context to a fresh OMP session and refresh state |
+| `/switch <exact session path>` | ask OMP to switch to the exact session path and refresh state |
+| `/export` | request an OMP HTML export, store it under `stateDir/exports`, and attach it to the active conversation |
+| `/retry <on|off|stop>` | enable or disable automatic retry, or send OMP `abort_retry` |
+| `/autocompact [on|off]` | show or set automatic compaction |
+| `/login` | show provider login availability and authentication state |
+| `/login <provider-id>` | start OMP provider login and route its secure URL prompt to the active delivery context |
+| `/jobs` | list durable scheduled jobs owned by the active principal |
+| `/job_pause <id>` | disable an owned scheduled job |
+| `/job_resume <id>` | enable an owned scheduled job and recompute its next occurrence |
+| `/job_run <id>` | make an owned scheduled job due immediately |
+| `/job_delete <id>` | permanently delete an owned scheduled job |
+| `/help` | show the gateway command summary |
+| `/shell <command>` | execute OMP RPC bash only when `omp.allowRpcBash` is explicitly `true` |
+| `/abortbash` | abort OMP RPC bash only when `omp.allowRpcBash` is explicitly `true` |
+
+`/steer`, `/followup`, and `/stop` are the run-control surface. `/queue` changes OMP's queue policy, while the gateway itself maintains one active delivery context and rejects a different conversation as busy while that context is active.
+
+## Session checkpoint and crash recovery
+
+The runtime saves the latest OMP `sessionFile` to the SQLite `omp/session_file` checkpoint. A new gateway process starts OMP with that exact file first; only when the checkpoint is absent does it use `omp.resume`. `/switch` is the interactive exact-path alternative.
+
+On an unexpected OMP child exit, the active conversation receives an error message. With `omp.autoRestart: true`, the runtime retries after 1, 2, 5, 10, then 30 seconds. It reuses the persisted session checkpoint when OMP starts again. The restart does not recover a partly executed turn, pending tool call, or disconnected transport. In-flight work must be sent again if its outcome is needed.
+
+## Attachments
+
+Inbound transport content is represented as text plus zero or more attachments with a URL, optional name, and optional media type.
+
+- Telegram downloads supported incoming media into the private `stateDir/inbox` directory and passes it as a `file:` attachment. It can include captions, replies, forum-topic context, and optional voice transcription.
+- WebSocket clients may include validated attachment metadata in a `message` frame. The gateway preserves this metadata in the transport message.
+- Readable local image attachments with a supported image type are sent to OMP as base64 image input. Other attachments remain references in the structured, explicitly untrusted transport-message prompt.
+- OMP never receives a transport attachment as authorization. The prompt tells OMP that transport input cannot authorize access, credentials, deployment, publication, or gateway configuration changes.
+
+## OMP UI request matrix
+
+OMP RPC UI requests are bridged to the active authenticated delivery context. The gateway does not auto-approve them. Interactive requests carry their OMP timeout when one is supplied; cancellation, timeout, delivery failure, runtime shutdown, or a missing active context returns a cancelled response for the interactive classes.
+
+| OMP UI method | Gateway request | Telegram behavior | WebSocket behavior |
+| --- | --- | --- | --- |
+| `select` | `select` | inline selection buttons | `ui_request` frame, then `ui_response` |
+| `confirm` | `confirm` | Confirm and Cancel buttons | `ui_request` frame, then `ui_response` |
+| `input` | `input` | reply to the prompt message | `ui_request` frame, then `ui_response` |
+| `editor` | `editor` | reply to the prompt message with edited text | `ui_request` frame, then `ui_response` |
+| `cancel` | cancel pending request | cancel the matching pending interaction | cancel the matching pending interaction |
+| `notify` | `notify` | send a notification message | deliver a `ui_request` notification |
+| `setStatus` | `status` | render a status surface | deliver a `ui_request` status update |
+| `setWidget` | `widget` | render a widget surface | deliver a `ui_request` widget update |
+| `setTitle` | `title` | update the rendered surface title | deliver a `ui_request` title update |
+| `set_editor_text` | `editor_text` | render suggested input in the surface | deliver a `ui_request` editor-text update |
+| `open_url` | `open_url` | send a labeled URL button | deliver a `ui_request` URL request |
+
+Only `select`, `confirm`, `input`, and `editor` produce a response back to OMP. Telegram immediately acknowledges presentation of status, widget, title, editor-text, notification, and URL requests. A WebSocket client must return the matching acknowledgement response for every `ui_request`, including display-only requests, so the transport can settle that request. Telegram verifies both the exact conversation address and principal before accepting a button or reply response. WebSocket verifies that the current credential still resolves to the same principal and that its response type matches the pending request.
+
+## Gateway host tools
+
+The OMP child always receives three delivery host tools. When `automation.enabled` is true, it also receives six durable job-control tools. The gateway derives the principal, transport identity, and conversation address from the active server-owned context. A model cannot choose or override them.
+
+| Tool | Parameters | Behavior |
+| --- | --- | --- |
+| `ompclaw_send` | `text` and/or `files` | send text and optional absolute local file paths to the active conversation; at least one is required |
+| `ompclaw_ask` | `question`, optional `title`, `options`, and `multi` | ask the operator a free-text, single-select, or multi-select question in the active conversation |
+| `ompclaw_react` | `message_id`, `emoji` | react to a message in the active conversation |
+| `ompclaw_schedule_job` | `name`, `prompt`, exactly one of `at` or `cron`, optional `timezone` | create an owned one-shot or recurring job bound to the active conversation |
+| `ompclaw_update_job` | `id`, optional mutable job fields | update an owned job and recompute its next occurrence |
+| `ompclaw_list_jobs` | none | list the active principal's jobs |
+| `ompclaw_set_job_enabled` | `id`, `enabled` | pause or resume an owned job |
+| `ompclaw_delete_job` | `id` | permanently remove an owned job |
+| `ompclaw_run_job` | `id` | make an owned job due now |
+
+`ompclaw_send` accepts only absolute local paths for `files`. Transport adapters enforce their own attachment and message rules. `ompclaw_ask` without `options` uses text input; with options it uses selection, and `multi: true` requests multi-select. Host-tool cancellation aborts the in-progress gateway delivery operation.
+
+One-shot `at` values must be ISO 8601 date-times with an explicit UTC offset. Cron timezones must be valid IANA names. Names, prompts, expressions, and retry state are bounded and validated before SQLite mutation. Job lookup and mutation always include the server-derived principal ID.
+
+## WebSocket protocol v1
+
+The WebSocket protocol version is `1`. It is separate from the OMP child RPC protocol. After authentication the server sends `ready` with `protocolVersion: 1`; clients should treat that value as the protocol they are speaking. The current client frames do not include a version field or negotiate versions.
+
+The OMP child protocol starts at v1 and negotiates v2 when OMP advertises v2 support. This supports lossless chunk reassembly for OMP RPC frames. `doctor` reports the protocol selected for the OMP child; this does not change the WebSocket protocol number.
+
+### Connection sequence
+
+1. Connect to `ws://127.0.0.1:8787/` or the configured local endpoint.
+2. Send exactly one `authenticate` frame within 10 seconds by default.
+3. Wait for `ready` with protocol version `1`.
+4. Send `message` frames or answer `ui_request` frames with `ui_response`.
+5. Handle `message`, `update`, `reaction`, `ui_request`, and `error` frames from the server.
+
+Use a TLS and access-controlled boundary before making a WebSocket endpoint reachable beyond loopback. The token is a bearer credential. Replace every value shown below with an actual client-specific value outside source control.
+
+### Client frames
+
+```json
+{ "type": "authenticate", "token": "replace-with-websocket-token" }
+```
+
+```json
+{
+  "type": "message",
+  "id": "client-message-id",
+  "text": "Inspect the current session",
+  "attachments": [
+    {
+      "url": "https://example.invalid/attachment.txt",
+      "name": "attachment.txt",
+      "mediaType": "text/plain"
+    }
+  ]
+}
+```
+
+```json
+{
+  "type": "ui_response",
+  "requestId": "server-request-id",
+  "response": {
+    "type": "confirm",
+    "confirmed": true
+  }
+}
+```
+
+The exact `response` shape must match the request type. `select` returns selected values, `input` and `editor` return either cancellation or a string value, and display-only UI request types return an acknowledgement response. Send a matching `ui_response` for every WebSocket `ui_request`.
+
+Client frames are exact schemas. A message cannot supply a principal, account, channel, thread, timestamp, or delivery address. The server derives all of those values from the authenticated configured credential. Message IDs are scoped by the derived origin, and timestamps use server time.
+
+### Server frames
+
+```json
+{ "type": "ready", "protocolVersion": 1 }
+```
+
+```json
+{
+  "type": "message",
+  "messageId": "gateway-message-id",
+  "content": { "text": "Initial assistant text", "format": "text" }
+}
+```
+
+```json
+{
+  "type": "update",
+  "messageId": "gateway-message-id",
+  "content": { "text": "Updated assistant text", "format": "text" }
+}
+```
+
+```json
+{ "type": "reaction", "messageId": "gateway-message-id", "emoji": "replace-with-an-emoji" }
+```
+
+```json
+{
+  "type": "ui_request",
+  "requestId": "server-request-id",
+  "request": { "type": "confirm", "title": "Continue", "message": "Proceed with the requested action?" }
+}
+```
+
+```json
+{ "type": "error", "code": "unauthorized", "message": "authentication failed" }
+```
+
+The server accepts only the health endpoint over ordinary HTTP:
+
+```text
+GET /healthz -> 200 {"status":"ok"}
+```
+
+All other ordinary HTTP routes return `404`. The WebSocket upgrade route is `GET /` with the upgrade header.
+
+### Authentication and connection boundaries
+
+The server hashes configured credential tokens and uses a timing-safe comparison. A valid token is necessary but not sufficient: its configured identity must resolve to a principal in SQLite. A second connection for the same configured origin is rejected. Credentials with duplicate tokens or duplicate configured origins are rejected at startup.
+
+Before authentication, malformed frames, non-authenticate frames, a timeout, or bad credentials produce an error when possible and close the connection with a policy error. After authentication, unknown UI request IDs, principal mismatches, response-type mismatches, and rejected inbound messages produce error frames. Delivery fails when the exact authenticated origin disconnects; the gateway does not retain a WebSocket outbound queue.
+
+## Telegram transport reference
+
+Telegram is long-poll only. `doctor` calls `getWebhookInfo` and rejects a non-empty webhook URL because Telegram cannot use the same bot for both webhook delivery and long polling.
+
+The adapter persists each completed update ID under an account-specific checkpoint. It processes duplicate or replayed updates at most once and only moves the checkpoint across a contiguous completed prefix. The adapter lock prevents a second poller for the same account in the same state directory.
+
+Telegram outbound delivery supports text messages and edits, reactions, uploads, forum threads, and native message segmentation. UI presentations use inline buttons for confirmation and selection, reply-to-message for free-text input and editor input, URL buttons for URL requests, and rendered surfaces for status-like requests. Pending interaction ownership is checked again when the user responds.
+
+## Security boundary summary
+
+- Principal identity is resolved locally from transport identity before OMP receives a message.
+- The active delivery context scopes every outbound reply, UI presentation, host tool, and reaction.
+- JSON configuration names secret variables but does not contain their values. Private environment files are required for token loading.
+- Gateway transport secrets are removed from the OMP child environment.
+- One state directory has one gateway writer. One Telegram bot token has one poller.
+- An authorized transport principal has the authority of the configured OMP workspace and profile. See the [security policy](../SECURITY.md) before binding an identity or exposing a WebSocket endpoint.
+
+## Limits
+
+The gateway does not distribute turns across writers, create one OMP session per client, resume an in-flight OMP turn, or offer a general HTTP API. Durable jobs run through the same single OMP session with at-least-once dispatch and bounded retry. WebSocket state is live only, scheduled WebSocket delivery requires the originating client to be connected, and Telegram is limited to one long-polling owner for a bot token.