@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/proc/output-streams.js

@@ -0,0 +1,54 @@
+/**
+ * Ask the child's output streams whether anything is still arriving (W1,
+ * defence 1).
+ *
+ * WHY THIS EXISTS AT ALL, AND THE RELEASE-GATE FAILURE THAT PROVED IT.
+ *
+ * `bash` settles on `'close'`, which fires only once every stdio stream is
+ * closed - and a detached grandchild that inherited the pipe keeps it open after
+ * the shell is long gone, so the promise had a path that never settled. The
+ * drain window (`PROC_LIMITS.drainMs`) closes that: a quarter of a second after
+ * `'exit'`, settle anyway and stamp
+ *
+ *     [note] the command exited but a background child is still holding its
+ *     output stream.
+ *
+ * The first build decided that sentence by TIMER EXPIRY - whatever had not
+ * settled when the window closed was called a held pipe. That is a claim about
+ * STATE inferred from a clock, and under load the two disagree. The release gate
+ * caught it on `tool-output-store.test.ts` AC-30 ("`bash` returns the same bytes
+ * with and without a recorder"): the second call of `node -e
+ * "process.stdout.write(...)"` returned the note for a child that had printed
+ * two lines and exited immediately. The pipe was closed microseconds after
+ * `'exit'`; the event loop was busy enough (four workers, 400 files, ~200 s of
+ * transforms behind it) that the timers phase came round before libuv delivered
+ * the close notification, so a 250 ms timer won a race it was never meant to
+ * win - and the model was told a background child was holding its output stream
+ * when nothing was.
+ *
+ * Hence: READ THE STREAMS, DO NOT GUESS FROM THE CLOCK. A `Readable` has ended
+ * once it has emitted `'end'` (`readableEnded`) or been destroyed. While either
+ * child descriptor is still open the sentence above is literally true; the
+ * moment both have ended it is false no matter what a timer says. Callers use
+ * this to decide the WORDING (note or not) and, together with the `'end'`
+ * events, to settle the ordinary path without waiting for `'close'` at all.
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope.
+ */
+/**
+ * Whether one child descriptor can still deliver bytes.
+ *
+ * A stream that has been destroyed is finished even when `readableEnded` is
+ * still false - that is the state a killed child's pipes end up in.
+ */
+export function isOutputStreamOpen(stream) {
+    if (!stream)
+        return false;
+    if (stream.destroyed)
+        return false;
+    return stream.readableEnded !== true;
+}
+/** Whether EITHER child descriptor can still deliver bytes. */
+export function hasOpenOutputStreams(streams) {
+    return isOutputStreamOpen(streams.stdout) || isOutputStreamOpen(streams.stderr);
+}

package/dist/skills/service.d.ts

@@ -9,6 +9,7 @@ import { SkillRegistry, type SkillFileRef, type SkillHost, type SkillPlatform, t
 import type { NoticeLevel } from '../agent/reducer.js';
 import type { SkillsConfig, SkillsRuntimeOptions, SkillsToolPolicyMode } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import { type SkillRoutingReport } from './triage.js';
 /**
  * Capability-probing approval gate (D17 / §8.3.1).
  *
@@ -229,6 +230,46 @@ export declare class SkillService {
     /** Warn once about `--skill <name>` values that match nothing (§7.5). */
     reportUnknownForcedSkills(): void;
     setDisabled(name: string, disabled: boolean): void;
+    /**
+     * Route one task against the installed skills — PURE COMPUTATION (I-T2).
+     *
+     * Reads in-memory records only: no file, no body, no network, no model call. The
+     * whole "which skills could apply here" question therefore costs zero context
+     * bytes, which is what makes the disclosure ladder honest — Level 2 is paid for
+     * only when the model actually opens a skill.
+     *
+     * Returns `null` when triage is switched off, so every caller has one shape to
+     * check rather than an empty report that looks like "no match".
+     *
+     * Writes NO usage counter. An automatic proposal is not a user's choice, which
+     * is the same reason `loadBody({ countUse: false })` exists for always-on
+     * skills: counting it would pin an auto-suggested skill to the top of the
+     * ranking forever and destroy the signal the ranking is there to carry.
+     */
+    triage(task: string): SkillRoutingReport | null;
+    /**
+     * `/skills route <text>` — the same computation, WITHOUT the on/off gate.
+     *
+     * The gate exists to keep the block out of the prompt; it must not make the
+     * explanation unreachable, because "why did nothing match" is the question a user
+     * asks precisely when they suspect the switch is off.
+     */
+    route(task: string): SkillRoutingReport;
+    /**
+     * `/skills triage on|off` — persist the switch AND rebuild the prompt now.
+     *
+     * `updateConfig` deliberately only replaces this object's config and calls
+     * `persist`; it does NOT call `deps.onChange`. Every other mutator supplies that
+     * call itself (`setDisabled` above, the directory-trust path below), and `onChange`
+     * is the sole route to `controller.refreshSkills()` → `rebuildSystemPrompt()`.
+     * Without it the setting would be written to disk and the running session would
+     * keep the old prompt until the next launch — which reads as a broken switch.
+     *
+     * The early return is not an optimization: `updateConfig` persists, so flipping a
+     * switch to the value it already has would produce a pointless disk write and a
+     * pointless prompt rebuild on every keystroke.
+     */
+    setTriageEnabled(enabled: boolean): void;
     getConfig(): SkillsConfig;
     /** Local use counters backing `--sort=recent`; empty when tracking is off. */
     getUsage(): SkillUsageMap;

package/dist/skills/service.js

@@ -14,6 +14,7 @@ import { currentPlatform } from './node-host.js';
 import { MANIFEST_FILENAME, readManifest, sha256Buffer, sha256File } from './manifest.js';
 import { isDirectory, normalizeTrustPath, resolveSkillRoots, getStagingDir, } from './paths.js';
 import { USAGE_MAX_ENTRIES, loadUsage, pruneUsage, recordUse } from './usage.js';
+import { buildRoutingReport } from './triage.js';
 const ENTRY_FILE = 'SKILL.md';
 /**
  * Re-exported from `manifest.ts` rather than spelled out again. The two copies
@@ -615,6 +616,67 @@ export class SkillService {
         this.updateConfig({ disabled: [...next] });
         this.deps.onChange?.();
     }
+    /**
+     * Route one task against the installed skills — PURE COMPUTATION (I-T2).
+     *
+     * Reads in-memory records only: no file, no body, no network, no model call. The
+     * whole "which skills could apply here" question therefore costs zero context
+     * bytes, which is what makes the disclosure ladder honest — Level 2 is paid for
+     * only when the model actually opens a skill.
+     *
+     * Returns `null` when triage is switched off, so every caller has one shape to
+     * check rather than an empty report that looks like "no match".
+     *
+     * Writes NO usage counter. An automatic proposal is not a user's choice, which
+     * is the same reason `loadBody({ countUse: false })` exists for always-on
+     * skills: counting it would pin an auto-suggested skill to the top of the
+     * ranking forever and destroy the signal the ranking is there to carry.
+     */
+    triage(task) {
+        if (!this.config.enabled || !this.config.triage)
+            return null;
+        return buildRoutingReport({
+            task,
+            records: this.registry.list(),
+            activeNames: this.registry.activeNames,
+            now: Date.now(),
+        });
+    }
+    /**
+     * `/skills route <text>` — the same computation, WITHOUT the on/off gate.
+     *
+     * The gate exists to keep the block out of the prompt; it must not make the
+     * explanation unreachable, because "why did nothing match" is the question a user
+     * asks precisely when they suspect the switch is off.
+     */
+    route(task) {
+        return buildRoutingReport({
+            task,
+            records: this.registry.list(),
+            activeNames: this.registry.activeNames,
+            now: Date.now(),
+        });
+    }
+    /**
+     * `/skills triage on|off` — persist the switch AND rebuild the prompt now.
+     *
+     * `updateConfig` deliberately only replaces this object's config and calls
+     * `persist`; it does NOT call `deps.onChange`. Every other mutator supplies that
+     * call itself (`setDisabled` above, the directory-trust path below), and `onChange`
+     * is the sole route to `controller.refreshSkills()` → `rebuildSystemPrompt()`.
+     * Without it the setting would be written to disk and the running session would
+     * keep the old prompt until the next launch — which reads as a broken switch.
+     *
+     * The early return is not an optimization: `updateConfig` persists, so flipping a
+     * switch to the value it already has would produce a pointless disk write and a
+     * pointless prompt rebuild on every keystroke.
+     */
+    setTriageEnabled(enabled) {
+        if (this.config.triage === enabled)
+            return;
+        this.updateConfig({ triage: enabled });
+        this.deps.onChange?.();
+    }
     getConfig() {
         return this.config;
     }

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;