@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

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

@@ -1,7 +1,7 @@
-import type { StationTool } from '@metro-labs/mcp/stations/types';
+import type { StationTool } from '@metro-labs/core/stations/types';
+import { PRIORITIES } from './labels.js';
 import {
   str,
-  createChannel,
   setChannelMetadata,
   xmtpSendAttachments,
 } from './tools-handlers.js';
@@ -15,43 +15,9 @@ const lineProp = {
 } as const;
 
 export const XMTP_TOOLS: StationTool[] = [
-  {
-    name: 'create_channel',
-    description:
-      'Create a new XMTP group conversation (channel). Args: addresses (required, array of ' +
-      'Ethereum 0x addresses to add as members), name (required, the group name), labels? ' +
-      '(optional string[] status labels applied after creation), account? ' +
-      '(defaults to your only XMTP account). Calls the daemon xmtp `newGroup`, then ' +
-      '`updateChannelMeta` if labels ' +
-      'are given. Returns the new metro:// line and convId. This is an xmtp-only operation. ' +
-      'NOTE: there is no add-members verb on the daemon, so members must be supplied at ' +
-      'creation time.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        addresses: {
-          type: 'array',
-          description: 'Ethereum 0x addresses to add as group members.',
-          items: { type: 'string' },
-        },
-        name: { type: 'string', description: 'The group/channel name.' },
-        labels: {
-          type: 'array',
-          description: 'Optional status labels to apply after creation.',
-          items: { type: 'string' },
-        },
-        account: {
-          type: 'string',
-          description:
-            'XMTP account to create under. Omit when you have only one.',
-        },
-      },
-      required: ['addresses', 'name'],
-    },
-    handle: (a, ctx) => createChannel(a, ctx),
-  },
   {
     name: 'ask',
+    group: 'write',
     description:
       'Ask a question as a poll in an XMTP conversation (mirrors Claude AskUserQuestion). ' +
       'Single-question form: question (required), options? (string[]), header?, multiSelect?, ' +
@@ -116,11 +82,12 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'dm',
+    group: 'write',
     description:
       'Open (or reuse) a 1:1 XMTP DM with an Ethereum address. Args: address (required, 0x...), ' +
       'account? (defaults to your only XMTP account). Returns the new metro:// line and ' +
       'convId. xmtp-only ' +
-      '(daemon `newDm`). Use this instead of create_channel when there is a single recipient.',
+      '(daemon `newDm`). For a group, use create_group.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -145,10 +112,13 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'group_info',
+    group: 'read',
     description:
       "Read an XMTP channel's current metadata + membership. Args: line (required). Returns " +
-      '{line, id, account, version (dm|group), name, memberCount, labels, github, preview, ' +
-      'members:[{inboxId, address}]}. xmtp-only (daemon `groupInfo`). Use before ' +
+      '{line, id, account, version (dm|group), name, memberCount, labels, category, status, priority, github, preview, ' +
+      'assigned, appData (stored JSON object), rawAppData (stored JSON string), ' +
+      'members:[{inboxId, address}]}. Syncs first and fails if metadata cannot be read. ' +
+      'xmtp-only (daemon `groupInfo`). Use before ' +
       'set_channel_metadata/add_members to see current state.',
     inputSchema: {
       type: 'object',
@@ -163,35 +133,88 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'close_channel',
+    group: 'write',
+    destructive: true,
     description:
-      'Archive/close an XMTP group (removes members). Args: line (required). xmtp-only ' +
-      '(daemon `closeGroup`). Irreversible-ish: members are removed from the group.',
+      'Remove members from an XMTP group, and optionally leave it. Args: line (required), ' +
+      'removeInboxIds? (inbox ids to remove; your own is ignored here), removeSelf? (true to ' +
+      'leave the group yourself). With neither, nothing changes. xmtp-only (daemon ' +
+      '`closeGroup`). Returns {removed, leftSelf}.',
     inputSchema: {
       type: 'object',
-      properties: { line: lineProp },
+      properties: {
+        line: lineProp,
+        removeInboxIds: {
+          type: 'array',
+          description: 'Inbox ids of the members to remove.',
+          items: { type: 'string' },
+        },
+        removeSelf: {
+          type: 'boolean',
+          description: 'Leave the group after removing the others.',
+        },
+      },
       required: ['line'],
     },
     async handle(a, ctx) {
       const line = str(a.line);
       if (!line) return ctx.err('close_channel requires `line`');
-      return ctx.okJson(await ctx.call('closeGroup', { line }));
+      const args: Record<string, unknown> = { line };
+      if (Array.isArray(a.removeInboxIds)) args.removeInboxIds = a.removeInboxIds.map(String);
+      if (a.removeSelf === true) args.removeSelf = true;
+      return ctx.okJson(await ctx.call('closeGroup', args));
     },
   },
   {
     name: 'set_channel_metadata',
+    group: 'write',
     description:
       "Update an existing channel's metadata. Args: line (required, the metro:// line), and " +
-      'any of labels? (string[]), github? (url), preview? (url), name? (string). All provided ' +
-      'fields are applied together in one atomic updateChannelMeta daemon call (a single ' +
-      'appData merge plus name update). xmtp-only ' +
-      '(channel metadata lives on xmtp groups). Returns the updated channel info.',
+      'any of metadata? (JSON object), github? (url), preview? (url), name? (string). ' +
+      'metadata is a shallow appData patch: omitted keys are preserved, supplied nested ' +
+      'values replace that key, and null deletes custom keys. v is reserved. Put labels, ' +
+      'assigned, category, status and priority inside metadata. assigned replaces the array with normalized lowercase ' +
+      'Ethereum addresses of current members. Read group_info and union existing IDs to ' +
+      'add assignees. category and status are each one free-form string per channel, trimmed, ' +
+      'whitespace collapsed and truncated to 24 characters. priority is trimmed and must be Urgent, High, Medium or Low. ' +
+      '"" or null clears category, status or priority. labels remains a legacy top-level alias. Duplicate top-level/metadata ' +
+      'label/link aliases are refused. All fields use one updateChannelMeta call. xmtp-only. ' +
+      'Returns updated metadata. Reread group_info to verify persistence.',
     inputSchema: {
       type: 'object',
       properties: {
         line: lineProp,
+        metadata: {
+          type: 'object',
+          description: 'Shallow JSON appData patch. Omitted keys stay unchanged. v is reserved.',
+          properties: {
+            labels: { type: 'array', items: { type: 'string' } },
+            assigned: {
+              type: 'array',
+              description: 'Replacement assignee list. Current member Ethereum addresses only. [] clears.',
+              items: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' },
+            },
+            category: {
+              type: ['string', 'null'],
+              description: 'One free-form category, trimmed, whitespace collapsed, truncated to 24 characters. "" or null clears it.',
+            },
+            status: {
+              type: ['string', 'null'],
+              description: 'One free-form status, trimmed, whitespace collapsed, truncated to 24 characters. "" or null clears it.',
+            },
+            priority: {
+              type: ['string', 'null'],
+              enum: [...PRIORITIES, '', null],
+              description: 'One priority: Urgent, High, Medium or Low. Surrounding whitespace is trimmed; empty or null clears it.',
+            },
+            github: { type: 'string' },
+            preview: { type: 'string' },
+          },
+          additionalProperties: true,
+        },
         labels: {
           type: 'array',
-          description: 'Status labels to set.',
+          description: 'Legacy alias. Prefer metadata.labels.',
           items: { type: 'string' },
         },
         github: {

package/runtime/node_modules/@metro-labs/xmtp/src/transcribe.ts

@@ -1,7 +1,6 @@
-import { errMsg } from '@metro-labs/mcp/log';
-import { mintId, SELF_URI } from './wire.js';
-
-type EmitInbound = (accountId: string, e: Record<string, unknown>) => void;
+import { errMsg } from '@metro-labs/core/log';
+import { emitInbound, selfUri } from '@metro-labs/core/stations/train-events';
+import { mintId } from '@metro-labs/core/stations/station-runtime';
 
 const WHISPER_BIN = process.env.METRO_WHISPER_BIN ?? 'whisper-cli';
 const WHISPER_MODEL =
@@ -14,7 +13,6 @@ export async function transcribeAndEmit(
   line: string,
   accountId: string,
   sourceMsgId: string,
-  emitInbound: EmitInbound,
 ): Promise<void> {
   const {
     existsSync: ex,
@@ -69,7 +67,7 @@ export async function transcribeAndEmit(
       ts: new Date().toISOString(),
       station: 'xmtp',
       line,
-      from: SELF_URI,
+      from: selfUri(),
       text: `🎙️ ${text}`,
       payload: {
         contentType: 'transcript',

package/runtime/node_modules/@metro-labs/xmtp/src/verify.ts

@@ -1,7 +1,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Client, type ClientOptions, type Signer } from '@xmtp/node-sdk';
-import { expandHome, signerFor, XMTP_ENV } from './identity.js';
+import { expandHome, identityFor, signerFor, XMTP_ENV } from './identity.js';
+import { ensureDeployed } from './smart.js';
 
 export class XmtpVerifyError extends Error {}
 
@@ -10,6 +11,7 @@ export interface XmtpVerified {
   address: string;
   installationId: string;
   dbPath: string;
+  smart: boolean;
 }
 
 interface RegisteredClient {
@@ -34,15 +36,25 @@ const reason = (err: unknown): string =>
 export async function verifyXmtpKey(
   privateKey: string,
   dbPath: string,
+  smart = false,
   create: CreateXmtpClient = openInbox,
 ): Promise<XmtpVerified> {
-  let signer: Signer;
-  let address: string;
+  let identity: Awaited<ReturnType<typeof identityFor>>;
   try {
-    ({ signer, address } = signerFor(privateKey));
+    signerFor(privateKey);
   } catch {
     throw new XmtpVerifyError('that is not a usable XMTP private key');
   }
+  try {
+    identity = await identityFor(privateKey, smart);
+  } catch (err) {
+    throw new XmtpVerifyError(`could not build the smart account on Base: ${reason(err)}`);
+  }
+  const { signer, address } = identity;
+  if (identity.smart !== null)
+    await ensureDeployed(identity.smart).catch((err: unknown) => {
+      throw new XmtpVerifyError(`could not deploy the smart account on Base (is the ZeroDev sponsorship still on?): ${reason(err)}`);
+    });
   const resolved = expandHome(dbPath);
   mkdirSync(dirname(resolved), { recursive: true });
   const client = await create(signer, resolved).catch((err: unknown) => {
@@ -59,6 +71,7 @@ export async function verifyXmtpKey(
     address,
     installationId: client.installationId,
     dbPath: resolved,
+    smart,
   };
 }
 
@@ -68,10 +81,11 @@ async function runCli(): Promise<void> {
     const input = JSON.parse(readFileSync(0, 'utf8')) as {
       privateKey?: unknown;
       dbPath?: unknown;
+      smart?: unknown;
     };
     if (typeof input.privateKey !== 'string' || typeof input.dbPath !== 'string')
       throw new XmtpVerifyError('xmtp verify needs a privateKey and a dbPath');
-    out = { ok: true, ...(await verifyXmtpKey(input.privateKey, input.dbPath)) };
+    out = { ok: true, ...(await verifyXmtpKey(input.privateKey, input.dbPath, input.smart === true)) };
   } catch (err) {
     out = { ok: false, error: reason(err) };
   }

package/runtime/node_modules/@metro-labs/xmtp/src/wallet.ts

@@ -0,0 +1,28 @@
+import type { EncodedContent } from '@xmtp/content-type-primitives';
+import {
+  SignatureReferenceCodec,
+  SignatureRequestCodec,
+  TransactionReferenceCodec,
+  WalletSendCallsCodec,
+} from './codecs.js';
+import { bad, isNode, parseJson } from './frames.js';
+
+const WALLET_TYPES: Record<string, { codec: { encode(c: Record<string, unknown>): EncodedContent }; needs: string[] }> = {
+  walletSendCalls: { codec: new WalletSendCallsCodec(), needs: ['version', 'chainId', 'from', 'calls'] },
+  transactionReference: { codec: new TransactionReferenceCodec(), needs: ['networkId', 'reference'] },
+  signatureRequest: { codec: new SignatureRequestCodec(), needs: ['id', 'kind'] },
+  signatureReference: { codec: new SignatureReferenceCodec(), needs: ['requestId', 'signature', 'signer'] },
+};
+
+export function buildWalletContent(raw: unknown): { encoded: EncodedContent; summary: string } {
+  const args = parseJson(raw, 'wallet');
+  const type = isNode(args) && typeof args.type === 'string' ? args.type : '';
+  const spec = Object.hasOwn(WALLET_TYPES, type) ? WALLET_TYPES[type] : undefined;
+  if (!isNode(args) || !spec) throw bad(`wallet type must be one of ${Object.keys(WALLET_TYPES).join(', ')}`);
+  const content = parseJson(args.content, 'wallet content');
+  if (!isNode(content)) throw bad(`wallet content must be the ${type} JSON object`);
+  const missing = spec.needs.filter((key) => content[key] === undefined);
+  if (missing.length > 0) throw bad(`${type} content needs ${missing.join(', ')}`);
+  const encoded = spec.codec.encode(content);
+  return { encoded, summary: encoded.fallback ?? type };
+}

package/runtime/node_modules/@metro-labs/xmtp/src/wire.ts

@@ -1,7 +1,3 @@
-export { emit, respond, mintId } from '@metro-labs/mcp/stations/station-runtime';
-
-export const SELF_URI = process.env.METRO_SELF_URI ?? '';
-
 const UID_MAP_MAX = 5000;
 const uidToXmtp = new Map<string, string>();
 
@@ -37,3 +33,17 @@ export function resolveMsgId(rawId: string): string {
       '(not seen by this train; pass the raw xmtp message_id)',
   );
 }
+
+const SENT_MAX = 5000;
+const sentIds = new Set<string>();
+
+export function rememberSent(xmtpId: string | undefined): void {
+  if (!xmtpId) return;
+  sentIds.add(xmtpId);
+  if (sentIds.size > SENT_MAX) {
+    const oldest = sentIds.values().next().value;
+    if (oldest !== undefined) sentIds.delete(oldest);
+  }
+}
+
+export const sentByMe = (xmtpId: string): boolean => sentIds.has(xmtpId);

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.26"
+  "version": "0.1.0-beta.261"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@metro-labs/core",
+  "version": "0.1.0",
+  "private": true,
+  "description": "What every metro process shares: the logger, the event bus and its types, ids, secure file writes, the train protocol, station types and attachment handling. No HTTP, no policy.",
+  "type": "module",
+  "exports": {
+    "./log": "./src/log.ts",
+    "./events": "./src/events.ts",
+    "./is-record": "./src/is-record.ts",
+    "./runner-activity": "./src/runner-activity.ts",
+    "./secure-fs": "./src/secure-fs.ts",
+    "./version": "./src/version.ts",
+    "./train-error": "./src/train-error.ts",
+    "./trains/protocol": "./src/protocol.ts",
+    "./ids": "./src/ids.ts",
+    "./tickets": "./src/tickets.ts",
+    "./station-names": "./src/station-names.ts",
+    "./str": "./src/str.ts",
+    "./lines": "./src/lines.ts",
+    "./endpoints": "./src/endpoints.ts",
+    "./stations/types": "./src/stations/types.ts",
+    "./stations/account-files": "./src/stations/account-files.ts",
+    "./stations/station-runtime": "./src/stations/station-runtime.ts",
+    "./stations/account-store": "./src/stations/account-store.ts",
+    "./stations/attachments": "./src/stations/attachments.ts",
+    "./stations/mail": "./src/stations/mail.ts",
+    "./stations/mail-text": "./src/stations/mail-text.ts",
+    "./stations/mail-trust": "./src/stations/mail-trust.ts",
+    "./stations/oauth": "./src/stations/oauth.ts",
+    "./stations/messaging-normalize": "./src/stations/messaging-normalize.ts",
+    "./stations/profile": "./src/stations/profile.ts",
+    "./stations/sender-profile": "./src/stations/sender-profile.ts",
+    "./stations/train-events": "./src/stations/train-events.ts",
+    "./stations/train-boot": "./src/stations/train-boot.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
+  },
+  "dependencies": {
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.3",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/endpoints.ts

@@ -0,0 +1,7 @@
+export interface Endpoint {
+  id: string;
+  webhookId?: string;
+  label: string;
+  secret?: string;
+  createdAt: string;
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/events.ts

@@ -0,0 +1,121 @@
+import { Line } from './lines.js';
+import { errMsg, log } from './log.js';
+
+export const userSelf = (): Line =>
+  (process.env.METRO_FROM ?? 'metro://user') as Line;
+
+export type StructuredEvent =
+  | { type: 'msg' }
+  | { type: 'react'; emoji?: string; targetId?: string }
+  | { type: 'edit'; targetId?: string }
+  | { type: 'delete'; targetId?: string }
+  | { type: 'reply'; replyTo?: string }
+  | { type: 'system'; source?: string; eventName?: string };
+
+export interface MetroEvent {
+  id: string;
+  ts: string;
+  station: string;
+  line: Line;
+  lineName?: string;
+  from: Line;
+  fromName?: string;
+  fromDisplayName?: string;
+  to: Line;
+  text?: string;
+  messageId?: string;
+  replyTo?: string;
+  isPrivate?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  senderVerified?: boolean;
+  payload?: unknown;
+  display?: string;
+  event?: StructuredEvent;
+  agent?: string;
+  seq?: number;
+}
+
+function isExternalWebhook(e: MetroEvent): boolean {
+  return e.station === 'webhook' && !Line.isLocal(e.from);
+}
+
+function webhookEventName(e: MetroEvent): string | undefined {
+  const headers = (e.payload as { headers?: Record<string, string> } | undefined)
+    ?.headers;
+  return headers?.['x-github-event'] ?? headers?.['x-intercom-topic'];
+}
+
+export function classifyEvent(e: MetroEvent): StructuredEvent {
+  if (isExternalWebhook(e)) {
+    return {
+      type: 'system',
+      source: 'webhook',
+      eventName: webhookEventName(e),
+    };
+  }
+  const emoji =
+    (e.payload as { emoji?: string } | undefined)?.emoji ??
+    e.text?.match(/^\[react (.+)\]$/)?.[1];
+  if (emoji) return { type: 'react', emoji, targetId: e.replyTo };
+  if (e.replyTo) return { type: 'reply', replyTo: e.replyTo };
+  return { type: 'msg' };
+}
+
+export function formatDisplay(e: MetroEvent): string {
+  const headerFor = (icon: string, parts: (string | undefined)[]): string =>
+    `**${icon} ${parts.filter(Boolean).join(' · ')}**`;
+  const body = e.text ?? '';
+  if (isExternalWebhook(e)) {
+    const ev = webhookEventName(e);
+    return `${headerFor('🪝', ['webhook', e.lineName, ev])}\n> ${body}`;
+  }
+  if (Line.isLocal(e.from)) {
+    return `${headerFor('📤', [e.station, '→', e.fromName ?? e.to])}\n> ${body}`;
+  }
+  return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
+}
+
+export { mintId } from './ids.js';
+
+export type BusListener = (event: MetroEvent, busSeq: number) => void;
+
+export interface BufferedEvent {
+  busSeq: number;
+  event: MetroEvent;
+}
+
+const BUS_BUFFER_MAX = 500;
+
+const listeners = new Set<BusListener>();
+const buffer: BufferedEvent[] = [];
+let busSeq = 0;
+
+export function publishEvent(event: MetroEvent): void {
+  busSeq += 1;
+  const seq = busSeq;
+  buffer.push({ busSeq: seq, event });
+  if (buffer.length > BUS_BUFFER_MAX) buffer.shift();
+  for (const fn of [...listeners]) {
+    try {
+      fn(event, seq);
+    } catch (err) {
+      log.error({ busSeq: seq, err: errMsg(err) }, 'bus: a listener threw');
+    }
+  }
+}
+
+export function currentBusSeq(): number {
+  return busSeq;
+}
+
+export function bufferedSince(afterBusSeq: number): BufferedEvent[] {
+  return buffer.filter((b) => b.busSeq > afterBusSeq);
+}
+
+export function subscribeEvents(fn: BusListener): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/ids.ts

@@ -0,0 +1,28 @@
+import { randomBytes, randomInt } from 'node:crypto';
+
+const ID_BYTES = 8;
+const REROLLS = 16;
+const APPROVAL_LETTERS = 'abcdefghijkmnopqrstuvwxyz';
+const APPROVAL_LENGTH = 5;
+
+export const approvalId = (): string => Array.from({ length: APPROVAL_LENGTH }, () => APPROVAL_LETTERS[randomInt(APPROVAL_LETTERS.length)]).join('');
+
+export const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{10}$/;
+
+export const mintId = (): string =>
+  `msg_${randomBytes(6).toString('base64url')}`;
+
+export function newId(): string {
+  for (let attempt = 0; attempt < REROLLS; attempt += 1) {
+    const id = randomBytes(ID_BYTES).toString('base64url');
+    if (ID_RE.test(id)) return id;
+  }
+  throw new Error('could not generate an id');
+}
+
+export function parseId(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  return ID_RE.test(raw) ? raw : null;
+}
+
+export const AGENT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$/;

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/is-record.ts

@@ -0,0 +1,2 @@
+export const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/lines.ts

@@ -0,0 +1,78 @@
+export type Line = string & { readonly __line: unique symbol };
+export const asLine = (s: string): Line => s as Line;
+
+const PREFIX = 'metro://';
+const build = (station: string, ...seg: (string | number)[]): Line =>
+  asLine(`${PREFIX}${station}/${seg.map(String).join('/')}`);
+
+function parseAccountScoped(
+  line: Line | string,
+  station: string,
+  validate?: (resource: string) => boolean,
+): { accountId: string; resource: string } | null {
+  const p = Line.parse(line);
+  if (p?.station !== station || p.path.length !== 2) return null;
+  const [accountId, resource] = p.path;
+  if (accountId === undefined || resource === undefined) return null;
+  if (validate && !validate(resource)) return null;
+  return { accountId, resource };
+}
+
+const isSnowflake = (s: string): boolean => /^\d+$/.test(s);
+const isThreemaResource = (s: string): boolean =>
+  /^(?:[A-Z0-9]{8}|\*[A-Z0-9]{7})(?:-[0-9a-f]{16})?$/i.test(s);
+const isMailResource = (s: string): boolean => /^[A-Za-z0-9=_%.@+-]+$/.test(s);
+const isSignedInt = (s: string): boolean => /^-?\d+$/.test(s);
+
+const topicPart = (topicId: string | undefined): { topicId?: number } | null => {
+  if (topicId === undefined) return {};
+  return isSnowflake(topicId) ? { topicId: Number(topicId) } : null;
+};
+
+function parseTelegramLine(
+  line: Line | string,
+): { accountId: string; chatId: number; topicId?: number } | null {
+  const p = Line.parse(line);
+  if (p?.station !== 'telegram-bot') return null;
+  const [accountId, chatId, topicId, ...extra] = p.path;
+  if (accountId === undefined || chatId === undefined || extra.length > 0) return null;
+  if (!isSignedInt(chatId)) return null;
+  const topic = topicPart(topicId);
+  return topic === null ? null : { accountId, chatId: Number(chatId), ...topic };
+}
+
+export const Line = {
+  claude: (orgId: string, sessionId: string): Line =>
+    build('claude', orgId, sessionId),
+  webhook: (endpointId: string): Line => build('webhook', endpointId),
+  user: (station: string, id: string | number): Line =>
+    build(station, 'user', id),
+
+  parse(line: Line | string): { station: string; path: string[] } | null {
+    if (!line.startsWith(PREFIX)) return null;
+    const rest = line.slice(PREFIX.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0) return null;
+    const path = rest
+      .slice(slash + 1)
+      .split('/')
+      .filter(Boolean);
+    return path.length ? { station: rest.slice(0, slash), path } : null;
+  },
+  station: (line: Line | string): string | null =>
+    Line.parse(line)?.station ?? null,
+  isLocal: (line: Line | string): boolean => Line.station(line) === 'claude',
+
+  parseXmtp: (line: Line | string) => parseAccountScoped(line, 'xmtp'),
+
+  parseDiscord: (line: Line | string) =>
+    parseAccountScoped(line, 'discord-bot', isSnowflake),
+
+  parseTelegram: (line: Line | string) => parseTelegramLine(line),
+
+  parseThreema: (line: Line | string) =>
+    parseAccountScoped(line, 'threema', isThreemaResource),
+
+  parseMail: (line: Line | string, station: 'outlook' | 'gmail') =>
+    parseAccountScoped(line, station, isMailResource),
+};