Skip to content

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.

6.8 KB
Raw Blame
/**
 * Tunnel envelope types for the inverted WS transport.
 *
 * The inverted chain is: node ─dial▶ manager ─dial▶ backend; web/device ─dial▶ backend.
 * The inner "frame" is the existing client/server WS message ({ type, dbSessionId?, payload? }) —
 * opaque at the transport layer. These envelopes wrap it as it is tunnelled up/down the chain and
 * as it crosses backend instances via Redis (see lib/bus.ts).
 *
 * Directions:
 *  - up   = node → manager → backend → clients (brain events, acks)
 *  - down = clients → backend → manager → node (chat messages, control)
 */

/** The inner WS message (existing ClientEvent / BrainEvent shape). Opaque here. */
export type Frame = Record<string, unknown>

// ── Frames on the manager↔backend socket (multiplexed: many agents over one socket) ──────────────

/** node/brain event travelling toward clients. `machineId` (= routing key, sha256(apiKey)[:32]) carried because the socket is multiplexed. */
export interface UpEnvelope {
  t: 'up'
  machineId: string
  /** origin client connId to skip when re-delivering (preserves broadcastToOthers). */
  excludeConnId?: string
  /** deliver to web/UI sockets (default true when absent). false = device-only (forwardToCommander). */
  webEligible?: boolean
  /** deliver to device/commander sockets (COMMANDER_FORWARD set, or curated commander frames). */
  commanderEligible?: boolean
  frame: Frame
}

/** client message travelling toward the node. */
export interface DownEnvelope {
  t: 'down'
  machineId: string
  /** originating client connId (so the node can tag its emitted events with excludeConnId). */
  connId: string
  frame: Frame
}

/** manager tells its backend a node connected/disconnected → backend (un)subscribes down:{machineId}.
 *  `app_register`/`app_unregister` are the app-proxy variant, sent on the APP-pool socket (or the control
 *  socket when no dedicated app pool) → backend (un)subscribes appdown:{machineId} on that socket. */
export interface RegisterEnvelope {
  t: 'register' | 'unregister' | 'app_register' | 'app_unregister'
  machineId: string
}

/** manager identifies itself + advertises capacity on connect and on heartbeat. */
export interface HelloEnvelope {
  t: 'hello'
  managerId: string
  capacity?: number
  nodeCount?: number
  // The manager→backend pool's CONTROL socket sets this; the backend subscribes mgr:{managerId} only
  // for control sockets, so provisioning isn't forwarded once per pool socket.
  control?: boolean
  // Set by the manager's dedicated APP-pool sockets (cosmetic/observability — routing is driven by the
  // app_register frame + machineId, not this flag).
  app?: boolean
}

export interface PingEnvelope {
  t: 'ping'
}

/** backend→manager provisioning command over the manager socket (Phase 3; replaces control HTTP).
 *  `app_create`/`app_delete` register/remove a public app deployment (subdomain → node app port). */
export interface ProvisionEnvelope {
  t: 'provision'
  requestId: string
  cmd: 'create' | 'start' | 'stop' | 'destroy' | 'app_create' | 'app_delete'
  payload: Record<string, unknown>
}

// ── App-proxy tunnel: transparent HTTP/WS reverse proxy for public app hosting, streamed over the
//    manager socket so the backend never needs the manager's address. Multiplexed by `streamId`
//    (one stream = one client connection). down = backend→manager; up = manager→backend.
export interface AppReqEnvelope {
  t: 'app_req'
  streamId: string
  subdomain: string
  method: string
  url: string
  headers: Record<string, string | string[] | undefined>
}
export interface AppBodyEnvelope {
  t: 'app_body' | 'app_res_body'
  streamId: string
  chunk?: string // base64
  end?: boolean
}
export interface AppResEnvelope {
  t: 'app_res'
  streamId: string
  status: number
  headers: Record<string, string | string[] | undefined>
}
export interface AppWsOpenEnvelope {
  t: 'app_ws_open'
  streamId: string
  subdomain: string
  url: string
  headers: Record<string, string | string[] | undefined>
}
export interface AppWsMsgEnvelope {
  t: 'app_ws_msg'
  streamId: string
  data: string // base64
  binary: boolean
}
export interface AppWsCloseEnvelope {
  t: 'app_ws_close'
  streamId: string
  code?: number
  ok?: boolean
}
export interface AppAbortEnvelope {
  t: 'app_abort'
  streamId: string
  reason?: string
}
export type AppDownFrame = AppReqEnvelope | AppBodyEnvelope | AppWsOpenEnvelope | AppWsMsgEnvelope | AppWsCloseEnvelope | AppAbortEnvelope
export type AppUpFrame = AppResEnvelope | AppBodyEnvelope | AppWsMsgEnvelope | AppWsCloseEnvelope | AppAbortEnvelope

/** manager→backend provisioning result. */
export interface ProvisionResultEnvelope {
  t: 'provision_result'
  requestId: string
  ok: boolean
  data?: unknown
  error?: string
}

/** backend informs the node of its current client counts so it can gate event buffering/replay. */
export interface ClientsEnvelope {
  t: 'clients'
  machineId: string
  ui: number
  commander: number
}

export type ManagerFrame =
  | UpEnvelope
  | DownEnvelope
  | RegisterEnvelope
  | HelloEnvelope
  | PingEnvelope
  | ClientsEnvelope
  | ProvisionResultEnvelope // manager → backend (reply to a ProvisionEnvelope sent down)
  | AppResEnvelope // app-proxy tunnel: manager → backend (response head/body/ws/abort), keyed by streamId
  | AppBodyEnvelope
  | AppWsMsgEnvelope
  | AppWsCloseEnvelope
  | AppAbortEnvelope

// ── Frames on the node↔manager socket (single machine per socket: machineId implicit) ────────────────

export type NodeUpFrame = Omit<UpEnvelope, 'machineId'>
export type NodeDownFrame = Omit<DownEnvelope, 'machineId'>
export type NodeFrame = NodeUpFrame | NodeDownFrame | ClientsEnvelope | PingEnvelope

// ── Redis bus payloads (machineId is encoded in the channel name, not the body) ────────────────────

export interface UpBusMsg {
  excludeConnId?: string
  webEligible?: boolean
  commanderEligible?: boolean
  // Deliver ONLY to the commander socket whose resolved deviceId matches (device-targeted push, e.g.
  // `device_revoked`). Absent ⇒ normal per-machine fan-out.
  targetDeviceId?: string
  // Deliver ONLY to the client socket with this connId (adapter-targeted push: E2EE pairing/welcome
  // and per-client RPC replies). Absent ⇒ normal per-machine fan-out.
  targetConnId?: string
  /** Optional kind constraint for connId-targeted traffic. Terminal streams are web/Desktop-only. */
  targetKind?: 'web' | 'commander'
  frame: Frame
  // Publisher's PROCESS_ID — the origin instance already delivered to its local clients directly, so its
  // own Redis loopback delivery is skipped (chat-up local fast-path). Absent on legacy/other publishers.
  originPid?: string
}

export interface DownBusMsg {
  connId: string
  frame: Frame
}