@felipefontoura/paperclip-adapter-hermes-local-plus 0.1.11

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.11] - 2026-06-11
+
+### Added
+- Per-agent scratch CWD. Hermes is spawned with `cwd = /paperclip/instances/<inst>/workspaces/<agentId>` instead of the Paperclip server's own `/app` working directory.
+- Honest error logging on the four `try { ... } catch { ... }` blocks the plugin owns. Failures now surface on the Run page with a `[paperclip] WARN ...` line instead of being swallowed silently.
+
+### Changed
+- Default `cwd` no longer inherits from the Paperclip server. The Hermes auto-injection that pulled `/app/AGENTS.md` (the Paperclip contributor guide) into every wake's system prompt is gone.
+
+### Performance
+- **-22.7% input tokens on cold wakes (9 044 → 6 992 measured).** See [`docs/03-cwd-fix-saved-22-percent.md`](./docs/03-cwd-fix-saved-22-percent.md) for the validation report.
+
+## [0.1.10] - 2026-06-11
+
+### Fixed
+- Custom Provider env injection now uses the correct names: `OPENAI_BASE_URL` (not `OPENAI_API_BASE`) plus the `_HERMES_FORCE_<NAME>` escape hatch that bypasses Hermes's provider-env blocklist. End-to-end routing to OpenAI-compatible endpoints (Z.AI, Together AI, Groq, Ollama, vLLM, …) is finally working.
+
+## [0.1.9] - 2026-06-11
+
+### Fixed
+- `${SECRET_NAME}` substitution now resolves from `adapterConfig.env` (the agent-level Environment Variables row in the Paperclip UI) before falling back to `process.env`. Lets one company secret serve dozens of agents.
+
+## [0.1.8] - 2026-06-11
+
+### Added
+- 10 new fields on the Configuration tab: `provider` (dynamic), `customProviderBaseUrl`, `customProviderApiKey` (secret), `customProviderModelOverride`, `customProviderHeaders`, `heartbeatTemplateMode`, `toolsets`, `sessionResume`, `debug`, plus the v0.1.7 `promptTemplate`.
+- `listProviders()` populates the Provider select dynamically from `~/.hermes/config.yaml` (`custom_providers[].name`) + `~/.hermes/auth.json` (`credential_pool`). Always includes `Auto` + `Custom (OpenAI-compatible)`.
+- Custom Provider routing: when `provider = custom`, the plugin passes `--provider openai-api` and injects `OPENAI_BASE_URL` / `OPENAI_API_KEY` env vars from the form fields.
+- `heartbeatTemplateMode` (`auto` / `light` / `full` / `custom`) gives the operator explicit control over which prompt template the plugin selects.
+
+### Changed
+- Default toolsets jump from `terminal,skills` to a powerful set matching what `hermes chat` enables on the host: `terminal,skills,web,browser,file,code_execution,memory,todo,vision,session_search,delegation`. Aluno leigo gets a real Hermes agent by default.
+- Removed the broken `--reasoning-effort` push that the UI's universal `thinkingEffort` field used to generate. Hermes has no such CLI flag — the arg was being silently dropped.
+
+## [0.1.7] - 2026-06-11
+
+### Added
+- `getConfigSchema()` is now exported correctly so the Paperclip server route `GET /api/adapters/<type>/config-schema` returns the plugin's UI form fields. The earlier `agentConfigurationSchema` name was a red herring; nothing read it.
+- `LIGHT_PROMPT_TEMPLATE` for wakes where `AGENTS.md` has substantive content (>200 chars). Reduces a typical focused-task wake from ~18 k to ~5 k input tokens by skipping the heartbeat workflow injection.
+- `promptTemplate` textarea field on the Configuration tab.
+
+## [0.1.6] - 2026-06-11
+
+### Changed
+- `syncSkills()` now fetches `sourcePath` from Paperclip's HTTP API instead of inferring it via string parsing of the runtime snapshot path. Cached for 30 s per company to avoid hammering the server.
+
+## [0.1.5] - 2026-06-11
+
+### Fixed
+- Skill references survive. `syncSkills()` symlinks against the source directory (`/paperclip/instances/.../skills/<bare>`) instead of the runtime snapshot (`__runtime__/<bare>--<hash>`), which strips everything except `SKILL.md` on build. Multi-file skills (Hormozi, Feynman, etc.) now expose `references/`, `assets/`, and friends to Hermes.
+
+## [0.1.0 - 0.1.4]
+
+Initial scaffold and early iterations. See git history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Fontoura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# paperclip-adapter-hermes-local-plus
+
+**Drop-in replacement for Paperclip's built-in `hermes_local` adapter.**
+Brings the full power of [Hermes Agent](https://hermes-agent.nousresearch.com)
+into the [Paperclip](https://paperclipai.com) UI — for both the non-technical
+operator and the operator who knows their way around a YAML.
+
+```bash
+npm install @felipefontoura/paperclip-adapter-hermes-local-plus
+```
+
+That's it. No fork, no patch, no monkey-patch. The plugin registers under
+the same `type` as the built-in adapter and Paperclip's external-plugin
+loader makes it the active one.
+
+---
+
+## Why this exists
+
+Paperclip ships a tiny built-in `hermes_local` adapter that spawns
+`hermes chat -q "<prompt>"` and parses the output. It's a starting
+point. In day-to-day operation, you hit ten things that don't quite work:
+
+- Multi-file skills (Hormozi, Feynman, etc.) lose their `references/`
+  on the way to Hermes because Paperclip's runtime build strips them.
+- Provider selection lives in `~/.hermes/config.yaml`. Want this agent
+  on Anthropic and that one on Z.AI? SSH in, edit YAML, restart.
+- Pluging in a Together AI / Groq / Ollama / OpenRouter? Edit
+  `custom_providers:` by hand. Aluno leigo never finds out how.
+- The default heartbeat template kidnaps the agent. The persona you
+  carefully wrote in AGENTS.md gets overridden by "list all open
+  issues, post a completion comment …".
+- 22% of every wake's token bill is the Paperclip server's own
+  `AGENTS.md` accidentally injected by Hermes auto-discovery into the
+  system prompt — for every aluno agent that has nothing to do with
+  the Paperclip codebase.
+- Cosmetic UI fields that don't do anything ("Thinking effort" — pass-
+  through to a CLI flag that Hermes doesn't have).
+
+This plugin is the **production-grade** version that fixes all of those
+without touching the upstream Paperclip image and without writing to
+`~/.hermes/config.yaml`.
+
+The full list is in `docs/01-configuration-fields-reference.md`.
+
+---
+
+## Highlights
+
+| Feature | What it changes |
+| --- | --- |
+| **Skill references survive** | `syncSkills()` symlinks against the source directory, not the runtime snapshot. Every file in `references/`, `assets/`, etc. shows up to Hermes. |
+| **Provider dropdown that tells the truth** | UI Provider select is built dynamically from `~/.hermes/config.yaml` + `auth.json`. Only providers actually configured on this install show up. No 401s from clicking "huggingface" without a key. |
+| **Custom OpenAI-compatible provider, 1 minute** | Pick `Custom` in the Provider select, paste a Base URL, paste a key, type a model id. Plugin injects `OPENAI_BASE_URL` / `OPENAI_API_KEY` plus Hermes's `_HERMES_FORCE_` escape hatch. Routes the wake at Together / Groq / Fireworks / OpenRouter / Ollama / vLLM / anything OpenAI-shaped. |
+| **One company secret, N agents** | Custom Provider API Key field accepts `${TOGETHER_API_KEY}` references resolved from the agent-level Environment Variables row. Rotate a key once; every agent picks up the change. |
+| **Heartbeat template that doesn't hijack** | When `AGENTS.md` has substantive content, a light prompt template kicks in. The persona drives, not the operational workflow. 18 k → 5 k input tokens on a focused-task wake we measured. |
+| **22% token cost reduction shipped** | Per-agent scratch CWD stops Hermes from auto-injecting Paperclip's own contributor guide as "Project Context". Verified live: 9 044 → 6 992 input tokens. |
+| **Honest error surfaces** | No silent `catch { }` blocks for failure paths the plugin owns. Wrong JSON in Extra Headers? Surface in the Run page. Provider auto-detection fell back? Logged. |
+| **Configuration fields the upstream adapter doesn't expose** | `getConfigSchema()` returns 10 fields the Paperclip UI renders natively — Provider, Custom Provider URL/Key/Model/Headers, Heartbeat template mode, Prompt template, Toolsets, Session resume, Debug. |
+
+---
+
+## How to install
+
+### Option 1: as a Paperclip external plugin
+
+The Paperclip server reads `/paperclip/adapter-plugins.json`. Add this
+plugin and restart the service:
+
+```bash
+# Inside the paperclip container
+cd /paperclip/adapter-plugins
+mkdir -p hermes-local-plus-0.1.11
+cd hermes-local-plus-0.1.11
+npm pack @felipefontoura/paperclip-adapter-hermes-local-plus@0.1.11
+tar xzf felipefontoura-paperclip-adapter-hermes-local-plus-0.1.11.tgz --strip-components=1
+
+# Register
+node -e '
+  const fs = require("fs");
+  const p = "/paperclip/adapter-plugins.json";
+  const cur = JSON.parse(fs.readFileSync(p, "utf8")).filter(x => x.type !== "hermes_local");
+  cur.push({
+    packageName: "/paperclip/adapter-plugins/hermes-local-plus-0.1.11",
+    localPath:   "/paperclip/adapter-plugins/hermes-local-plus-0.1.11",
+    version: "0.1.11",
+    type: "hermes_local",
+    installedAt: new Date().toISOString(),
+  });
+  fs.writeFileSync(p, JSON.stringify(cur, null, 2));
+'
+
+# Restart paperclip
+docker service update --force paperclip_paperclip
+```
+
+After the restart Paperclip's UI shows `Hermes Agent (local)` as an
+adapter type. Create an agent, hit `Run Heartbeat`, done.
+
+### Option 2: via bento (unattended install)
+
+If your Paperclip lives on a [bento](https://github.com/felipefontoura/bento)-managed
+host, `bento install paperclip` does everything above. See
+`docs/04-bento-unattended-install.md` for the full breakdown.
+
+---
+
+## Configuration in the Paperclip UI
+
+`Configuration` tab on every agent of type `Hermes Agent (local)`:
+
+```
+Permissions & Configuration
+├── Command                           hermes
+├── Model                             Default ▾  (dynamic from config.yaml)
+├── Provider                          Auto ▾     (dynamic from config.yaml + auth.json)
+├── Custom Provider — Base URL        https://api.together.xyz/v1
+├── Custom Provider — API Key         ${TOGETHER_API_KEY}
+├── Custom Provider — Model           meta-llama/Llama-3.1-70B-Instruct
+├── Custom Provider — Extra headers   {"X-Org-Id": "abc"}
+├── Heartbeat template mode           Auto ▾
+├── Prompt template (advanced)        (textarea, supports {{variables}})
+├── Toolsets                          terminal,skills,web,browser,...
+├── Session resume                    Auto ▾
+└── Debug                             ⚫ off
+```
+
+Each field is documented in `docs/01-configuration-fields-reference.md`
+with the exact CLI flag / env var it maps to and the trade-off you're
+buying.
+
+---
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Paperclip server (Node)                                │
+│   ↳ external adapter plugin: hermes-local-plus         │
+│       ├── getConfigSchema()    drives the UI form       │
+│       ├── listModels()         Model select             │
+│       ├── listProviders()      Provider select          │
+│       ├── execute(ctx, cfg)    spawns Hermes subprocess │
+│       └── syncSkills(ctx, …)   symlinks source dirs     │
+└──────────────────────┬─────────────────────────────────┘
+                       │  subprocess
+                       ▼
+┌────────────────────────────────────────────────────────┐
+│ /usr/local/bin/hermes-paperclip                        │
+│   ↳ wraps /opt/hermes/bin/hermes                       │
+│       ↳ reads ~/.hermes/config.yaml + auth.json + .env │
+│       ↳ runs `chat` with args+env from the plugin      │
+└────────────────────────────────────────────────────────┘
+```
+
+The plugin owns translation: UI form fields → CLI args + env vars.
+Hermes owns execution. `config.yaml` belongs to the operator alone —
+the plugin reads it to populate dropdowns, but never writes.
+
+---
+
+## Documentation
+
+| Doc | Read when |
+| --- | --- |
+| [`docs/01-configuration-fields-reference.md`](./docs/01-configuration-fields-reference.md) | You're configuring an agent and want to know what a field does, what the trade-off is, and an example. |
+| [`docs/02-why-wakes-cost-tokens.md`](./docs/02-why-wakes-cost-tokens.md) | You're surprised by your bill. Empirical breakdown of where Hermes input tokens go, what's prunable, what isn't. |
+| [`docs/03-cwd-fix-saved-22-percent.md`](./docs/03-cwd-fix-saved-22-percent.md) | You want a template for measuring + validating a plugin optimization. |
+| [`docs/04-bento-unattended-install.md`](./docs/04-bento-unattended-install.md) | You operate a bento-managed host and want the unattended install path. |
+
+---
+
+## Compatibility
+
+Tested against:
+
+- Paperclip server: `ghcr.io/paperclipai/paperclip:latest` (built-in
+  external-adapter loader required).
+- Hermes Agent: `nousresearch/hermes-agent:latest`. Verified routes:
+  `chat`, `sessions export`, `--resume`, `--continue`. Custom Provider
+  routing tested with Z.AI's OpenAI-compatible endpoint.
+- Providers exercised end-to-end: Anthropic (`anthropic`), OpenAI
+  (`openai-codex`), Z.AI (`zai-coding-plan`), OpenRouter (`openrouter`),
+  any OpenAI-compatible via the Custom Provider form.
+- Docker Swarm with Paperclip running as a single replica. Plugin is
+  stateless — multi-replica is a function of the underlying Paperclip
+  install, not us.
+
+---
+
+## Status
+
+`v0.1.x` — production-deployed at the maintainer's install. Stable for
+the use cases listed above. Breaking changes still permitted between
+minor versions while the API settles. Pin a specific version in your
+`adapter-plugins.json` entry.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).
+
+Built on top of [`hermes-paperclip-adapter`](https://github.com/NousResearch/hermes-agent)
+(Nous Research) — same shape, different opinion about what the operator
+actually needs.

package/dist/build-config-BVrymwyU.d.ts

@@ -0,0 +1,90 @@
+import { CreateConfigValues } from '@paperclipai/adapter-utils';
+
+/**
+ * Build adapter configuration from UI form values.
+ *
+ * Translates Paperclip's CreateConfigValues into the adapterConfig
+ * object stored in the agent record.
+ *
+ * NOTE: Provider resolution happens at runtime in execute.ts, not here.
+ * The UI may or may not pass a provider field. If it does, we persist it
+ * as the user's explicit override. If not, execute.ts will detect it from
+ * ~/.hermes/config.yaml at runtime.
+ */
+
+/**
+ * Build a Hermes Agent adapter config from the Paperclip UI form values.
+ */
+declare function buildHermesConfig(v: CreateConfigValues): Record<string, unknown>;
+/**
+ * v0.1.7 — `getConfigSchema()` for the Paperclip Configuration tab.
+ *
+ * Paperclip's UI calls `GET /api/adapters/<type>/config-schema`, which in
+ * turn calls `adapter.getConfigSchema()` on the registered adapter object
+ * (see `/app/server/dist/routes/adapters.js:498`). The function MUST be
+ * named exactly that on the adapter — `agentConfigurationSchema` was a
+ * red herring; it isn't read by anything.
+ *
+ * Verified shape (mirrors `@paperclipai/adapter-cursor-cloud`):
+ *
+ *   {
+ *     fields: [{
+ *       key:       string,           // adapterConfig key the field writes to
+ *       label:     string,           // UI label
+ *       type:      "text" | "select" | "toggle",   // observed values
+ *       required?: boolean,
+ *       default?:  string | boolean, // NOT "defaultValue"
+ *       hint?:     string,           // NOT "description"
+ *       options?:  [{ value, label }] // only for type: "select"
+ *     }]
+ *   }
+ *
+ * Aluno-leigo note: a "textarea" type was NOT observed in any built-in
+ * adapter. We use plain "text" — even multi-line content survives there,
+ * just gets rendered in a single-line input. Trade-off accepted: real
+ * UI for the field, ugly for long content. Advanced users that paste
+ * multi-line templates can still set them via `PATCH adapterConfig`.
+ */
+declare function getConfigSchema(): Promise<{
+    fields: ({
+        key: string;
+        label: string;
+        type: "select";
+        default: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+        hint: string;
+    } | {
+        key: string;
+        label: string;
+        type: "text";
+        default: string;
+        hint: string;
+        options?: undefined;
+    } | {
+        key: string;
+        label: string;
+        type: "secret";
+        default: string;
+        hint: string;
+        options?: undefined;
+    } | {
+        key: string;
+        label: string;
+        type: "textarea";
+        default: string;
+        hint: string;
+        options?: undefined;
+    } | {
+        key: string;
+        label: string;
+        type: "toggle";
+        default: boolean;
+        hint: string;
+        options?: undefined;
+    })[];
+}>;
+
+export { buildHermesConfig as b, getConfigSchema as g };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import * as _paperclipai_adapter_utils from '@paperclipai/adapter-utils';
+import { execute, testEnvironment, listSkills as listHermesSkills, syncSkills as syncHermesSkills, detectModel, listModels } from './server/index.js';
+export { sessionCodec } from './server/index.js';
+import { g as getConfigSchema } from './build-config-BVrymwyU.js';
+
+declare const type = "hermes_local";
+declare const label = "Hermes Agent";
+declare const category: "local";
+/**
+ * Models list — always empty at build time. The combobox is populated at
+ * runtime by `listModels()` (server/index.ts), which inspects Hermes'
+ * actual config + credential pool on disk. Hardcoding would force every
+ * install to ship Felipe-specific provider names.
+ */
+declare const models: never[];
+declare const agentConfigurationDoc: {
+    summary: string;
+    steps: string[];
+};
+/**
+ * Paperclip plugin-loader contract — must export createServerAdapter()
+ * returning a ServerAdapterModule. Capabilities here are what Patch #1
+ * in paperclip-hermes-patch-bundle.md added by hand to the core
+ * registry.js — embedding them in the plugin module means no bind mount.
+ */
+declare function createServerAdapter(): {
+    type: string;
+    label: string;
+    category: "local";
+    execute: typeof execute;
+    testEnvironment: typeof testEnvironment;
+    sessionCodec: _paperclipai_adapter_utils.AdapterSessionCodec;
+    listSkills: typeof listHermesSkills;
+    syncSkills: typeof syncHermesSkills;
+    detectModel: typeof detectModel;
+    listModels: typeof listModels;
+    models: never[];
+    agentConfigurationDoc: {
+        summary: string;
+        steps: string[];
+    };
+    getConfigSchema: typeof getConfigSchema;
+    supportsInstructionsBundle: boolean;
+    instructionsPathKey: string;
+    supportsLocalAgentJwt: boolean;
+    requiresMaterializedRuntimeSkills: boolean;
+};
+
+export { agentConfigurationDoc, category, createServerAdapter, detectModel, execute, label, listHermesSkills as listSkills, models, syncHermesSkills as syncSkills, testEnvironment, type };