@pikiloom/kernel 0.1.1

package/README.md

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

package/dist/contracts/driver.d.ts

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

package/dist/contracts/driver.js

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

package/dist/contracts/ports.d.ts

@@ -0,0 +1,84 @@
+import type { UniversalInteraction, UniversalSnapshot, ModelDescriptor, EffortOption, ToolDescriptor, SkillDescriptor } from '../protocol/index.js';
+import type { McpServerSpec, DriverResult } from './driver.js';
+export interface CoreSessionRecord {
+    agent: string;
+    sessionId: string;
+    nativeSessionId?: string | null;
+    workspacePath: string;
+    createdAt: string;
+    updatedAt: string;
+    title?: string | null;
+    model?: string | null;
+    effort?: string | null;
+    runState?: 'running' | 'completed' | 'incomplete';
+    runDetail?: string | null;
+}
+export interface SessionStore {
+    ensure(agent: string, opts: {
+        sessionId?: string | null;
+        title?: string | null;
+        workdir: string;
+    }): Promise<{
+        sessionId: string;
+        workspacePath: string;
+    }>;
+    get(agent: string, sessionId: string): Promise<CoreSessionRecord | null>;
+    save(record: CoreSessionRecord): Promise<void>;
+    list(agent: string, opts?: {
+        limit?: number;
+    }): Promise<CoreSessionRecord[]>;
+    recordResult(agent: string, sessionId: string, result: DriverResult): Promise<void>;
+    appendTurn?(agent: string, sessionId: string, turn: UniversalSnapshot): Promise<void>;
+    history?(agent: string, sessionId: string): Promise<UniversalSnapshot[]>;
+}
+export interface ModelInjection {
+    model?: string | null;
+    env?: Record<string, string>;
+    extraArgs?: string[];
+    configOverrides?: string[];
+    providerName?: string | null;
+    contextWindow?: number | null;
+}
+export interface ModelResolver {
+    resolve(agent: string, opts: {
+        model?: string | null;
+        profileId?: string | null;
+    }): Promise<ModelInjection | null>;
+}
+export interface ToolProvider {
+    provideForSession(opts: {
+        agent: string;
+        workdir: string;
+        workspacePath: string;
+    }): Promise<{
+        servers: McpServerSpec[];
+        env?: Record<string, string>;
+    }>;
+}
+export interface SystemPromptBuilder {
+    compose(opts: {
+        agent: string;
+        base?: string;
+        isFirstTurn: boolean;
+    }): string | undefined;
+}
+export interface InteractionHandler {
+    askUser(interaction: UniversalInteraction): Promise<Record<string, string[]> | null>;
+}
+export interface Catalog {
+    listModels(opts: {
+        agent: string;
+    }): Promise<ModelDescriptor[]>;
+    listEffort(opts: {
+        agent: string;
+        model?: string | null;
+    }): Promise<EffortOption[]>;
+    listTools(opts: {
+        agent: string;
+        workdir: string;
+    }): Promise<ToolDescriptor[]>;
+    listSkills(opts: {
+        agent: string;
+        workdir: string;
+    }): Promise<SkillDescriptor[]>;
+}

package/dist/contracts/ports.js

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

package/dist/contracts/surface.d.ts

@@ -0,0 +1,75 @@
+import type { UniversalSnapshot, SnapshotPatch, SessionMeta, AgentInfo, ModelDescriptor, EffortOption, ToolDescriptor, SkillDescriptor } from '../protocol/index.js';
+import type { McpServerSpec } from './driver.js';
+export interface PromptInput {
+    prompt: string;
+    agent?: string;
+    sessionKey?: string;
+    workdir?: string;
+    model?: string | null;
+    effort?: string | null;
+    attachments?: string[];
+}
+export interface LoomIO {
+    prompt(input: PromptInput): Promise<{
+        sessionKey: string;
+        taskId: string;
+    }>;
+    stop(sessionKey: string): boolean;
+    steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;
+    interact(promptId: string, action: 'select' | 'text' | 'skip' | 'cancel', value?: string): boolean;
+    subscribe(cb: (sessionKey: string, snapshot: UniversalSnapshot, patch: SnapshotPatch, seq: number) => void): () => void;
+    onSessionsChanged(cb: (sessions: SessionMeta[]) => void): () => void;
+    listSessions(): SessionMeta[];
+    getSnapshot(sessionKey: string): {
+        snapshot: UniversalSnapshot;
+        seq: number;
+    } | null;
+    getHistory(sessionKey: string): Promise<UniversalSnapshot[]>;
+    listAgents(): string[];
+    listAgentInfo(): AgentInfo[];
+    listModels(agent: string): Promise<ModelDescriptor[]>;
+    listEffort(agent: string, model?: string | null): Promise<EffortOption[]>;
+    listTools(agent: string, workdir?: string): Promise<ToolDescriptor[]>;
+    listSkills(agent: string, workdir?: string): Promise<SkillDescriptor[]>;
+}
+export interface SurfaceCapabilities {
+    editMessages?: boolean;
+    images?: boolean;
+    buttons?: boolean;
+    tunnel?: boolean;
+}
+export interface PtyHandle {
+    onData(cb: (data: string) => void): () => void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    onExit(cb: (e: {
+        exitCode: number;
+        signal?: number;
+    }) => void): () => void;
+    readonly pid: number;
+}
+export interface TuiHost {
+    openTui(opts: {
+        agent?: string;
+        workdir?: string;
+        model?: string | null;
+        sessionId?: string | null;
+        cols?: number;
+        rows?: number;
+    }): Promise<PtyHandle>;
+}
+export interface Surface {
+    readonly id: string;
+    readonly capabilities?: SurfaceCapabilities;
+    start(io: LoomIO, host?: TuiHost): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface Plugin {
+    readonly id: string;
+    tools?(opts: {
+        agent: string;
+        workdir: string;
+    }): McpServerSpec[] | Promise<McpServerSpec[]>;
+    decorateSnapshot?(snapshot: UniversalSnapshot): UniversalSnapshot;
+}

package/dist/contracts/surface.js

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

package/dist/drivers/claude.d.ts

@@ -0,0 +1,23 @@
+import type { AgentDriver, AgentTurnInput, DriverContext, DriverResult, DriverEvent, TuiInput, TuiSpec } from '../contracts/driver.js';
+import type { UniversalPlan } from '../protocol/index.js';
+export declare class ClaudeDriver implements AgentDriver {
+    private readonly bin;
+    readonly id = "claude";
+    readonly capabilities: {
+        steer: boolean;
+        interact: boolean;
+        resume: boolean;
+        tui: boolean;
+    };
+    constructor(bin?: string);
+    tui(input: TuiInput): TuiSpec;
+    run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
+    private usage;
+}
+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;
+export declare function todoWriteToPlan(input: any): UniversalPlan | null;
+export declare function shortToolValue(value: unknown, max?: number): string;
+export declare function summarizeToolUse(name: string, input: any): string;
+export declare function firstResultLine(content: any): string;