@seed-app-studio/protocol

Transport-neutral bridge protocol contracts for SEED App Host, Electron, Web SaaS, and gateway runtimes.

JSON-RPC 2.0 Protocol

All cross-runtime communication uses JSON-RPC 2.0 as the single wire protocol.

Frame Types

| Type | Direction | Description | | ------------ | --------------- | --------------------------------------------------------- | | Request | Client → Server | { jsonrpc: "2.0", id, method, params? } | | Response | Server → Client | { jsonrpc: "2.0", id, result } | | Error | Server → Client | { jsonrpc: "2.0", id, error: { code, message, data? } } | | Notification | Server → Client | { jsonrpc: "2.0", method, params? } (no id) |

Core API

import {
  // Creation
  createJsonRpcRequest,
  createJsonRpcResponse,
  createJsonRpcError,
  createJsonRpcNotification,
  // Parsing
  parseJsonRpcFrame,
  deserializeJsonRpcFrame,
  // Serialization
  serializeJsonRpcFrame,
  // Validation
  validateJsonRpcRequest,
  // Error codes
  JSON_RPC_ERROR_CODES,
} from "@seed-app-studio/protocol";

Event Notifications

All events use method: "seed.event" with a canonical event catalog:

import {
  CANONICAL_EVENT_TYPES,
  createSeedEventNotification,
  validateCanonicalEvent,
  validateCanonicalEventMeta,
} from "@seed-app-studio/protocol";

const notification = createSeedEventNotification({
  type: CANONICAL_EVENT_TYPES.AGENT_MESSAGE_DELTA,
  runtime: 'electron', // or 'web-saas'
  payload: { conversationId, runId, content, role },
  meta: { traceId, eventId, seq?, tenantId?, userId? },
});

Transport Contracts

| Runtime | Transport | Auth | Channel | | ------------ | ----------- | ------------------- | --------------------- | | electron | IPC | preload-main | seed-bridge-adapter | | web-saas | WebSocket | session-cookie | /v1/ws | | local-webui | WebSocket | local-session | localhost:25809 | | react-native | WebView | manifest-capability | postMessage | | app-host | postMessage | manifest-capability | postMessage |

Migration Note

Legacy SeedBridgeRequest / SeedBridgeResult / SeedBridgeEvent types are @deprecated. They are retained only for migration-boundary conversion. New code MUST use JSON-RPC 2.0 frames.

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