@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,111 @@
+/** Max chars of recent activity fed to the recap call. */
+export const RECAP_RECENT_CHARS = 6000;
+/** How many exchanges (user + assistant) the recap looks back. */
+const RECAP_RECENT_TURNS = 6;
+/** The first text block of a message `content` payload. */
+function textOfContent(content) {
+    if (typeof content === 'string')
+        return content.trim() || undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (record['type'] !== 'text')
+            continue;
+        const value = record['text'];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+/**
+ * Collect the most recent user/assistant exchanges from a session event
+ * log as plain `role: text` lines, capped to the tail turns and a char
+ * budget. Rows derived from the log (tool cards, notices) are skipped —
+ * the recap wants the conversation, not the chrome.
+ */
+export function collectRecentActivity(events, limitChars) {
+    const entries = [];
+    for (const event of events) {
+        const record = event;
+        if (record['type'] === 'user/message') {
+            const data = record['data'];
+            const text = textOfContent(data?.['content']);
+            if (text !== undefined)
+                entries.push({ role: 'user', text });
+            continue;
+        }
+        if (record['type'] === 'assistant/message') {
+            const data = record['data'];
+            const message = data?.['message'];
+            const text = textOfContent(message?.['content']);
+            if (text !== undefined)
+                entries.push({ role: 'assistant', text });
+        }
+    }
+    const tail = entries.slice(-RECAP_RECENT_TURNS * 2);
+    let budget = limitChars;
+    // Admit NEWEST first: the recap exists to summarize where the session
+    // STANDS, so the most recent exchanges must survive a long entry eating
+    // the budget — oldest-first admission lets one oversized message starve
+    // every exchange after it (the very ones a recap is for).
+    const picked = [];
+    for (const entry of [...tail].reverse()) {
+        if (budget <= 0)
+            break;
+        const text = entry.text.length > budget ? entry.text.slice(0, budget) : entry.text;
+        picked.push({ role: entry.role, text });
+        budget -= text.length + entry.role.length + 2;
+    }
+    // Present in chronological order (oldest → newest) for readable quoting.
+    picked.reverse();
+    return picked.map(entry => `${entry.role}: ${entry.text}`).join('\n');
+}
+/**
+ * Wrap the recent-activity excerpt with the single-response, JSON-only
+ * recap contract. The model answers with a title + one-line summary in
+ * the language of the activity (matching the user's own words).
+ */
+export function wrapRecapPrompt(activity) {
+    return `Create a compact session recap from the activity excerpt below.
+Use the user's language and describe the work and its current outcome accurately.
+Return one JSON object with two string fields:
+- "title": a descriptive title of about 2-6 words.
+- "summary": one line of about 10-20 words covering the most recent progress.
+Do not include Markdown fences or any text outside the JSON object.
+
+Activity excerpt:
+${activity}`;
+}
+/**
+ * Parse the model's recap response: extract the JSON object (tolerating
+ * stray prose around it); on failure the whole text becomes the summary
+ * and no title is proposed.
+ */
+export function parseRecapResponse(raw) {
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    if (start !== -1 && end > start) {
+        try {
+            const parsed = JSON.parse(raw.slice(start, end + 1));
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const record = parsed;
+                const summary = typeof record['summary'] === 'string' && record['summary'].trim() !== ''
+                    ? record['summary'].trim()
+                    : undefined;
+                const title = typeof record['title'] === 'string' && record['title'].trim() !== ''
+                    ? record['title'].trim()
+                    : undefined;
+                if (summary !== undefined) {
+                    return title === undefined ? { summary } : { summary, title };
+                }
+            }
+        }
+        catch {
+            // Fall through to the raw-text fallback below.
+        }
+    }
+    return { summary: raw.trim() };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Custom session-entry renderers — pi's `pi.registerMessageRenderer`. A
+ * plugin that appends its own log-only session events (`session.append(
+ * 'my-plugin/event', payload)`) registers a renderer mapping the payload to
+ * plain TEXT rows; the channel then projects those events into the
+ * transcript on the live stream and on replay (resume/rewind), exactly like
+ * its built-in projection of `activity/status` or `agent-preset/selected`.
+ *
+ * Renderers are text-only by design: the full-React surface is the scenes
+ * seam (`ctx.tuiScenes`, with the host-React contract); transcript rows are
+ * shared with replay paths where a crash mid-replay would corrupt the whole
+ * screen, so a renderer never receives React and its output is sanitized
+ * (control chars stripped, lines preview-clipped like `pushLocal` output).
+ *
+ * Registration rules (untrusted-input discipline):
+ *
+ * - The type must look like `plugin/event` (kebab, one slash) — this is the
+ *   same shape the session-log strict registry expects plugins to register.
+ * - Core vocabulary is off-limits: a renderer can never shadow a built-in
+ *   event type's projection (locals win, same as commands).
+ * - A renderer that throws is skipped for THAT event and logged once per
+ *   type — replay must survive a buggy plugin.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** What a renderer returns: an optional title row plus body lines. */
+export interface TuiEntryRenderResult {
+    /** Short heading (rendered as a notice row); omit for a body-only entry. */
+    title?: string;
+    /** Body rows, oldest-to-newest reading order. */
+    lines: readonly string[];
+}
+export type TuiEntryRenderer = (payload: unknown) => TuiEntryRenderResult | undefined;
+/** Host-only transcript projection path. Plugins can register a renderer but
+ * cannot invoke an arbitrary registered renderer on demand. */
+export interface TuiRendererHost {
+    register(type: string, renderer: TuiEntryRenderer): () => void;
+    render(type: string, payload: unknown): TuiEntryRenderResult | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiRenderers: TuiRendererRuntime;
+    }
+}
+/** `ctx.tuiRenderers` — custom session-entry text renderers. */
+export declare class TuiRendererRuntime extends Service {
+    constructor(ctx: Context);
+    /**
+     * Map a log-only session event type to transcript rows. Returns the
+     * dispose function (caller scopes it with `ctx.effect`, same contract as
+     * `tuiScenes`). Refusals warn instead of throwing. The optional trailing
+     * `identity` (the plugin's own ctx) only feeds the effect ledger's
+     * pluginId — omitting it records `undeclared` (C-060).
+     */
+    register(type: string, renderer: TuiEntryRenderer, identity?: Context): () => void;
+}
+export declare function getHostRenderers(runtime: TuiRendererRuntime | undefined): TuiRendererHost | undefined;
+export default TuiRendererRuntime;
+//# sourceMappingURL=renderers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/renderers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAUtD,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,GAAG,SAAS,CAAA;AAErF;+DAC+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAA;IAC9D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CAAA;CACzE;AAsBD,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,YAAY,EAAE,kBAAkB,CAAA;KACjC;CACF;AAED,gEAAgE;AAChE,qBAAa,kBAAmB,SAAQ,OAAO;gBACjC,GAAG,EAAE,OAAO;IAmCxB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;CA+DnF;AA6CD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAOrG;AAED,eAAe,kBAAkB,CAAA"}

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

@@ -0,0 +1,198 @@
+/**
+ * Custom session-entry renderers — pi's `pi.registerMessageRenderer`. A
+ * plugin that appends its own log-only session events (`session.append(
+ * 'my-plugin/event', payload)`) registers a renderer mapping the payload to
+ * plain TEXT rows; the channel then projects those events into the
+ * transcript on the live stream and on replay (resume/rewind), exactly like
+ * its built-in projection of `activity/status` or `agent-preset/selected`.
+ *
+ * Renderers are text-only by design: the full-React surface is the scenes
+ * seam (`ctx.tuiScenes`, with the host-React contract); transcript rows are
+ * shared with replay paths where a crash mid-replay would corrupt the whole
+ * screen, so a renderer never receives React and its output is sanitized
+ * (control chars stripped, lines preview-clipped like `pushLocal` output).
+ *
+ * Registration rules (untrusted-input discipline):
+ *
+ * - The type must look like `plugin/event` (kebab, one slash) — this is the
+ *   same shape the session-log strict registry expects plugins to register.
+ * - Core vocabulary is off-limits: a renderer can never shadow a built-in
+ *   event type's projection (locals win, same as commands).
+ * - A renderer that throws is skipped for THAT event and logged once per
+ *   type — replay must survive a buggy plugin.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session';
+import { cleanRenderText } from './sanitize.js';
+import { bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+const TYPE_PATTERN = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/u;
+/**
+ * The built-in session-event vocabulary, FROZEN at module load. The live
+ * KNOWN_SESSION_EVENT_TYPES set cannot serve as this denylist: a plugin
+ * persisting custom events MUST add its types to that set (seam 1's hard
+ * rule), so by the time it registers a renderer for `my-plugin/note`, the
+ * mutable set already contains `my-plugin/note` — checking against it would
+ * reject exactly the types this seam exists for. The module-load snapshot
+ * (this service's row mounts before any plugin row) is the built-in truth.
+ */
+const BUILTIN_SESSION_EVENT_TYPES = new Set(KNOWN_SESSION_EVENT_TYPES);
+/** Output bounds (render-path hygiene): a renderer runs on the REPLAY path
+ *  too, where an unbounded result would synchronously create thousands of
+ *  transcript rows. Sanitization itself lives in ./sanitize.js. */
+const MAX_RENDER_LINES = 100;
+const TITLE_CELLS = 120;
+const LINE_CELLS = 400;
+/** `ctx.tuiRenderers` — custom session-entry text renderers. */
+export class TuiRendererRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiRenderers');
+        compositionRoot(ctx);
+        const runtime = this;
+        const state = {
+            renderers: new Map(),
+            failedTypes: new Set(),
+            host: undefined,
+            logger: ctx.logger,
+            runtime: adapterRuntimeFor(ctx),
+        };
+        const host = Object.freeze({
+            register: (type, renderer) => {
+                const state = rendererStateFor(runtime);
+                let normalized;
+                try {
+                    normalized = String(type ?? '').trim().toLowerCase();
+                }
+                catch {
+                    return () => { };
+                }
+                if (!TYPE_PATTERN.test(normalized) || typeof renderer !== 'function' || state.renderers.has(normalized)) {
+                    return () => { };
+                }
+                state.renderers.set(normalized, renderer);
+                return () => {
+                    if (state.renderers.get(normalized) !== renderer)
+                        return;
+                    state.renderers.delete(normalized);
+                };
+            },
+            render: (type, payload) => renderEntry(runtime, type, payload),
+        });
+        state.host = host;
+        hostRenderers.set(runtime, state);
+    }
+    /**
+     * Map a log-only session event type to transcript rows. Returns the
+     * dispose function (caller scopes it with `ctx.effect`, same contract as
+     * `tuiScenes`). Refusals warn instead of throwing. The optional trailing
+     * `identity` (the plugin's own ctx) only feeds the effect ledger's
+     * pluginId — omitting it records `undeclared` (C-060).
+     */
+    register(type, renderer, identity) {
+        assertCapabilityShadowPolicy('host.renderers.register', rendererStateFor(this).runtime.mode, rendererStateFor(this).runtime.slices);
+        let caller;
+        try {
+            caller = requirePluginCaller(this.ctx, 'tuiRenderers.register', this);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiRenderers.register requires a live non-root plugin activation');
+            return () => { };
+        }
+        const state = rendererStateFor(this);
+        let normalized;
+        try {
+            normalized = String(type ?? '').trim().toLowerCase();
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiRenderers.register rejected an uncoercible event type');
+            return () => { };
+        }
+        if (!TYPE_PATTERN.test(normalized)) {
+            this.ctx.logger.warn('dsh-tui: tuiRenderers.register rejected an invalid event type');
+            return () => { };
+        }
+        // The channel's own projection (its renderEvent switch plus special-
+        // cased plugin events like agent-preset/selected) always wins. The check
+        // uses the module-load snapshot of the built-in vocabulary — NOT the live
+        // KNOWN_SESSION_EVENT_TYPES, which plugins must extend with their own
+        // types (see BUILTIN_SESSION_EVENT_TYPES above).
+        if (BUILTIN_SESSION_EVENT_TYPES.has(normalized) || normalized === 'agent-preset/selected') {
+            this.ctx.logger.warn(`dsh-tui: tuiRenderers.register rejected "${normalized}" — built-in event types keep their own projection`);
+            return () => { };
+        }
+        if (state.renderers.has(normalized)) {
+            this.ctx.logger.warn(`dsh-tui: tuiRenderers.register rejected "${normalized}" — already registered`);
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'create',
+                resource: { kind: 'renderer', id: normalized },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
+            return () => { };
+        }
+        if (typeof renderer !== 'function') {
+            this.ctx.logger.warn(`dsh-tui: tuiRenderers.register rejected "${normalized}" — renderer must be a function`);
+            return () => { };
+        }
+        state.renderers.set(normalized, renderer);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'renderer', id: normalized }, result: 'applied' }, identity);
+        const dispose = () => {
+            if (state.renderers.get(normalized) !== renderer)
+                return;
+            state.renderers.delete(normalized);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'renderer', id: normalized }, result: 'applied' }, identity);
+        };
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+}
+const hostRenderers = new WeakMap();
+function rendererStateFor(runtime) {
+    const state = hostRenderers.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiRenderers host state is unavailable');
+    return state;
+}
+function renderEntry(runtime, type, payload) {
+    const state = rendererStateFor(runtime);
+    const renderer = state.renderers.get(type);
+    if (renderer === undefined)
+        return undefined;
+    try {
+        const result = renderer(payload);
+        if (result === undefined)
+            return undefined;
+        const raw = result;
+        if (!Array.isArray(raw.lines))
+            return undefined;
+        const lines = [];
+        for (const line of raw.lines) {
+            if (lines.length >= MAX_RENDER_LINES)
+                break;
+            if (typeof line !== 'string' && typeof line !== 'number' && typeof line !== 'boolean')
+                continue;
+            lines.push(cleanRenderText(String(line), LINE_CELLS));
+        }
+        const title = typeof raw.title === 'string' ? cleanRenderText(raw.title, TITLE_CELLS) : undefined;
+        return { ...(title === undefined || title === '' ? {} : { title }), lines };
+    }
+    catch (error) {
+        if (!state.failedTypes.has(type)) {
+            state.failedTypes.add(type);
+            state.logger.warn(`dsh-tui: renderer for "${type}" threw; its entries are skipped: %o`, error);
+        }
+        return undefined;
+    }
+}
+export function getHostRenderers(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return hostRenderers.get(concreteService(runtime))?.host;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiRendererRuntime;

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

@@ -0,0 +1,45 @@
+/**
+ * The render-path sanitization contract for plugin-supplied text — the
+ * single implementation behind every managed-UI seam (dialogs, status line,
+ * entry renderers, rewind modes, decision notices). TUI-PROP-009 Track A
+ * makes these rules normative, so they live in exactly one place:
+ *
+ * - C0/C1 control chars are stripped (replaced by a space) — plugin text
+ *   must never smuggle escape sequences onto the screen;
+ * - whitespace collapses to single spaces (render paths are single-line);
+ * - width is capped in terminal CELLS (never string.length) with an
+ *   ellipsis.
+ *
+ * Non-scalar input is DROPPED, never `String()`-coerced — `String({})`
+ * would put "[object Object]" on the render path. Scalars
+ * (string/number/boolean) coerce through String() first.
+ */
+/** Sanitize an already-string value for the render path. */
+export declare function cleanRenderText(value: string, maxCells: number): string;
+/**
+ * Sanitize an untrusted (possibly non-string) value. Non-scalars — objects,
+ * arrays, functions, symbols, null/undefined — yield '' so the caller takes
+ * its drop/refuse path; scalars coerce then sanitize.
+ */
+export declare function cleanScalarText(value: unknown, maxCells: number): string;
+/**
+ * Truncate to a cell budget WITHOUT ellipsis, whitespace folding, or any
+ * other mutation — the editing-path counterpart of {@link cleanRenderText}.
+ * An input panel caps what the user types/pastes; inserting '…' or
+ * collapsing their spaces would corrupt text they can still edit.
+ */
+export declare function capCells(value: string, maxCells: number): string;
+/** C0/C1 control chars → space, nothing else touched. The single-line
+ *  input panel flattens pasted chunks with this (newlines become spaces —
+ *  the panel has no second row for them). */
+export declare function flattenInline(value: string): string;
+/**
+ * Single-line field ingress for terminal/clipboard paste: strip COMPLETE
+ * ANSI/OSC sequences first (paste content is user-controlled bytes — a
+ * smuggled ESC[… would otherwise break out of the render path), then flatten
+ * every remaining C0/C1 control char to a space. Unlike {@link flattenInline},
+ * this never leaves `[31m`-style residue behind; the two regexes mirror
+ * {@link cleanRenderText}'s strip, and the final pass covers the rest.
+ */
+export declare function flattenPasteInline(value: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAevE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;6CAE6C;AAC7C,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxD"}

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

@@ -0,0 +1,84 @@
+/**
+ * The render-path sanitization contract for plugin-supplied text — the
+ * single implementation behind every managed-UI seam (dialogs, status line,
+ * entry renderers, rewind modes, decision notices). TUI-PROP-009 Track A
+ * makes these rules normative, so they live in exactly one place:
+ *
+ * - C0/C1 control chars are stripped (replaced by a space) — plugin text
+ *   must never smuggle escape sequences onto the screen;
+ * - whitespace collapses to single spaces (render paths are single-line);
+ * - width is capped in terminal CELLS (never string.length) with an
+ *   ellipsis.
+ *
+ * Non-scalar input is DROPPED, never `String()`-coerced — `String({})`
+ * would put "[object Object]" on the render path. Scalars
+ * (string/number/boolean) coerce through String() first.
+ */
+import { stringWidth } from '../ink/stringWidth.js';
+/** Sanitize an already-string value for the render path. */
+export function cleanRenderText(value, maxCells) {
+    // Remove complete ANSI control sequences before stripping control bytes.
+    // Otherwise an SGR such as ESC[31m becomes the visible garbage "[31m".
+    const withoutAnsi = value
+        .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/gu, '')
+        .replace(/\u001B\[[0-?]*[ -/]*[@-~]/gu, '');
+    // eslint-disable-next-line no-control-regex -- deliberate: sanitize untrusted render-path text
+    const flat = withoutAnsi.replace(/[\x00-\x1f\x7f-\x9f]/g, ' ').replace(/\s+/g, ' ').trim();
+    if (stringWidth(flat) <= maxCells)
+        return flat;
+    let out = '';
+    for (const ch of flat) {
+        if (stringWidth(out + ch) > maxCells - 1)
+            break;
+        out += ch;
+    }
+    return `${out}…`;
+}
+/**
+ * Sanitize an untrusted (possibly non-string) value. Non-scalars — objects,
+ * arrays, functions, symbols, null/undefined — yield '' so the caller takes
+ * its drop/refuse path; scalars coerce then sanitize.
+ */
+export function cleanScalarText(value, maxCells) {
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        return '';
+    return cleanRenderText(String(value), maxCells);
+}
+/**
+ * Truncate to a cell budget WITHOUT ellipsis, whitespace folding, or any
+ * other mutation — the editing-path counterpart of {@link cleanRenderText}.
+ * An input panel caps what the user types/pastes; inserting '…' or
+ * collapsing their spaces would corrupt text they can still edit.
+ */
+export function capCells(value, maxCells) {
+    if (stringWidth(value) <= maxCells)
+        return value;
+    let out = '';
+    for (const ch of value) {
+        if (stringWidth(out + ch) > maxCells)
+            break;
+        out += ch;
+    }
+    return out;
+}
+/** C0/C1 control chars → space, nothing else touched. The single-line
+ *  input panel flattens pasted chunks with this (newlines become spaces —
+ *  the panel has no second row for them). */
+export function flattenInline(value) {
+    // eslint-disable-next-line no-control-regex -- deliberate: sanitize untrusted render-path text
+    return value.replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
+}
+/**
+ * Single-line field ingress for terminal/clipboard paste: strip COMPLETE
+ * ANSI/OSC sequences first (paste content is user-controlled bytes — a
+ * smuggled ESC[… would otherwise break out of the render path), then flatten
+ * every remaining C0/C1 control char to a space. Unlike {@link flattenInline},
+ * this never leaves `[31m`-style residue behind; the two regexes mirror
+ * {@link cleanRenderText}'s strip, and the final pass covers the rest.
+ */
+export function flattenPasteInline(value) {
+    const withoutAnsi = value
+        .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/gu, '')
+        .replace(/\u001B\[[0-?]*[ -/]*[@-~]/gu, '');
+    return flattenInline(withoutAnsi);
+}

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

@@ -0,0 +1,87 @@
+/** Provider-neutral full-screen scene registry for terminal front doors. */
+import type React from 'react';
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ChannelUi as Channel } from '../adapter/channel/ui-policy.js';
+/**
+ * Props every plugin scene receives. Both element creation and hooks must go
+ * through the HOST's React, never the plugin's own copy:
+ *
+ * - Hooks: a component rendered by this TUI's reconciler but calling hooks
+ *   imported from a second React copy (the plugin's own node_modules) dies
+ *   with an invalid-hook-call on first render. Use the injected `React`.
+ * - Elements: this app's reconciler (React 19) accepts only
+ *   `Symbol.for('react.transitional.element')` elements. JSX compiled
+ *   against a plugin-bundled older React emits `Symbol.for('react.element')`
+ *   and throws on first render. Create elements with the injected `React`
+ *   (`React.createElement`/`React.Fragment`), or compile JSX against the
+ *   host runtime via tsconfig
+ *   `"jsxImportSource": "dsh-cli"` (its `./jsx-runtime`
+ *   subpath re-exports this app's own react/jsx-runtime). A plugin-owned
+ *   React copy works ONLY if it is the same React 19 line — and its hooks
+ *   remain off-limits regardless.
+ */
+export interface TuiSceneProps {
+    /** The TUI's React instance — use THIS for every hook and element. */
+    React: typeof React;
+    /** The TUI's ui kit (Box/Text/useInput/useTerminalSize/…). */
+    ui: typeof import('../ui.js');
+    /** Live session channel: rows, status, trace events, notifications. */
+    channel: Channel;
+    /** Leave the scene and return to whatever screen was up before. */
+    close(): void;
+}
+export interface TuiSceneDescriptor {
+    /** Unique scene id (kebab-case); the plugin's own commands open it by id. */
+    id: string;
+    /** Optional human label for logs/debugging; the scene renders its own header. */
+    title?: string;
+    component: React.ComponentType<TuiSceneProps>;
+}
+/** Host-only scene controls used by the channel; omitted from the plugin export. */
+export interface TuiSceneHost {
+    readonly active: TuiSceneDescriptor | undefined;
+    register(descriptor: TuiSceneDescriptor): () => void;
+    list(): readonly TuiSceneDescriptor[];
+    open(id: string): boolean;
+    close(): void;
+    subscribe(listener: () => void): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiScenes: TuiSceneRuntime;
+    }
+}
+export declare const name = "dsh-tui-scenes";
+/**
+ * Small host-only registry; command execution remains owned by dsh-commands.
+ *
+ * A plugin registers a scene once (`ctx.tuiScenes.register(...)`, keep the
+ * dispose) and opens it from anywhere host-side — typically its own
+ * dsh-commands handler: `ctx.tuiScenes.open('my-scene')` plus a silent
+ * `success` result, so the conversation stays untouched while the scene
+ * takes the whole terminal the way the trajectory scene does.
+ */
+export declare class TuiSceneRuntime extends Service {
+    constructor(ctx: Context);
+    /**
+     * Register a full-screen scene; returns the dispose function (caller
+     * scopes it with `ctx.effect`). The optional trailing `identity` (the
+     * plugin's own ctx) only feeds the effect ledger's pluginId — omitting it
+     * records `undeclared` (C-060).
+     */
+    register(descriptor: TuiSceneDescriptor, identity?: Context): () => void;
+    /**
+     * Swap the conversation for the named scene. Returns false (and warns)
+     * when no plugin registered that id — a mistyped id must fail visibly in
+     * the log, not silently do nothing in the UI.
+     */
+    open(id: string): boolean;
+    close(): void;
+    /** The scene currently replacing the conversation, if any. */
+    get active(): TuiSceneDescriptor | undefined;
+    /** UI-side change feed: fired after every open/close/dispose transition. */
+    subscribe(listener: () => void): () => void;
+}
+export declare function getHostSceneRuntime(runtime: TuiSceneRuntime | undefined): TuiSceneHost | undefined;
+export default TuiSceneRuntime;
+//# sourceMappingURL=scenes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/scenes.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,IAAI,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAS3E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,8DAA8D;IAC9D,EAAE,EAAE,cAAc,UAAU,CAAC,CAAA;IAC7B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;IAChB,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAA;IACV,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,CAAA;CAC9C;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IACpD,IAAI,IAAI,SAAS,kBAAkB,EAAE,CAAA;IACrC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,KAAK,IAAI,IAAI,CAAA;IACb,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,SAAS,EAAE,eAAe,CAAA;KAC3B;CACF;AAED,eAAO,MAAM,IAAI,mBAAmB,CAAA;AAEpC;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,OAAO;gBAC9B,GAAG,EAAE,OAAO;IAkDxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IAkDxE;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAOzB,KAAK,IAAI,IAAI;IAOb,8DAA8D;IAC9D,IAAI,MAAM,IAAI,kBAAkB,GAAG,SAAS,CAQ3C;IAED,4EAA4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAU5C;AAmED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAOlG;AAED,eAAe,eAAe,CAAA"}