@aragon-agent/cli 0.6.39 → 0.6.40

package/dist/skills/triage.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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.
+ */
+import type { SkillRecord, SkillScope } from '@aragon-agent/core';
+export interface SkillTriageLimits {
+    /** Candidates presented per turn. R-1: more than three is a reading list. */
+    maxCandidates: number;
+    /** One keyword hit is enough to be worth showing. */
+    minScore: number;
+    /** The score at which "you were told and did not load it" is worth a notice. */
+    confidentScore: number;
+    /**
+     * Byte ceiling for `<skill_candidates>`. 900, NOT 700: the fixed overhead is
+     * about 114 B, so 700 leaves ~586 B for three lines that cost up to 249 B each.
+     * A ceiling that silently drops the third candidate on ordinary input is not a
+     * ceiling, it is a slow leak — see the arithmetic table in `triage.test.ts`.
+     */
+    maxBlockBytes: number;
+    /** Byte ceiling for the `<skill_triage>` protocol block, asserted elsewhere. */
+    maxProtocolBytes: number;
+    /** Task text is truncated to this before tokenizing. */
+    maxTaskChars: number;
+    /** Tokens kept after tokenizing; bounds the scoring loop on a long task. */
+    maxTokens: number;
+    /** Latin tokens shorter than this are noise ("a", "of", "to"). */
+    latinTokenMinChars: number;
+    /** CJK runs shorter than this are noise; a single ideograph means nothing. */
+    cjkMinRunChars: number;
+    /** Bigrams taken per run. A 2,000-char run cannot be allowed to flood the set. */
+    maxCjkGramsPerRun: number;
+    /**
+     * Longest CJK run that ALSO contributes a whole-run token.
+     *
+     * Above this the whole-run token is dropped on purpose: a 2,000-character
+     * "token" cannot be a substring of any haystack, so it can only occupy one of
+     * `maxTokens` slots that a real token needed.
+     */
+    maxWholeRunChars: number;
+    /** Skill names are unbounded upstream (a kebab directory can be long). */
+    maxNameChars: number;
+    /** One line of description per candidate. */
+    descLineChars: number;
+    /** Each match-reason tag. */
+    reasonChars: number;
+}
+export declare const SKILL_TRIAGE_LIMITS: SkillTriageLimits;
+export type MatchReason = 'name' | 'keyword' | 'description';
+export interface SkillScore {
+    score: number;
+    reasons: MatchReason[];
+    mentioned: boolean;
+}
+export interface SkillCandidate {
+    name: string;
+    scope: SkillScope;
+    /** Already truncated to `descLineChars`; the renderer does not re-cut it. */
+    description: string;
+    /** 0..44 — see `TRIAGE_WEIGHTS` / `TRIAGE_CAPS`. */
+    score: number;
+    /** At most three, in the order they were first hit. */
+    reasons: MatchReason[];
+}
+export interface SkillRoutingReport {
+    /** The task text AFTER truncation to `maxTaskChars`. */
+    task: string;
+    /** How many tokens the task produced — the explanation for a miss. */
+    tokenCount: number;
+    /** How many records were eligible to be scored. */
+    eligible: number;
+    candidates: SkillCandidate[];
+    /**
+     * The best-scoring skill that did NOT make the list, or `null` when nothing
+     * scored at all.
+     *
+     * It exists for exactly one caller: `/skills route`'s "no match" output. "No
+     * skill matched" on its own is a dead end, and the threshold is the one number a
+     * user may need to argue with. Naming the runner-up and its score is what turns
+     * that dead end into "the threshold is slightly too high" or "nothing is close".
+     */
+    topUnqualified: {
+        name: string;
+        score: number;
+    } | null;
+    decision: 'none' | 'suggest' | 'confident';
+    /**
+     * Timestamp, for display and logging only. It never participates in ordering or
+     * scoring, which is what keeps this module a pure function (I-T2).
+     */
+    at: number;
+}
+/**
+ * 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 declare function tokenizeTask(text: string, limits?: SkillTriageLimits): string[];
+/**
+ * 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 declare function scoreSkill(record: SkillRecord, tokens: string[], taskText: string): SkillScore;
+export interface SelectSkillCandidatesInput {
+    task: string;
+    records: SkillRecord[];
+    /** Skills already loaded this turn — never proposed again (I-T4). */
+    activeNames: readonly string[];
+    limits?: Partial<SkillTriageLimits>;
+    /**
+     * Reference timestamp for the report's `at` field. Absent means `0`, so the
+     * function has no clock of its own (I-T2).
+     */
+    now?: number;
+}
+/**
+ * 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 declare function selectSkillCandidates(input: SelectSkillCandidatesInput): SkillCandidate[];
+/**
+ * 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 declare function buildRoutingReport(input: SelectSkillCandidatesInput): SkillRoutingReport;
+/**
+ * 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 declare function renderSkillCandidates(candidates: SkillCandidate[], opts?: {
+    maxBytes?: number;
+    limits?: Partial<SkillTriageLimits>;
+}): string;

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/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;