@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

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

@@ -0,0 +1,225 @@
+import { webhookPort } from '../net/tunnel.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { parseId } from '@metro-labs/core/ids';
+import { log } from '@metro-labs/core/log';
+import {
+  apiFailure,
+  apiSession, requireAdmin,
+  projectParam,
+  cors,
+  sendJson,
+  type ApiSession,
+} from '@metro-labs/http/api-http';
+import { ATTACHABLE, handleAccountRoute, type AccountApiDeps } from './accounts-api.js';
+import {
+  accountRoute,
+  accountRouteAllows,
+  type AccountRoute,
+} from './account-routes.js';
+import {
+  type AgentSummary,
+  type DeletedAgent,
+} from './admin.js';
+
+const PREFIX = '/api/agents';
+
+export interface AgentApiDeps extends AccountApiDeps {
+  listAgents: (subject: string, project: string) => Promise<AgentSummary[]>;
+  deleteAgent: (
+    subject: string,
+    id: string,
+  ) => Promise<DeletedAgent>;
+  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: '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[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`;
+
+interface KeyPayload {
+  key: string | null;
+  endpoint: string | null;
+}
+
+const credentials = (key: string): KeyPayload => ({ key, endpoint: `${localMcpEndpoint()}?token=${key}` });
+
+function keyPayload(agent: AgentSummary): KeyPayload {
+  const value = agent.owned ? agent.key : null;
+  return value === null ? { key: null, endpoint: null } : 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 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 === 'agent') {
+      requireAdmin(session);
+      await handleDelete(req, res, deps, session, tgt.id);
+    } else await handleList(req, res, deps, session);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}
+
+const ALLOWED: Record<AgentTarget['kind'], string[]> = {
+  collection: ['GET'],
+  agent: ['DELETE'],
+};
+
+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) => {
+    if (res.headersSent) return;
+    apiFailure(req, res, err, 'agent-api');
+  });
+  return true;
+}

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

@@ -0,0 +1,122 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { apiFailure, apiSession, cors, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import type { LoadedAccount, LoadedAgent, LoadedConnector } from '../stations/materialize.js';
+import { STATIONS } from '@metro-labs/core/station-names';
+
+const AGENTS = '/api/agents';
+const RESTORE_PATH = `${AGENTS}/restore`;
+const BUNDLE_MAX = 2 * 1024 * 1024;
+const STATION_NAMES = new Set<string>(STATIONS);
+
+export interface AgentBundle {
+  version: 1;
+  agent: { id: string; name: string; key: string; stations: LoadedAccount[] };
+  connectors: LoadedConnector[];
+}
+
+export const loadedAgentOf = (bundle: AgentBundle): LoadedAgent => ({
+  id: bundle.agent.id,
+  name: bundle.agent.name,
+  key: bundle.agent.key,
+  accounts: bundle.agent.stations,
+  connectors: [],
+});
+
+export interface RestoredAgent {
+  id: string;
+  name: string;
+  stations: number;
+  connectors: number;
+}
+
+export type ImportMode = 'append' | 'overwrite';
+
+export interface BundleApiDeps {
+  bundle: (subject: string, agentId: string) => Promise<AgentBundle>;
+  restore: (subject: string, bundle: AgentBundle, mode: ImportMode) => Promise<RestoredAgent>;
+}
+
+export function parseMode(raw: unknown): ImportMode {
+  const mode = isRecord(raw) && typeof raw.mode === 'string' ? raw.mode : 'overwrite';
+  if (mode !== 'append' && mode !== 'overwrite') throw bad("mode is 'append' or 'overwrite'");
+  return mode;
+}
+
+const bad = (what: string): ApiError => new ApiError(`bundle: ${what}`, 400);
+
+function stationOf(raw: unknown): LoadedAccount {
+  if (!isRecord(raw) || typeof raw.station !== 'string' || !STATION_NAMES.has(raw.station))
+    throw bad('a station is not a known station');
+  if (typeof raw.id !== 'string' || !isRecord(raw.config)) throw bad('a station has no id or config');
+  const allowlist = Array.isArray(raw.allowlist)
+    ? raw.allowlist.filter((s): s is string => typeof s === 'string')
+    : null;
+  return { station: raw.station as LoadedAccount['station'], id: raw.id, allowlist, enabled: raw.enabled !== false, config: raw.config };
+}
+
+function connectorOf(raw: unknown): LoadedConnector {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || typeof raw.name !== 'string' || typeof raw.url !== 'string')
+    throw bad('a connector is missing its id, name or url');
+  if (!isRecord(raw.config)) throw bad('a connector has no config');
+  return { id: raw.id, name: raw.name, url: raw.url, transport: 'http', config: raw.config };
+}
+
+function agentOf(raw: unknown): AgentBundle['agent'] {
+  if (!isRecord(raw)) throw bad('not a v1 agent bundle');
+  const { id, name, key, stations } = raw;
+  if (typeof id !== 'string' || parseId(id) === null) throw bad('agent id is not an id');
+  if (typeof key !== 'string' || key === '') throw bad('agent has no key');
+  if (!Array.isArray(stations)) throw bad('agent has no station list');
+  return { id, name: typeof name === 'string' ? name : '', key, stations: stations.map(stationOf) };
+}
+
+export function parseBundle(raw: unknown): AgentBundle {
+  if (!isRecord(raw) || raw.version !== 1) throw bad('not a v1 agent bundle');
+  const connectors = Array.isArray(raw.connectors) ? raw.connectors : [];
+  return { version: 1, agent: agentOf(raw.agent), connectors: connectors.map(connectorOf) };
+}
+
+async function answer(req: IncomingMessage, deps: BundleApiDeps, subject: string, path: string): Promise<unknown> {
+  if (path === RESTORE_PATH) {
+    const body: unknown = await readJsonBody(req, BUNDLE_MAX);
+    return deps.restore(subject, parseBundle(body), parseMode(body));
+  }
+  const id = parseId(path.slice(AGENTS.length + 1).split('/')[0] ?? '');
+  if (id === null) throw new ApiError('no such agent', 404);
+  return deps.bundle(subject, id);
+}
+
+export function handleBundleRequest(req: IncomingMessage, res: ServerResponse, deps: BundleApiDeps): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  const isRestore = path === RESTORE_PATH;
+  const isBundle = /^\/api\/agents\/[^/]+\/bundle$/.test(path);
+  if (!isRestore && !isBundle) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (req.method !== (isRestore ? 'POST' : 'GET')) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then((session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      return answer(req, deps, session.subject, path);
+    })
+    .then((body) => {
+      sendJson(req, res, isRestore ? 201 : 200, body);
+    })
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) apiFailure(req, res, err, 'bundle-api');
+      else {
+        log.warn({ err: errMsg(err) }, 'bundle-api: request failed');
+        if (!res.headersSent) sendJson(req, res, 500, { error: 'bundle api failed' });
+      }
+    });
+  return true;
+}

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

@@ -0,0 +1,364 @@
+import { readFileSync, rmdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isOrganizationId } from '@metro-labs/http/workos-token';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import {
+  newApiKey,
+  AgentAdminError,
+  normalizeAgentName,
+  type AgentSummary,
+  type CreatedAgent,
+  type DeletedAgent,
+  type OwnedAgent,
+} from './admin.js';
+import type { AccountRef } from './account-attach.js';
+import {
+  agentFilePath,
+  AgentFileError,
+  agentsDir,
+  listAgentFiles,
+  parseAgentFile,
+  readAgentFile,
+  type AgentFile,
+} from './files.js';
+import { newId } from '@metro-labs/core/ids';
+import { registerKey, unregisterAgentKey } from './keys.js';
+import { MOVABLE_STATIONS, type LoadedAgent } from '../stations/materialize.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import { normalizeAddress } from '@metro-labs/core/address';
+
+export const LOCAL_PROJECT_ID = 'localdaemon';
+const OWNER_FILE = '.owner';
+
+interface Stored {
+  path: string;
+  file: AgentFile;
+}
+
+const missing = (): AgentAdminError => new AgentAdminError('no such agent', 404);
+
+export function parseOwner(raw: string): string | null {
+  const text = raw.trim();
+  return isOrganizationId(text) ? text : normalizeAddress(text);
+}
+
+export function localOwner(dir = agentsDir()): string | null {
+  try {
+    return parseOwner(readFileSync(join(dir, OWNER_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function setLocalOwner(raw: string, dir = agentsDir()): string {
+  const owner = parseOwner(raw);
+  if (owner === null) throw new ApiError(`'${raw}' is neither an organization id nor an Ethereum address`, 400);
+  ensureSecureDir(dir);
+  writeSecure(join(dir, OWNER_FILE), `${owner}\n`);
+  return owner;
+}
+
+
+function isOwner(subject: string, dir: string): boolean {
+  const owner = localOwner(dir);
+  return owner !== null && owner === parseOwner(subject);
+}
+
+export function storedAgents(dir: string): Stored[] {
+  return listAgentFiles(dir).map((path) => ({ path, file: readAgentFile(path) }));
+}
+
+function save(stored: Stored): void {
+  writeSecure(stored.path, `${JSON.stringify(stored.file, null, 2)}\n`);
+}
+
+function ownedOrThrow(subject: string, id: string, dir: string): Stored {
+  if (!isOwner(subject, dir)) throw missing();
+  const found = storedAgents(dir).find((s) => s.file.id === id);
+  if (found === undefined) throw missing();
+  return found;
+}
+
+export async function localOwnedAgentOrThrow(
+  subject: string,
+  id: string,
+  dir = agentsDir(),
+): Promise<{ agent: OwnedAgent }> {
+  const { file } = ownedOrThrow(subject, id, dir);
+  return Promise.resolve({ agent: { id: file.id, name: file.name } });
+}
+
+export async function localListAgents(
+  subject: string,
+  project: string,
+  dir = agentsDir(),
+): Promise<AgentSummary[]> {
+  if (project !== LOCAL_PROJECT_ID || !isOwner(subject, dir))
+    throw new AgentAdminError('no such project', 404);
+  return Promise.resolve(
+    storedAgents(dir)
+      .map(({ file }) => ({ id: file.id, name: file.name, owned: true, key: file.key }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+  );
+}
+
+function freshId(taken: Set<string>): string {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const id = newId();
+    if (!taken.has(id)) return id;
+  }
+  throw new AgentAdminError('could not allocate a free id', 500);
+}
+
+export async function localCreateAgent(
+  subject: string,
+  project: string,
+  rawName?: string,
+  dir = agentsDir(),
+): Promise<CreatedAgent> {
+  if (project !== LOCAL_PROJECT_ID || !isOwner(subject, dir))
+    throw new AgentAdminError('no such project', 404);
+  const name = rawName === undefined ? null : normalizeAgentName(rawName);
+  const existing = storedAgents(dir);
+  if (existing.length > 0) throw new AgentAdminError('this box already has its agent', 409);
+  const id = freshId(new Set());
+  const key = newApiKey();
+  ensureSecureDir(dir);
+  save({
+    path: agentFilePath(dir),
+    file: { version: 1, id, name, key, owner: localOwner(dir), stations: [], connectors: [] },
+  });
+  registerKey(key, id);
+  return Promise.resolve({ id, name, key });
+}
+
+export type Ensured = 'created' | 'present' | 'no-owner';
+
+export async function ensureLocalAgent(dir = agentsDir()): Promise<Ensured> {
+  if (storedAgents(dir).length > 0) return 'present';
+  const owner = localOwner(dir);
+  if (owner === null) return 'no-owner';
+  await localCreateAgent(owner, LOCAL_PROJECT_ID, undefined, dir);
+  return 'created';
+}
+
+export async function localDeleteAgent(
+  subject: string,
+  id: string,
+  dir = agentsDir(),
+): Promise<DeletedAgent> {
+  const stored = ownedOrThrow(subject, id, dir);
+  const attached = stored.file.stations.length;
+  if (attached > 0)
+    throw new AgentAdminError(
+      `the agent still has ${String(attached)} station account(s) attached — detach them first`,
+      409,
+    );
+  rmSync(stored.path);
+  removeIfEmpty(join(stored.path, '..'));
+  unregisterAgentKey(id);
+  return Promise.resolve({ id, name: stored.file.name });
+}
+
+function assertUnclaimed(existing: Stored[], agent: LoadedAgent): void {
+  for (const { file } of existing) {
+    if (file.id === agent.id)
+      throw new AgentAdminError(`agent ${agent.id} is already on this machine`, 409);
+    if (agent.key !== null && file.key === agent.key)
+      throw new AgentAdminError('that agent key is already on this machine', 409);
+  }
+}
+
+export function assertLocalOwner(subject: string, dir = agentsDir()): void {
+  if (!isOwner(subject, dir)) throw new AgentAdminError('no such project', 404);
+}
+
+function assertImportable(agent: LoadedAgent): asserts agent is LoadedAgent & { key: string } {
+  const immovable = agent.accounts.find((a) => !MOVABLE_STATIONS.has(a.station));
+  if (immovable !== undefined)
+    throw new AgentAdminError(
+      `a ${immovable.station} endpoint needs a public url and cannot live on a local daemon`,
+      400,
+    );
+  if (agent.key === null)
+    throw new AgentAdminError('that agent has no key; reset it on metro.box first', 400);
+}
+
+interface ImportTarget {
+  path: string;
+  previous: AgentFile | undefined;
+}
+
+function importTarget(dir: string, agent: LoadedAgent & { key: string }): ImportTarget {
+  const existing = storedAgents(dir);
+  const same = existing.find((s) => s.file.id === agent.id);
+  if (same === undefined && existing.length > 0)
+    throw new AgentAdminError('this box already has its agent; import into it rather than bringing another', 409);
+  assertUnclaimed(existing.filter((s) => s !== same), agent);
+  return { path: same?.path ?? agentFilePath(dir), previous: same?.file };
+}
+
+export type ImportMode = 'append' | 'overwrite';
+
+export async function localImportAgent(
+  subject: string,
+  agent: LoadedAgent,
+  dir = agentsDir(),
+  mode: ImportMode = 'overwrite',
+): Promise<{ id: string; name: string; key: string; stations: number }> {
+  assertLocalOwner(subject, dir);
+  assertImportable(agent);
+  const { path, previous } = importTarget(dir, agent);
+  const file = fileFor(agent, localOwner(dir), path, previous, mode);
+  ensureSecureDir(join(path, '..'));
+  save({ path, file });
+  if (previous !== undefined && previous.key !== agent.key) unregisterAgentKey(agent.id);
+  registerKey(agent.key, agent.id);
+  return Promise.resolve({
+    id: agent.id,
+    name: agent.name,
+    key: agent.key,
+    stations: file.stations.length,
+  });
+}
+
+function mergedStations(
+  agent: LoadedAgent,
+  previous: AgentFile | undefined,
+  mode: ImportMode,
+): AgentFile['stations'] {
+  const before = previous?.stations ?? [];
+  const here = (station: string, id: string): boolean => before.some((s) => s.station === station && s.id === id);
+  const fromMetro = agent.accounts
+    .map((a) => ({ ...a, allowlist: a.allowlist ?? ['*'] }))
+    .filter((m) => mode === 'overwrite' || !here(m.station, m.id));
+  const kept = before.filter((s) => !fromMetro.some((m) => m.station === s.station && m.id === s.id));
+  return [...fromMetro, ...kept];
+}
+
+function fileFor(
+  agent: LoadedAgent,
+  owner: string | null,
+  path: string,
+  previous: AgentFile | undefined,
+  mode: ImportMode,
+): AgentFile {
+  try {
+    return parseAgentFile(
+      JSON.stringify({
+        version: 1,
+        id: agent.id,
+        name: previous?.name ?? null,
+        key: agent.key,
+        owner,
+        stations: mergedStations(agent, previous, mode),
+        connectors: previous?.connectors ?? [],
+      }),
+      path,
+    );
+  } catch (err) {
+    if (err instanceof AgentFileError)
+      throw new AgentAdminError(`metro's copy of this agent cannot be written here: ${err.message}`, 400);
+    throw err;
+  }
+}
+
+export function readLocalAgentFile(agentId: string, dir = agentsDir()): AgentFile {
+  const found = storedAgents(dir).find((s) => s.file.id === agentId);
+  if (found === undefined) throw missing();
+  return found.file;
+}
+
+function removeIfEmpty(folder: string): void {
+  try {
+    rmdirSync(folder);
+  } catch {
+    return;
+  }
+}
+
+function assertTokenFree(all: Stored[], station: StationName, token: string): void {
+  const taken = all.some((s) =>
+    s.file.stations.some(
+      (a) => a.station === station && a.config.token === token,
+    ),
+  );
+  if (taken)
+    throw new AgentAdminError(
+      'that bot token is already attached to an agent on this machine',
+      409,
+    );
+}
+
+export async function localAttachAccount(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  config: Record<string, unknown>,
+  dir = agentsDir(),
+): Promise<AccountRef> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  if (!MOVABLE_STATIONS.has(station))
+    throw new AgentAdminError(
+      `a ${station} endpoint needs a public url and cannot live on a local daemon`,
+      400,
+    );
+  const token = config.token;
+  if (typeof token === 'string') assertTokenFree(storedAgents(dir), station, token);
+  const taken = new Set(stored.file.stations.map((a) => a.id));
+  const accountId = freshId(taken);
+  stored.file.stations.push({ station, id: accountId, allowlist: ['*'], enabled: true, config });
+  save(stored);
+  return Promise.resolve({ agentId, station, accountId });
+}
+
+export async function localSetAllowlist(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  allowlist: string[],
+  dir = agentsDir(),
+): Promise<string[]> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const account = stored.file.stations.find((a) => a.station === station && a.id === accountId);
+  if (account === undefined) throw new AgentAdminError('no such account on this agent', 404);
+  account.allowlist = allowlist;
+  save(stored);
+  return Promise.resolve(allowlist);
+}
+
+export async function localSetAccountEnabled(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  enabled: boolean,
+  dir = agentsDir(),
+): Promise<boolean> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const account = stored.file.stations.find((a) => a.station === station && a.id === accountId);
+  if (account === undefined) throw new AgentAdminError('no such account on this agent', 404);
+  account.enabled = enabled;
+  save(stored);
+  return Promise.resolve(enabled);
+}
+
+export async function localDetachAccount(
+  subject: string,
+  agentId: string,
+  station: StationName,
+  accountId: string,
+  dir = agentsDir(),
+): Promise<AccountRef> {
+  const stored = ownedOrThrow(subject, agentId, dir);
+  const before = stored.file.stations.length;
+  stored.file.stations = stored.file.stations.filter(
+    (a) => !(a.station === station && a.id === accountId),
+  );
+  if (stored.file.stations.length === before)
+    throw new AgentAdminError('no such account on this agent', 404);
+  save(stored);
+  return Promise.resolve({ agentId, station, accountId });
+}