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

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';