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

package/runtime/node_modules/@metro-labs/daemon/src/gateway/provider-models.ts

@@ -0,0 +1,65 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { GatewayError } from './forward.js';
+import type { AnthropicSettings, BedrockSettings } from './model-config.js';
+
+export const ANTHROPIC_API = 'https://api.anthropic.com';
+const ANTHROPIC_VERSION = '2023-06-01';
+const LIST_MAX = 1000;
+
+export interface ProviderModel {
+  id: string;
+  name: string;
+}
+
+export const KNOWN_CLAUDE: ProviderModel[] = [
+  { id: 'claude-fable-5-1', name: 'Claude Fable 5.1' },
+  { id: 'claude-opus-5', name: 'Claude Opus 5' },
+  { id: 'claude-sonnet-5', name: 'Claude Sonnet 5' },
+  { id: 'claude-haiku-4-5-20251001', name: 'Claude Haiku 4.5' },
+];
+
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+export async function anthropicModels(settings: AnthropicSettings, base = ANTHROPIC_API, fetchImpl: typeof fetch = fetch): Promise<ProviderModel[]> {
+  if (settings.apiKey === '') return KNOWN_CLAUDE;
+  const res = await fetchImpl(`${base}/v1/models?limit=${String(LIST_MAX)}`, {
+    headers: { 'x-api-key': settings.apiKey, 'anthropic-version': ANTHROPIC_VERSION, accept: 'application/json' },
+    redirect: 'manual',
+  });
+  if (!res.ok) throw new GatewayError(res.status, 'api_error', `Anthropic would not list its models with the stored key (${String(res.status)})`);
+  const body: unknown = await res.json();
+  const data = isRecord(body) && Array.isArray(body.data) ? body.data : null;
+  if (data === null) throw new GatewayError(502, 'api_error', 'Anthropic answered with no model list');
+  return data
+    .flatMap((entry) => (isRecord(entry) && str(entry.id) !== '' ? [{ id: str(entry.id), name: str(entry.display_name) || str(entry.id) }] : []))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export const bedrockControlBase = (region: string): string => `https://bedrock.${region}.amazonaws.com`;
+
+export async function bedrockModels(settings: BedrockSettings, base?: string, fetchImpl: typeof fetch = fetch): Promise<ProviderModel[]> {
+  if (settings.region === '') throw new GatewayError(400, 'invalid_request_error', 'Bedrock needs a region before its models can be listed');
+  if (settings.apiKey === '') throw new GatewayError(400, 'invalid_request_error', 'Bedrock needs an API key before its models can be listed');
+  const res = await fetchImpl(`${base ?? bedrockControlBase(settings.region)}/inference-profiles?maxResults=${String(LIST_MAX)}`, {
+    headers: { authorization: `Bearer ${settings.apiKey}`, accept: 'application/json' },
+    redirect: 'manual',
+  });
+  if (!res.ok)
+    throw new GatewayError(
+      res.status,
+      'api_error',
+      `Bedrock would not list its inference profiles (${String(res.status)}); the stored key may cover the runtime only, so type the model id instead`,
+    );
+  const body: unknown = await res.json();
+  const list = isRecord(body) && Array.isArray(body.inferenceProfileSummaries) ? body.inferenceProfileSummaries : null;
+  if (list === null) throw new GatewayError(502, 'api_error', 'Bedrock answered with no inference profile list');
+  return list
+    .flatMap((entry) => {
+      if (!isRecord(entry)) return [];
+      const id = str(entry.inferenceProfileId);
+      const status = str(entry.status);
+      if (id === '' || !id.includes('anthropic') || (status !== '' && status !== 'ACTIVE')) return [];
+      return [{ id, name: str(entry.inferenceProfileName) || id }];
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/served.ts

@@ -0,0 +1,17 @@
+export interface Served {
+  provider: string;
+  model: string;
+  at: string;
+}
+
+let last: Served | null = null;
+
+export const noteServed = (served: Served): void => {
+  last = served;
+};
+
+export const lastServed = (): Served | null => last;
+
+export const forgetServed = (): void => {
+  last = null;
+};

package/runtime/node_modules/@metro-labs/daemon/src/gateway/usage.ts

@@ -0,0 +1,242 @@
+export type UsageProvider = 'anthropic' | 'codex' | 'openrouter' | 'bedrock' | 'gemini';
+
+export interface UsageWindow {
+  label: string;
+  used: number | null;
+  resetAt: string | null;
+  detail: string | null;
+}
+
+export interface Tally {
+  requests: number;
+  input: number;
+  output: number;
+  cached: number;
+  since: string;
+}
+
+export interface ProviderUsage {
+  windows: UsageWindow[];
+  note: string | null;
+  at: string;
+  tally: Tally | null;
+}
+
+type Reported = Omit<ProviderUsage, 'tally'>;
+
+const latest = new Map<UsageProvider, Reported>();
+const tallies = new Map<UsageProvider, Tally>();
+
+export const noteUsage = (provider: UsageProvider, usage: Reported): void => {
+  latest.set(provider, usage);
+};
+
+export function usageSeen(): Partial<Record<UsageProvider, ProviderUsage>> {
+  const out: Partial<Record<UsageProvider, ProviderUsage>> = {};
+  const providers = new Set<UsageProvider>([...latest.keys(), ...tallies.keys()]);
+  for (const provider of providers) {
+    const reported = latest.get(provider);
+    const tally = tallies.get(provider) ?? null;
+    out[provider] = reported === undefined
+      ? { windows: [], note: null, at: tally?.since ?? new Date().toISOString(), tally }
+      : { ...reported, tally };
+  }
+  return out;
+}
+
+export const usageOf = (provider: UsageProvider): Reported | undefined => latest.get(provider);
+
+export const forgetUsage = (): void => {
+  latest.clear();
+  tallies.clear();
+};
+
+export interface Counted {
+  input: number;
+  output: number;
+  cached: number;
+}
+
+export function tallyTokens(provider: UsageProvider, counted: Counted, now = new Date()): void {
+  const so = tallies.get(provider) ?? { requests: 0, input: 0, output: 0, cached: 0, since: now.toISOString() };
+  tallies.set(provider, {
+    requests: so.requests + 1,
+    input: so.input + counted.input,
+    output: so.output + counted.output,
+    cached: so.cached + counted.cached,
+    since: so.since,
+  });
+}
+
+const TOKEN_FIELD = /"(input_tokens|output_tokens|cache_read_input_tokens|cache_creation_input_tokens)"\s*:\s*(\d+)/g;
+
+export class UsageScanner {
+  private carry = '';
+  private readonly max = { input: 0, output: 0, read: 0, creation: 0 };
+  private touched = false;
+
+  constructor(private readonly provider: UsageProvider) {}
+
+  private scan(text: string): void {
+    for (const hit of text.matchAll(TOKEN_FIELD)) {
+      const value = Number(hit[2]);
+      if (!Number.isFinite(value)) continue;
+      this.touched = true;
+      if (hit[1] === 'input_tokens') this.max.input = Math.max(this.max.input, value);
+      else if (hit[1] === 'output_tokens') this.max.output = Math.max(this.max.output, value);
+      else if (hit[1] === 'cache_read_input_tokens') this.max.read = Math.max(this.max.read, value);
+      else this.max.creation = Math.max(this.max.creation, value);
+    }
+  }
+
+  feed(text: string): void {
+    const joined = this.carry + text;
+    const cut = joined.lastIndexOf('\n');
+    if (cut === -1) {
+      this.carry = joined;
+      return;
+    }
+    this.scan(joined.slice(0, cut));
+    this.carry = joined.slice(cut + 1);
+  }
+
+  done(now = new Date()): void {
+    if (this.carry !== '') this.scan(this.carry);
+    this.carry = '';
+    if (!this.touched) return;
+    tallyTokens(this.provider, { input: this.max.input, output: this.max.output, cached: this.max.read + this.max.creation }, now);
+    this.touched = false;
+  }
+}
+
+const clamp = (value: number): number => Math.min(1, Math.max(0, value));
+
+function fraction(raw: string | null): number | null {
+  if (raw === null) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? clamp(value) : null;
+}
+
+const MS_THRESHOLD = 1e12;
+
+function whenFrom(raw: string | null, now: Date, relative = false): string | null {
+  if (raw === null || raw.trim() === '') return null;
+  const numeric = Number(raw);
+  if (Number.isFinite(numeric)) {
+    const absolute = numeric > MS_THRESHOLD ? numeric : numeric * 1000;
+    const ms = relative ? now.getTime() + numeric * 1000 : absolute;
+    return new Date(ms).toISOString();
+  }
+  const parsed = Date.parse(raw);
+  return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+
+const ANTHROPIC_WINDOWS: [string, string][] = [
+  ['5h', '5-hour window'],
+  ['7d', 'Weekly'],
+  ['7d_sonnet', 'Weekly, Sonnet'],
+];
+
+function anthropicUnified(headers: Headers, now: Date): { windows: UsageWindow[]; note: string | null } {
+  const windows: UsageWindow[] = [];
+  let note: string | null = null;
+  for (const [key, label] of ANTHROPIC_WINDOWS) {
+    const used = fraction(headers.get(`anthropic-ratelimit-unified-${key}-utilization`));
+    if (used === null) continue;
+    const status = headers.get(`anthropic-ratelimit-unified-${key}-status`);
+    const blocked = status !== null && status !== 'allowed' ? status.replaceAll('_', ' ') : null;
+    if (blocked !== null && note === null) note = `${label}: ${blocked}`;
+    windows.push({ label, used, resetAt: whenFrom(headers.get(`anthropic-ratelimit-unified-${key}-reset`), now), detail: blocked });
+  }
+  return { windows, note };
+}
+
+function anthropicKeyed(headers: Headers, now: Date): UsageWindow[] {
+  const limit = Number(headers.get('anthropic-ratelimit-tokens-limit'));
+  const remaining = Number(headers.get('anthropic-ratelimit-tokens-remaining'));
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining) || limit <= 0) return [];
+  return [
+    {
+      label: 'Tokens per minute',
+      used: clamp(1 - remaining / limit),
+      resetAt: whenFrom(headers.get('anthropic-ratelimit-tokens-reset'), now),
+      detail: `${remaining.toLocaleString('en-US')} of ${limit.toLocaleString('en-US')} left`,
+    },
+  ];
+}
+
+export function anthropicUsage(headers: Headers, now = new Date()): Reported | null {
+  const unified = anthropicUnified(headers, now);
+  if (unified.windows.length > 0) return { ...unified, at: now.toISOString() };
+  const keyed = anthropicKeyed(headers, now);
+  return keyed.length === 0 ? null : { windows: keyed, note: null, at: now.toISOString() };
+}
+
+const MINUTES_PER_HOUR = 60;
+const MINUTES_PER_DAY = 24 * MINUTES_PER_HOUR;
+const MINUTES_PER_WEEK = 7 * MINUTES_PER_DAY;
+
+export function windowLabel(minutes: number | null): string {
+  if (minutes === null || !Number.isFinite(minutes) || minutes <= 0) return 'Usage window';
+  if (minutes === MINUTES_PER_WEEK) return 'Weekly';
+  if (minutes % MINUTES_PER_DAY === 0) return `${String(minutes / MINUTES_PER_DAY)}-day window`;
+  if (minutes % MINUTES_PER_HOUR === 0) return `${String(minutes / MINUTES_PER_HOUR)}-hour window`;
+  return `${String(minutes)}-minute window`;
+}
+
+function codexWindow(headers: Headers, kind: 'primary' | 'secondary', now: Date): UsageWindow | null {
+  const raw = headers.get(`x-codex-${kind}-used-percent`);
+  if (raw === null) return null;
+  const percent = Number(raw);
+  if (!Number.isFinite(percent)) return null;
+  const used = clamp(percent / 100);
+  const minutes = Number(headers.get(`x-codex-${kind}-window-minutes`) ?? 'none');
+  const absolute = whenFrom(headers.get(`x-codex-${kind}-reset-at`), now);
+  const resetAt = absolute ?? whenFrom(headers.get(`x-codex-${kind}-reset-after-seconds`), now, true);
+  return { label: windowLabel(Number.isFinite(minutes) ? minutes : null), used, resetAt, detail: null };
+}
+
+function codexCredits(headers: Headers): UsageWindow | null {
+  if (headers.get('x-codex-credits-has-credits') !== 'true') return null;
+  const balance = Number(headers.get('x-codex-credits-balance') ?? 'none');
+  if (!Number.isFinite(balance)) return null;
+  return { label: 'Credits', used: null, resetAt: null, detail: `${balance.toLocaleString('en-US')} left` };
+}
+
+export function codexUsage(headers: Headers, now = new Date()): Reported | null {
+  const windows = [codexWindow(headers, 'primary', now), codexWindow(headers, 'secondary', now), codexCredits(headers)].filter(
+    (w): w is UsageWindow => w !== null,
+  );
+  if (windows.length === 0) return null;
+  const reached = headers.get('x-codex-rate-limit-reached-type');
+  return { windows, note: reached === null || reached === '' ? null : reached.replaceAll('_', ' '), at: now.toISOString() };
+}
+
+export function noteUsageHeaders(provider: 'anthropic' | 'codex', headers: Headers, now = new Date()): void {
+  const usage = provider === 'anthropic' ? anthropicUsage(headers, now) : codexUsage(headers, now);
+  if (usage !== null) noteUsage(provider, usage);
+}
+
+const dollars = (value: number): string => `$${value.toFixed(2)}`;
+
+export interface QuotaRow {
+  id: string;
+  remaining: number | null;
+  resetAt: string | null;
+}
+
+export function geminiUsage(rows: QuotaRow[], now = new Date()): Reported | null {
+  const windows: UsageWindow[] = rows
+    .filter((row) => row.remaining !== null)
+    .map((row) => ({ label: row.id, used: clamp(1 - (row.remaining ?? 0)), resetAt: row.resetAt, detail: null }));
+  return windows.length === 0 ? null : { windows, note: null, at: now.toISOString() };
+}
+
+export function openrouterUsage(total: number, spent: number, now = new Date()): Reported {
+  const used = total > 0 ? clamp(spent / total) : null;
+  return {
+    windows: [{ label: 'Credits', used, resetAt: null, detail: `${dollars(spent)} of ${dollars(total)} used` }],
+    note: null,
+    at: now.toISOString(),
+  };
+}

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

@@ -0,0 +1,151 @@
+import { forwardTrainCall } from '../stations/train-call.js';
+import {
+  accountStationNames,
+  stationByName,
+} from '../stations/registry.js';
+import { listEndpoints } from '../net/tunnel.js';
+import { hookUrl, threemaCallbackUrl } from '../stations/attach.js';
+import { accountEnabled, agentIdForAccount, allowlistForAccount, knownAccounts, type KnownAccount } from '../agents/map.js';
+
+const accountId = (acc: unknown): string | undefined => {
+  const id = (acc as { id?: unknown }).id;
+  return typeof id === 'string' ? id : undefined;
+};
+
+const asRecord = (acc: unknown): Record<string, unknown> | undefined =>
+  typeof acc === 'object' && acc !== null && !Array.isArray(acc)
+    ? (acc as Record<string, unknown>)
+    : undefined;
+
+function withAgentId(station: string, acc: unknown): unknown {
+  const rec = asRecord(acc);
+  if (rec === undefined) return acc;
+  const id = typeof rec.id === 'string' ? rec.id : undefined;
+  if (id === undefined) return acc;
+  const agentId = agentIdForAccount(station, id);
+  if (agentId === undefined) return acc;
+  const allowlist = allowlistForAccount(station, id);
+  const tagged = allowlist === undefined ? { ...rec, agentId } : { ...rec, agentId, allowlist };
+  return accountEnabled(station, id) ? tagged : { ...tagged, enabled: false };
+}
+
+export function attachAgentIds(
+  byStation: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [station, list] of Object.entries(byStation))
+    out[station] = list.map((acc) => withAgentId(station, acc));
+  return out;
+}
+
+export function scopeAccountsByAgent(
+  byStation: Record<string, unknown[]>,
+  allowed: Set<string>,
+): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [station, list] of Object.entries(byStation)) {
+    out[station] = list.filter((acc) => {
+      const id = accountId(acc);
+      if (id === undefined) return false;
+      const agentId = agentIdForAccount(station, id);
+      return agentId !== undefined && allowed.has(agentId);
+    });
+  }
+  return out;
+}
+
+const hasTrain = (station: string): boolean =>
+  stationByName(station)?.hasTrain !== false;
+
+function inCoreAccounts(station: string): unknown[] {
+  if (station !== 'webhook') return [];
+  return listEndpoints().flatMap((e) =>
+    e.secret === undefined || e.webhookId === undefined
+      ? []
+      : [
+          {
+            id: e.id,
+            handle: `/api/webhooks/${e.webhookId}`,
+            endpoint: hookUrl(e.webhookId, e.secret),
+          },
+        ],
+  );
+}
+
+function withCallbackUrl(acc: unknown): unknown {
+  const rec = asRecord(acc);
+  if (rec === undefined) return acc;
+  const { callbackId, callbackToken, ...rest } = rec;
+  if (typeof callbackId !== 'string' || typeof callbackToken !== 'string') return rest;
+  return { ...rest, callback: threemaCallbackUrl(callbackId, callbackToken) };
+}
+
+const decorate = (station: string, rows: unknown[]): unknown[] =>
+  station === 'threema' ? rows.map(withCallbackUrl) : rows;
+
+export interface ScopedAccounts {
+  accounts: Record<string, unknown[]>;
+  unavailable: string[];
+}
+
+async function liveAccounts(
+  station: string,
+): Promise<{ rows: unknown[]; reachable: boolean }> {
+  if (!hasTrain(station))
+    return { rows: inCoreAccounts(station), reachable: true };
+  try {
+    const resp = await forwardTrainCall(station, 'accounts', {});
+    const list = (resp.result as { accounts?: unknown[] } | undefined)?.accounts;
+    return { rows: decorate(station, Array.isArray(list) ? list : []), reachable: true };
+  } catch {
+    return { rows: [], reachable: false };
+  }
+}
+
+function mergeKnown(
+  station: string,
+  live: unknown[],
+  known: KnownAccount[],
+): unknown[] {
+  const seen = new Set(
+    live.flatMap((row) => {
+      const id = accountId(row);
+      return id === undefined ? [] : [id];
+    }),
+  );
+  const missing = known
+    .filter((r) => r.station === station && !seen.has(r.id))
+    .map((r) => ({ id: r.id }));
+  return [...live, ...missing];
+}
+
+async function loadStations(): Promise<ScopedAccounts> {
+  const unavailable: string[] = [];
+  const accounts: Record<string, unknown[]> = {};
+  const known = knownAccounts();
+  await Promise.all(
+    accountStationNames().map(async (station) => {
+      const { rows, reachable } = await liveAccounts(station);
+      if (!reachable) unavailable.push(station);
+      accounts[station] = hasTrain(station) ? mergeKnown(station, rows, known) : rows;
+    }),
+  );
+  return { accounts, unavailable };
+}
+
+export async function gatherAccounts(
+  allowedAgents?: Set<string>,
+): Promise<Record<string, unknown[]>> {
+  const { accounts } = await loadStations();
+  return allowedAgents ? scopeAccountsByAgent(accounts, allowedAgents) : accounts;
+}
+
+export async function gatherAccountsForAgents(
+  allowed: Set<string>,
+): Promise<ScopedAccounts> {
+  const { accounts, unavailable } = await loadStations();
+  return {
+    accounts: attachAgentIds(scopeAccountsByAgent(accounts, allowed)),
+    unavailable,
+  };
+}

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

@@ -0,0 +1,216 @@
+import { stationForLine } from '../stations/registry.js';
+import { kindOf, toCanonical } from '@metro-labs/core/stations/attachments';
+import {
+  cleanupAttachments,
+  resolveAttachments,
+  type ResolvedAttachment,
+} from '../stations/attach-resolve.js';
+import type { CanonicalAttachment, ToolResult } from '@metro-labs/core/stations/types';
+import { errResult, makeCtx, ok, okJson, toErr } from './ctx.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+import { str } from '@metro-labs/core/str';
+
+type Station = NonNullable<ReturnType<typeof stationForLine>>;
+
+interface MessageArgs {
+  line: string;
+  a: Record<string, unknown>;
+  ctx: ReturnType<typeof makeCtx>;
+  onSent?: (messageId: string) => void;
+  station: Station;
+}
+
+const messageIdOf = (response: { result: unknown }): string | undefined => {
+  const id = (response.result as { messageId?: unknown } | null)?.messageId;
+  return typeof id === 'string' && id !== '' ? id : undefined;
+};
+
+const withId = (text: string, messageId: string | undefined): string =>
+  messageId === undefined ? text : `${text} — message_id: ${messageId}`;
+
+interface Sent {
+  labels: string[];
+  messageId?: string;
+}
+
+const deliveredLabels = (response: { result: unknown }): string[] => {
+  const list = (response.result as { attachments?: unknown } | null)
+    ?.attachments;
+  return Array.isArray(list)
+    ? list.filter((x): x is string => typeof x === 'string')
+    : [];
+};
+
+function assertDelivered(
+  station: Station,
+  delivered: string[],
+  atts: ResolvedAttachment[],
+): void {
+  if (delivered.length < atts.length)
+    throw new Error(
+      `${station.name} delivered ${delivered.length} of ${atts.length} attachment(s); ` +
+        'the message text may still have been sent',
+    );
+}
+
+async function sendNative(
+  m: MessageArgs,
+  text: string | undefined,
+  replyTo: string | undefined,
+  atts: ResolvedAttachment[],
+): Promise<Sent> {
+  const { line, ctx, station } = m;
+  const labels: string[] = [];
+  let messageId: string | undefined;
+  if (text) {
+    const response = await ctx.call(
+      'send',
+      replyTo ? { line, text, replyTo } : { line, text },
+    );
+    messageId = messageIdOf(response);
+    labels.push('text');
+  }
+  if (!atts.length) return { labels, messageId };
+  const delivered = station.sendAttachments
+    ? await station.sendAttachments(line, atts, ctx)
+    : [];
+  assertDelivered(station, delivered, atts);
+  labels.push(...delivered);
+  return { labels, messageId };
+}
+
+async function sendForwarded(
+  m: MessageArgs,
+  text: string | undefined,
+  replyTo: string | undefined,
+  atts: ResolvedAttachment[],
+): Promise<Sent> {
+  const { line, ctx, station } = m;
+  const args: Record<string, unknown> = { line };
+  if (text) args.text = text;
+  if (replyTo) args.replyTo = replyTo;
+  if (atts.length) args.attachments = atts.map(toCanonical);
+  const response = await ctx.call('send', args);
+  const messageId = messageIdOf(response);
+  const labels: string[] = [];
+  if (text) labels.push('text');
+  if (!atts.length) return { labels, messageId };
+  const delivered = deliveredLabels(response);
+  assertDelivered(station, delivered, atts);
+  labels.push(...delivered);
+  return { labels, messageId };
+}
+
+const unsupported = (station: Station, atts: CanonicalAttachment[]): string =>
+  `${station.name} cannot send attachments (${atts
+    .map((a) => kindOf(a.mime ?? '', a.path ?? a.url ?? a.name ?? ''))
+    .join(', ')}); send a link in \`text\` instead`;
+
+function noteSent(m: MessageArgs, messageId: string | undefined): void {
+  if (messageId !== undefined) m.onSent?.(messageId);
+}
+
+async function handleSend(m: MessageArgs): Promise<ToolResult> {
+  const text = m.a.text as string | undefined;
+  const replyTo = m.a.reply_to as string | undefined;
+  const requested = (m.a.attachments as CanonicalAttachment[] | undefined) ?? [];
+  if (!text && !requested.length)
+    return errResult('send requires `text` or `attachments`');
+  if (requested.length && m.station.attachmentMode === 'none')
+    return errResult(unsupported(m.station, requested));
+  const atts = await resolveAttachments(requested, {
+    allowed: allowedAgents(currentIdentity()),
+  });
+  try {
+    const native =
+      m.station.attachmentMode === 'native' &&
+      typeof m.station.sendAttachments === 'function';
+    const sent = native
+      ? await sendNative(m, text, replyTo, atts)
+      : await sendForwarded(m, text, replyTo, atts);
+    if (!sent.labels.length)
+      return errResult('send requires `text` or `attachments`');
+    noteSent(m, sent.messageId);
+    return ok(withId(`sent: ${sent.labels.join(', ')}`, sent.messageId));
+  } finally {
+    await cleanupAttachments(atts);
+  }
+}
+
+async function handleRead({ line, a, ctx }: MessageArgs): Promise<ToolResult> {
+  const args: Record<string, unknown> = { line };
+  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);
+  return okJson(await ctx.call('read', args));
+}
+
+type MessageHandler = (m: MessageArgs) => Promise<ToolResult>;
+
+interface VerbSpec {
+  args: readonly (readonly [string, string])[];
+  success: string;
+}
+
+const MESSAGE_VERBS: Record<string, VerbSpec> = {
+  reply: { args: [['message_id', 'replyTo'], ['text', 'text']], success: 'replied' },
+  react: { args: [['message_id', 'messageId'], ['emoji', 'emoji']], success: 'reacted' },
+  unreact: {
+    args: [['message_id', 'messageId'], ['emoji', 'emoji']],
+    success: 'reaction removed',
+  },
+  edit: { args: [['message_id', 'messageId'], ['text', 'text']], success: 'edited' },
+  delete: { args: [['message_id', 'messageId']], success: 'deleted' },
+};
+
+function makeVerbHandler(verb: string, spec: VerbSpec): MessageHandler {
+  return async ({ line, a, ctx, onSent }) => {
+    const payload: Record<string, unknown> = { line };
+    for (const [snake, camel] of spec.args) {
+      const value = str(a[snake]);
+      if (!value) {
+        const fields = spec.args.map(([snakeName]) => `\`${snakeName}\``).join(' and ');
+        return errResult(`${verb} requires ${fields}`);
+      }
+      payload[camel] = value;
+    }
+    const response = await ctx.call(verb, payload);
+    const messageId = messageIdOf(response);
+    if (verb === 'reply' && messageId !== undefined) onSent?.(messageId);
+    return ok(withId(spec.success, messageId));
+  };
+}
+
+const MESSAGE_HANDLERS: Record<string, MessageHandler> = {
+  send: handleSend,
+  read: handleRead,
+  ...Object.fromEntries(
+    Object.entries(MESSAGE_VERBS).map(([verb, spec]) => [verb, makeVerbHandler(verb, spec)]),
+  ),
+};
+
+export interface ToolHooks {
+  onSent?: (messageId: string) => void;
+}
+
+export async function dispatchMessageTool(
+  name: string,
+  a: Record<string, unknown>,
+  hooks: ToolHooks = {},
+): Promise<ToolResult> {
+  const line = str(a.line);
+  if (!line) return errResult(`${name} requires \`line\``);
+  const station = stationForLine(line);
+  if (!station || station.messageVerbs.size === 0) {
+    return errResult(
+      `${station?.name ?? 'these'} lines do not support outbound messaging (send/reply/react/unreact/edit/delete/read).`,
+    );
+  }
+  const handler = MESSAGE_HANDLERS[name];
+  if (!handler) return errResult(`unknown tool: ${name}`);
+  try {
+    return await handler({ line, a, ctx: makeCtx(station.name), station, onSent: hooks.onSent });
+  } catch (e) {
+    return toErr(name, e);
+  }
+}