@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/agent/reducer.d.ts

@@ -15,14 +15,22 @@ import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agen
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 import type { FastReview, FastSnapshot } from '../fast/types.js';
-import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
+import type { CompactionMode, CompactionPhase, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { AcceptanceSnapshot, TodoItem, TodoSnapshot } from '../todo/types.js';
 import type { JobKind, ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
+import type { TaskSummaryView } from '../fast/task-summary-types.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
-export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents';
+export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents'
+/**
+ * tui-shortcut-drawer-and-task-summary §4.5: the keyboard drawer (`Ctrl+G` /
+ * `/keys`). A single field, so the drawer and `/help` cannot both hold the
+ * keyboard - which is also why `Ctrl+G` TAKES OVER from another overlay instead
+ * of being swallowed while one is open (P2-3).
+ */
+ | 'shortcuts';
 export type ToolStatus = 'pending' | 'running' | 'done' | 'error';
 /** Ephemeral, auto-dismissed acknowledgement (spec §3.9). */
 export interface Toast {
@@ -229,6 +237,22 @@ export type Entry = {
         messages: number;
         charsRemoved: number;
     };
+    /**
+     * The stage the LIVE card is in (context-compaction-never-fires C).
+     *
+     * Absent on a settled card and on every card written before this field
+     * existed, which is why the renderer treats it as optional and falls back to
+     * the old `summarizing with <model>` line.
+     */
+    phase?: CompactionPhase;
+    /** Set when the cut relaxed `keepRecentTurns` to exist at all (B). */
+    keepRelaxed?: boolean;
+    retainedTurns?: number;
+    /** Messages the relaxed cut left verbatim - the number the card states. */
+    retainedMessages?: number;
+    keepRecentTurnsUsed?: number;
+    /** Messages the digest left out, so they cannot be quoted (A1). */
+    elidedMessages?: number;
     live: boolean;
 } | {
     id: string;
@@ -391,6 +415,23 @@ export interface ViewState {
      * totals. `null` is what leaves an ordinary session's status bar unchanged.
      */
     compaction: CompactionSnapshot | null;
+    /**
+     * The session's task label, or `null` while there is none
+     * (tui-shortcut-drawer-and-task-summary D-13).
+     *
+     * PURE VIEW STATE: never persisted, never in the conversation history, never in
+     * `config.json`. It lives here because the header and the drawer must read the
+     * SAME field - two copies would be two labels for one task.
+     *
+     * THE TWO WRITERS ARE `taskSummaryPending` / `taskSummaryReady`, and the two
+     * CLEARERS are `resetConversation` and `restoreEntries`: clearing is the
+     * reducer's job (it is the only place that knows a task ended), while
+     * REBUILDING after `/resume` is the App wrapper's job, because only it can see
+     * the restored entries before they are reduced.
+     */
+    taskSummary: TaskSummaryView | null;
+    /** A summary call is in flight. Drives the drawer's `summarizing` line and `/task`. */
+    taskSummaryPending: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -562,6 +603,21 @@ export type ViewAction = {
 } | {
     type: 'restoreEntries';
     entries: Entry[];
+}
+/**
+ * The task label lifecycle (tui-shortcut-drawer-and-task-summary §7.1).
+ *
+ * TWO ACTIONS, because "a call started" and "a call finished" are different
+ * facts and the drawer reports them differently (`summarizing` vs the label).
+ * `taskSummaryReady` carries `null` in exactly one case: the call failed AND
+ * `taskSummary.fallback` is off, which is a deliberate "show nothing" rather
+ * than an empty string that would read as a broken feature.
+ */
+ | {
+    type: 'taskSummaryPending';
+} | {
+    type: 'taskSummaryReady';
+    view: TaskSummaryView | null;
 } | {
     type: 'setAgentMode';
     mode: AgentMode;
@@ -643,6 +699,18 @@ export type ViewAction = {
     type: 'compactionEnd';
     record: CompactionRecord;
 }
+/**
+ * The live card's stage (context-compaction-never-fires C).
+ *
+ * Its own action rather than a field on `compactionStart` because the phases
+ * arrive AFTER it, one per step, and because a phase must be able to land on a
+ * card that a previous attempt already settled into the same entry id.
+ */
+ | {
+    type: 'compactionPhase';
+    index: number;
+    phase: CompactionPhase;
+}
 /**
  * Compaction spend.
  *

package/dist/agent/reducer.js

@@ -67,6 +67,8 @@ export function initialViewState(seed = {}) {
         retry: null,
         fast: null,
         compaction: null,
+        taskSummary: null,
+        taskSummaryPending: false,
         seq: 0,
         teamEntryId: undefined,
         todoEntryId: undefined,
@@ -906,9 +908,25 @@ export function viewReducer(state, action) {
                 turnProduced: false,
                 errorNoticed: false,
                 aborted: false,
+                // THE TASK LABEL IS PART OF THE TASK (D-13). `/clear`, `/reset` and a
+                // session switch all land here, so the header loses its label without the
+                // App needing a second cleanup path. `/clear screen` does NOT come here -
+                // it keeps the conversation, so it keeps the label.
+                taskSummary: null,
+                taskSummaryPending: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
+        // --- Task summary (tui-shortcut-drawer-and-task-summary §7.1) ----------
+        //
+        // TWO FIELDS, ONE DIRECTION: `pending` is a latch the App raises before the
+        // call and releases on the result, and `taskSummary` is only ever replaced
+        // wholesale. Neither is persisted and neither is derived from `entries`, so a
+        // resumed conversation shows nothing until the App rebuilds the label.
+        case 'taskSummaryPending':
+            return { ...state, taskSummaryPending: true };
+        case 'taskSummaryReady':
+            return { ...state, taskSummary: action.view, taskSummaryPending: false };
         // Pure mirror write. The App only ever dispatches what
         // `controller.setAgentMode()` reported it ADOPTED, so this reducer has no
         // deferral logic of its own to get out of step with (§3.1 / R-P7).
@@ -1116,12 +1134,11 @@ export function viewReducer(state, action) {
         case 'fastTier':
             return { ...state, fast: action.snapshot };
         // --- Context compaction (context-auto-compaction §5.5) ----------------
-        // NOT A TOTAL FUNCTION OVER COMPACTION ATTEMPTS (quiet-noop §3.1). A
-        // `pressure` compaction that declines before calling a model or changing the
-        // history dispatches NOTHING - no `compactionStart`, no `compactionEnd`, no
-        // entry - exactly as a checkpoint below the threshold dispatches nothing.
-        // Counting cards here counts compactions that RAN, never checkpoints that
-        // fired; `/compact status` and the diagnostic log are where the attempts are.
+        // THE TRANSCRIPT NOW CARRIES ONE CARD PER ATTEMPT (context-compaction-never-
+        // fires C). Before this change a declined `pressure` checkpoint dispatched
+        // NOTHING, which is what made "95 % and nothing happens" unreportable: the
+        // feature was trying, failing and saying nothing. The flood the old rule
+        // feared is bounded by `maxPerRun` / `stuckLimit` in `compaction/limits.ts`.
         case 'compactionStart': {
             const { id, seq } = nextId(state);
             let entries = state.entries;
@@ -1171,6 +1188,7 @@ export function viewReducer(state, action) {
                 tokensAfter: 0,
                 model: action.model,
                 startedAt: Date.now(),
+                phase: 'planning',
                 live: true,
             };
             return {
@@ -1199,6 +1217,16 @@ export function viewReducer(state, action) {
                     ...(record.tailRelief ? { tailRelief: record.tailRelief } : {}),
                     ...(record.decision ? { decision: record.decision } : {}),
                     ...(record.memoryVersion ? { memoryVersion: record.memoryVersion } : {}),
+                    ...(record.keepRelaxed ? { keepRelaxed: record.keepRelaxed } : {}),
+                    ...(record.retainedTurns !== undefined
+                        ? { retainedTurns: record.retainedTurns } : {}),
+                    ...(record.retainedMessages !== undefined
+                        ? { retainedMessages: record.retainedMessages } : {}),
+                    ...(record.retainedMessages !== undefined
+                        ? { retainedMessages: record.retainedMessages } : {}),
+                    ...(record.keepRecentTurnsUsed !== undefined
+                        ? { keepRecentTurnsUsed: record.keepRecentTurnsUsed } : {}),
+                    ...(record.elidedMessages ? { elidedMessages: record.elidedMessages } : {}),
                     model: record.model,
                     durationMs: record.durationMs,
                     // SETTLED. `Transcript`'s boundary is monotonic, so a card that
@@ -1235,12 +1263,30 @@ export function viewReducer(state, action) {
                 ...(record.tailRelief ? { tailRelief: record.tailRelief } : {}),
                 ...(record.decision ? { decision: record.decision } : {}),
                 ...(record.memoryVersion ? { memoryVersion: record.memoryVersion } : {}),
+                ...(record.keepRelaxed ? { keepRelaxed: record.keepRelaxed } : {}),
+                ...(record.retainedTurns !== undefined ? { retainedTurns: record.retainedTurns } : {}),
+                ...(record.keepRecentTurnsUsed !== undefined
+                    ? { keepRecentTurnsUsed: record.keepRecentTurnsUsed } : {}),
+                ...(record.elidedMessages ? { elidedMessages: record.elidedMessages } : {}),
                 model: record.model,
                 durationMs: record.durationMs,
                 live: false,
             };
             return { ...state, seq, ...appendEntry(state, state.entries, entry) };
         }
+        case 'compactionPhase': {
+            // THE LIVE CARD'S STAGE, AND NOTHING ELSE. It must not open a card (a phase
+            // can arrive for an entry that a fast settle already closed) and must not
+            // resurrect a settled one: `live` is left untouched, so a late phase on a
+            // settled card changes nothing the renderer shows.
+            if (!state.compactionEntryId)
+                return state;
+            const phase = action.phase;
+            return {
+                ...state,
+                entries: mapEntry(state.entries, state.compactionEntryId, (e) => e.kind === 'compaction' && e.live ? { ...e, phase } : e),
+            };
+        }
         case 'compactionUsage':
             // `usageTotal` AND NOTHING ELSE, exactly as `teamUsage` and `fastUsage`. In
             // particular NOT `context`: that gauge shows the LEAD's context
@@ -1423,6 +1469,13 @@ export function viewReducer(state, action) {
                 // NOT cleared — it is the session's own tier projection, which a
                 // `/resume` does not change.
                 fastEntryId: undefined,
+                // `/resume` ADOPTS ANOTHER CONVERSATION, so the previous conversation's
+                // label describes something that is no longer on screen. The reducer only
+                // CLEARS it; the App's `makeCtx().dispatch` wrapper rebuilds one from
+                // `action.entries` (D-13), because it is the only layer that sees the
+                // restored entries BEFORE this branch runs.
+                taskSummary: null,
+                taskSummaryPending: false,
             };
         }
         // --- Background services (§3.10 / D-11) -----------------------------

package/dist/agent/skill-triage-prompt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `<skill_triage>` system-prompt block (skill-triage-and-unbounded-ask §4.2.3).
+ *
+ * WHY A PROTOCOL BLOCK AT ALL. The capability this feature fixes already existed:
+ * the Level 1 catalog is in every prompt, `skill(name)` loads a body, and
+ * `README.md` has claimed since the Skills feature landed that "the model decides
+ * on its own whether a task matches a skill". What was missing is any instruction
+ * that the decision has to HAPPEN, before the work rather than after it. The
+ * catalog's own opening paragraph is a STATEMENT ("if a task matches one, call the
+ * skill tool"), not a step in an order of operations, and a statement the model
+ * has read forty times is the one it skims.
+ *
+ * WHY IT IS THIS SHORT. The protocol is paid for on EVERY LLM request: the system
+ * prompt is re-sent each time and nothing in this repository uses provider-side
+ * prefix caching. An earlier draft carried a 1.9 KB version whose second half
+ * repeated the disclosure ladder that `<available_skills>` already states three
+ * lines above it. Repeating a rule is not emphasis, it is noise — and noise about
+ * a rule teaches the model that these blocks are skimmable. Measured size of the
+ * block below is 1273 bytes; `skill-triage-prompt.test.ts` asserts the ceiling of
+ * 1500 so an edit has 227 bytes of room, not unlimited scope.
+ *
+ * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
+ */
+import type { SkillCandidate } from '../skills/triage.js';
+/** Bump when the wording changes, so a transcript can be dated. */
+export declare const SKILL_TRIAGE_BLOCK_VERSION = "v1-2026-10-26";
+export interface SkillTriageBlockOptions {
+    /** This turn's candidates, best first. Empty is normal and renders no data block. */
+    candidates: SkillCandidate[];
+}
+/**
+ * Protocol first, candidates second — in that order, always.
+ *
+ * The order is the meaning: the protocol says what to do, the data block says with
+ * what. Reversing them would put a list of suggestions above the rules for reading
+ * it, which is how a suggestion turns into an instruction.
+ */
+export declare function buildSkillTriageBlock(options: SkillTriageBlockOptions): string;
+/** Byte size of the protocol half, for the budget assertion in the tests. */
+export declare function skillTriageProtocolBytes(): number;
+/** The ceiling the protocol half must stay under, in bytes. */
+export declare const SKILL_TRIAGE_PROTOCOL_MAX_BYTES: number;

package/dist/agent/skill-triage-prompt.js

@@ -0,0 +1,74 @@
+/**
+ * The `<skill_triage>` system-prompt block (skill-triage-and-unbounded-ask §4.2.3).
+ *
+ * WHY A PROTOCOL BLOCK AT ALL. The capability this feature fixes already existed:
+ * the Level 1 catalog is in every prompt, `skill(name)` loads a body, and
+ * `README.md` has claimed since the Skills feature landed that "the model decides
+ * on its own whether a task matches a skill". What was missing is any instruction
+ * that the decision has to HAPPEN, before the work rather than after it. The
+ * catalog's own opening paragraph is a STATEMENT ("if a task matches one, call the
+ * skill tool"), not a step in an order of operations, and a statement the model
+ * has read forty times is the one it skims.
+ *
+ * WHY IT IS THIS SHORT. The protocol is paid for on EVERY LLM request: the system
+ * prompt is re-sent each time and nothing in this repository uses provider-side
+ * prefix caching. An earlier draft carried a 1.9 KB version whose second half
+ * repeated the disclosure ladder that `<available_skills>` already states three
+ * lines above it. Repeating a rule is not emphasis, it is noise — and noise about
+ * a rule teaches the model that these blocks are skimmable. Measured size of the
+ * block below is 1273 bytes; `skill-triage-prompt.test.ts` asserts the ceiling of
+ * 1500 so an edit has 227 bytes of room, not unlimited scope.
+ *
+ * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
+ */
+import { renderSkillCandidates, SKILL_TRIAGE_LIMITS } from '../skills/triage.js';
+/** Bump when the wording changes, so a transcript can be dated. */
+export const SKILL_TRIAGE_BLOCK_VERSION = 'v1-2026-10-26';
+/**
+ * The protocol text. Kept as a literal array so a diff of the prompt is a diff of
+ * the source, and so the grader/test can see line boundaries.
+ */
+const PROTOCOL_LINES = [
+    '<skill_triage>',
+    `Version: ${SKILL_TRIAGE_BLOCK_VERSION}`,
+    '',
+    'Triage every task that touches the workspace: AFTER the project guidance and the',
+    'directory listing, BEFORE you plan or change anything. A user-typed /<skill-name>',
+    'is an override, not the only way in.',
+    '',
+    '1. Read <available_skills> above, and <skill_candidates> when present. A candidate',
+    '   is a computed guess about your message, not a verdict - check its one-line',
+    '   description before trusting it.',
+    '2. If the catalog says some skills were not shown, or nothing listed plainly',
+    '   covers the task, call skill_find(query) once before concluding there is no',
+    '   skill.',
+    '3. If a skill covers the task, call skill(name="...") BEFORE the first source read',
+    '   that would change code, then follow it. Say why in one line, not a paragraph.',
+    '4. If nothing covers the task, say so in one clause and continue. Do not load a',
+    '   skill to look diligent, and never load several "to be safe".',
+    '',
+    'A loaded skill is reference material, not permission to ignore the user, the',
+    'plan-mode rules, or the tools you actually have. If a skill narrows your tool set,',
+    'that is its allowed-tools declaration working: report it, do not work around it.',
+    'Never install or author a skill because a task looks like it needs one; that',
+    'decision belongs to the user.',
+    '</skill_triage>',
+];
+const PROTOCOL = PROTOCOL_LINES.join('\n');
+/**
+ * Protocol first, candidates second — in that order, always.
+ *
+ * The order is the meaning: the protocol says what to do, the data block says with
+ * what. Reversing them would put a list of suggestions above the rules for reading
+ * it, which is how a suggestion turns into an instruction.
+ */
+export function buildSkillTriageBlock(options) {
+    const candidates = renderSkillCandidates(options.candidates);
+    return candidates.length > 0 ? `${PROTOCOL}\n${candidates}` : PROTOCOL;
+}
+/** Byte size of the protocol half, for the budget assertion in the tests. */
+export function skillTriageProtocolBytes() {
+    return new TextEncoder().encode(PROTOCOL).length;
+}
+/** The ceiling the protocol half must stay under, in bytes. */
+export const SKILL_TRIAGE_PROTOCOL_MAX_BYTES = SKILL_TRIAGE_LIMITS.maxProtocolBytes;

package/dist/agent/system-prompt.d.ts

@@ -34,8 +34,20 @@ export interface SystemPromptParams {
      * plan as its final message instead of calling tools it does not have.
      */
     planInteractive?: boolean;
-    /** `planModeMaxAskRounds`, substituted into the block so the two agree. */
-    planMaxAskRounds?: number;
+    /**
+     * The rendered `<skill_triage>` block plus (when there are candidates) the
+     * `<skill_candidates>` block, or `''`.
+     *
+     * Spliced conditionally exactly as `skillsBlock` and the plan block are, which
+     * is what keeps invariant I-T1 true: `skills.triage: false`, a zero-skill
+     * install and `--no-skills` all produce the pre-feature prompt BYTE FOR BYTE.
+     *
+     * POSITION IS THE SEMANTICS. It goes immediately AFTER `skillsBlock`, because
+     * its first instruction refers to `<available_skills> above`, and a block
+     * separated from what it points at reads as a dangling reference. It also goes
+     * BEFORE the plan block, whose first step defers to it.
+     */
+    skillTriageBlock?: string;
     /**
      * The rendered `<team_mode>` block for a LEAD with team mode on, or `''`.
      *
@@ -114,6 +126,20 @@ export interface SystemPromptParams {
      * the child does not have.
      */
     jobsBlock?: string;
+    /**
+     * The rendered `<structured_result>` block, or `''`
+     * (headless-request-scope-and-typed-result section 2.3.8).
+     *
+     * Spliced conditionally exactly as every block above is, which is what keeps I-S1
+     * true: a run without `--result-schema` produces the pre-feature prompt BYTE FOR
+     * BYTE for a fixed tool array.
+     *
+     * POSITION IS THE SEMANTICS. It goes after every subsystem block and before
+     * `## Additional instructions`: it describes the SHAPE OF THE ANSWER, which is
+     * closer to the end of the work than any "how to behave" block, while the caller's
+     * own appended instructions still come last and still win.
+     */
+    structuredResultBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -33,17 +33,18 @@ export function buildSystemPrompt(params) {
     const skillsBlock = params.skillsBlock ?? '';
     const hasSkills = skillsBlock.length > 0;
     const planBlock = params.agentMode === 'plan'
-        ? buildPlanModeBlock({
-            interactive: params.planInteractive !== false,
-            maxAskRounds: params.planMaxAskRounds ?? 4,
-        })
+        ? buildPlanModeBlock({ interactive: params.planInteractive !== false })
         : '';
+    // `''` when the caller has no candidates or the feature is off — which is what
+    // keeps this block's absence byte-identical to the pre-feature prompt (I-T1).
+    const skillTriageBlock = params.skillTriageBlock ?? '';
     const teamBlock = params.teamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
     const backgroundBlock = params.backgroundBlock ?? '';
     const jobsBlock = params.jobsBlock ?? '';
+    const structuredResultBlock = params.structuredResultBlock ?? '';
     const appended = (params.appendSystemPrompt ?? '').trim();
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
@@ -60,6 +61,9 @@ export function buildSystemPrompt(params) {
         '',
         buildProjectGuidanceBlock(),
         ...(hasSkills ? ['', skillsBlock] : []),
+        // AFTER <available_skills> (it refers to it as "above") and BEFORE <plan_mode>
+        // (whose step 1 defers to it). Conditional like every other optional block.
+        ...(skillTriageBlock ? ['', skillTriageBlock] : []),
         ...(planBlock ? ['', planBlock] : []),
         ...(teamBlock ? ['', teamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
@@ -67,6 +71,10 @@ export function buildSystemPrompt(params) {
         ...(fastBlock ? ['', fastBlock] : []),
         ...(backgroundBlock ? ['', backgroundBlock] : []),
         ...(jobsBlock ? ['', jobsBlock] : []),
+        // AFTER every subsystem block, BEFORE the caller's own instructions: it describes
+        // the shape of the answer, which is the last thing to know before answering, while
+        // `## Additional instructions` still has the final word (section 2.3.8).
+        ...(structuredResultBlock ? ['', structuredResultBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',