@relay-harness/coding-agent 0.0.0-stage → 1.0.3

package/docs/json.md

@@ -0,0 +1,226 @@
+# JSON Event Stream
+
+JSON mode emits structured progress for one invocation:
+
+```bash
+relay --mode json "Review this repository"
+```
+
+Relay writes one session header followed by session events, then exits after the supplied prompts finish. RPC mode emits the same session-event shapes but has no session header because it is a bidirectional, long-lived protocol. See [RPC Mode](rpc.md).
+
+This page is the canonical reference for events shared by JSON and RPC mode. Message values use the [shared message types](message-types.md).
+
+## Framing and process I/O
+
+The stream uses strict JSONL framing. Each record is one JSON object terminated by LF (`\n`). Split records only on LF and strip an optional preceding carriage return. Unicode line and paragraph separators are valid inside JSON strings and are not record boundaries.
+
+Node.js `readline` is not suitable for this stream because it also recognizes those Unicode separators. Use a byte or UTF-8 stream decoder and split on LF.
+
+Read stdout continuously. A reader that stops consuming records can stall Relay when the pipe buffer fills. Stdout is reserved for JSONL; diagnostics and application logging go to stderr.
+
+## Session header
+
+The first JSON-mode record is the current [session header](session-format.md#sessionheader):
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path"}
+```
+
+RPC mode does not emit this record. Use [`get_state`](rpc-commands.md#get_state) for its current session ID and file.
+
+## Event sequence
+
+A basic run produces records like these:
+
+```json
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
+{"type":"message_end","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
+{"type":"message_start","message":{"role":"assistant","content":[],"stopReason":"pending","...":"..."}}
+{"type":"message_update","usage":{"...":"..."},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_end","message":{"role":"assistant","...":"..."}}
+{"type":"turn_end","message":{"role":"assistant","...":"..."},"toolResults":[]}
+{"type":"agent_end","messages":[{"...":"..."}],"willRetry":false}
+{"type":"agent_settled"}
+```
+
+`agent_end` closes one low-level agent run. Automatic retry, overflow recovery, compaction retry, steering, or follow-up work can still continue. `agent_settled` means Relay has no remaining automatic work for that session-level run.
+
+## Agent and turn events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `agent_start` | None | A low-level agent run started. |
+| `agent_end` | `messages`, `willRetry` | That low-level run ended. `messages` contains messages generated by the run. |
+| `agent_settled` | None | Relay will not continue automatically through retries, compaction recovery, or queued messages. |
+| `turn_start` | None | One assistant turn started. |
+| `turn_end` | `message`, `toolResults` | One assistant response and its resulting tool calls finished. |
+
+A turn is one assistant response plus any tool calls and tool results produced by that response.
+
+## Message events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `message_start` | `message` | A message started. |
+| `message_update` | `usage`, `assistantMessageEvent` | An assistant message emitted a content-block update. |
+| `message_end` | `message` | A message completed. This is the authoritative final message. |
+
+### Reconstruct streaming messages
+
+Wire `message_update` records are delta-only. They omit the SDK event's cumulative `message` field and every `assistantMessageEvent.partial` snapshot so stream size remains linear.
+
+The nested event is one of:
+
+| Type | Fields in addition to `type` | Meaning |
+|---|---|---|
+| `start` | None | The provider stream started; its cumulative `partial` field is removed on the wire. |
+| `text_start` | `contentIndex` | A text block started. |
+| `text_delta` | `contentIndex`, `delta` | Append text to the block. |
+| `text_end` | `contentIndex`, `content` | The text block ended with authoritative content. |
+| `thinking_start` | `contentIndex` | A thinking block started. |
+| `thinking_delta` | `contentIndex`, `delta` | Append thinking text to the block. |
+| `thinking_end` | `contentIndex`, `content` | The thinking block ended with authoritative content. |
+| `toolcall_start` | `contentIndex`, `id`, `toolName` | A tool-call block started. |
+| `toolcall_delta` | `contentIndex`, `delta` | Append serialized argument data. |
+| `toolcall_end` | `contentIndex`, `toolCall` | The tool call ended with the complete `ToolCall`. |
+| `done` | `reason`, `message` | The provider stream completed successfully. |
+| `error` | `reason`, `error` | The provider stream ended with an error or abort message. |
+
+The normal agent loop translates provider-level `start`, `done`, and `error` into `message_start` and `message_end` session events rather than emitting them as `message_update`. They remain admitted by the exported `JsonAgentSessionEvent` transformation for callers that construct a matching session event.
+
+Use `contentIndex` to identify the content block. Buffer `delta` fields for a live display, but replace reconstructed data with the completed content in `text_end`, `thinking_end`, or `toolcall_end`. Replace the whole partial message with `message_end.message` when it arrives.
+
+The top-level `usage` is the latest cumulative provider-reported usage for the assistant response. It can remain zero until completion when a provider does not report usage while streaming.
+
+```json
+{"type":"message_update","usage":{"input":100,"output":1,"cacheRead":0,"cacheWrite":0,"totalTokens":101,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello "}}
+```
+
+## Tool execution events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `tool_execution_start` | `toolCallId`, `toolName`, `args` | Tool execution started. |
+| `tool_execution_update` | `toolCallId`, `toolName`, `args`, `partialResult` | The tool reported a partial result. |
+| `tool_execution_end` | `toolCallId`, `toolName`, `result`, `isError` | Tool execution finished. |
+
+Use `toolCallId` to correlate the lifecycle. `partialResult` is the latest partial result supplied by the tool. Whether it replaces or extends an earlier update depends on that tool's result contract.
+
+```json
+{"type":"tool_execution_start","toolCallId":"call_abc123","toolName":"bash","args":{"command":"ls -la"}}
+{"type":"tool_execution_update","toolCallId":"call_abc123","toolName":"bash","args":{"command":"ls -la"},"partialResult":{"content":[{"type":"text","text":"partial output"}],"details":{}}}
+{"type":"tool_execution_end","toolCallId":"call_abc123","toolName":"bash","result":{"content":[{"type":"text","text":"complete output"}],"details":{}},"isError":false}
+```
+
+## Queue and state events
+
+| Event | Fields | Meaning |
+|---|---|---|
+| `queue_update` | `steering`, `followUp` | The pending steering or follow-up queue changed. Both fields contain the complete current queue. |
+| `entry_appended` | `entry` | An extension appended a custom session entry through `relay.appendEntry()`. |
+| `session_info_changed` | `name` | The session display name changed. An absent `name` means it was cleared. |
+| `thinking_level_changed` | `level` | The active thinking level changed. |
+
+The `entry` value uses a persisted [session entry type](session-format.md#entry-types).
+
+## Compaction events
+
+`compaction_start` reports why compaction began:
+
+```json
+{"type":"compaction_start","reason":"threshold"}
+```
+
+`reason` is `"manual"`, `"threshold"`, or `"overflow"`.
+
+`compaction_end` contains the result when compaction succeeds:
+
+```json
+{
+  "type": "compaction_end",
+  "reason": "threshold",
+  "result": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
+    "tokensBefore": 150000,
+    "estimatedTokensAfter": 32000,
+    "usage": {"...": "..."},
+    "details": {}
+  },
+  "aborted": false,
+  "willRetry": false
+}
+```
+
+If compaction was aborted, `result` is absent and `aborted` is true. If it failed, `result` is absent, `aborted` is false, and `errorMessage` describes the failure. Successful overflow recovery sets `willRetry` to true before Relay retries the prompt.
+
+See [Compaction and Branch Summaries](compaction.md) for result semantics.
+
+## Retry events
+
+Assistant-turn retry emits:
+
+```json
+{"type":"auto_retry_start","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"529 overloaded"}
+{"type":"auto_retry_end","success":true,"attempt":2}
+```
+
+On final failure, `auto_retry_end` has `success: false` and a `finalError` string.
+
+Compaction and branch-summary retry emit:
+
+```json
+{"type":"summarization_retry_scheduled","attempt":1,"maxAttempts":3,"delayMs":2000,"errorMessage":"terminated"}
+{"type":"summarization_retry_attempt_start","source":"compaction","reason":"threshold"}
+{"type":"summarization_retry_finished"}
+```
+
+For a branch summary, `source` is `"branchSummary"` and `reason` is absent. The `reason` on a compaction retry is `"manual"`, `"threshold"`, or `"overflow"`.
+
+## RPC-only events
+
+A direct RPC [`bash`](rpc-commands.md#bash) command emits one `bash_execution_update` for each output chunk. Its optional `id` matches the command ID. The final command response can contain truncated output, but these events stream all output:
+
+```json
+{"type":"bash_execution_update","id":"req-1","delta":"total 48\n"}
+```
+
+RPC also adds `extension_error` when an extension handler throws:
+
+```json
+{"type":"extension_error","extensionPath":"/path/to/extension.ts","event":"tool_call","error":"Error message"}
+```
+
+Extension UI records are a separate RPC subprotocol, not `AgentSessionEvent` values. See [RPC Extension UI](rpc-extension-ui.md).
+
+## TypeScript types
+
+The SDK's `AgentSessionEvent` contains cumulative streaming snapshots for in-process consumers. JSON and RPC transform only `message_update`:
+
+```typescript
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+
+type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
+  ? WithoutPartial<T> & { id: string; toolName: string }
+  : WithoutPartial<T>;
+
+type JsonAgentSessionEvent =
+  | Exclude<AgentSessionEvent, { type: "message_update" }>
+  | {
+      type: "message_update";
+      usage: Usage;
+      assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
+    };
+```
+
+Use the exported `JsonAgentSessionEvent` type from `@relay-harness/coding-agent`. Its implementation is in [`json-event.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/modes/json-event.ts).
+
+## Example
+
+Print completed messages from a one-shot run:
+
+```bash
+relay --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```

package/docs/keybindings.md

@@ -0,0 +1,194 @@
+# Keybindings Reference
+
+Relay exposes named actions, such as `app.session.new`, that can be assigned keybindings. You can change default assignments or bind unassigned actions in Relay's [user configuration](configuration.md#agent-directory).
+
+Run `/hotkeys` to see the active shortcuts for the main editor and application.
+
+## Assign keybindings
+
+Create `<agent-dir>/keybindings.json`. The agent directory defaults to `~/.relay/agent` and is described in [Agent directory](configuration.md#agent-directory).
+
+Map each action identifier to one key or a list of keys:
+
+```json
+{
+  "app.session.new": "ctrl+shift+n",
+  "app.session.tree": ["ctrl+shift+t", "alt+shift+t"]
+}
+```
+
+A configured value replaces the default for that action. Use an empty list to disable an action's keybindings:
+
+```json
+{
+  "tui.altScreen.pageUp": []
+}
+```
+
+After editing the file, run `/reload` to apply the changes to the active session.
+
+## Key syntax
+
+Write a key as `modifier+key`. Modifiers are `ctrl`, `shift`, `alt`, and `super`. You can combine modifiers. Valid keys are:
+
+- **Letters:** `a-z`
+- **Digits:** `0-9`
+- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
+- **Function:** `f1`-`f12`
+- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
+
+Examples: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, and `ctrl+1`.
+
+`super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
+
+## Actions
+
+### Terminal UI
+
+#### Cursor movement
+
+| Keybinding id | Default | Description |
+|---|---|---|
+| `tui.editor.cursorUp` | `up` | Move cursor up, browsing older history at the top |
+| `tui.editor.cursorDown` | `down` | Move cursor down, browsing newer history at the bottom |
+| `tui.editor.historyPrevious` | None | Select the previous prompt history entry |
+| `tui.editor.historyNext` | None | Select the next prompt history entry |
+| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
+| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
+| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
+| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+home`, `ctrl+a` | Move to line start |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+end`, `ctrl+e` | Move to line end |
+| `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
+| `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
+| `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
+| `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
+
+The dedicated history actions browse prompt history regardless of cursor position and take precedence over application actions using the same key.
+
+#### Text editing
+
+| Keybinding id | Default | Description |
+|---|---|---|
+| `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
+| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
+| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
+| `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
+| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
+| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
+| `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
+| `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
+| `tui.editor.undo` | `ctrl+-` (`ctrl+z` on Windows; `alt+z` on WSL) | Undo last edit |
+
+#### Input and selection
+
+| Keybinding id | Default | Description |
+|---|---|---|
+| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab or autocomplete |
+| `tui.input.copy` | `ctrl+c` | Copy selection |
+| `tui.select.up` | `up` | Move selection up |
+| `tui.select.down` | `down` | Move selection down |
+| `tui.select.pageUp` | `pageUp` | Page up in list |
+| `tui.select.pageDown` | `pageDown` | Page down in list |
+| `tui.select.confirm` | `enter` | Confirm selection |
+| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
+
+#### Fullscreen
+
+In fullscreen mode, these actions control the transcript and take precedence over editor actions using the same key.
+
+| Keybinding id | Default | Description |
+|---|---|---|
+| `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
+| `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
+| `tui.altScreen.halfPageUp` | None | Scroll the transcript up by half a page |
+| `tui.altScreen.halfPageDown` | None | Scroll the transcript down by half a page |
+| `tui.altScreen.lineUp` | None | Scroll the transcript up by one line |
+| `tui.altScreen.lineDown` | None | Scroll the transcript down by one line |
+| `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` only on Windows and WSL) | Jump to the previous marked message |
+| `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` only on Windows and WSL) | Jump to the next marked message |
+| `tui.altScreen.search` | `ctrl+shift+f` (`ctrl+f` on Windows and WSL) | Search the rendered transcript |
+| `tui.altScreen.searchNext` | `enter`, `ctrl+g` | Select the next search match while searching |
+| `tui.altScreen.searchPrevious` | `shift+enter`, `ctrl+shift+g` | Select the previous search match while searching |
+| `tui.altScreen.searchClose` | `escape` | Close transcript search |
+| `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
+| `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
+
+### Application
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.interrupt` | `escape` | Cancel / abort |
+| `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
+| `app.exit` | `ctrl+d` | Exit (when editor empty) |
+| `app.suspend` | `ctrl+z` (None on Windows) | Suspend to background |
+| `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
+| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows and WSL) | Paste files on macOS, images, or text from clipboard |
+
+On native Windows, `app.suspend` has no default because Windows terminals do not support Unix job control. If you assign it manually, Relay shows a status message instead of suspending. WSL uses the normal `ctrl+z` and `fg` behavior.
+
+### Sessions
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.session.new` | None | Start a new session (`/new`) |
+| `app.session.tree` | None | Open session tree navigator (`/tree`) |
+| `app.session.fork` | None | Fork current session (`/fork`) |
+| `app.session.resume` | None | Open session resume picker (`/resume`) |
+| `app.session.togglePath` | `ctrl+p` | Toggle path display |
+| `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
+| `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
+| `app.session.rename` | `ctrl+r` | Rename session |
+| `app.session.delete` | `ctrl+d` | Delete session |
+| `app.session.deleteNoninvasive` | `ctrl+backspace` | Delete session when query is empty |
+
+### Models and Thinking
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.model.select` | `ctrl+l` | Open model selector |
+| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
+| `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
+| `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
+| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
+| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
+
+### Display and Message Queue
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
+| `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; in fullscreen mode, copy the active selection when `fullscreenCopyOnSelect` is `false`; otherwise copy the last assistant message. On OAuth sign-in screens, copy the sign-in URL |
+| `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
+| `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |
+
+### Tree Navigation
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
+| `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
+| `app.tree.editLabel` | `shift+l` | Edit the label on the selected tree node |
+| `app.tree.toggleLabelTimestamp` | `shift+t` | Toggle label timestamps in the tree |
+| `app.tree.filter.default` | `ctrl+d` | Set tree filter to default view |
+| `app.tree.filter.noTools` | `ctrl+t` | Toggle tree filter that hides tool results |
+| `app.tree.filter.userOnly` | `ctrl+u` | Toggle tree filter that shows only user messages |
+| `app.tree.filter.labeledOnly` | `ctrl+l` | Toggle tree filter that shows only labeled entries |
+| `app.tree.filter.all` | `ctrl+a` | Toggle tree filter that shows all entries |
+| `app.tree.filter.cycleForward` | `ctrl+o` | Cycle tree filter forward |
+| `app.tree.filter.cycleBackward` | `shift+ctrl+o` | Cycle tree filter backward |
+
+### Scoped Models Selector
+
+Used inside the scoped models selector (opened via `/scoped-models`).
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
+| `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
+| `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
+| `app.models.reorderUp` | `alt+up` | Move the selected model up in the cycle order |
+| `app.models.reorderDown` | `alt+down` | Move the selected model down in the cycle order |

package/docs/laya.md

@@ -0,0 +1,152 @@
+# Adaptive Execution with Laya
+
+Relay normally runs every request on the model you selected. A typo fix then costs as much quota as a distributed-systems design. The `laya/auto` model instead picks the model, reasoning effort, role, skills, tools and validation for each request: the cheapest combination likely to succeed.
+
+```
+/model laya/auto
+```
+
+```
+"Corrija o texto deste botão"        -> fast tier,   claude-haiku-4-5  • minimal
+"Fix the race condition in workers"  -> strong tier, claude-opus-5-5   • high
+"Fix the login token expiry"         -> strong tier (rule: authentication) • medium, review required
+```
+
+## How a request is routed
+
+1. **Task intelligence (Laya).** [Laya](https://github.com/NandhaKishorM/laya) is a small local classifier, the fast "System 1". It answers 18 typed questions about the request in one call: task type, complexity, scope, risk, ambiguity, reasoning needed, recommended capability tier and effort, agent role, validation level, the tools needed, and whether the task is security-sensitive. Relay calls it through the same System One protocol it uses for TypeSafe classifiers. A request close to a task learned with `/laya learn` takes that task's answers instead ([memory](#teach-laya-from-your-sessions)).
+2. **Policy engine.** Deterministic rules set floors Laya cannot lower. Production database migrations, authentication, security vulnerabilities and payment processing require at least the `strong` tier, an effort of at least `medium`, and review. High risk also requires `strong`. An answer whose confidence is below `laya.minConfidence` raises the tier by one.
+3. **Model registry.** Tiers are abstract (`fast`, `balanced`, `strong`, `frontier`), so Laya never learns model names. The registry maps each tier to concrete models; only models whose provider has credentials are candidates.
+4. **Selection.** Each candidate gets a utility from the cost profile: `quality × P(success) − cost × quota cost − latency × latency − risk × failure risk`. `P(success)` starts from a prior (0.90 when the model's tier is the required tier, +0.04 per tier above, −0.18 per tier below) and moves toward the observed success rate of that model on that task class. The best candidate whose success estimate reaches the profile minimum wins.
+5. **Execution.** The routed model gets a short `[laya:plan]` message next to your request: the role to take, relevant skills, the tools expected, and how to validate. It is sent after your message, not in the system prompt, so the prompt cache stays valid.
+6. **Escalation.** After `laya.escalateAfterFailures` failed tool calls (or harness verification requests) in a turn, the task moves to the next tier. A rate-limit or overload error moves it to an equivalent model of another provider.
+7. **Telemetry.** Each request is recorded with its classification, selected model, outcome, tests and usage. The history feeds `P(success)` in later sessions.
+
+Reasoning effort follows Laya's recommendation up to `xhigh`. Routing never uses `max`. `laya/auto` has no thinking level of its own: a selected level would cap Laya's choice without you noticing. The footer shows the routed model and effort next to the selection, and the status line shows the task type and tier.
+
+When the Laya server is not running (Docker is missing or stopped, or the image is still downloading), keyword rules in English and Portuguese answer instead, and the status line shows `(rules)`. Laya is retried a minute later.
+
+## Cost profiles
+
+| Profile | Weights | Minimum success estimate |
+|---|---|---|
+| `economy` | cost 50%, quality 30%, latency 20% | 0.75 |
+| `balanced` (default) | quality 45%, cost 30%, latency 15%, risk 10% | 0.85 |
+| `quality` | quality 70%, risk 20%, cost 10% | 0.90 |
+| `critical` | quality 70%, risk 30% | 0.95 |
+
+Select one with `laya.policy`, `relay --laya-policy economy`, or `/laya policy quality` for the session.
+
+## Model registry
+
+| Tier | Default models, in preference order |
+|---|---|
+| `fast` | `anthropic/claude-haiku-4-5`, `openai-codex/gpt-6-luna`, `google/gemini-3.5-flash` |
+| `balanced` | `anthropic/claude-sonnet-5-5`, `openai-codex/gpt-5.6-terra`, `google/gemini-3.8-flash` |
+| `strong` | `anthropic/claude-opus-5-5`, `openai-codex/gpt-6-sol`, `google/gemini-3.1-pro-preview` |
+| `frontier` | `anthropic/claude-fable-5-1`, `openai-codex/gpt-6.1-sol` |
+
+Replace a tier with `laya.models`:
+
+```json
+{
+  "laya": {
+    "models": { "fast": ["openai-codex/gpt-6-luna"] },
+    "quota": { "anthropic": 0.8, "openai-codex": 0.25 }
+  }
+}
+```
+
+`laya.quota` states how much of each subscription is left. Scarce quota makes a provider's models more expensive in the utility, so an equivalent model of another provider wins.
+
+## Laya runs in Docker
+
+Relay itself runs on your machine; Laya and its Python run only in Docker. The npm package contains neither the trained model (650 MB) nor Python with torch. Both come in a Docker image, `ghcr.io/eltonssouza/relay-laya`, built by Relay's release from the same sources as the package:
+
+| Image | Used when | Size |
+|---|---|---|
+| `v1-cpu-<hash>` | No NVIDIA GPU | about 2 GB |
+| `v1-cuda-<hash>` | `nvidia-smi` finds an NVIDIA GPU; training uses it | about 6 GB |
+
+The image holds Python 3.11, `torch`, `laya[serve]`, the shipped model from the Hugging Face repository [eltonssouza/relay-laya](https://huggingface.co/eltonssouza/relay-laya) (pinned to one commit, every file checked against the sha256 in the package), and the scripts that serve and train it. The tag ends in a hash of all of that, so each Relay version runs the image built from its own sources.
+
+Install is automatic. Every time Relay starts in interactive mode it makes sure, in the background, that:
+
+1. the image is present, pulling it the first time (the status line shows the layers);
+2. a container named `relay-laya` runs it with the active model, published on `127.0.0.1:8737` only (the port of `laya.baseUrl`), with `--restart unless-stopped`;
+3. the server answers.
+
+The container then keeps running between sessions and comes back with Docker, so requests do not wait for the model to load. It serves on the CPU, which keeps the GPU free for training. Models trained from your sessions live in the Docker volume `relay-laya-models`. On the host, `~/.relay/agent/laya` only holds Relay's own data: the training exercises, the list of trained models, and telemetry. A Python environment or model left there by Relay 1.0.2 is deleted.
+
+Until the server answers, and whenever Docker is missing or stopped, keyword rules route requests; Relay says once why Laya is not running. Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/) (Windows, macOS) or Docker Engine (Linux) and start it; the next Relay start installs Laya. `/laya setup` does it right away.
+
+A server that already answers on the port when there is no `relay-laya` container is used as is, so you can run your own; one that announces other questions than Relay's, such as a laya-trainer server of another project, is reported instead of used. Relay manages a container only for a local `laya.baseUrl`. `"laya": { "autostart": false }` leaves Docker alone, and `laya.image` runs another image, for example one you built with `npm run laya:image -- --variant cpu` in a Relay checkout.
+
+## Teach Laya from your sessions
+
+The shipped model learned from synthetic requests, so it routes your kind of work by rules of thumb. Teach it the tasks you actually do:
+
+```
+/laya learn
+```
+
+1. **Collect.** Relay lists every request of the current session with the evidence of how it went: the model and effort that ran it, the tools called, the files changed, the commands, the errors of failed tool calls, whether tests and builds passed, what laya/auto planned, and your next message (a correction there means the task was not done right). `/laya learn <session file>` reads another session instead.
+2. **Label.** The agent answers Laya's 18 questions for each task from that evidence, for example "this fix needed the `balanced` tier, not `fast`: it took two failed edits and a correction". When the task taught something, it also writes a lesson: "The label comes from `locales/pt-BR/orders.json`, not the component; run `npm run i18n:check`." It saves them with the `laya_learn` tool and replies with a table of what it labeled. The labels are exercises in `~/.relay/agent/laya/training/data/dataset.jsonl`; a request learned again replaces its old labels.
+3. **Remember.** From the next request on, without waiting for training and even without Docker:
+   - A request close to a learned task is routed with that task's labels instead of Laya's or the keyword rules' answers. The status line shows `(memory)`. "Corrija o texto do botão Salvar na tela de pedidos, está cortado" goes to the tier and effort the learned "Corrija o texto do botão Salvar na tela de pedidos" needed, not to the cheapest tier the words "corrija o texto" suggest.
+   - The model that runs a request gets the lessons of similar learned tasks: in the laya/auto plan, or in a hidden `[laya:lessons]` message when you selected a model yourself.
+
+   Closeness is the cosine of the requests' word vectors, with words common to every coding request weighted down: routing needs 0.6, a lesson 0.45. Requests in another language than the learned one rarely match; training covers those. Turn the memory off with `"laya": { "memory": false }`.
+4. **Train.** Training runs in a Docker container, `relay-laya-train`, from the model that routes today. It mixes the session tasks with a replay sample of the earlier exercises, so Laya learns the new tasks without forgetting the rest. With an 8 GB NVIDIA GPU it takes about 7 minutes; the container gets the GPU when the CUDA image runs and Docker supports GPUs (Docker Desktop with WSL 2 on Windows, the NVIDIA Container Toolkit on Linux). Without one Relay asks first, because it can take an hour or more. The current model keeps routing while it runs, and the status line shows its progress.
+5. **Test and activate.** The new model and the current one answer the same held-out test, exercises neither was trained on. The new model routes requests from then on unless it answers more than 1% fewer test questions: Relay replaces the server container with one serving it, and reports how many answers on the session tasks it now gets right, before and after.
+
+You can also ask in your own words ("learn from this conversation"): with [`tool_search`](cli.md#tools) active, the agent finds `laya_learn` itself.
+
+| Command | Effect |
+|---|---|
+| `/laya learn [session file]` | Label the tasks of this session (or of a session file) and train on them |
+| `/laya train` | Train again on every session task collected so far |
+| `/laya models` | The shipped and trained models, their test scores, the exercises, and training progress |
+| `/laya use <model>` | Route with another model, for example `/laya use v1` to go back to the shipped one |
+
+Trained models live in the Docker volume `relay-laya-models` (about 680 MB each). Relay keeps the active one and the two newest others, and deletes older ones. Training needs Docker and the Laya image (`/laya setup`), and stops when Relay quits; it continues across `/new` and `/resume`.
+
+## Retrain from scratch
+
+To change the questions or rebuild the model, train with the `laya-trainer` Claude Code plugin. The questions Relay sends are the contract with the trained checkpoint, so train with Relay's own definitions:
+
+1. `/laya-init` prepares the training tools.
+2. `/laya decisions` (in Relay) writes the questions to `.laya/decisions.json`.
+3. `/laya seed 1100` writes synthetic bootstrap exercises to `.laya/data/relay-seed.jsonl`; add them with `/laya-data`. Their labels follow one rule from the task profile, so they teach Laya the policy, not evidence. The session tasks in `~/.relay/agent/laya/training/data/dataset.jsonl` (source `session`) can be added the same way.
+4. `/laya-train`, then `/laya-eval`.
+
+`/laya export` writes one exercise per successful routed request, labeled only with the tier that finished it, to `.laya/data/relay-telemetry.jsonl`. Telemetry stays local and contains your requests; turn it off with `"laya": { "telemetry": false }`.
+
+### Ship a new model
+
+A retrained model reaches users through a new revision of the Hugging Face repository, a new manifest in the package, and the images the release builds from it:
+
+```bash
+hf upload eltonssouza/relay-laya .laya/models/v2 . --commit-message "Laya model v2"
+node scripts/package-laya-model.mjs --model .laya/models/v2 --version v2 --out /tmp/laya-v2 --revision <commit from the upload>
+cp /tmp/laya-v2/model-manifest.ts packages/coding-agent/src/extensions/laya/model-manifest.ts
+```
+
+`hf upload` needs `hf auth login` with a token that can write to the repository. Upload before the release that embeds the new manifest: the release workflow builds the images, which download the model files and fail on a missing or altered one, so an unknown model never ships. Users get the new image, and a container serving it, on their next Relay start.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/laya` | Profile, container and server status, the routing model and training progress, models with credentials, quota, and the last plan with its alternatives and escalations |
+| `/laya setup`, `/laya start` | Pull the image if needed and start or update the `relay-laya` container now |
+| `/laya stop` | Stop the container; the next Relay start runs it again |
+| `/laya learn [session file]` | Teach Laya the tasks of this session ([details](#teach-laya-from-your-sessions)) |
+| `/laya train` | Train again on the session tasks collected so far |
+| `/laya models`, `/laya use <model>` | List the shipped and trained models, or route with another one |
+| `/laya policy <profile>` | Cost profile for this session |
+| `/laya decisions [path]` | Write the questions in laya-trainer format |
+| `/laya seed [count] [path]` | Write synthetic training exercises |
+| `/laya export [path]` | Write evidence-labeled exercises from telemetry |
+
+Set `"laya": { "toolRouting": "enforce" }` to also deactivate the tools a request does not need, for example `edit` and `write` for a question. The tool set is restored before the next request is planned. Tools the router does not recognize stay active.