@pikiloom/kernel 0.2.2 → 0.2.4

package/dist/drivers/claude.d.ts

@@ -30,9 +30,20 @@ export declare function claudeUsageOf(s: ClaudeUsageState): UniversalUsage;
 export declare function claudeContextWindowFromModel(model: unknown): number | null;
 export declare function claudeEffectiveContextWindow(advertised: number | null): number | null;
 export declare function handleClaudeEvent(ev: any, s: any, emit: (e: DriverEvent) => void): void;
-export declare function claudeUserMessage(text: string): string;
+export declare function claudeBgHoldCapMs(): number;
+export declare function isTerminalTaskStatus(status: unknown): boolean;
+export declare function trackClaudeBackgroundTask(ev: any, s: any): void;
+export declare function pendingClaudeBackgroundTasks(s: any): number;
+export type ClaudeResultSettleDecision = 'settle' | 'hold';
+export declare function decideClaudeResultSettle(input: {
+    hasError: boolean;
+    pendingBackground: number;
+}): ClaudeResultSettleDecision;
+export declare function claudeUserMessage(text: string, attachments?: string[]): string;
 export declare function emitClaudeImages(blocks: any[], s: any, emit: (e: DriverEvent) => void): void;
 export declare function todoWriteToPlan(input: any): UniversalPlan | null;
+export declare function readClaudeTaskCreateId(ev: any, block: any): string | null;
+export declare function rebuildClaudeTaskPlan(s: any): UniversalPlan | null;
 export declare function shortToolValue(value: unknown, max?: number): string;
 export declare function summarizeToolUse(name: string, input: any): string;
 export declare function firstResultLine(content: any): string;

package/dist/drivers/claude.js

@@ -1,4 +1,6 @@
 import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
 import { discoverClaudeNativeSessions } from '../workspace/native.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
@@ -28,7 +30,14 @@ export class ClaudeDriver {
     }
     run(input, ctx) {
         const steerable = !!input.steerable;
-        const args = ['-p', '--verbose', '--output-format', 'stream-json', '--include-partial-messages'];
+        // Always drive Claude over a stream-json stdin and keep that stdin OPEN for the whole turn.
+        // That open stdin is what lets Claude's native "launch detached background work → end the
+        // turn → wake itself up and report when the work finishes" flow play out: it only happens
+        // while stdin stays open (with it closed, Claude exits at the first `result` and the wake-up
+        // — and any in-process background agent/workflow — is lost). Image attachments also need the
+        // stream-json user message (a plain text stdin can't carry images). `--replay-user-messages`
+        // + registerSteer remain the only mid-turn-steer-specific bits.
+        const args = ['-p', '--verbose', '--output-format', 'stream-json', '--include-partial-messages', '--input-format', 'stream-json'];
         if (input.model)
             args.push('--model', input.model);
         if (input.effort)
@@ -42,7 +51,7 @@ export class ClaudeDriver {
         if (input.permissionMode)
             args.push('--permission-mode', input.permissionMode); // parity: keep bypass/accept-edits on the kernel path
         if (steerable)
-            args.push('--input-format', 'stream-json', '--replay-user-messages'); // parity: mid-turn steer
+            args.push('--replay-user-messages'); // parity: mid-turn steer
         if (input.extraArgs?.length)
             args.push(...input.extraArgs);
         const state = {
@@ -54,26 +63,57 @@ export class ClaudeDriver {
             contextWindow: null, turnOutputTokensBase: 0,
             subAgents: new Map(),
             tools: new Map(),
+            taskList: new Map(),
+            taskOrder: [],
+            pendingTaskCreates: new Map(),
+            // run_in_background lifecycle: task ids seen as started vs. reached a terminal status.
+            bgStarted: new Set(), bgTerminal: new Set(),
         };
         return new Promise((resolve) => {
             let child;
             let settled = false;
-            const finish = (r) => {
+            let holdCapTimer = null;
+            const usageOf = () => this.usage(state);
+            const clearHoldCap = () => { if (holdCapTimer) {
+                clearTimeout(holdCapTimer);
+                holdCapTimer = null;
+            } };
+            // kill=true SIGTERMs immediately — fast exit, used once nothing is left running in the
+            // background (a normal turn, or a wake-up turn after every background task finished).
+            // 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) => {
                 if (settled)
                     return;
                 settled = true;
+                clearHoldCap();
                 try {
                     child?.stdin?.end();
                 }
                 catch { /* ignore */ }
-                if (steerable) {
-                    try {
-                        child?.kill('SIGTERM');
+                if (!child.killed && child.exitCode == null) {
+                    if (kill) {
+                        try {
+                            child.kill('SIGTERM');
+                        }
+                        catch { /* ignore */ }
+                    }
+                    else {
+                        const guard = setTimeout(() => { try {
+                            child?.kill('SIGTERM');
+                        }
+                        catch { /* ignore */ } }, CLAUDE_EXIT_LEAK_GUARD_MS);
+                        if (typeof guard.unref === 'function')
+                            guard.unref();
                     }
-                    catch { /* ignore */ }
-                } // replay mode keeps the process alive past the turn
+                }
                 resolve(r);
             };
+            const settleResult = (opts = {}) => finish({
+                ok: !state.error, text: state.text, reasoning: state.reasoning || undefined,
+                error: state.error, stopReason: opts.stopReason ?? state.stopReason, sessionId: state.sessionId, usage: usageOf(),
+            }, opts.kill ?? true);
             try {
                 child = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
             }
@@ -90,9 +130,9 @@ export class ClaudeDriver {
             else
                 ctx.signal.addEventListener('abort', onAbort, { once: true });
             if (steerable) {
-                ctx.registerSteer(async (prompt) => {
+                ctx.registerSteer(async (prompt, attachments) => {
                     try {
-                        child.stdin.write(claudeUserMessage(prompt) + '\n');
+                        child.stdin.write(claudeUserMessage(prompt, attachments) + '\n');
                         return true;
                     }
                     catch {
@@ -100,14 +140,17 @@ export class ClaudeDriver {
                     }
                 });
             }
-            const usageOf = () => this.usage(state);
             let buf = '';
             let stderr = '';
             child.stdout.on('data', (chunk) => {
+                if (settled)
+                    return; // ignore the process's post-settle shutdown chatter
                 buf += chunk.toString('utf8');
                 const lines = buf.split('\n');
                 buf = lines.pop() || '';
                 for (const line of lines) {
+                    if (settled)
+                        return;
                     const trimmed = line.trim();
                     if (!trimmed)
                         continue;
@@ -119,29 +162,42 @@ export class ClaudeDriver {
                         continue;
                     }
                     handleClaudeEvent(ev, state, ctx.emit);
-                    if (steerable && ev.type === 'result') {
-                        // In replay mode the turn ends on `result` but the process lingers; settle now.
-                        finish({ ok: !state.error, text: state.text, reasoning: state.reasoning || undefined, error: state.error, stopReason: state.stopReason, sessionId: state.sessionId, usage: usageOf() });
+                    if (ev.type !== 'result')
+                        continue;
+                    const hasError = !!ev.is_error || (Array.isArray(ev.errors) && ev.errors.length > 0) || !!state.error;
+                    const pending = pendingClaudeBackgroundTasks(state);
+                    if (decideClaudeResultSettle({ hasError, pendingBackground: pending }) === 'hold') {
+                        // Background work is still running: do NOT end the turn here. Keep stdin open so Claude
+                        // wakes itself up and streams a follow-up turn reporting the finished work — we settle
+                        // on THAT result (pending back to 0). A cap bounds the wait so a never-completing daemon
+                        // (e.g. a dev server) eventually settles (graceful, no kill) instead of holding forever.
+                        if (!holdCapTimer) {
+                            holdCapTimer = setTimeout(() => { if (!settled)
+                                settleResult({ stopReason: 'background', kill: false }); }, claudeBgHoldCapMs());
+                            if (typeof holdCapTimer.unref === 'function')
+                                holdCapTimer.unref();
+                        }
+                        continue;
                     }
+                    settleResult();
                 }
             });
             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) => {
+                if (settled)
+                    return;
                 if (ctx.signal.aborted) {
-                    finish({ ok: false, text: state.text, reasoning: state.reasoning, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: state.sessionId, usage: usageOf() });
+                    finish({ ok: false, text: state.text, reasoning: state.reasoning, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: state.sessionId, usage: usageOf() }, false);
                     return;
                 }
                 const ok = !state.error && code === 0;
-                finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason: state.stopReason, sessionId: state.sessionId, usage: usageOf() });
+                finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason: state.stopReason, sessionId: state.sessionId, usage: usageOf() }, false);
             });
             try {
-                if (steerable)
-                    child.stdin.write(claudeUserMessage(input.prompt) + '\n'); // keep stdin open for steering
-                else {
-                    child.stdin.write(input.prompt);
-                    child.stdin.end();
-                }
+                // 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 */ }
         });
@@ -215,6 +271,7 @@ export function handleClaudeEvent(ev, s, emit) {
         return;
     }
     if (t === 'system') {
+        trackClaudeBackgroundTask(ev, s);
         if (ev.session_id && ev.session_id !== s.sessionId) {
             s.sessionId = ev.session_id;
             emit({ type: 'session', sessionId: ev.session_id });
@@ -301,6 +358,34 @@ export function handleClaudeEvent(ev, s, emit) {
                     emit({ type: 'plan', plan });
                 continue;
             }
+            // Task list (current Claude mechanism): stash the subject; the tool_result assigns the id.
+            // Plan-only — like the legacy driver these never surface as Activity rows.
+            if (name === 'TaskCreate') {
+                const subject = typeof b.input?.subject === 'string' ? b.input.subject.trim() : '';
+                if (subject)
+                    (s.pendingTaskCreates ||= new Map()).set(id, { subject });
+                continue;
+            }
+            if (name === 'TaskUpdate') {
+                const taskId = String(b.input?.taskId ?? '').trim();
+                const rawStatus = String(b.input?.status ?? '').trim().toLowerCase();
+                if (taskId) {
+                    if (rawStatus === 'deleted') {
+                        s.taskList?.delete(taskId);
+                        if (Array.isArray(s.taskOrder))
+                            s.taskOrder = s.taskOrder.filter((x) => x !== taskId);
+                    }
+                    else if (rawStatus) {
+                        const existing = s.taskList?.get(taskId);
+                        if (existing)
+                            existing.status = rawStatus;
+                    }
+                    const plan = rebuildClaudeTaskPlan(s);
+                    if (plan)
+                        emit({ type: 'plan', plan });
+                }
+                continue;
+            }
             if (name === 'Task' || name === 'Agent') {
                 const input = b.input || {};
                 const sub = {
@@ -348,6 +433,23 @@ export function handleClaudeEvent(ev, s, emit) {
                 continue;
             emitClaudeImages(b.content || [], s, emit);
             const id = String(b.tool_use_id || '').trim();
+            // TaskCreate result: the assigned task id arrives here; register the task and emit the plan.
+            if (id && s.pendingTaskCreates?.has(id)) {
+                const pending = s.pendingTaskCreates.get(id);
+                const assignedId = readClaudeTaskCreateId(ev, b);
+                if (pending && assignedId) {
+                    s.pendingTaskCreates.delete(id);
+                    (s.taskList ||= new Map());
+                    (s.taskOrder ||= []);
+                    if (!s.taskList.has(assignedId))
+                        s.taskOrder.push(assignedId);
+                    s.taskList.set(assignedId, { subject: pending.subject, status: 'pending' });
+                    const plan = rebuildClaudeTaskPlan(s);
+                    if (plan)
+                        emit({ type: 'plan', plan });
+                }
+                continue;
+            }
             const tool = id ? s.tools?.get(id) : undefined;
             if (!tool)
                 continue;
@@ -384,10 +486,86 @@ export function handleClaudeEvent(ev, s, emit) {
         return;
     }
 }
-// A stream-json user message (for --input-format stream-json; used to send the prompt and
-// to inject mid-turn steer messages while stdin stays open).
-export function claudeUserMessage(text) {
-    return JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text }] } });
+// ── run_in_background lifecycle (background → wake-up) ───────────────────────────────────
+// Claude streams a structured lifecycle for detached background work as `system` sub-events:
+//   { subtype:'task_started',      task_id, tool_use_id, description }   ← launched
+//   { subtype:'task_updated',      task_id, patch:{ status } }           ← progress / terminal
+//   { subtype:'task_notification', task_id, status }                     ← terminal (completed/killed/…)
+// A task counts as pending from task_started until a terminal task_updated/task_notification.
+// While any are pending the driver keeps the turn alive instead of ending it at `result`, so
+// Claude's own background→wake-up turn (which reports the finished work) can stream in. Pure +
+// exported for hermetic testing.
+// How long, with no settle, to keep holding a turn open for a background task to finish and
+// trigger Claude's wake-up turn, before giving up (so a never-completing daemon doesn't hang
+// the turn forever). Override with PIKILOOM_CLAUDE_BG_HOLD_MS.
+const CLAUDE_BG_HOLD_CAP_DEFAULT_MS = 10 * 60_000;
+export function claudeBgHoldCapMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_BG_HOLD_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_BG_HOLD_CAP_DEFAULT_MS;
+}
+// After we settle a held turn gracefully (stdin closed, no kill), force-kill the lingering
+// process only if it hasn't exited on its own within this window. Backstop against leaks.
+const CLAUDE_EXIT_LEAK_GUARD_MS = 15_000;
+export function isTerminalTaskStatus(status) {
+    return /^(complete|done|success|succeed|finish|kill|fail|error|stop|cancel|abort|timed?_?out|timeout)/i
+        .test(String(status ?? '').trim());
+}
+export function trackClaudeBackgroundTask(ev, s) {
+    const subtype = ev?.subtype;
+    if (subtype !== 'task_started' && subtype !== 'task_updated' && subtype !== 'task_notification')
+        return;
+    const id = String(ev?.task_id ?? ev?.tool_use_id ?? '').trim();
+    if (!id)
+        return;
+    if (subtype === 'task_started') {
+        (s.bgStarted ||= new Set()).add(id);
+        return;
+    }
+    if (isTerminalTaskStatus(ev?.patch?.status ?? ev?.status))
+        (s.bgTerminal ||= new Set()).add(id);
+}
+export function pendingClaudeBackgroundTasks(s) {
+    const started = s?.bgStarted;
+    if (!started?.size)
+        return 0;
+    const terminal = s?.bgTerminal;
+    let n = 0;
+    for (const id of started)
+        if (!terminal?.has(id))
+            n++;
+    return n;
+}
+// At a `result` event: settle the turn normally, unless background work is still running
+// (then hold the process open for the wake-up). Errors always settle.
+export function decideClaudeResultSettle(input) {
+    if (input.hasError)
+        return 'settle';
+    return input.pendingBackground > 0 ? 'hold' : 'settle';
+}
+// Claude vision input formats (matches the legacy driver / Anthropic API: png, jpeg, gif, webp).
+const CLAUDE_IMAGE_MIME = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp',
+};
+// A stream-json user message (for --input-format stream-json; used to send the prompt and to
+// inject mid-turn steer messages while stdin stays open). Image attachments are inlined as base64
+// image content blocks so the model actually sees them; other files become a text note. Without
+// this the kernel path sent text only and silently dropped pasted/attached images.
+export function claudeUserMessage(text, attachments) {
+    const content = [];
+    for (const filePath of attachments || []) {
+        const mime = CLAUDE_IMAGE_MIME[extname(filePath).toLowerCase()];
+        if (mime) {
+            try {
+                content.push({ type: 'image', source: { type: 'base64', media_type: mime, data: readFileSync(filePath).toString('base64') } });
+                continue;
+            }
+            catch { /* unreadable -> fall through to a text note */ }
+        }
+        content.push({ type: 'text', text: `[Attached file: ${filePath}]` });
+    }
+    content.push({ type: 'text', text });
+    return JSON.stringify({ type: 'user', message: { role: 'user', content } });
 }
 // Surface base64 image content blocks as artifacts (data URLs), deduped per turn.
 export function emitClaudeImages(blocks, s, emit) {
@@ -425,6 +603,45 @@ export function todoWriteToPlan(input) {
     }
     return steps.length ? { explanation: null, steps } : null;
 }
+// ── Claude task-list (TaskCreate / TaskUpdate) -> UniversalPlan ──────────────────────
+// Current Claude Code drives its task list through TaskCreate/TaskUpdate, NOT TodoWrite
+// (TodoWrite is the legacy mechanism). TaskCreate carries the subject; its tool_result then
+// assigns a stable task id (toolUseResult.task.id, or "Task #N" in the text). TaskUpdate flips
+// a task's status by id. We accumulate the list in driver state and re-emit the whole plan on
+// each change. Without this the kernel path never emits a plan event for Claude, so the
+// dashboard's task-list card never renders. Ported from pikiloom's legacy claude driver.
+// The assigned task id from a TaskCreate tool_result. Prefer the structured field; fall back
+// to parsing "Task #N" from a string result.
+export function readClaudeTaskCreateId(ev, block) {
+    const structured = ev?.toolUseResult?.task?.id;
+    if (structured != null && String(structured).trim())
+        return String(structured).trim();
+    const content = block?.content;
+    if (typeof content === 'string') {
+        const m = content.match(/Task #(\d+)/);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
+export function rebuildClaudeTaskPlan(s) {
+    if (!Array.isArray(s?.taskOrder) || !s.taskOrder.length)
+        return null;
+    const steps = [];
+    for (const id of s.taskOrder) {
+        const task = s.taskList?.get(id);
+        if (!task)
+            continue;
+        const lowered = String(task.status || '').toLowerCase();
+        const status = lowered === 'completed' ? 'completed'
+            : (lowered === 'in_progress' || lowered === 'inprogress') ? 'inProgress'
+                : 'pending';
+        const text = String(task.subject || '').trim();
+        if (text)
+            steps.push({ text, status });
+    }
+    return steps.length ? { explanation: null, steps } : null;
+}
 // ── Tool-call summarization (ported from pikiloom's summarizeClaudeToolUse) ──────────
 // Turns a Claude tool_use {name,input} into a one-line human summary. The runtime's
 // activity projector joins these into snapshot.activity; the structured form lives in

package/dist/drivers/codex.js

@@ -241,7 +241,21 @@ export class CodexDriver {
         const ok = await srv.start();
         if (!ok)
             return { ok: false, text: '', error: 'failed to start codex app-server', stopReason: 'error' };
-        const onAbort = () => srv.kill();
+        let settle = () => { };
+        const turnDone = new Promise((res) => { settle = res; });
+        // On abort: gracefully interrupt the running turn, then settle turnDone OURSELVES. A bare
+        // 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 = () => {
+            if (state.sessionId && state.turnId) {
+                srv.call('turn/interrupt', { threadId: state.sessionId, turnId: state.turnId }, 5_000).finally(() => settle());
+            }
+            else {
+                srv.kill();
+                settle();
+            }
+        };
         if (ctx.signal.aborted)
             onAbort();
         else
@@ -264,8 +278,6 @@ export class CodexDriver {
                 state.sessionId = threadId;
                 ctx.emit({ type: 'session', sessionId: threadId });
             }
-            let settle = () => { };
-            const turnDone = new Promise((res) => { settle = res; });
             srv.onNotification((method, params) => {
                 if (params?.threadId && params.threadId !== state.sessionId && method !== 'turn/started')
                     return;

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, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, decideClaudeResultSettle, claudeBgHoldCapMs, type ClaudeResultSettleDecision, } 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/dist/index.js

@@ -19,7 +19,7 @@ export { attachTui } from './runtime/tui.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 // Drivers & surfaces (also available via subpath exports)
 export { EchoDriver } from './drivers/echo.js';
-export { ClaudeDriver } from './drivers/claude.js';
+export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, decideClaudeResultSettle, claudeBgHoldCapMs, } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
 export { AcpDriver } from './drivers/acp.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",