moqi-tui 0.2.0

package/lib/presence.js

@@ -0,0 +1,144 @@
+/**
+ * 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 { hostname } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { isPresenceRecord, PRESENCE_VERSION, } from "./tui/fleet.js";
+/** Directory holding this device's presence records. */
+export function presenceDir(dshHome) {
+    return join(dshHome, 'tui-presence');
+}
+/**
+ * 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 class PresencePublisher {
+    dir;
+    host;
+    owned = new Set();
+    timer;
+    snapshot = [];
+    disabled = false;
+    constructor(dshHome, host = hostname()) {
+        this.dir = presenceDir(dshHome);
+        this.host = host;
+    }
+    /** Begin heartbeating. `intervalMs` must be well under the stale threshold. */
+    start(intervalMs = 5000) {
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => {
+            this.publish(this.snapshot);
+        }, intervalMs);
+        // A heartbeat must not be the reason the process stays alive.
+        this.timer.unref?.();
+    }
+    /** Publish the current set of sessions, replacing whatever was there. */
+    publish(sessions) {
+        if (this.disabled)
+            return;
+        this.snapshot = sessions;
+        try {
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            // A home that cannot be written is a device that does not appear.
+            this.disabled = true;
+            return;
+        }
+        const now = Date.now();
+        const live = new Set();
+        for (const session of sessions) {
+            const record = {
+                v: PRESENCE_VERSION,
+                host: this.host,
+                pid: process.pid,
+                sessionId: session.sessionId,
+                title: session.title,
+                status: session.status,
+                model: session.model,
+                cwd: session.cwd,
+                updatedAt: now,
+            };
+            const path = join(this.dir, `${safeName(session.sessionId)}.json`);
+            try {
+                writeFileSync(path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+                live.add(path);
+                this.owned.add(path);
+            }
+            catch {
+                // Skip this record; the rest of the fleet view still works.
+            }
+        }
+        // Drop records for sessions this process has closed.
+        for (const path of [...this.owned]) {
+            if (live.has(path))
+                continue;
+            this.owned.delete(path);
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                // Best effort: a leftover record ages out as stale.
+            }
+        }
+    }
+    /** Remove every record this process published. Safe to call repeatedly. */
+    stop() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        for (const path of this.owned) {
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                // Nothing to do; the record ages out.
+            }
+        }
+        this.owned.clear();
+    }
+}
+/** Read every presence record in a directory, skipping anything malformed. */
+export function readPresenceDir(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+            if (isPresenceRecord(parsed))
+                records.push(parsed);
+        }
+        catch {
+            // A half-written or foreign file is not a reason to lose the rest.
+        }
+    }
+    return records;
+}
+/** Keep a session id usable as a filename. */
+function safeName(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+}

package/lib/rename.js

@@ -0,0 +1,35 @@
+/**
+ * `/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
+ */
+/** The tab-label budget: the automatic first-prompt title uses the same cap. */
+const TITLE_LIMIT = 60;
+/**
+ * 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 function planRename(request) {
+    const title = request.trim().replace(/\s+/g, ' ');
+    if (title === '')
+        return { kind: 'refresh' };
+    return { kind: 'pin', title: title.slice(0, TITLE_LIMIT) };
+}
+/**
+ * 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 function snapshotTitle(snapshot) {
+    const title = snapshot?.title;
+    return typeof title === 'string' && title.trim() !== '' ? title : undefined;
+}

package/lib/rewind.js

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+/** Text of one model-visible message event, or `''` when it carries none. */
+function textOf(event) {
+    const blocks = event.data?.message?.content;
+    if (!Array.isArray(blocks))
+        return '';
+    return blocks
+        .filter((block) => {
+        const candidate = block;
+        return candidate.type === 'text' && typeof candidate.text === 'string';
+    })
+        .map((block) => block.text)
+        .join('');
+}
+/**
+ * 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 function projectUserTurns(events) {
+    const turns = [];
+    let currentTurnStart;
+    for (const event of events) {
+        if (event.type === 'turn/start')
+            currentTurnStart = event.seq;
+        else if (event.type === 'user/message') {
+            const text = textOf(event);
+            if (text.trim() !== '')
+                turns.push({ seq: event.seq, text, turnStartSeq: currentTurnStart });
+        }
+    }
+    return turns;
+}
+/**
+ * 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 function rewindTarget(turns, chosenIndex) {
+    const turn = turns[chosenIndex];
+    if (turn === undefined || turn.turnStartSeq === undefined)
+        return undefined;
+    if (turn.turnStartSeq <= 0)
+        return undefined;
+    return { cutSeq: turn.turnStartSeq, text: turn.text };
+}
+/**
+ * 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 function forkCut(events, endSeq) {
+    for (let index = Math.min(endSeq, events.length) - 1; index >= 0; index -= 1) {
+        if (events[index]?.type === 'turn/end')
+            return index + 1;
+    }
+    return 0;
+}
+/**
+ * The lineage of a session id inside a set of known sessions, oldest ancestor
+ * first, for `/tree`.
+ */
+export function lineage(sessions, id) {
+    const byId = new Map(sessions.map((session) => [session.id, session]));
+    const path = [];
+    let current = byId.get(id);
+    const seen = new Set();
+    while (current !== undefined && !seen.has(current.id)) {
+        seen.add(current.id);
+        path.unshift({ id: current.id, title: current.title });
+        const parent = current.parentSession;
+        current = parent === undefined ? undefined : byId.get(parent);
+    }
+    return path;
+}

package/lib/sessions-store.js

@@ -0,0 +1,134 @@
+/**
+ * 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
+ */
+import { readdir, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The sessions root: `$DSH_HOME/sessions`, defaulting to `~/.dsh/sessions`. */
+export function sessionsRoot() {
+    const home = process.env['DSH_HOME'] ?? join(homedir(), '.dsh');
+    return join(home, 'sessions');
+}
+/**
+ * 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 function encodeSegment(raw) {
+    if (raw.length === 0)
+        throw new Error('cannot encode an empty path segment');
+    if (raw === '.')
+        return '~002E';
+    if (raw === '..')
+        return '~002E~002E';
+    let out = '';
+    for (let index = 0; index < raw.length; index += 1) {
+        const code = raw.charCodeAt(index);
+        const char = String.fromCharCode(code);
+        if (char !== '~' && /^[A-Za-z0-9._-]$/.test(char))
+            out += char;
+        else
+            out += `~${code.toString(16).toUpperCase().padStart(4, '0')}`;
+    }
+    return out;
+}
+/**
+ * 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 function projectKey(cwd) {
+    if (cwd.length === 0)
+        throw new Error('cannot encode an empty project path');
+    let readable = '';
+    let separatorRun = false;
+    for (let index = 0; index < cwd.length; index += 1) {
+        const code = cwd.charCodeAt(index);
+        const char = String.fromCharCode(code);
+        if (char === '/' || char === '\\' || char === ':') {
+            if (!separatorRun)
+                readable += '-';
+            separatorRun = true;
+        }
+        else if (char !== '~' && /^[A-Za-z0-9._-]$/.test(char)) {
+            readable += char;
+            separatorRun = false;
+        }
+        else {
+            readable += `~${code.toString(16).toUpperCase().padStart(4, '0')}`;
+            separatorRun = false;
+        }
+    }
+    return `--${(readable.replace(/^-+/, '') || 'root').slice(0, 251)}--`;
+}
+/** The directory one stored session owns, given the cwd it was created with. */
+export function storedSessionDir(cwd, id) {
+    return join(sessionsRoot(), projectKey(cwd), encodeSegment(id));
+}
+/**
+ * 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 async function findStoredSessionDir(id) {
+    const segment = encodeSegment(id);
+    const root = sessionsRoot();
+    let projects;
+    try {
+        projects = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return undefined; // no sessions root: nothing is stored
+    }
+    for (const entry of projects) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = join(root, entry.name, segment);
+        try {
+            const contents = await readdir(candidate);
+            if (contents.length > 0)
+                return candidate;
+        }
+        catch {
+            // Not in this project directory; keep scanning.
+        }
+    }
+    return 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 async function deleteStoredSession(cwd, id) {
+    return removeDir(storedSessionDir(cwd, id));
+}
+/** Delete a session found by id through {@link findStoredSessionDir}. */
+export async function deleteStoredSessionDir(dir) {
+    return removeDir(dir);
+}
+async function removeDir(dir) {
+    try {
+        await rm(dir, { recursive: true });
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}

package/lib/startup.js

@@ -0,0 +1,92 @@
+/**
+ * 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 { Command } from 'commander';
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline';
+import { VERSION } from "./version.js";
+/** Stable Cordis plugin name. */
+export const name = 'tui-startup';
+/** Services required before the flags can be resolved. */
+export const inject = ['cmdlineArgs'];
+/** Service key provided by this plugin and injected by the app row. */
+export const TUI_STARTUP_SERVICE = 'tuiStartup';
+/** This app's command grammar, help text, and examples. */
+function tuiCommand() {
+    return new Command()
+        .name('dsh --profile tui')
+        .description('An interactive terminal client for the Harness.')
+        .version(VERSION, '--version', 'print the app version and exit')
+        .helpOption('-h, --help', 'show this help')
+        .option('--resume <id>', 'open the persisted session with this id instead of a new one')
+        .option('--model <name>', 'model to select for this run')
+        .option('--thinking', 'start with reasoning output visible')
+        .option('--context-limit <tokens>', "context budget override; default is the model's own capacity")
+        .option('--mouse', 'report mouse events so the wheel scrolls (disables terminal text selection)')
+        .option('--no-bell', 'stay silent when a session finishes instead of ringing the terminal bell')
+        .option('--no-restore', 'start with one empty session instead of reopening the last ones')
+        .option('--peer <host>', 'device to include in the fleet overview; repeatable, anything ssh accepts', (value, previous) => [...previous, value], [])
+        .option('--voice-model <path>', 'whisper.cpp weights for push-to-talk dictation (ctrl+v)')
+        .option('--voice-bin <path>', 'whisper.cpp executable to transcribe with; default searches PATH')
+        .option('--dispatch-profile <name>', 'profile /dispatch boots on a peer; headless by default')
+        .addHelpText('after', `
+Examples:
+  dsh --profile tui                      start a new session
+  dsh --profile tui --resume session-...  reopen an existing session
+  dsh --profile tui --thinking            show the reasoner's chain of thought
+  dsh --profile tui --peer laptop         include another device in ctrl+f
+  dsh --profile tui --no-restore          start clean instead of reopening tabs
+
+Inside the app, type / for the command palette; press ctrl+c for the sessions
+menu and ctrl+c again within 1.5s to quit.
+`);
+}
+/**
+ * Parse this app's flags and provide them as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ */
+export function apply(ctx) {
+    const program = tuiCommand();
+    program.action(() => {
+        const options = program.opts();
+        if (options.resume !== undefined && options.resume.trim() === '') {
+            program.error('error: --resume requires a non-empty session id');
+        }
+        // Left undefined, the app asks the provider for the model's real capacity.
+        let contextLimit;
+        const fromEnvironment = process.env['MOQI_CONTEXT_LIMIT'];
+        if (fromEnvironment !== undefined && /^\d+$/.test(fromEnvironment)) {
+            contextLimit = Number.parseInt(fromEnvironment, 10);
+        }
+        if (options.contextLimit !== undefined) {
+            if (!/^\d+$/.test(options.contextLimit)) {
+                program.error('error: --context-limit requires a positive integer');
+            }
+            contextLimit = Number.parseInt(options.contextLimit, 10);
+        }
+        if (contextLimit !== undefined && contextLimit <= 0) {
+            program.error('error: --context-limit must be greater than zero');
+        }
+        ctx.provide(TUI_STARTUP_SERVICE, {
+            resumeSessionId: options.resume,
+            model: options.model,
+            thinking: options.thinking === true,
+            contextLimit,
+            mouse: options.mouse === true,
+            // commander maps --no-bell to bell: false and leaves it true otherwise.
+            bell: options.bell !== false,
+            restore: options.restore !== false,
+            peers: options.peer ?? [],
+            // Left undefined the app reads MOQI_WHISPER_MODEL / _BIN, then falls
+            // back to its own search, so passing nothing here is the normal case.
+            voiceModel: options.voiceModel,
+            voiceBin: options.voiceBin,
+            dispatchProfile: options.dispatchProfile,
+        });
+    });
+    parseCmdline(ctx, program);
+}

package/lib/tui/atfile.js

@@ -0,0 +1,154 @@
+/**
+ * `@` 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
+ */
+import { fuzzyMatch } from "./state.js";
+/** Raster formats the Harness attachment service admits. */
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+/** Whether a path names an image the composer can stage as an attachment. */
+export function isImagePath(path) {
+    const dot = path.lastIndexOf('.');
+    if (dot === -1)
+        return false;
+    const extension = path.slice(dot).toLowerCase();
+    return IMAGE_EXTENSIONS.includes(extension);
+}
+/** Directories a workspace walk never descends into. */
+export const SKIP_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    '.hg',
+    '.svn',
+    'dist',
+    'lib',
+    'build',
+    'out',
+    'coverage',
+    '.cache',
+    '.venv',
+    '__pycache__',
+    '.DS_Store',
+]);
+/**
+ * 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 function activeAtToken(text, cursor) {
+    // Walk back over the token the cursor sits in.
+    let start = cursor;
+    while (start > 0 && !/[\s]/.test(text[start - 1] ?? ''))
+        start -= 1;
+    if (text[start] !== '@')
+        return undefined;
+    const query = text.slice(start + 1, cursor);
+    // A space has been typed after the token: the user has moved on.
+    if (/[\n]/.test(query))
+        return undefined;
+    return { query, start };
+}
+/**
+ * Whether a query names a directory rather than fuzzy-matching the workspace:
+ * anything containing a separator (`src/`, `../lib`, `~/notes`).
+ */
+export function isPathShaped(query) {
+    return query.includes('/');
+}
+/**
+ * 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 function filterFiles(query, paths, limit = 200) {
+    const normalized = query.toLowerCase();
+    const scored = [];
+    for (const path of paths) {
+        if (!fuzzyMatch(normalized, path.toLowerCase()))
+            continue;
+        const depth = path.split('/').length;
+        scored.push({ path, score: depth * 1000 + path.length });
+    }
+    scored.sort((a, b) => a.score - b.score);
+    return scored.slice(0, limit).map(({ path }) => ({ path, directory: false }));
+}
+/**
+ * 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 class AtMenu {
+    open = false;
+    matches = [];
+    selected = 0;
+    /** The token the menu is showing matches for; a change reopens it. */
+    query = '';
+    /** Recompute from the active token. `dismissed` is the token the user pressed esc on. */
+    update(token, candidates, dismissed) {
+        if (token === undefined || token.query === dismissed) {
+            this.close();
+            return;
+        }
+        this.query = token.query;
+        this.matches = [...candidates];
+        this.selected = 0;
+        this.open = this.matches.length > 0;
+    }
+    move(delta) {
+        if (!this.open || this.matches.length === 0)
+            return;
+        this.selected = Math.min(Math.max(this.selected + delta, 0), this.matches.length - 1);
+    }
+    current() {
+        if (!this.open)
+            return undefined;
+        return this.matches[this.selected];
+    }
+    close() {
+        this.open = false;
+        this.matches = [];
+        this.selected = 0;
+        this.query = '';
+    }
+}
+/**
+ * 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 function acceptToken(text, cursor, token, path) {
+    const before = text.slice(0, token.start);
+    const after = text.slice(cursor);
+    const inserted = `${path} `;
+    return { text: before + inserted + after, cursor: before.length + inserted.length };
+}
+/**
+ * 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 function extractImageTokens(text) {
+    const numbers = [];
+    const stripped = text.replace(/\[Image #(\d+)[^\]]*\]/g, (whole, digits) => {
+        numbers.push(Number.parseInt(digits, 10));
+        return '';
+    });
+    // Tidy the doubled spaces removal can leave behind.
+    const cleaned = stripped.replace(/ {2,}/g, ' ').replace(/^[ \t]+|[ \t]+$/gm, '');
+    return { text: cleaned, numbers };
+}