@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.70

package/runtime/node_modules/@metro-labs/mcp/src/db/vault.ts

@@ -0,0 +1,109 @@
+import { and, asc, eq } from 'drizzle-orm';
+import { ApiError } from '../daemon/api-error.js';
+import { isRecord } from '../daemon/is-record.js';
+import { getDb } from './client.js';
+import { AGENT_NAME_RE, parseId } from './ids.js';
+import { vaults } from './schema.js';
+import { STATIONS } from './stations.js';
+import { normalizeAddress } from './address.js';
+
+export class VaultError extends ApiError {}
+
+import { ENVELOPE_MAX, type VaultBundle, type VaultEntry } from '../daemon/vault-types.js';
+
+export interface VaultInput {
+  name: string;
+  stations: string[];
+  envelope: Record<string, unknown>;
+}
+const STATION_NAMES = new Set<string>(STATIONS);
+
+const missing = (): VaultError => new VaultError('no such bundle', 404);
+
+function ownerOf(subject: string): string {
+  const address = normalizeAddress(subject);
+  if (address === null) throw new VaultError('the vault needs a vault identity', 403);
+  return address;
+}
+
+function stationsOf(raw: unknown): string[] {
+  if (!Array.isArray(raw)) throw new VaultError('stations must be a list of station names', 400);
+  const list = raw.map((s: unknown) => (typeof s === 'string' ? s : ''));
+  const bad = list.find((s) => !STATION_NAMES.has(s));
+  if (bad !== undefined) throw new VaultError(`'${bad}' is not a station`, 400);
+  return [...new Set(list)];
+}
+
+function envelopeOf(raw: unknown, id: string): Record<string, unknown> {
+  if (!isRecord(raw) || raw.v !== 1 || raw.agentId !== id)
+    throw new VaultError('envelope must be a v1 envelope for this agent', 400);
+  const key = raw.key;
+  if (!isRecord(key) || normalizeAddress(typeof key.recipient === 'string' ? key.recipient : '') === null)
+    throw new VaultError('envelope must name the wallet it was sealed to', 400);
+  if (typeof raw.ciphertext !== 'string' || typeof raw.nonce !== 'string')
+    throw new VaultError('envelope carries no ciphertext', 400);
+  if (JSON.stringify(raw).length > ENVELOPE_MAX)
+    throw new VaultError(`envelope is over ${String(ENVELOPE_MAX)} bytes`, 413);
+  return raw;
+}
+
+export function parseVaultInput(subject: string, id: string, body: unknown): VaultInput & { owner: string } {
+  const owner = ownerOf(subject);
+  if (parseId(id) === null) throw missing();
+  if (!isRecord(body)) throw new VaultError('body must be an object', 400);
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  if (!AGENT_NAME_RE.test(name)) throw new VaultError('name is not an agent name', 400);
+  return { owner, name, stations: stationsOf(body.stations), envelope: envelopeOf(body.envelope, id) };
+}
+
+const entryOf = (row: { id: string; name: string; stations: unknown; syncedAt: string }): VaultEntry => ({
+  id: row.id,
+  name: row.name,
+  stations: Array.isArray(row.stations) ? row.stations.filter((s): s is string => typeof s === 'string') : [],
+  syncedAt: row.syncedAt,
+});
+
+export async function listVaultForOwner(subject: string): Promise<VaultEntry[]> {
+  const owner = ownerOf(subject);
+  const rows = await getDb()
+    .select({ id: vaults.id, name: vaults.name, stations: vaults.stations, syncedAt: vaults.syncedAt })
+    .from(vaults)
+    .where(eq(vaults.owner, owner))
+    .orderBy(asc(vaults.name));
+  return rows.map(entryOf);
+}
+
+export async function putVaultForOwner(subject: string, id: string, body: unknown): Promise<VaultEntry> {
+  const input = parseVaultInput(subject, id, body);
+  const syncedAt = new Date().toISOString();
+  const values = { id, owner: input.owner, name: input.name, stations: input.stations, envelope: input.envelope, syncedAt };
+  const db = getDb();
+  const held = await db.select({ owner: vaults.owner }).from(vaults).where(eq(vaults.id, id));
+  if (held[0] !== undefined && held[0].owner !== input.owner) throw missing();
+  await db
+    .insert(vaults)
+    .values(values)
+    .onConflictDoUpdate({ target: vaults.id, set: { name: input.name, stations: input.stations, envelope: input.envelope, syncedAt } });
+  return entryOf(values);
+}
+
+export async function getVaultForOwner(subject: string, id: string): Promise<VaultBundle> {
+  const owner = ownerOf(subject);
+  if (parseId(id) === null) throw missing();
+  const rows = await getDb().select().from(vaults).where(and(eq(vaults.id, id), eq(vaults.owner, owner)));
+  const row = rows[0];
+  if (row === undefined) throw missing();
+  return { ...entryOf(row), envelope: isRecord(row.envelope) ? row.envelope : {} };
+}
+
+export async function deleteVaultForOwner(subject: string, id: string): Promise<{ id: string; name: string }> {
+  const owner = ownerOf(subject);
+  if (parseId(id) === null) throw missing();
+  const gone = await getDb()
+    .delete(vaults)
+    .where(and(eq(vaults.id, id), eq(vaults.owner, owner)))
+    .returning({ id: vaults.id, name: vaults.name });
+  const row = gone[0];
+  if (row === undefined) throw missing();
+  return row;
+}

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

@@ -0,0 +1,141 @@
+import { forwardTrainCall } from '../daemon/train-call.js';
+import {
+  accountStationNames,
+  stationByName,
+} from '../stations/registry.js';
+import { listEndpoints } from '../daemon/tunnel.js';
+import { hookUrl } from '../stations/attach.js';
+import { agentIdForAccount, knownAccounts, type KnownAccount } from '../db/agent-map.js';
+import { stationRunsHere } from '../db/materialize.js';
+import { type StationName } from '../db/stations.js';
+
+const accountId = (acc: unknown): string | undefined => {
+  const id = (acc as { id?: unknown }).id;
+  return typeof id === 'string' ? id : undefined;
+};
+
+const asRecord = (acc: unknown): Record<string, unknown> | undefined =>
+  typeof acc === 'object' && acc !== null && !Array.isArray(acc)
+    ? (acc as Record<string, unknown>)
+    : undefined;
+
+function withAgentId(station: string, acc: unknown): unknown {
+  const rec = asRecord(acc);
+  if (rec === undefined) return acc;
+  const id = typeof rec.id === 'string' ? rec.id : undefined;
+  if (id === undefined) return acc;
+  const agentId = agentIdForAccount(station, id);
+  return agentId === undefined ? acc : { ...rec, agentId };
+}
+
+export function attachAgentIds(
+  byStation: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [station, list] of Object.entries(byStation))
+    out[station] = list.map((acc) => withAgentId(station, acc));
+  return out;
+}
+
+export function scopeAccountsByAgent(
+  byStation: Record<string, unknown[]>,
+  allowed: Set<string>,
+): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = {};
+  for (const [station, list] of Object.entries(byStation)) {
+    out[station] = list.filter((acc) => {
+      const id = accountId(acc);
+      if (id === undefined) return false;
+      const agentId = agentIdForAccount(station, id);
+      return agentId !== undefined && allowed.has(agentId);
+    });
+  }
+  return out;
+}
+
+const hasTrain = (station: string): boolean =>
+  stationByName(station)?.hasTrain !== false;
+
+function inCoreAccounts(station: string): unknown[] {
+  if (station !== 'webhook') return [];
+  return listEndpoints().flatMap((e) =>
+    e.secret === undefined || e.webhookId === undefined
+      ? []
+      : [
+          {
+            id: e.id,
+            handle: `/api/webhooks/${e.webhookId}`,
+            endpoint: hookUrl(e.webhookId, e.secret),
+          },
+        ],
+  );
+}
+
+export interface ScopedAccounts {
+  accounts: Record<string, unknown[]>;
+  unavailable: string[];
+}
+
+async function liveAccounts(
+  station: string,
+): Promise<{ rows: unknown[]; reachable: boolean }> {
+  if (!hasTrain(station))
+    return { rows: inCoreAccounts(station), reachable: true };
+  if (!stationRunsHere(station as StationName))
+    return { rows: [], reachable: true };
+  try {
+    const resp = await forwardTrainCall(station, 'accounts', {});
+    const list = (resp.result as { accounts?: unknown[] } | undefined)?.accounts;
+    return { rows: Array.isArray(list) ? list : [], reachable: true };
+  } catch {
+    return { rows: [], reachable: false };
+  }
+}
+
+function mergeKnown(
+  station: string,
+  live: unknown[],
+  known: KnownAccount[],
+): unknown[] {
+  const seen = new Set(
+    live.flatMap((row) => {
+      const id = accountId(row);
+      return id === undefined ? [] : [id];
+    }),
+  );
+  const missing = known
+    .filter((r) => r.station === station && !seen.has(r.id))
+    .map((r) => ({ id: r.id }));
+  return [...live, ...missing];
+}
+
+async function loadStations(): Promise<ScopedAccounts> {
+  const unavailable: string[] = [];
+  const accounts: Record<string, unknown[]> = {};
+  const known = knownAccounts();
+  await Promise.all(
+    accountStationNames().map(async (station) => {
+      const { rows, reachable } = await liveAccounts(station);
+      if (!reachable) unavailable.push(station);
+      accounts[station] = hasTrain(station) ? mergeKnown(station, rows, known) : rows;
+    }),
+  );
+  return { accounts, unavailable };
+}
+
+export async function gatherAccounts(
+  allowedAgents?: Set<string>,
+): Promise<Record<string, unknown[]>> {
+  const { accounts } = await loadStations();
+  return allowedAgents ? scopeAccountsByAgent(accounts, allowedAgents) : accounts;
+}
+
+export async function gatherAccountsForAgents(
+  allowed: Set<string>,
+): Promise<ScopedAccounts> {
+  const { accounts, unavailable } = await loadStations();
+  return {
+    accounts: attachAgentIds(scopeAccountsByAgent(accounts, allowed)),
+    unavailable,
+  };
+}

package/runtime/node_modules/@metro-labs/mcp/src/mcp/call-tools.ts

@@ -0,0 +1,216 @@
+import { stationForLine } from '../stations/registry.js';
+import { kindOf, toCanonical } from '../stations/attachments.js';
+import {
+  cleanupAttachments,
+  resolveAttachments,
+  type ResolvedAttachment,
+} from '../stations/attach-resolve.js';
+import type { CanonicalAttachment, ToolResult } from '../stations/types.js';
+import { errResult, makeCtx, ok, okJson, toErr } from './ctx.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+import { str } from './str.js';
+
+type Station = NonNullable<ReturnType<typeof stationForLine>>;
+
+interface MessageArgs {
+  line: string;
+  a: Record<string, unknown>;
+  ctx: ReturnType<typeof makeCtx>;
+  onSent?: (messageId: string) => void;
+  station: Station;
+}
+
+const messageIdOf = (response: { result: unknown }): string | undefined => {
+  const id = (response.result as { messageId?: unknown } | null)?.messageId;
+  return typeof id === 'string' && id !== '' ? id : undefined;
+};
+
+const withId = (text: string, messageId: string | undefined): string =>
+  messageId === undefined ? text : `${text} — message_id: ${messageId}`;
+
+interface Sent {
+  labels: string[];
+  messageId?: string;
+}
+
+const deliveredLabels = (response: { result: unknown }): string[] => {
+  const list = (response.result as { attachments?: unknown } | null)
+    ?.attachments;
+  return Array.isArray(list)
+    ? list.filter((x): x is string => typeof x === 'string')
+    : [];
+};
+
+function assertDelivered(
+  station: Station,
+  delivered: string[],
+  atts: ResolvedAttachment[],
+): void {
+  if (delivered.length < atts.length)
+    throw new Error(
+      `${station.name} delivered ${delivered.length} of ${atts.length} attachment(s); ` +
+        'the message text may still have been sent',
+    );
+}
+
+async function sendNative(
+  m: MessageArgs,
+  text: string | undefined,
+  replyTo: string | undefined,
+  atts: ResolvedAttachment[],
+): Promise<Sent> {
+  const { line, ctx, station } = m;
+  const labels: string[] = [];
+  let messageId: string | undefined;
+  if (text) {
+    const response = await ctx.call(
+      'send',
+      replyTo ? { line, text, replyTo } : { line, text },
+    );
+    messageId = messageIdOf(response);
+    labels.push('text');
+  }
+  if (!atts.length) return { labels, messageId };
+  const delivered = station.sendAttachments
+    ? await station.sendAttachments(line, atts, ctx)
+    : [];
+  assertDelivered(station, delivered, atts);
+  labels.push(...delivered);
+  return { labels, messageId };
+}
+
+async function sendForwarded(
+  m: MessageArgs,
+  text: string | undefined,
+  replyTo: string | undefined,
+  atts: ResolvedAttachment[],
+): Promise<Sent> {
+  const { line, ctx, station } = m;
+  const args: Record<string, unknown> = { line };
+  if (text) args.text = text;
+  if (replyTo) args.replyTo = replyTo;
+  if (atts.length) args.attachments = atts.map(toCanonical);
+  const response = await ctx.call('send', args);
+  const messageId = messageIdOf(response);
+  const labels: string[] = [];
+  if (text) labels.push('text');
+  if (!atts.length) return { labels, messageId };
+  const delivered = deliveredLabels(response);
+  assertDelivered(station, delivered, atts);
+  labels.push(...delivered);
+  return { labels, messageId };
+}
+
+const unsupported = (station: Station, atts: CanonicalAttachment[]): string =>
+  `${station.name} cannot send attachments (${atts
+    .map((a) => kindOf(a.mime ?? '', a.path ?? a.url ?? a.name ?? ''))
+    .join(', ')}); send a link in \`text\` instead`;
+
+function noteSent(m: MessageArgs, messageId: string | undefined): void {
+  if (messageId !== undefined) m.onSent?.(messageId);
+}
+
+async function handleSend(m: MessageArgs): Promise<ToolResult> {
+  const text = m.a.text as string | undefined;
+  const replyTo = m.a.reply_to as string | undefined;
+  const requested = (m.a.attachments as CanonicalAttachment[] | undefined) ?? [];
+  if (!text && !requested.length)
+    return errResult('send requires `text` or `attachments`');
+  if (requested.length && m.station.attachmentMode === 'none')
+    return errResult(unsupported(m.station, requested));
+  const atts = await resolveAttachments(requested, {
+    allowed: allowedAgents(currentIdentity()),
+  });
+  try {
+    const native =
+      m.station.attachmentMode === 'native' &&
+      typeof m.station.sendAttachments === 'function';
+    const sent = native
+      ? await sendNative(m, text, replyTo, atts)
+      : await sendForwarded(m, text, replyTo, atts);
+    if (!sent.labels.length)
+      return errResult('send requires `text` or `attachments`');
+    noteSent(m, sent.messageId);
+    return ok(withId(`sent: ${sent.labels.join(', ')}`, sent.messageId));
+  } finally {
+    await cleanupAttachments(atts);
+  }
+}
+
+async function handleRead({ line, a, ctx }: MessageArgs): Promise<ToolResult> {
+  const args: Record<string, unknown> = { line };
+  if (typeof a.limit === 'number') args.limit = a.limit;
+  if (a.before) args.before = str(a.before);
+  if (a.since) args.since = str(a.since);
+  return okJson(await ctx.call('read', args));
+}
+
+type MessageHandler = (m: MessageArgs) => Promise<ToolResult>;
+
+interface VerbSpec {
+  args: readonly (readonly [string, string])[];
+  success: string;
+}
+
+const MESSAGE_VERBS: Record<string, VerbSpec> = {
+  reply: { args: [['message_id', 'replyTo'], ['text', 'text']], success: 'replied' },
+  react: { args: [['message_id', 'messageId'], ['emoji', 'emoji']], success: 'reacted' },
+  unreact: {
+    args: [['message_id', 'messageId'], ['emoji', 'emoji']],
+    success: 'reaction removed',
+  },
+  edit: { args: [['message_id', 'messageId'], ['text', 'text']], success: 'edited' },
+  delete: { args: [['message_id', 'messageId']], success: 'deleted' },
+};
+
+function makeVerbHandler(verb: string, spec: VerbSpec): MessageHandler {
+  return async ({ line, a, ctx, onSent }) => {
+    const payload: Record<string, unknown> = { line };
+    for (const [snake, camel] of spec.args) {
+      const value = str(a[snake]);
+      if (!value) {
+        const fields = spec.args.map(([snakeName]) => `\`${snakeName}\``).join(' and ');
+        return errResult(`${verb} requires ${fields}`);
+      }
+      payload[camel] = value;
+    }
+    const response = await ctx.call(verb, payload);
+    const messageId = messageIdOf(response);
+    if (verb === 'reply' && messageId !== undefined) onSent?.(messageId);
+    return ok(withId(spec.success, messageId));
+  };
+}
+
+const MESSAGE_HANDLERS: Record<string, MessageHandler> = {
+  send: handleSend,
+  read: handleRead,
+  ...Object.fromEntries(
+    Object.entries(MESSAGE_VERBS).map(([verb, spec]) => [verb, makeVerbHandler(verb, spec)]),
+  ),
+};
+
+export interface ToolHooks {
+  onSent?: (messageId: string) => void;
+}
+
+export async function dispatchMessageTool(
+  name: string,
+  a: Record<string, unknown>,
+  hooks: ToolHooks = {},
+): Promise<ToolResult> {
+  const line = str(a.line);
+  if (!line) return errResult(`${name} requires \`line\``);
+  const station = stationForLine(line);
+  if (!station || station.messageVerbs.size === 0) {
+    return errResult(
+      `${station?.name ?? 'these'} lines do not support outbound messaging (send/reply/react/unreact/edit/delete/read).`,
+    );
+  }
+  const handler = MESSAGE_HANDLERS[name];
+  if (!handler) return errResult(`unknown tool: ${name}`);
+  try {
+    return await handler({ line, a, ctx: makeCtx(station.name), station, onSent: hooks.onSent });
+  } catch (e) {
+    return toErr(name, e);
+  }
+}

package/runtime/node_modules/@metro-labs/mcp/src/mcp/channel-owner.ts

@@ -0,0 +1,29 @@
+import { eventInScope } from '../db/agent-scope.js';
+import { allowedAgents, type RequestIdentity } from './request-identity.js';
+import { sessionScopeKey } from './session-route.js';
+
+export class ChannelOwner {
+  private stream: RequestIdentity | undefined;
+
+  bindStream(identity: RequestIdentity): void {
+    this.stream = identity;
+  }
+
+  releaseStream(): void {
+    this.stream = undefined;
+  }
+
+  scope(): Set<string> {
+    return allowedAgents(this.stream);
+  }
+
+  streamBelongsTo(identity: RequestIdentity): boolean {
+    if (this.stream === undefined) return false;
+    return sessionScopeKey(this.stream) === sessionScopeKey(identity);
+  }
+
+  inScope(line: string): boolean {
+    if (this.stream === undefined) return false;
+    return eventInScope(this.scope(), line);
+  }
+}

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

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { forwardTrainCall } from '../daemon/train-call.js';
+import { errMsg, log } from '../daemon/log.js';
+import { TrainError } from '../daemon/train-error.js';
+import { type ToolContext, type ToolResult } from '../stations/types.js';
+
+export async function metroCall(
+  train: string,
+  action: string,
+  args: Record<string, unknown>,
+): Promise<{ result: unknown }> {
+  const line = typeof args.line === 'string' ? args.line : undefined;
+  log.info({ train, action, line }, 'metro: dispatching train call');
+  let response;
+  try {
+    response = await forwardTrainCall(train, action, args);
+  } catch (err) {
+    log.warn(
+      { train, action, line, err: errMsg(err) },
+      'metro: train call failed to dispatch',
+    );
+    throw new TrainError(
+      'metro_call_failed',
+      `metro ${action} ${train}: ${errMsg(err)}`,
+    );
+  }
+  if (response.error) {
+    log.warn(
+      { train, action, line, err: response.error },
+      'metro: train call returned error',
+    );
+    throw new TrainError(
+      'metro_call_error',
+      `metro ${action} ${train}: ${response.error}`,
+    );
+  }
+  log.info({ train, action, line }, 'metro: train call ok');
+  return { result: response.result ?? null };
+}
+
+export const ok = (text: string): ToolResult => ({
+  content: [{ type: 'text', text }],
+});
+export const okJson = (v: unknown): ToolResult => ({
+  content: [{ type: 'text', text: JSON.stringify(v, null, 2) }],
+});
+export const errResult = (text: string): ToolResult => ({
+  content: [{ type: 'text', text }],
+  isError: true,
+});
+export const toErr = (name: string, e: unknown): ToolResult =>
+  e instanceof TrainError
+    ? errResult(e.message)
+    : errResult(`metro ${name} failed: ${String(e)}`);
+
+export const makeCtx = (station: string): ToolContext => ({
+  call: (action, args) => metroCall(station, action, args),
+  ok,
+  okJson,
+  err: errResult,
+  readFile: (path) => readFile(path),
+});

package/runtime/node_modules/@metro-labs/mcp/src/mcp/event-store.ts

@@ -0,0 +1,91 @@
+import type {
+  EventStore,
+  EventId,
+  StreamId,
+} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { frameInScope, frameLine } from './frame-scope.js';
+
+const EVENT_STORE_MAX = 500;
+
+interface StoredEvent {
+  eventId: EventId;
+  streamId: StreamId;
+  message: JSONRPCMessage;
+  line: string | undefined;
+  owner: Set<string>;
+}
+
+export interface EventStoreDeps {
+  scopeOf: () => Set<string>;
+  max?: number;
+}
+
+export interface ScopedReplay {
+  send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+  scope: Set<string> | undefined;
+  onWithheld?: (eventId: EventId, line: string | undefined) => void;
+}
+
+const SEP = '_';
+
+const encodeEventId = (streamId: StreamId, seq: number): EventId =>
+  `${streamId}${SEP}${seq}`;
+
+const decodeStreamId = (eventId: EventId): StreamId | undefined => {
+  const idx = eventId.lastIndexOf(SEP);
+  if (idx <= 0) return undefined;
+  return eventId.slice(0, idx);
+};
+
+export class BoundedEventStore implements EventStore {
+  private readonly max: number;
+  private readonly scopeOf: () => Set<string>;
+  private readonly events: StoredEvent[] = [];
+  private seq = 0;
+
+  constructor(deps: EventStoreDeps) {
+    this.scopeOf = deps.scopeOf;
+    this.max = deps.max ?? EVENT_STORE_MAX;
+  }
+
+  storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId> {
+    const eventId = encodeEventId(streamId, ++this.seq);
+    this.events.push({
+      eventId,
+      streamId,
+      message,
+      line: frameLine(message),
+      owner: new Set(this.scopeOf()),
+    });
+    if (this.events.length > this.max) this.events.shift();
+    return Promise.resolve(eventId);
+  }
+
+  getStreamIdForEventId(eventId: EventId): Promise<StreamId | undefined> {
+    return Promise.resolve(decodeStreamId(eventId));
+  }
+
+  async replayEventsAfter(
+    lastEventId: EventId,
+    { send, scope, onWithheld }: ScopedReplay,
+  ): Promise<StreamId> {
+    const streamId = decodeStreamId(lastEventId);
+    if (streamId === undefined) return '';
+    const allowed = scope ?? new Set<string>();
+    let seen = false;
+    for (const e of this.events) {
+      if (e.streamId !== streamId) continue;
+      if (!seen) {
+        if (e.eventId === lastEventId) seen = true;
+        continue;
+      }
+      if (!frameInScope(allowed, e)) {
+        onWithheld?.(e.eventId, e.line);
+        continue;
+      }
+      await send(e.eventId, e.message);
+    }
+    return streamId;
+  }
+}

package/runtime/node_modules/@metro-labs/mcp/src/mcp/frame-scope.ts

@@ -0,0 +1,21 @@
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { eventInScope } from '../db/agent-scope.js';
+import { str } from './str.js';
+
+export interface FrameOrigin {
+  line: string | undefined;
+  owner: Set<string>;
+}
+
+export function frameLine(message: JSONRPCMessage): string | undefined {
+  const params: unknown = (message as { params?: unknown }).params;
+  if (typeof params !== 'object' || params === null) return undefined;
+  const meta: unknown = (params as { meta?: unknown }).meta;
+  if (typeof meta !== 'object' || meta === null) return undefined;
+  return str((meta as { line?: unknown }).line) || undefined;
+}
+
+export function frameInScope(scope: Set<string>, origin: FrameOrigin): boolean {
+  if (origin.line !== undefined) return eventInScope(scope, origin.line);
+  return origin.owner.size > 0 && [...origin.owner].every((id) => scope.has(id));
+}