pi-webmcp 0.1.0

package/src/services/PiWebMcpCommandService.ts

@@ -0,0 +1,184 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer } from "@earendil-works/pi-tui";
+import { Context, Effect, Layer, Option, Ref, Result, Schema, SchemaTransformation, Stream, SubscriptionRef } from "effect";
+import { BrowserClient } from "./BrowserClient";
+import { PiContext } from "./PiApi";
+import { PiTurnRefService } from "./PiTurnRefService";
+import { PiWebMcpAllowedOriginService } from "./PiWebMcpAllowedOriginService";
+import { PiWebMcpListService } from "./PiWebMcpListService";
+import { PiWebMcpToolStateService } from "./PiWebMcpToolStateService";
+import { WebMcpToolDiff, WebMcpToolDiffService } from "./WebMcpToolDiffService";
+import { WebMcpToolsService } from "./WebMcpToolsService";
+
+const Subcommand = Schema.Literals([
+  "connect",
+  "disconnect",
+  "list",
+]);
+
+const CommandArgs = Schema.String.pipe(
+  Schema.decode(SchemaTransformation.trim().compose(SchemaTransformation.toLowerCase())),
+  Schema.decodeTo(Schema.Literals(["", ...Subcommand.literals])),
+);
+
+function formatAddedOrigins(diff: WebMcpToolDiff) {
+  const counts = new Map<string, number>();
+
+  for (const tool of diff.added) {
+    counts.set(tool.origin, (counts.get(tool.origin) ?? 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([origin, count]) => `${origin} [${count}]`)
+    .join(", ");
+}
+
+export class PiWebMcpCommandService extends Context.Service<PiWebMcpCommandService, {
+  readonly handle: (args: string) => Effect.Effect<void, never, PiContext>;
+  readonly nudge: () => Effect.Effect<void>;
+}>()("pi-webmcp/PiWebMcpCommandService") {
+  static readonly liveWithoutDependencies = Layer.effect(
+    PiWebMcpCommandService,
+    Effect.gen(function*() {
+      const browser = yield* BrowserClient;
+      const toolState = yield* PiWebMcpToolStateService;
+      const listService = yield* PiWebMcpListService;
+      const tools = yield* WebMcpToolsService;
+      const allowedOrigin = yield* PiWebMcpAllowedOriginService;
+      const toolDiff = yield* WebMcpToolDiffService;
+      const turnRefService = yield* PiTurnRefService;
+      const notificationShownRef = yield* turnRefService.make(Option.some(true));
+      const nudges = yield* SubscriptionRef.make<unknown>(null);
+
+      const disconnect = Effect.fn("PiWebMcpCommandService.disconnect")(function*() {
+        const ctx = yield* PiContext;
+
+        ctx.ui.setWidget("webmcp-list", undefined);
+        // TODO: detach active CDP target sessions before disconnecting.
+        yield* browser.disconnect().pipe(Effect.ignore);
+        yield* toolState.stage([]);
+      });
+
+      const list = Effect.fn("PiWebMcpCommandService.list")(function*() {
+        const ctx = yield* PiContext;
+        const cdp = yield* browser.get;
+
+        if (Option.isNone(cdp)) {
+          ctx.ui.notify("WebMCP: Not connected. Run `/webmcp` first.", "error");
+          return;
+        }
+
+        const text = yield* listService.markdown({});
+
+        if (Option.isNone(text)) {
+          ctx.ui.notify("WebMCP: No tools discovered.", "info");
+          return;
+        }
+
+        const markdownTheme = getMarkdownTheme();
+
+        ctx.ui.setWidget("webmcp-list", () => {
+          const widget = new Container();
+          widget.addChild(new Markdown(text.value, 0, 0, markdownTheme));
+          widget.addChild(new Spacer(1));
+          return widget;
+        });
+      });
+
+      const connect = Effect.fn("PiWebMcpCommandService.connect")(function*() {
+        const ctx = yield* PiContext;
+
+        ctx.ui.setWidget("webmcp-list", undefined);
+
+        const connected = yield* browser.connect({ force: true }).pipe(
+          Effect.as(true),
+          Effect.catchTag(
+            "BrowserClientError",
+            Effect.fn("PiWebMcpCommandService.connect.handleBrowserClientError")(function*() {
+              ctx.ui.notify("WebMCP: Failed to connect to Chrome. Make sure Chrome is open with remote debugging enabled.", "error");
+              return false;
+            }),
+          ),
+        );
+
+        if (!connected) return;
+
+        yield* tools.changes.pipe(
+          Stream.map((tools) => tools.filter((tool) => allowedOrigin.isAllowed(tool.origin))),
+          Stream.zipLatestWith(SubscriptionRef.changes(nudges), (tools) => tools),
+          // Stage every change immediately so the registry stays current.
+          Stream.tap((active) => toolState.stage(active)),
+          // Only notify for the latest change once the agent is idle. If a
+          // newer change arrives while we're waiting, `switchMap` interrupts
+          // the pending notification and restarts with the latest state,
+          // preventing a backlog of queued notifications.
+          Stream.switchMap((active) =>
+            Stream.fromEffectDrain(Effect.gen(function*() {
+              yield* Effect.promise(() => ctx.waitForIdle());
+
+              const committed = yield* toolState.committed;
+              const diff = toolDiff.diff(committed, active);
+
+              const notificationShown = yield* Ref.get(notificationShownRef).pipe(
+                Effect.map(Option.getOrElse(() => false)),
+              );
+
+              if (!toolDiff.hasDiff(diff) && notificationShown) {
+                ctx.ui.notify("");
+                return;
+              }
+
+              if (diff.added.length === 0) {
+                return;
+              }
+
+              yield* Ref.set(notificationShownRef, Option.some(true));
+
+              ctx.ui.notify(`WebMCP: New tool(s) discovered for ${formatAddedOrigins(diff)}.`, "info");
+            }))
+          ),
+          Stream.runDrain,
+          Effect.forkDetach,
+        );
+      });
+
+      return PiWebMcpCommandService.of({
+        handle: Effect.fn("PiWebMcpCommandService.handle")(function*(args: string) {
+          const ctx = yield* PiContext;
+
+          const result = Schema.decodeUnknownResult(CommandArgs)(args);
+
+          if (Result.isFailure(result)) {
+            ctx.ui.notify(`Usage: /webmcp [${Subcommand.literals.join("|")}]`, "error");
+            return;
+          }
+
+          const command = result.success;
+
+          if (command === "disconnect") {
+            return yield* disconnect();
+          }
+
+          if (command === "list") {
+            return yield* list();
+          }
+
+          yield* connect();
+        }),
+        nudge: Effect.fn("PiWebMcpCommandService.nudge")(function*() {
+          yield* SubscriptionRef.set(nudges, Symbol());
+        }),
+      });
+    }),
+  );
+
+  static readonly live = PiWebMcpCommandService.liveWithoutDependencies.pipe(
+    Layer.provide(PiWebMcpListService.live),
+    Layer.provide(PiWebMcpToolStateService.live),
+    Layer.provide(WebMcpToolsService.live),
+    Layer.provide(PiTurnRefService.live),
+    Layer.provide(PiWebMcpAllowedOriginService.live),
+    Layer.provide(WebMcpToolDiffService.live),
+  );
+}

package/src/services/PiWebMcpDescribeService.ts

@@ -0,0 +1,93 @@
+import { type AgentToolResult, highlightCode } from "@earendil-works/pi-coding-agent";
+import { Context, Effect, Formatter, Layer, Option, Schema } from "effect";
+import { Origin, ToolId, WebMcpTool } from "../schemas/WebMcpTool";
+import { agentConnectInstruction } from "../utils/copy";
+import { BrowserClient } from "./BrowserClient";
+import { PiContext } from "./PiApi";
+import { PiWebMcpToolStateService } from "./PiWebMcpToolStateService";
+
+export type PiWebMcpDescribeParams = {
+  readonly tool: string;
+  readonly origin: string;
+};
+
+export type PiWebMcpDescribeDetails = {
+  readonly connected?: boolean;
+  readonly id?: ToolId;
+  readonly error?: string;
+};
+
+export class PiWebMcpDescribeService extends Context.Service<PiWebMcpDescribeService, {
+  readonly execute: (params: PiWebMcpDescribeParams) => Effect.Effect<AgentToolResult<PiWebMcpDescribeDetails>, never, PiContext>;
+}>()("pi-webmcp/PiWebMcpDescribeService") {
+  static readonly live = Layer.effect(
+    PiWebMcpDescribeService,
+    Effect.gen(function*() {
+      const browser = yield* BrowserClient;
+      const toolState = yield* PiWebMcpToolStateService;
+
+      // TODO: refactor `listToolsText` into an Effect-native formatter (e.g. a
+      // `Schema` representation / `Formatter`-based renderer) instead of a
+      // plain string builder. Needs investigation into SchemaRepresentation
+      // / Formatter.formatJson usage and whether grouping by origin belongs
+      // in a dedicated service.
+      const listToolsText = (tools: WebMcpTool[]) => {
+        if (tools.length === 0) return "No WebMCP tools found. Ask the user to run `/webmcp` first.";
+
+        return tools
+          .sort((a, b) => a.name.localeCompare(b.name))
+          .map((tool) => {
+            const id = tool.id;
+            const name = id === tool.name ? id : `${id} (${tool.name})`;
+            const description = tool.description ? `\n    ${tool.description}` : "";
+            return `  - ${name} @ ${tool.origin}${description}`;
+          })
+          .join("\n");
+      };
+
+      // TODO: refactor `resolveTool` into an Effect-native lookup, e.g.
+      // Schema-validated selection / `Effect.gen` returning a typed
+      // `Result`/`Option` instead of a `{ candidates }` discriminated object.
+      // Needs investigation into whether this and PiWebMcpExecuteService's
+      // resolveTool should share one service.
+      const resolveTool = (tools: WebMcpTool[], id: ToolId, origin: Origin) => {
+        const candidates = tools.filter((tool) => (tool.id === id || tool.name === id) && tool.origin === origin);
+
+        return candidates.length === 1 ? candidates[0] : { candidates };
+      };
+
+      return PiWebMcpDescribeService.of({
+        execute: Effect.fn("PiWebMcpDescribeService.execute")(function*(params: PiWebMcpDescribeParams) {
+          const cdpOption = yield* browser.get;
+          if (Option.isNone(cdpOption)) {
+            return {
+              content: [{ type: "text", text: agentConnectInstruction }],
+              details: {},
+            };
+          }
+
+          const activeTools = [...yield* toolState.committed, ...yield* toolState.staged];
+          const origin = Schema.decodeUnknownSync(Origin)(params.origin);
+          const toolId = Schema.decodeUnknownSync(ToolId)(params.tool);
+          const resolved = resolveTool(activeTools, toolId, origin);
+          if ("candidates" in resolved) {
+            return {
+              content: [{
+                type: "text",
+                text: resolved.candidates.length > 0
+                  ? `Ambiguous tool. Provide origin.\n\n${listToolsText(resolved.candidates)}`
+                  : `Tool not found: ${params.tool}. Try webmcp_list first.`,
+              }],
+              details: {},
+            };
+          }
+
+          const inputSchema = Formatter.formatJson(Schema.encodeSync(Schema.Json)(resolved.inputSchema ?? {}), { space: 2 });
+          const highlightedInputSchema = highlightCode(inputSchema, "json").join("\n");
+          const text = `\n${resolved.description ?? "(no description)"}\n\n${highlightedInputSchema}`;
+          return { content: [{ type: "text", text }], details: {} };
+        }),
+      });
+    }),
+  );
+}

package/src/services/PiWebMcpExecuteService.ts

@@ -0,0 +1,153 @@
+import { type AgentToolResult, highlightCode } from "@earendil-works/pi-coding-agent";
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { Origin, ToolId, WebMcpTool } from "../schemas/WebMcpTool";
+import { agentConnectInstruction } from "../utils/copy";
+import { BrowserClient, type CdpClient } from "./BrowserClient";
+import { PiContext } from "./PiApi";
+import { PiWebMcpToolStateService } from "./PiWebMcpToolStateService";
+
+export type PiWebMcpExecuteParams = {
+  readonly tool: string;
+  readonly origin: string;
+  readonly args?: string;
+};
+
+export type PiWebMcpExecuteDetails = {
+  readonly connected?: boolean;
+  readonly id?: ToolId;
+  readonly origin?: Origin;
+  readonly input?: Record<string, unknown>;
+  readonly result?: unknown;
+  readonly error?: string;
+};
+
+export class PiWebMcpExecuteError extends Schema.TaggedErrorClass<PiWebMcpExecuteError>()("PiWebMcpExecuteError", {
+  operation: Schema.Union([Schema.Literal("parseInput"), Schema.Literal("invokeTool")]),
+  cause: Schema.Unknown,
+}) {}
+
+function listToolsText(tools: WebMcpTool[]) {
+  if (tools.length === 0) return "No WebMCP tools found. Ask the user to run `/webmcp` first.";
+
+  return tools
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((tool) => {
+      const id = tool.id;
+      const name = id === tool.name ? id : `${id} (${tool.name})`;
+      const description = tool.description ? `\n    ${tool.description}` : "";
+      return `  - ${name} @ ${tool.origin}${description}`;
+    })
+    .join("\n");
+}
+
+function resolveTool(tools: WebMcpTool[], id: ToolId, origin?: Origin) {
+  const candidates = tools.filter((tool) => (tool.id === id || tool.name === id) && (!origin || tool.origin === origin));
+
+  return candidates.length === 1 ? candidates[0] : { candidates };
+}
+
+function parseInput(args: string | undefined) {
+  return Effect.try({
+    try: () => {
+      if (!args) return {};
+      const input = JSON.parse(args) as unknown;
+      if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new Error("args must be a JSON object string");
+      }
+      return input as Record<string, unknown>;
+    },
+    catch: (cause) => new PiWebMcpExecuteError({ operation: "parseInput", cause }),
+  });
+}
+
+function invokeWebMcpTool(cdp: CdpClient, tool: WebMcpTool, input: Record<string, unknown>) {
+  return Effect.tryPromise({
+    try: async () => {
+      if (!tool.sessionId) throw new Error("WebMCP tool is missing its CDP session id. Re-run `/webmcp` and try again.");
+
+      let invocationId: string | undefined;
+      const responsePromise = new Promise<unknown>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          reject(
+            new Error(
+              "Timed out waiting for WebMCP.toolResponded. The page accepted the invocation but did not respond; declarative form tools may require the page/form to opt into toolautosubmit or otherwise call event.respondWith(...).",
+            ),
+          );
+        }, 60_000);
+
+        cdp.on("WebMCP.toolResponded", (ev: any, evSessionId?: string) => {
+          if (evSessionId !== tool.sessionId) return;
+          if (!invocationId || ev.invocationId === invocationId) {
+            clearTimeout(timer);
+            resolve(ev);
+          }
+        });
+      });
+
+      const invokeResult = await cdp.send("WebMCP.invokeTool", {
+        frameId: tool.frameId,
+        toolName: tool.name,
+        input,
+      }, tool.sessionId);
+      invocationId = invokeResult.invocationId;
+
+      const response = await responsePromise;
+      return { invokeResult, response };
+    },
+    catch: (cause) => new PiWebMcpExecuteError({ operation: "invokeTool", cause }),
+  });
+}
+
+function textResult(text: string, details: PiWebMcpExecuteDetails): AgentToolResult<PiWebMcpExecuteDetails> {
+  return { content: [{ type: "text", text }], details };
+}
+
+export class PiWebMcpExecuteService extends Context.Service<PiWebMcpExecuteService, {
+  readonly execute: (params: PiWebMcpExecuteParams) => Effect.Effect<AgentToolResult<PiWebMcpExecuteDetails>, never, PiContext>;
+}>()("pi-webmcp/PiWebMcpExecuteService") {
+  static readonly live = Layer.effect(
+    PiWebMcpExecuteService,
+    Effect.gen(function*() {
+      const browser = yield* BrowserClient;
+      const toolState = yield* PiWebMcpToolStateService;
+
+      return PiWebMcpExecuteService.of({
+        execute: Effect.fn("PiWebMcpExecuteService.execute")(
+          function*(params: PiWebMcpExecuteParams) {
+            const cdpOption = yield* browser.get;
+            if (Option.isNone(cdpOption)) {
+              return textResult(agentConnectInstruction, { connected: false });
+            }
+
+            const activeTools = [...yield* toolState.committed, ...yield* toolState.staged];
+            const origin = Schema.decodeUnknownSync(Origin)(params.origin);
+            const toolId = Schema.decodeUnknownSync(ToolId)(params.tool);
+            const resolved = resolveTool(activeTools, toolId, origin);
+            if ("candidates" in resolved) {
+              return textResult(
+                resolved.candidates.length > 0
+                  ? `Ambiguous tool. Retry with origin.\n\n${listToolsText(resolved.candidates)}`
+                  : `Tool not found: ${params.tool}. Try /webmcp first.`,
+                { error: "tool_not_found_or_ambiguous" },
+              );
+            }
+
+            const input = yield* parseInput(params.args);
+            const result = yield* invokeWebMcpTool(cdpOption.value, resolved, input);
+            const inputJson = highlightCode(JSON.stringify(input, null, 2), "json").join("\n");
+            const responseJson = highlightCode(JSON.stringify((result as any).response, null, 2), "json").join("\n");
+            const text = `\n→\n\n${inputJson}\n\n←\n\n${responseJson}`;
+
+            return textResult(text, {
+              id: resolved.id,
+              origin: resolved.origin,
+              input,
+              result,
+            });
+          },
+          (effect) => effect.pipe(Effect.catch((cause: unknown) => Effect.succeed(textResult(String(cause instanceof Error ? cause.message : cause), { error: "execute_failed" })))),
+        ),
+      });
+    }),
+  );
+}

package/src/services/PiWebMcpListService.ts

@@ -0,0 +1,107 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { Context, Effect, Layer, Option, Schema } from "effect";
+import { Origin, WebMcpTool } from "../schemas/WebMcpTool";
+import { agentConnectInstruction } from "../utils/copy";
+import { BrowserClient } from "./BrowserClient";
+import { PiContext } from "./PiApi";
+import { PiWebMcpToolStateService } from "./PiWebMcpToolStateService";
+
+export type PiWebMcpListParams = {
+  readonly filter?: string;
+  readonly refresh?: boolean;
+  readonly origin?: string;
+};
+
+export class PiWebMcpListService extends Context.Service<PiWebMcpListService, {
+  readonly markdown: (params: PiWebMcpListParams) => Effect.Effect<Option.Option<string>, never, PiContext>;
+  readonly execute: (params: PiWebMcpListParams) => Effect.Effect<AgentToolResult<unknown>, never, PiContext>;
+}>()("pi-webmcp/PiWebMcpListService") {
+  static readonly live = Layer.effect(
+    PiWebMcpListService,
+    Effect.gen(function*() {
+      const browser = yield* BrowserClient;
+      const toolState = yield* PiWebMcpToolStateService;
+
+      const uniqueTools = (tools: WebMcpTool[]): WebMcpTool[] => {
+        return [...new Map(tools.map((tool) => [`${tool.origin}:${tool.name}:${tool.frameId}`, tool])).values()];
+      };
+
+      const groupToolsByOrigin = (tools: WebMcpTool[]): WebMcpTool[][] => {
+        const groups: WebMcpTool[][] = [];
+        for (const tool of uniqueTools(tools)) {
+          const group = groups.find((group) => group[0]?.origin === tool.origin);
+          if (group) {
+            group.push(tool);
+          } else {
+            groups.push([tool]);
+          }
+        }
+
+        return groups.sort((a, b) => a[0]!.origin.localeCompare(b[0]!.origin));
+      };
+
+      const formatToolList = (tools: WebMcpTool[]): Option.Option<string> => {
+        if (tools.length === 0) {
+          return Option.none();
+        }
+
+        const sections = groupToolsByOrigin(tools).map((list) => {
+          const origin = list[0]!.origin;
+          const body = list
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((tool) => {
+              const description = tool.description ? ` ${tool.description}` : "";
+              return `- **${tool.name}**${description}`;
+            })
+            .join("\n\n");
+          return `${origin}\n\n${body}`;
+        });
+
+        return Option.some(`\n${sections.join("\n\n")}`);
+      };
+
+      const markdown = Effect.fn("PiWebMcpListService.markdown")(function*(params: PiWebMcpListParams) {
+        const cdp = yield* browser.get;
+
+        if (Option.isNone(cdp)) {
+          return Option.none<string>();
+        }
+
+        const staged = yield* toolState.staged;
+        const committed = yield* toolState.committed;
+
+        let tools = [...staged, ...committed];
+
+        if (params.origin) {
+          const targetOrigin = Schema.decodeUnknownSync(Origin)(params.origin);
+          tools = tools.filter((tool) => tool.origin === targetOrigin);
+        }
+
+        return formatToolList(tools);
+      });
+
+      const fallbackMessage = Effect.fn("PiWebMcpListService.fallbackMessage")(function*() {
+        const cdp = yield* browser.get;
+
+        if (Option.isNone(cdp)) {
+          return agentConnectInstruction;
+        }
+
+        return "No WebMCP tools found.";
+      });
+
+      return PiWebMcpListService.of({
+        markdown,
+        execute: Effect.fn("PiWebMcpListService.execute")(function*(params: PiWebMcpListParams) {
+          const maybeMarkdown = yield* markdown(params);
+          const text = Option.isSome(maybeMarkdown) ? maybeMarkdown.value : yield* fallbackMessage();
+
+          return {
+            content: [{ type: "text", text }],
+            details: {},
+          };
+        }),
+      });
+    }),
+  );
+}