@seed-app-studio/sdk

SEED App Client SDK — unified API for interacting with SEED Agent Runtime across all platforms.

Transport Migration (JSON-RPC 2.0)

All transports have been migrated to JSON-RPC 2.0 as the wire protocol.

Available Transports

| Transport | Function | Platform | Wire Format | | -------------------- | ------------------------------------- | ----------------------------------------- | --------------------------------------- | | App Host window | createWindowSeedAppTransport() | App Studio iframe / browser host | SDK envelope over postMessage | | Electron IPC | createSeedAppElectronTransport() | Desktop Electron | JSON-RPC 2.0 over IPC | | Endpoint WebSocket | createSeedAppEndpointTransport() | Web SaaS endpoint / mobile remote runtime | JSON-RPC 2.0 over WebSocket | | Raw WebSocket | createSeedAppWebSocketTransport() | Web SaaS low-level socket clients | JSON-RPC 2.0 over WebSocket | | React Native WebView | createSeedAppReactNativeTransport() | Mobile embedded App Studio surface | JSON-RPC 2.0 over WebView postMessage |

Usage

import {
  createSeedAppClient,
  createSeedAppElectronTransport,
  createSeedAppEndpointTransport,
  createSeedAppReactNativeTransport,
} from "@seed-app-studio/sdk";

// Electron
const client = createSeedAppClient({
  transport: createSeedAppElectronTransport(),
});

// Web endpoint (SaaS / Mobile remote runtime); the browser sends its HttpOnly session cookie.
const client = createSeedAppClient({
  transport: createSeedAppEndpointTransport({
    endpoint: "wss://seed.example.com/v1/ws",
  }),
});

// React Native WebView
const client = createSeedAppClient({
  transport: createSeedAppReactNativeTransport(),
});

// All transports expose the same API
const agents = await client.agent.list();
const result = await client.agent.run({ input: "hello" });
const unsub = client.agent.subscribe((event) => console.log(event));

Never put credentials in a WebSocket URL. Web SaaS uses the browser session cookie by default. Local hosts with an explicit token should use the subprotocol credential strategy; custom Node WebSocket factories may use bearer. The legacy-query strategy exists only for compatibility and is deprecated.

Web SaaS Conversation Execution Policy

Web SaaS hosts can expose the experimental agent.permission.policy capability. When it is enabled, applications can read or update the execution policy of an existing conversation:

const current = await client.agent.executionPolicy.get({ conversationId });

await client.agent.executionPolicy.set({
  conversationId,
  mode: "ask", // "automatic" or "ask"
});

The server is authoritative for this setting. automatic skips only runtime confirmation requests that contain an explicit allow option; it never bypasses tenant, workspace, resource, provider, or other authorization checks. A change applies to the next submitted turn and does not change a turn that is already running. Clients must hide or disable this UI when agent.permission.policy is not enabled.

Migration from SeedBridge* Types

If your code references SeedBridgeElectronIpcFrame or SeedBridgeRequest/Result/Event:

1. Replace createSeedBridgeElectronIpcRequestFrame() → createJsonRpcRequest()
2. Replace parseSeedBridgeElectronIpcFrame() → deserializeJsonRpcFrame()
3. Replace serializeSeedBridgeElectronIpcFrame() → serializeJsonRpcFrame()
4. Replace SeedBridgeEvent handling → seed.event notification parsing

The SeedAppClient interface is unchanged — only the underlying transport serialization changed.

Dual-Format Compatibility

During the migration period, all adapters accept both JSON-RPC and legacy SeedBridge frames on ingress. New code MUST send JSON-RPC frames. Legacy frame support will be removed in a future release.

See: openspec/changes/unify-jsonrpc-bridge/ for the full migration plan.