@pikiloom/kernel 0.2.7 → 0.2.8

package/dist/drivers/claude.d.ts

@@ -32,6 +32,8 @@ export declare function claudeEffectiveContextWindow(advertised: 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 claudeModelStallMs(): number;
+export declare function claudeUserEventHasToolResult(ev: any): boolean;
 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;

package/dist/drivers/claude.js

@@ -77,6 +77,10 @@ export class ClaudeDriver {
             // wake-up turns can still land before we close (see claudeBgSettleQuietMs).
             let holdCapTimer = null;
             let quietTimer = null;
+            // modelStall: post-tool watchdog — fires only while the turn is waiting on the MODEL (a
+            // tool_result handed control back and no reply is streaming), never while a tool or
+            // background task is still running (see armModelStall).
+            let modelStallTimer = null;
             const usageOf = () => this.usage(state);
             const unref = (tm) => { if (tm && typeof tm.unref === 'function')
                 tm.unref(); };
@@ -88,6 +92,10 @@ export class ClaudeDriver {
                 clearTimeout(quietTimer);
                 quietTimer = null;
             } };
+            const clearModelStall = () => { if (modelStallTimer) {
+                clearTimeout(modelStallTimer);
+                modelStallTimer = 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
@@ -99,6 +107,7 @@ export class ClaudeDriver {
                 settled = true;
                 clearHoldCap();
                 clearQuiet();
+                clearModelStall();
                 try {
                     child?.stdin?.end();
                 }
@@ -121,7 +130,7 @@ export class ClaudeDriver {
                 resolve(r);
             };
             const settleResult = (opts = {}) => finish({
-                ok: !state.error, text: state.text, reasoning: state.reasoning || undefined,
+                ok: opts.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
@@ -141,6 +150,29 @@ export class ClaudeDriver {
                     settleResult({ kill: false }); }, claudeBgSettleQuietMs());
                 unref(quietTimer);
             };
+            // Post-tool model-stall watchdog: after a tool_result hands control back to the model, the
+            // model normally streams its next message within a couple of seconds. If instead it goes
+            // fully silent — no stream/assistant events — the turn is stuck waiting on the MODEL (a
+            // provider stall / rate-limit backoff), NOT on a tool (a running tool has no tool_result
+            // yet, so this is never armed then) and NOT on background work (its own hold, re-checked
+            // below). Left alone the kernel turn hangs forever with the answer never delivered. Bound
+            // it: settle gracefully (no kill) as incomplete with stopReason 'stalled' so the terminal
+            // shows a clear "resend to continue" note instead of a dead spinner. Armed on tool_result,
+            // cleared the moment the model emits anything.
+            const armModelStall = () => {
+                clearModelStall();
+                modelStallTimer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    // Background work legitimately produces no stream events; keep waiting (the bg hold owns it).
+                    if (pendingClaudeBackgroundTasks(state) > 0) {
+                        armModelStall();
+                        return;
+                    }
+                    settleResult({ stopReason: 'stalled', kill: false, ok: false });
+                }, claudeModelStallMs());
+                unref(modelStallTimer);
+            };
             try {
                 child = spawn(this.bin, args, { cwd: input.workdir, env: { ...process.env, ...(input.env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
             }
@@ -190,7 +222,11 @@ export class ClaudeDriver {
                     }
                     handleClaudeEvent(ev, state, ctx.emit);
                     const pending = pendingClaudeBackgroundTasks(state);
+                    // Any model output means the model is alive and streaming — cancel the post-tool stall watchdog.
+                    if (ev.type === 'stream_event' || ev.type === 'assistant')
+                        clearModelStall();
                     if (ev.type === 'result') {
+                        clearModelStall();
                         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') {
@@ -221,6 +257,10 @@ export class ClaudeDriver {
                         else
                             armQuiet();
                     }
+                    // A tool_result handed control back to the model with no background pending — arm the
+                    // post-tool stall watchdog. Cleared above the moment the model's next event streams in.
+                    if (ev.type === 'user' && pending === 0 && claudeUserEventHasToolResult(ev))
+                        armModelStall();
                 }
             });
             child.stderr.on('data', (c) => { stderr += c.toString('utf8'); });
@@ -559,6 +599,23 @@ 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;
 }
+// How long the model may stay COMPLETELY silent after a tool_result (control handed back to it,
+// no background pending) before the driver gives up and settles the turn as 'stalled'. Deliberately
+// generous: legitimate silent extended-thinking (subscription accounts stream no thinking text) and
+// slow providers must not trip it, and a still-running tool never trips it (it has no tool_result
+// yet). This is the backstop for a turn that would otherwise hang forever with the answer never
+// delivered. Override with PIKILOOM_CLAUDE_MODEL_STALL_MS.
+const CLAUDE_MODEL_STALL_DEFAULT_MS = 120_000;
+export function claudeModelStallMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_MODEL_STALL_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_MODEL_STALL_DEFAULT_MS;
+}
+// True when a claude `type:'user'` stream event carries at least one tool_result block — i.e. the
+// tool loop just handed control back to the model. Pure + exported for hermetic testing.
+export function claudeUserEventHasToolResult(ev) {
+    const c = ev?.message?.content;
+    return Array.isArray(c) && c.some((b) => b?.type === 'tool_result');
+}
 // 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;

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