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
Agent Messages: a tab turned off holds its messages 5 minutes before they fail (#1259)
Dee2eccda165422
diff --git a/cli/src/messages/mailbox.spec.ts b/cli/src/messages/mailbox.spec.tsindex f178cddcd..6e48af151 100644--- a/cli/src/messages/mailbox.spec.ts+++ b/cli/src/messages/mailbox.spec.ts@@ -25,6 +25,7 @@ function setup(over: Partial<MailboxDeps> = {}) {const delivered: Array<[string, string, string]> = []const statuses: DeliveryStatus[] = []let refused: string | null = null+ let held: string | null = nulllet ready = trueconst writable = vi.fn()const deps: MailboxDeps = {@@ -32,6 +33,7 @@ function setup(over: Partial<MailboxDeps> = {}) {agent: () => agent,deliver: (agentId, text, id) => { delivered.push([agentId, text, id]) },refused: () => refused,+ held: () => held,ready: () => ready,text: (_d, m) => `[${m.id}] ${m.text}`,changed: (status) => { statuses.push(status) },@@ -48,6 +50,7 @@ function setup(over: Partial<MailboxDeps> = {}) {now: () => clock,setAgent: (next: MailboxAgent | null) => { agent = next },refuse: (why: string | null) => { refused = why },+ hold: (why: string | null) => { held = why },setReady: (next: boolean) => { ready = next },claim: (pane: string, key: string) => {// As the hook does: the rename into claimed/, which it makes.@@ -271,6 +274,45 @@ describe('Agent Messages\' mailbox', () => {expect(t.inbox.waiting('%3', written.key)).toBe(false)})+ it('holds a delivery its tab does not carry for now: out of the hook\'s reach, given to no one, put back after', () => {+ // A tab turned off by a slip of the mouse failed the message waiting in it (2026-10-12).+ const t = setup()+ const waiting = t.accept({ ...message(), fyi: true })+ expect(t.inbox.waiting('%3', waiting.key)).toBe(true)+ t.hold('off for now')+ t.mailbox.refuseAll()+ expect(waiting).toMatchObject({ state: 'queued', reason: 'off for now' })+ expect(t.inbox.waiting('%3', waiting.key)).toBe(false)+ t.mailbox.pump()+ expect(t.inbox.waiting('%3', waiting.key)).toBe(false)+ t.hold(null)+ t.mailbox.pump()+ expect(t.inbox.waiting('%3', waiting.key)).toBe(true)+ expect(waiting.reason).toBe(FYI_REASON)+ // A parked attempt is back with the hook: held, it leaves the hook's reach too, and is typed again after.+ const typed = t.accept(message('m0000002'))+ t.event(typed.attempt!.id, 'queued')+ t.tick(PARK_MS)+ t.mailbox.pump()+ expect(typed.attempt?.parked).toBe(true)+ expect(t.inbox.waiting('%3', typed.key)).toBe(true)+ t.hold('off for now')+ t.mailbox.pump()+ expect(typed).toMatchObject({ state: 'queued', reason: 'off for now', attempt: undefined })+ expect(t.inbox.waiting('%3', typed.key)).toBe(false)+ t.hold(null)+ t.mailbox.pump()+ expect(t.delivered.filter(([, , id]) => id.includes(typed.key))).toHaveLength(2)+ // Refused for good, a parked one fails like any other.+ t.event(typed.attempt!.id, 'queued')+ t.tick(PARK_MS)+ t.mailbox.pump()+ t.refuse('gone')+ t.mailbox.refuseAll()+ expect(typed).toMatchObject({ state: 'failed', reason: 'gone' })+ expect(t.inbox.waiting('%3', typed.key)).toBe(false)+ })+it('fails a delivery the directory refuses, withdrawing it from the hook; nothing moves before the directory is read', () => {const t = setup()t.setReady(false)diff --git a/cli/src/messages/mailbox.ts b/cli/src/messages/mailbox.tsindex f68692cd8..facdf4d24 100644--- a/cli/src/messages/mailbox.ts+++ b/cli/src/messages/mailbox.ts@@ -63,6 +63,9 @@ export interface MailboxDeps {/** Null while a delivery may still be made; otherwise why it can no longer be (it left the tab, the tab* turned Agent Messages off). */refused(delivery: LocalDelivery): string | null+ /** Null while a delivery may be made; otherwise why it waits, given to no one, the hook included: its tab no longer+ * carries it, for less long than it is held before it is refused. */+ held?(delivery: LocalDelivery): string | null/** Whether who may message whom is known yet: until it is, nothing is typed and nothing refused. */ready(): boolean/** Why a delivery may never be made, whatever the tabs say, or null: asked as the mailbox starts, before the@@ -101,6 +104,8 @@ export const deliveryKey = (messageId: string, agentId: string): string =>export class Mailbox {private timer: ReturnType<typeof setInterval> | null = nullprivate started = false+ /** Deliveries held out of the hook's reach while their tab does not carry them ([hold]). */+ private readonly holding = new Set<LocalDelivery>()constructor(private readonly deps: MailboxDeps) {}private now(): number { return this.deps.now?.() ?? Date.now() }private get local(): LocalDelivery[] { return this.deps.store.state.local }@@ -204,10 +209,16 @@ export class Mailbox {if (delivery.state !== 'queued') continueif (delivery.reason === WAITING.team_waiting_idle) this.report(delivery, this.idleReason(delivery))if (delivery.pane && taken.has(`${delivery.pane.slice(1)}-${delivery.key}`) && this.deps.inbox.claimed(delivery.pane, delivery.key)) { this.finish(delivery, 'hook'); continue }- if (delivery.attempt) { this.watch(delivery); continue }+ if (delivery.attempt) {+ // A parked attempt is back in the hook's inbox: where its tab no longer carries it, the hook must not take it.+ if (!delivery.attempt.parked || !this.outside(delivery)) { this.watch(delivery); continue }+ delivery.attempt = undefined+ }if (!this.deps.ready()) continueconst refused = this.deps.refused(delivery)if (refused) { this.fail(delivery, refused); continue }+ const held = this.deps.held?.(delivery)+ if (held) { this.hold(delivery, held); continue }const agent = this.deps.agent(delivery.agentId)const message = this.deps.store.entry(delivery.messageId)?.messageif (!message) { this.fail(delivery, 'the message is no longer kept'); continue }@@ -223,7 +234,8 @@ export class Mailbox {delivery.pane = agent.panedelivery.session = agent.sessionthis.put(delivery, message, agent)- if (delivery.reason === 'its harness is stopped') this.report(delivery, undefined)+ const wasHeld = this.holding.delete(delivery)+ if (wasHeld || delivery.reason === 'its harness is stopped') this.report(delivery, undefined)this.save()}// News waits for the hook, or for the agent to read it: typed, it would start a turn of its own.@@ -237,16 +249,33 @@ export class Mailbox {}}- /** Withdraw what waits for an agent's messages in a tab that turned off, or that it left. */+ /** Withdraw what waits for an agent's messages in a tab that turned off, or that it left: held for a while, then+ * refused. */refuseAll(): void {if (!this.deps.ready()) returnfor (const delivery of this.local) {- if (delivery.state !== 'queued' || delivery.attempt) continue+ if (delivery.state !== 'queued' || (delivery.attempt && !delivery.attempt.parked)) continueconst refused = this.deps.refused(delivery)+ const held = refused ? null : this.deps.held?.(delivery)+ if (refused || held) delivery.attempt = undefinedif (refused) this.fail(delivery, refused)+ else if (held) this.hold(delivery, held)}}+ /** Whether the tabs no longer carry a delivery, for now or for good. */+ private outside(delivery: LocalDelivery): boolean {+ return this.deps.ready() && Boolean(this.deps.refused(delivery) || this.deps.held?.(delivery))+ }++ /** Its tab does not carry it, for now: out of the hook's reach, given to no one, and put back once it is carried+ * again (the pump puts what is missing from the inbox). */+ private hold(delivery: LocalDelivery, reason: string): void {+ this.holding.add(delivery)+ if (delivery.pane && this.deps.inbox.waiting(delivery.pane, delivery.key)) { this.deps.inbox.withdraw(delivery.pane, delivery.key); this.save() }+ this.report(delivery, reason)+ }+/** A typed attempt in flight: parked once the core has held it behind a turn, forgotten when the core never* took it or kept it too long. */private watch(delivery: LocalDelivery): void {diff --git a/cli/src/messages/service.spec.ts b/cli/src/messages/service.spec.tsindex 990460bfc..299b7f2a1 100644--- a/cli/src/messages/service.spec.ts+++ b/cli/src/messages/service.spec.ts@@ -6,10 +6,10 @@ import type { BackendNotice, TurnDelivery } from '../core/api.js'import type { RegisteredSession } from '../lib/registry.js'import { fakeCore } from '../testing/fakeCore.js'import { PaneInbox } from './inbox.js'-import { deliveryKey, FYI_REASON } from './mailbox.js'+import { deliveryKey, FYI_REASON, PUMP_MS } from './mailbox.js'import { header, LIMITS, LONG_TEXT, longAdvice, MessageError, parseMessage, type Message } from './model.js'import type { Rpc } from './rpc.js'-import { REMOTE_STATUS_MS, startAgentMessages, SWEEP_AFTER_MS, TICK_MS } from './service.js'+import { HELD_OFF_REASON, HELD_OUTSIDE_MS, REMOTE_STATUS_MS, startAgentMessages, SWEEP_AFTER_MS, TICK_MS } from './service.js'import { MessageStore } from './store.js'import { Ledger, ledgerPath } from '../agentClient/ledger.js'@@ -561,16 +561,44 @@ describe('the roster note and the directory', () => {again.stop()})- it('fails a waiting delivery once its tab turns Agent Messages off', async () => {+ it('holds a waiting delivery while its tab has Agent Messages off, goes on once it is on again, and fails it later', async () => {+ // Turned off by a slip of the mouse and on again a minute later, a tab failed the message waiting in it (2026-10-12).+ vi.useFakeTimers()const t = setup()+ t.service.start()const reply = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })t.deliveryEvent({ deliveryId: t.delivered[0][2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })- t.tabs[0].enabled = false- t.notice({ type: 'desk_changed', revision: 6 })- await new Promise((settle) => setTimeout(settle, 0))- const history = await t.ask({ action: 'history', limit: 10 })- expect((history.messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>).find((m) => m.id === reply.id)!.statuses[0])- .toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off in this tab' })+ const key = deliveryKey(reply.id as string, 'api')+ const status = async () => ((await t.ask({ action: 'history', limit: 10 })).messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>)+ .find((m) => m.id === reply.id)!.statuses[0]+ const turn = async (enabled: boolean) => {+ t.tabs[0].enabled = enabled+ t.notice({ type: 'desk_changed', revision: 6 })+ await vi.advanceTimersByTimeAsync(0)+ }+ await turn(false)+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })+ // Given to no one meanwhile: out of the hook's reach.+ expect(t.inbox.waiting('%2', key)).toBe(false)+ t.tick(HELD_OUTSIDE_MS - 1)+ await vi.advanceTimersByTimeAsync(PUMP_MS)+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })+ const attempts = t.delivered.length+ await turn(true)+ await vi.advanceTimersByTimeAsync(PUMP_MS)+ // Carried again: put back, and typed into the idle agent.+ expect(t.delivered.length).toBe(attempts + 1)+ expect(t.delivered.at(-1)![2]).toContain(key)+ expect((await status()).reason).not.toBe(HELD_OFF_REASON)+ t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })+ // Off for good: held a while again, then failed.+ await turn(false)+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })+ t.tick(HELD_OUTSIDE_MS)+ await vi.advanceTimersByTimeAsync(PUMP_MS)+ expect(await status()).toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off in this tab' })+ expect(t.inbox.waiting('%2', key)).toBe(false)+ t.service.stop()})it('answers a failure it did not expect without saying more', async () => {diff --git a/cli/src/messages/service.ts b/cli/src/messages/service.tsindex 566c2fc2a..8d3fe1be8 100644--- a/cli/src/messages/service.ts+++ b/cli/src/messages/service.ts@@ -58,6 +58,10 @@ export const REMOTE_STATUS_MS = 15_000export const WHO_MS = 60_000/** How old an inbox file nothing here waits on must be before a start sweeps it away. */export const SWEEP_AFTER_MS = 10 * 60_000+/** How long a delivery no tab with Agent Messages on carries is held, given to no one, before it fails. */+export const HELD_OUTSIDE_MS = 5 * 60_000+export const HELD_OFF_REASON = 'Agent Messages are off in this tab: it waits 5 minutes for them to be on again, then fails'+export const HELD_LEFT_REASON = 'it is not in a tab with the sender: it waits 5 minutes for that to change, then fails'const PANE = /^%\d{1,9}$//** The most messages `harness send` alone gives an agent at once, unread ones first. */@@ -115,7 +119,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})return { pane: session.tmuxPane, session: session.sessionId ?? '', available: session.active && core.agents.terminalAvailable(agentId) }},deliver: (agentId, text, deliveryId) => { core.turns.deliver(agentId, text, deliveryId); options.changed?.() },- refused: (delivery) => refusal(delivery),+ refused: (delivery) => { const v = verdict(delivery); return v && 'refused' in v ? v.refused : null },+ held: (delivery) => { const v = verdict(delivery); return v && 'held' in v ? v.held : null },forbidden: (delivery) => forbidden(delivery),ready: () => directory.current() !== null,text: (delivery, message) => {@@ -137,19 +142,34 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})return store.entry(delivery.messageId)?.message.tabId === 'started' ? 'it was sent outside any tab with Agent Messages on' : null}- /** Why a local delivery can no longer be made, or null. Only what may never be made is refused before the- * directory is read. */- function refusal(delivery: LocalDelivery): string | null {+ /** When the tabs stopped carrying each local delivery (`messageId agentId`), while they do not. */+ const outsideSince = new Map<string, number>()++ /**+ * Whether a local delivery may be made: null; held, given to no one, while no tab with Agent Messages on carries+ * it, for HELD_OUTSIDE_MS; refused after that, or at once when it may never be made. Only what may never be made is+ * refused before the directory is read. A tab turned off by a slip of the mouse and on again a minute later failed+ * the message waiting in it (owner, 2026-10-12): held, it goes on once the tab is on again.+ */+ function verdict(delivery: LocalDelivery): { refused: string } | { held: string } | null {const entry = store.entry(delivery.messageId)- if (!entry) return 'the message is no longer kept'+ if (!entry) return { refused: 'the message is no longer kept' }const never = forbidden(delivery)- if (never) return never+ if (never) return { refused: never }if (!directory.current()) return null+ const key = `${delivery.messageId} ${delivery.agentId}`const recipient = { machineId: self(), agentId: delivery.agentId }// Only a tab with Agent Messages on carries a message.- if (directory.shared(entry.message.from, recipient)) return null+ if (directory.shared(entry.message.from, recipient)) { outsideSince.delete(key); return null }const tab = directory.current()!.tabs.find((t) => t.id === entry.message.tabId)- return tab && !tab.enabled ? 'Agent Messages were turned off in this tab' : 'it is no longer in a tab with the sender'+ const off = Boolean(tab && !tab.enabled)+ const since = outsideSince.get(key) ?? now()+ if (now() - since < HELD_OUTSIDE_MS) {+ outsideSince.set(key, since)+ return { held: off ? HELD_OFF_REASON : HELD_LEFT_REASON }+ }+ outsideSince.delete(key)+ return { refused: off ? 'Agent Messages were turned off in this tab' : 'it is no longer in a tab with the sender' }}function localChanged(status: DeliveryStatus, delivery: LocalDelivery): void {diff --git a/docs/design/2026-10-10-agent-messages.md b/docs/design/2026-10-10-agent-messages.mdindex 155206105..b8c46ffaf 100644--- a/docs/design/2026-10-10-agent-messages.md+++ b/docs/design/2026-10-10-agent-messages.md@@ -245,6 +245,11 @@ returns; a start sweeps old files nothing waits on.States: **queued**, **delivered** (claimed by the hook, or typed; "unconfirmed" when the core could not say),**failed** (the recipient left the tab or the flag was turned off), each with the time, the route and a reason.+A delivery no tab with Agent Messages on carries any more is held for 5 minutes before it fails: out of the hook's+reach and never typed, so off still means off, and put back once a tab carries it again. A tab turned off by a slip+of the mouse and on again a minute later failed the message waiting in it (owner, 2026-10-12); a harness that leaves+its tab for a moment loses nothing either.+### LimitsPer sender: 30 messages in 10 minutes, then `RATE_LIMITED` and an alert to the person. Per message: 16,000