@pikiloom/kernel 0.2.14 → 0.2.15

package/dist/drivers/claude.d.ts

@@ -33,6 +33,9 @@ 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 claudeBgAgentHoldCapMs(): number;
+export declare function claudeTurnHasAgentBackground(s: any): boolean;
+export declare function claudeBgHoldRecheckMs(): number;
 export declare function claudeBgSettleQuietMs(): number;
 export declare function claudeModelStallMs(): number;
 export declare const CLAUDE_TRUNCATED_RECOVERY_PROMPT: string;

package/dist/drivers/claude.js

@@ -59,6 +59,8 @@ export class ClaudeDriver {
             // Dangling-tool-loop tracking: sawToolResult flips on the first tool_result; textSinceToolResult
             // goes false at every tool_result and true again once the model streams visible text.
             sawToolResult: false, textSinceToolResult: false,
+            // Wall-clock of the last parsed stream event — the hold cap defers while this is fresh.
+            lastEventAt: Date.now(),
             sessionId: null, model: null,
             stopReason: null, error: null,
             input: null, output: null, cached: null,
@@ -138,13 +140,29 @@ export class ClaudeDriver {
                 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
-            // "still running in the background" so the empty-text fallback reads right). Idempotent.
+            // Cap while holding for a still-running background task (stopReason marks it as
+            // "still running in the background" so the terminal presentation reads right). Idempotent —
+            // the countdown is absolute from the first arm. Sub-agent-backed holds use the longer
+            // agent cap, and a cap that fires while events are still flowing defers instead of
+            // cutting an actively-working turn mid-generation (the 2026-07-06 "停止不再继续生成":
+            // the 10-min cap yanked a live research turn 22s after its last tool_result and the
+            // graceful-close leak guard then killed the 4 still-running Explore agents).
             const armHoldCap = () => {
                 if (holdCapTimer)
                     return;
-                holdCapTimer = setTimeout(() => { if (!settled)
-                    settleResult({ stopReason: 'background', kill: false }); }, claudeBgHoldCapMs());
+                const capMs = claudeTurnHasAgentBackground(state) ? claudeBgAgentHoldCapMs() : claudeBgHoldCapMs();
+                const fire = () => {
+                    holdCapTimer = null;
+                    if (settled)
+                        return;
+                    if (Date.now() - (state.lastEventAt ?? 0) < claudeBgSettleQuietMs()) {
+                        holdCapTimer = setTimeout(fire, claudeBgHoldRecheckMs());
+                        unref(holdCapTimer);
+                        return;
+                    }
+                    settleResult({ stopReason: 'background', kill: false });
+                };
+                holdCapTimer = setTimeout(fire, capMs);
                 unref(holdCapTimer);
             };
             // Grace close once all background work is done: settle gracefully (no kill) if Claude stays
@@ -225,6 +243,7 @@ export class ClaudeDriver {
                     catch {
                         continue;
                     }
+                    state.lastEventAt = Date.now();
                     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.
@@ -689,6 +708,27 @@ 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;
 }
+// Sub-agent-backed background work (Task/Agent tool launches) gets a much longer hold: these
+// are finite model-driven jobs whose results the turn is genuinely waiting on — a research
+// fleet mapping two repos legitimately runs past the 10-minute daemon cap, and capping it
+// there discarded the agents' work and cut the turn mid-flight ("停止不再继续生成").
+// Override with PIKILOOM_CLAUDE_BG_AGENT_HOLD_MS.
+const CLAUDE_BG_AGENT_HOLD_CAP_DEFAULT_MS = 45 * 60_000;
+export function claudeBgAgentHoldCapMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_BG_AGENT_HOLD_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_BG_AGENT_HOLD_CAP_DEFAULT_MS;
+}
+export function claudeTurnHasAgentBackground(s) {
+    return !!s?.bgAgentTasks?.size;
+}
+// When the hold cap fires while events are still flowing, defer and re-check on this cadence
+// instead of yanking an actively-working turn (the cap bounds SILENT stuck holds, nothing else).
+// Override with PIKILOOM_CLAUDE_BG_HOLD_RECHECK_MS (tests need sub-second rechecks).
+const CLAUDE_BG_HOLD_RECHECK_DEFAULT_MS = 30_000;
+export function claudeBgHoldRecheckMs() {
+    const raw = Number(process.env.PIKILOOM_CLAUDE_BG_HOLD_RECHECK_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : CLAUDE_BG_HOLD_RECHECK_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
@@ -743,6 +783,15 @@ export function trackClaudeBackgroundTask(ev, s) {
     const subtype = ev?.subtype;
     if (subtype !== 'task_started' && subtype !== 'task_updated' && subtype !== 'task_notification')
         return;
+    // Sub-agent-backed background tasks (Task/Agent tool launches) are FINITE model-driven jobs,
+    // unlike a detached shell that may daemonize forever — they earn a much longer hold cap
+    // (see armHoldCap). The task_started's tool_use_id points at the launching tool call, which
+    // for sub-agents lives in s.subAgents.
+    if (subtype === 'task_started') {
+        const tui = String(ev?.tool_use_id ?? '').trim();
+        if (tui && s?.subAgents?.has?.(tui))
+            (s.bgAgentTasks ||= new Set()).add(String(ev?.task_id ?? ev?.id ?? tui));
+    }
     const id = String(ev?.task_id ?? ev?.tool_use_id ?? '').trim();
     if (!id)
         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, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgSettleQuietMs, type ClaudeResultSettleDecision, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, } from './drivers/claude.js';
+export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgAgentHoldCapMs, claudeTurnHasAgentBackground, claudeBgHoldRecheckMs, claudeBgSettleQuietMs, type ClaudeResultSettleDecision, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, } 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, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, } from './drivers/claude.js';
+export { ClaudeDriver, isTerminalTaskStatus, trackClaudeBackgroundTask, pendingClaudeBackgroundTasks, markClaudeTaskNotificationTerminal, decideClaudeResultSettle, claudeBgHoldCapMs, claudeBgAgentHoldCapMs, claudeTurnHasAgentBackground, claudeBgHoldRecheckMs, claudeBgSettleQuietMs, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, } 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.14",
+  "version": "0.2.15",
   "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",