@deepseek-harness-tui/dsh-tui 0.8.0 → 0.8.1

package/lib/types/dsh-adapter/shortcuts.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Plugin keyboard shortcuts — pi's `pi.registerShortcut`. A plugin binds a
+ * combo (`ctrl+shift+p`, `alt+k`, …) to a handler; the chat screen matches
+ * combos against keypresses that survived every built-in binding and runs
+ * the handler, consuming the key.
+ *
+ * Precedence rule (same philosophy as the command list: a plugin shadows
+ * nothing built in):
+ *
+ * - Combos must carry ctrl or alt (meta) — bare letters are typing, and
+ *   bare Esc/arrows are navigation. Rejected at registration.
+ * - A RESERVED list (every combo the TUI itself binds globally or in the
+ *   prompt editor) is refused at registration with a warning. The list is
+ *   the enforcement of "locals win": collisions can never reach the matcher.
+ * - Overlays (pickers, dialogs, scenes, the session browser) own the
+ *   keyboard while open; shortcuts match only in the plain chat state.
+ *
+ * Handlers are fire-and-forget from the UI's point of view: async handlers
+ * are awaited but their rejection is caught and toasted — a throwing
+ * handler must never break the keyboard for everyone else.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** Minimal shape of the ink Key flags the matcher reads (kept structurally
+ *  compatible with `Key` from the ui kit without importing React-facing
+ *  modules into the adapter). */
+export interface TuiShortcutKey {
+    ctrl?: boolean;
+    meta?: boolean;
+    super?: boolean;
+    shift?: boolean;
+    return?: boolean;
+    escape?: boolean;
+    tab?: boolean;
+    backspace?: boolean;
+    delete?: boolean;
+    upArrow?: boolean;
+    downArrow?: boolean;
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+    home?: boolean;
+    end?: boolean;
+    pageUp?: boolean;
+    pageDown?: boolean;
+}
+export interface TuiShortcutOptions {
+    /** One-line description (shown by future /help surfaces; required so
+     *  every binding is discoverable). */
+    description: string;
+    handler: () => void | Promise<void>;
+}
+interface ParsedCombo {
+    readonly raw: string;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+    /** Named key flag on the Key object, or undefined for a character key. */
+    readonly named?: keyof TuiShortcutKey;
+    /** Character to match against the ink `input` string (lowercased). */
+    readonly char?: string;
+}
+/**
+ * Parse `ctrl+shift+p` style combos. Returns undefined on anything
+ * malformed or disallowed (no modifier, unknown key name); `allowReserved`
+ * is exposed for tests only.
+ */
+export declare function parseShortcutCombo(raw: string): ParsedCombo | undefined;
+/** Match a keypress against a parsed combo. `input` is ink's input string
+ *  (already the resolved character; ctrl+space arrives as ' '). */
+export declare function matchShortcut(combo: ParsedCombo, input: string, key: TuiShortcutKey): boolean;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiShortcuts: TuiShortcutRuntime;
+    }
+}
+/** `ctx.tuiShortcuts` — plugin keyboard shortcut registry. */
+export declare class TuiShortcutRuntime extends Service {
+    private readonly shortcuts;
+    /** Handler invocation errors are surfaced through this hook — the chat
+     *  screen wires it to its notification toast. */
+    onError: ((combo: string, error: unknown) => void) | undefined;
+    constructor(ctx: Context);
+    /**
+     * Bind `combo` to `handler`. Invalid, modifier-less, reserved, or
+     * duplicate combos are refused with a logger warning rather than a throw
+     * — a bad binding must not fail the plugin's whole boot.
+     *
+     * Returns the dispose function; the CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as `tuiScenes`
+     * registration. (A service method only sees the service's own ctx, so
+     * caller-fiber cleanup cannot happen here.)
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared` (C-060).
+     */
+    register(combo: string, options: TuiShortcutOptions, identity?: Context): () => void;
+    /** Registered combos with descriptions (diagnostics / future /help). */
+    list(): readonly {
+        combo: string;
+        description: string;
+    }[];
+    /**
+     * Match a keypress; on a hit, run the handler and return true (the UI
+     * consumes the key). Handler rejections are caught and reported through
+     * {@link onError} — never propagated into the input path.
+     */
+    dispatch(input: string, key: TuiShortcutKey): boolean;
+}
+export default TuiShortcutRuntime;
+//# sourceMappingURL=shortcuts.d.ts.map

package/lib/types/dsh-adapter/shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/shortcuts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGtD;;iCAEiC;AACjC,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;0CACsC;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,cAAc,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AA6DD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CA8CvE;AAkBD;mEACmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAiB7F;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,YAAY,EAAE,kBAAkB,CAAA;KACjC;CACF;AAED,8DAA8D;AAC9D,qBAAa,kBAAmB,SAAQ,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE;qDACiD;IACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;gBAElD,GAAG,EAAE,OAAO;IAIxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IAoDpF,wEAAwE;IACxE,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE;IAIzD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO;CAatD;AAED,eAAe,kBAAkB,CAAA"}

package/lib/types/dsh-adapter/shortcuts.js

@@ -0,0 +1,268 @@
+/**
+ * Plugin keyboard shortcuts — pi's `pi.registerShortcut`. A plugin binds a
+ * combo (`ctrl+shift+p`, `alt+k`, …) to a handler; the chat screen matches
+ * combos against keypresses that survived every built-in binding and runs
+ * the handler, consuming the key.
+ *
+ * Precedence rule (same philosophy as the command list: a plugin shadows
+ * nothing built in):
+ *
+ * - Combos must carry ctrl or alt (meta) — bare letters are typing, and
+ *   bare Esc/arrows are navigation. Rejected at registration.
+ * - A RESERVED list (every combo the TUI itself binds globally or in the
+ *   prompt editor) is refused at registration with a warning. The list is
+ *   the enforcement of "locals win": collisions can never reach the matcher.
+ * - Overlays (pickers, dialogs, scenes, the session browser) own the
+ *   keyboard while open; shortcuts match only in the plain chat state.
+ *
+ * Handlers are fire-and-forget from the UI's point of view: async handlers
+ * are awaited but their rejection is caught and toasted — a throwing
+ * handler must never break the keyboard for everyone else.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+const NAMED_KEYS = {
+    enter: 'return',
+    return: 'return',
+    esc: 'escape',
+    escape: 'escape',
+    tab: 'tab',
+    backspace: 'backspace',
+    delete: 'delete',
+    up: 'upArrow',
+    down: 'downArrow',
+    left: 'leftArrow',
+    right: 'rightArrow',
+    home: 'home',
+    end: 'end',
+    pageup: 'pageUp',
+    pagedown: 'pageDown',
+};
+/**
+ * Combos the TUI owns, globally or inside the prompt editor (the editor's
+ * bindings are checked AFTER plugin shortcuts, so refusing them here is
+ * what keeps "locals win" true). Built-in handlers match a MODIFIER SUBSET
+ * (`isMod(key) && input === 'x'` — they never exclude an extra Shift), so
+ * the reserved check below refuses a plugin combo whose SHIFTLESS form is
+ * reserved: ctrl+shift+x would shadow Ctrl+X on terminals that report both
+ * as the same keypress (ConPTY does), and would be dead weight on terminals
+ * that don't.
+ */
+const RESERVED_COMBOS = new Set([
+    'ctrl+c', // interrupt / clear
+    'ctrl+d', // exit on empty input
+    'ctrl+t', // startup context panel
+    'ctrl+r', // history search
+    'ctrl+x', // external editor
+    'ctrl+o', // transcript mode toggle
+    'ctrl+l', // terminal redraw
+    'ctrl+e', // show all messages / line end
+    'ctrl+v', // paste
+    'ctrl+a', // line start
+    'ctrl+u', // kill line
+    'ctrl+k', // kill to end
+    'ctrl+w', // kill word
+    'ctrl+left', // word jump
+    'ctrl+right', // word jump
+    'ctrl+return', // newline (multi-line input)
+    'ctrl+shift+return', // shift+Enter newline (CSI 13;6u) — same editor binding
+    'alt+return', // newline fallback on terminals without shift reporting
+    'alt+up', // pull the last pending message back for editing
+    'escape', // pickers / interrupt / rewind double-tap
+    'tab', // command completion
+    'shift+tab', // session-mode cycle
+]);
+/**
+ * Parse `ctrl+shift+p` style combos. Returns undefined on anything
+ * malformed or disallowed (no modifier, unknown key name); `allowReserved`
+ * is exposed for tests only.
+ */
+export function parseShortcutCombo(raw) {
+    const parts = String(raw ?? '')
+        .toLowerCase()
+        .split('+')
+        .map(part => part.trim())
+        .filter(part => part !== '');
+    if (parts.length === 0)
+        return undefined;
+    let ctrl = false;
+    let meta = false;
+    let shift = false;
+    let named;
+    let char;
+    for (const part of parts) {
+        if (part === 'ctrl' || part === 'control') {
+            if (ctrl)
+                return undefined;
+            ctrl = true;
+        }
+        else if (part === 'alt' || part === 'meta' || part === 'option') {
+            if (meta)
+                return undefined;
+            meta = true;
+        }
+        else if (part === 'shift') {
+            if (shift)
+                return undefined;
+            shift = true;
+        }
+        else if (part === 'space') {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            char = ' ';
+        }
+        else if (part in NAMED_KEYS) {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            named = NAMED_KEYS[part];
+        }
+        else if ([...part].length === 1) {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            char = part;
+        }
+        else {
+            return undefined;
+        }
+    }
+    if (char === undefined && named === undefined)
+        return undefined;
+    // Bare keys are typing/navigation; a modifier is what makes a shortcut.
+    if (!ctrl && !meta)
+        return undefined;
+    // Escape combos are refused outright: the input layer sets key.meta = true
+    // for EVERY Escape (ink/events/input-event.ts — `keypress.meta ||
+    // keypress.name === 'escape' || keypress.option`), so an alt+escape combo
+    // would match every bare Esc press and shadow clear-input / the double-Esc
+    // rewind. Esc is fully owned by the TUI; there is no unambiguous way to
+    // bind it.
+    if (named === 'escape')
+        return undefined;
+    return { raw: parts.join('+'), ctrl, meta, shift, ...(named === undefined ? {} : { named }), ...(char === undefined ? {} : { char }) };
+}
+/** Canonical form for dedupe/reserved checks: modifiers sorted, key last. */
+function comboKey(combo) {
+    const mods = [combo.ctrl ? 'ctrl' : '', combo.meta ? 'alt' : '', combo.shift ? 'shift' : '']
+        .filter(part => part !== '')
+        .sort();
+    return [...mods, combo.named === undefined ? (combo.char ?? '') : String(combo.named)].join('+');
+}
+/** Reserved lookup accepts user-spelled combos too (`ctrl+c`). */
+function reservedKey(raw) {
+    const combo = parseShortcutCombo(raw);
+    return combo === undefined ? raw.toLowerCase() : comboKey(combo);
+}
+const RESERVED_CANONICAL = new Set([...RESERVED_COMBOS].map(reservedKey));
+/** Match a keypress against a parsed combo. `input` is ink's input string
+ *  (already the resolved character; ctrl+space arrives as ' '). */
+export function matchShortcut(combo, input, key) {
+    if (Boolean(key.ctrl) !== combo.ctrl)
+        return false;
+    // ink reports Alt as meta; Esc itself also sets meta, which is why the
+    // modifier check runs against the combo, not a bare flag read.
+    if (Boolean(key.meta) !== combo.meta)
+        return false;
+    if (key.super)
+        return false;
+    // Shift must match for NAMED keys exactly as for characters — otherwise a
+    // registered ctrl+shift+enter would also match a plain ctrl+enter press,
+    // letting a plugin shadow the editor's built-in Ctrl+Enter delivery.
+    if (Boolean(key.shift) !== combo.shift)
+        return false;
+    if (combo.named !== undefined) {
+        return key[combo.named] === true;
+    }
+    if (combo.char === undefined)
+        return false;
+    // Shift+letter arrives as the uppercase character; compare case-folded
+    // (the shift FLAG equality above already pinned the modifier state).
+    return input.toLowerCase() === combo.char;
+}
+/** `ctx.tuiShortcuts` — plugin keyboard shortcut registry. */
+export class TuiShortcutRuntime extends Service {
+    shortcuts = new Map();
+    /** Handler invocation errors are surfaced through this hook — the chat
+     *  screen wires it to its notification toast. */
+    onError;
+    constructor(ctx) {
+        super(ctx, 'tuiShortcuts');
+    }
+    /**
+     * Bind `combo` to `handler`. Invalid, modifier-less, reserved, or
+     * duplicate combos are refused with a logger warning rather than a throw
+     * — a bad binding must not fail the plugin's whole boot.
+     *
+     * Returns the dispose function; the CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as `tuiScenes`
+     * registration. (A service method only sees the service's own ctx, so
+     * caller-fiber cleanup cannot happen here.)
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared` (C-060).
+     */
+    register(combo, options, identity) {
+        const parsed = parseShortcutCombo(combo);
+        if (parsed === undefined) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected ${JSON.stringify(combo)} — need ctrl/alt plus one key (e.g. "ctrl+shift+p")`);
+            return () => { };
+        }
+        const key = comboKey(parsed);
+        // Built-ins match a modifier subset (see RESERVED_COMBOS): a combo whose
+        // SHIFTLESS form is reserved collides with the built-in on terminals that
+        // don't report Shift distinctly, so it is refused too. The exact form is
+        // still checked for combos reserved WITH shift (ctrl+shift+return).
+        const shiftlessKey = comboKey({ ...parsed, shift: false });
+        if (RESERVED_CANONICAL.has(key) || RESERVED_CANONICAL.has(shiftlessKey)) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${combo}" — reserved by a built-in binding`);
+            return () => { };
+        }
+        if (this.shortcuts.has(key)) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${combo}" — already registered`);
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'bind',
+                resource: { kind: 'shortcut', id: key },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
+            return () => { };
+        }
+        const description = cleanScalarText(options?.description, 120);
+        if (typeof options?.handler !== 'function' || description === '') {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${combo}" — needs a description and a handler`);
+            return () => { };
+        }
+        const entry = { combo: parsed, description, handler: options.handler };
+        this.shortcuts.set(key, entry);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        return () => {
+            if (this.shortcuts.get(key) !== entry)
+                return;
+            this.shortcuts.delete(key);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        };
+    }
+    /** Registered combos with descriptions (diagnostics / future /help). */
+    list() {
+        return [...this.shortcuts.values()].map(entry => ({ combo: entry.combo.raw, description: entry.description }));
+    }
+    /**
+     * Match a keypress; on a hit, run the handler and return true (the UI
+     * consumes the key). Handler rejections are caught and reported through
+     * {@link onError} — never propagated into the input path.
+     */
+    dispatch(input, key) {
+        for (const entry of this.shortcuts.values()) {
+            if (!matchShortcut(entry.combo, input, key))
+                continue;
+            Promise.resolve()
+                .then(() => entry.handler())
+                .catch((error) => {
+                this.onError?.(entry.combo.raw, error);
+                this.ctx.logger.warn(`dsh-tui: shortcut "${entry.combo.raw}" handler failed: %o`, error);
+            });
+            return true;
+        }
+        return false;
+    }
+}
+export default TuiShortcutRuntime;

package/lib/types/dsh-adapter/status.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Keyed status-line contributions — pi's `ctx.ui.setStatus(key, text)`.
+ * Each plugin owns a key; setting text shows it, setting undefined clears
+ * it. The TUI renders all contributions as one joined line above the prompt
+ * (host-owned rendering: plugins supply text, never layout).
+ *
+ * Same split as the dialogs seam: a cordis-free store the chat screen
+ * subscribes to, and a thin cordis service validating untrusted text.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** One rendered contribution. */
+export interface TuiStatusEntry {
+    readonly key: string;
+    readonly text: string;
+}
+/** Cordis-free keyed-text store. Render order is first-set order (Map
+ *  insertion order), so a plugin's line never jumps around on updates. */
+export declare class TuiStatusStore {
+    private readonly listeners;
+    private readonly entries;
+    private snapshot;
+    /** Set or clear (undefined/empty) one key. */
+    set(key: string, text: string | undefined, token?: number): void;
+    /** Current contributions, first-set first (stable between changes). */
+    getSnapshot(): readonly TuiStatusEntry[];
+    /** Clear `key` only while it still holds the write tagged `token` — a
+     *  stale disposer must not wipe a newer contribution (even one with
+     *  identical text). Returns true when this call actually cleared. */
+    clearIf(key: string, token: number): boolean;
+    /** Drop everything (teardown). */
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    private emit;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiStatus: TuiStatusRuntime;
+    }
+}
+/**
+ * `ctx.tuiStatus` — plugin-facing status contributions. Invalid keys and
+ * oversized text are rejected with a logger warning instead of throwing:
+ * a status line must never take the TUI down.
+ */
+export declare class TuiStatusRuntime extends Service {
+    /** The store the chat screen renders. Exposed for the host, not plugins. */
+    readonly store: TuiStatusStore;
+    /** Monotonic per-write token; a disposer only clears ITS write (see the
+     *  store's token comment for the same-value ABA this prevents). */
+    private nextToken;
+    constructor(ctx: Context);
+    /**
+     * Set (or clear with `undefined`) the contribution for `key`. Keys are
+     * plugin-namespaced by convention (`my-plugin`, `my-plugin:detail`);
+     * control chars are stripped and text is capped at 200 cells. Text is
+     * scalar-only: string/number/boolean are coerced to string, anything else
+     * is refused with a warning (never rendered as "[object Object]", never
+     * silently treated as a clear).
+     *
+     * Returns a disposer that clears the contribution IF the key still holds
+     * exactly this write (a later set — even of identical text — wins over a
+     * stale disposer). The CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as
+     * `tuiShortcuts`/`tuiScenes`: a service method only sees the service's own
+     * ctx, so per-plugin cleanup cannot happen here. Without that, an unloaded
+     * or hot-reloaded plugin would leave its line behind forever.
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared`, never a
+     * guess (C-060 honest identity).
+     */
+    set(key: string, text: string | number | boolean | undefined, identity?: Context): () => void;
+}
+export default TuiStatusRuntime;
+//# sourceMappingURL=status.d.ts.map

package/lib/types/dsh-adapter/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGtD,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAQD;0EAC0E;AAC1E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAKlD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqD;IAG7E,OAAO,CAAC,QAAQ,CAAgC;IAEhD,8CAA8C;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,IAAI;IAmB3D,uEAAuE;IACvE,WAAW,IAAI,SAAS,cAAc,EAAE;IAIxC;;yEAEqE;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAQ5C,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAOb,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,IAAI;CAGb;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,SAAS,EAAE,gBAAgB,CAAA;KAC5B;CACF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,OAAO;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,iBAAuB;IAErC;uEACmE;IACnE,OAAO,CAAC,SAAS,CAAI;gBAET,GAAG,EAAE,OAAO;IAKxB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;CAoD9F;AAED,eAAe,gBAAgB,CAAA"}

package/lib/types/dsh-adapter/status.js

@@ -0,0 +1,168 @@
+/**
+ * Keyed status-line contributions — pi's `ctx.ui.setStatus(key, text)`.
+ * Each plugin owns a key; setting text shows it, setting undefined clears
+ * it. The TUI renders all contributions as one joined line above the prompt
+ * (host-owned rendering: plugins supply text, never layout).
+ *
+ * Same split as the dialogs seam: a cordis-free store the chat screen
+ * subscribes to, and a thin cordis service validating untrusted text.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+// Colon-separated segments are the documented namespacing convention
+// (`plugin:sub-item`); each segment stays a lowercase slug.
+const KEY_PATTERN = /^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)*$/u;
+const TEXT_CELLS = 200;
+const MAX_ENTRIES = 20;
+/** Cordis-free keyed-text store. Render order is first-set order (Map
+ *  insertion order), so a plugin's line never jumps around on updates. */
+export class TuiStatusStore {
+    listeners = new Set();
+    // Each write carries a token: a disposer compares TOKENS, not text —
+    // value comparison has an ABA hole (set 'x', set 'x' again, the first
+    // disposer would wipe the second write, e.g. a hot reload restoring the
+    // same status text).
+    entries = new Map();
+    // useSyncExternalStore requires a referentially stable snapshot between
+    // emits — a fresh array per call would re-render in an infinite loop.
+    snapshot = [];
+    /** Set or clear (undefined/empty) one key. */
+    set(key, text, token = 0) {
+        const had = this.entries.has(key);
+        if (text === undefined || text === '') {
+            if (!had)
+                return;
+            this.entries.delete(key);
+        }
+        else {
+            const existing = this.entries.get(key);
+            if (existing?.text === text) {
+                // Same text, new write: adopt the new token so the newest disposer
+                // is the one that owns the line (no re-emit — nothing visible changed).
+                existing.token = token;
+                return;
+            }
+            this.entries.set(key, { text, token });
+        }
+        this.snapshot = [...this.entries].map(([entryKey, entry]) => ({ key: entryKey, text: entry.text }));
+        this.emit();
+    }
+    /** Current contributions, first-set first (stable between changes). */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    /** Clear `key` only while it still holds the write tagged `token` — a
+     *  stale disposer must not wipe a newer contribution (even one with
+     *  identical text). Returns true when this call actually cleared. */
+    clearIf(key, token) {
+        if (this.entries.get(key)?.token !== token)
+            return false;
+        this.entries.delete(key);
+        this.snapshot = [...this.entries].map(([entryKey, entry]) => ({ key: entryKey, text: entry.text }));
+        this.emit();
+        return true;
+    }
+    /** Drop everything (teardown). */
+    clear() {
+        if (this.entries.size === 0)
+            return;
+        this.entries.clear();
+        this.snapshot = [];
+        this.emit();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * `ctx.tuiStatus` — plugin-facing status contributions. Invalid keys and
+ * oversized text are rejected with a logger warning instead of throwing:
+ * a status line must never take the TUI down.
+ */
+export class TuiStatusRuntime extends Service {
+    /** The store the chat screen renders. Exposed for the host, not plugins. */
+    store = new TuiStatusStore();
+    /** Monotonic per-write token; a disposer only clears ITS write (see the
+     *  store's token comment for the same-value ABA this prevents). */
+    nextToken = 1;
+    constructor(ctx) {
+        super(ctx, 'tuiStatus');
+        ctx.effect(() => () => this.store.clear());
+    }
+    /**
+     * Set (or clear with `undefined`) the contribution for `key`. Keys are
+     * plugin-namespaced by convention (`my-plugin`, `my-plugin:detail`);
+     * control chars are stripped and text is capped at 200 cells. Text is
+     * scalar-only: string/number/boolean are coerced to string, anything else
+     * is refused with a warning (never rendered as "[object Object]", never
+     * silently treated as a clear).
+     *
+     * Returns a disposer that clears the contribution IF the key still holds
+     * exactly this write (a later set — even of identical text — wins over a
+     * stale disposer). The CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as
+     * `tuiShortcuts`/`tuiScenes`: a service method only sees the service's own
+     * ctx, so per-plugin cleanup cannot happen here. Without that, an unloaded
+     * or hot-reloaded plugin would leave its line behind forever.
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared`, never a
+     * guess (C-060 honest identity).
+     */
+    set(key, text, identity) {
+        const noop = () => { };
+        const normalized = String(key ?? '').trim().toLowerCase();
+        if (!KEY_PATTERN.test(normalized)) {
+            this.ctx.logger.warn(`dsh-tui: tuiStatus.set rejected invalid key ${JSON.stringify(key)}`);
+            return noop;
+        }
+        if (text !== undefined && !this.store.getSnapshot().some(e => e.key === normalized)) {
+            // New key beyond the cap: the line is one row of terminal — an
+            // unbounded count would push the prompt off screen.
+            if (this.store.getSnapshot().length >= MAX_ENTRIES) {
+                this.ctx.logger.warn(`dsh-tui: tuiStatus.set rejected "${normalized}": ${MAX_ENTRIES} contributions already shown`);
+                return noop;
+            }
+        }
+        let cleaned;
+        if (text !== undefined) {
+            // Scalar-only coercion (Track A contract): a non-scalar text (an
+            // object would otherwise render as "[object Object]") is REFUSED with
+            // a warning — it must not silently become a clear, either.
+            if (typeof text !== 'string' && typeof text !== 'number' && typeof text !== 'boolean') {
+                this.ctx.logger.warn(`dsh-tui: tuiStatus.set rejected non-scalar text for "${normalized}"`);
+                return noop;
+            }
+            cleaned = cleanScalarText(text, TEXT_CELLS);
+        }
+        const token = this.nextToken++;
+        const had = this.store.getSnapshot().some(entry => entry.key === normalized);
+        this.store.set(normalized, cleaned, token);
+        const ledger = this.ctx.get('tuiEffectLedger');
+        if (cleaned === undefined) {
+            if (had)
+                ledger?.record({ operation: 'release', resource: { kind: 'status', id: normalized }, result: 'applied' }, identity);
+        }
+        else {
+            ledger?.record({
+                operation: had ? 'replace' : 'bind',
+                resource: { kind: 'status', id: normalized },
+                result: 'applied',
+                ...(had ? { replaces: { resourceId: normalized } } : {}),
+            }, identity);
+        }
+        return () => {
+            if (this.store.clearIf(normalized, token)) {
+                this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'status', id: normalized }, result: 'applied' }, identity);
+            }
+        };
+    }
+}
+export default TuiStatusRuntime;

package/lib/types/extensions.d.ts

@@ -0,0 +1,8 @@
+export * from './dsh-adapter/extensions.js';
+export * from './dsh-adapter/extension-events.js';
+export * from './dsh-adapter/dialogs.js';
+export * from './dsh-adapter/status.js';
+export * from './dsh-adapter/shortcuts.js';
+export * from './dsh-adapter/renderers.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":"AAMA,cAAc,6BAA6B,CAAA;AAC3C,cAAc,mCAAmC,CAAA;AACjD,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAG1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA"}

package/lib/types/extensions.js

@@ -0,0 +1,15 @@
+// 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
+// (`@deepseek-harness-tui/dsh-tui/extensions`); importing the module also
+// applies the `declare module '@deepseek-ai/cordis'` augmentation for the
+// decision events and the four service properties on Context.
+export * from './dsh-adapter/extensions.js';
+export * from './dsh-adapter/extension-events.js';
+export * from './dsh-adapter/dialogs.js';
+export * from './dsh-adapter/status.js';
+export * from './dsh-adapter/shortcuts.js';
+export * from './dsh-adapter/renderers.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';