@aragon-agent/cli 0.6.29 → 0.6.31

package/dist/commands/perf.d.ts

@@ -34,7 +34,8 @@ export interface PerfSnapshot {
     heightsEstimated: number;
     cols: number;
     /** Geometry. */
-    mode: 'fullscreen';
+    mode: 'fullscreen' | 'native';
+    /** Full-screen: the transcript viewport. Native: the live region height. */
     viewportRows: number;
     offset: number;
     /** Right-edge scrollbar diagnostics; read lazily so it reflects the live bridge. */
@@ -74,6 +75,29 @@ export declare function setPerfResetHook(fn: (() => void) | null): void;
 /** Called by `cli.tsx` after building the writer. Passing `null` detaches. */
 export declare function setFrameStatsProvider(fn: (() => FrameWriterStats) | null): void;
 export declare function readFrameStats(): FrameWriterStats | null;
+/**
+ * Native-scroll writer counters (tui-native-terminal-scroll §5.1). A third
+ * module-level slot for the reason the one above records: the writer lives outside
+ * React. `guardHitsOutsideResize > 0` on a session with no resize is the defect
+ * signal (a live region reached the terminal height); `clippedRows > 0` means Ink
+ * and the terminal disagreed about a character's width (I-S13).
+ */
+export interface ScrollbackPerf {
+    regionRows: number;
+    framesSeed: number;
+    framesDiff: number;
+    framesFull: number;
+    staticRowsWritten: number;
+    elidedEntries: number;
+    guardHits: number;
+    guardHitsOutsideResize: number;
+    clippedRows: number;
+    fallbacks: number;
+    resizes: number;
+    repaints: number;
+}
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export declare function setScrollbackStatsProvider(fn: (() => ScrollbackPerf) | null): void;
 /** Format a snapshot as the six-line block documented in §5.4 (plus the scrollbar line). */
 export declare function formatPerfReport(snap: PerfSnapshot): string;
 export declare const perfCommand: SlashCommand;

package/dist/commands/perf.js

@@ -68,6 +68,24 @@ export function setFrameStatsProvider(fn) {
 export function readFrameStats() {
     return frameStats ? frameStats() : null;
 }
+let scrollbackStats = null;
+/** Called by `cli.tsx` in native mode. Passing `null` detaches. */
+export function setScrollbackStatsProvider(fn) {
+    scrollbackStats = fn;
+}
+function formatScrollbackLine() {
+    const stats = scrollbackStats?.();
+    if (!stats)
+        return [];
+    return [
+        `scrollback region ${stats.regionRows} rows  -  batches seed ${stats.framesSeed}, ` +
+            `diff ${stats.framesDiff}, full ${stats.framesFull}, repaint ${stats.repaints}  -  ` +
+            `static rows ${stats.staticRowsWritten}  -  elided ${stats.elidedEntries}`,
+        `           guardHits ${stats.guardHits} (outside resize ${stats.guardHitsOutsideResize})  -  ` +
+            `clippedRows ${stats.clippedRows}  -  fallbacks ${stats.fallbacks}  -  ` +
+            `resizes ${stats.resizes}`,
+    ];
+}
 function mb(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
@@ -107,7 +125,10 @@ export function formatPerfReport(snap) {
     const caches = renderCacheStats();
     const eco = snap.rung > 0 ? '  -  eco' : '';
     const governor = snap.governorEnabled ? '' : '  -  governor off';
-    const scrollbar = snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
+    const native = snap.mode === 'native';
+    const scrollbar = native
+        ? ['scrollbar  n/a (native scroll)']
+        : snap.scrollbar ? [formatScrollbarLine(snap.scrollbar)] : [];
     return [
         `render     rung ${snap.rung}  -  interval ${snap.intervalMs}ms  -  last commit ` +
             `${Math.round(snap.lastCommitMs)}ms${eco}${governor}`,
@@ -118,8 +139,11 @@ export function formatPerfReport(snap) {
         `caches     md ${caches.markdownEntries} (${mb(caches.markdownBytes)})  -  ` +
             `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
             `lines ${caches.lineEntries}`,
-        `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        native
+            ? `mode       native  -  live region ${snap.viewportRows} rows`
+            : `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
         formatWriterLine(),
+        ...formatScrollbackLine(),
         ...scrollbar,
     ].join('\n');
 }

package/dist/commands/registry.d.ts

@@ -100,6 +100,12 @@ export interface CommandContext {
      * missing, which is the same reason `update` above it is optional.
      */
     mouse?: MouseCommandPort;
+    /**
+     * True in native-scroll mode (tui-native-terminal-scroll): the terminal owns
+     * scrolling and selection, so there is no capture to toggle. Lets `/mouse` say so
+     * instead of the generic "not captured" answer.
+     */
+    nativeScroll?: boolean;
     /**
      * The foreign-write door, for `/copy`'s OSC 52 half (§4.4.5).
      *

package/dist/config/env.js

@@ -392,6 +392,10 @@ export function readEnvConfig() {
         partial.diffRender =
             diffRender === '1' || diffRender === 'true' || diffRender === 'on' || diffRender === 'yes';
     }
+    // Invalid values are ignored, like every other ARAGON_* key.
+    const scrollMode = process.env.ARAGON_SCROLL_MODE?.trim().toLowerCase();
+    if (scrollMode === 'native' || scrollMode === 'app')
+        partial.scrollMode = scrollMode;
     const syncOutput = process.env.ARAGON_SYNC_OUTPUT?.trim().toLowerCase();
     if (syncOutput !== undefined && syncOutput.length > 0) {
         partial.syncOutput =

package/dist/config/load.d.ts

@@ -5,7 +5,7 @@
  * layers, `idleTimeout` is re-derived to be strictly ≥ `toolTimeout` so a
  * legitimately long single tool run can never be watchdog-killed.
  */
-import { type CliConfig } from './schema.js';
+import { type CliConfig, type ScrollMode } from './schema.js';
 import type { ModelRole } from './model-profiles.js';
 export interface CliFlags {
     provider?: string;
@@ -149,6 +149,8 @@ export interface CliFlags {
      * all — i.e. the documented escape hatch would quietly un-set itself.
      */
     diffRender?: boolean;
+    /** `--scroll-mode <native|app>`; already validated by `cli.tsx` (exit 2 on junk). */
+    scrollMode?: ScrollMode;
     /** `--sync-output` ⇒ true, `--no-sync-output` ⇒ false, absent ⇒ undefined (§5.2). */
     syncOutput?: boolean;
     /**

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
+import { DEFAULT_CONFIG, DEFAULT_SCROLL_MODE, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampCompactionConfig, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampBashConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampContextWindow, clampMaxTokens, clampMaxRenderInterval, clampScrollMode, clampScrollResumeMs, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, legacyTeamCeilingPatch, parseThresholdInput, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile, updatePersistedConfig } from './store.js';
 import { projectModelProfiles, resolveModelProfileState, resolveModelRoleKey, } from './model-profile-resolution.js';
@@ -334,6 +334,16 @@ function resolveDiffRender(flags, env, file) {
         return file.diffRender;
     return DEFAULT_CONFIG.diffRender;
 }
+/** flags > env > file > default, like `resolveDiffRender` (tui-native-terminal-scroll §6.1). */
+function resolveScrollMode(flags, env, file) {
+    if (flags.scrollMode !== undefined)
+        return flags.scrollMode;
+    if (env.scrollMode !== undefined)
+        return env.scrollMode;
+    if (file.scrollMode !== undefined)
+        return clampScrollMode(file.scrollMode, DEFAULT_SCROLL_MODE);
+    return DEFAULT_SCROLL_MODE;
+}
 /** Same ladder for the DEC 2026 envelope (§5.1). */
 function resolveSyncOutput(flags, env, file) {
     if (flags.syncOutput !== undefined)
@@ -638,6 +648,7 @@ export function loadConfig(flags = {}, options = {}) {
         renderGovernor: resolveRenderGovernor(flags, env.partial, file),
         maxRenderIntervalMs: clampMaxRenderInterval(pick(flags.maxRenderInterval, env.partial.maxRenderIntervalMs, file.maxRenderIntervalMs), DEFAULT_CONFIG.maxRenderIntervalMs),
         diffRender: resolveDiffRender(flags, env.partial, file),
+        scrollMode: resolveScrollMode(flags, env.partial, file),
         syncOutput: resolveSyncOutput(flags, env.partial, file),
         confirmTools,
         toolTimeoutMs,

package/dist/config/schema.d.ts

@@ -39,6 +39,17 @@ export declare function isThemeName(v: unknown): v is ThemeName;
  * and would not match `clampThinkingLevel` / `clampTranscriptWindow`.
  */
 export declare function clampTheme(v: unknown, fallback: ThemeName): ThemeName;
+export declare const SCROLL_MODES: readonly ["native", "app"];
+/**
+ * How the interactive TUI scrolls (tui-native-terminal-scroll D1).
+ *
+ * `native` prints settled conversation into the host terminal's own scrollback and
+ * keeps only a bounded live region on screen; `app` is the original full-screen
+ * alternate-screen layout with application-owned scrolling.
+ */
+export type ScrollMode = (typeof SCROLL_MODES)[number];
+export declare const DEFAULT_SCROLL_MODE: ScrollMode;
+export declare function clampScrollMode(v: unknown, fallback: ScrollMode): ScrollMode;
 export declare const DENSITY_MODES: readonly ["comfortable", "compact"];
 export type DensityMode = (typeof DENSITY_MODES)[number];
 export declare function clampDensity(v: unknown, fallback: DensityMode): DensityMode;
@@ -864,6 +875,8 @@ export interface PersistedConfig {
     maxRenderIntervalMs: number;
     /** Repaint only the frame rows that changed (tui-input-flicker-fix §5.1). */
     diffRender: boolean;
+    /** Native terminal scrolling vs the full-screen app layout (tui-native-terminal-scroll D1). */
+    scrollMode: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;
@@ -1068,6 +1081,20 @@ export interface CliConfig {
      * with no compile error and no runtime error.
      */
     diffRender: boolean;
+    /**
+     * Native terminal scrolling vs the full-screen app layout
+     * (tui-native-terminal-scroll D1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `diffRender` above records: `runInteractive` reads `config.scrollMode`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set` and never reach the screen plan.
+     *
+     * OPTIONAL ON THIS SHAPE ONLY so the many hand-built `CliConfig` fixtures in the
+     * test suite stay valid without edits (I-S9); `loadConfig` always sets it and
+     * the one reader (`runInteractive`) falls back to `DEFAULT_SCROLL_MODE`.
+     */
+    scrollMode?: ScrollMode;
     /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
     syncOutput: boolean;
     confirmTools: boolean;

package/dist/config/schema.js

@@ -69,6 +69,14 @@ export function clampTheme(v, fallback) {
 // ---------------------------------------------------------------------------
 // Density / hints (v0.4.0)
 // ---------------------------------------------------------------------------
+export const SCROLL_MODES = ['native', 'app'];
+export const DEFAULT_SCROLL_MODE = 'native';
+export function clampScrollMode(v, fallback) {
+    if (typeof v !== 'string')
+        return fallback;
+    const normalized = v.trim().toLowerCase();
+    return normalized === 'native' || normalized === 'app' ? normalized : fallback;
+}
 export const DENSITY_MODES = ['comfortable', 'compact'];
 export function clampDensity(v, fallback) {
     return v === 'comfortable' || v === 'compact' ? v : fallback;
@@ -970,6 +978,7 @@ export const DEFAULT_CONFIG = {
     renderGovernor: DEFAULT_RENDER_GOVERNOR,
     maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
     diffRender: DEFAULT_DIFF_RENDER,
+    scrollMode: DEFAULT_SCROLL_MODE,
     syncOutput: DEFAULT_SYNC_OUTPUT,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,

package/dist/config/ui-state.d.ts

@@ -84,6 +84,12 @@ export interface UiState {
      * older file, which is the behaviour wanted here anyway.
      */
     vtInputNoticeVersion: number;
+    /**
+     * Which revision of the "scrolling now uses your terminal" notice this user has
+     * been shown (`0` = none; tui-native-terminal-scroll D12). A scalar beside the
+     * others for the same reasons the two above record, and NOT a schema bump.
+     */
+    scrollModeNoticeVersion: number;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -98,6 +104,9 @@ export declare function setMouseNoticeVersion(version: number): void;
 /** `0` on a file written before the field existed — see the field's comment. */
 export declare function getVtInputNoticeVersion(): number;
 export declare function setVtInputNoticeVersion(version: number): void;
+/** `0` on a file written before the field existed. */
+export declare function getScrollModeNoticeVersion(): number;
+export declare function setScrollModeNoticeVersion(version: number): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -37,6 +37,7 @@ const DEFAULT_UI_STATE = {
     mouseNoticeSeen: false,
     mouseNoticeVersion: 0,
     vtInputNoticeVersion: 0,
+    scrollModeNoticeVersion: 0,
 };
 let memory = null;
 /** Non-negative integer or `fallback`; shared by both numeric fields. */
@@ -69,6 +70,7 @@ function readFromDisk() {
                 : DEFAULT_UI_STATE.mouseNoticeSeen,
             mouseNoticeVersion: coerceCount(parsed.mouseNoticeVersion, DEFAULT_UI_STATE.mouseNoticeVersion),
             vtInputNoticeVersion: coerceCount(parsed.vtInputNoticeVersion, DEFAULT_UI_STATE.vtInputNoticeVersion),
+            scrollModeNoticeVersion: coerceCount(parsed.scrollModeNoticeVersion, DEFAULT_UI_STATE.scrollModeNoticeVersion),
         };
     }
     catch {
@@ -142,6 +144,13 @@ export function getVtInputNoticeVersion() {
 export function setVtInputNoticeVersion(version) {
     update({ vtInputNoticeVersion: version });
 }
+/** `0` on a file written before the field existed. */
+export function getScrollModeNoticeVersion() {
+    return loadUiState().scrollModeNoticeVersion;
+}
+export function setScrollModeNoticeVersion(version) {
+    update({ scrollModeNoticeVersion: version });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/ui/App.d.ts

@@ -10,6 +10,8 @@ import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
 import { type Entry, type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
+import { type ScrollbackBridge } from './scrollback/use-scrollback-view.js';
+import type { ScrollMode } from '../config/schema.js';
 import type { MouseSource } from '../input/stdin-filter.js';
 import { type PasteBridge } from '../input/limits.js';
 import type { CheckpointResult } from '../session/checkpoint.js';
@@ -86,6 +88,14 @@ export interface AppProps {
      */
     pasteBridge?: PasteBridge;
     terminal?: TerminalBridge;
+    /**
+     * `'native'` prints settled conversation into the terminal's own scrollback and
+     * renders only a bounded live region (tui-native-terminal-scroll). DEFAULTS TO
+     * `'app'` so every existing render test and call site is untouched (I-S9).
+     */
+    scrollMode?: ScrollMode;
+    /** The writer / feed channel `cli.tsx` shares with the tree; required for `'native'`. */
+    scrollback?: ScrollbackBridge;
     /**
      * The transcript to seed the first frame with, from a resumed session
      * (tui-session-id-resume 3.12).
@@ -148,4 +158,4 @@ export interface TerminalBridge {
     writeForeign?: (text: string) => void;
     selection?: SelectionBridge;
 }
-export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, initialEntries, session, sessionBridge, sessionNotice, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, scrollMode, scrollback, initialEntries, session, sessionBridge, sessionNotice, }: AppProps): React.ReactElement;