@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/agent/retry-view.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import type { Glyphs } from '../../ui/glyphs.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export declare const RETRY_UI: {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    readonly statusCompactCols: 100;
+};
+/** The five phases of the one card a turn gets. */
+export type RetryPhase = 'waiting' | 'retrying' | 'recovered' | 'exhausted' | 'interrupted';
+/** The shape `formatRetryLine` reads — the `kind: 'retry'` entry, structurally. */
+export interface RetryLineInput {
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    phase: RetryPhase;
+    resumeAt?: number;
+    totalRetries?: number;
+    elapsedMs?: number;
+}
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export declare function secondsLeft(resumeAt: number | undefined, now: number): number;
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export declare function retryHeadline(errorType: string): string;
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export declare function formatRetryLine(entry: RetryLineInput, glyphs: Glyphs, now: number): string;
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export declare function formatRetryChip(active: {
+    attempt: number;
+    max: number;
+    secondsLeft: number;
+}, cols: number): string;

package/dist/model/agent/retry-view.js

@@ -0,0 +1,95 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import { formatDuration } from './usage.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export const RETRY_UI = {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    statusCompactCols: 100,
+};
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export function secondsLeft(resumeAt, now) {
+    if (resumeAt === undefined)
+        return 0;
+    return Math.max(0, Math.ceil((resumeAt - now) / 1000));
+}
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export function retryHeadline(errorType) {
+    switch (errorType) {
+        case 'rate_limit':
+            return 'Rate limited by the provider';
+        case 'overloaded':
+            return 'Provider overloaded';
+        case 'server_error':
+            return 'Provider error';
+        case 'network_error':
+            return 'Network error reaching the provider';
+        case 'timeout':
+            return 'The request timed out';
+        default:
+            return 'Provider call failed';
+    }
+}
+function plural(n) {
+    return n === 1 ? 'retry' : 'retries';
+}
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export function formatRetryLine(entry, glyphs, now) {
+    const dot = ` ${glyphs.midDot} `;
+    const counter = `retry ${entry.attempt}/${entry.maxRetries}`;
+    const settled = entry.totalRetries ?? entry.attempt;
+    switch (entry.phase) {
+        case 'waiting':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} in ${secondsLeft(entry.resumeAt, now)}s`;
+        case 'retrying':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} ${glyphs.ellipsis}`;
+        case 'recovered':
+            return `recovered after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'exhausted':
+            return `${retryHeadline(entry.errorType)}${dot}gave up after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'interrupted':
+            return `interrupted after ${settled} ${plural(settled)}`;
+    }
+}
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export function formatRetryChip(active, cols) {
+    if (cols >= RETRY_UI.statusCompactCols) {
+        return `retry ${active.attempt}/${active.max} ${active.secondsLeft}s`;
+    }
+    return `[r${active.attempt}]`;
+}

package/dist/model/agent/usage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Token + cost accounting derived from `TokenUsage` and `ModelInfo.cost`
+ * (which is expressed in USD per 1M tokens). See spec §6.2 status bar.
+ */
+import type { ModelCost, TokenUsage } from '@aragon-agent/core';
+import type { UsageTotal } from './reducer.js';
+/** Compute the USD cost of a single `TokenUsage` given a model's cost table. */
+export declare function computeCost(usage: TokenUsage, cost?: ModelCost): number;
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export declare function addUsage(total: UsageTotal, usage: TokenUsage, costDelta: number): UsageTotal;
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export declare function promptTokensOf(total: UsageTotal): number;
+/** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
+export declare function formatCost(usd: number): string;
+/** Format a token count compactly (`1.2k`, `3.4M`). */
+export declare function formatTokens(n: number): string;
+/** Format a millisecond duration compactly (`820ms`, `3.4s`, `1m02s`). */
+export declare function formatDuration(ms: number): string;

package/dist/model/agent/usage.js

@@ -0,0 +1,84 @@
+/**
+ * Token + cost accounting derived from `TokenUsage` and `ModelInfo.cost`
+ * (which is expressed in USD per 1M tokens). See spec §6.2 status bar.
+ */
+/** Compute the USD cost of a single `TokenUsage` given a model's cost table. */
+export function computeCost(usage, cost) {
+    if (!cost)
+        return 0;
+    const perM = (tokens, rate) => rate ? (tokens / 1_000_000) * rate : 0;
+    return (perM(usage.inputTokens, cost.input) +
+        perM(usage.outputTokens, cost.output) +
+        perM(usage.cacheReadTokens ?? 0, cost.cacheRead) +
+        perM(usage.cacheWriteTokens ?? 0, cost.cacheWrite));
+}
+/**
+ * Fold one `TokenUsage` into a running session total
+ * (context-usage-gauge-accuracy §3.6 / W5).
+ *
+ * THE ONE ADDITION SITE, and collapsing four hand-written copies into it is the
+ * point rather than a tidy-up. The reducer had the same three lines in four
+ * branches - `turnEnd`, `teamUsage`, `fastUsage`, `compactionUsage` - and all
+ * four silently omitted the cache terms, so the status bar's `^` read LOWER than
+ * the `$` beside it on any session behind a caching gateway. A fifth source
+ * added later would have made the identical omission; now it cannot.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as the four branches already
+ * required: the summarizer and the fast tier may be different models with
+ * different price tables, and a reducer that priced its own would have to know
+ * about three of them.
+ */
+export function addUsage(total, usage, costDelta) {
+    return {
+        inputTokens: total.inputTokens + usage.inputTokens,
+        outputTokens: total.outputTokens + usage.outputTokens,
+        cacheReadTokens: total.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: total.cacheWriteTokens + (usage.cacheWriteTokens ?? 0),
+        costUsd: total.costUsd + costDelta,
+    };
+}
+/**
+ * The number the status bar's `^` shows: the PROMPT side of the session total.
+ *
+ * DELIBERATELY THE SAME TERMS AS `occupiedTokens` MINUS `outputTokens`
+ * (`compaction/pressure.ts`). Anthropic reports `input_tokens` EXCLUDING cached
+ * tokens and puts them in two separate fields, so `inputTokens` alone
+ * under-reports for anyone behind a caching gateway - while `computeCost` above
+ * has always priced all three. That is the "three units on one row" defect
+ * (P1-3): the percentage counted cache, the dollars counted cache, and the arrow
+ * did not.
+ *
+ * `$` IS STILL NOT THE SAME TOTAL, and the distinction is worth keeping straight
+ * (RV-14): `computeCost` also prices OUTPUT tokens. What this function asserts is
+ * narrower and exact - both cache terms are counted, on both sides.
+ */
+export function promptTokensOf(total) {
+    return total.inputTokens + total.cacheReadTokens + total.cacheWriteTokens;
+}
+/** Format a USD amount for the status bar (`$0.0000`, or `$1.23` when large). */
+export function formatCost(usd) {
+    if (usd <= 0)
+        return '$0.00';
+    if (usd < 1)
+        return `$${usd.toFixed(4)}`;
+    return `$${usd.toFixed(2)}`;
+}
+/** Format a token count compactly (`1.2k`, `3.4M`). */
+export function formatTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+/** Format a millisecond duration compactly (`820ms`, `3.4s`, `1m02s`). */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const s = ms / 1000;
+    if (s < 60)
+        return `${s.toFixed(1)}s`;
+    const m = Math.floor(s / 60);
+    const rem = Math.floor(s % 60);
+    return `${m}m${String(rem).padStart(2, '0')}s`;
+}

package/dist/model/compaction/limits.d.ts

@@ -0,0 +1,61 @@
+/** Structural limits for v2 compaction. All character counts are UTF-16 units. */
+export declare const COMPACTION_LIMITS: {
+    readonly digestMaxChars: 120000;
+    /**
+     * The smallest digest worth sending when the budget collapses (never-fires A1).
+     *
+     * `digestBudgetChars(7000)` is 0 - a summarizer whose window is smaller than the
+     * reserve has no input room - and before this change a 0 budget simply threw.
+     * Eliding is only safe while SOMETHING survives: a digest with no messages and no
+     * source map forces the model to invent a delta (`invalid_memory_delta`) or to
+     * return none, so the floor is spent on the first entry, the last entry and the
+     * elision marker.
+     */
+    readonly digestMinChars: 2000;
+    /**
+     * The tail budget the SECOND planning pass may fall back to (never-fires B).
+     *
+     * A MEANINGFUL TAIL, NOT A TOKEN-LEVEL FLOOR. `planCompaction` walks down from
+     * the LARGEST safe cut, so the cut it relaxes to leaves exactly this many
+     * messages behind; too small a number would satisfy the planner while breaking
+     * the thing the user asked for (the recent instructions stay verbatim). Tens of
+     * messages is one or two agentic turns' worth of tool calls.
+     */
+    readonly minRetainedMessages: 40;
+    readonly summarizerReserveTokens: 8000;
+    readonly summaryMaxChars: 32000;
+    readonly summaryOutputTokens: 4096;
+    readonly memoryJsonChars: 32000;
+    readonly memoryEnvelopeChars: 1024;
+    readonly protectedMemoryChars: 48000;
+    readonly memoryItems: 200;
+    readonly protectedUserMessages: 200;
+    readonly memoryAdditions: 64;
+    readonly coverageClips: 200;
+    readonly jsonDepth: 32;
+    readonly instructionsChars: 4000;
+    readonly itemTextChars: 1200;
+    readonly sourceExcerptChars: 512;
+    readonly itemSources: 8;
+    readonly toolResultEdgeChars: 1500;
+    readonly operationTimeoutMs: 120000;
+    readonly callTimeoutMs: 45000;
+    readonly minTurnsBetween: 2;
+    readonly maxPerRun: 5;
+    readonly minReclaimRatio: 0.15;
+    readonly stuckLimit: 2;
+    readonly tailToolResultChars: 2000;
+    readonly blockAllowanceTokens: 2000;
+    readonly archiveMaxFiles: 20;
+    readonly archiveMaxAgeMs: 604800000;
+    readonly archiveMaxBytes: 8000000;
+    readonly cardTextRows: 6;
+    readonly statusCompactCols: 100;
+};
+export declare const COMPACTION_BLOCK_VERSION = "v2-2026-10";
+export declare const ANCHOR_TAG_OPEN = "<original_task>";
+export declare const ANCHOR_TAG_CLOSE = "</original_task>";
+export declare const BLOCK_TAG_OPEN = "<compacted_context";
+export declare const BLOCK_TAG_CLOSE = "</compacted_context>";
+/** Retained legacy helper for explicit callers; v2 compression never clips the tail. */
+export declare function tailClipMarker(removed: number): string;

package/dist/model/compaction/limits.js

@@ -0,0 +1,64 @@
+/** Structural limits for v2 compaction. All character counts are UTF-16 units. */
+export const COMPACTION_LIMITS = {
+    digestMaxChars: 120_000,
+    /**
+     * The smallest digest worth sending when the budget collapses (never-fires A1).
+     *
+     * `digestBudgetChars(7000)` is 0 - a summarizer whose window is smaller than the
+     * reserve has no input room - and before this change a 0 budget simply threw.
+     * Eliding is only safe while SOMETHING survives: a digest with no messages and no
+     * source map forces the model to invent a delta (`invalid_memory_delta`) or to
+     * return none, so the floor is spent on the first entry, the last entry and the
+     * elision marker.
+     */
+    digestMinChars: 2_000,
+    /**
+     * The tail budget the SECOND planning pass may fall back to (never-fires B).
+     *
+     * A MEANINGFUL TAIL, NOT A TOKEN-LEVEL FLOOR. `planCompaction` walks down from
+     * the LARGEST safe cut, so the cut it relaxes to leaves exactly this many
+     * messages behind; too small a number would satisfy the planner while breaking
+     * the thing the user asked for (the recent instructions stay verbatim). Tens of
+     * messages is one or two agentic turns' worth of tool calls.
+     */
+    minRetainedMessages: 40,
+    summarizerReserveTokens: 8_000,
+    summaryMaxChars: 32_000,
+    summaryOutputTokens: 4_096,
+    memoryJsonChars: 32_000,
+    memoryEnvelopeChars: 1_024,
+    protectedMemoryChars: 48_000,
+    memoryItems: 200,
+    protectedUserMessages: 200,
+    memoryAdditions: 64,
+    coverageClips: 200,
+    jsonDepth: 32,
+    instructionsChars: 4_000,
+    itemTextChars: 1_200,
+    sourceExcerptChars: 512,
+    itemSources: 8,
+    toolResultEdgeChars: 1_500,
+    operationTimeoutMs: 120_000,
+    callTimeoutMs: 45_000,
+    minTurnsBetween: 2,
+    maxPerRun: 5,
+    minReclaimRatio: 0.15,
+    stuckLimit: 2,
+    // Legacy capacity helpers remain callable, but v2 never mutates retained tails.
+    tailToolResultChars: 2_000,
+    blockAllowanceTokens: 2_000,
+    archiveMaxFiles: 20,
+    archiveMaxAgeMs: 604_800_000,
+    archiveMaxBytes: 8_000_000,
+    cardTextRows: 6,
+    statusCompactCols: 100,
+};
+export const COMPACTION_BLOCK_VERSION = 'v2-2026-10';
+export const ANCHOR_TAG_OPEN = '<original_task>';
+export const ANCHOR_TAG_CLOSE = '</original_task>';
+export const BLOCK_TAG_OPEN = '<compacted_context';
+export const BLOCK_TAG_CLOSE = '</compacted_context>';
+/** Retained legacy helper for explicit callers; v2 compression never clips the tail. */
+export function tailClipMarker(removed) {
+    return `\n[... ${removed} characters removed by context compaction ...]`;
+}