@pikiloom/kernel 0.2.21 → 0.3.1

package/dist/drivers/shared.js

@@ -0,0 +1,66 @@
+import { extname } from 'node:path';
+// Driver-internal helpers shared by the concrete drivers (claude/codex/gemini/acp).
+// NOT part of the public API — nothing here is re-exported by any barrel. Each helper
+// exists because the same code appeared verbatim in 3+ drivers.
+/** Stateful newline splitter for a child process' stdout: feed chunks, get complete lines. */
+export function createLineBuffer() {
+    let buf = '';
+    return (chunk) => {
+        buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        return lines;
+    };
+}
+/** Parse one ndjson line; undefined for blank lines / non-JSON noise. */
+export function parseJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run `fn` when the signal aborts (immediately if it already has). Returns an
+ * unsubscribe for drivers that must detach the handler when the turn settles.
+ */
+export function wireAbort(signal, fn) {
+    if (signal.aborted) {
+        fn();
+        return () => { };
+    }
+    signal.addEventListener('abort', fn, { once: true });
+    return () => signal.removeEventListener('abort', fn);
+}
+/** SIGTERM a child, swallowing the already-dead race. */
+export function sigterm(proc) {
+    try {
+        proc?.kill('SIGTERM');
+    }
+    catch { /* ignore */ }
+}
+// Attachment vocabulary: every driver inlines the same image formats (the Anthropic
+// vision set, which the others accept too) and notes non-image files the same way.
+const IMAGE_MIME_BY_EXT = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp',
+};
+/** Mime type when the file is an inlineable image, else null. */
+export function imageMimeForFile(filePath) {
+    return IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? null;
+}
+/** The text note substituted for a non-image attachment. */
+export function attachedFileNote(filePath) {
+    return `[Attached file: ${filePath}]`;
+}
+/**
+ * Context-window occupancy as a display percent (one decimal, capped at 99.9).
+ * Pass `used` as null when the caller wants "no data" rather than 0%.
+ */
+export function contextPercent(used, window) {
+    return window && used != null ? Math.min(99.9, Math.round((used / window) * 1000) / 10) : null;
+}

package/dist/index.d.ts

@@ -9,13 +9,14 @@ 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, claudeBgAgentHoldCapMs, claudeTurnHasAgentBackground, claudeBgHoldRecheckMs, claudeBgSettleQuietMs, type ClaudeResultSettleDecision, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, isClaudeSyntheticResumeNoise, claudeProducedRealOutput, claudeResumeNoopRetryLimit, } from './drivers/claude.js';
+export { ClaudeDriver } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
 export { AcpDriver, type AcpDriverConfig } from './drivers/acp.js';
 export { HermesDriver } from './drivers/hermes.js';
 export { WebSurface, type WebSurfaceOptions } from './surfaces/web.js';
 export { CliSurface } from './surfaces/cli.js';
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, type DiscoverOptions, } from './drivers/native.js';
 export * from './workspace/index.js';
 export * from './accounts.js';
 export * from './protocol/index.js';

package/dist/index.js

@@ -8,6 +8,10 @@
 //   await loom.start()
 //
 // pikiloom itself is just a consumer of this package.
+//
+// This barrel IS the public API (pinned by test/api-surface.test.ts). Driver-internal
+// parser/settle helpers are exported by their modules for white-box tests but are
+// deliberately NOT re-exported here.
 export { createLoom } from './runtime/loom.js';
 export { Hub } from './runtime/hub.js';
 export { SessionRunner } from './runtime/session-runner.js';
@@ -19,16 +23,20 @@ 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, claudeBgAgentHoldCapMs, claudeTurnHasAgentBackground, claudeBgHoldRecheckMs, claudeBgSettleQuietMs, claudeModelStallMs, claudeUserEventHasToolResult, handleClaudeEvent, claudeTurnEndedDangling, claudeTruncatedRecoveryEnabled, CLAUDE_TRUNCATED_RECOVERY_PROMPT, isClaudeSyntheticResumeNoise, claudeProducedRealOutput, claudeResumeNoopRetryLimit, } from './drivers/claude.js';
+export { ClaudeDriver } from './drivers/claude.js';
 export { CodexDriver } from './drivers/codex.js';
 export { GeminiDriver } from './drivers/gemini.js';
 export { AcpDriver } from './drivers/acp.js';
 export { HermesDriver } from './drivers/hermes.js';
 export { WebSurface } from './surfaces/web.js';
 export { CliSurface } from './surfaces/cli.js';
+// Native-session discovery: pure readers of each agent CLI's own transcript store
+// (driver-axis knowledge; drivers implement listNativeSessions with these).
+export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, } from './drivers/native.js';
 // Workspace: unified top-level directory + session/skill/mcp management (loom.paths/sessions/skills/mcp)
 export * from './workspace/index.js';
-// Multi-account: per-account isolated config dirs (CLAUDE_CONFIG_DIR / CODEX_HOME)
+// Multi-account: which env var carries an agent's auth token, so an app can inject a
+// selected account's token per spawn (see accounts.ts for the design notes).
 export * from './accounts.js';
 // Protocol (the wire vocabulary; shared with transports)
 export * from './protocol/index.js';

package/dist/protocol/index.d.ts

@@ -101,6 +101,11 @@ export interface SessionMeta {
     phase?: SessionPhase;
     updatedAt?: number;
 }
+export declare function makeSessionKey(agent: string, sessionId: string): string;
+export declare function splitSessionKey(sessionKey: string): {
+    agent: string;
+    sessionId: string;
+};
 export interface SnapshotPatch {
     full?: UniversalSnapshot;
     appendText?: string;

package/dist/protocol/index.js

@@ -2,6 +2,16 @@
 // This is the SSOT shape: a driver-agnostic, accumulating snapshot of one session,
 // plus a small set of control verbs. Ported from pikiloom's pikichannel protocol.
 export const PROTOCOL_VERSION = 1;
+// ---- Session keys ----
+// A sessionKey is `${agent}:${sessionId}` — the composite id shared by the runtime, every
+// store, and every terminal. These two helpers ARE that contract; nothing else parses it.
+export function makeSessionKey(agent, sessionId) {
+    return `${agent}:${sessionId}`;
+}
+export function splitSessionKey(sessionKey) {
+    const i = sessionKey.indexOf(':');
+    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
+}
 export function emptySnapshot() {
     return { phase: 'idle', updatedAt: 0 };
 }

package/dist/runtime/hub.js

@@ -1,10 +1,6 @@
 import { randomUUID } from 'node:crypto';
-import { diffSnapshot, emptySnapshot, } from '../protocol/index.js';
+import { diffSnapshot, emptySnapshot, makeSessionKey, splitSessionKey, } from '../protocol/index.js';
 import { SessionRunner } from './session-runner.js';
-function splitKey(sessionKey) {
-    const i = sessionKey.indexOf(':');
-    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
-}
 export class Hub {
     deps;
     sessions = new Map();
@@ -57,12 +53,12 @@ export class Hub {
         if (!driver)
             throw new Error(`No driver registered for agent "${agent}"`);
         const workdir = input.workdir || this.deps.workdir;
-        const resumeId = input.sessionKey ? splitKey(input.sessionKey).sessionId : null;
+        const resumeId = input.sessionKey ? splitSessionKey(input.sessionKey).sessionId : null;
         const preExisted = resumeId ? !!(await this.deps.sessionStore.get(agent, resumeId)) : false;
         const { sessionId, workspacePath } = await this.deps.sessionStore.ensure(agent, {
             sessionId: resumeId, workdir, title: input.prompt.slice(0, 80),
         });
-        const sessionKey = `${agent}:${sessionId}`;
+        const sessionKey = makeSessionKey(agent, sessionId);
         const taskId = randomUUID();
         const runner = new SessionRunner(sessionKey, agent, taskId, (snap, seq) => this.onRunnerUpdate(sessionKey, snap, seq), this.deps.interactionHandler);
         this.runnersByTask.set(taskId, runner);
@@ -320,7 +316,7 @@ export class Hub {
         return e ? { snapshot: e.snapshot, seq: e.seq } : null;
     }
     async getHistory(sessionKey) {
-        const { agent, sessionId } = splitKey(sessionKey);
+        const { agent, sessionId } = splitSessionKey(sessionKey);
         if (!agent || !this.deps.sessionStore.history)
             return [];
         try {

package/dist/workspace/index.d.ts

@@ -1,5 +1,4 @@
 export { resolveLoomPaths, normalizeStateDirName, type LoomPaths, type LoomScope } from './paths.js';
-export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, NATIVE_SESSION_RUNNING_THRESHOLD_MS, type DiscoverOptions, type NativeSessionInfo, } from './native.js';
 export { SessionsManager, type ManagedSessionInfo, type SessionSource, type ListSessionsOptions, type SearchSessionsOptions, type SessionsManagerDeps, } from './sessions.js';
-export { SkillsManager, ensureDirSymlink, type SkillInfo, type SkillSearchResult, type SkillsManagerOptions, } from './skills.js';
+export { SkillsManager, ensureDirSymlink, parseSkillMeta, type SkillInfo, type SkillMeta, type SkillSearchResult, type SkillsManagerOptions, } from './skills.js';
 export { McpRegistry, type McpCatalogEntry, type McpSearchResult, type McpRegistryOptions, } from './mcp.js';

package/dist/workspace/index.js

@@ -1,7 +1,8 @@
 // Workspace subsystem: the unified top-level directory + session/skill/mcp management that
 // a consuming app gets "for free" off createLoom() (exposed as loom.paths/sessions/skills/mcp).
+// (Native-session discovery lives with the drivers — drivers/native.ts — because knowing each
+// agent CLI's on-disk transcript format is driver-axis knowledge.)
 export { resolveLoomPaths, normalizeStateDirName } from './paths.js';
-export { discoverClaudeNativeSessions, discoverCodexNativeSessions, discoverGeminiNativeSessions, encodeClaudeProjectDir, NATIVE_SESSION_RUNNING_THRESHOLD_MS, } from './native.js';
 export { SessionsManager, } from './sessions.js';
-export { SkillsManager, ensureDirSymlink, } from './skills.js';
+export { SkillsManager, ensureDirSymlink, parseSkillMeta, } from './skills.js';
 export { McpRegistry, } from './mcp.js';

package/dist/workspace/mcp.js

@@ -1,3 +1,4 @@
+import { searchNpmPackages } from './npm-search.js';
 const BUILTIN_RECOMMENDED = [
     { id: 'filesystem', name: 'Filesystem', description: 'Read/write files under allowed directories.', category: 'core', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] }, homepage: 'https://github.com/modelcontextprotocol/servers' },
     { id: 'github', name: 'GitHub', description: 'GitHub repos, issues, and PRs.', category: 'dev', brand: 'github', transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] }, envKeys: ['GITHUB_PERSONAL_ACCESS_TOKEN'], homepage: 'https://github.com/modelcontextprotocol/servers' },
@@ -57,22 +58,11 @@ export class McpRegistry {
         }
         // 2) npm fallback.
         try {
-            const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(`mcp server ${q}`.trim())}&size=${n}`;
-            const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
-            if (!res.ok)
-                return [];
-            const data = await res.json();
-            const objects = Array.isArray(data?.objects) ? data.objects : [];
-            return objects.map((o) => {
-                const pkg = o?.package ?? {};
-                return {
-                    name: String(pkg.name ?? ''),
-                    description: pkg.description ?? null,
-                    source: 'npm',
-                    npmPackage: pkg.name ?? null,
-                    homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
-                };
-            }).filter(s => s.name).slice(0, n);
+            const hits = await searchNpmPackages(`mcp server ${q}`.trim(), n, fetchImpl);
+            return hits.map(h => ({
+                name: h.name, description: h.description, source: 'npm',
+                npmPackage: h.name, homepage: h.homepage,
+            })).slice(0, n);
         }
         catch (e) {
             this.log?.(`[mcp] npm search failed: ${e?.message || e}`);

package/dist/workspace/npm-search.d.ts

@@ -0,0 +1,9 @@
+export interface NpmPackageHit {
+    name: string;
+    description: string | null;
+    homepage: string | null;
+    author: string | null;
+    version: string | null;
+}
+/** Query registry.npmjs.org's search endpoint. [] on non-OK; throws on network failure. */
+export declare function searchNpmPackages(text: string, size: number, fetchImpl: typeof fetch): Promise<NpmPackageHit[]>;

package/dist/workspace/npm-search.js

@@ -0,0 +1,21 @@
+// Shared npm-registry search used by SkillsManager.search and McpRegistry's npm fallback.
+// Workspace-internal — not exported by any barrel.
+/** Query registry.npmjs.org's search endpoint. [] on non-OK; throws on network failure. */
+export async function searchNpmPackages(text, size, fetchImpl) {
+    const url = `https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(text)}&size=${size}`;
+    const res = await fetchImpl(url, { headers: { accept: 'application/json' } });
+    if (!res.ok)
+        return [];
+    const data = await res.json();
+    const objects = Array.isArray(data?.objects) ? data.objects : [];
+    return objects.map((o) => {
+        const pkg = o?.package ?? {};
+        return {
+            name: String(pkg.name ?? ''),
+            description: pkg.description ?? null,
+            homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
+            author: pkg.publisher?.username ?? pkg.author?.name ?? null,
+            version: pkg.version ?? null,
+        };
+    }).filter(h => h.name);
+}

package/dist/workspace/sessions.js

@@ -1,8 +1,5 @@
 import path from 'node:path';
-function splitKey(sessionKey) {
-    const i = sessionKey.indexOf(':');
-    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
-}
+import { makeSessionKey, splitSessionKey } from '../protocol/index.js';
 function ts(iso) {
     if (!iso)
         return 0;
@@ -14,7 +11,7 @@ function newer(a, b) {
 }
 function managedToInfo(agent, rec) {
     return {
-        sessionKey: `${agent}:${rec.sessionId}`,
+        sessionKey: makeSessionKey(agent, rec.sessionId),
         agent,
         sessionId: rec.sessionId,
         title: rec.title ?? null,
@@ -31,7 +28,7 @@ function managedToInfo(agent, rec) {
 }
 function nativeToInfo(agent, n) {
     return {
-        sessionKey: `${agent}:${n.sessionId}`,
+        sessionKey: makeSessionKey(agent, n.sessionId),
         agent,
         sessionId: n.sessionId,
         title: n.title,
@@ -72,7 +69,7 @@ export class SessionsManager {
                     if (!rec.workdir || path.resolve(rec.workdir) !== workdir)
                         continue;
                 }
-                byKey.set(`${agent}:${rec.sessionId}`, managedToInfo(agent, rec));
+                byKey.set(makeSessionKey(agent, rec.sessionId), managedToInfo(agent, rec));
             }
         }
         // Native sessions (the agents' own stores) — inherently per-workdir.
@@ -89,7 +86,7 @@ export class SessionsManager {
                     this.deps.log?.(`[sessions] ${agent}.listNativeSessions failed: ${e?.message || e}`);
                 }
                 for (const n of natives) {
-                    const key = `${agent}:${n.sessionId}`;
+                    const key = makeSessionKey(agent, n.sessionId);
                     const existing = byKey.get(key);
                     if (existing) {
                         // Same identity discovered both ways: managed record wins, but adopt the newer
@@ -118,7 +115,7 @@ export class SessionsManager {
         return typeof opts.limit === 'number' ? matched.slice(0, Math.max(0, opts.limit)) : matched;
     }
     async get(sessionKey, opts = {}) {
-        const { agent, sessionId } = splitKey(sessionKey);
+        const { agent, sessionId } = splitSessionKey(sessionKey);
         if (!agent)
             return null;
         const rec = await this.deps.store.get(agent, sessionId).catch(() => null);

package/dist/workspace/skills.d.ts

@@ -21,6 +21,17 @@ export interface SkillsManagerOptions {
     agentSkillDirs?: string[];
     log?: (msg: string) => void;
 }
+export interface SkillMeta {
+    label: string | null;
+    description: string | null;
+    mcpRequires?: string[];
+}
+/**
+ * Parse a SKILL.md's frontmatter (label/name + description + mcp_requires), falling back
+ * to the first `# heading` for the label. Exported so an app scanning additional skill
+ * stores (e.g. an agent's own ~/.claude/skills) reads them with the same rules.
+ */
+export declare function parseSkillMeta(content: string): SkillMeta;
 /** Make `linkPath` a symlink to `targetDir` (idempotent; replaces a stale link/dir). */
 export declare function ensureDirSymlink(linkPath: string, targetDir: string): void;
 export declare class SkillsManager {

package/dist/workspace/skills.js

@@ -1,13 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { searchNpmPackages } from './npm-search.js';
 const DEFAULT_AGENT_SKILL_DIRS = ['.claude/skills', '.agents/skills'];
-function parseSkillMeta(content) {
+/**
+ * Parse a SKILL.md's frontmatter (label/name + description + mcp_requires), falling back
+ * to the first `# heading` for the label. Exported so an app scanning additional skill
+ * stores (e.g. an agent's own ~/.claude/skills) reads them with the same rules.
+ */
+export function parseSkillMeta(content) {
     let label = null;
     let description = null;
     let mcpRequires;
     const fm = content.match(/^---\s*\n([\s\S]*?)\n---/);
     if (fm) {
-        const lm = fm[1].match(/^label:\s*(.+)/m);
+        // Both frontmatter dialects: pikiloom's `label:` and the agent-native `name:`.
+        const lm = fm[1].match(/^label:\s*(.+)/m) || fm[1].match(/^name:\s*(.+)/m);
         if (lm)
             label = lm[1].trim();
         const dm = fm[1].match(/^description:\s*(.+)/m);
@@ -145,25 +152,12 @@ export class SkillsManager {
     /** Search installable skills on the npm registry (best-effort; [] on failure). */
     async search(query, limit = 20) {
         const q = (query || '').trim();
-        const text = encodeURIComponent(`agent skill ${q}`.trim());
-        const url = `https://registry.npmjs.org/-/v1/search?text=${text}&size=${Math.max(1, Math.min(50, limit))}`;
         try {
-            const res = await fetch(url, { headers: { accept: 'application/json' } });
-            if (!res.ok)
-                return [];
-            const data = await res.json();
-            const objects = Array.isArray(data?.objects) ? data.objects : [];
-            return objects.map((o) => {
-                const pkg = o?.package ?? {};
-                return {
-                    name: String(pkg.name ?? ''),
-                    description: pkg.description ?? null,
-                    source: 'npm',
-                    author: pkg.publisher?.username ?? pkg.author?.name ?? null,
-                    homepage: pkg.links?.homepage ?? pkg.links?.npm ?? null,
-                    version: pkg.version ?? null,
-                };
-            }).filter(s => s.name);
+            const hits = await searchNpmPackages(`agent skill ${q}`.trim(), Math.max(1, Math.min(50, limit)), fetch);
+            return hits.map(h => ({
+                name: h.name, description: h.description, source: 'npm',
+                author: h.author, homepage: h.homepage, version: h.version,
+            }));
         }
         catch (e) {
             this.log?.(`[skills] search failed: ${e?.message || e}`);

package/llms.txt

@@ -59,6 +59,7 @@ interface UniversalSnapshot {
 }
 ```
 Wire delta helpers: `diffSnapshot(prev,next) => SnapshotPatch` (prefix-append text/reasoning; undefined→null clears) and `applySnapshotPatch(prev,patch)`. `emptySnapshot()`, `PROTOCOL_VERSION`.
+Session keys: a sessionKey is `${agent}:${sessionId}` — compose/parse ONLY via `makeSessionKey(agent, sessionId)` / `splitSessionKey(sessionKey)`.
 
 ## Control verbs (LoomIO, via loom.io)
 
@@ -86,7 +87,8 @@ governs a session index, a skills registry and per-agent symlinks, resolved in t
 - `loom.skills: SkillsManager` — the canonical skills registry. `canonicalDir(scope,wd?)` = `<root>/skills`;
   `ensureLinks(scope, wd?)` symlinks it into each agent's dir (default `.claude/skills`, `.agents/skills`,
   overridable via `agentSkillDirs`) so a skill registered once is visible to every agent. `list({workdir?,scope?})`,
-  `search(query) => npm results`.
+  `search(query) => npm results`. `parseSkillMeta(content)` (exported) reads a SKILL.md's frontmatter
+  (label/name + description + mcp_requires) — reuse it when scanning additional skill stores yourself.
 - `loom.mcp: McpRegistry` — `recommended(): McpCatalogEntry[]` (curated), `search(query)` (MCP registry → npm),
   `toServerSpec(entry, env?) => McpServerSpec`. Enabling/injecting a server stays on the Plugin.tools()/ToolProvider seam.
 
@@ -95,12 +97,18 @@ Drivers expose native discovery via the optional `AgentDriver.listNativeSessions
 
 ## Drivers (pass to createLoom({drivers}) or loom.registerDriver)
 
-- ClaudeDriver (id 'claude'): `claude` CLI stream-json, supports --effort; steer ✓, resume ✓, tui ✓
+- ClaudeDriver (id 'claude'): `claude` CLI stream-json, supports --effort; steer ✓, resume ✓, tui ✓.
+  Background-hold/stall/recovery heuristics tunable via PIKILOOM_CLAUDE_* env (see README).
 - CodexDriver (id 'codex'): `codex app-server` JSON-RPC; steer ✓, HITL via askUser, resume ✓, tui ✓
 - GeminiDriver (id 'gemini'): `gemini` stream-json; resume ✓, tui ✓
-- HermesDriver (id 'hermes'): ACP session/update; resume ✓
+- AcpDriver (id from config): generic ACP ndjson JSON-RPC — any ACP CLI via `new AcpDriver({ id, command, args })`; HITL via askUser, resume ✓
+- HermesDriver (id 'hermes'): preset `new AcpDriver({ id:'hermes', command:'hermes', args:['acp'] })`; HITL via askUser, resume ✓
 - EchoDriver (id 'echo'): hermetic in-process test driver; all caps ✓
 
+Multi-account: `accountTokenSupported(agent)` / `accountTokenEnvVar(agent)` / `accountTokenEnv(agent, token)` —
+which env var carries an agent's auth token (claude: CLAUDE_CODE_OAUTH_TOKEN), so an app injects a selected
+account's token per spawn (via ModelResolver env or a Plugin contributeSpawn). Storage/selection stay app-side.
+
 Write a driver: implement `AgentDriver { id; capabilities?; run(input, ctx); tui?(input) }`. In run(), call `ctx.emit(event)`:
 `DriverEvent = {type:'session',sessionId} | {type:'text',delta} | {type:'reasoning',delta} | {type:'tool',call:UniversalToolCall} | {type:'plan',plan} | {type:'subagent',subagent} | {type:'usage',usage} | {type:'artifact',artifact} | {type:'activity',line}`.
 `ctx = { signal: AbortSignal, emit, askUser(interaction)=>Promise<answers>, registerSteer(fn) }`. Return `DriverResult { ok, text, reasoning?, error?, stopReason?, sessionId?, usage? }`. Emit a `tool` event on BOTH start (status 'running') and completion (status 'done'/'failed'); the kernel projects `activity` from these.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.2.21",
+  "version": "0.3.1",
   "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",