@deepseek-harness-tui/dsh-tui 0.14.1 → 0.16.0

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

@@ -22,6 +22,7 @@
 import { compositionRoot } from './host-access.js';
 import { assertCapabilityShadowPolicy, defaultAdapterRuntime, } from '../adapter/kernel/runtime.js';
 import { snapshotLiveSessionEvents } from './compat/liveSession.js';
+import { getLang } from '../i18n.js';
 import { DEFAULT_PERMISSION_OPTIONS, } from '../channel/permissions.js';
 const approvalStores = new WeakMap();
 /** Host-only registration used by the TUI plugin bootstrap. */
@@ -35,6 +36,26 @@ export function getApprovalStore(ctx) {
     return approvalStores.get(root);
 }
 const COMMAND_CLIP = 500;
+/**
+ * The ask's reason in the UI language. Requests may carry a localized
+ * `displayReason: { en, zh }` next to the English audit `reason` (DSH's
+ * auto-review asks do); older request types lack the field, so it is read
+ * structurally.
+ * @param req - The pending approval request.
+ * @returns The localized reason, else `req.reason`.
+ */
+function reasonOf(req) {
+    const display = req.displayReason;
+    if (display !== null && typeof display === 'object') {
+        const byLang = display;
+        for (const lang of [getLang(), 'en']) {
+            const text = byLang[lang];
+            if (typeof text === 'string' && text.trim() !== '')
+                return text;
+        }
+    }
+    return req.reason;
+}
 /**
  * Recover the gated command from the session log: the approval request
  * links to an already-presented tool call via `callId`, so the arguments
@@ -135,6 +156,9 @@ export class ApprovalStore {
      * have flipped — re-checks below this guard are skipped.
      */
     externalCheckedAtEvents = -1;
+    /** UI language the parked asks' reasons were resolved in (see
+     *  {@link refreshReasonLang}). */
+    reasonLang = getLang();
     notifyQueued = false;
     /**
      * CallIds whose approval ask already settled (decided or cancelled).
@@ -172,6 +196,7 @@ export class ApprovalStore {
      * @returns The cached snapshot; the reference is stable between mutations.
      */
     getSnapshot() {
+        this.refreshReasonLang();
         this.refreshActiveExternal();
         return this.snapshotCache;
     }
@@ -200,6 +225,7 @@ export class ApprovalStore {
      *   when the agent has no parked ask.
      */
     pendingAgentDetail(agentId) {
+        this.refreshReasonLang();
         for (const ask of [...(this.active === undefined ? [] : [this.active]), ...this.queue]) {
             if (ask.snapshot.agentId !== agentId)
                 continue;
@@ -223,6 +249,23 @@ export class ApprovalStore {
             this.emit();
         });
     }
+    /** Re-resolve every parked ask's localized reason after a `/lang` switch;
+     *  Chat re-renders on the switch, so the read below lands on the new
+     *  language without a store subscription. */
+    refreshReasonLang() {
+        const lang = getLang();
+        if (lang === this.reasonLang)
+            return;
+        this.reasonLang = lang;
+        for (const pending of [...(this.active === undefined ? [] : [this.active]), ...this.queue]) {
+            const reason = reasonOf(pending.request);
+            if (reason === undefined)
+                delete pending.snapshot.reason;
+            else
+                pending.snapshot.reason = reason;
+        }
+        this.rebuildSnapshot();
+    }
     /** Rebuild the cached snapshot after any mutation of active. */
     rebuildSnapshot() {
         const pending = this.active;
@@ -322,6 +365,7 @@ export class ApprovalStore {
         assertCapabilityShadowPolicy('host.presentation.approve', this.runtime.mode, this.runtime.slices);
         return new Promise(resolve => {
             const command = commandOf(req);
+            const reason = reasonOf(req);
             // Source badge: park() is reached through the approval/request
             // waterfall, which any in-process plugin can dispatch — the agent-id
             // gate in plugin.ts says whose SESSION it names, not that a live tool
@@ -342,7 +386,7 @@ export class ApprovalStore {
                 snapshot: {
                     agentId: String(req.agent.id),
                     toolName: req.toolName,
-                    ...(req.reason !== undefined ? { reason: req.reason } : {}),
+                    ...(reason !== undefined ? { reason } : {}),
                     ...(command !== undefined ? { command } : {}),
                     ...(external ? { external: true } : {}),
                 },

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;AAM1F,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;4BA+K1B,YAAY,KAAG,SAAS,UAAU,EAAE;4BA0JpC,oBAAoB,KAAG,SAAS,UAAU,EAAE;8BAmB1C,SAAS,YAAY,EAAE,KAAG,SAAS,UAAU,EAAE;iBAW9D,IAAI;4BA7TS,MAAM,WAAW,MAAM,KAAG,YAAY,GAAG,SAAS;8BAYhD,MAAM,WAAW,MAAM,QAAQ,YAAY,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAG,cAAc,GAAG,SAAS;EAyTjI;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

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

@@ -4,6 +4,8 @@ import { BACKGROUND_START_ACK, isSubagentToolName, parseJobOutputId, todoPanelIt
 import { harnessToolResultView, prepareReplayEvents, toolErrorText } from '../channel/transcript.js';
 import { isCompactionCheckpointSource, toolResultPayload } from '../compat/messages.js';
 import { transcriptImagesOf } from '../transcript-images.js';
+import { isTeamToolName, TEAM_SPAWN_TOOL, teamMessageOf, teamToolCallView, teamToolResultView } from '../team-tools.js';
+import { teamMailboxAsRelay, withoutTeammateReminder } from '../compat/agent-team-0.2.0.js';
 /**
  * DeepSeek's rate windows, injected into the shared projector as its
  * `pricingWindow`: each usage buckets by the time its request ran.
@@ -148,6 +150,8 @@ export function createDshTranslator(deps) {
     /** Frame revisions are monotone within one attached Agent lifecycle; a
      *  re-delivered or out-of-order frame is dropped here. */
     let lastStreamRevision = -1;
+    /** Whether this session's first human prompt has been translated. */
+    let promptSeen = false;
     /**
      * Open calls by callId until their result: what the result's presenter,
      * images and task feeds need. `card: false` = question-presented (the
@@ -156,6 +160,35 @@ export function createDshTranslator(deps) {
      * projector's own card index: deleted on result, cleared on reset.
      */
     const openCalls = new Map();
+    /**
+     * `spawn_teammate` calls that have not written their member yet. The team
+     * refuses a teammate (name taken or invalid, member limit, not the Lead,
+     * service disposing, cancelled) before it appends `team/member`: no roster
+     * row carries that error, so a failed result brings back the plain card.
+     * Once the member is written its failure shows on the roster, and the call
+     * leaves this map. Bounded like `openCalls`.
+     */
+    const unwrittenSpawns = new Map();
+    /** A `team/member` write settles the pending spawn of that name. Two
+     *  parallel spawns of one name cannot be told apart; the first one goes. */
+    const onTeamMember = (data) => {
+        const name = data?.member?.name;
+        if (typeof name !== 'string')
+            return;
+        for (const [callId, call] of unwrittenSpawns) {
+            let args;
+            try {
+                args = JSON.parse(call.argsJson);
+            }
+            catch {
+                continue;
+            }
+            if (args?.name === name) {
+                unwrittenSpawns.delete(callId);
+                return;
+            }
+        }
+    };
     /** Ask the producing tool how its call should render (diff/terminal/…).
      *  Unknown tool, unparseable args, or a throwing presenter all degrade to
      *  the plain text card. */
@@ -163,7 +196,7 @@ export function createDshTranslator(deps) {
         try {
             const tool = deps.tools()?.get(name, deps.scope());
             if (tool?.presentCall === undefined)
-                return undefined;
+                return teamToolCallView(name, rawArgs);
             return tool.presentCall(JSON.parse(rawArgs));
         }
         catch {
@@ -182,8 +215,13 @@ export function createDshTranslator(deps) {
             if (local !== undefined)
                 return local;
             const tool = deps.tools()?.get(name, deps.scope());
-            if (tool?.presentResult === undefined)
-                return undefined;
+            if (tool?.presentResult === undefined) {
+                // Only the team tools read the text: skip joining every other result.
+                if (!isTeamToolName(name))
+                    return undefined;
+                const text = toolResultPayload(data.message).content.map(item => (item.type === 'text' ? item.text : '')).join('').trim();
+                return teamToolResultView(name, rawArgs, text);
+            }
             return tool.presentResult(JSON.parse(rawArgs), {
                 ...toolResultPayload(data.message),
                 ...(data.meta !== undefined ? { meta: data.meta } : {}),
@@ -194,7 +232,8 @@ export function createDshTranslator(deps) {
         }
     };
     const translateUserMessage = (event) => {
-        const data = event.data;
+        // compat(dsh 0.2.0, log): a 0.2.0 mailbox delivery reads as the relay it became.
+        const data = teamMailboxAsRelay(event.data);
         const base = { id: data.id, anchor: String(event.seq), seq: event.seq, time: event.time, blocks: data.content };
         // Both legacy and V4 checkpoints render as a folded summary rather than
         // disappearing with the other injected context.
@@ -217,16 +256,28 @@ 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) }];
+        }
+        // An Agent Teams peer message: a bubble labelled with its sender.
+        const team = teamMessageOf(data.source, data.content);
+        if (team !== undefined) {
+            return [{ type: 'user.message', ...base, blocks: team.blocks, source: 'team-message', sender: team.sender, text: team.text }];
+        }
         // Injected context (plugin/skill source) is model-facing only; it has no
         // transcript-facing text.
         if (data.source.kind !== 'user')
             return [{ type: 'user.message', ...base, source: 'injected', text: '' }];
+        // compat(dsh 0.2.0, log): a 0.2.0 teammate's first prompt drops its identity block.
+        const content = promptSeen ? data.content : withoutTeammateReminder(data).content;
+        promptSeen = true;
         return [{
                 type: 'user.message',
                 ...base,
+                blocks: content,
                 source: 'user',
-                text: firstTextOf(data.content),
-                images: transcriptImagesOf(data.content, deps.attachments),
+                text: firstTextOf(content),
+                images: transcriptImagesOf(content, deps.attachments),
             }];
     };
     const translateToolResult = (event) => {
@@ -234,6 +285,8 @@ export function createDshTranslator(deps) {
         const callId = data.message.source.callId;
         const call = openCalls.get(callId);
         openCalls.delete(callId);
+        const spawn = unwrittenSpawns.get(callId);
+        unwrittenSpawns.delete(callId);
         const payload = toolResultPayload(data.message);
         const isError = data.error !== undefined || payload.isError;
         // Text/presentation/images are derived only for results something
@@ -250,11 +303,13 @@ export function createDshTranslator(deps) {
             time: event.time,
             content: payload.content,
             text,
-            ...(isError && call !== undefined ? { errorText: toolErrorText(event) } : {}),
+            ...(isError && (call !== undefined || spawn !== undefined) ? { errorText: toolErrorText(event) } : {}),
             ...(card === undefined ? {} : { images: transcriptImagesOf(data.message.content, deps.attachments) }),
             ...(data.meta === undefined ? {} : { meta: data.meta }),
             ...(card === undefined || isError ? {} : { presentation: presentResultView(card.name, card.args, data) }),
         };
+        if (spawn !== undefined && isError)
+            return [{ ...spawn, presentation: presentCallView(spawn.name, spawn.argsJson) }, result];
         if (card === undefined || isError)
             return [result];
         const events = [result];
@@ -325,8 +380,11 @@ export function createDshTranslator(deps) {
                     return [{ ...base, presentation: QUESTION }];
                 }
                 // The delegation tools render as the live subagent card.
-                if (isSubagentToolName(data.name))
+                if (isSubagentToolName(data.name)) {
+                    if (data.name === TEAM_SPAWN_TOOL)
+                        unwrittenSpawns.set(callId, base);
                     return [{ ...base, presentation: SUBAGENT }];
+                }
                 openCalls.set(callId, { name: data.name, args: data.arguments, card: true });
                 return [{ ...base, presentation: presentCallView(data.name, data.arguments) }];
             }
@@ -371,6 +429,8 @@ export function createDshTranslator(deps) {
                 break;
         }
         const data = event.data;
+        if (type === 'team/member')
+            onTeamMember(data);
         switch (type) {
             case 'assistant/chunk': {
                 // Pre-0.1.5 live streams and raw pre-V3 logs carry per-token chunks
@@ -451,6 +511,7 @@ export function createDshTranslator(deps) {
      */
     const translateReplay = (events) => {
         lastStreamRevision = -1;
+        promptSeen = false;
         const out = [];
         for (const event of prepareReplayEvents(events)) {
             for (const translated of translateEvent(event))
@@ -461,7 +522,9 @@ export function createDshTranslator(deps) {
     /** Forget the frame fence and every open call (paired with a projector reset). */
     const reset = () => {
         lastStreamRevision = -1;
+        promptSeen = false;
         openCalls.clear();
+        unwrittenSpawns.clear();
     };
     return { translateEvent, translateFrame, translateReplay, reset, presentCallView, presentResultView };
 }

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-assembly.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** One bundle whose `Backend` declaration did not become a registry entry. */
+export interface BackendAssemblyRefusal {
+    readonly bundle: string;
+    readonly reason: string;
+}
+/** What one assembly pass did. Returned rather than only logged, so the
+ *  regression can assert the pass without reading the logs. */
+export interface BackendAssembly {
+    /** The profile manifest the pass read, when this boot has one. */
+    readonly profile: string | undefined;
+    /** Bundle layers the pass looked at (composition-owned packages excluded). */
+    readonly scanned: readonly string[];
+    /** Backend ids registered by this pass, in scan order. The built-in seed is
+     *  registered before it and is not part of the report. */
+    readonly registered: readonly string[];
+    /** Bundles that announced a backend this host could not assemble. */
+    readonly refused: readonly BackendAssemblyRefusal[];
+}
+/**
+ * Register every backend an installed bundle declares.
+ *
+ * Synchronous by contract (see the module comment): the caller runs this before
+ * the boot parses a backend choice. A second pass over the same composition is a
+ * no-op for the entries the first pass registered (see {@link assemblyStateOf}) —
+ * two callers exist on purpose: the entry decides which kernel to boot *before*
+ * `apply` runs, and both questions ("is this bundle a layer" for the route, "which
+ * backend is this id" for the session) are answered by the same registry.
+ */
+export declare function assembleBackendsFromProfile(ctx: Context): BackendAssembly;
+//# sourceMappingURL=backend-assembly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend-assembly.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/backend-assembly.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;+DAC+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC;8DAC0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CA2CzE"}

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

@@ -0,0 +1,225 @@
+/**
+ * The assembly point (Stage D-1 / roadmap §4.7): the `Backend` declarations of the
+ * bundles a profile composes become registry entries, so that installing a
+ * third-party backend bundle and restarting puts that backend in the kernel
+ * picker.
+ *
+ * Three properties decide the shape of this file.
+ *
+ *  - **Discovery precedes parsing, synchronously.** The boot parses a backend
+ *    choice through the registry (`parseBackendChoice`, membership is the second
+ *    half of the parse — P0 D1), and an id that is not registered yet reads as an
+ *    unknown value: dsh plus a warning, never the backend the user installed.
+ *    Nothing that waits for a fiber to activate can satisfy that: a third-party
+ *    bundle's rows are composed *after* this row (the profile's own bundles come
+ *    before `cordis.patch.yml`), so an event or timer would fire after the parse.
+ *    The discovery therefore reads **files** — the profile's own manifest — and
+ *    registers before anything is parsed. The import of the backend module stays
+ *    lazy (an installed backend nobody selects is never imported, D4).
+ *
+ *  - **One reading of "what is installed".** `/plugin install` and the CLI both
+ *    record an installed bundle in the profile manifest's `dsh.profile.bundles`
+ *    (the manager's own `reconcile()` writes it), and the profile manifest is what
+ *    the Loader composes. So the scan reads that file, not the plugin-manager
+ *    service: the service's `listBundles()` is asynchronous, and a service answer
+ *    would arrive after the parse. The predicate is the same one
+ *    `./plugin-manager.ts`'s `extraBundles()` uses — the composition's own packages
+ *    are not plugins a person installed — so the list and the assembly cannot
+ *    disagree about whom they are talking about.
+ *
+ *  - **Judgement, never a guess.** A bundle's declaration is read only through the
+ *    identity rule #1568 established: the entry is resolved by the Loader's own ESM
+ *    resolver and the `dsh-plugin.json` counts only beside the `package.json` that
+ *    establishes that entry's package root. A Loader without Node internals cannot
+ *    answer that question, and this module then refuses to answer it too, saying
+ *    so, instead of falling back to a second path resolver of its own.
+ *
+ * A refusal is contained, never silent and never fatal: notes 0009 requires a
+ * failure to be attributable to the entry it belongs to, without taking the rest
+ * of the composition down. Registration errors therefore become one warning line
+ * naming the bundle and the reason (the registry's own checks stay as loud as they
+ * are — this catches them one level out), and every other bundle is still
+ * assembled.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { logForDebugging } from '../utils/debug.js';
+import { findManifest, loadThroughLoader, compositionLoader, resolveEntryUrl } from './admission-loader.js';
+import { backendManifestOf } from './backend-contribution.js';
+import { registerBackend } from './backend-registry.js';
+import { declaredBackendsIn, isCompositionOwned } from './plugin-declaration.js';
+/**
+ * Register every backend an installed bundle declares.
+ *
+ * Synchronous by contract (see the module comment): the caller runs this before
+ * the boot parses a backend choice. A second pass over the same composition is a
+ * no-op for the entries the first pass registered (see {@link assemblyStateOf}) —
+ * two callers exist on purpose: the entry decides which kernel to boot *before*
+ * `apply` runs, and both questions ("is this bundle a layer" for the route, "which
+ * backend is this id" for the session) are answered by the same registry.
+ */
+export function assembleBackendsFromProfile(ctx) {
+    const profile = profileManifestPathOf(ctx);
+    const refused = [];
+    const registered = [];
+    const done = (scanned) => ({ profile, scanned, registered, refused });
+    if (profile === undefined) {
+        logForDebugging('dsh-tui: backend assembly skipped — this composition has no profile directory to read (no baseUrl)');
+        return done([]);
+    }
+    const bundles = installedBundlesOf(profile);
+    if (bundles === undefined)
+        return done([]);
+    const scanned = bundles.filter(name => !isCompositionOwned(name));
+    if (scanned.length === 0)
+        return done(scanned);
+    const baseUrl = ctx.baseUrl;
+    const loader = compositionLoader(ctx);
+    if (loader?.internal === undefined) {
+        // The Loader runs plugins through plain `import()` when it has no Node
+        // internals, but that path resolves relative to *this* module: an answer
+        // computed here would name a module the Loader never executes. Refuse.
+        logForDebugging(`dsh-tui: backend assembly skipped — the Loader ESM resolver is unavailable, so the entry of `
+            + `${scanned.length} installed bundle(s) cannot be established: ${scanned.join(', ')}`);
+        return done(scanned);
+    }
+    const state = assemblyStateOf(ctx);
+    for (const bundle of scanned) {
+        for (const refusal of assembleBundle(bundle, loader, baseUrl, registered, state.owners))
+            refused.push(refusal);
+    }
+    if (registered.length > 0) {
+        logForDebugging(`dsh-tui: registered ${registered.length} backend(s) from installed bundles: ${registered.join(', ')}`);
+    }
+    for (const refusal of refused) {
+        // Attributable and loud for the person who installed it — a backend that
+        // silently never appears is the one outcome nobody can debug. Said once per
+        // composition: the second pass (the entry assembles, `apply` assembles again)
+        // reports the same refusals and must not repeat them to the reader.
+        const said = `${refusal.bundle}\u0000${refusal.reason}`;
+        if (state.warned.has(said))
+            continue;
+        state.warned.add(said);
+        ctx.logger.warn(`dsh-tui: bundle "${refusal.bundle}" declares a backend that was not registered: ${refusal.reason}`);
+    }
+    return done(scanned);
+}
+const assemblyStateOf = (ctx) => {
+    const existing = assembled.get(ctx);
+    if (existing !== undefined)
+        return existing;
+    const fresh = { owners: new Map(), warned: new Set() };
+    assembled.set(ctx, fresh);
+    return fresh;
+};
+const assembled = new WeakMap();
+/** One bundle's declarations → registry entries. Returns the refusals it owns. */
+function assembleBundle(bundle, loader, baseUrl, registered, owned) {
+    const refuse = (reason) => [{ bundle, reason }];
+    const url = resolveEntryUrl(loader, bundle, baseUrl);
+    if (url === undefined) {
+        return refuse('its entry module could not be resolved through the Loader resolver');
+    }
+    let entryFile;
+    try {
+        entryFile = fileURLToPath(url);
+    }
+    catch {
+        return refuse(`its entry resolved to ${url}, which is not a file`);
+    }
+    const manifestPath = findManifest(entryFile);
+    // No package-root declaration: this bundle is not a TUI plugin at all, which
+    // is the normal case and not a problem to report.
+    if (manifestPath === undefined)
+        return [];
+    let source;
+    try {
+        source = readFileSync(manifestPath, 'utf8');
+    }
+    catch (error) {
+        return refuse(`its declaration at ${manifestPath} could not be read (${messageOf(error)})`);
+    }
+    const { backends, problems } = declaredBackendsIn(source);
+    const refusals = problems.map(problem => ({ bundle, reason: problem }));
+    if (backends.length === 0 && problems.length === 0)
+        return [];
+    // The public declaration has no export selector: all entries would load the
+    // same `backend` object, which can carry only one session/data-directory id.
+    if (backends.length > 1)
+        return [...refusals, { bundle, reason: 'only one Backend per bundle can bind the fixed backend export' }];
+    for (const declared of backends) {
+        // A second pass over the same composition (the entry assembles before the
+        // route and `apply` assembles again) must be a no-op, not a storm of
+        // "already registered". An id this very bundle registered is the same entry;
+        // an id another bundle claimed is a conflict, and the registry answers it.
+        if (owned.get(declared.spec.id) === bundle)
+            continue;
+        let manifest;
+        try {
+            manifest = backendManifestOf(declared.spec);
+        }
+        catch (error) {
+            refusals.push({ bundle, reason: `its Backend declaration could not be projected (${messageOf(error)})` });
+            continue;
+        }
+        try {
+            // `load` is the module namespace, resolved once here and imported only if
+            // this backend is ever selected. The registry reads `backendExport`
+            // (default `backend`) and `unloadExport` out of that namespace, exactly as
+            // it does for the built-in index.
+            registerBackend({ manifest, load: () => loadThroughLoader(loader, bundle, url, baseUrl) });
+            registered.push(manifest.id);
+            owned.set(manifest.id, bundle);
+        }
+        catch (error) {
+            refusals.push({ bundle, reason: messageOf(error) });
+        }
+    }
+    return refusals;
+}
+/**
+ * The profile manifest this boot reads and composes: the `package.json` of the
+ * directory the Loader resolves module specifiers against (`Context.baseUrl`, set
+ * by the host to the profile directory — every row's context inherits it). No
+ * `baseUrl` means no profile (a bare Cordis root, a `--config` overlay, a source
+ * checkout), and then no bundle was installed into anything either.
+ */
+function profileManifestPathOf(ctx) {
+    const baseUrl = ctx.baseUrl;
+    if (typeof baseUrl !== 'string' || baseUrl === '')
+        return undefined;
+    try {
+        const url = new URL(baseUrl);
+        if (url.protocol !== 'file:')
+            return undefined;
+        return join(fileURLToPath(url), 'package.json');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The bundle layers this profile composes: `dsh.profile.bundles` in its manifest,
+ * which is what `/plugin install`, `enable` and the CLI all write (the manager's
+ * `reconcile()` appends every newly installed bundle that declares `dsh.bundle`;
+ * a disabled one leaves the list without being uninstalled). `undefined` when the
+ * file cannot be read or parsed — a broken profile is not an empty one.
+ */
+function installedBundlesOf(profile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(profile, 'utf8'));
+    }
+    catch (error) {
+        logForDebugging(`dsh-tui: backend assembly skipped — ${profile} could not be read (${messageOf(error)})`);
+        return undefined;
+    }
+    const declared = parsed?.dsh?.profile?.bundles;
+    if (!Array.isArray(declared))
+        return [];
+    return declared.filter((name) => typeof name === 'string' && name !== '');
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}