@deepseek-harness-tui/dsh-tui 0.14.0 → 0.15.0

package/lib/types/dsh-adapter/admission-loader.js

@@ -0,0 +1,256 @@
+/**
+ * Admits third-party plugin activations via their package-root
+ * `dsh-plugin.json` (`getHostAdmission()`), binding the identity to the
+ * plugin's own fiber. A refused activation keeps running (an
+ * unload would rewrite the user's profile) but stays outside every mediated
+ * capability. Listeners and the retry timer ride the caller's `ctx.effect`.
+ */
+import { findPackageJSON } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Context } from '@deepseek-ai/cordis';
+import { componentIdentityOf } from './component-identity.js';
+import { compositionRoot, withHostRootCapability } from './host-access.js';
+import { getHostAdmission } from './plugin-host.js';
+import { logForDebugging } from '../utils/debug.js';
+/** Retry window for an admission not decidable yet (a required contract or
+ *  the host itself arrives later). Bounded so a host that never arrives
+ *  (issue #183) settles as `refused` with a diagnostic instead of ticking forever. */
+const RETRY_INTERVAL_MS = 200;
+const RETRY_ATTEMPTS = 100;
+/**
+ * Watch `ctx`'s composition and admit every third-party activation that
+ * carries a package-root `dsh-plugin.json`. The listeners and the retry
+ * timer are bound to `ctx`'s own teardown.
+ */
+export function armAdmissionLoader(ctx, options = {}) {
+    const root = compositionRoot(ctx);
+    const retryAttempts = options.retryAttempts ?? RETRY_ATTEMPTS;
+    const loader = root.get('loader', false);
+    if (loader === undefined || typeof loader.locate !== 'function' || typeof loader.resolve !== 'function') {
+        logForDebugging('dsh-tui: admission loader not armed — this composition has no cordis loader');
+        return;
+    }
+    const state = new WeakMap();
+    const manifests = new WeakMap();
+    const attempts = new WeakMap();
+    const pending = new Set();
+    let timer;
+    const host = options.host ?? (() => ctx.get('tuiPluginHost', false));
+    const stopTimer = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    const settle = (fiber, next) => {
+        state.set(fiber, next);
+        pending.delete(fiber);
+    };
+    const attempt = (fiber) => {
+        const pluginCtx = fiber.ctx;
+        // LOADING (1), not ACTIVE (2): Cordis emits it before the row's callback
+        // runs, so the plugin has its identity while its `apply` registers panels.
+        // ACTIVE is the catch-up path for rows that activated before arming.
+        if (!Context.is(pluginCtx) || (fiber.state !== 1 && fiber.state !== 2)) {
+            settle(fiber, 'skipped');
+            return;
+        }
+        // Already admitted (the row called admission itself, or a previous pass
+        // of this loader did): the manifest identity is host-owned and single.
+        if (componentIdentityOf(pluginCtx) !== undefined) {
+            settle(fiber, 'admitted');
+            return;
+        }
+        // The manifest lookup is one synchronous walk per activation, cached for
+        // the fiber's lifetime (a restart reuses it; the package cannot move).
+        if (!manifests.has(fiber))
+            manifests.set(fiber, manifestPathOf(loader, fiber));
+        const resolved = manifests.get(fiber);
+        // No manifest at its package root:
+        // nothing to admit, and no retry will change that.
+        if (resolved === undefined) {
+            settle(fiber, 'skipped');
+            return;
+        }
+        const live = host();
+        const admission = live === undefined ? undefined : getHostAdmission(live);
+        if (admission === undefined) {
+            const waited = (attempts.get(fiber) ?? 0) + 1;
+            attempts.set(fiber, waited);
+            // The host has not arrived (an absent host looks like a late one):
+            // bounded wait, then a logged refusal.
+            if (waited >= retryAttempts) {
+                settle(fiber, 'refused');
+                logForDebugging(`dsh-tui: admission loader refused a Component after waiting ${waited} ticks for `
+                    + `tuiPluginHost / its admission seam (host ${live === undefined ? 'missing' : 'without getHostAdmission'})`, { manifest: resolved });
+            }
+            return;
+        }
+        let source;
+        try {
+            source = readFileSync(resolved, 'utf8');
+        }
+        catch (error) {
+            settle(fiber, 'skipped');
+            logForDebugging(`dsh-tui: admission loader could not read ${resolved} (${messageOf(error)})`);
+            return;
+        }
+        const count = (attempts.get(fiber) ?? 0) + 1;
+        attempts.set(fiber, count);
+        try {
+            const identity = admission.admit(pluginCtx, source, { source: resolved });
+            settle(fiber, 'admitted');
+            logForDebugging('dsh-tui: admission loader admitted a Component', {
+                componentId: identity.componentId,
+                activationId: identity.activationId,
+                manifest: resolved,
+            });
+        }
+        catch (error) {
+            if (count >= retryAttempts) {
+                settle(fiber, 'refused');
+                logForDebugging(`dsh-tui: admission loader refused a Component after ${count} attempts (${messageOf(error)})`, {
+                    manifest: resolved,
+                });
+            }
+        }
+    };
+    const consider = (fiber) => {
+        if (typeof fiber !== 'object' || fiber === null)
+            return;
+        const activation = fiber;
+        if (activation.state !== 1 && activation.state !== 2)
+            return;
+        const current = state.get(fiber);
+        if (current === 'admitted' || current === 'refused')
+            return;
+        // Synchronous on purpose: the row's callback runs one microtask after
+        // LOADING, so any hop here would let `apply` run before the identity exists.
+        pending.add(fiber);
+        attempt(activation);
+        if (pending.has(fiber) && timer === undefined)
+            timer = setTimeout(flush, RETRY_INTERVAL_MS);
+    };
+    const flush = () => {
+        stopTimer();
+        for (const fiber of [...pending])
+            attempt(fiber);
+        if (pending.size > 0)
+            timer = setTimeout(flush, RETRY_INTERVAL_MS);
+    };
+    // Rows that activated before this loader was armed (the profile path
+    // applies plugin rows before the TUI row) come from the entry tree; every
+    // later activation arrives through the lifecycle event.
+    const seed = () => {
+        if (typeof loader.entries !== 'function')
+            return;
+        try {
+            for (const entry of loader.entries())
+                consider(entry.fiber);
+        }
+        catch (error) {
+            logForDebugging(`dsh-tui: admission loader could not walk the entry tree (${messageOf(error)})`);
+        }
+    };
+    ctx.effect(() => {
+        const listener = (fiber) => {
+            // A fiber that leaves the running states loses the identity with its
+            // own effects (restart): forget the pass so a re-activation is admitted
+            // again.
+            const fiberState = fiber?.state;
+            if (typeof fiber === 'object' && fiber !== null && (fiberState === 5 || fiberState === 4 || fiberState === 3)) {
+                state.delete(fiber);
+                pending.delete(fiber);
+                attempts.delete(fiber);
+                return;
+            }
+            consider(fiber);
+        };
+        // On the composition root (plugin rows' lifecycle events never travel
+        // through the TUI row), `global` so child filters cannot hide them; in the
+        // host capability, since the root guard refuses `root.events.on` here.
+        const disposer = withHostRootCapability(() => root.on('internal/status', listener, { global: true }));
+        return () => {
+            if (typeof disposer === 'function') {
+                withHostRootCapability(() => disposer());
+            }
+        };
+    });
+    ctx.effect(() => stopTimer);
+    seed();
+}
+/** The package-root `dsh-plugin.json` of the entry that owns `fiber`, if any.
+ *  Both loader calls are fenced: `EntryTree.resolve` throws for nested ids
+ *  (`include:<group>:<row>`); an uninspectable entry is simply skipped. */
+function manifestPathOf(loader, fiber) {
+    let entry;
+    try {
+        const entryId = loader.locate?.(fiber);
+        entry = entryId === undefined ? undefined : loader.resolve?.(entryId);
+    }
+    catch {
+        return undefined;
+    }
+    const name = entry?.options?.name;
+    if (typeof name !== 'string' || name === '')
+        return undefined;
+    const entryFile = resolveEntryFile(name, entry?.ctx?.baseUrl);
+    return entryFile === undefined ? undefined : findManifest(entryFile);
+}
+/** The module file an entry `name` resolves to, following the same rules the
+ *  loader's own import uses (file URL, relative to `baseUrl`, bare
+ *  specifier relative to the profile). */
+function resolveEntryFile(name, baseUrl) {
+    try {
+        // Builtin rows (loader groups, timers) have no package directory.
+        if (name.startsWith('cordis:'))
+            return undefined;
+        if (name.startsWith('file:'))
+            return fileURLToPath(name);
+        if (isAbsolute(name))
+            return name;
+        if (name.startsWith('.')) {
+            return baseUrl === undefined || baseUrl === '' ? undefined : fileURLToPath(new URL(name, baseUrl));
+        }
+        // Through the package's own resolution: `exports` need not list
+        // `./package.json`, and a subpath (`pkg/sub`) lands on the same root.
+        return findPackageJSON(name, requireBase(baseUrl));
+    }
+    catch {
+        return undefined;
+    }
+}
+function requireBase(baseUrl) {
+    if (baseUrl === undefined || baseUrl === '')
+        return pathToFileURL(join(process.cwd(), 'index.js'));
+    try {
+        return baseUrl.startsWith('file:') ? new URL(baseUrl) : pathToFileURL(join(baseUrl, 'index.js'));
+    }
+    catch {
+        return pathToFileURL(join(process.cwd(), 'index.js'));
+    }
+}
+/** Walk up from the entry module to its package root. The walk stops at the
+ *  first `package.json`: a manifest lives at the package root, never deeper,
+ *  so DSH's own rows (a `package.json` one level up from their entry) cost
+ *  one lookup instead of a climb to the filesystem root. */
+function findManifest(from) {
+    let dir = dirname(resolvePath(from));
+    for (let depth = 0; depth < 64; depth += 1) {
+        const candidate = join(dir, 'dsh-plugin.json');
+        if (existsSync(candidate))
+            return candidate;
+        if (existsSync(join(dir, 'package.json')))
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/types/dsh-adapter/backend/translate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/backend/translate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,0BAA0B,CAAA;AAC/F,OAAO,EAAa,KAAK,UAAU,EAAqB,KAAK,cAAc,EAA0D,MAAM,uBAAuB,CAAA;AAElK,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAI3D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAI1F,MAAM,WAAW,iBAAiB;IAChC;;0DAEsD;IACtD,KAAK,IAAI,iBAAiB,GAAG,SAAS,CAAA;IACtC;4EACwE;IACxE,KAAK,IAAI,OAAO,CAAA;IAChB;+DAC2D;IAC3D,WAAW,IAAI,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAkEtD;AA6FD,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB;4BAgI1B,YAAY,KAAG,SAAS,UAAU,EAAE;4BAsJpC,oBAAoB,KAAG,SAAS,UAAU,EAAE;8BAmB1C,SAAS,YAAY,EAAE,KAAG,SAAS,UAAU,EAAE;iBAU9D,IAAI;4BAnSS,MAAM,WAAW,MAAM,KAAG,YAAY,GAAG,SAAS;8BAYhD,MAAM,WAAW,MAAM,QAAQ,YAAY,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAG,cAAc,GAAG,SAAS;EA6RjI;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"translate.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/backend/translate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,0BAA0B,CAAA;AAC/F,OAAO,EAAa,KAAK,UAAU,EAAqB,KAAK,cAAc,EAA0D,MAAM,uBAAuB,CAAA;AAElK,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAI3D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAI1F,MAAM,WAAW,iBAAiB;IAChC;;0DAEsD;IACtD,KAAK,IAAI,iBAAiB,GAAG,SAAS,CAAA;IACtC;4EACwE;IACxE,KAAK,IAAI,OAAO,CAAA;IAChB;+DAC2D;IAC3D,WAAW,IAAI,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAkEtD;AA6FD,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB;4BAmI1B,YAAY,KAAG,SAAS,UAAU,EAAE;4BAsJpC,oBAAoB,KAAG,SAAS,UAAU,EAAE;8BAmB1C,SAAS,YAAY,EAAE,KAAG,SAAS,UAAU,EAAE;iBAU9D,IAAI;4BAtSS,MAAM,WAAW,MAAM,KAAG,YAAY,GAAG,SAAS;8BAYhD,MAAM,WAAW,MAAM,QAAQ,YAAY,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAG,cAAc,GAAG,SAAS;EAgSjI;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/lib/types/dsh-adapter/backend/translate.js

@@ -217,6 +217,9 @@ export function createDshTranslator(deps) {
                 return NO_EVENTS;
             return [goalChange(change)];
         }
+        if (data.source.kind === 'model-selection') {
+            return [{ type: 'notice', level: 'info', text: textOf(data.content) }];
+        }
         // Injected context (plugin/skill source) is model-facing only; it has no
         // transcript-facing text.
         if (data.source.kind !== 'user')

package/lib/types/dsh-adapter/backend-admission.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Admission of one backend declaration (B-2, W-1): what the *host* knows about a
+ * `BackendSpec`, decided before anything runs.
+ *
+ * `validateBackendSpec()` (tui-profile) answers "is this shape well formed?".
+ * This answers the other half: "can this host honor it?" — a capability name in a
+ * vocabulary the host does not implement, a permission name with no grant, an id
+ * the host owns. The two are deliberately separate layers: the shape validator
+ * lives with the protocol (it must reject the same thing in every host that
+ * implements the family), while these verdicts depend on host state.
+ *
+ * The five-state vocabulary is reused verbatim from the plugin admission
+ * (`NegotiationDecision`, `NEGOTIATION_ERROR_CODES`), not invented here:
+ * a contribution family speaks the same admission language as every other
+ * plugin surface, and `negotiate.ts` stays untouched (it has no backend concept
+ * and does not need one).
+ *
+ * **Scope.** This decides; it does not wire the family into the registry /
+ * descriptor chain by itself. Since W-2 (stage C) that chain *is* wired —
+ * `Backend` is a host-published contract, the profile pins this family's contract
+ * profile by digest and the descriptor publishes the coordinate only on real
+ * probe evidence ({@link probeBackendAdmission}) — while the step that reads a
+ * mounted bundle's declaration into {@link registerBackend} is still the stage C
+ * install chain's work.
+ *
+ * **Published codes.** The contract profile
+ * (`tui-profile/registry/contracts/backend-v1alpha1.json`) publishes exactly the
+ * codes this file can produce: `BACKEND_ID_RESERVED` and `PERMISSION_NOT_GRANTED`.
+ * A code with no producer is a phantom its readers would write error handling for,
+ * so a future one waits until the stage that gives it a producer
+ * (`scripts/verify-backend-contribution.ts` pins the pair).
+ */
+import type { BackendSpec } from '../adapter/spec/tui-contributions.js';
+import type { NegotiationDecision } from '../adapter/standard/types.js';
+/** The host facts the verdict depends on; passed in, so the function is pure. */
+export interface BackendAdmissionHost {
+    /** Ids this host owns (`BUILTIN_BACKEND_IDS`); a contribution may not wear one. */
+    readonly reservedIds: ReadonlySet<string>;
+    /** Names this host's session model implements (`BACKEND_CAPABILITY_NAMES`). */
+    readonly capabilityNames: ReadonlySet<string>;
+    /** The host's permission vocabulary (`EXPECTED_PERMISSIONS`). */
+    readonly permissionNames: ReadonlySet<string>;
+    /** Permissions actually granted to this entry; empty until a grant flow (C). */
+    readonly granted: ReadonlySet<string>;
+}
+/** The verdicts a registered entry can carry: the two that admit, and the one
+ *  that registers without being offered. `rejected`/`unknown` never reach the
+ *  registry — the caller throws on them (a build-time error for an in-tree
+ *  manifest must be loud). `reasonCode` stays a `string` because the vocabulary
+ *  is `NegotiationDecision`'s, shared with every other plugin surface; among
+ *  these three verdicts the only `reasonCode` produced is
+ *  `PERMISSION_NOT_GRANTED` (`rejected` carries `BACKEND_ID_RESERVED`). */
+export type BackendAdmission = {
+    readonly decision: 'compatible';
+} | {
+    readonly decision: 'compatible_degraded';
+    readonly missingOptional: readonly string[];
+} | {
+    readonly decision: 'waiting_authorization';
+    readonly reasonCode: string;
+    readonly deniedPermissions: readonly string[];
+};
+export declare function backendAdmission(spec: BackendSpec, host: BackendAdmissionHost): NegotiationDecision;
+//# sourceMappingURL=backend-admission.d.ts.map

package/lib/types/dsh-adapter/backend-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-admission.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backend-admission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAA;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAEvE,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;2EAM2E;AAC3E,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAO9H,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,oBAAoB,GAAG,mBAAmB,CA4BnG"}

package/lib/types/dsh-adapter/backend-admission.js

@@ -0,0 +1,34 @@
+/** Unknown capability or permission names, in the same list, distinguishable at
+ *  a glance from protocol coordinates (which are `apiVersion#kind`). */
+const capabilityItem = (name) => `capability:${name}`;
+const permissionItem = (name) => `permission:${name}`;
+export function backendAdmission(spec, host) {
+    // A reserved id never reaches here in the in-tree path (registerBackend refuses
+    // it before projecting), but this is the reusable gate for a bundle, so it
+    // refuses it itself rather than trusting the caller to have done it. The other
+    // two member refusals — a host label key and a `nativeKey` declaration — are
+    // shape violations: `validateBackendSpec()` rejects both as unknown fields
+    // (`exactRecord`), so they cannot arrive as a `BackendSpec` at all and never
+    // need a reason code of their own.
+    if (host.reservedIds.has(spec.id)) {
+        return { decision: 'rejected', reasonCode: 'BACKEND_ID_RESERVED' };
+    }
+    const unknownCapabilities = spec.capabilities.filter(name => !host.capabilityNames.has(name));
+    const unknownGrants = spec.grants.filter(name => !host.permissionNames.has(name));
+    const denied = spec.grants.filter(name => host.permissionNames.has(name) && !host.granted.has(name));
+    // A permission the host cannot name is a fact the host must not act on: it is
+    // recorded as a pending item and the entry degrades, exactly like an unknown
+    // capability (D-3). Silently treating it as usable would claim a grant nobody
+    // can revoke; refusing would invent a permission vocabulary.
+    const missingOptional = [...unknownCapabilities.map(capabilityItem), ...unknownGrants.map(permissionItem)];
+    if (denied.length > 0) {
+        return {
+            decision: 'waiting_authorization',
+            reasonCode: 'PERMISSION_NOT_GRANTED',
+            deniedPermissions: [...denied],
+        };
+    }
+    if (missingOptional.length > 0)
+        return { decision: 'compatible_degraded', missingOptional };
+    return { decision: 'compatible' };
+}

package/lib/types/dsh-adapter/backend-contribution.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The in-tree side of the `Backend` contribution family (B-2): one projection
+ * from this package's own manifest shape to the public declaration shape.
+ *
+ * A built-in manifest is a **superset** of `BackendSpec`: it carries in-tree
+ * facts (`inTree`, `alwaysAvailable`, `nativeKey`, `vendorPackages`,
+ * `backendExport`, and a `label` that may name a host i18n key) that no
+ * contribution may declare. Dogfooding therefore means proving the projection:
+ * `backendContributionOf()` strips those, expands the label into the literal
+ * text the spec requires, and the result must satisfy `validateBackendSpec()` for
+ * every built-in. A manifest that grows a field the spec cannot express reds here
+ * instead of drifting (scripts/verify-backend-contribution.ts).
+ *
+ * `backendExport` stays in-tree on purpose: it is the build-time index's
+ * mechanism (the registry reads an export name out of a module namespace), not a
+ * contribution field. A contribution hands its handler object over at
+ * registration, like `assertSceneHandler`'s scene handlers.
+ */
+import type { BackendManifest } from '../agent/backend-manifest.js';
+/**
+ * Project one manifest onto the public declaration. Pure: the same manifest
+ * projects to a deep-equal value every time (no timestamps, no host state), which
+ * is what lets the gate compare two projections and diff keys.
+ */
+export declare function backendContributionOf(manifest: BackendManifest): Record<string, unknown>;
+//# sourceMappingURL=backend-contribution.d.ts.map

package/lib/types/dsh-adapter/backend-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-contribution.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backend-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAoBnE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAaxF"}

package/lib/types/dsh-adapter/backend-contribution.js

@@ -0,0 +1,37 @@
+import { t } from '../i18n.js';
+/** The label text a contribution would declare, or a refusal.
+ *
+ *  Only an in-tree manifest may carry a host i18n key, and the projection is what
+ *  turns one into the literal text the spec requires — so it is also where the rule
+ *  has to hold when the projection is called directly: expanding a *plugin's* key
+ *  would launder it into the literal `t()` happens to return, i.e. let a contribution
+ *  paint itself with this host's own name. `registerBackend` refuses that combination
+ *  before projecting; this refuses it again, so the exported projection cannot be used
+ *  to do what registration forbids. */
+function labelTextOf(manifest) {
+    if (manifest.label.kind === 'literal')
+        return manifest.label.text;
+    if (!manifest.inTree) {
+        throw new Error(`dsh-tui: backend "${manifest.id}" is not in-tree and may not project a host label key`);
+    }
+    return t(manifest.label.key);
+}
+/**
+ * Project one manifest onto the public declaration. Pure: the same manifest
+ * projects to a deep-equal value every time (no timestamps, no host state), which
+ * is what lets the gate compare two projections and diff keys.
+ */
+export function backendContributionOf(manifest) {
+    return {
+        id: manifest.id,
+        label: { text: labelTextOf(manifest) },
+        shortLabel: manifest.shortLabel,
+        ...(manifest.product === undefined ? {} : { product: manifest.product }),
+        // Absent declarations project to the empty list: the spec requires both
+        // fields, so "I declare nothing" must be sayable and must mean "nothing".
+        capabilities: [...(manifest.capabilities ?? [])],
+        grants: [...(manifest.grants ?? [])],
+        ...(manifest.install === undefined ? {} : { install: { ...manifest.install } }),
+        ...(manifest.unloadExport === undefined ? {} : { unloadExport: manifest.unloadExport }),
+    };
+}

package/lib/types/dsh-adapter/backend-registry.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The runtime backend registry (roadmap Stage A / P0).
+ *
+ * Before this module, "which backends exist" was a hand-written closed set
+ * spread over `kernelPrefs.ts`, this adapter, the launcher copy and the boundary
+ * gate: every new backend had to be copied into all of them (codex did exactly
+ * that, #1352). Now the set is the built-in seed plus whatever the build-time
+ * index found under `src/backends/*​/manifest.ts` — adding a backend is a new
+ * directory, nothing else.
+ *
+ * Three properties this file must keep (they are what a fourth backend would
+ * otherwise break):
+ *
+ *  - **Lazy**: an entry that is never loaded is never imported. `probeKernels`
+ *    is the only path that loads everything, and it is opt-in.
+ *  - **Booked pooling** (D4): `unloadExport` is remembered when — and only when —
+ *    the entry's module was actually imported, so a DSH-only boot does not pay a
+ *    module import (let alone a child process) just to close a pool it never
+ *    opened. The one exit funnel (`plugin.ts`'s `disposeRootAndThen`) calls
+ *    {@link unloadBackends} after the fiber is disposed and stays otherwise
+ *    untouched.
+ *  - **Membership is the second half of the parse** (D1): a syntactically valid
+ *    but unregistered id must behave exactly like an unknown value everywhere
+ *    (dsh + a warning, never a crashed boot). See {@link parseBackendChoice}.
+ */
+import type { AgentBackend } from '../agent/backend.js';
+import { isBackendIdSyntax, type BackendEntry, type BackendManifest } from '../agent/backend-manifest.js';
+import { type KernelBackendId } from '../kernelPrefs.js';
+import { type BackendAdmission } from './backend-admission.js';
+export { isBackendIdSyntax };
+/**
+ * One registered backend: the manifest, its id as a validated {@link KernelBackendId}
+ * (the cast below is reached only after the syntax gate), the lazy loader, and the
+ * one fact the registry derives from the manifest.
+ *
+ * `installable` is derived, not declared: the old `installable` field was a
+ * boolean that the registration gate forced to equal "declares install data", so
+ * it carried no information of its own — and the half that *is* a runtime
+ * question (`does this host run that executor?`) could not be written in a
+ * manifest at all. Picker rows read it from here, and `installSurfaceFor(id)`
+ * answers the same question with the actions attached.
+ */
+export interface RegisteredBackend {
+    readonly id: KernelBackendId;
+    readonly manifest: BackendManifest;
+    readonly installable: boolean;
+    /**
+     * What the admission decided about this entry (B-2). `compatible_degraded`
+     * carries the names the host does not implement, `waiting_authorization` the
+     * permissions nobody granted; `rejected` and `unknown` never become an entry
+     * (registration throws on them). Every in-tree backend is `compatible` today.
+     */
+    readonly admission: BackendAdmission;
+    readonly load?: () => Promise<Record<string, unknown>>;
+}
+/**
+ * Add one entry. The built-in seeds register themselves below; the plugin
+ * discovery of Stage C is the intended second caller, which is why the checks
+ * are loud rather than lenient: a bad manifest must fail at registration, not
+ * paint a wrong row.
+ */
+export declare function registerBackend(entry: BackendEntry): void;
+/** Every registered backend, in declaration order (= picker order). */
+export declare function listBackends(): readonly RegisteredBackend[];
+/**
+ * The entries a picker may offer (B-2). A `waiting_authorization` entry is
+ * registered — its id exists, the boot's two-stage parse must find it, and its
+ * session refs must resolve — but it is not offered: nothing has granted what it
+ * declares, so selecting it would open a backend the host cannot describe. Today
+ * no entry is in that state (every in-tree manifest declares `grants: []`); the
+ * shape exists so the C stage's grant flow has somewhere to land.
+ */
+export declare function listOfferedBackends(): readonly RegisteredBackend[];
+/**
+ * What the backend admission machine reports when asked whether it is mounted
+ * and can admit a *contribution* (W-2).
+ */
+export interface BackendAdmissionProbe {
+    /** Entries the registry holds: the built-in seed plus every registration. */
+    readonly registered: number;
+    /** How many of them a picker may offer (not `waiting_authorization`). */
+    readonly offered: number;
+    /** What a synthetic third-party declaration was admitted as. A machine that
+     *  could not answer `compatible` would refuse every contribution, so this is
+     *  the one verdict the probe accepts. */
+    readonly verdict: 'compatible';
+}
+/**
+ * Read-only probe behind the host descriptor's `Backend` contract (W-2): is the
+ * backend admission machine mounted, and does it answer for a *contribution*?
+ *
+ * The descriptor publishes `tui.dsh/v1alpha1#Backend` only on real probe evidence
+ * (`hasVerificationEvidence`, descriptor publication barrier), and "a service row
+ * exists" is deliberately not evidence. So this probe walks the same path a
+ * third-party declaration takes — build a declaration no host owns, run it
+ * through the family validator, then through the host's admission facts — and
+ * reports what came back. It registers nothing, imports nothing and writes
+ * nothing: an entry that was never loaded is still never loaded.
+ */
+export declare function probeBackendAdmission(): BackendAdmissionProbe;
+/** One backend, or undefined when no such backend is registered. */
+export declare function getBackend(id: string): RegisteredBackend | undefined;
+/** Whether an untrusted value names a backend this process can actually run.
+ *  This is the second half of the parse (D1) and the only way to obtain a
+ *  {@link KernelBackendId} outside `kernelPrefs`' own syntax gate. */
+export declare function isRegisteredBackend(value: unknown): value is KernelBackendId;
+/**
+ * The backend a configured / remembered value names: trimmed, lowercased, and
+ * **registered**. Anything else is undefined, which every caller already treats
+ * as "no choice made" (dsh + a warning) — the semantics an unknown value had
+ * before the set was open (D1).
+ */
+export declare function parseBackendChoice(value: unknown): KernelBackendId | undefined;
+/** The display name of a backend id: its manifest's short brand name, else the
+ *  id itself (a session from an uninstalled plugin must still render as
+ *  something). */
+export declare function backendLabel(id: string): string;
+/**
+ * Import one registered backend's implementation and book its pool hook.
+ *
+ * The two failure messages stay distinct (D1): "not registered" means the id was
+ * never a choice, "has no loader" means the id names the host's own kernel.
+ */
+export declare function loadBackend(id: KernelBackendId): Promise<AgentBackend>;
+/**
+ * Close the pooled, process-wide resources of every backend this process
+ * actually loaded, in load order, then forget them (idempotent).
+ *
+ * Called once from the exit funnel *after* `ctx.root.fiber.dispose()`: closing a
+ * pool first would break the in-flight sessions whose calls still hold it
+ * (D4-P3). A failing or hanging hook must not block the exit — failures only
+ * reach the debug log, and a stuck one is caught by the funnel's existing 5s
+ * bound (P4).
+ */
+export declare function unloadBackends(): Promise<void>;
+//# sourceMappingURL=backend-registry.d.ts.map

package/lib/types/dsh-adapter/backend-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-registry.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backend-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAKzG,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAE7E,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAKhF,OAAO,EAAE,iBAAiB,EAAE,CAAA;AA6C5B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACvD;AA0CD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAgEzD;AAOD,uEAAuE;AACvE,wBAAgB,YAAY,IAAI,SAAS,iBAAiB,EAAE,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,iBAAiB,EAAE,CAElE;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;6CAEyC;IACzC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,IAAI,qBAAqB,CAkB7D;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEpE;AAED;;sEAEsE;AACtE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAI9E;AAED;;kBAEkB;AAClB,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAkB5E;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CASpD"}