@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/commands/subagent-command.js

@@ -0,0 +1,242 @@
+/**
+ * `/subagent` — force the next turn to fan out into a parallel team
+ * (subagent-fanout 3.5 / 5.2).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHAT THIS COMMAND IS AND IS NOT (D-8 / D-9 / D-10). It does not dispatch: it
+ * parses the user's intent, refuses honestly when forcing cannot work, prints
+ * ONE line saying what will happen next, and submits a normal user turn. The
+ * lead then calls `task` on the one dispatch path that already exists, so Esc,
+ * the watchdog pause, the report, spend accounting and the concurrency lock all
+ * keep working without a second implementation. The consequence the user must
+ * be told about is that forcing is INSTRUCTION-LEVEL: the notice says "the next
+ * turn dispatches them", never "N subagents started".
+ *
+ * THE GUARD ORDER IS A CONTRACT (R-P1-10 / R-P1-11): status -> capability ->
+ * parse. A `--no-team` session typing `/subagent -n x` is told the session has
+ * no team capability, because a syntax hint would send them to fix the one thing
+ * that is not wrong.
+ */
+import { buildForcedDirective, parseSubagentArgs } from '../team/forced-dispatch.js';
+import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
+/**
+ * The default count when the user names none (D-11).
+ *
+ * FOUR, not `maxSubagents`: `<team_mode>` tells the model two to four is usually
+ * enough, so "force one dispatch" must not silently become the most expensive
+ * call the session can make. The status line advertises the real ceiling so the
+ * user who wants the widest fan-out knows which flag to add.
+ */
+const DEFAULT_FORCED_COUNT = 4;
+/** `off (--no-team)` / `off` / `on`: the three states the status line tells apart. */
+function teamState(ctx) {
+    if (!ctx.controller.isTeamRegistered())
+        return 'off (--no-team)';
+    return ctx.controller.isTeamEnabled() ? 'on' : 'off';
+}
+/** The subagent model line, phrased by the same authority `/team status` uses. */
+function modelLine(ctx) {
+    const config = ctx.controller.getConfig();
+    const team = ctx.controller.getTeamConfig();
+    const fast = config.fast;
+    return subagentModelSummary({
+        mode: team.model,
+        modelProfileId: team.modelProfileId,
+        mainConnection: `${config.provider}:${config.model}`,
+        fastConnection: fast.enabled && fast.model
+            ? `${fast.provider || config.provider}:${fast.model}` : null,
+        profiles: config.modelProfiles,
+        hasKey: (id) => ctx.controller.hasApiKey(id),
+    });
+}
+/**
+ * The no-argument answer: five lines, honest in every session state.
+ *
+ * IT RUNS BEFORE EVERY GUARD (R-P1-11). "How wide can I go?" is a question, not
+ * a request, and a question deserves an answer even in a `--no-team` session -
+ * which is exactly where the user is most likely to ask it.
+ */
+function reportStatus(ctx) {
+    const team = ctx.controller.getTeamConfig();
+    const max = team.maxSubagents;
+    // The bracket's bounds are the LIVE width, never a literal: at capacity 2 this
+    // line has to read `<2-2>`, or the status line teaches a flag that arrives
+    // narrowed every time.
+    const low = Math.min(2, max);
+    const lines = [
+        `Forced fan-out: /subagent [-n <${low}-${max}>] [--parts a,b,c] [--read-only] <brief>`,
+        `Capacity: ${max} per dispatch, ${team.maxConcurrent} at once `
+            + '(team.maxSubagents / team.maxConcurrent)',
+        `Subagent model: ${modelLine(ctx)}`,
+        `Supervisor: ${team.overseer ? 'on' : 'off'}. Team mode: ${teamState(ctx)}.`,
+    ];
+    // Disclosed, never refused (R-P2-6): plan mode may remove `task` from this
+    // turn's tool array, and a user who is told so will not read the silence as a
+    // broken command.
+    if (ctx.controller.getAgentMode() === 'plan') {
+        lines.push('Plan mode is on: the task tool may be unavailable this turn.');
+    }
+    ctx.notify('info', lines.join('\n'));
+}
+/**
+ * Guard 5's sentence. The provider is named because "no API key" alone leaves
+ * the user guessing which of their configured providers is the empty one.
+ */
+function reportMissingKey(ctx, team) {
+    const config = ctx.controller.getConfig();
+    const resolution = ctx.controller.subagentModelResolution();
+    const provider = resolution.effective === 'main'
+        ? config.provider : resolution.ref.providerId;
+    const note = team.model === 'fast' && !ctx.controller.hasApiKey(undefined, 'fast')
+        ? ' Fast tier has no key either; children will fail and the report will say so.'
+        : '';
+    ctx.notify('warn', `No API key for ${provider}. Set one with /settings or an environment variable.${note}`);
+}
+/** The five capability refusals, in the fixed order 3.5.3 records. */
+function refused(ctx, team) {
+    if (!ctx.controller.isTeamRegistered()) {
+        ctx.notify('warn', 'Team mode is off for this session (started with --no-team). '
+            + 'Restart without --no-team to use /subagent.');
+        return true;
+    }
+    if (!ctx.controller.isTeamEnabled()) {
+        ctx.notify('warn', 'Team mode is off. Run /team on, then /subagent again.');
+        return true;
+    }
+    // The team lock and the lead's turn are separate refusals for one reason: both
+    // would collide with `task`'s own BUSY_REFUSAL, and the user would see a failed
+    // tool card instead of a sentence explaining why nothing ran.
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', 'A team dispatch is already running. '
+            + 'Wait for its report, or press Esc to stop it.');
+        return true;
+    }
+    if (ctx.controller.isRunning()) {
+        ctx.notify('warn', 'A turn is in progress. Press Esc to stop it, then run /subagent again.');
+        return true;
+    }
+    if (!ctx.controller.hasApiKey()) {
+        reportMissingKey(ctx, team);
+        return true;
+    }
+    return false;
+}
+/** The four parse failures, each with the one sentence that fixes it. */
+function reportParseError(ctx, parsed) {
+    if (parsed.error === 'count') {
+        ctx.notify('warn', '/subagent: -n needs a number of 1 or more, e.g. -n 4.');
+        return;
+    }
+    if (parsed.error === 'conflict') {
+        ctx.notify('warn', '/subagent: use -n or --parts, not both.');
+        return;
+    }
+    if (parsed.error === 'flag') {
+        ctx.notify('warn', `/subagent: unknown option "${parsed.token ?? ''}". Try /subagent for usage.`);
+        return;
+    }
+    ctx.notify('warn', '/subagent <brief> - describe the work; add -n <count> to fix the fan-out.');
+}
+/**
+ * Narrow the parsed intent against the LIVE width.
+ *
+ * TWO CEILINGS, IN THIS ORDER (R-P1-3): the structural `forcedPartsMax` bounds
+ * what one argument may carry (the parser already applied it), and the policy
+ * `maxSubagents` bounds what this session may dispatch - which only this layer
+ * can apply, because only it can read the live config.
+ */
+function planForced(args, team) {
+    const max = team.maxSubagents;
+    if (args.parts.length > 0) {
+        // A PARTS LIST STARTS WITH A CHILD PER SURVIVING PART, and `requested` is the
+        // number the user TYPED - not the structural 8 the parser already applied.
+        // Quoting the post-truncation count made the old notice tell a user who asked
+        // for eleven parts that they had asked for eight (R-4: the notice and the
+        // directive must both name the user's number).
+        const parts = args.parts.slice(0, max);
+        return {
+            brief: args.brief,
+            parts,
+            partsAdmitted: args.parts.length,
+            partsRequested: args.partsRequested,
+            requested: args.partsRequested,
+            count: parts.length,
+            readOnly: args.readOnly,
+        };
+    }
+    const requested = args.count ?? Math.min(DEFAULT_FORCED_COUNT, max);
+    return {
+        brief: args.brief,
+        parts: [],
+        partsAdmitted: 0,
+        partsRequested: 0,
+        requested,
+        count: Math.max(1, Math.min(requested, max)),
+        readOnly: args.readOnly,
+    };
+}
+/** The one line that says what the NEXT turn will do - a plan, not a result. */
+function planNotice(planned, team) {
+    const noun = planned.count === 1 ? 'subagent' : 'subagents';
+    const head = `Forcing a fan-out of ${planned.count} ${noun}`;
+    const followUp = `${head} (max ${team.maxSubagents}) - the next turn dispatches them. `
+        + 'Esc stops the turn.';
+    // TWO CEILINGS, TWO SENTENCES. `forcedPartsMax` bounds what one argument may
+    // carry and `team.maxSubagents` bounds what may be dispatched; naming the wrong
+    // one sends the user to change a number that is not the reason.
+    if (planned.parts.length > 0) {
+        if (planned.parts.length < planned.partsAdmitted) {
+            return `${head} (asked for ${planned.partsRequested} parts; `
+                + `team.maxSubagents is ${team.maxSubagents}).`;
+        }
+        if (planned.partsAdmitted < planned.partsRequested) {
+            return `${head} (asked for ${planned.partsRequested} parts, `
+                + `the first ${planned.parts.length} are used).`;
+        }
+        return followUp;
+    }
+    if (planned.requested > planned.count) {
+        return `${head} (asked for ${planned.requested}; `
+            + `team.maxSubagents is ${team.maxSubagents}).`;
+    }
+    return followUp;
+}
+/** The command body; `registerSubagentCommand` is the only registration site. */
+export function runSubagentCommand(ctx) {
+    if (ctx.args.trim().length === 0) {
+        reportStatus(ctx);
+        return;
+    }
+    const team = ctx.controller.getTeamConfig();
+    if (refused(ctx, team))
+        return;
+    const parsed = parseSubagentArgs(ctx.args);
+    if (!parsed.ok) {
+        reportParseError(ctx, parsed);
+        return;
+    }
+    const planned = planForced(parsed.args, team);
+    const directive = buildForcedDirective({
+        brief: planned.brief,
+        count: planned.count,
+        readOnly: planned.readOnly,
+        parts: planned.parts,
+        maxSubagents: team.maxSubagents,
+        clamped: planned.requested > planned.count,
+        requested: planned.requested,
+        planMode: ctx.controller.getAgentMode() === 'plan',
+    });
+    ctx.notify('info', planNotice(planned, team));
+    // `userInitiated: false`: a directive the user did not type belongs in neither
+    // the prompt history nor the hint-fade counter (todo-plan-followthrough C-12).
+    ctx.submit(directive, { userInitiated: false });
+}
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export function registerSubagentCommand(registry) {
+    registry.register({
+        name: 'subagent',
+        description: 'Force the next turn to fan out into a parallel team',
+        run: (ctx) => { runSubagentCommand(ctx); },
+    });
+}

package/dist/commands/task-command.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `/task` and `/task refresh` (tui-shortcut-drawer-and-task-summary §4.7).
+ *
+ * ASCII ONLY: `src/commands/**` is inside the glyph scanner's scope.
+ *
+ * WHY "task summary" AND NEVER BARE "task": this package already has a TOOL named
+ * `task` (the subagent dispatcher, `team/task-tool.ts`), and `HelpOverlay`'s team
+ * table prints that name. A help line that said only "task" would make two unrelated
+ * things share one word on the same screen.
+ *
+ * WHY A NOTICE AND NOT AN OVERLAY: three lines of provenance do not deserve a
+ * frame, and the guaranteed reporting surface for "why is there no label" has to be
+ * somewhere the user can scroll back to - a toast disappears.
+ *
+ * BOTH COMMANDS ARE REGISTERED UNCONDITIONALLY, even with
+ * `taskSummary.enabled = false`: they are the only surface that can EXPLAIN the
+ * switch, and a missing command answers "unknown command" instead of "off" (the
+ * `/prompts` D-19 rule).
+ */
+import type { SlashCommand } from './registry.js';
+/** One line per fact, or a single honest line when there is no label. */
+export declare function formatTaskSummaryReport(input: {
+    view: {
+        text: string;
+        tone: 'model' | 'fallback';
+        reason: string | null;
+        by: string;
+        at: number;
+    } | null;
+    pending: boolean;
+    enabled: boolean;
+    now: number;
+}): string[];
+/** `''` for a bare `/task`, `'refresh'` for `/task refresh`, else the raw argument. */
+export declare function parseTaskArgs(args: string): {
+    action: 'show' | 'refresh' | 'unknown';
+    raw: string;
+};
+export declare const taskCommand: SlashCommand;

package/dist/commands/task-command.js

@@ -0,0 +1,102 @@
+/**
+ * `/task` and `/task refresh` (tui-shortcut-drawer-and-task-summary §4.7).
+ *
+ * ASCII ONLY: `src/commands/**` is inside the glyph scanner's scope.
+ *
+ * WHY "task summary" AND NEVER BARE "task": this package already has a TOOL named
+ * `task` (the subagent dispatcher, `team/task-tool.ts`), and `HelpOverlay`'s team
+ * table prints that name. A help line that said only "task" would make two unrelated
+ * things share one word on the same screen.
+ *
+ * WHY A NOTICE AND NOT AN OVERLAY: three lines of provenance do not deserve a
+ * frame, and the guaranteed reporting surface for "why is there no label" has to be
+ * somewhere the user can scroll back to - a toast disappears.
+ *
+ * BOTH COMMANDS ARE REGISTERED UNCONDITIONALLY, even with
+ * `taskSummary.enabled = false`: they are the only surface that can EXPLAIN the
+ * switch, and a missing command answers "unknown command" instead of "off" (the
+ * `/prompts` D-19 rule).
+ */
+/** One line per fact, or a single honest line when there is no label. */
+export function formatTaskSummaryReport(input) {
+    if (!input.enabled) {
+        return [
+            'Task summary is off (config taskSummary.enabled = false).',
+            'Turn it back on with: aragon config set taskSummary.enabled true',
+        ];
+    }
+    if (input.view === null) {
+        if (input.pending)
+            return ['Task summary: still being generated.'];
+        return [
+            'No task summary yet.',
+            'It appears after the first prompt of a task; /task refresh regenerates it.',
+        ];
+    }
+    const age = formatAge(input.now - input.view.at);
+    const source = input.view.tone === 'fallback'
+        ? `your own words (${input.view.reason ?? 'fallback'})`
+        : input.view.by;
+    return [
+        `Task summary: ${input.view.text}`,
+        `Source: ${source}${age === '' ? '' : `, ${age}`}`,
+        'Regenerate with /task refresh, or open the drawer (Ctrl+G) to see why.',
+    ];
+}
+/** `12s ago` / `3m ago` / `1h ago`, or `''` for a clock that went backwards. */
+function formatAge(ageMs) {
+    if (!Number.isFinite(ageMs) || ageMs < 0)
+        return '';
+    const seconds = Math.floor(ageMs / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    return `${Math.floor(minutes / 60)}h ago`;
+}
+/** `''` for a bare `/task`, `'refresh'` for `/task refresh`, else the raw argument. */
+export function parseTaskArgs(args) {
+    const raw = args.trim();
+    if (raw.length === 0)
+        return { action: 'show', raw };
+    if (raw.toLowerCase() === 'refresh')
+        return { action: 'refresh', raw };
+    return { action: 'unknown', raw };
+}
+/**
+ * The command body: parse, report, or regenerate.
+ *
+ * NAMED FOR WHAT IT DOES, not for the port it touches (review fix RF-5): the old
+ * name described a variable, and this function is the whole of `/task`.
+ */
+function runTaskCommand(ctx) {
+    if (!ctx.taskSummary) {
+        ctx.notify('warn', 'The task summary is not available in this build.');
+        return;
+    }
+    const port = ctx.taskSummary;
+    const { action, raw } = parseTaskArgs(ctx.args);
+    if (action === 'unknown') {
+        ctx.notify('warn', `Unknown argument "${raw}" - use /task or /task refresh.`);
+        return;
+    }
+    if (action === 'refresh') {
+        const anchor = port.refresh();
+        if (anchor === '') {
+            ctx.notify('info', 'No prompt to summarise yet - send one first.');
+            return;
+        }
+        ctx.notify('info', 'Regenerating the task summary...');
+        return;
+    }
+    const state = port.read();
+    for (const line of formatTaskSummaryReport({ ...state, now: Date.now() })) {
+        ctx.notify('info', line);
+    }
+}
+export const taskCommand = {
+    name: 'task',
+    description: 'Show the header task summary (/task refresh regenerates it)',
+    run: runTaskCommand,
+};

package/dist/compaction/command.js

@@ -16,6 +16,7 @@ import { parseThresholdInput } from '../config/schema.js';
 import { formatCost, formatTokens } from '../agent/usage.js';
 import { computeCost } from '../agent/usage.js';
 import { COMPACTION_LIMITS } from './limits.js';
+import { compactionReasonLine } from './reason-text.js';
 import { findArchive, listArchives } from './archive.js';
 /**
  * `/compact status` — THE GUARANTEED REPORTING SURFACE (§6.5 / AC-17).
@@ -46,7 +47,7 @@ export function formatCompactionStatus(ctx) {
         return lines.join('\n');
     }
     const state = snapshot.selfDisabled
-        ? `self-disabled (${snapshot.selfDisabledReason ?? 'no progress'})`
+        ? `self-disabled (${compactionReasonLine(snapshot.selfDisabledReason ?? 'no progress')})`
         : controller.isCompactionEnabled()
             ? snapshot.live
                 ? 'on'
@@ -61,7 +62,13 @@ export function formatCompactionStatus(ctx) {
         `[${p.source === 'usage' ? 'measured' : 'estimated'}]`);
     lines.push(`  Automatic trigger: occupancy >= ${(config.threshold * 100).toFixed(2)}%; ` +
         `manual: /compact (${Math.ceil(p.contextWindow * config.threshold)} tokens)`);
+    // TWO LINES, BECAUSE THE TAIL GUARANTEE IS NOW CONDITIONAL (never-fires B).
+    // `keepRecentTurns` stays the promise; the second line is what happens when a run
+    // has too few user turns for that promise to be satisfiable, and saying it here
+    // is what makes the card's `kept M of N` readable rather than surprising.
     lines.push(`  Keeps: the original task + ${config.keepRecentTurns} recent turns, verbatim`);
+    lines.push(`  Relaxes to: the last ${COMPACTION_LIMITS.minRetainedMessages} messages ` +
+        'when a run has too few user turns for that');
     lines.push(`  Summarizer: ${snapshot.model || '(none)'}` +
         (config.useFastTier ? ' (fast tier preferred)' : ' (fast tier not used)'));
     lines.push('  On summarize failure: ' + (config.onFailure === 'truncate'
@@ -79,8 +86,14 @@ export function formatCompactionStatus(ctx) {
     if (declined > 0) {
         sessionNotes.push(`${declined} ${declined === 1 ? 'checkpoint' : 'checkpoints'} declined`);
     }
-    lines.push(`  This session: ${snapshot.compactions} ` +
-        `${snapshot.compactions === 1 ? 'compaction' : 'compactions'}` +
+    // ATTEMPTS, THEN APPLIED (never-fires C). `compactions` counts every card the
+    // user saw, which now includes the ones that declined, so reporting it alone
+    // would overstate how much the feature actually achieved.
+    const attempts = snapshot.applied === undefined
+        ? `${snapshot.compactions} ${snapshot.compactions === 1 ? 'compaction' : 'compactions'}`
+        : `${snapshot.compactions} ${snapshot.compactions === 1 ? 'attempt' : 'attempts'}` +
+            ` (${snapshot.applied} applied)`;
+    lines.push(`  This session: ${attempts}` +
         (sessionNotes.length > 0 ? ` (${sessionNotes.join(', ')})` : '') +
         `, ${formatTokens(snapshot.tokensReclaimed)} tokens reclaimed`);
     const cost = snapshot.pricingUnknown

package/dist/compaction/compactor.d.ts

@@ -93,6 +93,7 @@ export declare class Compactor implements ContextManager {
     private compactionsThisRun;
     private lastCompactionTurn;
     private compactions;
+    private appliedCompactions;
     private declined;
     private tokensReclaimed;
     private sessionUsage;
@@ -132,8 +133,31 @@ export declare class Compactor implements ContextManager {
     private callOnce;
     private checkCandidate;
     private isCurrent;
+    /**
+     * Open the card for THIS attempt (C).
+     *
+     * CALLED FROM `compact()`'S ENTRY, so the two pre-model rejections are visible
+     * too. The old position - inside `callOnce` - made an attempt that never called
+     * a model indistinguishable from a checkpoint that never fired, which is exactly
+     * how this feature spent 96 attempts without a single user-visible symptom.
+     *
+     * `state.index !== undefined` keeps it idempotent: `callOnce` no longer calls it,
+     * but the guard stays so a future re-announce cannot open a second card for one
+     * attempt.
+     */
     private announce;
+    /** Publish the current phase, for the live card only. */
+    private phase;
     private keep;
+    /**
+     * The relaxation disclosure, as record fields.
+     *
+     * ONE PLACE BUILDS IT, so the card, the reducer and the diagnostic log cannot
+     * describe one relaxed cut three different ways. Absent entirely when the first
+     * planning pass found a cut, which is what keeps a normal compaction's record
+     * byte-identical to the round before this change.
+     */
+    private relaxedFields;
     private finishRecord;
     /** Commit only the engine/host verdict; candidates have no authority before this point. */
     settleOperation(verdict: {
@@ -152,6 +176,7 @@ export declare class Compactor implements ContextManager {
     sessionTotals(): {
         selfDisabledReason?: string | undefined;
         compactions: number;
+        applied: number;
         declined: number;
         tokensReclaimed: number;
         usage: TokenUsage;