feat(cli): add agentOverrides and modelOverrides to config key validation (#532)

- Add agentOverrides (minDepth 3) and modelOverrides (minDepth 2) to VALID_CONFIG_KEYS
- Support per-key minDepth instead of hardcoded 3
- No knownFields for either key (sub-keys are user-defined)
- Add 5 new tests covering valid/invalid paths for both keys

小橘 <xiaoju@shazhou.work>

.changeset/pre.json

@@ -0,0 +1,30 @@
+{
+  "mode": "exit",
+  "tag": "alpha",
+  "initialVersions": {
+    "@uncaged/cli-workflow": "0.4.5",
+    "@uncaged/workflow-agent-cursor": "0.4.5",
+    "@uncaged/workflow-agent-hermes": "0.4.5",
+    "@uncaged/workflow-agent-llm": "0.4.5",
+    "@uncaged/workflow-agent-react": "0.4.5",
+    "@uncaged/workflow-cas": "0.4.5",
+    "@uncaged/workflow-dashboard": "0.1.0",
+    "@uncaged/workflow-execute": "0.4.5",
+    "@uncaged/workflow-gateway": "0.4.5",
+    "@uncaged/workflow-protocol": "0.4.5",
+    "@uncaged/workflow-reactor": "0.4.5",
+    "@uncaged/workflow-register": "0.4.5",
+    "@uncaged/workflow-runtime": "0.4.5",
+    "@uncaged/workflow-template-develop": "0.4.5",
+    "@uncaged/workflow-template-solve-issue": "0.4.5",
+    "@uncaged/workflow-util": "0.4.5",
+    "@uncaged/workflow-util-agent": "0.4.5"
+  },
+  "changesets": [
+    "env-api-unify",
+    "fix-internal-deps",
+    "fix-publish-src",
+    "fix-workspace-deps",
+    "rfc-252-agent-fn"
+  ]
+}

packages/cli-workflow/CHANGELOG.md

@@ -1,11 +0,0 @@
-# @uncaged/cli-workflow
-
-## 0.5.1
-
-### Patch Changes
-
-- Add 5 persona-based skills (actor, user, author, developer, adapter) and fix skill CLI description truncation
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/cli-workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/cli-workflow/src/__tests__/config.test.ts

@@ -618,5 +618,65 @@ defaultModel: default
         rmSync(tempDir, { recursive: true, force: true });
       }
     });
+
+    test("agentOverrides — accepts valid 3-segment path", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "agentOverrides.solve-issue.planner", "claude-code");
+        const value = await cmdConfigGet(tempDir, "agentOverrides.solve-issue.planner");
+        expect(value).toBe("claude-code");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("agentOverrides — rejects incomplete path (2 segments)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "agentOverrides.solve-issue", "hermes")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("modelOverrides — accepts valid 2-segment path", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "modelOverrides.extract", "gpt4");
+        const value = await cmdConfigGet(tempDir, "modelOverrides.extract");
+        expect(value).toBe("gpt4");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("modelOverrides — rejects incomplete path (1 segment only)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "modelOverrides", "gpt4")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects unknown top-level key (regression)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "randomKey", "value")).rejects.toThrow(
+          /Unknown config key/,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
   });
 });

packages/cli-workflow/src/cli.ts

@@ -564,7 +564,7 @@ program
   .option("--base-url <url>", "OpenAI-compatible API base URL")
   .option("--api-key <key>", "API key")
   .option("--model <name>", "Default model name")
-  .option("--agent <name>", "Default agent alias")
+  .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
   .action(
     (opts: {
       provider?: string;

packages/cli-workflow/src/commands/config.ts

@@ -5,7 +5,10 @@ import { parse, stringify } from "yaml";
 /**
  * Valid configuration key schema
  */
-const VALID_CONFIG_KEYS: Record<string, { nested: boolean; knownFields?: string[] }> = {
+const VALID_CONFIG_KEYS: Record<
+  string,
+  { nested: boolean; knownFields?: string[]; minDepth?: number }
+> = {
   providers: {
     nested: true,
     knownFields: ["baseUrl", "apiKey"],
@@ -18,6 +21,17 @@ const VALID_CONFIG_KEYS: Record<string, { nested: boolean; knownFields?: string[
     nested: true,
     knownFields: ["command", "args"],
   },
+  agentOverrides: {
+    nested: true,
+    // agentOverrides.<workflowName>.<roleName> = agentAlias (string value)
+    // No knownFields — workflow/role names are user-defined
+  },
+  modelOverrides: {
+    nested: true,
+    minDepth: 2,
+    // modelOverrides.<scenario> = modelAlias (string value)
+    // No knownFields — scenarios are user-defined
+  },
   defaultAgent: { nested: false },
   defaultModel: { nested: false },
 };
@@ -43,8 +57,9 @@ function validateConfigKey(path: string[]): void {
     throw new Error(`${topLevel} is a scalar key and cannot have nested properties`);
   }
 
-  // Nested keys must have at least 3 segments (e.g., providers.myProvider.baseUrl)
-  if (schema.nested && path.length < 3) {
+  // Nested keys must have at least minDepth segments (default 3)
+  const minDepth = schema.minDepth ?? 3;
+  if (schema.nested && path.length < minDepth) {
     const fields = schema.knownFields?.join(", ") ?? "";
     throw new Error(
       `Incomplete path for ${topLevel}. Must specify a field (e.g., ${topLevel}.<name>.<field>). Valid fields: ${fields}`,

packages/workflow-agent-builtin/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-agent-builtin
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-builtin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-builtin",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-agent-claude-code/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-agent-claude-code
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-claude-code",
-  "version": "0.5.1",
+  "version": "0.1.0",
   "files": [
     "src",
     "dist",

packages/workflow-agent-hermes/CHANGELOG.md

@@ -1,10 +0,0 @@
-# @uncaged/workflow-agent-hermes
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1
-  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-hermes/README.md

@@ -1,10 +1,12 @@
 # @uncaged/workflow-agent-hermes
 
-`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
+`uwf-hermes` — an **agent adapter** that bridges the `uwf` workflow engine and the Hermes CLI.
 
 ## Overview
 
-Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
+`uwf-hermes` is an adapter (not the Hermes CLI itself). The `uwf` engine speaks a generic agent protocol (stdin/stdout frontmatter contract); `uwf-hermes` translates that protocol into Hermes ACP (Agent Client Protocol) calls. Other adapters (e.g. `uwf-claude-code`, `uwf-cursor`) do the same for their respective CLIs.
+
+On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
 
 **Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
 

packages/workflow-agent-hermes/__tests__/issue-551.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PKG_ROOT = join(import.meta.dir, "..");
+
+describe("Issue #551 — bin entry & engines", () => {
+  test("package.json declares bun in engines", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    expect(pkg.engines).toBeDefined();
+    expect(pkg.engines.bun).toBeDefined();
+    expect(pkg.engines.bun).toMatch(/^>=?\s*[\d.]+/);
+  });
+
+  test("bin entry file has bun shebang", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    const binPath = pkg.bin["uwf-hermes"];
+    const content = readFileSync(join(PKG_ROOT, binPath), "utf-8");
+    expect(content.startsWith("#!/usr/bin/env bun")).toBe(true);
+  });
+
+  test("README.md explains uwf-hermes is an adapter", () => {
+    const readme = readFileSync(join(PKG_ROOT, "README.md"), "utf-8");
+    expect(readme.toLowerCase()).toContain("adapter");
+    expect(readme).toMatch(/uwf-hermes/);
+    expect(readme).toMatch(/hermes/);
+  });
+});

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",
@@ -42,5 +42,8 @@
   "bugs": {
     "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
   },
+  "engines": {
+    "bun": ">= 1.0.0"
+  },
   "license": "MIT"
 }

packages/workflow-protocol/CHANGELOG.md

@@ -1,3 +0,0 @@
-# @uncaged/workflow-protocol
-
-## 0.5.1

packages/workflow-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-util-agent/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @uncaged/workflow-util-agent
-
-## 0.5.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @uncaged/workflow-util@0.5.1
-  - @uncaged/workflow-protocol@0.5.1

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util-agent",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

packages/workflow-util/CHANGELOG.md

@@ -1,7 +0,0 @@
-# @uncaged/workflow-util
-
-## 0.5.1
-
-### Patch Changes
-
-- Add 5 persona-based skills (actor, user, author, developer, adapter) and fix skill CLI description truncation

packages/workflow-util/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-util",
-  "version": "0.5.1",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",

scripts/publish-all.mjs

@@ -21,7 +21,6 @@ const publishOrder = [
   "workflow-util-agent",
   "workflow-agent-hermes",
   "workflow-agent-builtin",
-  "workflow-agent-claude-code",
   "cli-workflow",
 ];