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
/**
* 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 frame of an agent
* whose terminal is attached goes out again. (A viewer that moved used to move the core's streams to it
* too; they are the viewers' own now, and follow it in their process.)
*
* 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.
*
* A client served a viewer over its connection (core/viewerStreams.ts): each frame of its stream is told
* to the process as it comes, never held (a stream dies with the process that held it), and refused
* instead while the process is not reading, so a hung one cannot pile a client's uploads up in the core.
* What the stream answers comes back as a notice for that connection; one the core cannot deliver ends
* that stream in the process, as a frame the forwarder could not send ended it in the core's. A rendered
* frame (`viewer_surface`) is asked of the process (`surface`), and answered unavailable, as a routed
* request is, if it is down or slower than a client waits.
*
* The process runs on demand (core/viewersWake.ts): an agent with a harness attached asks for it, and so does a
* client's stream that comes before it has ever connected to this core. That stream's frames are held, in order and
* bounded, until it connects, as a request to a service on demand waits for it (core/serviceLinks.ts `onDemand`), and
* refused if it has not come within a start's wait. Once it has connected, a stream is refused at once while it is
* down, as before: a process that went down is the master's to bring back, and a client waits for nobody meanwhile.
* Held, a stream that woke a process with no viewer yet is refused by the viewers themselves; one that came while a
* running process reconnects to a core that restarted is served.
*/
import type { AgentDshContext } from '../lib/agentFrame.js'
import { viewerStreamId } from '../lib/viewerFrames.js'
import { VIEWERS_UNAVAILABLE, type CoreApi, type ViewersPort } from './api.js'
import { ON_DEMAND_START_MS, type ServiceFrame } from './serviceLinks.js'
import { NOT_SERVED } from './viewerStreams.js'
/** Tell the viewers' process something (core/serviceLinks.ts `notify`, for `viewers`). */
export type NotifyViewers = (frame: ServiceFrame, opts?: { untilDelivered?: boolean }) => boolean
/** The rest of the link to the viewers' process (core/serviceLinks.ts `call` and `buffered`, for `viewers`). */
export interface ViewersChannel {
call(type: string, payload: Record<string, unknown>, waitMs?: number): Promise<Record<string, unknown>>
buffered(): number
}
/** Past this many bytes waiting on the socket to the viewers' process, it is not reading: a stream's frame
* is refused rather than kept. A client sends at most a viewer window (128 KiB) per stream unacknowledged
* (lib/viewerWire.ts), so a process that reads keeps far less than this waiting. */
export const VIEWERS_BUFFER_LIMIT = 4 * 1024 * 1024
/** How long a client's rendered frame may wait on the viewers: under the 25 s the desktop gives the
* request, so it hears why rather than timing out. Starting a headless browser takes a few seconds. */
export const SURFACE_WAIT_MS = 20_000
const CLOSED: ViewersChannel = { call: async () => VIEWERS_UNAVAILABLE, buffered: () => 0 }
/** The viewers' process on demand: how the link asks for it, and how long a stream waits for it to connect. */
export interface ViewersDemand {
/** Ask for the process (core/viewersWake.ts `ask`); `why` is what the log says. */
wake(why: string): void
/** How long a stream's frames are held for a process that has not connected yet (`ON_DEMAND_START_MS`). */
startWaitMs?: number
setTimer?: (run: () => void, ms: number) => unknown
clearTimer?: (timer: unknown) => void
}
/** A client's stream frame held until the process connects. */
interface Held {
connId: string
type: string
frame: Record<string, unknown>
bytes: number
}
/** What the viewers last said of one agent. */
interface Known {
context: AgentDshContext | null
forwardingUrl: string | null
}
export function createViewersLink(core: Pick<CoreApi, 'agents' | 'clients'>, notify: NotifyViewers, channel: ViewersChannel = CLOSED, demand?: ViewersDemand) {
const attached = new Set<string>()
const known = new Map<string, Known>()
const setTimer = demand?.setTimer ?? ((run, ms) => setTimeout(run, ms))
const clearTimer = demand?.clearTimer ?? ((timer) => clearTimeout(timer as ReturnType<typeof setTimeout>))
/** Connected to this core at least once, or run by the master from the start (no `demand`): a stream is told or
* refused at once from then on. */
let seen = !demand
/** Asked for by a stream and not connected within a start's wait: its streams are refused at once, as a request
* to a service on demand that did not start is (core/serviceLinks.ts `unstarted`), until it connects. */
let unstarted = false
let held: Held[] = []
let heldBytes = 0
let startTimer: unknown = null
const tell = (connId: string, type: string, frame: Record<string, unknown>): boolean =>
channel.buffered() <= VIEWERS_BUFFER_LIMIT && notify({ type: 'service_event', payload: { kind: 'stream', connId, type, frame } })
/** A stream's frame nobody will take ends that stream on the client's side; a close needs no answer. */
const refuse = (connId: string, type: string, frame: Record<string, unknown>): void => {
if (type !== 'viewer_close' && viewerStreamId(frame.streamId)) core.clients.viewerFrame(connId, 'viewer_close', { streamId: frame.streamId, error: NOT_SERVED })
}
const release = (): Held[] => {
const frames = held
held = []
heldBytes = 0
if (startTimer !== null) clearTimer(startTimer)
startTimer = null
return frames
}
/** Held for a process not yet connected, within the bound a hung process's socket gets: past it, refused. */
const hold = (connId: string, type: string, frame: Record<string, unknown>): boolean => {
const bytes = JSON.stringify(frame).length
if (heldBytes + bytes > VIEWERS_BUFFER_LIMIT) return false
held.push({ connId, type, frame, bytes })
heldBytes += bytes
if (startTimer === null) {
demand!.wake('a viewer stream')
startTimer = setTimer(() => {
startTimer = null
unstarted = true
for (const each of release()) refuse(each.connId, each.type, each.frame)
}, demand!.startWaitMs ?? ON_DEMAND_START_MS)
}
return true
}
const port: ViewersPort = {
attach: (session) => {
if (!session.dsh) return
attached.add(session.agentId)
demand?.wake('a harness here')
notify({ type: 'service_event', payload: { kind: 'attach', session } })
},
detach: (agentId) => {
attached.delete(agentId)
known.delete(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 () => {},
stream: (connId, type, frame) => seen || unstarted ? tell(connId, type, frame) : hold(connId, type, frame),
surface: (connId, payload) => channel.call('surface', { ...payload, connId }, SURFACE_WAIT_MS),
closed: (connId) => {
// What it held for the connection goes with it: nobody is left to read the answer.
held = held.filter((each) => connId !== undefined && each.connId !== connId)
heldBytes = held.reduce((sum, each) => sum + each.bytes, 0)
notify({ type: 'service_event', payload: { kind: 'closed', ...(connId === undefined ? {} : { connId }) } })
},
}
/** What the process tells the core without asking: a stream's frame for one client's connection. */
const notice = (payload: Record<string, unknown>): void => {
if (payload.kind !== 'viewer' || typeof payload.connId !== 'string' || typeof payload.type !== 'string') return
const frame = payload.payload && typeof payload.payload === 'object' ? payload.payload as Record<string, unknown> : {}
if (core.clients.viewerFrame(payload.connId, payload.type, frame)) return
// Not delivered: the stream ends in the process too, without another word to a client it cannot reach.
if (payload.type !== 'viewer_close' && viewerStreamId(frame.streamId)) {
port.stream(payload.connId, 'viewer_close', { streamId: frame.streamId, error: 'Viewer connection closed' })
}
}
/** 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)
// 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,
notice,
/** The process connected: the streams held for it go to it, in the order they came. */
connected(): void {
seen = true
unstarted = false
for (const each of release()) if (!tell(each.connId, each.type, each.frame)) refuse(each.connId, each.type, each.frame)
},
/** 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>