@aragon-agent/cli 0.6.39 → 0.6.42

package/dist/skills/triage.js

@@ -0,0 +1,393 @@
+/**
+ * Deterministic skill routing for the pre-work triage step
+ * (skill-triage-and-unbounded-ask §4.2.2).
+ *
+ * WHY THIS IS NOT AN LLM CALL (D-11). The question "which installed skill, if any,
+ * covers this task?" is answered against data the process already holds: the
+ * `SkillRecord` set in `SkillRegistry`, with a name, a one-line description and a
+ * keyword list. A model call would add a round trip, latency and — the decisive
+ * point — untestability, because a router that is itself a model can only be
+ * asserted on statistically. This module is a pure function of its inputs, so the
+ * whole feature has unit tests instead of anecdotes.
+ *
+ * WHAT IT IS ALLOWED TO TOUCH. Records only. No filesystem, no `SKILL.md` read,
+ * no network, no clock (invariant I-T2, asserted by a source-scanning test). That
+ * is what makes the disclosure ladder real: "which skills exist" costs zero
+ * context bytes and zero IO, and the expensive Level 2 body is paid for only when
+ * the model actually calls `skill(name)`.
+ *
+ * BOTH SCRIPTS ARE HANDLED. The user writes tasks in Chinese and English, and
+ * skill descriptions are usually English. Space-separated tokens alone score zero
+ * on CJK text, so a run of Han/Kana/Hangul characters is tokenized into bigrams
+ * (plus the whole run when it is short enough for a phrase match to be likely).
+ *
+ * ASCII ONLY IN LITERALS: `skills/` is outside the glyph scanner's scope today,
+ * but new text keeps the same rule rather than assuming a scanner will never
+ * cover it.
+ */
+export const SKILL_TRIAGE_LIMITS = {
+    maxCandidates: 3,
+    minScore: 4,
+    confidentScore: 9,
+    maxBlockBytes: 900,
+    maxProtocolBytes: 1500,
+    maxTaskChars: 2000,
+    maxTokens: 64,
+    latinTokenMinChars: 3,
+    cjkMinRunChars: 2,
+    maxCjkGramsPerRun: 24,
+    maxWholeRunChars: 32,
+    maxNameChars: 40,
+    descLineChars: 160,
+    reasonChars: 32,
+};
+// ---------------------------------------------------------------------------
+// Scoring constants
+// ---------------------------------------------------------------------------
+const TRIAGE_WEIGHTS = { mentioned: 12, nameToken: 5, keyword: 4, description: 2 };
+const TRIAGE_CAPS = { nameTokens: 2, keywords: 4, descriptions: 3 };
+/**
+ * Scope precedence, HIGHEST first.
+ *
+ * DELIBERATELY A COPY of `SCOPE_RANK` in core's `disclosure.ts`, which is a
+ * module-private constant and not part of the published surface (D-12 forbids
+ * changing core to export it). The duplication is allowed; letting it DRIFT is
+ * not, which is why `triage.test.ts` pins this ordering against
+ * `catalogRecords()` rather than against a hand-written list.
+ */
+const TRIAGE_SCOPE_RANK = {
+    env: 0,
+    project: 1,
+    user: 2,
+    bundled: 3,
+};
+/**
+ * Words that carry no routing signal. Kept deliberately short: a stopword list is
+ * a blunt instrument, and every entry here is a token that can no longer match a
+ * skill description.
+ */
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'for', 'with', 'when', 'use', 'using', 'make',
+    'please', 'this', 'that', 'from', 'into', 'all', 'can', 'you', 'your', 'our',
+    'it', 'is', 'are', 'to', 'of', 'in', 'on',
+]);
+/**
+ * Latin words.
+ *
+ * `-` AND `_` ARE SEPARATORS, NOT WORD CHARACTERS, and that is what makes
+ * `pdf-forms` yield `pdf` *and* `forms`. Two reasons, both structural:
+ *
+ *  1. `normalizeHaystack` folds exactly those two characters to spaces, so a token
+ *     that still contained one could never be a substring of any haystack — it
+ *     would be a token that can only ever score zero.
+ *  2. A kebab skill name is the most likely phrase a user types verbatim, and
+ *     AC-T1 requires the parts to be individually searchable. The whole phrase is
+ *     still recognised, by `mentioned`, which is worth more than a single token.
+ *
+ * `.`, `+` and `#` stay INSIDE tokens because they survive folding: `package.json`,
+ * `c++` and `c#` are what the user typed and what a description says.
+ */
+const LATIN_TOKEN = /[a-z0-9][a-z0-9+#.]*/g;
+const CJK_RUN = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]+/g;
+/** One encoder for the whole module; `Buffer` is a Node global and this is not. */
+const ENCODER = new TextEncoder();
+function byteLength(text) {
+    return ENCODER.encode(text).length;
+}
+// ---------------------------------------------------------------------------
+// Tokenizing
+// ---------------------------------------------------------------------------
+/**
+ * Task text to a token set, Latin words and CJK bigrams mixed together.
+ *
+ * DETERMINISTIC BY CONSTRUCTION: no random sampling, no clock, no iteration over a
+ * `Set` whose insertion order depends on anything but the input. AC-T3 asserts
+ * that two calls on the same input are `deepEqual`.
+ */
+export function tokenizeTask(text, limits = SKILL_TRIAGE_LIMITS) {
+    const task = text.slice(0, limits.maxTaskChars).toLowerCase();
+    const tokens = [];
+    const seen = new Set();
+    const push = (token) => {
+        if (seen.has(token))
+            return false;
+        seen.add(token);
+        tokens.push(token);
+        return tokens.length < limits.maxTokens;
+    };
+    for (const match of task.matchAll(LATIN_TOKEN)) {
+        const token = match[0];
+        if (token.length < limits.latinTokenMinChars)
+            continue;
+        if (STOPWORDS.has(token))
+            continue;
+        if (!push(token))
+            return tokens;
+    }
+    for (const match of task.matchAll(CJK_RUN)) {
+        const run = match[0];
+        if (run.length < limits.cjkMinRunChars)
+            continue;
+        // Short runs are a single meaningful word ("表单", "重试"), so the run itself
+        // is the token. Long runs additionally yield bigrams, which is what lets
+        // "修复登录接口的超时重试逻辑" match a description containing "重试".
+        if (run.length <= 6) {
+            if (!push(run))
+                return tokens;
+            continue;
+        }
+        for (const gram of cjkBigrams(run, limits.maxCjkGramsPerRun)) {
+            if (!push(gram))
+                return tokens;
+        }
+        if (run.length <= limits.maxWholeRunChars) {
+            if (!push(run))
+                return tokens;
+        }
+    }
+    return tokens;
+}
+/**
+ * Bigrams of a long CJK run, capped at `max` by EVEN SAMPLING rather than by
+ * taking a prefix.
+ *
+ * A prefix would only ever describe the beginning of the sentence, and the words
+ * that matter in "帮我修复一下登录接口在超时之后的重试逻辑" are near the end. Even
+ * sampling keeps the whole run represented, and is a fixed arithmetic rule, so the
+ * result is still deterministic.
+ */
+function cjkBigrams(run, max) {
+    const total = run.length - 1;
+    if (total <= max) {
+        const grams = [];
+        for (let i = 0; i < total; i += 1)
+            grams.push(run.slice(i, i + 2));
+        return grams;
+    }
+    const grams = [];
+    const used = new Set();
+    for (let step = 0; step < max; step += 1) {
+        const index = Math.floor((step * total) / max);
+        if (used.has(index))
+            continue;
+        used.add(index);
+        grams.push(run.slice(index, index + 2));
+    }
+    return grams;
+}
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+/**
+ * Score one record against the task (44 is the ceiling: 12 + 5*2 + 4*4 + 2*3).
+ *
+ * THE THREE HAYSTACKS ARE SEPARATE on purpose. A token found in `keywords` is a
+ * deliberate author signal and scores 4; the same token found only in the prose
+ * description scores 2. Merging them into one string would make every keyword hit
+ * look like a description hit as well, inflating the score on exactly the records
+ * whose authors were least specific.
+ *
+ * `record.frontmatter.keywords`, never `record.keywords`: `SkillRecord` has no
+ * top-level keyword field, and both keywords and `activation` hang off
+ * `frontmatter`.
+ */
+export function scoreSkill(record, tokens, taskText) {
+    const nameHay = normalizeHaystack(record.name);
+    const keywordHay = normalizeHaystack(record.frontmatter.keywords.join(' '));
+    const descHay = normalizeHaystack(record.description);
+    let nameHits = 0;
+    let keywordHits = 0;
+    let descHits = 0;
+    for (const token of tokens) {
+        if (nameHits < TRIAGE_CAPS.nameTokens && nameHay.includes(token)) {
+            nameHits += 1;
+            continue;
+        }
+        if (keywordHits < TRIAGE_CAPS.keywords && keywordHay.includes(token)) {
+            keywordHits += 1;
+            continue;
+        }
+        if (descHits < TRIAGE_CAPS.descriptions && descHay.includes(token))
+            descHits += 1;
+    }
+    const mentioned = isMentioned(record.name, taskText);
+    const reasons = [];
+    if (nameHits > 0 || mentioned)
+        reasons.push('name');
+    if (keywordHits > 0)
+        reasons.push('keyword');
+    if (descHits > 0)
+        reasons.push('description');
+    const score = (mentioned ? TRIAGE_WEIGHTS.mentioned : 0) +
+        nameHits * TRIAGE_WEIGHTS.nameToken +
+        keywordHits * TRIAGE_WEIGHTS.keyword +
+        descHits * TRIAGE_WEIGHTS.description;
+    return { score, reasons, mentioned };
+}
+/** Lowercase, with `-` / `_` folded to spaces so `pdf-forms` matches "pdf forms". */
+function normalizeHaystack(text) {
+    return text.toLowerCase().replace(/[-_]+/g, ' ');
+}
+/** The skill's full name appears in the raw task, hyphenated or spaced. */
+function isMentioned(name, taskText) {
+    const haystack = taskText.toLowerCase();
+    return haystack.includes(name.toLowerCase())
+        || haystack.includes(name.toLowerCase().replace(/-+/g, ' '));
+}
+/**
+ * The candidate list alone — `buildRoutingReport` minus the report.
+ *
+ * ONE PIPELINE, TWO VIEWS. This used to repeat the tokenize / rank / filter / slice
+ * sequence, which meant the candidate order and the report's `topUnqualified` were
+ * produced by two pieces of code that had to be kept in agreement by hand: exactly
+ * the drift `rankEligible`'s single comparator exists to prevent. The report owns
+ * the arithmetic; this is the projection of it for a caller who does not want
+ * `at` / `eligible` / `topUnqualified`.
+ */
+export function selectSkillCandidates(input) {
+    return buildRoutingReport(input).candidates;
+}
+/**
+ * Every eligible record with its score, best first — the shared middle of
+ * `selectSkillCandidates` and `buildRoutingReport`.
+ *
+ * Filters, then sorts with ONE comparator so the candidate list and the
+ * "runner-up" line can never disagree about which record is better: score
+ * descending, then scope precedence, then name. Records that scored zero are
+ * dropped here — they carry no signal and would only pad `topUnqualified` with an
+ * arbitrary name.
+ */
+function rankEligible(records, tokens, task, active) {
+    return records
+        .filter((record) => isEligible(record, active))
+        .map((record) => ({ record, ...scoreSkill(record, tokens, task) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        const rank = TRIAGE_SCOPE_RANK[a.record.scope] - TRIAGE_SCOPE_RANK[b.record.scope];
+        if (rank !== 0)
+            return rank;
+        return a.record.name.localeCompare(b.record.name, 'en');
+    });
+}
+function toCandidate(entry, limits) {
+    return {
+        name: entry.record.name,
+        scope: entry.record.scope,
+        description: truncateToChars(entry.record.description, limits.descLineChars),
+        score: entry.score,
+        reasons: entry.reasons.slice(0, 3),
+    };
+}
+function isEligible(record, active) {
+    if (record.disabled || record.invalid)
+        return false;
+    if (record.frontmatter.activation === 'manual')
+        return false;
+    return !active.has(record.name);
+}
+/**
+ * The router's whole decision, as one pure call — and the ONE place the arithmetic
+ * lives (`selectSkillCandidates` is a projection of it).
+ *
+ * THE FILTER IS THE SAME ONE `catalogRecords` AND `skill_find` USE (I-T4): not
+ * disabled, not invalid, not `activation: manual`, and not already active. It is
+ * re-implemented here rather than imported because the report needs the
+ * candidates' scores, and `catalogRecords` returns records. `triage.test.ts` pins
+ * this filter against `catalogRecords` so the two cannot drift apart silently.
+ *
+ * ORDER IS SCOPE FIRST, then name. That is NOT the order the user sees in
+ * `<available_skills>`, where `usageTracking` re-ranks by recent use
+ * (`service.ts:catalogBlock`). Intentional: the catalog answers "what have I used
+ * lately", the candidate list answers "what should I read first".
+ *
+ * `at` is the only non-derived field and it is display-only, so a test can pass a
+ * fixed value and compare two reports with `deepEqual`.
+ */
+export function buildRoutingReport(input) {
+    const limits = { ...SKILL_TRIAGE_LIMITS, ...input.limits };
+    const task = input.task.slice(0, limits.maxTaskChars);
+    const tokens = tokenizeTask(task, limits);
+    const active = new Set(input.activeNames);
+    const ranked = rankEligible(input.records, tokens, task, active);
+    const qualified = ranked.filter((entry) => entry.score >= limits.minScore);
+    const candidates = qualified.slice(0, limits.maxCandidates).map((e) => toCandidate(e, limits));
+    const runnerUp = ranked.find((entry) => entry.score < limits.minScore);
+    const best = candidates[0]?.score ?? 0;
+    return {
+        task,
+        tokenCount: tokens.length,
+        eligible: input.records.filter((record) => isEligible(record, active)).length,
+        candidates,
+        topUnqualified: runnerUp ? { name: runnerUp.record.name, score: runnerUp.score } : null,
+        decision: candidates.length === 0 ? 'none' : best >= limits.confidentScore ? 'confident' : 'suggest',
+        at: input.now ?? 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rendering (§4.2.2)
+// ---------------------------------------------------------------------------
+const CANDIDATES_OPEN = '<skill_candidates note="computed from your message, not a verdict - confirm before loading">';
+const CANDIDATES_CLOSE = '</skill_candidates>';
+/**
+ * The `<skill_candidates>` block, or `''` when there is nothing to propose.
+ *
+ * `''` is load-bearing: it is what keeps `buildSystemPrompt` byte-identical to the
+ * pre-feature text when triage finds nothing, so an empty result cannot leave an
+ * empty shell behind (I-T1).
+ *
+ * BUDGET DISCIPLINE, copied from `renderSkillCatalog`: reserve the worst-case
+ * overflow line UP FRONT, add lines while they fit, and on overflow drop whole
+ * lines rather than truncating text or the closing tag. A dropped candidate is
+ * visible as `(+N more not shown)`; a truncated one reads as a corrupt skill name.
+ */
+export function renderSkillCandidates(candidates, opts = {}) {
+    if (candidates.length === 0)
+        return '';
+    const limits = { ...SKILL_TRIAGE_LIMITS, ...opts.limits };
+    const maxBytes = opts.maxBytes ?? limits.maxBlockBytes;
+    const fixed = byteLength(CANDIDATES_OPEN) + byteLength(`\n${CANDIDATES_CLOSE}`);
+    const reserve = byteLength(`\n${overflowLine(candidates.length)}`);
+    const lines = [];
+    let used = fixed;
+    for (const candidate of candidates) {
+        const line = candidateLine(candidate, limits);
+        const cost = byteLength(`\n${line}`);
+        if (used + cost + reserve > maxBytes)
+            break;
+        lines.push(line);
+        used += cost;
+    }
+    const omitted = candidates.length - lines.length;
+    const parts = [CANDIDATES_OPEN, ...lines];
+    if (omitted > 0)
+        parts.push(overflowLine(omitted));
+    parts.push(CANDIDATES_CLOSE);
+    return parts.join('\n');
+}
+function overflowLine(count) {
+    return `(+${count} more not shown)`;
+}
+/**
+ * `- name (scope): description [reason]`
+ *
+ * THE NAME IS CUT HERE AND NOWHERE ELSE. A kebab directory name has no upstream
+ * length limit, so one 200-character name would otherwise consume the entire block
+ * and starve the candidates behind it. The cut is on the NAME only; the identity
+ * the controller tracks for "notified once" is `candidate.name`, whole.
+ */
+function candidateLine(candidate, limits) {
+    const name = truncateToChars(candidate.name, limits.maxNameChars);
+    const description = truncateToChars(candidate.description, limits.descLineChars);
+    const reason = truncateToChars(candidate.reasons.join(', '), limits.reasonChars);
+    const suffix = reason.length > 0 ? ` [${reason}]` : '';
+    return `- ${name} (${candidate.scope}): ${description}${suffix}`;
+}
+/** Collapse whitespace, then cut to `max` CHARACTERS with an ASCII ellipsis. */
+function truncateToChars(text, max) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (clean.length <= max)
+        return clean;
+    return `${clean.slice(0, Math.max(1, max - 3)).trimEnd()}...`;
+}

package/dist/team/dispatch-gate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The dispatch gate: the THIRD and only MECHANICAL layer of forced team mode
+ * (team-command-forced-dispatch §3.7 / §6.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A MECHANICAL LAYER EXISTS AT ALL. The directive and the prompt block are
+ * both requests, and a request can be declined. The requirement behind `/team`
+ * is a COMMITMENT - "after the lead plans, subagents must do the work" - so the
+ * one part of it that does not depend on the model's cooperation is a decision
+ * taken by the host after the turn has already ended. Everything here is a pure
+ * function of four facts the caller counted, which is what keeps `ui/App.tsx`
+ * to wiring rather than policy.
+ *
+ * THREE BOUNDS, AND NONE OF THEM IS DECORATION (D-8):
+ *  - `toolsUsed > 0`   - a pure question ("what did those two children find?")
+ *                        must be answerable from context; nudging it would buy a
+ *                        second dispatch of a fact already in the transcript.
+ *  - `nudgesUsed < 1`  - a model that will not dispatch must not turn into an
+ *                        unbounded paid loop. `FORCED_NUDGE_LIMIT` is the whole
+ *                        defence, and I-10 pins WHERE it is reset (the user's own
+ *                        submit, never `agent_start`) because a per-turn reset
+ *                        would make this bound disappear while every test stayed
+ *                        green.
+ *  - `!aborted && !errored` - Esc and a provider failure are not disobedience.
+ *                        Urging a re-dispatch after an error would spend money to
+ *                        reproduce the error.
+ *
+ * `dispatchAttempted` IS NOT `dispatched` (P1-7). The `task` tool refuses for
+ * three reasons that never emit `dispatch_start` - team off, dispatch busy, no
+ * API key - and each of those refusals is the upstream telling the model "no".
+ * Counting only real dispatches would have the gate say "you dispatched nothing,
+ * dispatch now", the model comply, and the same refusal arrive twice: two turns
+ * of noise around a fact both layers already knew.
+ */
+/** The four facts the caller counts, and the run's own verdict on itself. */
+export interface ForcedDispatchProbe {
+    /** `getForcedTeam() !== null`. */
+    armed: boolean;
+    /**
+     * The armed fan-out count, echoed into the nudge's first sentence.
+     *
+     * NOT IN §3.7's FIVE-FIELD PROBE, and the omission does not survive contact
+     * with §5.2: the decision carries the MESSAGE (`{ kind: 'nudge'; message }`)
+     * and `App` submits `gate.message` verbatim, so the number the nudge names has
+     * to reach this function somehow. Reading it here - from the same probe the
+     * gate already receives - keeps the decision a pure function of its argument
+     * instead of forcing the caller to rebuild the message and losing the guarantee
+     * that `buildDispatchNudge()` is the only author of those bytes. Ignored when
+     * `armed` is false (see `team-command-forced-dispatch` spec,
+     * `## 实施过程发现的方案缺陷`).
+     */
+    count: number;
+    /** This turn emitted `dispatch_start` OR called `task` at least once (even refused). */
+    dispatchAttempted: boolean;
+    /** Tool calls the MODEL made this turn. Zero means a pure answer. */
+    toolsUsed: number;
+    /** Fallback nudges already spent. Reset only by a user-initiated submit (I-10). */
+    nudgesUsed: number;
+    runEnd: {
+        aborted: boolean;
+        errored: boolean;
+    };
+}
+export type ForcedDispatchDecision = {
+    kind: 'none';
+} | {
+    kind: 'nudge';
+    message: string;
+};
+/** The line written to the USER before the nudge is submitted (§6.4). */
+export declare const FORCED_NUDGE_NOTICE = "Forced team mode: no dispatch last turn - asking the agent to dispatch now.";
+/**
+ * The nudge itself, verbatim from §6.4.
+ *
+ * It names a NUMBER and then immediately permits fewer, because the one thing
+ * worse than a missing dispatch is four children inventing work to justify
+ * themselves. The closing sentence repeats the directive's prohibition: this
+ * message is the model's whole context for the turn it is about to run.
+ */
+export declare function buildDispatchNudge(count: number): string;
+/**
+ * Should the host ask for one more turn? Every clause must hold, short-circuiting
+ * in the order the header records so a cheap fact answers before a costly one.
+ */
+export declare function decideForcedDispatch(probe: ForcedDispatchProbe): ForcedDispatchDecision;

package/dist/team/dispatch-gate.js

@@ -0,0 +1,75 @@
+/**
+ * The dispatch gate: the THIRD and only MECHANICAL layer of forced team mode
+ * (team-command-forced-dispatch §3.7 / §6.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * WHY A MECHANICAL LAYER EXISTS AT ALL. The directive and the prompt block are
+ * both requests, and a request can be declined. The requirement behind `/team`
+ * is a COMMITMENT - "after the lead plans, subagents must do the work" - so the
+ * one part of it that does not depend on the model's cooperation is a decision
+ * taken by the host after the turn has already ended. Everything here is a pure
+ * function of four facts the caller counted, which is what keeps `ui/App.tsx`
+ * to wiring rather than policy.
+ *
+ * THREE BOUNDS, AND NONE OF THEM IS DECORATION (D-8):
+ *  - `toolsUsed > 0`   - a pure question ("what did those two children find?")
+ *                        must be answerable from context; nudging it would buy a
+ *                        second dispatch of a fact already in the transcript.
+ *  - `nudgesUsed < 1`  - a model that will not dispatch must not turn into an
+ *                        unbounded paid loop. `FORCED_NUDGE_LIMIT` is the whole
+ *                        defence, and I-10 pins WHERE it is reset (the user's own
+ *                        submit, never `agent_start`) because a per-turn reset
+ *                        would make this bound disappear while every test stayed
+ *                        green.
+ *  - `!aborted && !errored` - Esc and a provider failure are not disobedience.
+ *                        Urging a re-dispatch after an error would spend money to
+ *                        reproduce the error.
+ *
+ * `dispatchAttempted` IS NOT `dispatched` (P1-7). The `task` tool refuses for
+ * three reasons that never emit `dispatch_start` - team off, dispatch busy, no
+ * API key - and each of those refusals is the upstream telling the model "no".
+ * Counting only real dispatches would have the gate say "you dispatched nothing,
+ * dispatch now", the model comply, and the same refusal arrive twice: two turns
+ * of noise around a fact both layers already knew.
+ */
+import { FORCED_NUDGE_LIMIT } from './limits.js';
+/** The line written to the USER before the nudge is submitted (§6.4). */
+export const FORCED_NUDGE_NOTICE = 'Forced team mode: no dispatch last turn - asking the agent to dispatch now.';
+/**
+ * The nudge itself, verbatim from §6.4.
+ *
+ * It names a NUMBER and then immediately permits fewer, because the one thing
+ * worse than a missing dispatch is four children inventing work to justify
+ * themselves. The closing sentence repeats the directive's prohibition: this
+ * message is the model's whole context for the turn it is about to run.
+ */
+export function buildDispatchNudge(count) {
+    return [
+        'Forced team mode is on and the last turn dispatched nothing. Call the `task` tool now',
+        `with ${count} subagents - or fewer if the work genuinely does not split - then report `
+            + 'their',
+        'combined result. Do not do the work yourself.',
+    ].join('\n');
+}
+/**
+ * Should the host ask for one more turn? Every clause must hold, short-circuiting
+ * in the order the header records so a cheap fact answers before a costly one.
+ */
+export function decideForcedDispatch(probe) {
+    if (!probe.armed)
+        return { kind: 'none' };
+    // A REFUSED `task` STILL COUNTS (P1-7): "attempted" is the honest predicate.
+    if (probe.dispatchAttempted)
+        return { kind: 'none' };
+    if (!(probe.toolsUsed > 0))
+        return { kind: 'none' };
+    if (probe.runEnd.aborted || probe.runEnd.errored)
+        return { kind: 'none' };
+    if (probe.nudgesUsed >= FORCED_NUDGE_LIMIT)
+        return { kind: 'none' };
+    // THE MESSAGE IS BUILT HERE, from the same probe, so `buildDispatchNudge()`
+    // stays the only author of these bytes and the caller can submit
+    // `decision.message` without reconstructing it.
+    return { kind: 'nudge', message: buildDispatchNudge(probe.count) };
+}

package/dist/team/forced-dispatch.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `/subagent` — parse the user's arguments and compile them into ONE user turn
+ * (subagent-fanout 3.5.2 / 3.5.4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and this module
+ * also produces text a model reads in a `cmd.exe` terminal.
+ *
+ * WHY A PROMPT AND NOT A DIRECT `dispatch()` CALL (D-8 / 3.5.1, option C). The
+ * alternative — the command splits the brief itself and calls
+ * `TeamRuntime.dispatch()` — needs a SECOND dispatch entry point (breaking I-1),
+ * a run lifecycle the command does not own (Esc, the lead's idle watchdog, the
+ * report rendered into the transcript, spend accounting, the concurrency lock),
+ * and a planner that cannot see the conversation. Compiling the user's intent
+ * into a normal user turn keeps all of that on the one path that already has it.
+ * The cost is that forcing is INSTRUCTION-LEVEL rather than mechanical, which is
+ * why the command body prints a plan ("the next turn dispatches them") instead
+ * of claiming results (D-10).
+ *
+ * TWO PURE FUNCTIONS, NO IO: parse and compile. Both are deterministic, so the
+ * whole surface is unit-testable without a terminal, a config file or a model.
+ */
+/**
+ * Bumped whenever the directive's wording changes; the string appears VERBATIM
+ * on the directive's first line so a behaviour report ties to one revision with
+ * a single grep (D-15). The `-YYYY-MM` suffix is part of the version, not a
+ * comment: `v1` alone is easy to confuse with the other counters in this package.
+ */
+export declare const FORCED_DISPATCH_VERSION = "v1-2026-10";
+export interface SubagentCommandArgs {
+    /** The task text, with flags stripped and whitespace collapsed. */
+    brief: string;
+    /** `null` when the user did not pass `-n` (the caller applies the default). */
+    count: number | null;
+    /** Already slugged, deduped, and capped at `TEAM_LIMITS.forcedPartsMax`. */
+    parts: string[];
+    /**
+     * How many usable parts the user asked for BEFORE the `forcedPartsMax` cap.
+     *
+     * THE ONE FIELD THE OBVIOUS FOUR COULD NOT CARRY. `--parts` has two ceilings -
+     * the structural 8 and the policy `maxSubagents` - and R-P1-3 requires BOTH to
+     * be disclosed ("asked for 11 parts, the first 8 are used"). A capped array
+     * cannot name what it dropped, so the count that was dropped is kept here; the
+     * command body is the only place that can also apply the policy ceiling.
+     */
+    partsRequested: number;
+    /** `--read-only`: every child refuses writes and shell. */
+    readOnly: boolean;
+}
+export type SubagentParseResult = {
+    ok: true;
+    args: SubagentCommandArgs;
+} | {
+    ok: false;
+    error: 'count' | 'conflict' | 'flag' | 'brief';
+    token?: string;
+};
+/**
+ * Parse `/subagent` arguments. ONE parameter (R-P1-1): the structural bounds are
+ * constants this module imports, not a caller's opinion.
+ *
+ * NEVER THROWS and never guesses. Every malformed input maps to one of the four
+ * errors the command body has a sentence for, because "we did something
+ * reasonable with your typo" is indistinguishable from a bug at the terminal.
+ */
+export declare function parseSubagentArgs(raw: string): SubagentParseResult;
+export interface ForcedDispatchRequest {
+    brief: string;
+    /** Already narrowed to `[1, maxSubagents]` by the command body. */
+    count: number;
+    readOnly: boolean;
+    /** Already narrowed to `maxSubagents`; may be empty. */
+    parts: string[];
+    /** The LIVE `team.maxSubagents`, quoted in the disclosure lines. */
+    maxSubagents: number;
+    /** True when `requested` exceeded what the config allows. */
+    clamped: boolean;
+    /**
+     * What the user ASKED for before narrowing - `-n 12` is 12, five parts are 5.
+     * Quoting the narrowed number instead would produce "you asked for 8; the
+     * configured maximum is 8", which says nothing (R-4).
+     */
+    requested: number;
+    /** Disclosed, never a reason to refuse (R-P2-6): plan mode may hide `task`. */
+    planMode: boolean;
+}
+/**
+ * The ONE user turn a `/subagent` invocation submits. Same input, same bytes -
+ * which is what makes the snapshot tests meaningful.
+ *
+ * THE ORDER OF THE SENTENCES IS THE ORDER OF THE MODEL'S DECISIONS: what to do
+ * (call `task` ONCE), what it must not do instead (work alone), then the lucky
+ * case (the brief does not split), then the brief itself, then the disclosure
+ * lines, then the per-spec rules.
+ */
+export declare function buildForcedDirective(request: ForcedDispatchRequest): string;