@beeos-ai/device-agent 0.5.1 → 0.6.0

package/.pi/extensions/android-tools.ts

@@ -47,6 +47,18 @@ import { Type } from "@sinclair/typebox";
 import { getPiExtensionContext } from "../../src/pi-context.js";
 import type { Shortcut, ShortcutResult } from "../../src/shortcuts/index.js";
 
+/**
+ * Server-side floor for `mobile_use` step budget.
+ *
+ * The outer orchestrator LLM frequently misjudges ADB / Android tasks as
+ * "simple actions" and emits `max_steps: 5..15`, which the inner
+ * `Agent.run` loop blows through before the task can finish — surfacing as
+ * "Reached max steps (N)". Clamping upward at the tool boundary protects
+ * the user without preventing the LLM from explicitly asking for more
+ * steps when it judges a flow as complex.
+ */
+const MIN_MOBILE_USE_STEPS = 30;
+
 export default function (pi: ExtensionAPI) {
   // ── mobile_use ─────────────────────────────────────────────────────────────
   pi.registerTool({
@@ -57,12 +69,12 @@ export default function (pi: ExtensionAPI) {
       "A VLM runs its own screenshot→reason→act loop until it finishes or hits max-steps. " +
       "Pass a full, concrete instruction with app-native UI text. " +
       "For long text (especially Chinese), embed it verbatim and note '原样输入、不要翻译'. " +
-      "One call runs 10–30 steps autonomously; do NOT call repeatedly for the same task.",
+      "One call runs 20–50 steps autonomously; do NOT call repeatedly for the same task.",
     promptSnippet: "mobile_use(task): drive Android phone via VLM screenshot→reason→act loop",
     parameters: Type.Object({
       task: Type.String({ description: "Full natural-language instruction in Chinese or English" }),
       max_steps: Type.Integer({
-        description: "Maximum VLM steps for this call. Required. Typical range 10-30 depending on task complexity.",
+        description: "Maximum VLM steps for this call. Required. Typical range 20-50 depending on task complexity.",
         minimum: 1,
         maximum: 100,
       }),
@@ -72,7 +84,16 @@ export default function (pi: ExtensionAPI) {
       if (signal?.aborted) throw new Error("aborted");
 
       const ctx = getPiExtensionContext();
-      const result = await ctx.runMobileUse(params.task, params.max_steps, signal ?? undefined);
+      const requested = params.max_steps;
+      const effective = Math.max(MIN_MOBILE_USE_STEPS, requested);
+      if (effective !== requested) {
+        const log = (await import("../../src/logger/index.js")).getLogger();
+        log.warn(
+          { component: "mobile_use", requested, effective, floor: MIN_MOBILE_USE_STEPS },
+          "mobile_use.max_steps clamped up to floor",
+        );
+      }
+      const result = await ctx.runMobileUse(params.task, effective, signal ?? undefined);
       return { content: [{ type: "text", text: result }], details: null };
     },
   });

package/dist/app/in-flight-turn.d.ts

@@ -0,0 +1,120 @@
+/**
+ * In-flight assistant turn aggregator.
+ *
+ * A single ACP `session/prompt` produces a stream of host events
+ * (`task:text` deltas, `task:tool` start/update/end, etc.). Persisting
+ * each delta as a separate row produces unusable transcripts on reload
+ * — the resulting bubble is fragmented into dozens of tiny rows with
+ * no clean way to reconstruct what the agent actually said. To match
+ * OpenClaw's "one JSONL line = one complete assistant turn" model, we
+ * accumulate the delta stream in memory here and only commit a single
+ * `AssistantTurnRecord` when the turn terminates.
+ *
+ * Lifecycle:
+ *   - `start(...)` — called from `task:start`, allocates a buffer.
+ *   - `appendText(delta)` / `noteToolStart` / `noteToolUpdate` /
+ *     `noteToolEnd` — accumulate during the turn.
+ *   - `noteFatalNotice(text)` — capture terminal error text so the
+ *     persisted turn carries an `error` field even if the agent's
+ *     final reply is empty.
+ *   - `finalize(stopReason)` — return an immutable
+ *     `AssistantTurnRecord` ready to be appended to JSONL and emitted
+ *     to the client. Caller resets the buffer afterwards.
+ *
+ * This module is pure data + state machine — no IO, no notifications.
+ * SessionManager owns the IO + dispatch side.
+ */
+/** Final status of a single tool invocation inside one turn. */
+export type ToolCallStatus = "in_progress" | "completed" | "failed";
+/** Stop reason mirrored from beeos-claw's three-valued enum. */
+export type StopReason = "end_turn" | "cancelled" | "error";
+export interface InFlightToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+    status: ToolCallStatus;
+    /** Latest output observed (overwritten on each `update` and `end`). */
+    output?: string;
+    startedAt: number;
+    endedAt?: number;
+}
+/** Persisted shape — what gets written to JSONL on `task:end`. */
+export interface PersistedToolCall {
+    id: string;
+    name: string;
+    args: unknown;
+    status: ToolCallStatus;
+    output?: string;
+    startedAt: number;
+    endedAt?: number;
+}
+export interface AssistantTurnRecord {
+    /** Stable `messageId` stamped on every chunk during this turn. */
+    messageId: string;
+    /** Stable `_turnId` stamped on every chunk during this turn. */
+    turnId: string;
+    /** Wall-clock time when the turn started (epoch ms). */
+    startedAt: number;
+    /** Wall-clock time when the turn finalized (epoch ms). */
+    completedAt: number;
+    /** Concatenated assistant reply (sum of every `task:text` delta). */
+    text: string;
+    /** Tool calls in invocation order (insertion order is preserved). */
+    toolCalls: PersistedToolCall[];
+    /** Stop reason at finalize time. */
+    stopReason: StopReason;
+    /** User-facing error text when the turn terminated abnormally. */
+    error?: string;
+}
+/**
+ * Mutable in-flight buffer. Construct once per turn via
+ * `InFlightTurnAggregator.start(...)`, accumulate, then `finalize()`.
+ */
+export declare class InFlightTurnAggregator {
+    readonly taskId: string;
+    readonly turnId: string;
+    readonly messageId: string;
+    readonly startedAt: number;
+    private text;
+    private readonly toolCalls;
+    /** Insertion order tracker — `Map` already preserves it but we keep
+     * an explicit list for tests / iteration clarity. */
+    private readonly toolOrder;
+    private errorText;
+    constructor(taskId: string, turnId: string, messageId: string, startedAt?: number);
+    /** Convenience constructor mirroring SessionManager call sites. */
+    static start(opts: {
+        taskId: string;
+        turnId: string;
+        messageId: string;
+        now?: number;
+    }): InFlightTurnAggregator;
+    /** Append a text delta to the in-flight reply. Empty deltas are no-ops. */
+    appendText(delta: string): void;
+    /** Read-only snapshot of the accumulated text — used by load-replay. */
+    currentText(): string;
+    /** Read-only ordered list of tool calls — used by load-replay. */
+    currentToolCalls(): readonly InFlightToolCall[];
+    noteToolStart(opts: {
+        id: string;
+        name: string;
+        args: unknown;
+        now?: number;
+    }): void;
+    noteToolUpdate(opts: {
+        id: string;
+        output?: string;
+    }): void;
+    noteToolEnd(opts: {
+        id: string;
+        output?: string;
+        isError?: boolean;
+        now?: number;
+    }): void;
+    /** Capture terminal error text from a `task:notice level=error`. */
+    noteFatalNotice(text: string): void;
+    /** Whether anything would actually be persisted on finalize. */
+    isEmpty(): boolean;
+    /** Produce the immutable record ready for JSONL append + replay. */
+    finalize(stopReason: StopReason, now?: number): AssistantTurnRecord;
+}

package/dist/app/in-flight-turn.js

@@ -0,0 +1,158 @@
+/**
+ * In-flight assistant turn aggregator.
+ *
+ * A single ACP `session/prompt` produces a stream of host events
+ * (`task:text` deltas, `task:tool` start/update/end, etc.). Persisting
+ * each delta as a separate row produces unusable transcripts on reload
+ * — the resulting bubble is fragmented into dozens of tiny rows with
+ * no clean way to reconstruct what the agent actually said. To match
+ * OpenClaw's "one JSONL line = one complete assistant turn" model, we
+ * accumulate the delta stream in memory here and only commit a single
+ * `AssistantTurnRecord` when the turn terminates.
+ *
+ * Lifecycle:
+ *   - `start(...)` — called from `task:start`, allocates a buffer.
+ *   - `appendText(delta)` / `noteToolStart` / `noteToolUpdate` /
+ *     `noteToolEnd` — accumulate during the turn.
+ *   - `noteFatalNotice(text)` — capture terminal error text so the
+ *     persisted turn carries an `error` field even if the agent's
+ *     final reply is empty.
+ *   - `finalize(stopReason)` — return an immutable
+ *     `AssistantTurnRecord` ready to be appended to JSONL and emitted
+ *     to the client. Caller resets the buffer afterwards.
+ *
+ * This module is pure data + state machine — no IO, no notifications.
+ * SessionManager owns the IO + dispatch side.
+ */
+/**
+ * Mutable in-flight buffer. Construct once per turn via
+ * `InFlightTurnAggregator.start(...)`, accumulate, then `finalize()`.
+ */
+export class InFlightTurnAggregator {
+    taskId;
+    turnId;
+    messageId;
+    startedAt;
+    text = "";
+    toolCalls = new Map();
+    /** Insertion order tracker — `Map` already preserves it but we keep
+     * an explicit list for tests / iteration clarity. */
+    toolOrder = [];
+    errorText;
+    constructor(taskId, turnId, messageId, startedAt = Date.now()) {
+        this.taskId = taskId;
+        this.turnId = turnId;
+        this.messageId = messageId;
+        this.startedAt = startedAt;
+    }
+    /** Convenience constructor mirroring SessionManager call sites. */
+    static start(opts) {
+        return new InFlightTurnAggregator(opts.taskId, opts.turnId, opts.messageId, opts.now ?? Date.now());
+    }
+    /** Append a text delta to the in-flight reply. Empty deltas are no-ops. */
+    appendText(delta) {
+        if (!delta)
+            return;
+        this.text += delta;
+    }
+    /** Read-only snapshot of the accumulated text — used by load-replay. */
+    currentText() {
+        return this.text;
+    }
+    /** Read-only ordered list of tool calls — used by load-replay. */
+    currentToolCalls() {
+        return this.toolOrder.map((id) => this.toolCalls.get(id)).filter(Boolean);
+    }
+    noteToolStart(opts) {
+        if (this.toolCalls.has(opts.id)) {
+            // Re-issued start (rare — agent core sometimes replays). Reset
+            // to the new args/name but preserve insertion order.
+            this.toolCalls.set(opts.id, {
+                id: opts.id,
+                name: opts.name,
+                args: opts.args,
+                status: "in_progress",
+                startedAt: opts.now ?? Date.now(),
+            });
+            return;
+        }
+        this.toolCalls.set(opts.id, {
+            id: opts.id,
+            name: opts.name,
+            args: opts.args,
+            status: "in_progress",
+            startedAt: opts.now ?? Date.now(),
+        });
+        this.toolOrder.push(opts.id);
+    }
+    noteToolUpdate(opts) {
+        const existing = this.toolCalls.get(opts.id);
+        if (!existing)
+            return;
+        if (opts.output !== undefined)
+            existing.output = opts.output;
+        // status stays "in_progress" — terminal status comes via noteToolEnd.
+    }
+    noteToolEnd(opts) {
+        const existing = this.toolCalls.get(opts.id);
+        if (!existing) {
+            // End-without-start (some adapters skip the start hook). Synthesise a
+            // record so we don't lose the terminal state.
+            this.toolCalls.set(opts.id, {
+                id: opts.id,
+                name: opts.id,
+                args: {},
+                status: opts.isError ? "failed" : "completed",
+                output: opts.output,
+                startedAt: opts.now ?? Date.now(),
+                endedAt: opts.now ?? Date.now(),
+            });
+            this.toolOrder.push(opts.id);
+            return;
+        }
+        existing.status = opts.isError ? "failed" : "completed";
+        if (opts.output !== undefined)
+            existing.output = opts.output;
+        existing.endedAt = opts.now ?? Date.now();
+    }
+    /** Capture terminal error text from a `task:notice level=error`. */
+    noteFatalNotice(text) {
+        if (text)
+            this.errorText = text;
+    }
+    /** Whether anything would actually be persisted on finalize. */
+    isEmpty() {
+        return this.text.length === 0 && this.toolOrder.length === 0 && !this.errorText;
+    }
+    /** Produce the immutable record ready for JSONL append + replay. */
+    finalize(stopReason, now = Date.now()) {
+        const toolCalls = this.toolOrder.map((id) => {
+            const tc = this.toolCalls.get(id);
+            const out = {
+                id: tc.id,
+                name: tc.name,
+                args: tc.args,
+                status: tc.status,
+                startedAt: tc.startedAt,
+            };
+            if (tc.output !== undefined)
+                out.output = tc.output;
+            if (tc.endedAt !== undefined)
+                out.endedAt = tc.endedAt;
+            return out;
+        });
+        const record = {
+            messageId: this.messageId,
+            turnId: this.turnId,
+            startedAt: this.startedAt,
+            completedAt: now,
+            text: this.text,
+            toolCalls,
+            stopReason,
+        };
+        if (this.errorText)
+            record.error = this.errorText;
+        return record;
+    }
+}
+//# sourceMappingURL=in-flight-turn.js.map

package/dist/app/in-flight-turn.js.map

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

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

@@ -0,0 +1,109 @@
+/**
+ * Append-only JSONL persistence layer for `MessageStore`.
+ *
+ * Layout (one file per session, plus one metadata file):
+ *
+ *   ${BEEOS_HOME ?? ~/.beeos}/device-agent/sessions/
+ *     ├── <sid>.jsonl          # append-only record log
+ *     └── <sid>.meta.json      # { sessionId, title, createdAt, updatedAt }
+ *
+ * Each JSONL line is a serialised `PersistedRecord` (see message-store.ts):
+ *
+ *   {"v":1,"type":"user_message","id":"...","ts":...,"content":"...","turnId":"...","messageId":"..."}
+ *   {"v":1,"type":"assistant_turn","id":"...","ts":...,"messageId":"...","turnId":"...",
+ *    "startedAt":...,"completedAt":...,"text":"...","toolCalls":[...],"stopReason":"...","error":"..."}
+ *
+ * IO strategy:
+ *
+ *   - Appends use `fs.writeSync` against a long-lived FD opened in
+ *     append mode (`O_APPEND`). Sync IO sidesteps the buffer-flush
+ *     race that bites WriteStream-based rotation (`clearSession`
+ *     followed immediately by a new append). The blocking cost is
+ *     negligible at our message rate (1-2 records per ~5-10s task).
+ *   - `O_APPEND` guarantees every kernel write seeks to EOF
+ *     atomically, so concurrent appenders on the same file (rare —
+ *     would only happen if two device-agent siblings shared a
+ *     sessions dir) never interleave a single line.
+ *
+ * Crash semantics:
+ *
+ *   - Each write hits disk before the call returns; finalised turns
+ *     survive an unclean shutdown. The user-selected `memory_only`
+ *     in-flight policy means a turn that hadn't yet reached `task:end`
+ *     is lost — that's expected.
+ *   - Reads tolerate partial / corrupt tail lines (the writer might
+ *     have died mid-line on a previous run) by skipping any line that
+ *     fails to parse. Same convention as beeos-claw's
+ *     `LocalSessionHistory.readEntries`.
+ */
+import { MessageStore, type MessageStoreOptions, type PersistedAssistantTurn, type UserMessageRecord } from "./message-store.js";
+import type { AssistantTurnRecord } from "./in-flight-turn.js";
+export interface JsonlMessageStoreOptions extends MessageStoreOptions {
+    /** Directory where `<sid>.jsonl` and `<sid>.meta.json` live. */
+    sessionsDir: string;
+    /**
+     * Specific sids to preload eagerly. Optional — when omitted, the
+     * store scans `sessionsDir` for every `*.jsonl` file. Production
+     * callers (single-session device-agent) pass the fixed sid here so
+     * `open` is O(1) regardless of how many other sids share the dir.
+     */
+    preloadSids?: readonly string[];
+    /** Logger — only used to warn on parse failures. Optional. */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Persistent variant of `MessageStore` — every append is mirrored to a
+ * per-session JSONL log, every metadata change debounced into
+ * `<sid>.meta.json`.
+ *
+ * Construct via `JsonlMessageStore.open(...)` so the on-disk state can
+ * be loaded into memory before any reads happen.
+ */
+export declare class JsonlMessageStore extends MessageStore {
+    private readonly sessionsDir;
+    private readonly logger?;
+    /** Lazily-opened append-mode FDs keyed by sessionId. */
+    private readonly fds;
+    private readonly metaTimers;
+    private closed;
+    private constructor();
+    /** Construct and load on-disk state into memory. */
+    static open(opts: JsonlMessageStoreOptions): Promise<JsonlMessageStore>;
+    /** Path of the JSONL transcript for a given sid. */
+    private sessionFile;
+    /** Path of the metadata file for a given sid. */
+    private metaFile;
+    /** Discover every sid present on disk by scanning `*.jsonl` files. */
+    private discoverSids;
+    /**
+     * Read the JSONL for a sid into memory. Skips rows that fail to
+     * parse (truncated tail line on a previous crash, schema mismatch
+     * from a future version, etc.) so a single bad row doesn't sink the
+     * whole session.
+     */
+    private preloadSession;
+    private readMeta;
+    private getOrCreateFd;
+    appendUserMessage(sessionId: string, content: string, opts?: {
+        turnId?: string;
+        messageId?: string;
+        now?: number;
+    }): UserMessageRecord;
+    appendAssistantTurn(sessionId: string, turn: AssistantTurnRecord, opts?: {
+        now?: number;
+    }): PersistedAssistantTurn;
+    upsertSession(sessionId: string, title?: string): void;
+    renameSession(sessionId: string, title: string): void;
+    clearSession(sessionId: string): void;
+    deleteSession(sessionId: string): void;
+    /** Flush every pending meta write and close every open FD. */
+    close(): Promise<void>;
+    private writeJsonlLine;
+    private closeFd;
+    private rotateStream;
+    private scheduleMetaWrite;
+    private snapshotMeta;
+    private writeMetaNow;
+}