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

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

@@ -0,0 +1,180 @@
+import type { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type SubagentRun, type SubagentStartRequest } from '@deepseek-ai/dsh-subagent';
+import type { LocalAgentDshConfig } from './index.ts';
+import { type DshLiveMirrorGranularity } from './session-mirror.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. */
+export declare const DEFAULT_LIVE_REQUEST_TIMEOUT_MS = 30000;
+/** Default timeout for the serve handshake (a cold sub-dsh 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 the channel stays broken before a round retries live. */
+export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
+/**
+ * The serve channel could not come up (spawn failure or handshake
+ * timeout/mismatch). 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 DshLiveDriverTimeouts {
+    readonly initializeMs: number;
+    readonly requestMs: number;
+    readonly convergeMs: number;
+    /** How long a broken channel stays on the exec fallback before a retry. */
+    readonly channelRetryMs: number;
+}
+/** Fully resolved inputs for one live round (the live counterpart of DshCliRunSpec). */
+export interface DshLiveRoundSpec {
+    /** Parent Session workspace; also the runtime process cwd. */
+    readonly cwd: string;
+    /** The `dsh` harness's scoped home, injected as the runtime's `$DSH_HOME`. */
+    readonly homeDir: string;
+    /** dsh subagent session recording this delegation (always live on this path). */
+    readonly childSession: Session;
+    /** The sub-dsh session id — the caller-supplied uuid, == the child session id. */
+    readonly sessionId: string;
+    /** The delegating session (member-channel registration). */
+    readonly parentSessionId: string;
+    /** Resume round: continue the session, appending under this turn number. */
+    readonly resume?: {
+        readonly turn: number;
+    } | undefined;
+    /**
+     * The member's START model — the delegation's own requested model, or the
+     * composer's session-level override, as resolved by the provider. When it
+     * names one, a resident runtime bound to a DIFFERENT model is retired
+     * before the spawn so the round respawns onto it (the sub-dsh session
+     * resumes from disk — only the process is replaced). Absent means the
+     * spawn resolver decides (override → settings).
+     */
+    readonly startModel?: string | undefined;
+    readonly configuration?: LocalAgentResolvedConfiguration;
+}
+/**
+ * The live driver owns every resident runtime of this provider generation.
+ * The LiveDriverSwitch builds a generation when the settings resolve live on,
+ * retires one with {@link DshLiveDriver.drain} (never interrupts), and
+ * disposes with the enabled toggle (disposeAll).
+ */
+export declare class DshLiveDriver {
+    private readonly ctx;
+    private readonly config;
+    private readonly timeouts;
+    private readonly runtimes;
+    /** In-flight spawns by member: concurrent rounds share one, disposeAll waits them out. */
+    private readonly ensuring;
+    private readonly idleTimers;
+    /** Per-member round serialization (the resume lock covers resume-vs-resume only). */
+    private readonly roundChains;
+    /** When the channel last failed its spawn/handshake probe (breaker with cooldown). */
+    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;
+    /** Aborts in-flight spawns when the driver is disposed mid-handshake. */
+    private readonly disposeController;
+    constructor(ctx: Context, config: LocalAgentDshConfig & {
+        /**
+         * Resolver for the member's configured model, read at each RUNTIME
+         * SPAWN (the serve process is where a live round's model binds, through
+         * its `--model` flag). Receives the member's child session id so the
+         * session-level override can outrank the settings value; absent, or
+         * resolving to nothing, the spawn carries no `--model` and the sub-dsh
+         * inherits the host instance's default selection.
+         */
+        modelFor?: (childSessionId: string) => string | undefined;
+    }, timeouts?: DshLiveDriverTimeouts);
+    /**
+     * Whether the channel is in its post-failure cooldown. A spawn/handshake
+     * failure trips the breaker (rounds fall back to exec), but only for
+     * `channelRetryMs` — a transient boot fault must not disable live driving
+     * until the next plugin reload.
+     */
+    get disabled(): boolean;
+    /** Count of resident runtimes currently registered (zombie accounting in tests). */
+    get liveCount(): number;
+    private clearIdleTimer;
+    /** Arm the idle reaper; every round settlement re-arms it. */
+    private armIdleTimer;
+    /** Reclaim one runtime: deregister, wire shutdown, terminate ladder, member release. */
+    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) sub-dsh session.
+     */
+    hasRuntime(key: string): boolean;
+    /** @deprecated Compatibility no-op: live output is always incremental. */
+    setLiveMirrorGranularity(_granularity: DshLiveMirrorGranularity): 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 the member's live runtime bound at spawn: the identifier, or
+     * undefined when the runtime spawned with no `--model`. Null when the
+     * member has no live runtime in this generation — the broker's switch check
+     * distinguishes "no runtime to retire" from "runtime bound to no model".
+     */
+    boundModelOf(key: string): string | undefined | null;
+    /**
+     * Retire the member's resident runtime so the NEXT round respawns (the
+     * sub-dsh session itself carries over via the on-disk resume). The
+     * composer's model switch calls this after storing the new override; the
+     * caller guarantees no round is in flight for the member.
+     */
+    retireRuntime(key: string): Promise<void>;
+    /**
+     * The member's live runtime, spawning it (once per member at a time) when
+     * absent or dead. `signal` abandons the spawn on cancellation.
+     */
+    private ensureRuntime;
+    /**
+     * Spawn the member's resident runtime and prove the wire with a handshake.
+     * Spawn/handshake failure trips the channel breaker (exec fallback) and
+     * throws {@link LiveChannelUnavailableError}; a later crash is NOT a broken
+     * channel — the next round re-spawns and resumes the on-disk session. A
+     * cancellation mid-spawn reclaims the half-started runtime and throws the
+     * abort instead, without touching the breaker.
+     */
+    private spawnRuntime;
+    private markChannelBroken;
+    /**
+     * Drive one delegation round on the member's resident runtime. Rounds of
+     * one member are strictly serialized: the facade's resume lock covers
+     * resume-vs-resume only, and a resume racing an in-flight fresh round would
+     * otherwise overwrite the runtime's single notification sink and strand
+     * the earlier round forever.
+     */
+    /** Prepare the owned headless agent and validate its adapter without a model turn. */
+    prepare(spec: DshLiveRoundSpec, signal: AbortSignal): Promise<void>;
+    startRound(request: SubagentStartRequest, spec: DshLiveRoundSpec): Promise<SubagentRun>;
+    /**
+     * The serialized round body. Mirrors the exec run's settlement contract
+     * exactly (settleRunResult + turn/end bookkeeping) so the facade, the
+     * tool, and the projections cannot tell the difference — except `cancel`
+     * is a runtime interrupt and the process survives. Cancellation is honored
+     * in EVERY window: a slow spawn/handshake or a slow accept races the abort
+     * signal and settles aborted instead of running the turn to completion
+     * unwatched.
+     */
+    private startRoundLocked;
+}
+//# sourceMappingURL=live-driver.d.ts.map