@agentstage/bridge 0.1.0

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAMlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAoBtE"}

package/dist/vite/index.js

@@ -0,0 +1,23 @@
+import { join } from 'path';
+import { createBridgeGateway } from '../gateway/createBridgeGateway.js';
+export function bridgePlugin(options = {}) {
+    return {
+        name: 'agentstage-bridge',
+        configureServer(server) {
+            const pagesDir = options.pagesDir || join(process.cwd(), 'src', 'pages');
+            const gateway = createBridgeGateway({ pagesDir });
+            // 保存 gateway 引用供后续使用
+            server.bridgeGateway = gateway;
+            // 同步检查 httpServer 是否可用
+            if (server.httpServer) {
+                gateway.attach(server.httpServer);
+                console.log('[Bridge] WebSocket mounted at /_bridge');
+                console.log('[Bridge] Pages directory:', pagesDir);
+            }
+            else {
+                console.warn('[Bridge] httpServer not available during configureServer');
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAMxE,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,eAAe,CAAC,MAAqB;YACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YACzE,MAAM,OAAO,GAAG,mBAAmB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAElD,qBAAqB;YACpB,MAAc,CAAC,aAAa,GAAG,OAAO,CAAC;YAExC,uBAAuB;YACvB,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,UAAwC,CAAC,CAAC;gBAChE,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;gBACtD,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC;YACrD,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@agentstage/bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/gateway/index.d.ts",
+      "default": "./dist/gateway/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "default": "./dist/sdk/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:e2e": "vitest run test/e2e",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "crossws": "^0.4.4",
+    "ws": "^8.14.0",
+    "zod": "^3.22.0",
+    "zod-to-json-schema": "^3.22.0",
+    "zustand": "^4.5.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.33",
+    "@types/ws": "^8.5.0",
+    "get-port": "^7.0.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.4.21",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/browser/createBridgeStore.ts

@@ -0,0 +1,276 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { CreateBridgeStoreOptions, BridgeStore } from './types.js';
+import type { StoreDescription, GatewayMessage, ServerMessage } from '../shared/types.js';
+
+const WS_PATH = '/_bridge';
+
+function generateStoreId(pageId: string): string {
+  const random = Math.random().toString(36).substring(2, 10);
+  return `${pageId}#${random}`;
+}
+
+function getGatewayUrl(): string {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.host}${WS_PATH}?type=browser`;
+}
+
+export function createBridgeStore<
+  TState,
+  TActions extends Record<string, { payload?: unknown }> = Record<string, never>
+>(
+  options: CreateBridgeStoreOptions<TState, TActions>
+): BridgeStore<TState> {
+  const gatewayUrl = options.gatewayUrl;
+  const storeKey = options.storeKey || 'main';
+  const storeId = generateStoreId(options.pageId);
+
+  const store = createStore<TState>((set, get) =>
+    options.createState(
+      (fn) => set(fn(get())),
+      get
+    )
+  );
+
+  const description: StoreDescription = {
+    pageId: options.pageId,
+    storeKey,
+    schema: zodToJsonSchema(options.description.schema, { name: 'State' }),
+    actions: Object.fromEntries(
+      Object.entries(options.description.actions).map(([key, def]) => [
+        key,
+        {
+          description: def.description,
+          payload: def.payload
+            ? zodToJsonSchema(def.payload, { name: `${key}Payload` })
+            : undefined,
+        },
+      ])
+    ),
+    events: options.description.events
+      ? Object.fromEntries(
+          Object.entries(options.description.events).map(([key, def]) => [
+            key,
+            {
+              description: def.description,
+              payload: def.payload
+                ? zodToJsonSchema(def.payload, { name: `${key}Payload` })
+                : undefined,
+            },
+          ])
+        )
+      : undefined,
+  };
+
+  let ws: WebSocket | null = null;
+  let version = 0;
+  let isConnected = false;
+  let isHydrated = false;
+  let resolveHydration: (() => void) | null = null;
+  let hydrationPromise: Promise<void> | null = null;
+  let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+  let suppressNextPublish = false;
+
+  function send(message: GatewayMessage) {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(message));
+    }
+  }
+
+  function startHeartbeat() {
+    heartbeatInterval = setInterval(() => {
+      send({ type: 'store.heartbeat' });
+    }, 30000);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatInterval) {
+      clearInterval(heartbeatInterval);
+      heartbeatInterval = null;
+    }
+  }
+
+  function handleGatewayMessage(data: string) {
+    try {
+      const msg = JSON.parse(data) as ServerMessage;
+
+      switch (msg.type) {
+        case 'client.setState': {
+          const { state, expectedVersion, requestId, version: targetVersion } = msg.payload;
+          const canAck = typeof requestId === 'string' && requestId.length > 0;
+          if (expectedVersion !== undefined && expectedVersion !== version) {
+            if (canAck) {
+              send({
+                type: 'store.stateApplied',
+                payload: {
+                  storeId,
+                  requestId,
+                  status: 'version_mismatch',
+                  version,
+                },
+              });
+            }
+            return;
+          }
+          try {
+            suppressNextPublish = true;
+            store.setState(state as TState);
+            if (typeof targetVersion === 'number') {
+              version = targetVersion;
+            }
+            if (canAck) {
+              send({
+                type: 'store.stateApplied',
+                payload: {
+                  storeId,
+                  requestId,
+                  status: 'applied',
+                  version,
+                },
+              });
+            }
+          } catch (error) {
+            if (canAck) {
+              send({
+                type: 'store.stateApplied',
+                payload: {
+                  storeId,
+                  requestId,
+                  status: 'failed',
+                  version,
+                  error: error instanceof Error ? error.message : String(error),
+                },
+              });
+            }
+          }
+
+          // Mark as hydrated on first setState
+          if (!isHydrated) {
+            isHydrated = true;
+            resolveHydration?.();
+          }
+          break;
+        }
+
+        case 'client.dispatch': {
+          const { action } = msg.payload;
+          const current = store.getState();
+          if (typeof (current as any).dispatch === 'function') {
+            (current as any).dispatch(action);
+          }
+          break;
+        }
+
+        case 'client.ping':
+          break;
+      }
+    } catch (err) {
+      console.error('[BridgeStore] Failed to handle message:', err);
+    }
+  }
+
+  const unsubscribe = store.subscribe((state) => {
+    if (suppressNextPublish) {
+      suppressNextPublish = false;
+      return;
+    }
+    version += 1;
+    send({
+      type: 'store.stateChanged',
+      payload: {
+        storeId,
+        state,
+        version,
+        source: 'browser',
+      },
+    });
+  });
+
+  return {
+    store,
+
+    describes() {
+      return description;
+    },
+
+    get isConnected() {
+      return isConnected;
+    },
+
+    get isHydrated() {
+      return isHydrated;
+    },
+
+    connect(): Promise<{ storeId: string; disconnect: () => void }> {
+      return new Promise((resolve, reject) => {
+        if (ws?.readyState === WebSocket.OPEN) {
+          resolve({ storeId, disconnect: () => ws?.close() });
+          return;
+        }
+
+        const url = gatewayUrl || getGatewayUrl();
+        if (!url) {
+          reject(new Error('Cannot connect: gatewayUrl not provided and window is not available'));
+          return;
+        }
+
+        ws = new WebSocket(url);
+
+        ws.onopen = () => {
+          isConnected = true;
+
+          // Create hydration promise - resolves when first client.setState arrives
+          hydrationPromise = new Promise((resolveHydrationFn) => {
+            resolveHydration = resolveHydrationFn;
+          });
+
+          send({
+            type: 'store.register',
+            payload: {
+              storeId,
+              pageId: options.pageId,
+              storeKey,
+              description,
+              initialState: store.getState(),
+            },
+          });
+
+          startHeartbeat();
+        };
+
+        // Wait for hydration before resolving connect()
+        const checkHydration = async () => {
+          if (hydrationPromise) {
+            await hydrationPromise;
+          }
+          resolve({
+            storeId,
+            disconnect: () => {
+              send({ type: 'store.disconnect' });
+              stopHeartbeat();
+              unsubscribe();
+              ws?.close();
+            },
+          });
+        };
+        checkHydration();
+
+        ws.onmessage = (event) => {
+          handleGatewayMessage(event.data);
+        };
+
+        ws.onclose = () => {
+          isConnected = false;
+          stopHeartbeat();
+        };
+
+        ws.onerror = (err) => {
+          reject(err);
+        };
+      });
+    },
+  };
+}

package/src/browser/index.ts

@@ -0,0 +1,6 @@
+export { createBridgeStore } from './createBridgeStore.js';
+export type { 
+  CreateBridgeStoreOptions, 
+  BridgeStore,
+} from './types.js';
+export type { StoreDescription, StoreState } from '../shared/types.js';

package/src/browser/types.ts

@@ -0,0 +1,36 @@
+import type { StoreApi } from 'zustand/vanilla';
+import type { ZodSchema } from 'zod';
+import type { StoreDescription, StoreState } from '../shared/types.js';
+
+export interface CreateBridgeStoreOptions<
+  TState,
+  TActions extends Record<string, { payload?: unknown }>
+> {
+  gatewayUrl?: string;
+  pageId: string;
+  storeKey?: string;
+  description: {
+    schema: ZodSchema<TState>;
+    actions: {
+      [K in keyof TActions]: {
+        description: string;
+        payload?: ZodSchema<TActions[K]['payload']>;
+      }
+    };
+    events?: Record<string, { description: string; payload?: ZodSchema<unknown> }>;
+  };
+  createState: (
+    set: (fn: (state: TState) => Partial<TState>) => void,
+    get: () => TState
+  ) => TState;
+}
+
+export interface BridgeStore<TState> {
+  readonly store: StoreApi<TState>;
+  describes(): StoreDescription;
+  connect(): Promise<{ storeId: string; disconnect: () => void }>;
+  readonly isConnected: boolean;
+  readonly isHydrated: boolean;
+}
+
+export type { StoreDescription, StoreState };

package/src/gateway/apiHandler.ts

@@ -0,0 +1,107 @@
+import type { Gateway } from './types.js';
+
+export function createBridgeApiHandler(gateway: Gateway) {
+  return {
+    GET: async ({ request }: { request: Request }) => {
+      const url = new URL(request.url);
+      const path = url.pathname.replace('/api/bridge', '').split('/').filter(Boolean);
+      
+      if (path.length === 1 && path[0] === 'stores') {
+        return Response.json({ stores: gateway.listStores() });
+      }
+      
+      if (path.length === 2 && path[0] === 'stores') {
+        const storeId = path[1];
+        const store = gateway.getStore(storeId);
+        if (!store) {
+          return new Response(JSON.stringify({ error: 'Store not found' }), { 
+            status: 404,
+            headers: { 'Content-Type': 'application/json' }
+          });
+        }
+        return Response.json({
+          id: store.id,
+          pageId: store.pageId,
+          storeKey: store.storeKey,
+          description: store.description,
+          version: store.version,
+          connectedAt: store.connectedAt,
+          lastActivity: store.lastActivity,
+        });
+      }
+      
+      if (path.length === 3 && path[0] === 'stores' && path[2] === 'state') {
+        const storeId = path[1];
+        const state = gateway.getState(storeId);
+        if (!state) {
+          return new Response(JSON.stringify({ error: 'Store not found' }), { 
+            status: 404,
+            headers: { 'Content-Type': 'application/json' }
+          });
+        }
+        return Response.json(state);
+      }
+      
+      if (path.length === 3 && path[0] === 'pages' && path[2] === 'stores') {
+        const pageId = path[1];
+        const stores = gateway.stores;
+        const pageStores = Array.from(stores.values())
+          .filter(s => s.pageId === pageId)
+          .map(s => ({
+            id: s.id,
+            storeKey: s.storeKey,
+            version: s.version,
+            connectedAt: s.connectedAt,
+          }));
+        return Response.json({ stores: pageStores });
+      }
+      
+      return new Response(JSON.stringify({ error: 'Not found' }), { 
+        status: 404,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    },
+    
+    POST: async ({ request }: { request: Request }) => {
+      const url = new URL(request.url);
+      const path = url.pathname.replace('/api/bridge', '').split('/').filter(Boolean);
+      
+      if (path.length === 3 && path[0] === 'stores' && path[2] === 'state') {
+        const storeId = path[1];
+        const body = await request.json();
+        
+        try {
+          await gateway.setState(storeId, body.state, { 
+            expectedVersion: body.expectedVersion 
+          });
+          return Response.json({ ok: true });
+        } catch (err) {
+          return new Response(
+            JSON.stringify({ error: err instanceof Error ? err.message : 'Failed to set state' }), 
+            { status: 500, headers: { 'Content-Type': 'application/json' } }
+          );
+        }
+      }
+      
+      if (path.length === 3 && path[0] === 'stores' && path[2] === 'dispatch') {
+        const storeId = path[1];
+        const body = await request.json();
+        
+        try {
+          await gateway.dispatch(storeId, body.action);
+          return Response.json({ ok: true });
+        } catch (err) {
+          return new Response(
+            JSON.stringify({ error: err instanceof Error ? err.message : 'Failed to dispatch' }), 
+            { status: 500, headers: { 'Content-Type': 'application/json' } }
+          );
+        }
+      }
+      
+      return new Response(JSON.stringify({ error: 'Not found' }), { 
+        status: 404,
+        headers: { 'Content-Type': 'application/json' }
+      });
+    },
+  };
+}