pikiloom 0.4.37 → 0.4.38

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

@@ -0,0 +1,194 @@
+import { spawn } from 'node:child_process';
+// Minimal ACP (Agent Client Protocol) ndjson JSON-RPC client — same wire as codex
+// app-server. Used by the Hermes driver to drive any-model agents over ACP.
+class AcpClient {
+    bin;
+    args;
+    env;
+    proc = null;
+    buf = '';
+    nextId = 1;
+    pending = new Map();
+    notify;
+    constructor(bin, args, env) {
+        this.bin = bin;
+        this.args = args;
+        this.env = env;
+    }
+    onNotification(cb) { this.notify = cb; }
+    start() {
+        try {
+            this.proc = spawn(this.bin, this.args, { stdio: ['pipe', 'pipe', 'pipe'], env: this.env ? { ...process.env, ...this.env } : process.env });
+        }
+        catch {
+            return false;
+        }
+        this.proc.stdout.on('data', (chunk) => this.onData(chunk));
+        this.proc.on('close', () => { for (const cb of this.pending.values())
+            cb({ error: { message: 'acp exited' } }); this.pending.clear(); });
+        this.proc.on('error', () => { });
+        return true;
+    }
+    onData(chunk) {
+        this.buf += chunk.toString('utf8');
+        const lines = this.buf.split('\n');
+        this.buf = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let m;
+            try {
+                m = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (m.method && m.id != null) {
+                this.respond(m.id, {});
+            } // agent->client request: ack
+            else if (m.id != null) {
+                const cb = this.pending.get(m.id);
+                if (cb) {
+                    this.pending.delete(m.id);
+                    cb(m);
+                }
+            }
+            else if (m.method)
+                this.notify?.(m.method, m.params ?? {});
+        }
+    }
+    request(method, params, timeoutMs = 60_000) {
+        return new Promise((resolve) => {
+            if (!this.proc || this.proc.killed) {
+                resolve({ error: { message: 'not connected' } });
+                return;
+            }
+            const id = this.nextId++;
+            const timer = setTimeout(() => { this.pending.delete(id); resolve({ error: { message: `ACP '${method}' timed out` } }); }, timeoutMs);
+            this.pending.set(id, (m) => { clearTimeout(timer); resolve(m); });
+            try {
+                this.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+            }
+            catch {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve({ error: { message: 'write failed' } });
+            }
+        });
+    }
+    respond(id, result) { try {
+        this.proc?.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+    }
+    catch { /* closed */ } }
+    kill() { try {
+        this.proc?.kill('SIGTERM');
+    }
+    catch { /* ignore */ } this.proc = null; }
+}
+export class HermesDriver {
+    bin;
+    id = 'hermes';
+    capabilities = { steer: false, interact: false, resume: true, tui: false };
+    constructor(bin = 'hermes') {
+        this.bin = bin;
+    }
+    async run(input, ctx) {
+        const client = new AcpClient(this.bin, ['acp'], input.env);
+        const s = { text: '', reasoning: '', sessionId: input.sessionId ?? null, contextWindow: null, contextUsed: null, error: null };
+        const tools = new Set();
+        if (!client.start())
+            return { ok: false, text: '', error: 'failed to start hermes acp', stopReason: 'error' };
+        const onAbort = () => { try {
+            client.request('session/cancel', { sessionId: s.sessionId });
+        }
+        catch { /* ignore */ } client.kill(); };
+        if (ctx.signal.aborted)
+            onAbort();
+        else
+            ctx.signal.addEventListener('abort', onAbort, { once: true });
+        client.onNotification((method, params) => {
+            if (method !== 'session/update')
+                return;
+            applyHermesUpdate(params?.update ?? params, s, tools, ctx.emit);
+        });
+        try {
+            const init = await client.request('initialize', { protocolVersion: 1, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } } });
+            if (init.error)
+                return { ok: false, text: '', error: init.error.message || 'initialize failed', stopReason: 'error' };
+            if (!s.sessionId) {
+                const ns = await client.request('session/new', { cwd: input.workdir, mcpServers: [] });
+                if (ns.error)
+                    return { ok: false, text: '', error: ns.error.message || 'session/new failed', stopReason: 'error' };
+                s.sessionId = ns.result?.sessionId || ns.result?.session_id || null;
+                if (s.sessionId)
+                    ctx.emit({ type: 'session', sessionId: s.sessionId });
+            }
+            else {
+                await client.request('session/load', { sessionId: s.sessionId, cwd: input.workdir, mcpServers: [] }, 30_000).catch(() => ({}));
+            }
+            if (!s.sessionId)
+                return { ok: false, text: '', error: 'hermes returned no session id', stopReason: 'error' };
+            if (input.model)
+                await client.request('session/set_model', { sessionId: s.sessionId, modelId: input.model }, 15_000).catch(() => ({}));
+            const promptResp = await client.request('session/prompt', {
+                sessionId: s.sessionId,
+                prompt: [{ type: 'text', text: input.prompt }],
+            }, 7_200_000);
+            const usage = { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: s.contextUsed, contextPercent: null };
+            if (ctx.signal.aborted)
+                return { ok: false, text: s.text, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: s.sessionId, usage };
+            if (promptResp.error)
+                return { ok: false, text: s.text, error: promptResp.error.message || 'session/prompt failed', stopReason: 'error', sessionId: s.sessionId, usage };
+            const stopReason = promptResp.result?.stopReason ?? 'end_turn';
+            return { ok: !s.error, text: s.text, reasoning: s.reasoning || undefined, error: s.error, stopReason, sessionId: s.sessionId, usage };
+        }
+        finally {
+            client.kill();
+        }
+    }
+}
+export function applyHermesUpdate(u, s, tools, emit) {
+    if (!u)
+        return;
+    switch (u.sessionUpdate) {
+        case 'agent_message_chunk': {
+            const t = u.content?.text;
+            if (typeof t === 'string' && t) {
+                s.text += t;
+                emit({ type: 'text', delta: t });
+            }
+            return;
+        }
+        case 'agent_thought_chunk': {
+            const t = u.content?.text;
+            if (typeof t === 'string' && t) {
+                s.reasoning += t;
+                emit({ type: 'reasoning', delta: t });
+            }
+            return;
+        }
+        case 'tool_call': {
+            const id = typeof u.toolCallId === 'string' ? u.toolCallId : '';
+            const title = (typeof u.title === 'string' && u.title.trim()) || 'tool';
+            if (id && !tools.has(id)) {
+                tools.add(id);
+                emit({ type: 'tool', call: { id, name: title, summary: title, status: 'running' } });
+            }
+            return;
+        }
+        case 'tool_call_update': {
+            const id = typeof u.toolCallId === 'string' ? u.toolCallId : '';
+            const title = (typeof u.title === 'string' && u.title.trim()) || 'tool';
+            if (id && (u.status === 'completed' || u.status === 'failed'))
+                emit({ type: 'tool', call: { id, name: title, summary: title, status: u.status === 'failed' ? 'failed' : 'done' } });
+            return;
+        }
+        case 'usage_update': {
+            if (typeof u.used === 'number') {
+                s.contextUsed = u.used;
+                emit({ type: 'usage', usage: { inputTokens: null, outputTokens: null, cachedInputTokens: null, contextUsedTokens: u.used, contextPercent: null } });
+            }
+            return;
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export { EchoDriver } from './echo.js';
+export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
+export { CodexDriver } from './codex.js';
+export { GeminiDriver, parseGeminiEvent } from './gemini.js';
+export { HermesDriver, applyHermesUpdate } from './hermes.js';

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

@@ -0,0 +1,5 @@
+export { EchoDriver } from './echo.js';
+export { ClaudeDriver, handleClaudeEvent, todoWriteToPlan } from './claude.js';
+export { CodexDriver } from './codex.js';
+export { GeminiDriver, parseGeminiEvent } from './gemini.js';
+export { HermesDriver, applyHermesUpdate } from './hermes.js';

package/packages/kernel/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { createLoom, type Loom, type LoomConfig, type TuiLaunchOptions } from './runtime/loom.js';
+export { Hub } from './runtime/hub.js';
+export { SessionRunner } from './runtime/session-runner.js';
+export { runTurn, type RunTurnOptions, type TurnOutcome } from './runtime/turn.js';
+export { PtyBridge, ptyAvailable, type PtyExit, type PtyOpenOpts } from './runtime/pty.js';
+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 { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
+export { EchoDriver } from './drivers/echo.js';
+export { ClaudeDriver } from './drivers/claude.js';
+export { CodexDriver } from './drivers/codex.js';
+export { GeminiDriver } from './drivers/gemini.js';
+export { HermesDriver } from './drivers/hermes.js';
+export { WebSurface, type WebSurfaceOptions } from './surfaces/web.js';
+export { CliSurface } from './surfaces/cli.js';
+export * from './protocol/index.js';

package/packages/kernel/dist/index.js

@@ -0,0 +1,29 @@
+// @pikiloom/kernel — heterogeneous coding agents -> an interaction-friendly,
+// accumulating session snapshot + control handle, over pluggable surfaces.
+//
+//   const loom = createLoom({
+//     drivers: [new ClaudeDriver()],                 // 下层 (unchanged)
+//     surfaces: [new WebSurface({ port: 8787 })],  // 上层 (IM / Web / tunnel)
+//   })
+//   await loom.start()
+//
+// pikiloom itself is just a consumer of this package.
+export { createLoom } from './runtime/loom.js';
+export { Hub } from './runtime/hub.js';
+export { SessionRunner } from './runtime/session-runner.js';
+export { runTurn } from './runtime/turn.js';
+export { PtyBridge, ptyAvailable } from './runtime/pty.js';
+export { attachTui } from './runtime/tui.js';
+// AgentInfo + Model/Effort/Tool/Skill descriptors are wire vocabulary — exported via protocol below.
+// Default ports
+export { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, AutoCancelInteractionHandler, DeferToTerminalInteractionHandler, NoopCatalog, defaultBaseDir, } from './ports/defaults.js';
+// Drivers & surfaces (also available via subpath exports)
+export { EchoDriver } from './drivers/echo.js';
+export { ClaudeDriver } from './drivers/claude.js';
+export { CodexDriver } from './drivers/codex.js';
+export { GeminiDriver } from './drivers/gemini.js';
+export { HermesDriver } from './drivers/hermes.js';
+export { WebSurface } from './surfaces/web.js';
+export { CliSurface } from './surfaces/cli.js';
+// Protocol (the wire vocabulary; shared with transports)
+export * from './protocol/index.js';

package/packages/kernel/dist/ports/defaults.d.ts

@@ -0,0 +1,59 @@
+import type { UniversalSnapshot, ModelDescriptor, EffortOption, ToolDescriptor, SkillDescriptor } from '../protocol/index.js';
+import type { SessionStore, CoreSessionRecord, ModelResolver, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog } from '../contracts/ports.js';
+export declare class FsSessionStore implements SessionStore {
+    private readonly baseDir;
+    constructor(baseDir: string);
+    private dir;
+    private recordPath;
+    private turnsPath;
+    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: {
+        ok: boolean;
+        error?: string | null;
+        text?: string;
+        sessionId?: string | null;
+    }): Promise<void>;
+    appendTurn(agent: string, sessionId: string, turn: UniversalSnapshot): Promise<void>;
+    history(agent: string, sessionId: string): Promise<UniversalSnapshot[]>;
+}
+export declare function defaultBaseDir(appNamespace: string): string;
+export declare class NullModelResolver implements ModelResolver {
+    resolve(): Promise<null>;
+}
+export declare class NoopToolProvider implements ToolProvider {
+    provideForSession(): Promise<{
+        servers: [];
+        env?: Record<string, string>;
+    }>;
+}
+export declare class PassthroughSystemPromptBuilder implements SystemPromptBuilder {
+    compose(opts: {
+        agent: string;
+        base?: string;
+        isFirstTurn: boolean;
+    }): string | undefined;
+}
+export declare class AutoCancelInteractionHandler implements InteractionHandler {
+    askUser(): Promise<Record<string, string[]>>;
+}
+export declare class DeferToTerminalInteractionHandler implements InteractionHandler {
+    askUser(): Promise<null>;
+}
+export declare class NoopCatalog implements Catalog {
+    listModels(): Promise<ModelDescriptor[]>;
+    listEffort(): Promise<EffortOption[]>;
+    listTools(): Promise<ToolDescriptor[]>;
+    listSkills(): Promise<SkillDescriptor[]>;
+}

package/packages/kernel/dist/ports/defaults.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+// ---- FsSessionStore: the default local persistence + workspace backend ----
+export class FsSessionStore {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    dir(agent, sessionId) {
+        return path.join(this.baseDir, agent, sessionId);
+    }
+    recordPath(agent, sessionId) {
+        return path.join(this.dir(agent, sessionId), 'record.json');
+    }
+    turnsPath(agent, sessionId) {
+        return path.join(this.dir(agent, sessionId), 'turns.jsonl');
+    }
+    async ensure(agent, opts) {
+        const sessionId = (opts.sessionId && opts.sessionId.trim()) || randomUUID();
+        const workspacePath = path.join(this.dir(agent, sessionId), 'workspace');
+        fs.mkdirSync(workspacePath, { recursive: true });
+        const existing = await this.get(agent, sessionId);
+        if (!existing) {
+            const now = new Date().toISOString();
+            await this.save({
+                agent, sessionId, workspacePath,
+                createdAt: now, updatedAt: now,
+                title: opts.title ?? null, runState: 'running', runDetail: null,
+            });
+        }
+        return { sessionId, workspacePath };
+    }
+    async get(agent, sessionId) {
+        try {
+            const raw = fs.readFileSync(this.recordPath(agent, sessionId), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(record) {
+        const p = this.recordPath(record.agent, record.sessionId);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify({ ...record, updatedAt: new Date().toISOString() }, null, 2));
+    }
+    async list(agent, opts) {
+        const agentDir = path.join(this.baseDir, agent);
+        let ids = [];
+        try {
+            ids = fs.readdirSync(agentDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
+        }
+        catch {
+            return [];
+        }
+        const records = [];
+        for (const id of ids) {
+            const rec = await this.get(agent, id);
+            if (rec)
+                records.push(rec);
+        }
+        records.sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+        return opts?.limit ? records.slice(0, opts.limit) : records;
+    }
+    async recordResult(agent, sessionId, result) {
+        const rec = await this.get(agent, sessionId);
+        if (!rec)
+            return;
+        rec.runState = result.ok ? 'completed' : 'incomplete';
+        rec.runDetail = result.error ?? null;
+        if (result.sessionId)
+            rec.nativeSessionId = result.sessionId;
+        if (result.text && !rec.title)
+            rec.title = result.text.slice(0, 80);
+        await this.save(rec);
+    }
+    async appendTurn(agent, sessionId, turn) {
+        const p = this.turnsPath(agent, sessionId);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, JSON.stringify(turn) + '\n');
+    }
+    async history(agent, sessionId) {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.turnsPath(agent, sessionId), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                out.push(JSON.parse(t));
+            }
+            catch { /* skip a corrupt/partial line */ }
+        }
+        return out;
+    }
+}
+export function defaultBaseDir(appNamespace) {
+    return path.join(os.homedir(), `.${appNamespace}`, 'sessions');
+}
+// ---- Trivial defaults: native login, no tools, passthrough prompt, auto-cancel HITL ----
+export class NullModelResolver {
+    async resolve() { return null; }
+}
+export class NoopToolProvider {
+    async provideForSession() { return { servers: [] }; }
+}
+export class PassthroughSystemPromptBuilder {
+    compose(opts) {
+        return opts.isFirstTurn ? opts.base : undefined;
+    }
+}
+// Headless HITL resolver: cancel every interaction immediately (empty answers).
+export class AutoCancelInteractionHandler {
+    async askUser() { return {}; }
+}
+// Default HITL resolver: defer to a terminal. Returns null so the interaction stays
+// pending in the snapshot until a terminal calls interact() — the right default for an
+// IM/Web-attached app. Headless callers opt into AutoCancelInteractionHandler instead.
+export class DeferToTerminalInteractionHandler {
+    async askUser() { return null; }
+}
+// Default catalog: empty. The kernel knows zero models/effort/tools/skills; an app
+// supplies them via its own Catalog impl. Agent capabilities come from the driver registry.
+export class NoopCatalog {
+    async listModels() { return []; }
+    async listEffort() { return []; }
+    async listTools() { return []; }
+    async listSkills() { return []; }
+}