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

package/docs/compaction.md

@@ -0,0 +1,463 @@
+# Compaction Reference
+
+This reference describes automatic compaction, branch summarization, persisted entries, and extension hooks. For the user workflow, see [Sessions and Context](sessions.md#manage-conversation-context).
+
+**Source files** ([relay](https://github.com/eltonssouza/relay-harness)):
+- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+
+For TypeScript definitions in your project, inspect `node_modules/@relay-harness/coding-agent/dist/`.
+
+## Overview
+
+Relay has two summarization mechanisms:
+
+| Mechanism | Trigger | Purpose |
+|-----------|---------|---------|
+| Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
+| Branch summarization | `/tree` navigation | Preserve context when switching branches |
+
+Both use closely related structured formats and track file operations cumulatively. Summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+
+## Compaction
+
+### When It Triggers
+
+Auto-compaction triggers when:
+
+```
+contextTokens > contextWindow - reserveTokens
+```
+
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.relay/agent/settings.json` or `<project-dir>/.relay/settings.json`). This leaves room for the LLM's response.
+
+During a multi-turn agent run, Relay checks the canonical projected context after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Relay compacts during `prepareNextTurn`, then performs the existing catch-up steering poll before `turn_start`. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Relay also checks before a new user prompt and performs final-attempt overflow recovery after the low-level run ends.
+
+A provider context-overflow error or an early final `stopReason: "length"` can select one compact-and-retry recovery attempt. Length responses with tool calls retain their synthetic failed tool results and follow the ordinary tool/queue scheduler rather than forcing the run to end.
+
+You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
+
+### How It Works
+
+1. **Find cut point**: Walk backwards through the finalized session projection, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.relay/agent/settings.json` or `<project-dir>/.relay/settings.json`) is reached
+2. **Extract messages**: Collect projected messages from the previous kept boundary (or session start) up to the cut point
+3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
+4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
+5. **Rebuilds context**: Session rebuilds the context for the next request, using summary + messages from `firstKeptEntryId` onwards
+
+```
+Before compaction:
+
+  entry:  0     1     2     3      4     5     6      7      8     9
+        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
+                └────────┬───────┘ └──────────────┬──────────────┘
+               messagesToSummarize            kept messages
+                                   ↑
+                          firstKeptEntryId (entry 4)
+
+After compaction (new entry appended):
+
+  entry:  0     1     2     3      4     5     6      7      8     9     10
+        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
+               └──────────┬──────┘ └──────────────────────┬───────────────────┘
+                 not sent to LLM                    sent to LLM
+                                                         ↑
+                                              starts from firstKeptEntryId
+
+What the LLM sees:
+
+  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
+  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
+  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
+       ↑         ↑      └─────────────────┬────────────────┘
+    prompt   from cmp          messages from firstKeptEntryId
+```
+
+On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. A retain-none compaction records its own ID as `firstKeptEntryId`; repeated compaction starts after that entry. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Relay also recalculates `tokensBefore` from the rebuilt, context-edited session projection before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced. Omitted raw entries remain stored but do not affect cut selection, summaries, checkpoints, or token estimates.
+
+### Overflow and Length Recovery Ordering
+
+Recovery preserves the existing lifecycle and queue order. The completed attempt remains visible to `turn_end` and `agent_end`; post-run recovery then repairs persisted model context before a fresh retry:
+
+```text
+persist final assistant response
+→ extension/public turn_end
+→ extension/public agent_end
+→ append context_edit omissions for the selected attempt
+→ for overflow/length: run session_before_compact and append compaction on success
+→ start the retry as a fresh run
+```
+
+If recovery compaction fails or is cancelled, Relay keeps the omission edits, appends no compaction, and schedules no internal retry. Existing queued work remains governed by ordinary steering and follow-up rules. `agent_before_settle` sees the repaired projection after recovery processing. Raw transcript history, exports, billing totals, and history-search extensions can still inspect the omitted attempt.
+
+### Split user-message spans
+
+A user-message span starts with a user message and includes all turns until the next user message. Normally, compaction cuts at user-message boundaries.
+
+When one user-message span exceeds `keepRecentTokens`, the cut point lands within that span at an assistant message. This is a split user-message span:
+
+```
+Split user-message span (one span exceeds budget):
+
+  entry:  0     1     2      3     4      5      6     7      8
+        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
+        │ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
+        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
+                ↑                                     ↑
+         turnStartIndex = 1                  firstKeptEntryId = 7
+                │                                     │
+                └──── turnPrefixMessages (1-6) ───────┘
+                                                      └── kept (7-8)
+
+  isSplitTurn = true
+  messagesToSummarize = []  (no earlier user-message spans)
+  turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
+```
+
+For split user-message spans, Relay generates two summaries and merges them:
+1. **History summary**: Previous context (if any)
+2. **User-message-span prefix summary**: The early part of the split user-message span
+
+### Cut Point Rules
+
+Valid cut points are:
+- User messages
+- Assistant messages
+- BashExecution messages
+- Custom messages (custom_message, branch_summary)
+
+Never cut at tool results (they must stay with their tool call).
+
+Preparation advances the kept boundary into a context-invisible suffix only when that suffix contains an omitted assistant attempt and no unomitted context-producing entries. Recovery `context_edit` omissions satisfy this rule; intrinsically context-invisible metadata may coexist with them. Metadata alone and newly appended custom messages do not move the cut. A replacement edit affecting the candidate input or summarized prefix also blocks advancement because the omitted assistant answered the pre-edit input; replacements of suffix entries that are ultimately omitted remain safe. This allows an over-budget recovered input to be summarized while retaining the edits that keep the abandoned attempt omitted, without making bookkeeping change whether new model input is preserved verbatim.
+
+### CompactionEntry Structure
+
+Defined in [`session-manager.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/session-manager.ts):
+
+```typescript
+interface CompactionEntry<T = unknown> {
+  type: "compaction";
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+
+// Default compaction uses this for details (from compaction.ts):
+interface CompactionDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+Extensions can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom extension implementations can use their own structure. Generated and extension-provided summaries store their LLM `usage` when available so session totals include summarization work.
+
+See [`prepareCompaction()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+
+## Branch Summarization
+
+### When It Triggers
+
+When you use `/tree` to navigate to a different branch, Relay offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+
+### How It Works
+
+1. **Find common ancestor**: Deepest node shared by old and new positions
+2. **Collect entries**: Walk from old leaf back to common ancestor
+3. **Prepare with budget**: Include messages up to token budget (newest first)
+4. **Generate summary**: Call LLM with structured format
+5. **Append entry**: Save `BranchSummaryEntry` at navigation point
+
+```
+Tree before navigation:
+
+         ┌─ B ─ C ─ D (old leaf, being abandoned)
+    A ───┤
+         └─ E ─ F (target)
+
+Common ancestor: A
+Entries to summarize: B, C, D
+
+After navigation with summary:
+
+         ┌─ B ─ C ─ D
+    A ───┤
+         └─ E ─ F ─ [summary of B,C,D] (new leaf)
+```
+
+### Cumulative File Tracking
+
+Default compaction and branch summarization track files cumulatively. Both extract file operations from tool calls in the messages being summarized. Compaction also carries file lists from the previous Relay-generated compaction. Branch summarization carries file lists from Relay-generated branch summaries in the entries it summarizes.
+
+File tracking therefore accumulates across default compactions and nested default branch summaries. Relay does not automatically carry file lists from extension-generated summaries whose `fromHook` field is `true`; extensions manage their own `details` format.
+
+### BranchSummaryEntry Structure
+
+Defined in [`session-manager.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/session-manager.ts):
+
+```typescript
+interface BranchSummaryEntry<T = unknown> {
+  type: "branch_summary";
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+  summary: string;
+  fromId: string;      // Entry we navigated from
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+
+// Default branch summarization uses this for details (from branch-summarization.ts):
+interface BranchSummaryDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+Same as compaction, extensions can store custom data in `details`.
+
+See [`collectEntriesForBranchSummary()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
+
+## Summary Format
+
+Both formats include Goal, Constraints & Preferences, Progress, Key Decisions, and Next Steps. Compaction summaries also include Critical Context. Branch summaries stop after Next Steps. Relay appends file lists to either format when relevant.
+
+Compaction summaries use this format:
+
+```markdown
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Requirements mentioned by user]
+
+## Progress
+### Done
+- [x] [Completed tasks]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues, if any]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Next Steps
+1. [What should happen next]
+
+## Critical Context
+- [Data needed to continue]
+
+<read-files>
+path/to/file1.ts
+path/to/file2.ts
+</read-files>
+
+<modified-files>
+path/to/changed.ts
+</modified-files>
+```
+
+### Message Serialization
+
+Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+
+```
+[User]: What they said
+[Assistant thinking]: Internal reasoning
+[Assistant]: Response text
+[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
+[Tool result]: Output from tool
+```
+
+This prevents the model from treating it as a conversation to continue.
+
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
+
+## Custom Summarization via Extensions
+
+Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
+
+### session_before_compact
+
+Fired before auto-compaction or `/compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
+
+```typescript
+relay.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+
+  // preparation.messagesToSummarize - messages to summarize
+  // preparation.turnPrefixMessages - user-message-span prefix (if isSplitTurn)
+  // preparation.previousSummary - previous compaction summary
+  // preparation.fileOps - extracted file operations
+  // preparation.tokensBefore - context tokens before compaction
+  // preparation.firstKeptEntryId - where kept messages start
+  // preparation.settings - effective settings after applying model overrides
+
+  // branchEntries - all entries on current branch (for custom state)
+  // reason - "manual" (/compact), "threshold", or "overflow"
+  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)
+  // signal - AbortSignal (pass to LLM calls)
+
+  // Cancel:
+  return { cancel: true };
+
+  // Custom summary:
+  return {
+    compaction: {
+      summary: "Your summary...",
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      // usage: summaryResponse.usage, // Optional; included in session totals
+      details: { /* custom data */ },
+    }
+  };
+});
+```
+
+#### Converting Messages to Text
+
+To generate a summary with your own model, convert messages to text using `serializeConversation`:
+
+```typescript
+import { convertToLlm, serializeConversation } from "@relay-harness/coding-agent";
+
+relay.on("session_before_compact", async (event, ctx) => {
+  const { preparation } = event;
+  
+  // Convert AgentMessage[] to Message[], then serialize to text
+  const conversationText = serializeConversation(
+    convertToLlm(preparation.messagesToSummarize)
+  );
+  // Returns:
+  // [User]: message text
+  // [Assistant thinking]: thinking content
+  // [Assistant]: response text
+  // [Assistant tool calls]: read(path="..."); bash(command="...")
+  // [Tool result]: output text
+
+  // Now send to your model for summarization
+  const { summary, usage } = await myModel.summarize(conversationText);
+  
+  return {
+    compaction: {
+      summary,
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      usage,
+    }
+  };
+});
+```
+
+See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
+
+### session_compact_failed
+
+Fired when manual or automatic compaction fails or is aborted. This is useful for telemetry extensions that need to pair `session_before_compact` attempts with terminal outcomes.
+
+```typescript
+relay.on("session_compact_failed", async (event, ctx) => {
+  const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
+  // reason - "manual" (/compact), "threshold", or "overflow"
+  // errorMessage - present for non-abort failures
+  // aborted - true for canceled/aborted compactions
+  // willRetry - whether the aborted turn would have retried after compaction
+  // fromExtension - whether extension-provided compaction content was being used
+});
+```
+
+### session_before_tree
+
+Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+
+```typescript
+relay.on("session_before_tree", async (event, ctx) => {
+  const { preparation, signal } = event;
+
+  // preparation.targetId - where we're navigating to
+  // preparation.oldLeafId - current position (being abandoned)
+  // preparation.commonAncestorId - shared ancestor
+  // preparation.entriesToSummarize - entries that would be summarized
+  // preparation.userWantsSummary - whether user chose to summarize
+
+  // Cancel navigation entirely:
+  return { cancel: true };
+
+  // Provide custom summary (only used if userWantsSummary is true):
+  if (preparation.userWantsSummary) {
+    return {
+      summary: {
+        summary: "Your summary...",
+        // usage: summaryResponse.usage, // Optional; included in session totals
+        details: { /* custom data */ },
+      }
+    };
+  }
+});
+```
+
+See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+
+## Settings
+
+Configure compaction in `~/.relay/agent/settings.json` or `<project-dir>/.relay/settings.json`:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable auto-compaction |
+| `reserveTokens` | `16384` | Tokens to reserve for LLM response |
+| `keepRecentTokens` | `20000` | Recent tokens to keep (not summarized) |
+
+Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+### Per-model overrides
+
+Use `compaction.modelOverrides` to tune token budgets for different models:
+
+```json
+{
+  "compaction": {
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000,
+    "modelOverrides": {
+      "some-provider/big-model": {
+        "reserveTokens": 400000
+      }
+    }
+  }
+}
+```
+
+For a model with a 1M context window, this override triggers compaction above 600K tokens and keeps the ordinary 20000 recent tokens. Other models retain the ordinary 16384-token reserve. `reserveTokens` also influences summarization output limits, capped by the model's maximum output tokens; it is not solely a trigger threshold.
+
+Keys are exact, case-sensitive `provider/modelId` values, including any slashes within the model ID. Each `reserveTokens` and `keepRecentTokens` value falls back independently from the model override to the ordinary setting to the built-in default. Values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. Only omitted ordinary values use built-in defaults. `enabled` remains global, not model-specific.
+
+These resolved values are used for manual compaction, all automatic threshold checks, overflow recovery, and extension-visible `preparation.settings`. Model switches affect subsequent checks and compactions without changing ordinary settings. Compaction already in progress uses the model and settings captured for that operation. Branch summarization settings are unaffected.
+
+Overrides work in both global and project settings. The files merge recursively before lookup, so a global model-specific value beats a project-wide fallback; a project must override that model entry to change it. See [Settings](settings.md#per-model-compaction-overrides) for details.

package/docs/configuration.md

@@ -0,0 +1,47 @@
+# Configuration
+
+Relay supports user-level and project configuration. User-level configuration lives in the agent directory, which defaults to `~/.relay/agent`. Project configuration lives in `.relay` under the working directory and loads after [project trust](security.md#understand-project-trust) is granted. The only exception is `sessionDir`, which Relay reads before resolving trust so it can locate sessions.
+
+In interactive mode, use `/settings` to change common preferences. For other options, ask Relay to update the configuration or edit the relevant files directly. Run `/reload` after manually changing settings, keybindings, instructions, or resources.
+
+## Agent directory
+
+The agent directory is shown as `<agent-dir>` below. Set its location with the `RELAY_CODING_AGENT_DIR` environment variable or the SDK's [`agentDir`](sdk.md) option.
+
+| Path | Responsibility |
+|---|---|
+| `<agent-dir>/settings.json` | User-level [settings](settings.md), including preferences, defaults, resource paths, and Relay package declarations. |
+| `<agent-dir>/keybindings.json` | Custom terminal UI and application [keybindings](keybindings.md). |
+| `<agent-dir>/mcp.json` | [MCP servers](mcp.md) available in every project. |
+| `<agent-dir>/models.json` | [Compatible endpoints, models, and model overrides](models.md#configure-a-compatible-endpoint). |
+| `<agent-dir>/auth.json` | Saved API keys and OAuth credentials. |
+| `<agent-dir>/AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, or `CLAUDE.MD` | User instructions applied across working directories. |
+| `<agent-dir>/SYSTEM.md` | Replaces Relay’s default system prompt. |
+| `<agent-dir>/APPEND_SYSTEM.md` | Adds instructions to Relay’s system prompt. |
+| `<agent-dir>/extensions/` | User [extensions](extensions.md). |
+| `<agent-dir>/skills/` | User [skills](skills.md) and supporting files. |
+| `<agent-dir>/prompts/` | User [prompt templates](prompt-templates.md) exposed as slash commands. |
+| `<agent-dir>/themes/` | User [theme](themes.md) files. |
+
+## Project `.relay` directory
+
+| Path | Responsibility |
+|---|---|
+| `.relay/settings.json` | Project-level [settings](settings.md), resource paths, and Relay package declarations. |
+| `.relay/mcp.json` | Project [MCP servers](mcp.md). |
+| `.relay/SYSTEM.md` | Replaces the system prompt for the project. |
+| `.relay/APPEND_SYSTEM.md` | Adds project-specific instructions to the system prompt. |
+| `.relay/extensions/` | Project extensions. |
+| `.relay/skills/` | Project skills and supporting files. |
+| `.relay/prompts/` | Project prompt templates exposed as slash commands. |
+| `.relay/themes/` | Project theme files. |
+
+For `SYSTEM.md` and `APPEND_SYSTEM.md`, the trusted project file takes precedence over the corresponding agent-directory file. Files with the same name are not combined.
+
+## Context files
+
+Context files are separate from project `.relay` configuration. Relay loads them from the agent directory, the working directory, and its parent directories. A context file applies whenever Relay runs in its directory or anywhere below it.
+
+An `AGENTS.override.md` replaces `AGENTS.md` or `CLAUDE.md` only in the same directory. It does not suppress context files from the agent directory or other directories.
+
+Context-file discovery does not require project trust.

package/docs/containerization.md

@@ -0,0 +1,154 @@
+# Run Relay in an isolated environment
+
+Use an isolated environment to limit the files, credentials, processes, and network services that generated commands can access or affect.
+
+You can isolate the complete Relay process or keep Relay on the host and route selected tools into an isolated environment.
+
+## Choose an isolation method
+
+| Method | Where Relay runs | What is isolated | Credential handling | Best for |
+|---|---|---|---|---|
+| Plain Docker | Container | Relay, built-in tools, `!` commands, and extensions | Credentials passed into the container | A straightforward local container boundary |
+| Docker Sandboxes | Managed sandbox | Relay, built-in tools, `!` commands, and extensions | Provider credentials remain on the host and are substituted by the proxy | Managed local isolation without exposing the real provider key |
+| OpenShell | Local or remote sandbox | Relay, built-in tools, `!` commands, and extensions | Policy-controlled credentials and inference routing | Filesystem, process, network, and credential policies |
+
+The method changes where extensions run. When the complete Relay process runs inside an isolated environment, its extensions run there too.
+
+## Decide what Relay can access
+
+An isolated process can still affect resources you expose to it:
+
+- A read-write host mount lets Relay modify those host files.
+- Mounting `~/.relay/agent` exposes your Relay credentials, settings, extensions, and sessions.
+- Environment variables passed into a container are available to processes inside it.
+- Network access may allow code or tool output to leave the environment.
+- Tool-only isolation does not constrain the host Relay process or extension tools that do not use the isolated backend.
+
+Expose only the working folder, credentials, and network destinations needed for the task. Use read-only mounts or copy files into and out of the environment when you do not want writes to affect the host.
+
+## Run Relay in plain Docker
+
+Plain Docker provides the simplest whole-process container boundary.
+
+### Build the image
+
+Create `Dockerfile.relay`:
+
+```dockerfile
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+RUN git clone --depth 1 https://github.com/eltonssouza/relay-harness.git /opt/relay \
+  && cd /opt/relay \
+  && npm ci --ignore-scripts \
+  && npm run build:offline \
+  && npm link -w packages/coding-agent
+
+WORKDIR /workspace
+ENTRYPOINT ["relay"]
+```
+
+Build it from the directory containing the file:
+
+```bash
+docker build -t relay-sandbox -f Dockerfile.relay .
+```
+
+### Start Relay
+
+From the working folder you want Relay to access, run:
+
+```bash
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v "$PWD:/workspace" \
+  -v relay-agent-home:/root/.relay/agent \
+  relay-sandbox
+```
+
+Replace `ANTHROPIC_API_KEY` with the credential required by your provider. The named `relay-agent-home` volume keeps container-local settings, credentials, and sessions between runs.
+
+Do not mount the host's `~/.relay/agent` unless the container should have access to your host Relay configuration and credentials.
+
+### Verify the workspace
+
+Inside Relay, run:
+
+```text
+!pwd
+```
+
+The command should report `/workspace`. Changes under `/workspace` write through to the mounted host folder. Remove the bind mount or use a read-only mount when that is not acceptable.
+
+## Run Relay with Docker Sandboxes
+
+[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) runs the complete Relay process inside a managed sandbox. Its proxy can keep the real provider credential on the host and substitute it when requests leave the sandbox.
+
+Configure credentials before creating the sandbox. Do not run `/login` inside the sandbox because that writes a real credential into it.
+
+### Use a Claude Pro or Max token
+
+Generate the token with `claude setup-token` on a machine with Claude Code. If an `anthropic` secret is already configured, remove it first so the proxy does not add an API-key header alongside the bearer token:
+
+```bash
+sbx secret rm anthropic
+
+sbx secret set-custom \
+  --host api.anthropic.com \
+  --env ANTHROPIC_OAUTH_TOKEN \
+  --placeholder 'sk-ant-oat01-{rand}'
+```
+
+`sbx secret set-custom` reads the real token from standard input. The sandbox receives an OAuth-shaped placeholder, which the proxy replaces only for requests to the configured host.
+
+For an Anthropic API key, use `sbx secret set anthropic` instead.
+
+### Start Relay
+
+Run this from the working folder you want mounted:
+
+```bash
+sbx run --kit "docker.io/sbx/relay-kit:latest" relay
+```
+
+For an existing sandbox, run Relay non-interactively with:
+
+```bash
+sbx exec <sandbox-name> -- relay -p "list the failing tests"
+```
+
+See the [Relay kit documentation](https://github.com/docker/sbx-kits-contrib/tree/main/relay) for other providers, troubleshooting, and image pinning.
+
+## Run Relay with OpenShell
+
+[NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) provides local or remote sandboxes with filesystem, process, network, credential, and inference policies.
+
+### Select a gateway
+
+Every sandbox requires an active gateway:
+
+```bash
+openshell gateway add <gateway-url> --name <name>
+openshell gateway select <name>
+```
+
+### Create the sandbox
+
+```bash
+openshell sandbox create --name relay-sandbox --from relay -- relay
+```
+
+Relay, its built-in tools, `!` commands, and extension tools run inside the OpenShell boundary.
+
+### Transfer files to a remote sandbox
+
+A remote gateway does not bind-mount your host working folder. Clone the repository inside the sandbox or transfer files explicitly:
+
+```bash
+openshell sandbox upload relay-sandbox ./working-folder /workspace
+openshell sandbox download relay-sandbox /workspace/working-folder ./working-folder-out
+```
+
+OpenShell inference routing can keep raw model credentials outside the sandbox. When configured, point Relay at the corresponding OpenAI-compatible or Anthropic-compatible endpoint exposed by the gateway.