@frockbot/plugin-composio 0.0.0 → 0.1.1

package/frockbot.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 3,
+  "id": "composio",
+  "displayName": "Composio",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "contributions": {
+    "backend": [
+      { "entry": "./backend", "host": "gateway" },
+      { "entry": "./user-configuration", "host": "user" }
+    ],
+    "runtime": { "entry": "./agent" }
+  },
+  "permissions": ["connections:manage", "tools:execute"],
+  "configuration": {
+    "settings": [],
+    "connectionTypes": [
+      {
+        "id": "gmail",
+        "displayName": "Gmail",
+        "allowMultiple": true,
+        "authorization": { "kind": "grant", "driverId": "composio" },
+        "capabilities": ["gmail-tools"]
+      }
+    ],
+    "capabilities": [
+      {
+        "id": "gmail-tools",
+        "kind": "tool",
+        "connectionTypes": ["gmail"]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,45 @@
 {
   "name": "@frockbot/plugin-composio",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/composio-client.ts",
+    "./backend": "./src/backend.ts",
+    "./backend-contracts": "./src/backend-contracts.ts",
+    "./user-configuration": "./src/user-configuration.ts",
+    "./agent": "./src/agent.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/configuration-core": "0.1.1",
+    "@frockbot/connection-core": "0.1.1",
+    "@frockbot/kernel-contracts": "0.1.1",
+    "@frockbot/plugin-settings": "0.1.1",
+    "@frockbot/plugin-tools": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "latest",
+    "@types/bun": "1.3.6",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-composio"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,207 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { type SessionEvent, SessionStore } from "@frockbot/kernel-contracts";
+import { ToolRegistry } from "@frockbot/plugin-tools";
+import { Context } from "cordis";
+import { createComposioRouterPlugin } from "./agent.js";
+import { ComposioClient } from "./composio-client.js";
+
+const roots: Context[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => root.fiber.dispose()));
+});
+
+describe("Composio router Plugin", () => {
+  test("refuses invented slugs until search returns the exact tool", async () => {
+    const calls: string[] = [];
+    let authorizationCalls = 0;
+    const client = new ComposioClient({
+      apiKey: "secret",
+      fetch: (input) => {
+        const url = String(input);
+        calls.push(url);
+        if (url.includes("/tools?")) {
+          return Promise.resolve(
+            Response.json({
+              items: [
+                {
+                  slug: "GMAIL_FETCH_EMAILS",
+                  name: "Fetch emails",
+                  description: "Fetch Gmail messages",
+                },
+              ],
+            }),
+          );
+        }
+        return Promise.resolve(Response.json({ data: { messages: [] } }));
+      },
+    });
+    const root = new Context();
+    roots.push(root);
+    await root.plugin(SessionStore);
+    await root.plugin(ToolRegistry);
+    await root.plugin(
+      createComposioRouterPlugin({
+        client,
+        userId: "user-1",
+        toolkitSlug: "gmail",
+        authorizeEffect: () => {
+          authorizationCalls += 1;
+          return Promise.resolve({
+            connectedAccountId: "ca_123",
+            toolkitSlug: "gmail",
+          });
+        },
+      }),
+    );
+    const context = {
+      botId: "primary",
+      agentId: "primary",
+      compositionGenerationId: "bootstrap",
+      turnType: "chat" as const,
+      sessionId: "user-1:primary",
+      effectId: "tool:1:1:0",
+      signal: new AbortController().signal,
+    };
+
+    const invented = await root.tools.prepare(
+      {
+        id: "invented",
+        name: "composio_execute_tool",
+        input: { toolSlug: "GMAIL_FETCH_EMAILS", arguments: {} },
+      },
+      context,
+    );
+    if (invented.kind !== "ready") throw new Error("execute tool was denied");
+    expect(await root.tools.executePrepared(invented, context)).toMatchObject({
+      isError: true,
+    });
+    expect(calls).toEqual([]);
+
+    const search = await root.tools.prepare(
+      {
+        id: "search",
+        name: "composio_search_tools",
+        input: { query: "fetch emails" },
+      },
+      context,
+    );
+    if (search.kind !== "ready") throw new Error("search tool was denied");
+    expect(await root.tools.executePrepared(search, context)).toMatchObject({
+      isError: false,
+    });
+
+    const exact = await root.tools.prepare(
+      {
+        id: "exact",
+        name: "composio_execute_tool",
+        input: { toolSlug: "GMAIL_FETCH_EMAILS", arguments: {} },
+      },
+      context,
+    );
+    if (exact.kind !== "ready") throw new Error("execute tool was denied");
+    expect(await root.tools.executePrepared(exact, context)).toMatchObject({
+      isError: false,
+    });
+    expect(calls).toHaveLength(2);
+    expect(authorizationCalls).toBe(2);
+  });
+
+  test("restores searched slug authorization from the durable session", async () => {
+    const timestamp = "2026-08-28T00:00:00.000Z";
+    const durableEvents = [
+      {
+        type: "session/created",
+        createdAt: timestamp,
+      },
+      {
+        type: "assistant/message",
+        turn: 1,
+        step: 1,
+        requestId: "search-request",
+        text: "",
+        toolCalls: [
+          {
+            id: "search-before-eviction",
+            name: "composio_search_tools",
+            input: {},
+          },
+        ],
+      },
+      {
+        type: "tool/call",
+        turn: 1,
+        step: 1,
+        occurrenceId: "tool:1:1:0",
+        name: "composio_search_tools",
+        input: {},
+      },
+      {
+        type: "tool/result",
+        turn: 1,
+        step: 1,
+        occurrenceId: "tool:1:1:0",
+        name: "composio_search_tools",
+        content: JSON.stringify([
+          {
+            slug: "GMAIL_FETCH_EMAILS",
+            name: "Fetch emails",
+            description: "Fetch Gmail messages",
+          },
+        ]),
+        isError: false,
+        status: "completed",
+      },
+    ].map((event, seq) => ({ ...event, seq, timestamp })) as SessionEvent[];
+    const calls: string[] = [];
+    const client = new ComposioClient({
+      apiKey: "secret",
+      fetch: (input) => {
+        calls.push(String(input));
+        return Promise.resolve(Response.json({ data: { messages: [] } }));
+      },
+    });
+    const root = new Context();
+    roots.push(root);
+    await root.plugin(SessionStore, {
+      initialSessions: { "resumed-session": durableEvents },
+    });
+    root.sessions.create("resumed-session");
+    await root.plugin(ToolRegistry);
+    await root.plugin(
+      createComposioRouterPlugin({
+        client,
+        userId: "user-1",
+        toolkitSlug: "gmail",
+        authorizeEffect: () =>
+          Promise.resolve({
+            connectedAccountId: "ca_123",
+            toolkitSlug: "gmail",
+          }),
+      }),
+    );
+    const context = {
+      botId: "primary",
+      agentId: "primary",
+      compositionGenerationId: "bootstrap",
+      turnType: "chat" as const,
+      sessionId: "resumed-session",
+      effectId: "tool:1:1:1",
+      signal: new AbortController().signal,
+    };
+    const execution = await root.tools.prepare(
+      {
+        id: "execute-after-eviction",
+        name: "composio_execute_tool",
+        input: { toolSlug: "GMAIL_FETCH_EMAILS", arguments: {} },
+      },
+      context,
+    );
+    if (execution.kind !== "ready") throw new Error("execute tool was denied");
+
+    await expect(
+      root.tools.executePrepared(execution, context),
+    ).resolves.toMatchObject({ isError: false });
+    expect(calls).toHaveLength(1);
+  });
+});

package/src/agent.ts

@@ -0,0 +1,227 @@
+import { type ToolDefinition } from "@frockbot/kernel-contracts";
+import type { Context, Plugin } from "cordis";
+import { ComposioClient } from "./composio-client.js";
+
+export interface ComposioToolDeclaration {
+  slug: string;
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  version?: string;
+}
+
+export interface ComposioPluginConfig {
+  client: ComposioClient;
+  userId: string;
+  connectedAccountId: string;
+  tools: ComposioToolDeclaration[];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface ComposioRouterPluginConfig {
+  client: ComposioClient;
+  userId: string;
+  toolkitSlug: string;
+  authorizeEffect(): Promise<{
+    connectedAccountId: string;
+    toolkitSlug: string;
+  }>;
+}
+
+export function createConfiguredComposioRuntimeContribution(config: {
+  assignment: {
+    packageId: string;
+    capabilityId: string;
+    connectionId?: string;
+    state: string;
+  };
+  userId: string;
+  readSecret(name: string): string | undefined;
+  authorizeConnection(): Promise<{ safeMetadata: Record<string, unknown> }>;
+}): Plugin.Function | undefined {
+  if (
+    config.assignment.packageId !== "composio" ||
+    config.assignment.capabilityId !== "gmail-tools" ||
+    config.assignment.state !== "enabled" ||
+    !config.assignment.connectionId
+  ) {
+    return undefined;
+  }
+  const apiKey = config.readSecret("COMPOSIO_API_KEY");
+  if (!apiKey) throw new Error("Assigned Composio Connection is misconfigured");
+  const authorizeEffect = async () => {
+    const connection = await config.authorizeConnection();
+    const connectedAccountId = connection.safeMetadata.connectedAccountId;
+    const toolkitSlug = connection.safeMetadata.toolkitSlug;
+    if (
+      typeof connectedAccountId !== "string" ||
+      typeof toolkitSlug !== "string"
+    ) {
+      throw new Error("Composio effect is no longer authorized");
+    }
+    return { connectedAccountId, toolkitSlug };
+  };
+  return createComposioRouterPlugin({
+    client: new ComposioClient({ apiKey }),
+    userId: config.userId,
+    toolkitSlug: "gmail",
+    authorizeEffect,
+  });
+}
+
+export function createComposioRouterPlugin(
+  config: ComposioRouterPluginConfig,
+): Plugin.Function {
+  const allowedToolSlugs = new Set<string>();
+  let runtimeContext: Context | undefined;
+  const search: ToolDefinition = {
+    name: "composio_search_tools",
+    // A general work tool: the full toolset an `executor` subagent gets, and
+    // not part of the narrow reach of `browserUse`, `computerUse`, or the two
+    // video roles. See `@frockbot/plugin-subagents` `SUBAGENT_TOOL_REACH_V1`.
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Search the connected toolkit for exact Composio tool slugs before executing one.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+    },
+    validate: isObject,
+    execute: async (input: unknown) => {
+      const query =
+        isObject(input) && typeof input.query === "string"
+          ? input.query
+          : undefined;
+      const grant = await config.authorizeEffect();
+      if (grant.toolkitSlug !== config.toolkitSlug) {
+        throw new Error("Composio effect grant changed toolkit");
+      }
+      const result = await config.client.searchTools(grant.toolkitSlug, query);
+      for (const tool of result) allowedToolSlugs.add(tool.slug);
+      return { content: JSON.stringify(result), isError: false };
+    },
+  };
+  const execute: ToolDefinition = {
+    name: "composio_execute_tool",
+    // A general work tool: the full toolset an `executor` subagent gets, and
+    // not part of the narrow reach of `browserUse`, `computerUse`, or the two
+    // video roles. See `@frockbot/plugin-subagents` `SUBAGENT_TOOL_REACH_V1`.
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Execute an exact Composio tool slug returned by composio_search_tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        toolSlug: { type: "string" },
+        arguments: { type: "object" },
+      },
+      required: ["toolSlug", "arguments"],
+    },
+    validate: (input: unknown) =>
+      isObject(input) &&
+      typeof input.toolSlug === "string" &&
+      isObject(input.arguments),
+    execute: async (input: unknown, context) => {
+      if (
+        !isObject(input) ||
+        typeof input.toolSlug !== "string" ||
+        !isObject(input.arguments)
+      ) {
+        return { content: "Invalid Composio tool input", isError: true };
+      }
+      const wasDurablySearched = runtimeContext?.sessions
+        .get(context.sessionId)
+        ?.events.some((event) => {
+          if (
+            event.type !== "tool/result" ||
+            event.name !== "composio_search_tools" ||
+            event.isError
+          ) {
+            return false;
+          }
+          try {
+            const result: unknown = JSON.parse(event.content);
+            return (
+              Array.isArray(result) &&
+              result.some(
+                (candidate) =>
+                  isObject(candidate) && candidate.slug === input.toolSlug,
+              )
+            );
+          } catch {
+            return false;
+          }
+        });
+      if (!allowedToolSlugs.has(input.toolSlug) && !wasDurablySearched) {
+        return {
+          content:
+            "Tool slug was not returned by composio_search_tools in this runtime.",
+          isError: true,
+        };
+      }
+      const grant = await config.authorizeEffect();
+      if (grant.toolkitSlug !== config.toolkitSlug) {
+        return {
+          content: "Composio effect grant changed toolkit",
+          isError: true,
+        };
+      }
+      const result = await config.client.executeTool({
+        toolSlug: input.toolSlug,
+        userId: config.userId,
+        connectedAccountId: grant.connectedAccountId,
+        arguments: input.arguments,
+      });
+      return { content: JSON.stringify(result), isError: false };
+    },
+  };
+  const plugin: Plugin.Function = (ctx: Context) => {
+    runtimeContext = ctx;
+    const removeSearch = ctx.tools.register(search);
+    const removeExecute = ctx.tools.register(execute);
+    return () => {
+      runtimeContext = undefined;
+      removeExecute();
+      removeSearch();
+    };
+  };
+  plugin.inject = ["tools", "sessions"];
+  return plugin;
+}
+
+export function createComposioPlugin(
+  config: ComposioPluginConfig,
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx: Context) => {
+    const disposers = config.tools.map((declaration) => {
+      const tool: ToolDefinition = {
+        name: declaration.name,
+        description: declaration.description,
+        inputSchema: declaration.inputSchema,
+        validate: isObject,
+        execute: async (input: unknown) => {
+          const result = await config.client.executeTool({
+            toolSlug: declaration.slug,
+            userId: config.userId,
+            connectedAccountId: config.connectedAccountId,
+            version: declaration.version,
+            arguments: input as Record<string, unknown>,
+          });
+          return {
+            content: JSON.stringify(result),
+            isError: false,
+          };
+        },
+      };
+      return ctx.tools.register(tool);
+    });
+    return () => {
+      for (const dispose of disposers.toReversed()) dispose();
+    };
+  };
+  plugin.inject = ["tools"];
+  return plugin;
+}

package/src/backend-contracts.ts

@@ -0,0 +1,8 @@
+export {
+  decodeRevokeConnectionResultV1,
+  decodeStartConnectionResultV1,
+  type ConnectionCompletionResult,
+  type RevokeConnectionResult,
+  type StartConnectionResult,
+  // pi-lens-ignore: ts:2307
+} from "@frockbot/connection-core";