@linxiraos/pi-tui 1.3.2 → 1.4.1

package/dist/types/tools/job-widget.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Live widgets for background jobs: the rendered state of what a job is
+ * doing (a benchmark's requests/s over time, tests passed per model, CI jobs
+ * green so far), shown in the `wait` card, the HUD's jobs pill and the jobs
+ * sheet.
+ *
+ * A widget is data, not code. In coding-agent, a cheap model writes a
+ * `JobWidgetSpec` once per job (rules that pull numbers out of the job's
+ * output streams, and the blocks to draw them with); the job-widgets runtime
+ * then applies those rules to every new line and recomputes a
+ * {@link JobWidgetView}. Renderers here draw that view as TSP nodes (Tern) or
+ * ANSI lines, and never see a rule or a regex.
+ */
+import type { TspPropNode, TspSpan, TspTone } from "@linxiraos/pi-wire";
+import type { NativeNode } from "../native/node.js";
+import type { Theme } from "../theme/theme.js";
+/** Where a widget's view stands. */
+export type JobWidgetState = 
+/** The cheap model is writing the spec; the view holds the model-free fallback meanwhile. */
+"authoring"
+/** The spec's rules drive the view. */
+ | "live"
+/** No spec (no model, authoring failed, nothing to read yet): last line and rates only. */
+ | "fallback";
+/** A formatted number with the direction it moved, for headlines and stats. */
+export interface JobWidgetTrend {
+    /** `▲ 15%`, `▼ 3.2 ms`. */
+    text: string;
+    /** `success` when the move is toward `better`, `error` away from it, `muted` without a direction. */
+    tone: "success" | "error" | "muted";
+}
+/** The headline value: the one number a glance should take away (`186 tok/s`). */
+export interface JobWidgetHeadline {
+    /** Formatted value with its unit. */
+    text: string;
+    /** What the value is, when the title does not already say it (`decode`, `p50`). */
+    label?: string;
+    trend?: JobWidgetTrend;
+}
+/** A time series drawn as columns, newest right, with optional reference lines. */
+export interface JobWidgetSparkBlock {
+    kind: "spark";
+    /** What the series measures (`tok/s · nvfp4 b1`). */
+    label: string;
+    /** At most 48 values, oldest first, already downsampled. */
+    values: number[];
+    /** Domain of the chart; covers the values and every mark. */
+    min: number;
+    max: number;
+    /** Horizontal reference lines in value units (a target, a baseline). */
+    marks?: {
+        value: number;
+        label: string;
+        tone?: TspTone;
+    }[];
+    /** Latest value, formatted (`186 tok/s`). */
+    last: string;
+    /** Per-point tooltip text, same length as `values` (`12:04:31 · 186 tok/s`). */
+    tips?: string[];
+    tone?: TspTone;
+}
+/** One bar per key (a model, a shard): a value against a common maximum. */
+export interface JobWidgetBarsBlock {
+    kind: "bars";
+    label: string;
+    items: {
+        label: string;
+        value: number;
+        text: string;
+        tone?: TspTone;
+    }[];
+    /** The value a full bar stands for. */
+    max: number;
+}
+/** Progress of a countable whole (`7/9 trials`). */
+export interface JobWidgetMeterBlock {
+    kind: "meter";
+    label: string;
+    /** 0–1. */
+    value: number;
+    /** `7/9 trials`. */
+    text: string;
+    tone?: TspTone;
+}
+/** A few labelled numbers on one line (`p50 41 ms · p99 212 ms · errors 0`). */
+export interface JobWidgetStatBlock {
+    kind: "stat";
+    items: {
+        label: string;
+        text: string;
+        tone?: TspTone;
+        trend?: JobWidgetTrend;
+    }[];
+}
+/** One cell per key with its latest state (CI jobs, shards, workers). */
+export interface JobWidgetGridBlock {
+    kind: "grid";
+    label: string;
+    items: {
+        label: string;
+        text: string;
+        tone: TspTone;
+    }[];
+}
+/** The latest line a rule captured (the test now running, the current phase). */
+export interface JobWidgetTextBlock {
+    kind: "text";
+    text: string;
+}
+export type JobWidgetBlock = JobWidgetSparkBlock | JobWidgetBarsBlock | JobWidgetMeterBlock | JobWidgetStatBlock | JobWidgetGridBlock | JobWidgetTextBlock;
+/**
+ * Everything a renderer needs to draw one job's widget. Plain JSON: it rides
+ * on `JobSnapshot.widget` through `wait` progress updates and is persisted
+ * with the final `wait` result, so a sealed card redraws the last state after
+ * a session reload.
+ */
+export interface JobWidgetView {
+    /** Short name of what is being watched (`verb-bench · 3 models`). */
+    title: string;
+    headline?: JobWidgetHeadline;
+    /** What the job is doing now: a subagent's stage, or the last line of output. */
+    stage?: string;
+    /** Top to bottom; the first block is the primary one, and compact views show only it. */
+    blocks: JobWidgetBlock[];
+    state: JobWidgetState;
+    /** Epoch ms of the newest data the view reflects. */
+    updatedAt: number;
+}
+/** A running job's widget, as the HUD and the status line list them. */
+export interface JobWidgetEntry {
+    id: string;
+    type: JobTileType;
+    view: JobWidgetView;
+}
+/** What a glance at a widget reads: its headline, else the primary figure of its blocks. */
+export interface JobWidgetGlance {
+    text: string;
+    label?: string;
+    trend?: JobWidgetTrend;
+}
+/** What one glance at the widget reads: the headline, else the latest figure of its first spark or meter. */
+export declare function jobWidgetGlance(view: JobWidgetView): JobWidgetGlance | undefined;
+/** The widget's first spark cut to its newest `points` values (the HUD's mini chart); undefined without data. */
+export declare function jobWidgetSpark(view: JobWidgetView, points?: number): JobWidgetSparkBlock | undefined;
+/** The entry whose live widget (one a spec drives) saw data last. */
+export declare function latestJobWidget<T extends JobWidgetEntry>(entries: readonly T[]): T | undefined;
+/** The widget as one plain line for tooltips: `verb-bench · 3 models — decode 186 tok/s ▲ 15%`. */
+export declare function jobWidgetSummary(view: JobWidgetView): string;
+/** Spans of a glance: muted label, strong number, toned trend. */
+export declare function jobWidgetGlanceSpans(glance: JobWidgetGlance): TspSpan[];
+/**
+ * A glance for the ANSI status line: the figure with its trend, then a
+ * `cells`-wide sparkline of the primary spark when there is one.
+ */
+export declare function formatJobWidgetGlance(view: JobWidgetView, theme: Theme, cells?: number): string;
+/**
+ * A job's whole widget as a TSP subtree (role `zeta.job.widget`), as the jobs
+ * sheet details it: a head row (title, stage, headline) over every block.
+ */
+export declare function describeJobWidget(view: JobWidgetView): NativeNode;
+/**
+ * The HUD jobs pill's hover card: up to four running jobs as tiles, then a
+ * count of the rest; undefined without widgets. Its tiles carry no clock:
+ * Tern draws the card only once hovered, and a clock drawn then would start
+ * from the last time the program wrote.
+ */
+export declare function describeJobWidgetsHovercard(entries: readonly JobWidgetEntry[]): TspPropNode | undefined;
+/** The HUD's mini chart: the newest values of the widget's first spark; undefined without one. */
+export declare function describeJobWidgetMiniSpark(view: JobWidgetView): NativeNode | undefined;
+/** Where a tiled job stands. */
+export type JobTileStatus = "running" | "completed" | "failed" | "cancelled";
+/** What kind of job a tile shows: a subagent (`task`) goes by its name, any other job by what it runs. */
+export type JobTileType = "bash" | "task" | "eval";
+/** One job as a tile draws it: who it is, how long it has run, and its widget when it has one. */
+export interface JobTile {
+    id: string;
+    type: JobTileType;
+    status: JobTileStatus;
+    /** The job's label (a command): the title of a job that is no subagent, before a widget names it. */
+    label: string;
+    /** How long the job has run; a tile without it shows no clock. */
+    durationMs?: number;
+    /** Whether the job is live (its dot pulses, its clock runs); settled and sealed tiles freeze. */
+    live: boolean;
+    /** The job's widget; only a live one (a spec drives it) draws figures and charts, any lends its stage. */
+    widget?: JobWidgetView;
+    /** A task's own completion estimate (0–100), drawn as a ring. */
+    completionPercent?: number;
+    /** What the job is doing now, when its widget names nothing: a task's stage in its own words. */
+    stage?: string;
+    exitCode?: number;
+}
+/**
+ * Jobs as one frame of equal tiles (role `zeta.job.tiles`) that wraps onto
+ * more rows when the frame runs out of width.
+ */
+export declare function describeJobTiles(tiles: readonly JobTile[]): NativeNode;
+/**
+ * One job as a tile (role `zeta.job.tile`): a head line (status, name, id,
+ * a task's own completion estimate as a ring, clock), then what a live
+ * widget shows (the figure a glance takes away, its primary block, quiet
+ * lines of stats) and the stage. With nothing to chart, the stage is the
+ * tile's body.
+ */
+export declare function describeJobTile(tile: JobTile): NativeNode;
+/**
+ * A job's whole widget as terminal lines, each within `width` (capped at 80
+ * so bars stay next to their labels): the head line (title, stage, headline
+ * at the right), then every block under a shared label column.
+ */
+export declare function renderJobWidgetLines(view: JobWidgetView, width: number, theme: Theme): string[];
+/** How the ANSI wait card draws a tile. */
+export interface JobTileLineOptions {
+    /** Opens the title line: the caller's status icon and type badge. */
+    lead: string;
+    /** Closes the title line at the right, after the figure: the duration. */
+    meta: string;
+    /** Every block rather than the primary one alone (an expanded card). */
+    full?: boolean;
+}
+/**
+ * A tile as terminal lines within `width`: the lead, name and id with the
+ * figure and meta at the right, then a live widget's primary block (every
+ * block when `full`) and dim lines of stats and stage, capped at 80 cells.
+ */
+export declare function renderJobTileLines(tile: JobTile, width: number, theme: Theme, options: JobTileLineOptions): string[];

package/dist/types/tools/json-tree.d.ts

@@ -70,6 +70,8 @@ export interface JsonTreeDescribeOptions {
     openDepth?: number;
     /** Root object keys omitted. Defaults to internal tool argument metadata. */
     hiddenRootKeys?: readonly string[];
+    /** Called after the tree is built if a depth, node or scalar cap left part of the value out. */
+    onTruncated?: () => void;
 }
 /**
  * TSP `tree` of a JSON value: containers become expandable nodes labelled with

package/dist/types/tools/line-ranges.d.ts

@@ -10,12 +10,19 @@ export interface LineRange {
 export declare const LINE_RANGE_CHUNK_SOURCE: string;
 /** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
 export declare function parseLineRangeChunk(sel: string): LineRange | null;
+/** What a bare `N` selects in a one-chunk list: lines `N` onward (`:50`), or the single line `N`. */
+export type BareLineMode = "onward" | "single";
 /**
  * Parse a comma-separated list of line ranges (e.g. `5-16,960-973` or `19,59`). Returns
  * the ranges in ascending order with overlapping/adjacent ranges merged so
  * downstream consumers can stream the file in a single forward pass per range.
  */
-export declare function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null;
+export declare function parseLineRanges(sel: string, bare?: BareLineMode): [LineRange, ...LineRange[]] | null;
+/**
+ * Sort non-empty `ranges` by start line and merge the ones that overlap or touch;
+ * an open-ended range (`endLine` undefined) reaches EOF and absorbs every later one.
+ */
+export declare function mergeLineRanges(ranges: readonly LineRange[]): [LineRange, ...LineRange[]];
 /**
  * Extract the line-range component from a read-tool selector that may also
  * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded

package/dist/types/tools/mcp.d.ts

@@ -63,6 +63,27 @@ export interface MCPResourceContent {
 }
 /** Supported MCP result content blocks retained in display metadata. */
 export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+/** Server-reported progress of an in-flight MCP request. */
+export interface MCPProgress {
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * Read MCP progress fields from an untrusted record: `progress` must be a
+ * finite number; `total` is kept only when finite and `message` only when a
+ * string. Shared by the transports, the Eval bridge, and the status renderer.
+ */
+export declare function parseMCPProgress(value: unknown): MCPProgress | undefined;
+/**
+ * One-line display text for MCP progress, at most `maxWidth` cells: the
+ * message, with `progress/total` when the server reports a total. The bare
+ * progress value appears only when there is no message: without a total it is
+ * an opaque counter, not a percentage. Home paths in the message show as `~`,
+ * and a long message is cut before the count, so the count stays visible.
+ * Every progress display (tool card and both Eval status renderers) uses it.
+ */
+export declare function formatMCPProgress(progress: MCPProgress, maxWidth?: number): string;
 /** MCP result details shared by renderers and programmatic tool consumers. */
 export interface MCPToolDetails {
     /** Server name */
@@ -81,6 +102,8 @@ export interface MCPToolDetails {
     provider?: string;
     /** Provider display name (e.g., "Claude Code", "MCP Config") */
     providerName?: string;
+    /** Latest progress of a running call; present only on partial updates. */
+    progress?: MCPProgress;
     /** Structured output metadata (set by the spill wrapper when output is truncated to an artifact). */
     meta?: OutputMeta;
 }

package/dist/types/tools/output-meta.d.ts

@@ -110,7 +110,7 @@ export interface OutputMeta {
     /** Capture failure of this output itself; aggregate reports keep source failures on their entries. */
     artifactError?: OutputArtifactError;
     source?: SourceMeta;
-    /** The output is a bounded page of session artifact storage its `source` re-reads with line selectors; spill-to-artifact skips it. */
+    /** The output is a bounded page of a file or session artifact its `source` re-reads with line selectors; spill-to-artifact skips it. */
     pagedSource?: true;
     diagnostics?: DiagnosticMeta;
     limits?: LimitsMeta;

package/dist/types/tools/read.d.ts

@@ -71,8 +71,14 @@ export interface ReadToolDetails {
      */
     displayReadTargetLinks?: Array<string | null>;
 }
-/** Split a filesystem path from its trailing read selector. */
-export declare function splitPathAndSel(rawPath: string): {
+/**
+ * Split a filesystem path from its trailing read selector. `foldListColons: false`
+ * keeps a colon repeated inside a list as part of the path (`a:1-30,:-30` peels
+ * only `:-30`), for callers checking whether that shorter split names a real file.
+ */
+export declare function splitPathAndSel(rawPath: string, options?: {
+    foldListColons?: boolean;
+}): {
     path: string;
     sel?: string;
 };

package/dist/types/tools/renderer.d.ts

@@ -27,8 +27,9 @@ export interface RenderResultOptions {
     executionStarted?: boolean;
     /**
      * Milliseconds since this call began executing (`tool_execution_start`),
-     * or its total once settled; undefined before it starts. Native describe
-     * hooks only.
+     * or its total once settled; undefined before it starts. The terminal
+     * transcript's options object computes it on read, so a render-time read
+     * is live while the block's spinner ticks.
      */
     elapsedMs?: number;
     /** The call was abandoned without a final result (turn aborted, sealed). Native describe hooks only. */
@@ -177,6 +178,11 @@ export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
      * `options.spinnerFrame`.
      */
     animatedPartialResult?: boolean | ((args: TArgs) => boolean);
+    /**
+     * Repaint the block once a second while its call executes, for renderers
+     * that show live `options.elapsedMs` without consuming the spinner frame.
+     */
+    tickElapsed?: boolean;
     /**
      * Whether replacing a pending call render with the first result requires a
      * full viewport repaint. Use for merged renderers whose pending rows can be

package/dist/types/tools/result-card.d.ts

@@ -16,5 +16,5 @@ export interface CardToolResult {
 export declare function firstText(result: CardToolResult): string;
 /** Sanitize one display line: tabs become spaces, carriage returns are dropped. */
 export declare function safe(value: string): string;
-/** Padded card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
+/** Card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
 export declare function card(lines: (width: number, expanded: boolean) => string[], options: RenderResultOptions): Component;

package/dist/types/tools/streaming-output.d.ts

@@ -261,6 +261,7 @@ export declare class OutputSink {
      * Replace the in-memory buffer with the given text. Used when an upstream
      * minimizer rewrites the captured output after the raw bytes have already
      * been streamed.
+     * The replacement is held to the per-line column cap like streamed output.
      *
      * After this call the buffer is authoritative: streaming counters realign
      * to the replacement, the retained head window is cleared, and head

package/dist/types/tools/task.d.ts

@@ -264,6 +264,18 @@ export interface AgentProgress {
     advisor?: boolean;
     /** The agent's latest self-estimate of task completion (0–100), from the periodic `task.completionProbe` side request. */
     completionPercent?: number;
+    /**
+     * The agent's current step in its own words (one line, ≤ 80 chars), from the
+     * same probe reply as {@link completionPercent}. Running rows prefer it over
+     * `lastIntent`; the job widget uses it as its stage line.
+     */
+    stage?: string;
+    /**
+     * What the agent says shows its progress live (one line, ≤ 200 chars), e.g.
+     * "BENCH lines in bg_2 pipe:1, tok_s higher is better, target 70% of roofline";
+     * from the probe reply. Feeds the job widget author's brief; never rendered.
+     */
+    watch?: string;
     /** Data extracted by registered subprocess tool handlers (keyed by tool name) */
     extractedToolData?: Record<string, unknown[]>;
     /**

package/dist/types/tools/wait.d.ts

@@ -3,6 +3,7 @@ import type { Theme } from "../theme/theme.js";
 import { type OutputMeta } from "./output-meta.js";
 import { type ConfiguredThinkingLevel } from "../render/render-utils.js";
 import type { StructuredSubagentOutput } from "./task.js";
+import { type JobWidgetView } from "./job-widget.js";
 import type { RenderResultOptions, ToolActivitySummary } from "./renderer.js";
 import type { IrcDeliveryReceipt, IrcMessage } from "./irc.js";
 import type { NativeToolView, ToolRenderResult } from "./renderer.js";
@@ -29,6 +30,10 @@ export interface JobSnapshot {
     advisor?: boolean;
     /** The task agent's latest self-estimated completion (0–100); see `AgentProgress.completionPercent`. */
     completionPercent?: number;
+    /** The task agent's latest stage in its own words; see `AgentProgress.stage`. */
+    stage?: string;
+    /** The job's live widget, while one is being drawn; frozen at its last state once the job settles. */
+    widget?: JobWidgetView;
     resultText?: string;
     errorText?: string;
     /** Source-output metadata retained for per-job warnings and persisted row rendering. */
@@ -96,6 +101,12 @@ export interface CoordinationDetails {
     agents?: AgentActivitySnapshot[];
     /** `wait` was cut short by steering, a peer message, or a completion notice that injects next. */
     interrupted?: boolean;
+    /**
+     * `wait` returned early without a message because continuing would deadlock:
+     * the peer it was waiting on is itself waiting on this agent. Both sides can
+     * keep working — answer the peer, then wait again.
+     */
+    status?: "peer-waiting-on-you";
 }
 /** Pending wait frame. */
 declare function waitRenderCall(_args: object, _options: RenderResultOptions, uiTheme: Theme): Component;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-tui",
-	"version": "1.3.2",
+	"version": "1.4.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -38,14 +38,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@linxiraos/pi-omptype": "1.3.2",
-		"@linxiraos/pi-agent-core": "1.3.2",
-		"@linxiraos/pi-ai": "1.3.2",
-		"@linxiraos/pi-catalog": "1.3.2",
-		"@linxiraos/pi-natives": "1.3.2",
-		"@linxiraos/pi-utils": "1.3.2",
-		"@linxiraos/pi-wire": "1.3.2",
-		"@linxiraos/pi-snapcompact": "1.3.2"
+		"@linxiraos/pi-omptype": "1.4.1",
+		"@linxiraos/pi-agent-core": "1.4.1",
+		"@linxiraos/pi-ai": "1.4.1",
+		"@linxiraos/pi-catalog": "1.4.1",
+		"@linxiraos/pi-natives": "1.4.1",
+		"@linxiraos/pi-utils": "1.4.1",
+		"@linxiraos/pi-wire": "1.4.1",
+		"@linxiraos/pi-snapcompact": "1.4.1"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/apps/session-picker.ts

@@ -1,9 +1,12 @@
 import { logger } from "@linxiraos/pi-utils";
 import {
+	type ResumeSourceLike,
 	SessionSelectorComponent,
-	type SessionSelectorEntry,
 	type SessionHistoryMatcher,
+	type SessionSelectorEntry,
+	type SessionSelectorOptions,
 } from "../overlays/session-selector";
+import type { ResumeTreeSource } from "../overlays/resume-tree";
 import { runStandaloneTui } from "./standalone-picker";
 
 /** Persistence and history capabilities supplied by the session-owning host. */
@@ -12,6 +15,8 @@ export interface SessionPickerHost<T extends SessionSelectorEntry = SessionSelec
 	loadHistoryMatcher?(): SessionHistoryMatcher;
 	deleteSession?(session: T): Promise<boolean>;
 	loadAllSessions?(): Promise<T[]>;
+	/** Builds the three-level resume source for the standalone `--resume` tree. */
+	loadResumeSource?(deleteMode: "trash" | "permanent", workspacePath?: string): Promise<ResumeTreeSource | undefined>;
 }
 
 /** Presentation and capability controls for the standalone session picker. */
@@ -24,6 +29,12 @@ export interface SessionPickerOptions<T extends SessionSelectorEntry = SessionSe
 	allowGlobalScope?: boolean;
 	historySearch?: boolean;
 	pinnedIds?: ReadonlySet<string>;
+	/** Opt into the three-level resume tree; `deleteMode` words the confirm step. */
+	resume?: { deleteMode: "trash" | "permanent"; workspacePath?: string };
+	/** The host's resume model; when set, the native picker renders the project tree. */
+	resumeSource?: ResumeSourceLike;
+	/** Delete wording: in-session moves to trash, `--resume` deletes permanently. */
+	deleteMode?: "trash" | "permanent";
 }
 
 /**
@@ -51,6 +62,11 @@ export async function selectSession<T extends SessionSelectorEntry>(
 		}
 	}
 
+	const resumeMode = options.resume?.deleteMode;
+	const resumeSource = resumeMode
+		? await host.loadResumeSource?.(resumeMode, options.resume?.workspacePath)
+		: undefined;
+
 	return runStandaloneTui<T | null>(
 		({ ui, finish }) => {
 			const selector = new SessionSelectorComponent(
@@ -73,7 +89,9 @@ export async function selectSession<T extends SessionSelectorEntry>(
 					scopeLabel: options.scopeLabel,
 					showCwd: options.showCwd,
 					pinnedIds,
-				},
+					resumeSource: resumeSource ?? options.resumeSource,
+					deleteMode: resumeMode ?? options.deleteMode,
+				} as SessionSelectorOptions<T> & { resumeSource?: ResumeTreeSource; deleteMode?: "trash" | "permanent" },
 			);
 			selector.setOnRequestRender(() => ui.requestRender());
 			return selector;

package/src/autocomplete.d.ts

@@ -39,6 +39,12 @@ export interface AutocompleteItem {
     state?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
+    /**
+     * Slash command matched only through its description, not its name or an alias:
+     * a browse hit, so Enter submits the typed text instead of running it unless the
+     * user moved the selection onto it.
+     */
+    descriptionMatch?: boolean;
 }
 type Awaitable<T> = T | Promise<T>;
 export interface SlashCommand {

package/src/autocomplete.ts

@@ -226,6 +226,12 @@ export interface AutocompleteItem {
 	state?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
+	/**
+	 * Slash command matched only through its description, not its name or an alias:
+	 * a browse hit, so Enter submits the typed text instead of running it unless the
+	 * user moved the selection onto it.
+	 */
+	descriptionMatch?: boolean;
 }
 
 type Awaitable<T> = T | Promise<T>;
@@ -332,14 +338,18 @@ function getCommandAliases(cmd: CommandEntry): string[] {
 }
 
 function getStaticCommandDescription(cmd: CommandEntry): string {
-	return cmd.description ?? "";
+	const raw: unknown = cmd.description;
+	const description = typeof raw === "function" ? (raw as () => string)() : raw;
+	return typeof description === "string" ? description : "";
 }
 
 function getAutocompleteCommandDescription(cmd: CommandEntry): string {
-	if ("getAutocompleteDescription" in cmd && typeof cmd.getAutocompleteDescription === "function") {
-		return cmd.getAutocompleteDescription() ?? cmd.description ?? "";
-	}
-	return cmd.description ?? "";
+	const candidate: unknown =
+		"getAutocompleteDescription" in cmd && typeof cmd.getAutocompleteDescription === "function"
+			? cmd.getAutocompleteDescription()
+			: cmd.description;
+	const description = typeof candidate === "function" ? (candidate as () => string)() : candidate;
+	return typeof description === "string" && description.length > 0 ? description : getStaticCommandDescription(cmd);
 }
 
 /**
@@ -437,6 +447,7 @@ function buildSlashCommandCompletions(
 						...(cmd.iconName && { iconName: cmd.iconName }),
 						...(fullDesc && { description: fullDesc }),
 						...nativeTextMemo,
+						...(nameScore === 0 && { descriptionMatch: true }),
 					};
 				}
 
@@ -444,7 +455,11 @@ function buildSlashCommandCompletions(
 					for (const alias of getCommandAliases(cmd)) {
 						if (alias === name) continue;
 						const aliasScore = scoreCommandTextMatch(lowerPrefix, alias.toLowerCase());
-						if (aliasScore === 0 || (best && aliasScore <= best.score)) continue;
+						if (aliasScore === 0) continue;
+						// An alias can match even when the description outranks it; Enter
+						// must still accept the command rather than submit the raw query.
+						if (best?.descriptionMatch) delete best.descriptionMatch;
+						if (best && aliasScore <= best.score) continue;
 						const fullDesc = resolveFullDesc();
 						best = {
 							value: alias,

package/src/chat/skill-message.ts

@@ -14,8 +14,8 @@ import { collapseSkillTokens, skillChipLabel, skillChipStyle, skillToken } from
 import { tuiText, tuiTextFmt } from "../i18n";
 import { type UserBubbleOptions, UserMessageComponent, userBubbleColor } from "./user-message";
 import type { TspSpan } from "@linxiraos/pi-wire";
-import { card, md, node, span, text } from "../native/describe";
-import { type NativeChild, type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
+import { card, md, node, span } from "../native/describe";
+import { type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
 import { Memo } from "../native/memo";
 
 /**
@@ -64,8 +64,7 @@ export class SkillMessageComponent extends Container {
 	}
 
 	handleNativeEvent(event: NativeUiEvent): void {
-		const expanded = rootToggleExpanded(event);
-		if (expanded !== undefined) this.setExpanded(expanded);
+		if (event.type === "toggle" && event.key === "prompt") this.setExpanded(!event.collapsed);
 	}
 
 	/**
@@ -101,20 +100,20 @@ export class SkillMessageComponent extends Container {
 			const children: NativeChild[] = [];
 			if (draft) children.push(md(draft));
 			const promptText = this.#expanded ? this.#extractText() : "";
-			if (promptText) {
-				children.push(
-					node(
-						"section",
-						{ head: [span("prompt", "muted")], role: "zeta.skill.prompt" },
-						[md(promptText)],
-						"prompt",
-					),
-				);
-			}
-			return card(
-				{ role: "zeta.skill", tone: "user", head, collapsible: true, collapsed: !this.#expanded },
-				children.length > 0 ? children : [text([span(label, "muted")])],
+			children.push(
+				node(
+					"section",
+					{
+						head: [span("prompt", "muted")],
+						role: "zeta.skill.prompt",
+						collapsible: true,
+						collapsed: !this.#expanded,
+					},
+					promptText ? [md(promptText)] : [],
+					"prompt",
+				),
 			);
+			return card({ role: "zeta.skill", tone: "user", head }, children);
 		});
 	}