@stage-labs/metro 0.1.0-beta.27 → 0.1.0-beta.271

package/runtime/marketplace/plugin/STAGE.md

@@ -0,0 +1,95 @@
+---
+name: stage
+description: How to use Stage channels (XMTP groups, https://stage.box) through metro. Create a channel, rename it, add or remove members, set labels and assignees, read its info, and send, reply, react, unreact, delete and read messages, and post frames (interactive ChatKit widget views) and wallet cards (payment and signature requests, receipts). Works only when this agent has an XMTP account in metro.
+---
+
+Stage (https://stage.box) is a messenger built on XMTP. A Stage channel is an XMTP group. You use it with the metro tools below (`mcp__metro__<name>`).
+
+**XMTP only.** All of this needs an XMTP account connected to this agent in metro. Check with `list_accounts`: it must show an account under `xmtp`. Many agents have none. Then none of this works: say so plainly and do not try another channel. The owner can add an XMTP channel on https://metro.box.
+
+**Lines and links.** A channel's line is `metro://xmtp/<account>/<channel id>`. Pass it verbatim as `line`. Its link is `https://stage.box/#/channel/<channel id>`, the last part of the line. Stage shows Markdown, so `[#Launch plan](https://stage.box/#/channel/<channel id>)` is a clickable link. A `message_id` comes from the inbound message or from `read`.
+
+**Channels.**
+- Create: `create_group {"station": "xmtp", "name": "Launch plan", "members": ["0x…"]}`. Members are 0x addresses or XMTP inbox ids. It returns the new `line` and `id`.
+- Rename: `set_channel_metadata {"line": "…", "name": "New title"}`. No tool sets the description or the picture.
+- Add or remove people: `add_members {"line": "…", "members": ["0x…"]}`. `remove_members` takes the same shape.
+- Leave: `close_channel {"line": "…", "removeSelf": true}`.
+- Read: `group_info {"line": "…"}` gives the name, `labels`, `assigned`, `category`, `status`, `priority`, `appData` and the members (`inboxId`, `address`). `list_members {"line": "…"}` gives the members only.
+- Direct chat: `dm {"address": "0x…"}` opens a 1:1 chat and returns its line.
+- With several XMTP accounts, add `"account": "<id>"` to `create_group` and `dm`.
+
+**Labels, assignees, category, status and priority.** They live in the channel's metadata, and Stage shows them on the channel.
+- Labels: `set_channel_metadata {"line": "…", "metadata": {"labels": ["Bug"]}}`. At most 16 labels of 24 characters each.
+- Assignees: `set_channel_metadata {"line": "…", "metadata": {"assigned": ["0x…"]}}`. Only 0x addresses of current members.
+- Category: `set_channel_metadata {"line": "…", "metadata": {"category": "Clients"}}`.
+- Status: `set_channel_metadata {"line": "…", "metadata": {"status": "In review"}}`.
+- Category and status are each one free-form string per channel. Both are trimmed, whitespace is collapsed, and text is truncated to 24 characters. `""` or `null` clears either field. `group_info` returns them as `category` and `status`.
+- Priority: `set_channel_metadata {"line": "…", "metadata": {"priority": "High"}}`. Exactly `Urgent`, `High`, `Medium` or `Low` after trimming surrounding whitespace; empty text or `null` clears it. `group_info` returns it as `priority`.
+- Each key you send replaces that whole value. Keys you leave out stay as they are. To add one label or one assignee, read `group_info` first and send the old list plus the new one. `[]` clears a list. Read `group_info` again to check it saved.
+
+**Task status labels.** Keep the owner's existing workflow. For a label-based task workflow, keep exactly one of these status labels, plus any project labels:
+- `🗒️ Backlog`
+- `🎯 To-do`
+- `🚧 In progress`
+- `🔍 In review`
+- `✅ Done`
+- `🚫 Blocked`
+
+Move it from Backlog or To-do to In progress, then In review, then Done. Use Blocked while you wait on someone. To change it, read `group_info`, swap the old status for the new one in `labels`, keep the other labels, and send the whole list with `set_channel_metadata` `metadata.labels`.
+
+The separate `metadata.status` and `metadata.priority` fields are optional. Status is free-form, not limited to the label names above. Do not migrate or remove existing labels unless asked.
+
+**Messages.**
+- Send: `send {"line": "…", "text": "Hello"}`. Reply with a quote: `reply {"line": "…", "message_id": "…", "text": "…"}`.
+- React: `react {"line": "…", "message_id": "…", "emoji": "👍"}`. `unreact` takes the same shape.
+- Delete one of your own messages: `delete {"line": "…", "message_id": "…"}`. XMTP has no edit and no typing.
+- History: `read {"line": "…", "limit": 20}`.
+- Poll: `ask {"line": "…", "question": "Ship today?", "options": ["Yes", "No"]}`.
+- File: `create_upload {"name": "report.pdf"}`, run the `curl` line it returns in a shell, then `send {"line": "…", "attachments": [{"upload": "<upload_id>"}]}`. Files that are not images are refused over about 190 KiB.
+
+**Frames.** A frame is a small interactive view: a report, a choice, a form. Stage shows the frame itself in the chat (its `start` screen when it has screens), at image size, at most 400 x 400, clipped with a fade when taller. A tap opens it full screen. Its buttons do nothing in the chat: they work in the full view.
+- Send: `send {"line": "…", "frame": {"title": "Deploy", "description": "Version 2.4 is ready", "widget": {…}}}`. A frame goes with `send`, like a file: there is no separate tool. `title` and `description` are optional: they come from the first `Title` and text in the widget when missing. With `text` as well, the text goes first, and the `message_id` you get back is the frame's.
+- `widget` is OpenAI ChatKit widget JSON, with ChatKit's names and props (https://openai.github.io/chatkit-js/): a `Card`, `ListView` or `Basic` root, with `Row`, `Col`, `Box`, `Text`, `Title`, `Caption`, `Markdown`, `Badge`, `Icon`, `Image`, `Button`, `Divider`, `Spacer`, `Form`, `Input`, `Textarea`, `Select`, `DatePicker`, `Checkbox`, `RadioGroup` and `Table`. Images must be `https://`. Number spacing is in steps of 4px. At most 64K characters, 16 levels deep and 500 nodes. Stage shows a small notice for anything it does not know.
+- Example, the arguments of one `send`:
+  ```json
+  {"line": "…", "frame": {"widget": {"type": "Card", "children": [
+    {"type": "Title", "value": "Deploy version 2.4?"},
+    {"type": "Text", "value": "3 fixes, no migration.", "color": "secondary"},
+    {"type": "Input", "name": "note", "placeholder": "Note (optional)"},
+    {"type": "Row", "children": [
+      {"type": "Button", "label": "Deploy", "onClickAction": {"type": "deploy", "payload": {"version": "2.4"}}},
+      {"type": "Button", "label": "Not now", "color": "secondary", "onClickAction": {"type": "deploy.cancel"}}
+    ]}
+  ]}}}
+  ```
+- A tap comes back to you as a reply to the frame: `Frame action: deploy {"version":"2.4","note":"…"} (tapped "Deploy")`. The values of the fields (`Input`, `Select`, `Checkbox`, …) are added to the payload by their `name`. `Button.onClickAction`, `ListViewItem.onClickAction`, a `Card` `confirm`/`cancel` (`{"label", "action"}`) and a `Form` `onSubmitAction` send one. Answer it like any message.
+- Screens: send `screens` instead of `widget` to put several screens in one frame, e.g. a list and a page per item. Each screen is a widget, or `{"title", "widget"}` for its own title in Stage's top bar. `start` names the first screen and is required. The action `{"type": "frame.open", "payload": {"screen": "<id>"}}` opens a screen and `{"type": "frame.back"}` goes back. They stay in Stage: no message comes to you. Stage's back arrow goes to the previous screen, and to the chat from the first one. Every other action comes to you as usual, with `screen` (the screen it was tapped on) in its payload. At most 50 screens and 64K characters for all of them; `start` and every `frame.open` must name a screen. Example:
+  ```json
+  {"line": "…", "frame": {"title": "Open invoices", "start": "home", "screens": {
+    "home": {"type": "ListView", "children": [
+      {"type": "ListViewItem", "onClickAction": {"type": "frame.open", "payload": {"screen": "inv-1"}},
+        "children": [{"type": "Text", "value": "Acme, CHF 420"}]}
+    ]},
+    "inv-1": {"title": "Acme", "widget": {"type": "Card", "children": [
+      {"type": "Title", "value": "Invoice 1040, CHF 420"},
+      {"type": "Row", "children": [
+        {"type": "Button", "label": "Back", "color": "secondary", "onClickAction": {"type": "frame.back"}},
+        {"type": "Button", "label": "Pay", "onClickAction": {"type": "invoice.pay", "payload": {"id": 1040}}}
+      ]}
+    ]}}
+  }}}
+  ```
+
+**Wallet cards.** The payment and signature cards Stage's own Request payment and Request signature send. Sending one moves nothing and signs nothing: the person taps Pay or Sign and confirms in Stage. Send one only when you were asked to.
+- Send: `send {"line": "…", "wallet": {"type": "<type>", "content": {…}}}`. With `text` or a `frame` as well, the card goes last, and the `message_id` you get back is the card's.
+- Payment request, `walletSendCalls`, a card with a Pay button. Stage pays a request with one call; a Stage wallet pays on Base only.
+  ```json
+  {"type": "walletSendCalls", "content": {"version": "1.0", "chainId": "0x2105", "from": "0x<your address>", "calls": [
+    {"to": "0x<who gets paid>", "value": "0x38d7ea4c68000", "metadata": {"description": "Dinner", "transactionType": "transfer",
+      "currency": "ETH", "amount": 0.001, "decimals": 18, "toAddress": "0x<who gets paid>"}}
+  ]}}
+  ```
+  `chainId` is a hex string (`0x2105` is Base) and `value` is in wei, hex. For a token, `to` is the token contract, `data` its `transfer(address,uint256)` call data, `value` is left out, and `metadata` has `currency`, `amount` and `toAddress` (who gets paid).
+- Receipt, `transactionReference`: `{"networkId": 8453, "reference": "0x<tx hash>", "metadata": {"currency": "USDC", "amount": 5}}`. Stage shows "Payment sent · 5 USDC" (or "Transaction sent" without an amount) and a link to the explorer. Only post a real transaction hash.
+- Signature request, `signatureRequest`, a card with a Sign button: `{"id": "<any id>", "kind": "personal", "message": "The text to sign", "description": "Why"}`, or `"kind": "eip712"` with `"eip712": {"domain", "types", "primaryType", "message"}` instead of `message`.
+- Signature, `signatureReference`: `{"requestId": "<message_id of the request>", "signature": "0x…", "signer": "0x…"}`. Stage shows it as Signed.

package/runtime/marketplace/plugin/bin/guard.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { policyVerdict } from './policy.mjs';
+
+const BLOCKING = new Set(['AskUserQuestion', 'ExitPlanMode', 'EnterPlanMode']);
+const ORCHESTRATION = new Set([
+  'Agent',
+  'Workflow',
+  'ToolSearch',
+  'Skill',
+  'ScheduleWakeup',
+  'Monitor',
+  'CronCreate',
+  'CronList',
+  'CronDelete',
+  'TaskCreate',
+  'TaskGet',
+  'TaskList',
+  'TaskOutput',
+  'TaskStop',
+  'TaskUpdate',
+]);
+const IMAGE = /\.(png|jpe?g|gif|webp|bmp)$/i;
+const MCP = /^mcp__/;
+const METRO_MCP = /^mcp__metro__/;
+const VOICE = process.env.METRO_SESSION === 'voice';
+
+function answer(decision, reason) {
+  process.stdout.write(
+    `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: reason } })}\n`,
+  );
+}
+
+function ownerPolicy(tool, input, subagent) {
+  const verdict = policyVerdict(tool, input);
+  if (verdict === null) return null;
+  const { where } = verdict;
+  if (verdict.access === 'deny') return { decision: 'deny', reason: `Blocked by the owner's policy for ${verdict.owner} (${verdict.tool}).` };
+  if (subagent) return { decision: 'ask', reason: `The owner asked to approve ${where}.` };
+  return {
+    decision: 'deny',
+    reason: `${where} needs the owner's approval, and waiting for it here would stop the whole session. Run this exact call from a background worker (Agent, run_in_background: true): the worker waits for the owner's answer while you keep answering.`,
+  };
+}
+
+function verdict(payload, input) {
+  const tool = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+  if (BLOCKING.has(tool))
+    return `${tool} blocks the session waiting on the terminal, and nobody is watching it. Decide with your best judgement and state the assumption, or ask over chat with the metro tools and keep working in the meantime.`;
+  if (typeof payload.agent_id === 'string' && payload.agent_id !== '') return null;
+  if (tool === 'Agent' && input.run_in_background === false)
+    return VOICE
+      ? 'On a voice call a foreground subagent leaves the caller in silence until it finishes. Re-issue the identical Agent call with run_in_background: true, tell the caller you will come back to it, and keep talking.'
+      : 'A foreground subagent blinds the main thread: it cannot see or acknowledge inbound metro messages until the agent finishes. Re-issue the identical Agent call with run_in_background: true, then wait for the task notification.';
+  if (VOICE) return null;
+  if (ORCHESTRATION.has(tool)) return null;
+  if (METRO_MCP.test(tool)) return null;
+  if (MCP.test(tool))
+    return `A connector call is work, not orchestration: ${tool} reads somebody's files, mail or records, and its answer can be long enough to crowd out the chat you are here to follow. Only metro's own tools run on this thread. Delegate it to a subagent with the Agent tool (run_in_background: true; the worker reaches every connector) and relay what it finds.`;
+  if (tool === 'Read' && typeof input.file_path === 'string' && IMAGE.test(input.file_path)) return null;
+  return `The main thread is orchestrator-only, so ${tool === '' ? 'this tool' : tool} is not available here. Delegate the work to a subagent with the Agent tool (run_in_background: true; the worker agent has full tool access) or to a Workflow, and report the result over metro.`;
+}
+
+let payload = {};
+try {
+  payload = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  payload = {};
+}
+const shaped = payload !== null && typeof payload === 'object' ? payload : {};
+const input = shaped.tool_input !== null && typeof shaped.tool_input === 'object' ? shaped.tool_input : {};
+const reason = verdict(shaped, input);
+const policy = reason === null && typeof shaped.tool_name === 'string' ? ownerPolicy(shaped.tool_name, input, typeof shaped.agent_id === 'string' && shaped.agent_id !== '') : null;
+if (reason !== null) answer('deny', reason);
+else if (policy !== null) answer(policy.decision, policy.reason);

package/runtime/marketplace/plugin/bin/metro-plugin.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const agentsDir = () => process.env.METRO_AGENTS_DIR || join(homedir(), '.metro', 'agents');
+
+function readAgent() {
+  const path = join(agentsDir(), 'agent.json');
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error(`no agent on this machine yet (${path})`);
+  }
+  if (typeof parsed?.key !== 'string') throw new Error(`no agent key in ${path}`);
+  return parsed;
+}
+
+if (process.argv[2] !== 'headers') {
+  process.stderr.write('usage: metro-plugin.mjs headers\n');
+  process.exit(1);
+}
+
+try {
+  process.stdout.write(`${JSON.stringify({ Authorization: `Bearer ${readAgent().key}` })}\n`);
+} catch (err) {
+  process.stderr.write(`metro: ${err.message}\n`);
+  process.stdout.write('{}\n');
+}

package/runtime/marketplace/plugin/bin/policy.mjs

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const METRO_TOOL = /^mcp__metro__(.+)$/;
+const RANK = { allow: 0, ask: 1, deny: 2 };
+const LINE_FIELD = { get_profile: 'from' };
+const STATION_ARG = new Set(['create_group', 'set_profile']);
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => (typeof v === 'string' ? v : '');
+const agentsDir = () => process.env.METRO_AGENTS_DIR?.trim() || join(homedir(), '.metro', 'agents');
+
+function readSnapshot() {
+  try {
+    const parsed = JSON.parse(readFileSync(join(agentsDir(), 'policy.json'), 'utf8'));
+    return isRecord(parsed) && parsed.version === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+const fromLine = (line, override) => {
+  const parts = line.split('/');
+  return line.startsWith('metro://') && parts[2] && parts[3] ? [{ station: parts[2], account: override || parts[3] }] : [];
+};
+
+function stationOfAccount(snap, account) {
+  const hits = Object.entries(isRecord(snap.stations) ? snap.stations : {}).filter(
+    ([, ids]) => Array.isArray(ids) && ids.includes(account),
+  );
+  return hits.length === 1 ? hits[0][0] : undefined;
+}
+
+function targets(snap, name, input) {
+  if (Array.isArray(snap.ungated) && snap.ungated.includes(name)) return [];
+  const account = text(input.account);
+  const line = text(input[LINE_FIELD[name] ?? 'line']);
+  if (line) return fromLine(line, name in LINE_FIELD || name === 'list_members' ? '' : account);
+  const owners = isRecord(snap.owners) ? snap.owners : {};
+  const station = (STATION_ARG.has(name) ? text(input.station) : text(owners[name])) || (account ? stationOfAccount(snap, account) : undefined);
+  if (!station) return [];
+  if (account) return [{ station, account }];
+  const ids = isRecord(snap.stations) && Array.isArray(snap.stations[station]) ? snap.stations[station] : [];
+  return ids.map((id) => ({ station, account: id }));
+}
+
+function decide(policy, name, group) {
+  if (!isRecord(policy)) return 'allow';
+  const byTool = isRecord(policy.tools) ? policy.tools[name] : undefined;
+  const access = byTool ?? policy[group] ?? 'allow';
+  return access in RANK ? access : 'allow';
+}
+
+const normalized = (name) => name.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+function connectorCall(snap, toolName) {
+  for (const [server, entry] of Object.entries(isRecord(snap.connectors) ? snap.connectors : {})) {
+    if (!isRecord(entry)) continue;
+    const name = text(entry.name);
+    const prefixes = [`mcp__plugin_metro_${server}__`, `mcp__${server}__`, `mcp__${normalized(`metro.box ${name}`)}__`];
+    const prefix = prefixes.find((p) => toolName.startsWith(p) && toolName.length > p.length);
+    if (prefix === undefined) continue;
+    const called = toolName.slice(prefix.length);
+    const tools = isRecord(entry.tools) ? entry.tools : {};
+    const policy = isRecord(entry.policy) ? entry.policy : {};
+    const known = [...Object.keys(tools), ...Object.keys(isRecord(policy.tools) ? policy.tools : {})];
+    const tool = known.find((k) => k === called) ?? known.find((k) => normalized(k) === called) ?? called;
+    return { name: name || server, tool, group: tools[tool] === 'read' ? 'read' : 'write', policy };
+  }
+  return null;
+}
+
+function connectorVerdict(snap, toolName) {
+  const call = connectorCall(snap, toolName);
+  if (call === null) return null;
+  const access = decide(call.policy, call.tool, call.group);
+  return access === 'allow' ? null : { access, tool: call.tool, owner: call.name, where: `${call.tool} on ${call.name}` };
+}
+
+export function policyVerdict(toolName, input) {
+  const name = METRO_TOOL.exec(toolName)?.[1];
+  if (name === undefined && !toolName.startsWith('mcp__')) return null;
+  const snap = readSnapshot();
+  if (snap === null) return null;
+  if (name === undefined) return connectorVerdict(snap, toolName);
+  const tools = isRecord(snap.tools) ? snap.tools : {};
+  const group = tools[name] === 'read' ? 'read' : 'write';
+  const accounts = isRecord(snap.accounts) ? snap.accounts : {};
+  let verdict = null;
+  for (const target of targets(snap, name, input)) {
+    const access = decide(accounts[`${target.station}/${target.account}`], name, group);
+    if (access !== 'allow' && (verdict === null || RANK[access] > RANK[verdict.access]))
+      verdict = { access, tool: name, owner: target.station, where: `${name} on ${target.station} (${target.account})` };
+  }
+  return verdict;
+}

package/runtime/marketplace/plugin/bin/session-start.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const given = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
+const claudeDir = given(process.env.CLAUDE_CONFIG_DIR) ?? join(given(process.env.HOME) ?? homedir(), '.claude');
+const SKILL = join(claudeDir, 'skills', 'metro', 'SKILL.md');
+const FALLBACK = join(dirname(dirname(fileURLToPath(import.meta.url))), 'METRO.md');
+
+const body = (text) => text.replace(/^---[\s\S]*?\n---\n/, '').trim();
+
+function guidance() {
+  for (const path of [SKILL, FALLBACK]) {
+    if (!existsSync(path)) continue;
+    try {
+      const text = body(readFileSync(path, 'utf8'));
+      if (text !== '') return text;
+    } catch {
+      continue;
+    }
+  }
+  return '';
+}
+
+const text = process.env.METRO_SESSION === 'voice' ? '' : guidance();
+if (text !== '')
+  process.stdout.write(
+    `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `This machine runs as a metro agent. Standing rules, kept in the metro skill:\n\n${text}` } })}\n`,
+  );

package/runtime/marketplace/plugin/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/guard.mjs\"",
+            "statusMessage": "Checking the orchestrator boundary"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/session-start.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,53 @@
+{
+  "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",
+    "./call": "./src/call.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/node_modules/@metro-labs/core/src/call.ts

@@ -0,0 +1,81 @@
+import { isRecord } from './is-record.js';
+
+export const CALL_NOTICE = 'notifications/metro/call';
+export const CALL_STATE = 'notifications/metro/call_state';
+
+export interface CallState {
+  route: CallRoute | null;
+}
+
+export interface CallRoute {
+  agentId: string;
+  line: string;
+  from: string;
+  callId: string;
+  generation: string;
+}
+
+export interface SpeechTarget {
+  callId: string;
+  generation: string;
+  sourceId: string;
+}
+
+export interface CallSource {
+  route: CallRoute;
+  sourceId: string;
+}
+
+export type SpeechStatus = 'accepted' | 'queued' | 'started' | 'completed' | 'interrupted' | 'failed';
+
+export type CallNotice =
+  | { type: 'started'; route: CallRoute; sourceId: string }
+  | { type: 'heard'; route: CallRoute; sourceId: string; text: string }
+  | { type: 'ended'; route: CallRoute }
+  | { type: 'speech'; route: CallRoute; sourceId: string; actionId: string; status: SpeechStatus };
+
+const filled = (value: unknown): value is string => typeof value === 'string' && value.length > 0 && value.length <= 2048;
+
+export function callRoute(value: unknown): CallRoute | null {
+  if (!isRecord(value)) return null;
+  const { agentId, line, from, callId, generation } = value;
+  return filled(agentId) && filled(line) && filled(from) && filled(callId) && filled(generation)
+    ? { agentId, line, from, callId, generation }
+    : null;
+}
+
+export function callState(value: unknown): CallState | null {
+  if (!isRecord(value)) return null;
+  if (value.route === null) return { route: null };
+  const route = callRoute(value.route);
+  return route === null ? null : { route };
+}
+
+export function speechTarget(value: unknown): SpeechTarget | null {
+  if (!isRecord(value)) return null;
+  const { callId, generation, sourceId } = value;
+  return filled(callId) && filled(generation) && filled(sourceId) ? { callId, generation, sourceId } : null;
+}
+
+const STATUSES: readonly SpeechStatus[] = ['accepted', 'queued', 'started', 'completed', 'interrupted', 'failed'];
+
+const speechStatus = (value: unknown): SpeechStatus | null => STATUSES.find((status) => status === value) ?? null;
+
+function sourcedNotice(value: Record<string, unknown>, route: CallRoute, sourceId: string): CallNotice | null {
+  if (value.type === 'started') return { type: 'started', route, sourceId };
+  if (value.type === 'heard') return typeof value.text === 'string' && value.text.length <= 32_000 ? { type: 'heard', route, sourceId, text: value.text } : null;
+  if (value.type !== 'speech' || !filled(value.actionId)) return null;
+  const status = speechStatus(value.status);
+  return status === null ? null : { type: 'speech', route, sourceId, actionId: value.actionId, status };
+}
+
+export function callNotice(value: unknown): CallNotice | null {
+  if (!isRecord(value)) return null;
+  const route = callRoute(value.route);
+  if (route === null) return null;
+  if (value.type === 'ended') return { type: 'ended', route };
+  return filled(value.sourceId) ? sourcedNotice(value, route, value.sourceId) : null;
+}
+
+export const sameCall = (a: CallRoute, b: CallRoute): boolean =>
+  a.agentId === b.agentId && a.line === b.line && a.from === b.from && a.callId === b.callId && a.generation === b.generation;

package/runtime/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/node_modules/@metro-labs/{mcp/src/daemon → core/src}/events.ts

@@ -1,7 +1,8 @@
-import { randomBytes } from 'node:crypto';
-import { Line } from '../stations/lines.js';
+import { Line } from './lines.js';
+import { errMsg, log } from './log.js';
 
-export { userSelf, daemonSelf, selfLine } from './identity.js';
+export const userSelf = (): Line =>
+  (process.env.METRO_FROM ?? 'metro://user') as Line;
 
 export type StructuredEvent =
   | { type: 'msg' }
@@ -24,6 +25,10 @@ export interface MetroEvent {
   text?: string;
   messageId?: string;
   replyTo?: string;
+  isPrivate?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  senderVerified?: boolean;
   payload?: unknown;
   display?: string;
   event?: StructuredEvent;
@@ -71,8 +76,7 @@ export function formatDisplay(e: MetroEvent): string {
   return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
 }
 
-export const mintId = (): string =>
-  `msg_${randomBytes(6).toString('base64url')}`;
+export { mintId } from './ids.js';
 
 export type BusListener = (event: MetroEvent, busSeq: number) => void;
 
@@ -83,6 +87,50 @@ export interface BufferedEvent {
 
 export const BUS_BUFFER_MAX = 500;
 
+export interface RunEventMetadata {
+  isPrivate?: boolean;
+  senderVerified?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  emoji?: string;
+  removed?: boolean;
+  targetId?: string;
+  attachmentCount?: number;
+  attachmentTypes?: ('image' | 'video' | 'audio' | 'file')[];
+  attachmentStatus?: 'saved' | 'failed';
+  attachmentFor?: string;
+}
+
+export interface RunEvent {
+  id: string;
+  seq: number;
+  ts: string;
+  kind: StructuredEvent['type'];
+  direction: 'inbound' | 'outbound' | 'system';
+  agentId: string;
+  station: string;
+  accountId: string | null;
+  line: string;
+  lineName?: string;
+  from?: string;
+  fromName?: string;
+  fromDisplayName?: string;
+  to?: string;
+  text?: string;
+  truncated: boolean;
+  messageId?: string;
+  replyTo?: string;
+  metadata: RunEventMetadata;
+}
+
+export interface RunEventsPage {
+  events: RunEvent[];
+  cursor: string;
+  hasMore: boolean;
+  reset: boolean;
+  retention: { capacity: number; oldestAt: string | null; oldestSeq: number | null };
+}
+
 const listeners = new Set<BusListener>();
 const buffer: BufferedEvent[] = [];
 let busSeq = 0;
@@ -96,7 +144,7 @@ export function publishEvent(event: MetroEvent): void {
     try {
       fn(event, seq);
     } catch (err) {
-      console.error('[metro-bus] listener threw for busSeq', seq, err);
+      log.error({ busSeq: seq, err: errMsg(err) }, 'bus: a listener threw');
     }
   }
 }

package/runtime/node_modules/@metro-labs/{mcp/src/db → core/src}/ids.ts

@@ -1,10 +1,17 @@
-import { randomBytes } from 'node:crypto';
+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');
@@ -17,3 +24,5 @@ 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/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);