@frockbot/plugin-mcp 0.1.3 → 0.2.0

package/package.json

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

package/src/agent.test.ts

@@ -6,7 +6,7 @@ import {
   createConfiguredMcpRuntimeContribution,
   decodeMcpConnectionSettingsV1,
   MAX_MCP_SERVERS_PER_USER_V1,
-  mcpAssignmentResolutionV1,
+  mcpCapabilityResolutionV1,
   mcpConnectionLifecycleV1,
   mcpServerSlugV1,
   mcpToolNameV1,
@@ -96,20 +96,19 @@ function server(options: {
 async function mount(config: {
   fetch: typeof fetch;
   connection?: ConnectionView;
-  assignmentIndex?: number;
+  capabilityIndex?: number;
   failures?: string[];
   outcomes?: unknown[];
 }): Promise<{ root: Context; mounted: boolean }> {
   const plugin = await createConfiguredMcpRuntimeContribution({
-    assignment: {
+    capability: {
       packageId: "mcp",
       capabilityId: "mcp-tools",
       connectionId: "mcp-1",
-      state: "enabled",
     },
-    ...(config.assignmentIndex === undefined
+    ...(config.capabilityIndex === undefined
       ? {}
-      : { assignmentIndex: config.assignmentIndex }),
+      : { capabilityIndex: config.capabilityIndex }),
     userId: "user-1",
     readSecret: () => undefined,
     authorizeConnection: () =>
@@ -170,7 +169,7 @@ describe("Connection-scoped settings", () => {
   });
 });
 
-describe("mounting one Assignment", () => {
+describe("mounting one enabled Capability", () => {
   test("registers every listed tool with the server's own schema", async () => {
     const { root } = await mount({ fetch: server({}) });
 
@@ -284,7 +283,7 @@ describe("mounting one Assignment", () => {
     const { mounted } = await mount({
       failures,
       fetch: server({}),
-      assignmentIndex: MAX_MCP_SERVERS_PER_USER_V1,
+      capabilityIndex: MAX_MCP_SERVERS_PER_USER_V1,
     });
 
     expect(mounted).toBe(false);
@@ -385,13 +384,13 @@ describe("the durable lifecycle a mount participates in", () => {
     });
   });
 
-  test("the Assignment's resolution key moves with the server epoch", () => {
-    const before = mcpAssignmentResolutionV1({
-      assignment: { connectionId: "mcp-1" },
+  test("the Capability's resolution key moves with the server epoch", () => {
+    const before = mcpCapabilityResolutionV1({
+      capability: { connectionId: "mcp-1" },
       connection: connection({ safeMetadata: { serverEpoch: 1 } }),
     });
-    const restarted = mcpAssignmentResolutionV1({
-      assignment: { connectionId: "mcp-1" },
+    const restarted = mcpCapabilityResolutionV1({
+      capability: { connectionId: "mcp-1" },
       connection: connection({ safeMetadata: { serverEpoch: 2 } }),
     });
     expect(restarted).not.toBe(before);

package/src/agent.ts

@@ -1,5 +1,5 @@
 /**
- * The runtime Contribution: one enabled Assignment of `mcp-tools` becomes one
+ * The runtime Contribution: one enabled `mcp-tools` Capability becomes one
  * remote MCP server's tools in the Bot's tool registry.
  *
  * Everything the Bot ever sees of a server passes through here, and every byte
@@ -27,7 +27,7 @@ import {
 import { mcpAuthorizationRequiredV1 } from "./oauth.js";
 import { decodeOutboundMcpUrlV1 } from "./ssrf.js";
 import {
-  mcpAssignmentResolutionKeyV1,
+  mcpCapabilityResolutionKeyV1,
   mcpFailureCodeV1,
   MAX_MCP_INSTRUCTIONS_BYTES_V1,
   type McpFailureCodeV1,
@@ -62,8 +62,8 @@ export const MCP_TOOL_SUBAGENT_ROLES: readonly string[] = ["executor"];
 
 /**
  * The durable per-User ceiling on remote MCP servers. Counted over the enabled
- * Assignments of this Package, so a Bot cannot be handed a seventeenth server
- * by adding one more Assignment.
+ * Capabilities of this Package, so a Bot cannot be handed a seventeenth server
+ * by enabling one more Connection.
  */
 export const MAX_MCP_SERVERS_PER_USER_V1 = 16;
 
@@ -200,18 +200,17 @@ function isObject(value: unknown): value is Record<string, unknown> {
 }
 
 export interface McpRuntimeContributionConfig {
-  assignment: {
+  capability: {
     packageId: string;
     capabilityId: string;
     connectionId?: string;
-    state: string;
   };
   /**
-   * This Assignment's ordinal among the enabled Assignments of this Package,
+   * This Capability's ordinal among the enabled ones of this Package,
    * which is what makes the per-User server ceiling countable from inside a
-   * per-Assignment factory.
+   * per-Capability factory.
    */
-  assignmentIndex?: number;
+  capabilityIndex?: number;
   userId: string;
   readSecret(name: string): string | undefined;
   authorizeConnection(): Promise<ConnectionView>;
@@ -240,7 +239,7 @@ export interface McpRuntimeContributionConfig {
 }
 
 /**
- * Resolve one Assignment into a mounted runtime Plugin. The handshake and
+ * Resolve one enabled Capability into a mounted runtime Plugin. The handshake and
  * `tools/list` happen here, before the Plugin mounts, so a server that cannot
  * be reached contributes nothing instead of half-registering.
  */
@@ -248,23 +247,22 @@ export async function createConfiguredMcpRuntimeContribution(
   config: McpRuntimeContributionConfig,
 ): Promise<Plugin.Function | undefined> {
   if (
-    config.assignment.packageId !== MCP_PACKAGE_ID ||
-    config.assignment.capabilityId !== MCP_CAPABILITY_ID ||
-    config.assignment.state !== "enabled" ||
-    !config.assignment.connectionId
+    config.capability.packageId !== MCP_PACKAGE_ID ||
+    config.capability.capabilityId !== MCP_CAPABILITY_ID ||
+    !config.capability.connectionId
   ) {
     return undefined;
   }
-  if ((config.assignmentIndex ?? 0) >= MAX_MCP_SERVERS_PER_USER_V1) {
+  if ((config.capabilityIndex ?? 0) >= MAX_MCP_SERVERS_PER_USER_V1) {
     config.onFailure?.(
-      `A User may assign at most ${MAX_MCP_SERVERS_PER_USER_V1} MCP servers`,
+      `A User may enable at most ${MAX_MCP_SERVERS_PER_USER_V1} MCP servers`,
     );
     return undefined;
   }
   const fetchImpl = config.fetch ?? boundFetch;
   let client: McpClient | undefined;
   let lifecycle: { serverEpoch?: number; instructions?: string } = {};
-  const connectionId = config.assignment.connectionId;
+  const connectionId = config.capability.connectionId;
   try {
     const connection = await config.authorizeConnection();
     lifecycle = mcpConnectionLifecycleV1(connection);
@@ -275,7 +273,7 @@ export async function createConfiguredMcpRuntimeContribution(
     const apiKey =
       connection.connectionTypeId === MCP_KEYED_CONNECTION_TYPE_ID ||
       connection.connectionTypeId === MCP_OAUTH_CONNECTION_TYPE_ID
-        ? await openAssignedCredential(config, connection)
+        ? await openEnabledCredential(config, connection)
         : undefined;
     client = new McpClient({
       url: settings.url,
@@ -372,18 +370,18 @@ export async function createConfiguredMcpRuntimeContribution(
 }
 
 /**
- * What one Assignment of `mcp-tools` resolves to, including the server's
+ * What one enabled `mcp-tools` Capability resolves to, including the server's
  * `serverEpoch`. A restart bumps the epoch, so this key changes, so the next
  * admitted Turn resolves a different mount and re-handshakes — while the
  * in-flight Turn, holding the client it already mounted, is untouched.
  */
-export function mcpAssignmentResolutionV1(config: {
-  assignment: { connectionId?: string };
+export function mcpCapabilityResolutionV1(config: {
+  capability: { connectionId?: string };
   connection: { generation?: string; safeMetadata?: Record<string, unknown> };
 }): string {
   const lifecycle = mcpConnectionLifecycleV1(config.connection);
-  return mcpAssignmentResolutionKeyV1({
-    connectionId: config.assignment.connectionId ?? "",
+  return mcpCapabilityResolutionKeyV1({
+    connectionId: config.capability.connectionId ?? "",
     ...(config.connection.generation === undefined
       ? {}
       : { connectionGeneration: config.connection.generation }),
@@ -393,7 +391,7 @@ export function mcpAssignmentResolutionV1(config: {
   });
 }
 
-async function openAssignedCredential(
+async function openEnabledCredential(
   config: McpRuntimeContributionConfig,
   connection: ConnectionView,
 ): Promise<string> {

package/src/lifecycle-tools.ts

@@ -12,14 +12,9 @@
  *
  * These tools need no Connection: they read and write the User's own MCP
  * records through the host the Bot's Durable Object supplies, which is why
- * this Contribution mounts for a Turn rather than for an Assignment.
+ * 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.test.ts

@@ -7,7 +7,7 @@ import {
   decodeMcpRefusalRecordV1,
   decodeMcpServerRecordV1,
   decodeMcpServerStatusViewV1,
-  mcpAssignmentResolutionKeyV1,
+  mcpCapabilityResolutionKeyV1,
   mcpConnectionMetadataV1,
   mcpFailureCodeV1,
   type McpServerRecordV1,
@@ -263,19 +263,19 @@ describe("the mount outcome that crosses back from a Bot", () => {
   });
 });
 
-describe("the Assignment resolution key", () => {
+describe("the Capability resolution key", () => {
   test("changes when the server epoch changes, and only then", () => {
-    const before = mcpAssignmentResolutionKeyV1({
+    const before = mcpCapabilityResolutionKeyV1({
       connectionId: "mcp-1",
       connectionGeneration: "gen-1",
       serverEpoch: 1,
     });
-    const restarted = mcpAssignmentResolutionKeyV1({
+    const restarted = mcpCapabilityResolutionKeyV1({
       connectionId: "mcp-1",
       connectionGeneration: "gen-1",
       serverEpoch: 2,
     });
-    const again = mcpAssignmentResolutionKeyV1({
+    const again = mcpCapabilityResolutionKeyV1({
       connectionId: "mcp-1",
       connectionGeneration: "gen-1",
       serverEpoch: 1,
@@ -286,13 +286,13 @@ describe("the Assignment resolution key", () => {
 
   test("changes when the Connection generation changes", () => {
     expect(
-      mcpAssignmentResolutionKeyV1({
+      mcpCapabilityResolutionKeyV1({
         connectionId: "mcp-1",
         connectionGeneration: "gen-2",
         serverEpoch: 1,
       }),
     ).not.toBe(
-      mcpAssignmentResolutionKeyV1({
+      mcpCapabilityResolutionKeyV1({
         connectionId: "mcp-1",
         connectionGeneration: "gen-1",
         serverEpoch: 1,

package/src/records.ts

@@ -96,7 +96,7 @@ export interface McpServerRecordV1 {
   transport: "streamable-http" | "sse";
   instructions?: string;
   /**
-   * Bumped by `mcp/restart`. It participates in the Assignment's resolution
+   * Bumped by `mcp/restart`. It participates in the Capability's resolution
    * key, so the next admitted Turn resolves a different mount and
    * re-handshakes; the in-flight Turn keeps the client it already has.
    */
@@ -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`,
@@ -653,12 +624,12 @@ export function decodeMcpMountOutcomeV1(
 }
 
 /**
- * What one Assignment of `mcp-tools` resolves to. The `serverEpoch` is in it,
+ * What one enabled `mcp-tools` Capability resolves to. The `serverEpoch` is in it,
  * which is the whole of restart semantics: a restart changes this key, the
  * next admitted Turn resolves a different mount and re-handshakes, and the
  * in-flight Turn — already holding its client — is untouched.
  */
-export function mcpAssignmentResolutionKeyV1(input: {
+export function mcpCapabilityResolutionKeyV1(input: {
   connectionId: string;
   connectionGeneration?: string;
   serverEpoch?: number;

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(
@@ -531,7 +494,7 @@ export class McpUserBackendContribution {
         if (connection.state === "revoked" || connection.state === "revoking") {
           throw new Error("MCP Connection is revoked");
         }
-        // The epoch bump is the whole of restart: it is in the Assignment's
+        // The epoch bump is the whole of restart: it is in the Capability's
         // resolution key, so the next admitted Turn resolves a different
         // mount and re-handshakes, while the in-flight Turn keeps the client
         // it already holds. The handshake here refreshes the status the User
@@ -704,7 +667,7 @@ export class McpUserBackendContribution {
       // The Connection generation and the credential generation are the same
       // thing for a keyed server, and deliberately are not for an OAuth one: a
       // refresh rotates the sealed generation without disturbing the
-      // Assignment resolution key a Turn is pinned to.
+      // Capability resolution key a Turn is pinned to.
       expectedGeneration: await this.currentCredentialGeneration(
         input.accountId,
         connection,
@@ -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
@@ -1518,8 +1481,8 @@ export class McpUserBackendContribution {
           { ...connection, state, failure: undefined },
         );
         // GrokBot's `RemoveMcpAccount`: the server is gone, so its record is
-        // gone with it. The Assignments that named it become unavailable
-        // tombstones through the ordinary Connection dependency path.
+        // gone with it. Any Bot that was using the Connection fails closed
+        // when its next Turn resolves the User's enabled capability set.
         await this.removeServer(connection.connectionId);
         return this.receipt(command.commandId, connection.connectionId);
       }

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([]);
-  });
-});