@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,161 @@
+/**
+ * Agent-presets roster integration (issue #8): compose each session's
+ * model-facing world (tools, prompt sections, projections) from one preset
+ * directory instead of the host composition.
+ *
+ * Mirrors the official host's integration (dsh-host-apiproxy's
+ * `composeAgent`): the preset id is resolved BEFORE create/resume because the
+ * session boundary snapshots `meta` (the durable header's `agentPreset`)
+ * before asynchronous setup begins; the mount itself runs inside the agent
+ * factory's `setup(agentCtx)` hook, where a composition failure rolls the
+ * whole creation back instead of publishing a half-configured agent.
+ *
+ * A deployment without the roster (bare `dsh --config cordis.yml` boots,
+ * older CLI without the shipped preset root) composes nothing: callers get
+ * no `setup` and every session shares the host composition — the behavior
+ * before presets existed.
+ */
+import { recordedModelRoute } from '../modelRoute.js';
+import { snapshotLiveSessionEvents } from './compat/liveSession.js';
+import { readPersistedSession } from './compat/persistence.js';
+import { resolveCompatiblePreset, resolveRecordedPreset, rosterOf, } from './preset-resolution.js';
+const ASK_USER_TOOL = 'ask_user_question';
+/**
+ * Resolve the preset one new/resumed session will run under and the setup
+ * that installs it. `requested` undefined adopts the roster default.
+ *
+ * Resolution failures (unknown/broken preset id, an empty roster that cannot
+ * supply even the default) degrade to the rosterless composition with a loud
+ * log line: a session that cannot start at all is worse than one running on
+ * the host composition.
+ *
+ * @param ctx - The plugin context (roster lookup + logging).
+ * @param requested - The preset id the caller wants, or undefined for the default.
+ * @returns The header value + setup hook, or an empty composition.
+ */
+export async function composePreset(ctx, requested) {
+    const presets = rosterOf(ctx);
+    if (presets === undefined)
+        return {};
+    let resolvedId;
+    try {
+        resolvedId = (await resolveCompatiblePreset(presets, requested)).id;
+    }
+    catch (error) {
+        ctx.logger.warn(`dsh-tui: agent preset ${requested === undefined ? '(default)' : `"${requested}"`} unavailable ` +
+            `(${error instanceof Error ? error.message : String(error)}) — composing the session without a preset`);
+        return {};
+    }
+    return {
+        agentPreset: resolvedId,
+        setup: async (agentCtx) => {
+            await presets.mount(agentCtx, resolvedId);
+        },
+    };
+}
+/**
+ * The preset a PERSISTED session actually runs, read from its log: the last
+ * `agent-preset/selected` event wins over the creation header (a blank
+ * session may have switched). undefined when the log records none (sessions
+ * from before presets existed → the roster default applies at mount).
+ *
+ * @param ctx - The plugin context (persistence lookup).
+ * @param sessionId - The persisted session to inspect.
+ * @returns The running preset id, or undefined when unrecorded/unreadable.
+ */
+export async function resolvePersistedPreset(ctx, sessionId) {
+    const persistence = ctx.get('sessionPersistence');
+    if (persistence === undefined)
+        return undefined;
+    try {
+        const { meta, events } = await readPersistedSession(persistence, sessionId);
+        return resolveRecordedPreset({ header: meta, events });
+    }
+    catch {
+        // A missing/corrupt artifact leaves resume itself to report the failure;
+        // the preset lookup must not mask it with a second, misleading error.
+        return undefined;
+    }
+}
+/**
+ * The preset a LIVE session runs, resolved from its own log (last
+ * `agent-preset/selected` wins over the header). Used for fork-style creates
+ * (rewind/model switch) and for reading an already-live agent's composition.
+ *
+ * @param session - The live session.
+ * @returns The running preset id, or undefined when the log records none.
+ */
+export function runningPresetOf(session) {
+    const header = session.header ?? {};
+    return resolveRecordedPreset({ header, events: snapshotLiveSessionEvents(session) });
+}
+/**
+ * The route a PERSISTED session actually ran, read from its log: the last
+ * `request/header` snapshot. undefined when the log records none (a session
+ * that never started a turn) or the artifact is unreadable.
+ *
+ * Resume feeds this back into `agents.resume({ agentOptions })` so the
+ * resumed agent's `options.model` is populated again — a cordis.yml that
+ * pins only `provider` (issue #67: a half-pin never merges) leaves
+ * agentOptions.model undefined, which breaks the `{{model}}` persona variable
+ * for the resumed agent's own assembly AND for every subagent it spawns
+ * (dsh-subagent's `resolveChildAgentOptions` inherits `parent.options.model`).
+ *
+ * @param ctx - The plugin context (persistence lookup).
+ * @param sessionId - The persisted session to inspect.
+ * @returns The recorded model route, or undefined when unrecorded/unreadable.
+ */
+export async function resolvePersistedRoute(ctx, sessionId) {
+    const persistence = ctx.get('sessionPersistence');
+    if (persistence === undefined)
+        return undefined;
+    try {
+        const { events } = await readPersistedSession(persistence, sessionId);
+        return recordedModelRoute(events);
+    }
+    catch {
+        // A missing/corrupt artifact leaves resume itself to report the failure;
+        // the route lookup must not mask it with a second, misleading error.
+        return undefined;
+    }
+}
+/**
+ * Keep the official Minimal preset's model-facing contract at exactly two
+ * tools. The TUI mounts ask_user_question at the host layer so every other
+ * preset (including user presets) can use its questionnaire UI; host-layer
+ * tools otherwise merge into Minimal's scoped catalog as a third tool.
+ *
+ * This is a per-assembly filter rather than a startup-time decision because
+ * one TUI process can resume, create, or recompose sessions under different
+ * presets. The session log remains the source of truth for the active preset.
+ *
+ * @param assembly - Fully assembled prompt inputs for one model request.
+ * @param presetId - Preset recorded for the requesting session.
+ * @returns The original assembly, except ask_user_question is absent in Minimal.
+ */
+export function filterMinimalPresetTools(assembly, presetId) {
+    if (presetId !== 'minimal' || !assembly.tools.some(tool => tool.name === ASK_USER_TOOL))
+        return assembly;
+    return {
+        ...assembly,
+        tools: assembly.tools.filter(tool => tool.name !== ASK_USER_TOOL),
+    };
+}
+/**
+ * Read a service the way a joined agent sees it: through the preset scope
+ * chain when a roster is mounted (preset realms hide e.g. `compaction` from
+ * the root context), falling back to the host context otherwise. Mirrors the
+ * official host's `agentPresets.serviceFor(agent, key) ?? ctx.get(key)`.
+ *
+ * @param ctx - The plugin context (roster + host fallback).
+ * @param agent - The live agent whose scope chain resolves first.
+ * @param key - The cordis service key.
+ * @returns The service instance, or undefined when neither layer provides it.
+ */
+export function serviceForAgent(ctx, agent, key) {
+    const presets = rosterOf(ctx);
+    const scoped = presets?.serviceFor?.(agent, key);
+    if (scoped !== undefined)
+        return scoped;
+    return ctx.get(key);
+}

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

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const PROMPT_DEBUG_FILENAME = ".dsh-prompt-debug.json";
+export declare function registerPromptDebug(ctx: Context): void;
+//# sourceMappingURL=promptDebug.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"promptDebug.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/promptDebug.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,eAAO,MAAM,qBAAqB,2BAA2B,CAAA;AAqG7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAiGtD"}

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

@@ -0,0 +1,163 @@
+/**
+ * On-demand capture of every final AgentLoop request context observed for a
+ * live session.
+ *
+ * The LLM waterfall is the last provider-neutral boundary before adapter
+ * dispatch. Capturing there records the fully assembled system prompt,
+ * messages, and tool schemas after prompt/tool plugins have contributed.
+ * @module dsh-cli/prompt-debug
+ */
+import { join, resolve } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { isAgentLoopRequest } from '@deepseek-ai/dsh-llm';
+import { snapshotLiveSessionEvents } from './compat/liveSession.js';
+import { t } from '../i18n.js';
+export const PROMPT_DEBUG_FILENAME = '.dsh-prompt-debug.json';
+function latestPosition(agent) {
+    const events = snapshotLiveSessionEvents(agent.session);
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === 'step/start')
+            return event.data;
+    }
+    return undefined;
+}
+function latestRequestHeaderReason(agent) {
+    const events = snapshotLiveSessionEvents(agent.session);
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === 'request/header')
+            return event.data.reason;
+    }
+    return undefined;
+}
+function turnCompleted(agent, turn) {
+    return snapshotLiveSessionEvents(agent.session).some(event => event.type === 'turn/end' && event.data.turn === turn);
+}
+function captureRequest(agent, options, requestIndex, position, attempt) {
+    const requestHeaderReason = latestRequestHeaderReason(agent);
+    return {
+        capturedAt: new Date().toISOString(),
+        requestIndex,
+        ...position,
+        attempt,
+        ...(requestHeaderReason === undefined ? {} : { requestHeaderReason }),
+        finalLlmContext: {
+            provider: options.provider,
+            model: options.model,
+            ...(options.reasoningEffort === undefined ? {} : { reasoningEffort: options.reasoningEffort }),
+            ...(options.system === undefined ? {} : { system: options.system }),
+            messages: options.messages,
+            ...(options.tools === undefined ? {} : { tools: options.tools }),
+            ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+            ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
+            ...(options.stop === undefined ? {} : { stop: options.stop }),
+        },
+    };
+}
+/**
+ * Register `/debug-prompt` and retain the final requests observed for each
+ * live session (most recent {@link DEBUG_PROMPT_MAX_REQUESTS} kept). The
+ * command writes one private, atomic snapshot into the receiving session's
+ * workspace; it never records credentials, transport headers, or
+ * AbortSignals.
+ */
+/** Retention cap per session: every capture holds the fully assembled
+ * request context (messages + tools), so an unbounded list grows
+ * quadratically with an uncompacted conversation — the dominant long-session
+ * memory term. Retries of the current step stay well inside this window. */
+const DEBUG_PROMPT_MAX_REQUESTS = 8;
+export function registerPromptDebug(ctx) {
+    const commands = ctx.get('commands');
+    const agents = ctx.get('agents');
+    if (commands === undefined || agents === undefined || ctx.get('llm') === undefined)
+        return;
+    const captureStartedAt = new Date().toISOString();
+    const captures = new Map();
+    ctx.on('llm/stream', (options, next) => {
+        if (!isAgentLoopRequest(options) || options.sessionId === undefined)
+            return next();
+        const agent = agents.get(options.sessionId);
+        if (agent === undefined)
+            return next();
+        const position = latestPosition(agent);
+        if (position === undefined)
+            return next();
+        const sessionId = String(options.sessionId);
+        const capture = captures.get(sessionId) ?? { requests: [] };
+        if (!captures.has(sessionId))
+            captures.set(sessionId, capture);
+        const previous = capture.requests.findLast(request => request.turn === position.turn && request.step === position.step);
+        const attempt = (previous?.attempt ?? 0) + 1;
+        capture.requests.push(captureRequest(agent, options, capture.requests.length + 1, position, attempt));
+        if (capture.requests.length > DEBUG_PROMPT_MAX_REQUESTS) {
+            capture.requests.splice(0, capture.requests.length - DEBUG_PROMPT_MAX_REQUESTS);
+        }
+        return next();
+    });
+    // Replaced agents are no longer addressable by `/debug-prompt`; release
+    // their potentially large message/tool snapshots with the agent lifecycle.
+    ctx.on('agent/disposed', ({ agent }) => {
+        captures.delete(String(agent.session.id));
+    });
+    ctx.effect(() => commands.register({
+        name: 'debug-prompt',
+        description: 'Write every observed final LLM request context for this session to the workspace root',
+        recordInput: false,
+        handler: async ({ agent, rawInput }) => {
+            if (rawInput.trim().length > 0) {
+                return { kind: 'error', text: 'Usage: /debug-prompt' };
+            }
+            const sessionId = String(agent.session.id);
+            const capture = captures.get(sessionId);
+            if (capture === undefined || capture.requests.length === 0) {
+                return {
+                    kind: 'error',
+                    text: 'No final LLM request is available for this session. Send one prompt, wait for it to finish, then run /debug-prompt.',
+                };
+            }
+            const latest = capture.requests.at(-1);
+            if (!turnCompleted(agent, latest.turn)) {
+                return { kind: 'error', text: 'The latest model turn is still running. Wait for it to finish, then run /debug-prompt.' };
+            }
+            const root = resolve(agent.session.header.cwd ?? process.cwd());
+            const output = join(root, PROMPT_DEBUG_FILENAME);
+            const turns = new Map();
+            for (const request of capture.requests) {
+                const turn = turns.get(request.turn) ?? { turn: request.turn, requests: [] };
+                if (!turns.has(request.turn))
+                    turns.set(request.turn, turn);
+                turn.requests.push(request);
+            }
+            const document = {
+                schemaVersion: 2,
+                generatedAt: new Date().toISOString(),
+                captureStartedAt,
+                captureScope: 'Requests observed by this dsh-tui process; requests from before a session resume cannot be reconstructed.',
+                warning: 'Sensitive debug data: contains system prompts, conversation messages, tool schemas, and tool results. It intentionally excludes credentials and transport headers.',
+                sessionId,
+                turnCount: turns.size,
+                requestCount: capture.requests.length,
+                turns: [...turns.values()].map(turn => ({
+                    ...turn,
+                    requestCount: turn.requests.length,
+                })),
+            };
+            try {
+                await writeFileAtomic(output, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+            }
+            catch (error) {
+                return {
+                    kind: 'error',
+                    text: `Could not write prompt debug file: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+            return {
+                kind: 'success',
+                // Localized copy carries the synced/shared-workspace cleanup reminder
+                // (the snapshot lands in the workspace root, 0600); see i18n.ts.
+                text: t('prompt-debug-saved', { count: capture.requests.length, file: output }),
+            };
+        },
+    }));
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Question-provider seat guard (issue #98 security follow-up).
+ *
+ * On the legacy/rc `registerProvider` API, the harness allows exactly ONE
+ * user-questions provider per context. The original fix made this TUI yield
+ * the seat silently on DUPLICATE_PROVIDER so profiles carrying
+ * @deepseek-ai/dsh-web-app keep booting — but silence cuts both ways: a
+ * malicious plugin that registers FIRST also gets silent ownership of the
+ * questionnaire and can answer the model's ask_user_question on the user's
+ * behalf.
+ *
+ * The upstream error carries no incumbent identity (fixed message + code
+ * only), and the public API offers no query — but the service stores the
+ * incumbent provider object on its `provider` property, which is reachable
+ * structurally. This module turns that probe into a whitelist decision with
+ * PROVENANCE: silent yields are reserved for host-verified identities (this
+ * module's private symbol tag — the true host-coexistence scenario), while a
+ * whitelist hit that the incumbent merely self-reported (name/hostId/id
+ * fields any plugin can copy) gets an honest "identity not host-verified"
+ * alert: forgeable silence is worse than a loud warning.
+ */
+/**
+ * Front doors allowed to hold the questionnaire seat without a notice.
+ * Third-party plugins must not be listed here: the seat decides who speaks
+ * FOR the user to the model.
+ */
+export declare const QUESTION_PROVIDER_HOST_WHITELIST: readonly string[];
+/**
+ * The incumbent provider's identity as probed off the service, plus whether
+ * that identity is host-verified. `verified: true` can only be minted by
+ * this module's private symbol tag; self-reported `name`/`hostId`/`id`
+ * fields are readable but forgeable by any plugin.
+ */
+export interface IncumbentQuestionProviderIdentity {
+    readonly id: string;
+    readonly verified: boolean;
+}
+/** What apply() should do after a DUPLICATE_PROVIDER registration attempt. */
+export interface QuestionProviderYieldDecision {
+    /**
+     * `silent` keeps the issue-#98 behavior (host-verified whitelist only);
+     * `alert` notifies the user; `alert-unverified` is the honest variant for
+     * a self-reported whitelist hit — the name matches a host front door but
+     * nothing proves who wrote it.
+     */
+    readonly action: 'silent' | 'alert' | 'alert-unverified';
+    /** The incumbent identity the decision was based on, when one was found. */
+    readonly incumbentId: string | undefined;
+}
+/**
+ * Decide how to react to an incumbent user-questions provider. Only a
+ * HOST-VERIFIED whitelisted incumbent (the symbol tag) keeps the silent
+ * yield: a self-reported `name: 'dsh-web-app'` is exactly what a seat
+ * squatter would write, so whitelist hits without verification get the
+ * unverified alert instead of silence. Third-party ids and no identity at
+ * all alert — the conservative default, because silence is exactly what an
+ * attacker squatting the seat wants.
+ */
+export declare function decideQuestionProviderYield(incumbent: IncumbentQuestionProviderIdentity | undefined): QuestionProviderYieldDecision;
+/** Tag a provider this TUI is about to register so a later boot (recompose
+ * leftover, restart race) can recognize itself in the seat. */
+export declare function tagTuiQuestionProvider(provider: object): void;
+/**
+ * Probe the user-questions service for the incumbent provider's identity.
+ *
+ * Recognition order:
+ *   1. this TUI's private symbol tag (unforgeable outside the module) —
+ *      reported as verified;
+ *   2. an explicit identity marker the incumbent attached (`name`, `hostId`,
+ *      `id`) — readable for the notice text but reported as unverified,
+ *      because those fields are trivially copyable by a squatter;
+ *   3. nothing — return undefined, which the decision maps to the alert path.
+ */
+export declare function incumbentQuestionProviderId(service: object): IncumbentQuestionProviderIdentity | undefined;
+//# sourceMappingURL=providerGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerGuard.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/providerGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAA+B,CAAA;AAE7F;;;;;GAKG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,kBAAkB,CAAA;IACxD,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,iCAAiC,GAAG,SAAS,GACvD,6BAA6B,CAM/B;AASD;+DAC+D;AAC/D,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAY7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,iCAAiC,GAAG,SAAS,CAoB1G"}

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

@@ -0,0 +1,104 @@
+/**
+ * Question-provider seat guard (issue #98 security follow-up).
+ *
+ * On the legacy/rc `registerProvider` API, the harness allows exactly ONE
+ * user-questions provider per context. The original fix made this TUI yield
+ * the seat silently on DUPLICATE_PROVIDER so profiles carrying
+ * @deepseek-ai/dsh-web-app keep booting — but silence cuts both ways: a
+ * malicious plugin that registers FIRST also gets silent ownership of the
+ * questionnaire and can answer the model's ask_user_question on the user's
+ * behalf.
+ *
+ * The upstream error carries no incumbent identity (fixed message + code
+ * only), and the public API offers no query — but the service stores the
+ * incumbent provider object on its `provider` property, which is reachable
+ * structurally. This module turns that probe into a whitelist decision with
+ * PROVENANCE: silent yields are reserved for host-verified identities (this
+ * module's private symbol tag — the true host-coexistence scenario), while a
+ * whitelist hit that the incumbent merely self-reported (name/hostId/id
+ * fields any plugin can copy) gets an honest "identity not host-verified"
+ * alert: forgeable silence is worse than a loud warning.
+ */
+/**
+ * Front doors allowed to hold the questionnaire seat without a notice.
+ * Third-party plugins must not be listed here: the seat decides who speaks
+ * FOR the user to the model.
+ */
+export const QUESTION_PROVIDER_HOST_WHITELIST = ['dsh-web-app', 'dsh-tui'];
+/**
+ * Decide how to react to an incumbent user-questions provider. Only a
+ * HOST-VERIFIED whitelisted incumbent (the symbol tag) keeps the silent
+ * yield: a self-reported `name: 'dsh-web-app'` is exactly what a seat
+ * squatter would write, so whitelist hits without verification get the
+ * unverified alert instead of silence. Third-party ids and no identity at
+ * all alert — the conservative default, because silence is exactly what an
+ * attacker squatting the seat wants.
+ */
+export function decideQuestionProviderYield(incumbent) {
+    if (incumbent === undefined)
+        return { action: 'alert', incumbentId: undefined };
+    const whitelisted = QUESTION_PROVIDER_HOST_WHITELIST.includes(incumbent.id);
+    if (incumbent.verified && whitelisted)
+        return { action: 'silent', incumbentId: incumbent.id };
+    if (whitelisted)
+        return { action: 'alert-unverified', incumbentId: incumbent.id };
+    return { action: 'alert', incumbentId: incumbent.id };
+}
+/**
+ * Module-private tag marking a provider object as this TUI's own. Symbol-keyed
+ * so a third party cannot forge the marker by copying visible fields onto its
+ * provider (the symbol never leaves this module).
+ */
+const TUI_PROVIDER_TAG = Symbol('dsh-tui question provider');
+/** Tag a provider this TUI is about to register so a later boot (recompose
+ * leftover, restart race) can recognize itself in the seat. */
+export function tagTuiQuestionProvider(provider) {
+    try {
+        Object.defineProperty(provider, TUI_PROVIDER_TAG, {
+            value: 'dsh-tui',
+            configurable: false,
+            writable: false,
+            enumerable: false,
+        });
+    }
+    catch {
+        // A frozen provider from an older TUI copy simply stays untagged — the
+        // decision then falls back to the conservative alert, never a crash.
+    }
+}
+/**
+ * Probe the user-questions service for the incumbent provider's identity.
+ *
+ * Recognition order:
+ *   1. this TUI's private symbol tag (unforgeable outside the module) —
+ *      reported as verified;
+ *   2. an explicit identity marker the incumbent attached (`name`, `hostId`,
+ *      `id`) — readable for the notice text but reported as unverified,
+ *      because those fields are trivially copyable by a squatter;
+ *   3. nothing — return undefined, which the decision maps to the alert path.
+ */
+export function incumbentQuestionProviderId(service) {
+    let provider;
+    try {
+        provider = service.provider;
+    }
+    catch {
+        return undefined;
+    }
+    if (provider === null || typeof provider !== 'object')
+        return undefined;
+    try {
+        if (provider[TUI_PROVIDER_TAG] === 'dsh-tui') {
+            return { id: 'dsh-tui', verified: true };
+        }
+        for (const key of ['name', 'hostId', 'id']) {
+            const value = provider[key];
+            if (typeof value === 'string' && value.trim() !== '')
+                return { id: value.trim(), verified: false };
+        }
+    }
+    catch {
+        // A getter that throws must not take the boot down with it.
+    }
+    return undefined;
+}

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

@@ -0,0 +1,42 @@
+import type { ProviderSetupHost } from '../adapter/ports/channel-settings.js';
+export type { ProviderSetupHost, CatalogProviderCandidate, ConfiguredProvider, ProfilePathOp, OAuthSetupHost, OAuthProviderStatus, OAuthLoginResult } from '../adapter/ports/channel-settings.js';
+import { type AskUserQuestionAnswer, type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+/** Route id rule shared with the dsh configuration surface (web Models page). */
+export declare const PROVIDER_ROUTE_ID: RegExp;
+/** Wire protocols dsh-llm-pi-ai can serve on a manually declared route. */
+export declare const PROVIDER_PROTOCOLS: readonly ["openai-completions", "openai-responses", "anthropic-messages"];
+/**
+ * Derive the credential ref for a route, matching the official web UI
+ * convention so TUI- and web-added providers resolve the same key.
+ */
+export declare function deriveKeyRef(route: string): string;
+export interface ProviderWizardDeps {
+    readonly host: ProviderSetupHost;
+    readonly ask: (request: AskUserQuestionRequest, options?: {
+        redact?: boolean;
+    }) => Promise<AskUserQuestionAnswer>;
+    readonly notify: (text: string, options?: {
+        color?: 'error' | 'warning' | 'success';
+        timeoutMs?: number;
+    }) => void;
+    readonly pushLocal: (title: string, lines: readonly string[]) => void;
+    /** Live turn state; the model-switch question is skipped while working. */
+    readonly working: () => boolean;
+    readonly switchModel: (provider: string, model: string) => Promise<boolean>;
+}
+export type ProviderWizardOutcome = 'added' | 'updated' | 'deleted' | 'signed-out' | 'cancelled' | 'failed';
+/**
+ * Run the provider wizard. Opens with an action choice (add / edit); the
+ * add path runs the guided config flow, and edit picks a configured route
+ * then opens a menu of targeted edits (API key, base URL, wire protocol,
+ * model list, delete this provider) with the route locked. Each menu item
+ * applies immediately and exits — no confirmation between picking an edit
+ * and writing it — and patches only the picked field, leaving every other
+ * stored setting (including fields the wizard does not model) in place.
+ * For built-in (catalog) routes the menu is limited to API
+ * key, model list, and delete; base URL and wire protocol are only
+ * meaningful for custom endpoints. Resolves 'cancelled' when the user
+ * dismisses any question (Esc) — nothing has been written at that point.
+ */
+export declare function runProviderWizard(deps: ProviderWizardDeps): Promise<ProviderWizardOutcome>;
+//# sourceMappingURL=providerWizard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerWizard.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/providerWizard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAsH,MAAM,sCAAsC,CAAA;AACjM,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAA;AAsBjM,OAAO,EAEL,KAAK,qBAAqB,EAE1B,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAA;AAGxC,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,QAAoC,CAAA;AAElE,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,2EAIrB,CAAA;AAEV;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,CACZ,OAAO,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAC3B,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,CACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KACtE,IAAI,CAAA;IACT,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IACrE,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5E;AAED,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAA;AA4D3G;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,qBAAqB,CAAC,CA8BhC"}