@aragon-agent/cli 0.6.7 → 0.6.9

package/dist/agent/controller.js

@@ -45,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). */
@@ -246,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`.
@@ -855,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.
      */
@@ -911,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
@@ -959,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.
@@ -967,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
@@ -976,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
@@ -1492,6 +1477,7 @@ 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.
@@ -1519,6 +1505,7 @@ 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.

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

@@ -115,20 +115,7 @@ export type Entry = {
     kind: 'notice';
     level: NoticeLevel;
     text: string;
-}
-/**
- * A team dispatch (team-subagents §5.3). JSON-SERIALIZABLE by construction, so
- * `/save` and `/resume` need no format change.
- *
- * `active: true` is normalized away ON LOAD, in `session/persist.ts`, not here
- * (P1-5). A session saved mid-dispatch would otherwise resume with a card that
- * claims to be running while nothing is: it spins forever, and because
- * `Transcript`'s settled boundary is MONOTONIC an entry that never settles
- * never reaches `<Static>` and is re-rendered on every frame for the rest of
- * the session. The reducer never legitimately sees a stale-active entry — only
- * the file does — which is why the fix belongs in the load path.
- */
- | {
+} | {
     id: string;
     kind: 'team';
     dispatchId: string;
@@ -137,20 +124,7 @@ export type Entry = {
     aborted: boolean;
     durationMs?: number;
     active: boolean;
-}
-/**
- * The turn's todo checklist (todo-plan-execution §3.8). ONE per user turn,
- * rewritten in place — a 7-item list updated twice per item would otherwise be
- * 14 near-identical tool cards in the one surface the user reads most.
- *
- * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
- *
- * `live: true` is normalized away ON LOAD, in `session/persist.ts`, for the
- * same reason the team entry's `active` is (C-5): `Transcript`'s settled
- * boundary is MONOTONIC, so an entry that never settles never reaches
- * `<Static>` and is re-rendered on every frame for the rest of the session.
- */
- | {
+} | {
     id: string;
     kind: 'todo';
     items: TodoItem[];
@@ -165,21 +139,7 @@ export type Entry = {
      * card this session produced.
      */
     interrupted?: boolean;
-}
-/**
- * The turn's retry story (llm-api-retry-backoff §6.4). ONE per turn, REWRITTEN
- * IN PLACE — ten retries rendered as ten notices would bury the transcript in
- * the one moment the user most needs it legible.
- *
- * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
- *
- * `phase: 'waiting' | 'retrying'` is normalized away ON LOAD, in
- * `session/persist.ts`, exactly as the team entry's `active` and the todo
- * card's `live` are (R-10): `Transcript`'s settled boundary is MONOTONIC, so a
- * card that never settles never reaches `<Static>` and is re-rendered on every
- * frame for the rest of the session.
- */
- | {
+} | {
     id: string;
     kind: 'retry';
     /** 1-based retry index of the LATEST attempt this card has seen. */
@@ -195,22 +155,7 @@ export type Entry = {
     /** Filled on settle. */
     totalRetries?: number;
     elapsedMs?: number;
-}
-/**
- * One fast-model review (fast-model-tier §5.4). ONE CARD PER REVIEW, never
- * rewritten across reviews — a critique is a single event, unlike the todo
- * card's per-turn checklist.
- *
- * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
- *
- * `live: true` is normalized away ON LOAD, in `session/persist.ts`, next to
- * `team.active`, `todo.live` and the retry card's phase, and for the identical
- * reason (C-5): `Transcript`'s settled boundary is MONOTONIC, so an entry that
- * never settles never reaches `<Static>` and is re-rendered on every frame for
- * the rest of the session. The reducer never legitimately sees a stale-live
- * entry — only the file does.
- */
- | {
+} | {
     id: string;
     kind: 'fast';
     /** 1-based within the session, so the card can name itself. */
@@ -224,27 +169,7 @@ export type Entry = {
     turn: number;
     durationMs?: number;
     live: boolean;
-}
-/**
- * One context compaction (context-auto-compaction §5.5). ONE CARD PER
- * COMPACTION, rewritten once when the call returns — like the fast card, and
- * unlike the todo card's per-turn checklist.
- *
- * JSON-SERIALIZABLE by construction, so `/save` and `/resume` need no format
- * change.
- *
- * `live: true` is normalized away ON LOAD, in `session/persist.ts`, next to
- * `team.active`, `todo.live`, the retry card's phase and `fast.live`, and for
- * the identical reason (C-8): `Transcript`'s settled boundary is MONOTONIC, so
- * an entry that never settles never reaches `<Static>` and is re-rendered on
- * every frame for the rest of the session.
- *
- * EVERY STRING ON THIS CARD DESCRIBES THE HISTORY, NEVER THE SCREEN (P2-9).
- * `/clear` empties the transcript view but not `messages`, so a compaction can
- * legitimately fire against a visually empty transcript and report
- * "112 -> 9 messages" with nine visible rows.
- */
- | {
+} | {
     id: string;
     kind: 'compaction';
     /** 1-based within the session, so the card can name itself. */
@@ -275,29 +200,7 @@ export type Entry = {
         charsRemoved: number;
     };
     live: boolean;
-}
-/**
- * One supervised background service (background-service-supervision §3.10).
- *
- * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
- *
- * IT IS THE ONE LIVE CARD THAT DOES **NOT** BLOCK THE SETTLED BOUNDARY ONCE IT
- * IS UP (D-11 / P0-4). Every other live clause in
- * `Transcript.tsx::computeSettledCount` is bounded by an OPERATION — a
- * dispatch, a turn, one LLM call, one countdown — and each carries a comment
- * saying that an entry which never settles is re-rendered on every frame for
- * the rest of the session. A service is bounded by the USER'S INTENT: a dev
- * server left up for an hour is the normal case. So only `starting` blocks
- * (bounded by `readyTimeoutMs`), a `ready`/`running` card commits its body to
- * `<Static>`, and a later terminal transition appends a NEW one-row entry
- * rather than trying to rewrite a card `<Static>` has already printed.
- *
- * `terminal: true` marks that second entry. `session/persist.ts` rewrites any
- * restored non-terminal card to `stopped`, next to `team.active`, `todo.live`,
- * the retry phase, `fast.live` and `compaction.live`, and for the identical
- * reason.
- */
- | {
+} | {
     id: string;
     kind: 'service';
     /** `s1`, `s2`, ... — the id the model quotes back. */
@@ -677,16 +580,7 @@ export type ViewAction = {
 } | {
     type: 'serviceUpdate';
     service: ServiceSnapshot;
-}
-/**
- * A service reached a terminal state.
- *
- * IT APPENDS A NEW ONE-ROW ENTRY rather than rewriting the card (D-11). The
- * card may already have been printed into `<Static>`, and `<Static>` cannot
- * un-print — so any design that rewrites a printed card is wrong whatever it
- * claims. A second event at a second time is also simply more honest.
- */
- | {
+} | {
     type: 'serviceEnd';
     service: ServiceSnapshot;
 };

package/dist/agent/reducer.js

@@ -382,31 +382,6 @@ function settleRetryCard(state, entries, phase) {
         retryEntryId: undefined,
     };
 }
-/**
- * EVERY PATH THAT REACHES `status: 'idle'` RELEASES THE LIVE TAIL (D-35 / AC-40).
- *
- * `runEnd` finalizes only the streaming ASSISTANT entry and `abortMark` maps only
- * assistant entries, so neither touches a tool entry stranded at
- * `status: 'running'` -- the engine's own idle watchdog, a provider error mid-call
- * and `Esc` all produce one. Today that costs a single spinner row. With a tail
- * attached it costs a permanent multi-row card whose stall counter is frozen at
- * its last value, because the 200 ms ticker that feeds `nowSec` is torn down the
- * instant `state.status` leaves `running` -- and, worse, `computeSettledCount`
- * breaks on a non-settled tool entry, so that card pins `Transcript`'s MONOTONIC
- * settled boundary and re-renders the tail every frame for the rest of the
- * session. The rule and the stakes are `settleRetryCard`'s, verbatim.
- *
- * THE STATUS IS DELIBERATELY NOT CHANGED. That is a different decision with
- * different consequences for `bashBadge` and for the run's own bookkeeping, and
- * it is not this round's to make. Only the tail is released.
- *
- * `liveSeq` is BUMPED rather than cleared, and that is not bookkeeping: clearing
- * `live` is a non-append mutation, and with the status untouched nothing else in
- * the tool revision moves -- so without the bump the height cache would keep
- * serving the multi-row measurement for a card that now draws one row (I-L3-1).
- * Entries with no tail are returned by identity, which is what keeps
- * `EntryView`'s memo boundary intact for the rest of the transcript.
- */
 function releaseLiveTails(entries) {
     let touched = false;
     const next = entries.map((e) => {
@@ -1218,22 +1193,6 @@ export function viewReducer(state, action) {
                 entries: mapEntry(state.entries, known, (e) => e.kind === 'retry' ? { ...e, phase: 'retrying', resumeAt: undefined } : e),
             };
         }
-        /**
-         * Rewind the view for a mid-stream restart.
-         *
-         * THE ONLY ACTION IN THIS REDUCER THAT SHRINKS `entries`, and it is safe for
-         * one specific reason (§6.4 / AC-22). `Transcript` clamps its settled boundary
-         * with a MONOTONIC high-water mark: if `highWater` ever exceeded
-         * `entries.length` the clamp would mark EVERYTHING settled — including the
-         * still-streaming assistant entry — and `<Static>` would duplicate it.
-         *
-         * It cannot, and the ORDERING is why: the entries removed here are
-         * `kind: 'tool'` cards created by `toolCallStart` AFTER `turnStart` created the
-         * streaming assistant entry, so they sit strictly above it in the array; and
-         * the boundary scan already breaks at that entry. Removing only entries above
-         * the boundary is the invariant. A future action that removed a SETTLED entry
-         * would break `<Static>` and nothing would report it.
-         */
         case 'streamRestart': {
             const discarded = new Set(action.discardedToolCallIds);
             const entries = state.entries.filter((e) => !(e.kind === 'tool' && discarded.has(e.toolCallId)));
@@ -1326,18 +1285,6 @@ export function viewReducer(state, action) {
                 droppedEntries: appended.droppedEntries,
             };
         }
-        /**
-         * Rewrite the LIVE card in place.
-         *
-         * SAFE ONLY BECAUSE OF D-11'S OTHER HALF: a `ready` / `running` card has
-         * reached `<Static>` and cannot be re-printed, so `serviceEnd` appends a new
-         * entry instead of routing through here. What this handles is the window in
-         * which the card is still in the live region — `starting`, and the one
-         * transition out of it — plus the output tail while it is there.
-         *
-         * The lookup is by `serviceId` and SKIPS terminal entries, so a stray update
-         * cannot rewrite the one-row record `serviceEnd` appended.
-         */
         case 'serviceUpdate': {
             const target = findServiceEntryId(state, action.service.id);
             if (!target)
@@ -1347,15 +1294,6 @@ export function viewReducer(state, action) {
                 entries: mapEntry(state.entries, target, (e) => e.kind === 'service' ? { ...e, ...serviceFields(action.service) } : e),
             };
         }
-        /**
-         * A service reached a terminal state.
-         *
-         * TWO WRITES, AND BOTH ARE REQUIRED. The live card is settled in place so
-         * `computeSettledCount` can move past it and `estimateEntryRows` stops
-         * charging for a tail nothing will add to; the NEW one-row entry is what the
-         * user actually reads, because the card may already be printed into
-         * `<Static>` and `<Static>` cannot un-print (D-11 / R-13).
-         */
         case 'serviceEnd': {
             const target = findServiceEntryId(state, action.service.id);
             const settled = target