@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/fast/limits.d.ts

@@ -96,3 +96,57 @@ export declare const FAST_LIMITS: {
  * exactly what `TEAM_BLOCK_VERSION` and `TODO_BLOCK_VERSION` are for.
  */
 export declare const FAST_BLOCK_VERSION = "v2-2026-10";
+/**
+ * The bounds one task-summary label may consume
+ * (tui-shortcut-drawer-and-task-summary D-11).
+ *
+ * STRUCTURAL, NOT POLICY, for the reason this file's header records: these say
+ * what a one-line header label can PHYSICALLY carry, not what the user prefers.
+ * The two user switches (`taskSummary.enabled` / `.fallback`) live in
+ * `config/schema.ts` and are not interchangeable with these.
+ *
+ * THE THREE CAPS HAVE THREE DIFFERENT JOBS, and v1 left that implicit (P1-8):
+ *
+ *  - GENERATION (the system prompt in `summary-prompt.ts`): at most 6 words in
+ *    space-separated languages, at most 12 characters in CJK. The normal path is
+ *    constrained by this and by nothing else.
+ *  - NORMALISATION (`normalizeTaskSummary`): `summaryMaxWords` and
+ *    `cjkMaxGraphemes` are applied first, then `summaryMaxChars` catches the one
+ *    case those two cannot - a long run with no whitespace. That order is
+ *    asserted by `task-summary-normalize.test.ts`.
+ *  - RENDERING: `maxCells` is the hard ceiling on the header cell. The header
+ *    fits within whatever width is left; the drawer WRAPS instead of cutting.
+ */
+export declare const TASK_SUMMARY_LIMITS: {
+    /** Hard cap on the call's own output. A label is not a paragraph. */
+    readonly outputTokens: 64;
+    /**
+     * Wall-clock budget for ONE summary call, INCLUDING the fast registry's single
+     * retry. Short on purpose: the label is decoration on the header row, and a
+     * user waiting for the first token must never wait on it - the call is fired
+     * after `prompt()` has been started and nothing awaits it (AC-13).
+     */
+    readonly timeoutMs: 8000;
+    /** How much of the user's message is sent. Long prompts are summarised from the head. */
+    readonly anchorMaxChars: 2000;
+    /** Storage ceiling. Only ever reached by a model that ignored the prompt rules. */
+    readonly summaryMaxChars: 60;
+    /** Space-separated languages: the label is at most this many words. */
+    readonly summaryMaxWords: 8;
+    /** CJK: the label is at most this many grapheme clusters. */
+    readonly cjkMaxGraphemes: 12;
+    /**
+     * The header cell's hard ceiling in terminal COLUMNS (not characters).
+     *
+     * Shared by `ui/layout/header-left.ts` and the drawer so the two cannot
+     * disagree about how wide a label is allowed to be. v1 referenced this
+     * constant without defining it (P1-8).
+     */
+    readonly maxCells: 28;
+};
+/**
+ * Bumped whenever the task-summary system prompt's wording changes, so a
+ * behaviour report can be tied to a revision with one grep - the same purpose
+ * `FAST_BLOCK_VERSION` serves for the review prompt.
+ */
+export declare const TASK_SUMMARY_PROMPT_VERSION = "v1-2026-10";

package/dist/fast/limits.js

@@ -96,3 +96,57 @@ export const FAST_LIMITS = {
  * exactly what `TEAM_BLOCK_VERSION` and `TODO_BLOCK_VERSION` are for.
  */
 export const FAST_BLOCK_VERSION = 'v2-2026-10';
+/**
+ * The bounds one task-summary label may consume
+ * (tui-shortcut-drawer-and-task-summary D-11).
+ *
+ * STRUCTURAL, NOT POLICY, for the reason this file's header records: these say
+ * what a one-line header label can PHYSICALLY carry, not what the user prefers.
+ * The two user switches (`taskSummary.enabled` / `.fallback`) live in
+ * `config/schema.ts` and are not interchangeable with these.
+ *
+ * THE THREE CAPS HAVE THREE DIFFERENT JOBS, and v1 left that implicit (P1-8):
+ *
+ *  - GENERATION (the system prompt in `summary-prompt.ts`): at most 6 words in
+ *    space-separated languages, at most 12 characters in CJK. The normal path is
+ *    constrained by this and by nothing else.
+ *  - NORMALISATION (`normalizeTaskSummary`): `summaryMaxWords` and
+ *    `cjkMaxGraphemes` are applied first, then `summaryMaxChars` catches the one
+ *    case those two cannot - a long run with no whitespace. That order is
+ *    asserted by `task-summary-normalize.test.ts`.
+ *  - RENDERING: `maxCells` is the hard ceiling on the header cell. The header
+ *    fits within whatever width is left; the drawer WRAPS instead of cutting.
+ */
+export const TASK_SUMMARY_LIMITS = {
+    /** Hard cap on the call's own output. A label is not a paragraph. */
+    outputTokens: 64,
+    /**
+     * Wall-clock budget for ONE summary call, INCLUDING the fast registry's single
+     * retry. Short on purpose: the label is decoration on the header row, and a
+     * user waiting for the first token must never wait on it - the call is fired
+     * after `prompt()` has been started and nothing awaits it (AC-13).
+     */
+    timeoutMs: 8_000,
+    /** How much of the user's message is sent. Long prompts are summarised from the head. */
+    anchorMaxChars: 2_000,
+    /** Storage ceiling. Only ever reached by a model that ignored the prompt rules. */
+    summaryMaxChars: 60,
+    /** Space-separated languages: the label is at most this many words. */
+    summaryMaxWords: 8,
+    /** CJK: the label is at most this many grapheme clusters. */
+    cjkMaxGraphemes: 12,
+    /**
+     * The header cell's hard ceiling in terminal COLUMNS (not characters).
+     *
+     * Shared by `ui/layout/header-left.ts` and the drawer so the two cannot
+     * disagree about how wide a label is allowed to be. v1 referenced this
+     * constant without defining it (P1-8).
+     */
+    maxCells: 28,
+};
+/**
+ * Bumped whenever the task-summary system prompt's wording changes, so a
+ * behaviour report can be tied to a revision with one grep - the same purpose
+ * `FAST_BLOCK_VERSION` serves for the review prompt.
+ */
+export const TASK_SUMMARY_PROMPT_VERSION = 'v1-2026-10';

package/dist/fast/summary-call.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The bounded task-summary call (tui-shortcut-drawer-and-task-summary §6.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE OWNS ITS TIMER AND NOT ITS `AbortController`, which is the same
+ * prohibition `review-call.ts:7-29` states at length: a controller encapsulated
+ * with the call it aborts cannot be stamped by the lifecycle, so a cancellation
+ * and a timeout arrive as byte-identical bare errors. Here the consequence is
+ * cheaper (a label is decoration) but the rule is the same - the CALLER creates
+ * the controller, passes the signal, and aborts it once this function returns.
+ * `AgentController.summarizeTask` does exactly that, and it does so
+ * unconditionally, so a timed-out request never keeps a socket open.
+ *
+ * IT NEVER REJECTS. Every failure - four tier-off reasons, a missing key, a
+ * timeout, an abort, a provider error, an unusable reply - becomes a
+ * `TaskSummaryOutcome` carrying a `TaskSummaryReason`. A header label must not be
+ * able to produce an unhandled rejection in a TUI that has nowhere to show one.
+ */
+import type { AssistantMessage, LLMRequest } from '@aragon-agent/core';
+import type { ModelRole } from '../config/model-profiles.js';
+import type { CliConfig } from '../config/schema.js';
+import type { TaskSummaryOutcome } from './task-summary-types.js';
+/**
+ * Everything one call needs from its host, in the shape `AgentController`
+ * already uses for one-shot fast work (`createFastOverseerProvider`, F-16).
+ *
+ * THE KEY IS A GETTER, NOT A VALUE: `hasKey` / `getApiKey` read the live config
+ * and the environment, and a captured string would be the key from the moment
+ * the closure was built.
+ */
+export interface TaskSummaryCallDeps {
+    getConfig(): CliConfig;
+    hasKey(providerId: string, role?: ModelRole): boolean;
+    getApiKey(providerId: string, role?: ModelRole): string | undefined;
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    /** `config.taskSummary.fallback`, read at call time so `/config set` applies live. */
+    fallbackEnabled(): boolean;
+    /** The glyph this terminal renders for a cut label; supplied, never spelled here. */
+    ellipsis(): string;
+}
+export interface TaskSummaryCallParams {
+    /** The user's message (or the restored session's first user message). */
+    anchor: string;
+    /** Owned by the caller; aborted by the caller once this resolves. */
+    signal?: AbortSignal;
+    /** Epoch ms, injected so the timestamp is assertable. */
+    now: number;
+}
+/**
+ * Send one summary and bound it in time.
+ *
+ * WHY THE FALLBACK IS BUILT HERE AND NOT BY THE CALLER: every early return needs
+ * the same three arguments (anchor, reason, now) plus the user's `fallback`
+ * switch. Returning a bare reason and making the caller build the floor gives two
+ * places that can disagree about whether "no key" shows the user's own words.
+ */
+export declare function runTaskSummaryCall(deps: TaskSummaryCallDeps, params: TaskSummaryCallParams): Promise<TaskSummaryOutcome>;
+/**
+ * The deps `AgentController` builds from its live fast wiring (F-16 shape).
+ *
+ * `fallbackEnabled` and `ellipsis` have defaults because the controller always
+ * knows the config but does not always have a terminal capability set: the
+ * header passes the real glyph, a headless caller gets the ASCII one.
+ */
+export declare function createTaskSummaryDeps(input: {
+    getConfig(): CliConfig;
+    hasKey(providerId: string, role?: ModelRole): boolean;
+    getApiKey(providerId: string, role?: ModelRole): string | undefined;
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    ellipsis?: () => string;
+}): TaskSummaryCallDeps;

package/dist/fast/summary-call.js

@@ -0,0 +1,133 @@
+/**
+ * The bounded task-summary call (tui-shortcut-drawer-and-task-summary §6.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE OWNS ITS TIMER AND NOT ITS `AbortController`, which is the same
+ * prohibition `review-call.ts:7-29` states at length: a controller encapsulated
+ * with the call it aborts cannot be stamped by the lifecycle, so a cancellation
+ * and a timeout arrive as byte-identical bare errors. Here the consequence is
+ * cheaper (a label is decoration) but the rule is the same - the CALLER creates
+ * the controller, passes the signal, and aborts it once this function returns.
+ * `AgentController.summarizeTask` does exactly that, and it does so
+ * unconditionally, so a timed-out request never keeps a socket open.
+ *
+ * IT NEVER REJECTS. Every failure - four tier-off reasons, a missing key, a
+ * timeout, an abort, a provider error, an unusable reply - becomes a
+ * `TaskSummaryOutcome` carrying a `TaskSummaryReason`. A header label must not be
+ * able to produce an unhandled rejection in a TUI that has nowhere to show one.
+ */
+import { TASK_SUMMARY_LIMITS } from './limits.js';
+import { resolveFastTier } from './resolve.js';
+import { buildTaskSummaryRequest, fallbackView, interpretSummary, summaryBy, summaryText, } from './summary-prompt.js';
+/** The tier-off reasons spelled the way the rest of the fast layer spells them. */
+function tierReason(reason) {
+    if (reason === 'disabled')
+        return 'tier-off';
+    if (reason === 'no_model')
+        return 'no-model';
+    if (reason === 'no_adapter')
+        return 'no-adapter';
+    return 'no-key';
+}
+/**
+ * Send one summary and bound it in time.
+ *
+ * WHY THE FALLBACK IS BUILT HERE AND NOT BY THE CALLER: every early return needs
+ * the same three arguments (anchor, reason, now) plus the user's `fallback`
+ * switch. Returning a bare reason and making the caller build the floor gives two
+ * places that can disagree about whether "no key" shows the user's own words.
+ */
+export async function runTaskSummaryCall(deps, params) {
+    const fallback = (reason) => fallbackView({
+        anchor: params.anchor,
+        reason,
+        now: params.now,
+        fallbackEnabled: deps.fallbackEnabled(),
+        ellipsis: deps.ellipsis(),
+    });
+    // A prompt that is only whitespace has no label in it, and asking a model to
+    // summarise nothing burns a call to be told so.
+    if (params.anchor.trim().length === 0)
+        return fallback('empty');
+    if (params.signal?.aborted)
+        return fallback('aborted');
+    const config = deps.getConfig();
+    const tier = resolveFastTier(config, deps.hasKey);
+    // D-12: the MAIN model is never borrowed for this. A user without a fast tier
+    // has not bought the feature, and paying main-model latency for a header cell
+    // is the one trade this design refuses.
+    if (!tier.ok)
+        return fallback(tierReason(tier.reason));
+    const providerId = tier.ref.providerId;
+    const apiKey = deps.getApiKey(providerId, 'fast');
+    if (!apiKey)
+        return fallback('no-key');
+    const request = buildTaskSummaryRequest({
+        anchor: params.anchor,
+        providerId,
+        modelId: tier.ref.modelId,
+        apiKey,
+        ...(tier.ref.baseUrl ? { baseUrl: tier.ref.baseUrl } : {}),
+        ...(params.signal ? { signal: params.signal } : {}),
+        now: params.now,
+    });
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), TASK_SUMMARY_LIMITS.timeoutMs);
+        // NEVER KEEP THE PROCESS ALIVE FOR A HEADER LABEL: `unref` where the runtime
+        // offers it (Node does; the browser-shaped host this package is also built
+        // for does not) so a pending label cannot delay an exit.
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    });
+    try {
+        const raced = await Promise.race([
+            deps.complete(providerId, request),
+            timeout,
+        ]);
+        if (raced === 'timeout')
+            return fallback('timeout');
+        const raw = summaryText(raced);
+        if (raw.length === 0)
+            return fallback('bad-output');
+        return interpretSummary({
+            raw,
+            anchor: params.anchor,
+            by: summaryBy(providerId, tier.ref.modelId),
+            now: params.now,
+            fallbackEnabled: deps.fallbackEnabled(),
+            ellipsis: deps.ellipsis(),
+        });
+    }
+    catch {
+        // A cancellation is NOT a provider fault and must not be reported as one:
+        // the retry layer returns silently on abort, so both arrive as bare errors
+        // and the signal is the only witness that distinguishes them.
+        return fallback(params.signal?.aborted ? 'aborted' : 'error');
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * The deps `AgentController` builds from its live fast wiring (F-16 shape).
+ *
+ * `fallbackEnabled` and `ellipsis` have defaults because the controller always
+ * knows the config but does not always have a terminal capability set: the
+ * header passes the real glyph, a headless caller gets the ASCII one.
+ */
+export function createTaskSummaryDeps(input) {
+    return {
+        getConfig: input.getConfig,
+        hasKey: input.hasKey,
+        getApiKey: input.getApiKey,
+        complete: input.complete,
+        // `!== false`, so a hand-built config without the section behaves like the
+        // shipped default (floor on) rather than like a dead feature.
+        fallbackEnabled: () => input.getConfig().taskSummary?.fallback !== false,
+        ellipsis: input.ellipsis ?? (() => '...'),
+    };
+}

package/dist/fast/summary-prompt.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The task-summary prompt, its output normalisation, the language check and the
+ * deterministic floor (tui-shortcut-drawer-and-task-summary §4.4 / §6.2).
+ *
+ * ASCII ONLY: `src/fast/**` is inside the glyph scanner's scope. Every string in
+ * this file is English prose that goes to the model or into a code branch; the
+ * only non-ASCII the runtime ever sees arrives from the USER's message, which is
+ * data, not a literal.
+ *
+ * THE FLOOR NEVER LIES (D-9). Nine failure modes converge on one function,
+ * `localTaskSummary`, which returns a normalised prefix of the user's own words.
+ * That is the one outcome that cannot be wrong: the language matches by
+ * construction, nothing is invented, and the header cell is never empty. A model
+ * label that disagrees with the user's language is treated as a failure rather
+ * than displayed, because a Chinese task shown to a Chinese user as English is
+ * worse than their own sentence clipped.
+ */
+import type { AssistantMessage, LLMRequest } from '@aragon-agent/core';
+import type { TaskSummaryOutcome, TaskSummarySpan, TaskSummaryView } from './task-summary-types.js';
+/**
+ * The request one summary sends. No tools, no thinking, one bounded message.
+ *
+ * `modelLimits` is deliberately NOT set: the fast path uses the same output-cap
+ * authority as every other call (`resolveOutputTokens`), and hand-setting a
+ * second ceiling here is how the two would drift.
+ */
+export declare function buildTaskSummaryRequest(input: {
+    anchor: string;
+    providerId: string;
+    modelId: string;
+    apiKey: string;
+    baseUrl?: string;
+    signal?: AbortSignal;
+    now: number;
+}): LLMRequest;
+/**
+ * `cjk` | `latin` | `other`, by LETTER majority.
+ *
+ * DIGITS AND PUNCTUATION ARE NOT LETTERS (the spec's wording) - a message that is
+ * only `pwd`'s output would otherwise be classified by its spaces. `other` is a
+ * real answer, not a failure: it means "the language rule cannot be checked",
+ * and the caller treats it as "no opinion" instead of a mismatch.
+ */
+export declare function dominantScript(text: string): TaskSummarySpan;
+/**
+ * Clean one raw model reply into a displayable label.
+ *
+ * THE FIVE STEPS ARE SEPARATE AND IN THIS ORDER, so each is independently
+ * assertable (v2 P1-8):
+ *
+ *  1. strip ANSI escapes, then every remaining control character;
+ *  2. collapse every whitespace run (newlines included) to ONE space and trim;
+ *  3. strip a leading label prefix and any wrapping quotes / backticks / markers;
+ *  4. strip trailing punctuation, ASCII and CJK full-width;
+ *  5. cap by script - words to `summaryMaxWords` OR graphemes to
+ *     `cjkMaxGraphemes` - then hard-cap characters at `summaryMaxChars`.
+ *
+ * Returns `null` when nothing survives; the caller reports that as `bad-output`
+ * and falls back. A refusal ("I cannot help with that") normalises to a non-empty
+ * string, so the LANGUAGE check is what rejects it - which is why step 5 runs
+ * before step 6 in `interpretSummary` rather than here.
+ */
+export declare function normalizeTaskSummary(raw: string): string | null;
+/**
+ * The deterministic floor: a normalised verbatim prefix of the anchor.
+ *
+ * WHY IT IS SCRIPT-AWARE: a CJK sentence has no spaces, so a word-based clip
+ * would keep the first 8 characters and add an ellipsis - unreadable. CJK is
+ * clipped by graphemes instead, which is the same unit the prompt constrains.
+ *
+ * THE ELLIPSIS IS PASSED IN (`glyphs.ellipsis`) because this module may not
+ * spell a non-ASCII glyph (the scanner's rule); the caller supplies the one the
+ * terminal can actually render.
+ */
+export declare function localTaskSummary(anchor: string, span: TaskSummarySpan, ellipsis: string): string | null;
+/** Build the fallback view, or `null` when the user switched the floor off. */
+export declare function fallbackView(input: {
+    anchor: string;
+    reason: TaskSummaryView['reason'];
+    now: number;
+    fallbackEnabled: boolean;
+    ellipsis: string;
+}): TaskSummaryOutcome;
+/**
+ * Assemble the outcome from raw model text, applying D-9.
+ *
+ * ORDER MATTERS: normalise, then compare scripts, then decide. A model label in
+ * the wrong language is a FAILURE (`language-mismatch`), not something to
+ * display with a caveat - the fallback is the same length, in the right
+ * language, and true by construction.
+ *
+ * AND IT IS NOT RETRIED. A second call costs money and 1-3 seconds to reach an
+ * answer the fallback already gives correctly.
+ */
+export declare function interpretSummary(input: {
+    raw: string;
+    anchor: string;
+    by: string;
+    now: number;
+    fallbackEnabled: boolean;
+    ellipsis: string;
+}): TaskSummaryOutcome;
+/** The assistant text of a completion, or `''` for a tool-only answer. */
+export declare function summaryText(message: AssistantMessage | undefined): string;
+/** One model identity string, as the drawer's status line prints it. */
+export declare function summaryBy(providerId: string, modelId: string): string;