@pikiloom/kernel 0.1.1 → 0.1.3

package/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/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/dist/index.d.ts

@@ -6,7 +6,7 @@ export { PtyBridge, ptyAvailable, type PtyExit, type PtyOpenOpts } from './runti
 export { attachTui, type AttachTuiOptions } from './runtime/tui.js';
 export type { AgentDriver, AgentTurnInput, DriverContext, DriverEvent, DriverResult, SteerFn, McpServerSpec, TuiInput, TuiSpec, } from './contracts/driver.js';
 export type { SessionStore, CoreSessionRecord, ModelResolver, ModelInjection, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog, } from './contracts/ports.js';
-export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, } from './contracts/surface.js';
+export type { LoomIO, PromptInput, Surface, SurfaceCapabilities, Plugin, SpawnContribution, } from './contracts/surface.js';
 export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
 export { EchoDriver } from './drivers/echo.js';
 export { ClaudeDriver } from './drivers/claude.js';

package/dist/runtime/hub.d.ts

@@ -49,6 +49,9 @@ export declare class Hub implements LoomIO {
     private queueView;
     private publishQueued;
     private collectTools;
+    private mergeSpawn;
+    private pluginSpawn;
+    private composeSystemPrompt;
     private onRunnerUpdate;
     stop(sessionKey: string): boolean;
     steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;

package/dist/runtime/hub.js

@@ -45,7 +45,11 @@ export class Hub {
             throw new Error(`Driver "${agent}" does not support TUI mode`);
         const workdir = opts.workdir || this.deps.workdir;
         const injection = await this.deps.modelResolver.resolve(agent, { model: opts.model, profileId: null }).catch(() => null);
-        return driver.tui({ workdir, model: injection?.model ?? opts.model ?? null, sessionId: opts.sessionId ?? null, env: injection?.env });
+        const model = injection?.model ?? opts.model ?? null;
+        // Same merge as run(), so the raw-PTY rail also gets plugin env/args (e.g. a hijack redirect).
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'tui', opts.sessionId ?? null, model);
+        const spawn = this.mergeSpawn([{ env: injection?.env, extraArgs: injection?.extraArgs }, ...pluginParts]);
+        return driver.tui({ workdir, model, sessionId: opts.sessionId ?? null, env: spawn.env, extraArgs: spawn.extraArgs });
     }
     async prompt(input) {
         const agent = (input.agent || this.deps.defaultAgent || '').trim();
@@ -98,20 +102,28 @@ export class Hub {
         // prior turn's native session id and any refreshed credentials/tools.
         const rec = await this.deps.sessionStore.get(agent, sessionId);
         const injection = await this.deps.modelResolver.resolve(agent, { model: input.model, profileId: null }).catch(() => null);
-        const tools = await this.collectTools(agent, workdir, workspacePath);
         const model = injection?.model ?? input.model ?? null;
         const effort = input.effort ?? null;
-        const systemPrompt = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn: !preExisted });
+        const tools = await this.collectTools(agent, workdir, workspacePath);
+        const pluginParts = await this.pluginSpawn(agent, workdir, 'run', sessionId, model);
+        // precedence: ModelResolver (model/creds) -> ToolProvider.env -> plugins (last, so a
+        // model-traffic hijack plugin can override the resolver's base URL).
+        const spawn = this.mergeSpawn([
+            { env: injection?.env, extraArgs: injection?.extraArgs, configOverrides: injection?.configOverrides },
+            { env: tools.env },
+            ...pluginParts,
+        ]);
+        const systemPrompt = await this.composeSystemPrompt(agent, workdir, !preExisted);
         const turnInput = {
             prompt: input.prompt,
             attachments: input.attachments,
             sessionId: rec?.nativeSessionId || (input.sessionKey ? sessionId : null),
             workdir,
             model, effort, systemPrompt,
-            env: injection?.env,
-            extraArgs: injection?.extraArgs, // BYOK flags from the ModelResolver
-            configOverrides: injection?.configOverrides, // codex BYOK -c routing
-            extraMcpServers: tools,
+            env: spawn.env,
+            extraArgs: spawn.extraArgs,
+            configOverrides: spawn.configOverrides,
+            extraMcpServers: tools.servers,
         };
         runner.run(driver, turnInput, input.prompt, model, effort)
             .then(async (result) => {
@@ -154,11 +166,16 @@ export class Hub {
         if (entry?.runner)
             this.onRunnerUpdate(sessionKey, entry.runner.snapshot, entry.runner.currentSeq);
     }
+    // MCP servers (ToolProvider + each plugin) PLUS the ToolProvider's session env (previously
+    // dropped) — surfaced so the spawn env merge can apply it.
     async collectTools(agent, workdir, workspacePath) {
-        const out = [];
+        const servers = [];
+        let env;
         try {
             const base = await this.deps.toolProvider.provideForSession({ agent, workdir, workspacePath });
-            out.push(...base.servers);
+            servers.push(...base.servers);
+            if (base.env && Object.keys(base.env).length)
+                env = base.env;
         }
         catch (e) {
             this.deps.log?.(`[hub] toolProvider failed: ${e?.message || e}`);
@@ -167,14 +184,71 @@ export class Hub {
             if (!plugin.tools)
                 continue;
             try {
-                out.push(...(await plugin.tools({ agent, workdir })));
+                servers.push(...(await plugin.tools({ agent, workdir })));
             }
             catch (e) {
                 this.deps.log?.(`[hub] plugin ${plugin.id} tools failed: ${e?.message || e}`);
             }
         }
+        return { servers, env };
+    }
+    // Merge ordered spawn contributions: env keys later-wins, extraArgs/configOverrides concatenate.
+    // Callers order parts [ModelResolver, ToolProvider.env, ...plugins] so a plugin (e.g. a model-
+    // traffic hijack) can override the resolver's base URL. Never touches global process.env.
+    mergeSpawn(parts) {
+        let env;
+        const extraArgs = [];
+        const configOverrides = [];
+        for (const p of parts) {
+            if (!p)
+                continue;
+            if (p.env && Object.keys(p.env).length)
+                env = { ...(env || {}), ...p.env };
+            if (p.extraArgs?.length)
+                extraArgs.push(...p.extraArgs);
+            if (p.configOverrides?.length)
+                configOverrides.push(...p.configOverrides);
+        }
+        return { env, extraArgs: extraArgs.length ? extraArgs : undefined, configOverrides: configOverrides.length ? configOverrides : undefined };
+    }
+    async pluginSpawn(agent, workdir, mode, sessionId, model) {
+        const out = [];
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.contributeSpawn)
+                continue;
+            try {
+                const c = await plugin.contributeSpawn({ agent, workdir, mode, sessionId, model });
+                if (c)
+                    out.push(c);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} contributeSpawn failed: ${e?.message || e}`);
+            }
+        }
         return out;
     }
+    // Final system/developer prompt = the singular SystemPromptBuilder base + each plugin's
+    // promptFragment (in registration order), joined. Delivered via AgentTurnInput.systemPrompt,
+    // which each driver applies its own way (claude --append-system-prompt / codex / gemini).
+    async composeSystemPrompt(agent, workdir, isFirstTurn) {
+        const parts = [];
+        const base = this.deps.systemPromptBuilder.compose({ agent, base: this.deps.systemPromptBase, isFirstTurn });
+        if (base && base.trim())
+            parts.push(base);
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.promptFragment)
+                continue;
+            try {
+                const f = await plugin.promptFragment({ agent, workdir, isFirstTurn });
+                if (f && f.trim())
+                    parts.push(f);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} promptFragment failed: ${e?.message || e}`);
+            }
+        }
+        return parts.length ? parts.join('\n\n') : undefined;
+    }
     onRunnerUpdate(sessionKey, snapshot, _seq) {
         const entry = this.sessions.get(sessionKey);
         if (!entry)

package/dist/runtime/loom.d.ts

@@ -28,6 +28,7 @@ export interface LoomConfig {
 export interface Loom {
     readonly io: LoomIO;
     registerDriver(driver: AgentDriver): void;
+    registerPlugin(plugin: Plugin): void;
     start(): Promise<void>;
     stop(): Promise<void>;
     status(): {

package/dist/runtime/loom.js

@@ -10,6 +10,8 @@ export function createLoom(config = {}) {
     for (const d of config.drivers || [])
         drivers.set(d.id, d);
     const defaultAgent = config.defaultAgent || config.drivers?.[0]?.id || 'echo';
+    // Held as a live reference so registerPlugin() mutates the same array the Hub iterates.
+    const plugins = [...(config.plugins || [])];
     const hub = new Hub({
         drivers,
         defaultAgent,
@@ -21,7 +23,7 @@ export function createLoom(config = {}) {
         catalog: config.catalog || new NoopCatalog(),
         interactionHandler: config.interactionHandler || new DeferToTerminalInteractionHandler(),
         serialPerSession: config.serialPerSession,
-        plugins: config.plugins || [],
+        plugins,
         systemPromptBase: config.systemPromptBase,
         log,
     });
@@ -36,6 +38,7 @@ export function createLoom(config = {}) {
     return {
         io: hub,
         registerDriver(driver) { drivers.set(driver.id, driver); },
+        registerPlugin(plugin) { plugins.push(plugin); },
         async start() {
             if (started)
                 return;

package/llms.txt

@@ -0,0 +1,100 @@
+# @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 = the registration unit for everything ONE capability adds to a session (register via `createLoom({plugins})` or `loom.registerPlugin(p)`):
+  `{ id; tools?({agent,workdir})=>McpServerSpec[]; promptFragment?({agent,workdir,isFirstTurn})=>string|null; contributeSpawn?({agent,workdir,mode:'run'|'tui',sessionId?,model?})=>SpawnContribution|null; decorateSnapshot?(snap) }`.
+  `SpawnContribution = { env?; extraArgs?; configOverrides? }`. Kernel merges per-spawn (NEVER touches global process.env), order `[ModelResolver → ToolProvider.env → plugins]` (plugin overrides resolver — e.g. a hijack redirecting `ANTHROPIC_BASE_URL` to a local proxy, applied on BOTH run() and tui()). `promptFragment`s append to the SystemPromptBuilder base. So tools + their usage-prompt + env/flags register in ONE place. The singular ModelResolver/SystemPromptBuilder remain the authoritative model-cred/base-prompt source; plugins are the composable layer on top.
+- 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.3",
   "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",