@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/ui/StatusBar.d.ts

@@ -88,6 +88,25 @@ interface StatusBarProps {
         done: number;
         total: number;
     };
+    /**
+     * Live background services (background-service-supervision §3.8), or absent
+     * when none are running — an ordinary session's bar is then unchanged.
+     *
+     * LEFT CLUSTER, after the todo chip, and it DEGRADES rather than hiding below
+     * `PROC_LIMITS.statusCompactCols`. That is the `todoActive` / `teamActive`
+     * ladder rather than `compactionActive`'s hide-below-threshold one, and the
+     * choice is deliberate: `compact` and `fast` describe something the CLI is
+     * doing to itself, whereas this is a PROCESS ON THE USER'S MACHINE HOLDING A
+     * PORT. A narrow terminal is a reason to shorten it, never a reason to stop
+     * saying it.
+     *
+     * `live` counts `starting | ready | running`. The transcript records events
+     * about a service (D-11); this is where "what is running right now" lives,
+     * alongside `/bg` and `bash_output`.
+     */
+    servicesActive?: {
+        live: number;
+    };
     /**
      * Live retry state (llm-api-retry-backoff §6.6), or absent when nothing is
      * retrying — an ordinary session's bar is then unchanged.
@@ -138,6 +157,46 @@ interface StatusBarProps {
     fastActive?: {
         inFlight: boolean;
     };
+    /**
+     * Live context compaction (context-auto-compaction §6.2), or absent when it is
+     * off for this session — in which case an ordinary session's bar is unchanged.
+     *
+     * RIGHT CLUSTER, next to `fast` and `eco`, and it DEGRADES below
+     * `COMPACTION_LIMITS.statusCompactCols`. The `teamActive` / `ecoRung` /
+     * `fastActive` treatment rather than the `agentMode` one, for the reason the
+     * note on `agentMode` gives: the mode must never be unreportable, whereas
+     * compaction has a fuller home in `/compact status` — the GUARANTEED reporting
+     * surface (§6.5) — and a chip on a 60-column terminal costs the context gauge
+     * more than it says.
+     *
+     * `inFlight` renders `compacting`, so a summarization that is taking a while is
+     * visible on this row without a spinner competing with the activity line's.
+     */
+    compactionActive?: {
+        inFlight: boolean;
+    };
+    /**
+     * Where the gauge turns amber and red (§6.2).
+     *
+     * ABSENT means today's hardcoded `{ warn: 60, high: 85 }`, so a session with
+     * compaction off renders a byte-identical bar. When present these are
+     * `warnThreshold * 100` and `threshold * 100`, which is what makes the colour
+     * the user sees agree with the number the trigger fires on.
+     */
+    gaugeMarks?: {
+        warn: number;
+        high: number;
+    };
+    /**
+     * Whether `contextTokens` is a DERIVED figure rather than a measured one.
+     *
+     * It WIDENS THE EXISTING `~`, it does not add a second marker. Today that
+     * prefix means "the window is a guess" (`contextWindowKnown`); with compaction
+     * it also has to mean "the occupancy is a guess", because the bar is written
+     * from an estimate for one turn after every compaction so it can fall
+     * immediately (§6.2 / AC-5).
+     */
+    contextEstimated?: boolean;
 }
 export declare function StatusBar(props: StatusBarProps): React.ReactElement;
 export {};

package/dist/ui/StatusBar.js

@@ -6,8 +6,10 @@ import { buildGauge } from './gauge.js';
 import { MODE_LABEL } from '../agent/agent-mode.js';
 import { formatRetryChip } from '../agent/retry-view.js';
 import { FAST_LIMITS } from '../fast/limits.js';
+import { COMPACTION_LIMITS } from '../compaction/limits.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 import { TODO_LIMITS } from '../todo/limits.js';
+import { PROC_LIMITS } from '../proc/limits.js';
 /** Below this the `eco` chip costs the context gauge more than it is worth. */
 const ECO_MIN_COLS = 72;
 /**
@@ -29,14 +31,22 @@ function redrawChar(nonce) {
     return nonce % 2 === 0 ? ' ' : NBSP;
 }
 export function StatusBar(props) {
-    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, agentMode = 'build', pendingAgentMode = null, teamActive, todoActive, retryActive, ecoRung = 0, fastActive, } = props;
+    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, agentMode = 'build', pendingAgentMode = null, teamActive, todoActive, servicesActive, retryActive, ecoRung = 0, fastActive, compactionActive, gaugeMarks, contextEstimated = false, } = props;
     const { stdout } = useStdout();
     const cols = stdout?.columns ?? 80;
     const running = status === 'running';
     const glyphs = pickGlyphs(caps);
     const pct = contextWindow > 0 ? Math.min(100, Math.round((contextTokens / contextWindow) * 100)) : 0;
-    const gauge = buildGauge(pct, cols < 72 ? 8 : 12, theme, caps);
-    const pctLabel = `${contextWindowKnown ? '' : '~'}${gauge.pct}%`;
+    // `gaugeMarks` is spread rather than passed as `undefined`, so a session with
+    // compaction off takes `buildGauge`'s own default and the bar is byte-identical
+    // to the pre-feature build.
+    const gauge = gaugeMarks
+        ? buildGauge(pct, cols < 72 ? 8 : 12, theme, caps, gaugeMarks)
+        : buildGauge(pct, cols < 72 ? 8 : 12, theme, caps);
+    // ONE `~` FOR TWO KINDS OF APPROXIMATION (§6.2). A second marker would be a
+    // second thing to explain for a distinction the user does not act on
+    // differently: either way the number is a guess.
+    const pctLabel = `${contextWindowKnown && !contextEstimated ? '' : '~'}${gauge.pct}%`;
     const tokens = `${formatTokens(usageTotal.inputTokens)}${glyphs.arrowUp} ${formatTokens(usageTotal.outputTokens)}${glyphs.arrowDown}`;
     const statusGlyph = running ? theme.symbols.toolRunning : theme.symbols.toolPending;
     // Nothing at all in build mode with nothing pending: the default posture is
@@ -57,5 +67,7 @@ export function StatusBar(props) {
                                 ? `agents ${teamActive.running}/${teamActive.total}`
                                 : `[${teamActive.running}]`] })), retryActive && (_jsxs(Text, { color: theme.noticeWarn, bold: true, children: ['  ', formatRetryChip(retryActive, cols)] })), todoActive && (_jsxs(Text, { color: theme.accent, children: ['  ', cols >= TODO_LIMITS.statusCompactCols
                                 ? `todo ${todoActive.done}/${todoActive.total}`
-                                : `[${todoActive.done}/${todoActive.total}]`] })), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [fastActive && cols >= FAST_LIMITS.statusCompactCols && (_jsxs(Text, { color: theme.muted, children: ["fast", fastActive.inFlight ? '*' : '', '  '] })), ecoRung > 0 && cols >= ECO_MIN_COLS && (_jsxs(Text, { color: theme.muted, children: ["eco", '  '] })), scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
+                                : `[${todoActive.done}/${todoActive.total}]`] })), servicesActive && (_jsxs(Text, { color: theme.accent, children: ['  ', cols >= PROC_LIMITS.statusCompactCols
+                                ? `svc ${servicesActive.live}`
+                                : `[${servicesActive.live}]`] })), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [compactionActive && cols >= COMPACTION_LIMITS.statusCompactCols && (_jsxs(Text, { color: compactionActive.inFlight ? theme.accent : theme.muted, children: [compactionActive.inFlight ? 'compacting' : 'compact', '  '] })), fastActive && cols >= FAST_LIMITS.statusCompactCols && (_jsxs(Text, { color: theme.muted, children: ["fast", fastActive.inFlight ? '*' : '', '  '] })), ecoRung > 0 && cols >= ECO_MIN_COLS && (_jsxs(Text, { color: theme.muted, children: ["eco", '  '] })), scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
 }

package/dist/ui/TeamPanel.js

@@ -88,7 +88,13 @@ export function activityLine(run, cols) {
                     ? 'waiting for mail'
                     : 'tool';
         case 'done':
-            return `done  ${run.turns} turns`;
+            // `compacted N` ON THE SETTLED ROW ONLY (hardening §3.4.4 / W3). A running
+            // row is already competing for `activityBudget(cols)` with the child's own
+            // prose, and a marker that displaces what the child is DOING right now
+            // buys nothing - the dispatch report carries the same fact for good.
+            return run.compactions
+                ? `done  ${run.turns} turns  compacted ${run.compactions}`
+                : `done  ${run.turns} turns`;
         case 'failed':
             return 'failed';
         case 'aborted':

package/dist/ui/Transcript.d.ts

@@ -31,6 +31,7 @@ import type { TermCapabilities } from './capabilities.js';
 import { type DensityMode } from './density.js';
 import type { Entry } from '../agent/reducer.js';
 import type { RenderMode } from './layout/frame.js';
+import { type TailSink } from './layout/follow-state.js';
 import type { HeightStore } from './use-height-store.js';
 /**
  * Largest prefix length P such that `entries[0..P)` are all terminal, none is
@@ -119,7 +120,7 @@ export declare const EntryView: React.MemoExoticComponent<typeof EntryViewImpl>;
  * `selectWindow`, and the two spacers are what keep the scroll maths honest
  * while they are absent.
  */
-export declare function TranscriptList({ entries, expandedToolIds, thinkingVisible, reducedMotion, density, mode, nowSec, theme, caps, windowSize, cols, heights, mountedSink, }: TranscriptProps & {
+export declare function TranscriptList({ entries, expandedToolIds, thinkingVisible, reducedMotion, density, mode, nowSec, theme, caps, windowSize, cols, heights, mountedSink, tailSink, }: TranscriptProps & {
     windowSize: number;
     /** The viewport's own width — narrower than the terminal when the rail is up. */
     cols: number;
@@ -132,6 +133,25 @@ export declare function TranscriptList({ entries, expandedToolIds, thinkingVisib
     mountedSink?: {
         current: number;
     };
+    /**
+     * Rows appended AT THE TAIL, published for `ScrollViewport`'s Rule A
+     * (tui-selection-and-scroll-follow §4.3.1a). THIS IS P0-1's FIX.
+     *
+     * It lives here because this is the only place that holds the per-entry height
+     * table, and therefore the only place that can tell "the agent produced output"
+     * apart from "an entry above changed height" or "the horizon dropped an entry
+     * off the front". Reacting to `measureElement(inner).height` instead conflates
+     * all three, breaks `virtual-window.ts`'s invariant V-4, and closes an
+     * offset → mounted-set → measured-height → offset loop.
+     *
+     * A REF WRITTEN DURING RENDER, exactly as `mountedSink` above is and for the
+     * same reason: a `setState` here would make observing the tail cost a render.
+     * If this sink ever needs more than that — a `setState`, or the geometry
+     * context — STOP AND RE-REVIEW: the loop above is open again, and the correct
+     * response is full entry anchoring (D-13's rejected alternative), not a larger
+     * sink.
+     */
+    tailSink?: TailSink;
 }): React.ReactElement;
 export declare function Transcript({ entries, expandedToolIds, thinkingVisible, reducedMotion, density, mode, nowSec, theme, caps, }: TranscriptProps): React.ReactElement;
 export {};

package/dist/ui/Transcript.js

@@ -39,9 +39,12 @@ import { TeamCard, teamCardColor } from './entries/TeamCard.js';
 import { TodoCard, todoCardColor } from './entries/TodoCard.js';
 import { RetryCard, retryCardColor } from './entries/RetryCard.js';
 import { FastCard, fastCardColor } from './entries/FastCard.js';
+import { CompactionCard, compactionCardColor } from './entries/CompactionCard.js';
+import { ServiceCard, serviceCardColor, serviceGlyph } from './entries/ServiceCard.js';
 import { MeasuredEntry } from './layout/MeasuredEntry.js';
 import { useViewportGeometry } from './layout/viewport-geometry.js';
 import { estimateEntryRows, heightKey, selectWindow, VIRTUAL_LIMITS, } from './layout/virtual-window.js';
+import { advanceTailRows } from './layout/follow-state.js';
 import { useTerminalSize } from './layout/useTerminalSize.js';
 /** Keep the last K entries in the live region so a mutating tail stays hot. */
 const LIVE_TAIL = 1;
@@ -99,6 +102,37 @@ export function computeSettledCount(entries, expandedToolIds) {
         // other half.
         if (e.kind === 'fast' && e.live)
             break;
+        // Nor is a compaction card whose call is still open: it is rewritten once,
+        // when the engine reports its verdict, and `<Static>` cannot un-print what it
+        // has already drawn (C-8). `session/persist.ts` forces `live: false` on load,
+        // which is the other half.
+        if (e.kind === 'compaction' && e.live)
+            break;
+        /**
+         * A SERVICE BLOCKS ONLY WHILE IT IS `starting` (D-11 / P0-4).
+         *
+         * Every clause above is bounded by an OPERATION — a dispatch, a turn, one
+         * LLM call, one countdown — which is why each of them can safely pin this
+         * prefix scan: the wait is short and it ends. A service is bounded by the
+         * USER'S INTENT. A dev server left up for an hour is the normal case, not
+         * the pathological one, so treating it like the other five would pin the
+         * boundary at the card and re-render the whole transcript from there on
+         * EVERY FRAME, FOREVER, on exactly the long sessions where it is least
+         * likely to be noticed.
+         *
+         * `starting` is different, and it is different for the reason that makes
+         * every other clause here legitimate: it is bounded by `readyTimeoutMs`,
+         * after which the supervisor calls the service `running` whatever happened.
+         *
+         * The cost of the rest is that a printed card stops mirroring live state —
+         * which is what a transcript IS. A terminal transition appends a NEW one-row
+         * entry rather than rewriting a card `<Static>` has already drawn, and live
+         * state lives in the status chip, `/bg` and `bash_output`. Weakening this to
+         * "any non-terminal service blocks" is the change D-11 exists to prevent;
+         * see condition 5 of the design's review verdict before making it.
+         */
+        if (e.kind === 'service' && e.status === 'starting')
+            break;
         count = i + 1;
     }
     return count;
@@ -111,7 +145,14 @@ export function computeSettledCount(entries, expandedToolIds) {
  * comparator, on every frame, forever.
  */
 function nowSecFor(entry, nowSec) {
-    return entry.kind === 'tool' && entry.status === 'running' ? nowSec : undefined;
+    if (entry.kind === 'tool' && entry.status === 'running')
+        return nowSec;
+    // THE LIVE COMPACTION CARD IS THE SECOND CONSUMER (hardening W5). It is at most
+    // ONE entry in the whole transcript, and it settles - so the memo boundary this
+    // function protects is unchanged for every other card, forever.
+    if (entry.kind === 'compaction' && entry.live)
+        return nowSec;
+    return undefined;
 }
 function noticeColor(level, theme) {
     if (level === 'error')
@@ -133,7 +174,7 @@ function EntryViewImpl({ entry, prev, expanded, thinkingVisible, reducedMotion,
     const frame = (glyph, color, children) => (_jsx(EntryFrame, { glyph: glyph, color: color, continuation: glyphs.railVertical, separation: separation, spacerColor: theme.border, children: children }));
     switch (entry.kind) {
         case 'user':
-            return frame(glyphs.user, theme.user, _jsx(UserEntry, { text: entry.text, theme: theme }));
+            return frame(glyphs.user, theme.user, _jsx(UserEntry, { text: entry.text, theme: theme, caps: caps }));
         case 'assistant': {
             // While text streams, the spinner IS the role marker. Braille dots are
             // both an animation and a Unicode-only glyph, so reduced motion and an
@@ -185,6 +226,16 @@ function EntryViewImpl({ entry, prev, expanded, thinkingVisible, reducedMotion,
                 reducedMotion: reducedMotion, theme: theme, caps: caps }));
         case 'fast':
             return frame(entry.status === 'failed' ? glyphs.toolError : glyphs.teamAgent, fastCardColor(entry.status, theme), _jsx(FastCard, { reviewIndex: entry.reviewIndex, model: entry.model, status: entry.status, text: entry.text, detail: entry.detail, turn: entry.turn, durationMs: entry.durationMs, live: entry.live, reducedMotion: reducedMotion, theme: theme, caps: caps }));
+        case 'compaction':
+            return frame(entry.applied || entry.live ? glyphs.compaction : glyphs.toolError, compactionCardColor(entry, theme), _jsx(CompactionCard, { index: entry.index, trigger: entry.trigger, mode: entry.mode, applied: entry.applied, reason: entry.reason, messagesBefore: entry.messagesBefore, messagesAfter: entry.messagesAfter, tokensBefore: entry.tokensBefore, tokensAfter: entry.tokensAfter, summary: entry.summary, model: entry.model, durationMs: entry.durationMs, tailRelief: entry.tailRelief, 
+                // ONLY WHILE LIVE, and only when the clock has ticked at least once:
+                // `nowSec` is `undefined` until then, and a settled card must keep
+                // rendering `durationMs` rather than a figure that would drift.
+                elapsedMs: entry.live && nowSec !== undefined && entry.startedAt !== undefined
+                    ? Math.max(0, nowSec * 1000 - entry.startedAt)
+                    : undefined, live: entry.live, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
+        case 'service':
+            return frame(serviceGlyph(entry, glyphs), serviceCardColor(entry, theme), _jsx(ServiceCard, { serviceId: entry.serviceId, command: entry.command, status: entry.status, url: entry.url, port: entry.port, exitCode: entry.exitCode, startedAt: entry.startedAt, readyAt: entry.readyAt, endedAt: entry.endedAt, rows: entry.rows, terminal: entry.terminal, killIncomplete: entry.killIncomplete, expanded: expanded, reducedMotion: reducedMotion, theme: theme, caps: caps }));
         case 'notice':
             return frame(noticeSymbol(entry.level, theme), noticeColor(entry.level, theme), _jsx(Text, { color: noticeColor(entry.level, theme), children: entry.text }));
         default:
@@ -248,7 +299,7 @@ export const EntryView = React.memo(EntryViewImpl, (a, b) => {
  * `selectWindow`, and the two spacers are what keep the scroll maths honest
  * while they are absent.
  */
-export function TranscriptList({ entries, expandedToolIds, thinkingVisible, reducedMotion, density, mode, nowSec, theme, caps, windowSize, cols, heights, mountedSink, }) {
+export function TranscriptList({ entries, expandedToolIds, thinkingVisible, reducedMotion, density, mode, nowSec, theme, caps, windowSize, cols, heights, mountedSink, tailSink, }) {
     const size = Math.max(1, Math.floor(windowSize));
     const visible = entries.length > size ? entries.slice(-size) : entries;
     const collapsed = entries.length - visible.length;
@@ -291,6 +342,13 @@ export function TranscriptList({ entries, expandedToolIds, thinkingVisible, redu
     const slice = visible.slice(selection.startIndex, selection.endIndex);
     if (mountedSink)
         mountedSink.current = slice.length;
+    // One more pass over the array `selectWindow` has already walked, reading the
+    // SAME height table and never the geometry context (§4.3.1a). `visible` is
+    // what is drawn, so its last entry is the tail; entries the horizon dropped are
+    // not "removed rows" and must not register as one.
+    if (tailSink) {
+        tailSink.current = advanceTailRows(tailSink.current, visible.map((entry) => entry.id), heightOf);
+    }
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [collapsed > 0 && (_jsxs(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: [glyphs.ellipsis, " ", collapsed, " earlier ", collapsed === 1 ? 'entry' : 'entries', " collapsed (/save exports the full session)"] })), selection.leadingRows > 0 && (_jsx(Box, { flexShrink: 0, height: selection.leadingRows })), slice.map((entry, i) => {
                 const index = selection.startIndex + i;
                 return (_jsx(MeasuredEntry, { heightKey: keyOf(entry), onMeasure: report, children: _jsx(EntryView, { entry: entry, prev: index > 0 ? visible[index - 1] : undefined, expanded: !!expandedToolIds[entry.id], thinkingVisible: thinkingVisible, reducedMotion: reducedMotion, density: density, mode: mode, nowSec: nowSecFor(entry, nowSec), theme: theme, caps: caps }) }, entry.id));

package/dist/ui/clipboard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Clipboard (tui-selection-and-scroll-follow §4.4.5) — the SINGLE clipboard path
+ * for the package. `/copy` and the selection release both come through here.
+ *
+ * Two mechanisms, both attempted, and the return value names the better one so
+ * the toast can say what was SENT rather than claiming a success neither one can
+ * confirm:
+ *
+ *  1. **OSC 52.** It reaches the clipboard of the machine the USER is sitting
+ *     at, which is the only correct target over SSH, and it is the only mechanism
+ *     that works with no helper binary installed. `/copy` gained SSH support the
+ *     moment it moved onto this module.
+ *  2. **The platform binary** (`clip` / `pbcopy` / `xclip`), moved here unchanged
+ *     from `commands/builtins.ts`, for the local case and for terminals that
+ *     ignore OSC 52 (tmux without `set -g set-clipboard on`, R-7).
+ *
+ * IT TAKES A WRITE *DOOR*, NOT A STREAM, and that is P1-6 rather than taste. In
+ * full-screen mode stdout is a `Proxy` in front of the frame differ; an
+ * unrecognised chunk there takes `passThrough(true)`, which increments
+ * `fallbacks` and — on the first one — raises `onFirstFallback`, wired to
+ * `console.warn(FRAME_FALLBACK_NOTICE)`. Sending OSC 52 through the proxy would
+ * therefore print a diagnostic at a user who did nothing wrong the first time
+ * they copied anything, and would permanently corrupt a counter documented to
+ * mean "something wrote to stdout behind Ink's back". The caller supplies
+ * `writeForeign` instead, and this module cannot pick the wrong door.
+ */
+export type CopyVia = 'osc52' | 'native' | 'none';
+/**
+ * Ceiling on an OSC 52 payload, in bytes of the ORIGINAL text.
+ *
+ * xterm's default limit is around 100 000 BASE64 characters and tmux / screen
+ * are stricter, so 56 000 source bytes (~74 700 base64) stays inside all three
+ * with room to spare. Past it the sequence is skipped rather than truncated: a
+ * terminal that drops an over-long OSC 52 leaves the clipboard holding whatever
+ * was there before, and half a selection is worse than none.
+ */
+export declare const MAX_OSC52_BYTES = 56000;
+/** `\x1b]52;c;<base64>\x07` — `c` is the CLIPBOARD selection, not PRIMARY. */
+export declare function osc52(text: string): string;
+/**
+ * Put `text` on the clipboard and report the best mechanism that was reached.
+ *
+ * `write` is the foreign-write door (see the module header). Omit it and OSC 52
+ * is skipped entirely, which is the correct behaviour for a caller that has no
+ * terminal to write to.
+ *
+ * NEITHER MECHANISM IS DETECTABLE. `spawn` returning without throwing does not
+ * mean `xclip` exists, and an OSC 52 sequence a terminal ignores is
+ * indistinguishable from one it honours. The return value therefore names what
+ * was ATTEMPTED, and every caller's user-facing text is worded accordingly.
+ */
+export declare function copyText(text: string, write?: (chunk: string) => void): CopyVia;

package/dist/ui/clipboard.js

@@ -0,0 +1,91 @@
+/**
+ * Clipboard (tui-selection-and-scroll-follow §4.4.5) — the SINGLE clipboard path
+ * for the package. `/copy` and the selection release both come through here.
+ *
+ * Two mechanisms, both attempted, and the return value names the better one so
+ * the toast can say what was SENT rather than claiming a success neither one can
+ * confirm:
+ *
+ *  1. **OSC 52.** It reaches the clipboard of the machine the USER is sitting
+ *     at, which is the only correct target over SSH, and it is the only mechanism
+ *     that works with no helper binary installed. `/copy` gained SSH support the
+ *     moment it moved onto this module.
+ *  2. **The platform binary** (`clip` / `pbcopy` / `xclip`), moved here unchanged
+ *     from `commands/builtins.ts`, for the local case and for terminals that
+ *     ignore OSC 52 (tmux without `set -g set-clipboard on`, R-7).
+ *
+ * IT TAKES A WRITE *DOOR*, NOT A STREAM, and that is P1-6 rather than taste. In
+ * full-screen mode stdout is a `Proxy` in front of the frame differ; an
+ * unrecognised chunk there takes `passThrough(true)`, which increments
+ * `fallbacks` and — on the first one — raises `onFirstFallback`, wired to
+ * `console.warn(FRAME_FALLBACK_NOTICE)`. Sending OSC 52 through the proxy would
+ * therefore print a diagnostic at a user who did nothing wrong the first time
+ * they copied anything, and would permanently corrupt a counter documented to
+ * mean "something wrote to stdout behind Ink's back". The caller supplies
+ * `writeForeign` instead, and this module cannot pick the wrong door.
+ */
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+/**
+ * Ceiling on an OSC 52 payload, in bytes of the ORIGINAL text.
+ *
+ * xterm's default limit is around 100 000 BASE64 characters and tmux / screen
+ * are stricter, so 56 000 source bytes (~74 700 base64) stays inside all three
+ * with room to spare. Past it the sequence is skipped rather than truncated: a
+ * terminal that drops an over-long OSC 52 leaves the clipboard holding whatever
+ * was there before, and half a selection is worse than none.
+ */
+export const MAX_OSC52_BYTES = 56_000;
+/** `\x1b]52;c;<base64>\x07` — `c` is the CLIPBOARD selection, not PRIMARY. */
+export function osc52(text) {
+    return `\x1b]52;c;${Buffer.from(text, 'utf-8').toString('base64')}\x07`;
+}
+/** Best-effort clipboard copy via the platform's clipboard CLI. */
+function copyNative(text) {
+    const cmd = process.platform === 'win32'
+        ? { file: 'clip', args: [] }
+        : process.platform === 'darwin'
+            ? { file: 'pbcopy', args: [] }
+            : { file: 'xclip', args: ['-selection', 'clipboard'] };
+    try {
+        const child = spawn(cmd.file, cmd.args, { stdio: ['pipe', 'ignore', 'ignore'] });
+        child.on('error', () => {
+            /* swallow — clipboard is best-effort, and a missing xclip is ordinary */
+        });
+        child.stdin?.end(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Put `text` on the clipboard and report the best mechanism that was reached.
+ *
+ * `write` is the foreign-write door (see the module header). Omit it and OSC 52
+ * is skipped entirely, which is the correct behaviour for a caller that has no
+ * terminal to write to.
+ *
+ * NEITHER MECHANISM IS DETECTABLE. `spawn` returning without throwing does not
+ * mean `xclip` exists, and an OSC 52 sequence a terminal ignores is
+ * indistinguishable from one it honours. The return value therefore names what
+ * was ATTEMPTED, and every caller's user-facing text is worded accordingly.
+ */
+export function copyText(text, write) {
+    if (text.length === 0)
+        return 'none';
+    let sentOsc52 = false;
+    if (write && Buffer.byteLength(text, 'utf-8') <= MAX_OSC52_BYTES) {
+        try {
+            write(osc52(text));
+            sentOsc52 = true;
+        }
+        catch {
+            // A closed or broken stdout must never turn a copy into a crash.
+        }
+    }
+    const sentNative = copyNative(text);
+    if (sentOsc52)
+        return 'osc52';
+    return sentNative ? 'native' : 'none';
+}

package/dist/ui/composer-limits.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Composer and transcript row ceilings (tui-paste-handling section 5.5 / 5.6).
+ *
+ * Structural, not policy (D-10): the only user-facing key this feature adds is
+ * the boolean `paste`. Everything here is a bound that keeps the frame's row
+ * arithmetic true, and every one of them is switchable by returning a larger
+ * number rather than by a config flag.
+ */
+/** At or below BOTH of these a paste is inserted verbatim rather than collapsed. */
+export declare const PASTE_INLINE_MAX_LINES = 6;
+export declare const PASTE_INLINE_MAX_CHARS = 400;
+/**
+ * Rows one submitted user message may RENDER in the transcript, before the
+ * `... +N more lines` tail (G7).
+ *
+ * `ui/layout/virtual-window.ts` imports this rather than duplicating the number,
+ * unlike `DIFF_COLLAPSED_LINES` / `TOOL_LIVE_TAIL_ROWS` beside it: I-13 makes the
+ * render cap and the height estimate THE SAME NUMBER, and there is no
+ * import-cycle reason here for them to be two.
+ */
+export declare const USER_ENTRY_MAX_ROWS = 40;
+/**
+ * Ceiling on the composer's DRAFT rows at a given terminal height.
+ *
+ * Non-decreasing in `terminalRows`. Returning `Infinity` reduces the whole
+ * height-bound layer to the rung below it (section 12, S4), which is what makes
+ * that stage revertible on its own.
+ */
+export declare function draftMaxRows(terminalRows: number): number;
+/** The terminal height at which `draftMaxRows` steps from 3 to 6. Pinned by test. */
+export declare const DRAFT_MAX_ROWS_HINT_TIER = 20;

package/dist/ui/composer-limits.js

@@ -0,0 +1,50 @@
+/**
+ * Composer and transcript row ceilings (tui-paste-handling section 5.5 / 5.6).
+ *
+ * Structural, not policy (D-10): the only user-facing key this feature adds is
+ * the boolean `paste`. Everything here is a bound that keeps the frame's row
+ * arithmetic true, and every one of them is switchable by returning a larger
+ * number rather than by a config flag.
+ */
+/** At or below BOTH of these a paste is inserted verbatim rather than collapsed. */
+export const PASTE_INLINE_MAX_LINES = 6;
+export const PASTE_INLINE_MAX_CHARS = 400;
+/**
+ * Rows one submitted user message may RENDER in the transcript, before the
+ * `... +N more lines` tail (G7).
+ *
+ * `ui/layout/virtual-window.ts` imports this rather than duplicating the number,
+ * unlike `DIFF_COLLAPSED_LINES` / `TOOL_LIVE_TAIL_ROWS` beside it: I-13 makes the
+ * render cap and the height estimate THE SAME NUMBER, and there is no
+ * import-cycle reason here for them to be two.
+ */
+export const USER_ENTRY_MAX_ROWS = 40;
+/**
+ * The terminal height at which the composer's hint row starts to fit.
+ *
+ * DELIBERATELY A SECOND COPY of `ui/layout/budget.ts::HINT_MIN_ROWS` rather than
+ * an import: `budget.ts` calls `draftMaxRows` to clamp its composer term, so an
+ * import in this direction would close an ESM cycle whose only protection is
+ * that neither side reads the other at module scope -- true today, and a
+ * confusing TDZ crash the first time someone hoists a use. `budget.test.ts`
+ * asserts the two numbers are equal, so they cannot drift in silence.
+ */
+const DRAFT_TIER_MIN_ROWS = 20;
+/**
+ * Ceiling on the composer's DRAFT rows at a given terminal height.
+ *
+ * Non-decreasing in `terminalRows`. Returning `Infinity` reduces the whole
+ * height-bound layer to the rung below it (section 12, S4), which is what makes
+ * that stage revertible on its own.
+ */
+export function draftMaxRows(terminalRows) {
+    if (!Number.isFinite(terminalRows))
+        return 3;
+    if (terminalRows >= 30)
+        return 10;
+    if (terminalRows >= DRAFT_TIER_MIN_ROWS)
+        return 6;
+    return 3;
+}
+/** The terminal height at which `draftMaxRows` steps from 3 to 6. Pinned by test. */
+export const DRAFT_MAX_ROWS_HINT_TIER = DRAFT_TIER_MIN_ROWS;

package/dist/ui/composer-rows.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Composer layout (tui-paste-handling section 5.5) -- pure. No Ink, no React.
+ *
+ * THE ONE PLACE THAT MAPS A BUFFER INDEX TO A SCREEN CELL (I-9). The composer
+ * used to hand its buffer to Ink one `<Text>` per logical line and let Yoga wrap
+ * it, which is fine until the draft is taller than the frame: `AppShell` gives
+ * the bottom chrome `flexShrink={0}`, so a tall composer does not grow the frame
+ * -- Yoga takes the rows out of the transcript and `overflow: hidden` clips them
+ * away, while `layout/budget.ts` keeps telling five consumers the composer is
+ * three rows tall. Four hundred presses of `Shift+Enter` do it without pasting
+ * anything.
+ *
+ * So the wrap happens HERE, the row count is a number this module returns, and
+ * `budget.ts` is told that number (I-8).
+ *
+ * HARD WRAP BY DISPLAY COLUMN, NEVER `layout/wrap-rows.ts::wrapToRows` (D-15).
+ * That function is a PROSE wrapper: it splits on `/\s+/` and rejoins with single
+ * spaces, so it destroys indentation and makes the character-index-to-screen-cell
+ * mapping the caret depends on impossible to state, let alone compute.
+ */
+export interface ComposerSegment {
+    readonly text: string;
+    readonly kind: 'text' | 'token';
+}
+export interface ComposerRow {
+    readonly segments: ComposerSegment[];
+}
+export interface ComposerLayout {
+    /** At most `maxRows`, and always containing the caret when `active`. */
+    readonly rows: ComposerRow[];
+    /** Index into `rows`, or -1 when the composer is not focused. */
+    readonly cursorRow: number;
+    /** Display column within that row. */
+    readonly cursorCol: number;
+    /** Rows the buffer occupies BEFORE the window was applied. */
+    readonly totalRows: number;
+    readonly hiddenAbove: number;
+    readonly hiddenBelow: number;
+}
+export interface ComposerLayoutInput {
+    readonly buffer: string;
+    readonly cursor: number;
+    readonly cols: number;
+    readonly maxRows: number;
+    readonly active: boolean;
+}
+/** Total display width of a run, using the same table the layout used. */
+export declare function displayWidth(text: string): number;
+/**
+ * Wrap `buffer` into rows, locate the caret, and select a window of at most
+ * `maxRows` rows that contains it.
+ *
+ * The window is pinned to the BOTTOM -- where the user is typing -- and pulled up
+ * only far enough to keep the caret visible. That is deterministic, which matters
+ * because this function holds no state between calls: a scroll offset would have
+ * to live in the reducer and would then need its own invalidation rules.
+ */
+export declare function layoutComposer(input: ComposerLayoutInput): ComposerLayout;
+export interface RowSplit {
+    readonly before: ComposerSegment[];
+    /** The one cell the caret sits on, or `null` when it sits past the last one. */
+    readonly at: ComposerSegment | null;
+    readonly after: ComposerSegment[];
+}
+/**
+ * Split one row at a display column so the renderer can draw an inverse caret on
+ * exactly one cell.
+ *
+ * Lives here rather than in the component because it walks the SAME width table
+ * `layoutComposer` walked (I-9): a second, subtly different measurement is how
+ * the caret ends up drawn on a cell that does not hold the character it is on.
+ */
+export declare function splitRowAtColumn(row: ComposerRow, column: number): RowSplit;