pikiloom 0.4.36 → 0.4.38

package/dist/agent/drivers/codex.js

@@ -773,6 +773,23 @@ function createCodexStreamState(opts) {
         generatingImages: 0,
     };
 }
+// Codex on a ChatGPT-account login rejects non-OpenAI models with a raw upstream JSON blob
+// (e.g. {"detail":"The 'deepseek-v4-pro' model is not supported when using Codex with a
+// ChatGPT account."}). When a third-party model is correctly bound to a Provider profile the
+// injector routes around this; this only fires when no binding exists, so turn the opaque
+// upstream error into an actionable instruction instead of leaking JSON to the chat bubble.
+export function humanizeCodexError(raw) {
+    if (!raw)
+        return null;
+    const match = raw.match(/The '([^']+)' model is not supported when using Codex with a ChatGPT account/i);
+    if (match) {
+        const model = match[1];
+        return `Codex 正在使用 ChatGPT 账号登录，无法运行第三方模型「${model}」。`
+            + `请在「智能体配置」页接入该模型的供应商（填入 Base URL 与 API Key），添加对应模型档案并绑定到 Codex，`
+            + `或改用 Codex 原生模型（如 gpt-5.5）。`;
+    }
+    return raw;
+}
 function codexErrorResult(error, start, sessionId, model, thinkingEffort) {
     return {
         ok: false, message: error, thinking: null,
@@ -1119,7 +1136,7 @@ export async function doCodexStream(opts) {
         if (threadResp.error) {
             const errMsg = threadResp.error.message || 'thread/start failed';
             agentWarn(`[codex-rpc] thread error: ${errMsg}`);
-            return codexErrorResult(errMsg, start, opts.sessionId, opts.model, opts.thinkingEffort);
+            return codexErrorResult(humanizeCodexError(errMsg) ?? errMsg, start, opts.sessionId, opts.model, opts.thinkingEffort);
         }
         const threadResult = threadResp.result;
         s.sessionId = threadResult.thread?.id ?? s.sessionId;
@@ -1210,7 +1227,7 @@ export async function doCodexStream(opts) {
             unsubscribeRequests();
             const errMsg = turnResp.error.message || 'turn/start failed';
             agentWarn(`[codex-rpc] turn/start error: ${errMsg}`);
-            return codexErrorResult(errMsg, start, s.sessionId, s.model, s.thinkingEffort);
+            return codexErrorResult(humanizeCodexError(errMsg) ?? errMsg, start, s.sessionId, s.model, s.thinkingEffort);
         }
         s.turnId = turnResp.result?.turn?.id ?? null;
         publishTurnControl();
@@ -1226,7 +1243,7 @@ export async function doCodexStream(opts) {
             tryEmitCodexImageBlock(s, callId);
         }
         const ok = s.turnStatus === 'completed' && !timedOut && !interrupted;
-        const error = s.turnError
+        const error = humanizeCodexError(s.turnError)
             || (interrupted ? 'Interrupted by user.' : null)
             || (timedOut ? `Timed out after ${opts.timeout}s waiting for turn completion.` : null)
             || (!ok ? `Turn ${s.turnStatus || 'unknown'}.` : null);

package/dist/agent/index.js

@@ -7,7 +7,7 @@ export { attachAgentImage, attachInlineImage, materializeImage, rewriteAttachmen
 export { deliverArtifact, readDeliveredArtifacts, deliveredArtifactBlocks, tailDeliveredBlocks, latestDeliveredTaskId, mimeForArtifact, } from './artifacts.js';
 export { Q, agentLog, agentWarn, agentError, dedupeStrings, numberOrNull, normalizeStreamPreviewPlan, parseTodoWriteAsPlan, normalizeActivityLine, pushRecentActivity, detectClaudeApiError, isRetryableClaudeApiError, detectClaudeModelError, claudeModelErrorMessage, firstNonEmptyLine, shortValue, normalizeErrorMessage, joinErrorMessages, appendSystemPrompt, mimeForExt, computeContext, buildStreamPreviewMeta, summarizeClaudeToolUse, summarizeClaudeToolResult, previewToolCallInput, previewToolCallResult, roundPercent, toIsoFromEpochSeconds, normalizeUsageStatus, labelFromWindowMinutes, usageWindowFromRateLimit, parseJsonTail, modelFamily, normalizeClaudeModelId, emptyUsage, readTailLines, stripInjectedPrompts, sanitizeSessionUserPreviewText, SESSION_PREVIEW_IMAGE_PLACEHOLDER_RE, CLAUDE_AT_MENTION_IMAGE_RE, extractClaudeAtMentionImagePaths, stripClaudeAtMentionImages, isPendingSessionId, emitSessionIdUpdate, sessionListDisplayTitle, } from './utils.js';
 export { updateSessionMeta, promoteSessionId, recordFork, resolveCanonicalSessionId, getSessionPromotions, listPikiloomSessions, findPikiloomSession, getSessionStoredConfig, ensureManagedSession, findManagedThreadSession, stageSessionFiles, mergeManagedAndNativeSessions, managedRecordToSessionInfo, getSessions, getSessionTail, getSessionMessages, applyTurnWindow, applyTurnFilter, classifySession, deriveUserStatus, exportSession, importSession, deleteAgentSession, isProcessAlive, isRunningSessionStale, reconcileOrphanedRunningSessions, } from './session.js';
-export { detectAgentBin, listAgents, resolveDefaultAgent, run, doStream, listModels, resolveAgentModels, getUsage, getAgentBoundModelId, setAgentBoundModelId, } from './stream.js';
+export { detectAgentBin, listAgents, resolveDefaultAgent, run, doStream, recoverProfileIdForModel, listModels, resolveAgentModels, getUsage, getAgentBoundModelId, setAgentBoundModelId, } from './stream.js';
 export { registerDriver, getDriver, getDriverCapabilities, allDrivers, allDriverIds, hasDriver, shutdownAllDrivers, } from './driver.js';
 export { getProjectSkillPaths, initializeProjectSkills, listSkills, getGlobalSkillsRoot, collapseSkillPrompt, } from './skills.js';
 export { readGoal, writeGoal, clearGoal, setGoal, pauseGoal, resumeGoal, completeGoal, accountTurn, bumpContinuationCount, shouldContinueAfterTurn, renderContinuationPrompt, renderBudgetLimitPrompt, sessionGoalPath, DEFAULT_MAX_CONTINUATIONS, } from './goal.js';
@@ -19,6 +19,6 @@ export { getMcpToken, saveMcpToken, deleteMcpToken, hasValidMcpToken, startAutho
 export { installSkill, removeSkill, checkSkillUpdates, getGlobalSkillsDir, recordSkillInstall, getSkillLedgerEntry, forgetSkillInstall, normalizeSkillSourceKey, } from './skill-installer.js';
 export { getRecommendedClis, getRecommendedCli, detectCli, getCachedCliStatus, invalidateCliStatus, currentPlatform, getCliCatalog, refreshCliStatus, startCliAuthSession, getAuthSession, cancelAuthSession, applyCliToken, logoutCli, startCliInstallSession, } from './cli/index.js';
 export { doClaudeStream } from './drivers/claude.js';
-export { doCodexStream, buildCodexTurnInput, shutdownCodexServer, getCodexUsageLive } from './drivers/codex.js';
+export { doCodexStream, buildCodexTurnInput, shutdownCodexServer, getCodexUsageLive, humanizeCodexError } from './drivers/codex.js';
 export { doGeminiStream } from './drivers/gemini.js';
 export { doHermesStream } from './drivers/hermes.js';

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)
@@ -388,6 +389,35 @@ function finalizeStreamResult(result, workdir, prompt, session, workflowEnabled,
     saveSessionRecord(workdir, session.record);
     return { ...result, sessionId: session.sessionId, workspacePath: session.workspacePath };
 }
+function requestedModelForAgent(opts) {
+    switch (opts.agent) {
+        case 'claude': return (opts.claudeModel || opts.model || '').trim();
+        case 'codex': return (opts.codexModel || opts.model || '').trim();
+        case 'gemini': return (opts.geminiModel || opts.model || '').trim();
+        case 'hermes': return (opts.hermesModel || opts.model || '').trim();
+    }
+    return (opts.model || '').trim();
+}
+// When a session carries a third-party model id but its profile binding was lost
+// (stale/deleted profileId, or a model selected without a binding), resolveAgentInjection
+// returns null and the agent silently falls back to its native account — e.g. Codex on a
+// ChatGPT login rejects "deepseek-v4-pro". If exactly one configured profile (for a provider
+// kind this agent accepts) declares that model id, the intent is unambiguous: recover it.
+export function recoverProfileIdForModel(agent, modelId) {
+    const model = modelId.trim();
+    if (!model)
+        return null;
+    const accepted = new Set(getAcceptedProviderKinds(agent));
+    if (accepted.size === 0)
+        return null;
+    const matches = listProfiles().filter(profile => {
+        if (profile.modelId !== model)
+            return false;
+        const provider = getProvider(profile.providerId);
+        return !!provider && accepted.has(provider.kind);
+    });
+    return matches.length === 1 ? matches[0].id : null;
+}
 export async function doStream(opts) {
     let session;
     let prepared;
@@ -446,7 +476,18 @@ export async function doStream(opts) {
         agentWarn(`[mcp] bridge start failed: ${e.message} — proceeding without MCP`);
     }
     try {
-        const injection = await resolveAgentInjection(prepared.agent, prepared.profileId);
+        let injection = await resolveAgentInjection(prepared.agent, prepared.profileId);
+        if (!injection) {
+            const requestedModel = requestedModelForAgent(prepared);
+            const recoveredProfileId = recoverProfileIdForModel(prepared.agent, requestedModel);
+            if (recoveredProfileId) {
+                injection = await resolveAgentInjection(prepared.agent, recoveredProfileId);
+                if (injection) {
+                    prepared.profileId = recoveredProfileId;
+                    agentLog(`[byok] recovered lost provider binding: agent=${prepared.agent} model=${requestedModel} → profile=${recoveredProfileId}`);
+                }
+            }
+        }
         if (injection) {
             prepared.extraEnv = { ...(prepared.extraEnv || {}), ...injection.env };
             if (injection.modelOverride) {
@@ -518,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.36",
+  "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.