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
import type { MessageHold } from '../engines/facets/screen.js'
import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'
import type { ProductUsageMetric } from '../lib/productUsageContract.js'
import type { PreparedHandoff, HandoffPermit, HandoffOutcome } from '../lib/handoffAuthority.js'
import type { AgentTokenUsage, AgentUsageTarget } from '../lib/agentUsageWire.js'
import type { CloudHarness } from '../lib/cloudAgents.js'
import type { SharedTrustPeer } from '../lib/sharedMachinesPort.js'
import type { GridAssignmentProcess, GridAssignmentAnswer } from '../lib/gridAssignmentWire.js'
/**
* The boundary the services stand on (docs/design/2026-10-03-harnessd.md, "The core boundary"):
* `CoreApi` is what a service may ask of the core, and `CorePorts` is what the core asks of services.
*
* Both are in process today. When a service moves into a process of its own, its `CoreApi` calls
* become requests on the local socket and its port becomes a proxy that sends them; the service's
* code stays as it is. Members are added as services move behind it, each a call that exists today,
* never a generic `call(name, args)`.
*
* The apps reach a service through the requests it answers (`ServiceRequests`), which its start
* returns. The core routes them to it; a port is only for what the core itself must ask.
*/
import type { RecentTurn } from '../cable/cableHost.js'
import type { NativeTurnRead } from '../lib/nativeTurnObservations.js'
import type { ReviewedAnswer } from '../cable/questionInbox.js'
import type { AgentEngine } from '../engines/types.js'
import type { AppSwarms } from '../cable/cableSession.js'
import type { UnreadNotification } from '../lib/notificationRead.js'
import type { AutonomousDeviceAgent, AutonomousDeviceDelivery, AutonomousDeviceReceipt } from '../lib/autonomous-device/service.js'
import type { StoreAgent } from '../lib/autonomous-device/store.js'
import type { DshLaunchAnswer, DshLaunchRequest, DshMaterializeAnswer, DshMaterializeRequest } from '../dsh/launchWire.js'
import type { AgentDshContext } from '../lib/agentFrame.js'
import type { GridAccess } from '../lib/gridAttach.js'
import type { createHarnessResourcesReader } from '../lib/harnessResources.js'
import type { createHarnessStorageReader } from '../lib/harnessTelemetry.js'
import type { AgentGridTarget, GridAnnotation } from '../lib/gridAnnotation.js'
import { GRID_FLEET_MAX_TIMEOUT_MS } from '../lib/gridFleetProtocol.js'
import type { GridLaunchAnswer, GridLaunchOverride, GridLaunchRequest } from '../lib/gridLaunchWire.js'
import type { NewAgentModel } from '../lib/newAgentModel.js'
import type { LastTurnText, LiveEvent } from '../engines/kit/events.js'
import type { CreationObservation } from '../lib/creationObservation.js'
import type { SessionRecaps } from '../lib/recapReads.js'
import type { SessionInputDelivery } from '../lib/sessionInput.js'
import type { AgentCloseRequest, AgentCloseResult } from '../lib/closeAgentService.js'
import { projectDisplayName, type registry, type RegisteredSession } from '../lib/registry.js'
import type { RuntimeModelOption } from '../lib/runtimeProfile.js'
import { externalUnavailable, type ExternalSessionAnswer, type ExternalSessionRequest } from '../lib/externalSessionWire.js'
import type { SessionSearchIndex } from '../lib/sessionSearch/indexer.js'
import type { StoppedAgentStore } from '../lib/stoppedAgents.js'
import type { TerminalBinaryClear } from '../lib/terminalBinary.js'
import { VIEWER_UP_TYPES } from '../lib/viewerFrames.js'
import type { RouteAnswer } from '../localWsServer.js'
import type { DeviceInputStatus } from './deviceInput.js'
import { FAIL, later, readFallback, ServiceUnavailableError, type PortFallbacks } from './serviceHost.js'
export type { RouteAnswer }
/** What a service guards its own parts with, as the core guards a service (core/serviceHost.ts): the
* devices keep a dial failing from costing ⌘K its routing (services/devices.ts). */
export { FAIL, later, readFallback, ServiceUnavailableError, type PortFallbacks }
/** A service may open a terminal with a literal argv, never shell source. */
export interface TerminalOpen {
argv: string[]
cwd: string
}
export type TerminalOpenResult = { ok: true; agentId: string } | { ok: false; error: string; detail?: string }
/** What a viewer is shown of a terminal it watches: a frame, or a terminal's bytes (base64 of the local binary
* frame, lib/terminalBinary.ts). */
export type TerminalWatchOutput = { type: string; payload: Record<string, unknown> } | { binary: string }
/**
* A read-only view of agents' terminals for a feature's own viewers (Share's observers, core/terminalWatch.ts):
* each viewer's terminal frames in (`terminal_open`, `terminal_ack`, …), what it is shown out. Nothing a
* viewer sends ever reaches a pane.
*/
export interface TerminalWatch {
frame(viewer: string, type: string, payload: Record<string, unknown>): Promise<void>
close(viewer: string): Promise<void>
onOutput(listener: (viewer: string, output: TerminalWatchOutput) => void): () => void
}
export interface TerminalsPort {
open(request: TerminalOpen): Promise<TerminalOpenResult>
/** Fresh registry facts for a shell launch receipt, never a service's cached agent snapshot. */
describe(agentId: string): Promise<Record<string, unknown> | null>
/** The exact launched engine has exited, with no newer binding replacing the evidence. */
visitStatus(agentId: string): Promise<{ exited: boolean }>
watch: TerminalWatch
}
/** A service without the core's launch call must refuse, never launch outside the core; it watches nothing. */
export const TERMINALS_OFF: TerminalsPort = {
open: async () => ({ ok: false, error: 'SERVICE_UNAVAILABLE' }),
describe: async () => null,
visitStatus: async () => ({ exited: false }),
watch: { frame: async () => {}, close: async () => {}, onOutput: () => () => {} },
}
/** Read-only conversation facts for the handoff in the edge host. Each lookup asks the core now;
* a stopped record is never replaced by a stale live-agent list in another process. */
export interface ConversationReads {
publish(prepared: PreparedHandoff, permit: HandoffPermit): Promise<HandoffOutcome>
/** A live agent by agent/session id, otherwise the stopped record by agent id. */
resolve(id: string): Promise<RegisteredSession | null>
recentAsks(sessionId: string, n: number): Promise<string[]>
lastFullText(sessionId: string): Promise<string | null>
recaps(sessionId: string, n: number): Promise<string[]>
/** The core verifies process birth, ownership and deletion; discovery never binds the agent. */
discover(agentId: string): Promise<{ engine: AgentEngine; sessionId: string; transcriptPath: string | null } | null>
findTranscript(engine: AgentEngine, sessionId: string, options: { codexHome?: string }): Promise<string | null>
transcriptOk(engine: AgentEngine, path: string, codexHome: string | null): Promise<boolean>
}
/** No retained record or history, no discovered session and no permission to read a guessed path. */
export const CONVERSATIONS_OFF: ConversationReads = {
publish: async () => { throw new Error('handoff publication is unavailable') },
resolve: async () => null,
recentAsks: async () => [],
lastFullText: async () => null,
recaps: async () => [],
discover: async () => null,
findTranscript: async () => null,
transcriptOk: async () => false,
}
export interface UsagePort {
read(target: AgentUsageTarget): Promise<Record<string, unknown>>
stop(): void
}
export const USAGE_FALLBACKS: PortFallbacks<UsagePort> = { read: later(FAIL), stop: undefined }
export interface CoreApi {
/** Last aggregate observation, never a transcript read. Optional for services that do not ask. */
usage?: (target: AgentUsageTarget) => Promise<AgentTokenUsage | null>
/** An agent's token totals read from its transcript now, not the cached snapshot (the devices' turn tokens);
* null for an agent that is not here or whose engine has no usage. */
usageFresh?: (agentId: string) => Promise<AgentTokenUsage | null>
/** The daemon's data folder; a service keeps its own files in it. */
dataDir: string
terminals: TerminalsPort
/** This computer, as the dial's wheel and the fleet name it. */
machine: {
/** The account's id for this machine, or '' until the daemon has one (signed out). */
id(): string
/** This computer's own durable id. */
computerId(): string
/** Its display name, else "This machine". */
name(): string
}
conversations: ConversationReads
agents: {
/** Every agent on this machine: the live ones, then the stopped ones. */
all(): RegisteredSession[]
/** The live agents. */
live(): RegisteredSession[]
/** The name the apps show for an agent. */
displayName(session: RegisteredSession): string
/** A live agent, by its agent id. */
byAgent(agentId: string): RegisteredSession | undefined
/** A live agent, by its agent id or its engine session id: whichever the apps asked by. */
resolve(id: string): RegisteredSession | undefined
/** The live agents the apps are shown. */
advertised(): RegisteredSession[]
/** The running cloud harnesses (core/agents/cloud.ts) as rows an agent list reads: an id, a start, an
* engine and a name, with no pane, transcript or process. Only the lists that show them ask (the dial,
* the fleet); absent where a core or process offers none. */
cloud?(): RegisteredSession[]
/** Whether the agent's terminal is attached: a frame without one reads to the apps as "agent gone". */
terminalAvailable(agentId: string): boolean
/** Fresh native lifecycle evidence. Absence from a live snapshot alone is
* not a stop: a saved stopped record must also exist in the core. */
stopped?(agentId: string): Promise<boolean>
/** The agent is neither live nor kept as a stopped record: closed by hand, or its record deleted. Only for an agent
* the caller already knows was created; it does not prove an agent that is still starting is gone. */
gone?(agentId: string): Promise<boolean>
/** The exact durable native creation receipt. Null means unavailable, never
* proof that a launch was missing, cancelled or failed. */
creationStatus?(creationId: string): Promise<CreationObservation | null>
/** Send the agent's frame to the apps again. */
sync(session: RegisteredSession): void
/** The Model/Effort choices an agent's engine offers (opaque `runtime-v1` ids): one agent's, or
* every live agent's when none is named. */
runtimeModels(agentId?: string): Promise<RuntimeModelOption[]>
/** The opaque runtime-v1 profile an agent runs with: its model and effort, for a picker's chips. */
runtimeProfile(session: RegisteredSession): string | null
/** Switch a live agent's model and effort; nothing without a model. */
setRuntime(agentId: string, model?: string, effort?: string): void
/** Fork a live agent, as the window's `agent_fork` does: the new agent's id, or the refusal. */
fork(agentId: string): Promise<{ ok: true; agentId: string } | { ok: false; error: string; detail?: string }>
/** Create an agent, as the window's `agent_create` does with no grid, profile or model of its own: the
* new agent's id, or the refusal. */
create(request: AgentCreateRequest): Promise<{ ok: true; agentId: string } | { ok: false; error: string; detail?: string }>
/** What a live agent's frame says about its harness: its name, its viewer and its verdict; null for none. */
dsh(session: RegisteredSession): AgentDshContext | null
/** What a live Claude Code or Codex agent's pane footer says it is doing ("Reading 3 files"), or null:
* the dial's working card. The pane is read by the core; only the line leaves it. */
activityText(agentId: string): Promise<string | null>
/** `activityText` with the footer's timer, for a Harness Pro. Absent in a
* core that cannot read them; the dial then gets the footer alone. */
activitySnapshot?(agentId: string): Promise<{ text: string; elapsedSeconds?: number } | null>
/** Whether each of these agents is working now, as this computer's windows are told (core/turns/activity.ts):
* Agent Messages tells a shared tab's other accounts. An agent that is not live is left out. */
activity(agentIds: string[]): Promise<Record<string, 'working' | 'idle' | 'unknown'>>
/** What each of these agents is doing, in one line of at most 120 characters (core/turns/summaries.ts): the prompt
* it is running, or its latest recap line. An agent not live, or with nothing known, is left out. */
summaries(agentIds: string[]): Promise<Record<string, string>>
/** Close a harness another agent started (`startedBy: agent`) as `agent_close` closes one: its screen saved, its
* process stopped, its conversation kept. `idle` refuses one that works, waits for the person or holds a draft
* (`SESSION_NOT_IDLE`); `now` does not. Any other harness is refused (`NOT_AGENT_STARTED`): the agent cleanup
* (services/agentCleanup.ts) closes those, and nothing else. Absent where the core does not let a service close. */
closeStarted?(agentId: string, mode: 'idle' | 'now'): Promise<AgentCloseResult>
/** Close only the recorded native identity started for a Swarm. Missing live sessions are already gone. */
closeSwarm?(request: { agentId: string; creationId?: string; sessionId?: string; createdAt?: string; expiresAt?: number }): Promise<AgentCloseResult>
/** Reopen a Swarm Lead whose session is gone, on its own conversation, as a resume does: nothing is typed into it
* (superTabs/host.ts keeps Leads alive). Only an agent stopped here that this machine's Super Tab host keeps as the
* Lead of an active project (superTabs/retention.ts); a live one is answered ok. */
keepLeadAlive?(agentId: string): Promise<{ ok: true } | { ok: false; error: string; detail?: string }>
/** Close, now and keeping its conversation, a Super Tab member whose session the backend ends (its project deleted,
* the agent removed). Only a harness this machine's Super Tab host retains as a member, or one whose exact native
* creation receipt [creationId] (the Swarm's start) names it; a gone one is closed. */
closeMember?(agentId: string, creationId?: string): Promise<AgentCloseResult>
/** When a live agent's conversation last moved, epoch ms: the latest dated work in its transcript
* (lib/transcriptActivity.ts), what the apps' `updatedAt` is when there is one. Null for none live, and for an
* engine that keeps no dated transcript: a hook's time or the bind's is not when it last answered. Absent where
* the core is not asked it. */
lastActivity?(agentId: string): Promise<number | null>
}
/** A device's or another machine's turns for an agent on this one: the doors the web and the hooks use. */
turns: {
/** Deliver text into a live agent. */
send(agentId: string, text: string): void
/** Stop a live agent's turn. */
stop(agentId: string): void
/** A live agent's last `n` completed turns, newest first. A promise, so that the devices in their own
* process ask it of the core when they need it. */
recent(agentId: string, n: number): Promise<RecentTurn[]>
/** The person's own last questions to a live agent, newest first. */
asks(agentId: string): Promise<string[]>
/** Deliver text into a live agent under a delivery id of the caller's own, as the Wi-Fi device, Agent
* Messages and the orchestrator deliver their turns: one path for the three. What becomes of it is heard through
* `onDelivery`, under the same id. */
deliver(agentId: string, text: string, deliveryId: string, options?: DeliveryOptions): void
/** Take back a delivery not yet being written: true when it was, and it never will be; false for one
* the agent's pane is already taking. Answered at once, as the orchestrator reads it in
* line: in a service's own process the core is asked and the answer cannot wait, so it is false there,
* and a delivery the core did take back is then heard `rejected` (`cancelled`). */
cancelDelivery(deliveryId: string): boolean
/** Hear what becomes of each delivery: queued, written, its turn started, refused and why, or past
* knowing. Returns how to stop hearing. */
onDelivery(listener: (event: TurnDelivery) => void): () => void
/** Replace a service's short-lived permission to write queued typed deliveries.
* IDs use `team:service:<service>:`; expired or absent permission means wait.
* This guards the final terminal write even when its authorizing service stops. */
leaseDeliveries(service: string, leases: Record<string, number>): Promise<boolean>
}
questions: {
/** Answer a live agent's question, keyed by the question keys it asked with. */
answer(agentId: string, requestId: string, answers: Record<string, string>): void
/** Answer it with the selections a device reviewed; resolves whether the terminal confirmed it. */
answerReviewed(answer: ReviewedAnswer): Promise<boolean>
}
transcripts: {
/** How to read a conversation its engine keeps in a database instead of a transcript file;
* undefined for every other engine. */
databaseHistory(session: RegisteredSession): (() => Promise<readonly LiveEvent[]>) | undefined
/** A session's last turn as its engine recorded it: what was asked and the final answer; null when
* there is none yet. Read from the end of its transcript, bounded (core/transcripts/lastTurn.ts). */
lastTurn(sessionId: string): Promise<LastTurnText | null>
/** Bounded live prompt/answer observations, starting at a requested cursor.
* An omitted cursor establishes the current boundary, without past history. */
nativeTurns?: NativeTurnRead
}
/** The sign-in the core holds for every service: a service never holds a credential itself. */
account: {
/** The account's private grid name, minted and remembered by the backend; null when an older
* backend issues none. Bounded in time. */
mintGridName(): Promise<string | null>
/** This machine's harness access token, for handing a sign-in to grid, dialling the fleet's lane or a
* dial's spoken words to the transcriber. Rejects when signed out. `force` refreshes it (once, after a
* 401 for `failedToken`): the core's one session manager shares a refresh in flight with the backend link. */
accessToken(options?: { force?: boolean; failedToken?: string }): Promise<string>
/** The fleet's lane to the owner's other machines, sealed by the gateway with this machine's E2EE
* identity, which no service holds (`LaneSeal`). */
lane: LaneSeal
/** This machine's E2EE identity as Share's owner signs with it, held by the gateway (`ObserverKey`). */
observerKey: ObserverKey
/** Shared tabs' keys: rosters and key changes signed with this machine's identity, and the sessions to the
* tabs' other machines, held by the gateway (`TabKey`). */
tabKey: TabKey
/** Shared tabs' relay: a socket per shared tab, held by the gateway (`TabRelay`); what it hears is
* `GatewayEvents.tabFrame`, which the core hands to Agent Messages. */
tabRelay: TabRelay
/** The account's connected services, sealed and opened by the gateway for its machines (`ConnectorVault`). */
connectorVault: ConnectorVault
/** Whether this computer holds an account: a sign-in or sign-out restarts the daemon. */
signedIn(): boolean
/** The account's environment (`prod`, …), which the backend checks every request against. */
environment(): string
/** The owner's machines, read from the backend now (`GET /api/machines`, or this computer alone signed
* out), and kept as the core's own list for the windows and the trust group. Never rejects. */
machines(): Promise<{ status: number; body: Record<string, unknown> }>
/** The account's private grid as the backend named it (`machine_meta`), or as grid's set-up just
* confirmed it; null before either. Working it out when neither has said is the models service's
* (`lib/gridDerive.ts`). */
privateGridName(): Promise<string | null>
/** This machine's name as the account's Machines list shows it (the backend's `machine_meta`); null
* until the first one lands. */
machineName(): string | null
/** A read or write of the account's backend, signed in by the core (`proxyBackend`): an experiment's
* account-wide settings, and Agent Messages' tabs. A failure is an answer: 502, 504, 401. */
backend(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }>
/** The account signed in here, its id and email, as the backend says it (`GET /api/auth/me`), read by the core's own
* sign-in; null while it cannot be read, or by a process that cannot ask (`accountIdentity`). */
identity(): Promise<AccountIdentity | null>
/** Hear the account's changes the backend announces (`desk_changed`, …). Returns how to stop hearing. */
onNotice(listener: (notice: BackendNotice) => void): () => void
}
clients: {
/** An agent's viewer moved: the windows' viewer panes forward to the new one. */
viewerChanged(agentId: string): void
/** A frame of a viewer stream for the one connection that opened it (`viewer_response`, `viewer_data`,
* `viewer_ack`, `viewer_end`, `viewer_close`): false when it cannot reach that connection. Only those
* types; the core drops any other. */
viewerFrame(connId: string, type: string, payload: Record<string, unknown>): boolean
/** The account's grid has a name: the models picker answers with it at once. */
gridNamed(name: string): void
/** What the models picker lists may have changed (a local model started or stopped, grid set up):
* the windows on this computer are pushed the list again (`grid_models_changed`). */
gridModelsChanged(): void
/** A harness being installed or updated moved on (`dsh_install_status`): the apps show it in the
* create dialog. */
dshInstallStatus(status: Record<string, unknown>): void
/** A frame for every window on this computer, as an experiment tells them it changed
* (`orchestrator_changed`, `team_changed`); never sent off this computer. */
windows(frame: { type: string; payload: Record<string, unknown> }): void
/** A frame for one of Share's observers, sealed by Share itself, to the relay through the gateway; false
* when it could not be handed over. */
observer(connId: string, type: string, payload: Record<string, unknown>): boolean
/** A frame from the devices for every window on this computer, never the cloud: what a hand at this
* desk did. Only `DEVICE_WINDOW_FRAMES`; the core drops any other. */
sendLocal(frame: DeviceWindowFrame): void
/** A window bridge's ask, to one window on this computer; false when it is gone. Only
* `DEVICE_BRIDGE_FRAMES`. */
sendToWindow(connId: string, frame: DeviceBridgeFrame): boolean
/** Whether a window on this computer is attached. */
hasWindow(): boolean
/** The devices on this computer changed (`harness_devices_changed`): the windows and the owner's apps
* show them. */
devicesChanged(payload: Record<string, unknown>): void
/** A dial on this computer is watching it, or no longer is: the core then makes the turn cards and
* recaps for it, as for a device watching through the backend. */
dialWatching(watching: boolean): void
/** A turn's card for the devices (`commander_event`): its progress, and its recap once it ends. */
turnCard(frame: TurnCardFrame): void
/** A turn's recap for the apps (`turn_summary`, or `turn_summary_pending` while one is being cut). */
turnSummary(frame: TurnSummaryFrame): void
}
/** How an agent's shell reaches this daemon: the command that runs this harness's CLI, the port the daemon
* serves and the machine it serves as. An experiment writes them into the prompts of the agents it runs
* (`… orchestrator --port 18473 --machine …`). */
daemon: DaemonAddress
/** The cloud agents' doors into the core (services/cloud.ts): absent from a core or a process that offers them none. */
cloud?: CloudCore
/** The Super Tab service's door into the core (superTabs/attention.ts): absent from a core or a process that offers it none. */
superTabs?: SuperTabsCore
/** The devices' way to the Super Tab service's `super_tabs` requests, for the Swarm cards alone (`cardsWanted`, `cardRecap`,
* `cardOpen`, `cardSay`, `cardWorker`; superTabs/inCore/cards.ts refuses any other action): its answer, or SERVICE_UNAVAILABLE. Absent from a core or a
* process that offers none. */
superTabRequest?: (payload: Record<string, unknown>) => Promise<Record<string, unknown>>
/** The Wi-Fi device's doors into the core (services/wifi.ts): each one call it made when it ran here. */
wifi: {
/** What it lists and reads in line (`WifiView`), asked again before each request it answers. */
view(): Promise<WifiView>
/** A device's prompt into a live agent, through the pane's write lock, as delivery `deliveryId`. Settles
* once the lock has taken it: what it said of the prompt meanwhile is the reply's to carry. */
submit(agentId: string, text: string, deliveryId: string): Promise<void>
/** A queued delivery the device no longer stands behind (it was unpaired). */
cancel(deliveryId: string): void
/** The agent's transcript shows the device's prompt began its turn: the pane's lock moves on. */
started(agentId: string, text: string): void
/** Stop a live agent's turn; resolves whether it stopped. */
stop(agentId: string): Promise<boolean>
/** Answer a live agent's question, never a permission dialog; resolves whether the terminal took it. */
answer(agentId: string, requestId: string, answers: Record<string, string>): Promise<boolean>
/** Start an agent for an installed Store harness in `cwd`, with the device's fixed, safe launch
* arguments; refused when another agent works there. */
create(packageId: string, engine: string, cwd: string): Promise<ForkResult>
/** Move the window's focus one agent along the desk, the dial's way; 'no_app' without a window. */
stepFocus(direction: 'next' | 'previous', currentAgentId?: string): Promise<{ machineId: string; agentId: string } | 'no_agents' | 'no_app'>
/** A stroke on the device's glass for the window's terminal; false without a window. */
scroll(phase: 'down' | 'move' | 'up', dy: number, velocity: number): boolean
/** Ask the window to select an agent (`device_focus`); false without a window. */
focusApp(agentId: string, expiresAt: number, focusRevision: string): boolean
/** Ask the window to open the agent a Store preparation made (`device_prepare_open`). */
reveal(operationId: string, agentId: string): void
/** An answer or event for one device session, sealed to it by the gateway, if the session is still
* that identity's device. */
send(connId: string, identity: string, type: string, payload: Record<string, unknown>): void
/** Which identity's app said hello on a session (null: it left): the core counts it as watching. */
hello(connId: string, identity: string | null): void
/** A device said hello: what the agents are doing is sent again for it. */
joined(): void
/** It is built and serving: the gateway may connect the devices' direct links, which a service that
* could not be built would leave unanswered. */
ready(): void
/** A device asked to be unpaired, over its session: its pairing goes. */
unpaired(identity: string): void
/** The focus revision, as it changes: a window's stale selection is refused against it. */
focus(revision: string): void
/** It no longer reads this agent's transcript, as of the `seen`th prompt the core told it of. */
transcripts(agentId: string, seen: number): void
/** The agents whose transcripts it reads, said as it starts. */
watching(agentIds: string[]): void
/** The agents a device subscribed to: their tools' events are sent too, not only the answer's text. */
streams(agentIds: string[]): void
}
}
/** An agent to create, as an experiment asks for one (the orchestrator's Director and specialists). */
export interface AgentCreateRequest {
engine: AgentEngine
cwd: string
/** The harness to create it as, installed here; null for the engine alone. */
dsh: string | null
/** The message it opens with, already submitted. */
prompt: string
name: string
bypassPermission: boolean
}
/** See `CoreApi.daemon`. */
export interface DaemonAddress {
command: string
port: number
machineId(): string
/** The account's environment (`prod`, `staging`, …), as the links a feature makes name it. */
autonomousEnv: string
}
/**
* This machine's E2EE identity as Share's owner uses it (sharing/crypto.ts `OwnerKey`): its public half, and
* the signature on a welcome to one observer of one share. The private half is the gateway's alone; a Share in
* a process of its own asks for each welcome and holds no credential. Base64 throughout.
*/
export interface ObserverKey {
publicKey(): Promise<string>
signWelcome(machineId: string, shareId: string, peer: string, ephemeral: string): Promise<string>
}
/** A process with no key of the core's: it signs nothing. */
export const OBSERVER_KEY_OFF: ObserverKey = {
publicKey: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
signWelcome: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
}
/** A peer in a shared tab: its machine, and the identity key the roster lists for it, vouched for by the caller. */
export interface TabLink { sharedTabId: string; machineId: string; peerPub: string }
/**
* Shared tabs' keys, held by the gateway with this machine's E2EE identity
* (docs/superpowers/specs/2026-10-15-agent-messages-across-accounts-design.md): the owner's signature on a roster
* and on a move to a new key, and a session per peer machine, keyed by tab and machine. Agent Messages, in the edge
* host, holds no key and asks for each.
*/
export interface TabKey {
publicKey(): Promise<string>
signRoster(sharedTabId: string, version: number, body: string): Promise<string>
signKeyChange(sharedTabId: string, nextPub: string): Promise<string>
hello(link: TabLink): Promise<Record<string, unknown>>
welcome(link: TabLink, payload: Record<string, unknown>): Promise<boolean>
accept(link: TabLink, hello: Record<string, unknown>): Promise<{ welcome: Record<string, unknown> } | { refused: true }>
seal(link: TabLink, frame: Record<string, unknown>): Promise<LaneSealed>
open(link: TabLink, frame: Record<string, unknown>): Promise<LaneOpened>
drop(link: TabLink): void
}
/** A process with no key of the core's: it signs nothing, starts no session and seals nothing. */
export const TAB_KEY_OFF: TabKey = {
publicKey: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
signRoster: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
signKeyChange: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
hello: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
welcome: async () => false,
accept: async () => ({ refused: true }),
seal: async () => ({ lost: true }),
open: async () => ({ lost: true }),
drop: () => {},
}
/**
* What a shared tab's relay said (gateway/tabRelay.ts, the backend's `/api/agent-messages-ws`), handed on to Agent
* Messages as it arrived: a frame from one of the tab's machines with who the relay says sent it (`from`, stamped by
* the relay, never the sender's word), a frame it had nobody to deliver to (`undeliverable`, the machine it was for),
* the relay admitting this machine (`ready`, sent again after each redial), or the socket closed for good (`closed`:
* 4403 when this machine is not in the tab, 4409 when another socket of it took the tab over).
*/
export interface TabFrame {
sharedTabId: string
from?: { machineId: string; userId: string }
payload?: Record<string, unknown>
undeliverable?: string
closed?: { code: number; reason: string }
ready?: true
}
/**
* Shared tabs' relay, held by the gateway (gateway/tabRelay.ts): one long-lived socket per shared tab, which carries
* frames already sealed between the tab's machines (`TabKey`). What it hears comes back as `GatewayEvents.tabFrame`.
*/
export interface TabRelay {
/** Keep a socket to the shared tab's relay open (idempotent). */
open(sharedTabId: string): Promise<void>
/** Send a frame to a machine of the shared tab; false when no socket is open for the tab. */
send(sharedTabId: string, to: string, payload: Record<string, unknown>): Promise<boolean>
/** Close the tab's socket and stop reconnecting. */
close(sharedTabId: string): void
}
/** A process with no relay of the core's: it opens nothing and sends nothing. */
export const TAB_RELAY_OFF: TabRelay = { open: async () => {}, send: async () => false, close: () => {} }
/**
* The account's connected services sealed for its machines (lib/e2ee/connectorVault.ts), by the gateway,
* which holds this machine's identity and reads the device key log: `seal` makes an envelope for every
* machine of the account's log (not suspended, not pending), `open` reads one only if such a machine
* signed it, and answers null otherwise. `complete` says it was sealed for every such machine: one that
* is not misses a machine added since, and is sealed again. The envelope is opaque JSON for the backend.
*/
export interface ConnectorVault {
seal(plaintext: string): Promise<Record<string, unknown>>
open(envelope: unknown): Promise<{ plaintext: string, complete: boolean } | null>
}
/** A process with no key of the core's: it seals and opens nothing. */
export const CONNECTOR_VAULT_OFF: ConnectorVault = {
seal: () => Promise.reject(new Error('no key: this process holds no E2EE identity')),
open: async () => null,
}
/** A service in its own process that acts on no agent: it creates none and reads no harness's frame. */
export const AGENT_ACTIONS_OFF: Pick<CoreApi['agents'], 'create' | 'dsh'> = {
create: async () => ({ ok: false, error: 'SERVICE_UNAVAILABLE' }),
dsh: () => null,
}
/** The account signed in here, as Agent Messages' shared tabs name their owner and members by it. */
export interface AccountIdentity { accountId: string; email: string }
/**
* The account signed in here, read once through the core's own sign-in (`GET /api/auth/me`): a sign-in to another
* account starts a new core, so what it read stays true. Asked again after a read that failed or said nothing usable.
* Read by the core rather than by Agent Messages in its process, which may call only `MESSAGES_BACKEND_ROUTES`.
*/
export function accountIdentity(backend: CoreApi['account']['backend']): () => Promise<AccountIdentity | null> {
let known: AccountIdentity | null = null
return async () => {
if (known) return known
const reply = await backend('GET', '/api/auth/me').catch(() => null)
const data = reply?.status === 200 && reply.body.success === true ? reply.body.data as { user?: Record<string, unknown> } | undefined : undefined
const user = data?.user
if (typeof user?.id !== 'string' || !user.id || typeof user.email !== 'string' || !user.email) return null
known = { accountId: user.id, email: user.email }
return known
}
}
/** The account as a service that reads no backend, hears no notice and signs nothing has it. */
export const ACCOUNT_BACKEND_OFF: Pick<CoreApi['account'], 'backend' | 'identity' | 'onNotice' | 'observerKey' | 'tabKey' | 'tabRelay' | 'connectorVault'> = {
backend: async () => ({ status: 503, body: { error: 'SERVICE_UNAVAILABLE' } }),
identity: async () => null,
onNotice: () => () => {},
observerKey: OBSERVER_KEY_OFF,
tabKey: TAB_KEY_OFF,
tabRelay: TAB_RELAY_OFF,
connectorVault: CONNECTOR_VAULT_OFF,
}
/** Where a service that was never told runs this daemon from: the installed CLI, on no port it knows. */
export const DAEMON_UNKNOWN: DaemonAddress = { command: 'harness', port: 0, machineId: () => '', autonomousEnv: 'prod' }
/** How a delivery is told apart: `answersQuestion` marks a person's Swarm message, which closes the question it answers
* in a Claude pane (core/input.ts `beforeTeamWrite`);
* `writtenAt` is when it was written (ms), as only a question open since then is its to close. */
export interface DeliveryOptions { answersQuestion?: true; writtenAt?: number }
/** What became of a delivered turn (`turns.deliver`), as the core's input says it: `queued`, written
* (`delivered`), its turn `started`, `rejected` with why, or `unknown`. `sessionId` is the agent it was
* delivered to, as the delivery named it. */
export type TurnDelivery = SessionInputDelivery
/** The delivery members of a core that delivers nothing for this service: nothing is written, nothing is
* taken back, and nothing is heard. */
export const DELIVERIES_OFF: Pick<CoreApi['turns'], 'deliver' | 'cancelDelivery' | 'onDelivery' | 'leaseDeliveries'> = {
deliver: () => {},
cancelDelivery: () => false,
onDelivery: () => () => {},
leaseDeliveries: async () => false,
}
/** A turn's card for the devices: the dial's and the Wi-Fi device's tiles and their notifications. */
export type TurnCardFrame = {
type: 'commander_event'
agentId: string
dbSessionId: string
name?: string
payload: Record<string, unknown>
}
/** A turn's recap for the windows and the phone. */
export type TurnSummaryFrame = { type: 'turn_summary' | 'turn_summary_pending' } & Record<string, unknown>
/** The frame types `clients.turnCard` and `clients.turnSummary` carry: the core sends no other for them. */
export const TURN_CARD_TYPES: ReadonlySet<string> = new Set(['commander_event'])
export const TURN_SUMMARY_TYPES: ReadonlySet<string> = new Set(['turn_summary', 'turn_summary_pending'])
/** `agents.resolve` over a service process's own copy of the agents, as the registry answers it: by agent
* id, then by engine session id (an agent with none yet is never found by an empty one). */
export function resolveAgent(agents: readonly RegisteredSession[], id: string): RegisteredSession | undefined {
return agents.find((agent) => agent.agentId === id) ?? (id ? agents.find((agent) => agent.sessionId === id) : undefined)
}
/** Who sent a request, as the core established it. A service trusts this, never a field of the
* payload: a payload says whatever its sender wrote. */
export interface Asker {
/** A process on this machine (the desktop app, `hn`, a script), over the local socket. */
local: boolean
/** Whether it may control this machine: a local process, a paired app, or a verified machine share.
* A device or an observer may not. Account-backed services also check accountOwner. */
owner: boolean
/** Authority to use the host account, separately from control of a shared machine.
* Established by the gateway's pairing record, never by the request payload.
* Absent in older transports; a local owner remains authoritative. */
accountOwner?: boolean
/** A guest's session (RemoteClient.guest): the account it is shared with. Never `owner`. */
guest?: string
/** Another of the owner's machines, when the request came over that machine's own link: its id as its pairing
* record holds it, and the label it was paired under. Set by the core from the gateway's record, never the payload. */
machine?: { machineId: string; label: string | null }
/** The connection it came over (a window's, a remote client's), as the core names it, and the id it
* asked under: what a service keys work by that belongs to one connection (the Model Manager's grid
* commands, which a cancel on the same connection stops; a limit on how many at once per connection).
* The handler hears that connection close through `closed`. Absent when the core itself asks, and from
* a core from before it was given: then the request is its own connection. */
connection?: string
requestId?: string
}
/**
* A request a service answers for the apps: the reply, or a promise of it. A throw or a rejection is
* answered `SERVICE_FAILED` by the host and counted against the service.
*
* `closed` is aborted when the connection that asked closes (`Asker.connection`), or when the core that
* routed it goes: nobody is left to read the answer, so the work for it may stop. A handler that ignores
* it runs to the end, as every one did before it was given; one called without it (a spec, a wrapper)
* is never told.
*/
export type ServiceRequest = (payload: Record<string, unknown>, asker: Asker, closed?: AbortSignal) => Record<string, unknown> | Promise<Record<string, unknown>>
/** 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
/** Memories (services/memory.ts), an experiment: what this machine's agents remember, for the owner's Memories
* panes on their other machines, and the About You profile and its on/off choice from them. */
export const MEMORY_REQUESTS = ['memory_snapshot', 'memory_about_put', 'memory_deliver'] as const
/** The router (services/router.ts), an experiment: where a task a person typed or said should go, decided for
* the client that asks, which acts on it. */
export const ROUTER_REQUESTS = ['route_decide'] as const
export const SUPER_TAB_REQUESTS = ['super_tabs'] as const
export interface SuperTabsPort { connected(): void; disconnected(): void; stop(): void; swarmRole(harnessId: string): Promise<import('../lib/swarmSkills.js').SwarmSkillGrant | null | undefined> }
export const SUPER_TAB_FALLBACKS: PortFallbacks<SuperTabsPort> = { connected: undefined, disconnected: undefined, stop: undefined, swarmRole: later(undefined) }
/** The project and folder readers (services/projects.ts). */
export const PROJECTS_REQUESTS = ['git_pull_request', 'git_pull_requests_status', 'git_project_info', 'scm_project_info', 'project_preview', 'fs_list_dir', 'agent_read_file'] as const
/** A window's name for its repo and its work, by a small model in the background (services/windowNames.ts). */
export const WINDOW_NAMES_REQUESTS = ['window_name'] as const
/** Change agent's handoff file, prepared in the edge host (services/handoff.ts). */
export const HANDOFF_REQUESTS = ['agent_handoff_prepare', 'agent_handoff_complete'] as const
/** Connected services for every local agent, and their MCP bridge, in the edge host (services/connectors.ts). */
export const CONNECTORS_REQUESTS = ['connectors'] as const
/** Sharing this machine with other accounts, and adding machines shared with this one, in the edge host
* (services/sharedMachines.ts). */
export const SHARED_MACHINES_REQUESTS = ['shared_machines', 'guest_folders'] as const
/** What the core asks to start a guest's harness: whose (the email the gateway named the session by), which
* engine, and whether it works without asking for each command. */
export interface GuestLaunchInput { email: string; engine: string; bypassPermission: boolean; prompt?: string
/** The engine's own flags for the permission mode asked for (lib/engineLaunch.ts `permissionModeFlags`), as an
* owner's launch passes them; absent, `bypassPermission` alone decides. */
permissionFlags?: string[]
/** A folder the owner shares to start in; the guest's workspace when absent or not shared. */
cwd?: string }
/** A guest's harness as shared machines builds it (services/guestLaunches.ts): the pane's command, which runs
* the engine as the guest's own OS user on the guest's own sign-in, the variables to set on the pane, and
* `workspace`, where it starts (the guest's workspace or a folder the owner shares). The core opens it and
* records whose it is (core/agents/guestCreate.ts).
*
* `guestHostUser` is set where the pane must be made by the guest's own host rather than this account (Windows:
* lib/windows/guestHostBackend.ts), whose panes already run as that user; its absence means the owner's backend
* starts the pane and a helper hands it to the guest (macOS, Linux). */
export type GuestLaunch =
| { ok: true; workspace: string; argv: string[]; env: Record<string, string>; guestHostUser?: string }
| { ok: false; error: string; detail?: string }
/** The core's call into shared machines: a guest's launch (docs/plans/2026-10-19-guest-machine-sharing-plan.md). */
export interface SharedMachinesCorePort {
guestLaunch(input: GuestLaunchInput): Promise<GuestLaunch>
/** The service stopping: its reads stop. */
stop(): Promise<void> | void
}
/** What a guest's New Harness is told while shared machines is off or failing. */
export const GUEST_LAUNCH_UNAVAILABLE: GuestLaunch = {
ok: false, error: 'GUEST_UNAVAILABLE', detail: 'Sharing isn\'t running on this computer right now. Try again in a moment.',
}
export const SHARED_MACHINES_FALLBACKS: PortFallbacks<SharedMachinesCorePort> = { guestLaunch: later(GUEST_LAUNCH_UNAVAILABLE), stop: undefined }
/** What the core calls while `ports.sharedMachines` is null. */
export const SHARED_MACHINES_OFF: SharedMachinesCorePort = { guestLaunch: async () => GUEST_LAUNCH_UNAVAILABLE, stop: () => {} }
/** A Harness OS computer managed from the owner's phone: whether it runs Harness OS, its update, and its Wi-Fi,
* in the edge host (services/osDevice.ts). */
export const OS_DEVICE_REQUESTS = ['os_device'] as const
/** Add-ons for a device that is this Harness machine (lib/autonomous-device/machineAddons.ts): the owner's machines
* read what it published and propose to it, each proposal stamped with the machine it came from. */
export const MACHINE_ADDON_REQUESTS = ['machine_addon'] as const
/**
* Models (services/models.ts).
*
* The Model Manager's grid commands, `grid_fleet_run` and `grid_fleet_cancel`, are among them: a command
* is a job of the connection that started it, and a cancel stops only that connection's own
* (`lib/gridFleetRpc.ts`), keyed by the connection and request id the core gives every request
* (`Asker`). Their handshake, `grid_fleet_capabilities`, is still the socket's: the Grid harness runs a
* command only after it and reads an answer without its protocol as "update Harness", which a models
* service that is down must not make it say.
* 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',
'grid_fleet_run', 'grid_fleet_cancel', 'grid_swarm_sync', 'grid_swarm_api_share', 'grid_swarm_api_shares', 'grid_swarm_offer', 'grid_swarm_offers', 'grid_swarm_heal',
'api_connections', 'codex_profiles_list', 'codex_profile_link',
'claude_profiles_list', 'claude_profile_link', 'swarm_account_offer',
] as const
const MINUTE = 60_000
/**
* How long the core waits on a service in a process of its own for these answers before it answers
* SERVICE_UNAVAILABLE, where the half minute it gives any other would cut short what they do
* (core/serviceLinks.ts). By service, then by request or port call. A wait that runs out answers the
* asker; the work itself goes on in the service's process.
*
* - A grid command runs as long as its caller asked, up to half an hour (`GRID_FLEET_MAX_TIMEOUT_MS`).
* - Grid's set-up installs `grid` on first use (its installer is given ten minutes, `gridInstall.ts`),
* hands it this machine's sign-in and makes the account's grid: a Set up, a Get, a Use, `ensure` and
* a move onto a grid model (`moveTarget`) each wait for it.
* - A launch target, the private grid's name and the lists each run a few `grid` calls of up to 30 s.
* - The Store's install and update set up a harness's toolchain: minutes.
*
* A grid or saved-API launch (`gridLaunch`) is built from what models has in hand, and a saved API's target
* (`apiTarget`) reads its model list for at most 15 s (lib/apiModels.ts): both take the half minute, which bounds
* how long a launch on one can wait. A launch on the engine's own login asks models nothing.
*/
export const LONG_ANSWERS: Readonly<Record<string, Readonly<Record<string, number>>>> = {
// Fifty GitHub reads, four at a time, each with an eight-second subprocess deadline.
projects: { git_pull_requests_status: 120_000 },
// The device's own service waits up to 20 s for its next proposal (lib/autonomous-device/machineAddons.ts).
machineAddons: { machine_addon: 30_000 },
models: {
grid_fleet_run: GRID_FLEET_MAX_TIMEOUT_MS + MINUTE,
grid_fleet_models_list: 15 * MINUTE, grid_fleet_model_download: 15 * MINUTE, grid_fleet_model_start: 15 * MINUTE,
ensure: 15 * MINUTE, moveTarget: 15 * MINUTE,
launchTarget: 3 * MINUTE, privateGridName: 2 * MINUTE, lists: 2 * MINUTE,
},
store: { dsh_install: 30 * MINUTE, dsh_update: 30 * MINUTE, dshMaterialize: 6 * MINUTE },
// A cloud agent's maker answers on its own time: Fo's reply waits 40 s, and a busy Fo is retried for half a
// minute more. A wait shorter than that said "not running" of words that were then sent anyway.
cloud: { create: 3 * MINUTE, deliver: 3 * MINUTE, answer: 3 * MINUTE, stopHarness: 2 * MINUTE, cloud_send: 3 * MINUTE },
// A guest's first harness makes their OS account (`dscl`, a home); turning guest access on waits on the
// owner at the admin prompt, which gives up after ten minutes (lib/guestHelperInstall.ts).
sharedMachines: { guestLaunch: 2 * MINUTE, shared_machines: 11 * MINUTE },
}
/** The orchestrator (services/orchestrator.ts): its projects, for the apps and for the agents it runs. */
export const ORCHESTRATOR_REQUESTS = ['orchestrator'] as const
/** Share (services/sharing.ts): an owner's shares of a harness, their links and their comments; and the observers
* shared tabs want for this computer's harnesses, derived again from their rosters (`harness_share_rosters`, which
* Agent Messages asks through the core as a roster changes, core/messagesLink.ts `observers`). */
export const SHARE_REQUESTS = [
'harness_share_list', 'harness_share_invite', 'harness_share_remove', 'harness_share_link',
'harness_share_comments', 'harness_share_comment_post', 'harness_share_comment_remove', 'harness_share_rosters',
] as const
/** Agent Messages (services/messages.ts, messages/service.ts): from `harness send` in an agent's pane, from the
* owner's other machines and from the windows. A service in the edge host since 2026-10-12, no longer an
* experiment: its own process cost every computer it was on 62 MiB at idle for a few MiB of messaging. */
export const MESSAGES_REQUESTS = ['agent_messages'] as const
/** Cloud agents (services/cloud.ts, cloud/service.ts): a cloud harness's conversation for its chat pane, and
* which cloud agents are connected here, for New Harness. */
export const CLOUD_REQUESTS = ['cloud_transcript', 'cloud_send', 'cloud_agents'] as const
/**
* What Agent Messages in a process of its own may do through the core, and nothing more (core/messagesLink.ts
* answers it, and checks each): the agents as the apps are shown them (`shown`) and how an agent's shell reaches
* this daemon (`daemon`), which its roster and its `harness send` read; the account signed in here (`account`, its id
* and email, which the core reads: `accountIdentity`); the account's backend, only the routes of
* `MESSAGES_BACKEND_ROUTES` (`backend`): its tabs and their leaders, and shared tabs' shares, rosters, invitations, members and moves; its
* log's change notice for the windows (`windows`, only `MESSAGES_WINDOW_FRAME`); which of its typed deliveries may be
* written (`writable`); and shared tabs' keys, which the gateway holds (`tab_key`, one `TabKey` method a call,
* lib/tabKeyWire.ts), and their relay, whose sockets the gateway holds too (`tab_relay`, one `TabRelay` method a call,
* lib/tabRelayWire.ts); and that a shared tab's roster changed here (`observers`), which the core hands to Share as
* `harness_share_rosters`, so that a member removed stops watching this computer's harnesses at once. It writes turns into agents (core/deliveries.ts, `TURN_DELIVERERS`) and hears the account's
* `desk_changed`. The questions the experiment asked are answered as they were, so a core of either version answers
* the process of the other (harnessd/services.ts); a core from before `account` answers it `UNKNOWN_QUERY`, and shared
* tabs are then unavailable while the rest of Agent Messages runs on.
*/
export const MESSAGES_QUERIES = ['writable', 'shown', 'daemon', 'account', 'backend', 'windows', 'tab_key', 'tab_relay', 'observers', 'activity'] as const
/** Each id as the backend makes it: a shared tab's (24 hex), a desk tab's, an invitation's (a UUID) and an account's. */
const SHARED_TAB = '[a-f0-9]{24}', DESK_TAB = '[A-Za-z0-9_-]{1,64}', USER = '[A-Za-z0-9_-]{1,128}'
const INVITE = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
const route = (method: string, path: string) => ({ method, path: new RegExp(`^/api/agent-messages${path}$`) })
/**
* The backend routes Agent Messages in its process may call through the core's sign-in (`backend`), by method and
* whole path, and no others (backend/src/routes/agentMessages.ts). Its process holds no credential: the core signs
* each call, so a route left open here is a route any code in that process could call as the account. Anchored, and
* each id held to the shape the backend gives it, so that no path climbs out (`..`), carries a query or names another
* route. Shared tabs' were refused by the one GET this allowed before, which left every share action failing in the
* edge host, where Agent Messages runs.
*/
export const MESSAGES_BACKEND_ROUTES: ReadonlyArray<{ method: string; path: RegExp }> = [
route('GET', ''),
route('GET', '/shares'),
route('PUT', `/shares/${DESK_TAB}/roster`),
route('POST', `/shares/${SHARED_TAB}/invites`),
route('GET', '/invites'),
route('DELETE', `/invites/${INVITE}`),
route('POST', `/invites/${INVITE}/accept`),
route('DELETE', `/shares/${SHARED_TAB}/members/${USER}`),
route('DELETE', `/shares/${SHARED_TAB}`),
route('POST', `/shares/${SHARED_TAB}/move`),
// A desk tab's setting: its leader, which the person chooses for a shared tab from any computer of the account
// (sharedTabs.ts `setLeader`). The computer that shares the tab signs the roster that follows it.
route('PATCH', `/tabs/${DESK_TAB}`),
]
/** Whether Agent Messages in its process may make this backend call (`MESSAGES_BACKEND_ROUTES`). */
export const messagesBackendAllowed = (method: unknown, path: unknown): boolean =>
typeof method === 'string' && typeof path === 'string' && MESSAGES_BACKEND_ROUTES.some((r) => r.method === method && r.path.test(path))
export const MESSAGES_WINDOW_FRAME = 'messages_changed'
/** Shared tabs changed on this computer (a roster, an invitation, an alert, a notice, a waiting request or the
* untrusted list): the windows read `shares` again. Only a revision: what changed is read, never pushed. */
export const SHARED_TABS_WINDOW_FRAME = 'shared_tabs_changed'
/** Another account's harness in a shared tab started or stopped working (messages/tabActivity.ts). */
export const SHARED_ACTIVITY_WINDOW_FRAME = 'shared_activity'
/** What Agent Messages may tell this computer's windows (core/messagesLink.ts `windows`), and nothing else. */
export const MESSAGES_WINDOW_FRAMES: readonly string[] = [MESSAGES_WINDOW_FRAME, SHARED_TABS_WINDOW_FRAME, SHARED_ACTIVITY_WINDOW_FRAME]
/**
* The experiments: services that cost nothing until they are on (docs/design/2026-10-06-core-boundary-next.md,
* "Experimental features: move only"). Each runs in a process of its own that the master starts only once the
* core asks for it (harnessd/services.ts `onDemand`): when one of its `requests` arrives, or at start when its
* saved `state` is in the data folder (paths under it; `dir/*.ext` for a file of that kind in that folder).
* Off, it has no process and none of its code is loaded anywhere. Each may act on the core through the hooks
* an experiment has (core/experimentQueries.ts, core/deliveries.ts), and no other process may.
*
* Adding one: its service (`start<Name>(core, ports)`, returning its requests' handlers) and its process's
* runner (`SERVICE_RUNNERS`, src/serviceProcess.ts); its process (`SERVICE_HOSTS`, `onDemand: true`); its
* entry here; and its start for the core's own process (services/inline.ts `EXPERIMENT_STARTS`). Removing
* one is deleting those.
*/
export const EXPERIMENTS: Readonly<Record<string, { requests: readonly string[]; state: readonly string[] }>> = {
orchestrator: { requests: ORCHESTRATOR_REQUESTS, state: ['orchestrator/*.json'] },
// Its invitations and links: a harness was shared from here. Or a shared tab held here (Agent Messages' file): the
// observers its members are granted are derived and renewed by Share, and taken back once one leaves.
sharing: { requests: SHARE_REQUESTS, state: ['harness-shares.json', 'harness-collaboration.json', 'agent-messages/shared-tabs.json', 'super-tabs/host-*.json'] },
// Request-only, on from its first request until the daemon stops: another machine's Memories pane asks, and
// the package's own files are its state.
memory: { requests: MEMORY_REQUESTS, state: [] },
// Request-only too: it keeps nothing, and asks Jev only when a client asks it.
router: { requests: ROUTER_REQUESTS, state: [] },
// A Swarm host here.
superTabs: { requests: SUPER_TAB_REQUESTS, state: ['super-tabs/host-*.json'] },
// Cloud agents. Its harnesses: one was started here, and is watched again as the daemon starts. A New Harness
// for one, an answer or a message to one wakes it too (its port's calls, core/agents/cloud.ts).
cloud: { requests: CLOUD_REQUESTS, state: ['cloud/harnesses.json'] },
}
/** The services that may write turns into agents from a process of their own (core/deliveries.ts): the experiments,
* and Agent Messages, which left them for the edge host and still types a message into an idle agent. No other
* process may: writing into a pane is no other service's to ask. */
export const TURN_DELIVERERS: readonly string[] = [...Object.keys(EXPERIMENTS), 'messages']
/** The core's calls into Share: an observer's frame as the relay handed it over, the relay gone (every observer
* with it), and stopping it. */
export interface SharingPort {
observer(connId: string, type: string, payload: Record<string, unknown>): Promise<void> | void
linkDown(): void
stop(): Promise<void> | void
}
/** What the core gets when Share fails: an observer's frame goes unanswered, as it would to a daemon without
* Share, and a shutdown goes on. */
export const SHARING_FALLBACKS: PortFallbacks<SharingPort> = { observer: undefined, linkDown: undefined, stop: undefined }
/** What an agent is to the orchestrator's projects: a specialist (`worker`), or a project's Director, and
* whether work is still out under it. */
export type OrchestratorRole = { role: 'worker' } | { role: 'director'; busy: boolean }
/** The core's calls into the orchestrator: what an agent is to its projects, asked at every turn's end
* (core/turns/recaps.ts), the frames the apps are sent, which its projects read their Directors' turns
* from, and stopping it. */
export interface OrchestratorPort {
roleOf(agentId: string): OrchestratorRole | null
frame(frame: Record<string, unknown>): void
stop(): void
}
/** What the core gets when the orchestrator fails: no agent is a specialist or a Director, so every turn's
* end is announced; no project hears a frame; a shutdown goes on. */
export const ORCHESTRATOR_FALLBACKS: PortFallbacks<OrchestratorPort> = { roleOf: null, frame: undefined, stop: undefined }
/** 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. */
export type SearchPort = Pick<SessionSearchIndex, 'touch' | 'deleteHistory' | 'session' | 'stop'> & {
inspect(request: ExternalSessionRequest): Promise<ExternalSessionAnswer>
}
/** What the core gets when search fails: nothing indexed and no title. */
export const SEARCH_FALLBACKS: PortFallbacks<SearchPort> = {
touch: undefined, deleteHistory: undefined, session: undefined, stop: undefined, inspect: later(externalUnavailable()),
}
/*
* Recaps (services/recaps.ts): each turn's recap, the devices' turn cards and the notifications a finished
* turn rings, built from the turn's lifecycle. The core tells the recaps that lifecycle as it happens and
* never waits on them: a session runs the same without them, and a turn they miss simply has no recap.
*/
/** A session as the core knows it when it tells the recaps something: what a card is addressed to. */
export interface RecapSession {
sessionId: string
/** The agent that owns it: a card is addressed to the agent, stable across a `/clear`. */
agentId: string
/** Its display name, which a summary card carries for a machine whose tile is not loaded. */
name?: string
/** Its engine (`claude`, `codex`, …): what a finished turn's tier is decided with (lib/notifyTier.ts). */
engine?: string
/** Its transcript: a Claude sub-agent writes its own beside it, which a held turn end watches. */
transcriptPath?: string
/** An Orchestrator specialist's turn, or its director's while specialists are out: nobody's news. Said
* where a turn ends, a cancel or a forget (reading it reads the orchestrator); absent, the recaps keep
* what they were last told. */
subagent?: boolean
/** Its finished turns are silent on the devices (the dial, the phone): its news reaches people another way. The core
* only carries this; who says it is outside the core (a Swarm agent's, through the Swarm's door: superTabs/inCore.ts).
* Said with every event, since the recaps in their own process have no agent list to look it up in (#2540's review). */
quietOnDevices?: boolean
}
/** Who watches this machine's turn cards: a device at all (through the backend or on the cable), and one
* rendering this machine right now. `remote`: an app away from this desk (the phone, a browser) holds a session
* over the relay, and hears how loudly each turn ends (`turn_summary`'s `tier`); absent from an older core. */
export interface RecapWatchers { device: boolean; active: boolean; remote?: boolean }
/** The turn lifecycle, as the core tells the recaps. */
export type TurnLifecycle =
/** A session's events (a turn started, its text, its tools and sub-agents, its end), as one batch. */
| { kind: 'events'; session: RecapSession; events: LiveEvent[]; replay: boolean }
/** The core's five-second turn heartbeat, and whether the turn is verifiably working right now. */
| { kind: 'beat'; session: RecapSession; working: boolean }
/** The turn was cancelled: no turn end comes. */
| { kind: 'cancelled'; session: RecapSession }
/** The session was unbound, or its agent removed; what is stored for it is kept for a resume. */
| { kind: 'forgotten'; session: RecapSession }
/** The engine's Stop hook: it stopped writing. */
| { kind: 'stopped'; sessionId: string }
/** The agent's conversation moved to a new session (a `/clear`, a fork's first turn): its recaps follow. */
| { kind: 'rebound'; from: string; to: string }
/** The conversation was purged: everything stored for it goes. */
| { kind: 'purged'; sessionId: string }
/** A question was put to the person, or answered: a turn waiting on one is not announced as done. */
| { kind: 'asked' | 'answered'; sessionId: string; requestId: string }
/** A device joined: every session's card is said again. `working`: the sessions whose turn is
* verifiably working now, whose busy card is said with it. */
| { kind: 'rejoined'; working: string[] }
/** The session attached with its last turn already over, so its end was read as history: recapped quietly
* if it has none yet (it ended while the daemon was stopped). */
| { kind: 'settled'; session: RecapSession }
/** The core's calls into the recaps: the lifecycle, and what they hold of a session, read in line. */
export interface RecapsPort {
/** Something happened to a turn. A notice: the core never waits for it, and one the recaps miss costs
* that turn its recap, nothing else. */
lifecycle(event: TurnLifecycle, watchers: RecapWatchers): void
/** A session's last turns and asks, and whether its card is busy; null when they hold nothing. */
recaps(sessionId: string): SessionRecaps | null
/** The cards of every turn still working or being recapped, for a dial that just attached: asked when it
* attaches and sent when they come, never waited for in line. */
liveCards(): Promise<TurnCardFrame[]>
}
/** What the core gets when the recaps fail: nothing told, no recap, and no live card. */
export const RECAPS_FALLBACKS: PortFallbacks<RecapsPort> = { lifecycle: undefined, recaps: null, liveCards: later([]) }
/**
* The core's calls into the agent cleanup (services/agentCleanup.ts): what happens to the harnesses agents start.
* Notices: the core never waits for them, and one the cleanup misses leaves a harness open, as before it.
*/
export interface AgentCleanupPort {
/** A harness was closed or stopped (`agent_close`, Stop Harness, a purge): the harnesses it started close too. */
closed(agentId: string): void
/** The person typed or pasted into a harness, from a window or the phone (an agent id or a session id): one another
* agent started is the person's from then on. */
typed(id: string): void
stop(): void
}
/** What the core gets when the cleanup fails: nothing told, and every harness left open, as before it. */
export const AGENT_CLEANUP_FALLBACKS: PortFallbacks<AgentCleanupPort> = { closed: undefined, typed: undefined, stop: undefined }
/** The core's calls into the DSH viewers: each harness agent's viewer server and verdict watch. */
export interface ViewersPort {
/** Start the agent's viewer and verdict watch when it has a DSH. Idempotent: called on every
* observation of the agent. */
attach(session: RegisteredSession): void
/** Stop them: the agent was forgotten. */
detach(agentId: string): void
/** What the agent's frame says about its DSH: its name, its viewer and its verdict. */
frameContext(session: RegisteredSession): AgentDshContext | null
/** Where the windows' viewer pane for the agent forwards to. */
forwardingUrl(agentId: string): string | null
/** Stop every viewer and watch, for a restart or a shutdown. */
stop(): Promise<void>
/** A client's frame of a viewer stream (`viewer_request`, `viewer_data`, …), from the connection `connId`:
* how a client that cannot reach this machine's loopback (a phone, another machine's window) is served
* a viewer. False when the viewers did not take it. */
stream(connId: string, type: string, payload: Record<string, unknown>): boolean
/** A client's `viewer_surface`: a frame of a viewer rendered for it by a headless browser, or why not. */
surface(connId: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>
/** A client's connection ended (`connId`), or every one did (none: the link went down, or the socket is
* stopping): its viewer streams and surfaces close. */
closed(connId?: string): void
}
/** What a client is told for a surface the viewers cannot render while they are off or failing. */
export const VIEWERS_UNAVAILABLE = { error: 'SERVICE_UNAVAILABLE', service: 'viewers', retryable: true }
/** What the core gets when the viewers fail: agents' frames carry no DSH context and the windows
* no viewer, a client's viewer stream is refused at once (core/viewerStreams.ts) and its surface
* answered unavailable, and a restart or shutdown goes on. Their process on demand, before it has
* first connected, holds a stream and a surface while it starts instead (core/viewersLink.ts). */
export const VIEWERS_FALLBACKS: PortFallbacks<ViewersPort> = {
attach: undefined, detach: undefined, frameContext: null, forwardingUrl: null, stop: later(undefined),
stream: false, surface: later(VIEWERS_UNAVAILABLE), closed: undefined,
}
/**
* The core's calls into models (grid). Everything an agent's launch, its frame or a keystroke to it needs
* of grid, so the core never loads grid's code (docs/design/2026-10-06-core-boundary-next.md, step 7):
* in the core's process the service answers itself; in its own, core/modelsLink.ts does, from what the
* service last told it for what a frame or a keystroke reads, and by asking it for the rest.
*/
export interface ModelsPort {
/** Have grid ready for what the caller is about to do; resolves with what happened, never rejects. */
ensure: GridAccess['ensure']
/** What an agent's frame says of the grid it is on: from memory, so a frame costs no I/O. */
annotation(grid: AgentGridTarget): GridAnnotation | null
/** Someone is typing to an agent on `grid`: start it while they type, if it sleeps. */
prewarm(grid: AgentGridTarget): void
/** Where a new agent on `selection` sends its inference, resolved from this machine's own signed-in
* grid; null when that grid does not serve the model now. */
launchTarget(selection: NewAgentModel): Promise<GridLaunchOverride | null>
/** Where a running agent moved onto `model` sends its inference (`agent_retarget`): grid set up first,
* on `gridName` or the account's own; the sentence a person reads when it cannot be. */
moveTarget(request: { gridName: string | null; model: string }): Promise<{ target: GridLaunchOverride } | { detail: string }>
/** An agent was just moved onto a grid model: start that grid while its pane restarts, if it sleeps. */
moved(launch: GridLaunchOverride): void
/**
* The launch that points `request.engine` at a grid or a saved API (lib/gridLaunch.ts): what its pane starts
* with and the config files the core writes for it, with a saved API's endpoint and key as saved now when
* `refresh`. An engine that cannot be pointed there is answered with the reason. The core builds no grid launch
* itself (docs/design/2026-10-08-launch-port.md).
*/
gridLaunch(request: GridLaunchRequest): Promise<GridLaunchAnswer>
/** Fresh process evidence, batched; core never waits for it to discover or bind a session. */
gridAssignments(processes: readonly GridAssignmentProcess[]): Promise<GridAssignmentAnswer[]>
/** Where an agent moved onto a saved API's model sends its inference: the key travels only into its launch. The
* sentence a person reads when the API cannot be used. */
apiTarget(request: { connectionId: string; model: string }): Promise<{ target: GridLaunchOverride; apiBase: string } | { detail: string }>
/** The account's private grid: the backend's word, else what this machine works out; null for none. */
privateGridName(): Promise<string | null>
/** What `grid_models_changed` tells the windows: the list as a window that draws row state reads it,
* and as one that does not. */
lists(): Promise<{ plain: Record<string, unknown>; rowState: Record<string, unknown> }>
/** The machine list the core just read (null when signed out): which of the account's other computers
* seem offline, for the models only they serve. */
machines(body: Record<string, unknown> | null, computerId: string): void
/** The sign-in ended: drop what lives exactly as long as it. */
signedOut(): void
}
/**
* What the core gets when models fails: grid set-up, every target and every grid or saved-API launch answered
* with an error (a create on a grid model answers GRID_UNAVAILABLE, and so does a relaunch on one), frames with no
* note and no prewarm, the private grid as the backend said it or none, and no push of the lists. A launch on the
* engine's own login never asks models.
*/
export const MODELS_FALLBACKS: PortFallbacks<ModelsPort> = {
ensure: later(FAIL), annotation: null, prewarm: undefined, launchTarget: later(FAIL), moveTarget: later(FAIL), moved: undefined,
gridAssignments: later(FAIL), gridLaunch: later(FAIL), apiTarget: later(FAIL), privateGridName: later(null), lists: later(FAIL), machines: undefined, signedOut: undefined,
}
/** What the core calls while `ports.models` is null (models is off): its fallbacks' answers. */
export const MODELS_OFF: ModelsPort = {
ensure: () => Promise.reject(new ServiceUnavailableError('models')),
annotation: () => null,
prewarm: () => {},
launchTarget: () => Promise.reject(new ServiceUnavailableError('models')),
moveTarget: () => Promise.reject(new ServiceUnavailableError('models')),
moved: () => {},
gridAssignments: () => Promise.reject(new ServiceUnavailableError('models')),
gridLaunch: () => Promise.reject(new ServiceUnavailableError('models')),
apiTarget: () => Promise.reject(new ServiceUnavailableError('models')),
privateGridName: async () => null,
lists: () => Promise.reject(new ServiceUnavailableError('models')),
machines: () => {},
signedOut: () => {},
}
/** The core's calls into the machine monitor: the readings `agents_list` adds to its rows when a window
* asks for the monitor, and forgetting what a purged agent's workspace held. The same readers answer the
* monitor's own request (`machine_resources`), so the two share one sample and one cache. */
export interface MonitorPort {
/** Each live agent's processes, and the shared ones (lib/harnessResources.ts). */
resources: ReturnType<typeof createHarnessResourcesReader>
/** What each agent's workspace and transcript hold on disk; `invalidate` drops what was measured
* (lib/harnessTelemetry.ts). */
storage: ReturnType<typeof createHarnessStorageReader>
}
/** What the core gets when the monitor fails: the list's rows without readings (core/agents/list.ts
* answers a failed sample as none), and nothing measured to forget. */
export const MONITOR_FALLBACKS: PortFallbacks<MonitorPort> = { resources: later(FAIL), storage: later(new Map()) }
/** What the core calls while `ports.monitor` is null (the monitor is off): its fallbacks' answers. */
export const MONITOR_OFF: MonitorPort = {
resources: () => Promise.reject(new ServiceUnavailableError('monitor')),
storage: async () => new Map(),
}
/** The core's calls into workspaces: name made-up worktree branches after their sessions, on each
* terminal-title pass, and sweep the worktrees nothing uses, when the core says it is time. */
export interface WorkspacesPort {
nameBranches(): void
sweepUnused(): void
}
/** What the core gets when workspaces fails: branches keep their names and nothing is swept. */
export const WORKSPACES_FALLBACKS: PortFallbacks<WorkspacesPort> = { nameBranches: undefined, sweepUnused: undefined }
/** The core's calls into Agent Messages: whether one of its typed deliveries (a `team:` id) may still be written,
* asked in line as it is written (core/input.ts); and that the core's copy of the account's switch changed
* (core/experiments.ts `createAgentSettingsSync`), which wakes it when it is turned on: off, it runs no timer that
* would read the file again, and a file never written has nothing to watch (messages/settingWatch.ts). */
export interface MessagesPort {
canWrite(deliveryId: string): boolean
settingsChanged(): void
}
/** What the core gets when Agent Messages fails: none of its deliveries may be written (each waits, unwritten), and
* a settings write tells it nothing. */
export const MESSAGES_FALLBACKS: PortFallbacks<MessagesPort> = { canWrite: false, settingsChanged: undefined }
/**
* The cloud agents' doors into the core (docs/design/2026-10-11-cloud-agents.md, "The one core change"): the
* harnesses its service owns, which have no pane, and the questions they ask. The core lists them beside the
* terminal agents and tells every client what changed (core/agents/cloud.ts).
*/
export interface CloudCore {
/** Every cloud harness, replacing the last list. */
publish(harnesses: CloudHarness[]): void
/** One waits on the person: shown wherever questions show; the answer comes back through `CloudPort.answer`. */
ask(agentId: string, requestId: string, question: { text: string; choices: string[] }): void
/** That question is no longer asked. */
unask(agentId: string, requestId: string): void
}
/** The request ids of the Super Tab waits on the devices: never an engine's (theirs are its tool ids), so an answer
* sent back for one is never typed into a pane (services/devices.ts). */
export const SUPER_TAB_REQUEST_PREFIX = 'supertab:'
/**
* A Super Tab member on this machine waits on a person: its assignment needs a decision or is stuck
* (superTabs/attention.ts). Shown on the devices cabled here as a question nobody answers there: display only.
*/
export interface SuperTabAttention {
/** The local agent (its harness id). */
agentId: string
/** `supertab:<assignment>:<status>`: stable for one wait, never an engine's question id. */
requestId: string
/** The Super Tab's name, at most 48 bytes. */
superTab: string
attention: 'decision' | 'stuck'
/** What the device reads: the decision asked for, or why it is stuck. */
text: string
}
/** What the core hands the Swarm's own close and reopen (superTabs/inCore/agents.ts): the live registry, the stopped
* records, and the core's close, resume and creation receipts. */
export interface SwarmAgentDeps {
byAgent(agentId: string): RegisteredSession | undefined
stoppedIds(): string[]
closeAgent?: (request: AgentCloseRequest) => Promise<AgentCloseResult>
resumeAgent?: (agentId: string) => Promise<{ ok: true } | { ok: false; error: string; detail?: string }>
creationStatus?: (creationId: string) => Promise<CreationObservation | null>
}
export type SwarmAgents = Required<Pick<CoreApi['agents'], 'closeSwarm' | 'keepLeadAlive' | 'closeMember'>>
type SwarmSkill = NonNullable<RegisteredSession['swarmSkill']>
/** The Swarm's part of an agent's start (superTabs/inCore/launch.ts), handed to the launches while the Swarm is on: the
* roles and skill modes a start may ask for, the role's skill written into the project folder (what the engine is told
* to read), and the Harness GitHub App's git and gh for another person's project work (null where it has none). */
export interface SwarmLaunch {
role(value: unknown): value is SwarmSkill['role']
mode(value: unknown): value is NonNullable<SwarmSkill['mode']>
prepare(cwd: string, skill: SwarmSkill): { instructions: string }
github(key: string): { env: Record<string, string>; clearEnv: string[] } | null
/** The engine's arguments for a session the Swarm starts, never for a person's own (lib/swarmEngineArgs.ts). */
args(engine: string): string[]
}
/** Fill a missing Swarm role of an older Swarm session at its restart or resume (superTabs/inCore/adoption.ts): the row
* to launch, or null when the launch is no longer this one's. Absent while the Swarm is off. */
export type AdoptSwarmSkill = ((session: RegisteredSession, current: () => boolean) => Promise<RegisteredSession | null>) & {
/** One role read, for a relaunch that cannot wait (boot restore, a model switch, a host move): the row to launch with
* its role, written to the registry only by `commit`; `unavailable` when the role could not be read, which the caller
* holds or refuses, never launching without it; null when the launch is no longer this one's. */
lookup?(session: RegisteredSession, current: () => boolean): Promise<{ row: RegisteredSession; commit(): void } | 'unavailable' | null>
/** Whether a relaunch of this row asks the Swarm for its role first (restore's `needs`). */
needed?(session: RegisteredSession): boolean
}
export type LeadState = 'ask' | 'stuck' | 'work' | 'done'
/** One Swarm's Lead on a Harness Pro's card (superTabs/cards.ts). `order`: the project's index in the Swarm (the app's
* order), so a dial can show the Leads as the app does whatever their urgency. */
export interface SwarmLead {
id: string; projectId: string; project: string; engine: string; owner: string; local: string; state: LeadState; order: number; since?: number
/** The face of a round dial without swarmBuddy: today's rule, whatever a newer dial swiped to. */
chat?: SwarmChat
notice?: LeadNotice
/** While the Swarm has Buddies on: the face of a dial that speaks swarmBuddy, on the side it keeps for this Swarm. */
sideChat?: SwarmChat
/** Present only while the Swarm has Buddies on. */
buddies?: true
/** The reader's own Buddy in this project, when it has one. */
buddy?: SwarmBuddy
/** The newest message the reader's Buddy wrote in its chat since the baseline: the dial's quiet alert. */
buddyNotice?: LeadNotice
}
/** One Swarm this account is in, as a Harness Pro's card: its Leads, most urgent first. */
export interface SwarmCard { id: string; name: string; count: number; leads: SwarmLead[]
/** The reader's own Personal Swarm (the list row's `personal: true`); never set on a Team Swarm. */
personal?: true }
/** A Lead's last message, for its card; `chatId` when it is the last message of the chat on the round dial's face, and
* `buddy` when that face is a swarmBuddy dial's (`CardChat` 'buddy'), so each dial takes only the recaps it asked for. */
export interface LeadRecap { tabId: string; leadId: string; text: string; at: number; none: boolean; chatId?: string; buddy?: true }
/** A project's places to chat (designs 2026-10-28-round-dial-swarm-chat and 2026-10-29-round-dial-pm-buddy): its Lead
* conversation, the reader's Buddy chat, and a group. A dial without swarmBuddy calls the Buddy chat `pm`, where the PM's
* private lines land since Buddies replaced Chat with PM; a swarmBuddy dial calls it `buddy` and hears the Buddy there. */
export type ChatKind = 'lead' | 'pm' | 'group' | 'buddy'
/** The chat on a project's face on the round dial: the Lead's, unless the window has the project's Buddy chat or a group
* open (or a swarmBuddy dial's side says the Buddy's). `working` only for a working group, `since` from one of its agents'
* turn here. */
export interface SwarmChat { kind: ChatKind; id: string; name: string; working: boolean; since?: number }
/** The newest tag of the reader's in the project since the baseline, the dial's alert: in its Lead conversation (`lead`), the
* reader's Buddy chat or a Chat with PM (`pm`), or a task chat (`group`, #2965); or the newest message the reader's Buddy
* wrote in its chat (`buddy`, the quiet one). `thread`: the root of the thread it is in, when it is in that thread only; such
* a notice is read only where that thread is open. */
export interface LeadNotice { chat: 'lead' | 'pm' | 'group' | 'buddy'; chatId: string; id: string; text: string; at: number; thread?: string
/** A decision asked of the reader: only a swarmNeedsYou dial hears it. */
decision?: true
/** On a decision's notice: the tag notice it covers (never a decision), which a dial that hears no decisions keeps showing. */
tag?: LeadNotice }
/** The reader's own Buddy in a project, for a round dial's Buddy screen: its chat, name and engine, Desktop's pattern for
* its name (`cells`, the 15 half bits; `color`, `#rrggbb`), and `live` false while it is down. */
export interface SwarmBuddy { chatId: string; name: string; engine: string; cells: number; color: string; live: boolean
/** Its session id when it runs on this computer: how a tap on its notification is told from any other agent's. Never sent
* to a device. */
local?: string }
/** The chat the window opens when a device picks a project or taps a session: the project's Lead conversation or the reader's Buddy's. */
export type CardSide = 'pm' | 'buddy'
/** Which chat a card request is about: the Lead's conversation (false, the Pro), today's face (true, a swarmChat dial), or
* the face on a swarmBuddy dial's side ('buddy'). */
export type CardChat = boolean | 'buddy'
/** What became of words spoken on a device for a Lead: posted, not a Lead here (`said` false, so the turn goes as before), or
* refused by the backend with its code and message, which must never become a terminal turn instead. */
export type SaidOnCard = { said: true } | { said: false; refused?: { code: string; message: string } }
/** The conversation the window has open in a Swarm tab. */
export interface CardFocus { tabId: string; conversationId: string }
/** The Super Tab service's door into the core (superTabs/inCore/attention.ts): the waits of its members here. */
export interface SuperTabsCore {
/** Every wait, replacing the last set: the core raises what is new on the devices and closes what is gone. */
attention(items: SuperTabAttention[]): void
/** Every Swarm this account is in, whole, each time it changes: the core keeps the last list for a dial that attaches
* later and hands it to the devices (superTabs/inCore/cards.ts). */
cards(items: SwarmCard[]): void
/** What one Lead last said, pushed when the recap on a Harness Pro's screen moved on. */
cardRecap(recap: LeadRecap): void
/** Members may watch an agent of this machine's: Share must run to invite them (superTabs/observers.ts). Its saved
* state wakes it only as the core starts, so a machine that joined a Swarm while running never invited anyone and
* each member's pane read "must be online" (River on a contributed machine, 2026-10-23). */
shareObservers(): void
/** A member's terminal as plain text for its Lead (superTabs/inCore/terminal.ts): the visible screen, with up to 200 lines
* of scrollback when asked, and what the screen reader says it waits on (a permission prompt, a question). */
screen(agentId: string, scrollback: number): Promise<SuperTabScreen>
/** Text, then each key by its tmux name, typed into a member's terminal under the pane's write lock. */
input(agentId: string, text: string, keys: string[]): Promise<SuperTabTyped>
/** The same keys, sent only if the visible screen, read again under the pane's write lock, is exactly `screen` (superTabs/inCore/
* terminal.ts): for a caller that read the screen earlier and must not type into a different one. */
inputIfScreen(agentId: string, keys: string[], screen: string): Promise<SuperTabTyped>
}
export type SuperTabScreen = { ok: true; text: string; hold: MessageHold | null } | { ok: false; error: string }
export type SuperTabTyped = { ok: true } | { ok: false; error: string }
/** What the cloud service answers the core: done, or why not, in words a person reads. */
export type CloudResult = { ok: true; detail?: string } | { ok: false; error: string; detail?: string }
/** The core's calls into the cloud agents' service: a New Harness for one, a person's words, an answer, a new name, a Stop. */
export interface CloudPort {
/** `agent_create` for a cloud agent: the new harness's frame, or why not. */
create(request: Record<string, unknown>): Promise<{ ok: true; agent: Record<string, unknown> } | { ok: false; error: string; detail?: string }>
deliver(agentId: string, text: string): Promise<CloudResult>
answer(agentId: string, requestId: string, answers: Record<string, string>): Promise<CloudResult>
/** Rename Harness: the name Harness shows. The maker's own name for the work stays as it is. */
rename(agentId: string, name: string): Promise<CloudResult>
/** Stop Harness. Not `stop`: a service host reads a port's `stop` as stopping the service itself. */
stopHarness(agentId: string): Promise<CloudResult>
}
/** A call the cloud service could not take: it is off, failing, or slower than the core waits. */
export const CLOUD_DOWN = { ok: false as const, error: 'SERVICE_UNAVAILABLE', detail: 'Cloud agents are not running here. Try again in a moment.' }
/** What the core gets when the cloud service fails: each call is refused with a reason, and nothing is lost but it. */
export const CLOUD_FALLBACKS: PortFallbacks<CloudPort> = { create: later(CLOUD_DOWN), deliver: later(CLOUD_DOWN), answer: later(CLOUD_DOWN), rename: later(CLOUD_DOWN), stopHarness: later(CLOUD_DOWN) }
/** What a delivered turn answers: delivered, or refused with the machine's name and a reason a person can read. */
export type SendResult = { ok: true } | { ok: false; machine: string; reason: string }
/** What a fork answers: the new agent's id, or why not. */
export type ForkResult = { ok: true; agentId: string } | { ok: false; error: string; detail?: string }
/*
* The devices (services/devices.ts): the dials on USB, the window bridges they speak through, and the
* fleet's router every turn goes through, ⌘K's included (docs/design/2026-10-06-core-boundary-next.md,
* "Devices", step 9). They answer the core through `DevicesPort` and reach it through `CoreApi`, so that
* they can run in a process of their own: a device that fails, hangs or leaks costs the devices, never a
* session.
*/
/** The frames the devices may send every window on this computer (`clients.sendLocal`): what a hand at
* this desk did on a dial, and a spoken task offered to the window's palette. Never to the cloud. */
export const DEVICE_WINDOW_FRAMES = [
'dial_open', 'dial_notification_read', 'dial_forked', 'dial_focus', 'dial_swarm', 'dial_scroll', 'dial_status',
'voice_route_request', 'dial_super_tab',
] as const
export type DeviceWindowFrame = { type: (typeof DEVICE_WINDOW_FRAMES)[number]; payload: Record<string, unknown> }
/** The frames the devices may send one window (`clients.sendToWindow`): a window bridge's ask, to the
* window that has the person's attention. */
export const DEVICE_BRIDGE_FRAMES = ['dial_selection', 'dial_visit', 'dial_form'] as const
export type DeviceBridgeFrame = { type: (typeof DEVICE_BRIDGE_FRAMES)[number]; payload: Record<string, unknown> }
/** Which window has the person's attention, as the local socket last heard (`app_focus` with a focus
* revision): where a spoken selection or visit goes (`voice`), and a New Harness form (`form`). */
export interface WindowFocus {
voice: { machineId: string; agentId: string; connId: string } | null
form: { machineId: string; connId: string } | null
}
/** A window's answer to a spoken task it was offered (`voice_route_reply`). */
export type VoiceRouteReply = { t: 'taken' } | { t: 'sent'; agentId: string } | { t: 'cancelled' }
/** The Devices tab (services/devices.ts): the devices on this computer, and a device's settings. Only
* the owner, on this computer or through the owner's own app, may manage them. */
export const DEVICES_REQUESTS = ['harness_devices_list', 'harness_device_settings', 'pet_preview', 'pet_apply', 'pet_reset', 'pet_status'] as const
/**
* The core's calls into the devices: what the windows on this computer said that the dial follows, the
* cards every device is sent, ⌘K, and stopping. Every one is a notice or a request the core never waits
* on in line: across a process, a hung devices process answers the fallbacks, never a frozen core.
*/
export interface DevicesPort {
/** A frame bound for the devices (`commander_event`, `commander_question`, `commander_question_close`):
* every one the core sends the Wi-Fi devices, as it is sent, so a dial cannot drift from them. */
card(frame: Record<string, unknown>): void
/** The window's tiles on its active tab, in tile order, and whether the window is in front. */
desk(agentIds: string[], foreground: boolean): void
/** The window's tabs, or null once it has gone. */
swarms(swarms: AppSwarms | null): void
/** The Swarms' cards for a Harness Pro (superTabs/inCore/cards.ts), whole; replayed to a dial that attaches. */
swarmCards(items: SwarmCard[]): void
/** One Lead's last message, for the recap a Harness Pro has open. */
swarmCardRecap(recap: LeadRecap): void
/** What the window still has unread, newest first. */
unread(items: UnreadNotification[]): void
/** The window moved to an agent. */
appFocus(machineId: string, agentId: string): void
/** The window looked at an agent. */
seen(agentId: string, readToken?: string): void
/** A window changing one device's settings. */
settings(id: string, patch: Record<string, unknown>): void
/** Which window has the person's attention now. */
windowFocus(focus: WindowFocus): void
/** A window's answer to a bridge's ask. */
windowReply(kind: 'selection' | 'visit' | 'form', connId: string, machineId: string, payload: Record<string, unknown>): void
/** A window's answer to a spoken task it was offered. */
voiceReply(voiceId: string, reply: VoiceRouteReply): void
/** A window left. */
windowGone(connId: string): void
/** ⌘K: which agent a typed task belongs to, on any of the owner's machines. */
routeTask(text: string): Promise<RouteAnswer>
/** ⌘K's send: the turn delivered on the agent's own machine, or refused with why. */
routeSend(agentId: string, text: string): Promise<SendResult>
/** The Wi-Fi device borrowing the dial's walk along the desk, through the core (`CoreApi.wifi.stepFocus`). */
stepFocus(direction: 'next' | 'previous', currentAgentId?: string): Promise<{ machineId: string; agentId: string } | 'no_agents'>
/** The Wi-Fi device borrowing the dial's stroke for the window's terminal. */
scroll(phase: 'down' | 'move' | 'up', dy: number, velocity: number): void
/** The engines the live agents run: the voice router's worker is one of them. */
engines(engines: string[]): void
/** Whether a device watches through the backend: the voice router keeps its worker warm meanwhile. */
commanders(connected: boolean): void
/** Let go of the serial ports and the lane, for a restart or a shutdown. */
stop(): Promise<void>
}
const DEVICES_UNAVAILABLE = 'the devices service is unavailable'
/**
* What the core gets when the devices fail: the dial and the window bridges hear nothing, ⌘K says so,
* picking no agent and sending nothing, the Wi-Fi device finds no desk to walk, and a shutdown goes on.
*/
export const DEVICES_FALLBACKS: PortFallbacks<DevicesPort> = {
card: undefined, desk: undefined, swarms: undefined, swarmCards: undefined, swarmCardRecap: undefined, unread: undefined, appFocus: undefined, seen: undefined,
settings: undefined, windowFocus: undefined, windowReply: undefined, voiceReply: undefined, windowGone: undefined,
routeTask: later({ agentId: '', machineId: '', name: '', confidence: 0, reason: DEVICES_UNAVAILABLE, candidates: [], weighed: 0, machines: 0, via: '' }),
routeSend: later({ ok: false, machine: '', reason: DEVICES_UNAVAILABLE }),
stepFocus: later('no_agents'), scroll: undefined, engines: undefined, commanders: undefined, stop: later(undefined),
}
/*
* The Wi-Fi device (services/wifi.ts, lib/autonomous-device/): a paired device that speaks its own
* protocol (docs/autonomous-device-integration.md) over an E2EE session the gateway holds, on its direct
* link or the relay. It runs beside the dials, in the devices' process (step 9, D3): the core tells it
* what the agents do and the requests its sessions bring, and it answers them through the core, which
* checks that each answer goes to the session it came from.
*/
/** What the core holds for the Wi-Fi device's service, said again each time it starts: every device
* session the gateway holds, which of them said their app's hello (served on, told to resync, as after a
* daemon restart), and the window that has the person's attention. */
export interface WifiResume {
sessions: Array<{ connId: string; client: RemoteClient }>
helloed: Array<{ connId: string; identity: string }>
focus: { machineId: string; agentId: string; connId: string } | null
}
/** A receipt the device asked for by `harness device receipt`, or the service is not there to say. */
export type WifiReceipt = { receipt: AutonomousDeviceReceipt | null } | { unavailable: true }
/** `harness autonomous-device addon`: what devices published, a proposal sent, or one read back
* (lib/autonomous-device/addons.ts); refused with the add-on layer's own code, or the service is not there. */
export const WIFI_ADDON_OPS = ['state', 'propose', 'proposal'] as const
export type WifiAddonOp = typeof WIFI_ADDON_OPS[number]
export type WifiAddon = { result: Record<string, unknown> } | { error: { code: string; message: string } } | { unavailable: true }
/** What the core lists for the Wi-Fi device, read in line while it answers a request: the agents as it
* shows them, the Store's evidence on each, and whether a window is attached to show one. */
export interface WifiView {
agents: AutonomousDeviceAgent[]
store: StoreAgent[]
hasWindow: boolean
}
/**
* The core's calls into the Wi-Fi device: its sessions and their requests, as the gateway hands them on,
* and what the agents do that it follows (cards, turns, live text, its own deliveries into the panes and
* the transcript lines that prove them). All notices but `receipt`, which a person asked for.
*/
export interface WifiPort {
/** A device session the gateway holds, as it changes (null: it lost its session). */
session(connId: string, client: RemoteClient | null): void
/** A device's request, as it arrived sealed and as its session opened it (null: it would not open).
* Settles once the service has taken it: what the core says after it is heard after it. */
request(connId: string, frame: Record<string, unknown>, opened: Record<string, unknown> | null): Promise<void>
/** A device's connection closed. */
dropped(connId: string): void
/** The owner unpaired a device here; its sessions are gone. */
revoked(identity: string): void
/** What the core holds for it (`WifiResume`), as it starts. Settles once the sessions are served again. */
resume(state: WifiResume): Promise<void>
/** A frame bound for the devices, as it is sent, with the turn's whole answer for a summary. */
card(frame: Record<string, unknown>, fullText?: string): void
turnStarted(agentId: string): void
turnEnded(agentId: string, aborted: boolean): void
/** An agent's live events, for the devices that subscribed to it. */
stream(agentId: string, events: readonly LiveEvent[]): void
/** A transcript line of an agent the device sent a prompt to, which proves what its turn did. */
transcript(agentId: string, sessionId: string, engine: string, line: string): void
/** Its own deliveries into the panes, as the pane's write lock moves them on (core/deviceInput.ts). */
delivery(event: AutonomousDeviceDelivery): void
dispatched(agentId: string, deliveryId: string, text: string, sessionId?: string): void
inputStatus(event: DeviceInputStatus): void
agentGone(agentId: string): void
/** A window moved to an agent (null: it left one), by its connection. Settles once it is applied. */
appFocus(machineId: string, agentId: string | null, connId: string): Promise<void>
/** A window opened the agent a device's Store preparation made. */
revealed(operationId: string, agentId: string): void
/** `harness device receipt`: what became of one of a device's requests. */
receipt(deviceId: string, idempotencyKey: string): Promise<WifiReceipt>
/** `harness autonomous-device addon`: an agent reads what devices published, or proposes to one. */
addon(op: WifiAddonOp, input: Record<string, unknown>): Promise<WifiAddon>
stop(): Promise<void>
}
/** The Wi-Fi device's doors, for a service that is not it: nothing is listed, sent, made or moved. */
export const WIFI_OFF: CoreApi['wifi'] = {
view: async () => ({ agents: [], store: [], hasWindow: false }),
submit: async () => {}, cancel: () => {}, started: () => {},
stop: async () => false, answer: async () => false,
create: async () => ({ ok: false, error: 'UNSUPPORTED' }),
stepFocus: async () => 'no_app', scroll: () => false, focusApp: () => false, reveal: () => {},
send: () => {}, hello: () => {}, joined: () => {}, ready: () => {}, unpaired: () => {}, focus: () => {},
transcripts: () => {}, watching: () => {}, streams: () => {},
}
/**
* What the core gets when the Wi-Fi device's service is off: its devices hear nothing (a request they sent
* is unanswered, which they retry with the same key, as after a lost frame) and `harness device receipt`
* says it is not running.
*/
export const WIFI_FALLBACKS: PortFallbacks<WifiPort> = {
session: undefined, request: later(undefined), dropped: undefined, revoked: undefined, resume: later(undefined), card: undefined,
turnStarted: undefined, turnEnded: undefined, stream: undefined, transcript: undefined, delivery: undefined,
dispatched: undefined, inputStatus: undefined, agentGone: undefined, appFocus: later(undefined), revealed: undefined,
receipt: later({ unavailable: true }), addon: later({ unavailable: true }), stop: later(undefined),
}
/*
* The gateway: the relay and its end-to-end encryption (docs/design/2026-10-06-core-boundary-next.md,
* "Relay and E2EE", step 10). It holds the backend link, the E2EE sessions and the keys; every remote
* client (a phone, a browser, another machine's desktop, a device) reaches the core through it, and every
* frame the core has for one leaves through it. The core speaks plaintext to it, and never sees a key.
*
* Unlike a service it is transport: what it tells the core (`GatewayEvents`) is who the remote clients
* are and what they asked, and what the core asks of it (`GatewayPort`) is to carry frames to them, sealed
* by its rules (which frames, to whom, what is refused unsealed), which stay the gateway's alone.
*/
/** What a remote client proved with its E2EE session: an owner's app or browser, or a device. */
export type RemoteRole = 'web' | 'device'
/**
* What the account's own apps away from this desk may ask of this machine and hear from it, beyond what an owner may
* (backendSocket.ts `remoteAppPolicy`). Set only on a Harness Team daemon, by the Swarm (superTabs/inCore/teamApps.ts):
* there the account is the Mac's owner's, and another person's Product Manager may run, holding people's private chats.
*/
export interface RemoteAppPolicy {
/** Why a request is refused, or null to answer it as for any owner. */
refuse(type: string, payload: Record<string, unknown>): { error: string; message: string } | null
/** A reply's payload as the apps may see it. */
reply(type: string, payload: Record<string, unknown>): Record<string, unknown>
/** An up-frame as the apps may hear it, or null to withhold it. */
event<F extends { agentId?: unknown; payload?: unknown }>(frame: F): F | null
/** Whether the apps' terminal streams only watch now: no input, paste or resize reaches a terminal, binary frames included
* (lib/terminalStreamManager.ts `watchOnly`). */
watchOnly(): boolean
/** Whether a session, by its agent id or its engine's session id, is closed to the apps: its open terminal streams close
* (lib/terminalStreamManager.ts `closedTo`). */
isConfidential(id: string): boolean
}
/** A remote client the gateway holds a session with, as the core may know it: its role, the label its
* identity was paired under (null for none) for naming it to the person, its identity's public key (the
* Wi-Fi device's requests are kept apart by it), and whether it is on a device's direct link rather than
* the relay. Nothing here is a secret. */
export interface RemoteClient {
role: RemoteRole
accountOwner?: boolean
/** Set for a session trusted only because this machine is shared with another account: that account's
* email ('' when an older store did not record it). A guest uses its own space and nothing of the
* owner's (docs/plans/2026-10-19-guest-machine-sharing-plan.md, core/guestPolicy.ts). */
guest?: string
label: string | null
identity: string
direct: boolean
/** The machine this session's identity was paired as, when it is one of the owner's machines (`kind: 'machine'`). */
machineId?: string
}
/** How a remote client's frame arrived: the backend's relay, or a paired client's own P2P channel. */
export type RemoteTransport = 'relay' | 'p2p'
/** The control frames only the backend sends, as the gateway hands them on once it has checked that the
* backend sent them (on its own address, in the clear, over the relay). */
export type BackendNotice =
| { type: 'desk_changed'; revision: number }
| { type: 'zoo_changed'; revision: number }
| { type: 'machines_changed'; reason: string }
| { type: 'device_keys_changed' }
| { type: 'connectors_changed'; revision: number }
/** Work waits for an agent of this machine's (backend lib/adapterWs.ts): its Swarm host reads that agent's deliveries now.
* Naming none, the server says it pushes them, and every list is read once (superTabs/host.ts PUSH_LEASE_MS). */
| { type: 'super_tab_deliveries'; tabId?: string; agentId?: string }
/** A Lead's terminal request waits for an agent of this machine (backend lib/swarmDeliveryPushes.ts): its Swarm host picks
* it up now rather than at its next poll (superTabs/terminal.ts). The backend's `__` frame, kept by name. */
| { type: '__terminal_waiting'; tabId: string; agentId: string }
/** The server renews the Swarm host's delivery push lease, each minute through Redis (backend lib/swarmDeliveryPushes.ts):
* the host keeps reading an idle worker's list only when told (superTabs/host.ts PUSH_LEASE_MS). A `__` frame, kept by name. */
| { type: '__deliveries_lease' }
/** A commit changed what this machine's Swarm host reads (backend lib/swarmHostPushes.ts): it reads its changes now. Naming
* none, the server says it pushes them, and the host reads only when told (superTabs/hostFeed.ts HOST_PUSH_LEASE_MS). */
| { type: 'swarm_host_changed'; tabId?: string; lastChangedAt?: number }
/** A Swarm the account is in changed (backend lib/swarmClientPushes.ts): this computer's windows read it again. Naming none,
* the server says it pushes them (desktop super_tabs/swarm_pushes.dart). */
| { type: 'swarm_changed'; tabId?: string; lastChangedAt?: number; parts?: Array<'main' | 'machine'> }
/** What a person has open on this computer, per surface (lib/windowSurfaces.ts). */
export type { LocalWindows, WindowSurface } from '../lib/windowSurfaces.js'
import type { LocalWindows, WindowSurface } from '../lib/windowSurfaces.js'
/** What the core asks of the gateway: everything bound for a remote client, and the link's state. */
export interface GatewayPort {
/** Optional, fixed-name counter to the gateway; no user payload or identifier. */
usageCounter?(metric: ProductUsageMetric): void
usageLaunch?(signal: ProductUsageLaunchSignal): void
/** Dial the backend: this daemon is signed in. */
connect(): void
/** Never dial: signed out, so nothing is sealed or queued for a link that will not open. */
serveThisComputerOnly(): void
/** Hold remote clients' frames, in order, until `openRequests`: the core is not ready to answer. */
holdRequests(): void
openRequests(): void
/** Whether the backend link is up. */
connected(): boolean
/** A frame for the web audience: sealed under the group key when it carries content, queued while the
* link is down. [guest]: the guest whose harness it is about, whose sessions get it sealed for each. */
broadcast(frame: Record<string, unknown>, guest?: string): void
/** A frame for the devices (the commander audience), sealed the same way. */
commander(frame: Record<string, unknown>): void
/** A notification for every browser signed in to the account (the user audience). */
user(frame: Record<string, unknown>): void
/** The answer to a remote client's request: to it alone, sealed when its type carries content, and a
* bare E2EE_REQUIRED when it cannot be. `connId` '' is the backend's own request. */
reply(connId: string, type: string, requestId: unknown, payload: Record<string, unknown>): void
/** A frame for one remote client, sealed to it; false when it holds no session. */
target(connId: string, type: string, payload: Record<string, unknown>): boolean
/** A terminal frame for one remote client, sealed to it, over its P2P channel when the stream moved
* there; false when it could not be sent. */
terminal(connId: string, type: string, payload: Record<string, unknown>): boolean
terminalBinary(connId: string, clear: TerminalBinaryClear): boolean
/** Share's frame to an observer: plaintext to the relay, sealed by Share itself. */
observer(connId: string, type: string, payload: Record<string, unknown>): boolean
/** A window opened on this computer: the backend counts it as the person's session at once, or when
* the link next comes up. */
windowOpened(surface: WindowSurface): void
/** The windows attached on this computer, per surface — tools (`harness pair`, the MCP server) are
* not windows and are not counted. */
localClients(windows: LocalWindows): void
/** A local connection's request the gateway answers (the E2EE pairings), answered back to it through
* `GatewayEvents.toLocal`. */
local(connId: string, frame: Record<string, unknown>): Promise<void>
/** The Wi-Fi device's answer or event for one of its sessions, sealed to it, over its direct link or the
* relay; false when that session is gone. */
device(connId: string, type: string, payload: Record<string, unknown>): boolean
/** Which identity's app said hello on a Wi-Fi device session (null: it left), so that the gateway can
* tell the device it was unpaired while its session still stands. */
deviceClient(connId: string, identity: string | null): void
stop(): Promise<void>
}
/** What the gateway tells the core. In the core's process these are calls; in the gateway's own, frames
* on the link the master started it with, which no other process can open. */
export interface GatewayEvents {
/** A remote client's request, opened and admitted. `role` is the session that sealed it: who asked is
* the gateway's word, and the core trusts nothing in the frame for it. Resolves once it is handled. */
frame(connId: string, frame: Record<string, unknown>, transport: RemoteTransport, role: RemoteRole): Promise<void> | void
/** A remote client's terminal bytes, opened. */
binary(connId: string, clear: TerminalBinaryClear): Promise<void> | void
/** A remote client gained a session (its role and label), or lost it (null). */
client(connId: string, client: RemoteClient | null): void
/** The relay says a client's connection closed: what it had open goes with it. */
disconnected(connId: string): Promise<void> | void
/** Share's observer, relayed: Share opens its own frames. */
observer(connId: string, type: string, payload: Record<string, unknown>): Promise<void> | void
/** A frame for a window on this computer that asked the gateway something (`GatewayPort.local`); with
* `connId` '', for every process attached here (the answer to the backend's own request, which the
* windows heard with every event before the gateway was its own part). */
toLocal(connId: string, frame: Record<string, unknown>): void
/** The backend link's state, as it changes. */
status(connected: boolean): void
/** The link went down: every remote client with it. */
linkDown(): void
/** How many devices watch this machine, and how many of them render it now (null: the backend does not
* say). `recheck`: the presence was asked about again, though it may not have changed. */
commanders(count: number, active: number | null, recheck?: boolean): void
/** A device attached: the live state is sent again for it. */
commanderJoined(): void
/** The backend's word on this machine: its name, the account's private grid. A key that is absent is
* unchanged; null is "none". */
meta(meta: { name?: string | null; gridName?: string | null }): void
/** The account's other changes, for the windows on this computer. */
notice(notice: BackendNotice): void
/** This machine was removed from the account, or its session ended: stop for good. */
revoked(): void
/** Another computer holds this machine: stop for good, keeping the session. */
busy(): void
/** A Wi-Fi device's request (`autonomous_device_request`), as it arrived sealed and as the session that
* sealed it opened it (null when it could not be opened, or was not the device's to send). */
device(connId: string, frame: Record<string, unknown>, opened: Record<string, unknown> | null): Promise<void> | void
/** A paired identity was unpaired: the Wi-Fi device service forgets it. */
deviceRevoked(identity: string): void
/** Something the windows on this computer show of the account's devices (the device key log's notices). */
toWindows(frame: Record<string, unknown>): void
/** What a shared tab's relay said (`GatewayOps.tabRelay`), for Agent Messages. */
tabFrame(event: TabFrame): void
}
/**
* The fleet's lane to the owner's other machines (device/deviceLink.ts), sealed by the gateway, which holds
* this machine's E2EE identity (the one `harness link connect` proves knowledge against). The lane keeps
* which machines have a session; the session itself, its keys and its counters, is the gateway's, one per
* machine. A gateway that restarted holds none and says so (`lost`): the lane then starts one again, and
* sends nothing for that machine in the clear meanwhile.
*/
export interface LaneSeal {
/** Start a session with a linked machine, pinned to the key `harness link connect` left for it (`peerPub`,
* base64): the hello to send it, in the clear. Replaces any session that machine had. Rejects when the
* gateway cannot start one (it is not running). */
hello(machineId: string, peerPub: string): Promise<Record<string, unknown>>
/** The machine's welcome to that hello: true once the session is up. */
welcome(machineId: string, payload: Record<string, unknown>): Promise<boolean>
/** The machine's new keys, for a session that is up. */
rekey(machineId: string, payload: Record<string, unknown>): Promise<void>
/** A frame for the machine, sealed as its session seals that type (a type it does not seal goes as it is). */
seal(machineId: string, frame: Record<string, unknown>): Promise<LaneSealed>
/** A sealed frame from the machine, opened; `unreadable` when it does not open (stale, forged, garbled);
* `unknownEpoch` when it is sealed under a group epoch none of the machine's sessions here ever held: the
* far daemon restarted, and the session here is with a process that is gone. */
open(machineId: string, frame: Record<string, unknown>): Promise<LaneOpened>
/** The lane is done with the machine's session. */
drop(machineId: string): void
}
export type LaneSealed = { frame: Record<string, unknown> } | { lost: true }
export type LaneOpened = { frame: Record<string, unknown> } | { unreadable: true } | { unknownEpoch: true } | { lost: true }
/** A service with no lane of the core's: it starts no session and seals nothing, never sends in the clear. */
export const LANE_OFF: LaneSeal = {
hello: () => Promise.reject(new Error('no lane: this process holds no E2EE identity')),
welcome: async () => false,
rekey: async () => {},
seal: async () => ({ lost: true }),
open: async () => ({ lost: true }),
drop: () => {},
}
/** An HTTP answer for the daemon's own routes (`harness pair`, `harness devices`, …), as the hook server sends it. */
export interface HttpAnswer {
status: number
body: Record<string, unknown>
/** A busy or failing answer's Retry-After, when it had one (gateway/accountHttp.ts). */
retryAfterMs?: number
}
/** What the core's status reads of the relay: the machine's E2EE fingerprint, its pairings and the one
* waiting to pair. */
export interface GatewayStatus {
fingerprint: string | null
pairs: Array<Record<string, unknown>>
pending: Record<string, unknown> | null
}
/** The account's sign-in as the gateway's device key log reads it: no credential, only which sign-in. */
export interface GatewayAccount {
/** The machine id the backend gave this sign-in; null signed out. */
machineId: string | null
/** Which sign-in by hand this is, and the account it was made to (lib/authSession.ts `signInOf`), or null. */
signIn: { epoch: string; adopted: boolean; at: number | null; acct?: string } | null
autonomousEnv?: string
}
/** The gateway's last successful machine list, scoped to the account that fetched it. No credentials. */
export interface GatewayMachines {
owner: string | null
body: Record<string, unknown> | null
fetchedAt: number
}
/** A Wi-Fi device operation refused, with the code the device's local API answers it under. */
export interface GatewayRefusal {
code: string
message: string
}
/**
* The daemon's own commands about the keys, which the gateway holds: `harness pair`, `unpair`,
* `remote-password`, `link connect`, `group`, `devices`, and the Wi-Fi device's pairing. Each answers as
* the hook server's route does; while the gateway is down, a 503.
*/
export interface GatewayOps {
/** Account HTTP and its cache live with the network, outside the session core. */
backend(method: string, path: string, body?: unknown): Promise<HttpAnswer>
machines(fallback?: boolean): Promise<HttpAnswer>
mintGridName(): Promise<string | null>
status(): Promise<GatewayStatus>
pair(code: string): Promise<HttpAnswer>
listPairs(): Promise<HttpAnswer>
revoke(id: string): Promise<HttpAnswer>
revokeAll(): Promise<HttpAnswer>
setRemotePassword(password: string): Promise<HttpAnswer>
clearRemotePassword(): Promise<HttpAnswer>
remotePasswordStatus(): Promise<HttpAnswer>
trustLinkedPeer(peer: { pub: string; machineId: string; label: string }): Promise<HttpAnswer>
groupList(): Promise<HttpAnswer>
groupSync(): Promise<HttpAnswer>
groupRemove(selector: string): Promise<HttpAnswer>
devicesList(): Promise<HttpAnswer>
devicesRemove(pub: string): Promise<HttpAnswer>
devicesHistory(): Promise<HttpAnswer>
/** `confirm`: "It's mine" for the one key named, shared with the account's other devices. */
devicesDismiss(body: { pub?: string; pubs?: string[]; baseline?: boolean; confirm?: boolean }): Promise<HttpAnswer>
devicesRebaseline(confirm: boolean, head?: { seq: number; hash: string }): Promise<HttpAnswer>
/** The Wi-Fi device's direct links: discovered devices, pairing one, and its pairings. A refusal is an
* answer (`{ refused }`), as the device's local API words it. */
wifi(request: { op: 'discover' | 'pair' | 'pairStatus' | 'list' | 'revoke'; device?: string; code?: string; id?: string }):
Promise<{ result: Record<string, unknown> } | { refused: GatewayRefusal }>
/** The Wi-Fi device service is up (its direct links start) or gone (they stop). */
wifiService(on: boolean): void
/** A Wi-Fi device asked to be unpaired, over its own authenticated session. */
revokeIdentity(identity: string): void
/** The account's sign-in, as it is now (after start-up recorded which sign-in it is); the device key log
* registers this machine with it. */
account(account: GatewayAccount): void
/** The owner's machines the backend last said were online, for the trust group's exchanges; null when
* the list is not the backend's. */
reachable(machineIds: string[] | null): void
/** The fleet's lane's sessions (`core.account.lane`). */
lane: LaneSeal
/** Share's owner's signature on a welcome, with this machine's identity (`core.account.observerKey`). */
observerKey: ObserverKey
/** Shared tabs' rosters signed and their sessions, with this machine's identity (`core.account.tabKey`). */
tabKey: TabKey
/** Shared tabs' relay sockets (`core.account.tabRelay`); what they hear is `GatewayEvents.tabFrame`. */
tabRelay: TabRelay
/** The account's connected services sealed for its machines (`core.account.connectorVault`). */
connectorVault: ConnectorVault
/** Machines shared across accounts, made to hold exactly what the shared-machines service says
* (gateway/sharedTrust.ts): the ones shared with this account pinned, the machines of the accounts this
* one is shared with trusted; a part left out stays as it is. Answers how many of each it holds. */
sharedTrust(desired: { pins?: SharedTrustPeer[]; keys?: SharedTrustPeer[] }): Promise<{ pins: number; keys: number }>
}
/** A window on this computer working on another of the owner's machines, through the relay: what the
* local socket asks of the gateway for it (lib/remoteRelay.ts `RemoteRelayPool`, or its link). */
export interface WindowRelaySession {
send(frame: Record<string, unknown>): Promise<void>
sendBinary(clear: TerminalBinaryClear): Promise<void>
detach(): void
}
export interface WindowRelaySink {
sendFrame(frame: Record<string, unknown>): boolean
sendBinary(frame: Uint8Array): boolean
}
export interface WindowRelay {
acquire(machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>, sink: WindowRelaySink,
onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
acquireIsolated(machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>, sink: WindowRelaySink,
onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
invalidate(machineId: string): void
invalidateIsolated(machineId: string): void
/** A window here watching, read-only, a harness someone shared with this account (sharing/relay.ts, the
* Share relay's own socket, `/api/observer-ws`). Fails with the close the window gets: 4403 when the
* share ended or was never there, 1013 when it could not be reached just now. The gateway's has it; a
* bare pool of sessions to other machines (lib/remoteRelay.ts) does not, and shares nothing. */
acquireShare?(machineId: string, shareId: string, sink: WindowRelaySink,
onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
}
export interface StorePort {
dshMaterialize(request: DshMaterializeRequest): Promise<DshMaterializeAnswer>
dshLaunch(request: DshLaunchRequest): Promise<DshLaunchAnswer>
}
export const STORE_FALLBACKS: PortFallbacks<StorePort> = { dshMaterialize: later(FAIL), dshLaunch: later(FAIL) }
export const STORE_OFF: StorePort = {
dshMaterialize: () => Promise.reject(new ServiceUnavailableError('store')),
dshLaunch: () => Promise.reject(new ServiceUnavailableError('store')),
}
/** Each port is filled by the service that owns it when that service starts, and is null while the
* service is off: the core never waits on one. */
export interface CorePorts {
usage: UsagePort | null
store: StorePort | null
search: SearchPort | null
viewers: ViewersPort | null
models: ModelsPort | null
workspaces: WorkspacesPort | null
messages: MessagesPort | null
devices: DevicesPort | null
wifi: WifiPort | null
monitor: MonitorPort | null
orchestrator: OrchestratorPort | null
sharing: SharingPort | null
recaps: RecapsPort | null
agentCleanup: AgentCleanupPort | null
cloud: CloudPort | null
superTabs: SuperTabsPort | null
sharedMachines: SharedMachinesCorePort | null
}
export function emptyPorts(): CorePorts {
return { usage: null, store: null, search: null, viewers: null, models: null, workspaces: null, messages: null, devices: null, wifi: null, monitor: null, orchestrator: null, sharing: null, recaps: null, agentCleanup: null, cloud: null, superTabs: null, sharedMachines: null }
}
export interface CoreApiDeps {
terminals?: TerminalsPort
conversations?: ConversationReads
dataDir: string
registry: Pick<typeof registry, 'list' | 'byAgent' | 'resolve' | 'advertised' | 'terminalAvailable'>
stoppedAgents: Pick<StoppedAgentStore, 'list' | 'ids'>
databaseHistory: CoreApi['transcripts']['databaseHistory']
syncSession: CoreApi['agents']['sync']
runtimeModels: CoreApi['agents']['runtimeModels']
viewerChanged: CoreApi['clients']['viewerChanged']
viewerFrame: CoreApi['clients']['viewerFrame']
gridNamed: CoreApi['clients']['gridNamed']
gridModelsChanged: CoreApi['clients']['gridModelsChanged']
dshInstallStatus: CoreApi['clients']['dshInstallStatus']
mintGridName: CoreApi['account']['mintGridName']
accessToken: CoreApi['account']['accessToken']
lane: CoreApi['account']['lane']
observerKey: CoreApi['account']['observerKey']
tabKey: CoreApi['account']['tabKey']
tabRelay: CoreApi['account']['tabRelay']
connectorVault: CoreApi['account']['connectorVault']
observer: CoreApi['clients']['observer']
privateGridName: CoreApi['account']['privateGridName']
machineName: CoreApi['account']['machineName']
backend: CoreApi['account']['backend']
onNotice: CoreApi['account']['onNotice']
create: CoreApi['agents']['create']
creationStatus?: CoreApi['agents']['creationStatus']
dsh: CoreApi['agents']['dsh']
windows: CoreApi['clients']['windows']
daemon: DaemonAddress
runtimeProfile: CoreApi['agents']['runtimeProfile']
setRuntime: CoreApi['agents']['setRuntime']
fork: CoreApi['agents']['fork']
turns: CoreApi['turns']
questions: CoreApi['questions']
machine: CoreApi['machine']
activityText: CoreApi['agents']['activityText']
activitySnapshot?: CoreApi['agents']['activitySnapshot']
/** Whether each agent works now (`activity`); absent, no agent is reported. */
activity?: CoreApi['agents']['activity']
/** One line on what each agent does (`summaries`); absent, none is given. */
summaries?: CoreApi['agents']['summaries']
/** One `agent_close` (core/agents/close.ts), for `closeStarted`; absent, a service closes nothing. */
closeAgent?: (request: AgentCloseRequest) => Promise<AgentCloseResult>
/** When an agent's conversation last moved (lib/transcriptActivity.ts), for `lastActivity`. */
activityAt?: (session: RegisteredSession) => Promise<number | null>
/** A resume of a stopped agent (core/agents/lifecycle.ts `resumeAgent`), for `keepLeadAlive`. */
resumeAgent?: (agentId: string) => Promise<{ ok: true } | { ok: false; error: string; detail?: string }>
/** The Swarm's `closeSwarm`, `keepLeadAlive` and `closeMember` (superTabs/inCore/agents.ts), built on what the core
* reads its agents by; absent while the Swarm is off, and then the core offers none of them. */
swarmAgents?: (deps: SwarmAgentDeps) => SwarmAgents
signedIn: CoreApi['account']['signedIn']
environment: CoreApi['account']['environment']
machines: CoreApi['account']['machines']
/** Where the devices' frames go: every window on this computer, or one. Only the devices' own frame
* types reach these (`createCoreApi`). */
sendLocal(frame: { type: string; payload: Record<string, unknown> }): void
sendToWindow(connId: string, frame: { type: string; payload: Record<string, unknown> }): boolean
hasWindow: CoreApi['clients']['hasWindow']
devicesChanged: CoreApi['clients']['devicesChanged']
dialWatching: CoreApi['clients']['dialWatching']
/** The Wi-Fi device's doors (core/wifi.ts). */
wifi: CoreApi['wifi']
/** The cloud agents' doors (core/agents/cloud.ts). */
cloud?: CloudCore
/** The Super Tab service's door (superTabs/inCore/attention.ts). */
superTabs?: SuperTabsCore
/** The devices' way to the Super Tab service's card requests. */
superTabRequest?: CoreApi['superTabRequest']
/** The running cloud harnesses as list rows (`agents.cloud`). */
cloudRows?: () => RegisteredSession[]
lastTurn: CoreApi['transcripts']['lastTurn']
nativeTurns?: NativeTurnRead
/** Where a turn's cards and recaps go: the devices, and the apps. Only their own frame types reach these. */
turnCard: CoreApi['clients']['turnCard']
turnSummary: CoreApi['clients']['turnSummary']
log?: (line: string) => void
}
export function createCoreApi({
dataDir, registry, stoppedAgents, databaseHistory, syncSession, runtimeModels, viewerChanged,
gridNamed, gridModelsChanged, dshInstallStatus, mintGridName, accessToken, lane, observerKey, tabKey, tabRelay, connectorVault, observer, privateGridName, machineName, backend, onNotice,
runtimeProfile, setRuntime, fork, create, creationStatus, dsh, windows, daemon, turns, questions, terminals = TERMINALS_OFF, conversations = CONVERSATIONS_OFF, viewerFrame, machine, activityText, activitySnapshot, activity, summaries,
closeAgent, activityAt, resumeAgent, swarmAgents,
signedIn, environment, machines, sendLocal, sendToWindow, hasWindow, devicesChanged, dialWatching, wifi, cloud, superTabs, superTabRequest, cloudRows, lastTurn, nativeTurns, turnCard, turnSummary,
log = (line) => console.warn(line),
}: CoreApiDeps): CoreApi {
// The devices reach the windows through these alone, and only with their own frames: a devices process
// speaks to the core as a service, and what it may put in front of a person is decided here, not there.
const windowFrames = new Set<string>(DEVICE_WINDOW_FRAMES)
const bridgeFrames = new Set<string>(DEVICE_BRIDGE_FRAMES)
const refused = (type: unknown): void => log(`[services] the devices sent a window ${String(type).slice(0, 40)}, which is not theirs to send`)
// The recaps reach the devices and the apps through their own two doors, and only with their own frames.
const refusedRecap = (type: unknown): void => log(`[services] the recaps sent ${String(type).slice(0, 40)}, which is not theirs to send`)
return {
dataDir,
terminals,
machine,
conversations,
agents: {
all: () => [...registry.list(), ...stoppedAgents.list()],
stopped: async id => !registry.byAgent(id) && stoppedAgents.list().some(s => s.agentId === id),
gone: async id => !registry.byAgent(id) && !stoppedAgents.ids().includes(id),
live: () => registry.list(),
displayName: projectDisplayName,
byAgent: (agentId) => registry.byAgent(agentId),
resolve: (id) => registry.resolve(id),
advertised: () => registry.advertised(),
...(cloudRows ? { cloud: cloudRows } : {}),
terminalAvailable: (agentId) => registry.terminalAvailable(agentId),
sync: syncSession,
runtimeModels,
runtimeProfile,
setRuntime,
fork,
create,
...(creationStatus ? { creationStatus } : {}),
dsh,
activityText,
activitySnapshot,
activity: activity ?? (async () => ({})),
summaries: summaries ?? (async () => ({})),
// The Swarm's own close and reopen (superTabs/inCore/agents.ts), handed in while it is on.
...swarmAgents?.({ byAgent: id => registry.byAgent(id), stoppedIds: () => stoppedAgents.ids(), closeAgent, resumeAgent, creationStatus }),
// Decided here, not in the service: whatever the cleanup asks, from its process or this one, the core closes only
// a harness another agent started, the conversation it reviewed (`agent_close`'s identity), and keeps it.
closeStarted: async (agentId, mode) => {
const session = registry.byAgent(agentId)
if (!session) return { error: 'AGENT_CHANGED' }
if (session.startedBy !== 'agent') return { error: 'NOT_AGENT_STARTED' }
if (!closeAgent) return { error: 'UNSUPPORTED' }
return closeAgent({ agentId, sessionId: session.sessionId, createdAt: new Date(session.registeredAt).toISOString(), mode })
},
lastActivity: async (agentId) => {
const session = registry.byAgent(agentId)
return session && activityAt ? activityAt(session) : null
},
},
turns,
questions,
transcripts: { databaseHistory, lastTurn, ...(nativeTurns ? { nativeTurns } : {}) },
account: { mintGridName, accessToken, lane, observerKey, tabKey, tabRelay, connectorVault, privateGridName, machineName, backend,
identity: accountIdentity(backend), onNotice, signedIn, environment, machines },
clients: {
viewerChanged, gridNamed, gridModelsChanged, dshInstallStatus, windows, observer, hasWindow, devicesChanged, dialWatching,
// A viewers process speaks to the core as a service: what it may send a client is a viewer stream's
// frame, decided here, never whatever it names.
viewerFrame: (connId, type, payload) => VIEWER_UP_TYPES.has(type) && viewerFrame(connId, type, payload),
sendLocal: (frame) => {
if (windowFrames.has(frame?.type)) sendLocal(frame)
else refused(frame?.type)
},
sendToWindow: (connId, frame) => {
if (bridgeFrames.has(frame?.type)) return sendToWindow(connId, frame)
refused(frame?.type)
return false
},
turnCard: (frame) => { if (TURN_CARD_TYPES.has(frame?.type)) turnCard(frame); else refusedRecap(frame?.type) },
turnSummary: (frame) => { if (TURN_SUMMARY_TYPES.has(frame?.type)) turnSummary(frame); else refusedRecap(frame?.type) },
},
daemon,
wifi,
...(cloud ? { cloud } : {}),
...(superTabs ? { superTabs } : {}),
...(superTabRequest ? { superTabRequest } : {}),
}
}