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

package/lib/types/dsh-adapter/plugins-info.js

@@ -0,0 +1,276 @@
+/**
+ * /plugins diagnostics surface (C-070 trust disclosure + C-030 negotiation
+ * diagnostics): assembles the lines behind the `/plugins` command.
+ *
+ * Sections (overview):
+ *
+ * 1. TRUST BANNER — always the first line (C-070): plugins run in-process;
+ *    grants are behavioral constraints, not a security boundary; passing
+ *    validation is not proof of safety.
+ * 2. HOST DESCRIPTOR summary — what the running host actually advertises
+ *    (coordinates + generation), including drift-dropped contracts.
+ * 3. GRANT MATRIX — plugins × the registered permissions. The plugin set is
+ *    the union of FOOTPRINTS ONLY: keys of the grants file, pluginIds seen
+ *    in the effect ledger, and storage namespaces on disk (the host cannot
+ *    enumerate installed plugins — that knowledge lives in the dsh CLI
+ *    Loader). The header says so honestly.
+ * 4. LEDGER TAIL — the last 5 effect-ledger records.
+ *
+ * `/plugins check <path>` uses the parser and projection from the pinned
+ * @dsh-std/manifest revision, then evaluates every public/private protocol
+ * through one ProtocolCatalog. Manifests and on-disk files are UNTRUSTED input:
+ * every derived line passes cleanScalarText before it reaches the
+ * transcript.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseManifest, projectManifest } from '@dsh-std/manifest';
+import { DATA_DIR } from '../utils/paths.js';
+import { t } from '../i18n.js';
+import { loadSpecData } from '../plugin-spec/registry.js';
+import { createContractIndex, validatePlugin } from '../plugin-spec/validate.js';
+import { negotiate } from '../plugin-spec/negotiate.js';
+import { cleanScalarText } from './sanitize.js';
+import { buildHostDescriptor } from './host-descriptor.js';
+import { PLUGIN_STORAGE_DIR } from './plugin-storage.js';
+import { EFFECT_LEDGER_FILE } from './effect-ledger.js';
+/** How many plugins the matrix shows before an overflow note. */
+export const PLUGINS_MATRIX_MAX_ROWS = 20;
+/** How many ledger records the tail section shows. */
+export const PLUGINS_LEDGER_TAIL = 5;
+/** Per-line cell cap for file-derived content. */
+const LINE_CELLS = 200;
+const cell = (value) => cleanScalarText(String(value ?? ''), LINE_CELLS);
+/** Parse the ledger file tolerantly (skip corrupt lines, never throw). */
+function readLedgerRecords(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null && typeof parsed === 'object')
+                records.push(parsed);
+        }
+        catch {
+            // Corrupt line: the diagnostics surface skips it (never rewrites).
+        }
+    }
+    return records;
+}
+/** The plugin set for the matrix: grants-file keys ∪ ledger pluginIds ∪
+ *  storage namespaces ('host'/'undeclared' ledger identities are not
+ *  plugins and are excluded). */
+function footprintPlugins(deps, dataDir, ledgerFile, storageDir) {
+    const found = new Set();
+    try {
+        const raw = JSON.parse(readFileSync(join(dataDir, 'extension-grants.json'), 'utf8'));
+        if (raw !== null && typeof raw === 'object') {
+            const table = raw;
+            for (const section of [table.grants, table.denies]) {
+                if (section !== null && typeof section === 'object') {
+                    for (const plugin of Object.keys(section))
+                        found.add(plugin);
+                }
+            }
+        }
+    }
+    catch {
+        // Missing/corrupt grants file: the GrantStore already answers deny;
+        // the matrix simply has no rows from this source.
+    }
+    for (const record of readLedgerRecords(ledgerFile)) {
+        if (typeof record.pluginId === 'string' && record.pluginId !== '' && record.pluginId !== 'host' && record.pluginId !== 'undeclared') {
+            found.add(record.pluginId);
+        }
+    }
+    try {
+        for (const entry of readdirSync(storageDir)) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const namespace = decodeURIComponent(entry.slice(0, -'.json'.length));
+            if (namespace !== '')
+                found.add(namespace);
+        }
+    }
+    catch {
+        // No storage directory yet: no rows from this source.
+    }
+    void deps;
+    return [...found].sort();
+}
+/** `/plugins check <path>`: official parse/projection + profile validation + negotiation. */
+function checkManifestLines(pathArg, deps) {
+    const lines = [];
+    const target = resolve(pathArg);
+    if (!existsSync(target)) {
+        lines.push(t('plugins-check-not-found', { path: cell(pathArg) }));
+        return lines;
+    }
+    let source;
+    try {
+        source = readFileSync(target, 'utf8');
+    }
+    catch (error) {
+        lines.push(t('plugins-check-invalid-json', { err: cell(error instanceof Error ? error.message : String(error)) }));
+        return lines;
+    }
+    const data = loadSpecData();
+    if (data === undefined) {
+        lines.push(t('plugins-check-spec-unavailable'));
+        return lines;
+    }
+    let manifest;
+    try {
+        manifest = parseManifest(source, { source: target });
+        // Projection is an explicit admission stage. validatePlugin performs its
+        // own defensive projection too, but keeping this call here makes parser
+        // and projection failures distinguishable at the user-facing boundary.
+        projectManifest(manifest);
+    }
+    catch (error) {
+        const message = cell(error instanceof Error ? error.message : String(error));
+        lines.push(error instanceof SyntaxError
+            ? t('plugins-check-invalid-json', { err: message })
+            : t('plugins-check-schema-failed', { err: message }));
+        return lines;
+    }
+    const index = createContractIndex(data.registry, data.permissions);
+    try {
+        validatePlugin(index, manifest);
+    }
+    catch (error) {
+        lines.push(t('plugins-check-invalid', { err: cell(error instanceof Error ? error.message : String(error)) }));
+        return lines;
+    }
+    const host = deps.host ?? buildHostDescriptor({ generationId: 'plugins-check' });
+    const granted = manifest.permissions
+        .map(request => ({
+        name: request.name,
+        scope: request.scope,
+        // `/plugins check` has no live activation instance. Passing an
+        // activation-less principal makes GrantStore fail closed when policy
+        // contains activation-scoped rules instead of treating them as global.
+        granted: deps.grants.allows({ componentId: manifest.id }, request.name, request.scope),
+    }));
+    const decision = negotiate(index, manifest, host.descriptor, granted);
+    lines.push(...decisionLines(decision));
+    if (host.dropped.length > 0) {
+        lines.push(t('plugins-check-dropped', { dropped: cell(host.dropped.join(', ')) }));
+    }
+    return lines;
+}
+function decisionLines(decision) {
+    switch (decision.decision) {
+        case 'compatible':
+            return [t('plugins-check-state', { state: 'compatible' })];
+        case 'compatible_degraded':
+            return [t('plugins-check-state', {
+                    state: `compatible_degraded (missingOptional: ${cell(decision.missingOptional.join(', '))})`,
+                })];
+        case 'waiting_authorization':
+            return [t('plugins-check-state', {
+                    state: `waiting_authorization (${cell(decision.reasonCode)}: ${cell(decision.deniedPermissions.join(', '))})`,
+                })];
+        case 'rejected': {
+            const detail = decision.missingRequired !== undefined
+                ? `${cell(decision.reasonCode)}: ${cell(decision.missingRequired.join(', '))}`
+                : `${cell(decision.reasonCode)}: facet ${cell(decision.facetApiVersion)} vs host [${cell((decision.hostFacetApiVersions ?? []).join(', '))}]`;
+            return [t('plugins-check-state', { state: `rejected (${detail})` })];
+        }
+        case 'unknown':
+            return [t('plugins-check-state', {
+                    state: `unknown (${cell(decision.reasonCode)}: ${cell(decision.unknownContracts.join(', '))})`,
+                })];
+    }
+}
+/** The `/plugins` overview lines (banner always first). */
+export function pluginsInfoLines(args, deps) {
+    const lines = [t('plugins-trust-banner')];
+    const trimmed = args.trim();
+    if (trimmed !== '') {
+        const [sub, ...rest] = trimmed.split(/\s+/);
+        if (sub === 'check') {
+            const pathArg = rest.join(' ');
+            if (pathArg === '') {
+                lines.push(t('plugins-check-usage'));
+                return lines;
+            }
+            lines.push(...checkManifestLines(pathArg, deps));
+            return lines;
+        }
+        lines.push(t('plugins-unknown-subcommand', { sub: cell(sub) }));
+        return lines;
+    }
+    const dataDir = deps.dataDir ?? DATA_DIR;
+    const ledgerFile = deps.ledgerFile ?? EFFECT_LEDGER_FILE;
+    const storageDir = deps.storageDir ?? join(dataDir, PLUGIN_STORAGE_DIR);
+    // ── Host Descriptor ──
+    if (deps.host === undefined) {
+        lines.push(t('plugins-host-unavailable'));
+    }
+    else {
+        const { descriptor, dropped } = deps.host;
+        lines.push(`Host Descriptor: ${cell(descriptor.hostId)} v${cell(descriptor.hostVersion)} · generation ${cell(descriptor.runtime.generationId)}`);
+        lines.push(`  facets: ${cell(descriptor.facetApiVersions.join(', ') || '—')}`);
+        for (const contract of descriptor.contracts) {
+            const definition = contract.definition.source === 'dsh-std'
+                ? contract.definition.package
+                : contract.definition.profileHash.slice(0, 19) + '…';
+            lines.push(`  ${cell(contract.apiVersion)}#${cell(contract.kind)} · definition ${cell(definition)} · perms ${cell(contract.permissions.join(', ') || '—')}`);
+        }
+        for (const coordinate of dropped) {
+            lines.push(`  ${cell(coordinate)} · ${t('plugins-contract-dropped')}`);
+        }
+    }
+    // ── 授权矩阵 ──
+    const plugins = footprintPlugins(deps, dataDir, ledgerFile, storageDir);
+    lines.push(t('plugins-matrix-note'));
+    const permissions = deps.grants.knownPermissions();
+    if (permissions.length === 0) {
+        lines.push(`  ${t('plugins-matrix-no-registry')}`);
+    }
+    else if (plugins.length === 0) {
+        lines.push(`  ${t('plugins-matrix-empty')}`);
+    }
+    else {
+        lines.push(`  ${permissions.map((permission, index) => `[${index + 1}] ${cell(permission)}`).join('  ')}`);
+        const shown = plugins.slice(0, PLUGINS_MATRIX_MAX_ROWS);
+        const width = Math.max(...shown.map(plugin => plugin.length), 8);
+        for (const plugin of shown) {
+            const diagnosticScope = (permission) => {
+                if (permission === 'storage.local.read' || permission === 'storage.local.write')
+                    return plugin;
+                if (permission === 'commands.invoke')
+                    return 'diagnostic.command';
+                return 'session:*';
+            };
+            const marks = permissions.map(permission => (deps.grants.allows({ componentId: plugin }, permission, diagnosticScope(permission)) ? '✓' : '·')).join(' ');
+            lines.push(`  ${cell(plugin).padEnd(width)}  ${marks}`);
+        }
+        if (plugins.length > shown.length) {
+            lines.push(`  ${t('plugins-footprint-overflow', { count: plugins.length - shown.length })}`);
+        }
+    }
+    // ── 台账尾 ──
+    const records = readLedgerRecords(ledgerFile);
+    if (records.length === 0) {
+        lines.push(t('plugins-ledger-empty'));
+    }
+    else {
+        lines.push(t('plugins-ledger-header', { file: cell(ledgerFile) }));
+        for (const record of records.slice(-PLUGINS_LEDGER_TAIL)) {
+            const resource = record.resource ?? {};
+            lines.push(`  #${cell(record.sequence)} ${cell(record.operation)} ${cell(resource.kind)}/${cell(resource.id)} ` +
+                `${cell(record.pluginId)} ${cell(record.result)}${typeof record.errorCode === 'string' ? ` (${cell(record.errorCode)})` : ''}`);
+        }
+    }
+    return lines;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiRenderers: TuiRendererRuntime;
+    }
+}
+/** `ctx.tuiRenderers` — custom session-entry text renderers. */
+export declare class TuiRendererRuntime extends Service {
+    private readonly renderers;
+    private readonly failedTypes;
+    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;
+    /**
+     * Project one event; undefined when no renderer applies, the renderer has
+     * no opinion, or it failed (failure is sticky-logged once per type so a
+     * replayed log does not spam the warn stream per event).
+     *
+     * The result is validated and sanitized INSIDE the try boundary: the title
+     * must be a string (anything else is dropped — a non-string would crash
+     * the React render path), lines are kept to scalars, control chars are
+     * stripped, and the count/width caps bound what a replay can synchronously
+     * lay out.
+     */
+    render(type: string, payload: unknown): TuiEntryRenderResult | 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;AAItD,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;AAsBrF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,YAAY,EAAE,kBAAkB,CAAA;KACjC;CACF;AAED,gEAAgE;AAChE,qBAAa,kBAAmB,SAAQ,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;gBAEpC,GAAG,EAAE,OAAO;IAIxB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IA+ClF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS;CAwBzE;AAED,eAAe,kBAAkB,CAAA"}

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

@@ -0,0 +1,138 @@
+/**
+ * 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';
+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 {
+    renderers = new Map();
+    failedTypes = new Set();
+    constructor(ctx) {
+        super(ctx, 'tuiRenderers');
+    }
+    /**
+     * 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) {
+        const normalized = String(type ?? '').trim().toLowerCase();
+        if (!TYPE_PATTERN.test(normalized)) {
+            this.ctx.logger.warn(`dsh-tui: tuiRenderers.register rejected invalid event type ${JSON.stringify(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 (this.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 () => { };
+        }
+        this.renderers.set(normalized, renderer);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'renderer', id: normalized }, result: 'applied' }, identity);
+        return () => {
+            if (this.renderers.get(normalized) !== renderer)
+                return;
+            this.renderers.delete(normalized);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'renderer', id: normalized }, result: 'applied' }, identity);
+        };
+    }
+    /**
+     * Project one event; undefined when no renderer applies, the renderer has
+     * no opinion, or it failed (failure is sticky-logged once per type so a
+     * replayed log does not spam the warn stream per event).
+     *
+     * The result is validated and sanitized INSIDE the try boundary: the title
+     * must be a string (anything else is dropped — a non-string would crash
+     * the React render path), lines are kept to scalars, control chars are
+     * stripped, and the count/width caps bound what a replay can synchronously
+     * lay out.
+     */
+    render(type, payload) {
+        const renderer = this.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 (!this.failedTypes.has(type)) {
+                this.failedTypes.add(type);
+                this.ctx.logger.warn(`dsh-tui: renderer for "${type}" threw; its entries are skipped: %o`, error);
+            }
+            return undefined;
+        }
+    }
+}
+export default TuiRendererRuntime;

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

@@ -0,0 +1,36 @@
+/**
+ * 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;
+//# 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,CAUvE;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"}

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

@@ -0,0 +1,65 @@
+/**
+ * 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) {
+    // eslint-disable-next-line no-control-regex -- deliberate: sanitize untrusted render-path text
+    const flat = value.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, ' ');
+}

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

@@ -57,7 +57,13 @@ export declare class TuiSceneRuntime extends Service {
     private readonly listeners;
     private current;
     constructor(ctx: Context);
-    register(descriptor: TuiSceneDescriptor): () => void;
+    /**
+     * 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

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

@@ -1 +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,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;;;;;;;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,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;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,OAAO,CAAgC;gBAEnC,GAAG,EAAE,OAAO;IAIxB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAiBpD;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAMb,8DAA8D;IAC9D,IAAI,MAAM,IAAI,kBAAkB,GAAG,SAAS,CAE3C;IAED,4EAA4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,MAAM;CAGf;AAED,eAAe,eAAe,CAAA"}
+{"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,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;;;;;;;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,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;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,OAAO,CAAgC;gBAEnC,GAAG,EAAE,OAAO;IAIxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IAoCxE;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAMb,8DAA8D;IAC9D,IAAI,MAAM,IAAI,kBAAkB,GAAG,SAAS,CAE3C;IAED,4EAA4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,MAAM;CAGf;AAED,eAAe,eAAe,CAAA"}

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

@@ -17,18 +17,33 @@ export class TuiSceneRuntime extends Service {
     constructor(ctx) {
         super(ctx, 'tuiScenes');
     }
-    register(descriptor) {
+    /**
+     * 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, identity) {
         const id = descriptor.id.trim().toLowerCase();
         if (!/^[a-z][a-z0-9_-]*$/u.test(id))
             throw new TypeError(`invalid TUI scene id: ${descriptor.id}`);
-        if (this.scenes.has(id))
+        if (this.scenes.has(id)) {
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'create',
+                resource: { kind: 'scene', id },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
             throw new Error(`TUI scene "${id}" is already registered`);
+        }
         const normalized = { ...descriptor, id };
         this.scenes.set(id, normalized);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'scene', id }, result: 'applied' }, identity);
         return () => {
             if (this.scenes.get(id) !== normalized)
                 return;
             this.scenes.delete(id);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'scene', id }, result: 'applied' }, identity);
             // Disposing the open scene must not strand the user on a dead screen.
             if (this.current === normalized) {
                 this.current = undefined;