feat(daemon,cli): RFC-003 Phase 5 — Integration (hot-reload + validate)

- Kernel: rebuild AgentRegistry on config hot-reload, log agent_registry_reload
- Running threads unaffected, new threads use rebuilt registry
- nerve validate: check agent name refs in WorkflowSpec source files
- nerve validate: verify adapter type is known (KNOWN_AGENT_ADAPTER_IDS)
- nerve validate: require extract config when WorkflowSpec agent refs exist
- Tests: kernel reload (mock), validate (missing/valid/extract/adapter)

Closes #239
Ref: #234

packages/cli/src/__tests__/validate-workflow-agents.test.ts

@@ -0,0 +1,146 @@
+/**
+ * RFC-003 Phase 5: nerve validate — WorkflowSpec agent refs and extract.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  collectWorkflowSpecAgentReferences,
+  validateAgentConfigurationLayer,
+} from "../workflow-agent-validation.js";
+
+function baseConfig(overrides: Partial<NerveConfig> = {}): NerveConfig {
+  return {
+    maxRounds: 10,
+    senses: {},
+    workflows: {},
+    api: { port: null, token: null, host: "127.0.0.1" },
+    agents: {},
+    extract: null,
+    ...overrides,
+  };
+}
+
+describe("validateAgentConfigurationLayer", () => {
+  let nerveRoot: string;
+
+  afterEach(() => {
+    rmSync(nerveRoot, { recursive: true, force: true });
+  });
+
+  it("fails when WorkflowSpec references an agent not in nerve.yaml", () => {
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-val-agents-"));
+    mkdirSync(join(nerveRoot, "workflows", "demo", "src"), { recursive: true });
+    writeFileSync(
+      join(nerveRoot, "workflows", "demo", "src", "index.ts"),
+      `
+import type { WorkflowSpec } from "@uncaged/nerve-core";
+const spec: WorkflowSpec<{ r: { x: number } }> = {
+  name: "demo",
+  roles: {
+    r: { agent: "missing-agent", prompt: "p", meta: {} as never, timeout: null },
+  },
+  moderator: () => "__end__" as never,
+};
+export default spec;
+`,
+      "utf8",
+    );
+
+    const result = validateAgentConfigurationLayer(baseConfig({ agents: {} }), nerveRoot);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.message).toContain("missing-agent");
+    }
+  });
+
+  it("passes when all WorkflowSpec agent refs exist and extract is configured", () => {
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-val-agents-"));
+    mkdirSync(join(nerveRoot, "workflows", "demo", "src"), { recursive: true });
+    writeFileSync(
+      join(nerveRoot, "workflows", "demo", "src", "index.ts"),
+      `
+roles: { x: { agent: "my-dev", prompt: "", meta: {} as never, timeout: null } }
+agent: "my-dev"
+`,
+      "utf8",
+    );
+
+    const result = validateAgentConfigurationLayer(
+      baseConfig({
+        agents: {
+          "my-dev": { type: "echo", model: "auto", timeout: null },
+        },
+        extract: { provider: "dashscope", model: "qwen-plus" },
+      }),
+      nerveRoot,
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  it("requires extract when any WorkflowSpec agent ref is found", () => {
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-val-agents-"));
+    mkdirSync(join(nerveRoot, "workflows", "demo", "src"), { recursive: true });
+    writeFileSync(
+      join(nerveRoot, "workflows", "demo", "src", "wf.ts"),
+      `const role = { agent: "my-dev", prompt: "x" };`,
+      "utf8",
+    );
+
+    const result = validateAgentConfigurationLayer(
+      baseConfig({
+        agents: {
+          "my-dev": { type: "echo", model: "auto", timeout: null },
+        },
+        extract: null,
+      }),
+      nerveRoot,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.message).toMatch(/extract/i);
+    }
+  });
+
+  it("rejects unknown agent adapter type in nerve.yaml", () => {
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-val-agents-"));
+    const result = validateAgentConfigurationLayer(
+      baseConfig({
+        agents: {
+          bad: { type: "future-adapter", model: "auto", timeout: null },
+        },
+      }),
+      nerveRoot,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.message).toContain("future-adapter");
+      expect(result.message).toContain("echo");
+    }
+  });
+});
+
+describe("collectWorkflowSpecAgentReferences", () => {
+  let nerveRoot: string;
+
+  afterEach(() => {
+    rmSync(nerveRoot, { recursive: true, force: true });
+  });
+
+  it("collects agent strings from workflows/*/src", () => {
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-collect-refs-"));
+    mkdirSync(join(nerveRoot, "workflows", "w1", "src", "nested"), { recursive: true });
+    writeFileSync(
+      join(nerveRoot, "workflows", "w1", "src", "nested", "a.ts"),
+      `agent: 'alpha'\nagent: "beta"`,
+      "utf8",
+    );
+
+    expect(collectWorkflowSpecAgentReferences(nerveRoot)).toEqual(["alpha", "beta"]);
+  });
+});

packages/cli/src/commands/validate.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { parseNerveConfig } from "@uncaged/nerve-core";
 import { defineCommand } from "citty";
 
+import { validateAgentConfigurationLayer } from "../workflow-agent-validation.js";
 import { getNerveRoot } from "../workspace.js";
 
 export const validateCommand = defineCommand({
@@ -12,7 +13,8 @@ export const validateCommand = defineCommand({
     description: "Validate nerve.yaml configuration",
   },
   async run() {
-    const configPath = join(getNerveRoot(), "nerve.yaml");
+    const nerveRoot = getNerveRoot();
+    const configPath = join(nerveRoot, "nerve.yaml");
     let raw: string;
     try {
       raw = readFileSync(configPath, "utf8");
@@ -29,6 +31,12 @@ export const validateCommand = defineCommand({
     }
 
     const config = result.value;
+    const agentLayer = validateAgentConfigurationLayer(config, nerveRoot);
+    if (!agentLayer.ok) {
+      process.stderr.write(`❌ Config validation failed: ${agentLayer.message}\n`);
+      process.exit(1);
+    }
+
     const senseCount = Object.keys(config.senses).length;
     const triggerScheduleCount = Object.values(config.senses).filter(
       (s) => s.interval !== null || s.on.length > 0,

packages/cli/src/workflow-agent-validation.ts

@@ -0,0 +1,96 @@
+/**
+ * RFC-003: cross-check WorkflowSpec `agent:` references in workflow sources against nerve.yaml.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+import { KNOWN_AGENT_ADAPTER_IDS } from "@uncaged/nerve-core";
+
+/** Matches RoleSpec `agent: "name"` / `agent: 'name'` in workflow TypeScript sources. */
+const WORKFLOW_SPEC_AGENT_PATTERN = /agent:\s*["']([^"']+)["']/g;
+
+function collectTsSourceFiles(dir: string, acc: string[]): void {
+  if (!existsSync(dir)) return;
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      collectTsSourceFiles(p, acc);
+    } else if (ent.isFile() && /\.(ts|mts|cts)$/.test(ent.name) && !ent.name.endsWith(".d.ts")) {
+      acc.push(p);
+    }
+  }
+}
+
+/**
+ * Collects distinct agent names referenced via `agent: "..."` in each workflow's `src` tree.
+ */
+export function collectWorkflowSpecAgentReferences(nerveRoot: string): string[] {
+  const workflowsRoot = join(nerveRoot, "workflows");
+  if (!existsSync(workflowsRoot)) {
+    return [];
+  }
+
+  const refs = new Set<string>();
+  for (const wfName of readdirSync(workflowsRoot)) {
+    const wfDir = join(workflowsRoot, wfName);
+    if (!statSync(wfDir).isDirectory()) continue;
+
+    const srcDir = join(wfDir, "src");
+    const files: string[] = [];
+    collectTsSourceFiles(srcDir, files);
+
+    for (const filePath of files) {
+      const content = readFileSync(filePath, "utf8");
+      for (const m of content.matchAll(WORKFLOW_SPEC_AGENT_PATTERN)) {
+        refs.add(m[1]);
+      }
+    }
+  }
+
+  return [...refs].sort((a, b) => a.localeCompare(b));
+}
+
+const knownAdapterSet = new Set<string>(KNOWN_AGENT_ADAPTER_IDS);
+
+export type AgentLayerValidationResult = { ok: true } | { ok: false; message: string };
+
+/**
+ * Validates agents.*.type against known adapters, WorkflowSpec agent refs vs `agents:`,
+ * and `extract:` when any WorkflowSpec role references an agent (typed meta uses extract).
+ */
+export function validateAgentConfigurationLayer(
+  config: NerveConfig,
+  nerveRoot: string,
+): AgentLayerValidationResult {
+  for (const [name, agent] of Object.entries(config.agents)) {
+    if (!knownAdapterSet.has(agent.type)) {
+      return {
+        ok: false,
+        message: `agents.${name}.type: unknown adapter "${agent.type}" (known: ${KNOWN_AGENT_ADAPTER_IDS.join(", ")})`,
+      };
+    }
+  }
+
+  const refs = collectWorkflowSpecAgentReferences(nerveRoot);
+
+  for (const ref of refs) {
+    if (config.agents[ref] === undefined) {
+      return {
+        ok: false,
+        message: `WorkflowSpec references unknown agent "${ref}" (not defined under agents: in nerve.yaml)`,
+      };
+    }
+  }
+
+  if (refs.length > 0 && config.extract === null) {
+    return {
+      ok: false,
+      message:
+        "extract: required when WorkflowSpec roles reference agents (configure extract.provider and extract.model)",
+    };
+  }
+
+  return { ok: true };
+}

packages/core/src/agent-adapter-ids.ts

@@ -0,0 +1,5 @@
+/**
+ * Agent adapter types that have a daemon implementation (RFC-003).
+ * Keep in sync with `packages/daemon` agent factory dispatch.
+ */
+export const KNOWN_AGENT_ADAPTER_IDS = ["echo"] as const;

packages/core/src/index.ts

@@ -36,6 +36,7 @@ export type { Result } from "./result.js";
 export { ok, err } from "./result.js";
 export { parseNerveConfig } from "./parse-nerve-config.js";
 export { isPlainRecord } from "./is-plain-record.js";
+export { KNOWN_AGENT_ADAPTER_IDS } from "./agent-adapter-ids.js";
 
 export type { RoutedSenseOutput } from "./sense-workflow-directive.js";
 export { parseWorkflowTrigger, routeSenseComputeOutput } from "./sense-workflow-directive.js";

packages/daemon/src/__tests__/kernel-agent-registry-reload.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Kernel AgentRegistry integration — rebuilt on reloadConfig (RFC-003 Phase 5).
+ */
+
+import { EventEmitter } from "node:events";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { NerveConfig } from "@uncaged/nerve-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockCreateAgentRegistry = vi.hoisted(() =>
+  vi.fn(() => ({
+    get: vi.fn(),
+    getAgentConfig: vi.fn(),
+  })),
+);
+
+const mockChildren: MockChild[] = [];
+
+type MockChild = EventEmitter & {
+  send: ReturnType<typeof vi.fn>;
+  kill: ReturnType<typeof vi.fn>;
+  pid: number;
+};
+
+function makeMockChild(pid = 1): MockChild {
+  const child = new EventEmitter() as MockChild;
+  setImmediate(() => {
+    child.emit("message", { type: "ready" });
+  });
+  child.send = vi.fn((msg: unknown) => {
+    if (msg === null || typeof msg !== "object") return;
+    const m = msg as Record<string, unknown>;
+    if (m.type === "shutdown") {
+      setImmediate(() => child.emit("exit", 0, null));
+    }
+  });
+  child.kill = vi.fn((_signal?: string) => {
+    child.emit("exit", null, _signal ?? "SIGKILL");
+  });
+  child.pid = pid;
+  return child;
+}
+
+vi.mock("node:child_process", () => ({
+  fork: vi.fn((_script: string, _args: string[], _opts: unknown) => {
+    const child = makeMockChild(mockChildren.length + 1);
+    mockChildren.push(child);
+    return child;
+  }),
+}));
+
+vi.mock("../agent-registry.js", () => ({
+  createAgentRegistry: mockCreateAgentRegistry,
+}));
+
+const { createKernel } = await import("../kernel.js");
+const { createLogStore } = await import("@uncaged/nerve-store");
+
+function makeConfig(agents: NerveConfig["agents"]): NerveConfig {
+  return {
+    senses: {
+      "cpu-usage": {
+        group: "system",
+        throttle: null,
+        timeout: null,
+        gracePeriod: null,
+        retention: 10_000,
+        interval: null,
+        on: [],
+      },
+    },
+    workflows: {},
+    maxRounds: 10,
+    agents,
+    extract: null,
+    api: { port: null, token: null, host: "127.0.0.1" },
+  };
+}
+
+describe("kernel — AgentRegistry hot-reload", () => {
+  let nerveRoot: string;
+
+  beforeEach(() => {
+    mockChildren.length = 0;
+    mockCreateAgentRegistry.mockClear();
+    mockCreateAgentRegistry.mockImplementation(() => ({
+      get: vi.fn(),
+      getAgentConfig: vi.fn(),
+    }));
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    nerveRoot = mkdtempSync(join(tmpdir(), "nerve-kernel-agent-reg-"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    rmSync(nerveRoot, { recursive: true, force: true });
+  });
+
+  it("rebuilds AgentRegistry on reloadConfig", async () => {
+    const logStore = createLogStore(join(nerveRoot, "logs.db"));
+    const a = makeConfig({
+      dev: { type: "echo", model: "auto", timeout: null },
+    });
+    const kernel = createKernel(a, nerveRoot, { logStore });
+    await vi.runAllTimersAsync();
+
+    expect(mockCreateAgentRegistry).toHaveBeenCalledTimes(1);
+    expect(mockCreateAgentRegistry.mock.calls[0][0]).toEqual(a.agents);
+
+    const b = makeConfig({
+      dev: { type: "echo", model: "auto", timeout: null },
+      ops: { type: "echo", model: "auto", timeout: null },
+    });
+    kernel.reloadConfig(b);
+
+    expect(mockCreateAgentRegistry).toHaveBeenCalledTimes(2);
+    expect(mockCreateAgentRegistry.mock.calls[1][0]).toEqual(b.agents);
+
+    const reloadLogs = logStore.query({ source: "system", type: "agent_registry_reload" });
+    expect(reloadLogs.length).toBe(1);
+    expect(reloadLogs[0].payload).toBe(JSON.stringify({ agentNames: ["dev", "ops"] }));
+
+    await kernel.stop();
+    await vi.runAllTimersAsync();
+  });
+
+  it("getAgentRegistry returns the registry from the latest reload", async () => {
+    const cfg = makeConfig({});
+    const kernel = createKernel(cfg, nerveRoot);
+    await vi.runAllTimersAsync();
+
+    const r1 = kernel.getAgentRegistry();
+    kernel.reloadConfig(makeConfig({ x: { type: "echo", model: "auto", timeout: null } }));
+    const r2 = kernel.getAgentRegistry();
+
+    expect(r1).not.toBe(r2);
+
+    await kernel.stop();
+    await vi.runAllTimersAsync();
+  });
+});

packages/daemon/src/agent-registry.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig, AgentFn } from "@uncaged/nerve-core";
+import { KNOWN_AGENT_ADAPTER_IDS } from "@uncaged/nerve-core";
 
 import { createEchoAgent } from "./agent-adapters/echo.js";
 
@@ -12,7 +13,9 @@ function createAgentFnForConfig(config: AgentConfig): AgentFn {
   if (config.type === "echo") {
     return createEchoAgent(config);
   }
-  throw new Error(`Unknown agent adapter type: "${config.type}"`);
+  throw new Error(
+    `Unknown agent adapter type: "${config.type}" (known: ${KNOWN_AGENT_ADAPTER_IDS.join(", ")})`,
+  );
 }
 
 export function createAgentRegistry(agents: Record<string, AgentConfig>): AgentRegistry {

packages/daemon/src/kernel.ts

@@ -19,6 +19,8 @@ import { routeSenseComputeOutput } from "@uncaged/nerve-core";
 
 import { createLogStore } from "@uncaged/nerve-store";
 import type { LogStore } from "@uncaged/nerve-store";
+import { createAgentRegistry } from "./agent-registry.js";
+import type { AgentRegistry } from "./agent-registry.js";
 import { createDaemonHandlers } from "./daemon-handlers.js";
 import { createDaemonIpcServer } from "./daemon-ipc.js";
 import type { DaemonIpcServer } from "./daemon-ipc.js";
@@ -64,6 +66,8 @@ export type Kernel = {
   triggerSense: (senseName: string) => void;
   restartGroup: (group: string) => Promise<void>;
   reloadConfig: (newConfig: NerveConfig) => void;
+  /** Agent adapters rebuilt on config hot-reload; running workflow threads keep bindings from thread start. */
+  getAgentRegistry: () => AgentRegistry;
   getHealth: () => KernelHealth;
   /** HTTP/IPC-oriented health (version, uptime seconds, hostname). */
   getDaemonHealth: () => HealthInfo;
@@ -126,6 +130,7 @@ export function createKernel(
   });
 
   let config = initialConfig;
+  let agentRegistry = createAgentRegistry(config.agents);
 
   let _signalIdCounter = 0;
   function nextSignalId(): number {
@@ -305,6 +310,14 @@ export function createKernel(
     const oldConfig = config;
     const oldWorkflows = config.workflows;
     config = newConfig;
+    agentRegistry = createAgentRegistry(newConfig.agents);
+    logStore.append({
+      source: "system",
+      type: "agent_registry_reload",
+      refId: null,
+      payload: JSON.stringify({ agentNames: Object.keys(newConfig.agents).sort() }),
+      timestamp: Date.now(),
+    });
     scheduler.stop();
     scheduler = createSenseScheduler(config, bus, triggerFn, {
       logStore,
@@ -477,6 +490,7 @@ export function createKernel(
     triggerSense,
     restartGroup: (group) => senseWorkerPool.restartGroup(group),
     reloadConfig,
+    getAgentRegistry: () => agentRegistry,
     getHealth,
     getDaemonHealth,
   };