The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* Pointing an agent at an Autonomous Grid instead of the engine's own login.
*
* The desktop app lets a user pick a grid (and optionally a model), mints a short-lived relay key for
* it, and sends the result as `payload.grid` on `agent_create` / `agent_retarget`. Nothing about that
* reaches an engine by itself: this CLI is what spawns the engine, so this module turns that payload
* into the launch — environment, and where the vendor demands it, argv.
*
* The one place that payload is kept is the registry row (`RegisteredSession.gridLaunch`, in a 0600
* file this daemon owns) — so a restart, or a pane recreated after a reboot, relaunches onto the SAME
* grid with the SAME key rather than silently coming back on the engine's own login. Nothing THIS
* module writes (argv, a config directory) ever carries the key; that rule is unchanged.
*
* ## Every entry here is the vendor's own documented contract
*
* The relay speaks two dialects — Anthropic Messages at `<grid>/relay`, and OpenAI
* chat/completions + responses at `<grid>/relay/v1` — so an engine can be pointed at it only if the
* engine itself offers a way to change its endpoint. Those ways differ, and none of them is
* guessable: `ANTHROPIC_BASE_URL` for Claude Code, `-c model_providers.*` argv for Codex,
* `GROK_MODELS_BASE_URL` for Grok, `COPILOT_PROVIDER_BASE_URL` for Copilot. Each entry below cites
* where it was read from.
*
* An engine with no entry is REFUSED, and the refusal names why for that engine specifically. Three
* shapes of "no" appear, and they are worth telling apart because only one of them could ever change
* on our side:
*
* * **Wrong protocol.** The engine CAN be re-pointed, but at its own vendor's API rather than an
* OpenAI- or Anthropic-shaped one. Cursor Agent reads `CURSOR_API_ENDPOINT` (default
* `https://api2.cursor.sh`, read out of the shipped bundle) and Antigravity reads
* `GOOGLE_GEMINI_BASE_URL` — handing either the relay would send it a dialect the relay does not
* serve (grid ADR 0012 lists Gemini as a future data edit, not a served endpoint). A knob
* existing is not the same as a knob that helps, and pointing one of these at a grid would fail
* inside the app with an error naming neither.
* * **Config-file only** (pi, kilo): the provider block has to be written into the user's own
* dotfile. Editing another tool's configuration on someone's behalf is a side effect that
* outlives the agent, so this module does not do it.
* * **Nothing documented** (muse, commandcode, amp, devin): no vendor documentation describes an
* endpoint override. These are the entries that could gain a contract tomorrow — with a cited
* source, not a plausible-looking variable name.
*
* Refusing is the point. Silently launching against the engine's own login would put the agent
* somewhere other than where the user said, spend the wrong account, and look like it worked.
*/
import { homedir } from 'node:os'
import { join } from 'node:path'
import type { AgentEngine } from '../engines/types.js'
import { isOpencodeV2 } from '../engines/opencode/contract.js'
import {
anthropicBaseUrl, API_NETWORK_PREFIX, GRID_KEY_VAR, GRID_ROUTER_MODEL, isApiLaunch, relayBaseUrl,
type GridEngineLaunch, type GridLaunchAnswer, type GridLaunchMachine, type GridLaunchOverride, type GridLaunchRequest,
type GridLaunchResult, type GridWebSearchStatus,
} from './gridLaunchWire.js'
import {
CLAUDE_ALLOW_WEB_TOOLS_ARG,
CLAUDE_DISALLOW_WEB_TOOLS_ARG,
claudeGridPromptArgs,
CODEX_DISABLE_WEB_SEARCH_ARGS,
mcpServersConfig,
codexMcpArgs,
GRID_MCP_AUTH_VAR,
GROK_CONFIG_FILE,
GROK_GRID_HOME_LINKS,
GROK_HOME_VAR,
grokGridConfig,
HERMES_MANAGED_CONFIG_FILE,
HERMES_MANAGED_DIR_VAR,
HERMES_SYSTEM_MANAGED_DIR,
hermesManagedConfig,
mcpAuthorizationHeader,
} from './gridWebMcp.js'
import { HARNESS_MCP_SERVER_NAME } from './harnessWebTools.js'
export * from './gridLaunchWire.js'
/**
* Grok's real state directory — the one a private [GROK_HOME_VAR] borrows `sessions/` from.
*
* `homedir()` rather than the daemon's own `env.GROK_HOME`, deliberately and for the reason stated
* beside [HERMES_SYSTEM_MANAGED_DIR]: a contract that reads process configuration answers
* differently depending on who launched it. The two agree in every deployment that matters — the
* daemon's `GROK_HOME` defaults to exactly this — and a machine that has moved it has moved the
* transcripts the daemon reads too, which is a question for the caller, not for a pure contract.
*/
function userGrokHome(): string {
return join(homedir(), '.grok')
}
/** The file OpenCode's `OPENCODE_CONFIG` is pointed at. */
const OPENCODE_CONFIG_FILE = 'opencode.json'
/**
* A grid's name as an OpenCode provider id.
*
* The id is what a person types as `<id>/<model>`, so it has to survive being typed: lowercase, no
* spaces, no dots. Grid names carry all three — `autonomous.ai`, `private autonomous`, `macOS` — so
* this is a real transformation rather than a formality.
*
* autonomous.ai -> autonomous-ai
* private autonomous -> private-autonomous
* macOS -> macos
*
* A name that leaves nothing behind (punctuation only) falls back to `grid`, because an empty
* provider key would make the config unparseable rather than merely odd.
*/
export function gridProviderId(networkName: string): string {
const slug = networkName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
return slug || 'grid'
}
/**
* The provider id OpenCode's generated config declares for [override].
*
* A saved API is `api-<connection id>`, never its bare name: OpenCode ships built-in providers under
* names like `openrouter`, and a config block with the same id is merged into the built-in one rather
* than replacing it.
*/
function opencodeProviderId(override: GridLaunchOverride): string {
return isApiLaunch(override)
? `api-${gridProviderId(override.networkId.slice(API_NETWORK_PREFIX.length))}`
: gridProviderId(override.networkName)
}
/**
* The provider block OpenCode reads, as JSON.
*
* Four things here are load-bearing, each of which breaks the engine differently when got wrong:
*
* 1. **No top-level `model` key on v1.** OpenCode 1.x's schema `$ref`s a CLOSED enum of known public
* models with no wildcard branch, so naming a private grid's model there makes OpenCode refuse
* the whole config at startup — a failure that arrives as a dead pane, long after the launch
* looked fine. The model is selected on argv instead, which is not schema-validated. v2 is the
* other way round: its TUI has no `-m`, and it accepts `model` naming the provider declared here
* (measured on 2.0.18: a fresh `--standalone` pane opened on it), so on v2 the key is written.
* 2. **`baseURL` is the relay root verbatim.** It already ends in `/relay/v1`; the SDK appends
* `/chat/completions` itself, so any "normalising" here 404s every request.
* 3. **`apiKey` is `{env:…}`, not the key.** Nothing written to disk by this module may contain a
* credential. This diverges from the advice a person following OpenCode's own docs gets — there
* the literal is recommended, because an unset variable silently becomes an empty string and a
* human-launched OpenCode has no guarantee the variable is set. Here it IS guaranteed: the
* daemon puts it in the pane's environment with `tmux new-session -e` before the engine starts.
* 4. **`limit` only when the window is known, and then BOTH halves.** OpenCode requires `context`
* and `output` together and rejects the config given only one. It is how OpenCode knows how much
* room is left, so without it a session ran on until the relay refused a request as too long,
* never having compacted. Absent when the relay did not report a window: inventing one would be
* worse than OpenCode's own defaults. `output` is a quarter of the window, capped at OpenCode's
* own 32K output ceiling — it is also what OpenCode holds back from the window for the reply, so
* a larger share would compact a small window after every other turn.
*/
/** OpenCode's own ceiling on a reply, which it also reserves out of the window. */
const OPENCODE_OUTPUT_MAX = 32_000
function opencodeOutputLimit(contextWindow: number): number {
return Math.min(OPENCODE_OUTPUT_MAX, Math.floor(contextWindow / 4))
}
function opencodeGridConfig(
provider: string,
override: GridLaunchOverride,
model: string,
v2: boolean,
): string {
// EXACTLY ONE model, and that is deliberate: it is what the agent was created with.
//
// Offering the router alongside it would let someone switch inside OpenCode, which reads as a
// kindness until you ask what the agent is running on. The probe that answers that
// (`readOpencodeGridAssignment`) reads this file, so a file naming two models can only say which
// one is live by parsing the engine's argv — and an argv is a live process's business, which it
// may rewrite. One model here makes the answer a fact about a file that cannot change under us.
//
// Choosing a different model is what every other engine here does too: per agent, at creation.
const models: Record<string, { name: string; limit?: { context: number; output: number } }> = {
[model]: {
name: model,
...(override.contextWindow
? { limit: { context: override.contextWindow, output: opencodeOutputLimit(override.contextWindow) } }
: {}),
},
}
return `${JSON.stringify({
$schema: 'https://opencode.ai/config.json',
// v2 only — see point 1 above. A resumed session keeps its own model whatever this says; the
// caller switches that one through the API (`sessionModel`).
...(v2 ? { model: `${provider}/${model}` } : {}),
provider: {
[provider]: {
npm: '@ai-sdk/openai-compatible',
// The grid's name as written — this is what a person reads in the model picker, so it keeps
// its dots and its capitals while the id beside it does not.
name: override.networkName,
options: {
baseURL: relayBaseUrl(override.baseUrl),
apiKey: `{env:${GRID_KEY_VAR}}`,
},
models,
},
},
// The grid's web tools, referencing the key exactly the way `apiKey` above does — opencode's own
// `{env:…}`, so this file still contains no credential.
...(override.mcpUrl
? {
mcp: {
[HARNESS_MCP_SERVER_NAME]: {
type: 'remote',
url: override.mcpUrl,
enabled: true,
headers: { Authorization: `Bearer {env:${GRID_KEY_VAR}}` },
},
},
}
: {}),
}, null, 2)}\n`
}
interface GridEngineContract {
build: (override: GridLaunchOverride, machine: GridLaunchMachine) => GridEngineLaunch
/** The engine cannot start against a grid without being told which model to ask for. */
requiresModel?: boolean
}
/**
* The variable an engine is told to read the key from, where the engine supports that indirection.
*
* Codex names it in `env_key`; Pi's `models.json` writes it as a `$VAR` reference. Both exist so the
* credential can stay in the environment while the configuration that points at it is not secret.
*/
/** The provider id our generated config declares. Pi selects it as `--model <id>/<model>`. */
const GRID_PROVIDER_ID = 'grid'
/**
* The status for an engine whose contract wires the server whenever there is a url to wire — which
* is every contract but Pi's, and Hermes's only when the machine lets it.
*/
const webSearchWhenWired = (override: GridLaunchOverride): GridWebSearchStatus =>
override.mcpUrl ? 'on' : 'unavailable'
/**
* Pi's provider block, as the Grid app shipped and unit-tested it
* (`autonomous-grid-app`, `pi_grid_config.dart` at 36d00c95, before Pi was dropped from that app for
* reasons about ITS chat UI — a fourth agent nobody reached for, and a 180 MB private Node
* toolchain — none of which apply here, where the user installs Pi themselves).
*
* `api: openai-completions` makes Pi post to `<base>/chat/completions`, which is what the relay
* serves. The context/cost numbers are Pi's own bookkeeping for its display; the grid decides what
* the model really takes.
*
* Registered by an extension (`pi -e`), not written as a `models.json` under a `PI_CODING_AGENT_DIR`
* of our own. That variable moves Pi's WHOLE home: the person's settings, packages and auth went with
* it, and so did `sessions/`, so every model switch reopened Pi in a new directory where `--session`
* found nothing and the daemon fell back to a fresh conversation (2026-10-14). An extension adds the
* provider and leaves `~/.pi/agent` exactly as the person keeps it.
*/
function piProviderExtension(baseUrl: string, model: string, contextWindow?: number): string {
const provider = {
name: 'Autonomous Grid',
baseUrl,
api: 'openai-completions',
// An env reference, not the key — nothing secret is written to disk.
apiKey: `$${GRID_KEY_VAR}`,
models: [{
id: model,
name: model,
reasoning: false,
input: ['text'],
// The real window when the relay reported one — the same fault as every engine here:
// told 200K, Pi never compacted before a smaller server refused the request.
contextWindow: contextWindow ?? 200000,
maxTokens: 8192,
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
}],
}
return `// Written by the machine adapter for this agent's grid launch. Adds the grid as a provider.\n`
+ `export default function (pi) {\n pi.registerProvider(${JSON.stringify(GRID_PROVIDER_ID)}, ${JSON.stringify(provider, null, 2).replace(/\n/g, '\n ')})\n}\n`
}
/** The file [piProviderExtension] is written to, handed to Pi with `-e`. */
const PI_PROVIDER_EXTENSION_FILE = 'grid-provider.ts'
/**
* Every engine that can be pointed at a grid, and how.
*
* `undefined` is a refusal with a reason attached in [GRID_ENGINE_REFUSALS]; see the module comment
* for why a missing entry is never filled in with a plausible-looking guess.
*/
const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> = {
// The grid CLI's own launch target (`autonomous-grid/shared/launch/claude.py`), so these are the
// vendor's names as that team verified them rather than this repo's reading of them.
claude: {
build: (override) => {
const webSearch = webSearchWhenWired(override)
return {
env: {
ANTHROPIC_BASE_URL: anthropicBaseUrl(override.baseUrl),
// The bearer variable, and ONLY it. Claude Code warns when ANTHROPIC_AUTH_TOKEN and
// ANTHROPIC_API_KEY are both set, and the relay prefers the Bearer header anyway — so
// ANTHROPIC_API_KEY would decide nothing, while colliding with the variable a user's own
// Anthropic key lives in.
ANTHROPIC_AUTH_TOKEN: override.apiKey,
// `grid launch claude` deliberately sets no model variable, on the grounds that a launcher
// has no standing to choose a user's model. That reasoning does not carry here: the desktop
// app ASKED, and this is the answer. Left unset when the user picked no model.
...(override.model ? { ANTHROPIC_MODEL: override.model } : {}),
// The window to compact within. A grid model's id is one Claude Code does not recognise, so
// it assumes 200K and compacts only near that — on a smaller server, never, because the
// server refuses the request first. This is the documented variable for exactly that
// case (code.claude.com/docs/en/model-config, "unrecognized model IDs").
...(override.contextWindow ? { CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(override.contextWindow) } : {}),
// Only when there are web tools to reach: the variable exists to be referenced by the config
// below, and setting it otherwise would leave a key in the pane that nothing reads.
...(override.mcpUrl ? { [GRID_KEY_VAR]: override.apiKey } : {}),
},
args: [
// On every grid launch, web tools or not: the built-in search is an Anthropic server tool
// that no grid runs, and the built-in fetch summarises through a model the grid does not
// serve. See `CLAUDE_DISALLOW_WEB_TOOLS_ARG`.
CLAUDE_DISALLOW_WEB_TOOLS_ARG,
// With the server comes its approval: a tool the daemon wired in and a permission mode then
// refuses is worse than no tool at all. See `CLAUDE_ALLOW_WEB_TOOLS_ARG`.
...(override.mcpUrl
? ['--mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR), CLAUDE_ALLOW_WEB_TOOLS_ARG]
: []),
// And the words. An agent moved here mid-conversation reads `WebSearch` off its own history
// before it reads the list, so the prompt names what is gone and — when one was wired — what
// replaces it, delivered past the recorded prompt a resume would otherwise replay. See
// `claudeGridPromptArgs`.
...claudeGridPromptArgs(webSearch === 'on'),
],
webSearch,
}
},
},
// Codex configures its provider entirely on the command line — `-c key=value` overrides anything
// `~/.codex/config.toml` would have said, which is how `ori codex` points it at OpenRouter without
// touching a dotfile (see `gatewayRuntime.ts`). Key names verified against the grid repo's
// `docs/codex-quickstart.md` and `-c` against codex-cli 0.144.6 on this machine.
//
// The key travels in the environment under `env_key`, never in argv.
codex: {
build: (override) => ({
env: {
[GRID_KEY_VAR]: override.apiKey,
...(override.mcpUrl ? { [GRID_MCP_AUTH_VAR]: mcpAuthorizationHeader(override.apiKey) } : {}),
},
args: [
'-c', 'model_provider="grid"',
'-c', 'model_providers.grid.name="Autonomous Grid"',
'-c', `model_providers.grid.base_url="${relayBaseUrl(override.baseUrl)}"`,
'-c', `model_providers.grid.env_key="${GRID_KEY_VAR}"`,
// Mandatory: Codex speaks the Responses dialect and rejects `wire_api = "chat"`.
'-c', 'model_providers.grid.wire_api="responses"',
// The relay streams HTTP SSE, not WebSocket.
'-c', 'model_providers.grid.supports_websockets=false',
// On every grid launch, web tools or not: the native search is a Responses-API feature no
// grid serves. See `CODEX_DISABLE_WEB_SEARCH_ARGS`.
...CODEX_DISABLE_WEB_SEARCH_ARGS,
...(override.mcpUrl ? codexMcpArgs(override.mcpUrl) : []),
...(override.model ? ['-m', override.model] : []),
// The window, and where to compact inside it. Codex knows neither for a model it does not
// recognise, so it never compacted and the relay refused the request as too long instead.
// 90% leaves the summary request itself room to fit.
...(override.contextWindow
? [
'-c', `model_context_window=${override.contextWindow}`,
'-c', `model_auto_compact_token_limit=${Math.floor(override.contextWindow * 0.9)}`,
]
: []),
],
webSearch: webSearchWhenWired(override),
}),
},
// opencode's simplest documented custom provider: the OpenAI-compatible pair
// (https://opencode.ai/docs/providers). The model is left to the app — its `--model` wants a
// `provider/model` pair whose provider id is not documented for the env-var route, and inventing
// one would send it looking for a model that does not exist.
// OpenCode is the one engine here that an endpoint variable alone cannot steer, and the reason is
// worth stating because `OPENAI_BASE_URL` looks like it should be enough — the grid CLI's own
// `grid info --env` exports exactly that pair, and it is enough for hermes.
//
// OpenCode's `openai` provider carries a COMPILED-IN model catalogue (49 entries: gpt-4o,
// gpt-5.6-terra-pro, …). It sends requests to `OPENAI_BASE_URL` but never asks that endpoint what
// it serves, so pointing it at a grid gives an engine that will only ever name models the grid has
// never heard of. Measured: it selected `gpt-5.6-terra-pro` and the relay answered
//
// 503 · No providers available for this model. This grid serves: DeepSeek-V4-Flash-0731, …
//
// and `-m openai/DeepSeek-V4-Flash-0731` — naming a real grid model under its built-in provider —
// made OpenCode's own server throw instead.
//
// So it takes the shape codex and pi take: DECLARE a provider. `OPENCODE_CONFIG` names a config
// file, this daemon writes one into a directory it owns, and the grid arrives as a provider whose
// models are the grid's own ids. The user's `~/.config/opencode/opencode.json` is never opened.
//
// ## v2 (2.0.18, measured)
//
// The TUI rejects `-m` and exits 1, so the model goes in the config file instead (see
// `opencodeGridConfig`, point 1). And by default the TUI attaches to ONE background service shared
// by every OpenCode on the machine, which never sees a pane's `OPENCODE_CONFIG`: a session put on a
// provider declared only here showed the service's default model in its footer. `--standalone`
// gives the pane its own server, which reads the file — the same session then showed the declared
// model. A resumed session keeps its stored model either way, so `sessionModel` is what the caller
// switches it to before the relaunch.
opencode: {
build: (override, machine) => {
const provider = opencodeProviderId(override)
// No model chosen means the grid routes — `Auto` is the router's own id, and the relay serves
// it (verified: 200). It is a real id to OpenCode either way, which is what matters: the
// provider block has to name something, and leaving the model out entirely puts OpenCode back
// on its own catalogue and the 503 above.
const model = override.model ?? GRID_ROUTER_MODEL
const v2 = isOpencodeV2(machine.opencodeMajor)
return {
// The key travels in the environment and is REFERENCED from the file, never written into it
// — the rule every config-file engine here follows.
env: { [GRID_KEY_VAR]: override.apiKey },
// Deliberately NOT `OPENAI_BASE_URL`/`OPENAI_API_KEY`. Setting them would re-arm the built-in
// `openai` provider beside ours, and its catalogue is what chose the model the grid refused.
args: v2 ? ['--standalone'] : ['-m', `${provider}/${model}`],
configDir: {
envVar: 'OPENCODE_CONFIG',
pointAt: OPENCODE_CONFIG_FILE,
files: [{
name: OPENCODE_CONFIG_FILE,
content: opencodeGridConfig(provider, override, model, v2),
}],
},
webSearch: webSearchWhenWired(override),
sessionModel: `${provider}/${model}`,
}
},
},
// Nous Research's documented trio for a custom OpenAI-compatible endpoint
// (hermes-agent/website/docs/reference/environment-variables.md) — plus the model on the command
// line, which is the only place hermes reads it from in the mode this daemon actually launches.
//
// `HERMES_INFERENCE_MODEL` is read by `hermes -z` and by the gateway behind `hermes --tui`. The
// pane opened here is neither: it is the INTERACTIVE CLI, whose model resolution is `-m` then
// config.yaml and no env tier at all (`cli.py:_init_model_and_provider`, "Priority: CLI args >
// env vars > config file" — the env half is about the provider). And a grid move relaunches as
// `hermes --resume <id>`, which restores the model stored on the session row unless argv carried
// an explicit `-m`; that flag is the documented opt-out ("resume must not clobber an explicit -m
// with the session's stored model", `cli.py` / `cli_model_switch_mixin.py`).
//
// Measured on 2026-09-08 before this line existed: the pane's environment said
// `HERMES_INFERENCE_MODEL=GLM-4.7-Flash` — which is what the desktop's model pill read back and
// printed — while hermes itself ran DeepSeek-V4-Flash-0731, the default in the user's own
// ~/.hermes/config.yaml and the model persisted on the resumed session's row.
//
// The variable stays beside the flag: `-z`/`--tui` read it, and it is how `gridAssignment.ts`
// answers "which model is this agent on" for hermes without parsing a live process's argv.
//
// ⚠️ The ENDPOINT has no such flag. Hermes's custom-provider resolver deliberately ignores
// `OPENAI_BASE_URL` ("config.yaml is the single source of truth for endpoint URLs",
// `runtime_provider_backends.py`) and the CLI exposes no `--base-url`, so moving a hermes agent
// between grids moves its model but leaves its requests on whatever relay config.yaml names. The
// only lever left is `HERMES_HOME`, which would take state.db and the user's skills with it and
// break the resume this move depends on.
//
// ⚠️ The overlay is the ONE thing here a machine can refuse. `HERMES_MANAGED_DIR` REPLACES
// `/etc/hermes` rather than adding to it — so on a machine where an administrator pinned Hermes
// settings there, writing ours would take their policy away for as long as the agent runs. The
// agent still launches on the grid; it launches without web tools, which is the smaller loss and
// the one the app can say out loud (`unsupported`). The machine fact arrives from the caller
// (`GridLaunchMachine`); the decision is made here so create, retarget and restore cannot differ.
hermes: {
build: (override, machine) => {
const overlay = !machine.hermesSystemManaged && override.mcpUrl
? hermesManagedConfig(override.mcpUrl, GRID_KEY_VAR)
: undefined
return {
env: {
OPENAI_BASE_URL: relayBaseUrl(override.baseUrl),
OPENAI_API_KEY: override.apiKey,
...(override.model ? { HERMES_INFERENCE_MODEL: override.model } : {}),
// Referenced by the overlay below, so it exists only when there is an overlay to read it.
...(overlay ? { [GRID_KEY_VAR]: override.apiKey } : {}),
},
args: override.model ? ['-m', override.model] : [],
// Hermes reads its MCP servers from one config file and takes no flag for them, so the web
// tools arrive as a managed-scope overlay merged over the user's own — see `gridWebMcp.ts`,
// including why this is `HERMES_MANAGED_DIR` and not `HERMES_HOME`.
...(overlay
? {
configDir: {
envVar: HERMES_MANAGED_DIR_VAR,
files: [{ name: HERMES_MANAGED_CONFIG_FILE, content: overlay }],
},
}
: {}),
// The pin outranks the url: a machine that cannot take the overlay cannot take it whether or
// not the grid offered one, and that is the fact a person can act on.
webSearch: machine.hermesSystemManaged ? 'unsupported' : webSearchWhenWired(override),
}
},
},
// xAI's own Grok CLI (the one this repo discovers under `~/.grok`, whose transcripts carry the
// `_x.ai/session/update` method). Its docs: "Grok fetches the model list from {base_url}/models",
// and "when you set models_base_url, Grok uses API key auth instead of session auth" — the second
// half of which does NOT hold in practice: measured, the variable moves where requests go but not
// which credential is picked, and the session token still wins. See `grokGridConfig`. The model has
// no documented variable, so it goes in argv AND into the config block that carries the credential.
//
// Its web tools cost it a private home. Grok reads `[mcp_servers]` from its config file and takes
// no flag for them, and the only layer that both starts unattended and is not the user's own file
// is `$GROK_HOME/config.toml` — the project layer is gated on a folder-trust prompt nobody is
// there to answer, and `CLAUDE_CONFIG_DIR` does not move MCP discovery at all. See `gridWebMcp.ts`,
// which measured each of them.
//
// ⚠️ `GROK_HOME` moves the WHOLE state directory, `sessions/` included — and for grok that is not
// cosmetic: `cli.ts` drops an observed grok agent entirely when it can find no transcript, so an
// un-borrowed home would launch an agent the harness never registers. The directory is linked back
// rather than moved; [GROK_GRID_HOME_LINKS] says which, and why the list stops where it does.
//
// ⚠️ The private home is NOT optional, and the reason is the credential order rather than the web
// tools. `XAI_API_KEY` is the LAST thing Grok reaches for — behind the OIDC session token — so an
// agent launched with the documented variable pair alone authenticates as the user's own xAI login
// and the relay answers 401. The config block declares the model with `env_key`, which outranks the
// session token; `grokGridConfig` carries the measurement. So every grid launch writes a config,
// web tools or not, and the user's own `~/.grok` is still never opened.
grok: {
// Deliberately NOT `requiresModel`. The credential rides on a declared model block, so a launch
// does need SOME model named — but that is this contract's problem to solve, not a question to
// put back to the user. No model picked means the grid routes, and the relay serves its router id
// like any other model (verified: `{"model":"Auto"}` → 200, answered by DeepSeek-V4-Flash-0731),
// so `Auto` is what the block declares. Verified end to end: Grok launched against `[model."Auto"]`
// with `env_key` answered a prompt through the router with `auth_mode=null` and no probe.
//
// Making this `requiresModel` was the first fix here and it was the wrong one: it turned "Auto",
// the default the New Agent dialog shows, into a refusal at the moment of clicking Create —
// trading a 401 the user could not diagnose for a wall they could not get past. Same trade
// OpenCode faced, same answer (see `GRID_ROUTER_MODEL` in its contract above).
build: (override, machine) => {
// One name, used in three places that must agree: argv, the config block's header, and the
// `model` field inside it. A mismatch would declare a credential for a model Grok never asks for.
const model = override.model ?? GRID_ROUTER_MODEL
return {
env: {
GROK_MODELS_BASE_URL: relayBaseUrl(override.baseUrl),
// Kept even though the config below is what actually wins. It is the documented pair for a
// custom endpoint, it is what `gridAssignment.ts` reads back, and on a build whose config
// layer we have misjudged it is still the credential Grok would reach for last.
XAI_API_KEY: override.apiKey,
// Referenced by `env_key` in the config, which is always written — so this always is too.
[GRID_KEY_VAR]: override.apiKey,
},
args: ['-m', model],
// ⚠️ ALWAYS a config directory now, web tools or not. It used to be written only when there
// were MCP servers to declare, on the reasoning that a launch with nothing to configure should
// leave the user's `~/.grok` alone — but the credential order (see `grokGridConfig`) means the
// config is what makes the grid key win over the OIDC session token. Without it a grid agent
// authenticates as the user's xAI login and the relay answers 401.
configDir: {
envVar: GROK_HOME_VAR,
files: [{
name: GROK_CONFIG_FILE,
content: grokGridConfig(
override.mcpUrl,
GRID_KEY_VAR,
model,
relayBaseUrl(override.baseUrl),
),
}],
links: GROK_GRID_HOME_LINKS.map((name) => ({ name, target: join(machine.grokHome ?? userGrokHome(), name) })),
},
webSearch: webSearchWhenWired(override),
}
},
},
// Pi takes the grid from an extension file in a directory this daemon owns, handed over with `-e`
// (see [piProviderExtension]): the person's own `~/.pi/agent` (settings, packages, sessions) is
// read as always and never written.
//
// The provider block has to name the model it serves, and Pi selects it as `grid/<model>` — so
// something must always be named. No model chosen means the grid routes: `Auto` is the router's
// own id and the relay answers it like any other, exactly as OpenCode's block above relies on.
//
// This used to be `requiresModel: true`, which refused the launch outright. That made Pi the one
// grid-capable engine a person could not start from the New agent dialog at all, since the dialog
// always creates on Auto and no longer offers a model field — a dead end, not a prompt to go and
// pick something.
pi: {
build: (override) => {
const model = override.model ?? GRID_ROUTER_MODEL
return {
env: { [GRID_KEY_VAR]: override.apiKey },
args: ['--model', `${GRID_PROVIDER_ID}/${model}`],
configDir: {
arg: '-e',
pointAt: PI_PROVIDER_EXTENSION_FILE,
files: [
{ name: PI_PROVIDER_EXTENSION_FILE, content: piProviderExtension(relayBaseUrl(override.baseUrl), model, override.contextWindow) },
],
},
// Pi has no MCP client, so there is nothing to hand the server to — with or without a url.
webSearch: 'unsupported',
}
},
},
// GitHub's documented BYOK path for Copilot CLI (docs.github.com … /use-byok-models). Copilot
// will not start against a custom provider without being told the model, so that is enforced
// here rather than left to fail inside the app.
//
// Web tools ride the same JSON document Claude Code is handed, under Copilot's own flag. The flag
// is `--additional-mcp-config` rather than a `--mcp-config`: it AUGMENTS `~/.copilot/mcp-config.json`
// for the session, which is the behaviour wanted here and the reason no dotfile is written.
copilot: {
requiresModel: true,
build: (override) => ({
env: {
COPILOT_PROVIDER_BASE_URL: relayBaseUrl(override.baseUrl),
COPILOT_PROVIDER_API_KEY: override.apiKey,
...(override.model ? { COPILOT_MODEL: override.model } : {}),
// Same rule as claude: the variable exists only to be referenced by the config below, so it
// is set only when there is a config to reference it.
...(override.mcpUrl ? { [GRID_KEY_VAR]: override.apiKey } : {}),
},
args: override.mcpUrl
? ['--additional-mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR)]
: [],
webSearch: webSearchWhenWired(override),
}),
},
}
/**
* Why an engine cannot be pointed at a grid, in words the person who picked it can act on.
*
* Every engine without a contract has an entry: "unsupported" on its own tells a user nothing about
* whether to wait for a release, change a setting, or pick another engine.
*/
const GRID_ENGINE_REFUSALS: Partial<Record<AgentEngine, string>> = {
// NOTE: pi is NOT here — it is supported through a private config directory. Kilo is, because its
// CLI has no OpenAI-compatible provider to configure at all, in any directory.
cursor: 'Cursor Agent can only be re-pointed at another Cursor API (CURSOR_API_ENDPOINT), '
+ 'not at an OpenAI-compatible relay',
agy: 'Antigravity speaks the Gemini API, which this relay does not serve',
kilo: 'the Kilo CLI has no OpenAI-compatible provider option yet (its own issues #5840, #6315)',
amp: 'Amp documents no way to change where it sends inference',
devin: 'Devin runs on its own hosted service and documents no endpoint override',
muse: 'Muse Code documents no way to change its endpoint',
commandcode: 'Command Code documents no way to change its endpoint',
omp: 'Harness has not yet verified how omp is pointed at another endpoint',
terminal: 'a terminal runs no engine to point at a grid — start one inside it and it will use its own login',
}
/** Engines that can be pointed at a grid today, for error text that names what to pick instead: the contracts'
* own list, which the core's declared one (lib/gridLaunchWire.ts `GRID_CAPABLE_ENGINES`) is held equal to. */
export function contractEngines(): AgentEngine[] {
return Object.keys(GRID_ENGINE_CONTRACTS) as AgentEngine[]
}
/**
* How `engine` must be launched to reach `override` on a machine like `machine`, or why it cannot be.
*
* `machine` is required rather than defaulted on purpose: the one fact in it is a policy an
* administrator set, and a caller that forgot to read it would write the overlay that policy exists
* to refuse — the exact failure moving the decision in here was meant to end.
*/
export function buildGridEngineLaunch(
engine: AgentEngine,
override: GridLaunchOverride,
machine: GridLaunchMachine,
): GridLaunchResult {
const contract = GRID_ENGINE_CONTRACTS[engine]
if (!contract) {
const reason = GRID_ENGINE_REFUSALS[engine] ?? 'it has no known way to change its endpoint'
return {
ok: false,
error: 'GRID_ENGINE_UNSUPPORTED',
detail: `${engine} cannot run on grid ${override.networkName}: ${reason}. `
+ `It would have run on its own login instead. Engines that can: ${contractEngines().join(', ')}.`,
}
}
if (contract.requiresModel && !override.model) {
return {
ok: false,
error: 'GRID_MODEL_REQUIRED',
detail: `${engine} will not start against a grid without a model. `
+ `Pick one for ${override.networkName} and try again.`,
}
}
return { ok: true, launch: contract.build(override, machine) }
}
/** A placeholder override, used only to ask a contract which variables it sets. Never launched. */
const PROBE_OVERRIDE: GridLaunchOverride = {
networkId: 'probe',
networkName: 'probe',
baseUrl: 'https://example.invalid/probe/relay/v1',
apiKey: 'probe',
model: 'probe',
// Present so the probe reports the variables a launch WITH web tools sets. Retarget clears what
// this answers, and a probe that left them out would move an agent to another grid while its old
// grid's MCP credential stayed in the pane — the exact staleness the doc comment below warns of.
mcpUrl: 'https://example.invalid/v1/grid/web-mcp/',
// Present for the same reason: a launch that knew its window sets a variable (Claude Code's), and
// moving back to the own login must take it out of the pane with the rest.
contextWindow: 131072,
}
/**
* Which environment variables pointing [engine] at a grid sets.
*
* Asked of the contract by building one, rather than kept as a second list beside it. A hand-written
* list would be correct exactly until an engine's contract gained a variable, and the symptom of it
* being stale is the worst kind: an agent moved back to its own login that quietly keeps talking to
* the grid, reporting success the whole way.
*
* Empty for an engine that has no contract — there is nothing to clear because nothing was set.
*/
export function contractEnvVarNames(engine: AgentEngine): string[] {
// No pin, for the same reason the probe carries an MCP url: this asks which variables a launch
// WITH web tools sets, so that clearing them covers the fullest launch this engine can get.
const built = buildGridEngineLaunch(engine, PROBE_OVERRIDE, { hermesSystemManaged: false })
if (!built.ok) return []
const names = Object.keys(built.launch.env)
if (built.launch.configDir?.envVar) names.push(built.launch.configDir.envVar)
return names
}
/**
* The models service's answer to the core (`ModelsPort.gridLaunch`): the launch `request.engine` takes to reach
* `request.override` and the override it was built from. `refresh` repeats a saved API's launch with its endpoint
* and key as saved now (`refreshApi`, lib/apiModels.ts), and a removed or unusable API is refused before anything
* is built, as a relaunch always refused it.
*/
export function answerGridLaunch(
request: GridLaunchRequest,
refreshApi: (override: GridLaunchOverride) => { override: GridLaunchOverride; apiBase?: string } | { error: string; detail: string },
): GridLaunchAnswer {
let override = request.override
let apiBase: string | undefined
if (request.refresh) {
const refreshed = refreshApi(override)
if ('error' in refreshed) return { ok: false, error: refreshed.error, detail: refreshed.detail }
override = refreshed.override
apiBase = refreshed.apiBase
}
const built = buildGridEngineLaunch(request.engine, override, request.machine)
const base = apiBase ? { apiBase } : {}
if (!built.ok) return { ...built, ...base }
return { ok: true, launch: built.launch, override, ...base }
}