@pikiloom/kernel 0.1.1 → 0.1.2

package/README.md

@@ -1,107 +1,284 @@
 # @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);
+```
+
+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
 ```
 
-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.
+`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).
 
-### 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).
+## 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:
+
+```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 }[] }[]; }
+```
+
+**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.
 
-## Contracts
+**Ports** (side) — all optional, each with a default, so `createLoom()` runs with zero config:
 
-| 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 |
+| 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) |
 
-Wire shape: `UniversalSnapshot` (phase/text/reasoning/plan/toolCalls/usage/interactions/artifacts)
-+ delta `diffSnapshot`/`applySnapshotPatch` (prefix-append text, `undefined→null` field-clears
-that survive JSON).
+**Plugins** contribute per-session tools (`tools()`) and/or augment snapshots (`decorateSnapshot()`).
 
-## 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`, `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/llms.txt

@@ -0,0 +1,98 @@
+# @pikiloom/kernel
+
+> Reusable core that turns heterogeneous coding-agent CLIs (Claude Code, Codex, Gemini, ACP/Hermes)
+> into ONE uniform, accumulating `UniversalSnapshot` + control verbs (prompt/stop/steer/interact),
+> exposed over pluggable surfaces (IM, Web, tunnel, raw PTY). You read one snapshot shape and never
+> parse a CLI's native output. ESM-only, Node >= 20. Runtime dep: `ws`; optional: `node-pty` (raw TUI).
+
+This file is an LLM-oriented summary. Full prose: README.md. Exact types: the bundled `dist/**/*.d.ts`.
+
+## Install & import
+
+```
+npm i @pikiloom/kernel
+```
+ESM only. Main export re-exports everything; subpaths: `@pikiloom/kernel/drivers`, `/surfaces`, `/protocol`.
+
+## Three usage tiers
+
+1) ONE turn, no persistence — `runTurn(driver, input, opts?) => Promise<{ result, snapshot }>`:
+```ts
+import { runTurn, ClaudeDriver } from '@pikiloom/kernel';
+const { result, snapshot } = await runTurn(
+  new ClaudeDriver(),
+  { prompt: 'hi', workdir: process.cwd(), effort: 'high' },            // AgentTurnInput
+  { onSnapshot: (s) => render(s), onSteer: (steer) => {}, signal },    // RunTurnOptions (signal = AbortSignal to stop)
+);
+// result: { ok, text, reasoning?, error?, stopReason?, sessionId?, usage? }
+```
+
+2) FULL multi-session backend — `createLoom(config) => Loom`:
+```ts
+import { createLoom, ClaudeDriver, WebSurface } from '@pikiloom/kernel';
+const loom = createLoom({ drivers: [new ClaudeDriver()], surfaces: [new WebSurface({ port: 8787 })], defaultAgent: 'claude' });
+await loom.start();
+const { sessionKey, taskId } = await loom.io.prompt({ prompt: 'hi', agent: 'claude' });
+const unsub = loom.io.subscribe((key, snapshot, patch, seq) => render(snapshot));
+```
+Every port has a default (zero config). Override any: sessionStore, modelResolver, toolProvider, systemPromptBuilder, catalog, interactionHandler, plugins, serialPerSession, appNamespace, workdir, defaultAgent, log.
+
+3) RAW TUI passthrough — `loom.runTui({ agent, workdir })` (full stdio passthrough) or `loom.openTui(...) => PtyBridge` (onData/write/resize/onExit). Needs optional `node-pty`; `ptyAvailable()` reports it.
+
+## UniversalSnapshot — the shape you render (accumulates across a turn)
+
+```ts
+interface UniversalSnapshot {
+  phase: 'idle'|'queued'|'streaming'|'done';
+  taskId?; sessionId?; agent?; model?; effort?; prompt?: string|null;
+  text?: string;        // accumulated assistant output (append)
+  reasoning?: string;   // accumulated thinking (append; empty if the model/auth withholds it — see gotchas)
+  activity?: string;    // human-readable execution trail, kernel-derived from toolCalls (one line per tool, status suffix)
+  plan?: { explanation: string|null; steps: { text: string; status: 'pending'|'inProgress'|'completed' }[] } | null;
+  toolCalls?: { id; name; summary; input?; result?; status: 'running'|'done'|'failed' }[];
+  subAgents?: { id; kind; description; model; tools[]; status }[];
+  usage?: { inputTokens; outputTokens; cachedInputTokens; contextUsedTokens?; contextPercent; providerName? } | null;
+  artifacts?: { url?; path?; fileName; mime?; kind: 'photo'|'document'; caption? }[];
+  interactions?: { promptId; kind: 'user-input'|'permission'|'confirmation'; title; questions: { id; text; type?: 'text'|'select'; choices? }[] }[];
+  queued?: { taskId; prompt }[];
+  error?: string|null; incomplete?: boolean; startedAt?; updatedAt: number;
+}
+```
+Wire delta helpers: `diffSnapshot(prev,next) => SnapshotPatch` (prefix-append text/reasoning; undefined→null clears) and `applySnapshotPatch(prev,patch)`. `emptySnapshot()`, `PROTOCOL_VERSION`.
+
+## Control verbs (LoomIO, via loom.io)
+
+- `prompt({ prompt, agent?, sessionKey?, workdir?, model?, effort?, attachments? }) => Promise<{ sessionKey, taskId }>`
+- `stop(sessionKey) => boolean`  (interrupts current turn; queued tasks stay and the next promotes)
+- `steer(taskId, prompt, attachments?) => Promise<boolean>`  (mid-turn; only drivers with capabilities.steer)
+- `interact(promptId, 'select'|'text'|'skip'|'cancel', value?) => boolean`  (answer a pending interaction)
+- `subscribe((sessionKey, snapshot, patch, seq) => void) => unsubscribe`
+- `getSnapshot(sessionKey)`, `getHistory(sessionKey)`, `listSessions()`, `listAgents()`, `listAgentInfo()`
+- discovery: `listModels(agent)`, `listEffort(agent, model?)`, `listTools(agent, workdir?)`, `listSkills(agent, workdir?)`
+Concurrent prompts to one session queue by default (serialPerSession=true).
+
+## Drivers (pass to createLoom({drivers}) or loom.registerDriver)
+
+- ClaudeDriver (id 'claude'): `claude` CLI stream-json, supports --effort; steer ✓, resume ✓, tui ✓
+- CodexDriver (id 'codex'): `codex app-server` JSON-RPC; steer ✓, HITL via askUser, resume ✓, tui ✓
+- GeminiDriver (id 'gemini'): `gemini` stream-json; resume ✓, tui ✓
+- HermesDriver (id 'hermes'): ACP session/update; resume ✓
+- EchoDriver (id 'echo'): hermetic in-process test driver; all caps ✓
+
+Write a driver: implement `AgentDriver { id; capabilities?; run(input, ctx); tui?(input) }`. In run(), call `ctx.emit(event)`:
+`DriverEvent = {type:'session',sessionId} | {type:'text',delta} | {type:'reasoning',delta} | {type:'tool',call:UniversalToolCall} | {type:'plan',plan} | {type:'subagent',subagent} | {type:'usage',usage} | {type:'artifact',artifact} | {type:'activity',line}`.
+`ctx = { signal: AbortSignal, emit, askUser(interaction)=>Promise<answers>, registerSteer(fn) }`. Return `DriverResult { ok, text, reasoning?, error?, stopReason?, sessionId?, usage? }`. Emit a `tool` event on BOTH start (status 'running') and completion (status 'done'/'failed'); the kernel projects `activity` from these.
+
+## Surfaces & Ports
+
+- Surface (上层, binds LoomIO): built-in `WebSurface` (ws host, wire protocol), `CliSurface`. Implement `Surface { id; capabilities?; start(io, host?); stop() }` for an IM channel.
+- Plugin: `{ id; tools?({agent,workdir}); decorateSnapshot?(snapshot) }`.
+- Ports (defaults in parens): SessionStore (FsSessionStore), ModelResolver (NullModelResolver = native login; override for BYOK), ToolProvider (NoopToolProvider), SystemPromptBuilder (PassthroughSystemPromptBuilder), Catalog (NoopCatalog), InteractionHandler (DeferToTerminalInteractionHandler; AutoCancelInteractionHandler for one-shots). `defaultBaseDir(ns)`.
+
+## Gotchas (read before using)
+
+- ESM only; Node >= 20. `node-pty` is OPTIONAL — required only for tui()/runTui()/openTui(); a missing one degrades gracefully (`ptyAvailable()===false`), it never breaks import.
+- `reasoning` is only populated when the agent streams plaintext thinking. Subscription/OAuth Claude withholds it (streams only an encrypted signature) → `reasoning` empty; BYOK Anthropic API and Codex DO stream it. Not a kernel bug.
+- `activity` is derived by the kernel from structured `toolCalls`+`subAgents` (you don't build it). Rich UIs can use `toolCalls` directly; simple/text surfaces can use the `activity` string.
+- The kernel bakes in ZERO model knowledge: model/effort/tool/skill lists come from the Catalog port (your app's SSOT). Per-agent capabilities come from the driver registry (`listAgentInfo()`).
+- `stop` interrupts only the running turn (queued tasks promote); it is not "cancel everything".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Heterogeneous coding agents (Claude / Codex / Gemini / ACP) -> an interaction-friendly, accumulating session snapshot + control handle, over pluggable surfaces (IM, Web, tunnel, TUI). The reusable core pikiloom itself is built on.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",