@pikiloom/kernel 0.3.17 → 0.3.18

package/dist/contracts/driver.d.ts

@@ -79,6 +79,7 @@ export interface DriverResult {
     sessionId?: string | null;
     usage?: UniversalUsage | null;
     anchor?: string | null;
+    transport?: 'cold' | 'warm' | null;
 }
 export interface TuiInput {
     workdir: string;

package/dist/drivers/claude-pool.d.ts

@@ -0,0 +1,20 @@
+import type { ChildProcess } from 'node:child_process';
+export declare function claudeWarmIdleTtlMs(): number;
+export declare function claudeWarmMaxProcesses(): number;
+export declare class ClaudeWarmPool {
+    private readonly parked;
+    size(): number;
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId: string, fingerprint: string): ChildProcess | null;
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId: string, fingerprint: string, child: ChildProcess): void;
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId: string): void;
+    dispose(): void;
+    /** Remove bookkeeping without deciding the child's fate. */
+    private unpark;
+}

package/dist/drivers/claude-pool.js

@@ -0,0 +1,125 @@
+import { sigterm } from './shared.js';
+// ── Warm Claude process pool ─────────────────────────────────────────────────────────
+// A `claude -p --input-format stream-json` process stays alive after `result` for as long
+// as its stdin is open, and a user message written to that stdin runs a NEW turn in the
+// same conversation (the steer path has always relied on this). Every cold spawn costs
+// ~4s of CLI init before the first model request — the single largest local overhead of a
+// Claude turn — so after a clean settle the driver parks the process here instead of
+// killing it, and the session's next continuation turn skips the spawn entirely.
+//
+// Discipline (mirrors mirasim's Codex warm pool):
+//  - keyed by native session id; one process per session, serial turns only.
+//  - a process is reused only when its spawn-time fingerprint (model/effort/workdir/…)
+//    still matches what a cold spawn would use; any drift destroys it and goes cold.
+//  - idle processes are destroyed after a TTL; the pool is size-capped (oldest-idle out).
+//  - only CLEAN settles pool (no error / abort / timeout / background hold); everything
+//    else keeps today's kill semantics, so pooling can never leak a wedged process.
+// Idle TTL before a parked process is destroyed. Override with PIKILOOM_CLAUDE_WARM_IDLE_MS.
+const CLAUDE_WARM_IDLE_TTL_DEFAULT_MS = 10 * 60_000;
+export function claudeWarmIdleTtlMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_IDLE_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_WARM_IDLE_TTL_DEFAULT_MS;
+}
+// Max parked processes (each holds a full CLI + its MCP servers — roughly 0.5–1 GB).
+// Override with PIKILOOM_CLAUDE_WARM_MAX.
+const CLAUDE_WARM_MAX_DEFAULT = 4;
+export function claudeWarmMaxProcesses() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_WARM_MAX);
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : CLAUDE_WARM_MAX_DEFAULT;
+}
+// After ending a parked process's stdin, force-kill only if it hasn't exited on its own
+// within this window — same leak-guard shape as a graceful turn settle.
+const CLAUDE_WARM_DESTROY_GUARD_MS = 15_000;
+/** End a no-longer-poolable process the same way a graceful settle does. */
+function destroyClaudeChild(child) {
+    try {
+        child.stdin?.end();
+    }
+    catch { /* ignore */ }
+    if (child.exitCode != null || child.killed)
+        return;
+    const guard = setTimeout(() => sigterm(child), CLAUDE_WARM_DESTROY_GUARD_MS);
+    if (typeof guard.unref === 'function')
+        guard.unref();
+}
+export class ClaudeWarmPool {
+    parked = new Map();
+    size() {
+        return this.parked.size;
+    }
+    /**
+     * Reclaim the parked process for `sessionId`, or null when there is none, it died while
+     * parked, or its spawn fingerprint no longer matches (that entry is destroyed — the turn
+     * must go cold so the new model/effort/config actually applies).
+     */
+    take(sessionId, fingerprint) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return null;
+        this.unpark(sessionId, entry);
+        if (entry.child.exitCode != null || entry.child.killed)
+            return null;
+        if (entry.fingerprint !== fingerprint) {
+            destroyClaudeChild(entry.child);
+            return null;
+        }
+        return entry.child;
+    }
+    /** Park a process after a clean settle. The caller has already detached its turn listeners. */
+    put(sessionId, fingerprint, child) {
+        if (child.exitCode != null || child.killed || !child.stdin || child.stdin.destroyed) {
+            destroyClaudeChild(child);
+            return;
+        }
+        this.evictSession(sessionId); // never two processes for one session
+        while (this.parked.size >= Math.max(claudeWarmMaxProcesses(), 0)) {
+            const oldest = [...this.parked.entries()].sort((a, b) => a[1].parkedAt - b[1].parkedAt)[0];
+            if (!oldest)
+                break;
+            this.evictSession(oldest[0]);
+        }
+        if (claudeWarmMaxProcesses() <= 0) {
+            destroyClaudeChild(child);
+            return;
+        }
+        const onClose = () => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child) {
+                this.unpark(sessionId, cur);
+            }
+        };
+        // Keep both pipes flowing while parked so the CLI can never block on a full pipe.
+        const drain = () => { };
+        child.stdout?.on('data', drain);
+        child.stderr?.on('data', drain);
+        child.on('close', onClose);
+        const idleTimer = setTimeout(() => {
+            const cur = this.parked.get(sessionId);
+            if (cur?.child === child)
+                this.evictSession(sessionId);
+        }, claudeWarmIdleTtlMs());
+        if (typeof idleTimer.unref === 'function')
+            idleTimer.unref();
+        this.parked.set(sessionId, { child, fingerprint, parkedAt: Date.now(), idleTimer, onClose, drain });
+    }
+    /** Destroy the parked process for a session (rewind made its in-memory context stale, TTL, cap). */
+    evictSession(sessionId) {
+        const entry = this.parked.get(sessionId);
+        if (!entry)
+            return;
+        this.unpark(sessionId, entry);
+        destroyClaudeChild(entry.child);
+    }
+    dispose() {
+        for (const sessionId of [...this.parked.keys()])
+            this.evictSession(sessionId);
+    }
+    /** Remove bookkeeping without deciding the child's fate. */
+    unpark(sessionId, entry) {
+        clearTimeout(entry.idleTimer);
+        entry.child.stdout?.off('data', entry.drain);
+        entry.child.stderr?.off('data', entry.drain);
+        entry.child.off('close', entry.onClose);
+        this.parked.delete(sessionId);
+    }
+}

package/dist/drivers/claude.d.ts

@@ -1,5 +1,12 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
 import type { UniversalPlan } from '../protocol/index.js';
+export interface ClaudeDriverOptions {
+    /** Keep the CLI process alive after a clean turn and reuse it for the session's next
+     *  continuation turn (skips the ~4s spawn+init). Off by default: a parked process holds
+     *  real memory and keeps the event loop alive, which a one-shot embedder must not inherit
+     *  silently. Long-lived hosts opt in and call dispose() on shutdown. */
+    warmPool?: boolean;
+}
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -11,7 +18,12 @@ export declare class ClaudeDriver implements AgentDriver {
         fork: boolean;
         rewind: boolean;
     };
-    constructor(bin?: string);
+    private readonly pool;
+    constructor(bin?: string, opts?: ClaudeDriverOptions);
+    /** Destroy every parked warm process. Long-lived hosts call this on shutdown. */
+    dispose(): void;
+    /** Parked warm processes right now (tests + telemetry). */
+    warmPoolSize(): number;
     tui(input: TuiInput): TuiSpec;
     listNativeSessions(opts: {
         workdir: string;
@@ -24,6 +36,7 @@ export declare class ClaudeDriver implements AgentDriver {
         workdir: string;
     }): string | null;
 }
+export declare function claudeProcessFingerprint(bin: string, input: AgentTurnInput): string;
 export declare function claudeResumeArgs(sessionId: string, fork?: {
     anchor?: string | null;
 } | null, rewind?: {

package/dist/drivers/claude.js

@@ -1,17 +1,24 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { ClaudeWarmPool } from './claude-pool.js';
 import { claudeTranscriptTailAnchor, discoverClaudeNativeSessions } from './native.js';
 import { attachedFileNote, contextPercent, createLineBuffer, imageMimeForFile, parseJsonLine, sigterm, wireAbort } from './shared.js';
-// Real driver: shells the local `claude` CLI in stream-json mode and normalizes its
-// events into kernel DriverEvents. Faithful to pikiloom's claude.ts event shapes
-// (system / stream_event{message_start,content_block_delta,message_delta} / assistant / result),
-// but fully self-contained. Proves "下层 Claude 不变".
 export class ClaudeDriver {
     bin;
     id = 'claude';
     capabilities = { steer: true, interact: false, resume: true, tui: true, fork: true, rewind: true };
-    constructor(bin = 'claude') {
+    pool;
+    constructor(bin = 'claude', opts = {}) {
         this.bin = bin;
+        this.pool = opts.warmPool ? new ClaudeWarmPool() : null;
+    }
+    /** Destroy every parked warm process. Long-lived hosts call this on shutdown. */
+    dispose() {
+        this.pool?.dispose();
+    }
+    /** Parked warm processes right now (tests + telemetry). */
+    warmPoolSize() {
+        return this.pool?.size() ?? 0;
     }
     // Interactive Claude Code TUI (no -p): the kernel spawns this in a PTY and passes
     // the terminal through. Model/resume/BYOK-env come from the kernel's resolution.
@@ -54,6 +61,17 @@ export class ClaudeDriver {
             args.push('--replay-user-messages'); // parity: mid-turn steer
         if (input.extraArgs?.length)
             args.push(...input.extraArgs);
+        // Warm reuse: a rewind rebranches the session's transcript, so a parked process's
+        // in-memory conversation is stale — destroy it. A fork never touches the parent's
+        // transcript (the parked parent stays valid); the fork turn itself must cold-spawn
+        // for its --fork-session flags. Only a plain continuation may reclaim a process, and
+        // only when the spawn fingerprint still matches what a cold spawn would use now.
+        const fingerprint = claudeProcessFingerprint(this.bin, input);
+        if (input.rewind && input.sessionId)
+            this.pool?.evictSession(input.sessionId);
+        const pooled = (!input.fork && !input.rewind && input.sessionId && this.pool)
+            ? this.pool.take(input.sessionId, fingerprint)
+            : null;
         const state = {
             text: '', reasoning: '', streamedText: false, streamedReasoning: false,
             // Dangling-tool-loop tracking: sawToolResult flips on the first tool_result; textSinceToolResult
@@ -82,6 +100,8 @@ export class ClaudeDriver {
         };
         return new Promise((resolve) => {
             let child;
+            let transport = 'cold';
+            let promptDelivered = false;
             let settled = false;
             // One-shot guard for the truncated-turn recovery injection (see the result handler).
             let truncatedRecoveryAttempted = false;
@@ -101,6 +121,8 @@ export class ClaudeDriver {
             const usageOf = () => this.usage(state);
             const unref = (tm) => { if (tm && typeof tm.unref === 'function')
                 tm.unref(); };
+            let disposeAbort = null;
+            let detachTurnListeners = () => { };
             const clearHoldCap = () => { if (holdCapTimer) {
                 clearTimeout(holdCapTimer);
                 holdCapTimer = null;
@@ -118,18 +140,29 @@ export class ClaudeDriver {
             // kill=false only ends stdin and lets Claude shut down on its own, so any still-running
             // detached background work survives a clean exit (a hard kill mid-flight is exactly what
             // tore the background — and the wake-up — down before). A leak-guard SIGTERM is the backstop.
-            const finish = (r, kill = true) => {
+            const finish = (r, kill = true, park = false) => {
                 if (settled)
                     return;
                 settled = true;
                 clearHoldCap();
                 clearQuiet();
                 clearModelStall();
+                disposeAbort?.();
+                // Park instead of kill: only a CLEAN settle qualifies (ok, no error, no abort, the
+                // process still healthy, session known) — every other exit keeps today's semantics,
+                // so pooling can never leak a wedged or errored process.
+                if (park && this.pool && state.sessionId && r.ok && !r.error && !ctx.signal.aborted
+                    && child && !child.killed && child.exitCode == null) {
+                    detachTurnListeners();
+                    this.pool.put(state.sessionId, fingerprint, child);
+                    resolve({ ...r, transport });
+                    return;
+                }
                 try {
                     child?.stdin?.end();
                 }
                 catch { /* ignore */ }
-                if (!child.killed && child.exitCode == null) {
+                if (child && !child.killed && child.exitCode == null) {
                     if (kill)
                         sigterm(child);
                     else {
@@ -137,12 +170,12 @@ export class ClaudeDriver {
                         unref(guard);
                     }
                 }
-                resolve(r);
+                resolve({ ...r, transport });
             };
             const settleResult = (opts = {}) => finish({
                 ok: opts.ok ?? !state.error, text: state.text, reasoning: state.reasoning || undefined,
                 error: state.error, stopReason: opts.stopReason ?? state.stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf(),
-            }, opts.kill ?? true);
+            }, opts.kill ?? true, opts.park ?? false);
             // Cap while holding for a still-running background task (stopReason marks it as
             // "still running in the background" so the terminal presentation reads right). Idempotent —
             // the countdown is absolute from the first arm. Sub-agent-backed holds use the longer
@@ -199,14 +232,32 @@ export class ClaudeDriver {
                 }, claudeModelStallMs(input.effort));
                 unref(modelStallTimer);
             };
-            try {
-                child = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+            // Acquire the process: a reclaimed warm process gets the prompt as its acquisition
+            // probe — a dead pipe throws synchronously here and the turn transparently falls
+            // back to a cold spawn (whose --resume flags are already in `args`).
+            let acquired = null;
+            if (pooled) {
+                try {
+                    pooled.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+                    acquired = pooled;
+                    transport = 'warm';
+                    promptDelivered = true;
+                }
+                catch {
+                    sigterm(pooled);
+                }
             }
-            catch (err) {
-                finish({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
-                return;
+            if (!acquired) {
+                try {
+                    acquired = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+                }
+                catch (err) {
+                    finish({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
+                    return;
+                }
             }
-            wireAbort(ctx.signal, () => sigterm(child));
+            child = acquired;
+            disposeAbort = wireAbort(ctx.signal, () => sigterm(child));
             if (steerable) {
                 ctx.registerSteer(async (prompt, attachments) => {
                     try {
@@ -220,7 +271,7 @@ export class ClaudeDriver {
             }
             const nextLines = createLineBuffer();
             let stderr = '';
-            child.stdout.on('data', (chunk) => {
+            const onStdout = (chunk) => {
                 if (settled)
                     return; // ignore the process's post-settle shutdown chatter
                 for (const line of nextLines(chunk)) {
@@ -299,8 +350,10 @@ export class ClaudeDriver {
                             // DELIVERED live but never lands in the transcript, so the next re-render erases
                             // it (the "对话结束之后就被吞了" shape, caught by the turn audit). Ending stdin
                             // lets the CLI finish writing and exit on its own; the leak-guard SIGTERM is the
-                            // backstop.
-                            settleResult({ kill: false });
+                            // backstop. park: this clean settle is the ONE warm-pool-eligible exit — the
+                            // process (stdin open, transcript flushing in its own time) is parked for the
+                            // session's next turn instead of being shut down; finish() re-checks health.
+                            settleResult({ kill: false, park: true });
                             return;
                         }
                         if (decision === 'hold') {
@@ -332,10 +385,10 @@ export class ClaudeDriver {
                     if (ev.type === 'user' && pending === 0 && claudeUserEventHasToolResult(ev))
                         armModelStall();
                 }
-            });
-            child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
-            child.on('error', (err) => finish({ ok: false, text: state.text, error: `claude spawn error: ${err.message}`, stopReason: 'error' }));
-            child.on('close', (code) => {
+            };
+            const onStderr = (c) => { stderr += c.toString('utf8'); };
+            const onError = (err) => finish({ ok: false, text: state.text, error: `claude spawn error: ${err.message}`, stopReason: 'error' });
+            const onClose = (code) => {
                 if (settled)
                     return;
                 if (ctx.signal.aborted) {
@@ -349,13 +402,27 @@ export class ClaudeDriver {
                 // dangling check must win over it.)
                 const stopReason = (ok && claudeTurnEndedDangling(state)) ? 'truncated' : state.stopReason;
                 finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf() }, false);
-            });
-            try {
-                // Send the prompt as a stream-json user message and keep stdin OPEN (do not end it here):
-                // closing it makes Claude exit at the first `result`, before any background task finishes.
-                child.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+            };
+            // Parking hands the process to the pool — these turn-scoped listeners must not
+            // outlive the turn (the pool installs its own drain + close bookkeeping).
+            detachTurnListeners = () => {
+                child.stdout?.off('data', onStdout);
+                child.stderr?.off('data', onStderr);
+                child.off('error', onError);
+                child.off('close', onClose);
+            };
+            child.stdout.on('data', onStdout);
+            child.stderr.on('data', onStderr);
+            child.on('error', onError);
+            child.on('close', onClose);
+            if (!promptDelivered) {
+                try {
+                    // Send the prompt as a stream-json user message and keep stdin OPEN (do not end it here):
+                    // closing it makes Claude exit at the first `result`, before any background task finishes.
+                    child.stdin.write(claudeUserMessage(input.prompt, input.attachments) + '\n');
+                }
+                catch { /* ignore */ }
             }
-            catch { /* ignore */ }
         });
     }
     usage(s) {
@@ -367,6 +434,38 @@ export class ClaudeDriver {
         return claudeTranscriptTailAnchor(opts.workdir, opts.sessionId);
     }
 }
+// The spawn-time facts that must still match for a parked warm process to serve a
+// continuation turn as if it were a fresh cold `--resume` — any drift (model switch,
+// effort change, new MCP config, different BYOK env, …) destroys the parked process so
+// the new configuration actually applies. `sessionId` is the pool key, not fingerprint
+// material, and `systemPrompt` is deliberately EXCLUDED: it is a first-turn-only input
+// (the parked process already carries it applied; a cold --resume would not re-send it
+// either), so including it would make every continuation miss the pool. Pure + exported
+// for hermetic testing.
+export function claudeProcessFingerprint(bin, input) {
+    return JSON.stringify([
+        bin, input.workdir, input.model ?? null, input.effort ?? null,
+        input.mcpConfigPath ?? null, input.permissionMode ?? null, !!input.steerable,
+        fingerprintExtraArgs(input.extraArgs),
+        Object.entries(input.env ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ]);
+}
+// `--session-id <uuid>` pins a FRESH session's native id and is contributed on the first
+// turn only (continuations resume instead) — it names the session, it doesn't configure
+// the process. Like sessionId itself it must not be fingerprint material, or every
+// continuation of a session born with it would miss the pool forever.
+function fingerprintExtraArgs(extraArgs) {
+    const args = extraArgs ?? [];
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--session-id') {
+            i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
 // The --resume flag family for one turn: plain resume appends to the session; a fork branches
 // a NEW session off it (--fork-session), optionally cut at an inclusive keep-boundary record
 // uuid (--resume-session-at); a rewind cuts at that boundary WITHOUT --fork-session, so claude

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, To
 export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 export { EchoDriver } from './drivers/echo.js';
-export { ClaudeDriver } from './drivers/claude.js';
+export { ClaudeDriver, type ClaudeDriverOptions } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
 export { AcpDriver, type AcpDriverConfig } from './drivers/acp.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Heterogeneous coding agents (Claude / Codex / Gemini / ACP) -> an interaction-friendly, accumulating session snapshot + control handle, over pluggable surfaces (IM, Web, tunnel, TUI). The reusable core pikiloom itself is built on.",
   "type": "module",
   "license": "MIT",