@dotdrelle/wiki-manager 0.15.66 → 0.15.70

package/src/orchestrator/providers/fakeRuntimeProvider.test.js

@@ -0,0 +1,201 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createFakeRuntimeProvider } from './fakeRuntimeProvider.js';
+import {
+  RUNTIME_PROTOCOL_VERSION,
+  RuntimeProviderUnavailableError,
+  assertRuntimeDescription,
+  assertRuntimeProvider,
+} from './runtimeProvider.js';
+
+function echoProvider(options) {
+  const provider = createFakeRuntimeProvider(options);
+  assertRuntimeProvider(provider);
+  return provider;
+}
+
+async function waitForStatus(provider, runId, predicate, { timeoutMs = 1000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const status = await provider.status(runId);
+    if (predicate(status.status)) return status;
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 2));
+  }
+  throw new Error(`run ${runId} did not reach the expected status in time`);
+}
+
+test('discovery exposes the declared capabilities (Test 1)', async () => {
+  const provider = echoProvider({ capabilities: [{ name: 'agent.echo', operations: ['run'] }] });
+
+  const description = assertRuntimeDescription(await provider.describe());
+  assert.equal(description.runtime, 'fake');
+  assert.equal(description.protocolVersion, RUNTIME_PROTOCOL_VERSION);
+  assert.equal(description.health, 'available');
+
+  assert.deepEqual(
+    await provider.discoverCapabilities(),
+    [{ name: 'agent.echo', operations: ['run'] }],
+  );
+});
+
+test('execute returns a runId and reaches completed (Test 2)', async () => {
+  const provider = echoProvider();
+
+  const run = await provider.execute({ objective: 'echo' });
+  assert.equal(run.status, 'running');
+  assert.ok(run.runId);
+
+  const status = await waitForStatus(provider, run.runId, (value) => value === 'completed');
+  assert.equal(status.status, 'completed');
+});
+
+test('subscribe replays and streams the run events (Test 3)', async () => {
+  const provider = echoProvider();
+
+  const run = await provider.execute({ objective: 'echo' });
+  const events = [];
+  const unsubscribe = provider.subscribe(run.runId, (event) => events.push(event));
+
+  await waitForStatus(provider, run.runId, (value) => value === 'completed');
+
+  const types = events.map((event) => event.type);
+  assert.ok(types.includes('run_started'), 'replayed run_started');
+  assert.ok(types.includes('tool_finished'), 'replayed tool_finished');
+  assert.ok(types.includes('run_completed'), 'streamed run_completed');
+  unsubscribe();
+});
+
+test('cancel stops the run and emits run_cancelled (Test 4)', async () => {
+  const provider = echoProvider({ autoCompleteMs: 50 });
+
+  const run = await provider.execute({ objective: 'echo' });
+  const events = [];
+  provider.subscribe(run.runId, (event) => events.push(event));
+
+  await provider.cancel(run.runId);
+  const status = await provider.status(run.runId);
+  assert.equal(status.status, 'cancelled');
+  assert.ok(events.some((event) => event.type === 'run_cancelled'));
+});
+
+test('a down provider reports unavailable and rejects execution (Test 5)', async () => {
+  const provider = echoProvider({ available: false });
+
+  const description = await provider.describe();
+  assert.equal(description.health, 'unavailable');
+
+  await assert.rejects(() => provider.discoverCapabilities(), RuntimeProviderUnavailableError);
+  await assert.rejects(() => provider.execute({ objective: 'echo' }), RuntimeProviderUnavailableError);
+});
+
+test('concurrent runs are independent (Test 6)', async () => {
+  const provider = echoProvider();
+
+  const [a, b, c] = await Promise.all([
+    provider.execute({ objective: 'A' }),
+    provider.execute({ objective: 'B' }),
+    provider.execute({ objective: 'C' }),
+  ]);
+
+  const runIds = [a.runId, b.runId, c.runId];
+  assert.equal(new Set(runIds).size, 3, 'three distinct run ids');
+
+  const statuses = await Promise.all(
+    runIds.map((runId) => waitForStatus(provider, runId, (value) => value === 'completed')),
+  );
+  assert.deepEqual(
+    statuses.map((status) => status.status),
+    ['completed', 'completed', 'completed'],
+  );
+});
+
+test('a provider with requireApproval waits for approve() before completing (Test 7)', async () => {
+  const provider = echoProvider({ requireApproval: true });
+
+  const run = await provider.execute({ objective: 'echo' });
+  assert.equal(run.status, 'waiting_approval');
+
+  const events = [];
+  provider.subscribe(run.runId, (event) => events.push(event));
+  assert.ok(events.some((event) => event.type === 'approval_required'), 'the proposal was emitted');
+  assert.ok(!events.some((event) => event.type === 'run_completed'), 'nothing completes before approval');
+
+  await provider.approve(run.runId, { approved: true, scope: ['echo'] });
+  const status = await waitForStatus(provider, run.runId, (value) => value === 'completed');
+  assert.equal(status.status, 'completed');
+  assert.ok(events.some((event) => event.type === 'run_completed'));
+});
+
+test('denying the HITL approval cancels the run', async () => {
+  const provider = echoProvider({ requireApproval: true });
+
+  const run = await provider.execute({ objective: 'echo' });
+  await provider.approve(run.runId, { approved: false, reason: 'refused' });
+
+  const status = await provider.status(run.runId);
+  assert.equal(status.status, 'cancelled');
+});
+
+test('per-capability HITL: a mutating capability waits for approve(), a read-only one does not', async () => {
+  const provider = echoProvider({
+    capabilities: [
+      { name: 'agent.review', operations: ['run'] },
+      { name: 'agent.research', operations: ['run'], mutationClass: 'ingest' },
+    ],
+  });
+
+  const readRun = await provider.execute({ capability: 'agent.review', objective: 'audit' });
+  const readStatus = await waitForStatus(provider, readRun.runId, (value) => value === 'completed');
+  assert.equal(readStatus.status, 'completed');
+
+  const mutatingRun = await provider.execute({ capability: 'agent.research', objective: 'research' });
+  assert.equal(mutatingRun.status, 'waiting_approval');
+  const events = [];
+  provider.subscribe(mutatingRun.runId, (event) => events.push(event));
+  const approval = events.find((event) => event.type === 'approval_required');
+  assert.equal(approval.proposal.mutations[0].kind, 'ingest', 'the announced class matches the declared mutationClass');
+
+  await provider.approve(mutatingRun.runId, { approved: true, scope: ['ingest'] });
+  const final = await waitForStatus(provider, mutatingRun.runId, (value) => value === 'completed');
+  assert.equal(final.status, 'completed');
+});
+
+test("the 'plan' operation is a dry-run and never pauses, even on a mutating capability", async () => {
+  const provider = echoProvider({
+    capabilities: [{ name: 'agent.plan', operations: ['plan', 'run'], defaultRequiresApproval: true }],
+  });
+
+  const dryRun = await provider.execute({ capability: 'agent.plan', operation: 'plan', objective: 'propose' });
+  const dryStatus = await waitForStatus(provider, dryRun.runId, (value) => value === 'completed');
+  assert.equal(dryStatus.status, 'completed', 'plan completes without approval');
+
+  const liveRun = await provider.execute({ capability: 'agent.plan', operation: 'run', objective: 'propose' });
+  assert.equal(liveRun.status, 'waiting_approval', 'run pauses for approval');
+  await provider.approve(liveRun.runId, { approved: true });
+  const final = await waitForStatus(provider, liveRun.runId, (value) => value === 'completed');
+  assert.equal(final.status, 'completed');
+});
+
+test('fake provider carries a proposal in the structured result, like the gateway', async () => {
+  const proposal = {
+    capability: 'knowledge.update',
+    operation: 'ingest',
+    objective: 'ingest the pending raw sources',
+    reason: 'deterministic E2E',
+  };
+  const provider = createFakeRuntimeProvider({
+    capabilities: [{ name: 'agent.proposal-test', operations: ['run'] }],
+    proposal,
+  });
+  const run = await provider.execute({ capability: 'agent.proposal-test', operation: 'run', objective: 'propose' });
+  const status = await waitForStatus(provider, run.runId, (value) => value === 'completed');
+  assert.deepEqual(status.result.planExpansionRequest, proposal);
+});
+
+test('fake provider without a proposal keeps a plain result', async () => {
+  const provider = createFakeRuntimeProvider({ capabilities: [{ name: 'agent.echo', operations: ['run'] }] });
+  const run = await provider.execute({ capability: 'agent.echo', operation: 'run', objective: 'echo' });
+  const status = await waitForStatus(provider, run.runId, (value) => value === 'completed');
+  assert.equal(status.result.planExpansionRequest, undefined);
+  assert.equal(typeof status.result.content, 'string');
+});

package/src/orchestrator/providers/runtimeProvider.js

@@ -0,0 +1,101 @@
+import { assertContract } from '../../contracts/schemas.js';
+
+/**
+ * External Agent Runtime Provider — contrat.
+ *
+ * Le point d'abstraction qui laisse Wiki Manager router une tâche agentique
+ * vers un moteur externe (Deep Agents, autre) SANS le transformer en couche
+ * d'orchestration. Le contrat est volontairement plus petit que le moteur
+ * interne : il ne reproduit ni Control Queue, ni scheduler, ni DAG, ni
+ * politique d'approbation complète, ni objective resolver — ces responsabilités
+ * restent dans Wiki Manager (voir RFC § 8).
+ *
+ * Un provider implémente :
+ *
+ *   describe(): Promise<RuntimeDescription>
+ *       { runtime, version, protocolVersion, health, capabilities? }
+ *
+ *   discoverCapabilities(): Promise<Capability[]>
+ *       [{ name: 'agent.review', operations: ['run'] }, ...]
+ *
+ *   execute(request: RuntimeExecuteRequest): Promise<RuntimeRun>
+ *       { runId, status: 'running' } — ne bloque pas.
+ *
+ *   status(runId: string): Promise<RuntimeStatus>
+ *       { runId, status } — status parmi les états terminaux du moteur.
+ *
+ *   cancel(runId: string): Promise<void>
+ *
+ *   subscribe(runId: string, listener: RuntimeEventListener): Unsubscribe
+ *       le listener reçoit des RuntimeEvent ; `Unsubscribe` est une fonction.
+ *
+ *   approve(runId: string, { approved, scope?, reason? }): Promise<void>
+ *       Réponse au human-in-the-loop du runtime. CE N'EST PAS un mécanisme
+ *       d'approbation : son seul appelant est le dispatcher, et uniquement
+ *       après qu'un grant humain couvre la demande (`approvalCovered`).
+ *       Jamais exposé en tool ni en endpoint — le projet a déjà retiré un
+ *       self-approval tool, ce serait le réintroduire.
+ *
+ * Le mot « provider » est ici distinct des `providers` du `CapabilityRegistry`
+ * (qui sont des instances d'agents MCP). Un RuntimeProvider n'est PAS un agent
+ * MCP : c'est un backend d'exécution externe découvert séparément.
+ */
+
+export const RUNTIME_PROTOCOL_VERSION = '1';
+
+export const RUNTIME_EVENT_TYPES = [
+  'run_created',
+  'run_started',
+  'agent_thinking',
+  'tool_started',
+  'tool_finished',
+  'subagent_started',
+  'subagent_finished',
+  'message',
+  'approval_required',
+  'run_completed',
+  'run_failed',
+  'run_cancelled',
+];
+
+export class RuntimeProviderUnavailableError extends Error {
+  constructor(runtime, reason) {
+    super(`Runtime provider unavailable: ${runtime} (${reason})`);
+    this.name = 'RuntimeProviderUnavailableError';
+    this.runtime = String(runtime ?? 'unknown');
+    this.reason = String(reason ?? 'unknown');
+  }
+}
+
+const CONTRACT_METHODS = [
+  'describe',
+  'discoverCapabilities',
+  'execute',
+  'status',
+  'cancel',
+  'subscribe',
+  'approve',
+];
+
+export function assertRuntimeProvider(provider) {
+  if (!provider || typeof provider !== 'object') {
+    throw new RuntimeProviderUnavailableError('unknown', 'provider is not an object');
+  }
+  for (const method of CONTRACT_METHODS) {
+    if (typeof provider[method] !== 'function') {
+      throw new RuntimeProviderUnavailableError(
+        provider.runtime ?? 'unknown',
+        `missing method "${method}"`,
+      );
+    }
+  }
+  return provider;
+}
+
+export function assertRuntimeDescription(description) {
+  return assertContract('runtimeDescription', description);
+}
+
+export function normalizeRuntimeEvent(event) {
+  return assertContract('runtimeEvent', event);
+}

package/src/orchestrator/providers/runtimeProviders.js

@@ -0,0 +1,325 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { dispatchRuntimeLog } from '../../core/agentEvents.js';
+import { managerStateDir } from '../../core/env.js';
+import { createDeepAgentsProvider } from './deepAgentsProvider.js';
+import { createFakeRuntimeProvider } from './fakeRuntimeProvider.js';
+import { assertRuntimeProvider } from './runtimeProvider.js';
+
+/**
+ * Découverte des runtimes agentiques externes et projection en « agents »
+ * synthétiques, afin que leurs capabilities entrent dans le même
+ * `CapabilityRegistry` que les agents MCP (RFC § 10, niveau B).
+ *
+ * Un runtime down ne produit AUCUN agent : ses capabilities sont simplement
+ * absentes du registry, et la résolution échoue en `capability_not_found`
+ * sans jamais toucher aux capabilities MCP existantes (isolation de panne,
+ * RFC § 39). Le runtime défaillant est néanmoins signalé via la liste
+ * `unavailable` retournée — une dégradation doit s'annoncer.
+ */
+
+export async function discoverRuntimeProviderAgents(runtimeProviders) {
+  const providers = Array.isArray(runtimeProviders)
+    ? runtimeProviders
+    : (runtimeProviders?.list?.() ?? []);
+  const agents = [];
+  const unavailable = [];
+
+  for (const entry of providers) {
+    const provider = entry?.provider ?? entry;
+    const runtimeId = String(entry?.id ?? provider?.runtime ?? 'external-runtime');
+    let description;
+    try {
+      assertRuntimeProvider(provider);
+      description = await provider.describe();
+    } catch (error) {
+      unavailable.push({ runtimeId, error: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    if (description?.health === 'unavailable') {
+      unavailable.push({ runtimeId, error: description?.error ?? 'runtime reports unavailable' });
+      continue;
+    }
+    let capabilities;
+    try {
+      capabilities = await provider.discoverCapabilities();
+    } catch (error) {
+      unavailable.push({ runtimeId, error: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    const health = ['available', 'degraded'].includes(description?.health)
+      ? description.health
+      : 'available';
+    for (const capability of capabilities ?? []) {
+      agents.push(runtimeProviderAgent(runtimeId, provider, description, capability, health));
+    }
+  }
+
+  return { agents, unavailable };
+}
+
+/**
+ * Configuration `agentRuntimes` (RFC § 37), fichier `agent-runtimes.json` dans
+ * le répertoire d'état du manager. Deux formes tolérées : un tableau nu, ou un
+ * objet `{ "runtimes": [...] }`. Absent ou illisible ⇒ aucune runtime déclarée.
+ *
+ * Entrée : `{ id, type, endpoint?, enabled?, capabilities?, limits? }`.
+ */
+export function loadAgentRuntimesConfig({ stateDir = managerStateDir(), log = () => {}, env = process.env } = {}) {
+  const file = join(stateDir, 'agent-runtimes.json');
+  let entries = [];
+  if (existsSync(file)) {
+    try {
+      const raw = JSON.parse(readFileSync(file, 'utf8'));
+      entries = Array.isArray(raw)
+        ? raw
+        : (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.runtimes ?? [] : []);
+    } catch (error) {
+      log(`agent-runtimes.json unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return withImpliedGateway(entries, env, log);
+}
+
+// One switch: when the operator starts the gateway container
+// (GATEWAY_ENABLED=true in the manager .env), the manager implies the runtime
+// declaration itself — if it starts, it is usable. agent-runtimes.json stays
+// for the exceptional cases: a custom endpoint, pinned capabilities, or
+// another engine (fake). An explicit ENABLED deepagents entry wins over the
+// implied one; a disabled entry does not block it — but that override is a
+// case worth stating, not assuming: an operator who wrote `enabled: false`
+// deliberately would otherwise have no way to learn why deepagents ran anyway.
+function withImpliedGateway(entries, env = process.env, log = () => {}) {
+  if (!isTruthy(env.GATEWAY_ENABLED)) return entries;
+  const explicitEnabled = entries.some((entry) =>
+    entry?.type === 'deepagents' && entry?.enabled !== false);
+  if (explicitEnabled) return entries;
+  const disabledEntry = entries.find((entry) => entry?.type === 'deepagents' && entry?.enabled === false);
+  if (disabledEntry) {
+    log('agent-runtimes: GATEWAY_ENABLED=true implies a "deepagents" runtime despite an explicit enabled:false entry in agent-runtimes.json');
+  }
+  const port = String(env.GATEWAY_PORT ?? '7789');
+  const token = String(env.GATEWAY_AUTH_TOKEN ?? '').trim();
+  // The implied entry inherits the disabled entry's declared capability shape
+  // (approval classes, alias operations, descriptions): the scaffolded
+  // agent-runtimes.json ships the full list with enabled:false, and dropping it
+  // here would let a gateway /capabilities response that omits
+  // defaultRequiresApproval/mutationClass turn a mutating capability into a
+  // self-approving one. The endpoint stays host-local (the manager runtime runs
+  // on the host, not in the agents network) and the env token still wins.
+  const inheritedCapabilities = Array.isArray(disabledEntry?.capabilities) && disabledEntry.capabilities.length > 0
+    ? { capabilities: disabledEntry.capabilities }
+    : {};
+  const inheritedHeaders = disabledEntry?.headers && typeof disabledEntry.headers === 'object'
+    ? disabledEntry.headers
+    : {};
+  return [
+    ...entries.filter((entry) => entry !== disabledEntry),
+    {
+      ...(disabledEntry?.timeoutMs ? { timeoutMs: disabledEntry.timeoutMs } : {}),
+      ...inheritedCapabilities,
+      id: 'deepagents',
+      type: 'deepagents',
+      endpoint: `http://localhost:${port}`,
+      enabled: true,
+      ...(token
+        ? { headers: { ...inheritedHeaders, Authorization: `Bearer ${token}` } }
+        : (Object.keys(inheritedHeaders).length > 0 ? { headers: inheritedHeaders } : {})),
+    },
+  ];
+}
+
+function isTruthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
+}
+
+/**
+ * Usines de providers par `type`. `fake` sert les tests/plomberie ; `deepagents`
+ * parle HTTP à un runtime externe (Phase 5). Un type inconnu est ignoré et
+ * signalé — jamais une erreur fatale au démarrage.
+ */
+export const runtimeProviderFactories = {
+  fake: (entry = {}) => createFakeRuntimeProvider({
+    runtime: String(entry?.id ?? 'fake'),
+    capabilities: Array.isArray(entry?.capabilities) && entry.capabilities.length > 0
+      ? entry.capabilities
+      : undefined,
+    ...(entry?.available === false ? { available: false } : {}),
+    ...(entry?.proposal && typeof entry.proposal === 'object' ? { proposal: entry.proposal } : {}),
+  }),
+  deepagents: (entry = {}) => createDeepAgentsProvider({
+    id: String(entry?.id ?? 'deepagents'),
+    endpoint: String(entry?.endpoint ?? 'http://agent-runtime:7789'),
+    capabilities: Array.isArray(entry?.capabilities) && entry.capabilities.length > 0
+      ? entry.capabilities
+      : null,
+    ...(entry?.headers && typeof entry.headers === 'object' ? { headers: entry.headers } : {}),
+    ...(entry?.timeoutMs ? { timeoutMs: Number(entry.timeoutMs) } : {}),
+  }),
+};
+
+export function resolveRuntimeProviders(config = [], { factories = runtimeProviderFactories } = {}) {
+  const providers = [];
+  const skipped = [];
+  for (const entry of Array.isArray(config) ? config : []) {
+    if (!entry || typeof entry !== 'object') continue;
+    if (entry.enabled === false) continue;
+    const id = String(entry?.id ?? entry?.type ?? '');
+    const type = String(entry?.type ?? '');
+    const factory = factories?.[type];
+    if (typeof factory !== 'function') {
+      skipped.push({ id, reason: `unknown runtime type "${type}"` });
+      continue;
+    }
+    try {
+      const provider = factory(entry);
+      assertRuntimeProvider(provider);
+      providers.push({ id, type, provider });
+    } catch (error) {
+      skipped.push({ id, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { providers, skipped };
+}
+
+/**
+ * Hook de découverte : peuple `session.runtimeProviderAgents` à partir de la
+ * config, et signale les runtimes sautées/indisponibles dans le journal
+ * (une dégradation doit s'annoncer). Appelée au boot et à chaque re-scan,
+ * en vis-à-vis de `discoverAgentsOnce`.
+ */
+export async function discoverRuntimeProvidersOnce(session, {
+  signal = null,
+  config = null,
+} = {}) {
+  if (!session || typeof session !== 'object') return [];
+  void signal;
+  let impliedGatewayOverride = false;
+  const entries = config ?? loadAgentRuntimesConfig({
+    log: (message) => {
+      if (String(message).startsWith('agent-runtimes: GATEWAY_ENABLED=true implies')) impliedGatewayOverride = true;
+    },
+  });
+  const resolved = resolveRuntimeProviders(entries);
+  const { agents, unavailable } = await discoverRuntimeProviderAgents(resolved.providers);
+
+  // A failed probe is not a lost agent (same rule as agentRegistry): a runtime
+  // that reported unavailable this round but for which we hold a last-known-good
+  // capability set keeps that set until it recovers, instead of every `agent.*`
+  // capability vanishing from the registry on a transient network blip. Health
+  // is deliberately not downgraded — capabilityResolver only accepts
+  // available/degraded, so moving it to unavailable would trade a silent loss
+  // for a silent refusal. A runtime that answers is authoritative, even when it
+  // answers with zero capabilities (a real removal); a runtime no longer
+  // configured is forgotten.
+  session._runtimeProviderLastKnown ??= new Map();
+  const lastKnown = session._runtimeProviderLastKnown;
+  const configuredIds = new Set(resolved.providers.map((entry) => String(entry?.id ?? entry?.provider?.runtime ?? 'external-runtime')));
+  const unavailableIds = new Set(unavailable.map((item) => item.runtimeId));
+  const answeredIds = new Set(agents.map((agent) => agent.runtimeId));
+  for (const id of configuredIds) {
+    if (unavailableIds.has(id) && !answeredIds.has(id)) continue; // preserved below
+    const fresh = agents.filter((agent) => agent.runtimeId === id);
+    if (fresh.length > 0) lastKnown.set(id, fresh);
+    else lastKnown.delete(id);
+  }
+  for (const id of [...lastKnown.keys()]) {
+    if (!configuredIds.has(id)) lastKnown.delete(id);
+  }
+  const preservedByRuntime = new Map();
+  for (const item of unavailable) {
+    if (answeredIds.has(item.runtimeId)) continue;
+    const kept = lastKnown.get(item.runtimeId);
+    if (kept && kept.length > 0) preservedByRuntime.set(item.runtimeId, kept);
+  }
+  const effectiveAgents = [...agents];
+  for (const kept of preservedByRuntime.values()) effectiveAgents.push(...kept);
+  session.runtimeProviderAgents = effectiveAgents;
+  // A degradation is announced ONCE, on the transition to down/skipped — not
+  // on every periodic re-scan. The agent registry learned this the hard way: a
+  // stopped endpoint is a fact to state, not an error to repeat every minute.
+  // The set is edge-triggered and forgotten as soon as the runtime recovers,
+  // so a future outage is announced again.
+  if (impliedGatewayOverride && !session._gatewayOverrideAnnounced) {
+    dispatchRuntimeLog(session, 'agent-runtimes: GATEWAY_ENABLED=true implies a "deepagents" runtime despite an explicit enabled:false entry in agent-runtimes.json');
+  }
+  session._gatewayOverrideAnnounced = impliedGatewayOverride;
+  session._runtimeProviderDown ??= new Set();
+  const currentDown = new Set();
+  for (const item of resolved.skipped) {
+    const key = `skipped:${item.id || '(unnamed)'}`;
+    currentDown.add(key);
+    if (!session._runtimeProviderDown.has(key)) {
+      dispatchRuntimeLog(session, `agent-runtimes: ${item.id || '(unnamed)'} skipped (${item.reason})`);
+    }
+  }
+  for (const item of unavailable) {
+    const key = `unavailable:${item.runtimeId}`;
+    currentDown.add(key);
+    if (!session._runtimeProviderDown.has(key)) {
+      const kept = preservedByRuntime.get(item.runtimeId)?.length ?? 0;
+      dispatchRuntimeLog(session, kept > 0
+        ? `agent-runtimes: ${item.runtimeId} unavailable (${item.error}) — keeping ${kept} last-known capabilit${kept === 1 ? 'y' : 'ies'} until it recovers`
+        : `agent-runtimes: ${item.runtimeId} unavailable (${item.error})`);
+    }
+  }
+  session._runtimeProviderDown = currentDown;
+  return effectiveAgents;
+}
+
+function runtimeProviderAgent(runtimeId, provider, description, capability, health) {
+  const name = String(capability?.name ?? '');
+  const operations = Array.isArray(capability?.operations)
+    ? capability.operations.map(String).filter(Boolean)
+    : [];
+  const agentInstanceId = `${runtimeId}::${name}`;
+  return {
+    agentInstanceId,
+    serverName: null,
+    legacy: false,
+    orchestrable: true,
+    health,
+    providerKind: 'external-runtime',
+    runtimeId,
+    runtimeProvider: provider,
+    lastSeenAt: new Date().toISOString(),
+    description: {
+      contractVersion: '1',
+      agentType: 'external-runtime',
+      agentInstanceId,
+      displayName: `${runtimeId} (${name})`,
+      capabilities: [{
+        id: name,
+        version: '1',
+        description: String(capability?.description ?? `${runtimeId}/${name}`),
+        inputSchema: {},
+        outputSchema: {},
+        supportedOperations: operations.length > 0 ? operations : ['run'],
+        aliases: Array.isArray(capability?.aliases) ? capability.aliases.map(String).filter(Boolean) : [],
+        aliasOperations: capability?.aliasOperations && typeof capability.aliasOperations === 'object'
+          ? { ...capability.aliasOperations }
+          : null,
+        // Without these, an external-runtime capability can never be seen as
+        // mutating by isMutatingTask/buildExecutorOnlyFragment, so a task
+        // that should wait for a human grant starts unapproved by construction.
+        ...(typeof capability?.mutationClass === 'string' ? { mutationClass: capability.mutationClass } : {}),
+        ...(capability?.defaultRequiresApproval === true ? { defaultRequiresApproval: true } : {}),
+      }],
+      orchestration: {
+        canPlan: false,
+        canExpandPlan: false,
+        canExecute: true,
+        canCancel: true,
+        canResume: false,
+        supportsIdempotency: false,
+        supportsParallelWorkers: true,
+        singleTaskOnly: true,
+      },
+      limits: {
+        recommendedConcurrency: Number(description?.limits?.recommendedConcurrency ?? 4),
+        maxConcurrency: Number(description?.limits?.maxConcurrency ?? 8),
+      },
+      health: { status: health },
+    },
+  };
+}