@stage-labs/metro 0.1.0-beta.23 → 0.1.0-beta.231

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

@@ -1,5 +1,5 @@
-import { serializeTrainError, type TrainErrorInfo } from '../daemon/train-error.js';
-import type { Normalized } from './messaging-normalize.js';
+import { serializeTrainError, type TrainErrorInfo } from '../train-error.js';
+import type { Normalize } from './messaging-normalize.js';
 
 export const emit = (e: unknown): void =>
   void process.stdout.write(JSON.stringify(e) + '\n');
@@ -12,8 +12,7 @@ export const respond = (
     JSON.stringify({ op: 'response', id, ...body }) + '\n',
   );
 
-export const mintId = (): string =>
-  `msg_${Math.random().toString(36).slice(2, 10)}`;
+export { mintId } from '../ids.js';
 
 type Args = Record<string, unknown>;
 
@@ -28,30 +27,26 @@ export type StationHandler = (id: string, args: Args) => void | Promise<void>;
 
 export interface StationConfig {
   handlers: Record<string, StationHandler>;
-  normalize: (action: string, args: Args) => Normalized;
-  preDispatch?: (id: string, action: string) => boolean;
+  normalize?: Normalize;
 }
 
 const lineTag = (args: Args): string =>
   typeof args.line === 'string' ? args.line : '?';
 
-export function makeStation({ handlers, normalize, preDispatch }: StationConfig) {
+export function makeStation({ handlers, normalize }: StationConfig) {
   const known = Object.keys(handlers).join(', ');
   return async function handleCall(msg: CallMsg): Promise<void> {
     const { id } = msg;
     let action = msg.action;
     let args: Args = msg.args;
     try {
-      ({ action, args } = normalize(msg.action, msg.args));
-      emit({ op: 'log', text: `call ${action} recv (line=${lineTag(args)})` });
-      if (preDispatch?.(id, action)) return;
+      if (normalize && !handlers[action]) ({ action, args } = normalize(action, args));
       const handler = handlers[action];
       if (!handler) {
         respond(id, { error: `unknown action '${action}' (have: ${known})` });
         return;
       }
       await handler(id, args);
-      emit({ op: 'log', text: `call ${action} done (line=${lineTag(args)})` });
     } catch (err) {
       const info = serializeTrainError(err);
       emit({

package/runtime/node_modules/@metro-labs/core/src/stations/train-boot.ts

@@ -0,0 +1,42 @@
+import { errMsg } from '../log.js';
+import { readCalls } from '../protocol.js';
+import { TrainError } from '../train-error.js';
+import type { CallMsg } from './station-runtime.js';
+
+export function announceAccounts(station: string, ids: Iterable<string>): void {
+  const list = [...ids];
+  if (list.length === 0) {
+    process.stderr.write(`${station}: no accounts booted, exiting\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`${station} train ready — ${String(list.length)} account(s): ${list.join(', ')}\n`);
+}
+
+export interface ClientTrain<A extends { id: string }, C> {
+  station: string;
+  accounts: Map<string, A>;
+  loadAccounts: () => A[];
+  createClient: (account: A) => C;
+  startInbound: (client: C) => Promise<void>;
+  makeHandleCall: (clientFor: (accountId: string) => C) => (msg: CallMsg) => Promise<void>;
+}
+
+export function runClientTrain<A extends { id: string }, C>(train: ClientTrain<A, C>): void {
+  const clients = new Map<string, C>();
+  const clientFor = (accountId: string): C => {
+    const known = clients.get(accountId);
+    if (known !== undefined) return known;
+    const account = train.accounts.get(accountId);
+    if (!account) throw new TrainError('not_implemented', `unknown account '${accountId}'`);
+    const client = train.createClient(account);
+    clients.set(accountId, client);
+    return client;
+  };
+  readCalls(train.station, train.makeHandleCall(clientFor));
+  for (const cfg of train.loadAccounts()) train.accounts.set(cfg.id, cfg);
+  for (const id of train.accounts.keys())
+    train.startInbound(clientFor(id)).catch((err: unknown) => {
+      process.stderr.write(`${train.station}[${id}] inbound failed: ${errMsg(err)}\n`);
+    });
+  announceAccounts(train.station, train.accounts.keys());
+}

package/runtime/node_modules/@metro-labs/core/src/stations/train-events.ts

@@ -0,0 +1,84 @@
+import { mintId } from '../ids.js';
+import { emit } from './station-runtime.js';
+
+type Fields = Record<string, unknown>;
+type Out = (e: unknown) => void;
+
+export const selfUri = (): string => process.env.METRO_SELF_URI ?? 'metro://user';
+
+export function emitInbound(account: string, e: Fields, out: Out = emit): void {
+  out({
+    ...e,
+    payload: { ...(e.payload as Fields | undefined), account },
+  });
+}
+
+export interface AttachmentAt {
+  station: string;
+  account: string;
+  line: string;
+  forId: string;
+  index: number;
+  from?: string;
+}
+
+export interface SavedFile {
+  path: string;
+  mime?: string;
+  name?: string;
+  bytes?: number;
+}
+
+function attachmentEvent(at: AttachmentAt, text: string, payload: Fields): Fields {
+  return {
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: at.station,
+    line: at.line,
+    from: at.from ?? selfUri(),
+    text,
+    payload: { account: at.account, attachmentFor: at.forId, index: at.index, ...payload },
+  };
+}
+
+export const attachmentSavedEvent = (at: AttachmentAt & { saved: SavedFile; extra?: Fields }): Fields =>
+  attachmentEvent(at, `📎 saved: ${at.saved.path}`, {
+    contentType: 'attachmentSaved',
+    ...(at.saved.bytes === undefined ? {} : { size: at.saved.bytes }),
+    ...at.extra,
+    attachmentPath: at.saved.path,
+    mime: at.saved.mime,
+    name: at.saved.name,
+  });
+
+export const attachmentFailedEvent = (at: AttachmentAt & { reason: string; extra?: Fields }): Fields =>
+  attachmentEvent(at, `📎 not fetched: ${at.reason}`, {
+    contentType: 'attachmentFailed',
+    ...at.extra,
+    reason: at.reason,
+  });
+
+const reasonOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+export function reportAttachment(
+  save: Promise<SavedFile>,
+  at: AttachmentAt,
+  extra: { saved?: Fields; failed?: Fields } = {},
+  out: Out = emit,
+): void {
+  const tag = `${at.station}[${at.account}]`;
+  save
+    .then(
+      (saved) => {
+        out(attachmentSavedEvent({ ...at, saved, extra: extra.saved }));
+      },
+      (err: unknown) => {
+        const reason = reasonOf(err);
+        process.stderr.write(`${tag} attachment save failed: ${reason}\n`);
+        out(attachmentFailedEvent({ ...at, reason, extra: extra.failed }));
+      },
+    )
+    .catch((err: unknown) => {
+      process.stderr.write(`${tag} attachment event not emitted: ${reasonOf(err)}\n`);
+    });
+}

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

@@ -1,3 +1,5 @@
+import type { ProfileField } from './profile.js';
+
 export type Verb =
   | 'send'
   | 'reply'
@@ -5,7 +7,8 @@ export type Verb =
   | 'unreact'
   | 'edit'
   | 'delete'
-  | 'read';
+  | 'read'
+  | 'typing';
 
 export interface ToolResult {
   content: { type: 'text'; text: string }[];
@@ -32,10 +35,14 @@ export interface ToolContext {
   readFile(path: string): Promise<Buffer>;
 }
 
+export type ToolGroup = 'read' | 'write';
+
 export interface StationTool {
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  group?: ToolGroup;
+  destructive?: boolean;
   handle(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
 }
 
@@ -89,6 +96,8 @@ export interface GroupResult {
   inviteLink?: string;
 }
 
+export type ReadFilter = 'account' | 'query' | 'from' | 'until' | 'unread_only' | 'message_id';
+
 export type AttachmentMode = 'canonical' | 'native' | 'none';
 
 export interface Station {
@@ -97,7 +106,15 @@ export interface Station {
   hasTrain: boolean;
   messageVerbs: ReadonlySet<Verb>;
   groupOps?: ReadonlySet<GroupOp>;
+  resolvesSenders?: boolean;
+  profileFields?: ReadonlySet<ProfileField>;
+  claimsName?: boolean;
+  readsProfiles?: boolean;
+  readFilters?: ReadonlySet<ReadFilter>;
+  approvals?: boolean;
   attachmentMode: AttachmentMode;
+  forget?: (accountId: string) => void;
+  forgetExcept?: (keptAccountIds: readonly string[]) => void;
   sendAttachments?(
     line: string,
     atts: CanonicalAttachment[],

package/runtime/node_modules/@metro-labs/core/src/tickets.ts

@@ -0,0 +1,37 @@
+import { randomBytes } from 'node:crypto';
+
+export interface TicketStore<T> {
+  mint: (value: T, now?: number) => { ticket: string; expiresAt: number };
+  take: (ticket: string, now?: number) => T | undefined;
+  size: (now?: number) => number;
+}
+
+export function ticketStore<T>(ttlMs: number, max: number): TicketStore<T> {
+  const open = new Map<string, { value: T; expiresAt: number }>();
+  const prune = (now: number): void => {
+    for (const [ticket, entry] of open) if (entry.expiresAt <= now) open.delete(ticket);
+  };
+  return {
+    mint(value, now = Date.now()) {
+      prune(now);
+      while (open.size >= max) {
+        const oldest = open.keys().next();
+        if (oldest.done === true) break;
+        open.delete(oldest.value);
+      }
+      const ticket = randomBytes(32).toString('base64url');
+      const expiresAt = now + ttlMs;
+      open.set(ticket, { value, expiresAt });
+      return { ticket, expiresAt };
+    },
+    take(ticket, now = Date.now()) {
+      const entry = open.get(ticket);
+      open.delete(ticket);
+      return entry !== undefined && entry.expiresAt > now ? entry.value : undefined;
+    },
+    size(now = Date.now()) {
+      prune(now);
+      return open.size;
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/core/src/version.ts

@@ -0,0 +1,2 @@
+export const METRO_VERSION =
+  process.env.METRO_VERSION ?? process.env.npm_package_version ?? 'dev';

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

@@ -0,0 +1,49 @@
+{
+  "name": "@metro-labs/daemon",
+  "version": "0.1.0-beta.15",
+  "private": true,
+  "description": "The metro daemon a user runs on their own machine with `metro serve`: the MCP server Claude Code connects to, the station subprocesses it supervises, the model gateway, and the signed-identity APIs the page at metro.box talks to.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bonustrack/metro.git"
+  },
+  "homepage": "https://github.com/bonustrack/metro#readme",
+  "bugs": "https://github.com/bonustrack/metro/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./src/mcp/index.ts"
+  },
+  "scripts": {
+    "start": "bun src/server.ts",
+    "build": "tsc",
+    "test": "tsc --noEmit && DYLD_FALLBACK_LIBRARY_PATH=/usr/lib METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/core": "workspace:*",
+    "@metro-labs/http": "workspace:*",
+    "@metro-labs/discord-bot": "workspace:*",
+    "@metro-labs/telegram": "workspace:*",
+    "@metro-labs/telegram-bot": "workspace:*",
+    "@metro-labs/threema": "workspace:*",
+    "@metro-labs/outlook": "workspace:*",
+    "@metro-labs/gmail": "workspace:*",
+    "@metro-labs/webhook": "workspace:*",
+    "@metro-labs/whatsapp": "workspace:*",
+    "@metro-labs/xmtp": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.2",
+    "@types/ws": "^8.18.0",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/agent-fs.ts

@@ -0,0 +1,134 @@
+import { spawn, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import type { Readable } from 'node:stream';
+import { runningAsMetro } from '../metro-user/privilege.js';
+import { agentUser, asUser } from './user.js';
+
+export interface AgentStat {
+  size: number;
+  mtime: Date;
+  mtimeMs: number;
+  mode: number;
+  isFile: () => boolean;
+  isDirectory: () => boolean;
+  isSymbolicLink: () => boolean;
+}
+
+export interface AgentDirent {
+  name: string;
+  isFile: () => boolean;
+  isDirectory: () => boolean;
+  isSymbolicLink: () => boolean;
+}
+
+const MAX_OUTPUT = 256 * 1024 * 1024;
+
+const refused = (err: unknown): boolean => {
+  const code = (err as { code?: unknown } | null)?.code;
+  return (code === 'EACCES' || code === 'EPERM') && runningAsMetro();
+};
+
+function asAgentSh(script: string, args: string[]): Buffer {
+  const [file, argv] = asUser(agentUser(), 'sh', ['-c', script, 'metro', ...args]);
+  const run = spawnSync(file, argv, { maxBuffer: MAX_OUTPUT, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (run.error !== undefined) throw run.error;
+  if (run.status !== 0) {
+    const err = new Error(run.stderr.toString('utf8').trim() || `no such file or directory, ${args[0] ?? ''}`) as Error & { code: string };
+    err.code = 'ENOENT';
+    throw err;
+  }
+  return run.stdout;
+}
+
+function viaAgent<T>(native: () => T, fallback: () => T): T {
+  try {
+    return native();
+  } catch (err) {
+    if (!refused(err)) throw err;
+    return fallback();
+  }
+}
+
+export function existsSync(path: string): boolean {
+  try {
+    fs.accessSync(path, fs.constants.F_OK);
+    return true;
+  } catch (err) {
+    if (!refused(err)) return false;
+    try {
+      asAgentSh('test -e "$1"', [path]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+const kindTests = (kind: string): Pick<AgentStat, 'isFile' | 'isDirectory' | 'isSymbolicLink'> => ({
+  isFile: () => kind === 'f',
+  isDirectory: () => kind === 'd',
+  isSymbolicLink: () => kind === 'l',
+});
+
+function agentStat(path: string, follow: boolean): AgentStat {
+  const out = asAgentSh(`stat ${follow ? '-L ' : ''}-c "%s %Y %f %F" -- "$1"`, [path]).toString('utf8').trim();
+  const [size = '0', mtime = '0', mode = '0', ...type] = out.split(' ');
+  const kind = type.join(' ') === 'directory' ? 'd' : type.join(' ') === 'symbolic link' ? 'l' : 'f';
+  const ms = Number(mtime) * 1000;
+  return { size: Number(size), mtime: new Date(ms), mtimeMs: ms, mode: parseInt(mode, 16), ...kindTests(kind) };
+}
+
+export const statSync = (path: string): AgentStat => viaAgent(() => fs.statSync(path), () => agentStat(path, true));
+
+export const realpathSync = (path: string): string =>
+  viaAgent(() => fs.realpathSync(path), () => asAgentSh('realpath -e -- "$1"', [path]).toString('utf8').trim());
+
+export function readFileSync(path: string, encoding: 'utf8'): string {
+  return viaAgent(() => fs.readFileSync(path, encoding), () => asAgentSh('cat -- "$1"', [path]).toString('utf8'));
+}
+
+export function readRange(path: string, start: number, length: number): Buffer {
+  return viaAgent(
+    () => {
+      const fd = fs.openSync(path, 'r');
+      try {
+        const buffer = Buffer.alloc(length);
+        return buffer.subarray(0, fs.readSync(fd, buffer, 0, length, start));
+      } finally {
+        fs.closeSync(fd);
+      }
+    },
+    () => asAgentSh('tail -c +"$2" -- "$1" | head -c "$3"', [path, String(start + 1), String(length)]),
+  );
+}
+
+export function readdirNames(path: string): string[] {
+  return readdirEntries(path).map((e) => e.name);
+}
+
+export function readdirEntries(path: string): AgentDirent[] {
+  return viaAgent(
+    () => fs.readdirSync(path, { withFileTypes: true }),
+    () =>
+      asAgentSh('find -H "$1" -mindepth 1 -maxdepth 1 -printf "%y\\t%f\\0"', [path])
+        .toString('utf8')
+        .split('\0')
+        .filter((line) => line.includes('\t'))
+        .map((line) => {
+          const at = line.indexOf('\t');
+          return { name: line.slice(at + 1), ...kindTests(line.slice(0, at)) };
+        }),
+  );
+}
+
+export function createReadStream(path: string): Readable {
+  try {
+    fs.accessSync(path, fs.constants.R_OK);
+    return fs.createReadStream(path);
+  } catch (err) {
+    if (!refused(err)) return fs.createReadStream(path);
+    const [file, argv] = asUser(agentUser(), 'cat', ['--', path]);
+    const child = spawn(file, argv, { stdio: ['ignore', 'pipe', 'ignore'] });
+    return child.stdout;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/crontab.ts

@@ -0,0 +1,44 @@
+import type { Runner } from './schedules.js';
+import type { AgentUser } from './user.js';
+
+const NO_CRONTAB = /no crontab for/i;
+
+const indexesOf = (lines: string[], marker: string): number[] => lines.flatMap((l, i) => (l === marker ? [i] : []));
+
+function outsideBlock(lines: string[], begin: string, end: string): string[] {
+  const starts = indexesOf(lines, begin);
+  const stops = indexesOf(lines, end);
+  const [start = -1] = starts;
+  const [stop = -1] = stops;
+  if (starts.length !== 1 || stops.length !== 1 || stop < start) return lines;
+  return [...lines.slice(0, start), ...lines.slice(stop + 1)];
+}
+
+export function withBlock(lines: string[], begin: string, end: string, block: string[], at: 'top' | 'end', owned: (line: string) => boolean = () => false): string[] {
+  const kept = outsideBlock(lines, begin, end).filter((l) => l !== '' && l !== begin && l !== end && !owned(l));
+  if (block.length === 0) return kept;
+  const wrapped = [begin, ...block, end];
+  return at === 'top' ? [...wrapped, ...kept] : [...kept, ...wrapped];
+}
+
+const failure = (what: string, user: AgentUser, out: { status: number | null; stderr?: string }): Error =>
+  new Error(`could not ${what} the crontab of ${user.name}: ${(out.stderr ?? '').trim() || `exit ${String(out.status)}`}`);
+
+export function readCrontab(user: AgentUser, runner: Runner): string[] {
+  const out = runner.run('crontab', ['-l', '-u', user.name]);
+  if (out.status === 0) return out.stdout.split('\n');
+  if (out.status === 1 && NO_CRONTAB.test(out.stderr ?? '')) return [];
+  throw failure('read', user, out);
+}
+
+export function writeCrontab(user: AgentUser, runner: Runner, lines: string[], next: string[]): boolean {
+  if (next.join('\n') === lines.filter((l) => l !== '').join('\n')) return false;
+  const out = runner.run('crontab', ['-u', user.name, '-'], next.length === 0 ? '' : `${next.join('\n')}\n`);
+  if (out.status !== 0) throw failure('write', user, out);
+  return true;
+}
+
+export function editCrontab(user: AgentUser, runner: Runner, change: (lines: string[]) => string[]): boolean {
+  const lines = readCrontab(user, runner);
+  return writeCrontab(user, runner, lines, change(lines));
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/files-api.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { sessionRoute } from '@metro-labs/http/api-http';
+import { readAgentPath } from './files.js';
+import { agentUser } from './user.js';
+
+const PATH = '/api/files';
+
+const queryPath = (req: IncomingMessage): string => new URLSearchParams((req.url ?? '').split('?')[1] ?? '').get('path') ?? '';
+
+export function handleFilesRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET'] }, admin: true, label: 'files-api' }, () => Promise.resolve(readAgentPath(agentUser(), queryPath(req))));
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/files.ts

@@ -0,0 +1,89 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { asUser, type AgentUser } from './user.js';
+
+type EntryKind = 'folder' | 'file' | 'other';
+
+interface FileEntry {
+  name: string;
+  kind: EntryKind;
+  bytes: number;
+  modifiedAt: string;
+}
+
+export type FilesAnswer =
+  | { root: string; path: string; kind: 'folder'; entries: FileEntry[]; more: boolean }
+  | { root: string; path: string; kind: 'file'; bytes: number; modifiedAt: string; text: string | null; truncated: boolean };
+
+const MAX_ENTRIES = 2000;
+const PREVIEW_BYTES = 256 * 1024;
+const SNIFF_BYTES = 8192;
+
+const SCRIPT = [
+  'if [ -d "$1" ]; then',
+  '  printf "D\\0"; find -H "$1" -mindepth 1 -maxdepth 1 -printf "%y\\0%s\\0%T@\\0%f\\0"',
+  'elif [ -f "$1" ]; then',
+  '  printf "F\\0"; stat -L -c "%s %Y" -- "$1" | tr "\\n" "\\0"; head -c "$2" -- "$1"',
+  'else',
+  '  echo "no such file or folder" >&2; exit 2',
+  'fi',
+].join('\n');
+
+export function segmentsOf(path: string): string[] {
+  const parts = path.split('/').filter((part) => part !== '');
+  if (parts.some((part) => part === '.' || part === '..' || part.includes('\0')))
+    throw new ApiError('that path is not inside the home folder', 400);
+  return parts;
+}
+
+const stamp = (seconds: number): string => (Number.isFinite(seconds) && seconds > 0 ? new Date(seconds * 1000).toISOString() : '');
+
+const kindOf = (letter: string): EntryKind => (letter === 'd' ? 'folder' : letter === 'f' ? 'file' : 'other');
+
+const byKindThenName = (a: FileEntry, b: FileEntry): number =>
+  a.kind === 'folder' && b.kind !== 'folder' ? -1 : b.kind === 'folder' && a.kind !== 'folder' ? 1 : a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' });
+
+function preview(bytes: Buffer, size: number): { text: string | null; truncated: boolean } {
+  const binary = bytes.subarray(0, SNIFF_BYTES).includes(0);
+  return { text: binary ? null : bytes.subarray(0, PREVIEW_BYTES).toString('utf8'), truncated: size > PREVIEW_BYTES };
+}
+
+function folderAnswer(root: string, path: string, entries: FileEntry[]): FilesAnswer {
+  const sorted = entries.sort(byKindThenName);
+  return { root, path, kind: 'folder', entries: sorted.slice(0, MAX_ENTRIES), more: sorted.length > MAX_ENTRIES };
+}
+
+function parseListing(out: Buffer): FileEntry[] {
+  const fields = out.toString('utf8').split('\0');
+  const entries: FileEntry[] = [];
+  for (let at = 0; at + 3 < fields.length; at += 4)
+    entries.push({ kind: kindOf(fields[at] ?? ''), bytes: Number(fields[at + 1]), modifiedAt: stamp(Number(fields[at + 2])), name: fields[at + 3] ?? '' });
+  return entries;
+}
+
+function parseFile(root: string, path: string, out: Buffer): FilesAnswer {
+  const end = out.indexOf(0);
+  const [size = '0', mtime = '0'] = out.subarray(0, end).toString('utf8').trim().split(' ');
+  const bytes = Number(size);
+  return { root, path, kind: 'file', bytes, modifiedAt: stamp(Number(mtime)), ...preview(out.subarray(end + 1), bytes) };
+}
+
+function readAsAgent(user: AgentUser, path: string): FilesAnswer {
+  const target = join(user.home, ...segmentsOf(path));
+  const [file, argv] = asUser(user, 'sh', ['-c', SCRIPT, 'metro', target, String(PREVIEW_BYTES + 1)]);
+  const run = spawnSync(file, argv, { stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024, timeout: 20_000 });
+  if (run.error !== undefined) throw new ApiError(`could not read that path: ${run.error.message}`, 500);
+  if (run.status !== 0) throw new ApiError(run.stderr.toString('utf8').trim() || 'the agent cannot read that path', 404);
+  return answerOf(user.home, path, run.stdout);
+}
+
+export function answerOf(root: string, path: string, out: Buffer): FilesAnswer {
+  const body = out.subarray(2);
+  return out.subarray(0, 1).toString() === 'D' ? folderAnswer(root, path, parseListing(body)) : parseFile(root, path, body);
+}
+
+export function readAgentPath(user: AgentUser | null, path: string): FilesAnswer {
+  if (user === null) throw new ApiError('Claude Code does not run as its own user on this machine, so there is no agent folder to show', 409);
+  return readAsAgent(user, path);
+}