@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,96 @@
+import { join } from 'node:path';
+import { isRecord } from './is-record.js';
+
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const SKILL_HASH = /^[a-f0-9]{64}$/;
+export const SKILL_COMMIT = /^[a-f0-9]{40}$/;
+export const SKILL_FILE_MAX = 256 * 1024;
+export const SKILL_TOTAL_MAX = 8 * 1024 * 1024;
+export const SKILL_FILES_MAX = 256;
+export const SKILL_MANIFEST_MAX = 128 * 1024;
+
+export interface SkillSource {
+  repository: string;
+  ref: string;
+  folder: string;
+}
+
+export interface SkillFile {
+  path: string;
+  size: number;
+  sha256: string;
+  executable?: boolean;
+}
+
+export interface SkillGeneration {
+  id: string;
+  source: (SkillSource & { repositoryId: number; commit: string }) | null;
+  createdAt: string;
+  skills: { name: string; description: string }[];
+  files: SkillFile[];
+}
+
+export interface SkillActivation {
+  generation: string | null;
+  loading: string | null;
+  rollback?: string | null;
+  appliedAt: string | null;
+  problem: string | null;
+  shadowed: string[];
+}
+
+export const skillSourceRoot = (claudeDir: string): string => join(claudeDir, 'metro-github');
+export const skillRelease = (root: string, id: string): string => {
+  if (!SKILL_HASH.test(id)) throw new Error('Invalid skills generation.');
+  return join(root, 'releases', id);
+};
+
+export function skillPath(path: string): boolean {
+  const parts = path.split('/');
+  return path.length <= 240 && parts.length >= 2 && parts.length <= 8 && SKILL_NAME.test(parts[0] ?? '') &&
+    parts.every((part) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(part)) &&
+    !parts.slice(1, -1).includes('SKILL.md') && !(parts.length > 2 && parts.at(-1) === 'SKILL.md');
+}
+
+function manifestSkill(value: unknown): SkillGeneration['skills'][number] {
+  if (!isRecord(value) || typeof value.name !== 'string' || !SKILL_NAME.test(value.name) || typeof value.description !== 'string' || value.description.length > 1024) throw new Error('Invalid skill name or description.');
+  return { name: value.name, description: value.description };
+}
+
+function fileSize(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > SKILL_FILE_MAX) throw new Error('Invalid skills file size.');
+  return value;
+}
+
+function manifestFile(value: unknown): SkillFile {
+  if (!isRecord(value)) throw new Error('Invalid skills file.');
+  if (typeof value.path !== 'string' || !skillPath(value.path) || typeof value.sha256 !== 'string' || !SKILL_HASH.test(value.sha256)) throw new Error('Invalid skills file path or hash.');
+  return { path: value.path, size: fileSize(value.size), sha256: value.sha256, ...(value.executable === true ? { executable: true } : {}) };
+}
+
+function manifestSource(s: unknown): SkillGeneration['source'] {
+  if (s === null) return null;
+  if (!isRecord(s) || typeof s.repository !== 'string' || typeof s.ref !== 'string' || typeof s.folder !== 'string' || typeof s.repositoryId !== 'number' || typeof s.commit !== 'string' || !SKILL_COMMIT.test(s.commit)) throw new Error('Invalid skills provenance.');
+  return { repository: s.repository, ref: s.ref, folder: s.folder, repositoryId: s.repositoryId, commit: s.commit };
+}
+
+function checkFiles(skills: SkillGeneration['skills'], files: SkillFile[]): void {
+  if (files.reduce((sum, file) => sum + file.size, 0) > SKILL_TOTAL_MAX || new Set(files.map((f) => f.path.toLowerCase())).size !== files.length || new Set(skills.map((s) => s.name)).size !== skills.length) throw new Error('Duplicate or oversized skills files.');
+  if (files.some((f) => !skills.some((s) => f.path.startsWith(`${s.name}/`))) || skills.some((s) => !files.some((f) => f.path === `${s.name}/SKILL.md`))) throw new Error('Every skill needs its own SKILL.md.');
+}
+
+function boundedGeneration(generation: SkillGeneration): SkillGeneration {
+  if (Buffer.byteLength(JSON.stringify(generation)) > SKILL_MANIFEST_MAX) throw new Error('Skills manifest is too large.');
+  return generation;
+}
+
+export function skillGeneration(raw: unknown): SkillGeneration {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !SKILL_HASH.test(raw.id) || typeof raw.createdAt !== 'string' || !Array.isArray(raw.skills) || !Array.isArray(raw.files)) throw new Error('Invalid skills manifest.');
+  if (raw.skills.length > 64 || raw.files.length > SKILL_FILES_MAX) throw new Error('Skills manifest is too large.');
+  const skills = raw.skills.map(manifestSkill);
+  const files = raw.files.map(manifestFile);
+  const source = manifestSource(raw.source);
+  checkFiles(skills, files);
+  if (source === null) checkFiles([], files);
+  return boundedGeneration({ id: raw.id, source, createdAt: raw.createdAt, skills, files });
+}

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

@@ -0,0 +1,14 @@
+export const STATIONS = [
+  'xmtp',
+  'telegram-bot',
+  'telegram',
+  'discord-bot',
+  'whatsapp',
+  'threema',
+  'outlook',
+  'gmail',
+  'webhook',
+] as const;
+
+export type StationName = (typeof STATIONS)[number];
+

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/account-files.ts

@@ -0,0 +1,41 @@
+import { readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { log } from '../log.js';
+
+export interface AccountFiles {
+  path: (accountId: string) => string;
+  forget: (accountId: string) => void;
+  forgetExcept: (keptAccountIds: readonly string[]) => void;
+}
+
+const safeSegment = (s: string): string => s.replace(/[^A-Za-z0-9_-]/g, '_');
+
+function listed(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+export function accountFiles(dirEnv: string, prefix: string): AccountFiles {
+  const dir = (): string => process.env[dirEnv] ?? join(homedir(), '.metro');
+  const name = (accountId: string): string => `${prefix}${safeSegment(accountId)}.json`;
+  const remove = (file: string, reason: string): void => {
+    rmSync(join(dir(), file), { force: true });
+    log.info({ file: join(dir(), file) }, reason);
+  };
+  return {
+    path: (accountId) => join(dir(), name(accountId)),
+    forget: (accountId) => {
+      remove(name(accountId), 'station: removed the files of a detached account');
+    },
+    forgetExcept: (keptAccountIds) => {
+      const kept = new Set(keptAccountIds.map(name));
+      for (const file of listed(dir()))
+        if (file.startsWith(prefix) && file.endsWith('.json') && !kept.has(file))
+          remove(file, 'station: removed the files of an account that is no longer attached');
+    },
+  };
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/account-store.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg } from '../log.js';
+import { chmodIfExists } from '../secure-fs.js';
+
+export type Die = (msg: string) => never;
+
+export interface AccountStoreOpts<T> {
+  prefix: string;
+  validate?: (raw: T[], die: Die) => void;
+}
+
+export interface Loader<T> {
+  die: Die;
+  loadAccounts: () => T[];
+}
+
+const envName = (prefix: string): string =>
+  `${prefix.toUpperCase().replace(/-/g, '_')}_ACCOUNTS_FILE`;
+
+const accountsFile = (prefix: string): string =>
+  process.env[envName(prefix)] ?? join(homedir(), '.metro', `${prefix}-accounts.json`);
+
+function checkIds(raw: { id: string }[], die: Die): void {
+  const seen = new Set<string>();
+  for (const a of raw) {
+    if (!a.id) die('account missing id');
+    if (seen.has(a.id)) die(`duplicate account id '${a.id}'`);
+    seen.add(a.id);
+  }
+}
+
+function readList<T>(file: string, die: Die): T[] {
+  if (!existsSync(file))
+    return die(
+      `no accounts file ${file} — the daemon writes it from ~/.metro/agents/agent.json at boot; attach an account to this station from the page first`,
+    );
+  chmodIfExists(file);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return die(`bad ${file}: ${errMsg(e)}`);
+  }
+  if (!Array.isArray(raw) || raw.length === 0)
+    return die(`${file} must be a non-empty array`);
+  return raw as T[];
+}
+
+export function makeAccountStore<T extends { id: string }>(
+  opts: AccountStoreOpts<T>,
+): Loader<T> {
+  const die: Die = (msg) => {
+    process.stderr.write(`${opts.prefix}: ${msg}\n`);
+    process.exit(2);
+  };
+
+  function loadAccounts(): T[] {
+    const raw = readList<T>(accountsFile(opts.prefix), die);
+    checkIds(raw, die);
+    opts.validate?.(raw, die);
+    return raw;
+  }
+
+  return { die, loadAccounts };
+}
+
+export function resolveAccountId(
+  accounts: Map<string, unknown>,
+  args: { account?: string; line?: string },
+  parseAccountId: (line: string) => string | undefined,
+): string {
+  const have = [...accounts.keys()];
+  let id = args.account;
+  id ??= args.line ? parseAccountId(args.line) : undefined;
+  id ??= have.length === 1 ? have[0] : undefined;
+  if (id === undefined)
+    throw new Error(`name an account (have: ${have.join(', ')})`);
+  if (!accounts.has(id))
+    throw new Error(`unknown account '${id}' (have: ${have.join(', ')})`);
+  return id;
+}

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

@@ -0,0 +1,202 @@
+export const attachDir = (): string =>
+  process.env.METRO_XMTP_ATTACH_DIR ??
+  `${process.env.HOME}/.cache/metro/messenger-uploads`;
+
+const CACHE_NAME_RE = /^msg_[A-Za-z0-9]{1,16}_\d+\.[A-Za-z0-9]{1,5}$/;
+
+export const resolveCachedAttachment = (name: string): string | null =>
+  CACHE_NAME_RE.test(name) ? `${attachDir()}/${name}` : null;
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/heic': 'heic',
+  'audio/mp4': 'm4a',
+  'audio/mpeg': 'mp3',
+  'audio/ogg': 'ogg',
+  'audio/wav': 'wav',
+  'video/mp4': 'mp4',
+  'video/quicktime': 'mov',
+  'video/webm': 'webm',
+  'application/pdf': 'pdf',
+};
+
+const extFromName = (filename: string | undefined): string | undefined => {
+  const ext = filename
+    ?.split('?')[0]
+    ?.split('#')[0]
+    ?.split('.')
+    .pop()
+    ?.toLowerCase();
+  return ext !== undefined && ext.length >= 1 && ext.length <= 5
+    ? ext
+    : undefined;
+};
+
+export const extFromMime = (mime: string | undefined): string | undefined => {
+  if (mime === undefined) return undefined;
+  const mapped = MIME_EXT[mime];
+  if (mapped) return mapped;
+  if (mime.startsWith('image/')) return mime.slice(6).replace('jpeg', 'jpg');
+  return undefined;
+};
+
+const extFor = (
+  filename: string | undefined,
+  mime: string | undefined,
+): string => extFromName(filename) ?? extFromMime(mime) ?? 'bin';
+
+const cacheFileName = (
+  messageId: string,
+  index: number,
+  filename: string | undefined,
+  mime: string | undefined,
+): string => {
+  const safeId =
+    messageId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 16) || 'unknown';
+  return `msg_${safeId}_${index}.${extFor(filename, mime)}`;
+};
+
+export interface SavedAttachment {
+  path: string;
+  mime?: string;
+  name?: string;
+  bytes: number;
+}
+
+export const MAX_ATTACHMENT_BYTES = Number(
+  process.env.METRO_ATTACH_MAX_BYTES ?? 100 * 1024 * 1024,
+);
+
+export function assertAttachmentSize(bytes: number): void {
+  if (bytes > MAX_ATTACHMENT_BYTES)
+    throw new Error(
+      `attachment size ${bytes} exceeds limit of ${MAX_ATTACHMENT_BYTES} bytes`,
+    );
+}
+
+export function assertContentLength(header: string | null | undefined): void {
+  if (header == null) return;
+  const n = Number(header);
+  if (Number.isFinite(n)) assertAttachmentSize(n);
+}
+
+const cachePathFor = async (
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<string> => {
+  const { mkdir } = await import('node:fs/promises');
+  const nodePath = await import('node:path');
+  const dir = attachDir();
+  await mkdir(dir, { recursive: true });
+  return nodePath.join(
+    dir,
+    cacheFileName(messageId, index, meta.name, meta.mime),
+  );
+};
+
+export const saveBufferToCache = async (
+  data: Uint8Array,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  assertAttachmentSize(data.length);
+  const { writeFile, rename, rm } = await import('node:fs/promises');
+  const { randomUUID } = await import('node:crypto');
+  const path = await cachePathFor(messageId, index, meta);
+  const part = `${await cachePathFor(randomUUID(), index, meta)}.part`;
+  try {
+    await writeFile(part, data);
+    await rename(part, path);
+  } finally {
+    await rm(part, { force: true });
+  }
+  return { path, mime: meta.mime, name: meta.name, bytes: data.length };
+};
+
+export const saveStreamToCache = async (
+  chunks: AsyncIterable<Uint8Array>,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  const { open, rename, rm } = await import('node:fs/promises');
+  const path = await cachePathFor(messageId, index, meta);
+  const part = `${path}.part`;
+  const handle = await open(part, 'w');
+  let bytes = 0;
+  try {
+    for await (const chunk of chunks) {
+      bytes += chunk.length;
+      assertAttachmentSize(bytes);
+      await handle.write(chunk);
+    }
+  } catch (err) {
+    await handle.close();
+    await rm(part, { force: true });
+    throw err;
+  }
+  await handle.close();
+  await rename(part, path);
+  return { path, mime: meta.mime, name: meta.name, bytes };
+};
+
+export const guessMime = (path: string): string => {
+  const ext = (path.split('.').pop() ?? '').toLowerCase();
+  const map: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    heic: 'image/heic',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    m4v: 'video/x-m4v',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+    pdf: 'application/pdf',
+  };
+  return map[ext] ?? 'application/octet-stream';
+};
+
+export const isImageMime = (mime: string): boolean =>
+  mime.toLowerCase().startsWith('image/');
+export const isImageExt = (path: string): boolean =>
+  /\.(png|jpe?g|gif|webp|heic|bmp|svg)$/i.test(path);
+
+export const appendFile = async (
+  form: FormData,
+  field: string,
+  path: string,
+  name: string,
+): Promise<void> => {
+  const data = await Bun.file(path).arrayBuffer();
+  form.append(field, new Blob([data]), name);
+};
+
+export const kindOf = (mime: string, path: string): string => {
+  if (isImageMime(mime) || isImageExt(path)) return 'image';
+  if (mime.startsWith('video/')) return 'video';
+  if (mime.startsWith('audio/')) return 'audio';
+  return 'file';
+};
+
+export const toCanonical = (a: {
+  path: string;
+  mime: string;
+  name: string;
+}): Record<string, unknown> => ({
+  kind: kindOf(a.mime, a.path),
+  path: a.path,
+  name: a.name,
+  mime: a.mime,
+});

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/channel-directory.ts

@@ -0,0 +1,159 @@
+import { Line } from '../lines.js';
+import { ticketStore } from '../tickets.js';
+import { TrainError } from '../train-error.js';
+
+export const DIRECTORY_LIMIT = 5000;
+const SNAPSHOT_BYTES = 2 * 1024 * 1024;
+const CURSOR_TTL = 5 * 60 * 1000;
+const KINDS = new Set(['direct', 'group', 'channel', 'thread']);
+
+export interface ChannelEntry {
+  id: string;
+  line: string;
+  name?: string;
+  kind: 'direct' | 'group' | 'channel' | 'thread';
+}
+
+export interface ChannelCapability {
+  supported: boolean;
+  complete: boolean;
+  source: 'remote' | 'local' | 'mixed' | 'unsupported';
+  reason?: string;
+}
+
+export interface ChannelSnapshot {
+  channels: ChannelEntry[];
+  capability: ChannelCapability;
+}
+
+export interface ChannelList extends ChannelSnapshot {
+  next_cursor?: string;
+}
+
+export interface ChannelOptions {
+  query: string;
+  limit: number;
+  cursor?: string;
+}
+
+function cursorOf(cursor: unknown): string | undefined {
+  if (cursor === undefined) return undefined;
+  if (typeof cursor !== 'string' || !cursor || cursor.length > 2048)
+    throw new TrainError('bad_request', 'cursor must be a nonempty string of at most 2048 characters');
+  return cursor;
+}
+
+export function channelOptions(args: Record<string, unknown>): ChannelOptions {
+  const { query = '', limit = 50 } = args;
+  if (typeof query !== 'string' || query.length > 200)
+    throw new TrainError('bad_request', 'query must be a string of at most 200 characters');
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new TrainError('bad_request', 'limit must be an integer from 1 to 100');
+  const cursor = cursorOf(args.cursor);
+  return { query: query.trim().toLowerCase(), limit, ...(cursor === undefined ? {} : { cursor }) };
+}
+
+export function channelMatches(entry: ChannelEntry, query: string): boolean {
+  return [entry.id, entry.line, entry.name ?? ''].some((value) => value.toLowerCase().includes(query));
+}
+
+export function channelEntry(entry: ChannelEntry, account: string): ChannelEntry | undefined {
+  if (!entry.id || entry.id.length > 1024 || entry.line.length > 2048 || !KINDS.has(entry.kind))
+    return undefined;
+  const parsed = Line.parse(entry.line);
+  if (parsed?.path[0] !== account || parsed.path.length < 2) return undefined;
+  return {
+    id: entry.id,
+    line: entry.line,
+    kind: entry.kind,
+    ...(entry.name ? { name: Array.from(entry.name).slice(0, 256).join('') } : {}),
+  };
+}
+
+function limitedCapability(capability: ChannelCapability): ChannelCapability {
+  return {
+    ...capability,
+    complete: false,
+    reason: [capability.reason, 'Directory metadata exceeded the local size or entry limit; results are partial.']
+      .filter(Boolean).join(' '),
+  };
+}
+
+function bounded(snapshot: ChannelSnapshot, account: string, query: string): ChannelSnapshot {
+  const seen = new Set<string>();
+  const channels: ChannelEntry[] = [];
+  let bytes = 0;
+  let clipped = snapshot.channels.length > DIRECTORY_LIMIT;
+  for (const raw of snapshot.channels.slice(0, DIRECTORY_LIMIT)) {
+    const entry = channelEntry(raw, account);
+    if (!entry) {
+      clipped = true;
+      continue;
+    }
+    if (seen.has(entry.line)) continue;
+    bytes += Buffer.byteLength(JSON.stringify(entry));
+    if (bytes > SNAPSHOT_BYTES) {
+      clipped = true;
+      break;
+    }
+    seen.add(entry.line);
+    if (channelMatches(raw, query)) channels.push(entry);
+  }
+  channels.sort((a, b) => a.line < b.line ? -1 : Number(a.line > b.line));
+  return { channels, capability: clipped ? limitedCapability(snapshot.capability) : { ...snapshot.capability } };
+}
+
+interface Cursor {
+  account: string;
+  query: string;
+  snapshot: ChannelSnapshot;
+  offset: number;
+  expiresAt: number;
+}
+
+export class ChannelDirectory {
+  private readonly cursors = ticketStore<Cursor>(CURSOR_TTL, 32);
+
+  async list(
+    account: string,
+    args: Record<string, unknown>,
+    load: () => Promise<ChannelSnapshot>,
+  ): Promise<ChannelList> {
+    const options = channelOptions(args);
+    const cursor = options.cursor === undefined
+      ? {
+        account,
+        query: options.query,
+        snapshot: bounded(await load(), account, options.query),
+        offset: 0,
+        expiresAt: Date.now() + CURSOR_TTL,
+      }
+      : this.resume(options.cursor, account, options.query);
+    return this.page(cursor, options.limit);
+  }
+
+  private resume(ticket: string, account: string, query: string): Cursor {
+    const cursor = this.cursors.peek(ticket);
+    if (!cursor || cursor.account !== account || cursor.query !== query || cursor.expiresAt <= Date.now())
+      throw new TrainError('channel_cursor', 'Invalid or expired channel cursor; start a new listing for this account and query.');
+    return cursor;
+  }
+
+  private page(cursor: Cursor, limit: number): ChannelList {
+    const { snapshot, offset } = cursor;
+    const channels = snapshot.channels.slice(offset, offset + limit).map((entry) => ({ ...entry }));
+    const nextOffset = offset + channels.length;
+    if (nextOffset >= snapshot.channels.length)
+      return { channels, capability: { ...snapshot.capability } };
+    const { ticket } = this.cursors.mint({ ...cursor, offset: nextOffset });
+    return {
+      channels,
+      capability: {
+        ...snapshot.capability,
+        complete: false,
+        reason: [snapshot.capability.reason, 'More channels are available; follow next_cursor.'].filter(Boolean).join(' '),
+      },
+      next_cursor: ticket,
+    };
+  }
+}