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

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

@@ -0,0 +1,78 @@
+/**
+ * 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 unload): 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.
+ *
+ * @module @khorsheed/dsh-local-agent-kimi — internal, unit-tested directly.
+ */
+import type { KimiNativeConfiguration } from './model-catalog.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SettingsFace } from '@khorsheed/dsh-local-agent';
+import { KimiAcpLiveDriver } from './live-driver.ts';
+import type { KimiLiveMirrorGranularity } from './live-driver.ts';
+/** The resolved live settings (rc.1: volatile row config; 0.1.5: schema defaults ← YAML base ← user layer). */
+export interface KimiLiveSettings {
+    live: boolean;
+    liveMirrorGranularity: KimiLiveMirrorGranularity;
+    /** The configured model, when the card or the YAML base names one. */
+    model?: string;
+    /** Model identifiers the card has saved before (its input's suggestions). */
+    recentModels?: readonly string[];
+}
+export declare class LiveDriverSwitch {
+    private readonly ctx;
+    private readonly liveIdleMs;
+    /**
+     * Per-spawn model resolver, handed to every driver generation. Member-aware:
+     * the driver's runtime binds whatever the member's layers resolve to.
+     */
+    private readonly model?;
+    private liveOn;
+    private active;
+    /** Retiring generations still draining their in-flight rounds. */
+    private readonly draining;
+    private readonly unwatch;
+    constructor(ctx: Context, face: SettingsFace<KimiLiveSettings>, liveIdleMs: number | undefined, 
+    /**
+     * Per-spawn model resolver, handed to every driver generation. Member-aware:
+     * the driver's runtime binds whatever the member's layers resolve to.
+     */
+    model?: ((childSessionId: string) => string | undefined) | 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 kimi
+     * session into two processes.
+     */
+    readonly resolve: (childSessionId: string) => KimiAcpLiveDriver | undefined;
+    /** Mirror the resolved settings into the driver generation. */
+    private apply;
+    /**
+     * Retire one member's runtime on the ACTIVE generation (a composer-driven
+     * model switch): the next round respawns onto the new model. A member still
+     * hosted by a draining generation is left alone — its rounds already gate
+     * to exec, and the drain reclaims the process.
+     */
+    retireMemberRuntime(childSessionId: string): Promise<void>;
+    /**
+     * The model the member's active-generation runtime is bound to, or
+     * undefined when no live runtime serves the member (the broker's
+     * same-model no-op check).
+     */
+    memberRuntimeModel(childSessionId: string): string | undefined;
+    /**
+     * Whether the active generation hosts (or is spawning) the member's
+     * runtime — the broker's retire decision needs this apart from the bound
+     * model, since a runtime that bound NO model reports undefined either way.
+     */
+    memberHasRuntime(childSessionId: string): boolean;
+    memberRuntimeConfiguration(childSessionId: string): KimiNativeConfiguration | undefined;
+    /** Plugin unload: interrupt whatever survives (disposeAll, not drain). */
+    dispose(): void;
+}
+//# sourceMappingURL=live-switch.d.ts.map

package/lib/types/live-switch.js

@@ -0,0 +1,112 @@
+/**
+ * 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 unload): 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.
+ *
+ * @module @khorsheed/dsh-local-agent-kimi — internal, unit-tested directly.
+ */
+import { KimiAcpLiveDriver } from './live-driver.js';
+export class LiveDriverSwitch {
+    ctx;
+    liveIdleMs;
+    model;
+    liveOn = false;
+    active;
+    /** Retiring generations still draining their in-flight rounds. */
+    draining = new Set();
+    unwatch;
+    constructor(ctx, face, liveIdleMs, 
+    /**
+     * Per-spawn model resolver, handed to every driver generation. Member-aware:
+     * the driver's runtime binds whatever the member's layers resolve to.
+     */
+    model) {
+        this.ctx = ctx;
+        this.liveIdleMs = liveIdleMs;
+        this.model = model;
+        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 kimi
+     * 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;
+    };
+    /** 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 KimiAcpLiveDriver(this.ctx, {
+                ...this.liveIdleMs === undefined ? {} : { liveIdleMs: this.liveIdleMs },
+                ...this.model === undefined ? {} : { model: this.model },
+            })
+            : 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-kimi: live driver drain failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    }
+    /**
+     * Retire one member's runtime on the ACTIVE generation (a composer-driven
+     * model switch): the next round respawns onto the new model. A member still
+     * hosted by a draining generation is left alone — its rounds already gate
+     * to exec, and the drain reclaims the process.
+     */
+    async retireMemberRuntime(childSessionId) {
+        await this.active?.retireRuntime(childSessionId);
+    }
+    /**
+     * The model the member's active-generation runtime is bound to, or
+     * undefined when no live runtime serves the member (the broker's
+     * same-model no-op check).
+     */
+    memberRuntimeModel(childSessionId) {
+        return this.active?.runtimeModel(childSessionId);
+    }
+    /**
+     * Whether the active generation hosts (or is spawning) the member's
+     * runtime — the broker's retire decision needs this apart from the bound
+     * model, since a runtime that bound NO model reports undefined either way.
+     */
+    memberHasRuntime(childSessionId) {
+        return this.active?.hasRuntime(childSessionId) ?? false;
+    }
+    memberRuntimeConfiguration(childSessionId) {
+        for (const driver of [this.active, ...this.draining]) {
+            const configuration = driver?.runtimeConfiguration(childSessionId);
+            if (configuration !== undefined)
+                return configuration;
+        }
+        return undefined;
+    }
+    /** Plugin 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/member-bridge-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Kimi scoped-home MCP config injection for the member bridge. Kimi declares
+ * stdio MCP servers in `$KIMI_CODE_HOME/mcp.json` (`mcpServers` map); the file
+ * is read once per CLI session start, and edits never interrupt an open
+ * session — so the family writes one entry PER RUN (keyed by the run's token
+ * suffix, keeping concurrent delegations of the same scoped home race-free),
+ * prunes it when the run settles, and drops stale family entries (crashed
+ * host) on every write. User-declared servers are preserved verbatim.
+ * @module @khorsheed/dsh-local-agent-kimi/member-bridge-config
+ */
+/** Server-key prefix marking the family's per-run bridge entries. */
+export declare const MEMBER_BRIDGE_SERVER_PREFIX = "dsh-member-";
+/**
+ * The per-run MCP server key. The run's token suffix keeps concurrent runs
+ * distinct; each `kimi -p` round is a fresh CLI session, so per-run (rather
+ * than per-member) naming costs nothing.
+ * @param token - the run's member-channel token.
+ * @returns the mcp.json server key.
+ */
+export declare function memberBridgeServerKey(token: string): string;
+/**
+ * Declare the member bridge for one run: set the per-run server entry and
+ * prune other family entries (settled or crashed runs — an open session's
+ * already-registered server is unaffected, per kimi's mid-session semantics).
+ * Synchronous read-modify-write: single-process callers race-free by event
+ * loop; the file is small and written once per run.
+ * @param homeDir - the kimi scoped home.
+ * @param key - this run's server key ({@link memberBridgeServerKey}).
+ * @param command - the bridge spawn command (`node` + entry path).
+ * @param env - the bridge environment (socket path + per-run token).
+ */
+export declare function injectMemberBridge(homeDir: string, key: string, command: {
+    command: string;
+    args: string[];
+}, env: Record<string, string>): void;
+/**
+ * Remove one run's bridge entry (settle path). Absent entries and a missing
+ * config are no-ops.
+ * @param homeDir - the kimi scoped home.
+ * @param key - the run's server key.
+ */
+export declare function removeMemberBridge(homeDir: string, key: string): void;
+//# sourceMappingURL=member-bridge-config.d.ts.map

package/lib/types/member-bridge-config.js

@@ -0,0 +1,80 @@
+/**
+ * Kimi scoped-home MCP config injection for the member bridge. Kimi declares
+ * stdio MCP servers in `$KIMI_CODE_HOME/mcp.json` (`mcpServers` map); the file
+ * is read once per CLI session start, and edits never interrupt an open
+ * session — so the family writes one entry PER RUN (keyed by the run's token
+ * suffix, keeping concurrent delegations of the same scoped home race-free),
+ * prunes it when the run settles, and drops stale family entries (crashed
+ * host) on every write. User-declared servers are preserved verbatim.
+ * @module @khorsheed/dsh-local-agent-kimi/member-bridge-config
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Kimi's user-level MCP config filename inside the scoped home. */
+const MCP_CONFIG_FILENAME = 'mcp.json';
+/** Server-key prefix marking the family's per-run bridge entries. */
+export const MEMBER_BRIDGE_SERVER_PREFIX = 'dsh-member-';
+/**
+ * The per-run MCP server key. The run's token suffix keeps concurrent runs
+ * distinct; each `kimi -p` round is a fresh CLI session, so per-run (rather
+ * than per-member) naming costs nothing.
+ * @param token - the run's member-channel token.
+ * @returns the mcp.json server key.
+ */
+export function memberBridgeServerKey(token) {
+    return `${MEMBER_BRIDGE_SERVER_PREFIX}${token.slice(0, 8)}`;
+}
+/** Read the scoped mcp.json; a missing or malformed file reads as empty. */
+function readMcpConfig(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return {};
+    return parsed;
+}
+/** Write the config back, preserving every non-family key. */
+function writeMcpConfig(file, config) {
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+/**
+ * Declare the member bridge for one run: set the per-run server entry and
+ * prune other family entries (settled or crashed runs — an open session's
+ * already-registered server is unaffected, per kimi's mid-session semantics).
+ * Synchronous read-modify-write: single-process callers race-free by event
+ * loop; the file is small and written once per run.
+ * @param homeDir - the kimi scoped home.
+ * @param key - this run's server key ({@link memberBridgeServerKey}).
+ * @param command - the bridge spawn command (`node` + entry path).
+ * @param env - the bridge environment (socket path + per-run token).
+ */
+export function injectMemberBridge(homeDir, key, command, env) {
+    const file = join(homeDir, MCP_CONFIG_FILENAME);
+    const config = readMcpConfig(file);
+    const servers = { ...(config.mcpServers ?? {}) };
+    for (const name of Object.keys(servers)) {
+        if (name.startsWith(MEMBER_BRIDGE_SERVER_PREFIX) && name !== key)
+            delete servers[name];
+    }
+    servers[key] = { command: command.command, args: command.args, env };
+    writeMcpConfig(file, { ...config, mcpServers: servers });
+}
+/**
+ * Remove one run's bridge entry (settle path). Absent entries and a missing
+ * config are no-ops.
+ * @param homeDir - the kimi scoped home.
+ * @param key - the run's server key.
+ */
+export function removeMemberBridge(homeDir, key) {
+    const file = join(homeDir, MCP_CONFIG_FILENAME);
+    const config = readMcpConfig(file);
+    if (config.mcpServers === undefined || !(key in config.mcpServers))
+        return;
+    const servers = { ...config.mcpServers };
+    delete servers[key];
+    writeMcpConfig(file, { ...config, mcpServers: servers });
+}

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

@@ -0,0 +1,97 @@
+/**
+ * The kimi harness's model broker: the member/harness model surface the
+ * family gateway routes to (`harnessModel` for the settings card,
+ * `memberModel`/`setMemberModel` for the composer picker). Resolution follows
+ * the family's fixed order — the session-level override (the composer's
+ * picker write) first, then the delegation's recorded model, then the
+ * plugin-config `model` key, then the scoped config's own `default_model`,
+ * and last the CLI's built-in default, which names nothing.
+ *
+ * Per-member state is IN MEMORY by design: the session-level override is a
+ * composer gesture that deliberately does not survive a host restart, and the
+ * start-model ledger only mirrors what the delegation records already persist
+ * (the core hands the recorded value back as `delegationModel` on reads).
+ * The spawn side of a switch is lazy: `setMemberModel` retires the member's
+ * resident runtime when its bound model no longer matches, and the member's
+ * next round respawns onto the new model, `session/load`-ing the same CLI
+ * session — the conversation carries over, the process fact changes.
+ * @module @khorsheed/dsh-local-agent-kimi/model-broker
+ */
+import type { MemberConfigurationAdapter } from '@khorsheed/dsh-local-agent';
+import type { LocalAgentMemberBinding } from '@khorsheed/dsh-local-agent/types';
+import type { KimiModelCatalog } from './model-catalog.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import type { LocalAgentModelBroker, LocalAgentModelInfo, LocalAgentModelDirectory } from '@khorsheed/dsh-local-agent/types';
+import type { LiveDriverSwitch } from './live-switch.ts';
+/**
+ * The kimi harness's {@link LocalAgentModelBroker}. Also the provider-facing
+ * member-model ledger: the provider records each delegation's start model
+ * here and reads the session-level override for its exec-path resolution, so
+ * the picker write reaches the very next round on either driver.
+ */
+export declare class KimiModelBroker implements LocalAgentModelBroker {
+    private readonly ctx;
+    private readonly deps;
+    /** Session-level overrides per member (the composer picker's writes). */
+    private readonly overrides;
+    /** Each member's START model — the model its delegation's first round named. */
+    private readonly startModels;
+    /**
+     * @param ctx - plugin context carrying the family registry (the in-flight
+     *   read behind `switchable`).
+     * @param deps - the harness's live readers: the scoped home, the settings
+     *   layer, the card's recent-model memory, the live toggle, and the driver
+     *   switch a switch retires runtimes through.
+     */
+    constructor(ctx: Context, deps: {
+        /** The default scope's scoped home (cliDefault + discovery reads). */
+        homeDir: (childSessionId?: string) => string;
+        catalog?: KimiModelCatalog;
+        /** The plugin-config `model` key, resolved per read. */
+        settingsModel: () => string | undefined;
+        /** The settings card's recently saved identifiers (choices memory). */
+        recentModels: () => readonly string[];
+        /** Whether the live driver is currently on. */
+        isLive: () => boolean;
+        /** The driver generations a model switch retires a member runtime through. */
+        liveSwitch: LiveDriverSwitch;
+    });
+    configurationAdapter(binding: LocalAgentMemberBinding): MemberConfigurationAdapter;
+    modelDirectory(childSessionId?: string, refresh?: boolean): Promise<LocalAgentModelDirectory>;
+    followModelDirectory(childSessionId: string | undefined, signal: AbortSignal): AsyncIterable<LocalAgentModelDirectory>;
+    /**
+     * Record the model a member's delegation STARTED with (the provider's call
+     * site, fresh and resume rounds alike). The live driver's spawn resolver
+     * ranks it between the override and the settings layer.
+     */
+    noteStartModel(childSessionId: string, model: string): void;
+    /**
+     * The member's session-level override, when the composer picker set one —
+     * the exec path's top layer (it outranks even the delegation's recorded
+     * model, so the provider folds it into the requested slot).
+     */
+    overrideFor(childSessionId: string): string | undefined;
+    /**
+     * The member's spawn-binding resolver (the live driver config): override,
+     * then the member's start model, then the settings layer. Undefined writes
+     * nothing — the scoped config's own `default_model` decides, as it always
+     * did.
+     */
+    readonly spawnModel: (childSessionId: string) => string | undefined;
+    /**
+     * Read the model surface. With no member this is the harness default (the
+     * settings card's "what would a round run with"): override and delegation
+     * stay absent by construction.
+     */
+    modelInfo(childSessionId?: string, delegationModel?: string): Promise<LocalAgentModelInfo>;
+    /**
+     * Set (or clear) the member's session-level override. Throws while a round
+     * is in flight for the member — the switch retires the resident runtime,
+     * and retiring mid-round would kill the run. A same-value set (or clearing
+     * an unset override) is a no-op; otherwise a live runtime whose bound model
+     * differs from the new effective model is retired so the next round
+     * respawns onto it, resuming the same CLI session.
+     */
+    setMemberModel(childSessionId: string, model: string | undefined): Promise<void>;
+}
+//# sourceMappingURL=model-broker.d.ts.map

package/lib/types/model-broker.js

@@ -0,0 +1,205 @@
+/**
+ * The kimi harness's model broker: the member/harness model surface the
+ * family gateway routes to (`harnessModel` for the settings card,
+ * `memberModel`/`setMemberModel` for the composer picker). Resolution follows
+ * the family's fixed order — the session-level override (the composer's
+ * picker write) first, then the delegation's recorded model, then the
+ * plugin-config `model` key, then the scoped config's own `default_model`,
+ * and last the CLI's built-in default, which names nothing.
+ *
+ * Per-member state is IN MEMORY by design: the session-level override is a
+ * composer gesture that deliberately does not survive a host restart, and the
+ * start-model ledger only mirrors what the delegation records already persist
+ * (the core hands the recorded value back as `delegationModel` on reads).
+ * The spawn side of a switch is lazy: `setMemberModel` retires the member's
+ * resident runtime when its bound model no longer matches, and the member's
+ * next round respawns onto the new model, `session/load`-ing the same CLI
+ * session — the conversation carries over, the process fact changes.
+ * @module @khorsheed/dsh-local-agent-kimi/model-broker
+ */
+import { extendModelDirectory } from '@khorsheed/dsh-local-agent';
+import { readKimiModelConfiguration } from './model-configuration.js';
+import { listKimiConfigModels, readKimiDefaultModel } from './provision.js';
+/** The refusal a mid-round switch gets (in flight = the runtime must not die). */
+const SWITCH_IN_FLIGHT_REASON = '该成员有进行中的委派轮次，等其完成后再切换模型';
+/** Dedupe a candidate list, dropping blanks and keeping first-seen order. */
+function dedupe(candidates) {
+    const seen = new Set();
+    const out = [];
+    for (const candidate of candidates) {
+        const value = candidate?.trim();
+        if (value === undefined || value === '' || seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+/**
+ * The kimi harness's {@link LocalAgentModelBroker}. Also the provider-facing
+ * member-model ledger: the provider records each delegation's start model
+ * here and reads the session-level override for its exec-path resolution, so
+ * the picker write reaches the very next round on either driver.
+ */
+export class KimiModelBroker {
+    ctx;
+    deps;
+    /** Session-level overrides per member (the composer picker's writes). */
+    overrides = new Map();
+    /** Each member's START model — the model its delegation's first round named. */
+    startModels = new Map();
+    /**
+     * @param ctx - plugin context carrying the family registry (the in-flight
+     *   read behind `switchable`).
+     * @param deps - the harness's live readers: the scoped home, the settings
+     *   layer, the card's recent-model memory, the live toggle, and the driver
+     *   switch a switch retires runtimes through.
+     */
+    constructor(ctx, deps) {
+        this.ctx = ctx;
+        this.deps = deps;
+    }
+    configurationAdapter(binding) {
+        const home = this.ctx.localAgent.homeDir('kimi', binding.scope);
+        const resolve = async (selection) => {
+            const model = selection.model.mode === 'value' ? selection.model.value
+                : (selection.model.mode === 'inherit' ? binding.model : undefined) ?? this.deps.settingsModel() ?? await readKimiDefaultModel(home);
+            const configured = await readKimiModelConfiguration(home, model);
+            const native = this.deps.liveSwitch.memberRuntimeConfiguration(binding.childSessionId);
+            const entry = native?.directory.entries.find(entry => entry.value === model)
+                ?? configured.entries.find(entry => entry.value === model);
+            const effort = (selection.effort.mode === 'value' ? selection.effort.value : selection.effort.mode === 'inherit' ? binding.effort : undefined) ?? configured.effort;
+            if (effort !== undefined && entry?.reasoning !== undefined && !entry.reasoning.options.some(option => option.value === effort)) {
+                throw new Error('Kimi has not advertised this reasoning effort for the selected model');
+            }
+            if (!this.deps.isLive() && effort !== undefined && configured.protocol !== 'kimi') {
+                throw new Error('This model protocol has no Kimi exec effort override; use ACP live mode');
+            }
+            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.liveSwitch.retireMemberRuntime(binding.childSessionId); return resolved; },
+            reconcile: async (state) => {
+                if (this.ctx.localAgent.isDelegationActive(binding.childSessionId))
+                    return { active: true, matches: 'unknown', resolved: {} };
+                await this.deps.liveSwitch.retireMemberRuntime(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(childSessionId);
+        const info = await this.modelInfo(childSessionId);
+        return info.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(childSessionId, signal))
+            yield await this.modelDirectory(childSessionId);
+    }
+    /**
+     * Record the model a member's delegation STARTED with (the provider's call
+     * site, fresh and resume rounds alike). The live driver's spawn resolver
+     * ranks it between the override and the settings layer.
+     */
+    noteStartModel(childSessionId, model) {
+        const value = model.trim();
+        if (value !== '')
+            this.startModels.set(childSessionId, value);
+    }
+    /**
+     * The member's session-level override, when the composer picker set one —
+     * the exec path's top layer (it outranks even the delegation's recorded
+     * model, so the provider folds it into the requested slot).
+     */
+    overrideFor(childSessionId) {
+        return this.overrides.get(childSessionId);
+    }
+    /**
+     * The member's spawn-binding resolver (the live driver config): override,
+     * then the member's start model, then the settings layer. Undefined writes
+     * nothing — the scoped config's own `default_model` decides, as it always
+     * did.
+     */
+    spawnModel = (childSessionId) => this.overrideFor(childSessionId)
+        ?? this.startModels.get(childSessionId)
+        ?? this.deps.settingsModel();
+    /**
+     * Read the model surface. With no member this is the harness default (the
+     * settings card's "what would a round run with"): override and delegation
+     * stay absent by construction.
+     */
+    async modelInfo(childSessionId, delegationModel) {
+        const override = childSessionId === undefined ? undefined : this.overrideFor(childSessionId);
+        const delegation = childSessionId === undefined
+            ? undefined
+            : delegationModel ?? this.startModels.get(childSessionId);
+        const settings = this.deps.settingsModel();
+        const homeDir = this.deps.homeDir(childSessionId);
+        const native = this.deps.catalog?.read(childSessionId);
+        const [cliDefault, discovered] = await Promise.all([
+            readKimiDefaultModel(homeDir).catch(() => undefined),
+            listKimiConfigModels(homeDir).catch(() => []),
+        ]);
+        const choices = dedupe([settings, cliDefault, ...discovered, ...(native?.entries.filter(entry => !entry.hidden).map(entry => entry.value) ?? []), ...this.deps.recentModels()]);
+        const [effective, source] = override !== undefined ? [override, 'override']
+            : delegation !== undefined ? [delegation, 'delegation']
+                : settings !== undefined ? [settings, 'settings']
+                    : cliDefault !== undefined ? [cliDefault, 'cli-config']
+                        : [undefined, 'cli-builtin'];
+        const inFlight = childSessionId !== undefined
+            && this.ctx.localAgent.activeDelegations().includes(childSessionId);
+        return {
+            ...effective === undefined ? {} : { effective },
+            source,
+            ...override === undefined ? {} : { override },
+            ...delegation === undefined ? {} : { delegation },
+            ...settings === undefined ? {} : { settings },
+            ...cliDefault === undefined ? {} : { cliDefault },
+            choices,
+            ...native === undefined ? {} : { directory: extendModelDirectory(native, [settings, cliDefault, ...discovered], this.deps.recentModels()) },
+            live: this.deps.isLive(),
+            switchable: !inFlight,
+            ...inFlight ? { reason: SWITCH_IN_FLIGHT_REASON } : {},
+        };
+    }
+    /**
+     * Set (or clear) the member's session-level override. Throws while a round
+     * is in flight for the member — the switch retires the resident runtime,
+     * and retiring mid-round would kill the run. A same-value set (or clearing
+     * an unset override) is a no-op; otherwise a live runtime whose bound model
+     * differs from the new effective model is retired so the next round
+     * respawns onto it, resuming the same CLI session.
+     */
+    async setMemberModel(childSessionId, model) {
+        if (typeof this.ctx.localAgent.setMemberModel === 'function')
+            return this.ctx.localAgent.setMemberModel(childSessionId, model);
+        if (this.ctx.localAgent.activeDelegations().includes(childSessionId)) {
+            throw new Error(SWITCH_IN_FLIGHT_REASON);
+        }
+        const value = model?.trim();
+        const previous = this.overrides.get(childSessionId);
+        if (value === undefined || value === '') {
+            if (previous === undefined)
+                return;
+            this.overrides.delete(childSessionId);
+        }
+        else {
+            if (previous === value)
+                return;
+            this.overrides.set(childSessionId, value);
+        }
+        // Retire only when the runtime's bound model no longer matches what the
+        // member's next round resolves to — a same-model switch keeps the process.
+        const effective = (await this.modelInfo(childSessionId)).effective;
+        if (this.deps.liveSwitch.memberHasRuntime(childSessionId)
+            && this.deps.liveSwitch.memberRuntimeModel(childSessionId) !== effective) {
+            await this.deps.liveSwitch.retireMemberRuntime(childSessionId);
+        }
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { LocalAgentModelDirectory, LocalAgentModelDirectoryData } from '@khorsheed/dsh-local-agent/types';
+export interface KimiNativeConfiguration {
+    directory: LocalAgentModelDirectoryData;
+    modelConfigId?: string;
+    effortConfigId?: string;
+    currentModel?: string;
+    currentEffort?: string;
+}
+/** ACP v1 configOptions are authoritative; old models metadata is a read-only fallback. */
+export declare function kimiNativeConfiguration(value: unknown): KimiNativeConfiguration | undefined;
+/** Reads configuration before a session exists; never starts a disposable ACP session. */
+export declare class KimiModelCatalog {
+    private readonly context;
+    private readonly cache;
+    constructor(context: (childSessionId?: string) => {
+        homeDir: string;
+        cwd?: string;
+        native?: KimiNativeConfiguration;
+    });
+    private key;
+    read(childSessionId?: string): LocalAgentModelDirectory;
+    refresh(childSessionId?: string): Promise<LocalAgentModelDirectory>;
+    follow(childSessionId: string | undefined, signal: AbortSignal): AsyncIterable<LocalAgentModelDirectory>;
+    dispose(): void;
+}
+//# sourceMappingURL=model-catalog.d.ts.map