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

package/lib/types/dsh-adapter/message-observer.js

@@ -0,0 +1,509 @@
+/**
+ * messages.observe contract surface (C-042,
+ * `messages.dsh/v1alpha1#MessageObserver`): the host event broker, mounted
+ * by the dsh-tui-plugin-host row as `ctx.tuiMessageObserver`.
+ *
+ * Mapping (deliberately narrow):
+ *
+ * - `user/message`      → `message.received` (the user's prompt)
+ * - `assistant/message` → `message.sent` (the assembled step reply)
+ * - EVERYTHING ELSE (assistant/chunk streaming, tool/*, turn/*, mode
+ *   events, …) produces NO envelope — observation starts conservative.
+ *
+ * Envelope rules (the pinned `@dsh-std/messages` v0.15 definition):
+ *
+ * - `scope` = `session:<sessionId>`; `sequence` = the session event's own
+ *   `seq` (monotonic within scope, gaps allowed — unmapped events simply
+ *   leave holes); `eventId` = `<sessionId>:<seq>` with schema-unsafe
+ *   characters flattened to `_`.
+ * - privacyClass is ALWAYS `sensitive` for now (conservative and
+ *   irreversible-safe; finer classification is a future, documented step).
+ * - Content carries the text/image subset (MCP ContentBlock): text runs
+ *   join (a pure-text message keeps the single trimmed block); session
+ *   image blocks are `{type:'image', attachment}` REFERENCES resolved via
+ *   the attachments service into base64 `data` with a 192 KiB budget —
+ *   an unreadable/oversize image is dropped and marks `truncated`.
+ *   `summary` is the sanitized first 200 cells of the joined text;
+ *   `truncated` marks summary, content, or image-drop truncation.
+ * - EVERY produced envelope passes the official pinned validator before delivery;
+ *   a malformed envelope is dropped with a warning, never delivered.
+ *
+ * Scope isolation (C-042): `subscribe` requires an exact `scope` string
+ * and an envelope is delivered ONLY to subscriptions of the same scope —
+ * a plugin moving between sessions subscribes per scope and never
+ * receives another session's sensitive content.
+ *
+ * Grant gating (`messages.observe.read`, default deny):
+ *
+ * - SUBSCRIBE time: a denied plugin gets a no-op disposer + a warning
+ *   naming plugin and grant (fast fail, as-if-unsubscribed).
+ * - DELIVER time: every publish re-checks each subscription; a revoked
+ *   grant RELEASES the subscription (contract cleanup rule) with one
+ *   warning.
+ *
+ * Delivery semantics: at-most-once, no replay; envelope builds serialize
+ * broker-wide (image reads are async — delivery order stays the publish
+ * order, so sequence stays monotonic); callbacks of ONE subscription run
+ * serially (per-subscription promise chain); a throwing listener is
+ * isolated (warn, name the plugin, keep delivering to the rest). The host
+ * MUST NOT persist payload through this contract — the broker keeps no
+ * history.
+ *
+ * privacyClass: sensitive — envelope content is never logged.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { validateMessageEvent } from '@dsh-std/messages';
+import { check } from '../plugin-spec/schema-check.js';
+import { cleanScalarText } from './sanitize.js';
+import { readGrantStore } from './grants.js';
+import { declaresObserverScope, declaresPermission, requireComponentIdentity, } from './component-identity.js';
+import { normalizePermissionScope, scopeCovers, SESSION_SCOPE_MAX_CHARS, } from '../plugin-spec/permission-scope.js';
+/** Summary bound (cells; schema maxLength 1024 chars — 200 cells ≤ 1024). */
+export const OBSERVE_SUMMARY_CELLS = 200;
+/** Content text bound (chars; schema maxLength 262144). */
+export const OBSERVE_CONTENT_MAX_CHARS = 262144;
+/** Scope bound (schema maxLength 256). */
+export const OBSERVE_SCOPE_MAX_CHARS = SESSION_SCOPE_MAX_CHARS;
+/** messageId bound (schema maxLength 256). */
+export const OBSERVE_ID_MAX_CHARS = 256;
+/** Raw image byte budget per block (192 KiB → ≤262144 base64 chars). */
+export const OBSERVE_IMAGE_MAX_BYTES = 192 * 1024;
+/** Base64 length bound implied by OBSERVE_IMAGE_MAX_BYTES. */
+export const OBSERVE_IMAGE_BASE64_MAX_CHARS = 262144;
+/** Per-callback budget; timeout closes the subscription deterministically. */
+export const OBSERVE_CALLBACK_TIMEOUT_MS = 1500;
+/** Bound queued callbacks per subscription so a stalled listener cannot grow
+ * an unbounded Promise chain before its timeout closes the subscription. */
+export const OBSERVE_CALLBACK_QUEUE_LIMIT = 32;
+/** The envelope schema's mimeType pattern (image blocks). */
+const OBSERVE_MIME_PATTERN = /^[A-Za-z0-9.+-]+\/[A-Za-z0-9.+-]+$/;
+function deepFreeze(value) {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}
+function freezeEnvelope(envelope) {
+    return deepFreeze(structuredClone(envelope));
+}
+/** Session events are untrusted at this boundary. Never coerce arbitrary
+ * objects through `String()` because a hostile `toString` can fabricate
+ * message text (or throw) before the envelope validator sees it. */
+function sourceBlockType(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    try {
+        const type = value.type;
+        return type === 'text' || type === 'image' ? type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sourceText(value) {
+    try {
+        const text = value.text;
+        return typeof text === 'string' ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runWithBudget(task, timeoutMs) {
+    let timer;
+    const work = Promise.resolve()
+        .then(task)
+        .then(() => ({ kind: 'fulfilled' }), error => ({ kind: 'rejected', error }));
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve({ kind: 'timeout' }), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Match a requested observer scope against the concrete scope of an
+ * envelope.  `session:*` is an explicit, grantable parent scope; all other
+ * scopes remain exact.  Keeping this relation in the broker means a wildcard
+ * declaration cannot accidentally become global unless both the manifest and
+ * the current grant cover it. */
+function observerScopeCovers(subscriptionScope, envelopeScope) {
+    const declared = normalizePermissionScope('messages.observe.read', subscriptionScope, 'host');
+    const actual = normalizePermissionScope('messages.observe.read', envelopeScope, 'host');
+    return declared !== undefined && actual !== undefined && scopeCovers(declared, actual);
+}
+/**
+ * `ctx.tuiMessageObserver` — the messages.observe broker. The channel
+ * publishes mapped session events; plugins subscribe with their own
+ * context. When the vendored envelope schema is unavailable (packaging
+ * accident) the broker fails CLOSED: subscriptions are accepted but nothing
+ * is ever delivered (a host that cannot self-check must not emit).
+ */
+export class TuiMessageObserverRuntime extends Service {
+    grantsOption;
+    fallbackGrants;
+    ledgerOption;
+    subscriptions = new Set();
+    validateEnvelope;
+    validatorUnavailable;
+    validatorWarned = false;
+    buildChain = Promise.resolve();
+    constructor(ctx, options = {}) {
+        super(ctx, 'tuiMessageObserver');
+        this.grantsOption = options.grants;
+        this.fallbackGrants = readGrantStore();
+        this.ledgerOption = options.ledger;
+        if (Object.hasOwn(options, 'validateEnvelope')) {
+            this.validatorUnavailable = options.validateEnvelope === undefined;
+            this.validateEnvelope = options.validateEnvelope ?? (() => { throw new Error('standard envelope validator unavailable'); });
+        }
+        else if (Object.hasOwn(options, 'envelopeSchema')) {
+            const schema = options.envelopeSchema;
+            this.validatorUnavailable = schema === undefined;
+            this.validateEnvelope = schema === undefined
+                ? (() => { throw new Error('vendored envelope schema unavailable'); })
+                : (value) => check(value, schema, schema);
+        }
+        else {
+            this.validatorUnavailable = false;
+            this.validateEnvelope = (value) => { validateMessageEvent(value); };
+        }
+    }
+    /** Grants: the plugin-host row's store when mounted, else a private read.
+     *  Resolved PER CALL — sibling services mounted later by the same apply()
+     *  are not visible to constructors (cordis), so a constructor-time probe
+     *  would silently stick to the fallback. */
+    grants() {
+        return this.grantsOption ?? this.ctx.get('tuiPluginHost')?.grants ?? this.fallbackGrants;
+    }
+    /** Optional observability; a bare mount (tests) simply records nothing. */
+    ledger() {
+        return this.ledgerOption ?? this.ctx.get('tuiEffectLedger');
+    }
+    /**
+     * Subscribe to observation envelopes for ONE scope. Identity = the verified
+     * Component bound to the PASSED activation (the same identity rule as
+     * storage); the scope
+     * is required and matched exactly — a plugin moving between sessions
+     * subscribes per scope and never receives another scope's sensitive
+     * content (C-042 isolation). A denied subscription fast-fails: no-op
+     * disposer + warning. The subscription releases when the caller's context
+     * unloads.
+     */
+    subscribe(pluginCtx, listener, options) {
+        const identity = requireComponentIdentity(pluginCtx);
+        const plugin = identity.componentId;
+        const scope = typeof options?.scope === 'string' ? options.scope : '';
+        if (scope === '' || scope.length > OBSERVE_SCOPE_MAX_CHARS) {
+            this.ctx.logger.warn(`dsh-tui: messages.observe subscription from plugin "${plugin}" refused — options.scope must be a ` +
+                `non-empty string of at most ${OBSERVE_SCOPE_MAX_CHARS} characters (e.g. "session:<id>")`);
+            return () => false;
+        }
+        if (typeof listener !== 'function'
+            || !declaresObserverScope(identity, scope)
+            || !declaresPermission(identity, 'messages.observe.read', scope)
+            || !this.grants().allows({ componentId: identity.componentId, activationId: identity.activationId }, 'messages.observe.read', scope)) {
+            this.ctx.logger.warn(`dsh-tui: messages.observe subscription from Component "${plugin}" denied — ` +
+                'the scope is not statically declared or the current grant does not cover it; the listener was NOT registered');
+            this.ledger()?.record({
+                operation: 'bind',
+                resource: { kind: 'permission', id: 'messages.observe.read' },
+                result: 'failed',
+                errorCode: 'PERMISSION_NOT_GRANTED',
+            }, pluginCtx);
+            return () => false;
+        }
+        const subscription = {
+            plugin,
+            identity,
+            ownerContext: pluginCtx,
+            scope,
+            listener,
+            chain: Promise.resolve(),
+            pendingCallbacks: 0,
+            closed: false,
+        };
+        this.subscriptions.add(subscription);
+        this.ledger()?.record({ operation: 'bind', resource: { kind: 'subscription', id: plugin }, result: 'applied' }, pluginCtx);
+        const release = () => {
+            if (subscription.closed)
+                return false;
+            this.drop(subscription);
+            return true;
+        };
+        subscription.stopGrantWatch = this.grants().onChange?.(() => {
+            if (!this.grants().allows({ componentId: identity.componentId, activationId: identity.activationId }, 'messages.observe.read', scope))
+                release();
+        });
+        try {
+            pluginCtx.effect(() => release);
+        }
+        catch {
+            // Degraded context: the subscription lives until process end.
+        }
+        return release;
+    }
+    /**
+     * Publish a session event (channel `session/event` arm). Non-mapped
+     * event types return immediately; everything else never throws into the
+     * caller — problems are warned, not raised.
+     */
+    publish(session, event) {
+        try {
+            this.publishGuarded(session, event);
+        }
+        catch (error) {
+            this.ctx.logger.warn(`dsh-tui: messages.observe publish failed (event dropped): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    publishGuarded(session, event) {
+        if (this.subscriptions.size === 0)
+            return;
+        const record = event;
+        const kind = record.type === 'user/message'
+            ? 'message.received'
+            : record.type === 'assistant/message'
+                ? 'message.sent'
+                : undefined;
+        if (kind === undefined)
+            return;
+        if (typeof record.seq !== 'number' || !Number.isInteger(record.seq) || record.seq < 0)
+            return;
+        const sessionId = session?.id;
+        if (typeof sessionId !== 'string' || sessionId === '') {
+            this.ctx.logger.warn('dsh-tui: messages.observe publish skipped — the session carries no string id');
+            return;
+        }
+        const data = (record.data ?? {});
+        const message = (kind === 'message.sent' ? data.message : data);
+        const scope = `session:${sessionId}`;
+        // Never truncate a session identity into the schema's scope bound: two
+        // distinct long ids can otherwise collapse into one subscription scope.
+        if (scope.length > OBSERVE_SCOPE_MAX_CHARS) {
+            this.ctx.logger.warn(`dsh-tui: messages.observe publish skipped — the session scope exceeds ${OBSERVE_SCOPE_MAX_CHARS} characters`);
+            return;
+        }
+        // C-042 isolation: match subscriptions BEFORE building anything — a
+        // subscription for another scope must never see this scope's content.
+        const matched = [...this.subscriptions].filter(subscription => !subscription.closed && observerScopeCovers(subscription.scope, scope));
+        if (matched.length === 0)
+            return;
+        // Builds serialize broker-wide so delivery order stays the publish
+        // order even though image reads are async (sequence stays monotonic).
+        this.buildChain = this.buildChain.then(() => this.buildAndDeliver(kind, sessionId, scope, record.seq, message, matched));
+    }
+    async buildAndDeliver(kind, sessionId, scope, sequence, message, matched) {
+        try {
+            const text = this.textOf(message?.content);
+            const { blocks, truncated: contentTruncated } = await this.contentOf(message?.content);
+            const summary = cleanScalarText(text, OBSERVE_SUMMARY_CELLS);
+            // Exact truncation detection: the capped clean differs from the
+            // uncapped clean (cells ≠ chars, so length comparison would lie).
+            const summaryTruncated = summary !== cleanScalarText(text, Number.MAX_SAFE_INTEGER);
+            const envelope = {
+                eventType: 'messages.observe',
+                eventVersion: '0.15',
+                eventId: `${sessionId}:${sequence}`.replace(/[^A-Za-z0-9._:-]/g, '_'),
+                scope,
+                sequence,
+                // Conservative-by-default: every envelope is sensitive until a
+                // documented finer classification exists.
+                privacyClass: 'sensitive',
+                summary,
+                payload: {
+                    kind,
+                    ...(typeof message?.id === 'string' && message.id.length > 0 && message.id.length <= OBSERVE_ID_MAX_CHARS
+                        ? { messageId: message.id }
+                        : {}),
+                    author: kind === 'message.received' ? 'user' : 'assistant',
+                    content: blocks,
+                    ...(summaryTruncated || contentTruncated ? { truncated: true } : {}),
+                },
+            };
+            // Self-check EVERY envelope with the pinned @dsh-std/messages validator.
+            if (this.validatorUnavailable) {
+                if (!this.validatorWarned) {
+                    this.validatorWarned = true;
+                    this.ctx.logger.warn('dsh-tui: standard message envelope validator unavailable — delivery is fail-closed');
+                }
+                return;
+            }
+            try {
+                this.validateEnvelope(envelope);
+            }
+            catch (error) {
+                this.ctx.logger.warn(`dsh-tui: messages.observe envelope failed the standard validator and was dropped: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            for (const subscription of matched) {
+                if (subscription.closed)
+                    continue;
+                // Deliver-time grant re-check: a revoked grant RELEASES the
+                // subscription (contract cleanup rule), with one warning.
+                if (!this.grants().allows({ componentId: subscription.identity.componentId, activationId: subscription.identity.activationId }, 'messages.observe.read', scope)) {
+                    this.ctx.logger.warn(`dsh-tui: messages.observe subscription of plugin "${subscription.plugin}" released — the grant was revoked`);
+                    this.drop(subscription);
+                    continue;
+                }
+                if (subscription.pendingCallbacks >= OBSERVE_CALLBACK_QUEUE_LIMIT) {
+                    this.ctx.logger.warn(`dsh-tui: messages.observe listener of Component "${subscription.plugin}" reached its ` +
+                        `${OBSERVE_CALLBACK_QUEUE_LIMIT}-callback queue limit; this envelope was skipped`);
+                    continue;
+                }
+                subscription.pendingCallbacks += 1;
+                const run = subscription.chain.then(async () => {
+                    if (subscription.closed)
+                        return;
+                    const isolated = freezeEnvelope(envelope);
+                    const result = await runWithBudget(() => subscription.listener(isolated), OBSERVE_CALLBACK_TIMEOUT_MS);
+                    if (result.kind === 'timeout') {
+                        this.ctx.logger.warn(`dsh-tui: messages.observe listener of Component "${subscription.plugin}" exceeded ` +
+                            `${OBSERVE_CALLBACK_TIMEOUT_MS}ms and the subscription was closed`);
+                        this.drop(subscription);
+                    }
+                    else if (result.kind === 'rejected') {
+                        this.ctx.logger.warn(`dsh-tui: messages.observe listener of Component "${subscription.plugin}" failed; delivery continues: ` +
+                            `${result.error instanceof Error ? result.error.message : String(result.error)}`);
+                    }
+                });
+                subscription.chain = run.catch(error => {
+                    this.ctx.logger.warn(`dsh-tui: messages.observe delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+                }).finally(() => { subscription.pendingCallbacks -= 1; });
+            }
+        }
+        catch (error) {
+            this.ctx.logger.warn(`dsh-tui: messages.observe publish failed (event dropped): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** Release a subscription exactly once (disposer, ctx unload, revoke). */
+    drop(subscription) {
+        if (subscription.closed)
+            return;
+        subscription.closed = true;
+        subscription.stopGrantWatch?.();
+        subscription.stopGrantWatch = undefined;
+        this.subscriptions.delete(subscription);
+        this.ledger()?.record({ operation: 'release', resource: { kind: 'subscription', id: subscription.plugin }, result: 'applied' }, subscription.ownerContext);
+    }
+    /** Join the text blocks of a session message's content (text-only view). */
+    textOf(content) {
+        if (!Array.isArray(content))
+            return '';
+        let text = '';
+        for (const block of content) {
+            if (sourceBlockType(block) !== 'text')
+                continue;
+            const value = sourceText(block);
+            if (value !== undefined)
+                text += value;
+        }
+        return text.trim();
+    }
+    /**
+     * Map session content blocks to envelope blocks in order (text/image
+     * subset). Consecutive text runs join into one block (capped at
+     * OBSERVE_CONTENT_MAX_CHARS, pure-text messages keep the exact legacy
+     * shape: a single trimmed block); image blocks resolve through the
+     * attachments service (soft-probe) with a byte budget. A failed or
+     * oversize image becomes NO block plus the truncation mark; zero
+     * surviving blocks collapse to a single empty text block (schema
+     * minItems 1).
+     */
+    async contentOf(content) {
+        const blocks = [];
+        let pendingText = '';
+        let truncated = false;
+        const appendText = (value) => {
+            const remaining = OBSERVE_CONTENT_MAX_CHARS - pendingText.length;
+            if (remaining <= 0) {
+                truncated = true;
+                return;
+            }
+            if (value.length > remaining) {
+                pendingText += value.slice(0, remaining);
+                truncated = true;
+                return;
+            }
+            pendingText += value;
+        };
+        const flushText = () => {
+            const run = pendingText.trim();
+            pendingText = '';
+            if (run === '')
+                return;
+            blocks.push({ type: 'text', text: run });
+        };
+        if (Array.isArray(content)) {
+            for (const raw of content) {
+                const type = sourceBlockType(raw);
+                if (type === 'text') {
+                    const text = sourceText(raw);
+                    if (text === undefined) {
+                        // A declared text block with a non-string body is malformed source
+                        // data, not the literal string "[object Object]".
+                        truncated = true;
+                        continue;
+                    }
+                    appendText(text);
+                    continue;
+                }
+                if (type === 'image') {
+                    const image = await this.imageBlockOf(raw);
+                    if (image === undefined) {
+                        truncated = true;
+                        continue;
+                    }
+                    flushText();
+                    blocks.push(image);
+                    continue;
+                }
+                // Unknown block types are outside the text/image subset: dropped.
+            }
+        }
+        flushText();
+        if (blocks.length === 0)
+            blocks.push({ type: 'text', text: '' });
+        return { blocks, truncated };
+    }
+    /** Resolve a session image block (`{type:'image', attachment}` — a
+     *  REFERENCE, never inline data) to an envelope image block; undefined =
+     *  drop (unreadable, oversize, bad media type, no attachment store). */
+    async imageBlockOf(block) {
+        try {
+            if (block === null || typeof block !== 'object')
+                return undefined;
+            const attachment = block.attachment;
+            if (attachment === null || attachment === undefined || typeof attachment !== 'object')
+                return undefined;
+            const mediaType = attachment.mediaType;
+            if (typeof mediaType !== 'string' || !OBSERVE_MIME_PATTERN.test(mediaType))
+                return undefined;
+            const bytes = attachment.bytes;
+            if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0 || bytes > OBSERVE_IMAGE_MAX_BYTES)
+                return undefined;
+            const reader = this.ctx.get('attachments');
+            if (typeof reader?.readImage !== 'function')
+                return undefined;
+            // A failing read drops ONLY this image (the envelope survives with the
+            // truncation mark) — one corrupt attachment must not nuke the message.
+            const stored = await reader.readImage(attachment);
+            const data = stored?.data;
+            if (!(data instanceof Uint8Array) || data.byteLength > OBSERVE_IMAGE_MAX_BYTES)
+                return undefined;
+            const base64 = Buffer.from(data).toString('base64');
+            if (base64.length > OBSERVE_IMAGE_BASE64_MAX_CHARS)
+                return undefined;
+            return { type: 'image', data: base64, mimeType: mediaType };
+        }
+        catch {
+            // Source content and attachment service output are untrusted here.
+            // Drop only this block and let the enclosing envelope carry truncated.
+            return undefined;
+        }
+    }
+}

package/lib/types/dsh-adapter/plugin-host.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The dsh-tui-plugin-host row: the plugin-interop anchor every later
+ * contract surface hangs off (storage.local, messages.observe, effect
+ * ledger — each lands as a sibling service mounted by THIS row's apply, so
+ * the patch surface changed exactly once for the whole v0.15 alignment).
+ *
+ * What it provides on `ctx.tuiPluginHost`:
+ *
+ * - `generationId` — the runtime generation id (C-050), a fresh UUID per
+ *   row activation; ledger records and the Host Descriptor stamp it so
+ *   effects from different process generations can never be confused.
+ * - `grants` — the unified 8-permission live GrantStore (./grants.js).
+ * - `hostDescriptor()` — the C-010 Host Descriptor (./host-descriptor.js),
+ *   built lazily and cached; drifted contracts are dropped fail-closed.
+ * - `selfCheck()` — vendored registry + contract-profile violations
+ *   (definition/profile drift, ten-point incompleteness, parity mismatches).
+ * - `registerCommand(pluginCtx, definition)` — the MEDIATED command
+ *   registration surface (C-041 attribution): stamps each command with the
+ *   verified Component identity so the invoke checkpoint can enforce per-owner
+ *   denies (./command-attribution.js). Direct `ctx.get('commands')`
+ *   registrations stay unattributed — the documented C-070 boundary.
+ *
+ * Discipline notes:
+ *
+ * - #183: consumers NEVER get this service via inject — always
+ *   `ctx.get('tuiPluginHost', false)` soft probing, with the skew warning in
+ *   plugin.ts covering profile launches on a stale patch.
+ * - The D-7 decision gate does NOT depend on this row: the extensions row
+ *   and the channel each install it with their own GrantStore read, so a
+ *   missing plugin-host row never relaxes interception gating.
+ * - Boot-time self-check failures are logged once here (fail closed happens
+ *   per-contract at descriptor build time; boot must not die on drifted
+ *   vendored data).
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import type { HostDescriptor } from '../plugin-spec/types.js';
+import { type GrantStore } from './grants.js';
+import { type HostDescriptorBuild } from './host-descriptor.js';
+import { type DecisionRegistrationOptions } from './decision-guard.js';
+import { type VerifiedComponentIdentity } from './component-identity.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiPluginHost: TuiPluginHostRuntime;
+    }
+}
+/** `ctx.tuiPluginHost` — plugin-interop anchor (generation, grants, descriptor). */
+export declare class TuiPluginHostRuntime extends Service {
+    /** Runtime generation id (C-050): fresh per activation of this row. */
+    readonly generationId: `${string}-${string}-${string}-${string}-${string}`;
+    /** Live scoped grant store; every operation observes the current file. */
+    readonly grants: GrantStore;
+    private descriptorBuild;
+    private descriptorCommandsMounted;
+    constructor(ctx: Context);
+    /**
+     * The C-010 Host Descriptor, built lazily and cached while the
+     * runtime-dependent commands capability remains unchanged.
+     */
+    hostDescriptor(): HostDescriptor;
+    /** The full build result (descriptor + dropped coordinates + warnings). */
+    describe(): HostDescriptorBuild;
+    private build;
+    /**
+     * Parse, project, validate, negotiate, and bind one activation's Component
+     * identity before any mediated runtime capability can be used.
+     */
+    admit(pluginCtx: Context, source: string, options?: {
+        source?: string;
+        activationId?: string;
+    }): VerifiedComponentIdentity;
+    /**
+     * Host-mediated DecisionEvents activation surface.  A plugin cannot use a
+     * raw `ctx.on` for these points: the verified Component identity, static
+     * requirement, scope and current grant are all checked before insertion in
+     * the registry.  The returned disposer is idempotent and is also owned by
+     * the activation so deactivation cannot leave an effect behind.
+     */
+    subscribeDecision(pluginCtx: Context, event: string, listener: (payload: Record<string, unknown>) => unknown, options?: DecisionRegistrationOptions): () => boolean;
+    /**
+     * Mediated command registration (C-041 attribution): registers through
+     * the commands service and, on success, stamps the command's owner as
+     * the verified Component identity — so the channel's invoke checkpoint
+     * can enforce per-owner `commands.invoke` denies on the host-mediated
+     * path. Mirrors the honest-identity pattern of storage.open /
+     * messages.observe subscribe: there is no parameter to impersonate
+     * another plugin. The returned disposer unregisters AND lifts the stamp
+     * (idempotent). Duplicates throw the mapped DUPLICATE_CONTRIBUTION_ID
+     * error; a missing commands service fails loud (the descriptor's
+     * Command contract is excluded in that situation anyway).
+    */
+    registerCommand(pluginCtx: Context, definition: CommandDefinition): () => void;
+    registerCommand(pluginCtx: Context, contributionId: string, definition: CommandDefinition): () => void;
+    /**
+     * Vendored registry + contract-profile self-check (C-020 definition/profile
+     * pins, C-040 ten-point completeness, coordinate/permission parity). Empty =
+     * clean; violations are strings, never thrown.
+     */
+    selfCheck(): string[];
+}
+export declare const name = "dsh-tui-plugin-host";
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=plugin-host.d.ts.map

package/lib/types/dsh-adapter/plugin-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAI7D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAiD,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAM9G,OAAO,EAKL,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,yBAAyB,CAAA;AAEhC,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,aAAa,EAAE,oBAAoB,CAAA;KACpC;CACF;AAED,oFAAoF;AACpF,qBAAa,oBAAqB,SAAQ,OAAO;IAC/C,uEAAuE;IACvE,QAAQ,CAAC,YAAY,sDAAe;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAE3B,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,yBAAyB,CAAqB;gBAE1C,GAAG,EAAE,OAAO;IAexB;;;OAGG;IACH,cAAc,IAAI,cAAc;IAIhC,2EAA2E;IAC3E,QAAQ,IAAI,mBAAmB;IAI/B,OAAO,CAAC,KAAK;IAuBb;;;OAGG;IACH,KAAK,CACH,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GACvD,yBAAyB;IA4B5B;;;;;;OAMG;IACH,iBAAiB,CACf,SAAS,EAAE,OAAO,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACvD,OAAO,GAAE,2BAAgC,GACxC,MAAM,OAAO;IAgDhB;;;;;;;;;;;MAWE;IACF,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAC9E,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAyFtG;;;;OAIG;IACH,SAAS,IAAI,MAAM,EAAE;CAKtB;AAED,eAAO,MAAM,IAAI,wBAAwB,CAAA;AAEzC,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAaxC"}