@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.21

package/runtime/node_modules/@metro-labs/mcp/src/stations/lines.ts

@@ -0,0 +1,82 @@
+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('/')}`);
+
+export 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) return null;
+  let accountId: string, resource: string;
+  if (p.path.length === 2 && p.path[0] !== undefined && p.path[1] !== undefined) {
+    accountId = p.path[0];
+    resource = p.path[1];
+  } else if (p.path.length === 1 && p.path[0] !== undefined) {
+    accountId = 'default';
+    resource = p.path[0];
+  } else return null;
+  if (validate && !validate(resource)) return null;
+  return { accountId, resource };
+}
+
+const isSnowflake = (s: string): boolean => /^\d+$/.test(s);
+const isSignedInt = (s: string): boolean => /^-?\d+$/.test(s);
+
+function splitTelegramAccount(path: string[]): { accountId: string; rest: string[] } {
+  const first = path[0];
+  if (path.length >= 2 && first !== undefined && !isSignedInt(first))
+    return { accountId: first, rest: path.slice(1) };
+  return { accountId: 'default', rest: path };
+}
+
+function parseTelegramLine(
+  line: Line | string,
+): { accountId: string; chatId: number; topicId?: number } | null {
+  const p = Line.parse(line);
+  if (p?.station !== 'telegram') return null;
+  const { accountId, rest } = splitTelegramAccount(p.path);
+  const [chatId, topicId] = rest;
+  if (rest.length < 1 || rest.length > 2 || chatId === undefined || !isSignedInt(chatId))
+    return null;
+  if (topicId !== undefined && !isSnowflake(topicId)) return null;
+  return {
+    accountId,
+    chatId: Number(chatId),
+    ...(topicId !== undefined ? { topicId: Number(topicId) } : {}),
+  };
+}
+
+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', isSnowflake),
+
+  parseTelegram: (line: Line | string) => parseTelegramLine(line),
+};

package/runtime/node_modules/@metro-labs/mcp/src/stations/messaging-normalize.ts

@@ -0,0 +1,88 @@
+type Args = Record<string, unknown>;
+export interface Normalized {
+  action: string;
+  args: Args;
+}
+
+interface Attachment {
+  kind?: string;
+  path?: string;
+  url?: string;
+  data?: string;
+  mime?: string;
+  name?: string;
+}
+
+interface DiscordFile {
+  file: string;
+  kind: string;
+  name: string;
+}
+
+const discordFile = (a: Attachment): DiscordFile | null => {
+  const file = a.path ?? a.url;
+  if (typeof file !== 'string') return null;
+  return { file, kind: a.kind ?? 'file', name: a.name ?? '' };
+};
+
+function discordAttachments(att: Attachment[]): Args {
+  const usable = att
+    .map(discordFile)
+    .filter((f): f is DiscordFile => f !== null);
+  if (!usable.length) return {};
+  return {
+    files: usable.map((f) => f.file),
+    attachmentKinds: usable.map((f) => f.kind),
+    attachmentNames: usable.map((f) => f.name),
+  };
+}
+
+export function normalizeDiscord(action: string, env: Args): Normalized {
+  const att = (env.attachments as Attachment[] | undefined) ?? [];
+  if (action === 'send') {
+    return { action: 'send', args: { ...env, ...discordAttachments(att) } };
+  }
+  if (action === 'reply') {
+    const replyTo = env.replyTo ?? env.messageId;
+    return {
+      action: 'send',
+      args: { ...env, replyTo, ...discordAttachments(att) },
+    };
+  }
+  if (action === 'unreact')
+    return { action: 'react', args: { ...env, emoji: '' } };
+  if (action === 'read') {
+    return {
+      action: 'fetch',
+      args: { line: env.line, limit: env.limit, before: env.before },
+    };
+  }
+  return { action, args: env };
+}
+
+export function normalizeTelegram(action: string, env: Args): Normalized {
+  if (action === 'reply') {
+    return {
+      action: 'send',
+      args: {
+        line: env.line,
+        text: env.text,
+        replyTo: env.replyTo,
+        attachments: env.attachments,
+      },
+    };
+  }
+  if (action === 'unreact')
+    return { action: 'react', args: { ...env, emoji: '' } };
+  return { action, args: env };
+}
+
+export function normalizeXmtp(action: string, env: Args): Normalized {
+  if (action === 'unreact') {
+    return { action: 'react', args: { ...env, action: 'removed' } };
+  }
+  if (action === 'read') {
+    return { action: 'query', args: { line: env.line, limit: env.limit } };
+  }
+  return { action, args: env };
+}

package/runtime/node_modules/@metro-labs/mcp/src/stations/registry.ts

@@ -0,0 +1,35 @@
+import type { Station } from './types.js';
+import { Line } from './lines.js';
+import { xmtpStation } from '@metro-labs/xmtp';
+import { telegramStation } from '@metro-labs/telegram';
+import { telegramUserStation } from '@metro-labs/telegram-user';
+import { discordStation } from '@metro-labs/discord';
+import { whatsappStation } from '@metro-labs/whatsapp';
+import { webhookStation } from '@metro-labs/webhook';
+
+export const STATIONS: readonly Station[] = [
+  xmtpStation,
+  telegramStation,
+  telegramUserStation,
+  discordStation,
+  whatsappStation,
+  webhookStation,
+];
+
+export const stationByName = (name: string): Station | undefined =>
+  STATIONS.find((s) => s.name === name);
+
+export const stationForLine = (line: string): Station | undefined => {
+  const s = Line.station(line);
+  return s ? stationByName(s) : undefined;
+};
+
+export const accountStationNames = (): string[] =>
+  STATIONS.filter((s) => s.hasAccounts).map((s) => s.name);
+
+export const accountStationCapabilities = (): Record<string, string[]> => {
+  const out: Record<string, string[]> = {};
+  for (const s of STATIONS)
+    if (s.hasAccounts) out[s.name] = [...s.messageVerbs].sort();
+  return out;
+};

package/runtime/node_modules/@metro-labs/mcp/src/stations/station-runtime.ts

@@ -0,0 +1,64 @@
+import { serializeTrainError, type TrainErrorInfo } from '../daemon/train-error.js';
+import type { Normalized } from './messaging-normalize.js';
+
+export const emit = (e: unknown): void =>
+  void process.stdout.write(JSON.stringify(e) + '\n');
+
+export const respond = (
+  id: string,
+  body: { result?: unknown; error?: string; errorInfo?: TrainErrorInfo },
+): void =>
+  void process.stdout.write(
+    JSON.stringify({ op: 'response', id, ...body }) + '\n',
+  );
+
+export const mintId = (): string =>
+  `msg_${Math.random().toString(36).slice(2, 10)}`;
+
+type Args = Record<string, unknown>;
+
+export interface CallMsg {
+  op: 'call';
+  id: string;
+  action: string;
+  args: Args;
+}
+
+export type StationHandler = (id: string, args: Args) => void | Promise<void>;
+
+export interface StationConfig {
+  handlers: Record<string, StationHandler>;
+  normalize: (action: string, args: Args) => Normalized;
+  preDispatch?: (id: string, action: string) => boolean;
+}
+
+const lineTag = (args: Args): string =>
+  typeof args.line === 'string' ? args.line : '?';
+
+export function makeStation({ handlers, normalize, preDispatch }: StationConfig) {
+  const known = Object.keys(handlers).join(', ');
+  return async function handleCall(msg: CallMsg): Promise<void> {
+    const { id } = msg;
+    let action = msg.action;
+    let args: Args = msg.args;
+    try {
+      ({ action, args } = normalize(msg.action, msg.args));
+      emit({ op: 'log', text: `call ${action} recv (line=${lineTag(args)})` });
+      if (preDispatch?.(id, action)) return;
+      const handler = handlers[action];
+      if (!handler) {
+        respond(id, { error: `unknown action '${action}' (have: ${known})` });
+        return;
+      }
+      await handler(id, args);
+      emit({ op: 'log', text: `call ${action} done (line=${lineTag(args)})` });
+    } catch (err) {
+      const info = serializeTrainError(err);
+      emit({
+        op: 'log',
+        text: `call ${action} FAILED (line=${lineTag(args)}): ${info.error}`,
+      });
+      respond(id, info);
+    }
+  };
+}

package/runtime/node_modules/@metro-labs/mcp/src/stations/types.ts

@@ -0,0 +1,107 @@
+export type Verb =
+  | 'send'
+  | 'reply'
+  | 'react'
+  | 'unreact'
+  | 'edit'
+  | 'delete'
+  | 'read';
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+export interface CanonicalAttachment {
+  path?: string;
+  url?: string;
+  data?: string;
+  upload?: string;
+  mime?: string;
+  name?: string;
+}
+
+export interface ToolContext {
+  call(
+    action: string,
+    args: Record<string, unknown>,
+  ): Promise<{ result: unknown }>;
+  ok(text: string): ToolResult;
+  okJson(value: unknown): ToolResult;
+  err(text: string): ToolResult;
+  readFile(path: string): Promise<Buffer>;
+}
+
+export interface StationTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handle(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+
+export interface MetroMember {
+  id: string;
+  name?: string;
+  display_name?: string;
+  address?: string;
+  roles?: string[];
+  is_admin?: boolean;
+  is_bot?: boolean;
+}
+
+export interface MemberCapability {
+  supported: boolean;
+  complete: boolean;
+  reason?: string;
+  total?: number;
+}
+
+export interface MemberList {
+  members: MetroMember[];
+  capability: MemberCapability;
+}
+
+export type GroupOp =
+  | 'create_group'
+  | 'add_members'
+  | 'remove_members'
+  | 'invite_link';
+
+export type MemberOutcomeStatus = 'added' | 'invited' | 'removed' | 'failed';
+
+export interface MemberOutcome {
+  id: string;
+  status: MemberOutcomeStatus;
+  reason?: string;
+}
+
+export interface GroupCapability {
+  supported: boolean;
+  reason?: string;
+}
+
+export interface GroupResult {
+  capability: GroupCapability;
+  line?: string;
+  id?: string;
+  name?: string;
+  members?: MemberOutcome[];
+  inviteLink?: string;
+}
+
+export type AttachmentMode = 'canonical' | 'native' | 'none';
+
+export interface Station {
+  name: string;
+  hasAccounts: boolean;
+  hasTrain: boolean;
+  messageVerbs: ReadonlySet<Verb>;
+  groupOps?: ReadonlySet<GroupOp>;
+  attachmentMode: AttachmentMode;
+  sendAttachments?(
+    line: string,
+    atts: CanonicalAttachment[],
+    ctx: ToolContext,
+  ): Promise<string[]>;
+  tools: StationTool[];
+}

package/runtime/node_modules/@metro-labs/telegram/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@metro-labs/telegram",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./verify": "./src/verify.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/mcp": "workspace:*"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.2",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

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

@@ -0,0 +1,120 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  makeAccountStore,
+  resolveAccountId,
+} from '@metro-labs/mcp/stations/account-store';
+import { Line } from '@metro-labs/mcp/lines';
+
+const ACCOUNTS_FILE =
+  process.env.TELEGRAM_ACCOUNTS_FILE ??
+  join(homedir(), '.metro', 'telegram-accounts.json');
+
+export interface AccountConfig {
+  id: string;
+  token: string;
+  owner?: string;
+}
+
+export const { loadAccounts } = makeAccountStore<AccountConfig>({
+  prefix: 'telegram',
+  file: ACCOUNTS_FILE,
+  allowlistEnv: ['TELEGRAM_ONLY_ACCOUNTS', 'TELEGRAM_ACCOUNTS'],
+  validate(raw, die) {
+    const seenId = new Set<string>();
+    const seenTok = new Set<string>();
+    for (const a of raw) {
+      if (!a.id) die('account missing id');
+      if (!a.token || typeof a.token !== 'string')
+        die(`account '${a.id}' missing token`);
+      if (seenId.has(a.id)) die(`duplicate account id '${a.id}'`);
+      if (seenTok.has(a.token))
+        die(
+          `account '${a.id}' reuses a token used by another account (409 on getUpdates)`,
+        );
+      seenId.add(a.id);
+      seenTok.add(a.token);
+    }
+  },
+});
+
+export interface Account {
+  cfg: AccountConfig;
+  api: string;
+  fileApi: string;
+  offset: number;
+}
+export const accounts = new Map<string, Account>();
+
+export async function tg<T>(
+  accountId: string,
+  method: string,
+  body: unknown,
+  timeoutMs = 30_000,
+): Promise<T> {
+  const acct = accounts.get(accountId);
+  if (!acct) throw new Error(`unknown account '${accountId}'`);
+  const res = await fetch(`${acct.api}/${method}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const json = (await res.json()) as {
+    ok: boolean;
+    description?: string;
+    result?: T;
+  };
+  if (!json.ok)
+    throw new Error(`telegram ${method}: ${json.description ?? 'unknown'}`);
+  return json.result as T;
+}
+
+export async function tgForm<T>(
+  accountId: string,
+  method: string,
+  form: FormData,
+  timeoutMs = 60_000,
+): Promise<T> {
+  const acct = accounts.get(accountId);
+  if (!acct) throw new Error(`unknown account '${accountId}'`);
+  const res = await fetch(`${acct.api}/${method}`, {
+    method: 'POST',
+    body: form,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const json = (await res.json()) as {
+    ok: boolean;
+    description?: string;
+    result?: T;
+  };
+  if (!json.ok)
+    throw new Error(`telegram ${method}: ${json.description ?? 'unknown'}`);
+  return json.result as T;
+}
+
+export function accountFor(args: { account?: string; line?: string }): string {
+  return resolveAccountId(
+    accounts,
+    args,
+    (line) => Line.parseTelegram(line)?.accountId,
+  );
+}
+
+export function lineOf(
+  accountId: string,
+  chatId: number | string,
+  topicId?: number,
+): string {
+  const tail = topicId !== undefined ? `${chatId}/${topicId}` : `${chatId}`;
+  return `metro://telegram/${accountId}/${tail}`;
+}
+
+export function targetOf(
+  line: string,
+  accountOverride?: string,
+): { accountId: string; chatId: number; topicId?: number } {
+  const parsed = Line.parseTelegram(line);
+  if (!parsed) throw new Error(`bad telegram line: ${line}`);
+  return { ...parsed, accountId: accountOverride ?? parsed.accountId };
+}