@paperclipai/hermes-paperclip-adapter 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+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,228 @@
+# Paperclip Adapter for Hermes Agent
+
+A [Paperclip](https://paperclip.ing) adapter that lets you run [Hermes Agent](https://github.com/NousResearch/hermes-agent) as a managed employee in a Paperclip company.
+
+Hermes Agent is a full-featured AI agent by [Nous Research](https://nousresearch.com) with 30+ native tools, persistent memory, session persistence, 80+ skills, MCP support, and multi-provider model access.
+
+## Key Features
+
+This adapter provides:
+
+- **8 inference providers** — Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax
+- **Skills integration** — Scans both Paperclip-managed and Hermes-native skills (`~/.hermes/skills/`), with sync/list/resolve APIs
+- **Structured transcript parsing** — Raw Hermes stdout is parsed into typed `TranscriptEntry` objects so Paperclip renders proper tool cards with status icons and expand/collapse
+- **Rich post-processing** — Converts Hermes ASCII banners, setext headings, and `+--+` table borders into clean GFM markdown
+- **Comment-driven wakes** — Agents wake to respond to issue comments, not just task assignments
+- **Auto model detection** — Reads `~/.hermes/config.yaml` to pre-populate the UI with the user's configured model
+- **Session codec** — Structured validation and migration of session state across heartbeats
+- **Benign stderr reclassification** — MCP init messages and structured logs are reclassified so they don't appear as errors in the UI
+- **Session source tagging** — Sessions are tagged as `tool` source so they don't clutter the user's interactive history
+- **Filesystem checkpoints** — Optional `--checkpoints` for rollback safety
+- **Thinking effort control** — Passes `--reasoning-effort` for thinking/reasoning models
+
+### Hermes Agent Capabilities
+
+| Feature | Claude Code | Codex | Hermes Agent |
+|---------|------------|-------|-------------|
+| Persistent memory | ❌ | ❌ | ✅ Remembers across sessions |
+| Native tools | ~5 | ~5 | 30+ (terminal, file, web, browser, vision, git, etc.) |
+| Skills system | ❌ | ❌ | ✅ 80+ loadable skills |
+| Session search | ❌ | ❌ | ✅ FTS5 search over past conversations |
+| Sub-agent delegation | ❌ | ❌ | ✅ Parallel sub-tasks |
+| Context compression | ❌ | ❌ | ✅ Auto-compresses long conversations |
+| MCP client | ❌ | ❌ | ✅ Connect to any MCP server |
+| Multi-provider | Anthropic only | OpenAI only | ✅ 8 providers out of the box |
+
+## Installation
+
+```bash
+npm install @paperclipai/hermes-paperclip-adapter
+```
+
+### Prerequisites
+
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed (`pip install hermes-agent`)
+- Python 3.10+
+- At least one LLM API key (Anthropic, OpenRouter, or OpenAI)
+
+## Quick Start
+
+### 1. Register the adapter in your Paperclip server
+
+Add to your Paperclip server's adapter registry (`server/src/adapters/registry.ts`):
+
+```typescript
+import * as hermesLocal from "@paperclipai/hermes-paperclip-adapter";
+import {
+  execute,
+  testEnvironment,
+  detectModel,
+  listSkills,
+  syncSkills,
+  sessionCodec,
+} from "@paperclipai/hermes-paperclip-adapter/server";
+
+registry.set("hermes_local", {
+  ...hermesLocal,
+  execute,
+  testEnvironment,
+  detectModel,
+  listSkills,
+  syncSkills,
+  sessionCodec,
+});
+```
+
+### 2. Create a Hermes agent in Paperclip
+
+In the Paperclip UI or via API, create an agent with adapter type `hermes_local`:
+
+```json
+{
+  "name": "Hermes Engineer",
+  "adapterType": "hermes_local",
+  "adapterConfig": {
+    "model": "anthropic/claude-sonnet-4",
+    "maxIterations": 50,
+    "timeoutSec": 300,
+    "persistSession": true,
+    "enabledToolsets": ["terminal", "file", "web"]
+  }
+}
+```
+
+### 3. Assign work
+
+Create issues in Paperclip and assign them to your Hermes agent. On each heartbeat, Hermes will:
+
+1. Receive the task instructions
+2. Use its full tool suite to complete the work
+3. Report results back to Paperclip
+4. Persist session state for continuity
+
+## Configuration Reference
+
+### Core
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | `anthropic/claude-sonnet-4` | Model in `provider/model` format |
+| `provider` | string | *(auto-detected)* | API provider: `auto`, `openrouter`, `nous`, `openai-codex`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` |
+| `timeoutSec` | number | `300` | Execution timeout in seconds |
+| `graceSec` | number | `10` | Grace period before SIGKILL |
+
+### Tools
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `toolsets` | string | *(all)* | Comma-separated toolsets to enable (e.g. `"terminal,file,web"`) |
+
+Available toolsets: `terminal`, `file`, `web`, `browser`, `code_execution`, `vision`, `mcp`, `creative`, `productivity`
+
+### Session & Workspace
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `persistSession` | boolean | `true` | Resume sessions across heartbeats |
+| `worktreeMode` | boolean | `false` | Git worktree isolation |
+| `checkpoints` | boolean | `false` | Enable filesystem checkpoints for rollback |
+
+### Advanced
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `hermesCommand` | string | `hermes` | Custom CLI binary path |
+| `verbose` | boolean | `false` | Enable verbose output |
+| `quiet` | boolean | `true` | Quiet mode (clean output, no banner/spinner) |
+| `extraArgs` | string[] | `[]` | Additional CLI arguments |
+| `env` | object | `{}` | Extra environment variables |
+| `promptTemplate` | string | *(built-in)* | Custom prompt template |
+| `paperclipApiUrl` | string | `http://127.0.0.1:3100/api` | Paperclip API base URL |
+
+### Prompt Template Variables
+
+Use `{{variable}}` syntax in `promptTemplate`:
+
+| Variable | Description |
+|----------|-------------|
+| `{{agentId}}` | Paperclip agent ID |
+| `{{agentName}}` | Agent display name |
+| `{{companyId}}` | Company ID |
+| `{{companyName}}` | Company name |
+| `{{runId}}` | Current heartbeat run ID |
+| `{{taskId}}` | Assigned task/issue ID |
+| `{{taskTitle}}` | Task title |
+| `{{taskBody}}` | Task instructions |
+| `{{projectName}}` | Project name |
+| `{{paperclipApiUrl}}` | Paperclip API base URL |
+| `{{commentId}}` | Comment ID (when woken by a comment) |
+| `{{wakeReason}}` | Reason this run was triggered |
+
+Conditional sections:
+
+- `{{#taskId}}...{{/taskId}}` — included only when a task is assigned
+- `{{#noTask}}...{{/noTask}}` — included only when no task (heartbeat check)
+- `{{#commentId}}...{{/commentId}}` — included only when woken by a comment
+
+## Architecture
+
+```
+Paperclip                          Hermes Agent
+┌──────────────────┐               ┌──────────────────┐
+│  Heartbeat       │               │                  │
+│  Scheduler       │───execute()──▶│  hermes chat -q  │
+│                  │               │                  │
+│  Issue System    │               │  30+ Tools       │
+│  Comment Wakes   │◀──results─────│  Memory System   │
+│                  │               │  Session DB      │
+│  Cost Tracking   │               │  Skills          │
+│                  │               │  MCP Client      │
+│  Skill Sync      │◀──snapshot────│  ~/.hermes/skills│
+│  Org Chart       │               │                  │
+└──────────────────┘               └──────────────────┘
+```
+
+The adapter spawns Hermes Agent's CLI in single-query mode (`-q`). Hermes
+processes the task using its full tool suite, then exits. The adapter:
+
+1. **Captures** stdout/stderr and parses token usage, session IDs, and cost
+2. **Parses** raw output into structured `TranscriptEntry` objects (tool cards with status icons)
+3. **Post-processes** Hermes ASCII formatting (banners, setext headings, table borders) into clean GFM markdown
+4. **Reclassifies** benign stderr (MCP init, structured logs) so they don't show as errors
+5. **Tags** sessions as `tool` source to keep them separate from interactive usage
+6. **Reports** results back to Paperclip with cost, usage, and session state
+
+Session persistence works via Hermes's `--resume` flag — each run picks
+up where the last one left off, maintaining conversation context,
+memories, and tool state across heartbeats. The `sessionCodec` validates
+and migrates session state between runs.
+
+### Skills Integration
+
+The adapter scans two skill sources and merges them:
+
+- **Paperclip-managed skills** — bundled with the adapter, togglable from the UI
+- **Hermes-native skills** — from `~/.hermes/skills/`, read-only, always loaded
+
+The `listSkills` / `syncSkills` APIs expose a unified snapshot so the
+Paperclip UI can display both managed and native skills in one view.
+
+## Development
+
+```bash
+git clone https://github.com/paperclipai/hermes-paperclip-adapter
+cd hermes-paperclip-adapter
+npm install
+npm run build
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Links
+
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — The AI agent this adapter runs
+- [Paperclip](https://github.com/paperclipai/paperclip) — The orchestration platform
+- [Nous Research](https://nousresearch.com) — The team behind Hermes
+- [Paperclip Docs](https://paperclip.ing/docs) — Paperclip documentation

package/dist/cli/format-event.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI output formatting for Hermes Agent adapter.
+ *
+ * Pretty-prints Hermes output lines in the terminal when running
+ * Paperclip's CLI tools.
+ */
+/**
+ * Format a Hermes Agent stdout event for terminal display.
+ *
+ * @param raw    Raw stdout line from Hermes
+ * @param debug  If true, show extra metadata with color coding
+ */
+export declare function printHermesStreamEvent(raw: string, debug: boolean): void;
+//# sourceMappingURL=format-event.d.ts.map

package/dist/cli/format-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.d.ts","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CA6CxE"}

package/dist/cli/format-event.js

@@ -0,0 +1,52 @@
+/**
+ * CLI output formatting for Hermes Agent adapter.
+ *
+ * Pretty-prints Hermes output lines in the terminal when running
+ * Paperclip's CLI tools.
+ */
+import pc from "picocolors";
+/**
+ * Format a Hermes Agent stdout event for terminal display.
+ *
+ * @param raw    Raw stdout line from Hermes
+ * @param debug  If true, show extra metadata with color coding
+ */
+export function printHermesStreamEvent(raw, debug) {
+    const line = raw.trim();
+    if (!line)
+        return;
+    if (!debug) {
+        console.log(line);
+        return;
+    }
+    // Adapter log lines
+    if (line.startsWith("[hermes]")) {
+        console.log(pc.blue(line));
+        return;
+    }
+    // Tool output (┊ prefix)
+    if (line.startsWith("┊")) {
+        console.log(pc.cyan(line));
+        return;
+    }
+    // Thinking
+    if (line.includes("💭") || line.startsWith("<thinking>")) {
+        console.log(pc.dim(line));
+        return;
+    }
+    // Errors
+    if (line.startsWith("Error:") ||
+        line.startsWith("ERROR:") ||
+        line.startsWith("Traceback")) {
+        console.log(pc.red(line));
+        return;
+    }
+    // Session info
+    if (/session/i.test(line) && /id|saved|resumed/i.test(line)) {
+        console.log(pc.green(line));
+        return;
+    }
+    // Default: gray in debug mode
+    console.log(pc.gray(line));
+}
+//# sourceMappingURL=format-event.js.map

package/dist/cli/format-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.js","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,KAAc;IAChE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO;IAElB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IAED,oBAAoB;IACpB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,yBAAyB;IACzB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,WAAW;IACX,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,SAAS;IACT,IACE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAC5B,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,eAAe;IACf,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,8BAA8B;IAC9B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI module exports — used by Paperclip's CLI for terminal formatting.
+ */
+export { printHermesStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,5 @@
+/**
+ * CLI module exports — used by Paperclip's CLI for terminal formatting.
+ */
+export { printHermesStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hermes Agent adapter for Paperclip.
+ *
+ * Runs Hermes Agent (https://github.com/NousResearch/hermes-agent)
+ * as a managed employee in a Paperclip company. Hermes Agent is a
+ * full-featured AI agent with 30+ native tools, persistent memory,
+ * skills, session persistence, and MCP support.
+ *
+ * @packageDocumentation
+ */
+import type { ServerAdapterModule } from "@paperclipai/adapter-utils";
+export declare const type = "hermes_local";
+export declare const label = "Hermes Agent";
+/**
+ * Models available through Hermes Agent.
+ *
+ * Hermes supports any model via any provider. The Paperclip UI should
+ * prefer detectModel() plus manual entry over curated placeholder models,
+ * since Hermes availability depends on the user's local configuration.
+ */
+export declare const models: {
+    id: string;
+    label: string;
+}[];
+/**
+ * Documentation shown in the Paperclip UI when configuring a Hermes agent.
+ */
+export declare const agentConfigurationDoc = "# Hermes Agent Configuration\n\nHermes Agent is a full-featured AI agent by Nous Research with 30+ native\ntools, persistent memory, session persistence, skills, and MCP support.\n\n## Prerequisites\n\n- Python 3.10+ installed\n- Hermes Agent installed: `pip install hermes-agent`\n- At least one LLM API key configured in ~/.hermes/.env\n\n## Core Configuration\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| model | string | (Hermes configured default) | Optional explicit model in provider/model format. Leave blank to use Hermes's configured default model. |\n| provider | string | (auto) | API provider: auto, openrouter, nous, openai-codex, zai, kimi-coding, minimax, minimax-cn. Usually not needed \u2014 Hermes auto-detects from model name. |\n| timeoutSec | number | 300 | Execution timeout in seconds |\n| graceSec | number | 10 | Grace period after SIGTERM before SIGKILL |\n\n## Tool Configuration\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| toolsets | string | (all) | Comma-separated toolsets to enable (e.g. \"terminal,file,web\") |\n\n## Session & Workspace\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| persistSession | boolean | true | Resume sessions across heartbeats |\n| worktreeMode | boolean | false | Use git worktree for isolated changes |\n| checkpoints | boolean | false | Enable filesystem checkpoints |\n\n## Advanced\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| hermesCommand | string | hermes | Path to hermes CLI binary |\n| verbose | boolean | false | Enable verbose output |\n| extraArgs | string[] | [] | Additional CLI arguments |\n| env | object | {} | Extra environment variables |\n| promptTemplate | string | (default) | Custom prompt template with {{variable}} placeholders |\n\n## Available Template Variables\n\n- `{{agentId}}` \u2014 Paperclip agent ID\n- `{{agentName}}` \u2014 Agent display name\n- `{{companyId}}` \u2014 Paperclip company ID\n- `{{companyName}}` \u2014 Company display name\n- `{{runId}}` \u2014 Current heartbeat run ID\n- `{{taskId}}` \u2014 Current task/issue ID (if assigned)\n- `{{taskTitle}}` \u2014 Task title (if assigned)\n- `{{taskBody}}` \u2014 Task description (if assigned)\n- `{{projectName}}` \u2014 Project name (if scoped to a project)\n";
+/**
+ * External adapter plugin entrypoint expected by Paperclip's adapter manager.
+ */
+export declare function createServerAdapter(): ServerAdapterModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAYtE,eAAO,MAAM,IAAI,iBAAe,CAAC;AACjC,eAAO,MAAM,KAAK,iBAAgB,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAO,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,qBAAqB,81EAuDjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAgBzD"}

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * Hermes Agent adapter for Paperclip.
+ *
+ * Runs Hermes Agent (https://github.com/NousResearch/hermes-agent)
+ * as a managed employee in a Paperclip company. Hermes Agent is a
+ * full-featured AI agent with 30+ native tools, persistent memory,
+ * skills, session persistence, and MCP support.
+ *
+ * @packageDocumentation
+ */
+import { ADAPTER_TYPE, ADAPTER_LABEL } from "./shared/constants.js";
+import { execute, testEnvironment, sessionCodec, listSkills, syncSkills, detectModel, } from "./server/index.js";
+export const type = ADAPTER_TYPE;
+export const label = ADAPTER_LABEL;
+/**
+ * Models available through Hermes Agent.
+ *
+ * Hermes supports any model via any provider. The Paperclip UI should
+ * prefer detectModel() plus manual entry over curated placeholder models,
+ * since Hermes availability depends on the user's local configuration.
+ */
+export const models = [];
+/**
+ * Documentation shown in the Paperclip UI when configuring a Hermes agent.
+ */
+export const agentConfigurationDoc = `# Hermes Agent Configuration
+
+Hermes Agent is a full-featured AI agent by Nous Research with 30+ native
+tools, persistent memory, session persistence, skills, and MCP support.
+
+## Prerequisites
+
+- Python 3.10+ installed
+- Hermes Agent installed: \`pip install hermes-agent\`
+- At least one LLM API key configured in ~/.hermes/.env
+
+## Core Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| model | string | (Hermes configured default) | Optional explicit model in provider/model format. Leave blank to use Hermes's configured default model. |
+| provider | string | (auto) | API provider: auto, openrouter, nous, openai-codex, zai, kimi-coding, minimax, minimax-cn. Usually not needed — Hermes auto-detects from model name. |
+| timeoutSec | number | 300 | Execution timeout in seconds |
+| graceSec | number | 10 | Grace period after SIGTERM before SIGKILL |
+
+## Tool Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| toolsets | string | (all) | Comma-separated toolsets to enable (e.g. "terminal,file,web") |
+
+## Session & Workspace
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| persistSession | boolean | true | Resume sessions across heartbeats |
+| worktreeMode | boolean | false | Use git worktree for isolated changes |
+| checkpoints | boolean | false | Enable filesystem checkpoints |
+
+## Advanced
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| hermesCommand | string | hermes | Path to hermes CLI binary |
+| verbose | boolean | false | Enable verbose output |
+| extraArgs | string[] | [] | Additional CLI arguments |
+| env | object | {} | Extra environment variables |
+| promptTemplate | string | (default) | Custom prompt template with {{variable}} placeholders |
+
+## Available Template Variables
+
+- \`{{agentId}}\` — Paperclip agent ID
+- \`{{agentName}}\` — Agent display name
+- \`{{companyId}}\` — Paperclip company ID
+- \`{{companyName}}\` — Company display name
+- \`{{runId}}\` — Current heartbeat run ID
+- \`{{taskId}}\` — Current task/issue ID (if assigned)
+- \`{{taskTitle}}\` — Task title (if assigned)
+- \`{{taskBody}}\` — Task description (if assigned)
+- \`{{projectName}}\` — Project name (if scoped to a project)
+`;
+/**
+ * External adapter plugin entrypoint expected by Paperclip's adapter manager.
+ */
+export function createServerAdapter() {
+    return {
+        type,
+        execute,
+        testEnvironment,
+        sessionCodec,
+        listSkills,
+        syncSkills,
+        models,
+        supportsLocalAgentJwt: true,
+        supportsInstructionsBundle: true,
+        instructionsPathKey: "instructionsFilePath",
+        requiresMaterializedRuntimeSkills: false,
+        agentConfigurationDoc,
+        detectModel,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,OAAO,EACP,eAAe,EACf,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,MAAM,CAAC,MAAM,IAAI,GAAG,YAAY,CAAC;AACjC,MAAM,CAAC,MAAM,KAAK,GAAG,aAAa,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAoC,EAAE,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDpC,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,IAAI;QACJ,OAAO;QACP,eAAe;QACf,YAAY;QACZ,UAAU;QACV,UAAU;QACV,MAAM;QACN,qBAAqB,EAAE,IAAI;QAC3B,0BAA0B,EAAE,IAAI;QAChC,mBAAmB,EAAE,sBAAsB;QAC3C,iCAAiC,EAAE,KAAK;QACxC,qBAAqB;QACrB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,14 @@
+import { expect, test } from "vitest";
+import { createServerAdapter } from "./index.js";
+test("root package export exposes Paperclip external adapter entrypoint", () => {
+    const adapter = createServerAdapter();
+    expect(adapter.type).toBe("hermes_local");
+    expect(typeof adapter.execute).toBe("function");
+    expect(typeof adapter.testEnvironment).toBe("function");
+    expect(typeof adapter.sessionCodec?.deserialize).toBe("function");
+    expect(adapter.supportsLocalAgentJwt).toBe(true);
+    expect(adapter.supportsInstructionsBundle).toBe(true);
+    expect(adapter.instructionsPathKey).toBe("instructionsFilePath");
+    expect(typeof adapter.detectModel).toBe("function");
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,IAAI,CAAC,mEAAmE,EAAE,GAAG,EAAE;IAC7E,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1C,MAAM,CAAC,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,CAAC,OAAO,OAAO,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,CAAC,OAAO,OAAO,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClE,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACjE,MAAM,CAAC,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC"}

package/dist/server/command-resolution.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command-resolution.test.d.ts.map

package/dist/server/command-resolution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-resolution.test.d.ts","sourceRoot":"","sources":["../../src/server/command-resolution.test.ts"],"names":[],"mappings":""}

package/dist/server/command-resolution.test.js

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { expect, test } from "vitest";
+import { HERMES_CLI } from "../shared/constants.js";
+import { resolveHermesCommand } from "./execute.js";
+import { testEnvironment } from "./test.js";
+test("resolveHermesCommand prefers hermesCommand over command", () => {
+    expect(resolveHermesCommand({ hermesCommand: "hermes_maximus", command: "hermes_backup" }))
+        .toBe("hermes_maximus");
+});
+test("resolveHermesCommand falls back to command before default hermes binary", () => {
+    expect(resolveHermesCommand({ command: "hermes_maximus" })).toBe("hermes_maximus");
+    expect(resolveHermesCommand({})).toBe(HERMES_CLI);
+});
+test("testEnvironment accepts config.command when hermesCommand is absent", async () => {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "hermes-command-resolution-"));
+    const cliPath = path.join(tempDir, "fake-hermes");
+    try {
+        await writeFile(cliPath, "#!/bin/sh\necho fake-hermes 1.2.3\n", "utf8");
+        await chmod(cliPath, 0o755);
+        const result = await testEnvironment({
+            companyId: "company-test",
+            adapterType: "hermes_local",
+            config: {
+                command: cliPath,
+            },
+        });
+        expect(result.status).not.toBe("fail");
+        expect(result.checks.some((check) => check.code === "hermes_cli_not_found")).toBe(false);
+        expect(result.checks.some((check) => check.code === "hermes_version" && check.message.includes("fake-hermes 1.2.3"))).toBe(true);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+});
+//# sourceMappingURL=command-resolution.test.js.map

package/dist/server/command-resolution.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-resolution.test.js","sourceRoot":"","sources":["../../src/server/command-resolution.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,IAAI,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACnE,MAAM,CAAC,oBAAoB,CAAC,EAAE,aAAa,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC,CAAC;SACxF,IAAI,CAAC,gBAAgB,CAAC,CAAC;AAC5B,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,yEAAyE,EAAE,GAAG,EAAE;IACnF,MAAM,CAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACnF,MAAM,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACpD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qEAAqE,EAAE,KAAK,IAAI,EAAE;IACrF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,4BAA4B,CAAC,CAAC,CAAC;IACpF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAElD,IAAI,CAAC;QACH,MAAM,SAAS,CACb,OAAO,EACP,qCAAqC,EACrC,MAAM,CACP,CAAC;QACF,MAAM,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAE5B,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;YACnC,SAAS,EAAE,cAAc;YACzB,WAAW,EAAE,cAAc;YAC3B,MAAM,EAAE;gBACN,OAAO,EAAE,OAAO;aACjB;SACF,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzF,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CACvB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,gBAAgB,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAC1F,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/server/detect-model.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Detect the current model and provider from the user's Hermes config.
+ *
+ * Reads ~/.hermes/config.yaml and extracts the default model,
+ * provider, base_url, api_key presence, and api_mode settings.
+ *
+ * Also provides provider resolution logic that merges explicit config,
+ * Hermes config detection, and model-name prefix inference.
+ */
+export interface DetectedModel {
+    /** Model name from config (e.g. "gpt-5.4", "anthropic/claude-sonnet-4") */
+    model: string;
+    /** Provider name from config (e.g. "copilot", "zai"). May be empty. */
+    provider: string;
+    /** Base URL override from config (e.g. "https://api.githubcopilot.com"). May be empty. */
+    baseUrl: string;
+    /** Whether Hermes config includes a non-empty API key. */
+    hasApiKey: boolean;
+    /** API mode from config (e.g. "chat_completions", "codex_responses"). May be empty. */
+    apiMode: string;
+    /** Where the detection came from */
+    source: "config";
+}
+/**
+ * Read the Hermes config file and extract the default model config.
+ */
+export declare function detectModel(configPath?: string): Promise<DetectedModel | null>;
+/**
+ * Parse model.default, model.provider, model.base_url, model.api_key, and model.api_mode
+ * from raw YAML content. Uses simple regex parsing to avoid a YAML dependency.
+ */
+export declare function parseModelFromConfig(content: string): DetectedModel | null;
+/**
+ * Infer a provider from the model name using prefix-based hints.
+ *
+ * For example:
+ *   "gpt-5.4"       → "copilot"
+ *   "claude-sonnet-4" → "anthropic"
+ *   "glm-5-turbo"   → "zai"
+ *
+ * Returns undefined if no hint matches (caller should fall back to "auto").
+ */
+export declare function inferProviderFromModel(model: string): string | undefined;
+/**
+ * Resolve the correct provider for a model, using a priority chain:
+ *
+ *   1. Explicit provider from adapterConfig (highest priority — user override)
+ *   2. Provider from Hermes config file — ONLY if the config model matches
+ *      the requested model (otherwise the config provider is for a different model)
+ *   3. If Hermes config matches the requested model but uses runtime settings that
+ *      the adapter cannot represent directly, return "auto" and let Hermes resolve it itself
+ *   4. Provider inferred from model name prefix
+ *   5. "auto" (let Hermes figure it out — lowest priority)
+ *
+ * Always returns a valid provider string.
+ * The `resolvedFrom` field indicates which source was used, useful for logging.
+ */
+export declare function resolveProvider(options: {
+    /** Explicit provider from adapterConfig (user override) */
+    explicitProvider?: string | null;
+    /** Provider detected from Hermes config file */
+    detectedProvider?: string;
+    /** Model name from Hermes config file (to check consistency) */
+    detectedModel?: string;
+    /** Base URL detected from Hermes config file */
+    detectedBaseUrl?: string;
+    /** Whether Hermes config includes a non-empty API key */
+    detectedHasApiKey?: boolean;
+    /** API mode detected from Hermes config file */
+    detectedApiMode?: string;
+    /** Model name to infer from if no explicit/detected provider */
+    model?: string;
+}): {
+    provider: string;
+    resolvedFrom: string;
+};
+//# sourceMappingURL=detect-model.d.ts.map

package/dist/server/detect-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-model.d.ts","sourceRoot":"","sources":["../../src/server/detect-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA2C1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAaxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAiE7C"}