pikiloom 0.4.37 → 0.4.38

package/dist/agent/kernel-bridge.js

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { agentLog, agentWarn } from './utils.js';
+import { normalizeClaudeSessionEntrypoint } from './drivers/claude.js';
+import { humanizeCodexError } from './drivers/codex.js';
+// ── The cutover seam: route an agent turn through @pikiloom/kernel ──────────────
+//
+// DEFAULT: ON — claude/codex/gemini/hermes turns run on the kernel drivers (via runTurn).
+// Escape hatches to the legacy driver path:
+//   LOOM_KERNEL_PIPELINE=0             (env; force legacy at startup; survives dev.sh scrub)
+//   ~/.pikiloom/dev/kernel-legacy.on   (file; hot-toggle legacy without restart)
+//   LOOM_KERNEL_PIPELINE=1             (env; force kernel, overriding the file)
+// Tests always run legacy (the unit suite asserts legacy driver behavior). The bridge
+// re-applies app-level parity the pure kernel must not own (claude jsonl entrypoint, codex humanize).
+const KERNEL_AGENTS = new Set(['claude', 'codex', 'gemini', 'hermes']);
+export function shouldUseKernelPipeline(agent) {
+    if (!KERNEL_AGENTS.has(agent))
+        return false;
+    if (process.env.VITEST || process.env.NODE_ENV === 'test')
+        return false; // tests assert legacy
+    if (process.env.LOOM_KERNEL_PIPELINE === '0')
+        return false; // explicit legacy
+    if (process.env.LOOM_KERNEL_PIPELINE === '1')
+        return true; // explicit kernel
+    try {
+        if (fs.existsSync(path.join(os.homedir(), '.pikiloom', 'dev', 'kernel-legacy.on')))
+            return false;
+    }
+    catch { /* ignore */ }
+    return true; // default: kernel
+}
+// Build the kernel driver instance + the per-agent AgentTurnInput from pikiloom StreamOpts.
+function buildKernelDriver(kernel, opts) {
+    const common = {
+        prompt: opts.prompt,
+        workdir: opts.workdir,
+        sessionId: opts.sessionId ?? null,
+        attachments: opts.attachments,
+        effort: opts.thinkingEffort,
+        env: opts.extraEnv,
+        mcpConfigPath: opts.mcpConfigPath ?? null,
+    };
+    switch (opts.agent) {
+        case 'codex': {
+            // codexExtraArgs is a flattened ['-c','k=v','-c','k=v',...]; extract the k=v values
+            // so the kernel keeps BYOK provider routing.
+            const ce = opts.codexExtraArgs || [];
+            const configOverrides = [];
+            for (let i = 0; i < ce.length; i++)
+                if (ce[i] === '-c' && ce[i + 1])
+                    configOverrides.push(ce[++i]);
+            return { driver: new kernel.CodexDriver(), input: { ...common, model: opts.codexModel ?? opts.model ?? null, systemPrompt: opts.codexDeveloperInstructions, configOverrides, fullAccess: opts.codexFullAccess } };
+        }
+        case 'gemini':
+            return { driver: new kernel.GeminiDriver(), input: { ...common, model: opts.geminiModel ?? opts.model ?? null, systemPrompt: opts.geminiSystemInstruction, extraArgs: opts.geminiExtraArgs } };
+        case 'hermes':
+            return { driver: new kernel.HermesDriver(), input: { ...common, model: opts.hermesModel ?? opts.model ?? null } };
+        case 'claude':
+        default:
+            return {
+                driver: new kernel.ClaudeDriver(),
+                input: { ...common, model: opts.claudeModel ?? opts.model ?? null, systemPrompt: opts.claudeAppendSystemPrompt, permissionMode: opts.claudePermissionMode ?? null, extraArgs: opts.claudeExtraArgs, steerable: !!opts.onSteerReady },
+            };
+    }
+}
+let _kernel = null;
+export async function loadKernel() {
+    if (_kernel)
+        return _kernel;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, '../../packages/kernel/dist/index.js'), // src/agent (dev) & dist/agent (prod) -> <repo>/packages/kernel
+        path.resolve(process.cwd(), 'packages/kernel/dist/index.js'),
+    ];
+    // Prefer an installed package if present, else the in-repo built dist.
+    // (specifier kept in a variable so tsc treats it as a dynamic any, not a static resolve)
+    const pkgName = '@pikiloom/kernel';
+    try {
+        _kernel = await import(pkgName);
+        return _kernel;
+    }
+    catch { /* not installed */ }
+    for (const c of candidates) {
+        if (fs.existsSync(c)) {
+            _kernel = await import(pathToFileURL(c).href);
+            return _kernel;
+        }
+    }
+    throw new Error(`@pikiloom/kernel not found (build it: npm run build in packages/kernel). Looked in: ${candidates.join(', ')}`);
+}
+// A kernel 'artifact' (e.g. a generated image as a data URL) -> write to a temp file and
+// deliver through pikiloom's normal file-delivery seam (same path as im_send_file).
+async function deliverKernelArtifact(artifact, opts) {
+    try {
+        const send = opts.mcpSendFile;
+        if (typeof send !== 'function' || !artifact?.url)
+            return;
+        const m = String(artifact.url).match(/^data:([^;]+);base64,(.*)$/s);
+        if (!m)
+            return;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kernel-art-'));
+        const file = path.join(dir, artifact.fileName || 'artifact.bin');
+        fs.writeFileSync(file, Buffer.from(m[2], 'base64'));
+        await send(file, { kind: artifact.kind || 'document', caption: artifact.caption });
+    }
+    catch { /* best-effort delivery */ }
+}
+export async function kernelStream(opts) {
+    const start = Date.now();
+    const kernel = await loadKernel();
+    const { driver, input } = buildKernelDriver(kernel, opts);
+    agentLog(`[kernel-bridge] routing ${opts.agent} turn via @pikiloom/kernel ${driver?.constructor?.name || 'Driver'}`);
+    let delivered = 0; // artifacts already sent out-of-band
+    let seenSid = null;
+    // SessionRunner (via runTurn) owns the event accumulation; the bridge only translates
+    // the kernel's UniversalSnapshot onto pikiloom's preview (onText) and delivers any new
+    // artifacts through the normal file seam. This is the "product bridge" pattern: map your
+    // request -> AgentTurnInput, map snapshot -> your UI, map result -> your result shape.
+    const onSnapshot = (s) => {
+        const arts = s.artifacts || [];
+        for (; delivered < arts.length; delivered++)
+            void deliverKernelArtifact(arts[delivered], opts);
+        if (s.sessionId && s.sessionId !== seenSid) {
+            seenSid = s.sessionId;
+            try {
+                opts.onSessionId?.(s.sessionId);
+            }
+            catch { /* ignore */ }
+        }
+        const m = {
+            inputTokens: s.usage?.inputTokens ?? null,
+            outputTokens: s.usage?.outputTokens ?? null,
+            cachedInputTokens: s.usage?.cachedInputTokens ?? null,
+            contextUsedTokens: s.usage?.contextUsedTokens ?? null,
+            contextPercent: s.usage?.contextPercent ?? null,
+            toolCalls: s.toolCalls?.length ? s.toolCalls : undefined,
+            subAgents: s.subAgents?.length ? s.subAgents : undefined,
+            providerName: opts.byokProviderName ?? null,
+        };
+        try {
+            opts.onText(s.text || '', s.reasoning || '', s.activity || '', m, s.plan ?? null);
+        }
+        catch { /* isolate */ }
+    };
+    let result;
+    let snapshot = {};
+    try {
+        ({ result, snapshot } = await kernel.runTurn(driver, input, {
+            onSnapshot,
+            onSteer: (fn) => { try {
+                opts.onSteerReady?.(fn);
+            }
+            catch { /* ignore */ } },
+            signal: opts.abortSignal,
+        }));
+    }
+    catch (err) {
+        agentWarn(`[kernel-bridge] kernel run failed: ${err?.message || err}`);
+        result = { ok: false, text: '', error: err?.message || String(err), stopReason: 'error', sessionId: opts.sessionId ?? null };
+    }
+    const finalSessionId = result.sessionId || snapshot.sessionId || opts.sessionId || null;
+    if (finalSessionId && finalSessionId !== seenSid) {
+        try {
+            opts.onSessionId?.(finalSessionId);
+        }
+        catch { /* ignore */ }
+    }
+    // App-level parity the pure kernel must not own (mirrors legacy *.doStream):
+    //  - claude: rewrite the native jsonl entrypoint sdk-cli->cli (VSCode session visibility).
+    //  - codex: translate raw provider error JSON (ChatGPT-account / third-party) to prose.
+    if (opts.agent === 'claude') {
+        try {
+            normalizeClaudeSessionEntrypoint(opts.workdir, finalSessionId);
+        }
+        catch { /* best-effort */ }
+    }
+    const finalError = (opts.agent === 'codex' && result.error)
+        ? (humanizeCodexError(result.error) ?? result.error)
+        : (result.error ?? null);
+    const u = result.usage || snapshot.usage || {};
+    return {
+        ok: !!result.ok,
+        message: (result.text || snapshot.text || '').trim() || (finalError ?? '(no output)'),
+        thinking: (result.reasoning || snapshot.reasoning || '').trim() || null,
+        plan: snapshot.plan ?? null,
+        sessionId: finalSessionId,
+        workspacePath: null,
+        model: input.model ?? null,
+        thinkingEffort: opts.thinkingEffort,
+        elapsedS: (Date.now() - start) / 1000,
+        inputTokens: u.inputTokens ?? null,
+        outputTokens: u.outputTokens ?? null,
+        cachedInputTokens: u.cachedInputTokens ?? null,
+        cacheCreationInputTokens: null,
+        contextWindow: null,
+        contextUsedTokens: u.contextUsedTokens ?? null,
+        contextPercent: null,
+        codexCumulative: null,
+        error: finalError,
+        stopReason: result.stopReason ?? null,
+        incomplete: !result.ok,
+        activity: snapshot.activity || null,
+    };
+}

package/dist/agent/stream.js

@@ -12,6 +12,7 @@ import { Q, agentLog, agentWarn, agentError, joinErrorMessages, normalizeErrorMe
 import { saveSessionRecord, setSessionRunState, applySessionRunResult, ensureSessionWorkspace, importFilesIntoWorkspace, syncManagedSessionIdentity, summarizePromptTitle, recordFork, resolveCanonicalSessionId, } from './session.js';
 import { clearAwaitResume } from './await-resume.js';
 import { collapseSkillPrompt } from './skills.js';
+import { shouldUseKernelPipeline, kernelStream } from './kernel-bridge.js';
 function trimSessionText(value, max = 24_000) {
     const text = typeof value === 'string' ? value.trim() : '';
     if (!text)
@@ -558,7 +559,24 @@ export async function doStream(opts) {
             throw new Error(`Agent ${prepared.agent} does not support fork`);
         }
         await awaitAgentUpdateIdle(prepared.agent, AGENT_UPDATE_TIMEOUTS.spawnWait);
-        const result = await driver.doStream(prepared);
+        // Cutover seam: when enabled (default ON for claude/codex/gemini/hermes), route the
+        // agent turn through @pikiloom/kernel. kernelStream throws ONLY if the kernel package
+        // can't be loaded (missing dist) — every in-turn error is returned as a result. So a
+        // throw here means "kernel unavailable": fall back to the legacy driver rather than
+        // failing the turn. See agent/kernel-bridge.ts.
+        let result;
+        if (shouldUseKernelPipeline(prepared.agent)) {
+            try {
+                result = await kernelStream(prepared);
+            }
+            catch (kernelErr) {
+                agentWarn(`[kernel-bridge] kernel unavailable, falling back to legacy driver: ${kernelErr?.message || kernelErr}`);
+                result = await driver.doStream(prepared);
+            }
+        }
+        else {
+            result = await driver.doStream(prepared);
+        }
         const finalized = finalizeStreamResult(result, opts.workdir, opts.prompt, session, opts.claudeWorkflowEnabled, opts.profileId);
         finalized.byokProviderName = prepared.byokProviderName ?? null;
         finalized.byokProfileName = prepared.byokProfileName ?? null;

package/dist/cli/kernel-app.js

@@ -0,0 +1,115 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadKernel } from '../agent/kernel-bridge.js';
+import { loadUserConfig, applyUserConfig } from '../core/config/user-config.js';
+import { resolveAgentInjection } from '../model/injector.js';
+// ── The "new version": pikiloom's backend booted ON @pikiloom/kernel ────────────
+//
+// Gated by LOOM_KERNEL_APP=1 (non-PIKILOOM_ prefix so it survives dev.sh's env scrub).
+//   LOOM_KERNEL_APP=1 npm run dev   -> this kernel runtime on the dashboard port
+//   npm run dev                      -> the legacy app (old version), untouched
+//
+// One createLoom() drives every agent through the kernel's Driver registry and exposes it
+// over a WebSurface carrying both lanes on one ws host: Lane S (web/structured snapshot) and
+// Lane R (raw PTY / terminal). The whole C1-C5 SDK surface (history, catalog, HITL, per-session
+// queue, wire) is live here.
+const DEMO_MODELS = {
+    claude: [{ id: 'claude-opus-4-8', label: 'Opus 4.8', providerName: 'anthropic', contextWindow: 200000 }],
+    codex: [{ id: 'gpt-5.5-codex', label: 'GPT-5.5 Codex', providerName: 'openai', contextWindow: 400000 }],
+    gemini: [{ id: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro', providerName: 'google', contextWindow: 1000000 }],
+    echo: [{ id: 'echo-1', label: 'Echo (hermetic)', providerName: 'local', contextWindow: 8192 }],
+};
+export async function runKernelApp(argv) {
+    const i = argv.indexOf('--dashboard-port');
+    const port = (i >= 0 && parseInt(argv[i + 1], 10)) || 3940;
+    const k = await loadKernel();
+    const { createLoom, ClaudeDriver, CodexDriver, GeminiDriver, HermesDriver, EchoDriver, WebSurface } = k;
+    // Load providers/profiles so the active BYOK/豆包 bindings are visible to the resolver.
+    try {
+        applyUserConfig(loadUserConfig(), undefined, { overwrite: true, clearMissing: true });
+    }
+    catch (e) {
+        console.log(`[kernel-app] config load: ${e?.message || e}`);
+    }
+    // REAL ModelResolver: delegate to pikiloom's resolveAgentInjection (BYOK / 豆包 / native).
+    // null => native CLI login; else map the InjectedSpawnConfig onto the kernel's ModelInjection.
+    const modelResolver = {
+        async resolve(agent, opts) {
+            let inj = null;
+            try {
+                inj = await resolveAgentInjection(agent, opts.profileId ?? undefined);
+            }
+            catch (e) {
+                console.log(`[kernel-app] inject ${agent} failed: ${e?.message || e}`);
+                return null;
+            }
+            if (!inj)
+                return null; // no active profile → native login
+            const env = { ...(inj.env || {}) };
+            if (inj.homeOverride)
+                env.HOME = inj.homeOverride;
+            if (inj.configFiles && Object.keys(inj.configFiles).length)
+                console.log(`[kernel-app] note: ${agent} injection has configFiles (not yet threaded through kernel)`);
+            return {
+                model: inj.modelOverride ?? opts.model ?? null,
+                env,
+                extraArgs: inj.argvAppend?.length ? inj.argvAppend : undefined,
+                configOverrides: inj.codexConfigOverrides?.length ? inj.codexConfigOverrides : undefined,
+                providerName: inj.providerName ?? null,
+                contextWindow: inj.contextWindow ?? null,
+            };
+        },
+    };
+    // Discovery (C2). A full cutover wires pikiloom's runtime-config / catalog / mcp SSOT
+    // through this port; here a representative catalog proves discovery end to end.
+    const catalog = {
+        async listModels({ agent }) { return DEMO_MODELS[agent] || []; },
+        async listEffort() { return [{ id: 'low' }, { id: 'medium' }, { id: 'high' }]; },
+        async listTools() { return []; },
+        async listSkills() { return []; },
+    };
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    let html = '<!doctype html><meta charset=utf-8><title>pikiloom · kernel</title>'
+        + '<body style="font:14px system-ui;padding:2rem;max-width:42rem">'
+        + '<h1>pikiloom — kernel runtime (new version)</h1>'
+        + '<p>The WebSurface ws host is live on this port. Connect any pikichannel/ws client and speak the UniversalSnapshot wire protocol (hello → subscribe → prompt; getHistory / getCatalog).</p>';
+    for (const c of [
+        path.resolve(here, '../../packages/kernel/examples/console.html'),
+        path.resolve(process.cwd(), 'packages/kernel/examples/console.html'),
+    ]) {
+        try {
+            html = fs.readFileSync(c, 'utf8');
+            break;
+        }
+        catch { /* fallback inline */ }
+    }
+    const server = http.createServer((req, res) => {
+        if (req.method === 'GET' && (req.url === '/' || req.url?.startsWith('/?'))) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' });
+            res.end(html);
+            return;
+        }
+        res.writeHead(404);
+        res.end('not found');
+    });
+    // WebSurface serves BOTH lanes: Lane S (Web/structured snapshot) and Lane R (Surface/
+    // raw PTY, via the TuiHost the kernel hands it at start). One ws host, two lanes.
+    const web = new WebSurface({ server, name: 'pikiloom-kernel' });
+    const surfaces = [web];
+    const loom = createLoom({
+        appNamespace: 'pikiloom-kernel',
+        drivers: [new EchoDriver(), new ClaudeDriver(), new CodexDriver(), new GeminiDriver(), new HermesDriver()],
+        defaultAgent: 'claude',
+        surfaces,
+        catalog,
+        modelResolver,
+        log: (m) => console.log(`[kernel-app] ${m}`),
+    });
+    await loom.start();
+    await new Promise((resolve) => server.listen(port, () => resolve()));
+    const st = loom.status();
+    console.log(`[kernel-app] NEW VERSION up — http+ws http://localhost:${port}  agents=${st.agents.join(',')}  surfaces=${st.surfaces.join(',')}`);
+    // The http+ws server keeps the process alive.
+}

package/dist/cli/main.js

@@ -590,6 +590,13 @@ async function launchChannels(channels, dashboard) {
 export async function main() {
     if (await handleMcpServeMode())
         return;
+    // Cutover gate: LOOM_KERNEL_APP=1 boots the backend on @pikiloom/kernel (new version)
+    // instead of the legacy app. Non-PIKILOOM_ prefix so it survives dev.sh's env scrub.
+    if (process.env.LOOM_KERNEL_APP === '1') {
+        const { runKernelApp } = await import('./kernel-app.js');
+        await runKernelApp(process.argv.slice(2));
+        return;
+    }
     const args = parseArgs(process.argv.slice(2));
     let userConfig = loadUserConfig();
     if (args.version) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist/",
     "dashboard/dist/",
+    "packages/kernel/dist/",
     "LICENSE",
     "README.md"
   ],
@@ -33,7 +34,8 @@
     "build:dashboard": "vite build --config dashboard/vite.config.ts",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "copy:pikichannel-web": "node -e \"require('fs').cpSync('src/pikichannel/web','dist/pikichannel/web',{recursive:true})\"",
-    "build": "npm run clean && npm run build:dashboard && tsc && npm run copy:pikichannel-web",
+    "build:kernel": "tsc -p packages/kernel/tsconfig.json",
+    "build": "npm run clean && npm run build:dashboard && tsc && npm run build:kernel && npm run copy:pikichannel-web",
     "postbuild": "node -e \"require('fs').chmodSync('dist/cli/main.js',0o755)\"",
     "prepack": "npm run build",
     "test": "vitest run",

package/packages/kernel/README.md

@@ -0,0 +1,107 @@
+# @pikiloom/kernel
+
+Heterogeneous coding agents (Claude / Codex / Gemini / ACP) → an **interaction-friendly,
+accumulating session snapshot + control handle**, exposed over **pluggable surfaces**
+(IM, Web, tunnel). Environmental concerns are **injected ports** with working defaults.
+
+This is the reusable core **pikiloom itself is meant to be built on**. Drop it into any
+project and stand up a "pikiloom-like" backend in a few lines.
+
+## The model (one package, three rings)
+
+```
+上层 (you write):   IM bindings · Web UI/skin · Plugins        ── implement Surface / Plugin
+                          ▲ createLoom({ surfaces, plugins, ...ports })
+@pikiloom/kernel:   terminal/  Surface contract + LoomIO + built-in WebSurface
+  (one import,      runtime/   SessionRunner · Hub (multi-session) · snapshot accumulation · control verbs
+   internally       agent/     driver registry + Claude/Echo drivers + spawn/parse       ← Driver
+   modular)         protocol/  UniversalSnapshot + diff (the wire vocabulary)            ← Channel
+                    ports/     SessionStore · ModelResolver · ToolProvider · ... (+ defaults)
+                          ▲ spawns external CLIs (unchanged)
+下层 (unchanged):   the `claude` / `codex` / … binaries, native protocols
+```
+
+**IM and Web are not two systems** — they are both just `Surface`s over the same `LoomIO`.
+
+## Quickstart
+
+```ts
+import { createLoom, ClaudeDriver, WebSurface } from '@pikiloom/kernel';
+
+const loom = createLoom({
+  drivers: [new ClaudeDriver()],            // 下层 (unchanged)
+  surfaces: [new WebSurface({ port: 8787 })], // 上层 (IM / Web / tunnel)
+});
+await loom.start();
+```
+
+Add an IM terminal by implementing `Surface.start(io)`: route inbound messages to
+`io.prompt(...)` and render `io.subscribe(...)` snapshots back. Everything else (storage,
+credentials, tools, prompts) has a default and is overridable via ports.
+
+### TUI passthrough (`pikiloom code` → Claude/Codex TUI)
+
+Two orthogonal driver outputs off the same registry: `run()` yields a structured
+`UniversalSnapshot` (Web/IM); `tui()` yields a raw, full-screen interactive process that
+the kernel spawns in a **PTY** and passes through transparently (with optional tee/mirror).
+
+```ts
+import { createLoom, ClaudeDriver, CodexDriver } from '@pikiloom/kernel';
+const loom = createLoom({ drivers: [new ClaudeDriver(), new CodexDriver()], defaultAgent: 'claude' });
+await loom.runTui({ agent: 'claude', workdir: process.cwd() }); // you're now in the real Claude TUI, launched by the kernel
+```
+
+`runTui` does full stdin/stdout raw passthrough on the current terminal; `openTui` returns
+a `PtyBridge` (`onData`/`write`/`resize`/`onExit`) so you can drive or tee it yourself.
+Requires the optional `node-pty` dependency.
+
+## Contracts
+
+| Seam | Interface | Direction |
+|------|-----------|-----------|
+| Agent (下层) | `AgentDriver.run(input, ctx)` → emits `DriverEvent`s | down, bundled (+ `registerDriver` escape hatch) |
+| Surface (上层) | `Surface.start(io: LoomIO)` | up, app-provided (WebSurface built-in) |
+| Session API | `LoomIO` = prompt/stop/steer/interact + subscribe/getSnapshot/listSessions | the meeting point |
+| Plugin | `Plugin.tools()` / `decorateSnapshot()` | up, app-provided |
+| Ports | `SessionStore` · `ModelResolver` · `ToolProvider` · `SystemPromptBuilder` · `InteractionHandler` | side, defaults included |
+
+Wire shape: `UniversalSnapshot` (phase/text/reasoning/plan/toolCalls/usage/interactions/artifacts)
++ delta `diffSnapshot`/`applySnapshotPatch` (prefix-append text, `undefined→null` field-clears
+that survive JSON).
+
+## What's included
+
+- Drivers: `EchoDriver` (hermetic), `ClaudeDriver` (real `claude` CLI, stream-json + TUI), `CodexDriver` (app-server JSON-RPC + TUI), `GeminiDriver` (stream-json), `HermesDriver` (ACP).
+- Terminals: `WebSurface` (ws host speaking the wire protocol — any pikichannel client connects), `CliSurface`.
+- TUI: `PtyBridge` + `attachTui` + `Loom.runTui/openTui` (raw PTY passthrough with tee).
+- Ports: `FsSessionStore`, `NullModelResolver`, `NoopToolProvider`, `PassthroughSystemPromptBuilder`, `AutoCancelInteractionHandler`.
+
+## Publishing / CI
+
+`npm publish ./packages/kernel --access public` (scoped-public). Each pikiloom release bumps
++ builds the kernel (`scripts/release.sh`) and the Release workflow publishes it alongside
+pikiloom — needs the `@pikiloom` npm scope to exist and `NPM_TOKEN` to have publish access.
+
+> Known rough edge: node-pty's prebuilt `spawn-helper` can lose its executable bit on some
+> npm installs (`posix_spawnp failed`). Fix: `chmod +x node_modules/node-pty/prebuilds/*/spawn-helper`.
+
+## Verification
+
+```bash
+npm run typecheck                 # tsc, clean
+npm test                          # hermetic: snapshot diff, full lifecycle (stop/steer/interact), web ws flow
+KERNEL_E2E_REAL=1 npm test        # also drives the real `claude` CLI end-to-end
+node examples/smoke.mjs           # smoke against the compiled dist
+```
+
+Status: contracts + runtime + Echo/Claude drivers + Web terminal + default ports are
+implemented and **E2E-verified** (hermetic + real-claude + compiled-artifact). The kernel
+lives beside `src/` and does **not** touch the existing pikiloom app.
+
+## Roadmap (gated cutover)
+
+1. Port the remaining drivers (Codex/Gemini/Hermes-ACP) behind the same `AgentDriver` contract.
+2. Promote pikiloom's concrete IM channels to reference `Surface` adapters (`@pikiloom/kernel/surfaces/*`).
+3. Add the full pikichannel transport (WebRTC + rendezvous + TURN + `/api` tunnel) as a `WebSurface` option.
+4. Re-point the pikiloom app's `main.ts` at `createLoom({...})`; keep multi-session queue / promotion / goal
+   auto-continuation in the app (not the kernel). Switch over only after parity is proven on DEV.

package/packages/kernel/dist/contracts/driver.d.ts

@@ -0,0 +1,95 @@
+import type { UniversalToolCall, UniversalPlan, UniversalUsage, UniversalInteraction, UniversalArtifact, UniversalSubAgent } from '../protocol/index.js';
+export interface AgentTurnInput {
+    prompt: string;
+    attachments?: string[];
+    sessionId?: string | null;
+    workdir: string;
+    model?: string | null;
+    effort?: string | null;
+    systemPrompt?: string;
+    env?: Record<string, string>;
+    extraMcpServers?: McpServerSpec[];
+    mcpConfigPath?: string | null;
+    permissionMode?: string | null;
+    extraArgs?: string[];
+    configOverrides?: string[];
+    fullAccess?: boolean;
+    steerable?: boolean;
+}
+export interface McpServerSpec {
+    name: string;
+    type?: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+export type DriverEvent = {
+    type: 'session';
+    sessionId: string;
+} | {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'reasoning';
+    delta: string;
+} | {
+    type: 'tool';
+    call: UniversalToolCall;
+} | {
+    type: 'plan';
+    plan: UniversalPlan;
+} | {
+    type: 'subagent';
+    subagent: UniversalSubAgent;
+} | {
+    type: 'usage';
+    usage: Partial<UniversalUsage>;
+} | {
+    type: 'artifact';
+    artifact: UniversalArtifact;
+} | {
+    type: 'activity';
+    line: string;
+};
+export type SteerFn = (prompt: string, attachments?: string[]) => Promise<boolean>;
+export interface DriverContext {
+    signal: AbortSignal;
+    emit(event: DriverEvent): void;
+    askUser(interaction: UniversalInteraction): Promise<Record<string, string[]>>;
+    registerSteer(fn: SteerFn): void;
+}
+export interface DriverResult {
+    ok: boolean;
+    text: string;
+    reasoning?: string;
+    error?: string | null;
+    stopReason?: string | null;
+    sessionId?: string | null;
+    usage?: UniversalUsage | null;
+}
+export interface TuiInput {
+    workdir: string;
+    model?: string | null;
+    sessionId?: string | null;
+    env?: Record<string, string>;
+    extraArgs?: string[];
+}
+export interface TuiSpec {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+}
+export interface AgentDriver {
+    readonly id: string;
+    readonly capabilities?: {
+        steer?: boolean;
+        interact?: boolean;
+        resume?: boolean;
+        tui?: boolean;
+    };
+    run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
+    tui?(input: TuiInput): TuiSpec;
+}

package/packages/kernel/dist/contracts/driver.js

@@ -0,0 +1 @@
+export {};