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

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

@@ -0,0 +1,87 @@
+import type { Message } from '@mtcute/bun';
+import { FileLocation } from '@mtcute/bun';
+import {
+  saveBufferToCache,
+  type SavedAttachment,
+} from '@metro-labs/mcp/stations/attachments';
+import type { UserClient } from './client.js';
+
+type Media = NonNullable<Message['media']>;
+export type DownloadableMedia = Media & FileLocation;
+
+export function isDownloadable(media: Media): media is DownloadableMedia {
+  return media instanceof FileLocation;
+}
+
+interface MediaMeta {
+  mime?: string;
+  name?: string;
+}
+
+function fallbackMime(media: DownloadableMedia): string | undefined {
+  const type = (media as { type?: unknown }).type;
+  if (type === 'photo') return 'image/jpeg';
+  if (type === 'sticker') return 'image/webp';
+  return undefined;
+}
+
+function metaOf(media: DownloadableMedia): MediaMeta {
+  const withMime = media as { mimeType?: unknown };
+  const withName = media as { fileName?: unknown };
+  const mime =
+    (typeof withMime.mimeType === 'string' ? withMime.mimeType : undefined) ??
+    fallbackMime(media);
+  const name =
+    typeof withName.fileName === 'string' ? withName.fileName : undefined;
+  return {
+    ...(mime ? { mime } : {}),
+    ...(name ? { name } : {}),
+  };
+}
+
+export interface PendingDescriptor {
+  kind: string;
+  name?: string;
+}
+
+const KIND_BY_TYPE: Record<string, string> = {
+  photo: 'image',
+  sticker: 'image',
+  voice: 'audio',
+  audio: 'audio',
+  video: 'video',
+  video_note: 'video',
+  animation: 'video',
+};
+
+function mediaType(media: DownloadableMedia): string {
+  const type = (media as { type?: unknown }).type;
+  return typeof type === 'string' ? type : '';
+}
+
+function kindOf(media: DownloadableMedia, mime: string | undefined): string {
+  const byType = KIND_BY_TYPE[mediaType(media)];
+  if (byType) return byType;
+  if (mime?.startsWith('image/')) return 'image';
+  if (mime?.startsWith('audio/')) return 'audio';
+  if (mime?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+export function pendingDescriptorOf(media: DownloadableMedia): PendingDescriptor {
+  const meta = metaOf(media);
+  return {
+    kind: kindOf(media, meta.mime),
+    ...(meta.name ? { name: meta.name } : {}),
+  };
+}
+
+export async function downloadMedia(
+  client: UserClient,
+  media: DownloadableMedia,
+  messageId: string,
+  index = 0,
+): Promise<SavedAttachment> {
+  const buf = await client.tg.downloadAsBuffer(media);
+  return saveBufferToCache(buf, messageId, index, metaOf(media));
+}

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

@@ -0,0 +1,77 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { TelegramClient } from '@mtcute/bun';
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import type { UserAccount } from './types.js';
+
+const STATE_DIR =
+  process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+
+export interface Self {
+  username: string | null;
+  phone: string | null;
+}
+
+export interface UserClient {
+  account: UserAccount;
+  tg: TelegramClient;
+  self: () => Self | null;
+  connect: () => Promise<void>;
+  startUpdates: () => Promise<void>;
+  disconnect: () => Promise<void>;
+}
+
+function storagePath(accountId: string): string {
+  const dir = join(STATE_DIR, 'telegram-user');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${accountId}.session`);
+}
+
+export function createClient(account: UserAccount): UserClient {
+  const apiId = account.apiId ?? 0;
+  const { apiHash } = account;
+  if (!Number.isInteger(apiId) || apiId <= 0 || !apiHash)
+    throw new TrainError(
+      'telegram_user_auth',
+      `account '${account.id}' missing apiId/apiHash`,
+    );
+  const tg = new TelegramClient({
+    apiId,
+    apiHash,
+    storage: storagePath(account.id),
+  });
+
+  let me: Self | null = null;
+
+  const connect = async (): Promise<void> => {
+    try {
+      await tg.importSession(account.session);
+      await tg.connect();
+    } catch (e) {
+      throw new TrainError(
+        'telegram_user_auth',
+        `account '${account.id}' connect failed: ${errMsg(e)}`,
+      );
+    }
+    try {
+      const user = await tg.getMe();
+      me = { username: user.username ?? null, phone: user.phoneNumber ?? null };
+    } catch (e) {
+      process.stderr.write(
+        `telegram-user[${account.id}] identity unavailable: ${errMsg(e)}\n`,
+      );
+    }
+  };
+
+  const startUpdates = async (): Promise<void> => {
+    await tg.startUpdatesLoop();
+  };
+
+  const disconnect = async (): Promise<void> => {
+    await tg.disconnect();
+  };
+
+  return { account, tg, self: () => me, connect, startUpdates, disconnect };
+}

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

@@ -0,0 +1,141 @@
+import type { Chat, Message, Peer, User } from '@mtcute/bun';
+import type { SavedAttachment } from '@metro-labs/mcp/stations/attachments';
+import { lineOf } from './accounts.js';
+import { mintId } from './wire.js';
+import { isDownloadable, pendingDescriptorOf } from './attachments.js';
+
+const isUser = (peer: Peer): peer is User => peer.type === 'user';
+const isChat = (peer: Peer): peer is Chat => peer.type === 'chat';
+
+export function senderName(peer: Peer): string | undefined {
+  if (isUser(peer)) return peer.username ? `@${peer.username}` : peer.firstName;
+  return peer.title;
+}
+
+export function displayName(peer: Peer): string | undefined {
+  if (isUser(peer)) return peer.firstName;
+  return peer.title;
+}
+
+function chatName(peer: Peer): string | undefined {
+  if (isChat(peer)) return peer.title;
+  if (isUser(peer)) return peer.username ? `@${peer.username}` : peer.firstName;
+  return undefined;
+}
+
+function topicOf(m: Message): number | undefined {
+  if (!m.isTopicMessage) return undefined;
+  const threadId = m.replyToMessage?.threadId;
+  return threadId ?? undefined;
+}
+
+function mediaTag(m: Message): string | undefined {
+  if (m.media === null) return undefined;
+  return `[${m.media.type}]`;
+}
+
+function projectText(m: Message): string {
+  const tag = mediaTag(m);
+  return [m.text, tag].filter(Boolean).join(' ');
+}
+
+export function isOwnEcho(m: Message): boolean {
+  if (m.isOutgoing) return true;
+  const { sender } = m;
+  return isUser(sender) && sender.isSelf;
+}
+
+export function envelope(
+  accountId: string,
+  m: Message,
+): Record<string, unknown> {
+  const topicId = topicOf(m);
+  const line = lineOf(accountId, m.chat.id, topicId);
+  const isPrivate = isUser(m.chat);
+  const { media } = m;
+  const attachments =
+    media !== null && isDownloadable(media)
+      ? [pendingDescriptorOf(media)]
+      : undefined;
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: m.date.toISOString(),
+    station: 'telegram-user',
+    line,
+    line_name: chatName(m.chat),
+    from: `metro://telegram-user/${accountId}/user/${m.sender.id}`,
+    from_name: senderName(m.sender),
+    from_display_name: displayName(m.sender),
+    message_id: String(m.id),
+    text: projectText(m),
+    is_private: isPrivate,
+    has_media: media !== null,
+    payload: {
+      account: accountId,
+      message_id: String(m.id),
+      ...(attachments ? { attachments } : {}),
+    },
+  };
+}
+
+export function attachmentSavedEnvelope(
+  accountId: string,
+  line: string,
+  sourceEnvId: string,
+  saved: SavedAttachment,
+  index = 0,
+): Record<string, unknown> {
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: 'telegram-user',
+    line,
+    from: `metro://telegram-user/${accountId}/self`,
+    text: `📎 saved: ${saved.path}`,
+    payload: {
+      account: accountId,
+      contentType: 'attachmentSaved',
+      attachmentFor: sourceEnvId,
+      index,
+      attachmentPath: saved.path,
+      localPath: saved.path,
+      mime: saved.mime,
+      name: saved.name,
+    },
+  };
+}
+
+export interface ReactionInput {
+  accountId: string;
+  chatId: number;
+  messageId: number;
+  emoji: string;
+  senderId: number;
+  date: Date;
+  isPrivate: boolean;
+  senderName?: string;
+  removed?: boolean;
+}
+
+export function reactionEnvelope(r: ReactionInput): Record<string, unknown> {
+  return {
+    kind: 'react',
+    id: mintId(),
+    ts: r.date.toISOString(),
+    station: 'telegram-user',
+    line: lineOf(r.accountId, r.chatId),
+    from: `metro://telegram-user/${r.accountId}/user/${r.senderId}`,
+    from_name: r.senderName,
+    message_id: String(r.messageId),
+    emoji: r.emoji,
+    event: { type: 'react', emoji: r.emoji, targetId: String(r.messageId) },
+    is_private: r.isPrivate,
+    payload: {
+      account: r.accountId,
+      message_id: String(r.messageId),
+      removed: r.removed === true,
+    },
+  };
+}

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

@@ -0,0 +1,261 @@
+import type {
+  GroupResult,
+  MemberOutcome,
+} from '@metro-labs/mcp/stations/types';
+import { TrainError } from '@metro-labs/mcp/train-error';
+import { errMsg } from '@metro-labs/mcp/log';
+import type { UserClient } from './client.js';
+import { lineOf } from './accounts.js';
+
+export interface MissingInvitee {
+  userId: number;
+}
+
+interface CreateGroupResponse {
+  chat: { id: number };
+  missing: MissingInvitee[];
+}
+
+interface InviteLink {
+  link: string;
+}
+
+interface TgGroup {
+  createGroup: (p: {
+    title: string;
+    users: string[];
+  }) => Promise<CreateGroupResponse>;
+  addChatMembers: (
+    chatId: number,
+    users: string[],
+    params: { forwardCount: number },
+  ) => Promise<MissingInvitee[]>;
+  kickChatMember: (p: { chatId: number; userId: string }) => Promise<unknown>;
+  exportInviteLink: (chatId: number) => Promise<InviteLink>;
+  resolvePeer: (peer: string) => Promise<{
+    userId?: number;
+    channelId?: number;
+    chatId?: number;
+  }>;
+}
+
+const tgGroup = (client: UserClient): TgGroup => {
+  const tg: unknown = client.tg;
+  return tg as TgGroup;
+};
+
+const INVITE_REASON =
+  'could not be direct-added (not a mutual contact or privacy-restricted); share the invite link';
+
+const ADD_FAILURE_CODES = [
+  'CHAT_MEMBER_ADD_FAILED',
+  'USER_PRIVACY_RESTRICTED',
+  'USER_NOT_MUTUAL_CONTACT',
+  'USER_CHANNELS_TOO_MUCH',
+  'USER_ALREADY_PARTICIPANT',
+  'USER_BLOCKED',
+  'USER_BOT',
+  'USER_KICKED',
+  'PEER_FLOOD',
+  'USERS_TOO_MUCH',
+];
+
+function isAddFailure(e: unknown): boolean {
+  const msg = errMsg(e).toUpperCase();
+  return ADD_FAILURE_CODES.some((code) => msg.includes(code));
+}
+
+const added = (id: string): MemberOutcome => ({ id, status: 'added' });
+const invited = (id: string): MemberOutcome => ({
+  id,
+  status: 'invited',
+  reason: INVITE_REASON,
+});
+
+function membersOf(args: Record<string, unknown>): string[] {
+  const raw = args.members;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((v) => typeof v === 'string' && v.length > 0) as string[];
+}
+
+async function addOne(
+  client: UserClient,
+  chatId: number,
+  member: string,
+): Promise<MemberOutcome> {
+  try {
+    const missing = await tgGroup(client).addChatMembers(chatId, [member], {
+      forwardCount: 0,
+    });
+    return missing.length ? invited(member) : added(member);
+  } catch (e) {
+    if (isAddFailure(e)) return invited(member);
+    throw e;
+  }
+}
+
+interface CreatedChat {
+  chatId: number;
+  outcomes: MemberOutcome[];
+}
+
+async function createWithAll(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  const res = await tgGroup(client).createGroup({ title, users: members });
+  const missing = new Set(res.missing.map((m) => m.userId));
+  const outcomes: MemberOutcome[] = [];
+  for (const m of members) {
+    const uid = await idOf(client, m);
+    outcomes.push(
+      uid !== null && missing.has(Number(uid)) ? invited(m) : added(m),
+    );
+  }
+  return { chatId: res.chat.id, outcomes };
+}
+
+async function createPerMember(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  let chatId: number | null = null;
+  const outcomes: MemberOutcome[] = [];
+  const pending: string[] = [];
+  for (const m of members) {
+    if (chatId !== null) {
+      pending.push(m);
+      continue;
+    }
+    try {
+      const res = await tgGroup(client).createGroup({ title, users: [m] });
+      chatId = res.chat.id;
+      outcomes.push(res.missing.length ? invited(m) : added(m));
+    } catch (e) {
+      if (!isAddFailure(e)) throw e;
+      outcomes.push(invited(m));
+    }
+  }
+  if (chatId === null)
+    throw new TrainError(
+      'telegram_user_call',
+      'could not create group: no requested member could be added',
+    );
+  for (const m of pending) outcomes.push(await addOne(client, chatId, m));
+  return { chatId, outcomes };
+}
+
+async function createChat(
+  client: UserClient,
+  title: string,
+  members: string[],
+): Promise<CreatedChat> {
+  try {
+    return await createWithAll(client, title, members);
+  } catch (e) {
+    if (!isAddFailure(e)) throw e;
+    return createPerMember(client, title, members);
+  }
+}
+
+async function finalize(
+  client: UserClient,
+  base: GroupResult,
+  chatId: number,
+  outcomes: MemberOutcome[],
+): Promise<GroupResult> {
+  const result: GroupResult = { ...base, members: outcomes };
+  if (outcomes.some((o) => o.status === 'invited'))
+    result.inviteLink = (await tgGroup(client).exportInviteLink(chatId)).link;
+  return result;
+}
+
+async function idOf(client: UserClient, member: string): Promise<string | null> {
+  const trimmed = member.replace(/^@/, '');
+  if (/^-?\d+$/.test(trimmed)) return trimmed;
+  try {
+    const peer = await tgGroup(client).resolvePeer(member);
+    const uid = peer.userId ?? peer.channelId ?? peer.chatId;
+    return uid !== undefined ? String(uid) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function groupCreate(
+  client: UserClient,
+  accountId: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const name = typeof args.name === 'string' ? args.name : '';
+  if (!name) throw new TrainError('bad_request', 'groupCreate requires a `name`');
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupCreate requires `members`');
+  const { chatId, outcomes } = await createChat(client, name, members);
+  return finalize(
+    client,
+    {
+      capability: { supported: true },
+      line: lineOf(accountId, chatId),
+      id: String(chatId),
+      name,
+    },
+    chatId,
+    outcomes,
+  );
+}
+
+export async function groupAddMembers(
+  client: UserClient,
+  chatId: number,
+  line: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupAddMembers requires `members`');
+  const outcomes: MemberOutcome[] = [];
+  for (const m of members) outcomes.push(await addOne(client, chatId, m));
+  return finalize(
+    client,
+    { capability: { supported: true }, line, id: String(chatId) },
+    chatId,
+    outcomes,
+  );
+}
+
+export async function groupRemoveMembers(
+  client: UserClient,
+  chatId: number,
+  line: string,
+  args: Record<string, unknown>,
+): Promise<GroupResult> {
+  const members = membersOf(args);
+  if (!members.length)
+    throw new TrainError('bad_request', 'groupRemoveMembers requires `members`');
+  for (const m of members)
+    await tgGroup(client).kickChatMember({ chatId, userId: m });
+  return {
+    capability: { supported: true },
+    line,
+    id: String(chatId),
+    members: members.map((id) => ({ id, status: 'removed' as const })),
+  };
+}
+
+export async function groupInviteLink(
+  client: UserClient,
+  chatId: number,
+  line: string,
+): Promise<GroupResult> {
+  const link = await tgGroup(client).exportInviteLink(chatId);
+  return {
+    capability: { supported: true },
+    line,
+    id: String(chatId),
+    inviteLink: link.link,
+  };
+}

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

@@ -0,0 +1,52 @@
+import type { Message } from '@mtcute/bun';
+import { lineOf } from './accounts.js';
+import { displayName, senderName } from './format.js';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+export function clampLimit(limit: unknown): number {
+  const n = typeof limit === 'number' ? limit : Number(limit);
+  if (!Number.isFinite(n)) return DEFAULT_LIMIT;
+  return Math.min(Math.max(1, Math.trunc(n)), MAX_LIMIT);
+}
+
+function senderUri(accountId: string, m: Message): string {
+  return `metro://telegram-user/${accountId}/user/${m.sender.id}`;
+}
+
+function textOf(m: Message): string {
+  if (m.text) return m.text;
+  if (m.media !== null) return `[${m.media.type}]`;
+  return '';
+}
+
+export interface ReadMessage {
+  id: string;
+  ts: string;
+  from: string;
+  from_name?: string;
+  from_display_name?: string;
+  text: string;
+}
+
+export function shapeHistory(
+  accountId: string,
+  chatId: number,
+  messages: readonly Message[],
+): { line: string; count: number; messages: ReadMessage[] } {
+  const ordered = [...messages].reverse();
+  const shaped = ordered.map((m) => ({
+    id: String(m.id),
+    ts: m.date.toISOString(),
+    from: senderUri(accountId, m),
+    from_name: senderName(m.sender),
+    from_display_name: displayName(m.sender),
+    text: textOf(m),
+  }));
+  return {
+    line: lineOf(accountId, chatId),
+    count: shaped.length,
+    messages: shaped,
+  };
+}

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

@@ -0,0 +1,78 @@
+import type { Message } from '@mtcute/bun';
+import { errMsg, log } from '@metro-labs/mcp/log';
+import { emit } from './wire.js';
+import { envelope, isOwnEcho, attachmentSavedEnvelope } from './format.js';
+import { downloadMedia, isDownloadable } from './attachments.js';
+import { subscribeReactions } from './reactions.js';
+import type { UserClient } from './client.js';
+
+async function saveMediaAndEmit(
+  client: UserClient,
+  m: Message,
+  env: Record<string, unknown>,
+): Promise<void> {
+  const { media } = m;
+  if (media === null || !isDownloadable(media)) return;
+  const accountId = client.account.id;
+  try {
+    const saved = await downloadMedia(client, media, String(m.id), 0);
+    emit(
+      attachmentSavedEnvelope(
+        accountId,
+        env.line as string,
+        env.id as string,
+        saved,
+      ),
+    );
+  } catch (e) {
+    process.stderr.write(
+      `telegram-user[${accountId}] media save failed: ${errMsg(e)}\n`,
+    );
+  }
+}
+
+function emitMessage(client: UserClient, m: Message): void {
+  log.debug(
+    { train: 'telegram-user', account: client.account.id, messageId: m.id },
+    'inbound message received',
+  );
+  if (isOwnEcho(m)) return;
+  const env = envelope(client.account.id, m);
+  emit(env);
+  if (m.media !== null)
+    saveMediaAndEmit(client, m, env).catch((err: unknown) => {
+      process.stderr.write(
+        `telegram-user[${client.account.id}] media save failed: ${errMsg(err)}\n`,
+      );
+    });
+}
+
+function subscribe(client: UserClient): void {
+  const accountId = client.account.id;
+  const onMessage = (m: Message): void => {
+    try {
+      emitMessage(client, m);
+    } catch (e) {
+      process.stderr.write(
+        `telegram-user[${accountId}] normalize failed: ${errMsg(e)}\n`,
+      );
+    }
+  };
+  client.tg.onNewMessage.add(onMessage);
+  client.tg.onEditMessage.add(onMessage);
+  subscribeReactions(client);
+}
+
+export async function startInbound(client: UserClient): Promise<void> {
+  const accountId = client.account.id;
+  try {
+    subscribe(client);
+    await client.connect();
+    await client.startUpdates();
+    process.stderr.write(`telegram-user[${accountId}] inbound connected\n`);
+  } catch (e) {
+    process.stderr.write(
+      `telegram-user[${accountId}] connect failed: ${errMsg(e)}\n`,
+    );
+  }
+}