@pikiloom/kernel 0.2.21 → 0.3.1

package/dist/drivers/codex.js

@@ -1,112 +1,6 @@
-import { spawn } from 'node:child_process';
-import { discoverCodexNativeSessions } from '../workspace/native.js';
-// Minimal newline-delimited JSON-RPC client for `codex app-server` (ported faithfully
-// from pikiloom's CodexAppServer; trimmed to what the kernel needs).
-class AppServer {
-    bin;
-    configOverrides;
-    env;
-    proc = null;
-    buf = '';
-    nextId = 1;
-    pending = new Map();
-    notify;
-    requestResponder;
-    constructor(bin, configOverrides, env) {
-        this.bin = bin;
-        this.configOverrides = configOverrides;
-        this.env = env;
-    }
-    onNotification(cb) { this.notify = cb; }
-    onServerRequest(cb) { this.requestResponder = cb; }
-    async start() {
-        const args = ['app-server'];
-        // Do NOT force model_reasoning_summary — codex reasoning summaries stay OFF by default
-        // (respecting ~/.codex/config.toml, which is the original behavior). A caller that wants
-        // thinking can pass `model_reasoning_summary=...` via configOverrides; we never inject it.
-        const overrides = [...this.configOverrides];
-        if (!overrides.some(c => /^features\.goals\s*=/.test(c)))
-            overrides.push('features.goals=true');
-        for (const c of overrides)
-            args.push('-c', c);
-        try {
-            this.proc = spawn(this.bin, args, { stdio: ['pipe', 'pipe', 'pipe'], env: this.env ? { ...process.env, ...this.env } : process.env });
-        }
-        catch {
-            return false;
-        }
-        this.proc.stdout.on('data', (chunk) => this.onData(chunk));
-        this.proc.on('close', () => { for (const cb of this.pending.values())
-            cb({ error: { message: 'app-server exited' } }); this.pending.clear(); });
-        this.proc.on('error', () => { });
-        const init = await this.call('initialize', { clientInfo: { name: '@pikiloom/kernel', version: '0.1.0' }, capabilities: { experimentalApi: true } }, 15_000);
-        return !init.error;
-    }
-    onData(chunk) {
-        this.buf += chunk.toString('utf8');
-        const lines = this.buf.split('\n');
-        this.buf = lines.pop() || '';
-        for (const line of lines) {
-            if (!line.trim())
-                continue;
-            let msg;
-            try {
-                msg = JSON.parse(line);
-            }
-            catch {
-                continue;
-            }
-            if (msg.method && msg.id != null) { // server -> client request
-                const id = msg.id;
-                Promise.resolve(this.requestResponder ? this.requestResponder(msg.method, msg.params ?? {}, id) : {})
-                    .then((result) => this.respond(id, result ?? {}))
-                    .catch(() => this.respond(id, {}));
-            }
-            else if (msg.id != null) { // response to our call
-                const cb = this.pending.get(msg.id);
-                if (cb) {
-                    this.pending.delete(msg.id);
-                    cb(msg);
-                }
-            }
-            else if (msg.method) { // notification
-                this.notify?.(msg.method, msg.params ?? {});
-            }
-        }
-    }
-    call(method, params, timeoutMs = 60_000) {
-        return new Promise((resolve) => {
-            if (!this.proc || this.proc.killed) {
-                resolve({ error: { message: 'not connected' } });
-                return;
-            }
-            const id = this.nextId++;
-            const timer = setTimeout(() => { this.pending.delete(id); resolve({ error: { message: `RPC '${method}' timed out` } }); }, timeoutMs);
-            this.pending.set(id, (m) => { clearTimeout(timer); resolve(m); });
-            const msg = { jsonrpc: '2.0', id, method };
-            if (params !== undefined)
-                msg.params = params;
-            try {
-                this.proc.stdin.write(JSON.stringify(msg) + '\n');
-            }
-            catch {
-                clearTimeout(timer);
-                this.pending.delete(id);
-                resolve({ error: { message: 'write failed' } });
-            }
-        });
-    }
-    respond(id, result) {
-        try {
-            this.proc?.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
-        }
-        catch { /* closed */ }
-    }
-    kill() { try {
-        this.proc?.kill('SIGTERM');
-    }
-    catch { /* ignore */ } this.proc = null; }
-}
+import { discoverCodexNativeSessions } from './native.js';
+import { StdioRpcClient } from './rpc.js';
+import { attachedFileNote, contextPercent, imageMimeForFile, wireAbort } from './shared.js';
 function planFromUpdate(params) {
     const rawSteps = Array.isArray(params?.plan?.steps) ? params.plan.steps : Array.isArray(params?.steps) ? params.steps : Array.isArray(params?.plan) ? params.plan : [];
     const steps = rawSteps.map((st) => {
@@ -247,16 +141,23 @@ export class CodexDriver {
         // BYOK provider routing arrives as `-c key=value` overrides; pass them through so the
         // kernel path keeps third-party models (e.g. glm via OpenRouter) instead of falling back
         // to the native account.
-        const config = [...(input.configOverrides || [])];
-        const srv = new AppServer(this.bin, config, input.env);
+        // Do NOT force model_reasoning_summary — codex reasoning summaries stay OFF by default
+        // (respecting ~/.codex/config.toml, which is the original behavior). A caller that wants
+        // thinking can pass `model_reasoning_summary=...` via configOverrides; we never inject it.
+        const overrides = [...(input.configOverrides || [])];
+        if (!overrides.some(c => /^features\.goals\s*=/.test(c)))
+            overrides.push('features.goals=true');
+        const args = ['app-server'];
+        for (const c of overrides)
+            args.push('-c', c);
+        const srv = new StdioRpcClient({ command: this.bin, args, env: input.env, label: 'codex app-server' });
         const state = { text: '', reasoning: '', streamedReasoning: false, msgs: [], thinkParts: [], sessionId: input.sessionId ?? null, input: null, output: null, cached: null, contextUsed: null, contextWindow: null, status: null, error: null, turnId: null };
         const phases = new Map();
         const toolSummaries = new Map();
         const deltaItems = new Set();
         let lastTextItemId = null;
         let steerRegistered = false;
-        const ok = await srv.start();
-        if (!ok)
+        if (!srv.start())
             return { ok: false, text: '', error: 'failed to start codex app-server', stopReason: 'error' };
         let settle = () => { };
         const turnDone = new Promise((res) => { settle = res; });
@@ -264,20 +165,19 @@ export class CodexDriver {
         // srv.kill() (SIGTERM) never produces a turn/completed notification, so without this explicit
         // settle() the `await turnDone` below hangs forever — run() never resolves and the task stays
         // "running" in the orchestrator even though the codex process is already dead ("停止不掉，但实际上已经停了").
-        const onAbort = () => {
+        wireAbort(ctx.signal, () => {
             if (state.sessionId && state.turnId) {
-                srv.call('turn/interrupt', { threadId: state.sessionId, turnId: state.turnId }, 5_000).finally(() => settle());
+                srv.request('turn/interrupt', { threadId: state.sessionId, turnId: state.turnId }, 5_000).finally(() => settle());
             }
             else {
                 srv.kill();
                 settle();
             }
-        };
-        if (ctx.signal.aborted)
-            onAbort();
-        else
-            ctx.signal.addEventListener('abort', onAbort, { once: true });
+        });
         try {
+            const init = await srv.request('initialize', { clientInfo: { name: '@pikiloom/kernel', version: '0.1.0' }, capabilities: { experimentalApi: true } }, 15_000);
+            if (init.error)
+                return { ok: false, text: '', error: 'failed to start codex app-server', stopReason: 'error' };
             const threadParams = { cwd: input.workdir, model: input.model || null };
             if (input.systemPrompt)
                 threadParams.developerInstructions = input.systemPrompt;
@@ -286,8 +186,8 @@ export class CodexDriver {
                 threadParams.sandbox = 'danger-full-access';
             }
             const threadResp = input.sessionId
-                ? await srv.call('thread/resume', { threadId: input.sessionId, ...threadParams })
-                : await srv.call('thread/start', threadParams);
+                ? await srv.request('thread/resume', { threadId: input.sessionId, ...threadParams })
+                : await srv.request('thread/start', threadParams);
             if (threadResp.error)
                 return { ok: false, text: '', error: threadResp.error.message || 'thread/start failed', stopReason: 'error' };
             const threadId = threadResp.result?.thread?.id ?? input.sessionId ?? null;
@@ -306,7 +206,7 @@ export class CodexDriver {
                             ctx.registerSteer(async (prompt, attachments = []) => {
                                 if (!state.sessionId || !state.turnId)
                                     return false;
-                                const r = await srv.call('turn/steer', { threadId: state.sessionId, expectedTurnId: state.turnId, input: buildTurnInput(prompt, attachments) }, 30_000);
+                                const r = await srv.request('turn/steer', { threadId: state.sessionId, expectedTurnId: state.turnId, input: buildTurnInput(prompt, attachments) }, 30_000);
                                 if (r.error)
                                     return false;
                                 state.turnId = r.result?.turnId ?? state.turnId;
@@ -400,22 +300,28 @@ export class CodexDriver {
                 }
             });
             // Codex server->client requests: route user-input to the HITL seam (ctx.askUser),
-            // accept approvals by default (parity with the legacy codex driver).
-            srv.onServerRequest(async (method, params, id) => {
-                if (method === 'item/tool/requestUserInput') {
-                    const interaction = codexUserInputToInteraction(params, `codex-input-${id}`);
-                    if (!interaction)
-                        return { answers: {} };
-                    const answers = await ctx.askUser(interaction);
-                    return { answers: Object.fromEntries(Object.entries(answers).map(([qid, vals]) => [qid, { answers: vals }])) };
+            // accept approvals by default (parity with the legacy codex driver). Never throw —
+            // an unanswerable request degrades to an empty response, not a JSON-RPC error.
+            srv.onRequest(async (method, params, id) => {
+                try {
+                    if (method === 'item/tool/requestUserInput') {
+                        const interaction = codexUserInputToInteraction(params, `codex-input-${id}`);
+                        if (!interaction)
+                            return { answers: {} };
+                        const answers = await ctx.askUser(interaction);
+                        return { answers: Object.fromEntries(Object.entries(answers).map(([qid, vals]) => [qid, { answers: vals }])) };
+                    }
+                    if (method === 'item/commandExecution/requestApproval' || method === 'item/fileChange/requestApproval')
+                        return { decision: 'accept' };
+                    if (method === 'item/permissions/requestApproval')
+                        return { permissions: {}, scope: 'turn' };
+                    return {};
+                }
+                catch {
+                    return {};
                 }
-                if (method === 'item/commandExecution/requestApproval' || method === 'item/fileChange/requestApproval')
-                    return { decision: 'accept' };
-                if (method === 'item/permissions/requestApproval')
-                    return { permissions: {}, scope: 'turn' };
-                return {};
             });
-            const turnResp = await srv.call('turn/start', {
+            const turnResp = await srv.request('turn/start', {
                 threadId: state.sessionId,
                 input: buildTurnInput(input.prompt, input.attachments || []),
                 model: input.model || undefined,
@@ -453,12 +359,10 @@ export class CodexDriver {
         return discoverCodexNativeSessions(opts.workdir, { limit: opts.limit });
     }
 }
-const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
 function buildTurnInput(prompt, attachments) {
     const input = [];
     for (const f of attachments) {
-        const ext = f.slice(f.lastIndexOf('.')).toLowerCase();
-        input.push(IMAGE_EXTS.has(ext) ? { type: 'localImage', path: f } : { type: 'text', text: `[Attached file: ${f}]` });
+        input.push(imageMimeForFile(f) ? { type: 'localImage', path: f } : { type: 'text', text: attachedFileNote(f) });
     }
     input.push({ type: 'text', text: prompt });
     return input;
@@ -486,7 +390,7 @@ function codexContextUsed(raw) {
 }
 // Fold a codex tokenUsage payload into driver state: last-turn counts, context
 // occupancy, and the model window. Tolerant of nested {info:{…}} and flat shapes.
-export function applyCodexTokenUsage(s, rawUsage) {
+function applyCodexTokenUsage(s, rawUsage) {
     if (!rawUsage || typeof rawUsage !== 'object')
         return;
     const info = rawUsage.info && typeof rawUsage.info === 'object' ? rawUsage.info : rawUsage;
@@ -521,18 +425,17 @@ export function applyCodexTokenUsage(s, rawUsage) {
     if (cw != null && cw > 0)
         s.contextWindow = cw;
 }
-export function codexUsageOf(s) {
+function codexUsageOf(s) {
     const fallback = (s.input ?? 0) + (s.cached ?? 0);
     const used = s.contextUsed ?? (fallback > 0 ? fallback : null);
     const window = s.contextWindow ?? null;
-    const contextPercent = used != null && window ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
     const turnOutput = s.output ?? 0;
     return {
         inputTokens: s.input,
         outputTokens: s.output,
         cachedInputTokens: s.cached,
         contextUsedTokens: used,
-        contextPercent,
+        contextPercent: contextPercent(used, window),
         turnOutputTokens: turnOutput > 0 ? turnOutput : null,
     };
 }

package/dist/drivers/gemini.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { discoverGeminiNativeSessions } from '../workspace/native.js';
+import { discoverGeminiNativeSessions } from './native.js';
+import { createLineBuffer, parseJsonLine, sigterm, wireAbort } from './shared.js';
 // Native kernel Gemini driver: `gemini --output-format stream-json ... -p <prompt>` and
 // parse its stream-json events into kernel DriverEvents. Faithful to pikiloom's geminiParse.
 export class GeminiDriver {
@@ -21,7 +22,7 @@ export class GeminiDriver {
         if (extra.length)
             args.push(...extra);
         args.push('-p', input.prompt);
-        const s = { text: '', sessionId: input.sessionId ?? null, model: input.model ?? null, input: null, output: null, cached: null, stopReason: null, error: null };
+        const s = { text: '', sessionId: input.sessionId ?? null, input: null, output: null, cached: null, stopReason: null, error: null };
         const tools = new Map();
         return new Promise((resolve) => {
             let child;
@@ -32,32 +33,14 @@ export class GeminiDriver {
                 resolve({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
                 return;
             }
-            const onAbort = () => { try {
-                child.kill('SIGTERM');
-            }
-            catch { /* ignore */ } };
-            if (ctx.signal.aborted)
-                onAbort();
-            else
-                ctx.signal.addEventListener('abort', onAbort, { once: true });
-            let buf = '';
+            wireAbort(ctx.signal, () => sigterm(child));
+            const nextLines = createLineBuffer();
             let stderr = '';
             child.stdout.on('data', (chunk) => {
-                buf += chunk.toString('utf8');
-                const lines = buf.split('\n');
-                buf = lines.pop() || '';
-                for (const line of lines) {
-                    const trimmed = line.trim();
-                    if (!trimmed)
-                        continue;
-                    let ev;
-                    try {
-                        ev = JSON.parse(trimmed);
-                    }
-                    catch {
-                        continue;
-                    }
-                    parseGeminiEvent(ev, s, tools, ctx.emit);
+                for (const line of nextLines(chunk)) {
+                    const ev = parseJsonLine(line);
+                    if (ev !== undefined)
+                        parseGeminiEvent(ev, s, tools, ctx.emit);
                 }
             });
             child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
@@ -92,7 +75,6 @@ export function parseGeminiEvent(ev, s, tools, emit) {
             s.sessionId = ev.session_id;
             emit({ type: 'session', sessionId: ev.session_id });
         }
-        s.model = ev.model ?? s.model;
         return;
     }
     if (t === 'message' && ev.role === 'assistant') {

package/dist/drivers/hermes.d.ts

@@ -1,5 +1,4 @@
-import { AcpDriver, applyAcpUpdate } from './acp.js';
+import { AcpDriver } from './acp.js';
 export declare class HermesDriver extends AcpDriver {
     constructor(bin?: string);
 }
-export declare const applyHermesUpdate: typeof applyAcpUpdate;

package/dist/drivers/hermes.js

@@ -1,4 +1,4 @@
-import { AcpDriver, applyAcpUpdate } from './acp.js';
+import { AcpDriver } from './acp.js';
 // Hermes = the reference ACP agent, shipped as a thin preset over the generic AcpDriver.
 // Any other ACP CLI (OpenCode, Gemini-ACP, …) is just `new AcpDriver({ id, command, args })`.
 export class HermesDriver extends AcpDriver {
@@ -6,6 +6,3 @@ export class HermesDriver extends AcpDriver {
         super({ id: 'hermes', command: bin, args: ['acp'] });
     }
 }
-// Back-compat alias: the generic ACP session/update parser handles the identical wire that
-// the original hermes-specific parser did. Kept so existing imports/tests resolve.
-export const applyHermesUpdate = applyAcpUpdate;

package/dist/drivers/index.d.ts

@@ -1,6 +1,7 @@
 export { EchoDriver } from './echo.js';
-export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
+export { ClaudeDriver } from './claude.js';
 export { CodexDriver } from './codex.js';
-export { GeminiDriver, parseGeminiEvent } from './gemini.js';
-export { AcpDriver, applyAcpUpdate, toAcpMcpServers, buildAcpPromptBlocks, type AcpDriverConfig } from './acp.js';
-export { HermesDriver, applyHermesUpdate } from './hermes.js';
+export { GeminiDriver } from './gemini.js';
+export { AcpDriver, type AcpDriverConfig } from './acp.js';
+export { HermesDriver } from './hermes.js';
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, type DiscoverOptions, type NativeSessionInfo, } from './native.js';

package/dist/drivers/index.js

@@ -1,6 +1,10 @@
+// The agent axis: one driver per coding-agent CLI, plus native-session discovery (pure
+// readers of each CLI's own on-disk transcript store). White-box parser/settle helpers are
+// deliberately NOT re-exported here — tests import them from their defining module.
 export { EchoDriver } from './echo.js';
-export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
+export { ClaudeDriver } from './claude.js';
 export { CodexDriver } from './codex.js';
-export { GeminiDriver, parseGeminiEvent } from './gemini.js';
-export { AcpDriver, applyAcpUpdate, toAcpMcpServers, buildAcpPromptBlocks } from './acp.js';
-export { HermesDriver, applyHermesUpdate } from './hermes.js';
+export { GeminiDriver } from './gemini.js';
+export { AcpDriver } from './acp.js';
+export { HermesDriver } from './hermes.js';
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, } from './native.js';

package/dist/{workspace → drivers}/native.d.ts

@@ -6,7 +6,6 @@ export interface DiscoverOptions {
     /** A session whose file changed within this window is treated as "running". */
     runningThresholdMs?: number;
 }
-export declare const NATIVE_SESSION_RUNNING_THRESHOLD_MS = 10000;
 /** Claude encodes a workdir into a project dir name by replacing non-alphanumerics with '-'. */
 export declare function encodeClaudeProjectDir(workdir: string): string;
 export declare function discoverClaudeNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];

package/dist/{workspace → drivers}/native.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-export const NATIVE_SESSION_RUNNING_THRESHOLD_MS = 10_000;
+const NATIVE_SESSION_RUNNING_THRESHOLD_MS = 10_000;
 function homeOf(opts) {
     return opts?.home || os.homedir();
 }

package/dist/drivers/rpc.d.ts

@@ -0,0 +1,45 @@
+export type RpcMsg = {
+    jsonrpc?: string;
+    id?: number | string;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: any;
+};
+/** Throw from an onRequest handler to answer with a specific JSON-RPC error code. */
+export declare class RpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+export interface StdioRpcOptions {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    label?: string;
+}
+export declare class StdioRpcClient {
+    private readonly opts;
+    private proc;
+    private nextId;
+    private readonly pending;
+    private notifyCb?;
+    private requestCb?;
+    private readonly stderrTail;
+    private readonly label;
+    constructor(opts: StdioRpcOptions);
+    onNotification(cb: (method: string, params: any) => void): void;
+    /** Serve peer->client requests. Throw RpcError for a coded error; anything else answers -32603. */
+    onRequest(cb: (method: string, params: any, id: number | string) => any | Promise<any>): void;
+    /** Rolling tail of the process' stderr — startup/crash diagnostics. */
+    stderrText(): string;
+    start(): boolean;
+    private onLine;
+    private handleRequest;
+    request(method: string, params?: any, timeoutMs?: number): Promise<RpcMsg>;
+    notify(method: string, params?: any): void;
+    private respond;
+    private respondError;
+    private write;
+    kill(): void;
+}

package/dist/drivers/rpc.js

@@ -0,0 +1,130 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+/** Throw from an onRequest handler to answer with a specific JSON-RPC error code. */
+export class RpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const STDERR_TAIL_LINES = 20;
+export class StdioRpcClient {
+    opts;
+    proc = null;
+    nextId = 1;
+    pending = new Map();
+    notifyCb;
+    requestCb;
+    stderrTail = [];
+    label;
+    constructor(opts) {
+        this.opts = opts;
+        this.label = opts.label || opts.command;
+    }
+    onNotification(cb) { this.notifyCb = cb; }
+    /** Serve peer->client requests. Throw RpcError for a coded error; anything else answers -32603. */
+    onRequest(cb) { this.requestCb = cb; }
+    /** Rolling tail of the process' stderr — startup/crash diagnostics. */
+    stderrText() { return this.stderrTail.join('\n'); }
+    start() {
+        try {
+            this.proc = spawn(this.opts.command, this.opts.args, {
+                cwd: this.opts.cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: this.opts.env ? { ...process.env, ...this.opts.env } : process.env,
+            });
+        }
+        catch {
+            return false;
+        }
+        const rl = createInterface({ input: this.proc.stdout, crlfDelay: Infinity });
+        rl.on('line', (line) => this.onLine(line));
+        // Always drain stderr (an unread pipe backpressures the child) and keep a tail for errors.
+        this.proc.stderr.on('data', (chunk) => {
+            for (const ln of chunk.toString('utf8').split('\n')) {
+                const t = ln.trim();
+                if (!t)
+                    continue;
+                this.stderrTail.push(t.slice(0, 240));
+                if (this.stderrTail.length > STDERR_TAIL_LINES)
+                    this.stderrTail.shift();
+            }
+        });
+        this.proc.on('close', () => {
+            for (const cb of this.pending.values())
+                cb({ error: { message: `${this.label} exited` } });
+            this.pending.clear();
+        });
+        this.proc.on('error', () => { });
+        return true;
+    }
+    onLine(line) {
+        const t = line.trim();
+        if (!t)
+            return;
+        let m;
+        try {
+            m = JSON.parse(t);
+        }
+        catch {
+            return;
+        } // non-JSON stdout noise
+        if (m.method && m.id != null) {
+            void this.handleRequest(m);
+            return;
+        } // peer -> client request
+        if (m.id != null) { // response to one of our requests
+            const cb = this.pending.get(m.id);
+            if (cb) {
+                this.pending.delete(m.id);
+                cb(m);
+            }
+            return;
+        }
+        if (m.method)
+            this.notifyCb?.(m.method, m.params ?? {}); // notification
+    }
+    async handleRequest(m) {
+        const id = m.id;
+        if (!this.requestCb) {
+            this.respondError(id, -32601, `Method not implemented: ${m.method}`);
+            return;
+        }
+        try {
+            const result = await this.requestCb(m.method, m.params ?? {}, id);
+            this.respond(id, result ?? null);
+        }
+        catch (e) {
+            const code = e instanceof RpcError ? e.code : -32603;
+            this.respondError(id, code, e?.message || 'handler error');
+        }
+    }
+    request(method, params, timeoutMs = 60_000) {
+        return new Promise((resolve) => {
+            if (!this.proc || this.proc.killed) {
+                resolve({ error: { message: 'not connected' } });
+                return;
+            }
+            const id = this.nextId++;
+            const timer = setTimeout(() => { this.pending.delete(id); resolve({ error: { message: `${this.label} '${method}' timed out` } }); }, timeoutMs);
+            this.pending.set(id, (m) => { clearTimeout(timer); resolve(m); });
+            this.write({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    notify(method, params) { this.write({ jsonrpc: '2.0', method, params }); }
+    respond(id, result) { this.write({ jsonrpc: '2.0', id, result }); }
+    respondError(id, code, message) { this.write({ jsonrpc: '2.0', id, error: { code, message } }); }
+    write(msg) {
+        if (!this.proc || this.proc.killed)
+            return;
+        try {
+            this.proc.stdin.write(JSON.stringify(msg) + '\n');
+        }
+        catch { /* stream closed */ }
+    }
+    kill() { try {
+        this.proc?.kill('SIGTERM');
+    }
+    catch { /* ignore */ } this.proc = null; }
+}

package/dist/drivers/shared.d.ts

@@ -0,0 +1,21 @@
+import type { ChildProcess } from 'node:child_process';
+/** Stateful newline splitter for a child process' stdout: feed chunks, get complete lines. */
+export declare function createLineBuffer(): (chunk: Buffer | string) => string[];
+/** Parse one ndjson line; undefined for blank lines / non-JSON noise. */
+export declare function parseJsonLine(line: string): any | undefined;
+/**
+ * Run `fn` when the signal aborts (immediately if it already has). Returns an
+ * unsubscribe for drivers that must detach the handler when the turn settles.
+ */
+export declare function wireAbort(signal: AbortSignal, fn: () => void): () => void;
+/** SIGTERM a child, swallowing the already-dead race. */
+export declare function sigterm(proc: ChildProcess | null | undefined): void;
+/** Mime type when the file is an inlineable image, else null. */
+export declare function imageMimeForFile(filePath: string): string | null;
+/** The text note substituted for a non-image attachment. */
+export declare function attachedFileNote(filePath: string): string;
+/**
+ * Context-window occupancy as a display percent (one decimal, capped at 99.9).
+ * Pass `used` as null when the caller wants "no data" rather than 0%.
+ */
+export declare function contextPercent(used: number | null | undefined, window: number | null | undefined): number | null;