@khorsheed/dsh-local-agent-dsh 0.1.0-rc.6

package/lib/types/live-switch.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The settings-driven live-driver switch: owns the active driver generation
+ * and retires old ones on a settings change, without a plugin reload.
+ *
+ * Toggle OFF (or the enabled generation unloading): the retiring generation
+ * is DRAINED, not killed — new rounds are refused (the provider's catch falls
+ * back to exec), in-flight rounds finish on their runtime, idle runtimes are
+ * reclaimed at once. Toggling ON builds the next generation lazily (no
+ * process until the first round). Legacy granularity settings are ignored.
+ *
+ * Composition with the `enabled` toggle: the switch lives INSIDE one enabled
+ * generation (index.ts constructs it only while the harness/provider/tool are
+ * registered, and disposes it with them). `enabled` gates EXISTENCE — its
+ * teardown keeps the historical hard semantics (`dispose()` → disposeAll,
+ * which may interrupt); `live` gates the MODE of an enabled generation and
+ * never interrupts (drain). While `enabled` is off the live value is inert
+ * and applies when the toggle turns on again.
+ *
+ * @module @khorsheed/dsh-local-agent-dsh — internal, unit-tested directly.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SettingsFace } from '@khorsheed/dsh-local-agent';
+import type { LocalAgentDshConfig } from './index.ts';
+import { DshLiveDriver } from './live-driver.ts';
+import type { DshLiveMirrorGranularity } from './session-mirror.ts';
+/** The resolved `local-agent-dsh` settings (rc.1: volatile row config; 0.1.5: schema defaults ← YAML base ← user layer). */
+export interface DshLiveSettings {
+    /** The DeepSeek delegation toggle; the switch itself reads only the live fields. */
+    enabled: boolean;
+    live: boolean;
+    liveMirrorGranularity: DshLiveMirrorGranularity;
+}
+export declare class LiveDriverSwitch {
+    private readonly ctx;
+    private readonly config;
+    private readonly extras;
+    private liveOn;
+    private active;
+    /** Retiring generations still draining their in-flight rounds. */
+    private readonly draining;
+    private readonly unwatch;
+    constructor(ctx: Context, face: SettingsFace<DshLiveSettings>, config: LocalAgentDshConfig, extras?: {
+        /**
+         * Per-spawn model resolver, handed to every driver generation. Receives
+         * the member's child session id so the session-level override can
+         * outrank the settings value.
+         */
+        modelFor?: (childSessionId: string) => string | undefined;
+    });
+    /**
+     * Resolve the live driver for one round's member (the provider's call
+     * site). A retiring generation still hosting the member gates the new one —
+     * the round falls back to exec rather than double-loading the same sub-dsh
+     * session into two processes.
+     */
+    readonly resolve: (childSessionId: string) => DshLiveDriver | undefined;
+    /**
+     * The model the member's live runtime bound at spawn (the broker's switch
+     * check): the identifier, undefined for "bound to no model", null for "no
+     * live runtime". Consults only the ACTIVE generation — a draining one is on
+     * its way out anyway.
+     */
+    boundModel(childSessionId: string): string | undefined | null;
+    /**
+     * Retire the member's resident runtime in the active generation so the next
+     * round respawns onto the member's new effective model (the composer's
+     * model switch path; the sub-dsh session itself carries over via the
+     * on-disk resume).
+     */
+    retireRuntime(childSessionId: string): Promise<void>;
+    /** Mirror the resolved settings into the driver generation. */
+    private apply;
+    /** Enabled-generation unload: interrupt whatever survives (disposeAll, not drain). */
+    dispose(): void;
+}
+//# sourceMappingURL=live-switch.d.ts.map

package/lib/types/live-switch.js

@@ -0,0 +1,100 @@
+/**
+ * The settings-driven live-driver switch: owns the active driver generation
+ * and retires old ones on a settings change, without a plugin reload.
+ *
+ * Toggle OFF (or the enabled generation unloading): the retiring generation
+ * is DRAINED, not killed — new rounds are refused (the provider's catch falls
+ * back to exec), in-flight rounds finish on their runtime, idle runtimes are
+ * reclaimed at once. Toggling ON builds the next generation lazily (no
+ * process until the first round). Legacy granularity settings are ignored.
+ *
+ * Composition with the `enabled` toggle: the switch lives INSIDE one enabled
+ * generation (index.ts constructs it only while the harness/provider/tool are
+ * registered, and disposes it with them). `enabled` gates EXISTENCE — its
+ * teardown keeps the historical hard semantics (`dispose()` → disposeAll,
+ * which may interrupt); `live` gates the MODE of an enabled generation and
+ * never interrupts (drain). While `enabled` is off the live value is inert
+ * and applies when the toggle turns on again.
+ *
+ * @module @khorsheed/dsh-local-agent-dsh — internal, unit-tested directly.
+ */
+import { DshLiveDriver } from './live-driver.js';
+export class LiveDriverSwitch {
+    ctx;
+    config;
+    extras;
+    liveOn = false;
+    active;
+    /** Retiring generations still draining their in-flight rounds. */
+    draining = new Set();
+    unwatch;
+    constructor(ctx, face, config, extras = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.extras = extras;
+        this.apply(face.get());
+        this.unwatch = face.watch((next) => { this.apply(next); });
+    }
+    /**
+     * Resolve the live driver for one round's member (the provider's call
+     * site). A retiring generation still hosting the member gates the new one —
+     * the round falls back to exec rather than double-loading the same sub-dsh
+     * session into two processes.
+     */
+    resolve = (childSessionId) => {
+        if (this.active === undefined)
+            return undefined;
+        for (const retiring of this.draining) {
+            if (retiring.hasRuntime(childSessionId))
+                return undefined;
+        }
+        return this.active;
+    };
+    /**
+     * The model the member's live runtime bound at spawn (the broker's switch
+     * check): the identifier, undefined for "bound to no model", null for "no
+     * live runtime". Consults only the ACTIVE generation — a draining one is on
+     * its way out anyway.
+     */
+    boundModel(childSessionId) {
+        return this.active?.boundModelOf(childSessionId) ?? null;
+    }
+    /**
+     * Retire the member's resident runtime in the active generation so the next
+     * round respawns onto the member's new effective model (the composer's
+     * model switch path; the sub-dsh session itself carries over via the
+     * on-disk resume).
+     */
+    async retireRuntime(childSessionId) {
+        await this.active?.retireRuntime(childSessionId);
+    }
+    /** Mirror the resolved settings into the driver generation. */
+    apply(next) {
+        if (next.live === this.liveOn) {
+            return;
+        }
+        this.liveOn = next.live;
+        const retiring = this.active;
+        this.active = next.live
+            ? new DshLiveDriver(this.ctx, {
+                ...this.config,
+                ...this.extras.modelFor === undefined ? {} : { modelFor: this.extras.modelFor },
+            })
+            : undefined;
+        if (retiring !== undefined) {
+            this.draining.add(retiring);
+            void retiring.drain().then(() => { this.draining.delete(retiring); }, (error) => {
+                this.draining.delete(retiring);
+                this.ctx.logger.warn(`local-agent-dsh: live driver drain failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    }
+    /** Enabled-generation unload: interrupt whatever survives (disposeAll, not drain). */
+    dispose() {
+        this.unwatch();
+        void this.active?.disposeAll();
+        for (const retiring of this.draining)
+            void retiring.disposeAll();
+        this.draining.clear();
+    }
+}

package/lib/types/model-broker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The dsh harness's model broker: the member-aware model surface the core
+ * gateway routes to (`harnessModel` for the settings card, `memberModel` /
+ * `setMemberModel` for the composer picker). It owns the session-level
+ * override map — shared with the exec provider (which consults it per round)
+ * and the live driver (which binds it at runtime spawn) — and retires a
+ * member's resident serve process when a switch leaves it bound to a
+ * different model, so the NEXT round respawns onto the new one while the
+ * sub-dsh session itself carries over via the on-disk resume.
+ *
+ * Resolution order is the family's fixed one (first match wins): override →
+ * the delegation's recorded model → the plugin-config `model` (settings) →
+ * the host instance's default model selection spelled `provider/model`
+ * (cliDefault — the selection a sub-dsh with no `--model` inherits) → the
+ * CLI's built-in default, which names nothing. The pickable vocabulary is
+ * settings + cliDefault + the host's own adapter enumeration (the public
+ * `ctx.llm` surface — `listProviders` × `listModels`, spelled `provider/model`
+ * exactly as the sub-dsh's `--model` expects; the same trio the host's model
+ * picker is built on) + the card's recent-model memory.
+ * @module @khorsheed/dsh-local-agent-dsh/model-broker
+ */
+import type { MemberConfigurationAdapter } from '@khorsheed/dsh-local-agent';
+import type { DshModelCatalog } from './model-catalog.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import type { LocalAgentModelBroker, LocalAgentModelInfo, LocalAgentModelDirectory, LocalAgentMemberBinding } from '@khorsheed/dsh-local-agent/types';
+/** Everything the broker reads or drives, injected so the unit specs stay small. */
+export interface DshModelBrokerDeps {
+    /** Host context carrying the family registry (in-flight reads, delegation records). */
+    readonly ctx: Context;
+    /** The plugin-config `model` resolver — the settings layer, blank reads unset. */
+    readonly settingsModel: () => string | undefined;
+    /**
+     * The host instance's default model selection spelled `provider/model` —
+     * what a round with no `--model` inherits. Undefined when the service or
+     * the selection is unreadable (absence is the honest answer, never a guess).
+     */
+    readonly cliDefault: () => string | undefined;
+    readonly defaultEffort?: () => string | undefined;
+    /**
+     * The host's adapter enumeration spelled `provider/model` — discovered
+     * host-side via `ctx.llm` and cached by the caller (refreshed on
+     * `llm/adapters-updated`), so this read stays synchronous. Empty when the
+     * service is absent: the other choice layers still answer.
+     */
+    readonly discovered: () => readonly string[];
+    readonly catalog?: DshModelCatalog;
+    /** The card's recent-model memory (the suggestion vocabulary's tail). */
+    readonly recentModels: () => readonly string[];
+    /** Whether the live driver is on (the member's rounds bind resident runtimes). */
+    readonly live: () => boolean;
+    /**
+     * The session-level overrides this broker owns. Shared by reference with the
+     * exec provider's per-round resolution and the live driver's spawn binding,
+     * so a switch reaches every path without a reload.
+     */
+    readonly overrides: Map<string, string>;
+    /**
+     * The model the member's live runtime bound at spawn: the identifier,
+     * undefined for "bound to no model", null for "no live runtime".
+     */
+    readonly liveBoundModel: (childSessionId: string) => string | undefined | null;
+    /** Retire the member's live runtime; the next round respawns onto the new model. */
+    readonly retireRuntime: (childSessionId: string) => Promise<void>;
+}
+export declare class DshModelBroker implements LocalAgentModelBroker {
+    private readonly deps;
+    constructor(deps: DshModelBrokerDeps);
+    configurationAdapter(binding: LocalAgentMemberBinding): MemberConfigurationAdapter;
+    modelDirectory(childSessionId?: string, refresh?: boolean): Promise<LocalAgentModelDirectory>;
+    followModelDirectory(childSessionId: string | undefined, signal: AbortSignal): AsyncIterable<LocalAgentModelDirectory>;
+    /** The member's in-flight rounds (an empty answer on a core that predates the read). */
+    private activeDelegations;
+    /** The model the member's NEXT spawn binds explicitly: override → recorded → settings. */
+    private boundLayer;
+    /** Read the model surface; every layer reports its own value so a UI can explain the effective one. */
+    modelInfo(childSessionId?: string, delegationModel?: string): LocalAgentModelInfo;
+    /**
+     * Set (or clear) the member's session-level override. Same-model is a
+     * no-op; a different model with a live runtime bound elsewhere retires the
+     * runtime so the next round respawns (the sub-dsh session resumes from
+     * disk). Throws while a round is in flight — retiring mid-round would kill
+     * the run.
+     */
+    setMemberModel(childSessionId: string, model: string | undefined): Promise<void>;
+}
+//# sourceMappingURL=model-broker.d.ts.map

package/lib/types/model-broker.js

@@ -0,0 +1,149 @@
+/**
+ * The dsh harness's model broker: the member-aware model surface the core
+ * gateway routes to (`harnessModel` for the settings card, `memberModel` /
+ * `setMemberModel` for the composer picker). It owns the session-level
+ * override map — shared with the exec provider (which consults it per round)
+ * and the live driver (which binds it at runtime spawn) — and retires a
+ * member's resident serve process when a switch leaves it bound to a
+ * different model, so the NEXT round respawns onto the new one while the
+ * sub-dsh session itself carries over via the on-disk resume.
+ *
+ * Resolution order is the family's fixed one (first match wins): override →
+ * the delegation's recorded model → the plugin-config `model` (settings) →
+ * the host instance's default model selection spelled `provider/model`
+ * (cliDefault — the selection a sub-dsh with no `--model` inherits) → the
+ * CLI's built-in default, which names nothing. The pickable vocabulary is
+ * settings + cliDefault + the host's own adapter enumeration (the public
+ * `ctx.llm` surface — `listProviders` × `listModels`, spelled `provider/model`
+ * exactly as the sub-dsh's `--model` expects; the same trio the host's model
+ * picker is built on) + the card's recent-model memory.
+ * @module @khorsheed/dsh-local-agent-dsh/model-broker
+ */
+import { extendModelDirectory } from '@khorsheed/dsh-local-agent';
+/** Dedupe the choice vocabulary, dropping unset layers and blanks. */
+function dedupeChoices(layers) {
+    const seen = new Set();
+    const choices = [];
+    for (const layer of layers) {
+        const value = layer?.trim();
+        if (value === undefined || value === '' || seen.has(value))
+            continue;
+        seen.add(value);
+        choices.push(value);
+    }
+    return choices;
+}
+export class DshModelBroker {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    configurationAdapter(binding) {
+        const resolve = async (selection) => {
+            let directory = this.deps.catalog?.read();
+            if (directory?.status === 'loading')
+                directory = await this.deps.catalog?.refresh();
+            const model = selection.model.mode === 'value' ? selection.model.value
+                : (selection.model.mode === 'inherit' ? binding.model : undefined) ?? this.deps.settingsModel() ?? this.deps.cliDefault();
+            const entry = directory?.entries.find(entry => entry.value === model);
+            const requested = selection.effort.mode === 'value' ? selection.effort.value : selection.effort.mode === 'inherit' ? binding.effort : undefined;
+            const effort = requested ?? this.deps.defaultEffort?.() ?? entry?.reasoning?.default;
+            if (effort !== undefined && !entry?.reasoning?.options.some(option => option.value === effort)) {
+                throw new Error('DSH has not advertised this reasoning effort for the selected model');
+            }
+            return { ...model === undefined ? {} : { model }, ...effort === undefined ? {} : { effort } };
+        };
+        return {
+            validate: async (selection) => { await resolve(selection); }, prepare: resolve,
+            apply: async (selection) => { const resolved = await resolve(selection); await this.deps.retireRuntime(binding.childSessionId); return resolved; },
+            reconcile: async (state) => {
+                if (this.activeDelegations().includes(binding.childSessionId))
+                    return { active: true, matches: 'unknown', resolved: {} };
+                await this.deps.retireRuntime(binding.childSessionId);
+                return { active: false, matches: 'current', resolved: await resolve(state.current.selection) };
+            },
+        };
+    }
+    async modelDirectory(childSessionId, refresh = false) {
+        if (refresh)
+            await this.deps.catalog?.refresh();
+        return this.modelInfo(childSessionId).directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+    }
+    async *followModelDirectory(childSessionId, signal) {
+        if (this.deps.catalog === undefined) {
+            yield await this.modelDirectory(childSessionId);
+            return;
+        }
+        for await (const _snapshot of this.deps.catalog.follow(signal))
+            yield await this.modelDirectory(childSessionId);
+    }
+    /** The member's in-flight rounds (an empty answer on a core that predates the read). */
+    activeDelegations() {
+        const registry = this.deps.ctx.localAgent;
+        return typeof registry.activeDelegations === 'function' ? registry.activeDelegations() : [];
+    }
+    /** The model the member's NEXT spawn binds explicitly: override → recorded → settings. */
+    boundLayer(childSessionId) {
+        const override = this.deps.overrides.get(childSessionId);
+        if (override !== undefined)
+            return override;
+        const record = this.deps.ctx.localAgent.getDelegation(childSessionId);
+        const recorded = record?.model?.trim();
+        if (recorded !== undefined && recorded !== '')
+            return recorded;
+        return this.deps.settingsModel();
+    }
+    /** Read the model surface; every layer reports its own value so a UI can explain the effective one. */
+    modelInfo(childSessionId, delegationModel) {
+        const settings = this.deps.settingsModel();
+        const cliDefault = this.deps.cliDefault();
+        const directory = this.deps.catalog?.read();
+        const override = childSessionId === undefined ? undefined : this.deps.overrides.get(childSessionId);
+        const delegation = delegationModel?.trim() === '' ? undefined : delegationModel;
+        const effective = override ?? delegation ?? settings ?? cliDefault;
+        const source = override !== undefined ? 'override'
+            : delegation !== undefined ? 'delegation'
+                : settings !== undefined ? 'settings'
+                    : cliDefault !== undefined ? 'cli-config' : 'cli-builtin';
+        const inFlight = childSessionId !== undefined && this.activeDelegations().includes(childSessionId);
+        return {
+            ...effective === undefined ? {} : { effective },
+            source,
+            ...override === undefined ? {} : { override },
+            ...delegation === undefined ? {} : { delegation },
+            ...settings === undefined ? {} : { settings },
+            ...cliDefault === undefined ? {} : { cliDefault },
+            ...directory === undefined ? {} : { directory: extendModelDirectory(directory, [settings, cliDefault], this.deps.recentModels()) },
+            choices: dedupeChoices([settings, cliDefault, ...this.deps.discovered(), ...this.deps.recentModels()]),
+            live: this.deps.live(),
+            switchable: !inFlight,
+            ...inFlight ? { reason: '成员有进行中的委派轮次，等其完成后再切换模型' } : {},
+        };
+    }
+    /**
+     * Set (or clear) the member's session-level override. Same-model is a
+     * no-op; a different model with a live runtime bound elsewhere retires the
+     * runtime so the next round respawns (the sub-dsh session resumes from
+     * disk). Throws while a round is in flight — retiring mid-round would kill
+     * the run.
+     */
+    async setMemberModel(childSessionId, model) {
+        if (typeof this.deps.ctx.localAgent.setMemberModel === 'function')
+            return this.deps.ctx.localAgent.setMemberModel(childSessionId, model);
+        if (this.activeDelegations().includes(childSessionId)) {
+            throw new Error(`subagent-dsh: 成员有进行中的委派轮次，等其完成后再切换模型 (child session ${childSessionId})`);
+        }
+        const trimmed = model?.trim();
+        const next = trimmed === undefined || trimmed === '' ? undefined : trimmed;
+        if (this.deps.overrides.get(childSessionId) === next)
+            return;
+        if (next === undefined)
+            this.deps.overrides.delete(childSessionId);
+        else
+            this.deps.overrides.set(childSessionId, next);
+        const bound = this.deps.liveBoundModel(childSessionId);
+        if (bound !== null && bound !== this.boundLayer(childSessionId)) {
+            await this.deps.retireRuntime(childSessionId);
+        }
+    }
+}

package/lib/types/model-catalog.d.ts

@@ -0,0 +1,27 @@
+import type { LlmModelInfo, LlmResolvedModelInfo } from '@deepseek-ai/dsh-llm';
+import type { LocalAgentModelDirectory } from '@khorsheed/dsh-local-agent/types';
+export interface DshModelDirectoryFace {
+    listProviders(): readonly {
+        id: string;
+    }[];
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModelInfo?(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+}
+/** The public host adapter catalog used by sub-DSH provisioning. No generation request. */
+export declare class DshModelCatalog {
+    private readonly deps;
+    private readonly cache;
+    constructor(deps: {
+        llm: () => DshModelDirectoryFace | undefined;
+        defaultModel: () => string | undefined;
+        timeoutMs?: number;
+    });
+    private key;
+    read(): LocalAgentModelDirectory;
+    refresh(): Promise<LocalAgentModelDirectory>;
+    follow(signal: AbortSignal): AsyncIterable<LocalAgentModelDirectory>;
+    invalidate(): void;
+    dispose(): void;
+    private discover;
+}
+//# sourceMappingURL=model-catalog.d.ts.map

package/lib/types/model-catalog.js

@@ -0,0 +1,71 @@
+import { ModelDirectoryCache } from '@khorsheed/dsh-local-agent';
+/** The public host adapter catalog used by sub-DSH provisioning. No generation request. */
+export class DshModelCatalog {
+    deps;
+    cache;
+    constructor(deps) {
+        this.deps = deps;
+        this.cache = new ModelDirectoryCache({ load: async (_key, signal) => {
+                const controller = new AbortController();
+                const abort = () => controller.abort();
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted)
+                    abort();
+                let timer;
+                try {
+                    return await Promise.race([
+                        this.discover(controller.signal),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => { controller.abort(); reject(new Error('DSH model directory timed out')); }, deps.timeoutMs ?? 5_000);
+                            timer.unref();
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                    signal.removeEventListener('abort', abort);
+                }
+            } });
+    }
+    key() { return JSON.stringify({ defaultModel: this.deps.defaultModel() }); }
+    read() { return this.cache.read(this.key()); }
+    refresh() { return this.cache.refresh(this.key()); }
+    follow(signal) { return this.cache.follow(() => this.key(), signal); }
+    invalidate() { this.cache.invalidate(this.key()); }
+    dispose() { this.cache.dispose(); }
+    async discover(signal) {
+        const llm = this.deps.llm();
+        if (llm === undefined || typeof llm.listProviders !== 'function' || typeof llm.listModels !== 'function') {
+            return { entries: [], complete: false, customInput: true, unsupported: true, reason: 'The host exposes no adapter model directory' };
+        }
+        const providers = llm.listProviders();
+        const groups = await Promise.allSettled(providers.map(async (provider) => Promise.all((await llm.listModels(provider.id)).map(async (model) => {
+            let resolved;
+            try {
+                resolved = await llm.resolveModelInfo?.(provider.id, model.id, signal);
+            }
+            catch { /* Unknown capabilities stay unknown. */ }
+            const entry = {
+                value: `${provider.id}/${model.id}`, label: model.name ?? model.id, source: 'native',
+                ...model.description === undefined ? {} : { description: model.description },
+                ...resolved === undefined ? {} : { resolvedModel: `${resolved.provider}/${resolved.id}` },
+                ...resolved?.reasoning === undefined ? {} : { reasoning: {
+                        options: resolved.reasoning.efforts.map(effort => ({ value: String(effort.id), label: effort.name, ...effort.description === undefined ? {} : { description: effort.description } })),
+                        ...resolved.reasoning.defaultEffort === undefined ? {} : { default: String(resolved.reasoning.defaultEffort) },
+                    } },
+            };
+            return entry;
+        }))));
+        const failed = groups.filter(group => group.status === 'rejected').length;
+        if (failed > 0 && failed === groups.length)
+            throw new Error('DSH adapters could not list models');
+        const entries = groups.flatMap(group => group.status === 'fulfilled' ? group.value : []);
+        const defaultModel = this.deps.defaultModel();
+        return {
+            entries, complete: failed === 0, customInput: true,
+            ...defaultModel === undefined ? {} : { defaultModel },
+            ...failed === 0 ? {} : { reason: `${failed} adapter model list(s) unavailable` },
+        };
+    }
+}