@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,257 @@
+import { t } from '../../i18n.js';
+import { isReservedCredentialRef } from '../credentialRefGuard.js';
+import { settingsValue } from '../compat/settings.js';
+export function createSettingsHosts(ctx, assertActive = () => undefined) {
+    let settingsHostResolved = false;
+    let settingsHostCache;
+    return {
+        settingsHost() {
+            if (settingsHostResolved)
+                return settingsHostCache;
+            settingsHostResolved = true;
+            // The `/settings` screen's runtime surface, over the same dsh-base
+            // seams the `/provider` wizard uses: settings (namespace descriptors +
+            // revision-fenced mutate) and credentials (secret writes). Structurally
+            // typed like the other optional seams in this file.
+            const settings = ctx.get('settings');
+            const credentials = ctx.get('credentials');
+            if (!settings)
+                return undefined;
+            settingsHostCache = {
+                listNamespaces() {
+                    // redactSecrets: the screen never renders a secret literal — secret
+                    // fields are write-only controls over the credentials seam.
+                    return settings.describe({ redactSecrets: true }).map(descriptor => ({
+                        ns: descriptor.ns,
+                        revision: descriptor.revision,
+                        applies: descriptor.applies,
+                        value: descriptor.value,
+                        user: descriptor.user,
+                    }));
+                },
+                write(ns, ops, expectedRevision) {
+                    return settings.mutate(ns, ops, expectedRevision);
+                },
+                async credentialConfigured(ref) {
+                    // The environment shadows the store (providerSetup.envShadows), so
+                    // an env-provided key counts as configured.
+                    if (process.env[ref] !== undefined)
+                        return true;
+                    return credentials !== undefined && (await credentials.resolve(ref)) !== undefined;
+                },
+                async writeCredential(ref, value) {
+                    if (!credentials)
+                        throw new Error('credentials service unavailable');
+                    // Second layer of the secret-ref reservation guard: the
+                    // registration layer already rejects plugin sections with
+                    // host-owned refs, but this seam must not trust it — a stale
+                    // section (registered before the guard) or a direct call must not
+                    // reach the shared credentials. The host's own main-credential
+                    // writes go through providerSetup().writeCredential instead.
+                    if (isReservedCredentialRef(ref))
+                        throw new Error(t('settings-secret-ref-reserved', { ref }));
+                    await credentials.set(ref, value);
+                },
+            };
+            return settingsHostCache;
+        },
+        providerSetup() {
+            // The `/provider` wizard's runtime surface, over the dsh-base seams:
+            // settings (profile persistence), credentials (key storage) and the
+            // llm runtime's configurable-provider directory + model discovery.
+            // Structurally typed like the other optional seams in this file.
+            const llm = ctx.get('llm');
+            const settings = ctx.get('settings');
+            const credentials = ctx.get('credentials');
+            // Without dsh-llm-pi-ai there is no adapter watching the settings
+            // section, so a written profile would never activate a route. The
+            // adapter registers its `llm-pi-ai` settings namespace at mount, which
+            // is the rc.6-observable mount signal (the newer
+            // `listModelDiscoveryNamespaces()` does not exist in rc.6).
+            if (!llm || !settings || !credentials
+                || !settings.describe().some(descriptor => descriptor.ns === 'llm-pi-ai')) {
+                return undefined;
+            }
+            const revision = () => settings.describe().find(descriptor => descriptor.ns === 'llm-pi-ai')?.revision;
+            // The OAuth sign-in surface (dsh-auth-style plugin), structural and
+            // optional: mounting the plugin lights up the wizard's OAuth branch,
+            // and without it the wizard is exactly what it was before.
+            const oauthApi = ctx.get('dshAuth')?.api;
+            // Real catalog membership on this mount: routes the adapter knows from
+            // its installed catalog (`declared !== true`). A stored profile naming
+            // such a route is an activation/override of the catalog route — even
+            // when it carries an explicit `api` field — while routes the adapter
+            // only knows because a profile names them are custom. Classifying by
+            // anything less (a profile-shape guess) misroutes the edit semantics.
+            const catalogMembers = () => new Set(llm.listConfigurableProviders()
+                .filter(entry => entry.settingsNs === 'llm-pi-ai' && entry.declared !== true)
+                .map(entry => entry.provider));
+            return {
+                ...(oauthApi === undefined ? {} : { oauth: oauthApi }),
+                listCatalogProviders() {
+                    // declared === true marks routes the adapter knows only because a
+                    // stored profile names them (user-added); the rest are activatable
+                    // catalog routes.
+                    return llm.listConfigurableProviders()
+                        .filter(entry => entry.settingsNs === 'llm-pi-ai' && entry.declared !== true)
+                        .map(entry => ({ provider: entry.provider, displayName: entry.displayName }));
+                },
+                routeExists(route) {
+                    const section = settingsValue(settings, 'llm-pi-ai');
+                    return section?.providers !== undefined && route in section.providers;
+                },
+                listRefUsers(ref, exceptRoute) {
+                    // The RESOLVED merge (settings.get), not the user layer: a base
+                    // provider or composition-base route naming this ref is invisible
+                    // to listConfiguredProviders() but still consumes the credential.
+                    const section = settingsValue(settings, 'llm-pi-ai');
+                    const providers = section?.providers;
+                    if (providers === undefined || typeof providers !== 'object' || providers === null)
+                        return [];
+                    return Object.entries(providers).flatMap(([route, profile]) => {
+                        if (route === exceptRoute)
+                            return [];
+                        if (typeof profile !== 'object' || profile === null)
+                            return [];
+                        const stored = profile;
+                        return stored.apiKeyEnv === ref ? [route] : [];
+                    });
+                },
+                listConfiguredProviders() {
+                    // The editable/deletable set is the USER layer only: `describe()`'s
+                    // `user` is the raw user section — the same source the /settings
+                    // screen treats as overrides. `settings.get()` is the resolved
+                    // merge; listing a route inherited from a composition base would
+                    // promise a delete that cannot land (the unset only clears the
+                    // user layer, so the base value re-inherits) while the credential
+                    // is really gone. When the running base exposes no `user` layer,
+                    // fall back to the resolved section: such builds (the official
+                    // dsh-base) carry zero base routes anyway, so the layers coincide.
+                    const descriptor = settings.describe().find(row => row.ns === 'llm-pi-ai');
+                    // Only an absent `user` (older base) falls back; a present-but-empty
+                    // user layer legitimately exposes nothing to edit.
+                    const section = (descriptor?.user !== undefined
+                        ? descriptor.user
+                        : settingsValue(settings, 'llm-pi-ai'));
+                    const providers = section?.providers;
+                    if (providers === undefined || typeof providers !== 'object' || providers === null)
+                        return [];
+                    const catalog = catalogMembers();
+                    return Object.entries(providers).flatMap(([route, profile]) => {
+                        // The settings section is user-editable, so a `providers.<route>`
+                        // entry may be null or a scalar; skip anything that is not a plain
+                        // object instead of dereferencing it and throwing (which would
+                        // block the edit/delete menu for every route).
+                        if (typeof profile !== 'object' || profile === null)
+                            return [];
+                        const stored = profile;
+                        const ref = typeof stored.apiKeyEnv === 'string' ? stored.apiKeyEnv : '';
+                        const baseURL = typeof stored.baseURL === 'string' && stored.baseURL !== ''
+                            ? stored.baseURL
+                            : undefined;
+                        const api = typeof stored.api === 'string' && stored.api !== ''
+                            ? stored.api
+                            : undefined;
+                        // Keep the raw model entries: a model-list re-selection must
+                        // rewrite kept ids with their stored objects, so per-model fields
+                        // this wizard never learned about survive the edit.
+                        const modelEntries = Array.isArray(stored.models)
+                            ? stored.models.filter((model) => typeof model === 'object' && model !== null)
+                            : undefined;
+                        const models = modelEntries?.flatMap(entry => typeof entry.id === 'string' ? [entry.id] : []);
+                        return [{
+                                route,
+                                ref,
+                                isCatalog: catalog.has(route),
+                                shadowed: ref !== '' && process.env[ref] !== undefined,
+                                ...(baseURL !== undefined ? { baseURL } : {}),
+                                ...(api !== undefined ? { api } : {}),
+                                ...(models !== undefined ? { models } : {}),
+                                ...(modelEntries !== undefined && modelEntries.length > 0
+                                    ? { modelEntries }
+                                    : {}),
+                            }];
+                    });
+                },
+                discoverModels(request) {
+                    return llm.discoverModels('llm-pi-ai', request);
+                },
+                envShadows(ref) {
+                    return process.env[ref] !== undefined;
+                },
+                envValue(ref) {
+                    return process.env[ref];
+                },
+                async readCredential(ref) {
+                    const resolved = await credentials.resolve(ref);
+                    return resolved?.value;
+                },
+                writeCredential(ref, value) {
+                    return credentials.set(ref, value);
+                },
+                removeCredential(ref) {
+                    return credentials.unset(ref);
+                },
+                async writeProfile(route, profile) {
+                    const ops = [{ op: 'set', path: ['providers', route], value: profile }];
+                    try {
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                    catch (error) {
+                        // One retry on a stale-revision conflict (a concurrent write
+                        // landed between describe and mutate); anything else propagates
+                        // so the wizard can report and roll back the credential.
+                        const code = error?.code;
+                        if (code !== 'SETTINGS_CONFLICT')
+                            throw error;
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                },
+                async mutateProfile(route, ops) {
+                    // Route-relative path patch: only the addressed fields inside
+                    // `providers.<route>` enter the write, so stored fields the TUI
+                    // does not model never pass through here and cannot be dropped.
+                    const full = ops.map(op => op.op === 'set'
+                        ? { op: 'set', path: ['providers', route, ...op.path], value: op.value }
+                        : { op: 'unset', path: ['providers', route, ...op.path] });
+                    try {
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', full, revision());
+                    }
+                    catch (error) {
+                        // Same stale-revision retry as writeProfile.
+                        const code = error?.code;
+                        if (code !== 'SETTINGS_CONFLICT')
+                            throw error;
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', full, revision());
+                    }
+                },
+                async removeProfile(route) {
+                    const ops = [{ op: 'unset', path: ['providers', route] }];
+                    try {
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                    catch (error) {
+                        // Same stale-revision retry as writeProfile: the wizard reports
+                        // any real failure so the credential deletion can be skipped.
+                        const code = error?.code;
+                        if (code !== 'SETTINGS_CONFLICT')
+                            throw error;
+                        assertActive();
+                        await settings.mutate('llm-pi-ai', ops, revision());
+                    }
+                },
+            };
+        },
+        async oauthProviderStatuses() {
+            // Same optional seam the wizard's OAuth branch reads: absent plugin →
+            // undefined, and `/login` renders exactly its pre-plugin lines.
+            const api = ctx.get('dshAuth')?.api;
+            return api === undefined ? undefined : api.providers();
+        }
+    };
+}

package/lib/types/dsh-adapter/channel/skill-catalog.d.ts

@@ -0,0 +1,33 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { CommandRuntime } from '@deepseek-ai/dsh-commands';
+import { type LocalCommand, type LocalizedDescriptions } from '../../commands.js';
+import type { ChannelOwner } from './owner.js';
+import type { SkillRegistry } from './loaded-context.js';
+/** Owns the merged catalog, host registrations, retry timer and all skill reads. */
+export declare function createSkillCatalog(ctx: Context, deps: {
+    owner: Pick<ChannelOwner, 'current' | 'own'>;
+    commandService: CommandRuntime | undefined;
+    agent(): Agent;
+    cwd(): string;
+    setCommands(commands: LocalCommand[]): void;
+    commandDescriptions(name: string): LocalizedDescriptions | undefined;
+    /** Submit a user line through the channel's delivery pipeline. The
+     *  fallback skill path rides this same entry point and attaches the
+     *  rendered body, so the line stays a plain user message (fence, pending
+     *  preview and `@` expansion included) and the body is appended to that
+     *  message's step batch — never a turn of its own. */
+    deliverUserText(text: string, placement: 'followup', attach?: UserMessage): void;
+}): {
+    start: () => void;
+    release: () => void;
+    refreshCommands: () => void;
+    refreshSkillCommands: (fromRetry?: boolean) => Promise<void>;
+    registryFor: (agent: Agent) => SkillRegistry | undefined;
+    viewOptions: (agent: Agent) => {
+        scope: Agent;
+        cwd: string;
+    };
+};
+//# sourceMappingURL=skill-catalog.d.ts.map

package/lib/types/dsh-adapter/channel/skill-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-catalog.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/skill-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE/D,OAAO,EAA8E,KAAK,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAI7J,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,oFAAoF;AACpF,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IACJ,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;IAC5C,cAAc,EAAE,cAAc,GAAG,SAAS,CAAA;IAC1C,KAAK,IAAI,KAAK,CAAA;IACd,GAAG,IAAI,MAAM,CAAA;IACb,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;IAC3C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;IACpE;;;;0DAIsD;IACtD,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;CACjF;iBA4JiB,IAAI;mBARF,IAAI;2BAhII,IAAI;mDAoDwB,OAAO,CAAC,IAAI,CAAC;yBAtDzC,KAAK,KAAG,aAAa,GAAG,SAAS;yBADjC,KAAK,KAAG;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;EA+JlE"}

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

@@ -0,0 +1,215 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { isUserInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill';
+import { HIDDEN_COMMAND_NAMES, isLocalCommandName, parseCommandName, LOCAL_COMMANDS } from '../../commands.js';
+import { t } from '../../i18n.js';
+import { serviceForAgent } from '../presets.js';
+import { hasCommandErrorCode, mapCommandError } from '../command-errors.js';
+const SKILL_COMMAND_RETRY_MS = 800;
+const MAX_SKILL_RETRY_ATTEMPTS = 3;
+/** Owns the merged catalog, host registrations, retry timer and all skill reads. */
+export function createSkillCatalog(ctx, deps) {
+    let commandListSeq = 0;
+    let skillCommandSeq = 0;
+    let lastGoodSkills;
+    const registrations = new Map();
+    const refused = new Set();
+    let retry;
+    let retryAttempts = 0;
+    let released = false;
+    const resetRetry = () => {
+        if (retry !== undefined)
+            clearTimeout(retry);
+        retry = undefined;
+        retryAttempts = 0;
+    };
+    const viewOptions = (agent) => ({ scope: agent, cwd: deps.cwd() });
+    const registryFor = (agent) => serviceForAgent(ctx, agent, 'skills');
+    const refreshCommands = () => {
+        if (!deps.owner.current())
+            return;
+        const target = deps.agent();
+        const token = ++commandListSeq;
+        const merged = [...LOCAL_COMMANDS];
+        if (deps.commandService !== undefined) {
+            for (const descriptor of deps.commandService.list(target)) {
+                if (!deps.owner.current())
+                    return;
+                if (HIDDEN_COMMAND_NAMES.has(descriptor.name) || merged.some(command => command.name === descriptor.name))
+                    continue;
+                const descriptions = deps.commandDescriptions(descriptor.name);
+                // `images` became `attachments` upstream (composer attachment
+                // admission); read both so older cohorts keep their image commands.
+                const input = descriptor.input;
+                merged.push({ name: descriptor.name, description: descriptor.description, ...(descriptions === undefined ? {} : { descriptions }), tag: input?.hint, external: true, acceptsImages: input?.attachments ?? input?.images === true, ...(registrations.has(descriptor.name) ? { skill: true } : {}) });
+            }
+        }
+        if (!deps.owner.current() || target !== deps.agent())
+            return;
+        deps.setCommands(merged);
+        if (!deps.owner.current() || target !== deps.agent())
+            return;
+        const registry = registryFor(target);
+        if (registry === undefined)
+            return;
+        const restore = () => {
+            if (!deps.owner.current() || target !== deps.agent())
+                return;
+            const fallback = lastGoodSkills?.agent === target ? lastGoodSkills.commands : [];
+            const entries = fallback.filter(entry => !merged.some(command => command.name === entry.name));
+            if (entries.length > 0)
+                deps.setCommands([...merged, ...entries]);
+        };
+        void registry.snapshot(viewOptions(target)).then(observation => {
+            if (!deps.owner.current() || token !== commandListSeq || target !== deps.agent())
+                return;
+            if (!observation.complete) {
+                ctx.logger.warn('skill command merge: incomplete catalog observation, keeping last-good skills');
+                restore();
+                return;
+            }
+            // Cache the observation, not the delta: registered skills are already
+            // in merged on later reads. Local/host collisions still win on restore.
+            const skills = [];
+            for (const skill of observation.skills) {
+                if (isUserInvocable(skill) && !skills.some(command => command.name === skill.name)) {
+                    skills.push({ name: skill.name, description: skill.description, skill: true });
+                }
+            }
+            lastGoodSkills = { agent: target, commands: skills };
+            const added = skills.filter(entry => !merged.some(command => command.name === entry.name));
+            if (added.length > 0 && deps.owner.current() && target === deps.agent())
+                deps.setCommands([...merged, ...added]);
+        }).catch((error) => {
+            if (!deps.owner.current() || token !== commandListSeq || target !== deps.agent())
+                return;
+            ctx.logger.warn('skill command merge failed: %o', error);
+            restore();
+        });
+    };
+    const refreshSkillCommands = async (fromRetry = false) => {
+        if (released || !deps.owner.current() || deps.commandService === undefined)
+            return;
+        // Explicit refreshes (including skills/change and agent swaps) supersede
+        // the old ladder. Only the timer continuation consumes the same budget.
+        if (!fromRetry)
+            resetRetry();
+        const token = ++skillCommandSeq;
+        const target = deps.agent();
+        const registry = registryFor(target);
+        if (registry === undefined)
+            return;
+        let observation;
+        try {
+            observation = await registry.snapshot(viewOptions(target));
+        }
+        catch (error) {
+            if (deps.owner.current() && token === skillCommandSeq && target === deps.agent())
+                ctx.logger.warn('skill commands: catalog read failed: %o', error);
+            return;
+        }
+        if (!deps.owner.current() || token !== skillCommandSeq || target !== deps.agent())
+            return;
+        if (!observation.complete) {
+            if (retry === undefined && retryAttempts < MAX_SKILL_RETRY_ATTEMPTS) {
+                const delay = SKILL_COMMAND_RETRY_MS * 2 ** retryAttempts++;
+                retry = setTimeout(() => {
+                    retry = undefined;
+                    if (token === skillCommandSeq && target === deps.agent())
+                        void refreshSkillCommands(true);
+                }, delay);
+                retry.unref?.();
+            }
+            // Partial reads cannot revoke callable handlers or replace descriptions.
+            // Keep the last-good registrations until an authoritative observation.
+            return;
+        }
+        resetRetry();
+        const wanted = new Map(observation.skills
+            .filter(isUserInvocable)
+            .filter(skill => parseCommandName(`/${skill.name}`)?.name === skill.name)
+            .filter(skill => !isLocalCommandName(skill.name))
+            .map(skill => [skill.name, skill.description]));
+        for (const [name, entry] of registrations) {
+            if (wanted.get(name) === entry.description)
+                continue;
+            entry.dispose();
+            registrations.delete(name);
+        }
+        for (const [name, description] of wanted) {
+            if (registrations.has(name) || refused.has(name) || deps.commandService.find(target, name) !== undefined)
+                continue;
+            try {
+                const dispose = deps.commandService.register({
+                    name, description, recordInput: false,
+                    handler: async ({ agent: invoker, rawInput, signal }) => {
+                        // This registration is bound to this Channel; retained handlers
+                        // must never redirect another agent into its current session.
+                        if (!deps.owner.current() || invoker !== deps.agent())
+                            return { kind: 'error', text: t('skill-unavailable', { name }) };
+                        const tools = ctx.get('tools');
+                        if (tools?.get('skill', invoker) !== undefined) {
+                            if (!deps.owner.current() || invoker !== deps.agent())
+                                return { kind: 'error', text: t('skill-unavailable', { name }) };
+                            deps.deliverUserText(`/${name}${rawInput}`, 'followup');
+                            return { kind: 'success' };
+                        }
+                        const skill = await registryFor(invoker)?.get(name, { ...viewOptions(invoker), signal });
+                        if (skill === undefined || !isUserInvocable(skill))
+                            return { kind: 'error', text: t('skill-unavailable', { name }) };
+                        if (!deps.owner.current() || invoker !== deps.agent())
+                            return { kind: 'error', text: t('skill-unavailable', { name }) };
+                        // No `skill` tool: deliver the gesture as the user's own line and
+                        // attach the rendered body. The channel's resident pre-step
+                        // listener appends the body AFTER the admitted batch — the same
+                        // shape/order as dsh-tool-skill's gesture boundary (#842).
+                        const bodyMessage = createUserMessage({ content: [{ type: 'text', text: renderSkillContent(skill) }], source: { kind: 'skill-invocation', name, form: 'instructions' } });
+                        deps.deliverUserText(`/${name}${rawInput}`, 'followup', bodyMessage);
+                        return { kind: 'success' };
+                    },
+                });
+                registrations.set(name, { dispose, description });
+                ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'command', id: name }, result: 'applied' }, ctx);
+            }
+            catch (error) {
+                const mapped = mapCommandError(error);
+                refused.add(name);
+                ctx.logger.warn(`skill commands: "${name}" not registrable%s: %o`, hasCommandErrorCode(mapped, 'DUPLICATE_CONTRIBUTION_ID') ? ' (DUPLICATE_CONTRIBUTION_ID)' : '', mapped);
+                ctx.get('tuiEffectLedger')?.record({ operation: 'create', resource: { kind: 'command', id: name }, result: 'failed', errorCode: hasCommandErrorCode(mapped, 'DUPLICATE_CONTRIBUTION_ID') ? 'DUPLICATE_CONTRIBUTION_ID' : 'COMMAND_FAILED' }, ctx);
+            }
+        }
+    };
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        skillCommandSeq += 1;
+        resetRetry();
+        for (const entry of registrations.values())
+            entry.dispose();
+        registrations.clear();
+    };
+    const start = () => {
+        if (!deps.owner.current())
+            return;
+        // Establish a single idempotent teardown before the first registration;
+        // a later ctx.on() throw then rolls back every earlier listener.
+        const owned = [deps.owner.own(release)];
+        try {
+            owned.push(deps.owner.own(ctx.on('commands/change', refreshCommands)));
+            owned.push(deps.owner.own(ctx.on('skills/change', () => { refreshCommands(); void refreshSkillCommands(); })));
+            if (!deps.owner.current()) {
+                for (const dispose of owned.reverse())
+                    dispose();
+                return;
+            }
+            refreshCommands();
+            void refreshSkillCommands();
+        }
+        catch (error) {
+            for (const dispose of owned.reverse())
+                dispose();
+            throw error;
+        }
+    };
+    return { start, release, refreshCommands, refreshSkillCommands, registryFor, viewOptions };
+}

package/lib/types/dsh-adapter/channel/state.d.ts

@@ -0,0 +1,51 @@
+import type { AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { SessionModeSpec } from '../../sessionModes.js';
+import { type PageMarginSetting, type ScrollGutterMode, type StatusBarConfig, type ToolBackground } from '../../tuiDisplayPrefs.js';
+import type { ChannelState } from './types.js';
+/** Launch configuration belongs to channel construction, not the composition root. */
+export interface ChannelLaunchOptions {
+    model: string;
+    cwd: string;
+    provider: string;
+    effort?: string;
+    activity?: boolean;
+    /** Read the activity projection's current value when a session binds. A
+     *  projection value only arrives on change, so a resumed session needs this
+     *  read to render its line before the next event lands. */
+    seedActivity?: (session: unknown) => void;
+    activityFrames?: string;
+    diffLayout?: 'auto' | 'split' | 'unified';
+    thinkingFold?: 'preview' | 'full';
+    toolBackground?: ToolBackground;
+    scrollGutter?: ScrollGutterMode;
+    pageMargin?: PageMarginSetting;
+    foldTerminalCommand?: boolean;
+    promptSessionLabel?: boolean;
+    expandEditor?: boolean;
+    smoothStreaming?: boolean;
+    statusBar?: Partial<StatusBarConfig>;
+    whale?: boolean;
+    whaleIdle?: boolean;
+    minimal?: boolean;
+    contextBar?: boolean;
+    configuredPreset?: string;
+    configuredProvider?: string;
+    configuredModel?: string;
+    configuredLang?: string;
+    configuredActivityFrames?: string;
+    agentPreset?: string;
+    modes?: readonly SessionModeSpec[];
+    handle?: AgentHandle;
+}
+/**
+ * Neutral observable fields only. Behaviour is assembled explicitly by the
+ * composition root after each specialist owner exists, so this factory cannot
+ * acquire services, subscribe, or create a second authority bag.
+ */
+export declare function createInitialChannelView(options: ChannelLaunchOptions, input: {
+    agentId: string;
+    sessionId: string;
+    mode: ChannelState['mode'];
+    cwdDescription: string;
+}): Pick<ChannelState, 'effortLevels' | 'version' | 'rows' | 'status' | 'sessionTitle' | 'sessionColor' | 'agentId' | 'sessionId' | 'agentBindingGeneration' | 'model' | 'provider' | 'tokens' | 'cwd' | 'displayCwd' | 'gitBranch' | 'working' | 'cancelPending' | 'spinnerMode' | 'responseChars' | 'activeToolCount' | 'turnStart' | 'lastUserText' | 'notifications' | 'contextWindow' | 'reasoningEffort' | 'mode' | 'modeIndex' | 'activityFrames' | 'configuredProvider' | 'configuredModel' | 'configuredPreset' | 'configuredActivityFrames' | 'configuredLang' | 'diffLayout' | 'thinkingFold' | 'toolBackground' | 'scrollGutter' | 'pageMargin' | 'foldTerminalCommand' | 'promptSessionLabel' | 'expandEditor' | 'smoothStreaming' | 'statusBar' | 'whale' | 'whaleIdle' | 'minimal' | 'activityEnabled' | 'contextBarEnabled' | 'agentPreset' | 'goal' | 'todos' | 'loadedContext' | 'pending' | 'commandList' | 'lastUsage' | 'tps' | 'tpsSamples' | 'contextSegments' | 'subagents' | 'backgroundJobs' | 'selection'>;
+//# sourceMappingURL=state.d.ts.map

package/lib/types/dsh-adapter/channel/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/state.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,31 @@
+import { normalizePageMargin, normalizeScrollGutter, normalizeStatusBar, normalizeToolBackground } from '../../tuiDisplayPrefs.js';
+import { normalizeActivityPreset } from '../../components/activityFrames.js';
+/**
+ * Neutral observable fields only. Behaviour is assembled explicitly by the
+ * composition root after each specialist owner exists, so this factory cannot
+ * acquire services, subscribe, or create a second authority bag.
+ */
+export function createInitialChannelView(options, input) {
+    return {
+        effortLevels: undefined, version: 0, rows: [], selection: undefined, status: 'starting', sessionTitle: '', sessionColor: '',
+        agentId: input.agentId, sessionId: input.sessionId, agentBindingGeneration: 0, model: options.model, provider: options.provider,
+        tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, peak: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, idle: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } },
+        cwd: options.cwd, displayCwd: input.cwdDescription, gitBranch: undefined, working: false,
+        cancelPending: false, spinnerMode: 'requesting', responseChars: 0, activeToolCount: 0,
+        turnStart: 0, lastUserText: '', notifications: [], contextWindow: undefined,
+        reasoningEffort: options.effort, mode: input.mode, modeIndex: 0,
+        activityFrames: normalizeActivityPreset(options.activityFrames), configuredProvider: options.configuredProvider,
+        configuredModel: options.configuredModel, configuredPreset: options.configuredPreset,
+        configuredActivityFrames: options.configuredActivityFrames, configuredLang: options.configuredLang,
+        diffLayout: options.diffLayout ?? 'auto', thinkingFold: options.thinkingFold ?? 'preview',
+        toolBackground: normalizeToolBackground(options.toolBackground), scrollGutter: normalizeScrollGutter(options.scrollGutter),
+        pageMargin: normalizePageMargin(options.pageMargin), foldTerminalCommand: options.foldTerminalCommand === true,
+        promptSessionLabel: options.promptSessionLabel === true, expandEditor: options.expandEditor !== false,
+        smoothStreaming: options.smoothStreaming !== false, statusBar: normalizeStatusBar(options.statusBar),
+        whale: options.whale !== false, whaleIdle: options.whaleIdle !== false, minimal: options.minimal === true, activityEnabled: options.activity !== false,
+        contextBarEnabled: options.contextBar !== false, agentPreset: options.agentPreset, goal: undefined,
+        todos: [], loadedContext: undefined, pending: [], commandList: [], lastUsage: undefined,
+        tps: undefined, tpsSamples: [], contextSegments: { system: 0, prompt: 0, assistant: 0, thinking: 0, tools: 0 },
+        subagents: [], backgroundJobs: [],
+    };
+}