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

package/lib/types/kimi-cli-provider.d.ts

@@ -0,0 +1,215 @@
+/**
+ * One-shot and resumable Kimi CLI subagent lifecycle: spawn `kimi -p "<task>"`
+ * through the subprocess seam, capture its printed response as the run output,
+ * and dispose to whole-tree quiescence. Mirrors the official one-shot Codex
+ * provider, and adds the family's own resume: a later round calls the tool with
+ * the first round's dsh child session id, the family registry maps it back to
+ * the kimi session, and the provider spawns `kimi -S session_<id> -p` so the
+ * SAME kimi conversation continues inside the SAME dsh child session.
+ * @module @khorsheed/dsh-local-agent-kimi/kimi-cli-provider
+ */
+import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import { type ResolvedSubagentStartRequest, type SubagentCapabilities, type SubagentProvider, type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { DelegationExecTarget, LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
+import type { KimiAcpLiveDriver } from './live-driver.ts';
+import type { KimiModelBroker } from './model-broker.ts';
+import { type KimiMirrorDelta, type KimiMirrorOptions } from './session-mirror.ts';
+/** Default POSIX grace between subprocess termination tiers. */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/**
+ * Auth-shaped failure signatures in kimi's stderr or output: the endpoint
+ * rejected the credential. Narrow on purpose — matched against
+ * provider-controlled error output only.
+ */
+export declare const KIMI_AUTH_FAILURE: RegExp;
+/** Default interval between live transcript-mirror polls during a run. */
+export declare const DEFAULT_LIVE_MIRROR_INTERVAL_MS = 2000;
+/**
+ * The version `kimi --version` reports, probed through the shared subprocess
+ * seam inside the SCOPED home (never the user's own installation) and cached
+ * by the family probe against the executable's identity. Kimi's wire log names
+ * no build, so this is the only version channel the harness has — both the
+ * effective-settings snapshot and a settled round's read-back read it.
+ * @param ctx - host context carrying the subprocess seam.
+ * @param homeDir - the harness's scoped home.
+ * @returns the version, or undefined when the CLI cannot be asked.
+ */
+export declare function kimiCliVersion(ctx: Context, homeDir: string): Promise<string | undefined>;
+export declare class KimiCliProvider implements SubagentProvider {
+    private readonly ctx;
+    private readonly live?;
+    private readonly model?;
+    private readonly memberModels?;
+    readonly name = "kimi-cli";
+    readonly capabilities: SubagentCapabilities;
+    readonly inheritsParentContext = false;
+    /**
+     * @param live - the live driver, or a resolver returning the current
+     *   generation's driver per member (the settings toggle swaps generations;
+     *   a resolver may return undefined to steer one member's round to exec
+     *   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.
+     * @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: Context, live?: KimiAcpLiveDriver | ((childSessionId: string) => KimiAcpLiveDriver | undefined) | undefined, model?: (() => string | undefined) | undefined, memberModels?: KimiModelBroker | undefined);
+    /** Resolve the live driver for one round's member, if live is on for it. */
+    private liveDriver;
+    /**
+     * Register one run with the member channel and declare the bridge MCP server
+     * in the scoped home's mcp.json (per-run entry, socket + token in its env).
+     * Returns the release handle, or undefined when the mounted core
+     * predates the member channel (declare-and-degrade: the run proceeds
+     * exactly as before). Token-only auth: host 0.1.5 removed the child pid the
+     * parentage cross-check used; the per-run token is the sole credential (see
+     * the package README's threat model). `release` invalidates the token and
+     * prunes the config entry on any settle path.
+     */
+    private memberRun;
+    start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;
+    /** Fresh round: record the child session, spawn `kimi -p`, mirror after settle. */
+    private startKimiFresh;
+    /** Resume round: continue the recorded kimi session inside the existing child session. */
+    private startKimiResume;
+}
+/** Fully resolved inputs for one Kimi CLI run. */
+export interface KimiCliRunSpec {
+    /** Parent Session workspace; also the kimi process cwd. */
+    readonly cwd: string;
+    /** Explicit environment layered after the shared credential scrub. */
+    readonly env: Readonly<NodeJS.ProcessEnv>;
+    /**
+     * Run the CLI inside this container instead of on the host: the argv below
+     * is wrapped in `docker exec` and {@link env} is forwarded through NAME-only
+     * `-e` flags. Absent means the host spawn, unchanged.
+     */
+    readonly exec?: DelegationExecTarget | undefined;
+    /** Resolved endpoint label for diagnostics; absent means the CLI default. */
+    readonly endpointLabel?: string | undefined;
+    /**
+     * Model this round runs with, passed as `kimi -m <model>`. The value must
+     * name a model the scoped `config.toml` defines (a `[models."…"]` key) —
+     * kimi resolves the flag against its own model table. Absent means no `-m`
+     * on the argv at all: `default_model` decides, exactly as before the key
+     * rode every round.
+     */
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+    readonly controlled?: boolean;
+    /** Subprocess termination grace passed to the shared process-tree owner. */
+    readonly disposeGraceMs: number;
+    /** Shared subprocess service spawn operation. */
+    readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /** Diagnostic sink for a post-publication error flattened into a result. */
+    readonly onError?: (error: Error, stopReason: SubagentStopReason) => void;
+    /**
+     * Called when the settled failure is auth-shaped (the endpoint rejected the
+     * credential — a 401 a presence probe cannot see). The provider wires this
+     * to the family registry's auth-failure mark.
+     */
+    readonly onAuthFailure?: ((detail: string) => void) | undefined;
+    /** dsh subagent session recording this delegation; its transcript is mirrored after settle. */
+    readonly childSession?: Session | undefined;
+    /** The `kimi` harness's scoped home, read for the transcript to mirror. */
+    readonly homeDir?: string | undefined;
+    /** Host context carrying session persistence for the transcript mirror. */
+    readonly ctx?: Context | undefined;
+    /**
+     * Resume round: continue the CLI session named by `cliSessionId` with
+     * `kimi -S session_<id> -p` instead of a fresh `kimi -p`, appending this
+     * round into the same child session under the given turn number.
+     */
+    readonly resume?: {
+        readonly cliSessionId: string;
+        readonly turn: number;
+    } | undefined;
+    /**
+     * Called after the run settles with the kimi session id parsed from stderr
+     * (absent when the hint is missing). The fresh path uses it to record the
+     * delegation so a later resume round can continue the session.
+     */
+    readonly onCliSessionId?: ((cliSessionId: string | undefined) => void) | undefined;
+    /**
+     * Called once per settled round, after the wire log has been fully mirrored:
+     * the round's observed model identifier (the wire's `usage.record` /
+     * `llm.request` `model`) and token usage (the round's mirror windows summed),
+     * each absent when the wire yielded none. The provider wires this to the
+     * registry's observation channel (`recordRoundSettled` — the delegation
+     * record's `observedModel` merge and the `settled` run-progress event).
+     * Fires for fresh and resume rounds alike, on every terminal state.
+     */
+    readonly onRoundSettled?: ((round: {
+        readonly observedModel?: string;
+        readonly cliVersion?: string;
+        readonly usage?: TokenUsage;
+        readonly toolCalls?: LocalAgentToolCalls;
+    }) => void) | undefined;
+    /**
+     * Called when the round SETTLED COMPLETED — the CLI reached its endpoint and
+     * produced an answer, which is the only evidence a host has that the scoped
+     * credential is live. The provider wires this to the family registry's
+     * auth-success mark (the `verified` credential grade).
+     */
+    readonly onAuthSuccess?: (() => void) | undefined;
+    /**
+     * The version the executable reports, resolved lazily and cached by the
+     * family probe. Kimi's wire log names no CLI version, so this is the only
+     * channel the round's read-back has.
+     */
+    readonly cliVersion?: (() => Promise<string | undefined>) | undefined;
+    /**
+     * Live-mirror poll interval during the run; absent disables nothing — the
+     * default ({@link DEFAULT_LIVE_MIRROR_INTERVAL_MS}) applies. Tests inject a
+     * small value.
+     */
+    readonly liveMirrorIntervalMs?: number | undefined;
+}
+/**
+ * Extract the kimi session id from the CLI's printed response. `kimi -p`
+ * prints a resume hint (`To resume this session: kimi -r session_<id>`) on
+ * stdout after a run; mirroring that exact session instead of the newest-by-
+ * mtime keeps concurrent delegations from cross-mirroring.
+ * @param output - the collected CLI stdout.
+ * @returns the session id, or undefined when the hint is absent.
+ */
+export declare function kimiSessionIdFromOutput(output: string): string | undefined;
+/**
+ * Validate and join the one-shot task before crossing the process boundary.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the joined non-empty text.
+ */
+export declare function textTask(prompt: readonly ContentBlock[]): string;
+/**
+ * Mirror the transcript delta after the recorded offset, advance the offset,
+ * and report one `delta` progress per newly mirrored line. Shared by the live
+ * poll and the settle-time mirror so the two paths cannot drift. The offset
+ * read (`kimiMirroredLines`) and write (`setKimiMirroredLines`) are the same
+ * bookkeeping the settle path used before live mirroring existed.
+ * @param ctx - host context carrying localAgent and session persistence.
+ * @param childSession - the dsh child session being mirrored into.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @param kimiSessionId - the kimi session to mirror.
+ * @returns the mirror delta (new total + newly mirrored line texts).
+ */
+export declare function mirrorKimiDelta(ctx: Context, childSession: Session, homeDir: string, kimiSessionId: string | undefined, options?: KimiMirrorOptions): Promise<KimiMirrorDelta>;
+/**
+ * Start the real `kimi -p` (fresh) or `kimi -S session_<id> -p` (resume)
+ * child and publish its run. The kimi response is printed to stdout; stderr
+ * is inherited for diagnostics. The run id is the child session id for a
+ * session-backed run, so the tool's `resume="<id>"` self-description names
+ * the same handle the registry records.
+ * @param request - resolved shared subagent request.
+ * @param spec - workspace, environment, process service, and diagnostic policy.
+ * @returns the published run after the child starts.
+ */
+export declare function startKimiCliRun(request: SubagentStartRequest, spec: KimiCliRunSpec): Promise<SubagentRun>;
+//# sourceMappingURL=kimi-cli-provider.d.ts.map