@pikiloom/kernel 0.2.20 → 0.3.1

package/README.md

@@ -205,7 +205,8 @@ interrupts only the current turn and the next queued task promotes.
 | `ClaudeDriver` | `claude` | `claude` CLI, stream-json (+ `--effort`, partial messages) | ✓ | — | ✓ | ✓ |
 | `CodexDriver` | `codex` | `codex app-server` JSON-RPC (HITL via `requestUserInput`) | ✓ | via askUser | ✓ | ✓ |
 | `GeminiDriver` | `gemini` | `gemini --output-format stream-json` | — | — | ✓ | ✓ |
-| `HermesDriver` | `hermes` | ACP `session/update` | — | — | ✓ | — |
+| `AcpDriver` | *(config)* | generic ACP ndjson JSON-RPC — any ACP CLI: `new AcpDriver({ id, command, args })` | — | via askUser | ✓ | — |
+| `HermesDriver` | `hermes` | ACP preset over `AcpDriver` (`hermes acp`) | — | via askUser | ✓ | — |
 | `EchoDriver` | `echo` | none (hermetic, in-process) | ✓ | ✓ | ✓ | ✓ |
 
 Write your own by implementing `AgentDriver` and passing it to `createLoom({ drivers })` (or
@@ -311,16 +312,28 @@ node-builtins-only and additive — every existing port/default is unchanged.
 
 ## Exports
 
-Main entry `@pikiloom/kernel` re-exports everything. Subpaths: `@pikiloom/kernel/drivers`,
-`@pikiloom/kernel/surfaces`, `@pikiloom/kernel/protocol`.
+Main entry `@pikiloom/kernel` is the public API, pinned by `test/api-surface.test.ts`.
+Subpaths: `@pikiloom/kernel/drivers`, `@pikiloom/kernel/surfaces`, `@pikiloom/kernel/protocol`.
+Driver-internal parser/settle helpers are exported only from their modules (for white-box
+tests) and are NOT part of the public surface.
 
 - Runtime: `createLoom`, `Loom`, `Hub`, `SessionRunner`, `runTurn`, `PtyBridge`, `ptyAvailable`, `attachTui`
-- Drivers: `EchoDriver`, `ClaudeDriver`, `CodexDriver`, `GeminiDriver`, `HermesDriver`
+- Drivers: `EchoDriver`, `ClaudeDriver`, `CodexDriver`, `GeminiDriver`, `AcpDriver` (+ `AcpDriverConfig`), `HermesDriver`
+- Native discovery (driver-axis): `discover{Claude,Codex,Gemini}NativeSessions`, `encodeClaudeProjectDir` + type `DiscoverOptions`
 - Surfaces: `WebSurface`, `CliSurface`
 - Ports/defaults: `FsSessionStore`, `NullModelResolver`, `NoopToolProvider`, `PassthroughSystemPromptBuilder`, `AutoCancelInteractionHandler`, `DeferToTerminalInteractionHandler`, `NoopCatalog`, `defaultBaseDir`
-- Workspace: `resolveLoomPaths`, `SessionsManager`, `SkillsManager`, `McpRegistry`, `ensureDirSymlink`, `discover{Claude,Codex,Gemini}NativeSessions` + types `LoomPaths`, `LoomScope`, `ManagedSessionInfo`, `NativeSessionInfo`, `SkillInfo`, `McpCatalogEntry`
-- Protocol: `UniversalSnapshot`, `diffSnapshot`, `applySnapshotPatch`, `emptySnapshot`, `PROTOCOL_VERSION`, all wire/`Client*`/`Server*` message types
-- Types: `AgentDriver`, `AgentTurnInput`, `DriverContext`, `DriverEvent`, `DriverResult`, `LoomIO`, `PromptInput`, `Surface`, `Plugin`, `SpawnContribution`, `SessionStore`, `ModelResolver`, `ToolProvider`, `SystemPromptBuilder`, `InteractionHandler`, `Catalog`, …
+- Workspace: `resolveLoomPaths`, `normalizeStateDirName`, `SessionsManager`, `SkillsManager`, `McpRegistry`, `ensureDirSymlink`, `parseSkillMeta` + types `LoomPaths`, `LoomScope`, `ManagedSessionInfo`, `SkillInfo`, `SkillMeta`, `McpCatalogEntry`
+- Multi-account: `accountTokenSupported`, `accountTokenEnvVar`, `accountTokenEnv` — which env var carries an agent's auth token, so an app can inject a selected account's token per spawn (claude: `CLAUDE_CODE_OAUTH_TOKEN`; storage/selection stay app-side)
+- Protocol: `UniversalSnapshot`, `diffSnapshot`, `applySnapshotPatch`, `emptySnapshot`, `PROTOCOL_VERSION`, `makeSessionKey`, `splitSessionKey`, all wire/`Client*`/`Server*` message types
+- Types: `AgentDriver`, `AgentTurnInput`, `DriverContext`, `DriverEvent`, `DriverResult`, `NativeSessionInfo`, `LoomIO`, `PromptInput`, `Surface`, `Plugin`, `SpawnContribution`, `SessionStore`, `ModelResolver`, `ToolProvider`, `SystemPromptBuilder`, `InteractionHandler`, `Catalog`, …
+
+### Claude driver tuning (env)
+
+The claude driver's background-hold / stall / recovery heuristics ship sane defaults and can
+be tuned per deployment: `PIKILOOM_CLAUDE_BG_HOLD_MS`, `PIKILOOM_CLAUDE_BG_AGENT_HOLD_MS`,
+`PIKILOOM_CLAUDE_BG_HOLD_RECHECK_MS`, `PIKILOOM_CLAUDE_BG_SETTLE_QUIET_MS`,
+`PIKILOOM_CLAUDE_MODEL_STALL_MS`, `PIKILOOM_CLAUDE_TRUNCATED_RECOVERY` (=0 disables),
+`PIKILOOM_CLAUDE_RESUME_NOOP_RETRIES`.
 
 ---
 

package/dist/drivers/acp.js

@@ -1,132 +1,7 @@
-import { spawn } from 'node:child_process';
-import { createInterface } from 'node:readline';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, extname } from 'node:path';
-class AcpRpcError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-    }
-}
-// ── ACP JSON-RPC client over a child process' stdio (ndjson framing) ───────────
-class AcpClient {
-    bin;
-    args;
-    env;
-    cwd;
-    proc = null;
-    nextId = 1;
-    pending = new Map();
-    notifyCb;
-    requestCb;
-    stderrTail = [];
-    constructor(bin, args, env, cwd) {
-        this.bin = bin;
-        this.args = args;
-        this.env = env;
-        this.cwd = cwd;
-    }
-    onNotification(cb) { this.notifyCb = cb; }
-    onRequest(cb) { this.requestCb = cb; }
-    stderrText() { return this.stderrTail.join('\n'); }
-    start() {
-        try {
-            this.proc = spawn(this.bin, this.args, {
-                cwd: this.cwd,
-                stdio: ['pipe', 'pipe', 'pipe'],
-                env: this.env ? { ...process.env, ...this.env } : process.env,
-            });
-        }
-        catch {
-            return false;
-        }
-        const rl = createInterface({ input: this.proc.stdout, crlfDelay: Infinity });
-        rl.on('line', (line) => this.onLine(line));
-        this.proc.stderr.on('data', (chunk) => {
-            for (const ln of chunk.toString('utf8').split('\n')) {
-                const t = ln.trim();
-                if (!t)
-                    continue;
-                this.stderrTail.push(t.slice(0, 240));
-                if (this.stderrTail.length > 20)
-                    this.stderrTail.shift();
-            }
-        });
-        this.proc.on('close', () => { for (const cb of this.pending.values())
-            cb({ error: { message: 'acp process exited' } }); this.pending.clear(); });
-        this.proc.on('error', () => { });
-        return true;
-    }
-    onLine(line) {
-        const t = line.trim();
-        if (!t)
-            return;
-        let m;
-        try {
-            m = JSON.parse(t);
-        }
-        catch {
-            return;
-        } // non-JSON stdout noise
-        if (m.method && m.id != null) {
-            void this.handleRequest(m);
-            return;
-        } // agent -> client request
-        if (m.id != null) { // response to one of our requests
-            const cb = this.pending.get(m.id);
-            if (cb) {
-                this.pending.delete(m.id);
-                cb(m);
-            }
-            return;
-        }
-        if (m.method)
-            this.notifyCb?.(m.method, m.params ?? {}); // notification (session/update)
-    }
-    async handleRequest(m) {
-        const id = m.id;
-        if (!this.requestCb) {
-            this.respondError(id, -32601, `Method not implemented: ${m.method}`);
-            return;
-        }
-        try {
-            const result = await this.requestCb(m.method, m.params ?? {});
-            this.respond(id, result ?? null);
-        }
-        catch (e) {
-            const code = e instanceof AcpRpcError ? e.code : -32603;
-            this.respondError(id, code, e?.message || 'handler error');
-        }
-    }
-    request(method, params, timeoutMs = 60_000) {
-        return new Promise((resolve) => {
-            if (!this.proc || this.proc.killed) {
-                resolve({ error: { message: 'not connected' } });
-                return;
-            }
-            const id = this.nextId++;
-            const timer = setTimeout(() => { this.pending.delete(id); resolve({ error: { message: `ACP '${method}' timed out` } }); }, timeoutMs);
-            this.pending.set(id, (m) => { clearTimeout(timer); resolve(m); });
-            this.write({ jsonrpc: '2.0', id, method, params });
-        });
-    }
-    notify(method, params) { this.write({ jsonrpc: '2.0', method, params }); }
-    respond(id, result) { this.write({ jsonrpc: '2.0', id, result }); }
-    respondError(id, code, message) { this.write({ jsonrpc: '2.0', id, error: { code, message } }); }
-    write(msg) {
-        if (!this.proc || this.proc.killed)
-            return;
-        try {
-            this.proc.stdin.write(JSON.stringify(msg) + '\n');
-        }
-        catch { /* stream closed */ }
-    }
-    kill() { try {
-        this.proc?.kill('SIGTERM');
-    }
-    catch { /* ignore */ } this.proc = null; }
-}
+import { dirname } from 'node:path';
+import { RpcError, StdioRpcClient } from './rpc.js';
+import { attachedFileNote, contextPercent, imageMimeForFile, wireAbort } from './shared.js';
 // ── pikiloom McpServerSpec[] -> ACP mcpServers[] ───────────────────────────────
 export function toAcpMcpServers(servers) {
     if (!servers || !servers.length)
@@ -145,29 +20,19 @@ export function toAcpMcpServers(servers) {
     }
     return out;
 }
-const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
-function mimeForExt(ext) {
-    if (ext === '.jpg' || ext === '.jpeg')
-        return 'image/jpeg';
-    if (ext === '.gif')
-        return 'image/gif';
-    if (ext === '.webp')
-        return 'image/webp';
-    return 'image/png';
-}
 // ACP prompt content blocks: text + inline base64 images; other attachments noted as text.
 export function buildAcpPromptBlocks(prompt, attachments) {
     const blocks = [];
     for (const f of attachments) {
-        const ext = extname(f).toLowerCase();
-        if (IMAGE_EXTS.has(ext)) {
+        const mime = imageMimeForFile(f);
+        if (mime) {
             try {
-                blocks.push({ type: 'image', mimeType: mimeForExt(ext), data: readFileSync(f).toString('base64') });
+                blocks.push({ type: 'image', mimeType: mime, data: readFileSync(f).toString('base64') });
                 continue;
             }
             catch { /* fall through to a text note */ }
         }
-        blocks.push({ type: 'text', text: `[Attached file: ${f}]` });
+        blocks.push({ type: 'text', text: attachedFileNote(f) });
     }
     blocks.push({ type: 'text', text: prompt });
     return blocks;
@@ -260,12 +125,13 @@ export function applyAcpUpdate(update, s, tools, emit) {
         case 'usage_update': {
             if (typeof update.size === 'number')
                 s.contextWindow = update.size;
-            if (typeof update.used === 'number')
-                s.contextUsed = update.used;
             if (typeof update.used === 'number') {
-                const window = s.contextWindow;
-                const contextPercent = window && update.used > 0 ? Math.min(99.9, Math.round((update.used / window) * 1000) / 10) : null;
-                emit({ type: 'usage', usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: update.used, contextPercent } });
+                s.contextUsed = update.used;
+                emit({ type: 'usage', usage: {
+                        inputTokens: null, outputTokens: null, cachedInputTokens: null,
+                        contextUsedTokens: update.used,
+                        contextPercent: contextPercent(update.used > 0 ? update.used : null, s.contextWindow),
+                    } });
             }
             return;
         }
@@ -321,7 +187,7 @@ function fallbackOptionId(options, fallback) {
 function readAcpTextFile(params) {
     const p = String(params?.path || '');
     if (!p || !existsSync(p))
-        throw new AcpRpcError(-32602, `file not found: ${p}`);
+        throw new RpcError(-32602, `file not found: ${p}`);
     let content = readFileSync(p, 'utf8');
     const line = typeof params?.line === 'number' ? params.line : null;
     const limit = typeof params?.limit === 'number' ? params.limit : null;
@@ -335,7 +201,7 @@ function readAcpTextFile(params) {
 function writeAcpTextFile(params) {
     const p = String(params?.path || '');
     if (!p)
-        throw new AcpRpcError(-32602, 'path required');
+        throw new RpcError(-32602, 'path required');
     try {
         mkdirSync(dirname(p), { recursive: true });
     }
@@ -351,9 +217,11 @@ function acpUsage(s, raw) {
         output = n(raw.outputTokens ?? raw.output_tokens);
         cached = n(raw.cachedReadTokens ?? raw.cached_read_tokens ?? raw.cachedInputTokens);
     }
-    const window = s.contextWindow, used = s.contextUsed;
-    const contextPercent = window && used ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
-    return { inputTokens: input, outputTokens: output, cachedInputTokens: cached, contextUsedTokens: used, contextPercent, turnOutputTokens: output };
+    const used = s.contextUsed;
+    return {
+        inputTokens: input, outputTokens: output, cachedInputTokens: cached, contextUsedTokens: used,
+        contextPercent: contextPercent(used || null, s.contextWindow), turnOutputTokens: output,
+    };
 }
 export class AcpDriver {
     id;
@@ -376,19 +244,18 @@ export class AcpDriver {
     }
     async run(input, ctx) {
         const env = { ...(this.cfg.env || {}), ...(input.env || {}) };
-        const client = new AcpClient(this.cfg.command, this.cfg.args, env, input.workdir);
+        const client = new StdioRpcClient({ command: this.cfg.command, args: this.cfg.args, env, cwd: input.workdir, label: this.id });
         const state = { text: '', reasoning: '', contextWindow: null, contextUsed: null };
         const tools = new Set();
         let sessionId = input.sessionId ?? null;
         let permSeq = 0;
         if (!client.start())
             return { ok: false, text: '', error: `failed to start ${this.cfg.command}`, stopReason: 'error' };
-        const onAbort = () => { if (sessionId)
-            client.notify('session/cancel', { sessionId }); client.kill(); };
-        if (ctx.signal.aborted)
-            onAbort();
-        else
-            ctx.signal.addEventListener('abort', onAbort, { once: true });
+        const unwireAbort = wireAbort(ctx.signal, () => {
+            if (sessionId)
+                client.notify('session/cancel', { sessionId });
+            client.kill();
+        });
         client.onNotification((method, params) => {
             if (method === 'session/update')
                 applyAcpUpdate(params?.update ?? params, state, tools, ctx.emit);
@@ -398,14 +265,14 @@ export class AcpDriver {
                 case 'session/request_permission': return this.resolvePermission(params, ctx, `${this.id}-perm-${++permSeq}`);
                 case 'fs/read_text_file':
                     if (!this.cfg.fsAccess)
-                        throw new AcpRpcError(-32601, 'fs/read_text_file not supported');
+                        throw new RpcError(-32601, 'fs/read_text_file not supported');
                     return readAcpTextFile(params);
                 case 'fs/write_text_file':
                     if (!this.cfg.fsAccess)
-                        throw new AcpRpcError(-32601, 'fs/write_text_file not supported');
+                        throw new RpcError(-32601, 'fs/write_text_file not supported');
                     return writeAcpTextFile(params);
                 default:
-                    throw new AcpRpcError(-32601, `Method not implemented: ${method}`);
+                    throw new RpcError(-32601, `Method not implemented: ${method}`);
             }
         });
         try {
@@ -447,7 +314,7 @@ export class AcpDriver {
             return { ok: true, text: state.text, reasoning: state.reasoning || undefined, error: null, stopReason, sessionId, usage };
         }
         finally {
-            ctx.signal.removeEventListener('abort', onAbort);
+            unwireAbort();
             client.kill();
         }
     }

package/dist/drivers/claude.d.ts

@@ -1,5 +1,5 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
-import type { UniversalUsage, UniversalPlan } from '../protocol/index.js';
+import type { UniversalPlan } from '../protocol/index.js';
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -18,19 +18,6 @@ export declare class ClaudeDriver implements AgentDriver {
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     private usage;
 }
-export interface ClaudeUsageState {
-    input: number | null;
-    output: number | null;
-    cached: number | null;
-    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 claudeBgAgentHoldCapMs(): number;
@@ -40,6 +27,9 @@ export declare function claudeBgSettleQuietMs(): number;
 export declare function claudeModelStallMs(): number;
 export declare const CLAUDE_TRUNCATED_RECOVERY_PROMPT: string;
 export declare function claudeTruncatedRecoveryEnabled(): boolean;
+export declare function isClaudeSyntheticResumeNoise(text: string): boolean;
+export declare function claudeProducedRealOutput(s: any): boolean;
+export declare function claudeResumeNoopRetryLimit(): number;
 export declare function claudeUserEventHasToolResult(ev: any): boolean;
 export declare function isTerminalTaskStatus(status: unknown): boolean;
 export declare function trackClaudeBackgroundTask(ev: any, s: any): void;
@@ -53,11 +43,4 @@ export declare function decideClaudeResultSettle(input: {
     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;
 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 applyTaskUpdateToTodoPlan(plan: UniversalPlan | null | undefined, taskId: string, rawStatus: string): 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;