@beeos-ai/device-agent 0.4.0

package/dist/app/device-manager.js

@@ -0,0 +1,64 @@
+/**
+ * Application use case — DeviceManager.
+ *
+ * MVP keeps a single active IDevice (parity with the Python agent which is
+ * 1 device = 1 process). The class is structured to support multi-device
+ * fan-out later — the inbound layer never has to be rewritten when that day
+ * comes.
+ */
+export class DeviceManager {
+    devices = new Map();
+    activeId = null;
+    /** Register and connect a device. Returns the canonical id used. */
+    async register(device, id) {
+        await device.connect();
+        const info = await device.getInfo().catch(() => undefined);
+        const finalId = id ?? info?.name ?? "default";
+        const reg = { id: finalId, device, info };
+        this.devices.set(finalId, reg);
+        if (!this.activeId)
+            this.activeId = finalId;
+        return reg;
+    }
+    list() {
+        return Array.from(this.devices.values());
+    }
+    get(id) {
+        return this.devices.get(id ?? this.activeId ?? "");
+    }
+    active() {
+        const reg = this.get();
+        if (!reg)
+            throw new Error("No active device — register one first.");
+        return reg.device;
+    }
+    setActive(id) {
+        if (!this.devices.has(id))
+            throw new Error(`Unknown device id: ${id}`);
+        this.activeId = id;
+    }
+    async disconnectAll() {
+        for (const r of this.devices.values()) {
+            try {
+                await r.device.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        this.devices.clear();
+        this.activeId = null;
+    }
+    /** Quick liveness probe; returns true iff device.getInfo() resolves. */
+    async healthCheck(id) {
+        const reg = this.get(id);
+        if (!reg)
+            return false;
+        try {
+            reg.info = await reg.device.getInfo();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=device-manager.js.map

package/dist/app/device-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.js","sourceRoot":"","sources":["../../src/app/device-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,OAAO,aAAa;IACP,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;IACzD,QAAQ,GAAkB,IAAI,CAAC;IAEvC,oEAAoE;IACpE,KAAK,CAAC,QAAQ,CAAC,MAAe,EAAE,EAAW;QACzC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,EAAE,IAAI,IAAI,EAAE,IAAI,IAAI,SAAS,CAAC;QAC9C,MAAM,GAAG,GAAuB,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,EAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,MAAM;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACpE,OAAO,GAAG,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC;gBAAC,MAAM,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,WAAW,CAAC,EAAW;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvB,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/app/message-store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory MessageStore.
+ *
+ * Mirrors the surface of the Python `MessageStore` (`add_message`,
+ * `get_messages_as_dicts`, `list_sessions`, etc.) so the ACP handlers stay
+ * byte-for-byte compatible. Persistence is left out of the MVP; `~/.beeos`
+ * SQLite can be re-added later behind the same interface (pluggable adapter).
+ */
+export interface StoredMessage {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    messageType: "text" | "tool_call" | "tool_result" | "status";
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+export interface SessionRecord {
+    sessionId: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MessageHistoryEntry {
+    role: string;
+    content: string;
+    type: string;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+}
+export declare class MessageStore {
+    private readonly maxPerSession;
+    private readonly maxSessions;
+    private readonly sessions;
+    private readonly messages;
+    constructor(opts?: {
+        maxMessagesPerSession?: number;
+        maxSessions?: number;
+    });
+    upsertSession(sessionId: string, title?: string): void;
+    sessionExists(sessionId: string): boolean;
+    renameSession(sessionId: string, title: string): void;
+    deleteSession(sessionId: string): void;
+    listSessions(limit?: number): Array<{
+        sessionId: string;
+        title: string;
+        updatedAt: number;
+    }>;
+    clearSession(sessionId: string): void;
+    addMessage(sessionId: string, role: StoredMessage["role"], content: string, messageType?: StoredMessage["messageType"], metadata?: Record<string, unknown>): string;
+    getMessages(sessionId: string, limit?: number): StoredMessage[];
+    getMessagesAsDicts(sessionId: string, limit?: number): MessageHistoryEntry[];
+    /** Drop the least-recently-updated sessions when we exceed maxSessions. */
+    private evictSessionLru;
+}

package/dist/app/message-store.js

@@ -0,0 +1,99 @@
+/**
+ * In-memory MessageStore.
+ *
+ * Mirrors the surface of the Python `MessageStore` (`add_message`,
+ * `get_messages_as_dicts`, `list_sessions`, etc.) so the ACP handlers stay
+ * byte-for-byte compatible. Persistence is left out of the MVP; `~/.beeos`
+ * SQLite can be re-added later behind the same interface (pluggable adapter).
+ */
+import { randomUUID } from "node:crypto";
+export class MessageStore {
+    maxPerSession;
+    maxSessions;
+    sessions = new Map();
+    messages = new Map();
+    constructor(opts = {}) {
+        this.maxPerSession = opts.maxMessagesPerSession ?? 100;
+        this.maxSessions = opts.maxSessions ?? 200;
+    }
+    upsertSession(sessionId, title = "New chat") {
+        const now = Date.now();
+        const cur = this.sessions.get(sessionId);
+        if (cur) {
+            cur.updatedAt = now;
+            return;
+        }
+        this.sessions.set(sessionId, { sessionId, title, createdAt: now, updatedAt: now });
+        this.evictSessionLru();
+    }
+    sessionExists(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    renameSession(sessionId, title) {
+        const s = this.sessions.get(sessionId);
+        if (s) {
+            s.title = title;
+            s.updatedAt = Date.now();
+        }
+    }
+    deleteSession(sessionId) {
+        this.sessions.delete(sessionId);
+        this.messages.delete(sessionId);
+    }
+    listSessions(limit = 50) {
+        const all = Array.from(this.sessions.values())
+            .sort((a, b) => b.updatedAt - a.updatedAt)
+            .slice(0, limit);
+        return all.map((s) => ({ sessionId: s.sessionId, title: s.title, updatedAt: s.updatedAt }));
+    }
+    clearSession(sessionId) {
+        this.messages.delete(sessionId);
+    }
+    addMessage(sessionId, role, content, messageType = "text", metadata = {}) {
+        const id = randomUUID();
+        const now = Date.now();
+        const entry = { id, sessionId, role, content, messageType, metadata, createdAt: now };
+        const arr = this.messages.get(sessionId) ?? [];
+        arr.push(entry);
+        if (arr.length > this.maxPerSession)
+            arr.splice(0, arr.length - this.maxPerSession);
+        this.messages.set(sessionId, arr);
+        const s = this.sessions.get(sessionId);
+        if (s)
+            s.updatedAt = now;
+        else
+            this.upsertSession(sessionId);
+        return id;
+    }
+    getMessages(sessionId, limit) {
+        const arr = this.messages.get(sessionId) ?? [];
+        const n = Math.min(limit ?? this.maxPerSession, arr.length);
+        return arr.slice(arr.length - n);
+    }
+    getMessagesAsDicts(sessionId, limit) {
+        return this.getMessages(sessionId, limit).map((m) => {
+            const out = {
+                role: m.role,
+                content: m.content,
+                type: m.messageType,
+                createdAt: m.createdAt,
+            };
+            if (Object.keys(m.metadata).length > 0)
+                out.metadata = m.metadata;
+            return out;
+        });
+    }
+    /** Drop the least-recently-updated sessions when we exceed maxSessions. */
+    evictSessionLru() {
+        if (this.sessions.size <= this.maxSessions)
+            return;
+        const sorted = Array.from(this.sessions.values()).sort((a, b) => a.updatedAt - b.updatedAt);
+        const overflow = this.sessions.size - this.maxSessions;
+        for (let i = 0; i < overflow; i++) {
+            const id = sorted[i].sessionId;
+            this.sessions.delete(id);
+            this.messages.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=message-store.js.map

package/dist/app/message-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-store.js","sourceRoot":"","sources":["../../src/app/message-store.ts"],"names":[],"mappings":"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"}

package/dist/app/session-manager.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Application use case — SessionManager.
+ *
+ * Owns ACP session lifecycle (new/load/list/rename/delete/clear) and the
+ * dispatch of `session/prompt` to the underlying `AgentHost`. Streaming
+ * `session/update` envelopes are produced by translating `AgentEvent`s
+ * received from the host bus.
+ *
+ * SessionManager itself is protocol-agnostic w.r.t. the agent core — it
+ * speaks `AgentHost` only. The translation of host events into ACP
+ * envelopes lives here so swapping `IAgentCore` (single-layer / pi
+ * orchestrator / mock) doesn't change ACP semantics.
+ *
+ * Surface mirrors the Python `SessionHandler` so ACP handlers remain
+ * thin pass-throughs.
+ */
+import { MessageStore, type MessageHistoryEntry } from "./message-store.js";
+import type { AgentHost } from "../ports/agent-host.js";
+export interface SessionUpdateNotifier {
+    /** Called for every step during `session/prompt`. */
+    send(sessionId: string, update: Record<string, unknown>): void;
+}
+export interface SessionManagerOptions {
+    host: AgentHost;
+    messageStore?: MessageStore;
+    notifier?: SessionUpdateNotifier;
+    /**
+     * Called when the user asks to switch the underlying agent model.
+     * `provider` may be empty when the caller doesn't pin a specific adapter
+     * (auto-detect from `model`).
+     */
+    onSetModel?: (provider: string, model: string) => Promise<void> | void;
+    maxSessions?: number;
+    sessionTtlMs?: number;
+}
+export declare class SessionManager {
+    private readonly host;
+    private readonly store;
+    private readonly notifier;
+    private readonly onSetModel;
+    private readonly maxSessions;
+    private readonly sessionTtlMs;
+    private readonly sessions;
+    /** taskId → sessionId for routing host events to the right ACP session. */
+    private readonly taskToSession;
+    private activeSessionId;
+    private currentTask;
+    private unsubscribe;
+    constructor(opts: SessionManagerOptions);
+    /** Detach from the host bus (used when shutting down the ACP plugin). */
+    detach(): void;
+    newSession(): {
+        sessionId: string;
+    };
+    loadSession(sessionId: string): {
+        sessionId: string;
+        history: MessageHistoryEntry[];
+    };
+    listSessions(): {
+        sessions: {
+            sessionId: string;
+            title: string;
+            updatedAt: number;
+        }[];
+    };
+    renameSession(sessionId: string, title: string): {
+        sessionId: string;
+        title: string;
+    };
+    deleteSession(sessionId: string): {
+        deleted: boolean;
+    };
+    clearSession(sessionId: string): {
+        cleared: boolean;
+    };
+    setMode(sessionId: string, mode: string): {
+        sessionId: string;
+        mode: string;
+    };
+    setModel(sessionId: string, model: string, provider?: string): Promise<{
+        sessionId: string;
+        provider: string;
+        model: string;
+    }>;
+    /**
+     * Run a prompt to completion and return the ACP `stopReason`.
+     *
+     * Streams `session/update` notifications during execution (translated
+     * from `AgentHost` events).
+     */
+    prompt(rawPrompt: string | Array<{
+        type?: string;
+        text?: string;
+    }>, sessionIdHint?: string): Promise<{
+        stopReason: string;
+    }>;
+    /** Cancel the in-flight task for the active session, if any. */
+    cancel(): Promise<boolean>;
+    /**
+     * Translate host `AgentEvent`s into ACP `session/update` envelopes.
+     *
+     * Handles five legitimate ACP-emitting sources plus structural events:
+     *   - `task:text`      — streamed user-visible reply (agent_message_chunk)
+     *   - `task:reasoning` — streaming "thinking" delta (agent_thought_chunk):
+     *                        planner plan/replan descriptions and per-step
+     *                        VLM rationale.
+     *   - `task:tool`      — start / end pairs (tool_call / tool_call_update)
+     *   - `task:notice`    — out-of-band protocol notice. level=warn
+     *                        (transient retry hints) is dropped — noise
+     *                        the user can't act on. level=error (terminal
+     *                        failure) becomes a `system_message_chunk`
+     *                        with `metadata.kind = "agent_notice"`; the
+     *                        web client merges it into the matching
+     *                        assistant bubble's footer. NOT persisted.
+     *   - `task:step`      — structural step record (no ACP emission, kept
+     *                        for HTTP debug / future plugins).
+     *
+     * Every emitted envelope carries `_turnId` (groups all chunks of a
+     * single user prompt) and `messageId` (the per-task authoritative id
+     * shared by every chunk / thought / tool / notice in this turn). The
+     * web `chat-store` sidecar resolver pins thoughts and tool calls to
+     * the assistant bubble bearing the matching `_messageId`.
+     *
+     * Events for tasks not owned by this SessionManager are ignored —
+     * other plugins (HTTP debug, custom) may submit tasks through the
+     * same host bus.
+     */
+    private handleHostEvent;
+    private resolveSession;
+    private notify;
+    private evictExpired;
+}