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

package/docs/custom-provider.md

@@ -0,0 +1,173 @@
+# Custom Providers
+
+A provider extension connects Relay to a model service that needs custom authentication, model discovery, request handling, or streaming. If the service already speaks a supported API, configure it in `models.json` instead.
+
+Provider extensions run inside Relay and can inspect credentials, prompts, tool definitions, model responses, and usage. Treat them as trusted code and avoid logging secrets or provider payloads.
+
+## Choose the smallest integration
+
+| Requirement | Use |
+|---|---|
+| Add models behind a supported API | [`models.json`](models.md#configure-a-compatible-endpoint) |
+| Change an existing provider endpoint or headers | `models.json` or a small provider extension |
+| Discover models dynamically | A provider with `refreshModels` |
+| Add a `/login` flow | A provider with native or legacy OAuth configuration |
+| Implement an unsupported wire protocol | A provider with `stream` or `streamSimple` |
+
+A provider extension is an [extension](extensions.md), so it follows the same loading, trust, reload, and error behavior.
+
+## Register a provider
+
+Call `relay.registerProvider()` from the extension factory. Relay waits for asynchronous factories before startup continues, so providers registered there are available to startup model selection and `relay --list-models`.
+
+There are two registration forms:
+
+- Register a complete `Provider` from `@relay-harness/ai` for native authentication, filtering, discovery, refresh, and streaming behavior.
+- Register a provider name with `ProviderConfig` for the legacy configuration form used by existing extensions.
+
+Prefer a complete provider for new integrations that own more than static endpoint and model metadata. Relay composes `models.json` overrides above a registered native provider.
+
+Registering only `baseUrl` or `headers` for an existing provider preserves its built-in models. Supplying `models` in the legacy form replaces that provider's models across chat, image, and classifier operations. An omitted `type` means `"chat"`; image and classifier models require explicit discriminants and implementations keyed by their `api` values through the `images` and `classifiers` fields.
+
+For example, a mixed-operation provider can register non-chat models and their implementations together:
+
+```typescript
+relay.registerProvider("media-tools", {
+  apiKey: "$MEDIA_TOOLS_API_KEY",
+  models: [
+    {
+      type: "image",
+      id: "image-v1",
+      name: "Image V1",
+      api: "media-images",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      output: ["image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    },
+    {
+      type: "classifier",
+      id: "classifier-v1",
+      name: "Classifier V1",
+      api: "media-classifier",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 64000,
+    },
+  ],
+  images: {
+    "media-images": { generateImages: async (model, context, options) => result },
+  },
+  classifiers: {
+    "media-classifier": { classify: async (model, context, options) => result },
+  },
+});
+```
+
+Model-level `baseUrl` values take precedence over the provider endpoint. If no `models` list is supplied, built-in models of every operation remain registered. Equal model IDs in different operations remain distinct, including their model-specific headers.
+
+Calls made after initial extension loading take effect immediately. Use `relay.unregisterProvider()` to remove the dynamic provider and restore built-in behavior that it replaced.
+
+See the checked [GitLab Duo provider](../examples/extensions/custom-provider-gitlab-duo/) for a complete registration that delegates streaming to built-in API implementations.
+
+## Provide authentication
+
+Static providers can resolve an API key from a literal, environment interpolation, or a command. These values use the same syntax as `models.json`:
+
+- `$NAME` and `${NAME}` read environment variables.
+- A leading `!command` uses command output.
+- `$$` emits a literal `$`.
+- `$!` emits a literal leading `!`.
+
+Use native provider authentication when the integration needs stored credentials, custom resolution, provider-scoped environment, or multiple login methods.
+
+An OAuth provider supplies a display name, login flow, token refresh, and access-token resolution. After registration it appears in `/login`, and Relay stores returned credentials in `~/.relay/agent/auth.json`.
+
+OAuth callbacks are UI-neutral. They can open an authorization URL, show a device code, report progress, request input, or ask the user to choose a login method. Honor cancellation and the supplied abort signal during network requests.
+
+Never write access tokens, refresh tokens, authorization headers, or complete provider responses to ordinary logs.
+
+## Supply and refresh models
+
+Every model needs an ID, display name, input capabilities, and cost metadata. Chat and classifier models also need a context window; chat models need an output limit and reasoning support; image models declare their output modalities. Choose the API implementation at the provider level unless one model requires an override.
+
+Set `promptCache.short` or `promptCache.long` to the provider's best-effort cache lifetime in seconds when Relay should keep an idle prompt cache warm. Leave them unset to disable cache warming for that retention tier.
+
+Compatibility flags describe verified differences in an otherwise supported API. Do not enable them based only on an endpoint claiming compatibility.
+
+Confirm the request fields and response behavior against the actual server.
+
+Use `refreshModels` when the available catalog comes from a live service. Pass `context.signal` to blocking I/O so callers can cancel refreshes.
+
+The two registration forms have different refresh contracts:
+
+- A complete `Provider` returns nothing. It calls `context.publish({ update })` to install provider-owned model state, after which its synchronous `getModels()` exposes the latest list.
+- Legacy `ProviderConfig.refreshModels` returns mixed-operation model definitions. Relay replaces that registration’s live models with the returned list and applies any requested persistence.
+
+Publish persisted catalog data only when it should survive across runs. A live service such as llama.cpp can update its in-memory list without persisting it; a remote catalog can retain a snapshot for offline startup.
+
+## Reuse a supported streaming API
+
+Use one of Relay AI’s API implementations whenever the provider protocol matches it.
+
+Supported implementations cover Anthropic Messages, OpenAI Chat Completions and Responses, Google Generative AI and Vertex, Azure OpenAI Responses, Mistral Conversations, and Bedrock Converse.
+
+The provider can still customize authentication, base URLs, headers, model filtering, and discovery while delegating request conversion and streaming to an existing API implementation.
+
+This is safer than copying a stream implementation because it preserves Relay’s message conversion, tool handling, usage accounting, cancellation, and compatibility behavior.
+
+## Implement custom streaming
+
+Implement `streamSimple` only when no existing API implementation can represent the service. Study the implementations under [`packages/ai/src/api`](https://github.com/eltonssouza/relay-harness/tree/main/packages/ai/src/api) first.
+
+The stream receives a normalized `TranscriptContext`. System prompts and tool declarations live in transcript system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. A model that supports mid-conversation system messages can receive them in place; otherwise call `collapseSystemMessages(context)` to fold later system messages into the leading one.
+
+A custom stream must:
+
+1. Create an assistant message with provider, model, timestamp, pending stop reason, content, and zeroed usage.
+2. After request setup succeeds, emit one `start` event before content events.
+3. Update the message while emitting balanced text, thinking, and tool-call events.
+4. Finalize usage, cost, content, and stop reason.
+5. Emit exactly one terminal `done` or `error` event and close the stream.
+6. Convert cancellation into an aborted result.
+
+Request setup can fail before `start`; in that case the stream can terminate directly with `error`. Missing request authentication may also throw synchronously before a stream is returned.
+
+Content indexes refer to blocks in the assistant message. Update each block before emitting the event whose `partial` field exposes that state. Tool-call arguments must contain valid parsed input by `toolcall_end`.
+
+The stream must also honor request instrumentation supplied through `SimpleStreamOptions`:
+
+- Call `options.onPayload` before sending the provider request and use any replacement payload it returns.
+- Call `options.onResponse` after receiving the response but before consuming its body.
+- Await `options.onProviderStreamEvent?.(providerEvent, model)` for each parsed provider event before normalizing it.
+- Pass through the abort signal and provider-scoped environment.
+
+These hooks power extension request inspection, response-header events, and provider-stream observation. Omitting them makes the provider behave differently from Relay’s built-in providers.
+
+## Report failures and usage
+
+Set a concrete terminal stop reason. Error and aborted messages need an `errorMessage`; successful messages need accurate input, output, cache, total-token, and cost values.
+
+Relay can compact and retry after recognized context-overflow errors. If the service uses an unknown message, normalize only that provider’s overflow response to `context_length_exceeded` in a guarded `message_end` handler.
+
+Do not rewrite rate limits or transient provider failures as context overflow. Those failures use Relay’s normal retry behavior instead.
+
+## Test the integration
+
+Test at least:
+
+- ordinary and empty text responses
+- tool calls and tool results
+- image input and image tool results when supported
+- usage and cost accounting
+- abort behavior
+- context overflow
+- malformed or partial streams
+- Unicode boundaries
+- cross-provider session handoff
+- authentication refresh and cancellation
+
+The provider tests under [`packages/ai/test`](https://github.com/eltonssouza/relay-harness/tree/main/packages/ai/test) define the behavior expected from built-in providers. Adapt the relevant suites rather than relying only on manual prompts.
+
+Run the extension directly while developing, then move it to a discovered extension location or distribute it through a [Relay package](packages.md). Use `/reload` after changing a discovered provider extension in an active session.

package/docs/docs.json

@@ -0,0 +1,224 @@
+{
+  "navigation": [
+    {
+      "title": "Get Started",
+      "items": [
+        {
+          "title": "Overview",
+          "path": "index.md"
+        },
+        {
+          "title": "Quickstart",
+          "path": "quickstart.md"
+        },
+        {
+          "title": "How Relay Works",
+          "path": "how-relay-works.md"
+        }
+      ]
+    },
+    {
+      "title": "Guides",
+      "items": [
+        {
+          "title": "Run Relay",
+          "items": [
+            {
+              "title": "Use Relay in the Terminal",
+              "path": "usage.md"
+            },
+            {
+              "title": "Choose a Model",
+              "path": "models.md"
+            },
+            {
+              "title": "Manage Sessions and Context",
+              "path": "sessions.md"
+            },
+            {
+              "title": "Run Relay Safely",
+              "path": "security.md"
+            },
+            {
+              "title": "Isolate Relay",
+              "path": "containerization.md"
+            },
+            {
+              "title": "Run Local Models",
+              "path": "llama-cpp.md"
+            },
+            {
+              "title": "Configure Your Terminal",
+              "path": "terminal-setup.md"
+            },
+            {
+              "title": "Configure Shell Commands",
+              "path": "shell-aliases.md"
+            },
+            {
+              "title": "Run Relay in tmux",
+              "path": "tmux.md"
+            },
+            {
+              "title": "Run Relay on Windows",
+              "path": "windows.md"
+            },
+            {
+              "title": "Run Relay on Android",
+              "path": "termux.md"
+            }
+          ]
+        },
+        {
+          "title": "Customize Relay",
+          "items": [
+            {
+              "title": "Configure Relay",
+              "path": "configuration.md"
+            },
+            {
+              "title": "Create Prompt Templates",
+              "path": "prompt-templates.md"
+            },
+            {
+              "title": "Add Skills",
+              "path": "skills.md"
+            },
+            {
+              "title": "Create Themes",
+              "path": "themes.md"
+            },
+            {
+              "title": "Use Relay Packages",
+              "path": "packages.md"
+            },
+            {
+              "title": "Connect MCP Servers",
+              "path": "mcp.md"
+            }
+          ]
+        },
+        {
+          "title": "Build on Relay",
+          "items": [
+            {
+              "title": "Build Extensions",
+              "path": "extensions.md"
+            },
+            {
+              "title": "Add Custom Providers",
+              "path": "custom-provider.md"
+            },
+            {
+              "title": "Route with Virtual Models",
+              "path": "virtual-models.md"
+            },
+            {
+              "title": "Build Terminal UI Components",
+              "path": "tui.md"
+            },
+            {
+              "title": "Integrate with the CLI",
+              "path": "cli-integration.md"
+            },
+            {
+              "title": "Use the SDK",
+              "path": "sdk.md"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Reference",
+      "items": [
+        {
+          "title": "CLI",
+          "path": "cli.md"
+        },
+        {
+          "title": "Codemode",
+          "path": "codemode.md"
+        },
+        {
+          "title": "Slash Commands",
+          "path": "slash-commands.md"
+        },
+        {
+          "title": "Settings",
+          "path": "settings.md"
+        },
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
+        {
+          "title": "Keybindings",
+          "path": "keybindings.md"
+        },
+        {
+          "title": "Providers",
+          "path": "providers.md"
+        },
+        {
+          "title": "Session File Format",
+          "path": "session-format.md"
+        },
+        {
+          "title": "Compaction and Branch Summaries",
+          "path": "compaction.md"
+        },
+        {
+          "title": "Harness Core",
+          "path": "harness-core.md"
+        },
+        {
+          "title": "Adaptive Execution with Laya",
+          "path": "laya.md"
+        },
+        {
+          "title": "Requirements Intake",
+          "path": "intake.md"
+        },
+        {
+          "title": "JSON Event Stream",
+          "path": "json.md"
+        },
+        {
+          "title": "RPC Protocol",
+          "path": "rpc.md"
+        },
+        {
+          "title": "RPC Commands",
+          "path": "rpc-commands.md"
+        },
+        {
+          "title": "RPC Extension UI",
+          "path": "rpc-extension-ui.md"
+        },
+        {
+          "title": "Message Types",
+          "path": "message-types.md"
+        }
+      ]
+    }
+  ],
+  "redirects": [
+    {
+      "from": "development.md",
+      "to": "index.md"
+    },
+    {
+      "from": "session.md",
+      "to": "session-format.md"
+    },
+    {
+      "from": "tree.md",
+      "to": "sessions.md"
+    },
+    {
+      "from": "process-integration.md",
+      "to": "cli-integration.md"
+    }
+  ]
+}

package/docs/environment-variables.md

@@ -0,0 +1,97 @@
+# Environment Variables
+
+Relay uses environment variables in three ways:
+
+- Variables such as `RELAY_OFFLINE` configure the Relay process.
+- Relay sets process markers so child processes can identify Relay as the launching agent.
+- Commands run by the LLM-callable shell tools receive `RELAY_*` variables describing the current session.
+
+Provider API-key variables are documented separately in [Providers](providers.md#use-an-api-key-from-the-environment).
+
+## Process Marker
+
+The CLI and RPC entry points set two process markers:
+
+- `AI_AGENT=relay` is a generic marker that lets tooling identify Relay as the agent that launched the process.
+- `RELAY_CODING_AGENT=true` is Relay-specific and lets child processes detect that they run inside Relay.
+
+Child processes inherit both markers. They are not session-specific and are not set automatically when Relay is embedded through the SDK.
+
+## Shell Tool Session Environment
+
+Commands run by the `bash` and `powershell` tools receive the current Relay session state:
+
+| Variable | Description |
+|----------|-------------|
+| `RELAY_SESSION_ID` | Current session ID |
+| `RELAY_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
+| `RELAY_PROVIDER` | Currently selected model provider |
+| `RELAY_MODEL` | Currently selected model ID |
+| `RELAY_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+
+The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next shell command without restarting Relay. `RELAY_PROVIDER` and `RELAY_MODEL` identify the selected Relay model, not a different upstream model that a router may choose internally.
+
+When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
+
+```bash
+printf '%s/%s\n' "$RELAY_PROVIDER" "$RELAY_MODEL"
+printf 'reasoning=%s session=%s\n' "$RELAY_REASONING_LEVEL" "$RELAY_SESSION_ID"
+```
+
+The session file can be inspected directly when the session is persistent:
+
+```bash
+if [ -n "$RELAY_SESSION_FILE" ]; then
+  tail -n 1 "$RELAY_SESSION_FILE"
+fi
+```
+
+These variables are injected into the LLM-callable `bash` and `powershell` tools. They are not injected into user-entered `!` or `!!` commands.
+
+### Custom Shell Tools
+
+Tools created with `createBashTool()` or `createPowerShellTool()` expose the session environment by default when registered with Relay. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  spawnHook: (ctx) => ({
+    ...ctx,
+    env: { ...ctx.env, CI: "1" },
+  }),
+});
+```
+
+Disable session metadata independently of the spawn hook:
+
+```typescript
+const powershellTool = createPowerShellTool(cwd, {
+  exposeSessionEnvironment: false,
+  spawnHook: (ctx) => ctx,
+});
+```
+
+When disabled, Relay removes inherited values for these variables so nested Relay processes do not expose stale parent-session metadata.
+
+## Relay Process Configuration
+
+These variables are read by Relay itself:
+
+| Variable | Description |
+|----------|-------------|
+| `RELAY_CODING_AGENT_DIR` | Override the config directory; default is `~/.relay/agent` |
+| `RELAY_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
+| `RELAY_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
+| `RELAY_OFFLINE` | Disable automatic network activity, including model catalog refreshes |
+| `RELAY_SKIP_VERSION_CHECK` | Disable the GitHub latest-release check |
+| `RELAY_TELEMETRY` | Override provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `RELAY_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
+| `RELAY_SHARE_VIEWER_URL` | Base URL of a session viewer for `/share` links; without it, `/share` prints only the gist URL |
+| `RELAY_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `RELAY_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
+| `RELAY_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
+| `RELAY_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
+| `RELAY_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
+| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
+| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+
+Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and provider-specific configuration are listed in [Providers](providers.md#use-an-api-key-from-the-environment).