@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,329 @@
+/**
+ * Managed plugin dialogs — the pi `ctx.ui.select/confirm/input` seam for
+ * dsh-TUI. Plugins hand the HOST a declarative request; the TUI renders the
+ * dialog in its own chrome (next to the approval panel), owns the keyboard,
+ * and settles the plugin's promise with the user's answer. Plugins never
+ * touch the TTY themselves.
+ *
+ * Split in two, mirroring QuestionStore/ApprovalStore:
+ *
+ * - {@link TuiDialogStore} — cordis-free queue + snapshot. The chat screen
+ *   subscribes to it and renders the current dialog; tests can drive it
+ *   without a cordis context.
+ * - {@link TuiDialogRuntime} — the cordis service (`ctx.tuiDialogs`)
+ *   plugins call. Validation of untrusted request data lives here.
+ *
+ * Queue semantics mirror the approval store: parallel plugin calls park
+ * FIFO and surface one at a time. A request settles exactly once — user
+ * answer, Esc cancel, caller AbortSignal, caller timeout, or service
+ * teardown (`cancelled` outcomes map to `undefined`/`false` returns).
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+import { activationContext, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+/** Render-path strings are untrusted: sanitization (control-char stripping,
+ *  cell-width caps, scalar-only coercion) lives in ./sanitize.js — the one
+ *  implementation of the Track A contract. `clean` drops non-scalars to ''
+ *  so callers take their refuse path instead of rendering "[object Object]". */
+const clean = cleanScalarText;
+const TITLE_CELLS = 120;
+const LABEL_CELLS = 120;
+const MESSAGE_CELLS = 400;
+/** The documented bound of the resolved input text; the panel enforces it
+ *  on every edit path (typing AND paste) so the promise never resolves with
+ *  a larger value. */
+export const INPUT_CELLS = 500;
+const MAX_OPTIONS = 100;
+/** Bound a request that omits both signal and timeout. */
+export const DIALOG_DEFAULT_TIMEOUT_MS = 30_000;
+let nextDialogId = 1;
+/**
+ * Cordis-free dialog queue. `ask` parks a request; the UI drains one at a
+ * time via the snapshot and settles through {@link decide}/{@link cancel}.
+ */
+export class TuiDialogStore {
+    listeners = new Set();
+    queue = [];
+    active = null;
+    /** Park a request. The snapshot argument must already be sanitized. */
+    ask(snapshot, signal, timeoutMs, owner, bindOwnerEffect) {
+        if (signal?.aborted)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            let settled = false;
+            const pending = {
+                // The key is stable per dialog (the panel remounts fresh per
+                // request, like ApprovalSnapshot.key) and unique across the queue.
+                key: `dlg-${nextDialogId++}`,
+                snapshot: undefined,
+                settle: () => { },
+                onAbort: () => { },
+                timer: undefined,
+                ownerCleanup: undefined,
+            };
+            pending.snapshot = { ...snapshot, key: pending.key };
+            pending.settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (pending.timer !== undefined)
+                    clearTimeout(pending.timer);
+                signal?.removeEventListener('abort', pending.onAbort);
+                const ownerCleanup = pending.ownerCleanup;
+                pending.ownerCleanup = undefined;
+                ownerCleanup?.();
+                resolve(value);
+            };
+            pending.onAbort = () => {
+                // Normal completion also disposes the owner effect. The effect's
+                // cleanup must not re-enter the abort path and advance the queue a
+                // second time.
+                if (settled)
+                    return;
+                // Aborted while queued: drop silently. Aborted while active: close
+                // the dialog and advance the queue.
+                const index = this.queue.indexOf(pending);
+                if (index !== -1)
+                    this.queue.splice(index, 1);
+                if (this.active === pending)
+                    this.active = null;
+                pending.settle(undefined);
+                // Must advance (not just emit): with the active dialog gone, the
+                // next queued request has to become active — otherwise its Promise
+                // parks forever and the UI shows no dialog until an unrelated ask
+                // happens to trigger advance.
+                this.advance();
+            };
+            signal?.addEventListener('abort', pending.onAbort, { once: true });
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                pending.timer = setTimeout(pending.onAbort, timeoutMs);
+            }
+            if (owner !== undefined) {
+                const bound = bindOwnerEffect?.(pending.onAbort, cleanup => { pending.ownerCleanup = cleanup; }) ?? false;
+                if (!bound) {
+                    // An inactive or untrusted activation must never leave an orphan in
+                    // the queue. The binder also rolls back partial owner state.
+                    pending.onAbort();
+                    return;
+                }
+            }
+            this.queue.push(pending);
+            this.advance();
+        });
+    }
+    /** The dialog the UI should render right now, if any. */
+    getSnapshot() {
+        return this.active?.snapshot ?? null;
+    }
+    /**
+     * Settle the active dialog with the user's answer. The caller passes the
+     * key of the snapshot IT rendered; a mismatched key is a stale callback
+     * and ignored. This is not paranoia: ConPTY can deliver one Enter as a
+     * same-batch CR+LF pair, firing the old panel's handler twice before
+     * React unmounts it — an unkeyed decide would settle the active dialog
+     * AND the successor the first call just promoted (one Enter answering two
+     * consecutive dialogs).
+     */
+    decide(key, value) {
+        const pending = this.active;
+        if (pending === null || pending.key !== key)
+            return;
+        this.active = null;
+        pending.settle(value);
+        this.advance();
+    }
+    /** Cancel the active dialog (Esc). Keyed like {@link decide}: a stale
+     *  panel's Esc must not close the successor it never rendered. */
+    cancel(key) {
+        const pending = this.active;
+        if (pending === null || pending.key !== key)
+            return;
+        this.active = null;
+        pending.settle(undefined);
+        this.advance();
+    }
+    /** Settle everything queued + active (teardown): all resolve cancelled. */
+    settleAll() {
+        const pending = [...this.queue];
+        this.queue.length = 0;
+        if (this.active !== null)
+            pending.push(this.active);
+        this.active = null;
+        for (const item of pending)
+            item.settle(undefined);
+        this.emit();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    advance() {
+        if (this.active === null && this.queue.length > 0) {
+            this.active = this.queue.shift() ?? null;
+        }
+        this.emit();
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * `ctx.tuiDialogs` — plugin-facing managed dialogs. Every method validates
+ * its request (untrusted data on the render path) and resolves with the
+ * cancelled value (`undefined`/`false`) rather than throwing when the
+ * request is malformed — a dialog must never take the plugin or the TUI
+ * down; callers get a logger warning instead.
+ */
+export class TuiDialogRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiDialogs');
+        compositionRoot(ctx);
+        // Keep queue state off the service object. Cordis invokes public methods
+        // through a caller-bound proxy, so JS `#private` fields are unsuitable
+        // here; the module-local WeakMap preserves both encapsulation and proxy
+        // compatibility.
+        const store = new TuiDialogStore();
+        hostDialogStores.set(this, store);
+        hostDialogRuntimes.set(this, adapterRuntimeFor(ctx));
+        ctx.effect(() => () => store.settleAll());
+    }
+    /** Cordis traceable services normally provide the caller through `this.ctx`;
+     * the explicit overloads below make ownership unambiguous for embedders and
+     * tests that retain the service instance directly. */
+    callContext(value) {
+        const caller = requirePluginCaller(this.ctx, 'tuiDialogs', this);
+        if (!Context.is(value))
+            return caller;
+        // An explicit owner is accepted only when it is the activation that made
+        // the service call.  Otherwise a plugin could pass the root (or another
+        // plugin's context) and leave an orphaned dialog alive after deactivation.
+        const canonical = activationContext(value);
+        if (canonical === undefined || activationContext(caller) !== canonical) {
+            throw new Error('tuiDialogs owner context must be the calling activation');
+        }
+        return canonical;
+    }
+    timeoutOf(value) {
+        return typeof value === 'number' && Number.isFinite(value) && value > 0
+            ? Math.min(Math.floor(value), 24 * 60 * 60 * 1000)
+            : DIALOG_DEFAULT_TIMEOUT_MS;
+    }
+    select(ownerOrRequest, explicitRequest) {
+        assertCapabilityShadowPolicy('host.dialogs.select', dialogRuntimeFor(this).mode, dialogRuntimeFor(this).slices);
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            const rawOptions = Array.isArray(request?.options) ? request.options : [];
+            const options = [];
+            for (const raw of rawOptions.slice(0, MAX_OPTIONS)) {
+                // The id is NOT render-path data — it is the opaque token the promise
+                // resolves with, matched by the plugin against its own options. Sanitizing
+                // it (whitespace collapse, cell truncation) would hand back a DIFFERENT
+                // string the plugin cannot look up; validate and keep it verbatim.
+                const id = raw?.id;
+                const label = clean(raw?.label, LABEL_CELLS);
+                if (typeof id !== 'string' || id === '' || !label)
+                    continue;
+                // '' (absent, blank, or a dropped non-scalar) means no description row.
+                const description = clean(raw?.description, MESSAGE_CELLS);
+                options.push({ id, label, ...(description === '' ? {} : { description }) });
+            }
+            if (!title || options.length === 0) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.select called without a title or options; cancelled');
+                return Promise.resolve(undefined);
+            }
+            return dialogStoreFor(this)
+                .ask({ kind: 'select', title, options }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => (typeof value === 'string' ? value : undefined));
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.select received malformed data; cancelled');
+            return Promise.resolve(undefined);
+        }
+    }
+    confirm(ownerOrRequest, explicitRequest) {
+        assertCapabilityShadowPolicy('host.dialogs.confirm', dialogRuntimeFor(this).mode, dialogRuntimeFor(this).slices);
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            if (!title) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.confirm called without a title; cancelled');
+                return Promise.resolve(false);
+            }
+            const message = clean(request?.message, MESSAGE_CELLS);
+            const confirmLabel = clean(request?.confirmLabel, LABEL_CELLS);
+            const cancelLabel = clean(request?.cancelLabel, LABEL_CELLS);
+            return dialogStoreFor(this)
+                .ask({
+                kind: 'confirm',
+                title,
+                ...(message === '' ? {} : { message }),
+                confirmLabel,
+                cancelLabel,
+            }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => value === true);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.confirm received malformed data; cancelled');
+            return Promise.resolve(false);
+        }
+    }
+    input(ownerOrRequest, explicitRequest) {
+        assertCapabilityShadowPolicy('host.dialogs.input', dialogRuntimeFor(this).mode, dialogRuntimeFor(this).slices);
+        try {
+            const owner = this.callContext(ownerOrRequest);
+            const request = (explicitRequest ?? ownerOrRequest);
+            const title = clean(request?.title, TITLE_CELLS);
+            if (!title) {
+                this.ctx.logger.warn('dsh-tui: tuiDialogs.input called without a title; cancelled');
+                return Promise.resolve(undefined);
+            }
+            const placeholder = clean(request?.placeholder, LABEL_CELLS);
+            const initial = clean(request?.initial, INPUT_CELLS);
+            return dialogStoreFor(this)
+                .ask({ kind: 'input', title, ...(placeholder === '' ? {} : { placeholder }), initial }, request.signal, this.timeoutOf(request.timeoutMs), owner, (disposer, onRegistered) => bindCallerEffect(owner, disposer, onRegistered))
+                .then(value => (typeof value === 'string' ? value : undefined));
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiDialogs.input received malformed data; cancelled');
+            return Promise.resolve(undefined);
+        }
+    }
+}
+/**
+ * Host-only queue accessor. This module is intentionally not a package
+ * export; plugins receive only the traceable `tuiDialogs` capability, whose
+ * public surface is select/confirm/input.
+ */
+const hostDialogStores = new WeakMap();
+const hostDialogRuntimes = new WeakMap();
+function dialogRuntimeFor(runtime) {
+    const state = hostDialogRuntimes.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiDialogs host runtime is unavailable');
+    return state;
+}
+function dialogStoreFor(runtime) {
+    const store = hostDialogStores.get(concreteService(runtime));
+    if (store === undefined)
+        throw new Error('tuiDialogs host store is unavailable');
+    return store;
+}
+export function getHostDialogStore(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return hostDialogStores.get(concreteService(runtime));
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiDialogRuntime;

package/lib/types/dsh-adapter/effect-ledger.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Effect ledger (C-060): an append-only JSONL journal of plugin-visible
+ * effects at `~/.dsh-tui/effect-ledger.jsonl`, mounted by the
+ * dsh-tui-plugin-host row as `ctx.tuiEffectLedger`.
+ *
+ * Every record carries the lifecycle triple:
+ *
+ * - `pluginId` — derived from the verified Component identity bound to the
+ *   PASSED activation. `'host'` is used for host/root records and
+ *   `'undeclared'` for a plugin-facing call without a verified identity; a
+ *   display fiber name is never trusted as authorization identity.
+ * - `activationInstance` — stable per cordis fiber for the lifetime of this
+ *   process (first-seen assignment from a WeakMap), so a hot-reloaded plugin
+ *   shows up as a NEW instance while all effects of one activation share one
+ *   id.
+ * - `runtimeGenerationId` — the plugin-host row's generation (C-050), so
+ *   records from different process generations can never be confused.
+ *
+ * Recording rules:
+ *
+ * - FAIL-CLOSED ON SCHEMA: every record is validated against the vendored
+ *   `effect-ledger-record.schema.json` BEFORE it is appended; a record that
+ *   fails is dropped with a warning, never written. A missing vendored
+ *   schema suppresses ALL writes (warned once) — the same posture as the
+ *   messages.observe envelope check. The schema's `additionalProperties:
+ *   false` is what structurally bans secrets from the ledger: callers
+ *   cannot smuggle payload fields through.
+ * - SEQUENCE: continues across restarts (max sequence in the existing file
+ *   + 1); corrupt lines are skipped, never rewritten.
+ * - NEVER THROWS: recording is observability, not a gate — internal errors
+ *   (including disk failures) are caught and warned, the caller's path is
+ *   unaffected.
+ *
+ * privacyClass: operational — records hold identifiers and error codes,
+ * never message content, storage values, or grant-file contents.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** Default ledger file (JSONL, one record per line). */
+export declare const EFFECT_LEDGER_FILE: string;
+/** Resource kinds recorded by the host's wired emitters. */
+export declare const LEDGER_RESOURCE_KINDS: readonly ["command", "scene", "shortcut", "status", "renderer", "theme", "storage-namespace", "subscription", "permission"];
+export type LedgerOperation = 'create' | 'bind' | 'replace' | 'release' | 'cleanup-failed';
+export type LedgerResult = 'applied' | 'pending' | 'failed';
+/** Caller-facing record input; the runtime fills the lifecycle triple. */
+export interface LedgerEntry {
+    operation: LedgerOperation;
+    resource: {
+        kind: string;
+        id: string;
+    };
+    result: LedgerResult;
+    /** Contract error code when result is 'failed' (e.g. PERMISSION_NOT_GRANTED). */
+    errorCode?: string;
+    /** What this record supersedes (operation 'replace'). */
+    replaces?: {
+        resourceId?: string;
+        activationInstance?: string;
+    };
+    /** `sha256:<64hex>` digest of an opaque value, when a record must reference one. */
+    valueDigest?: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiEffectLedger: TuiEffectLedgerRuntime;
+    }
+}
+/** `ctx.tuiEffectLedger` — append-only effect journal (C-060). */
+export declare class TuiEffectLedgerRuntime extends Service {
+    constructor(ctx: Context, options?: {
+        file?: string;
+        generationId?: string;
+        ledgerSchema?: Record<string, unknown>;
+    });
+    /**
+     * Append one record. `identity` is the caller's own context (plugins pass
+     * their plugin ctx through the managed services' optional trailing
+     * parameter); omitting it records `undeclared`, never a guess.
+     */
+    record(entry: LedgerEntry, identity?: Context): void;
+    /** Append one kernel-resolved record to the JSONL file. */
+    private appendKernelRecord;
+    /** Kernel-ledger owner resolver: verified activation identity wins; host /
+     * undeclared fallbacks are explicit and never borrowed from fiber names. */
+    private resolveKernelOwner;
+    /** Runtime generation (C-050): options override, else the plugin-host
+     *  service's id — resolved on first record and cached (the host row mounts
+     *  before any caller can record). */
+    private generation;
+    /** Continue numbering after the existing file's max sequence (restart-safe). */
+    private resumeSequence;
+    private fiberOf;
+    private pluginIdOf;
+    private activationOf;
+}
+export default TuiEffectLedgerRuntime;
+//# sourceMappingURL=effect-ledger.d.ts.map

package/lib/types/dsh-adapter/effect-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-ledger.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/effect-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AActD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAwC,CAAA;AAEvE,4DAA4D;AAC5D,eAAO,MAAM,qBAAqB,6HAUxB,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAA;AAC1F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE3D,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAA;IAC1B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,MAAM,EAAE,YAAY,CAAA;IACpB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,eAAe,EAAE,sBAAsB,CAAA;KACxC;CACF;AAWD,kEAAkE;AAClE,qBAAa,sBAAuB,SAAQ,OAAO;gBAE/C,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO;IAsChG;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI;IAWpD,2DAA2D;IAC3D,OAAO,CAAC,kBAAkB;IAwD1B;gFAC4E;IAC5E,OAAO,CAAC,kBAAkB;IAqB1B;;yCAEqC;IACrC,OAAO,CAAC,UAAU;IAOlB,gFAAgF;IAChF,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,YAAY;CAarB;AA+CD,eAAe,sBAAsB,CAAA"}