@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/sdk-runner/src/session-watch.ts

@@ -0,0 +1,158 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+const METRO_TOOL = /^mcp__metro__(.+)$/;
+
+export const uuidsOf = (m: Record<string, unknown>): string[] | null => {
+  if (Array.isArray(m.user_message_uuids)) return m.user_message_uuids.filter((u): u is string => typeof u === 'string');
+  return typeof m.user_message_uuid === 'string' ? [m.user_message_uuid] : null;
+};
+
+export const startedCommand = (m: Record<string, unknown>): string | null =>
+  m.type === 'command_lifecycle' && m.state === 'started' && typeof m.command_uuid === 'string' ? m.command_uuid : null;
+
+export const completedCommand = (m: Record<string, unknown>): string | null =>
+  m.type === 'command_lifecycle' && m.state === 'completed' && typeof m.command_uuid === 'string' ? m.command_uuid : null;
+
+const num = (value: unknown): number => (typeof value === 'number' ? value : 0);
+
+function contextOf(usage: unknown): number {
+  if (!isRecord(usage)) return 0;
+  return num(usage.input_tokens) + num(usage.cache_read_input_tokens) + num(usage.cache_creation_input_tokens);
+}
+
+function toolResultIds(message: unknown): string[] {
+  if (!isRecord(message) || !Array.isArray(message.content)) return [];
+  return message.content.filter(isRecord).filter((b) => b.type === 'tool_result' && typeof b.tool_use_id === 'string').map((b) => String(b.tool_use_id));
+}
+
+export class SessionWatch {
+  private readonly writes = new Set<string>();
+  private readonly idle: (() => void)[] = [];
+  private readonly compacted: (() => void)[] = [];
+  private compactingNow = false;
+  private busy = false;
+  private sessionStateSeen = false;
+  private requiresAction = false;
+  private awaitingInput: string | null = null;
+  private lastContext = 0;
+  private streamUsage: Record<string, unknown> = {};
+
+  constructor(private readonly readOnly: (tool: string) => boolean) {}
+
+  get compacting(): boolean {
+    return this.compactingNow;
+  }
+
+  get context(): number {
+    return this.lastContext;
+  }
+
+  get writing(): boolean {
+    return this.writes.size > 0;
+  }
+
+  get safe(): boolean { return !this.busy && !this.writing && !this.compacting; }
+
+  get admitting(): boolean {
+    return this.awaitingInput === null && !this.requiresAction && !this.compacting;
+  }
+
+  dispatched(uuid?: string): void {
+    this.busy = true;
+    this.awaitingInput = uuid ?? null;
+  }
+
+  restoreContext(context: number): void { this.lastContext = context; }
+
+  observe(m: Record<string, unknown>): void {
+    if (m.parent_tool_use_id !== null && m.parent_tool_use_id !== undefined) return;
+    this.acknowledge(m);
+    this.lifecycle(m);
+    if (m.type === 'assistant' && isRecord(m.message)) this.assistant(m.message);
+    else if (m.type === 'stream_event' && isRecord(m.event)) this.stream(m.event);
+    else if (m.type === 'user') for (const id of toolResultIds(m.message)) this.done(id);
+  }
+
+  whenNotWriting(): Promise<void> {
+    return this.writing ? new Promise((resolve) => { this.idle.push(resolve); }) : Promise.resolve();
+  }
+
+  whenNotCompacting(): Promise<void> {
+    return this.compactingNow ? new Promise((resolve) => { this.compacted.push(resolve); }) : Promise.resolve();
+  }
+
+  private acknowledge(m: Record<string, unknown>): void {
+    if (this.awaitingInput === null) return;
+    const completed = completedCommand(m) === this.awaitingInput;
+    if (completed || startedCommand(m) === this.awaitingInput || uuidsOf(m)?.includes(this.awaitingInput)) this.awaitingInput = null;
+  }
+
+  private lifecycle(m: Record<string, unknown>): void {
+    if (m.type === 'system') this.system(m);
+    else if (m.type === 'result' && !this.sessionStateSeen) {
+      this.busy = typeof m.queued_turn_count === 'number' && m.queued_turn_count > 0;
+      this.settle();
+    }
+    if (m.type === 'assistant' || m.type === 'stream_event' || startedCommand(m) !== null) this.busy = true;
+  }
+
+  private system(m: Record<string, unknown>): void {
+    if (m.subtype === 'session_state_changed') this.sessionState(m.state);
+    else if (m.subtype === 'status') this.setCompacting(m.status === 'compacting');
+    else if (m.subtype === 'compact_boundary') {
+      this.setCompacting(false);
+      this.lastContext = 0;
+      this.streamUsage = {};
+    }
+  }
+
+  private sessionState(state: unknown): void {
+    this.sessionStateSeen = true;
+    if (state === 'running' || state === 'requires_action') {
+      this.busy = true;
+      this.requiresAction = state === 'requires_action';
+    } else if (state === 'idle') {
+      this.busy = false;
+      this.requiresAction = false;
+      this.settle();
+    }
+  }
+
+  private stream(event: Record<string, unknown>): void {
+    if (event.type === 'message_start' && isRecord(event.message)) {
+      this.streamUsage = isRecord(event.message.usage) ? event.message.usage : {};
+    } else if (event.type === 'message_delta' && isRecord(event.usage)) {
+      this.streamUsage = { ...this.streamUsage, ...event.usage };
+    } else return;
+    this.lastContext = contextOf(this.streamUsage) || this.lastContext;
+  }
+
+  private setCompacting(on: boolean): void {
+    this.compactingNow = on;
+    if (!on) for (const resume of this.compacted.splice(0)) resume();
+  }
+
+  private assistant(message: Record<string, unknown>): void {
+    this.lastContext = contextOf(message.usage) || this.lastContext;
+    if (!Array.isArray(message.content)) return;
+    for (const block of message.content.filter(isRecord)) {
+      if (block.type !== 'tool_use' || typeof block.id !== 'string' || typeof block.name !== 'string') continue;
+      const tool = METRO_TOOL.exec(block.name)?.[1];
+      if (tool !== undefined && !this.readOnly(tool)) this.writes.add(block.id);
+    }
+  }
+
+  private done(id: string): void {
+    if (this.writes.delete(id) && this.writes.size === 0) this.wake();
+  }
+
+  private settle(): void {
+    if (this.writes.size === 0) return;
+    this.writes.clear();
+    this.wake();
+  }
+
+  private wake(): void {
+    for (const resume of this.idle.splice(0)) resume();
+  }
+}

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

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:net';
+
+export async function claimRunner(home: string): Promise<() => Promise<void>> {
+  const hash = createHash('sha256').update(home).digest('hex');
+  const server = createServer((socket) => { socket.destroy(); });
+  const address = process.platform === 'linux' ? { path: `\0metro-sdk-${hash}` } : { host: '127.0.0.1', port: 30_000 + parseInt(hash.slice(0, 4), 16) % 30_000 };
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', () => { reject(new Error('The Agent SDK runner is already running, or its local process lock is unavailable.')); });
+    server.listen(address, resolve);
+  });
+  return () => new Promise<void>((resolve, reject) => {
+    server.close((err) => { if (err === undefined) resolve(); else reject(err); });
+  });
+}

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();
+  }
+}