@panda-agent/panda-app-sdk 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @panda-agent/panda-app-sdk
+
+Panda 智能应用 SDK — 在 iframe 或 Utility Process 中调用 Panda Desktop 提供的应用平台 API。
+
+SDK 为纯客户端 RPC 封装，**不包含** Panda Core 运行时。应用须在 Panda Desktop 中安装并运行。
+
+## 安装
+
+```bash
+npm install @panda-agent/panda-app-sdk
+```
+
+## 入口
+
+| 子路径 | 运行环境 | 用途 |
+|--------|----------|------|
+| `@panda-agent/panda-app-sdk/browser` | iframe（Session / Standalone UI） | `PandaApp.connectIframe()` |
+| `@panda-agent/panda-app-sdk/node` | Utility Process（Standalone 后端 / Headless） | `PandaApp.connectUtilityProcess()` |
+
+## 快速开始
+
+### Session / Standalone 前端
+
+```typescript
+import { PandaApp } from '@panda-agent/panda-app-sdk/browser';
+
+const app = PandaApp.connectIframe();
+const conv = await app.conversation.createForApp({ title: 'My task', ephemeral: true });
+await app.conversation.submitMessage(conv.conversationId, 'Hello');
+```
+
+使用 Vite / webpack 将 browser 入口打进前端 bundle。
+
+### Standalone / Headless 后端（`package/main.mjs`）
+
+```typescript
+import { PandaApp, APP_UTILITY_READY } from '@panda-agent/panda-app-sdk/node';
+
+const app = PandaApp.connectUtilityProcess();
+
+process.parentPort.postMessage({
+  type: APP_UTILITY_READY,
+  appId: process.env.PANDA_APP_ID ?? 'unknown',
+});
+
+// 使用 app.conversation / app.tools 等 API
+```
+
+`APP_UTILITY_READY` 为可选握手消息（宿主仅记录日志，不阻塞启动）。
+
+建议用 esbuild 将 node 入口打成单文件 `main.mjs` 再随应用 zip 分发。
+
+## 应用类型对照
+
+| presentation | browser SDK | node SDK |
+|--------------|-------------|----------|
+| `session` | 必须 | 不需要 |
+| `standalone` | UI 需要 | `runtime.processEntry` 需要 |
+| `headless` | 不需要 | 必须 |
+
+## 高级用法
+
+需要裸 `invoke`（例如共享验收脚本）时：
+
+```typescript
+import { createIframeBridgeTransport, createAppSdk } from '@panda-agent/panda-app-sdk/browser';
+
+const transport = createIframeBridgeTransport();
+const app = createAppSdk(transport);
+const invoke = (path: string, args?: unknown[]) => transport.invoke(path, args);
+```
+
+## 开发与构建（monorepo 内）
+
+```bash
+cd packages/app-sdk
+npm install
+npm run build          # 产出 dist/browser、dist/node
+npm run vendor-fixtures # 复制到 panda-desktop/fixtures/*/package/vendor/
+npm test
+```
+
+修改 SDK 后需重新 `build` 并 `vendor-fixtures`，桌面 demo 才会更新。
+
+## 发布到 npm
+
+```bash
+cd packages/app-sdk
+npm run release:publish:dry-run   # 干跑
+npm run release:publish           # 发布到 @panda-agent（需 npm 组织权限）
+npm run release:publish:tester    # 先发 tester tag
+```
+
+发布前会校验 `package.json` version 与 Core `PANDA_APP_SDK_VERSION` 一致。本包 `.npmrc` 指向 `registry.npmjs.org`（勿使用仓库根目录的 npmmirror 配置）。
+
+## 版本
+
+`runtime.getHost().appSdkVersion` 与 npm 包版本应对齐。发布时同步更新 Core 中 `PANDA_APP_SDK_VERSION`（`app-platform-runtime-types.ts`）。
+
+建议 Panda Desktop 版本不低于 SDK 发布说明中的最低宿主版本。

package/dist/browser/index.d.ts

@@ -0,0 +1,115 @@
+export { PANDA_APP_BRIDGE_EVENT, PANDA_APP_BRIDGE_INVOKE, PANDA_APP_BRIDGE_INVOKE_RESULT, } from './protocol.js';
+export { createAppSdk } from './create-app-sdk.js';
+export { createIframeBridgeTransport } from './transport/iframe.js';
+export type * from './types.js';
+export declare const PandaApp: {
+    connectIframe(): {
+        auth: {
+            getCurrentUser: () => Promise<import("./types.js").AppUser | null>;
+        };
+        model: {
+            list: (options?: {
+                enabledOnly?: boolean;
+                visibleOnly?: boolean;
+                scene?: string;
+            }) => Promise<import("./types.js").ModelListItem[]>;
+            resolveForScene: (request?: {
+                scene?: string;
+                preferredModelId?: string;
+            }) => Promise<import("./types.js").ModelListItem | null>;
+        };
+        workspace: {
+            list: (request: {
+                limit: number;
+                includeEphemeral?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem[]>;
+            ensureLocal: (request: {
+                path: string;
+                touch?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem>;
+        };
+        conversation: {
+            createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
+            disposeForApp: (conversationId: string) => Promise<unknown>;
+            submitMessage: (conversationId: string, prompt: string) => Promise<unknown>;
+            getMessages: (conversationId: string) => Promise<unknown>;
+            subscribe: (options: import("./types.js").ConversationSubscribeOptions & {
+                onEvent?: import("./types.js").AppEventHandler;
+            }) => Promise<{
+                subscriptionId: string;
+                unsubscribe: () => Promise<void>;
+            }>;
+            awaitTurn: (options: {
+                conversationId: string;
+                turnId?: string;
+                timeoutMs?: number;
+            }) => Promise<unknown>;
+        };
+        session: {
+            mount: (conversationId: string, appId: string, replaceConfirmed?: boolean) => Promise<unknown>;
+            unmount: (conversationId: string) => Promise<unknown>;
+            getMount: (conversationId: string) => Promise<unknown>;
+        };
+        ingress: {
+            submit: (conversationId: string, prompt: string) => Promise<{
+                conversationId: string;
+                status: string;
+            }>;
+        };
+        tools: {
+            list: (request: {
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<Array<{
+                name: string;
+                displayName: string;
+                description: string;
+                kind: string;
+            }>>;
+            execute: (request: {
+                toolName: string;
+                args?: Record<string, unknown>;
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<{
+                toolName: string;
+                workspaceId: string;
+                ok: boolean;
+                llmContent?: string;
+                error?: {
+                    message: string;
+                    type?: string;
+                };
+                displayData?: unknown;
+            }>;
+        };
+        runtime: {
+            now: () => Promise<{
+                timestamp: number;
+                iso: string;
+                timeZone: string;
+                utcOffsetMinutes: number;
+            }>;
+            getHost: () => Promise<{
+                platform: string;
+                arch: string;
+                osName: string;
+                hostProduct: string;
+                shell: string;
+                shellKind: string;
+                homeDir: string;
+                pandaVersion: string;
+                appSdkVersion: string;
+            }>;
+        };
+        dialog: {
+            showOpen: (request?: import("./types.js").DialogShowOpenRequest) => Promise<import("./types.js").DialogShowOpenResult>;
+            readPickedFile: (request: import("./types.js").DialogReadPickedFileRequest) => Promise<import("./types.js").DialogReadPickedFileResult>;
+            releasePick: (pickToken: string) => Promise<unknown>;
+            showSave: (request?: import("./types.js").DialogShowSaveRequest) => Promise<import("./types.js").DialogShowSaveResult>;
+            writeSaveFile: (request: import("./types.js").DialogWriteSaveFileRequest) => Promise<import("./types.js").DialogWriteSaveFileResult>;
+            pickAndReadFile: (options?: import("./types.js").DialogPickAndReadFileOptions) => Promise<import("./types.js").DialogReadPickedFileResult | null>;
+            saveFile: (options: import("./types.js").DialogSaveFileOptions) => Promise<string | null>;
+        };
+    };
+};

package/dist/browser/index.js

@@ -0,0 +1,212 @@
+// src/protocol.ts
+var PANDA_APP_BRIDGE_INVOKE = "panda-app-bridge:invoke";
+var PANDA_APP_BRIDGE_INVOKE_RESULT = "panda-app-bridge:invoke-result";
+var PANDA_APP_BRIDGE_EVENT = "panda-app-bridge:event";
+
+// src/create-app-sdk.ts
+function createAppSdk(transport) {
+  return {
+    auth: {
+      getCurrentUser: () => transport.invoke("auth.getCurrentUser", [])
+    },
+    model: {
+      list: (options) => transport.invoke("model.list", [options ?? {}]),
+      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}])
+    },
+    workspace: {
+      list: (request) => transport.invoke("workspace.list", [request]),
+      ensureLocal: (request) => transport.invoke("workspace.ensureLocal", [request])
+    },
+    conversation: {
+      createForApp: (options) => transport.invoke("conversation.createForApp", [options ?? {}]),
+      disposeForApp: (conversationId) => transport.invoke("conversation.disposeForApp", [conversationId]),
+      submitMessage: (conversationId, prompt) => transport.invoke("conversation.submitMessage", [conversationId, prompt]),
+      getMessages: (conversationId) => transport.invoke("conversation.getMessages", [conversationId]),
+      subscribe: async (options) => {
+        const result = await transport.invoke("conversation.subscribe", [options]);
+        let offEvent;
+        if (options.onEvent) {
+          offEvent = transport.subscribe(result.subscriptionId, options.onEvent);
+        }
+        return {
+          subscriptionId: result.subscriptionId,
+          unsubscribe: async () => {
+            offEvent?.();
+            await transport.invoke("conversation.unsubscribe", [result.subscriptionId]);
+          }
+        };
+      },
+      awaitTurn: (options) => transport.invoke("conversation.awaitTurn", [options])
+    },
+    session: {
+      mount: (conversationId, appId, replaceConfirmed) => transport.invoke("mountSession", [conversationId, appId, replaceConfirmed === true]),
+      unmount: (conversationId) => transport.invoke("unmountSession", [conversationId]),
+      getMount: (conversationId) => transport.invoke("getSessionMount", [conversationId])
+    },
+    ingress: {
+      submit: (conversationId, prompt) => transport.invoke("ingress.submit", [conversationId, prompt])
+    },
+    tools: {
+      list: (request) => transport.invoke("tools.list", [request]),
+      execute: (request) => transport.invoke("tools.execute", [request])
+    },
+    runtime: {
+      now: () => transport.invoke("runtime.now", []),
+      getHost: () => transport.invoke("runtime.getHost", [])
+    },
+    dialog: {
+      showOpen: (request) => transport.invoke("dialog.showOpen", [request ?? {}]),
+      readPickedFile: (request) => transport.invoke("dialog.readPickedFile", [request]),
+      releasePick: (pickToken) => transport.invoke("dialog.releasePick", [pickToken]),
+      showSave: (request) => transport.invoke("dialog.showSave", [request ?? {}]),
+      writeSaveFile: (request) => transport.invoke("dialog.writeSaveFile", [request]),
+      pickAndReadFile: async (options) => {
+        const { encoding, ...openRequest } = options ?? {};
+        const opened = await transport.invoke("dialog.showOpen", [openRequest]);
+        if (opened.canceled || opened.filePaths.length === 0) {
+          return null;
+        }
+        const filePath = opened.filePaths[0];
+        try {
+          return await transport.invoke("dialog.readPickedFile", [
+            { pickToken: opened.pickToken, filePath, encoding }
+          ]);
+        } finally {
+          await transport.invoke("dialog.releasePick", [opened.pickToken]).catch(() => void 0);
+        }
+      },
+      saveFile: async (options) => {
+        const { content, encoding, ...saveRequest } = options;
+        const saved = await transport.invoke("dialog.showSave", [saveRequest]);
+        if (saved.canceled) {
+          return null;
+        }
+        await transport.invoke("dialog.writeSaveFile", [
+          {
+            saveToken: saved.saveToken,
+            filePath: saved.filePath,
+            content,
+            encoding
+          }
+        ]);
+        return saved.filePath;
+      }
+    }
+  };
+}
+
+// src/request-id.browser.ts
+function newRequestId() {
+  return crypto.randomUUID();
+}
+
+// src/transport/shared/pending-invoke.ts
+function createPendingInvoke(newRequestId2) {
+  const pending = /* @__PURE__ */ new Map();
+  function invoke(postMessage, invokeType, path, args) {
+    const requestId = newRequestId2();
+    return new Promise((resolve, reject) => {
+      pending.set(requestId, { resolve, reject });
+      postMessage({ type: invokeType, requestId, path, args });
+    });
+  }
+  function handleInvokeResult(message) {
+    if (!message.requestId) {
+      return;
+    }
+    const entry = pending.get(message.requestId);
+    if (!entry) {
+      return;
+    }
+    pending.delete(message.requestId);
+    if (message.ok) {
+      entry.resolve(message.result);
+    } else {
+      entry.reject(new Error(message.error ?? "invoke failed"));
+    }
+  }
+  return { invoke, handleInvokeResult };
+}
+
+// src/transport/shared/subscription-events.ts
+function createSubscriptionEvents() {
+  const handlersBySubscriptionId = /* @__PURE__ */ new Map();
+  function subscribe(subscriptionId, handler) {
+    const handlers = handlersBySubscriptionId.get(subscriptionId) ?? /* @__PURE__ */ new Set();
+    handlers.add(handler);
+    handlersBySubscriptionId.set(subscriptionId, handlers);
+    return () => {
+      const current = handlersBySubscriptionId.get(subscriptionId);
+      if (!current) {
+        return;
+      }
+      current.delete(handler);
+      if (current.size === 0) {
+        handlersBySubscriptionId.delete(subscriptionId);
+      }
+    };
+  }
+  function dispatch(subscriptionId, event) {
+    const handlers = handlersBySubscriptionId.get(subscriptionId);
+    if (!handlers) {
+      return;
+    }
+    for (const handler of handlers) {
+      handler(event);
+    }
+  }
+  function remove(subscriptionId) {
+    handlersBySubscriptionId.delete(subscriptionId);
+  }
+  return { subscribe, dispatch, remove };
+}
+
+// src/transport/iframe.ts
+function createIframeBridgeTransport() {
+  if (typeof window === "undefined") {
+    throw new Error("[app-sdk] iframe bridge requires browser context");
+  }
+  const { invoke: createInvoke, handleInvokeResult } = createPendingInvoke(newRequestId);
+  const subscriptions = createSubscriptionEvents();
+  window.addEventListener("message", (event) => {
+    const data = event.data;
+    if (!data || typeof data !== "object" || !data.type) {
+      return;
+    }
+    if (data.type === PANDA_APP_BRIDGE_EVENT && data.subscriptionId && data.event) {
+      subscriptions.dispatch(data.subscriptionId, data.event);
+      return;
+    }
+    if (data.type === PANDA_APP_BRIDGE_INVOKE_RESULT) {
+      handleInvokeResult(data);
+    }
+  });
+  return {
+    invoke(path, args) {
+      return createInvoke(
+        (message) => {
+          window.parent.postMessage(message, "*");
+        },
+        PANDA_APP_BRIDGE_INVOKE,
+        path,
+        args
+      );
+    },
+    subscribe: subscriptions.subscribe
+  };
+}
+
+// src/browser.ts
+var PandaApp = {
+  connectIframe() {
+    return createAppSdk(createIframeBridgeTransport());
+  }
+};
+export {
+  PANDA_APP_BRIDGE_EVENT,
+  PANDA_APP_BRIDGE_INVOKE,
+  PANDA_APP_BRIDGE_INVOKE_RESULT,
+  PandaApp,
+  createAppSdk,
+  createIframeBridgeTransport
+};

package/dist/node/index.d.ts

@@ -0,0 +1,115 @@
+export { APP_UTILITY_EVENT, APP_UTILITY_INVOKE, APP_UTILITY_INVOKE_RESULT, APP_UTILITY_READY, } from './protocol.js';
+export { createAppSdk } from './create-app-sdk.js';
+export { createUtilityProcessTransport } from './transport/utility-process.js';
+export type * from './types.js';
+export declare const PandaApp: {
+    connectUtilityProcess(): {
+        auth: {
+            getCurrentUser: () => Promise<import("./types.js").AppUser | null>;
+        };
+        model: {
+            list: (options?: {
+                enabledOnly?: boolean;
+                visibleOnly?: boolean;
+                scene?: string;
+            }) => Promise<import("./types.js").ModelListItem[]>;
+            resolveForScene: (request?: {
+                scene?: string;
+                preferredModelId?: string;
+            }) => Promise<import("./types.js").ModelListItem | null>;
+        };
+        workspace: {
+            list: (request: {
+                limit: number;
+                includeEphemeral?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem[]>;
+            ensureLocal: (request: {
+                path: string;
+                touch?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem>;
+        };
+        conversation: {
+            createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
+            disposeForApp: (conversationId: string) => Promise<unknown>;
+            submitMessage: (conversationId: string, prompt: string) => Promise<unknown>;
+            getMessages: (conversationId: string) => Promise<unknown>;
+            subscribe: (options: import("./types.js").ConversationSubscribeOptions & {
+                onEvent?: import("./types.js").AppEventHandler;
+            }) => Promise<{
+                subscriptionId: string;
+                unsubscribe: () => Promise<void>;
+            }>;
+            awaitTurn: (options: {
+                conversationId: string;
+                turnId?: string;
+                timeoutMs?: number;
+            }) => Promise<unknown>;
+        };
+        session: {
+            mount: (conversationId: string, appId: string, replaceConfirmed?: boolean) => Promise<unknown>;
+            unmount: (conversationId: string) => Promise<unknown>;
+            getMount: (conversationId: string) => Promise<unknown>;
+        };
+        ingress: {
+            submit: (conversationId: string, prompt: string) => Promise<{
+                conversationId: string;
+                status: string;
+            }>;
+        };
+        tools: {
+            list: (request: {
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<Array<{
+                name: string;
+                displayName: string;
+                description: string;
+                kind: string;
+            }>>;
+            execute: (request: {
+                toolName: string;
+                args?: Record<string, unknown>;
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<{
+                toolName: string;
+                workspaceId: string;
+                ok: boolean;
+                llmContent?: string;
+                error?: {
+                    message: string;
+                    type?: string;
+                };
+                displayData?: unknown;
+            }>;
+        };
+        runtime: {
+            now: () => Promise<{
+                timestamp: number;
+                iso: string;
+                timeZone: string;
+                utcOffsetMinutes: number;
+            }>;
+            getHost: () => Promise<{
+                platform: string;
+                arch: string;
+                osName: string;
+                hostProduct: string;
+                shell: string;
+                shellKind: string;
+                homeDir: string;
+                pandaVersion: string;
+                appSdkVersion: string;
+            }>;
+        };
+        dialog: {
+            showOpen: (request?: import("./types.js").DialogShowOpenRequest) => Promise<import("./types.js").DialogShowOpenResult>;
+            readPickedFile: (request: import("./types.js").DialogReadPickedFileRequest) => Promise<import("./types.js").DialogReadPickedFileResult>;
+            releasePick: (pickToken: string) => Promise<unknown>;
+            showSave: (request?: import("./types.js").DialogShowSaveRequest) => Promise<import("./types.js").DialogShowSaveResult>;
+            writeSaveFile: (request: import("./types.js").DialogWriteSaveFileRequest) => Promise<import("./types.js").DialogWriteSaveFileResult>;
+            pickAndReadFile: (options?: import("./types.js").DialogPickAndReadFileOptions) => Promise<import("./types.js").DialogReadPickedFileResult | null>;
+            saveFile: (options: import("./types.js").DialogSaveFileOptions) => Promise<string | null>;
+        };
+    };
+};

package/dist/node/index.js

@@ -0,0 +1,216 @@
+// src/protocol.ts
+var APP_UTILITY_INVOKE = "app-utility:invoke";
+var APP_UTILITY_INVOKE_RESULT = "app-utility:invoke-result";
+var APP_UTILITY_READY = "app-utility:ready";
+var APP_UTILITY_EVENT = "app-utility:event";
+
+// src/create-app-sdk.ts
+function createAppSdk(transport) {
+  return {
+    auth: {
+      getCurrentUser: () => transport.invoke("auth.getCurrentUser", [])
+    },
+    model: {
+      list: (options) => transport.invoke("model.list", [options ?? {}]),
+      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}])
+    },
+    workspace: {
+      list: (request) => transport.invoke("workspace.list", [request]),
+      ensureLocal: (request) => transport.invoke("workspace.ensureLocal", [request])
+    },
+    conversation: {
+      createForApp: (options) => transport.invoke("conversation.createForApp", [options ?? {}]),
+      disposeForApp: (conversationId) => transport.invoke("conversation.disposeForApp", [conversationId]),
+      submitMessage: (conversationId, prompt) => transport.invoke("conversation.submitMessage", [conversationId, prompt]),
+      getMessages: (conversationId) => transport.invoke("conversation.getMessages", [conversationId]),
+      subscribe: async (options) => {
+        const result = await transport.invoke("conversation.subscribe", [options]);
+        let offEvent;
+        if (options.onEvent) {
+          offEvent = transport.subscribe(result.subscriptionId, options.onEvent);
+        }
+        return {
+          subscriptionId: result.subscriptionId,
+          unsubscribe: async () => {
+            offEvent?.();
+            await transport.invoke("conversation.unsubscribe", [result.subscriptionId]);
+          }
+        };
+      },
+      awaitTurn: (options) => transport.invoke("conversation.awaitTurn", [options])
+    },
+    session: {
+      mount: (conversationId, appId, replaceConfirmed) => transport.invoke("mountSession", [conversationId, appId, replaceConfirmed === true]),
+      unmount: (conversationId) => transport.invoke("unmountSession", [conversationId]),
+      getMount: (conversationId) => transport.invoke("getSessionMount", [conversationId])
+    },
+    ingress: {
+      submit: (conversationId, prompt) => transport.invoke("ingress.submit", [conversationId, prompt])
+    },
+    tools: {
+      list: (request) => transport.invoke("tools.list", [request]),
+      execute: (request) => transport.invoke("tools.execute", [request])
+    },
+    runtime: {
+      now: () => transport.invoke("runtime.now", []),
+      getHost: () => transport.invoke("runtime.getHost", [])
+    },
+    dialog: {
+      showOpen: (request) => transport.invoke("dialog.showOpen", [request ?? {}]),
+      readPickedFile: (request) => transport.invoke("dialog.readPickedFile", [request]),
+      releasePick: (pickToken) => transport.invoke("dialog.releasePick", [pickToken]),
+      showSave: (request) => transport.invoke("dialog.showSave", [request ?? {}]),
+      writeSaveFile: (request) => transport.invoke("dialog.writeSaveFile", [request]),
+      pickAndReadFile: async (options) => {
+        const { encoding, ...openRequest } = options ?? {};
+        const opened = await transport.invoke("dialog.showOpen", [openRequest]);
+        if (opened.canceled || opened.filePaths.length === 0) {
+          return null;
+        }
+        const filePath = opened.filePaths[0];
+        try {
+          return await transport.invoke("dialog.readPickedFile", [
+            { pickToken: opened.pickToken, filePath, encoding }
+          ]);
+        } finally {
+          await transport.invoke("dialog.releasePick", [opened.pickToken]).catch(() => void 0);
+        }
+      },
+      saveFile: async (options) => {
+        const { content, encoding, ...saveRequest } = options;
+        const saved = await transport.invoke("dialog.showSave", [saveRequest]);
+        if (saved.canceled) {
+          return null;
+        }
+        await transport.invoke("dialog.writeSaveFile", [
+          {
+            saveToken: saved.saveToken,
+            filePath: saved.filePath,
+            content,
+            encoding
+          }
+        ]);
+        return saved.filePath;
+      }
+    }
+  };
+}
+
+// src/request-id.node.ts
+import { randomUUID } from "node:crypto";
+function newRequestId() {
+  return randomUUID();
+}
+
+// src/transport/shared/pending-invoke.ts
+function createPendingInvoke(newRequestId2) {
+  const pending = /* @__PURE__ */ new Map();
+  function invoke(postMessage, invokeType, path, args) {
+    const requestId = newRequestId2();
+    return new Promise((resolve, reject) => {
+      pending.set(requestId, { resolve, reject });
+      postMessage({ type: invokeType, requestId, path, args });
+    });
+  }
+  function handleInvokeResult(message) {
+    if (!message.requestId) {
+      return;
+    }
+    const entry = pending.get(message.requestId);
+    if (!entry) {
+      return;
+    }
+    pending.delete(message.requestId);
+    if (message.ok) {
+      entry.resolve(message.result);
+    } else {
+      entry.reject(new Error(message.error ?? "invoke failed"));
+    }
+  }
+  return { invoke, handleInvokeResult };
+}
+
+// src/transport/shared/subscription-events.ts
+function createSubscriptionEvents() {
+  const handlersBySubscriptionId = /* @__PURE__ */ new Map();
+  function subscribe(subscriptionId, handler) {
+    const handlers = handlersBySubscriptionId.get(subscriptionId) ?? /* @__PURE__ */ new Set();
+    handlers.add(handler);
+    handlersBySubscriptionId.set(subscriptionId, handlers);
+    return () => {
+      const current = handlersBySubscriptionId.get(subscriptionId);
+      if (!current) {
+        return;
+      }
+      current.delete(handler);
+      if (current.size === 0) {
+        handlersBySubscriptionId.delete(subscriptionId);
+      }
+    };
+  }
+  function dispatch(subscriptionId, event) {
+    const handlers = handlersBySubscriptionId.get(subscriptionId);
+    if (!handlers) {
+      return;
+    }
+    for (const handler of handlers) {
+      handler(event);
+    }
+  }
+  function remove(subscriptionId) {
+    handlersBySubscriptionId.delete(subscriptionId);
+  }
+  return { subscribe, dispatch, remove };
+}
+
+// src/transport/utility-process.ts
+function createUtilityProcessTransport() {
+  const parentPort = process.parentPort;
+  if (!parentPort) {
+    throw new Error("[app-sdk] parentPort unavailable");
+  }
+  const { invoke: createInvoke, handleInvokeResult } = createPendingInvoke(newRequestId);
+  const subscriptions = createSubscriptionEvents();
+  parentPort.on("message", (event) => {
+    const msg = event.data;
+    if (!msg || typeof msg !== "object" || !msg.type) {
+      return;
+    }
+    if (msg.type === APP_UTILITY_EVENT && msg.subscriptionId && msg.event) {
+      subscriptions.dispatch(msg.subscriptionId, msg.event);
+      return;
+    }
+    if (msg.type === APP_UTILITY_INVOKE_RESULT) {
+      handleInvokeResult(msg);
+    }
+  });
+  return {
+    invoke(path, args) {
+      return createInvoke(
+        (message) => {
+          parentPort.postMessage(message);
+        },
+        APP_UTILITY_INVOKE,
+        path,
+        args
+      );
+    },
+    subscribe: subscriptions.subscribe
+  };
+}
+
+// src/node.ts
+var PandaApp = {
+  connectUtilityProcess() {
+    return createAppSdk(createUtilityProcessTransport());
+  }
+};
+export {
+  APP_UTILITY_EVENT,
+  APP_UTILITY_INVOKE,
+  APP_UTILITY_INVOKE_RESULT,
+  APP_UTILITY_READY,
+  PandaApp,
+  createAppSdk,
+  createUtilityProcessTransport
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@panda-agent/panda-app-sdk",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Panda 智能应用 SDK — iframe / Utility Process 客户端",
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"exports": {
+		"./browser": {
+			"types": "./dist/browser/index.d.ts",
+			"default": "./dist/browser/index.js"
+		},
+		"./node": {
+			"types": "./dist/node/index.d.ts",
+			"default": "./dist/node/index.js"
+		}
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "node scripts/build.mjs",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "npm run build && vitest run",
+		"verify-dist": "node scripts/verify-dist.mjs",
+		"vendor-fixtures": "node scripts/vendor-fixtures.mjs",
+		"prepack": "npm run build && npm run verify-dist",
+		"release:pack": "npm pack",
+		"release:publish": "node ./scripts/publish-app-sdk.mjs --tag latest",
+		"release:publish:dry-run": "node ./scripts/publish-app-sdk.mjs --tag latest --dry-run",
+		"release:publish:tester": "node ./scripts/publish-app-sdk.mjs --tag tester",
+		"release:publish:tester:dry-run": "node ./scripts/publish-app-sdk.mjs --tag tester --dry-run",
+		"prepublishOnly": "npm run typecheck && npm run test"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"esbuild": "^0.27.2",
+		"typescript": "~5.8.3",
+		"vitest": "^4.0.17"
+	}
+}