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

package/lib/types/dsh-adapter/plugins-info.d.ts

@@ -0,0 +1,43 @@
+/**
+ * /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 type { GrantStore } from './grants.js';
+import type { HostDescriptorBuild } from './host-descriptor.js';
+/** How many plugins the matrix shows before an overflow note. */
+export declare const PLUGINS_MATRIX_MAX_ROWS = 20;
+/** How many ledger records the tail section shows. */
+export declare const PLUGINS_LEDGER_TAIL = 5;
+export interface PluginsInfoDeps {
+    /** Effective grant answers (the plugin-host row's store when mounted). */
+    grants: GrantStore;
+    /** The plugin-host row's descriptor build; undefined → row not mounted. */
+    host?: HostDescriptorBuild;
+    /** Test overrides; default under DATA_DIR. */
+    dataDir?: string;
+    ledgerFile?: string;
+    storageDir?: string;
+}
+/** The `/plugins` overview lines (banner always first). */
+export declare function pluginsInfoLines(args: string, deps: PluginsInfoDeps): string[];
+//# sourceMappingURL=plugins-info.d.ts.map

package/lib/types/dsh-adapter/plugins-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins-info.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugins-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAYH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAK/D,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAIpC,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,UAAU,CAAA;IAClB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,mBAAmB,CAAA;IAC1B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AA2JD,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAmF9E"}

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/promptDebug.d.ts

@@ -1,10 +1,4 @@
 import type { Context } from '@deepseek-ai/cordis';
 export declare const PROMPT_DEBUG_FILENAME = ".dsh-prompt-debug.json";
-/**
- * Register `/debug-prompt` and retain every final request observed for each
- * live session. The command writes one private, atomic snapshot into the
- * receiving session's workspace; it never records credentials, transport
- * headers, or AbortSignals.
- */
 export declare function registerPromptDebug(ctx: Context): void;
 //# sourceMappingURL=promptDebug.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"promptDebug.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/promptDebug.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,eAAO,MAAM,qBAAqB,2BAA2B,CAAA;AAmF7D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA4FtD"}
+{"version":3,"file":"promptDebug.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/promptDebug.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,eAAO,MAAM,qBAAqB,2BAA2B,CAAA;AAiG7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA+FtD"}

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

@@ -52,11 +52,17 @@ function captureRequest(agent, options, requestIndex, position, attempt) {
     };
 }
 /**
- * Register `/debug-prompt` and retain every final request observed for each
- * live session. The command writes one private, atomic snapshot into the
- * receiving session's workspace; it never records credentials, transport
- * headers, or AbortSignals.
+ * Register `/debug-prompt` and retain the final requests observed for each
+ * live session (most recent {@link DEBUG_PROMPT_MAX_REQUESTS} kept). The
+ * command writes one private, atomic snapshot into the receiving session's
+ * workspace; it never records credentials, transport headers, or
+ * AbortSignals.
  */
+/** Retention cap per session: every capture holds the fully assembled
+ * request context (messages + tools), so an unbounded list grows
+ * quadratically with an uncompacted conversation — the dominant long-session
+ * memory term. Retries of the current step stay well inside this window. */
+const DEBUG_PROMPT_MAX_REQUESTS = 8;
 export function registerPromptDebug(ctx) {
     const commands = ctx.get('commands');
     const agents = ctx.get('agents');
@@ -80,6 +86,9 @@ export function registerPromptDebug(ctx) {
         const previous = capture.requests.findLast(request => request.turn === position.turn && request.step === position.step);
         const attempt = (previous?.attempt ?? 0) + 1;
         capture.requests.push(captureRequest(agent, options, capture.requests.length + 1, position, attempt));
+        if (capture.requests.length > DEBUG_PROMPT_MAX_REQUESTS) {
+            capture.requests.splice(0, capture.requests.length - DEBUG_PROMPT_MAX_REQUESTS);
+        }
         return next();
     });
     // Replaced agents are no longer addressable by `/debug-prompt`; release

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

@@ -0,0 +1,57 @@
+/**
+ * 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 {
+    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;AAKtD,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,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;IAexB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;CA8DnF;AA4CD,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,173 @@
+/**
+ * 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';
+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,
+        };
+        const host = Object.freeze({ 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) {
+        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,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"}