@stage-labs/metro 0.1.0-beta.305 → 0.1.0-beta.306

package/runtime/node_modules/@metro-labs/http/src/mcp-server-tools.ts

@@ -0,0 +1,93 @@
+import { MCP_CALLS_MAX, MCP_FIND_DEFAULT, MCP_FIND_MAX, TOOL_CALL, TOOL_CALL_EXAMPLE, TOOL_SEARCH } from './mcp-server-protocol.js';
+
+export interface McpServerTool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: Record<string, unknown>;
+}
+
+const searchSchema = {
+  type: 'object',
+  properties: {
+    query: {
+      type: 'string',
+      description: 'What to look for: "select:<connector>.<tool>" (comma separated) loads exact tools, keywords rank tools, "+word" requires that word in the tool name.',
+    },
+    max_results: { type: 'number', description: `Maximum number of results to return (default: ${String(MCP_FIND_DEFAULT)}, at most ${String(MCP_FIND_MAX)})`, default: MCP_FIND_DEFAULT },
+  },
+  required: ['query'],
+  additionalProperties: false,
+};
+
+const callSchema = {
+  type: 'object',
+  properties: {
+    calls: {
+      type: 'array',
+      minItems: 1,
+      maxItems: MCP_CALLS_MAX,
+      description: `1 to ${String(MCP_CALLS_MAX)} independent calls. They run in parallel and are answered in order.`,
+      items: {
+        type: 'object',
+        properties: {
+          tool: { type: 'string', description: 'The tool name exactly as tool_search returned it: <connector>.<tool>.' },
+          arguments: { type: 'object', description: 'The tool\'s arguments, matching the parameters tool_search returned.', additionalProperties: true },
+          approval: { type: 'string', pattern: '^[a-km-z]{5}$', description: 'The 5-letter approval id, only when repeating a call the owner approved.' },
+        },
+        required: ['tool'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['calls'],
+  additionalProperties: false,
+};
+
+function connectorsLine(keys: string[] | null): string {
+  if (keys === null) return 'The connectors of this agent are named here once Metro reaches mcp.metro.box.';
+  return keys.length === 0 ? 'This agent has no connectors it may use yet.' : `This agent's connectors: ${keys.join(', ')}.`;
+}
+
+export const toolSearchDescription = (keys: string[] | null): string =>
+  [
+    'Search the tools of every connector assigned to this agent: third-party services such as Notion, n8n, Linear or Gmail, run by mcp.metro.box. Same design as Claude Code\'s ToolSearch, for connectors.',
+    connectorsLine(keys),
+    'Three query forms, one example each:',
+    '- "select:notion.search" loads exact tools by name (comma separated for several).',
+    '- "notion create page" ranks tools by the words in their name and description.',
+    '- "+linear issue" requires "linear" in the tool name and ranks by the other words.',
+    'Results are full definitions (name, description and the JSON schema of the arguments) in a <functions> block. Each name is <connector>.<tool>: pass it exactly as "tool" to tool_call. Tools the owner blocked are never returned.',
+  ].join('\n');
+
+export const TOOL_CALL_DESCRIPTION = [
+  'Run connector tools that tool_search found. Always find a tool with tool_search first: its exact name and argument schema come from there.',
+  `Shape: ${TOOL_CALL_EXAMPLE}`,
+  `Up to ${String(MCP_CALLS_MAX)} independent calls run in parallel in one tool_call and are answered in order. Each result starts with "[n] <connector>.<tool>", then the tool's own content, or one line saying why it did not run:`,
+  '- not_found: no such connector or tool here. Run tool_search, then use a name it returned.',
+  '- needs_approval: the owner was asked in chat and on metro.box. Tell the person what is waiting, wait for the channel message "Approved: <tool> (<id>)", then call again with the same tool and arguments plus "approval": "<id>". An approval works once.',
+  '- denied or blocked: the owner refused or blocked this call. Do not retry it.',
+  '- signin: the connector must be signed in again. Tell the owner to do it on the organization\'s Connectors page on metro.box.',
+  '- unavailable: the connector or Metro could not be reached. Try again later.',
+  '- vendor_error: the connector answered with its own error, shown as it came.',
+].join('\n');
+
+export function mcpServerTools(keys: string[] | null): McpServerTool[] {
+  return [
+    {
+      name: TOOL_SEARCH,
+      title: 'Search connector tools',
+      description: toolSearchDescription(keys),
+      inputSchema: searchSchema,
+      annotations: { title: 'Search connector tools', readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: TOOL_CALL,
+      title: 'Call connector tools',
+      description: TOOL_CALL_DESCRIPTION,
+      inputSchema: callSchema,
+      annotations: { title: 'Call connector tools', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+  ];
+}

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.305"
+  "version": "0.1.0-beta.306"
 }

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.305",
+  "version": "0.1.0-beta.306",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/{runtime/marketplace/plugin → skills}/METRO.md

@@ -1,9 +1,9 @@
 ---
 name: metro
-description: How this box's agent works on metro. Acknowledge, delegate, relay, answer over chat, never block on the terminal. Loaded at every session start by the metro plugin; edit it here to change the rules on this box.
+description: How this box's agent works on metro. Acknowledge, delegate, relay, answer over chat, never block on the terminal. Loaded at every session start by a metro hook; edit it here to change the rules on this box.
 ---
 
-You are the main thread of a Claude Code session that is connected to chat through metro, on a machine nobody watches. The main thread is an orchestrator: it may only delegate and talk. A guard in the metro plugin denies every other tool on this thread, so this is the shape of the work, not a preference.
+You are the main thread of a Claude Code session that is connected to chat through metro, on a machine nobody watches. The main thread is an orchestrator: it may only delegate and talk. A guard metro installs denies every other tool on this thread, so this is the shape of the work, not a preference.
 
 **Inbound.** A message arrives as a `<channel source="metro" …>` block. Read `addressed` first: `direct`, `mention` or `reply` means it is for you; without it the message merely happened in a room you watch, so treat it as context and stay silent unless the person plainly wants you. For a message that is for you, the first tool call is `react` on it (👀, then 👍 or ✅ once done) so the person knows you saw it, and any reply goes on the same `line`, passed verbatim. Exception: when the person asks you to close something ("mark as done"), skip the reaction and the acknowledgement: close it directly and confirm once when it is finished.
 
@@ -15,7 +15,12 @@ You are the main thread of a Claude Code session that is connected to chat throu
 
 **Calls that need the owner's approval run in a worker.** The owner can make a metro tool on a channel wait for approval. On the main thread such a call is refused, because waiting for the answer would stop the whole session: hand that exact call to a background worker (`run_in_background: true`) and keep answering. The worker waits for the owner's answer on its own.
 
-**Connectors through the `mcp` server.** Every connector the organization gave this agent sits behind the `mcp` server's two tools. Find what you need with `find_tools`: `select:notion.search,linear.create_issue` for exact names, keywords (`notion page update`) to rank, or `+slack send` to require `slack` in the tool name. Have a worker run them with `call_tool`, up to 10 independent calls in one go. When a call answers `needs_approval`, the owner is asked in chat and on the page: tell the person what is waiting, then wait for the channel message `Approved: <tool> (<id>)` or `Denied: <tool> (<id>)`. After an approval, have a worker call `call_tool` again with the same tool and arguments and `approval: "<id>"`.
+**Connectors.** Third-party tools the organization gave this agent (Notion, n8n, Linear, Gmail and the like) are reached only through two metro tools, in two steps:
+
+1. `tool_search` finds a tool and returns its full definition: `select:notion.search` for an exact name, words (`notion create page`) to rank, or `+linear issue` to require `linear` in the name. Each name is `<connector>.<tool>`.
+2. `tool_call` runs it, with the name exactly as found and arguments that match its schema. After `tool_search` with `select:notion.search` returned `notion.search`: `{"calls": [{"tool": "notion.search", "arguments": {"query": "roadmap"}}]}`.
+
+Put up to 10 independent calls in one `tool_call`; they run in parallel and come back in order, each under `[n] <tool>`. `tool_search` may run on this thread, but never call `tool_call` here: delegate it to a worker, as all other work. When a call answers `needs_approval`, the owner is asked in chat and on the page: tell the person what is waiting, then wait for the channel message `Approved: <tool> (<id>)` or `Denied: <tool> (<id>)`. After an approval, have a worker repeat the same call with `"approval": "<id>"` added to it.
 
 **Finish what was asked.** You work on your own. Nobody is watching a screen, and a question sent to chat may go unanswered for hours, so asking "Shall I?" about work already requested simply stops it. Anything reversible that follows from the request, do. Stop only for a destructive action or a genuine change of scope. Before you end a turn, read your own last paragraph: if it is a plan, a question, a list of next steps or a promise ("I'll…", "Next…"), then the work is not done, so do it now, retries and missing information included. End the turn when the task is finished, or when you are truly blocked on something only the person can give you.
 

package/runtime/marketplace/.claude-plugin/marketplace.json

@@ -1,12 +0,0 @@
-{
-  "name": "metro",
-  "description": "Metro — connector relay and chat bridge for agents",
-  "owner": { "name": "Bonustrack", "url": "https://metro.box" },
-  "plugins": [
-    {
-      "name": "metro",
-      "source": "./plugin",
-      "description": "Every connector on this box as its own MCP server through metro's local relay, the orchestrator guard, and the standing rules loaded at session start."
-    }
-  ]
-}

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,16 +0,0 @@
-{
-  "name": "metro",
-  "version": "0.1.0-beta.305",
-  "description": "Metro for Claude Code, installed by the metro daemon on this machine: one `mcp` server on mcp.metro.box for the organization connectors (find_tools, call_tool), the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever reaches this machine.",
-  "author": {
-    "name": "Bonustrack",
-    "url": "https://metro.box"
-  },
-  "repository": "https://github.com/bonustrack/metro",
-  "license": "MIT",
-  "keywords": [
-    "metro",
-    "mcp",
-    "connectors"
-  ]
-}

package/runtime/marketplace/plugin/.mcp.json

@@ -1 +0,0 @@
-{}

package/runtime/marketplace/plugin/bin/metro-plugin.mjs

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-const agentsDir = () => process.env.METRO_AGENTS_DIR || join(homedir(), '.metro', 'agents');
-const MCP_TOKEN = /^mcp_[A-Za-z0-9_-]{43}$/;
-
-function readMcpToken() {
-  try {
-    const token = readFileSync(join(agentsDir(), 'mcp-token'), 'utf8').trim();
-    return MCP_TOKEN.test(token) ? token : null;
-  } catch {
-    return null;
-  }
-}
-
-if (process.argv[2] !== 'mcp-headers') {
-  process.stderr.write('usage: metro-plugin.mjs mcp-headers\n');
-  process.exit(1);
-}
-
-const token = readMcpToken();
-if (token !== null) process.stdout.write(`${JSON.stringify({ Authorization: `Bearer ${token}` })}\n`);

package/runtime/marketplace/plugin/hooks/hooks.json

@@ -1,25 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/guard.mjs\"",
-            "statusMessage": "Checking the orchestrator boundary"
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/session-start.mjs\""
-          }
-        ]
-      }
-    ]
-  }
-}

package/runtime/node_modules/@metro-labs/daemon/src/claude/plugin-install.ts

@@ -1,149 +0,0 @@
-import { execFile } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { isRecord } from '@metro-labs/core/is-record';
-import { log } from '@metro-labs/core/log';
-import { agentMarketplaceDir, agentUser, asAgent, claudeBin } from '../agent-user/user.js';
-
-const MARKETPLACE = 'metro';
-const PLUGIN = 'metro@metro';
-const STEP_MS = 120_000;
-const SAID_MAX = 300;
-
-export interface Answer {
-  status: number;
-  stdout: string;
-  stderr: string;
-}
-
-export type Run = (args: string[]) => Promise<Answer>;
-
-export interface PluginInstallDeps {
-  run: Run | null;
-  marketplaceDir: string | null;
-}
-
-export type PluginOutcome = 'skipped' | 'unchanged' | 'installed' | 'updated' | 'failed';
-
-function storeMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
-  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
-  if (store === '') return null;
-  const dir = join(store, 'marketplace');
-  return existsSync(join(dir, '.claude-plugin', 'marketplace.json')) ? dir : null;
-}
-
-export function stagedMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
-  const store = storeMarketplaceDir(env);
-  const user = agentUser();
-  if (store === null || user === null) return store;
-  const copy = agentMarketplaceDir(user);
-  return existsSync(join(copy, '.claude-plugin', 'marketplace.json')) ? copy : null;
-}
-
-export function stagedPluginVersion(dir: string): string | null {
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(join(dir, 'plugin', '.claude-plugin', 'plugin.json'), 'utf8'));
-    return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : null;
-  } catch {
-    return null;
-  }
-}
-
-const runner =
-  (bin: string): Run =>
-  (args) =>
-    new Promise((resolve) => {
-      execFile(...asAgent(bin, args), { encoding: 'utf8', timeout: STEP_MS, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
-        const status = err === null ? 0 : typeof (err as { code?: unknown }).code === 'number' ? (err as { code: number }).code : 1;
-        resolve({ status, stdout, stderr });
-      });
-    });
-
-async function findClaude(candidates = agentUser() === null ? ['claude', join(homedir(), '.local', 'bin', 'claude')] : [claudeBin()]): Promise<Run | null> {
-  for (const bin of candidates) {
-    const run = runner(bin);
-    if ((await run(['--version'])).status === 0) return run;
-  }
-  return null;
-}
-
-function listOf(stdout: string): Record<string, unknown>[] {
-  try {
-    const parsed: unknown = JSON.parse(stdout);
-    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
-  } catch {
-    return [];
-  }
-}
-
-const realish = (path: string): string => {
-  try {
-    return realpathSync(path);
-  } catch {
-    return path;
-  }
-};
-
-const samePath = (a: string | null, b: string): boolean => a !== null && realish(a) === realish(b);
-
-async function step(run: Run, args: string[]): Promise<boolean> {
-  const answer = await run(args);
-  if (answer.status === 0) {
-    log.info({ args }, 'plugin: claude');
-    return true;
-  }
-  log.warn({ args, said: `${answer.stderr}${answer.stdout}`.trim().slice(0, SAID_MAX) }, 'plugin: claude refused');
-  return false;
-}
-
-async function marketplacePath(run: Run): Promise<string | null | undefined> {
-  const mine = listOf((await run(['plugin', 'marketplace', 'list', '--json'])).stdout).find((m) => m.name === MARKETPLACE);
-  if (mine === undefined) return undefined;
-  const at = mine.installLocation ?? mine.path;
-  return typeof at === 'string' ? at : null;
-}
-
-async function ensureMarketplace(run: Run, dir: string): Promise<boolean> {
-  const at = await marketplacePath(run);
-  if (at !== undefined && samePath(at, dir)) return true;
-  if (at !== undefined) await step(run, ['plugin', 'marketplace', 'remove', MARKETPLACE]);
-  return step(run, ['plugin', 'marketplace', 'add', dir]);
-}
-
-async function installedVersion(run: Run): Promise<string | null> {
-  const mine = listOf((await run(['plugin', 'list', '--json'])).stdout).find((p) => p.id === PLUGIN);
-  return mine !== undefined && typeof mine.version === 'string' ? mine.version : null;
-}
-
-async function ensureInstalled(run: Run, wanted: string | null): Promise<PluginOutcome> {
-  const have = await installedVersion(run);
-  if (have === null) return (await step(run, ['plugin', 'install', PLUGIN, '-y', '--scope', 'user'])) ? 'installed' : 'failed';
-  if (wanted === null || have === wanted) return 'unchanged';
-  await step(run, ['plugin', 'marketplace', 'update', MARKETPLACE]);
-  return (await step(run, ['plugin', 'update', PLUGIN, '-y'])) ? 'updated' : 'failed';
-}
-
-function explainMissingMarketplace(env: NodeJS.ProcessEnv = process.env): void {
-  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
-  if (store === '') return;
-  log.warn(
-    { store },
-    'plugin: the runtime store holds no plugin marketplace, so metro cannot install its Claude Code plugin; restart the metro service once so `metro serve` stages it again',
-  );
-}
-
-export async function ensureMetroPlugin(deps?: Partial<PluginInstallDeps>): Promise<PluginOutcome> {
-  const dir = deps?.marketplaceDir === undefined ? stagedMarketplaceDir() : deps.marketplaceDir;
-  if (dir === null) {
-    if (deps?.marketplaceDir === undefined) explainMissingMarketplace();
-    return 'skipped';
-  }
-  const run = deps?.run === undefined ? await findClaude() : deps.run;
-  if (run === null) {
-    log.info('plugin: claude is not on this machine, so metro leaves its Claude Code plugin alone');
-    return 'skipped';
-  }
-  if (!(await ensureMarketplace(run, dir))) return 'failed';
-  return ensureInstalled(run, stagedPluginVersion(dir));
-}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/plugin-sync.ts

@@ -1,100 +0,0 @@
-import { existsSync, readdirEntries, readFileSync } from '../agent-user/agent-fs.js';
-import { writeHomeInPlace } from '../agent-user/home-fs.js';
-import { agentMarketplaceDir, agentUser } from '../agent-user/user.js';
-import { join } from 'node:path';
-import { errMsg, log } from '@metro-labs/core/log';
-import { claudeDir } from '../claude/files.js';
-import { MCP_SERVER_KEY, mcpServerUrl } from '../mcp-server/config.js';
-
-const MARKER = join('bin', 'metro-plugin.mjs');
-const FILE = '.mcp.json';
-const MCP_HELPER = 'node "${CLAUDE_PLUGIN_ROOT}/bin/metro-plugin.mjs" mcp-headers';
-
-interface PluginServer {
-  type: 'http';
-  url: string;
-  headersHelper: string;
-}
-
-const pluginServers = (url: string | null): Record<string, PluginServer> =>
-  url === null ? {} : { [MCP_SERVER_KEY]: { type: 'http', url, headersHelper: MCP_HELPER } };
-
-const SEARCH_DEPTH = 5;
-
-function pluginRootsUnder(dir: string, depth: number, out: string[]): void {
-  if (depth < 0 || out.length >= 8) return;
-  let entries;
-  try {
-    entries = readdirEntries(dir);
-  } catch {
-    return;
-  }
-  if (entries.some((e) => e.name === 'bin' && e.isDirectory()) && existsSync(join(dir, MARKER))) {
-    out.push(dir);
-    return;
-  }
-  for (const entry of entries)
-    if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules')
-      pluginRootsUnder(join(dir, entry.name), depth - 1, out);
-}
-
-function stagedPluginDir(env: NodeJS.ProcessEnv = process.env): string | null {
-  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
-  if (store === '') return null;
-  const user = agentUser();
-  return join(user === null ? join(store, 'marketplace') : agentMarketplaceDir(user), 'plugin');
-}
-
-export function installedPluginFiles(dir = claudeDir(), staged = stagedPluginDir()): string[] {
-  const roots: string[] = [];
-  const root = join(dir, 'plugins');
-  if (existsSync(root)) pluginRootsUnder(root, SEARCH_DEPTH, roots);
-  if (staged !== null && existsSync(join(staged, MARKER)) && !roots.includes(staged)) roots.push(staged);
-  return roots.map((found) => join(found, FILE));
-}
-
-const readOrNull = (path: string): string | null => {
-  try {
-    return readFileSync(path, 'utf8');
-  } catch {
-    return null;
-  }
-};
-
-function writeIfChanged(path: string, text: string): boolean {
-  if (readOrNull(path) === text) return false;
-  writeHomeInPlace(path, text, 0o644);
-  return true;
-}
-
-export interface PluginSyncOptions {
-  dir?: string;
-  staged?: string | null;
-  url?: string | null;
-}
-
-function filesFor(opts: PluginSyncOptions): string[] {
-  const staged = opts.staged === undefined ? stagedPluginDir() : opts.staged;
-  return installedPluginFiles(opts.dir ?? claudeDir(), staged);
-}
-
-export function syncPluginServers(opts: PluginSyncOptions = {}): number {
-  const files = filesFor(opts);
-  if (files.length === 0) return 0;
-  const servers = pluginServers(opts.url === undefined ? mcpServerUrl() : opts.url);
-  const text = `${JSON.stringify(servers, null, 2)}\n`;
-  let written = 0;
-  for (const file of files) {
-    try {
-      if (writeIfChanged(file, text)) written += 1;
-    } catch (err) {
-      log.warn({ file, err: errMsg(err) }, 'plugin: could not write the MCP servers');
-    }
-  }
-  if (written > 0)
-    log.info(
-      { files: written, servers: Object.keys(servers) },
-      'plugin: MCP servers written; run /reload-plugins --force to pick them up in a running session',
-    );
-  return written;
-}