pikiloom 0.4.38 → 0.4.39

package/dist/agent/mcp/capabilities.js

@@ -0,0 +1,39 @@
+// Session tool capabilities: each co-locates a session MCP tool group (defined under
+// ./tools/) with the prompt fragment that teaches the agent to use it. This is the local,
+// decoupled analog of a @pikiloom/kernel Plugin (a capability = its tools + its usage
+// prompt, as one unit). pikiloom composes its own system prompt app-side and feeds the
+// kernel a finished string, so this module intentionally does NOT import the kernel — that
+// is what keeps pikiloom fully decoupled from the kernel's Hub/plugin runtime.
+const ARTIFACT_RETURN = [
+    '[Artifact Return]',
+    'To hand a file to the user — a screenshot, report, archive, generated asset, anything they asked you to "send" — call the `im_send_file` tool with the file path and a short caption. It is delivered through whatever terminal the user is on (an IM chat or the web dashboard) and stays retrievable even when they are connected remotely. Do NOT just print a local filesystem path: a remote user cannot open paths on this machine.',
+].join('\n');
+const ASK_USER = [
+    '[Asking the user]',
+    'The built-in `AskUserQuestion` tool is disabled here and will fail. If you would otherwise call it, call `mcp__pikiloom__im_ask_user` instead — same intent (a question plus optional choices), it blocks until the user replies via the IM/dashboard channel. Default behaviour is unchanged: infer obvious decisions yourself and only ask when you genuinely cannot proceed.',
+].join('\n');
+export const SESSION_TOOL_CAPABILITIES = [
+    {
+        id: 'artifact-delivery',
+        tools: ['im_send_file', 'im_list_files'],
+        promptFragment: () => ARTIFACT_RETURN,
+    },
+    {
+        id: 'ask-user',
+        tools: ['im_ask_user'],
+        // Only when the HITL path is wired and the agent is claude (codex/gemini handle asks natively).
+        promptFragment: ({ agent, onInteraction }) => (onInteraction && agent === 'claude') ? ASK_USER : null,
+    },
+];
+// Compose the session tool prompt = each capability's applicable fragment, in registration
+// order, joined by a blank line. Byte-identical to the prior inline assembly in bot.ts.
+export function composeSessionToolPrompt(ctx) {
+    const parts = [];
+    for (const cap of SESSION_TOOL_CAPABILITIES) {
+        const fragment = cap.promptFragment(ctx);
+        const trimmed = String(fragment || '').trim();
+        if (trimmed)
+            parts.push(trimmed);
+    }
+    return parts.join('\n\n');
+}

package/dist/bot/bot.js

@@ -8,6 +8,7 @@ import { getActiveProfileId, getActiveProfile, setActiveProfile } from '../model
 import { querySessions, querySessionTail, updateSession, } from './session-hub.js';
 import { getDriver, hasDriver, allDriverIds, getDriverCapabilities } from '../agent/driver.js';
 import { resolveGuiIntegrationConfig } from '../agent/mcp/bridge.js';
+import { composeSessionToolPrompt } from '../agent/mcp/capabilities.js';
 import { terminateProcessTree } from '../core/process-control.js';
 import { expandTilde } from '../core/platform.js';
 import { VERSION } from '../core/version.js';
@@ -48,18 +49,6 @@ function appendExtraPrompt(base, extra) {
         return lhs;
     return `${lhs}\n\n${rhs}`;
 }
-function buildMcpDeliveryPrompt() {
-    return [
-        '[Artifact Return]',
-        'To hand a file to the user — a screenshot, report, archive, generated asset, anything they asked you to "send" — call the `im_send_file` tool with the file path and a short caption. It is delivered through whatever terminal the user is on (an IM chat or the web dashboard) and stays retrievable even when they are connected remotely. Do NOT just print a local filesystem path: a remote user cannot open paths on this machine.',
-    ].join('\n');
-}
-function buildClaudeAskUserPrompt() {
-    return [
-        '[Asking the user]',
-        'The built-in `AskUserQuestion` tool is disabled here and will fail. If you would otherwise call it, call `mcp__pikiloom__im_ask_user` instead — same intent (a question plus optional choices), it blocks until the user replies via the IM/dashboard channel. Default behaviour is unchanged: infer obvious decisions yourself and only ask when you genuinely cannot proceed.',
-    ].join('\n');
-}
 function buildBrowserAutomationPrompt(browserEnabled) {
     if (!browserEnabled) {
         return [
@@ -2022,7 +2011,9 @@ export class Bot {
         const workflowEnabled = cs.agent === 'claude' && (extras?.workflowEnabled ?? this.claudeWorkflowEnabled);
         const deliverySessionKey = ('key' in cs && typeof cs.key === 'string') ? cs.key : null;
         const wrappedSendFile = this.buildArtifactSendFile(cs.agent, deliverySessionKey, cs, mcpSendFile);
-        const mcpSystemPrompt = appendExtraPrompt(appendExtraPrompt(appendExtraPrompt(buildMcpDeliveryPrompt(), onInteraction && cs.agent === 'claude' ? buildClaudeAskUserPrompt() : ''), buildBrowserAutomationPrompt(browserEnabled)), workflowEnabled ? buildWorkflowOptInPrompt() : '');
+        // Session tool capabilities (im_send_file / im_ask_user) bundle their usage prompt with
+        // the tool itself — see agent/mcp/capabilities.ts. Browser/workflow remain session policy.
+        const mcpSystemPrompt = appendExtraPrompt(appendExtraPrompt(composeSessionToolPrompt({ agent: cs.agent, onInteraction: !!onInteraction }), buildBrowserAutomationPrompt(browserEnabled)), workflowEnabled ? buildWorkflowOptInPrompt() : '');
         const effectiveSystemPrompt = isFirstTurnOfSession
             ? appendExtraPrompt(systemPrompt, mcpSystemPrompt)
             : (mcpSystemPrompt || undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.38",
+  "version": "0.4.39",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {

package/packages/kernel/README.md

@@ -1,107 +1,305 @@
 # @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.
+Turn heterogeneous coding agents (**Claude Code · Codex · Gemini · ACP/Hermes**) into one
+**uniform, accumulating session snapshot + a small set of control verbs**, exposed over
+**pluggable surfaces** (IM, Web, tunnel, raw terminal). Environmental concerns (storage,
+credentials, tools, prompts) 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.
+This is the reusable core that [pikiloom](https://github.com/xiaotonng/pikiloom) itself is
+built on. Drop it into any project and stand up a "pikiloom-like" backend in a few lines —
+**you never parse a CLI's output or learn each agent's wire format**; you read one
+`UniversalSnapshot` and call `prompt / stop / steer / interact`.
 
-## The model (one package, three rings)
+```bash
+npm i @pikiloom/kernel
+```
+
+- Runtime dep: `ws`. Optional: `node-pty` (only for raw-TUI passthrough). Node ≥ 20, ESM-only.
+- TypeScript types ship in the package (`dist/**/*.d.ts`). For an LLM-oriented summary, see [`llms.txt`](./llms.txt).
+
+---
+
+## Mental model
 
 ```
-上层 (you write):   IM bindings · Web UI/skin · Plugins        ── implement Surface / Plugin
+上层 (you write):   IM bindings · Web UI · 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
+@pikiloom/kernel:   contracts/  Driver · Surface · LoomIO · Ports
+  (one import,      runtime/    SessionRunner · Hub (multi-session) · snapshot accumulation · control verbs
+   modular inside)  drivers/    Claude / Codex / Gemini / Hermes / Echo  ← the agent axis (下层)
+                    surfaces/   WebSurface (ws host) · CliSurface
+                    protocol/   UniversalSnapshot + diff  ← the wire vocabulary
+                    ports/      SessionStore · ModelResolver · ToolProvider · ... (+ defaults)
+                          ▲ spawns the external `claude` / `codex` / `gemini` CLIs (unchanged)
+下层 (unchanged):   the agent binaries, native protocols
 ```
 
-**IM and Web are not two systems** — they are both just `Surface`s over the same `LoomIO`.
+**IM and Web are not two systems** — both are just `Surface`s over the same `LoomIO`.
+
+### Two rails, same driver registry
+
+| Rail | Driver method | Output | Use for |
+|------|---------------|--------|---------|
+| **Structured** | `driver.run(input, ctx)` | streamed `UniversalSnapshot` (text, reasoning, tool activity, plan, usage) | IM, Web dashboards, any UI that renders structured turns |
+| **Raw PTY** | `driver.tui(input)` | a real full-screen interactive process passed through a PTY | a local terminal app (`pikiloom code`-style); needs `node-pty` |
 
-## Quickstart
+---
+
+## Quick start
+
+### 1. One turn through one agent — `runTurn` (the bridge primitive)
+
+The smallest unit. No persistence, no multi-session — just run a turn and get a streamed
+snapshot + final result. This is exactly what an existing app maps onto its own UI.
 
 ```ts
-import { createLoom, ClaudeDriver, WebSurface } from '@pikiloom/kernel';
+import { runTurn, ClaudeDriver } from '@pikiloom/kernel';
+
+const { result, snapshot } = await runTurn(
+  new ClaudeDriver(),
+  { prompt: 'Summarize package.json in one line', workdir: process.cwd(), effort: 'high' },
+  {
+    onSnapshot: (s) => {
+      // fires on every event — render live:
+      //   s.text       accumulated assistant output
+      //   s.reasoning  accumulated thinking (when the model/auth exposes it)
+      //   s.activity   human-readable execution trail ("Read foo.ts", "Run shell: npm test")
+      //   s.toolCalls  structured tool calls [{ name, summary, status }]
+      //   s.plan, s.usage, s.artifacts, s.interactions
+      process.stdout.write(`\r${s.activity?.split('\n').at(-1) ?? ''}`);
+    },
+    onSteer: (steer) => { /* call steer('extra prompt') mid-turn */ },
+    signal: undefined,  // pass an AbortSignal to stop the turn
+  },
+);
+console.log(result.ok, result.text, result.sessionId);
+```
+
+### 2. A full multi-session backend — `createLoom`
+
+Adds persistence, a session hub, per-session queueing, discovery, and surfaces. Every port
+has a default, so this runs with zero wiring.
+
+```ts
+import { createLoom, ClaudeDriver, CodexDriver, WebSurface } from '@pikiloom/kernel';
 
 const loom = createLoom({
-  drivers: [new ClaudeDriver()],            // 下层 (unchanged)
-  surfaces: [new WebSurface({ port: 8787 })], // 上层 (IM / Web / tunnel)
+  drivers: [new ClaudeDriver(), new CodexDriver()],   // 下层 (unchanged binaries)
+  surfaces: [new WebSurface({ port: 8787 })],         // 上层 (Web/tunnel; add your IM Surface here)
+  defaultAgent: 'claude',
+  // optional ports — override any one to swap storage / credentials / tools / prompts:
+  // sessionStore, modelResolver, toolProvider, systemPromptBuilder, catalog, interactionHandler
 });
 await loom.start();
+
+// Drive it from anywhere via loom.io (LoomIO):
+const { sessionKey, taskId } = await loom.io.prompt({ prompt: 'hello', agent: 'claude' });
+const unsub = loom.io.subscribe((key, snapshot, patch, seq) => { /* render */ });
+loom.io.steer(taskId, 'actually, do X instead');
+loom.io.stop(sessionKey);
 ```
 
-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.
+To add an **IM channel**, implement `Surface.start(io)`: route inbound messages to
+`io.prompt(...)` and render `io.subscribe(...)` snapshots back out. Nothing else changes.
+
+### 3. Raw TUI passthrough — `runTui` / `openTui`
+
+```ts
+const loom = createLoom({ drivers: [new ClaudeDriver()], defaultAgent: 'claude' });
+await loom.runTui({ agent: 'claude', workdir: process.cwd() }); // you're now in the real Claude TUI
+```
 
-### TUI passthrough (`pikiloom code` → Claude/Codex TUI)
+`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 (`ptyAvailable()` reports availability).
 
-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).
+---
+
+## The data you read: `UniversalSnapshot`
+
+One driver-agnostic shape for every agent. A surface renders *this* and never touches a
+CLI's native format. It **accumulates** across a turn (text/reasoning append; structured
+fields replace).
 
 ```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
+interface UniversalSnapshot {
+  phase: 'idle' | 'queued' | 'streaming' | 'done';
+  taskId?: string | null;
+  sessionId?: string | null;
+  agent?: string | null;
+  model?: string | null;
+  effort?: string | null;
+  prompt?: string | null;
+
+  text?: string;        // accumulated assistant output
+  reasoning?: string;   // accumulated thinking (only when the model/auth streams it; see note)
+  activity?: string;    // human-readable execution trail, one line per tool/subagent (kernel-derived)
+  plan?: UniversalPlan | null;                 // { explanation, steps:[{ text, status }] }
+  toolCalls?: UniversalToolCall[];             // structured: { id, name, summary, input?, result?, status }
+  subAgents?: UniversalSubAgent[];             // spawned sub-agents and their tools
+  usage?: UniversalUsage | null;               // { inputTokens, outputTokens, cachedInputTokens, contextPercent, ... }
+  artifacts?: UniversalArtifact[];             // generated files/images { url|path, fileName, mime, kind }
+  interactions?: UniversalInteraction[];       // pending human-in-the-loop questions (answer via interact())
+  queued?: UniversalQueuedTask[];              // prompts waiting behind the running turn
+
+  error?: string | null;
+  incomplete?: boolean; // true if the turn was interrupted / errored
+  startedAt?: number;
+  updatedAt: number;
+}
 ```
 
-`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.
+Sub-shapes:
 
-## Contracts
+```ts
+interface UniversalToolCall { id: string; name: string; summary: string; input?: string | null; result?: string | null; status: 'running' | 'done' | 'failed'; }
+interface UniversalPlan { explanation: string | null; steps: { text: string; status: 'pending' | 'inProgress' | 'completed' }[]; }
+interface UniversalUsage { inputTokens: number | null; outputTokens: number | null; cachedInputTokens: number | null; contextUsedTokens?: number | null; contextPercent: number | null; providerName?: string | null; }
+interface UniversalArtifact { url?: string; path?: string; fileName: string; mime?: string; kind: 'photo' | 'document'; caption?: string; }
+interface UniversalInteraction { promptId: string; kind: 'user-input' | 'permission' | 'confirmation'; title: string; questions: { id: string; text: string; type?: 'text' | 'select'; choices?: { label: string; value?: string }[] }[]; }
+```
 
-| 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 |
+**Activity projection (kernel-owned).** Every driver emits *structured* tool calls; the
+kernel's `SessionRunner` derives `snapshot.activity` from `toolCalls` + `subAgents` centrally
+(`projectActivity`): one line per call with a status suffix — `summary` while running,
+`summary done` / `summary -> detail` on success, `summary failed: detail` on error. So every
+surface gets a readable execution trail for free, and rich UIs can still use `toolCalls`
+directly. You implement this **nowhere** — it's a property of the snapshot.
+
+**Reasoning note.** Plaintext thinking only appears when the agent actually streams it
+(e.g. BYOK Anthropic API keys, Codex `item/reasoning`). Subscription/OAuth Claude withholds
+plaintext extended-thinking (streams only an encrypted signature), so `reasoning` is empty
+there — a platform behavior, not a kernel limitation. The Claude driver also captures
+reasoning delivered as a complete block, not only as streamed deltas.
+
+### Streaming on the wire — `diffSnapshot` / `applySnapshotPatch`
+
+`diffSnapshot(prev, next)` produces a compact `SnapshotPatch` (prefix-append for `text` /
+`reasoning`; field replacement otherwise, with `undefined → null` so field-clears survive
+`JSON.stringify`). `applySnapshotPatch(prev, patch)` reassembles it on the client. `WebSurface`
+uses these; reuse them for your own transport.
+
+---
+
+## Control verbs (`LoomIO`)
+
+```ts
+io.prompt({ prompt, agent?, sessionKey?, workdir?, model?, effort?, attachments? })  // → { sessionKey, taskId }
+io.stop(sessionKey)                         // interrupt the running turn (queued tasks stay & promote)
+io.steer(taskId, prompt, attachments?)      // inject a message mid-turn (drivers with capabilities.steer)
+io.interact(promptId, action, value?)       // answer a pending interaction: 'select' | 'text' | 'skip' | 'cancel'
+io.subscribe((sessionKey, snapshot, patch, seq) => …)   // live snapshots
+io.getSnapshot(sessionKey) · io.getHistory(sessionKey) · io.listSessions()
+io.listAgentInfo() · io.listModels(agent) · io.listEffort(agent, model?) · io.listTools(agent, workdir?) · io.listSkills(agent, workdir?)
+```
+
+Concurrent prompts to one session **queue** by default (`serialPerSession`, no clobber); `stop`
+interrupts only the current turn and the next queued task promotes.
+
+---
+
+## Drivers (the agent axis)
+
+| Driver | id | transport | steer | interact | resume | tui |
+|--------|----|-----------|:-----:|:--------:|:------:|:---:|
+| `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` | — | — | ✓ | — |
+| `EchoDriver` | `echo` | none (hermetic, in-process) | ✓ | ✓ | ✓ | ✓ |
+
+Write your own by implementing `AgentDriver` and passing it to `createLoom({ drivers })` (or
+`loom.registerDriver(...)`). A driver normalizes its agent into `DriverEvent`s:
+
+```ts
+type DriverEvent =
+  | { type: 'session';  sessionId: string }
+  | { type: 'text';     delta: string }
+  | { type: 'reasoning'; delta: string }
+  | { type: 'tool';     call: UniversalToolCall }   // emit on tool start AND completion (status update)
+  | { type: 'plan';     plan: UniversalPlan }
+  | { type: 'subagent'; subagent: UniversalSubAgent }
+  | { type: 'usage';    usage: Partial<UniversalUsage> }
+  | { type: 'artifact'; artifact: UniversalArtifact }
+  | { type: 'activity'; line: string };             // explicit activity line (drivers that don't emit tool events)
+
+interface AgentDriver {
+  readonly id: string;
+  readonly capabilities?: { steer?: boolean; interact?: boolean; resume?: boolean; tui?: boolean };
+  run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>; // ctx: { signal, emit, askUser, registerSteer }
+  tui?(input: TuiInput): TuiSpec;
+}
+```
+
+---
+
+## Surfaces & Ports
+
+**Surfaces** (上层) bind to `LoomIO`. Built in: `WebSurface` (a WebSocket host speaking the
+wire protocol — any pikichannel-style client connects), `CliSurface`. Implement `Surface` to
+add an IM channel or your own UI.
+
+**Ports** (side) — all optional, each with a default, so `createLoom()` runs with zero config:
+
+| Port | Default | Swap to… |
+|------|---------|----------|
+| `SessionStore` | `FsSessionStore` (`~/.<ns>/sessions`) | your DB / transcript store |
+| `ModelResolver` | `NullModelResolver` (native login) | BYOK credential/provider injection |
+| `ToolProvider` | `NoopToolProvider` | per-session MCP servers |
+| `SystemPromptBuilder` | `PassthroughSystemPromptBuilder` | your system/developer prompt |
+| `Catalog` | `NoopCatalog` | model/effort/tool/skill discovery for composers |
+| `InteractionHandler` | `DeferToTerminalInteractionHandler` | programmatic HITL answers (`AutoCancelInteractionHandler` for one-shots) |
+
+**Plugins** are the registration unit for everything ONE capability adds to a session —
+register many, composed deterministically (and dynamically via `loom.registerPlugin(...)`):
+
+```ts
+interface Plugin {
+  id: string;
+  tools?(opts: { agent; workdir }): McpServerSpec[];                          // MCP servers
+  promptFragment?(opts: { agent; workdir; isFirstTurn }): string | null;       // how-to-use / behavior prompt
+  contributeSpawn?(opts: { agent; workdir; mode: 'run'|'tui'; sessionId?; model? }): SpawnContribution | null; // { env?, extraArgs?, configOverrides? }
+  decorateSnapshot?(snapshot): UniversalSnapshot;
+}
+```
 
-Wire shape: `UniversalSnapshot` (phase/text/reasoning/plan/toolCalls/usage/interactions/artifacts)
-+ delta `diffSnapshot`/`applySnapshotPatch` (prefix-append text, `undefined→null` field-clears
-that survive JSON).
+The kernel merges contributions per spawn — **never mutating global `process.env`** — in order
+`[ModelResolver → ToolProvider.env → plugins (registration order)]`, so a plugin can override
+the resolver (e.g. point an agent's `ANTHROPIC_BASE_URL` at a local proxy). `promptFragment`s are
+appended to the `SystemPromptBuilder` base and delivered via each agent's native mechanism. This
+is how a capability registers its tools **and** their usage prompt **and** any env/flags in one
+place — and how a model-traffic interceptor injects a redirect on both the `run()` and `tui()`
+rails without the kernel knowing anything about it. (The singular `ModelResolver` /
+`SystemPromptBuilder` ports remain the one authoritative model-credential / base-prompt source;
+plugins are the composable per-capability layer on top.)
 
-## 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`.
+## Exports
 
-## Publishing / CI
+Main entry `@pikiloom/kernel` re-exports everything. Subpaths: `@pikiloom/kernel/drivers`,
+`@pikiloom/kernel/surfaces`, `@pikiloom/kernel/protocol`.
 
-`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.
+- Runtime: `createLoom`, `Loom`, `Hub`, `SessionRunner`, `runTurn`, `PtyBridge`, `ptyAvailable`, `attachTui`
+- Drivers: `EchoDriver`, `ClaudeDriver`, `CodexDriver`, `GeminiDriver`, `HermesDriver`
+- Surfaces: `WebSurface`, `CliSurface`
+- Ports/defaults: `FsSessionStore`, `NullModelResolver`, `NoopToolProvider`, `PassthroughSystemPromptBuilder`, `AutoCancelInteractionHandler`, `DeferToTerminalInteractionHandler`, `NoopCatalog`, `defaultBaseDir`
+- 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`, …
 
-> 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
+## Verify
 
 ```bash
 npm run typecheck                 # tsc, clean
-npm test                          # hermetic: snapshot diff, full lifecycle (stop/steer/interact), web ws flow
+npm test                          # hermetic: snapshot diff, full lifecycle (stop/steer/interact), web ws flow, driver parsers
 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.
+See `examples/` for a runnable web console, a Feishu/Lark terminal, and a Node smoke test.
 
-## Roadmap (gated cutover)
+## License
 
-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.
+MIT

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

@@ -65,11 +65,28 @@ export interface Surface {
     start(io: LoomIO, host?: TuiHost): Promise<void>;
     stop(): Promise<void>;
 }
+export interface SpawnContribution {
+    env?: Record<string, string>;
+    extraArgs?: string[];
+    configOverrides?: string[];
+}
 export interface Plugin {
     readonly id: string;
     tools?(opts: {
         agent: string;
         workdir: string;
     }): McpServerSpec[] | Promise<McpServerSpec[]>;
+    promptFragment?(opts: {
+        agent: string;
+        workdir: string;
+        isFirstTurn: boolean;
+    }): string | null | undefined | Promise<string | null | undefined>;
+    contributeSpawn?(opts: {
+        agent: string;
+        workdir: string;
+        mode: 'run' | 'tui';
+        sessionId?: string | null;
+        model?: string | null;
+    }): SpawnContribution | null | undefined | Promise<SpawnContribution | null | undefined>;
     decorateSnapshot?(snapshot: UniversalSnapshot): UniversalSnapshot;
 }

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

@@ -1,5 +1,5 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec } from '../contracts/driver.js';
-import type { UniversalPlan } from '../protocol/index.js';
+import type { UniversalUsage, UniversalPlan } from '../protocol/index.js';
 export declare class ClaudeDriver implements AgentDriver {
     private readonly bin;
     readonly id = "claude";
@@ -14,6 +14,17 @@ 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;
+}
+export declare function claudeUsageOf(s: ClaudeUsageState): UniversalUsage;
+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 claudeUserMessage(text: string): string;
 export declare function emitClaudeImages(blocks: any[], s: any, emit: (e: DriverEvent) => void): void;

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

@@ -46,6 +46,8 @@ export class ClaudeDriver {
             sessionId: null, model: null,
             stopReason: null, error: null,
             input: null, output: null, cached: null,
+            cacheCreation: null,
+            contextWindow: null, turnOutputTokensBase: 0,
             subAgents: new Map(),
             tools: new Map(),
         };
@@ -141,9 +143,45 @@ export class ClaudeDriver {
         });
     }
     usage(s) {
-        return { inputTokens: s.input, outputTokens: s.output, cachedInputTokens: s.cached, contextPercent: null };
+        return claudeUsageOf(s);
     }
 }
+export function claudeUsageOf(s) {
+    const used = (s.input ?? 0) + (s.cached ?? 0) + (s.cacheCreation ?? 0) + (s.output ?? 0);
+    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) + (s.output ?? 0);
+    return {
+        inputTokens: s.input,
+        outputTokens: s.output,
+        cachedInputTokens: s.cached,
+        contextUsedTokens: used > 0 ? used : null,
+        contextPercent,
+        turnOutputTokens: turnOutput > 0 ? turnOutput : null,
+    };
+}
+// 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) {
+    const id = String(model ?? '').trim().toLowerCase();
+    if (!id)
+        return null;
+    if (id === 'haiku' || /claude-haiku-/.test(id))
+        return 200_000;
+    if (id === 'opus' || id === 'sonnet' || id === 'fable')
+        return 1_000_000;
+    if (/claude-(opus|sonnet)-/.test(id) || /claude-fable-/.test(id))
+        return 1_000_000;
+    return null;
+}
+// Usable window = advertised minus Claude's max-output (20k) + autocompact (13k) reserve.
+const CLAUDE_USABLE_WINDOW_RESERVE = 33_000;
+export function claudeEffectiveContextWindow(advertised) {
+    if (advertised == null)
+        return null;
+    return advertised <= CLAUDE_USABLE_WINDOW_RESERVE ? advertised : advertised - CLAUDE_USABLE_WINDOW_RESERVE;
+}
 // Parse one claude stream-json event into kernel DriverEvents (pure + exported for
 // hermetic testing). Faithful to pikiloom's claudeParse shapes.
 export function handleClaudeEvent(ev, s, emit) {
@@ -178,16 +216,21 @@ export function handleClaudeEvent(ev, s, emit) {
             emit({ type: 'session', sessionId: ev.session_id });
         }
         s.model = ev.model ?? s.model;
+        s.contextWindow = claudeEffectiveContextWindow(claudeContextWindowFromModel(s.model)) ?? s.contextWindow;
         return;
     }
     if (t === 'stream_event') {
         const inner = ev.event || {};
         if (inner.type === 'message_start') {
             const u = inner.message?.usage;
-            if (u) {
-                s.input = u.input_tokens ?? s.input;
-                s.cached = u.cache_read_input_tokens ?? s.cached;
-            }
+            // Claude emits one message per tool-use round within a single turn. Carry the prior
+            // message's output into the per-turn base, then reset to the new message's prompt size
+            // so contextUsedTokens tracks current occupancy while turnOutputTokens sums the turn.
+            s.turnOutputTokensBase = (s.turnOutputTokensBase ?? 0) + (s.output ?? 0);
+            s.input = u?.input_tokens ?? 0;
+            s.cached = u?.cache_read_input_tokens ?? 0;
+            s.cacheCreation = u?.cache_creation_input_tokens ?? 0;
+            s.output = 0;
         }
         else if (inner.type === 'content_block_delta') {
             const d = inner.delta || {};
@@ -211,7 +254,9 @@ export function handleClaudeEvent(ev, s, emit) {
                     s.input = u.input_tokens;
                 if (u.cache_read_input_tokens != null)
                     s.cached = u.cache_read_input_tokens;
-                emit({ type: 'usage', usage: { inputTokens: s.input, outputTokens: s.output, cachedInputTokens: s.cached, contextPercent: null } });
+                if (u.cache_creation_input_tokens != null)
+                    s.cacheCreation = u.cache_creation_input_tokens;
+                emit({ type: 'usage', usage: claudeUsageOf(s) });
             }
             if (inner.delta?.stop_reason)
                 s.stopReason = inner.delta.stop_reason;
@@ -312,6 +357,8 @@ export function handleClaudeEvent(ev, s, emit) {
             const cached = u.cache_read_input_tokens ?? u.cached_input_tokens;
             if (s.cached == null && cached != null)
                 s.cached = cached;
+            if (s.cacheCreation == null && u.cache_creation_input_tokens != null)
+                s.cacheCreation = u.cache_creation_input_tokens;
         }
         return;
     }

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

@@ -1,4 +1,5 @@
 import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { UniversalUsage } from '../protocol/index.js';
 export declare class CodexDriver implements AgentDriver {
     private readonly bin;
     readonly id = "codex";
@@ -12,3 +13,12 @@ export declare class CodexDriver implements AgentDriver {
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui(input: TuiInput): TuiSpec;
 }
+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;