@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/agent/controller.d.ts

@@ -31,6 +31,7 @@ import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot
 import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
+import { type ConversationResetOptions, type ConversationResetResult } from './conversation-reset.js';
 import type { AgentMode } from './agent-mode.js';
 import type { NoticeLevel } from './reducer.js';
 /** Approval gate used whenever there is provably no human to ask (headless). */
@@ -548,9 +549,12 @@ export declare class AgentController {
     /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
     restoreTodos(items: unknown): void;
     /**
-     * `/todo clear` and `/clear`. A user override of a projection (I-2's standing
-     * exception). `/todo` refuses mid-run before it gets here; `/clear` does not,
-     * on purpose — refusing there would leave it unable to clear the transcript.
+     * `/todo clear` and `/clear screen`. A user override of a projection (I-2's
+     * standing exception). `/todo` refuses mid-run before it gets here;
+     * `/clear screen` does not, on purpose - refusing there would leave a user
+     * unable to clear the transcript mid-run. `/clear` itself is the conversation
+     * boundary: it reaches the store through `clearMessages()` with reason
+     * 'reset', after it has interrupted the run.
      */
     clearTodos(): void;
     getRetryConfig(): RetryConfig;
@@ -626,7 +630,49 @@ export declare class AgentController {
      * `subscribeTeam` / `subscribeTodos` / `subscribeFast` already set.
      */
     subscribeToolOutput(listener: ToolOutputListener): () => void;
+    /**
+     * Clear the conversation history: THE NEW-CONVERSATION BOUNDARY.
+     *
+     * Six things, and every one of them is session-scoped: cancel the idle
+     * compaction, drop the `/resume` identity, clear Core's history, bump
+     * `startupSequence`, deep-invalidate compaction and the meter, and clear the
+     * skill activation frames. `/resume` has the twin of this in `replaceMessages`,
+     * and `/clear` is this one's second caller - see
+     * `docs/plans/clear-command-context-reset/spec.md`.
+     */
     clearMessages(): void;
+    /**
+     * `/clear` (and therefore `/reset`) - the conversation reset, in the one order
+     * that is safe.
+     *
+     * A THIN ADAPTER AND NOTHING ELSE (D-7). The order - interrupt, bounded wait,
+     * archive, clear queues, clear history - lives in `agent/conversation-reset.ts`
+     * so it can be proven against a six-line fake instead of against a fully
+     * constructed controller. Everything below is a wiring decision, and two of
+     * them are load-bearing:
+     *
+     * `interruptRun` IS `forceStop()`, NOT `abort()` (P0-2 / C-1). `abort()` bumps
+     * `startupSequence` only, so the events the engine keeps emitting while it
+     * unwinds would be adopted by `App` as ordinary events of the new run - the
+     * first screen of a fresh conversation would show the previous task's text and
+     * tool cards, and the status bar would bounce back out of `idle`. `forceStop()`
+     * also increments `runGen`, which is the fence `App` compares every event
+     * against, and hard-kills a foreground `bash` that ignores the abort signal -
+     * without which the bounded wait below could only ever time out.
+     *
+     * The session is archived BEFORE the clear and never after (D-9 step 4),
+     * because after it there is nothing left to save.
+     */
+    resetConversation(opts?: ConversationResetOptions): Promise<ConversationResetResult>;
+    /**
+     * The four parts of the archive input this controller can answer itself.
+     *
+     * `entries` is NOT one of them (P0-1). The screen transcript lives in `App`'s
+     * `ViewState`, and teaching the controller about the view layer to obtain it
+     * would invert the dependency this class exists to keep. The command layer
+     * passes a thunk instead - see `CommandContext.transcriptEntries`.
+     */
+    private describeClearedConversation;
     /** Read-only view of the live system prompt (regression tests, /debug). */
     getSystemPrompt(): string;
     replaceMessages(messages: Message[], identity?: CompactionIdentity): void;

package/dist/agent/controller.js

@@ -38,6 +38,8 @@ import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
 import { buildSystemPrompt } from './system-prompt.js';
+import { resetConversationWith, } from './conversation-reset.js';
+import { archiveClearedConversation, } from '../session/clear-archive.js';
 /**
  * Extra budget, on top of `PROC_LIMITS.killGraceMs`, that `prompt()` allows a
  * force-stopped engine to unwind in before it starts a new run anyway (I-8).
@@ -1445,9 +1447,12 @@ export class AgentController {
         this.todos?.restore(items);
     }
     /**
-     * `/todo clear` and `/clear`. A user override of a projection (I-2's standing
-     * exception). `/todo` refuses mid-run before it gets here; `/clear` does not,
-     * on purpose — refusing there would leave it unable to clear the transcript.
+     * `/todo clear` and `/clear screen`. A user override of a projection (I-2's
+     * standing exception). `/todo` refuses mid-run before it gets here;
+     * `/clear screen` does not, on purpose - refusing there would leave a user
+     * unable to clear the transcript mid-run. `/clear` itself is the conversation
+     * boundary: it reaches the store through `clearMessages()` with reason
+     * 'reset', after it has interrupted the run.
      */
     clearTodos() {
         this.todos?.clear('user');
@@ -1697,6 +1702,16 @@ export class AgentController {
             this.outputListeners.delete(listener);
         };
     }
+    /**
+     * Clear the conversation history: THE NEW-CONVERSATION BOUNDARY.
+     *
+     * Six things, and every one of them is session-scoped: cancel the idle
+     * compaction, drop the `/resume` identity, clear Core's history, bump
+     * `startupSequence`, deep-invalidate compaction and the meter, and clear the
+     * skill activation frames. `/resume` has the twin of this in `replaceMessages`,
+     * and `/clear` is this one's second caller - see
+     * `docs/plans/clear-command-context-reset/spec.md`.
+     */
     clearMessages() {
         this.idleCompaction?.abort();
         this.restoredCompactionIdentity = undefined;
@@ -1723,6 +1738,66 @@ export class AgentController {
         // overriding a projection of a belief the model still holds.
         this.todos?.clear('reset');
     }
+    /**
+     * `/clear` (and therefore `/reset`) - the conversation reset, in the one order
+     * that is safe.
+     *
+     * A THIN ADAPTER AND NOTHING ELSE (D-7). The order - interrupt, bounded wait,
+     * archive, clear queues, clear history - lives in `agent/conversation-reset.ts`
+     * so it can be proven against a six-line fake instead of against a fully
+     * constructed controller. Everything below is a wiring decision, and two of
+     * them are load-bearing:
+     *
+     * `interruptRun` IS `forceStop()`, NOT `abort()` (P0-2 / C-1). `abort()` bumps
+     * `startupSequence` only, so the events the engine keeps emitting while it
+     * unwinds would be adopted by `App` as ordinary events of the new run - the
+     * first screen of a fresh conversation would show the previous task's text and
+     * tool cards, and the status bar would bounce back out of `idle`. `forceStop()`
+     * also increments `runGen`, which is the fence `App` compares every event
+     * against, and hard-kills a foreground `bash` that ignores the abort signal -
+     * without which the bounded wait below could only ever time out.
+     *
+     * The session is archived BEFORE the clear and never after (D-9 step 4),
+     * because after it there is nothing left to save.
+     */
+    async resetConversation(opts = {}) {
+        return resetConversationWith({
+            isRunning: () => this.isRunning(),
+            interruptRun: () => this.forceStop(),
+            awaitEngineIdle: () => this.waitForEngineIdle().then(() => !this.isRunning()),
+            archive: (readTranscript) => archiveClearedConversation({
+                ...this.describeClearedConversation(),
+                entries: readTranscript(),
+            }),
+            clearQueues: () => this.clearAllQueues(),
+            clearHistory: () => {
+                const cleared = this.agent.state.messages.length;
+                this.clearMessages();
+                return cleared;
+            },
+        }, opts);
+    }
+    /**
+     * The four parts of the archive input this controller can answer itself.
+     *
+     * `entries` is NOT one of them (P0-1). The screen transcript lives in `App`'s
+     * `ViewState`, and teaching the controller about the view layer to obtain it
+     * would invert the dependency this class exists to keep. The command layer
+     * passes a thunk instead - see `CommandContext.transcriptEntries`.
+     */
+    describeClearedConversation() {
+        const snapshot = this.getSessionSnapshot();
+        return {
+            model: {
+                providerId: this.config.provider,
+                modelId: this.config.model,
+                ...(this.config.baseUrl ? { baseUrl: this.config.baseUrl } : {}),
+            },
+            messages: snapshot.messages,
+            ...(snapshot.compactionIdentity ? { compactionIdentity: snapshot.compactionIdentity } : {}),
+            todos: this.getTodoSnapshot()?.items ?? [],
+        };
+    }
     /** Read-only view of the live system prompt (regression tests, /debug). */
     getSystemPrompt() {
         return this.agent.state.systemPrompt;

package/dist/agent/conversation-reset.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The single authority on the ORDER of a conversation reset
+ * (clear-command-context-reset §3.4 / D-9).
+ *
+ * ASCII ONLY: `src/agent/**` is inside `glyphs.test.ts::inScope`, and this module
+ * contributes transcript text (the "could not stop" message) through the command
+ * layer.
+ *
+ * WHY A PORT RATHER THAN A METHOD ON `AgentController`: the order - interrupt,
+ * bounded wait, archive, clear queues, clear history - is the thing that has a
+ * correctness proof attached to it (a clear that lands before the engine unwinds
+ * pollutes the new conversation, or produces a `tool_use` with no `tool_result`).
+ * Written as a method, that order can only be tested by constructing a controller
+ * and everything it wires. Written against a port, the order itself is the thing
+ * under test, and every failure branch is reachable from a six-line fake.
+ *
+ * `interruptRun` IS NOT CALLED `abort`, ON PURPOSE (P0-2). It maps to
+ * `controller.forceStop()`, which does three things `abort()` does not: it
+ * hard-kills foreground `bash` children (the only thing that unblocks a tool that
+ * ignores the abort signal), and it bumps `runGen` - the generation fence `App`
+ * compares every engine event against. A method named `abort` that quietly does
+ * more than the existing `abort()` would be the exact kind of misleading name
+ * this feature exists to remove.
+ */
+import type { Entry } from './reducer.js';
+/** The minimal host surface a reset needs. Supplied by `AgentController` alone. */
+export interface ConversationResetPort {
+    /** Whether a run is in flight right now. */
+    isRunning(): boolean;
+    /**
+     * Interrupt the current run: `controller.forceStop()` (P0-2).
+     *
+     * = `abort()` (stops team / fast / compaction) + `killForeground('force')`
+     * + `runGen += 1`. Background services are deliberately untouched.
+     */
+    interruptRun(): void;
+    /** Bounded wait for the engine to unwind; `true` means it settled. */
+    awaitEngineIdle(): Promise<boolean>;
+    /**
+     * Best-effort archive of the old conversation; an absolute path, or `null`.
+     *
+     * `readTranscript` is supplied by the caller because the screen transcript lives
+     * in `ViewState`, which the controller does not and must not know about (P0-1).
+     * Implementations never throw.
+     */
+    archive(readTranscript: () => Entry[]): string | null;
+    /** Drop Core's two queues plus the CLI's pending steering list. */
+    clearQueues(): void;
+    /** Clear the history (the six-part boundary) and return the message count. */
+    clearHistory(): number;
+}
+export interface ConversationResetOptions {
+    /** Interrupt a running engine (default `true`). `false` refuses instead. */
+    interrupt?: boolean;
+    /** Read the screen transcript for the archive. Absent = history-only archive. */
+    readTranscript?: () => Entry[];
+}
+export type ConversationResetResult = {
+    ok: true;
+    interrupted: boolean;
+    archivedPath: string | null;
+    messagesCleared: number;
+} | {
+    ok: false;
+    reason: 'still-running';
+    message: string;
+};
+/**
+ * The one message a failed reset shows. It names the NEXT ACTION rather than the
+ * failure, because `forceStop()` already ran: what is left to try is the human's
+ * own hand.
+ */
+export declare const CLEAR_STILL_RUNNING_MESSAGE = "Could not stop the current run. Press Esc twice to force-stop, then /clear.";
+/**
+ * Reset the conversation, in the only order that is safe.
+ *
+ * THE ORDER IS THE DESIGN (D-9). Each step exists because of what happens if it
+ * moves:
+ *  1. interrupt - a clear that does not stop the loop first is overwritten by the
+ *     loop's next `tool_result` append;
+ *  2. bounded wait - the interrupt is a request; `agent.abort()` resolves nothing
+ *     by itself, so clearing now still races the unwind;
+ *  3. archive - BEFORE the clear, because after it there is nothing left to save;
+ *  4. clear queues - before the history, so a drain cannot re-feed the old queue;
+ *  5. clear history - the six-part boundary plus `startupSequence`.
+ *
+ * A FAILED WAIT CLEARS NOTHING (I-4). Half a reset - queues emptied, history
+ * still there - is worse than no reset at all, because the view and the engine
+ * then disagree with no visible cause.
+ */
+export declare function resetConversationWith(port: ConversationResetPort, opts?: ConversationResetOptions): Promise<ConversationResetResult>;

package/dist/agent/conversation-reset.js

@@ -0,0 +1,66 @@
+/**
+ * The single authority on the ORDER of a conversation reset
+ * (clear-command-context-reset §3.4 / D-9).
+ *
+ * ASCII ONLY: `src/agent/**` is inside `glyphs.test.ts::inScope`, and this module
+ * contributes transcript text (the "could not stop" message) through the command
+ * layer.
+ *
+ * WHY A PORT RATHER THAN A METHOD ON `AgentController`: the order - interrupt,
+ * bounded wait, archive, clear queues, clear history - is the thing that has a
+ * correctness proof attached to it (a clear that lands before the engine unwinds
+ * pollutes the new conversation, or produces a `tool_use` with no `tool_result`).
+ * Written as a method, that order can only be tested by constructing a controller
+ * and everything it wires. Written against a port, the order itself is the thing
+ * under test, and every failure branch is reachable from a six-line fake.
+ *
+ * `interruptRun` IS NOT CALLED `abort`, ON PURPOSE (P0-2). It maps to
+ * `controller.forceStop()`, which does three things `abort()` does not: it
+ * hard-kills foreground `bash` children (the only thing that unblocks a tool that
+ * ignores the abort signal), and it bumps `runGen` - the generation fence `App`
+ * compares every engine event against. A method named `abort` that quietly does
+ * more than the existing `abort()` would be the exact kind of misleading name
+ * this feature exists to remove.
+ */
+/**
+ * The one message a failed reset shows. It names the NEXT ACTION rather than the
+ * failure, because `forceStop()` already ran: what is left to try is the human's
+ * own hand.
+ */
+export const CLEAR_STILL_RUNNING_MESSAGE = 'Could not stop the current run. Press Esc twice to force-stop, then /clear.';
+/**
+ * Reset the conversation, in the only order that is safe.
+ *
+ * THE ORDER IS THE DESIGN (D-9). Each step exists because of what happens if it
+ * moves:
+ *  1. interrupt - a clear that does not stop the loop first is overwritten by the
+ *     loop's next `tool_result` append;
+ *  2. bounded wait - the interrupt is a request; `agent.abort()` resolves nothing
+ *     by itself, so clearing now still races the unwind;
+ *  3. archive - BEFORE the clear, because after it there is nothing left to save;
+ *  4. clear queues - before the history, so a drain cannot re-feed the old queue;
+ *  5. clear history - the six-part boundary plus `startupSequence`.
+ *
+ * A FAILED WAIT CLEARS NOTHING (I-4). Half a reset - queues emptied, history
+ * still there - is worse than no reset at all, because the view and the engine
+ * then disagree with no visible cause.
+ */
+export async function resetConversationWith(port, opts = {}) {
+    const interrupt = opts.interrupt ?? true;
+    const running = port.isRunning();
+    if (running && !interrupt) {
+        return { ok: false, reason: 'still-running', message: CLEAR_STILL_RUNNING_MESSAGE };
+    }
+    if (running) {
+        port.interruptRun();
+        const settled = await port.awaitEngineIdle();
+        if (!settled) {
+            return { ok: false, reason: 'still-running', message: CLEAR_STILL_RUNNING_MESSAGE };
+        }
+    }
+    const readTranscript = opts.readTranscript ?? (() => []);
+    const archivedPath = port.archive(readTranscript);
+    port.clearQueues();
+    const messagesCleared = port.clearHistory();
+    return { ok: true, interrupted: running, archivedPath, messagesCleared };
+}

package/dist/agent/model-probe-limits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Structural bounds for the profile connection probe (model-profile-connection-test §7).
+ *
+ * STRUCTURAL, NOT POLICY: nothing here is clamped, persisted or user-tunable. These
+ * are the physical limits of one probe - how long a single round trip may take, how
+ * many lines and characters a result may occupy, how many models a list page can
+ * carry before it must truncate. The user-tunable keys live in `config/schema.ts`.
+ *
+ * THE OUTPUT-TOKEN CAP IS DELIBERATELY ABSENT. It must come from core's
+ * `MIN_MAX_OUTPUT_TOKENS`, or this file becomes a second authority for "how many
+ * tokens may this model produce" - which is exactly what `output-limits.ts` exists
+ * to prevent.
+ *
+ * ASCII ONLY: this module lives in `agent/`, which `glyphs.test.ts::inScope` scans.
+ */
+export interface ProbeLimits {
+    /** Ceiling on ONE real round trip (`complete`). */
+    testTimeoutMs: number;
+    /**
+     * Sub-budget for the best-effort model list that runs CONCURRENTLY with the
+     * completion. It never decides the verdict (§4.3 / RV-P1-1): a slow `/models`
+     * that ate the adapter's own 15 s discovery timeout would turn a healthy
+     * connection into a false `timeout`.
+     */
+    listModelsBudgetMs: number;
+    /** Ceiling on a discovery (`listModels`) issued from the list page. */
+    discoveryTimeoutMs: number;
+    /** Characters of the model's reply kept for the `Reply:` line. */
+    replyChars: number;
+    /** Characters of a locally composed failure sentence. */
+    detailChars: number;
+    /** Rows a list page may carry before `truncated` becomes true. */
+    maxListedModels: number;
+    /** Above this many rows the list page grows a search line (picker parity). */
+    searchThreshold: number;
+    /** Characters of a model's display name kept in one list row. */
+    maxNameChars: number;
+}
+export declare const PROBE_LIMITS: ProbeLimits;

package/dist/agent/model-probe-limits.js

@@ -0,0 +1,25 @@
+/**
+ * Structural bounds for the profile connection probe (model-profile-connection-test §7).
+ *
+ * STRUCTURAL, NOT POLICY: nothing here is clamped, persisted or user-tunable. These
+ * are the physical limits of one probe - how long a single round trip may take, how
+ * many lines and characters a result may occupy, how many models a list page can
+ * carry before it must truncate. The user-tunable keys live in `config/schema.ts`.
+ *
+ * THE OUTPUT-TOKEN CAP IS DELIBERATELY ABSENT. It must come from core's
+ * `MIN_MAX_OUTPUT_TOKENS`, or this file becomes a second authority for "how many
+ * tokens may this model produce" - which is exactly what `output-limits.ts` exists
+ * to prevent.
+ *
+ * ASCII ONLY: this module lives in `agent/`, which `glyphs.test.ts::inScope` scans.
+ */
+export const PROBE_LIMITS = {
+    testTimeoutMs: 20_000,
+    listModelsBudgetMs: 5_000,
+    discoveryTimeoutMs: 20_000,
+    replyChars: 60,
+    detailChars: 160,
+    maxListedModels: 400,
+    searchThreshold: 8,
+    maxNameChars: 48,
+};

package/dist/agent/model-probe.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The connection probe behind `Test connection` and `Discover models`
+ * (model-profile-connection-test §4.2-§4.8).
+ *
+ * WHY THIS IS NOT `ModelRegistry.discoverModels()`: that path folds every exception
+ * into `[]` and stores the result in a five-minute process-wide cache. Using it here
+ * would (a) collapse "wrong key", "wrong URL" and "this account owns no models" into
+ * one sentence, and (b) let a probe of an UNSAVED draft endpoint poison `/model`,
+ * `/context` and the main session's window resolution for five minutes. So the probe
+ * talks to the adapter directly and classifies by `LLMError.errorType`.
+ *
+ * WHY `complete()` AND NOT ONLY `listModels()`: a model can be listed and still be
+ * unable to generate (gateway aliases, permission layers). One real round trip is the
+ * only honest answer to "does this work right now", and it is also the only evidence
+ * that can produce `model_not_found`.
+ *
+ * ASCII ONLY: `agent/` is inside `glyphs.test.ts::inScope`.
+ */
+import { type ProviderRegistry } from '@aragon-agent/core';
+/** Every way a probe can fail, once and for all (§7). */
+export type ProbeFailureKind = 'missing_key' | 'unsupported_provider' | 'invalid_base_url' | 'auth' | 'model_not_found' | 'invalid_request' | 'rate_limit' | 'provider_unavailable' | 'network' | 'timeout' | 'cancelled' | 'unknown';
+export interface ProbeTarget {
+    provider: string;
+    /** `''` means "no model typed yet" - the probe then only lists models. */
+    model: string;
+    baseUrl: string | null;
+    /** The RESOLVED plaintext key from `resolveDraftKey()`, never `editor.apiKey`. */
+    apiKey: string | null;
+}
+export interface ProbeRequest extends ProbeTarget {
+    signal?: AbortSignal;
+}
+export interface ProbeOutcome {
+    ok: boolean;
+    /** Fingerprint of the target this outcome describes (§4.6). */
+    targetId: string;
+    latencyMs: number;
+    kind?: ProbeFailureKind;
+    /** Locally composed, already redacted sentence. Never provider response text. */
+    detail?: string;
+    reply?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    availableModels?: number;
+    modelListed?: boolean;
+}
+export interface ModelCandidate {
+    id: string;
+    name: string;
+    contextWindow?: number;
+    supportsTools: boolean;
+}
+export interface DiscoveryOutcome {
+    ok: boolean;
+    connectionId: string;
+    kind?: ProbeFailureKind;
+    detail?: string;
+    models: ModelCandidate[];
+    truncated: boolean;
+    /**
+     * How many models the endpoint returned BEFORE truncation. The truncation line
+     * needs the real number ("Showing first 400 of 960"), and re-deriving it from a
+     * clamped array is impossible.
+     */
+    total?: number;
+}
+export interface ModelProbe {
+    test(request: ProbeRequest): Promise<ProbeOutcome>;
+    discover(request: ProbeRequest): Promise<DiscoveryOutcome>;
+    targetFingerprint(target: ProbeTarget): string;
+    connectionFingerprint(target: ProbeTarget): string;
+}
+export interface ProbeDeps {
+    registry: Pick<ProviderRegistry, 'get'>;
+    /** Injected clock; tests pin `latencyMs` through it. */
+    now?: () => number;
+}
+/**
+ * Which key this draft would actually use (§4.2.1).
+ *
+ * The editor's `apiKey` field is ALWAYS the empty string: it is the replacement
+ * input, not the live credential. `finishProfileEditor` resolves `keep` to the
+ * saved entry key and `shared` to `null`, and the runtime then falls back to the
+ * shared per-provider key. Without this table the most common path - editing an
+ * existing profile, whose credential mode defaults to `keep` - would report
+ * `(no key)` for a profile that has one.
+ */
+export declare function resolveDraftKey(input: {
+    credentialMode: 'keep' | 'replace' | 'shared';
+    draftKey: string;
+    existingKey: string | null;
+    sharedKey?: string;
+}): string | null;
+/**
+ * The host a failure sentence names - same four clauses as
+ * `profileEndpointSummary()` in `ui/overlays/ModelProfilePicker.tsx`, which this
+ * layer may not import (agent -> ui would invert the layering). `model-probe.test.ts`
+ * asserts the two agree, so the duplication cannot drift silently.
+ */
+export declare function endpointHost(baseUrl: string | null): string;
+/** Create the probe port. One instance per App; `SettingsScreen` only passes it down. */
+export declare function createModelProbe(deps: ProbeDeps): ModelProbe;