@panda-agent/panda-app-sdk 0.1.0 → 0.4.0

package/dist/node/index.d.ts

@@ -3,7 +3,8 @@ export { createAppSdk } from './create-app-sdk.js';
 export { createUtilityProcessTransport } from './transport/utility-process.js';
 export type * from './types.js';
 export declare const PandaApp: {
-    connectUtilityProcess(): {
+    connect: () => {
+        ready: () => Promise<void>;
         auth: {
             getCurrentUser: () => Promise<import("./types.js").AppUser | null>;
         };
@@ -17,6 +18,7 @@ export declare const PandaApp: {
                 scene?: string;
                 preferredModelId?: string;
             }) => Promise<import("./types.js").ModelListItem | null>;
+            chat: (request: import("./types.js").ModelChatRequest) => Promise<import("./types.js").ModelChatResult>;
         };
         workspace: {
             list: (request: {
@@ -28,9 +30,32 @@ export declare const PandaApp: {
                 touch?: boolean;
             }) => Promise<import("./types.js").WorkspaceListItem>;
         };
+        artifacts: {
+            list: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsListResult>;
+            snapshot: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsSnapshotResult>;
+            readText: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadTextResult>;
+            readDataUrl: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadDataUrlResult>;
+        };
+        conversationData: {
+            readActivity: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationActivityQuery) => Promise<import("./types.js").ConversationActivity>;
+            listConversations: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            readRecords: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationRecordsQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataRecord>>;
+            readRecord: (ref: import("./types.js").ConversationRef, recordId: string, query?: import("./types.js").ConversationRecordQuery) => Promise<import("./types.js").ConversationDataRecord>;
+            getRuntime: (ref: import("./types.js").ConversationRef, options?: {
+                streamingPreview?: boolean;
+            }) => Promise<import("./types.js").ConversationRuntimeObservation>;
+            listRuntime: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            getLocations: (ref: import("./types.js").ConversationRef) => Promise<import("./types.js").ConversationRecordLocation[]>;
+        };
         conversation: {
+            create: (options?: import("./types.js").CreateConversationOptions) => Promise<import("./types.js").CreateConversationResult>;
             createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
             disposeForApp: (conversationId: string) => Promise<unknown>;
+            listForApp: (workspaceId?: string) => Promise<unknown>;
+            attach: (conversationId: string) => Promise<{
+                conversationId: string;
+            }>;
+            detach: (conversationId: string) => Promise<unknown>;
             submitMessage: (conversationId: string, prompt: string) => Promise<unknown>;
             getMessages: (conversationId: string) => Promise<unknown>;
             subscribe: (options: import("./types.js").ConversationSubscribeOptions & {
@@ -46,9 +71,16 @@ export declare const PandaApp: {
             }) => Promise<unknown>;
         };
         session: {
-            mount: (conversationId: string, appId: string, replaceConfirmed?: boolean) => Promise<unknown>;
-            unmount: (conversationId: string) => Promise<unknown>;
-            getMount: (conversationId: string) => Promise<unknown>;
+            getContext: () => Promise<import("./types.js").SessionContext>;
+            mount: (conversationId: string, appId: string) => Promise<unknown>;
+            unmount: (conversationId: string, appId: string) => Promise<unknown>;
+            listMounts: (conversationId: string) => Promise<unknown>;
+        };
+        todo: {
+            get: (conversationId: string) => Promise<import("./types.js").TodoSnapshot>;
+        };
+        memory: {
+            listSessionEntries: (conversationId: string) => Promise<import("./types.js").MemorySessionEntries>;
         };
         ingress: {
             submit: (conversationId: string, prompt: string) => Promise<{
@@ -56,6 +88,37 @@ export declare const PandaApp: {
                 status: string;
             }>;
         };
+        agent: {
+            invokeSkill: (request: import("./types.js").InvokeSkillRequest) => Promise<import("./types.js").InvokeSkillResult>;
+            invokeSubagent: (request: import("./types.js").InvokeSubagentRequest) => Promise<import("./types.js").InvokeSubagentResult>;
+            cancelSubagent: (invocationId: string) => Promise<import("./types.js").CancelSubagentResult>;
+        };
+        ui: {
+            theme: () => Promise<import("./types.js").AppUiThemeResult>;
+            openExternal: (url: string) => Promise<void>;
+            sessionSurface: {
+                getState: () => Promise<import("./types.js").SessionSurfaceState>;
+                show: (options?: {
+                    activate?: boolean;
+                    reason?: string;
+                }) => Promise<unknown>;
+                collapse: () => Promise<unknown>;
+            };
+        };
+        storage: {
+            global: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+            session: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+        };
         tools: {
             list: (request: {
                 workspace?: import("./types.js").WorkspaceRef;
@@ -100,7 +163,190 @@ export declare const PandaApp: {
                 homeDir: string;
                 pandaVersion: string;
                 appSdkVersion: string;
+                capabilities?: {
+                    invocationToolPolicy?: boolean;
+                    appPrivateMcp?: boolean;
+                };
+            }>;
+            supports: (requiredVersion: string) => Promise<boolean>;
+        };
+        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>;
+        };
+    };
+    /** @deprecated Use PandaApp.connect() instead. */
+    connectUtilityProcess: () => {
+        ready: () => Promise<void>;
+        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>;
+            chat: (request: import("./types.js").ModelChatRequest) => Promise<import("./types.js").ModelChatResult>;
+        };
+        workspace: {
+            list: (request: {
+                limit: number;
+                includeEphemeral?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem[]>;
+            ensureLocal: (request: {
+                path: string;
+                touch?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem>;
+        };
+        artifacts: {
+            list: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsListResult>;
+            snapshot: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsSnapshotResult>;
+            readText: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadTextResult>;
+            readDataUrl: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadDataUrlResult>;
+        };
+        conversationData: {
+            readActivity: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationActivityQuery) => Promise<import("./types.js").ConversationActivity>;
+            listConversations: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            readRecords: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationRecordsQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataRecord>>;
+            readRecord: (ref: import("./types.js").ConversationRef, recordId: string, query?: import("./types.js").ConversationRecordQuery) => Promise<import("./types.js").ConversationDataRecord>;
+            getRuntime: (ref: import("./types.js").ConversationRef, options?: {
+                streamingPreview?: boolean;
+            }) => Promise<import("./types.js").ConversationRuntimeObservation>;
+            listRuntime: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            getLocations: (ref: import("./types.js").ConversationRef) => Promise<import("./types.js").ConversationRecordLocation[]>;
+        };
+        conversation: {
+            create: (options?: import("./types.js").CreateConversationOptions) => Promise<import("./types.js").CreateConversationResult>;
+            createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
+            disposeForApp: (conversationId: string) => Promise<unknown>;
+            listForApp: (workspaceId?: string) => Promise<unknown>;
+            attach: (conversationId: string) => Promise<{
+                conversationId: string;
+            }>;
+            detach: (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: {
+            getContext: () => Promise<import("./types.js").SessionContext>;
+            mount: (conversationId: string, appId: string) => Promise<unknown>;
+            unmount: (conversationId: string, appId: string) => Promise<unknown>;
+            listMounts: (conversationId: string) => Promise<unknown>;
+        };
+        todo: {
+            get: (conversationId: string) => Promise<import("./types.js").TodoSnapshot>;
+        };
+        memory: {
+            listSessionEntries: (conversationId: string) => Promise<import("./types.js").MemorySessionEntries>;
+        };
+        ingress: {
+            submit: (conversationId: string, prompt: string) => Promise<{
+                conversationId: string;
+                status: string;
+            }>;
+        };
+        agent: {
+            invokeSkill: (request: import("./types.js").InvokeSkillRequest) => Promise<import("./types.js").InvokeSkillResult>;
+            invokeSubagent: (request: import("./types.js").InvokeSubagentRequest) => Promise<import("./types.js").InvokeSubagentResult>;
+            cancelSubagent: (invocationId: string) => Promise<import("./types.js").CancelSubagentResult>;
+        };
+        ui: {
+            theme: () => Promise<import("./types.js").AppUiThemeResult>;
+            openExternal: (url: string) => Promise<void>;
+            sessionSurface: {
+                getState: () => Promise<import("./types.js").SessionSurfaceState>;
+                show: (options?: {
+                    activate?: boolean;
+                    reason?: string;
+                }) => Promise<unknown>;
+                collapse: () => Promise<unknown>;
+            };
+        };
+        storage: {
+            global: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+            session: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+        };
+        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;
+                capabilities?: {
+                    invocationToolPolicy?: boolean;
+                    appPrivateMcp?: boolean;
+                };
             }>;
+            supports: (requiredVersion: string) => Promise<boolean>;
         };
         dialog: {
             showOpen: (request?: import("./types.js").DialogShowOpenRequest) => Promise<import("./types.js").DialogShowOpenResult>;

package/dist/node/index.js

@@ -4,30 +4,75 @@ var APP_UTILITY_INVOKE_RESULT = "app-utility:invoke-result";
 var APP_UTILITY_READY = "app-utility:ready";
 var APP_UTILITY_EVENT = "app-utility:event";
 
+// src/semver.ts
+function compareSemver(v1, v2) {
+  const parse = (v) => {
+    const parts = v.split(".");
+    const nums = [];
+    for (let i = 0; i < 3; i++) {
+      const n = parseInt(parts[i] ?? "0", 10);
+      nums.push(Number.isFinite(n) ? n : 0);
+    }
+    return nums;
+  };
+  const a = parse(v1);
+  const b = parse(v2);
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
 // src/create-app-sdk.ts
 function createAppSdk(transport) {
+  const policyPreflights = /* @__PURE__ */ new Map();
+  let ready;
   return {
+    /** Report this side ready. Initialization and the first usable render must finish before calling. */
+    ready: () => ready ??= transport.ready ? transport.ready() : Promise.reject(new Error("This Panda host does not support App readiness")),
     auth: {
       getCurrentUser: () => transport.invoke("auth.getCurrentUser", [])
     },
     model: {
       list: (options) => transport.invoke("model.list", [options ?? {}]),
-      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}])
+      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}]),
+      chat: (request) => transport.invoke("model.chat", [request])
     },
     workspace: {
       list: (request) => transport.invoke("workspace.list", [request]),
       ensureLocal: (request) => transport.invoke("workspace.ensureLocal", [request])
     },
+    artifacts: {
+      list: (request) => transport.invoke("artifacts.list", [request]),
+      snapshot: (request) => transport.invoke("artifacts.snapshot", [request]),
+      readText: (request) => transport.invoke("artifacts.readText", [request]),
+      readDataUrl: (request) => transport.invoke("artifacts.readDataUrl", [request])
+    },
+    conversationData: {
+      readActivity: (ref, query) => transport.invoke("conversationData.readActivity", [ref, query]),
+      listConversations: (query) => transport.invoke("conversationData.listConversations", [query ?? {}]),
+      readRecords: (ref, query) => transport.invoke("conversationData.readRecords", [ref, query]),
+      readRecord: (ref, recordId, query) => transport.invoke("conversationData.readRecord", [ref, recordId, query ?? {}]),
+      getRuntime: (ref, options) => transport.invoke("conversationData.getRuntime", [ref, options ?? {}]),
+      listRuntime: (query) => transport.invoke("conversationData.listRuntime", [query ?? {}]),
+      getLocations: (ref) => transport.invoke("conversationData.getLocations", [ref])
+    },
     conversation: {
+      create: (options) => transport.invoke("conversation.create", [options ?? {}]),
       createForApp: (options) => transport.invoke("conversation.createForApp", [options ?? {}]),
       disposeForApp: (conversationId) => transport.invoke("conversation.disposeForApp", [conversationId]),
+      listForApp: (workspaceId) => transport.invoke("conversation.listForApp", workspaceId === void 0 ? [] : [workspaceId]),
+      attach: (conversationId) => transport.invoke("conversation.attach", [conversationId]),
+      detach: (conversationId) => transport.invoke("conversation.detach", [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]);
+        const { onEvent, ...request } = options;
+        const result = await transport.invoke("conversation.subscribe", [request]);
         let offEvent;
-        if (options.onEvent) {
-          offEvent = transport.subscribe(result.subscriptionId, options.onEvent);
+        if (onEvent) {
+          offEvent = transport.subscribe(result.subscriptionId, onEvent);
         }
         return {
           subscriptionId: result.subscriptionId,
@@ -40,20 +85,85 @@ function createAppSdk(transport) {
       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])
+      getContext: () => transport.invoke("session.getContext", []),
+      mount: (conversationId, appId) => transport.invoke("mountSession", [conversationId, appId]),
+      unmount: (conversationId, appId) => transport.invoke("unmountSession", [conversationId, appId]),
+      listMounts: (conversationId) => transport.invoke("listSessionMounts", [conversationId])
+    },
+    todo: {
+      get: (conversationId) => transport.invoke("todo.get", [conversationId])
+    },
+    memory: {
+      listSessionEntries: (conversationId) => transport.invoke("memory.listSessionEntries", [conversationId])
     },
     ingress: {
       submit: (conversationId, prompt) => transport.invoke("ingress.submit", [conversationId, prompt])
     },
+    agent: {
+      invokeSkill: (request) => transport.invoke("agent.invokeSkill", [request]),
+      invokeSubagent: async (request) => {
+        const restricted = request.allowedTools !== void 0 || request.readableFiles !== void 0;
+        const id = restricted ? request.invocationId?.trim() : void 0;
+        if (id && policyPreflights.has(id)) throw new Error("Duplicate subagent invocationId");
+        const pending = { cancelled: false };
+        if (id) policyPreflights.set(id, pending);
+        try {
+          if (restricted) {
+            const host = await transport.invoke("runtime.getHost", []);
+            if (pending.cancelled) throw new Error("Subagent cancelled before dispatch");
+            if (host?.capabilities?.invocationToolPolicy !== true) {
+              throw Object.assign(new Error("Host does not support invocation tool policies; refusing an unrestricted fallback"), { code: "APP_HOST_CAPABILITY_REQUIRED" });
+            }
+          }
+          if (id) policyPreflights.delete(id);
+          return await transport.invoke("agent.invokeSubagent", [request]);
+        } finally {
+          if (id && policyPreflights.get(id) === pending) policyPreflights.delete(id);
+        }
+      },
+      cancelSubagent: async (invocationId) => {
+        const pending = policyPreflights.get(invocationId.trim());
+        if (pending) {
+          pending.cancelled = true;
+          return { cancelled: true };
+        }
+        return transport.invoke("agent.cancelSubagent", [{ invocationId }]);
+      }
+    },
+    ui: {
+      theme: () => transport.invoke("ui.theme", []),
+      openExternal: (url) => transport.invoke("ui.openExternal", [{ url }]),
+      sessionSurface: {
+        getState: () => transport.invoke("ui.sessionSurface.getState", []),
+        show: (options) => transport.invoke("ui.sessionSurface.show", [options ?? {}]),
+        collapse: () => transport.invoke("ui.sessionSurface.collapse", [])
+      }
+    },
+    storage: {
+      global: {
+        get: (key) => transport.invoke("storage.global.get", [key]),
+        set: (key, value) => transport.invoke("storage.global.set", [key, value]),
+        delete: (key) => transport.invoke("storage.global.delete", [key]),
+        list: (prefix) => transport.invoke("storage.global.list", prefix === void 0 ? [] : [prefix])
+      },
+      session: {
+        get: (key) => transport.invoke("storage.session.get", [key]),
+        set: (key, value) => transport.invoke("storage.session.set", [key, value]),
+        delete: (key) => transport.invoke("storage.session.delete", [key]),
+        list: (prefix) => transport.invoke("storage.session.list", prefix === void 0 ? [] : [prefix])
+      }
+    },
     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", [])
+      getHost: () => transport.invoke("runtime.getHost", []),
+      supports: async (requiredVersion) => {
+        const host = await transport.invoke("runtime.getHost", []);
+        return compareSemver(host.appSdkVersion, requiredVersion) >= 0;
+      }
     },
     dialog: {
       showOpen: (request) => transport.invoke("dialog.showOpen", [request ?? {}]),
@@ -105,11 +215,21 @@ function newRequestId() {
 // src/transport/shared/pending-invoke.ts
 function createPendingInvoke(newRequestId2) {
   const pending = /* @__PURE__ */ new Map();
-  function invoke(postMessage, invokeType, path, args) {
+  function invoke(postMessage, invokeType, path, args, timeoutMs) {
     const requestId = newRequestId2();
     return new Promise((resolve, reject) => {
-      pending.set(requestId, { resolve, reject });
-      postMessage({ type: invokeType, requestId, path, args });
+      const timer = timeoutMs ? setTimeout(() => {
+        pending.delete(requestId);
+        reject(new Error("App ready acknowledgement timed out; update or reopen the Panda host"));
+      }, timeoutMs) : void 0;
+      pending.set(requestId, { resolve, reject, timer });
+      try {
+        postMessage({ type: invokeType, requestId, path, args });
+      } catch (error) {
+        pending.delete(requestId);
+        clearTimeout(timer);
+        reject(error);
+      }
     });
   }
   function handleInvokeResult(message) {
@@ -121,6 +241,7 @@ function createPendingInvoke(newRequestId2) {
       return;
     }
     pending.delete(message.requestId);
+    clearTimeout(entry.timer);
     if (message.ok) {
       entry.resolve(message.result);
     } else {
@@ -185,6 +306,9 @@ function createUtilityProcessTransport() {
     }
   });
   return {
+    ready: async () => {
+      await createInvoke((message) => parentPort.postMessage(message), APP_UTILITY_READY, "app.ready", [], 3e4);
+    },
     invoke(path, args) {
       return createInvoke(
         (message) => {
@@ -200,10 +324,11 @@ function createUtilityProcessTransport() {
 }
 
 // src/node.ts
+var connect = () => createAppSdk(createUtilityProcessTransport());
 var PandaApp = {
-  connectUtilityProcess() {
-    return createAppSdk(createUtilityProcessTransport());
-  }
+  connect,
+  /** @deprecated Use PandaApp.connect() instead. */
+  connectUtilityProcess: connect
 };
 export {
   APP_UTILITY_EVENT,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@panda-agent/panda-app-sdk",
-	"version": "0.1.0",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Panda 智能应用 SDK — iframe / Utility Process 客户端",
 	"license": "MIT",