@pikiloom/kernel 0.2.4 → 0.2.6

package/dist/drivers/claude.d.ts

@@ -31,13 +31,16 @@ export declare function claudeContextWindowFromModel(model: unknown): number | n
 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 claudeBgHoldCapMs(): number;
+export declare function claudeBgSettleQuietMs(): number;
 export declare function isTerminalTaskStatus(status: unknown): boolean;
 export declare function trackClaudeBackgroundTask(ev: any, s: any): void;
+export declare function markClaudeTaskNotificationTerminal(content: any, s: any): void;
 export declare function pendingClaudeBackgroundTasks(s: any): number;
-export type ClaudeResultSettleDecision = 'settle' | 'hold';
+export type ClaudeResultSettleDecision = 'settle' | 'hold' | 'quiet-settle';
 export declare function decideClaudeResultSettle(input: {
     hasError: boolean;
     pendingBackground: number;
+    sawBackground: boolean;
 }): ClaudeResultSettleDecision;
 export declare function claudeUserMessage(text: string, attachments?: string[]): string;
 export declare function emitClaudeImages(blocks: any[], s: any, emit: (e: DriverEvent) => void): void;

package/dist/drivers/claude.js

@@ -72,12 +72,22 @@ export class ClaudeDriver {
         return new Promise((resolve) => {
             let child;
             let settled = false;
+            // holdCap: hard backstop while a background task is still running (never-completing daemon).
+            // quiet: fires once all known background tasks finished AND Claude has gone quiet, so trailing
+            // wake-up turns can still land before we close (see claudeBgSettleQuietMs).
             let holdCapTimer = null;
+            let quietTimer = null;
             const usageOf = () => this.usage(state);
+            const unref = (tm) => { if (tm && typeof tm.unref === 'function')
+                tm.unref(); };
             const clearHoldCap = () => { if (holdCapTimer) {
                 clearTimeout(holdCapTimer);
                 holdCapTimer = null;
             } };
+            const clearQuiet = () => { if (quietTimer) {
+                clearTimeout(quietTimer);
+                quietTimer = 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
@@ -88,6 +98,7 @@ export class ClaudeDriver {
                     return;
                 settled = true;
                 clearHoldCap();
+                clearQuiet();
                 try {
                     child?.stdin?.end();
                 }
@@ -104,8 +115,7 @@ export class ClaudeDriver {
                             child?.kill('SIGTERM');
                         }
                         catch { /* ignore */ } }, CLAUDE_EXIT_LEAK_GUARD_MS);
-                        if (typeof guard.unref === 'function')
-                            guard.unref();
+                        unref(guard);
                     }
                 }
                 resolve(r);
@@ -114,6 +124,23 @@ export class ClaudeDriver {
                 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);
+            // Absolute cap while holding for a still-running background task (stopReason marks it as
+            // "still running in the background" so the empty-text fallback reads right). Idempotent.
+            const armHoldCap = () => {
+                if (holdCapTimer)
+                    return;
+                holdCapTimer = setTimeout(() => { if (!settled)
+                    settleResult({ stopReason: 'background', kill: false }); }, claudeBgHoldCapMs());
+                unref(holdCapTimer);
+            };
+            // Grace close once all background work is done: settle gracefully (no kill) if Claude stays
+            // quiet for the window. Re-armed on every event, so a still-streaming wake-up keeps it open.
+            const armQuiet = () => {
+                clearQuiet();
+                quietTimer = setTimeout(() => { if (!settled)
+                    settleResult({ kill: false }); }, claudeBgSettleQuietMs());
+                unref(quietTimer);
+            };
             try {
                 child = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
             }
@@ -162,24 +189,38 @@ export class ClaudeDriver {
                         continue;
                     }
                     handleClaudeEvent(ev, state, ctx.emit);
-                    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();
+                    if (ev.type === 'result') {
+                        const hasError = !!ev.is_error || (Array.isArray(ev.errors) && ev.errors.length > 0) || !!state.error;
+                        const decision = decideClaudeResultSettle({ hasError, pendingBackground: pending, sawBackground: state.bgStarted.size > 0 });
+                        if (decision === 'settle') {
+                            settleResult();
+                            return;
                         }
+                        if (decision === 'hold') {
+                            clearQuiet();
+                            armHoldCap();
+                            continue;
+                        }
+                        // 'quiet-settle': every known background task finished, but Claude may still be delivering
+                        // wake-up turns whose delivery trails the completion status (with parallel agents the last
+                        // one's completion can land before an earlier one's wake-up result). Don't exit here — wait
+                        // for Claude to go quiet, then close gracefully so no in-flight wake-up is torn down. Keep
+                        // the hold cap armed as an absolute backstop.
+                        armHoldCap();
+                        armQuiet();
                         continue;
                     }
-                    settleResult();
+                    // Non-result activity: a still-streaming wake-up refreshes the quiet window; a newly-started
+                    // background task pulls us back into the hold.
+                    if (quietTimer) {
+                        if (pending > 0) {
+                            clearQuiet();
+                            armHoldCap();
+                        }
+                        else
+                            armQuiet();
+                    }
                 }
             });
             child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
@@ -424,10 +465,13 @@ export function handleClaudeEvent(ev, s, emit) {
         return;
     }
     if (t === 'user') {
+        // Background wake-up delivery: a `<task-notification>` tag (as a string or a text block) marks
+        // its background task terminal — an extra completion signal alongside the system task events.
+        markClaudeTaskNotificationTerminal(ev.message?.content, s);
         // Tool results: surface generated images as artifacts AND close out the tool call
         // (status done/failed + a result detail) so toolCalls is a faithful structured SSOT
         // and the runtime's activity projection can render the execution trail.
-        const contents = ev.message?.content || [];
+        const contents = Array.isArray(ev.message?.content) ? ev.message.content : [];
         for (const b of contents) {
             if (b?.type !== 'tool_result')
                 continue;
@@ -503,6 +547,18 @@ 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;
 }
+// Once every KNOWN background task has finished, how long Claude must stay quiet (no further
+// output at all) before we close a background turn. A completed task's status races AHEAD of the
+// wake-up turn that reports it — with N parallel agents finishing together, the last agent's
+// completion can land before an earlier agent's wake-up result, so exiting at the first
+// pending==0 result would kill the still-undelivered wake-ups (the "background was running when
+// the process exited" failure). Refreshed on every event, so a still-streaming wake-up keeps it
+// alive. Override with PIKILOOM_CLAUDE_BG_SETTLE_QUIET_MS.
+const CLAUDE_BG_SETTLE_QUIET_DEFAULT_MS = 15_000;
+export function claudeBgSettleQuietMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_BG_SETTLE_QUIET_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_BG_SETTLE_QUIET_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;
@@ -524,6 +580,32 @@ export function trackClaudeBackgroundTask(ev, s) {
     if (isTerminalTaskStatus(ev?.patch?.status ?? ev?.status))
         (s.bgTerminal ||= new Set()).add(id);
 }
+function claudeContentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+    return '';
+}
+// Extra completion signal (mirrors the legacy driver): Claude delivers a background wake-up as a
+// `type:'user'` message carrying a `<task-notification>` tag (<task-id>/<tool-use-id>/<status>).
+// Mark that task terminal too, so a missed/absent system task_notification still lets pending
+// reach 0 (instead of the turn hanging to the hold cap).
+export function markClaudeTaskNotificationTerminal(content, s) {
+    const text = claudeContentText(content);
+    if (!text || !text.includes('<task-notification>'))
+        return;
+    const tag = (name) => {
+        const m = text.match(new RegExp(`<${name}>\\s*([^<]*?)\\s*</${name}>`));
+        return m ? m[1].trim() : '';
+    };
+    const status = tag('status');
+    if (status && !isTerminalTaskStatus(status))
+        return;
+    for (const id of [tag('task-id'), tag('tool-use-id')])
+        if (id)
+            (s.bgTerminal ||= new Set()).add(id);
+}
 export function pendingClaudeBackgroundTasks(s) {
     const started = s?.bgStarted;
     if (!started?.size)
@@ -535,12 +617,19 @@ export function pendingClaudeBackgroundTasks(s) {
             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.
+// At a `result` event, decide how to end the turn:
+//  - error                               → 'settle' now (hard exit).
+//  - a background task is still running   → 'hold' the process open for its wake-up.
+//  - background done BUT this turn launched background work → 'quiet-settle': do NOT exit at this
+//    result. Claude may still be DELIVERING wake-up turns whose delivery trails their task's
+//    completion status (see claudeBgSettleQuietMs); wait for it to go quiet, then close gracefully.
+//  - a plain turn (no background)         → 'settle' now.
 export function decideClaudeResultSettle(input) {
     if (input.hasError)
         return 'settle';
-    return input.pendingBackground > 0 ? 'hold' : 'settle';
+    if (input.pendingBackground > 0)
+        return 'hold';
+    return input.sawBackground ? 'quiet-settle' : 'settle';
 }
 // Claude vision input formats (matches the legacy driver / Anthropic API: png, jpeg, gif, webp).
 const CLAUDE_IMAGE_MIME = {

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, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, decideClaudeResultSettle, claudeBgHoldCapMs, type ClaudeResultSettleDecision, } from './drivers/claude.js';
+export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgSettleQuietMs, 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, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, decideClaudeResultSettle, claudeBgHoldCapMs, } from './drivers/claude.js';
+export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgSettleQuietMs, } 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.4",
+  "version": "0.2.6",
   "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",