pikiloom 0.4.37 → 0.4.39

package/packages/kernel/dist/runtime/hub.js

@@ -0,0 +1,334 @@
+import { randomUUID } from 'node:crypto';
+import { diffSnapshot, emptySnapshot, } from '../protocol/index.js';
+import { SessionRunner } from './session-runner.js';
+function splitKey(sessionKey) {
+    const i = sessionKey.indexOf(':');
+    return i < 0 ? { agent: '', sessionId: sessionKey } : { agent: sessionKey.slice(0, i), sessionId: sessionKey.slice(i + 1) };
+}
+export class Hub {
+    deps;
+    sessions = new Map();
+    runnersByTask = new Map();
+    active = new Map(); // sessionKey -> currently running turn
+    waiting = new Map(); // sessionKey -> FIFO of queued turns
+    seqByKey = new Map(); // monotonic publish seq per session (survives turn changes)
+    updateSubs = new Set();
+    sessionsSubs = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    listAgents() { return [...this.deps.drivers.keys()]; }
+    // ---- discovery (capabilities from drivers; models/effort/tools/skills from Catalog) ----
+    listAgentInfo() {
+        return [...this.deps.drivers.values()].map(d => ({ id: d.id, capabilities: d.capabilities }));
+    }
+    listModels(agent) {
+        return this.deps.catalog.listModels({ agent }).catch((e) => { this.deps.log?.(`[hub] listModels failed: ${e?.message || e}`); return []; });
+    }
+    listEffort(agent, model) {
+        return this.deps.catalog.listEffort({ agent, model: model ?? null }).catch((e) => { this.deps.log?.(`[hub] listEffort failed: ${e?.message || e}`); return []; });
+    }
+    listTools(agent, workdir) {
+        return this.deps.catalog.listTools({ agent, workdir: workdir || this.deps.workdir }).catch((e) => { this.deps.log?.(`[hub] listTools failed: ${e?.message || e}`); return []; });
+    }
+    listSkills(agent, workdir) {
+        return this.deps.catalog.listSkills({ agent, workdir: workdir || this.deps.workdir }).catch((e) => { this.deps.log?.(`[hub] listSkills failed: ${e?.message || e}`); return []; });
+    }
+    // Resolve how to launch an agent's interactive TUI (with model injection applied),
+    // without spawning it — the caller (launcher / Loom.runTui) owns the PTY.
+    async resolveTui(opts) {
+        const agent = (opts.agent || this.deps.defaultAgent || '').trim();
+        const driver = this.deps.drivers.get(agent);
+        if (!driver)
+            throw new Error(`No driver registered for agent "${agent}"`);
+        if (!driver.tui)
+            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);
+        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();
+        const driver = this.deps.drivers.get(agent);
+        if (!driver)
+            throw new Error(`No driver registered for agent "${agent}"`);
+        const workdir = input.workdir || this.deps.workdir;
+        const resumeId = input.sessionKey ? splitKey(input.sessionKey).sessionId : null;
+        const preExisted = resumeId ? !!(await this.deps.sessionStore.get(agent, resumeId)) : false;
+        const { sessionId, workspacePath } = await this.deps.sessionStore.ensure(agent, {
+            sessionId: resumeId, workdir, title: input.prompt.slice(0, 80),
+        });
+        const sessionKey = `${agent}:${sessionId}`;
+        const taskId = randomUUID();
+        const runner = new SessionRunner(sessionKey, agent, taskId, (snap, seq) => this.onRunnerUpdate(sessionKey, snap, seq), this.deps.interactionHandler);
+        this.runnersByTask.set(taskId, runner);
+        const item = { runner, taskId, input, driver, agent, sessionId, sessionKey, workdir, workspacePath, preExisted };
+        // Per-session serial orchestration (default): one turn per session at a time. A prompt
+        // for a busy session queues (surfaced in the active snapshot's `queued`) and promotes
+        // when the running turn finishes — never clobbering the in-flight turn's snapshot.
+        if (this.deps.serialPerSession !== false && this.active.has(sessionKey)) {
+            this.enqueue(item);
+        }
+        else {
+            void this.runNow(item);
+        }
+        return { sessionKey, taskId };
+    }
+    enqueue(item) {
+        const q = this.waiting.get(item.sessionKey) ?? [];
+        q.push(item);
+        this.waiting.set(item.sessionKey, q);
+        this.publishQueued(item.sessionKey);
+    }
+    // Build and run one turn. The sync prefix (mark active, install the session entry) runs
+    // before the first await, so getSnapshot() is valid the instant prompt() returns.
+    async runNow(item) {
+        const { runner, taskId, input, driver, agent, sessionId, sessionKey, workdir, workspacePath, preExisted } = item;
+        this.active.set(sessionKey, runner);
+        const prev = this.sessions.get(sessionKey);
+        const entry = {
+            meta: { sessionKey, agent, title: input.prompt.slice(0, 80), phase: 'streaming', updatedAt: Date.now() },
+            // Inherit the prior turn's published state so this turn's FIRST diff correctly resets
+            // text/tools/usage/queued on the client — no cross-turn bleed on the same session.
+            snapshot: runner.snapshot, lastPublished: prev?.lastPublished ?? emptySnapshot(), seq: prev?.seq ?? 0, runner,
+        };
+        this.sessions.set(sessionKey, entry);
+        this.emitSessionsChanged();
+        // Resolve injection / tools / resume-target at run time so a promoted turn sees the
+        // 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 model = injection?.model ?? input.model ?? null;
+        const effort = input.effort ?? null;
+        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: spawn.env,
+            extraArgs: spawn.extraArgs,
+            configOverrides: spawn.configOverrides,
+            extraMcpServers: tools.servers,
+        };
+        runner.run(driver, turnInput, input.prompt, model, effort)
+            .then(async (result) => {
+            await this.deps.sessionStore.recordResult(agent, sessionId, result);
+            // Persist the completed turn's final snapshot as a transcript entry. The runner's
+            // snapshot is stable once done (a follow-up prompt spawns a fresh runner+snapshot).
+            try {
+                await this.deps.sessionStore.appendTurn?.(agent, sessionId, runner.snapshot);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] appendTurn failed ${sessionKey}: ${e?.message || e}`);
+            }
+        })
+            .catch((err) => this.deps.log?.(`[hub] run error ${sessionKey}: ${err?.message || err}`))
+            .finally(() => {
+            this.runnersByTask.delete(taskId);
+            if (this.active.get(sessionKey) === runner)
+                this.active.delete(sessionKey);
+            this.promoteNext(sessionKey); // serial: start the next queued turn (queue survives stop)
+            this.emitSessionsChanged();
+        });
+    }
+    promoteNext(sessionKey) {
+        const q = this.waiting.get(sessionKey);
+        if (!q || q.length === 0) {
+            this.waiting.delete(sessionKey);
+            return;
+        }
+        const next = q.shift();
+        if (q.length === 0)
+            this.waiting.delete(sessionKey);
+        void this.runNow(next);
+    }
+    queueView(sessionKey) {
+        return (this.waiting.get(sessionKey) || []).map(it => ({ taskId: it.taskId, prompt: it.input.prompt }));
+    }
+    // Re-publish the active turn's snapshot so a queue change (enqueue/drain) reaches subscribers.
+    publishQueued(sessionKey) {
+        const entry = this.sessions.get(sessionKey);
+        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 servers = [];
+        let env;
+        try {
+            const base = await this.deps.toolProvider.provideForSession({ agent, workdir, workspacePath });
+            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}`);
+        }
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.tools)
+                continue;
+            try {
+                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)
+            return;
+        let decorated = snapshot;
+        for (const plugin of this.deps.plugins) {
+            if (plugin.decorateSnapshot)
+                decorated = plugin.decorateSnapshot(decorated);
+        }
+        const queued = this.queueView(sessionKey);
+        decorated = { ...decorated, queued: queued.length ? queued : undefined };
+        entry.snapshot = decorated;
+        entry.seq = (this.seqByKey.get(sessionKey) ?? entry.seq ?? 0) + 1; // monotonic per session across turns
+        this.seqByKey.set(sessionKey, entry.seq);
+        entry.meta = { ...entry.meta, phase: decorated.phase, updatedAt: decorated.updatedAt, title: entry.meta.title || decorated.prompt?.slice(0, 80) || null };
+        const patch = diffSnapshot(entry.lastPublished, decorated);
+        entry.lastPublished = JSON.parse(JSON.stringify(decorated));
+        for (const cb of this.updateSubs) {
+            try {
+                cb(sessionKey, decorated, patch, entry.seq);
+            }
+            catch { /* isolate subscriber */ }
+        }
+        if (decorated.phase === 'done')
+            this.emitSessionsChanged();
+    }
+    // ---- control verbs ----
+    stop(sessionKey) {
+        const r = this.sessions.get(sessionKey)?.runner;
+        if (!r)
+            return false;
+        r.stop();
+        return true;
+    }
+    async steer(taskId, prompt, attachments) {
+        const r = this.runnersByTask.get(taskId);
+        return r ? r.steer(prompt, attachments) : false;
+    }
+    interact(promptId, action, value) {
+        for (const r of this.runnersByTask.values()) {
+            if (r.interact(promptId, action, value))
+                return true;
+        }
+        return false;
+    }
+    // ---- subscriptions & queries ----
+    subscribe(cb) {
+        this.updateSubs.add(cb);
+        return () => this.updateSubs.delete(cb);
+    }
+    onSessionsChanged(cb) {
+        this.sessionsSubs.add(cb);
+        return () => this.sessionsSubs.delete(cb);
+    }
+    emitSessionsChanged() {
+        const list = this.listSessions();
+        for (const cb of this.sessionsSubs) {
+            try {
+                cb(list);
+            }
+            catch { /* isolate */ }
+        }
+    }
+    listSessions() {
+        return [...this.sessions.values()].map(e => e.meta).sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    }
+    getSnapshot(sessionKey) {
+        const e = this.sessions.get(sessionKey);
+        return e ? { snapshot: e.snapshot, seq: e.seq } : null;
+    }
+    async getHistory(sessionKey) {
+        const { agent, sessionId } = splitKey(sessionKey);
+        if (!agent || !this.deps.sessionStore.history)
+            return [];
+        try {
+            return await this.deps.sessionStore.history(agent, sessionId);
+        }
+        catch (e) {
+            this.deps.log?.(`[hub] history failed ${sessionKey}: ${e?.message || e}`);
+            return [];
+        }
+    }
+}

package/packages/kernel/dist/runtime/loom.d.ts

@@ -0,0 +1,45 @@
+import type { AgentDriver, TuiSpec } from '../contracts/driver.js';
+import type { SessionStore, ModelResolver, ToolProvider, SystemPromptBuilder, Catalog, InteractionHandler } from '../contracts/ports.js';
+import type { LoomIO, Surface, Plugin } from '../contracts/surface.js';
+import { PtyBridge, type PtyOpenOpts, type PtyExit } from './pty.js';
+export interface TuiLaunchOptions {
+    agent?: string;
+    workdir?: string;
+    model?: string | null;
+    sessionId?: string | null;
+}
+export interface LoomConfig {
+    appNamespace?: string;
+    workdir?: string;
+    defaultAgent?: string;
+    drivers?: AgentDriver[];
+    surfaces?: Surface[];
+    plugins?: Plugin[];
+    sessionStore?: SessionStore;
+    modelResolver?: ModelResolver;
+    toolProvider?: ToolProvider;
+    systemPromptBuilder?: SystemPromptBuilder;
+    catalog?: Catalog;
+    interactionHandler?: InteractionHandler;
+    serialPerSession?: boolean;
+    systemPromptBase?: string;
+    log?: (msg: string) => void;
+}
+export interface Loom {
+    readonly io: LoomIO;
+    registerDriver(driver: AgentDriver): void;
+    registerPlugin(plugin: Plugin): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): {
+        agents: string[];
+        surfaces: string[];
+        started: boolean;
+    };
+    resolveTui(opts: TuiLaunchOptions): Promise<TuiSpec>;
+    openTui(opts: TuiLaunchOptions & PtyOpenOpts): Promise<PtyBridge>;
+    runTui(opts: TuiLaunchOptions & {
+        observers?: Array<(c: string) => void>;
+    }): Promise<PtyExit>;
+}
+export declare function createLoom(config?: LoomConfig): Loom;

package/packages/kernel/dist/runtime/loom.js

@@ -0,0 +1,72 @@
+import { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, NoopCatalog, DeferToTerminalInteractionHandler, defaultBaseDir, } from '../ports/defaults.js';
+import { Hub } from './hub.js';
+import { PtyBridge } from './pty.js';
+import { attachTui } from './tui.js';
+export function createLoom(config = {}) {
+    const appNamespace = config.appNamespace || 'loom';
+    const workdir = config.workdir || process.cwd();
+    const log = config.log || (() => { });
+    const drivers = new Map();
+    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,
+        workdir,
+        sessionStore: config.sessionStore || new FsSessionStore(defaultBaseDir(appNamespace)),
+        modelResolver: config.modelResolver || new NullModelResolver(),
+        toolProvider: config.toolProvider || new NoopToolProvider(),
+        systemPromptBuilder: config.systemPromptBuilder || new PassthroughSystemPromptBuilder(),
+        catalog: config.catalog || new NoopCatalog(),
+        interactionHandler: config.interactionHandler || new DeferToTerminalInteractionHandler(),
+        serialPerSession: config.serialPerSession,
+        plugins,
+        systemPromptBase: config.systemPromptBase,
+        log,
+    });
+    const surfaces = config.surfaces || [];
+    let started = false;
+    // Lane R opener (raw PTY): resolve the agent's TUI spec (with model injection) and
+    // spawn it in a PtyBridge. Shared by Loom.openTui and the TuiHost given to surfaces.
+    const openTui = async (opts) => {
+        const spec = await hub.resolveTui(opts);
+        return PtyBridge.open(spec, { cols: opts.cols, rows: opts.rows });
+    };
+    return {
+        io: hub,
+        registerDriver(driver) { drivers.set(driver.id, driver); },
+        registerPlugin(plugin) { plugins.push(plugin); },
+        async start() {
+            if (started)
+                return;
+            started = true;
+            for (const t of surfaces) {
+                await t.start(hub, { openTui }); // hub = Lane S (LoomIO); openTui = Lane R
+                log(`[loom] terminal started: ${t.id}`);
+            }
+        },
+        async stop() {
+            if (!started)
+                return;
+            started = false;
+            for (const t of surfaces) {
+                try {
+                    await t.stop();
+                }
+                catch { /* ignore */ }
+            }
+        },
+        status() {
+            return { agents: [...drivers.keys()], surfaces: surfaces.map(t => t.id), started };
+        },
+        resolveTui(opts) { return hub.resolveTui(opts); },
+        openTui,
+        async runTui(opts) {
+            const spec = await hub.resolveTui(opts);
+            return attachTui(spec, { observers: opts.observers });
+        },
+    };
+}

package/packages/kernel/dist/runtime/pty.d.ts

@@ -0,0 +1,23 @@
+import type { TuiSpec } from '../contracts/driver.js';
+export declare function ptyAvailable(): boolean;
+export interface PtyOpenOpts {
+    cols?: number;
+    rows?: number;
+}
+export interface PtyExit {
+    exitCode: number;
+    signal?: number;
+}
+export declare class PtyBridge {
+    private readonly proc;
+    private readonly dataCbs;
+    private readonly exitCbs;
+    private constructor();
+    static open(spec: TuiSpec, opts?: PtyOpenOpts): PtyBridge;
+    onData(cb: (d: string) => void): () => void;
+    onExit(cb: (e: PtyExit) => void): () => void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    get pid(): number;
+}

package/packages/kernel/dist/runtime/pty.js

@@ -0,0 +1,69 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let _pty;
+function loadPty() {
+    if (_pty === undefined) {
+        try {
+            _pty = require('node-pty');
+        }
+        catch {
+            _pty = null;
+        }
+    }
+    return _pty;
+}
+export function ptyAvailable() { return !!loadPty(); }
+// A pseudo-terminal bridge around an agent's interactive process. Carries raw TUI bytes
+// in both directions and fans `onData` out to many observers (full passthrough + tee/mirror).
+// This is the capability the kernel previously lacked: transparently passing through
+// Claude/Codex TUI traffic instead of only the structured -p stream.
+export class PtyBridge {
+    proc;
+    dataCbs = new Set();
+    exitCbs = new Set();
+    constructor(proc) {
+        this.proc = proc;
+        proc.onData((d) => { for (const cb of this.dataCbs) {
+            try {
+                cb(d);
+            }
+            catch { /* isolate */ }
+        } });
+        proc.onExit((e) => {
+            for (const cb of this.exitCbs) {
+                try {
+                    cb({ exitCode: e.exitCode, signal: e.signal });
+                }
+                catch { /* isolate */ }
+            }
+        });
+    }
+    static open(spec, opts = {}) {
+        const pty = loadPty();
+        if (!pty)
+            throw new Error('node-pty is not available — install the optional dependency `node-pty` to use TUI passthrough.');
+        const proc = pty.spawn(spec.command, spec.args, {
+            name: 'xterm-256color',
+            cols: opts.cols || 80,
+            rows: opts.rows || 24,
+            cwd: spec.cwd,
+            env: { ...process.env, ...(spec.env || {}) },
+        });
+        return new PtyBridge(proc);
+    }
+    onData(cb) { this.dataCbs.add(cb); return () => this.dataCbs.delete(cb); }
+    onExit(cb) { this.exitCbs.add(cb); return () => this.exitCbs.delete(cb); }
+    write(data) { try {
+        this.proc.write(data);
+    }
+    catch { /* closed */ } }
+    resize(cols, rows) { try {
+        this.proc.resize(Math.max(1, cols), Math.max(1, rows));
+    }
+    catch { /* closed */ } }
+    kill(signal) { try {
+        this.proc.kill(signal);
+    }
+    catch { /* closed */ } }
+    get pid() { return this.proc.pid; }
+}

package/packages/kernel/dist/runtime/session-runner.d.ts

@@ -0,0 +1,27 @@
+import type { UniversalSnapshot } from '../protocol/index.js';
+import type { AgentDriver, AgentTurnInput, DriverResult } from '../contracts/driver.js';
+import type { InteractionHandler } from '../contracts/ports.js';
+export declare class SessionRunner {
+    readonly sessionKey: string;
+    readonly agent: string;
+    readonly taskId: string;
+    private readonly onUpdate;
+    private readonly interactionHandler?;
+    readonly snapshot: UniversalSnapshot;
+    private seq;
+    private readonly abort;
+    private steerFn;
+    private pending;
+    private finished;
+    constructor(sessionKey: string, agent: string, taskId: string, onUpdate: (snapshot: UniversalSnapshot, seq: number) => void, interactionHandler?: InteractionHandler | undefined);
+    get currentSeq(): number;
+    private publish;
+    run(driver: AgentDriver, input: AgentTurnInput, prompt: string, model: string | null, effort: string | null): Promise<DriverResult>;
+    private applyEvent;
+    private askUser;
+    private flushPending;
+    stop(): void;
+    steer(prompt: string, attachments?: string[]): Promise<boolean>;
+    interact(promptId: string, action: 'select' | 'text' | 'skip' | 'cancel', value?: string): boolean;
+}
+export declare function projectActivity(snap: UniversalSnapshot): string;