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

package/lib/types/dsh-adapter/plugin-host.js

@@ -0,0 +1,270 @@
+/**
+ * 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 { Service } from '@deepseek-ai/cordis';
+import { randomUUID } from 'node:crypto';
+import { parseManifest, projectManifest } from '@dsh-std/manifest';
+import { loadSpecData, verifyContractProfiles, verifyRegistry } from '../plugin-spec/registry.js';
+import { createContractIndex, validatePlugin } from '../plugin-spec/validate.js';
+import { negotiate } from '../plugin-spec/negotiate.js';
+import { readGrantStore } from './grants.js';
+import { buildHostDescriptor, HOST_SUPPORTED_CONTRACTS } from './host-descriptor.js';
+import { TuiEffectLedgerRuntime } from './effect-ledger.js';
+import { TuiPluginStorageRuntime } from './plugin-storage.js';
+import { TuiMessageObserverRuntime } from './message-observer.js';
+import { stampCommandOwner, unstampCommandOwner } from './command-attribution.js';
+import { hasCommandErrorCode, mapCommandError } from './command-errors.js';
+import { installDecisionGuard, decisionHandlerMetadataOf, registerDecisionHandler, withDecisionRegistration, } from './decision-guard.js';
+import { bindComponentIdentity, declaresCommand, requiresDecisionEvents, requireComponentIdentity, } from './component-identity.js';
+/** `ctx.tuiPluginHost` — plugin-interop anchor (generation, grants, descriptor). */
+export class TuiPluginHostRuntime extends Service {
+    /** Runtime generation id (C-050): fresh per activation of this row. */
+    generationId = randomUUID();
+    /** Live scoped grant store; every operation observes the current file. */
+    grants;
+    descriptorBuild;
+    descriptorCommandsMounted;
+    constructor(ctx) {
+        super(ctx, 'tuiPluginHost');
+        this.grants = readGrantStore();
+        // The host row may be mounted without the extensions row or a channel;
+        // decision registration must remain mediated in that degraded topology.
+        installDecisionGuard(ctx, this.grants);
+        const violations = this.selfCheck();
+        if (violations.length > 0) {
+            ctx.logger.warn(`dsh-tui: vendored plugin-spec registry failed self-check (${violations.length} violation(s)); ` +
+                `affected contracts are dropped from the Host Descriptor fail-closed: ${violations.join(' | ')}`);
+        }
+    }
+    /**
+     * The C-010 Host Descriptor, built lazily and cached while the
+     * runtime-dependent commands capability remains unchanged.
+     */
+    hostDescriptor() {
+        return this.build().descriptor;
+    }
+    /** The full build result (descriptor + dropped coordinates + warnings). */
+    describe() {
+        return this.build();
+    }
+    build() {
+        // C-010 honesty: advertise Command only when the commands service is
+        // actually mounted — a bare/embedded context without dsh-commands must
+        // not negotiate `compatible` for a capability plugins will never get.
+        // Probed on every descriptor request: the service can mount or unmount
+        // after the first lazy build.
+        const commandsMounted = this.ctx.get('commands') !== undefined;
+        if (this.descriptorBuild === undefined || this.descriptorCommandsMounted !== commandsMounted) {
+            const supported = HOST_SUPPORTED_CONTRACTS.filter(contract => contract.kind !== 'Command' || commandsMounted);
+            this.descriptorBuild = buildHostDescriptor({ generationId: this.generationId, supported });
+            this.descriptorCommandsMounted = commandsMounted;
+            if (!commandsMounted) {
+                this.ctx.logger.warn('dsh-tui: host descriptor: commands.dsh/v1alpha1#Command excluded — the commands service is not mounted on this context');
+            }
+            for (const warning of this.descriptorBuild.warnings) {
+                this.ctx.logger.warn(`dsh-tui: host descriptor: ${warning}`);
+            }
+        }
+        return this.descriptorBuild;
+    }
+    /**
+     * Parse, project, validate, negotiate, and bind one activation's Component
+     * identity before any mediated runtime capability can be used.
+     */
+    admit(pluginCtx, source, options = {}) {
+        const manifest = parseManifest(source, { source: options.source });
+        // The host owns the activation instance identity. Embedders may provide a
+        // pre-issued id when policy has an activation-scoped grant; otherwise a
+        // fresh opaque id is generated once and bound to this Cordis activation.
+        const activationId = options.activationId ?? randomUUID();
+        const data = loadSpecData();
+        if (data === undefined)
+            throw new Error('dsh-tui: admission profile is unavailable');
+        const index = createContractIndex(data.registry, data.permissions);
+        validatePlugin(index, manifest);
+        const projection = projectManifest(manifest);
+        const grants = manifest.permissions
+            .map(request => ({
+            name: request.name,
+            scope: request.scope,
+            granted: this.grants.allows({ componentId: manifest.id, activationId }, request.name, request.scope),
+        }));
+        const decision = negotiate(index, manifest, this.hostDescriptor(), grants);
+        if (decision.decision !== 'compatible' && decision.decision !== 'compatible_degraded') {
+            throw new Error(`dsh-tui: Component ${manifest.id} admission ${decision.decision}: ${'reasonCode' in decision ? decision.reasonCode : 'incompatible'}`);
+        }
+        return bindComponentIdentity(pluginCtx, manifest, projection, activationId);
+    }
+    /**
+     * 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, event, listener, options = {}) {
+        const identity = requireComponentIdentity(pluginCtx);
+        if (!requiresDecisionEvents(identity)) {
+            throw new Error(`dsh-tui: Component "${identity.componentId}" must require tui.dsh/v1alpha1#DecisionEvents before subscribing`);
+        }
+        const previousMetadata = decisionHandlerMetadataOf(listener);
+        const release = withDecisionRegistration(pluginCtx, () => registerDecisionHandler(pluginCtx, identity, event, listener, options, () => {
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'decision-handler', id: `${identity.componentId}:${event}` }, result: 'applied' }, pluginCtx);
+        }));
+        // A missing live grant is represented by a no-op disposer rather than an
+        // exception. Do not write a successful bind record for that path; the
+        // ledger must describe effects that actually entered the registry.
+        const metadata = decisionHandlerMetadataOf(listener);
+        const registered = metadata !== previousMetadata
+            && metadata?.componentId === identity.componentId
+            && metadata.activationId === identity.activationId
+            && metadata.event === event;
+        if (!registered) {
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'bind',
+                resource: { kind: 'permission', id: `${event}` },
+                result: 'failed',
+                errorCode: 'PERMISSION_NOT_GRANTED',
+            }, pluginCtx);
+            return () => false;
+        }
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'decision-handler', id: `${identity.componentId}:${event}` }, result: 'applied' }, pluginCtx);
+        return release;
+    }
+    registerCommand(pluginCtx, contributionOrDefinition, explicitDefinition) {
+        // Resolve through the registrant context so dsh-commands attaches the
+        // registration to that agent's scoped layer rather than the host-global
+        // layer. Its traceable service proxy carries this context into register().
+        const commands = pluginCtx.get('commands');
+        if (commands === undefined) {
+            throw new Error('dsh-tui: registerCommand unavailable — the commands service is not mounted on this context');
+        }
+        const identity = requireComponentIdentity(pluginCtx);
+        const definition = typeof contributionOrDefinition === 'string' ? explicitDefinition : contributionOrDefinition;
+        if (definition === undefined)
+            throw new TypeError('dsh-tui: registerCommand requires a command definition');
+        const name = typeof definition.name === 'string' ? definition.name : 'unknown';
+        const inferred = identity.manifest.contributes.commands.filter(command => command.id === name || command.id.endsWith(`.${name}`));
+        const contributionId = typeof contributionOrDefinition === 'string'
+            ? contributionOrDefinition
+            : inferred.length === 1 ? inferred[0].id : '';
+        if (contributionId === '' || !declaresCommand(identity, contributionId)) {
+            throw new TypeError(`dsh-tui: command "${name}" is not bound to a declared contribution id`);
+        }
+        // dsh-commands normalizes into a fresh definition and intentionally drops
+        // unknown fields. A per-registration handler wrapper survives that copy,
+        // giving the invoke checkpoint a collision-free identity for the actual
+        // resolved definition (including agent-scoped shadows).
+        const handler = definition?.handler;
+        const attributedDefinition = typeof handler === 'function'
+            ? {
+                ...definition,
+                handler: function (invocation) {
+                    return handler.call(this, invocation);
+                },
+            }
+            : definition;
+        let dispose;
+        try {
+            dispose = commands.register(attributedDefinition);
+        }
+        catch (error) {
+            const mapped = mapCommandError(error);
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'create',
+                resource: { kind: 'command', id: contributionId },
+                result: 'failed',
+                errorCode: hasCommandErrorCode(mapped, 'DUPLICATE_CONTRIBUTION_ID') ? 'DUPLICATE_CONTRIBUTION_ID' : 'COMMAND_FAILED',
+            }, pluginCtx);
+            throw mapped;
+        }
+        stampCommandOwner(this.ctx, attributedDefinition, identity, contributionId);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'command', id: contributionId }, result: 'applied' }, pluginCtx);
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            unstampCommandOwner(this.ctx, attributedDefinition, identity.activationId);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'command', id: contributionId }, result: 'applied' }, pluginCtx);
+        };
+        // commands.register() already belongs to pluginCtx and therefore removes
+        // the definition on fiber teardown. Keep the attribution in that same
+        // lifecycle even when the caller never invokes our returned wrapper.
+        try {
+            pluginCtx.effect(() => release);
+        }
+        catch {
+            // Degraded contexts retain the wrapper-only cleanup path below.
+        }
+        let disposed = false;
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            try {
+                dispose();
+            }
+            finally {
+                release();
+            }
+        };
+    }
+    /**
+     * 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() {
+        const data = loadSpecData();
+        if (data === undefined)
+            return ['vendored spec data unavailable (ecosystem-spec/)'];
+        return [...verifyRegistry(data), ...verifyContractProfiles(data)];
+    }
+}
+export const name = 'dsh-tui-plugin-host';
+export function apply(ctx) {
+    // The plugin-host service first — the contract surfaces mounted below
+    // read its grant store (they fall back to a private read only when mounted
+    // standalone, e.g. in tests).
+    ctx.plugin(TuiPluginHostRuntime);
+    // Effect ledger (C-060): mounted before the surfaces below so they can
+    // soft-probe it at construction; generation comes from the host service.
+    ctx.plugin(TuiEffectLedgerRuntime);
+    // storage.local (C-040): per-plugin private persistence.
+    ctx.plugin(TuiPluginStorageRuntime);
+    // messages.observe (C-042): the grant-gated observation broker the
+    // channel publishes mapped session events into.
+    ctx.plugin(TuiMessageObserverRuntime);
+}

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

@@ -0,0 +1,113 @@
+/**
+ * storage.local contract surface (C-040, `storage.dsh/v1alpha1#LocalStorage`):
+ * per-plugin private persistence, mounted by the dsh-tui-plugin-host row as
+ * `ctx.tuiPluginStorage`.
+ *
+ * The plugin-facing API is `open(ctx)` → `{ get, set, delete }`:
+ *
+ * - VERIFIED IDENTITY: the namespace is derived from the admitted Component
+ *   identity bound to the PASSED activation — there is no parameter to name
+ *   another plugin, so cross-plugin access is rejected by construction.
+ * - GRANTS AT CALL TIME: `get` requires `storage.local.read`, `set`/`delete`
+ *   require `storage.local.write` — checked per call against the live grant
+ *   store (a revoked grant blocks the very next operation without restart).
+ * - Backend: `~/.dsh-tui/plugin-storage/<namespace>.json`, one flat JSON
+ *   object per namespace. Writes go through dsh-atomic-write (`withFileLock`
+ *   for the read-modify-write cycle + `writeFileAtomic` for the commit), and
+ *   an in-process per-namespace promise chain serializes operations in
+ *   invocation order (contract concurrency rule — the lock alone does not
+ *   order contenders).
+ * - QUOTA (host-defined): 256 keys AND 256 KiB of serialized content per
+ *   namespace; a `set` that would cross either fails with QUOTA_EXCEEDED and
+ *   changes nothing.
+ * - Keys stay ordinary data even when they collide with Object.prototype
+ *   names ("__proto__", "toString", "constructor"): namespace tables are
+ *   null-prototype and membership is decided with Object.hasOwn. Values
+ *   must be EXACT JSON values — inputs JSON.stringify would silently
+ *   mutate (undefined, NaN/±Infinity, functions, class instances, sparse
+ *   arrays, cycles) are rejected instead of round-tripping a lie.
+ * - A corrupt namespace file is NEVER overwritten silently: every operation
+ *   fails with STORAGE_UNAVAILABLE and the bytes stay on disk for manual
+ *   recovery. Closing a handle (plugin unload) retains data (contract
+ *   cleanup rule); later calls on a closed handle fail STORAGE_UNAVAILABLE.
+ * - privacyClass: sensitive — keys AND values are never logged.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { type GrantStore } from './grants.js';
+import type { TuiEffectLedgerRuntime } from './effect-ledger.js';
+/** Quota: max distinct keys per namespace. */
+export declare const STORAGE_MAX_KEYS = 256;
+/** Quota: max serialized file size per namespace (bytes). */
+export declare const STORAGE_MAX_BYTES: number;
+/** Max key length (characters). */
+export declare const STORAGE_KEY_MAX_LENGTH = 128;
+export type PluginStorageErrorCode = 'PERMISSION_NOT_GRANTED' | 'INVALID_KEY' | 'INVALID_VALUE' | 'QUOTA_EXCEEDED' | 'STORAGE_UNAVAILABLE';
+/** Storage failure with the contract's error code on `.code`. */
+export declare class PluginStorageError extends Error {
+    readonly code: PluginStorageErrorCode;
+    constructor(code: PluginStorageErrorCode, message: string);
+}
+/** The per-namespace handle returned by {@link TuiPluginStorageRuntime.open}. */
+export interface TuiPluginStorage {
+    get(input: {
+        key: string;
+    }): Promise<{
+        value: unknown | null;
+    }>;
+    set(input: {
+        key: string;
+        value: unknown;
+    }): Promise<{
+        stored: true;
+    }>;
+    delete(input: {
+        key: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiPluginStorage: TuiPluginStorageRuntime;
+    }
+}
+/** Namespace directory under the data dir. */
+export declare const PLUGIN_STORAGE_DIR = "plugin-storage";
+/**
+ * Plugin name → safe, collision-free file name. encodeURIComponent keeps
+ * alphanumerics and `- _ . ! ~ * ' ( )`, so scoped names like `@foo/bar`
+ * encode reversibly; pathological results ('', '.', '..') map to '_'.
+ */
+export declare function storageFileName(plugin: string): string;
+/**
+ * `ctx.tuiPluginStorage` — storage.local contract surface. Mounted by the
+ * dsh-tui-plugin-host row; grants come from that row's store when present
+ * (normal path) or a private read otherwise (bare mounts in tests).
+ */
+export declare class TuiPluginStorageRuntime extends Service {
+    private readonly grantsOption;
+    private readonly fallbackGrants;
+    private readonly ledgerOption;
+    private readonly namespaces;
+    private readonly dir;
+    constructor(ctx: Context, options?: {
+        dir?: string;
+        grants?: GrantStore;
+        ledger?: TuiEffectLedgerRuntime;
+    });
+    /** 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. */
+    private grants;
+    /** Optional observability; a bare mount (tests) simply records nothing. */
+    private ledger;
+    /**
+     * Open the caller's private namespace. Identity = the PASSED context's
+     * verified Component identity (no way to name another plugin). The handle
+     * closes automatically when the caller's context unloads (idempotent
+     * disposer); data is retained (contract cleanup rule).
+     */
+    open(pluginCtx: Context): TuiPluginStorage;
+}
+//# sourceMappingURL=plugin-storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-storage.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugin-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAWtD,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAEhE,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,QAAa,CAAA;AAC3C,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC,MAAM,MAAM,sBAAsB,GAC9B,wBAAwB,GACxB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,qBAAqB,CAAA;AAEzB,iEAAiE;AACjE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;gBACzB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAC/D,GAAG,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACtE,MAAM,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAC9D;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,gBAAgB,EAAE,uBAAuB,CAAA;KAC1C;CACF;AAED,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAgID;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;gBAEhB,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,sBAAsB,CAAA;KAAO;IAQ9G;;;gDAG4C;IAC5C,OAAO,CAAC,MAAM;IAId,2EAA2E;IAC3E,OAAO,CAAC,MAAM;IAId;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB;CA2K3C"}