dsh-loop-engine 0.1.7-rc4 → 0.1.7-rc5

package/README.md

@@ -22,7 +22,7 @@ A **published** dsh needs no extra setup. Booting the harness from its **source
 
 ## Version compatibility
 
-dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
+dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harness version>-rcN`. From `0.1.7-rc1` on, **one release serves two harness generations**: the 0.1.5 line (`>=0.1.5-rc.1 <0.1.6-0`, all sharing the old settings API) and the 0.1.7 line (`>=0.1.7-rc.1 <0.1.8-0`, whose `rc.1` and `rc.2` are both verified). It detects the running generation at load and takes the matching code path, so a single published package installs onto either. Every harness package it consumes declares that union range in `peerDependencies`; a harness outside it fails loudly at boot or session resume. Within a covered line a new `rc` needs no plugin release unless the API surfaces it depends on moved — `docs/compatibility.md` §1 lists the surfaces and the diff command that decides it. Read `rcN` as **this plugin's own release counter for that harness line**, not as the harness's `rc` number (`0.1.7-rc1` … `0.1.7-rc5` all serve `0.1.7-rc.1` and `0.1.7-rc.2`). `0.1.7-rc1` … `0.1.7-rc5` target harness `0.1.7-rc.2`; `0.1.5-rc3` … `0.1.5-rc5` target harness `0.1.5-rc.2`; `0.1.5-rc1`/`0.1.5-rc2` target `0.1.5-rc.1`; `1.0.0-rc8` … `1.0.0-rc15` target `0.1.2-rc.1`; `1.0.0-rc7` and earlier target `0.1.1-rc.2`.
 
 ### Requirements
 
@@ -48,6 +48,7 @@ dsh-loop-engine is versioned **in lockstep with the harness it targets**: `<harn
 
 - Its preset is a copy of `standard` minus the dsh-native rows an external engine replaces — dsh's `/plan`, `/compact` (and auto-compaction), the model-facing goal tool, the human `/goal` command, and the dsh skill rows (one stripped preset per engine). The preset is a harness-generation-dependent artifact: a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>/` on the 0.1.5 line, and an `@deepseek-ai/dsh-agent-preset` row inserted into the profile patch on the 0.1.7 line, which no longer reads that directory. See [docs/architecture.md](docs/architecture.md) §3.5.
 - The engine's own slash commands and skill catalog are registered into **that agent's own scope**, so two sessions on different engines never see each other's menus, and the whole surface is released with the agent.
+- **Kimi Code and Codex keep ONE child process per session** (`kimi acp` / `codex app-server`), reused across steps — that is what saves a spawn per step, and it also means a session that finished a turn and is left alone keeps paying for that process (the harness does not release an agent at turn end). Claude Code and Pi spawn per step and hold nothing. Set `childIdleMs` (milliseconds) in the composition entry — the plugin's row in the profile's `cordis.patch.yml` — to shut an idle session's child down, respawning it on the next step; `0` or omitted keeps the child for the session's whole life, which is the default. It closes the child only: the agent, the session, and the page are untouched, so nothing reloads and `session/disposed` is never emitted. See [docs/driver-core.md](docs/driver-core.md) §7.8.
 - Engine-agnostic dsh commands (`/export`, `/feedback`, `/permission`) keep working and stay.
 
 ## Known limitations

package/README.zh.md

@@ -22,7 +22,7 @@ dsh plugin --profile web add dsh-loop-engine
 
 ## 版本兼容
 
-`dsh-loop-engine` 与它针对的 harness **同版本对齐**:`<harness version>-rcN`。自 `0.1.7-rc1` 起,**一个发布版本同时服务两代 harness**:0.1.5 线(`>=0.1.5-rc.1 <0.1.6-0`,三段 `rc` 共用同一套旧 settings API)与 0.1.7 线(`>=0.1.7-rc.1 <0.1.8-0`,其中 `rc.1` 与 `rc.2` 都已核对)。它在加载期探测当前是哪一代、走对应分支,所以同一份已发布产物在两代上都能安装运行。它消费的每个 harness 包都在 `peerDependencies` 里声明这个并集范围;超出范围会在启动或会话恢复时响亮地失败。在被覆盖的那条线里,新的 `rc` **不需要**插件跟版——除非它依赖的 API 面动了;`docs/compatibility.md` §1 列出了这些面与"要不要改代码"的那条判定命令。`0.1.5-rc3` … `0.1.5-rc5` 针对 harness `0.1.5-rc.2`;`0.1.5-rc1`/`0.1.5-rc2` 针对 `0.1.5-rc.1`;`1.0.0-rc8` … `1.0.0-rc15` 针对 `0.1.2-rc.1`;`1.0.0-rc7` 及更早针对 `0.1.1-rc.2`。
+`dsh-loop-engine` 与它针对的 harness **同版本对齐**:`<harness version>-rcN`。自 `0.1.7-rc1` 起,**一个发布版本同时服务两代 harness**:0.1.5 线(`>=0.1.5-rc.1 <0.1.6-0`,三段 `rc` 共用同一套旧 settings API)与 0.1.7 线(`>=0.1.7-rc.1 <0.1.8-0`,其中 `rc.1` 与 `rc.2` 都已核对)。它在加载期探测当前是哪一代、走对应分支,所以同一份已发布产物在两代上都能安装运行。它消费的每个 harness 包都在 `peerDependencies` 里声明这个并集范围;超出范围会在启动或会话恢复时响亮地失败。在被覆盖的那条线里,新的 `rc` **不需要**插件跟版——除非它依赖的 API 面动了;`docs/compatibility.md` §1 列出了这些面与"要不要改代码"的那条判定命令。`rcN` 读作**本插件对那条 harness 线的第 N 次发布号**,不是 harness 自己的 `rc` 号(`0.1.7-rc1` … `0.1.7-rc5` 都服务 `0.1.7-rc.1` 与 `0.1.7-rc.2`)。`0.1.7-rc1` … `0.1.7-rc5` 针对 harness `0.1.7-rc.2`;`0.1.5-rc3` … `0.1.5-rc5` 针对 harness `0.1.5-rc.2`;`0.1.5-rc1`/`0.1.5-rc2` 针对 `0.1.5-rc.1`;`1.0.0-rc8` … `1.0.0-rc15` 针对 `0.1.2-rc.1`;`1.0.0-rc7` 及更早针对 `0.1.1-rc.2`。
 
 ### 环境要求
 

package/lib/index.js

@@ -2389,6 +2389,34 @@ import { LlmError as LlmError3, createAssistantMessage as createAssistantMessage
 import { createScope as createScope2 } from "@deepseek-ai/dsh-scope";
 import { canonicalHeader as canonicalHeader2 } from "@deepseek-ai/dsh-session";
 
+// src/driver-core/idle-child.ts
+function createIdleChildCloser(options) {
+  const { idleMs, close, warn } = options;
+  let timer;
+  const cancel = () => {
+    if (timer === void 0) return;
+    clearTimeout(timer);
+    timer = void 0;
+  };
+  return {
+    arm: () => {
+      if (!(idleMs > 0)) return;
+      cancel();
+      timer = setTimeout(() => {
+        timer = void 0;
+        try {
+          close();
+        } catch (error) {
+          warn(`loop-engine: idle shutdown failed to close a child process: ${String(error)}`);
+        }
+      }, idleMs);
+      timer.unref?.();
+    },
+    cancel,
+    dispose: cancel
+  };
+}
+
 // src/engine-codex/model-handover.ts
 var CODEX_DSH_PROVIDER = "dsh";
 var CODEX_DSH_API_KEY_ENV = "DSH_LOOP_ENGINE_API_KEY";
@@ -2928,9 +2956,18 @@ var CodexAgent = class {
     this.phase = { kind: "idle", lastTurn };
     this.scope = createScope2(loopCtx, this);
     this.ctx = this.scope.ctx.extend({ agent: this });
+    this.idleChild = createIdleChildCloser({
+      idleMs: this.config.childIdleMs,
+      close: () => {
+        this.closeChild();
+      },
+      warn: (message) => {
+        loopCtx.logger.warn(message);
+      }
+    });
     this.scope.ctx.effect(() => () => {
-      this.appServer?.dispose();
-      this.appServer = void 0;
+      this.idleChild.dispose();
+      this.closeChild();
     }, "codex.appServerClient()");
   }
   loopCtx;
@@ -2982,6 +3019,17 @@ var CodexAgent = class {
    * must respawn the child rather than reuse one configured for another endpoint.
    */
   appServerConfig;
+  /**
+   * Countdown that shuts the child down once this agent has been idle past the
+   * configured window, so an idle session stops paying for a process nothing
+   * is driving. Armed and cancelled by {@link setPhase}.
+   */
+  idleChild;
+  /** Shut the cached child down; the next step's {@link appServerClient} spawns a fresh one. */
+  closeChild() {
+    this.appServer?.dispose();
+    this.appServer = void 0;
+  }
   /**
    * Return the cached app-server client, spawning one on first use, after a dead
    * process, or when the resolved dsh endpoint changed since the last spawn.
@@ -3075,6 +3123,8 @@ var CodexAgent = class {
   setPhase(next) {
     const previousStatus = this.status;
     this.phase = next;
+    if (next.kind === "idle") this.idleChild.arm();
+    else this.idleChild.cancel();
     const status = this.status;
     if (status !== previousStatus) {
       this.dispatch.emit("agent/status", { status });
@@ -3610,14 +3660,16 @@ var Config2 = z2.object({
   sandboxMode: z2.union([...CODEX_SANDBOX_MODES]),
   approvalPolicy: z2.union([...CODEX_APPROVAL_POLICIES]),
   env: z2.dict(z2.string()).default({}),
-  model: z2.string()
+  model: z2.string(),
+  childIdleMs: z2.number()
 });
 function resolveConfig2(config) {
   return {
     sandboxMode: config.sandboxMode,
     approvalPolicy: config.approvalPolicy,
     env: config.env ?? {},
-    model: config.model
+    model: config.model,
+    childIdleMs: config.childIdleMs ?? 0
   };
 }
 var CODEX_ENGINE_LABEL = "agentLoopCodex";
@@ -5122,9 +5174,18 @@ var KimiAgent = class {
     this.phase = { kind: "idle", lastTurn };
     this.scope = createScope4(loopCtx, this);
     this.ctx = this.scope.ctx.extend({ agent: this });
+    this.idleChild = createIdleChildCloser({
+      idleMs: this.config.childIdleMs,
+      close: () => {
+        this.closeChild();
+      },
+      warn: (message) => {
+        loopCtx.logger.warn(message);
+      }
+    });
     this.scope.ctx.effect(() => () => {
-      this.acp?.dispose();
-      this.acp = void 0;
+      this.idleChild.dispose();
+      this.closeChild();
     }, "kimi.acpClient()");
   }
   loopCtx;
@@ -5157,6 +5218,17 @@ var KimiAgent = class {
    * every step.
    */
   handoverEnvCache;
+  /**
+   * Countdown that shuts the child down once this agent has been idle past the
+   * configured window, so an idle session stops paying for a process nothing
+   * is driving. Armed and cancelled by {@link setPhase}.
+   */
+  idleChild;
+  /** Shut the cached child down; the next step's {@link acpClient} spawns a fresh one. */
+  closeChild() {
+    this.acp?.dispose();
+    this.acp = void 0;
+  }
   get status() {
     return this.phase.kind === "idle" || this.phase.kind === "maintenance" ? "idle" : "running";
   }
@@ -5164,6 +5236,8 @@ var KimiAgent = class {
   setPhase(next) {
     const previousStatus = this.status;
     this.phase = next;
+    if (next.kind === "idle") this.idleChild.arm();
+    else this.idleChild.cancel();
     const status = this.status;
     if (status !== previousStatus) {
       this.dispatch.emit("agent/status", { status });
@@ -5732,13 +5806,15 @@ var KIMI_DISPOSE_GRACE_MS = 3e3;
 var Config4 = z4.object({
   model: z4.string(),
   env: z4.dict(z4.string()).default({}),
-  bin: z4.string()
+  bin: z4.string(),
+  childIdleMs: z4.number()
 });
 function resolveConfig4(config) {
   return {
     model: config.model,
     env: config.env ?? {},
-    bin: kimiBinResolver(config.bin)
+    bin: kimiBinResolver(config.bin),
+    childIdleMs: config.childIdleMs ?? 0
   };
 }
 var KIMI_ENGINE_LABEL = "agentLoopKimi";
@@ -7498,6 +7574,7 @@ var Config5 = z6.object({
   piProvider: z6.string(),
   piThinking: z6.string(),
   kimiBin: z6.string(),
+  childIdleMs: z6.number(),
   // The live fields exist only on the 0.1.7 line; the 0.1.5 line carries the
   // selection in a settings section instead. The empty arm never runs when the
   // coverage job is on 0.1.7; the 0.1.5 dep set is exercised by
@@ -7568,7 +7645,8 @@ function codexConfig(config) {
     ...config.sandboxMode === void 0 ? {} : { sandboxMode: config.sandboxMode },
     ...config.approvalPolicy === void 0 ? {} : { approvalPolicy: config.approvalPolicy },
     ...config.env === void 0 ? {} : { env: config.env },
-    ...config.model === void 0 ? {} : { model: config.model }
+    ...config.model === void 0 ? {} : { model: config.model },
+    ...config.childIdleMs === void 0 ? {} : { childIdleMs: config.childIdleMs }
   };
 }
 function piConfig(config) {
@@ -7584,7 +7662,8 @@ function kimiConfig(config) {
   return {
     ...config.model === void 0 ? {} : { model: config.model },
     ...config.env === void 0 ? {} : { env: config.env },
-    ...config.kimiBin === void 0 ? {} : { bin: config.kimiBin }
+    ...config.kimiBin === void 0 ? {} : { bin: config.kimiBin },
+    ...config.childIdleMs === void 0 ? {} : { childIdleMs: config.childIdleMs }
   };
 }
 function apply(ctx, config) {

package/lib/types/driver-core/idle-child.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Idle shutdown for a driver's persistent child process.
+ *
+ * Two engines keep one child alive per session so a step never pays a spawn:
+ * Kimi's `kimi acp` and Codex's app-server. Nothing in the harness releases an
+ * agent when a turn ends — an agent lives as long as its session's scope — so
+ * that child outlives the work that needed it and an idle session keeps
+ * costing what its child costs (tens to hundreds of MB for a Node CLI). The
+ * closer arms a countdown whenever its owner goes idle and runs the owner's
+ * close when the countdown expires, so the next step's own lazy accessor
+ * spawns a fresh child.
+ *
+ * The closer is inert unless `idleMs` is positive: a deployment that does not
+ * configure idle shutdown keeps every child for the process's lifetime, which
+ * is the behaviour that predates this reasoner.
+ *
+ * This is deliberately NOT an agent release: disposing the agent emits
+ * `session/disposed`, which the browser half reads as "this session is gone"
+ * with no way back in that page's lifetime (`router-loop.ts` `move`). Closing
+ * the child leaves the agent, the session, and the page exactly where they are.
+ *
+ * @module dsh-loop-engine/driver-core/idle-child
+ */
+/** An armed-on-idle countdown that closes one child process. */
+export interface IdleChildCloser {
+    /**
+     * (Re)start the countdown. Called when the owner settles into an idle phase;
+     * a no-op while idle shutdown is disabled.
+     */
+    arm(): void;
+    /**
+     * Cancel a pending countdown, for the moment the child is needed again.
+     * Cancelling a countdown that never armed is a no-op.
+     */
+    cancel(): void;
+    /**
+     * Cancel the countdown and drop the timer. Called from the owner's teardown,
+     * so a disposed agent never closes a child through a stale callback.
+     */
+    dispose(): void;
+}
+/** Input of {@link createIdleChildCloser}. */
+export interface IdleChildCloserOptions {
+    /** Idle window in milliseconds; zero or less leaves the child alone forever. */
+    readonly idleMs: number;
+    /** Close the child; the owner's next accessor call spawns a fresh one. */
+    readonly close: () => void;
+    /** Report a failing close without letting it escape the countdown. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Build one owner's idle countdown.
+ * @param options - the idle window, the close to run, and a diagnostic sink.
+ * @returns the closer, inert while the idle window is not positive.
+ */
+export declare function createIdleChildCloser(options: IdleChildCloserOptions): IdleChildCloser;
+//# sourceMappingURL=idle-child.d.ts.map

package/lib/types/engine-codex/agent.d.ts

@@ -70,7 +70,15 @@ export declare class CodexAgent implements Agent {
      * must respawn the child rather than reuse one configured for another endpoint.
      */
     private appServerConfig;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    /** Shut the cached child down; the next step's {@link appServerClient} spawns a fresh one. */
+    private closeChild;
     /**
      * Return the cached app-server client, spawning one on first use, after a dead
      * process, or when the resolved dsh endpoint changed since the last spawn.

package/lib/types/engine-codex/loop.d.ts

@@ -40,6 +40,12 @@ export interface Config {
     env?: Record<string, string>;
     /** Fallback model for the app-server thread, used when the session selects none; Codex native settings own the model when omitted. */
     model?: string;
+    /**
+     * Idle window in milliseconds before a session's `codex app-server` child is
+     * shut down, spawned again by the next step. Omitted or non-positive keeps
+     * the child for the session's whole life.
+     */
+    childIdleMs?: number;
 }
 /** Schema of the Codex loop plugin configuration. */
 export declare const Config: z<Config>;

package/lib/types/engine-codex/types.d.ts

@@ -15,5 +15,12 @@ export interface ResolvedConfig {
     readonly approvalPolicy: CodexApprovalPolicy | undefined;
     readonly env: Record<string, string>;
     readonly model: string | undefined;
+    /**
+     * How long an idle session keeps its `codex app-server` child, in
+     * milliseconds; zero or less keeps it for the session's whole life. See
+     * `driver-core/idle-child.ts` for why the child, and not the agent, is what
+     * gets released.
+     */
+    readonly childIdleMs: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types/engine-kimi/agent.d.ts

@@ -56,7 +56,15 @@ export declare class KimiAgent implements Agent {
      * every step.
      */
     private handoverEnvCache;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: KimiSpawnCapability, bin: string);
+    /** Shut the cached child down; the next step's {@link acpClient} spawns a fresh one. */
+    private closeChild;
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
     private setPhase;

package/lib/types/engine-kimi/loop.d.ts

@@ -32,6 +32,12 @@ export interface Config {
     env?: Record<string, string>;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     bin?: string;
+    /**
+     * Idle window in milliseconds before a session's `kimi acp` child is shut
+     * down, spawned again by the next step. Omitted or non-positive keeps the
+     * child for the session's whole life.
+     */
+    childIdleMs?: number;
 }
 /** Schema of the Kimi loop plugin configuration. */
 export declare const Config: z<Config>;

package/lib/types/engine-kimi/types.d.ts

@@ -19,5 +19,12 @@ export interface ResolvedConfig {
     readonly env: Record<string, string>;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     readonly bin: string;
+    /**
+     * How long an idle session keeps its `kimi acp` child, in milliseconds; zero
+     * or less keeps it for the session's whole life. See
+     * `driver-core/idle-child.ts` for why the child, and not the agent, is what
+     * gets released.
+     */
+    readonly childIdleMs: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -74,6 +74,14 @@ export interface Config extends ClaudeCodeConfig {
     piThinking?: string;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     kimiBin?: string;
+    /**
+     * Idle window in milliseconds after which a hosted session's PERSISTENT child
+     * process (Kimi's `kimi acp`, Codex's app-server) is shut down and spawned
+     * again by the next step. Zero or omitted keeps the child for the session's
+     * whole life. Only these two engines hold a child between steps: the Pi and
+     * Claude Code drivers spawn per step, so the knob does not reach them.
+     */
+    childIdleMs?: number;
     /**
      * Default engine NEW sessions are created on. A live, profile-backed field:
      * the settings shell edits it and the running plugin reads it through this

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-loop-engine",
   "description": "Web-switchable agent loop engine selection for the DeepSeek Harness - out-of-tree plugin (Claude Code / Codex / Pi / Kimi Code drivers) maintained by @kuun993, zero main-repo changes",
-  "version": "0.1.7-rc4",
+  "version": "0.1.7-rc5",
   "publishConfig": {
     "access": "public"
   },