@aragon-agent/cli 0.5.2 → 0.5.3

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) }],
+            };
+        },
+    };
+}

package/dist/team/human-queue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * TeamHumanQueue — serializes subagent confirmations onto the ONE human slot
+ * (team-subagents §3.11 / I-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `App.tsx` holds `humanRequest` as a SINGLE state slot and `resolveHuman`
+ * broadcasts one response to every pending entry, so two children raising a
+ * `--confirm` dialog at the same instant would double-resolve it. This queue is
+ * a plain promise chain that admits one request at a time and prefixes the
+ * summary with the child's label, so the user can always tell WHICH agent is
+ * asking.
+ *
+ * THE WATCHDOG IS PAUSED ON ENQUEUE, NOT ON DISPLAY (D-18 / P0-4). This is
+ * invariant I-3 one level down, and it is the second-most likely way to ship
+ * this feature broken. A child sitting third in the FIFO is emitting nothing,
+ * and its own `idleTimeout` (210 s by default) is armed: a user who takes four
+ * minutes over the first dialog would otherwise lose children 2 and 3 to their
+ * own watchdogs, each printing `[Agent] idle watchdog fired` over the TUI and
+ * each landing in the report as a failure that has nothing to do with the work.
+ * `controller.ts` records fixing exactly this for the LEAD's `--confirm` gate;
+ * repeating it for children would regress a fix this codebase already paid for.
+ * The wait starts when the promise is chained, which is where the time actually
+ * goes — hence enqueue, not display.
+ */
+import type { ConfirmRequest } from '../tools/index.js';
+/** The slice of `Agent` this queue needs. Structural, so tests can stub it. */
+export interface WatchdogPausable {
+    pauseIdleWatchdog(): void;
+    resumeIdleWatchdog(): void;
+}
+export declare class TeamHumanQueue {
+    private readonly confirm;
+    /** The chain. Never rejects: a failed request resolves `false` (deny). */
+    private tail;
+    constructor(confirm: (req: ConfirmRequest) => Promise<boolean>);
+    /**
+     * Ask the human about `req` on behalf of `label`, one at a time.
+     *
+     * @param child  Paused for the whole wait, queue time included. May be `null`
+     *               in the window before the child's `Agent` exists.
+     * @param signal The child's `ctx.signal`. An abort resolves `false` so the
+     *               child is never left owing an answer to a dialog nobody is
+     *               going to reach.
+     */
+    request(child: WatchdogPausable | null, label: string, req: ConfirmRequest, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Chain `run` after everything already queued.
+     *
+     * The `catch` is what keeps the chain alive: an unhandled rejection here would
+     * poison `this.tail` and every LATER request would reject without ever being
+     * shown, which presents as "the second file write silently did nothing".
+     */
+    private enqueue;
+}

package/dist/team/human-queue.js

@@ -0,0 +1,72 @@
+/**
+ * TeamHumanQueue — serializes subagent confirmations onto the ONE human slot
+ * (team-subagents §3.11 / I-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `App.tsx` holds `humanRequest` as a SINGLE state slot and `resolveHuman`
+ * broadcasts one response to every pending entry, so two children raising a
+ * `--confirm` dialog at the same instant would double-resolve it. This queue is
+ * a plain promise chain that admits one request at a time and prefixes the
+ * summary with the child's label, so the user can always tell WHICH agent is
+ * asking.
+ *
+ * THE WATCHDOG IS PAUSED ON ENQUEUE, NOT ON DISPLAY (D-18 / P0-4). This is
+ * invariant I-3 one level down, and it is the second-most likely way to ship
+ * this feature broken. A child sitting third in the FIFO is emitting nothing,
+ * and its own `idleTimeout` (210 s by default) is armed: a user who takes four
+ * minutes over the first dialog would otherwise lose children 2 and 3 to their
+ * own watchdogs, each printing `[Agent] idle watchdog fired` over the TUI and
+ * each landing in the report as a failure that has nothing to do with the work.
+ * `controller.ts` records fixing exactly this for the LEAD's `--confirm` gate;
+ * repeating it for children would regress a fix this codebase already paid for.
+ * The wait starts when the promise is chained, which is where the time actually
+ * goes — hence enqueue, not display.
+ */
+export class TeamHumanQueue {
+    confirm;
+    /** The chain. Never rejects: a failed request resolves `false` (deny). */
+    tail = Promise.resolve();
+    constructor(confirm) {
+        this.confirm = confirm;
+    }
+    /**
+     * Ask the human about `req` on behalf of `label`, one at a time.
+     *
+     * @param child  Paused for the whole wait, queue time included. May be `null`
+     *               in the window before the child's `Agent` exists.
+     * @param signal The child's `ctx.signal`. An abort resolves `false` so the
+     *               child is never left owing an answer to a dialog nobody is
+     *               going to reach.
+     */
+    request(child, label, req, signal) {
+        child?.pauseIdleWatchdog();
+        const queued = this.enqueue(async () => {
+            if (signal?.aborted)
+                return false;
+            return this.confirm({ ...req, summary: `[${label}] ${req.summary}` });
+        });
+        const raced = signal ? Promise.race([queued, abortsToFalse(signal)]) : queued;
+        return raced.finally(() => child?.resumeIdleWatchdog());
+    }
+    /**
+     * Chain `run` after everything already queued.
+     *
+     * The `catch` is what keeps the chain alive: an unhandled rejection here would
+     * poison `this.tail` and every LATER request would reject without ever being
+     * shown, which presents as "the second file write silently did nothing".
+     */
+    enqueue(run) {
+        const next = this.tail.then(run, run).catch(() => false);
+        this.tail = next;
+        return next;
+    }
+}
+/** Resolve `false` when `signal` aborts, with the listener cleaned up after. */
+function abortsToFalse(signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        signal.addEventListener('abort', () => resolve(false), { once: true });
+    });
+}

package/dist/team/limits.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TEAM_LIMITS — the single authority on every bound this subsystem enforces
+ * (team-subagents §3.5 / §3.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * TWO KINDS OF NUMBER LIVE HERE AND THEY ARE NOT INTERCHANGEABLE.
+ *
+ *  - The `TEAM_LIMITS` entries below are STRUCTURAL: they describe what the
+ *    report format, the message channel and the panel can physically carry, and
+ *    a user has no business tuning them. They are constants.
+ *  - The six `team.*` config keys (`config/schema.ts`) are POLICY: how wide to
+ *    fan out, how long to wait. They are clamped, persisted and user-facing.
+ *
+ * `hardMaxSubagents` sits on the structural side ON PURPOSE even though it
+ * bounds a config key: the requirement caps the fan-out at 10 (R-g), so a
+ * hand-edited `config.json` must not be able to raise it. It is applied twice —
+ * once in `clampTeamConfig` and once in `normalizeSubagentSpecs` — because a
+ * clamp that only runs on the read path leaves a bad value on disk.
+ *
+ * BYTES, NOT CHARACTERS, for every report budget (D-8 / I-9). `ToolExecutor`
+ * truncates combined tool text at 100 000 BYTES; a 24 000-character CJK report
+ * is 72 000 bytes, so a character-denominated cap would let the executor chop
+ * the report mid-section and take the failure count with it.
+ */
+export declare const TEAM_LIMITS: {
+    /**
+     * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
+     * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
+     * for thirty can exceed it.
+     */
+    readonly hardMaxSubagents: 10;
+    /** `SubagentSpec.description`, clamped (never rejected). */
+    readonly descriptionChars: 60;
+    /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
+     *  this has to be generous enough to carry a whole brief. */
+    readonly promptChars: 8000;
+    /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
+     *  short enough that five of them fit one row of an 80-column terminal. */
+    readonly labelChars: 12;
+    readonly reportMaxBytes: 48000;
+    readonly summaryMaxBytes: 6000;
+    /**
+     * Floor a summary is trimmed TO, never below. A section trimmed to nothing is
+     * indistinguishable from a child that reported nothing, which is exactly the
+     * distinction the report exists to preserve.
+     */
+    readonly summaryFloorBytes: 400;
+    /** Deduped `write_file` / `edit_file` paths recorded per child (§3.4). */
+    readonly filesTouchedMax: 30;
+    /** `team_send` calls one child may spend on a whole dispatch. */
+    readonly messagesPerAgent: 6;
+    /** `team_send` calls the whole dispatch may spend. */
+    readonly messagesPerDispatch: 24;
+    /** Minimum gap between one child's sends. */
+    readonly minSendIntervalMs: 15000;
+    /** Quota units a `to: "all"` broadcast costs. */
+    readonly broadcastCost: 2;
+    readonly subjectChars: 80;
+    readonly bodyChars: 800;
+    /** `team_wait` timeout clamp, in seconds. */
+    readonly waitMinSeconds: 5;
+    readonly waitMaxSeconds: 120;
+    readonly waitDefaultSeconds: 30;
+    /**
+     * `agent_update` coalescing window (§5.2). Five children streaming tokens must
+     * not push five React renders per token; phase transitions always pass.
+     */
+    readonly agentUpdateThrottleMs: 120;
+    /** Agent rows the live panel renders before collapsing to `+N more` (§6.1). */
+    readonly panelMaxRows: 5;
+    /** Below this many terminal rows the panel collapses to its header line. */
+    readonly panelCollapseRows: 20;
+    /** Below this many columns the status-bar readout degrades to `[3]` (D-20). */
+    readonly statusCompactCols: 100;
+    /**
+     * STORAGE ceiling for a prose activity tail (P0-1). The most a `SubagentRun`
+     * may carry, NOT the width of the column: `TeamPanel.activityBudget(cols)`
+     * derives the display budget from the terminal and is always <= this.
+     */
+    readonly activityChars: 64;
+    /**
+     * Floor under `activityBudget`. Below roughly 46 columns the roster has bigger
+     * problems than an elided activity line, and a column narrower than this shows
+     * nothing but an ellipsis - at which point the phase word is more informative.
+     */
+    readonly activityMinChars: 12;
+    /** Rolling text buffer kept per child. The only per-token allocation. */
+    readonly activityTailChars: 160;
+    /** Per picked tool argument (P1-4). A path or a command longer than this is
+     *  elided on capture, so a run can never carry more than a few hundred bytes
+     *  of argument however large the real call was. */
+    readonly activityArgChars: 120;
+    /** At or above this many columns the activity line carries a full path or
+     *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
+     *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
+    readonly activityWideCols: 100;
+    /** Retries of a child that produced NOTHING. One, and not configurable: a
+     *  second retry doubles the worst-case latency of a failing dispatch and buys
+     *  nothing a re-dispatch by the lead would not buy better. */
+    readonly maxColdStartRetries: 1;
+    readonly retryBackoffMs: 2000;
+};
+/**
+ * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).
+ *
+ * They are not in the lead's registered tool list, so evaluating them against
+ * the lead's `allowed-tools` ceiling would refuse them and dead-end the channel
+ * — the same dead end `SKILL_TOOL_FLOOR` exists to prevent one level up.
+ *
+ * Deliberately NOT added to `HOST_TOOL_NAMES` (P2-5). That constant answers
+ * "can a skill's `allowed-tools` declaration ever take effect?", and these two
+ * are never registered on a lead — so a skill naming them genuinely IS
+ * unenforceable, and `aragon skills doctor` reporting it as such is correct
+ * rather than a gap.
+ */
+export declare const TEAM_SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Bumped whenever the wording of either prompt block changes, so a behaviour
+ * report can be tied to a block revision with one grep.
+ */
+export declare const TEAM_BLOCK_VERSION = "v1-2026-07";

package/dist/team/limits.js

@@ -0,0 +1,128 @@
+/**
+ * TEAM_LIMITS — the single authority on every bound this subsystem enforces
+ * (team-subagents §3.5 / §3.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * TWO KINDS OF NUMBER LIVE HERE AND THEY ARE NOT INTERCHANGEABLE.
+ *
+ *  - The `TEAM_LIMITS` entries below are STRUCTURAL: they describe what the
+ *    report format, the message channel and the panel can physically carry, and
+ *    a user has no business tuning them. They are constants.
+ *  - The six `team.*` config keys (`config/schema.ts`) are POLICY: how wide to
+ *    fan out, how long to wait. They are clamped, persisted and user-facing.
+ *
+ * `hardMaxSubagents` sits on the structural side ON PURPOSE even though it
+ * bounds a config key: the requirement caps the fan-out at 10 (R-g), so a
+ * hand-edited `config.json` must not be able to raise it. It is applied twice —
+ * once in `clampTeamConfig` and once in `normalizeSubagentSpecs` — because a
+ * clamp that only runs on the read path leaves a bad value on disk.
+ *
+ * BYTES, NOT CHARACTERS, for every report budget (D-8 / I-9). `ToolExecutor`
+ * truncates combined tool text at 100 000 BYTES; a 24 000-character CJK report
+ * is 72 000 bytes, so a character-denominated cap would let the executor chop
+ * the report mid-section and take the failure count with it.
+ */
+export const TEAM_LIMITS = {
+    /**
+     * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
+     * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
+     * for thirty can exceed it.
+     */
+    hardMaxSubagents: 10,
+    // --- Spec normalization (§3.3.1) ---
+    /** `SubagentSpec.description`, clamped (never rejected). */
+    descriptionChars: 60,
+    /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
+     *  this has to be generous enough to carry a whole brief. */
+    promptChars: 8000,
+    /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
+     *  short enough that five of them fit one row of an 80-column terminal. */
+    labelChars: 12,
+    // --- Report budgeting (§3.7). BYTES. ---
+    reportMaxBytes: 48_000,
+    summaryMaxBytes: 6_000,
+    /**
+     * Floor a summary is trimmed TO, never below. A section trimmed to nothing is
+     * indistinguishable from a child that reported nothing, which is exactly the
+     * distinction the report exists to preserve.
+     */
+    summaryFloorBytes: 400,
+    /** Deduped `write_file` / `edit_file` paths recorded per child (§3.4). */
+    filesTouchedMax: 30,
+    // --- The team bus (§3.6). The "bu neng tai pin fan" clause, in numbers. ---
+    /** `team_send` calls one child may spend on a whole dispatch. */
+    messagesPerAgent: 6,
+    /** `team_send` calls the whole dispatch may spend. */
+    messagesPerDispatch: 24,
+    /** Minimum gap between one child's sends. */
+    minSendIntervalMs: 15_000,
+    /** Quota units a `to: "all"` broadcast costs. */
+    broadcastCost: 2,
+    subjectChars: 80,
+    bodyChars: 800,
+    /** `team_wait` timeout clamp, in seconds. */
+    waitMinSeconds: 5,
+    waitMaxSeconds: 120,
+    waitDefaultSeconds: 30,
+    /**
+     * `agent_update` coalescing window (§5.2). Five children streaming tokens must
+     * not push five React renders per token; phase transitions always pass.
+     */
+    agentUpdateThrottleMs: 120,
+    /** Agent rows the live panel renders before collapsing to `+N more` (§6.1). */
+    panelMaxRows: 5,
+    /** Below this many terminal rows the panel collapses to its header line. */
+    panelCollapseRows: 20,
+    /** Below this many columns the status-bar readout degrades to `[3]` (D-20). */
+    statusCompactCols: 100,
+    // --- Live activity (team-live-activity F-1) ---
+    /**
+     * STORAGE ceiling for a prose activity tail (P0-1). The most a `SubagentRun`
+     * may carry, NOT the width of the column: `TeamPanel.activityBudget(cols)`
+     * derives the display budget from the terminal and is always <= this.
+     */
+    activityChars: 64,
+    /**
+     * Floor under `activityBudget`. Below roughly 46 columns the roster has bigger
+     * problems than an elided activity line, and a column narrower than this shows
+     * nothing but an ellipsis - at which point the phase word is more informative.
+     */
+    activityMinChars: 12,
+    /** Rolling text buffer kept per child. The only per-token allocation. */
+    activityTailChars: 160,
+    /** Per picked tool argument (P1-4). A path or a command longer than this is
+     *  elided on capture, so a run can never carry more than a few hundred bytes
+     *  of argument however large the real call was. */
+    activityArgChars: 120,
+    /** At or above this many columns the activity line carries a full path or
+     *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
+     *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
+    activityWideCols: 100,
+    // --- Cold-start retry (team-live-activity F-4) ---
+    /** Retries of a child that produced NOTHING. One, and not configurable: a
+     *  second retry doubles the worst-case latency of a failing dispatch and buys
+     *  nothing a re-dispatch by the lead would not buy better. */
+    maxColdStartRetries: 1,
+    retryBackoffMs: 2_000,
+};
+/**
+ * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).
+ *
+ * They are not in the lead's registered tool list, so evaluating them against
+ * the lead's `allowed-tools` ceiling would refuse them and dead-end the channel
+ * — the same dead end `SKILL_TOOL_FLOOR` exists to prevent one level up.
+ *
+ * Deliberately NOT added to `HOST_TOOL_NAMES` (P2-5). That constant answers
+ * "can a skill's `allowed-tools` declaration ever take effect?", and these two
+ * are never registered on a lead — so a skill naming them genuinely IS
+ * unenforceable, and `aragon skills doctor` reporting it as such is correct
+ * rather than a gap.
+ */
+export const TEAM_SUBAGENT_TOOL_NAMES = new Set(['team_send', 'team_wait']);
+/**
+ * Bumped whenever the wording of either prompt block changes, so a behaviour
+ * report can be tied to a block revision with one grep.
+ */
+export const TEAM_BLOCK_VERSION = 'v1-2026-07';