@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/agent-guide/__tests__/tool-surface.json

@@ -0,0 +1,514 @@
+{
+  "apply_file_upload": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.all",
+      "body.branch (required)",
+      "body.destination (required)",
+      "body.mode: create | overwrite | update",
+      "body.sessionId",
+      "body.token (required)"
+    ]
+  },
+  "branch_status": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.base",
+      "body.branch (required)",
+      "body.sessionId"
+    ]
+  },
+  "call_tool_chain": {
+    "servedTo": [
+      "MCP"
+    ],
+    "arguments": [
+      "code (required)",
+      "max_output_size",
+      "timeout"
+    ]
+  },
+  "commit_change": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.description",
+      "body.summary (required)"
+    ]
+  },
+  "compare_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.at",
+      "body.branch (required)",
+      "body.from",
+      "body.path (required)",
+      "body.sessionId",
+      "body.to"
+    ]
+  },
+  "copy_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.dest (required)",
+      "body.dryRun",
+      "body.sessionId",
+      "body.src (required)"
+    ]
+  },
+  "create_branch": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.name (required)"
+    ]
+  },
+  "create_plugin": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.name (required)",
+      "body.parent"
+    ]
+  },
+  "delete_branch": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.discardUnmerged",
+      "body.dryRun",
+      "body.name (required)"
+    ]
+  },
+  "delete_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "delete_folder": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.confirm",
+      "body.dryRun",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "edit_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.new_string (required)",
+      "body.old_string (required)",
+      "body.path (required)",
+      "body.replace_all",
+      "body.sessionId"
+    ]
+  },
+  "file_stat": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.explainAccess",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "get_agent_guide": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.section"
+    ]
+  },
+  "get_change_request": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.number (required)"
+    ]
+  },
+  "get_skill": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch",
+      "body.file",
+      "body.name (required)",
+      "body.version"
+    ]
+  },
+  "grep": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.ignore_case",
+      "body.max_results",
+      "body.path",
+      "body.pattern (required)",
+      "body.sessionId"
+    ]
+  },
+  "list_branches": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": []
+  },
+  "list_change_request_files": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.include: patches",
+      "body.number (required)",
+      "body.page",
+      "body.per_page"
+    ]
+  },
+  "list_change_request_reviews": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.number (required)",
+      "body.page",
+      "body.per_page"
+    ]
+  },
+  "list_change_requests": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.author",
+      "body.base",
+      "body.head",
+      "body.page",
+      "body.per_page",
+      "body.state: open | closed | all"
+    ]
+  },
+  "list_file_changes": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.limit",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "list_files": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.path",
+      "body.sessionId"
+    ]
+  },
+  "list_local_tools": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": []
+  },
+  "list_skills": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch"
+    ]
+  },
+  "list_tool_setup": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch"
+    ]
+  },
+  "list_tools": {
+    "servedTo": [
+      "MCP"
+    ],
+    "arguments": []
+  },
+  "merge_branch": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.source (required)",
+      "body.target (required)"
+    ]
+  },
+  "mkdir": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "move_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.confirm",
+      "body.dest (required)",
+      "body.dryRun",
+      "body.rewriteLinks",
+      "body.sessionId",
+      "body.src (required)"
+    ]
+  },
+  "my_plugin": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": []
+  },
+  "open_change_request": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.description",
+      "body.include: patches | all-paths",
+      "body.sourceBranch (required)",
+      "body.targetBranch (required)",
+      "body.title (required)"
+    ]
+  },
+  "open_page": {
+    "servedTo": [
+      "MCP"
+    ],
+    "arguments": [
+      "body.heading",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "read_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.limit",
+      "body.offset",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "read_file_at": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.at (required)",
+      "body.branch (required)",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "request_file_download": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.paths (required)",
+      "body.sessionId"
+    ]
+  },
+  "request_file_upload": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": []
+  },
+  "save_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.path (required)"
+    ]
+  },
+  "share_current_branch": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)"
+    ]
+  },
+  "start_session": {
+    "servedTo": [
+      "MCP"
+    ],
+    "arguments": []
+  },
+  "switch_branch": {
+    "servedTo": [
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)"
+    ]
+  },
+  "tools_info": {
+    "servedTo": [
+      "MCP"
+    ],
+    "arguments": [
+      "tool_names (required)"
+    ]
+  },
+  "unzip": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.destination",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "update_branch": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.from",
+      "body.resolutions",
+      "body.resolutions[].choose: ours | theirs | delete",
+      "body.resolutions[].content",
+      "body.resolutions[].path (required)",
+      "body.sessionId"
+    ]
+  },
+  "update_change_request": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.appendDescription",
+      "body.description",
+      "body.number (required)",
+      "body.title"
+    ]
+  },
+  "write_file": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.content (required)",
+      "body.mode: create | overwrite | update",
+      "body.path (required)",
+      "body.sessionId"
+    ]
+  },
+  "write_files": {
+    "servedTo": [
+      "MCP",
+      "in-app agent"
+    ],
+    "arguments": [
+      "body.branch (required)",
+      "body.files (required)",
+      "body.files[].content (required)",
+      "body.files[].path (required)",
+      "body.mode: create | overwrite | update",
+      "body.sessionId"
+    ]
+  }
+}

package/src/modules/agent-guide/__tests__/tool-surface.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { hexisCatalog } from '../../../__tests__/hexis-catalog.js';
+import type { UtcpTool } from '../../tool-registry/index.js';
+
+/**
+ * The platform's tools as an agent can call them: each tool's name, where it
+ * is served, and every argument it takes (nested ones by their dotted path),
+ * which are required, and the values an enum allows. Kept as a committed file,
+ * `tool-surface.json` beside this test.
+ *
+ * Why: the guide teaches these calls, and a change to them is the change most
+ * likely to leave the guide wrong without failing anything else. The guide
+ * check (`guide-matches-code.test.ts`) catches a name the guide uses that the
+ * code lost; it cannot catch an argument the code GAINED, or one that became
+ * required, that the guide should now mention. This file does: a pull request
+ * that changes the surface fails here until it updates the file, and the
+ * updated file shows the change in the diff where reviewers see it. That is
+ * the moment to update the guide, or to say in the pull request that no guide
+ * change is needed. Accept with
+ * `pnpm --filter @bevel-software/platform-core-backend exec vitest run src/modules/agent-guide -u`.
+ */
+
+const ACCEPT =
+  'The tool surface changed (a tool, an argument, a required flag or an enum value). If agents need to know, ' +
+  'update the guide in packages/core-backend/agent-guide/ in this pull request; then accept the new surface with ' +
+  '`pnpm --filter @bevel-software/platform-core-backend exec vitest run src/modules/agent-guide -u`. See AGENTS.md.';
+
+type Schema = { type?: unknown; properties?: Record<string, Schema>; required?: string[]; items?: Schema; enum?: unknown[] };
+
+/** Every argument under `schema`, by dotted path (`files[].path`), with its required flag and enum. */
+function argumentsOf(schema: Schema | undefined, prefix = '', depth = 0): string[] {
+  if (!schema?.properties || depth > 3) return [];
+  return Object.entries(schema.properties)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([name, sub]) => {
+      const path = `${prefix}${name}`;
+      const required = schema.required?.includes(name) ? ' (required)' : '';
+      const allowed = sub.enum ?? sub.items?.enum;
+      const line = `${path}${required}${allowed ? `: ${allowed.join(' | ')}` : ''}`;
+      const nested = sub.items?.properties ? argumentsOf(sub.items, `${path}[].`, depth + 1) : argumentsOf(sub, `${path}.`, depth + 1);
+      return [line, ...nested];
+    });
+}
+
+/** A platform tool's own arguments: under `body` when it takes them there, flat otherwise. */
+function ownArguments(tool: UtcpTool): string[] {
+  const inputs = (tool.inputs ?? (tool as { inputSchema?: unknown }).inputSchema) as Schema | undefined;
+  const body = inputs?.properties?.body;
+  return body ? argumentsOf(body).map((a) => `body.${a}`) : argumentsOf(inputs);
+}
+
+describe('the tool surface agents are taught', () => {
+  it('matches the surface the guide was last checked against', async () => {
+    const { internal, external, metaTools } = await hexisCatalog();
+    const surfaces = new Map<string, Set<string>>();
+    const tools = new Map<string, UtcpTool>();
+    for (const [surface, list] of [
+      ['in-app agent', internal],
+      ['MCP', external],
+      ['MCP', metaTools as unknown as UtcpTool[]],
+    ] as const) {
+      for (const tool of list) {
+        tools.set(tool.name, tool);
+        surfaces.set(tool.name, (surfaces.get(tool.name) ?? new Set()).add(surface));
+      }
+    }
+    const surface = Object.fromEntries(
+      [...tools.keys()].sort().map((name) => [
+        name,
+        { servedTo: [...surfaces.get(name)!].sort(), arguments: ownArguments(tools.get(name)!) },
+      ]),
+    );
+    await expect(`${JSON.stringify(surface, null, 2)}\n`).toMatchFileSnapshot('./tool-surface.json', ACCEPT);
+  });
+});