@beeos-ai/device-agent 0.4.0

package/dist/model/image/transport.js

@@ -0,0 +1,154 @@
+/**
+ * ImageTransport — strategy abstraction for delivering a compressed VLM
+ * image to the model.
+ *
+ *   bytes ──▶ Transport ──▶ ImageRef
+ *
+ * Two concrete strategies live in the codebase:
+ *   - `DataUrlTransport`  (Phase A) → inline `data:<mime>;base64,...`
+ *   - `HttpUrlTransport`  (Phase B) → presign + PUT to S3, return signed
+ *                                     GET URL
+ *
+ * `FallbackTransport` composes any two strategies so production traffic
+ * can be configured to "prefer http-url, gracefully degrade to data-url
+ * on transient upload failure" — keeping a hard correctness floor while
+ * still gaining the body-size win when everything is healthy.
+ */
+import { presignFileUpload, putPresignedBytes, } from "../../adapters/agent-gateway-client.js";
+/**
+ * Inline-base64 transport. Always succeeds (modulo OOM); the body bloat
+ * is bounded only by the input bytes — pair this with `compressForVlm`
+ * upstream to stay below ARouter's 5MB body cap.
+ */
+export class DataUrlTransport {
+    name = "data-url";
+    async send(bytes, mime) {
+        const url = `data:${mime};base64,${bytes.toString("base64")}`;
+        return { kind: "data-url", url, mime };
+    }
+}
+/**
+ * Adapter implementation of `HttpUrlFileClient` that hits the live
+ * Agent Gateway over HTTP/1.1 with Ed25519 auth. Suitable for
+ * production wiring; tests should pass a mock `HttpUrlFileClient`.
+ */
+export class AgentGatewayFileClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    presignFileUpload(args) {
+        return presignFileUpload({
+            agentGatewayUrl: this.opts.agentGatewayUrl,
+            identity: this.opts.identity,
+            fileName: args.fileName,
+            mimeType: args.mimeType,
+            timeoutMs: this.opts.timeoutMs,
+        });
+    }
+    putPresignedBytes(args) {
+        return putPresignedBytes({
+            uploadUrl: args.uploadUrl,
+            bytes: args.bytes,
+            mimeType: args.mimeType,
+            timeoutMs: this.opts.timeoutMs,
+        });
+    }
+}
+/**
+ * Resource-link transport — pre-signs an S3/MinIO PUT URL via Agent
+ * Gateway, uploads the (already-compressed) image bytes, and returns
+ * the paired pre-signed GET URL as an `kind: "http-url"` `ImageRef`.
+ *
+ * Why this exists:
+ *
+ *   - ARouter / Cloudfront / nginx in front of `llama.cpp` cap request
+ *     bodies at ≈5 MB. A raw 1080×1920 PNG screenshot base64-encoded
+ *     in a chat-completion message routinely overflows that cap, so
+ *     the only robust path for production traffic is to ship a URL,
+ *     not bytes.
+ *   - `llama.cpp`'s vision server fetches `image_url`s natively
+ *     (subject to its own ≈10 MB / 10 s download caps), making this a
+ *     transport-only change — no model-side adapter rewrite required.
+ *
+ * Errors:
+ *   - Both steps surface `AgentGatewayError`. Compose with
+ *     `FallbackTransport(http, data)` if the caller wants a graceful
+ *     degradation to inline base64 on transient upload failure.
+ *
+ * Body sigv4 caveat: the `Content-Type` MUST equal what was passed at
+ * presign time, otherwise S3 returns 403 (signature mismatch). We
+ * forward `mime` to both calls so this is automatic.
+ */
+export class HttpUrlTransport {
+    client;
+    name = "http-url";
+    keyPrefix;
+    randomUUID;
+    now;
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.keyPrefix = opts.keyPrefix ?? "vlm-screenshots/";
+        this.randomUUID = opts.randomUUID ?? (() => globalThis.crypto.randomUUID());
+        this.now = opts.now ?? (() => Date.now());
+    }
+    async send(bytes, mime) {
+        const ext = mime === "image/png" ? "png" : "jpg";
+        const fileName = `${this.keyPrefix}${this.now()}-${this.randomUUID()}.${ext}`;
+        const presigned = await this.client.presignFileUpload({ fileName, mimeType: mime });
+        if (!presigned.uploadUrl) {
+            throw new Error("HttpUrlTransport: presign returned empty uploadUrl");
+        }
+        await this.client.putPresignedBytes({
+            uploadUrl: presigned.uploadUrl,
+            bytes,
+            mimeType: mime,
+        });
+        if (!presigned.downloadUrl) {
+            // Local dev (LocalStore) returns no presigned GET URL. We refuse
+            // to silently lie here — the caller should compose with a
+            // `FallbackTransport(http, data)` to recover.
+            throw new Error("HttpUrlTransport: backend did not return a downloadUrl (LocalStore mode)");
+        }
+        return { kind: "http-url", url: presigned.downloadUrl, mime };
+    }
+}
+const noopLogger = {
+    warn() {
+        /* no-op */
+    },
+};
+/**
+ * Try `primary`; if it throws, log and fall back to `fallback`. The
+ * second transport's failure propagates to the caller — we never silently
+ * swallow a degraded-mode error.
+ */
+export class FallbackTransport {
+    primary;
+    fallback;
+    name;
+    logger;
+    onFallback;
+    constructor(primary, fallback, opts = {}) {
+        this.primary = primary;
+        this.fallback = fallback;
+        this.name = `fallback(${primary.name}->${fallback.name})`;
+        this.logger = opts.logger ?? noopLogger;
+        this.onFallback = opts.onFallback;
+    }
+    async send(bytes, mime) {
+        try {
+            return await this.primary.send(bytes, mime);
+        }
+        catch (err) {
+            this.logger.warn("image transport fell back", {
+                primary: this.primary.name,
+                fallback: this.fallback.name,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            this.onFallback?.(err);
+            return await this.fallback.send(bytes, mime);
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/model/image/transport.js.map

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

package/dist/orchestrator-system-prompt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Outer orchestrator system prompts (pi-coding-agent).
+ * Per-tool details live in tool `description` / schema, not here.
+ * Select via ORCH_LANG env var: "cn" (default) | "en".
+ */
+export declare const ORCHESTRATOR_SYSTEM_PROMPT: string;

package/dist/orchestrator-system-prompt.js

@@ -0,0 +1,81 @@
+/**
+ * Outer orchestrator system prompts (pi-coding-agent).
+ * Per-tool details live in tool `description` / schema, not here.
+ * Select via ORCH_LANG env var: "cn" (default) | "en".
+ */
+const CN = `\
+# Android 手机自动化编排 Agent
+
+> 工具的参数、限制、返回格式在 \`tools\` 载荷里定义，本提示词只讲**策略**。
+
+## 工具选择
+
+| 工具 | 适用场景 |
+|------|----------|
+| \`mobile_use\` | **首选**。大多数任务直接交给它；内部跑 VLM 截图→推理→执行闭环，自主完成多步操作。 |
+| \`ground\` | 需要**精确像素坐标**时：补救 \`mobile_use\` 误触，或配合 adb 手动执行点击。 |
+| \`ui_xml\` | 需要**查看控件树**（resource-id / bounds / clickable）时：调试或确认当前页面状态。 |
+
+## 调用规则
+
+**\`mobile_use\`**
+- 指令写完整、写具体：界面原文、应用名、需要输入的文字（注明"原样输入、不改写"）。
+- 单次调用完成一个连贯子任务；跨 App 的长流程可拆成多次顺序调用。
+- 用 \`max_steps\` 控制步数：**每次调用必须在工具参数里显式传入**（Schema 必填）；简单操作 5–10，复杂流程 20–30。
+- 失败后先分析原因（设备状态、参数、当前界面），不要用相同参数盲目重试。
+
+**\`ground\` / \`ui_xml\`**
+- 典型组合：\`ui_xml\` 找到 resource-id → \`ground\` 定位像素 → adb 执行。
+- 不能替代 \`mobile_use\` 主路径，只在需要原子级精度时介入。
+
+## 多轮对话
+
+记住之前的结论和已执行操作，不必每轮从零确认，除非用户改需求或上下文已变。
+
+## 任务结束
+
+用一两句话总结结果，用中文回复。
+
+## 交流
+
+用户问你是否具备某工具（如 \`mobile_use\`）时，明确回答可否并一句话说明用途；禁止仅用「hi」等无信息回复。
+`;
+const EN = `\
+# Android device orchestration agent
+
+> Tool parameters, limits, and return formats are in the \`tools\` payload. This prompt covers **strategy only**.
+
+## Tool selection
+
+| Tool | When to use |
+|------|-------------|
+| \`mobile_use\` | **Default.** Handles most tasks; runs a VLM screenshot→reason→act loop autonomously. |
+| \`ground\` | When you need **exact pixel coords**: recover from a mis-tap, or feed coords to adb manually. |
+| \`ui_xml\` | When you need the **view hierarchy** (resource-id / bounds / clickable): debug or verify screen state. |
+
+## Calling rules
+
+**\`mobile_use\`**
+- Write instructions in full: exact on-screen labels, app names, verbatim text to type (note "paste verbatim, no paraphrase").
+- One call = one coherent subtask; split cross-app flows into sequential calls.
+- \`max_steps\` is **required on every call** (tool schema); use 5–10 for simple actions, 20–30 for complex flows.
+- On failure: diagnose first (device state, args, current screen). Do not retry with the same call.
+
+**\`ground\` / \`ui_xml\`**
+- Typical pattern: \`ui_xml\` → find resource-id → \`ground\` → pixel coords → adb tap.
+- These are atomic helpers, not replacements for the \`mobile_use\` main path.
+
+## Multi-turn
+
+Retain prior conclusions and actions; do not re-confirm from scratch unless intent or context changed.
+
+## Task completion
+
+Summarize in one or two sentences; match the user's language.
+
+## Communication
+
+If asked whether you can use a tool (e.g. \`mobile_use\`), answer clearly (yes/no) and one sentence on what it does; do not reply with meaningless fillers like "hi" only.
+`;
+export const ORCHESTRATOR_SYSTEM_PROMPT = (process.env.ORCH_LANG ?? "cn") === "en" ? EN : CN;
+//# sourceMappingURL=orchestrator-system-prompt.js.map

package/dist/orchestrator-system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-system-prompt.js","sourceRoot":"","sources":["../src/orchestrator-system-prompt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCV,CAAC;AAEF,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCV,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC"}

package/dist/pi-context.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pi extension context — process-wide service locator that bridges
+ * `PiOrchestratorAgent` (which knows about the sibling `device-mcp-server`,
+ * `config.grounder`, and the `mobile_use` runner) and the
+ * `.pi/extensions/*.ts` files that pi-coding-agent loads on startup.
+ *
+ * Why a singleton?
+ *
+ *  pi-coding-agent's `ExtensionContext` (the value passed to
+ *  `pi.registerTool({ execute })`) is a fixed shape we don't control — it
+ *  holds the session id, abort signal, and update sink, but no slot for
+ *  custom dependency injection. Without this module the only way to reach
+ *  a screenshot from inside an extension was to read `process.env`
+ *  and `new AndroidDevice(...)`, which (a) bypasses the sibling
+ *  `device-mcp-server` (so ACP-driven device switches and out-of-process
+ *  sandboxes are invisible) and (b) bypasses `config.grounder` /
+ *  `config.mobileUse` (so user-supplied URLs and API keys silently lose).
+ *
+ *  The singleton is **scoped to the lifetime of the active
+ *  `PiOrchestratorAgent` session**: the adapter calls
+ *  `setPiExtensionContext(ctx)` immediately before constructing the pi
+ *  session (so `loader.reload()` and the first `prompt()` see a hot
+ *  context) and `setPiExtensionContext(null)` on `dispose()`.
+ *
+ *  Tests and harness scripts that call extensions outside of a pi session
+ *  must call `setPiExtensionContext(...)` themselves; otherwise
+ *  `getPiExtensionContext()` throws so we don't silently fall back to env
+ *  defaults.
+ */
+import type { IMcpRuntime } from "./mcp-client/runtime.js";
+import type { IGrounder } from "./grounding/grounder.js";
+export type { IGrounder };
+export interface PiExtensionContext {
+    /**
+     * Active MCP runtime — typically the sibling `device-mcp-server` HTTP
+     * client. Implementations should re-resolve from the bootstrap layer on
+     * every call so an ACP `device/select` (or autospawn restart) is
+     * reflected immediately on the next tool call.
+     */
+    getMcpClient(): IMcpRuntime;
+    /**
+     * Visual grounder configured from the outer agent's `config.grounder`.
+     * Re-built lazily on first access so the underlying HTTP client is
+     * shared across `ground` invocations within the same session.
+     */
+    getGrounder(): IGrounder;
+    /**
+     * Run the inner mobile_use VLM loop end-to-end. Returns the final
+     * agent message (the same string the legacy `mobileUse(task, maxSteps)`
+     * helper returned). Implementations route through `AgentLoop` over the
+     * sibling MCP server so step/text callbacks reach the outer host.
+     */
+    runMobileUse(task: string, maxSteps: number, abortSignal?: AbortSignal): Promise<string>;
+    /**
+     * Dump the current UI XML, optionally filtered by substring (matches
+     * text / resource-id / content-desc / class name, case-insensitive).
+     * Implementations call `mcp.uiDump({ format: "raw" })` and pass the
+     * result through `formatUiXmlToolOutput`.
+     */
+    getUiXml(query?: string): Promise<string>;
+}
+/**
+ * Install (or clear, when `ctx` is `null`) the context that
+ * `getPiExtensionContext()` resolves. `PiOrchestratorAgent` calls this
+ * before booting the pi session and clears it on dispose.
+ *
+ * Tests / harness scripts that exercise extensions in isolation must
+ * `setPiExtensionContext(stub)` first and clear it on teardown to keep
+ * other tests deterministic.
+ */
+export declare function setPiExtensionContext(ctx: PiExtensionContext | null): void;
+/**
+ * Resolve the active context. Throws when no `PiOrchestratorAgent`
+ * session is in flight — extensions are designed to run inside a pi
+ * session and should never be invoked from cold storage.
+ */
+export declare function getPiExtensionContext(): PiExtensionContext;
+/**
+ * Inspect-without-throw helper. Returns the active context or `null`.
+ * Exposed mainly for diagnostics / debug routes.
+ */
+export declare function peekPiExtensionContext(): PiExtensionContext | null;

package/dist/pi-context.js

@@ -0,0 +1,62 @@
+/**
+ * Pi extension context — process-wide service locator that bridges
+ * `PiOrchestratorAgent` (which knows about the sibling `device-mcp-server`,
+ * `config.grounder`, and the `mobile_use` runner) and the
+ * `.pi/extensions/*.ts` files that pi-coding-agent loads on startup.
+ *
+ * Why a singleton?
+ *
+ *  pi-coding-agent's `ExtensionContext` (the value passed to
+ *  `pi.registerTool({ execute })`) is a fixed shape we don't control — it
+ *  holds the session id, abort signal, and update sink, but no slot for
+ *  custom dependency injection. Without this module the only way to reach
+ *  a screenshot from inside an extension was to read `process.env`
+ *  and `new AndroidDevice(...)`, which (a) bypasses the sibling
+ *  `device-mcp-server` (so ACP-driven device switches and out-of-process
+ *  sandboxes are invisible) and (b) bypasses `config.grounder` /
+ *  `config.mobileUse` (so user-supplied URLs and API keys silently lose).
+ *
+ *  The singleton is **scoped to the lifetime of the active
+ *  `PiOrchestratorAgent` session**: the adapter calls
+ *  `setPiExtensionContext(ctx)` immediately before constructing the pi
+ *  session (so `loader.reload()` and the first `prompt()` see a hot
+ *  context) and `setPiExtensionContext(null)` on `dispose()`.
+ *
+ *  Tests and harness scripts that call extensions outside of a pi session
+ *  must call `setPiExtensionContext(...)` themselves; otherwise
+ *  `getPiExtensionContext()` throws so we don't silently fall back to env
+ *  defaults.
+ */
+let active = null;
+/**
+ * Install (or clear, when `ctx` is `null`) the context that
+ * `getPiExtensionContext()` resolves. `PiOrchestratorAgent` calls this
+ * before booting the pi session and clears it on dispose.
+ *
+ * Tests / harness scripts that exercise extensions in isolation must
+ * `setPiExtensionContext(stub)` first and clear it on teardown to keep
+ * other tests deterministic.
+ */
+export function setPiExtensionContext(ctx) {
+    active = ctx;
+}
+/**
+ * Resolve the active context. Throws when no `PiOrchestratorAgent`
+ * session is in flight — extensions are designed to run inside a pi
+ * session and should never be invoked from cold storage.
+ */
+export function getPiExtensionContext() {
+    if (!active) {
+        throw new Error("PiExtensionContext is not set — pi extensions must run inside a PiOrchestratorAgent session " +
+            "(or call setPiExtensionContext() in tests).");
+    }
+    return active;
+}
+/**
+ * Inspect-without-throw helper. Returns the active context or `null`.
+ * Exposed mainly for diagnostics / debug routes.
+ */
+export function peekPiExtensionContext() {
+    return active;
+}
+//# sourceMappingURL=pi-context.js.map

package/dist/pi-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-context.js","sourceRoot":"","sources":["../src/pi-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA4CH,IAAI,MAAM,GAA8B,IAAI,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA8B;IAClE,MAAM,GAAG,GAAG,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,8FAA8F;YAC5F,6CAA6C,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/pi-local-skills.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceDiagnostic, Skill } from "@mariozechner/pi-coding-agent";
+/**
+ * Pi 默认会从 package manager 收录 ~/.agents/skills、~/.pi/agent/skills、项目 .pi/skills 等。
+ * 这里关闭自动收录（noSkills），只把 `<projectRoot>/.pi/skills` 作为唯一 skill 根目录；
+ * skillsOverride 再兜底过滤，避免 CLI 临时路径混进上下文。
+ */
+export declare function projectPiSkillsLoaderOptions(projectRoot: string): {
+    noSkills: true;
+    additionalSkillPaths: string[];
+    skillsOverride: (current: {
+        skills: Skill[];
+        diagnostics: ResourceDiagnostic[];
+    }) => {
+        skills: Skill[];
+        diagnostics: ResourceDiagnostic[];
+    };
+};

package/dist/pi-local-skills.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+/**
+ * Pi 默认会从 package manager 收录 ~/.agents/skills、~/.pi/agent/skills、项目 .pi/skills 等。
+ * 这里关闭自动收录（noSkills），只把 `<projectRoot>/.pi/skills` 作为唯一 skill 根目录；
+ * skillsOverride 再兜底过滤，避免 CLI 临时路径混进上下文。
+ */
+export function projectPiSkillsLoaderOptions(projectRoot) {
+    const skillsDir = resolve(projectRoot, ".pi", "skills");
+    const additionalSkillPaths = existsSync(skillsDir) ? [skillsDir] : [];
+    const prefix = skillsDir.endsWith(sep) ? skillsDir : `${skillsDir}${sep}`;
+    return {
+        noSkills: true,
+        additionalSkillPaths,
+        skillsOverride: (current) => ({
+            skills: current.skills.filter((s) => {
+                const norm = resolve(s.filePath);
+                return norm === skillsDir || norm.startsWith(prefix);
+            }),
+            diagnostics: current.diagnostics,
+        }),
+    };
+}
+//# sourceMappingURL=pi-local-skills.js.map

package/dist/pi-local-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-local-skills.js","sourceRoot":"","sources":["../src/pi-local-skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGzC;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAQ9D,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxD,MAAM,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC;IAE1E,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,oBAAoB;QACpB,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBACjC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YACvD,CAAC,CAAC;YACF,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/plugins/acp/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin — acp.
+ *
+ * Bridges the device-agent's `AgentHost` to the BeeOS platform via the
+ * Agent Control Protocol (ACP) over a WebSocket transport.
+ *
+ * Responsibilities:
+ *   - Construct `SessionManager` (subscribes to host events).
+ *   - Wire ACP handlers (`session/*`, `device/*`, `models/list`, `skills/list`).
+ *   - Open the Bridge WebSocket, bind the router, fan `session/update`
+ *     notifications back through the transport.
+ *
+ * Disabled when `--standalone` (no remote control plane) or `--no-acp`
+ * is passed; in that mode only the http-debug plugin is useful.
+ */
+import type { IMcpRuntime } from "../../mcp-client/runtime.js";
+import type { IBridgeTransport } from "../../ports/transport.js";
+import type { AgentPlugin, PluginContext } from "../../ports/plugin.js";
+export interface AcpPluginOptions {
+    /**
+     * Lazy MCP-runtime resolver. Invoked once per ACP `device/*` request so
+     * autospawn restarts / device hot-swaps are transparent to the handlers.
+     * Production callers pass through the same `mcpProvider` that the agent
+     * core consumes.
+     */
+    mcpProvider: () => IMcpRuntime;
+    /** Ed25519 identity for the Bridge handshake. */
+    keypair: {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    /** Optional pre-built transport (used by tests for mock injection). */
+    transportOverride?: IBridgeTransport;
+}
+export declare class AcpPlugin implements AgentPlugin {
+    private readonly opts;
+    readonly name = "acp";
+    private ctx?;
+    private transport;
+    private sessions;
+    private unbind;
+    constructor(opts: AcpPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/plugins/acp/index.js

@@ -0,0 +1,111 @@
+/**
+ * Plugin — acp.
+ *
+ * Bridges the device-agent's `AgentHost` to the BeeOS platform via the
+ * Agent Control Protocol (ACP) over a WebSocket transport.
+ *
+ * Responsibilities:
+ *   - Construct `SessionManager` (subscribes to host events).
+ *   - Wire ACP handlers (`session/*`, `device/*`, `models/list`, `skills/list`).
+ *   - Open the Bridge WebSocket, bind the router, fan `session/update`
+ *     notifications back through the transport.
+ *
+ * Disabled when `--standalone` (no remote control plane) or `--no-acp`
+ * is passed; in that mode only the http-debug plugin is useful.
+ */
+import { BridgeWsTransport } from "../../adapters/transport-bridge-ws.js";
+import { MessageStore } from "../../app/message-store.js";
+import { SessionManager } from "../../app/session-manager.js";
+import { AcpDeviceHandlers } from "../../inbound/acp/handlers/device.js";
+import { AcpSessionHandlers } from "../../inbound/acp/handlers/session.js";
+import { AcpRouter, bindRouterToTransport } from "../../inbound/acp/router.js";
+import { TransportSessionNotifier } from "../../inbound/acp/notifier.js";
+export class AcpPlugin {
+    opts;
+    name = "acp";
+    ctx;
+    transport = null;
+    sessions = null;
+    unbind = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async init(ctx) {
+        this.ctx = ctx;
+        const { config, log, host } = ctx;
+        if (config.disableAcp) {
+            log.info("acp: disabled by --no-acp / disableAcp config");
+            return;
+        }
+        if (!config.bridgeUrl) {
+            log.warn("acp: bridgeUrl unset, plugin will not start");
+            return;
+        }
+        const transport = this.opts.transportOverride ??
+            new BridgeWsTransport({
+                bridgeUrl: config.bridgeUrl,
+                service: config.bridgeService,
+                privateKey: this.opts.keypair.privateKey,
+                publicKey: this.opts.keypair.publicKey,
+            });
+        transport.on("connected", () => log.info("acp: bridge connected"));
+        transport.on("disconnected", (reason) => log.warn({ reason }, "acp: bridge disconnected"));
+        transport.on("error", (err) => log.error({ err: err.message }, "acp: bridge transport error"));
+        const notifier = new TransportSessionNotifier(transport);
+        const messageStore = new MessageStore();
+        const sessions = new SessionManager({
+            host,
+            messageStore,
+            notifier,
+            // `Config.sessionTimeoutMs` is the single source of truth for idle GC.
+            // 0 disables the threshold check (effectively keeps sessions forever
+            // until `maxSessions` LRU eviction kicks in) — it's surfaced in the
+            // schema so kiosk deployments can pin a deterministic value.
+            sessionTtlMs: config.sessionTimeoutMs > 0 ? config.sessionTimeoutMs : undefined,
+            onSetModel: async (provider, model) => {
+                try {
+                    await host.agent.setModel(provider, model);
+                    log.info({ provider, model }, "acp: agent model switched");
+                }
+                catch (e) {
+                    log.warn({ err: e.message, provider, model }, "acp: setModel failed");
+                }
+            },
+        });
+        const router = new AcpRouter({
+            device: new AcpDeviceHandlers(this.opts.mcpProvider),
+            session: new AcpSessionHandlers(sessions),
+            log: ({ method, error }) => {
+                if (error)
+                    log.warn({ method, err: error.message }, "acp handler error");
+                else
+                    log.debug({ method }, "acp request");
+            },
+        });
+        this.transport = transport;
+        this.sessions = sessions;
+        this.unbind = bindRouterToTransport(router, transport);
+    }
+    async start() {
+        if (!this.transport)
+            return;
+        await this.transport.connect();
+    }
+    async stop() {
+        if (this.sessions) {
+            this.sessions.detach();
+            this.sessions = null;
+        }
+        if (this.unbind) {
+            try {
+                await this.unbind();
+            }
+            catch {
+                /* ignore */
+            }
+            this.unbind = null;
+        }
+        this.transport = null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/plugins/acp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/acp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAmBzE,MAAM,OAAO,SAAS;IAOS;IANpB,IAAI,GAAG,KAAK,CAAC;IACd,GAAG,CAAiB;IACpB,SAAS,GAA4B,IAAI,CAAC;IAC1C,QAAQ,GAA0B,IAAI,CAAC;IACvC,MAAM,GAAiC,IAAI,CAAC;IAEpD,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD,KAAK,CAAC,IAAI,CAAC,GAAkB;QAC3B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC;QAElC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,GAAG,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;YAC1D,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtB,GAAG,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GACb,IAAI,CAAC,IAAI,CAAC,iBAAiB;YAC3B,IAAI,iBAAiB,CAAC;gBACpB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,aAAa;gBAC7B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU;gBACxC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS;aACvC,CAAC,CAAC;QACL,SAAS,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC;QACnE,SAAS,CAAC,EAAE,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,0BAA0B,CAAC,CAAC,CAAC;QAC3F,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,6BAA6B,CAAC,CAAC,CAAC;QAE/F,MAAM,QAAQ,GAAG,IAAI,wBAAwB,CAAC,SAAS,CAAC,CAAC;QACzD,MAAM,YAAY,GAAG,IAAI,YAAY,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC;YAClC,IAAI;YACJ,YAAY;YACZ,QAAQ;YACR,uEAAuE;YACvE,qEAAqE;YACrE,oEAAoE;YACpE,6DAA6D;YAC7D,YAAY,EAAE,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;YAC/E,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;gBACpC,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;oBAC3C,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,2BAA2B,CAAC,CAAC;gBAC7D,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAG,CAAW,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,sBAAsB,CAAC,CAAC;gBACnF,CAAC;YACH,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;YAC3B,MAAM,EAAE,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;YACpD,OAAO,EAAE,IAAI,kBAAkB,CAAC,QAAQ,CAAC;YACzC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE;gBACzB,IAAI,KAAK;oBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAG,KAAe,CAAC,OAAO,EAAE,EAAE,mBAAmB,CAAC,CAAC;;oBAC/E,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,aAAa,CAAC,CAAC;YAC5C,CAAC;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;CACF"}

package/dist/plugins/agent-sync/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Plugin — agent-sync.
+ *
+ * Posts a single `POST /api/v1/agents/sync` to Agent Gateway during
+ * `start()` so the device-agent appears in the platform's Agents
+ * directory and is discoverable via A2A.
+ *
+ * Failure is non-fatal — sync errors only emit a warning, the device
+ * still serves ACP normally. This keeps ground-truth agent metadata
+ * close to the binary that hosts the actual capabilities, while
+ * allowing development setups (no AGW reachability, no key file)
+ * to keep working.
+ *
+ * Resync semantics:
+ *   - one shot at start (parity with the legacy `main.ts` behavior)
+ *   - if `BEEOS_AGENT_SYNC_INTERVAL_MS` (or the constructor option) is
+ *     set to a positive number, we re-post on that cadence; default off
+ */
+import { type AgentDeclarationInput, type AgentGatewayIdentity } from "../../adapters/agent-gateway-client.js";
+import type { AgentPlugin, PluginContext } from "../../ports/plugin.js";
+export interface AgentSyncOptions {
+    /** Build the AgentDeclaration on demand (called every sync cycle). */
+    buildDeclarations: () => Promise<AgentDeclarationInput[]>;
+    /** Resolve the Ed25519 identity each sync cycle (pulled from FileIdentity). */
+    loadIdentity: () => Promise<AgentGatewayIdentity | null>;
+    /** Cadence for periodic resyncs. 0 / undefined = single shot. */
+    intervalMs?: number;
+}
+export declare class AgentSyncPlugin implements AgentPlugin {
+    private readonly opts;
+    readonly name = "agent-sync";
+    private ctx?;
+    private timer;
+    private stopped;
+    constructor(opts: AgentSyncOptions);
+    init(ctx: PluginContext): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runOnce;
+}