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
/**
* Delivered turns: text a feature writes into an agent under a delivery id of its own, and what becomes of
* it. The Wi-Fi device, Agent Messages and the orchestrator each deliver their turns this way, one path for the
* three (docs/design/2026-10-06-core-boundary-next.md, "Experimental features: move only"). It is what
* lets a feature that delivers turns run in a process of its own: before, each was a slot on the socket
* (`onMessage`, `onCancelOrchestratorMessage`, `orchestratorDelivery`, `teamDelivery`) that only code in
* the core's process could call.
*
* In the core's process a service delivers through `turns` (`CoreApi.turns`) and hears every delivery's
* progress, as the socket's features always did: each ignores the ids that are not its own. A service in its
* own process delivers by asking the core (`answer`, services/turnsLink.ts) and hears only its own
* deliveries, told to it until it has them: a delivery it made is its business and no other process's.
*/
import type { CoreApi, TurnDelivery } from './api.js'
type Payload = Record<string, unknown>
/** The most deliveries held while the core starts: Agent Messages' mailbox resumes a few at most. */
export const HELD_DELIVERIES = 1_000
/** The most deliveries whose maker is remembered: past it the oldest is forgotten, and what becomes of it
* is told to no process. A delivery settles within minutes (its queue item lives five), and a process
* makes a few a minute. */
export const KEPT_DELIVERERS = 10_000
/** A service must keep checking authority while a turn waits for an idle terminal. */
export const DELIVERY_LEASE_MS = 3_000
const guarded = (id: string) => id.startsWith('team:service:')
const owned = (service: string, id: string) => id.startsWith(`team:service:${service}:`) && id.length <= 240
export interface DeliveriesDeps {
/** Write the text into the agent under the delivery id (core/input.ts `submitAgent`). */
submit(agentId: string, text: string, deliveryId: string): void
/** Take back a delivery not yet being written (`SessionInputController.cancelDelivery`). */
cancel(deliveryId: string): boolean
/** Tell a service in its own process what became of a delivery it made. */
tell(service: string, event: TurnDelivery): void
/** The services in their own processes that may deliver turns: writing into an agent is no other's to ask. */
deliverers: ReadonlySet<string>
log?: (line: string) => void
now?: () => number
}
const text = (value: unknown): string => (typeof value === 'string' ? value : '')
export function createDeliveries(deps: DeliveriesDeps) {
const log = deps.log ?? ((line: string) => console.warn(line))
const listeners = new Set<(event: TurnDelivery) => void>()
const now = deps.now ?? Date.now
const leases = new Map<string, Map<string, number>>()
const lease = (service: string, input: unknown): boolean => {
if (!deps.deliverers.has(service) || !input || typeof input !== 'object' || Array.isArray(input)) return false
const entries = Object.entries(input)
if (entries.length > HELD_DELIVERIES || entries.some(([id, until]) => !owned(service, id) || typeof until !== 'number' || !Number.isFinite(until))) return false
const ceiling = now() + DELIVERY_LEASE_MS
leases.set(service, new Map(entries.map(([id, until]) => [id, Math.min(until as number, ceiling)])))
return true
}
/** Which process made each delivery, oldest first. */
const makers = new Map<string, string>()
/**
* What was delivered before the core's input was wired (`ready`), in order. Agent Messages' mailbox resumes
* its queue on a timer as soon as it starts, in the core's process or in its own, and the socket held such a
* turn back with "Agent input is not ready" until then; dropped, it would read as written and never be.
*/
let held: Array<{ agentId: string; text: string; deliveryId: string }> | null = []
const submit = (agentId: string, content: string, deliveryId: string): void => {
if (!held) { deps.submit(agentId, content, deliveryId); return }
held.push({ agentId, text: content, deliveryId })
if (held.length > HELD_DELIVERIES) {
const dropped = held.shift()!
settled({ deliveryId: dropped.deliveryId, sessionId: dropped.agentId, state: 'rejected', reason: 'queue_full' })
}
}
/** Take back a delivery still held, as the input would one still queued, or ask the input. */
const cancel = (deliveryId: string): boolean => {
const at = held?.findIndex((delivery) => delivery.deliveryId === deliveryId) ?? -1
if (at < 0) return deps.cancel(deliveryId)
const [taken] = held!.splice(at, 1)
settled({ deliveryId, sessionId: taken.agentId, state: 'rejected', reason: 'cancelled' })
return true
}
/** Deliveries from a person's message, which close a question open on the pane, until they settle. */
const answering = new Map<string, { writtenAt?: number }>()
const answers = (writtenAt: unknown) => Number.isFinite(writtenAt) ? { writtenAt: writtenAt as number } : {}
const settled = (event: TurnDelivery): void => {
if (event.state !== 'queued') answering.delete(event.deliveryId)
for (const listener of listeners) {
try { listener(event) } catch (error) {
log(`[deliveries] a listener failed on ${event.deliveryId.slice(0, 40)} · ${error instanceof Error ? error.message : String(error)}`)
}
}
const maker = makers.get(event.deliveryId)
if (maker) deps.tell(maker, event)
}
const turns: Pick<CoreApi['turns'], 'deliver' | 'cancelDelivery' | 'onDelivery' | 'leaseDeliveries'> = {
deliver: (agentId, content, deliveryId, options) => {
if (options?.answersQuestion) answering.set(deliveryId, answers(options.writtenAt))
submit(agentId, content, deliveryId)
},
cancelDelivery: (deliveryId) => cancel(deliveryId),
onDelivery: (listener) => {
listeners.add(listener)
return () => { listeners.delete(listener) }
},
leaseDeliveries: async (service, input) => lease(service, input),
}
return {
/** The delivery members of the core's own `CoreApi`, for the services in its process. */
turns,
/** Null leaves older delivery namespaces to their existing policy. An unknown
* guarded ID is denied, including after a core restart forgets all leases. */
canWrite(deliveryId: string): boolean | null {
if (!guarded(deliveryId)) return null
const service = deliveryId.split(':')[2]
return (leases.get(service)?.get(deliveryId) ?? 0) > now()
},
/** The delivery, when it is unsettled and came from a person's message (`DeliveryOptions.answersQuestion`), else null. */
answersQuestion: (deliveryId: string): { writtenAt?: number } | null => answering.get(deliveryId) ?? null,
/** The core's input says what became of a delivery: every listener here hears it, each guarded, and the
* process that made it is told. A listener that throws costs that listener the event, never the input
* that said it or another listener. */
settled,
/** The core's input is wired: what was held is written, in order, and the rest as it comes. */
ready(): void {
const waiting = held ?? []
held = null
for (const delivery of waiting) deps.submit(delivery.agentId, delivery.text, delivery.deliveryId)
},
/** A service in its own process delivering a turn, or taking one back (`service_query`): null when the
* query is not one of these. Refused for a service that is not a deliverer. */
answer(service: string, query: string, payload: Payload): Payload | null {
if (query !== 'deliver' && query !== 'cancel_delivery' && query !== 'lease_deliveries') return null
if (!deps.deliverers.has(service)) return { error: 'NOT_A_DELIVERER' }
if (query === 'lease_deliveries') return { leased: lease(service, payload.leases) }
const deliveryId = text(payload.deliveryId)
if (!deliveryId) return { error: 'INVALID_DELIVERY' }
if (guarded(deliveryId) && !owned(service, deliveryId)) return { error: 'INVALID_DELIVERY' }
if (query === 'cancel_delivery') return { cancelled: cancel(deliveryId) }
const agentId = text(payload.agentId)
if (!agentId || typeof payload.text !== 'string') return { error: 'INVALID_DELIVERY' }
// Known before it is written: the input says `queued` as it takes it, and that is the maker's to hear.
makers.delete(deliveryId)
makers.set(deliveryId, service)
if (makers.size > KEPT_DELIVERERS) makers.delete(makers.keys().next().value!)
if (payload.answersQuestion === true) answering.set(deliveryId, answers(payload.writtenAt))
submit(agentId, payload.text, deliveryId)
return {}
},
}
}
export type Deliveries = ReturnType<typeof createDeliveries>