@omercnet/paseo-shared-browser 0.3.1-next.72.1

package/server/mcp-entry.ts

@@ -0,0 +1,194 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import type { JsonValue } from "./runtime-protocol";
+import { AgentSupervisorClient } from "./supervisor-client";
+import { resolveSupervisorPaths } from "./supervisor";
+
+const TICKET_ENV = "PASEO_SHARED_BROWSER_TICKET";
+const MIN_VIEWPORT = { width: 320, height: 480 } as const;
+const MAX_VIEWPORT = { width: 1600, height: 1200 } as const;
+
+const pointSchema = z.object({
+  x: z.number().finite().nonnegative(),
+  y: z.number().finite().nonnegative(),
+  width: z.number().finite().positive().max(16_384),
+  height: z.number().finite().positive().max(16_384),
+});
+
+const inputEventSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("click"),
+    point: pointSchema,
+    button: z.enum(["left", "right", "middle"]).default("left"),
+    clickCount: z.union([z.literal(1), z.literal(2)]).default(1),
+  }),
+  z.object({ kind: z.literal("move"), point: pointSchema }),
+  z.object({
+    kind: z.literal("drag"),
+    start: pointSchema,
+    end: pointSchema,
+    button: z.enum(["left", "right", "middle"]).default("left"),
+  }),
+  z.object({
+    kind: z.literal("scroll"),
+    point: pointSchema,
+    deltaX: z.number().finite().min(-4_000).max(4_000),
+    deltaY: z.number().finite().min(-4_000).max(4_000),
+  }),
+  z.object({ kind: z.literal("type"), text: z.string().min(1).max(4_000) }),
+  z.object({
+    kind: z.literal("key"),
+    key: z.enum([
+      "Enter",
+      "Tab",
+      "Backspace",
+      "Delete",
+      "Escape",
+      "ArrowUp",
+      "ArrowDown",
+      "ArrowLeft",
+      "ArrowRight",
+      "Home",
+      "End",
+      "PageUp",
+      "PageDown",
+      "Space",
+    ]),
+  }),
+]);
+
+function paseoHome(): string {
+  return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+}
+
+function asObject(value: JsonValue): Record<string, JsonValue> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Shared Browser supervisor returned an invalid response");
+  return value;
+}
+
+function textResult(value: JsonValue) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+async function main(): Promise<void> {
+  const ticket = process.env[TICKET_ENV];
+  if (!ticket) throw new Error(`${TICKET_ENV} is required`);
+  const client = new AgentSupervisorClient({
+    ticket,
+    paths: resolveSupervisorPaths(paseoHome()),
+  });
+  await client.open();
+
+  const server = new McpServer({ name: "paseo-shared-browser", version: "0.2.2" });
+
+  server.registerTool(
+    "shared_browser_status",
+    {
+      description: "Read the current shared browser state for this agent's workspace.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true, idempotentHint: true },
+    },
+    async () => textResult(await client.request("status", {})),
+  );
+
+  server.registerTool(
+    "shared_browser_capture",
+    {
+      description:
+        "Capture the current shared browser frame and state. Capture before sending input.",
+      inputSchema: z.object({ quality: z.enum(["low", "medium", "high"]).default("medium") }),
+      annotations: { readOnlyHint: true, idempotentHint: true },
+    },
+    async ({ quality }) => {
+      const result = await client.request("capture", { quality });
+      const data = asObject(result);
+      const frame = data.frame;
+      const content: Array<
+        { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+      > = [{ type: "text", text: JSON.stringify(data.state, null, 2) }];
+      if (frame && typeof frame === "object" && !Array.isArray(frame)) {
+        const image = frame as Record<string, JsonValue>;
+        if (typeof image.dataBase64 === "string" && typeof image.mimeType === "string")
+          content.push({ type: "image", data: image.dataBase64, mimeType: image.mimeType });
+      }
+      return { content };
+    },
+  );
+
+  server.registerTool(
+    "shared_browser_acquire_control",
+    {
+      description:
+        "Acquire browser control if no human or other viewer currently holds it. Forced takeover is unavailable.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async () => textResult(await client.request("acquire-control", {})),
+  );
+
+  server.registerTool(
+    "shared_browser_release_control",
+    {
+      description: "Release this agent's browser control lease.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async () => textResult(await client.request("release-control", {})),
+  );
+  server.registerTool(
+    "shared_browser_navigate",
+    {
+      description: "Navigate the shared browser using the agent's current observed state.",
+      inputSchema: z.object({
+        action: z.discriminatedUnion("kind", [
+          z.object({ kind: z.literal("goto"), url: z.string().trim().min(1).max(8_192) }),
+          z.object({ kind: z.literal("back") }),
+          z.object({ kind: z.literal("forward") }),
+          z.object({ kind: z.literal("reload") }),
+        ]),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ action }) =>
+      textResult(await client.request("navigate", { action: action as unknown as JsonValue })),
+  );
+
+  server.registerTool(
+    "shared_browser_input",
+    {
+      description:
+        "Send one input event using the exact frame returned by the latest capture. Stale frames are rejected.",
+      inputSchema: z.object({ event: inputEventSchema }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async ({ event }) =>
+      textResult(await client.request("input", { event: event as unknown as JsonValue })),
+  );
+
+  server.registerTool(
+    "shared_browser_viewport",
+    {
+      description: "Resize the shared browser viewport using the agent's current observed state.",
+      inputSchema: z.object({
+        width: z.number().int().min(MIN_VIEWPORT.width).max(MAX_VIEWPORT.width),
+        height: z.number().int().min(MIN_VIEWPORT.height).max(MAX_VIEWPORT.height),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (viewport) =>
+      textResult(await client.request("viewport", { viewport: viewport as unknown as JsonValue })),
+  );
+
+  const transport = new StdioServerTransport();
+  process.once("exit", () => client.disconnect());
+  await server.connect(transport);
+}
+
+void main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/server/runtime-owner.ts

@@ -0,0 +1,122 @@
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AgentBrowserRuntime, type BrowserViewport } from "./agent-browser-runtime";
+import type { JsonValue } from "./runtime-protocol";
+import type { RuntimeOwner } from "./supervisor";
+
+const DEFAULT_BROWSER_URL = "https://example.com/";
+
+interface OwnedRuntime {
+  runtimeId: string;
+  runtime: AgentBrowserRuntime;
+}
+
+function paseoHome(): string {
+  return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+}
+
+export async function createRuntimeOwner(): Promise<RuntimeOwner<OwnedRuntime>> {
+  const root = join(paseoHome(), "plugin-data", "shared-browser");
+  const binaryPath =
+    process.env.PASEO_SHARED_BROWSER_AGENT_BROWSER_BINARY ??
+    join(root, "runtime", "node_modules", ".bin", "agent-browser");
+  const executablePath =
+    process.env.PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE ??
+    join(root, "runtime", "chromium", "chrome");
+  return {
+    async create(workspaceId) {
+      const hash = createHash("sha256").update(workspaceId).digest("hex");
+      const runtime = new AgentBrowserRuntime({
+        binaryPath,
+        executablePath,
+        profilePath: join(root, "profiles", hash),
+        ipcDirectory: join(root, "ipc"),
+        session: `ws-${hash.slice(0, 16)}`,
+        initialUrl: DEFAULT_BROWSER_URL,
+      });
+      await runtime.launch();
+      return { runtimeId: randomUUID(), runtime };
+    },
+    async request(owned, operation, input) {
+      const data =
+        input && typeof input === "object" && !Array.isArray(input)
+          ? (input as Record<string, JsonValue>)
+          : {};
+      switch (operation) {
+        case "identity":
+          return owned.runtime.identity() as unknown as JsonValue;
+        case "state":
+          return owned.runtime.state() as unknown as JsonValue;
+        case "navigate":
+          await owned.runtime.navigate(String(data.url));
+          return null;
+        case "back":
+          await owned.runtime.back();
+          return null;
+        case "forward":
+          await owned.runtime.forward();
+          return null;
+        case "reload":
+          await owned.runtime.reload();
+          return null;
+        case "emulate":
+          await owned.runtime.emulate(data as unknown as BrowserViewport);
+          return null;
+        case "screencast.start":
+          await owned.runtime.startScreencast(Number(data.quality));
+          return null;
+        case "screencast.stop":
+          await owned.runtime.stopScreencast();
+          return null;
+        case "frame":
+          return (await owned.runtime.frame(
+            Number(data.maxBytes),
+            Number(data.quality),
+            Number(data.waitMs),
+          )) as unknown as JsonValue;
+        case "mouse.move":
+          await owned.runtime.mouseMove(Number(data.x), Number(data.y));
+          return null;
+        case "mouse.down":
+          await owned.runtime.mouseDown(
+            Number(data.x),
+            Number(data.y),
+            String(data.button) as "left" | "middle" | "right",
+            Number(data.clickCount),
+          );
+          return null;
+        case "mouse.up":
+          await owned.runtime.mouseUp(
+            Number(data.x),
+            Number(data.y),
+            String(data.button) as "left" | "middle" | "right",
+            Number(data.clickCount),
+          );
+          return null;
+        case "mouse.wheel":
+          await owned.runtime.wheel(
+            Number(data.x),
+            Number(data.y),
+            Number(data.deltaX),
+            Number(data.deltaY),
+          );
+          return null;
+        case "text.insert":
+          await owned.runtime.insertText(String(data.text));
+          return null;
+        case "key.down":
+          await owned.runtime.keyDown(String(data.key));
+          return null;
+        case "key.up":
+          await owned.runtime.keyUp(String(data.key));
+          return null;
+        default:
+          throw new Error(`Unknown browser runtime operation: ${operation}`);
+      }
+    },
+    async stop(owned) {
+      await owned.runtime.shutdown();
+    },
+  };
+}

package/server/runtime-protocol.ts

@@ -0,0 +1,260 @@
+export const RUNTIME_PROTOCOL_VERSION = 2 as const;
+export const DEFAULT_ORPHAN_GRACE_MS = 120_000;
+export const DEFAULT_BRIDGE_HEARTBEAT_MS = 10_000;
+export const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export interface RuntimeDescriptor {
+  workspaceId: string;
+  runtimeId: string;
+  createdAt: number;
+}
+
+export interface BridgeLease {
+  bridgeId: string;
+  epoch: number;
+  heartbeatIntervalMs: number;
+  expiresAt: number;
+}
+
+interface RuntimeRequestBase {
+  id: string;
+  version: typeof RUNTIME_PROTOCOL_VERSION;
+}
+
+interface AdminRequestBase extends RuntimeRequestBase {
+  token: string;
+  bridgeId: string;
+}
+
+export type AgentBrowserOperation =
+  | "status"
+  | "capture"
+  | "acquire-control"
+  | "release-control"
+  | "navigate"
+  | "input"
+  | "viewport";
+
+export type RuntimeRequest =
+  | (AdminRequestBase & { method: "bridge.claim"; takeover?: boolean })
+  | (AdminRequestBase & { method: "bridge.heartbeat"; epoch: number })
+  | (AdminRequestBase & { method: "workspace.ensure"; epoch: number; workspaceId: string })
+  | (AdminRequestBase & {
+      method: "workspace.request";
+      epoch: number;
+      workspaceId: string;
+      operation: string;
+      input: JsonValue;
+    })
+  | (AdminRequestBase & { method: "workspace.archive"; epoch: number; workspaceId: string })
+  | (AdminRequestBase & {
+      method: "browser.request";
+      epoch: number;
+      operation: string;
+      input: JsonValue;
+    })
+  | (AdminRequestBase & { method: "ticket.issue"; epoch: number; ticket: string })
+  | (AdminRequestBase & {
+      method: "ticket.bind";
+      epoch: number;
+      ticket: string;
+      agentId: string;
+      workspaceId: string;
+    })
+  | (AdminRequestBase & { method: "agent.revoke"; epoch: number; agentId: string })
+  | (RuntimeRequestBase & {
+      method: "agent.request";
+      ticket: string;
+      operation: AgentBrowserOperation;
+      input: JsonValue;
+    });
+
+export type RuntimeResult = BridgeLease | RuntimeDescriptor | JsonValue | { archived: true };
+
+export type RuntimeResponse =
+  | { id: string; ok: true; result: RuntimeResult }
+  | { id: string; ok: false; error: { code: RuntimeErrorCode; message: string } };
+
+export type RuntimeErrorCode =
+  | "AUTHENTICATION_FAILED"
+  | "BRIDGE_FENCED"
+  | "INVALID_REQUEST"
+  | "PROTOCOL_MISMATCH"
+  | "WORKSPACE_ARCHIVED"
+  | "WORKSPACE_NOT_FOUND"
+  | "RUNTIME_BUSY"
+  | "UNKNOWN_OUTCOME"
+  | "RUNTIME_FAILURE";
+
+export class RuntimeProtocolError extends Error {
+  readonly code: RuntimeErrorCode;
+
+  constructor(code: RuntimeErrorCode, message: string) {
+    super(message);
+    this.name = "RuntimeProtocolError";
+    this.code = code;
+  }
+}
+
+export function isRuntimeResponse(value: unknown): value is RuntimeResponse {
+  if (!isRecord(value) || typeof value.id !== "string" || typeof value.ok !== "boolean")
+    return false;
+  if (value.ok) return "result" in value;
+  return (
+    isRecord(value.error) &&
+    typeof value.error.code === "string" &&
+    typeof value.error.message === "string"
+  );
+}
+
+export function parseRuntimeRequest(value: unknown): RuntimeRequest {
+  if (!isRecord(value))
+    throw new RuntimeProtocolError("INVALID_REQUEST", "Request must be an object");
+  const id = requireString(value, "id");
+  const method = requireString(value, "method");
+  if (value.version !== RUNTIME_PROTOCOL_VERSION) {
+    throw new RuntimeProtocolError(
+      "PROTOCOL_MISMATCH",
+      `Expected protocol version ${RUNTIME_PROTOCOL_VERSION}`,
+    );
+  }
+  if (method === "agent.request") {
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      ticket: requireString(value, "ticket"),
+      operation: requireAgentOperation(value.operation),
+      input: requireJsonValue(value, "input"),
+    };
+  }
+
+  const token = requireString(value, "token");
+  const bridgeId = requireString(value, "bridgeId");
+  if (method === "bridge.claim")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      takeover: value.takeover === true,
+    };
+  const epoch = requireInteger(value, "epoch");
+  if (method === "bridge.heartbeat")
+    return { id, version: RUNTIME_PROTOCOL_VERSION, method, token, bridgeId, epoch };
+  if (method === "workspace.ensure" || method === "workspace.archive")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      workspaceId: requireString(value, "workspaceId"),
+    };
+  if (method === "workspace.request")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      workspaceId: requireString(value, "workspaceId"),
+      operation: requireString(value, "operation"),
+      input: requireJsonValue(value, "input"),
+    };
+  if (method === "browser.request")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      operation: requireString(value, "operation"),
+      input: requireJsonValue(value, "input"),
+    };
+  if (method === "ticket.issue")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      ticket: requireString(value, "ticket"),
+    };
+  if (method === "ticket.bind")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      ticket: requireString(value, "ticket"),
+      agentId: requireString(value, "agentId"),
+      workspaceId: requireString(value, "workspaceId"),
+    };
+  if (method === "agent.revoke")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      agentId: requireString(value, "agentId"),
+    };
+  throw new RuntimeProtocolError("INVALID_REQUEST", `Unknown method: ${method}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireString(value: Record<string, unknown>, key: string): string {
+  const result = value[key];
+  if (typeof result !== "string" || result.length === 0)
+    throw new RuntimeProtocolError("INVALID_REQUEST", `${key} must be a non-empty string`);
+  return result;
+}
+
+function requireInteger(value: Record<string, unknown>, key: string): number {
+  const result = value[key];
+  if (typeof result !== "number" || !Number.isSafeInteger(result))
+    throw new RuntimeProtocolError("INVALID_REQUEST", `${key} must be a safe integer`);
+  return result;
+}
+
+function requireAgentOperation(value: unknown): AgentBrowserOperation {
+  if (
+    value === "status" ||
+    value === "capture" ||
+    value === "acquire-control" ||
+    value === "release-control" ||
+    value === "navigate" ||
+    value === "input" ||
+    value === "viewport"
+  )
+    return value;
+  throw new RuntimeProtocolError("INVALID_REQUEST", "Unknown agent browser operation");
+}
+
+function requireJsonValue(value: Record<string, unknown>, key: string): JsonValue {
+  if (!(key in value) || !isJsonValue(value[key]))
+    throw new RuntimeProtocolError("INVALID_REQUEST", `${key} must be valid JSON`);
+  return value[key];
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  return isRecord(value) && Object.values(value).every(isJsonValue);
+}