Merge pull request 'fix(hermes): add engines.bun, document adapter pattern (#551)' (#552) from fix/551-hermes-bin-engines into main

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/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

@@ -42,5 +42,8 @@
   "bugs": {
     "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
   },
+  "engines": {
+    "bun": ">= 1.0.0"
+  },
   "license": "MIT"
 }