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

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,112 @@
+# 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.
+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, 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.
+
+## Install the trained Laya
+
+The npm package does not contain the trained model (650 MB) or the Python environment it runs in (a few GB with torch). Relay fetches both once, into `~/.relay/agent/laya`:
+
+| Piece | Where it comes from | Size |
+|---|---|---|
+| Trained model | The public 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 | about 680 MB |
+| Python environment | A venv created from Python 3.10 to 3.13, with `torch` (a CUDA build only when `nvidia-smi` finds a GPU, the CPU build otherwise), `laya[serve]`, `fastapi` and `uvicorn` | a few GB |
+
+The first time you send a request with `laya/auto` selected, Relay asks whether to install them. You can also run `/laya setup` at any time. After that, `laya/auto` starts the server on `127.0.0.1:8000` by itself when a request needs it and stops it when the session ends. A server that already answers on that port is used as is, so you can run your own. Until the install finishes, or when it is declined, keyword rules route requests.
+
+Relay only starts a server for a local `laya.baseUrl`. Set `"laya": { "autostart": false }` to never start or offer one.
+
+Requirements: Python 3.10 to 3.13 (set `laya.python` if it is not on the PATH under `python3`, `python` or `py`), and on Windows a home directory path short enough for torch's DLLs (the default is).
+
+## Train and serve Laya
+
+Laya is trained 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.
+4. `/laya-train`, then `/laya-eval`.
+
+Over time, replace opinion with evidence: `/laya export` writes one exercise per successful routed request, labeled with the tier that finished it, to `.laya/data/relay-telemetry.jsonl`. Review it, add it with `/laya-data`, and train again. 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 and a new manifest in the package:
+
+```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 npm release that embeds the new manifest. The manifest pins the commit, file sizes and hashes, so a missing or altered file makes the install fail instead of running an unknown model. Installed users get the new version in a new directory on their next `/laya setup`.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/laya` | Profile, runtime and server status, models with credentials, quota, and the last plan with its alternatives and escalations |
+| `/laya setup` | Install the Python environment and download the trained model |
+| `/laya start`, `/laya stop` | Start the local server, or stop the one this session started |
+| `/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.

package/docs/llama-cpp.md

@@ -0,0 +1,114 @@
+# Local Models with llama.cpp
+
+Relay supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
+
+Use a current llama.cpp build with router support. Follow the [build instructions](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) or install a [prebuilt release](https://github.com/ggml-org/llama.cpp/releases) for your platform.
+
+## Start the router
+
+Start `llama-server` without `--model` or `-m`. Passing a model starts single-model mode instead of router mode.
+
+```bash
+llama-server \
+  --models-dir ~/models \
+  --no-models-autoload \
+  --jinja \
+  --host 127.0.0.1 \
+  --port 8080 \
+  -ngl 999 \
+  -c 32768
+```
+
+Important options:
+
+- `--models-dir ~/models` discovers local GGUF files.
+- `--no-models-autoload` keeps loading explicit through `/llama`.
+- `--jinja` enables compatible chat templates and tool calling.
+- `-ngl 999` offloads as many layers as possible to the GPU.
+- `-c 32768` sets the context window for each loaded model. Omit it to use the model's native context, which may require substantially more memory.
+
+A single-file model can sit directly in the model directory. Put multimodal and multi-shard models in separate subdirectories:
+
+```text
+~/models/
+├── llama-3.2-1b-Q4_K_M.gguf
+├── gemma-3-4b-it-Q4_K_M/
+│   ├── gemma-3-4b-it-Q4_K_M.gguf
+│   └── mmproj-F16.gguf
+└── large-model-Q4_K_M/
+    ├── large-model-Q4_K_M-00001-of-00003.gguf
+    ├── large-model-Q4_K_M-00002-of-00003.gguf
+    └── large-model-Q4_K_M-00003-of-00003.gguf
+```
+
+Restart the router after manually adding files. For per-model context sizes and other options, use [llama.cpp model presets](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets).
+
+## Configure Relay
+
+Start Relay and configure the provider:
+
+```text
+/login llama.cpp
+```
+
+Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
+
+If you start the router with `--no-models-autoload`, `/login llama.cpp` only stores the connection. Run `/llama` to load a model, then `/model` to select the loaded model for the current session.
+
+Environment variables can configure the same values without `/login`:
+
+```bash
+export LLAMA_BASE_URL=http://127.0.0.1:8080
+export LLAMA_API_KEY=optional-secret
+relay
+```
+
+If the server uses an API key, start `llama-server` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
+
+## Manage models
+
+Run:
+
+```text
+/llama
+```
+
+- Select an unloaded model to load it.
+- Select a loaded model to unload it.
+- Select **Download model…**, search Hugging Face, then choose a repository and quantization. Exact `owner/repository[:quant]` values also work.
+- Press Escape during a load or download to confirm cancellation.
+
+Hugging Face search uses `HF_TOKEN` when set, then checks `$HF_TOKEN_PATH`, `$HF_HOME/token`, `$XDG_CACHE_HOME/huggingface/token`, and `~/.cache/huggingface/token`. Search also works without authentication, subject to lower rate limits. Relay warns before downloading gated repositories and links to their access page. The llama.cpp server performs the download, so its process must also have `HF_TOKEN` when the selected repository requires access.
+
+If other models are loaded, Relay asks whether to unload them first or keep them loaded. Relay does not silently unload models and never deletes model files. The router may be shared with other clients, so `/llama` always displays the router's current state.
+
+Loaded and sleeping models appear in `/model`. Sleeping models wake automatically when selected. With router autoload enabled, unloaded preset models also appear and load when selected. With `--no-models-autoload`, load a model through `/llama` before selecting it.
+
+If the router disconnects, `/llama` shows **Retry** and **Close**. Retry reconnects and refreshes model state without replaying the interrupted operation.
+
+## Classification
+
+Every model listed for chat is also listed as a classifier model with the same ID and the `llama-cpp-classify` API. Classifier models answer typed `choice`, `bool`, and `score` questions about JSON state, like TypeSafe's Jev models. The model reaches them from [`codemode`](cli.md#enable-codemode) scripts, and extensions through `ctx.modelRegistry.classify()`; see [Classifier models](models.md#use-classifier-models).
+
+The model does not generate an answer. Each question becomes one chat prompt: the state, every question of the request, the state again, and then the question with its answers under single-token labels. Labels are letters for a choice (up to 62 options), `Yes`/`No` for a bool, and digits for a score (up to 10 levels). The second copy of the state is read with the questions in view, which improved accuracy on JevBench with small models. Relay reads the probabilities of the labels as the next token and normalizes them. A choice returns every option's probability and a confidence of `(n * peak - 1) / (n - 1)`; a score returns the expected level.
+
+- Raw label probabilities are usually overconfident. The per-request `temperature` option divides the label logits before normalizing; values above 1 soften the distribution. It changes no answer.
+- Questions run one after another. Everything before the final question is the same for all questions of a request, so the server's prompt cache evaluates it once. The state appears twice, so it needs twice its size in context.
+- Small models may follow instructions written inside the state. The prompt tells the model to judge the state as data, but that is not a guarantee.
+- Hybrid models such as Qwen3.5 cannot rewind a partially cached prompt without context checkpoints. If each question reprocesses the whole state, start the router with `--ctx-checkpoints 32 --checkpoint-min-step 0`.
+
+## Troubleshooting
+
+Check that the router is reachable:
+
+```bash
+curl http://127.0.0.1:8080/health
+curl http://127.0.0.1:8080/models
+```
+
+- **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
+- **Model missing from `/model` with `--no-models-autoload`:** Load it with `/llama` first.
+- **Load fails or uses too much memory:** Lower `-c` or unload another model.
+- **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.
+
+To remove the `llama.cpp` provider and `/llama`, disable `llama.cpp` under Built-in in `relay config`, or set `"extensions": ["-builtin:llama.cpp"]` in [settings](settings.md#resources).