The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(adapters): restore built-in Hermes and sync lockfile with server
HenkDzf884cbab78f9
diff --git a/docs/adapters/overview.md b/docs/adapters/overview.mdindex 55fd4d4e9d..dfb4b21fb3 100644--- a/docs/adapters/overview.md+++ b/docs/adapters/overview.md@@ -24,6 +24,7 @@ When a heartbeat fires, Paperclip:| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) || Cursor | `cursor` | Runs Cursor in background mode || Pi Local | `pi_local` | Runs an embedded Pi agent locally |+| Hermes Local | `hermes_local` | Runs Hermes CLI locally (`hermes-paperclip-adapter`) || OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint || [Process](/adapters/process) | `process` | Executes arbitrary shell commands || [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |@@ -35,7 +36,6 @@ These adapters ship as standalone npm packages and are installed via the plugin| Adapter | Package | Type Key | Description ||---------|---------|----------|-------------|| Droid Local | `@henkey/droid-paperclip-adapter` | `droid_local` | Runs Factory Droid locally |-| Hermes Local | `@henkey/hermes-paperclip-adapter` | `hermes_local` | Runs Hermes CLI locally |## External Adapters@@ -78,7 +78,7 @@ my-adapter/## Choosing an Adapter-- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, or install `droid_local` / `hermes_local` as external plugins+- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, or install `droid_local` as an external plugin- **Need to run a script or command?** Use `process`- **Need to call an external service?** Use `http`- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter) or [build an external adapter plugin](/adapters/external-adapters)diff --git a/docs/agents-runtime.md b/docs/agents-runtime.mdindex dffb6fe29a..cafc39e975 100644--- a/docs/agents-runtime.md+++ b/docs/agents-runtime.md@@ -39,6 +39,7 @@ Built-in adapters:- `opencode_local`: runs your local `opencode` CLI- `cursor`: runs Cursor in background mode- `pi_local`: runs an embedded Pi agent locally+- `hermes_local`: runs your local `hermes` CLI (`hermes-paperclip-adapter`)- `openclaw_gateway`: connects to an OpenClaw gateway endpoint- `process`: generic shell command adapter- `http`: calls an external HTTP endpoint@@ -46,9 +47,8 @@ Built-in adapters:External plugin adapters (install via the adapter manager or API):- `droid_local`: runs your local Factory Droid CLI (`@henkey/droid-paperclip-adapter`)-- `hermes_local`: runs your local `hermes` CLI (`@henkey/hermes-paperclip-adapter`)-For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `droid_local`, `hermes_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.+For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `droid_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.## 3.2 Runtime behavior@@ -177,7 +177,7 @@ Start with least privilege where possible, and avoid exposing secrets in broad r## 10. Minimal setup checklist-1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` and `hermes_local` are also available via the adapter manager.+1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` are also available via the adapter manager.2. Set `cwd` to the target workspace (for local adapters).3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle.4. Configure heartbeat policy (timer and/or assignment wakeups).diff --git a/server/package.json b/server/package.jsonindex b519ed1a7f..4b95606abb 100644--- a/server/package.json+++ b/server/package.json@@ -66,6 +66,7 @@"drizzle-orm": "^0.38.4","embedded-postgres": "^18.1.0-beta.16","express": "^5.1.0",+ "hermes-paperclip-adapter": "^0.2.0","jsdom": "^28.1.0","multer": "^2.0.2","open": "^11.0.0",diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.tsnew file mode 100644index 0000000000..463a56945f--- /dev/null+++ b/server/src/adapters/builtin-adapter-types.ts@@ -0,0 +1,15 @@+/**+ * Adapter types shipped with Paperclip. External plugins must not replace these.+ */+export const BUILTIN_ADAPTER_TYPES = new Set([+ "claude_local",+ "codex_local",+ "cursor",+ "gemini_local",+ "openclaw_gateway",+ "opencode_local",+ "pi_local",+ "hermes_local",+ "process",+ "http",+]);diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 35ae45c57d..aa8ddeb465 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -67,6 +67,21 @@ import {import {agentConfigurationDoc as piAgentConfigurationDoc,} from "@paperclipai/adapter-pi-local";+import {+ execute as hermesExecute,+ testEnvironment as hermesTestEnvironment,+ sessionCodec as hermesSessionCodec,+ listSkills as hermesListSkills,+ syncSkills as hermesSyncSkills,+ detectModel as detectModelFromHermes,+} from "hermes-paperclip-adapter/server";+import {+ agentConfigurationDoc as hermesAgentConfigurationDoc,+ models as hermesModels,+} from "hermes-paperclip-adapter";+import { BUILTIN_ADAPTER_TYPES } from "./builtin-adapter-types.js";+import { buildExternalAdapters } from "./plugin-loader.js";+import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";import { processAdapter } from "./process/index.js";import { httpAdapter } from "./http/index.js";@@ -163,6 +178,19 @@ const piLocalAdapter: ServerAdapterModule = {agentConfigurationDoc: piAgentConfigurationDoc,};+const hermesLocalAdapter: ServerAdapterModule = {+ type: "hermes_local",+ execute: hermesExecute,+ testEnvironment: hermesTestEnvironment,+ sessionCodec: hermesSessionCodec,+ listSkills: hermesListSkills,+ syncSkills: hermesSyncSkills,+ models: hermesModels,+ supportsLocalAgentJwt: true,+ agentConfigurationDoc: hermesAgentConfigurationDoc,+ detectModel: () => detectModelFromHermes(),+};+const adaptersByType = new Map<string, ServerAdapterModule>();function registerBuiltInAdapters() {@@ -174,6 +202,7 @@ function registerBuiltInAdapters() {cursorLocalAdapter,geminiLocalAdapter,openclawGatewayAdapter,+ hermesLocalAdapter,processAdapter,httpAdapter,]) {@@ -184,15 +213,12 @@ function registerBuiltInAdapters() {registerBuiltInAdapters();// ----------------------------------------------------------------------------// Load external adapter plugins (droid, hermes, etc.)+// Load external adapter plugins (e.g. droid_local)//// External adapter packages export createServerAdapter() which returns a// ServerAdapterModule. The host fills in sessionManagement.// ----------------------------------------------------------------------------import { buildExternalAdapters } from "./plugin-loader.js";-import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";-/** Cached sync wrapper — the store is a simple JSON file read, safe to call frequently. */function getDisabledAdapterTypesFromStore(): string[] {return getDisabledAdapterTypes();@@ -208,6 +234,12 @@ const externalAdaptersReady: Promise<void> = (async () => {try {const externalAdapters = await buildExternalAdapters();for (const externalAdapter of externalAdapters) {+ if (BUILTIN_ADAPTER_TYPES.has(externalAdapter.type)) {+ console.warn(+ `[paperclip] Skipping external adapter "${externalAdapter.type}" — conflicts with built-in adapter`,+ );+ continue;+ }adaptersByType.set(externalAdapter.type,{diff --git a/server/src/routes/adapters.ts b/server/src/routes/adapters.tsindex c50d558122..579ed31d49 100644--- a/server/src/routes/adapters.ts+++ b/server/src/routes/adapters.ts@@ -39,25 +39,10 @@ import type { ServerAdapterModule } from "../adapters/types.js";import { loadExternalAdapterPackage, getUiParserSource, getOrExtractUiParserSource, reloadExternalAdapter } from "../adapters/plugin-loader.js";import { logger } from "../middleware/logger.js";import { assertBoard } from "./authz.js";+import { BUILTIN_ADAPTER_TYPES } from "../adapters/builtin-adapter-types.js";const execFileAsync = promisify(execFile);-// ----------------------------------------------------------------------------// Known built-in adapter types (cannot be removed via the API)-// -----------------------------------------------------------------------------const BUILTIN_ADAPTER_TYPES = new Set([- "claude_local",- "codex_local",- "cursor",- "gemini_local",- "openclaw_gateway",- "opencode_local",- "pi_local",- "process",- "http",-]);-// ---------------------------------------------------------------------------// Request / Response types// ---------------------------------------------------------------------------diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex 36a87d6338..8bf2a1045f 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -76,6 +76,7 @@ export function agentRoutes(db: Db) {codex_local: "instructionsFilePath",droid_local: "instructionsFilePath",gemini_local: "instructionsFilePath",+ hermes_local: "instructionsFilePath",opencode_local: "instructionsFilePath",cursor: "instructionsFilePath",pi_local: "instructionsFilePath",diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.tsindex cbaae0119d..fe80927396 100644--- a/ui/src/adapters/adapter-display-registry.ts+++ b/ui/src/adapters/adapter-display-registry.ts@@ -16,6 +16,7 @@ import {Cpu,} from "lucide-react";import { OpenCodeLogoIcon } from "@/components/OpenCodeLogoIcon";+import { HermesIcon } from "@/components/HermesIcon";// ---------------------------------------------------------------------------// Type suffix parsing@@ -73,6 +74,11 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {description: "Local multi-provider agent",icon: OpenCodeLogoIcon,},+ hermes_local: {+ label: "Hermes Agent",+ description: "Local Hermes CLI agent",+ icon: HermesIcon,+ },pi_local: {label: "Pi",description: "Local Pi agent",diff --git a/ui/src/adapters/hermes-local/config-fields.tsx b/ui/src/adapters/hermes-local/config-fields.tsxnew file mode 100644index 0000000000..4b80704365--- /dev/null+++ b/ui/src/adapters/hermes-local/config-fields.tsx@@ -0,0 +1,49 @@+import type { AdapterConfigFieldsProps } from "../types";+import {+ Field,+ DraftInput,+} from "../../components/agent-config-primitives";+import { ChoosePathButton } from "../../components/PathInstructionsModal";++const inputClass =+ "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";+const instructionsFileHint =+ "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";++export function HermesLocalConfigFields({+ isCreate,+ values,+ set,+ config,+ eff,+ mark,+ hideInstructionsFile,+}: AdapterConfigFieldsProps) {+ if (hideInstructionsFile) return null;+ return (+ <Field label="Agent instructions file" hint={instructionsFileHint}>+ <div className="flex items-center gap-2">+ <DraftInput+ value={+ isCreate+ ? values!.instructionsFilePath ?? ""+ : eff(+ "adapterConfig",+ "instructionsFilePath",+ String(config.instructionsFilePath ?? ""),+ )+ }+ onCommit={(v) =>+ isCreate+ ? set!({ instructionsFilePath: v })+ : mark("adapterConfig", "instructionsFilePath", v || undefined)+ }+ immediate+ className={inputClass}+ placeholder="/absolute/path/to/AGENTS.md"+ />+ <ChoosePathButton />+ </div>+ </Field>+ );+}diff --git a/ui/src/adapters/hermes-local/index.ts b/ui/src/adapters/hermes-local/index.tsnew file mode 100644index 0000000000..93d9ed6aca--- /dev/null+++ b/ui/src/adapters/hermes-local/index.ts@@ -0,0 +1,12 @@+import type { UIAdapterModule } from "../types";+import { parseHermesStdoutLine } from "hermes-paperclip-adapter/ui";+import { HermesLocalConfigFields } from "./config-fields";+import { buildHermesConfig } from "hermes-paperclip-adapter/ui";++export const hermesLocalUIAdapter: UIAdapterModule = {+ type: "hermes_local",+ label: "Hermes Agent",+ parseStdoutLine: parseHermesStdoutLine,+ ConfigFields: HermesLocalConfigFields,+ buildAdapterConfig: buildHermesConfig,+};diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.tsindex a27e7316fb..8c48ecbc3c 100644--- a/ui/src/adapters/registry.ts+++ b/ui/src/adapters/registry.ts@@ -6,6 +6,7 @@ import { geminiLocalUIAdapter } from "./gemini-local";import { openCodeLocalUIAdapter } from "./opencode-local";import { piLocalUIAdapter } from "./pi-local";import { openClawGatewayUIAdapter } from "./openclaw-gateway";+import { hermesLocalUIAdapter } from "./hermes-local";import { processUIAdapter } from "./process";import { httpUIAdapter } from "./http";import { loadDynamicParser } from "./dynamic-loader";@@ -18,6 +19,7 @@ function registerBuiltInUIAdapters() {claudeLocalUIAdapter,codexLocalUIAdapter,geminiLocalUIAdapter,+ hermesLocalUIAdapter,openCodeLocalUIAdapter,piLocalUIAdapter,cursorLocalUIAdapter,