@agent-phonon/server-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-phonon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @agent-phonon/server-sdk
+ *
+ * 让任何项目一键成为 agent-phonon 服务端：管理多设备、编排其上的 agent。
+ */
+export { PhononServer, PhononDevice, PhononSession } from "./server.js";
+export type { PhononServerOptions, HookDecider, SendResult } from "./server.js";
+export { RpcPeer } from "./rpc.js";
+export type { Transport } from "./rpc.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @agent-phonon/server-sdk
+ *
+ * 让任何项目一键成为 agent-phonon 服务端：管理多设备、编排其上的 agent。
+ */
+export { PhononServer, PhononDevice, PhononSession } from "./server.js";
+export { RpcPeer } from "./rpc.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/rpc.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 双向 JSON-RPC 2.0 peer（server 侧，零 core 依赖）。
+ * 每个 device 连接一个。两端皆可作 requester。
+ */
+export interface Transport {
+    send(data: string): void;
+    close(): void;
+}
+export type RpcHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
+export declare class RpcPeer {
+    private transport;
+    private handler;
+    private pending;
+    private nextId;
+    constructor(transport: Transport, handler: RpcHandler);
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    handle(data: string): Promise<void>;
+    rejectAll(reason: string): void;
+}
+export declare function newId(): string;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAQzF,qBAAa,OAAO;IAClB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,MAAM,CAAK;gBAEP,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU;IAKrD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAIvC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCzC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAIhC;AAED,wBAAgB,KAAK,IAAI,MAAM,CAE9B"}

package/dist/rpc.js

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+export class RpcPeer {
+    transport;
+    handler;
+    pending = new Map();
+    nextId = 1;
+    constructor(transport, handler) {
+        this.transport = transport;
+        this.handler = handler;
+    }
+    request(method, params, timeoutMs = 600000) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = timeoutMs > 0 ? setTimeout(() => { this.pending.delete(id); reject(new Error(`rpc timeout: ${method}`)); }, timeoutMs) : undefined;
+            this.pending.set(id, { resolve, reject, timer });
+            this.transport.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+        });
+    }
+    notify(method, params) {
+        this.transport.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+    }
+    async handle(data) {
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        // 响应
+        if (("result" in msg || "error" in msg) && "id" in msg) {
+            const p = this.pending.get(msg.id);
+            if (!p)
+                return;
+            this.pending.delete(msg.id);
+            if (p.timer)
+                clearTimeout(p.timer);
+            if ("error" in msg && msg.error)
+                p.reject(msg.error);
+            else
+                p.resolve(msg.result);
+            return;
+        }
+        // 请求 / 通知
+        if (typeof msg.method === "string") {
+            const isNotification = !("id" in msg) || msg.id === undefined || msg.id === null;
+            try {
+                const result = await this.handler(msg.method, msg.params);
+                if (!isNotification)
+                    this.transport.send(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: result ?? null }));
+            }
+            catch (err) {
+                if (!isNotification) {
+                    this.transport.send(JSON.stringify({
+                        jsonrpc: "2.0", id: msg.id,
+                        error: { code: -32000, message: err?.message ?? "error" },
+                    }));
+                }
+            }
+        }
+    }
+    rejectAll(reason) {
+        for (const [, p] of this.pending) {
+            if (p.timer)
+                clearTimeout(p.timer);
+            p.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}
+export function newId() {
+    return randomUUID();
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,247 @@
+import { EventEmitter } from "node:events";
+import { RpcPeer } from "./rpc.js";
+import type { AgentDescriptor, SessionMeta, StreamEvent, HookFiredParams, HookAction } from "@agent-phonon/protocol";
+/**
+ * agent-phonon Server SDK。
+ *
+ * 让任何项目「一键成为 phonon 服务端」：导入 SDK → 配鉴权 → 监听 device →
+ * 用干净接口（discover / createSession / send / onStream / onHook）编排
+ * 多台设备上的 agent。协议帧/握手/ack/HITL 路由全由 SDK 处理。
+ *
+ * 支持多设备：一个 PhononServer 同时连多个 phonon。
+ */
+export interface SendResult {
+    turnId: string;
+    disposition: string;
+}
+export declare class PhononSession extends EventEmitter {
+    readonly sessionId: string;
+    readonly device: PhononDevice;
+    private lastSeq;
+    constructor(device: PhononDevice, sessionId: string);
+    /** 发任务（结果走 'stream' 事件）。 */
+    send(input: string, opts?: {
+        verbosity?: "final" | "messages" | "tools" | "trace";
+        skills?: string[];
+        whenBusy?: "queue" | "interrupt" | "inject";
+        clientRequestId?: string;
+    }): Promise<SendResult>;
+    inject(context: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>): Promise<unknown>;
+    interrupt(reason?: string): Promise<unknown>;
+    switchModel(model: string): Promise<unknown>;
+    compress(mode?: "native" | "custom"): Promise<unknown>;
+    status(): Promise<SessionMeta>;
+    terminate(): Promise<unknown>;
+    /** 内部：收到本 session 的 stream.event。 */
+    _onStream(ev: StreamEvent): void;
+    /** 本 session 已收到的最大 seq（device 用于 ack）。 */
+    get _lastSeq(): number;
+    on(event: "stream", listener: (ev: StreamEvent) => void): this;
+    on(event: "end", listener: (ev: StreamEvent) => void): this;
+}
+export type HookDecider = (hook: HookFiredParams, session: PhononSession | undefined) => HookAction | {
+    action: HookAction;
+    reason?: string;
+} | Promise<HookAction | {
+    action: HookAction;
+    reason?: string;
+}>;
+export declare class PhononDevice extends EventEmitter {
+    readonly deviceId: string;
+    readonly tenantId: string;
+    private peer;
+    private sessions;
+    private hookDecider?;
+    /** 自发输出（无对应 session 时）回调。 */
+    private onUnsolicited?;
+    constructor(deviceId: string, tenantId: string, peer: RpcPeer);
+    call(method: string, params: unknown): Promise<unknown>;
+    /** 列设备上可用 agent。 */
+    discover(): Promise<AgentDescriptor[]>;
+    /** 建会话。 */
+    createSession(params: {
+        project: string;
+        agent: string;
+        model: string;
+        worktreeId?: string;
+        verbosity?: "final" | "messages" | "tools" | "trace";
+        clientRequestId?: string;
+    }): Promise<PhononSession>;
+    /** 列会话。 */
+    listSessions(filter?: {
+        project?: string;
+        agent?: string;
+        status?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        sessions: SessionMeta[];
+        nextCursor?: string;
+    }>;
+    /** 设备 OS/机器信息，用于 server 做任务调度决策。 */
+    info(): Promise<unknown>;
+    /** 设备资源快照（CPU/内存/磁盘/进程/GPU best-effort）。 */
+    resources(): Promise<unknown>;
+    project: {
+        create: (p: {
+            name: string;
+            path?: string;
+            git?: boolean;
+            remote?: string;
+            clientRequestId?: string;
+        }) => Promise<{
+            project: {
+                projectId: string;
+                path: string;
+            };
+        }>;
+        list: () => Promise<{
+            projects: unknown[];
+        }>;
+        get: (projectId: string) => Promise<unknown>;
+        remove: (projectId: string, opts?: {
+            deleteFiles?: boolean;
+            whenActiveSessions?: "reject" | "cascade";
+        }) => Promise<unknown>;
+        worktree: {
+            create: (p: {
+                projectId: string;
+                baseBranch: string;
+                newBranch?: string;
+                path?: string;
+            }) => Promise<unknown>;
+            list: (projectId: string) => Promise<unknown>;
+            remove: (p: {
+                projectId: string;
+                worktreeId: string;
+                force?: boolean;
+            }) => Promise<unknown>;
+        };
+        deleteBranch: (p: {
+            projectId: string;
+            branch: string;
+            force?: boolean;
+        }) => Promise<unknown>;
+    };
+    env: {
+        set: (p: {
+            scope: "global" | "project" | "skill";
+            projectId?: string;
+            agent?: string;
+            skillName?: string;
+            name: string;
+            value: string;
+            secret?: boolean;
+            clientRequestId?: string;
+        }) => Promise<unknown>;
+        list: (p?: {
+            scope?: "global" | "project" | "skill";
+            projectId?: string;
+            agent?: string;
+            skillName?: string;
+            reveal?: boolean;
+        }) => Promise<unknown>;
+        delete: (p: {
+            scope: "global" | "project" | "skill";
+            projectId?: string;
+            agent?: string;
+            skillName?: string;
+            name: string;
+            clientRequestId?: string;
+        }) => Promise<unknown>;
+    };
+    file: {
+        read: (p: {
+            projectId: string;
+            worktreeId?: string;
+            path: string;
+            encoding?: "utf8" | "base64";
+            maxBytes?: number;
+        }) => Promise<unknown>;
+        write: (p: {
+            projectId: string;
+            worktreeId?: string;
+            path: string;
+            encoding?: "utf8" | "base64";
+            data: string;
+            overwrite?: boolean;
+            createDirs?: boolean;
+            clientRequestId?: string;
+        }) => Promise<unknown>;
+        list: (p: {
+            projectId: string;
+            worktreeId?: string;
+            path?: string;
+            recursive?: boolean;
+            limit?: number;
+        }) => Promise<unknown>;
+        stat: (p: {
+            projectId: string;
+            worktreeId?: string;
+            path: string;
+        }) => Promise<unknown>;
+        mkdir: (p: {
+            projectId: string;
+            worktreeId?: string;
+            path: string;
+            recursive?: boolean;
+            clientRequestId?: string;
+        }) => Promise<unknown>;
+    };
+    skill: {
+        install: (p: {
+            agent: string;
+            name: string;
+            scope: "global" | "project";
+            projectId?: string;
+            source: unknown;
+            clientRequestId?: string;
+        }) => Promise<unknown>;
+        uninstall: (p: {
+            agent: string;
+            name: string;
+            scope: "global" | "project";
+            projectId?: string;
+        }) => Promise<unknown>;
+        list: (filter?: {
+            agent?: string;
+            scope?: "global" | "project";
+            projectId?: string;
+        }) => Promise<unknown>;
+    };
+    /** 设置 HITL 裁决器（device 级，所有 session 共用）。 */
+    setHookDecider(fn: HookDecider): void;
+    /** 设置自发输出回调。 */
+    setUnsolicitedHandler(fn: (ev: StreamEvent) => void): void;
+    /** 内部：处理 phonon → server 的请求/通知。 */
+    _handleInbound(method: string, params: unknown): Promise<unknown>;
+    _onClose(): void;
+}
+export interface PhononServerOptions {
+    port?: number;
+    host?: string;
+    /** 鉴权：返回 tenantId 表示通过，返回 null 拒绝。缺省全部放行（本地测试）。 */
+    authenticate?: (deviceId: string, deviceKey: string | undefined) => {
+        tenantId: string;
+    } | null | Promise<{
+        tenantId: string;
+    } | null>;
+}
+export declare class PhononServer extends EventEmitter {
+    private wss?;
+    private opts;
+    private devices;
+    private actualPort;
+    constructor(opts?: PhononServerOptions);
+    listen(): Promise<number>;
+    get port(): number;
+    /** 当前连接的设备列表。 */
+    listDevices(): PhononDevice[];
+    getDevice(deviceId: string): PhononDevice | undefined;
+    private onConnection;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

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

package/dist/server.js

@@ -0,0 +1,240 @@
+import { EventEmitter } from "node:events";
+import { WebSocketServer, WebSocket } from "ws";
+import { RpcPeer, newId } from "./rpc.js";
+export class PhononSession extends EventEmitter {
+    sessionId;
+    device;
+    lastSeq = -1;
+    constructor(device, sessionId) {
+        super();
+        this.device = device;
+        this.sessionId = sessionId;
+    }
+    /** 发任务（结果走 'stream' 事件）。 */
+    async send(input, opts) {
+        return this.device.call("session.send", { sessionId: this.sessionId, input, ...opts });
+    }
+    inject(context) {
+        return this.device.call("session.inject", { sessionId: this.sessionId, context });
+    }
+    interrupt(reason) {
+        return this.device.call("session.interrupt", { sessionId: this.sessionId, reason });
+    }
+    switchModel(model) {
+        return this.device.call("session.switchModel", { sessionId: this.sessionId, model });
+    }
+    compress(mode = "native") {
+        return this.device.call("session.compress", { sessionId: this.sessionId, mode });
+    }
+    status() {
+        return this.device.call("session.status", { sessionId: this.sessionId });
+    }
+    terminate() {
+        return this.device.call("session.terminate", { sessionId: this.sessionId });
+    }
+    /** 内部：收到本 session 的 stream.event。 */
+    _onStream(ev) {
+        const seq = ev.seq;
+        this.emit("stream", ev);
+        if (ev.final)
+            this.emit("end", ev);
+        if (seq > this.lastSeq)
+            this.lastSeq = seq;
+    }
+    /** 本 session 已收到的最大 seq（device 用于 ack）。 */
+    get _lastSeq() {
+        return this.lastSeq;
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+}
+export class PhononDevice extends EventEmitter {
+    deviceId;
+    tenantId;
+    peer;
+    sessions = new Map();
+    hookDecider;
+    /** 自发输出（无对应 session 时）回调。 */
+    onUnsolicited;
+    constructor(deviceId, tenantId, peer) {
+        super();
+        this.deviceId = deviceId;
+        this.tenantId = tenantId;
+        this.peer = peer;
+    }
+    call(method, params) {
+        return this.peer.request(method, params);
+    }
+    /** 列设备上可用 agent。 */
+    async discover() {
+        const r = (await this.peer.request("discovery.list", {}));
+        return r.agents;
+    }
+    /** 建会话。 */
+    async createSession(params) {
+        const r = (await this.peer.request("session.create", { verbosity: "messages", ...params }));
+        const s = new PhononSession(this, r.sessionId);
+        this.sessions.set(r.sessionId, s);
+        return s;
+    }
+    /** 列会话。 */
+    async listSessions(filter) {
+        return this.peer.request("session.list", filter ?? {});
+    }
+    /** 设备 OS/机器信息，用于 server 做任务调度决策。 */
+    info() {
+        return this.peer.request("device.info", {});
+    }
+    /** 设备资源快照（CPU/内存/磁盘/进程/GPU best-effort）。 */
+    resources() {
+        return this.peer.request("device.resources", {});
+    }
+    // ---- project / file / skill 便捷封装 ----
+    project = {
+        create: (p) => this.peer.request("project.create", p),
+        list: () => this.peer.request("project.list", {}),
+        get: (projectId) => this.peer.request("project.get", { projectId }),
+        remove: (projectId, opts) => this.peer.request("project.remove", { projectId, ...opts }),
+        worktree: {
+            create: (p) => this.peer.request("project.worktree.create", p),
+            list: (projectId) => this.peer.request("project.worktree.list", { projectId }),
+            remove: (p) => this.peer.request("project.worktree.remove", p),
+        },
+        deleteBranch: (p) => this.peer.request("project.git.deleteBranch", p),
+    };
+    env = {
+        set: (p) => this.peer.request("env.set", p),
+        list: (p) => this.peer.request("env.list", p ?? {}),
+        delete: (p) => this.peer.request("env.delete", p),
+    };
+    file = {
+        read: (p) => this.peer.request("file.read", p),
+        write: (p) => this.peer.request("file.write", p),
+        list: (p) => this.peer.request("file.list", p),
+        stat: (p) => this.peer.request("file.stat", p),
+        mkdir: (p) => this.peer.request("file.mkdir", p),
+    };
+    skill = {
+        install: (p) => this.peer.request("skill.install", p),
+        uninstall: (p) => this.peer.request("skill.uninstall", p),
+        list: (filter) => this.peer.request("skill.list", filter ?? {}),
+    };
+    /** 设置 HITL 裁决器（device 级，所有 session 共用）。 */
+    setHookDecider(fn) {
+        this.hookDecider = fn;
+    }
+    /** 设置自发输出回调。 */
+    setUnsolicitedHandler(fn) {
+        this.onUnsolicited = fn;
+    }
+    /** 内部：处理 phonon → server 的请求/通知。 */
+    async _handleInbound(method, params) {
+        if (method === "stream.event") {
+            const ev = params;
+            const s = this.sessions.get(ev.sessionId);
+            if (s) {
+                s._onStream(ev);
+                // 自动 ack
+                this.peer.notify("stream.ack", { sessionId: ev.sessionId, lastSeq: s._lastSeq });
+            }
+            else if (ev.origin === "unsolicited" && this.onUnsolicited) {
+                this.onUnsolicited(ev);
+            }
+            return null;
+        }
+        if (method === "hook.fired") {
+            const fired = params;
+            const s = this.sessions.get(fired.sessionId ?? "");
+            if (!this.hookDecider)
+                return { applied: true }; // 默认放行
+            const d = await this.hookDecider(fired, s);
+            const action = typeof d === "string" ? d : d.action;
+            const reason = typeof d === "string" ? undefined : d.reason;
+            return { action, reason };
+        }
+        if (method === "discovery.changed") {
+            this.emit("discoveryChanged", params);
+            return null;
+        }
+        if (method === "document.send") {
+            this.emit("document", params);
+            return { delivered: [] };
+        }
+        if (method === "document.prepare_upload") {
+            this.emit("prepareUpload", params);
+            return { uploadRef: newId(), uploadUrl: "", method: "PUT" };
+        }
+        if (method === "interaction.request") {
+            this.emit("interaction", params);
+            return { requestId: params.requestId, action: "cancel" };
+        }
+        return null;
+    }
+    _onClose() {
+        this.peer.rejectAll("device disconnected");
+        this.emit("disconnect");
+    }
+}
+export class PhononServer extends EventEmitter {
+    wss;
+    opts;
+    devices = new Map();
+    actualPort = 0;
+    constructor(opts = {}) {
+        super();
+        this.opts = opts;
+    }
+    listen() {
+        return new Promise((resolve) => {
+            const wss = new WebSocketServer({ port: this.opts.port ?? 0, host: this.opts.host });
+            this.wss = wss;
+            wss.on("connection", (ws) => this.onConnection(ws));
+            wss.on("listening", () => {
+                const addr = wss.address();
+                this.actualPort = typeof addr === "object" && addr ? addr.port : (this.opts.port ?? 0);
+                resolve(this.actualPort);
+            });
+        });
+    }
+    get port() { return this.actualPort; }
+    /** 当前连接的设备列表。 */
+    listDevices() { return [...this.devices.values()]; }
+    getDevice(deviceId) { return this.devices.get(deviceId); }
+    onConnection(ws) {
+        const transport = { send: (d) => ws.send(d), close: () => ws.close() };
+        let device;
+        const peer = new RpcPeer(transport, async (method, params) => {
+            if (method === "connect.hello") {
+                const p = params;
+                const auth = this.opts.authenticate
+                    ? await this.opts.authenticate(p.deviceId, p.auth?.deviceKey)
+                    : { tenantId: `tenant-${p.deviceId}` };
+                if (!auth)
+                    throw new Error("unauthorized");
+                device = new PhononDevice(p.deviceId, auth.tenantId, peer);
+                this.devices.set(p.deviceId, device);
+                this.emit("device", device); // 用户监听这个
+                return { protocolVersion: "0.1.0", tenantId: auth.tenantId, features: [], at: new Date().toISOString() };
+            }
+            if (!device)
+                throw new Error("not connected");
+            return device._handleInbound(method, params);
+        });
+        ws.on("message", (raw) => peer.handle(raw.toString()));
+        ws.on("close", () => {
+            if (device) {
+                this.devices.delete(device.deviceId);
+                device._onClose();
+            }
+        });
+    }
+    close() {
+        return new Promise((resolve) => {
+            if (!this.wss)
+                return resolve();
+            this.wss.close(() => resolve());
+        });
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agent-phonon/server-sdk",
+  "version": "0.2.0",
+  "description": "Server SDK for agent-phonon — build a server that orchestrates agents across multiple devices.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@agent-phonon/protocol": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.6.3"
+  },
+  "author": "agent-phonon contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackerphysics/agent-phonon.git",
+    "directory": "packages/sdk-server-ts"
+  },
+  "homepage": "https://github.com/hackerphysics/agent-phonon#readme",
+  "bugs": {
+    "url": "https://github.com/hackerphysics/agent-phonon/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test dist/**/*.test.js"
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @agent-phonon/server-sdk
+ *
+ * 让任何项目一键成为 agent-phonon 服务端：管理多设备、编排其上的 agent。
+ */
+export { PhononServer, PhononDevice, PhononSession } from "./server.js";
+export type { PhononServerOptions, HookDecider, SendResult } from "./server.js";
+export { RpcPeer } from "./rpc.js";
+export type { Transport } from "./rpc.js";

package/src/rpc.ts

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+
+/**
+ * 双向 JSON-RPC 2.0 peer（server 侧，零 core 依赖）。
+ * 每个 device 连接一个。两端皆可作 requester。
+ */
+
+export interface Transport {
+  send(data: string): void;
+  close(): void;
+}
+
+export type RpcHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
+
+interface Pending {
+  resolve: (v: unknown) => void;
+  reject: (e: unknown) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export class RpcPeer {
+  private transport: Transport;
+  private handler: RpcHandler;
+  private pending = new Map<string | number, Pending>();
+  private nextId = 1;
+
+  constructor(transport: Transport, handler: RpcHandler) {
+    this.transport = transport;
+    this.handler = handler;
+  }
+
+  request(method: string, params: unknown, timeoutMs = 600000): Promise<unknown> {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => { this.pending.delete(id); reject(new Error(`rpc timeout: ${method}`)); }, timeoutMs) : undefined;
+      this.pending.set(id, { resolve, reject, timer });
+      this.transport.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    });
+  }
+
+  notify(method: string, params: unknown): void {
+    this.transport.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+  }
+
+  async handle(data: string): Promise<void> {
+    let msg: Record<string, unknown>;
+    try { msg = JSON.parse(data); } catch { return; }
+
+    // 响应
+    if (("result" in msg || "error" in msg) && "id" in msg) {
+      const p = this.pending.get(msg.id as string | number);
+      if (!p) return;
+      this.pending.delete(msg.id as string | number);
+      if (p.timer) clearTimeout(p.timer);
+      if ("error" in msg && msg.error) p.reject(msg.error);
+      else p.resolve((msg as { result: unknown }).result);
+      return;
+    }
+
+    // 请求 / 通知
+    if (typeof msg.method === "string") {
+      const isNotification = !("id" in msg) || msg.id === undefined || msg.id === null;
+      try {
+        const result = await this.handler(msg.method, msg.params);
+        if (!isNotification) this.transport.send(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: result ?? null }));
+      } catch (err) {
+        if (!isNotification) {
+          this.transport.send(JSON.stringify({
+            jsonrpc: "2.0", id: msg.id,
+            error: { code: -32000, message: (err as Error)?.message ?? "error" },
+          }));
+        }
+      }
+    }
+  }
+
+  rejectAll(reason: string): void {
+    for (const [, p] of this.pending) { if (p.timer) clearTimeout(p.timer); p.reject(new Error(reason)); }
+    this.pending.clear();
+  }
+}
+
+export function newId(): string {
+  return randomUUID();
+}

package/src/server.ts

@@ -0,0 +1,290 @@
+import { EventEmitter } from "node:events";
+import { WebSocketServer, WebSocket } from "ws";
+import { RpcPeer, type Transport, newId } from "./rpc.js";
+import type {
+  AgentDescriptor,
+  SessionMeta,
+  StreamEvent,
+  HookFiredParams,
+  HookAction,
+} from "@agent-phonon/protocol";
+
+/**
+ * agent-phonon Server SDK。
+ *
+ * 让任何项目「一键成为 phonon 服务端」：导入 SDK → 配鉴权 → 监听 device →
+ * 用干净接口（discover / createSession / send / onStream / onHook）编排
+ * 多台设备上的 agent。协议帧/握手/ack/HITL 路由全由 SDK 处理。
+ *
+ * 支持多设备：一个 PhononServer 同时连多个 phonon。
+ */
+
+// ---------------------------------------------------------------------------
+// PhononSession：一个会话，流式事件用 EventEmitter
+// ---------------------------------------------------------------------------
+export interface SendResult {
+  turnId: string;
+  disposition: string;
+}
+
+export class PhononSession extends EventEmitter {
+  readonly sessionId: string;
+  readonly device: PhononDevice;
+  private lastSeq = -1;
+
+  constructor(device: PhononDevice, sessionId: string) {
+    super();
+    this.device = device;
+    this.sessionId = sessionId;
+  }
+
+  /** 发任务（结果走 'stream' 事件）。 */
+  async send(input: string, opts?: { verbosity?: "final" | "messages" | "tools" | "trace"; skills?: string[]; whenBusy?: "queue" | "interrupt" | "inject"; clientRequestId?: string }): Promise<SendResult> {
+    return this.device.call("session.send", { sessionId: this.sessionId, input, ...opts }) as Promise<SendResult>;
+  }
+
+  inject(context: Array<{ role: "system" | "user" | "assistant"; content: string }>): Promise<unknown> {
+    return this.device.call("session.inject", { sessionId: this.sessionId, context });
+  }
+  interrupt(reason?: string): Promise<unknown> {
+    return this.device.call("session.interrupt", { sessionId: this.sessionId, reason });
+  }
+  switchModel(model: string): Promise<unknown> {
+    return this.device.call("session.switchModel", { sessionId: this.sessionId, model });
+  }
+  compress(mode: "native" | "custom" = "native"): Promise<unknown> {
+    return this.device.call("session.compress", { sessionId: this.sessionId, mode });
+  }
+  status(): Promise<SessionMeta> {
+    return this.device.call("session.status", { sessionId: this.sessionId }) as Promise<SessionMeta>;
+  }
+  terminate(): Promise<unknown> {
+    return this.device.call("session.terminate", { sessionId: this.sessionId });
+  }
+
+  /** 内部：收到本 session 的 stream.event。 */
+  _onStream(ev: StreamEvent): void {
+    const seq = (ev as { seq: number }).seq;
+    this.emit("stream", ev);
+    if ((ev as { final?: boolean }).final) this.emit("end", ev);
+    if (seq > this.lastSeq) this.lastSeq = seq;
+  }
+  /** 本 session 已收到的最大 seq（device 用于 ack）。 */
+  get _lastSeq(): number {
+    return this.lastSeq;
+  }
+
+  // 类型化 on
+  override on(event: "stream", listener: (ev: StreamEvent) => void): this;
+  override on(event: "end", listener: (ev: StreamEvent) => void): this;
+  override on(event: string, listener: (...args: never[]) => void): this {
+    return super.on(event, listener as (...args: unknown[]) => void);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PhononDevice：一台连入的设备
+// ---------------------------------------------------------------------------
+export type HookDecider = (hook: HookFiredParams, session: PhononSession | undefined) => HookAction | { action: HookAction; reason?: string } | Promise<HookAction | { action: HookAction; reason?: string }>;
+
+export class PhononDevice extends EventEmitter {
+  readonly deviceId: string;
+  readonly tenantId: string;
+  private peer: RpcPeer;
+  private sessions = new Map<string, PhononSession>();
+  private hookDecider?: HookDecider;
+  /** 自发输出（无对应 session 时）回调。 */
+  private onUnsolicited?: (ev: StreamEvent) => void;
+
+  constructor(deviceId: string, tenantId: string, peer: RpcPeer) {
+    super();
+    this.deviceId = deviceId;
+    this.tenantId = tenantId;
+    this.peer = peer;
+  }
+
+  call(method: string, params: unknown): Promise<unknown> {
+    return this.peer.request(method, params);
+  }
+
+  /** 列设备上可用 agent。 */
+  async discover(): Promise<AgentDescriptor[]> {
+    const r = (await this.peer.request("discovery.list", {})) as { agents: AgentDescriptor[] };
+    return r.agents;
+  }
+
+  /** 建会话。 */
+  async createSession(params: { project: string; agent: string; model: string; worktreeId?: string; verbosity?: "final" | "messages" | "tools" | "trace"; clientRequestId?: string }): Promise<PhononSession> {
+    const r = (await this.peer.request("session.create", { verbosity: "messages", ...params })) as { sessionId: string };
+    const s = new PhononSession(this, r.sessionId);
+    this.sessions.set(r.sessionId, s);
+    return s;
+  }
+
+  /** 列会话。 */
+  async listSessions(filter?: { project?: string; agent?: string; status?: string; limit?: number; cursor?: string }): Promise<{ sessions: SessionMeta[]; nextCursor?: string }> {
+    return this.peer.request("session.list", filter ?? {}) as Promise<{ sessions: SessionMeta[]; nextCursor?: string }>;
+  }
+
+  /** 设备 OS/机器信息，用于 server 做任务调度决策。 */
+  info(): Promise<unknown> {
+    return this.peer.request("device.info", {});
+  }
+
+  /** 设备资源快照（CPU/内存/磁盘/进程/GPU best-effort）。 */
+  resources(): Promise<unknown> {
+    return this.peer.request("device.resources", {});
+  }
+
+  // ---- project / file / skill 便捷封装 ----
+  project = {
+    create: (p: { name: string; path?: string; git?: boolean; remote?: string; clientRequestId?: string }) => this.peer.request("project.create", p) as Promise<{ project: { projectId: string; path: string } }>,
+    list: () => this.peer.request("project.list", {}) as Promise<{ projects: unknown[] }>,
+    get: (projectId: string) => this.peer.request("project.get", { projectId }),
+    remove: (projectId: string, opts?: { deleteFiles?: boolean; whenActiveSessions?: "reject" | "cascade" }) => this.peer.request("project.remove", { projectId, ...opts }),
+    worktree: {
+      create: (p: { projectId: string; baseBranch: string; newBranch?: string; path?: string }) => this.peer.request("project.worktree.create", p),
+      list: (projectId: string) => this.peer.request("project.worktree.list", { projectId }),
+      remove: (p: { projectId: string; worktreeId: string; force?: boolean }) => this.peer.request("project.worktree.remove", p),
+    },
+    deleteBranch: (p: { projectId: string; branch: string; force?: boolean }) => this.peer.request("project.git.deleteBranch", p),
+  };
+
+  env = {
+    set: (p: { scope: "global" | "project" | "skill"; projectId?: string; agent?: string; skillName?: string; name: string; value: string; secret?: boolean; clientRequestId?: string }) => this.peer.request("env.set", p),
+    list: (p?: { scope?: "global" | "project" | "skill"; projectId?: string; agent?: string; skillName?: string; reveal?: boolean }) => this.peer.request("env.list", p ?? {}),
+    delete: (p: { scope: "global" | "project" | "skill"; projectId?: string; agent?: string; skillName?: string; name: string; clientRequestId?: string }) => this.peer.request("env.delete", p),
+  };
+
+  file = {
+    read: (p: { projectId: string; worktreeId?: string; path: string; encoding?: "utf8" | "base64"; maxBytes?: number }) => this.peer.request("file.read", p),
+    write: (p: { projectId: string; worktreeId?: string; path: string; encoding?: "utf8" | "base64"; data: string; overwrite?: boolean; createDirs?: boolean; clientRequestId?: string }) => this.peer.request("file.write", p),
+    list: (p: { projectId: string; worktreeId?: string; path?: string; recursive?: boolean; limit?: number }) => this.peer.request("file.list", p),
+    stat: (p: { projectId: string; worktreeId?: string; path: string }) => this.peer.request("file.stat", p),
+    mkdir: (p: { projectId: string; worktreeId?: string; path: string; recursive?: boolean; clientRequestId?: string }) => this.peer.request("file.mkdir", p),
+  };
+
+  skill = {
+    install: (p: { agent: string; name: string; scope: "global" | "project"; projectId?: string; source: unknown; clientRequestId?: string }) => this.peer.request("skill.install", p),
+    uninstall: (p: { agent: string; name: string; scope: "global" | "project"; projectId?: string }) => this.peer.request("skill.uninstall", p),
+    list: (filter?: { agent?: string; scope?: "global" | "project"; projectId?: string }) => this.peer.request("skill.list", filter ?? {}),
+  };
+
+  /** 设置 HITL 裁决器（device 级，所有 session 共用）。 */
+  setHookDecider(fn: HookDecider): void {
+    this.hookDecider = fn;
+  }
+  /** 设置自发输出回调。 */
+  setUnsolicitedHandler(fn: (ev: StreamEvent) => void): void {
+    this.onUnsolicited = fn;
+  }
+
+  /** 内部：处理 phonon → server 的请求/通知。 */
+  async _handleInbound(method: string, params: unknown): Promise<unknown> {
+    if (method === "stream.event") {
+      const ev = params as StreamEvent;
+      const s = this.sessions.get((ev as { sessionId: string }).sessionId);
+      if (s) {
+        s._onStream(ev);
+        // 自动 ack
+        this.peer.notify("stream.ack", { sessionId: (ev as { sessionId: string }).sessionId, lastSeq: s._lastSeq });
+      } else if ((ev as { origin?: string }).origin === "unsolicited" && this.onUnsolicited) {
+        this.onUnsolicited(ev);
+      }
+      return null;
+    }
+    if (method === "hook.fired") {
+      const fired = params as HookFiredParams;
+      const s = this.sessions.get((fired as { sessionId?: string }).sessionId ?? "");
+      if (!this.hookDecider) return { applied: true }; // 默认放行
+      const d = await this.hookDecider(fired, s);
+      const action = typeof d === "string" ? d : d.action;
+      const reason = typeof d === "string" ? undefined : d.reason;
+      return { action, reason };
+    }
+    if (method === "discovery.changed") { this.emit("discoveryChanged", params); return null; }
+    if (method === "document.send") { this.emit("document", params); return { delivered: [] }; }
+    if (method === "document.prepare_upload") { this.emit("prepareUpload", params); return { uploadRef: newId(), uploadUrl: "", method: "PUT" }; }
+    if (method === "interaction.request") { this.emit("interaction", params); return { requestId: (params as { requestId: string }).requestId, action: "cancel" }; }
+    return null;
+  }
+
+  _onClose(): void {
+    this.peer.rejectAll("device disconnected");
+    this.emit("disconnect");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PhononServer：监听 ws，管理多设备
+// ---------------------------------------------------------------------------
+export interface PhononServerOptions {
+  port?: number;
+  host?: string;
+  /** 鉴权：返回 tenantId 表示通过，返回 null 拒绝。缺省全部放行（本地测试）。 */
+  authenticate?: (deviceId: string, deviceKey: string | undefined) => { tenantId: string } | null | Promise<{ tenantId: string } | null>;
+}
+
+export class PhononServer extends EventEmitter {
+  private wss?: WebSocketServer;
+  private opts: PhononServerOptions;
+  private devices = new Map<string, PhononDevice>();
+  private actualPort = 0;
+
+  constructor(opts: PhononServerOptions = {}) {
+    super();
+    this.opts = opts;
+  }
+
+  listen(): Promise<number> {
+    return new Promise((resolve) => {
+      const wss = new WebSocketServer({ port: this.opts.port ?? 0, host: this.opts.host });
+      this.wss = wss;
+      wss.on("connection", (ws: WebSocket) => this.onConnection(ws));
+      wss.on("listening", () => {
+        const addr = wss.address();
+        this.actualPort = typeof addr === "object" && addr ? addr.port : (this.opts.port ?? 0);
+        resolve(this.actualPort);
+      });
+    });
+  }
+
+  get port(): number { return this.actualPort; }
+
+  /** 当前连接的设备列表。 */
+  listDevices(): PhononDevice[] { return [...this.devices.values()]; }
+  getDevice(deviceId: string): PhononDevice | undefined { return this.devices.get(deviceId); }
+
+  private onConnection(ws: WebSocket): void {
+    const transport: Transport = { send: (d) => ws.send(d), close: () => ws.close() };
+    let device: PhononDevice | undefined;
+
+    const peer = new RpcPeer(transport, async (method, params) => {
+      if (method === "connect.hello") {
+        const p = params as { deviceId: string; auth?: { deviceKey?: string } };
+        const auth = this.opts.authenticate
+          ? await this.opts.authenticate(p.deviceId, p.auth?.deviceKey)
+          : { tenantId: `tenant-${p.deviceId}` };
+        if (!auth) throw new Error("unauthorized");
+        device = new PhononDevice(p.deviceId, auth.tenantId, peer);
+        this.devices.set(p.deviceId, device);
+        this.emit("device", device); // 用户监听这个
+        return { protocolVersion: "0.1.0", tenantId: auth.tenantId, features: [], at: new Date().toISOString() };
+      }
+      if (!device) throw new Error("not connected");
+      return device._handleInbound(method, params);
+    });
+
+    ws.on("message", (raw: Buffer) => peer.handle(raw.toString()));
+    ws.on("close", () => {
+      if (device) { this.devices.delete(device.deviceId); device._onClose(); }
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.wss) return resolve();
+      this.wss.close(() => resolve());
+    });
+  }
+}