Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

feat(server): add bot plugin controls (#88)

Leo10c0ed2bdd60
diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
index 30bbb74f8..b0d75a1ce 100644
--- a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
@@ -7,6 +7,23 @@ import {
createAkeruPluginRuntime,
} from "./AkeruCatalogToolHandlers.ts";
+const now = "2026-01-01T00:00:00.000Z";
+function snapshot(
+ mcpServers: readonly Record<string, unknown>[] = [],
+ bots: readonly Record<string, unknown>[] = [],
+) {
+ return {
+ snapshotSequence: 0,
+ projects: [],
+ bots,
+ groups: [],
+ delegations: [],
+ mcpServers,
+ threads: [],
+ updatedAt: now,
+ } as never;
+}
+
describe("Akeru catalog MCP tool handlers", () => {
it("authenticates through the session manager and reports the authorization URL", async () => {
const status = {
@@ -83,84 +100,184 @@ describe("Akeru catalog MCP tool handlers", () => {
);
});
- it("omits every catalog handler when no production manager exists", () => {
+ it("omits handlers when neither the plugin runtime nor MCP manager exists", () => {
expect(createAkeruCatalogToolHandlers()).toEqual({});
});
- it("persists and enables URL plugins through orchestration commands", async () => {
- const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);
- const install = createAkeruPluginRuntime({
+ it("searches and inspects the shared directory with health and dependent bots", async () => {
+ const runtime = createAkeruPluginRuntime({
readSnapshot: async () =>
- ({
- mcpServers: [
+ snapshot(
+ [
{
- id: "builtin-search",
- name: "Old search",
+ id: "builtin-exa",
+ name: "Exa",
transport: "url",
- url: "https://old.example.com/mcp",
- enabled: false,
- createdAt: "2026-01-01T00:00:00.000Z",
- updatedAt: "2026-01-01T00:00:00.000Z",
+ url: "https://mcp.exa.ai/mcp",
+ enabled: true,
+ createdAt: now,
+ updatedAt: now,
+ },
+ ],
+ [
+ {
+ id: "bot-research",
+ name: "Research",
+ archivedAt: null,
+ disabledMcpServerIds: [],
+ },
+ {
+ id: "bot-disabled",
+ name: "Disabled",
+ archivedAt: null,
+ disabledMcpServerIds: ["builtin-exa"],
},
],
- }) as never,
+ ),
+ dispatch: async () => undefined,
+ });
+ const statuses = [
+ {
+ name: "builtin-exa",
+ connected: true,
+ toolCount: 2,
+ toolNames: ["search", "research"],
+ transport: "http" as const,
+ },
+ ];
+
+ const search = await runtime.search({ query: "code-search", limit: 5 }, statuses);
+ expect(search.plugins.map((plugin) => plugin.id)).toContain("exa");
+ const exa = await runtime.getPlugin("exa", statuses);
+ expect(exa).toMatchObject({
+ publisher: { name: "Exa Labs" },
+ capabilities: expect.arrayContaining(["search the web"]),
+ permissions: expect.arrayContaining([
+ expect.objectContaining({ id: "read-search-results", approval: "read" }),
+ ]),
+ connection: { type: "ready" },
+ installed: { serverId: "builtin-exa", enabled: true, health: { state: "healthy" } },
+ affectedBots: [{ id: "bot-research", name: "Research" }],
+ affectedRoutines: [],
+ routinesAvailable: false,
+ });
+ await expect(runtime.getPlugin("missing")).rejects.toThrow("was not found");
+ });
+
+ it("installs catalog-owned recipes and enables an existing disabled plugin", async () => {
+ const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);
+ const runtime = createAkeruPluginRuntime({
+ readSnapshot: async () =>
+ snapshot([
+ {
+ id: "builtin-exa",
+ name: "Old Exa",
+ transport: "url",
+ url: "https://old.example.com/mcp",
+ enabled: false,
+ createdAt: now,
+ updatedAt: now,
+ },
+ ]),
dispatch,
id: () => "test-id",
});
- await expect(
- install({
- pluginId: "search",
- name: "Search",
- url: "https://example.com/mcp",
- authentication: "oauth",
- }),
- ).resolves.toEqual({
- mcpServerId: "builtin-search",
+ await expect(runtime.install("exa")).resolves.toMatchObject({
+ pluginId: "exa",
+ mcpServerId: "builtin-exa",
enabled: true,
+ changed: true,
authenticationRequired: true,
+ nextTool: { id: "AuthenticateMcpServer", input: { serverId: "builtin-exa" } },
});
expect(dispatch.mock.calls.map(([command]) => command.type)).toEqual([
"mcp-server.update",
"mcp-server.enable",
]);
expect(dispatch.mock.calls[0]?.[0]).toMatchObject({
- name: "Search",
- url: "https://example.com/mcp",
+ name: "Exa",
+ url: "https://mcp.exa.ai/mcp",
});
});
- it("creates enabled plugins and rejects credential-bearing URLs before persistence", async () => {
+ it("creates enabled plugins and rejects unavailable directory entries", async () => {
const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);
- const install = createAkeruPluginRuntime({
- readSnapshot: async () => ({ mcpServers: [] }) as never,
+ const runtime = createAkeruPluginRuntime({
+ readSnapshot: async () => snapshot(),
dispatch,
- now: () => "2026-01-01T00:00:00.000Z",
+ now: () => now,
id: () => "test-id",
});
- await install({
- pluginId: "public-search",
- name: "Public search",
- url: "https://example.com/mcp",
- authentication: "none",
- });
+ await runtime.install("context");
expect(dispatch).toHaveBeenCalledWith(
expect.objectContaining({
type: "mcp-server.create",
- mcpServerId: "builtin-public-search",
+ mcpServerId: "builtin-context",
+ url: "https://mcp.context.dev/mcp",
enabled: true,
}),
);
-
- await expect(
- install({
- pluginId: "secret-search",
- name: "Secret search",
- url: "https://[email protected]/mcp",
- authentication: "oauth",
- }),
- ).rejects.toThrow("must not contain credentials");
+ await expect(runtime.install("typefully")).rejects.toThrow("not available for installation");
+ await expect(runtime.install("missing")).rejects.toThrow("was not found");
expect(dispatch).toHaveBeenCalledOnce();
});
+
+ it("removes installed plugins with the pre-change dependent view", async () => {
+ const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);
+ const runtime = createAkeruPluginRuntime({
+ readSnapshot: async () =>
+ snapshot(
+ [
+ {
+ id: "builtin-exa",
+ name: "Exa",
+ transport: "url",
+ url: "https://mcp.exa.ai/mcp",
+ enabled: true,
+ createdAt: now,
+ updatedAt: now,
+ },
+ ],
+ [
+ {
+ id: "bot-research",
+ name: "Research",
+ archivedAt: null,
+ disabledMcpServerIds: [],
+ },
+ ],
+ ),
+ dispatch,
+ id: () => "test-id",
+ });
+
+ await expect(runtime.uninstall("exa")).resolves.toMatchObject({
+ removed: true,
+ before: { affectedBots: [{ id: "bot-research", name: "Research" }] },
+ });
+ expect(dispatch).toHaveBeenCalledWith(
+ expect.objectContaining({ type: "mcp-server.delete", mcpServerId: "builtin-exa" }),
+ );
+
+ const absent = createAkeruPluginRuntime({
+ readSnapshot: async () => snapshot(),
+ dispatch,
+ });
+ await expect(absent.uninstall("exa")).rejects.toThrow("is not installed");
+ });
+
+ it("exposes plugin tools without creating a second MCP setup path", () => {
+ const runtime = createAkeruPluginRuntime({
+ readSnapshot: async () => snapshot(),
+ dispatch: async () => undefined,
+ });
+ expect(Object.keys(createAkeruCatalogToolHandlers(undefined, runtime))).toEqual([
+ "SearchPlugins",
+ "GetPlugin",
+ "InstallPlugin",
+ "UninstallPlugin",
+ ]);
+ });
});
diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.ts
index 650422e54..45589a7ab 100644
--- a/apps/server/src/provider/AkeruCatalogToolHandlers.ts
+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.ts
@@ -1,4 +1,6 @@
+// @effect-diagnostics globalDate:off globalRandom:off nodeBuiltinImport:off
import * as NodeCrypto from "node:crypto";
+import * as NodeFS from "node:fs";
import type { McpManager } from "@mastra/code-sdk/mcp/index";
import {
@@ -6,10 +8,46 @@ import {
McpServerId,
type AkeruToolId,
type AkeruToolInputSchemas,
+ type McpServer,
type OrchestrationCommand,
type OrchestrationReadModel,
} from "@t3tools/contracts";
-import * as DateTime from "effect/DateTime";
+
+import {
+ isInstallableManifest,
+ loadManifestCatalog,
+ type CatalogManifestModules,
+} from "../../../../plugins/manifestCatalog.ts";
+import type { PluginManifest } from "../../../../plugins/schema.ts";
+
+declare global {
+ interface ImportMeta {
+ glob<T>(
+ pattern: string | readonly string[],
+ options: { readonly eager: true; readonly import: string; readonly query?: string },
+ ): Record<string, T>;
+ }
+}
+
+function loadNodeCatalogModules(): CatalogManifestModules {
+ const entriesUrl = new URL("../../../../plugins/entries/", import.meta.url);
+ return Object.fromEntries(
+ NodeFS.readdirSync(entriesUrl, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => [
+ `./entries/${entry.name}/plugin.json`,
+ JSON.parse(NodeFS.readFileSync(new URL(`${entry.name}/plugin.json`, entriesUrl), "utf8")),
+ ]),
+ );
+}
+
+const catalogManifestModules =
+ typeof import.meta.glob === "function"
+ ? import.meta.glob<unknown>("../../../../plugins/entries/*/plugin.json", {
+ eager: true,
+ import: "default",
+ })
+ : loadNodeCatalogModules();
export interface AkeruCatalogToolHandlerInput {
readonly input: unknown;
@@ -18,6 +56,8 @@ export interface AkeruCatalogToolHandlerInput {
export type AkeruCatalogToolHandler = (input: AkeruCatalogToolHandlerInput) => Promise<unknown>;
+type McpRuntimeStatus = ReturnType<McpManager["getServerStatuses"]>[number];
+
export interface AkeruPluginRuntimeOptions {
readonly readSnapshot: () => Promise<OrchestrationReadModel>;
readonly dispatch: (command: OrchestrationCommand) => Promise<unknown>;
@@ -25,52 +65,233 @@ export interface AkeruPluginRuntimeOptions {
readonly id?: () => string;
}
+function pluginServerId(pluginId: string) {
+ return McpServerId.make(`builtin-${pluginId}`);
+}
+
+function pluginConnectionHealth(
+ server: McpServer | undefined,
+ statuses: readonly McpRuntimeStatus[],
+) {
+ if (!server) return { state: "not-installed" as const };
+ if (!server.enabled) return { state: "disabled" as const };
+ const status = statuses.find((candidate) => candidate.name === server.id);
+ if (!status) return { state: "not-checked" as const };
+ return status.connected
+ ? { state: "healthy" as const, toolCount: status.toolCount, toolNames: status.toolNames }
+ : { state: "failed" as const, error: status.error ?? "The MCP server did not connect." };
+}
+
+function pluginView(
+ plugin: PluginManifest,
+ snapshot: OrchestrationReadModel,
+ statuses: readonly McpRuntimeStatus[],
+) {
+ const serverId = pluginServerId(plugin.id);
+ const server = snapshot.mcpServers?.find((candidate) => candidate.id === serverId);
+ const affectedBots = server?.enabled
+ ? snapshot.bots
+ .filter(
+ (bot) =>
+ bot.archivedAt === null && !bot.disabledMcpServerIds.some((id) => id === serverId),
+ )
+ .map((bot) => ({ id: bot.id, name: bot.name }))
+ : [];
+ return {
+ id: plugin.id,
+ name: plugin.name,
+ description: plugin.description,
+ publisher: plugin.publisher,
+ capabilities: plugin.capabilities,
+ permissions: plugin.permissions,
+ approvals: plugin.approvals,
+ connection: plugin.connection,
+ authentication: plugin.authentication,
+ requiredCredentials: plugin.requiredCredentials,
+ transport: plugin.transport,
+ platforms: plugin.platforms,
+ catalogStatus: plugin.catalogStatus,
+ installed: {
+ serverId,
+ enabled: server?.enabled ?? false,
+ health: pluginConnectionHealth(server, statuses),
+ },
+ affectedBots,
+ affectedRoutines: [],
+ routinesAvailable: false,
+ };
+}
+
+function pluginMatches(plugin: PluginManifest, query: string): boolean {
+ return [
+ plugin.id,
+ plugin.name,
+ plugin.description,
+ plugin.primaryCategory,
+ plugin.publisher.name,
+ ...plugin.tags,
+ ...plugin.capabilities,
+ ]
+ .join("\n")
+ .toLocaleLowerCase()
+ .includes(query.trim().toLocaleLowerCase());
+}
+
+function sameRecipe(server: McpServer, plugin: PluginManifest): boolean {
+ if (plugin.transport.type === "url") {
+ return (
+ server.transport === "url" &&
+ server.name === plugin.name &&
+ server.url === plugin.transport.url
+ );
+ }
+ if (plugin.transport.type === "stdio") {
+ return (
+ server.transport === "stdio" &&
+ server.name === plugin.name &&
+ server.command === plugin.transport.command &&
+ JSON.stringify(server.args ?? []) === JSON.stringify(plugin.transport.args ?? [])
+ );
+ }
+ return false;
+}
+
export function createAkeruPluginRuntime(options: AkeruPluginRuntimeOptions) {
- const now = options.now ?? (() => DateTime.formatIso(DateTime.nowUnsafe()));
+ const catalog = loadManifestCatalog(catalogManifestModules);
+ const byId = new Map(catalog.map((plugin) => [plugin.id, plugin]));
+ const now = options.now ?? (() => new Date().toISOString());
const id = options.id ?? (() => NodeCrypto.randomUUID());
- return async (input: (typeof AkeruToolInputSchemas.InstallPlugin)["Type"]) => {
- const url = new URL(input.url);
- if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
- throw new Error("Plugin URL must be HTTP or HTTPS and must not contain credentials.");
+ const commandId = (operation: string) => CommandId.make(`plugin:${operation}:${id()}`);
+
+ const getPlugin = async (pluginId: string, statuses: readonly McpRuntimeStatus[] = []) => {
+ const plugin = byId.get(pluginId);
+ if (!plugin) throw new Error(`Plugin '${pluginId}' was not found in the curated directory.`);
+ return pluginView(plugin, await options.readSnapshot(), statuses);
+ };
+
+ const search = async (
+ input: (typeof AkeruToolInputSchemas.SearchPlugins)["Type"],
+ statuses: readonly McpRuntimeStatus[] = [],
+ ) => {
+ const query = input.query ?? "";
+ const matches = catalog.filter((plugin) => pluginMatches(plugin, query));
+ const limit = input.limit ?? 20;
+ const snapshot = await options.readSnapshot();
+ return {
+ query,
+ total: matches.length,
+ plugins: matches.slice(0, limit).map((plugin) => pluginView(plugin, snapshot, statuses)),
+ };
+ };
+
+ const install = async (pluginId: string) => {
+ const plugin = byId.get(pluginId);
+ if (!plugin) throw new Error(`Plugin '${pluginId}' was not found in the curated directory.`);
+ if (!isInstallableManifest(plugin)) {
+ const blocker =
+ plugin.connection.type === "approval-pending" ||
+ plugin.connection.type === "verification-pending"
+ ? ` ${plugin.connection.blocker}`
+ : "";
+ throw new Error(`Plugin '${pluginId}' is not available for installation.${blocker}`);
}
- const mcpServerId = McpServerId.make(`builtin-${input.pluginId}`);
- const existing = ((await options.readSnapshot()).mcpServers ?? []).find(
- (server) => server.id === mcpServerId,
- );
- await options.dispatch(
- existing
- ? {
- type: "mcp-server.update",
- commandId: CommandId.make(`plugin:update:${id()}`),
- mcpServerId,
- name: input.name,
- transport: "url",
- url: input.url,
- }
- : {
- type: "mcp-server.create",
- commandId: CommandId.make(`plugin:create:${id()}`),
- mcpServerId,
- name: input.name,
- transport: "url",
- url: input.url,
- enabled: true,
- createdAt: now(),
- },
- );
- if (existing && !existing.enabled) {
- await options.dispatch({
- type: "mcp-server.enable",
- commandId: CommandId.make(`plugin:enable:${id()}`),
- mcpServerId,
- });
+ if (plugin.authentication === "api-key") {
+ throw new Error(
+ `Plugin '${pluginId}' needs the shared credential question contract before installation.`,
+ );
}
+
+ const snapshot = await options.readSnapshot();
+ const mcpServerId = pluginServerId(plugin.id);
+ const existing = snapshot.mcpServers?.find((server) => server.id === mcpServerId);
+ if (!existing) {
+ await options.dispatch(
+ plugin.transport.type === "url"
+ ? {
+ type: "mcp-server.create",
+ commandId: commandId("create"),
+ mcpServerId,
+ name: plugin.name,
+ transport: "url",
+ url: plugin.transport.url,
+ enabled: true,
+ createdAt: now(),
+ }
+ : {
+ type: "mcp-server.create",
+ commandId: commandId("create"),
+ mcpServerId,
+ name: plugin.name,
+ transport: "stdio",
+ command: plugin.transport.command,
+ ...(plugin.transport.args ? { args: plugin.transport.args } : {}),
+ enabled: true,
+ createdAt: now(),
+ },
+ );
+ } else {
+ if (!sameRecipe(existing, plugin)) {
+ await options.dispatch(
+ plugin.transport.type === "url"
+ ? {
+ type: "mcp-server.update",
+ commandId: commandId("update"),
+ mcpServerId,
+ name: plugin.name,
+ transport: "url",
+ url: plugin.transport.url,
+ }
+ : {
+ type: "mcp-server.update",
+ commandId: commandId("update"),
+ mcpServerId,
+ name: plugin.name,
+ transport: "stdio",
+ command: plugin.transport.command,
+ ...(plugin.transport.args ? { args: plugin.transport.args } : {}),
+ },
+ );
+ }
+ if (!existing.enabled) {
+ await options.dispatch({
+ type: "mcp-server.enable",
+ commandId: commandId("enable"),
+ mcpServerId,
+ });
+ }
+ }
+
return {
+ pluginId: plugin.id,
mcpServerId,
enabled: true,
- authenticationRequired: input.authentication !== "none",
+ changed: !existing || !sameRecipe(existing, plugin) || !existing.enabled,
+ authenticationRequired: plugin.authentication !== "none",
+ nextTool:
+ plugin.authentication === "oauth" || plugin.authentication === "optional-oauth"
+ ? { id: "AuthenticateMcpServer" as const, input: { serverId: mcpServerId } }
+ : null,
+ health: { state: "not-checked" as const },
};
};
+
+ const uninstall = async (pluginId: string, statuses: readonly McpRuntimeStatus[] = []) => {
+ const plugin = byId.get(pluginId);
+ if (!plugin) throw new Error(`Plugin '${pluginId}' was not found in the curated directory.`);
+ const snapshot = await options.readSnapshot();
+ const mcpServerId = pluginServerId(plugin.id);
+ const existing = snapshot.mcpServers?.find((server) => server.id === mcpServerId);
+ if (!existing) throw new Error(`Plugin '${pluginId}' is not installed.`);
+ const before = pluginView(plugin, snapshot, statuses);
+ await options.dispatch({
+ type: "mcp-server.delete",
+ commandId: commandId("delete"),
+ mcpServerId,
+ });
+ return { pluginId: plugin.id, mcpServerId, removed: true, before };
+ };
+
+ return { search, getPlugin, install, uninstall };
}
function field(value: unknown, key: string): unknown {
@@ -88,15 +309,28 @@ function requiredString(value: unknown, key: string): string {
export function createAkeruCatalogToolHandlers(
mcpManager?: McpManager,
- installPlugin?: ReturnType<typeof createAkeruPluginRuntime>,
+ pluginRuntime?: ReturnType<typeof createAkeruPluginRuntime>,
): Partial<Record<AkeruToolId, AkeruCatalogToolHandler>> {
+ const statuses = () => mcpManager?.getServerStatuses() ?? [];
return {
- ...(installPlugin
+ ...(pluginRuntime
? {
- InstallPlugin: async ({ input, emitProgress }: AkeruCatalogToolHandlerInput) => {
- const name = requiredString(input, "name");
- await emitProgress(`Installing plugin '${name}'.`);
- return installPlugin(input as (typeof AkeruToolInputSchemas.InstallPlugin)["Type"]);
+ SearchPlugins: async ({ input }) =>
+ pluginRuntime.search(
+ input as (typeof AkeruToolInputSchemas.SearchPlugins)["Type"],
+ statuses(),
+ ),
+ GetPlugin: async ({ input }) =>
+ pluginRuntime.getPlugin(requiredString(input, "pluginId"), statuses()),
+ InstallPlugin: async ({ input, emitProgress }) => {
+ const pluginId = requiredString(input, "pluginId");
+ await emitProgress(`Installing plugin '${pluginId}'.`);
+ return pluginRuntime.install(pluginId);
+ },
+ UninstallPlugin: async ({ input, emitProgress }) => {
+ const pluginId = requiredString(input, "pluginId");
+ await emitProgress(`Removing plugin '${pluginId}'.`);
+ return pluginRuntime.uninstall(pluginId, statuses());
},
}
: {}),
diff --git a/apps/server/src/provider/AkeruToolRuntime.test.ts b/apps/server/src/provider/AkeruToolRuntime.test.ts
index 491307391..148762e53 100644
--- a/apps/server/src/provider/AkeruToolRuntime.test.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.test.ts
@@ -366,6 +366,46 @@ describe("AkeruToolRuntime", () => {
).rejects.toThrow();
});
+ it("keeps plugin inspection read-only and requires one-shot grants for install and removal", async () => {
+ const search = vi.fn(async () => ({ plugins: [] }));
+ const install = vi.fn(async () => ({ installed: true }));
+ const uninstall = vi.fn(async () => ({ removed: true }));
+ const runtime = createAkeruToolRuntime();
+ runtime.registerSession("thread-plugins", {
+ runtimeMode: "full-access",
+ workspaceType: "none",
+ catalogHandlers: {
+ SearchPlugins: search,
+ InstallPlugin: install,
+ UninstallPlugin: uninstall,
+ },
+ });
+
+ await expect(
+ runtime.execute({
+ threadId: "thread-plugins",
+ toolId: "SearchPlugins",
+ toolCallId: "tool-search",
+ input: { query: "web" },
+ approvalMode: "require-grant",
+ }),
+ ).resolves.toEqual({ plugins: [] });
+
+ for (const toolId of ["InstallPlugin", "UninstallPlugin"] as const) {
+ const execution = {
+ threadId: "thread-plugins",
+ toolId,
+ toolCallId: `tool-${toolId}`,
+ input: { pluginId: "exa" },
+ approvalMode: "require-grant" as const,
+ };
+ await expect(runtime.execute(execution)).rejects.toThrow("requires approval");
+ runtime.grantApproval(execution);
+ await expect(runtime.execute(execution)).resolves.toBeDefined();
+ await expect(runtime.execute(execution)).rejects.toThrow("requires approval");
+ }
+ });
+
it("copies files only when both boundaries are registered", async () => {
const runtime = createAkeruToolRuntime();
const bot = workspace("copy-bot");
diff --git a/apps/server/src/provider/AkeruToolRuntime.ts b/apps/server/src/provider/AkeruToolRuntime.ts
index 0fc3cb065..ca1a64724 100644
--- a/apps/server/src/provider/AkeruToolRuntime.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.ts
@@ -130,7 +130,10 @@ const BACKEND_NAMES: Record<
| "UpdateChannel"
| "SendToUser"
| "UpdateBotProfile"
+ | "SearchPlugins"
+ | "GetPlugin"
| "InstallPlugin"
+ | "UninstallPlugin"
| "AuthenticateMcpServer"
| "RestartMcpServers"
>,
diff --git a/packages/contracts/src/akeruTools.test.ts b/packages/contracts/src/akeruTools.test.ts
index 9281d31de..7be4965a0 100644
--- a/packages/contracts/src/akeruTools.test.ts
+++ b/packages/contracts/src/akeruTools.test.ts
@@ -43,6 +43,24 @@ describe("Akeru tool contracts", () => {
expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "InstallPlugin")?.approval).toBe(
"production",
);
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "UninstallPlugin")?.approval).toBe(
+ "delete",
+ );
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "SearchPlugins")?.approval).toBe("none");
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "GetPlugin")?.approval).toBe("none");
+ });
+
+ it("accepts catalog-owned plugin inputs and rejects model-supplied recipes", () => {
+ expect(decodeAkeruToolInput("InstallPlugin", { pluginId: "exa" })).toEqual({
+ pluginId: "exa",
+ });
+ expect(() =>
+ decodeAkeruToolInput("InstallPlugin", {
+ pluginId: "exa",
+ url: "https://attacker.example/mcp",
+ }),
+ ).toThrow();
+ expect(() => decodeAkeruToolInput("SearchPlugins", { query: "web", limit: 51 })).toThrow();
});
it("hides SendToAgent at delegation limits", () => {
diff --git a/packages/contracts/src/akeruTools.ts b/packages/contracts/src/akeruTools.ts
index 7e443e8b1..422ca4196 100644
--- a/packages/contracts/src/akeruTools.ts
+++ b/packages/contracts/src/akeruTools.ts
@@ -7,12 +7,13 @@ import {
GroupId,
IsoDateTime,
NonNegativeInt,
+ PositiveInt,
ThreadId,
TrimmedNonEmptyString,
} from "./baseSchemas.ts";
import { AkeruMemoryTargetScope } from "./akeruMemory.ts";
import { AKERU_DELEGATION_MAX_CONCURRENCY, AKERU_DELEGATION_MAX_DEPTH } from "./akeruDelegation.ts";
-import { McpServerId, McpServerUrl } from "./mcpServer.ts";
+import { McpServerId } from "./mcpServer.ts";
import { BotSandbox, RuntimeMode } from "./orchestration.ts";
export const AKERU_COMMAND_MAX_CHARS = 32_000;
@@ -66,7 +67,10 @@ export const AkeruToolId = Schema.Literals([
"CreateChannel",
"UpdateChannel",
"SendToUser",
+ "SearchPlugins",
+ "GetPlugin",
"InstallPlugin",
+ "UninstallPlugin",
"UpdateBotProfile",
"AuthenticateMcpServer",
"RestartMcpServers",
@@ -123,12 +127,13 @@ export const AkeruToolInputSchemas = {
SendToUser: Schema.Struct({
message: TrimmedNonEmptyString.check(Schema.isMaxLength(AKERU_COMMAND_MAX_CHARS)),
}),
- InstallPlugin: Schema.Struct({
- pluginId: TrimmedNonEmptyString,
- name: TrimmedNonEmptyString,
- url: McpServerUrl,
- authentication: Schema.Literals(["none", "oauth", "optional-oauth"]),
+ SearchPlugins: Schema.Struct({
+ query: Schema.optional(TrimmedNonEmptyString),
+ limit: Schema.optional(PositiveInt.check(Schema.isLessThanOrEqualTo(50))),
}),
+ GetPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
+ InstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
+ UninstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
UpdateBotProfile: UpdateBotProfileInput,
AuthenticateMcpServer: McpServerIdInput,
RestartMcpServers: Schema.Struct({
@@ -259,9 +264,18 @@ export const AKERU_TOOL_CATALOG = [
define("SendToUser", "bot-workspace", "Send a message into the current Akeru thread.", {
approval: "send",
}),
- define("InstallPlugin", "bot-workspace", "Install or update a URL MCP plugin.", {
+ define("SearchPlugins", "bot-workspace", "Search the curated plugin directory."),
+ define(
+ "GetPlugin",
+ "bot-workspace",
+ "Inspect a plugin, its connection, permissions, health, and dependents.",
+ ),
+ define("InstallPlugin", "bot-workspace", "Install a curated plugin after inspecting it.", {
approval: "production",
}),
+ define("UninstallPlugin", "bot-workspace", "Remove a curated plugin after inspecting it.", {
+ approval: "delete",
+ }),
define("UpdateBotProfile", "bot-workspace", "Update this bot's public profile."),
define("AuthenticateMcpServer", "bot-workspace", "Authenticate an MCP server.", {
approval: "secrets",
diff --git a/plugins/catalog.ts b/plugins/catalog.ts
index caca0c478..46ec9e251 100644
--- a/plugins/catalog.ts
+++ b/plugins/catalog.ts
@@ -1,5 +1,10 @@
-import type { PluginCategory } from "./categories";
-import { parsePluginManifest, type PluginManifest, type PluginSkill } from "./schema";
+import type { PluginCategory } from "./categories.ts";
+import {
+ isInstallableManifest,
+ loadManifestCatalog,
+ type CatalogManifestModules,
+} from "./manifestCatalog.ts";
+import type { PluginManifest, PluginSkill } from "./schema.ts";
export interface PluginLogo {
readonly src: string;
@@ -58,7 +63,6 @@ export type PluginDirectoryDefinition =
export type PluginDefinition = CatalogPluginDefinition;
export type { PluginSkill };
-type CatalogModules = Readonly<Record<string, unknown>>;
type AssetModules = Readonly<Record<string, string>>;
const catalogModules = import.meta.glob<unknown>("./entries/*/plugin.json", {
@@ -74,12 +78,6 @@ const catalogAssets = import.meta.glob<string>(
},
);
-function pluginDirectory(manifestPath: string): string {
- const match = /^\.\/entries\/([^/]+)\/plugin\.json$/.exec(manifestPath);
- if (!match?.[1]) throw new TypeError(`Invalid plugin manifest path '${manifestPath}'.`);
- return match[1];
-}
-
function assetUrl(
assets: AssetModules,
directory: string,
@@ -94,16 +92,12 @@ function assetUrl(
function toPluginDefinition(
manifest: PluginManifest,
- directory: string,
assets: AssetModules,
): PluginDirectoryDefinition {
- if (manifest.id !== directory) {
- throw new TypeError(`Plugin '${manifest.id}' must live in entries/${manifest.id}/.`);
- }
const logo = {
...manifest.logo,
- src: assetUrl(assets, directory, "logo.svg", manifest.id),
- darkSrc: assetUrl(assets, directory, "logo-dark.svg", manifest.id),
+ src: assetUrl(assets, manifest.id, "logo.svg", manifest.id),
+ darkSrc: assetUrl(assets, manifest.id, "logo-dark.svg", manifest.id),
};
const base = {
...manifest,
@@ -138,42 +132,21 @@ function toPluginDefinition(
});
}
-function comparePluginOrder(
- left: PluginDirectoryDefinition,
- right: PluginDirectoryDefinition,
-): number {
- return (
- (left.featuredRank ?? Number.POSITIVE_INFINITY) -
- (right.featuredRank ?? Number.POSITIVE_INFINITY) || left.id.localeCompare(right.id)
- );
-}
-
export function loadDirectoryCatalog(
- modules: CatalogModules = catalogModules,
+ modules: CatalogManifestModules = catalogModules,
assets: AssetModules = catalogAssets,
): readonly PluginDirectoryDefinition[] {
- const ids = new Set<string>();
- const plugins = Object.entries(modules).map(([path, input]) => {
- const directory = pluginDirectory(path);
- const manifest = parsePluginManifest(input, path);
- if (ids.has(manifest.id)) throw new TypeError(`Duplicate plugin id '${manifest.id}'.`);
- ids.add(manifest.id);
- return toPluginDefinition(manifest, directory, assets);
- });
- return Object.freeze(plugins.toSorted(comparePluginOrder));
+ return Object.freeze(
+ loadManifestCatalog(modules).map((manifest) => toPluginDefinition(manifest, assets)),
+ );
}
export function isInstallablePlugin(plugin: PluginDirectoryDefinition): plugin is PluginDefinition {
- return (
- plugin.catalogStatus === "available" &&
- plugin.kind !== "mcp-unavailable" &&
- plugin.connection.type !== "approval-pending" &&
- plugin.connection.type !== "verification-pending"
- );
+ return isInstallableManifest(plugin) && plugin.kind !== "mcp-unavailable";
}
export function loadCatalog(
- modules: CatalogModules = catalogModules,
+ modules: CatalogManifestModules = catalogModules,
assets: AssetModules = catalogAssets,
): readonly CatalogPluginDefinition[] {
return loadDirectoryCatalog(modules, assets).filter(isInstallablePlugin);
diff --git a/plugins/index.ts b/plugins/index.ts
index 75ef3de2b..ed992c284 100644
--- a/plugins/index.ts
+++ b/plugins/index.ts
@@ -10,6 +10,11 @@ export {
type PluginLogo,
type PluginSkill,
} from "./catalog";
+export {
+ isInstallableManifest,
+ loadManifestCatalog,
+ type CatalogManifestModules,
+} from "./manifestCatalog";
export {
PLUGIN_APPROVAL_CLASSES,
PLUGIN_CATEGORIES,
diff --git a/plugins/manifestCatalog.ts b/plugins/manifestCatalog.ts
new file mode 100644
index 000000000..725132453
--- /dev/null
+++ b/plugins/manifestCatalog.ts
@@ -0,0 +1,54 @@
+import { parsePluginManifest, type PluginManifest } from "./schema.ts";
+
+export type CatalogManifestModules = Readonly<Record<string, unknown>>;
+type PluginManifestInstallability = Pick<
+ PluginManifest,
+ "catalogStatus" | "transport" | "connection"
+>;
+type InstallableManifestFields = {
+ readonly catalogStatus: "available";
+ readonly transport: Exclude<PluginManifest["transport"], { readonly type: "unavailable" }>;
+ readonly connection: Exclude<
+ PluginManifest["connection"],
+ { readonly type: "approval-pending" | "verification-pending" }
+ >;
+};
+
+function pluginDirectory(manifestPath: string): string {
+ const match = /(?:^|\/)entries\/([^/]+)\/plugin\.json$/.exec(manifestPath);
+ if (!match?.[1]) throw new TypeError(`Invalid plugin manifest path '${manifestPath}'.`);
+ return match[1];
+}
+
+function comparePluginOrder(left: PluginManifest, right: PluginManifest): number {
+ return (
+ (left.featuredRank ?? Number.POSITIVE_INFINITY) -
+ (right.featuredRank ?? Number.POSITIVE_INFINITY) || left.id.localeCompare(right.id)
+ );
+}
+
+export function loadManifestCatalog(modules: CatalogManifestModules): readonly PluginManifest[] {
+ const ids = new Set<string>();
+ const plugins = Object.entries(modules).map(([path, input]) => {
+ const directory = pluginDirectory(path);
+ const manifest = parsePluginManifest(input, path);
+ if (ids.has(manifest.id)) throw new TypeError(`Duplicate plugin id '${manifest.id}'.`);
+ if (manifest.id !== directory) {
+ throw new TypeError(`Plugin '${manifest.id}' must live in entries/${manifest.id}/.`);
+ }
+ ids.add(manifest.id);
+ return manifest;
+ });
+ return Object.freeze(plugins.toSorted(comparePluginOrder));
+}
+
+export function isInstallableManifest<T extends PluginManifestInstallability>(
+ plugin: T,
+): plugin is T & InstallableManifestFields {
+ return (
+ plugin.catalogStatus === "available" &&
+ plugin.transport.type !== "unavailable" &&
+ plugin.connection.type !== "approval-pending" &&
+ plugin.connection.type !== "verification-pending"
+ );
+}