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

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

@@ -0,0 +1,285 @@
+import { isBackendIdSyntax } from '../agent/backend-manifest.js';
+import { BACKEND_CAPABILITY_NAMES } from '../adapter/spec/backend-capabilities.js';
+import { EXPECTED_PERMISSIONS } from '../adapter/spec/protocol-constants.js';
+import { validateBackendSpec } from '../adapter/spec/tui-contributions.js';
+import { cleanRenderText } from '../channel/sanitize.js';
+import { BUILTIN_BACKEND_IDS } from '../kernelPrefs.js';
+import { logForDebugging } from '../utils/debug.js';
+import { backendAdmission } from './backend-admission.js';
+import { backendContributionOf } from './backend-contribution.js';
+import { GENERATED_BACKENDS } from './backends.generated.js';
+import { installExecutor } from './install/executors.js';
+export { isBackendIdSyntax };
+/**
+ * The DSH kernel. In-tree and always available, but **not** an `AgentBackend`:
+ * its session is built by `createDshSession()` from the DSH agent, and P0 does
+ * not force it into the backend contract just for symmetry (roadmap §7.3).
+ * Seeded first, so the picker order stays `dsh, claude, codex, …`.
+ */
+const DSH_MANIFEST = {
+    id: 'dsh',
+    label: { kind: 'key', key: 'kernel-label-dsh' },
+    shortLabel: 'DSH',
+    product: 'dsh-core',
+    inTree: true,
+    alwaysAvailable: true,
+    // Not an `AgentBackend`, so it has no optional session surface to declare —
+    // stated explicitly rather than left to the projection's default (B-2).
+    capabilities: [],
+    grants: [],
+};
+/**
+ * What replaced Stage A's `HOST_INSTALLABLE_BACKEND_ID = 'claude'`: a manifest
+ * now *names an executor* (`BackendManifest.install.executor`) and the registry
+ * looks the name up in the host's table (`src/dsh-adapter/install/`). An entry is
+ * installable exactly when that lookup finds something, so the row that opens a
+ * wizard is the row whose own recipe names an executor this host runs — not the
+ * row that happens to wear the privileged id.
+ *
+ * A table rather than a static import of one backend's installer, because the
+ * discovery this has to survive is the post-mount one: Stage C reads a bundle's
+ * contribution after the plugin is mounted (§4.4), and a link-time constant could
+ * not be consulted then.
+ *
+ * An unknown executor is **not** a registration error (§6 item 12): the entry
+ * registers with no install surface, and its "not installed" row degrades to
+ * detection's own hint instead of growing a button that cannot work. The recipe
+ * is therefore validated for *shape* here, never for whether this host likes its
+ * value. The strings a plugin declares are also the wizard's render path and (on
+ * Windows) a `pnpm add` argument, so admitting a third-party recipe is Stage C/D
+ * work — until then a plugin may name only a value of this closed table.
+ */
+const installableOf = (manifest) => manifest.install !== undefined && installExecutor(manifest.install.executor) !== undefined;
+/** Registration order = picker order (`listBackends`). */
+const entries = new Map();
+/**
+ * Cell budget for a plugin-declared name. The picker pane is at most ~72 cells
+ * wide and the launchpad plate far narrower, so this only bounds what a
+ * misbehaving manifest can put on the render path (and in the notices written to
+ * stdout) — layout truncation stays the renderer's job.
+ */
+const LABEL_MAX_CELLS = 48;
+/** Close hooks of the entries whose module was actually imported (D4). */
+const loadedUnloads = new Map();
+/**
+ * What this host knows when admitting a backend declaration (B-2). The
+ * vocabularies come from the spec plane (`src/adapter/spec/**`), the granted set
+ * is empty until a backend grant flow exists (C stage) — which is why every
+ * in-tree manifest declares `grants: []` rather than a permission nobody could
+ * grant (D-3).
+ */
+const HOST_ADMISSION_FACTS = {
+    reservedIds: new Set(BUILTIN_BACKEND_IDS),
+    capabilityNames: new Set(BACKEND_CAPABILITY_NAMES),
+    permissionNames: new Set(EXPECTED_PERMISSIONS.map(permission => permission.name)),
+    granted: new Set(),
+};
+/**
+ * The same facts for **this host's own seed**: a built-in manifest legitimately
+ * wears a built-in id, so the reserved set is the one rule that flips. Everything
+ * else (the capability and permission vocabularies) applies to a seed exactly as
+ * it does to a contribution — and the admission verdict is still recorded, which
+ * is what makes the dogfood check in `verify-backend-contribution.ts` meaningful.
+ */
+const SEED_ADMISSION_FACTS = { ...HOST_ADMISSION_FACTS, reservedIds: new Set() };
+const admissionFactsFor = (manifest) => manifest.inTree ? SEED_ADMISSION_FACTS : HOST_ADMISSION_FACTS;
+/**
+ * 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 function registerBackend(entry) {
+    const { manifest } = entry;
+    const where = `dsh-tui: backend "${manifest.id}"`;
+    if (!isBackendIdSyntax(manifest.id)) {
+        throw new Error(`${where} has an invalid id (lowercase letters, digits and dashes, at most 32 characters)`);
+    }
+    if (entries.has(manifest.id))
+        throw new Error(`${where} is already registered`);
+    if (!manifest.inTree && BUILTIN_BACKEND_IDS.includes(manifest.id)) {
+        // `dsh` refs serialize without a prefix (`formatSessionRef`), so a plugin
+        // wearing that id would collide with first-party references.
+        throw new Error(`${where} is a reserved built-in id`);
+    }
+    if (!manifest.inTree && manifest.label.kind === 'key') {
+        // Otherwise a plugin could claim a first-party name: `t()` returns the text
+        // of an existing key (`src/i18n.ts`), so the row would read "DeepSeek Harness".
+        throw new Error(`${where} is not in-tree and may not use a host label key; declare { kind: 'literal', text }`);
+    }
+    if (!manifest.inTree && manifest.alwaysAvailable === true) {
+        throw new Error(`${where} is not in-tree and may not be always-available`);
+    }
+    if (!manifest.inTree && manifest.nativeKey !== undefined) {
+        throw new Error(`${where} is not in-tree and may not declare a native channel`);
+    }
+    if (manifest.alwaysAvailable === true && entry.load !== undefined) {
+        throw new Error(`${where} is always-available and must not have a loader (it is not an AgentBackend)`);
+    }
+    // Shape only: what the recipe names is the host's business, and a value it does
+    // not implement means "no install surface", never a refused registration.
+    const install = manifest.install;
+    if (install !== undefined && ![install.executor, install.specifier, install.version].every(field => typeof field === 'string' && field !== '')) {
+        throw new Error(`${where} declares an install recipe without a non-empty executor, specifier and version`);
+    }
+    // The contribution family gate (B-2). Order matters: project the in-tree
+    // superset down to the public declaration, validate that declaration against the
+    // family's own definition (the same validator every other host of this protocol
+    // runs), then decide the half only this host can answer — capability and
+    // permission vocabularies. A refusal here is a build-time error and must be
+    // loud; a `waiting_authorization` entry registers, because the id does exist and
+    // the boot, the warnings and the session refs must know it, but it is not
+    // offered (see {@link listOfferedBackends}).
+    const contribution = validateBackendSpec(backendContributionOf(manifest));
+    const verdict = backendAdmission(contribution, admissionFactsFor(manifest));
+    if (verdict.decision === 'rejected' || verdict.decision === 'unknown') {
+        throw new Error(`${where} was refused at admission: ${verdict.reasonCode}`);
+    }
+    const admission = verdict;
+    // Plugin-declared names are external input: flatten control/escape sequences
+    // and cap the width here, once, so the picker, the launchpad plate and the
+    // handoff notices all render the same sanitized text (in-tree names are this
+    // package's own strings and stay verbatim; `label.key` must stay a raw key).
+    const registered = {
+        // The one place that may mint a KernelBackendId: the syntax gate above has
+        // already run, and membership is this very map.
+        id: manifest.id,
+        manifest: manifest.inTree ? manifest : {
+            ...manifest,
+            label: manifest.label.kind === 'literal' ? { kind: 'literal', text: cleanRenderText(manifest.label.text, LABEL_MAX_CELLS) } : manifest.label,
+            shortLabel: cleanRenderText(manifest.shortLabel, LABEL_MAX_CELLS),
+        },
+        installable: installableOf(manifest),
+        admission,
+        ...(entry.load === undefined ? {} : { load: entry.load }),
+    };
+    entries.set(manifest.id, registered);
+}
+// The built-in seed: dsh first, then the generated index in directory-name
+// order (claude, codex, …).
+registerBackend({ manifest: DSH_MANIFEST });
+for (const entry of GENERATED_BACKENDS)
+    registerBackend(entry);
+/** Every registered backend, in declaration order (= picker order). */
+export function listBackends() {
+    return [...entries.values()];
+}
+/**
+ * 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 function listOfferedBackends() {
+    return listBackends().filter(entry => entry.admission.decision !== 'waiting_authorization');
+}
+/**
+ * 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 function probeBackendAdmission() {
+    const entries = listBackends();
+    const offered = listOfferedBackends().length;
+    // A declaration with no reserved id, no capabilities and no grants — the shape
+    // the profile's own CLI-shaped fixture uses, so the verdict cannot depend on
+    // anything this host happens to have registered.
+    const declaration = validateBackendSpec({
+        id: 'admission-probe',
+        label: { text: 'Admission probe' },
+        shortLabel: 'Admission probe',
+        capabilities: [],
+        grants: [],
+    });
+    const verdict = backendAdmission(declaration, HOST_ADMISSION_FACTS);
+    if (verdict.decision !== 'compatible') {
+        throw new Error(`dsh-tui: backend admission machine answered ${verdict.decision}; it cannot admit a contribution`);
+    }
+    return Object.freeze({ registered: entries.length, offered, verdict: 'compatible' });
+}
+/** One backend, or undefined when no such backend is registered. */
+export function getBackend(id) {
+    return entries.get(id);
+}
+/** 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 function isRegisteredBackend(value) {
+    return isBackendIdSyntax(value) && entries.has(value);
+}
+/**
+ * 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 function parseBackendChoice(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const id = value.trim().toLowerCase();
+    return isRegisteredBackend(id) ? id : 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 function backendLabel(id) {
+    return getBackend(id)?.manifest.shortLabel ?? id;
+}
+/**
+ * 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 async function loadBackend(id) {
+    const entry = entries.get(id);
+    if (entry === undefined)
+        throw new Error(`dsh-tui: backend "${id}" is not registered`);
+    if (entry.load === undefined)
+        throw new Error(`dsh-tui: backend "${id}" has no loader (only the DSH kernel is not an AgentBackend)`);
+    const module = await entry.load();
+    const { backendExport, unloadExport } = entry.manifest;
+    if (unloadExport !== undefined) {
+        const unload = module[unloadExport];
+        if (typeof unload !== 'function') {
+            throw new Error(`dsh-tui: backend "${id}" declares unloadExport "${unloadExport}", but its module does not export it`);
+        }
+        // Overwriting is fine: the same module instance hands back the same hook.
+        loadedUnloads.set(id, unload);
+    }
+    const exportName = backendExport ?? 'backend';
+    const backend = module[exportName];
+    if (backend === undefined)
+        throw new Error(`dsh-tui: backend "${id}" does not export "${exportName}"`);
+    return backend;
+}
+/**
+ * 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 async function unloadBackends() {
+    for (const [id, unload] of loadedUnloads) {
+        try {
+            await unload();
+        }
+        catch (error) {
+            logForDebugging(`dsh-tui: backend "${id}" unload failed (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    loadedUnloads.clear();
+}

package/lib/types/dsh-adapter/backends.d.ts

@@ -1,41 +1,78 @@
 /** Non-DSH backend loading, detection and startup session ownership. */
 import type { Context } from '@deepseek-ai/cordis';
-import type { AgentBackend, BackendHost, OpenTarget, SdkInstallTarget, SdkInstaller } from '../agent/backend.js';
+import type { AgentBackend, BackendHost, OpenTarget, SdkInstallSurface } from '../agent/backend.js';
 import type { AgentEvent } from '../agent/events.js';
 import type { AgentSession } from '../agent/session.js';
 import type { KernelStatus } from '../components/kernelCatalog.js';
-/** Close an already-loaded backend's pooled processes without loading it on DSH. */
-export declare function closeBackendResources(): Promise<void>;
-export declare const BACKEND_LOADERS: {
-    claude: () => Promise<AgentBackend>;
-    codex: () => Promise<AgentBackend>;
-};
-/** The kernel picker's one-click SDK install surface (Chat consumes it as
- *  props; the types are the neutral ones from agent/backend.js). */
-export declare const sdkInstall: {
-    resolveTarget: () => SdkInstallTarget;
-    start: (dir: string) => SdkInstaller;
-    checkPnpm: () => Promise<boolean>;
-    pinned: {
-        readonly specifier: "@anthropic-ai/claude-agent-sdk@0.3.287";
-        readonly version: "0.3.287";
-    };
-};
-/** All probes and sessions share one credential source per provider. */
-export declare function createBackendHost(ctx: Context, cwd: string, stderr: (line: string) => void): Promise<BackendHost>;
-/** Resume failures abort boot; history is read before the channel's first paint. */
-export declare function openBackendStartup(ctx: Context, backend: AgentBackend, input: {
+/**
+ * The install surface of one registered backend (Stage B / B-1): the manifest's
+ * recipe with the actions of the executor that recipe names. Undefined when the
+ * entry declares no recipe, is not registered, or names an executor this host
+ * does not implement — all three are "no install surface", which the picker
+ * renders as the dim row's dead-end reason.
+ *
+ * The manifest says **what** (specifier + pin) and **which executor**; nothing
+ * here imports a backend, and nothing is resolved before the user picks a row:
+ * the entry behind that row is the one whose recipe gets run (§6 item 12).
+ *
+ * The id is a plain `string` on purpose, exactly like `getBackend`: membership is
+ * half of what this answers, so asking about an id that was never registered is a
+ * question with an answer, not a type error.
+ */
+export declare function installSurfaceFor(id: string): SdkInstallSurface | undefined;
+/**
+ * The host services of one backend. Built per backend (not once for all of
+ * them) because `dataDir` is backend-scoped: `<DATA_DIR>/backends/<id>` is the
+ * only place a backend has any business writing, and the id is what names it.
+ *
+ * `locale` is a live read, not a snapshot: `/lang` switches the whole UI at
+ * runtime, and a backend's own text follows it string by string (B-3). The
+ * language union is restated by `getLang()`'s own return type, so a new
+ * shipped language fails to compile here until the domain contract knows it.
+ */
+export declare function createBackendHost(ctx: Context, backendId: string, cwd: string, stderr: (line: string) => void): Promise<BackendHost>;
+/**
+ * What the channel needs about the startup backend before its session exists,
+ * plus `start()`, which opens it (mount claim, open, history); the screen
+ * mounts in between.
+ * A resume failure rejects `start()`; no fresh session is started instead.
+ */
+export declare function prepareBackendStartup(ctx: Context, backend: AgentBackend, input: {
     readonly cwd: string;
     readonly stderr: (line: string) => void;
     readonly configuredSessionId?: string;
     readonly argv: readonly string[];
 }): Promise<{
-    session: AgentSession;
+    resumedSessionId: string | undefined;
     label: string;
     backendId: string;
+    catalog: import("../agent/backend.js").SessionCatalog | undefined;
+    sessionPrefs: import("../agent/backend.js").BackendSessionPrefs;
+    start: () => Promise<{
+        session: AgentSession;
+        initialHistory: readonly AgentEvent[];
+    }>;
+    persisted: (_sessionId: string, rows: readonly {
+        readonly kind: string;
+    }[]) => boolean;
+    resumeCommand: (sessionId: string) => string;
+    open: (target: Extract<OpenTarget, {
+        readonly kind: "create" | "resume";
+    }>) => Promise<AgentSession>;
+}>;
+/** Resume failures abort boot; history is read before the channel's first paint. */
+export declare function openBackendStartup(ctx: Context, backend: AgentBackend, input: Parameters<typeof prepareBackendStartup>[2]): Promise<{
+    session: AgentSession;
     initialHistory: readonly AgentEvent[];
+    resumedSessionId: string | undefined;
+    label: string;
+    backendId: string;
     catalog: import("../agent/backend.js").SessionCatalog | undefined;
     sessionPrefs: import("../agent/backend.js").BackendSessionPrefs;
+    start: () => Promise<{
+        session: AgentSession;
+        initialHistory: readonly AgentEvent[];
+    }>;
     persisted: (_sessionId: string, rows: readonly {
         readonly kind: string;
     }[]) => boolean;
@@ -44,6 +81,12 @@ export declare function openBackendStartup(ctx: Context, backend: AgentBackend,
         readonly kind: "create" | "resume";
     }>) => Promise<AgentSession>;
 }>;
-/** Probe optional backends lazily; failed loading leaves their row unavailable. */
+/**
+ * Probe every optional backend once (`dsh` is always available and has no
+ * loader). Loading goes through the registry, so a probed backend's pool hook is
+ * booked just like an opened one's — a backend that builds its pool in `detect()`
+ * (the contract does not forbid it) is then still closed at exit. Failures leave
+ * their row unavailable instead of failing the probe.
+ */
 export declare function probeKernels(ctx: Context, cwd: string): Promise<Record<string, KernelStatus>>;
 //# sourceMappingURL=backends.d.ts.map

package/lib/types/dsh-adapter/backends.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backends.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backends.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAyB,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvI,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAclE,oFAAoF;AACpF,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3D;AAED,eAAO,MAAM,eAAe;;;CAMoD,CAAA;AAEhF;oEACoE;AACpE,eAAO,MAAM,UAAU;yBACF,gBAAgB;iBACtB,MAAM,KAAG,YAAY;qBACnB,OAAO,CAAC,OAAO,CAAC;;;;;CAEhC,CAAA;AAID,wEAAwE;AACxE,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBvH;AAED,oFAAoF;AACpF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE;IACnF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;;;;;;;4BAgD2B,MAAM,QAAQ,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;+BAC/C,MAAM;mBAClB,OAAO,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,CAAC;GAG7E;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAYnG"}
+{"version":3,"file":"backends.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backends.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAyB,UAAU,EAAE,iBAAiB,EAAkC,MAAM,qBAAqB,CAAA;AAC1J,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAWlE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAW3E;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAqB1I;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;;;;;;iBASyB,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,cAAc,EAAE,SAAS,UAAU,EAAE,CAAA;KAAE,CAAC;4BA2CvE,MAAM,QAAQ,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;+BAC/C,MAAM;mBAClB,OAAO,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,CAAC;GAG7E;AAED,oFAAoF;AACpF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC;aAnDnF,YAAY;oBAAkB,SAAS,UAAU,EAAE;;;;;;iBAAtE,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,cAAc,EAAE,SAAS,UAAU,EAAE,CAAA;KAAE,CAAC;4BA2CvE,MAAM,QAAQ,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;+BAC/C,MAAM;mBAClB,OAAO,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,CAAC;GAS7E;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAenG"}

package/lib/types/dsh-adapter/backends.generated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * GENERATED by scripts/gen-backend-index.mjs — do not edit.
+ * 2 backend manifest(s) in directory-name order (picker order):
+ * claude, codex.
+ *
+ * `pnpm compile` refreshes this file: commit the result. It is checked in
+ * because the CI test groups restore the build artifact instead of compiling, and
+ * the registry imports it from `src/` (see the generator for the whole story).
+ */
+import type { BackendEntry } from '../agent/backend-manifest.js';
+export declare const GENERATED_BACKENDS: readonly BackendEntry[];
+//# sourceMappingURL=backends.generated.d.ts.map

package/lib/types/dsh-adapter/backends.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.generated.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backends.generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAIhE,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAGrD,CAAA"}

package/lib/types/dsh-adapter/backends.generated.js

@@ -0,0 +1,6 @@
+import { manifest as claudeManifest } from '../backends/claude/manifest.js';
+import { manifest as codexManifest } from '../backends/codex/manifest.js';
+export const GENERATED_BACKENDS = [
+    { manifest: claudeManifest, load: () => import('../backends/claude/index.js') },
+    { manifest: codexManifest, load: () => import('../backends/codex/index.js') },
+];

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

@@ -1,40 +1,63 @@
+import { join } from 'node:path';
 import { formatSessionRef } from '../agent/refs.js';
+import { getBackend, listBackends, loadBackend } from './backend-registry.js';
 import { reserveMount, reserveNewSession } from '../sessionMounts.js';
 import { resumeTargetFromArgv } from '../sessionHistory.js';
 import { mountFailureText } from '../sessions/resumeFailure.js';
+import { getLang } from '../i18n.js';
+import { installedTuiVersion } from '../update.js';
 import { logForDebugging } from '../utils/debug.js';
-// Static on purpose: the install module imports no vendor package (node
-// built-ins + update.ts, which this adapter loads anyway), so a DSH-only
-// boot pays nothing for having the wizard's surface at hand.
-import { checkPnpmAvailable, CLAUDE_SDK_SPECIFIER, resolveSdkInstallTarget, startClaudeSdkInstall } from '../backends/claude/install.js';
-import { VALIDATED_SDK_VERSION } from '../backends/claude/contract.js';
+import { DATA_DIR } from '../utils/paths.js';
+import { installExecutor } from './install/executors.js';
 import { fileChannelTokens } from '../backends/shared/channel-tokens.js';
-let closeCodexHubs;
-/** Close an already-loaded backend's pooled processes without loading it on DSH. */
-export async function closeBackendResources() {
-    await closeCodexHubs?.();
+/**
+ * The install surface of one registered backend (Stage B / B-1): the manifest's
+ * recipe with the actions of the executor that recipe names. Undefined when the
+ * entry declares no recipe, is not registered, or names an executor this host
+ * does not implement — all three are "no install surface", which the picker
+ * renders as the dim row's dead-end reason.
+ *
+ * The manifest says **what** (specifier + pin) and **which executor**; nothing
+ * here imports a backend, and nothing is resolved before the user picks a row:
+ * the entry behind that row is the one whose recipe gets run (§6 item 12).
+ *
+ * The id is a plain `string` on purpose, exactly like `getBackend`: membership is
+ * half of what this answers, so asking about an id that was never registered is a
+ * question with an answer, not a type error.
+ */
+export function installSurfaceFor(id) {
+    const recipe = getBackend(id)?.manifest.install;
+    if (recipe === undefined)
+        return undefined;
+    const executor = installExecutor(recipe.executor);
+    if (executor === undefined)
+        return undefined;
+    return {
+        ...recipe,
+        resolveTarget: () => executor.resolveTarget(),
+        start: (dir) => executor.start(recipe.specifier, dir),
+        preflight: () => executor.preflight(),
+    };
 }
-export const BACKEND_LOADERS = {
-    claude: () => import('../backends/claude/index.js').then(m => m.claudeBackend),
-    codex: () => import('../backends/codex/index.js').then(m => {
-        closeCodexHubs = m.closeAllCodexHubs;
-        return m.codexBackend;
-    }),
-};
-/** The kernel picker's one-click SDK install surface (Chat consumes it as
- *  props; the types are the neutral ones from agent/backend.js). */
-export const sdkInstall = {
-    resolveTarget: () => resolveSdkInstallTarget(),
-    start: (dir) => startClaudeSdkInstall(dir),
-    checkPnpm: () => checkPnpmAvailable(),
-    pinned: { specifier: CLAUDE_SDK_SPECIFIER, version: VALIDATED_SDK_VERSION },
-};
 const credentialSources = new Map();
-/** All probes and sessions share one credential source per provider. */
-export async function createBackendHost(ctx, cwd, stderr) {
+/**
+ * The host services of one backend. Built per backend (not once for all of
+ * them) because `dataDir` is backend-scoped: `<DATA_DIR>/backends/<id>` is the
+ * only place a backend has any business writing, and the id is what names it.
+ *
+ * `locale` is a live read, not a snapshot: `/lang` switches the whole UI at
+ * runtime, and a backend's own text follows it string by string (B-3). The
+ * language union is restated by `getLang()`'s own return type, so a new
+ * shipped language fails to compile here until the domain contract knows it.
+ */
+export async function createBackendHost(ctx, backendId, cwd, stderr) {
     const { createOAuthCredentialSource } = await import('./oauth-credential-source.js');
+    const appVersion = installedTuiVersion();
     return {
         cwd,
+        dataDir: join(DATA_DIR, 'backends', backendId),
+        locale: () => getLang(),
+        ...(appVersion === undefined ? {} : { appVersion }),
         debug: message => logForDebugging(message),
         warn: message => ctx.logger.warn(message),
         stderr,
@@ -49,26 +72,37 @@ export async function createBackendHost(ctx, cwd, stderr) {
         },
     };
 }
-/** Resume failures abort boot; history is read before the channel's first paint. */
-export async function openBackendStartup(ctx, backend, input) {
+/**
+ * What the channel needs about the startup backend before its session exists,
+ * plus `start()`, which opens it (mount claim, open, history); the screen
+ * mounts in between.
+ * A resume failure rejects `start()`; no fresh session is started instead.
+ */
+export async function prepareBackendStartup(ctx, backend, input) {
     const launch = backend.launch;
     if (launch === undefined)
         throw new Error(`dsh-tui: backend "${backend.id}" does not support startup`);
-    const host = await createBackendHost(ctx, input.cwd, input.stderr);
-    const prefs = launch.sessionPrefs(host.debug);
+    const host = await createBackendHost(ctx, backend.id, input.cwd, input.stderr);
+    const prefs = launch.sessionPrefs(host);
     const requested = (input.configuredSessionId ?? resumeTargetFromArgv(input.argv, () => prefs.lastSession()))?.trim();
     const resumeId = requested === undefined || requested === ''
         ? undefined
         : requested.startsWith(`${backend.id}:`) ? requested.slice(backend.id.length + 1) : requested;
-    let session;
-    let initialHistory = [];
-    if (resumeId !== undefined) {
+    const start = async () => {
+        if (resumeId === undefined) {
+            const session = await backend.open({ kind: 'create', cwd: input.cwd }, host);
+            const { reservation } = await reserveNewSession(formatSessionRef(session.ref));
+            reservation.settle();
+            return { session, initialHistory: [] };
+        }
         const key = formatSessionRef({ backendId: backend.id, sessionId: resumeId });
         const reserved = await reserveMount(key);
         if (!reserved.ok) {
             throw new Error(`dsh-tui: cannot resume ${backend.descriptor.label} session "${resumeId}": ${mountFailureText(reserved)} — ` +
                 'two processes driving one session would interleave its transcript. Close that terminal, or drop --resume to start a fresh session.');
         }
+        let session;
+        let initialHistory;
         try {
             session = await backend.open({ kind: 'resume', sessionId: resumeId }, host);
             try {
@@ -88,36 +122,48 @@ export async function openBackendStartup(ctx, backend, input) {
         reserved.reservation.settle();
         prefs.setLastSession(resumeId);
         prefs.touch(resumeId);
-    }
-    else {
-        session = await backend.open({ kind: 'create', cwd: input.cwd }, host);
-        const { reservation } = await reserveNewSession(formatSessionRef(session.ref));
-        reservation.settle();
-    }
+        return { session, initialHistory };
+    };
     return {
-        session,
+        // Boot and landing-page state use the target this backend actually opened.
+        resumedSessionId: resumeId,
         label: backend.descriptor.label,
         backendId: backend.id,
-        initialHistory,
         catalog: backend.catalog,
         sessionPrefs: prefs,
+        start,
         // A submitted user row means the backend has persisted a resumable transcript.
         persisted: (_sessionId, rows) => rows.some(row => row.kind === 'user'),
         resumeCommand: (sessionId) => launch.resumeCommand(sessionId),
         open: (target) => backend.open(target, target.kind === 'create' ? { ...host, cwd: target.cwd } : host),
     };
 }
-/** Probe optional backends lazily; failed loading leaves their row unavailable. */
+/** Resume failures abort boot; history is read before the channel's first paint. */
+export async function openBackendStartup(ctx, backend, input) {
+    const prepared = await prepareBackendStartup(ctx, backend, input);
+    return { ...prepared, ...await prepared.start() };
+}
+/**
+ * Probe every optional backend once (`dsh` is always available and has no
+ * loader). Loading goes through the registry, so a probed backend's pool hook is
+ * booked just like an opened one's — a backend that builds its pool in `detect()`
+ * (the contract does not forbid it) is then still closed at exit. Failures leave
+ * their row unavailable instead of failing the probe.
+ */
 export async function probeKernels(ctx, cwd) {
-    const host = await createBackendHost(ctx, cwd, () => undefined);
     const statuses = {};
-    for (const [id, load] of Object.entries(BACKEND_LOADERS)) {
+    for (const entry of listBackends()) {
+        if (entry.load === undefined)
+            continue;
+        // One host per entry: `dataDir` is backend-scoped, and a probe must not
+        // hand a backend a directory that is not its own.
+        const host = await createBackendHost(ctx, entry.id, cwd, () => undefined);
         try {
-            statuses[id] = await (await load()).detect(host);
+            statuses[entry.id] = await (await loadBackend(entry.id)).detect(host);
         }
         catch (error) {
             host.debug('dsh-tui: kernel probe failed (' + (error instanceof Error ? error.message : String(error)) + ')');
-            statuses[id] = { installed: false };
+            statuses[entry.id] = { installed: false };
         }
     }
     return statuses;

package/lib/types/dsh-adapter/channel/action-readiness.d.ts

@@ -14,6 +14,8 @@ export type ChannelActionMethods = Pick<ChannelState, ChannelActionMethodName>;
 export declare function createChannelActionMethods(getReadyActions: () => ChannelActionDelegates): ChannelActionMethods;
 export declare function createChannelActionReadiness(): {
     install(next: ChannelActionDelegates): void;
+    /** Replace the installed table (the adoption-window extension, core/compose.ts). */
+    reinstall(next: ChannelActionDelegates): void;
     getReadyActions(): ChannelActionDelegates;
 };
 /**