@xopcai/extension-ui-sdk 0.0.313 → 0.0.314

package/README.md

@@ -86,3 +86,44 @@ pnpm -C packages/extension-ui-sdk run docs
 ## License
 
 MIT
+# Pinned Local App capabilities
+
+Installed Local Apps may declare `ui.capabilities` entries with an exact `id`,
+`majorVersion`, and `descriptorDigest` from the authenticated Gateway catalog.
+Currently supported bindings are `xopc.notes.get`, `xopc.notes.list`,
+`xopc.tasks.get`, and `xopc.tasks.list` for reads, plus `xopc.notes.create`,
+`xopc.notes.update`, and `xopc.notes.append` for local writes. Wildcards, duplicate
+IDs, undeclared operations, and supplied implementation code are rejected.
+
+Bindings are included in the release source hash and permission review. Obtain a
+fresh acceptance result and user grant after changing the release. The UI host
+binds calls to its registered iframe and reviewed release; never embed Gateway
+credentials in the app or pass an extension identity, grant, or release digest
+as capability arguments.
+
+```ts
+const descriptor = await client.capability.describe('xopc.notes.list');
+const result = await client.capability.call(descriptor.id, {
+  majorVersion: descriptor.majorVersion,
+  descriptorDigest: descriptor.descriptorDigest,
+  input: { limit: 20 },
+});
+```
+
+The host refuses undeclared or changed contracts, disabled/uninstalled apps, and
+missing or revoked grants. A release switch or revocation during a read prevents
+delivery of its result. This API currently targets installed Local Apps, not
+arbitrary Node extensions. Writes require an explicit stable `idempotencyKey`;
+retain it after timeouts or unknown outcomes. Keys are isolated by caller, app,
+and installed release. Updates also require the current note revision.
+
+Agents use `xopc_use` with `mode: "local_app"`, `command: "capabilities"`, and
+`args: { extensionId }` to discover an already granted release. Invoke with
+`command: "invoke"` and `args: { extensionId, manifestDigest, capabilityId, call }`.
+Discovery never creates a grant. Both paths share the host dispatcher and release
+checks. Task writes, destructive actions, arbitrary backend registrations, and
+external writes are not exposed by these bindings.
+
+Release validation and installation reject stale host contract digests; refresh
+the binding and repeat acceptance before publishing. Rollback verifies the stored
+artifact source hash and contract compatibility without reversing business data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/extension-ui-sdk",
-  "version": "0.0.313",
+  "version": "0.0.314",
   "description": "Gateway Console extension UI SDK (iframe postMessage client)",
   "repository": {
     "type": "git",

package/src/client.test.ts

@@ -4,6 +4,16 @@ import { createExtensionClient } from './client.js';
 import type { Transport } from './transport.js';
 
 describe('extension client product navigation', () => {
+  it('forwards the pinned capability contract without attaching caller authority', async () => {
+    const request = vi.fn(async () => ({ status: 'succeeded', releaseId: 'release', data: {} }));
+    const client = createExtensionClient({ transport: { request } as unknown as Transport });
+    const call = { majorVersion: 1, descriptorDigest: 'a'.repeat(64), input: {} };
+    await client.capability.describe('xopc.notes.list');
+    await client.capability.call('xopc.notes.list', call);
+    expect(request.mock.calls).toEqual([
+      ['capability.describe', { id: 'xopc.notes.list' }], ['capability.call', { id: 'xopc.notes.list', call }],
+    ]);
+  });
   it('opens first-class product references through the host router', async () => {
     const request = vi.fn(async () => undefined);
     const transport = {

package/src/client.ts

@@ -14,6 +14,10 @@ export function createExtensionClient(options?: CreateExtensionClientOptions): E
   const transport = options?.transport ?? new Transport();
 
   const client: ExtensionClient = {
+    capability: {
+      describe: id => transport.request('capability.describe', { id }),
+      call: (id, call) => transport.request('capability.call', { id, call }),
+    },
     async whenReady() {
       await transport.ready;
     },

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { CapabilityCall, CapabilityDescriptor } from '@xopcai/gateway-contract';
+
 export enum ExtensionErrorCode {
   PermissionDenied = 4001,
   InvalidRequest = 4002,
@@ -62,6 +64,10 @@ export type ExtensionToHostMessage = ExtensionRequest | ExtensionEventMessage;
 export type StreamHandler = (payload: unknown) => void;
 
 export interface ExtensionClient {
+  capability: {
+    describe(id: string): Promise<CapabilityDescriptor>;
+    call(id: string, call: CapabilityCall): Promise<{ status: 'succeeded'; releaseId: string; data: unknown }>;
+  };
   whenReady(): Promise<void>;
   theme: {
     getTheme(): Promise<ThemeInfo>;