@aragon-agent/cli 0.6.4 → 0.6.8

package/dist/agent/controller.js

@@ -28,6 +28,7 @@ import { addSignalHook } from '../logging/install.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
 import { CompactionWiring, offCompactionSnapshot } from '../compaction/wiring.js';
+import { ContextMeter } from '../compaction/meter.js';
 import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
@@ -44,7 +45,7 @@ import { buildSystemPrompt } from './system-prompt.js';
  *
  * `bash`'s own kill grace is what a wedged foreground command costs; this covers
  * the loop's own unwinding on top of it. Waiting FOREVER is not an option - a
- * tool that never settles is exactly why rung two exists.
+ * tool that never settles is exactly why the force-stop rung exists.
  */
 const ENGINE_UNWIND_GRACE_MS = 3000;
 /** Approval gate used whenever there is provably no human to ask (headless). */
@@ -187,6 +188,23 @@ export class AgentController {
     // -----------------------------------------------------------------------
     compaction;
     // -----------------------------------------------------------------------
+    // Context occupancy (context-usage-gauge-accuracy §3.2 / W1)
+    //
+    // CONSTRUCTED UNCONDITIONALLY, unlike its neighbour, and that asymmetry IS the
+    // feature. `compaction` above is `null` for a session started with
+    // `--no-compaction` - and before this field existed, that took the only
+    // measuring code in the process with it: such a session's gauge had exactly
+    // one sample per turn (the provider's `turn_end` usage) and read `0 %` after a
+    // `/resume`. Occupancy is not a compaction concern; it is what compaction
+    // READS.
+    //
+    // IT COSTS A HEADLESS HOST NOTHING (I-11). `aragon exec` builds an
+    // `AgentController` too, and nothing there reads this number; the meter arms
+    // no timer while it has no subscribers, so the extra object is a few scalars
+    // and a `Set`.
+    // -----------------------------------------------------------------------
+    contextMeter;
+    // -----------------------------------------------------------------------
     // Background services (background-service-supervision §3.3 / §3.6)
     //
     // CONSTRUCTED UNCONDITIONALLY, and that is the one thing about this field that
@@ -228,6 +246,7 @@ export class AgentController {
      * abort lands.
      */
     runGen = 0;
+    startupSequence = 0;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -500,6 +519,28 @@ export class AgentController {
             modelId: config.model,
             ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
         };
+        // --- Context occupancy, part 1: BEFORE the Agent, UNCONDITIONALLY ------
+        //
+        // Built here for the same C-12 reason the wiring is - lazy `getMessages` /
+        // `getSystemPrompt` closures, `attach` after `new Agent` - and built for
+        // EVERY session, including one with compaction off, because that is the one
+        // whose gauge was broken (P1-4 / P0-2).
+        this.contextMeter = new ContextMeter({
+            getMessages: () => this.agent.state.messages,
+            getSystemPrompt: () => this.agent.state.systemPrompt,
+            getModelInfo: () => this.getModelInfo(),
+            // ONE PREDICATE FOR "IS THE DENOMINATOR REAL". `isPricedModel` is
+            // `modelRegistry.getModel(...) !== undefined`, and `getModelInfoFor` falls
+            // back to `buildRuntimeModel` - a 128k placeholder AND a zero cost table -
+            // for exactly the models it answers `false` for. The two are the same
+            // question about the same static table, not a coincidence.
+            isWindowKnown: () => this.isPricedModel({
+                providerId: this.config.provider,
+                modelId: this.config.model,
+            }),
+            // LIVE, so a settings-screen edit moves the denominator without a relaunch.
+            getWindowOverride: () => this.config.contextWindow,
+        });
         // --- Context compaction, part 1: BEFORE the Agent ----------------------
         //
         // It needs no agent reference to EXIST — only live config, the key
@@ -517,6 +558,9 @@ export class AgentController {
                 getMessages: () => this.agent.state.messages,
                 getSystemPrompt: () => this.agent.state.systemPrompt,
                 notify: (level, text) => deps.notify?.(level, text),
+                // ONE METER PER PROCESS (R-1). The wiring forwards it to the compactor,
+                // so the trigger and the gauge cannot read two different numbers.
+                meter: this.contextMeter,
             })
             : null;
         this.agent = new Agent({
@@ -567,6 +611,15 @@ export class AgentController {
         // subscribed could not run before `new Agent(...)`, and the port has to be
         // inside its constructor argument (C-12 / P0-2).
         this.compaction?.attach((listener) => this.agent.subscribe(listener));
+        // --- Context occupancy, part 2: after the Agent exists -----------------
+        //
+        // ORDER RELATIVE TO THE LINE ABOVE IS DELIBERATELY IRRELEVANT (I-9 / T7).
+        // The append direction is order-free because the meter marks itself dirty
+        // and re-measures on read; the replace direction is order-free because the
+        // splice is announced from `settlePending`'s own synchronous code rather
+        // than from a listener. If a future change makes this ordering matter, the
+        // fix is at those two sites, not here.
+        this.contextMeter.attach((listener) => this.agent.subscribe(listener));
         // --- Fast tier, part 2: after the Agent exists --------------------------
         //
         // `FastWiring` subscribes to the lead's event stream, so it cannot be built
@@ -803,43 +856,33 @@ export class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    async prompt(text) {
-        // I-8 - THIS METHOD NEVER REJECTS, AND THAT HAS TO BE A PROPERTY OF THE
-        // METHOD RATHER THAN A COMMENT ABOVE IT (P0-1).
-        //
-        // `App` calls this as `void controller.prompt(...)`, and
-        // `logging/install.ts` routes an `unhandledRejection` into `handleFatal`,
-        // which EXITS THE PROCESS. `Agent.prompt()` throws SYNCHRONOUSLY while
-        // `Agent.running` is true - so before the force-stop ladder existed this was
-        // merely nearly-true (the view was only ever idle when the engine was), and
-        // rung two makes the view idle while the engine is still unwinding. Without
-        // the wait and the guard below, "Esc, Esc, then type" would kill the CLI on
-        // the very screen this feature exists to rescue.
-        //
-        // TWO PARTS, BOTH REQUIRED. First WAIT the engine out, bounded, so the
-        // common case (the engine unwinds in a few hundred ms) starts a real run
-        // rather than reporting a failure. Then swallow anything that still escapes
-        // and surface it through the existing notify channel, because a message that
-        // cannot be started must produce a visible sentence - never a crash, and
-        // never silence.
-        if (this.agent.state.isRunning) {
-            this.abort();
-            await this.waitForEngineIdle();
-        }
+    async prompt(text, options = {}) {
+        // Capture BEFORE stopping: synchronous abort listeners may cancel this request.
+        const request = ++this.startupSequence;
         try {
-            await this.startPrompt(text);
+            if (this.agent.state.isRunning) {
+                this.stopEngine();
+                await this.waitForEngineIdle();
+            }
+            if (request !== this.startupSequence) {
+                return { status: 'not-started', reason: 'cancelled' };
+            }
+            if (this.agent.state.isRunning)
+                throw new Error('The previous run is still stopping.');
+            return await this.startPrompt(text, options, request);
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
             getLogger().warn('agent', 'prompt_failed', { reason });
             this.notifyHostFn?.('error', `Could not start the run: ${reason}`);
+            return { status: 'not-started', reason: 'failed' };
         }
     }
     /**
      * Wait for the engine to unwind, bounded.
      *
      * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
-     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * that never settles is exactly why the force-stop rung exists, and `Agent.waitForIdle()`
      * alone would hang here for as long as it hangs there. The budget is the two
      * graces a wedged `bash` can legitimately spend, plus the executor's own.
      */
@@ -859,31 +902,25 @@ export class AgentController {
             void this.agent.waitForIdle().then(finish, finish);
         });
     }
-    /** The pre-round body of `prompt`, unchanged apart from being private. */
-    startPrompt(text) {
-        // A new user message is a new intent, so the previous turn's tool ceiling
-        // expires here and anything a slash command queued is promoted (D-G1 / D-G2).
-        // This and `steer()` below are the ONLY two places a user message enters the
-        // engine, which is what makes a per-turn scope implementable at all (FG9).
+    /** Prepare before clearing the plan, then enter the engine without yielding. */
+    async startPrompt(text, options, request) {
         if (this.skillsEnabled)
             this.skills.beginUserTurn();
-        // The ask-round budget is per USER TURN and resets here for the same reason
-        // the skill frame does. `steer()` deliberately does NOT reset it: a user
-        // steering "actually, use Postgres" into a running plan is answering the
-        // questions, not buying four more rounds of them.
         this.askRounds = 0;
-        // Same asymmetry, same reason (§3.5): a completed plan is dropped HERE
-        // rather than at `agent_end`, so the user gets their `7/7 done` moment, and
-        // an unfinished one survives "continue" / "now do the rest" but not four
-        // unrelated turns.
-        this.todos?.beginUserTurn();
-        // The fast reviewer is asked whether the run is on track FOR THIS (§3.5.2).
-        // Without it the reviewer judges progress without being told the goal, which
-        // is the one input it cannot reconstruct from the event stream.
         this.fast?.setGoal(text);
-        return this.agent.prompt(text);
+        if (request !== this.startupSequence) {
+            return { status: 'not-started', reason: 'cancelled' };
+        }
+        this.todos?.beginUserTurn(options.todoPolicy);
+        await this.agent.prompt(text);
+        return { status: 'finished' };
     }
+    /** Cancel pending startup as well as any engine run already in progress. */
     abort() {
+        this.startupSequence += 1;
+        this.stopEngine();
+    }
+    stopEngine() {
         // SET BEFORE `agent.abort()`, SYNCHRONOUSLY — guard 1 of §3.5.4a. The loop
         // still emits the batch's final `tool_execution_end` (`agent-loop.ts:249`)
         // after an Esc lands inside the last tool's `await`, and the reviewer's
@@ -907,7 +944,7 @@ export class AgentController {
         this.teamRuntime?.abortAll();
     }
     /**
-     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * Final rung of the Esc ladder: stop the AGENT, whatever it is blocked on
      * (§3.6 / G3).
      *
      * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
@@ -915,7 +952,7 @@ export class AgentController {
      *   1. `abort()` - everything it does today, unchanged.
      *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
      *      child. THIS is what actually unblocks a wedged `await tool.execute`;
-     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      an abort signal a tool ignores is advisory, and the force-stop rung exists for
      *      precisely the tools that ignore it.
      *   3. `runGen += 1` - so `App` can drop the events the engine will keep
      *      emitting while it unwinds (I-7). Without it the view bounces straight
@@ -924,7 +961,7 @@ export class AgentController {
      *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
      *      sentences and it is exactly the kind of thing a later reader will
      *      "fix" by making this kill everything - which would mean a user who
-     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      confirmed a force-stop of a runaway turn also lost the dev server they
      *      had been working against for an hour. It is invariant I-4.
      *
      * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
@@ -1207,6 +1244,7 @@ export class AgentController {
         this.teamRuntime?.dispose();
         this.fast?.dispose();
         this.compaction?.dispose();
+        this.contextMeter.dispose();
         // REAP BEFORE RELEASING THE HOOK, in that order: disposal is a teardown, and
         // a service that outlives it has nothing left that could ever stop it.
         this.procs.reapSync();
@@ -1337,6 +1375,13 @@ export class AgentController {
         // so the snapshot the chip and `/compact status` read has to be refreshed
         // for the same reason and at the same moments (the RV-3 lesson).
         this.compaction?.onConfigChanged();
+        // THE DENOMINATOR MOVED, NOT THE HISTORY (context-usage-gauge-accuracy §3.4).
+        // A re-measure, deliberately NOT a reset: the measured base is still a true
+        // statement about the messages, and throwing it away would swap a correct
+        // numerator for a whole-history estimate on a common operation. The
+        // numerator's calibration is one turn stale until the next `turn_end`
+        // (RV-13), which is the trade this call names.
+        this.contextMeter.onWindowChanged();
     }
     setThinkingLevel(level) {
         this.config = { ...this.config, thinkingLevel: level };
@@ -1432,10 +1477,18 @@ export class AgentController {
     }
     clearMessages() {
         this.agent.clearMessages();
+        this.startupSequence += 1;
         // INVALIDATION SITE 3 (context-auto-compaction-hardening §3.2.3). The history
         // was CLEARED, not appended to, so the prefix length the last measurement
         // covered indexes an array that no longer exists.
+        //
+        // BOTH LINES, AND THE SECOND IS NOT REDUNDANT (context-usage-gauge-accuracy
+        // I-9). The wiring is `null` for a `--no-compaction` session, so it is the
+        // meter call that guarantees a re-measure - deleting it "to de-duplicate"
+        // reintroduces P0-2 for exactly the sessions this feature was written for. A
+        // deep reset is idempotent, so both firing costs nothing.
         this.compaction?.onHistoryReplaced();
+        this.contextMeter.onHistoryReplaced();
         // A new conversation has no loaded skills, so the "already loaded earlier
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
@@ -1452,10 +1505,19 @@ export class AgentController {
     }
     replaceMessages(messages) {
         this.agent.replaceMessages(messages);
+        this.startupSequence += 1;
         // INVALIDATION SITE 4 (§3.2.3) - `/resume`, and any future host-side rewrite.
         // `estimateAppendedTokens` bounds-checks as well, so a MISSED site costs
         // accuracy and never correctness; that belt does not make this call optional.
+        //
+        // THE SECOND LINE IS THE P0-2 FIX. Before it, `/resume` of a 180k-token
+        // session left the gauge and `/compact status` reading 0 %: nothing
+        // re-measured and nothing published, so the mount-time "empty history"
+        // reading stood until the next completed turn. The DEEP reset also drops
+        // `estimateOffset`, because `/resume` can change the model in the same
+        // breath (I-8).
         this.compaction?.onHistoryReplaced();
+        this.contextMeter.onHistoryReplaced();
     }
     getMessages() {
         return this.agent.state.messages;
@@ -1571,6 +1633,56 @@ export class AgentController {
             return () => { };
         return this.fast.subscribe(listener);
     }
+    /**
+     * The FIFTH thin forwarder: the current fast-tier snapshot, or `null` when
+     * this session never registered a tier at all
+     * (web-use-tier-cooperation-and-control-closure §4.2.1).
+     *
+     * `null` and "a snapshot with `live: false`" are different answers and callers
+     * depend on the difference: the first means "there is no tier here", the
+     * second means "there is one and it is not usable right now".
+     *
+     * Deliberately NOT folded into the existing `review_end` event: that shape is
+     * consumed by `App` too, and this round promised to be purely additive.
+     */
+    fastSnapshot() {
+        return this.fast?.snapshot() ?? null;
+    }
+    // -----------------------------------------------------------------------
+    // Context occupancy (context-usage-gauge-accuracy §4.2) — THREE FORWARDERS
+    //
+    // ALL THREE ARE AVAILABLE UNCONDITIONALLY, which is the whole difference
+    // between this block and the compaction one below it: there is no
+    // `?? offSomething()` fallback here, because the meter always exists.
+    // -----------------------------------------------------------------------
+    /**
+     * Subscribe to occupancy publications. Returns an unsubscribe function.
+     *
+     * THE SOLE UPSTREAM OF `ViewState.context` (I-1). The gauge used to have two
+     * writers - `turnEnd` and a `contextTokensEstimated` dispatch fired from two
+     * places in `App` - which is the entire cause of P0-1: both wrote in the same
+     * synchronous fan-out and the second one won, restoring the pre-compaction
+     * figure one statement after the bar had correctly fallen. One writer makes
+     * that class of bug unrepresentable rather than merely fixed.
+     */
+    subscribeContextUsage(listener) {
+        return this.contextMeter.subscribe(listener);
+    }
+    /**
+     * Occupancy right now, re-measuring if the history has moved.
+     *
+     * `/context` READS THIS AND NOT `getCompactionSnapshot().pressure` (RV-8). The
+     * latter returns `offCompactionSnapshot()`'s hardcoded zero pressure when
+     * compaction was never registered, so a report built on it would read 0 % for
+     * precisely the sessions this feature exists to fix.
+     */
+    getContextUsage() {
+        return this.contextMeter.currentUsage();
+    }
+    /** The meter itself, for the wiring's single-instance assertion and tests. */
+    getContextMeter() {
+        return this.contextMeter;
+    }
     // -----------------------------------------------------------------------
     // Context compaction (context-auto-compaction §3.2.1) — THIN FORWARDERS
     // -----------------------------------------------------------------------

package/dist/agent/headless.d.ts

@@ -4,6 +4,7 @@
  * derived from the event stream (R2), not from the resolved promise:
  *   0 = success, 1 = agent error (incl. a silently-swallowed throw), 2 = config.
  */
+import type { PromptOutcome } from './prompt-options.js';
 import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
@@ -15,7 +16,7 @@ import { type FollowThroughMode } from '../todo/follow-through.js';
 export interface HeadlessController {
     preflight(): PreflightResult;
     subscribe(listener: (event: AgentEvent) => void): () => void;
-    prompt(text: string): Promise<void>;
+    prompt(text: string): Promise<void | PromptOutcome>;
     getModelInfo(): ModelInfo;
     /**
      * The CLI-local team stream — OPTIONAL, deliberately (team-subagents §3.12 /

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

@@ -0,0 +1,15 @@
+/** Explicit TUI task boundary; omission retains legacy programmatic behavior. */
+export interface PromptOptions {
+    todoPolicy?: 'new-task' | 'continue';
+}
+/** History recording is independent of whether this message continues a plan. */
+export interface SubmitMessageOptions extends PromptOptions {
+    userInitiated?: boolean;
+}
+/** Startup outcome only; engine events still describe the result of the run. */
+export type PromptOutcome = {
+    status: 'finished';
+} | {
+    status: 'not-started';
+    reason: 'cancelled' | 'failed';
+};

package/dist/agent/prompt-options.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/reducer.d.ts

@@ -14,7 +14,7 @@ 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 } from '../compaction/types.js';
+import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger, ContextUsageSnapshot } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
 import type { ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
@@ -329,6 +329,16 @@ export type Entry = {
 export interface UsageTotal {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Cache read hits (context-usage-gauge-accuracy §3.6 / P1-3).
+     *
+     * `occupiedTokens` counts them and `computeCost` PRICES them, so a session
+     * total that omits them makes the status bar's `^` read lower than the `$`
+     * next to it - on the same row, from the same turns. That was three units on
+     * one line, and this field plus its sibling are what collapse them to one.
+     */
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
     costUsd: number;
 }
 /**
@@ -349,8 +359,20 @@ export interface ViewState {
     entries: Entry[];
     status: 'idle' | 'running';
     usageTotal: UsageTotal;
-    /** Running input size of the most recent turn vs. the model context window. */
-    contextTokens: number;
+    /**
+     * Context occupancy, as published by `AgentController`'s `ContextMeter`.
+     *
+     * ITS ONLY WRITER IS `case 'contextUsage'` (I-1), and that is the structural
+     * half of the P0-1 fix. It replaced `contextTokens` + `contextTokensEstimated`,
+     * which between them had THREE writing branches (`turnEnd`,
+     * `contextTokensEstimated`, `resetConversation`) fed by two competing
+     * upstreams. Two writers in one synchronous fan-out means the later one wins,
+     * and the later one was the stale `snapshot` carrying the PRE-compaction
+     * figure - so the bar fell and bounced straight back, every time, with nothing
+     * logging a fault. `context-one-writer.test.ts` scans this file to keep it
+     * that way.
+     */
+    context: ContextUsageSnapshot;
     overlay: Overlay;
     thinkingVisible: boolean;
     /** Ephemeral acks; auto-dismissed by App (spec §3.9). */
@@ -408,16 +430,6 @@ export interface ViewState {
      * totals. `null` is what leaves an ordinary session's status bar unchanged.
      */
     compaction: CompactionSnapshot | null;
-    /**
-     * Whether `contextTokens` is currently a DERIVED figure rather than a measured
-     * one (§6.2 / P1-11).
-     *
-     * Set by `compactionEnd`, cleared by the next `turnEnd`. The status bar widens
-     * its leading `~` to cover it: today `~` means "the window is a guess", and
-     * this makes it also mean "the occupancy is a guess". Honesty about a guess is
-     * cheaper than a support thread about a wrong percentage.
-     */
-    contextTokensEstimated: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -648,15 +660,17 @@ export type ViewAction = {
     snapshot: CompactionSnapshot;
 }
 /**
- * Overwrite the gauge with a DERIVED occupancy (§6.2).
+ * The occupancy reading, from `AgentController.subscribeContextUsage`.
  *
- * Separate from `compactionEnd` because the value is not always available at
- * the same instant, and because the flag it sets — `contextTokensEstimated` —
- * has to be clearable by the next `turnEnd` independently.
+ * THE ONLY ACTION THAT WRITES `state.context`, AND IT IS DISPATCHED FROM
+ * EXACTLY ONE PLACE (I-1 / T11). It replaced `contextTokensEstimated`, which
+ * `App` fired from two branches of the compaction stream while `turnEnd` wrote
+ * the same field from the agent stream - three writers, two upstreams, one
+ * number, and the P0-1 bounce as the result.
  */
  | {
-    type: 'contextTokensEstimated';
-    tokens: number;
+    type: 'contextUsage';
+    snapshot: ContextUsageSnapshot;
 } | {
     type: 'serviceStart';
     service: ServiceSnapshot;