@aragon-agent/cli 0.6.39 → 0.6.42

package/dist/proc/log-mirror.d.ts

@@ -9,7 +9,7 @@
  * `read_file` and `grep`): it is the full log on disk plus the PATH in the
  * truncation note.
  *
- * THREE RULES, each of which is about not becoming a new failure mode:
+ * THREE RULES PLUS A SCOPE, each of which is about not becoming a new failure mode:
  *
  *  - ASYNC AND COALESCED. `appendFile` with a <=4 writes/second buffer, so a
  *    webpack build emitting thousands of lines cannot turn logging into the
@@ -19,19 +19,36 @@
  *  - FAILURES ARE DEBUG LOGS, NEVER THROWS. A full disk must not kill a training
  *    run; the ring, the tools and the job state machine do not depend on this
  *    module at all.
+ *  - SCOPED TO ITS OWN ROOT. The retention sweep deletes session directories under
+ *    the jobs root the CALLER names, never under a parent derived from it: a
+ *    derived parent is other people's directory the moment the mirror is handed a
+ *    scratch path.
  */
 export interface JobLogMirrorOptions {
     /** `${aragonHome}/jobs/${sessionTag}`. A closure so a test can hand in a temp dir. */
     root: () => string;
+    /**
+     * THE DIRECTORY WHOSE SESSION SUBDIRECTORIES MAY BE SWEPT - passed, never derived.
+     *
+     * `dirname(root())` used to stand in for this, and it was wrong in the only way that
+     * matters: for any caller whose `root()` does not sit exactly one level below the jobs
+     * directory (a scratch dir in a test is the OS temp root's child) it handed the sweep a
+     * directory full of OTHER people's data and deleted everything but the newest few
+     * entries. A release run paid 40 s for that sweep and lost the temp directories of the
+     * test files running beside it. Omitted means NO sweep at all: growth is bounded only
+     * for callers that name the root they own.
+     */
+    jobsRoot?: () => string;
     maxBytes?: number;
     flushMs?: number;
 }
 /**
  * Delete all but the newest `PROC_LIMITS.mirrorRetainDirs` session directories.
  *
- * BEST EFFORT AND SILENT. This runs once per process at first use, and its whole
- * job is to stop `~/.aragon-agent/jobs/` from growing without bound; a directory
- * that cannot be read is not a reason to refuse to start.
+ * BEST EFFORT AND SILENT. This runs once per mirror at first use, and its whole job is to
+ * stop `~/.aragon-agent/jobs/` from growing without bound; a directory that cannot be read
+ * is not a reason to refuse to start. `jobsRoot` MUST be the directory this module owns -
+ * see `JobLogMirrorOptions.jobsRoot` for what deriving it cost.
  */
 export declare function pruneJobLogSessions(jobsRoot: string): void;
 export declare class JobLogMirror {

package/dist/proc/log-mirror.js

@@ -9,7 +9,7 @@
  * `read_file` and `grep`): it is the full log on disk plus the PATH in the
  * truncation note.
  *
- * THREE RULES, each of which is about not becoming a new failure mode:
+ * THREE RULES PLUS A SCOPE, each of which is about not becoming a new failure mode:
  *
  *  - ASYNC AND COALESCED. `appendFile` with a <=4 writes/second buffer, so a
  *    webpack build emitting thousands of lines cannot turn logging into the
@@ -19,18 +19,34 @@
  *  - FAILURES ARE DEBUG LOGS, NEVER THROWS. A full disk must not kill a training
  *    run; the ring, the tools and the job state machine do not depend on this
  *    module at all.
+ *  - SCOPED TO ITS OWN ROOT. The retention sweep deletes session directories under
+ *    the jobs root the CALLER names, never under a parent derived from it: a
+ *    derived parent is other people's directory the moment the mirror is handed a
+ *    scratch path.
  */
 import { appendFile, appendFileSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { getLogger } from '../logging/logger.js';
 import { PROC_LIMITS } from './limits.js';
+/**
+ * True when `path` holds nothing but `<jobId>.log` files, or nothing at all.
+ *
+ * DEFENSE IN DEPTH, NOT THE PRIMARY GUARD. The primary guard is that the caller names
+ * the jobs root instead of having it derived. This one means a sweep handed a directory
+ * that is not a mirror root is a no-op rather than a data loss - an empty directory and a
+ * directory of job logs are the only two shapes this module ever creates.
+ */
+function isMirrorDirectory(path) {
+    return readdirSync(path, { withFileTypes: true }).every((entry) => entry.isFile() && entry.name.endsWith('.log'));
+}
 /**
  * Delete all but the newest `PROC_LIMITS.mirrorRetainDirs` session directories.
  *
- * BEST EFFORT AND SILENT. This runs once per process at first use, and its whole
- * job is to stop `~/.aragon-agent/jobs/` from growing without bound; a directory
- * that cannot be read is not a reason to refuse to start.
+ * BEST EFFORT AND SILENT. This runs once per mirror at first use, and its whole job is to
+ * stop `~/.aragon-agent/jobs/` from growing without bound; a directory that cannot be read
+ * is not a reason to refuse to start. `jobsRoot` MUST be the directory this module owns -
+ * see `JobLogMirrorOptions.jobsRoot` for what deriving it cost.
  */
 export function pruneJobLogSessions(jobsRoot) {
     try {
@@ -41,14 +57,16 @@ export function pruneJobLogSessions(jobsRoot) {
             .map((entry) => {
             const path = join(jobsRoot, entry.name);
             try {
-                return { path, mtime: statSync(path).mtimeMs };
+                return { path, mtime: statSync(path).mtimeMs, prunable: isMirrorDirectory(path) };
             }
             catch {
-                return { path, mtime: 0 };
+                return { path, mtime: 0, prunable: false };
             }
         })
             .sort((a, b) => b.mtime - a.mtime);
         for (const stale of dirs.slice(PROC_LIMITS.mirrorRetainDirs)) {
+            if (!stale.prunable)
+                continue;
             try {
                 rmSync(stale.path, { recursive: true, force: true });
             }
@@ -107,7 +125,11 @@ export class JobLogMirror {
             this.files.set(jobId, { path, bytes, capped: bytes >= this.maxBytes() });
             if (!this.pruned) {
                 this.pruned = true;
-                pruneJobLogSessions(dirname(this.opts.root()));
+                // ONLY THE ROOT THE CALLER NAMED. See `JobLogMirrorOptions.jobsRoot` for why
+                // `dirname(root())` is not a substitute for it.
+                const jobsRoot = this.opts.jobsRoot?.();
+                if (jobsRoot !== undefined)
+                    pruneJobLogSessions(jobsRoot);
             }
         }
         catch (err) {

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;