@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

package/runtime/sdk-runner/src/skill-work.ts

@@ -0,0 +1,76 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const TERMINAL = new Set(['completed', 'failed', 'killed', 'stopped']);
+interface Task { tool: string | null; background: boolean }
+
+export class SkillWork {
+  private readonly tasks = new Map<string, Task>();
+  private readonly tools = new Map<string, string | null>();
+  private overflow = false;
+  get safe(): boolean { return !this.overflow && this.tasks.size === 0 && this.tools.size === 0; }
+
+  private blocks(message: Record<string, unknown>): void {
+    if (!isRecord(message.message) || !Array.isArray(message.message.content)) return;
+    const parent = typeof message.parent_tool_use_id === 'string' ? message.parent_tool_use_id : null;
+    for (const block of message.message.content.filter(isRecord)) {
+      if (block.type === 'tool_use' && typeof block.id === 'string') this.tools.set(block.id, parent);
+      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') this.tools.delete(block.tool_use_id);
+    }
+  }
+
+  private retire(id: string, tool = this.tasks.get(id)?.tool): void {
+    this.tasks.delete(id);
+    if (tool == null) return;
+    const retired = new Set([tool]);
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const [child, parent] of this.tools) {
+        if (parent === null || !retired.has(parent) || retired.has(child)) continue;
+        retired.add(child);
+        changed = true;
+      }
+    }
+    for (const child of retired) this.tools.delete(child);
+  }
+
+  private background(id: string, value: unknown): boolean {
+    return typeof value === 'boolean' ? value : this.tasks.get(id)?.background ?? false;
+  }
+
+  private task(message: Record<string, unknown>): void {
+    if (typeof message.task_id !== 'string') return;
+    const id = message.task_id;
+    const tool = typeof message.tool_use_id === 'string' ? message.tool_use_id : this.tasks.get(id)?.tool ?? null;
+    if (message.subtype === 'task_started') this.tasks.set(id, { tool, background: this.background(id, message.is_backgrounded) });
+    if (message.subtype === 'task_notification') this.retire(id, tool);
+    if (message.subtype === 'task_updated' && isRecord(message.patch)) this.patch(id, message.patch);
+  }
+
+  private patch(id: string, patch: Record<string, unknown>): void {
+    if (TERMINAL.has(String(patch.status))) { this.retire(id); return; }
+    if (!this.tasks.has(id) && !['running', 'paused', 'pending'].includes(String(patch.status))) return;
+    const task = this.tasks.get(id) ?? { tool: null, background: false };
+    if (typeof patch.is_backgrounded === 'boolean') task.background = patch.is_backgrounded;
+    this.tasks.set(id, task);
+  }
+
+  private snapshot(entries: unknown[]): void {
+    const ids = new Set(entries.filter(isRecord).flatMap((task) => typeof task.task_id === 'string' ? [task.task_id] : []));
+    for (const [id, task] of this.tasks) if (task.background && !ids.has(id)) this.retire(id);
+    for (const id of ids) this.tasks.set(id, { tool: this.tasks.get(id)?.tool ?? null, background: true });
+  }
+
+  private frontDone(message: Record<string, unknown>): void {
+    if (message.parent_tool_use_id != null) return;
+    for (const [id, parent] of this.tools) if (parent === null) this.tools.delete(id);
+  }
+
+  observe(message: Record<string, unknown>): void {
+    if (this.overflow) return;
+    this.blocks(message);
+    if (message.type === 'result') this.frontDone(message);
+    if (message.type === 'system') this.task(message);
+    if (message.subtype === 'background_tasks_changed' && Array.isArray(message.tasks)) this.snapshot(message.tasks);
+    this.overflow = this.tools.size > 4096 || this.tasks.size > 4096;
+  }
+}

package/runtime/sdk-runner/src/skills-files.ts

@@ -0,0 +1,169 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readSync, lstatSync, statSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_FILE_MAX, SKILL_HASH, SKILL_MANIFEST_MAX, skillGeneration, skillRelease, type SkillGeneration } from '@metro-labs/core/skill-source';
+
+const digest = (bytes: string | Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+const LINK = /^\.\.\/releases\/[a-f0-9]{64}\/visible-[a-f0-9]{64}$/;
+
+function directory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  if (!lstatSync(path).isDirectory()) throw new Error('The managed skills directory is not a regular directory.');
+}
+
+export function prepareSkillsRoot(root: string): void {
+  directory(root);
+  directory(join(root, 'releases'));
+  directory(join(root, '.claude'));
+}
+
+export function pendingSkills(root: string): SkillGeneration | null {
+  const path = join(root, 'pending.json');
+  let stat;
+  try { stat = lstatSync(path); } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return null; throw err; }
+  if (!stat.isFile() || stat.size > SKILL_MANIFEST_MAX) throw new Error('Invalid pending skills manifest.');
+  return skillGeneration(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+}
+
+function localText(file: string): string {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > SKILL_FILE_MAX) throw new Error('A local skill cannot be checked safely.');
+    const bytes = Buffer.alloc(SKILL_FILE_MAX + 1);
+    let size = 0;
+    for (;;) {
+      const read = readSync(fd, bytes, size, bytes.length - size, size);
+      if (read === 0) break;
+      size += read;
+      if (size === bytes.length) break;
+    }
+    if (size > SKILL_FILE_MAX) throw new Error('A local skill is too large.');
+    return bytes.subarray(0, size).toString('utf8');
+  } finally { closeSync(fd); }
+}
+
+export type LocalAliases = Map<string, { signature: string; name: string | null }>;
+
+function localAlias(file: string, cache: LocalAliases): string | null {
+  try {
+    const stat = statSync(file);
+    const signature = `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    const cached = cache.get(file);
+    if (cached?.signature === signature) return cached.name;
+    const header = /^---\r?\n([\s\S]*?)\r?\n---/.exec(localText(file))?.[1];
+    const meta: unknown = header === undefined ? null : Bun.YAML.parse(header);
+    const name = isRecord(meta) && typeof meta.name === 'string' ? meta.name : null;
+    cache.set(file, { signature, name });
+    return name;
+  } catch (err) { return isRecord(err) && ['ENOENT', 'ENOTDIR'].includes(String(err.code)) ? null : '*'; }
+}
+
+export function localSkillNames(claude: string, cache: LocalAliases = new Map()): string[] {
+  const names = new Set<string>();
+  let folders: string[];
+  try { folders = readdirSync(join(claude, 'skills')); } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return []; throw err; }
+  if (folders.length > 2000) return ['*'];
+  const paths = new Set<string>();
+  for (const name of folders) {
+    names.add(name);
+    const path = join(claude, 'skills', name, 'SKILL.md');
+    paths.add(path);
+    const alias = localAlias(path, cache);
+    if (alias !== null) names.add(alias);
+  }
+  for (const path of cache.keys()) if (!paths.has(path)) cache.delete(path);
+  return [...names].sort();
+}
+
+export function projectionKey(generation: SkillGeneration, locals: string[]): string {
+  return `${generation.id}:${digest(JSON.stringify(locals))}`;
+}
+
+function onlyManifestFiles(root: string, generation: SkillGeneration): void {
+  const files = new Set(generation.files.map((file) => file.path));
+  const directories = new Set(generation.files.flatMap((file) => file.path.split('/').slice(0, -1).map((_part, index, parts) => parts.slice(0, index + 1).join('/'))));
+  const visit = (path: string): void => {
+    for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+      const relative = path === '' ? entry.name : `${path}/${entry.name}`;
+      if (entry.isDirectory() && directories.has(relative)) visit(relative);
+      else if (!entry.isFile() || !files.has(relative)) throw new Error('Unexpected file in staged skills.');
+    }
+  };
+  visit('');
+}
+
+function verifiedFiles(release: string, generation: SkillGeneration): void {
+  directory(release);
+  directory(join(release, 'skills'));
+  onlyManifestFiles(join(release, 'skills'), generation);
+  for (const file of generation.files) {
+    let parent = join(release, 'skills');
+    for (const part of file.path.split('/').slice(0, -1)) {
+      parent = join(parent, part);
+      if (!lstatSync(parent).isDirectory()) throw new Error('A managed skill contains a linked directory.');
+    }
+    const path = join(release, 'skills', file.path);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size !== file.size || digest(readFileSync(path)) !== file.sha256) throw new Error('A staged skill changed before activation.');
+  }
+}
+
+export function projectSkills(root: string, generation: SkillGeneration, locals: string[]): { target: string; shadowed: string[] } {
+  prepareSkillsRoot(root);
+  const release = skillRelease(root, generation.id);
+  verifiedFiles(release, generation);
+  const shadowed = generation.skills.filter((skill) => locals.includes('*') || locals.includes(skill.name)).map((skill) => skill.name);
+  const name = `visible-${digest(JSON.stringify(locals))}`;
+  const visible = join(release, name);
+  directory(visible);
+  const expected = generation.skills.filter((skill) => !shadowed.includes(skill.name)).map((skill) => skill.name);
+  if (readdirSync(visible).some((entry) => !expected.includes(entry))) throw new Error('Unexpected file in skills projection.');
+  for (const skill of generation.skills) {
+    if (shadowed.includes(skill.name)) continue;
+    const path = join(visible, skill.name);
+    try { symlinkSync(`../skills/${skill.name}`, path, 'dir'); }
+    catch (err) { if (!isRecord(err) || err.code !== 'EEXIST' || readlinkSync(path) !== `../skills/${skill.name}`) throw err; }
+  }
+  return { target: `../releases/${generation.id}/${name}`, shadowed };
+}
+
+export function currentSkills(root: string): string | null {
+  try {
+    const target = readlinkSync(join(root, '.claude', 'skills'));
+    if (!LINK.test(target)) throw new Error('The managed skills link has an unexpected target.');
+    return target;
+  } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return null; throw err; }
+}
+
+export function switchSkills(root: string, target: string | null): void {
+  prepareSkillsRoot(root);
+  const link = join(root, '.claude', 'skills');
+  currentSkills(root);
+  if (target === null) { rmSync(link, { force: true }); return; }
+  if (!LINK.test(target)) throw new Error('Invalid managed skills target.');
+  const next = `${link}-${randomUUID()}`;
+  try { symlinkSync(target, next, 'dir'); renameSync(next, link); }
+  finally { rmSync(next, { force: true }); }
+}
+
+function oldRelease(path: string): boolean {
+  let stat;
+  try { stat = lstatSync(join(path, 'manifest.json')); }
+  catch (err) { if (!isRecord(err) || err.code !== 'ENOENT') throw err; stat = lstatSync(path); }
+  return Date.now() - stat.mtimeMs > 5 * 60_000;
+}
+
+export function pruneSkills(root: string, keep: Set<string>): void {
+  const pending = pendingSkills(root);
+  if (pending !== null) keep.add(pending.id);
+  for (const id of readdirSync(join(root, 'releases'))) {
+    if (!SKILL_HASH.test(id) || keep.has(id)) continue;
+    const release = skillRelease(root, id);
+    if (!lstatSync(release).isDirectory()) continue;
+    try {
+      if (oldRelease(release)) rmSync(release, { recursive: true });
+    } catch (err) { if (!isRecord(err) || err.code !== 'ENOENT') throw err; }
+  }
+}

package/runtime/sdk-runner/src/skills.ts

@@ -0,0 +1,150 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { log } from '@metro-labs/core/log';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import { SKILL_MANIFEST_MAX, type SkillActivation, type SkillGeneration } from '@metro-labs/core/skill-source';
+import { currentSkills, localSkillNames, pendingSkills, prepareSkillsRoot, projectionKey, projectSkills, pruneSkills, switchSkills, type LocalAliases } from './skills-files.js';
+
+interface SkillHooks {
+  safe(): boolean;
+  reload(): Promise<unknown>;
+  wake(): void;
+}
+const INITIAL: SkillActivation = { generation: null, loading: null, appliedAt: null, problem: null, shadowed: [] };
+class ReloadTimeout extends Error {}
+
+function savedStatus(root: string): unknown {
+  const path = join(root, 'status.json');
+  try {
+    if (lstatSync(path).size > SKILL_MANIFEST_MAX) throw new Error('Invalid skills status.');
+    return JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch (err) { if (isRecord(err) && err.code === 'ENOENT') return null; throw err; }
+}
+
+function repairInterrupted(root: string, raw: unknown): void {
+  if (!isRecord(raw) || typeof raw.loading !== 'string') return;
+  if (raw.rollback !== null && typeof raw.rollback !== 'string') throw new Error('Missing skills rollback target.');
+  switchSkills(root, raw.rollback);
+}
+
+function previousStatus(root: string): SkillActivation {
+  const raw = savedStatus(root);
+  repairInterrupted(root, raw);
+  const id = currentSkills(root)?.split('/')[2];
+  if (id === undefined) return { ...INITIAL };
+  if (!isRecord(raw) || raw.generation !== id || typeof raw.appliedAt !== 'string' || !Array.isArray(raw.shadowed)) throw new Error('Skills activation was interrupted.');
+  return { generation: id, appliedAt: raw.appliedAt, loading: null, problem: null, shadowed: raw.shadowed.filter((name): name is string => typeof name === 'string').slice(0, 64) };
+}
+
+async function reload(hooks: SkillHooks, timeout: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([hooks.reload(), new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => { reject(new ReloadTimeout('Skill reload timed out.')); }, timeout);
+    })]);
+  } finally { clearTimeout(timer); }
+}
+
+export class SkillsRefresh {
+  private hooks: SkillHooks | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly aliases: LocalAliases = new Map();
+  private key: string | null = null;
+  private failed: string | null = null;
+  private closed = false;
+  private prunedAt = 0;
+  private status: SkillActivation;
+  busy = false;
+
+  constructor(readonly root: string, private readonly claude: string, private readonly timeout = 20_000) {
+    prepareSkillsRoot(root);
+    this.status = previousStatus(root);
+    this.save();
+  }
+
+  start(hooks: SkillHooks): void {
+    this.hooks = hooks;
+    this.check();
+    this.timer = setInterval(() => { this.check(); }, 1000);
+    this.timer.unref();
+  }
+
+  close(): void {
+    this.closed = true;
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  check(): void {
+    if (this.closed || this.busy || this.hooks === null || !this.hooks.safe()) return;
+    try {
+      const generation = pendingSkills(this.root);
+      if (generation === null) return;
+      const locals = generation.skills.length === 0 ? [] : localSkillNames(this.claude, this.aliases);
+      const key = projectionKey(generation, locals);
+      if (this.unchanged(key)) return;
+      this.busy = true;
+      this.apply(generation, locals, key, this.hooks).catch(() => { this.pause(); });
+    } catch {
+      this.status.problem = 'The managed skills files are unreadable. The loaded skills are kept.';
+      try { this.save(); } catch { this.pause(); }
+    }
+  }
+
+  private unchanged(key: string): boolean {
+    if (key !== this.key && key !== this.failed) return false;
+    if (Date.now() - this.prunedAt > 60_000) {
+      const active = currentSkills(this.root)?.split('/')[2] ?? '';
+      try { pruneSkills(this.root, new Set([active])); } catch { log.warn('sdk-runner: old managed skills could not be removed'); }
+      this.prunedAt = Date.now();
+    }
+    return true;
+  }
+
+  private save(): void { writeSecure(join(this.root, 'status.json'), JSON.stringify(this.status)); }
+
+  private pause(): void {
+    this.busy = true;
+    this.status.problem = 'Skill reload could not finish safely. Input is paused. Check the files, then stop and start the Agent SDK.';
+    try { this.save(); } catch { log.error('sdk-runner: skills state could not be saved; input remains paused'); }
+  }
+
+  private async recover(before: string | null, previous: SkillActivation, hooks: SkillHooks, err: unknown): Promise<void> {
+    switchSkills(this.root, before);
+    if (err instanceof ReloadTimeout) { this.pause(); return; }
+    try {
+      await reload(hooks, this.timeout);
+      if (this.closed) return;
+      this.status = { ...previous, loading: null, problem: 'Skill reload failed. The previous skills were restored. Sync again, or remove the source again to retry unloading.' };
+      this.save();
+      this.busy = false;
+    } catch { this.pause(); }
+  }
+
+  private async apply(generation: SkillGeneration, locals: string[], key: string, hooks: SkillHooks): Promise<void> {
+    const before = currentSkills(this.root);
+    const previous = { ...this.status };
+    this.status = { ...previous, loading: generation.id, rollback: before, problem: null };
+    this.save();
+    try {
+      const projection = projectSkills(this.root, generation, locals);
+      switchSkills(this.root, projection.target);
+      await reload(hooks, this.timeout);
+      if (this.closed) return;
+      this.key = key;
+      this.failed = null;
+      this.status = { generation: generation.id, loading: null, appliedAt: new Date().toISOString(), problem: null, shadowed: projection.shadowed };
+      this.save();
+      this.busy = false;
+      const keep = new Set([generation.id]);
+      if (before !== null && generation.source !== null) keep.add(before.split('/')[2] ?? '');
+      try { pruneSkills(this.root, keep); } catch { log.warn('sdk-runner: old managed skills could not be removed'); }
+    } catch (err) {
+      if (this.closed) return;
+      this.failed = key;
+      await this.recover(before, previous, hooks, err);
+    }
+    hooks.wake();
+  }
+}

package/runtime/sdk-runner/src/task-ledger.ts

@@ -0,0 +1,244 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { runnerTaskDescription } from '@metro-labs/core/runner-activity';
+import { activityName } from './activity-tasks.js';
+import type { Unanswered } from './inbox.js';
+import { pendingNotice, TASK_LIMIT, type SavedTask, type TaskReason } from './task-state.js';
+
+interface Tool { name: string; parent: string | null }
+const failed = (text: unknown): TaskReason => typeof text === 'string' && /\b429\b|rate.?limit/i.test(text.slice(0, 4_096)) ? 'rate_limit' : 'task_error';
+
+export class TaskLedger {
+  private readonly rows = new Map<string, SavedTask>();
+  private readonly tools = new Map<string, Tool>();
+  private readonly errors = new Map<string, TaskReason>();
+
+  constructor(tasks: SavedTask[], private readonly save: (tasks: SavedTask[], handled?: ReadonlySet<string>) => void) {
+    for (const task of tasks) this.rows.set(task.id, task);
+  }
+
+  snapshot(): SavedTask[] { return [...this.rows.values()]; }
+
+  interrupted(inputs: Unanswered[], now: number): void {
+    let changed = false;
+    for (const input of inputs) {
+      const id = `input:${input.uuid ?? input.at}`;
+      if (!this.rows.has(id) && !this.room()) break;
+      const task = this.get(id, now);
+      if (task.notice !== null) continue;
+      task.state = 'interrupted';
+      task.owner = 'main';
+      task.notice = pendingNotice('interrupted', task.attempt, now);
+      changed = true;
+    }
+    if (changed) this.save(this.snapshot());
+  }
+
+  observe(m: Record<string, unknown>, now: number): void {
+    if (m.type === 'assistant' || m.type === 'user') this.content(m, now);
+    else if (m.type === 'result') this.result(m, now);
+    else if (m.type === 'system') this.system(m, now);
+  }
+
+  private result(m: Record<string, unknown>, now: number): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    if (m.is_error === true) this.turnFailed(m, now);
+    this.errors.delete('main');
+  }
+
+  private system(m: Record<string, unknown>, now: number): void {
+    if (m.subtype === 'background_tasks_changed') { this.background(m, now); return; }
+    const id = activityName(m.task_id);
+    if (id === null) return;
+    if (m.ambient === true || m.skip_transcript === true) { this.hide(id); return; }
+    const event = activityName(m.uuid);
+    const known = this.rows.get(id);
+    if (event !== null && known?.events.includes(event)) return;
+    this.taskEvent(id, m, event, now);
+  }
+
+  cancel(): SavedTask[] {
+    for (const task of this.rows.values()) {
+      if (task.state === 'running') task.state = 'stopped';
+      task.handledAttempt = task.attempt;
+      task.notice = null;
+    }
+    return this.snapshot();
+  }
+
+  changed(handled?: ReadonlySet<string>): void { this.save(this.snapshot(), handled); }
+
+  private taskEvent(id: string, m: Record<string, unknown>, event: string | null, now: number): void {
+    const known = this.rows.get(id);
+    if (m.subtype === 'task_started') this.start(id, m.tool_use_id, event, now, m.description);
+    else if (m.subtype === 'task_notification') this.end(id, m, event, now);
+    else if (m.subtype === 'task_updated' && isRecord(m.patch) && known !== undefined) {
+      if (this.describe(known, m.patch.description)) this.save(this.snapshot());
+      this.end(id, { status: m.patch.status === 'killed' ? 'stopped' : m.patch.status, summary: m.patch.error }, event, now);
+    } else if (m.subtype === 'task_progress') this.progress(id, m.tool_use_id, now);
+  }
+
+  private progress(id: string, rawTool: unknown, now: number): void {
+    const task = this.rows.get(id);
+    if (task?.state !== 'running') return;
+    const tool = activityName(rawTool) ?? task.toolUseId;
+    if (tool === task.toolUseId && now - task.updatedAt < 10_000) return;
+    task.toolUseId = tool;
+    task.updatedAt = now;
+    this.resolveOwners();
+    this.save(this.snapshot());
+  }
+
+  private turnFailed(m: Record<string, unknown>, now: number): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    const id = activityName(m.uuid);
+    if (id === null) return;
+    const task = this.get(`turn:${id}`, now);
+    task.owner = 'main';
+    task.state = 'failed';
+    const reason = m.api_error_status === 429 ? 'rate_limit' : this.errors.get('main') ?? 'provider_error';
+    if (task.handledAttempt !== task.attempt) task.notice ??= pendingNotice(reason, task.attempt, now);
+    this.save(this.snapshot());
+  }
+
+  private room(): boolean {
+    if (this.rows.size < TASK_LIMIT) return true;
+    const old = this.snapshot().find((task) => task.notice === null && task.state !== 'running');
+    if (old === undefined) return false;
+    this.rows.delete(old.id);
+    return true;
+  }
+
+  private get(id: string, now: number): SavedTask {
+    const known = this.rows.get(id);
+    if (known !== undefined) return known;
+    if (!this.room()) throw new Error('The saved Agent SDK task ledger is full. Handle pending recovery notices before starting more work.');
+    const task: SavedTask = { id, toolUseId: null, owner: null, attempt: 0, state: 'interrupted', events: [], updatedAt: now, notice: null };
+    this.rows.set(id, task);
+    return task;
+  }
+
+  private start(id: string, rawTool: unknown, event: string | null, now: number, description?: unknown): void {
+    const task = this.get(id, now);
+    if (task.state !== 'running') task.attempt += 1;
+    task.state = 'running';
+    this.describe(task, description);
+    if (event !== null) task.events = [...task.events, event].slice(-16);
+    task.updatedAt = now;
+    task.toolUseId = activityName(rawTool) ?? task.toolUseId;
+    this.resolveOwners();
+    this.save(this.snapshot());
+  }
+
+  private resolveOwners(): void {
+    for (const task of this.rows.values()) {
+      if (task.owner !== null) continue;
+      const tool = task.toolUseId === null ? undefined : this.tools.get(task.toolUseId);
+      if (tool !== undefined) task.parentToolUseId = tool.parent;
+      const parent = task.parentToolUseId;
+      if (parent === null) task.owner = 'main';
+      else if (parent !== undefined) task.owner = this.snapshot().find((owner) => owner.toolUseId === parent)?.id ?? null;
+    }
+  }
+
+  private end(id: string, m: Record<string, unknown>, event: string | null, now: number): void {
+    if (m.status !== 'completed' && m.status !== 'failed' && m.status !== 'stopped') return;
+    const task = this.get(id, now);
+    task.toolUseId = activityName(m.tool_use_id) ?? task.toolUseId;
+    task.state = m.reason === 'worker_restart' ? 'interrupted' : m.status;
+    if (event !== null) task.events = [...task.events, event].slice(-16);
+    task.updatedAt = now;
+    if (task.handledAttempt !== task.attempt) this.failedTask(task, m, now);
+    this.errors.delete(task.toolUseId ?? '');
+    this.resolveOwners();
+    this.save(this.snapshot());
+  }
+
+  private failedTask(task: SavedTask, m: Record<string, unknown>, now: number): void {
+    if (m.status !== 'failed' && m.reason !== 'worker_restart') return;
+    const reason = m.reason === 'worker_restart' ? 'worker_restart' : this.errors.get(task.toolUseId ?? '') ?? failed(m.summary);
+    if (task.notice?.attempt !== task.attempt) task.notice = pendingNotice(reason, task.attempt, now);
+    else if (reason === 'rate_limit' && task.notice.reason !== reason) {
+      task.notice.reason = reason;
+      task.notice.nextAt = Math.max(task.notice.nextAt, now + 30_000);
+    }
+  }
+
+  private hide(id: string): void {
+    if (this.rows.delete(id)) this.save(this.snapshot());
+  }
+
+  private background(m: Record<string, unknown>, now: number): void {
+    if (!Array.isArray(m.tasks)) return;
+    let described = false;
+    for (const row of m.tasks) {
+      if (!isRecord(row)) continue;
+      const id = activityName(row.task_id);
+      if (id === null) continue;
+      const known = this.rows.get(id);
+      if (row.ambient === true) this.hide(id);
+      else if (known === undefined) this.start(id, undefined, activityName(m.uuid), now, row.description);
+      else described = this.describe(known, row.description) || described;
+    }
+    if (described) this.save(this.snapshot());
+  }
+
+  private describe(task: SavedTask, raw: unknown): boolean {
+    const description = runnerTaskDescription(raw);
+    if (description === null || description === task.description) return false;
+    task.description = description;
+    return true;
+  }
+
+  private content(m: Record<string, unknown>, now: number): void {
+    const parent = activityName(m.parent_tool_use_id);
+    this.rememberError(m, parent);
+    if (!isRecord(m.message) || !Array.isArray(m.message.content)) return;
+    for (const block of m.message.content.filter(isRecord)) {
+      if (block.type === 'tool_use' && m.type === 'assistant') this.tool(block, parent);
+      else if (block.type === 'tool_result' && m.type === 'user') this.receipt(block, m.tool_use_result, now);
+    }
+  }
+
+  private rememberError(m: Record<string, unknown>, parent: string | null): void {
+    if (m.type === 'assistant' && typeof m.error === 'string') this.errors.set(parent ?? 'main', m.error === 'rate_limit' ? 'rate_limit' : 'provider_error');
+  }
+
+  private tool(block: Record<string, unknown>, parent: string | null): void {
+    const id = activityName(block.id);
+    const name = activityName(block.name);
+    if (id === null || name === null) return;
+    this.tools.set(id, { name, parent });
+    if (this.snapshot().some((task) => task.owner === null)) {
+      this.resolveOwners();
+      this.save(this.snapshot());
+    }
+    if (this.tools.size <= 400) return;
+    const oldest = this.tools.keys().next().value;
+    if (oldest !== undefined) this.tools.delete(oldest);
+  }
+
+  private receipt(block: Record<string, unknown>, structured: unknown, now: number): void {
+    const tool = typeof block.tool_use_id === 'string' ? this.tools.get(block.tool_use_id) : undefined;
+    if (tool?.name !== 'SendMessage' || block.is_error === true) return;
+    const raw = isRecord(structured) ? structured : this.renderedReceipt(block.content);
+    if (!isRecord(raw) || raw.success !== true) return;
+    const id = activityName(raw.resumedAgentId);
+    if (id !== null) this.resumed(id, activityName(block.tool_use_id), now);
+  }
+
+  private resumed(id: string, event: string | null, now: number): void {
+    const task = this.rows.get(id);
+    if (event !== null && task?.events.includes(event)) return;
+    if (task?.state === 'running') {
+      if (event !== null) { task.events = [...task.events, event].slice(-16); this.save(this.snapshot()); }
+      return;
+    }
+    this.start(id, undefined, event, now);
+  }
+
+  private renderedReceipt(content: unknown): unknown {
+    const text = typeof content === 'string' ? content : Array.isArray(content) ? content.filter(isRecord).filter((block) => block.type === 'text').map((block) => block.text).join('') : '';
+    if (text.length > 4_096) return null;
+    try { return JSON.parse(text); } catch { return null; }
+  }
+}