@khorsheed/dsh-local-agent-dsh 0.2.0-rc.1 → 0.2.0

package/lib/types/index.js

@@ -4,7 +4,7 @@
  * namespace (default off); while ON, the controller registers the `dsh`
  * harness into the core registry (scoped home under the shared homes root,
  * `$DSH_HOME`), the `dsh-cli` delegation provider (sub-dsh headless runs with
- * the parent's resolved DeepSeek key), and the family delegation tool for it.
+ * the parent's selected API-key model route), and the family delegation tool for it.
  * While OFF — the default — nothing model-visible mounts, so the instance
  * keeps exactly the current behavior (official in-process subagent tools) and
  * the model never sees two overlapping delegation tools at once.
@@ -22,18 +22,19 @@
  *
  * @module @khorsheed/dsh-local-agent-dsh
  */
-import { join } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import z from '@deepseek-ai/schemastery';
-import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { settingsFace, vol } from '@khorsheed/dsh-local-agent';
 import { mountSubagentDelegationTool } from '@khorsheed/dsh-local-agent/tool-factory';
 import { CONTAINER_NODE_OPTIONS, DshCliProvider, dshCliVersion } from './dsh-cli-provider.js';
 import { DEFAULT_LIVE_IDLE_MS } from './live-driver.js';
 import { LiveDriverSwitch } from './live-switch.js';
 import { DshModelCatalog } from './model-catalog.js';
+import { canInheritModelProvider, localModelLaunch } from './model-launch.js';
 import { DshModelBroker } from './model-broker.js';
 import { listDshSessions } from './records.js';
-import { defaultPresetRoot, DEFAULT_SUB_PROFILE_NAME, provisionDshScope, USER_PRESET_DIR } from './provision.js';
+import { DEFAULT_SUB_PROFILE_NAME, provisionDshScope } from './provision.js';
 /** Stable Cordis plugin name; the bundle patch row id. */
 export const name = 'local-agent-dsh';
 /** Services required before the toggle controller can mount. */
@@ -69,9 +70,10 @@ function volatilize(field) {
 }
 export const Config = z.object({
     profileName: z.string().default(DEFAULT_SUB_PROFILE_NAME),
-    apiKeyRef: z.string().default('DEEPSEEK_API_KEY'),
+    apiKeyRef: z.string(),
     cliLaunch: z.array(z.string()),
     headlessBundleDir: z.string(),
+    unitHeadlessBundleDir: z.string(),
     permissions: z.union([z.const('read-only'), z.const('workspace-write'), z.const('danger-full-access')]),
     model: volatilize(SETTINGS_FIELDS.model),
     live: volatilize(SETTINGS_FIELDS.live),
@@ -100,8 +102,8 @@ const DSH_TOOL_NAME = 'subagent_dsh';
 /**
  * This package's own name, passed to the family tool factory as the
  * tool-origin owner (AGENTS.md § Tool origin tagging — a shared factory never
- * hardcodes an owner). Duplicated from src/invariant.ts, the same pattern the
- * worktrees/room `./tool` entries use.
+ * hardcodes an owner), the same pattern the worktrees/room `./tool` entries
+ * use.
  */
 const PACKAGE_NAME = '@khorsheed/dsh-local-agent-dsh';
 /**
@@ -116,10 +118,6 @@ const dshSubagentTool = {
         mountSubagentDelegationTool(toolCtx, { provider: 'dsh-cli', toolName: DSH_TOOL_NAME }, PACKAGE_NAME);
     },
 };
-/** Resolve the sub-dsh credential or report unconfigured. */
-async function resolveApiKey(ctx, config) {
-    return ctx.credentials.resolve(credentialRef(config.apiKeyRef ?? 'DEEPSEEK_API_KEY'));
-}
 /**
  * Mount the toggle controller: register the settings namespace, then mirror
  * its value into harness/provider/tool registrations, live.
@@ -181,6 +179,7 @@ export function apply(ctx, config) {
         const modelCatalog = new DshModelCatalog({
             llm: () => ctx.get('llm'),
             defaultModel: hostDefaultModel,
+            canInheritProvider: provider => canInheritModelProvider(ctx, provider),
         });
         void modelCatalog.read();
         ctx.on('llm/adapters-updated', () => { modelCatalog.invalidate(); });
@@ -207,14 +206,28 @@ export function apply(ctx, config) {
             retireRuntime: childSessionId => currentLiveSwitch?.retireRuntime(childSessionId) ?? Promise.resolve(),
         });
         /**
-         * This deployment's preset root — where a person or a pack installed the
-         * presets this instance offers, and the SOURCE every scope's own copy is
-         * taken from. Derived the way the roster derives it, from the settings
-         * service's harness home when there is one.
+         * This instance's own profile directory — the loader's `baseUrl`, which
+         * the host sets to the directory holding the profile's `cordis.yml`. Its
+         * direct dependencies are where an installed preset package is found, and
+         * the SOURCE every scope's own copy is taken from (the same package this
+         * instance's capability catalog measures). Undefined when the loader
+         * exposes no file URL, which leaves a scope able to keep the copy it has
+         * but unable to take a new one.
          */
-        const instancePresetRoot = () => {
-            const home = ctx.get?.('settings')?.home;
-            return home === undefined ? defaultPresetRoot() : join(home, USER_PRESET_DIR);
+        const instanceProfileDir = () => {
+            const baseUrl = ctx.baseUrl;
+            if (typeof baseUrl !== 'string' || !baseUrl.startsWith('file:'))
+                return undefined;
+            try {
+                return dirname(fileURLToPath(new URL('./package.json', baseUrl)));
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const profileDirOption = () => {
+            const dir = instanceProfileDir();
+            return dir === undefined ? {} : { instanceProfileDir: dir };
         };
         const harness = {
             prepareMember: async ({ binding, childSession, configuration, signal }) => {
@@ -242,7 +255,7 @@ export function apply(ctx, config) {
             provision: (scopedHome, options) => {
                 const provisioned = provisionDshScope(scopedHome, config, {
                     ...(options?.preset === undefined ? {} : { preset: options.preset }),
-                    presetRoot: instancePresetRoot(),
+                    ...(profileDirOption()),
                 });
                 return {
                     ...(provisioned.preset === undefined ? {} : { preset: provisioned.preset }),
@@ -251,7 +264,8 @@ export function apply(ctx, config) {
             },
             isAuthenticated: async () => {
                 try {
-                    return (await resolveApiKey(ctx, config)) !== undefined;
+                    await localModelLaunch(ctx, config, resolveModel() ?? hostDefaultModel());
+                    return true;
                 }
                 catch {
                     return false;
@@ -318,7 +332,7 @@ export function apply(ctx, config) {
             if (!enabled)
                 return;
             // Idempotent: heals a deleted or drifted sub-profile before each round.
-            provisionDshScope(homeDir, config, { presetRoot: instancePresetRoot() });
+            provisionDshScope(homeDir, config, profileDirOption());
             disposers.push(ctx.localAgent.register(harness));
             // The live driver is settings-driven WITHIN this enabled generation:
             // the card's toggle (user layer over the YAML composition base) swaps

package/lib/types/live-driver.js

@@ -19,13 +19,16 @@
  * @module @khorsheed/dsh-local-agent-dsh/live-driver
  */
 import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
 import { BlockAssembler, createAssistantMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
 import { settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { delegationEnv, persistChildSession, LiveStreamPublisher, LiveFlush } from '@khorsheed/dsh-local-agent';
 import { LIVE_SERVER_NAME, LIVE_WIRE_PROTOCOL_VERSION, } from '@khorsheed/dsh-local-agent-dsh-headless/wire';
-import { DEFAULT_DISPOSE_GRACE_MS, dshLaunchArgv, dshTextTask, registerMemberRun, resolveApiKey, } from './dsh-cli-provider.js';
+import { DEFAULT_DISPOSE_GRACE_MS, dshLaunchArgv, dshTextTask, registerMemberRun, } from './dsh-cli-provider.js';
+import { localModelLaunch } from './model-launch.js';
 import { DEFAULT_SUB_PROFILE_NAME, provisionDshScope } from './provision.js';
-import { mirrorDshLiveEvent, mirrorDshSession } from './session-mirror.js';
+import { mirrorDshLiveEvent, mirrorDshSession, closeMirroredOpenStep, mirroredOpenStep } from './session-mirror.js';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export const DEFAULT_LIVE_IDLE_MS = 30 * 60_000;
 /** Default timeout for a wire request acknowledgement. */
@@ -77,6 +80,7 @@ class LiveRuntime {
      * spawned with no model flag at all. A round whose start model differs
      * retires the runtime instead of silently running the old one.
      */
+    modelLaunchFingerprint;
     configurationKey;
     boundModel;
     reclaimed = false;
@@ -361,7 +365,7 @@ export class DshLiveDriver {
      * The member's live runtime, spawning it (once per member at a time) when
      * absent or dead. `signal` abandons the spawn on cancellation.
      */
-    async ensureRuntime(spec, apiKey, signal) {
+    async ensureRuntime(spec, launch, signal) {
         const key = spec.sessionId;
         const startModel = spec.startModel?.trim();
         const existing = this.runtimes.get(key);
@@ -370,7 +374,8 @@ export class DshLiveDriver {
             // to a different one: retire so the respawn binds the asked-for model
             // (the sub-dsh session resumes from disk — only the process is
             // replaced).
-            if ((spec.configuration !== undefined && existing.configurationKey !== JSON.stringify(spec.configuration))
+            if (existing.modelLaunchFingerprint !== launch.fingerprint
+                || (spec.configuration !== undefined && existing.configurationKey !== JSON.stringify(spec.configuration))
                 || (spec.configuration === undefined && existing.configurationKey !== undefined)
                 || (startModel !== undefined && startModel !== '' && existing.boundModel !== startModel)) {
                 await this.reclaim(key);
@@ -386,7 +391,7 @@ export class DshLiveDriver {
         const pending = this.ensuring.get(key);
         if (pending !== undefined)
             return pending;
-        const spawn = this.spawnRuntime(spec, apiKey, signal)
+        const spawn = this.spawnRuntime(spec, launch, signal)
             .finally(() => { this.ensuring.delete(key); });
         this.ensuring.set(key, spawn);
         return spawn;
@@ -399,7 +404,7 @@ export class DshLiveDriver {
      * cancellation mid-spawn reclaims the half-started runtime and throws the
      * abort instead, without touching the breaker.
      */
-    async spawnRuntime(spec, apiKey, signal) {
+    async spawnRuntime(spec, launch, signal) {
         const key = spec.sessionId;
         if (this.disposed) {
             throw new LiveChannelUnavailableError('the live driver is disposed');
@@ -434,7 +439,7 @@ export class DshLiveDriver {
             // and the DSH_* facts survive the shared scrub only here.
             env: delegationEnv({
                 DSH_HOME: spec.homeDir,
-                DEEPSEEK_API_KEY: apiKey,
+                ...launch.env,
                 // Same tsx tsconfig carry-over as the exec path (see startDshCliRun).
                 ...process.env.TSX_TSCONFIG_PATH === undefined
                     ? {}
@@ -455,6 +460,7 @@ export class DshLiveDriver {
         // A blank resolution binds no model at all — record exactly what the argv
         // carries so a later start-model comparison never retires needlessly.
         runtime.boundModel = model === undefined || model === '' ? undefined : model;
+        runtime.modelLaunchFingerprint = launch.fingerprint;
         runtime.configurationKey = spec.configuration === undefined ? undefined : JSON.stringify(spec.configuration);
         runtime.onDead = () => {
             // Delete only OUR registration: a crash-then-respawn can interleave so
@@ -523,9 +529,9 @@ export class DshLiveDriver {
         if (this.draining || this.disabled)
             throw new LiveChannelUnavailableError('the live driver is unavailable for preparation');
         try {
-            provisionDshScope(spec.homeDir, this.config);
-            const apiKey = await resolveApiKey(this.ctx, this.config);
-            const runtime = await this.ensureRuntime(spec, apiKey, signal);
+            provisionDshScope(spec.homeDir, { ...this.config, inheritModelConfiguration: true });
+            const launch = await localModelLaunch(this.ctx, this.config, spec.configuration?.model ?? spec.startModel ?? this.config.modelFor?.(spec.sessionId));
+            const runtime = await this.ensureRuntime(spec, launch, signal);
             await runtime.request('session/prepare', { sessionId: spec.sessionId, resume: spec.resume !== undefined });
             signal.throwIfAborted();
             this.armIdleTimer(spec.sessionId);
@@ -674,6 +680,7 @@ export class DshLiveDriver {
                     acceptStream(entry.frame);
             }
         };
+        let nativeFailure;
         let resolveIdle;
         const idle = new Promise((resolve) => { resolveIdle = resolve; });
         const installHandlers = (rt) => {
@@ -705,10 +712,10 @@ export class DshLiveDriver {
             };
         };
         // Provisioning is idempotent; re-running heals a drifted sub-profile.
-        provisionDshScope(spec.homeDir, this.config);
-        const apiKey = await resolveApiKey(this.ctx, this.config);
+        provisionDshScope(spec.homeDir, { ...this.config, inheritModelConfiguration: true });
+        const launch = await localModelLaunch(this.ctx, this.config, spec.configuration?.model ?? spec.startModel ?? this.config.modelFor?.(spec.sessionId));
         const accepted = (async () => {
-            const rt = await this.ensureRuntime(spec, apiKey, request.signal);
+            const rt = await this.ensureRuntime(spec, launch, request.signal);
             runtime = rt;
             if (runAbort.signal.aborted) {
                 // Cancelled while the runtime came up and no turn exists sub-side: the
@@ -751,6 +758,7 @@ export class DshLiveDriver {
                 return { output: collectOutput(), stopReason: 'aborted' };
             }
             if (reason?.kind === 'error') {
+                nativeFailure = { message: reason.error.message, code: reason.error.code };
                 throw new Error(`subagent-dsh live: the turn failed: ${reason.error.message}`);
             }
             if (reason?.kind !== 'completed') {
@@ -777,7 +785,13 @@ export class DshLiveDriver {
         }).then(async (settled) => {
             roundSettled = true;
             liveFlush.dispose();
-            if (turnOpened && streaming !== undefined && streamPublisher !== undefined) {
+            // The interrupted stream's partial content folds durably only while its
+            // step is still OPEN: a graceful sub-dsh unwind writes its own
+            // interrupted assistant/message and step/end (both crossed the wire),
+            // and an append at the closed step would fail the released-log reader.
+            const openStep = turnOpened ? mirroredOpenStep(childSession) : undefined;
+            if (turnOpened && streaming !== undefined && streamPublisher !== undefined
+                && openStep !== undefined && openStep.step === streaming.step) {
                 const blocks = streaming.assembler.interruptedBlocks();
                 if (blocks.length > 0) {
                     childSession.append('assistant/message', {
@@ -790,22 +804,6 @@ export class DshLiveDriver {
                 }
             }
             streamPublisher?.dispose();
-            // Identical turn/end bookkeeping to the exec path — but only for a turn
-            // that actually opened (a pre-accept cancel records no turn at all).
-            if (turnOpened) {
-                if (settled.stopReason === 'completed') {
-                    childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
-                }
-                else if (settled.stopReason === 'aborted') {
-                    childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
-                }
-                else {
-                    childSession.append('turn/end', {
-                        turn,
-                        reason: { kind: 'error', error: { message: 'the live round did not complete', code: 'UNKNOWN' } },
-                    });
-                }
-            }
             // Settlement clears the round's handlers: a late notification drops at
             // the runtime frame instead of landing in a dead closure.
             if (runtime !== undefined) {
@@ -813,24 +811,18 @@ export class DshLiveDriver {
                 runtime.onEvent = undefined;
                 runtime.onIdle = undefined;
             }
-            // A completed answer is not a durable turn until its final boundary
-            // and any closing stream checkpoints have reached the child store.
             if (turnOpened) {
-                persist();
-                await persistQueue;
-            }
-            return settled;
-        });
-        // Settle reconciliation: the file-based mirror pass (the serve side flushed
-        // before its idle notification) dedupes against the live-mirrored prefix
-        // and catches anything the wire dropped; the final mirror progress report
-        // is authoritative, exactly as in the exec path. Then re-arm the reaper. A
-        // round that never opened owns no span — skip the pass entirely (it would
-        // re-scan the previous round or, under exec fallback, fight its polling).
-        void result.then(async () => {
-            try {
-                if (turnOpened) {
-                    await persistQueue;
+                // Settle reconciliation IN-CHAIN: the file-based mirror pass (the serve
+                // side flushed before its idle notification) dedupes against the
+                // live-mirrored prefix and catches anything the wire dropped; the
+                // final mirror progress report is authoritative, exactly as in the
+                // exec path. It runs before turn/end so every mirrored event lands
+                // inside the turn window — the released-log reader rejects content
+                // outside an open turn on every cold read — and inside the result
+                // chain so the round serializer (and a resume round's turn/start)
+                // never overtakes the boundary. A mirror fault degrades to a warn;
+                // the boundary still closes.
+                try {
                     if (mirroredMessages > 0)
                         persist();
                     await persistQueue.catch(() => { });
@@ -855,13 +847,35 @@ export class DshLiveDriver {
                         registry?.recordRoundSettled?.(childSession.id, round);
                     }
                 }
+                catch (error) {
+                    this.ctx.logger.warn(`subagent-dsh: live settle mirror failed: ${thrown(error).message}`);
+                }
+                // The copied tail's open step (an interrupted round leaves it open —
+                // the reader rejects a turn/end over it) receives its closure first.
+                closeMirroredOpenStep(childSession);
+                // Identical turn/end bookkeeping to the exec path — a completed,
+                // interrupted, or failed round each closes its window.
+                if (settled.stopReason === 'completed') {
+                    childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+                }
+                else if (settled.stopReason === 'aborted') {
+                    childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+                }
+                else {
+                    childSession.append('turn/end', {
+                        turn,
+                        reason: { kind: 'error', error: nativeFailure ?? { message: 'the live round did not complete', code: 'UNKNOWN' } },
+                    });
+                }
+                // A completed answer is not a durable turn until its final boundary
+                // and any closing stream checkpoints have reached the child store.
+                persist();
+                await persistQueue;
             }
-            catch (error) {
-                this.ctx.logger.warn(`subagent-dsh: live settle mirror failed: ${thrown(error).message}`);
-            }
-            finally {
-                this.armIdleTimer(spec.sessionId);
-            }
+            // Re-arm the idle reaper for every settled round — including one that
+            // never opened its turn (the runtime is up and must not leak).
+            this.armIdleTimer(spec.sessionId);
+            return settled;
         });
         // Publication gate: hold start() until the turn is accepted (channel
         // errors still throw for the provider's exec fallback), but NEVER hold it
@@ -869,7 +883,11 @@ export class DshLiveDriver {
         // the result settles aborted.
         await Promise.race([accepted, abortBranch.catch(() => undefined)]);
         return subprocessRunHandle({
-            id: childSession.id,
+            // Host 0.2.1: a fresh PER-EXECUTION run id — the activation manager
+            // rejects a run id naming a live Session (this child session is live),
+            // and resume rounds reuse the child session id. The family's durable
+            // tracking key (the child session id) rides the staged intent instead.
+            id: SessionId(randomUUID()),
             result,
             signal: request.signal,
             onAbort,

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

@@ -15,6 +15,7 @@ export declare class DshModelCatalog {
         llm: () => DshModelDirectoryFace | undefined;
         defaultModel: () => string | undefined;
         timeoutMs?: number;
+        canInheritProvider?: (provider: string) => boolean;
     });
     private key;
     read(): LocalAgentModelDirectory;

package/lib/types/model-catalog.js

@@ -39,7 +39,8 @@ export class DshModelCatalog {
         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 allProviders = llm.listProviders();
+        const providers = allProviders.filter(provider => this.deps.canInheritProvider?.(provider.id) ?? true);
         const groups = await Promise.allSettled(providers.map(async (provider) => Promise.all((await llm.listModels(provider.id)).map(async (model) => {
             let resolved;
             try {
@@ -62,10 +63,14 @@ export class DshModelCatalog {
             throw new Error('DSH adapters could not list models');
         const entries = groups.flatMap(group => group.status === 'fulfilled' ? group.value : []);
         const defaultModel = this.deps.defaultModel();
+        const omitted = allProviders.length - providers.length;
         return {
-            entries, complete: failed === 0, customInput: true,
-            ...defaultModel === undefined ? {} : { defaultModel },
-            ...failed === 0 ? {} : { reason: `${failed} adapter model list(s) unavailable` },
+            entries, complete: failed === 0 && providers.length === allProviders.length, customInput: true,
+            ...defaultModel === undefined || !entries.some(entry => entry.value === defaultModel) ? {} : { defaultModel },
+            ...(failed === 0 && omitted === 0) ? {} : { reason: [
+                    ...(failed === 0 ? [] : [`${failed} adapter model list(s) unavailable`]),
+                    ...(omitted === 0 ? [] : [`${omitted} provider(s) do not support local API-key inheritance`]),
+                ].join('; ') },
         };
     }
 }

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

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { LocalAgentDshConfig } from './index.ts';
+/** Private launch environment: never persisted in a profile, transcript or argv. */
+export declare const MODEL_CONFIG_ENV = "DSH_LOCAL_AGENT_MODEL_CONFIG";
+/** Whether this provider has a supported local configuration transfer contract. */
+export declare function canInheritModelProvider(ctx: Context, provider: string): boolean;
+export interface LocalModelLaunch {
+    readonly env: Record<string, string>;
+    /** In-memory fingerprint also retires a resident process after endpoint/key changes. */
+    readonly fingerprint: string;
+}
+/** Snapshot only the selected local route and resolve only its explicitly named credential. */
+export declare function localModelLaunch(ctx: Context, config: LocalAgentDshConfig, model?: string): Promise<LocalModelLaunch>;
+//# sourceMappingURL=model-launch.d.ts.map

package/lib/types/model-launch.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+/** Private launch environment: never persisted in a profile, transcript or argv. */
+export const MODEL_CONFIG_ENV = 'DSH_LOCAL_AGENT_MODEL_CONFIG';
+const MODEL_KEY_ENV = 'DSH_LOCAL_AGENT_MODEL_API_KEY';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function settings(ctx) {
+    return new Map((ctx.get('settings')?.describe?.() ?? []).flatMap(row => {
+        const value = object(row.value);
+        return value === undefined ? [] : [[String(row.ns), value]];
+    }));
+}
+function piProfile(ctx, provider, values) {
+    const directory = ctx.get('llm')?.listConfigurableProviders?.().find(row => row.provider === provider);
+    // Only the official pi-ai providers dictionary has this inheritance contract.
+    // Other adapter families must explicitly provide a transport before being advertised.
+    const ns = directory?.settingsNs ?? 'llm-pi-ai';
+    if (ns !== 'llm-pi-ai')
+        return undefined;
+    if (directory && (directory.settingsPath.length !== 2 || directory.settingsPath[0] !== 'providers' || directory.settingsPath[1] !== provider))
+        return undefined;
+    return object(object(values.get(ns)?.providers)?.[provider]);
+}
+/** Whether this provider has a supported local configuration transfer contract. */
+export function canInheritModelProvider(ctx, provider) {
+    if (provider === 'deepseek-official')
+        return true;
+    const profile = piProfile(ctx, provider, settings(ctx));
+    return typeof profile?.apiKeyEnv === 'string' && profile.apiKeyEnv.trim() !== '';
+}
+/** Snapshot only the selected local route and resolve only its explicitly named credential. */
+export async function localModelLaunch(ctx, config, model) {
+    const provider = model?.includes('/') ? model.slice(0, model.indexOf('/')) : 'deepseek-official';
+    const values = settings(ctx);
+    let inherited, ref, keyName;
+    if (provider === 'deepseek-official') {
+        const profile = structuredClone(values.get('llm-deepseek') ?? {});
+        ref = config.apiKeyRef ?? (typeof profile.apiKeyEnv === 'string' ? profile.apiKeyEnv : 'DEEPSEEK_API_KEY');
+        inherited = { deepseek: { ...profile, apiKeyEnv: 'DEEPSEEK_API_KEY' } };
+        keyName = 'DEEPSEEK_API_KEY';
+    }
+    else {
+        const profile = piProfile(ctx, provider, values);
+        if (typeof profile?.apiKeyEnv !== 'string' || profile.apiKeyEnv.trim() === '') {
+            throw new Error(`subagent-dsh: model provider "${provider}" has no inheritable API-key route; configure its credential reference in the host Models settings`);
+        }
+        ref = profile.apiKeyEnv;
+        inherited = { piAi: { providers: { [provider]: { ...structuredClone(profile), apiKeyEnv: MODEL_KEY_ENV } } } };
+        keyName = MODEL_KEY_ENV;
+    }
+    const credential = await ctx.get('credentials')?.resolve(credentialRef(ref));
+    if (!credential?.value)
+        throw new Error(`subagent-dsh: credential ${ref} is unavailable for model provider "${provider}"`);
+    const env = { [MODEL_CONFIG_ENV]: JSON.stringify(inherited), [keyName]: credential.value };
+    return { env, fingerprint: createHash('sha256').update(JSON.stringify(env)).digest('hex') };
+}