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

package/lib/types/kimi-cli-provider.js

@@ -10,13 +10,13 @@
  */
 import { randomUUID } from 'node:crypto';
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { NO_START_CAPABILITIES, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
-import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel, containerExecSpawn, containerScopedHome, delegationEnv, establishSubagentCatalogChild, probeCliVersion, resolveChildCwd, subagentDelegationLabel, } from '@khorsheed/dsh-local-agent';
+import { NO_START_CAPABILITIES, SUBAGENT_DESCRIPTOR_VERSION, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
+import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel, containerExecSpawn, containerScopedHome, delegationEnv, establishSubagentCatalogChild, persistChildSession, probeCliVersion, resolveChildCwd, subagentDelegationLabel, } from '@khorsheed/dsh-local-agent';
 import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from '@khorsheed/dsh-local-agent/types';
 import { LiveChannelUnavailableError } from './live-driver.js';
-import { guardKimiCredential } from './credential-guard.js';
 import { injectMemberBridge, memberBridgeServerKey, removeMemberBridge } from './member-bridge-config.js';
-import { readKimiBaseUrl } from './provision.js';
+import { ensureKimiEndpointProvider, KIMI_MANAGED_BASE_URL, readKimiBaseUrl } from './provision.js';
+import { endpointAuthEnv, hasEndpointCredential } from './endpoint-auth.js';
 import { kimiExecConfiguration } from './model-configuration.js';
 import { addTokenUsage } from './session-view.js';
 import { mirrorKimiSessionDelta } from './session-mirror.js';
@@ -81,6 +81,7 @@ export class KimiCliProvider {
     live;
     model;
     memberModels;
+    endpoint;
     name = 'kimi-cli';
     capabilities = NO_START_CAPABILITIES;
     inheritsParentContext = false;
@@ -91,19 +92,43 @@ export class KimiCliProvider {
      *   while a retiring generation still hosts it).
      * @param model - resolver for the configured model, read PER ROUND so a
      *   settings-card write takes effect on the next delegation without a
-     *   reload. Undefined (the resolver absent, or returning undefined) leaves
-     *   the argv exactly as it was before the key rode every round — the scoped
-     *   config.toml's `default_model` then decides, as it always did.
+     *   reload; it receives the round's scope (a named scope's curated list
+     *   answers first). Undefined (the resolver absent, or returning
+     *   undefined) leaves the argv exactly as it was before the key rode every
+     *   round — the scoped config.toml's `default_model` then decides, as it
+     *   always did.
      * @param memberModels - the broker's member-model ledger: the provider
      *   records each delegation's start model here (the live driver's spawn
      *   resolver binds it) and reads the session-level override as the exec
      *   path's top layer. Absent (older wiring), both drop out.
      */
-    constructor(ctx, live, model, memberModels) {
+    constructor(ctx, live, model, memberModels, 
+    /**
+     * Resolver for the scope's endpoint credential, read PER ROUND so a
+     * settings-card write takes effect on the next delegation without a
+     * reload. A resolution carrying a key authenticates the round through the
+     * managed provider's `api_key_env` indirection (the key rides the child
+     * process's environment); the same resolution's baseUrl is pinned onto
+     * the managed provider by the pre-spawn config surgery.
+     */
+    endpoint) {
         this.ctx = ctx;
         this.live = live;
         this.model = model;
         this.memberModels = memberModels;
+        this.endpoint = endpoint;
+    }
+    /**
+     * Resolve the scope's endpoint for this round and land its baseUrl on the
+     * managed provider (the surgery writes only on drift), so a hand-edited
+     * endpoint-auth.json applies without a restart.
+     */
+    async prepareEndpoint(homeDir) {
+        if (this.endpoint === undefined)
+            return undefined;
+        const endpoint = await this.endpoint(homeDir).catch(() => undefined);
+        await ensureKimiEndpointProvider(homeDir, hasEndpointCredential(endpoint) ? endpoint.baseUrl ?? KIMI_MANAGED_BASE_URL : undefined).catch(() => false);
+        return endpoint;
     }
     /** Resolve the live driver for one round's member, if live is on for it. */
     liveDriver(childSessionId) {
@@ -200,7 +225,7 @@ export class KimiCliProvider {
                 ...record?.configurationLock === undefined ? {} : { configurationLock: record.configurationLock },
             }, configuration => this.startKimiResume(request, intent, cwd, homeDir, exec, scope, record?.model, configuration), request.signal, intent?.onAdmitted);
         }
-        const childSessionId = SessionId(intent?.preparedMemberId ?? randomUUID());
+        const childSessionId = SessionId(intent?.preparedMemberId ?? intent?.childSessionId ?? randomUUID());
         if (typeof this.ctx.localAgent.withMemberConfigurationRound !== 'function') {
             if (intent?.effort !== undefined)
                 throw new Error('Kimi effort requires the configuration admission core');
@@ -234,20 +259,25 @@ export class KimiCliProvider {
                     delegationDepth: (request.parent.session.header.delegationDepth ?? 0) + 1,
                 },
             });
-            // The durable one-shot descriptor the runtime resolved marks this child
-            // as session-backed; without it the 子代理 projection cannot classify
-            // the session and the delegation stays invisible. The label carries the
-            // harness display name as the source marker so the dropdown shows which
-            // local agent produced the conversation.
+            // The durable one-shot descriptor marks this child as session-backed;
+            // without it the 子代理 projection cannot classify the session and the
+            // delegation stays invisible. Host 0.2.1 no longer resolves a descriptor
+            // onto the request (the runtime's one-shot snapshot is gone), so the
+            // provider stamps the same payload itself. The label carries the harness
+            // display name as the source marker so the dropdown shows which local
+            // agent produced the conversation; the activation spec's required label
+            // arrives as the empty string when the caller named none.
             const harness = this.ctx.localAgent.get('kimi');
-            const label = subagentDelegationLabel(harness?.displayName ?? 'kimi', request.descriptor.label);
+            const label = subagentDelegationLabel(harness?.displayName ?? 'kimi', request.label || undefined);
             childSession.append('subagent/descriptor', {
-                ...request.descriptor,
+                version: SUBAGENT_DESCRIPTOR_VERSION,
+                mode: 'one-shot',
+                provider: this.name,
                 label,
             });
-            // The official runtime appends the parent-side subagent/catalog
-            // discovery row only for in-process children (run.localAgent); this run
-            // is remote, so the provider appends it here — once per child, where
+            // The 0.2.1 manager appends the parent-side subagent/catalog discovery
+            // row only for parent-delivered children; the family runs caller
+            // delivery, so the provider appends it here — once per child, where
             // the descriptor lands. A failure degrades to the warn below; a missing
             // row never blocks the delegation.
             establishSubagentCatalogChild(request.parent.session, childSession.header, label);
@@ -264,7 +294,13 @@ export class KimiCliProvider {
         // diagnostics: the CLI reads it directly, and a user-edited value is
         // authoritative. Log it so a failing delegation reports which endpoint
         // it actually used.
-        const baseUrl = await readKimiBaseUrl(homeDir).catch(() => undefined);
+        // The round's endpoint credential: resolved per round (a card write
+        // applies to the next delegation) and pinned onto the managed provider
+        // by the surgery above; the key rides the spawn env under api_key_env.
+        const endpoint = await this.prepareEndpoint(homeDir);
+        const baseUrl = hasEndpointCredential(endpoint)
+            ? endpoint.baseUrl
+            : await readKimiBaseUrl(homeDir).catch(() => undefined);
         this.ctx.logger.info(`subagent-kimi: delegating via ${baseUrl ?? 'kimi default endpoint'}`);
         // Live driver: the round goes to the member's resident `kimi acp` process.
         // A channel that fails at spawn/handshake falls through to the exec
@@ -330,12 +366,12 @@ export class KimiCliProvider {
         try {
             const run = await startKimiCliRun(request, {
                 cwd,
-                env: delegationEnv({ KIMI_CODE_HOME: homeDir }),
+                env: delegationEnv({ KIMI_CODE_HOME: homeDir, ...endpointAuthEnv(endpoint) }),
                 ...exec === undefined ? {} : { exec },
                 endpointLabel: baseUrl,
                 // The session-level override (the composer picker) outranks even the
                 // delegation's own model — the family order puts it first.
-                ...(configuration?.resolved ?? resolveRoundModel(this.memberModels?.overrideFor(runId) ?? requestedModel, this.model)),
+                ...(configuration?.resolved ?? resolveRoundModel(this.memberModels?.overrideFor(runId) ?? requestedModel, () => this.model?.(scope))),
                 ...configuration === undefined ? {} : { controlled: true },
                 disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
                 spawn: spec => this.ctx.subprocess.spawn(spec),
@@ -343,9 +379,6 @@ export class KimiCliProvider {
                     this.ctx.logger.warn(`subagent-kimi: child run failed (${stopReason}) via ${baseUrl ?? 'kimi default endpoint'}: ${error instanceof Error ? error.message : String(error)}`);
                 },
                 onAuthFailure: (detail) => {
-                    // The sentinel: an empty-shell wipe restored here makes the
-                    // caller's retry (or the next round) succeed.
-                    void guardKimiCredential(homeDir, message => { this.ctx.logger.warn(message); });
                     this.ctx.localAgent.reportAuthFailure('kimi', detail, scope);
                 },
                 onAuthSuccess: () => { markCredentialVerified(this.ctx, scope); },
@@ -442,18 +475,23 @@ export class KimiCliProvider {
             const member = exec === undefined && scope === undefined
                 ? this.memberRun(intent.childSessionId, request.parent.session.id, homeDir)
                 : undefined;
-            const baseUrl = await readKimiBaseUrl(homeDir).catch(() => undefined);
+            // Same endpoint handling as the fresh path: resolve per round, pin
+            // the managed provider, inject the key under api_key_env.
+            const endpoint = await this.prepareEndpoint(homeDir);
+            const baseUrl = hasEndpointCredential(endpoint)
+                ? endpoint.baseUrl
+                : await readKimiBaseUrl(homeDir).catch(() => undefined);
             this.ctx.logger.info(`subagent-kimi: resuming via ${baseUrl ?? 'kimi default endpoint'}`);
             let run;
             try {
                 run = await startKimiCliRun(request, {
                     cwd,
-                    env: delegationEnv({ KIMI_CODE_HOME: homeDir }),
+                    env: delegationEnv({ KIMI_CODE_HOME: homeDir, ...endpointAuthEnv(endpoint) }),
                     ...exec === undefined ? {} : { exec },
                     endpointLabel: baseUrl,
                     // See the fresh path: the session-level override outranks the
                     // delegation's recorded model on the exec path too.
-                    ...(configuration?.resolved ?? resolveRoundModel(this.memberModels?.overrideFor(intent.childSessionId) ?? requestedModel, this.model)),
+                    ...(configuration?.resolved ?? resolveRoundModel(this.memberModels?.overrideFor(intent.childSessionId) ?? requestedModel, () => this.model?.(scope))),
                     ...configuration === undefined ? {} : { controlled: true },
                     disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
                     spawn: spec => this.ctx.subprocess.spawn(spec),
@@ -461,9 +499,6 @@ export class KimiCliProvider {
                         this.ctx.logger.warn(`subagent-kimi: child run failed (${stopReason}) via ${baseUrl ?? 'kimi default endpoint'}: ${error instanceof Error ? error.message : String(error)}`);
                     },
                     onAuthFailure: (detail) => {
-                        // The sentinel: an empty-shell wipe restored here makes the
-                        // caller's retry (or the next round) succeed.
-                        void guardKimiCredential(homeDir, message => { this.ctx.logger.warn(message); });
                         this.ctx.localAgent.reportAuthFailure('kimi', detail, scope);
                     },
                     onAuthSuccess: () => { markCredentialVerified(this.ctx, scope); },
@@ -588,8 +623,11 @@ async function mirrorKimiAfterExit(spec, stderr) {
         // The round's turn selects which transcript lines the tool-call accounting
         // belongs to — the mirror window would under-count a settle pass a live
         // poll already drained, and over-count a resume round's earlier turns.
+        // Settle mode: calls whose result never reached the wire fold with a
+        // synthesized interrupted result instead of holding the offset forever.
         const delta = await mirrorKimiDelta(spec.ctx, spec.childSession, spec.homeDir, kimiSessionId, {
             turn: spec.resume?.turn ?? 1,
+            settle: true,
         });
         // Report the final mirrored-line count even when the live mirror already
         // advanced the offset (empty delta): the settle report is authoritative.
@@ -783,24 +821,6 @@ export async function startKimiCliRun(request, spec) {
         // or not the round is session-backed.
         if (settled.stopReason === 'completed')
             spec.onAuthSuccess?.();
-        // The turn closes at the real settle moment, so the timing projection's
-        // duration equals the actual CLI runtime. Every terminal path closes the
-        // window — a failed or cancelled run settles 'error'/'aborted' instead of
-        // leaving the turn open with a distorted tiny duration.
-        if (spec.childSession !== undefined) {
-            if (settled.stopReason === 'completed') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
-            }
-            else if (settled.stopReason === 'aborted') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
-            }
-            else {
-                spec.childSession.append('turn/end', {
-                    turn,
-                    reason: { kind: 'error', error: { message: 'kimi -p exited before the run completed', code: 'UNKNOWN' } },
-                });
-            }
-        }
         return settled;
     });
     // After the child EXITS — however it ended (completed, killed by dispose, or
@@ -808,9 +828,12 @@ export async function startKimiCliRun(request, spec) {
     // subagent session, so a cancelled round still preserves its partial work
     // and real token usage instead of leaving the child blank. The mirror reads
     // the wire file, so it only reflects what kimi flushed before the kill.
-    // Waits for the settle chain first (so turn/end is already appended) AND for
-    // the process to actually exit (so the wire file is complete) before
-    // reading it. Enqueued behind any in-flight live poll on the mirror queue.
+    // Waits for the settle chain first AND for the process to actually exit (so
+    // the wire file is complete) before reading it. Enqueued behind any
+    // in-flight live poll on the mirror queue. The turn closes AFTER the settle
+    // mirror, still inside the mirror queue: every mirrored step must land
+    // before turn/end — the released-log reader rejects a step outside an open
+    // turn on every cold read.
     void result.then(() => child.done).then(() => {
         // Auth detection runs post-exit: streams are drained by then, so a fast
         // failure's stderr is complete (a settle-time read could race the flush).
@@ -828,24 +851,51 @@ export async function startKimiCliRun(request, spec) {
         // usage into the round total, then reports the round's settled
         // observation — the wire's model plus the round's accumulated usage.
         enqueueMirror(async () => {
-            const settled = await mirrorKimiAfterExit(spec, stderr);
-            addRoundUsage(settled?.usage);
+            const settled = await result;
+            const mirrored = await mirrorKimiAfterExit(spec, stderr);
+            addRoundUsage(mirrored?.usage);
+            // The turn closes at the real settle moment, so the timing
+            // projection's duration equals the actual CLI runtime (plus the
+            // settle-mirror quiescence). Every terminal path closes the window —
+            // a failed or cancelled run settles 'error'/'aborted' instead of
+            // leaving the turn open with a distorted tiny duration.
+            if (spec.childSession !== undefined) {
+                if (settled.stopReason === 'completed') {
+                    spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+                }
+                else if (settled.stopReason === 'aborted') {
+                    spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+                }
+                else {
+                    spec.childSession.append('turn/end', {
+                        turn,
+                        reason: { kind: 'error', error: { message: 'kimi -p exited before the run completed', code: 'UNKNOWN' } },
+                    });
+                }
+                if (spec.ctx !== undefined) {
+                    await persistChildSession(spec.ctx, spec.childSession).catch((error) => {
+                        spec.ctx?.logger.warn(`subagent-kimi: turn/end persistence failed: ${thrown(error).message}`);
+                    });
+                }
+            }
             // The wire log names the model but never the CLI build, so the version
             // is the executable's own answer, probed once per binary.
             const cliVersion = await spec.cliVersion?.();
             spec.onRoundSettled?.({
-                ...settled?.model === undefined ? {} : { observedModel: settled.model },
+                ...mirrored?.model === undefined ? {} : { observedModel: mirrored.model },
                 ...cliVersion === undefined ? {} : { cliVersion },
                 ...roundUsage === undefined ? {} : { usage: roundUsage },
-                ...settled?.toolCalls === undefined ? {} : { toolCalls: settled.toolCalls },
+                ...mirrored?.toolCalls === undefined ? {} : { toolCalls: mirrored.toolCalls },
             });
         });
     }, () => { });
     return Promise.resolve(subprocessRunHandle({
-        // A session-backed run's id is the child session id (the seam's local-run
-        // contract), so the tool's resume self-description names the same handle
-        // the delegation registry records.
-        id: spec.childSession?.id ?? SessionId(randomUUID()),
+        // Host 0.2.1: the published run id is a fresh PER-EXECUTION identity —
+        // the activation manager rejects a run id naming a live Session (the
+        // mirrored child session is exactly that), and resume rounds reuse the
+        // child session id. The durable child identity the family tracks rides
+        // the staged intent instead (spec.childSession.id == its childSessionId).
+        id: SessionId(randomUUID()),
         result,
         signal: request.signal,
         onAbort,

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

@@ -16,11 +16,14 @@
  * throttled `mirrorKimiDelta` passes and the settle pass stays authoritative
  * (one fold, one offset, zero divergence between the two drivers). Every
  * transcript item folds 1:1 into the child session log.
- * Live output also mirrors the in-flight item: chunk
- * deltas accumulate per streaming item and append throttled snapshot
- * assistant/messages at the item's reserved (turn, step) — the host folds
- * repeated settles at one coordinate into one live-updating chat node — and
- * the wire line completing the item folds at the same step, finalizing it.
+ * Live output rides the `local-agent/stream` channel: chunk deltas
+ * accumulate per streaming item and publish throttled updates at the item's
+ * reserved (turn, step) — the member live node renders them as-is — while
+ * the item's durable content lands as ONE atomic step/start→…→step/end
+ * triple at that step, written by the completing wire line's fold or at
+ * settle. Durable steps stay dense and strictly sequential (the released-log
+ * reader validates exactly that on every cold open); snapshots never hold a
+ * step open across appends.
  *
  * Lifecycle mirrors the dsh/codex live drivers' discipline: lazy spawn with an
  * initialize handshake (loadSession capability required — crash recovery is
@@ -38,6 +41,7 @@ import { type KimiNativeConfiguration } from './model-catalog.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
 import { type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import { type KimiEndpointAuth } from './endpoint-auth.ts';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export declare const DEFAULT_LIVE_IDLE_MS: number;
 /** Default timeout for a wire request acknowledgement (never for session/prompt). */
@@ -159,6 +163,14 @@ export declare class KimiAcpLiveDriver {
          * retired and respawned onto the new one.
          */
         model?: (childSessionId: string) => string | undefined;
+        /**
+         * Resolver for the scope's endpoint credential, read at each RUNTIME
+         * SPAWN so a settings-card write reaches the next respawn without a
+         * reload. A resolution carrying a key authenticates the runtime through
+         * the managed provider's `api_key_env` indirection (the key rides the
+         * process env; the baseUrl is pinned by the pre-spawn surgery).
+         */
+        endpoint?: (scopeHome: string) => Promise<KimiEndpointAuth>;
     }, timeouts?: KimiLiveDriverTimeouts);
     /** Whether the channel is in its post-failure cooldown (rounds fall back to exec). */
     get disabled(): boolean;