@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/tools/tool-gate.js

@@ -0,0 +1,87 @@
+/**
+ * The per-call approval gate: one wrapper, one shared denial text, no I/O.
+ *
+ * ASCII ONLY - `src/tools/**` is inside the glyph scanner's scope.
+ *
+ * WHY A WRAPPER AND NOT A CORE HOOK (headless-host-bridge section 2.3.3). A
+ * `beforeExecute` callback on Core's `ToolExecutor` would put a human wait in
+ * front of the plan gate's refusal, freeze a new field into the public API that
+ * `public-api.test.ts` guards, and teach the engine about a host shape it has no
+ * business knowing. The `{...tool, execute}` shape below is the one already used
+ * three times in `tools/index.ts` (confirmation, skill ceiling, plan gate), so
+ * nothing in the engine has to learn that an approval exists.
+ *
+ * WHERE IT SITS IN THE STACK IS PART OF THE DESIGN, not an accident of import
+ * order: `tools/index.ts` applies it AFTER every append (so `skill_create` is
+ * reachable) and BEFORE the `toolPolicy` / plan-gate wrappers are added, so at
+ * call time those two refusals - which need no I/O - happen first and a tool that
+ * policy would refuse never interrupts a human.
+ */
+import { errorResult } from '@aragon-agent/core';
+/**
+ * THE ONE PLACE A DENIAL IS WORDED. Shared by the wrapper below and by the tests,
+ * so "the model is told what happened and what to do instead" is a single string
+ * rather than a paragraph repeated in two modules.
+ *
+ * The last sentence is not politeness. A bare "denied" makes a model retry the
+ * same call; the observed failure mode is a paid loop that burns a budget on one
+ * forbidden command. Naming the tool and the reason is what lets it route around
+ * the refusal instead.
+ */
+export function denialMessage(tool, reason) {
+    const why = reason && reason.trim().length > 0 ? ` Reason: ${reason.trim()}` : '';
+    return (`The caller denied this tool call (${tool}).${why} ` +
+        'Do not retry the same call. Explain what you were trying to do, or take a different approach.');
+}
+/** The text a timed-out decision produces. Exported for the same reason. */
+export function timeoutMessage(tool, timeoutMs) {
+    return (`The caller did not answer within ${timeoutMs} ms. The tool was not run. ` +
+        `Do not retry ${tool} without asking; explain what you needed it for instead.`);
+}
+/** The text an aborted turn produces, in the middle of a decision wait. */
+export function interruptedMessage(tool) {
+    return `The turn was interrupted before the caller answered, so ${tool} was not run.`;
+}
+/**
+ * Wrap a tool behind the gate. Same `{...tool, execute}` shape as every other
+ * wrapper in this package, and the same `errorResult` discipline: a refusal is a
+ * TOOL RESULT, never a throw, because the engine pushes whatever this returns
+ * into history - and a `tool_use` with no `tool_result` is an HTTP 400 on the next
+ * request.
+ */
+export function withToolApproval(tool, gate, options = {}) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const request = {
+                tool: tool.name,
+                callId: id,
+                input: (params ?? {}),
+                summary: summarize(tool.name, (params ?? {})),
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            };
+            const ask = () => gate.decide(request);
+            const verdict = options.withHumanWait ? await options.withHumanWait(ask) : await ask();
+            if (verdict.allow)
+                return original(id, params, ctx);
+            return errorResult(verdict.message ?? denialMessage(tool.name, verdict.reason));
+        },
+    };
+}
+/**
+ * A local copy of the one-line summary, for the same reason `tools/index.ts` keeps
+ * its own: this file must stay importable by a test without dragging in the whole
+ * builtin tool set, and the two call sites describe the same three tools.
+ */
+function summarize(toolName, params) {
+    if (toolName === 'bash')
+        return `Run: ${String(params.command ?? '')}`;
+    if (toolName === 'write_file')
+        return `Write: ${String(params.path ?? '')}`;
+    if (toolName === 'edit_file')
+        return `Edit: ${String(params.path ?? '')}`;
+    if (toolName === 'skill_create')
+        return `Create skill: ${String(params.name ?? '')}`;
+    return toolName;
+}

package/dist/ui/App.js

@@ -87,6 +87,12 @@ import { createClipboardCoordinator } from './clipboard-task.js';
 import { QueuePanel } from './QueuePanel.js';
 import { QueueOverlay } from './overlays/QueueOverlay.js';
 import { AgentsBoardOverlay } from './overlays/AgentsBoardOverlay.js';
+// THE KEYBOARD DRAWER AND THE HEADER LABEL (tui-shortcut-drawer-and-task-summary).
+// Both are thin here on purpose: the drawer's geometry lives in
+// `layout/shortcut-panel-layout.ts` and the trigger rule in
+// `layout/task-summary-cell.ts`, so this file only routes state into them.
+import { ShortcutPanel } from './overlays/ShortcutPanel.js';
+import { shouldSummarize, taskSectionFrom } from './layout/task-summary-cell.js';
 import { buildQueueLayout } from './layout/queue-layout.js';
 import { interactionCopy } from './interaction-copy.js';
 import { createRunMetrics, updateRunMetrics, freezeRunMetrics, projectRunMetrics } from './run-metrics.js';
@@ -170,6 +176,36 @@ function applyPromptMutation(action) {
         return movePrompt(action.id, action.delta);
     return setPromptFavorite(action.id, action.favorite);
 }
+/**
+ * The first USER message in a transcript, or `''`.
+ *
+ * Used by the `/resume` rebuild, which must describe the conversation it is
+ * ADOPTING rather than the one on screen (D-13). A restored session can open with a
+ * tool card or a settled system notice, so "entries[0]" is not the answer.
+ */
+function firstUserText(entries) {
+    const entry = entries.find((candidate) => candidate.kind === 'user');
+    return entry && entry.kind === 'user' ? entry.text : '';
+}
+/**
+ * The overlays that hold an unresolved promise to the agent (review fix RF-1).
+ *
+ * NOT PANELS: `confirm` is a tool waiting for approval, `question` and `plan` are
+ * human-input requests, and each one is settled ONLY by the Escape branch of the
+ * global key handler. An overlay that can be dismissed without settling it strands
+ * the run, so `Ctrl+G` refuses to take the keyboard from these three - the same
+ * shape of refusal as `tooSmall` - and the header keeps naming `Esc close`.
+ */
+const DECISION_OVERLAYS = new Set(['confirm', 'question', 'plan']);
+/** The LAST user message in a transcript, or `''` — the anchor `/task refresh` uses. */
+function lastUserText(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry && entry.kind === 'user')
+            return entry.text;
+    }
+    return '';
+}
 export function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, scrollMode = 'app', scrollback, initialEntries, session, sessionBridge, sessionNotice, }) {
     const native = scrollMode === 'native' && scrollback !== undefined;
     /** Set when the native writer swallowed repeated tall frames; cleared by a resize. */
@@ -201,6 +237,14 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const [draftClearedByCtrlC, setDraftClearedByCtrlC] = useState(false);
     const [popupRows, setPopupRows] = useState(0);
     const [statusExpanded, setStatusExpanded] = useState(false);
+    /**
+     * The `/keys <query>` pre-filter for the drawer.
+     *
+     * STATE RATHER THAN A PROP OF THE COMMAND, because the command and the panel are
+     * two moments: `/keys git` sets the filter, `Ctrl+G` opens with whatever was set
+     * last, and the panel itself never types (F-2: a text field would fight `Esc`).
+     */
+    const [shortcutQuery, setShortcutQuery] = useState('');
     const dimensions = buildFrameBudget({ ...size, draftRows, popupRows, statusExpanded });
     const { rows, cols } = dimensions;
     /**
@@ -304,6 +348,17 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const reducedMotion = cfg.reducedMotion ?? false;
     const stateRef = useRef(state);
     stateRef.current = state;
+    /**
+     * The task label's two guards (tui-shortcut-drawer-and-task-summary D-10).
+     *
+     * `taskSummaryEpoch` IS THE CORRECTNESS GUARD and the `AbortController` is the
+     * economy one: the epoch decides whether a late result may still be adopted, the
+     * abort releases the connection the moment its answer stopped mattering. Neither
+     * substitutes for the other, so both are bumped/cancelled on every new-task
+     * boundary - `/clear`, `/resume`, and a new first submit.
+     */
+    const taskSummaryEpoch = useRef(0);
+    const taskSummaryAbort = useRef(null);
     const startedAt = useRef(Date.now());
     const confirmRef = useRef(null);
     confirmRef.current = confirmState;
@@ -1628,6 +1683,74 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         }
         return applied;
     };
+    /**
+     * Cancel any in-flight label call and make its result unadoptable.
+     *
+     * ONE FUNCTION FOR BOTH BOUNDARIES: the epoch is incremented BEFORE the abort so a
+     * resolution that is already sitting in the microtask queue cannot slip through
+     * between the two statements.
+     */
+    const cancelTaskSummary = () => {
+        taskSummaryEpoch.current += 1;
+        taskSummaryAbort.current?.abort();
+        taskSummaryAbort.current = null;
+    };
+    /**
+     * Start one label call, if the trigger rule allows it (D-7).
+     *
+     * FIRE AND FORGET, AND NEVER AWAITED: the caller (`submitMessage`) starts
+     * `controller.prompt()` immediately after this returns, so the summary can never
+     * delay the first token (AC-13). `summarizeTask` never rejects, so there is no
+     * `.catch` here and no unhandled rejection can reach a TUI with nowhere to show it.
+     */
+    const ensureTaskSummary = (anchor, opts = {}) => {
+        const decision = shouldSummarize({
+            anchor,
+            // `force` IS THE `/resume` REBUILD. The reducer is about to replace the label
+            // with `null`, so reading the CURRENT state here would see the old
+            // conversation's label still in place and skip the rebuild - a race the
+            // wrapper cannot win by ordering alone, because React applies the action on
+            // the next render. An explicit instruction outranks the automatic rule; the
+            // `enabled` and anchor checks still apply.
+            hasSummary: opts.force === true ? false : stateRef.current.taskSummary !== null,
+            pending: opts.force === true ? false : stateRef.current.taskSummaryPending,
+            enabled: controller.getConfig().taskSummary?.enabled !== false,
+            userInitiated: opts.userInitiated !== false,
+        });
+        if (!decision.start)
+            return;
+        taskSummaryEpoch.current += 1;
+        const epoch = taskSummaryEpoch.current;
+        taskSummaryAbort.current?.abort();
+        const abort = new AbortController();
+        taskSummaryAbort.current = abort;
+        dispatch({ type: 'taskSummaryPending' });
+        // `?.` FOR THE SAME REASON `isCompactionBusy?.()` AND `isFastRegistered?.()` USE IT:
+        // a host that supplies a partial controller (every App test double, and any
+        // embedding that never wanted this feature) must not crash on a header
+        // decoration. A missing method means "no label machinery here", which is exactly
+        // `view: null`.
+        const call = controller.summarizeTask?.(anchor, {
+            signal: abort.signal,
+            ellipsis: glyphs.ellipsis,
+        });
+        if (!call) {
+            // Nothing was started, so the latch must come back down or every later task
+            // would be skipped as `pending`.
+            dispatch({ type: 'taskSummaryReady', view: null });
+            return;
+        }
+        void call.then((outcome) => {
+            if (!mounted.current)
+                return;
+            // THE EPOCH CHECK IS THE ADOPTION RULE, not a nicety: `/clear` while a call was
+            // in flight would otherwise paint the previous task's label onto an empty
+            // session, which is the one thing a label must never do.
+            if (epoch !== taskSummaryEpoch.current)
+                return;
+            dispatch({ type: 'taskSummaryReady', view: outcome.view });
+        });
+    };
     const makeCtx = (args) => ({
         args,
         requestCopy: copyCoordinator.requestCopy,
@@ -1678,6 +1801,24 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
                     dispatch({ type: 'abortMark' });
                     dispatch({ type: 'runEnd' });
                 }
+                // A NEW-TASK BOUNDARY INVALIDATES THE LABEL IN FLIGHT (D-10 / D-13). The
+                // reducer clears the stored view in both branches; this cancels the call
+                // whose answer belongs to the conversation that just ended, and it runs
+                // BEFORE `dispatch(action)` so no late result can be adopted in between.
+                cancelTaskSummary();
+                if (action.type === 'restoreEntries') {
+                    // `/resume` REBUILDS ONE LABEL FROM THE ENTRIES IT JUST ADOPTED.
+                    //
+                    // FROM `action.entries`, NOT `state.entries`: this wrapper runs before the
+                    // reducer applies the action, so the state snapshot is still the
+                    // conversation being replaced. Reading the reducer's input is also the
+                    // only way this works for the `/resume` path at all - and the App's
+                    // initial seed (`seedViewState`) calls `viewReducer` DIRECTLY, so
+                    // launching with `--resume` costs nothing (AC-26).
+                    const anchor = firstUserText(action.entries);
+                    if (anchor !== '')
+                        ensureTaskSummary(anchor, { userInitiated: true, force: true });
+                }
             }
             dispatch(action);
         },
@@ -1692,6 +1833,27 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             resolve: (ref) => resolvePromptRef(loadPromptLibrary(), ref),
         },
         setOverlay: (overlay) => dispatch({ type: 'setOverlay', overlay }),
+        // THE TASK LABEL PORT (`/keys`, `/task`; §6.4). Reads go through `stateRef` so a
+        // command always sees the LATEST label rather than the one from the render that
+        // built this context - the same rule `transcriptEntries` above records.
+        taskSummary: {
+            openPanel: (query) => {
+                setShortcutQuery(query ?? '');
+                dispatch({ type: 'setOverlay', overlay: 'shortcuts' });
+            },
+            read: () => ({
+                view: stateRef.current.taskSummary,
+                pending: stateRef.current.taskSummaryPending,
+                enabled: controller.getConfig().taskSummary?.enabled !== false,
+            }),
+            refresh: () => {
+                const anchor = lastUserText(stateRef.current.entries);
+                if (anchor === '')
+                    return '';
+                ensureTaskSummary(anchor, { force: true, userInitiated: true });
+                return anchor;
+            },
+        },
         notify,
         toast,
         persistConfig,
@@ -1805,6 +1967,15 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             return { accepted: true };
         }
         // Fire-and-forget: events drive the UI. prompt() never rejects.
+        //
+        // THE LABEL HOOK SITS HERE AND NOWHERE ELSE (P1-1): after `preflight()` said
+        // yes, before `prompt()` is started. Above this line the two `return`s are a
+        // restart notice and a run already starting; between `dispatch({type:'submit'})`
+        // and `preflight()` is the path where a rejected submission would pay for a
+        // model call that describes a turn nobody ran; and below, in the queueing
+        // branch, the message is steering rather than a new task.
+        if (opts.userInitiated !== false)
+            ensureTaskSummary(message);
         void controller.prompt(message, { todoPolicy: opts.todoPolicy ?? 'new-task' }).then((outcome) => {
             if (!mounted.current || sequence !== submissionSequence.current)
                 return;
@@ -2170,10 +2341,36 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             }, 1500);
             return;
         }
+        // Ctrl+G: THE KEYBOARD DRAWER (tui-shortcut-drawer-and-task-summary D-1).
+        //
+        // THREE STATES, NOT ONE GUARD (P2-3). It used to require "no overlay open" and
+        // then flipped the status detail row; both halves are gone:
+        //  - `shortcuts` open  -> close it (the `Ctrl+B` precedent);
+        //  - nothing open      -> open it;
+        //  - some OTHER overlay -> TAKE OVER. Swallowing the key would leave the user
+        //    pressing a key whose only on-screen hint is `Esc close` and getting
+        //    nothing, and what they asked for was this panel.
+        //
+        // THE DECISION OVERLAYS ARE THE ONE EXCEPTION, AND IT IS NOT A NICETY (review fix
+        // RF-1). `confirm`, `question` and `plan` are not panels: each holds an
+        // unresolved promise to the agent - a tool waiting for approval, a question
+        // waiting for an answer - and the Escape branch further down is the ONLY path
+        // that settles one (`cancelConfirmation` / `cancelPendingHuman`). Taking the
+        // keyboard away from such a dialog would hide it and leave that promise pending
+        // for ever: a run that never resumes, and a screen that cannot say why. A
+        // read-only reference panel is not worth stranding a run, so the key stays inert
+        // here and the header keeps naming the key that does work.
+        //
+        // THE DETAIL-ROW TOGGLE MOVED INSIDE THE DRAWER (`d`, D-6): `HelpOverlay` and
+        // `CHANGELOG` both name the new home, and the panel's title line carries the
+        // `details on|off` state.
         if (key.ctrl && input.toLowerCase() === 'g') {
-            if (tooSmall || stateRef.current.overlay)
+            if (tooSmall)
+                return;
+            const open = stateRef.current.overlay;
+            if (DECISION_OVERLAYS.has(open))
                 return;
-            setStatusExpanded(value => !value);
+            dispatch({ type: 'setOverlay', overlay: open === 'shortcuts' ? null : 'shortcuts' });
             return;
         }
         // Ctrl+B: the Agents board (tui-subagent-panel D-6 / §6.5).
@@ -2652,14 +2849,12 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     // ALWAYS CALLED, INERT WHEN `enabled` IS FALSE: hooks cannot be conditional, and
     // an inert hook is what keeps `scrollMode: 'app'` byte-identical (I-S9).
     const viewCols = native ? Math.max(1, cols - 1) : cols;
-    const header = (_jsx(Header, { columns: viewCols, statusExpanded: statusExpanded, scrolledLines: scrolledLines, overlayOpen: overlay !== null, cwd: controller.getCwd(), provider: cfg.provider, model: cfg.model, hasKey: hasKey, variant: pickHeaderVariant(cols), theme: theme, caps: caps, 
-        // ALWAYS TRUE (agent-model-kits §4.7 / RV-P1-2): the requirement is that
-        // `ctrl+G` reveals `ctrl+K`, and the user with an empty library needs that
-        // hint most - the picker itself carries the "create one in /settings" row.
-        kitHint: true, 
-        // `prompts.hint=false` removes the `^P prompts` clause and nothing else; the key
-        // still works (AC-3).
-        promptsHint: cfg.prompts?.hint !== false }));
+    const header = (_jsx(Header, { columns: viewCols, 
+        // DERIVED IN EXACTLY ONE PLACE (0-3 (d)): both overlay slots render
+        // `overlayNode`, and both read this same three-state value from here.
+        panel: overlay === null ? 'none' : overlay === 'shortcuts' ? 'shortcuts' : 'other', scrolledLines: scrolledLines, taskSummary: state.taskSummary === null
+            ? null
+            : { text: state.taskSummary.text, tone: state.taskSummary.tone }, summaryEnabled: cfg.taskSummary?.enabled !== false, cwd: controller.getCwd(), provider: cfg.provider, model: cfg.model, hasKey: hasKey, variant: pickHeaderVariant(cols), theme: theme, caps: caps }));
     // The header and the opener are SLOTS OF THE SHELL, not printed bytes (D3/D4): at
     // `H = rows - 1` a printed row is pushed off the screen by the very next frame, so
     // `printBanner()` was a way of making the banner invisible. Neither is passed here.
@@ -2710,7 +2905,25 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const openerCols = nativeBudget ? nativeBudget.previewCols : contentCols;
     const opener = empty ? (_jsx(SessionOpener, { variant: pickOpenerVariant(openerRows, openerCols), version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: openerRows, theme: theme, caps: caps })) : null;
     const overlayMaxRows = nativeBudget ? nativeBudget.overlayRows : viewportBudget;
-    const overlayNode = overlay === 'queue' ? (_jsx(QueueOverlay, { pending: state.pendingSteering, cols: viewCols, maxRows: overlayMaxRows, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'help' ? (_jsx(OverlayFrame, { title: "Help", hint: `Esc close ${glyphs.midDot} PgUp/PgDn scroll`, maxRows: overlayMaxRows, cols: viewCols, rows: helpRows(theme, caps, native), scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'model' ? (_jsx(ModelPicker, { isActive: !tooSmall, registry: controller.getModelRegistry(), currentProvider: cfg.provider, currentModel: cfg.model, maxRows: overlayMaxRows, cols: viewCols, theme: theme, caps: caps, onSelect: handleModelSelect })) : overlay === 'kit' ? (_jsx(KitPicker, { isActive: !tooSmall, library: cfg.modelProfiles, config: cfg, ...(kitDiskConfig ? { diskConfig: kitDiskConfig } : {}), active: activeKit, 
+    const overlayNode = 
+    // THE DRAWER (tui-shortcut-drawer-and-task-summary D-4): it rides the SAME
+    // overlay slot as `/help` and `/agents`, so it needs no new frame shape, no
+    // second scroll authority and no geometry change in `ScrollViewport`.
+    overlay === 'shortcuts' ? (_jsx(ShortcutPanel, { isActive: !tooSmall, cols: viewCols, maxRows: overlayMaxRows, theme: theme, caps: caps, native: native, running: running, query: shortcutQuery, task: taskSectionFrom({
+            view: state.taskSummary,
+            pending: state.taskSummaryPending,
+            enabled: cfg.taskSummary?.enabled !== false,
+            now: Date.now(),
+        }), detailsExpanded: statusExpanded, onToggleDetails: () => setStatusExpanded((value) => !value), onRefresh: () => {
+            // THE MANUAL OVERRIDE (D-7): the last thing the user asked for. An empty
+            // conversation has nothing to describe, so it says so instead of calling.
+            const anchor = lastUserText(state.entries);
+            if (anchor === '') {
+                toast('info', 'No prompt to summarise yet.');
+                return;
+            }
+            ensureTaskSummary(anchor, { force: true, userInitiated: true });
+        } })) : overlay === 'queue' ? (_jsx(QueueOverlay, { pending: state.pendingSteering, cols: viewCols, maxRows: overlayMaxRows, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'help' ? (_jsx(OverlayFrame, { title: "Help", hint: `Esc close ${glyphs.midDot} PgUp/PgDn scroll`, maxRows: overlayMaxRows, cols: viewCols, rows: helpRows(theme, caps, native), scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps })) : overlay === 'model' ? (_jsx(ModelPicker, { isActive: !tooSmall, registry: controller.getModelRegistry(), currentProvider: cfg.provider, currentModel: cfg.model, maxRows: overlayMaxRows, cols: viewCols, theme: theme, caps: caps, onSelect: handleModelSelect })) : overlay === 'kit' ? (_jsx(KitPicker, { isActive: !tooSmall, library: cfg.modelProfiles, config: cfg, ...(kitDiskConfig ? { diskConfig: kitDiskConfig } : {}), active: activeKit, 
         // ONLY THE APPLY IS BLOCKED while work is in flight (§4.7): a list a
         // user cannot even OPEN reads as a broken key.
         busy: controller.isModelSettingsBusy(), maxRows: overlayMaxRows, cols: viewCols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onChoose: handleKitChoose, onClose: () => dispatch({ type: 'setOverlay', overlay: null }) })) : overlay === 'prompts' ? (_jsx(PromptLibraryOverlay, { isActive: !tooSmall, library: promptLibrary, ...(promptIntent ? { intent: promptIntent } : {}), cols: viewCols, maxRows: overlayMaxRows, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onMutate: handlePromptMutate, onNotice: notify, onClose: () => dispatch({ type: 'setOverlay', overlay: null }) })) : overlay === 'prompt-pick' ? (_jsx(PromptPicker, { isActive: !tooSmall, library: promptLibrary, cols: viewCols, maxRows: overlayMaxRows, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onFill: handlePromptFill, onManage: (entry) => openPromptLibrary(entry), onClose: closePromptPicker })) : overlay === 'settings' ? (_jsx(SettingsScreen, { isActive: !tooSmall, initial: {

package/dist/ui/Header.d.ts

@@ -1,8 +1,19 @@
-/** One-row brand bar with a fixed-width history and detail affordance. */
+/**
+ * One-row brand bar: word mark, identity, working directory, task summary and a
+ * fixed-width hint column (tui-shortcut-drawer-and-task-summary §4.2 / §4.3).
+ *
+ * THIS COMPONENT COMPUTES NO WIDTHS ANY MORE. Both halves come from pure
+ * planners - `planHeaderHints` for the right column and `planHeaderLeft` for the
+ * clause ladder - so the only arithmetic left here is "join what I was given".
+ * The old shape carried a `statusExpanded` flag, a kit switch and a prompts
+ * switch, all of which existed to choose between header clauses; the clauses are
+ * gone (the drawer lists the keys instead), so the props are gone with them.
+ */
 import React from 'react';
 import type { Theme } from './theme.js';
 import type { TermCapabilities } from './capabilities.js';
 import { type HeaderVariant } from './Logo.js';
+import { type HeaderPanelState } from './layout/header-hints.js';
 interface HeaderProps {
     cwd: string;
     provider: string;
@@ -12,25 +23,26 @@ interface HeaderProps {
     theme: Theme;
     caps: TermCapabilities;
     columns?: number;
-    statusExpanded?: boolean;
-    scrolledLines?: number;
-    overlayOpen?: boolean;
     /**
-     * Whether the expanded status row teaches `ctrl+K` (agent-model-kits §4.7).
-     *
-     * DEFAULTS TO TRUE because that is the requirement - `ctrl+G` must reveal the
-     * kit key - and because a default of `false` would leave the one caller that
-     * forgets the prop silently teaching nothing.
+     * What the right column says. Derived in ONE place - the line that renders
+     * `<Header>` - so the two overlay slots cannot disagree about it.
      */
-    kitHint?: boolean;
+    panel?: HeaderPanelState;
+    scrolledLines?: number;
     /**
-     * Whether the collapsed row teaches `ctrl+P` (quick-prompt-library D-15).
+     * The session's task label, or `null` while there is none.
      *
-     * DEFAULTS TO TRUE for the same reason `kitHint` does: the requirement is that the
-     * key be visible, and a default of `false` would leave the one caller that forgets
-     * the prop silently teaching nothing. `cfg.prompts.hint` is what turns it off.
+     * `null` WHILE PENDING TOO: a placeholder here would spend eight columns of the
+     * row to draw an ellipsis and then move everything back when the label lands,
+     * so the first submit visibly jogged the header. The label now appears once,
+     * complete (P2-10).
      */
-    promptsHint?: boolean;
+    taskSummary?: {
+        text: string;
+        tone: 'model' | 'fallback';
+    } | null;
+    /** `config.taskSummary.enabled`; `false` removes the cell without removing the words. */
+    summaryEnabled?: boolean;
 }
-export declare function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns, statusExpanded, scrolledLines, overlayOpen, kitHint, promptsHint }: HeaderProps): React.ReactElement;
+export declare function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns, panel, scrolledLines, taskSummary, summaryEnabled, }: HeaderProps): React.ReactElement;
 export {};

package/dist/ui/Header.js

@@ -2,24 +2,26 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { basename } from 'node:path';
 import { Box, Text } from 'ink';
 import { Logo } from './Logo.js';
-import { planHeaderHints, HEADER_HINT_LIMITS } from './layout/header-hints.js';
-export function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns = 80, statusExpanded = false, scrolledLines = 0, overlayOpen = false, kitHint = true, promptsHint = true }) {
-    // The right-hand hints are planned, not assembled (tui-branch-terminal-shortcut
-    // 3.9 / D-11). `plan.text` is exactly `plan.cells` wide and already carries the
-    // scroll chip's own trailing spacing, so this component can no longer clip a
-    // hint by guessing one cell short - and the ladder that decides which hints
-    // survive a narrow terminal lives in a pure function with its own tests.
-    //
-    // `kitHint` is the `^K switch kit` clause (agent-model-kits §4.7): `App`
-    // passes `true` always, because the requirement is that `ctrl+G` reveals the
-    // key - and the user with no kits needs that hint most.
-    const plan = planHeaderHints({
-        columns, statusExpanded, overlayOpen, scrolledLines, kitHint, promptsHint,
+import { pickGlyphs } from './glyphs.js';
+import { planHeaderHints, HEADER_HINT_LIMITS, } from './layout/header-hints.js';
+import { planHeaderLeft } from './layout/header-left.js';
+export function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns = 80, panel = 'none', scrolledLines = 0, taskSummary = null, summaryEnabled = true, }) {
+    const glyphs = pickGlyphs(caps);
+    // THE RIGHT COLUMN FIRST: it is the only clause that may never be dropped, so
+    // the left half is planned against what is left after it (defect 12).
+    const plan = planHeaderHints({ columns, panel, scrolledLines });
+    const leftCells = Math.max(0, columns - plan.cells - HEADER_HINT_LIMITS.separatorCells);
+    const left = planHeaderLeft({
+        leftCells,
+        provider,
+        model,
+        cwd: basename(cwd) || cwd,
+        hasKey,
+        summary: taskSummary,
+        summaryEnabled,
+        ellipsis: glyphs.ellipsis,
     });
-    // THE TWO HALVES ARE SEPARATED BY CELLS, NOT BY LUCK (defect 12). The left half
-    // is `wrap="truncate"`, which draws its ellipsis in the LAST cell it owns; with
-    // the right half starting in the very next cell a narrow terminal read
-    // `aragon...Details off` as one string. The blank column comes out of the left
-    // half's width, so the row still spans exactly `columns`.
-    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: Math.max(0, columns - plan.cells - HEADER_HINT_LIMITS.separatorCells), flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.accent, children: ['  ', provider, ":", model] }), _jsxs(Text, { color: theme.muted, children: ['  ', basename(cwd) || cwd] }), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: HEADER_HINT_LIMITS.separatorCells, flexShrink: 0 }), _jsx(Box, { width: plan.cells, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: plan.text }) })] });
+    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: leftCells, flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [left.text.model && _jsxs(Text, { color: theme.accent, children: ['  ', left.text.model] }), left.text.cwd && _jsxs(Text, { color: theme.muted, children: ['  ', left.text.cwd] }), left.text.summary && _jsxs(Text, { color: theme.muted, children: ['  ', glyphs.midDot, ' '] }), left.text.summary && (taskSummary?.tone === 'fallback'
+                                    ? _jsx(Text, { color: theme.muted, dimColor: true, children: left.text.summary })
+                                    : _jsx(Text, { color: theme.primary, children: left.text.summary })), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: HEADER_HINT_LIMITS.separatorCells, flexShrink: 0 }), _jsx(Box, { width: plan.cells, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: plan.text }) })] });
 }

package/dist/ui/interaction-hints.js

@@ -29,6 +29,12 @@ export function actionCandidates(input) {
     if (input.overlay) {
         if (input.overlay === 'confirm')
             return [copy.approveTool, copy.rejectTool];
+        // THE DRAWER SELECTS, IT DOES NOT SCROLL (tui-shortcut-drawer-and-task-summary
+        // §5). It is a list with a cursor, so the generic `copy.scroll` fallback would
+        // describe the wrong interaction - and the drawer's own footer already names
+        // every key, so one clause is the whole line.
+        if (input.overlay === 'shortcuts')
+            return [copy.select];
         const selects = ['question', 'model', 'session', 'settings'].includes(input.overlay);
         return [selects ? copy.select : copy.scroll,
             ...(selects ? [input.overlay === 'settings' ? copy.saveSettings : copy.confirm] : [])];

package/dist/ui/layout/OverlayFrame.d.ts

@@ -10,6 +10,24 @@ interface OverlayFrameBase {
     cols?: number;
     theme: Theme;
     caps: TermCapabilities;
+    /**
+     * Where the frame sits on the row when `width` is given.
+     *
+     * DEFAULT `'left'` AND NO WRAPPER BOX: with neither new prop set, the render
+     * tree is byte-identical to the pre-`shortcut-drawer` one, which is what keeps
+     * the eight existing overlays' layout assertions green (`R-16`).
+     */
+    align?: 'left' | 'right';
+    /**
+     * An explicit width for a frame that is NOT the full terminal width - the
+     * shortcut drawer's right-hand bar.
+     *
+     * THE FRAME STILL DECIDES ITS OWN FORM from `cols` (`BORDERLESS_COLS`), so the
+     * caller passes the TERMINAL width here and the bar's width separately. Passing
+     * the bar's width as `cols` would put a 46-cell drawer on a 200-column terminal
+     * into the rail form for ever.
+     */
+    width?: number;
 }
 interface OverlayFrameControlled extends OverlayFrameBase {
     /** One element per row, each already `wrap="truncate"`. */

package/dist/ui/layout/OverlayFrame.js

@@ -60,14 +60,29 @@ export function OverlayFrame(props) {
             onScrollClamp?.(overflowOffset);
     }, [overflowOffset, onScrollClamp]);
     const inner = (_jsxs(_Fragment, { children: [_jsxs(Box, { flexDirection: "row", height: 1, flexShrink: 0, children: [_jsx(Box, { flexGrow: 1, flexShrink: 1, children: _jsx(Text, { wrap: "truncate", color: theme.primary, bold: true, children: title }) }), position && _jsx(Box, { width: stringWidth(position), flexShrink: 0, children: _jsx(Text, { color: theme.muted, children: position }) })] }), _jsx(Box, { flexDirection: "column", flexShrink: 0, height: unbounded ? undefined : Math.max(1, maxRows - (compact ? 2 : bordered ? 5 : 3)), overflowY: "hidden", children: body }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hint })] }));
-    if (compact)
-        return _jsx(Box, { width: cols, height: Math.max(0, maxRows), flexDirection: "column", flexShrink: 0, overflowY: "hidden", children: inner });
+    // THE NEW PROPS ARE OPTIONAL AND THEIR DEFAULT IS TODAY'S BEHAVIOUR (R-16): the
+    // three branches below return exactly what they always returned unless the
+    // caller asked for a width or a right-hand placement. When it did, the SAME box
+    // is built and then placed inside one row-wide wrapper, which is the only way
+    // Ink can push a fixed-width child to the right edge (a `marginLeft: 'auto'`
+    // does not exist here).
+    const width = props.width;
+    const align = props.align ?? 'left';
+    const placed = (node) => {
+        if (width === undefined && align === 'left')
+            return node;
+        return (_jsx(Box, { width: cols, flexDirection: "row", flexShrink: 0, justifyContent: align === 'right' ? 'flex-end' : 'flex-start', children: node }));
+    };
+    const boxWidth = width === undefined ? {} : { width };
+    if (compact) {
+        return placed(_jsx(Box, { ...boxWidth, width: width ?? cols, height: Math.max(0, maxRows), flexDirection: "column", flexShrink: 0, overflowY: "hidden", children: inner }));
+    }
     if (!bordered) {
         // Narrow terminals trade the box for a rail: same grouping, 2 fewer rows
         // and 4 fewer columns (§5.2).
-        return (_jsx(Box, { flexDirection: "column", flexShrink: 0, marginTop: 1, children: _jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: railBorderStyle, borderTop: false, borderBottom: false, borderRight: false, borderColor: theme.primary, paddingLeft: 1, children: inner }) }));
+        return placed(_jsx(Box, { flexDirection: "column", flexShrink: 0, marginTop: 1, ...boxWidth, children: _jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: railBorderStyle, borderTop: false, borderBottom: false, borderRight: false, borderColor: theme.primary, paddingLeft: 1, children: inner }) }));
     }
-    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: glyphs.boxStyle, borderColor: theme.primary, paddingX: 1, marginTop: 1, children: inner }));
+    return placed(_jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: glyphs.boxStyle, borderColor: theme.primary, paddingX: 1, marginTop: 1, ...boxWidth, children: inner }));
 }
 /**
  * Rows one PgUp/PgDn - and one Shift+wheel notch - turns inside a controlled