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

package/runtime/node_modules/@metro-labs/outlook/src/html.ts

@@ -0,0 +1,72 @@
+export const MAX_TEXT_CHARS = 20_000;
+
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  ndash: '-',
+  mdash: '-',
+  hellip: '...',
+  rsquo: "'",
+  lsquo: "'",
+  rdquo: '"',
+  ldquo: '"',
+};
+
+function codePoint(n: number): string {
+  return Number.isInteger(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
+}
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name: string) => {
+    if (name.startsWith('#x') || name.startsWith('#X')) return codePoint(parseInt(name.slice(2), 16));
+    if (name.startsWith('#')) return codePoint(Number(name.slice(1)));
+    return ENTITIES[name.toLowerCase()] ?? whole;
+  });
+}
+
+export function htmlToText(html: string): string {
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(head|style|script|title)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<\/(p|div|tr|h[1-6]|blockquote|table|ul|ol)\s*>/gi, '\n')
+    .replace(/<(p|div|tr|h[1-6]|blockquote|table)\b[^>]*>/gi, '\n')
+    .replace(/<\/t[dh]\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, '');
+  return tidy(decodeEntities(text));
+}
+
+export function tidy(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t ]+/g, ' ')
+    .split('\n')
+    .map((l) => l.trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function capText(text: string, max = MAX_TEXT_CHARS): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n[... ${String(text.length - max)} more characters]`;
+}
+
+export function bodyText(body: { contentType?: unknown; content?: unknown } | undefined): string {
+  const content = typeof body?.content === 'string' ? body.content : '';
+  return String(body?.contentType).toLowerCase() === 'html' ? htmlToText(content) : tidy(content);
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '<br>');
+}

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

@@ -0,0 +1,104 @@
+import { log } from '@metro-labs/core/log';
+import { emitInbound, reportAttachment } from '@metro-labs/core/stations/train-events';
+import type { Account } from './accounts.js';
+import { listFiles, metaOf, saveFile, type MailFile } from './attachments.js';
+import { addressOf, inboundEnvelope, MESSAGE_FIELDS, type GraphMessage } from './format.js';
+import { graphJson, GraphGone } from './graph.js';
+import { noteSeen } from './state.js';
+import { screen, type Screened } from './trust.js';
+
+export const POLL_MS = Number(process.env.METRO_OUTLOOK_POLL_MS) || 30_000;
+
+const FIRST_PAGE = `/me/mailFolders/inbox/messages/delta?$select=${MESSAGE_FIELDS}`;
+const PAGE_SIZE = { prefer: 'odata.maxpagesize=50' };
+
+interface DeltaPage {
+  value?: GraphMessage[];
+  '@odata.nextLink'?: string;
+  '@odata.deltaLink'?: string;
+}
+
+function fresh(acct: Account, m: GraphMessage, since: string): boolean {
+  if (m['@removed'] !== undefined) return false;
+  if (acct.state.seen.includes(m.id)) return false;
+  if (addressOf(m.from) === acct.email) return false;
+  return Date.parse(m.receivedDateTime ?? '') >= Date.parse(since);
+}
+
+const reasonOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+async function screened(acct: Account, m: GraphMessage): Promise<Screened> {
+  return screen(acct, m).catch((err: unknown) => {
+    process.stderr.write(`outlook[${acct.id}] could not read the headers of a message, so it counts as unverified: ${reasonOf(err)}\n`);
+    return { verified: false };
+  });
+}
+
+async function deliver(acct: Account, m: GraphMessage): Promise<boolean> {
+  const verdict = await screened(acct, m);
+  if ('skip' in verdict) {
+    log.debug({ account: acct.id, reason: verdict.skip }, 'outlook: skipped an automated mail');
+    return false;
+  }
+  const files: MailFile[] =
+    m.hasAttachments === true
+      ? await listFiles(acct, m.id).catch((err: unknown) => {
+          process.stderr.write(`outlook[${acct.id}] could not list the files of a message: ${reasonOf(err)}\n`);
+          return [];
+        })
+      : [];
+  const env = inboundEnvelope(acct.id, acct.email, m, files.map(metaOf), verdict.verified);
+  emitInbound(acct.id, env);
+  const at = { station: 'outlook', account: acct.id, line: String(env.line), forId: String(env.id) };
+  for (const [index, file] of files.entries())
+    reportAttachment(saveFile(acct, m.id, file, index), { ...at, index }, { saved: { kind: file.kind, size: file.size }, failed: { kind: file.kind } });
+  return true;
+}
+
+async function walk(acct: Account, start: string, onMessage: (m: GraphMessage) => Promise<void>): Promise<string | null> {
+  let next: string | undefined = start;
+  while (next !== undefined) {
+    const page: DeltaPage = await graphJson<DeltaPage>(acct, next, { headers: PAGE_SIZE });
+    for (const m of page.value ?? []) await onMessage(m);
+    if (page['@odata.deltaLink'] !== undefined) return page['@odata.deltaLink'];
+    next = page['@odata.nextLink'];
+  }
+  return null;
+}
+
+export async function syncOnce(acct: Account): Promise<number> {
+  const state = acct.state;
+  const since = state.syncedAt;
+  if (state.deltaLink === null || since === null) {
+    state.syncedAt = since ?? new Date().toISOString();
+    state.deltaLink = await walk(acct, FIRST_PAGE, () => Promise.resolve());
+    acct.save();
+    return 0;
+  }
+  let count = 0;
+  try {
+    state.deltaLink = await walk(acct, state.deltaLink, async (m) => {
+      if (!fresh(acct, m, since)) return;
+      if (await deliver(acct, m)) count += 1;
+      noteSeen(state, m.id);
+    });
+  } catch (err) {
+    if (!(err instanceof GraphGone)) throw err;
+    state.deltaLink = null;
+  }
+  acct.save();
+  return count;
+}
+
+export function startPolling(acct: Account, intervalMs = POLL_MS): void {
+  const tick = (): void => {
+    syncOnce(acct)
+      .catch((err: unknown) => {
+        process.stderr.write(`outlook[${acct.id}] mail check failed: ${err instanceof Error ? err.message : String(err)}\n`);
+      })
+      .finally(() => {
+        setTimeout(tick, intervalMs);
+      });
+  };
+  tick();
+}

package/runtime/node_modules/@metro-labs/outlook/src/index.ts

@@ -0,0 +1,12 @@
+import { readCalls } from '@metro-labs/core/trains/protocol';
+import { announceAccounts } from '@metro-labs/core/stations/train-boot';
+import { Account, accounts, loadAccounts } from './accounts.js';
+import { handleCall } from './actions.js';
+import { startPolling } from './inbound.js';
+
+readCalls('outlook', handleCall);
+
+for (const cfg of loadAccounts()) accounts.set(cfg.id, new Account(cfg));
+announceAccounts('outlook', accounts.keys());
+
+for (const acct of accounts.values()) startPolling(acct);

package/runtime/node_modules/@metro-labs/outlook/src/login.ts

@@ -0,0 +1,150 @@
+import {
+  OutlookAuthError,
+  pollDeviceCode,
+  requestDeviceCode,
+  type DeviceCode,
+  type FetchLike,
+  type Poll,
+  type Tokens,
+} from './auth.js';
+import { authorizeUrl, newState, pkcePair, redeemCode, type Pkce } from './browser.js';
+import { verifyMailbox, type Mailbox } from './me.js';
+
+export { parseMailbox } from './me.js';
+
+export { OutlookAuthError as OutlookLoginError } from './auth.js';
+export { NOT_SET_UP } from './config.js';
+export { failureOf } from './auth.js';
+
+export interface OutlookLoginResult {
+  config: Record<string, unknown>;
+  identity: Record<string, string>;
+}
+
+export interface OutlookLoginEvents {
+  onDone: (result: OutlookLoginResult) => void;
+  onFailed: (message: string) => void;
+}
+
+export interface OutlookLoginDeps {
+  fetch?: FetchLike;
+  now?: () => number;
+  mailbox?: string | null;
+}
+
+const SLOW_DOWN_MS = 5_000;
+
+function resultOf(tokens: Tokens, tenantId: string | null, mailbox: Mailbox, now: number): OutlookLoginResult {
+  return {
+    config: {
+      accountEmail: mailbox.email,
+      refreshToken: tokens.refreshToken,
+      accessToken: tokens.accessToken,
+      expiresAt: tokens.expiresAt,
+      tenantId,
+      createdAt: new Date(now).toISOString(),
+    },
+    identity: { email: mailbox.email, ...(mailbox.name === '' ? {} : { name: mailbox.name }) },
+  };
+}
+
+export class OutlookBrowserLogin {
+  readonly state = newState();
+  readonly authorizeUrl: string;
+  private readonly pkce: Pkce = pkcePair();
+  private used = false;
+  private readonly fetchImpl: FetchLike;
+  private readonly now: () => number;
+  private readonly mailbox: string | null;
+
+  constructor(deps: OutlookLoginDeps = {}) {
+    this.fetchImpl = deps.fetch ?? ((input, init) => fetch(input, init));
+    this.now = deps.now ?? Date.now;
+    this.mailbox = deps.mailbox ?? null;
+    this.authorizeUrl = authorizeUrl(this.pkce.challenge, this.state, this.mailbox);
+  }
+
+  async finish(code: string, state: string): Promise<OutlookLoginResult> {
+    if (state !== this.state)
+      throw new OutlookAuthError('This sign-in link belongs to another attempt. Start again from the Channels page.');
+    if (this.used) throw new OutlookAuthError('This sign-in was already used. Start again from the Channels page.');
+    this.used = true;
+    const { tokens, tenantId } = await redeemCode(code, this.pkce.verifier, this.fetchImpl, this.now());
+    return resultOf(tokens, tenantId, await verifyMailbox(tokens.accessToken, this.fetchImpl, this.mailbox), this.now());
+  }
+}
+
+export class OutlookLogin {
+  private code: DeviceCode | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private stopped = false;
+  private readonly fetchImpl: FetchLike;
+  private readonly now: () => number;
+  private readonly mailbox: string | null;
+
+  constructor(private readonly events: OutlookLoginEvents, deps: OutlookLoginDeps = {}) {
+    this.fetchImpl = deps.fetch ?? ((input, init) => fetch(input, init));
+    this.now = deps.now ?? Date.now;
+    this.mailbox = deps.mailbox ?? null;
+  }
+
+  async start(): Promise<DeviceCode> {
+    const code = await requestDeviceCode(this.fetchImpl, this.now());
+    this.code = code;
+    this.schedule(code.intervalMs);
+    return code;
+  }
+
+  cancel(): Promise<void> {
+    this.stopped = true;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+    return Promise.resolve();
+  }
+
+  private schedule(delayMs: number): void {
+    if (this.stopped) return;
+    this.timer = setTimeout(() => {
+      this.tick().catch((err: unknown) => {
+        this.fail(err instanceof OutlookAuthError ? err.message : 'Metro could not finish the Microsoft sign-in.');
+      });
+    }, delayMs);
+    this.timer.unref();
+  }
+
+  private fail(message: string): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.events.onFailed(message);
+  }
+
+  private async tick(): Promise<void> {
+    const code = this.code;
+    if (code === null || this.stopped) return;
+    if (this.now() >= code.expiresAt) {
+      this.fail('The sign-in code expired before it was used. Start again.');
+      return;
+    }
+    await this.settle(code, await pollDeviceCode(code, this.fetchImpl, this.now()));
+  }
+
+  private async settle(code: DeviceCode, poll: Poll): Promise<void> {
+    if (poll.kind === 'pending') {
+      this.schedule(code.intervalMs);
+      return;
+    }
+    if (poll.kind === 'slow_down') {
+      code.intervalMs += SLOW_DOWN_MS;
+      this.schedule(code.intervalMs);
+      return;
+    }
+    if (poll.kind === 'failed') {
+      this.fail(poll.message);
+      return;
+    }
+    const mailbox = await verifyMailbox(poll.tokens.accessToken, this.fetchImpl, this.mailbox);
+    if (this.stopped) return;
+    this.stopped = true;
+    this.events.onDone(resultOf(poll.tokens, poll.tenantId, mailbox, this.now()));
+  }
+}

package/runtime/node_modules/@metro-labs/outlook/src/me.ts

@@ -0,0 +1,41 @@
+import { OutlookAuthError, type FetchLike } from './auth.js';
+import { graphBase } from './config.js';
+
+export interface Mailbox {
+  email: string;
+  name: string;
+}
+
+const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+const MAILBOX_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function parseMailbox(value: unknown): string | null {
+  const mailbox = text(value).toLowerCase();
+  if (mailbox === '') return null;
+  if (!MAILBOX_RE.test(mailbox))
+    throw new OutlookAuthError('Type the whole address of the mailbox, like andy@company.com, or leave it blank.');
+  return mailbox;
+}
+
+const wrongMailbox = (actual: string, wanted: string): string =>
+  `You signed in as ${actual}, not ${wanted}. Nothing was connected. Start again and pick ${wanted} on Microsoft's page, or use "Use another account".`;
+
+export async function verifyMailbox(accessToken: string, fetchImpl: FetchLike, wanted: string | null = null): Promise<Mailbox> {
+  let res: Response;
+  try {
+    res = await fetchImpl(`${graphBase()}/me?$select=mail,userPrincipalName,displayName`, {
+      headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+    });
+  } catch (err) {
+    throw new OutlookAuthError(`Metro could not reach Microsoft Graph: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!res.ok) throw new OutlookAuthError(`Microsoft Graph refused the new sign-in (${String(res.status)}), so nothing was connected.`);
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const mail = text(body.mail).toLowerCase();
+  const principal = text(body.userPrincipalName).toLowerCase();
+  const email = mail || principal;
+  if (email === '') throw new OutlookAuthError('Microsoft Graph did not say which mailbox this is, so nothing was connected.');
+  if (wanted !== null && wanted !== mail && wanted !== principal) throw new OutlookAuthError(wrongMailbox(email, wanted));
+  return { email, name: text(body.displayName) };
+}

package/runtime/node_modules/@metro-labs/outlook/src/outbound.ts

@@ -0,0 +1,116 @@
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountOf, type Account } from './accounts.js';
+import { assertSendable, attachFile, filesOf, type OutgoingFile } from './attachments.js';
+import { conversationOfLine, lineOf } from './format.js';
+import { graph, graphJson, jsonInit, messagePath, odataQuote, queryOf } from './graph.js';
+import { escapeHtml } from './html.js';
+
+type Args = Record<string, unknown>;
+
+export const EPOCH = '1900-01-01T00:00:00Z';
+
+const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+export async function latestInConversation(acct: Account, conversationId: string): Promise<string> {
+  const filter = `receivedDateTime ge ${EPOCH} and conversationId eq ${odataQuote(conversationId)}`;
+  const params = queryOf({ $filter: filter, $orderby: 'receivedDateTime desc', $top: '1', $select: 'id' });
+  const body = await graphJson<{ value?: { id: string }[] }>(acct, `/me/messages?${params}`);
+  const id = body.value?.[0]?.id;
+  if (id === undefined)
+    throw new TrainError('outlook_empty_conversation', 'Outlook has no message in this conversation to answer', { retryable: false });
+  return id;
+}
+
+async function discard(acct: Account, draftId: string): Promise<void> {
+  await graph(acct, messagePath(draftId), { method: 'DELETE' }).catch((err: unknown) => {
+    process.stderr.write(`outlook[${acct.id}] could not remove an unsent draft: ${err instanceof Error ? err.message : String(err)}\n`);
+  });
+}
+
+async function withFiles(acct: Account, target: string, verb: 'reply' | 'replyAll', comment: string, files: OutgoingFile[]): Promise<string[]> {
+  const draft = await graphJson<{ id?: string }>(acct, `${messagePath(target)}/${verb === 'reply' ? 'createReply' : 'createReplyAll'}`, jsonInit('POST', { comment }));
+  const draftId = draft.id;
+  if (draftId === undefined) throw new TrainError('outlook_graph_error', 'Outlook did not open a reply draft', { retryable: true });
+  const labels: string[] = [];
+  try {
+    for (const file of files) labels.push(await attachFile(acct, draftId, file));
+    await graph(acct, `${messagePath(draftId)}/send`, { method: 'POST' });
+  } catch (err) {
+    await discard(acct, draftId);
+    throw err;
+  }
+  return labels;
+}
+
+const ADDRESS_RE = /^[^@\s/]+@[^@\s/]+\.[^@\s/]+$/;
+const SUBJECT_MAX = 255;
+
+export const isAddress = (target: string): boolean => target.includes('@');
+
+export function subjectOf(subject: string, text: string): string {
+  const chosen = subject !== '' ? subject : (text.split('\n').find((l) => l.trim() !== '') ?? '').trim();
+  if (chosen === '') throw new TrainError('outlook_subject_required', 'a new email needs a subject or some text', { retryable: false });
+  return chosen.length > SUBJECT_MAX ? `${chosen.slice(0, SUBJECT_MAX - 3)}...` : chosen;
+}
+
+async function compose(id: string, acct: Account, to: string, args: Args, text: string, files: OutgoingFile[]): Promise<void> {
+  if (!ADDRESS_RE.test(to)) throw new TrainError('outlook_bad_address', `not an email address: ${to}`, { retryable: false });
+  const draft = await graphJson<{ id?: string; conversationId?: string }>(acct, '/me/messages', jsonInit('POST', {
+    subject: subjectOf(str(args.subject), text),
+    body: { contentType: 'Text', content: text },
+    toRecipients: [{ emailAddress: { address: to } }],
+  }));
+  if (draft.id === undefined) throw new TrainError('outlook_graph_error', 'Outlook did not open a draft', { retryable: true });
+  const labels: string[] = [];
+  try {
+    for (const file of files) labels.push(await attachFile(acct, draft.id, file));
+    await graph(acct, `${messagePath(draft.id)}/send`, { method: 'POST' });
+  } catch (err) {
+    await discard(acct, draft.id);
+    throw err;
+  }
+  const line = draft.conversationId === undefined ? undefined : lineOf(acct.id, draft.conversationId);
+  respond(id, { result: { account: acct.id, messageId: draft.id, ...(line === undefined ? {} : { line }), ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+interface Outgoing {
+  target: string;
+  acct: Account;
+  files: OutgoingFile[];
+  text: string;
+  replyTo: string;
+}
+
+async function outgoing(args: Args): Promise<Outgoing> {
+  const line = str(args.line);
+  const parsed = conversationOfLine(line);
+  if (parsed === null) throw new TrainError('outlook_bad_line', `not an outlook line: ${line}`, { retryable: false });
+  const acct = accountOf(args);
+  const files = filesOf(args.attachments);
+  const text = typeof args.text === 'string' ? args.text : '';
+  if (text.trim() === '' && files.length === 0)
+    throw new TrainError('outlook_text_required', 'give some text or a file to send', { retryable: false });
+  await assertSendable(files);
+  return { target: parsed.conversationId, acct, files, text, replyTo: str(args.replyTo) };
+}
+
+async function answer(id: string, args: Args, verb: 'reply' | 'replyAll'): Promise<void> {
+  const { target: conversation, acct, files, text, replyTo } = await outgoing(args);
+  if (isAddress(conversation)) {
+    if (verb === 'reply' || replyTo !== '')
+      throw new TrainError('outlook_reply_needs_thread', 'reply on the thread\'s own line; an address line starts a new email', { retryable: false });
+    await compose(id, acct, conversation.toLowerCase(), args, text, files);
+    return;
+  }
+  const target = replyTo === '' ? await latestInConversation(acct, conversation) : replyTo;
+  const comment = escapeHtml(text);
+  let labels: string[] = [];
+  if (files.length === 0) await graph(acct, `${messagePath(target)}/${verb}`, jsonInit('POST', { comment }));
+  else labels = await withFiles(acct, target, verb, comment, files);
+  respond(id, { result: { account: acct.id, repliedTo: target, ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+export const reply = (id: string, args: Args): Promise<void> => answer(id, args, 'reply');
+
+export const send = (id: string, args: Args): Promise<void> => answer(id, args, str(args.replyTo) === '' ? 'replyAll' : 'reply');

package/runtime/node_modules/@metro-labs/outlook/src/query.ts

@@ -0,0 +1,119 @@
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountOf, type Account } from './accounts.js';
+import { listFiles, saveFile } from './attachments.js';
+import { conversationOfLine, fullOf, LIST_FIELDS, MESSAGE_FIELDS, summaryOf, type GraphMessage } from './format.js';
+import { graph, graphJson, jsonInit, messagePath, odataQuote, queryOf } from './graph.js';
+import { EPOCH } from './outbound.js';
+
+type Args = Record<string, unknown>;
+
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+
+const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+export interface ReadQuery {
+  conversationId: string | null;
+  query: string;
+  from: string;
+  since: string;
+  until: string;
+  before: string;
+  unreadOnly: boolean;
+  limit: number;
+}
+
+function isoOf(raw: string, field: string): string {
+  if (raw === '') return '';
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) throw new TrainError('outlook_bad_date', `${field} must be a date, for example 2026-09-24 or 2026-09-24T10:00:00Z`, { retryable: false });
+  return new Date(at).toISOString();
+}
+
+export function readQueryOf(args: Args): ReadQuery {
+  const line = str(args.line);
+  const conversation = line === '' ? null : conversationOfLine(line);
+  if (line !== '' && conversation === null) throw new TrainError('outlook_bad_line', `not an outlook line: ${line}`, { retryable: false });
+  const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), MAX_LIMIT) : DEFAULT_LIMIT;
+  return {
+    conversationId: conversation?.conversationId ?? null,
+    query: str(args.query).replace(/"/g, ''),
+    from: str(args.from).toLowerCase(),
+    since: isoOf(str(args.since), 'since'),
+    until: isoOf(str(args.until), 'until'),
+    before: str(args.before),
+    unreadOnly: args.unreadOnly === true,
+    limit,
+  };
+}
+
+export function filterOf(q: ReadQuery, beforeAt: string): string {
+  const parts = [`receivedDateTime ge ${q.since === '' ? EPOCH : q.since}`];
+  const until = [q.until, beforeAt].filter((s) => s !== '').sort()[0];
+  if (until !== undefined) parts.push(`receivedDateTime lt ${until}`);
+  if (q.conversationId !== null) parts.push(`conversationId eq ${odataQuote(q.conversationId)}`);
+  if (q.from !== '') parts.push(`from/emailAddress/address eq ${odataQuote(q.from)}`);
+  if (q.unreadOnly) parts.push('isRead eq false');
+  return parts.join(' and ');
+}
+
+function inWindow(at: number, q: ReadQuery, beforeAt: string): boolean {
+  if (q.since !== '' && at < Date.parse(q.since)) return false;
+  if (q.until !== '' && at >= Date.parse(q.until)) return false;
+  return beforeAt === '' || at < Date.parse(beforeAt);
+}
+
+function matches(q: ReadQuery, m: GraphMessage, beforeAt: string): boolean {
+  if (q.conversationId !== null && m.conversationId !== q.conversationId) return false;
+  if (q.unreadOnly && m.isRead === true) return false;
+  return inWindow(Date.parse(m.receivedDateTime ?? ''), q, beforeAt);
+}
+
+async function receivedAt(acct: Account, messageId: string): Promise<string> {
+  if (messageId === '') return '';
+  const m = await graphJson<GraphMessage>(acct, `${messagePath(messageId)}?$select=receivedDateTime`);
+  return m.receivedDateTime ?? '';
+}
+
+export function searchParams(q: ReadQuery, beforeAt: string): string {
+  if (q.query === '')
+    return queryOf({ $filter: filterOf(q, beforeAt), $orderby: 'receivedDateTime desc', $top: String(q.limit), $select: LIST_FIELDS });
+  const terms = q.from === '' ? q.query : `from:${q.from} ${q.query}`;
+  return queryOf({ $search: `"${terms}"`, $top: String(MAX_LIMIT), $select: LIST_FIELDS });
+}
+
+async function list(id: string, acct: Account, q: ReadQuery): Promise<void> {
+  const beforeAt = await receivedAt(acct, q.before);
+  const body = await graphJson<{ value?: GraphMessage[] }>(acct, `/me/messages?${searchParams(q, beforeAt)}`);
+  const found = (body.value ?? []).filter((m) => q.query === '' || matches(q, m, beforeAt)).slice(0, q.limit);
+  respond(id, {
+    result: {
+      account: acct.id,
+      mode: q.query === '' ? 'filter' : 'search',
+      messages: found.map((m) => summaryOf(acct.id, m)),
+    },
+  });
+}
+
+async function one(id: string, acct: Account, messageId: string): Promise<void> {
+  const m = await graphJson<GraphMessage>(acct, `${messagePath(messageId)}?$select=${MESSAGE_FIELDS}`);
+  const files = m.hasAttachments === true ? await listFiles(acct, m.id) : [];
+  const attachments = [];
+  for (const [index, file] of files.entries()) {
+    const saved = await saveFile(acct, m.id, file, index);
+    attachments.push({ name: file.name, mime: file.mime, kind: file.kind, size: saved.bytes, local_path: saved.path });
+  }
+  if (m.isRead !== true) await graph(acct, messagePath(m.id), jsonInit('PATCH', { isRead: true }));
+  respond(id, { result: { account: acct.id, message: { ...fullOf(acct.id, m), is_read: true, attachments } } });
+}
+
+export async function read(id: string, args: Args): Promise<void> {
+  const acct = accountOf(args);
+  const messageId = str(args.messageId);
+  if (messageId !== '') {
+    await one(id, acct, messageId);
+    return;
+  }
+  await list(id, acct, readQueryOf(args));
+}

package/runtime/node_modules/@metro-labs/outlook/src/state.ts

@@ -0,0 +1,43 @@
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+
+export interface AccountState {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  deltaLink: string | null;
+  syncedAt: string | null;
+  seen: string[];
+}
+
+const SEEN_MAX = 500;
+
+export const stateFiles = accountFiles('OUTLOOK_STATE_DIR', 'outlook-state-');
+
+const statePath =(accountId: string): string => stateFiles.path(accountId);
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+const nullable = (v: unknown): string | null => (typeof v === 'string' && v !== '' ? v : null);
+
+export function loadState(accountId: string, seed: Partial<AccountState>): AccountState {
+  const saved = readJson<Record<string, unknown>>(statePath(accountId), {});
+  const refreshToken = text(saved.refreshToken) || text(seed.refreshToken);
+  const fromFile = text(saved.refreshToken) !== '';
+  return {
+    refreshToken,
+    accessToken: fromFile ? text(saved.accessToken) : text(seed.accessToken),
+    expiresAt: fromFile ? Number(saved.expiresAt) || 0 : Number(seed.expiresAt) || 0,
+    deltaLink: nullable(saved.deltaLink) ?? seed.deltaLink ?? null,
+    syncedAt: nullable(saved.syncedAt),
+    seen: Array.isArray(saved.seen) ? saved.seen.filter((s): s is string => typeof s === 'string') : [],
+  };
+}
+
+export function saveState(accountId: string, state: AccountState): void {
+  writeSecure(statePath(accountId), JSON.stringify(state));
+}
+
+export function noteSeen(state: AccountState, messageId: string): void {
+  state.seen.push(messageId);
+  if (state.seen.length > SEEN_MAX) state.seen.splice(0, state.seen.length - SEEN_MAX);
+}

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

@@ -0,0 +1,15 @@
+import type { ReadFilter, Station, Verb } from '@metro-labs/core/stations/types';
+import { stateFiles } from './state.js';
+
+export const outlookStation: Station = {
+  name: 'outlook',
+  hasAccounts: true,
+  hasTrain: true,
+  messageVerbs: new Set<Verb>(['send', 'reply', 'read']),
+  readFilters: new Set<ReadFilter>(['account', 'query', 'from', 'until', 'unread_only', 'message_id']),
+  approvals: false,
+  attachmentMode: 'canonical',
+  forget: stateFiles.forget,
+  forgetExcept: stateFiles.forgetExcept,
+  tools: [],
+};