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
/**
* A read-only view of agents' terminals for a feature's own viewers (`core.terminals.watch`): Share's
* observers. The plan's "read-only terminal subscription" (docs/design/2026-10-06-core-boundary-next.md,
* "Sharing"): Share used to read panes through a stream manager of its own over the core's terminals; now the
* core runs that manager, read-only, and a feature in its own process hands it each viewer's terminal frames
* and hears back what each viewer is shown. A viewer can only watch: the manager is read-only, and refuses
* input before any reaches a pane, as Share's own did.
*
* What a viewer is shown goes to whoever asked for it: a listener in the core's process (`onOutput`), or the
* process that sent the viewer's frames (`tell`). A terminal's bytes go as `binary`, base64 of the local
* binary frame (lib/terminalBinary.ts `encodeTerminalLocal`), as Share already carried them to its observers.
*/
import type { MoveGate } from '../lib/hostMove/gate.js'
import type { RegisteredSession } from '../lib/registry.js'
import type { TerminalBackendCoordinator } from '../lib/terminalBackendCoordinator.js'
import type { TerminalRuntimeRef } from '../lib/terminalTypes.js'
import { encodeTerminalLocal } from '../lib/terminalBinary.js'
import { TerminalStreamManager } from '../lib/terminalStreamManager.js'
import type { TerminalWatch, TerminalWatchOutput } from './api.js'
type Payload = Record<string, unknown>
/** The most viewers whose process is remembered; past it the oldest is forgotten. Share takes 100 at most. */
export const KEPT_VIEWERS = 1_000
export interface TerminalWatchDeps {
terminals: Pick<TerminalBackendCoordinator, 'openStream'>
resolve: (agentId: string) => RegisteredSession | undefined
/** Tell a process what its viewer is shown; false when it could not be told (the stream then closes). */
tell: (service: string, viewer: string, output: TerminalWatchOutput) => boolean
/** The processes that may watch: a viewer is only ever an experiment's. */
watchers: ReadonlySet<string>
/** The core's gate for an agent changing host (hostMove/gate.ts): a viewer that opens during a move counts as
* someone using the agent, and its stream is moved with the agent's others (`retarget`). */
moveGate?: MoveGate
/** Swapped in tests for a manager they can drive. */
manager?: (deps: ConstructorParameters<typeof TerminalStreamManager>[0]) => WatchManager
}
type WatchManager = Pick<TerminalStreamManager, 'handleFrame' | 'closeConnection' | 'stop' | 'isLookedAt' | 'retarget'>
const text = (value: unknown): string => (typeof value === 'string' ? value : '')
export function createTerminalWatch(deps: TerminalWatchDeps) {
const listeners = new Set<(viewer: string, output: TerminalWatchOutput) => void>()
/** Which process each viewer is a process's, oldest first. */
const owners = new Map<string, string>()
const show = (viewer: string, output: TerminalWatchOutput): boolean => {
const owner = owners.get(viewer)
if (owner) return deps.tell(owner, viewer, output)
let shown = false
for (const listener of listeners) {
try { listener(viewer, output); shown = true } catch { /* that listener's viewer misses the frame */ }
}
return shown
}
let manager: WatchManager | null = null
/** Built at the first viewer: a daemon no one shares costs no stream manager. */
const streams = () => manager ??= (deps.manager ?? ((d) => new TerminalStreamManager(d)))({
readOnly: true,
terminals: deps.terminals as TerminalBackendCoordinator,
resolveAgent: deps.resolve,
streamingAvailable: true,
...(deps.moveGate ? { moveGate: deps.moveGate } : {}),
sendTarget: (viewer, type, payload) => show(viewer, { type, payload }),
sendBinaryTarget: (viewer, frame) => {
const bytes = encodeTerminalLocal(frame)
return bytes !== null && show(viewer, { binary: Buffer.from(bytes).toString('base64') })
},
})
const watch: TerminalWatch = {
frame: async (viewer, type, payload) => { await streams().handleFrame(viewer, type, payload) },
close: async (viewer) => {
await manager?.closeConnection(viewer)
owners.delete(viewer)
},
onOutput: (listener) => {
listeners.add(listener)
return () => { listeners.delete(listener) }
},
}
return {
/** The watch of the core's own `CoreApi`, for a feature in this process. */
watch,
/** Whether a Share viewer has this agent's terminal open (a viewer is a person, never a `watch: true` reader). */
isWatched(agentId: string): boolean { return manager?.isLookedAt(agentId) ?? false },
/** Move the viewers' streams of [agentId] to [to]: the agent changed host (`TerminalStreamManager.retarget`). */
async retarget(agentId: string, to: TerminalRuntimeRef): Promise<void> { await manager?.retarget(agentId, to) },
/** A process's viewer's frame (`watch_frame`) or its end (`watch_close`): null for any other query. */
async answer(service: string, query: string, payload: Payload): Promise<Payload | null> {
if (query !== 'watch_frame' && query !== 'watch_close') return null
if (!deps.watchers.has(service)) return { error: 'NOT_A_WATCHER' }
const viewer = text(payload.viewer)
if (!viewer) return { error: 'INVALID_VIEWER' }
if (query === 'watch_close') { await watch.close(viewer); return {} }
const type = text(payload.type)
if (!type.startsWith('terminal_')) return { error: 'INVALID_FRAME' }
owners.delete(viewer)
owners.set(viewer, service)
if (owners.size > KEPT_VIEWERS) owners.delete(owners.keys().next().value!)
await watch.frame(viewer, type, payload.payload && typeof payload.payload === 'object' ? payload.payload as Payload : {})
return {}
},
/** A process went: every viewer it had stops being shown anything. */
async gone(service: string): Promise<void> {
for (const [viewer, owner] of [...owners]) if (owner === service) await watch.close(viewer)
},
async stop(): Promise<void> { await manager?.stop() },
}
}
export type TerminalWatchLink = ReturnType<typeof createTerminalWatch>