@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/decision-guard.js

@@ -0,0 +1,460 @@
+/**
+ * RFC 0005 D-7 enforcement: subscribing to an intercept-class (decision)
+ * event requires an explicit host-side grant — default deny.
+ *
+ * Interception is strictly more powerful than observation: a plugin that can
+ * veto user input or a session switch can change what the user's intent
+ * actually does. So `tui/input`, `tui/rewind-prompt`, `tui/session-switch`
+ * and `tui/compact` are NOT free-for-all `ctx.on` targets: the subscribing
+ * plugin (identified by its verified Component identity) must hold the
+ * matching `domain.resource.intercept` grant. Grant answers
+ * come from the unified 8-permission GrantStore in
+ * `../adapter/standard/grants.js` (registry-driven defaults,
+ * `grants`/`denies` sections, corrupt fail-closed) — this module is only the
+ * subscribe-time CHECKPOINT: which event needs which permission, and the
+ * cordis bail hook that enforces it.
+ *
+ * A denied subscription never enters the dispatch chain — it is "as if
+ * unregistered" (D-7) and the caller gets a no-op disposer plus a logger
+ * warning naming the plugin, the event, and the missing grant.
+ *
+ * Re-check semantics (D-7: subscription, revocation, scope change): every
+ * operation reads the live GrantStore and grant-owned registrations are
+ * released when its change watcher observes a revocation.
+ *
+ * Mechanism: cordis bails `internal/listener` on EVERY `ctx.on` before
+ * registering, with `this` bound to the subscribing context; a truthy bail
+ * result skips the registration and becomes the caller's disposer. That is
+ * the whole hook — no patching of the events service.
+ */
+import { EXTENSION_GRANTS_FILE, parseGrantStore, readGrantStore, } from '../adapter/standard/grants.js';
+import { componentIdentityOf, requiresDecisionEvents, } from './component-identity.js';
+import { INTERCEPT_EVENT_SCOPE_BY_PERMISSION, normalizePermissionScope, permissionScopeCovers, } from '../adapter/standard/permission-scope.js';
+import { TUI_DECISION_EVENT_NAMES } from '../adapter/standard/tui-extension.js';
+import { DECISION_EVENT_PERMISSIONS } from '../adapter/spec/protocol-constants.js';
+import { bindCallerEffect, compositionRoot } from './host-access.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+/** The intercept permission each decision event requires. The map is
+ * derived in src/adapter/spec/protocol-constants.ts and re-exported here for
+ * compatibility; product code must not declare a second copy. */
+export { DECISION_EVENT_PERMISSIONS };
+// ── Compatibility aliases (pre-GrantStore names) ────────────────────────────
+// These aliases are intentionally outside the P6 removal scope: they are a
+// long-term compatibility surface for existing embedder/test code. They map
+// directly to the canonical `../adapter/standard/grants.js` implementation.
+// OWNER: dsh-tui adapter. UNTIL: no scheduled removal.
+export { EXTENSION_GRANTS_FILE };
+/** @deprecated Use parseGrantStore from `../adapter/standard/grants.js`.
+ * Long-term compatibility alias; owner: dsh-tui adapter. */
+export const parseExtensionGrants = parseGrantStore;
+/** @deprecated Use readGrantStore from `../adapter/standard/grants.js`.
+ * Long-term compatibility alias; owner: dsh-tui adapter. */
+export const readExtensionGrants = readGrantStore;
+/**
+ * Install the D-7 gate: every subscription to a decision event is checked
+ * against `grants` at subscribe time. Registered with `global` so context
+ * filtering can never hide a plugin's subscription from the gate, and
+ * `prepend` so it decides before any later internal/listener hook.
+ *
+ * Idempotent per cordis root: BOTH the extensions row and createChannel
+ * call this — the channel is the dispatch path, so a stale patch without
+ * the extensions row (or a bare embed mounting neither) must not leave
+ * decision events subscribable-by-default. The first installer wins; both
+ * production call sites read the same host-owned grants file, so which one
+ * lands first is unobservable.
+ */
+const guardedRoots = new WeakSet();
+/**
+ * Real DecisionEvents dispatch topology, keyed by Cordis composition root.
+ *
+ * The guard alone is NOT evidence that an event is actually dispatched:
+ * `installDecisionGuard()` only installs the subscribe-time gate. The actual
+ * dispatch paths live in the channel (`createChannel`), which calls
+ * `markDecisionDispatchTopology()` after it is composed. Until that marker is
+ * present, `probeDecisionEventFeatures()` returns no features — the public
+ * Host Descriptor must not publish DecisionEvents from a composition that only
+ * has a guard and no real channel/dispatch source.
+ */
+const decisionDispatchTopology = new WeakMap();
+const handlerMetadata = new WeakMap();
+const registries = new WeakMap();
+function rootKey(ctx) {
+    return compositionRoot(ctx);
+}
+function registryFor(ctx, grants) {
+    const key = rootKey(ctx);
+    const runtime = adapterRuntimeFor(ctx);
+    let registry = registries.get(key);
+    if (registry === undefined) {
+        registry = { grants: grants ?? readGrantStore(undefined, undefined, runtime), handlers: new Map(), runtime };
+        registries.set(key, registry);
+    }
+    else if (grants !== undefined) {
+        registry.grants = grants;
+    }
+    return registry;
+}
+export function decisionRegistryOf(ctx) {
+    return registryFor(ctx);
+}
+/** Return a stable snapshot of handlers for one event and payload scope. */
+export function decisionHandlersOf(ctx, event, payloadScope) {
+    const rows = [...(registryFor(ctx).handlers.get(event)?.values() ?? [])];
+    const permission = eventPermission(event);
+    const scopePermission = permission ?? 'messages.observe.read';
+    const actual = typeof payloadScope === 'string'
+        ? normalizePermissionScope(scopePermission, payloadScope, 'host')
+        : undefined;
+    return rows
+        .filter(row => {
+        const declared = normalizeDecisionScope(event, row.scope, 'host');
+        // A session-scoped handler cannot be safely applied when the host did
+        // not provide a session scope. Treat the missing scope as an
+        // unmatchable request instead of turning a narrow grant into a global
+        // one. Event-point scopes remain applicable because they deliberately
+        // cover every session.
+        if (actual === undefined)
+            return declared?.kind === 'event';
+        // An event-name scope (for example `tui/input`) selects the Decision
+        // Events point, not one session. It therefore applies to every payload
+        // session; only session-kind scopes participate in session filtering.
+        return declared?.kind === 'event' && declared.value === event
+            || (declared !== undefined && permissionScopeCovers(scopePermission, declared, actual));
+    })
+        .sort((left, right) => {
+        const order = compareStableText(left.order, right.order);
+        if (order !== 0)
+            return order;
+        const component = compareStableText(left.componentId, right.componentId);
+        if (component !== 0)
+            return component;
+        return compareStableText(left.activationId, right.activationId);
+    });
+}
+function eventPermission(event) {
+    return DECISION_EVENT_PERMISSIONS[event];
+}
+/** Normalize a handler scope against its actual event point. Notification
+ * points have no intercept permission, but still support event/session scopes
+ * for deterministic delivery filtering. */
+function normalizeDecisionScope(event, scope, componentId) {
+    const permission = eventPermission(event);
+    if (permission !== undefined)
+        return normalizePermissionScope(permission, scope, componentId);
+    if (scope === event)
+        return { kind: 'event', value: event };
+    return normalizePermissionScope('messages.observe.read', scope, componentId);
+}
+/** Pick a scope for a legacy-looking `ctx.on(event, listener)` call without
+ * widening a concrete declaration. */
+function defaultDecisionScope(identity, event) {
+    const permission = eventPermission(event);
+    if (permission === undefined)
+        return event;
+    const expectedEvent = INTERCEPT_EVENT_SCOPE_BY_PERMISSION[permission];
+    const requests = identity.manifest.permissions.filter(request => request.name === permission);
+    if (requests.some(request => request.scope === expectedEvent))
+        return expectedEvent;
+    if (requests.some(request => {
+        const normalized = normalizePermissionScope(permission, request.scope, identity.componentId);
+        return normalized?.kind === 'session' && normalized.value === 'session:*';
+    }))
+        return 'session:*';
+    // A concrete session grant cannot safely be inferred for a context-level
+    // listener. The caller must pass that scope explicitly through the mediated
+    // API, otherwise registration is refused.
+    return undefined;
+}
+/** Host-only registration used by TuiPluginHostRuntime. */
+export function registerDecisionHandler(pluginCtx, identity, event, listener, options = {}, onRelease) {
+    const runtime = registryFor(pluginCtx).runtime;
+    assertCapabilityShadowPolicy('host.decision.subscribe', runtime.mode, runtime.slices);
+    if (componentIdentityOf(pluginCtx) !== identity) {
+        throw new Error('DecisionEvents registration identity is not bound to the calling activation');
+    }
+    if (!requiresDecisionEvents(identity)) {
+        throw new Error('DecisionEvents registration requires tui.dsh/v1alpha1#DecisionEvents');
+    }
+    if (!TUI_DECISION_EVENT_NAMES.includes(event)) {
+        throw new TypeError(`unknown TUI DecisionEvents point: ${event}`);
+    }
+    if (typeof listener !== 'function')
+        throw new TypeError('DecisionEvents handler must be a function');
+    const scope = options.scope ?? defaultDecisionScope(identity, event);
+    if (scope === undefined) {
+        throw new Error(`DecisionEvents scope for ${event} must be explicit when the manifest only declares a concrete session scope`);
+    }
+    const normalizedScope = normalizeDecisionScope(event, scope, identity.componentId);
+    if (normalizedScope === undefined)
+        throw new TypeError(`DecisionEvents scope is not enforceable: ${scope}`);
+    const permission = eventPermission(event);
+    const staticallyDeclared = permission === undefined
+        ? normalizedScope.kind === 'event' && normalizedScope.value === event
+        : identity.manifest.permissions.some(request => {
+            if (request.name !== permission)
+                return false;
+            const declared = normalizePermissionScope(permission, request.scope, identity.componentId);
+            return declared !== undefined && permissionScopeCovers(permission, declared, normalizedScope);
+        });
+    if (!staticallyDeclared) {
+        throw new Error(`DecisionEvents permission ${permission}@${scope} is not statically declared by ${identity.componentId}`);
+    }
+    const registry = registryFor(pluginCtx);
+    const principal = { componentId: identity.componentId, activationId: identity.activationId };
+    const currentlyGranted = permission === undefined || registry.grants.allows(principal, permission, scope);
+    if (!currentlyGranted) {
+        try {
+            pluginCtx.logger.warn(`dsh-tui: ${event} registration denied for Component "${identity.componentId}" — grant ${permission}@${scope} is missing`);
+        }
+        catch { /* best effort */ }
+        return () => false;
+    }
+    const order = options.order ?? identity.componentId;
+    if (order === '' || /[\x00-\x1f\x7f-\x9f]/u.test(order)) {
+        throw new TypeError('DecisionEvents order must be a non-empty control-free string');
+    }
+    const key = `${identity.activationId}\0${event}\0${order}`;
+    const byActivation = registry.handlers.get(event) ?? new Map();
+    if (byActivation.has(key))
+        throw new Error(`DecisionEvents order is already registered for this activation/event: ${event}@${order}`);
+    const row = Object.freeze({
+        event,
+        scope,
+        componentId: identity.componentId,
+        activationId: identity.activationId,
+        order,
+        identity,
+        ownerContext: pluginCtx,
+        listener,
+    });
+    byActivation.set(key, row);
+    handlerMetadata.set(listener, {
+        componentId: identity.componentId,
+        activationId: identity.activationId,
+        event,
+        order,
+    });
+    registry.handlers.set(event, byActivation);
+    let closed = false;
+    let stopGrantWatch;
+    const release = () => {
+        if (closed)
+            return false;
+        closed = true;
+        stopGrantWatch?.();
+        stopGrantWatch = undefined;
+        if (byActivation.get(key) === row)
+            byActivation.delete(key);
+        if (handlerMetadata.get(listener)?.activationId === identity.activationId
+            && handlerMetadata.get(listener)?.event === event
+            && handlerMetadata.get(listener)?.order === order)
+            handlerMetadata.delete(listener);
+        try {
+            onRelease?.();
+        }
+        catch {
+            // The registry has already released the effect. Observability failures
+            // must not turn a revoke/deactivate cleanup into a leaked handler.
+        }
+        return true;
+    };
+    // Both deactivation and grant-file revocation are release boundaries. Bind
+    // through the host-captured Fiber effect so an explicit Context shadow
+    // cannot replace the cleanup function.
+    bindCallerEffect(pluginCtx, release);
+    if (permission !== undefined) {
+        const stop = registry.grants.onChange?.(() => {
+            const principal = { componentId: identity.componentId, activationId: identity.activationId };
+            if (!registry.grants.allows(principal, permission, scope))
+                release();
+        });
+        stopGrantWatch = stop;
+        if (stop !== undefined) {
+            bindCallerEffect(pluginCtx, stop);
+        }
+    }
+    return release;
+}
+/** Locale-independent comparator for the declared decision order policy.
+ * `localeCompare()` can vary with host ICU settings, which would make the
+ * winner depend on the machine running the same admitted component set. */
+function compareStableText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function fiberKey(ctx) {
+    try {
+        const fiber = ctx.fiber;
+        return typeof fiber === 'object' && fiber !== null ? fiber : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Execute ctx.on for one host-mediated decision registration. */
+export function withDecisionRegistration(ctx, callback) {
+    const fiber = fiberKey(ctx);
+    if (fiber === undefined)
+        throw new Error('decision registration requires a Cordis activation');
+    return callback();
+}
+export function decisionHandlerMetadataOf(listener) {
+    return handlerMetadata.get(listener);
+}
+/** Return the event names for which a real dispatch topology is recorded in
+ * this composition. Empty means only a guard (or nothing) is mounted. */
+export function decisionDispatchEventNames(ctx) {
+    const root = compositionRoot(ctx);
+    const counts = typeof root === 'object' && root !== null
+        ? decisionDispatchTopology.get(root)
+        : undefined;
+    return counts === undefined
+        ? Object.freeze([])
+        : Object.freeze([...counts.keys()].sort());
+}
+/** True when this composition has at least one real DecisionEvents dispatch
+ * source (today: the live channel). Used by host descriptor/admission views. */
+export function hasDecisionDispatchTopology(ctx) {
+    return decisionDispatchEventNames(ctx).length > 0;
+}
+/**
+ * Record that this composition contains a real DecisionEvents dispatch
+ * source for the supplied event names. Called by the channel after it mounts
+ * the dispatch path; never called by guard installation alone.
+ *
+ * Returns a disposer that decrements this source's contribution. Multiple
+ * dispatch sources in the same composition are reference-counted per event,
+ * so unloading one channel does not erase another live channel's topology.
+ *
+ * Lifecycle assumption: in the current TUI the channel is mounted by a
+ * Cordis plugin/context and `createChannel()` registers this disposer in that
+ * context's effect cleanup, so unloading the owning context unmarks the
+ * topology. If an embedder intentionally treats the channel as a
+ * process-level singleton and never disposes the owning context, the marker
+ * persists for the process lifetime — matching the singleton assumption and
+ * not leaking across unloaded channels. Tests can always call the disposer or
+ * `unmarkDecisionDispatchTopology()` explicitly to prove post-unload
+ * behavior.
+ */
+export function markDecisionDispatchTopology(ctx, events = TUI_DECISION_EVENT_NAMES) {
+    const root = compositionRoot(ctx);
+    if (typeof root !== 'object' || root === null)
+        return () => undefined;
+    const known = new Set(TUI_DECISION_EVENT_NAMES);
+    const added = [];
+    let counts = decisionDispatchTopology.get(root);
+    if (counts === undefined) {
+        counts = new Map();
+        decisionDispatchTopology.set(root, counts);
+    }
+    for (const event of events) {
+        if (!known.has(event))
+            continue;
+        counts.set(event, (counts.get(event) ?? 0) + 1);
+        added.push(event);
+    }
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        unmarkDecisionDispatchTopology(ctx, added);
+    };
+}
+/**
+ * Remove this composition's DecisionEvents dispatch topology registration for
+ * the supplied events (defaults to all known events). Also available as the
+ * disposer returned by `markDecisionDispatchTopology()`; `createChannel()`
+ * calls it when the channel's Cordis effect/context is unloaded.
+ */
+export function unmarkDecisionDispatchTopology(ctx, events = TUI_DECISION_EVENT_NAMES) {
+    const root = compositionRoot(ctx);
+    if (typeof root !== 'object' || root === null)
+        return;
+    const counts = decisionDispatchTopology.get(root);
+    if (counts === undefined)
+        return;
+    const known = new Set(TUI_DECISION_EVENT_NAMES);
+    for (const event of events) {
+        if (!known.has(event))
+            continue;
+        const remaining = (counts.get(event) ?? 0) - 1;
+        if (remaining > 0)
+            counts.set(event, remaining);
+        else
+            counts.delete(event);
+    }
+    if (counts.size === 0)
+        decisionDispatchTopology.delete(root);
+}
+/** Read-only DecisionEvents feature probe: reports only event names that have
+ * BOTH a guard and a real channel/dispatch topology in this composition. It
+ * creates no subscription and is used by the live-driver evidence path. */
+export function probeDecisionEventFeatures(ctx) {
+    const root = compositionRoot(ctx);
+    if (typeof root !== 'object' || root === null || !guardedRoots.has(root))
+        return Object.freeze([]);
+    return decisionDispatchEventNames(ctx);
+}
+export function installDecisionGuard(ctx, grants) {
+    // Degraded/fake contexts (minimal embedders, test harnesses) may lack
+    // `root` or `on` entirely — the gate is best-effort there, matching the
+    // channel's soft-degradation posture: no dedup bookkeeping without a root
+    // object, no hook without an `on`.
+    const root = compositionRoot(ctx);
+    // Keep the live grant source even when another row installed the Cordis
+    // hook first.  The file-backed GrantStore evaluates each operation again.
+    registryFor(ctx, grants);
+    if (typeof root === 'object' && root !== null) {
+        if (guardedRoots.has(root))
+            return;
+        guardedRoots.add(root);
+    }
+    if (typeof ctx.on !== 'function')
+        return;
+    ctx.on('internal/listener', function (name, listener) {
+        if (typeof name !== 'string')
+            return undefined;
+        const permission = DECISION_EVENT_PERMISSIONS[name];
+        if (permission === undefined && !TUI_DECISION_EVENT_NAMES.includes(name))
+            return undefined;
+        // `this` is the SUBSCRIBING context (cordis binds internal/listener
+        // hooks to it). A fiber name is used below only for a refusal diagnostic;
+        // authorization always comes from the verified Component identity.
+        let pluginName = 'root';
+        try {
+            const resolved = this.fiber?.name;
+            if (typeof resolved === 'string' && resolved !== '')
+                pluginName = resolved;
+        }
+        catch {
+            // A degraded context without fiber access: fall back to 'root'.
+        }
+        const identity = componentIdentityOf(this);
+        // The public Cordis surface remains usable, but it is mediated into the
+        // same registry as subscribeDecision: a verified Component, static
+        // DecisionEvents requirement, normalized scope and live grant are all
+        // required before the raw listener is ever visible to dispatch. Cordis
+        // treats a truthy internal/listener result as a bail/disposer, so returning
+        // the registry release function prevents a second unmediated registration.
+        if (identity !== undefined && typeof listener === 'function') {
+            try {
+                return registerDecisionHandler(this, identity, name, listener, {});
+            }
+            catch (error) {
+                try {
+                    this.logger.warn(`dsh-tui: ${name} subscription from Component "${identity.componentId}" denied — ` +
+                        `${error instanceof Error ? error.message : String(error)}`);
+                }
+                catch { /* best effort */ }
+                return () => false;
+            }
+        }
+        const requiredGrant = permission === undefined ? '' : `; required grant ${permission}`;
+        ctx.logger.warn(`dsh-tui: ${name} direct subscription from Component "${pluginName}" denied${requiredGrant} — ` +
+            'use the mediated DecisionEvents activation surface; the listener was NOT registered');
+        // Truthy bail result: cordis skips the registration and hands this back
+        // as the caller's disposer — a no-op keeps the ctx.on contract intact.
+        return () => false;
+    }, { global: true, prepend: true });
+}

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

@@ -0,0 +1,145 @@
+/**
+ * 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';
+/** Option of a select dialog. `id` is what the promise resolves with. */
+export interface TuiDialogSelectOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+/** What the chat screen renders while a dialog is pending. */
+export type TuiDialogSnapshot = {
+    readonly key: string;
+    readonly kind: 'select';
+    readonly title: string;
+    readonly options: readonly TuiDialogSelectOption[];
+} | {
+    readonly key: string;
+    readonly kind: 'confirm';
+    readonly title: string;
+    readonly message?: string;
+    readonly confirmLabel: string;
+    readonly cancelLabel: string;
+} | {
+    readonly key: string;
+    readonly kind: 'input';
+    readonly title: string;
+    readonly placeholder?: string;
+    readonly initial: string;
+};
+/** Common request options. */
+export interface TuiDialogBase {
+    /** Dialog title (rendered bold). Control chars are stripped. */
+    title: string;
+    /** Cancels the request when fired — the pi `signal` option. */
+    signal?: AbortSignal;
+    /** Auto-cancel after this many ms. Guards against a wedged flow when no
+     *  TUI consumer is present (headless embedders). */
+    timeoutMs?: number;
+}
+export interface TuiDialogSelectRequest extends TuiDialogBase {
+    options: readonly TuiDialogSelectOption[];
+}
+export interface TuiDialogConfirmRequest extends TuiDialogBase {
+    message?: string;
+    /** Empty/absent labels fall back to the host's localized defaults. */
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+export interface TuiDialogInputRequest extends TuiDialogBase {
+    placeholder?: string;
+    initial?: string;
+}
+/** Settled value of the active dialog: the select id, the confirm boolean,
+ *  or the input text. `undefined` means cancelled. */
+export type TuiDialogAnswer = string | boolean | undefined;
+/** Distributive Omit: `Omit` over a union collapses to the shared members
+ *  only, which would strip kind-specific fields from the ask() input. */
+type WithoutKey<T> = T extends unknown ? Omit<T, 'key'> : never;
+/** 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 declare const INPUT_CELLS = 500;
+/** Bound a request that omits both signal and timeout. */
+export declare const DIALOG_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * 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 declare class TuiDialogStore {
+    private readonly listeners;
+    private readonly queue;
+    private active;
+    /** Park a request. The snapshot argument must already be sanitized. */
+    ask(snapshot: WithoutKey<TuiDialogSnapshot>, signal?: AbortSignal, timeoutMs?: number, owner?: Context, bindOwnerEffect?: (disposer: () => unknown, onRegistered: (cleanup: () => unknown) => void) => boolean): Promise<TuiDialogAnswer>;
+    /** The dialog the UI should render right now, if any. */
+    getSnapshot(): TuiDialogSnapshot | 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: string, value: TuiDialogAnswer): void;
+    /** Cancel the active dialog (Esc). Keyed like {@link decide}: a stale
+     *  panel's Esc must not close the successor it never rendered. */
+    cancel(key: string): void;
+    /** Settle everything queued + active (teardown): all resolve cancelled. */
+    settleAll(): void;
+    subscribe(listener: () => void): () => void;
+    private advance;
+    private emit;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiDialogs: TuiDialogRuntime;
+    }
+}
+/**
+ * `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 declare class TuiDialogRuntime extends Service {
+    constructor(ctx: Context);
+    /** 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. */
+    private callContext;
+    private timeoutOf;
+    /** Pick one of `options`; resolves the option id, or undefined on cancel. */
+    select(request: TuiDialogSelectRequest): Promise<string | undefined>;
+    select(owner: Context, request: TuiDialogSelectRequest): Promise<string | undefined>;
+    /** Yes/no question; resolves the boolean, false on cancel. */
+    confirm(request: TuiDialogConfirmRequest): Promise<boolean>;
+    confirm(owner: Context, request: TuiDialogConfirmRequest): Promise<boolean>;
+    /** Free-text input; resolves the text, or undefined on cancel. */
+    input(request: TuiDialogInputRequest): Promise<string | undefined>;
+    input(owner: Context, request: TuiDialogInputRequest): Promise<string | undefined>;
+}
+export declare function getHostDialogStore(runtime: TuiDialogRuntime | undefined): TuiDialogStore | undefined;
+export default TuiDialogRuntime;
+//# sourceMappingURL=dialogs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dialogs.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/dialogs.ts"],"names":[],"mappings":"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"}