@stage-labs/metro 0.1.0-beta.8 → 0.1.0-beta.80

package/runtime/node_modules/@metro-labs/daemon/src/agents/accounts-api.ts

@@ -0,0 +1,311 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { ApiError } from '@metro-labs/http/api-error';
+import {
+  apiFailure,
+  bodyField,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from '@metro-labs/http/api-http';
+import {
+  isStationName,
+  parseAccountId,
+  type AccountRef,
+} from './account-attach.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import {
+  ATTACHABLE_STATIONS,
+  isAttachStation,
+  type AttachInput,
+  type OneTimeSecret,
+  type PreparedAccount,
+} from '../stations/attach.js';
+import {
+  INTERACTIVE_STATIONS,
+  isInteractiveStation,
+  type InteractiveStation,
+} from '../stations/attach-interactive.js';
+import {
+  ATTACH_ID_RE,
+  type AttachOwner,
+  type AttachView,
+} from '../stations/attach-session.js';
+
+export interface AttachSessionApi {
+  start: (
+    owner: AttachOwner,
+    station: InteractiveStation,
+    input: Record<string, unknown>,
+  ) => Promise<AttachView>;
+  view: (owner: AttachOwner, attachId: string) => AttachView;
+  submit: (
+    owner: AttachOwner,
+    attachId: string,
+    input: { code?: unknown; password?: unknown },
+  ) => Promise<AttachView>;
+  cancel: (owner: AttachOwner, attachId: string) => Promise<void>;
+}
+
+export interface AccountApiDeps {
+  attachSessions: AttachSessionApi;
+  prepareAccount: (input: AttachInput) => Promise<PreparedAccount>;
+  attachAccount: (
+    subject: string,
+    agentId: string,
+    station: StationName,
+    config: Record<string, unknown>,
+  ) => Promise<AccountRef>;
+  detachAccount: (
+    subject: string,
+    agentId: string,
+    station: StationName,
+    accountId: string,
+  ) => Promise<AccountRef>;
+  syncStations: (station: StationName) => Promise<void>;
+}
+
+export type AccountRoute =
+  | { kind: 'start' }
+  | { kind: 'session'; attachId: string }
+  | { kind: 'step'; attachId: string }
+  | { kind: 'account'; station: StationName; accountId: string };
+
+export const ATTACHABLE: string[] = [
+  ...ATTACHABLE_STATIONS,
+  ...INTERACTIVE_STATIONS,
+];
+
+const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
+  start: ['POST'],
+  session: ['GET', 'DELETE'],
+  step: ['POST'],
+  account: ['DELETE'],
+};
+
+function twoSegmentRoute(head: string, tail: string): AccountRoute | null {
+  if (ATTACH_ID_RE.test(head))
+    return tail === 'step' ? { kind: 'step', attachId: head } : null;
+  if (!isStationName(head)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: 'account', station: head, accountId };
+}
+
+export function accountRoute(rest: string[]): AccountRoute | null {
+  const [head, tail] = rest;
+  if (head === undefined) return null;
+  if (rest.length === 1)
+    return head === 'start'
+      ? { kind: 'start' }
+      : ATTACH_ID_RE.test(head)
+        ? { kind: 'session', attachId: head }
+        : null;
+  if (rest.length !== 2 || tail === undefined) return null;
+  return twoSegmentRoute(head, tail);
+}
+
+export function accountRouteAllows(
+  route: AccountRoute,
+  method: string | undefined,
+): boolean {
+  return ROUTE_METHODS[route.kind].includes(method ?? '');
+}
+
+async function activate(
+  deps: AccountApiDeps,
+  station: StationName,
+): Promise<boolean> {
+  try {
+    await deps.syncStations(station);
+    return true;
+  } catch (err) {
+    log.warn(
+      { station, err: errMsg(err) },
+      'account-api: station reload failed, the change lands at the next boot',
+    );
+    return false;
+  }
+}
+
+interface AttachPayload {
+  status: 'done';
+  agentId: string;
+  station: string;
+  accountId: string;
+  identity: Record<string, string>;
+  activated: boolean;
+  secret?: OneTimeSecret;
+}
+
+async function storeAccount(
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  station: StationName,
+  prepared: PreparedAccount,
+): Promise<AccountRef> {
+  try {
+    return await deps.attachAccount(
+      session.subject,
+      agentId,
+      station,
+      prepared.config,
+    );
+  } catch (err) {
+    prepared.discard?.();
+    throw err;
+  }
+}
+
+function ownerOf(session: ApiSession, agentId: string): AttachOwner {
+  return { subject: session.subject, agentId };
+}
+
+function asInput(body: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiId', 'apiHash', 'phone'])
+    out[key] = bodyField(body, key);
+  return out;
+}
+
+async function handleStart(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const station = bodyField(body, 'station');
+  if (isInteractiveStation(station)) {
+    const view = await deps.attachSessions.start(
+      ownerOf(session, agentId),
+      station,
+      asInput(body),
+    );
+    sendJson(req, res, 201, view);
+    return;
+  }
+  if (!isAttachStation(station))
+    throw new ApiError(`station must be one of ${ATTACHABLE.join(', ')}`, 400);
+  const prepared = await deps.prepareAccount({
+    station,
+    token: bodyField(body, 'token'),
+  });
+  const ref = await storeAccount(deps, session, agentId, station, prepared);
+  log.info(
+    { agentId: ref.agentId, station, account: ref.accountId },
+    'account-api: attached a station account',
+  );
+  const payload: AttachPayload = {
+    status: 'done',
+    agentId: ref.agentId,
+    station,
+    accountId: ref.accountId,
+    identity: prepared.identity,
+    activated: await activate(deps, station),
+  };
+  sendJson(
+    req,
+    res,
+    201,
+    prepared.secret === undefined
+      ? payload
+      : { ...payload, secret: prepared.secret },
+  );
+}
+
+async function handleDetach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const ref = await deps.detachAccount(
+    session.subject,
+    agentId,
+    target.station,
+    target.accountId,
+  );
+  log.info(
+    { agentId: ref.agentId, station: ref.station, account: ref.accountId },
+    'account-api: detached a station account',
+  );
+  sendJson(req, res, 200, {
+    agentId: ref.agentId,
+    station: ref.station,
+    accountId: ref.accountId,
+    detached: true,
+    activated: await activate(deps, ref.station),
+  });
+}
+
+async function handleSession(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  if (req.method === 'DELETE') {
+    await deps.attachSessions.cancel(owner, attachId);
+    sendJson(req, res, 200, { attachId, cancelled: true });
+    return;
+  }
+  sendJson(req, res, 200, deps.attachSessions.view(owner, attachId));
+}
+
+async function handleStep(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const view = await deps.attachSessions.submit(owner, attachId, {
+    code: bodyField(body, 'code'),
+    password: bodyField(body, 'password'),
+  });
+  sendJson(req, res, 200, view);
+}
+
+async function dispatchRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  if (route.kind === 'start')
+    return handleStart(req, res, deps, session, agentId);
+  if (route.kind === 'session')
+    return handleSession(
+      req,
+      res,
+      deps,
+      ownerOf(session, agentId),
+      route.attachId,
+    );
+  if (route.kind === 'step')
+    return handleStep(req, res, deps, ownerOf(session, agentId), route.attachId);
+  return handleDetach(req, res, deps, session, agentId, route);
+}
+
+export async function handleAccountRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  try {
+    await dispatchRoute(req, res, deps, session, agentId, route);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/admin.ts

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError } from '@metro-labs/http/api-error';
+import { AGENT_NAME_RE } from '@metro-labs/core/ids';
+
+export class AgentAdminError extends ApiError {}
+
+export interface AgentSummary {
+  id: string;
+  name: string;
+  owned: boolean;
+  key: string | null;
+}
+
+export interface CreatedAgent {
+  id: string;
+  name: string;
+  key: string;
+}
+
+export interface OwnedAgent {
+  id: string;
+  name: string;
+}
+
+export type DeletedAgent = OwnedAgent;
+
+export interface ResetAgentKey extends OwnedAgent {
+  key: string;
+}
+
+export function normalizeAgentName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim() : '';
+  if (!AGENT_NAME_RE.test(name))
+    throw new AgentAdminError(
+      'name must be 2-32 characters of A-Z, a-z, 0-9, - or _, starting with a letter or digit',
+      400,
+    );
+  return name;
+}
+
+export function newApiKey(): string {
+  return `mk_${randomBytes(32).toString('base64url')}`;
+}

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

@@ -0,0 +1,302 @@
+import { webhookPort } from '../net/tunnel.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { parseId } from '@metro-labs/core/ids';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  apiFailure,
+  apiSession,
+  projectParam,
+  cors,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from '@metro-labs/http/api-http';
+import {
+  accountRoute,
+  accountRouteAllows,
+  ATTACHABLE,
+  handleAccountRoute,
+  type AccountApiDeps,
+  type AccountRoute,
+} from './accounts-api.js';
+import {
+  type AgentSummary,
+  type CreatedAgent,
+  type DeletedAgent,
+  type ResetAgentKey,
+} from './admin.js';
+
+const PREFIX = '/api/agents';
+const SERVER_NAME = 'metro';
+
+export interface AgentApiDeps extends AccountApiDeps {
+  listAgents: (subject: string, project: string) => Promise<AgentSummary[]>;
+  createAgent: (
+    subject: string,
+    project: string,
+    name: string,
+  ) => Promise<CreatedAgent>;
+  deleteAgent: (
+    subject: string,
+    id: string,
+  ) => Promise<DeletedAgent>;
+  resetKey: (
+    subject: string,
+    id: string,
+  ) => Promise<ResetAgentKey>;
+  gatherAccounts: (allowed: Set<string>) => Promise<{
+    accounts: Record<string, unknown[]>;
+    unavailable: string[];
+  }>;
+  capabilities: () => Record<string, string[]>;
+  attachable?: string[];
+  liveness: () => Map<string, { connected: boolean; lastSeenAt: number }>;
+  connectorIds: (agentIds: string[]) => Promise<Map<string, string[]>>;
+}
+
+type Routable =
+  | { kind: 'collection' }
+  | { kind: 'agent'; id: string }
+  | { kind: 'key'; 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[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 = parseId(head);
+  return id === null ? { kind: 'unknown' } : subTarget(id, segments.slice(1));
+}
+
+const localMcpEndpoint = (): string => `http://127.0.0.1:${String(webhookPort())}/mcp`;
+
+export function mcpAddCommand(key: string): string {
+  const url = `${localMcpEndpoint()}?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: `${localMcpEndpoint()}?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 }>,
+  connectors: Map<string, string[]>,
+): Record<string, unknown> {
+  return {
+    id: agent.id,
+    name: agent.name,
+    owned: agent.owned,
+    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.subject, project);
+  const live = deps.liveness();
+  const connectors = await deps.connectorIds(list.map((a) => a.id));
+  const base = {
+    agents: list.map((a) => agentPayload(a, live, connectors)),
+    capabilities: deps.capabilities(),
+    attachable: deps.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 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.subject, project, name as string);
+  log.info(
+    { agent: created.name, id: created.id, owner: session.subject },
+    '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.subject, id);
+  log.info(
+    { agent: reset.name, id: reset.id, owner: session.subject },
+    '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.subject, id);
+  log.info(
+    { agent: gone.name, id: gone.id, owner: session.subject },
+    '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 === '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'],
+};
+
+function methodAllowed(tgt: Routable, method: string | undefined): boolean {
+  if (tgt.kind === 'accounts') return accountRouteAllows(tgt.route, method);
+  return ALLOWED[tgt.kind].includes(method ?? '');
+}
+
+async function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  tgt: Routable,
+): Promise<void> {
+  const session = await apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return;
+  }
+  if (tgt.kind === 'accounts')
+    await handleAccountRoute(req, res, deps, session, tgt.id, tgt.route);
+  else await 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;
+}