@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

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

@@ -0,0 +1,165 @@
+import { storedPolicy } from '../policy/policy.js';
+import { forwardTrainCall } from '../stations/train-call.js';
+import {
+  accountStationNames,
+  stationByName,
+} from '../stations/registry.js';
+import { listEndpoints } from '../stations/webhook-endpoints.js';
+import { hookUrl, threemaCallbackUrl } from '../stations/attach.js';
+import { accountEnabled, agentIdForAccount, allowlistForAccount, approversForAccount, 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 stored = storedPolicy({ kind: 'channel', station, account: id });
+  const policy = stored === undefined ? {} : { policy: stored };
+  const approvers = approversForAccount(station, id);
+  const extra = approvers.length === 0 ? policy : { ...policy, approvers };
+  const tagged = allowlist === undefined ? { ...rec, agentId, ...extra } : { ...rec, agentId, allowlist, ...extra };
+  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 };
+}
+
+const URL_SECRETS = new Set(['endpoint', 'callback']);
+
+function withoutUrlSecrets(acc: unknown): unknown {
+  const rec = asRecord(acc);
+  if (rec === undefined) return acc;
+  return Object.fromEntries(Object.entries(rec).filter(([key]) => !URL_SECRETS.has(key)));
+}
+
+export async function gatherAccounts(
+  allowedAgents?: Set<string>,
+): Promise<Record<string, unknown[]>> {
+  const { accounts } = await loadStations();
+  const scoped = allowedAgents ? scopeAccountsByAgent(accounts, allowedAgents) : accounts;
+  return Object.fromEntries(Object.entries(scoped).map(([station, rows]) => [station, rows.map(withoutUrlSecrets)]));
+}
+
+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/attachment-schema.ts

@@ -0,0 +1,91 @@
+import type { ToolDef } from './tool-def.js';
+
+export const attachmentItem = {
+  type: 'object',
+  description:
+    'A file to attach. Provide EXACTLY ONE source; naming two is an error and so is naming ' +
+    'none. Which one to use: `upload` for any real file on your own machine, including a ' +
+    'confidential one (call `create_upload` first, push the bytes over HTTP, then name the ' +
+    'id here); `data` ONLY for a tiny file, a few KB at most, because the base64 has to be ' +
+    'written out verbatim in this tool call and long base64 gets corrupted in the writing; ' +
+    '`url` when the file is ALREADY published somewhere the daemon can fetch it; `path` ONLY ' +
+    'for a file that is already sitting on the daemon host, which is almost never your ' +
+    'machine.',
+  properties: {
+    upload: {
+      type: 'string',
+      description:
+        'The `upload_id` of a file already pushed to metro over HTTP (`create_upload` mints ' +
+        'the slot and the one-line command; the bytes never pass through this conversation). ' +
+        'THIS IS THE ROUTE FOR ANYTHING REAL: it takes files up to 64 MiB, works for a file on ' +
+        'your own machine, and publishes nothing. The upload belongs to your agent, expires ' +
+        '30 minutes after it is created, and no other agent can name it.',
+    },
+    data: {
+      type: 'string',
+      description:
+        'Base64-encoded file bytes, inline in this call. ONLY FOR TINY FILES. The hard cap is ' +
+        '8 MiB decoded, but the real ceiling is far lower and is not enforced by the daemon: ' +
+        'this base64 has to be emitted verbatim as part of the tool call, and past roughly ' +
+        '10 KB (~13 KB of base64) it comes out corrupted, so the file arrives silently ' +
+        'damaged or fails to decode. Use `upload` instead for anything bigger. A ' +
+        '`data:<mime>;base64,` prefix is accepted and supplies the mime when `mime` is ' +
+        'omitted. Stations impose their own, lower limits (xmtp refuses non-image files over ' +
+        '~190 KiB).',
+    },
+    url: {
+      type: 'string',
+      description:
+        'http(s) URL fetched BY THE DAEMON, so it must already be publicly reachable from the ' +
+        'daemon host. Right when the file is already published; never for anything ' +
+        'confidential, because it has to be public for this to work at all. Use `upload` for ' +
+        'a confidential file.',
+    },
+    path: {
+      type: 'string',
+      description:
+        'Absolute path resolved ON THE DAEMON HOST, which is a different machine from yours. ' +
+        'A path on your own disk does NOT resolve here and is refused, however local it ' +
+        'looks. Use `upload` for a file on your machine.',
+    },
+    mime: {
+      type: 'string',
+      description: 'MIME type (guessed from the name/extension if omitted).',
+    },
+    name: {
+      type: 'string',
+      description:
+        'Filename to present (defaults to the basename, or to the name given at upload time).',
+    },
+  },
+} as const;
+
+export const CREATE_UPLOAD_TOOL: ToolDef = {
+  name: 'create_upload',
+  group: 'write',
+  description:
+    'Reserve a slot to push a file to metro over HTTP so you can attach it with `send`. Use ' +
+    'this for any file that actually matters: it is the only attachment route that carries a ' +
+    'file from YOUR machine without publishing it and without the bytes passing through this ' +
+    'conversation. Args: name? (the filename to present), mime?. Returns `upload_id`, a ' +
+    'single-use `upload_url` and a ready-to-run `curl` line. ONE STEP NEEDS A SHELL: run that ' +
+    'command (or any HTTP client) to push the bytes; there is no way to move a local file to ' +
+    'the daemon over MCP alone, because anything in an MCP call has to be written out by the ' +
+    'model first. If you have no shell, hand the single command to a subagent that does and ' +
+    'keep the `upload_id` -- the slot belongs to this metro agent, not to whoever runs the ' +
+    'command. Then: send({line, attachments:[{upload:"<upload_id>"}]}). Up to 64 MiB, expires ' +
+    '30 minutes after it is created, and no other agent can reference it.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Filename to present to the recipient (e.g. `report.pdf`).',
+      },
+      mime: {
+        type: 'string',
+        description: 'MIME type (guessed from the name/extension if omitted).',
+      },
+    },
+  },
+};

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

@@ -0,0 +1,45 @@
+import { CALL_NOTICE, sameCall, type CallNotice, type CallRoute } from '@metro-labs/core/call';
+import { errMsg, log } from '@metro-labs/core/log';
+import { eventInScope } from '../agents/scope.js';
+import { revokeCallPrompts } from '../approvals/pending.js';
+import { sharedCalls } from '../voice/shared.js';
+import type { McpSession } from './session.js';
+
+export const callInScope = (scope: Set<string>, route: CallRoute): boolean =>
+  scope.has(route.agentId) && eventInScope(scope, route.line);
+
+export function connectCallBridge(current: () => McpSession | undefined): void {
+  let owner: McpSession | undefined;
+  let route: CallRoute | undefined;
+  const available = (wanted: CallRoute): boolean => {
+    const session = current();
+    return session !== undefined && session.streamAttached && session.server.getClientVersion()?.name === 'metro-sdk-runner' &&
+      callInScope(session.scope, wanted) && (route === undefined || owner === session);
+  };
+  const boundTo = (session: McpSession | undefined, wanted: CallRoute): boolean => session === owner && route !== undefined && sameCall(route, wanted);
+  const forgetEnded = (notice: CallNotice): void => {
+    if (notice.type === 'ended' && route !== undefined && sameCall(route, notice.route)) {
+      owner = undefined;
+      route = undefined;
+    }
+  };
+  sharedCalls.connect({
+    available,
+    notify: (notice: CallNotice): boolean => {
+      const session = current();
+      const bound = notice.type === 'started' ? available(notice.route) : boundTo(session, notice.route);
+      forgetEnded(notice);
+      if (session === undefined || !session.streamAttached || !callInScope(session.scope, notice.route) || !bound) return false;
+      if (notice.type === 'started') {
+        owner = session;
+        route = notice.route;
+      }
+      session.server.notification({ method: CALL_NOTICE, params: { ...notice, meta: { line: notice.route.line } } }).catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'sdk-call: notification failed');
+        sharedCalls.end(notice.route);
+      });
+      return true;
+    },
+    revoked: (ended) => { revokeCallPrompts(ended); },
+  });
+}

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

@@ -0,0 +1,25 @@
+import { callRoute, speechTarget, type CallSource } from '@metro-labs/core/call';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readPreview } from '../approvals/preview.js';
+import { sharedCalls } from '../voice/shared.js';
+import { agentIdForLine } from '../agents/map.js';
+
+function boundCall(value: unknown, inScope: (line: string) => boolean): CallSource | null {
+  if (!isRecord(value)) return null;
+  const route = callRoute(value.route);
+  const sourceId = value.sourceId;
+  if (route === null || typeof sourceId !== 'string') return null;
+  const source = { route, sourceId };
+  return inScope(route.line) && sharedCalls.valid(source) ? source : null;
+}
+
+export function permissionCall(params: { call?: unknown; input_preview: string; tool_name: string }, inScope: (line: string) => boolean): CallSource | null | undefined {
+  if (params.call !== undefined) return boundCall(params.call, inScope);
+  if (params.tool_name !== 'mcp__metro__send') return undefined;
+  const { input } = readPreview(params.input_preview);
+  if (!isRecord(input) || input.speech === undefined) return undefined;
+  const target = speechTarget(input.speech);
+  if (target === null || typeof input.line !== 'string' || !inScope(input.line)) return null;
+  const agentId = agentIdForLine(input.line);
+  return agentId === undefined ? null : sharedCalls.source(input.line, target, new Set([agentId]));
+}

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

@@ -0,0 +1,253 @@
+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, toErr } from './ctx.js';
+import { runRead } from './read-tool.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+import { str } from '@metro-labs/core/str';
+import { sendSpeech } from './speech-send.js';
+
+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;
+  thread?: string;
+}
+
+const threadOf = (response: { result: unknown }, asked: string): string | undefined => {
+  const line = (response.result as { line?: unknown } | null)?.line;
+  return typeof line === 'string' && line !== '' && line !== asked ? line : undefined;
+};
+
+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',
+    );
+}
+
+const STAGE_PARTS = ['frame', 'wallet'] as const;
+
+const stagePartsIn = (m: MessageArgs): string[] => STAGE_PARTS.filter((key) => m.a[key] !== undefined);
+
+const stagePartArgs = (m: MessageArgs): Record<string, unknown> =>
+  Object.fromEntries(stagePartsIn(m).map((key) => [key, m.a[key]]));
+
+const sentLabels = (m: MessageArgs, text: string | undefined): string[] => [
+  ...(text ? ['text'] : []),
+  ...stagePartsIn(m),
+];
+
+function nativeBody(m: MessageArgs, text: string | undefined, replyTo: string | undefined): Record<string, unknown> {
+  const body: Record<string, unknown> = { line: m.line, ...stagePartArgs(m) };
+  if (text) body.text = text;
+  if (text && replyTo) body.replyTo = replyTo;
+  return body;
+}
+
+async function sendNative(
+  m: MessageArgs,
+  text: string | undefined,
+  replyTo: string | undefined,
+  atts: ResolvedAttachment[],
+): Promise<Sent> {
+  const { line, ctx, station } = m;
+  const labels = sentLabels(m, text);
+  let messageId: string | undefined;
+  if (labels.length) messageId = messageIdOf(await ctx.call('send', nativeBody(m, text, replyTo)));
+  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, ...stagePartArgs(m) };
+  if (text) args.text = text;
+  if (typeof m.a.subject === 'string' && m.a.subject.trim() !== '') args.subject = m.a.subject;
+  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 thread = threadOf(response, line);
+  const labels = sentLabels(m, text);
+  if (atts.length) {
+    const delivered = deliveredLabels(response);
+    assertDelivered(station, delivered, atts);
+    labels.push(...delivered);
+  }
+  return thread === undefined ? { labels, messageId } : { labels, messageId, thread };
+}
+
+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`;
+
+const NOTHING_TO_SEND = 'send requires `text`, `attachments`, `frame` or `wallet`';
+
+function refusal(m: MessageArgs, text: string | undefined, requested: CanonicalAttachment[]): string | undefined {
+  const stageOnly = stagePartsIn(m);
+  if (!text && !requested.length && !stageOnly.length) return NOTHING_TO_SEND;
+  if (stageOnly.length && m.station.sendsFrames !== true)
+    return `${m.station.name} cannot send \`${stageOnly.join('` or `')}\`; that is Stage (XMTP) only`;
+  if (requested.length && m.station.attachmentMode === 'none') return unsupported(m.station, requested);
+  return undefined;
+}
+
+function noteSent(m: MessageArgs, messageId: string | undefined): void {
+  if (messageId !== undefined) m.onSent?.(messageId);
+}
+
+async function handleSend(m: MessageArgs): Promise<ToolResult> {
+  if (m.a.speech !== undefined) return sendSpeech(m.line, m.a);
+  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) ?? [];
+  const refused = refusal(m, text, requested);
+  if (refused !== undefined) return errResult(refused);
+  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(NOTHING_TO_SEND);
+    noteSent(m, sent.messageId);
+    const done = withId(`sent: ${sent.labels.join(', ')}`, sent.messageId);
+    return ok(sent.thread === undefined ? done : `${done} — new thread line: ${sent.thread}`);
+  } finally {
+    await cleanupAttachments(atts);
+  }
+}
+
+const handleRead = ({ a, station }: MessageArgs): Promise<ToolResult> => runRead(station, a);
+
+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 handleTyping = async ({ line, ctx }: MessageArgs): Promise<ToolResult> => {
+  await ctx.call('typing', { line });
+  return ok('typing shown');
+};
+
+const MESSAGE_HANDLERS: Record<string, MessageHandler> = {
+  send: handleSend,
+  read: handleRead,
+  typing: handleTyping,
+  ...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}`);
+  const verbs: ReadonlySet<string> = station.messageVerbs;
+  if (!verbs.has(name))
+    return errResult(
+      `${station.name} does not support ${name}; it supports ${[...verbs].join(', ')}.`,
+    );
+  try {
+    return await handler({ line, a, ctx: makeCtx(station.name), station, onSent: hooks.onSent });
+  } catch (e) {
+    return toErr(name, e);
+  }
+}

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

@@ -0,0 +1,80 @@
+import { channelOptions, type ChannelList } from '@metro-labs/core/stations/channel-directory';
+import type { ToolResult } from '@metro-labs/core/stations/types';
+import { str } from '@metro-labs/core/str';
+import { stationByName } from '../stations/registry.js';
+import { callTargetDenied } from '../agents/scope.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { stationOfAccount } from './read-tool.js';
+import type { ToolDef } from './tool-def.js';
+
+export const LIST_CHANNELS_TOOL: ToolDef = {
+  name: 'list_channels',
+  group: 'read',
+  description:
+    'Discover existing conversations for one account from list_accounts, returning metadata only. ' +
+    'Args: account (required), query?, limit? (1 to 100, default 50), cursor?. Query matches names, ids or lines ' +
+    'case-insensitively. Returns {account, station, channels:[{id, line, name?, kind:direct|group|channel|thread}], ' +
+    'capability:{supported, complete, source:remote|local|mixed|unsupported, reason?}, next_cursor?}. ' +
+    'Use each returned line with other Metro tools. Follow next_cursor with the same account and query. ' +
+    'Check capability: local or partial directories are not exhaustive, and unsupported is not an empty account. ' +
+    'No recent message is required. Receive messages Off does not disable discovery; read policies still apply.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      account: { type: 'string', minLength: 1, description: 'An account id from list_accounts.' },
+      query: { type: 'string', maxLength: 200, description: 'Case-insensitive name, id or line substring.' },
+      limit: { type: 'integer', minimum: 1, maximum: 100, default: 50, description: 'Maximum channels per page.' },
+      cursor: { type: 'string', minLength: 1, maxLength: 2048, description: 'The next_cursor from the previous page.' },
+    },
+    required: ['account'],
+  },
+};
+
+export function channelScopeDenied(allowed: Set<string>, a: Record<string, unknown>): boolean {
+  const account = str(a.account);
+  const station = account ? stationOfAccount(account) : undefined;
+  return station === undefined || stationByName(station) === undefined || callTargetDenied(allowed, station, { account });
+}
+
+export function channelArgsError(a: Record<string, unknown>): ToolResult | undefined {
+  if (typeof a.account !== 'string' || !a.account.trim())
+    return errResult('list_channels requires `account` from list_accounts');
+  try {
+    channelOptions(a);
+    return undefined;
+  } catch (e) {
+    return toErr('list_channels', e);
+  }
+}
+
+export async function dispatchListChannels(a: Record<string, unknown>): Promise<ToolResult> {
+  const account = str(a.account);
+  const name = stationOfAccount(account);
+  const station = name === undefined ? undefined : stationByName(name);
+  if (station === undefined) return errResult('list_channels requires a unique account from list_accounts');
+  if (!station.hasTrain || station.discoversChannels !== true) {
+    const list: ChannelList = {
+      channels: [],
+      capability: {
+        supported: false,
+        complete: false,
+        source: 'unsupported',
+        reason: `${station.name} does not support channel discovery`,
+      },
+    };
+    return okJson({ account, station: station.name, ...list });
+  }
+  try {
+    const { limit, cursor } = channelOptions(a);
+    const args = {
+      account,
+      limit,
+      ...(a.query === undefined ? {} : { query: str(a.query) }),
+      ...(cursor === undefined ? {} : { cursor }),
+    };
+    const { result } = await makeCtx(station.name).call('listChannels', args);
+    return okJson({ ...result as ChannelList, account, station: station.name });
+  } catch (e) {
+    return toErr('list_channels', e);
+  }
+}