@askdkc/dsh-cli 0.11.3

package/lib/types/extensions.d.ts

@@ -0,0 +1,18 @@
+export * from './dsh-adapter/extensions.js';
+export { DECISION_HANDLER_TIMEOUT_MS, DECISION_TOTAL_TIMEOUT_MS, normalizeCancelDecision, } from './dsh-adapter/extension-events.js';
+export type { TuiDecisionContext, TuiInputEvent, TuiInputDecision, TuiRewindPromptEvent, TuiRewindMode, TuiRewindPromptDecision, TuiRewindDoneEvent, TuiSessionSwitchEvent, TuiSessionSwitchDecision, TuiSessionSwitchedEvent, TuiCompactEvent, TuiCompactDecision, } from './dsh-adapter/extension-events.js';
+export { DIALOG_DEFAULT_TIMEOUT_MS, INPUT_CELLS, TuiDialogRuntime, TuiDialogStore, } from './dsh-adapter/dialogs.js';
+export type { TuiDialogAnswer, TuiDialogBase, TuiDialogConfirmRequest, TuiDialogInputRequest, TuiDialogSelectOption, TuiDialogSelectRequest, TuiDialogSnapshot, } from './dsh-adapter/dialogs.js';
+export { TuiStatusRuntime, TuiStatusStore } from './dsh-adapter/status.js';
+export type { TuiStatusEntry, TuiStatusViewDescriptor, TuiStatusViewDisposer, TuiStatusViewMaxRows, TuiStatusViewProps, TuiStatusViewUi, } from './dsh-adapter/status.js';
+export type { TerminalImageSource } from './ink/terminal-image.js';
+export { matchShortcut, parseShortcutCombo, TuiShortcutRuntime } from './dsh-adapter/shortcuts.js';
+export type { TuiShortcutKey, TuiShortcutOptions } from './dsh-adapter/shortcuts.js';
+export { TuiRendererRuntime } from './dsh-adapter/renderers.js';
+export type { TuiEntryRenderer, TuiEntryRenderResult } from './dsh-adapter/renderers.js';
+export { TuiToastRuntime } from './dsh-adapter/toast.js';
+export type { TuiToastDelivery, TuiToastOptions, TuiToastSink } from './dsh-adapter/toast.js';
+export { TuiThemeRuntime } from './dsh-adapter/themes.js';
+export type { TuiThemeBase, TuiThemeDescriptor, TuiThemeRegistration, } from './dsh-adapter/themes.js';
+export { DECISION_EVENT_PERMISSIONS } from './dsh-adapter/decision-guard.js';
+//# sourceMappingURL=extensions.d.ts.map

package/lib/types/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/extensions.ts"],"names":[],"mappings":"AAQA,cAAc,6BAA6B,CAAA;AAI3C,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,mCAAmC,CAAA;AAC1C,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GACnB,MAAM,mCAAmC,CAAA;AAI1C,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,gBAAgB,EAChB,cAAc,GACf,MAAM,0BAA0B,CAAA;AACjC,YAAY,EACV,eAAe,EACf,aAAa,EACb,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC1E,YAAY,EACV,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,GAChB,MAAM,yBAAyB,CAAA;AAChC,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAClE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAClG,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAG7F,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA"}

package/lib/types/extensions.js

@@ -0,0 +1,27 @@
+// Re-export shim: the Cordis-backed implementation lives behind the adapter
+// boundary so UI consumers never import official @deepseek-ai/* packages.
+// Plugin authors import the seam types from here
+// (`dsh-cli/extensions`); importing the module also
+// applies the `declare module '@deepseek-ai/cordis'` augmentation for the
+// decision events and the five service properties on Context. In particular,
+// `tuiStatus.registerView()` returns `undefined` when the host refuses a rich
+// registration, or a cleanup-aware disposer when it admits one.
+export * from './dsh-adapter/extensions.js';
+// Decision dispatch is a host/channel operation.  Export only the event
+// vocabulary and safe normalizers; dispatching an arbitrary payload through
+// this module would let a plugin trigger every other plugin's handlers.
+export { DECISION_HANDLER_TIMEOUT_MS, DECISION_TOTAL_TIMEOUT_MS, normalizeCancelDecision, } from './dsh-adapter/extension-events.js';
+// Keep host accessors out of the plugin-facing export. The implementation
+// modules expose them only so the TUI host can wire Chat/channel; exporting
+// them here would let a plugin recover the private queue/store/dispatcher.
+export { DIALOG_DEFAULT_TIMEOUT_MS, INPUT_CELLS, TuiDialogRuntime, TuiDialogStore, } from './dsh-adapter/dialogs.js';
+export { TuiStatusRuntime, TuiStatusStore } from './dsh-adapter/status.js';
+export { matchShortcut, parseShortcutCombo, TuiShortcutRuntime } from './dsh-adapter/shortcuts.js';
+export { TuiRendererRuntime } from './dsh-adapter/renderers.js';
+export { TuiToastRuntime } from './dsh-adapter/toast.js';
+// Runtime themes expose only the registration capability. The host snapshot,
+// resolver and subscription accessor stay behind the adapter boundary.
+export { TuiThemeRuntime } from './dsh-adapter/themes.js';
+// The D-7 permission vocabulary (which grant each decision event needs) is
+// part of the plugin-facing contract too.
+export { DECISION_EVENT_PERMISSIONS } from './dsh-adapter/decision-guard.js';

package/lib/types/force-production-react.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=force-production-react.d.ts.map

package/lib/types/force-production-react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"force-production-react.d.ts","sourceRoot":"","sources":["../../src/force-production-react.ts"],"names":[],"mappings":""}

package/lib/types/force-production-react.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * React-reconciler selects its dev/production build at require time from
+ * NODE_ENV; the dev build records one performance.measure() per render into
+ * an unbounded buffer — the 4 GB long-session OOM (b1e06d8). Every launcher
+ * forces production, but a direct `dsh --profile dsh-tui` boot loads this
+ * plugin without one and silently regressed to the dev build. This module
+ * must stay the FIRST import of the package entry so its body runs before
+ * any module in the plugin graph requires react. `??=` keeps an explicit
+ * environment choice (a debugging session) in control.
+ */
+process.env.NODE_ENV ??= 'production';

package/lib/types/herdr.d.ts

@@ -0,0 +1,28 @@
+import { type ExecFileNoThrowResult } from './utils/execFileNoThrow.js';
+interface HerdrChannel {
+    readonly working: boolean;
+    subscribe(listener: () => void): () => void;
+}
+interface BlockingStore {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): unknown | null;
+}
+type RunCommand = (file: string, args: readonly string[]) => Promise<ExecFileNoThrowResult>;
+export interface HerdrIntegration {
+    settled(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface HerdrIntegrationOptions {
+    readonly channel: HerdrChannel;
+    readonly questions: BlockingStore;
+    readonly approvals: BlockingStore;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly run?: RunCommand;
+    readonly reportTimeoutMs?: number;
+    readonly releaseTimeoutMs?: number;
+    readonly retryDelaysMs?: readonly number[];
+}
+/** Report this TUI's lifecycle to the owning Herdr pane when Herdr launches it. */
+export declare function attachHerdrIntegration(options: HerdrIntegrationOptions): HerdrIntegration | undefined;
+export {};
+//# sourceMappingURL=herdr.d.ts.map

package/lib/types/herdr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr.d.ts","sourceRoot":"","sources":["../../src/herdr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAQxF,UAAU,YAAY;IACpB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C;AAED,UAAU,aAAa;IACrB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,WAAW,IAAI,OAAO,GAAG,IAAI,CAAA;CAC9B;AAED,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAkBD,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,GAAG,SAAS,CAgH9B"}

package/lib/types/herdr.js

@@ -0,0 +1,133 @@
+import { execFileNoThrow } from './utils/execFileNoThrow.js';
+const REPORT_TIMEOUT_MS = 2000;
+const RELEASE_TIMEOUT_MS = 500;
+const RETRY_DELAYS_MS = [100, 250, 500, 1000];
+function withTimeout(promise, timeoutMs) {
+    return new Promise(resolve => {
+        const timer = setTimeout(() => resolve(undefined), timeoutMs);
+        void promise.then(value => {
+            clearTimeout(timer);
+            resolve(value);
+        }, () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        });
+    });
+}
+/** Report this TUI's lifecycle to the owning Herdr pane when Herdr launches it. */
+export function attachHerdrIntegration(options) {
+    const env = options.env ?? process.env;
+    const executable = env.HERDR_BIN_PATH?.trim();
+    const paneId = env.HERDR_PANE_ID?.trim();
+    if (env.HERDR_ENV !== '1' || !executable || !paneId)
+        return undefined;
+    const reportTimeoutMs = options.reportTimeoutMs ?? REPORT_TIMEOUT_MS;
+    const releaseTimeoutMs = options.releaseTimeoutMs ?? RELEASE_TIMEOUT_MS;
+    const retryDelays = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+    const run = options.run ?? ((file, args) => execFileNoThrow(file, args, { timeout: reportTimeoutMs }));
+    const runSafely = (args) => {
+        try {
+            return Promise.resolve(run(executable, args));
+        }
+        catch {
+            return Promise.reject(new Error('Herdr command could not be started'));
+        }
+    };
+    let sequence = Date.now() * 1000;
+    let lastConfirmedReport = '';
+    let disposed = false;
+    let running = false;
+    let wakeDelay;
+    let settledPromise = Promise.resolve();
+    const computeState = () => {
+        const blocked = options.questions.getSnapshot() !== null || options.approvals.getSnapshot() !== null;
+        return { state: blocked ? 'blocked' : options.channel.working ? 'working' : 'idle', blocked };
+    };
+    const waitForRetry = (delayMs) => new Promise(resolve => {
+        const timer = setTimeout(() => {
+            wakeDelay = undefined;
+            resolve();
+        }, delayMs);
+        wakeDelay = () => {
+            clearTimeout(timer);
+            wakeDelay = undefined;
+            resolve();
+        };
+    });
+    const processQueue = async () => {
+        let failedState = '';
+        let attempts = 0;
+        try {
+            while (!disposed) {
+                const { state, blocked } = computeState();
+                if (state === lastConfirmedReport)
+                    break;
+                if (state !== failedState) {
+                    failedState = state;
+                    attempts = 0;
+                }
+                attempts += 1;
+                const result = await withTimeout(runSafely([
+                    'pane', 'report-agent', paneId,
+                    '--source', 'custom:dsh-tui',
+                    '--agent', 'dsh-tui',
+                    '--state', state,
+                    ...(blocked ? ['--message', 'Waiting for user input'] : []),
+                    '--seq', String(++sequence),
+                ]), reportTimeoutMs);
+                if (disposed)
+                    break;
+                if (result?.code === 0) {
+                    lastConfirmedReport = state;
+                    failedState = '';
+                    attempts = 0;
+                    continue;
+                }
+                if (attempts > retryDelays.length)
+                    break;
+                await waitForRetry(retryDelays[attempts - 1] ?? 0);
+            }
+        }
+        finally {
+            running = false;
+        }
+    };
+    const report = () => {
+        if (disposed)
+            return;
+        if (running) {
+            wakeDelay?.();
+            return;
+        }
+        if (computeState().state === lastConfirmedReport)
+            return;
+        running = true;
+        settledPromise = processQueue();
+    };
+    const unsubscribes = [
+        options.channel.subscribe(report),
+        options.questions.subscribe(report),
+        options.approvals.subscribe(report),
+    ];
+    report();
+    let disposePromise;
+    return {
+        settled: () => settledPromise,
+        dispose: () => {
+            if (disposePromise !== undefined)
+                return disposePromise;
+            disposed = true;
+            wakeDelay?.();
+            for (const unsubscribe of unsubscribes)
+                unsubscribe();
+            const release = runSafely([
+                'pane', 'release-agent', paneId,
+                '--source', 'custom:dsh-tui',
+                '--agent', 'dsh-tui',
+                '--seq', String(++sequence),
+            ]);
+            disposePromise = withTimeout(release, releaseTimeoutMs).then(() => undefined);
+            return disposePromise;
+        },
+    };
+}

package/lib/types/history.d.ts

@@ -0,0 +1,39 @@
+/** One persisted input-history entry. */
+export type HistoryEntry = {
+    text: string;
+    /** Unix ms timestamp. */
+    ts: number;
+};
+/**
+ * Entry cap for the persisted history. `↑`/`↓` and the Ctrl+R overlay read
+ * the same file, so both depths come from this one number.
+ */
+export declare const HISTORY_LIMIT = 200;
+/**
+ * Append an input to the persisted history, deduping the immediately
+ * previous entry and capping the file at `HISTORY_LIMIT` entries.
+ * @param text - Input to persist; blank inputs are ignored.
+ * @returns Resolves once this entry is persisted; callers on the input path
+ * intentionally discard it because persistence is best-effort.
+ */
+export declare function appendHistory(text: string): Promise<void>;
+/**
+ * Read the persisted history, newest first.
+ * @returns The persisted entries in reverse-chronological order.
+ */
+export declare function loadHistory(): HistoryEntry[];
+/**
+ * Read the persisted history in the order the composer walks it: oldest
+ * first, so `↑` reaches the newest entry first (the list tail) exactly as it
+ * does for the entries this process pushed itself.
+ * @returns The persisted entries in chronological order.
+ */
+export declare function loadHistoryOldestFirst(): HistoryEntry[];
+/**
+ * Stable id for a history entry (keeps React keys distinct across identical texts).
+ * @param entry - The history entry to hash.
+ * @param index - Position in the currently rendered result list.
+ * @returns A 12-char hex id derived from the entry text, timestamp, and index.
+ */
+export declare function historyEntryId(entry: HistoryEntry, index?: number): string;
+//# sourceMappingURL=history.d.ts.map

package/lib/types/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/history.ts"],"names":[],"mappings":"AAWA,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,MAAM,CAAA;AAuHhC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,EAAE,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,SAAI,GAAG,MAAM,CAErE"}

package/lib/types/history.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DATA_DIR } from './utils/paths.js';
+const HISTORY_DIR = DATA_DIR;
+const HISTORY_FILE = join(HISTORY_DIR, 'history.jsonl');
+const HISTORY_LOCK = `${HISTORY_FILE}.lock`;
+/**
+ * Entry cap for the persisted history. `↑`/`↓` and the Ctrl+R overlay read
+ * the same file, so both depths come from this one number.
+ */
+export const HISTORY_LIMIT = 200;
+const LOCK_RETRY_LIMIT = 500;
+const LOCK_RETRY_DELAY_MS = 5;
+const STALE_LOCK_MS = 30_000;
+async function removeStaleHistoryLock() {
+    try {
+        const ageMs = Date.now() - (await stat(HISTORY_LOCK)).mtimeMs;
+        if (ageMs < STALE_LOCK_MS)
+            return false;
+        await rm(HISTORY_LOCK, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return true;
+        throw error;
+    }
+}
+async function withHistoryLock(write) {
+    // 0700: history.jsonl holds the user's raw inputs (incl. pasted secrets),
+    // so the directory must not be group/world-readable. Mode applies to the
+    // creation only; pre-existing dirs are left as-is (no migration chmod).
+    await mkdir(HISTORY_DIR, { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < LOCK_RETRY_LIMIT; attempt += 1) {
+        try {
+            await mkdir(HISTORY_LOCK);
+            try {
+                await write();
+            }
+            finally {
+                await rm(HISTORY_LOCK, { recursive: true, force: true });
+            }
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST')
+                throw error;
+            if (await removeStaleHistoryLock())
+                continue;
+            await delay(LOCK_RETRY_DELAY_MS + Math.floor(Math.random() * 5));
+        }
+    }
+    throw new Error('history lock busy');
+}
+function parseRaw(raw) {
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.text === 'string' && parsed.text.length > 0) {
+                entries.push({ text: parsed.text, ts: typeof parsed.ts === 'number' ? parsed.ts : 0 });
+            }
+        }
+        catch {
+            // Skip malformed lines; the file is best-effort.
+        }
+    }
+    return entries;
+}
+function loadRaw() {
+    if (!existsSync(HISTORY_FILE))
+        return [];
+    try {
+        return parseRaw(readFileSync(HISTORY_FILE, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+async function loadRawAsync() {
+    try {
+        return parseRaw(await readFile(HISTORY_FILE, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+async function persistEntry(trimmed) {
+    try {
+        await withHistoryLock(async () => {
+            const entries = await loadRawAsync();
+            // Skip consecutive duplicates (repeated submits of the same
+            // command only advance the existing entry's timestamp).
+            const last = entries[entries.length - 1];
+            if (last && last.text === trimmed) {
+                last.ts = Date.now();
+            }
+            else {
+                entries.push({ text: trimmed, ts: Date.now() });
+            }
+            const sliced = entries.slice(-HISTORY_LIMIT);
+            // Atomic replace: a direct async overwrite exposes truncated bytes to
+            // the synchronous loadHistory() mid-write (review finding). Same-dir
+            // temp file + rename is atomic on POSIX and Windows alike; the temp
+            // keeps mode 0600 — entries carry the full user input text.
+            const tmpFile = `${HISTORY_FILE}.${process.pid}.tmp`;
+            try {
+                await writeFile(tmpFile, sliced.map(e => JSON.stringify(e)).join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
+                await rename(tmpFile, HISTORY_FILE);
+            }
+            finally {
+                // A failed rename would otherwise leave the user's raw input behind in
+                // the temp file, which appendHistory's best-effort catch swallows.
+                await rm(tmpFile, { force: true });
+            }
+        });
+    }
+    catch {
+        // Best-effort persistence; history still works for the session.
+    }
+}
+/**
+ * Serializes local appends. The file lock only orders writers across
+ * processes; without this chain two rapid submits can reach it in either
+ * order and loadHistory() would show them reversed.
+ */
+let appendChain = Promise.resolve();
+/**
+ * Append an input to the persisted history, deduping the immediately
+ * previous entry and capping the file at `HISTORY_LIMIT` entries.
+ * @param text - Input to persist; blank inputs are ignored.
+ * @returns Resolves once this entry is persisted; callers on the input path
+ * intentionally discard it because persistence is best-effort.
+ */
+export function appendHistory(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return Promise.resolve();
+    const queued = appendChain.then(() => persistEntry(trimmed));
+    // persistEntry never rejects, but keep the chain alive regardless so one
+    // failure cannot stall every later append.
+    appendChain = queued.catch(() => { });
+    return queued;
+}
+/**
+ * Read the persisted history, newest first.
+ * @returns The persisted entries in reverse-chronological order.
+ */
+export function loadHistory() {
+    return loadRaw().reverse();
+}
+/**
+ * Read the persisted history in the order the composer walks it: oldest
+ * first, so `↑` reaches the newest entry first (the list tail) exactly as it
+ * does for the entries this process pushed itself.
+ * @returns The persisted entries in chronological order.
+ */
+export function loadHistoryOldestFirst() {
+    return loadRaw();
+}
+/**
+ * Stable id for a history entry (keeps React keys distinct across identical texts).
+ * @param entry - The history entry to hash.
+ * @param index - Position in the currently rendered result list.
+ * @returns A 12-char hex id derived from the entry text, timestamp, and index.
+ */
+export function historyEntryId(entry, index = 0) {
+    return createHash('sha1').update(`${entry.text}\0${entry.ts}\0${index}`).digest('hex').slice(0, 12);
+}

package/lib/types/homePrefs.d.ts

@@ -0,0 +1,15 @@
+interface HomePrefs {
+    /** True once the workspace home has been shown as the landing screen. */
+    seen?: boolean;
+}
+/** Read the persisted landing preference; an unreadable file reads as unset. */
+export declare function readHomePrefs(): HomePrefs;
+/**
+ * Record that the workspace home has been shown.
+ *
+ * @returns True when the preference was durably written; false when the data
+ *   directory is not writable (the caller stays silent — see the module note).
+ */
+export declare function markHomeSeen(): boolean;
+export {};
+//# sourceMappingURL=homePrefs.d.ts.map

package/lib/types/homePrefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"homePrefs.d.ts","sourceRoot":"","sources":["../../src/homePrefs.ts"],"names":[],"mappings":"AA0BA,UAAU,SAAS;IACjB,yEAAyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,gFAAgF;AAChF,wBAAgB,aAAa,IAAI,SAAS,CASzC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAQtC"}

package/lib/types/homePrefs.js

@@ -0,0 +1,53 @@
+/**
+ * Landing-screen preference for the TUI's workspace home screen.
+ *
+ * A one-key preference under `~/.dsh-tui/home.json`, deliberately NOT a cordis
+ * config value: "has this installation shown the user the workspace home on a
+ * fresh launch yet" is per-machine UI state, like the lang and tray
+ * preferences next to it — not a deployment choice a cordis.yml row should own.
+ *
+ * The rule it enables is one-shot: the FIRST ordinary launch (no explicit
+ * `--resume`, no workspace target) lands on the workspace home instead of a
+ * blank conversation, because that is the launch where "which project am I
+ * working on" has no answer yet. After that the chat screen is the landing
+ * surface again, and the home screen stays reachable as a screen.
+ *
+ * A preference file that cannot be read or written is never fatal: the worst
+ * outcome is one extra home screen, or a chat screen where the home was
+ * expected. Both are recoverable with a single keypress.
+ *
+ * @module dsh-cli/homePrefs
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './utils/paths.js';
+const PREFS_FILE = join(DATA_DIR, 'home.json');
+/** Read the persisted landing preference; an unreadable file reads as unset. */
+export function readHomePrefs() {
+    try {
+        const parsed = JSON.parse(readFileSync(PREFS_FILE, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const seen = parsed.seen;
+        return typeof seen === 'boolean' ? { seen } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Record that the workspace home has been shown.
+ *
+ * @returns True when the preference was durably written; false when the data
+ *   directory is not writable (the caller stays silent — see the module note).
+ */
+export function markHomeSeen() {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        writeFileSync(PREFS_FILE, `${JSON.stringify({ ...readHomePrefs(), seen: true }, null, 2)}\n`, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/types/hooks/useBlink.d.ts

@@ -0,0 +1,10 @@
+import type { DOMElement } from '../ink/dom.js';
+/**
+ * Hook for synchronized blinking animations that pause when offscreen.
+ *
+ * @param enabled - Whether blinking is active
+ * @param intervalMs - Blink cycle length in ms; defaults to 600.
+ * @returns [ref, isVisible] - Ref to attach to element, true when visible in blink cycle
+ */
+export declare function useBlink(enabled: boolean, intervalMs?: number): [ref: (element: DOMElement | null) => void, isVisible: boolean];
+//# sourceMappingURL=useBlink.d.ts.map

package/lib/types/hooks/useBlink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBlink.d.ts","sourceRoot":"","sources":["../../../src/hooks/useBlink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAM/C;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,MAA0B,GACrC,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CASjE"}

package/lib/types/hooks/useBlink.js

@@ -0,0 +1,19 @@
+import { useAnimationFrame } from '../ink/hooks/use-animation-frame.js';
+import { useTerminalFocus } from '../ink/hooks/use-terminal-focus.js';
+const BLINK_INTERVAL_MS = 600;
+/**
+ * Hook for synchronized blinking animations that pause when offscreen.
+ *
+ * @param enabled - Whether blinking is active
+ * @param intervalMs - Blink cycle length in ms; defaults to 600.
+ * @returns [ref, isVisible] - Ref to attach to element, true when visible in blink cycle
+ */
+export function useBlink(enabled, intervalMs = BLINK_INTERVAL_MS) {
+    const focused = useTerminalFocus();
+    const [ref, time] = useAnimationFrame(enabled && focused ? intervalMs : null);
+    if (!enabled || !focused)
+        return [ref, true];
+    // Derive blink state from time - all instances see the same time so they sync
+    const isVisible = Math.floor(time / intervalMs) % 2 === 0;
+    return [ref, isVisible];
+}

package/lib/types/hooks/useExternalVersion.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Subscribe to an external store's version counter at DEFAULT lane.
+ *
+ * Deliberately NOT useSyncExternalStore for HIGH-FREQUENCY stores: a store
+ * change forces a SYNCLANE re-render (forceStoreRerender hardcodes lane 2),
+ * and during streaming that sync render preempts/discards whatever
+ * DefaultLane render is in flight. Every such sync commit then ends with
+ * Default work still pending, which React's commit-end lane accounting
+ * counts as a NESTED update with no reset — 50 consecutive dirty commits
+ * throw error #185 from whichever timer dispatches next, killing the
+ * process (the beta.3 crash; same mechanism as useRevealVersion in
+ * PR #680, which fixed the reveal store half of it).
+ *
+ * A manual subscription dispatches setState from the notification callback
+ * at DEFAULT lane instead: the wakeup coalesces into the in-flight render
+ * instead of preempting it, commits end clean, and the counter resets.
+ *
+ * The store's DATA stays synchronous to read during render (callers read
+ * the store directly — rows, status, whatever); the version number is only
+ * a render trigger, its value carries no meaning. This is safe against a
+ * one-beat-stale version: the next wakeup re-reads fresh data, and version
+ * counters are monotonic. Not a general useSyncExternalStore replacement —
+ * use it for version-counter wakeups where the caller re-reads the store
+ * during render anyway (mirrors the tearing analysis in useRevealVersion).
+ *
+ * @param subscribe - Store subscribe(fn) → unsubscribe.
+ * @param getVersion - Returns the store's monotonic version counter.
+ * @param enabled - Pass false to idle (no subscription).
+ * @returns The version number (trigger only; may trail by one wakeup).
+ */
+export declare function useExternalVersion(subscribe: (listener: () => void) => () => void, getVersion: () => number, enabled?: boolean): number;
+//# sourceMappingURL=useExternalVersion.d.ts.map

package/lib/types/hooks/useExternalVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExternalVersion.d.ts","sourceRoot":"","sources":["../../../src/hooks/useExternalVersion.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,EAC/C,UAAU,EAAE,MAAM,MAAM,EACxB,OAAO,GAAE,OAAc,GACtB,MAAM,CAoBR"}