@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

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

@@ -0,0 +1,58 @@
+import { TrainError } from '../train-error.js';
+
+export const PROFILE_FIELDS = ['name', 'bio', 'avatar'] as const;
+export type ProfileField = (typeof PROFILE_FIELDS)[number];
+
+export const NAME_MAX = 64;
+export const BIO_MAX = 512;
+
+export interface ProfileAvatar {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ProfileChange {
+  name?: string;
+  bio?: string;
+  avatar?: ProfileAvatar;
+}
+
+export interface ProfileApplied {
+  account: string;
+  applied: ProfileField[];
+}
+
+const text = (value: unknown, field: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw new TrainError('bad_request', `${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === '') throw new TrainError('bad_request', `${field} cannot be empty`);
+  if (trimmed.length > max) throw new TrainError('bad_request', `${field} is over ${String(max)} characters`);
+  return trimmed;
+};
+
+function avatarOf(value: unknown): ProfileAvatar | undefined {
+  if (value === undefined) return undefined;
+  const raw = (value ?? {}) as Record<string, unknown>;
+  if (typeof raw.path !== 'string' || raw.path === '') throw new TrainError('bad_request', 'avatar needs a local file');
+  return { path: raw.path, mime: typeof raw.mime === 'string' ? raw.mime : 'application/octet-stream', name: typeof raw.name === 'string' ? raw.name : 'avatar' };
+}
+
+export function parseProfileChange(args: Record<string, unknown>): ProfileChange {
+  const change: ProfileChange = {};
+  const name = text(args.name, 'name', NAME_MAX);
+  const bio = text(args.bio, 'bio', BIO_MAX);
+  const avatar = avatarOf(args.avatar);
+  if (name !== undefined) change.name = name;
+  if (bio !== undefined) change.bio = bio;
+  if (avatar !== undefined) change.avatar = avatar;
+  if (Object.keys(change).length === 0) throw new TrainError('bad_request', 'set_profile needs at least one of name, bio, avatar');
+  return change;
+}
+
+export const fieldsOf = (change: ProfileChange): ProfileField[] => PROFILE_FIELDS.filter((f) => change[f] !== undefined);
+
+export const assertImage = (avatar: ProfileAvatar): void => {
+  if (!avatar.mime.startsWith('image/')) throw new TrainError('bad_request', `avatar must be an image, not ${avatar.mime}`);
+};

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

@@ -0,0 +1,64 @@
+export interface SenderProfile {
+  id: string;
+  name?: string;
+  display_name?: string;
+  about?: string;
+  avatar?: string;
+  address?: string;
+}
+
+export interface ProfileCacheOptions {
+  ttlMs?: number;
+  max?: number;
+  onError: (key: string, err: unknown) => void;
+}
+
+export interface ProfileCache<T> {
+  get(key: string): Promise<T | null>;
+  peek(key: string): T | null;
+}
+
+const TTL_MS = 10 * 60_000;
+const MAX = 2000;
+
+interface Held<T> {
+  at: number;
+  value: Promise<T | null>;
+  settled: T | null;
+}
+
+export const nonEmpty = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined);
+
+export function makeProfileCache<T>(lookup: (key: string) => Promise<T | null>, opts: ProfileCacheOptions): ProfileCache<T> {
+  const ttl = opts.ttlMs ?? TTL_MS;
+  const max = opts.max ?? MAX;
+  const cache = new Map<string, Held<T>>();
+  const fresh = (key: string): Held<T> | undefined => {
+    const held = cache.get(key);
+    return held !== undefined && Date.now() - held.at < ttl ? held : undefined;
+  };
+  const start = (key: string): Held<T> => {
+    const held: Held<T> = { at: Date.now(), settled: null, value: Promise.resolve(null) };
+    held.value = lookup(key)
+      .then((value) => {
+        held.settled = value;
+        return value;
+      })
+      .catch((err: unknown) => {
+        opts.onError(key, err);
+        cache.delete(key);
+        return null;
+      });
+    cache.set(key, held);
+    while (cache.size > max) {
+      const oldest = cache.keys().next();
+      if (oldest.done) break;
+      cache.delete(oldest.value);
+    }
+    return held;
+  };
+  return {
+    get: (key) => (fresh(key) ?? start(key)).value,
+    peek: (key) => (fresh(key) ?? start(key)).settled,
+  };
+}

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

@@ -0,0 +1,59 @@
+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');
+
+export const respond = (
+  id: string,
+  body: { result?: unknown; error?: string; errorInfo?: TrainErrorInfo },
+): void =>
+  void process.stdout.write(
+    JSON.stringify({ op: 'response', id, ...body }) + '\n',
+  );
+
+export { mintId } from '../ids.js';
+
+type Args = Record<string, unknown>;
+
+export interface CallMsg {
+  op: 'call';
+  id: string;
+  action: string;
+  args: Args;
+}
+
+export type StationHandler = (id: string, args: Args) => void | Promise<void>;
+
+export interface StationConfig {
+  handlers: Record<string, StationHandler>;
+  normalize?: Normalize;
+}
+
+const lineTag = (args: Args): string =>
+  typeof args.line === 'string' ? args.line : '?';
+
+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 {
+      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);
+    } catch (err) {
+      const info = serializeTrainError(err);
+      emit({
+        op: 'log',
+        text: `call ${action} FAILED (line=${lineTag(args)}): ${info.error}`,
+      });
+      respond(id, info);
+    }
+  };
+}

package/runtime/sdk-runner/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/sdk-runner/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/sdk-runner/node_modules/@metro-labs/core/src/stations/types.ts

@@ -0,0 +1,125 @@
+import type { ProfileField } from './profile.js';
+
+export type Verb =
+  | 'send'
+  | 'reply'
+  | 'react'
+  | 'unreact'
+  | 'edit'
+  | 'delete'
+  | 'read'
+  | 'typing';
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+export interface CanonicalAttachment {
+  path?: string;
+  url?: string;
+  data?: string;
+  upload?: string;
+  mime?: string;
+  name?: string;
+}
+
+export interface ToolContext {
+  call(
+    action: string,
+    args: Record<string, unknown>,
+  ): Promise<{ result: unknown }>;
+  ok(text: string): ToolResult;
+  okJson(value: unknown): ToolResult;
+  err(text: string): ToolResult;
+  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>;
+}
+
+export interface MetroMember {
+  id: string;
+  name?: string;
+  display_name?: string;
+  address?: string;
+  roles?: string[];
+  is_admin?: boolean;
+  is_bot?: boolean;
+}
+
+export interface MemberCapability {
+  supported: boolean;
+  complete: boolean;
+  reason?: string;
+  total?: number;
+}
+
+export interface MemberList {
+  members: MetroMember[];
+  capability: MemberCapability;
+}
+
+export type GroupOp =
+  | 'create_group'
+  | 'add_members'
+  | 'remove_members'
+  | 'invite_link';
+
+export type MemberOutcomeStatus = 'added' | 'invited' | 'removed' | 'failed';
+
+export interface MemberOutcome {
+  id: string;
+  status: MemberOutcomeStatus;
+  reason?: string;
+}
+
+export interface GroupCapability {
+  supported: boolean;
+  reason?: string;
+}
+
+export interface GroupResult {
+  capability: GroupCapability;
+  line?: string;
+  id?: string;
+  name?: string;
+  members?: MemberOutcome[];
+  inviteLink?: string;
+}
+
+export type ReadFilter = 'account' | 'query' | 'from' | 'until' | 'unread_only' | 'message_id';
+
+export type AttachmentMode = 'canonical' | 'native' | 'none';
+
+export interface Station {
+  name: string;
+  hasAccounts: boolean;
+  hasTrain: boolean;
+  messageVerbs: ReadonlySet<Verb>;
+  groupOps?: ReadonlySet<GroupOp>;
+  resolvesSenders?: boolean;
+  profileFields?: ReadonlySet<ProfileField>;
+  claimsName?: boolean;
+  readsProfiles?: boolean;
+  readFilters?: ReadonlySet<ReadFilter>;
+  approvals?: boolean;
+  sendsFrames?: boolean;
+  attachmentMode: AttachmentMode;
+  forget?: (accountId: string) => void;
+  forgetExcept?: (keptAccountIds: readonly string[]) => void;
+  sendAttachments?(
+    line: string,
+    atts: CanonicalAttachment[],
+    ctx: ToolContext,
+  ): Promise<string[]>;
+  tools: StationTool[];
+}

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

@@ -0,0 +1,5 @@
+export function str(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  return '';
+}

package/runtime/sdk-runner/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/sdk-runner/node_modules/@metro-labs/core/src/train-error.ts

@@ -0,0 +1,53 @@
+export interface TrainErrorInfo {
+  code: string;
+  message: string;
+  retryable?: boolean;
+  retryAfterMs?: number;
+}
+
+export class TrainError extends Error {
+  readonly code: string;
+  readonly retryable?: boolean;
+  readonly retryAfterMs?: number;
+  constructor(
+    code: string,
+    message: string,
+    opts?: { retryable?: boolean; retryAfterMs?: number },
+  ) {
+    super(message);
+    this.name = 'TrainError';
+    this.code = code;
+    this.retryable = opts?.retryable;
+    this.retryAfterMs = opts?.retryAfterMs;
+  }
+  toErrorInfo(): TrainErrorInfo {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.retryable !== undefined ? { retryable: this.retryable } : {}),
+      ...(this.retryAfterMs !== undefined
+        ? { retryAfterMs: this.retryAfterMs }
+        : {}),
+    };
+  }
+}
+
+export function serializeTrainError(err: unknown): {
+  error: string;
+  errorInfo?: TrainErrorInfo;
+} {
+  if (err instanceof TrainError)
+    return { error: err.message, errorInfo: err.toErrorInfo() };
+  return { error: err instanceof Error ? err.message : String(err) };
+}
+
+export function coerceErrorInfo(v: unknown): TrainErrorInfo | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const o = v as Record<string, unknown>;
+  if (typeof o.code !== 'string' || typeof o.message !== 'string')
+    return undefined;
+  const info: TrainErrorInfo = { code: o.code, message: o.message };
+  if (typeof o.retryable === 'boolean') info.retryable = o.retryable;
+  if (typeof o.retryAfterMs === 'number') info.retryAfterMs = o.retryAfterMs;
+  return info;
+}

package/runtime/sdk-runner/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/sdk-runner/runner.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.1.0-beta.261",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.287",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.0.0"
+  }
+}

package/runtime/sdk-runner/src/activity-tasks.ts

@@ -0,0 +1,142 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RunnerEventKind, RunnerTask, RunnerTaskState } from '@metro-labs/core/runner-activity';
+
+export const activityName = (name: unknown): string | null => typeof name === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(name) ? name : null;
+const live = (task: RunnerTask): boolean => ['running', 'pending', 'paused'].includes(task.status);
+const terminal = (status: RunnerTaskState): boolean => ['completed', 'failed', 'stopped'].includes(status);
+type System = Extract<SDKMessage, { type: 'system' }>;
+type Emit = (kind: RunnerEventKind, tool?: string | null, taskId?: string | null) => void;
+
+export class ActivityTasks {
+  private readonly tasks = new Map<string, RunnerTask>();
+  private readonly parents = new Map<string, string>();
+  private readonly hidden = new Map<string, string>();
+  constructor(private readonly emit: Emit) {}
+
+  snapshot(): RunnerTask[] {
+    return [...this.tasks.values()].sort((a, b) => Number(live(b)) - Number(live(a)) || b.updatedAt - a.updatedAt).slice(0, 30).map((task) => ({ ...task }));
+  }
+
+  get running(): number { return [...this.tasks.values()].filter(live).length; }
+  taskFor(parent: string | null | undefined): string | null { return parent ? this.parents.get(parent) ?? null : null; }
+  known(id: string | null | undefined): string | null { return id && this.tasks.has(id) ? id : null; }
+  isHidden(id: string | null): boolean { return id !== null && this.hidden.has(id); }
+  isFinished(id: string): boolean { const task = this.tasks.get(id); return task !== undefined && !live(task); }
+
+  observe(message: System): void {
+    switch (message.subtype) {
+      case 'task_started': this.start(message); break;
+      case 'task_progress': this.progress(message); break;
+      case 'task_updated': this.patch(message); break;
+      case 'task_notification': this.end(message); break;
+      case 'background_tasks_changed': this.replace(message); break;
+      default: break;
+    }
+  }
+
+  stop(): void {
+    for (const task of this.tasks.values()) if (live(task)) this.status(task, 'stopped');
+  }
+
+  private get(id: string): RunnerTask | null {
+    if (!activityName(id) || this.hidden.has(id)) return null;
+    const known = this.tasks.get(id);
+    if (known) return known;
+    if (this.tasks.size >= 200) {
+      const old = [...this.tasks.values()].find((task) => !live(task));
+      if (!old) return null;
+      this.tasks.delete(old.id);
+      for (const [parent, taskId] of this.parents) if (taskId === old.id) this.parents.delete(parent);
+    }
+    const task: RunnerTask = { id, kind: null, agent: null, status: 'unknown', background: false, startedAt: 0, updatedAt: Date.now(), endedAt: null, lastTool: null, toolUses: 0, durationMs: 0 };
+    this.tasks.set(id, task);
+    return task;
+  }
+
+  private hide(id: string, toolUseId?: string): void {
+    this.tasks.delete(id);
+    const parents = [...this.parents].filter(([, task]) => task === id).map(([parent]) => parent);
+    for (const key of [id, toolUseId, ...parents]) {
+      if (key === undefined) continue;
+      const oldest = this.hidden.keys().next();
+      if (this.hidden.size >= 400 && !oldest.done) this.hidden.delete(oldest.value);
+      this.hidden.set(key, id);
+    }
+  }
+
+  private show(id: string): RunnerTask | null {
+    this.hidden.delete(id);
+    const task = this.get(id);
+    if (!task) return null;
+    for (const [key, taskId] of this.hidden) {
+      if (taskId !== id) continue;
+      this.hidden.delete(key);
+      this.parents.set(key, id);
+    }
+    return task;
+  }
+
+  private start(message: Extract<System, { subtype: 'task_started' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id, message.tool_use_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    task.kind = activityName(message.task_type);
+    task.agent = activityName(message.subagent_type);
+    task.background = message.is_backgrounded === true;
+    task.startedAt = Date.now();
+    task.endedAt = null;
+    if (message.tool_use_id) this.parents.set(message.tool_use_id, task.id);
+    this.status(task, 'running');
+  }
+
+  private progress(message: Extract<System, { subtype: 'task_progress' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task || terminal(task.status)) return;
+    task.lastTool = activityName(message.last_tool_name);
+    task.toolUses = message.usage.tool_uses;
+    task.durationMs = message.usage.duration_ms;
+    task.updatedAt = Date.now();
+  }
+
+  private patch(message: Extract<System, { subtype: 'task_updated' }>): void {
+    const task = this.tasks.get(message.task_id);
+    if (!task) return;
+    if (message.patch.is_backgrounded !== undefined) task.background = message.patch.is_backgrounded;
+    if (message.patch.status) this.status(task, message.patch.status === 'killed' ? 'stopped' : message.patch.status);
+    task.updatedAt = Date.now();
+  }
+
+  private end(message: Extract<System, { subtype: 'task_notification' }>): void {
+    if (message.ambient || message.skip_transcript) { this.hide(message.task_id); return; }
+    const task = this.get(message.task_id);
+    if (!task) return;
+    if (message.usage) {
+      task.durationMs = message.usage.duration_ms;
+      task.toolUses = message.usage.tool_uses;
+    }
+    this.status(task, message.status);
+  }
+
+  private replace(message: Extract<System, { subtype: 'background_tasks_changed' }>): void {
+    const ids = new Set(message.tasks.map((task) => task.task_id));
+    for (const task of this.tasks.values()) if (task.background && live(task) && !ids.has(task.id)) this.status(task, 'unknown');
+    for (const row of message.tasks) {
+      if (row.ambient) { this.hide(row.task_id); continue; }
+      const task = this.show(row.task_id);
+      if (!task || terminal(task.status)) continue;
+      task.kind = activityName(row.task_type);
+      task.background = true;
+      this.status(task, 'running');
+    }
+  }
+
+  private status(task: RunnerTask, status: RunnerTaskState): void {
+    const changed = task.status !== status;
+    task.status = status;
+    task.updatedAt = Date.now();
+    task.endedAt = terminal(status) ? task.updatedAt : null;
+    if (!changed) return;
+    const event: Partial<Record<RunnerTaskState, RunnerEventKind>> = { running: 'task_started', completed: 'task_completed', failed: 'task_failed', stopped: 'task_stopped' };
+    this.emit(event[status] ?? 'task_updated', null, task.id);
+  }
+}