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

package/docs/rpc-extension-ui.md

@@ -0,0 +1,200 @@
+# RPC Extension UI
+
+Extensions can request user interaction through `ctx.ui`. In RPC mode, supported calls become a request/response subprotocol alongside normal [RPC commands](rpc-commands.md) and [session events](json.md).
+
+There are two categories of extension UI methods:
+
+- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
+- **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
+
+If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
+
+## Limitations
+
+Some `ExtensionUIContext` methods are not supported or degraded in RPC mode because they require direct terminal UI access:
+
+- `custom()` returns `undefined`.
+- `onTerminalInput()` returns a no-op unsubscribe function.
+- `setWorkingMessage()`, `setWorkingVisible()`, `setWorkingIndicator()`, `setHiddenThinkingLabel()`, `setFooter()`, `setHeader()`, `addAutocompleteProvider()`, `setEditorComponent()`, and `setToolsExpanded()` are no-ops.
+- `getEditorText()` returns `""` and `getEditorComponent()` returns `undefined`.
+- `getToolsExpanded()` returns `false`.
+- `pasteToEditor()` delegates to `setEditorText()` without terminal paste handling.
+- `getAllThemes()` returns `[]`, and `getTheme()` returns `undefined`.
+- `setTheme()` returns `{ success: false, error: "Theme switching not supported in RPC mode" }`.
+
+Note: `ctx.mode` is `"rpc"` and `ctx.hasUI` is `true` in RPC mode because the dialog and fire-and-forget methods are functional via the extension UI sub-protocol. Use `ctx.mode === "tui"` to guard TUI-specific features like `custom()` that require a real terminal.
+
+## Requests from Relay
+
+All requests have `type: "extension_ui_request"`, a unique `id`, and a `method` field.
+
+### select
+
+Prompt the user to choose from a list. Dialog methods with a `timeout` field include the timeout in milliseconds; the agent auto-resolves with `undefined` if the client doesn't respond in time.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-1",
+  "method": "select",
+  "title": "Allow dangerous command?",
+  "options": ["Allow", "Block"],
+  "timeout": 10000
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the selected option string) or `cancelled: true`.
+
+### confirm
+
+Prompt the user for yes/no confirmation.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-2",
+  "method": "confirm",
+  "title": "Clear session?",
+  "message": "All messages will be lost.",
+  "timeout": 5000
+}
+```
+
+Expected response: `extension_ui_response` with `confirmed: true/false` or `cancelled: true`.
+
+### input
+
+Prompt the user for free-form text.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-3",
+  "method": "input",
+  "title": "Enter a value",
+  "placeholder": "type something..."
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the entered text) or `cancelled: true`.
+
+### editor
+
+Open a multi-line text editor with optional prefilled content.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-4",
+  "method": "editor",
+  "title": "Edit some text",
+  "prefill": "Line 1\nLine 2\nLine 3"
+}
+```
+
+Expected response: `extension_ui_response` with `value` (the edited text) or `cancelled: true`.
+
+### notify
+
+Display a notification. Fire-and-forget, no response expected.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-5",
+  "method": "notify",
+  "message": "Command blocked by user",
+  "notifyType": "warning"
+}
+```
+
+The `notifyType` field is `"info"`, `"warning"`, or `"error"`. Defaults to `"info"` if omitted.
+
+### setStatus
+
+Set or clear a status entry in the footer/status bar. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-6",
+  "method": "setStatus",
+  "statusKey": "my-ext",
+  "statusText": "Turn 3 running..."
+}
+```
+
+Send `statusText: undefined` (or omit it) to clear the status entry for that key.
+
+### setWidget
+
+Set or clear a widget (block of text lines) displayed above or below the editor. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-7",
+  "method": "setWidget",
+  "widgetKey": "my-ext",
+  "widgetLines": ["--- My Widget ---", "Line 1", "Line 2"],
+  "widgetPlacement": "aboveEditor"
+}
+```
+
+Send `widgetLines: undefined` (or omit it) to clear the widget. The `widgetPlacement` field is `"aboveEditor"` (default) or `"belowEditor"`. Only string arrays are supported in RPC mode; component factories are ignored.
+
+### setTitle
+
+Set the terminal window/tab title. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-8",
+  "method": "setTitle",
+  "title": "relay - my project"
+}
+```
+
+### set_editor_text
+
+Set the text in the input editor. Fire-and-forget.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-9",
+  "method": "set_editor_text",
+  "text": "prefilled text for the user"
+}
+```
+
+## Responses to Relay
+
+Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+
+### Value response (select, input, editor)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}
+```
+
+### Confirmation response (confirm)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-2", "confirmed": true}
+```
+
+### Cancellation response (any dialog)
+
+Dismiss any dialog method. The extension receives `undefined` (for select/input/editor) or `false` (for confirm).
+
+```json
+{"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}
+```
+
+## Example
+
+See the checked [RPC extension UI client](../examples/rpc-extension-ui.ts) and its [demo extension](../examples/extensions/rpc-demo.ts).
+
+The exported request and response unions are defined in [`rpc-types.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts). See [Extensions](extensions.md#ui-and-modes) for mode-independent extension guidance.

package/docs/rpc.md

@@ -0,0 +1,193 @@
+# RPC Mode
+
+RPC mode runs Relay as a long-lived subprocess controlled through JSON records on stdin and stdout. Use it for language-independent integrations, process isolation, IDEs, and custom user interfaces.
+
+For an in-process Node.js or Bun integration, prefer the [SDK](sdk.md). For a subprocess-based TypeScript integration, prefer the exported `RpcClient`, which starts Relay, correlates responses, exposes typed command methods, and delivers events to listeners.
+
+| Interface | Process boundary | Control model | Best fit |
+|---|---|---|---|
+| [SDK](sdk.md) | In process | Direct TypeScript methods and events | Node.js or Bun hosts that want complete API access |
+| RPC | Child process | JSONL commands, responses, and events | Other languages, isolated processes, IDEs, or custom clients |
+
+## Start RPC mode
+
+```bash
+relay --mode rpc --no-session
+```
+
+Normal CLI options still select the working folder, model, tools, resources, and session behavior. Common choices include `--provider`, `--model`, `--name`, `--no-session`, and `--session-dir`. See [Command Line](cli.md) for the complete, version-specific interface; `relay --help` is authoritative for the installed version.
+
+RPC mode rejects `@file` prompt arguments. Send prompts through the [`prompt`](rpc-commands.md#prompt) command instead.
+
+## Protocol records
+
+The protocol has four record families:
+
+| Direction | Record | Purpose |
+|---|---|---|
+| stdin | Command | Ask Relay to prompt, inspect state, change configuration, or manage the session |
+| stdout | `response` | Report whether one command succeeded and return any command data |
+| stdout | Session event | Stream run, message, tool, queue, compaction, and retry activity |
+| Both | Extension UI record | Forward supported extension interactions between Relay and the client |
+
+See [RPC Commands](rpc-commands.md), [JSON Event Stream](json.md), and [RPC Extension UI](rpc-extension-ui.md) for the canonical record definitions.
+
+### Correlate commands and responses
+
+Every command accepts an optional string `id`. A matching response repeats it:
+
+```json
+{"id":"req-1","type":"get_state"}
+{"id":"req-1","type":"response","command":"get_state","success":true,"data":{"...":"..."}}
+```
+
+Use unique IDs whenever more than one command can be outstanding. Command handling is asynchronous, so clients should correlate by ID rather than response order.
+
+Session events generally have no command ID because they describe session activity. `bash_execution_update` is the exception: when the originating [`bash`](rpc-commands.md#bash) command has an ID, its output events repeat that ID.
+
+An `extension_ui_response` uses the ID supplied by its `extension_ui_request`. It does not produce a normal command response.
+
+## Framing
+
+RPC uses strict JSONL framing. Write one complete JSON object per record and terminate it with LF (`\n`). Read stdout as a byte or UTF-8 stream and split records only on LF. Strip an optional preceding carriage return to accept CRLF input.
+
+Do not use a generic line reader that treats Unicode line or paragraph separators as record boundaries. In particular, Node.js `readline` also splits on `U+2028` and `U+2029`, which are valid inside JSON strings.
+
+Read stdout continuously. Relay honors stdout backpressure, but a client that stops reading can stall the process. Honor stdin backpressure when writing commands. Stdout is reserved for protocol records; diagnostics and application logging go to stderr.
+
+## Run lifecycle
+
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean model work completed:
+
+```json
+{"id":"req-2","type":"prompt","message":"Review this repository"}
+{"id":"req-2","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}
+```
+
+`data.disposition` reports what happened to the prompt. If it is `"handled"`, no run started for this prompt, so don't wait for `agent_settled`. See [RPC Commands](rpc-commands.md#prompt) for all values.
+
+Continue consuming [events](json.md) after that response. `agent_end` marks the end of one low-level agent run, but retries, overflow recovery, compaction, steering, or follow-up work can still follow. Wait for `agent_settled` when the client needs to know Relay will not continue automatically.
+
+Subscribe before sending a prompt to avoid missing a fast completion. `RpcClient.promptAndWait()` does this internally. If using separate `RpcClient` calls, install the event listener before `prompt()` and call `waitForIdle()` only while a run is active.
+
+## Errors
+
+A failed command returns one response with `success: false`:
+
+```json
+{"id":"req-3","type":"response","command":"set_model","success":false,"error":"Model not found: invalid/model"}
+```
+
+Malformed JSON produces a parse response without a request ID:
+
+```json
+{"type":"response","command":"parse","success":false,"error":"Failed to parse command: Unexpected token..."}
+```
+
+A success response only covers command handling. Provider failures and aborts after a prompt is accepted appear in the message and event stream.
+
+Clients must also handle child-process startup failures, unexpected exits, stderr diagnostics, cancellation, and their own deadlines. Do not parse stderr as protocol data.
+
+## Shutdown
+
+Close the child's stdin to request an orderly shutdown. Relay disposes the active runtime before exiting. Clients should still handle process signals and unexpected exits.
+
+An extension can also request shutdown through its extension context. Relay completes shutdown after the current command or after the active run emits `agent_settled`.
+
+## Minimal client
+
+This Python example uses a binary pipe reader, which splits on LF without treating Unicode separators as protocol boundaries:
+
+```python
+import json
+import subprocess
+
+process = subprocess.Popen(
+    ["relay", "--mode", "rpc", "--no-session"],
+    stdin=subprocess.PIPE,
+    stdout=subprocess.PIPE,
+)
+
+assert process.stdin is not None
+assert process.stdout is not None
+
+command = {"id": "prompt-1", "type": "prompt", "message": "Hello"}
+process.stdin.write(json.dumps(command).encode("utf-8") + b"\n")
+process.stdin.flush()
+
+while line := process.stdout.readline():
+    record = json.loads(line)
+    if record.get("type") == "message_update":
+        update = record["assistantMessageEvent"]
+        if update["type"] == "text_delta":
+            print(update["delta"], end="", flush=True)
+    elif record.get("type") == "agent_settled":
+        print()
+        break
+
+process.stdin.close()
+process.wait()
+```
+
+For maintained TypeScript clients, use the checked [RPC client example](../examples/rpc-client.ts). It requires a built Relay CLI because the repository example points to `dist/cli.js`.
+
+## Reference
+
+- [RPC Commands](rpc-commands.md): every stdin command and response
+- [JSON Event Stream](json.md): shared stdout session events and streaming reconstruction
+- [RPC Extension UI](rpc-extension-ui.md): dialogs, notifications, responses, and limitations
+- [Message Types](message-types.md): messages and content blocks used by responses and events
+- [Session File Format](session-format.md): entries returned by session commands
+- [`rpc-types.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/modes/rpc/rpc-types.ts): exported TypeScript protocol definitions
+- [`RpcClient`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts): subprocess client implementation
+
+## Moved reference anchors
+
+The detailed references formerly on this page now have dedicated pages. These anchors preserve existing links.
+
+<a id="prompt"></a>
+<a id="steer"></a>
+<a id="follow_up"></a>
+<a id="abort"></a>
+<a id="clear_queue"></a>
+<a id="new_session"></a>
+<a id="get_state"></a>
+<a id="get_messages"></a>
+<a id="set_model"></a>
+<a id="cycle_model"></a>
+<a id="get_available_models"></a>
+<a id="set_thinking_level"></a>
+<a id="cycle_thinking_level"></a>
+<a id="get_available_thinking_levels"></a>
+<a id="set_steering_mode"></a>
+<a id="set_follow_up_mode"></a>
+<a id="compact"></a>
+<a id="set_auto_compaction"></a>
+<a id="set_auto_retry"></a>
+<a id="abort_retry"></a>
+<a id="bash"></a>
+<a id="abort_bash"></a>
+<a id="get_session_stats"></a>
+<a id="export_html"></a>
+<a id="switch_session"></a>
+<a id="fork"></a>
+<a id="clone"></a>
+<a id="get_fork_messages"></a>
+<a id="get_entries"></a>
+<a id="get_tree"></a>
+<a id="get_last_assistant_text"></a>
+<a id="set_session_name"></a>
+<a id="get_commands"></a>
+
+Command details moved to [RPC Commands](rpc-commands.md).
+
+<a id="message_update-streaming"></a>
+<a id="bash_execution_update"></a>
+<a id="compaction_start--compaction_end"></a>
+<a id="summarization_retry_scheduled--summarization_retry_attempt_start--summarization_retry_finished"></a>
+
+Event details moved to [JSON Event Stream](json.md).
+
+<a id="extension-ui-protocol"></a>
+
+Extension interaction details moved to [RPC Extension UI](rpc-extension-ui.md).

package/docs/sdk.md

@@ -0,0 +1,147 @@
+# SDK
+
+`@relay-harness/coding-agent` embeds Relay in a Node.js or Bun process. It provides direct TypeScript access to the agent, sessions, tools, models, and resources used by the command-line application.
+
+Use the SDK for in-process TypeScript integration. For a language-independent or isolated subprocess, see [CLI Integration](cli-integration.md).
+
+```typescript
+import { createAgentSession } from "@relay-harness/coding-agent";
+
+const { session } = await createAgentSession();
+
+try {
+  await session.prompt("What files are in the current directory?");
+  console.log(session.getLastAssistantText());
+} finally {
+  session.dispose();
+}
+```
+
+This uses the working directory, discovered resources, stored settings, and configured credentials. `prompt()` resolves when the run finishes.
+
+The [complete minimal example](../examples/sdk/01-minimal.ts) also streams text events. All [SDK examples](../examples/sdk/) are typechecked with the repository.
+
+<a id="session-management"></a>
+
+## Session lifecycle
+
+`createAgentSession()` creates an `AgentSession`. The session owns one conversation, its model and tools, queued messages, compaction state, and extension runtime.
+
+Read current state through `session.messages`, `session.model`, `session.thinkingLevel`, `session.systemPrompt`, and `session.getActiveToolNames()`.
+
+`session.systemPrompt` is read-only and returns the current effective system prompt, including changes that have not yet been sent to the model. Tool changes are declared to the model before the next request.
+
+<a id="sessionmanager-api"></a>
+
+### Session storage
+
+Sessions are persistent by default. `SessionManager` owns the persisted or in-memory entry tree and tracks its active leaf. Branching changes that leaf without deleting abandoned branches. When Relay reconstructs model context, the manager selects the active branch and applies compaction.
+
+`SessionManager` is authoritative for finalized model context. Restore external history by constructing the session with a manager containing those entries. Assigning `session.agent.state.messages` does not replace persisted context.
+
+Use an in-memory manager when the host does not want session files:
+
+```typescript
+import { createAgentSession, SessionManager } from "@relay-harness/coding-agent";
+
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+});
+```
+
+See the checked [sessions example](../examples/sdk/11-sessions.ts) for creating, opening, continuing, listing, and forking sessions. [Session File Format](session-format.md) defines the persisted JSONL contract, and [Message Types](message-types.md) defines transcript values. For exact methods and signatures, use the exported TypeScript declarations or [`session-manager.ts`](../src/core/session-manager.ts).
+
+`cwd` selects the workspace used for project resource discovery, context files, session grouping, and built-in tool paths. Pass it explicitly when the target differs from `process.cwd()`.
+
+`session.dispose()` aborts active work, invalidates extension contexts, disconnects from the agent, and removes event listeners. Call it when the session is no longer needed.
+
+`AgentSessionRuntime` adds `newSession()`, `switchSession()`, `fork()`, and `importFromJsonl()`. Each operation replaces the active `AgentSession` and recreates services for the target working directory.
+
+After a runtime replacement, subscriptions belong to the old `AgentSession` and must be rebound. See the [session runtime example](../examples/sdk/13-session-runtime.ts).
+
+## Prompting
+
+`prompt()` handles extension commands and expands file-based prompt templates before ordinary user messages enter the agent. For an accepted agent run, it resolves after the run finishes, including automatic retries.
+
+A prompt sent while the session is already streaming must specify whether it should steer the current run or follow it. Calling `prompt()` without that choice rejects rather than guessing.
+
+A steering message enters after the current assistant turn and its tool calls. A follow-up enters after the current run finishes its pending work. `steer()` and `followUp()` expose those behaviors directly and return `"queued"` if the input was queued (including after an extension transformed it), or `"handled"` if an extension consumed it.
+
+`abort()` stops the active operation and waits for the session to become idle. `waitForIdle()` waits without aborting it.
+
+## Subscribing to events
+
+Subscribe before prompting when the host needs streamed output:
+
+```typescript
+const unsubscribe = session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+try {
+  await session.prompt("Explain this repository");
+} finally {
+  unsubscribe();
+}
+```
+
+Session events report message updates, tool execution, queues, compaction, retries, and run lifecycle changes.
+
+`message_end` contains the authoritative completed message. `agent_end` marks the end of one low-level agent run, but automatic recovery or queued work can still follow.
+
+Use `agent_settled` when the host needs to know that Relay will not continue automatically.
+
+## Configuring a session
+
+Without overrides, the factory creates a `ModelRuntime`, file-backed `SettingsManager`, persistent `SessionManager`, `DefaultResourceLoader`, and the configured default tools.
+
+Each boundary can be supplied explicitly:
+
+- `modelRuntime`, `model`, `thinkingLevel`, and `scopedModels` control model access and selection.
+- `settingsManager` supplies merged settings or an in-memory configuration.
+- `sessionManager` supplies persistent or in-memory conversation history.
+- `resourceLoader` supplies extensions, skills, prompt templates, themes, and context files.
+- `tools`, `noTools`, `excludeTools`, and `customTools` control the active tool set.
+
+Use `DefaultResourceLoader` when you want standard discovery with selected overrides. Supply a custom `ResourceLoader` when the host owns resource storage and discovery completely.
+
+<a id="inlineextension"></a>
+
+Inline extension factories can be supplied through `DefaultResourceLoader`. Give one an `InlineExtension` name only when it needs a stable name in diagnostics and startup output. A named inline extension with `replaceable: true` is left out when another extension registers a tool, command, or flag with a name it registers during loading, instead of both loading with a conflict. The CLI's built-in codemode, tool search, and MCP extensions are replaceable. A named entry with `builtin: true` is not an inline extension: it supplies the code of the `builtin:<name>` extension, which loads like a configured extension file. It loads by default, is listed in `relay config`, and is disabled by `-builtin:<name>` in the `extensions` setting or by `noExtensions`; `additionalExtensionPaths: ["builtin:<name>"]` loads it explicitly. It loads after project trust is resolved, so it cannot handle `project_trust`. The CLI's built-in extensions use it.
+
+<a id="codemode-mcp"></a>
+
+The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions do not; add `createCodemodeExtension()`, `createToolSearchExtension()`, and `createMcpExtension()` to the `extensionFactories` of `DefaultResourceLoader`. `codemode` and `tool_search` are registered inactive: enable them through the `defaultTools` setting (`["+codemode", "+tool_search"]` keeps the other default tools), or let the MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for servers with `deferred` exposure. The MCP extension connects its servers on `session_start`, so call `session.bindExtensions()`. See [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts).
+
+See the focused examples for [models](../examples/sdk/02-custom-model.ts), [tools](../examples/sdk/05-tools.ts), [extensions](../examples/sdk/06-extensions.ts), and [full control](../examples/sdk/12-full-control.ts).
+
+## Examples
+
+| Example | Purpose |
+|---|---|
+| [Minimal](../examples/sdk/01-minimal.ts) | Create, prompt, observe, and dispose a session |
+| [Custom model](../examples/sdk/02-custom-model.ts) | Select a model and thinking level |
+| [System prompt](../examples/sdk/03-custom-prompt.ts) | Replace or append to the system prompt |
+| [Skills](../examples/sdk/04-skills.ts) | Discover, filter, and add skills |
+| [Tools](../examples/sdk/05-tools.ts) | Select built-in tools and their working directory |
+| [Extensions](../examples/sdk/06-extensions.ts) | Load file-based and inline extensions |
+| [Context files](../examples/sdk/07-context-files.ts) | Add or replace project instructions |
+| [Prompt templates](../examples/sdk/08-prompt-templates.ts) | Add file-style prompt templates |
+| [Credentials](../examples/sdk/09-api-keys-and-oauth.ts) | Configure credential and model storage |
+| [Settings](../examples/sdk/10-settings.ts) | Supply file-backed or in-memory settings |
+| [Sessions](../examples/sdk/11-sessions.ts) | Control session persistence and restoration |
+| [Full control](../examples/sdk/12-full-control.ts) | Replace default discovery and state services |
+| [Session runtime](../examples/sdk/13-session-runtime.ts) | Replace the active session safely |
+| [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts) | Add the `codemode`, `tool_search`, and MCP extensions |
+
+<a id="exports"></a>
+
+## Resources
+
+- [Choose a Model](models.md) covers model selection and compatible endpoints; [Providers](providers.md) covers credentials and provider-specific setup.
+- [Configuration](configuration.md) explains normal discovery and settings; [Settings](settings.md) lists every setting.
+- [Sessions and Context](sessions.md) explains session behavior; [Session Format](session-format.md) defines persisted entries; [Message Types](message-types.md) defines shared transcript values.
+- [Extensions](extensions.md), [Skills](skills.md), and [Prompt Templates](prompt-templates.md) document resources supplied through a `ResourceLoader`.
+- [CLI Integration](cli-integration.md) covers print, JSON, and RPC alternatives to an in-process SDK integration.

package/docs/security.md

@@ -0,0 +1,99 @@
+# Run Relay safely
+
+Treat model-generated commands and code as untrusted. Relay can read, change, and execute files with the permissions of the account that started it, and it does not ask for approval before every tool call. Extensions, package installers, language servers, and other child processes run with those same permissions unless an operating-system or virtualization boundary restricts them.
+
+Files, comments, instructions, command output, and model responses can steer the model through prompt injection. Project trust controls which project resources load at startup, but it does not make that content or the resulting actions safe.
+
+Safety comes from limiting the files, credentials, processes, and network services Relay can access and affect if a generated action is wrong or hostile. Watching the transcript, using project trust, and reviewing changes do not create a security boundary.
+
+## Choose how to run Relay
+
+Different ways of running Relay place different limits on what generated commands can access:
+
+| How Relay runs | What remains protected |
+|---|---|
+| Directly, with the permissions of its operating-system user | Anything that user cannot access. A dedicated user account can narrow those permissions, but Relay still shares the operating system and network with other users. |
+| Entirely inside a container, virtual machine, or sandbox | Host files and processes that you do not expose to the environment. Credentials and network services remain accessible if you make them available inside it. This is usually the strongest practical option. |
+| Outside the isolated environment, with only its built-in tools running inside | Host resources are protected from actions performed through those tools. Relay itself and other extensions remain outside the boundary, so this is a narrower form of isolation. |
+
+The working folder controls resource discovery and the default location for tools, but it does not prevent commands from accessing other paths available to the Relay process.
+
+Whichever option you choose, only provide the files and services required for the task. Keep credentials outside the environment where possible, or use narrowly scoped, short-lived credentials. Restrict network access when commands do not need it.
+
+For setup instructions and the limitations of each isolation method, see [Run Relay in an isolated environment](containerization.md).
+
+<a id="project-trust"></a>
+
+## Understand project trust
+
+Project trust controls whether Relay loads most settings and resources supplied by a working folder. It prevents a folder from silently loading executable extensions before you approve it.
+
+Project trust is not a complete startup boundary. Relay reads the project `sessionDir` setting while selecting or creating a session, before it resolves project trust. Declining trust prevents the remaining project settings and protected resources from loading, but it cannot undo that initial session-directory lookup.
+
+Project trust does not limit what tool calls can access or affect. After Relay starts, enabled tools still use the operating-system permissions of the Relay process. Instructions and other content in the folder can also influence the model.
+
+### Resources protected by project trust
+
+Relay requires a project-trust decision when it finds any of these resources from the current working directory:
+
+- `.relay/settings.json`
+- `.relay/mcp.json`
+- `.relay/extensions`, `.relay/skills`, `.relay/prompts`, or `.relay/themes`
+- `.relay/SYSTEM.md` or `.relay/APPEND_SYSTEM.md`
+- project `.agents/skills` in the current directory or an ancestor directory
+
+A bare `.relay` directory does not require project trust.
+
+Granting project trust allows Relay to load:
+
+- project settings
+- project MCP servers from `.relay/mcp.json`
+- extensions, skills, prompt templates, themes, and system-prompt files under `.relay`
+- missing packages configured through project settings
+- project-local and project-package extensions
+
+Declining project trust skips those protected resources, except for the initial `sessionDir` lookup described above.
+
+Context files such as `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` load regardless of project trust unless you disable context loading. Treat instructions in a folder as untrusted input even when you decline project trust.
+
+### How Relay chooses a trust decision
+
+A command-line `--approve` or `--no-approve` override applies first. When protected resources exist and there is no command-line override:
+
+1. User-level and command-line extensions can handle the `project_trust` event. The first extension that returns yes or no owns the decision.
+2. If no extension decides, Relay looks for a saved decision for the current directory or one of its parents. The closest decision applies.
+3. If no saved decision applies, Relay follows the global `defaultProjectTrust` setting, whose default is `"ask"`.
+
+Saved decisions use canonical directory paths and live in:
+
+```text
+~/.relay/agent/trust.json
+```
+
+Use `/trust` to save a decision for future Relay processes.
+
+### Project trust without an interactive prompt
+
+Print, JSON, and RPC modes cannot show the built-in trust prompt. If no command-line override, extension, or saved decision applies:
+
+- `defaultProjectTrust: "always"` loads protected project resources.
+- `defaultProjectTrust: "ask"` or `"never"` skips them.
+
+Use `--approve` or `--no-approve` when an automated run needs an explicit one-time decision.
+
+## Reduce impact and improve recovery
+
+These practices do not replace isolation, but they reduce exposure or make recovery easier:
+
+- Give Relay access only to files and services required for the task.
+- Use snapshots, backups, or version control before substantial changes.
+- Review extensions and packages before loading them. Extensions execute inside the Relay process.
+- Prefer narrowly scoped, short-lived credentials.
+- Review diffs and generated output before applying results to another system.
+- Review sessions before exporting or sharing them. They can contain prompts, tool arguments, command output, file contents, and credentials exposed during the conversation.
+
+## Report a security issue
+
+Follow the repository [Security Policy](https://github.com/eltonssouza/relay-harness/blob/main/SECURITY.md). Do not open a public issue for a security-sensitive report.
+
+Expected local-agent behavior, prompt injection from untrusted content, lack of a built-in sandbox, and behavior from user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a privilege-boundary bypass or access that the local user did not already have.