@giselles-ai/browser-tool 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ExecutionReport = {
     warnings: string[];
 };
 type BrowserToolStatus = "idle" | "snapshotting" | "planning" | "ready" | "applying" | "error";
-type BridgeErrorCode = "UNAUTHORIZED" | "NO_BROWSER" | "TIMEOUT" | "INVALID_RESPONSE" | "NOT_FOUND" | "INTERNAL";
+type RelayErrorCode = "UNAUTHORIZED" | "NO_BROWSER" | "TIMEOUT" | "INVALID_RESPONSE" | "NOT_FOUND" | "INTERNAL";
 declare const fieldKindSchema: z.ZodEnum<{
     text: "text";
     textarea: "textarea";
@@ -128,7 +128,7 @@ declare const executeRequestSchema: z.ZodObject<{
         options: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-declare const bridgeRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+declare const relayRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"snapshot_request">;
     requestId: z.ZodString;
     instruction: z.ZodString;
@@ -201,7 +201,7 @@ declare const errorResponseSchema: z.ZodObject<{
     requestId: z.ZodString;
     message: z.ZodString;
 }, z.core.$strip>;
-declare const bridgeResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+declare const relayResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"snapshot_response">;
     requestId: z.ZodString;
     fields: z.ZodArray<z.ZodObject<{
@@ -275,7 +275,7 @@ declare const dispatchErrorSchema: z.ZodObject<{
     errorCode: z.ZodUnion<readonly [z.ZodLiteral<"UNAUTHORIZED">, z.ZodLiteral<"NO_BROWSER">, z.ZodLiteral<"TIMEOUT">, z.ZodLiteral<"INVALID_RESPONSE">, z.ZodLiteral<"NOT_FOUND">, z.ZodLiteral<"INTERNAL">]>;
     message: z.ZodString;
 }, z.core.$strip>;
-type BridgeRequest = z.infer<typeof bridgeRequestSchema>;
-type BridgeResponse = z.infer<typeof bridgeResponseSchema>;
+type RelayRequest = z.infer<typeof relayRequestSchema>;
+type RelayResponse = z.infer<typeof relayResponseSchema>;
 
-export { type BridgeErrorCode, type BridgeRequest, type BridgeResponse, type BrowserToolAction, type BrowserToolStatus, type ClickAction, type ExecutionReport, type FieldKind, type FillAction, type SelectAction, type SnapshotField, bridgeRequestSchema, bridgeResponseSchema, browserToolActionSchema, clickActionSchema, dispatchErrorSchema, dispatchSuccessSchema, errorResponseSchema, executeRequestSchema, executeResponseSchema, executionReportSchema, fieldKindSchema, fillActionSchema, selectActionSchema, snapshotFieldSchema, snapshotRequestSchema, snapshotResponseSchema };
+export { type BrowserToolAction, type BrowserToolStatus, type ClickAction, type ExecutionReport, type FieldKind, type FillAction, type RelayErrorCode, type RelayRequest, type RelayResponse, type SelectAction, type SnapshotField, browserToolActionSchema, clickActionSchema, dispatchErrorSchema, dispatchSuccessSchema, errorResponseSchema, executeRequestSchema, executeResponseSchema, executionReportSchema, fieldKindSchema, fillActionSchema, relayRequestSchema, relayResponseSchema, selectActionSchema, snapshotFieldSchema, snapshotRequestSchema, snapshotResponseSchema };

package/dist/index.js

@@ -54,7 +54,7 @@ var executeRequestSchema = z.object({
   actions: z.array(browserToolActionSchema),
   fields: z.array(snapshotFieldSchema)
 });
-var bridgeRequestSchema = z.discriminatedUnion("type", [
+var relayRequestSchema = z.discriminatedUnion("type", [
   snapshotRequestSchema,
   executeRequestSchema
 ]);
@@ -73,14 +73,14 @@ var errorResponseSchema = z.object({
   requestId: z.string().min(1),
   message: z.string().min(1)
 });
-var bridgeResponseSchema = z.discriminatedUnion("type", [
+var relayResponseSchema = z.discriminatedUnion("type", [
   snapshotResponseSchema,
   executeResponseSchema,
   errorResponseSchema
 ]);
 var dispatchSuccessSchema = z.object({
   ok: z.literal(true),
-  response: bridgeResponseSchema
+  response: relayResponseSchema
 });
 var dispatchErrorSchema = z.object({
   ok: z.literal(false),
@@ -95,8 +95,6 @@ var dispatchErrorSchema = z.object({
   message: z.string()
 });
 export {
-  bridgeRequestSchema,
-  bridgeResponseSchema,
   browserToolActionSchema,
   clickActionSchema,
   dispatchErrorSchema,
@@ -107,6 +105,8 @@ export {
   executionReportSchema,
   fieldKindSchema,
   fillActionSchema,
+  relayRequestSchema,
+  relayResponseSchema,
   selectActionSchema,
   snapshotFieldSchema,
   snapshotRequestSchema,

package/dist/mcp-server/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/mcp-server/bridge-client.ts
+// src/mcp-server/relay-client.ts
 import { randomUUID } from "crypto";
 
 // src/types.ts
@@ -61,7 +61,7 @@ var executeRequestSchema = z.object({
   actions: z.array(browserToolActionSchema),
   fields: z.array(snapshotFieldSchema)
 });
-var bridgeRequestSchema = z.discriminatedUnion("type", [
+var relayRequestSchema = z.discriminatedUnion("type", [
   snapshotRequestSchema,
   executeRequestSchema
 ]);
@@ -80,14 +80,14 @@ var errorResponseSchema = z.object({
   requestId: z.string().min(1),
   message: z.string().min(1)
 });
-var bridgeResponseSchema = z.discriminatedUnion("type", [
+var relayResponseSchema = z.discriminatedUnion("type", [
   snapshotResponseSchema,
   executeResponseSchema,
   errorResponseSchema
 ]);
 var dispatchSuccessSchema = z.object({
   ok: z.literal(true),
-  response: bridgeResponseSchema
+  response: relayResponseSchema
 });
 var dispatchErrorSchema = z.object({
   ok: z.literal(false),
@@ -102,7 +102,7 @@ var dispatchErrorSchema = z.object({
   message: z.string()
 });
 
-// src/mcp-server/bridge-client.ts
+// src/mcp-server/relay-client.ts
 function requiredEnv(name) {
   const value = process.env[name]?.trim();
   if (!value) {
@@ -113,15 +113,15 @@ function requiredEnv(name) {
 function trimTrailingSlash(input) {
   return input.replace(/\/+$/, "");
 }
-var BridgeClient = class {
-  baseUrl;
+var RelayClient = class {
+  url;
   sessionId;
   token;
   timeoutMs;
   vercelProtectionBypass;
   giselleProtectionBypass;
   constructor(input) {
-    this.baseUrl = trimTrailingSlash(input.baseUrl);
+    this.url = trimTrailingSlash(input.url);
     this.sessionId = input.sessionId;
     this.token = input.token;
     this.timeoutMs = input.timeoutMs ?? 2e4;
@@ -136,7 +136,7 @@ var BridgeClient = class {
       document: input.document
     });
     if (response.type !== "snapshot_response") {
-      throw new Error(`Unexpected bridge response type: ${response.type}`);
+      throw new Error(`Unexpected relay response type: ${response.type}`);
     }
     return response.fields;
   }
@@ -148,12 +148,12 @@ var BridgeClient = class {
       fields: input.fields
     });
     if (response.type !== "execute_response") {
-      throw new Error(`Unexpected bridge response type: ${response.type}`);
+      throw new Error(`Unexpected relay response type: ${response.type}`);
     }
     return response.report;
   }
   async dispatch(request) {
-    const payload = bridgeRequestSchema.parse(request);
+    const payload = relayRequestSchema.parse(request);
     let response;
     try {
       const headers = {
@@ -165,11 +165,11 @@ var BridgeClient = class {
       if (this.giselleProtectionBypass) {
         headers["x-giselle-protection-bypass"] = this.giselleProtectionBypass;
       }
-      response = await fetch(`${this.baseUrl}`, {
+      response = await fetch(`${this.url}`, {
         method: "POST",
         headers,
         body: JSON.stringify({
-          type: "bridge.dispatch",
+          type: "relay.dispatch",
           sessionId: this.sessionId,
           token: this.token,
           timeoutMs: this.timeoutMs,
@@ -180,9 +180,9 @@ var BridgeClient = class {
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(
         [
-          "Bridge dispatch network request failed.",
-          `baseUrl=${this.baseUrl}`,
-          "Ensure BROWSER_TOOL_BRIDGE_BASE_URL is reachable from the sandbox runtime.",
+          "Relay dispatch network request failed.",
+          `url=${this.url}`,
+          "Ensure BROWSER_TOOL_RELAY_URL is reachable from the sandbox runtime.",
           `cause=${message}`
         ].join(" ")
       );
@@ -194,28 +194,28 @@ var BridgeClient = class {
     }
     const success = dispatchSuccessSchema.safeParse(body);
     if (!success.success) {
-      throw new Error("Bridge dispatch returned an unexpected payload.");
+      throw new Error("Relay dispatch returned an unexpected payload.");
     }
     if (!response.ok) {
-      throw new Error(`Bridge dispatch failed with HTTP ${response.status}.`);
+      throw new Error(`Relay dispatch failed with HTTP ${response.status}.`);
     }
-    const parsedResponse = bridgeResponseSchema.parse(success.data.response);
+    const parsedResponse = relayResponseSchema.parse(success.data.response);
     return parsedResponse;
   }
 };
-function createBridgeClientFromEnv() {
+function createRelayClientFromEnv() {
   const vercelProtectionBypass = process.env.VERCEL_PROTECTION_BYPASS;
   const giselleProtectionBypass = process.env.GISELLE_PROTECTION_BYPASS;
   console.error(
-    `[bridge-client] VERCEL_PROTECTION_BYPASS=${vercelProtectionBypass?.trim() ? "(set)" : "(unset)"}`
+    `[relay-client] VERCEL_PROTECTION_BYPASS=${vercelProtectionBypass?.trim() ? "(set)" : "(unset)"}`
   );
   console.error(
-    `[bridge-client] GISELLE_PROTECTION_BYPASS=${giselleProtectionBypass?.trim() ? "(set)" : "(unset)"}`
+    `[relay-client] GISELLE_PROTECTION_BYPASS=${giselleProtectionBypass?.trim() ? "(set)" : "(unset)"}`
   );
-  return new BridgeClient({
-    baseUrl: requiredEnv("BROWSER_TOOL_BRIDGE_BASE_URL"),
-    sessionId: requiredEnv("BROWSER_TOOL_BRIDGE_SESSION_ID"),
-    token: requiredEnv("BROWSER_TOOL_BRIDGE_TOKEN"),
+  return new RelayClient({
+    url: requiredEnv("BROWSER_TOOL_RELAY_URL"),
+    sessionId: requiredEnv("BROWSER_TOOL_RELAY_SESSION_ID"),
+    token: requiredEnv("BROWSER_TOOL_RELAY_TOKEN"),
     vercelProtectionBypass,
     giselleProtectionBypass
   });
@@ -228,17 +228,17 @@ var executeFormActionsInputShape = {
   fields: z2.array(snapshotFieldSchema)
 };
 var executeFormActionsInputSchema = z2.object(executeFormActionsInputShape);
-async function runExecuteFormActions(input, bridgeClient) {
+async function runExecuteFormActions(input, relayClient) {
   const parsed = executeFormActionsInputSchema.parse(input);
-  return await bridgeClient.requestExecute({
+  return await relayClient.requestExecute({
     actions: parsed.actions,
     fields: parsed.fields
   });
 }
 
 // src/mcp-server/tools/get-form-snapshot.ts
-async function runGetFormSnapshot(bridgeClient) {
-  const fields = await bridgeClient.requestSnapshot({
+async function runGetFormSnapshot(relayClient) {
+  const fields = await relayClient.requestSnapshot({
     instruction: "snapshot"
   });
   return { fields };
@@ -274,8 +274,8 @@ var server = new McpServer(
 );
 server.registerTool("getFormSnapshot", {}, async () => {
   try {
-    const bridgeClient = createBridgeClientFromEnv();
-    const output = await runGetFormSnapshot(bridgeClient);
+    const relayClient = createRelayClientFromEnv();
+    const output = await runGetFormSnapshot(relayClient);
     return {
       content: [
         {
@@ -308,8 +308,8 @@ server.registerTool(
   { inputSchema: executeFormActionsInputShape },
   async (input) => {
     try {
-      const bridgeClient = createBridgeClientFromEnv();
-      const output = await runExecuteFormActions(input, bridgeClient);
+      const relayClient = createRelayClientFromEnv();
+      const output = await runExecuteFormActions(input, relayClient);
       return {
         content: [
           {

package/dist/relay/index.d.ts

@@ -0,0 +1,25 @@
+import Redis from 'ioredis';
+
+declare function createRelayHandler(): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+
+type RelayErrorCode = "UNAUTHORIZED" | "NO_BROWSER" | "TIMEOUT" | "INVALID_RESPONSE" | "NOT_FOUND" | "INTERNAL";
+
+declare global {
+    var __browserToolRelayRedis: Redis | undefined;
+}
+declare class RelayStoreError extends Error {
+    readonly code: RelayErrorCode;
+    readonly status: number;
+    constructor(code: RelayErrorCode, message: string, status: number);
+}
+declare function createRelaySession(): Promise<{
+    sessionId: string;
+    token: string;
+    expiresAt: number;
+}>;
+declare function toRelayError(error: unknown): RelayStoreError;
+
+export { createRelayHandler, createRelaySession, toRelayError };

package/dist/relay/index.js

@@ -0,0 +1,758 @@
+// src/relay/relay-handler.ts
+import { z as z2 } from "zod";
+
+// src/types.ts
+import { z } from "zod";
+var fieldKindSchema = z.enum([
+  "text",
+  "textarea",
+  "select",
+  "checkbox",
+  "radio"
+]);
+var snapshotFieldSchema = z.object({
+  fieldId: z.string().min(1),
+  selector: z.string().min(1),
+  kind: fieldKindSchema,
+  label: z.string().min(1),
+  name: z.string().optional(),
+  required: z.boolean(),
+  placeholder: z.string().optional(),
+  currentValue: z.union([z.string(), z.boolean()]),
+  options: z.array(z.string()).optional()
+});
+var fillActionSchema = z.object({
+  action: z.literal("fill"),
+  fieldId: z.string().min(1),
+  value: z.string()
+});
+var clickActionSchema = z.object({
+  action: z.literal("click"),
+  fieldId: z.string().min(1)
+});
+var selectActionSchema = z.object({
+  action: z.literal("select"),
+  fieldId: z.string().min(1),
+  value: z.string()
+});
+var browserToolActionSchema = z.discriminatedUnion("action", [
+  fillActionSchema,
+  clickActionSchema,
+  selectActionSchema
+]);
+var executionReportSchema = z.object({
+  applied: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  warnings: z.array(z.string())
+});
+var snapshotRequestSchema = z.object({
+  type: z.literal("snapshot_request"),
+  requestId: z.string().min(1),
+  instruction: z.string().min(1),
+  document: z.string().optional()
+});
+var executeRequestSchema = z.object({
+  type: z.literal("execute_request"),
+  requestId: z.string().min(1),
+  actions: z.array(browserToolActionSchema),
+  fields: z.array(snapshotFieldSchema)
+});
+var relayRequestSchema = z.discriminatedUnion("type", [
+  snapshotRequestSchema,
+  executeRequestSchema
+]);
+var snapshotResponseSchema = z.object({
+  type: z.literal("snapshot_response"),
+  requestId: z.string().min(1),
+  fields: z.array(snapshotFieldSchema)
+});
+var executeResponseSchema = z.object({
+  type: z.literal("execute_response"),
+  requestId: z.string().min(1),
+  report: executionReportSchema
+});
+var errorResponseSchema = z.object({
+  type: z.literal("error_response"),
+  requestId: z.string().min(1),
+  message: z.string().min(1)
+});
+var relayResponseSchema = z.discriminatedUnion("type", [
+  snapshotResponseSchema,
+  executeResponseSchema,
+  errorResponseSchema
+]);
+var dispatchSuccessSchema = z.object({
+  ok: z.literal(true),
+  response: relayResponseSchema
+});
+var dispatchErrorSchema = z.object({
+  ok: z.literal(false),
+  errorCode: z.union([
+    z.literal("UNAUTHORIZED"),
+    z.literal("NO_BROWSER"),
+    z.literal("TIMEOUT"),
+    z.literal("INVALID_RESPONSE"),
+    z.literal("NOT_FOUND"),
+    z.literal("INTERNAL")
+  ]),
+  message: z.string()
+});
+
+// src/relay/relay-store.ts
+import { randomUUID } from "crypto";
+import Redis from "ioredis";
+var DEFAULT_SESSION_TTL_MS = 10 * 60 * 1e3;
+var DEFAULT_REQUEST_TTL_SEC = 60;
+var DEFAULT_DISPATCH_TIMEOUT_MS = 20 * 1e3;
+var BROWSER_PRESENCE_TTL_SEC = 90;
+var RELAY_SSE_KEEPALIVE_INTERVAL_MS = 20 * 1e3;
+var REDIS_URL_ENV_CANDIDATES = [
+  "REDIS_URL",
+  "REDIS_TLS_URL",
+  "KV_URL",
+  "UPSTASH_REDIS_TLS_URL",
+  "UPSTASH_REDIS_URL"
+];
+var RELAY_SUBSCRIBER_REDIS_OPTIONS = {
+  enableReadyCheck: false,
+  autoResubscribe: false,
+  autoResendUnfulfilledCommands: false,
+  maxRetriesPerRequest: 2
+};
+var RelayStoreError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+};
+function createRelayError(code, message) {
+  switch (code) {
+    case "UNAUTHORIZED":
+      return new RelayStoreError(code, message, 401);
+    case "NO_BROWSER":
+      return new RelayStoreError(code, message, 409);
+    case "TIMEOUT":
+      return new RelayStoreError(code, message, 408);
+    case "INVALID_RESPONSE":
+      return new RelayStoreError(code, message, 422);
+    case "NOT_FOUND":
+      return new RelayStoreError(code, message, 404);
+    case "INTERNAL":
+      return new RelayStoreError(code, message, 500);
+    default:
+      return new RelayStoreError("INTERNAL", message, 500);
+  }
+}
+function resolveRedisUrl() {
+  for (const name of REDIS_URL_ENV_CANDIDATES) {
+    const value = process.env[name]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  throw createRelayError(
+    "INTERNAL",
+    `Missing Redis URL. Set one of: ${REDIS_URL_ENV_CANDIDATES.join(", ")}`
+  );
+}
+function getRedisClient() {
+  if (!globalThis.__browserToolRelayRedis) {
+    globalThis.__browserToolRelayRedis = new Redis(resolveRedisUrl(), {
+      maxRetriesPerRequest: 2
+    });
+  }
+  return globalThis.__browserToolRelayRedis;
+}
+function createRelaySubscriber() {
+  return getRedisClient().duplicate(RELAY_SUBSCRIBER_REDIS_OPTIONS);
+}
+function sessionKey(sessionId) {
+  return `relay:session:${sessionId}`;
+}
+function browserPresenceKey(sessionId) {
+  return `relay:browser:${sessionId}`;
+}
+function requestTypeKey(sessionId, requestId) {
+  return `relay:req:${sessionId}:${requestId}:type`;
+}
+function responseKey(sessionId, requestId) {
+  return `relay:resp:${sessionId}:${requestId}`;
+}
+function relayRequestChannel(sessionId) {
+  return `relay:${sessionId}:request`;
+}
+function relayResponseChannel(sessionId, requestId) {
+  return `relay:${sessionId}:response:${requestId}`;
+}
+function sessionExpiryTimestamp() {
+  return Date.now() + DEFAULT_SESSION_TTL_MS;
+}
+function parseSessionRecord(raw) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw createRelayError(
+      "INTERNAL",
+      "Relay session payload in Redis is malformed."
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || !("token" in parsed) || !("expiresAt" in parsed) || typeof parsed.token !== "string" || typeof parsed.expiresAt !== "number") {
+    throw createRelayError(
+      "INTERNAL",
+      "Relay session payload in Redis is invalid."
+    );
+  }
+  return {
+    token: parsed.token,
+    expiresAt: parsed.expiresAt
+  };
+}
+function toRequestType(value) {
+  if (value === "snapshot_request" || value === "execute_request") {
+    return value;
+  }
+  throw createRelayError(
+    "INTERNAL",
+    `Stored request type is invalid: ${value}`
+  );
+}
+function parseStoredRelayResponse(raw) {
+  let decoded = null;
+  try {
+    decoded = JSON.parse(raw);
+  } catch {
+    throw createRelayError(
+      "INVALID_RESPONSE",
+      "Relay response payload in Redis is malformed."
+    );
+  }
+  const parsed = relayResponseSchema.safeParse(decoded);
+  if (!parsed.success) {
+    throw createRelayError(
+      "INVALID_RESPONSE",
+      "Relay response payload in Redis is invalid."
+    );
+  }
+  return parsed.data;
+}
+async function touchSession(sessionId, token) {
+  const expiresAt = sessionExpiryTimestamp();
+  const redis = getRedisClient();
+  await redis.set(
+    sessionKey(sessionId),
+    JSON.stringify({ token, expiresAt }),
+    "EX",
+    Math.ceil(DEFAULT_SESSION_TTL_MS / 1e3)
+  );
+  return expiresAt;
+}
+async function getAuthorizedSession(sessionId, token) {
+  const redis = getRedisClient();
+  const raw = await redis.get(sessionKey(sessionId));
+  if (!raw) {
+    throw createRelayError(
+      "UNAUTHORIZED",
+      "Invalid relay session credentials."
+    );
+  }
+  const session = parseSessionRecord(raw);
+  if (session.token !== token) {
+    throw createRelayError(
+      "UNAUTHORIZED",
+      "Invalid relay session credentials."
+    );
+  }
+  const expiresAt = await touchSession(sessionId, token);
+  return {
+    token,
+    expiresAt
+  };
+}
+function validateResponseType(requestType, responseType) {
+  if (requestType === "snapshot_request" && responseType !== "snapshot_response") {
+    throw createRelayError(
+      "INVALID_RESPONSE",
+      `Expected snapshot_response, but received ${responseType}.`
+    );
+  }
+  if (requestType === "execute_request" && responseType !== "execute_response") {
+    throw createRelayError(
+      "INVALID_RESPONSE",
+      `Expected execute_response, but received ${responseType}.`
+    );
+  }
+}
+async function ensureBrowserConnected(sessionId) {
+  const redis = getRedisClient();
+  const isConnected = await redis.exists(browserPresenceKey(sessionId));
+  if (isConnected === 0) {
+    throw createRelayError(
+      "NO_BROWSER",
+      "No browser client is connected to this relay session."
+    );
+  }
+}
+async function waitForRelayResponseSignal(input) {
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const onMessage = (channel) => {
+      if (settled || channel !== input.channel) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    const onError = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      const message = error instanceof Error ? error.message : "Unknown Redis subscriber error.";
+      reject(
+        createRelayError(
+          "INTERNAL",
+          `Redis subscriber failed while waiting for response. ${message}`
+        )
+      );
+    };
+    const onTimeout = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(
+        createRelayError(
+          "TIMEOUT",
+          "Timed out waiting for browser relay response."
+        )
+      );
+    };
+    const timeoutId = setTimeout(onTimeout, input.timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      input.subscriber.off("message", onMessage);
+      input.subscriber.off("error", onError);
+    };
+    input.subscriber.on("message", onMessage);
+    input.subscriber.on("error", onError);
+    void input.trigger().catch((error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (error instanceof RelayStoreError) {
+        reject(error);
+        return;
+      }
+      const message = error instanceof Error ? error.message : "Unknown Redis publish error.";
+      reject(
+        createRelayError(
+          "INTERNAL",
+          `Failed to publish relay request. ${message}`
+        )
+      );
+    });
+  });
+}
+async function storeRelayResponse(input) {
+  const redis = getRedisClient();
+  await redis.multi().set(
+    responseKey(input.sessionId, input.requestId),
+    JSON.stringify(input.response),
+    "EX",
+    DEFAULT_REQUEST_TTL_SEC
+  ).del(requestTypeKey(input.sessionId, input.requestId)).publish(
+    relayResponseChannel(input.sessionId, input.requestId),
+    input.requestId
+  ).exec();
+}
+async function createRelaySession() {
+  const sessionId = randomUUID();
+  const token = `${randomUUID()}-${randomUUID()}`;
+  const expiresAt = sessionExpiryTimestamp();
+  const redis = getRedisClient();
+  await redis.set(
+    sessionKey(sessionId),
+    JSON.stringify({
+      token,
+      expiresAt
+    }),
+    "EX",
+    Math.ceil(DEFAULT_SESSION_TTL_MS / 1e3)
+  );
+  return {
+    sessionId,
+    token,
+    expiresAt
+  };
+}
+async function assertRelaySession(sessionId, token) {
+  await getAuthorizedSession(sessionId, token);
+}
+async function markBrowserConnected(sessionId, token) {
+  await getAuthorizedSession(sessionId, token);
+  const redis = getRedisClient();
+  await redis.set(
+    browserPresenceKey(sessionId),
+    "1",
+    "EX",
+    BROWSER_PRESENCE_TTL_SEC
+  );
+}
+async function touchBrowserConnected(sessionId) {
+  const redis = getRedisClient();
+  await redis.set(
+    browserPresenceKey(sessionId),
+    "1",
+    "EX",
+    BROWSER_PRESENCE_TTL_SEC
+  );
+}
+async function dispatchRelayRequest(input) {
+  await getAuthorizedSession(input.sessionId, input.token);
+  await ensureBrowserConnected(input.sessionId);
+  const redis = getRedisClient();
+  const timeoutMs = input.timeoutMs ?? DEFAULT_DISPATCH_TIMEOUT_MS;
+  const requestId = input.request.requestId;
+  const requestTypeStateKey = requestTypeKey(input.sessionId, requestId);
+  const storedResponseKey = responseKey(input.sessionId, requestId);
+  const responseEventChannel = relayResponseChannel(input.sessionId, requestId);
+  const subscriber = createRelaySubscriber();
+  const setPending = await redis.set(
+    requestTypeStateKey,
+    input.request.type,
+    "EX",
+    DEFAULT_REQUEST_TTL_SEC,
+    "NX"
+  );
+  if (setPending !== "OK") {
+    throw createRelayError(
+      "INVALID_RESPONSE",
+      `Request id is already pending: ${requestId}`
+    );
+  }
+  try {
+    await redis.del(storedResponseKey);
+    await subscriber.subscribe(responseEventChannel);
+    await waitForRelayResponseSignal({
+      subscriber,
+      channel: responseEventChannel,
+      timeoutMs,
+      trigger: async () => {
+        await redis.publish(
+          relayRequestChannel(input.sessionId),
+          JSON.stringify(input.request)
+        );
+      }
+    });
+    const storedResponse = await redis.get(storedResponseKey);
+    if (!storedResponse) {
+      throw createRelayError(
+        "TIMEOUT",
+        "Relay response notification was received without payload."
+      );
+    }
+    const parsedResponse = parseStoredRelayResponse(storedResponse);
+    if (parsedResponse.type === "error_response") {
+      throw createRelayError("INVALID_RESPONSE", parsedResponse.message);
+    }
+    validateResponseType(input.request.type, parsedResponse.type);
+    return parsedResponse;
+  } finally {
+    await Promise.allSettled([
+      redis.del(requestTypeStateKey),
+      redis.del(storedResponseKey)
+    ]);
+    await subscriber.unsubscribe(responseEventChannel).catch(() => void 0);
+    await subscriber.quit().catch(() => {
+      subscriber.disconnect();
+    });
+  }
+}
+async function resolveRelayResponse(input) {
+  await getAuthorizedSession(input.sessionId, input.token);
+  const redis = getRedisClient();
+  const requestId = input.response.requestId;
+  const requestTypeStateKey = requestTypeKey(input.sessionId, requestId);
+  const expectedRequestTypeRaw = await redis.get(requestTypeStateKey);
+  if (!expectedRequestTypeRaw) {
+    throw createRelayError(
+      "NOT_FOUND",
+      `Pending request was not found: ${requestId}`
+    );
+  }
+  const expectedRequestType = toRequestType(expectedRequestTypeRaw);
+  if (input.response.type === "error_response") {
+    await storeRelayResponse({
+      sessionId: input.sessionId,
+      requestId,
+      response: input.response
+    });
+    return;
+  }
+  try {
+    validateResponseType(expectedRequestType, input.response.type);
+  } catch (error) {
+    const relayError = error instanceof RelayStoreError ? error : createRelayError(
+      "INVALID_RESPONSE",
+      "Unexpected relay response type."
+    );
+    await storeRelayResponse({
+      sessionId: input.sessionId,
+      requestId,
+      response: {
+        type: "error_response",
+        requestId,
+        message: relayError.message
+      }
+    });
+    throw relayError;
+  }
+  await storeRelayResponse({
+    sessionId: input.sessionId,
+    requestId,
+    response: input.response
+  });
+}
+function toRelayError(error) {
+  if (error instanceof RelayStoreError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : "Unexpected relay failure.";
+  return createRelayError("INTERNAL", message);
+}
+
+// src/relay/relay-handler.ts
+var LOG_PREFIX = "[relay-handler]";
+var dispatchSchema = z2.object({
+  type: z2.literal("relay.dispatch"),
+  sessionId: z2.string().min(1),
+  token: z2.string().min(1),
+  request: relayRequestSchema,
+  timeoutMs: z2.number().int().positive().max(55e3).optional()
+});
+var respondSchema = z2.object({
+  type: z2.literal("relay.respond"),
+  sessionId: z2.string().min(1),
+  token: z2.string().min(1),
+  response: relayResponseSchema
+});
+var postBodySchema = z2.discriminatedUnion("type", [
+  dispatchSchema,
+  respondSchema
+]);
+function createSafeError(code, message, status) {
+  return Response.json({ ok: false, errorCode: code, message }, { status });
+}
+function createRelayEventsRoute(request) {
+  const url = new URL(request.url);
+  const sessionId = url.searchParams.get("sessionId") ?? "";
+  const token = url.searchParams.get("token") ?? "";
+  if (!sessionId || !token) {
+    return Promise.resolve(
+      Response.json(
+        {
+          errorCode: "UNAUTHORIZED",
+          message: "sessionId and token are required."
+        },
+        { status: 401 }
+      )
+    );
+  }
+  let cleanup = null;
+  const encoder = new TextEncoder();
+  return assertRelaySession(sessionId, token).then(() => {
+    console.info(`${LOG_PREFIX} sse.connect`, { sessionId });
+    const requestChannel = relayRequestChannel(sessionId);
+    const stream = new ReadableStream({
+      start(controller) {
+        const subscriber = createRelaySubscriber();
+        let keepaliveId = null;
+        let closed = false;
+        let nextEventId = 0;
+        const sendSseData = (payload) => {
+          nextEventId += 1;
+          controller.enqueue(
+            encoder.encode(
+              `id: ${nextEventId}
+data: ${JSON.stringify(payload)}
+
+`
+            )
+          );
+        };
+        const sendSseRawJson = (rawJson) => {
+          nextEventId += 1;
+          controller.enqueue(
+            encoder.encode(`id: ${nextEventId}
+data: ${rawJson}
+
+`)
+          );
+        };
+        const sendSseComment = (comment) => {
+          controller.enqueue(encoder.encode(`: ${comment}
+
+`));
+        };
+        const closeController = () => {
+          try {
+            controller.close();
+          } catch {
+          }
+        };
+        const onAbort = () => {
+          void cleanup?.();
+          closeController();
+        };
+        cleanup = async () => {
+          if (closed) {
+            return;
+          }
+          closed = true;
+          request.signal.removeEventListener("abort", onAbort);
+          if (keepaliveId) {
+            clearInterval(keepaliveId);
+          }
+          await subscriber.unsubscribe(requestChannel).catch(() => void 0);
+          await subscriber.quit().catch(() => {
+            subscriber.disconnect();
+          });
+        };
+        request.signal.addEventListener("abort", onAbort);
+        sendSseComment("connected");
+        subscriber.on("message", (channel, message) => {
+          if (closed || channel !== requestChannel) {
+            return;
+          }
+          try {
+            JSON.parse(message);
+          } catch {
+            return;
+          }
+          try {
+            console.info(`${LOG_PREFIX} sse.push`, { sessionId, message });
+            sendSseRawJson(message);
+          } catch {
+            void cleanup?.();
+            closeController();
+          }
+        });
+        subscriber.on("error", (error) => {
+          if (closed) {
+            return;
+          }
+          controller.error(error);
+          void cleanup?.();
+        });
+        void (async () => {
+          try {
+            await subscriber.subscribe(requestChannel);
+            await markBrowserConnected(sessionId, token);
+            console.info(`${LOG_PREFIX} sse.ready`, { sessionId });
+            sendSseData({ type: "ready", sessionId });
+            keepaliveId = setInterval(() => {
+              void touchBrowserConnected(sessionId).catch(() => void 0);
+              try {
+                sendSseComment("keepalive");
+              } catch {
+                void cleanup?.();
+                closeController();
+              }
+            }, RELAY_SSE_KEEPALIVE_INTERVAL_MS);
+          } catch (error) {
+            if (closed) {
+              return;
+            }
+            controller.error(error);
+            await cleanup?.();
+          }
+        })();
+      },
+      cancel() {
+        void cleanup?.();
+      }
+    });
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+        "Content-Encoding": "none"
+      }
+    });
+  }).catch((error) => {
+    console.error(`${LOG_PREFIX} sse.error`, {
+      sessionId,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    const relayError = toRelayError(error);
+    return Response.json(
+      {
+        errorCode: relayError.code,
+        message: relayError.message
+      },
+      { status: relayError.status }
+    );
+  });
+}
+async function createRelayPostRoute(request) {
+  const payload = await request.json().catch(() => null);
+  const parsed = postBodySchema.safeParse(payload);
+  if (!parsed.success) {
+    return createSafeError("INVALID_RESPONSE", "Invalid request payload.", 400);
+  }
+  if (parsed.data.type === "relay.dispatch") {
+    try {
+      const response = await dispatchRelayRequest({
+        sessionId: parsed.data.sessionId,
+        token: parsed.data.token,
+        request: parsed.data.request,
+        timeoutMs: parsed.data.timeoutMs
+      });
+      return Response.json({ ok: true, response });
+    } catch (error) {
+      const relayError = toRelayError(error);
+      return createSafeError(
+        relayError.code,
+        relayError.message,
+        relayError.status
+      );
+    }
+  }
+  try {
+    await resolveRelayResponse({
+      sessionId: parsed.data.sessionId,
+      token: parsed.data.token,
+      response: parsed.data.response
+    });
+    return Response.json({ ok: true });
+  } catch (error) {
+    const relayError = toRelayError(error);
+    return createSafeError(
+      relayError.code,
+      relayError.message,
+      relayError.status
+    );
+  }
+}
+function createRelayHandler() {
+  return {
+    GET: async (request) => createRelayEventsRoute(request),
+    POST: createRelayPostRoute
+  };
+}
+export {
+  createRelayHandler,
+  createRelaySession,
+  toRelayError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@giselles-ai/browser-tool",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"type": "module",
 	"sideEffects": false,
 	"license": "Apache-2.0",
@@ -27,6 +27,11 @@
 			"types": "./dist/mcp-server/index.d.ts",
 			"import": "./dist/mcp-server/index.js",
 			"default": "./dist/mcp-server/index.js"
+		},
+		"./relay": {
+			"types": "./dist/relay/index.d.ts",
+			"import": "./dist/relay/index.js",
+			"default": "./dist/relay/index.js"
 		}
 	},
 	"scripts": {
@@ -37,6 +42,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.0.0",
+		"ioredis": "^5.9.2",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {