The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
harnessd: the viewers can run in their own process (#775)
Dee48e30638dcaf
diff --git a/cli/e2e/viewersProcess.e2e.ts b/cli/e2e/viewersProcess.e2e.tsnew file mode 100644index 000000000..cf188a06c--- /dev/null+++ b/cli/e2e/viewersProcess.e2e.ts@@ -0,0 +1,209 @@+/**+ * The DSH viewers in their own process, for a real harness agent on the real daemon: harnessd's master+ * runs viewers beside the core (`HARNESSD_SERVICES=viewers`, here with search too), the harness's viewer+ * server is the viewers process's own, and its URL reaches the window through the core, which keeps each+ * agent's last word for the frames it builds (core/viewersLink.ts). Whatever happens to the viewers costs+ * the viewers alone: hung or killed, the core keeps answering frames with what it last knew, agents keep+ * working, and the master starts them again, which stops the viewer server the dead process left behind+ * and starts a new one whose URL replaces the old. A core that restarts leaves the viewers to their+ * process: the viewer keeps its URL, and the new core answers with it.+ */+import { execFileSync } from 'node:child_process'+import { mkdirSync, writeFileSync } from 'node:fs'+import { join } from 'node:path'+import { afterEach, describe, expect, it, onTestFailed } from 'vitest'+import { LocalClient, type Frame } from './harness/client.js'+import { IsolatedDaemon, until } from './harness/daemon.js'++const HARNESS = 'e2e/sketch'+const viewerScript = (d: IsolatedDaemon) => join(d.env.DSH_DIR!, 'e2e', 'sketch', 'viewer.mjs')++/** A harness with a viewer of its own, installed in the daemon's harness folder: a small web server on+ * the port the daemon hands it, which says which process it is. */+function installHarness(d: IsolatedDaemon): void {+ const dir = join(d.env.DSH_DIR!, 'e2e', 'sketch')+ mkdirSync(dir, { recursive: true })+ writeFileSync(viewerScript(d), [+ "import { createServer } from 'node:http'",+ "createServer((_, res) => res.end(`sketch viewer ${process.pid}`)).listen(Number(process.env.HARNESS_VIEWER_PORT), '127.0.0.1')",+ ].join('\n') + '\n')+ writeFileSync(join(dir, 'harness.json'), JSON.stringify({+ spec: 1, id: HARNESS, name: 'Sketch', engine: 'claude',+ // By its whole path, so a viewer server this test started is told apart from any other process.+ viewer: { command: `'${process.execPath}' '${viewerScript(d)}'`, url: 'http://127.0.0.1:${port}/' },+ }))+ writeFileSync(join(d.env.DSH_DIR!, 'installed.json'), JSON.stringify([+ { id: HARNESS, dir, source: dir, ref: null, commit: null, linked: false, installedAt: Date.now() },+ ]))+}++const processTable = (): Array<{ pid: number; command: string }> =>+ execFileSync('ps', ['-A', '-o', 'pid=,command=']).toString().trim().split('\n')+ .map((line) => line.trim().match(/^(\d+)\s+(.*)$/)).filter((match): match is RegExpMatchArray => !!match)+ .map(([, pid, command]) => ({ pid: Number(pid), command }))+/** The viewer servers this daemon's harness started that are still running (and their shells). */+const viewerServers = (d: IsolatedDaemon): number[] =>+ processTable().filter(({ command }) => command.includes(viewerScript(d))).map(({ pid }) => pid)+/** A process's parents, nearest first. */+function ancestors(pid: number): number[] {+ const found: number[] = []+ for (let at = pid; found.length < 8;) {+ const parent = Number(execFileSync('ps', ['-o', 'ppid=', '-p', String(at)]).toString().trim())+ if (!parent || parent <= 1) break+ found.push(parent)+ at = parent+ }+ return found+}++/** The viewers 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 viewers could be. */+const viewersPid = (d: IsolatedDaemon): number | null => {+ const started = [...d.log().matchAll(/\[harnessd\] service viewers started \(pid (\d+)\)/g)]+ return started.length ? Number(started[started.length - 1][1]) : null+}+const restarts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service viewers started .* restart \d+/g)].length+const ready = (d: IsolatedDaemon) => [...d.log().matchAll(/\[cli\] ready/g)].length++const row = async (client: LocalClient, agentId: string) =>+ ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)+ .find((agent) => agent.id === agentId)+async function create(d: IsolatedDaemon, client: LocalClient, folder: string, extra: Record<string, unknown> = {}, engine = 'claude'): Promise<Record<string, any>> {+ const cwd = join(d.projectsDir, folder)+ mkdirSync(cwd, { recursive: true })+ const created = await client.request('agent_create', { engine, cwd, bypassPermission: true, ...extra }, 90_000)+ expect(created.error, `${folder}: ${JSON.stringify(created)}`).toBeUndefined()+ return until(`${folder} to bind its conversation`, async () => {+ const agent = await row(client, created.agent.id)+ return agent?.sessionId && agent.status === 'active' ? agent : null+ }, 60_000, 500)+}+async function turn(client: LocalClient, agentId: string, content: string): Promise<void> {+ const ended = client.next((frame: Frame) => frame.type === 'turn_ended' && frame.agentId === agentId, 45_000, `turn_ended (${content})`)+ client.send('message', { agentId, content })+ await ended+}+/** The viewer URL the core answers the agent's frame with, once it has one other than `previous`. */+const viewerUrl = (client: LocalClient, agentId: string, previous: string | null = null): Promise<string> =>+ until(`a viewer URL for ${agentId}${previous ? ` other than ${previous}` : ''}`, async () => {+ const url = (await row(client, agentId))?.viewerUrl+ return typeof url === 'string' && url !== previous ? url : null+ }, 60_000, 250)+/** What the viewer at `url` answers, or null when nothing serves it. */+const serves = async (url: string): Promise<string | null> => {+ const response = await fetch(url, { signal: AbortSignal.timeout(2_000) }).catch(() => null)+ return response?.ok ? response.text() : null+}++describe('the DSH viewers in their own process', () => {+ let daemon: IsolatedDaemon | undefined+ /** Every daemon a test started, closed by the test or not: none may leave a viewer server behind. */+ const started: IsolatedDaemon[] = []+ afterEach(async () => {+ await daemon?.close()+ daemon = undefined+ // A viewer server runs in a process group of its own, and a failed test may have left one.+ for (const pid of started.splice(0).flatMap(viewerServers)) {+ try { process.kill(-pid, 'SIGKILL') } catch { /* not a group leader, or gone */ }+ try { process.kill(pid, 'SIGKILL') } catch { /* gone */ }+ }+ })+ const fresh = async (services: string) => {+ const d = await IsolatedDaemon.create({ env: {+ HARNESSD_SERVICES: services,+ HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200',+ HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000',+ } })+ daemon = d+ started.push(d)+ installHarness(d)+ onTestFailed(() => { console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`) })+ await d.start()+ return d+ }++ it('by default the viewers stay in the core\'s process, as before', async () => {+ const d = await fresh('')+ const client = await LocalClient.connect(d)+ const sketch = await create(d, client, 'sketch-default', { dsh: HARNESS })+ const answer = await serves(await viewerUrl(client, sketch.id))+ expect(answer).toMatch(/^sketch viewer \d+$/)+ expect(ancestors(Number(answer!.split(' ').pop()))).toContain(d.corePid())+ expect(viewersPid(d)).toBeNull()+ client.close()+ })++ it('a harness agent\'s viewer is the viewers process\'s, its URL reaches the window through the core, and search runs beside it', async () => {+ const d = await fresh('search,viewers')+ const client = await LocalClient.connect(d)+ await until('the viewers to connect to the core', () => d.log().includes('[services] viewers connected') || null, 30_000, 200)+ await until('search to connect to the core', () => d.log().includes('[services] search connected') || null, 30_000, 200)+ const sketch = await create(d, client, 'sketch-one', { dsh: HARNESS })+ const url = await viewerUrl(client, sketch.id)+ expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/$/)+ expect(await row(client, sketch.id)).toMatchObject({ dsh: HARNESS, dshName: 'Sketch', viewerName: 'Sketch Viewer' })+ // Pushed to the window on the agent's frame, not only there when it asks.+ await client.waitFor((frame) => frame.type === 'agent_synced' && frame.payload?.agent?.id === sketch.id && frame.payload.agent.viewerUrl === url,+ 30_000, 'the agent\'s frame with its viewer URL')+ // A real server, and the viewers process's: the core is not among its parents.+ const answer = await serves(url)+ expect(answer).toMatch(/^sketch viewer \d+$/)+ const parents = ancestors(Number(answer!.split(' ').pop()))+ expect(parents).toContain(viewersPid(d))+ expect(parents).not.toContain(d.corePid())+ await turn(client, sketch.id, 'about the axolotl in the sketch')+ await until('search to find the harness agent\'s conversation', async () =>+ JSON.stringify(await client.request('session_search', { query: 'axolotl' }, 30_000)).includes(sketch.sessionId) || null, 60_000, 1_000)+ expect(d.coresStarted()).toBe(1)+ client.close()+ // Stopped with the daemon, it stops its viewer servers before it goes.+ await d.close()+ daemon = undefined+ await until('no viewer server to be left running', () => viewerServers(d).length === 0 || null, 10_000, 200)+ })++ it('hung, then killed, the viewers cost only themselves: frames build from what the core last knew, agents work, and the master brings them back with a new viewer', async () => {+ const d = await fresh('viewers')+ const client = await LocalClient.connect(d)+ const sketch = await create(d, client, 'sketch-killed', { dsh: HARNESS })+ const plain = await create(d, client, 'plain-codex', {}, 'codex')+ const before = await viewerUrl(client, sketch.id)+ const first = viewersPid(d)!+ // Hung: it hears nothing and says nothing. The core answers the agent's frame with what it last knew.+ process.kill(first, 'SIGSTOP')+ expect((await row(client, sketch.id))?.viewerUrl).toBe(before)+ await turn(client, plain.id, 'while the viewers were hung')+ // Killed: the master starts it again, and the new process stops the viewer server the old one left.+ process.kill(first, 'SIGKILL')+ await until('the master to restart the viewers', () => restarts(d) >= 1 || null, 30_000, 200)+ expect(viewersPid(d)).not.toBe(first)+ const after = await viewerUrl(client, sketch.id, before)+ await until('the viewer left behind to be stopped', async () => (await serves(before)) === null || null, 30_000, 250)+ expect(await serves(after)).toMatch(/^sketch viewer \d+$/)+ await client.waitFor((frame) => frame.type === 'agent_synced' && frame.payload?.agent?.id === sketch.id && frame.payload.agent.viewerUrl === after,+ 30_000, 'the agent\'s frame with its new viewer URL')+ await turn(client, sketch.id, 'the harness agent never noticed')+ expect(d.coresStarted()).toBe(1)+ client.close()+ })++ it('a core that restarts leaves the viewers running: the new core answers with the same viewer', async () => {+ const d = await fresh('viewers')+ let client = await LocalClient.connect(d)+ const sketch = await create(d, client, 'sketch-core', { dsh: HARNESS })+ const url = await viewerUrl(client, sketch.id)+ const viewers = viewersPid(d)+ const core = d.corePid()!+ const wired = ready(d)+ process.kill(core, 'SIGKILL')+ await until('a new core to finish starting', () => ready(d) > wired || null, 60_000, 200)+ client.close()+ client = await LocalClient.connect(d)+ await until('the new core to answer with the same viewer', async () => (await row(client, sketch.id))?.viewerUrl === url || null, 60_000, 250)+ expect(viewersPid(d)).toBe(viewers)+ expect(restarts(d)).toBe(0)+ expect(await serves(url)).toMatch(/^sketch viewer \d+$/)+ await turn(client, sketch.id, 'after the core came back')+ client.close()+ })+})diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 640273706..23b6d08e6 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -164,8 +164,10 @@ import { databaseHistory } from './core/transcripts/databaseHistory.js'import { createCoreApi, emptyPorts, MODELS_FALLBACKS, SEARCH_FALLBACKS, TEAMS_FALLBACKS, VIEWERS_FALLBACKS, WORKSPACES_FALLBACKS, type TeamsPort } from './core/api.js'import { createServiceHost, testFaults } from './core/serviceHost.js'import { createServiceLinks } from './core/serviceLinks.js'+import { createViewersLink } from './core/viewersLink.js'import { KNOWN_SERVICES, serviceSpecs } from './harnessd/services.js'import { runSearchService } from './services/searchProcess.js'+import { runViewersService } from './services/viewersProcess.js'import { SEARCH_REQUESTS, startSearch } from './services/search.js'import { STORE_REQUESTS, startStore } from './services/store.js'import { startViewers } from './services/viewers.js'@@ -1811,8 +1813,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {// Each service starts and is called through the host, so one that fails is logged and left off and// the core carries on without it (core/serviceHost.ts).const serviceHost = createServiceHost(ports, { faults: testFaults(process.env.HARNESSD_TEST_FAULTS) })- // The DSH companions: each harness agent's viewer and verdict watch (services/viewers.ts).- serviceHost.start('viewers', startViewers, coreApi, VIEWERS_FALLBACKS)+ // The DSH companions: each harness agent's viewer and verdict watch (services/viewers.ts), started below.dshFrameContextRef = (s) => ports.viewers?.frameContext(s) ?? nullconst attachDsh = (s: RegisteredSession): void => ports.viewers?.attach(s)const detachDsh = (agentId: string): void => ports.viewers?.detach(agentId)@@ -2188,11 +2189,13 @@ async function runForeground(session: AuthSession | null): Promise<void> {const outOfProcess = new Set(serviceToken ? serviceSpecs(process.env, KNOWN_SERVICES).map((spec) => spec.name) : [])// 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 }+ // 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))const serviceLinks = createServiceLinks({token: serviceToken,owned: Object.fromEntries([...outOfProcess].map((name) => [name, requestsOf[name] ?? []])),- // Every agent, live then stopped, with the name the apps show for it: what search indexes.- answer: (_service, query) => query === 'agents'+ // 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) : query === 'agents'? { agents: coreApi.agents.all().map((session) => ({ ...session, displayName: coreApi.agents.displayName(session) })) }: { error: 'UNKNOWN_QUERY' },})@@ -2214,6 +2217,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {}// 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)// The harnesses installed here, and installing, updating and removing one (services/store.ts).serviceHost.serve('store', startStore, coreApi, STORE_REQUESTS)@@ -5573,12 +5579,13 @@ switch (cmd) {breakcase '__service': { // internal: a service harnessd's master runs in its own process (services/process.ts)const socketPath = localSocketPath(env.ADAPTER_DATA_DIR, env.PORT)- if (rest[0] !== 'search' || !socketPath) {+ const runService = rest[0] === 'search' ? runSearchService : rest[0] === 'viewers' ? runViewersService : null+ if (!runService || !socketPath) {console.error(`[service] ${rest[0] ?? '(none)'}: ${socketPath ? 'no such service in this build' : 'the core has no local socket to reach'}`)process.exit(2)}process.title = `harnessd ${rest[0]}`- runSearchService({ dataDir: env.ADAPTER_DATA_DIR, socketPath, machineId: computerId(), token: process.env.HARNESSD_SERVICE_TOKEN ?? '' })+ runService({ dataDir: env.ADAPTER_DATA_DIR, socketPath, machineId: computerId(), token: process.env.HARNESSD_SERVICE_TOKEN ?? '' })break}case '__run': // internal: the detached daemon child reads the durable SSO session — or runs without onediff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.mdindex 38affafe9..a3002b431 100644--- a/cli/src/core/AGENTS.md+++ b/cli/src/core/AGENTS.md@@ -30,4 +30,5 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE- `engines/`: the engines' hooks.- `input.ts`, `questions.ts`: messages into a pane; an agent's question and its answer.- `api.ts`: the contract with services. `serviceHost.ts`: services in this process.- `serviceLinks.ts`: services in their own processes.+ `serviceLinks.ts`: services in their own processes. `viewersLink.ts`: what the core keeps of the+ viewers when they run in theirs.diff --git a/cli/src/core/viewersLink.spec.ts b/cli/src/core/viewersLink.spec.tsnew file mode 100644index 000000000..7662d1201--- /dev/null+++ b/cli/src/core/viewersLink.spec.ts@@ -0,0 +1,149 @@+import { describe, expect, it, vi } from 'vitest'+import type { RegisteredSession } from '../lib/registry.js'+import { fakeCore } from '../testing/fakeCore.js'+import { createViewersLink } from './viewersLink.js'++const agent = (over: Partial<RegisteredSession> = {}) =>+ ({ agentId: 'a1', sessionId: 's1', engine: 'claude', dsh: 'acme/blender', cwd: '/work/scene', ...over }) as RegisteredSession++const context = (over: Record<string, unknown> = {}) =>+ ({ id: 'acme/blender', name: 'Blender', viewerUrl: null, viewerName: 'Blender Viewer', verdict: null, ...over })++function setup(live: RegisteredSession | null = agent(), terminalAvailable = true) {+ const core = fakeCore({+ agents: {+ byAgent: vi.fn(() => live ?? undefined),+ terminalAvailable: vi.fn(() => terminalAvailable),+ live: vi.fn(() => [agent(), agent({ agentId: 'plain', dsh: undefined }), agent({ agentId: 'a2', dsh: 'acme/kicad' })]),+ },+ })+ const notify = vi.fn(() => true)+ const link = createViewersLink(core, notify)+ return { core, notify, link, port: link.port }+}++describe('the viewers in their own process, as the core keeps them', () => {+ it('tells the process of each agent with a harness it attaches, and of no other', () => {+ const { notify, port } = setup()+ port.attach(agent())+ port.attach(agent({ agentId: 'plain', dsh: undefined }))+ // Not held while the process is down: it asks for every agent each time it connects.+ expect(notify.mock.calls).toEqual([[{ type: 'service_event', payload: { kind: 'attach', session: agent() } }]])+ })++ it('answers a frame with the fallbacks until the process has said anything of the agent', () => {+ const { port } = setup()+ port.attach(agent())+ expect(port.frameContext(agent())).toBeNull()+ expect(port.forwardingUrl('a1')).toBeNull()+ })++ it('keeps what the process says of an attached agent, follows its viewer and sends its frame again', () => {+ const { core, link, port } = setup()+ port.attach(agent())+ const said = context({ viewerUrl: 'http://127.0.0.1:7001/' })+ expect(link.answer('context', { agentId: 'a1', context: said, forwardingUrl: 'http://127.0.0.1:7001/', requestId: 'q1', query: 'context' })).toEqual({ kept: true })+ expect(port.frameContext(agent())).toEqual(said)+ expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')+ expect(core.agents.sync).toHaveBeenCalledWith(agent())+ // An agent without a harness has nothing to say on its frame, whatever was kept under its id.+ expect(port.frameContext(agent({ dsh: undefined }))).toBeNull()+ })++ it('a change that moves no viewer sends the frame without disturbing the viewer panes; no change does nothing', () => {+ const { core, link, port } = setup()+ port.attach(agent())+ link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })+ // Its first word moved nothing a viewer pane follows: no viewer yet.+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()+ expect(core.agents.sync).toHaveBeenCalledTimes(1)+ const verdict = { ready: true, summary: 'ok', errors: 0, warnings: 0, artifact: null, phases: [], updatedAt: null }+ link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })+ expect(port.frameContext(agent())).toMatchObject({ verdict })+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()+ expect(core.agents.sync).toHaveBeenCalledTimes(2)+ expect(link.answer('context', { agentId: 'a1', context: context({ verdict }), forwardingUrl: null })).toEqual({ kept: true })+ expect(core.agents.sync).toHaveBeenCalledTimes(2)+ })++ it('follows a viewer URL that moves even when nothing forwards to it', () => {+ const { core, link, port } = setup()+ port.attach(agent())+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://elsewhere.test/' }), forwardingUrl: null })+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')+ })++ it('waits for the terminal before sending a frame, which would otherwise read as "agent gone"', () => {+ const detached = setup(agent(), false)+ detached.port.attach(agent())+ detached.link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })+ expect(detached.port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })+ expect(detached.core.agents.sync).not.toHaveBeenCalled()+ const gone = setup(null)+ gone.port.attach(agent())+ gone.link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })+ expect(gone.core.agents.sync).not.toHaveBeenCalled()+ })++ it('keeps nothing of an agent it never attached, or detached since: a word said before the detach is older than it', () => {+ const { core, link, port } = setup()+ expect(link.answer('context', { agentId: 'a1', context: context(), forwardingUrl: null })).toEqual({ kept: false })+ port.attach(agent())+ port.detach('a1')+ expect(link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })).toEqual({ kept: false })+ expect(port.frameContext(agent())).toBeNull()+ expect(port.forwardingUrl('a1')).toBeNull()+ expect(core.agents.sync).not.toHaveBeenCalled()+ // Nor of one it cannot name.+ expect(link.answer('context', { agentId: 7, context: context() })).toEqual({ kept: false })+ })++ it('reads what does not look like a context or a URL as none', () => {+ const { link, port } = setup()+ port.attach(agent())+ link.answer('context', { agentId: 'a1', context: 'not a context', forwardingUrl: 9 })+ expect(port.frameContext(agent())).toBeNull()+ expect(port.forwardingUrl('a1')).toBeNull()+ })++ it('a detach forgets the agent, lets the viewer panes go of a viewer it had, and is held until the process hears it', () => {+ const { core, notify, link, port } = setup()+ port.attach(agent())+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })+ vi.mocked(core.clients.viewerChanged).mockClear()+ port.detach('a1')+ expect(core.clients.viewerChanged).toHaveBeenCalledWith('a1')+ expect(notify).toHaveBeenLastCalledWith({ type: 'service_event', payload: { kind: 'detach', agentId: 'a1' } }, { untilDelivered: true })+ expect(port.frameContext(agent())).toBeNull()+ // One with no viewer, or never heard of, has no viewer pane to let go of.+ vi.mocked(core.clients.viewerChanged).mockClear()+ port.attach(agent({ agentId: 'a2' }))+ link.answer('context', { agentId: 'a2', context: null, forwardingUrl: null })+ port.detach('a2')+ port.detach('never')+ expect(core.clients.viewerChanged).not.toHaveBeenCalled()+ })++ it('answers from what it last knew while the process cannot hear anything', () => {+ const { link, notify, port } = setup()+ port.attach(agent())+ link.answer('context', { agentId: 'a1', context: context({ viewerUrl: 'http://127.0.0.1:7001/' }), forwardingUrl: 'http://127.0.0.1:7001/' })+ notify.mockReturnValue(false)+ port.attach(agent())+ expect(port.frameContext(agent())).toMatchObject({ viewerUrl: 'http://127.0.0.1:7001/' })+ expect(port.forwardingUrl('a1')).toBe('http://127.0.0.1:7001/')+ })++ it('names the agents with a harness when the process asks, and refuses a question it does not know', () => {+ const { link } = setup()+ expect(link.answer('agents', {})).toEqual({ agents: [agent(), agent({ agentId: 'a2', dsh: 'acme/kicad' })] })+ expect(link.answer('session_search', {})).toEqual({ error: 'UNKNOWN_QUERY' })+ })++ it('stops nothing in the core: the viewers are the process\'s', async () => {+ const { notify, port } = setup()+ await expect(port.stop()).resolves.toBeUndefined()+ expect(notify).not.toHaveBeenCalled()+ })+})diff --git a/cli/src/core/viewersLink.ts b/cli/src/core/viewersLink.tsnew file mode 100644index 000000000..6d9b9650b--- /dev/null+++ b/cli/src/core/viewersLink.ts@@ -0,0 +1,97 @@+/**+ * The DSH viewers in their own process, as the core sees them (`HARNESSD_SERVICES=viewers`; the+ * process's side is services/viewersProcess.ts).+ *+ * The core asks the viewers two things while it builds an agent's frame: what its DSH context is (its+ * harness's name, its viewer URL, its verdict) and where the windows' viewer pane forwards to. A frame+ * cannot wait on another process, so the viewers tell the core each agent's answers whenever they change+ * (a `service_query` of kind `context`), the core keeps the last of them here, and the port answers from+ * that: while the process is down, with what it last knew, or the fallbacks for an agent it never heard+ * of. Each change then does in the core what the viewers did in their process: the windows' viewer panes+ * follow a viewer that moved (`clients.viewerChanged`), and the frame of an agent whose terminal is+ * attached goes out again.+ *+ * Attach and detach go to the process as notifications (`service_event`). A detach it missed would leave+ * a viewer running, so it is held until the process hears it. An attach it missed is caught up instead:+ * the process asks for every agent with a harness (`agents`) each time it connects, which a restarted+ * process needs anyway, since it starts holding nothing. Holding attaches as well would only pile up the+ * core's repeats (one per agent on every discovery pass) while the process is down.+ *+ * The core keeps what it hears only for the agents it has attached and not since detached: what the+ * process says of an agent before it hears the agent's detach must not bring the forgotten agent's+ * viewer back. The process says everything again on each attach, which is how the core's first word on+ * an agent arrives after a core restart, when the process connects before the core has attached anyone.+ */+import type { AgentDshContext } from '../lib/agentFrame.js'+import type { CoreApi, ViewersPort } from './api.js'+import type { ServiceFrame } from './serviceLinks.js'++/** Tell the viewers' process something (core/serviceLinks.ts `notify`, for `viewers`). */+export type NotifyViewers = (frame: ServiceFrame, opts?: { untilDelivered?: boolean }) => boolean++/** What the viewers last said of one agent. */+interface Known {+ context: AgentDshContext | null+ forwardingUrl: string | null+}++/** The two URLs a change in which the windows' viewer panes must follow. */+const urls = (known: Known | undefined): string => JSON.stringify([known?.context?.viewerUrl ?? null, known?.forwardingUrl ?? null])++export function createViewersLink(core: Pick<CoreApi, 'agents' | 'clients'>, notify: NotifyViewers) {+ const attached = new Set<string>()+ const known = new Map<string, Known>()++ const port: ViewersPort = {+ attach: (session) => {+ if (!session.dsh) return+ attached.add(session.agentId)+ notify({ type: 'service_event', payload: { kind: 'attach', session } })+ },+ detach: (agentId) => {+ attached.delete(agentId)+ const had = known.get(agentId)+ known.delete(agentId)+ // The windows' viewer panes let go of its viewer at once, as when it stopped in this process.+ if (urls(had) !== urls(undefined)) core.clients.viewerChanged(agentId)+ notify({ type: 'service_event', payload: { kind: 'detach', agentId } }, { untilDelivered: true })+ },+ frameContext: (session) => (session.dsh ? known.get(session.agentId)?.context ?? null : null),+ forwardingUrl: (agentId) => known.get(agentId)?.forwardingUrl ?? null,+ // The viewers are the process's: a core restarting or stopping leaves them running for the next core,+ // and the master stops the process itself when the daemon stops.+ stop: async () => {},+ }++ /** The process says what one agent's frame says of its harness now. */+ const heard = (payload: Record<string, unknown>): Record<string, unknown> => {+ const agentId = typeof payload.agentId === 'string' ? payload.agentId : ''+ if (!attached.has(agentId)) return { kept: false }+ const next: Known = {+ context: payload.context && typeof payload.context === 'object' ? payload.context as AgentDshContext : null,+ forwardingUrl: typeof payload.forwardingUrl === 'string' ? payload.forwardingUrl : null,+ }+ const before = known.get(agentId)+ if (JSON.stringify(before) === JSON.stringify(next)) return { kept: true }+ known.set(agentId, next)+ if (urls(before) !== urls(next)) core.clients.viewerChanged(agentId)+ // Only once the agent's terminal is attached: a frame with none reads to the desktop as "agent gone"+ // (services/viewers.ts, `syncCompanion`). The attach's own sync carries what arrived first.+ const session = core.agents.byAgent(agentId)+ if (session && core.agents.terminalAvailable(agentId)) core.agents.sync(session)+ return { kept: true }+ }++ return {+ port,+ /** The core's answers to the viewers' questions (core/serviceLinks.ts `answer`, for `viewers`). */+ answer(query: string, payload: Record<string, unknown>): Record<string, unknown> {+ // Every agent the core has with a harness, dormant ones too: the ones it attaches at start.+ if (query === 'agents') return { agents: core.agents.live().filter((session) => session.dsh) }+ if (query === 'context') return heard(payload)+ return { error: 'UNKNOWN_QUERY' }+ },+ }+}++export type ViewersLink = ReturnType<typeof createViewersLink>diff --git a/cli/src/harnessd/services.ts b/cli/src/harnessd/services.tsindex e57710319..de15a3b4a 100644--- a/cli/src/harnessd/services.ts+++ b/cli/src/harnessd/services.ts@@ -288,11 +288,14 @@ export class ServiceSupervisor {/*** The services this build can run in their own processes, with their memory budgets. Which of them do- * is `HARNESSD_SERVICES` (`search`): off until named, while each one beds in, and the core runs a+ * is `HARNESSD_SERVICES` (`search,viewers`): off until named, while each one beds in, and the core runs a* service that is not out here in its own process, as before.*/export const KNOWN_SERVICES: Readonly<Record<string, Omit<ServiceSpec, 'name'>>> = {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 },}/** Service timings from the environment (for tests and support); anything unset or invalid keeps its default. */diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.mdindex 5a5d31167..92e51ed29 100644--- a/cli/src/services/AGENTS.md+++ b/cli/src/services/AGENTS.md@@ -39,7 +39,7 @@ let several people build features at once without touching the core or each othe## Running in its own processA service that can crash natively, hang or leak should run in its own process, where it costs only-itself. Search does: `HARNESSD_SERVICES=search`.+itself. Search and the viewers do: `HARNESSD_SERVICES=search,viewers` (either alone, too).- `src/harnessd/services.ts` runs it (`KNOWN_SERVICES`, with its memory budget). The core routes therequests it declared (its `<NAME>_REQUESTS`) to its process, and the same handlers answer them there.@@ -49,6 +49,12 @@ itself. Search does: `HARNESSD_SERVICES=search`.`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 proofto copy: killed, hung (SIGSTOP), leaking, crashing on every start.+- 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+ the last ones and its port answers from them, or from the fallbacks before it has heard any. The+ process asks the core for everything it should hold each time it connects, which a restarted+ process needs anyway. `e2e/viewersProcess.e2e.ts` proves it with a real harness agent's viewer.## Do notdiff --git a/cli/src/services/viewersProcess.spec.ts b/cli/src/services/viewersProcess.spec.tsnew file mode 100644index 000000000..2cc3c413e--- /dev/null+++ b/cli/src/services/viewersProcess.spec.ts@@ -0,0 +1,251 @@+import { afterEach, describe, expect, it, vi } from 'vitest'+import type { CoreApi, CorePorts, ViewersPort } from '../core/api.js'+import type { AgentDshContext } from '../lib/agentFrame.js'+import type { RegisteredSession } from '../lib/registry.js'+import { runServiceProcess, type CoreConnection, type ServiceProcessOptions } from './process.js'+import { runViewersService, viewersCoreApi } from './viewersProcess.js'++// The real default reaches a real socket and this process's own channel: never in a test.+vi.mock('./process.js', () => ({ runServiceProcess: vi.fn(() => ({ stop: vi.fn() })) }))++const agent = (agentId = 'a1', over: Partial<RegisteredSession> = {}) =>+ ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', dsh: 'acme/blender', cwd: `/work/${agentId}`, ...over }) as RegisteredSession++/** Viewers that start nothing: what each agent's frame says is whatever the test sets. */+function fakeViewers() {+ const contexts = new Map<string, AgentDshContext>()+ const urls = new Map<string, string>()+ const port = {+ attach: vi.fn(),+ detach: vi.fn(),+ frameContext: vi.fn((session: RegisteredSession) => contexts.get(session.agentId) ?? null),+ forwardingUrl: vi.fn((agentId: string) => urls.get(agentId) ?? null),+ stop: vi.fn(async () => {}),+ } satisfies ViewersPort+ return { port, contexts, urls }+}++/** A connection to the core that records what it is told and answers `agents` with `listed`. */+function connection(listed: unknown = { agents: [] }) {+ const query = vi.fn(async (name: string, _payload?: Record<string, unknown>) => (name === 'agents' ? listed : { kept: true }) as Record<string, unknown>)+ const told = () => query.mock.calls.filter(([name]) => name === 'context').map(([, payload]) => payload)+ return { core: { query } satisfies CoreConnection, query, told }+}++const flush = () => new Promise((done) => setTimeout(done, 0))++describe('the viewers in their own process', () => {+ afterEach(() => vi.clearAllMocks())++ const setup = (over: Partial<Parameters<typeof runViewersService>[0]> = {}) => {+ 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!() }+ }++ it('reaches the core as `viewers`, through the socket and token it was given, and answers the apps nothing', () => {+ const { options } = setup()+ expect(options).toMatchObject({ name: 'viewers', socketPath: '/data/daemon-1.sock', machineId: 'm', token: 't' })+ expect(options.requests).toEqual({})+ })++ it('attaches what the core attaches, tells the core what the agent\'s frame says, and detaches what it detaches', async () => {+ const { viewers, api, options } = setup()+ const core = connection()+ options.onConnected!(core.core)+ await flush()+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: null, viewerName: 'Blender Viewer', verdict: null })+ options.onEvent!({ kind: 'attach', session: agent() })+ expect(viewers.port.attach).toHaveBeenCalledWith(agent())+ expect(api.agents.byAgent('a1')).toEqual(agent())+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])+ options.onEvent!({ kind: 'detach', agentId: 'a1' })+ expect(viewers.port.detach).toHaveBeenCalledWith('a1')+ expect(api.agents.byAgent('a1')).toBeUndefined()+ // What a stopping viewer says after its detach is not the core's to hear.+ api.clients.viewerChanged('a1')+ expect(core.told()).toHaveLength(1)+ })++ it('tells the core each change once, where the service would move the viewer panes or push a frame', async () => {+ const { viewers, api, options } = setup()+ const core = connection()+ options.onConnected!(core.core)+ options.onEvent!({ kind: 'attach', session: agent() })+ // A viewer came up: its URL, and where the windows' pane forwards.+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: 'http://127.0.0.1:7001/', verdict: null })+ viewers.urls.set('a1', 'http://127.0.0.1:7001/')+ api.clients.viewerChanged('a1')+ api.agents.sync(agent())+ expect(core.told()).toEqual([+ { agentId: 'a1', context: null, forwardingUrl: null },+ { agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: 'http://127.0.0.1:7001/' },+ ])+ // A verdict: the frame changes, and the core hears it.+ viewers.contexts.set('a1', { ...viewers.contexts.get('a1')!, verdict: { ready: true, summary: null, errors: 0, warnings: 0, artifact: null, phases: [], updatedAt: null } })+ api.agents.sync(agent())+ expect(core.told()).toHaveLength(3)+ // Said again on every attach, changed or not: a core that restarted keeps nothing until it attaches.+ options.onEvent!({ kind: 'attach', session: agent() })+ expect(core.told()).toHaveLength(4)+ })++ it('says nothing before it is connected, then everything the core lists once it has caught up', async () => {+ const { viewers, options } = setup()+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: null, verdict: null })+ options.onEvent!({ kind: 'attach', session: agent() })+ expect(viewers.port.attach).toHaveBeenCalledOnce()+ const core = connection({ agents: [agent()] })+ options.onConnected!(core.core)+ expect(core.told()).toEqual([])+ await flush()+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])+ })++ it('catches up with the core\'s agents on every connection: attaches what is missing, detaches what is gone', async () => {+ const { viewers, api, options } = setup()+ options.onEvent!({ kind: 'attach', session: agent('gone') })+ options.onEvent!({ kind: 'attach', session: agent('kept') })+ const core = connection({ agents: [agent('kept'), agent('new'), { not: 'an agent' }, null] })+ options.onConnected!(core.core)+ await flush()+ expect(viewers.port.attach).toHaveBeenCalledWith(agent('new'))+ expect(viewers.port.detach).toHaveBeenCalledWith('gone')+ expect(viewers.port.detach).toHaveBeenCalledTimes(1)+ expect(api.agents.all().map((session) => session.agentId).sort()).toEqual(['kept', 'new'])+ expect(api.agents.live()).toHaveLength(2)+ })++ it('leaves an agent heard of since it asked: news newer than the core\'s answer', async () => {+ const { viewers, api, options } = setup()+ options.onEvent!({ kind: 'attach', session: agent('a1') })+ let answer: (value: Record<string, unknown>) => void = () => {}+ const query = vi.fn((name: string) => (name === 'agents' ? new Promise<Record<string, unknown>>((done) => { answer = done }) : Promise.resolve({ kept: true })))+ options.onConnected!({ query })+ // While the question is out: a new agent attached, an old one detached.+ options.onEvent!({ kind: 'attach', session: agent('a4') })+ options.onEvent!({ kind: 'detach', agentId: 'a1' })+ answer({ agents: [agent('a1')] })+ await flush()+ expect(api.agents.all().map((session) => session.agentId)).toEqual(['a4'])+ // Attached once, before the question: the answer naming it did not bring it back.+ expect(viewers.port.attach.mock.calls.filter(([session]) => session.agentId === 'a1')).toHaveLength(1)+ })++ it('ignores an older connection\'s answer, an answer that names no agents, and a core that cannot answer', async () => {+ const { viewers, options } = setup()+ let answer: (value: Record<string, unknown>) => void = () => {}+ const older = vi.fn((name: string) => (name === 'agents' ? new Promise<Record<string, unknown>>((done) => { answer = done }) : Promise.resolve({})))+ options.onConnected!({ query: older })+ options.onConnected!(connection({ error: 'UNKNOWN_QUERY' }).core)+ answer({ agents: [agent('late')] })+ await flush()+ options.onConnected!({ query: vi.fn(async () => { throw new Error('the core went away') }) })+ await flush()+ expect(viewers.port.attach).not.toHaveBeenCalled()+ })++ it('a word lost with its connection is said again on the next one', async () => {+ const { viewers, options } = setup()+ const lost = vi.fn(async (name: string) => {+ if (name === 'context') throw new Error('the core went away')+ return { agents: [agent()] }+ })+ viewers.contexts.set('a1', { id: 'acme/blender', name: 'Blender', viewerUrl: 'http://127.0.0.1:7001/', verdict: null })+ options.onConnected!({ query: lost })+ options.onEvent!({ kind: 'attach', session: agent() })+ await flush()+ const core = connection({ agents: [agent()] })+ options.onConnected!(core.core)+ await flush()+ expect(core.told()).toEqual([{ agentId: 'a1', context: viewers.contexts.get('a1'), forwardingUrl: null }])+ })++ it('ignores what it is told that it does not act on', () => {+ const { viewers, options } = setup()+ options.onEvent!({ kind: 'touch', sessionId: 's1' })+ options.onEvent!({ kind: 'attach' })+ options.onEvent!({ kind: 'attach', session: { dsh: 'acme/blender' } })+ options.onEvent!({ kind: 'detach', agentId: 7 })+ expect(viewers.port.attach).not.toHaveBeenCalled()+ 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()+ 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 () => {+ 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])+ })++ it('does not run without viewers: the master starts it again, or parks it', () => {+ expect(() => setup({ start: () => {} })).toThrow('the viewers did not start')+ })++ it('runs on a core API of the agents the core attached, answering what the viewers never ask as nothing', async () => {+ const sessions = new Map([['a1', agent()]])+ const tell = vi.fn()+ const api = viewersCoreApi('/data', sessions, tell)+ expect(api.dataDir).toBe('/data')+ expect(api.agents.all()).toEqual([agent()])+ expect(api.agents.live()).toEqual([agent()])+ expect(api.agents.byAgent('a1')).toEqual(agent())+ expect(api.agents.displayName(agent())).toBe('')+ expect(api.agents.advertised()).toEqual([])+ // The core judges the terminal when it hears: here every change is worth telling.+ expect(api.agents.terminalAvailable('a1')).toBe(true)+ api.agents.sync(agent())+ api.clients.viewerChanged('a1')+ expect(tell.mock.calls).toEqual([['a1'], ['a1']])+ expect(api.transcripts.databaseHistory(agent())).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()+ await expect(api.account.accessToken()).rejects.toThrow('the viewers hold no credential')+ api.clients.gridNamed('grid')+ 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()+ }+ })+})diff --git a/cli/src/services/viewersProcess.ts b/cli/src/services/viewersProcess.tsnew file mode 100644index 000000000..499379ea0--- /dev/null+++ b/cli/src/services/viewersProcess.ts@@ -0,0 +1,165 @@+/**+ * The DSH viewers in their own process (`harness __service viewers`, with `HARNESSD_SERVICES=viewers`).+ *+ * The same viewer servers and verdict watches as in the core's process (services/viewers.ts), on a core+ * API built here. The agents are the ones the core attaches: it says each attach and detach+ * (`service_event`), and each time this process connects it asks the core for every agent with a harness+ * (`service_query agents`) and catches up, so a process started after a crash, or reconnected after the+ * core restarted, holds exactly the viewers the core's agents should have.+ *+ * What the core used to read from the service while it builds a frame (an agent's DSH context, where the+ * windows' viewer pane forwards) is told to the core whenever it changes (`service_query context`), and+ * the core keeps it (core/viewersLink.ts). Where the service would push a frame or move the windows'+ * viewer panes in the core's process, it tells the core here, and the core does both as before.+ *+ * The viewer servers, the watches on every harness's workspace and their restarts are this process's+ * alone: a crash or a leak costs the viewers, and the master starts them again. A new process stops the+ * viewer servers a crashed one left running before it starts its own (dsh/viewerLedger.ts). A core restart+ * no longer restarts every viewer: they stay up here, and the new core hears their URLs at once.+ */+import type { CoreApi } from '../core/api.js'+import { emptyPorts } from '../core/api.js'+import type { RegisteredSession } from '../lib/registry.js'+import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'+import { startViewers } from './viewers.js'++export interface ViewersServiceOptions {+ 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 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. */+const isSession = (value: unknown): value is RegisteredSession =>+ !!value && typeof value === 'object' && typeof (value as { agentId?: unknown }).agentId === 'string'++/**+ * The core API the viewers run on in their own process: the agents the core attached, and `tell` for+ * what the service would do to the core's windows. Whether an agent's terminal is attached is the core's+ * to judge when it hears; what the viewers never ask (search, sign-in) answers as nothing.+ */+export function viewersCoreApi(dataDir: string, sessions: ReadonlyMap<string, RegisteredSession>, tell: (agentId: string) => void): CoreApi {+ const attached = (): RegisteredSession[] => [...sessions.values()]+ return {+ dataDir,+ agents: {+ all: attached,+ live: attached,+ displayName: () => '',+ byAgent: (agentId) => sessions.get(agentId),+ advertised: () => [],+ terminalAvailable: () => true,+ sync: (session) => tell(session.agentId),+ },+ 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('the viewers hold no credential')) },+ clients: { viewerChanged: tell, gridNamed: () => {}, dshInstallStatus: () => {} },+ }+}++export function runViewersService(options: ViewersServiceOptions): ServiceProcess {+ /** The agents the core attached, by agent id: what this process holds viewers for. */+ const sessions = new Map<string, RegisteredSession>()+ /** What the current connection was last told of each agent, so a change is said once. */+ const told = new Map<string, string>()+ /** The agents attached or detached since the core was last asked for all of them: newer than its answer. */+ const heard = new Set<string>()+ let core: CoreConnection | null = null+ const ports = emptyPorts()++ const tell = (agentId: string): void => {+ const session = sessions.get(agentId)+ // A detached agent is the core's to forget: nothing said after its detach may bring it back.+ if (!core || !session) return+ const state = { agentId, context: viewers.frameContext(session), forwardingUrl: viewers.forwardingUrl(agentId) }+ const said = JSON.stringify(state)+ if (told.get(agentId) === said) return+ told.set(agentId, said)+ // Lost only with the connection; the next connection is told everything again.+ void core.query('context', state).catch(() => {})+ }++ ;(options.start ?? startViewers)(viewersCoreApi(options.dataDir, sessions, tell), ports)+ if (!ports.viewers) throw new Error('the viewers did not start')+ const viewers = ports.viewers++ const attach = (session: RegisteredSession): void => {+ sessions.set(session.agentId, session)+ viewers.attach(session)+ // Said again on every attach: a core that restarted has heard nothing yet, and keeps what it hears+ // only of an agent it has attached (core/viewersLink.ts).+ told.delete(session.agentId)+ tell(session.agentId)+ }+ const detach = (agentId: string): void => {+ sessions.delete(agentId)+ told.delete(agentId)+ viewers.detach(agentId)+ }+ /** Every agent the core has with a harness, as it answered: attach what is missing here, detach what it+ * no longer has, but leave an agent heard of since the question, whose news is newer than the answer. */+ const catchUp = (agents: unknown): void => {+ if (!Array.isArray(agents)) return+ const listed = new Map(agents.filter(isSession).map((session) => [session.agentId, session]))+ for (const [agentId, session] of listed) if (!heard.has(agentId)) attach(session)+ for (const agentId of [...sessions.keys()]) if (!listed.has(agentId) && !heard.has(agentId)) detach(agentId)+ }++ const exit = options.exit ?? ((code: number) => process.exit(code))+ let stopping: Promise<void> | null = null+ const stop = (): Promise<void> => {+ stopping ??= Promise.resolve().then(() => {+ service.stop()+ return viewers.stop()+ })+ 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({+ name: 'viewers',+ socketPath: options.socketPath,+ machineId: options.machineId,+ 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)+ attach(payload.session)+ } else if (payload.kind === 'detach' && typeof payload.agentId === 'string') {+ heard.add(payload.agentId)+ detach(payload.agentId)+ }+ },+ onConnected: (connection) => {+ core = connection+ told.clear()+ heard.clear()+ // The catch-up attaches every agent the core lists, and each attach tells the core that agent's+ // context: a new core hears everything, and one that only dropped the connection what changed.+ 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() } }+}diff --git a/docs/design/2026-10-03-harnessd.md b/docs/design/2026-10-03-harnessd.mdindex d280d639c..faebe7f83 100644--- a/docs/design/2026-10-03-harnessd.md+++ b/docs/design/2026-10-03-harnessd.md@@ -469,6 +469,15 @@ Done so far:`cli/src/services/searchProcess.ts` runs the same index on a core API built in its own process.`e2e/serviceProcesses.e2e.ts` proves on the real daemon that search killed, hung (stopped), leakingor crashing on every start costs search alone: the core never restarts and agents keep working.+- **The viewers in their own process** (`HARNESSD_SERVICES=viewers`, alone or beside search). The core+ asks the viewers two things in line while it builds a frame: an agent's DSH context and where its+ viewer pane forwards. So the process tells the core each agent's answers whenever they change, and+ the core keeps the last ones (`cli/src/core/viewersLink.ts`). While the process is down, frames carry+ what the core last knew. Attach and detach are notifications; a detach is held until the process+ hears it, and the process asks for every agent with a harness each time it connects. The viewer+ servers are the process's own: a crash costs only them (the new process stops the ones the old one+ left running, then starts its own), and a core restart no longer restarts them.+ `cli/e2e/viewersProcess.e2e.ts` proves it on the real daemon with a real harness agent's viewer.- **Services answer their own requests** (core/serviceHost.ts `route`). A service declares the frametypes it answers (`<NAME>_REQUESTS`) and returns their handlers from its start. The socket handssuch a request to it before its own switch, with who asked (`Asker`: local, owner), and never