@aragon-agent/cli 0.6.2 → 0.6.3

package/dist/logging/install.d.ts

@@ -129,7 +129,17 @@ export interface AgentEventSource {
         thinkingLevel: string;
     };
 }
-/** The nine members of the core `AgentEvent` union, as this module reads them. */
+/**
+ * The ELEVEN members of the core `AgentEvent` union, as this module reads them.
+ *
+ * THIS UNION MUST STAY A SUPERSET OF CORE'S, and the failure when it does not is
+ * a COMPILE error rather than a silent one (implementation finding IF-3): the
+ * `AgentEventSource` interface above takes a listener of THIS type, so a core
+ * union member missing here makes `AgentController` structurally incompatible
+ * with `attachAgentEvents` and every call site fails to type-check. That is the
+ * right failure mode, but it means adding an event to core is also a change
+ * here — the two `compaction_*` members below arrived that way.
+ */
 export type AgentLogEvent = {
     type: 'agent_start';
 } | {
@@ -183,6 +193,46 @@ export type AgentLogEvent = {
     duration?: number;
     error?: string;
     output?: string;
+}
+/**
+ * Context compaction (context-auto-compaction §5.1).
+ *
+ * RECORDED UNDER THE `agent` SCOPE HERE, not `compaction`. This module logs the
+ * LEAD'S LIFECYCLE, and "the run paused to compact" is part of that story — a
+ * support reader following a run's `agent` records must not find an unexplained
+ * gap where a 40-second summarization was. The `compaction` scope carries the
+ * subsystem's own detail (`compaction/compactor.ts`), which is a different
+ * question.
+ *
+ * NO `summary` FIELD IS READ, ever: it can be tens of thousands of characters,
+ * and this file's `message_update` case already records why a log larger than
+ * the conversation is not a log.
+ */
+ | {
+    type: 'compaction_start';
+    trigger?: string;
+    messageCount?: number;
+} | {
+    type: 'compaction_end';
+    applied?: boolean;
+    mode?: string;
+    reason?: string;
+    messagesBefore?: number;
+    messagesAfter?: number;
+    droppedMessages?: number;
+    /**
+     * The tail-relief report (context-auto-compaction-hardening W2).
+     *
+     * THIS UNION MUST STAY A SUPERSET OF CORE'S (IF-3). A field added to
+     * `CompactionEndEvent` and not mirrored here does not fail the build — the
+     * structural type simply ignores it — so the only trace of a degradation
+     * the user is entitled to know about would be missing from the log.
+     */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    durationMs?: number;
 };
 /**
  * Subscribe to the agent's events and record them.

package/dist/logging/install.js

@@ -273,6 +273,34 @@ export function attachAgentEvents(logger, controller) {
                     ms: turnStartedAt > 0 ? Date.now() - turnStartedAt : 0,
                 });
                 break;
+            // Context compaction (context-auto-compaction §5.1). At `info`, like
+            // `turn_end`, so a run's `agent` records have no unexplained 40-second gap
+            // where a summarization was.
+            case 'compaction_start':
+                logger.info('agent', 'compaction_start', {
+                    trigger: event.trigger,
+                    messages: event.messageCount,
+                });
+                break;
+            case 'compaction_end':
+                // `applied: false` is a WARN, not an info: it means the run is still at
+                // the occupancy that triggered this and is about to send anyway.
+                logger[event.applied ? 'info' : 'warn']('agent', 'compaction_end', {
+                    applied: event.applied,
+                    mode: event.mode,
+                    reason: event.reason,
+                    before: event.messagesBefore,
+                    after: event.messagesAfter,
+                    dropped: event.droppedMessages,
+                    ...(event.tailRelief
+                        ? {
+                            clipped: event.tailRelief.messages,
+                            clippedChars: event.tailRelief.charsRemoved,
+                        }
+                        : {}),
+                    ms: event.durationMs,
+                });
+                break;
             case 'message_update': {
                 // API retry (llm-api-retry-backoff §6.8), ABOVE the `trace` line so a
                 // three-minute pause is in the log at the DEFAULT level. Redaction is

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update' | 'compaction';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/session/persist.js

@@ -139,6 +139,25 @@ export function normalizeLoadedEntries(entries) {
                 detail: 'interrupted (session resumed)',
             };
         }
+        // THE FIFTH CLAUSE (context-auto-compaction §5.5 / C-8 / AC-19). A compaction
+        // card saved while its summarization was open resumes claiming to be running
+        // while nothing is, and — the part that actually costs — it never settles, so
+        // `Transcript`'s MONOTONIC boundary never advances past it and every frame for
+        // the rest of the session re-renders the whole tail.
+        //
+        // `applied: false` is also simply TRUE: whatever the call was going to
+        // return died with the process, and the history on disk is the PRE-compaction
+        // one. A card that claimed otherwise would tell the user their session had
+        // been compacted when it had not.
+        if (entry.kind === 'compaction' && entry.live) {
+            return {
+                ...entry,
+                live: false,
+                applied: false,
+                mode: 'none',
+                reason: 'interrupted (session resumed)',
+            };
+        }
         return entry;
     });
 }

package/dist/team/report.js

@@ -143,9 +143,15 @@ function buildSection(run) {
     // bytes, and it is the only place the lead learns which of its children were
     // cheap — the fact the whole second cost line is about.
     const tier = run.tier === 'fast' ? ' [fast]' : '';
+    // `compacted N` in the same position `retried Nx` uses, and for the same
+    // reason (context-auto-compaction-hardening §3.4.4 / W3): this is the ONLY
+    // place the lead learns that a child's own history was summarized mid-task, so
+    // a summary that reads thinner than the turn count suggests has a stated cause
+    // rather than an unexplained one. Absent when it never happened.
+    const compacted = run.compactions ? `, compacted ${run.compactions}` : '';
     const head = [
         `### ${run.label}${tier} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
-            `${run.turns} turns, ${run.toolCalls} tools${retried}`,
+            `${run.turns} turns, ${run.toolCalls} tools${retried}${compacted}`,
     ];
     if (run.filesTouched.length > 0)
         head.push(`files: ${run.filesTouched.join(', ')}`);

package/dist/team/runtime.d.ts

@@ -60,6 +60,16 @@ export interface TeamRuntimeDeps {
      * is the pre-feature behaviour.
      */
     resolveTier?: SubagentDeps['resolveTier'];
+    /**
+     * Per-child context compaction (context-auto-compaction-hardening §3.4 / W3).
+     *
+     * Passed straight through to `SubagentDeps`; absent means children get none,
+     * which is the pre-hardening behaviour exactly. `AgentController` supplies it
+     * from `CompactionWiring.childFactory()`, and the closure returns `undefined`
+     * when compaction is unregistered or `compaction.subagents` is false - which is
+     * what lets `subagent.ts` spread nothing at all.
+     */
+    contextManagerFor?: SubagentDeps['contextManagerFor'];
 }
 export declare class TeamRuntime {
     private readonly deps;

package/dist/team/runtime.js

@@ -132,6 +132,13 @@ export class TeamRuntime {
             ...(this.deps.humanQueue ? { humanQueue: this.deps.humanQueue } : {}),
             agentFactory: this.deps.agentFactory ?? defaultSubagentFactory,
             ...(this.deps.resolveTier ? { resolveTier: this.deps.resolveTier } : {}),
+            // Site two of two, and the omission is silent in the same way the policy
+            // one above is: declaring it on `TeamRuntimeDeps` and forgetting this line
+            // type-checks and forwards nothing, so every child would quietly run with
+            // no compaction while the config key says it has one.
+            ...(this.deps.contextManagerFor
+                ? { contextManagerFor: this.deps.contextManagerFor }
+                : {}),
         };
         // Hoisted into a factory so a retry can build a fresh child with IDENTICAL
         // wiring (F-4). Replacing the child rather than re-prompting it is the only

package/dist/team/subagent.d.ts

@@ -10,8 +10,9 @@
  * them (§3.11 / R-6). What a child does NOT get is spelled out below, and each
  * omission has a reason that is a correctness boundary rather than caution.
  */
-import { type AgentConfig, type AgentEvent, type AgentTool, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import { type AgentConfig, type AgentEvent, type AgentTool, type Message, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
+import type { ChildContextManagerProvider } from '../compaction/child.js';
 import type { CliConfig } from '../config/schema.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { FastTierName } from '../fast/types.js';
@@ -29,6 +30,24 @@ export interface SubagentAgentLike extends WatchdogPausable {
     prompt(text: string): Promise<void>;
     abort(): void;
     subscribe(listener: (event: AgentEvent) => void): () => void;
+    /**
+     * The child's live history, for its own context manager
+     * (context-auto-compaction-hardening §3.4.3 / W3).
+     *
+     * NARROWED ON PURPOSE. `Agent` satisfies this with its full `AgentState`
+     * getter and a stub satisfies it with `{ messages: [] }`. Widening it to
+     * `AgentState` would make every test stub fabricate a systemPrompt, a model and
+     * a phase to compile, for fields none of them use.
+     *
+     * A PROPERTY READ, NOT A METHOD CALL, AND THAT IS NOT A STYLE CHOICE: core's
+     * `Agent` has NO `getMessages()`. It exposes `get state(): AgentState`;
+     * `AgentController.getMessages()` is the CONTROLLER's own one-line forwarder
+     * over `this.agent.state.messages`. Adding a method to the engine to serve a
+     * host-side convenience would move the core export surface for nothing.
+     */
+    readonly state: {
+        readonly messages: readonly Message[];
+    };
 }
 export type SubagentAgentFactory = (config: AgentConfig) => SubagentAgentLike;
 /** The default factory: a real `Agent` from `@aragon-agent/core`. */
@@ -91,6 +110,17 @@ export interface SubagentDeps {
         ref: ModelRef;
         thinkingLevel: ThinkingLevel;
     };
+    /**
+     * Build this child its own context manager
+     * (context-auto-compaction-hardening §3.4.3 / W3).
+     *
+     * ABSENT means children get none, and `subagent.ts` then spreads NO
+     * `contextManager` key at all - so the child's loop gate tests a genuinely
+     * undefined field and a `compaction.subagents: false` session is byte-identical
+     * to round 1 (AC-H10). `AgentController` supplies it from
+     * `CompactionWiring.childFactory()`, which returns `null` when the key is off.
+     */
+    contextManagerFor?: ChildContextManagerProvider;
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */

package/dist/team/subagent.js

@@ -183,22 +183,40 @@ export function createSubagent(spec, deps, hooks) {
             thinkingLevel: deps.config.thinkingLevel,
         };
     const model = resolved.ref;
-    const agent = deps.agentFactory({
-        systemPrompt: buildSystemPrompt({
-            cwd: deps.getCwd(),
-            tools,
-            skillsBlock: deps.alwaysBlock ?? '',
-            agentMode: spec.readOnly ? 'plan' : deps.getMode(),
-            // A child has no overlay, so the plan block must describe the headless
-            // shape: write the plan as the final message rather than calling tools it
-            // does not have.
-            planInteractive: false,
-            subagentBlock: buildSubagentBlock({
-                label: spec.label,
-                description: spec.description,
-                peers: deps.bus.peersOf(spec.label),
-            }),
+    // HOISTED TO A LOCAL, AND THAT IS WHAT MAKES W3 POSSIBLE AT ALL. This was built
+    // INLINE inside the `agentFactory({...})` argument, so there was nothing for the
+    // child manager's `getSystemPrompt` accessor to close over - and the accessor
+    // cannot read it back off the agent, because `SubagentAgentLike` is narrowed to
+    // `state.messages` on purpose.
+    const systemPrompt = buildSystemPrompt({
+        cwd: deps.getCwd(),
+        tools,
+        skillsBlock: deps.alwaysBlock ?? '',
+        agentMode: spec.readOnly ? 'plan' : deps.getMode(),
+        // A child has no overlay, so the plan block must describe the headless
+        // shape: write the plan as the final message rather than calling tools it
+        // does not have.
+        planInteractive: false,
+        subagentBlock: buildSubagentBlock({
+            label: spec.label,
+            description: spec.description,
+            peers: deps.bus.peersOf(spec.label),
         }),
+    });
+    // LAZY ACCESSORS OVER `agentRef`, WHICH IS ASSIGNED AFTER THIS RETURNS. A
+    // non-lazy read here is `undefined` at construction and the child's estimate
+    // branch would silently measure an empty history - CR-1 one module over.
+    const contextManager = deps.contextManagerFor?.({
+        label: spec.label,
+        model,
+        getMessages: () => agentRef?.state.messages ?? [],
+        getSystemPrompt: () => systemPrompt,
+        onCompacted: () => {
+            run.compactions = (run.compactions ?? 0) + 1;
+        },
+    });
+    const agent = deps.agentFactory({
+        systemPrompt,
         model,
         tools,
         thinkingLevel: resolved.thinkingLevel,
@@ -217,6 +235,11 @@ export function createSubagent(spec, deps, hooks) {
             // explicitly.
             idleTimeout: deps.config.idleTimeoutMs,
         },
+        // SPREAD CONDITIONALLY, never `contextManager: deps.contextManagerFor?.(...)`.
+        // With the feature off the options bag has no such key, so the loop's gate
+        // tests a field that is genuinely `undefined` rather than a property holding
+        // one - the identical argument `AgentController` makes for the lead (AC-H10).
+        ...(contextManager ? { contextManager } : {}),
     });
     agentRef = agent;
     let lastEmit = 0;
@@ -289,6 +312,10 @@ export function createSubagent(spec, deps, hooks) {
                     outputTokens: run.usage.outputTokens + event.usage.outputTokens,
                 };
                 hooks.onUsage(spec.label, event.usage);
+                // W1's delta needs the history LENGTH the measurement covered, and the
+                // port carries no turn hook. `turn_end` is emitted BEFORE the assistant
+                // push, so this is exactly the history the reported `usage` describes.
+                contextManager?.onTurnEnd(event.usage, agentRef?.state.messages ?? [], systemPrompt);
                 const text = assistantText(event.message);
                 // The LAST non-empty assistant text wins, which is exactly the child's
                 // final message once the loop stops calling tools. Capturing it here

package/dist/team/types.d.ts

@@ -78,6 +78,14 @@ export interface SubagentRun {
     error?: string;
     /** Hit `team.maxTurnsPerSubagent` and was stopped mid-work. */
     truncated?: boolean;
+    /**
+     * Compactions this child performed on its OWN history
+     * (context-auto-compaction-hardening §3.4.4 / W3).
+     *
+     * OPTIONAL, so every existing construction site and fixture compiles
+     * unchanged. Absent and `0` mean the same thing to every reader.
+     */
+    compactions?: number;
     /**
      * Prose the child is writing right now, sanitized and clamped to
      * `TEAM_LIMITS.activityChars`. Set only between tool calls; cleared on

package/dist/ui/ActivityLine.d.ts

@@ -74,7 +74,25 @@ export interface ActivityLineProps {
      * not calm, it is wrong.
      */
     runningTool?: string;
+    /**
+     * A context compaction is in flight (context-auto-compaction §6.1).
+     *
+     * HIGHEST PRECEDENCE IN THE LABEL LADDER, above `runningTool` and above the
+     * rotating phrase. Compaction happens BEFORE `turn_start`, i.e. at a moment
+     * when `status` is `'running'` but no tool is in flight — precisely the window
+     * in which the phrase rotation would say something false, and it can last
+     * tens of seconds. `runningTool` already established the principle one step
+     * back: a UI that says "Pondering" while `npm test` runs is not calm, it is
+     * wrong, and one that says it while a 30 k-token summarization runs is the same
+     * error.
+     *
+     * STILL NO SECOND SPINNER. `single-spinner-while-running`'s D-1 stands: this
+     * row owns the only animation while it is mounted, and the compaction card
+     * follows `FastCard` in taking a `reducedMotion` that `App` has already
+     * widened.
+     */
+    compacting?: boolean;
     theme: Theme;
     caps: TermCapabilities;
 }
-export declare function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }: ActivityLineProps): React.ReactElement;
+export declare function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, compacting, theme, caps, }: ActivityLineProps): React.ReactElement;

package/dist/ui/ActivityLine.js

@@ -21,7 +21,7 @@ import { pickActivityPhrase } from './activity-phrases.js';
 export function liveSpinner(reducedMotion, caps) {
     return caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : null;
 }
-export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }) {
+export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, compacting, theme, caps, }) {
     const glyphs = pickGlyphs(caps);
     // PURE AND DERIVED FROM `(startedAt, now)`, so the sequence does not need to
     // keep rotating underneath the tool label: when the tool settles the phrase
@@ -31,7 +31,15 @@ export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool,
     // SECOND registry of tool names, and `toolGlyph` is already the one place that
     // knows them. Everything round 1 legislated for this row survives — one row,
     // no digits, no `esc abort`, no width ladder, ASCII only.
-    const label = runningTool ? `Running ${runningTool}` : `${phrase}${glyphs.ellipsis}`;
+    // THREE RUNGS, MOST SPECIFIC FIRST. `Compacting context` outranks a tool name
+    // because compaction can be the only thing happening, and it outranks the
+    // phrase for the reason `runningTool` does. ASCII only, and the ellipsis comes
+    // from `pickGlyphs` like every other one on this row.
+    const label = compacting
+        ? `Compacting context${glyphs.ellipsis}`
+        : runningTool
+            ? `Running ${runningTool}`
+            : `${phrase}${glyphs.ellipsis}`;
     // The IDENTICAL branch `Transcript.tsx` uses for the assistant role marker, and
     // it must stay identical: braille dots are both an animation AND a Unicode-only
     // glyph, so reduced motion and an ASCII terminal fall back to the same marker.

package/dist/ui/App.d.ts

@@ -11,6 +11,7 @@ import { type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
 import { type RenderMode } from './layout/frame.js';
 import type { MouseSource } from '../input/stdin-mouse-filter.js';
+import type { SelectionBridge } from './selection/selection-controller.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
     handler: ((req: ConfirmRequest) => Promise<boolean>) | null;
@@ -72,5 +73,51 @@ export interface AppProps {
      * 'off'`, on a non-TTY, in CI, and in every test that does not exercise it.
      */
     updateBridge?: UpdateBridge;
+    /**
+     * The terminal-facing services `cli.tsx` owns and this component cannot build
+     * (tui-selection-and-scroll-follow §4.4).
+     *
+     * ONE PROP RATHER THAN FOUR, and every FIELD of it is independently optional,
+     * so `--no-mouse`, `--no-diff-render` and inline mode each drop exactly the
+     * services they do not have. Absent altogether on a non-TTY and in every test
+     * that does not exercise selection, which is what keeps those trees
+     * byte-identical.
+     */
+    terminal?: TerminalBridge;
+}
+/**
+ * Terminal-level services, almost all of which exist only in a full-screen TTY
+ * session — `writeForeign` is the exception, because `/copy` is available in
+ * inline mode too and OSC 52 is what makes it work over SSH (§4.4.5).
+ *
+ * `selection` is a LATE-BOUND BRIDGE for the reason `updateBridge` above is one:
+ * the controller is constructed before `render()` and must not hold React state,
+ * while the toast sink and the redraw nonce only exist once this component has
+ * mounted. The effect below assigns both and clears them on unmount.
+ */
+export interface TerminalBridge {
+    /** Whether drag-select is on for this session (`mouseSelect` + a filter). */
+    mouseSelect: boolean;
+    /** Release the mouse to the terminal, or take it back (`/mouse`, G3). */
+    setMouseCapture?: (on: boolean) => void;
+    /** Whether the mouse is captured right now — read at command time. */
+    isMouseCaptured?: () => boolean;
+    /**
+     * Write bytes that are ours but are not a frame (OSC 52).
+     *
+     * IT MUST NOT BE `stdout.write` WITH THE DIFFER IN FRONT OF STDOUT (P1-6):
+     * that goes through the frame-writer proxy, which does not recognise an OSC 52
+     * chunk, counts it as a foreign write and prints `FRAME_FALLBACK_NOTICE` at
+     * the user the first time they copy anything. Without a differ — inline mode,
+     * `--no-diff-render` — stdout IS the real stream and `cli.tsx` supplies a
+     * direct write instead.
+     *
+     * Absent only when there is no terminal to accept it at all. It is never a
+     * function that writes nowhere: `copyText` reports `'osc52'` whenever its door
+     * took the text, so a no-op door would make the toast name a mechanism that
+     * was never attempted.
+     */
+    writeForeign?: (text: string) => void;
+    selection?: SelectionBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, terminal, }: AppProps): React.ReactElement;