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

package/runtime/node_modules/@metro-labs/daemon/src/connectors/relay-target.ts

@@ -0,0 +1,39 @@
+import type { ConnectorAuth, OAuthAuth } from './verify.js';
+
+export type RelayTarget =
+  | { kind: 'ok'; url: string; headers: Record<string, string> }
+  | { kind: 'missing' }
+  | { kind: 'signin' };
+
+export const bearerHeaders = (token: string): Record<string, string> => ({
+  Authorization: `Bearer ${token}`,
+});
+
+export function staleUsable(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt === undefined || auth.expiresAt > now;
+}
+
+function headerAuthHeaders(auth: ConnectorAuth): Record<string, string> | null {
+  return auth.kind === 'header' ? { [auth.name]: auth.value } : null;
+}
+
+export function unrefreshedTarget(
+  url: string,
+  auth: OAuthAuth,
+  force: boolean,
+  now = Date.now(),
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  if (staleUsable(auth, now))
+    return { kind: 'ok', url, headers: bearerHeaders(auth.accessToken) };
+  return { kind: 'ok', url, headers: {} };
+}
+
+export function fixedTarget(
+  url: string,
+  auth: Exclude<ConnectorAuth, OAuthAuth>,
+  force: boolean,
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  return { kind: 'ok', url, headers: headerAuthHeaders(auth) ?? {} };
+}

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

@@ -0,0 +1,295 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RelayTarget } from './relay-target.js';
+import type { AgentIdentity } from '@metro-labs/http/api-http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { errMsg, log } from '@metro-labs/core/log';
+
+export interface RelayApiDeps {
+  target: (connectorId: string, force: boolean) => Promise<RelayTarget>;
+  identify: (req: IncomingMessage) => AgentIdentity | null;
+}
+
+const ID_PATH_RE = /^\/relay\/([A-Za-z0-9][A-Za-z0-9_-]{10})$/;
+const METHODS = new Set(['POST', 'GET', 'DELETE']);
+const RELAY_BODY_MAX = 8 * 1024 * 1024;
+const FIRST_BYTE_MS = 120_000;
+const PASS_REQ = [
+  'accept',
+  'content-type',
+  'mcp-session-id',
+  'mcp-protocol-version',
+  'last-event-id',
+] as const;
+const PASS_RES = [
+  'content-type',
+  'mcp-session-id',
+  'mcp-protocol-version',
+  'cache-control',
+] as const;
+
+const keepaliveMs = (): number =>
+  Number(process.env.METRO_RELAY_KEEPALIVE_MS) || 25_000;
+
+const reconnectUrl = (id: string): string =>
+  `https://metro.box/#/connector/${id}`;
+
+function answer(
+  res: ServerResponse,
+  status: number,
+  body: Record<string, unknown>,
+): void {
+  if (res.headersSent) return;
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+const signinAnswer = (res: ServerResponse, id: string): void => {
+  answer(res, 424, {
+    error: 'this connector needs signing in again',
+    reconnect: reconnectUrl(id),
+  });
+};
+
+function closeIfBodyUnread(req: IncomingMessage, res: ServerResponse): void {
+  if (req.readableEnded) return;
+  const drop = (): void => {
+    req.socket?.destroy();
+  };
+  if (res.writableFinished) drop();
+  else res.once('finish', drop);
+}
+
+async function readCapped(req: IncomingMessage): Promise<Uint8Array<ArrayBuffer>> {
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > RELAY_BODY_MAX)
+    throw new ApiError('relay body exceeds 8 MiB', 413);
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const buf = chunk as Buffer;
+    total += buf.length;
+    if (total > RELAY_BODY_MAX)
+      throw new ApiError('relay body exceeds 8 MiB', 413);
+    chunks.push(buf);
+  }
+  const merged = Buffer.concat(chunks);
+  const out = new Uint8Array(new ArrayBuffer(merged.byteLength));
+  out.set(merged);
+  return out;
+}
+
+function upstreamHeaders(
+  req: IncomingMessage,
+  injected: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of PASS_REQ) {
+    const value = req.headers[name];
+    if (typeof value === 'string') out[name] = value;
+  }
+  return { ...out, ...injected };
+}
+
+async function forward(
+  req: IncomingMessage,
+  target: { url: string; headers: Record<string, string> },
+  body: Uint8Array<ArrayBuffer> | null,
+  signal: AbortSignal,
+): Promise<Response> {
+  const firstByte = setTimeout(() => {
+    log.warn({ url: target.url }, 'relay: upstream sent no response in time');
+  }, FIRST_BYTE_MS);
+  firstByte.unref?.();
+  try {
+    return await fetch(target.url, {
+      method: req.method,
+      headers: upstreamHeaders(req, target.headers),
+      ...(body === null ? {} : { body }),
+      signal,
+      redirect: 'manual',
+    });
+  } finally {
+    clearTimeout(firstByte);
+  }
+}
+
+interface Keepalive {
+  touch: () => void;
+  stop: () => void;
+}
+
+function startKeepalive(res: ServerResponse): Keepalive {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const arm = (): void => {
+    timer = setTimeout(() => {
+      try {
+        res.write(': keepalive\n\n');
+      } catch {
+        log.debug('relay: keepalive write failed');
+      }
+      arm();
+    }, keepaliveMs());
+    timer.unref?.();
+  };
+  arm();
+  return {
+    touch: (): void => {
+      if (timer) clearTimeout(timer);
+      arm();
+    },
+    stop: (): void => {
+      if (timer) clearTimeout(timer);
+    },
+  };
+}
+
+async function pumpBody(
+  res: ServerResponse,
+  body: ReadableStream<Uint8Array>,
+  touch: () => void,
+): Promise<void> {
+  const reader = body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return;
+    touch();
+    const ok = res.write(value);
+    if (!ok)
+      await new Promise((resolve) => {
+        res.once('drain', resolve);
+      });
+  }
+}
+
+async function pipe(res: ServerResponse, upstream: Response): Promise<void> {
+  const headers: Record<string, string> = {};
+  for (const name of PASS_RES) {
+    const value = upstream.headers.get(name);
+    if (value !== null) headers[name] = value;
+  }
+  const sse = (headers['content-type'] ?? '').includes('text/event-stream');
+  if (sse) headers['x-accel-buffering'] = 'no';
+  res.writeHead(upstream.status, headers);
+  if (upstream.body === null) {
+    res.end();
+    return;
+  }
+  const keepalive = sse ? startKeepalive(res) : null;
+  try {
+    await pumpBody(res, upstream.body, () => keepalive?.touch());
+  } finally {
+    keepalive?.stop();
+  }
+  res.end();
+}
+
+const authFailed = (status: number): boolean =>
+  status === 401 || status === 403;
+
+type Exchanged =
+  | { kind: 'response'; upstream: Response }
+  | { kind: 'missing' }
+  | { kind: 'signin' };
+
+async function exchange(
+  req: IncomingMessage,
+  connectorId: string,
+  deps: RelayApiDeps,
+  body: Uint8Array<ArrayBuffer> | null,
+  signal: AbortSignal,
+): Promise<Exchanged> {
+  const target = await deps.target(connectorId, false);
+  if (target.kind !== 'ok') return { kind: target.kind };
+  let upstream = await forward(req, target, body, signal);
+  if (!authFailed(upstream.status)) return { kind: 'response', upstream };
+  await upstream.body?.cancel();
+  const fresh = await deps.target(connectorId, true);
+  if (fresh.kind !== 'ok') return { kind: 'signin' };
+  upstream = await forward(req, fresh, body, signal);
+  if (!authFailed(upstream.status)) return { kind: 'response', upstream };
+  await upstream.body?.cancel();
+  return { kind: 'signin' };
+}
+
+async function relayExchange(
+  req: IncomingMessage,
+  res: ServerResponse,
+  connectorId: string,
+  deps: RelayApiDeps,
+): Promise<void> {
+  const control = new AbortController();
+  const bail = (): void => {
+    if (!res.writableEnded) control.abort();
+  };
+  res.once('close', bail);
+  res.socket?.once('close', bail);
+  res.once('finish', () => {
+    res.socket?.removeListener('close', bail);
+  });
+  const body = req.method === 'POST' ? await readCapped(req) : null;
+  const out = await exchange(
+    req,
+    connectorId,
+    deps,
+    body,
+    control.signal,
+  );
+  if (out.kind === 'missing') {
+    answer(res, 404, { error: 'no such connector' });
+    return;
+  }
+  if (out.kind === 'signin') {
+    signinAnswer(res, connectorId);
+    return;
+  }
+  if (out.upstream.status >= 300 && out.upstream.status < 400) {
+    await out.upstream.body?.cancel();
+    answer(res, 502, { error: 'the connector redirected; metro does not follow' });
+    return;
+  }
+  await pipe(res, out.upstream);
+}
+
+function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  connectorId: string,
+  deps: RelayApiDeps,
+): void {
+  const who = deps.identify(req);
+  if (who === null) {
+    answer(res, 401, { error: 'unauthorized' });
+    return;
+  }
+  relayExchange(req, res, connectorId, deps)
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) {
+        answer(res, err.status, { error: err.message });
+      } else {
+        log.warn({ err: errMsg(err), connector: connectorId }, 'relay: failed');
+        answer(res, 502, { error: 'metro could not reach the connector' });
+        if (!res.writableEnded) res.end();
+      }
+      closeIfBodyUnread(req, res);
+    });
+}
+
+export function handleRelayRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RelayApiDeps,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== '/relay' && !path.startsWith('/relay/')) return false;
+  const match = ID_PATH_RE.exec(path);
+  if (match?.[1] === undefined) {
+    answer(res, 404, { error: 'no such connector' });
+    return true;
+  }
+  if (!METHODS.has(req.method ?? '')) {
+    answer(res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  dispatch(req, res, match[1], deps);
+  return true;
+}

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

@@ -0,0 +1,277 @@
+import { join } from 'node:path';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  connectorUrlText,
+  ConnectorVerifyError,
+  parseConnectorUrl,
+  verifyRemoteMcp,
+  type ConnectorAuth,
+  type OAuthAuth,
+} from './verify.js';
+import { oauthExpired, refreshOAuth } from './oauth.js';
+import { advertisesOAuth } from './oauth-discovery.js';
+import {
+  ConnectorError,
+  connectorAuth,
+  connectorName,
+  readConfig,
+  stamp,
+  type ConnectorConfig,
+} from './config.js';
+import {
+  bearerHeaders,
+  fixedTarget,
+  unrefreshedTarget,
+  type RelayTarget,
+} from './relay-target.js';
+import {
+  connectorFromRow,
+  UNVERIFIED,
+  type Connector,
+  type ConnectorCheck,
+  type ConnectorInput,
+  type DeletedConnector,
+} from './model.js';
+import { agentsDir } from '../agents/files.js';
+import { assertLocalOwner, LOCAL_PROJECT_ID } from '../agents/file-admin.js';
+import { newId } from '@metro-labs/core/ids';
+import type { LoadedConnector } from '../stations/materialize.js';
+
+export interface LocalConnectorRow {
+  id: string;
+  name: string;
+  url: string;
+  transport: 'http';
+  config: ConnectorConfig;
+}
+
+const FILE = 'connectors.json';
+const filePath = (dir: string): string => join(dir, FILE);
+
+const isRow = (v: unknown): v is { id: string; name: string; url: string; config?: unknown } =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { id?: unknown }).id === 'string' &&
+  typeof (v as { name?: unknown }).name === 'string' &&
+  typeof (v as { url?: unknown }).url === 'string';
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value.map((item: unknown) => item) : [];
+
+export function readLocalConnectors(dir = agentsDir()): LocalConnectorRow[] {
+  const raw = readJson<{ connectors?: unknown }>(filePath(dir), {}, {
+    warn: 'connectors.json: malformed, ignoring',
+  });
+  return asList(raw.connectors).filter(isRow).map((r) => ({
+    id: r.id,
+    name: r.name,
+    url: r.url,
+    transport: 'http' as const,
+    config: readConfig(r.config),
+  }));
+}
+
+function writeRows(dir: string, rows: LocalConnectorRow[]): void {
+  writeSecure(filePath(dir), `${JSON.stringify({ version: 1, connectors: rows }, null, 2)}\n`);
+}
+
+const missing = (): ConnectorError => new ConnectorError('no such connector', 404);
+
+function ownedRows(subject: string, project: string, dir: string): LocalConnectorRow[] {
+  assertLocalOwner(subject, dir);
+  if (project !== LOCAL_PROJECT_ID) throw new ConnectorError('no such project', 404);
+  return readLocalConnectors(dir);
+}
+
+function rowOrThrow(subject: string, id: string, dir: string): LocalConnectorRow {
+  assertLocalOwner(subject, dir);
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row === undefined) throw missing();
+  return row;
+}
+
+function replace(dir: string, row: LocalConnectorRow): Connector {
+  writeRows(dir, readLocalConnectors(dir).map((r) => (r.id === row.id ? row : r)));
+  return connectorFromRow(row);
+}
+
+async function oauthCapable(url: URL, auth: ConnectorAuth): Promise<boolean> {
+  if (auth.kind === 'oauth') return true;
+  if (auth.kind === 'header') return false;
+  return advertisesOAuth(url);
+}
+
+export function localImportConnectors(rows: LoadedConnector[], dir = agentsDir()): number {
+  const current = readLocalConnectors(dir);
+  for (const row of rows) {
+    const other = current.find((r) => r.id !== row.id && r.name === row.name);
+    if (other !== undefined)
+      throw new ConnectorError(`a connector named '${row.name}' already exists on this daemon; rename it first`, 409);
+  }
+  const imported: LocalConnectorRow[] = rows.map((row) => ({
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    transport: 'http',
+    config: readConfig(row.config),
+  }));
+  const ids = new Set(imported.map((r) => r.id));
+  writeRows(dir, [...current.filter((r) => !ids.has(r.id)), ...imported]);
+  return imported.length;
+}
+
+export async function localListConnectors(
+  subject: string,
+  project: string,
+  dir = agentsDir(),
+): Promise<Connector[]> {
+  return Promise.resolve(ownedRows(subject, project, dir).map(connectorFromRow));
+}
+
+export async function localGetConnector(subject: string, id: string, dir = agentsDir()): Promise<Connector> {
+  return Promise.resolve(connectorFromRow(rowOrThrow(subject, id, dir)));
+}
+
+function assertNameFree(name: string, exceptId: string | null, dir: string): void {
+  if (readLocalConnectors(dir).some((r) => r.id !== exceptId && r.name === name))
+    throw new ConnectorError(`a connector named '${name}' already exists on this daemon`, 409);
+}
+
+function insert(dir: string, name: string, url: URL, config: ConnectorConfig): Connector {
+  assertNameFree(name, null, dir);
+  const row: LocalConnectorRow = { id: newId(), name, url: connectorUrlText(url), transport: 'http', config };
+  writeRows(dir, [...readLocalConnectors(dir), row]);
+  return connectorFromRow(row);
+}
+
+export async function localCreateConnector(
+  subject: string,
+  project: string,
+  input: ConnectorInput,
+  dir = agentsDir(),
+): Promise<Connector> {
+  ownedRows(subject, project, dir);
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const auth = connectorAuth(input.header, input.value);
+  const verified = stamp(await verifyRemoteMcp(url, auth));
+  return insert(dir, name, url, {
+    auth,
+    createdAt: new Date().toISOString(),
+    verified,
+    oauth: await oauthCapable(url, auth),
+  });
+}
+
+export async function localCreatePendingConnector(
+  subject: string,
+  project: string,
+  input: { name: unknown; url: unknown },
+  dir = agentsDir(),
+): Promise<Connector> {
+  ownedRows(subject, project, dir);
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  return Promise.resolve(
+    insert(dir, name, url, { auth: { kind: 'none' }, createdAt: new Date().toISOString(), verified: UNVERIFIED, oauth: true }),
+  );
+}
+
+export async function localReconnectConnector(
+  subject: string,
+  id: string,
+  auth: OAuthAuth,
+  dir = agentsDir(),
+): Promise<Connector> {
+  const row = rowOrThrow(subject, id, dir);
+  const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth));
+  return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+}
+
+export async function localDisconnectConnector(subject: string, id: string, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(subject, id, dir);
+  if (row.config.auth.kind !== 'oauth') throw new ConnectorError('that connector is not signed in', 400);
+  return Promise.resolve(replace(dir, { ...row, config: { ...row.config, auth: { kind: 'none' }, oauth: true } }));
+}
+
+async function freshAuth(auth: ConnectorAuth, resource: string): Promise<ConnectorAuth> {
+  if (auth.kind !== 'oauth' || !oauthExpired(auth)) return auth;
+  return refreshOAuth(auth, resource);
+}
+
+export async function localVerifyConnector(subject: string, id: string, dir = agentsDir()): Promise<ConnectorCheck> {
+  const row = rowOrThrow(subject, id, dir);
+  try {
+    const url = parseConnectorUrl(row.url);
+    const auth = await freshAuth(row.config.auth, url.toString());
+    const verified = stamp(await verifyRemoteMcp(url, auth));
+    const oauth = row.config.oauth || (await oauthCapable(url, auth));
+    replace(dir, { ...row, config: { ...row.config, auth, verified, oauth } });
+    return { id: row.id, name: row.name, ok: true, verified };
+  } catch (err) {
+    if (!(err instanceof ConnectorVerifyError)) throw err;
+    return { id: row.id, name: row.name, ok: false, reason: err.message };
+  }
+}
+
+export async function localRenameConnector(subject: string, id: string, raw: string, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(raw);
+  const row = rowOrThrow(subject, id, dir);
+  assertNameFree(name, id, dir);
+  return Promise.resolve(replace(dir, { ...row, name }));
+}
+
+export async function localDeleteConnector(subject: string, id: string, dir = agentsDir()): Promise<DeletedConnector> {
+  const row = rowOrThrow(subject, id, dir);
+  writeRows(dir, readLocalConnectors(dir).filter((r) => r.id !== id));
+  return Promise.resolve({ id: row.id, name: row.name });
+}
+
+const byIds = (ids: string[], dir: string): LocalConnectorRow[] =>
+  readLocalConnectors(dir).filter((r) => ids.includes(r.id));
+
+export async function localConnectorNamesByIds(ids: string[], dir = agentsDir()): Promise<{ id: string; name: string }[]> {
+  return Promise.resolve(byIds(ids, dir).map((r) => ({ id: r.id, name: r.name })));
+}
+
+const inflight = new Map<string, Promise<OAuthAuth>>();
+
+function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Promise<OAuthAuth> {
+  const running = inflight.get(row.id);
+  if (running !== undefined) return running;
+  const job = refreshOAuth(auth, parseConnectorUrl(row.url).toString())
+    .then((fresh) => {
+      replace(dir, { ...row, config: { ...row.config, auth: fresh } });
+      return fresh;
+    })
+    .finally(() => {
+      inflight.delete(row.id);
+    });
+  inflight.set(row.id, job);
+  return job;
+}
+
+async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boolean, dir: string): Promise<RelayTarget> {
+  if (!force && !oauthExpired(auth)) return { kind: 'ok', url: row.url, headers: bearerHeaders(auth.accessToken) };
+  try {
+    const fresh = await refreshOnce(row, auth, dir);
+    return { kind: 'ok', url: row.url, headers: bearerHeaders(fresh.accessToken) };
+  } catch (err) {
+    log.warn({ id: row.id, err: errMsg(err) }, 'local relay: token refresh failed');
+    return unrefreshedTarget(row.url, auth, force);
+  }
+}
+
+export async function localRelayTarget(
+  connectorId: string,
+  force: boolean,
+  dir = agentsDir(),
+): Promise<RelayTarget> {
+  const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
+  if (row === undefined) return { kind: 'missing' };
+  parseConnectorUrl(row.url);
+  const auth = row.config.auth;
+  if (auth.kind === 'oauth') return oauthTarget(row, auth, force, dir);
+  return fixedTarget(row.url, auth, force);
+}

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

@@ -0,0 +1,98 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+export const TOOL_KINDS = ['read', 'write'] as const;
+
+export type ToolKind = (typeof TOOL_KINDS)[number];
+
+export interface ToolInfo {
+  name: string;
+  title: string;
+  description: string;
+  kind: ToolKind;
+  annotated: boolean;
+  destructive: boolean;
+  idempotent: boolean;
+  openWorld: boolean;
+}
+
+const MAX_TOOLS = 500;
+const MAX_DESCRIPTION = 400;
+
+const str = (value: unknown, cap: number): string =>
+  typeof value === 'string' ? value.slice(0, cap) : '';
+
+const flag = (value: unknown, fallback: boolean): boolean =>
+  typeof value === 'boolean' ? value : fallback;
+
+export function classifyTool(annotations: unknown): ToolKind {
+  return isRecord(annotations) && annotations.readOnlyHint === true
+    ? 'read'
+    : 'write';
+}
+
+export function isDestructive(annotations: unknown): boolean {
+  if (!isRecord(annotations)) return true;
+  if (annotations.readOnlyHint === true) return false;
+  return annotations.destructiveHint !== false;
+}
+
+export function toToolInfo(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : undefined;
+  return {
+    name,
+    title: str(annotations?.title ?? raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: classifyTool(raw.annotations),
+    annotated: annotations !== undefined,
+    destructive: isDestructive(raw.annotations),
+    idempotent: flag(annotations?.idempotentHint, false),
+    openWorld: flag(annotations?.openWorldHint, true),
+  };
+}
+
+export function toToolList(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toToolInfo(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+function toStoredTool(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  return {
+    name,
+    title: str(raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: raw.kind === 'read' ? 'read' : 'write',
+    annotated: raw.annotated === true,
+    destructive: raw.destructive !== false,
+    idempotent: raw.idempotent === true,
+    openWorld: raw.openWorld !== false,
+  };
+}
+
+export function readStoredTools(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toStoredTool(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+export function countByKind(tools: ToolInfo[]): Record<ToolKind, number> {
+  const counts: Record<ToolKind, number> = { read: 0, write: 0 };
+  for (const tool of tools) counts[tool.kind] += 1;
+  return counts;
+}