@deepseek-harness-tui/dsh-tui 0.8.6 → 0.8.7

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

@@ -7,7 +7,7 @@ import { SessionId } from '@deepseek-ai/dsh-session';
 import { renderContextSections, renderPrompt } from '@deepseek-ai/dsh-system-prompt';
 import { loadBaselineInstructions } from '@deepseek-ai/dsh-agent-instructions';
 import { extname, isAbsolute, join } from 'node:path';
-import { completeCommands, isLocalCommandName, LOCAL_COMMANDS, parseCommandName } from '../commands.js';
+import { completeCommands, HIDDEN_COMMAND_NAMES, isLocalCommandName, LOCAL_COMMANDS, parseCommandName } from '../commands.js';
 import { clearResumeTarget, forgetSession, readResumeTarget, touchSession, writeResumeTarget } from '../sessionHistory.js';
 import { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, sessionsRoots } from './compat/index.js';
 import { listSummaries, locateSession, noteBranch, previewSession, } from './sessions/index.js';
@@ -25,8 +25,10 @@ import { extractMentions } from '../utils/mentions.js';
 import { t } from '../i18n.js';
 import { modeDisplayName, resolveSessionModes } from '../sessionModes.js';
 import { normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
+import { SubagentActivityStore } from './subagents.js';
 import { ActivityTracker } from 'dsh-working-activity/status';
 import { featureOn } from 'dsh-working-activity/config';
+import { setMinimalMode } from '../minimalMode.js';
 import { readActivityConfig } from '../activityPrefs.js';
 import { attachSessionToWorkspace } from './workspace.js';
 import { createLocalWorkspaceRuntime, getHostWorkspaceRuntime } from './workspaces.js';
@@ -40,6 +42,7 @@ import { installDecisionGuard } from './decision-guard.js';
 import { commandOwner } from './command-attribution.js';
 import { readGrantStore } from './grants.js';
 import { hasCommandErrorCode, mapCommandError } from './command-errors.js';
+import { installedLineOf } from './contract.js';
 import { pluginsInfoLines } from './plugins-info.js';
 import { cleanRenderText, cleanScalarText } from './sanitize.js';
 /** `tui/input` return normalization: transform/handled/cancel or no opinion.
@@ -136,6 +139,20 @@ function normalizeRewindDoneSummary(result, warn) {
  * observation (a provider whose directory watcher is still warming).
  */
 const SKILL_COMMAND_RETRY_MS = 800;
+/** Names the subagent delegation tools ship under (preset `toolName` values
+ *  plus the CLI default); each renders as a live subagent card, never a plain
+ *  tool card. */
+const SUBAGENT_TOOL_NAMES = new Set([
+    'task',
+    'subagent',
+    'subagent_fork',
+    'subagent_claude_code',
+    'subagent_codex',
+    'spawn_task',
+]);
+function isSubagentToolName(name) {
+    return SUBAGENT_TOOL_NAMES.has(name.toLowerCase());
+}
 const ARGS_PREVIEW_LIMIT = 160;
 const RESULT_PREVIEW_LIMIT = 240;
 /** Local `!`-command output cap (mirrors the result preview limit). */
@@ -405,6 +422,26 @@ async function waitForTurnEnd(session, fromSeq, timeoutMs) {
 export function createChannel(ctx, initialAgent, options) {
     let agent = initialAgent;
     let currentHandle = options.handle;
+    const subagentControl = {
+        interrupt(agentId) {
+            const child = subagentStore.get(agentId);
+            const target = child?.sessionId ?? agentId;
+            const runtime = ctx.subagents;
+            if (!runtime?.interrupt || !target)
+                return false;
+            try {
+                runtime.interrupt(target, { kind: 'ancestor', agent });
+                subagentStore.onCancelled(agentId, 'interrupted');
+                state.subagents = subagentStore.snapshot();
+                syncSubagentRows();
+                state.emit();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
     // D-7 backstop: the extensions row installs the decision-subscription
     // gate, but the channel IS the dispatch path — a stale patch without that
     // row (or a bare embed mounting neither) would otherwise leave tui/input
@@ -418,6 +455,55 @@ export function createChannel(ctx, initialAgent, options) {
     const fallbackGrantStore = readGrantStore();
     const currentGrantStore = () => ctx.get('tuiPluginHost')?.grants ?? fallbackGrantStore;
     installDecisionGuard(ctx, currentGrantStore());
+    // Subagent activity tracking: collects agent/subagent/*, session/event for
+    // subagents, and exposes live snapshots for the UI.
+    const subagentStore = new SubagentActivityStore();
+    // Subagent ChatRow tracking: maps agentId to its ChatRow for live updates.
+    const subagentRowsByAgentId = new Map();
+    // Task tool descriptions, queued in call order; each subagent/start consumes
+    // the oldest one so the card shows the user-visible task label.
+    const pendingTaskDescriptions = [];
+    /**
+     * Sync subagentStore state into ChatRows (insert/update in state.rows).
+     * Called whenever subagent state changes (spawned/completed/failed/output).
+     */
+    const syncSubagentRows = () => {
+        const snapshot = subagentStore.snapshot();
+        for (const sub of snapshot) {
+            let row = subagentRowsByAgentId.get(sub.agentId);
+            if (!row) {
+                // New subagent: insert a new ChatRow after the last user or assistant message
+                row = {
+                    id: nextRowId++,
+                    kind: 'subagent',
+                    text: sub.description,
+                    subagent: undefined, // will be filled below
+                };
+                subagentRowsByAgentId.set(sub.agentId, row);
+                state.rows.push(row);
+            }
+            const subagentRow = {
+                agentId: sub.agentId,
+                runId: sub.runId,
+                description: sub.description,
+                provider: sub.provider,
+                model: sub.model || 'default',
+                effort: sub.effort,
+                status: sub.status,
+                startedAt: sub.startedAt,
+                completedAt: sub.completedAt,
+                durationMs: sub.completedAt ? sub.completedAt - sub.startedAt : Date.now() - sub.startedAt,
+                outputLines: sub.output.slice(-3),
+                toolCalls: sub.toolCalls,
+                tokens: sub.tokens,
+                summary: sub.summary,
+                stopReason: sub.stopReason,
+                error: sub.error,
+            };
+            row.subagent = subagentRow;
+            row.text = sub.description;
+        }
+    };
     // The DSH slash-command registry (optional service): /plan, /goal and
     // friends register here; the TUI merges their descriptors into the slash
     // menu and dispatches through `execute` (which logs the paired
@@ -686,6 +772,12 @@ export function createChannel(ctx, initialAgent, options) {
     /** Monotonic token: only the latest `interruptAndDeliver` re-queues, so a
      *  second interrupt while the abort settles cannot double-deliver. */
     let interruptSeq = 0;
+    // Cancellation is asynchronous: a fast second Esc can arrive after the
+    // driver has accepted the first abort but before its turn/end event lands.
+    // Do not cancel the same driver twice, or the second cancel can swallow the
+    // replacement work queued by interruptAndDeliver and leave the UI gated on
+    // a working flag that has not observed turn/end yet.
+    let cancelInFlight = false;
     /** The llm runtime seam (dsh-llm LlmRuntime): route metadata resolution. */
     const llmRuntime = ctx.get('llm');
     /** Mutable per-agent model selection (dsh-agent's routing override seam).
@@ -818,6 +910,16 @@ export function createChannel(ctx, initialAgent, options) {
         applyEffort(found);
         return true;
     };
+    /** Whether the installed command service takes composer images: rc line
+     *  gate with a structural fallback, so a failed manifest probe (bundlers,
+     *  exotic loaders) still lands on the 4-param rc.8 shape at runtime. */
+    const commandServiceSupportsImages = (service) => {
+        const line = installedLineOf('@deepseek-ai/dsh-commands');
+        if (line !== undefined)
+            return line >= 8;
+        return typeof service.execute?.length === 'number'
+            && service.execute.length >= 4;
+    };
     /** Run one DSH registry command (`/plan`, …) on the live agent; the text
      *  of its result, '' when the result is textless, undefined when the
      *  command is not registered, and the error message when it throws. */
@@ -864,7 +966,22 @@ export function createChannel(ctx, initialAgent, options) {
             return t('command-invoke-denied-owner', { name, owner: owner.componentId });
         }
         try {
-            const execution = await commandService.execute(agent, `/${name}${rawInput}`, new AbortController().signal);
+            const signal = new AbortController().signal;
+            const line = `/${name}${rawInput}`;
+            const images = await registryCommandImages(commandService, definition, line, signal);
+            // rc.8 moved the signal to the 4th parameter and added composer
+            // images; older lines (rc.7/rc.6) take (agent, line, signal).
+            const execution = images === undefined
+                ? await commandService.execute(agent, line, signal)
+                : await commandService.execute(agent, line, images.images, signal);
+            if (images !== undefined && images.dropped.length > 0) {
+                // Loud-drop policy mirrors the submit pipeline (mentions-missing):
+                // a referenced image that never reached the command must be visible.
+                state.notify(t('mentions-missing', { paths: images.dropped.join(' ') }), {
+                    color: 'warning',
+                    timeoutMs: 4000,
+                });
+            }
             // `undefined` = not registered; a handler error surfaces as its
             // message so the user sees why the command failed.
             return execution?.result.text ?? '';
@@ -873,6 +990,51 @@ export function createChannel(ctx, initialAgent, options) {
             return error instanceof Error ? error.message : String(error);
         }
     };
+    /** Encode the staged `@`-mention images the user pasted for THIS command
+     *  line into rc.8's `EncodedImageAttachment` payloads; undefined = the
+     *  installed dsh-commands line predates composer images (rc.7/rc.6), so
+     *  the caller uses the legacy 3-arg invoke. Matches the submit pipeline's
+     *  token rule (expandMentions): a staged image attaches only when the
+     *  line references its token. A command that does not declare
+     *  `input.images` gets NO images — rc.8 admission settles such a batch
+     *  as an error, and upstream sends images only to image-capable commands.
+     *  A failing read drops just that image (reported via the returned
+     *  tokens) while the command still runs. */
+    const registryCommandImages = async (service, definition, line, signal) => {
+        if (!commandServiceSupportsImages(service))
+            return undefined;
+        const declaresImages = definition?.input?.images === true;
+        if (!declaresImages || stagedImages.size === 0)
+            return { images: [], dropped: [] };
+        const store = mentionAttachments(ctx);
+        if (typeof store?.readImage !== 'function')
+            return { images: [], dropped: [] };
+        const images = [];
+        const dropped = [];
+        for (const [token, attachment] of stagedImages) {
+            if (!line.includes(token))
+                continue;
+            try {
+                const stored = await store.readImage(attachment, signal);
+                if (stored?.data instanceof Uint8Array && stored.data.byteLength > 0) {
+                    images.push({
+                        mediaType: attachment.mediaType,
+                        data: Buffer.from(stored.data).toString('base64'),
+                        name: attachment.name,
+                    });
+                }
+                else {
+                    dropped.push(token);
+                }
+            }
+            catch {
+                // One unreadable staged image is dropped — same loud policy as the
+                // submit pipeline's mentions-missing warning (deliverUserText).
+                dropped.push(token);
+            }
+        }
+        return { images, dropped };
+    };
     // Session-mode folds: last-wins projections over the session log. The
     // event types are registered by dsh-plan-mode / dsh-sandbox-policy /
     // dsh-user-approval and are NOT in this package's typed SessionEvent
@@ -1001,6 +1163,8 @@ export function createChannel(ctx, initialAgent, options) {
         thinkingFold: options.thinkingFold ?? 'preview',
         toolBackground: normalizeToolBackground(options.toolBackground),
         statusBar: normalizeStatusBar(options.statusBar),
+        whale: options.whale !== false,
+        minimal: options.minimal === true,
         activityEnabled: options.activity !== false,
         contextBarEnabled: options.contextBar !== false,
         agentPreset: options.agentPreset,
@@ -1042,6 +1206,8 @@ export function createChannel(ctx, initialAgent, options) {
             thinking: 0,
             tools: 0,
         },
+        subagents: [],
+        subagentControl,
         subscribe(listener) {
             listeners.add(listener);
             return () => {
@@ -1165,6 +1331,11 @@ export function createChannel(ctx, initialAgent, options) {
         cancel() {
             // Keep the staged queue: an interrupt aborts the running turn but the
             // queued/steered messages are delivered as the next turn (web parity).
+            // Cancellation converges asynchronously; ignore a repeated Esc/Ctrl+C
+            // until the aborted turn has produced its terminal event.
+            if (cancelInFlight)
+                return;
+            cancelInFlight = true;
             agent.cancel({ kind: 'user' }, { keepInbox: true });
         },
         interruptAndDeliver(texts) {
@@ -1176,8 +1347,13 @@ export function createChannel(ctx, initialAgent, options) {
             // followup. dsh-agent's cancel-convergence wake latch accepts this
             // wake immediately after cancel and starts it once the aborted turn
             // retires; waiting for whenIdle is unsafe because it also follows
-            // replacement work and may never settle.
-            agent.cancel({ kind: 'user' });
+            // replacement work and may never settle. If cancellation is already
+            // in flight, keep the existing abort and still replace the pending
+            // interrupt delivery; fake/embedded agents may not emit turn/end.
+            if (!cancelInFlight) {
+                cancelInFlight = true;
+                agent.cancel({ kind: 'user' });
+            }
             const token = ++interruptSeq;
             const deliver = () => {
                 // A second interrupt while the abort is still settling must not
@@ -1985,6 +2161,19 @@ export function createChannel(ctx, initialAgent, options) {
             state.statusBar = next;
             state.emit();
         },
+        setWhale(visible) {
+            if (visible === state.whale)
+                return;
+            state.whale = visible;
+            state.emit();
+        },
+        setMinimal(enabled) {
+            setMinimalMode(enabled);
+            if (enabled === state.minimal)
+                return;
+            state.minimal = enabled;
+            state.emit();
+        },
         setActivityFrames(name) {
             if (!isPresetName(name)) {
                 state.notify(t('unknown-activity-preset', { name }), { color: 'error' });
@@ -2098,13 +2287,15 @@ export function createChannel(ctx, initialAgent, options) {
             // snapshot() over list(): only a COMPLETE observation is authoritative
             // (same contract as the skill-command merge above) — a partial catalog
             // must surface as "failed", not as a misleading near-empty picker.
-            const registry = skillRegistryFor(agent);
+            const target = agent;
+            const registry = skillRegistryFor(target);
             if (registry === undefined)
                 return [];
             try {
-                const observation = await registry.snapshot(skillViewOptions(agent));
-                if (!observation.complete)
+                const observation = await registry.snapshot(skillViewOptions(target));
+                if (target !== agent || !observation.complete) {
                     return undefined;
+                }
                 return observation.skills.map(skill => ({
                     name: skill.name,
                     description: skill.description,
@@ -2717,6 +2908,10 @@ export function createChannel(ctx, initialAgent, options) {
         const merged = [...LOCAL_COMMANDS];
         if (commandService) {
             for (const descriptor of commandService.list(target)) {
+                // Hidden TUI commands (e.g. /deepseek) stay out of the public
+                // command catalog even if a plugin/skill happens to share the name.
+                if (HIDDEN_COMMAND_NAMES.has(descriptor.name))
+                    continue;
                 if (merged.some(command => command.name === descriptor.name))
                     continue;
                 const descriptions = commandTrees?.descriptions(descriptor.name);
@@ -3559,6 +3754,22 @@ ${output}
                 // no card is a no-op below.
                 if (event.data.name === 'ask_user_question')
                     break;
+                // The Task tool's plain card is replaced by the live subagent card
+                // (Kimi Code semantics): the delegation itself renders as a subagent
+                // row, so the raw args/result card would only duplicate it. The call
+                // still runs - only its transcript rendering is suppressed.
+                if (isSubagentToolName(event.data.name)) {
+                    try {
+                        const args = JSON.parse(event.data.arguments);
+                        if (typeof args.description === 'string' && args.description)
+                            pendingTaskDescriptions.push(args.description);
+                    }
+                    catch {
+                        // Unparseable args leave the queue untouched; the card falls back
+                        // to the provider label.
+                    }
+                    break;
+                }
                 // Reasoning that led to a tool call is done thinking — fold the
                 // preview now, before the tool card grows the transcript past it
                 // (see foldLiveReasoning).
@@ -3629,6 +3840,7 @@ ${output}
                 break;
             }
             case 'turn/start': {
+                cancelInFlight = false;
                 state.working = true;
                 state.turnStart = Date.now();
                 state.responseChars = 0;
@@ -3644,6 +3856,7 @@ ${output}
                 break;
             }
             case 'turn/end': {
+                cancelInFlight = false;
                 settleStreaming();
                 state.working = false;
                 state.activeToolCount = 0;
@@ -3910,6 +4123,19 @@ ${output}
                 };
             })(),
             ctx.on('session/event', (session, event) => {
+                // First check if this is a subagent session
+                const subagentId = subagentStore.getSubagentIdBySession(session);
+                if (subagentId) {
+                    subagentStore.onSessionEvent(subagentId, event);
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    if (event.type === 'assistant/chunk')
+                        state.emitStream();
+                    else
+                        state.emit();
+                    return;
+                }
+                // Otherwise handle main agent session
                 if (session !== agent.session)
                     return;
                 // Observation broker (C-042): maps user/message + assistant/message
@@ -3940,6 +4166,67 @@ ${output}
                 else
                     state.emit();
             }),
+            // Subagent lifecycle tracking. The dsh-subagent service publishes scoped
+            // observe-only events as `subagent/start` and `subagent/end`; the parent
+            // Agent is carried by Cordis scope dispatch, not included in the payload.
+            (() => {
+                const disposeStart = ctx.on('subagent/start', (info) => {
+                    if (!info?.id)
+                        return;
+                    subagentStore.onSpawned(info.id, info.provider || 'subagent', info.provider, {
+                        runId: info.runId ?? info.id,
+                        local: info.local,
+                        description: pendingTaskDescriptions.shift() ?? `${info.provider || 'subagent'} task`,
+                    });
+                    // In-process providers publish a child Agent during this notification.
+                    // Resolve through ctx.get('agents') (the property proxy is
+                    // topology-sensitive); the child carries its session (live output
+                    // stream) and its provider/model route for the card header.
+                    try {
+                        const agents = ctx.get('agents');
+                        const child = agents?.get(info.id);
+                        if (child?.session) {
+                            subagentStore.linkSession(info.id, child.session);
+                            const model = child.options?.model ?? child.options?.provider;
+                            if (model)
+                                subagentStore.patch(info.id, { model, provider: child.options?.provider ?? info.provider });
+                        }
+                    }
+                    catch {
+                        // Session discovery is best-effort and must not break the parent turn.
+                    }
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    state.emit();
+                });
+                const disposeEnd = ctx.on('subagent/end', (info) => {
+                    if (!info?.id)
+                        return;
+                    const output = Array.isArray(info.lastAssistantMessage)
+                        ? info.lastAssistantMessage
+                            .map(block => typeof block === 'object' && block !== null && 'text' in block ? String(block.text ?? '') : '')
+                            .filter(Boolean)
+                            .join('\n')
+                        : '';
+                    // The final assistant output becomes the card's summary only; the
+                    // running waterfall came from the child session stream, so echoing
+                    // it into the output buffer would duplicate it on the collapsed card.
+                    subagentStore.flushOutput(info.id);
+                    if (info.stopReason === 'completed')
+                        subagentStore.onCompleted(info.id, output, info.stopReason);
+                    else if (info.stopReason === 'cancelled' || info.stopReason === 'aborted')
+                        subagentStore.onCancelled(info.id, info.stopReason, output);
+                    else
+                        subagentStore.onFailed(info.id, info.stopReason || 'Unknown error');
+                    state.subagents = subagentStore.snapshot();
+                    syncSubagentRows();
+                    state.emit();
+                });
+                return () => {
+                    disposeStart();
+                    disposeEnd();
+                };
+            })(),
         ];
     };
     // Subagents inherit provider/model from AgentOptions, but resumed TUI

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

@@ -1,20 +1,43 @@
-export declare const UPSTREAM_VALIDATED_VERSION = "0.1.0-rc.7";
+/** Primary validated upstream line (newest). */
+export declare const UPSTREAM_VALIDATED_VERSION = "0.1.0-rc.8";
+/** Every upstream rc line the adapter has been validated against.
+ *
+ * rc.8 = primary; rc.7 = previous line (full CI coverage); rc.6 = legacy
+ * line (install- and type-level compatibility, feature surface may lack
+ * rc.7/rc.8 additions — new features must degrade gracefully there).
+ * The peer range in package.json is deliberately wider than this list: an
+ * install on an older line is allowed but reports drift at boot.
+ */
+export declare const UPSTREAM_VALIDATED_RC_LINES: readonly [6, 7, 8];
 /**
  * Framework packages version on their own lines; the contract validates
  * their MAJOR (breaking surface), not the harness rc number.
  */
 export declare const UPSTREAM_FRAMEWORK_MAJORS: Record<string, number>;
 /** Official packages the adapter consumes at runtime or as types. */
-export declare const UPSTREAM_BLESSED_PACKAGES: readonly ["@deepseek-ai/cordis", "@deepseek-ai/schemastery", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-agent-presets", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-cordis-host-runner", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-persona", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-storage", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-workspace", "@deepseek-ai/dsh-system-prompt", "@deepseek-ai/dsh-terminal", "@deepseek-ai/dsh-terminal-bash", "@deepseek-ai/dsh-tool-ask-user", "@deepseek-ai/dsh-tool-bash-persistent", "@deepseek-ai/dsh-tool-cordis", "@deepseek-ai/dsh-user-approval", "@deepseek-ai/dsh-user-questions"];
+export declare const UPSTREAM_BLESSED_PACKAGES: readonly ["@deepseek-ai/cordis", "@deepseek-ai/schemastery", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-agent-presets", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-cordis-host-runner", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-persona", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-storage", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-workspace", "@deepseek-ai/dsh-system-prompt", "@deepseek-ai/dsh-terminal", "@deepseek-ai/dsh-terminal-bash", "@deepseek-ai/dsh-tool-ask-user", "@deepseek-ai/dsh-tool-bash-persistent", "@deepseek-ai/dsh-tool-cordis", "@deepseek-ai/dsh-user-approval", "@deepseek-ai/dsh-user-questions"];
 export interface UpstreamDriftEntry {
     package: string;
     installed: string | undefined;
     validated: string;
 }
+/** Human-readable summary of the validated lines, e.g. `0.1.0-rc.8 (rc.6/rc.7/rc.8)`. */
+export declare const UPSTREAM_VALIDATED_LABEL: string;
 export declare function installedUpstreamVersions(): Record<string, string | undefined>;
+/** The installed upstream rc line of one blessed package (undefined when
+ *  missing or not on the 0.1.0-rc line). Feature gates compare this against
+ *  the line a behavior was introduced on, so the adapter degrades on older
+ *  installs instead of calling APIs they do not have. */
+export declare function installedLineOf(packageName: string): number | undefined;
+/** The distinct upstream rc lines installed across the blessed harness
+ *  packages (framework packages excluded). One line = coherent install;
+ *  several = a mixed tree, which the per-package drift check cannot see.
+ *  Empty when nothing (or no harness package) is installed. */
+export declare function installedUpstreamLines(): number[];
 /**
- * Report every blessed package whose installed version is NOT the validated
- * release line. Empty array = the running install matches the contract.
+ * Report every blessed package whose installed version is NOT one of the
+ * validated release lines. Empty array = the running install matches the
+ * contract.
  */
 export declare function upstreamDrift(): UpstreamDriftEntry[];
 //# sourceMappingURL=contract.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,8xBA0B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAWD,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAgB9E;AAOD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,EAAE,CAsBpD"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAgBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,oBAAqB,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,2zBA2B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,yFAAyF;AACzF,eAAO,MAAM,wBAAwB,QAAmG,CAAA;AAYxI,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;yDAGyD;AACzD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAOD;;;+DAG+D;AAC/D,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAQjD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,EAAE,CAuBpD"}

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

@@ -1,9 +1,11 @@
 /**
  * Upstream compatibility contract.
  *
- * The TUI is validated against one upstream release line (0.1.0-rc.7).
- * Every official package this adapter touches is blessed here; anything
- * else must go through upstream channels or the adapter, never the UI.
+ * The TUI is validated against a set of upstream release lines — the
+ * current primary (0.1.0-rc.8) plus older lines kept in backward
+ * compatibility (0.1.0-rc.7, 0.1.0-rc.6). Every official package this
+ * adapter touches is blessed here; anything else must go through upstream
+ * channels or the adapter, never the UI.
  *
  * `upstreamDrift()` powers both the boot-time warning (dev visibility) and
  * the CI gate (scripts/verify-upstream-contract.ts) so a mismatched
@@ -11,7 +13,17 @@
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-export const UPSTREAM_VALIDATED_VERSION = '0.1.0-rc.7';
+/** Primary validated upstream line (newest). */
+export const UPSTREAM_VALIDATED_VERSION = '0.1.0-rc.8';
+/** Every upstream rc line the adapter has been validated against.
+ *
+ * rc.8 = primary; rc.7 = previous line (full CI coverage); rc.6 = legacy
+ * line (install- and type-level compatibility, feature surface may lack
+ * rc.7/rc.8 additions — new features must degrade gracefully there).
+ * The peer range in package.json is deliberately wider than this list: an
+ * install on an older line is allowed but reports drift at boot.
+ */
+export const UPSTREAM_VALIDATED_RC_LINES = [6, 7, 8];
 /**
  * Framework packages version on their own lines; the contract validates
  * their MAJOR (breaking surface), not the harness rc number.
@@ -34,6 +46,7 @@ export const UPSTREAM_BLESSED_PACKAGES = [
     '@deepseek-ai/dsh-llm',
     '@deepseek-ai/dsh-persona',
     '@deepseek-ai/dsh-session',
+    '@deepseek-ai/dsh-settings',
     '@deepseek-ai/dsh-skill',
     '@deepseek-ai/dsh-storage',
     '@deepseek-ai/dsh-storage-domain',
@@ -48,6 +61,8 @@ export const UPSTREAM_BLESSED_PACKAGES = [
     '@deepseek-ai/dsh-user-approval',
     '@deepseek-ai/dsh-user-questions',
 ];
+/** Human-readable summary of the validated lines, e.g. `0.1.0-rc.8 (rc.6/rc.7/rc.8)`. */
+export const UPSTREAM_VALIDATED_LABEL = `${UPSTREAM_VALIDATED_VERSION} (${UPSTREAM_VALIDATED_RC_LINES.map((n) => `rc.${n}`).join('/')})`;
 function resolvePackageJson(packageName) {
     try {
         const path = import.meta.resolve(`${packageName}/package.json`);
@@ -57,7 +72,13 @@ function resolvePackageJson(packageName) {
         return undefined;
     }
 }
+let cachedVersions;
 export function installedUpstreamVersions() {
+    // Package manifests do not change mid-process; memoize so per-call gates
+    // (e.g. the command-images line check) stay cheap. Frozen so callers can
+    // never corrupt the shared cache.
+    if (cachedVersions !== undefined)
+        return cachedVersions;
     const result = {};
     for (const packageName of UPSTREAM_BLESSED_PACKAGES) {
         let version;
@@ -73,15 +94,39 @@ export function installedUpstreamVersions() {
         }
         result[packageName] = version;
     }
-    return result;
+    cachedVersions = Object.freeze(result);
+    return cachedVersions;
+}
+/** The installed upstream rc line of one blessed package (undefined when
+ *  missing or not on the 0.1.0-rc line). Feature gates compare this against
+ *  the line a behavior was introduced on, so the adapter degrades on older
+ *  installs instead of calling APIs they do not have. */
+export function installedLineOf(packageName) {
+    return rcNumber(installedUpstreamVersions()[packageName]);
 }
 function rcNumber(version) {
-    const match = /0\.1\.0-rc\.(\d+)/u.exec(version ?? '');
+    const match = /^0\.1\.0-rc\.(\d+)$/u.exec(version ?? '');
     return match === null ? undefined : Number(match[1]);
 }
+/** The distinct upstream rc lines installed across the blessed harness
+ *  packages (framework packages excluded). One line = coherent install;
+ *  several = a mixed tree, which the per-package drift check cannot see.
+ *  Empty when nothing (or no harness package) is installed. */
+export function installedUpstreamLines() {
+    const lines = new Set();
+    for (const packageName of UPSTREAM_BLESSED_PACKAGES) {
+        if (UPSTREAM_FRAMEWORK_MAJORS[packageName] !== undefined)
+            continue;
+        const line = rcNumber(installedUpstreamVersions()[packageName]);
+        if (line !== undefined)
+            lines.add(line);
+    }
+    return [...lines].sort((a, b) => a - b);
+}
 /**
- * Report every blessed package whose installed version is NOT the validated
- * release line. Empty array = the running install matches the contract.
+ * Report every blessed package whose installed version is NOT one of the
+ * validated release lines. Empty array = the running install matches the
+ * contract.
  */
 export function upstreamDrift() {
     const drift = [];
@@ -96,13 +141,14 @@ export function upstreamDrift() {
             matches = installedMajor === frameworkMajor;
         }
         else {
-            matches = rcNumber(installed) === rcNumber(UPSTREAM_VALIDATED_VERSION);
+            const installedLine = rcNumber(installed);
+            matches = installedLine !== undefined && UPSTREAM_VALIDATED_RC_LINES.includes(installedLine);
         }
         if (!matches) {
             drift.push({
                 package: packageName,
                 installed,
-                validated: frameworkMajor !== undefined ? `major ${frameworkMajor}` : UPSTREAM_VALIDATED_VERSION,
+                validated: frameworkMajor !== undefined ? `major ${frameworkMajor}` : UPSTREAM_VALIDATED_LABEL,
             });
         }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAsB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAErG,eAAO,MAAM,IAAI,YAAY,CAAA;AAU7B,eAAO,MAAM,MAAM,UAAa,CAAA;AAEhC;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;yEAKqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;gDAC4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;gFAE4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;oCACgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;sBAIkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;4BAGwB;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;wDAEoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;kFAC8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;gCAG4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;6DAEyD;IACzD,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;IACzC;;8EAE0E;IAC1E,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;IACjC,sEAAsE;IACtE,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC;;;yDAGqD;IACrD,KAAK,CAAC,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CA8ChC,CAAA;AAEF;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAsB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAErG,eAAO,MAAM,IAAI,YAAY,CAAA;AAU7B,eAAO,MAAM,MAAM,UAAa,CAAA;AAEhC;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;yEAKqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;gDAC4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;gFAE4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;oCACgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;sBAIkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;4BAGwB;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;wDAEoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;kFAC8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;gCAG4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;6DAEyD;IACzD,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;IACzC;;8EAE0E;IAC1E,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;IACjC,sEAAsE;IACtE,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC;;;yDAGqD;IACrD,KAAK,CAAC,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CA8ChC,CAAA;AAEF;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBvE"}