pikiloom 0.4.36 → 0.4.38

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

@@ -0,0 +1,309 @@
+export declare const PROTOCOL_VERSION: 1;
+export type SessionPhase = 'idle' | 'queued' | 'streaming' | 'done';
+export interface UniversalPlanStep {
+    text: string;
+    status: 'pending' | 'inProgress' | 'completed';
+}
+export interface UniversalPlan {
+    explanation: string | null;
+    steps: UniversalPlanStep[];
+}
+export interface UniversalToolCall {
+    id: string;
+    name: string;
+    summary: string;
+    input?: string | null;
+    result?: string | null;
+    status: 'running' | 'done' | 'failed';
+}
+export interface UniversalSubAgent {
+    id: string;
+    kind: string | null;
+    description: string | null;
+    model: string | null;
+    tools: Array<{
+        id: string;
+        name: string;
+        summary: string;
+    }>;
+    status: 'running' | 'done' | 'failed';
+}
+export interface UniversalUsage {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cachedInputTokens: number | null;
+    contextUsedTokens?: number | null;
+    contextPercent: number | null;
+    turnOutputTokens?: number | null;
+    providerName?: string | null;
+}
+export interface UniversalQueuedTask {
+    taskId: string;
+    prompt: string;
+}
+export interface UniversalArtifact {
+    url?: string;
+    path?: string;
+    fileName: string;
+    fileSize?: number;
+    mime?: string;
+    kind: 'photo' | 'document';
+    caption?: string;
+}
+export interface UniversalInteractionQuestion {
+    id: string;
+    header?: string;
+    text: string;
+    type?: 'text' | 'select' | string;
+    choices?: Array<{
+        label: string;
+        description?: string;
+        value?: string;
+    }>;
+    allowFreeform?: boolean;
+    allowEmpty?: boolean;
+}
+export interface UniversalInteraction {
+    promptId: string;
+    kind: 'user-input' | 'permission' | 'confirmation';
+    title: string;
+    hint?: string | null;
+    questions: UniversalInteractionQuestion[];
+    currentIndex?: number;
+}
+export interface UniversalSnapshot {
+    phase: SessionPhase;
+    taskId?: string | null;
+    sessionId?: string | null;
+    agent?: string | null;
+    model?: string | null;
+    effort?: string | null;
+    prompt?: string | null;
+    text?: string;
+    reasoning?: string;
+    activity?: string;
+    plan?: UniversalPlan | null;
+    toolCalls?: UniversalToolCall[];
+    subAgents?: UniversalSubAgent[];
+    usage?: UniversalUsage | null;
+    artifacts?: UniversalArtifact[];
+    interactions?: UniversalInteraction[];
+    queued?: UniversalQueuedTask[];
+    error?: string | null;
+    incomplete?: boolean;
+    startedAt?: number;
+    updatedAt: number;
+}
+export interface SessionMeta {
+    sessionKey: string;
+    agent?: string | null;
+    title?: string | null;
+    phase?: SessionPhase;
+    updatedAt?: number;
+}
+export interface SnapshotPatch {
+    full?: UniversalSnapshot;
+    appendText?: string;
+    appendReasoning?: string;
+    set?: Partial<UniversalSnapshot>;
+}
+export declare function emptySnapshot(): UniversalSnapshot;
+export declare function diffSnapshot(prev: UniversalSnapshot, next: UniversalSnapshot): SnapshotPatch;
+export declare function applySnapshotPatch(prev: UniversalSnapshot | null, patch: SnapshotPatch): UniversalSnapshot;
+export interface AgentInfo {
+    id: string;
+    capabilities?: {
+        steer?: boolean;
+        interact?: boolean;
+        resume?: boolean;
+        tui?: boolean;
+    };
+}
+export interface ModelDescriptor {
+    id: string;
+    label?: string;
+    providerName?: string | null;
+    contextWindow?: number | null;
+}
+export interface EffortOption {
+    id: string;
+    label?: string;
+}
+export interface ToolDescriptor {
+    id: string;
+    name: string;
+    description?: string;
+    enabled?: boolean;
+}
+export interface SkillDescriptor {
+    id: string;
+    name: string;
+    description?: string;
+}
+export type TransportKind = 'websocket' | 'webrtc' | 'cli' | string;
+export type HostCapability = 'prompt' | 'stop' | 'steer' | 'interact' | 'subscribe-all' | 'artifacts' | 'history' | 'catalog' | 'tui';
+export interface HostInfo {
+    name: string;
+    version: string;
+    transport: TransportKind;
+    capabilities: HostCapability[];
+    authRequired?: boolean;
+}
+export interface ClientHello {
+    type: 'hello';
+    v: number;
+    client?: {
+        name?: string;
+        platform?: string;
+    };
+    token?: string;
+}
+export interface ClientSubscribe {
+    type: 'subscribe';
+    sessionKey: string;
+}
+export interface ClientUnsubscribe {
+    type: 'unsubscribe';
+    sessionKey: string;
+}
+export interface ClientPrompt {
+    type: 'prompt';
+    sessionKey?: string;
+    prompt: string;
+    agent?: string;
+    workdir?: string;
+    model?: string | null;
+    effort?: string | null;
+    attachments?: string[];
+    clientRef?: string;
+}
+export interface ClientStop {
+    type: 'stop';
+    sessionKey: string;
+}
+export interface ClientSteer {
+    type: 'steer';
+    taskId: string;
+    prompt: string;
+}
+export interface ClientInteract {
+    type: 'interact';
+    promptId: string;
+    action: 'select' | 'text' | 'skip' | 'cancel';
+    value?: string;
+}
+export interface ClientGetSnapshot {
+    type: 'getSnapshot';
+    sessionKey: string;
+}
+export interface ClientListSessions {
+    type: 'listSessions';
+}
+export interface ClientGetHistory {
+    type: 'getHistory';
+    sessionKey: string;
+    ref?: string;
+}
+export interface ClientGetCatalog {
+    type: 'getCatalog';
+    agent?: string;
+    model?: string | null;
+    workdir?: string;
+    ref?: string;
+}
+export interface ClientPing {
+    type: 'ping';
+    t?: number;
+}
+export interface ClientOpenTui {
+    type: 'openTui';
+    agent?: string;
+    workdir?: string;
+    model?: string | null;
+    sessionId?: string | null;
+    cols?: number;
+    rows?: number;
+    ref?: string;
+}
+export interface ClientTuiInput {
+    type: 'tuiInput';
+    tuiId: string;
+    data: string;
+}
+export interface ClientTuiResize {
+    type: 'tuiResize';
+    tuiId: string;
+    cols: number;
+    rows: number;
+}
+export interface ClientTuiClose {
+    type: 'tuiClose';
+    tuiId: string;
+}
+export type ClientMessage = ClientHello | ClientSubscribe | ClientUnsubscribe | ClientPrompt | ClientStop | ClientSteer | ClientInteract | ClientGetSnapshot | ClientListSessions | ClientGetHistory | ClientGetCatalog | ClientOpenTui | ClientTuiInput | ClientTuiResize | ClientTuiClose | ClientPing;
+export interface ServerWelcome {
+    type: 'welcome';
+    v: number;
+    host: HostInfo;
+    sessions: SessionMeta[];
+}
+export interface ServerSession {
+    type: 'session';
+    sessionKey: string;
+    seq: number;
+    patch: SnapshotPatch;
+}
+export interface ServerSessions {
+    type: 'sessions';
+    sessions: SessionMeta[];
+}
+export interface ServerHistory {
+    type: 'history';
+    sessionKey: string;
+    turns: UniversalSnapshot[];
+    ref?: string;
+}
+export interface ServerCatalog {
+    type: 'catalog';
+    agents: AgentInfo[];
+    agent?: string;
+    models: ModelDescriptor[];
+    effort: EffortOption[];
+    tools: ToolDescriptor[];
+    skills: SkillDescriptor[];
+    ref?: string;
+}
+export interface ServerAccepted {
+    type: 'accepted';
+    sessionKey: string;
+    taskId: string;
+    clientRef?: string;
+}
+export interface ServerError {
+    type: 'error';
+    message: string;
+    code?: string;
+    clientRef?: string;
+}
+export interface ServerPong {
+    type: 'pong';
+    t?: number;
+}
+export interface ServerTuiOpened {
+    type: 'tuiOpened';
+    tuiId: string;
+    ref?: string;
+}
+export interface ServerTuiData {
+    type: 'tuiData';
+    tuiId: string;
+    data: string;
+}
+export interface ServerTuiExit {
+    type: 'tuiExit';
+    tuiId: string;
+    exitCode: number;
+    signal?: number;
+}
+export type ServerMessage = ServerWelcome | ServerSession | ServerSessions | ServerHistory | ServerCatalog | ServerTuiOpened | ServerTuiData | ServerTuiExit | ServerAccepted | ServerError | ServerPong;
+export declare function isClientMessage(value: unknown): value is ClientMessage;

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

@@ -0,0 +1,59 @@
+// The wire vocabulary shared by the kernel runtime and every transport/terminal.
+// This is the SSOT shape: a driver-agnostic, accumulating snapshot of one session,
+// plus a small set of control verbs. Ported from pikiloom's pikichannel protocol.
+export const PROTOCOL_VERSION = 1;
+export function emptySnapshot() {
+    return { phase: 'idle', updatedAt: 0 };
+}
+const APPEND_FIELDS = ['text', 'reasoning'];
+const STRUCT_FIELDS = ['plan', 'toolCalls', 'subAgents', 'usage', 'artifacts', 'interactions', 'queued'];
+const SCALAR_FIELDS = ['phase', 'taskId', 'sessionId', 'agent', 'model', 'effort', 'prompt', 'activity', 'error', 'incomplete', 'startedAt', 'updatedAt'];
+export function diffSnapshot(prev, next) {
+    const patch = {};
+    let set;
+    // Coerce undefined -> null so a field-clear survives JSON serialization on the wire
+    // (JSON.stringify drops undefined-valued keys, which would otherwise leave the
+    // receiver's cumulative snapshot holding the previous turn's value).
+    const put = (k, v) => { (set ||= {})[k] = v === undefined ? null : v; };
+    for (const f of APPEND_FIELDS) {
+        const a = prev[f] ?? '';
+        const b = next[f] ?? '';
+        if (a === b)
+            continue;
+        if (typeof b === 'string' && typeof a === 'string' && b.startsWith(a)) {
+            if (f === 'text')
+                patch.appendText = b.slice(a.length);
+            else
+                patch.appendReasoning = b.slice(a.length);
+        }
+        else {
+            put(f, b);
+        }
+    }
+    for (const f of SCALAR_FIELDS) {
+        if (prev[f] !== next[f])
+            put(f, next[f]);
+    }
+    for (const f of STRUCT_FIELDS) {
+        if (JSON.stringify(prev[f]) !== JSON.stringify(next[f]))
+            put(f, next[f]);
+    }
+    if (set)
+        patch.set = set;
+    return patch;
+}
+export function applySnapshotPatch(prev, patch) {
+    if (patch.full)
+        return patch.full;
+    const next = prev ? { ...prev } : emptySnapshot();
+    if (patch.appendText)
+        next.text = (next.text || '') + patch.appendText;
+    if (patch.appendReasoning)
+        next.reasoning = (next.reasoning || '') + patch.appendReasoning;
+    if (patch.set)
+        Object.assign(next, patch.set);
+    return next;
+}
+export function isClientMessage(value) {
+    return !!value && typeof value === 'object' && typeof value.type === 'string';
+}

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

@@ -0,0 +1,65 @@
+import { type UniversalSnapshot, type SnapshotPatch, type SessionMeta, type AgentInfo, type ModelDescriptor, type EffortOption, type ToolDescriptor, type SkillDescriptor } from '../protocol/index.js';
+import type { AgentDriver, TuiSpec } from '../contracts/driver.js';
+import type { SessionStore, ModelResolver, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog } from '../contracts/ports.js';
+import type { LoomIO, PromptInput, Plugin } from '../contracts/surface.js';
+export interface HubDeps {
+    drivers: Map<string, AgentDriver>;
+    defaultAgent: string;
+    workdir: string;
+    sessionStore: SessionStore;
+    modelResolver: ModelResolver;
+    toolProvider: ToolProvider;
+    systemPromptBuilder: SystemPromptBuilder;
+    catalog: Catalog;
+    interactionHandler: InteractionHandler;
+    plugins: Plugin[];
+    serialPerSession?: boolean;
+    systemPromptBase?: string;
+    log?: (msg: string) => void;
+}
+export declare class Hub implements LoomIO {
+    private readonly deps;
+    private readonly sessions;
+    private readonly runnersByTask;
+    private readonly active;
+    private readonly waiting;
+    private readonly seqByKey;
+    private readonly updateSubs;
+    private readonly sessionsSubs;
+    constructor(deps: HubDeps);
+    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[]>;
+    resolveTui(opts: {
+        agent?: string;
+        workdir?: string;
+        model?: string | null;
+        sessionId?: string | null;
+    }): Promise<TuiSpec>;
+    prompt(input: PromptInput): Promise<{
+        sessionKey: string;
+        taskId: string;
+    }>;
+    private enqueue;
+    private runNow;
+    private promoteNext;
+    private queueView;
+    private publishQueued;
+    private collectTools;
+    private onRunnerUpdate;
+    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: (k: string, s: UniversalSnapshot, p: SnapshotPatch, seq: number) => void): () => void;
+    onSessionsChanged(cb: (s: SessionMeta[]) => void): () => void;
+    private emitSessionsChanged;
+    listSessions(): SessionMeta[];
+    getSnapshot(sessionKey: string): {
+        snapshot: UniversalSnapshot;
+        seq: number;
+    } | null;
+    getHistory(sessionKey: string): Promise<UniversalSnapshot[]>;
+}

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

@@ -0,0 +1,260 @@
+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);
+        return driver.tui({ workdir, model: injection?.model ?? opts.model ?? null, sessionId: opts.sessionId ?? null, env: injection?.env });
+    }
+    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 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 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,
+        };
+        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);
+    }
+    async collectTools(agent, workdir, workspacePath) {
+        const out = [];
+        try {
+            const base = await this.deps.toolProvider.provideForSession({ agent, workdir, workspacePath });
+            out.push(...base.servers);
+        }
+        catch (e) {
+            this.deps.log?.(`[hub] toolProvider failed: ${e?.message || e}`);
+        }
+        for (const plugin of this.deps.plugins) {
+            if (!plugin.tools)
+                continue;
+            try {
+                out.push(...(await plugin.tools({ agent, workdir })));
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] plugin ${plugin.id} tools failed: ${e?.message || e}`);
+            }
+        }
+        return out;
+    }
+    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 [];
+        }
+    }
+}