pikiloom 0.4.61 → 0.4.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.61",
+  "version": "0.4.62",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "dist/",
     "dashboard/dist/",
     "packages/kernel/dist/",
+    "packages/kernel/examples/console.html",
     "LICENSE",
     "README.md"
   ],

package/packages/kernel/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/packages/kernel/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/packages/kernel/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;
@@ -56,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;

package/packages/kernel/dist/drivers/claude.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { extname } from 'node:path';
-import { discoverClaudeNativeSessions } from '../workspace/native.js';
+import { discoverClaudeNativeSessions } from './native.js';
+import { attachedFileNote, contextPercent, createLineBuffer, imageMimeForFile, parseJsonLine, sigterm, wireAbort } from './shared.js';
 // Real driver: shells the local `claude` CLI in stream-json mode and normalizes its
 // events into kernel DriverEvents. Faithful to pikiloom's claude.ts event shapes
 // (system / stream_event{message_start,content_block_delta,message_delta} / assistant / result),
@@ -71,8 +71,11 @@ export class ClaudeDriver {
             taskList: new Map(),
             taskOrder: [],
             pendingTaskCreates: new Map(),
-            // run_in_background lifecycle: task ids seen as started vs. reached a terminal status.
-            bgStarted: new Set(), bgTerminal: new Set(),
+            todoPlan: null,
+            seenImages: new Set(),
+            // run_in_background lifecycle: task ids seen as started vs. reached a terminal status;
+            // bgAgentTasks marks the sub-agent-backed ones (they earn the longer hold cap).
+            bgStarted: new Set(), bgTerminal: new Set(), bgAgentTasks: new Set(),
         };
         return new Promise((resolve) => {
             let child;
@@ -124,17 +127,10 @@ export class ClaudeDriver {
                 }
                 catch { /* ignore */ }
                 if (!child.killed && child.exitCode == null) {
-                    if (kill) {
-                        try {
-                            child.kill('SIGTERM');
-                        }
-                        catch { /* ignore */ }
-                    }
+                    if (kill)
+                        sigterm(child);
                     else {
-                        const guard = setTimeout(() => { try {
-                            child?.kill('SIGTERM');
-                        }
-                        catch { /* ignore */ } }, CLAUDE_EXIT_LEAK_GUARD_MS);
+                        const guard = setTimeout(() => sigterm(child), CLAUDE_EXIT_LEAK_GUARD_MS);
                         unref(guard);
                     }
                 }
@@ -207,14 +203,7 @@ export class ClaudeDriver {
                 finish({ ok: false, text: '', error: `spawn failed: ${err?.message || err}`, stopReason: 'error' });
                 return;
             }
-            const onAbort = () => { try {
-                child.kill('SIGTERM');
-            }
-            catch { /* ignore */ } };
-            if (ctx.signal.aborted)
-                onAbort();
-            else
-                ctx.signal.addEventListener('abort', onAbort, { once: true });
+            wireAbort(ctx.signal, () => sigterm(child));
             if (steerable) {
                 ctx.registerSteer(async (prompt, attachments) => {
                     try {
@@ -226,27 +215,17 @@ export class ClaudeDriver {
                     }
                 });
             }
-            let buf = '';
+            const nextLines = createLineBuffer();
             let stderr = '';
             child.stdout.on('data', (chunk) => {
                 if (settled)
                     return; // ignore the process's post-settle shutdown chatter
-                buf += chunk.toString('utf8');
-                const lines = buf.split('\n');
-                buf = lines.pop() || '';
-                for (const line of lines) {
+                for (const line of nextLines(chunk)) {
                     if (settled)
                         return;
-                    const trimmed = line.trim();
-                    if (!trimmed)
+                    const ev = parseJsonLine(line);
+                    if (ev === undefined)
                         continue;
-                    let ev;
-                    try {
-                        ev = JSON.parse(trimmed);
-                    }
-                    catch {
-                        continue;
-                    }
                     state.lastEventAt = Date.now();
                     handleClaudeEvent(ev, state, ctx.emit);
                     const pending = pendingClaudeBackgroundTasks(state);
@@ -374,7 +353,7 @@ export class ClaudeDriver {
         return claudeUsageOf(s);
     }
 }
-export function claudeUsageOf(s) {
+function claudeUsageOf(s) {
     // 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
@@ -382,22 +361,20 @@ export function claudeUsageOf(s) {
     // 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) + effOutput;
     return {
         inputTokens: s.input,
         outputTokens: s.output,
         cachedInputTokens: s.cached,
         contextUsedTokens: used > 0 ? used : null,
-        contextPercent,
+        contextPercent: contextPercent(used > 0 ? used : null, s.contextWindow ?? null),
         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) {
+function applyClaudeThinkingEstimate(s, ev) {
     const prev = s.thinkingEstTokens ?? 0;
     const delta = Number(ev?.estimated_tokens_delta);
     const total = Number(ev?.estimated_tokens);
@@ -410,7 +387,7 @@ export function applyClaudeThinkingEstimate(s, ev) {
 // 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.
-export function claudeContextWindowFromModel(model) {
+function claudeContextWindowFromModel(model) {
     const id = String(model ?? '').trim().toLowerCase();
     if (!id)
         return null;
@@ -424,7 +401,7 @@ export function claudeContextWindowFromModel(model) {
 }
 // Usable window = advertised minus Claude's max-output (20k) + autocompact (13k) reserve.
 const CLAUDE_USABLE_WINDOW_RESERVE = 33_000;
-export function claudeEffectiveContextWindow(advertised) {
+function claudeEffectiveContextWindow(advertised) {
     if (advertised == null)
         return null;
     return advertised <= CLAUDE_USABLE_WINDOW_RESERVE ? advertised : advertised - CLAUDE_USABLE_WINDOW_RESERVE;
@@ -944,11 +921,6 @@ export function decideClaudeResultSettle(input) {
         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 = {
-    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif', '.webp': 'image/webp',
-};
 // A stream-json user message (for --input-format stream-json; used to send the prompt and to
 // inject mid-turn steer messages while stdin stays open). Image attachments are inlined as base64
 // image content blocks so the model actually sees them; other files become a text note. Without
@@ -956,7 +928,7 @@ const CLAUDE_IMAGE_MIME = {
 export function claudeUserMessage(text, attachments) {
     const content = [];
     for (const filePath of attachments || []) {
-        const mime = CLAUDE_IMAGE_MIME[extname(filePath).toLowerCase()];
+        const mime = imageMimeForFile(filePath);
         if (mime) {
             try {
                 content.push({ type: 'image', source: { type: 'base64', media_type: mime, data: readFileSync(filePath).toString('base64') } });
@@ -964,13 +936,13 @@ export function claudeUserMessage(text, attachments) {
             }
             catch { /* unreadable -> fall through to a text note */ }
         }
-        content.push({ type: 'text', text: `[Attached file: ${filePath}]` });
+        content.push({ type: 'text', text: attachedFileNote(filePath) });
     }
     content.push({ type: 'text', text });
     return JSON.stringify({ type: 'user', message: { role: 'user', content } });
 }
 // Surface base64 image content blocks as artifacts (data URLs), deduped per turn.
-export function emitClaudeImages(blocks, s, emit) {
+function emitClaudeImages(blocks, s, emit) {
     if (!Array.isArray(blocks))
         return;
     s.seenImages ||= new Set();
@@ -1014,7 +986,7 @@ export function todoWriteToPlan(input) {
 // dashboard's task-list card never renders. Ported from pikiloom's legacy claude driver.
 // The assigned task id from a TaskCreate tool_result. Prefer the structured field; fall back
 // to parsing "Task #N" from a string result.
-export function readClaudeTaskCreateId(ev, block) {
+function readClaudeTaskCreateId(ev, block) {
     const structured = ev?.toolUseResult?.task?.id;
     if (structured != null && String(structured).trim())
         return String(structured).trim();
@@ -1026,7 +998,7 @@ export function readClaudeTaskCreateId(ev, block) {
     }
     return null;
 }
-export function rebuildClaudeTaskPlan(s) {
+function rebuildClaudeTaskPlan(s) {
     if (!Array.isArray(s?.taskOrder) || !s.taskOrder.length)
         return null;
     const steps = [];
@@ -1048,7 +1020,7 @@ export function rebuildClaudeTaskPlan(s) {
 // Used when the id isn't in the TaskCreate store, so an update issued AFTER a TodoWrite still
 // lands on the displayed list — the plan reflects the state after the LAST change, whichever
 // mechanism wrote it. Returns a fresh plan (never mutates) or null when inapplicable.
-export function applyTaskUpdateToTodoPlan(plan, taskId, rawStatus) {
+function applyTaskUpdateToTodoPlan(plan, taskId, rawStatus) {
     if (!plan || !Array.isArray(plan.steps) || !plan.steps.length)
         return null;
     if (!/^\d+$/.test(taskId))
@@ -1072,7 +1044,7 @@ export function applyTaskUpdateToTodoPlan(plan, taskId, rawStatus) {
 // Turns a Claude tool_use {name,input} into a one-line human summary. The runtime's
 // activity projector joins these into snapshot.activity; the structured form lives in
 // toolCalls. Kept driver-local: knowing Claude's tool input shapes is the driver's job.
-export function shortToolValue(value, max = 140) {
+function shortToolValue(value, max = 140) {
     if (value == null)
         return '';
     const text = (typeof value === 'string' ? value : String(value)).replace(/\s+/g, ' ').trim();
@@ -1084,7 +1056,7 @@ function toolInputDetail(name, input) {
     const i = input || {};
     return i.command || i.file_path || i.path || i.pattern || i.query || i.url || i.description || '';
 }
-export function summarizeToolUse(name, input) {
+function summarizeToolUse(name, input) {
     const tool = String(name || '').trim() || 'Tool';
     const i = input || {};
     const description = shortToolValue(i.description, 120);
@@ -1149,7 +1121,7 @@ export function summarizeToolUse(name, input) {
     }
 }
 // First non-empty line of a tool_result content (string | block[]), for the "summary -> detail" form.
-export function firstResultLine(content) {
+function firstResultLine(content) {
     let text = '';
     if (typeof content === 'string')
         text = content;

package/packages/kernel/dist/drivers/codex.d.ts

@@ -1,5 +1,4 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, TuiInput, TuiSpec, NativeSessionInfo } from '../contracts/driver.js';
-import type { UniversalUsage } from '../protocol/index.js';
 export declare function codexToolSummary(item: any): {
     id: string;
     name: string;
@@ -34,12 +33,3 @@ export declare class CodexDriver implements AgentDriver {
         limit?: number;
     }): NativeSessionInfo[];
 }
-export interface CodexUsageState {
-    input: number | null;
-    output: number | null;
-    cached: number | null;
-    contextUsed?: number | null;
-    contextWindow?: number | null;
-}
-export declare function applyCodexTokenUsage(s: CodexUsageState, rawUsage: any): void;
-export declare function codexUsageOf(s: CodexUsageState): UniversalUsage;