pikiloom 0.4.37 → 0.4.39

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,68 @@
+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 mergeSpawn;
+    private pluginSpawn;
+    private composeSystemPrompt;
+    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[]>;
+}