moqi-tui 0.2.0

package/lib/types/persist.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Small durable state for the terminal app: composer history, UI
+ * preferences, and the sessions that were open, kept as one JSON file under
+ * `$DSH_HOME`.
+ *
+ * Everything here is best-effort by design. The app must run on a read-only
+ * or missing home just as well as on a writable one — persistence is a
+ * convenience, never a dependency.
+ * @module moqi-tui/persist
+ */
+/**
+ * One session that was open when the app last exited.
+ *
+ * Only the id is load-bearing — the transcript itself lives in the Harness
+ * session store and is re-read on restore. The model and title are carried
+ * along so the tab bar and footer read correctly the instant the app paints,
+ * rather than snapping into place once each agent has been adopted.
+ */
+export interface PersistedSession {
+    /** The Harness session id to re-adopt. */
+    id: string;
+    /** Label of the model that session was using; empty means "use the default". */
+    model: string;
+    /** The tab's title, normally the opening prompt; empty until one is sent. */
+    title: string;
+}
+/** What survives a restart of the app. */
+export interface PersistedState {
+    /** Previously sent prompts, oldest first, for composer recall. */
+    inputHistory: string[];
+    /** Whether reasoning output was visible when the app last ran. */
+    thinking: boolean;
+    /** Name of the chosen color palette; absent means the app's default. */
+    theme?: string;
+    /** Interface language: `en` or `zh-CN`. */
+    lang?: string;
+    /**
+     * Whether tool calls were listed rather than summarized when the app last
+     * ran; absent means the default, which is to list them.
+     */
+    expandTools?: boolean;
+    /** Devices to include in the fleet overview, as `ssh` destinations. */
+    peers: string[];
+    /** Sessions that were open at the last exit, in tab order. */
+    sessions: PersistedSession[];
+    /** Index into {@link PersistedState.sessions} of the tab that was on screen. */
+    activeSession: number;
+}
+/**
+ * How many sessions a single restore will bring back.
+ *
+ * Every restored tab costs one session-store lookup and one agent adoption,
+ * both of them I/O before the first paint. A state file that has grown a long
+ * tail — or been hand-edited — must not turn a launch into a multi-second
+ * stall, and nobody navigates more tabs than this by hand anyway.
+ */
+export declare const MAX_RESTORED_SESSIONS = 16;
+/** Where the state file lives: `$DSH_HOME/tui-state.json`, default `~/.dsh`. */
+export declare function statePath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Turn the raw file contents into state, without touching the filesystem.
+ *
+ * Parsing is separated from reading so the whole degrade-gracefully contract
+ * — bad JSON, a version from another release, a half-written array of
+ * sessions — can be exercised as a pure function. It never throws: an input
+ * it cannot make sense of yields the fallback, which is always usable.
+ */
+export declare function decodeState(raw: string): PersistedState;
+/**
+ * Read the persisted state, returning the fallback when there is none or it
+ * cannot be understood.
+ */
+export declare function loadState(env?: NodeJS.ProcessEnv): Promise<PersistedState>;
+/** The sessions to bring back, and which of them to put on screen. */
+export interface RestorePlan {
+    /** Sessions worth adopting, in tab order; may be empty. */
+    sessions: PersistedSession[];
+    /** Index into {@link RestorePlan.sessions} to make active. */
+    active: number;
+}
+/**
+ * Decide what a restore should attempt, given what is still on disk.
+ *
+ * The session store is not owned by this app: `/delete` prunes it, and so does
+ * anything else that touches `$DSH_HOME` between two runs. A remembered id
+ * whose directory has gone is therefore an ordinary outcome and not an error —
+ * it is dropped here, silently, before anything tries to adopt it.
+ *
+ * @param state - what was read back from disk.
+ * @param isAvailable - whether that session id still exists in the store.
+ */
+export declare function restorePlan(state: PersistedState, isAvailable: (id: string) => boolean): RestorePlan;
+/**
+ * A scratch path for the write-then-rename, unique to this process.
+ *
+ * The rename is what makes a save atomic, but the file it renames has to be
+ * this process's alone. Several sessions of this app run at once -- that is
+ * the point of the fleet -- and when two of them saved at the same moment they
+ * wrote the same `tui-state.json.tmp` on top of each other and renamed the
+ * interleaved result into place. The file that came out was one complete
+ * document followed by a fragment of another, which every later read then
+ * discarded as unparseable, silently losing the remembered sessions, peers and
+ * theme. Observed, not hypothetical.
+ */
+export declare function scratchPath(target: string): string;
+/**
+ * Write the state atomically: a temporary file in the same directory, then a
+ * rename, so a crash mid-write can never leave a half-written JSON behind.
+ */
+export declare function saveState(state: PersistedState, env?: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * The synchronous twin of {@link saveState}, for the teardown path: `quit()`
+ * asks the launcher to exit immediately, so an in-flight async write would be
+ * cut off and the last prompt lost.
+ */
+export declare function saveStateSync(state: PersistedState, env?: NodeJS.ProcessEnv): void;

package/lib/types/plugins.d.ts

@@ -0,0 +1,218 @@
+/**
+ * The plugin set of the profile this app booted from.
+ *
+ * A Harness profile is a directory under `$DSH_HOME/profiles/<name>` whose
+ * `package.json` carries two lists that are easy to confuse: `dependencies`,
+ * which is what pnpm put on disk, and `dsh.profile.bundles`, the ordered
+ * layer stack the launcher actually composes. A package can sit in the first
+ * and not the second, and that gap is exactly what this app calls enabled and
+ * disabled — which is why the picker reads a manifest rather than asking the
+ * package manager what is installed.
+ *
+ * Everything that only reads or rewrites that manifest is a pure function
+ * over a parsed object, because the alternative is a feature whose only test
+ * is a network install. The two operations that cannot be pure — adding and
+ * removing a package — are one narrow `execFile` at the bottom of the file.
+ *
+ * Nothing here takes effect until the app is restarted: the bundle sets
+ * `patchReload: "startup"`, so a layer list edited under a running terminal is
+ * read at the next launch and not before.
+ * @module moqi-tui/plugins
+ */
+/** The layer every profile composes first; nothing else works without it. */
+export declare const BASE_BUNDLE = "@deepseek-ai/dsh-base";
+/** This app's own package, as the profile's dependency list spells it. */
+export declare const APP_PACKAGE = "moqi-tui";
+/**
+ * The identifier this package used immediately before `moqi-tui`.
+ *
+ * A profile installed under the old name still lists it, and the app has to
+ * keep recognizing its own bundle as protected — otherwise the plugin pane
+ * offers to disable the terminal it is running inside. npm rejected the bare
+ * `moqi` as too close to existing packages, so the published name grew a
+ * suffix while the command stayed `moqi`.
+ */
+export declare const LEGACY_APP_PACKAGE = "moqi";
+/**
+ * Packages the picker lists but refuses to change.
+ *
+ * Disabling the base layer leaves a profile with no agent, and disabling this
+ * app removes the very screen the command was typed on — in both cases the
+ * only way back is to hand-edit JSON, so the app does not offer the rope.
+ */
+export declare const PROTECTED_PACKAGES: readonly string[];
+/** The package manager profiles are installed with. */
+export declare const PACKAGE_MANAGER = "pnpm";
+/** The `dsh.profile` section of a profile manifest. */
+export interface ProfileSection {
+    /** The ordered layer stack, by package name. */
+    bundles?: string[];
+    /** When the launcher re-reads the user patch file; this bundle sets `startup`. */
+    patchReload?: string;
+    /** Anything else the Harness writes there, preserved on the way back out. */
+    [key: string]: unknown;
+}
+/** The `dsh` section of a profile manifest. */
+export interface DshSection {
+    profile?: ProfileSection;
+    /** Anything else the Harness writes there, preserved on the way back out. */
+    [key: string]: unknown;
+}
+/**
+ * A profile's `package.json`, as far as this app cares.
+ *
+ * The index signature is load-bearing rather than lazy typing: the manifest is
+ * the user's file and carries fields this app has no business knowing about,
+ * and a rewrite that dropped them would be a silent data loss.
+ */
+export interface ProfileManifest {
+    dependencies?: Record<string, string>;
+    dsh?: DshSection;
+    [key: string]: unknown;
+}
+/** One package of the active profile, as the picker shows it. */
+export interface PluginEntry {
+    /** The package name, exactly as the manifest spells it. */
+    name: string;
+    /** The dependency spec it was installed from; empty for an in-box layer. */
+    spec: string;
+    /** Whether the profile installed it, as opposed to inheriting it in-box. */
+    installed: boolean;
+    /** Whether it is in `dsh.profile.bundles`, i.e. composed into the app. */
+    enabled: boolean;
+    /** Whether this app refuses to change it; see {@link PROTECTED_PACKAGES}. */
+    protected: boolean;
+}
+/** The outcome of an edit to the layer stack. */
+export interface BundleEdit {
+    /** The manifest to write back; the original when nothing moved. */
+    manifest: ProfileManifest;
+    /** Whether the layer stack actually changed. */
+    changed: boolean;
+    /** Why it did not, in a form the status line can print; empty when it did. */
+    reason: string;
+}
+/** A package name, with whatever version suffix came with it. */
+export interface PackageRequest {
+    /** The bare package name, without a version. */
+    name: string;
+    /** The single argument handed to the package manager. */
+    spec: string;
+}
+/** Either a package the app is willing to install, or why it is not. */
+export type PackageRequestResult = {
+    ok: true;
+    request: PackageRequest;
+} | {
+    ok: false;
+    reason: string;
+};
+/** How a package-manager run turned out. */
+export interface PackageManagerRun {
+    ok: boolean;
+    /** One line for the status bar: the manager's own last word, or the failure. */
+    message: string;
+}
+/** Whether this app declines to enable or disable a package. */
+export declare function isProtected(packageName: string): boolean;
+/** Where a profile of this name lives under a given Harness home. */
+export declare function resolveProfileDir(profileName: string, dshHome: string): string;
+/**
+ * Which profile this process booted, read back off the launcher's own argv.
+ *
+ * The launcher strips `--profile` before the plugin tree mounts and hands the
+ * app only what followed it, so `ctx.cmdlineArgs` cannot answer this and no
+ * environment variable carries it either. `process.argv` is untouched, though,
+ * and the flag is still sitting in it.
+ * @param argv - a launcher command line; `process.argv` by default.
+ * @returns the profile name, or undefined when the app was not launched that way.
+ */
+export declare function activeProfileName(argv?: readonly string[]): string | undefined;
+/**
+ * Read a profile's manifest, or nothing at all.
+ *
+ * A profile directory that is missing, unreadable, or holding something other
+ * than a JSON object is reported as "no plugins" rather than as an error: the
+ * app has to keep running on a home it cannot read, and a broken manifest is
+ * not something the terminal can fix anyway.
+ * @param dir - the profile directory from {@link resolveProfileDir}.
+ */
+export declare function readProfileManifest(dir: string): ProfileManifest | undefined;
+/**
+ * Write a profile's manifest back.
+ *
+ * Two-space JSON with a trailing newline, which is what both the Harness's own
+ * `writeProfileManifest` and this repo's install script emit — matching them
+ * keeps an app-side edit out of the diff a user takes of their own profile.
+ * @param dir - the profile directory from {@link resolveProfileDir}.
+ * @param manifest - the manifest value to persist.
+ */
+export declare function writeProfileManifest(dir: string, manifest: ProfileManifest): void;
+/**
+ * Every package of a profile, enabled ones first in composition order.
+ *
+ * The two lists are unioned rather than intersected because each holds names
+ * the other does not: an in-box layer like the base bundle is composed without
+ * ever being a dependency, and a package can be installed with no layer of its
+ * own. Enabled rows keep their `bundles` order, since that order is what the
+ * launcher applies; the rest are alphabetical, having no order to preserve.
+ * @param manifest - a parsed manifest, or undefined for an unreadable profile.
+ */
+export declare function listPlugins(manifest: ProfileManifest | undefined): PluginEntry[];
+/** Whether a package is currently composed into the app. */
+export declare function isPluginEnabled(manifest: ProfileManifest | undefined, packageName: string): boolean;
+/**
+ * Add a package to the layer stack, or take it out of it.
+ *
+ * Enabling appends. Patch layers compose in order and the last one to touch a
+ * row wins, so a plugin somebody just turned on should be able to override
+ * what was already there rather than be overridden by it. The base layer is
+ * then pulled back to the front, because everything else patches over it.
+ *
+ * Nothing is installed or deleted here — the package stays exactly where the
+ * package manager left it, and only the composed stack moves.
+ * @param manifest - the profile manifest to edit.
+ * @param packageName - the dependency to enable or disable.
+ * @param enabled - the membership wanted.
+ * @returns the manifest to write, or the original plus the reason it did not move.
+ */
+export declare function setPluginEnabled(manifest: ProfileManifest | undefined, packageName: string, enabled: boolean): BundleEdit;
+/**
+ * Drop a package from the layer stack whatever its protection, for use on the
+ * way to removing it from disk.
+ *
+ * A name left in `dsh.profile.bundles` after its package is gone is not a
+ * cosmetic leftover: the launcher fails loud on a listed bundle it cannot
+ * resolve, so the profile would stop booting. The stack is therefore edited
+ * first and the package manager run second — an interrupted removal then
+ * leaves a package that is merely disabled, which still starts.
+ * @param manifest - the profile manifest to edit.
+ * @param packageName - the dependency about to be removed.
+ */
+export declare function forgetPlugin(manifest: ProfileManifest | undefined, packageName: string): BundleEdit;
+/**
+ * Decide whether a typed string may be handed to the package manager.
+ *
+ * There is no registry search behind this app, so the string is whatever
+ * somebody typed, and it becomes one argument of a spawned process. The
+ * grammar is therefore checked rather than escaped: a name that is not a name
+ * is refused with a reason instead of being quoted and hoped about.
+ * @param input - the raw `/plugins add` argument.
+ */
+export declare function parsePackageRequest(input: string): PackageRequestResult;
+/**
+ * Run the package manager in a profile directory.
+ *
+ * pnpm and not npm: a profile's dependency on a local checkout is a `link:`
+ * spec, which npm rewrites into its own idea of a link and then loses on the
+ * next install — so the Harness installs profiles with pnpm and this app has
+ * to agree with it or it would quietly break the very profile it is editing.
+ *
+ * The run never throws and never reaches the terminal: output is piped, not
+ * inherited, because the app owns the alternate screen and a package manager's
+ * progress bars drawn into it would corrupt the frame. A failure comes back as
+ * a line for the status bar.
+ * @param dir - the profile directory to run in.
+ * @param args - the manager's arguments, already validated.
+ */
+export declare function runPackageManager(dir: string, args: readonly string[]): Promise<PackageManagerRun>;

package/lib/types/presence.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Publishing what this device is doing, for the fleet overview.
+ *
+ * Each open session gets one small JSON file under `$DSH_HOME/tui-presence`,
+ * refreshed on a heartbeat and deleted on exit. The file's age is the liveness
+ * signal — `session.lock` in the session store is not, because it is an empty
+ * flock target that outlives the process that made it.
+ *
+ * Nothing here listens on a port. The records are ordinary files, read by
+ * another device over SSH, so the fleet overview adds no network surface and
+ * no credentials of its own.
+ * @module
+ */
+import { type PresenceRecord, type PresenceStatus } from './tui/fleet.ts';
+/** Directory holding this device's presence records. */
+export declare function presenceDir(dshHome: string): string;
+/** What the app tells the publisher about one session. */
+export interface PresenceInput {
+    sessionId: string;
+    title: string;
+    status: PresenceStatus;
+    model?: string;
+    cwd?: string;
+}
+/**
+ * Writes and refreshes this device's presence records.
+ *
+ * The publisher is deliberately forgiving: a read-only or missing home must
+ * degrade to publishing nothing, never to failing a turn. The overview is a
+ * convenience, and a device that cannot publish simply does not appear.
+ */
+export declare class PresencePublisher {
+    private readonly dir;
+    private readonly host;
+    private readonly owned;
+    private timer;
+    private snapshot;
+    private disabled;
+    constructor(dshHome: string, host?: string);
+    /** Begin heartbeating. `intervalMs` must be well under the stale threshold. */
+    start(intervalMs?: number): void;
+    /** Publish the current set of sessions, replacing whatever was there. */
+    publish(sessions: readonly PresenceInput[]): void;
+    /** Remove every record this process published. Safe to call repeatedly. */
+    stop(): void;
+}
+/** Read every presence record in a directory, skipping anything malformed. */
+export declare function readPresenceDir(dir: string): PresenceRecord[];

package/lib/types/rename.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `/rename` decided before any service is touched.
+ *
+ * The command has two outcomes — pin a user title or regenerate the automatic
+ * one — and which one applies depends only on the text after the command
+ * name. Deciding here keeps `index.ts` down to wiring, so the suite can cover
+ * every branch without a Harness behind it.
+ *
+ * @module moqi-tui/rename
+ */
+/** What `/rename <request>` should do. */
+export type RenamePlan = {
+    kind: 'pin';
+    title: string;
+} | {
+    kind: 'refresh';
+};
+/**
+ * Classify one `/rename` request. Whitespace folds to single spaces — a
+ * session name is one line — surrounding space is dropped, and a request that
+ * says nothing asks for the automatic title to be regenerated (the service's
+ * documented unpin) rather than erroring on a stray space.
+ */
+export declare function planRename(request: string): RenamePlan;
+/**
+ * Read the title a `session/title` snapshot carries, defensively: the value
+ * crosses the plugin boundary from a service this build may shade, so nothing
+ * is assumed beyond "an object with a non-empty string `title`".
+ *
+ * @returns the snapshot's title, or `undefined` when it carries none.
+ */
+export declare function snapshotTitle(snapshot: unknown): string | undefined;

package/lib/types/rewind.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Rewind and fork arithmetic over a session log.
+ *
+ * A fork must be a *balanced completed-turn prefix*: contiguous from seq 0,
+ * ending between turns, with no open turn, step, or dangling tool call. This
+ * module finds those boundaries from the event types alone, so the rules are
+ * testable without a live session.
+ * @module
+ */
+/** The little bit of an event this module needs, plus its message payload. */
+export interface MessageEventLike extends LogEventLike {
+    data?: {
+        message?: {
+            content?: unknown;
+        };
+    };
+}
+/** The little bit of an event this module needs. */
+export interface LogEventLike {
+    seq: number;
+    type: string;
+}
+/** One human prompt in the log, with the turn it opened. */
+export interface UserTurn {
+    /** Seq of the `user/message` event. */
+    seq: number;
+    /** The prompt text, for the picker. */
+    text: string;
+    /** Seq of the `turn/start` that opened the containing turn. */
+    turnStartSeq: number | undefined;
+}
+/**
+ * Every human prompt in log order, each remembering the turn that carried it.
+ *
+ * A `user/message` outside any turn (a resumed or repaired log) keeps
+ * `turnStartSeq: undefined`, which makes it unrewindable rather than guessed.
+ */
+export declare function projectUserTurns(events: readonly MessageEventLike[]): UserTurn[];
+/**
+ * Where to cut the log to rewind to a chosen prompt.
+ *
+ * Rewinding means "take me back to just before this prompt was sent", so the
+ * cut is the start of the turn that contains it — everything before that turn
+ * is the seed, and the prompt itself returns to the composer.
+ *
+ * @returns the exclusive cut offset and the prompt text, or `undefined` when
+ *   the rewind is impossible: no turn boundary, or the boundary is the very
+ *   start of the log (rewinding past the first message leaves nothing).
+ */
+export declare function rewindTarget(turns: readonly UserTurn[], chosenIndex: number): {
+    cutSeq: number;
+    text: string;
+} | undefined;
+/**
+ * The exclusive cut offset for a full fork: after the last completed turn.
+ *
+ * A fork of an idle session keeps every completed turn; a log with an open
+ * turn at the end is cut back to the last `turn/end`, because a fork may not
+ * inherit a half-finished turn.
+ *
+ * @returns the exclusive offset, or 0 when there is no completed turn yet.
+ */
+export declare function forkCut(events: readonly LogEventLike[], endSeq: number): number;
+/**
+ * The lineage of a session id inside a set of known sessions, oldest ancestor
+ * first, for `/tree`.
+ */
+export declare function lineage(sessions: readonly {
+    id: string;
+    parentSession?: string;
+    title?: string;
+}[], id: string): {
+    id: string;
+    title?: string;
+}[];

package/lib/types/sessions-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the JSONL session store keeps sessions on disk, and how to remove one.
+ *
+ * The harness has no public delete API: storage is append-only by design and
+ * the query index reconciles against the filesystem, dropping entries whose
+ * session directory has gone. Deleting the directory is therefore the whole
+ * operation — and the reason a session stays stored until the user asks.
+ *
+ * The path encoding here mirrors `dsh-session-persistence-jsonl` exactly:
+ * `$DSH_HOME/sessions/<projectKey(cwd)>/<encodeSegment(id)>/`.
+ * @module
+ */
+/** The sessions root: `$DSH_HOME/sessions`, defaulting to `~/.dsh/sessions`. */
+export declare function sessionsRoot(): string;
+/**
+ * Encode one path segment: safe characters pass through, everything else
+ * becomes `~XXXX` with the code unit in upper-case hex. `.`
+ * and `..` are always escaped so a session id can never traverse.
+ */
+export declare function encodeSegment(raw: string): string;
+/**
+ * The readable directory key for a project path. Separators fold to `-`, the
+ * result is bounded to a filesystem component, and the name always carries the
+ * leading `--`/trailing `--` fence so a project directory is recognizable.
+ */
+export declare function projectKey(cwd: string): string;
+/** The directory one stored session owns, given the cwd it was created with. */
+export declare function storedSessionDir(cwd: string, id: string): string;
+/**
+ * Find a session's directory by id alone, scanning the project directories.
+ *
+ * The picker knows an id but not always the cwd it was created under, and the
+ * encoded id segment is unique across projects, so a scan is both correct and
+ * cheap: one `readdir` of the root plus one per project directory.
+ */
+export declare function findStoredSessionDir(id: string): Promise<string | undefined>;
+/**
+ * Delete a stored session from disk. The query index notices on its next
+ * reconciliation pass, so the session disappears from `/resume` too.
+ *
+ * @returns `true` when something was removed, `false` when no such session
+ *   was stored.
+ */
+export declare function deleteStoredSession(cwd: string, id: string): Promise<boolean>;
+/** Delete a session found by id through {@link findStoredSessionDir}. */
+export declare function deleteStoredSessionDir(dir: string): Promise<boolean>;

package/lib/types/startup.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The terminal app's command-line provider.
+ *
+ * It parses this app's own flags out of the shared immutable cmdline snapshot
+ * and publishes them as a service, so the app row can consume them lazily —
+ * the same shape the shipped headless bundle uses.
+ * @module moqi-tui/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "tui-startup";
+/** Services required before the flags can be resolved. */
+export declare const inject: string[];
+/** Service key provided by this plugin and injected by the app row. */
+export declare const TUI_STARTUP_SERVICE = "tuiStartup";
+/** What the app row reads from {@link TUI_STARTUP_SERVICE}. */
+export interface TuiStartupValues {
+    /** Exact session to adopt on launch; absent starts a fresh one. */
+    resumeSessionId: string | undefined;
+    /** Model override for this run; absent uses the profile's default. */
+    model: string | undefined;
+    /** Whether reasoning output starts visible. */
+    thinking: boolean;
+    /** Context budget override; absent means use the model's own capacity. */
+    contextLimit: number | undefined;
+    /** Report mouse events so the wheel scrolls; off by default. */
+    mouse: boolean;
+    /** Ring the bell when a session's turn finishes; on by default. */
+    bell: boolean;
+    /** Bring back the sessions that were open at the last exit; on by default. */
+    restore: boolean;
+    /** Devices to include in the fleet overview; empty means this one only. */
+    peers: string[];
+    /** Whisper weights for push-to-talk; absent falls back to the default search. */
+    voiceModel: string | undefined;
+    /** Whisper executable for push-to-talk; absent looks for the known names. */
+    voiceBin: string | undefined;
+    /** Peer profile `/dispatch` boots; the shipped `headless` one by default. */
+    dispatchProfile: string | undefined;
+}
+/**
+ * Parse this app's flags and provide them as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/tui/atfile.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `@` file completion: token detection, fuzzy filtering, and the inline menu.
+ *
+ * Like the rest of `tui/`, this module knows nothing about the terminal or the
+ * Harness — it turns composer text plus a candidate list into a menu state, so
+ * the interaction rules stay testable on their own.
+ * @module
+ */
+/** Whether a path names an image the composer can stage as an attachment. */
+export declare function isImagePath(path: string): boolean;
+/** Directories a workspace walk never descends into. */
+export declare const SKIP_DIRECTORIES: Set<string>;
+/**
+ * The `@` token being typed at the cursor, if any.
+ *
+ * A token counts only when the `@` sits at a token boundary — the start of
+ * the text or right after whitespace — so an email address in prose
+ * (`user@host`) or a social handle never opens the menu. The query is what
+ * follows the `@` up to the cursor; a query containing `/` is path-shaped and
+ * lists one directory rather than fuzzy-matching the whole workspace.
+ */
+export declare function activeAtToken(text: string, cursor: number): {
+    query: string;
+    start: number;
+} | undefined;
+/**
+ * Whether a query names a directory rather than fuzzy-matching the workspace:
+ * anything containing a separator (`src/`, `../lib`, `~/notes`).
+ */
+export declare function isPathShaped(query: string): boolean;
+export interface AtMatch {
+    /** Workspace-relative path, or a directory-relative one for path queries. */
+    path: string;
+    /** True when picking this entry descends into a directory. */
+    directory: boolean;
+}
+/**
+ * Rank candidates for a plain (non-path-shaped) query.
+ *
+ * Every path must contain the query as a subsequence, the same filter the
+ * model picker uses; shallower and shorter paths win so `state` finds
+ * `src/tui/state.ts` before `tests/theme-state-fixture.ts`.
+ */
+export declare function filterFiles(query: string, paths: readonly string[], limit?: number): AtMatch[];
+/**
+ * The inline completion menu over the active `@` token.
+ *
+ * It follows the composer rather than owning the keyboard: typing keeps
+ * filtering, `↑`/`↓` (or ctrl+p/n) move, `tab`/`enter` accept, `esc` dismisses
+ * — and only the menu closes, not anything layered beneath it.
+ */
+export declare class AtMenu {
+    open: boolean;
+    matches: AtMatch[];
+    selected: number;
+    /** The token the menu is showing matches for; a change reopens it. */
+    query: string;
+    /** Recompute from the active token. `dismissed` is the token the user pressed esc on. */
+    update(token: {
+        query: string;
+        start: number;
+    } | undefined, candidates: readonly AtMatch[], dismissed: string | undefined): void;
+    move(delta: number): void;
+    current(): AtMatch | undefined;
+    close(): void;
+}
+/**
+ * Replace the token a menu pick stands for with the accepted path.
+ *
+ * Returns the new composer text and cursor: the `@` and everything typed
+ * after it up to the cursor give way to the path plus a trailing space, so
+ * the next word starts cleanly. Whatever followed the cursor stays.
+ */
+export declare function acceptToken(text: string, cursor: number, token: {
+    start: number;
+}, path: string): {
+    text: string;
+    cursor: number;
+};
+/**
+ * Extract `[Image #N name]` tokens from a draft.
+ *
+ * Returns the text with the tokens stripped and the numbers in order, so the
+ * sender can pair them with staged attachment references. A token the user
+ * deleted leaves no trace: unmatched staged images are dropped at send.
+ */
+export declare function extractImageTokens(text: string): {
+    text: string;
+    numbers: number[];
+};