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

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

@@ -0,0 +1,245 @@
+/**
+ * The kimi provider's live driver: one resident `kimi acp` process per member
+ * (child session), driven over the vendor's Agent Client Protocol (ACP) —
+ * JSON-RPC NDJSON over stdio (protocol-probed against kimi 0.36.1; the
+ * harness `subagent-acp` package is the reference implementation). A
+ * delegation round is a `session/prompt` on the member's resident session
+ * instead of a fresh `kimi -p` process, which buys what the process boundary
+ * could not: runtime-level graceful interrupt (`session/cancel`; the process
+ * survives and the session stays continuable) and push-driven mirroring
+ * (`session/update` notifications trigger throttled file-mirror passes — see
+ * below why the transcript itself stays file-sourced).
+ *
+ * Mirroring contract (the kimi-specific call): kimi's ACP updates are
+ * token-level chunks, NOT the wire.jsonl line fold the exec mirror owns — so
+ * completed items always fold from the file: push events merely TRIGGER
+ * 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.
+ *
+ * Lifecycle mirrors the dsh/codex live drivers' discipline: lazy spawn with an
+ * initialize handshake (loadSession capability required — crash recovery is
+ * `session/load` of the recorded session id), one in-flight spawn per member,
+ * idle-timeout reclaim (stdin EOF → grace → SIGTERM ladder), a channel breaker
+ * with cooldown, `disposeAll` on unload, and cancellation honored in every
+ * window. The wire adapter is self-contained (no `@agentclientprotocol/sdk`
+ * dependency): StringDecoder framing, request correlation, and unattended
+ * auto-answers for `session/request_permission` (allow — matching the exec
+ * mode's auto-approve behavior; the proposal's default policy).
+ * @module @khorsheed/dsh-local-agent-kimi/live-driver
+ */
+import type { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
+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';
+/** 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). */
+export declare const DEFAULT_LIVE_REQUEST_TIMEOUT_MS = 30000;
+/** Default timeout for the ACP handshake (a cold boot can be slow). */
+export declare const DEFAULT_LIVE_INITIALIZE_TIMEOUT_MS = 60000;
+/** Bounded wait for an interrupted turn to converge while a run disposes. */
+export declare const DEFAULT_LIVE_DISPOSE_CONVERGE_MS = 5000;
+/** How long a tripped channel breaker stays on the exec fallback. */
+export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
+/** Minimum gap between push-triggered mirror passes. */
+export declare const DEFAULT_LIVE_MIRROR_THROTTLE_MS = 500;
+/** Default minimum interval between one streaming item's snapshot messages. */
+export declare const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 50;
+/** Default minimum text growth between one streaming item's snapshot messages. */
+export declare const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
+/**
+ * The ACP channel could not come up (spawn failure, handshake
+ * timeout/mismatch, or a missing loadSession capability). The provider
+ * catches exactly this and falls back to the exec one-shot; any other error
+ * is a real round failure.
+ */
+export declare class LiveChannelUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Internal timeouts; tests inject small values. */
+export interface KimiLiveDriverTimeouts {
+    readonly initializeMs: number;
+    readonly requestMs: number;
+    readonly convergeMs: number;
+    readonly channelRetryMs: number;
+    readonly mirrorThrottleMs: number;
+}
+/** How much of the live event stream crosses into the child session. */
+export type KimiLiveMirrorGranularity = 'event' | 'token';
+/** Fully resolved inputs for one live round. */
+export interface KimiLiveRoundSpec {
+    readonly configuration?: LocalAgentResolvedConfiguration;
+    /** Parent Session workspace; also the runtime process cwd and ACP session cwd. */
+    readonly cwd: string;
+    /** The `kimi` harness's scoped home, injected as the runtime's `KIMI_CODE_HOME`. */
+    readonly homeDir: string;
+    /** dsh subagent session recording this delegation (always live on this path). */
+    readonly childSession: Session;
+    /** The delegating session (member-channel registration). */
+    readonly parentSessionId: string;
+    /**
+     * Resume round: continue the session recorded as `cliSessionId`, appending
+     * under this turn number. Also the reattach path after a runtime crash.
+     */
+    readonly resume?: {
+        readonly cliSessionId: string;
+        readonly turn: number;
+    } | undefined;
+    /** Fresh round: called with the server-assigned session id (delegation record). */
+    readonly onCliSessionId?: ((cliSessionId: string) => void) | undefined;
+}
+/**
+ * Auth-shaped failure signatures in kimi's error output: the endpoint
+ * rejected the credential. Mirrors the exec path's detector
+ * (KIMI_AUTH_FAILURE in kimi-cli-provider.ts); the live path matches against
+ * session/prompt failure messages, which is where a mid-run 401 surfaces
+ * when the process does not exit.
+ */
+export declare const KIMI_LIVE_AUTH_FAILURE: RegExp;
+/**
+ * kimi ACP session ids are directory names (`session_<uuid>`); the family
+ * delegation record convention is the bare uuid (the exec path's settle-time
+ * stderr parse). Strip the prefix so live- and exec-written records stay
+ * interchangeable.
+ */
+export declare function bareKimiSessionId(acpSessionId: string): string;
+/** The ACP-native form of a recorded kimi session id (idempotent). */
+export declare function acpKimiSessionId(recordedId: string): string;
+/**
+ * Map an ACP prompt stop reason onto the shared stop contract (the harness
+ * subagent-acp mapping, verbatim): an unclean stop is never 'completed'.
+ */
+export declare function acpStopReasonToHarness(reason: string): SubagentStopReason;
+/**
+ * The kimi live driver owns every resident ACP runtime of this provider
+ * generation. Created only when `live: true`; disposed with the plugin.
+ */
+export declare class KimiAcpLiveDriver {
+    private readonly ctx;
+    private readonly config;
+    private readonly timeouts;
+    private readonly runtimes;
+    private readonly ensuring;
+    /** The model each in-flight spawn is binding (a stale-model spawn never serves a switched member). */
+    private readonly ensuringModel;
+    private readonly ensuringConfiguration;
+    private readonly idleTimers;
+    /** Per-member round serialization (the resume lock covers resume-vs-resume only). */
+    private readonly roundChains;
+    private channelBrokenAt;
+    private disposed;
+    /**
+     * Set by drain() (a settings-driven generation handoff): new rounds are
+     * refused so the provider falls back to exec, while in-flight rounds finish
+     * on their runtime undisturbed. Unlike `disposed`, the driver still serves
+     * what it already accepted.
+     */
+    private draining;
+    private readonly disposeController;
+    constructor(ctx: Context, config?: {
+        liveIdleMs?: number;
+        liveMirrorGranularity?: KimiLiveMirrorGranularity;
+        /** Maximum batching wait for incremental streaming messages. */
+        snapshotMinIntervalMs?: number;
+        /** @deprecated Character growth no longer gates live publication. */
+        snapshotMinChars?: number;
+        /**
+         * Resolver for the member's effective model, read at each RUNTIME
+         * SPAWN. `kimi acp` takes no model flag, so this path pins the scoped
+         * config's `default_model` instead of extending the argv. Absent, or
+         * resolving to nothing for the member, writes nothing at all. A runtime
+         * whose bound model no longer matches the member's resolved model is
+         * retired and respawned onto the new one.
+         */
+        model?: (childSessionId: string) => string | undefined;
+    }, timeouts?: KimiLiveDriverTimeouts);
+    /** Whether the channel is in its post-failure cooldown (rounds fall back to exec). */
+    get disabled(): boolean;
+    /** Count of resident runtimes currently registered (zombie accounting in tests). */
+    get liveCount(): number;
+    private clearIdleTimer;
+    private armIdleTimer;
+    private reclaim;
+    /** Reclaim every runtime (plugin unload); no process survives the profile. */
+    disposeAll(): Promise<void>;
+    /**
+     * True while the member's runtime exists or is being spawned. The settings
+     * controller gates a new generation on this: a fresh driver must not serve
+     * a member whose retiring generation still hosts the (same) kimi session.
+     */
+    hasRuntime(key: string): boolean;
+    /** @deprecated Compatibility no-op: live output is always incremental. */
+    setLiveMirrorGranularity(_granularity: KimiLiveMirrorGranularity): void;
+    /**
+     * Drain for a settings-driven generation handoff: refuse new rounds (the
+     * provider's catch falls back to exec), let every in-flight round finish on
+     * its runtime, then reclaim. Resolves when no runtime or spawn remains.
+     * Unlike disposeAll, in-flight work is never interrupted.
+     */
+    drain(): Promise<void>;
+    /** The model a runtime spawned for this member right now would bind. */
+    private resolveBoundModel;
+    private ensureRuntime;
+    /**
+     * Retire one member's resident runtime (a composer-driven model switch):
+     * the process is reclaimed and the member's next round respawns onto the
+     * new model, resuming the same CLI session. A member with no runtime (or
+     * only a dead one) is a no-op. Lazy: nothing spawns here.
+     */
+    retireRuntime(childSessionId: string): Promise<void>;
+    /**
+     * The model the member's live runtime is bound to, or undefined when the
+     * member has no live runtime (or it bound none). The broker compares this
+     * against the post-switch effective model to make a same-model set a no-op.
+     */
+    runtimeModel(childSessionId: string): string | undefined;
+    runtimeConfiguration(childSessionId: string): KimiNativeConfiguration | undefined;
+    /**
+     * Spawn the member's resident `kimi acp` and prove the wire: initialize +
+     * the loadSession capability (crash recovery needs it — without it the
+     * channel is not live-capable and the breaker trips). A cancellation
+     * mid-spawn reclaims the half-started process without touching the breaker.
+     */
+    private spawnRuntime;
+    private markChannelBroken;
+    /**
+     * Report an auth-shaped round failure to the family registry's auth-failure
+     * mark (the exec path's post-exit 401 detection ported to a process that
+     * never exits: the match runs against the settled error instead). Degrades
+     * silently on a core predating reportAuthFailure.
+     */
+    private reportAuthIfShaped;
+    /**
+     * Register the member channel for one resident process (token + bridge
+     * coordinates), duck-typed like the exec path's memberRun but WITHOUT the
+     * mcp.json write — the ACP session declares the bridge inline.
+     */
+    private registerMember;
+    /**
+     * Auto-answer the ACP permission surface unattended. `session/request_permission`
+     * selects the first allow option (allow_once/allow_always) — matching the
+     * exec mode's auto-approve behavior for `kimi -p` — and cancels when the
+     * child offered none. Anything else (fs/terminal, which we never
+     * advertised) is an error response.
+     */
+    private answerServerRequest;
+    /**
+     * Drive one delegation round on the member's resident ACP session. Mirrors
+     * the exec run's settlement contract exactly (settleRunResult + turn/end
+     * bookkeeping); cancel is `session/cancel` and the process survives.
+     */
+    /** Initialize the native session and model controls without sending a prompt. */
+    prepare(spec: KimiLiveRoundSpec, signal: AbortSignal): Promise<void>;
+    private configureSession;
+    startRound(request: SubagentStartRequest, spec: KimiLiveRoundSpec): Promise<SubagentRun>;
+    /** The serialized round body. */
+    private startRoundLocked;
+}
+//# sourceMappingURL=live-driver.d.ts.map