@aragon-agent/cli 0.5.1 → 0.5.3

package/dist/team/bus.js

@@ -0,0 +1,366 @@
+/**
+ * TeamBus — the subagent message channel (team-subagents §3.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * The requirement asks for "lei si ren lei jiao liu de dian hua ji zhi, dan bu
+ * neng tai pin fan" — a real telephone, used sparingly. This module takes both
+ * halves literally: there IS a channel, and it is expensive on purpose. The rate
+ * limits in `TEAM_LIMITS` are the requirement, not a compromise (R-9).
+ *
+ * DELIVERY IS PIGGY-BACKED, NEVER PUSHED (D-4). A message for child B is
+ * appended to B's NEXT TOOL RESULT by `withMailboxTail`. `Agent.steer()` looks
+ * like the natural push channel and is the wrong answer: the core agent loop
+ * treats steering that arrives mid-batch by pushing "Tool execution skipped due
+ * to steering interrupt." for EVERY REMAINING TOOL CALL in that batch, so a
+ * chatty peer would cancel its colleague's work as a side effect of saying
+ * hello. Piggy-backing costs zero extra turns, cannot interfere with the loop,
+ * and is guaranteed to be seen by any child that is doing anything at all.
+ *
+ * EVERY REFUSAL IS A NON-ERROR (D-7). An `errorResult` reads to a model as a
+ * malfunction and invites an immediate retry, which is precisely the "tai pin
+ * fan" behaviour being designed out. The verdicts below carry a `reason` the
+ * caller renders as ordinary text.
+ */
+import { TEAM_LIMITS } from './limits.js';
+/** The lead's stable address. Subagents are addressed by their `label`. */
+export const LEAD_KEY = 'lead';
+/** Broadcast address: every other participant, the lead included. */
+export const ALL_KEY = 'all';
+export class TeamBus {
+    labels;
+    mailboxes = new Map();
+    waiters = new Set();
+    sentBy = new Map();
+    lastSentAt = new Map();
+    blocked = new Map();
+    lead = [];
+    now;
+    onMessage;
+    canSend;
+    total = 0;
+    last;
+    constructor(labels, options = {}) {
+        this.labels = [...labels];
+        this.now = options.now ?? (() => Date.now());
+        if (options.onMessage)
+            this.onMessage = options.onMessage;
+        this.canSend = options.canSend ?? (() => true);
+        for (const label of this.labels)
+            this.mailboxes.set(label, []);
+    }
+    /** Every addressable participant, in dispatch order, with the lead last. */
+    participants() {
+        return [...this.labels, LEAD_KEY];
+    }
+    /** Sibling labels for the `<subagent_role>` block. */
+    peersOf(label) {
+        return this.labels.filter((l) => l !== label);
+    }
+    /** Messages addressed to `lead`, for the report's own section (§3.7). */
+    leadMail() {
+        return [...this.lead];
+    }
+    messageCount() {
+        return this.total;
+    }
+    lastMessage() {
+        return this.last;
+    }
+    sentCount(label) {
+        return this.sentBy.get(label) ?? 0;
+    }
+    /**
+     * Canonical label for a model-supplied `from`, or `undefined` (P1-3).
+     *
+     * PUBLIC, because `makeTeamWait` has to hand the SAME string to
+     * `checkWaitable` and to `wait()`. `wait()` and `deliverToWaiter` compare
+     * `m.from === opts.from` EXACTLY, so a caller that gate-checks `"A2"`
+     * case-insensitively and then passes `"A2"` down would wait the full timeout
+     * for a message the delivery filter can never match.
+     */
+    resolveLabel(raw) {
+        const t = raw.trim().toLowerCase();
+        return this.labels.find((l) => l.toLowerCase() === t);
+    }
+    /** `team_wait` calls refused as unanswerable, per label (F-3). */
+    recordBlockedWait(label) {
+        this.blocked.set(label, this.blockedWaitCount(label) + 1);
+    }
+    blockedWaitCount(label) {
+        return this.blocked.get(label) ?? 0;
+    }
+    // -------------------------------------------------------------------------
+    // Send
+    // -------------------------------------------------------------------------
+    /**
+     * Spend quota and deliver.
+     *
+     * Refusal ORDER is deliberate: the permanent conditions are reported before
+     * the temporary one. Telling a child to "try again in 9s" when its quota is
+     * already spent sends it back for a second refusal it cannot act on.
+     */
+    send(from, to, subjectRaw, bodyRaw) {
+        const target = to.trim().toLowerCase();
+        const cost = target === ALL_KEY ? TEAM_LIMITS.broadcastCost : 1;
+        const recipients = this.resolveRecipients(from, target);
+        if (recipients.length === 0) {
+            return { ok: false, reason: 'unknown_recipient', recipients: this.participants() };
+        }
+        const used = this.sentCount(from);
+        if (used + cost > TEAM_LIMITS.messagesPerAgent) {
+            return { ok: false, reason: 'agent_quota', used, max: TEAM_LIMITS.messagesPerAgent };
+        }
+        if (this.total + cost > TEAM_LIMITS.messagesPerDispatch) {
+            return {
+                ok: false,
+                reason: 'dispatch_quota',
+                used: this.total,
+                max: TEAM_LIMITS.messagesPerDispatch,
+            };
+        }
+        const last = this.lastSentAt.get(from);
+        const now = this.now();
+        if (last !== undefined && now - last < TEAM_LIMITS.minSendIntervalMs) {
+            return {
+                ok: false,
+                reason: 'too_soon',
+                retryInSeconds: Math.max(1, Math.ceil((TEAM_LIMITS.minSendIntervalMs - (now - last)) / 1000)),
+            };
+        }
+        // Clamped, never rejected: an over-long subject is a formatting slip, and
+        // refusing the whole message for it would spend a turn to convey nothing.
+        const subject = subjectRaw.trim().slice(0, TEAM_LIMITS.subjectChars);
+        const body = bodyRaw.trim().slice(0, TEAM_LIMITS.bodyChars);
+        this.sentBy.set(from, used + cost);
+        this.lastSentAt.set(from, now);
+        this.total += cost;
+        for (const recipient of recipients) {
+            const message = { from, to: recipient, subject, body, at: now };
+            this.last = message;
+            this.onMessage?.(message);
+            if (recipient === LEAD_KEY) {
+                // The lead is blocked inside `task` for the whole dispatch (§1.3), so
+                // its mail is COLLECTED rather than delivered: it reaches the model in
+                // the report, and the panel shows it live. Injecting it into the lead's
+                // history mid-tool is what §1.3 rules out.
+                this.lead.push(message);
+                continue;
+            }
+            if (!this.deliverToWaiter(recipient, message)) {
+                this.mailboxes.get(recipient)?.push(message);
+            }
+        }
+        return {
+            ok: true,
+            delivered: recipients,
+            spent: cost,
+            remaining: Math.max(0, TEAM_LIMITS.messagesPerAgent - (used + cost)),
+        };
+    }
+    resolveRecipients(from, target) {
+        if (target === ALL_KEY)
+            return this.participants().filter((p) => p !== from);
+        if (target === LEAD_KEY)
+            return [LEAD_KEY];
+        const match = this.labels.find((l) => l.toLowerCase() === target);
+        if (!match || match === from)
+            return [];
+        return [match];
+    }
+    // -------------------------------------------------------------------------
+    // Receive
+    // -------------------------------------------------------------------------
+    waiterFor(label) {
+        for (const w of this.waiters)
+            if (w.key === label)
+                return w;
+        return undefined;
+    }
+    /**
+     * Decide whether waiting could possibly pay off (F-3).
+     *
+     * TAKES `timeoutMs`, NOT `deadlineAt` (P1-1). The deadline is derived here,
+     * from the one clock this class has, so it is comparable with every registered
+     * `Waiter.deadlineAt`.
+     *
+     * PURE: no counters, no mutation, no waiter registration. `makeTeamWait`
+     * records the refusal, because a predicate with a counter inside it is a
+     * predicate people stop trusting (D-6).
+     *
+     * BIASED TOWARD PERMITTING (D-16). Every branch that cannot be decided returns
+     * `null`. A wait that should have been refused costs the child seconds it can
+     * see; a refusal that should have been a wait destroys a result the child
+     * cannot see was ever possible. The asymmetry is total, so the bias is total.
+     */
+    checkWaitable(key, opts) {
+        const peers = this.peersOf(key);
+        if (peers.length === 0)
+            return { reason: 'no_peers' };
+        let acceptable = peers;
+        let want;
+        if (opts.from !== undefined) {
+            const canonical = this.resolveLabel(opts.from);
+            // Covers a typo, `lead` (which never sends - its mail is collected for the
+            // report and there is no `team_send` on a lead), and the caller's own
+            // label. All three are "this wait can never be satisfied", and none of
+            // them is "you have no teammates" (P1-2).
+            if (canonical === undefined || canonical === key) {
+                return { reason: 'unknown_sender', asked: opts.from.trim(), peers };
+            }
+            acceptable = [canonical];
+            want = canonical;
+        }
+        // Something is already in the mailbox: `wait()` will return it synchronously,
+        // so this is never a pointless wait however dead the peers are. Matched with
+        // the SAME canonical label `wait()` will use (P1-3).
+        const queued = this.mailboxes.get(key) ?? [];
+        if (queued.some((m) => want === undefined || m.from === want))
+            return null;
+        const deadlineAt = this.now() + Math.max(0, opts.timeoutMs);
+        const finished = (p) => !this.canSend(p);
+        const blockedPast = (p) => {
+            const w = this.waiterFor(p);
+            return w !== undefined && w.deadlineAt >= deadlineAt;
+        };
+        const stuck = [];
+        for (const peer of acceptable) {
+            if (finished(peer) || blockedPast(peer)) {
+                stuck.push(peer);
+                continue;
+            }
+            return null; // this one could still send in time
+        }
+        const cannotAct = new Set([key, ...peers.filter(finished), ...stuck]);
+        this.closeCannotAct(cannotAct, key, finished);
+        if (acceptable.some((p) => !cannotAct.has(p)))
+            return null;
+        const dead = acceptable.filter(finished);
+        if (dead.length === acceptable.length)
+            return { reason: 'all_finished', who: dead };
+        return { reason: 'all_blocked', who: acceptable };
+    }
+    /**
+     * Shrink `cannotAct` to its fixpoint, in place (P0-3).
+     *
+     * Everyone acceptable being stuck is NOT yet a deadlock proof, because a
+     * blocked peer can be released EARLY by a third party: `a` waits on `b`, `b`
+     * waits on `c`, `c` messages `b` at t=10, `b` resumes and messages `a`. A
+     * deadline comparison alone refuses `a` at t=0 and throws that outcome away.
+     *
+     * So a blocked peer stays in the set only while everyone who could wake it is
+     * also in it (or is the caller, who is about to block). If growth stops with
+     * an acceptable peer outside the set, that peer can still be woken and the
+     * wait must be permitted.
+     *
+     * Terminates because each pass either removes at least one member or stops. At
+     * ten participants the worst case is a hundred set lookups, once per
+     * `team_wait`, and `team_wait` is itself rate-limited by the message budget.
+     */
+    closeCannotAct(cannotAct, key, finished) {
+        for (;;) {
+            let shrank = false;
+            for (const p of [...cannotAct]) {
+                if (p === key || finished(p))
+                    continue;
+                const w = this.waiterFor(p);
+                // Not blocked at all -> free to send whenever it likes.
+                if (w === undefined) {
+                    cannotAct.delete(p);
+                    shrank = true;
+                    continue;
+                }
+                // Who could release `p`? Its own acceptable senders - and `peersOf`, NOT
+                // `participants`, because the lead is never a sender. Using
+                // `participants` here would put `lead` in every from-less waiter's waker
+                // set, `lead` is never in `cannotAct`, and `all_blocked` would become
+                // unreachable for exactly the from-less waits it was written for.
+                const wakers = w.from ? [w.from] : this.peersOf(p);
+                if (wakers.some((x) => x !== p && !cannotAct.has(x))) {
+                    cannotAct.delete(p);
+                    shrank = true;
+                }
+            }
+            if (!shrank)
+                return;
+        }
+    }
+    /** Take everything queued for `key`. Called by `withMailboxTail` (§3.6). */
+    drain(key) {
+        const box = this.mailboxes.get(key);
+        if (!box || box.length === 0)
+            return [];
+        return box.splice(0, box.length);
+    }
+    /**
+     * Block until a matching message arrives, the signal aborts, or the deadline
+     * elapses. Resolves `null` on both non-delivery paths — from the model's point
+     * of view an abandoned wait and an expired one want the same guidance.
+     *
+     * THE CALLER PAUSES THE CHILD'S IDLE WATCHDOG around this (see
+     * `comm-tools.ts`). A deliberate wait is not a wedged agent, and the child
+     * emits nothing while it is here.
+     */
+    wait(key, opts) {
+        const queued = this.mailboxes.get(key) ?? [];
+        const index = queued.findIndex((m) => !opts.from || m.from === opts.from);
+        if (index >= 0)
+            return Promise.resolve(queued.splice(index, 1)[0] ?? null);
+        return new Promise((resolve) => {
+            let done = false;
+            const waiter = {
+                key,
+                ...(opts.from ? { from: opts.from } : {}),
+                // On THIS bus's clock, so `checkWaitable` can compare deadlines (P1-1).
+                deadlineAt: this.now() + Math.max(0, opts.timeoutMs),
+                settle: (message) => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    opts.signal?.removeEventListener('abort', onAbort);
+                    this.waiters.delete(waiter);
+                    resolve(message);
+                },
+            };
+            const onAbort = () => waiter.settle(null);
+            const timer = setTimeout(() => waiter.settle(null), Math.max(0, opts.timeoutMs));
+            // `unref` keeps a pending wait from holding the process open on exit; it
+            // does not exist on the browser timer type, hence the guard.
+            timer.unref?.();
+            this.waiters.add(waiter);
+            if (opts.signal?.aborted) {
+                waiter.settle(null);
+                return;
+            }
+            opts.signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /** Settle every outstanding wait with `null`. Called on abort and dispose. */
+    cancelAllWaits() {
+        for (const waiter of [...this.waiters])
+            waiter.settle(null);
+    }
+    deliverToWaiter(key, message) {
+        for (const waiter of this.waiters) {
+            if (waiter.key !== key)
+                continue;
+            if (waiter.from && waiter.from !== message.from)
+                continue;
+            waiter.settle(message);
+            return true;
+        }
+        return false;
+    }
+}
+/** Render queued mail as the `<team_mail>` block appended to a tool result. */
+export function renderMailBlock(messages) {
+    const lines = ['<team_mail>'];
+    for (const m of messages) {
+        lines.push(`from ${m.from}: ${m.subject}`);
+        if (m.body.length > 0)
+            lines.push(m.body);
+    }
+    lines.push('</team_mail>');
+    return lines.join('\n');
+}

package/dist/team/comm-tools.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `team_send` / `team_wait` and the `withMailboxTail` wrapper — the subagent
+ * half of the team bus (team-subagents §3.6 / §4.2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * REGISTERED ON CHILDREN ONLY. Neither tool ever reaches a lead, which is why
+ * neither is in `HOST_TOOL_NAMES` (P2-5) and why both are in
+ * `TEAM_SUBAGENT_TOOL_NAMES` — the `policyExempt` set that keeps the lead's
+ * `allowed-tools` ceiling from refusing tools it has never heard of and
+ * dead-ending the channel (§3.11).
+ *
+ * EVERY RESULT IS A NON-ERROR `textResult`, refusals included (D-7). An
+ * `errorResult` reads as a malfunction and invites an immediate retry, which is
+ * exactly the behaviour the rate limits exist to prevent.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import { TeamBus } from './bus.js';
+import type { WatchdogPausable } from './human-queue.js';
+/**
+ * `team_send`.
+ *
+ * The bus owns quota, interval and delivery; this tool owns only the wording,
+ * because the wording is what the model acts on and it must name the limit that
+ * was hit and what to do instead.
+ */
+export declare function makeTeamSend(bus: TeamBus, selfKey: string): AgentTool;
+export interface TeamWaitDeps {
+    /**
+     * The child's own `Agent`, read LAZILY.
+     *
+     * The tool array has to exist before `new Agent(...)` can be constructed, so
+     * there is a window in which this returns `null`. Resolving it eagerly would
+     * capture that `null` for the life of the child and silently drop the
+     * watchdog pause — the failure would only show up as a mysterious
+     * `idle watchdog fired` during a legitimate wait.
+     */
+    getAgent: () => WatchdogPausable | null;
+    /** Ceiling on any single wait: never longer than the child's own budget. */
+    maxWaitMs: number;
+}
+/**
+ * `team_wait`.
+ *
+ * Runs with THAT CHILD'S idle watchdog paused, in a `try/finally` — the same
+ * treatment `withHumanWait` gives an overlay and for the same reason: a
+ * deliberate wait is not a wedged tool, and the child emits nothing while it is
+ * blocked here (I-3, one level down).
+ */
+export declare function makeTeamWait(bus: TeamBus, selfKey: string, deps: TeamWaitDeps): AgentTool;
+/**
+ * Append anything queued for `key` to the tool's result, inside a `<team_mail>`
+ * block.
+ *
+ * Same `{...tool, execute}` shape as `withConfirmation` / `withToolPolicy` /
+ * `withPlanModeGate`, so nothing in the engine needs to know this happened. The
+ * mailbox is drained EVEN WHEN the wrapped tool errored: a refused `bash` call
+ * is still a delivery opportunity, and holding mail back until a successful call
+ * would make delivery depend on whether the child happened to be doing well.
+ */
+export declare function withMailboxTail(tool: AgentTool, bus: TeamBus, key: string): AgentTool;

package/dist/team/comm-tools.js

@@ -0,0 +1,221 @@
+/**
+ * `team_send` / `team_wait` and the `withMailboxTail` wrapper — the subagent
+ * half of the team bus (team-subagents §3.6 / §4.2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * REGISTERED ON CHILDREN ONLY. Neither tool ever reaches a lead, which is why
+ * neither is in `HOST_TOOL_NAMES` (P2-5) and why both are in
+ * `TEAM_SUBAGENT_TOOL_NAMES` — the `policyExempt` set that keeps the lead's
+ * `allowed-tools` ceiling from refusing tools it has never heard of and
+ * dead-ending the channel (§3.11).
+ *
+ * EVERY RESULT IS A NON-ERROR `textResult`, refusals included (D-7). An
+ * `errorResult` reads as a malfunction and invites an immediate retry, which is
+ * exactly the behaviour the rate limits exist to prevent.
+ */
+import { textResult } from '@aragon-agent/core';
+import { TEAM_LIMITS } from './limits.js';
+import { renderMailBlock } from './bus.js';
+const SEND_DESCRIPTION = 'Message a teammate. Use it only when it changes what they should do - a finding they ' +
+    'would otherwise duplicate, or a file you are about to change. You get ' +
+    `${TEAM_LIMITS.messagesPerAgent} messages for this whole task and at most one every ` +
+    `${Math.round(TEAM_LIMITS.minSendIntervalMs / 1000)} seconds; spending them on status updates means you cannot send ` +
+    'the one that matters. Incoming messages are appended to your next tool result ' +
+    'automatically; you do not need to poll.';
+const WAIT_DESCRIPTION = 'Block until a teammate messages you. Use this only when you genuinely cannot continue ' +
+    'without an answer - it spends wall-clock time and your teammate may never reply. ' +
+    'Messages you are simply expecting arrive on your next tool result without waiting.';
+/**
+ * `team_send`.
+ *
+ * The bus owns quota, interval and delivery; this tool owns only the wording,
+ * because the wording is what the model acts on and it must name the limit that
+ * was hit and what to do instead.
+ */
+export function makeTeamSend(bus, selfKey) {
+    return {
+        name: 'team_send',
+        label: 'Message teammate',
+        description: SEND_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'A peer label, "lead", or "all".' },
+                subject: { type: 'string', description: `<= ${TEAM_LIMITS.subjectChars} chars.` },
+                body: { type: 'string', description: `<= ${TEAM_LIMITS.bodyChars} chars.` },
+            },
+            required: ['to', 'subject', 'body'],
+        },
+        async execute(_id, params) {
+            const p = params;
+            const to = typeof p.to === 'string' ? p.to : '';
+            const subject = typeof p.subject === 'string' ? p.subject : '';
+            const body = typeof p.body === 'string' ? p.body : '';
+            if (to.trim().length === 0 || subject.trim().length === 0) {
+                return textResult('Not sent: team_send needs a "to" and a "subject".');
+            }
+            const verdict = bus.send(selfKey, to, subject, body);
+            if (verdict.ok) {
+                return textResult(`Delivered to ${verdict.delivered.join(', ')}. ${verdict.remaining} of ` +
+                    `${TEAM_LIMITS.messagesPerAgent} messages left.`);
+            }
+            switch (verdict.reason) {
+                case 'unknown_recipient':
+                    return textResult(`Not sent: no subagent labelled "${to.trim()}". Teammates: ` +
+                        `${verdict.recipients.filter((r) => r !== selfKey).join(', ')}.`);
+                case 'agent_quota':
+                    return textResult(`Not sent: message quota spent (${verdict.used}/${verdict.max}). Finish your work ` +
+                        'and put it in your final summary.');
+                case 'dispatch_quota':
+                    return textResult(`Not sent: the team has spent its message budget (${verdict.used}/${verdict.max}). ` +
+                        'Continue on your own and report what you found.');
+                case 'too_soon':
+                    return textResult(`Not sent: one message every ${Math.round(TEAM_LIMITS.minSendIntervalMs / 1000)}s. Try again in ` +
+                        `${verdict.retryInSeconds}s, or continue and report instead.`);
+            }
+        },
+    };
+}
+/**
+ * Label lists for a refusal sentence: joined with `and`, capped at three names.
+ *
+ * A 10-way dispatch must not produce a 200-character refusal - the child has to
+ * read it, and the point of the sentence is what to do next, not a roll call.
+ */
+function nameList(names) {
+    if (names.length === 0)
+        return 'nobody';
+    if (names.length === 1)
+        return names[0];
+    if (names.length <= 3)
+        return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+    return `${names.slice(0, 3).join(', ')} and ${names.length - 3} others`;
+}
+/**
+ * What the child is told instead of blocking (F-3).
+ *
+ * Following the refusal style `makeTeamSend` already uses: name the reason and
+ * say what to do instead, never as an `errorResult` (D-7 / D-11).
+ *
+ * `unknown_sender` is its own reason rather than folded into `no_peers` (P1-2)
+ * because it is the only one of the four the child can act on IN THIS TURN. The
+ * other three say "give up on the message"; this one says "you asked for a name
+ * nobody has, here are the names" - and telling a child in a five-way fan-out
+ * that it is "the only subagent in this dispatch" is simply false.
+ */
+function refusalText(refusal) {
+    switch (refusal.reason) {
+        case 'no_peers':
+            return ('Nobody to wait for: you are the only subagent in this dispatch. Continue and put ' +
+                'what you found in your final summary.');
+        case 'unknown_sender':
+            return (`Nobody here is called "${refusal.asked}". Teammates: ${nameList(refusal.peers)}. ` +
+                '(The lead never sends messages.) Continue, or wait again naming one of those.');
+        case 'all_finished':
+            return (`Nobody can answer: ${nameList(refusal.who)} already finished. Continue without it ` +
+                'and say so in your summary.');
+        case 'all_blocked':
+            return (`Deadlock avoided: ${nameList(refusal.who)} is waiting for a message too, and cannot ` +
+                'be released before your own deadline. Continue with what you have and report it.');
+    }
+}
+/**
+ * `team_wait`.
+ *
+ * Runs with THAT CHILD'S idle watchdog paused, in a `try/finally` — the same
+ * treatment `withHumanWait` gives an overlay and for the same reason: a
+ * deliberate wait is not a wedged tool, and the child emits nothing while it is
+ * blocked here (I-3, one level down).
+ */
+export function makeTeamWait(bus, selfKey, deps) {
+    return {
+        name: 'team_wait',
+        label: 'Wait for teammate',
+        description: WAIT_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                from: {
+                    type: 'string',
+                    description: 'Only accept a message from this label. Omit for any.',
+                },
+                timeoutSeconds: {
+                    type: 'number',
+                    default: TEAM_LIMITS.waitDefaultSeconds,
+                    description: `${TEAM_LIMITS.waitMinSeconds}-${TEAM_LIMITS.waitMaxSeconds}.`,
+                },
+            },
+        },
+        async execute(_id, params, ctx) {
+            const p = params;
+            const from = typeof p.from === 'string' && p.from.trim().length > 0 ? p.from.trim() : undefined;
+            const requested = typeof p.timeoutSeconds === 'number' && Number.isFinite(p.timeoutSeconds)
+                ? p.timeoutSeconds
+                : TEAM_LIMITS.waitDefaultSeconds;
+            const seconds = Math.min(TEAM_LIMITS.waitMaxSeconds, Math.max(TEAM_LIMITS.waitMinSeconds, Math.round(requested)));
+            const timeoutMs = Math.min(seconds * 1000, deps.maxWaitMs);
+            // `timeoutMs`, not a deadline: the bus owns the clock (P1-1). Checked
+            // BEFORE the watchdog pause on purpose - the refusal path returns
+            // synchronously, and a pause/resume pair around a synchronous return is a
+            // needless state transition on the one object whose state is hardest to
+            // reason about.
+            const refusal = bus.checkWaitable(selfKey, {
+                ...(from ? { from } : {}),
+                timeoutMs,
+            });
+            if (refusal) {
+                bus.recordBlockedWait(selfKey);
+                return textResult(refusalText(refusal));
+            }
+            // Past the gate, `from` is known to name a real peer, so hand `wait()` the
+            // CANONICAL label rather than what the model typed (P1-3). `wait()` and
+            // `deliverToWaiter` compare exactly; this is the one line that makes them
+            // agree with the gate that just permitted the call.
+            const fromLabel = from ? bus.resolveLabel(from) : undefined;
+            const agent = deps.getAgent();
+            agent?.pauseIdleWatchdog();
+            let message;
+            try {
+                message = await bus.wait(selfKey, {
+                    ...(fromLabel ? { from: fromLabel } : {}),
+                    timeoutMs,
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
+                });
+            }
+            finally {
+                agent?.resumeIdleWatchdog();
+            }
+            if (!message) {
+                return textResult(`No message arrived within ${Math.round(timeoutMs / 1000)}s. Continue without it.`);
+            }
+            return textResult(renderMailBlock([message]));
+        },
+    };
+}
+/**
+ * Append anything queued for `key` to the tool's result, inside a `<team_mail>`
+ * block.
+ *
+ * Same `{...tool, execute}` shape as `withConfirmation` / `withToolPolicy` /
+ * `withPlanModeGate`, so nothing in the engine needs to know this happened. The
+ * mailbox is drained EVEN WHEN the wrapped tool errored: a refused `bash` call
+ * is still a delivery opportunity, and holding mail back until a successful call
+ * would make delivery depend on whether the child happened to be doing well.
+ */
+export function withMailboxTail(tool, bus, key) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const result = await original(id, params, ctx);
+            const mail = bus.drain(key);
+            if (mail.length === 0)
+                return result;
+            return {
+                ...result,
+                content: [...result.content, { type: 'text', text: renderMailBlock(mail) }],
+            };
+        },
+    };
+}