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
/**
* What an experiment in its own process may ask of the core (`service_query`, core/serviceLinks.ts), beside
* the agents (core/agentQueries.ts) and its delivered turns (core/deliveries.ts): the generic hooks an
* experiment acts on the core through, so that none of its own code runs in the core's process
* (docs/design/2026-10-06-core-boundary-next.md, step 8).
* - `shown`: the live agents as the apps are shown them: each with its name, whether its terminal is there,
* and what its frame says about its harness (its viewer);
* - `create`: create an agent, as the window's `agent_create` does;
* - `creation_status`: read the exact native receipt without exposing its launch request;
* - `keep_lead_alive`, `close_member`: for the Super Tab service alone, reopen a stopped Swarm Lead and close a member
* whose session its backend ended, each only as core/api.ts allows;
* - `stop_turn`: stop an agent's turn;
* - `windows`: a change notice for every window on this computer (`orchestrator_changed`);
* - `daemon`: how an agent's shell reaches this daemon, for the prompts the experiment writes;
* - `backend`: a read or write of the account's backend under `/api/`, signed in by the core, which holds the
* sign-in (Share's links);
* - `observer_key`: this machine's public key, or its signature on a welcome to one observer of one share, by
* the gateway, which holds the identity (Share's owner);
* - `observer_send`: a frame Share sealed for one of its observers, to the relay through the gateway;
* - `account`: the account signed in here, its id and email, as the core reads it (`core.account.identity`), for Share
* alone: the observers a shared tab wants are derived for this account's harnesses;
* - `cloud_publish`, `cloud_ask`, `cloud_unask`: the cloud agents' harnesses and their questions
* (`core.cloud`, core/agents/cloud.ts), for the cloud service alone;
* - `super_tab_attention`: the Super Tab members here waiting on a person (`core.superTabs`,
* superTabs/inCore/attention.ts), for the Super Tab service alone;
* - `super_tab_cards`, `super_tab_card_recap`: the Swarms' cards and a Lead's last message for the Harness Pro
* (`core.superTabs`, superTabs/inCore/cards.ts), for the Super Tab service alone;
* - `super_tab_observers`: members may watch an agent here, so Share must run (`core.superTabs`), for the Super Tab
* service alone;
* - `super_tab_screen`, `super_tab_input`, `super_tab_input_if_screen`: a member's terminal read as plain text and typed into for its Lead,
* and keys typed there only while its screen is still the one the Service read
* (`core.superTabs`, superTabs/inCore/terminal.ts), for the Super Tab service alone.
* The core answers them only for the experiments (core/api.ts `EXPERIMENTS`): creating an agent or
* telling the windows something is no other process's to ask. The process's side is
* services/processCoreApi.ts. Agent Messages, an experiment until 2026-10-12, asks a few of the same and is
* answered by its own link, for what it uses alone (core/messagesLink.ts).
*/
import type { BackendSocket } from '../backendSocket.js'
import type { AgentCreateRequest, CoreApi } from './api.js'
import { creationObservation } from '../lib/creationObservation.js'
import { nativeTurnCursorIn } from '../lib/nativeTurnObservations.js'
type Payload = Record<string, unknown>
type Core = Pick<CoreApi, 'agents' | 'turns' | 'clients' | 'daemon' | 'account' | 'cloud' | 'superTabs' | 'transcripts'>
const QUERIES: ReadonlySet<string> = new Set(['shown', 'activity', 'close_swarm', 'keep_lead_alive', 'close_member', 'stopped', 'gone', 'creation_status', 'native_turns', 'create', 'stop_turn', 'windows', 'daemon', 'backend', 'observer_key', 'observer_send', 'account', 'cloud_publish', 'cloud_ask', 'cloud_unask', 'super_tab_attention', 'super_tab_cards', 'super_tab_card_recap', 'super_tab_observers', 'super_tab_screen', 'super_tab_input', 'super_tab_input_if_screen'])
const METHODS: ReadonlySet<string> = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
const text = (value: unknown): string => (typeof value === 'string' ? value : '')
/** The live agents as the apps are shown them (`shown`): each with its name, whether its terminal is there and
* what its frame says about its harness. */
export function shownAgents(core: Pick<CoreApi, 'agents'>): Payload {
return {
agents: core.agents.live().map((session) => ({
...session,
displayName: core.agents.displayName(session),
terminalAvailable: core.agents.terminalAvailable(session.agentId),
selectedModel: core.agents.runtimeProfile(session),
dshContext: core.agents.dsh(session),
})),
}
}
/** How an agent's shell reaches this daemon (`daemon`). */
export function daemonAddress(core: Pick<CoreApi, 'daemon'>): Payload {
return { command: core.daemon.command, port: core.daemon.port, machineId: core.daemon.machineId(), autonomousEnv: core.daemon.autonomousEnv }
}
/** What the add-ons of a device that is this machine ask in their own process (services/machineAddonsProcess.ts):
* this daemon's address, for the account's machine id. Answered before the experiments' check, which would refuse
* it as NOT_AN_EXPERIMENT; any other query of theirs is not answered here. */
export function answerMachineAddonsQuery(core: Pick<CoreApi, 'daemon'>, service: string, query: string): Payload | null {
return service === 'machineAddons' && query === 'daemon' ? daemonAddress(core) : null
}
/** The answer to an experiment's query, or null when it is not one of these. */
export async function answerExperimentQuery(core: Core, experiments: ReadonlySet<string>, service: string, query: string, payload: Payload): Promise<Payload | null> {
if (!QUERIES.has(query)) return null
// `account` is also what models asks for the account's grid name, of its own link (core/modelsLink.ts): only
// Share's and the Swarm's are answered here. Seen 2026-10-18: since #1376 models got NOT_AN_EXPERIMENT back instead, so
// the backend's grid name never reached it, and the picker said "Sign in to find models" to a signed-in person. The
// Swarm's round dial cards need the reader to find their own Buddy: answered nothing, the dial said "No Buddy here
// yet" to a person with one (Diego's dial, 2026-10-29).
if (query === 'account' && service !== 'sharing' && service !== 'superTabs') return null
if (!experiments.has(service)) return { error: 'NOT_AN_EXPERIMENT' }
switch (query) {
case 'shown':
return shownAgents(core)
case 'close_swarm': {
if (service !== 'superTabs') return { error: 'NOT_SUPER_TABS' }
const { agentId, creationId, sessionId, createdAt, expiresAt } = payload
if (!/^[A-Za-z0-9_-]{1,160}$/.test(text(agentId)) ||
creationId !== undefined && (typeof creationId !== 'string' || !/^[A-Za-z0-9_-]{16,96}$/.test(creationId)) ||
sessionId !== undefined && typeof sessionId !== 'string' ||
createdAt !== undefined && (typeof createdAt !== 'string' || !Number.isFinite(Date.parse(createdAt))) ||
expiresAt !== undefined && (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt))) return { error: 'INVALID_REQUEST' }
return { ...await (core.agents.closeSwarm?.({ agentId: agentId as string,
...(typeof creationId === 'string' ? { creationId } : {}), ...(typeof sessionId === 'string' ? { sessionId } : {}),
...(typeof createdAt === 'string' ? { createdAt } : {}), ...(typeof expiresAt === 'number' ? { expiresAt } : {}) }) ?? { error: 'UNSUPPORTED' }) }
}
// The Super Tab host keeps its Leads alive and closes the sessions its backend ends; the core decides which (core/api.ts).
case 'keep_lead_alive':
case 'close_member': {
if (service !== 'superTabs') return { error: 'NOT_SUPER_TABS' }
const { agentId, creationId } = payload
if (typeof agentId !== 'string' || !/^[A-Za-z0-9_-]{1,160}$/.test(agentId)
|| creationId !== undefined && (typeof creationId !== 'string' || !/^[A-Za-z0-9_-]{16,96}$/.test(creationId))) return { error: 'INVALID_REQUEST' }
return query === 'keep_lead_alive'
? { ...await (core.agents.keepLeadAlive?.(agentId) ?? { ok: false, error: 'UNSUPPORTED' }) }
: { ...await (core.agents.closeMember?.(agentId, creationId as string | undefined) ?? { error: 'UNSUPPORTED' }) }
}
// Whether its agents are in a turn: a Buddy session's idle end asks before ending one (superTabs/host.ts).
case 'activity': {
if (service !== 'superTabs') return { error: 'NOT_SUPER_TABS' }
const ids = Array.isArray(payload.agentIds) ? payload.agentIds.filter((id): id is string => typeof id === 'string').slice(0, 64) : []
return { activity: await core.agents.activity(ids) }
}
case 'stopped':
return { stopped: !!text(payload.agentId) && await core.agents.stopped?.(text(payload.agentId)) === true }
case 'gone':
return { gone: !!text(payload.agentId) && await core.agents.gone?.(text(payload.agentId)) === true }
case 'creation_status':
return { observation: await core.agents.creationStatus?.(text(payload.creationId)) ?? null }
case 'native_turns': {
const cursor = payload.cursor === undefined ? undefined : nativeTurnCursorIn(payload.cursor)
if (!/^[A-Za-z0-9_-]{1,160}$/.test(text(payload.agentId)) || cursor === null) return { error: 'INVALID_REQUEST' }
return { page: await core.transcripts.nativeTurns?.(text(payload.agentId), cursor) ?? null }
}
case 'create': {
if (!text(payload.engine) || !text(payload.cwd) || typeof payload.prompt !== 'string' || typeof payload.name !== 'string') return { ok: false, error: 'INVALID_REQUEST' }
const request: AgentCreateRequest = {
engine: payload.engine as AgentCreateRequest['engine'],
cwd: text(payload.cwd),
dsh: text(payload.dsh) || null,
prompt: payload.prompt,
name: payload.name,
bypassPermission: payload.bypassPermission === true,
}
return { ...await core.agents.create(request) }
}
case 'stop_turn':
if (text(payload.agentId)) core.turns.stop(text(payload.agentId))
return {}
case 'windows': {
const frame = payload.frame as Payload | undefined
// A change notice and nothing else: what the windows hear from the core itself is the core's to say.
if (!frame || !/^[a-z]+_changed$/.test(text(frame.type)) || !frame.payload || typeof frame.payload !== 'object') return { error: 'INVALID_FRAME' }
core.clients.windows({ type: text(frame.type), payload: frame.payload as Payload })
return {}
}
case 'backend': {
const method = text(payload.method), path = text(payload.path)
if (!METHODS.has(method) || !path.startsWith('/api/')) return { error: 'INVALID_REQUEST' }
return { ...await core.account.backend(method, path, payload.body) }
}
case 'observer_key':
try {
if (payload.op === 'public') return { key: await core.account.observerKey.publicKey() }
return { key: await core.account.observerKey.signWelcome(text(payload.machineId), text(payload.shareId), text(payload.peer), text(payload.ephemeral)) }
} catch (error) {
return { error: error instanceof Error ? error.message : String(error) }
}
case 'cloud_publish':
case 'cloud_ask':
case 'cloud_unask': {
if (service !== 'cloud' || !core.cloud) return { error: 'NOT_CLOUD' }
if (query === 'cloud_publish') core.cloud.publish(Array.isArray(payload.harnesses) ? payload.harnesses : [])
else if (query === 'cloud_ask') core.cloud.ask(text(payload.agentId), text(payload.questionId), (payload.question ?? {}) as { text: string; choices: string[] })
else core.cloud.unask(text(payload.agentId), text(payload.questionId))
return {}
}
case 'super_tab_attention': {
// The core checks each item (superTabs/inCore/attention.ts): what reaches the devices is decided there, not here.
if (service !== 'superTabs' || !core.superTabs) return { error: 'NOT_SUPER_TABS' }
core.superTabs.attention(Array.isArray(payload.items) ? payload.items : [])
return {}
}
case 'super_tab_cards':
case 'super_tab_card_recap': {
// Checked by the core (superTabs/inCore/cards.ts), which drops what is not sound; here only the list's shape.
if (service !== 'superTabs' || !core.superTabs) return { error: 'NOT_SUPER_TABS' }
if (query === 'super_tab_cards') core.superTabs.cards(Array.isArray(payload.items) ? payload.items : [])
else core.superTabs.cardRecap(payload.recap as never)
return {}
}
case 'super_tab_observers':
if (service !== 'superTabs' || !core.superTabs) return { error: 'NOT_SUPER_TABS' }
core.superTabs.shareObservers()
return {}
case 'super_tab_screen':
case 'super_tab_input':
case 'super_tab_input_if_screen': {
if (service !== 'superTabs' || !core.superTabs) return { error: 'NOT_SUPER_TABS' }
const { agentId, scrollback = 0, text: typed = '', keys = [], screen } = payload
if (!/^[A-Za-z0-9_-]{1,160}$/.test(text(agentId)) || typeof scrollback !== 'number' || typeof typed !== 'string'
|| !Array.isArray(keys) || !keys.every(key => typeof key === 'string')
|| (query === 'super_tab_input_if_screen' && (typeof screen !== 'string' || !keys.length))) return { ok: false, error: 'INVALID_REQUEST' }
return { ...query === 'super_tab_screen' ? await core.superTabs.screen(agentId as string, scrollback)
: query === 'super_tab_input_if_screen' ? await core.superTabs.inputIfScreen(agentId as string, keys as string[], screen as string)
: await core.superTabs.input(agentId as string, typed, keys as string[]) }
}
case 'account': {
const known = await core.account.identity()
return known ? { ...known } : { error: 'ACCOUNT_UNAVAILABLE' }
}
case 'observer_send': {
const connId = text(payload.connId), type = text(payload.type)
if (!connId.startsWith('observer:') || !type.startsWith('observer_') || !payload.payload || typeof payload.payload !== 'object') return { error: 'INVALID_FRAME' }
return { sent: core.clients.observer(connId, type, payload.payload as Payload) }
}
default:
return daemonAddress(core)
}
}
/**
* `core.agents.create`: the window's `agent_create` (the socket's `onCreateAgent`) with no grid, Codex profile,
* named agent or permission mode of the agent's own, as the socket created the orchestrator's agents for it.
*/
export async function createForExperiment(create: BackendSocket['onCreateAgent'], request: AgentCreateRequest): ReturnType<CoreApi['agents']['create']> {
if (!create) return { ok: false, error: 'UNSUPPORTED', detail: 'This daemon cannot create agents.' }
const result = await create({ ...request, grid: null, codexHome: null, agent: null, permissionMode: null })
return result.ok ? { ok: true, agentId: result.session.agentId } : { ok: false, error: result.error, ...(result.detail ? { detail: result.detail } : {}) }
}
/** Read the window's receipt through its existing provider; never infer a
* cancelled launch from a missing callback, an old core or a failed read. */
export async function creationForExperiment(read: BackendSocket['createStatusProvider'], creationId: string) {
if (!read || !/^[A-Za-z0-9_-]{16,96}$/.test(creationId)) return null
let reply: Record<string, unknown> | null = null
try { await read({ creationId }, { local: true }, value => { reply = value }) } catch { return null }
const frame = reply as Record<string, unknown> | null
const agent = frame?.agent as { id?: unknown } | undefined
// A closed terminal is unavailable to a window, but its durable creation
// receipt still identifies what launched. A service can check its stop.
return creationObservation(creationId, frame?.state === 'unavailable'
? { ...frame, state: 'created', agentId: frame.createdAgentId }
: { ...frame, agentId: agent?.id })
}