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.

One process, several services: the edge host, and the services in their own processes leave the core's (#875)

Dee3b2119e881a5
diff --git a/cli/e2e/lean.e2e.ts b/cli/e2e/lean.e2e.ts
index 4631f37b1..e6162a3a7 100644
--- a/cli/e2e/lean.e2e.ts
+++ b/cli/e2e/lean.e2e.ts
@@ -19,11 +19,13 @@ import { withLean } from './harness/release.js'
import { readLeanBundle } from '../src/harnessd/leanBundle.js'
type Engine = 'claude' | 'codex'
-const SERVICES = ['search', 'viewers', 'workspaces', 'teams']
+/** The processes the master runs the services in, and the services, each on its own link to the core. */
+const PROCESSES = ['search', 'viewers', 'edge', 'teams']
+const SERVICES = ['search', 'viewers', 'workspaces', 'usage', 'monitor', 'projects', 'teams']
const commandOf = (pid: number): string => execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim()
const rssMiB = (pid: number): number => Number(execFileSync('ps', ['-o', 'rss=', '-p', String(pid)], { encoding: 'utf8' }).trim()) / 1024
-const servicePids = (d: IsolatedDaemon): Map<string, number> => new Map(SERVICES.map((name) => {
+const servicePids = (d: IsolatedDaemon): Map<string, number> => new Map(PROCESSES.map((name) => {
const started = [...d.log().matchAll(new RegExp(`\\[harnessd\\] service ${name} started \\(pid (\\d+)\\)`, 'g'))]
return [name, Number(started.at(-1)?.[1] ?? 0)]
}))
@@ -47,7 +49,7 @@ describe('harnessd\'s master and services lean', () => {
daemon = d
onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-120).join('\n')}`) })
await d.start()
- await until('every service', () => SERVICES.every((name) => new RegExp(`service ${name} started`).test(d.log())) || null, 60_000, 200)
+ await until('every service process', () => PROCESSES.every((name) => new RegExp(`service ${name} started`).test(d.log())) || null, 60_000, 200)
return d
}
async function agentWorks(d: IsolatedDaemon, engine: Engine): Promise<void> {
diff --git a/cli/e2e/serviceProcesses.e2e.ts b/cli/e2e/serviceProcesses.e2e.ts
index e63752cde..3216b3745 100644
--- a/cli/e2e/serviceProcesses.e2e.ts
+++ b/cli/e2e/serviceProcesses.e2e.ts
@@ -1,9 +1,11 @@
/**
* Services in their own processes, for Claude Code and Codex, on the real daemon: harnessd's master runs
- * search beside the core (`HARNESSD_SERVICES=search`), and whatever happens to search — killed outright,
- * hung, leaking memory, crashing on every start — costs search alone. The core never restarts, every
- * agent keeps working, a search asked while it is down is answered SERVICE_UNAVAILABLE at once, and the
- * master brings search back (or parks it, when it keeps crashing).
+ * search beside the core (`HARNESSD_SERVICES=search`), and the edge host, one process for several light
+ * services (`HARNESSD_SERVICES=edge`: workspaces, usage, the monitor and the project readers). Whatever
+ * happens to either process — killed outright, hung, leaking memory, crashing on every start — costs that
+ * process alone. The core never restarts, every agent keeps working, a request asked while it is down is
+ * answered SERVICE_UNAVAILABLE at once, and the master brings it back (or parks it, when it keeps
+ * crashing), every service in it connected again.
*/
import { execFileSync } from 'node:child_process'
import { mkdirSync } from 'node:fs'
@@ -156,3 +158,123 @@ describe('services in their own processes', () => {
client.close()
})
})
+
+/** This daemon's edge host: titled `harnessd-edge` AND started by its own master, by the pid it logged. */
+function edgePids(d: IsolatedDaemon): number[] {
+ const ours = new Set([...d.log().matchAll(/\[harnessd\] service edge started \(pid (\d+)\)/g)].map((match) => Number(match[1])))
+ const table = execFileSync('ps', ['-A', '-o', 'pid=,command=']).toString().trim().split('\n')
+ return table.map((line) => line.trim().match(/^(\d+)\s+(.*)$/)).filter((match): match is RegExpMatchArray => !!match)
+ .filter(([, pid, command]) => command.trim() === 'harnessd-edge' && ours.has(Number(pid))).map(([, pid]) => Number(pid))
+}
+/** The services the edge host runs, each on its own link to the core. */
+const EDGE = ['workspaces', 'usage', 'monitor', 'projects']
+/** How many times each of the edge host's services has connected to the core. */
+const edgeConnections = (d: IsolatedDaemon): number => Math.min(...EDGE.map((service) => d.log().split(`[services] ${service} connected`).length - 1))
+/** The edge host answers, through the core: the home folder's subfolders, and the machine's own totals. */
+async function edgeAnswers(client: LocalClient): Promise<boolean> {
+ const listed = await client.request('fs_list_dir', {}, 30_000)
+ const machine = await client.request('machine_resources', {}, 30_000)
+ return listed.error === undefined && machine.error === undefined
+}
+/** Asked while the edge host is down: an answer at once, not a hang, and the Monitor's list still lists. */
+async function edgeDown(client: LocalClient, agentId: string): Promise<void> {
+ const listed = await client.request('fs_list_dir', {}, 40_000)
+ if (listed.error) expect(listed).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'projects', retryable: true })
+ const row = (await client.request('agents_list', { monitor: true }, 40_000)).agents.find((agent: Record<string, any>) => agent.id === agentId)
+ expect(row?.monitor).toBeDefined()
+}
+
+describe('the edge host: several services in one process of their own', () => {
+ let daemon: IsolatedDaemon | undefined
+ afterEach(async () => { await daemon?.close(); daemon = undefined })
+ const fresh = async (env: Record<string, string> = {}) => {
+ const d = await IsolatedDaemon.create({ env: {
+ HARNESSD_SERVICES: 'edge',
+ HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200',
+ HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000',
+ ...env,
+ } })
+ daemon = d
+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })
+ await d.start()
+ return d
+ }
+ const restarts = (d: IsolatedDaemon) => d.log().split('\n').filter((line) => /\[harnessd\] service edge started .* restart \d+/.test(line)).length
+
+ it('runs its services in one process, each on its own link, and answers through the core for both engines', async () => {
+ const d = await fresh()
+ const client = await LocalClient.connect(d)
+ await until('every edge service to connect to the core', () => edgeConnections(d) >= 1 || null, 30_000, 200)
+ expect(edgePids(d)).toHaveLength(1)
+ for (const engine of ['claude', 'codex'] as const) {
+ const agent = await create(d, client, engine, `edge-${engine}`)
+ await turn(client, agent.id, `with the edge host (${engine})`)
+ // The Monitor's rows carry the sample the core asked the monitor's process for.
+ const row = (await client.request('agents_list', { monitor: true }, 30_000)).agents.find((one: Record<string, any>) => one.id === agent.id)
+ expect(row.monitor.sampledAt).toEqual(expect.any(String))
+ expect(await client.request('git_project_info', { path: join(d.projectsDir, `edge-${engine}`) }, 30_000)).not.toHaveProperty('service')
+ }
+ expect(await edgeAnswers(client)).toBe(true)
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('killed outright: asked meanwhile it says so at once, agents go on, and the master brings it back with every service', async () => {
+ const d = await fresh()
+ const client = await LocalClient.connect(d)
+ const agent = await create(d, client, 'claude', 'edge-killed')
+ await until('every edge service to connect', () => edgeConnections(d) >= 1 || null, 30_000, 200)
+ const before = edgePids(d)
+ expect(before).toHaveLength(1)
+ for (const pid of before) process.kill(pid, 'SIGKILL')
+ await edgeDown(client, agent.id)
+ await turn(client, agent.id, 'while the edge host was gone')
+ await until('the master to restart the edge host', () => restarts(d) >= 1 || null, 30_000, 200)
+ await until('every edge service to connect again', () => edgeConnections(d) >= 2 || null, 30_000, 200)
+ await until('the edge host to answer again', () => edgeAnswers(client).then((ok) => ok || null), 30_000, 500)
+ expect(edgePids(d).some((pid) => !before.includes(pid))).toBe(true)
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('hung, it is killed by the master\'s heartbeat watch and started again; the core goes on', async () => {
+ const d = await fresh({ HARNESSD_SERVICE_HEARTBEAT_TIMEOUT_MS: '2000' })
+ const client = await LocalClient.connect(d)
+ const agent = await create(d, client, 'codex', 'edge-hung')
+ await until('every edge service to connect', () => edgeConnections(d) >= 1 || null, 30_000, 200)
+ for (const pid of edgePids(d)) process.kill(pid, 'SIGSTOP')
+ // Asked while it is stopped: answered when the link gives up on it or the master kills it, never a hang.
+ await edgeDown(client, agent.id)
+ await until('the master to find the edge host hung', () => d.log().includes('[harnessd] service edge sent no heartbeat') || null, 30_000, 200)
+ await until('the edge host to be started again', () => restarts(d) >= 1 || null, 30_000, 200)
+ await turn(client, agent.id, 'the core never waited on the edge host')
+ await until('the edge host to answer again', () => edgeAnswers(client).then((ok) => ok || null), 30_000, 500)
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('leaking, it is restarted at its memory budget, before it can hurt anything else', async () => {
+ const d = await fresh({ HARNESSD_TEST_FAULTS: 'edge.leak', HARNESSD_SERVICE_HEAP_LIMIT_MIB: '128' })
+ const client = await LocalClient.connect(d)
+ const agent = await create(d, client, 'claude', 'edge-leaking')
+ await until('the master to restart the edge host for memory', () => /\[harnessd\] service edge: (its heap is at|it is using)/.test(d.log()) || null, 60_000, 250)
+ await until('the edge host to be started again', () => restarts(d) >= 1 || null, 30_000, 200)
+ await turn(client, agent.id, 'the leak was the edge host\'s alone')
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('crashing on every start, it is parked, and asked meanwhile says so; agents go on', async () => {
+ const d = await fresh({ HARNESSD_TEST_FAULTS: 'edge.crash', HARNESSD_SERVICE_PARK_CRASHES: '3' })
+ const client = await LocalClient.connect(d)
+ const agent = await create(d, client, 'codex', 'edge-crash-loop')
+ await until('the master to park the edge host', () => d.log().includes('[harnessd] service edge ended 3 times') || null, 60_000, 250)
+ expect(await client.request('fs_list_dir', {}, 10_000)).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'projects', retryable: true })
+ expect(await client.request('machine_resources', {}, 10_000)).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true })
+ const row = (await client.request('agents_list', { monitor: true }, 30_000)).agents.find((one: Record<string, any>) => one.id === agent.id)
+ expect(row.monitor).toMatchObject({ rssBytes: null, cpu: null, processes: [], sampledAt: null })
+ await turn(client, agent.id, 'the edge host is parked and nothing else cares')
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+})
diff --git a/cli/e2e/services.e2e.ts b/cli/e2e/services.e2e.ts
index b0c19f82a..259c12f95 100644
--- a/cli/e2e/services.e2e.ts
+++ b/cli/e2e/services.e2e.ts
@@ -1,10 +1,11 @@
/**
* A failing service never takes the core down, proven on the real daemon: every service made to fail as
* it starts, and services made to fail on every call, while a client starts an agent, the agent binds,
- * messages become turns that start and end, and the daemon restarts. Both ways a service runs: in its
- * own process (the default for search, the viewers, workspaces and the teams, harnessd/services.ts),
- * and inside the core's process (`HARNESSD_SERVICES=none`, and always for models, the Store and the
- * fleet), where the core's host guards it (core/serviceHost.ts).
+ * messages become turns that start and end, and the daemon restarts. Both ways a service runs: in a
+ * process of its own (the default for search, the viewers, the teams and the edge host's workspaces,
+ * usage, monitor and project readers, harnessd/services.ts), and inside the core's process
+ * (`HARNESSD_SERVICES=none`, and always for models, the Store and the fleet), where the core's host
+ * guards it (core/serviceHost.ts).
*/
import { randomUUID } from 'node:crypto'
import { mkdirSync } from 'node:fs'
@@ -50,19 +51,21 @@ async function turn(client: LocalClient, agentId: string, content: string): Prom
const IN_THE_CORE = { HARNESSD_SERVICES: 'none' }
/** A master quick to give up on a service that keeps failing as it starts. */
const QUICK_TO_PARK = { HARNESSD_SERVICE_PARK_CRASHES: '3', HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000' }
-const PROCESS_SERVICES = ['search', 'viewers', 'workspaces', 'teams'] as const
+/** The processes the services run in by default, and what makes every one of them fail as it starts. */
+const SERVICE_PROCESSES = ['search', 'viewers', 'edge', 'teams'] as const
+const EVERY_PROCESS_FAILING = 'search,viewers,workspaces,usage,monitor,projects,teams'
describe('a failing service never takes the core down', () => {
let daemon: IsolatedDaemon | undefined
afterEach(async () => { await daemon?.close(); daemon = undefined })
it('with every service failing to start, in its own process or in the core, the core starts, runs an agent through turns and a restart, and says each one is unavailable', async () => {
- daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'search,viewers,workspaces,teams,models,store', ...QUICK_TO_PARK } })
+ daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: `${EVERY_PROCESS_FAILING},models,store`, ...QUICK_TO_PARK } })
const d = daemon
onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-120).join('\n')}`) })
await d.start()
// Each process fails as it starts, again and again, until the master parks it; the core never waits for one.
- for (const service of PROCESS_SERVICES) {
+ for (const service of SERVICE_PROCESSES) {
await until(`the master to park ${service}`, () => d.log().includes(`[harnessd] service ${service} ended 3 times`) || null, 60_000, 250)
}
for (const service of ['models', 'store']) {
@@ -73,6 +76,11 @@ describe('a failing service never takes the core down', () => {
await turn(client, agentId, 'first, with every service down')
expect(await client.request('session_search', { query: 'first' })).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'search' })
expect(await client.request('dsh_list', {})).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'store' })
+ expect(await client.request('fs_list_dir', { path: d.projectsDir })).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'projects', retryable: true })
+ expect(await client.request('machine_resources', {})).toMatchObject({ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true })
+ // With the monitor's process parked, the Monitor's list is still the list: its rows, without readings.
+ const monitored = (await client.request('agents_list', { monitor: true })).agents.find((agent: Record<string, any>) => agent.id === agentId)
+ expect(monitored.monitor).toMatchObject({ rssBytes: null, cpu: null, processes: [], sampledAt: null })
expect(d.coresStarted()).toBe(1)
await d.restart()
@@ -87,7 +95,7 @@ describe('a failing service never takes the core down', () => {
})
it('with services in their own processes failing on every request and event, each request is answered failed, every turn reaches the client, and nothing restarts', async () => {
- daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'search.touch,search.session_search,workspaces.nameBranches,workspaces.sweep' } })
+ daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'search.touch,search.session_search,workspaces.nameBranches,workspaces.sweep,monitor.resources,projects.fs_list_dir' } })
const d = daemon
onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-120).join('\n')}`) })
await d.start()
@@ -99,7 +107,14 @@ describe('a failing service never takes the core down', () => {
// request is answered for itself, as often as it is asked.
for (let i = 0; i < 6; i++) {
expect(await client.request('session_search', { query: `ask ${i}` }), `ask ${i}`).toMatchObject({ error: 'SERVICE_FAILED', service: 'search' })
+ expect(await client.request('fs_list_dir', { path: d.projectsDir }), `list ${i}`).toMatchObject({ error: 'SERVICE_FAILED', service: 'projects' })
+ // The core's own call into the monitor's process fails each time, and the list is its rows without readings.
+ const monitored = (await client.request('agents_list', { monitor: true })).agents.find((agent: Record<string, any>) => agent.id === agentId)
+ expect(monitored.monitor, `monitor ${i}`).toMatchObject({ rssBytes: null, cpu: null, processes: [], sampledAt: null })
}
+ // The edge host's other answers are its own: one reader failing costs that reader.
+ expect(await client.request('project_preview', { path: '/no/such/folder' })).not.toHaveProperty('service')
+ expect(await client.request('machine_resources', {})).not.toHaveProperty('error')
for (const line of [
'[service search] touch failed · injected fault: search.touch',
'[service search] session_search failed · injected fault: search.session_search',
@@ -236,8 +251,30 @@ describe('a failing service never takes the core down', () => {
client.close()
})
- it('the monitor\'s readings failing on every call leave the list its rows, then switch the monitor off; the core runs on', async () => {
- daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'monitor.resources,projects.fs_list_dir' } })
+ it('one service of the edge host failing to start leaves the others in it running, and the core', async () => {
+ daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'workspaces' } })
+ const d = daemon
+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-80).join('\n')}`) })
+ await d.start()
+ for (const service of ['usage', 'monitor', 'projects']) {
+ await until(`${service} to connect`, () => d.log().includes(`[services] ${service} connected`) || null, 30_000, 200)
+ }
+ expect(d.log()).toContain('[service workspaces] did not start · injected fault: workspaces')
+ const client = await LocalClient.connect(d)
+ const agentId = await boundAgent(d, client, 'edge-without-workspaces')
+ expect((await client.request('fs_list_dir', {})).error).toBeUndefined()
+ expect(await client.request('machine_resources', {})).not.toHaveProperty('error')
+ // The core's own call into the monitor's process: the Monitor's rows carry their sample.
+ const monitored = (await client.request('agents_list', { monitor: true })).agents.find((agent: Record<string, any>) => agent.id === agentId)
+ expect(monitored.monitor.sampledAt).toEqual(expect.any(String))
+ await turn(client, agentId, 'with workspaces off in the edge host')
+ expect(d.log()).not.toMatch(/\[harnessd\] service edge (exited|ended)/)
+ expect(d.coresStarted()).toBe(1)
+ client.close()
+ })
+
+ it('the monitor\'s readings failing on every call in the core leave the list its rows, then switch the monitor off; the core runs on', async () => {
+ daemon = await IsolatedDaemon.create({ env: { HARNESSD_TEST_FAULTS: 'monitor.resources,projects.fs_list_dir', ...IN_THE_CORE } })
onTestFailed(() => { console.log(`---- daemon log\n${daemon?.log().split('\n').slice(-80).join('\n')}`) })
await daemon.start()
const client = await LocalClient.connect(daemon)
diff --git a/cli/e2e/signedIn.e2e.ts b/cli/e2e/signedIn.e2e.ts
index f97d8503d..21f60db0b 100644
--- a/cli/e2e/signedIn.e2e.ts
+++ b/cli/e2e/signedIn.e2e.ts
@@ -14,7 +14,7 @@ import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'
type Engine = 'claude' | 'codex'
const MACHINE: FakeMachine = { machineId: 'c3'.repeat(16), computerId: 'e2e-computer-0000-0000-00000000000c', name: 'signed-in', token: 'e2e-token-signed-in' }
-const SERVICES = ['search', 'viewers', 'workspaces', 'teams'] as const
+const SERVICES = ['search', 'viewers', 'workspaces', 'usage', 'monitor', 'projects', 'teams'] as const
const row = async (client: LocalClient, agentId: string) =>
((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
diff --git a/cli/e2e/workspacesProcess.e2e.ts b/cli/e2e/workspacesProcess.e2e.ts
index ff5dca720..25a6e762c 100644
--- a/cli/e2e/workspacesProcess.e2e.ts
+++ b/cli/e2e/workspacesProcess.e2e.ts
@@ -1,6 +1,7 @@
/**
- * Workspaces in their own process, on the real daemon (`HARNESSD_SERVICES=workspaces`, here also with
- * search and the viewers): the branch Harness made up for a worktree takes its session's name, renamed by the workspaces
+ * Workspaces in their own process, the edge host (harnessd/services.ts `SERVICE_HOSTS`), on the real daemon
+ * (`HARNESSD_SERVICES=workspaces`: the edge host running workspaces alone; here also with search and the
+ * viewers): the branch Harness made up for a worktree takes its session's name, renamed by the workspaces
* process and shown on the agent's frame by the core; and the worktree sweep runs there, when the core's
* timer says. Whatever happens to the process costs workspaces alone. Stopped, hung, killed or crashing on
* every start, the core never restarts, agents keep working, and frames keep their branch names, which
@@ -45,13 +46,13 @@ function idle(d: IsolatedDaemon, path: string): void {
}
}
-/** The workspaces process the master runs now: the last one it said it started. Read from its log,
- * never from the process table, where another daemon's services could be. */
+/** The workspaces process the master runs now, the edge host: the last one it said it started. Read from
+ * its log, never from the process table, where another daemon's services could be. */
const workspacesPid = (d: IsolatedDaemon): number | null => {
- const started = [...d.log().matchAll(/\[harnessd\] service workspaces started \(pid (\d+)\)/g)]
+ const started = [...d.log().matchAll(/\[harnessd\] service edge started \(pid (\d+)\)/g)]
return started.length ? Number(started[started.length - 1][1]) : null
}
-const restarts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service workspaces started .* restart \d+/g)].length
+const restarts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service edge started .* restart \d+/g)].length
const ready = (d: IsolatedDaemon) => [...d.log().matchAll(/\[cli\] ready/g)].length
const connected = (d: IsolatedDaemon) => d.log().split('[services] workspaces connected').length - 1
@@ -135,7 +136,7 @@ describe('workspaces in their own process', () => {
const agent = await create(d, client, cwd)
const first = workspacesPid(d)!
process.kill(first, 'SIGSTOP')
- await until('the master to find workspaces hung', () => d.log().includes('[harnessd] service workspaces sent no heartbeat') || null, 30_000, 200)
+ await until('the master to find workspaces hung', () => d.log().includes('[harnessd] service edge sent no heartbeat') || null, 30_000, 200)
await until('workspaces to be started again', () => restarts(d) >= 1 || null, 30_000, 200)
expect(workspacesPid(d)).not.toBe(first)
await turn(client, agent.id, 'the core never waited on workspaces')
@@ -185,7 +186,7 @@ describe('workspaces in their own process', () => {
const client = await LocalClient.connect(d)
const cwd = worktree(d, repository(d), 'brave-otter', true)
const agent = await create(d, client, cwd)
- await until('the master to park workspaces', () => d.log().includes('[harnessd] service workspaces ended 3 times') || null, 60_000, 250)
+ await until('the master to park workspaces', () => d.log().includes('[harnessd] service edge ended 3 times') || null, 60_000, 250)
await turn(client, agent.id, 'workspaces is parked and nothing else cares')
expect(await branchOf(client, agent.id)).toBe('brave-otter')
expect(d.coresStarted()).toBe(1)
diff --git a/cli/src/architecture.spec.ts b/cli/src/architecture.spec.ts
index ca4c2dd76..cb759b88a 100644
--- a/cli/src/architecture.spec.ts
+++ b/cli/src/architecture.spec.ts
@@ -58,7 +58,12 @@ function runForegroundLines(): number {
/** The relative modules a source imports for its values: static, re-exported, bare and dynamic; never `import type`. */
function valueImports(path: string, text: string): string[] {
- const found: string[] = []
+ return importsFor(path, text).map(({ from }) => from)
+}
+
+/** `valueImports`, saying which are dynamic (`import('…')`). */
+function importsFor(path: string, text: string): Array<{ from: string; dynamic: boolean }> {
+ const found: Array<{ from: string; dynamic: boolean }> = []
const visit = (node: ts.Node): void => {
if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
let typeOnly: boolean
@@ -69,21 +74,28 @@ function valueImports(path: string, text: string): string[] {
} else {
typeOnly = node.isTypeOnly
}
- if (!typeOnly) found.push(node.moduleSpecifier.text)
+ if (!typeOnly) found.push({ from: node.moduleSpecifier.text, dynamic: false })
} else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) {
- found.push(node.arguments[0].text)
+ found.push({ from: node.arguments[0].text, dynamic: true })
}
ts.forEachChild(node, visit)
}
visit(ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true))
- return found.filter((specifier) => specifier.startsWith('.'))
+ return found.filter(({ from }) => from.startsWith('.'))
}
+/**
+ * The one import the core's walk does not follow: the services that run in a process of their own by
+ * default, loaded into the core's only when they run there instead (services/inline.ts). Only a dynamic
+ * import of it is passed over; a static one would load it in every core, and is walked.
+ */
+const IN_PROCESS_ONLY = 'services/inline.ts'
+
/**
* The code a process started on `entry` runs: every file its imports reach, as each file's lines
* (docs/design/2026-10-06-core-boundary-next.md, "The target, and its test"). It follows static and
* dynamic imports under src, `.js` to `.ts` and folders to their index, and leaves out `import type`
- * (types cost nothing at run time) and tests.
+ * (types cost nothing at run time), tests, and a dynamic import of `IN_PROCESS_ONLY`.
*/
function closureOf(entry: string): Map<string, number> {
const lines = new Map<string, number>()
@@ -107,10 +119,11 @@ function parsedFile(path: string): { lines: number; imports: string[] } {
const isFile = (candidate: string): boolean => { try { return statSync(candidate).isFile() } catch { return false } }
const text = readFileSync(path, 'utf8')
const imports: string[] = []
- for (const specifier of valueImports(path, text)) {
- const base = resolve(dirname(path), specifier)
+ for (const { from, dynamic } of importsFor(path, text)) {
+ const base = resolve(dirname(path), from)
const target = [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, join(base, 'index.ts')].find(isFile)
if (!target || !target.startsWith(SRC + '/') || !target.endsWith('.ts') || /\.(spec|test|e2e)\.ts$/.test(target)) continue
+ if (dynamic && relative(SRC, target) === IN_PROCESS_ONLY) continue
imports.push(target)
}
const result = { lines: text.split('\n').length, imports }
@@ -161,11 +174,15 @@ const SERVICE_MAY_IMPORT: Record<string, string> = {
*
* Grew by 97 for the Jev catalog (#888, lib/localModels.ts and appModels.ts): the models service's own
* code, in the core's process only until step 7 runs models in a process of its own and takes it out.
+ *
+ * Then at 102,019 in 430 with #893's shell launch (step 5), from 106,006 in 451: search, the viewers, workspaces, usage, the
+ * monitor and the project readers run in processes of their own, and their code is loaded into the
+ * core's only when they run there instead (services/inline.ts).
*/
-// Connected TUI shells add a literal-argv launch port and shell service (160 loaded lines).
-// Moving the search filename out of its CLI command removes 188 loaded lines, so this lowers
-// the measured closure by 28. Shell policy stays in the service; the core only launches argv.
-const CORE_CLOSURE_BUDGET = 106_006
+//
+// Connected TUI shells added a literal-argv launch port and shell service (#893, 160 loaded lines); moving
+// the search filename out of its CLI command removed 188, so that change lowered the closure by 28.
+const CORE_CLOSURE_BUDGET = 102_110
/** What is not the core's, by path: each goes to a service or its own process, in the plan's order. */
const EDGE: RegExp[] = [
@@ -206,7 +223,6 @@ const CORE_MAY_REACH: Record<string, string> = {
'device/deviceFleet.ts': 'step 9: the fleet, beside the dial',
'device/deviceLink.ts': 'step 9: the fleet, beside the dial',
'device/machineList.ts': 'step 9: the dial, in the devices process',
- 'dsh/artifacts.ts': 'step 5: the viewers\' in-process start, into services/inline.ts',
'dsh/builtins.ts': 'step 6: the Store, in the viewers\' process',
'dsh/catalog.ts': 'step 6: the Store, in the viewers\' process',
'dsh/install.ts': 'step 6: the Store, in the viewers\' process',
@@ -215,9 +231,6 @@ const CORE_MAY_REACH: Record<string, string> = {
'dsh/service.ts': 'step 6: the Store, in the viewers\' process',
'dsh/update.ts': 'step 6: the Store, in the viewers\' process',
'dsh/updates.ts': 'step 6: the Store, in the viewers\' process',
- 'dsh/verdict.ts': 'step 5: the viewers\' in-process start, into services/inline.ts',
- 'dsh/viewer.ts': 'step 5: the viewers\' in-process start, into services/inline.ts',
- 'dsh/viewerLedger.ts': 'step 5: the viewers\' in-process start, into services/inline.ts',
'dsh/wire.ts': 'step 6: the Store, in the viewers\' process',
'lib/autonomous-device/direct.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
'lib/autonomous-device/discovery.ts': 'step 10: the Wi-Fi device, into the devices process over the gateway',
@@ -265,11 +278,9 @@ const CORE_MAY_REACH: Record<string, string> = {
'lib/gridTarget.ts': 'step 7: models, in its own process',
'lib/gridWake.ts': 'step 7: models, in its own process',
'lib/localModels.ts': 'step 7: models, in its own process',
- 'lib/sessionSearch/indexer.ts': 'step 5: search\'s in-process start, into services/inline.ts',
- 'lib/sessionSearch/sessionTurns.ts': 'step 5: the handoff (lib/agentHandoff.ts), in the edge host',
- 'lib/sessionSearch/store.ts': 'step 5: search\'s in-process start, into services/inline.ts',
- 'lib/sessionSearch/transcript.ts': 'step 5: search\'s in-process start, into services/inline.ts; the readers keep this helper, beside them',
- 'lib/sessionSearch/turns.ts': 'step 5: the handoff (lib/agentHandoff.ts), in the edge host',
+ 'lib/sessionSearch/sessionTurns.ts': 'the handoff (lib/agentHandoff.ts), in the edge host once CoreApi gives it the stopped agents, recaps and discovery it reads',
+ 'lib/sessionSearch/transcript.ts': 'the readers of other engines\' sessions keep this helper: it moves beside them, out of search\'s folder',
+ 'lib/sessionSearch/turns.ts': 'the handoff (lib/agentHandoff.ts), in the edge host once CoreApi gives it the stopped agents, recaps and discovery it reads',
'orchestrator/artifacts.ts': 'step 8: the experimental host',
'orchestrator/model.ts': 'step 8: the experimental host',
'orchestrator/prompts.ts': 'step 8: the experimental host',
@@ -278,15 +289,9 @@ const CORE_MAY_REACH: Record<string, string> = {
'services/fleet.ts': 'step 9: the fleet, beside the dial',
'services/fleetRouter.ts': 'step 9: the fleet, beside the dial',
'services/models.ts': 'step 7: models, in its own process',
- 'services/monitor.ts': 'step 5: the machine monitor, in the edge host',
- 'services/shell.ts': 'step 5: shell setup and launch receipts, in the edge host; only the argv launch stays in the core',
- 'services/projects.ts': 'step 5: the project and folder readers, in the edge host',
+ 'services/shell.ts': 'shell setup and launch receipts, in the edge host; only the argv launch stays in the core (#893)',
'services/requestErrors.ts': 'step 7: with the last service that uses it, models, out of the core\'s process',
- 'services/search.ts': 'step 5: search\'s in-process start, into services/inline.ts',
'services/store.ts': 'step 6: the Store, in the viewers\' process',
- 'services/usage.ts': 'step 5: account usage, in the edge host',
- 'services/viewers.ts': 'step 5: the viewers\' in-process start, into services/inline.ts',
- 'services/workspaces.ts': 'step 5: workspaces, in the edge host',
'sharing/collaboration.ts': 'step 8: the experimental host',
'sharing/crypto.ts': 'step 8: the experimental host',
'sharing/grants.ts': 'step 8: the experimental host',
@@ -369,6 +374,12 @@ describe('the daemon\'s shape', () => {
expect(closureOf('entry.ts').has('cli.ts')).toBe(true)
expect(closureOf('core/main.ts').has('core/api.ts')).toBe(true)
expect(closureOf('core/main.ts').has('cli.ts')).toBe(false)
+ // The core loads the services' own code only when they run in its process: imported dynamically, and
+ // only from its entry, the import is not followed. Any other import of it is.
+ const main = importsFor('core/main.ts', readFileSync(join(SRC, 'core', 'main.ts'), 'utf8')).filter(({ from }) => from === '../services/inline.js')
+ expect(main).toEqual([{ from: '../services/inline.js', dynamic: true }])
+ expect(closureOf('core/main.ts').has(IN_PROCESS_ONLY)).toBe(false)
+ expect(importsFor('example.ts', "import { startSearch } from './services/inline.js'")).toEqual([{ from: './services/inline.js', dynamic: false }])
for (const exception of Object.keys(SERVICE_MAY_IMPORT)) {
const [file, from] = exception.split(' → ')
expect(services.some((found) => found.file === file && found.from === from), `${exception} is no longer needed: remove it`).toBe(true)
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index 743b61aa2..cc46cf61e 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -31,8 +31,12 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
- `input.ts`, `questions.ts`: messages into a pane; an agent's question and its answer.
- `main.ts`: the core's entry (`harness __run`) and composition root, `runForeground`: it builds these
modules, starts the services through `serviceHost` and wires the socket. The one core file that imports
- services and the socket, and the one outside the 100% coverage: wiring only, run end to end.
-- `api.ts`: the contract with services. `serviceHost.ts`: services in this process.
- `serviceLinks.ts`: services in their own processes. `viewersLink.ts`: what the core keeps of the
- viewers when they run in theirs. `workspacesLink.ts`: what the core tells workspaces in theirs.
- `teamsLink.ts`: every change to the teams' prompt scopes, kept until their process has it.
+ services and the socket, and the one outside the 100% coverage: wiring only, run end to end. The
+ services that run in their own processes by default it imports only dynamically, through
+ `../services/inline.ts`, and only when one runs in this process instead.
+- `api.ts`: the contract with services, their ports, fallbacks and requests. `serviceHost.ts`: services
+ in this process. `serviceLinks.ts`: services in their own processes. `viewersLink.ts`: what the core
+ keeps of the viewers when they run in theirs. `workspacesLink.ts`: what the core tells workspaces in
+ theirs. `teamsLink.ts`: every change to the teams' prompt scopes, kept until their process has it.
+ `monitorLink.ts`: the monitor's port, asked of its process. `agentQueries.ts`: what a service in its
+ own process may ask of the agents.
diff --git a/cli/src/core/agentQueries.spec.ts b/cli/src/core/agentQueries.spec.ts
new file mode 100644
index 000000000..74e9c85ab
--- /dev/null
+++ b/cli/src/core/agentQueries.spec.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import type { RegisteredSession } from '../lib/registry.js'
+import { fakeCore } from '../testing/fakeCore.js'
+import { answerAgentQuery } from './agentQueries.js'
+
+const agent = (agentId: string, over: Partial<RegisteredSession> = {}) => ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', cwd: `/work/${agentId}`, ...over }) as RegisteredSession
+
+describe('what a service in its own process may ask the core of the agents', () => {
+ const live = [agent('a1'), agent('a2')]
+ const stopped = [agent('a3', { active: false })]
+ const core = fakeCore({ agents: { all: () => [...live, ...stopped], live: () => live, advertised: () => [live[0]], displayName: (session: RegisteredSession) => `name of ${session.agentId}` } })
+
+ it('every agent, live then stopped, with the name the apps show for it', () => {
+ expect(answerAgentQuery(core, 'agents')).toEqual({ agents: [...live, ...stopped].map((session) => ({ ...session, displayName: `name of ${session.agentId}` })) })
+ })
+
+ it('the live agents, and those the apps are shown', () => {
+ expect(answerAgentQuery(core, 'live')).toEqual({ agents: live })
+ expect(answerAgentQuery(core, 'advertised')).toEqual({ agents: [live[0]] })
+ })
+
+ it('nothing else', () => {
+ expect(answerAgentQuery(core, 'credentials')).toEqual({ error: 'UNKNOWN_QUERY' })
+ })
+})
diff --git a/cli/src/core/agentQueries.ts b/cli/src/core/agentQueries.ts
new file mode 100644
index 000000000..99c45bb74
--- /dev/null
+++ b/cli/src/core/agentQueries.ts
@@ -0,0 +1,16 @@
+/**
+ * What a service in its own process may ask the core of the agents (`service_query`, core/serviceLinks.ts)
+ * when it has no link module of its own to answer it (the viewers, workspaces and the teams do):
+ * - `agents`: every agent, live then stopped, with the name the apps show for it (search indexes them);
+ * - `live`: the live agents, as `CoreApi.agents.live` answers in the core's process (the project readers);
+ * - `advertised`: the live agents the apps are shown (the monitor samples them).
+ * Each is read as it is asked, so the service works from the registry as it is at that moment.
+ */
+import type { CoreApi } from './api.js'
+
+export function answerAgentQuery(core: Pick<CoreApi, 'agents'>, query: string): Record<string, unknown> {
+ if (query === 'agents') return { agents: core.agents.all().map((session) => ({ ...session, displayName: core.agents.displayName(session) })) }
+ if (query === 'live') return { agents: core.agents.live() }
+ if (query === 'advertised') return { agents: core.agents.advertised() }
+ return { error: 'UNKNOWN_QUERY' }
+}
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index d61d76ca9..87bba64b1 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -153,6 +153,39 @@ export type ServiceRequest = (payload: Record<string, unknown>, asker: Asker) =>
/** The requests a service answers, by frame type: what its start returns. */
export type ServiceRequests = Readonly<Record<string, ServiceRequest>>
+/*
+ * The requests each service answers for the apps, declared here rather than in the service's own module.
+ * The core routes them, and answers them SERVICE_UNAVAILABLE while their service is off, from these
+ * lists alone: a service that runs in its own process is never loaded into the core's to learn them
+ * (docs/design/2026-10-06-core-boundary-next.md, "The target, and its test"). Its module re-exports its own.
+ */
+
+/** Session search (services/search.ts). */
+export const SEARCH_REQUESTS = ['session_search', 'session_tail'] as const
+/** The Harness Store (services/store.ts). */
+export const STORE_REQUESTS = ['dsh_list', 'dsh_install', 'dsh_update', 'dsh_remove'] as const
+/** Account usage (services/usage.ts). */
+export const USAGE_REQUESTS = ['usage_read'] as const
+/** The machine monitor (services/monitor.ts). */
+export const MONITOR_REQUESTS = ['machine_resources'] as const
+/** The project and folder readers (services/projects.ts). */
+export const PROJECTS_REQUESTS = ['git_pull_request', 'git_project_info', 'project_preview', 'fs_list_dir', 'agent_read_file'] as const
+/**
+ * Models (services/models.ts).
+ *
+ * The Model Manager's grid commands, `grid_fleet_run` and `grid_fleet_cancel`, are still the socket's:
+ * a command is a job of the connection that started it, and a cancel stops only that connection's job
+ * (`lib/gridFleetRpc.ts`), while a request answered by a service knows who asked but not over which
+ * connection. Their handshake, `grid_fleet_capabilities`, stays beside them: the Grid harness runs a
+ * command only after it, and reads an answer without its protocol as "update Harness".
+ * The saved APIs and the Codex profiles came out of the socket's switch (launchTargetRequests).
+ */
+export const MODELS_REQUESTS = [
+ 'grid_models_list', 'models_list',
+ 'grid_fleet_models_list', 'grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop',
+ 'api_connections', 'codex_profiles_list', 'codex_profile_link',
+] as const
+
/** The core's calls into session search: index a session at its turn boundaries, forget a purged
* conversation, the title it indexed for one being adopted, and stopping its sweeps. The apps' own
* requests (`session_search`, `session_tail`) are its `ServiceRequests`, not the core's calls. */
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 823a1c847..8488f7639 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -131,22 +131,18 @@ import { createAgentUpdate } from './agents/update.js'
import { createEngineHooks, installEngineHooks } from './engines/hooks.js'
import { createCursorTaskHooks } from './engines/cursorTasks.js'
import { databaseHistory } from './transcripts/databaseHistory.js'
-import { createCoreApi, emptyPorts, FLEET_FALLBACKS, MODELS_FALLBACKS, MONITOR_FALLBACKS, MONITOR_OFF, SEARCH_FALLBACKS, TEAMS_FALLBACKS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type TeamsPort } from './api.js'
+import { createCoreApi, emptyPorts, FLEET_FALLBACKS, MODELS_FALLBACKS, MODELS_REQUESTS, MONITOR_FALLBACKS, MONITOR_OFF, MONITOR_REQUESTS, PROJECTS_REQUESTS, SEARCH_FALLBACKS, SEARCH_REQUESTS, STORE_REQUESTS, TEAMS_FALLBACKS, USAGE_REQUESTS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type TeamsPort } from './api.js'
import { createServiceHost, testFaults } from './serviceHost.js'
import { startStalls } from './stall.js'
import { createServiceLinks } from './serviceLinks.js'
import { createViewersLink } from './viewersLink.js'
import { createWorkspacesLink } from './workspacesLink.js'
+import { createMonitorLink } from './monitorLink.js'
+import { answerAgentQuery } from './agentQueries.js'
import { KNOWN_SERVICES, servicesTheMasterRuns } from '../harnessd/services.js'
import { createTeamsLink } from './teamsLink.js'
-import { SEARCH_REQUESTS, startSearch } from '../services/search.js'
-import { STORE_REQUESTS, startStore } from '../services/store.js'
-import { USAGE_REQUESTS, startUsage } from '../services/usage.js'
-import { MONITOR_REQUESTS, startMonitor } from '../services/monitor.js'
-import { PROJECTS_REQUESTS, startProjects } from '../services/projects.js'
-import { startViewers } from '../services/viewers.js'
-import { MODELS_REQUESTS, startModels } from '../services/models.js'
-import { startWorkspaces } from '../services/workspaces.js'
+import { startStore } from '../services/store.js'
+import { startModels } from '../services/models.js'
import { startFleet } from '../services/fleet.js'
import { CORE_EXIT_STOP, CORE_EXIT_UPDATE } from '../harnessd/protocol.js'
import { localSocketPath, refuseServedDataFolder, type LocalSocketServer } from '../lib/localSocket.js'
@@ -1123,8 +1119,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// routed to them, and answered SERVICE_UNAVAILABLE while they are down (core/serviceLinks.ts).
const serviceToken = process.env.HARNESSD_SUPERVISED === '1' ? process.env.HARNESSD_SERVICE_TOKEN : undefined
const outOfProcess = servicesTheMasterRuns(process.env, KNOWN_SERVICES)
- // The requests each service that can run in its own process answers (its own module declares them).
- const requestsOf: Record<string, readonly string[]> = { search: SEARCH_REQUESTS }
+ // The requests each service that can run in its own process answers, as core/api.ts declares them.
+ const requestsOf: Record<string, readonly string[]> = { search: SEARCH_REQUESTS, usage: USAGE_REQUESTS, monitor: MONITOR_REQUESTS, projects: PROJECTS_REQUESTS }
// What the core keeps of the viewers in their own process, for the frames it builds (core/viewersLink.ts).
const viewersLink = createViewersLink(coreApi, (frame, opts) => serviceLinks.notify('viewers', frame, opts))
// How the core tells workspaces in their own process what to do, and answers them (core/workspacesLink.ts).
@@ -1134,16 +1130,16 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const serviceLinks = createServiceLinks({
token: serviceToken,
owned: Object.fromEntries([...outOfProcess].map((name) => [name, requestsOf[name] ?? []])),
- // Search asks for every agent, live then stopped, with the name the apps show for it: what it indexes.
answer: (service, query, payload) => service === 'viewers' ? viewersLink.answer(query, payload)
: service === 'workspaces' ? workspacesLink.answer(query, payload)
- : service === 'teams' ? teamsLink.answer(query, payload) : query === 'agents'
- ? { agents: coreApi.agents.all().map((session) => ({ ...session, displayName: coreApi.agents.displayName(session) })) }
- : { error: 'UNKNOWN_QUERY' },
+ : service === 'teams' ? teamsLink.answer(query, payload) : answerAgentQuery(coreApi, query),
})
// A request a service declared goes to it: in its own process, or in this one (core/serviceHost.ts).
backend.serviceRouter = (type, payload, asker, reply) =>
serviceLinks.route(type, payload, asker, reply) || serviceHost.route(type, payload, asker, reply)
+ // The services' own code, for those that run in this process (services/inline.ts): loaded only then, so
+ // one in its own process, as each is by default, is never loaded here.
+ const inline = KNOWN_SERVICES.some((name) => !outOfProcess.has(name)) ? await import('../services/inline.js') : null
// Session search (services/search.ts): in this process, or in its own (services/searchProcess.ts),
// where the core tells it what changed. A purge's forgetting waits for it if it is down.
@@ -1155,28 +1151,31 @@ async function runForeground(session: AuthSession | null): Promise<void> {
stop: () => {},
}
} else {
- serviceHost.start('search', startSearch, coreApi, SEARCH_FALLBACKS, SEARCH_REQUESTS)
+ serviceHost.start('search', inline!.startSearch, coreApi, SEARCH_FALLBACKS, SEARCH_REQUESTS)
}
// What the core calls search through: guarded, so it answers its fallbacks once search is switched off.
const sessionSearch = ports.search
// The DSH viewers: in this process, or in its own (services/viewersProcess.ts), told of each agent.
if (outOfProcess.has('viewers')) ports.viewers = viewersLink.port
- else serviceHost.start('viewers', startViewers, coreApi, VIEWERS_FALLBACKS)
- // Workspaces: in this process, or in its own (services/workspacesProcess.ts), told what to do and when.
+ else serviceHost.start('viewers', inline!.startViewers, coreApi, VIEWERS_FALLBACKS)
+ // Workspaces: in this process, or in the edge host (services/workspacesProcess.ts), told what to do and when.
if (outOfProcess.has('workspaces')) ports.workspaces = workspacesLink.port
- else serviceHost.start('workspaces', startWorkspaces, coreApi, WORKSPACES_FALLBACKS)
+ else serviceHost.start('workspaces', inline!.startWorkspaces, coreApi, WORKSPACES_FALLBACKS)
// The prompt scopes, behind the service host's guard (a fault there costs no message its write) or in their own process.
if (outOfProcess.has('teams')) ports.teams = backend.swarmPromptScopes = teamsLink.scopes
else serviceHost.start('teams', (_core, started) => { started.teams = backend.swarmPromptScopes }, coreApi, TEAMS_FALLBACKS)
// The harnesses installed here, and installing, updating and removing one (services/store.ts).
serviceHost.serve('store', startStore, coreApi, STORE_REQUESTS)
- // This machine's Claude and Codex rate limits, read with its own credentials (services/usage.ts).
- serviceHost.serve('usage', startUsage, coreApi, USAGE_REQUESTS)
- // This machine's and each agent's resources, for the Monitor and the list's readings (services/monitor.ts).
- serviceHost.start('monitor', startMonitor, coreApi, MONITOR_FALLBACKS, MONITOR_REQUESTS)
+ // This machine's Claude and Codex rate limits, read with its own credentials (services/usage.ts): in this
+ // process, or in the edge host (services/usageProcess.ts).
+ if (!outOfProcess.has('usage')) serviceHost.serve('usage', inline!.startUsage, coreApi, USAGE_REQUESTS)
+ // This machine's and each agent's resources, for the Monitor and the list's readings (services/monitor.ts):
+ // in this process, or in the edge host (services/monitorProcess.ts), asked through its port (core/monitorLink.ts).
+ if (outOfProcess.has('monitor')) ports.monitor = createMonitorLink((type, payload) => serviceLinks.call('monitor', type, payload))
+ else serviceHost.start('monitor', inline!.startMonitor, coreApi, MONITOR_FALLBACKS, MONITOR_REQUESTS)
// An agent's branch and pull request, a project's repository and preview, a folder's subfolders and a
- // media file from an agent's project (services/projects.ts).
- serviceHost.serve('projects', startProjects, coreApi, PROJECTS_REQUESTS)
+ // media file from an agent's project (services/projects.ts): in this process, or in the edge host.
+ if (!outOfProcess.has('projects')) serviceHost.serve('projects', inline!.startProjects, coreApi, PROJECTS_REQUESTS)
serviceHost.serve('shell', startShell, coreApi, SHELL_REQUESTS)
const runtimeController = new RuntimeProfileController({
diff --git a/cli/src/core/monitorLink.spec.ts b/cli/src/core/monitorLink.spec.ts
new file mode 100644
index 000000000..ebe707baa
--- /dev/null
+++ b/cli/src/core/monitorLink.spec.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createMonitorLink } from './monitorLink.js'
+import { ServiceUnavailableError } from './serviceHost.js'
+
+describe('the monitor in its own process, as the core reaches it', () => {
+ it('asks it for the readings the list adds, and answers its sample', async () => {
+ const snapshot = { agents: [{ agentId: 'a1', memoryBytes: 1 }], sampledAt: '2026-10-06T00:00:00.000Z', shared: [] }
+ const call = vi.fn(async () => ({ snapshot }))
+ await expect(createMonitorLink(call).resources()).resolves.toEqual(snapshot)
+ expect(call).toHaveBeenCalledWith('resources', {})
+ })
+
+ it('reads a monitor that is down, slow or failing as no sample: the list\'s rows without readings', async () => {
+ for (const answer of [{ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true }, { error: 'SERVICE_FAILED', service: 'monitor' }, { snapshot: 'not one' }]) {
+ await expect(createMonitorLink(async () => answer).resources()).rejects.toBeInstanceOf(ServiceUnavailableError)
+ }
+ })
+
+ it('asks what each agent\'s workspace and transcript hold, and to forget it after a purge', async () => {
+ const call = vi.fn(async (_type: string, payload: Record<string, unknown>) => (payload.invalidate ? {} : { entries: [['a1', { workspaceBytes: 7 }]] }))
+ const link = createMonitorLink(call)
+ const agents = [{ agentId: 'a1', cwd: '/work/a1' }]
+ expect(await link.storage(agents)).toEqual(new Map([['a1', { workspaceBytes: 7 }]]))
+ expect(call).toHaveBeenLastCalledWith('storage', { agents, invalidate: false })
+ // Nothing back (forgetting, or a monitor that is down): nothing measured.
+ expect(await link.storage([], true)).toEqual(new Map())
+ expect(call).toHaveBeenLastCalledWith('storage', { agents: [], invalidate: true })
+ })
+})
diff --git a/cli/src/core/monitorLink.ts b/cli/src/core/monitorLink.ts
new file mode 100644
index 000000000..d3ba7a254
--- /dev/null
+++ b/cli/src/core/monitorLink.ts
@@ -0,0 +1,35 @@
+/**
+ * The machine monitor in its own process, as the core reaches it (in the edge host; the process's side is
+ * services/monitorProcess.ts).
+ *
+ * The core asks the monitor two things, both answered when they are read and never in a connection's
+ * line: the readings `agents_list` adds to its rows for the Monitor (`resources`, `storage`), and, after a
+ * purge, to forget what it measured (`storage` with `invalidate`). Out of process each is a request to
+ * the monitor's process (core/serviceLinks.ts `call`), and an answer that does not come (the process is
+ * down, or slower than the link waits) is what the in-process fallbacks give (core/api.ts
+ * `MONITOR_FALLBACKS`): rows without readings, and nothing measured to forget. Nothing is held for the
+ * process while it is down: a reading asked for later is read later.
+ */
+import type { MonitorPort } from './api.js'
+import { ServiceUnavailableError } from './serviceHost.js'
+
+/** Ask the monitor's process (core/serviceLinks.ts `call`, for `monitor`): never rejects. */
+export type CallMonitor = (type: string, payload: Record<string, unknown>) => Promise<Record<string, unknown>>
+
+type Snapshot = Awaited<ReturnType<MonitorPort['resources']>>
+type Readings = Awaited<ReturnType<MonitorPort['storage']>>
+
+export function createMonitorLink(call: CallMonitor): MonitorPort {
+ return {
+ resources: async () => {
+ const answer = await call('resources', {})
+ // SERVICE_UNAVAILABLE or SERVICE_FAILED: no sample, which the list reads as rows without readings.
+ if (!answer.snapshot || typeof answer.snapshot !== 'object') throw new ServiceUnavailableError('monitor')
+ return answer.snapshot as Snapshot
+ },
+ storage: async (agents, invalidate = false) => {
+ const answer = await call('storage', { agents, invalidate })
+ return new Map(Array.isArray(answer.entries) ? answer.entries : []) as Readings
+ },
+ }
+}
diff --git a/cli/src/core/serviceLinks.spec.ts b/cli/src/core/serviceLinks.spec.ts
index 259688403..eb823970e 100644
--- a/cli/src/core/serviceLinks.spec.ts
+++ b/cli/src/core/serviceLinks.spec.ts
@@ -61,6 +61,27 @@ describe('service links', () => {
expect(links.route('agents_list', {}, ASKER, reply)).toBe(false)
})
+ it('asks a service what the core itself needs, as the core, and settles every way a routed request does', async () => {
+ const links = make({ owned: { monitor: ['machine_resources'] } })
+ // Down: unavailable at once, never a rejection.
+ await expect(links.call('monitor', 'resources', {})).resolves.toEqual({ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true })
+ const monitor = sink()
+ const link = links.accept('monitor', TOKEN, monitor, vi.fn())!
+ const answered = links.call('monitor', 'storage', { agents: [], invalidate: true })
+ expect(monitor.sent).toEqual([{ type: 'storage', payload: { agents: [], invalidate: true, requestId: 'route-1' }, asker: { local: true, owner: true } }])
+ link.receive({ type: 'storage_result', payload: { requestId: 'route-1', entries: [['a1', { workspaceBytes: 1 }]] } })
+ await expect(answered).resolves.toEqual({ entries: [['a1', { workspaceBytes: 1 }]] })
+ // The types it asks are not the apps' to route.
+ expect(links.route('storage', {}, ASKER, vi.fn())).toBe(false)
+ // Too slow, or gone before it answers: unavailable.
+ const slow = links.call('monitor', 'resources', {})
+ vi.advanceTimersByTime(5_000)
+ await expect(slow).resolves.toEqual({ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true })
+ const cut = links.call('monitor', 'resources', {})
+ link.closed()
+ await expect(cut).resolves.toEqual({ error: 'SERVICE_UNAVAILABLE', service: 'monitor', retryable: true })
+ })
+
it('answers SERVICE_UNAVAILABLE at once while the service is down, and when it cannot be sent to', () => {
const links = make()
const reply = vi.fn()
diff --git a/cli/src/core/serviceLinks.ts b/cli/src/core/serviceLinks.ts
index 0f76a46e4..1da3a947d 100644
--- a/cli/src/core/serviceLinks.ts
+++ b/cli/src/core/serviceLinks.ts
@@ -59,6 +59,9 @@ interface Waiting {
/** The most notifications held for one service while it is down. */
export const HELD_MAX = 1_000
+/** Who asks when the core itself asks a service (`call`): this machine's owner, on this machine. */
+const THE_CORE: Asker = { local: true, owner: true }
+
export function createServiceLinks(options: ServiceLinksOptions) {
const timeoutMs = options.timeoutMs ?? 30_000
const log = options.log ?? ((line: string) => console.warn(line))
@@ -87,6 +90,18 @@ export function createServiceLinks(options: ServiceLinksOptions) {
entry.reply(result)
}
+ /** Send `type` to `service`, its answer to `reply`, whatever becomes of the service. */
+ const ask = (service: string, type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void): void => {
+ const link = links.get(service)
+ if (!link) { reply(unavailable(service)); return }
+ const id = newId()
+ const entry: Waiting = { service, type, reply, timer: null }
+ // Cleared whenever the entry is settled, so it only ever fires for one still waiting.
+ entry.timer = setTimer(() => settle(id, entry, unavailable(service)), timeoutMs)
+ waiting.set(id, entry)
+ if (!link.sink.sendFrame({ type, payload: { ...payload, requestId: id }, asker })) settle(id, entry, unavailable(service))
+ }
+
return {
/** A service connecting. Null — and the socket closes it — unless the master started it. */
accept(service: string, token: string, sink: ServiceSink, close: (code: number, reason: string) => void): ServiceLink | null {
@@ -135,17 +150,17 @@ export function createServiceLinks(options: ServiceLinksOptions) {
route(type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void): boolean {
const service = ownerOf.get(type)
if (!service) return false
- const link = links.get(service)
- if (!link) { reply(unavailable(service)); return true }
- const id = newId()
- const entry: Waiting = { service, type, reply, timer: null }
- // Cleared whenever the entry is settled, so it only ever fires for one still waiting.
- entry.timer = setTimer(() => settle(id, entry, unavailable(service)), timeoutMs)
- waiting.set(id, entry)
- if (!link.sink.sendFrame({ type, payload: { ...payload, requestId: id }, asker })) settle(id, entry, unavailable(service))
+ ask(service, type, payload, asker, reply)
return true
},
+ /** Ask a service what the core itself needs (a port's call, core/monitorLink.ts): answered by its
+ * handler for `type` in its process, or SERVICE_UNAVAILABLE as a routed request is, while it is down
+ * or slow. Never rejects. The types it asks are no client's to route: only the core sends them. */
+ call(service: string, type: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+ return new Promise((resolve) => { ask(service, type, payload, THE_CORE, resolve) })
+ },
+
/** Tell a service something it needs to know; false when it is not connected to hear it. With
* `untilDelivered`, what it misses is said again when it next connects. */
notify(service: string, frame: ServiceFrame, opts: { untilDelivered?: boolean } = {}): boolean {
diff --git a/cli/src/harnessd/master.spec.ts b/cli/src/harnessd/master.spec.ts
index a0c576286..2396f6eb7 100644
--- a/cli/src/harnessd/master.spec.ts
+++ b/cli/src/harnessd/master.spec.ts
@@ -459,11 +459,14 @@ describe('runMaster', () => {
runMaster({
nodePath: process.execPath, execArgv: [], scriptPath: script, pidFile,
restoreUpdate: () => {}, confirmUpdate: () => {},
- env: { ...process.env, HARNESSD_SERVICES: 'search,unknown', HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '10' },
+ env: { ...process.env, HARNESSD_SERVICES: 'search,unknown,monitor,usage', HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '10' },
exit: (code) => exits.push(code), onSignal: (signal, listener) => signals.set(signal, listener),
})
const lines = (): Array<Record<string, any>> => existsSync(seen) ? readFileSync(seen, 'utf8').trim().split('\n').map((line) => JSON.parse(line)) : []
await until('the crashed service to be restarted', () => lines().filter((line) => line.role === 'service:search').length === 2)
+ // The light services share one process, the edge host, which runs each of those named.
+ await until('the edge host to start', () => lines().some((line) => line.role === 'service:usage,monitor'))
+ expect(lines().find((line) => line.role === 'service:usage,monitor')).toMatchObject({ name: 'edge', flags: ['--max-old-space-size=384'] })
const core = lines().find((line) => line.role === '__run')!
const services = lines().filter((line) => line.role === 'service:search')
expect(services.map((service) => service.restarts)).toEqual(['0', '1'])
@@ -471,7 +474,7 @@ describe('runMaster', () => {
expect(services[0].token).toMatch(/^[0-9a-f]{48}$/)
expect(core.token).toBe(services[0].token)
// The core is told exactly what runs out here, in a form a core from before the list reads too.
- expect(core).toMatchObject({ processes: 'search', services: 'search' })
+ expect(core).toMatchObject({ processes: 'search,usage,monitor', services: 'search,usage,monitor' })
expect(lines().some((line) => line.role === 'service:unknown')).toBe(false)
signals.get('SIGTERM')!()
await until('the master to finish', () => exits.length > 0)
diff --git a/cli/src/harnessd/master.ts b/cli/src/harnessd/master.ts
index 226bec34b..7b7df0dc0 100644
--- a/cli/src/harnessd/master.ts
+++ b/cli/src/harnessd/master.ts
@@ -16,7 +16,7 @@ import type { MasterMessage } from './protocol.js'
import {
PROBE_ANSWER, RESUME_ENV, createReexec, decodeResume, fingerprint, readMarker, recoverFailedReexec, removeMarker, runProbe, writeMarker,
} from './reexec.js'
-import { KNOWN_SERVICES, ServiceSupervisor, serviceOptions, serviceProcessesEnv, serviceSpecs } from './services.js'
+import { SERVICE_HOSTS, ServiceSupervisor, serviceOptions, serviceProcessesEnv, serviceSpecs } from './services.js'
import {
DEFAULT_SUPERVISOR_OPTIONS, Supervisor, type CoreHandle, type SupervisorDeps, type SupervisorOptions, type SupervisorStatus,
} from './supervisor.js'
@@ -221,7 +221,7 @@ export function probeMaster(config: { env: NodeJS.ProcessEnv; execArgv: string[]
const handed = config.env[RESUME_ENV]
const resume = decodeResume(handed)
if (handed !== undefined && !resume) throw new Error('the state it would be handed is not one this master can read')
- serviceSpecs(config.env, KNOWN_SERVICES)
+ serviceSpecs(config.env, SERVICE_HOSTS)
const inert = { wallClock: () => Date.now() } as unknown as SupervisorDeps
const status = new Supervisor(inert, supervisorOptions(config.env, config.execArgv), { version: config.version, resume }).status()
say(`${PROBE_ANSWER} · protocol ${status.protocol} · v${status.masterVersion}`)
@@ -294,11 +294,12 @@ export function runMaster(config: MasterConfig): Supervisor {
scriptPath: config.scriptPath, leanPath: config.serviceScriptPath, leanFingerprint: config.leanFingerprint,
folderFingerprint, exists: existsSync, sameBundle: () => bundle() === own, log,
})
- const specs = serviceSpecs(env, KNOWN_SERVICES)
+ const specs = serviceSpecs(env, SERVICE_HOSTS)
const services = new ServiceSupervisor(specs, {
spawnService: (spec, extra) => {
const script = lean.scriptFor(spec.name)
- const handle = coreHandle(spawn(named(`harnessd-${spec.name}`), [...coreExecArgv(config.execArgv, spec.heapLimitMiB), script, '__service', spec.name], {
+ // One process for every service it hosts, each on its own link to the core (services/process.ts).
+ const handle = coreHandle(spawn(named(`harnessd-${spec.name}`), [...coreExecArgv(config.execArgv, spec.heapLimitMiB), script, '__service', spec.services.join(',')], {
env: { ...env, ...extra },
stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
}))
diff --git a/cli/src/harnessd/services.spec.ts b/cli/src/harnessd/services.spec.ts
index 3bd6fc16a..5d885b454 100644
--- a/cli/src/harnessd/services.spec.ts
+++ b/cli/src/harnessd/services.spec.ts
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
- DEFAULT_SERVICE_OPTIONS, KNOWN_SERVICES, SERVICE_PROCESSES_ENV, ServiceSupervisor, serviceOptions, serviceProcessesEnv, serviceSpecs, servicesTheMasterRuns,
+ DEFAULT_SERVICE_OPTIONS, KNOWN_SERVICES, SERVICE_HOSTS, SERVICE_PROCESSES_ENV, ServiceSupervisor, serviceOptions, serviceProcessesEnv, serviceSpecs, servicesTheMasterRuns,
type ServiceSpec, type ServiceSupervisorOptions,
} from './services.js'
import type { CoreHandle } from './supervisor.js'
@@ -33,8 +33,8 @@ const options: ServiceSupervisorOptions = {
parkWindowMs: 60_000,
parkRetryMs: 120_000,
}
-const search: ServiceSpec = { name: 'search', heapLimitMiB: 512, rssLimitMiB: 1_024 }
-const devices: ServiceSpec = { name: 'devices', heapLimitMiB: 256, rssLimitMiB: 0 }
+const search: ServiceSpec = { name: 'search', services: ['search'], heapLimitMiB: 512, rssLimitMiB: 1_024 }
+const devices: ServiceSpec = { name: 'devices', services: ['devices'], heapLimitMiB: 256, rssLimitMiB: 0 }
describe('ServiceSupervisor', () => {
let children: FakeService[]
@@ -293,8 +293,8 @@ describe('ServiceSupervisor', () => {
})
it('reads the services to run from the environment, keeping only known ones, once each', () => {
- const known = { search: { heapLimitMiB: 512, rssLimitMiB: 1_024 }, devices: { heapLimitMiB: 256, rssLimitMiB: 0 } }
- expect(serviceSpecs({ HARNESSD_SERVICES: ' search, nope ,devices,search,' }, known)).toEqual([search, devices])
+ const known = { search: { services: ['search'], heapLimitMiB: 512, rssLimitMiB: 1_024 }, devices: { services: ['devices'], heapLimitMiB: 256, rssLimitMiB: 0 } }
+ expect(serviceSpecs({ HARNESSD_SERVICES: ' devices, nope ,search,devices,' }, known)).toEqual([search, devices])
// Every service in its own process unless told otherwise: isolation is the default.
expect(serviceSpecs({}, known)).toEqual([search, devices])
expect(serviceSpecs({ HARNESSD_SERVICES: 'none' }, known)).toEqual([])
@@ -305,15 +305,35 @@ describe('ServiceSupervisor', () => {
expect(serviceSpecs({ HARNESSD_SERVICES: 'search', HARNESSD_SERVICE_HEAP_LIMIT_MIB: '96' }, known)).toEqual([{ ...search, heapLimitMiB: 96 }])
expect(serviceSpecs({ HARNESSD_SERVICES: 'search', HARNESSD_SERVICE_HEAP_LIMIT_MIB: 'lots' }, known)).toEqual([search])
})
+
+ it('runs the services a host shares in one process: those named of them, or all of them by its name', () => {
+ const edge = { services: ['workspaces', 'usage', 'monitor'], heapLimitMiB: 256, rssLimitMiB: 512 }
+ const hosts = { search: { services: ['search'], heapLimitMiB: 512, rssLimitMiB: 1_024 }, edge }
+ expect(serviceSpecs({}, hosts)).toEqual([search, { name: 'edge', ...edge }])
+ expect(serviceSpecs({ HARNESSD_SERVICES: 'monitor,workspaces' }, hosts)).toEqual([{ name: 'edge', ...edge, services: ['workspaces', 'monitor'] }])
+ expect(serviceSpecs({ HARNESSD_SERVICES: 'edge,search' }, hosts)).toEqual([search, { name: 'edge', ...edge }])
+ expect(serviceSpecs({ HARNESSD_SERVICES: 'usage' }, hosts)).toEqual([{ name: 'edge', ...edge, services: ['usage'] }])
+ })
+
+ it('knows every service each process this build runs hosts, and each in one process only', () => {
+ const hosted = Object.values(SERVICE_HOSTS).flatMap((host) => host.services)
+ expect(KNOWN_SERVICES).toEqual(hosted)
+ expect(new Set(hosted).size).toBe(hosted.length)
+ expect(SERVICE_HOSTS.edge.services).toEqual(['workspaces', 'usage', 'monitor', 'projects'])
+ })
})
describe('which services the core leaves to its master', () => {
- const known = { search: {}, viewers: {}, workspaces: {}, teams: {} }
+ const known = ['search', 'viewers', 'workspaces', 'teams']
const supervised = { HARNESSD_SUPERVISED: '1', HARNESSD_SERVICE_TOKEN: 'token' }
it('is what the master says it runs, told in a form a core from before the list reads too', () => {
- const specs = serviceSpecs({ HARNESSD_SERVICES: 'search,viewers' }, KNOWN_SERVICES)
+ const specs = serviceSpecs({ HARNESSD_SERVICES: 'search,viewers' }, SERVICE_HOSTS)
expect(serviceProcessesEnv(specs)).toEqual({ [SERVICE_PROCESSES_ENV]: 'search,viewers', HARNESSD_SERVICES: 'search,viewers' })
+ // By service, not by process: a core from before the edge host routes the services it knows of it.
+ const hosted = serviceSpecs({ HARNESSD_SERVICES: 'edge' }, SERVICE_HOSTS)
+ expect(serviceProcessesEnv(hosted)).toEqual({ [SERVICE_PROCESSES_ENV]: 'workspaces,usage,monitor,projects', HARNESSD_SERVICES: 'workspaces,usage,monitor,projects' })
+ expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv(hosted) }, known)]).toEqual(['workspaces'])
expect(serviceProcessesEnv([])).toEqual({ [SERVICE_PROCESSES_ENV]: '', HARNESSD_SERVICES: 'none' })
expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv(specs) }, known)]).toEqual(['search', 'viewers'])
expect([...servicesTheMasterRuns({ ...supervised, ...serviceProcessesEnv([]) }, known)]).toEqual([])
diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.ts
index ce3df9678..626540a0f 100644
--- a/cli/src/harnessd/services.ts
+++ b/cli/src/harnessd/services.ts
@@ -1,11 +1,12 @@
/**
- * harnessd's services, each in its own process, kept running by the master beside the core.
+ * harnessd's services, in processes of their own, kept running by the master beside the core.
*
* A service is a feature the core can run without (search, devices, models, …). In the core's process a
* service's exception is caught (core/serviceHost.ts), but a native crash, a hung event loop or a leak
- * would still take the core with it. Out here a service can only take itself down: the master restarts
- * it with backoff, kills it when it stops beating (hung) or outgrows its memory budget (leaking), parks it
- * when it keeps crashing, and the core answers its requests SERVICE_UNAVAILABLE meanwhile.
+ * would still take the core with it. Out here a service can only take its own process down, and the
+ * services that share it (`SERVICE_HOSTS`): the master restarts it with backoff, kills it when it stops
+ * beating (hung) or outgrows its memory budget (leaking), parks it when it keeps crashing, and the core
+ * answers its services' requests SERVICE_UNAVAILABLE meanwhile.
*
* The same shape as ./supervisor.ts, for many children and fewer promises: a service has no port to
* bind and no update to prove; it beats, or it is restarted. Everything that touches the operating
@@ -15,8 +16,10 @@ import { heartbeatGraceMs, isCoreMessage } from './protocol.js'
import type { CoreHandle } from './supervisor.js'
export interface ServiceSpec {
- /** The service's name, as `harness __service <name>` runs it. */
+ /** The process's name: what the master logs it as and the process is titled (`harnessd <name>`). */
name: string
+ /** The services it runs, as `harness __service <a>,<b>` names them, each on its own link to the core. */
+ services: readonly string[]
/** The V8 heap limit it runs with, MiB; its budget is a share of it. */
heapLimitMiB: number
/** Resident memory past which it is restarted, MiB; 0: off. */
@@ -24,7 +27,7 @@ export interface ServiceSpec {
}
export interface ServiceSupervisorDeps {
- /** Start a service's process with these extra environment variables. */
+ /** Start a process with these extra environment variables, running every service its spec names. */
spawnService(spec: ServiceSpec, env: Record<string, string>): CoreHandle
/** A monotonic clock, in ms. */
now(): number
@@ -286,22 +289,38 @@ export class ServiceSupervisor {
}
}
+/** A process the services run in: the services it hosts, and its memory budget. */
+export type ServiceHostSpec = Omit<ServiceSpec, 'name'>
+
/**
- * The services this build runs in their own processes, with their memory budgets: every one, unless
+ * The processes this build runs its services in, with their memory budgets: every one, unless
* `HARNESSD_SERVICES` names a subset (`search,viewers`) or `none` (see `serviceSpecs`). A service that
* is not out here runs inside the core's process, behind the service host's guard, as before.
+ *
+ * A process per risk, not per feature (docs/design/2026-10-06-core-boundary-next.md, "The target
+ * shape"): native code (search's `node:sqlite`), memory and child-process herds (the viewers' servers)
+ * each get their own, so one feature cannot take another down. The light services are pure JavaScript
+ * answering requests, and share one: a fault in one can cost the others in the edge host, never the
+ * core, and the master restarts the host. Each is one process of about 60 MiB at idle; apart, they
+ * would cost that four times.
*/
-export const KNOWN_SERVICES: Readonly<Record<string, Omit<ServiceSpec, 'name'>>> = {
- search: { heapLimitMiB: 1_024, rssLimitMiB: 2_048 },
+export const SERVICE_HOSTS: Readonly<Record<string, ServiceHostSpec>> = {
+ search: { services: ['search'], heapLimitMiB: 1_024, rssLimitMiB: 2_048 },
// Its file watches on every harness's workspace; the viewer servers it starts are processes of their
// own, outside this budget.
- viewers: { heapLimitMiB: 512, rssLimitMiB: 1_024 },
- // The git work runs in git's own processes; this one only holds the agents the core sent it.
- workspaces: { heapLimitMiB: 256, rssLimitMiB: 512 },
+ viewers: { services: ['viewers'], heapLimitMiB: 512, rssLimitMiB: 1_024 },
+ // The git work (workspaces, the project readers) runs in git's own processes, and the monitor's
+ // samples in ps's and ioreg's; what it holds is the agents the core sent it and one parsed sample.
+ // The monitor parses up to 8 MB of ioreg output per Monitor poll on a Mac with a GPU, hence more
+ // than workspaces alone had.
+ edge: { services: ['workspaces', 'usage', 'monitor', 'projects'], heapLimitMiB: 384, rssLimitMiB: 768 },
// The prompt scopes hold a few drafts and fingerprints per agent: small, bounded state.
- teams: { heapLimitMiB: 256, rssLimitMiB: 512 },
+ teams: { services: ['teams'], heapLimitMiB: 256, rssLimitMiB: 512 },
}
+/** Every service this build can run outside the core's process: what `HARNESSD_SERVICES` names. */
+export const KNOWN_SERVICES: readonly string[] = Object.values(SERVICE_HOSTS).flatMap((host) => host.services)
+
/** Service timings from the environment (for tests and support); anything unset or invalid keeps its default. */
export function serviceOptions(env: NodeJS.ProcessEnv): ServiceSupervisorOptions {
const read = (name: string, fallback: number, min: number): number => {
@@ -333,7 +352,9 @@ export const SERVICE_PROCESSES_ENV = 'HARNESSD_SERVICE_PROCESSES'
* and runs none of them a second time.
*/
export function serviceProcessesEnv(specs: readonly ServiceSpec[]): Record<string, string> {
- const names = specs.map((spec) => spec.name).join(',')
+ // The services, not the processes: a core knows what it routes by service, and one from before the
+ // edge host still finds the services it knows here (workspaces) and runs the rest itself.
+ const names = specs.flatMap((spec) => spec.services).join(',')
return { [SERVICE_PROCESSES_ENV]: names, HARNESSD_SERVICES: names || 'none' }
}
@@ -345,25 +366,26 @@ export function serviceProcessesEnv(specs: readonly ServiceSpec[]): Record<strin
* released master that ran none, and answered search, the viewers, workspaces and the teams
* SERVICE_UNAVAILABLE until the master restarted (e2e/releaseRehearsal.e2e.ts). None without a master.
*/
-export function servicesTheMasterRuns(env: NodeJS.ProcessEnv, known: Readonly<Record<string, unknown>>): Set<string> {
+export function servicesTheMasterRuns(env: NodeJS.ProcessEnv, known: readonly string[]): Set<string> {
if (env.HARNESSD_SUPERVISED !== '1' || !env.HARNESSD_SERVICE_TOKEN) return new Set()
const said = env[SERVICE_PROCESSES_ENV] ?? env.HARNESSD_SERVICES ?? ''
- return new Set(said.split(',').map((name) => name.trim()).filter((name) => name && Object.hasOwn(known, name)))
+ return new Set(said.split(',').map((name) => name.trim()).filter((name) => known.includes(name)))
}
/**
- * The services to run in their own processes: every one this build knows, unless `HARNESSD_SERVICES`
- * names a subset; `none` (or empty) runs them all inside the core's process, for debugging or a quick
- * way back. Isolation is the point of the split (one service failing costs only itself), so it is the
- * default, not an opt-in. Only names this build knows. `HARNESSD_SERVICE_HEAP_LIMIT_MIB` gives every
- * one the same heap limit instead (tests, support).
+ * The processes to run the services in: every service this build knows, unless `HARNESSD_SERVICES`
+ * names a subset, by service (`search,workspaces`) or by process (`edge`, every service it hosts); `none`
+ * (or empty) runs them all inside the core's process, for debugging or a quick way back. Isolation is
+ * the point of the split (one service failing costs only its process), so it is the default, not an
+ * opt-in. Each process hosts the services named of its own, and is not started for none.
+ * `HARNESSD_SERVICE_HEAP_LIMIT_MIB` gives every one the same heap limit instead (tests, support).
*/
-export function serviceSpecs(env: NodeJS.ProcessEnv, known: Readonly<Record<string, Omit<ServiceSpec, 'name'>>>): ServiceSpec[] {
- const names = env.HARNESSD_SERVICES === undefined
- ? Object.keys(known)
- : env.HARNESSD_SERVICES.split(',').map((name) => name.trim()).filter((name) => name && name !== 'none')
+export function serviceSpecs(env: NodeJS.ProcessEnv, hosts: Readonly<Record<string, ServiceHostSpec>>): ServiceSpec[] {
+ const named = env.HARNESSD_SERVICES === undefined ? null
+ : new Set(env.HARNESSD_SERVICES.split(',').map((name) => name.trim()).filter((name) => name && name !== 'none'))
const heap = Number(env.HARNESSD_SERVICE_HEAP_LIMIT_MIB)
- return [...new Set(names)].filter((name) => Object.hasOwn(known, name)).map((name) => ({
- name, ...known[name], ...(Number.isInteger(heap) && heap > 0 ? { heapLimitMiB: heap } : {}),
- }))
+ return Object.entries(hosts).flatMap(([name, host]) => {
+ const services = host.services.filter((service) => !named || named.has(service) || named.has(name))
+ return services.length ? [{ name, ...host, services, ...(Number.isInteger(heap) && heap > 0 ? { heapLimitMiB: heap } : {}) }] : []
+ })
}
diff --git a/cli/src/leanEntry.spec.ts b/cli/src/leanEntry.spec.ts
index 4e75e51bc..5b882152c 100644
--- a/cli/src/leanEntry.spec.ts
+++ b/cli/src/leanEntry.spec.ts
@@ -13,12 +13,12 @@ import { fileURLToPath } from 'node:url'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { LEAN_ENTRY, readLeanBundle, writeLeanBundle } from './harnessd/leanBundle.js'
import { PROBE_ANSWER } from './harnessd/reexec.js'
-import { KNOWN_SERVICES } from './harnessd/services.js'
+import { KNOWN_SERVICES, SERVICE_HOSTS } from './harnessd/services.js'
const CLI_ROOT = fileURLToPath(new URL('..', import.meta.url))
-const ROLES = ['master', ...Object.keys(KNOWN_SERVICES)]
+const ROLES = ['master', ...KNOWN_SERVICES]
const RUNNER: Record<string, string> = { master: 'masterProcess' }
-for (const name of Object.keys(KNOWN_SERVICES)) RUNNER[name] = `${name}Process`
+for (const name of KNOWN_SERVICES) RUNNER[name] = `${name}Process`
describe('the lean bundle a release carries', () => {
let scratch = ''
@@ -58,9 +58,10 @@ describe('the lean bundle a release carries', () => {
}
})
- it('brings no zod to the master, search or workspaces', () => {
+ it('brings no zod to the master, search or the edge host', () => {
expect(hasZod(new Set(files.keys())), 'the bundle still holds zod, for the services whose own code uses it').toBe(true)
- for (const role of ['master', 'search', 'workspaces']) expect(hasZod(loads(role)), role).toBe(false)
+ // The edge host's services share one process: zod in any of them would be in all of them.
+ for (const role of ['master', 'search', ...SERVICE_HOSTS.edge.services]) expect(hasZod(loads(role)), role).toBe(false)
})
it('passes the release script\'s check, which a lean bundle that breaks a process does not', async () => {
diff --git a/cli/src/serviceProcess.spec.ts b/cli/src/serviceProcess.spec.ts
index d3fb7644b..1a1181256 100644
--- a/cli/src/serviceProcess.spec.ts
+++ b/cli/src/serviceProcess.spec.ts
@@ -1,5 +1,6 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { SERVICE_RUNNERS, startServiceProcess, type ServiceProcessOptions } from './serviceProcess.js'
+import type { ServiceHost, ServiceHostOptions, ServiceProcess } from './services/process.js'
import { KNOWN_SERVICES } from './harnessd/services.js'
const local = vi.hoisted(() => ({ socket: '/data/daemon-18473.sock' as string | null }))
@@ -13,28 +14,75 @@ describe('a service in its own process', () => {
afterEach(() => { process.title = title; local.socket = '/data/daemon-18473.sock'; vi.restoreAllMocks() })
it('can run every service the master knows, and loads each one\'s runner on its own', async () => {
- expect([...SERVICE_RUNNERS.keys()].sort()).toEqual(Object.keys(KNOWN_SERVICES).sort())
+ expect([...SERVICE_RUNNERS.keys()].sort()).toEqual([...KNOWN_SERVICES].sort())
for (const [name, load] of SERVICE_RUNNERS) expect(typeof await load(), name).toBe('function')
- })
+ // Every service's own code, imported: seconds on a loaded machine, not the default five.
+ }, 60_000)
+
+ /** A process that touches no channel, signal or exit: what it was asked to run, and what it was given. */
+ const fakeHost = () => {
+ const hosted: Array<{ options: ServiceHostOptions; services: ServiceProcess[] }> = []
+ const host = (options: ServiceHostOptions): ServiceHost => {
+ const entry = { options, services: [] as ServiceProcess[] }
+ hosted.push(entry)
+ return { add: (service) => { entry.services.push(service) }, leave: () => {} }
+ }
+ return { host, hosted }
+ }
it('runs the one it is named, against the core\'s socket, with the master\'s token', async () => {
const seen: ServiceProcessOptions[] = []
- const handle = { stop: () => {} }
+ const handle = { stop: vi.fn() }
const loaded: string[] = []
const runners = new Map([
['search', async () => { loaded.push('search'); return (options: ServiceProcessOptions) => { seen.push(options); return handle } }],
['viewers', async () => { loaded.push('viewers'); return () => handle }],
])
+ const { host, hosted } = fakeHost()
process.env.HARNESSD_SERVICE_TOKEN = 'token'
try {
- expect(await startServiceProcess('search', { runners })).toBe(handle)
+ await startServiceProcess('search', { runners, host })
} finally { delete process.env.HARNESSD_SERVICE_TOKEN }
expect(loaded).toEqual(['search'])
expect(process.title).toBe('harnessd-search')
// Its lines are stamped like the core's and the master's in the log they share.
expect(stamped.times).toBe(1)
expect(seen).toEqual([{ dataDir: expect.any(String), socketPath: '/data/daemon-18473.sock', machineId: expect.any(String), token: 'token' }])
- expect(await startServiceProcess('viewers', { runners })).toBe(handle)
+ expect(hosted).toEqual([{ options: { name: 'search', services: ['search'] }, services: [handle] }])
+ })
+
+ it('runs several in one process, as its master names it, each started on its own; stopping it stops each', async () => {
+ const started: string[] = []
+ const stops = { workspaces: vi.fn(), usage: vi.fn(async () => {}) }
+ const runners = new Map(Object.entries(stops).map(([name, stop]) => [name, async () => () => { started.push(name); return { stop } }]))
+ const { host, hosted } = fakeHost()
+ process.env.HARNESSD_SERVICE = 'edge'
+ try {
+ const running = await startServiceProcess(' workspaces,usage ,workspaces', { runners, host })
+ await running.stop()
+ } finally { delete process.env.HARNESSD_SERVICE }
+ expect(started).toEqual(['workspaces', 'usage'])
+ expect(process.title).toBe('harnessd-edge')
+ expect(hosted[0].options).toEqual({ name: 'edge', services: ['workspaces', 'usage'] })
+ expect(hosted[0].services).toHaveLength(2)
+ expect(stops.workspaces).toHaveBeenCalledOnce()
+ expect(stops.usage).toHaveBeenCalledOnce()
+ })
+
+ it('leaves off a service that cannot start and runs the others; with none started it fails as a lone one did', async () => {
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+ const fails = async () => () => { throw new Error('injected fault: usage') }
+ const runners = new Map([['usage', fails], ['monitor', async () => () => ({ stop: () => {} })]])
+ const { host, hosted } = fakeHost()
+ await startServiceProcess('usage,monitor', { runners, host })
+ expect(hosted[0].services).toHaveLength(1)
+ expect(error).toHaveBeenCalledWith('[service usage] did not start · injected fault: usage')
+ await expect(startServiceProcess('usage', { runners, host })).rejects.toThrow('injected fault: usage')
+ // Nothing started, no process beats for it: the master sees it end before its first heartbeat.
+ expect(hosted).toHaveLength(1)
+ const thrown = new Map([['usage', async () => () => { throw 'not an error' }]])
+ await expect(startServiceProcess('usage', { runners: thrown, host })).rejects.toBe('not an error')
+ expect(error).toHaveBeenCalledWith('[service usage] did not start · not an error')
})
it('refuses, with exit 2 and why, a service this build does not know or a core with no socket', async () => {
@@ -42,11 +90,16 @@ describe('a service in its own process', () => {
const exit = vi.fn((code: number): never => { throw new Error(`exit ${code}`) })
await expect(startServiceProcess('nope', { runners: new Map(), exit })).rejects.toThrow('exit 2')
await expect(startServiceProcess(undefined, { runners: new Map(), exit })).rejects.toThrow('exit 2')
+ await expect(startServiceProcess(' , ', { runners: new Map(), exit })).rejects.toThrow('exit 2')
+ // One name it does not know refuses the process: its master is from another build.
+ await expect(startServiceProcess('search,nope', { exit })).rejects.toThrow('exit 2')
local.socket = null
await expect(startServiceProcess('search', { exit })).rejects.toThrow('exit 2')
expect(error.mock.calls.map((call) => call[0])).toEqual([
'[service] nope: no such service in this build',
'[service] (none): no such service in this build',
+ '[service] (none): no such service in this build',
+ '[service] nope: no such service in this build',
'[service] search: the core has no local socket to reach',
])
const processExit = vi.spyOn(process, 'exit').mockImplementation(((code: number) => { throw new Error(`process.exit ${code}`) }) as never)
diff --git a/cli/src/serviceProcess.ts b/cli/src/serviceProcess.ts
index 4bc4fb7f4..2b6afbc5b 100644
--- a/cli/src/serviceProcess.ts
+++ b/cli/src/serviceProcess.ts
@@ -1,10 +1,11 @@
/**
- * A service in its own process (`__service <name>`), as harnessd's master starts it.
+ * Services in their own process (`__service <a>,<b>`), as harnessd's master starts them: one, or the
+ * several a host shares (harnessd/services.ts `SERVICE_HOSTS`).
*
- * Its own module, so the bundle's entry (entry.ts) can start a service that evaluates only that service:
- * each runner is imported by the process that runs it, and a search process never evaluates the
- * viewers. Isolation is the point of the split, and it cost the whole CLI per process while every one
- * evaluated the whole bundle: 115 to 160 MiB resident each at idle, measured from the bundle
+ * Its own module, so the bundle's entry (entry.ts) can start a process that evaluates only its own
+ * services: each runner is imported by the process that runs it, and a search process never evaluates
+ * the viewers. Isolation is the point of the split, and it cost the whole CLI per process while every
+ * one evaluated the whole bundle: 115 to 160 MiB resident each at idle, measured from the bundle
* (2026-10-05).
*/
import { env } from './config/env.js'
@@ -12,7 +13,7 @@ import { ensureUtf8Locale } from './lib/childLocale.js'
import { readOrMintComputerId } from './lib/computerIdentity.js'
import { localSocketPath } from './lib/localSocket.js'
import { ignoreLogWriteErrors, installTimestampedConsole } from './lib/log.js'
-import type { ServiceProcess } from './services/process.js'
+import { hostServices, type ServiceHost, type ServiceHostOptions, type ServiceProcess } from './services/process.js'
export interface ServiceProcessOptions {
dataDir: string
@@ -23,30 +24,49 @@ export interface ServiceProcessOptions {
type Runner = (options: ServiceProcessOptions) => ServiceProcess
/** Every service this build can run in its own process, and how to load its runner alone. */
-export const SERVICE_RUNNERS: ReadonlyMap<string, () => Promise<Runner>> = new Map([
+export const SERVICE_RUNNERS: ReadonlyMap<string, () => Promise<Runner>> = new Map<string, () => Promise<Runner>>([
['search', async () => (await import('./services/searchProcess.js')).runSearchService],
['viewers', async () => (await import('./services/viewersProcess.js')).runViewersService],
['workspaces', async () => (await import('./services/workspacesProcess.js')).runWorkspacesService],
+ ['usage', async () => (await import('./services/usageProcess.js')).runUsageService],
+ ['monitor', async () => (await import('./services/monitorProcess.js')).runMonitorService],
+ ['projects', async () => (await import('./services/projectsProcess.js')).runProjectsService],
['teams', async () => (await import('./services/teamsProcess.js')).runTeamsService],
])
export interface ServiceProcessDeps {
runners?: ReadonlyMap<string, () => Promise<Runner>>
+ /** The process the services run in; swapped in tests for one that touches no channel, signal or exit. */
+ host?: (options: ServiceHostOptions) => ServiceHost
exit?: (code: number) => never
}
-/** Run the service [name] until the master stops it; exits 2 for a name this build does not know. */
-export async function startServiceProcess(name: string | undefined, deps: ServiceProcessDeps = {}): Promise<ServiceProcess> {
+const describe = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/**
+ * Run the services [named] (`search`, or `workspaces,usage`) until the master stops them; exits 2 for a
+ * name this build does not know. Throws when none of them starts, as a lone service whose start throws
+ * always did: the process ends, and the master decides whether to try again.
+ */
+export async function startServiceProcess(named: string | undefined, deps: ServiceProcessDeps = {}): Promise<ServiceProcess> {
const runners = deps.runners ?? SERVICE_RUNNERS
const exit = deps.exit ?? ((code: number) => process.exit(code))
+ const names = [...new Set((named ?? '').split(',').map((name) => name.trim()).filter(Boolean))]
const socketPath = localSocketPath(env.ADAPTER_DATA_DIR, env.PORT)
- const load = name === undefined ? undefined : runners.get(name)
- if (!load || !socketPath) {
- console.error(`[service] ${name ?? '(none)'}: ${socketPath ? 'no such service in this build' : 'the core has no local socket to reach'}`)
+ const unknown = names.length ? names.find((name) => !runners.has(name)) : '(none)'
+ if (unknown !== undefined) {
+ console.error(`[service] ${unknown}: no such service in this build`)
+ return exit(2)
+ }
+ if (!socketPath) {
+ console.error(`[service] ${names.join(',')}: the core has no local socket to reach`)
return exit(2)
}
- // The same name as the hard link it was exec'd through (harnessd/processName.ts): one name in ps and Activity Monitor.
- process.title = `harnessd-${name}`
+ // The master names the process (`edge` for the services it shares); a process started by hand is named
+ // for what it runs. The same name as the hard link it was exec'd through (harnessd/processName.ts): one
+ // name in ps and Activity Monitor.
+ const title = process.env.HARNESSD_SERVICE || names.join(',')
+ process.title = `harnessd-${title}`
// Its lines share the daemon's log with the master's: a write a full disk refuses is dropped, not fatal.
ignoreLogWriteErrors()
// As every daemon process did at load: a service that runs `ps` or `git` must not get mangled output.
@@ -54,11 +74,30 @@ export async function startServiceProcess(name: string | undefined, deps: Servic
// Its lines go to the daemon's log between the core's and the master's, which are stamped: unstamped,
// a service's said nothing of when.
installTimestampedConsole()
- const run = await load()
- return run({
+ const loaded = await Promise.all(names.map(async (name) => [name, await runners.get(name)!()] as const))
+ const options: ServiceProcessOptions = {
dataDir: env.ADAPTER_DATA_DIR,
socketPath,
machineId: readOrMintComputerId(env.ADAPTER_COMPUTER_ID_FILE, env.ADAPTER_COMPUTER_ID),
token: process.env.HARNESSD_SERVICE_TOKEN ?? '',
- })
+ }
+ const running: ServiceProcess[] = []
+ let failure: unknown = null
+ for (const [name, run] of loaded) {
+ try {
+ running.push(run(options))
+ } catch (error) {
+ // One service that cannot start is off, and the others in its process run on: the core answers its
+ // requests SERVICE_UNAVAILABLE, as for any service that is down. In-process, the core's host does
+ // the same with a start that throws (core/serviceHost.ts).
+ failure ??= error
+ console.error(`[service ${name}] did not start · ${describe(error)}`)
+ }
+ }
+ if (!running.length) throw failure
+ const host = (deps.host ?? hostServices)({ name: title, services: names })
+ for (const service of running) host.add(service)
+ return {
+ stop: () => Promise.allSettled(running.map((service) => Promise.resolve().then(() => service.stop()))).then(() => {}),
+ }
}
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index eb6d05faf..996239454 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -9,11 +9,13 @@ let several people build features at once without touching the core or each othe
only through `core` (`src/core/api.ts`). If `CoreApi` lacks something you need, add it to `CoreApi`
in a separate, reviewed change; never import a core module, the registry, `cli.ts` or
`backendSocket.ts`.
-2. **If the apps call it, declare its requests and answer them from start.** Export the frame types,
- `export const <NAME>_REQUESTS = ['<name>_list', …] as const`, and return their handlers from start:
- `{ <name>_list: (payload, asker) => reply }`. A handler returns the reply (or a promise of it); the
- core routes the request to it, replies under the asker's request id, and never waits in line for it.
- Never add a case to `backendSocket.ts`'s switch or a slot to `BackendSocket`.
+2. **If the apps call it, declare its requests and answer them from start.** Declare the frame types in
+ `src/core/api.ts`, `export const <NAME>_REQUESTS = ['<name>_list', …] as const`, re-export them from
+ your module, and return their handlers from start: `{ <name>_list: (payload, asker) => reply }`. The
+ core routes them from that list alone, so a service in its own process is never loaded into the
+ core's to learn them. A handler returns the reply (or a promise of it); the core routes the request
+ to it, replies under the asker's request id, and never waits in line for it. Never add a case to
+ `backendSocket.ts`'s switch or a slot to `BackendSocket`.
- Trust `asker`, never the payload: `if (!asker.owner) return { error: 'OWNER_REQUIRED' }`.
- While the service is off, its requests are answered `SERVICE_UNAVAILABLE`, never `UNSUPPORTED`
(the apps read that as "update the CLI"). That is why the types are declared up front.
@@ -39,32 +41,47 @@ let several people build features at once without touching the core or each othe
## Running in its own process
-A service that can crash natively, hang or leak should run in its own process, where it costs only
-itself. Search, the viewers, workspaces and the teams' prompt scopes do, by default: every service in
-`KNOWN_SERVICES` runs in its own process unless `HARNESSD_SERVICES` names a subset
-(`search,viewers`), and `HARNESSD_SERVICES=none` runs them all inside the core's process (for debugging
-or a quick way back).
+A service that can crash natively, hang or leak should run in a process of its own, where it costs only
+that process. A process per risk, not per feature: search (native `node:sqlite`), the viewers (their
+servers), the teams' prompt scopes, and the edge host, one process for the light services that only
+answer requests (workspaces, usage, the monitor, the project readers). A fault in one of the edge
+host's services can cost the others in it, never the core. Every service in `KNOWN_SERVICES` runs out
+of the core's process by default, unless `HARNESSD_SERVICES` names a subset, by service
+(`search,usage`) or by process (`edge`), and `HARNESSD_SERVICES=none` runs them all inside the core's
+process (for debugging or a quick way back).
-- `src/harnessd/services.ts` runs it (`KNOWN_SERVICES`, with its memory budget). The core routes the
- requests it declared (its `<NAME>_REQUESTS`) to its process, and the same handlers answer them there.
+- `src/harnessd/services.ts` runs it (`SERVICE_HOSTS`: each process, the services it hosts and its
+ memory budget, one heartbeat for all of them). The core routes the requests it declared (its
+ `<NAME>_REQUESTS`) to its process, and the same handlers answer them there.
- `src/serviceProcess.ts` starts it (`SERVICE_RUNNERS`, which must name every service in
- `KNOWN_SERVICES`): a process imports only the runner it is named. From a release, it runs on the lean
- bundle cli.js carries for the master and the services (`src/harnessd/leanBundle.ts`), split so that a
- service loads its own code and nothing else: 61 to 77 MiB resident at idle (20 to 35 MiB physical
- footprint), against 118 to 131 (54 to 90) when each started on cli.js (2026-10-05). It is only an
- optimisation: the master starts a service from cli.js whenever the lean bundle cannot be used
- (`src/harnessd/leanServices.ts`), and the release script refuses one that does not load
- (`scripts/check-lean-bundle.mjs`).
+ `KNOWN_SERVICES`): a process imports only the runners it is named (`__service workspaces,usage`), and
+ a service whose start throws there is left off while the others in its process run. The core's
+ in-process starts are in `inline.ts`, which the core loads only when a service runs in its process:
+ a service in its own leaves the core's import closure (`src/architecture.spec.ts`). From a release,
+ it runs on the lean bundle cli.js carries for the master and the services
+ (`src/harnessd/leanBundle.ts`), split so that a service loads its own code and nothing else: 61 to 77
+ MiB resident at idle (20 to 35 MiB physical footprint), against 118 to 131 (54 to 90) when each
+ started on cli.js (2026-10-05). It is only an optimisation: the master starts a service from cli.js
+ whenever the lean bundle cannot be used (`src/harnessd/leanServices.ts`), and the release script
+ refuses one that does not load (`scripts/check-lean-bundle.mjs`).
- **What a service imports is what its process costs.** Import from small modules: one schema module
pulled in for a constant brought zod to search and workspaces, 8 MiB each (`src/dsh/id.ts`). A
failing import fails the service's start, loudly, and the master parks it. `src/leanEntry.spec.ts`
- holds each process to its own code, and the master, search and workspaces to no zod.
-- `src/services/process.ts` is the process's side: heartbeats to the master, the connection to the
- core with the master's token, reconnecting after core restarts.
+ holds each process to its own code, and the master, search and the edge host to no zod.
+- `src/services/process.ts` is the process's side: `hostServices` beats to the master and stops every
+ service before the process exits; `runServiceProcess` is each service's own connection to the core,
+ with the master's token, reconnecting after core restarts. `<host>.crash` and `<host>.leak`, or a
+ service's own, crash or leak the whole process: it is one process.
- `src/core/serviceLinks.ts` is the core's side: it routes those requests to the process, answers
`SERVICE_UNAVAILABLE` while it is down, and holds what the service must not miss.
- `src/services/searchProcess.ts` is the example to copy. `e2e/serviceProcesses.e2e.ts` is the proof
to copy: killed, hung (SIGSTOP), leaking, crashing on every start.
+- A port the core calls asynchronously, answered when it is read, can be a request to the process: the
+ monitor shows how (`src/services/monitorProcess.ts`, `src/core/monitorLink.ts`). The core asks with
+ `serviceLinks.call`, under types only it sends (the port's member names, so a test's fault names the
+ same member either way), and reads an answer that does not come as the port's fallbacks. A light
+ service that reads the agents asks for them as each request starts (`service_query live` or
+ `advertised`, `src/core/agentQueries.ts`; `src/services/processCoreApi.ts`).
- A port the core calls in line (while it builds a frame, say) cannot wait on another process. The
viewers show how (`src/services/viewersProcess.ts`, `src/core/viewersLink.ts`): the process tells
the core its answers whenever they change (a `service_query` kind the core answers), the core keeps
diff --git a/cli/src/services/inline.spec.ts b/cli/src/services/inline.spec.ts
new file mode 100644
index 000000000..c66029e44
--- /dev/null
+++ b/cli/src/services/inline.spec.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import * as inline from './inline.js'
+import { startMonitor } from './monitor.js'
+import { startProjects } from './projects.js'
+import { startSearch } from './search.js'
+import { startUsage } from './usage.js'
+import { startViewers } from './viewers.js'
+import { startWorkspaces } from './workspaces.js'
+
+describe('the services the core runs in its own process only when they do not run in theirs', () => {
+ it('are their own starts, unchanged: the same services either way', () => {
+ expect({ ...inline }).toEqual({ startMonitor, startProjects, startSearch, startUsage, startViewers, startWorkspaces })
+ })
+})
diff --git a/cli/src/services/inline.ts b/cli/src/services/inline.ts
new file mode 100644
index 000000000..c19db8d63
--- /dev/null
+++ b/cli/src/services/inline.ts
@@ -0,0 +1,18 @@
+/**
+ * The services that run in a process of their own by default (harnessd/services.ts `SERVICE_HOSTS`), for
+ * when they run in the core's instead: with `HARNESSD_SERVICES=none` (debugging, or a quick way back), a
+ * subset named, a master too old to run them, or no master at all (`harness start -f`).
+ *
+ * The core imports this module only then, and only dynamically (core/main.ts): what it reaches is the
+ * services' own code, which the core's process then never loads by default. That is how a service in its
+ * own process leaves the core's import closure, which src/architecture.spec.ts holds to a budget and
+ * walks without following this one import (docs/design/2026-10-06-core-boundary-next.md, "The target,
+ * and its test"). The core still routes these services' requests and holds their fallbacks: both are
+ * declared in core/api.ts, which it loads either way.
+ */
+export { startMonitor } from './monitor.js'
+export { startProjects } from './projects.js'
+export { startSearch } from './search.js'
+export { startUsage } from './usage.js'
+export { startViewers } from './viewers.js'
+export { startWorkspaces } from './workspaces.js'
diff --git a/cli/src/services/models.ts b/cli/src/services/models.ts
index 66dd05381..017ba0525 100644
--- a/cli/src/services/models.ts
+++ b/cli/src/services/models.ts
@@ -33,21 +33,9 @@ import { parseRuntimeProfile, type RuntimeModelOption } from '../lib/runtimeProf
import { ensureManagedGrid } from '../lib/runtimeInstall.js'
import { internalOnThrow } from './requestErrors.js'
-/**
- * The requests models answers for the apps.
- *
- * The Model Manager's grid commands, `grid_fleet_run` and `grid_fleet_cancel`, are still the socket's:
- * a command is a job of the connection that started it, and a cancel stops only that connection's job
- * (`lib/gridFleetRpc.ts`), while a request answered here knows who asked but not over which connection.
- * Their handshake, `grid_fleet_capabilities`, stays beside them: the Grid harness runs a command only
- * after it, and reads an answer without its protocol as "update Harness".
- * The saved APIs and the Codex profiles came out of the socket's switch (launchTargetRequests).
- */
-export const MODELS_REQUESTS = [
- 'grid_models_list', 'models_list',
- 'grid_fleet_models_list', 'grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop',
- 'api_connections', 'codex_profiles_list', 'codex_profile_link',
-] as const
+/** The requests models answers for the apps, declared in core/api.ts for the core to route (why the Model
+ * Manager's grid commands are not among them is said there). */
+export { MODELS_REQUESTS } from '../core/api.js'
export function startModels(core: CoreApi, ports: CorePorts): ServiceRequests {
// Grid is an add-on (`lib/gridAttach.ts`): nothing on this path installs `grid`, signs this machine in
diff --git a/cli/src/services/monitor.ts b/cli/src/services/monitor.ts
index da79c5fc6..da534f094 100644
--- a/cli/src/services/monitor.ts
+++ b/cli/src/services/monitor.ts
@@ -10,8 +10,8 @@ import { createHarnessStorageReader } from '../lib/harnessTelemetry.js'
import { readMachineResources } from '../lib/machineResources.js'
import { internalOnThrow } from './requestErrors.js'
-/** The request the monitor answers for the apps. */
-export const MONITOR_REQUESTS = ['machine_resources'] as const
+/** The request the monitor answers for the apps, declared in core/api.ts for the core to route. */
+export { MONITOR_REQUESTS } from '../core/api.js'
export interface MonitorDeps {
/** The machine's own totals. */
diff --git a/cli/src/services/monitorProcess.spec.ts b/cli/src/services/monitorProcess.spec.ts
new file mode 100644
index 000000000..27d569f09
--- /dev/null
+++ b/cli/src/services/monitorProcess.spec.ts
@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CoreApi, CorePorts, MonitorPort } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { runMonitorService } from './monitorProcess.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcessOptions } from './process.js'
+
+// The real default reaches a real socket and runs `ps`: never in a test.
+vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))
+
+const agent = (agentId: string) => ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', cwd: `/work/${agentId}` }) as RegisteredSession
+const ASKER = { local: true, owner: true }
+
+describe('the machine monitor in its own process', () => {
+ afterEach(() => vi.clearAllMocks())
+
+ const setup = () => {
+ let options: ServiceProcessOptions | null = null
+ let api: CoreApi | null = null
+ /** The agents each sample read. */
+ const sampled: string[][] = []
+ const snapshot = { agents: [], sampledAt: null, shared: [] }
+ const port = {
+ resources: vi.fn(async () => { sampled.push(api!.agents.advertised().map((session) => session.agentId)); return snapshot }),
+ storage: vi.fn(async (agents: readonly { agentId: string }[]) => new Map(agents.map((session) => [session.agentId, { workspaceBytes: 1 }]))),
+ } as unknown as MonitorPort
+ runMonitorService({
+ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
+ run: (given) => { options = given; return { stop: vi.fn() } },
+ start: (core: CoreApi, ports: CorePorts) => {
+ api = core
+ ports.monitor = port
+ return { machine_resources: async (payload) => ({ harnesses: payload.harnesses === true, read: sampled.length }) }
+ },
+ })
+ return { options: options!, port, sampled, snapshot }
+ }
+
+ it('answers the Monitor and the core\'s port from one set of readers, on the agents advertised as each sample starts', async () => {
+ const { options, port, sampled, snapshot } = setup()
+ expect(options).toMatchObject({ name: 'monitor', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ let advertised: Record<string, unknown> = { agents: [agent('a1')] }
+ const query = vi.fn(async (_name: string) => advertised)
+ options.onConnected!({ query } satisfies CoreConnection)
+ // The machine's own totals read no agent: the core is not asked.
+ expect(await options.requests.machine_resources!({}, ASKER)).toEqual({ harnesses: false, read: 0 })
+ expect(query).not.toHaveBeenCalled()
+ expect(await options.requests.machine_resources!({ harnesses: true }, ASKER)).toEqual({ harnesses: true, read: 0 })
+ expect(query).toHaveBeenLastCalledWith('advertised')
+ expect(await options.requests.resources!({}, ASKER)).toEqual({ snapshot })
+ // A core that cannot say leaves the agents it said last.
+ advertised = { error: 'UNKNOWN_QUERY' }
+ await options.requests.resources!({}, ASKER)
+ query.mockRejectedValueOnce(new Error('the core went away'))
+ await options.requests.resources!({}, ASKER)
+ expect(sampled).toEqual([['a1'], ['a1'], ['a1']])
+ // What the core asks the workspaces and transcripts of, and to forget: its agents, as it sent them.
+ expect(await options.requests.storage!({ agents: [agent('a2'), { nope: true }], invalidate: true }, ASKER)).toEqual({ entries: [['a2', { workspaceBytes: 1 }]] })
+ expect(port.storage).toHaveBeenLastCalledWith([agent('a2')], true)
+ expect(await options.requests.storage!({}, ASKER)).toEqual({ entries: [] })
+ expect(port.storage).toHaveBeenLastCalledWith([], false)
+ })
+
+ it('does not run without its readers: the master starts it again, or parks it', () => {
+ expect(() => runMonitorService({ dataDir: '/data', socketPath: '/s', machineId: 'm', token: 't', run: vi.fn(), start: () => ({}) })).toThrow('the monitor did not start')
+ })
+
+ it('runs as a real service by default, answering the Monitor and the port\'s two members', () => {
+ runMonitorService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ const options = vi.mocked(runServiceProcess).mock.calls.at(-1)![0]
+ expect(options.name).toBe('monitor')
+ expect(Object.keys(options.requests).sort()).toEqual(['machine_resources', 'resources', 'storage'])
+ })
+})
diff --git a/cli/src/services/monitorProcess.ts b/cli/src/services/monitorProcess.ts
new file mode 100644
index 000000000..05639cbfd
--- /dev/null
+++ b/cli/src/services/monitorProcess.ts
@@ -0,0 +1,67 @@
+/**
+ * The machine monitor in its own process (`harness __service monitor`, in the edge host).
+ *
+ * The same readers as in the core's process (services/monitor.ts), answering two askers:
+ * - the Monitor's own request, `machine_resources`;
+ * - the core, for the readings `agents_list` adds to its rows and for a purge's forgetting, through its
+ * port (core/monitorLink.ts). Those two requests are named as the port's members, `resources` and
+ * `storage`, so that a test's fault names the same member whichever process the monitor runs in.
+ *
+ * One sample and one cache serve both, here as in the core's process. The agents a sample reads are the
+ * ones the core advertises as it starts (`service_query advertised`). The `ps`, `nvidia-smi` and `ioreg`
+ * runs, and the parse of up to 8 MB of ioreg output at each Monitor poll, are this process's alone.
+ */
+import { emptyPorts } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { startMonitor } from './monitor.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'
+import { agentsIn, processCoreApi } from './processCoreApi.js'
+
+export interface MonitorServiceOptions {
+ dataDir: string
+ socketPath: string
+ machineId: string
+ token: string
+ /** Swapped in tests for one that does not touch the real socket or process. */
+ run?: typeof runServiceProcess
+ /** Swapped in tests for readers that run no `ps` and measure no folder. */
+ start?: typeof startMonitor
+}
+
+export function runMonitorService(options: MonitorServiceOptions): ServiceProcess {
+ let advertised: RegisteredSession[] = []
+ let core: CoreConnection | null = null
+ /** The agents the core advertises now: what a sample starting now reads. A core that cannot say leaves
+ * the last ones it said. */
+ const refresh = async (): Promise<void> => {
+ advertised = agentsIn(await core?.query('advertised').catch(() => null)) ?? advertised
+ }
+ const ports = emptyPorts()
+ const answers = (options.start ?? startMonitor)(processCoreApi(options.dataDir, 'monitor', { advertised: () => advertised }), ports)
+ if (!ports.monitor) throw new Error('the monitor did not start')
+ const monitor = ports.monitor
+ const machineResources = answers.machine_resources
+ return (options.run ?? runServiceProcess)({
+ name: 'monitor',
+ socketPath: options.socketPath,
+ machineId: options.machineId,
+ token: options.token,
+ requests: {
+ // The machine's own totals read no agent; the agents' readings read the ones advertised now.
+ machine_resources: async (payload, asker) => {
+ if (payload.harnesses === true) await refresh()
+ return machineResources(payload, asker)
+ },
+ // The port's members, asked only by the core (core/monitorLink.ts). Their failures are answered
+ // SERVICE_FAILED, which the core reads as its fallbacks: rows without readings, nothing forgotten.
+ resources: async () => {
+ await refresh()
+ return { snapshot: await monitor.resources() }
+ },
+ storage: async (payload) => ({
+ entries: [...await monitor.storage(agentsIn(payload) ?? [], payload.invalidate === true)],
+ }),
+ },
+ onConnected: (connection) => { core = connection },
+ })
+}
diff --git a/cli/src/services/process.spec.ts b/cli/src/services/process.spec.ts
index b70c30207..5fd5f83b8 100644
--- a/cli/src/services/process.spec.ts
+++ b/cli/src/services/process.spec.ts
@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import WebSocket from 'ws'
import type { MasterChannel } from '../harnessd/coreLink.js'
-import { runServiceProcess, serviceFaults, type ServiceProcessOptions } from './process.js'
+import { hostServices, LEAVE_GRACE_MS, REFUSED, runServiceProcess, serviceFaults, type ServiceHostOptions, type ServiceProcessOptions } from './process.js'
/** A socket that records what it is sent, and is told what the core says. */
class FakeSocket extends EventEmitter {
@@ -17,7 +17,7 @@ class FakeSocket extends EventEmitter {
close(): void { this.closed = true }
open(): void { this.readyState = WebSocket.OPEN; this.emit('open') }
say(frame: unknown): void { this.emit('message', Buffer.from(typeof frame === 'string' ? frame : JSON.stringify(frame))) }
- drop(): void { this.readyState = WebSocket.CLOSED; this.emit('error', new Error('reset')); this.emit('close') }
+ drop(code = 1006): void { this.readyState = WebSocket.CLOSED; this.emit('error', new Error('reset')); this.emit('close', code) }
}
class FakeChannel extends EventEmitter implements MasterChannel {
@@ -27,48 +27,36 @@ class FakeChannel extends EventEmitter implements MasterChannel {
memoryUsage() { return { rss: 10, heapUsed: 5 } }
}
-describe('a service in its own process', () => {
- let sockets: FakeSocket[]
+describe('the process the services run in', () => {
let exits: number[]
- let lines: string[]
- const socket = () => sockets[sockets.length - 1]
- const run = (over: Partial<ServiceProcessOptions> = {}) => runServiceProcess({
- name: 'search',
- socketPath: '/data/daemon-1.sock',
- machineId: 'machine-1',
- token: 'token-1',
- requests: {},
+ let sigterm: (() => void) | null
+ const host = (over: Partial<ServiceHostOptions> = {}) => hostServices({
+ name: 'edge',
+ services: ['workspaces', 'usage'],
channel: new FakeChannel(),
env: {},
- connect: (url) => { const next = new FakeSocket(url); sockets.push(next); return next as unknown as WebSocket },
exit: (code) => exits.push(code),
loopDelay: { take: () => 4, stop: vi.fn() },
- log: (line) => lines.push(line),
- initialBackoffMs: 100,
- maxBackoffMs: 400,
+ onSignal: (signal, handler) => { if (signal === 'SIGTERM') sigterm = handler },
...over,
})
- beforeEach(() => { vi.useFakeTimers(); sockets = []; exits = []; lines = [] })
+ beforeEach(() => { vi.useFakeTimers(); exits = []; sigterm = null })
afterEach(() => vi.useRealTimers())
- it('connects to the core\'s socket as the service it is, with the master\'s token', () => {
- const service = run()
- expect(socket().url).toBe('ws+unix:///data/daemon-1.sock:/api/local-ws')
- socket().open()
- expect(socket().sent).toEqual([{ type: 'machine_select', payload: { machineId: 'machine-1', localProtocolVersion: 1, role: 'service', service: 'search', token: 'token-1' } }])
- service.stop()
- expect(socket().closed).toBe(true)
- })
-
- it('beats to the master as the core does, and exits when the master goes', () => {
+ it('beats to the master as the core does, one beat for all it runs, and exits when the master goes', async () => {
const channel = new FakeChannel()
const loopDelay = { take: () => 4, stop: vi.fn() }
- run({ channel, loopDelay, env: { HARNESSD_WATCHDOG_MS: '3000' } })
+ const running = host({ channel, loopDelay, env: { HARNESSD_WATCHDOG_MS: '3000' } })
+ const stops = [vi.fn(), vi.fn()]
+ for (const stop of stops) running.add({ stop })
expect(channel.beats).toEqual([{ type: 'harnessd:heartbeat', rssBytes: 10, heapUsedBytes: 5, loopDelayMs: 4 }])
vi.advanceTimersByTime(1_000)
expect(channel.beats).toHaveLength(2)
channel.emit('disconnect')
+ await vi.advanceTimersByTimeAsync(0)
+ // Every service it runs is stopped before it goes.
+ for (const stop of stops) expect(stop).toHaveBeenCalledOnce()
expect(exits).toEqual([0])
expect(loopDelay.stop).toHaveBeenCalled()
vi.advanceTimersByTime(10_000)
@@ -78,9 +66,109 @@ describe('a service in its own process', () => {
it('without a master to beat to, runs all the same', () => {
const channel = new FakeChannel()
;(channel as { send?: unknown }).send = undefined
- const service = run({ channel })
+ host({ channel })
expect(channel.beats).toEqual([])
+ })
+
+ it('stops what it runs on the master\'s SIGTERM, waiting for a stop that takes a moment, and leaves once', async () => {
+ const running = host()
+ let stopped!: () => void
+ const slow = vi.fn(() => new Promise<void>((done) => { stopped = done }))
+ const failing = vi.fn(() => { throw new Error('would not stop') })
+ running.add({ stop: slow })
+ running.add({ stop: failing })
+ sigterm!()
+ running.leave(1)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(exits).toEqual([])
+ stopped()
+ await vi.advanceTimersByTimeAsync(0)
+ expect(slow).toHaveBeenCalledOnce()
+ expect(failing).toHaveBeenCalledOnce()
+ expect(exits).toEqual([0])
+ // The bound it had set on the stop is gone with it.
+ await vi.advanceTimersByTimeAsync(LEAVE_GRACE_MS)
+ expect(exits).toEqual([0])
+ })
+
+ it('exits all the same when a service never finishes stopping', async () => {
+ const running = host({ leaveGraceMs: 300 })
+ running.add({ stop: () => new Promise<void>(() => {}) })
+ running.leave(0)
+ await vi.advanceTimersByTimeAsync(299)
+ expect(exits).toEqual([])
+ await vi.advanceTimersByTimeAsync(1)
+ expect(exits).toEqual([0])
+ })
+
+ it('crashes or leaks on purpose when a test asks it to, of the process or of any service in it', async () => {
+ host({ env: { HARNESSD_TEST_FAULTS: 'edge.crash' } })
+ await vi.advanceTimersByTimeAsync(200)
+ expect(exits).toEqual([1])
+ host({ env: { HARNESSD_TEST_FAULTS: 'usage.crash' } })
+ await vi.advanceTimersByTimeAsync(200)
+ expect(exits).toEqual([1, 1])
+ const leaking = host({ env: { HARNESSD_TEST_FAULTS: 'workspaces.leak' } })
+ vi.advanceTimersByTime(300)
+ leaking.leave(0)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(exits).toEqual([1, 1, 0])
+ // A fault of a service it does not run is not its own.
+ host({ env: { HARNESSD_TEST_FAULTS: 'search.crash' } })
+ await vi.advanceTimersByTimeAsync(1_000)
+ expect(exits).toEqual([1, 1, 0])
+ })
+
+ it('runs on this process by default: its channel, its signal, its exit', async () => {
+ // No beat may reach the test runner's own channel: this process's `send` is set aside.
+ const send = process.send
+ ;(process as { send?: unknown }).send = undefined
+ const on = vi.spyOn(process, 'once').mockImplementation(() => process)
+ const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+ try {
+ hostServices({ name: 'search', services: ['search'] })
+ expect(on).toHaveBeenCalledWith('disconnect', expect.any(Function))
+ expect(on).toHaveBeenCalledWith('SIGTERM', expect.any(Function))
+ const leave = on.mock.calls.find(([event]) => event === 'disconnect')![1] as () => void
+ leave()
+ await vi.advanceTimersByTimeAsync(0)
+ expect(exit).toHaveBeenCalledWith(0)
+ } finally {
+ ;(process as { send?: unknown }).send = send
+ on.mockRestore()
+ exit.mockRestore()
+ }
+ })
+})
+
+describe('a service in its own process', () => {
+ let sockets: FakeSocket[]
+ let lines: string[]
+ const socket = () => sockets[sockets.length - 1]
+ const run = (over: Partial<ServiceProcessOptions> = {}) => runServiceProcess({
+ name: 'search',
+ socketPath: '/data/daemon-1.sock',
+ machineId: 'machine-1',
+ token: 'token-1',
+ requests: {},
+ env: {},
+ connect: (url) => { const next = new FakeSocket(url); sockets.push(next); return next as unknown as WebSocket },
+ log: (line) => lines.push(line),
+ initialBackoffMs: 100,
+ maxBackoffMs: 400,
+ ...over,
+ })
+
+ beforeEach(() => { vi.useFakeTimers(); sockets = []; lines = [] })
+ afterEach(() => vi.useRealTimers())
+
+ it('connects to the core\'s socket as the service it is, with the master\'s token', () => {
+ const service = run()
+ expect(socket().url).toBe('ws+unix:///data/daemon-1.sock:/api/local-ws')
+ socket().open()
+ expect(socket().sent).toEqual([{ type: 'machine_select', payload: { machineId: 'machine-1', localProtocolVersion: 1, role: 'service', service: 'search', token: 'token-1' } }])
service.stop()
+ expect(socket().closed).toBe(true)
})
it('answers the requests routed to it under their own request, failures included', async () => {
@@ -172,6 +260,29 @@ describe('a service in its own process', () => {
expect(sockets).toHaveLength(6)
})
+ it('asks again only once a minute when the core refuses it: a core that does not run it out of its process', () => {
+ const service = run({ refusedBackoffMs: 60_000 })
+ socket().drop(REFUSED)
+ vi.advanceTimersByTime(59_999)
+ expect(sockets).toHaveLength(1)
+ vi.advanceTimersByTime(1)
+ expect(sockets).toHaveLength(2)
+ // Any other end is the usual backoff.
+ socket().drop()
+ vi.advanceTimersByTime(200)
+ expect(sockets).toHaveLength(3)
+ service.stop()
+ // A minute by default.
+ const refused = runServiceProcess({ name: 'store', socketPath: '/s', machineId: 'm', token: 't', requests: {}, env: {},
+ connect: (url) => { const next = new FakeSocket(url); sockets.push(next); return next as unknown as WebSocket }, log: () => {} })
+ socket().drop(REFUSED)
+ vi.advanceTimersByTime(59_999)
+ expect(sockets).toHaveLength(4)
+ vi.advanceTimersByTime(1)
+ expect(sockets).toHaveLength(5)
+ refused.stop()
+ })
+
it('stops a reconnect it had scheduled, and stopping twice is stopping once', () => {
const service = run()
socket().drop()
@@ -199,10 +310,8 @@ describe('a service in its own process', () => {
expect(serviceFaults({}, 'search')).toEqual({ start: false, crash: false, leak: false, calls: new Set() })
})
- it('fails its start when a test asks it to, before it beats or connects, as a service whose start throws', () => {
- const channel = new FakeChannel()
- expect(() => run({ channel, env: { HARNESSD_TEST_FAULTS: 'search' } })).toThrow('injected fault: search')
- expect(channel.beats).toEqual([])
+ it('fails its start when a test asks it to, before it connects, as a service whose start throws', () => {
+ expect(() => run({ env: { HARNESSD_TEST_FAULTS: 'search' } })).toThrow('injected fault: search')
expect(sockets).toEqual([])
})
@@ -242,30 +351,13 @@ describe('a service in its own process', () => {
await vi.waitFor(() => expect(lines).toContain('[service search] rejects failed · index closed'))
expect(heard).toEqual(['throws', 'rejects', undefined, 'fine'])
expect(lines).toEqual(expect.arrayContaining(['[service search] throws failed · bad row', '[service search] event failed · not an error']))
- expect(exits).toEqual([])
- })
-
- it('crashes or leaks on purpose when a test asks it to', () => {
- run({ env: { HARNESSD_TEST_FAULTS: 'search.crash' } })
- vi.advanceTimersByTime(200)
- expect(exits).toEqual([1])
- const leaking = run({ env: { HARNESSD_TEST_FAULTS: 'search.leak' } })
- vi.advanceTimersByTime(300)
- leaking.stop()
- // Without a fault, connecting is just connecting.
- run({ env: {} })
- socket().open()
- socket().say({ type: 'connected' })
- expect(lines.at(-1)).toBe('[service search] connected to the core')
})
it('says it connected on the console by default', () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const service = runServiceProcess({
name: 'search', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't', requests: {}, env: {},
- channel: Object.assign(new FakeChannel(), { send: undefined }),
connect: (url) => { const next = new FakeSocket(url); sockets.push(next); return next as unknown as WebSocket },
- loopDelay: { take: () => 0, stop: () => {} },
})
socket().open()
socket().say({ type: 'connected' })
@@ -274,24 +366,18 @@ describe('a service in its own process', () => {
log.mockRestore()
})
- it('runs on this process by default: its channel, its exit, its sockets', () => {
- // No beat may reach the test runner's own channel: this process's `send` is set aside.
- const send = process.send
- ;(process as { send?: unknown }).send = undefined
- const on = vi.spyOn(process, 'once').mockImplementation(() => process)
- const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+ it('runs on this process by default: its environment, its sockets', () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+ const before = process.env.HARNESSD_TEST_FAULTS
+ process.env.HARNESSD_TEST_FAULTS = 'search'
try {
+ expect(() => runServiceProcess({ name: 'search', socketPath: '/nonexistent/daemon.sock', machineId: 'm', token: 't', requests: {} })).toThrow('injected fault: search')
+ delete process.env.HARNESSD_TEST_FAULTS
const service = runServiceProcess({ name: 'search', socketPath: '/nonexistent/daemon.sock', machineId: 'm', token: 't', requests: {} })
- expect(on).toHaveBeenCalledWith('disconnect', expect.any(Function))
- const leave = on.mock.calls.find(([event]) => event === 'disconnect')![1] as () => void
- leave()
- expect(exit).toHaveBeenCalledWith(0)
service.stop()
} finally {
- ;(process as { send?: unknown }).send = send
- on.mockRestore()
- exit.mockRestore()
+ if (before === undefined) delete process.env.HARNESSD_TEST_FAULTS
+ else process.env.HARNESSD_TEST_FAULTS = before
log.mockRestore()
}
})
diff --git a/cli/src/services/process.ts b/cli/src/services/process.ts
index 674429040..edcb4e8af 100644
--- a/cli/src/services/process.ts
+++ b/cli/src/services/process.ts
@@ -1,13 +1,15 @@
/**
- * A service in its own process (`harness __service <name>`), started and watched by harnessd's master
- * (harnessd/services.ts).
+ * Services in a process of their own (`harness __service <a>,<b>`), started and watched by harnessd's
+ * master (harnessd/services.ts): one service, or the several a host shares (the edge host).
*
- * It tells the master it is alive over the spawn channel, as the core does, and exits when the master
- * goes, so a crash never leaves one behind. It reaches the core the way a window does — the core's local
- * socket — under the service role, with the token the master gave both (core/serviceLinks.ts), and
- * reconnects with backoff whenever the core restarts; the service keeps its own state meanwhile. It
- * answers the requests the core routes to it, hears what the core tells it, and asks the core what it
- * needs to know.
+ * The process (`hostServices`) tells the master it is alive over the spawn channel, as the core does:
+ * one heartbeat, and so one memory budget, for everything it runs. It exits when the master goes, so a
+ * crash never leaves one behind, and stops what it runs first. Each service in it (`runServiceProcess`)
+ * reaches the core on a link of its own, the way a window does (the core's local socket), under the
+ * service role, its own name and the token the master gave the core and this process
+ * (core/serviceLinks.ts). It reconnects with backoff whenever the core restarts, and the service keeps
+ * its own state meanwhile. It answers the requests the core routes to it, hears what the core tells it,
+ * and asks the core what it needs to know.
*/
import WebSocket from 'ws'
import type { ServiceRequests } from '../core/api.js'
@@ -34,18 +36,19 @@ export interface ServiceProcessOptions {
onEvent?: (payload: Payload) => void | Promise<unknown>
/** Each time it is connected to a core: the first time, and after every core restart. */
onConnected?: (core: CoreConnection) => void
- /** The master's spawn channel; this process when absent. */
- channel?: MasterChannel
env?: NodeJS.ProcessEnv
connect?: (url: string) => WebSocket
- exit?: (code: number) => void
- loopDelay?: LoopDelay
log?: (line: string) => void
/** The reconnect delay starts here and doubles to `maxBackoffMs`. */
initialBackoffMs?: number
maxBackoffMs?: number
+ /** The delay after the core refused this service (`REFUSED`). */
+ refusedBackoffMs?: number
}
+/** How the core's local socket closes a service connection it does not take (localWsServer.ts). */
+export const REFUSED = 4401
+
/** What a test asked this service's process to do wrong. */
export interface ServiceFaults {
start: boolean
@@ -77,22 +80,94 @@ export function serviceFaults(env: NodeJS.ProcessEnv, name: string): ServiceFaul
const describe = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+/** A service running in this process. Its stop may take a moment (the viewers stop their servers). */
export interface ServiceProcess {
- stop(): void
+ stop(): void | Promise<void>
+}
+
+export interface ServiceHostOptions {
+ /** The process's name, as its master runs it (`HARNESSD_SERVICE`): `edge`, or its one service's. */
+ name: string
+ /** The services it runs. A crash or a leak a test asks of the process, or of any of them, is the process's. */
+ services: readonly string[]
+ /** The master's spawn channel; this process when absent. */
+ channel?: MasterChannel
+ env?: NodeJS.ProcessEnv
+ exit?: (code: number) => void
+ loopDelay?: LoopDelay
+ /** How the master's stop (SIGTERM) reaches this process; this process's own signal when absent. */
+ onSignal?: (signal: NodeJS.Signals, handler: () => void) => void
+ /** How long its services get to stop before it exits all the same. */
+ leaveGraceMs?: number
}
+export interface ServiceHost {
+ /** A service now running in this process: stopped before the process exits. */
+ add(service: ServiceProcess): void
+ /** Stop every service it runs, then exit with `code`. Only the first call counts. */
+ leave(code: number): void
+}
-export function runServiceProcess(options: ServiceProcessOptions): ServiceProcess {
+/** How long a process's services get to stop before it exits without them: the master's own grace for a
+ * SIGTERM is shorter, and a master that is gone waits for nothing. */
+export const LEAVE_GRACE_MS = 5_000
+
+/** The process the services run in: alive to the master, and gone with it. */
+export function hostServices(options: ServiceHostOptions): ServiceHost {
const channel: MasterChannel = options.channel ?? (process as unknown as MasterChannel)
+ const env = options.env ?? process.env
+ const exit = options.exit ?? ((code: number) => process.exit(code))
+ const faults = [options.name, ...options.services].map((name) => serviceFaults(env, name))
+ const services: ServiceProcess[] = []
+ let leaving = false
+
+ // Alive, to the master: the same beat the core sends, so the same watchdog and budgets apply, to the
+ // process as a whole. A host's services share its heap: one leaking costs every one of them a restart.
+ const loopDelay = options.loopDelay ?? processLoopDelay()
+ const beat = (): void => {
+ const memory = channel.memoryUsage()
+ channel.send?.({ type: 'harnessd:heartbeat', rssBytes: memory.rss, heapUsedBytes: memory.heapUsed, loopDelayMs: loopDelay.take() })
+ }
+ const beating = channel.send ? setInterval(beat, heartbeatInterval(env)) : null
+ if (channel.send) beat()
+ const leaked: Buffer[] = []
+ const leaking = faults.some((fault) => fault.leak)
+ ? setInterval(() => { leaked.push(Buffer.alloc(8 * 1024 * 1024, 1)); leaked.push(Buffer.from(new Array(200_000).fill('x').join(''))) }, 100)
+ : null
+
+ const leave = (code: number): void => {
+ if (leaving) return
+ leaving = true
+ if (beating) clearInterval(beating)
+ if (leaking) clearInterval(leaking)
+ loopDelay.stop()
+ // Its services stop first, however this process ends (the master's SIGTERM, the master going, a test
+ // fault): the viewers' servers run in process groups of their own, and would otherwise outlive it
+ // holding their ports until the next viewers process reaped them. Bounded, so one that never finishes
+ // stopping cannot keep an orphan alive once its master is gone.
+ const late = setTimeout(() => exit(code), options.leaveGraceMs ?? LEAVE_GRACE_MS)
+ void Promise.allSettled(services.map((service) => Promise.resolve().then(() => service.stop())))
+ .then(() => { clearTimeout(late); exit(code) })
+ }
+ if (faults.some((fault) => fault.crash)) setTimeout(() => leave(1), 200)
+ // The master is gone: so is this process, rather than an orphan holding what it holds.
+ channel.once('disconnect', () => leave(0))
+ ;(options.onSignal ?? ((signal, handler) => { process.once(signal, handler) }))('SIGTERM', () => leave(0))
+ return { add: (service) => { services.push(service) }, leave }
+}
+
+/** One service in its process: its own link to the core, answering what the core routes to it. */
+export function runServiceProcess(options: ServiceProcessOptions): ServiceProcess {
const env = options.env ?? process.env
const faults = serviceFaults(env, options.name)
- // As a service whose start throws: this process ends, and the master decides whether to try again.
+ // As a service whose start throws: it is not run, and, alone in its process, the process ends and the
+ // master decides whether to try again.
if (faults.start) throw new Error(`injected fault: ${options.name}`)
const connect = options.connect ?? ((url: string) => new WebSocket(url))
- const exit = options.exit ?? ((code: number) => process.exit(code))
const log = options.log ?? ((line: string) => console.log(line))
const initialBackoffMs = options.initialBackoffMs ?? 250
const maxBackoffMs = options.maxBackoffMs ?? 5_000
+ const refusedBackoffMs = options.refusedBackoffMs ?? 60_000
let stopped = false
let backoff = initialBackoffMs
let socket: WebSocket | null = null
@@ -100,20 +175,6 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
let queries = 0
const pending = new Map<string, { resolve: (payload: Payload) => void; reject: (error: Error) => void }>()
- // Alive, to the master: the same beat the core sends, so the same watchdog and budgets apply.
- const loopDelay = options.loopDelay ?? processLoopDelay()
- const beat = (): void => {
- const memory = channel.memoryUsage()
- channel.send?.({ type: 'harnessd:heartbeat', rssBytes: memory.rss, heapUsedBytes: memory.heapUsed, loopDelayMs: loopDelay.take() })
- }
- const beating = channel.send ? setInterval(beat, heartbeatInterval(env)) : null
- if (channel.send) beat()
- const leaked: Buffer[] = []
- if (faults.crash) setTimeout(() => exit(1), 200)
- const leaking = faults.leak ? setInterval(() => { leaked.push(Buffer.alloc(8 * 1024 * 1024, 1)); leaked.push(Buffer.from(new Array(200_000).fill('x').join(''))) }, 100) : null
- // The master is gone: so is this service, rather than an orphan holding what it holds.
- channel.once('disconnect', () => { stop(); exit(0) })
-
const send = (frame: { type: string; payload: Payload }): void => {
try { socket?.send(JSON.stringify(frame)) } catch { /* the socket is going; the core answers for us */ }
}
@@ -188,12 +249,15 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
})
ws.on('message', onFrame)
ws.on('error', () => { /* `close` follows, and reconnects */ })
- ws.on('close', () => {
+ ws.on('close', (code: number) => {
// A new socket is dialled only after this one closes, so this is always the current one.
socket = null
for (const [id, waiting] of pending) { pending.delete(id); waiting.reject(new Error('the core went away')) }
if (stopped) return
- const delay = backoff
+ // Refused: this core does not run the service out of its process, as a core from before it did under
+ // a newer master, for as long as the two differ. Asked again every few seconds, it only filled both
+ // logs; once a minute still finds a core that takes it.
+ const delay = code === REFUSED ? Math.max(backoff, refusedBackoffMs) : backoff
backoff = Math.min(backoff * 2, maxBackoffMs)
reconnectTimer = setTimeout(() => { reconnectTimer = null; dial() }, delay)
})
@@ -202,9 +266,6 @@ export function runServiceProcess(options: ServiceProcessOptions): ServiceProces
const stop = (): void => {
if (stopped) return
stopped = true
- if (beating) clearInterval(beating)
- if (leaking) clearInterval(leaking)
- loopDelay.stop()
if (reconnectTimer) clearTimeout(reconnectTimer)
try { socket?.close() } catch { /* already closed */ }
}
diff --git a/cli/src/services/processCoreApi.spec.ts b/cli/src/services/processCoreApi.spec.ts
new file mode 100644
index 000000000..d98165c82
--- /dev/null
+++ b/cli/src/services/processCoreApi.spec.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import type { RegisteredSession } from '../lib/registry.js'
+import { agentsIn, isSession, processCoreApi } from './processCoreApi.js'
+
+const agent = (agentId: string, over: Partial<RegisteredSession> = {}) => ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', cwd: `/work/${agentId}`, ...over }) as RegisteredSession
+
+describe('the core API a light service runs on in its own process', () => {
+ it('answers the agents from what the core last said, by agent id or session id', () => {
+ const live = [agent('a1'), agent('a2')]
+ const api = processCoreApi('/data', 'projects', { live: () => live, advertised: () => [live[1]] })
+ expect(api.dataDir).toBe('/data')
+ expect(api.agents.live()).toEqual(live)
+ expect(api.agents.all()).toEqual(live)
+ expect(api.agents.advertised()).toEqual([live[1]])
+ expect(api.agents.byAgent('a2')).toEqual(live[1])
+ expect(api.agents.resolve('s-a1')).toEqual(live[0])
+ expect(api.agents.resolve('nobody')).toBeUndefined()
+ })
+
+ it('answers agents it was never told of as none, and what these services never ask as nothing', async () => {
+ const api = processCoreApi('/data', 'usage')
+ expect(api.agents.live()).toEqual([])
+ expect(api.agents.advertised()).toEqual([])
+ expect(api.agents.byAgent('a1')).toBeUndefined()
+ expect(api.agents.displayName(agent('a1'))).toBe('')
+ expect(api.agents.terminalAvailable('a1')).toBe(false)
+ // Only the core launches a terminal (#893): a service in its own process is refused.
+ await expect(api.terminals.open({ argv: ['/bin/sh'] } as never)).resolves.toEqual({ ok: false, error: 'SERVICE_UNAVAILABLE' })
+ api.agents.sync(agent('a1'))
+ await expect(api.agents.runtimeModels()).resolves.toEqual([])
+ expect(api.agents.runtimeProfile(agent('a1'))).toBeNull()
+ api.agents.setRuntime('a1', 'opus')
+ await expect(api.agents.fork('a1')).resolves.toEqual({ ok: false, error: 'UNSUPPORTED' })
+ api.turns.send('a1', 'text')
+ api.turns.stop('a1')
+ expect(api.turns.recent('a1', 3)).toEqual([])
+ expect(api.turns.asks('a1')).toEqual([])
+ api.questions.answer('a1', 'q', {})
+ await expect(api.questions.answerReviewed({} as never)).resolves.toBe(false)
+ expect(api.transcripts.databaseHistory(agent('a1'))).toBeUndefined()
+ expect(api.external.sessions.list()).toEqual([])
+ await expect(api.external.sessions.scan()).resolves.toEqual([])
+ expect(api.external.open.known().size).toBe(0)
+ await expect(api.external.open.fresh()).resolves.toEqual(new Map())
+ await expect(api.account.mintGridName()).resolves.toBeNull()
+ // A service holds no credential, and says which one asked.
+ await expect(api.account.accessToken()).rejects.toThrow('usage holds no credential')
+ await expect(api.account.privateGridName()).resolves.toBeNull()
+ expect(api.account.machineName()).toBeNull()
+ api.clients.viewerChanged('a1')
+ api.clients.gridNamed('grid')
+ api.clients.gridModelsChanged()
+ api.clients.dshInstallStatus({ phase: 'clone' })
+ })
+
+ it('reads the agents out of the core\'s answer, and nothing out of anything else', () => {
+ expect(agentsIn({ agents: [agent('a1'), { agentId: 7 }, null, 'a2'] })).toEqual([agent('a1')])
+ expect(agentsIn({ error: 'QUERY_FAILED' })).toBeNull()
+ expect(agentsIn(null)).toBeNull()
+ expect(agentsIn(undefined)).toBeNull()
+ expect(isSession(agent('a1'))).toBe(true)
+ expect(isSession({ sessionId: 's' })).toBe(false)
+ })
+})
diff --git a/cli/src/services/processCoreApi.ts b/cli/src/services/processCoreApi.ts
new file mode 100644
index 000000000..b24a67999
--- /dev/null
+++ b/cli/src/services/processCoreApi.ts
@@ -0,0 +1,65 @@
+/**
+ * The core API a light service runs on in its own process (the edge host: usage, the monitor, the project
+ * readers): the agents the core last said, and nothing else. Each process asks the core for what it reads
+ * (`service_query live` or `advertised`, core/agentQueries.ts) as each request starts, so it answers as
+ * the core's registry would at that moment, never from a copy that waited.
+ *
+ * What these services never ask (turns, questions, sign-in, the windows) answers as nothing, and a
+ * credential is refused: a service holds none (services/AGENTS.md).
+ */
+import { resolveAgent, TERMINALS_OFF, type CoreApi } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+
+/** The agents a process was last told of. Those it is never told of read as none. */
+export interface AgentsView {
+ live?: () => RegisteredSession[]
+ advertised?: () => RegisteredSession[]
+}
+
+/** Whether what the core sent is an agent. */
+export const isSession = (value: unknown): value is RegisteredSession =>
+ !!value && typeof value === 'object' && typeof (value as { agentId?: unknown }).agentId === 'string'
+
+/** The agents in a core's answer (`{ agents: [...] }`), or null when it is not one. */
+export function agentsIn(answer: Record<string, unknown> | null | undefined): RegisteredSession[] | null {
+ return Array.isArray(answer?.agents) ? answer.agents.filter(isSession) : null
+}
+
+export function processCoreApi(dataDir: string, service: string, view: AgentsView = {}): CoreApi {
+ const live = (): RegisteredSession[] => view.live?.() ?? []
+ return {
+ dataDir,
+ // Terminals are launched by the core alone (the shell service, #893): a service in its own process
+ // is refused, never handed a way to start a process outside the core.
+ terminals: TERMINALS_OFF,
+ agents: {
+ // The stopped agents are never sent to these services: none of them reads one.
+ all: live,
+ live,
+ displayName: () => '',
+ byAgent: (agentId) => live().find((session) => session.agentId === agentId),
+ resolve: (id) => resolveAgent(live(), id),
+ advertised: () => view.advertised?.() ?? [],
+ terminalAvailable: () => false,
+ sync: () => {},
+ runtimeModels: async () => [],
+ runtimeProfile: () => null,
+ setRuntime: () => {},
+ fork: async () => ({ ok: false, error: 'UNSUPPORTED' }),
+ },
+ turns: { send: () => {}, stop: () => {}, recent: () => [], asks: () => [] },
+ questions: { answer: () => {}, answerReviewed: async () => false },
+ transcripts: { databaseHistory: () => undefined },
+ external: {
+ sessions: { list: () => [], scan: async () => [] },
+ open: { known: () => new Map(), fresh: async () => new Map() },
+ },
+ account: {
+ mintGridName: async () => null,
+ accessToken: () => Promise.reject(new Error(`${service} holds no credential`)),
+ privateGridName: async () => null,
+ machineName: () => null,
+ },
+ clients: { viewerChanged: () => {}, gridNamed: () => {}, gridModelsChanged: () => {}, dshInstallStatus: () => {} },
+ }
+}
diff --git a/cli/src/services/projects.ts b/cli/src/services/projects.ts
index 26a9a5b90..b8ca4a84c 100644
--- a/cli/src/services/projects.ts
+++ b/cli/src/services/projects.ts
@@ -12,8 +12,8 @@ import { projectPreview } from '../lib/projectPreview.js'
import { readSessionGitPullRequest, type ExpectedGitContext } from '../lib/sessionGitPullRequest.js'
import { internalOnThrow } from './requestErrors.js'
-/** The requests the project readers answer for the apps. */
-export const PROJECTS_REQUESTS = ['git_pull_request', 'git_project_info', 'project_preview', 'fs_list_dir', 'agent_read_file'] as const
+/** The requests the project readers answer for the apps, declared in core/api.ts for the core to route. */
+export { PROJECTS_REQUESTS } from '../core/api.js'
export function startProjects(core: CoreApi): ServiceRequests {
/** The browsable home, widened by the folders agents are running in: a repository outside both is not
diff --git a/cli/src/services/projectsProcess.spec.ts b/cli/src/services/projectsProcess.spec.ts
new file mode 100644
index 000000000..d7a05fccc
--- /dev/null
+++ b/cli/src/services/projectsProcess.spec.ts
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CoreApi } from '../core/api.js'
+import { PROJECTS_REQUESTS } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcessOptions } from './process.js'
+import { runProjectsService } from './projectsProcess.js'
+
+// The real default reaches a real socket: never in a test.
+vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))
+
+const agent = (agentId: string) => ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', cwd: `/work/${agentId}` }) as RegisteredSession
+const ASKER = { local: true, owner: true }
+
+describe('the project readers in their own process', () => {
+ afterEach(() => vi.clearAllMocks())
+
+ const setup = () => {
+ let options: ServiceProcessOptions | null = null
+ let api: CoreApi | null = null
+ /** What each reader saw of the live agents when it was asked. */
+ const seen: string[][] = []
+ runProjectsService({
+ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
+ run: (given) => { options = given; return { stop: vi.fn() } },
+ start: (core) => {
+ api = core
+ return { git_project_info: (payload, asker) => { seen.push(core.agents.live().map((session) => session.agentId)); return { path: payload.path, owner: asker.owner } } }
+ },
+ })
+ return { options: options!, api: api!, seen }
+ }
+
+ it('reads the live agents from the core as each request starts, and answers as the core\'s readers do', async () => {
+ const { options, api, seen } = setup()
+ expect(options).toMatchObject({ name: 'projects', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ // Before a core has connected: the agents it last said, which is none.
+ expect(await options.requests.git_project_info!({ path: '/work' }, ASKER)).toEqual({ path: '/work', owner: true })
+ let answer: Record<string, unknown> = { agents: [agent('a1')] }
+ const query = vi.fn(async (_name: string) => answer)
+ options.onConnected!({ query } satisfies CoreConnection)
+ await options.requests.git_project_info!({ path: '/work' }, ASKER)
+ expect(query).toHaveBeenLastCalledWith('live')
+ answer = { agents: [agent('a1'), agent('a2')] }
+ await options.requests.git_project_info!({ path: '/work' }, ASKER)
+ // A core that cannot say leaves what it said last.
+ answer = { error: 'UNKNOWN_QUERY' }
+ await options.requests.git_project_info!({ path: '/work' }, ASKER)
+ query.mockRejectedValueOnce(new Error('the core went away'))
+ await options.requests.git_project_info!({ path: '/work' }, ASKER)
+ expect(seen).toEqual([[], ['a1'], ['a1', 'a2'], ['a1', 'a2'], ['a1', 'a2']])
+ expect(api.agents.resolve('s-a2')).toEqual(agent('a2'))
+ })
+
+ it('runs as a real service by default, answering every request the core routes to the readers', () => {
+ runProjectsService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ const options = vi.mocked(runServiceProcess).mock.calls.at(-1)![0]
+ expect(options.name).toBe('projects')
+ expect(Object.keys(options.requests).sort()).toEqual([...PROJECTS_REQUESTS].sort())
+ })
+})
diff --git a/cli/src/services/projectsProcess.ts b/cli/src/services/projectsProcess.ts
new file mode 100644
index 000000000..75930a3ab
--- /dev/null
+++ b/cli/src/services/projectsProcess.ts
@@ -0,0 +1,45 @@
+/**
+ * The project and folder readers in their own process (`harness __service projects`, in the edge host):
+ * the same handlers as in the core's process (services/projects.ts), on the live agents the core names
+ * as each request starts (`service_query live`). An agent's branch and pull request, a project's
+ * repository and preview, a folder's subfolders and a media file are read here: the git runs, the disk
+ * reads and their time are this process's alone.
+ */
+import type { ServiceRequests } from '../core/api.js'
+import type { RegisteredSession } from '../lib/registry.js'
+import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'
+import { agentsIn, processCoreApi } from './processCoreApi.js'
+import { startProjects } from './projects.js'
+
+export interface ProjectsServiceOptions {
+ dataDir: string
+ socketPath: string
+ machineId: string
+ token: string
+ /** Swapped in tests for one that does not touch the real socket or process. */
+ run?: typeof runServiceProcess
+ /** Swapped in tests for readers that run no git and read no disk. */
+ start?: typeof startProjects
+}
+
+export function runProjectsService(options: ProjectsServiceOptions): ServiceProcess {
+ let live: RegisteredSession[] = []
+ let core: CoreConnection | null = null
+ /** The live agents now. A core that cannot say leaves the last ones it said. */
+ const refresh = async (): Promise<void> => {
+ live = agentsIn(await core?.query('live').catch(() => null)) ?? live
+ }
+ const answers = (options.start ?? startProjects)(processCoreApi(options.dataDir, 'projects', { live: () => live }))
+ // Each request reads the agents as they are when it is asked, as the core's registry would answer it:
+ // an agent stopped a moment ago is no longer one whose folder this reads.
+ const requests: ServiceRequests = Object.fromEntries(Object.entries(answers).map(([type, handle]) =>
+ [type, async (payload: Record<string, unknown>, asker: Parameters<typeof handle>[1]) => { await refresh(); return handle(payload, asker) }]))
+ return (options.run ?? runServiceProcess)({
+ name: 'projects',
+ socketPath: options.socketPath,
+ machineId: options.machineId,
+ token: options.token,
+ requests,
+ onConnected: (connection) => { core = connection },
+ })
+}
diff --git a/cli/src/services/search.ts b/cli/src/services/search.ts
index a00b4fb2a..63fcec6c6 100644
--- a/cli/src/services/search.ts
+++ b/cli/src/services/search.ts
@@ -12,8 +12,8 @@ import type { CoreApi, CorePorts, ServiceRequests } from '../core/api.js'
import { SessionSearchIndex, folderWords, type SearchSource } from '../lib/sessionSearch/indexer.js'
import { SessionSearchStore, SESSION_SEARCH_FILE } from '../lib/sessionSearch/store.js'
-/** The requests search answers for the apps. */
-export const SEARCH_REQUESTS = ['session_search', 'session_tail'] as const
+/** The requests search answers for the apps, declared in core/api.ts for the core to route. */
+export { SEARCH_REQUESTS } from '../core/api.js'
const number = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : undefined
const integer = (value: unknown) => typeof value === 'number' && Number.isInteger(value) ? value : undefined
diff --git a/cli/src/services/store.ts b/cli/src/services/store.ts
index d6c56b196..cc7f87177 100644
--- a/cli/src/services/store.ts
+++ b/cli/src/services/store.ts
@@ -15,8 +15,8 @@ import { removeDsh } from '../dsh/install.js'
import { mutateDsh } from '../dsh/service.js'
import { dshInstallReply, dshInstallRequest, dshInstallStatus, dshListRows, dshRemoveId, dshRemoveReply } from '../dsh/wire.js'
-/** The requests the store answers for the apps. */
-export const STORE_REQUESTS = ['dsh_list', 'dsh_install', 'dsh_update', 'dsh_remove'] as const
+/** The requests the store answers for the apps, declared in core/api.ts for the core to route. */
+export { STORE_REQUESTS } from '../core/api.js'
export interface StoreDeps {
refresh: typeof refreshDshRegistry
diff --git a/cli/src/services/usage.ts b/cli/src/services/usage.ts
index 9ab65c3e2..1eb68cce9 100644
--- a/cli/src/services/usage.ts
+++ b/cli/src/services/usage.ts
@@ -8,8 +8,8 @@ import type { CoreApi, ServiceRequests } from '../core/api.js'
import { readAccountUsage, type AccountUsageReading } from '../lib/accountUsage.js'
import { internalOnThrow } from './requestErrors.js'
-/** The request usage answers for the apps. */
-export const USAGE_REQUESTS = ['usage_read'] as const
+/** The request usage answers for the apps, declared in core/api.ts for the core to route. */
+export { USAGE_REQUESTS } from '../core/api.js'
export interface UsageDeps {
/** The vendors' answers. Injected so a spec reads no real home, Keychain or network. */
diff --git a/cli/src/services/usageProcess.spec.ts b/cli/src/services/usageProcess.spec.ts
new file mode 100644
index 000000000..fc3999292
--- /dev/null
+++ b/cli/src/services/usageProcess.spec.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CoreApi } from '../core/api.js'
+import { runServiceProcess, type ServiceProcessOptions } from './process.js'
+import { runUsageService } from './usageProcess.js'
+
+// The real default reaches a real socket: never in a test.
+vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))
+
+describe('account usage in its own process', () => {
+ afterEach(() => vi.clearAllMocks())
+
+ it('answers usage_read with the same handler as in the core\'s process, holding no credential', async () => {
+ let options: ServiceProcessOptions | null = null
+ let api: CoreApi | null = null
+ const service = { stop: vi.fn() }
+ const handle = runUsageService({
+ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
+ run: (given) => { options = given; return service },
+ start: (core) => { api = core; return { usage_read: async () => ({ providers: [] }) } },
+ })
+ expect(handle).toBe(service)
+ expect(options).toMatchObject({ name: 'usage', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ expect(await options!.requests.usage_read!({}, { local: true, owner: true })).toEqual({ providers: [] })
+ await expect(api!.account.accessToken()).rejects.toThrow('usage holds no credential')
+ })
+
+ it('runs as a real service by default', () => {
+ runUsageService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ expect(runServiceProcess).toHaveBeenCalledWith(expect.objectContaining({ name: 'usage', requests: { usage_read: expect.any(Function) } }))
+ })
+})
diff --git a/cli/src/services/usageProcess.ts b/cli/src/services/usageProcess.ts
new file mode 100644
index 000000000..36cd159f8
--- /dev/null
+++ b/cli/src/services/usageProcess.ts
@@ -0,0 +1,29 @@
+/**
+ * Account usage in its own process (`harness __service usage`, in the edge host): `usage_read`, the same
+ * handler as in the core's process (services/usage.ts). It asks the core nothing. Its two vendor round
+ * trips and the Keychain reads through `security` are this process's alone.
+ */
+import { runServiceProcess, type ServiceProcess } from './process.js'
+import { processCoreApi } from './processCoreApi.js'
+import { startUsage } from './usage.js'
+
+export interface UsageServiceOptions {
+ dataDir: string
+ socketPath: string
+ machineId: string
+ token: string
+ /** Swapped in tests for one that does not touch the real socket or process. */
+ run?: typeof runServiceProcess
+ /** Swapped in tests for usage that reads no Keychain and calls no vendor. */
+ start?: typeof startUsage
+}
+
+export function runUsageService(options: UsageServiceOptions): ServiceProcess {
+ return (options.run ?? runServiceProcess)({
+ name: 'usage',
+ socketPath: options.socketPath,
+ machineId: options.machineId,
+ token: options.token,
+ requests: (options.start ?? startUsage)(processCoreApi(options.dataDir, 'usage')),
+ })
+}
diff --git a/cli/src/services/viewersProcess.spec.ts b/cli/src/services/viewersProcess.spec.ts
index 305a3e89b..17242271e 100644
--- a/cli/src/services/viewersProcess.spec.ts
+++ b/cli/src/services/viewersProcess.spec.ts
@@ -41,18 +41,14 @@ describe('the viewers in their own process', () => {
const viewers = fakeViewers()
let api: CoreApi | null = null
let options: ServiceProcessOptions | null = null
- let onSigterm: (() => void) | null = null
const service = { stop: vi.fn() }
- const exits: number[] = []
const handle = runViewersService({
dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't',
run: (given) => { options = given; return service },
start: (core: CoreApi, ports: CorePorts) => { api = core; ports.viewers = viewers.port },
- onSignal: (signal, handler) => { if (signal === 'SIGTERM') onSigterm = handler },
- exit: (code) => exits.push(code),
...over,
})
- return { viewers, api: api!, options: options!, service, handle, exits, sigterm: () => onSigterm!() }
+ return { viewers, api: api!, options: options!, service, handle }
}
it('reaches the core as `viewers`, through the socket and token it was given, and answers the apps nothing', () => {
@@ -184,24 +180,20 @@ describe('the viewers in their own process', () => {
expect(viewers.port.detach).not.toHaveBeenCalled()
})
- it('stops its viewer servers before it goes, however it ends, and only once', async () => {
- const { viewers, service, handle, exits, options, sigterm } = setup()
- sigterm()
- options.exit!(1)
- handle.stop()
- await flush()
+ it('stops its viewer servers when its process stops it, and only once, however often asked', async () => {
+ const { viewers, service, handle } = setup()
+ const first = handle.stop()
+ const second = handle.stop()
+ await Promise.all([first, second])
expect(service.stop).toHaveBeenCalledOnce()
expect(viewers.port.stop).toHaveBeenCalledOnce()
- expect(exits).toEqual([0, 1])
})
- it('goes all the same when its viewers fail to stop', async () => {
+ it('says so when its viewers fail to stop: its process goes all the same (services/process.ts)', async () => {
const viewers = fakeViewers()
viewers.port.stop.mockRejectedValue(new Error('a watch would not close'))
- const { exits, sigterm } = setup({ start: (_core, ports) => { ports.viewers = viewers.port } })
- sigterm()
- await flush()
- expect(exits).toEqual([0])
+ const { handle } = setup({ start: (_core, ports) => { ports.viewers = viewers.port } })
+ await expect(handle.stop()).rejects.toThrow('a watch would not close')
})
it('does not run without viewers: the master starts it again, or parks it', () => {
@@ -247,19 +239,9 @@ describe('the viewers in their own process', () => {
api.clients.dshInstallStatus({ phase: 'clone' })
})
- it('runs as a real service process by default: its viewers, its signal, its exit', async () => {
- const once = vi.spyOn(process, 'once').mockImplementation(() => process)
- const exit = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
- try {
- runViewersService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
- expect(runServiceProcess).toHaveBeenCalledWith(expect.objectContaining({ name: 'viewers', socketPath: '/data/daemon-1.sock' }))
- const [signal, handler] = once.mock.calls.at(-1)!
- expect(signal).toBe('SIGTERM')
- ;(handler as () => void)()
- await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(0))
- } finally {
- once.mockRestore()
- exit.mockRestore()
- }
+ it('runs as a real service by default: its viewers, on its own link to the core', async () => {
+ const handle = runViewersService({ dataDir: '/data', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })
+ expect(runServiceProcess).toHaveBeenCalledWith(expect.objectContaining({ name: 'viewers', socketPath: '/data/daemon-1.sock' }))
+ await handle.stop()
})
})
diff --git a/cli/src/services/viewersProcess.ts b/cli/src/services/viewersProcess.ts
index 9f2c4da41..4cc059f27 100644
--- a/cli/src/services/viewersProcess.ts
+++ b/cli/src/services/viewersProcess.ts
@@ -32,9 +32,6 @@ export interface ViewersServiceOptions {
run?: typeof runServiceProcess
/** Swapped in tests for viewers that start no server and watch no file. */
start?: typeof startViewers
- /** How the master's stop (SIGTERM) reaches this process; this process's own signal when absent. */
- onSignal?: (signal: NodeJS.Signals, handler: () => void) => void
- exit?: (code: number) => void
}
/** Whether what the core sent is an agent this process can attach. */
@@ -131,7 +128,9 @@ export function runViewersService(options: ViewersServiceOptions): ServiceProces
for (const agentId of [...sessions.keys()]) if (!listed.has(agentId) && !heard.has(agentId)) detach(agentId)
}
- const exit = options.exit ?? ((code: number) => process.exit(code))
+ // Its process stops it before it exits, however it ends (services/process.ts `hostServices`): the viewer
+ // servers run in process groups of their own and would otherwise outlive it, holding their ports, until
+ // the next viewers process reaped them. Once, whoever asks.
let stopping: Promise<void> | null = null
const stop = (): Promise<void> => {
stopping ??= Promise.resolve().then(() => {
@@ -140,12 +139,6 @@ export function runViewersService(options: ViewersServiceOptions): ServiceProces
})
return stopping
}
- // However this process ends (the master's SIGTERM, the master going, a test fault), its viewer servers
- // are stopped first: they run in process groups of their own and would otherwise outlive it, holding
- // their ports, until the next viewers process reaped them.
- const leave = (code: number): void => {
- void stop().catch(() => {}).then(() => exit(code))
- }
const run = options.run ?? runServiceProcess
const service = run({
@@ -155,7 +148,6 @@ export function runViewersService(options: ViewersServiceOptions): ServiceProces
token: options.token,
// The apps ask the viewers nothing: only the core does, through the context it keeps.
requests: {},
- exit: leave,
onEvent: (payload) => {
if (payload.kind === 'attach' && isSession(payload.session)) {
heard.add(payload.session.agentId)
@@ -174,6 +166,5 @@ export function runViewersService(options: ViewersServiceOptions): ServiceProces
void connection.query('agents').then((answer) => { if (core === connection) catchUp(answer.agents) }, () => {})
},
})
- ;(options.onSignal ?? ((signal, handler) => { process.once(signal, handler) }))('SIGTERM', () => leave(0))
- return { stop: () => { void stop() } }
+ return { stop }
}