@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.31

package/runtime/node_modules/@metro-labs/mcp/src/daemon/agent-api.ts

@@ -0,0 +1,332 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from './log.js';
+import { publicBaseOrDefault } from './attach-serve.js';
+import {
+  apiFailure,
+  apiSession,
+  projectParam,
+  cors,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from './api-http.js';
+import {
+  accountRoute,
+  accountRouteAllows,
+  ATTACHABLE,
+  handleAccountRoute,
+  type AccountApiDeps,
+  type AccountRoute,
+} from './account-api.js';
+import {
+  parseAgentId,
+  type AgentSummary,
+  type CreatedAgent,
+  type DeletedAgent,
+  type ResetAgentKey,
+} from '../db/agent-admin.js';
+
+const PREFIX = '/api/agents';
+const SERVER_NAME = 'metro';
+
+export interface AgentApiDeps extends AccountApiDeps {
+  listAgents: (email: string, project: string) => Promise<AgentSummary[]>;
+  createAgent: (
+    email: string,
+    project: string,
+    name: string,
+  ) => Promise<CreatedAgent>;
+  deleteAgent: (
+    email: string,
+    id: string,
+  ) => Promise<DeletedAgent>;
+  resetKey: (
+    email: string,
+    id: string,
+  ) => Promise<ResetAgentKey>;
+  gatherAccounts: (allowed: Set<string>) => Promise<{
+    accounts: Record<string, unknown[]>;
+    unavailable: string[];
+  }>;
+  capabilities: () => Record<string, string[]>;
+  liveness: () => Map<string, { connected: boolean; lastSeenAt: number }>;
+  releaseRuntime: (email: string, agentId: string) => Promise<void>;
+  runtimes: (agentIds: string[]) => Promise<Map<string, string>>;
+  connectorIds: (agentIds: string[]) => Promise<Map<string, string[]>>;
+}
+
+type Routable =
+  | { kind: 'collection' }
+  | { kind: 'agent'; id: string }
+  | { kind: 'key'; id: string }
+  | { kind: 'runtime'; id: string }
+  | { kind: 'accounts'; id: string; route: AccountRoute };
+
+type Target = Routable | { kind: 'unknown' } | null;
+
+function subTarget(id: string, rest: string[]): Target {
+  if (rest.length === 0) return { kind: 'agent', id };
+  if (rest.length === 1 && rest[0] === 'key') return { kind: 'key', id };
+  if (rest.length === 1 && rest[0] === 'runtime')
+    return { kind: 'runtime', id };
+  if (rest[0] !== 'accounts') return { kind: 'unknown' };
+  const route = accountRoute(rest.slice(1));
+  return route === null ? { kind: 'unknown' } : { kind: 'accounts', id, route };
+}
+
+export function target(path: string): Target {
+  if (path === PREFIX || path === `${PREFIX}/`) return { kind: 'collection' };
+  if (!path.startsWith(`${PREFIX}/`)) return null;
+  const segments = path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+  const head = segments[0];
+  if (head === undefined) return { kind: 'collection' };
+  const id = parseAgentId(head);
+  return id === null ? { kind: 'unknown' } : subTarget(id, segments.slice(1));
+}
+
+export function mcpEndpoint(): string {
+  return `${publicBaseOrDefault()}/mcp`;
+}
+
+const LOCAL_MCP_ENDPOINT = 'http://127.0.0.1:8420/mcp';
+
+export function mcpAddCommand(key: string): string {
+  const url = `${LOCAL_MCP_ENDPOINT}?token=${key}`;
+  return `claude mcp add --transport http ${SERVER_NAME} "${url}"`;
+}
+
+interface KeyPayload {
+  key: string | null;
+  endpoint: string | null;
+  command: string | null;
+}
+
+function credentials(key: string): KeyPayload {
+  return {
+    key,
+    endpoint: `${LOCAL_MCP_ENDPOINT}?token=${key}`,
+    command: mcpAddCommand(key),
+  };
+}
+
+function keyPayload(agent: AgentSummary): KeyPayload {
+  const value = agent.owned ? agent.key : null;
+  if (value === null) return { key: null, endpoint: null, command: null };
+  return credentials(value);
+}
+
+function livenessPayload(
+  agent: AgentSummary,
+  live: Map<string, { connected: boolean; lastSeenAt: number }>,
+): Record<string, unknown> {
+  const found = agent.owned ? live.get(agent.id) : undefined;
+  if (found === undefined) return { connected: false, last_seen: null };
+  return {
+    connected: found.connected,
+    last_seen: new Date(found.lastSeenAt).toISOString(),
+  };
+}
+
+function agentPayload(
+  agent: AgentSummary,
+  live: Map<string, { connected: boolean; lastSeenAt: number }>,
+  runtimes: Map<string, string>,
+  connectors: Map<string, string[]>,
+): Record<string, unknown> {
+  return {
+    id: agent.id,
+    name: agent.name,
+    owned: agent.owned,
+    runtime: agent.owned ? (runtimes.get(agent.id) ?? null) : null,
+    connector_ids: connectors.get(agent.id) ?? [],
+    ...livenessPayload(agent, live),
+    ...keyPayload(agent),
+  };
+}
+
+function wantsAccounts(req: IncomingMessage): boolean {
+  const query = (req.url ?? '').split('?')[1] ?? '';
+  return new URLSearchParams(query).get('accounts') === '1';
+}
+
+async function handleList(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+): Promise<void> {
+  const project = projectParam(req);
+  if (project === null) {
+    sendJson(req, res, 400, { error: 'a project is required' });
+    return;
+  }
+  const list = await deps.listAgents(session.email, project);
+  const live = deps.liveness();
+  const held = await deps.runtimes(
+    list.filter((a) => a.owned).map((a) => a.id),
+  );
+  const connectors = await deps.connectorIds(list.map((a) => a.id));
+  const base = {
+    email: session.email,
+    endpoint: mcpEndpoint(),
+    agents: list.map((a) => agentPayload(a, live, held, connectors)),
+    capabilities: deps.capabilities(),
+    attachable: ATTACHABLE,
+  };
+  if (!wantsAccounts(req)) {
+    sendJson(req, res, 200, base);
+    return;
+  }
+  const { accounts, unavailable } = await deps.gatherAccounts(
+    new Set(list.map((a) => a.id)),
+  );
+  sendJson(req, res, 200, { ...base, accounts, unavailable });
+}
+
+async function handleRuntime(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  await deps.releaseRuntime(session.email, id);
+  log.info({ agent: id }, 'agent-api: runtime released');
+  sendJson(req, res, 200, { agent: id, runtime: null });
+}
+
+async function handleCreate(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const name = (body as { name?: unknown }).name;
+  const project = projectParam(req);
+  if (project === null) {
+    sendJson(req, res, 400, { error: 'a project is required' });
+    return;
+  }
+  const created = await deps.createAgent(session.email, project, name as string);
+  log.info(
+    { agent: created.name, id: created.id, owner: session.email },
+    'agent-api: created agent',
+  );
+  sendJson(req, res, 201, {
+    id: created.id,
+    name: created.name,
+    ...credentials(created.key),
+  });
+}
+
+async function handleResetKey(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const reset = await deps.resetKey(session.email, id);
+  log.info(
+    { agent: reset.name, id: reset.id, owner: session.email },
+    'agent-api: reset agent key',
+  );
+  sendJson(req, res, 200, {
+    id: reset.id,
+    name: reset.name,
+    reset: true,
+    ...credentials(reset.key),
+  });
+}
+
+async function handleDelete(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const gone = await deps.deleteAgent(session.email, id);
+  log.info(
+    { agent: gone.name, id: gone.id, owner: session.email },
+    'agent-api: deleted agent',
+  );
+  sendJson(req, res, 200, { id: gone.id, name: gone.name, deleted: true });
+}
+
+type AgentTarget = Exclude<Routable, { kind: 'accounts' }>;
+
+async function routeAgent(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  session: ApiSession,
+  tgt: AgentTarget,
+): Promise<void> {
+  try {
+    if (tgt.kind === 'key') await handleResetKey(req, res, deps, session, tgt.id);
+    else if (tgt.kind === 'runtime')
+      await handleRuntime(req, res, deps, session, tgt.id);
+    else if (tgt.kind === 'agent')
+      await handleDelete(req, res, deps, session, tgt.id);
+    else if (req.method === 'GET') await handleList(req, res, deps, session);
+    else await handleCreate(req, res, deps, session);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}
+
+const ALLOWED: Record<AgentTarget['kind'], string[]> = {
+  collection: ['GET', 'POST'],
+  agent: ['DELETE'],
+  key: ['POST'],
+  runtime: ['DELETE'],
+};
+
+function methodAllowed(tgt: Routable, method: string | undefined): boolean {
+  if (tgt.kind === 'accounts') return accountRouteAllows(tgt.route, method);
+  return ALLOWED[tgt.kind].includes(method ?? '');
+}
+
+function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  tgt: Routable,
+): Promise<void> {
+  const session = apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return Promise.resolve();
+  }
+  if (tgt.kind === 'accounts')
+    return handleAccountRoute(req, res, deps, session, tgt.id, tgt.route);
+  return routeAgent(req, res, deps, session, tgt);
+}
+
+export function handleAgentApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+): boolean {
+  const tgt = target((req.url ?? '').split('?')[0] ?? '');
+  if (tgt === null) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (tgt.kind === 'unknown') {
+    sendJson(req, res, 404, { error: 'no such agent' });
+    return true;
+  }
+  if (!methodAllowed(tgt, req.method)) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  dispatch(req, res, deps, tgt).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'agent-api: unhandled error');
+    if (!res.headersSent) sendJson(req, res, 500, { error: 'agent api failed' });
+  });
+  return true;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/agent-connector-api.ts

@@ -0,0 +1,150 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from './log.js';
+import {
+  apiFailure,
+  apiSession,
+  bodyField,
+  cors,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from './api-http.js';
+import { parseId } from '../db/ids.js';
+import type { AgentConnectors } from '../db/agent-connectors.js';
+
+const PREFIX = '/api/agents';
+
+export interface AgentConnectorApiDeps {
+  agentConnectors: (email: string, agentId: string) => Promise<AgentConnectors>;
+  addConnector: (
+    email: string,
+    agentId: string,
+    connectorId: string,
+  ) => Promise<AgentConnectors>;
+  removeConnector: (
+    email: string,
+    agentId: string,
+    connectorId: string,
+  ) => Promise<AgentConnectors>;
+  mintCode: (
+    email: string,
+    agentId: string,
+  ) => Promise<{ code: string; expiresAt: number; agent: string }>;
+}
+
+type Routable =
+  | { kind: 'connectors'; id: string }
+  | { kind: 'connector'; id: string; connectorId: string }
+  | { kind: 'code'; id: string };
+
+type Target = Routable | { kind: 'unknown' } | null;
+
+const ALLOWED: Record<Routable['kind'], string[]> = {
+  connectors: ['GET', 'POST'],
+  connector: ['DELETE'],
+  code: ['POST'],
+};
+
+function connectorTarget(id: string, rest: string[]): Target {
+  if (rest.length === 1) return { kind: 'connectors', id };
+  if (rest.length > 2) return { kind: 'unknown' };
+  const connectorId = parseId(rest[1] ?? '');
+  return connectorId === null
+    ? { kind: 'unknown' }
+    : { kind: 'connector', id, connectorId };
+}
+
+export function target(path: string): Target {
+  if (!path.startsWith(`${PREFIX}/`)) return null;
+  const segments = path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+  const id = parseId(segments[0] ?? '');
+  const head = segments[1];
+  if (id === null || head === undefined) return null;
+  if (head === 'connectors') return connectorTarget(id, segments.slice(1));
+  if (head === 'code' && segments.length === 2) return { kind: 'code', id };
+  return null;
+}
+
+async function handleConnectors(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentConnectorApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  if (req.method === 'GET') {
+    sendJson(req, res, 200, await deps.agentConnectors(session.email, id));
+    return;
+  }
+  const connectorId = bodyField(await readJsonBody(req), 'connectorId');
+  if (typeof connectorId !== 'string' || parseId(connectorId) === null) {
+    sendJson(req, res, 400, { error: 'connectorId is required' });
+    return;
+  }
+  sendJson(req, res, 200, await deps.addConnector(session.email, id, connectorId));
+}
+
+async function handleCode(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentConnectorApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const minted = await deps.mintCode(session.email, id);
+  log.info({ agent: id, email: session.email }, 'agent-api: minted pairing code');
+  sendJson(req, res, 201, minted);
+}
+
+async function route(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentConnectorApiDeps,
+  session: ApiSession,
+  tgt: Routable,
+): Promise<void> {
+  try {
+    if (tgt.kind === 'connectors') await handleConnectors(req, res, deps, session, tgt.id);
+    else if (tgt.kind === 'code') await handleCode(req, res, deps, session, tgt.id);
+    else
+      sendJson(
+        req,
+        res,
+        200,
+        await deps.removeConnector(session.email, tgt.id, tgt.connectorId),
+      );
+  } catch (err) {
+    apiFailure(req, res, err, 'agent-api');
+  }
+}
+
+export function handleAgentConnectorRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentConnectorApiDeps,
+): boolean {
+  const tgt = target((req.url ?? '').split('?')[0] ?? '');
+  if (tgt === null) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (tgt.kind === 'unknown') {
+    sendJson(req, res, 404, { error: 'no such connector' });
+    return true;
+  }
+  if (!ALLOWED[tgt.kind].includes(req.method ?? '')) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  const session = apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return true;
+  }
+  route(req, res, deps, session, tgt).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'agent-api: unhandled error');
+    if (!res.headersSent) sendJson(req, res, 500, { error: 'agent api failed' });
+  });
+  return true;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/agent-pair.ts

@@ -0,0 +1,20 @@
+import { makeCodeStore } from './pair-codes.js';
+
+export interface AgentCode {
+  email: string;
+  agentId: string;
+}
+
+const store = makeCodeStore<AgentCode>('ma');
+
+export const AGENT_CODE_RE = store.pattern;
+
+export const mintAgentCode = (
+  entry: AgentCode,
+  now?: number,
+): { code: string; expiresAt: number } => store.mint(entry, now);
+
+export const takeAgentCode = (code: string, now?: number): AgentCode | undefined =>
+  store.take(code, now);
+
+export const agentCodeCount = (): number => store.count();

package/runtime/node_modules/@metro-labs/mcp/src/daemon/api-error.ts

@@ -0,0 +1,8 @@
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/api-http.ts

@@ -0,0 +1,152 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { errMsg, log } from './log.js';
+import {
+  verifyAgentToken,
+  verifyRunToken,
+  verifySession,
+  type AgentClaims,
+  type RunClaims,
+} from './session.js';
+import { extractToken } from '../mcp/request-identity.js';
+
+const BODY_MAX = 4 * 1024;
+const DRAIN_MAX = 2 * BODY_MAX;
+
+export interface ApiSession {
+  email: string;
+}
+
+export function cors(req: IncomingMessage): Record<string, string> {
+  return {
+    'access-control-allow-origin': req.headers.origin ?? '*',
+    'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS',
+    'access-control-allow-headers': 'Authorization, Content-Type',
+    'access-control-max-age': '86400',
+    vary: 'Origin',
+  };
+}
+
+export function sendJson(
+  req: IncomingMessage,
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+): void {
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'cache-control': 'no-store',
+    ...cors(req),
+  });
+  res.end(JSON.stringify(body));
+}
+
+export function apiSession(req: IncomingMessage): ApiSession | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const { email } = verifySession(token, secret);
+    return { email: email.toLowerCase() };
+  } catch {
+    return null;
+  }
+}
+
+export function runIdentity(req: IncomingMessage): RunClaims | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const claims = verifyRunToken(token, secret);
+    return { ...claims, email: claims.email.toLowerCase() };
+  } catch {
+    return null;
+  }
+}
+
+export interface AgentIdentity extends AgentClaims {
+  runtimeId?: string;
+}
+
+export function agentIdentity(req: IncomingMessage): AgentIdentity | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const { email, agentId } = verifyAgentToken(token, secret);
+    return { email: email.toLowerCase(), agentId };
+  } catch {
+    const run = runIdentity(req);
+    if (run === null) return null;
+    return { email: run.email, agentId: run.agentId, runtimeId: run.runtimeId };
+  }
+}
+
+export type Fence = (runtimeId: string, agentId: string) => Promise<void>;
+
+const RELEASED = 'this machine no longer holds the agent';
+
+export async function assertLease(
+  who: AgentIdentity,
+  fence: Fence,
+): Promise<void> {
+  if (who.runtimeId === undefined) return;
+  try {
+    await fence(who.runtimeId, who.agentId);
+  } catch (err) {
+    if (err instanceof ApiError) throw new ApiError(RELEASED, 401);
+    throw err;
+  }
+}
+
+export function projectParam(req: IncomingMessage): string | null {
+  const raw = new URL(req.url ?? '/', 'http://localhost').searchParams.get(
+    'project',
+  );
+  return raw === null || raw === '' ? null : raw;
+}
+
+export async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  let over = false;
+  for await (const c of req) {
+    const buf = c as Buffer;
+    total += buf.length;
+    if (total > BODY_MAX) over = true;
+    if (!over) chunks.push(buf);
+    else if (total > DRAIN_MAX) break;
+  }
+  if (over) throw new ApiError('request body too large', 413);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (raw === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new ApiError('body must be JSON', 400);
+  }
+}
+
+export function apiFailure(
+  req: IncomingMessage,
+  res: ServerResponse,
+  err: unknown,
+  label = 'agent-api',
+): void {
+  if (err instanceof ApiError) {
+    sendJson(req, res, err.status, { error: err.message });
+    return;
+  }
+  log.warn({ err: errMsg(err) }, `${label}: request failed`);
+  if (!res.headersSent) sendJson(req, res, 500, { error: `${label} failed` });
+}
+
+export function bodyField(body: unknown, key: string): unknown {
+  return typeof body === 'object' && body !== null && !Array.isArray(body)
+    ? (body as Record<string, unknown>)[key]
+    : undefined;
+}