@frockbot/plugin-mcp 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-mcp",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,13 +25,13 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/configuration-core": "0.1.4",
-    "@frockbot/connection-core": "0.1.4",
-    "@frockbot/kernel-contracts": "0.1.4",
-    "@frockbot/plugin-credentials": "0.1.4",
-    "@frockbot/plugin-settings": "0.1.4",
-    "@frockbot/plugin-tools": "0.1.4",
-    "@frockbot/plugin-web": "0.1.4",
+    "@frockbot/configuration-core": "0.2.1",
+    "@frockbot/connection-core": "0.2.1",
+    "@frockbot/kernel-contracts": "0.2.1",
+    "@frockbot/plugin-credentials": "0.2.1",
+    "@frockbot/plugin-settings": "0.2.1",
+    "@frockbot/plugin-tools": "0.2.1",
+    "@frockbot/plugin-web": "0.2.1",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/lifecycle-tools.ts

@@ -14,12 +14,7 @@
  * records through the host the Bot's Durable Object supplies, which is why
  * this Contribution mounts for a Turn rather than for one Capability.
  */
-import type {
-  Session,
-  ToolDefinition,
-  ToolExecutionContext,
-  TurnTypeV1,
-} from "@frockbot/kernel-contracts";
+import type { ToolDefinition, TurnTypeV1 } from "@frockbot/kernel-contracts";
 import type { Context, Plugin } from "cordis";
 import type {
   McpLifecycleReceiptV1,
@@ -35,39 +30,12 @@ export const MCP_LIFECYCLE_TURN_TYPES: readonly TurnTypeV1[] = [
 ];
 
 /**
- * Adding a server, and asking the User to authorize one, are chat-only; every
- * other lifecycle verb is not. Both are User-shaped decisions, and an
- * automation or subagent Turn has no User in front of it to make one.
+ * Adding a server is chat-only; every other lifecycle verb is not. It is a
+ * User-shaped decision, and an automation or subagent Turn has no User in
+ * front of it to make one.
  */
 export const MCP_ADMISSION_TURN_TYPES: readonly TurnTypeV1[] = ["chat"];
 
-/**
- * The open step a send belongs to. The session log is the reconstruction
- * surface, so a card recorded without its turn and step would not replay in
- * place. The same rule `plugin-shell` applies to `send_to_user`, restated here
- * because this Package records its own send rather than reaching into that one.
- */
-function openStepPositionV1(
-  session: Session,
-  tool: string,
-): { turn: number; step: number } {
-  const started = session.events.findLast(
-    (event) => event.type === "step/start",
-  );
-  const ended = session.events.findLast((event) => event.type === "step/end");
-  if (started?.type !== "step/start") {
-    throw new Error(`${tool} has no open step to record against`);
-  }
-  if (
-    ended?.type === "step/end" &&
-    ended.turn === started.turn &&
-    ended.step === started.step
-  ) {
-    throw new Error(`${tool} has no open step to record against`);
-  }
-  return { turn: started.turn, step: started.step };
-}
-
 /**
  * The User authority these tools run with. The Bot never reaches the records
  * itself: its Durable Object carries each call to the User Durable Object
@@ -273,119 +241,7 @@ export function createMcpLifecycleRuntimePlugin(
       },
     },
   ];
-  definitions.push({
-    name: "mcp_authenticate_server",
-    description: [
-      "Ask the User to authorize one OAuth MCP server that is not connected.",
-      "This records a durable pending decision and shows the User a connect card.",
-      "It returns no link and no token, and it grants nothing: only the User,",
-      "pressing that card, can complete an authorization. Never write an",
-      "authorization URL yourself — you cannot have one, and one you composed",
-      "would not work. Chat turns only.",
-    ].join(" "),
-    inputSchema: {
-      type: "object",
-      properties: {
-        server_id: { type: "string" },
-        reason: { type: "string", maxLength: 2_000 },
-      },
-      required: ["server_id"],
-      additionalProperties: false,
-    },
-    admission: { turnTypes: [...MCP_ADMISSION_TURN_TYPES] },
-    validate: (input) => isObject(input),
-    execute: async (input: unknown, context: ToolExecutionContext) => {
-      try {
-        const value = isObject(input) ? input : {};
-        const serverId = text(value, "server_id");
-        const status = await host.readStatus();
-        const server = status.servers.find(
-          (candidate) => candidate.serverId === serverId,
-        );
-        if (!server) {
-          return {
-            content: `No MCP server "${serverId}" is available.`,
-            isError: true,
-          };
-        }
-        const applied = await host.execute({
-          schemaVersion: 1,
-          type: "mcp/request-authorization",
-          commandId: nextId(),
-          serverId,
-        });
-        if (applied.status !== "applied") return receipt(applied);
-        // The card is the User's, drawn by the host from the durable
-        // projection. What the Bot supplies is a reason, never a link.
-        const emitted = await emitConnectCard(context, {
-          connectionId: serverId,
-          title: `Connect ${server.label}`,
-          ...(typeof value.reason === "string" && value.reason.length > 0
-            ? { body: value.reason.slice(0, 2_000) }
-            : {}),
-        });
-        return {
-          content: JSON.stringify({
-            ...applied,
-            pendingAuthorization: true,
-            cardShown: emitted,
-          }),
-          isError: false,
-        };
-      } catch (error) {
-        return failed(error);
-      }
-    },
-  });
-
-  /**
-   * Record the connect card on the durable session log, as a `send/to-user`
-   * exactly like `send_to_user` produces — so the thread draws it, the
-   * transcript replays it, and no second delivery path exists.
-   */
-  async function emitConnectCard(
-    context: ToolExecutionContext,
-    card: { connectionId: string; title: string; body?: string },
-  ): Promise<boolean> {
-    const session = sessionStore()?.get(context.sessionId);
-    if (!session) return false;
-    let position: { turn: number; step: number };
-    try {
-      position = openStepPositionV1(session, "mcp_authenticate_server");
-    } catch {
-      return false;
-    }
-    session.append({
-      type: "send/to-user",
-      ...position,
-      occurrenceId: context.effectId,
-      payload: { type: "connect-card", ...card },
-    });
-    await session.flush();
-    return true;
-  }
-
-  let root: Context | undefined;
-
-  /**
-   * The Session store, if this root has one.
-   *
-   * Not an `inject`: these tools are the User's own MCP records and they work
-   * with no Session at all — `mcp_server_status` is answered outside a Turn in
-   * several tests and in the lifecycle surface. Only the connect card needs a
-   * Session, and without one it degrades to "the decision was recorded, no card
-   * was drawn" rather than costing the whole lifecycle its mount.
-   */
-  const sessionStore = (): Context["sessions"] | undefined => {
-    try {
-      return root?.sessions;
-    } catch {
-      return undefined;
-    }
-  };
-
   const plugin: Plugin.Function = (ctx: Context) => {
-    root = ctx;
     const disposers = definitions.map((definition) =>
       ctx.tools.register(definition, {
         admissionCeiling: MCP_LIFECYCLE_TURN_TYPES,
@@ -393,7 +249,6 @@ export function createMcpLifecycleRuntimePlugin(
     );
     return () => {
       for (const dispose of disposers.toReversed()) dispose();
-      root = undefined;
     };
   };
   plugin.inject = ["tools"];

package/src/mcp-client.ts

@@ -115,10 +115,11 @@ export class McpProtocolError extends Error {
  * The server said "authorize first".
  *
  * A 401 carrying `WWW-Authenticate: Bearer …` is the one MCP failure that is
- * not a broken server: it is a durable pending decision for the User. It is a
- * subclass rather than a sibling so every existing `McpProtocolError` handler
- * keeps working, and typed rather than a status check so the runtime seam and
- * the durable record agree on what it means without re-deriving it from prose.
+ * not a broken server: it puts the existing User Connection into a durable
+ * repair state. It is a subclass rather than a sibling so every existing
+ * `McpProtocolError` handler keeps working, and typed rather than a status
+ * check so the runtime seam and the durable record agree on what it means
+ * without re-deriving it from prose.
  */
 export class McpAuthorizationRequiredError extends McpProtocolError {
   /** RFC 9728 §5.1's `resource_metadata`, when the server named one. */

package/src/oauth-user.test.ts

@@ -728,49 +728,4 @@ describe("the pending-authorization projection", () => {
       { reason: "needs-auth", connectionId },
     );
   });
-
-  test("is what a Bot's request writes, and it writes nothing else", async () => {
-    const world = await fixture();
-    const { connectionId } = await connect(world);
-
-    const receipt = await world.mcp.executeLifecycle(ACCOUNT, {
-      schemaVersion: 1,
-      type: "mcp/request-authorization",
-      commandId: "bot-asked-1",
-      serverId: connectionId,
-    });
-    expect(receipt.status).toBe("applied");
-
-    // The decision is pending, and nothing about the server changed: a Bot
-    // does not get to declare its User's server broken.
-    expect((await world.read(connectionId)).pendingAuthorization).toMatchObject(
-      { reason: "needs-auth", connectionId },
-    );
-    expect((await world.read(connectionId)).state).toBe("ready");
-    expect(
-      (await world.mcp.readServerStatus(ACCOUNT)).servers[0],
-    ).toMatchObject({ state: "ready" });
-  });
-
-  test("refuses a Bot's request against a server that has nothing to authorize", async () => {
-    const world = await fixture();
-    const receipt = await world.mcp.executeLifecycle(ACCOUNT, {
-      schemaVersion: 1,
-      type: "mcp/add-server",
-      commandId: "add-public-1",
-      label: "Public",
-      url: SERVER,
-      transport: "streamable-http",
-    });
-    // The public server has no token, so there is no 401 path to it here; the
-    // request-authorization refusal is the assertion.
-    const refused = await world.mcp.executeLifecycle(ACCOUNT, {
-      schemaVersion: 1,
-      type: "mcp/request-authorization",
-      commandId: "bot-asked-2",
-      serverId: receipt.serverId!,
-    });
-    expect(refused.status).toBe("refused");
-    expect(refused.code).toBe("unauthorized");
-  });
 });

package/src/records.ts

@@ -393,24 +393,8 @@ export interface McpRestartCommandV1 {
   serverId: string;
 }
 
-/**
- * GrokBot's `AuthenticateMcpServer`, as the constitution requires it to be: a
- * Bot records a durable pending decision for its User and receives no link, no
- * token and no grant. Chat-only, because an automation Turn has no User in
- * front of it to decide.
- */
-export interface McpRequestAuthorizationCommandV1 {
-  schemaVersion: 1;
-  type: "mcp/request-authorization";
-  commandId: string;
-  serverId: string;
-}
-
 export type McpLifecycleCommandV1 =
-  | McpAddServerCommandV1
-  | McpSetInstructionsCommandV1
-  | McpRestartCommandV1
-  | McpRequestAuthorizationCommandV1;
+  McpAddServerCommandV1 | McpSetInstructionsCommandV1 | McpRestartCommandV1;
 
 export function decodeMcpLifecycleCommandV1(
   input: unknown,
@@ -504,19 +488,6 @@ export function decodeMcpLifecycleCommandV1(
         serverId: text(value.serverId, "serverId", 128),
       };
     }
-    case "mcp/request-authorization": {
-      exact(
-        value,
-        ["schemaVersion", "type", "commandId", "serverId"],
-        "mcp/request-authorization",
-      );
-      return {
-        schemaVersion: 1,
-        type: "mcp/request-authorization",
-        commandId,
-        serverId: text(value.serverId, "serverId", 128),
-      };
-    }
     default:
       throw new Error(
         `MCP lifecycle command "${String(value.type)}" is unknown`,

package/src/user.ts

@@ -485,43 +485,6 @@ export class McpUserBackendContribution {
           serverId: command.serverId,
         };
       }
-      case "mcp/request-authorization": {
-        // A durable pending decision, never a grant. The server record is left
-        // exactly as it is — a Bot does not get to declare its User's server
-        // broken — and what changes is the Connection projection the User's
-        // own surface draws a connect card from. No URL is minted here, and
-        // none is returned: only an authenticated `connection/start` does that.
-        const server = await this.requireServer(accountId, command.serverId);
-        const connection = await this.requireConnection(
-          accountId,
-          command.serverId,
-        );
-        if (connection.connectionTypeId !== MCP_OAUTH_CONNECTION_TYPE_ID) {
-          return this.refuse(command, {
-            code: "unauthorized",
-            message:
-              "This MCP server does not use OAuth, so there is nothing for the User to authorize. A keyed server needs a new key instead.",
-          });
-        }
-        await this.host.settings.replaceConnection(
-          accountId,
-          connection.connectionId,
-          connection.generation,
-          {
-            ...connection,
-            pendingAuthorization: mcpPendingAuthorizationV1(
-              server,
-              new Date(this.now()).toISOString(),
-            ),
-          },
-        );
-        return {
-          schemaVersion: 1,
-          commandId: command.commandId,
-          status: "applied",
-          serverId: command.serverId,
-        };
-      }
       case "mcp/restart": {
         const server = await this.requireServer(accountId, command.serverId);
         const connection = await this.requireConnection(
@@ -805,7 +768,7 @@ export class McpUserBackendContribution {
 
   /**
    * Mint one authorization. Only an authenticated User action reaches here —
-   * a Bot may record a pending decision, never a redirect.
+   * a Bot cannot request this path or receive a redirect.
    *
    * Order matters and is the durability argument: the quota is charged, the
    * Connection exists in `authorizing`, and the pending record carrying the

package/src/connect-card.test.ts

@@ -1,226 +0,0 @@
-/**
- * The connect card and the durable pending decision behind it.
- *
- * One rule holds these together and every test here is a restatement of it: a
- * Bot may record that its User needs to authorize something, and only the User
- * may authorize it. Nothing a Bot writes — the projection, the card payload,
- * the tool's own answer — may contain a link.
- */
-import { describe, expect, test } from "bun:test";
-import { Context } from "cordis";
-import { ToolRegistry } from "@frockbot/plugin-tools";
-import { decodeSendToUserPayloadV1 } from "@frockbot/kernel-contracts";
-import { decodePendingAuthorizationV1 } from "@frockbot/configuration-core";
-import { createMcpLifecycleRuntimePlugin } from "./lifecycle-tools.js";
-import { mcpPendingAuthorizationV1 } from "./records.js";
-import type {
-  McpLifecycleReceiptV1,
-  McpServerRecordV1,
-  McpServerStatusViewV1,
-} from "./records.js";
-
-const SERVER: McpServerRecordV1 = {
-  schemaVersion: 1,
-  serverId: "mcp-1",
-  label: "OAuth Example",
-  url: "https://mcp.example.test/mcp-oauth",
-  transport: "streamable-http",
-  serverEpoch: 1,
-  state: "needs-auth",
-  toolCount: 0,
-  toolsHash: "",
-  lastHandshakeAt: "2026-09-01T00:00:00.000Z",
-  failure: {
-    code: "unauthorized",
-    message: "MCP server answered 401",
-    at: "2026-09-01T00:00:00.000Z",
-  },
-};
-
-const STATUS: McpServerStatusViewV1 = {
-  schemaVersion: 1,
-  servers: [SERVER],
-  refusals: [],
-  quotas: { maxServers: 16, maxToolsPerServer: 64, maxResponseBytes: 262_144 },
-};
-
-const CALL_CONTEXT = {
-  botId: "bot-1",
-  agentId: "agent-1",
-  sessionId: "session-1",
-  compositionGenerationId: "generation-1",
-  effectId: "effect-1",
-  signal: new AbortController().signal,
-};
-
-describe("the pending-authorization projection", () => {
-  test("carries the reason, the moment, the Connection and its label — and no URL", () => {
-    const pending = mcpPendingAuthorizationV1(SERVER, SERVER.lastHandshakeAt);
-    expect(pending).toEqual({
-      reason: "needs-auth",
-      since: "2026-09-01T00:00:00.000Z",
-      connectionId: "mcp-1",
-      label: "OAuth Example",
-    });
-    // The server's own URL is in the record; it is not in the projection, and
-    // neither is anything else that could be followed.
-    expect(JSON.stringify(pending)).not.toContain("https://");
-    expect(decodePendingAuthorizationV1(pending)).toEqual(pending);
-  });
-
-  test("is refused if anything tries to smuggle a redirect onto it", () => {
-    expect(() =>
-      decodePendingAuthorizationV1({
-        ...mcpPendingAuthorizationV1(SERVER, SERVER.lastHandshakeAt),
-        redirectUrl: "https://auth.example.test/authorize?code_challenge=x",
-      }),
-    ).toThrow();
-  });
-});
-
-describe("the connect-card send payload", () => {
-  test("decodes with a Connection, a title and a body, and nothing else", () => {
-    const payload = decodeSendToUserPayloadV1({
-      type: "connect-card",
-      connectionId: "mcp-1",
-      title: "Connect OAuth Example",
-      body: "I need it to read your calendar.",
-    });
-    expect(payload).toEqual({
-      type: "connect-card",
-      connectionId: "mcp-1",
-      title: "Connect OAuth Example",
-      body: "I need it to read your calendar.",
-    });
-  });
-
-  test("refuses a payload carrying a URL", () => {
-    for (const extra of [
-      { url: "https://auth.example.test/authorize" },
-      { redirectUrl: "https://auth.example.test/authorize" },
-      { href: "https://auth.example.test/authorize" },
-    ]) {
-      expect(() =>
-        decodeSendToUserPayloadV1({
-          type: "connect-card",
-          connectionId: "mcp-1",
-          title: "Connect",
-          ...extra,
-        }),
-      ).toThrow(/unexpected key/);
-    }
-  });
-});
-
-function fixture(options: { status?: McpServerStatusViewV1 } = {}) {
-  const commands: unknown[] = [];
-  const appended: unknown[] = [];
-  const session = {
-    events: [{ type: "step/start", turn: 1, step: 1 }],
-    append: (event: unknown) => {
-      appended.push(event);
-    },
-    flush: () => Promise.resolve(),
-  };
-  const root = new Context();
-  let id = 0;
-  const ready = (async () => {
-    await root.plugin(ToolRegistry);
-    // The Session store the Agent loop provides. Registered as a service so
-    // the lifecycle Plugin finds it exactly as it does in a real Turn.
-    root.provide("sessions");
-    root.sessions = { get: () => session } as never;
-    await root.plugin(
-      createMcpLifecycleRuntimePlugin({
-        readStatus: () => Promise.resolve(options.status ?? STATUS),
-        execute: (command) => {
-          commands.push(command);
-          return Promise.resolve({
-            schemaVersion: 1,
-            commandId: "applied",
-            status: "applied",
-            serverId: "mcp-1",
-          } satisfies McpLifecycleReceiptV1);
-        },
-        randomId: () => `command-${++id}`,
-      }),
-    );
-  })();
-  return { root, commands, appended, ready };
-}
-
-async function call(
-  root: Context,
-  name: string,
-  input: unknown,
-): Promise<{ content: string; isError: boolean }> {
-  const toolCall = { id: "call-1", name, input };
-  const prepared = await root.tools.prepare(toolCall, {
-    ...CALL_CONTEXT,
-    toolCall,
-    turnType: "chat" as const,
-  });
-  if (prepared.kind !== "ready") return prepared.result;
-  return root.tools.executePrepared(prepared, {
-    ...CALL_CONTEXT,
-    toolCall,
-    turnType: "chat" as const,
-  });
-}
-
-describe("mcp_authenticate_server", () => {
-  test("is offered on a chat turn and nowhere else", async () => {
-    const { root, ready } = fixture();
-    await ready;
-    expect(
-      root.tools.schemas({ turnType: "chat" }).map((tool) => tool.name),
-    ).toContain("mcp_authenticate_server");
-    for (const turnType of ["automation", "subagent"] as const) {
-      expect(
-        root.tools.schemas({ turnType }).map((tool) => tool.name),
-      ).not.toContain("mcp_authenticate_server");
-    }
-  });
-
-  test("records a durable pending decision and emits a card with no URL", async () => {
-    const { root, commands, appended, ready } = fixture();
-    await ready;
-
-    const result = await call(root, "mcp_authenticate_server", {
-      server_id: "mcp-1",
-      reason: "I need it to read your calendar.",
-    });
-
-    expect(result.isError).toBe(false);
-    expect(commands).toEqual([
-      {
-        schemaVersion: 1,
-        type: "mcp/request-authorization",
-        commandId: "command-1",
-        serverId: "mcp-1",
-      },
-    ]);
-    expect(appended).toHaveLength(1);
-    const event = appended[0] as { type: string; payload: unknown };
-    expect(event.type).toBe("send/to-user");
-    expect(decodeSendToUserPayloadV1(event.payload)).toEqual({
-      type: "connect-card",
-      connectionId: "mcp-1",
-      title: "Connect OAuth Example",
-      body: "I need it to read your calendar.",
-    });
-    // Not the tool's answer, not the card: no link anywhere the Bot can see.
-    expect(JSON.stringify(event.payload)).not.toContain("http");
-    expect(result.content).not.toContain("http");
-  });
-
-  test("says so rather than inventing a server it was not given", async () => {
-    const { root, commands, ready } = fixture();
-    await ready;
-    const result = await call(root, "mcp_authenticate_server", {
-      server_id: "mcp-missing",
-    });
-    expect(result.isError).toBe(true);
-    expect(commands).toEqual([]);
-  });
-});