@aragon-agent/cli 0.5.1 → 0.5.3

package/dist/team/prompt.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two system-prompt blocks team mode adds (team-subagents §4.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * BOTH BLOCKS ARE SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-8: with team mode off the prompt is BYTE-IDENTICAL to
+ * the pre-team output for a fixed tool array. An unconditional guidance line
+ * anywhere here would quietly break `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * `TEAM_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { TEAM_BLOCK_VERSION } from './limits.js';
+export { TEAM_BLOCK_VERSION };
+export interface TeamBlockParams {
+    maxSubagents: number;
+    maxConcurrent: number;
+}
+/**
+ * The lead's `<team_mode>` block. Under 1200 characters on purpose: it is paid
+ * for on EVERY turn of every team-enabled session, so anything that does not
+ * change a delegation decision does not belong in it.
+ *
+ * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
+ * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
+ * that informs it.
+ */
+export declare function buildTeamBlock(params: TeamBlockParams): string;
+export interface SubagentBlockParams {
+    label: string;
+    description: string;
+    /** Sibling labels, excluding this child's own. */
+    peers: string[];
+}
+/**
+ * The child's `<subagent_role>` block.
+ *
+ * "YOUR FINAL MESSAGE IS THE ONLY THING YOUR LEAD SEES" is load-bearing rather
+ * than decorative: `SubagentRun.summary` is literally the last assistant text of
+ * the child's history, so a child that signs off with "Let me know if you want
+ * more detail!" produces a useless report entry and there is no mechanism that
+ * can repair it after the fact. Wording is the only enforcement available, so it
+ * is stated in imperative terms (R-12).
+ */
+export declare function buildSubagentBlock(params: SubagentBlockParams): string;

package/dist/team/prompt.js

@@ -0,0 +1,87 @@
+/**
+ * The two system-prompt blocks team mode adds (team-subagents §4.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * BOTH BLOCKS ARE SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-8: with team mode off the prompt is BYTE-IDENTICAL to
+ * the pre-team output for a fixed tool array. An unconditional guidance line
+ * anywhere here would quietly break `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * `TEAM_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { TEAM_BLOCK_VERSION, TEAM_LIMITS } from './limits.js';
+export { TEAM_BLOCK_VERSION };
+/**
+ * The lead's `<team_mode>` block. Under 1200 characters on purpose: it is paid
+ * for on EVERY turn of every team-enabled session, so anything that does not
+ * change a delegation decision does not belong in it.
+ *
+ * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
+ * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
+ * that informs it.
+ */
+export function buildTeamBlock(params) {
+    const max = Math.max(1, Math.floor(params.maxSubagents));
+    const concurrent = Math.max(1, Math.min(Math.floor(params.maxConcurrent), max));
+    return [
+        '<team_mode>',
+        `You can delegate to parallel subagents with the task tool (up to ${max} per`,
+        `call, ${concurrent} running at once).`,
+        '',
+        'Delegate when: the work splits into 2+ parts that do not need each other\'s',
+        'output; several areas must be read or searched at once; a long build or test',
+        'run can proceed while another part is investigated.',
+        '',
+        'Do not delegate when: one part needs another part\'s result (do those in order',
+        'yourself); two parts would edit the same file; the whole job is a few edits.',
+        'One well-scoped subagent is better than four vague ones. Two to four is the',
+        'usual size; more than that is rarely faster.',
+        '',
+        'Each subagent starts with no memory of this conversation, so its prompt must',
+        'carry everything it needs: the goal, the files or areas it owns, and what to',
+        'report back. Give each one a disjoint set of files to write. Subagents cannot',
+        'dispatch further subagents and cannot ask the user anything.',
+        '',
+        'You get one combined report when they all finish. Read it before deciding what',
+        'to do next, and tell the user what the team found in your own words.',
+        '</team_mode>',
+    ].join('\n');
+}
+/**
+ * The child's `<subagent_role>` block.
+ *
+ * "YOUR FINAL MESSAGE IS THE ONLY THING YOUR LEAD SEES" is load-bearing rather
+ * than decorative: `SubagentRun.summary` is literally the last assistant text of
+ * the child's history, so a child that signs off with "Let me know if you want
+ * more detail!" produces a useless report entry and there is no mechanism that
+ * can repair it after the fact. Wording is the only enforcement available, so it
+ * is stated in imperative terms (R-12).
+ */
+export function buildSubagentBlock(params) {
+    const peers = params.peers.length > 0
+        ? `Teammates: ${params.peers.join(', ')}. You cannot see their conversations and they cannot see yours.`
+        : 'You are the only subagent on this task.';
+    return [
+        '<subagent_role>',
+        `You are subagent "${params.label}" on a team. Your job: ${params.description}.`,
+        peers,
+        '',
+        'Work only on your own task. Do not edit files another subagent owns. You cannot',
+        'delegate further and there is no user to ask - if something is ambiguous, choose',
+        'the most reasonable reading, proceed, and say what you assumed.',
+        '',
+        `To reach a teammate use team_send (at most ${TEAM_LIMITS.messagesPerAgent} messages, one every`,
+        `${Math.round(TEAM_LIMITS.minSendIntervalMs / 1000)} seconds). Their replies arrive attached to your next tool result.`,
+        'Use team_wait only when you genuinely cannot continue without an answer.',
+        '',
+        'END WITH YOUR REPORT. Your final message is the only thing your lead sees. It',
+        'must state: what you did, what you found, every file you changed, and anything',
+        'still open. Be concrete and brief - no preamble, no restating this brief.',
+        '</subagent_role>',
+    ].join('\n');
+}

package/dist/team/report.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `buildDispatchReport` — the single text the lead receives back from `task`
+ * (team-subagents §3.7).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * BUDGETS ARE IN BYTES, NOT CHARACTERS (D-8 / I-9). `ToolExecutor` truncates
+ * combined tool text at 100 000 BYTES and appends `... [truncated]`; 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 because the header is FIRST,
+ * what it would chop off is the tail, but a report assembled the other way round
+ * would lose its own failure count. Hence the second rule below.
+ *
+ * HEADER FIRST, ALWAYS. When the budget is exhausted the SUMMARIES are trimmed
+ * (longest first, each to a floor, with an explicit `[trimmed]` marker); the
+ * header, the per-agent status lines and the conflict warning are never dropped.
+ * A report that loses its own failure count is worse than one that loses prose.
+ *
+ * A FAILED CHILD NEVER FAILS THE DISPATCH (D-14). Partial results are the normal
+ * outcome of a fan-out; an all-or-nothing result would throw away four successes
+ * because of one HTTP 429.
+ */
+import type { ModelCost } from '@aragon-agent/core';
+import type { DispatchOutcome, SubagentRun } from './types.js';
+export interface ReportOptions {
+    /** The lead's model cost table, so the header can state real spend (R-5). */
+    cost?: ModelCost;
+}
+/**
+ * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.
+ *
+ * Slicing the buffer blindly at a byte offset produces a replacement character
+ * in the middle of a CJK report — the exact failure D-8 exists to prevent, just
+ * one layer lower down.
+ */
+export declare function truncateBytes(text: string, maxBytes: number): string;
+/**
+ * Files written by more than one child.
+ *
+ * PHRASED AS A WARNING, NEVER AS A FACT. `filesTouched` only sees `write_file` /
+ * `edit_file`, so a child that writes through `bash` is invisible to it (R-2).
+ * "review before trusting either" is honest about that; "these two conflict"
+ * would not be.
+ */
+export declare function findFileConflicts(runs: SubagentRun[]): Array<{
+    path: string;
+    labels: string[];
+}>;
+/**
+ * Assemble the report.
+ *
+ * Trimming order: every summary starts clamped to `summaryMaxBytes`; if the
+ * whole document is still over `reportMaxBytes`, the LONGEST summary is halved
+ * repeatedly (never below `summaryFloorBytes`) until it fits or every summary is
+ * at the floor. Only then, as a last resort, are summaries dropped entirely —
+ * and even then the status lines survive, because they carry the failure count.
+ */
+export declare function buildDispatchReport(outcome: DispatchOutcome, options?: ReportOptions): string;

package/dist/team/report.js

@@ -0,0 +1,205 @@
+/**
+ * `buildDispatchReport` — the single text the lead receives back from `task`
+ * (team-subagents §3.7).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * BUDGETS ARE IN BYTES, NOT CHARACTERS (D-8 / I-9). `ToolExecutor` truncates
+ * combined tool text at 100 000 BYTES and appends `... [truncated]`; 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 because the header is FIRST,
+ * what it would chop off is the tail, but a report assembled the other way round
+ * would lose its own failure count. Hence the second rule below.
+ *
+ * HEADER FIRST, ALWAYS. When the budget is exhausted the SUMMARIES are trimmed
+ * (longest first, each to a floor, with an explicit `[trimmed]` marker); the
+ * header, the per-agent status lines and the conflict warning are never dropped.
+ * A report that loses its own failure count is worse than one that loses prose.
+ *
+ * A FAILED CHILD NEVER FAILS THE DISPATCH (D-14). Partial results are the normal
+ * outcome of a fan-out; an all-or-nothing result would throw away four successes
+ * because of one HTTP 429.
+ */
+import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
+import { TEAM_LIMITS } from './limits.js';
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/**
+ * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.
+ *
+ * Slicing the buffer blindly at a byte offset produces a replacement character
+ * in the middle of a CJK report — the exact failure D-8 exists to prevent, just
+ * one layer lower down.
+ */
+export function truncateBytes(text, maxBytes) {
+    if (maxBytes <= 0)
+        return '';
+    if (byteLength(text) <= maxBytes)
+        return text;
+    const buf = Buffer.from(text, 'utf8');
+    let end = Math.min(maxBytes, buf.length);
+    // A continuation byte is 0b10xxxxxx; back off until `end` starts a sequence.
+    while (end > 0 && (buf[end] !== undefined) && (buf[end] & 0xc0) === 0x80)
+        end -= 1;
+    return buf.subarray(0, end).toString('utf8');
+}
+/** `ok` / `aborted` / `failed: <reason>` — the bracketed badge on a section head. */
+function statusBadge(run) {
+    if (run.phase === 'aborted')
+        return '[aborted]';
+    if (run.phase === 'failed' || run.error) {
+        return `[failed: ${run.error ?? 'run produced no output'}]`;
+    }
+    if (run.truncated)
+        return '[stopped: turn cap reached]';
+    return '[ok]';
+}
+function elapsed(run) {
+    if (run.startedAt === undefined)
+        return '0.0s';
+    return formatDuration(Math.max(0, (run.endedAt ?? run.startedAt) - run.startedAt));
+}
+function isOk(run) {
+    return run.phase === 'done' && !run.error;
+}
+/**
+ * Files written by more than one child.
+ *
+ * PHRASED AS A WARNING, NEVER AS A FACT. `filesTouched` only sees `write_file` /
+ * `edit_file`, so a child that writes through `bash` is invisible to it (R-2).
+ * "review before trusting either" is honest about that; "these two conflict"
+ * would not be.
+ */
+export function findFileConflicts(runs) {
+    const owners = new Map();
+    for (const run of runs) {
+        for (const path of run.filesTouched) {
+            const list = owners.get(path) ?? [];
+            if (!list.includes(run.label))
+                list.push(run.label);
+            owners.set(path, list);
+        }
+    }
+    const out = [];
+    for (const [path, labels] of owners) {
+        if (labels.length > 1)
+            out.push({ path, labels });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+function buildHeader(outcome, options) {
+    const lines = [];
+    const durationMs = Math.max(0, outcome.endedAt - outcome.startedAt);
+    if (outcome.aborted) {
+        // FIRST LINE on an abort, so the model cannot present partial work as
+        // complete without having read past it.
+        lines.push(`Team dispatch ABORTED after ${formatDuration(durationMs)}; partial results below.`);
+    }
+    const ok = outcome.runs.filter(isOk).length;
+    const failed = outcome.runs.length - ok;
+    const counts = `${ok} ok, ${failed} failed`;
+    lines.push(outcome.requested > outcome.runs.length
+        ? `Team dispatch: ran ${outcome.runs.length} of ${outcome.requested} requested subagents ` +
+            `(${counts}) in ${formatDuration(durationMs)}.`
+        : `Team dispatch: ${outcome.runs.length} of ${outcome.runs.length} subagents finished ` +
+            `(${counts}) in ${formatDuration(durationMs)}.`);
+    lines.push(`Tokens: in ${formatTokens(outcome.usage.inputTokens)}, out ` +
+        `${formatTokens(outcome.usage.outputTokens)}. Cost: ${formatCost(computeCost(outcome.usage, options.cost))}.`);
+    for (const conflict of findFileConflicts(outcome.runs)) {
+        const who = conflict.labels.map((l) => `"${l}"`).join(' and ');
+        lines.push(`WARNING: agents ${who} both wrote ${conflict.path} - review before trusting either.`);
+    }
+    return lines;
+}
+function buildSection(run) {
+    // `retried Nx` on the head line, which is never trimmed. 11 bytes, and it is
+    // the only place the lead learns that a child's first attempt died before it
+    // did anything (F-4).
+    const retried = run.retries ? `, retried ${run.retries}x` : '';
+    const head = [
+        `### ${run.label} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
+            `${run.turns} turns, ${run.toolCalls} tools${retried}`,
+    ];
+    if (run.filesTouched.length > 0)
+        head.push(`files: ${run.filesTouched.join(', ')}`);
+    // A child that tried to reach a teammate and could not is a child whose brief
+    // had a dependency the lead should not have split (F-3). One line, in a
+    // section that is trimmed last, and only when it actually happened.
+    if (run.blockedWaits)
+        head.push(`blocked waits: ${run.blockedWaits} (no teammate could answer)`);
+    const summary = (run.summary ?? '').trim();
+    return { head, summary: summary.length > 0 ? summary : '(no summary)' };
+}
+function buildLeadMail(outcome) {
+    if (outcome.leadMail.length === 0)
+        return [];
+    const lines = ['### Messages to you'];
+    for (const m of outcome.leadMail) {
+        const at = Math.max(0, Math.round((m.at - outcome.startedAt) / 1000));
+        lines.push(`[${m.from} -> lead] "${m.subject}" (${at}s in)`);
+        if (m.body.length > 0)
+            lines.push(m.body);
+    }
+    return lines;
+}
+/**
+ * Assemble the report.
+ *
+ * Trimming order: every summary starts clamped to `summaryMaxBytes`; if the
+ * whole document is still over `reportMaxBytes`, the LONGEST summary is halved
+ * repeatedly (never below `summaryFloorBytes`) until it fits or every summary is
+ * at the floor. Only then, as a last resort, are summaries dropped entirely —
+ * and even then the status lines survive, because they carry the failure count.
+ */
+export function buildDispatchReport(outcome, options = {}) {
+    const header = buildHeader(outcome, options);
+    const sections = outcome.runs.map(buildSection);
+    const mail = buildLeadMail(outcome);
+    const summaries = sections.map((s) => truncateBytes(s.summary, TEAM_LIMITS.summaryMaxBytes));
+    const trimmed = summaries.map((s, i) => s.length < sections[i].summary.length);
+    const render = (bodies) => {
+        const blocks = [header.join('\n')];
+        sections.forEach((section, i) => {
+            const body = bodies[i];
+            const lines = [...section.head];
+            if (body !== null && body !== undefined) {
+                lines.push(trimmed[i] ? `${body}\n[trimmed]` : body);
+            }
+            blocks.push(lines.join('\n'));
+        });
+        if (mail.length > 0)
+            blocks.push(mail.join('\n'));
+        return blocks.join('\n\n');
+    };
+    let bodies = [...summaries];
+    let out = render(bodies);
+    let guard = 0;
+    while (byteLength(out) > TEAM_LIMITS.reportMaxBytes && guard < 200) {
+        guard += 1;
+        let longest = -1;
+        let longestBytes = TEAM_LIMITS.summaryFloorBytes;
+        bodies.forEach((body, i) => {
+            if (body === null)
+                return;
+            const size = byteLength(body);
+            if (size > longestBytes) {
+                longest = i;
+                longestBytes = size;
+            }
+        });
+        if (longest < 0)
+            break; // Every summary is at the floor.
+        const next = Math.max(TEAM_LIMITS.summaryFloorBytes, Math.floor(longestBytes / 2));
+        bodies[longest] = truncateBytes(bodies[longest], next);
+        trimmed[longest] = true;
+        out = render(bodies);
+    }
+    if (byteLength(out) > TEAM_LIMITS.reportMaxBytes) {
+        // Last resort. The header, the status lines and the conflict warning are
+        // still here, which is the whole point of assembling them separately.
+        bodies = bodies.map(() => null);
+        out = render(bodies);
+    }
+    return out;
+}

package/dist/team/retry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The cold-start retry decision (team-live-activity F-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * RETRY IS SAFE ONLY WHEN THE CHILD PROVABLY DID NOTHING. `turns === 0 &&
+ * toolCalls === 0` is the side-effect proof: no turn completed, so nothing was
+ * written to the transcript, and no tool ran, so nothing was written to disk.
+ * Everything else about the child is fresh by construction.
+ *
+ * THE TRAP IS THAT EVERY ABORT LOOKS RETRYABLE. `wrapFetchError` in
+ * `packages/core` classifies an `AbortError` as `errorType: 'timeout'` with
+ * `retryable: true`, and every abort in this system reaches the provider as an
+ * aborted fetch - so a user pressing Esc produces a "retryable" error. The
+ * predicate below does NOT see that, and must not be asked to: `TeamRuntime`
+ * excludes the abort paths before it ever calls the predicate, and there are
+ * exactly four of them (user Esc / `AgentController.abort()`, the `task` tool's
+ * `ctx.signal`, the dispatch timeout - all three via `this.aborted` - and the
+ * per-child timeout via the local `timedOut` flag). The turn-cap abort is
+ * excluded twice over, by `run.truncated` here and by `turns === 0`.
+ *
+ * There is a fifth guard and it is DEFENCE IN DEPTH, NOT A SUBSTITUTE. The core
+ * agent loop tests `ctx.signal.aborted` at the top of every stream iteration and
+ * breaks BEFORE emitting `message_update`, so on an aborted request the
+ * provider's `error` event never reaches a subscriber and `run.retryable` is
+ * never even set. That is a property of a `break` in another package that no
+ * test in this repo pins; it could change under a refactor of core's steering
+ * handling without anyone here noticing. The four exclusions stay, and the
+ * acceptance test keeps asserting all four from this side of the boundary.
+ */
+import type { SubagentRun } from './types.js';
+/**
+ * Read `retryable` STRUCTURALLY rather than with `instanceof LLMError`.
+ *
+ * The error is constructed inside `packages/core` and crosses a package
+ * boundary; a duplicated core instance (a linked checkout, a hoisting accident)
+ * would make `instanceof` false while the field is plainly there, and the
+ * failure mode would be "retries silently stopped happening". `formatStreamError`
+ * reads `errorType` exactly this way for the same reason (reducer.ts).
+ */
+export declare function isRetryableStreamError(err: unknown): boolean;
+/**
+ * Whether this attempt may be replaced by a fresh child.
+ *
+ * `attemptsSoFar` counts the attempt that just ended, so the first failure calls
+ * this with `1` and `maxColdStartRetries` of 1 permits exactly one replacement.
+ */
+export declare function shouldRetryColdStart(run: SubagentRun, attemptsSoFar: number): boolean;

package/dist/team/retry.js

@@ -0,0 +1,56 @@
+/**
+ * The cold-start retry decision (team-live-activity F-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * RETRY IS SAFE ONLY WHEN THE CHILD PROVABLY DID NOTHING. `turns === 0 &&
+ * toolCalls === 0` is the side-effect proof: no turn completed, so nothing was
+ * written to the transcript, and no tool ran, so nothing was written to disk.
+ * Everything else about the child is fresh by construction.
+ *
+ * THE TRAP IS THAT EVERY ABORT LOOKS RETRYABLE. `wrapFetchError` in
+ * `packages/core` classifies an `AbortError` as `errorType: 'timeout'` with
+ * `retryable: true`, and every abort in this system reaches the provider as an
+ * aborted fetch - so a user pressing Esc produces a "retryable" error. The
+ * predicate below does NOT see that, and must not be asked to: `TeamRuntime`
+ * excludes the abort paths before it ever calls the predicate, and there are
+ * exactly four of them (user Esc / `AgentController.abort()`, the `task` tool's
+ * `ctx.signal`, the dispatch timeout - all three via `this.aborted` - and the
+ * per-child timeout via the local `timedOut` flag). The turn-cap abort is
+ * excluded twice over, by `run.truncated` here and by `turns === 0`.
+ *
+ * There is a fifth guard and it is DEFENCE IN DEPTH, NOT A SUBSTITUTE. The core
+ * agent loop tests `ctx.signal.aborted` at the top of every stream iteration and
+ * breaks BEFORE emitting `message_update`, so on an aborted request the
+ * provider's `error` event never reaches a subscriber and `run.retryable` is
+ * never even set. That is a property of a `break` in another package that no
+ * test in this repo pins; it could change under a refactor of core's steering
+ * handling without anyone here noticing. The four exclusions stay, and the
+ * acceptance test keeps asserting all four from this side of the boundary.
+ */
+import { TEAM_LIMITS } from './limits.js';
+/**
+ * Read `retryable` STRUCTURALLY rather than with `instanceof LLMError`.
+ *
+ * The error is constructed inside `packages/core` and crosses a package
+ * boundary; a duplicated core instance (a linked checkout, a hoisting accident)
+ * would make `instanceof` false while the field is plainly there, and the
+ * failure mode would be "retries silently stopped happening". `formatStreamError`
+ * reads `errorType` exactly this way for the same reason (reducer.ts).
+ */
+export function isRetryableStreamError(err) {
+    return err?.retryable === true;
+}
+/**
+ * Whether this attempt may be replaced by a fresh child.
+ *
+ * `attemptsSoFar` counts the attempt that just ended, so the first failure calls
+ * this with `1` and `maxColdStartRetries` of 1 permits exactly one replacement.
+ */
+export function shouldRetryColdStart(run, attemptsSoFar) {
+    return (attemptsSoFar <= TEAM_LIMITS.maxColdStartRetries &&
+        run.retryable === true &&
+        run.turns === 0 &&
+        run.toolCalls === 0 &&
+        !run.truncated);
+}

package/dist/team/runtime.d.ts

@@ -0,0 +1,122 @@
+/**
+ * TeamRuntime — dispatch scheduling, budgets, the `TeamEvent` stream, abort and
+ * disposal (team-subagents §3.2 / §3.5 / §3.8).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * ALL CONCURRENCY LIVES INSIDE ONE TOOL EXECUTION (I-1 / D-1). The core agent
+ * loop runs tool calls strictly sequentially, and that is not an accident to be
+ * "fixed": plan mode's human-input bridge holds ONE outstanding request slot and
+ * is correct only because tool calls never overlap (I-P11). So `task` takes a
+ * BATCH and the fan-out is scheduled here, where it is ours to control. Anyone
+ * tempted to make `agent-loop.ts` concurrent to "fix" parallel delegation is
+ * about to silently mis-route a plan approval to a question wizard.
+ *
+ * The scheduler is a plain slot pool: an index cursor plus `maxConcurrent`
+ * worker loops, awaited with `Promise.allSettled`. No worker abstraction, no
+ * queue class, no event-loop trickery — every path is observable from the event
+ * stream.
+ */
+import type { ProviderRegistry, SkillRegistry, ToolPolicyDecision, ToolPolicyVerdict } from '@aragon-agent/core';
+import type { AgentMode } from '../agent/agent-mode.js';
+import type { CliConfig } from '../config/schema.js';
+import type { TeamHumanQueue } from './human-queue.js';
+import { type SubagentAgentFactory } from './subagent.js';
+import type { DispatchOutcome, SubagentSpec, TeamEventListener, TeamSnapshot } from './types.js';
+export interface TeamRuntimeDeps {
+    /** Read LIVE: a settings-screen model or key edit must reach the next dispatch. */
+    getConfig: () => CliConfig;
+    providerRegistry: ProviderRegistry;
+    getCwd: () => string;
+    getMode: () => AgentMode;
+    getApiKey: (providerId: string) => string | undefined;
+    skillRegistry?: SkillRegistry;
+    alwaysBlock?: () => string;
+    toolPolicy?: () => ToolPolicyDecision;
+    onChildToolPolicyEvent?: (e: {
+        label: string;
+        tool: string;
+        verdict: ToolPolicyVerdict;
+        sourceNames: string[];
+    }) => void;
+    humanQueue?: TeamHumanQueue;
+    /** Test seam (§8.1): a stub factory keeps the whole scheduler off the network. */
+    agentFactory?: SubagentAgentFactory;
+}
+export declare class TeamRuntime {
+    private readonly deps;
+    private readonly listeners;
+    private live;
+    private bus;
+    private snapshotState;
+    private busy;
+    private aborted;
+    private counter;
+    private dispatchTimer;
+    /**
+     * Every in-flight retry backoff, so an abort releases ALL of them (P1-7).
+     *
+     * A SET, NOT ONE FIELD, and the plural is load-bearing: the failure that
+     * triggers a cold start is usually provider-wide, so a 429 fails every
+     * in-flight child's first request in the same tick and up to `maxConcurrent`
+     * children enter backoff together. With a single stored resolver two of three
+     * are overwritten and only the last is released, so "an abort during the
+     * backoff window ends the dispatch promptly" would hold for one child and
+     * quietly not for the others.
+     */
+    private readonly pendingBackoffs;
+    constructor(deps: TeamRuntimeDeps);
+    subscribe(listener: TeamEventListener): () => void;
+    /**
+     * Unreachable while I-1 holds, and present anyway so "only one dispatch at a
+     * time" is a property of THIS module rather than a consequence of another
+     * package's loop shape (R-14).
+     */
+    isBusy(): boolean;
+    /** The live roster, for `/team` status. `null` when nothing is dispatching. */
+    snapshot(): TeamSnapshot | null;
+    dispatch(specs: SubagentSpec[], requested: number, signal?: AbortSignal): Promise<DispatchOutcome>;
+    /** One slot of the pool: take the next index until the list is exhausted. */
+    private worker;
+    /**
+     * Run one child to a terminal phase, replacing it once if its very first
+     * request died on a transport error before it did anything at all (F-4).
+     */
+    private runOne;
+    /**
+     * Swap a cold-started child for a fresh one, carrying only what must survive.
+     *
+     * `this.live` IS `handles`, so the single assignment below also makes
+     * `abortAll()` abort the NEW child and makes the outcome carry the new run.
+     * Anyone tempted to "clean up" that aliasing into a defensive copy must update
+     * both places.
+     */
+    private replaceForRetry;
+    /**
+     * The final phase of an attempt, in a FIXED ORDER: aborted, then timed out,
+     * then error, then no-summary, then done.
+     *
+     * Extracted verbatim so the retry loop has one exit and the order lives in one
+     * place.
+     */
+    private settlePhase;
+    /**
+     * Sleep, releasing early when the dispatch aborts.
+     *
+     * The timer is `unref`'d so a pending backoff cannot hold the process open on
+     * exit, and the resolver is registered in `pendingBackoffs` so `abortAll()`
+     * releases EVERY one of them rather than only the last (P1-7).
+     */
+    private backoff;
+    /**
+     * Stop every child and settle every blocking wait.
+     *
+     * Idempotent, and safe to call when nothing is running — `AgentController.abort()`
+     * calls it unconditionally.
+     */
+    abortAll(): void;
+    /** Process-exit path: abort everything and clear timers (R-15). */
+    dispose(): void;
+    private publish;
+    private emit;
+}