@deepseek-harness-tui/dsh-tui 0.7.3 → 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/promptDebug.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,148 @@
+/**
+ * On-demand capture of every final AgentLoop request context observed for a
+ * live session.
+ *
+ * The LLM waterfall is the last provider-neutral boundary before adapter
+ * dispatch. Capturing there records the fully assembled system prompt,
+ * messages, and tool schemas after prompt/tool plugins have contributed.
+ * @module @deepseek-harness-tui/dsh-tui/prompt-debug
+ */
+import { join, resolve } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { isAgentLoopRequest } from '@deepseek-ai/dsh-llm';
+export const PROMPT_DEBUG_FILENAME = '.dsh-prompt-debug.json';
+function latestPosition(agent) {
+    for (let index = agent.session.events.length - 1; index >= 0; index -= 1) {
+        const event = agent.session.events[index];
+        if (event?.type === 'step/start')
+            return event.data;
+    }
+    return undefined;
+}
+function latestRequestHeaderReason(agent) {
+    for (let index = agent.session.events.length - 1; index >= 0; index -= 1) {
+        const event = agent.session.events[index];
+        if (event?.type === 'request/header')
+            return event.data.reason;
+    }
+    return undefined;
+}
+function turnCompleted(agent, turn) {
+    return agent.session.events.some(event => event.type === 'turn/end' && event.data.turn === turn);
+}
+function captureRequest(agent, options, requestIndex, position, attempt) {
+    const requestHeaderReason = latestRequestHeaderReason(agent);
+    return {
+        capturedAt: new Date().toISOString(),
+        requestIndex,
+        ...position,
+        attempt,
+        ...(requestHeaderReason === undefined ? {} : { requestHeaderReason }),
+        finalLlmContext: {
+            provider: options.provider,
+            model: options.model,
+            ...(options.reasoningEffort === undefined ? {} : { reasoningEffort: options.reasoningEffort }),
+            ...(options.system === undefined ? {} : { system: options.system }),
+            messages: options.messages,
+            ...(options.tools === undefined ? {} : { tools: options.tools }),
+            ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+            ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
+            ...(options.stop === undefined ? {} : { stop: options.stop }),
+        },
+    };
+}
+/**
+ * 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 function registerPromptDebug(ctx) {
+    const commands = ctx.get('commands');
+    const agents = ctx.get('agents');
+    if (commands === undefined || agents === undefined || ctx.get('llm') === undefined)
+        return;
+    const captureStartedAt = new Date().toISOString();
+    const captures = new Map();
+    ctx.on('llm/stream', (options, next) => {
+        if (!isAgentLoopRequest(options) || options.sessionId === undefined)
+            return next();
+        const agent = agents.get(options.sessionId);
+        if (agent === undefined)
+            return next();
+        const position = latestPosition(agent);
+        if (position === undefined)
+            return next();
+        const sessionId = String(options.sessionId);
+        const capture = captures.get(sessionId) ?? { requests: [] };
+        if (!captures.has(sessionId))
+            captures.set(sessionId, capture);
+        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));
+        return next();
+    });
+    // Replaced agents are no longer addressable by `/debug-prompt`; release
+    // their potentially large message/tool snapshots with the agent lifecycle.
+    ctx.on('agent/disposed', ({ agent }) => {
+        captures.delete(String(agent.session.id));
+    });
+    ctx.effect(() => commands.register({
+        name: 'debug-prompt',
+        description: 'Write every observed final LLM request context for this session to the workspace root',
+        recordInput: false,
+        handler: async ({ agent, rawInput }) => {
+            if (rawInput.trim().length > 0) {
+                return { kind: 'error', text: 'Usage: /debug-prompt' };
+            }
+            const sessionId = String(agent.session.id);
+            const capture = captures.get(sessionId);
+            if (capture === undefined || capture.requests.length === 0) {
+                return {
+                    kind: 'error',
+                    text: 'No final LLM request is available for this session. Send one prompt, wait for it to finish, then run /debug-prompt.',
+                };
+            }
+            const latest = capture.requests.at(-1);
+            if (!turnCompleted(agent, latest.turn)) {
+                return { kind: 'error', text: 'The latest model turn is still running. Wait for it to finish, then run /debug-prompt.' };
+            }
+            const root = resolve(agent.session.header.cwd ?? process.cwd());
+            const output = join(root, PROMPT_DEBUG_FILENAME);
+            const turns = new Map();
+            for (const request of capture.requests) {
+                const turn = turns.get(request.turn) ?? { turn: request.turn, requests: [] };
+                if (!turns.has(request.turn))
+                    turns.set(request.turn, turn);
+                turn.requests.push(request);
+            }
+            const document = {
+                schemaVersion: 2,
+                generatedAt: new Date().toISOString(),
+                captureStartedAt,
+                captureScope: 'Requests observed by this dsh-tui process; requests from before a session resume cannot be reconstructed.',
+                warning: 'Sensitive debug data: contains system prompts, conversation messages, tool schemas, and tool results. It intentionally excludes credentials and transport headers.',
+                sessionId,
+                turnCount: turns.size,
+                requestCount: capture.requests.length,
+                turns: [...turns.values()].map(turn => ({
+                    ...turn,
+                    requestCount: turn.requests.length,
+                })),
+            };
+            try {
+                await writeFileAtomic(output, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+            }
+            catch (error) {
+                return {
+                    kind: 'error',
+                    text: `Could not write prompt debug file: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            return {
+                kind: 'success',
+                text: `Wrote ${capture.requests.length} final LLM request${capture.requests.length === 1 ? '' : 's'} to ${output}. The file contains sensitive conversation and prompt data.`,
+            };
+        },
+    }));
+}

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;