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

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

@@ -0,0 +1,111 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { InboundRelay } from '../channels/inbound.js';
+import { cancelPrompt, holdPrompt, type Behavior } from '../approvals/pending.js';
+import { ownerLine, type OwnerLine } from '../approvals/owner-line.js';
+import { approversForLine, lineReceives, mayApprove } from '../agents/map.js';
+import { sharedCalls } from '../voice/shared.js';
+import { metroCall } from './ctx.js';
+import { promptBody } from './permission-prompt.js';
+import { permissionCall } from './call-permission.js';
+
+const PermissionRequestSchema = z.object({
+  method: z.literal('notifications/claude/channel/permission_request'),
+  params: z.object({
+    request_id: z.string(),
+    tool_name: z.string(),
+    description: z.string(),
+    input_preview: z.string(),
+    call: z.unknown().optional(),
+  }),
+});
+
+type PermissionRequest = z.infer<typeof PermissionRequestSchema>;
+
+const trainOf = (line: string): string => line.split('/')[2] ?? '';
+
+export async function metroSend(line: string, text: string): Promise<void> {
+  await metroCall(trainOf(line), 'send', { line, text });
+}
+
+export interface PermissionRelayDeps {
+  mcp: Server;
+  relay: InboundRelay;
+  inScope: (line: string) => boolean;
+  live: () => boolean;
+  log: (...a: unknown[]) => void;
+}
+
+export type PromptLineDeps = Pick<PermissionRelayDeps, 'relay' | 'inScope' | 'live' | 'log'>;
+
+const callChat = (deps: PromptLineDeps): string | undefined => {
+  const route = sharedCalls.snapshot();
+  return route !== null && deps.inScope(route.line) ? route.line : undefined;
+};
+
+const ownerChat = (deps: PromptLineDeps, owner: OwnerLine | undefined): string | undefined =>
+  owner !== undefined && mayApprove(owner.line, owner.from) && deps.inScope(owner.line) && lineReceives(owner.line) ? owner.line : undefined;
+
+export function relayLine(deps: PromptLineDeps, requestId: string, callLine?: string): string | undefined {
+  if (!deps.live()) {
+    deps.log('permission_request: live events are off, so no chat answer can arrive; held for the page only', requestId);
+    return undefined;
+  }
+  const line = callLine ?? callChat(deps) ?? ownerChat(deps, ownerLine()) ?? deps.relay.knownLine;
+  if (!line) {
+    deps.log('permission_request: no known line, held for the page only', requestId);
+    return undefined;
+  }
+  if (!deps.inScope(line)) {
+    deps.log('permission_request: known line is outside the agent scope, held for the page only', requestId);
+    return undefined;
+  }
+  if (!lineReceives(line)) {
+    deps.log('permission_request: the known chat does not receive messages now, so no answer can arrive; held for the page only', requestId);
+    return undefined;
+  }
+  if (approversForLine(line).length === 0) {
+    deps.log('permission_request: nobody on that chat may approve, held for the page only', requestId);
+    return undefined;
+  }
+  return line;
+}
+
+export function registerPermissionRelay(deps: PermissionRelayDeps): void {
+  const { mcp, log } = deps;
+  mcp.setNotificationHandler(z.object({ method: z.literal('notifications/metro/permission_cancel'), params: z.object({ request_id: z.string() }) }), (notice) => {
+    cancelPrompt(notice.params.request_id, mcp);
+  });
+  const answer = (requestId: string) => async (behavior: Behavior): Promise<void> => {
+    await mcp.notification({ method: 'notifications/claude/channel/permission', params: { request_id: requestId, behavior } });
+  };
+  mcp.setNotificationHandler(PermissionRequestSchema as never, async (n: PermissionRequest) => {
+    const { params } = n;
+    const call = permissionCall(params, deps.inScope);
+    if (call === null) {
+      await answer(params.request_id)('deny');
+      return;
+    }
+    const line = relayLine(deps, params.request_id, call?.route.line);
+    holdPrompt(
+      {
+        requestId: params.request_id,
+        tool: params.tool_name,
+        description: params.description,
+        preview: params.input_preview,
+        line,
+        at: Date.now(),
+        ...(call === undefined ? {} : { call }),
+      },
+      mcp,
+      answer(params.request_id),
+      line === undefined ? undefined : async (text) => metroSend(line, text),
+    );
+    if (line === undefined) return;
+    try {
+      await metroSend(line, promptBody(params));
+    } catch (e) {
+      log('relay send failed', e);
+    }
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/policy-gate.ts

@@ -0,0 +1,88 @@
+import { str } from '@metro-labs/core/str';
+import type { ToolResult } from '@metro-labs/core/stations/types';
+import { accountFromLine, knownAccounts } from '../agents/map.js';
+import { policyFor, storedPolicy, strictest, type Access, type PolicyTarget } from '../policy/policy.js';
+import { errResult } from './ctx.js';
+import { NEEDS_APPROVAL, takeGrant } from '../approvals/pending.js';
+import { profileScopeLine } from './profile-lookup.js';
+import { stationOfAccount } from './read-tool.js';
+import { stationForTool, toolGroupOf } from './tool-catalog.js';
+import { CONNECTOR_TOOLS } from '../mcp-server/connector-tools.js';
+
+type ChannelTarget = Extract<PolicyTarget, { kind: 'channel' }>;
+
+export const UNGATED = new Set<string>(['list_accounts', 'create_upload', ...CONNECTOR_TOOLS]);
+
+function fromLine(line: string, override = ''): ChannelTarget[] {
+  const acct = accountFromLine(line);
+  return acct === undefined ? [] : [{ kind: 'channel', station: acct.station, account: override || acct.accountId }];
+}
+
+function channelTargets(name: string, a: Record<string, unknown>): ChannelTarget[] {
+  if (UNGATED.has(name)) return [];
+  if (name === 'get_profile') {
+    const line = profileScopeLine(a);
+    return line === undefined ? [] : fromLine(line, undefined);
+  }
+  const account = str(a.account);
+  if (name === 'list_channels') return accountTargets(name, { account });
+  const line = str(a.line);
+  if (line) return fromLine(line, name === 'list_members' ? undefined : account);
+  return accountTargets(name, a);
+}
+
+function accountTargets(name: string, a: Record<string, unknown>): ChannelTarget[] {
+  const account = str(a.account);
+  const station = stationForTool(name, a) ?? (account ? stationOfAccount(account) : undefined);
+  if (station === undefined) return [];
+  if (account) return [{ kind: 'channel', station, account }];
+  return knownAccounts()
+    .filter((k) => k.station === station)
+    .map((k) => ({ kind: 'channel', station, account: k.id }));
+}
+
+export interface PolicyVerdict {
+  access: Access;
+  target?: ChannelTarget;
+}
+
+export function channelDecision(name: string, a: Record<string, unknown>): PolicyVerdict {
+  const tool = { name, group: toolGroupOf(name) };
+  let verdict: PolicyVerdict = { access: 'allow' };
+  for (const target of channelTargets(name, a)) {
+    const access = policyFor(target, tool);
+    if (strictest([verdict.access, access]) !== verdict.access) verdict = { access, target };
+  }
+  return verdict;
+}
+
+const isChannelTool = (name: string) => (tool: string): boolean => tool === `mcp__metro__${name}`;
+
+export function policyGate(name: string, a: Record<string, unknown>): ToolResult | undefined {
+  const { access, target } = channelDecision(name, a);
+  if (access === 'allow' || target === undefined) return undefined;
+  if (access === 'deny') return errResult(`Blocked by the owner's policy for ${target.station} (${name}).`);
+  return takeGrant(isChannelTool(name), a) ? undefined : errResult(NEEDS_APPROVAL(target.station, name));
+}
+
+interface EffectivePolicy {
+  read: Access;
+  write: Access;
+  tools: Record<string, Access>;
+}
+
+function effectivePolicy(target: ChannelTarget): EffectivePolicy {
+  const stored = storedPolicy(target);
+  return { read: stored?.read ?? 'allow', write: stored?.write ?? 'allow', tools: { ...stored?.tools } };
+}
+
+export function withEffectivePolicy(byStation: Record<string, unknown[]>): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [station, rows] of Object.entries(byStation))
+    out[station] = rows.map((row) => {
+      if (typeof row !== 'object' || row === null || Array.isArray(row)) return row;
+      const id = (row as { id?: unknown }).id;
+      return typeof id === 'string' ? { ...row, policy: effectivePolicy({ kind: 'channel', station, account: id }) } : row;
+    });
+  return out;
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/policy-snapshot.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { agentsDir } from '../agents/files.js';
+import { knownAccounts } from '../agents/map.js';
+import { onPoliciesChanged, storedPolicies, type ToolPolicy } from '../policy/policy.js';
+import { UNGATED } from './policy-gate.js';
+import { stationToolOwners, TOOL_DEFS, toolGroupOf } from './tool-catalog.js';
+
+interface PolicySnapshot {
+  version: 1;
+  tools: Record<string, ToolGroup>;
+  owners: Record<string, string>;
+  ungated: string[];
+  accounts: Record<string, ToolPolicy>;
+  stations: Record<string, string[]>;
+}
+
+const FILE = 'policy.json';
+
+export const policySnapshotPath = (dir = agentsDir()): string => join(dir, FILE);
+
+function policySnapshot(): PolicySnapshot {
+  const accounts: Record<string, ToolPolicy> = {};
+  for (const { target, policy } of storedPolicies())
+    if (target.kind === 'channel') accounts[`${target.station}/${target.account}`] = policy;
+  const stations: Record<string, string[]> = {};
+  for (const known of knownAccounts()) (stations[known.station] ??= []).push(known.id);
+  return {
+    version: 1,
+    tools: Object.fromEntries(TOOL_DEFS.map((def) => [def.name, toolGroupOf(def.name)])),
+    owners: stationToolOwners(),
+    ungated: [...UNGATED],
+    accounts,
+    stations,
+  };
+}
+
+function current(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+function writePolicySnapshot(path = policySnapshotPath()): void {
+  const text = `${JSON.stringify(policySnapshot(), null, 2)}\n`;
+  if (current(path) === text) return;
+  try {
+    writeSecure(path, text);
+    log.info({ path }, 'policy: snapshot for the guard hook written');
+  } catch (err) {
+    log.warn({ path, err: errMsg(err) }, 'policy: the snapshot for the guard hook could not be written');
+  }
+}
+
+export function watchPolicySnapshot(): () => void {
+  writePolicySnapshot();
+  return onPoliciesChanged(() => {
+    writePolicySnapshot();
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/profile-lookup.ts

@@ -0,0 +1,60 @@
+import type { ToolDef } from './tool-def.js';
+import { Line } from '@metro-labs/core/lines';
+import type { Station, ToolResult } from '@metro-labs/core/stations/types';
+import { str } from '@metro-labs/core/str';
+import { stationByName } from '../stations/registry.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+
+export const GET_PROFILE_TOOL: ToolDef = {
+  name: 'get_profile',
+  group: 'read',
+  description:
+    'Who is this person? Give the `from` attribute of one of their messages verbatim ' +
+    '(`metro://<station>/<account>/user/<id>`) and get what their network says about them: ' +
+    '{id, name, display_name, about, avatar, address}. XMTP answers the Basename ' +
+    '(<label>.stage.base.eth), its name, description and avatar records, and the wallet address; ' +
+    'WhatsApp the phone number, the name they last used, the about line and the picture; Telegram the handle, the name and the bio; Discord ' +
+    'the username, the global name and the avatar. Fields the network does not have are absent. ' +
+    'The answer is cached for ten minutes, so ask when you want to know someone, not on every message.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      from: { type: 'string', description: 'The `from` of a message, exactly as received.' },
+    },
+    required: ['from'],
+  },
+};
+
+export interface ProfileTarget {
+  station: Station;
+  account: string;
+  user: string;
+}
+
+export function profileTarget(a: Record<string, unknown>): ProfileTarget | { refused: string } {
+  const from = str(a.from);
+  if (!from) return { refused: 'get_profile requires `from`' };
+  const parsed = Line.parse(from);
+  const at = parsed?.path.indexOf('user') ?? -1;
+  if (parsed === null || at < 1 || at + 1 >= parsed.path.length) return { refused: `${from} is not a person: expected metro://<station>/<account>/user/<id>` };
+  const station = stationByName(parsed.station);
+  if (!station) return { refused: `no station named ${parsed.station}` };
+  if (station.readsProfiles !== true) return { refused: `${station.name} has no profile metro can read` };
+  return { station, account: parsed.path.slice(0, at).join('/'), user: parsed.path.slice(at + 1).join('/') };
+}
+
+export const profileScopeLine = (a: Record<string, unknown>): string | undefined => {
+  const target = profileTarget(a);
+  return 'refused' in target ? undefined : `metro://${target.station.name}/${target.account}/user/${target.user}`;
+};
+
+export async function dispatchGetProfile(a: Record<string, unknown>): Promise<ToolResult> {
+  const target = profileTarget(a);
+  if ('refused' in target) return errResult(target.refused);
+  try {
+    const { result } = await makeCtx(target.station.name).call('profile', { account: target.account, user: target.user });
+    return okJson(result);
+  } catch (e) {
+    return toErr('get_profile', e);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/profile-tool.ts

@@ -0,0 +1,96 @@
+import type { ToolDef } from './tool-def.js';
+import type { CanonicalAttachment, Station, ToolResult } from '@metro-labs/core/stations/types';
+import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
+import { str } from '@metro-labs/core/str';
+import { STATIONS, stationByName } from '../stations/registry.js';
+import { cleanupAttachments, resolveAttachments, type ResolvedAttachment } from '../stations/attach-resolve.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+
+const SOURCE = { type: 'string' };
+
+export const SET_PROFILE_TOOL: ToolDef = {
+  name: 'set_profile',
+  group: 'write',
+  description:
+    'Change how one of your accounts presents itself on its network: the display name, the bio ' +
+    '(about line) and the avatar. Args: station (required), account? (which account of that station; ' +
+    'needed only when you have several), name?, bio?, avatar? (an image given like an attachment: ' +
+    'exactly one of upload, url, path, data, plus mime and name). At least one of name, bio, avatar. ' +
+    'Each station takes what its network allows (`list_accounts` reports the fields under ' +
+    '`profiles`); a field the station cannot set is refused by name, never dropped. Discord changes ' +
+    'the bot username and app description (Discord allows two username changes an hour); Telegram ' +
+    'bots set their name, description and photo; a Telegram user account sets its first name, bio ' +
+    '(70 chars) and photo; WhatsApp sets the profile name, about and picture; XMTP writes the ' +
+    'name, description and avatar records of the account\'s <label>.stage.base.eth name on Base, ' +
+    'so it needs a name first (claimed on the channel page, never by you). Visible to everyone ' +
+    'who talks to the account, so do it when asked, not on your own. Returns {account, applied}.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      station: { type: 'string', description: 'discord-bot | telegram-bot | telegram | whatsapp | xmtp' },
+      account: { type: 'string', description: 'The account id on that station, from list_accounts.' },
+      name: { type: 'string', description: 'The display name.' },
+      bio: { type: 'string', description: 'The bio or about line.' },
+      avatar: {
+        type: 'object',
+        description: 'The new picture, as an attachment source.',
+        properties: { upload: SOURCE, url: SOURCE, path: SOURCE, data: SOURCE, mime: SOURCE, name: SOURCE },
+      },
+    },
+    required: ['station'],
+  },
+};
+
+export const profileCapabilities = (): Record<string, ProfileField[]> => {
+  const out: Record<string, ProfileField[]> = {};
+  for (const s of STATIONS) if (s.profileFields !== undefined) out[s.name] = [...s.profileFields];
+  return out;
+};
+
+const asked = (a: Record<string, unknown>): ProfileField[] => PROFILE_FIELDS.filter((f) => a[f] !== undefined);
+
+type Target = { station: Station } | { refused: string };
+
+function targetOf(a: Record<string, unknown>): Target {
+  const name = str(a.station);
+  if (!name) return { refused: 'set_profile requires `station`' };
+  const station = stationByName(name);
+  if (!station) return { refused: `no station named ${name}` };
+  const fields = station.profileFields;
+  if (fields === undefined) return { refused: `${name} accounts have no profile metro can set` };
+  const wanted = asked(a);
+  if (wanted.length === 0) return { refused: 'set_profile needs at least one of name, bio, avatar' };
+  const refused = wanted.filter((f) => !fields.has(f));
+  if (refused.length > 0) return { refused: `${name} cannot set ${refused.join(', ')}; it takes ${[...fields].join(', ')}` };
+  return { station };
+}
+
+function trainArgs(a: Record<string, unknown>, picture: ResolvedAttachment | undefined): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  if (typeof a.account === 'string') args.account = a.account;
+  if (typeof a.name === 'string') args.name = a.name;
+  if (typeof a.bio === 'string') args.bio = a.bio;
+  if (picture !== undefined) args.avatar = { path: picture.path, mime: picture.mime, name: picture.name };
+  return args;
+}
+
+export async function dispatchSetProfile(a: Record<string, unknown>): Promise<ToolResult> {
+  const target = targetOf(a);
+  if ('refused' in target) return errResult(target.refused);
+  const avatar = a.avatar === undefined ? [] : [a.avatar as CanonicalAttachment];
+  let resolved: ResolvedAttachment[];
+  try {
+    resolved = await resolveAttachments(avatar, { allowed: allowedAgents(currentIdentity()) });
+  } catch (e) {
+    return toErr('set_profile', e);
+  }
+  try {
+    const { result } = await makeCtx(target.station.name).call('set_profile', trainArgs(a, resolved[0]));
+    return okJson(result);
+  } catch (e) {
+    return toErr('set_profile', e);
+  } finally {
+    await cleanupAttachments(resolved);
+  }
+}

package/runtime/node_modules/@metro-labs/{mcp → daemon}/src/mcp/raw-get-stream.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
 import type {
   StreamableHTTPServerTransport,
   EventId,
@@ -49,12 +50,24 @@ export const headerValue = (
   return typeof raw === 'string' ? raw : undefined;
 };
 
+export interface GetStreamDiagnostic {
+  tag: string;
+  openedAt: string;
+  attachedAt: string | null;
+  closedAt: string | null;
+  ownsMapping: boolean;
+}
+
 export interface RawGetSink {
   closed: boolean;
   attach: (transport: StreamableHTTPServerTransport) => void;
   close: () => void;
+  diagnostics: () => GetStreamDiagnostic;
 }
 
+const streamEnded = (sink: RawGetSink, res: ServerResponse): boolean =>
+  sink.closed || res.destroyed || res.writableEnded;
+
 export interface ValidateResult {
   ok: boolean;
   status?: number;
@@ -93,12 +106,11 @@ export interface ServeOpts {
   res: ServerResponse;
   log: (...a: unknown[]) => void;
   registerSink: (sink: RawGetSink | undefined) => void;
+  previous?: () => RawGetSink | undefined;
 }
 
-export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
-  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+function primeStream(transport: StreamableHTTPServerTransport, res: ServerResponse): void {
   const sessionId = web(transport)?.sessionId;
-
   res.writeHead(200, {
     'content-type': 'text/event-stream',
     'cache-control': 'no-cache, no-transform',
@@ -109,15 +121,29 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
   res.flushHeaders?.();
   res.write(RETRY_DIRECTIVE);
   res.write(COMMENT);
+}
+
+export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
+  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+  primeStream(transport, res);
 
   let active = transport;
+  let entry: StreamEntry | undefined;
+  const tag = randomUUID();
+  const openedAt = new Date().toISOString();
+  let attachedAt: string | null = null;
+  let closedAt: string | null = null;
   const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
   const closeStream = (): void => {
     if (sink.closed) return;
     sink.closed = true;
+    closedAt = new Date().toISOString();
     if (timers.keepalive) clearInterval(timers.keepalive);
-    web(active)?._streamMapping?.delete(STANDALONE_STREAM_ID);
-    registerSink(undefined);
+    const mapping = web(active)?._streamMapping;
+    if (entry !== undefined && mapping?.get(STANDALONE_STREAM_ID) === entry) {
+      mapping.delete(STANDALONE_STREAM_ID);
+      registerSink(undefined);
+    }
     try {
       res.end();
     } catch {
@@ -128,11 +154,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     closed: false,
     attach: (next: StreamableHTTPServerTransport): void => {
       active = next;
-      const entry: StreamEntry = {
+      entry = {
         controller: {
           enqueue: (chunk: Uint8Array): void => {
-            if (sink.closed) return;
-            if (res.destroyed || res.writableEnded) {
+            if (streamEnded(sink, res)) {
               closeStream();
               return;
             }
@@ -143,10 +168,22 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
         cleanup: closeStream,
       };
       web(next)?._streamMapping?.set(STANDALONE_STREAM_ID, entry);
+      attachedAt = new Date().toISOString();
     },
     close: closeStream,
+    diagnostics: () => ({
+      tag,
+      openedAt,
+      attachedAt,
+      closedAt,
+      ownsMapping: entry !== undefined && web(active)?._streamMapping?.get(STANDALONE_STREAM_ID) === entry,
+    }),
   };
 
+  res.on('close', closeStream);
+  res.on('error', closeStream);
+  req.on('close', closeStream);
+
   const lastEventId = headerValue(req, 'last-event-id');
   if (lastEventId) {
     await eventStore.replayEventsAfter(lastEventId, {
@@ -168,12 +205,17 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     });
   }
 
+  if (streamEnded(sink, res)) {
+    closeStream();
+    return;
+  }
+  opts.previous?.()?.close();
   sink.attach(transport);
   registerSink(sink);
+  if (sink.closed) return;
 
   timers.keepalive = setInterval(() => {
-    if (sink.closed) return;
-    if (res.destroyed || res.writableEnded) {
+    if (streamEnded(sink, res)) {
       closeStream();
       return;
     }
@@ -185,14 +227,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     }
   }, KEEPALIVE_MS);
   timers.keepalive.unref?.();
-
-  res.on('close', closeStream);
-  res.on('error', closeStream);
-  req.on('close', closeStream);
 }
 
 export interface ChannelGetOpts extends ServeOpts {
-  previous: RawGetSink | undefined;
+  previous: () => RawGetSink | undefined;
 }
 
 export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
@@ -201,7 +239,7 @@ export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
     opts.res.writeHead(check.status ?? 400).end(check.message ?? 'bad request');
     return false;
   }
-  if (opts.previous && !opts.previous.closed) opts.previous.close();
+  opts.previous()?.close();
   await serveStandaloneGet(opts);
   return true;
 }

package/runtime/node_modules/@metro-labs/daemon/src/mcp/read-tool.ts

@@ -0,0 +1,87 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { str } from '@metro-labs/core/str';
+import type { ReadFilter, Station, ToolResult } from '@metro-labs/core/stations/types';
+import { agentIdForAccount, accountFromLine, knownAccounts } from '../agents/map.js';
+import { attachmentUrl } from '../files/attach-serve.js';
+import { stationByName } from '../stations/registry.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { agentUser } from '../agent-user/user.js';
+
+const FILTERS: readonly (readonly [string, ReadFilter, string])[] = [
+  ['query', 'query', 'query'],
+  ['from', 'from', 'from'],
+  ['until', 'until', 'until'],
+  ['unread_only', 'unread_only', 'unreadOnly'],
+  ['message_id', 'message_id', 'messageId'],
+];
+
+const given = (v: unknown): boolean => v !== undefined && v !== null && v !== '' && v !== false;
+
+export function stationOfAccount(account: string): string | undefined {
+  const hits = knownAccounts().filter((a) => a.id === account);
+  return hits.length === 1 ? hits[0]?.station : undefined;
+}
+
+function readArgs(a: Record<string, unknown>): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  if (str(a.line)) args.line = str(a.line);
+  if (str(a.account)) args.account = str(a.account);
+  if (typeof a.limit === 'number') args.limit = a.limit;
+  if (a.before) args.before = str(a.before);
+  if (a.since) args.since = str(a.since);
+  for (const [snake, , camel] of FILTERS)
+    if (given(a[snake])) args[camel] = typeof a[snake] === 'boolean' ? a[snake] : str(a[snake]);
+  return args;
+}
+
+function ignoredFilters(station: Station, a: Record<string, unknown>): string[] {
+  const supported = station.readFilters ?? new Set<ReadFilter>();
+  return FILTERS.filter(([snake, filter]) => given(a[snake]) && !supported.has(filter)).map(([snake]) => snake);
+}
+
+function withUrls(result: unknown, agentId: string | undefined): unknown {
+  if (agentId === undefined || !isRecord(result) || !isRecord(result.message)) return result;
+  const files = result.message.attachments;
+  if (!Array.isArray(files)) return result;
+  const attachments = files.map((f: unknown) => {
+    if (!isRecord(f) || typeof f.local_path !== 'string') return f;
+    const url = attachmentUrl(f.local_path, agentId);
+    const shown = agentUser() === null ? f : Object.fromEntries(Object.entries(f).filter(([key]) => key !== 'local_path'));
+    return url === null ? shown : { ...shown, url };
+  });
+  return { ...result, message: { ...result.message, attachments } };
+}
+
+function answer(result: unknown, ignored: string[]): unknown {
+  if (ignored.length === 0) return result;
+  return isRecord(result) && !Array.isArray(result) ? { ...result, ignored } : { result, ignored };
+}
+
+function accountOfCall(station: Station, a: Record<string, unknown>, result: unknown): string | undefined {
+  const named = str(a.account) || (isRecord(result) ? str(result.account) : '');
+  const account = named || accountFromLine(str(a.line))?.accountId;
+  return account === undefined ? undefined : agentIdForAccount(station.name, account);
+}
+
+export async function runRead(station: Station, a: Record<string, unknown>): Promise<ToolResult> {
+  try {
+    const response = await makeCtx(station.name).call('read', readArgs(a));
+    const result = withUrls(response.result, accountOfCall(station, a, response.result));
+    return okJson(answer(result, ignoredFilters(station, a)));
+  } catch (e) {
+    return toErr('read', e);
+  }
+}
+
+export function linelessRead(a: Record<string, unknown>): Promise<ToolResult> | ToolResult {
+  const account = str(a.account);
+  if (!account) return errResult('read requires `line` or `account`');
+  const name = stationOfAccount(account);
+  const station = name === undefined ? undefined : stationByName(name);
+  if (station === undefined) return errResult(`no account ${account} on this box; list_accounts names them`);
+  if (!station.messageVerbs.has('read'))
+    return errResult(`${station.name} does not support read; it supports ${[...station.messageVerbs].join(', ')}.`);
+  if (!station.readFilters?.has('account'))
+    return errResult(`${station.name} reads one conversation at a time; give a \`line\` instead of an account`);
+  return runRead(station, a);
+}