@beeos-ai/device-agent 0.4.0

package/dist/agent.js

@@ -0,0 +1,162 @@
+/**
+ * @deprecated since v0.3.0 — use `AgentRunner` from `agent-runtime/agent-runner.ts`
+ * (or the `AgentRunnerCore` adapter at `adapters/agentcore-runner.ts` for
+ * embedders that need an `IAgentCore`). This shim only exists so that
+ * `InnerLoopVlm`, the legacy `api.ts` HTTP debug server, and external
+ * test embedders keep working without changes — new call sites must NOT
+ * reach for this class.
+ *
+ * Migration sketch:
+ *
+ * ```typescript
+ * // Before (v0.2.x)
+ * const a = new Agent(modelClient, device);
+ * const r = await a.run(task, { onStep, signal });
+ *
+ * // After (v0.3.0+)
+ * const adapter = new OpenAIAdapter({ client: modelClient, lang: "cn" });
+ * const mcp = new InProcMcpClient(device);
+ * const runner = new AgentRunner({ task, env: "mobile", mcp, adapter });
+ * const r = await runner.run();
+ * ```
+ *
+ * Legacy `Agent` — backwards-compatible shim around the new `AgentLoop`.
+ *
+ * Pre-monorepo this class hosted a hand-rolled screenshot → reason → act
+ * loop. The loop has now moved into `agent-runtime/core.AgentLoop`, which is
+ * Plan-Act-Reflect-aware, drives any `IMcpRuntime`, and wires every model
+ * through an `IModelAdapter`. This file keeps the original constructor
+ * signature, public methods, hook payload shapes, and termination strings so
+ * that `InnerLoopVlm`, `api.ts`, the `agent-hooks` test suite, and any
+ * external embedder continue to work without changes.
+ *
+ * Internally a fresh `AgentLoop` is constructed for each `run()` call. The
+ * device handed to the constructor is wrapped in `InProcMcpClient` (no HTTP
+ * hop), and the `ModelClient` is wrapped in `OpenAIAdapter` (the adapter
+ * that already translates legacy `ParsedAction` outputs onto the new unified
+ * `Action` schema, preserving coordinate-system metadata for AgentLoop's
+ * scaling layer).
+ *
+ * The shim is intentionally thin — anything new (waitForUser, reflection
+ * hooks, custom adapters, alternate envs) should go straight to `AgentLoop`
+ * (or `AgentRunner` for the Hybrid Plan-Act path).
+ */
+import { InProcMcpClient } from "./mcp-client/inproc.js";
+import { OpenAIAdapter } from "./agent-runtime/adapters/openai.js";
+import { AgentLoop } from "./agent-runtime/core.js";
+/** @deprecated since v0.3.0 — use `AgentRunner` instead. */
+export class Agent {
+    modelClient;
+    cfg;
+    mcp;
+    adapter;
+    constructor(modelClient, device, config = {}) {
+        this.modelClient = modelClient;
+        this.cfg = {
+            maxSteps: config.maxSteps ?? 30,
+            lang: config.lang ?? "cn",
+            verbose: config.verbose ?? true,
+        };
+        this.mcp = new InProcMcpClient(device);
+        this.adapter = new OpenAIAdapter({
+            client: modelClient,
+            lang: this.cfg.lang,
+        });
+        if (this.cfg.verbose) {
+            console.log(`[Agent] model=${modelClient.modelName} adapter=${modelClient.adapterName} lang=${this.cfg.lang}`);
+        }
+    }
+    async run(task, opts = {}) {
+        const stepCap = opts.maxSteps ?? this.cfg.maxSteps;
+        if (opts.signal?.aborted) {
+            return { finalText: "Task cancelled", steps: 0, cancelled: true };
+        }
+        const loop = new AgentLoop({
+            task,
+            env: "mobile",
+            mcp: this.mcp,
+            adapter: this.adapter,
+            maxSteps: stepCap,
+            signal: opts.signal,
+            hooks: {
+                onText: opts.onText,
+                onStep: opts.onStep
+                    ? async (event) => {
+                        await opts.onStep(legacyStepRecord(event));
+                    }
+                    : undefined,
+            },
+        });
+        const result = await loop.run();
+        let finalText = result.finalText;
+        if (result.terminator === "step_budget") {
+            finalText = "Max steps reached";
+        }
+        else if (result.terminator === "cancelled") {
+            finalText = result.finalText || "Task cancelled";
+        }
+        return {
+            finalText,
+            steps: result.steps,
+            cancelled: result.cancelled,
+        };
+    }
+    /**
+     * Legacy hook — clears any rolling adapter context so the next `run()`
+     * starts fresh. The new `AgentLoop` already isolates state per run, so
+     * this only matters if callers reach into the adapter directly.
+     */
+    reset() {
+        void this.adapter.close?.();
+    }
+    /** Internal — kept for backwards compatibility with embedders that peek. */
+    get model() {
+        return this.modelClient;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Translation: AgentStepEvent → legacy AgentStepRecord                       */
+/* -------------------------------------------------------------------------- */
+function legacyStepRecord(event) {
+    const action = event.action;
+    const legacyType = action.payload?._legacyType ?? action.type;
+    return {
+        index: event.index,
+        thinking: event.rationale,
+        action: action ? { actionType: legacyType, params: paramsFromAction(action) } : null,
+        finished: event.finished,
+        message: event.finished ? extractFinalMessage(action) : null,
+    };
+}
+function paramsFromAction(action) {
+    const out = {};
+    if (action.target?.kind === "point") {
+        out.x = action.target.x;
+        out.y = action.target.y;
+    }
+    else if (action.target?.kind === "box") {
+        out.start_x = action.target.x1;
+        out.start_y = action.target.y1;
+        out.end_x = action.target.x2;
+        out.end_y = action.target.y2;
+    }
+    else if (action.target?.kind === "text") {
+        out.text = action.target.value;
+    }
+    else if (action.target?.kind === "selector") {
+        out.selector = action.target.value;
+    }
+    for (const [k, v] of Object.entries(action.payload ?? {})) {
+        if (k.startsWith("_"))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+function extractFinalMessage(action) {
+    const msg = action.payload?.message;
+    if (typeof msg === "string" && msg.length > 0)
+        return msg;
+    return null;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/api.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public API — `mobileUse` (legacy, harness-only).
+ *
+ * **NOT exported from `index.ts`.** This entry point predates the
+ * `IAgentCore` / `AgentHost` plugin architecture and is kept on disk
+ * solely so the existing one-shot harness scripts (`test-mobile-use.ts`,
+ * `test-mem.ts`) keep compiling. Production paths reach the same inner
+ * VLM through `InnerLoopVlm` (single-layer / `legacyInner`) or the
+ * `mobile_use` pi extension via `PiOrchestratorAgent` (two-layer default).
+ *
+ * Internally we go through `InnerLoopVlm` so this file no longer
+ * duplicates the OpenAIClient construction logic — the loader resolves
+ * `config.mobileUse` from the same env / CLI flags / config-file source
+ * the rest of the agent uses.
+ */
+import type { AgentConfig } from "./agent.js";
+export type { AgentConfig };
+/**
+ * Drive the connected Android phone to complete a natural-language task.
+ *
+ * @param max_steps Maximum VLM steps for this call. When omitted, uses DEFAULT_MAX_STEPS (30).
+ *                  Callers (including outer agents) should explicitly pass this value;
+ *                  only test:mobile reads GUI_AGENT_MAX_STEPS from env as a convenience.
+ *
+ * @internal — use `bootstrap()` or `InnerLoopVlm` directly in production code.
+ */
+export declare function mobileUse(task: string, max_steps?: number): Promise<string>;

package/dist/api.js

@@ -0,0 +1,48 @@
+/**
+ * Public API — `mobileUse` (legacy, harness-only).
+ *
+ * **NOT exported from `index.ts`.** This entry point predates the
+ * `IAgentCore` / `AgentHost` plugin architecture and is kept on disk
+ * solely so the existing one-shot harness scripts (`test-mobile-use.ts`,
+ * `test-mem.ts`) keep compiling. Production paths reach the same inner
+ * VLM through `InnerLoopVlm` (single-layer / `legacyInner`) or the
+ * `mobile_use` pi extension via `PiOrchestratorAgent` (two-layer default).
+ *
+ * Internally we go through `InnerLoopVlm` so this file no longer
+ * duplicates the OpenAIClient construction logic — the loader resolves
+ * `config.mobileUse` from the same env / CLI flags / config-file source
+ * the rest of the agent uses.
+ */
+import { AndroidAdbAdapter } from "./adapters/device-android-adb.js";
+import { InnerLoopVlm } from "./adapters/vlm-inner-loop.js";
+import { loadConfig } from "./config/loader.js";
+const DEFAULT_MAX_STEPS = 30;
+/**
+ * Drive the connected Android phone to complete a natural-language task.
+ *
+ * @param max_steps Maximum VLM steps for this call. When omitted, uses DEFAULT_MAX_STEPS (30).
+ *                  Callers (including outer agents) should explicitly pass this value;
+ *                  only test:mobile reads GUI_AGENT_MAX_STEPS from env as a convenience.
+ *
+ * @internal — use `bootstrap()` or `InnerLoopVlm` directly in production code.
+ */
+export async function mobileUse(task, max_steps) {
+    const cfg = loadConfig({});
+    const max = max_steps ?? cfg.maxSteps ?? DEFAULT_MAX_STEPS;
+    const device = new AndroidAdbAdapter({
+        serial: cfg.adbSerial ?? process.env.GUI_AGENT_DEVICE_ID ?? undefined,
+        skipConnectValidation: true,
+    });
+    const opts = {
+        apiKey: cfg.mobileUse.apiKey || cfg.vlmApiKey || undefined,
+        baseUrl: cfg.mobileUse.baseUrl || cfg.vlmBaseUrl || undefined,
+        modelName: cfg.mobileUse.model || cfg.vlmModel || undefined,
+        maxSteps: max,
+        lang: (process.env.GUI_AGENT_LANG ?? "cn"),
+        verbose: process.env.GUI_AGENT_VERBOSE !== "0",
+    };
+    const vlm = new InnerLoopVlm(device, opts);
+    const result = await vlm.runTask({ task, maxSteps: max });
+    return result.finalMessage;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,YAAY,EAA4B,MAAM,8BAA8B,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAKhD,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,SAAkB;IAC9D,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,SAAS,IAAI,GAAG,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IAE3D,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,SAAS;QACrE,qBAAqB,EAAE,IAAI;KAC5B,CAAC,CAAC;IAEH,MAAM,IAAI,GAAwB;QAChC,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,SAAS,IAAI,SAAS;QAC1D,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,OAAO,IAAI,GAAG,CAAC,UAAU,IAAI,SAAS;QAC7D,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI,GAAG,CAAC,QAAQ,IAAI,SAAS;QAC3D,QAAQ,EAAE,GAAG;QACb,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAgB;QACzD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG;KAC/C,CAAC;IACF,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,YAAY,CAAC;AAC7B,CAAC"}

package/dist/app/agent-host.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Application — AgentHostImpl.
+ *
+ * Concrete implementation of the `AgentHost` port. Sits between an
+ * `IAgentCore` (the agent brain) and an arbitrary number of
+ * `AgentPlugin`s (ACP, HTTP debug, agent-sync, custom).
+ *
+ * Responsibilities:
+ *   - assign stable `taskId`s
+ *   - propagate `taskId` (and optional `correlationTag`) into the
+ *     pino correlation context so every log line during a task carries it
+ *   - translate `IAgentCore` callbacks (onText / onReasoning / onTool /
+ *     onStep) into a typed `AgentEvent` union dispatched to all listeners
+ *   - track per-task AbortControllers for `cancel(taskId)`
+ *
+ * The host is intentionally protocol-agnostic: it knows nothing about
+ * ACP `session/update` envelopes, HTTP REST shapes, or A2A. Plugins
+ * own those translations.
+ */
+import { type Logger } from "../logger/index.js";
+import type { IAgentCore } from "../ports/agent-core.js";
+import type { AgentEventListener, AgentHost, SubmitTaskOptions, SubmittedTask } from "../ports/agent-host.js";
+import type { IDeviceIdentity } from "../ports/identity.js";
+import type { DeviceManager } from "./device-manager.js";
+export interface AgentHostOptions {
+    agent: IAgentCore;
+    devices: DeviceManager;
+    identity?: IDeviceIdentity;
+    logger?: Logger;
+    /** Soft cap on inner steps when callers don't provide their own. */
+    defaultMaxSteps?: number;
+    /** Override notice throttle (ms). Tests pin this to 0 to disable. */
+    noticeWarnThrottleMs?: number;
+}
+export declare class AgentHostImpl implements AgentHost {
+    readonly agent: IAgentCore;
+    readonly devices: DeviceManager;
+    readonly identity?: IDeviceIdentity;
+    private readonly log;
+    private readonly defaultMaxSteps;
+    private readonly noticeWarnThrottleMs;
+    private readonly listeners;
+    private readonly tasks;
+    constructor(opts: AgentHostOptions);
+    on(listener: AgentEventListener): () => void;
+    submitTask(prompt: string, opts?: SubmitTaskOptions): SubmittedTask;
+    cancel(taskId: string): boolean;
+    cancelAll(): Promise<void>;
+    private runOne;
+    /**
+     * Translate a structured runtime error into a `task:notice` for the
+     * UI, throttling non-fatal warnings so a 5xx retry storm doesn't
+     * spam the chat. Fatal errors bypass the throttle entirely (the user
+     * needs to see them immediately) and are also injected by the
+     * `task:end with error` branch above as a safety net.
+     */
+    private handleAgentError;
+    private dispatch;
+}

package/dist/app/agent-host.js

@@ -0,0 +1,263 @@
+/**
+ * Application — AgentHostImpl.
+ *
+ * Concrete implementation of the `AgentHost` port. Sits between an
+ * `IAgentCore` (the agent brain) and an arbitrary number of
+ * `AgentPlugin`s (ACP, HTTP debug, agent-sync, custom).
+ *
+ * Responsibilities:
+ *   - assign stable `taskId`s
+ *   - propagate `taskId` (and optional `correlationTag`) into the
+ *     pino correlation context so every log line during a task carries it
+ *   - translate `IAgentCore` callbacks (onText / onReasoning / onTool /
+ *     onStep) into a typed `AgentEvent` union dispatched to all listeners
+ *   - track per-task AbortControllers for `cancel(taskId)`
+ *
+ * The host is intentionally protocol-agnostic: it knows nothing about
+ * ACP `session/update` envelopes, HTTP REST shapes, or A2A. Plugins
+ * own those translations.
+ */
+import { randomUUID } from "node:crypto";
+import { getLogger, runWithCorrelation } from "../logger/index.js";
+/**
+ * Minimum gap between consecutive `task:notice` (level=warn) events for a
+ * single task. ARouter / VLM 5xx storms can trigger `onError` dozens of
+ * times per second; without this throttle the chat would fill up with
+ * "Model temporarily unavailable…" lines. Fatal errors and the final
+ * `task:end` notice bypass this throttle.
+ */
+const NOTICE_WARN_THROTTLE_MS = 5_000;
+export class AgentHostImpl {
+    agent;
+    devices;
+    identity;
+    log;
+    defaultMaxSteps;
+    noticeWarnThrottleMs;
+    listeners = new Set();
+    tasks = new Map();
+    constructor(opts) {
+        this.agent = opts.agent;
+        this.devices = opts.devices;
+        this.identity = opts.identity;
+        this.log = opts.logger ?? getLogger();
+        this.defaultMaxSteps = opts.defaultMaxSteps ?? 30;
+        this.noticeWarnThrottleMs = opts.noticeWarnThrottleMs ?? NOTICE_WARN_THROTTLE_MS;
+    }
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    submitTask(prompt, opts = {}) {
+        const taskId = randomUUID();
+        // We deliberately keep `turnId` distinct from `taskId` at the type
+        // level even though we mirror them 1:1 today — see AgentEvent docs.
+        const turnId = taskId;
+        // One task = one logical agent message. All chunk / thought / tool /
+        // notice events stamp this id onto the envelope so chat-store's
+        // sidecar resolver pins them to the same assistant bubble.
+        const messageId = randomUUID();
+        const controller = new AbortController();
+        if (opts.abortSignal) {
+            if (opts.abortSignal.aborted)
+                controller.abort();
+            else
+                opts.abortSignal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+        const correlation = {
+            taskId,
+            ...(opts.correlationTag ? { sessionId: opts.correlationTag } : {}),
+        };
+        const done = runWithCorrelation(correlation, () => this.runOne(taskId, turnId, messageId, prompt, controller.signal, opts.maxSteps));
+        this.tasks.set(taskId, {
+            taskId,
+            turnId,
+            messageId,
+            controller,
+            done,
+            lastWarnNoticeAt: 0,
+            fatalNoticeDispatched: false,
+        });
+        void done.finally(() => {
+            this.tasks.delete(taskId);
+        });
+        return {
+            taskId,
+            done,
+            cancel: () => this.cancel(taskId),
+        };
+    }
+    cancel(taskId) {
+        const t = this.tasks.get(taskId);
+        if (!t)
+            return false;
+        if (t.controller.signal.aborted)
+            return false;
+        t.controller.abort();
+        return true;
+    }
+    async cancelAll() {
+        for (const t of this.tasks.values()) {
+            if (!t.controller.signal.aborted)
+                t.controller.abort();
+        }
+        await Promise.allSettled(Array.from(this.tasks.values()).map((t) => t.done));
+    }
+    // ── Internal ───────────────────────────────────────────────────────────────
+    async runOne(taskId, turnId, messageId, prompt, signal, maxSteps) {
+        const createdAt = Date.now();
+        await this.dispatch({ type: "task:start", taskId, turnId, prompt, createdAt });
+        let result;
+        let error;
+        try {
+            result = await this.agent.run({
+                task: prompt,
+                maxSteps: maxSteps ?? this.defaultMaxSteps,
+                abortSignal: signal,
+                onText: async (text) => {
+                    if (!text)
+                        return;
+                    await this.dispatch({ type: "task:text", taskId, turnId, messageId, text });
+                },
+                onReasoning: async (text) => {
+                    if (!text)
+                        return;
+                    await this.dispatch({ type: "task:reasoning", taskId, turnId, messageId, text });
+                },
+                onTool: async (tool) => {
+                    await this.dispatch({ type: "task:tool", taskId, turnId, messageId, tool });
+                },
+                onStep: async (step) => {
+                    await this.dispatch({ type: "task:step", taskId, turnId, messageId, step });
+                },
+                onError: async (err) => {
+                    await this.handleAgentError(taskId, err);
+                },
+            });
+        }
+        catch (e) {
+            error = e;
+            this.log.warn({ err: error.message, taskId }, "agent-host: task failed");
+            result = {
+                finalMessage: error.message ?? String(error),
+                steps: 0,
+                cancelled: signal.aborted,
+            };
+        }
+        // Surface terminal failure to the user *before* `task:end` so the
+        // chat shows "Task failed: …" instead of going silent. Cancellation
+        // is intentionally NOT translated into a notice — the UI already
+        // shows the cancel acknowledgement, and a duplicated error bubble
+        // there feels punitive.
+        //
+        // Dedup safety net: when the agent's own `onError` already routed a
+        // fatal notice through `handleAgentError` (e.g. inner `AgentLoop`
+        // fired `STEP_BUDGET` / `TIMEOUT` / `MODEL_FAIL` with `fatal=true`),
+        // skip the redundant emission here. Without this guard the UI shows
+        // BOTH "Task failed: agent exceeded 94220ms budget" (from onError)
+        // AND a second "Task failed: …" capsule (from this fallback) — which
+        // is exactly the double-TIMEOUT + double-error-text mess the user
+        // hit on the calculator session.
+        const tInfo = this.tasks.get(taskId);
+        if (error && !signal.aborted && !tInfo?.fatalNoticeDispatched) {
+            if (tInfo)
+                tInfo.fatalNoticeDispatched = true;
+            await this.dispatch({
+                type: "task:notice",
+                taskId,
+                turnId,
+                messageId,
+                level: "error",
+                text: `Task failed: ${error.message ?? String(error)}`,
+            });
+        }
+        const ev = {
+            type: "task:end",
+            taskId,
+            turnId,
+            result,
+            completedAt: Date.now(),
+            ...(error ? { error: error.message ?? String(error) } : {}),
+        };
+        await this.dispatch(ev);
+        return result;
+    }
+    /**
+     * Translate a structured runtime error into a `task:notice` for the
+     * UI, throttling non-fatal warnings so a 5xx retry storm doesn't
+     * spam the chat. Fatal errors bypass the throttle entirely (the user
+     * needs to see them immediately) and are also injected by the
+     * `task:end with error` branch above as a safety net.
+     */
+    async handleAgentError(taskId, err) {
+        const t = this.tasks.get(taskId);
+        if (!t)
+            return;
+        const level = err.fatal ? "error" : "warn";
+        if (level === "warn" && this.noticeWarnThrottleMs > 0) {
+            const now = Date.now();
+            if (now - t.lastWarnNoticeAt < this.noticeWarnThrottleMs)
+                return;
+            t.lastWarnNoticeAt = now;
+        }
+        // Fatal-notice dedup: at most one error-level notice per task. The
+        // first wins (typically the structured `STEP_BUDGET` / `TIMEOUT` /
+        // `MODEL_FAIL` from the inner AgentLoop). Subsequent fatal errors
+        // for the same task collapse silently — the `task:end` envelope
+        // still carries the final error string for log / audit consumers.
+        if (level === "error") {
+            if (t.fatalNoticeDispatched)
+                return;
+            t.fatalNoticeDispatched = true;
+        }
+        const text = err.fatal
+            ? formatFatalNoticeText(err)
+            : `Model temporarily unavailable, retrying… (${err.code})`;
+        await this.dispatch({
+            type: "task:notice",
+            taskId,
+            turnId: t.turnId,
+            messageId: t.messageId,
+            level,
+            text,
+        });
+    }
+    async dispatch(event) {
+        if (this.listeners.size === 0)
+            return;
+        for (const listener of Array.from(this.listeners)) {
+            try {
+                await listener(event);
+            }
+            catch (e) {
+                this.log.warn({ err: e.message, eventType: event.type }, "agent-host: listener threw");
+            }
+        }
+    }
+}
+/**
+ * Pick a user-friendly notice string for a fatal `AgentCoreRunError`.
+ *
+ * Some structured codes carry awkward / contradictory wording when shown
+ * after a successful-looking final reply. In particular `STEP_BUDGET`'s
+ * raw message is `hit step budget 20`, which paired with the agent's own
+ * "任务已经完成" line reads as "all done — also failed". The user-visible
+ * footer benefits from a calmer, more descriptive phrasing.
+ *
+ * Mapping:
+ *   - `STEP_BUDGET`  → `Reached max steps (N)` (extracts N from message)
+ *   - `TIMEOUT`      → `Task timed out`
+ *   - any other code → falls back to `Task failed: …` (preserves the
+ *                      structured message for debugging-style codes
+ *                      like `MODEL_FAIL` / `MCP_ACT_FAILED`).
+ */
+function formatFatalNoticeText(err) {
+    if (err.code === "STEP_BUDGET") {
+        const m = /(\d+)/.exec(err.message ?? "");
+        return m ? `Reached max steps (${m[1]})` : "Reached max steps";
+    }
+    if (err.code === "TIMEOUT")
+        return "Task timed out";
+    return `Task failed: ${err.message || err.code}`;
+}
+//# sourceMappingURL=agent-host.js.map

package/dist/app/agent-host.js.map

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

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+import type { IDevice, DeviceInfo } from "../ports/device.js";
+export interface DeviceRegistration {
+    /** Stable id for the device — defaults to `info.name` or `default`. */
+    id: string;
+    device: IDevice;
+    info?: DeviceInfo;
+}
+export declare class DeviceManager {
+    private readonly devices;
+    private activeId;
+    /** Register and connect a device. Returns the canonical id used. */
+    register(device: IDevice, id?: string): Promise<DeviceRegistration>;
+    list(): DeviceRegistration[];
+    get(id?: string): DeviceRegistration | undefined;
+    active(): IDevice;
+    setActive(id: string): void;
+    disconnectAll(): Promise<void>;
+    /** Quick liveness probe; returns true iff device.getInfo() resolves. */
+    healthCheck(id?: string): Promise<boolean>;
+}