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

package/lib/types/model-broker.js

@@ -35,6 +35,42 @@ function dedupe(candidates) {
     }
     return out;
 }
+/**
+ * Scope the served directory to the surface asking for it (the same helper
+ * lives in each provider's broker — fold into the family core when the
+ * directory faces next evolve):
+ *
+ * - memberless (the card's add-model dialog, the invite picker): the
+ *   endpoint's served catalog only — the configuration/history extras the
+ *   broker's info extension adds for STATUS display (a config-defined model
+ *   the endpoint does not serve) must never become add candidates;
+ * - a member whose harness has a curated list: the list IS the vocabulary,
+ *   in the list's own order (the same rule `choices` already follows) — a
+ *   curated value the endpoint no longer serves stays as a bare row (the
+ *   card shows it the same way), and the member's current effective model is
+ *   kept visible as a bare entry when it sits outside the list, so a pre-list
+ *   binding never renders blank;
+ * - a member without a curated list: the legacy extended vocabulary.
+ */
+function scopeServedDirectory(directory, opts) {
+    if (opts.member && opts.curated.length === 0)
+        return directory;
+    const served = directory.entries.filter(entry => entry.source === 'native');
+    if (!opts.member)
+        return { ...directory, entries: served };
+    const byValue = new Map(served.flatMap(entry => entry.resolvedModel === undefined
+        ? [[entry.value, entry]]
+        : [[entry.value, entry], [entry.resolvedModel, entry]]));
+    // Curated ORDER leads (the card's first row is the default); a curated value
+    // the endpoint no longer serves stays listed as a bare row, exactly like the
+    // card shows it.
+    const entries = opts.curated.map(value => byValue.get(value) ?? { value, label: value, source: 'configuration' });
+    const current = opts.current?.trim();
+    if (current !== undefined && current !== '' && !entries.some(entry => entry.value === current || entry.resolvedModel === current)) {
+        entries.push({ value: current, label: current, source: 'configuration' });
+    }
+    return { ...directory, entries };
+}
 /**
  * The kimi harness's {@link LocalAgentModelBroker}. Also the provider-facing
  * member-model ledger: the provider records each delegation's start model
@@ -92,7 +128,12 @@ export class KimiModelBroker {
         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 };
+        const directory = info.directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+        return scopeServedDirectory(directory, {
+            member: childSessionId !== undefined,
+            curated: this.deps.modelList?.(this.deps.homeDir(childSessionId)) ?? [],
+            current: info.effective,
+        });
     }
     async *followModelDirectory(childSessionId, signal) {
         if (this.deps.catalog === undefined) {

package/lib/types/session-mirror.d.ts

@@ -11,24 +11,45 @@ import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
 import type { Session } from '@deepseek-ai/dsh-session';
 import type { LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
 import { type KimiTranscriptLine } from './session-view.ts';
+/**
+ * The synthesized result for a call whose result the wire never recorded
+ * (a settle-pass fold, or a live reservation kimi never logged). The
+ * released-log contract resolves every advertised call before its step
+ * closes, so an interrupted call folds with this error result.
+ */
+export declare const KIMI_INTERRUPTED_TOOL_RESULT = "\uFF08\u5DE5\u5177\u8C03\u7528\u88AB\u4E2D\u65AD\uFF0C\u672A\u80FD\u8BB0\u5F55\u8FD4\u56DE\u7ED3\u679C\uFF09";
 /** One assistant-role message event, attributed to the kimi route. */
 export declare function assistantEvent(blocks: readonly ContentBlock[], model?: string): import("@deepseek-ai/dsh-llm").AssistantMessage;
 /**
- * The step the next fold pass would assign in one turn (the max existing
- * step + 1). The token-granularity live
- * driver reserves its stream merge key here LAZILY at the first delta, so
- * tool cards folded before the stream started keep their chronological
- * place below it instead of the stream squatting on step 1.
+ * The step the next fold pass would assign in one turn: the smallest step
+ * nothing holds (never written, never reserved at call time — callers skip
+ * their own reservations on top). Filling the smallest free step keeps the
+ * stored log dense: the released-log reader admits only dense, strictly
+ * sequential steps, and a reservation released mid-round (its content rode an
+ * earlier fold) leaves a gap only the next first-free write fills.
  * @param childSession - the run's child session.
  * @param turn - the round's turn number.
- * @returns the next free step in the turn.
+ * @returns the smallest free step in the turn.
  */
 export declare function nextKimiSessionStep(childSession: Session, turn: number): number;
+/**
+ * The step a durable write takes: one past the highest step this turn has
+ * opened in the log. The released-log reader admits steps only in order —
+ * one past the last, never below it — so the coordinate is decided when the
+ * step is written, never reserved ahead (a reservation filled later lands
+ * below a higher step already written: a gap, then a step out of order).
+ * Stream and tool reservations only key the live preview.
+ */
+export declare function nextWrittenKimiStep(childSession: Session, turn: number): number;
 /** The run-progress delta text for one transcript line (any kind). */
 export declare function kimiLineProgressText(line: KimiTranscriptLine): string;
 /** The result of one mirror pass: the new offset plus what was newly mirrored. */
 export interface KimiMirrorDelta {
-    /** The new total transcript-line count mirrored into the child session. */
+    /**
+     * The new mirror offset (transcript lines folded so far). An unresulted
+     * tool line (or a wire step the wire has not closed yet) HOLDS a mid-round
+     * pass: the offset stops before it and the next pass retries from there.
+     */
     total: number;
     /**
      * The folded text of each transcript line THIS pass newly mirrored, in
@@ -38,17 +59,24 @@ export interface KimiMirrorDelta {
      */
     texts: string[];
     /**
-     * The usage this pass computed for its window. Attached to the window's
-     * last folded assistant message when one exists (see `usageAttached`);
-     * otherwise returned unattached, so the caller (the token-granularity live
-     * driver) can carry it on the stream's final snapshot instead.
+     * The usage this pass computed for its window. Attached per wire step: the
+     * records whose line position falls inside a folded unit's span ride THAT
+     * unit's message (one usage.record per LLM request, matching the host
+     * session's own shape); anything no fold carried comes back as
+     * `usageUnattached` for the caller to carry.
      */
     usage?: TokenUsage;
     /**
-     * True when this pass's usage rode a folded assistant message — the caller
+     * True when this pass's usage rode folded assistant messages — the caller
      * must never attach that accounting a second time.
      */
     usageAttached?: boolean;
+    /**
+     * The window's accounting that NO fold carried (a pass with only held or
+     * fully-sealed folds): the token-granularity live driver sums it into the
+     * round's uncarried remainder, which the settle's final snapshot carries.
+     */
+    usageUnattached?: TokenUsage;
     /**
      * The model identifier the wire named (a `usage.record` or `llm.request`
      * `model` field, last one seen) — the delegation's observed-model source.
@@ -66,35 +94,51 @@ export interface KimiMirrorDelta {
 /**
  * The live stream ledger a fold pass coordinates with.
  * Absent on the exec path, where no streams reserve steps.
+ *
+ * The durable contract this enforces: the released-log reader admits only
+ * dense, strictly sequential steps (one open at a time) — so the fold writes
+ * every step as one atomic step/start→…→step/end triple, and a fold landing
+ * at a reserved step first finalizes every stream reservation below it.
  */
 export interface KimiMirrorStreams {
     /**
-     * Steps in-flight streams reserved for this turn (their snapshot messages
-     * append there). Sequential folds must skip them, so a tool card folded
-     * mid-stream lands ABOVE the stream's step and the projection renders the
-     * round's chronological order.
+     * Steps in-flight streams reserved for this turn (their live updates ride
+     * `local-agent/stream` events there). Sequential folds skip them, so a
+     * tool card folded mid-stream lands ABOVE the stream's step and the
+     * projection renders the round's chronological order.
      */
     reservedSteps(turn: number): readonly number[];
-    /** Reserve chronological placement from the ACP tool notification before its file fold. */
-    completeTool?(line: KimiTranscriptLine & {
+    /**
+     * Finalize every in-flight stream reserved below `step`, in ascending
+     * order, writing each one's atomic step triple with its accumulated text.
+     * Called before any fold writes at `step`. Stream reservations only: an
+     * unresulted tool line HOLDS the pass instead, so a tool reservation
+     * never sits inside the gap.
+     */
+    finalizeBefore?(turn: number, step: number): void;
+    /**
+     * Release the ACP tool notification's chronological reservation for this
+     * wire line WITHOUT writing: the line's fold carries the whole native
+     * lifecycle inside its step, so the reserved coordinate frees for a later
+     * fold. (A reservation kimi never logs to the wire stays reserved and
+     * finalizes as the driver's settle-time orphan fold.)
+     */
+    releaseTool?(line: KimiTranscriptLine & {
         kind: 'tool';
-    }): {
-        readonly step: number;
-        readonly opened: boolean;
-    } | undefined;
+    }): void;
     /**
-     * Pair one completed think/assistant transcript line with its in-flight
-     * stream. Returns the reservation — consuming it — when this line finalizes
-     * a stream: the caller folds the line's message at the reserved step,
-     * opening the step boundary only when `opened` is false (no snapshot ever
-     * landed), and closes it. Undefined folds the line sequentially. A
-     * (turn, step) NEVER takes a second step/start.
+     * Consume the round's in-flight content streams of the given kinds, pairing
+     * them with one fold: `step` is the fold coordinate (the earliest consumed
+     * reservation still needing one — absent when every consumed kind was
+     * already sealed, so the fold goes sequential), and `sealed` lists the
+     * kinds already durable (a gap fill wrote their triples — the fold must
+     * EXCLUDE their content). Reservations whose content rides this fold are
+     * released, so a later sequential fold may take their steps. Undefined when
+     * no stream pairs — the fold goes sequential.
      */
-    completeStream(line: KimiTranscriptLine & {
-        kind: 'assistant' | 'think';
-    }): {
-        readonly step: number;
-        readonly opened: boolean;
+    completeStreams(turn: number, kinds: readonly ('think' | 'text')[]): {
+        readonly step?: number;
+        readonly sealed: readonly ('think' | 'text')[];
     } | undefined;
 }
 /** Mirror behavior switches shared by the exec and live paths. */
@@ -113,12 +157,22 @@ export interface KimiMirrorOptions {
      * think/assistant lines with their streams and skip reserved steps.
      */
     streams?: KimiMirrorStreams;
+    /**
+     * Settle pass: a tool line whose result the wire never recorded folds with
+     * a synthesized interrupted result instead of holding the pass (the round
+     * is over — the result will never arrive). Mid-round passes hold there.
+     */
+    settle?: boolean;
 }
 /**
- * Mirror one kimi session's transcript into the dsh subagent session: each
- * user prompt becomes a `user/message`, each assistant reply (including
- * folded thinking and tool activity) an `assistant/message`, then the events
- * are appended to persistence so the child session is viewable.
+ * Mirror one kimi session's transcript into a dsh subagent session: each
+ * user prompt becomes a `user/message`, and each WIRE STEP (one LLM request:
+ * its thinking, reply text and tool calls share the wire's own step number)
+ * folds into one dsh step whose `assistant/message` carries the reasoning,
+ * text and tool-call blocks together — the host session's own shape, so the
+ * standard surfaces (conversation, Context Lens) read one request per LLM
+ * call. Then the events are appended to persistence so the child session is
+ * viewable.
  *
  * A resumed round (or a live poll) passes the already-mirrored
  * transcript-line count so only the delta is appended — re-mirroring earlier
@@ -128,22 +182,29 @@ export interface KimiMirrorOptions {
  * already in the child session, so a round mirrored across several live polls
  * does not restart step 1 per poll.
  *
- * Every folded step is wrapped in the `step/start`–`step/end` boundary pair
- * the live conversation assembler requires: without a boundary the step never
- * enters the location index, the assistant message resolves to a turn-level
- * location, and the real-time view renders nothing (only a full rebuild,
- * which mints step drafts from the explicit coordinates, recovers it). A
- * think/assistant line that completes an in-flight stream folds at the
- * stream's reserved step instead (see {@link KimiMirrorStreams}), and a
- * sequential fold never takes a step a stream reserved.
+ * Every folded step is one ATOMIC `step/start`–`step/end` triple, written
+ * only when its content lands: the released-log reader admits only dense,
+ * strictly sequential steps (one open at a time — a second `step/start`
+ * while another step is open fails the session's reload validation), and the
+ * live conversation assembler needs the boundary to materialize the step at
+ * all. A fold paired with in-flight streams lands at the earliest consumed
+ * reservation (see {@link KimiMirrorStreams}), after `finalizeBefore` has
+ * closed every stream reservation below it; a sequential fold never takes a
+ * step a stream reserved. Mid-round, a wire step the wire has not CLOSED yet
+ * (no `step.end`) holds the pass — its parts may still arrive — and so does
+ * an unresulted tool call (the reader resolves every advertised call before
+ * the step closes; the result merges into the call's line in place, so the
+ * next pass sees it). The settle pass folds the remainder with a synthesized
+ * interrupted result. Lines the wire never step-tagged (older kimi) fold one
+ * by one, immediately, as before.
  *
  * Usage accounting is exactly-once ACROSS passes: each `usage.record` is
- * tagged with the transcript position it occurred at, and a pass attaches the
- * records in the half-open range `(fromLines, newTotal]` — the records that
- * trail THIS pass's lines — summed onto the delta's final assistant message.
- * (A record flushed only after its line was already mirrored belongs to no
- * later pass and is dropped; kimi flushes content and usage together per
- * request, so this window is a flush race, not the norm.)
+ * tagged with the transcript position it occurred at, a pass owns the records
+ * between the old offset and its own consumed end, and inside the window each
+ * record rides the unit whose line span encloses it — one record per wire
+ * step, landing on its own step's message. (A record raced PAST its content
+ * encloses into the next unit instead: attribution off by one in a flush
+ * race, totals still exact.)
  * @param ctx - host context carrying the session persistence service.
  * @param childSession - the dsh subagent session created for this delegation.
  * @param homeDir - the `kimi` harness's scoped home.
@@ -151,7 +212,9 @@ export interface KimiMirrorOptions {
  *   recent session (a one-shot `kimi -p` run always creates a fresh one).
  * @param fromLines - transcript lines already mirrored into the child session
  *   (0 for the first round); only lines after this offset are appended.
- * @returns the new total and the newly mirrored lines' texts.
+ * @returns the new mirror offset and the newly mirrored lines' texts. A held
+ *   unit (open wire step or unresulted tool) stops the offset before itself;
+ *   the next pass retries from there.
  */
 export declare function mirrorKimiSessionDelta(ctx: Context, childSession: Session, homeDir: string, kimiSessionId?: string, fromLines?: number, options?: KimiMirrorOptions): Promise<KimiMirrorDelta>;
 /**