Skip to content

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.

feat: tell the app when an agent on a Local model has no web search

Kelvine42df7cb7c4d
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index dafe3d93d..44ae3fdc9 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -59,7 +59,7 @@ import { ENGINE_CLI_COMMANDS, ENGINES, engineBin, enginePathOverride } from './l
import type { AgentEngine } from './engines/types.js'
import { engineInstallRecipe } from './lib/engineInstall.js'
import { buildEngineCommandArgv, buildEngineLaunchArgv, commandAvailableInInteractiveShell } from './lib/engineLaunch.js'
-import { buildGridEngineLaunch, describeGridLaunch, gridConflictingEnvToClear, gridEnvVarNames, type GridEngineLaunch } from './lib/gridLaunch.js'
+import { buildGridEngineLaunch, describeGridLaunch, gridConflictingEnvToClear, gridEnvVarNames, type GridLaunchMachine, type GridWebSearchStatus } from './lib/gridLaunch.js'
import { HERMES_SYSTEM_MANAGED_DIR } from './lib/gridWebMcp.js'
import { writeGridConfigDir } from './lib/gridConfigDir.js'
import { tmuxSupportsSessionEnv, TMUX_SESSION_ENV_MIN } from './lib/tmuxVersion.js'
@@ -70,7 +70,7 @@ import { claudeContinuation, findLiveSession } from './lib/sessionRepair.js'
import { TmuxBackend } from './lib/tmuxBackend.js'
import { createAndRegisterPane } from './lib/createAgentPane.js'
import { restoreAgents } from './lib/restoreAgents.js'
-import { buildLaunchOverrides, validateLaunchOverrides, type LaunchOverridesDeps, type LaunchOverridesResult, type LaunchSource } from './lib/launchOverrides.js'
+import { buildLaunchOverrides, validateLaunchOverrides, type LaunchOverrides, type LaunchOverridesDeps, type LaunchOverridesResult, type LaunchSource } from './lib/launchOverrides.js'
import { buildHarnessSessionLabel } from './lib/harnessSessionLabel.js'
import { basename } from 'node:path'
import {
@@ -3343,23 +3343,17 @@ async function runForeground(session: AuthSession): Promise<void> {
}
}
/**
- * The config directory a grid launch should actually be given on THIS machine, or none.
+ * What the launch builder needs to know about THIS machine, read at launch time.
*
- * Only Hermes can lose one. Its web tools ride a managed-scope overlay, and `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 that can be said out loud.
- *
- * Here rather than in the contract because it is a fact about the machine: a `build()` that
- * stats the filesystem answers differently on two of them, and its spec would follow.
+ * The one fact is whether an administrator pinned Hermes settings in `/etc/hermes`: Hermes's web
+ * tools ride a managed-scope overlay that REPLACES that directory rather than adding to it, and the
+ * builder drops the overlay on such a machine (the agent launches on the grid without web tools,
+ * and the app says so). Read here rather than in the contract because it is a fact about the
+ * machine: a `build()` that stats the filesystem answers differently on two of them, and its spec
+ * would follow. What is DONE with the fact lives in the builder, so create, retarget and restore
+ * cannot disagree about it.
*/
- const gridConfigDirFor = (engine: AgentEngine, launch: GridEngineLaunch): GridEngineLaunch['configDir'] => {
- if (!launch.configDir || engine !== 'hermes' || !existsSync(HERMES_SYSTEM_MANAGED_DIR)) return launch.configDir
- console.warn(`[grid] ${engine} starts without web tools · ${HERMES_SYSTEM_MANAGED_DIR} pins this `
- + `machine's Hermes settings, and the overlay carrying the web tools would replace it`)
- return undefined
- }
+ const gridLaunchMachine = (): GridLaunchMachine => ({ hermesSystemManaged: existsSync(HERMES_SYSTEM_MANAGED_DIR) })
/**
* What a relaunch of `session` must be given, beyond the engine's argv, to come back where it was —
@@ -3368,7 +3362,7 @@ async function runForeground(session: AuthSession): Promise<void> {
* keyed on the agent, so relaunching the same agent rewrites one directory instead of leaving a trail.
*/
const launchOverridesDeps: LaunchOverridesDeps = {
- configDirFor: gridConfigDirFor,
+ machine: gridLaunchMachine,
writeGridConfigDir,
tmuxSupportsSessionEnv,
installCodexHooks: (codexHome) => { if (!env.DISABLE_HOOK_INSTALL) installCodexHooks(hookPort, codexHome) },
@@ -3376,6 +3370,18 @@ async function runForeground(session: AuthSession): Promise<void> {
const relaunchOverrides = (session: RegisteredSession, source: LaunchSource = session): Promise<LaunchOverridesResult> =>
buildLaunchOverrides(launchOverridesDeps, session.engine, source, session.agentId)
+ /**
+ * A restart or a post-reboot restore rebuilds the ROW's own launch, and the machine may decide
+ * differently about web search this time than it did when the row was written (an administrator
+ * pinned `/etc/hermes` since, or unpinned it). The override is the row's already; what is
+ * refreshed is the decision, so the frame describes the pane that actually came up. Retarget
+ * does not go through here — its override is new, and it records the pair itself once the move
+ * has succeeded.
+ */
+ const refreshGridWebSearch = (agentId: string, overrides: LaunchOverrides): void => {
+ if (overrides.gridLaunchRecord) registry.setGridLaunch(agentId, overrides.gridLaunchRecord)
+ }
+
watcher.start()
await cursorDiscovery.start()
// Panes that died while the daemon was down (a reboot takes the whole tmux server with it) are
@@ -3398,6 +3404,9 @@ async function runForeground(session: AuthSession): Promise<void> {
// own shell.
const built = await relaunchOverrides(entry)
if (!built.ok) return { error: built.error, detail: built.detail }
+ // Before the pane comes up rather than after: restore has no later hook per agent, and a
+ // pane that fails to come up is reported failed by the frame regardless of this field.
+ refreshGridWebSearch(entry.agentId, built.overrides)
const { env: launchEnv, extraArgs, clearEnv } = built.overrides
const argv = buildEngineLaunchArgv(entry.engine, {
...opts,
@@ -3589,9 +3598,9 @@ async function runForeground(session: AuthSession): Promise<void> {
// A grid is the user's answer to "where should this run", so every way of not honouring it is a
// refusal rather than a fallback — an agent silently started on the engine's own login spends the
// wrong account and looks identical to one that worked.
- let gridLaunch: { env: Record<string, string>; args: string[] } | undefined
+ let gridLaunch: { env: Record<string, string>; args: string[]; webSearch: GridWebSearchStatus } | undefined
if (grid) {
- const built = buildGridEngineLaunch(engine, grid)
+ const built = buildGridEngineLaunch(engine, grid, gridLaunchMachine())
if (!built.ok) {
console.warn(`[agent] create ${engine} refused · ${built.detail}`)
return { ok: false, error: built.error, detail: built.detail }
@@ -3604,12 +3613,11 @@ async function runForeground(session: AuthSession): Promise<void> {
console.warn(`[agent] create ${engine} refused · ${detail}`)
return { ok: false, error: 'TMUX_TOO_OLD_FOR_GRID', detail }
}
- gridLaunch = { env: { ...built.launch.env }, args: built.launch.args }
+ gridLaunch = { env: { ...built.launch.env }, args: built.launch.args, webSearch: built.launch.webSearch }
// An engine whose provider lives in a file gets a directory this daemon owns, never the
// user's own dotfiles. The label is unique per creation, so two agents never share one.
- const createConfigDir = gridConfigDirFor(engine, built.launch)
- if (createConfigDir) {
- const { envVar, files, pointAt, links } = createConfigDir
+ if (built.launch.configDir) {
+ const { envVar, files, pointAt, links } = built.launch.configDir
try {
const dir = await writeGridConfigDir(label, files, links)
// Pi is handed the directory; OpenCode's OPENCODE_CONFIG wants the file inside it.
@@ -3622,7 +3630,7 @@ async function runForeground(session: AuthSession): Promise<void> {
}
// Named in the log because the pane itself gives nothing away: the engine looks exactly like a
// normally launched one. The key is never printed.
- console.log(describeGridLaunch(engine, grid))
+ console.log(describeGridLaunch(engine, grid, built.launch.webSearch))
}
// A Codex agent pointed at a profile OTHER than this machine's default reads hooks.json from
// THAT folder, not the one `harness login` already installed into — without this, such an agent
@@ -3661,7 +3669,7 @@ async function runForeground(session: AuthSession): Promise<void> {
argv,
env: gridLaunch?.env ?? (codexHome ? { CODEX_HOME: codexHome } : undefined),
grid: grid ? { baseUrl: grid.baseUrl, model: grid.model ?? null } : null,
- gridLaunch: grid ?? null,
+ gridLaunchRecord: grid && gridLaunch ? { override: grid, webSearch: gridLaunch.webSearch } : null,
codexHome,
bypassPermission,
})
@@ -3926,8 +3934,10 @@ async function runForeground(session: AuthSession): Promise<void> {
probeGridAssignment(outcome.processIdentity, session.engine, outcome.processIdentity.executable),
])
registry.updateProcessIdentity(session.agentId, outcome.processIdentity, gateway.kind, assignment)
- // The launch that just worked is the one a restart or a post-reboot restore must repeat.
- registry.setGridLaunch(session.agentId, grid)
+ // The launch that just worked is the one a restart or a post-reboot restore must repeat — and
+ // what it decided about web search is what the app shows for this agent from now on. Null for
+ // a move home: the block, and the status with it, leave the frame together.
+ registry.setGridLaunch(session.agentId, built.overrides.gridLaunchRecord ?? null)
// Persisted only on the way OUT, and only once the move actually succeeded — a refused move
// must not overwrite the model the agent is still sitting on. Survives a daemon restart, so an
// agent left on a grid for a week still knows where it came from.
@@ -3939,7 +3949,10 @@ async function runForeground(session: AuthSession): Promise<void> {
// would leave the banner up over an agent that had already been moved.
if (refreshed) announceSession(refreshed)
const how = outcome.resumed ? 'resumed' : 'fresh session'
- const where = grid ? describeGridLaunch(session.engine, grid) : `${session.engine} on its own login`
+ const record = built.overrides.gridLaunchRecord
+ const where = record
+ ? describeGridLaunch(session.engine, record.override, record.webSearch)
+ : `${session.engine} on its own login`
console.log(`${where} · retargeted ${sid(session.agentId)} · ${how}`)
return { ok: true }
} finally {
@@ -4028,6 +4041,7 @@ async function runForeground(session: AuthSession): Promise<void> {
)
if (!outcome.ok) return { ok: false, error: 'RESTART_FAILED', detail: outcome.detail }
+ refreshGridWebSearch(session.agentId, built.overrides)
// Address the CANONICAL agentId from the resolved session, not the raw RPC input — `resolve()`
// accepts either an agentId or a bare sessionId, but `setActive`/`byAgent` only ever key on the
diff --git a/cli/src/lib/agentFrame.ts b/cli/src/lib/agentFrame.ts
index fd409e35c..fc0f17678 100644
--- a/cli/src/lib/agentFrame.ts
+++ b/cli/src/lib/agentFrame.ts
@@ -21,8 +21,17 @@
import { stat } from 'node:fs/promises'
import { agentProject, type AgentProject } from './agentProject.js'
import type { GridAssignment } from './gridAssignment.js'
+import type { GridWebSearchStatus } from './gridLaunch.js'
import { projectDisplayName, type RegisteredSession } from './registry.js'
+/**
+ * The grid block on the wire: where the agent's inference goes, and — when the daemon built the
+ * launch — whether it can search the web. `webSearch` is absent, not null, when there is nothing to
+ * say: a discovered grid agent, or a row from before the daemon recorded it. The app shows nothing
+ * for absent and for `on`; the two degraded words each get a sentence.
+ */
+export type GridFrameBlock = GridAssignment & { webSearch?: GridWebSearchStatus }
+
/**
* One agent as it travels to every client.
*
@@ -42,7 +51,7 @@ export type AgentFrame = {
terminal: { available: boolean; primary: string; runtimes: RegisteredSession['runtimes'] }
engine: RegisteredSession['engine']
selectedModel: string | null
- grid: GridAssignment | null
+ grid: GridFrameBlock | null
codexHome: string | null
project: AgentProject | null
}
@@ -83,8 +92,9 @@ export async function agentFrame(
// Where this agent's inference actually goes, so a client can tell which agents a newly picked
// grid has left behind. Read off the live process by discovery; carries no credential. Null is
// a real answer ("on no grid") and must be sent as one — omitting the key would make every push
- // indistinguishable from a daemon too old to know about grids.
- grid: s.grid ?? null,
+ // indistinguishable from a daemon too old to know about grids. The web-search status rides on
+ // the block — decided by the launch, kept on the row — so it is gone the moment the block is.
+ grid: s.grid ? { ...s.grid, ...(s.gridWebSearch ? { webSearch: s.gridWebSearch } : {}) } : null,
// The Codex profile folder this agent launched against, if one was chosen instead of the
// engine's own login. Codex only; null is a real answer ("uses ~/.codex") for the same reason
// `grid: null` is above.
diff --git a/cli/src/lib/createAgentPane.ts b/cli/src/lib/createAgentPane.ts
index 9d63830cc..aed02ab5b 100644
--- a/cli/src/lib/createAgentPane.ts
+++ b/cli/src/lib/createAgentPane.ts
@@ -13,7 +13,7 @@
*/
import { homedir } from 'node:os'
import type { AgentEngine } from '../engines/types.js'
-import type { GridLaunchOverride } from './gridLaunch.js'
+import type { GridLaunchRecord } from './gridLaunch.js'
import type { RegisteredSession } from './registry.js'
import type { TerminalBackend } from './terminalBackend.js'
import type { TerminalCreateResult, TmuxRuntimeRef } from './terminalTypes.js'
@@ -29,7 +29,7 @@ export interface CreateAgentPaneDeps {
primaryRuntimeKey?: string
cwd?: string | null
grid?: { baseUrl: string; model: string | null } | null
- gridLaunch?: GridLaunchOverride | null
+ gridLaunchRecord?: GridLaunchRecord | null
codexHome?: string | null
bypassPermission?: boolean
}) => RegisteredSession | null }
@@ -41,8 +41,9 @@ export interface CreateAgentPaneDeps {
argv: string[]
env?: Record<string, string>
grid?: { baseUrl: string; model: string | null } | null
- /** The grid launch behind `grid`, credential included — what restore/restart relaunch the pane with. */
- gridLaunch?: GridLaunchOverride | null
+ /** The grid launch behind `grid` (credential included — what restore/restart relaunch the pane with)
+ * and what building it decided about web search (what the app shows for this agent). */
+ gridLaunchRecord?: GridLaunchRecord | null
/** The CODEX_HOME folder this agent was launched against, if the caller chose one; codex only. */
codexHome?: string | null
maxAttempts?: number
@@ -76,7 +77,7 @@ export async function createAndRegisterPane(deps: CreateAgentPaneDeps): Promise<
primaryRuntimeKey: terminalRouteKey(spawned.runtime),
cwd: deps.cwd,
grid: deps.grid,
- gridLaunch: deps.gridLaunch,
+ gridLaunchRecord: deps.gridLaunchRecord,
codexHome: deps.codexHome,
bypassPermission: deps.bypassPermission,
})
diff --git a/cli/src/lib/gridAssignment.spec.ts b/cli/src/lib/gridAssignment.spec.ts
index 4eadb1ad5..b5bb04546 100644
--- a/cli/src/lib/gridAssignment.spec.ts
+++ b/cli/src/lib/gridAssignment.spec.ts
@@ -33,7 +33,7 @@ describe('classifyGridAssignment', () => {
// Pi and OpenCode keep their endpoint in a file rather than in the process, so they
// round-trip through their own probes below — this one only covers what a process carries.
if (engine === 'pi' || engine === 'opencode') continue
- const built = buildGridEngineLaunch(engine, OVERRIDE)
+ const built = buildGridEngineLaunch(engine, OVERRIDE, { hermesSystemManaged: false })
expect(built.ok).toBe(true)
if (!built.ok) continue
const assignment = classifyGridAssignment(engine, built.launch.env, built.launch.args.join(' '))
@@ -46,7 +46,7 @@ describe('classifyGridAssignment', () => {
it('never carries the credential out of the process', () => {
for (const engine of gridCapableEngines()) {
if (engine === 'pi' || engine === 'opencode') continue
- const built = buildGridEngineLaunch(engine, OVERRIDE)
+ const built = buildGridEngineLaunch(engine, OVERRIDE, { hermesSystemManaged: false })
if (!built.ok) continue
const assignment = classifyGridAssignment(engine, built.launch.env, built.launch.args.join(' '))
expect(JSON.stringify(assignment), engine).not.toContain('gridkey-secret')
@@ -111,7 +111,7 @@ describe('Pi, whose endpoint lives in a file', () => {
/** Writes the launch's own config files where the probe will look for them. */
function materialize(): { dir: string; args: string } {
- const built = buildGridEngineLaunch('pi', OVERRIDE)
+ const built = buildGridEngineLaunch('pi', OVERRIDE, { hermesSystemManaged: false })
if (!built.ok) throw new Error(built.detail)
const dir = mkdtempSync(join(tmpdir(), 'pi-grid-'))
dirs.push(dir)
@@ -217,7 +217,7 @@ describe('readOpencodeGridAssignment', () => {
// The strongest form of this test: build the real launch, write its real files where the probe
// will look, and read them back. A spec that hand-writes the config proves only that two
// hand-written shapes agree.
- const built = buildGridEngineLaunch('opencode', OVERRIDE)
+ const built = buildGridEngineLaunch('opencode', OVERRIDE, { hermesSystemManaged: false })
if (!built.ok) throw new Error(built.detail)
const dir = mkdtempSync(join(tmpdir(), 'opencode-grid-'))
dirs.push(dir)
@@ -318,7 +318,7 @@ describe('web tools do not disturb the probe', () => {
})
const classify = (engine: AgentEngine, override: GridLaunchOverride) => {
- const built = buildGridEngineLaunch(engine, override)
+ const built = buildGridEngineLaunch(engine, override, { hermesSystemManaged: false })
if (!built.ok) throw new Error(`${engine}: ${built.detail}`)
return classifyGridAssignment(engine, built.launch.env, built.launch.args.join(' '))
}
@@ -342,7 +342,7 @@ describe('web tools do not disturb the probe', () => {
})
it("reads OpenCode's config back with the server declared beside the provider", async () => {
- const built = buildGridEngineLaunch('opencode', WITH_MCP)
+ const built = buildGridEngineLaunch('opencode', WITH_MCP, { hermesSystemManaged: false })
if (!built.ok) throw new Error(built.detail)
const dir = mkdtempSync(join(tmpdir(), 'opencode-grid-mcp-'))
dirs.push(dir)
diff --git a/cli/src/lib/gridLaunch.spec.ts b/cli/src/lib/gridLaunch.spec.ts
index 918f0782c..1788a3ef9 100644
--- a/cli/src/lib/gridLaunch.spec.ts
+++ b/cli/src/lib/gridLaunch.spec.ts
@@ -9,6 +9,7 @@ import {
gridEnvVarNames,
parseGridLaunchOverride,
relayBaseUrl,
+ type GridLaunchMachine,
type GridLaunchOverride,
} from './gridLaunch.js'
import { ENGINES, type AgentEngine } from '../engines/types.js'
@@ -29,9 +30,11 @@ const WITH_MODEL: GridLaunchOverride = { ...WIRE, model: 'GLM-4.7-Flash' }
/** The control plane's web-tools mount, trailing slash and all — see `GridLaunchOverride.mcpUrl`. */
const MCP_URL = 'https://api-grid.autonomous.ai/v1/grid/web-mcp/'
const WITH_MCP: GridLaunchOverride = { ...WITH_MODEL, mcpUrl: MCP_URL }
+/** The ordinary machine: nobody has pinned Hermes settings in /etc/hermes. */
+const PLAIN_MACHINE: GridLaunchMachine = { hermesSystemManaged: false }
-function launchOf(engine: AgentEngine, override = WITH_MODEL) {
- const built = buildGridEngineLaunch(engine, override)
+function launchOf(engine: AgentEngine, override = WITH_MODEL, machine = PLAIN_MACHINE) {
+ const built = buildGridEngineLaunch(engine, override, machine)
if (!built.ok) throw new Error(`${engine} was refused: ${built.detail}`)
return built.launch
}
@@ -102,6 +105,8 @@ describe('the launch each engine gets', () => {
},
// The built-in web tools no grid can run — see "takes Claude Code's built-in web tools away".
args: ['--disallowedTools=WebSearch,WebFetch'],
+ // No MCP url in this override, so no web tools — and the app is told so.
+ webSearch: 'unavailable',
})
// Setting it too makes Claude Code warn that auth may not work, and it decides nothing.
expect(launchOf('claude').env).not.toHaveProperty('ANTHROPIC_API_KEY')
@@ -242,7 +247,7 @@ describe('the launch each engine gets', () => {
})
it('refuses Copilot without a model rather than letting it fail inside the app', () => {
- const built = buildGridEngineLaunch('copilot', OVERRIDE)
+ const built = buildGridEngineLaunch('copilot', OVERRIDE, PLAIN_MACHINE)
expect(built).toMatchObject({ ok: false, error: 'GRID_MODEL_REQUIRED' })
})
@@ -266,7 +271,7 @@ describe('the engines that cannot', () => {
const refused = ENGINES.filter((engine) => !capable.has(engine))
expect(refused.length).toBeGreaterThan(0)
for (const engine of refused) {
- const built = buildGridEngineLaunch(engine, OVERRIDE)
+ const built = buildGridEngineLaunch(engine, OVERRIDE, PLAIN_MACHINE)
expect(built.ok).toBe(false)
if (built.ok) continue
expect(built.error).toBe('GRID_ENGINE_UNSUPPORTED')
@@ -285,11 +290,26 @@ describe('the engines that cannot', () => {
describe('describeGridLaunch', () => {
it('names the grid and the model, and never the key', () => {
- const line = describeGridLaunch('claude', WITH_MODEL)
+ const line = describeGridLaunch('claude', WITH_MODEL, 'on')
expect(line).toContain('autonomous.ai')
expect(line).toContain('GLM-4.7-Flash')
expect(line).not.toContain(WIRE.apiKey)
- expect(describeGridLaunch('claude', OVERRIDE)).not.toContain(WIRE.apiKey)
+ expect(describeGridLaunch('claude', OVERRIDE, 'on')).not.toContain(WIRE.apiKey)
+ })
+
+ it('names the web-search status — the daemon log is where a degraded launch says why', () => {
+ expect(describeGridLaunch('claude', WITH_MCP, 'on')).toContain('web search on')
+ expect(describeGridLaunch('claude', WITH_MODEL, 'unavailable')).toContain('web search unavailable')
+ expect(describeGridLaunch('pi', WITH_MCP, 'unsupported')).toContain('web search unsupported')
+ // The url is the control plane's address, not a secret — but it is also not the log's business.
+ expect(describeGridLaunch('claude', WITH_MCP, 'on')).not.toContain(MCP_URL)
+ })
+
+ it('says why, for the two answers this module decides itself', () => {
+ expect(describeGridLaunch('hermes', WITH_MCP, 'unsupported')).toContain('/etc/hermes pins')
+ expect(describeGridLaunch('pi', WITH_MCP, 'unsupported')).toContain('no MCP client')
+ // `unavailable` was decided — and its reason logged — by the url resolver, not here.
+ expect(describeGridLaunch('claude', WITH_MODEL, 'unavailable')).toMatch(/web search unavailable$/)
})
})
@@ -343,14 +363,14 @@ describe('gridConflictingEnvToClear', () => {
apiKey: 'RELAY-KEY',
}
const clearedFor = (engine: AgentEngine, model?: string): string[] => {
- const built = buildGridEngineLaunch(engine, model ? { ...override, model } : override)
+ const built = buildGridEngineLaunch(engine, model ? { ...override, model } : override, PLAIN_MACHINE)
if (!built.ok) throw new Error(`${engine} refused: ${JSON.stringify(built)}`)
return gridConflictingEnvToClear(built.launch)
}
it('never clears a variable the same launch sets', () => {
for (const engine of ['claude', 'codex', 'opencode', 'hermes', 'grok', 'copilot', 'pi'] as const) {
- const built = buildGridEngineLaunch(engine, { ...override, model: 'a-model' })
+ const built = buildGridEngineLaunch(engine, { ...override, model: 'a-model' }, PLAIN_MACHINE)
if (!built.ok) throw new Error(`${engine} refused`)
const set = new Set(Object.keys(built.launch.env))
if (built.launch.configDir) set.add(built.launch.configDir.envVar)
@@ -400,7 +420,7 @@ describe('opencode declares the grid as a provider', () => {
apiKey: 'RELAY-KEY',
}
const launch = (model?: string) => {
- const built = buildGridEngineLaunch('opencode', model ? { ...base, model } : base)
+ const built = buildGridEngineLaunch('opencode', model ? { ...base, model } : base, PLAIN_MACHINE)
if (!built.ok) throw new Error('opencode refused')
return built.launch
}
@@ -665,3 +685,69 @@ describe('web tools (grid ADR 0041)', () => {
expect(launchOf('hermes', WITH_MODEL).env.GRID_API_KEY).toBeUndefined()
})
})
+
+describe('web search status — what the app is told about the launch it got', () => {
+ // Every engine with MCP wiring, which is every grid-capable one but Pi.
+ const WIRED: AgentEngine[] = ['claude', 'codex', 'opencode', 'hermes', 'grok', 'copilot']
+
+ it('is on when the MCP url is present and the engine wired it', () => {
+ for (const engine of WIRED) expect(launchOf(engine, WITH_MCP).webSearch, engine).toBe('on')
+ })
+
+ it('is unavailable when the url is absent — the grid could not be asked for it', () => {
+ for (const engine of WIRED) expect(launchOf(engine, WITH_MODEL).webSearch, engine).toBe('unavailable')
+ })
+
+ it('is unsupported for Pi, which has no MCP client, url or no url', () => {
+ expect(launchOf('pi', WITH_MCP).webSearch).toBe('unsupported')
+ expect(launchOf('pi', WITH_MODEL).webSearch).toBe('unsupported')
+ })
+
+ it('is unsupported for Hermes on a machine whose settings are pinned in /etc/hermes, and writes no overlay there', () => {
+ // The overlay REPLACES the system scope rather than adding to it, so on such a machine it is
+ // dropped — a decision the builder makes, so every caller (create, retarget, restore) agrees.
+ const launch = launchOf('hermes', WITH_MCP, { hermesSystemManaged: true })
+ expect(launch.webSearch).toBe('unsupported')
+ expect(launch.configDir).toBeUndefined()
+ // The variable exists only to be referenced by the overlay, so it goes with it.
+ expect(launch.env.GRID_API_KEY).toBeUndefined()
+ expect(launch.env.HERMES_MANAGED_DIR).toBeUndefined()
+ })
+
+ it('takes nothing else from Hermes on such a machine — inference is still pointed at the grid', () => {
+ const pinned = launchOf('hermes', WITH_MCP, { hermesSystemManaged: true })
+ const plain = launchOf('hermes', WITH_MCP)
+ expect(pinned.env).toMatchObject({ OPENAI_BASE_URL: plain.env.OPENAI_BASE_URL, OPENAI_API_KEY: plain.env.OPENAI_API_KEY })
+ expect(pinned.args).toEqual(plain.args)
+ })
+
+ it('is unsupported for Hermes on such a machine even with no url — the pin is the fact that lasts', () => {
+ expect(launchOf('hermes', WITH_MODEL, { hermesSystemManaged: true }).webSearch).toBe('unsupported')
+ })
+
+ it('leaves every other engine alone on such a machine', () => {
+ for (const engine of WIRED.filter((e) => e !== 'hermes')) {
+ expect(launchOf(engine, WITH_MCP, { hermesSystemManaged: true }).webSearch, engine).toBe('on')
+ }
+ })
+
+ it('says on exactly when the launch it describes names the server — for every engine, both machines', () => {
+ // "The engine wired it" is not taken on trust from the contract that reports it: the launch
+ // either carries the `harness` server (in argv or in a file it writes) or it does not, and the
+ // status must agree with that. A future contract that took a url and forgot to wire it, or
+ // wired it and reported otherwise, fails here.
+ const names = (launch: ReturnType<typeof launchOf>): string =>
+ [...launch.args, ...(launch.configDir?.files.map((f) => f.content) ?? [])].join('\n')
+ for (const machine of [PLAIN_MACHINE, { hermesSystemManaged: true }]) {
+ for (const engine of gridCapableEngines()) {
+ for (const override of [WITH_MCP, WITH_MODEL]) {
+ const built = buildGridEngineLaunch(engine, override, machine)
+ if (!built.ok) continue // copilot without a model — refused, nothing to describe
+ const wired = names(built.launch).includes('harness')
+ expect(built.launch.webSearch === 'on', `${engine} · mcpUrl ${!!override.mcpUrl} · pinned ${machine.hermesSystemManaged}`)
+ .toBe(wired)
+ }
+ }
+ }
+ })
+})
diff --git a/cli/src/lib/gridLaunch.ts b/cli/src/lib/gridLaunch.ts
index 9e1097385..6c6e6cfc4 100644
--- a/cli/src/lib/gridLaunch.ts
+++ b/cli/src/lib/gridLaunch.ts
@@ -57,6 +57,7 @@ import {
grokGridConfig,
HERMES_MANAGED_CONFIG_FILE,
HERMES_MANAGED_DIR_VAR,
+ HERMES_SYSTEM_MANAGED_DIR,
hermesManagedConfig,
mcpAuthorizationHeader,
} from './gridWebMcp.js'
@@ -333,12 +334,58 @@ export interface GridConfigFile {
content: string
}
+/**
+ * Whether the agent this launch produces can search the web, in the words the app shows.
+ *
+ * * `on` — the MCP url was present and the engine's contract wired the server in.
+ * * `unavailable` — no url reached the launch: the grid could not be asked for one (an outdated or
+ * missing `grid` CLI, no sign-in, an unknown grid — `gridMcpUrl.ts` logs which). Inference still
+ * goes to the grid; asking again later can fix it.
+ * * `unsupported` — the engine cannot take the server on this machine at all: Pi has no MCP client,
+ * and Hermes on a machine whose settings are pinned in [HERMES_SYSTEM_MANAGED_DIR] cannot be handed
+ * the overlay without replacing them. Nothing about the grid changes this.
+ *
+ * Decided HERE, by the same code that decides whether the server is wired, so the two cannot
+ * disagree — and stored with the launch rather than re-derived, so a reconnect or a restart reports
+ * what the launch actually did. The app reads it as `grid.webSearch` on every agent frame.
+ */
+export type GridWebSearchStatus = 'on' | 'unavailable' | 'unsupported'
+
+/**
+ * A grid launch as the registry keeps it: the override to repeat it with, and what building it
+ * decided about web search. One object so the two are written and cleared together — a status
+ * without its launch, or a launch without its status, is a row the app would read wrongly.
+ */
+export interface GridLaunchRecord {
+ override: GridLaunchOverride
+ webSearch: GridWebSearchStatus
+}
+
+/**
+ * Facts about THIS machine a contract cannot read for itself.
+ *
+ * A contract is pure — the module comment on [userGrokHome] says why: one that stats the filesystem
+ * answers differently on two machines, and its spec would follow. So the caller reads the machine
+ * and hands the answer in, and the contract decides from it. What it decides stays here, where every
+ * caller (create, retarget, restore) gets the same answer from the same code.
+ */
+export interface GridLaunchMachine {
+ /**
+ * Whether an administrator pinned Hermes settings in [HERMES_SYSTEM_MANAGED_DIR]. Hermes's web
+ * tools ride a managed-scope overlay that REPLACES that directory rather than adding to it, so on
+ * such a machine the overlay is dropped and the agent launches without web tools.
+ */
+ hermesSystemManaged: boolean
+}
+
/** How one engine is launched against a grid. */
export interface GridEngineLaunch {
/** Layered over the engine's inherited environment. This is where the key goes, always. */
env: Record<string, string>
/** Appended to the engine's argv. Never carries the key — `ps` is world-readable. */
args: string[]
+ /** What this launch gives the agent by way of web search. See [GridWebSearchStatus]. */
+ webSearch: GridWebSearchStatus
/**
* For an engine that reads its provider out of a config directory rather than an environment
* variable: files the daemon writes into a directory IT owns, and the variable that points the
@@ -372,7 +419,7 @@ export interface GridEngineLaunch {
}
interface GridEngineContract {
- build: (override: GridLaunchOverride) => GridEngineLaunch
+ build: (override: GridLaunchOverride, machine: GridLaunchMachine) => GridEngineLaunch
/** The engine cannot start against a grid without being told which model to ask for. */
requiresModel?: boolean
}
@@ -388,6 +435,13 @@ const GRID_KEY_VAR = 'GRID_API_KEY'
/** 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'
+
/**
* Every variable any contract in this file uses to point an engine somewhere.
*
@@ -441,7 +495,7 @@ export const GRID_CONFLICTING_ENV_VARS: readonly string[] = [
* Set-then-unset would be a bug, so the two sets are computed from one another rather than listed
* twice — a contract that gains a variable stops clearing it in the same edit.
*/
-export function gridConflictingEnvToClear(launch: GridEngineLaunch): string[] {
+export function gridConflictingEnvToClear(launch: Pick<GridEngineLaunch, 'env' | 'configDir'>): string[] {
const provided = new Set(Object.keys(launch.env))
if (launch.configDir) provided.add(launch.configDir.envVar)
return GRID_CONFLICTING_ENV_VARS.filter((name) => !provided.has(name))
@@ -527,6 +581,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
CLAUDE_DISALLOW_WEB_TOOLS_ARG,
...(override.mcpUrl ? ['--mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR)] : []),
],
+ webSearch: webSearchWhenWired(override),
}),
},
@@ -557,6 +612,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
...(override.mcpUrl ? codexMcpArgs(override.mcpUrl) : []),
...(override.model ? ['-m', override.model] : []),
],
+ webSearch: webSearchWhenWired(override),
}),
},
@@ -604,6 +660,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
content: opencodeGridConfig(provider, override, model),
}],
},
+ webSearch: webSearchWhenWired(override),
}
},
},
@@ -634,31 +691,43 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
// 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) => ({
- 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.
- ...(override.mcpUrl ? { [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`.
- ...(override.mcpUrl
- ? {
- configDir: {
- envVar: HERMES_MANAGED_DIR_VAR,
- files: [{
- name: HERMES_MANAGED_CONFIG_FILE,
- content: hermesManagedConfig(override.mcpUrl, GRID_KEY_VAR),
- }],
- },
- }
- : {}),
- }),
+ 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
@@ -730,6 +799,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
}],
links: GROK_GRID_HOME_LINKS.map((name) => ({ name, target: join(userGrokHome(), name) })),
},
+ webSearch: webSearchWhenWired(override),
}
},
},
@@ -759,6 +829,8 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
{ name: 'settings.json', content: piSettingsJson(userPiSkillsDir()) },
],
},
+ // Pi has no MCP client, so there is nothing to hand the server to — with or without a url.
+ webSearch: 'unsupported',
}
},
},
@@ -784,6 +856,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
args: override.mcpUrl
? ['--additional-mcp-config', mcpServersConfig(override.mcpUrl, GRID_KEY_VAR)]
: [],
+ webSearch: webSearchWhenWired(override),
}),
},
}
@@ -816,8 +889,18 @@ export type GridLaunchResult =
| { ok: true; launch: GridEngineLaunch }
| { ok: false; error: string; detail: string }
-/** How `engine` must be launched to reach `override`, or why it cannot be. */
-export function buildGridEngineLaunch(engine: AgentEngine, override: GridLaunchOverride): GridLaunchResult {
+/**
+ * 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'
@@ -836,13 +919,36 @@ export function buildGridEngineLaunch(engine: AgentEngine, override: GridLaunchO
+ `Pick one for ${override.networkName} and try again.`,
}
}
- return { ok: true, launch: contract.build(override) }
+ return { ok: true, launch: contract.build(override, machine) }
+}
+
+/**
+ * Why a launch has no web search, in the daemon log's words — for the two answers this module
+ * decides itself. `unavailable` is decided elsewhere (`gridMcpUrl.ts`), which logs its own reason
+ * the moment it gives up, so nothing is repeated here.
+ */
+function webSearchReason(engine: AgentEngine, webSearch: GridWebSearchStatus): string | null {
+ if (webSearch !== 'unsupported') return null
+ if (engine === 'pi') return 'Pi has no MCP client'
+ if (engine === 'hermes') {
+ return `${HERMES_SYSTEM_MANAGED_DIR} pins this machine's Hermes settings, and the overlay carrying `
+ + 'the web tools would replace it'
+ }
+ return null
}
-/** One log line naming where an agent was sent — grid, model, engine. Never the key. */
-export function describeGridLaunch(engine: AgentEngine, override: GridLaunchOverride): string {
+/** One log line naming where an agent was sent — grid, model, engine, and whether it got web
+ * search (with the reason when this module is the one that took it away). Never the key, never
+ * the MCP url. */
+export function describeGridLaunch(
+ engine: AgentEngine,
+ override: GridLaunchOverride,
+ webSearch: GridWebSearchStatus,
+): string {
+ const reason = webSearchReason(engine, webSearch)
return `[grid] ${engine} -> ${override.networkName} (${override.networkId})`
- + ` · ${override.model ?? 'model chosen by the engine'}`
+ + ` · ${override.model ?? 'model chosen by the engine'} · web search ${webSearch}`
+ + (reason ? ` (${reason})` : '')
}
/** A placeholder override, used only to ask a contract which variables it sets. Never launched. */
@@ -869,7 +975,9 @@ const PROBE_OVERRIDE: GridLaunchOverride = {
* Empty for an engine that has no contract — there is nothing to clear because nothing was set.
*/
export function gridEnvVarNames(engine: AgentEngine): string[] {
- const built = buildGridEngineLaunch(engine, PROBE_OVERRIDE)
+ // 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) names.push(built.launch.configDir.envVar)
diff --git a/cli/src/lib/gridWebSearchFrame.spec.ts b/cli/src/lib/gridWebSearchFrame.spec.ts
new file mode 100644
index 000000000..fc15363fb
--- /dev/null
+++ b/cli/src/lib/gridWebSearchFrame.spec.ts
@@ -0,0 +1,165 @@
+/**
+ * The web-search status, end to end on the daemon side: the plan-driven fake `grid` answers (or
+ * refuses) `mcp config`, the launch is built from what it said, the registry keeps what the launch
+ * decided, and the per-agent frame the app rebuilds itself from carries it — or, once the agent is
+ * back on its own login, carries no grid block at all.
+ *
+ * One spec across four modules on purpose. Each has its own unit spec; what none of them can say is
+ * that the value the app reads is the value the launch decided, with no hand-off in between that
+ * forgets it (the registry rebuilds its row from an explicit field list on load AND on the first
+ * hook bind, and `agentFrame` picks its fields explicitly — three places a field can silently drop).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fakeGridAnswers, installFakeGrid, type FakeGrid, type FakeGridPlan } from './__fixtures__/fakeGrid.js'
+import { agentFrame } from './agentFrame.js'
+import { buildLaunchOverrides, type LaunchOverridesDeps } from './launchOverrides.js'
+import { clearGridMcpUrlCache } from './gridMcpUrl.js'
+import { resolveGridTarget } from './gridModels.js'
+
+const { gridName: GRID, baseUrl: BASE_URL, mcpUrl: MCP_URL, plan } = fakeGridAnswers()
+
+let fake: FakeGrid | null = null
+let dataDir = ''
+
+function install(overrides: FakeGridPlan = {}): FakeGrid {
+ fake = installFakeGrid({ ...plan, ...overrides })
+ return fake
+}
+
+/** The registry, fresh, on its own state directory — the same way `registry.spec.ts` loads it. */
+async function loadRegistry() {
+ vi.resetModules()
+ process.env.ADAPTER_DATA_DIR = dataDir
+ process.env.CLAUDE_PROJECTS_DIR = dataDir
+ process.env.CODEX_HOME = dataDir
+ process.env.CURSOR_HOME = dataDir
+ const { registry } = await import('./registry.js')
+ registry.load()
+ return registry
+}
+
+const DEPS: LaunchOverridesDeps = {
+ machine: () => ({ hermesSystemManaged: false }),
+ writeGridConfigDir: async (key) => `/state/grid-engine-config/${key}`,
+ tmuxSupportsSessionEnv: async () => true,
+ installCodexHooks: () => {},
+}
+
+const IDENTITY = { pid: 4242, executable: 'claude', startMarker: 'boot-1' }
+
+/**
+ * What `agent_retarget` does with a resolved target, minus the pane: build the launch, and keep it —
+ * status included — on the row the frame is built from.
+ */
+async function retargetOntoGrid(registry: Awaited<ReturnType<typeof loadRegistry>>, agentId: string, model: string) {
+ const target = await resolveGridTarget(GRID, model)
+ if (!target) throw new Error('the fake grid did not resolve')
+ const built = await buildLaunchOverrides(DEPS, 'claude', { gridLaunch: target }, agentId)
+ if (!built.ok || !built.overrides.gridLaunchRecord) throw new Error(built.ok ? 'no grid launch was built' : built.detail)
+ registry.updateProcessIdentity(agentId, IDENTITY, null, { baseUrl: BASE_URL, model })
+ registry.setGridLaunch(agentId, built.overrides.gridLaunchRecord)
+ return built.overrides.gridLaunchRecord.webSearch
+}
+
+beforeEach(() => {
+ dataDir = mkdtempSync(join(tmpdir(), 'grid-websearch-frame-'))
+})
+
+afterEach(() => {
+ fake?.dispose()
+ fake = null
+ clearGridMcpUrlCache()
+ vi.restoreAllMocks()
+ rmSync(dataDir, { recursive: true, force: true })
+ delete process.env.ADAPTER_DATA_DIR
+ delete process.env.CLAUDE_PROJECTS_DIR
+ delete process.env.CODEX_HOME
+ delete process.env.CURSOR_HOME
+})
+
+describe('the web-search status on the per-agent frame', () => {
+ it('carries "unavailable" when the `grid` on this machine is too old for `mcp config`', async () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => {})
+ install({ mcp: { exit: 2, stderr: "grid: error: invalid choice: 'mcp'\n" } })
+ const registry = await loadRegistry()
+ const row = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/demo' })!
+
+ expect(await retargetOntoGrid(registry, row.agentId, 'GLM-4.7-Flash')).toBe('unavailable')
+
+ const frame = await agentFrame(registry.byAgent(row.agentId)!, { selectedModel: null, terminalAvailable: true })
+ expect(frame.grid).toEqual({ baseUrl: BASE_URL, model: 'GLM-4.7-Flash', webSearch: 'unavailable' })
+ })
+
+ it('carries "on" when the config was obtained and the engine wired it', async () => {
+ install()
+ const registry = await loadRegistry()
+ const row = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/demo' })!
+
+ expect(await retargetOntoGrid(registry, row.agentId, 'GLM-4.7-Flash')).toBe('on')
+
+ const frame = await agentFrame(registry.byAgent(row.agentId)!, { selectedModel: null, terminalAvailable: true })
+ expect(frame.grid).toEqual({ baseUrl: BASE_URL, model: 'GLM-4.7-Flash', webSearch: 'on' })
+ // The url reached the launch and the frame never carries it — nor the token behind it.
+ expect(JSON.stringify(frame)).not.toContain(MCP_URL)
+ expect(JSON.stringify(frame)).not.toContain('apiKey')
+ })
+
+ it('carries no grid block, and so no status, once the agent is back on its own login', async () => {
+ install()
+ const registry = await loadRegistry()
+ const row = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/demo' })!
+ await retargetOntoGrid(registry, row.agentId, 'GLM-4.7-Flash')
+
+ // The move home: the respawned process reads as "on no grid", and the launch is cleared.
+ registry.updateProcessIdentity(row.agentId, { ...IDENTITY, startMarker: 'boot-2' }, null, null)
+ registry.setGridLaunch(row.agentId, null)
+
+ const frame = await agentFrame(registry.byAgent(row.agentId)!, { selectedModel: null, terminalAvailable: true })
+ expect(frame).toHaveProperty('grid', null)
+ expect(JSON.stringify(frame)).not.toContain('webSearch')
+ })
+
+ it('survives a daemon restart — the status is on the row, not in memory', async () => {
+ install()
+ let registry = await loadRegistry()
+ const row = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/demo' })!
+ await retargetOntoGrid(registry, row.agentId, 'GLM-4.7-Flash')
+
+ registry = await loadRegistry()
+ const frame = await agentFrame(registry.byAgent(row.agentId)!, { selectedModel: null, terminalAvailable: true })
+ expect(frame.grid).toMatchObject({ webSearch: 'on' })
+ })
+
+ it('survives the first hook bind, which rebuilds the row', async () => {
+ install()
+ const registry = await loadRegistry()
+ const row = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%1' }], cwd: '/tmp/demo' })!
+ await retargetOntoGrid(registry, row.agentId, 'GLM-4.7-Flash')
+
+ // The engine's SessionStart hook: a real transcript, bound onto the pane the launch opened.
+ const transcriptPath = join(dataDir, 'session-1.jsonl')
+ writeFileSync(transcriptPath, '{}\n')
+ const bound = registry.register({ sessionId: 'session-1', transcriptPath, tmuxPane: '%1', cwd: '/tmp/demo' })
+ expect(bound?.entry.agentId).toBe(row.agentId)
+ const frame = await agentFrame(bound!.entry, { selectedModel: null, terminalAvailable: true })
+ expect(frame.grid).toMatchObject({ webSearch: 'on' })
+ })
+
+ it('says nothing about web search for a grid agent the daemon merely discovered', async () => {
+ // Someone ran `ANTHROPIC_BASE_URL=… claude` by hand: the daemon sees the grid on the process but
+ // built no launch, so it has no status to report — and must not invent one.
+ const registry = await loadRegistry()
+ const opened = registry.openProcessAgent({
+ engine: 'claude',
+ processIdentity: IDENTITY,
+ runtimes: [{ backend: 'tmux', paneId: '%2' }],
+ cwd: '/tmp/demo',
+ grid: { baseUrl: BASE_URL, model: null },
+ })
+ const frame = await agentFrame(opened!.entry, { selectedModel: null, terminalAvailable: true })
+ expect(frame.grid).toEqual({ baseUrl: BASE_URL, model: null })
+ })
+})
diff --git a/cli/src/lib/launchOverrides.spec.ts b/cli/src/lib/launchOverrides.spec.ts
index b81629958..7327c24fd 100644
--- a/cli/src/lib/launchOverrides.spec.ts
+++ b/cli/src/lib/launchOverrides.spec.ts
@@ -13,7 +13,7 @@ const GRID: GridLaunchOverride = {
function deps(overrides: Partial<LaunchOverridesDeps> = {}) {
const calls: string[] = []
const d: LaunchOverridesDeps = {
- configDirFor: (_engine, launch) => launch.configDir,
+ machine: () => ({ hermesSystemManaged: false }),
writeGridConfigDir: async (key) => { calls.push(`writeConfig:${key}`); return `/state/grid-engine-config/${key}` },
tmuxSupportsSessionEnv: async () => true,
installCodexHooks: (home) => { calls.push(`hooks:${home}`) },
@@ -117,3 +117,37 @@ describe('buildLaunchOverrides — coming back off a grid', () => {
expect(result.overrides.env.ANTHROPIC_MODEL).toBe('gpt-5')
})
})
+
+describe('buildLaunchOverrides — what the app is told about web search', () => {
+ const WITH_MCP: GridLaunchOverride = { ...GRID, mcpUrl: 'https://api-grid.example/v1/grid/web-mcp/' }
+
+ it('reports on when the launch wired the server', async () => {
+ const result = await buildLaunchOverrides(deps().d, 'claude', { gridLaunch: WITH_MCP }, 'a')
+ expect(result).toMatchObject({ ok: true, overrides: { gridLaunchRecord: { override: WITH_MCP, webSearch: 'on' } } })
+ })
+
+ it('reports unavailable when the persisted launch carries no url', async () => {
+ const result = await buildLaunchOverrides(deps().d, 'claude', { gridLaunch: GRID }, 'a')
+ expect(result).toMatchObject({ ok: true, overrides: { gridLaunchRecord: { override: GRID, webSearch: 'unavailable' } } })
+ })
+
+ it('reports unsupported for Hermes on a pinned machine, and writes nothing there', async () => {
+ // The machine fact is read through the dependency and handed to the builder; the builder drops
+ // the overlay, so there is no config directory to write — the write is what used to be pruned
+ // beside the builder, and is now simply never asked for.
+ const { d, calls } = deps({ machine: () => ({ hermesSystemManaged: true }) })
+ const result = await buildLaunchOverrides(d, 'hermes', { gridLaunch: WITH_MCP }, 'agent-h')
+ expect(result).toMatchObject({ ok: true, overrides: { gridLaunchRecord: { override: WITH_MCP, webSearch: 'unsupported' } } })
+ if (!result.ok) return
+ expect(calls).toEqual([])
+ expect(result.overrides.env).not.toHaveProperty('HERMES_MANAGED_DIR')
+ expect(result.overrides.clearEnv).toContain('HERMES_MANAGED_DIR')
+ })
+
+ it('says nothing about web search for a launch that is not onto a grid', async () => {
+ const own = await buildLaunchOverrides(deps().d, 'claude', { gridLaunch: null }, 'a')
+ expect(own.ok && own.overrides).not.toHaveProperty('gridLaunchRecord')
+ const profile = await buildLaunchOverrides(deps().d, 'codex', { codexHome: '/Users/x/.codex-work' }, 'a')
+ expect(profile.ok && profile.overrides).not.toHaveProperty('gridLaunchRecord')
+ })
+})
diff --git a/cli/src/lib/launchOverrides.ts b/cli/src/lib/launchOverrides.ts
index ff622b234..54f94a2b5 100644
--- a/cli/src/lib/launchOverrides.ts
+++ b/cli/src/lib/launchOverrides.ts
@@ -19,7 +19,9 @@ import {
buildGridEngineLaunch,
gridConflictingEnvToClear,
type GridEngineLaunch,
+ type GridLaunchMachine,
type GridLaunchOverride,
+ type GridLaunchRecord,
} from './gridLaunch.js'
import { TMUX_SESSION_ENV_MIN } from './tmuxVersion.js'
@@ -30,6 +32,13 @@ export interface LaunchOverrides {
extraArgs: string[]
/** Vendor credentials the launch must hide from the engine — see `gridConflictingEnvToClear`. */
clearEnv: string[]
+ /**
+ * The grid launch this was built from and what building it decided about web search — present
+ * only when this IS a grid launch. Exactly what `registry.setGridLaunch` keeps, so the caller
+ * stores it as-is and cannot pair a status with the wrong override. A launch back onto the
+ * engine's own login has no such thing to say.
+ */
+ gridLaunchRecord?: GridLaunchRecord
}
export type LaunchOverridesResult =
@@ -37,8 +46,8 @@ export type LaunchOverridesResult =
| { ok: false; error: string; detail: string }
export interface LaunchOverridesDeps {
- /** The config directory this MACHINE can give the launch, or none — cli.ts prunes Hermes's. */
- configDirFor: (engine: AgentEngine, launch: GridEngineLaunch) => GridEngineLaunch['configDir']
+ /** The facts about THIS machine a contract needs and cannot read for itself — see `GridLaunchMachine`. */
+ machine: () => GridLaunchMachine
writeGridConfigDir: (
key: string,
files: NonNullable<GridEngineLaunch['configDir']>['files'],
@@ -81,12 +90,12 @@ const noOverrides = (): LaunchOverrides => ({ env: {}, extraArgs: [], clearEnv:
* builds — config directory included — once it holds the pane).
*/
export async function validateLaunchOverrides(
- deps: Pick<LaunchOverridesDeps, 'tmuxSupportsSessionEnv'>,
+ deps: Pick<LaunchOverridesDeps, 'tmuxSupportsSessionEnv' | 'machine'>,
engine: AgentEngine,
source: LaunchSource,
): Promise<{ ok: true } | { ok: false; error: string; detail: string }> {
if (!source.gridLaunch) return { ok: true }
- const built = buildGridEngineLaunch(engine, source.gridLaunch)
+ const built = buildGridEngineLaunch(engine, source.gridLaunch, deps.machine())
if (!built.ok) return { ok: false, error: built.error, detail: built.detail }
// Only a launch that SETS variables needs the tmux that can set them.
if (!(await deps.tmuxSupportsSessionEnv())) {
@@ -127,12 +136,11 @@ export async function buildLaunchOverrides(
}
}
if (source.gridLaunch) {
- const built = buildGridEngineLaunch(engine, source.gridLaunch)
+ const built = buildGridEngineLaunch(engine, source.gridLaunch, deps.machine())
if (!built.ok) return { ok: false, error: built.error, detail: built.detail }
const env: Record<string, string> = { ...built.launch.env }
- const configDir = deps.configDirFor(engine, built.launch)
- if (configDir) {
- const { envVar, files, pointAt, links } = configDir
+ if (built.launch.configDir) {
+ const { envVar, files, pointAt, links } = built.launch.configDir
try {
const dir = await deps.writeGridConfigDir(configKey, files, links ?? [])
// Pi is handed the directory; OpenCode's OPENCODE_CONFIG wants the file inside it.
@@ -144,7 +152,15 @@ export async function buildLaunchOverrides(
}
// Derived from what this launch actually provides (the config-dir variable included), so an
// inherited vendor key never outranks the grid the engine was handed.
- return { ok: true, overrides: { env, extraArgs: [...built.launch.args], clearEnv: gridConflictingEnvToClear({ env, args: [] }) } }
+ return {
+ ok: true,
+ overrides: {
+ env,
+ extraArgs: [...built.launch.args],
+ clearEnv: gridConflictingEnvToClear({ env }),
+ gridLaunchRecord: { override: source.gridLaunch, webSearch: built.launch.webSearch },
+ },
+ }
}
if (source.codexHome) {
// A Codex agent on a profile OTHER than this machine's default reads hooks.json from THAT folder,
diff --git a/cli/src/lib/registry.spec.ts b/cli/src/lib/registry.spec.ts
index 407d8c441..342945a2f 100644
--- a/cli/src/lib/registry.spec.ts
+++ b/cli/src/lib/registry.spec.ts
@@ -1275,9 +1275,10 @@ describe('registry across a reboot and pane loss', () => {
runtimes: [{ backend: 'tmux', paneId: '%9' }],
cwd: '/tmp/demo',
grid: { baseUrl: GRID_LAUNCH.baseUrl, model: 'gpt-5' },
- gridLaunch: GRID_LAUNCH,
+ gridLaunchRecord: { override: GRID_LAUNCH, webSearch: 'on' },
})!
expect(pending.gridLaunch).toEqual(GRID_LAUNCH)
+ expect(pending.gridWebSearch).toBe('on')
expect(pending.launch).toEqual({ state: 'starting' })
const bound = registry.register({ sessionId: 'session-g', transcriptPath, tmuxPane: '%9', cwd: '/tmp/demo' })
@@ -1285,6 +1286,7 @@ describe('registry across a reboot and pane loss', () => {
expect(bound?.entry).toMatchObject({
grid: { baseUrl: GRID_LAUNCH.baseUrl, model: 'gpt-5' },
gridLaunch: GRID_LAUNCH,
+ gridWebSearch: 'on',
gateway: null,
})
// The hook is the engine reporting in: the launch is over and the frame reads ready.
diff --git a/cli/src/lib/registry.ts b/cli/src/lib/registry.ts
index 051072917..8dc1bab4d 100644
--- a/cli/src/lib/registry.ts
+++ b/cli/src/lib/registry.ts
@@ -36,7 +36,7 @@ import { env } from '../config/env.js'
import { readCodexRolloutMeta, resolveCodexRollout } from '../engines/codex/rollout.js'
import { ENGINES, type AgentEngine } from '../engines/types.js'
import type { GridAssignment } from './gridAssignment.js'
-import { parseGridLaunchOverride, type GridLaunchOverride } from './gridLaunch.js'
+import { parseGridLaunchOverride, type GridLaunchOverride, type GridLaunchRecord, type GridWebSearchStatus } from './gridLaunch.js'
import { commandcodeTranscriptPath } from '../engines/commandcode/transcript.js'
import { agyTranscriptPath } from '../engines/agy/session.js'
import { copilotTranscriptPath } from '../engines/copilot/session.js'
@@ -111,6 +111,14 @@ export interface RegisteredSession {
* treats as "grid agent without a credential".
*/
gridLaunch?: GridLaunchOverride | null
+ /**
+ * What `gridLaunch` decided about web search — `on`, `unavailable` or `unsupported` — as the app
+ * shows it (`grid.webSearch` on the frame). Written with the launch and cleared with it, never
+ * re-derived: the launch builder decided it from the machine as it was at launch, and that is what
+ * the pane actually got. Null on a vendor-login agent and on a discovered grid agent (no launch was
+ * built, so there is nothing to say); absent on a row written before this field existed.
+ */
+ gridWebSearch?: GridWebSearchStatus | null
/**
* The engine's OWN model this agent was on immediately before it moved to a grid.
*
@@ -759,6 +767,7 @@ class Registry {
grid: normalizedGridAssignment(raw.grid),
codexHome: typeof rawCodexHome === 'string' && rawCodexHome ? rawCodexHome : null,
...(rawGridLaunch !== undefined ? { gridLaunch: rawGridLaunch } : {}),
+ ...(rawGridLaunch ? { gridWebSearch: normalizedGridWebSearch(raw?.gridWebSearch) } : {}),
// ⚠️ Rehydrated EXPLICITLY, like every field above it. A row is rebuilt from this list on
// load, so a field added to the type and the setter but not to this list is written to
// disk and then silently dropped by the next load — which is exactly what happened, and
@@ -948,6 +957,7 @@ class Registry {
grid: input.grid ?? null,
// A discovered grid agent has no credential the daemon ever saw: it can be observed, not relaunched.
gridLaunch: null,
+ gridWebSearch: null,
codexHome: input.codexHome ?? null,
transcriptPath: null,
projectDir: basename(input.cwd ?? '') || agentId,
@@ -978,7 +988,8 @@ class Registry {
primaryRuntimeKey?: string
cwd?: string | null
grid?: GridAssignment | null
- gridLaunch?: GridLaunchOverride | null
+ /** The grid launch this pane was opened with and what it decided — the pair `setGridLaunch` keeps. */
+ gridLaunchRecord?: GridLaunchRecord | null
codexHome?: string | null
bypassPermission?: boolean
}): RegisteredSession | null {
@@ -998,7 +1009,8 @@ class Registry {
engine: input.engine,
gateway: null,
grid: input.grid ?? null,
- gridLaunch: input.gridLaunch ?? null,
+ gridLaunch: input.gridLaunchRecord?.override ?? null,
+ gridWebSearch: input.gridLaunchRecord?.webSearch ?? null,
codexHome: input.codexHome ?? null,
...(input.bypassPermission ? { bypassPermission: true } : {}),
transcriptPath: null,
@@ -1146,6 +1158,8 @@ class Registry {
grid: existing?.grid ?? null,
// The credential-bearing launch. Like codexHome: written once, carried forward, never re-derived.
gridLaunch: existing?.gridLaunch ?? null,
+ // What that launch decided — it travels with the launch, or it is lost at the first hook.
+ gridWebSearch: existing?.gridWebSearch ?? null,
// ⚠️ Carried forward for the same reason, and it was missed once: a bind REBUILDS the row from
// named fields, so a field the rebuild does not name survives on disk and vanishes from
// memory the moment the engine reports in. The symptom is a move back to the engine's own
@@ -1355,12 +1369,17 @@ class Registry {
return true
}
- /** Record the launch an agent was last put onto a grid with (`agent_create` / `agent_retarget`), or
- * null once it was moved back to the engine's own login. */
- setGridLaunch(agentId: string, gridLaunch: GridLaunchOverride | null): boolean {
+ /**
+ * Record the launch an agent was last put onto a grid with (`agent_create` / `agent_retarget`) and
+ * what it decided about web search — or null for both once the agent was moved back to the engine's
+ * own login. One call for the pair on purpose: a status without its launch, or a launch without its
+ * status, is a row the app would read wrongly.
+ */
+ setGridLaunch(agentId: string, launch: GridLaunchRecord | null): boolean {
const session = this.agents.get(agentId)
if (!session) return false
- session.gridLaunch = gridLaunch
+ session.gridLaunch = launch?.override ?? null
+ session.gridWebSearch = launch?.webSearch ?? null
session.updatedAt = Date.now()
this.save()
return true
@@ -1648,6 +1667,12 @@ function normalizedGridLaunch(value: unknown): GridLaunchOverride | null | undef
return parsed.state === 'ok' ? parsed.override : null
}
+/** What a persisted launch said about web search. Anything but the three known words is "nothing to
+ * say" — a row from a daemon that knew a fourth would otherwise have the app print it verbatim. */
+function normalizedGridWebSearch(value: unknown): GridWebSearchStatus | null {
+ return value === 'on' || value === 'unavailable' || value === 'unsupported' ? value : null
+}
+
/** A persisted grid assignment. Lenient on `model` on purpose: a row that only knows WHERE it pointed
* must still read as a grid agent, or a restore would relaunch it on the engine's own login. */
function normalizedGridAssignment(value: unknown): GridAssignment | null {
diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dart
index f0d231bd9..bb4528d97 100644
--- a/desktop/lib/core/models.dart
+++ b/desktop/lib/core/models.dart
@@ -114,6 +114,36 @@ class Machine {
);
}
+/// Whether an agent on a Local model can search the web, as the daemon decided when it built the
+/// launch (`grid.webSearch` on the agent frame).
+///
+/// Three words, each a different fact for the person reading the picker: `on` needs no sentence;
+/// `unavailable` means the daemon could not obtain the web-tools configuration this time (an
+/// outdated CLI, no sign-in) and moving the agent again may fix it; `unsupported` means the engine
+/// cannot take the tools on this machine at all (Pi has no MCP client; Hermes under a
+/// system-managed install), and nothing about the model changes that.
+enum GridWebSearch {
+ on,
+ unavailable,
+ unsupported;
+
+ /// The one sentence shown for a degraded status, or null when there is nothing to say.
+ String? get sentence => switch (this) {
+ GridWebSearch.on => null,
+ GridWebSearch.unavailable => 'Web search unavailable',
+ GridWebSearch.unsupported => 'Web search not supported by this engine',
+ };
+
+ /// The wire word, or null for anything else — an older daemon sends no field, and a newer one
+ /// might send a fourth word this build should neither print verbatim nor guess at.
+ static GridWebSearch? fromWire(Object? raw) => switch (raw) {
+ 'on' => GridWebSearch.on,
+ 'unavailable' => GridWebSearch.unavailable,
+ 'unsupported' => GridWebSearch.unsupported,
+ _ => null,
+ };
+}
+
/// Data-plane agent (RPC agents_list).
class Agent {
final String id;
@@ -129,6 +159,12 @@ class Agent {
/// Read by the daemon off the live process on every discovery, never bookkept — so it is the
/// truth even for an agent someone re-pointed by hand. Null is a real answer, not a missing one.
final String? gridModel;
+
+ /// Whether the agent can search the web on that model, or null when the daemon said nothing —
+ /// an agent on its own login, an older daemon, or a grid agent it merely discovered. Decided by
+ /// the daemon when it built the launch and carried on every frame, so it is right after a
+ /// reconnect or a restart without anything being replayed.
+ final GridWebSearch? gridWebSearch;
final String? parentAgentId;
final AgentProject? project;
final String status;
@@ -147,6 +183,7 @@ class Agent {
this.engineIconHint,
this.codexHome,
this.gridModel,
+ this.gridWebSearch,
this.parentAgentId,
this.project,
this.status = 'active',
@@ -181,6 +218,7 @@ class Agent {
'failed' => 'failed',
_ => 'ready',
};
+ final grid = j['grid'] as Map<String, dynamic>?;
return Agent(
id: j['id'] as String,
sessionId: _safeLabel(j['sessionId']),
@@ -189,7 +227,8 @@ class Agent {
engineDisplayName: _safeLabel(j['engineDisplayName']),
engineIconHint: _safeLabel(j['engineIconHint']),
codexHome: j['engine'] == 'codex' ? _safeCodexHome(j['codexHome']) : null,
- gridModel: _safeLabel((j['grid'] as Map<String, dynamic>?)?['model']),
+ gridModel: _safeLabel(grid?['model']),
+ gridWebSearch: GridWebSearch.fromWire(grid?['webSearch']),
parentAgentId: _safeLabel(j['parentAgentId'] ?? j['parentId']),
project: AgentProject.fromJson(j['project']),
status: (j['status'] as String?) ?? 'active',
@@ -215,6 +254,7 @@ class Agent {
engineIconHint: engineIconHint,
codexHome: codexHome,
gridModel: gridModel,
+ gridWebSearch: gridWebSearch,
parentAgentId: parentAgentId,
project: project,
status: status,
diff --git a/desktop/lib/widgets/grid_model_picker.dart b/desktop/lib/widgets/grid_model_picker.dart
index 9dcf81f95..1d30f416e 100644
--- a/desktop/lib/widgets/grid_model_picker.dart
+++ b/desktop/lib/widgets/grid_model_picker.dart
@@ -39,6 +39,13 @@ class GridModelPicker extends StatefulWidget {
/// checkmark, so the menu answers "where am I" as well as "where could I go".
final String? currentModel;
+ /// Whether the agent can search the web on [currentModel], as the daemon decided when it built
+ /// the launch. Shown as a subtitle under the current Local row and in the control's tooltip —
+ /// only for the two degraded values; `on` and null (nothing said) show nothing. Read only when
+ /// [currentModel] is set: it is a fact about a Local-model launch, and the Subscription row has
+ /// its own web tools.
+ final GridWebSearch? webSearch;
+
/// The agent's engine, for the subscription row's icon and label.
final String? engineLabel;
@@ -49,6 +56,7 @@ class GridModelPicker extends StatefulWidget {
this.onSelected,
this.onUseOwnLogin,
this.currentModel,
+ this.webSearch,
this.engineLabel,
});
@@ -60,6 +68,17 @@ class _GridModelPickerState extends State<GridModelPicker> {
bool _loading = false;
ModelsMenuController? _usage;
+ /// The sentence about web search on the current Local model, or null when there is none to
+ /// show. Null off a grid whatever the daemon said: a frame can lag a move home by a beat, and
+ /// the Subscription row must never wear a sentence about a launch it was no part of.
+ String? get _webSearchSentence =>
+ widget.currentModel == null ? null : widget.webSearch?.sentence;
+
+ /// The subtitle under one Local row: the sentence for the CURRENT model only. The status is about
+ /// this agent's launch, and the other rows are places it could go, about which nothing is known.
+ String? _subtitleFor(GridModel model) =>
+ widget.currentModel == model.id ? _webSearchSentence : null;
+
@override
void dispose() {
_usage?.dispose();
@@ -142,8 +161,10 @@ class _GridModelPickerState extends State<GridModelPicker> {
enabled: false,
height: 30,
child: Text(
+ // "Local models", in the user's own vocabulary: the grid is how a Local model is
+ // served, not a thing this menu asks anyone to know about.
answer.gridName == null
- ? 'No grid on this account yet — sign in again to set one up.'
+ ? 'No local models on this account yet — sign in again to set them up.'
: 'Nothing is being served yet.',
style: TextStyle(fontSize: 11, color: AppColors.textSoft),
),
@@ -151,13 +172,16 @@ class _GridModelPickerState extends State<GridModelPicker> {
for (final model in answer.models)
PopupMenuItem<_Choice>(
value: _Choice.model(model),
- height: 32,
+ // Taller only for the current row carrying a sentence; every other row keeps its height
+ // so the menu does not grow for a fact about one agent.
+ height: _subtitleFor(model) != null ? 46 : 32,
child: _Row(
selected: widget.currentModel == model.id,
title: model.id,
// Which of the user's machines answers it — the part that makes a private grid
// legible, and the reason `node` is carried through at all.
status: model.node.isEmpty ? null : model.node,
+ subtitle: _subtitleFor(model),
),
),
],
@@ -194,8 +218,11 @@ class _GridModelPickerState extends State<GridModelPicker> {
@override
Widget build(BuildContext context) {
+ final sentence = _webSearchSentence;
return Tooltip(
- message: 'Where this agent runs',
+ // The same sentence the menu shows, one line under the control's own — so a person can learn
+ // the agent has no web search without opening the menu at all.
+ message: sentence == null ? 'Where this agent runs' : 'Where this agent runs\n$sentence',
waitDuration: const Duration(milliseconds: 700),
child: InkWell(
onTap: _open,
@@ -230,13 +257,15 @@ class _GridModelPickerState extends State<GridModelPicker> {
}
/// One menu row: tick, optional engine mark, title, a quiet detail beside it, and a right-aligned
-/// status. The same column order in both sections, so the eye can run straight down the menu.
+/// status. The same column order in both sections, so the eye can run straight down the menu. A
+/// [subtitle], when there is one, sits under the title in the same column.
class _Row extends StatelessWidget {
final bool selected;
final String? engine;
final String title;
final String detail;
final String? status;
+ final String? subtitle;
const _Row({
required this.selected,
@@ -244,11 +273,12 @@ class _Row extends StatelessWidget {
this.engine,
this.detail = '',
this.status,
+ this.subtitle,
});
@override
Widget build(BuildContext context) {
- return Row(
+ final row = Row(
children: [
// A fixed tick column, so every row's label starts at the same x whether or not it is the
// active one — a menu whose text shifts between rows reads as misaligned. Section headers
@@ -291,6 +321,23 @@ class _Row extends StatelessWidget {
],
],
);
+ if (subtitle == null) return row;
+ return Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ row,
+ Padding(
+ // Behind the tick column, so the sentence starts under the title it is about.
+ padding: const EdgeInsets.only(left: _tickColumn, top: 2),
+ child: Text(
+ subtitle!,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(fontSize: 10.5, color: AppColors.textSoft),
+ ),
+ ),
+ ],
+ );
}
}
diff --git a/desktop/lib/widgets/terminal_panel.dart b/desktop/lib/widgets/terminal_panel.dart
index 63e96049a..2bb53d3a2 100644
--- a/desktop/lib/widgets/terminal_panel.dart
+++ b/desktop/lib/widgets/terminal_panel.dart
@@ -1554,6 +1554,7 @@ class _TerminalHeader extends StatelessWidget {
notifier: notifier,
machineId: session.machineId,
currentModel: agent?.gridModel,
+ webSearch: agent?.gridWebSearch,
engineLabel: session.engineId,
onSelected: (model) => unawaited(
notifier.retargetAgentToGridModel(
diff --git a/desktop/test/agent_creation_recovery_test.dart b/desktop/test/agent_creation_recovery_test.dart
index 6124adc6b..6f3e1aeb2 100644
--- a/desktop/test/agent_creation_recovery_test.dart
+++ b/desktop/test/agent_creation_recovery_test.dart
@@ -653,4 +653,45 @@ void main() {
app.dispose();
},
);
+
+ // The three refusals a grid launch can raise before anything starts, each with the sentence the
+ // daemon actually sends beside its code (`backendSocket.ts` / `launchOverrides.ts`). What the
+ // person reads must be that sentence, never the bare code.
+ for (final (code, detail) in const [
+ ('INVALID_GRID', 'grid is missing networkId, apiKey'),
+ (
+ 'TMUX_TOO_OLD_FOR_GRID',
+ "this machine's tmux is older than 3.2, which is the first version that can give a pane its own environment — so claude could not be pointed at grid Team grid.",
+ ),
+ (
+ 'GRID_CONFIG_FAILED',
+ "could not write pi's grid configuration · EACCES: permission denied",
+ ),
+ ]) {
+ test('a $code refusal reads as a sentence, not a code', () async {
+ final connection = _Connection();
+ final app = createApp(connectionForTest: (_) => connection);
+ addTearDown(app.dispose);
+ final attempt = AgentCreationAttempt();
+ final create = app.createAgent(
+ 'm',
+ engine: 'claude',
+ folder: '/work',
+ attempt: attempt,
+ );
+ connection.calls.last.reply.completeError(
+ WsRequestFailure(
+ responseType: 'agent_create_result',
+ code: code,
+ detail: detail,
+ ),
+ );
+ final message = await create;
+ expect(message, isNotNull);
+ expect(message, contains(detail));
+ expect(message, isNot(contains(code)));
+ // Refused before a launch: nothing to recover, and a second Create is safe.
+ expect(attempt.awaitingConfirmation, isFalse);
+ });
+ }
}
diff --git a/desktop/test/agent_model_test.dart b/desktop/test/agent_model_test.dart
index 2639120d4..9c7baeafc 100644
--- a/desktop/test/agent_model_test.dart
+++ b/desktop/test/agent_model_test.dart
@@ -59,4 +59,48 @@ void main() {
expect(agent.launchError, 'ENGINE_DID_NOT_START');
expect(agent.launchDetail, 'Engine exited see terminal');
});
+
+ group('web search on a Local model', () {
+ Agent onGrid(Map<String, Object?> grid) => Agent.fromJson({
+ 'id': 'agent-1',
+ 'name': 'Local',
+ 'engine': 'claude',
+ 'grid': {'baseUrl': 'https://grid.example/grid-abc/relay', ...grid},
+ });
+
+ test('reads the status off the grid block', () {
+ expect(onGrid({'model': 'qwen', 'webSearch': 'on'}).gridWebSearch, GridWebSearch.on);
+ expect(
+ onGrid({'model': 'qwen', 'webSearch': 'unavailable'}).gridWebSearch,
+ GridWebSearch.unavailable,
+ );
+ expect(
+ onGrid({'model': 'qwen', 'webSearch': 'unsupported'}).gridWebSearch,
+ GridWebSearch.unsupported,
+ );
+ });
+
+ test('has nothing to say when the daemon said nothing, or said a word it does not know', () {
+ // An older daemon, or a grid agent the daemon merely discovered: no field at all.
+ expect(onGrid({'model': 'qwen'}).gridWebSearch, isNull);
+ // A newer daemon with a fourth word: not printed verbatim, not guessed at.
+ expect(onGrid({'model': 'qwen', 'webSearch': 'throttled'}).gridWebSearch, isNull);
+ expect(onGrid({'model': 'qwen', 'webSearch': 7}).gridWebSearch, isNull);
+ });
+
+ test('has nothing to say off a grid', () {
+ final own = Agent.fromJson({'id': 'agent-2', 'name': 'Own', 'grid': null});
+ expect(own.gridModel, isNull);
+ expect(own.gridWebSearch, isNull);
+ });
+
+ test('each degraded status is one sentence; on is none', () {
+ expect(GridWebSearch.unavailable.sentence, 'Web search unavailable');
+ expect(
+ GridWebSearch.unsupported.sentence,
+ 'Web search not supported by this engine',
+ );
+ expect(GridWebSearch.on.sentence, isNull);
+ });
+ });
}
diff --git a/desktop/test/grid_model_picker_test.dart b/desktop/test/grid_model_picker_test.dart
index c978bd579..88bd732cb 100644
--- a/desktop/test/grid_model_picker_test.dart
+++ b/desktop/test/grid_model_picker_test.dart
@@ -52,6 +52,7 @@ void main() {
Future<void> open(
WidgetTester tester, {
String? currentModel,
+ GridWebSearch? webSearch,
VoidCallback? onOwnLogin,
ValueChanged<GridModel>? onSelected,
}) async {
@@ -66,6 +67,7 @@ void main() {
machineId: 'local',
engineLabel: 'claude',
currentModel: currentModel,
+ webSearch: webSearch,
onUseOwnLogin: onOwnLogin,
onSelected: onSelected,
),
@@ -101,6 +103,10 @@ void main() {
// model. A single "no models" would send a person looking in the wrong place.
await open(tester);
expect(find.textContaining('sign in again'), findsOneWidget);
+ // The user's vocabulary is "Local models", never "grid" — the grid is how a Local model is
+ // served, not a thing the picker asks anyone to know about.
+ expect(find.text('No local models on this account yet — sign in again to set them up.'), findsOneWidget);
+ expect(find.textContaining('grid'), findsNothing);
});
testWidgets('a served model shows under Local with the machine answering it', (tester) async {
@@ -151,4 +157,59 @@ void main() {
await tester.pumpAndSettle();
expect(calls, 1);
});
+
+ group('web search on the current Local model', () {
+ const served = [
+ {'id': 'Qwen-Test', 'node': 'macbook-m1max'},
+ {'id': 'Other-Model', 'node': 'macbook-m1max'},
+ ];
+
+ testWidgets('says nothing when it is on', (tester) async {
+ build(models: served);
+ await open(tester, currentModel: 'Qwen-Test', webSearch: GridWebSearch.on);
+ expect(find.textContaining('Web search'), findsNothing);
+ expect(tester.widget<Tooltip>(find.byType(Tooltip)).message, 'Where this agent runs');
+ });
+
+ testWidgets('says nothing when the daemon said nothing', (tester) async {
+ build(models: served);
+ await open(tester, currentModel: 'Qwen-Test');
+ expect(find.textContaining('Web search'), findsNothing);
+ });
+
+ testWidgets('a subtitle under the current row, and the tooltip, when it is unavailable', (tester) async {
+ build(models: served);
+ await open(tester, currentModel: 'Qwen-Test', webSearch: GridWebSearch.unavailable);
+ expect(find.text('Web search unavailable'), findsOneWidget);
+ // Under the CURRENT model, not every model: the status is about this agent's launch, and the
+ // other rows are places it could go, about which nothing is yet known.
+ final subtitle = tester.getTopLeft(find.text('Web search unavailable'));
+ final current = tester.getTopLeft(find.text('Qwen-Test'));
+ final other = tester.getTopLeft(find.text('Other-Model'));
+ expect(subtitle.dy, greaterThan(current.dy));
+ expect(subtitle.dy, lessThan(other.dy));
+ expect(
+ tester.widget<Tooltip>(find.byType(Tooltip)).message,
+ 'Where this agent runs\nWeb search unavailable',
+ );
+ });
+
+ testWidgets('the other sentence when the engine cannot take it', (tester) async {
+ build(models: served);
+ await open(tester, currentModel: 'Qwen-Test', webSearch: GridWebSearch.unsupported);
+ expect(find.text('Web search not supported by this engine'), findsOneWidget);
+ expect(
+ tester.widget<Tooltip>(find.byType(Tooltip)).message,
+ 'Where this agent runs\nWeb search not supported by this engine',
+ );
+ });
+
+ testWidgets('never under the Subscription row, which has its own web tools', (tester) async {
+ // A stale status with no current model (the agent came home, the frame has not caught up):
+ // the subscription row must not inherit a sentence about a launch it was never part of.
+ build(models: served);
+ await open(tester, currentModel: null, webSearch: GridWebSearch.unavailable);
+ expect(find.textContaining('Web search'), findsNothing);
+ });
+ });
}