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

package/lib/types/modelRoute.d.ts

@@ -61,8 +61,16 @@ export declare function recordedModelRoute(events: readonly {
  * Best-effort combination check (issue #67): when the llm runtime advertises
  * a non-empty catalog for the route's provider and the model is not in it,
  * reject the whole route in favor of `fallback` so a stale persisted choice
- * surfaces at startup instead of as a server-side model-name error. Any
- * uncertainty — no llm service, a failed or empty catalog — trusts the route.
+ * surfaces at startup instead of as a server-side model-name error.
+ *
+ * Uncertainty trusts the route — no llm service, an empty catalog, a catalog
+ * read that failed for transport or adapter-internal reasons. An unregistered
+ * PROVIDER is not uncertainty: no adapter owns the name, so the route is
+ * proven unusable and falls back exactly like an unknown model does. Trusting
+ * it does not keep startup alive either — agent creation dies a few frames
+ * later inside the preset setup hook, reported as `refusing to compose an
+ * unscoped context`, which names neither the provider nor the stale
+ * preference that chose it.
  * @param llm - The llm runtime seam, when mounted.
  * @param route - The resolved route to check.
  * @param fallback - Route to adopt when the check rejects.

package/lib/types/modelRoute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modelRoute.d.ts","sourceRoot":"","sources":["../../src/modelRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,wHAAwH;AACxH,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAA;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,GAAG,SAAS,CAI5G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,QAAQ,GAAE,UAAgC,GACzC,UAAU,CAKZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GAClD,UAAU,GAAG,SAAS,CAWxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE;IAAE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;CAAE,GAAG,SAAS,EACrF,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,UAAgC,GACzC,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CAUvD"}
+{"version":3,"file":"modelRoute.d.ts","sourceRoot":"","sources":["../../src/modelRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,wHAAwH;AACxH,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAA;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,GAAG,SAAS,CAI5G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,QAAQ,GAAE,UAAgC,GACzC,UAAU,CAKZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GAClD,UAAU,GAAG,SAAS,CAWxB;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE;IAAE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;CAAE,GAAG,SAAS,EACrF,KAAK,EAAE,UAAU,EACjB,QAAQ,GAAE,UAAgC,GACzC,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CAWvD"}

package/lib/types/modelRoute.js

@@ -69,12 +69,39 @@ export function recordedModelRoute(events) {
     }
     return undefined;
 }
+/**
+ * `LlmError` code the adapter registry raises for a provider nobody
+ * registered. Matched on the code rather than `instanceof LlmError`: a profile
+ * that resolves two copies of the llm package would fail the identity check
+ * while the code stays stable, and this module deliberately carries no llm
+ * import.
+ */
+const NO_ADAPTER_CODE = 'NO_ADAPTER';
+/**
+ * Whether a catalog read failed because the provider itself is unregistered,
+ * as opposed to a transport or adapter-internal failure.
+ * @param error - The value `listModels` rejected with.
+ * @returns True when no adapter owns the queried provider.
+ */
+function isUnregisteredProvider(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && error.code === NO_ADAPTER_CODE);
+}
 /**
  * Best-effort combination check (issue #67): when the llm runtime advertises
  * a non-empty catalog for the route's provider and the model is not in it,
  * reject the whole route in favor of `fallback` so a stale persisted choice
- * surfaces at startup instead of as a server-side model-name error. Any
- * uncertainty — no llm service, a failed or empty catalog — trusts the route.
+ * surfaces at startup instead of as a server-side model-name error.
+ *
+ * Uncertainty trusts the route — no llm service, an empty catalog, a catalog
+ * read that failed for transport or adapter-internal reasons. An unregistered
+ * PROVIDER is not uncertainty: no adapter owns the name, so the route is
+ * proven unusable and falls back exactly like an unknown model does. Trusting
+ * it does not keep startup alive either — agent creation dies a few frames
+ * later inside the preset setup hook, reported as `refusing to compose an
+ * unscoped context`, which names neither the provider nor the stale
+ * preference that chose it.
  * @param llm - The llm runtime seam, when mounted.
  * @param route - The resolved route to check.
  * @param fallback - Route to adopt when the check rejects.
@@ -87,8 +114,10 @@ export async function validateModelRoute(llm, route, fallback = DEFAULT_MODEL_RO
     try {
         models = await llm.listModels(route.provider);
     }
-    catch {
-        return { route };
+    catch (error) {
+        if (!isUnregisteredProvider(error))
+            return { route };
+        return { route: fallback, rejected: route };
     }
     if (models.length === 0 || models.some(model => model.id === route.model))
         return { route };

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

@@ -0,0 +1,13 @@
+export * from './dsh-adapter/plugin-host.js';
+export * from './dsh-adapter/grants.js';
+export * from './dsh-adapter/host-descriptor.js';
+export * from './dsh-adapter/plugin-storage.js';
+export * from './dsh-adapter/message-observer.js';
+export * from './dsh-adapter/effect-ledger.js';
+export * from './dsh-adapter/command-errors.js';
+export { commandOwner, fiberNameOf, stampCommandOwner, unstampCommandOwner } from './dsh-adapter/command-attribution.js';
+export { DECISION_EVENT_PERMISSIONS, decisionHandlersOf, registerDecisionHandler, withDecisionRegistration, } from './dsh-adapter/decision-guard.js';
+export { DECISION_HANDLER_TIMEOUT_MS, DECISION_TOTAL_TIMEOUT_MS, dispatchTuiNotification, } from './dsh-adapter/extension-events.js';
+export { DECISION_EVENTS_COORDINATE, TUI_EXTENSION_API_VERSION, TUI_DECISION_EVENT_NAMES, TUI_EXTENSION_PERMISSION_NAMES, createAdmissionCatalog, } from './plugin-spec/tui-extension.js';
+export type { ContractCoordinate, ContractRef, HostContract, HostDescriptor, NegotiationDecision, PermissionEntry, PermissionRegistry, } from './plugin-spec/types.js';
+//# sourceMappingURL=plugin-host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-host.d.ts","sourceRoot":"","sources":["../../src/plugin-host.ts"],"names":[],"mappings":"AAMA,cAAc,8BAA8B,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,cAAc,kCAAkC,CAAA;AAChD,cAAc,iCAAiC,CAAA;AAC/C,cAAc,mCAAmC,CAAA;AACjD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,iCAAiC,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAA;AACxH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,sBAAsB,GACvB,MAAM,gCAAgC,CAAA;AAEvC,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GACnB,MAAM,wBAAwB,CAAA"}

package/lib/types/plugin-host.js

@@ -0,0 +1,17 @@
+// Re-export shim: the Cordis-backed implementation lives behind the adapter
+// boundary so UI consumers never import official @deepseek-ai/* packages.
+// Plugin authors import the plugin-host types from here
+// (`@deepseek-harness-tui/dsh-tui/plugin-host`); importing the module also
+// applies the `declare module '@deepseek-ai/cordis'` augmentation for the
+// `tuiPluginHost` property on Context.
+export * from './dsh-adapter/plugin-host.js';
+export * from './dsh-adapter/grants.js';
+export * from './dsh-adapter/host-descriptor.js';
+export * from './dsh-adapter/plugin-storage.js';
+export * from './dsh-adapter/message-observer.js';
+export * from './dsh-adapter/effect-ledger.js';
+export * from './dsh-adapter/command-errors.js';
+export { commandOwner, fiberNameOf, stampCommandOwner, unstampCommandOwner } from './dsh-adapter/command-attribution.js';
+export { DECISION_EVENT_PERMISSIONS, decisionHandlersOf, registerDecisionHandler, withDecisionRegistration, } from './dsh-adapter/decision-guard.js';
+export { DECISION_HANDLER_TIMEOUT_MS, DECISION_TOTAL_TIMEOUT_MS, dispatchTuiNotification, } from './dsh-adapter/extension-events.js';
+export { DECISION_EVENTS_COORDINATE, TUI_EXTENSION_API_VERSION, TUI_DECISION_EVENT_NAMES, TUI_EXTENSION_PERMISSION_NAMES, createAdmissionCatalog, } from './plugin-spec/tui-extension.js';

package/lib/types/plugin-spec/negotiate.d.ts

@@ -0,0 +1,11 @@
+/** Five-state admission decision using dsh-std projection and ProtocolCatalog. */
+import type { ContractIndex } from './validate.js';
+import type { HostDescriptor, NegotiationDecision, PluginManifest } from './types.js';
+export interface GrantedPermission {
+    name: string;
+    scope: string;
+    /** Explicit effective answer. Omitted means a legacy positive grant row. */
+    granted?: boolean;
+}
+export declare function negotiate(index: ContractIndex, manifest: PluginManifest, host: HostDescriptor, grants?: readonly GrantedPermission[]): NegotiationDecision;
+//# sourceMappingURL=negotiate.d.ts.map

package/lib/types/plugin-spec/negotiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/plugin-spec/negotiate.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAIlF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,OAAO,KAAK,EAAE,cAAc,EAAsB,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAIzG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,wBAAgB,SAAS,CACvB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,cAAc,EACpB,MAAM,GAAE,SAAS,iBAAiB,EAAO,GACxC,mBAAmB,CA6FrB"}

package/lib/types/plugin-spec/negotiate.js

@@ -0,0 +1,97 @@
+/** Five-state admission decision using dsh-std projection and ProtocolCatalog. */
+import { defineProtocolDeclaration } from '@dsh-std/core';
+import { projectManifest } from '@dsh-std/manifest';
+import { rawScopeCovers } from './permission-scope.js';
+const coordinateKey = (ref) => `${ref.apiVersion}#${ref.kind}`;
+export function negotiate(index, manifest, host, grants = []) {
+    const supported = new Map(host.contracts.map(contract => [coordinateKey(contract), contract]));
+    const required = manifest.requires.contracts.filter(reference => reference.optional !== true);
+    const optional = manifest.requires.contracts.filter(reference => reference.optional === true);
+    const unknown = manifest.requires.contracts.filter(reference => {
+        try {
+            return index.resolveContractRef(reference).unregisteredVersion;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (unknown.length > 0) {
+        return {
+            decision: 'unknown',
+            reasonCode: 'UNKNOWN_PROTOCOL_VERSION',
+            unknownContracts: unknown.map(coordinateKey),
+        };
+    }
+    if (!host.facetApiVersions.includes(manifest.facets.host.apiVersion)) {
+        return {
+            decision: 'rejected',
+            reasonCode: 'FACET_API_VERSION_UNAVAILABLE',
+            facetApiVersion: manifest.facets.host.apiVersion,
+            hostFacetApiVersions: host.facetApiVersions,
+        };
+    }
+    const missingRequired = required.filter(reference => !supported.has(coordinateKey(reference)));
+    const missingOptional = optional.filter(reference => !supported.has(coordinateKey(reference)));
+    if (missingRequired.length > 0) {
+        return {
+            decision: 'rejected',
+            reasonCode: 'REQUIRED_PROTOCOL_UNAVAILABLE',
+            missingRequired: missingRequired.map(coordinateKey),
+        };
+    }
+    const projected = projectManifest(manifest);
+    const facet = projected.spec.facets.find(candidate => candidate.name === 'host');
+    const supportedKeys = new Set(host.contracts.map(contract => coordinateKey(contract)));
+    const declaration = defineProtocolDeclaration({
+        participant: { id: manifest.id },
+        // An optional protocol that is absent is intentionally omitted from the
+        // evaluator input; its degraded state was already recorded above. This
+        // keeps ProtocolCatalog's required-support error meaningful for every
+        // remaining requirement.
+        requires: (facet?.protocols?.requires ?? []).filter(reference => reference.optional !== true || supportedKeys.has(coordinateKey(reference))),
+    });
+    const hostDeclaration = defineProtocolDeclaration({
+        participant: { id: host.hostId },
+        supports: host.contracts.map(contract => ({
+            apiVersion: contract.apiVersion,
+            kind: contract.kind,
+            ...(Object.hasOwn(contract, 'spec') ? { spec: contract.spec } : {}),
+        })),
+    });
+    const report = index.protocols.negotiate([declaration, hostDeclaration]);
+    if (!report.compatible) {
+        return {
+            decision: 'rejected',
+            reasonCode: 'PROTOCOL_NEGOTIATION_FAILED',
+            issues: report.issues,
+        };
+    }
+    const hostPermissions = new Set(host.contracts.flatMap(contract => contract.permissions));
+    const denied = manifest.permissions.filter((request) => {
+        if (!hostPermissions.has(request.name))
+            return true;
+        const definition = index.permissions.permissions.find(permission => permission.name === request.name);
+        if (definition === undefined)
+            return true;
+        const matching = grants.filter(grant => grant.name === request.name
+            && rawScopeCovers(grant.name, grant.scope, request.scope, manifest.id));
+        // Explicit revocation wins over an allow-default permission. This keeps
+        // admission diagnostics aligned with the runtime checkpoint instead of
+        // reporting a plugin as compatible until its first invocation fails.
+        if (matching.some(grant => grant.granted === false))
+            return true;
+        if (definition.default === 'allow')
+            return false;
+        return !matching.some(grant => grant.granted !== false);
+    });
+    if (denied.length > 0) {
+        return {
+            decision: 'waiting_authorization',
+            reasonCode: 'PERMISSION_NOT_GRANTED',
+            deniedPermissions: denied.map(request => `${request.name}@${request.scope}`),
+        };
+    }
+    return missingOptional.length > 0
+        ? { decision: 'compatible_degraded', missingOptional: missingOptional.map(coordinateKey) }
+        : { decision: 'compatible' };
+}

package/lib/types/plugin-spec/permission-scope.d.ts

@@ -0,0 +1,32 @@
+/** Permission scope normalization shared by admission and runtime checks. */
+export declare const STORAGE_PERMISSIONS: Set<string>;
+export declare const INTERCEPT_PERMISSIONS: Set<string>;
+/** The decision point controlled by each intercept permission.  Keeping this
+ * mapping in the scope adapter (rather than accepting every `tui/*` name for
+ * every permission) prevents a manifest or grant from silently crossing an
+ * event boundary. */
+export declare const INTERCEPT_EVENT_SCOPE_BY_PERMISSION: Readonly<Record<string, string>>;
+/** A session scope is carried through the message envelope and may also be
+ * used by an intercept grant. Keep the canonical bound here so admission,
+ * grant evaluation, and runtime delivery cannot disagree about whether a
+ * scope is executable. */
+export declare const SESSION_SCOPE_MAX_CHARS = 256;
+export type ScopeKind = 'component' | 'command' | 'session' | 'event';
+export interface NormalizedPermissionScope {
+    kind: ScopeKind;
+    value: string;
+}
+/** Return undefined when this adapter cannot enforce the supplied scope. */
+export declare function normalizePermissionScope(permission: string, scope: string, componentId: string): NormalizedPermissionScope | undefined;
+export declare function scopeCovers(declared: NormalizedPermissionScope, actual: NormalizedPermissionScope): boolean;
+/**
+ * Permission-aware containment.  An event-point grant is the parent scope of
+ * the sessions delivered through that point, while a session grant can never
+ * be promoted into an event-point grant.  This relation is also used for
+ * denies, so a narrow `session:<id>` deny wins over a broad event grant.
+ */
+export declare function permissionScopeCovers(permission: string, declared: NormalizedPermissionScope, actual: NormalizedPermissionScope): boolean;
+/** Decision permission scopes may be expressed as one named event point. */
+export declare const TUI_EVENT_SCOPE_NAMES: Set<string>;
+export declare function rawScopeCovers(permission: string, declared: string, actual: string, componentId: string): boolean;
+//# sourceMappingURL=permission-scope.d.ts.map

package/lib/types/plugin-spec/permission-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-scope.d.ts","sourceRoot":"","sources":["../../../src/plugin-spec/permission-scope.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,eAAO,MAAM,mBAAmB,aAAyD,CAAA;AACzF,eAAO,MAAM,qBAAqB,aAKhC,CAAA;AAEF;;;qBAGqB;AACrB,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK/E,CAAA;AAEF;;;0BAG0B;AAC1B,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAI1C,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAErE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,yBAAyB,GAAG,SAAS,CA2BvC;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,yBAAyB,EAAE,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAI3G;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,yBAAyB,EACnC,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAKT;AAED,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,aAOhC,CAAA;AAEF,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAMjH"}

package/lib/types/plugin-spec/permission-scope.js

@@ -0,0 +1,90 @@
+/** Permission scope normalization shared by admission and runtime checks. */
+export const STORAGE_PERMISSIONS = new Set(['storage.local.read', 'storage.local.write']);
+export const INTERCEPT_PERMISSIONS = new Set([
+    'session.input.intercept',
+    'session.rewind.intercept',
+    'session.switch.intercept',
+    'session.compact.intercept',
+]);
+/** The decision point controlled by each intercept permission.  Keeping this
+ * mapping in the scope adapter (rather than accepting every `tui/*` name for
+ * every permission) prevents a manifest or grant from silently crossing an
+ * event boundary. */
+export const INTERCEPT_EVENT_SCOPE_BY_PERMISSION = Object.freeze({
+    'session.input.intercept': 'tui/input',
+    'session.rewind.intercept': 'tui/rewind-prompt',
+    'session.switch.intercept': 'tui/session-switch',
+    'session.compact.intercept': 'tui/compact',
+});
+/** A session scope is carried through the message envelope and may also be
+ * used by an intercept grant. Keep the canonical bound here so admission,
+ * grant evaluation, and runtime delivery cannot disagree about whether a
+ * scope is executable. */
+export const SESSION_SCOPE_MAX_CHARS = 256;
+const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/u;
+/** Return undefined when this adapter cannot enforce the supplied scope. */
+export function normalizePermissionScope(permission, scope, componentId) {
+    if (typeof scope !== 'string' || scope === '')
+        return undefined;
+    if (STORAGE_PERMISSIONS.has(permission)) {
+        return scope === componentId ? { kind: 'component', value: componentId } : undefined;
+    }
+    if (permission === 'commands.invoke') {
+        return /^[a-z][a-z0-9]*(?:[.-][a-z0-9][a-z0-9-]*)+$/u.test(scope)
+            ? { kind: 'command', value: scope }
+            : undefined;
+    }
+    if (INTERCEPT_PERMISSIONS.has(permission) && TUI_EVENT_SCOPE_NAMES.has(scope)) {
+        return INTERCEPT_EVENT_SCOPE_BY_PERMISSION[permission] === scope
+            ? { kind: 'event', value: scope }
+            : undefined;
+    }
+    if (permission === 'messages.observe.read' || INTERCEPT_PERMISSIONS.has(permission)) {
+        if (scope === 'session:*')
+            return { kind: 'session', value: scope };
+        if (scope.startsWith('session:')
+            && scope.length <= SESSION_SCOPE_MAX_CHARS
+            && scope.length > 'session:'.length
+            && !scope.includes('*')
+            && !CONTROL_CHARS.test(scope)) {
+            return { kind: 'session', value: scope };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+export function scopeCovers(declared, actual) {
+    if (declared.kind !== actual.kind)
+        return false;
+    return declared.value === actual.value
+        || (declared.kind === 'session' && declared.value === 'session:*' && actual.value.startsWith('session:'));
+}
+/**
+ * Permission-aware containment.  An event-point grant is the parent scope of
+ * the sessions delivered through that point, while a session grant can never
+ * be promoted into an event-point grant.  This relation is also used for
+ * denies, so a narrow `session:<id>` deny wins over a broad event grant.
+ */
+export function permissionScopeCovers(permission, declared, actual) {
+    if (scopeCovers(declared, actual))
+        return true;
+    return INTERCEPT_PERMISSIONS.has(permission)
+        && declared.kind === 'event'
+        && actual.kind === 'session';
+}
+/** Decision permission scopes may be expressed as one named event point. */
+export const TUI_EVENT_SCOPE_NAMES = new Set([
+    'tui/input',
+    'tui/rewind-prompt',
+    'tui/rewind-done',
+    'tui/session-switch',
+    'tui/session-switched',
+    'tui/compact',
+]);
+export function rawScopeCovers(permission, declared, actual, componentId) {
+    const normalizedDeclared = normalizePermissionScope(permission, declared, componentId);
+    const normalizedActual = normalizePermissionScope(permission, actual, componentId);
+    return normalizedDeclared !== undefined
+        && normalizedActual !== undefined
+        && permissionScopeCovers(permission, normalizedDeclared, normalizedActual);
+}

package/lib/types/plugin-spec/registry.d.ts

@@ -0,0 +1,23 @@
+/** Load and verify the pinned dsh-TUI admission profile. */
+import type { ContractRegistry, PermissionRegistry, RegistryEntry } from './types.js';
+export declare const DSH_STD_REVISION = "a2faa86243a5693ee4970e3d8b3aaf361edea298";
+export declare const ECOSYSTEM_SPEC_REVISION = "be1e9a219bd01decf79d825e0c3ac1685bde2be4";
+export interface SpecData {
+    dir: string;
+    registry: ContractRegistry;
+    permissions: PermissionRegistry;
+    schemas: {
+        host: Record<string, unknown>;
+        ledger: Record<string, unknown>;
+        claim: Record<string, unknown>;
+    };
+}
+export declare function locateSpecDir(start?: string): string | undefined;
+export declare function loadSpecData(dir?: string | undefined): SpecData | undefined;
+export declare function registryEntries(registry: ContractRegistry): RegistryEntry[];
+export declare function digestFile(dir: string, relative: string): `sha256:${string}`;
+/** Verify definition availability and private profile digest pins. */
+export declare function verifyRegistry(data: SpecData): string[];
+/** Verify the TUI-owned definitions; public definitions live in dsh-std. */
+export declare function verifyContractProfiles(data: SpecData): string[];
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/plugin-spec/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/plugin-spec/registry.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAO5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAErF,eAAO,MAAM,gBAAgB,6CAA6C,CAAA;AAC1E,eAAO,MAAM,uBAAuB,6CAA6C,CAAA;AAEjF,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,WAAW,EAAE,kBAAkB,CAAA;IAC/B,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAC/B,CAAA;CACF;AAID,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAgD,GAAG,MAAM,GAAG,SAAS,CASzG;AA0CD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,GAAG,SAA2B,GAAG,QAAQ,GAAG,SAAS,CAiB5F;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAI3E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,MAAM,EAAE,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAsBvD;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAiC/D"}

package/lib/types/plugin-spec/registry.js

@@ -0,0 +1,157 @@
+/** Load and verify the pinned dsh-TUI admission profile. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAdmissionCatalog } from './tui-extension.js';
+export const DSH_STD_REVISION = 'a2faa86243a5693ee4970e3d8b3aaf361edea298';
+export const ECOSYSTEM_SPEC_REVISION = 'be1e9a219bd01decf79d825e0c3ac1685bde2be4';
+const REGISTRY_FILE = join('registry', 'registry-0.15.json');
+export function locateSpecDir(start = dirname(fileURLToPath(import.meta.url))) {
+    let dir = start;
+    for (let index = 0; index < 8; index++) {
+        if (existsSync(join(dir, 'ecosystem-spec', REGISTRY_FILE)))
+            return join(dir, 'ecosystem-spec');
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+function loadJson(dir, relative) {
+    return JSON.parse(readFileSync(join(dir, relative), 'utf8'));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function soundEntry(value, privateDefinition) {
+    if (!isRecord(value) || typeof value.name !== 'string' || typeof value.kind !== 'string')
+        return false;
+    if (!isRecord(value.coordinates)
+        || typeof value.coordinates.apiVersion !== 'string'
+        || typeof value.coordinates.kind !== 'string')
+        return false;
+    if (!Array.isArray(value.permissions) || !value.permissions.every(permission => typeof permission === 'string'))
+        return false;
+    if (privateDefinition) {
+        return value.authority === 'dsh-tui'
+            && typeof value.profile === 'string'
+            && typeof value.profileHash === 'string';
+    }
+    return typeof value.package === 'string' && value.package.startsWith('@dsh-std/');
+}
+function structurallySound(data) {
+    if (!isRecord(data.registry)
+        || typeof data.registry.profileVersion !== 'string'
+        || !isRecord(data.registry.std)
+        || !Array.isArray(data.registry.imports)
+        || !Array.isArray(data.registry.definitions)
+        || !Array.isArray(data.registry.facetApiVersions)
+        || !data.registry.facetApiVersions.every(version => typeof version === 'string'))
+        return false;
+    if (!data.registry.imports.every(entry => soundEntry(entry, false)))
+        return false;
+    if (!data.registry.definitions.every(entry => soundEntry(entry, true)))
+        return false;
+    if (!isRecord(data.permissions) || !Array.isArray(data.permissions.permissions))
+        return false;
+    for (const permission of data.permissions.permissions) {
+        if (!isRecord(permission) || typeof permission.name !== 'string'
+            || (permission.default !== 'allow' && permission.default !== 'deny'))
+            return false;
+    }
+    return Object.values(data.schemas).every(isRecord);
+}
+export function loadSpecData(dir = locateSpecDir()) {
+    if (dir === undefined)
+        return undefined;
+    try {
+        const data = {
+            dir,
+            registry: loadJson(dir, REGISTRY_FILE),
+            permissions: loadJson(dir, join('registry', 'permissions-0.1.json')),
+            schemas: {
+                host: loadJson(dir, join('schemas', 'host-descriptor.schema.json')),
+                ledger: loadJson(dir, join('schemas', 'effect-ledger-record.schema.json')),
+                claim: loadJson(dir, join('schemas', 'conformance-claim.schema.json')),
+            },
+        };
+        return structurallySound(data) ? data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registryEntries(registry) {
+    return Array.isArray(registry.imports) && Array.isArray(registry.definitions)
+        ? [...registry.imports, ...registry.definitions]
+        : [];
+}
+export function digestFile(dir, relative) {
+    return `sha256:${createHash('sha256').update(readFileSync(join(dir, relative))).digest('hex')}`;
+}
+/** Verify definition availability and private profile digest pins. */
+export function verifyRegistry(data) {
+    const failures = [];
+    if (!Array.isArray(data.registry.imports)
+        || !Array.isArray(data.registry.definitions)) {
+        return ['registry imports/definitions are malformed'];
+    }
+    const { protocols } = createAdmissionCatalog();
+    for (const entry of registryEntries(data.registry)) {
+        const key = `${entry.coordinates.apiVersion}#${entry.coordinates.kind}`;
+        if (!protocols.understands(entry.coordinates))
+            failures.push(`${key}: ProtocolCatalog definition unavailable`);
+        if ('profile' in entry) {
+            let actual;
+            try {
+                actual = digestFile(data.dir, entry.profile);
+            }
+            catch {
+                failures.push(`${entry.name}: private profile unreadable (${entry.profile})`);
+                continue;
+            }
+            if (actual !== entry.profileHash)
+                failures.push(`${entry.name}: profileHash drifted (registry ${entry.profileHash}, actual ${actual})`);
+        }
+    }
+    return failures;
+}
+/** Verify the TUI-owned definitions; public definitions live in dsh-std. */
+export function verifyContractProfiles(data) {
+    const requiredKeys = [
+        'name', 'version', 'kind', 'coordinates', 'caller', 'permissions',
+        'errors', 'concurrency', 'timeout', 'cleanup', 'privacyClass', 'securityBoundary',
+    ];
+    const failures = [];
+    if (!Array.isArray(data.registry.definitions)) {
+        return ['registry definitions are malformed'];
+    }
+    for (const entry of data.registry.definitions) {
+        let profile;
+        try {
+            profile = loadJson(data.dir, entry.profile);
+        }
+        catch {
+            failures.push(`${entry.name}: private profile unreadable (${entry.profile})`);
+            continue;
+        }
+        for (const key of requiredKeys) {
+            if (!(key in profile))
+                failures.push(`${entry.name}: contract profile missing "${key}"`);
+        }
+        const coordinates = profile.coordinates;
+        if (coordinates?.apiVersion !== entry.coordinates.apiVersion || coordinates.kind !== entry.coordinates.kind) {
+            failures.push(`${entry.name}: profile/registry coordinates mismatch`);
+        }
+        const actualPermissions = [...(profile.permissions ?? [])].sort();
+        if (JSON.stringify(actualPermissions) !== JSON.stringify([...entry.permissions].sort())) {
+            failures.push(`${entry.name}: profile/registry permissions mismatch`);
+        }
+        if (!('operations' in profile) || profile.securityBoundary !== false) {
+            failures.push(`${entry.name}: capability boundary is incomplete`);
+        }
+    }
+    return failures;
+}

package/lib/types/plugin-spec/schema-check.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 零依赖 JSON Schema 校验器——上游 `conformance/tests/run.js` 的 check()
+ * 的保真 TS 移植。刻意只实现 vendored schemas 用到的子集：本地 $ref、
+ * oneOf（恰好一个匹配）、const/enum、object（required/additionalProperties:
+ * false/patternProperties）、array（min/maxItems/items/uniqueItems）、
+ * string（min/maxLength/pattern/format uri|date-time）、integer（minimum）、
+ * boolean。遇到子集之外的构件不静默放行——schema 更新引入新构件时这里
+ * 必须显式扩展（fixtures 矩阵会当场抓住）。
+ */
+type JsonSchema = Record<string, unknown>;
+/**
+ * Validate `value` against `schema`; throws an Error with the failing path
+ * (`$.a.b[0]: reason`) on the first violation.
+ */
+export declare function check(value: unknown, schema: JsonSchema, rootSchema?: JsonSchema, where?: string): void;
+export {};
+//# sourceMappingURL=schema-check.d.ts.map

package/lib/types/plugin-spec/schema-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-check.d.ts","sourceRoot":"","sources":["../../../src/plugin-spec/schema-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAqCzC;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAE,UAAmB,EAAE,KAAK,SAAM,GAAG,IAAI,CA0G5G"}