@aragon-agent/cli 0.6.24 → 0.6.25

package/dist/agent/model-probe.js

@@ -0,0 +1,391 @@
+/**
+ * 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 { createHash } from 'node:crypto';
+import { LLMError, MIN_MAX_OUTPUT_TOKENS, classifyOutputLimitFailure, } from '@aragon-agent/core';
+import { isValidEndpointUrl } from '../config/model-profiles.js';
+import { getLogger } from '../logging/logger.js';
+import { PROBE_LIMITS } from './model-probe-limits.js';
+/** `Reply with the single word OK.` - one isolated call, no tools, no system prompt. */
+const PROBE_PROMPT = 'Reply with the single word OK.';
+const UNKNOWN_DETAIL = 'The provider failed in an unrecognized way.';
+const NO_KEY_DETAIL_SUFFIX = ' Set one here or in the environment.';
+/**
+ * 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 function resolveDraftKey(input) {
+    const nonEmpty = (value) => value && value.trim().length > 0 ? value.trim() : null;
+    if (input.credentialMode === 'replace')
+        return nonEmpty(input.draftKey);
+    if (input.credentialMode === 'keep') {
+        return nonEmpty(input.existingKey) ?? nonEmpty(input.sharedKey);
+    }
+    return nonEmpty(input.sharedKey);
+}
+/** Trailing slashes are not part of an endpoint's identity. */
+function normalizeBaseUrl(baseUrl) {
+    const trimmed = (baseUrl ?? '').trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.replace(/\/+$/, '');
+}
+function keyDigest(apiKey) {
+    const trimmed = (apiKey ?? '').trim();
+    if (trimmed.length === 0)
+        return 'none';
+    return createHash('sha256').update(trimmed).digest('hex').slice(0, 12);
+}
+/**
+ * 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 function endpointHost(baseUrl) {
+    if (!baseUrl || baseUrl.trim().length === 0)
+        return 'the provider';
+    try {
+        const url = new URL(baseUrl.trim());
+        return url.username || url.password || url.search || url.hash ? 'this endpoint'
+            : url.host || 'the provider';
+    }
+    catch {
+        return 'this endpoint';
+    }
+}
+function fingerprint(provider, baseUrl, apiKey, model) {
+    const connection = `${provider}|${normalizeBaseUrl(baseUrl) ?? ''}|${keyDigest(apiKey)}`;
+    return model === undefined ? connection : `${connection}|${model.trim()}`;
+}
+/** Absolute sentence so a redacted, truncated message can never show a key. */
+function redactDetail(text, secrets) {
+    let safe = text;
+    for (const secret of secrets) {
+        if (secret.length > 0)
+            safe = safe.split(secret).join('[redacted]');
+    }
+    return safe.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, PROBE_LIMITS.detailChars);
+}
+/**
+ * One timer, two recorded facts. `cancelled` and `timeout` must be distinguishable
+ * AFTER the fact, because an aborted adapter may resolve quietly or throw something
+ * that looks like a network error (§4.3 step 6).
+ */
+function createDeadline(timeoutMs, parent) {
+    const controller = new AbortController();
+    let fired = false;
+    const onParentAbort = () => controller.abort();
+    if (parent) {
+        if (parent.aborted)
+            controller.abort();
+        else
+            parent.addEventListener('abort', onParentAbort, { once: true });
+    }
+    const handle = setTimeout(() => { fired = true; controller.abort(); }, timeoutMs);
+    unrefTimer(handle);
+    return {
+        signal: controller.signal,
+        isFired: () => fired,
+        isCancelled: () => parent?.aborted === true,
+        dispose: () => {
+            clearTimeout(handle);
+            parent?.removeEventListener('abort', onParentAbort);
+        },
+    };
+}
+/**
+ * Run the best-effort model list under a cap. It never rejects and never vetoes.
+ *
+ * The cap timer is `unref`'d exactly like the deadline (§4.8): after a fast verdict the
+ * list is still in flight, and a referenced five-second timer would keep the process
+ * alive on exit for a number nobody is going to read.
+ *
+ * Taking a THUNK rather than a promise is what stops a synchronous throw (§4.3 step 3):
+ * an adapter that fails before its first `await` - a test double, or a guard clause -
+ * would otherwise escape past this layer and cancel a completion not yet attempted.
+ */
+function withCap(call, ms) {
+    let pending;
+    try {
+        pending = call();
+    }
+    catch {
+        return Promise.resolve(undefined);
+    }
+    return new Promise((resolve) => {
+        const handle = setTimeout(() => resolve(undefined), ms);
+        unrefTimer(handle);
+        const settle = (value) => { clearTimeout(handle); resolve(value); };
+        pending.then((value) => settle(value), () => settle(undefined));
+    });
+}
+/** Timers and immediates both expose `unref<Timer>`; neither may outlive the probe. */
+function unrefTimer(handle) {
+    const unrefable = handle;
+    unrefable.unref?.();
+}
+/**
+ * The list AS IT STANDS when the verdict is reached.
+ *
+ * One macrotask of grace, so a list that resolved while the completion was in flight
+ * publishes itself before we judge - and a list still in flight is NOT waited for,
+ * because it has no veto over the verdict (§4.3 step 3 / RV-P1-1).
+ */
+function listAtVerdict(listing) {
+    const grant = new Promise((resolve) => {
+        unrefTimer(setImmediate(() => resolve(undefined)));
+    });
+    return Promise.race([listing, grant]);
+}
+function guardFailure(provider, request, targetId) {
+    const base = { ok: false, targetId, latencyMs: 0 };
+    if (!provider) {
+        return { ...base, kind: 'unsupported_provider',
+            detail: `This build has no adapter for ${request.provider}.` };
+    }
+    if (!request.apiKey || request.apiKey.trim().length === 0) {
+        return { ...base, kind: 'missing_key',
+            detail: `No API key for ${request.provider}.${NO_KEY_DETAIL_SUFFIX}` };
+    }
+    if (request.baseUrl && !isValidEndpointUrl(request.baseUrl)) {
+        return { ...base, kind: 'invalid_base_url',
+            detail: 'Base URL must be an http(s) URL without credentials, query or fragment.' };
+    }
+    return undefined;
+}
+function mentionsModel(err) {
+    return /model/i.test(err.message);
+}
+/** The ONE classification matrix (§4.4). Signal facts are checked by the caller. */
+function classifyError(err, facts) {
+    if (!(err instanceof LLMError))
+        return { kind: 'unknown', detail: UNKNOWN_DETAIL };
+    const status = typeof err.statusCode === 'number' ? err.statusCode : undefined;
+    const suffix = status === undefined ? '' : ` (HTTP ${status})`;
+    switch (err.errorType) {
+        case 'auth_error':
+            return { kind: 'auth', detail: `Key rejected by ${facts.provider}${suffix}.` };
+        case 'invalid_request':
+        case 'context_overflow':
+            return mentionsModel(err)
+                ? { kind: 'model_not_found',
+                    detail: `The provider did not accept model "${facts.model}"${suffix}.` }
+                : { kind: 'invalid_request', detail: `The provider rejected the request${suffix}.` };
+        case 'rate_limit':
+            return { kind: 'rate_limit',
+                detail: `Rate limited by ${facts.provider}${suffix || ' (HTTP 429)'}. Try again shortly.` };
+        case 'overloaded':
+        case 'server_error':
+            return { kind: 'provider_unavailable',
+                detail: `${facts.provider} is unavailable right now${suffix}.` };
+        case 'network_error':
+            return { kind: 'network',
+                detail: `Could not reach ${facts.host}. Check the base URL, DNS, proxy or VPN.` };
+        case 'timeout':
+            return { kind: 'timeout',
+                detail: `No answer from ${facts.host} within ${facts.timeoutSeconds} s.` };
+        default:
+            return { kind: 'unknown', detail: UNKNOWN_DETAIL };
+    }
+}
+function firstText(message) {
+    const block = message.content.find((part) => part.type === 'text');
+    return block && block.type === 'text' ? block.text : undefined;
+}
+/** Only text literally present in the error body may count as "the field is wrong". */
+function errorBody(err) {
+    return typeof err.raw === 'string' ? err.raw : err.message;
+}
+function isTokenFieldRejection(err, provider) {
+    if (!(err instanceof LLMError))
+        return false;
+    return classifyOutputLimitFailure(provider, err.statusCode ?? 0, errorBody(err)) !== undefined;
+}
+function requestFor(request, deadline, maxTokens) {
+    return {
+        model: request.model.trim(),
+        messages: [{ role: 'user', content: PROBE_PROMPT }],
+        apiKey: request.apiKey ?? '',
+        ...(request.baseUrl ? { baseUrl: request.baseUrl } : {}),
+        signal: deadline.signal,
+        ...(maxTokens === undefined ? {} : { maxTokens }),
+    };
+}
+function logProbe(facts, outcome, now) {
+    try {
+        getLogger().child('llm').info('probe_result', {
+            provider: facts.provider, model: facts.model, host: facts.host,
+            latencyMs: outcome.latencyMs, ok: outcome.ok, kind: outcome.kind ?? 'ok',
+            at: now,
+        });
+    }
+    catch { /* logging must never fail a probe */ }
+}
+function candidateOf(model) {
+    return {
+        id: model.id,
+        name: model.name && model.name !== model.id ? model.name : model.id,
+        ...(model.contextWindowSource === 'api' && model.contextWindow
+            ? { contextWindow: model.contextWindow } : {}),
+        supportsTools: model.supportsTools === true,
+    };
+}
+async function runDiscovery(provider, request, connectionId) {
+    const guard = guardFailure(provider, request, connectionId);
+    if (guard) {
+        return { ok: false, connectionId, kind: guard.kind, detail: guard.detail, models: [],
+            truncated: false, total: 0 };
+    }
+    const deadline = createDeadline(PROBE_LIMITS.discoveryTimeoutMs, request.signal);
+    const facts = { provider: request.provider, model: request.model,
+        host: endpointHost(request.baseUrl), timeoutSeconds: PROBE_LIMITS.discoveryTimeoutMs / 1000 };
+    try {
+        const listed = await provider.listModels(request.apiKey, request.baseUrl ?? undefined, deadline.signal);
+        const candidates = (listed ?? []).map(candidateOf).filter((entry) => entry.id.length > 0);
+        return { ok: true, connectionId, total: candidates.length,
+            models: candidates.slice(0, PROBE_LIMITS.maxListedModels),
+            truncated: candidates.length > PROBE_LIMITS.maxListedModels };
+    }
+    catch (failure) {
+        const verdict = request.signal?.aborted ? { kind: 'cancelled', detail: 'Cancelled.' }
+            : deadline.isFired()
+                ? { kind: 'timeout',
+                    detail: `No answer from ${facts.host} within ${facts.timeoutSeconds} s.` }
+                : classifyError(failure, facts);
+        return { ok: false, connectionId, kind: verdict.kind, detail: verdict.detail, models: [],
+            truncated: false, total: 0 };
+    }
+    finally {
+        deadline.dispose();
+    }
+}
+/** Create the probe port. One instance per App; `SettingsScreen` only passes it down. */
+export function createModelProbe(deps) {
+    const now = deps.now ?? Date.now;
+    return {
+        targetFingerprint: (target) => fingerprint(target.provider, target.baseUrl, target.apiKey, target.model),
+        connectionFingerprint: (target) => fingerprint(target.provider, target.baseUrl, target.apiKey),
+        discover: (request) => runDiscovery(deps.registry.get(request.provider), request, fingerprint(request.provider, request.baseUrl, request.apiKey)),
+        test: (request) => runTest(deps, request),
+    };
+}
+async function runTest(deps, request) {
+    const clock = deps.now ?? Date.now;
+    const started = clock();
+    const targetId = fingerprint(request.provider, request.baseUrl, request.apiKey, request.model);
+    const provider = deps.registry.get(request.provider);
+    const guard = guardFailure(provider, request, targetId);
+    if (guard)
+        return guard;
+    const adapter = provider;
+    const deadline = createDeadline(PROBE_LIMITS.testTimeoutMs, request.signal);
+    const facts = { provider: request.provider, model: request.model.trim(),
+        host: endpointHost(request.baseUrl), timeoutSeconds: PROBE_LIMITS.testTimeoutMs / 1000 };
+    // The list runs CONCURRENTLY and has no veto (§4.3 step 3): it may only decorate a
+    // verdict the completion already produced. Nothing waits for it except the
+    // model-less path, which has no completion to wait for.
+    const listing = withCap(() => adapter.listModels(request.apiKey, request.baseUrl ?? undefined, deadline.signal), PROBE_LIMITS.listModelsBudgetMs);
+    try {
+        return await completeAndJudge(adapter, request, deadline, facts, { targetId, started, now: clock, listing });
+    }
+    finally {
+        deadline.dispose();
+    }
+}
+async function completeAndJudge(provider, request, deadline, facts, context) {
+    const base = { targetId: context.targetId };
+    if (request.model.trim().length === 0) {
+        // Nothing to complete: list only, and report what the key can reach.
+        const reachable = await context.listing;
+        const latencyMs = context.now() - context.started;
+        if (request.signal?.aborted) {
+            return { ...base, ok: false, latencyMs, kind: 'cancelled', detail: 'Cancelled.' };
+        }
+        if (deadline.isFired()) {
+            return { ...base, ok: false, latencyMs, kind: 'timeout',
+                detail: `No answer from ${facts.host} within ${facts.timeoutSeconds} s.` };
+        }
+        return { ...base, ok: true, latencyMs,
+            ...(reachable ? { availableModels: reachable.length } : {}) };
+    }
+    let message;
+    let failure;
+    try {
+        message = await provider.complete(requestFor(request, deadline, MIN_MAX_OUTPUT_TOKENS));
+    }
+    catch (error) {
+        failure = error;
+    }
+    if (failure !== undefined && isTokenFieldRejection(failure, request.provider)) {
+        // Exactly ONE repair retry with the cap left to the adapter's own learned field.
+        try {
+            message = await provider.complete(requestFor(request, deadline));
+            failure = undefined;
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    const latencyMs = context.now() - context.started;
+    if (request.signal?.aborted) {
+        return { ...base, ok: false, latencyMs, kind: 'cancelled', detail: 'Cancelled.' };
+    }
+    if (deadline.isFired()) {
+        return { ...base, ok: false, latencyMs, kind: 'timeout',
+            detail: `No answer from ${facts.host} within ${facts.timeoutSeconds} s.` };
+    }
+    if (failure !== undefined || !message) {
+        const verdict = classifyError(failure, facts);
+        const secrets = [request.apiKey ?? ''];
+        const outcome = { ...base, ok: false, latencyMs, kind: verdict.kind,
+            detail: redactDetail(verdict.detail, secrets) };
+        const reachable = await listAtVerdict(context.listing);
+        if (reachable)
+            outcome.availableModels = reachable.length;
+        if (verdict.kind === 'model_not_found' && reachable) {
+            outcome.modelListed = reachable.some((model) => model.id === facts.model);
+        }
+        logProbe(facts, outcome, context.now());
+        return outcome;
+    }
+    const text = firstText(message);
+    if (text === undefined) {
+        const outcome = { ...base, ok: false, latencyMs, kind: 'unknown',
+            detail: UNKNOWN_DETAIL };
+        logProbe(facts, outcome, context.now());
+        return outcome;
+    }
+    const reachable = await listAtVerdict(context.listing);
+    const outcome = {
+        ...base, ok: true, latencyMs,
+        reply: text.trim().slice(0, PROBE_LIMITS.replyChars),
+        ...(message.usage ? { usage: { inputTokens: message.usage.inputTokens,
+                outputTokens: message.usage.outputTokens } } : {}),
+        ...(reachable ? { availableModels: reachable.length,
+            modelListed: reachable.some((model) => model.id === facts.model) } : {}),
+    };
+    logProbe(facts, outcome, context.now());
+    return outcome;
+}

package/dist/agent/reducer.js

@@ -767,25 +767,32 @@ export function viewReducer(state, action) {
                 ...state,
                 entries: [],
                 // The count describes what the RETAIN RING removed from the visible
-                // transcript. `/clear` empties it by intent, so carrying the number
+                // transcript. `/clear screen` empties it by intent, so carrying the number
                 // over would make the exported transcript claim a loss that did not
                 // happen.
                 droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
                 teamEntryId: undefined,
-                // The list goes with the screen it was on. `/clear` is an explicit user
-                // instruction, which is I-2's standing exception (`TodoClearReason`
-                // `'user'`, the same door `/todo clear` uses) — so the command clears the
+                // The list goes with the screen it was on. `/clear screen` is an explicit
+                // user instruction, which is I-2's standing exception (`TodoClearReason`
+                // `'user'`, the same door `/todo clear` uses) - so the command clears the
                 // STORE via `controller.clearTodos()` and this clears the MIRROR, exactly
                 // the pairing `resetConversation` below has always had.
                 //
                 // The mirror write is same-valued with the store's own `todoCleared`
                 // dispatch rather than redundant with it: it is what makes this action
-                // stand on its own. `builtins.ts` is the only dispatcher of it TODAY, and
-                // a second one — a real clear-screen key, a session-restore path — would
+                // stand on its own. `commands/clear-command.ts` is its only dispatcher
+                // TODAY - `/clear` itself now goes through `resetConversation`, because
+                // clearing the SCREEN and clearing the SESSION are different intentions
+                // (clear-command-context-reset D-3) - and a hypothetical second one would
                 // otherwise bring the bug back in identical form and in silence.
                 //
+                // KEPT RATHER THAN FOLDED INTO `resetConversation` for the same reason:
+                // a user who wants the screen back must not have to destroy their context
+                // to get it, and an action with no dispatcher is dead code by `CLAUDE.md`
+                // section 4 - which is what `/clear screen` prevents.
+                //
                 // The entry id is dropped because the entry it pointed at is gone.
                 todos: null,
                 todoEntryId: undefined,
@@ -799,7 +806,7 @@ export function viewReducer(state, action) {
                 // id must go with it or `compactionEnd` would `mapEntry` an id that no
                 // longer exists. `compaction` STAYS — unlike `retry` it is not a
                 // projection of an entry, it is the live state of a subsystem that is
-                // still running, and `/clear` clears the screen rather than the session.
+                // still running. `/clear screen` clears the screen, not the session.
                 compactionEntryId: undefined,
             };
         case 'resetConversation':
@@ -810,22 +817,47 @@ export function viewReducer(state, action) {
                 droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
-                // `context` IS DELIBERATELY UNTOUCHED (I-1). `builtins.ts` calls
-                // `controller.clearMessages()` BEFORE dispatching this, and that marks
-                // the meter dirty and schedules a publication; zeroing here would make
-                // the final state `0` rather than the meter's real answer - which for an
+                // `context` IS DELIBERATELY UNTOUCHED (I-1). `clear-command.ts` calls
+                // `controller.resetConversation()` BEFORE dispatching this, and that marks
+                // the meter dirty and schedules a publication; zeroing here would make the
+                // final state `0` rather than the meter's real answer - which for an
                 // emptied conversation is the system prompt's own couple of percent, not
                 // nothing. `usageTotal` DOES reset: that is session spend, not occupancy.
                 usageTotal: EMPTY_USAGE_TOTAL,
                 teamEntryId: undefined,
-                // `/reset` clears `messages`, so the belief is gone and the list goes
-                // with it — the other half of I-2. `controller.clearMessages()` clears
+                // `/clear` clears `messages`, so the belief is gone and the list goes
+                // with it - the other half of I-2. `controller.clearMessages()` clears
                 // the STORE; this clears the mirror.
                 todos: null,
                 todoEntryId: undefined,
                 retryEntryId: undefined,
                 retry: null,
                 compactionEntryId: undefined,
+                // THE SIX RUN FACTS THIS BRANCH USED TO KEEP (clear-command-context-reset
+                // §3.6 / P0-3). `reduceRunFacts` above already zeroes `runPhase`,
+                // `activeTool`, `runOutcome` and `seenSteeringIds`, so nothing here
+                // repeats those four - these six are the actual gap, and each one
+                // otherwise describes a run that no longer exists.
+                //
+                // `status` is the status bar: a late `runEnd` would correct it a moment
+                // later, and until then the user is told a conversation that is over is
+                // still running. `team` is a dispatch panel with nothing dispatching.
+                // `fastEntryId` points at a `kind: 'fast'` card that `entries: []` just
+                // deleted, the same dangling-id rule `retryEntryId` and
+                // `compactionEntryId` above already follow.
+                //
+                // `turnProduced` / `errorNoticed` / `aborted` are ALSO cleared by
+                // `submit`, which is not a reason to leave them out: clearing is an
+                // independent entry point, so a user who clears and then only reads the
+                // panel would carry the previous turn's three facts into a conversation
+                // they never submitted into - and `runEnd`'s settle rule reads exactly
+                // those three.
+                status: 'idle',
+                team: null,
+                fastEntryId: undefined,
+                turnProduced: false,
+                errorNoticed: false,
+                aborted: false,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };

package/dist/commands/builtins.js

@@ -21,6 +21,7 @@ import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
 import { registerQueueCommand } from './queue-command.js';
 import { perfCommand } from './perf.js';
 import { runCompactCommand } from '../compaction/command.js';
+import { runClearCommand } from './clear-command.js';
 import { runContextCommand } from '../compaction/context-command.js';
 /**
  * `/fast status` — THE GUARANTEED REPORTING SURFACE for the tier (§4.4 / R-8).
@@ -957,44 +958,23 @@ const COMMANDS = [
         },
     },
     {
+        // REGISTRATION ONLY. The body lives in `commands/clear-command.ts`: this file
+        // is already past the 1000-line guideline, and `/clear` is no longer a
+        // two-line projection reset - it interrupts a run, waits for it, archives the
+        // conversation and then clears (clear-command-context-reset D-8).
         name: 'clear',
-        description: 'Clear the visible transcript and the todo panel',
-        run: (ctx) => {
-            // A USER OVERRIDE OF A PROJECTION, the same class as `/todo clear`, so it
-            // reuses reason `'user'`; I-2 and its standing exception are stated on
-            // `TodoStore`. Clearing the STORE and not merely the view mirror is what
-            // keeps `/save`, `/todo status|continue` and follow-through agreeing with
-            // the screen — they read the store directly. `messages` is untouched:
-            // clearing the conversation is still `/reset` alone.
-            //
-            // DELIBERATELY WITHOUT `/todo clear`'s two guards: an `isRunning()` refusal
-            // would leave `/clear` unable to clear even the transcript mid-run, and an
-            // early return on an empty list would skip the dispatch below entirely.
-            // Clearing an empty store is already silent — it emits into a reducer
-            // branch that writes two fields that are both already at their defaults.
-            //
-            // Bounded side effect: the emptied store re-arms `todo_write`'s "a fresh
-            // plan has at least two items" gate, so a model that shrinks a plan to one
-            // item right after a mid-run `/clear` gets the refusal text and retries.
-            ctx.controller.clearTodos();
-            ctx.dispatch({ type: 'clearTranscript' });
-        },
+        description: 'Start a new conversation; "/clear screen" only clears the screen',
+        run: runClearCommand,
     },
     {
+        // ALIAS BY DESIGN (D-2), AND THIS IS THE WHOLE FIX. Until this change `/clear`
+        // cleared the screen while `/reset` cleared the session, so the command a
+        // user reaches for in a long conversation was the one that kept the history.
+        // One implementation makes that drift structurally impossible rather than
+        // merely fixed: there is no second body left to diverge.
         name: 'reset',
-        description: 'Start a new conversation',
-        run: (ctx) => {
-            if (ctx.controller.isRunning()) {
-                ctx.notify('warn', 'Cannot reset while the agent is running. Wait for it to stop.');
-                return;
-            }
-            ctx.controller.clearMessages();
-            ctx.controller.clearAllQueues();
-            ctx.dispatch({ type: 'resetConversation' });
-            ctx.toast('info', 'Started a new conversation.');
-            if (ctx.state.pendingSteering.length)
-                ctx.notify('warn', `\u5df2\u53d6\u6d88 ${ctx.state.pendingSteering.length} \u6761\u672a\u63a5\u6536\u6d88\u606f`);
-        },
+        description: 'Alias of /clear',
+        run: runClearCommand,
     },
     {
         name: 'cwd',

package/dist/commands/clear-command.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `/clear` - start a new conversation - plus its `/reset` alias and the
+ * `/clear screen` form that keeps the old "just wipe the screen" meaning
+ * (clear-command-context-reset §3.5 / D-1 / D-2 / D-3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. The one
+ * localized string below is written with `\u` escapes for that reason, exactly
+ * as the `/reset` body it replaces did.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/compact` and `/context` do (D-8). `builtins.ts` is 1511 lines against
+ * `CLAUDE.md`'s 1000-line cap, and this command is no longer a two-line
+ * projection reset - it interrupts a run, waits for it, archives a conversation
+ * and then clears. A two-line edit belongs inline; this does not.
+ *
+ * THE COMMAND'S ONLY JOB IS SEQUENCING AND SPEAKING. Every state change happens
+ * on the controller port (`AgentController.resetConversation`, which delegates
+ * the ORDER to `agent/conversation-reset.ts`), and every word the user reads is
+ * decided here, in one place, in the exact order they will read it.
+ */
+import type { CommandContext } from './registry.js';
+/**
+ * Run `/clear` or `/reset`. Both registry entries point HERE (D-2), which is
+ * what stops the two from drifting back into "one clears the screen, one clears
+ * the session" - the drift that produced the defect this feature fixes.
+ */
+export declare function runClearCommand(ctx: CommandContext): Promise<void>;