@pikiloom/kernel 0.2.7 → 0.2.9

package/dist/drivers/claude.d.ts

@@ -25,13 +25,17 @@ export interface ClaudeUsageState {
     cacheCreation?: number | null;
     contextWindow?: number | null;
     turnOutputTokensBase?: number | null;
+    thinkingEstTokens?: number | null;
 }
 export declare function claudeUsageOf(s: ClaudeUsageState): UniversalUsage;
+export declare function applyClaudeThinkingEstimate(s: any, ev: any): boolean;
 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 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

@@ -60,7 +60,7 @@ export class ClaudeDriver {
             stopReason: null, error: null,
             input: null, output: null, cached: null,
             cacheCreation: null,
-            contextWindow: null, turnOutputTokensBase: 0,
+            contextWindow: null, turnOutputTokensBase: 0, thinkingEstTokens: 0,
             subAgents: new Map(),
             tools: new Map(),
             taskList: new Map(),
@@ -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'); });
@@ -248,10 +288,16 @@ export class ClaudeDriver {
     }
 }
 export function claudeUsageOf(s) {
-    const used = (s.input ?? 0) + (s.cached ?? 0) + (s.cacheCreation ?? 0) + (s.output ?? 0);
+    // While a message is still streaming, the CLI's live thinking estimate (system/thinking_tokens)
+    // is often the ONLY output signal — subscription accounts stream no plaintext thinking and no
+    // usage until the message settles. Fold it into the derived numbers (never into the raw
+    // outputTokens) so the row ticks during silent extended thinking; the real per-message
+    // output_tokens supersedes it at message_delta.
+    const effOutput = Math.max(s.output ?? 0, s.thinkingEstTokens ?? 0);
+    const used = (s.input ?? 0) + (s.cached ?? 0) + (s.cacheCreation ?? 0) + effOutput;
     const window = s.contextWindow ?? null;
     const contextPercent = window && used > 0 ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
-    const turnOutput = (s.turnOutputTokensBase ?? 0) + (s.output ?? 0);
+    const turnOutput = (s.turnOutputTokensBase ?? 0) + effOutput;
     return {
         inputTokens: s.input,
         outputTokens: s.output,
@@ -261,6 +307,19 @@ export function claudeUsageOf(s) {
         turnOutputTokens: turnOutput > 0 ? turnOutput : null,
     };
 }
+// Accumulate the CLI's live thinking-token estimate onto driver state. Prefer the per-event
+// delta (correct whether the CLI's running total is per-message or per-turn); fall back to a
+// monotonic max of the running total. Returns true when the estimate advanced.
+export function applyClaudeThinkingEstimate(s, ev) {
+    const prev = s.thinkingEstTokens ?? 0;
+    const delta = Number(ev?.estimated_tokens_delta);
+    const total = Number(ev?.estimated_tokens);
+    if (Number.isFinite(delta) && delta > 0)
+        s.thinkingEstTokens = prev + delta;
+    else if (Number.isFinite(total))
+        s.thinkingEstTokens = Math.max(prev, total);
+    return (s.thinkingEstTokens ?? 0) > prev;
+}
 // Advertised context window by Claude model id (best-effort; unknown -> null so the
 // percent simply stays absent rather than wrong). Anchor-free so vendor-prefixed ids
 // (us.anthropic.claude-…) still match.
@@ -319,6 +378,13 @@ export function handleClaudeEvent(ev, s, emit) {
         }
         s.model = ev.model ?? s.model;
         s.contextWindow = claudeEffectiveContextWindow(claudeContextWindowFromModel(s.model)) ?? s.contextWindow;
+        // Live thinking progress (system/thinking_tokens, ~every 1.4s of sustained thinking): during
+        // extended thinking a subscription account streams no plaintext (signature_delta only) and no
+        // usage until the message settles, so without projecting these the terminal shows a dead
+        // spinner for the whole thinking phase.
+        if (ev.subtype === 'thinking_tokens' && applyClaudeThinkingEstimate(s, ev)) {
+            emit({ type: 'usage', usage: claudeUsageOf(s) });
+        }
         return;
     }
     if (t === 'stream_event') {
@@ -328,11 +394,17 @@ export function handleClaudeEvent(ev, s, emit) {
             // Claude emits one message per tool-use round within a single turn. Carry the prior
             // message's output into the per-turn base, then reset to the new message's prompt size
             // so contextUsedTokens tracks current occupancy while turnOutputTokens sums the turn.
-            s.turnOutputTokensBase = (s.turnOutputTokensBase ?? 0) + (s.output ?? 0);
+            // A message that never delivered real output_tokens keeps its thinking estimate as the carry.
+            s.turnOutputTokensBase = (s.turnOutputTokensBase ?? 0) + Math.max(s.output ?? 0, s.thinkingEstTokens ?? 0);
             s.input = u?.input_tokens ?? 0;
             s.cached = u?.cache_read_input_tokens ?? 0;
             s.cacheCreation = u?.cache_creation_input_tokens ?? 0;
             s.output = 0;
+            s.thinkingEstTokens = 0;
+            // The prompt-side counts are known the moment the model accepts the request — emit them so
+            // the context row appears right away instead of only after the first message settles
+            // (minutes into a long silent thinking phase, the "looks stuck" report).
+            emit({ type: 'usage', usage: claudeUsageOf(s) });
         }
         else if (inner.type === 'content_block_start') {
             // Claude emits multiple text/thinking blocks per turn (one set per tool-use round). Insert a
@@ -367,8 +439,11 @@ export function handleClaudeEvent(ev, s, emit) {
         else if (inner.type === 'message_delta') {
             const u = inner.usage;
             if (u) {
-                if (u.output_tokens != null)
+                // Real reported output supersedes the live thinking estimate for this message.
+                if (u.output_tokens != null) {
                     s.output = u.output_tokens;
+                    s.thinkingEstTokens = 0;
+                }
                 if (u.input_tokens != null)
                     s.input = u.input_tokens;
                 if (u.cache_read_input_tokens != null)
@@ -475,8 +550,13 @@ export function handleClaudeEvent(ev, s, emit) {
         for (const b of contents) {
             if (b?.type !== 'tool_result')
                 continue;
-            emitClaudeImages(b.content || [], s, emit);
             const id = String(b.tool_use_id || '').trim();
+            // A Read result is the agent inspecting a file, not a deliverable — surfacing those spammed
+            // the chat with every image the agent looked at (the legacy driver has the same exclusion).
+            // Images from generating tools (MCP image-gen, screenshots, …) still surface as photos.
+            const tool = id ? s.tools?.get(id) : undefined;
+            if (tool?.name !== 'Read')
+                emitClaudeImages(b.content || [], s, emit);
             // 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);
@@ -494,7 +574,6 @@ export function handleClaudeEvent(ev, s, emit) {
                 }
                 continue;
             }
-            const tool = id ? s.tools?.get(id) : undefined;
             if (!tool)
                 continue;
             const isError = !!b.is_error;
@@ -559,6 +638,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.9",
   "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",