@beeos-ai/device-agent 0.5.1 → 0.7.0

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

@@ -6,18 +6,44 @@
  * `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.
+ * Persistence model — turn-grained:
  *
- * Surface mirrors the Python `SessionHandler` so ACP handlers remain
- * thin pass-throughs.
+ *   - User prompts persist immediately on entry to `prompt()` (one
+ *     `user_message` JSONL row).
+ *   - Assistant chunks (`task:text`) and tool events (`task:tool`) are
+ *     accumulated in an in-memory `InFlightTurnAggregator`; nothing is
+ *     written until `task:end`, at which point a single
+ *     `assistant_turn` JSONL row captures the entire turn (full text,
+ *     every tool call in invocation order, stop reason, optional
+ *     terminal error). This matches OpenClaw's "one line = one
+ *     complete message" model and avoids the fragmented transcript
+ *     produced by the legacy "one row per chunk" implementation.
+ *
+ * Single-session mode (`fixedSessionId`):
+ *
+ *   When a fixedSessionId is supplied, every ACP session-management
+ *   method (`new`/`load`/`list`/`rename`/`delete`) collapses onto that
+ *   one sid. The mobile/web client receives `multipleSessions: false`
+ *   in the initialize handshake so the UI hides session-switching
+ *   affordances. This is the production configuration for device-agent
+ *   — a single physical device serialises tasks anyway, and a fixed
+ *   sid keeps the JSONL transcript stable across reconnects.
+ *
+ * Replay model — push-style:
+ *
+ *   `session/load` does NOT return history in the RPC `result` (the
+ *   web/mobile SDKs ignore that field). Instead, it pushes one
+ *   `history_turn` envelope per persisted turn followed by an
+ *   in-flight snapshot (streaming-style, WITHOUT `stream_complete`)
+ *   when a task is mid-flight. This matches beeos-claw's
+ *   `handleSessionLoad` exactly so the same chat-store reducer paths
+ *   handle both agents.
  */
-import { MessageStore, type MessageHistoryEntry } from "./message-store.js";
+import { MessageStore } from "./message-store.js";
 import type { AgentHost } from "../ports/agent-host.js";
+import type { PluginCommandRegistry } from "./plugin-commands/registry.js";
 export interface SessionUpdateNotifier {
-    /** Called for every step during `session/prompt`. */
+    /** Called for every step during `session/prompt` (and during `session/load` replay). */
     send(sessionId: string, update: Record<string, unknown>): void;
 }
 export interface SessionManagerOptions {
@@ -26,23 +52,42 @@ export interface SessionManagerOptions {
     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`).
+     * `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;
+    /**
+     * If set, single-session mode is active: every session-management
+     * method aliases to this sid, `multipleSessions` should be advertised
+     * as `false` in `initialize`, and `delete` collapses to `clear`.
+     */
+    fixedSessionId?: string;
     maxSessions?: number;
     sessionTtlMs?: number;
+    /**
+     * Optional plugin command registry. When set, `prompt()` does a
+     * prefix match against incoming text BEFORE dispatching to the
+     * AgentRunner — `/screenshot` and friends short-circuit straight
+     * to their handlers, bypassing the LLM entirely (mirrors OpenClaw
+     * `matchPluginCommand` semantics, see
+     * `openclaw/src/plugins/commands.ts`).
+     */
+    pluginCommands?: PluginCommandRegistry;
 }
 export declare class SessionManager {
     private readonly host;
     private readonly store;
     private readonly notifier;
     private readonly onSetModel;
+    private readonly fixedSessionId;
     private readonly maxSessions;
     private readonly sessionTtlMs;
+    private readonly pluginCommands;
     private readonly sessions;
     /** taskId → sessionId for routing host events to the right ACP session. */
     private readonly taskToSession;
+    /** Per-task in-flight aggregators. Keyed by taskId. */
+    private readonly inFlightByTask;
     private activeSessionId;
     private currentTask;
     private unsubscribe;
@@ -52,9 +97,22 @@ export declare class SessionManager {
     newSession(): {
         sessionId: string;
     };
+    /**
+     * Load a session.
+     *
+     * Push-replay model: emit one `history_turn` envelope per persisted
+     * turn so the chat-store sidecar resolver can reconstruct the bubble
+     * graph identically to a fresh streaming run. If a task is currently
+     * in-flight on this sid, additionally emit a streaming-style
+     * snapshot (`agent_message_chunk` + `tool_call` + `tool_call_update`)
+     * WITHOUT the closing `stream_complete` so the client knows the turn
+     * is still active.
+     *
+     * Returns `{ sessionId }` only — the legacy `history` field has been
+     * dropped because no client reads it (see explore audit).
+     */
     loadSession(sessionId: string): {
         sessionId: string;
-        history: MessageHistoryEntry[];
     };
     listSessions(): {
         sessions: {
@@ -67,6 +125,14 @@ export declare class SessionManager {
         sessionId: string;
         title: string;
     };
+    /**
+     * Delete a session.
+     *
+     * In single-session mode, this collapses to `clearSession` because
+     * the one-and-only session can't be removed without losing the
+     * device's identity. Otherwise drops the in-memory + persisted state
+     * for `sessionId`.
+     */
     deleteSession(sessionId: string): {
         deleted: boolean;
     };
@@ -94,56 +160,85 @@ export declare class SessionManager {
     /** Cancel the in-flight task for the active session, if any. */
     cancel(): Promise<boolean>;
     /**
-     * Translate host `AgentEvent`s into ACP `session/update` envelopes.
+     * Dispatch a `/command` prompt to its registered handler, bypassing
+     * the AgentRunner / LLM. The wire shape stays compatible with the
+     * regular prompt path:
+     *
+     *   1. user message persisted (so reload sees the typed `/screenshot`)
+     *   2. `agent_status: running`
+     *   3. handler runs — typically emits its own `agent_message_chunk`
+     *      with a `resource_link` (see `ScreenshotCommandHandler`)
+     *   4. `stream_complete` + `agent_status: idle`
      *
-     * 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 / update / end (tool_call / tool_call_update).
-     *                        `update` carries partial progress for long-running
-     *                        tools (large APK install, long shell streams,
-     *                        large screenshots) so the chat-store tool card
-     *                        can refresh in-place without waiting for `end`.
-     *                        Mirrors beeos-claw's tool_call_update in_progress
-     *                        semantics (see acp-gateway/tool-call-payload-builder.ts).
-     *   - `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).
-     *   - `task:end`       — terminal lifecycle event. We emit the canonical
-     *                        ACP `stream_complete` envelope here (BEFORE the
-     *                        `prompt()` finally block fires `agent_status:
-     *                        "idle"`). chat-store's `applyIncrementalUpdate`
-     *                        relies on `stream_complete` to (a) collapse
-     *                        streaming text part `state` from "streaming"
-     *                        back to "done" so the cursor caret stops
-     *                        rendering, and (b) trim `pendingMap` /
-     *                        `currentAsstId` so history-replay paths don't
-     *                        re-flag the just-finished turn as processing.
-     *                        Without it the bubble caret never collapses
-     *                        and reload paths see a stale `processing`
-     *                        pending — see plan
-     *                        `device-agent_stream_complete_对齐`.
+     * Errors from the handler are converted into a `system_message_chunk`
+     * notice (level=error) instead of crashing the whole session.
      *
-     * 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`.
+     * NOTE: assistant turns produced by plugin commands are intentionally
+     * NOT persisted — slash command output is time-sensitive (a stale
+     * screenshot helps no one) and the user should re-issue the command
+     * on reconnect. The user-side `/screenshot` text IS persisted so the
+     * conversation log makes sense.
+     */
+    private handlePluginCommand;
+    /**
+     * Translate host `AgentEvent`s into ACP `session/update` envelopes
+     * AND accumulate the assistant turn into the in-memory aggregator
+     * for this task. The aggregator is finalised on `task:end` and
+     * persisted as a single `assistant_turn` JSONL row — chunk-level
+     * persistence is intentionally NOT done (it produces fragmented
+     * transcripts that can't be reconstructed cleanly on reload).
      *
-     * Events for tasks not owned by this SessionManager are ignored —
-     * other plugins (HTTP debug, custom) may submit tasks through the
-     * same host bus.
+     * Source events:
+     *   - `task:start`     — allocate the in-flight aggregator.
+     *   - `task:text`      — append delta to in-flight + emit
+     *                        `agent_message_chunk`.
+     *   - `task:reasoning` — emit `agent_thought_chunk` only (NOT
+     *                        persisted — bloats LLM context on resume).
+     *   - `task:tool`      — track in in-flight + emit
+     *                        `tool_call` / `tool_call_update`. Mid-flight
+     *                        progress is forwarded as `in_progress`.
+     *   - `task:notice`    — `warn` is dropped entirely; `error` becomes
+     *                        a `system_message_chunk` with
+     *                        `metadata.kind = "agent_notice"` AND is
+     *                        captured as the in-flight `error` field so
+     *                        the persisted turn carries the failure
+     *                        text.
+     *   - `task:step`      — structural; no ACP emission.
+     *   - `task:end`       — finalise the in-flight, persist a single
+     *                        `assistant_turn` row, emit `stream_complete`
+     *                        BEFORE the closing `agent_status: idle`
+     *                        (chat-store relies on this order).
      */
     private handleHostEvent;
     private resolveSession;
+    /** Map any sid the client passes onto the canonical sid in fixed mode. */
+    private aliasSessionId;
+    /** Materialise the fixed session in-memory + on disk if it isn't yet. */
+    private ensureFixedSession;
+    /**
+     * Lazily create an in-flight aggregator for events that arrive
+     * without a preceding `task:start` (defensive — agent-host always
+     * fires start, but tests + alternate adapters may not).
+     */
+    private ensureInflight;
+    private findInflightForSession;
+    /**
+     * Emit a single persisted record as a `history_turn` envelope.
+     *
+     * Mirrors beeos-claw `bridge-core.replayAssistantTurnAsStream` —
+     * `history_turn` is a stamped-done snapshot of an entire turn that
+     * the chat-store reducer renders as a complete bubble (no streaming
+     * cursor). For assistant turns, we serialise tool calls into the
+     * shape `apply-update.buildToolCalls` accepts.
+     */
+    private emitHistoryTurn;
+    /**
+     * Emit the current state of an in-flight turn as streaming-style
+     * envelopes WITHOUT the closing `stream_complete`. The client uses
+     * the absence of `stream_complete` to recognise the turn is still
+     * generating, matching beeos-claw's `emitCurrentStreamSnapshot`.
+     */
+    private emitInflightSnapshot;
     private notify;
     private evictExpired;
 }