Skip to content

The open-source app everyone uses to manage agents at work

[codex] Add built-in Hermes adapters (#8543)

Dottafd2f82ac5bba
diff --git a/AGENTS.md b/AGENTS.md
index 52bc6c0a57..ddefe527d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -181,18 +181,19 @@ A change is done when all are true:
## 11. Fork-Specific: HenkDz/paperclip
-This is a fork of `paperclipai/paperclip` with QoL patches and an **external-only** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
+This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
### Branch Strategy
-- `feat/externalize-hermes-adapter` → core has **no** `hermes-paperclip-adapter` dependency and **no** built-in `hermes_local` registration. Install Hermes via the Adapter Plugin manager (`@henkey/hermes-paperclip-adapter` or a `file:` path).
-- Older fork branches may still document built-in Hermes; treat this file as authoritative for the externalize branch.
+- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.
+- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.
-### Hermes (plugin only)
+### Hermes (built-in)
-- Register through **Board → Adapter manager** (same as Droid). Type remains `hermes_local` once the package is loaded.
-- UI uses generic **config-schema** + **ui-parser.js** from the package — no Hermes imports in `server/` or `ui/` source.
-- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` for local dev of the adapter repo.
+- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.
+- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.
+- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.
+- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.
### Local Dev
@@ -217,5 +218,5 @@ PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See roo
- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
-- Built-in UI adapters can shadow external plugin parsers — remove built-in when fully externalizing
-- Reference external adapters: Hermes (`@henkey/hermes-paperclip-adapter` or `file:`) and Droid (npm)
+- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.
+- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.
diff --git a/Dockerfile b/Dockerfile
index cc503d98b6..a6631b71f5 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -31,6 +31,8 @@ COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/
COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
COPY packages/adapters/grok-local/package.json packages/adapters/grok-local/
+COPY packages/adapters/hermes/package.json packages/adapters/hermes/
+COPY packages/adapters/hermes-gateway/package.json packages/adapters/hermes-gateway/
COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
diff --git a/cli/esbuild.config.mjs b/cli/esbuild.config.mjs
index 7976b7c9cd..c92ea4f06f 100644
--- a/cli/esbuild.config.mjs
+++ b/cli/esbuild.config.mjs
@@ -21,6 +21,8 @@ const workspacePaths = [
"packages/adapter-utils",
"packages/adapters/claude-local",
"packages/adapters/codex-local",
+ "packages/adapters/hermes-gateway",
+ "packages/adapters/hermes",
"packages/adapters/openclaw-gateway",
];
diff --git a/cli/package.json b/cli/package.json
index ed894750eb..256291c2ef 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -51,6 +51,7 @@
"@paperclipai/db": "workspace:*",
"@paperclipai/server": "workspace:*",
"@paperclipai/shared": "workspace:*",
+ "@paperclipai/hermes-paperclip-adapter": "workspace:*",
"drizzle-orm": "0.45.2",
"dotenv": "^17.0.1",
"commander": "^13.1.0",
diff --git a/cli/src/__tests__/token.test.ts b/cli/src/__tests__/token.test.ts
index 02d53fe1e7..0242427d44 100644
--- a/cli/src/__tests__/token.test.ts
+++ b/cli/src/__tests__/token.test.ts
@@ -70,7 +70,10 @@ describe("token commands", () => {
expect(fetchMock.mock.calls[0]?.[0]).toBe(`http://localhost:3100/api/agents/worker?companyId=${COMPANY_ID}`);
expect(fetchMock.mock.calls[1]?.[0]).toBe(`http://localhost:3100/api/agents/${AGENT_ID}/keys`);
- expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({ name: "external-worker" });
+ expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({
+ name: "external-worker",
+ scope: { kind: "standard" },
+ });
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
agentId: AGENT_ID,
companyId: COMPANY_ID,
diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.ts
index 31dfe0d0af..260a45d6a3 100644
--- a/cli/src/adapters/registry.ts
+++ b/cli/src/adapters/registry.ts
@@ -6,6 +6,8 @@ import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";
import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
import { printGrokStreamEvent } from "@paperclipai/adapter-grok-local/cli";
+import { formatStdoutEvent as printHermesGatewayStreamEvent } from "@paperclipai/hermes-paperclip-adapter/gateway/cli";
+import { printHermesStreamEvent } from "@paperclipai/hermes-paperclip-adapter/cli";
import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";
@@ -57,6 +59,16 @@ const grokLocalCLIAdapter: CLIAdapterModule = {
formatStdoutEvent: printGrokStreamEvent,
};
+const hermesGatewayCLIAdapter: CLIAdapterModule = {
+ type: "hermes_gateway",
+ formatStdoutEvent: printHermesGatewayStreamEvent,
+};
+
+const hermesLocalCLIAdapter: CLIAdapterModule = {
+ type: "hermes_local",
+ formatStdoutEvent: printHermesStreamEvent,
+};
+
const openclawGatewayCLIAdapter: CLIAdapterModule = {
type: "openclaw_gateway",
formatStdoutEvent: printOpenClawGatewayStreamEvent,
@@ -73,6 +85,8 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
cursorCloudCLIAdapter,
geminiLocalCLIAdapter,
grokLocalCLIAdapter,
+ hermesGatewayCLIAdapter,
+ hermesLocalCLIAdapter,
openclawGatewayCLIAdapter,
processCLIAdapter,
httpCLIAdapter,
diff --git a/doc/CLI.md b/doc/CLI.md
index 2b4bfe6fc5..fd190a0e80 100644
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -688,6 +688,13 @@ pnpm paperclipai llm agent-configuration:adapter <adapter-type>
pnpm paperclipai llm agent-icons
```
+Hermes gateway uses the generic invite/join commands above rather than
+`openclaw invite-prompt`. Create an agent invite, read
+`invite onboarding:text`, submit a join request with
+`adapterType: "hermes_gateway"` and `agentDefaultsPayload.apiBaseUrl` /
+`agentDefaultsPayload.apiKey`, then approve and claim the key with the `join`
+commands. See [HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md).
+
## Adapter, Asset, And Skill Commands
```sh
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index f15c244098..aa47541b0a 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -710,6 +710,13 @@ The board UI generates agent onboarding prompts from the add-agent modal (`+` in
- `GET /api/skills/index` lists available skill documents.
- `GET /api/skills/paperclip` returns the Paperclip heartbeat skill markdown.
+Hermes gateway agents use this same generic agent invite flow with
+`adapterType=hermes_gateway` and `agentDefaultsPayload.apiBaseUrl` /
+`agentDefaultsPayload.apiKey`. See
+[HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md) for the full
+operator path, including Hermes credentials, invite approval, key claim, and
+fresh-state Docker smoke setup.
+
## OpenClaw Join Smoke Test
Run the end-to-end OpenClaw join smoke harness:
diff --git a/doc/HERMES_GATEWAY_ONBOARDING.md b/doc/HERMES_GATEWAY_ONBOARDING.md
new file mode 100644
index 0000000000..58b9dfc5b0
--- /dev/null
+++ b/doc/HERMES_GATEWAY_ONBOARDING.md
@@ -0,0 +1,193 @@
+# Hermes Gateway Onboarding
+
+Use this guide when a Hermes runtime should join Paperclip as an external
+`hermes_gateway` employee. This mirrors the OpenClaw gateway invite path, but
+Hermes uses the generic agent invite/onboarding flow instead of the
+OpenClaw-specific invite prompt endpoint.
+
+## Choose The Adapter
+
+Paperclip ships both Hermes adapters as built-ins:
+
+- `hermes_local` runs the local `hermes` CLI as a child process on the
+ Paperclip host.
+- `hermes_gateway` calls an already-running Hermes API server over HTTP/SSE.
+
+No Adapter manager installation is required for normal use. Adapter manager is
+only needed when you intentionally install an external
+`@paperclipai/hermes-paperclip-adapter` package to override or shadow a built-in
+adapter while developing the Hermes package. If the external override is paused
+or removed, Paperclip restores the built-in `hermes_local` / `hermes_gateway`
+adapter.
+
+## Required Credentials
+
+Keep these credentials distinct:
+
+- Hermes inference provider key: set at least one provider key for Hermes, such
+ as `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+ `GEMINI_API_KEY`, `GOOGLE_API_KEY`, or `MISTRAL_API_KEY`.
+- Hermes gateway key: set `API_SERVER_KEY` before starting Hermes. Paperclip
+ stores the same value as `agentDefaultsPayload.apiKey` so it can call Hermes.
+- Paperclip agent key: created after the board approves the join request and
+ claimed once by the Hermes agent. Hermes uses this key as
+ `PAPERCLIP_API_KEY` when it calls Paperclip.
+
+Do not reuse the Hermes gateway key as the Paperclip agent key. The Hermes
+gateway key authenticates Paperclip-to-Hermes traffic; the claimed Paperclip key
+authenticates Hermes-to-Paperclip traffic.
+
+## Start Hermes Gateway
+
+Install and configure Hermes first:
+
+```sh
+pip install hermes-agent
+export OPENROUTER_API_KEY='<provider-key>'
+export API_SERVER_KEY='<random-gateway-key>'
+API_SERVER_ENABLED=true hermes gateway run --replace --accept-hooks
+```
+
+The default Hermes API server port is `8642`. For local loopback testing,
+Paperclip can usually store `http://127.0.0.1:8642` as the gateway URL. For
+Docker, LAN, tailnet, or reverse-proxy setups, use a URL reachable by the
+Paperclip server process.
+
+Plain HTTP is accepted for loopback. Non-loopback HTTP is denied by default in
+the join flow; use HTTPS for real remote gateways. For private local
+development only, the join payload can set
+`dangerouslyAllowInsecureRemoteHttp: true`, and the smoke scripts expose the
+same escape hatch as `HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1`.
+
+## Invite From Paperclip
+
+In the board UI:
+
+1. Open the target company.
+2. Use the add-agent button in the agent sidebar.
+3. Generate an agent onboarding prompt/invite.
+4. Give the generated onboarding text to the Hermes runtime.
+
+The UI prompt points Hermes at the same machine-readable onboarding endpoints:
+
+- `GET /api/invites/:token`
+- `GET /api/invites/:token/onboarding`
+- `GET /api/invites/:token/onboarding.txt`
+- `GET /api/skills/index`
+- `GET /api/skills/paperclip`
+
+For CLI-driven setup, create and inspect the invite directly:
+
+```sh
+pnpm paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'
+pnpm paperclipai invite show <token>
+pnpm paperclipai invite onboarding:text <token>
+```
+
+Hermes should submit a join request with `requestType: "agent"` and
+`adapterType: "hermes_gateway"`:
+
+```json
+{
+ "requestType": "agent",
+ "agentName": "Hermes Gateway Engineer",
+ "adapterType": "hermes_gateway",
+ "capabilities": "Hermes gateway agent with code, browser, web, and file tools.",
+ "agentDefaultsPayload": {
+ "apiBaseUrl": "http://127.0.0.1:8642",
+ "apiKey": "<same-value-as-API_SERVER_KEY>",
+ "paperclipApiUrl": "http://127.0.0.1:3100",
+ "sessionKeyStrategy": "issue"
+ }
+}
+```
+
+Important URL roles:
+
+- `agentDefaultsPayload.apiBaseUrl` is the Hermes gateway URL that Paperclip
+ calls.
+- `agentDefaultsPayload.paperclipApiUrl` is the Paperclip base URL that Hermes
+ can call after approval and key claim.
+- `PAPERCLIP_API_URL` / `PAPERCLIP_API_KEY` are injected runtime values for
+ Hermes-originated Paperclip API calls after the agent is approved.
+
+## Approve And Claim
+
+After Hermes submits the join request:
+
+1. In Paperclip, review the pending agent join request.
+2. Approve it from the board UI, or use:
+
+ ```sh
+ pnpm paperclipai join list --company-id <company-id> --status pending_approval
+ pnpm paperclipai join approve <request-id> --company-id <company-id>
+ ```
+
+3. Hermes claims the one-time agent API key:
+
+ ```sh
+ pnpm paperclipai join claim-key <request-id> --claim-secret <secret>
+ ```
+
+4. Store the claimed Paperclip key in Hermes runtime state or secrets. The claim
+ secret and claimed key are sensitive and should not be pasted into issue
+ comments, logs, or prompt text.
+
+Once the key is claimed, create an issue assigned to the new Hermes gateway
+agent and wake it through the normal Paperclip heartbeat path.
+
+## Local Fresh-State Smoke
+
+For a fresh Docker-backed Hermes gateway and end-to-end Paperclip join/run
+verification, use:
+
+```sh
+PAPERCLIP_API_URL=http://127.0.0.1:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+pnpm smoke:hermes-gateway-e2e
+```
+
+The E2E smoke:
+
+- builds a fresh Hermes gateway container
+- seeds a minimal non-secret Hermes model config
+- passes provider keys from the host environment without printing them
+- verifies Hermes `/health`, `/v1/capabilities`, `/v1/runs`, SSE, and stop
+- creates and approves a Paperclip agent-only invite
+- joins as `hermes_gateway`
+- wakes the agent on a smoke issue
+- removes Paperclip and Docker test state on success
+
+If a Hermes gateway is already running and you only need to validate the invite
+and stored adapter config, use the join-only helper:
+
+```sh
+API_SERVER_ENABLED=true API_SERVER_KEY='<gateway-key>' hermes gateway run --replace --accept-hooks
+
+PAPERCLIP_API_URL=http://127.0.0.1:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642 \
+HERMES_GATEWAY_API_KEY='<gateway-key>' \
+pnpm smoke:hermes-gateway-join
+```
+
+See [HERMES_GATEWAY_SMOKE.md](./HERMES_GATEWAY_SMOKE.md) for Docker Desktop,
+Linux, same-network Docker, LAN/private-network, and reverse-proxy/TLS examples.
+
+## Install Entry Points
+
+Use these entry points depending on who is driving setup:
+
+- Board UI: add-agent button in the agent sidebar, then generate the agent
+ onboarding prompt.
+- Invite API: `GET /api/invites/:token/onboarding.txt` for the generated
+ llm.txt-style setup instructions.
+- CLI invite flow: `pnpm paperclipai invite create`, `invite show`,
+ `invite onboarding:text`, `join approve`, and `join claim-key`.
+- Smoke helpers: `pnpm smoke:hermes-gateway-e2e` for fresh-state Docker
+ verification and `pnpm smoke:hermes-gateway-join` for an already-running
+ gateway.
+- Adapter development override: Adapter manager can install
+ `@paperclipai/hermes-paperclip-adapter` as an external override, but normal
+ operators should use the built-in `hermes_local` and `hermes_gateway`
+ adapters.
diff --git a/doc/HERMES_GATEWAY_SMOKE.md b/doc/HERMES_GATEWAY_SMOKE.md
new file mode 100644
index 0000000000..a85026f241
--- /dev/null
+++ b/doc/HERMES_GATEWAY_SMOKE.md
@@ -0,0 +1,168 @@
+# Hermes Gateway Smoke
+
+This smoke validates the built-in `hermes_gateway` adapter against a fresh
+Hermes gateway. Keep real Hermes execution manual/local: the CI-safe checks only
+lint shell syntax and focused helper behavior.
+
+For the operator-facing install and invite flow, see
+[HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md). This smoke guide
+focuses on verification commands and network modes.
+
+## CI-safe validation
+
+Run these from the repo root:
+
+```sh
+bash -n scripts/smoke/hermes-gateway-join.sh scripts/smoke/hermes-gateway-e2e.sh
+pnpm test:hermes-gateway-smoke
+```
+
+`pnpm test:hermes-gateway-smoke` does not start Docker, Hermes, or Paperclip. It
+checks script help output, shell syntax, redaction helpers, URL slash handling,
+and the non-loopback HTTP guard.
+
+## Secrets and cleanup
+
+- Set the Hermes gateway key with `HERMES_GATEWAY_API_KEY` or `API_SERVER_KEY`.
+ The scripts print only `sha256=<prefix>` and length for secret identifiers.
+- Set at least one Hermes inference provider key on the host before running the
+ Docker E2E smoke. The script passes through set values for
+ `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
+ `GOOGLE_API_KEY`, and `MISTRAL_API_KEY`, and logs only the provider env var
+ names.
+- To pin the fresh Hermes container to a known non-secret model config, set
+ `HERMES_SMOKE_MODEL_PROVIDER`, `HERMES_SMOKE_MODEL_DEFAULT`, and optionally
+ `HERMES_SMOKE_MODEL_BASE_URL`. For example, OpenRouter GLM:
+
+ ```sh
+ HERMES_SMOKE_MODEL_PROVIDER=openrouter \
+ HERMES_SMOKE_MODEL_DEFAULT=z-ai/glm-5.2 \
+ HERMES_SMOKE_MODEL_BASE_URL=https://openrouter.ai/api/v1 \
+ pnpm smoke:hermes-gateway-e2e
+ ```
+
+ This writes only `model`, `providers: {}`, and
+ `command_allowlist: [execute_code]` into the temporary Hermes home. Provider
+ keys still come from environment variables and are redacted from diagnostics.
+- The E2E helper always seeds `command_allowlist: [execute_code]` in the fresh
+ Hermes config so non-interactive gateway/API runs do not wait for a manual
+ execute-code approval prompt. Do not copy a host `~/.hermes` directory into
+ the container to solve approval or provider setup.
+- Board/operator auth is required through `PAPERCLIP_AUTH_HEADER`,
+ `PAPERCLIP_COOKIE`, or a board-capable `PAPERCLIP_API_KEY`.
+- Diagnostic files are redacted before they are written, except the join output
+ file intentionally contains the claimed Paperclip agent key and is written
+ `chmod 600`.
+- Successful runs remove the smoke issue, smoke agent, join request, Docker
+ container, and per-run local state.
+- Set `HERMES_SMOKE_KEEP=1` to preserve diagnostics, state, and the container.
+ Failed runs automatically preserve them and print the retained paths.
+
+## URL model
+
+The smoke has three URLs because different processes need different routes:
+
+- `PAPERCLIP_API_URL`: Paperclip URL used by the operator shell.
+- `PAPERCLIP_API_URL_FOR_HERMES`: Paperclip URL used from inside the Hermes
+ container or remote Hermes host.
+- `HERMES_GATEWAY_API_BASE_URL`: Hermes gateway URL stored on the Paperclip
+ adapter, reachable by the Paperclip server.
+- `HERMES_GATEWAY_PROBE_URL`: Hermes gateway URL used by the operator shell for
+ direct `/health`, `/v1/capabilities`, `/v1/runs`, and SSE checks.
+
+Loopback HTTP gateway URLs are allowed. Non-loopback HTTP gateway URLs require
+`HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1` and should only be used on local/private
+development networks. Use HTTPS for real remote gateways.
+
+## Docker Desktop or Linux host Paperclip
+
+Use this when Paperclip runs on the host at `127.0.0.1:3100` and Docker can
+reach the host through `host.docker.internal`.
+
+```sh
+PAPERCLIP_API_URL=http://127.0.0.1:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+pnpm smoke:hermes-gateway-e2e
+```
+
+Linux uses `--add-host=host.docker.internal:host-gateway` by default through
+`HERMES_DOCKER_ADD_HOST=1`. If your Docker setup already provides
+`host.docker.internal`, the same command works.
+
+## Same Docker network as Paperclip
+
+Use this when Paperclip is a container on a Docker network and the Hermes smoke
+container should be reachable by container DNS. The operator shell still probes
+the host-published loopback port.
+
+```sh
+PAPERCLIP_API_URL=http://127.0.0.1:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+HERMES_CONTAINER_NAME=paperclip-hermes-gateway-smoke \
+HERMES_SMOKE_NETWORK=paperclip_default \
+HERMES_DOCKER_ADD_HOST=0 \
+HERMES_GATEWAY_API_BASE_URL=http://paperclip-hermes-gateway-smoke:8642 \
+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \
+PAPERCLIP_API_URL_FOR_HERMES=http://paperclip:3100 \
+HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 \
+pnpm smoke:hermes-gateway-e2e
+```
+
+Change `paperclip_default` and `paperclip` to your Compose network and service
+name. The unsafe HTTP flag is required because Paperclip stores a non-loopback
+`http://` gateway URL for private Docker DNS.
+
+## LAN or private-network Paperclip
+
+Use this when Paperclip is exposed on a private IP or tailnet address and the
+Hermes container can reach that address.
+
+```sh
+PAPERCLIP_API_URL=http://192.168.1.20:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+PAPERCLIP_API_URL_FOR_HERMES=http://192.168.1.20:3100 \
+HERMES_GATEWAY_API_BASE_URL=http://192.168.1.20:8642 \
+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \
+HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 \
+pnpm smoke:hermes-gateway-e2e
+```
+
+Only use this on a trusted private network. For anything beyond local/private
+development, put the Hermes gateway behind TLS and use the reverse-proxy mode.
+
+## Reverse proxy / TLS
+
+Use this when Paperclip should talk to Hermes through a TLS hostname. The smoke
+container still publishes a local port, and your reverse proxy forwards the TLS
+hostname to that port.
+
+```sh
+PAPERCLIP_API_URL=https://paperclip.example.com \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+PAPERCLIP_API_URL_FOR_HERMES=https://paperclip.example.com \
+HERMES_GATEWAY_API_BASE_URL=https://hermes-gateway.example.com \
+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \
+pnpm smoke:hermes-gateway-e2e
+```
+
+No unsafe HTTP escape hatch is needed because the adapter URL is HTTPS.
+
+## Join-only validation
+
+If a Hermes gateway is already running, use the join helper without building or
+starting a Docker container:
+
+```sh
+API_SERVER_ENABLED=true API_SERVER_KEY='<gateway-key>' hermes gateway run --replace --accept-hooks
+
+PAPERCLIP_API_URL=http://127.0.0.1:3100 \
+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \
+HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642 \
+HERMES_GATEWAY_API_KEY='<gateway-key>' \
+pnpm smoke:hermes-gateway-join
+```
+
+For non-loopback private HTTP join-only runs, set
+`HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1`. For Docker DNS or reverse-proxy setups,
+set `HERMES_GATEWAY_PROBE_URL` to the URL reachable from the operator shell and
+`HERMES_GATEWAY_API_BASE_URL` to the URL Paperclip should store on the adapter.
diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md
index c430d3473a..11582e9718 100644
--- a/doc/PUBLISHING.md
+++ b/doc/PUBLISHING.md
@@ -209,8 +209,12 @@ The helper script:
- checks that the package does not already exist on npm
- builds the target package unless `--skip-build` is passed
-- runs `npm pack --dry-run` in the package directory
-- only runs the real `npm publish --access public` when `--publish --otp <code>` is provided
+- runs `pnpm publish <package-dir> --dry-run --no-git-checks --access public` from the repo root
+- only runs the real `pnpm publish <package-dir> --no-git-checks --access public` when `--publish --otp <code>` is provided
+
+The helper intentionally uses `pnpm publish` instead of `npm publish` so workspace
+dependencies and `publishConfig` export fields are normalized before the package
+is sent to the registry.
For the real `--publish` step, the maintainer machine must already be authenticated to npm.
If `npm whoami` returns `401`, first run `npm logout --registry=https://registry.npmjs.org/` to clear any stale local auth, then run `npm login` or `npm adduser` locally as an npm org member, and finally rerun the helper.
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index e3246ed6da..44ff0bb037 100644
--- a/doc/SPEC-implementation.md
+++ b/doc/SPEC-implementation.md
@@ -153,7 +153,7 @@ Invariant: every business record belongs to exactly one company.
- `status` enum: `active | paused | idle | running | error | pending_approval | terminated`
- `reports_to` uuid fk `agents.id` null
- `capabilities` text null
-- `adapter_type` text; built-ins include `process`, `http`, `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `pi_local`, `cursor`, and `openclaw_gateway`
+- `adapter_type` text; built-ins include `process`, `http`, `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `pi_local`, `cursor`, `hermes_local`, `hermes_gateway`, and `openclaw_gateway`
- `adapter_config` jsonb not null
- `runtime_config` jsonb not null default `{}`; may include Paperclip runtime policy such as `modelProfiles.cheap.adapterConfig` for an optional low-cost model lane that does not change the primary adapter config
- `default_environment_id` uuid fk `environments.id` null
diff --git a/docker/hermes-gateway-smoke/Dockerfile b/docker/hermes-gateway-smoke/Dockerfile
new file mode 100644
index 0000000000..5939c7df6e
--- /dev/null
+++ b/docker/hermes-gateway-smoke/Dockerfile
@@ -0,0 +1,52 @@
+# syntax=docker/dockerfile:1.6
+ARG HERMES_VERSION=0.17.0
+FROM node:22-bookworm-slim
+
+ARG HERMES_VERSION
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+ bash \
+ ca-certificates \
+ curl \
+ git \
+ jq \
+ python3 \
+ python3-pip \
+ tini \
+ && rm -rf /var/lib/apt/lists/*
+
+# The npm package is a pinned bridge that exposes the `hermes` binary. Install
+# the matching Python package globally first so the non-root runtime user can
+# import the upstream Hermes modules at container start.
+RUN python3 -m pip install --break-system-packages --no-cache-dir "hermes-agent[anthropic]==${HERMES_VERSION}" "aiohttp==3.13.4" \
+ && rm -f /usr/local/bin/hermes /usr/local/bin/hermes-agent \
+ && npm install -g --ignore-scripts "hermes-agent@${HERMES_VERSION}" \
+ && python3 -c "import hermes_cli.main" \
+ && command -v hermes >/dev/null
+
+RUN useradd --create-home --shell /bin/bash --uid 10001 hermes \
+ && mkdir -p /home/hermes/.hermes /home/hermes/workspace \
+ && chown -R hermes:hermes /home/hermes
+
+COPY entrypoint.sh /usr/local/bin/hermes-gateway-entrypoint
+RUN chmod 0755 /usr/local/bin/hermes-gateway-entrypoint
+
+USER hermes
+WORKDIR /home/hermes/workspace
+
+ENV HOME=/home/hermes \
+ HERMES_HOME=/home/hermes/.hermes \
+ XDG_CONFIG_HOME=/home/hermes/.config \
+ XDG_CACHE_HOME=/home/hermes/.cache \
+ XDG_DATA_HOME=/home/hermes/.local/share \
+ API_SERVER_ENABLED=true \
+ API_SERVER_HOST=0.0.0.0 \
+ API_SERVER_PORT=8642 \
+ NO_COLOR=1
+
+EXPOSE 8642
+
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/hermes-gateway-entrypoint"]
diff --git a/docker/hermes-gateway-smoke/entrypoint.sh b/docker/hermes-gateway-smoke/entrypoint.sh
new file mode 100755
index 0000000000..a1496afa8c
--- /dev/null
+++ b/docker/hermes-gateway-smoke/entrypoint.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() {
+ echo "[hermes-gateway-smoke] $*"
+}
+
+hash_prefix() {
+ local value="$1"
+ if command -v sha256sum >/dev/null 2>&1; then
+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'
+ elif command -v shasum >/dev/null 2>&1; then
+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'
+ else
+ printf "unavailable"
+ fi
+}
+
+generate_key() {
+ node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))'
+}
+
+export HOME="${HOME:-/home/hermes}"
+export HERMES_HOME="${HERMES_HOME:-${HOME}/.hermes}"
+export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-${HOME}/.config}"
+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-${HOME}/.cache}"
+export XDG_DATA_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}"
+export API_SERVER_ENABLED="${API_SERVER_ENABLED:-true}"
+export API_SERVER_HOST="${API_SERVER_HOST:-0.0.0.0}"
+export API_SERVER_PORT="${API_SERVER_PORT:-8642}"
+export NO_COLOR="${NO_COLOR:-1}"
+
+if [[ "${API_SERVER_ENABLED}" != "true" ]]; then
+ log "forcing API_SERVER_ENABLED=true for gateway smoke"
+ export API_SERVER_ENABLED=true
+fi
+
+if [[ -z "${API_SERVER_KEY:-}" ]]; then
+ API_SERVER_KEY="$(generate_key)"
+ export API_SERVER_KEY
+ log "generated API_SERVER_KEY sha256=$(hash_prefix "$API_SERVER_KEY") len=${#API_SERVER_KEY}"
+else
+ log "using provided API_SERVER_KEY sha256=$(hash_prefix "$API_SERVER_KEY") len=${#API_SERVER_KEY}"
+fi
+
+mkdir -p "$HERMES_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_DATA_HOME" "$HOME/workspace"
+chmod 0700 "$HERMES_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_DATA_HOME" || true
+
+log "HOME=${HOME}"
+log "HERMES_HOME=${HERMES_HOME}"
+log "workspace=$(pwd)"
+log "API_SERVER_HOST=${API_SERVER_HOST}"
+log "API_SERVER_PORT=${API_SERVER_PORT}"
+log "state listing hash=$(find "$HERMES_HOME" -maxdepth 2 -type f -print 2>/dev/null | sort | sha256sum | awk '{print substr($1,1,12)}')"
+
+exec hermes gateway run --replace --accept-hooks "$@"
diff --git a/docs/adapters/external-adapters.md b/docs/adapters/external-adapters.md
index 3c814fc9ab..522679f667 100644
--- a/docs/adapters/external-adapters.md
+++ b/docs/adapters/external-adapters.md
@@ -15,6 +15,22 @@ Paperclip supports external adapter plugins that can be installed from npm packa
| Distribution | Ships with Paperclip | Published to npm or linked via `file:` |
| Updates | Requires Paperclip release | Independent versioning |
+### Built-in Hermes compatibility note
+
+Hermes is built in with two stable adapter type keys:
+
+- `hermes_local` starts the local Hermes CLI from
+ `@paperclipai/hermes-paperclip-adapter`.
+- `hermes_gateway` calls an already-running Hermes API server through
+ `@paperclipai/hermes-paperclip-adapter/gateway`.
+
+The legacy `@paperclipai/adapter-hermes-gateway` package is a deprecated
+compatibility shim for one release. It preserves the old gateway exports while
+forwarding to the unified Hermes package. New external override packages should
+depend on or link `@paperclipai/hermes-paperclip-adapter` and declare the type
+they override (`hermes_local` or `hermes_gateway`); the type keys did not
+change.
+
## Quick Start
### Minimal Package Structure
diff --git a/docs/adapters/overview.md b/docs/adapters/overview.md
index dfb4b21fb3..a2f62b54bb 100644
--- a/docs/adapters/overview.md
+++ b/docs/adapters/overview.md
@@ -24,11 +24,25 @@ 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`) |
+| Hermes Local | `hermes_local` | Runs the local Hermes CLI through `@paperclipai/hermes-paperclip-adapter` |
+| Hermes Gateway | `hermes_gateway` | Calls an already-running Hermes API server through `@paperclipai/hermes-paperclip-adapter/gateway` |
| 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 |
+### Hermes local vs gateway
+
+Use `hermes_local` when Paperclip should start the local `hermes` CLI on the
+same host for each heartbeat. Use `hermes_gateway` when Hermes is already
+running as an HTTP/SSE API server and Paperclip should call that server instead
+of spawning a process. Both type keys are stable built-ins.
+
+The unified Hermes package owns both built-in adapters. The older
+`@paperclipai/adapter-hermes-gateway` package remains only as a deprecated
+compatibility shim that re-exports the gateway entrypoints for one release.
+New plugin overrides should target `@paperclipai/hermes-paperclip-adapter` and
+set the desired type key (`hermes_local` or `hermes_gateway`).
+
### External (plugin) adapters
These adapters ship as standalone npm packages and are installed via the plugin system:
@@ -79,8 +93,9 @@ my-adapter/
## Choosing an Adapter
- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, or install `droid_local` as an external plugin
+- **Need Hermes on another host or already running as a service?** Use `hermes_gateway`
- **Need to run a script or command?** Use `process`
-- **Need to call an external service?** Use `http`
+- **Need to call a custom external service?** Use `http`
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter) or [build an external adapter plugin](/adapters/external-adapters)
## UI Parser Contract
diff --git a/docs/agents-runtime.md b/docs/agents-runtime.md
index 81bbda7ca1..252fa3d0a2 100644
--- a/docs/agents-runtime.md
+++ b/docs/agents-runtime.md
@@ -39,7 +39,8 @@ 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`)
+- `hermes_local`: starts your local `hermes` CLI through `@paperclipai/hermes-paperclip-adapter`
+- `hermes_gateway`: calls an already-running Hermes API server through `@paperclipai/hermes-paperclip-adapter/gateway`
- `openclaw_gateway`: connects to an OpenClaw gateway endpoint
- `process`: generic shell command adapter
- `http`: calls an external HTTP endpoint
@@ -48,7 +49,7 @@ External plugin adapters (install via the adapter manager or API):
- `droid_local`: runs your local Factory Droid CLI (`@henkey/droid-paperclip-adapter`)
-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.
+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. For `hermes_gateway`, Paperclip assumes the Hermes API server is already running, reachable from the Paperclip server, and configured with an API key. The older `@paperclipai/adapter-hermes-gateway` npm package is only a deprecated compatibility shim; the adapter type remains `hermes_gateway`.
## 3.2 Runtime behavior
@@ -177,7 +178,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`, `hermes_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` are also available via the adapter manager.
+1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `hermes_gateway`, `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/docs/guides/board-operator/managing-agents.md b/docs/guides/board-operator/managing-agents.md
index 4850222d0a..1ada4ec87e 100644
--- a/docs/guides/board-operator/managing-agents.md
+++ b/docs/guides/board-operator/managing-agents.md
@@ -28,10 +28,15 @@ Create agents from the Agents page. Each agent requires:
- **Capabilities** — short description of what this agent does
Common adapter choices:
-- `claude_local` / `codex_local` / `opencode_local` for local coding agents
-- `openclaw_gateway` / `http` for webhook-based external agents
+- `claude_local` / `codex_local` / `opencode_local` / `hermes_local` for local coding agents
+- `hermes_gateway` / `openclaw_gateway` / `http` for webhook-based external agents
- `process` for generic local command execution
+Use `hermes_local` when Paperclip should start the local Hermes CLI. Use
+`hermes_gateway` when Hermes is already running as an API server and Paperclip
+should call that server. Both are built-in adapter types from the unified
+`@paperclipai/hermes-paperclip-adapter` package.
+
For `opencode_local`, configure an explicit `adapterConfig.model` (`provider/model`).
Paperclip validates the selected model against live `opencode models` output.
diff --git a/package.json b/package.json
index 501b53a34d..75007b518d 100644
--- a/package.json
+++ b/package.json
@@ -38,7 +38,10 @@
"check:tokens": "node scripts/check-forbidden-tokens.mjs",
"check:no-git-push": "node scripts/check-no-git-push.mjs",
"test:check-no-git-push": "node --test scripts/check-no-git-push.test.mjs",
+ "test:hermes-gateway-smoke": "node --test scripts/smoke/hermes-gateway-smoke.test.mjs",
"docs:dev": "cd docs && npx mintlify dev",
+ "smoke:hermes-gateway-join": "./scripts/smoke/hermes-gateway-join.sh",
+ "smoke:hermes-gateway-e2e": "./scripts/smoke/hermes-gateway-e2e.sh",
"smoke:openclaw-join": "./scripts/smoke/openclaw-join.sh",
"smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh",
"smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh",
diff --git a/packages/adapters/hermes-gateway/README.md b/packages/adapters/hermes-gateway/README.md
new file mode 100644
index 0000000000..736930357b
--- /dev/null
+++ b/packages/adapters/hermes-gateway/README.md
@@ -0,0 +1,25 @@
+# Hermes Gateway Adapter Compatibility Shim
+
+`@paperclipai/adapter-hermes-gateway` is a deprecated compatibility shim.
+
+Use `@paperclipai/hermes-paperclip-adapter` for new installs and import gateway
+entrypoints from `@paperclipai/hermes-paperclip-adapter/gateway`. The adapter
+type remains `hermes_gateway`; only package ownership changed.
+
+`hermes_gateway` is for an already-running Hermes API server. It does not start
+the local Hermes CLI. If Paperclip should launch local `hermes chat` as a child
+process, use `hermes_local` from `@paperclipai/hermes-paperclip-adapter`
+instead.
+
+The shim preserves the legacy exports for one release:
+
+- `.`
+- `./server`
+- `./ui`
+- `./cli`
+- `./ui-parser`
+
+These exports forward to the unified Hermes package. Existing
+`@paperclipai/adapter-hermes-gateway` plugin installs should continue to load
+during the compatibility window, but should migrate to
+`@paperclipai/hermes-paperclip-adapter` before the shim is removed.
diff --git a/packages/adapters/hermes-gateway/package.json b/packages/adapters/hermes-gateway/package.json
new file mode 100644
index 0000000000..f9fb40cc3c
--- /dev/null
+++ b/packages/adapters/hermes-gateway/package.json
@@ -0,0 +1,81 @@
+{
+ "name": "@paperclipai/adapter-hermes-gateway",
+ "version": "0.1.0",
+ "description": "Deprecated compatibility shim for Hermes Gateway; use @paperclipai/hermes-paperclip-adapter/gateway",
+ "type": "module",
+ "license": "MIT",
+ "author": "Paperclip",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/paperclipai/paperclip",
+ "directory": "packages/adapters/hermes-gateway"
+ },
+ "bugs": {
+ "url": "https://github.com/paperclipai/paperclip/issues"
+ },
+ "homepage": "https://github.com/paperclipai/paperclip/tree/master/packages/adapters/hermes#readme",
+ "keywords": [
+ "paperclip",
+ "hermes",
+ "gateway",
+ "adapter",
+ "orchestration"
+ ],
+ "exports": {
+ ".": "./src/index.ts",
+ "./server": "./src/server/index.ts",
+ "./ui": "./src/ui/index.ts",
+ "./cli": "./src/cli/index.ts",
+ "./ui-parser": "./ui-parser.cjs"
+ },
+ "paperclip": {
+ "adapterUiParser": "1.0.0"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./server": {
+ "types": "./dist/server/index.d.ts",
+ "import": "./dist/server/index.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./cli": {
+ "types": "./dist/cli/index.d.ts",
+ "import": "./dist/cli/index.js"
+ },
+ "./ui-parser": "./ui-parser.cjs"
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "provenance": true
+ },
+ "files": [
+ "dist",
+ "ui-parser.cjs",
+ "README.md"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run"
+ },
+ "dependencies": {
+ "@paperclipai/hermes-paperclip-adapter": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^22.19.21",
+ "typescript": "^5.7.3",
+ "vitest": "^4.1.8"
+ },
+ "engines": {
+ "node": ">=20.0.0"
+ }
+}
diff --git a/packages/adapters/hermes-gateway/src/cli/index.ts b/packages/adapters/hermes-gateway/src/cli/index.ts
new file mode 100644
index 0000000000..0ecd76a446
--- /dev/null
+++ b/packages/adapters/hermes-gateway/src/cli/index.ts
@@ -0,0 +1 @@
+export { formatStdoutEvent } from "@paperclipai/hermes-paperclip-adapter/gateway/cli";
diff --git a/packages/adapters/hermes-gateway/src/index.ts b/packages/adapters/hermes-gateway/src/index.ts
new file mode 100644
index 0000000000..36e1cdc54f
--- /dev/null
+++ b/packages/adapters/hermes-gateway/src/index.ts
@@ -0,0 +1,7 @@
+export {
+ agentConfigurationDoc,
+ createServerAdapter,
+ label,
+ models,
+ type,
+} from "@paperclipai/hermes-paperclip-adapter/gateway";
diff --git a/packages/adapters/hermes-gateway/src/server/index.ts b/packages/adapters/hermes-gateway/src/server/index.ts
new file mode 100644
index 0000000000..eebc096eb7
--- /dev/null
+++ b/packages/adapters/hermes-gateway/src/server/index.ts
@@ -0,0 +1,9 @@
+export {
+ execute,
+ getConfigSchema,
+ mapFinalResultForTest,
+ parseSseFramesForTest,
+ resolveSessionKey,
+ sessionCodec,
+ testEnvironment,
+} from "@paperclipai/hermes-paperclip-adapter/gateway/server";
diff --git a/packages/adapters/hermes-gateway/src/ui/index.ts b/packages/adapters/hermes-gateway/src/ui/index.ts
new file mode 100644
index 0000000000..1f5105a6e4
--- /dev/null
+++ b/packages/adapters/hermes-gateway/src/ui/index.ts
@@ -0,0 +1 @@
+export { parseStdoutLine } from "@paperclipai/hermes-paperclip-adapter/gateway/ui";
diff --git a/packages/adapters/hermes-gateway/tsconfig.json b/packages/adapters/hermes-gateway/tsconfig.json
new file mode 100644
index 0000000000..8fea361a34
--- /dev/null
+++ b/packages/adapters/hermes-gateway/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "types": ["node"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/adapters/hermes-gateway/ui-parser.cjs b/packages/adapters/hermes-gateway/ui-parser.cjs
new file mode 100644
index 0000000000..9b2e7fa0ce
--- /dev/null
+++ b/packages/adapters/hermes-gateway/ui-parser.cjs
@@ -0,0 +1 @@
+module.exports = require("@paperclipai/hermes-paperclip-adapter/gateway/ui-parser");
diff --git a/packages/adapters/hermes-gateway/vitest.config.ts b/packages/adapters/hermes-gateway/vitest.config.ts
new file mode 100644
index 0000000000..ad7d95889a
--- /dev/null
+++ b/packages/adapters/hermes-gateway/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ exclude: ["dist/**", "node_modules/**"],
+ },
+});
diff --git a/packages/adapters/hermes/LICENSE b/packages/adapters/hermes/LICENSE
new file mode 100644
index 0000000000..5700b99782
--- /dev/null
+++ b/packages/adapters/hermes/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.
diff --git a/packages/adapters/hermes/README.md b/packages/adapters/hermes/README.md
new file mode 100644
index 0000000000..53c4ca3901
--- /dev/null
+++ b/packages/adapters/hermes/README.md
@@ -0,0 +1,335 @@
+# Paperclip Adapters for Hermes Agent
+
+A [Paperclip](https://paperclip.ing) adapter package 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.
+
+This package owns both built-in Hermes adapter types:
+
+- `hermes_local` runs the local Hermes CLI as a child process. The package root exports remain compatible with the original local adapter.
+- `hermes_gateway` calls an already-running Hermes API server over HTTP/SSE. Gateway entrypoints live under the `./gateway` export namespace.
+
+Choose `hermes_local` when Paperclip and Hermes run on the same trusted host
+and Paperclip should start `hermes chat` for each heartbeat. Choose
+`hermes_gateway` when Hermes is already running as an API server, often on
+another host, in Docker, or behind a private-network/TLS endpoint. The adapter
+type keys did not change during package consolidation.
+
+## 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
+
+This package ships with Paperclip core as the built-in `hermes_local` and
+`hermes_gateway` adapters. No Adapter manager installation is required for
+normal Paperclip use.
+
+### 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. Optional: override the built-in for adapter development
+
+For local adapter development, install the package from a local path in Adapter
+manager, or add an entry to `~/.paperclip/adapter-plugins.json` and restart
+Paperclip. The external package can override either built-in Hermes adapter
+while it is enabled:
+
+```json
+[
+ {
+ "packageName": "@paperclipai/hermes-paperclip-adapter",
+ "localPath": "/absolute/path/to/paperclip/packages/adapters/hermes",
+ "type": "hermes_local",
+ "installedAt": "2026-06-23T00:00:00.000Z"
+ }
+]
+```
+
+Use `"type": "hermes_gateway"` with the same package when testing a gateway
+override.
+
+The package root exports `createServerAdapter()` for the local server adapter,
+a declarative config schema for the generic agent form, and `./ui-parser` for
+local run transcript parsing. Gateway entrypoints are exported from `./gateway`,
+`./gateway/server`, `./gateway/ui`, `./gateway/cli`, and `./gateway/ui-parser`.
+Paperclip core imports these same package entrypoints for built-in adapter
+registration.
+
+### 2. Create a local 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"]
+ }
+}
+```
+
+This mode shells out to the local `hermes` CLI. Paperclip injects runtime
+environment variables and captures stdout/stderr from the child process.
+
+### 3. Create a Hermes gateway agent in Paperclip
+
+Start Hermes with its API server enabled first:
+
+```bash
+API_SERVER_ENABLED=true \
+API_SERVER_KEY=<generated-secret> \
+hermes gateway run --replace --accept-hooks
+```
+
+Then create an agent with adapter type `hermes_gateway`:
+
+```json
+{
+ "name": "Hermes Gateway Engineer",
+ "adapterType": "hermes_gateway",
+ "adapterConfig": {
+ "apiBaseUrl": "http://127.0.0.1:8642",
+ "apiKey": "<same-value-as-API_SERVER_KEY>",
+ "paperclipApiUrl": "http://127.0.0.1:3100",
+ "sessionKeyStrategy": "issue",
+ "timeoutSec": 120
+ }
+}
+```
+
+This mode does not start Hermes. It creates runs with `POST /v1/runs`, streams
+Hermes events with SSE, polls run status as a fallback, and stops timed-out runs
+with `POST /v1/runs/{run_id}/stop`.
+
+### Compatibility with the old gateway package
+
+`@paperclipai/adapter-hermes-gateway` remains as a deprecated compatibility shim
+for one release. It re-exports the gateway entrypoints from
+`@paperclipai/hermes-paperclip-adapter/gateway` and preserves the legacy exports
+for existing plugin installs. New installs and built-in Paperclip registrations
+should use `@paperclipai/hermes-paperclip-adapter`; the adapter type remains
+`hermes_gateway`.
+
+### Runtime API guidance
+
+Hermes receives Paperclip runtime identity through environment variables:
+
+- `PAPERCLIP_API_URL`
+- `PAPERCLIP_API_KEY`
+- `PAPERCLIP_RUN_ID`
+
+Prompts should reference those variables directly. Command output may redact
+secret values, so do not copy printed tokens into comments or config. Use
+`Authorization: Bearer $PAPERCLIP_API_KEY` on Paperclip API requests and
+`X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID` on mutating issue requests. For
+multiline comments or status updates, preserve newlines with a heredoc plus
+`jq --arg`.
+
+### Hermes-originated Paperclip tasks
+
+The package includes a Hermes skill/helper for the reverse direction: a user
+starts in Hermes and asks Hermes to create or update Paperclip work. This is not
+the same as Paperclip waking Hermes through `hermes_local` or `hermes_gateway`.
+
+Configure Paperclip access in Hermes env/profile secrets, not prompt text:
+
+```bash
+PAPERCLIP_API_URL=http://127.0.0.1:3100/api
+PAPERCLIP_BRIDGE_API_KEY=<task-bridge-scoped-agent-api-key>
+```
+
+Optional env values:
+
+- `PAPERCLIP_COMPANY_ID`
+- `PAPERCLIP_AGENT_ID`
+- `PAPERCLIP_RUN_ID`
+
+The bundled `paperclip-task-bridge` skill provides deterministic helper
+commands:
+
+```bash
+node ./paperclip-task.mjs list-assigned
+node ./paperclip-task.mjs create-task --parent-id "<approved-parent-issue-id>" --title "Investigate checkout failures" --description "Capture failing request and root cause."
+node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path."
+node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."
+```
+
+The helper reads credentials from environment variables and prints only JSON
+summaries. It supports `create-task`, `comment`, `update-status`, and
+`list-assigned`.
+
+Create the bridge key with `scope.kind = "task_bridge"` plus a `parentIssueId`
+or `projectId` boundary. Do not use a normal claimed agent API key for
+internet-facing Hermes chat/webhook task-bridge operations.
+
+### 4. 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/paperclip
+cd paperclip/packages/adapters/hermes
+pnpm install
+pnpm 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
diff --git a/packages/adapters/hermes/gateway-ui-parser.cjs b/packages/adapters/hermes/gateway-ui-parser.cjs
new file mode 100644
index 0000000000..1cba319c8d
--- /dev/null
+++ b/packages/adapters/hermes/gateway-ui-parser.cjs
@@ -0,0 +1,49 @@
+"use strict";
+
+function safeJsonParse(text) {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function asRecord(value) {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value;
+}
+
+function asString(value) {
+ return typeof value === "string" ? value : "";
+}
+
+function parseStdoutLine(line, ts) {
+ const trimmed = line.trim();
+ if (!trimmed) return [];
+
+ const eventMatch = trimmed.match(/^\[hermes-gateway:event\]\s+run=([^\s]+)\s+event=([^\s]+)\s+data=(.*)$/s);
+ if (eventMatch) {
+ const eventName = eventMatch[2];
+ const data = asRecord(safeJsonParse(eventMatch[3]));
+ if (eventName === "message.delta") {
+ const delta = asString(data && data.delta) || asString(data && data.text_delta);
+ return delta ? [{ kind: "assistant", ts, text: delta, delta: true }] : [];
+ }
+ if (eventName === "run.failed" || eventName === "run.error") {
+ const message = asString(data && data.error) || asString(data && data.message) || "Hermes run failed";
+ return [{ kind: "stderr", ts, text: message }];
+ }
+ if (eventName === "reasoning.available") {
+ return [{ kind: "thinking", ts, text: "Hermes reasoning available" }];
+ }
+ return [{ kind: "system", ts, text: `Hermes event: ${eventName}` }];
+ }
+
+ if (trimmed.startsWith("[hermes-gateway]")) {
+ return [{ kind: "system", ts, text: trimmed.replace(/^\[hermes-gateway\]\s*/, "") }];
+ }
+
+ return [{ kind: "stdout", ts, text: line }];
+}
+
+module.exports = { parseStdoutLine };
diff --git a/packages/adapters/hermes/package.json b/packages/adapters/hermes/package.json
new file mode 100644
index 0000000000..356c049d9d
--- /dev/null
+++ b/packages/adapters/hermes/package.json
@@ -0,0 +1,113 @@
+{
+ "name": "@paperclipai/hermes-paperclip-adapter",
+ "version": "0.3.1",
+ "description": "Paperclip adapters for Hermes Agent local CLI and Hermes Gateway HTTP/SSE runs",
+ "type": "module",
+ "license": "MIT",
+ "author": "Paperclip",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/paperclipai/paperclip",
+ "directory": "packages/adapters/hermes"
+ },
+ "bugs": {
+ "url": "https://github.com/paperclipai/paperclip/issues"
+ },
+ "homepage": "https://github.com/paperclipai/paperclip/tree/master/packages/adapters/hermes#readme",
+ "keywords": [
+ "paperclip",
+ "hermes",
+ "hermes-agent",
+ "ai-agent",
+ "adapter",
+ "orchestration"
+ ],
+ "exports": {
+ ".": "./src/index.ts",
+ "./server": "./src/server/index.ts",
+ "./ui": "./src/ui/index.ts",
+ "./cli": "./src/cli/index.ts",
+ "./ui-parser": "./ui-parser.cjs",
+ "./gateway": "./src/gateway/index.ts",
+ "./gateway/server": "./src/gateway/server/index.ts",
+ "./gateway/ui": "./src/gateway/ui/index.ts",
+ "./gateway/cli": "./src/gateway/cli/index.ts",
+ "./gateway/ui-parser": "./gateway-ui-parser.cjs"
+ },
+ "paperclip": {
+ "adapterUiParser": "1.0.0"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./server": {
+ "types": "./dist/server/index.d.ts",
+ "import": "./dist/server/index.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./cli": {
+ "types": "./dist/cli/index.d.ts",
+ "import": "./dist/cli/index.js"
+ },
+ "./ui-parser": "./ui-parser.cjs",
+ "./gateway": {
+ "types": "./dist/gateway/index.d.ts",
+ "import": "./dist/gateway/index.js"
+ },
+ "./gateway/server": {
+ "types": "./dist/gateway/server/index.d.ts",
+ "import": "./dist/gateway/server/index.js"
+ },
+ "./gateway/ui": {
+ "types": "./dist/gateway/ui/index.d.ts",
+ "import": "./dist/gateway/ui/index.js"
+ },
+ "./gateway/cli": {
+ "types": "./dist/gateway/cli/index.d.ts",
+ "import": "./dist/gateway/cli/index.js"
+ },
+ "./gateway/ui-parser": "./gateway-ui-parser.cjs"
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "provenance": true
+ },
+ "files": [
+ "dist",
+ "skills",
+ "ui-parser.cjs",
+ "gateway-ui-parser.cjs",
+ "README.md",
+ "LICENSE"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "dev": "tsc --watch",
+ "lint": "eslint src/",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run",
+ "test:command-resolution": "vitest run src/server/command-resolution.test.ts",
+ "prepack": "node scripts/prepare-publish-package.mjs",
+ "postpack": "node scripts/restore-dev-package.mjs",
+ "clean": "rm -rf dist"
+ },
+ "dependencies": {
+ "@paperclipai/adapter-utils": "workspace:*",
+ "picocolors": "^1.1.1"
+ },
+ "devDependencies": {
+ "@types/node": "^22.19.21",
+ "typescript": "^5.7.3",
+ "vitest": "^4.1.8"
+ },
+ "engines": {
+ "node": ">=20.0.0"
+ }
+}
diff --git a/packages/adapters/hermes/scripts/prepare-publish-package.mjs b/packages/adapters/hermes/scripts/prepare-publish-package.mjs
new file mode 100644
index 0000000000..b004c53f8b
--- /dev/null
+++ b/packages/adapters/hermes/scripts/prepare-publish-package.mjs
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageDir = resolve(scriptDir, "..");
+const packageJsonPath = join(packageDir, "package.json");
+const devPackageJsonPath = join(packageDir, "package.dev.json");
+
+function findRepoRoot(startDir) {
+ let current = startDir;
+ while (current !== dirname(current)) {
+ if (existsSync(join(current, "pnpm-workspace.yaml"))) {
+ return current;
+ }
+ current = dirname(current);
+ }
+ return null;
+}
+
+function readJson(filePath) {
+ return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+function collectWorkspaceVersions(repoRoot) {
+ const roots = ["packages", "server", "ui", "cli"];
+ const versions = new Map();
+
+ function walk(relDir) {
+ const absDir = join(repoRoot, relDir);
+ if (!existsSync(absDir)) return;
+
+ const pkgPath = join(absDir, "package.json");
+ if (existsSync(pkgPath)) {
+ const pkg = readJson(pkgPath);
+ if (pkg.name && pkg.version) {
+ versions.set(pkg.name, pkg.version);
+ }
+ return;
+ }
+
+ for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+ if (!entry.isDirectory()) continue;
+ if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git") continue;
+ walk(join(relDir, entry.name));
+ }
+ }
+
+ for (const root of roots) {
+ walk(root);
+ }
+
+ return versions;
+}
+
+function rewriteWorkspaceDeps(deps, workspaceVersions) {
+ if (!deps) return deps;
+ return Object.fromEntries(
+ Object.entries(deps).map(([name, version]) => {
+ if (typeof version !== "string" || !version.startsWith("workspace:")) {
+ return [name, version];
+ }
+
+ const resolvedVersion = workspaceVersions.get(name);
+ if (!resolvedVersion) {
+ throw new Error(`Cannot resolve workspace dependency ${name} for publish package`);
+ }
+ return [name, resolvedVersion];
+ }),
+ );
+}
+
+const pkg = readJson(packageJsonPath);
+const publishConfig = pkg.publishConfig ?? {};
+
+if (existsSync(devPackageJsonPath)) {
+ throw new Error(`Refusing to overwrite existing ${devPackageJsonPath}`);
+}
+
+if (!publishConfig.exports) {
+ throw new Error(`${pkg.name} is missing publishConfig.exports`);
+}
+
+const repoRoot = findRepoRoot(packageDir);
+const workspaceVersions = repoRoot ? collectWorkspaceVersions(repoRoot) : new Map();
+
+renameSync(packageJsonPath, devPackageJsonPath);
+
+const nextPublishConfig = { ...publishConfig };
+delete nextPublishConfig.exports;
+delete nextPublishConfig.main;
+delete nextPublishConfig.types;
+
+const publishPkg = {
+ ...pkg,
+ exports: publishConfig.exports,
+ main: publishConfig.main,
+ types: publishConfig.types,
+ publishConfig: nextPublishConfig,
+ dependencies: rewriteWorkspaceDeps(pkg.dependencies, workspaceVersions),
+ optionalDependencies: rewriteWorkspaceDeps(pkg.optionalDependencies, workspaceVersions),
+ peerDependencies: rewriteWorkspaceDeps(pkg.peerDependencies, workspaceVersions),
+};
+
+writeFileSync(packageJsonPath, `${JSON.stringify(publishPkg, null, 2)}\n`);
diff --git a/packages/adapters/hermes/scripts/restore-dev-package.mjs b/packages/adapters/hermes/scripts/restore-dev-package.mjs
new file mode 100644
index 0000000000..33e24fc04f
--- /dev/null
+++ b/packages/adapters/hermes/scripts/restore-dev-package.mjs
@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { existsSync, renameSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageDir = resolve(scriptDir, "..");
+const packageJsonPath = join(packageDir, "package.json");
+const devPackageJsonPath = join(packageDir, "package.dev.json");
+
+if (existsSync(devPackageJsonPath)) {
+ rmSync(packageJsonPath, { force: true });
+ renameSync(devPackageJsonPath, packageJsonPath);
+}
diff --git a/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.md b/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.md
new file mode 100644
index 0000000000..b325cec516
--- /dev/null
+++ b/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: paperclip-task-bridge
+description: Create, comment on, update, and list Paperclip tasks from Hermes using scoped Paperclip API credentials.
+---
+
+# Paperclip Task Bridge
+
+Use this skill when a Hermes-originated request needs to create or update Paperclip work directly. This is the Hermes-to-Paperclip direction, separate from Paperclip waking Hermes through the `hermes_local` or `hermes_gateway` adapter.
+
+## Required Environment
+
+Configure these in Hermes env/profile secrets, not in prompt text:
+
+- `PAPERCLIP_API_URL` - Paperclip base URL, with or without `/api`.
+- `PAPERCLIP_BRIDGE_API_KEY` - a Paperclip agent API key created with `scope.kind = "task_bridge"`.
+
+Optional:
+
+- `PAPERCLIP_API_KEY` - fallback env var for older profiles; it must still contain a `task_bridge` scoped key, never a full agent key.
+- `PAPERCLIP_COMPANY_ID` - skips one identity lookup when set.
+- `PAPERCLIP_AGENT_ID` - skips one identity lookup when set.
+- `PAPERCLIP_RUN_ID` - sent as `X-Paperclip-Run-Id` on mutating requests when Hermes is running inside a Paperclip heartbeat.
+
+Never print or paste API keys. The helper reads credentials from environment variables and only prints response summaries. Do not put a normal claimed agent API key in an internet-facing Hermes runtime; normal keys can use broad same-company Paperclip routes.
+
+## Create a Bridge Key
+
+Create the key from a board-authenticated Paperclip API session and store the returned token once:
+
+```sh
+curl -X POST "$PAPERCLIP_API_URL/api/agents/$HERMES_AGENT_ID/keys" \
+ -H "Authorization: Bearer $BOARD_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Hermes task bridge",
+ "scope": {
+ "kind": "task_bridge",
+ "parentIssueId": "00000000-0000-4000-8000-000000000000"
+ }
+ }'
+```
+
+Use `parentIssueId` or `parentIssueIds` when Hermes should only create child tasks under approved work. Use `projectId` or `projectIds` when the approved boundary is a project. A bridge key can create tasks only inside that boundary, can comment/update only bridge-created or assigned issues, and cannot use company-wide issue list/search/read surfaces.
+
+## Helper
+
+Run the helper from this skill directory:
+
+```sh
+node ./paperclip-task.mjs --help
+```
+
+Commands:
+
+```sh
+node ./paperclip-task.mjs list-assigned
+node ./paperclip-task.mjs create-task --parent-id "00000000-0000-4000-8000-000000000000" --title "Investigate checkout failures" --description "Capture failing request and root cause."
+node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path."
+node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."
+```
+
+`create-task` defaults to assigning the task to the authenticated Hermes agent so the work is immediately actionable. Use `--unassigned` to create backlog work instead. Use `--assignee-agent-id <uuid>` only when the Paperclip API key has permission to assign work to that agent.
+
+For multiline bodies, prefer files or stdin:
+
+```sh
+node ./paperclip-task.mjs create-task --title "Write rollout note" --description-file ./task.md
+node ./paperclip-task.mjs comment --issue PAP-123 --body-file -
+```
+
+## Workflow Expectations
+
+- Keep tasks company-scoped by using the company resolved from the scoped agent key.
+- Let Paperclip activity logging come from the normal API endpoints; do not write local logs that include credentials.
+- Use comments for durable progress.
+- Use `update-status` only when the issue has a real disposition: `done`, `in_review`, `blocked`, `todo`, `in_progress`, `backlog`, or `cancelled`.
+- Use `list-assigned` before creating duplicate work when the user asks about current Paperclip assignments.
diff --git a/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs b/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs
new file mode 100755
index 0000000000..956e953281
--- /dev/null
+++ b/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs
@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+
+const STATUSES = new Set(["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"]);
+const PRIORITIES = new Set(["critical", "high", "medium", "low"]);
+const WORK_MODES = new Set(["standard", "ask", "planning"]);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const HELP = `Paperclip task bridge for Hermes
+
+Usage:
+ paperclip-task.mjs list-assigned [--status todo,in_progress,in_review,blocked] [--limit 20]
+ paperclip-task.mjs create-task --title <title> [--description <text>|--description-file <path|->] [options]
+ paperclip-task.mjs comment --issue <id|identifier> (--body <text>|--body-file <path|->) [--resume|--reopen]
+ paperclip-task.mjs update-status --issue <id|identifier> --status <status> [--comment <text>|--comment-file <path|->]
+
+Environment:
+ PAPERCLIP_API_URL Paperclip base URL, with or without /api.
+ PAPERCLIP_BRIDGE_API_KEY
+ Task-bridge Paperclip API key with kind=task_bridge scope.
+ PAPERCLIP_API_KEY Fallback bridge key env var. Do not use a full agent key.
+ PAPERCLIP_COMPANY_ID Optional company id override.
+ PAPERCLIP_AGENT_ID Optional agent id override.
+ PAPERCLIP_RUN_ID Optional run id for X-Paperclip-Run-Id on mutations.
+
+create-task options:
+ --assignee-agent-id <uuid|self> Assign to an agent. Defaults to self.
+ --unassigned Create backlog/unassigned work.
+ --parent-id <uuid> Parent issue id.
+ --goal-id <uuid> Goal id.
+ --project-id <uuid> Project id.
+ --priority <critical|high|medium|low>
+ --status <backlog|todo|in_progress|in_review|done|blocked|cancelled>
+ --work-mode <standard|ask|planning>
+
+Output is JSON and never includes credentials.`;
+
+class UsageError extends Error {
+ constructor(message) {
+ super(message);
+ this.name = "UsageError";
+ }
+}
+
+class ApiError extends Error {
+ constructor(status, body) {
+ const message = typeof body?.error === "string" ? body.error : `Paperclip API request failed with status ${status}`;
+ super(message);
+ this.name = "ApiError";
+ this.status = status;
+ this.body = body;
+ }
+}
+
+function parseArgs(argv) {
+ const out = { _: [] };
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (!arg.startsWith("--")) {
+ out._.push(arg);
+ continue;
+ }
+ const eq = arg.indexOf("=");
+ if (eq !== -1) {
+ out[arg.slice(2, eq)] = arg.slice(eq + 1);
+ continue;
+ }
+ const key = arg.slice(2);
+ const next = argv[i + 1];
+ if (!next || next.startsWith("--")) {
+ out[key] = true;
+ continue;
+ }
+ out[key] = next;
+ i += 1;
+ }
+ return out;
+}
+
+function readStringFlag(args, name) {
+ const value = args[name];
+ if (typeof value !== "string" || value.trim().length === 0) return null;
+ return value;
+}
+
+function requireStringFlag(args, name) {
+ const value = readStringFlag(args, name);
+ if (!value) throw new UsageError(`Missing required --${name}`);
+ return value;
+}
+
+function boolFlag(args, name) {
+ return args[name] === true;
+}
+
+function normalizeApiBaseUrl(raw) {
+ if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
+ throw new UsageError("PAPERCLIP_API_URL is required");
+ }
+ const trimmed = raw.trim().replace(/\/+$/, "");
+ return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+
+function getConfig() {
+ const apiKey = process.env.PAPERCLIP_BRIDGE_API_KEY?.trim() || process.env.PAPERCLIP_API_KEY?.trim();
+ if (!apiKey) throw new UsageError("PAPERCLIP_BRIDGE_API_KEY is required");
+ return {
+ apiBaseUrl: normalizeApiBaseUrl(process.env.PAPERCLIP_API_URL),
+ apiKey,
+ runId: process.env.PAPERCLIP_RUN_ID?.trim() || null,
+ companyId: process.env.PAPERCLIP_COMPANY_ID?.trim() || null,
+ agentId: process.env.PAPERCLIP_AGENT_ID?.trim() || null,
+ };
+}
+
+async function readBody(args, textFlag, fileFlag) {
+ const direct = readStringFlag(args, textFlag);
+ const file = readStringFlag(args, fileFlag);
+ if (direct && file) throw new UsageError(`Use either --${textFlag} or --${fileFlag}, not both`);
+ if (direct) return direct;
+ if (!file) return null;
+ if (file === "-") {
+ return await new Promise((resolve, reject) => {
+ let data = "";
+ process.stdin.setEncoding("utf8");
+ process.stdin.on("data", (chunk) => {
+ data += chunk;
+ });
+ process.stdin.on("end", () => resolve(data));
+ process.stdin.on("error", reject);
+ });
+ }
+ return fs.readFile(file, "utf8");
+}
+
+async function apiFetch(config, path, options = {}) {
+ const headers = {
+ Authorization: `Bearer ${config.apiKey}`,
+ Accept: "application/json",
+ ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+ ...(options.mutating && config.runId ? { "X-Paperclip-Run-Id": config.runId } : {}),
+ };
+ const response = await fetch(`${config.apiBaseUrl}${path}`, {
+ method: options.method ?? "GET",
+ headers,
+ body: options.body === undefined ? undefined : JSON.stringify(options.body),
+ });
+ const text = await response.text();
+ let body = null;
+ if (text) {
+ try {
+ body = JSON.parse(text);
+ } catch {
+ body = { error: text.slice(0, 1000) };
+ }
+ }
+ if (!response.ok) throw new ApiError(response.status, body);
+ return body;
+}
+
+async function resolveIdentity(config) {
+ if (config.companyId && config.agentId) {
+ return { companyId: config.companyId, agentId: config.agentId, agent: null };
+ }
+ const agent = await apiFetch(config, "/agents/me");
+ const companyId = config.companyId || agent.companyId;
+ const agentId = config.agentId || agent.id;
+ if (!companyId || !agentId) throw new ApiError(500, { error: "Paperclip identity response did not include companyId and agent id" });
+ return { companyId, agentId, agent };
+}
+
+function issueSummary(issue) {
+ if (!issue || typeof issue !== "object") return issue;
+ return {
+ id: issue.id ?? null,
+ identifier: issue.identifier ?? null,
+ title: issue.title ?? null,
+ status: issue.status ?? null,
+ priority: issue.priority ?? null,
+ assigneeAgentId: issue.assigneeAgentId ?? null,
+ assigneeUserId: issue.assigneeUserId ?? null,
+ projectId: issue.projectId ?? null,
+ goalId: issue.goalId ?? null,
+ parentId: issue.parentId ?? null,
+ updatedAt: issue.updatedAt ?? null,
+ };
+}
+
+function commentSummary(comment) {
+ if (!comment || typeof comment !== "object") return comment;
+ return {
+ id: comment.id ?? null,
+ issueId: comment.issueId ?? null,
+ authorType: comment.authorType ?? null,
+ authorAgentId: comment.authorAgentId ?? null,
+ createdAt: comment.createdAt ?? null,
+ };
+}
+
+function printJson(value) {
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function validateEnum(value, allowed, label) {
+ if (!allowed.has(value)) {
+ throw new UsageError(`Invalid ${label}: ${value}`);
+ }
+ return value;
+}
+
+function parseLimit(args) {
+ const raw = readStringFlag(args, "limit");
+ if (!raw) return 20;
+ const value = Number.parseInt(raw, 10);
+ if (!Number.isInteger(value) || value <= 0 || value > 100) {
+ throw new UsageError("--limit must be an integer from 1 to 100");
+ }
+ return value;
+}
+
+async function listAssigned(config, args) {
+ const identity = await resolveIdentity(config);
+ const status = readStringFlag(args, "status") || "todo,in_progress,in_review,blocked";
+ const limit = parseLimit(args);
+ const issues = await apiFetch(config, "/agents/me/inbox-lite");
+ const allowedStatuses = new Set(status.split(",").map((entry) => entry.trim()).filter(Boolean));
+ const filteredIssues = Array.isArray(issues)
+ ? issues.filter((issue) => !allowedStatuses.size || allowedStatuses.has(issue?.status)).slice(0, limit)
+ : [];
+ printJson({
+ command: "list-assigned",
+ companyId: identity.companyId,
+ agentId: identity.agentId,
+ count: filteredIssues.length,
+ issues: filteredIssues.map(issueSummary),
+ });
+}
+
+async function createTask(config, args) {
+ const identity = await resolveIdentity(config);
+ const title = requireStringFlag(args, "title");
+ const description = await readBody(args, "description", "description-file");
+ const unassigned = boolFlag(args, "unassigned");
+ const assigneeRaw = readStringFlag(args, "assignee-agent-id");
+ const assigneeAgentId = unassigned
+ ? undefined
+ : !assigneeRaw || assigneeRaw === "self"
+ ? identity.agentId
+ : assigneeRaw;
+ if (assigneeAgentId !== undefined && !UUID_RE.test(assigneeAgentId)) {
+ throw new UsageError("--assignee-agent-id must be a UUID, self, or omitted");
+ }
+ const priority = readStringFlag(args, "priority") ?? "medium";
+ const workMode = readStringFlag(args, "work-mode") ?? "standard";
+ validateEnum(priority, PRIORITIES, "priority");
+ validateEnum(workMode, WORK_MODES, "work mode");
+ const body = {
+ title,
+ description,
+ priority,
+ workMode,
+ ...(assigneeAgentId !== undefined ? { assigneeAgentId } : {}),
+ };
+ for (const [flag, field] of [
+ ["parent-id", "parentId"],
+ ["goal-id", "goalId"],
+ ["project-id", "projectId"],
+ ]) {
+ const value = readStringFlag(args, flag);
+ if (value) body[field] = value;
+ }
+ const status = readStringFlag(args, "status");
+ if (status) body.status = validateEnum(status, STATUSES, "status");
+
+ const issue = await apiFetch(config, `/companies/${encodeURIComponent(identity.companyId)}/issues`, {
+ method: "POST",
+ mutating: true,
+ body,
+ });
+ printJson({ command: "create-task", issue: issueSummary(issue) });
+}
+
+async function comment(config, args) {
+ const issueRef = requireStringFlag(args, "issue");
+ const bodyText = await readBody(args, "body", "body-file");
+ if (!bodyText || bodyText.trim().length === 0) throw new UsageError("comment requires --body or --body-file");
+ const commentBody = {
+ body: bodyText,
+ ...(boolFlag(args, "resume") ? { resume: true } : {}),
+ ...(boolFlag(args, "reopen") ? { reopen: true } : {}),
+ };
+ const created = await apiFetch(config, `/issues/${encodeURIComponent(issueRef)}/comments`, {
+ method: "POST",
+ mutating: true,
+ body: commentBody,
+ });
+ printJson({ command: "comment", issue: issueRef, comment: commentSummary(created) });
+}
+
+async function updateStatus(config, args) {
+ const issueRef = requireStringFlag(args, "issue");
+ const status = validateEnum(requireStringFlag(args, "status"), STATUSES, "status");
+ const commentText = await readBody(args, "comment", "comment-file");
+ const body = {
+ status,
+ ...(commentText && commentText.trim().length > 0 ? { comment: commentText } : {}),
+ ...(boolFlag(args, "resume") ? { resume: true } : {}),
+ ...(boolFlag(args, "reopen") ? { reopen: true } : {}),
+ };
+ const issue = await apiFetch(config, `/issues/${encodeURIComponent(issueRef)}`, {
+ method: "PATCH",
+ mutating: true,
+ body,
+ });
+ printJson({ command: "update-status", issue: issueSummary(issue) });
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ const command = args._[0];
+ if (!command || command === "help" || command === "--help" || boolFlag(args, "help")) {
+ process.stdout.write(`${HELP}\n`);
+ return;
+ }
+ const config = getConfig();
+ if (command === "list-assigned") return listAssigned(config, args);
+ if (command === "create-task") return createTask(config, args);
+ if (command === "comment") return comment(config, args);
+ if (command === "update-status") return updateStatus(config, args);
+ throw new UsageError(`Unknown command: ${command}`);
+}
+
+main().catch((err) => {
+ if (err instanceof UsageError) {
+ process.stderr.write(`Usage error: ${err.message}\n\n${HELP}\n`);
+ process.exitCode = 2;
+ return;
+ }
+ if (err instanceof ApiError) {
+ printJson({
+ error: err.message,
+ status: err.status,
+ details: err.body?.details ?? null,
+ });
+ process.exitCode = 1;
+ return;
+ }
+ process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+ process.exitCode = 1;
+});
diff --git a/packages/adapters/hermes/src/cli/format-event.ts b/packages/adapters/hermes/src/cli/format-event.ts
new file mode 100644
index 0000000000..5f44bbeb4d
--- /dev/null
+++ b/packages/adapters/hermes/src/cli/format-event.ts
@@ -0,0 +1,61 @@
+/**
+ * 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: string, debug: boolean): void {
+ 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));
+}
diff --git a/packages/adapters/hermes/src/cli/index.ts b/packages/adapters/hermes/src/cli/index.ts
new file mode 100644
index 0000000000..2177ef6627
--- /dev/null
+++ b/packages/adapters/hermes/src/cli/index.ts
@@ -0,0 +1,5 @@
+/**
+ * CLI module exports — used by Paperclip's CLI for terminal formatting.
+ */
+
+export { printHermesStreamEvent } from "./format-event.js";
diff --git a/packages/adapters/hermes/src/gateway/cli/format-event.ts b/packages/adapters/hermes/src/gateway/cli/format-event.ts
new file mode 100644
index 0000000000..58705bc40a
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/cli/format-event.ts
@@ -0,0 +1,13 @@
+export function printHermesGatewayStreamEvent(line: string, debug: boolean): void {
+ const trimmed = line.trim();
+ if (!trimmed) return;
+ if (trimmed.startsWith("[hermes-gateway:event]")) {
+ console.log(trimmed);
+ return;
+ }
+ if (trimmed.startsWith("[hermes-gateway]")) {
+ console.log(trimmed);
+ return;
+ }
+ if (debug) console.log(line);
+}
diff --git a/packages/adapters/hermes/src/gateway/cli/index.ts b/packages/adapters/hermes/src/gateway/cli/index.ts
new file mode 100644
index 0000000000..673d48880d
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/cli/index.ts
@@ -0,0 +1 @@
+export { printHermesGatewayStreamEvent as formatStdoutEvent } from "./format-event.js";
diff --git a/packages/adapters/hermes/src/gateway/index.ts b/packages/adapters/hermes/src/gateway/index.ts
new file mode 100644
index 0000000000..dd89113df8
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/index.ts
@@ -0,0 +1,72 @@
+import type { AdapterSessionManagement, ServerAdapterModule } from "@paperclipai/adapter-utils";
+import { ADAPTER_LABEL, ADAPTER_TYPE } from "./shared/constants.js";
+import { execute, getConfigSchema, sessionCodec, testEnvironment } from "./server/index.js";
+
+export const type = ADAPTER_TYPE;
+export const label = ADAPTER_LABEL;
+export const models: { id: string; label: string }[] = [];
+
+const sessionManagement: AdapterSessionManagement = {
+ supportsSessionResume: true,
+ nativeContextManagement: "confirmed",
+ defaultSessionCompaction: {
+ enabled: true,
+ maxSessionRuns: 0,
+ maxRawInputTokens: 0,
+ maxSessionAgeHours: 0,
+ },
+};
+
+export const agentConfigurationDoc = `# hermes_gateway agent configuration
+
+Adapter: hermes_gateway
+
+Use when:
+- Hermes Agent runs on another host or process that exposes the Hermes API server.
+- Paperclip should create Hermes runs through POST /v1/runs and observe them through SSE events.
+- You need remote Hermes session continuity with X-Hermes-Session-Key.
+
+Don't use when:
+- Hermes should run as a local child process on the Paperclip host; use hermes_local instead.
+- The Hermes API server is not enabled or is only reachable over an unsafe public HTTP endpoint.
+- You need Hermes-originated Paperclip task creation only; that is a Paperclip skill/API bridge, not this wake adapter.
+
+Required fields:
+- apiBaseUrl (string): Hermes API server base URL, for example http://127.0.0.1:8642.
+- apiKey (string): Hermes API_SERVER_KEY. Sent as Authorization: Bearer <apiKey>.
+
+Optional fields:
+- headers (object or JSON string): extra noncritical headers. Authorization, Content-Type, Accept, Idempotency-Key, and X-Hermes-Session-Key are generated by the adapter.
+- paperclipApiUrl (string): Paperclip API URL reachable from the Hermes host. This is not a credential.
+- sessionKeyStrategy (issue | agent | run | none): defaults to issue.
+- timeoutSec (number): defaults to 120.
+- eventReconnectMs (number): defaults to 2000.
+- instructions (string): stable Hermes instructions sent separately from wake input.
+
+Runtime mapping:
+- Creates runs with POST /v1/runs.
+- Sends Idempotency-Key equal to the Paperclip run id for correlation only; Hermes v0.16.0 did not dedupe duplicate creates.
+- Streams GET /v1/runs/{run_id}/events and polls GET /v1/runs/{run_id} as fallback.
+- Calls POST /v1/runs/{run_id}/stop on timeout.
+
+Security guidance:
+- Prefer HTTPS or a private overlay network for non-loopback hosts.
+- Do not put Hermes apiKey or Paperclip bearer tokens in prompts, comments, logs, or result JSON.
+- Keep the default issue-scoped session strategy unless shared agent memory is intentional.
+`;
+
+export function createServerAdapter(): ServerAdapterModule {
+ return {
+ type,
+ execute,
+ testEnvironment,
+ sessionCodec,
+ sessionManagement,
+ models,
+ supportsLocalAgentJwt: false,
+ supportsInstructionsBundle: false,
+ requiresMaterializedRuntimeSkills: false,
+ agentConfigurationDoc,
+ getConfigSchema,
+ };
+}
diff --git a/packages/adapters/hermes/src/gateway/server/config-schema.ts b/packages/adapters/hermes/src/gateway/server/config-schema.ts
new file mode 100644
index 0000000000..ad27054d23
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/config-schema.ts
@@ -0,0 +1,76 @@
+import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";
+import { DEFAULT_EVENT_RECONNECT_MS, DEFAULT_TIMEOUT_SEC } from "../shared/constants.js";
+import { INSECURE_REMOTE_HTTP_ESCAPE_HATCH } from "./transport-security.js";
+
+export function getConfigSchema(): AdapterConfigSchema {
+ return {
+ fields: [
+ {
+ key: "apiBaseUrl",
+ label: "API base URL",
+ type: "text",
+ required: true,
+ hint: "Hermes API server base URL, such as http://127.0.0.1:8642 or a private HTTPS URL.",
+ },
+ {
+ key: "apiKey",
+ label: "API key",
+ type: "text",
+ required: true,
+ hint: "Hermes API_SERVER_KEY. Stored as a Paperclip secret reference.",
+ meta: { secret: true },
+ },
+ {
+ key: INSECURE_REMOTE_HTTP_ESCAPE_HATCH,
+ label: "Dangerously allow remote HTTP",
+ type: "toggle",
+ default: false,
+ hint: "Unsafe dev-only escape hatch. Remote Hermes gateways should use HTTPS; loopback HTTP remains allowed.",
+ },
+ {
+ key: "sessionKeyStrategy",
+ label: "Session key strategy",
+ type: "select",
+ default: "issue",
+ options: [
+ { value: "issue", label: "Issue scoped" },
+ { value: "agent", label: "Agent scoped" },
+ { value: "run", label: "Run scoped" },
+ { value: "none", label: "None" },
+ ],
+ hint: "Controls X-Hermes-Session-Key. Issue scoped prevents cross-task memory bleed by default.",
+ },
+ {
+ key: "timeoutSec",
+ label: "Timeout seconds",
+ type: "number",
+ default: DEFAULT_TIMEOUT_SEC,
+ },
+ {
+ key: "eventReconnectMs",
+ label: "Event reconnect ms",
+ type: "number",
+ default: DEFAULT_EVENT_RECONNECT_MS,
+ hint: "Delay before reconnecting the Hermes SSE events stream after a nonterminal disconnect.",
+ },
+ {
+ key: "paperclipApiUrl",
+ label: "Paperclip API URL",
+ type: "text",
+ hint: "Optional Paperclip API URL reachable by the remote Hermes host. This is not a credential.",
+ },
+ {
+ key: "headers",
+ label: "Extra headers",
+ type: "textarea",
+ hint: "Optional JSON object of extra nonsecret headers. Security-critical headers are generated by the adapter.",
+ },
+ {
+ key: "instructions",
+ label: "Instructions",
+ type: "textarea",
+ hint: "Optional stable Hermes instructions sent separately from the wake input.",
+ },
+ ],
+ };
+}
diff --git a/packages/adapters/hermes/src/gateway/server/execute.test.ts b/packages/adapters/hermes/src/gateway/server/execute.test.ts
new file mode 100644
index 0000000000..de3c165756
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/execute.test.ts
@@ -0,0 +1,417 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { execute, mapFinalResultForTest, parseSseFramesForTest, resolveSessionKey } from "./execute.js";
+import { testEnvironment } from "./test.js";
+
+function makeCtx(config: Record<string, unknown>): AdapterExecutionContext {
+ return {
+ runId: "pc-run-1",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Hermes",
+ adapterType: "hermes_gateway",
+ adapterConfig: config,
+ },
+ runtime: {
+ sessionId: null,
+ sessionParams: null,
+ sessionDisplayId: null,
+ taskKey: null,
+ },
+ config,
+ context: {
+ issueId: "issue-1",
+ wakeReason: "manual",
+ paperclipWake: {
+ issue: { identifier: "PAP-1", title: "Do the thing" },
+ },
+ },
+ onLog: vi.fn(async () => undefined),
+ onMeta: vi.fn(async () => undefined),
+ };
+}
+
+function sseStream(text: string): ReadableStream<Uint8Array> {
+ return new ReadableStream<Uint8Array>({
+ start(controller) {
+ controller.enqueue(new TextEncoder().encode(text));
+ controller.close();
+ },
+ });
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe("resolveSessionKey", () => {
+ it("derives issue-scoped session keys by default", () => {
+ expect(
+ resolveSessionKey({
+ strategy: "issue",
+ companyId: "company-1",
+ agentId: "agent-1",
+ runId: "run-1",
+ issueId: "issue-1",
+ }),
+ ).toBe("paperclip:company:company-1:agent:agent-1:issue:issue-1");
+ });
+
+ it("omits the session key for none strategy", () => {
+ expect(
+ resolveSessionKey({
+ strategy: "none",
+ companyId: "company-1",
+ agentId: "agent-1",
+ runId: "run-1",
+ issueId: "issue-1",
+ }),
+ ).toBeNull();
+ });
+});
+
+describe("parseSseFramesForTest", () => {
+ it("parses event and data lines while preserving partial frames", () => {
+ const parsed = parseSseFramesForTest("event: message.delta\ndata: {\"delta\":\"hi\"}\n\n:data\ndata: later");
+ expect(parsed.frames).toEqual([{ event: "message.delta", data: "{\"delta\":\"hi\"}" }]);
+ expect(parsed.rest).toBe(":data\ndata: later");
+ });
+});
+
+describe("execute", () => {
+ it("rejects remote plain HTTP unless the unsafe dev escape hatch is enabled", async () => {
+ const fetchMock = vi.fn(async () => new Response(JSON.stringify({ run_id: "unexpected" }), { status: 200 }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://192.168.1.25:8642",
+ apiKey: "secret-key",
+ }));
+
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("hermes_gateway_plain_http_remote_denied");
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it("constructs POST /v1/runs with auth, idempotency, and Hermes session headers", async () => {
+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith("/v1/runs")) {
+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });
+ }
+ if (url.endsWith("/events")) {
+ return new Response(
+ sseStream(
+ [
+ "event: message.delta",
+ "data: {\"delta\":\"done\"}",
+ "",
+ "event: run.completed",
+ "data: {\"status\":\"completed\",\"output\":\"done\",\"session_id\":\"session-1\",\"usage\":{\"input_tokens\":3,\"output_tokens\":2},\"model\":\"hermes-agent\"}",
+ "",
+ ].join("\n"),
+ ),
+ { status: 200, headers: { "content-type": "text/event-stream" } },
+ );
+ }
+ return new Response(JSON.stringify({ status: "completed", output: "done" }), { status: 200 });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ timeoutSec: 5,
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(result.summary).toBe("done");
+ expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 2 });
+
+ const calls = fetchMock.mock.calls as Array<[RequestInfo | URL, RequestInit?]>;
+ const createCall = calls.find(([input]) => String(input).endsWith("/v1/runs"));
+ expect(createCall).toBeTruthy();
+ const init = createCall?.[1] as RequestInit;
+ expect(init.headers).toMatchObject({
+ Authorization: "Bearer secret-key",
+ "Content-Type": "application/json",
+ "Idempotency-Key": "pc-run-1",
+ "X-Hermes-Session-Key": "paperclip:company:company-1:agent:agent-1:issue:issue-1",
+ });
+ const body = JSON.parse(String(init.body));
+ expect(body.input).toContain("Do the thing");
+ expect(body.session_id).toBe("paperclip:company:company-1:agent:agent-1:issue:issue-1");
+ });
+
+ it("redacts echoed auth material from stream logs and summaries", async () => {
+ const ctx = makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ timeoutSec: 5,
+ });
+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith("/v1/runs")) {
+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });
+ }
+ if (url.endsWith("/events")) {
+ return new Response(
+ sseStream(
+ [
+ "event: message.delta",
+ "data: {\"delta\":\"Authorization: Bearer secret-key\\nX-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1\"}",
+ "",
+ "event: run.completed",
+ "data: {\"status\":\"completed\",\"output\":\"Authorization: Bearer secret-key\\nraw key secret-key\\nX-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1\"}",
+ "",
+ ].join("\n"),
+ ),
+ { status: 200, headers: { "content-type": "text/event-stream" } },
+ );
+ }
+ return new Response(JSON.stringify({ status: "completed" }), { status: 200 });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(ctx);
+ const logText = (ctx.onLog as ReturnType<typeof vi.fn>).mock.calls.map(([, line]) => String(line)).join("\n");
+
+ expect(result.exitCode).toBe(0);
+ expect(result.summary).toContain("Bearer [redacted]");
+ expect(result.summary).toContain("raw key [redacted len=10]");
+ expect(result.summary).toContain("X-Hermes-Session-Key: [redacted]");
+ expect(result.summary).not.toContain("secret-key");
+ expect(result.summary).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");
+ expect(result.resultJson?.output).toBe(result.summary);
+ expect(logText).toContain("Bearer [redacted]");
+ expect(logText).toContain("X-Hermes-Session-Key: [redacted]");
+ expect(logText).not.toContain("secret-key");
+ expect(logText).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");
+ });
+
+ it("redacts agent-scoped Paperclip session keys from logs and public result metadata", async () => {
+ const ctx = makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ sessionKeyStrategy: "agent",
+ timeoutSec: 5,
+ });
+ const agentSessionKey = "paperclip:company:company-1:agent:agent-1";
+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith("/v1/runs")) {
+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });
+ }
+ if (url.endsWith("/events")) {
+ return new Response(
+ sseStream(
+ [
+ "event: message.delta",
+ `data: {"delta":"session ${agentSessionKey}"}`,
+ "",
+ "event: run.completed",
+ `data: {"status":"completed","output":"session ${agentSessionKey}","session_id":"${agentSessionKey}"}`,
+ "",
+ ].join("\n"),
+ ),
+ { status: 200, headers: { "content-type": "text/event-stream" } },
+ );
+ }
+ return new Response(JSON.stringify({ status: "completed" }), { status: 200 });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(ctx);
+ const logText = (ctx.onLog as ReturnType<typeof vi.fn>).mock.calls.map(([, line]) => String(line)).join("\n");
+
+ expect(result.exitCode).toBe(0);
+ expect(result.summary).toBe("session [redacted-session-key]");
+ expect(result.sessionId).toBe("[redacted-session-key]");
+ expect(result.sessionDisplayId).toBe("[redacted-session-key]");
+ expect(result.resultJson?.session_id).toBe("[redacted-session-key]");
+ expect(result.sessionParams).toEqual({
+ hermesRunId: "run-hermes-1",
+ strategy: "agent",
+ });
+ expect(logText).toContain("[redacted-session-key]");
+ expect(logText).not.toContain(agentSessionKey);
+ });
+
+ it("falls back to polling when SSE is unavailable", async () => {
+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url.endsWith("/v1/runs")) {
+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });
+ }
+ if (url.endsWith("/events")) {
+ return new Response("no stream", { status: 503 });
+ }
+ return new Response(JSON.stringify({
+ status: "completed",
+ output: "polled done",
+ session_id: "session-polled",
+ }), { status: 200 });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ timeoutSec: 5,
+ pollIntervalMs: 250,
+ }));
+
+ expect(result.exitCode).toBe(0);
+ expect(result.summary).toBe("polled done");
+ expect(fetchMock.mock.calls.some(([input]) => String(input).endsWith("/v1/runs/run-hermes-1"))).toBe(true);
+ });
+
+ it("maps HTTP auth failures", async () => {
+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ error: "bad key" }), { status: 401 })));
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ }));
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("hermes_gateway_auth_failed");
+ });
+
+ it("redacts echoed auth material from HTTP error payloads", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () =>
+ new Response(
+ JSON.stringify({
+ message: "Authorization rejected: Bearer secret-key raw secret-key",
+ detail: "X-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1",
+ nested: {
+ note: "session paperclip:company:company-1:agent:agent-1",
+ },
+ }),
+ { status: 401 },
+ )),
+ );
+
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ }));
+
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("hermes_gateway_auth_failed");
+ expect(result.errorMeta?.body).toEqual({
+ message: "Authorization rejected: Bearer [redacted] raw [redacted len=10]",
+ detail: "X-Hermes-Session-Key: [redacted]",
+ nested: {
+ note: "session [redacted-session-key]",
+ },
+ });
+ expect(result.errorMessage).not.toContain("secret-key");
+ expect(result.errorMessage).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");
+ });
+
+ it("calls stop on timeout", async () => {
+ const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = String(input);
+ if (url.endsWith("/v1/runs")) {
+ return new Response(JSON.stringify({ run_id: "run-slow", status: "started" }), { status: 200 });
+ }
+ if (url.endsWith("/events")) {
+ return new Promise<Response>(() => {});
+ }
+ if (url.endsWith("/stop")) {
+ return new Response(JSON.stringify({ status: "stopping" }), { status: 200 });
+ }
+ if (init?.method === "GET") {
+ return new Response(JSON.stringify({ status: "cancelled", last_event: "run.cancelled" }), { status: 200 });
+ }
+ return new Response(JSON.stringify({ status: "running" }), { status: 200 });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await execute(makeCtx({
+ apiBaseUrl: "http://127.0.0.1:8642",
+ apiKey: "secret-key",
+ timeoutSec: 0.001,
+ }));
+
+ expect(result.timedOut).toBe(true);
+ expect(result.errorCode).toBe("hermes_gateway_timeout");
+ expect(fetchMock.mock.calls.some(([input]) => String(input).endsWith("/stop"))).toBe(true);
+ });
+});
+
+describe("testEnvironment", () => {
+ it("fails remote plain HTTP before probing health", async () => {
+ const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "hermes_gateway",
+ config: {
+ apiBaseUrl: "http://hermes.example:8642",
+ apiKey: "secret-key",
+ },
+ });
+
+ expect(result.status).toBe("fail");
+ expect(result.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "hermes_gateway_plain_http_remote_denied",
+ level: "error",
+ }),
+ ]),
+ );
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it("allows remote plain HTTP only with the unsafe dev escape hatch", async () => {
+ const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "hermes_gateway",
+ config: {
+ apiBaseUrl: "http://hermes.example:8642",
+ apiKey: "secret-key",
+ dangerouslyAllowInsecureRemoteHttp: true,
+ },
+ });
+
+ expect(result.status).toBe("warn");
+ expect(result.checks).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",
+ level: "warn",
+ }),
+ expect.objectContaining({
+ code: "hermes_gateway_health_ok",
+ }),
+ ]),
+ );
+ expect(fetchMock).toHaveBeenCalled();
+ });
+});
+
+describe("mapFinalResultForTest", () => {
+ it("maps failed statuses into adapter errors", () => {
+ const result = mapFinalResultForTest({
+ terminal: {
+ runId: "run-1",
+ status: "failed",
+ payload: { status: "failed", error: "boom" },
+ },
+ outputChunks: [],
+ sessionKey: "session-key",
+ strategy: "issue",
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("hermes_gateway_run_failed");
+ expect(result.errorMessage).toBe("boom");
+ });
+});
diff --git a/packages/adapters/hermes/src/gateway/server/execute.ts b/packages/adapters/hermes/src/gateway/server/execute.ts
new file mode 100644
index 0000000000..f28ccea4fe
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/execute.ts
@@ -0,0 +1,914 @@
+import type {
+ AdapterExecutionContext,
+ AdapterExecutionResult,
+ UsageSummary,
+} from "@paperclipai/adapter-utils";
+import {
+ asNumber,
+ asString,
+ parseObject,
+ readPaperclipIssueWorkModeFromContext,
+ renderPaperclipWakePrompt,
+ stringifyPaperclipWakePayload,
+} from "@paperclipai/adapter-utils/server-utils";
+import {
+ ADAPTER_TYPE,
+ DEFAULT_EVENT_RECONNECT_MS,
+ DEFAULT_POLL_INTERVAL_MS,
+ DEFAULT_TIMEOUT_SEC,
+ STOP_GRACE_MS,
+} from "../shared/constants.js";
+import {
+ allowsInsecureRemoteHttp,
+ isRemotePlainHttp,
+ remotePlainHttpDeniedMessage,
+} from "./transport-security.js";
+
+type SessionKeyStrategy = "issue" | "agent" | "run" | "none";
+
+type SseFrame = {
+ event: string | null;
+ data: string;
+};
+
+type HermesHttpError = Error & {
+ status?: number;
+ code?: string;
+ retryNotBefore?: string | null;
+ body?: unknown;
+};
+
+type TerminalState = {
+ runId: string;
+ status: string;
+ eventName?: string | null;
+ payload?: Record<string, unknown> | null;
+ output?: string | null;
+};
+
+type ExecutionState = {
+ runId: string;
+ outputChunks: string[];
+ lastEventName: string | null;
+ terminal: TerminalState | null;
+ resolveTerminal: (state: TerminalState) => void;
+ terminalPromise: Promise<TerminalState>;
+};
+
+type TextRedactor = (value: string) => string;
+
+const CRITICAL_HEADERS = new Set([
+ "authorization",
+ "content-type",
+ "accept",
+ "idempotency-key",
+ "x-hermes-session-key",
+]);
+
+const SENSITIVE_KEY_PATTERN =
+ /(^|[_-])(auth|authorization|token|secret|password|api[_-]?key|private[_-]?key)([_-]|$)/i;
+const BEARER_TOKEN_PATTERN = /Bearer\s+\S+/gi;
+const HERMES_SESSION_KEY_HEADER_PATTERN = /(X-Hermes-Session-Key\s*[:=]\s*)([^\s,;]+)/gi;
+const PAPERCLIP_SESSION_KEY_PATTERN =
+ /\bpaperclip:(?:company:[A-Za-z0-9-]+:agent:[A-Za-z0-9-]+(?::(?:issue|run):[A-Za-z0-9-]+)?|run:[A-Za-z0-9-]+)\b/gi;
+
+const TERMINAL_STATUSES = new Set([
+ "completed",
+ "failed",
+ "error",
+ "cancelled",
+ "canceled",
+ "stopped",
+ "interrupted",
+]);
+
+const FAILURE_STATUSES = new Set(["failed", "error"]);
+const CANCELLED_STATUSES = new Set(["cancelled", "canceled", "stopped", "interrupted"]);
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function nonEmpty(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseNonNegativeNumber(value: unknown, fallback: number): number {
+ const parsed = typeof value === "number"
+ ? value
+ : typeof value === "string"
+ ? Number.parseFloat(value)
+ : Number.NaN;
+ if (!Number.isFinite(parsed)) return fallback;
+ return Math.max(0, parsed);
+}
+
+function clamp(value: number, min: number, max: number): number {
+ return Math.min(max, Math.max(min, value));
+}
+
+function normalizeSessionKeyStrategy(value: unknown): SessionKeyStrategy {
+ const raw = asString(value, "issue").trim().toLowerCase();
+ if (raw === "agent" || raw === "run" || raw === "none") return raw;
+ return "issue";
+}
+
+function normalizeBaseUrl(value: string): URL | null {
+ try {
+ const url = new URL(value);
+ if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+ url.pathname = url.pathname.replace(/\/+$/, "");
+ url.search = "";
+ url.hash = "";
+ return url;
+ } catch {
+ return null;
+ }
+}
+
+function apiUrl(baseUrl: URL, path: string): string {
+ const base = baseUrl.toString().replace(/\/+$/, "");
+ return `${base}${path}`;
+}
+
+function issueIdFromContext(ctx: AdapterExecutionContext): string | null {
+ return nonEmpty(ctx.context.taskId) ?? nonEmpty(ctx.context.issueId);
+}
+
+export function resolveSessionKey(input: {
+ strategy: SessionKeyStrategy;
+ companyId: string;
+ agentId: string;
+ runId: string;
+ issueId: string | null;
+}): string | null {
+ if (input.strategy === "none") return null;
+ if (input.strategy === "agent") {
+ return `paperclip:company:${input.companyId}:agent:${input.agentId}`;
+ }
+ if (input.strategy === "run") {
+ return `paperclip:run:${input.runId}`;
+ }
+ const issuePart = input.issueId ? `issue:${input.issueId}` : `run:${input.runId}`;
+ return `paperclip:company:${input.companyId}:agent:${input.agentId}:${issuePart}`;
+}
+
+function stringifyForLog(value: unknown, maxChars = 4_000): string {
+ const text = JSON.stringify(value);
+ return text.length <= maxChars ? text : `${text.slice(0, maxChars)}... [truncated ${text.length - maxChars} chars]`;
+}
+
+function sanitizeSensitiveText(value: string): string {
+ return value
+ .replace(BEARER_TOKEN_PATTERN, "Bearer [redacted]")
+ .replace(HERMES_SESSION_KEY_HEADER_PATTERN, "$1[redacted]")
+ .replace(PAPERCLIP_SESSION_KEY_PATTERN, "[redacted-session-key]");
+}
+
+function escapeRegExp(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function createTextRedactor(secrets: Array<string | null | undefined>): TextRedactor {
+ const exactSecrets = [...new Set(secrets.filter((secret): secret is string => typeof secret === "string" && secret.length >= 4))]
+ .sort((a, b) => b.length - a.length)
+ .map((secret) => ({
+ secret,
+ regex: new RegExp(escapeRegExp(secret), "g"),
+ }));
+
+ return (value: string) => {
+ let result = sanitizeSensitiveText(value);
+ for (const entry of exactSecrets) {
+ result = result.replace(entry.regex, `[redacted len=${entry.secret.length}]`);
+ }
+ return result;
+ };
+}
+
+function redactForLog(value: unknown, keyPath: string[] = [], depth = 0, redactText: TextRedactor = sanitizeSensitiveText): unknown {
+ const key = keyPath[keyPath.length - 1] ?? "";
+ if (typeof value === "string") {
+ if (SENSITIVE_KEY_PATTERN.test(key)) return `[redacted len=${value.length}]`;
+ const sanitized = redactText(value);
+ return sanitized.length > 500
+ ? `${sanitized.slice(0, 500)}... [truncated ${sanitized.length - 500} chars]`
+ : sanitized;
+ }
+ if (value == null || typeof value === "number" || typeof value === "boolean") return value;
+ if (Array.isArray(value)) {
+ if (depth > 5) return "[array-truncated]";
+ return value.slice(0, 40).map((entry, index) => redactForLog(entry, [...keyPath, String(index)], depth + 1, redactText));
+ }
+ if (typeof value === "object") {
+ if (depth > 5) return "[object-truncated]";
+ const out: Record<string, unknown> = {};
+ for (const [entryKey, entryValue] of Object.entries(value as Record<string, unknown>).slice(0, 80)) {
+ out[entryKey] = redactForLog(entryValue, [...keyPath, entryKey], depth + 1, redactText);
+ }
+ return out;
+ }
+ return redactText(String(value));
+}
+
+function parseHeaders(value: unknown): Record<string, string> {
+ const source =
+ typeof value === "string" && value.trim().length > 0
+ ? (() => {
+ try {
+ return JSON.parse(value);
+ } catch {
+ return {};
+ }
+ })()
+ : value;
+ const parsed = parseObject(source);
+ const headers: Record<string, string> = {};
+ for (const [key, entry] of Object.entries(parsed)) {
+ const normalized = key.trim();
+ if (!normalized || CRITICAL_HEADERS.has(normalized.toLowerCase())) continue;
+ if (typeof entry === "string") headers[normalized] = entry;
+ }
+ return headers;
+}
+
+function buildHeaders(input: {
+ apiKey: string;
+ sessionKey: string | null;
+ runId: string;
+ extraHeaders: Record<string, string>;
+ accept: string;
+ contentType?: string;
+}): Record<string, string> {
+ return {
+ ...input.extraHeaders,
+ Authorization: `Bearer ${input.apiKey}`,
+ Accept: input.accept,
+ ...(input.contentType ? { "Content-Type": input.contentType } : {}),
+ "Idempotency-Key": input.runId,
+ ...(input.sessionKey ? { "X-Hermes-Session-Key": input.sessionKey } : {}),
+ };
+}
+
+function buildInput(ctx: AdapterExecutionContext, paperclipApiUrl: string | null): string {
+ const wakePrompt = renderPaperclipWakePrompt(ctx.context.paperclipWake);
+ const wakePayloadJson = stringifyPaperclipWakePayload(ctx.context.paperclipWake);
+ const taskMarkdown = nonEmpty(ctx.context.paperclipTaskMarkdown);
+ const sessionHandoff = nonEmpty(ctx.context.paperclipSessionHandoffMarkdown);
+ const issueWorkMode = readPaperclipIssueWorkModeFromContext(ctx.context);
+ const lines = [
+ `You are ${ctx.agent.name}, an AI agent employee in a Paperclip-managed company.`,
+ "",
+ "Paperclip runtime identity:",
+ `- Agent ID: ${ctx.agent.id}`,
+ `- Company ID: ${ctx.agent.companyId}`,
+ `- Run ID: ${ctx.runId}`,
+ ...(paperclipApiUrl ? [`- Paperclip API URL: ${paperclipApiUrl}`] : []),
+ ...(issueWorkMode ? [`- Issue work mode: ${issueWorkMode}`] : []),
+ "",
+ "Execution contract:",
+ "- Take concrete action in this run when the task is actionable.",
+ "- Do not stop at a plan unless the issue asks for planning only.",
+ "- Leave durable progress and update the issue to a clear final disposition.",
+ "- Use X-Paperclip-Run-Id on mutating Paperclip API requests when a Paperclip API key is available.",
+ "",
+ wakePrompt,
+ ...(sessionHandoff ? ["", sessionHandoff] : []),
+ ...(taskMarkdown ? ["", taskMarkdown] : []),
+ ...(wakePayloadJson
+ ? [
+ "",
+ "Structured wake payload JSON:",
+ "```json",
+ wakePayloadJson,
+ "```",
+ ]
+ : []),
+ ];
+ return lines.filter((line) => line !== null && line !== undefined).join("\n").trim();
+}
+
+function buildRunBody(ctx: AdapterExecutionContext, sessionKey: string | null): Record<string, unknown> {
+ const paperclipApiUrl = nonEmpty(ctx.config.paperclipApiUrl);
+ const payloadTemplate = parseObject(ctx.config.payloadTemplate);
+ const input = nonEmpty(payloadTemplate.input) ?? buildInput(ctx, paperclipApiUrl);
+ const instructions =
+ nonEmpty(ctx.config.instructions) ??
+ nonEmpty(payloadTemplate.instructions) ??
+ "Follow the Paperclip wake instructions exactly. Do not expose secrets in logs, comments, or final output.";
+ return {
+ ...payloadTemplate,
+ input,
+ instructions,
+ ...(sessionKey ? { session_id: sessionKey } : {}),
+ };
+}
+
+async function readResponseJson(response: Response): Promise<unknown> {
+ const text = await response.text();
+ if (!text.trim()) return null;
+ try {
+ return JSON.parse(text);
+ } catch {
+ return { text };
+ }
+}
+
+function classifyHttpError(status: number): { code: string; family: AdapterExecutionResult["errorFamily"] | null } {
+ if (status === 401 || status === 403) return { code: "hermes_gateway_auth_failed", family: null };
+ if (status === 404) return { code: "hermes_gateway_runs_unsupported", family: null };
+ if (status === 429) return { code: "hermes_gateway_rate_limited", family: "transient_upstream" };
+ if (status >= 500) return { code: "hermes_gateway_upstream_error", family: "transient_upstream" };
+ return { code: "hermes_gateway_protocol_error", family: null };
+}
+
+async function fetchJson(input: RequestInfo | URL, init: RequestInit): Promise<unknown> {
+ let response: Response;
+ try {
+ response = await fetch(input, init);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ const fetchErr = new Error(`Hermes gateway request failed: ${message}`) as HermesHttpError;
+ fetchErr.code = "hermes_gateway_connect_failed";
+ throw fetchErr;
+ }
+ const body = await readResponseJson(response);
+ if (!response.ok) {
+ const classified = classifyHttpError(response.status);
+ const err = new Error(`Hermes gateway HTTP ${response.status}`) as HermesHttpError;
+ err.status = response.status;
+ err.code = classified.code;
+ err.retryNotBefore = response.headers.get("retry-after");
+ err.body = body;
+ throw err;
+ }
+ return body;
+}
+
+function extractRunId(value: unknown): string | null {
+ const record = asRecord(value);
+ return nonEmpty(record?.run_id) ?? nonEmpty(record?.runId) ?? nonEmpty(record?.id);
+}
+
+function eventNameFromData(data: unknown, fallback: string | null): string | null {
+ const record = asRecord(data);
+ return nonEmpty(record?.event) ?? nonEmpty(record?.type) ?? fallback;
+}
+
+function parseJsonData(data: string): unknown {
+ try {
+ return JSON.parse(data);
+ } catch {
+ return { text: data };
+ }
+}
+
+export function parseSseFramesForTest(buffer: string): { frames: SseFrame[]; rest: string } {
+ const normalized = buffer.replace(/\r\n/g, "\n");
+ const frames: SseFrame[] = [];
+ let offset = 0;
+ while (true) {
+ const idx = normalized.indexOf("\n\n", offset);
+ if (idx < 0) break;
+ const rawFrame = normalized.slice(offset, idx);
+ offset = idx + 2;
+ let event: string | null = null;
+ const dataLines: string[] = [];
+ for (const line of rawFrame.split("\n")) {
+ if (!line || line.startsWith(":")) continue;
+ if (line.startsWith("event:")) {
+ event = line.slice("event:".length).trim();
+ } else if (line.startsWith("data:")) {
+ dataLines.push(line.slice("data:".length).trimStart());
+ }
+ }
+ if (dataLines.length > 0) frames.push({ event, data: dataLines.join("\n") });
+ }
+ return { frames, rest: normalized.slice(offset) };
+}
+
+function createExecutionState(runId: string): ExecutionState {
+ let resolveTerminal!: (state: TerminalState) => void;
+ const terminalPromise = new Promise<TerminalState>((resolve) => {
+ resolveTerminal = resolve;
+ });
+ return {
+ runId,
+ outputChunks: [],
+ lastEventName: null,
+ terminal: null,
+ resolveTerminal,
+ terminalPromise,
+ };
+}
+
+function markTerminal(state: ExecutionState, terminal: TerminalState): void {
+ if (state.terminal) return;
+ state.terminal = terminal;
+ state.resolveTerminal(terminal);
+}
+
+function extractStatus(value: unknown): string | null {
+ const record = asRecord(value);
+ return nonEmpty(record?.status)?.toLowerCase() ?? null;
+}
+
+function extractOutput(value: unknown): string | null {
+ const record = asRecord(value);
+ if (!record) return null;
+ const direct =
+ nonEmpty(record.output) ??
+ nonEmpty(record.result) ??
+ nonEmpty(record.text) ??
+ nonEmpty(record.summary) ??
+ nonEmpty(record.message);
+ if (direct) return direct;
+ const nested = asRecord(record.data) ?? asRecord(record.payload);
+ return nested ? extractOutput(nested) : null;
+}
+
+async function handleEvent(
+ ctx: AdapterExecutionContext,
+ state: ExecutionState,
+ frame: SseFrame,
+ redactText: TextRedactor = sanitizeSensitiveText,
+): Promise<void> {
+ const parsed = parseJsonData(frame.data);
+ const record = asRecord(parsed);
+ const eventName = eventNameFromData(parsed, frame.event);
+ state.lastEventName = eventName;
+ await ctx.onLog(
+ "stdout",
+ `[hermes-gateway:event] run=${state.runId} event=${eventName ?? "message"} data=${stringifyForLog(redactForLog(parsed, [], 0, redactText), 8_000)}\n`,
+ );
+
+ const delta = nonEmpty(record?.delta) ?? nonEmpty(record?.text_delta);
+ if (eventName === "message.delta" && delta) {
+ const sanitizedDelta = redactText(delta);
+ state.outputChunks.push(sanitizedDelta);
+ await ctx.onLog("stdout", sanitizedDelta);
+ }
+
+ const status = extractStatus(parsed) ?? (eventName?.startsWith("run.") ? eventName.slice(4) : null);
+ if (status && TERMINAL_STATUSES.has(status)) {
+ markTerminal(state, {
+ runId: state.runId,
+ status,
+ eventName,
+ payload: record,
+ output: extractOutput(parsed),
+ });
+ }
+}
+
+async function delay(ms: number, signal: AbortSignal): Promise<void> {
+ if (signal.aborted) return;
+ await new Promise<void>((resolve) => {
+ const timer = setTimeout(resolve, ms);
+ signal.addEventListener(
+ "abort",
+ () => {
+ clearTimeout(timer);
+ resolve();
+ },
+ { once: true },
+ );
+ });
+}
+
+async function pollStatus(input: {
+ ctx: AdapterExecutionContext;
+ baseUrl: URL;
+ headers: Record<string, string>;
+ state: ExecutionState;
+ signal: AbortSignal;
+ intervalMs: number;
+ redactText?: TextRedactor;
+}): Promise<void> {
+ while (!input.signal.aborted && !input.state.terminal) {
+ await delay(input.intervalMs, input.signal);
+ if (input.signal.aborted || input.state.terminal) break;
+ try {
+ const status = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.state.runId)}`), {
+ method: "GET",
+ headers: input.headers,
+ signal: input.signal,
+ });
+ const normalized = extractStatus(status);
+ if (normalized && TERMINAL_STATUSES.has(normalized)) {
+ markTerminal(input.state, {
+ runId: input.state.runId,
+ status: normalized,
+ payload: asRecord(status),
+ output: extractOutput(status),
+ });
+ }
+ } catch (err) {
+ if (input.signal.aborted) return;
+ await input.ctx.onLog("stderr", `[hermes-gateway] status poll failed: ${redactErrorMessage(err, input.redactText)}\n`);
+ }
+ }
+}
+
+async function consumeEvents(input: {
+ ctx: AdapterExecutionContext;
+ baseUrl: URL;
+ headers: Record<string, string>;
+ state: ExecutionState;
+ signal: AbortSignal;
+ reconnectMs: number;
+ redactText?: TextRedactor;
+}): Promise<void> {
+ while (!input.signal.aborted && !input.state.terminal) {
+ try {
+ const response = await fetch(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.state.runId)}/events`), {
+ method: "GET",
+ headers: input.headers,
+ signal: input.signal,
+ });
+ if (!response.ok) {
+ await input.ctx.onLog("stderr", `[hermes-gateway] event stream HTTP ${response.status}; falling back to polling\n`);
+ await delay(input.reconnectMs, input.signal);
+ continue;
+ }
+ if (!response.body) {
+ await input.ctx.onLog("stderr", "[hermes-gateway] event stream response had no body; falling back to polling\n");
+ await delay(input.reconnectMs, input.signal);
+ continue;
+ }
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = "";
+ while (!input.signal.aborted && !input.state.terminal) {
+ const { value, done } = await reader.read();
+ if (done) {
+ if (buffer.trim().length > 0) {
+ const parsed = parseSseFramesForTest(`${buffer}\n\n`);
+ buffer = parsed.rest;
+ for (const frame of parsed.frames) {
+ await handleEvent(input.ctx, input.state, frame, input.redactText);
+ if (input.state.terminal) break;
+ }
+ }
+ break;
+ }
+ buffer += decoder.decode(value, { stream: true });
+ const parsed = parseSseFramesForTest(buffer);
+ buffer = parsed.rest;
+ for (const frame of parsed.frames) {
+ await handleEvent(input.ctx, input.state, frame, input.redactText);
+ if (input.state.terminal) break;
+ }
+ }
+ } catch (err) {
+ if (input.signal.aborted || input.state.terminal) return;
+ await input.ctx.onLog("stderr", `[hermes-gateway] event stream disconnected: ${redactErrorMessage(err, input.redactText)}\n`);
+ }
+ if (!input.state.terminal) await delay(input.reconnectMs, input.signal);
+ }
+}
+
+function parseUsage(value: unknown): UsageSummary | undefined {
+ const record = asRecord(value);
+ if (!record) return undefined;
+ const source = asRecord(record.usage) ?? record;
+ const inputTokens = asNumber(source.input_tokens ?? source.inputTokens ?? source.input, 0);
+ const outputTokens = asNumber(source.output_tokens ?? source.outputTokens ?? source.output, 0);
+ const cachedInputTokens = asNumber(source.cached_input_tokens ?? source.cachedInputTokens, 0);
+ if (inputTokens <= 0 && outputTokens <= 0 && cachedInputTokens <= 0) return undefined;
+ return {
+ inputTokens,
+ outputTokens,
+ ...(cachedInputTokens > 0 ? { cachedInputTokens } : {}),
+ };
+}
+
+function parseCostUsd(value: unknown): number | null {
+ const record = asRecord(value);
+ const raw = record?.cost_usd ?? record?.costUsd ?? asRecord(record?.usage)?.cost_usd ?? asRecord(record?.usage)?.costUsd;
+ const parsed = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseFloat(raw) : Number.NaN;
+ return Number.isFinite(parsed) ? parsed : null;
+}
+
+function extractSessionId(value: unknown): string | null {
+ const record = asRecord(value);
+ return nonEmpty(record?.session_id) ?? nonEmpty(record?.sessionId) ?? nonEmpty(asRecord(record?.data)?.session_id);
+}
+
+function extractModel(value: unknown): string | null {
+ const record = asRecord(value);
+ return nonEmpty(record?.model) ?? nonEmpty(asRecord(record?.usage)?.model);
+}
+
+function extractErrorMessage(value: unknown): string | null {
+ const record = asRecord(value);
+ return nonEmpty(record?.error) ?? nonEmpty(record?.message) ?? nonEmpty(record?.detail) ?? extractOutput(value);
+}
+
+function terminalResultCode(status: string): { exitCode: number; signal: string | null; errorCode: string | null } {
+ if (status === "completed") return { exitCode: 0, signal: null, errorCode: null };
+ if (FAILURE_STATUSES.has(status)) return { exitCode: 1, signal: null, errorCode: "hermes_gateway_run_failed" };
+ if (CANCELLED_STATUSES.has(status)) return { exitCode: 1, signal: "SIGTERM", errorCode: "hermes_gateway_cancelled" };
+ return { exitCode: 1, signal: null, errorCode: "hermes_gateway_protocol_error" };
+}
+
+export function mapFinalResultForTest(input: {
+ terminal: TerminalState;
+ outputChunks: string[];
+ sessionKey: string | null;
+ strategy: SessionKeyStrategy;
+ redactText?: TextRedactor;
+}): AdapterExecutionResult {
+ const redactText = input.redactText ?? sanitizeSensitiveText;
+ const payload = input.terminal.payload ?? {};
+ const output = redactText(
+ input.terminal.output ?? extractOutput(payload) ?? input.outputChunks.join("").trim(),
+ );
+ const sessionId = extractSessionId(payload) ?? input.sessionKey;
+ const sessionDisplayId = sessionId ? redactText(sessionId) : null;
+ const mapped = terminalResultCode(input.terminal.status);
+ const usage = parseUsage(payload);
+ const costUsd = parseCostUsd(payload);
+ const errorMessage = mapped.errorCode
+ ? redactText(extractErrorMessage(payload) ?? `Hermes run ${input.terminal.status}`)
+ : null;
+ return {
+ exitCode: mapped.exitCode,
+ signal: mapped.signal,
+ timedOut: false,
+ provider: "hermes_gateway",
+ model: extractModel(payload),
+ ...(mapped.errorCode ? { errorCode: mapped.errorCode } : {}),
+ ...(errorMessage ? { errorMessage } : {}),
+ ...(usage ? { usage } : {}),
+ ...(costUsd !== null ? { costUsd } : {}),
+ ...(output ? { summary: output.slice(0, 2_000) } : {}),
+ sessionId: sessionDisplayId,
+ sessionParams: {
+ hermesRunId: input.terminal.runId,
+ ...(sessionId && sessionDisplayId === sessionId ? { hermesSessionId: sessionId } : {}),
+ strategy: input.strategy,
+ },
+ sessionDisplayId,
+ resultJson: {
+ run_id: input.terminal.runId,
+ status: input.terminal.status,
+ session_id: sessionDisplayId,
+ last_event: input.terminal.eventName ?? null,
+ output: output ?? "",
+ usage: usage ?? null,
+ cost_usd: costUsd,
+ },
+ };
+}
+
+async function stopRun(input: {
+ ctx: AdapterExecutionContext;
+ baseUrl: URL;
+ headers: Record<string, string>;
+ runId: string;
+ redactText?: TextRedactor;
+}): Promise<Record<string, unknown> | null> {
+ try {
+ const stopped = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.runId)}/stop`), {
+ method: "POST",
+ headers: input.headers,
+ });
+ await input.ctx.onLog("stdout", `[hermes-gateway] stop requested for run ${input.runId}\n`);
+ return asRecord(stopped);
+ } catch (err) {
+ await input.ctx.onLog("stderr", `[hermes-gateway] stop request failed: ${redactErrorMessage(err, input.redactText)}\n`);
+ return null;
+ }
+}
+
+async function fetchFinalStatus(input: {
+ baseUrl: URL;
+ headers: Record<string, string>;
+ runId: string;
+ deadlineMs: number;
+}): Promise<Record<string, unknown> | null> {
+ const deadline = Date.now() + input.deadlineMs;
+ while (Date.now() < deadline) {
+ try {
+ const status = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.runId)}`), {
+ method: "GET",
+ headers: input.headers,
+ });
+ const record = asRecord(status);
+ const normalized = extractStatus(status);
+ if (normalized && TERMINAL_STATUSES.has(normalized)) return record;
+ } catch {
+ return null;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 500));
+ }
+ return null;
+}
+
+function redactErrorMessage(err: unknown, redactText: TextRedactor = sanitizeSensitiveText): string {
+ if (err instanceof Error) return redactText(err.message);
+ return redactText(String(err));
+}
+
+function errorResult(err: unknown, redactText: TextRedactor = sanitizeSensitiveText): AdapterExecutionResult {
+ const hermesError = err as HermesHttpError;
+ const code = hermesError.code ?? "hermes_gateway_protocol_error";
+ const classified = hermesError.status ? classifyHttpError(hermesError.status) : null;
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: code,
+ errorFamily: classified?.family ?? (code === "hermes_gateway_connect_failed" ? "transient_upstream" : null),
+ retryNotBefore: hermesError.retryNotBefore ?? null,
+ errorMessage: redactErrorMessage(err, redactText),
+ errorMeta: {
+ ...(hermesError.status ? { status: hermesError.status } : {}),
+ ...(hermesError.body ? { body: redactForLog(hermesError.body, [], 0, redactText) as Record<string, unknown> } : {}),
+ },
+ };
+}
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+ const apiBaseUrlValue = asString(ctx.config.apiBaseUrl ?? ctx.config.url, "").trim();
+ if (!apiBaseUrlValue) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: "hermes_gateway_api_base_url_missing",
+ errorMessage: "Hermes gateway adapter requires apiBaseUrl.",
+ };
+ }
+
+ const baseUrl = normalizeBaseUrl(apiBaseUrlValue);
+ if (!baseUrl) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: "hermes_gateway_api_base_url_invalid",
+ errorMessage: `Invalid Hermes gateway apiBaseUrl: ${apiBaseUrlValue}`,
+ };
+ }
+ if (isRemotePlainHttp(baseUrl) && !allowsInsecureRemoteHttp(ctx.config)) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: "hermes_gateway_plain_http_remote_denied",
+ errorMessage: remotePlainHttpDeniedMessage(baseUrl.hostname),
+ };
+ }
+
+ const apiKey = nonEmpty(ctx.config.apiKey) ?? nonEmpty(ctx.config.token);
+ if (!apiKey) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: "hermes_gateway_api_key_missing",
+ errorMessage: "Hermes gateway adapter requires apiKey.",
+ };
+ }
+
+ const timeoutSec = parseNonNegativeNumber(ctx.config.timeoutSec, DEFAULT_TIMEOUT_SEC);
+ const timeoutMs = timeoutSec > 0 ? Math.ceil(timeoutSec * 1000) : 0;
+ const reconnectMs = Math.floor(clamp(parseNonNegativeNumber(ctx.config.eventReconnectMs, DEFAULT_EVENT_RECONNECT_MS), 250, 30_000));
+ const pollIntervalMs = Math.floor(clamp(parseNonNegativeNumber(ctx.config.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS), 250, 10_000));
+ const strategy = normalizeSessionKeyStrategy(ctx.config.sessionKeyStrategy);
+ const sessionKey = resolveSessionKey({
+ strategy,
+ companyId: ctx.agent.companyId,
+ agentId: ctx.agent.id,
+ runId: ctx.runId,
+ issueId: issueIdFromContext(ctx),
+ });
+ const extraHeaders = parseHeaders(ctx.config.headers);
+ const runHeaders = buildHeaders({
+ apiKey,
+ sessionKey,
+ runId: ctx.runId,
+ extraHeaders,
+ accept: "application/json",
+ contentType: "application/json",
+ });
+ const eventHeaders = buildHeaders({
+ apiKey,
+ sessionKey,
+ runId: ctx.runId,
+ extraHeaders,
+ accept: "text/event-stream",
+ });
+ const redactText = createTextRedactor([
+ apiKey,
+ sessionKey,
+ runHeaders.Authorization,
+ runHeaders["X-Hermes-Session-Key"],
+ ]);
+ const body = buildRunBody(ctx, sessionKey);
+
+ await ctx.onMeta?.({
+ adapterType: ADAPTER_TYPE,
+ command: "POST /v1/runs",
+ commandArgs: [baseUrl.origin, "/v1/runs"],
+ context: {
+ runId: ctx.runId,
+ timeoutSec,
+ eventReconnectMs: reconnectMs,
+ sessionKeyStrategy: strategy,
+ hasSessionKey: Boolean(sessionKey),
+ },
+ });
+ await ctx.onLog("stdout", `[hermes-gateway] creating run at ${baseUrl.origin}/v1/runs (timeout=${timeoutSec}s, session=${strategy})\n`);
+ await ctx.onLog("stdout", `[hermes-gateway] request headers (redacted): ${stringifyForLog(redactForLog(runHeaders, [], 0, redactText), 3_000)}\n`);
+
+ let runId: string | null = null;
+ try {
+ const created = await fetchJson(apiUrl(baseUrl, "/v1/runs"), {
+ method: "POST",
+ headers: runHeaders,
+ body: JSON.stringify(body),
+ });
+ runId = extractRunId(created);
+ if (!runId) {
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ errorCode: "hermes_gateway_protocol_error",
+ errorMessage: "Hermes /v1/runs response did not include run_id.",
+ errorMeta: { response: redactForLog(created, [], 0, redactText) as Record<string, unknown> },
+ };
+ }
+ } catch (err) {
+ return errorResult(err, redactText);
+ }
+
+ await ctx.onLog("stdout", `[hermes-gateway] run created: ${runId}\n`);
+
+ const state = createExecutionState(runId);
+ const controller = new AbortController();
+ void consumeEvents({
+ ctx,
+ baseUrl,
+ headers: eventHeaders,
+ state,
+ signal: controller.signal,
+ reconnectMs,
+ redactText,
+ }).catch(() => undefined);
+ void pollStatus({
+ ctx,
+ baseUrl,
+ headers: eventHeaders,
+ state,
+ signal: controller.signal,
+ intervalMs: pollIntervalMs,
+ redactText,
+ }).catch(() => undefined);
+
+ let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+ const timeoutPromise = new Promise<"timeout">((resolve) => {
+ if (timeoutMs <= 0) return;
+ timeoutTimer = setTimeout(() => resolve("timeout"), timeoutMs);
+ });
+
+ const outcome = await Promise.race([state.terminalPromise, timeoutPromise]);
+ if (timeoutTimer) clearTimeout(timeoutTimer);
+ controller.abort();
+
+ if (outcome === "timeout") {
+ await stopRun({ ctx, baseUrl, headers: eventHeaders, runId, redactText });
+ const finalStatus = await fetchFinalStatus({ baseUrl, headers: eventHeaders, runId, deadlineMs: STOP_GRACE_MS });
+ return {
+ exitCode: 1,
+ signal: null,
+ timedOut: true,
+ errorCode: "hermes_gateway_timeout",
+ errorMessage: `Hermes gateway run timed out after ${timeoutSec}s.`,
+ provider: "hermes_gateway",
+ resultJson: {
+ run_id: runId,
+ status: extractStatus(finalStatus) ?? "timeout",
+ last_event: state.lastEventName,
+ final_status: redactForLog(finalStatus, [], 0, redactText),
+ },
+ sessionParams: {
+ hermesRunId: runId,
+ strategy,
+ },
+ sessionDisplayId: sessionKey ? redactText(sessionKey) : null,
+ };
+ }
+
+ return mapFinalResultForTest({
+ terminal: outcome,
+ outputChunks: state.outputChunks,
+ sessionKey,
+ strategy,
+ redactText,
+ });
+}
diff --git a/packages/adapters/hermes/src/gateway/server/index.ts b/packages/adapters/hermes/src/gateway/server/index.ts
new file mode 100644
index 0000000000..b29873d6ec
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/index.ts
@@ -0,0 +1,45 @@
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+export { execute, resolveSessionKey, parseSseFramesForTest, mapFinalResultForTest } from "./execute.js";
+export { testEnvironment } from "./test.js";
+export { getConfigSchema } from "./config-schema.js";
+
+function readString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+ deserialize(raw) {
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+ const record = raw as Record<string, unknown>;
+ const hermesSessionId = readString(record.hermesSessionId) ?? readString(record.sessionId);
+ const sessionKey = readString(record.sessionKey);
+ const hermesRunId = readString(record.hermesRunId);
+ const strategy = readString(record.strategy);
+ if (!hermesSessionId && !sessionKey && !hermesRunId) return null;
+ return {
+ ...(hermesRunId ? { hermesRunId } : {}),
+ ...(hermesSessionId ? { hermesSessionId } : {}),
+ ...(sessionKey ? { sessionKey } : {}),
+ ...(strategy ? { strategy } : {}),
+ };
+ },
+ serialize(params) {
+ if (!params) return null;
+ const hermesSessionId = readString(params.hermesSessionId) ?? readString(params.sessionId);
+ const sessionKey = readString(params.sessionKey);
+ const hermesRunId = readString(params.hermesRunId);
+ const strategy = readString(params.strategy);
+ if (!hermesSessionId && !sessionKey && !hermesRunId) return null;
+ return {
+ ...(hermesRunId ? { hermesRunId } : {}),
+ ...(hermesSessionId ? { hermesSessionId } : {}),
+ ...(sessionKey ? { sessionKey } : {}),
+ ...(strategy ? { strategy } : {}),
+ };
+ },
+ getDisplayId(params) {
+ if (!params) return null;
+ return readString(params.hermesSessionId) ?? readString(params.sessionKey) ?? readString(params.hermesRunId);
+ },
+};
diff --git a/packages/adapters/hermes/src/gateway/server/test.ts b/packages/adapters/hermes/src/gateway/server/test.ts
new file mode 100644
index 0000000000..da601a3e81
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/test.ts
@@ -0,0 +1,127 @@
+import type {
+ AdapterEnvironmentCheck,
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import { asString } from "@paperclipai/adapter-utils/server-utils";
+import {
+ allowsInsecureRemoteHttp,
+ isLoopbackHostname,
+ isRemotePlainHttp,
+ remotePlainHttpDeniedMessage,
+} from "./transport-security.js";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+ if (checks.some((check) => check.level === "error")) return "fail";
+ if (checks.some((check) => check.level === "warn")) return "warn";
+ return "pass";
+}
+
+function normalizeBaseUrl(value: string): URL | null {
+ try {
+ const url = new URL(value);
+ if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+ return url;
+ } catch {
+ return null;
+ }
+}
+
+export async function testEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const checks: AdapterEnvironmentCheck[] = [];
+ const apiBaseUrl = asString(ctx.config.apiBaseUrl ?? ctx.config.url, "").trim();
+ const apiKey = asString(ctx.config.apiKey ?? ctx.config.token, "").trim();
+
+ if (!apiBaseUrl) {
+ checks.push({
+ code: "hermes_gateway_api_base_url_missing",
+ level: "error",
+ message: "Hermes Gateway requires apiBaseUrl.",
+ hint: "Enable Hermes API server and set apiBaseUrl, for example http://127.0.0.1:8642.",
+ });
+ }
+
+ const parsed = apiBaseUrl ? normalizeBaseUrl(apiBaseUrl) : null;
+ if (apiBaseUrl && !parsed) {
+ checks.push({
+ code: "hermes_gateway_api_base_url_invalid",
+ level: "error",
+ message: "apiBaseUrl must be an http:// or https:// URL.",
+ });
+ }
+
+ if (!apiKey) {
+ checks.push({
+ code: "hermes_gateway_api_key_missing",
+ level: "error",
+ message: "Hermes Gateway requires apiKey.",
+ hint: "Set Hermes API_SERVER_KEY and copy the same value into adapterConfig.apiKey.",
+ });
+ }
+
+ if (parsed && isRemotePlainHttp(parsed) && !allowsInsecureRemoteHttp(ctx.config)) {
+ checks.push({
+ code: "hermes_gateway_plain_http_remote_denied",
+ level: "error",
+ message: remotePlainHttpDeniedMessage(parsed.hostname),
+ hint: "Use https:// for remote Hermes gateways. Loopback http://localhost and http://127.0.0.1 remain allowed.",
+ });
+ } else if (parsed && isRemotePlainHttp(parsed)) {
+ checks.push({
+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",
+ level: "warn",
+ message: "Unsafe dev escape hatch enabled for non-loopback HTTP Hermes traffic.",
+ hint: "Remove the escape hatch and use HTTPS before using this gateway for real credentials.",
+ });
+ } else if (parsed?.protocol === "http:" && isLoopbackHostname(parsed.hostname)) {
+ checks.push({
+ code: "hermes_gateway_loopback_http_allowed",
+ level: "info",
+ message: "Loopback HTTP Hermes gateway URL is allowed.",
+ });
+ }
+
+ if (checks.some((check) => check.level === "error") || !parsed || !apiKey) {
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+ }
+
+ try {
+ const healthUrl = new URL("/health", parsed);
+ const response = await fetch(healthUrl, {
+ method: "GET",
+ headers: {
+ Authorization: `Bearer ${apiKey}`,
+ Accept: "application/json",
+ },
+ signal: AbortSignal.timeout(2_000),
+ });
+ checks.push({
+ code: response.ok ? "hermes_gateway_health_ok" : "hermes_gateway_health_failed",
+ level: response.ok ? "info" : "warn",
+ message: response.ok
+ ? "Hermes Gateway health endpoint is reachable."
+ : `Hermes Gateway health endpoint returned HTTP ${response.status}.`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "hermes_gateway_health_unreachable",
+ level: "warn",
+ message: "Could not reach Hermes Gateway health endpoint.",
+ detail: err instanceof Error ? err.message : String(err),
+ });
+ }
+
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/hermes/src/gateway/server/transport-security.ts b/packages/adapters/hermes/src/gateway/server/transport-security.ts
new file mode 100644
index 0000000000..00d7deceff
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/server/transport-security.ts
@@ -0,0 +1,36 @@
+export const INSECURE_REMOTE_HTTP_ESCAPE_HATCH = "dangerouslyAllowInsecureRemoteHttp";
+
+export function parseBooleanLike(value: unknown): boolean | null {
+ if (typeof value === "boolean") return value;
+ if (typeof value !== "string") return null;
+ const normalized = value.trim().toLowerCase();
+ if (["1", "true", "yes", "on"].includes(normalized)) return true;
+ if (["0", "false", "no", "off"].includes(normalized)) return false;
+ return null;
+}
+
+export function isLoopbackHostname(hostname: string): boolean {
+ const value = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+ return (
+ value === "localhost" ||
+ value === "::1" ||
+ value === "0:0:0:0:0:0:0:1" ||
+ value === "127.0.0.1" ||
+ /^127(?:\.\d{1,3}){3}$/.test(value)
+ );
+}
+
+export function isRemotePlainHttp(url: URL): boolean {
+ return url.protocol === "http:" && !isLoopbackHostname(url.hostname);
+}
+
+export function allowsInsecureRemoteHttp(config: Record<string, unknown>): boolean {
+ return parseBooleanLike(config[INSECURE_REMOTE_HTTP_ESCAPE_HATCH]) === true;
+}
+
+export function remotePlainHttpDeniedMessage(hostname: string): string {
+ return (
+ `Hermes gateway apiBaseUrl uses remote plain HTTP for "${hostname}". ` +
+ `Use HTTPS or set ${INSECURE_REMOTE_HTTP_ESCAPE_HATCH}=true only for unsafe local development.`
+ );
+}
diff --git a/packages/adapters/hermes/src/gateway/shared/constants.ts b/packages/adapters/hermes/src/gateway/shared/constants.ts
new file mode 100644
index 0000000000..de974c47a7
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/shared/constants.ts
@@ -0,0 +1,7 @@
+export const ADAPTER_TYPE = "hermes_gateway";
+export const ADAPTER_LABEL = "Hermes Gateway";
+
+export const DEFAULT_TIMEOUT_SEC = 120;
+export const DEFAULT_EVENT_RECONNECT_MS = 2_000;
+export const DEFAULT_POLL_INTERVAL_MS = 1_000;
+export const STOP_GRACE_MS = 10_000;
diff --git a/packages/adapters/hermes/src/gateway/ui/index.ts b/packages/adapters/hermes/src/gateway/ui/index.ts
new file mode 100644
index 0000000000..eae592b1e0
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/ui/index.ts
@@ -0,0 +1 @@
+export { parseHermesGatewayStdoutLine as parseStdoutLine } from "./parse-stdout.js";
diff --git a/packages/adapters/hermes/src/gateway/ui/parse-stdout.ts b/packages/adapters/hermes/src/gateway/ui/parse-stdout.ts
new file mode 100644
index 0000000000..df9db752dd
--- /dev/null
+++ b/packages/adapters/hermes/src/gateway/ui/parse-stdout.ts
@@ -0,0 +1,47 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+
+function safeJsonParse(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string {
+ return typeof value === "string" ? value : "";
+}
+
+export function parseHermesGatewayStdoutLine(line: string, ts: string): TranscriptEntry[] {
+ const trimmed = line.trim();
+ if (!trimmed) return [];
+
+ const eventMatch = trimmed.match(/^\[hermes-gateway:event\]\s+run=([^\s]+)\s+event=([^\s]+)\s+data=(.*)$/s);
+ if (eventMatch) {
+ const eventName = eventMatch[2];
+ const data = asRecord(safeJsonParse(eventMatch[3]));
+ if (eventName === "message.delta") {
+ const delta = asString(data?.delta) || asString(data?.text_delta);
+ return delta ? [{ kind: "assistant", ts, text: delta, delta: true }] : [];
+ }
+ if (eventName === "run.failed" || eventName === "run.error") {
+ const message = asString(data?.error) || asString(data?.message) || "Hermes run failed";
+ return [{ kind: "stderr", ts, text: message }];
+ }
+ if (eventName === "reasoning.available") {
+ return [{ kind: "thinking", ts, text: "Hermes reasoning available" }];
+ }
+ return [{ kind: "system", ts, text: `Hermes event: ${eventName}` }];
+ }
+
+ if (trimmed.startsWith("[hermes-gateway]")) {
+ return [{ kind: "system", ts, text: trimmed.replace(/^\[hermes-gateway\]\s*/, "") }];
+ }
+
+ return [{ kind: "stdout", ts, text: line }];
+}
diff --git a/packages/adapters/hermes/src/index.test.ts b/packages/adapters/hermes/src/index.test.ts
new file mode 100644
index 0000000000..03e8809262
--- /dev/null
+++ b/packages/adapters/hermes/src/index.test.ts
@@ -0,0 +1,63 @@
+import { expect, test } from "vitest";
+
+import {
+ createHermesGatewayServerAdapter,
+ createHermesLocalServerAdapter,
+ createServerAdapter,
+ hermesGatewayType,
+} from "./index.js";
+import { createServerAdapter as createGatewayServerAdapterFromSubpath } from "./gateway/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.sessionManagement?.nativeContextManagement).toBe("confirmed");
+ expect(adapter.supportsLocalAgentJwt).toBe(true);
+ expect(adapter.supportsInstructionsBundle).toBe(true);
+ expect(adapter.instructionsPathKey).toBe("instructionsFilePath");
+ expect(adapter.getRuntimeCommandSpec?.({ command: "hermes-dev" })).toMatchObject({
+ command: "hermes-dev",
+ detectCommand: "hermes-dev",
+ installCommand: null,
+ });
+ expect(typeof adapter.detectModel).toBe("function");
+ expect(typeof adapter.getConfigSchema).toBe("function");
+});
+
+test("root package export keeps explicit local and gateway adapter factories", () => {
+ const localAdapter = createHermesLocalServerAdapter();
+ const gatewayAdapter = createHermesGatewayServerAdapter();
+
+ expect(localAdapter.type).toBe("hermes_local");
+ expect(gatewayAdapter.type).toBe("hermes_gateway");
+ expect(hermesGatewayType).toBe("hermes_gateway");
+ expect(gatewayAdapter.supportsLocalAgentJwt).toBe(false);
+ expect(gatewayAdapter.supportsInstructionsBundle).toBe(false);
+});
+
+test("gateway subpath export exposes the Hermes Gateway adapter entrypoint", () => {
+ const adapter = createGatewayServerAdapterFromSubpath();
+
+ expect(adapter.type).toBe("hermes_gateway");
+ expect(typeof adapter.execute).toBe("function");
+ expect(typeof adapter.testEnvironment).toBe("function");
+ expect(typeof adapter.sessionCodec?.deserialize).toBe("function");
+ expect(adapter.sessionManagement?.nativeContextManagement).toBe("confirmed");
+ expect(typeof adapter.getConfigSchema).toBe("function");
+});
+
+test("Hermes adapter exposes bundled Paperclip task bridge skill", async () => {
+ const adapter = createServerAdapter();
+ const snapshot = await adapter.listSkills?.({
+ adapterType: "hermes_local",
+ agentId: "11111111-1111-4111-8111-111111111111",
+ companyId: "22222222-2222-4222-8222-222222222222",
+ config: {},
+ });
+
+ expect(snapshot?.entries.some((entry) => entry.runtimeName === "paperclip-task-bridge")).toBe(true);
+});
diff --git a/packages/adapters/hermes/src/index.ts b/packages/adapters/hermes/src/index.ts
new file mode 100644
index 0000000000..3494bf5970
--- /dev/null
+++ b/packages/adapters/hermes/src/index.ts
@@ -0,0 +1,176 @@
+/**
+ * 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 {
+ AdapterRuntimeCommandSpec,
+ AdapterSessionManagement,
+ ServerAdapterModule,
+} from "@paperclipai/adapter-utils";
+
+import { ADAPTER_TYPE, ADAPTER_LABEL } from "./shared/constants.js";
+import {
+ execute,
+ testEnvironment,
+ sessionCodec,
+ listSkills,
+ syncSkills,
+ detectModel,
+ getConfigSchema,
+} from "./server/index.js";
+import { resolveHermesCommand } from "./server/execute.js";
+
+export const type = ADAPTER_TYPE;
+export const label = ADAPTER_LABEL;
+export {
+ createServerAdapter as createHermesGatewayServerAdapter,
+ agentConfigurationDoc as hermesGatewayAgentConfigurationDoc,
+ label as hermesGatewayLabel,
+ models as hermesGatewayModels,
+ type as hermesGatewayType,
+} from "./gateway/index.js";
+
+/**
+ * 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: { id: string; label: string }[] = [];
+
+const sessionManagement: AdapterSessionManagement = {
+ supportsSessionResume: true,
+ nativeContextManagement: "confirmed",
+ defaultSessionCompaction: {
+ enabled: true,
+ maxSessionRuns: 0,
+ maxRawInputTokens: 0,
+ maxSessionAgeHours: 0,
+ },
+};
+
+function getRuntimeCommandSpec(config: Record<string, unknown>): AdapterRuntimeCommandSpec {
+ const command = resolveHermesCommand(config);
+ return {
+ command,
+ detectCommand: command,
+ installCommand: null,
+ };
+}
+
+/**
+ * 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 |
+
+## Hermes-Originated Paperclip Tasks
+
+This adapter package also ships a Hermes-facing Paperclip task bridge skill:
+\`paperclip-task-bridge\`. Use it when a user starts in Hermes and asks Hermes
+to create, comment on, update, or list Paperclip tasks.
+
+Configure credentials through Hermes env/profile secrets, never in prompt text:
+
+- \`PAPERCLIP_API_URL\` - Paperclip base URL, with or without \`/api\`
+- \`PAPERCLIP_BRIDGE_API_KEY\` - Paperclip agent API key created with \`scope.kind = "task_bridge"\`
+- optional fallback \`PAPERCLIP_API_KEY\` - must still be a task_bridge key, never a normal claimed agent key
+- optional \`PAPERCLIP_COMPANY_ID\`, \`PAPERCLIP_AGENT_ID\`, and \`PAPERCLIP_RUN_ID\`
+
+The bridge is separate from adapter execution:
+
+- \`hermes_local\` means Paperclip shells out to local \`hermes chat\`.
+- \`hermes_gateway\` means Paperclip wakes remote Hermes through Hermes's API server.
+- \`paperclip-task-bridge\` means Hermes calls Paperclip's REST API to manage tasks.
+
+Create task bridge keys with a parent issue or project boundary. Do not expose
+normal claimed Paperclip agent API keys to internet-facing Hermes chat/webhook
+task-bridge surfaces.
+
+## 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(): ServerAdapterModule {
+ return {
+ type,
+ execute,
+ testEnvironment,
+ sessionCodec,
+ sessionManagement,
+ listSkills,
+ syncSkills,
+ models,
+ supportsLocalAgentJwt: true,
+ supportsInstructionsBundle: true,
+ instructionsPathKey: "instructionsFilePath",
+ requiresMaterializedRuntimeSkills: false,
+ getRuntimeCommandSpec,
+ agentConfigurationDoc,
+ detectModel,
+ getConfigSchema,
+ };
+}
+
+export { createServerAdapter as createHermesLocalServerAdapter };
diff --git a/packages/adapters/hermes/src/server/command-resolution.test.ts b/packages/adapters/hermes/src/server/command-resolution.test.ts
new file mode 100644
index 0000000000..0462ad5a0c
--- /dev/null
+++ b/packages/adapters/hermes/src/server/command-resolution.test.ts
@@ -0,0 +1,48 @@
+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 });
+ }
+});
diff --git a/packages/adapters/hermes/src/server/config-schema.ts b/packages/adapters/hermes/src/server/config-schema.ts
new file mode 100644
index 0000000000..25d3a5bd69
--- /dev/null
+++ b/packages/adapters/hermes/src/server/config-schema.ts
@@ -0,0 +1,108 @@
+import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";
+
+import {
+ DEFAULT_GRACE_SEC,
+ DEFAULT_TIMEOUT_SEC,
+ VALID_PROVIDERS,
+} from "../shared/constants.js";
+
+function providerLabel(provider: string): string {
+ if (provider === "auto") return "Auto";
+ if (provider === "openai-codex") return "OpenAI Codex";
+ if (provider === "kimi-coding") return "Kimi Coding";
+ if (provider === "minimax-cn") return "MiniMax China";
+ return provider
+ .split("-")
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+ .join(" ");
+}
+
+export function getConfigSchema(): AdapterConfigSchema {
+ return {
+ fields: [
+ {
+ key: "provider",
+ label: "Provider",
+ type: "select",
+ default: "auto",
+ options: VALID_PROVIDERS.map((provider) => ({
+ value: provider,
+ label: providerLabel(provider),
+ })),
+ hint: "Usually auto. Set this only when Hermes cannot infer the provider from the model or ~/.hermes/config.yaml.",
+ },
+ {
+ key: "timeoutSec",
+ label: "Timeout seconds",
+ type: "number",
+ default: DEFAULT_TIMEOUT_SEC,
+ },
+ {
+ key: "graceSec",
+ label: "Grace seconds",
+ type: "number",
+ default: DEFAULT_GRACE_SEC,
+ hint: "Seconds to wait after SIGTERM before killing the Hermes process.",
+ },
+ {
+ key: "maxTurnsPerRun",
+ label: "Max turns per run",
+ type: "number",
+ hint: "Optional Hermes --max-turns limit for tool-calling iterations.",
+ },
+ {
+ key: "toolsets",
+ label: "Toolsets",
+ type: "text",
+ hint: "Optional comma-separated Hermes toolsets, such as terminal,file,web.",
+ },
+ {
+ key: "persistSession",
+ label: "Persist session",
+ type: "toggle",
+ default: true,
+ hint: "Resume Hermes sessions across Paperclip heartbeats.",
+ },
+ {
+ key: "worktreeMode",
+ label: "Hermes worktree mode",
+ type: "toggle",
+ default: false,
+ hint: "Pass Hermes --worktree.",
+ },
+ {
+ key: "checkpoints",
+ label: "Checkpoints",
+ type: "toggle",
+ default: false,
+ hint: "Pass Hermes --checkpoints.",
+ },
+ {
+ key: "quiet",
+ label: "Quiet output",
+ type: "toggle",
+ default: true,
+ hint: "Pass Hermes --quiet for cleaner Paperclip run transcripts.",
+ },
+ {
+ key: "verbose",
+ label: "Verbose output",
+ type: "toggle",
+ default: false,
+ hint: "Pass Hermes --verbose.",
+ },
+ {
+ key: "paperclipApiUrl",
+ label: "Paperclip API URL",
+ type: "text",
+ hint: "Optional API base override. Defaults to PAPERCLIP_API_URL.",
+ },
+ {
+ key: "promptTemplate",
+ label: "Prompt template",
+ type: "textarea",
+ hint: "Optional custom prompt template with {{variable}} placeholders.",
+ },
+ ],
+ };
+}
diff --git a/packages/adapters/hermes/src/server/detect-model.test.ts b/packages/adapters/hermes/src/server/detect-model.test.ts
new file mode 100644
index 0000000000..05ee2d8fc3
--- /dev/null
+++ b/packages/adapters/hermes/src/server/detect-model.test.ts
@@ -0,0 +1,186 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, test } from "vitest";
+
+import { parseModelFromConfig, resolveProvider } from "./detect-model.js";
+import { testEnvironment } from "./test.js";
+
+const providerEnvKeys = [
+ "ANTHROPIC_API_KEY",
+ "OPENROUTER_API_KEY",
+ "OPENAI_API_KEY",
+ "ZAI_API_KEY",
+ "KIMI_API_KEY",
+ "MINIMAX_API_KEY",
+];
+
+const previousEnv = {
+ HOME: process.env.HOME,
+ USERPROFILE: process.env.USERPROFILE,
+ HOMEDRIVE: process.env.HOMEDRIVE,
+ HOMEPATH: process.env.HOMEPATH,
+ ...Object.fromEntries(providerEnvKeys.map((key) => [key, process.env[key]])),
+};
+
+afterEach(async () => {
+ for (const [key, value] of Object.entries(previousEnv)) {
+ if (value === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = value;
+ }
+ }
+});
+
+test("parseModelFromConfig tracks api_key presence without exposing the raw secret", () => {
+ const parsed = parseModelFromConfig([
+ "model:",
+ " default: oca/gpt-5.4",
+ " provider: custom",
+ " base_url: https://example.invalid/litellm",
+ " api_key: super-secret-value",
+ "",
+ ].join("\n"));
+
+ expect(parsed).toBeTruthy();
+ expect(parsed?.hasApiKey).toBe(true);
+ expect(Object.hasOwn(parsed ?? {}, "apiKey")).toBe(false);
+});
+
+test("resolveProvider does not fall through to model inference when Hermes config provider is unsupported but matches the requested model", () => {
+ expect(resolveProvider({
+ explicitProvider: undefined,
+ detectedProvider: "custom",
+ detectedModel: "oca/gpt-5.4",
+ detectedBaseUrl: "https://example.invalid/litellm",
+ detectedHasApiKey: true,
+ model: "oca/gpt-5.4",
+ })).toEqual({
+ provider: "auto",
+ resolvedFrom: "hermesConfigUnsupported:custom",
+ });
+});
+
+test("resolveProvider also defers to Hermes runtime when the matching config omits provider but includes runtime signals", () => {
+ expect(resolveProvider({
+ explicitProvider: undefined,
+ detectedProvider: "",
+ detectedModel: "oca/gpt-5.4",
+ detectedBaseUrl: "https://example.invalid/litellm",
+ detectedHasApiKey: true,
+ model: "oca/gpt-5.4",
+ })).toEqual({
+ provider: "auto",
+ resolvedFrom: "hermesConfigRuntime",
+ });
+});
+
+test("resolveProvider still infers from the requested model when Hermes config is for a different model", () => {
+ expect(resolveProvider({
+ explicitProvider: undefined,
+ detectedProvider: "custom",
+ detectedModel: "oca/gpt-5.4",
+ detectedBaseUrl: "https://example.invalid/litellm",
+ detectedHasApiKey: true,
+ model: "claude-sonnet-4",
+ })).toEqual({
+ provider: "anthropic",
+ resolvedFrom: "modelInference",
+ });
+});
+
+async function withHermesHomeConfig(
+ configLines: string[],
+ fn: () => Promise<void>,
+) {
+ const tempHome = await mkdtemp(join(tmpdir(), "hermes-paperclip-adapter-"));
+ const hermesDir = join(tempHome, ".hermes");
+ const configPath = join(hermesDir, "config.yaml");
+
+ await mkdir(hermesDir, { recursive: true });
+ await writeFile(configPath, `${configLines.join("\n")}\n`, "utf8");
+ process.env.HOME = tempHome;
+ process.env.USERPROFILE = tempHome;
+ delete process.env.HOMEDRIVE;
+ delete process.env.HOMEPATH;
+ for (const key of providerEnvKeys) {
+ delete process.env[key];
+ }
+
+ try {
+ await fn();
+ } finally {
+ await rm(tempHome, { recursive: true, force: true });
+ }
+}
+
+test("testEnvironment does not warn about missing API keys when Hermes config provides a supported provider api_key", async () => {
+ await withHermesHomeConfig([
+ "model:",
+ " default: openrouter/gpt-4.1-mini",
+ " provider: openrouter",
+ " api_key: test-secret",
+ ], async () => {
+ const result = await testEnvironment({
+ companyId: "company-test",
+ adapterType: "hermes_local",
+ config: {
+ hermesCommand: "python3",
+ model: "openrouter/gpt-4.1-mini",
+ },
+ });
+
+ const codes = result.checks.map((check) => check.code);
+
+ expect(codes.includes("hermes_no_api_keys")).toBe(false);
+ expect(result.status).toBe("pass");
+ });
+});
+
+test("testEnvironment describes provider-omitted runtime config without inventing provider auto", async () => {
+ await withHermesHomeConfig([
+ "model:",
+ " default: oca/gpt-5.4",
+ " base_url: https://example.invalid/litellm",
+ " api_key: test-secret",
+ ], async () => {
+ const result = await testEnvironment({
+ companyId: "company-test",
+ adapterType: "hermes_local",
+ config: {
+ hermesCommand: "python3",
+ model: "oca/gpt-5.4",
+ },
+ });
+
+ const apiKeyCheck = result.checks.find((check) => check.code === "hermes_api_key_in_config");
+ expect(apiKeyCheck).toBeTruthy();
+ expect(apiKeyCheck?.message).toMatch(/without an explicit provider/i);
+ expect(apiKeyCheck?.message).not.toMatch(/provider "auto"/i);
+ });
+});
+
+test("testEnvironment does not warn about missing API keys when Hermes config provides a custom provider base_url and api_key", async () => {
+ await withHermesHomeConfig([
+ "model:",
+ " default: oca/gpt-5.4",
+ " provider: custom",
+ " base_url: https://example.invalid/litellm",
+ " api_key: test-secret",
+ ], async () => {
+ const result = await testEnvironment({
+ companyId: "company-test",
+ adapterType: "hermes_local",
+ config: {
+ hermesCommand: "python3",
+ model: "oca/gpt-5.4",
+ },
+ });
+
+ const codes = result.checks.map((check) => check.code);
+
+ expect(codes.includes("hermes_no_api_keys")).toBe(false);
+ expect(result.status).toBe("pass");
+ });
+});
diff --git a/packages/adapters/hermes/src/server/detect-model.ts b/packages/adapters/hermes/src/server/detect-model.ts
new file mode 100644
index 0000000000..fc92ca4601
--- /dev/null
+++ b/packages/adapters/hermes/src/server/detect-model.ts
@@ -0,0 +1,217 @@
+/**
+ * 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.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { MODEL_PREFIX_PROVIDER_HINTS, VALID_PROVIDERS } from "../shared/constants.js";
+
+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 async function detectModel(
+ configPath?: string,
+): Promise<DetectedModel | null> {
+ const filePath = configPath ?? join(homedir(), ".hermes", "config.yaml");
+
+ let content: string;
+ try {
+ content = await readFile(filePath, "utf-8");
+ } catch {
+ return null;
+ }
+
+ return parseModelFromConfig(content);
+}
+
+/**
+ * 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 function parseModelFromConfig(content: string): DetectedModel | null {
+ const lines = content.split("\n");
+ let model = "";
+ let provider = "";
+ let baseUrl = "";
+ let hasApiKey = false;
+ let apiMode = "";
+ let inModelSection = false;
+ let modelSectionIndent = 0;
+
+ for (const line of lines) {
+ const trimmed = line.trimEnd();
+ const indent = line.length - line.trimStart().length;
+
+ // Track model: section (indent 0)
+ if (/^model:\s*$/.test(trimmed) && indent === 0) {
+ inModelSection = true;
+ modelSectionIndent = 0;
+ continue;
+ }
+
+ // We left the model section if indent drops back to the section level or below
+ if (inModelSection && indent <= modelSectionIndent && trimmed && !trimmed.startsWith("#")) {
+ inModelSection = false;
+ }
+
+ if (inModelSection) {
+ const match = trimmed.match(/^\s*(\w+)\s*:\s*(.+)$/);
+ if (match) {
+ const key = match[1];
+ const val = match[2].trim().replace(/#.*$/, "").trim().replace(/^['"]|['"]$/g, "");
+ if (key === "default") model = val;
+ if (key === "provider") provider = val;
+ if (key === "base_url") baseUrl = val;
+ if (key === "api_key") hasApiKey = val.length > 0;
+ if (key === "api_mode") apiMode = val;
+ }
+ }
+ }
+
+ if (!model) return null;
+
+ return { model, provider, baseUrl, hasApiKey, apiMode, source: "config" };
+}
+
+/**
+ * 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 function inferProviderFromModel(model: string): string | undefined {
+ const lower = model.toLowerCase();
+
+ // Strip provider/ prefix if present (e.g. "anthropic/claude-sonnet-4")
+ const bareName = lower.includes("/") ? lower.split("/").pop()! : lower;
+
+ for (const [prefix, hint] of MODEL_PREFIX_PROVIDER_HINTS) {
+ if (bareName.startsWith(prefix)) {
+ return hint;
+ }
+ }
+
+ return 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 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 } {
+ const {
+ explicitProvider,
+ detectedProvider,
+ detectedModel,
+ detectedBaseUrl,
+ detectedHasApiKey,
+ detectedApiMode,
+ model,
+ } = options;
+
+ // 1. Explicit provider from adapterConfig — user override, always wins
+ if (explicitProvider && (VALID_PROVIDERS as readonly string[]).includes(explicitProvider)) {
+ return { provider: explicitProvider, resolvedFrom: "adapterConfig" };
+ }
+
+ const supportedProviders = VALID_PROVIDERS as readonly string[];
+ const configMatchesRequestedModel =
+ !!detectedModel &&
+ !!model &&
+ detectedModel.toLowerCase() === model.toLowerCase();
+
+ // 2. Provider from Hermes config file — but ONLY if the config model matches
+ // the requested model. Otherwise the config provider is for a different model
+ // and would cause exactly the kind of routing bug we're fixing.
+ if (
+ configMatchesRequestedModel &&
+ !!detectedProvider &&
+ supportedProviders.includes(detectedProvider)
+ ) {
+ return { provider: detectedProvider, resolvedFrom: "hermesConfig" };
+ }
+
+ const hasRuntimeSignals = !!detectedBaseUrl || !!detectedHasApiKey || !!detectedApiMode;
+
+ // 3a. Matching Hermes config with an unsupported provider (for example "custom")
+ // should not fall through to model-name inference, because that can route to
+ // the wrong provider entirely. Defer back to Hermes's own runtime resolution.
+ if (configMatchesRequestedModel && !!detectedProvider && !supportedProviders.includes(detectedProvider)) {
+ return {
+ provider: "auto",
+ resolvedFrom: `hermesConfigUnsupported:${detectedProvider}`,
+ };
+ }
+
+ // 3b. Matching Hermes config may omit provider entirely while still specifying
+ // enough runtime information (base_url, api_key, api_mode) for Hermes itself.
+ // In that case, also defer to Hermes instead of doing a wrong prefix inference.
+ if (configMatchesRequestedModel && !detectedProvider && hasRuntimeSignals) {
+ return {
+ provider: "auto",
+ resolvedFrom: "hermesConfigRuntime",
+ };
+ }
+
+ // 4. Infer from model name prefix
+ if (model) {
+ const inferred = inferProviderFromModel(model);
+ if (inferred) {
+ return { provider: inferred, resolvedFrom: "modelInference" };
+ }
+ }
+
+ // 5. Let Hermes auto-detect
+ return { provider: "auto", resolvedFrom: "auto" };
+}
diff --git a/packages/adapters/hermes/src/server/execute.ts b/packages/adapters/hermes/src/server/execute.ts
new file mode 100644
index 0000000000..ae85c29857
--- /dev/null
+++ b/packages/adapters/hermes/src/server/execute.ts
@@ -0,0 +1,584 @@
+/**
+ * Server-side execution logic for the Hermes Agent adapter.
+ *
+ * Spawns `hermes chat -q "..." -Q` as a child process, streams output,
+ * and returns structured results to Paperclip.
+ *
+ * Verified CLI flags (hermes chat):
+ * -q/--query single query (non-interactive)
+ * -Q/--quiet quiet mode (no banner/spinner, only response + session_id)
+ * -m/--model model name (e.g. anthropic/claude-sonnet-4)
+ * -t/--toolsets comma-separated toolsets to enable
+ * --provider inference provider (auto, openrouter, nous, etc.)
+ * -r/--resume resume session by ID
+ * -w/--worktree isolated git worktree
+ * -v/--verbose verbose output
+ * --checkpoints filesystem checkpoints
+ * --yolo bypass dangerous-command approval prompts (agents have no TTY)
+ * --source session source tag for filtering
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type {
+ AdapterExecutionContext,
+ AdapterExecutionResult,
+ UsageSummary,
+} from "@paperclipai/adapter-utils";
+
+import {
+ runChildProcess,
+ buildPaperclipEnv,
+ renderTemplate,
+ ensureAbsoluteDirectory,
+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+ joinPromptSections,
+ renderPaperclipWakePrompt,
+ stringifyPaperclipWakePayload,
+} from "@paperclipai/adapter-utils/server-utils";
+
+import {
+ HERMES_CLI,
+ DEFAULT_TIMEOUT_SEC,
+ DEFAULT_GRACE_SEC,
+ DEFAULT_MODEL,
+ VALID_PROVIDERS,
+} from "../shared/constants.js";
+
+import {
+ detectModel,
+ resolveProvider,
+} from "./detect-model.js";
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+function cfgString(v: unknown): string | undefined {
+ return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function cfgNumber(v: unknown): number | undefined {
+ return typeof v === "number" ? v : undefined;
+}
+function cfgBoolean(v: unknown): boolean | undefined {
+ return typeof v === "boolean" ? v : undefined;
+}
+function cfgStringArray(v: unknown): string[] | undefined {
+ return Array.isArray(v) && v.every((i) => typeof i === "string")
+ ? (v as string[])
+ : undefined;
+}
+
+export function resolveHermesCommand(config: Record<string, unknown>): string {
+ return cfgString(config.hermesCommand) || cfgString(config.command) || HERMES_CLI;
+}
+
+// ---------------------------------------------------------------------------
+// Wake-up prompt builder
+// ---------------------------------------------------------------------------
+
+const HERMES_DEFAULT_PROMPT_TEMPLATE = [
+ 'You are "{{agent.name}}", an AI agent employee in a Paperclip-managed company.',
+ "",
+ "Paperclip runtime identity:",
+ "- Agent ID: {{agent.id}}",
+ "- Company ID: {{agent.companyId}}",
+ "- Run ID: {{run.id}}",
+ "- API base: {{paperclipApiUrl}}",
+ "",
+ "Paperclip API guidance:",
+ "- Use `curl` from the terminal for Paperclip API calls; browser/web extraction tools may not reach localhost.",
+ "- Use `$PAPERCLIP_API_URL`, `$PAPERCLIP_API_KEY`, and `$PAPERCLIP_RUN_ID`; do not hard-code local ports or copy secrets into comments.",
+ "- Displayed command logs may redact secrets; rely on environment variables instead of printed token values.",
+ "- Include `-H \"Authorization: Bearer $PAPERCLIP_API_KEY\"` on API requests.",
+ "- Include `-H \"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\"` on mutating issue requests.",
+ "- For multiline comments or status updates, preserve newlines with `jq --arg` or a heredoc-fed helper rather than hand-escaping JSON.",
+ "",
+ "Safe multiline update pattern:",
+ "```bash",
+ "api=\"${PAPERCLIP_API_URL%/}\"",
+ "case \"$api\" in */api) ;; *) api=\"$api/api\" ;; esac",
+ "",
+ "body=$(cat <<'MD'",
+ "Summary line",
+ "",
+ "- Detail one",
+ "- Detail two",
+ "MD",
+ ")",
+ "jq -n --arg status done --arg comment \"$body\" '{status:$status, comment:$comment}' | \\",
+ " curl -sS -X PATCH \"$api/issues/{{context.issueId}}\" \\",
+ " -H \"Authorization: Bearer $PAPERCLIP_API_KEY\" \\",
+ " -H \"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\" \\",
+ " -H \"Content-Type: application/json\" \\",
+ " --data-binary @-",
+ "```",
+ "",
+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+].join("\n");
+
+function renderConditionalSections(template: string, vars: Record<string, unknown>): string {
+ const isTruthy = (key: string) => {
+ if (key === "noTask") return !vars.taskId;
+ const value = vars[key];
+ if (Array.isArray(value)) return value.length > 0;
+ return Boolean(value);
+ };
+ return template.replace(
+ /\{\{#([a-zA-Z0-9_.-]+)\}\}([\s\S]*?)\{\{\/\1\}\}/g,
+ (_match, key: string, body: string) => (isTruthy(key) ? body : ""),
+ );
+}
+
+export function buildPrompt(
+ ctx: AdapterExecutionContext,
+ config: Record<string, unknown>,
+ options: { resumedSession?: boolean } = {},
+): string {
+ const template = cfgString(config.promptTemplate) || HERMES_DEFAULT_PROMPT_TEMPLATE;
+
+ const context = (ctx as any).context || {};
+ const taskId = cfgString(context.taskId) || cfgString(context.issueId) || cfgString(ctx.config?.taskId);
+ const taskTitle = cfgString(context.taskTitle) || cfgString(ctx.config?.taskTitle) || "";
+ const taskBody = cfgString(context.taskBody) || cfgString(ctx.config?.taskBody) || "";
+ const commentId = cfgString(context.commentId) || cfgString(context.wakeCommentId) || cfgString(ctx.config?.commentId) || "";
+ const wakeReason = cfgString(context.wakeReason) || cfgString(ctx.config?.wakeReason) || "";
+ const agentName = ctx.agent?.name || "Hermes Agent";
+ const companyName = cfgString(context.companyName) || cfgString(ctx.config?.companyName) || "";
+ const projectName = cfgString(context.projectName) || cfgString(ctx.config?.projectName) || "";
+
+ // Build API URL — ensure it has the /api path
+ let paperclipApiUrl =
+ cfgString(config.paperclipApiUrl) ||
+ process.env.PAPERCLIP_API_URL ||
+ "http://127.0.0.1:3100/api";
+ // Ensure /api suffix
+ if (!paperclipApiUrl.endsWith("/api")) {
+ paperclipApiUrl = paperclipApiUrl.replace(/\/+$/, "") + "/api";
+ }
+
+ const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, {
+ resumedSession: options.resumedSession === true,
+ });
+ const paperclipTaskMarkdown = cfgString(context.paperclipTaskMarkdown)?.trim() || "";
+ const sessionHandoffMarkdown = cfgString(context.paperclipSessionHandoffMarkdown)?.trim() || "";
+ const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake) || "";
+
+ const vars: Record<string, unknown> = {
+ agentId: ctx.agent?.id || "",
+ agentName,
+ companyId: ctx.agent?.companyId || "",
+ companyName,
+ runId: ctx.runId || "",
+ agent: ctx.agent || {},
+ company: { id: ctx.agent?.companyId || "", name: companyName },
+ run: { id: ctx.runId || "", source: "on_demand" },
+ context,
+ taskId: taskId || "",
+ taskTitle,
+ taskBody,
+ commentId,
+ wakeReason,
+ projectName,
+ paperclipApiUrl,
+ paperclipWakePrompt: wakePrompt,
+ paperclipTaskMarkdown,
+ taskContext: paperclipTaskMarkdown,
+ paperclipWakeJson: wakePayloadJson,
+ wakePayloadJson,
+ paperclipApiKeyEnv: "PAPERCLIP_API_KEY",
+ paperclipRunIdEnv: "PAPERCLIP_RUN_ID",
+ };
+
+ const rendered = renderTemplate(renderConditionalSections(template, vars), vars);
+ return joinPromptSections([
+ wakePrompt,
+ sessionHandoffMarkdown,
+ paperclipTaskMarkdown,
+ rendered,
+ ]);
+}
+
+// ---------------------------------------------------------------------------
+// Output parsing
+// ---------------------------------------------------------------------------
+
+/** Regex to extract session ID from Hermes quiet-mode output: "session_id: <id>" */
+const SESSION_ID_REGEX = /^session_id:\s*(\S+)/m;
+
+/** Regex for legacy session output format */
+const SESSION_ID_REGEX_LEGACY = /session[_ ](?:id|saved)[:\s]+([a-zA-Z0-9_-]+)/i;
+
+/** Regex to extract token usage from Hermes output. */
+const TOKEN_USAGE_REGEX =
+ /tokens?[:\s]+(\d+)\s*(?:input|in)\b.*?(\d+)\s*(?:output|out)\b/i;
+
+/** Regex to extract cost from Hermes output. */
+const COST_REGEX = /(?:cost|spent)[:\s]*\$?([\d.]+)/i;
+
+interface ParsedOutput {
+ sessionId?: string;
+ response?: string;
+ usage?: UsageSummary;
+ costUsd?: number;
+ errorMessage?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Response cleaning
+// ---------------------------------------------------------------------------
+
+/** Strip noise lines from a Hermes response (tool output, system messages, etc.) */
+function cleanResponse(raw: string): string {
+ return raw
+ .split("\n")
+ .filter((line) => {
+ const t = line.trim();
+ if (!t) return true; // keep blank lines for paragraph separation
+ if (t.startsWith("[tool]") || t.startsWith("[hermes]") || t.startsWith("[paperclip]")) return false;
+ if (t.startsWith("session_id:")) return false;
+ if (/^\[\d{4}-\d{2}-\d{2}T/.test(t)) return false;
+ if (/^\[done\]\s*┊/.test(t)) return false;
+ if (/^┊\s*[\p{Emoji_Presentation}]/u.test(t) && !/^┊\s*💬/.test(t)) return false;
+ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(t)) return false;
+ return true;
+ })
+ .map((line) => {
+ let t = line.replace(/^[\s]*┊\s*💬\s*/, "").trim();
+ t = t.replace(/^\[done\]\s*/, "").trim();
+ return t;
+ })
+ .join("\n")
+ .replace(/\n{3,}/g, "\n\n")
+ .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Output parsing
+// ---------------------------------------------------------------------------
+
+function parseHermesOutput(stdout: string, stderr: string): ParsedOutput {
+ const combined = stdout + "\n" + stderr;
+ const result: ParsedOutput = {};
+
+ // In quiet mode, Hermes outputs:
+ // <response text>
+ //
+ // session_id: <id>
+ const sessionMatch = stdout.match(SESSION_ID_REGEX);
+ if (sessionMatch?.[1]) {
+ result.sessionId = sessionMatch?.[1] ?? null;
+ // The response is everything before the session_id line
+ const sessionLineIdx = stdout.lastIndexOf("\nsession_id:");
+ if (sessionLineIdx > 0) {
+ result.response = cleanResponse(stdout.slice(0, sessionLineIdx));
+ }
+ } else {
+ // Legacy format (non-quiet mode)
+ const legacyMatch = combined.match(SESSION_ID_REGEX_LEGACY);
+ if (legacyMatch?.[1]) {
+ result.sessionId = legacyMatch?.[1] ?? null;
+ }
+ // In non-quiet mode, extract clean response from stdout by
+ // filtering out tool lines, system messages, and noise
+ const cleaned = cleanResponse(stdout);
+ if (cleaned.length > 0) {
+ result.response = cleaned;
+ }
+ }
+
+ // Extract token usage
+ const usageMatch = combined.match(TOKEN_USAGE_REGEX);
+ if (usageMatch) {
+ result.usage = {
+ inputTokens: parseInt(usageMatch[1], 10) || 0,
+ outputTokens: parseInt(usageMatch[2], 10) || 0,
+ };
+ }
+
+ // Extract cost
+ const costMatch = combined.match(COST_REGEX);
+ if (costMatch?.[1]) {
+ result.costUsd = parseFloat(costMatch[1]);
+ }
+
+ // Check for error patterns in stderr
+ if (stderr.trim()) {
+ const errorLines = stderr
+ .split("\n")
+ .filter((line) => /error|exception|traceback|failed/i.test(line))
+ .filter((line) => !/INFO|DEBUG|warn/i.test(line)); // skip log-level noise
+ if (errorLines.length > 0) {
+ result.errorMessage = errorLines.slice(0, 5).join("\n");
+ }
+ }
+
+ return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main execute
+// ---------------------------------------------------------------------------
+
+export async function execute(
+ ctx: AdapterExecutionContext,
+): Promise<AdapterExecutionResult> {
+ const config = (ctx.config ?? ctx.agent?.adapterConfig ?? {}) as Record<string, unknown>;
+
+ // ── Resolve configuration ──────────────────────────────────────────────
+ const hermesCmd = resolveHermesCommand(config);
+ const model = cfgString(config.model) || DEFAULT_MODEL;
+ const timeoutSec = cfgNumber(config.timeoutSec) || DEFAULT_TIMEOUT_SEC;
+ const graceSec = cfgNumber(config.graceSec) || DEFAULT_GRACE_SEC;
+ const maxTurns = cfgNumber(config.maxTurnsPerRun);
+ const toolsets = cfgString(config.toolsets) || cfgStringArray(config.enabledToolsets)?.join(",");
+ const extraArgs = cfgStringArray(config.extraArgs);
+ const persistSession = cfgBoolean(config.persistSession) !== false;
+ const worktreeMode = cfgBoolean(config.worktreeMode) === true;
+ const checkpoints = cfgBoolean(config.checkpoints) === true;
+ const prevSessionId = cfgString(
+ (ctx.runtime?.sessionParams as Record<string, unknown> | null)?.sessionId,
+ );
+
+ // ── Resolve provider (defense in depth) ────────────────────────────────
+ // Priority chain:
+ // 1. Explicit provider in adapterConfig (user override)
+ // 2. Provider from ~/.hermes/config.yaml (detected at runtime)
+ // 3. Provider inferred from model name prefix
+ // 4. "auto" (let Hermes decide)
+ //
+ // This ensures that even if the agent was created before provider tracking
+ // was added, or if the model was changed without updating provider, the
+ // correct provider is still used.
+ let detectedConfig: Awaited<ReturnType<typeof detectModel>> | null = null;
+ const explicitProvider = cfgString(config.provider);
+
+ if (!explicitProvider) {
+ try {
+ detectedConfig = await detectModel();
+ } catch {
+ // Non-fatal — detection failure shouldn't block execution
+ }
+ }
+
+ const { provider: resolvedProvider, resolvedFrom } = resolveProvider({
+ explicitProvider,
+ detectedProvider: detectedConfig?.provider,
+ detectedModel: detectedConfig?.model,
+ detectedBaseUrl: detectedConfig?.baseUrl,
+ detectedHasApiKey: detectedConfig?.hasApiKey,
+ detectedApiMode: detectedConfig?.apiMode,
+ model,
+ });
+
+ // ── Load agent instructions file (Paperclip instruction bundles) ──────
+ // Paperclip can materialize managed instructions into instructionsFilePath;
+ // when present, inject that bundle into the Hermes prompt.
+ const instructionsFilePath = cfgString(config.instructionsFilePath);
+ let agentInstructions = "";
+ if (instructionsFilePath) {
+ try {
+ agentInstructions = await fs.readFile(instructionsFilePath, "utf-8");
+ const loadedInstructionsLength = agentInstructions.length;
+ const instructionsFileDir = path.dirname(instructionsFilePath);
+ agentInstructions += `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}/.`;
+ await ctx.onLog(
+ "stdout",
+ `[hermes] Loaded agent instructions from ${instructionsFilePath} (${loadedInstructionsLength} chars)\n`,
+ );
+ } catch (err) {
+ const reason = err instanceof Error ? err.message : String(err);
+ // Non-fatal: log to stdout with an explicit "Warning:" prefix so the
+ // Paperclip UI doesn't render this as a red error (stderr output is
+ // surfaced as an error signal even when execution continues).
+ await ctx.onLog(
+ "stdout",
+ `[hermes] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
+ );
+ }
+ }
+
+ // ── Build prompt ───────────────────────────────────────────────────────
+ let prompt = buildPrompt(ctx, config, { resumedSession: Boolean(prevSessionId) });
+ if (agentInstructions) {
+ prompt = agentInstructions + "\n\n---\n\n" + prompt;
+ }
+
+ // ── Build command args ─────────────────────────────────────────────────
+ // Use -Q (quiet) to get clean output: just response + session_id line
+ const useQuiet = cfgBoolean(config.quiet) === true; // default false
+ const args: string[] = ["chat", "-q", prompt];
+ if (useQuiet) args.push("-Q");
+
+ if (model) {
+ args.push("-m", model);
+ }
+
+ // Always pass --provider when we have a resolved one (not "auto").
+ // "auto" means Hermes will decide on its own — no need to pass it.
+ if (resolvedProvider !== "auto") {
+ args.push("--provider", resolvedProvider);
+ }
+
+ if (toolsets) {
+ args.push("-t", toolsets);
+ }
+
+ if (maxTurns && maxTurns > 0) {
+ args.push("--max-turns", String(maxTurns));
+ }
+
+ if (worktreeMode) args.push("-w");
+ if (checkpoints) args.push("--checkpoints");
+ if (cfgBoolean(config.verbose) === true) args.push("-v");
+
+ // Tag sessions as "tool" source so they don't clutter the user's session history.
+ // Requires hermes-agent >= PR #3255 (feat/session-source-tag).
+ args.push("--source", "tool");
+
+ // Bypass Hermes dangerous-command approval prompts.
+ // Paperclip agents run as non-interactive subprocesses with no TTY,
+ // so approval prompts would always timeout and deny legitimate commands
+ // (curl, python3 -c, etc.). Agents operate in a sandbox — the approval
+ // system is designed for human-attended interactive sessions.
+ args.push("--yolo");
+
+ if (persistSession && prevSessionId) {
+ args.push("--resume", prevSessionId);
+ }
+
+ if (extraArgs?.length) {
+ args.push(...extraArgs);
+ }
+
+ // ── Build environment ──────────────────────────────────────────────────
+ const userEnv = config.env as Record<string, string> | undefined;
+ const env: Record<string, string> = {
+ ...(process.env as Record<string, string>),
+ ...(userEnv && typeof userEnv === "object" ? userEnv : {}),
+ ...buildPaperclipEnv(ctx.agent),
+ };
+
+ if (ctx.runId) env.PAPERCLIP_RUN_ID = ctx.runId;
+
+ // BUG FIX: Inject authToken as PAPERCLIP_API_KEY (matches adapter-claude-local behavior)
+ if ((ctx as any).authToken) env.PAPERCLIP_API_KEY = (ctx as any).authToken;
+
+ // BUG FIX: Read task context from ctx.context (wake context), not ctx.config (adapter config)
+ const ctxContext = (ctx as any).context || {};
+ const envTaskId = cfgString(ctxContext.taskId) || cfgString(ctxContext.issueId) || cfgString(ctx.config?.taskId);
+ if (envTaskId) env.PAPERCLIP_TASK_ID = envTaskId;
+ const envWakeReason = cfgString(ctxContext.wakeReason) || cfgString(ctx.config?.wakeReason);
+ if (envWakeReason) env.PAPERCLIP_WAKE_REASON = envWakeReason;
+ const envCommentId = cfgString(ctxContext.commentId) || cfgString(ctxContext.wakeCommentId) || cfgString(ctx.config?.commentId);
+ if (envCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = envCommentId;
+ const wakePayloadJson = stringifyPaperclipWakePayload(ctxContext.paperclipWake);
+ if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
+
+ // ── Resolve working directory ──────────────────────────────────────────
+ const cwd =
+ cfgString(config.cwd) || cfgString(ctx.config?.workspaceDir) || ".";
+ try {
+ await ensureAbsoluteDirectory(cwd);
+ } catch {
+ // Non-fatal
+ }
+
+ // ── Log start ──────────────────────────────────────────────────────────
+ await ctx.onLog(
+ "stdout",
+ `[hermes] Starting Hermes Agent (model=${model}, provider=${resolvedProvider} [${resolvedFrom}], timeout=${timeoutSec}s${maxTurns ? `, max_turns=${maxTurns}` : ""})\n`,
+ );
+ if (prevSessionId) {
+ await ctx.onLog(
+ "stdout",
+ `[hermes] Resuming session: ${prevSessionId}\n`,
+ );
+ }
+
+ // ── Execute ────────────────────────────────────────────────────────────
+ // Hermes writes non-error noise to stderr (MCP init, INFO logs, etc).
+ // Paperclip renders all stderr as red/error in the UI.
+ // Wrap onLog to reclassify benign stderr lines as stdout.
+ const wrappedOnLog = async (stream: "stdout" | "stderr", chunk: string) => {
+ if (stream === "stderr") {
+ const trimmed = chunk.trimEnd();
+ // Benign patterns that should NOT appear as errors:
+ // - Structured log lines: [timestamp] INFO/DEBUG/WARN: ...
+ // - MCP server registration messages
+ // - Python import/site noise
+ const isBenign = /^\[?\d{4}[-/]\d{2}[-/]\d{2}T/.test(trimmed) || // structured timestamps
+ /^[A-Z]+:\s+(INFO|DEBUG|WARN|WARNING)\b/.test(trimmed) || // log levels
+ /Successfully registered all tools/.test(trimmed) ||
+ /MCP [Ss]erver/.test(trimmed) ||
+ /tool registered successfully/.test(trimmed) ||
+ /Application initialized/.test(trimmed);
+ if (isBenign) {
+ return ctx.onLog("stdout", chunk);
+ }
+ }
+ return ctx.onLog(stream, chunk);
+ };
+
+ const result = await runChildProcess(ctx.runId, hermesCmd, args, {
+ cwd,
+ env,
+ timeoutSec,
+ graceSec,
+ onLog: wrappedOnLog,
+ });
+
+ // ── Parse output ───────────────────────────────────────────────────────
+ const parsed = parseHermesOutput(result.stdout || "", result.stderr || "");
+
+ await ctx.onLog(
+ "stdout",
+ `[hermes] Exit code: ${result.exitCode ?? "null"}, timed out: ${result.timedOut}\n`,
+ );
+ if (parsed.sessionId) {
+ await ctx.onLog("stdout", `[hermes] Session: ${parsed.sessionId}\n`);
+ }
+
+ // ── Build result ───────────────────────────────────────────────────────
+ const executionResult: AdapterExecutionResult = {
+ exitCode: result.exitCode,
+ signal: result.signal,
+ timedOut: result.timedOut,
+ provider: resolvedProvider,
+ model,
+ };
+
+ if (parsed.errorMessage) {
+ executionResult.errorMessage = parsed.errorMessage;
+ }
+
+ if (parsed.usage) {
+ executionResult.usage = parsed.usage;
+ }
+
+ if (parsed.costUsd !== undefined) {
+ executionResult.costUsd = parsed.costUsd;
+ }
+
+ // Summary from agent response
+ if (parsed.response) {
+ executionResult.summary = parsed.response.slice(0, 2000);
+ }
+
+ // Set resultJson so Paperclip can persist run metadata (used for UI display + auto-comments)
+ executionResult.resultJson = {
+ result: parsed.response || "",
+ session_id: parsed.sessionId || null,
+ usage: parsed.usage || null,
+ cost_usd: parsed.costUsd ?? null,
+ };
+
+ // Store session ID for next run
+ if (persistSession && parsed.sessionId) {
+ executionResult.sessionParams = { sessionId: parsed.sessionId };
+ executionResult.sessionDisplayId = parsed.sessionId.slice(0, 16);
+ }
+
+ return executionResult;
+}
diff --git a/packages/adapters/hermes/src/server/index.ts b/packages/adapters/hermes/src/server/index.ts
new file mode 100644
index 0000000000..2382374d46
--- /dev/null
+++ b/packages/adapters/hermes/src/server/index.ts
@@ -0,0 +1,49 @@
+/**
+ * Server-side adapter module exports.
+ */
+
+export { execute } from "./execute.js";
+export { testEnvironment } from "./test.js";
+export { detectModel, parseModelFromConfig, resolveProvider, inferProviderFromModel } from "./detect-model.js";
+export { getConfigSchema } from "./config-schema.js";
+export {
+ listHermesSkills as listSkills,
+ syncHermesSkills as syncSkills,
+ resolveHermesDesiredSkillNames as resolveDesiredSkillNames,
+} from "./skills.js";
+
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+function readNonEmptyString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Session codec for structured validation and migration of session parameters.
+ *
+ * Hermes Agent uses a single `sessionId` for cross-heartbeat session continuity
+ * via the `--resume` CLI flag. The codec validates and normalizes this field.
+ */
+export const sessionCodec: AdapterSessionCodec = {
+ deserialize(raw: unknown) {
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+ const record = raw as Record<string, unknown>;
+ const sessionId =
+ readNonEmptyString(record.sessionId) ??
+ readNonEmptyString(record.session_id);
+ if (!sessionId) return null;
+ return { sessionId };
+ },
+ serialize(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ const sessionId =
+ readNonEmptyString(params.sessionId) ??
+ readNonEmptyString(params.session_id);
+ if (!sessionId) return null;
+ return { sessionId };
+ },
+ getDisplayId(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ return readNonEmptyString(params.sessionId) ?? readNonEmptyString(params.session_id);
+ },
+};
diff --git a/packages/adapters/hermes/src/server/paperclip-task-bridge.test.ts b/packages/adapters/hermes/src/server/paperclip-task-bridge.test.ts
new file mode 100644
index 0000000000..1801407269
--- /dev/null
+++ b/packages/adapters/hermes/src/server/paperclip-task-bridge.test.ts
@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const helperPath = path.resolve(__dirname, "../../skills/paperclip-task-bridge/paperclip-task.mjs");
+const apiKey = "pc_test_secret_should_not_print";
+
+type RequestRecord = {
+ method: string;
+ url: string;
+ headers: http.IncomingHttpHeaders;
+ body: unknown;
+};
+
+function runHelper(args: string[], env: Record<string, string>) {
+ return new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve, reject) => {
+ const child = spawn(process.execPath, [helperPath, ...args], {
+ env: {
+ ...process.env,
+ ...env,
+ },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ let stdout = "";
+ let stderr = "";
+ child.stdout.setEncoding("utf8");
+ child.stderr.setEncoding("utf8");
+ child.stdout.on("data", (chunk) => {
+ stdout += chunk;
+ });
+ child.stderr.on("data", (chunk) => {
+ stderr += chunk;
+ });
+ child.on("error", reject);
+ child.on("close", (code) => resolve({ code, stdout, stderr }));
+ });
+}
+
+describe("paperclip-task-bridge helper", () => {
+ let server: http.Server;
+ let baseUrl: string;
+ let requests: RequestRecord[];
+
+ beforeEach(async () => {
+ requests = [];
+ server = http.createServer(async (req, res) => {
+ let raw = "";
+ req.setEncoding("utf8");
+ for await (const chunk of req) raw += chunk;
+ const body = raw ? JSON.parse(raw) : null;
+ requests.push({
+ method: req.method ?? "GET",
+ url: req.url ?? "/",
+ headers: req.headers,
+ body,
+ });
+
+ res.setHeader("Content-Type", "application/json");
+ if (req.headers.authorization !== `Bearer ${apiKey}`) {
+ res.statusCode = 401;
+ res.end(JSON.stringify({ error: "bad auth" }));
+ return;
+ }
+ if (req.method === "GET" && req.url === "/api/agents/me") {
+ res.end(JSON.stringify({ id: "11111111-1111-4111-8111-111111111111", companyId: "22222222-2222-4222-8222-222222222222" }));
+ return;
+ }
+ if (req.method === "GET" && req.url === "/api/agents/me/inbox-lite") {
+ res.end(JSON.stringify([
+ {
+ id: "33333333-3333-4333-8333-333333333333",
+ identifier: "PAP-123",
+ title: "Existing task",
+ status: "todo",
+ priority: "medium",
+ assigneeAgentId: "11111111-1111-4111-8111-111111111111",
+ updatedAt: "2026-06-26T00:00:00.000Z",
+ },
+ ]));
+ return;
+ }
+ if (req.method === "POST" && req.url === "/api/companies/22222222-2222-4222-8222-222222222222/issues") {
+ res.statusCode = 201;
+ res.end(JSON.stringify({
+ id: "44444444-4444-4444-8444-444444444444",
+ identifier: "PAP-124",
+ title: body.title,
+ status: body.status ?? "todo",
+ priority: body.priority,
+ assigneeAgentId: body.assigneeAgentId ?? null,
+ }));
+ return;
+ }
+ if (req.method === "POST" && req.url === "/api/issues/PAP-123/comments") {
+ res.statusCode = 201;
+ res.end(JSON.stringify({
+ id: "55555555-5555-4555-8555-555555555555",
+ issueId: "33333333-3333-4333-8333-333333333333",
+ authorType: "agent",
+ authorAgentId: "11111111-1111-4111-8111-111111111111",
+ createdAt: "2026-06-26T00:00:00.000Z",
+ }));
+ return;
+ }
+ if (req.method === "PATCH" && req.url === "/api/issues/PAP-123") {
+ res.end(JSON.stringify({
+ id: "33333333-3333-4333-8333-333333333333",
+ identifier: "PAP-123",
+ title: "Existing task",
+ status: body.status,
+ priority: "medium",
+ }));
+ return;
+ }
+ res.statusCode = 404;
+ res.end(JSON.stringify({ error: "not found" }));
+ });
+
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("missing server address");
+ baseUrl = `http://127.0.0.1:${address.port}/api`;
+ });
+
+ afterEach(async () => {
+ await new Promise<void>((resolve, reject) => {
+ server.close((err) => (err ? reject(err) : resolve()));
+ });
+ });
+
+ function env() {
+ return {
+ PAPERCLIP_API_URL: baseUrl,
+ PAPERCLIP_BRIDGE_API_KEY: apiKey,
+ PAPERCLIP_COMPANY_ID: "22222222-2222-4222-8222-222222222222",
+ PAPERCLIP_AGENT_ID: "11111111-1111-4111-8111-111111111111",
+ PAPERCLIP_RUN_ID: "66666666-6666-4666-8666-666666666666",
+ };
+ }
+
+ it("lists assigned tasks without printing credentials", async () => {
+ const result = await runHelper(["list-assigned"], env());
+
+ expect(result.code).toBe(0);
+ expect(result.stdout).toContain('"command": "list-assigned"');
+ expect(result.stdout).toContain('"identifier": "PAP-123"');
+ expect(result.stdout).not.toContain(apiKey);
+ expect(result.stderr).not.toContain(apiKey);
+ expect(requests.some((request) => request.url === "/api/agents/me/inbox-lite")).toBe(true);
+ });
+
+ it("creates tasks assigned to the authenticated agent by default", async () => {
+ const result = await runHelper(["create-task", "--title", "Bridge task", "--description", "Created from Hermes"], env());
+
+ expect(result.code).toBe(0);
+ expect(result.stdout).toContain('"identifier": "PAP-124"');
+ const createRequest = requests.find((request) => request.method === "POST" && request.url.includes("/companies/"));
+ expect(createRequest?.headers["x-paperclip-run-id"]).toBe("66666666-6666-4666-8666-666666666666");
+ expect(createRequest?.body).toMatchObject({
+ title: "Bridge task",
+ description: "Created from Hermes",
+ priority: "medium",
+ workMode: "standard",
+ assigneeAgentId: "11111111-1111-4111-8111-111111111111",
+ });
+ expect(result.stdout).not.toContain(apiKey);
+ });
+
+ it("comments and updates status through direct issue identifier routes", async () => {
+ const comment = await runHelper(["comment", "--issue", "PAP-123", "--body", "Progress from Hermes"], env());
+ const update = await runHelper(["update-status", "--issue", "PAP-123", "--status", "in_review", "--comment", "Ready"], env());
+
+ expect(comment.code).toBe(0);
+ expect(update.code).toBe(0);
+ const commentRequest = requests.find((request) => request.method === "POST" && request.url.includes("/comments"));
+ const patchRequest = requests.find((request) => request.method === "PATCH");
+ expect(commentRequest?.body).toMatchObject({ body: "Progress from Hermes" });
+ expect(patchRequest?.body).toMatchObject({ status: "in_review", comment: "Ready" });
+ expect(comment.stdout + update.stdout).not.toContain(apiKey);
+ });
+});
diff --git a/packages/adapters/hermes/src/server/prompt-rendering.test.ts b/packages/adapters/hermes/src/server/prompt-rendering.test.ts
new file mode 100644
index 0000000000..1a5d1c9a8a
--- /dev/null
+++ b/packages/adapters/hermes/src/server/prompt-rendering.test.ts
@@ -0,0 +1,248 @@
+import { expect, test } from "vitest";
+
+import { buildPrompt } from "./execute.js";
+
+function baseContext(overrides: Record<string, unknown> = {}) {
+ return {
+ agent: {
+ id: "agent-1",
+ name: "Hermes Engineer",
+ companyId: "company-1",
+ },
+ runId: "run-1",
+ config: {},
+ context: {
+ issueId: "issue-1",
+ paperclipWake: {
+ reason: "issue_assigned",
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-3404",
+ title: "Plan the Hermes prompt update",
+ status: "in_progress",
+ priority: "medium",
+ workMode: "planning",
+ },
+ checkedOutByHarness: true,
+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },
+ comments: [],
+ fallbackFetchNeeded: false,
+ },
+ paperclipTaskMarkdown: [
+ "Paperclip task context:",
+ '- Issue: "PAP-3404"',
+ '- Title: "Plan the Hermes prompt update"',
+ "",
+ "Planning mode directive:",
+ "Make the plan only. Do not write code or perform implementation work.",
+ "",
+ "Issue description:",
+ "```text",
+ "Use the wake payload as runtime authority.",
+ "```",
+ ].join("\n"),
+ ...overrides,
+ },
+ } as any;
+}
+
+test("renders standard assignment wake with task authority and no backlog discovery guidance", () => {
+ const prompt = buildPrompt(baseContext({
+ paperclipWake: {
+ reason: "issue_assigned",
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-11750",
+ title: "Add Hermes prompt rendering regression tests",
+ status: "in_progress",
+ priority: "medium",
+ workMode: "standard",
+ },
+ checkedOutByHarness: true,
+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },
+ comments: [],
+ fallbackFetchNeeded: false,
+ },
+ paperclipTaskMarkdown: [
+ "Paperclip task context:",
+ '- Issue: "PAP-11750"',
+ '- Title: "Add Hermes prompt rendering regression tests"',
+ "",
+ "Issue description:",
+ "```text",
+ "Add focused unit tests for assignment wake and custom prompt rendering.",
+ "```",
+ ].join("\n"),
+ }), {});
+
+ expect(prompt).toContain("## Paperclip Wake Payload");
+ expect(prompt).toContain("- reason: issue_assigned");
+ expect(prompt).toContain("- issue: PAP-11750 Add Hermes prompt rendering regression tests");
+ expect(prompt).toContain("- issue work mode: standard");
+ expect(prompt).toContain("Paperclip task context:");
+ expect(prompt).toContain("Add focused unit tests for assignment wake and custom prompt rendering.");
+ expect(prompt).toContain("The harness already checked out this issue for the current run.");
+ expect(prompt).toContain("clear final disposition");
+ expect(prompt).not.toContain("check for unassigned issues");
+ expect(prompt).not.toContain("status=backlog");
+});
+
+test("renders scoped planning wake authority before the Hermes default workflow", () => {
+ const prompt = buildPrompt(baseContext(), {
+ paperclipApiUrl: "http://127.0.0.1:3101/api",
+ });
+
+ expect(prompt).toContain("## Paperclip Wake Payload");
+ expect(prompt).toContain("- issue: PAP-3404 Plan the Hermes prompt update");
+ expect(prompt).toContain("- planning directive: Make the plan only. Do not write code or perform implementation work.");
+ expect(prompt).toContain("- checkout: already claimed by the harness for this run");
+ expect(prompt).toContain("The harness already checked out this issue for the current run.");
+ expect(prompt).toContain("Issue description:\n```text\nUse the wake payload as runtime authority.\n```");
+ expect(prompt).toContain("clear final disposition");
+ expect(prompt).toContain("keep `in_progress` only when a live continuation path exists");
+ expect(prompt).not.toContain("check for unassigned issues");
+ expect(prompt).not.toContain("status=backlog");
+});
+
+test("renders resume deltas instead of full scoped-wake boilerplate when continuing a session", () => {
+ const prompt = buildPrompt(baseContext({
+ paperclipWake: {
+ reason: "issue_commented",
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-11750",
+ title: "Add Hermes prompt rendering regression tests",
+ status: "in_progress",
+ priority: "medium",
+ workMode: "standard",
+ },
+ latestCommentId: "comment-2",
+ commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+ comments: [{ id: "comment-2", body: "Please add the resume-delta case.", createdAt: "2026-06-23T00:00:00.000Z" }],
+ fallbackFetchNeeded: false,
+ },
+ }), {}, { resumedSession: true });
+
+ expect(prompt).toContain("## Paperclip Resume Delta");
+ expect(prompt).toContain("You are resuming an existing Paperclip session.");
+ expect(prompt).toContain("Focus on the new wake delta below");
+ expect(prompt).toContain("Please add the resume-delta case.");
+ expect(prompt).toContain("- fallback fetch needed: no");
+ expect(prompt).not.toContain("Before generic repo exploration or boilerplate heartbeat updates");
+});
+
+test("renders comment wake batch guidance without defaulting to a full-thread refetch", () => {
+ const prompt = buildPrompt(baseContext({
+ wakeCommentId: "comment-1",
+ paperclipWake: {
+ reason: "issue_commented",
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-3404",
+ title: "Plan the Hermes prompt update",
+ status: "in_progress",
+ priority: "medium",
+ workMode: "standard",
+ },
+ latestCommentId: "comment-1",
+ commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+ comments: [{ id: "comment-1", body: "Please tighten the prompt.", createdAt: "2026-06-23T00:00:00.000Z" }],
+ fallbackFetchNeeded: false,
+ },
+ }), {});
+
+ expect(prompt).toContain("Use this inline wake data first before refetching the issue thread.");
+ expect(prompt).toContain("Only fetch the API thread when `fallbackFetchNeeded` is true");
+ expect(prompt).toContain("New comments in order:");
+ expect(prompt).toContain("Please tighten the prompt.");
+ expect(prompt).toContain("- fallback fetch needed: no");
+});
+
+test("renders accepted-plan continuation without authorizing implementation on the planning issue", () => {
+ const prompt = buildPrompt(baseContext({
+ paperclipWake: {
+ reason: "issue_commented",
+ issue: {
+ id: "issue-1",
+ identifier: "PAP-3404",
+ title: "Plan the Hermes prompt update",
+ status: "in_progress",
+ priority: "medium",
+ workMode: "planning",
+ },
+ interactionKind: "request_confirmation",
+ interactionStatus: "accepted",
+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },
+ comments: [],
+ fallbackFetchNeeded: false,
+ },
+ }), {});
+
+ expect(prompt).toContain("- planning directive: Create child issues from the approved plan only. Do not write code or perform implementation work on the planning issue.");
+ expect(prompt).toContain("- accepted-plan continuation: you may create child implementation issues from the approved plan");
+ expect(prompt).toContain("must not start implementation work on the planning issue itself");
+ expect(prompt).not.toContain("- planning directive: Make the plan only.");
+ expect(prompt).not.toContain("Update the plan only");
+});
+
+test("keeps authoritative parent and ancestor context from task markdown", () => {
+ const prompt = buildPrompt(baseContext({
+ paperclipTaskMarkdown: [
+ "Paperclip task context:",
+ '- Issue: "PAP-3404"',
+ "",
+ "Authoritative parent / ancestor context:",
+ "- Parent: PAP-11724 Optimize prompt traces (in_progress) [medium]",
+ "- Ancestor 2: PAP-11721 Fetch raw traces (done) [medium]",
+ ].join("\n"),
+ }), {});
+
+ expect(prompt).toContain("Authoritative parent / ancestor context:");
+ expect(prompt).toContain("- Parent: PAP-11724 Optimize prompt traces (in_progress) [medium]");
+ expect(prompt).not.toContain("check the issue body or comments for references");
+});
+
+test("renders safe Paperclip API examples from environment variables with multiline update preservation", () => {
+ const prompt = buildPrompt(baseContext(), {
+ paperclipApiUrl: "http://paperclip.local/api",
+ });
+
+ expect(prompt).toContain("Use `$PAPERCLIP_API_URL`, `$PAPERCLIP_API_KEY`, and `$PAPERCLIP_RUN_ID`");
+ expect(prompt).toContain("Displayed command logs may redact secrets");
+ expect(prompt).toContain('-H "Authorization: Bearer $PAPERCLIP_API_KEY"');
+ expect(prompt).toContain('-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID"');
+ expect(prompt).toContain("body=$(cat <<'MD'");
+ expect(prompt).toContain("jq -n --arg status done --arg comment \"$body\"");
+ expect(prompt).toContain("--data-binary @-");
+ expect(prompt).not.toContain("Authorization: Bearer <");
+});
+
+test("preserves custom prompt templates while exposing runtime and wake variables", () => {
+ const prompt = buildPrompt(baseContext(), {
+ paperclipApiUrl: "http://paperclip.local/api",
+ promptTemplate: [
+ "CUSTOM TEMPLATE",
+ "agent={{agent.name}}",
+ "api={{paperclipApiUrl}}",
+ "keyEnv={{paperclipApiKeyEnv}}",
+ "runEnv={{paperclipRunIdEnv}}",
+ "wakePrompt={{paperclipWakePrompt}}",
+ "task={{paperclipTaskMarkdown}}",
+ "wakeJson={{paperclipWakeJson}}",
+ "wake={{wakePayloadJson}}",
+ ].join("\n"),
+ });
+
+ expect(prompt).toContain("CUSTOM TEMPLATE");
+ expect(prompt).toContain("agent=Hermes Engineer");
+ expect(prompt).toContain("api=http://paperclip.local/api");
+ expect(prompt).toContain("keyEnv=PAPERCLIP_API_KEY");
+ expect(prompt).toContain("runEnv=PAPERCLIP_RUN_ID");
+ expect(prompt).toContain("wakePrompt=## Paperclip Wake Payload");
+ expect(prompt).toContain("task=Paperclip task context:");
+ expect(prompt).toContain("wakeJson={\"reason\":\"issue_assigned\"");
+ expect(prompt).toContain('"reason":"issue_assigned"');
+ expect(prompt).toContain("## Paperclip Wake Payload");
+ expect(prompt).toContain("Issue description:\n```text\nUse the wake payload as runtime authority.\n```");
+ expect(prompt).not.toContain("Paperclip runtime identity:");
+});
diff --git a/packages/adapters/hermes/src/server/skills.ts b/packages/adapters/hermes/src/server/skills.ts
new file mode 100644
index 0000000000..6a9ea3c0d7
--- /dev/null
+++ b/packages/adapters/hermes/src/server/skills.ts
@@ -0,0 +1,226 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+ AdapterSkillContext,
+ AdapterSkillEntry,
+ AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+ readPaperclipRuntimeSkillEntries,
+ resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+import { fileURLToPath } from "node:url";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function asString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveHermesHome(config: Record<string, unknown>): string {
+ const env =
+ typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+ ? (config.env as Record<string, unknown>)
+ : {};
+ const configuredHome = asString(env.HOME);
+ return configuredHome ? path.resolve(configuredHome) : os.homedir();
+}
+
+interface SkillFrontmatter {
+ name?: string;
+ description?: string;
+ version?: string;
+ category?: string;
+ metadata?: Record<string, unknown>;
+}
+
+function parseSkillFrontmatter(content: string): SkillFrontmatter {
+ const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+ if (!match) return {};
+ const frontmatter: Record<string, unknown> = {};
+ for (const line of match[1].split("\n")) {
+ const idx = line.indexOf(":");
+ if (idx === -1) continue;
+ const key = line.slice(0, idx).trim();
+ let val: unknown = line.slice(idx + 1).trim();
+ // Strip quotes
+ if (typeof val === "string" && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
+ val = val.slice(1, -1);
+ }
+ frontmatter[key] = val;
+ }
+ return frontmatter as SkillFrontmatter;
+}
+
+async function scanHermesSkills(
+ skillsHome: string,
+): Promise<AdapterSkillEntry[]> {
+ const entries: AdapterSkillEntry[] = [];
+
+ try {
+ const categories = await fs.readdir(skillsHome, { withFileTypes: true });
+ for (const cat of categories) {
+ if (!cat.isDirectory()) continue;
+ const catPath = path.join(skillsHome, cat.name);
+
+ // Check if the category directory itself has a SKILL.md (top-level skill)
+ const topLevelSkillMd = path.join(catPath, "SKILL.md");
+ if (await fs.stat(topLevelSkillMd).catch(() => null)) {
+ entries.push(await buildSkillEntry(cat.name, topLevelSkillMd, cat.name));
+ }
+
+ // Scan for sub-skills
+ const items = await fs.readdir(catPath, { withFileTypes: true }).catch(() => []);
+ for (const item of items) {
+ if (!item.isDirectory()) continue;
+ const skillMd = path.join(catPath, item.name, "SKILL.md");
+ if (await fs.stat(skillMd).catch(() => null)) {
+ const key = item.name;
+ entries.push(await buildSkillEntry(key, skillMd, `${cat.name}/${item.name}`));
+ }
+ }
+ }
+ } catch {
+ // ~/.hermes/skills/ doesn't exist — no skills available
+ }
+
+ return entries.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+async function buildSkillEntry(
+ key: string,
+ skillMdPath: string,
+ categoryPath: string,
+): Promise<AdapterSkillEntry> {
+ let description: string | null = null;
+ try {
+ const content = await fs.readFile(skillMdPath, "utf8");
+ const fm = parseSkillFrontmatter(content);
+ description = fm.description ?? null;
+ } catch {
+ // ignore
+ }
+
+ return {
+ key,
+ runtimeName: key,
+ desired: true, // Hermes loads all available skills
+ managed: false,
+ state: "installed",
+ origin: "user_installed",
+ originLabel: "Hermes skill",
+ locationLabel: `~/.hermes/skills/${categoryPath}`,
+ readOnly: true, // Hermes manages its own skills — Paperclip can't toggle them
+ sourcePath: skillMdPath,
+ targetPath: null,
+ detail: description,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+async function buildHermesSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+ const home = resolveHermesHome(config);
+ const hermesSkillsHome = path.join(home, ".hermes", "skills");
+
+ // 1. Scan Paperclip-managed skills (bundled with the adapter)
+ const paperclipEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, paperclipEntries);
+ const desiredSet = new Set(desiredSkills);
+ const availableByKey = new Map(paperclipEntries.map((e) => [e.key, e]));
+
+ // 2. Scan Hermes's own skills from ~/.hermes/skills/
+ const hermesSkillEntries = await scanHermesSkills(hermesSkillsHome);
+ const hermesKeys = new Set(hermesSkillEntries.map((e) => e.key));
+
+ // 3. Merge: Paperclip skills first (ephemeral), then Hermes skills
+ const entries: AdapterSkillEntry[] = [];
+ const warnings: string[] = [];
+
+ // Paperclip-managed skills
+ for (const entry of paperclipEntries) {
+ const desired = desiredSet.has(entry.key);
+ entries.push({
+ key: entry.key,
+ runtimeName: entry.runtimeName,
+ desired,
+ managed: true,
+ state: desired ? "configured" : "available",
+ origin: "company_managed",
+ originLabel: "Managed by Paperclip",
+ readOnly: false,
+ sourcePath: entry.source,
+ targetPath: null,
+ detail: desired
+ ? "Will be available on the next run via Hermes skill loading."
+ : null,
+ });
+ }
+
+ // Hermes-installed skills (read-only, always loaded)
+ for (const entry of hermesSkillEntries) {
+ // Skip if Paperclip already manages a skill with the same key
+ if (availableByKey.has(entry.key)) continue;
+ entries.push(entry);
+ }
+
+ // Check for desired skills that don't exist
+ for (const desiredSkill of desiredSkills) {
+ if (availableByKey.has(desiredSkill) || hermesKeys.has(desiredSkill)) continue;
+ warnings.push(
+ `Desired skill "${desiredSkill}" is not available in Paperclip or Hermes skills.`,
+ );
+ entries.push({
+ key: desiredSkill,
+ runtimeName: null,
+ desired: true,
+ managed: true,
+ state: "missing",
+ origin: "external_unknown",
+ originLabel: "External or unavailable",
+ readOnly: false,
+ sourcePath: null,
+ targetPath: null,
+ detail:
+ "Cannot find this skill in Paperclip or ~/.hermes/skills/.",
+ });
+ }
+
+ return {
+ adapterType: "hermes_local",
+ supported: true,
+ mode: "persistent",
+ desiredSkills,
+ entries,
+ warnings,
+ };
+}
+
+export async function listHermesSkills(
+ ctx: AdapterSkillContext,
+): Promise<AdapterSkillSnapshot> {
+ return buildHermesSkillSnapshot(ctx.config);
+}
+
+export async function syncHermesSkills(
+ ctx: AdapterSkillContext,
+ _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+ // Hermes manages its own skill loading — sync is a no-op.
+ // Return the current snapshot so the UI stays in sync.
+ return buildHermesSkillSnapshot(ctx.config);
+}
+
+export function resolveHermesDesiredSkillNames(
+ config: Record<string, unknown>,
+ availableEntries: Array<{ key: string; runtimeName?: string | null }>,
+): string[] {
+ return resolvePaperclipDesiredSkillNames(config, availableEntries);
+}
diff --git a/packages/adapters/hermes/src/server/test.ts b/packages/adapters/hermes/src/server/test.ts
new file mode 100644
index 0000000000..b75ce020ca
--- /dev/null
+++ b/packages/adapters/hermes/src/server/test.ts
@@ -0,0 +1,387 @@
+/**
+ * Environment test for the Hermes Agent adapter.
+ *
+ * Verifies that Hermes Agent is installed, accessible, and configured
+ * before allowing the adapter to be used.
+ */
+
+import type {
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+ AdapterEnvironmentCheck,
+} from "@paperclipai/adapter-utils";
+
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { promisify } from "node:util";
+
+import { HERMES_CLI, DEFAULT_MODEL, ADAPTER_TYPE, VALID_PROVIDERS } from "../shared/constants.js";
+import { detectModel, resolveProvider, inferProviderFromModel } from "./detect-model.js";
+import { resolveHermesCommand } from "./execute.js";
+
+const execFileAsync = promisify(execFile);
+
+function asString(v: unknown): string | undefined {
+ return typeof v === "string" ? v : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+async function checkCliInstalled(
+ command: string,
+): Promise<AdapterEnvironmentCheck | null> {
+ try {
+ // Try to run the command to see if it exists
+ await execFileAsync(command, ["--version"], { timeout: 10_000 });
+ return null; // OK — it ran successfully
+ } catch (err: unknown) {
+ const e = err as NodeJS.ErrnoException;
+ if (e.code === "ENOENT") {
+ return {
+ level: "error",
+ message: `Hermes CLI "${command}" not found in PATH`,
+ hint: "Install Hermes Agent: pip install hermes-agent",
+ code: "hermes_cli_not_found",
+ };
+ }
+ // Command exists but --version might have failed for some reason
+ // Still consider it installed
+ return null;
+ }
+}
+
+async function checkCliVersion(
+ command: string,
+): Promise<AdapterEnvironmentCheck | null> {
+ try {
+ const { stdout } = await execFileAsync(command, ["--version"], {
+ timeout: 10_000,
+ });
+ const version = stdout.trim();
+ if (version) {
+ return {
+ level: "info",
+ message: `Hermes Agent version: ${version}`,
+ code: "hermes_version",
+ };
+ }
+ return {
+ level: "warn",
+ message: "Could not determine Hermes Agent version",
+ code: "hermes_version_unknown",
+ };
+ } catch {
+ return {
+ level: "warn",
+ message:
+ "Could not determine Hermes Agent version (hermes --version failed)",
+ hint: "Make sure the hermes CLI is properly installed and functional",
+ code: "hermes_version_failed",
+ };
+ }
+}
+
+async function checkPython(): Promise<AdapterEnvironmentCheck | null> {
+ try {
+ const { stdout } = await execFileAsync("python3", ["--version"], {
+ timeout: 5_000,
+ });
+ const version = stdout.trim();
+ const match = version.match(/(\d+)\.(\d+)/);
+ if (match) {
+ const major = parseInt(match[1], 10);
+ const minor = parseInt(match[2], 10);
+ if (major < 3 || (major === 3 && minor < 10)) {
+ return {
+ level: "error",
+ message: `Python ${version} found — Hermes requires Python 3.10+`,
+ hint: "Upgrade Python to 3.10 or later",
+ code: "hermes_python_old",
+ };
+ }
+ }
+ return null; // OK
+ } catch {
+ return {
+ level: "warn",
+ message: "python3 not found in PATH",
+ hint: "Hermes Agent requires Python 3.10+. Install it from python.org",
+ code: "hermes_python_missing",
+ };
+ }
+}
+
+function checkModel(
+ config: Record<string, unknown>,
+): AdapterEnvironmentCheck | null {
+ const model = asString(config.model);
+ if (!model) {
+ return {
+ level: "info",
+ message: "No model specified — Hermes will use its configured default model",
+ hint: "Set a model explicitly in Paperclip only if you want to override your local Hermes configuration.",
+ code: "hermes_configured_default_model",
+ };
+ }
+ return {
+ level: "info",
+ message: `Model: ${model}`,
+ code: "hermes_model_configured",
+ };
+}
+
+async function checkApiKeys(
+ config: Record<string, unknown>,
+ detectedConfig: Awaited<ReturnType<typeof detectModel>> | null,
+): Promise<AdapterEnvironmentCheck | null> {
+ // The server resolves secret refs into config.env before calling testEnvironment,
+ // so we check config.env first (adapter-configured secrets), then fall back to
+ // process.env (server/host environment), then ~/.hermes/.env (Hermes local config).
+ const envConfig = (config.env ?? {}) as Record<string, unknown>;
+ const resolvedEnv: Record<string, string> = {};
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string" && value.length > 0) resolvedEnv[key] = value;
+ }
+
+ // Also read ~/.hermes/.env — Hermes stores API keys there by default and does
+ // not export them to the parent process, so Paperclip's process.env won't
+ // contain them. Parsing this file ensures the environment test reports
+ // accurate results for keys that Hermes already knows about.
+ const hermesEnvKeys: Record<string, string> = {};
+ try {
+ const homeDir = process.env.HOME || process.env.USERPROFILE || "/root";
+ const hermesEnvPath = `${homeDir}/.hermes/.env`;
+ const content = readFileSync(hermesEnvPath, "utf-8");
+ for (const line of content.split("\n")) {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith("#")) continue;
+ const eqIdx = trimmed.indexOf("=");
+ if (eqIdx > 0) {
+ const key = trimmed.substring(0, eqIdx).trim();
+ const value = trimmed.substring(eqIdx + 1).trim();
+ if (value.length > 0) hermesEnvKeys[key] = value;
+ }
+ }
+ } catch {
+ // ~/.hermes/.env may not exist — that's fine
+ }
+
+ const has = (key: string): boolean =>
+ !!(resolvedEnv[key] ?? process.env[key] ?? hermesEnvKeys[key]);
+
+ const hasAnthropic = has("ANTHROPIC_API_KEY");
+ const hasOpenRouter = has("OPENROUTER_API_KEY");
+ const hasOpenAI = has("OPENAI_API_KEY");
+ const hasZai = has("ZAI_API_KEY");
+ const hasKimi = has("KIMI_API_KEY");
+ const hasMiniMax = has("MINIMAX_API_KEY");
+
+ const providers: string[] = [];
+ if (hasAnthropic) providers.push("Anthropic");
+ if (hasOpenRouter) providers.push("OpenRouter");
+ if (hasOpenAI) providers.push("OpenAI");
+ if (hasZai) providers.push("Z.AI");
+ if (hasKimi) providers.push("Kimi");
+ if (hasMiniMax) providers.push("MiniMax");
+
+ if (providers.length > 0) {
+ return {
+ level: "info",
+ message: `API keys found: ${providers.join(", ")}`,
+ code: "hermes_api_keys_found",
+ };
+ }
+
+ const requestedModel = asString(config.model);
+
+ const supportedProviders = VALID_PROVIDERS as readonly string[];
+ const modelMatchesRequested =
+ !!detectedConfig?.model &&
+ (!requestedModel || detectedConfig.model.toLowerCase() === requestedModel.toLowerCase());
+
+ const matchingHermesConfigApiKey =
+ !!detectedConfig?.hasApiKey &&
+ modelMatchesRequested;
+
+ if (matchingHermesConfigApiKey && detectedConfig) {
+ const providerLabel = detectedConfig.provider.trim();
+
+ if (!providerLabel) {
+ return {
+ level: "info",
+ message: "Hermes config includes an API key for the requested model via ~/.hermes/config.yaml without an explicit provider",
+ hint: "Skipping the built-in API-key warning because Hermes can use model.api_key from the local Hermes config.",
+ code: "hermes_api_key_in_config",
+ };
+ }
+
+ if (!supportedProviders.includes(providerLabel)) {
+ return {
+ level: "info",
+ message: `Hermes config includes runtime settings for unsupported adapter provider "${providerLabel}" via ~/.hermes/config.yaml`,
+ hint: "Skipping the built-in API-key warning because Hermes can resolve this provider at runtime.",
+ code: "hermes_custom_provider_config",
+ };
+ }
+
+ return {
+ level: "info",
+ message: `Hermes config includes an API key for provider "${providerLabel}" via ~/.hermes/config.yaml`,
+ hint: "Skipping the built-in API-key warning because Hermes can use model.api_key from the local Hermes config.",
+ code: "hermes_api_key_in_config",
+ };
+ }
+
+ return {
+ level: "warn",
+ message: "No LLM API keys found in environment",
+ hint: "Set API keys in the agent's env secrets or ~/.hermes/.env. Hermes supports: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, ZAI_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY",
+ code: "hermes_no_api_keys",
+ };
+}
+
+/**
+ * Check provider/model consistency.
+ * Warns if the configured provider might be wrong for the model.
+ */
+async function checkProviderConsistency(
+ config: Record<string, unknown>,
+ detectedConfig: Awaited<ReturnType<typeof detectModel>> | null,
+): Promise<AdapterEnvironmentCheck | null> {
+ const model = asString(config.model);
+ if (!model) return null;
+
+ const explicitProvider = asString(config.provider);
+
+ const { provider: resolved, resolvedFrom } = resolveProvider({
+ explicitProvider,
+ detectedProvider: detectedConfig?.provider,
+ detectedModel: detectedConfig?.model,
+ detectedBaseUrl: detectedConfig?.baseUrl,
+ detectedHasApiKey: detectedConfig?.hasApiKey,
+ detectedApiMode: detectedConfig?.apiMode,
+ model,
+ });
+
+ // If provider was explicitly set but doesn't match what Hermes config says,
+ // that's worth flagging.
+ if (explicitProvider && detectedConfig?.provider && explicitProvider !== detectedConfig.provider) {
+ return {
+ level: "warn",
+ message: `Provider mismatch: adapterConfig has "${explicitProvider}" but ~/.hermes/config.yaml has "${detectedConfig.provider}". Using adapterConfig value.`,
+ hint: `Model "${model}" may not work correctly with provider "${explicitProvider}". Consider aligning with your Hermes config or removing the explicit provider to use auto-detection.`,
+ code: "hermes_provider_mismatch",
+ };
+ }
+
+ // If Hermes config matches the requested model but uses an adapter-unsupported
+ // provider such as "custom", do not report a false provider inference.
+ if (!explicitProvider && resolvedFrom.startsWith("hermesConfigUnsupported:")) {
+ const unsupportedProvider = resolvedFrom.split(":", 2)[1] || detectedConfig?.provider || "unknown";
+ return {
+ level: "info",
+ message: `Hermes config uses unsupported adapter provider "${unsupportedProvider}" for model "${model}" — deferring to Hermes auto-detection`,
+ hint: "Paperclip will avoid model-name provider inference here and let Hermes resolve the provider from ~/.hermes/config.yaml at runtime.",
+ code: "hermes_provider_unsupported",
+ };
+ }
+
+ // If matching Hermes config provides runtime signals without an explicit provider,
+ // also defer to Hermes rather than inventing a provider from the model name.
+ if (!explicitProvider && resolvedFrom === "hermesConfigRuntime") {
+ return {
+ level: "info",
+ message: `Hermes config provides runtime settings for model "${model}" without an explicit adapter provider — deferring to Hermes auto-detection`,
+ hint: "Paperclip will avoid model-name provider inference here and let Hermes resolve the provider from ~/.hermes/config.yaml at runtime.",
+ code: "hermes_provider_runtime_config",
+ };
+ }
+
+ // If provider was auto-detected (not explicitly set), log what was resolved
+ if (!explicitProvider && resolvedFrom !== "auto") {
+ return {
+ level: "info",
+ message: `Provider auto-detected as "${resolved}" (from ${resolvedFrom}) for model "${model}"`,
+ code: "hermes_provider_detected",
+ };
+ }
+
+ // If we couldn't resolve any provider, warn
+ if (resolvedFrom === "auto" && !explicitProvider) {
+ return {
+ level: "warn",
+ message: `Could not determine provider for model "${model}" — will use Hermes auto-detection`,
+ hint: "Set an explicit provider in the agent config or ensure ~/.hermes/config.yaml has a matching provider for this model.",
+ code: "hermes_provider_unknown",
+ };
+ }
+
+ return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main test
+// ---------------------------------------------------------------------------
+
+export async function testEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const config = (ctx.config ?? {}) as Record<string, unknown>;
+ const command = resolveHermesCommand(config);
+ const checks: AdapterEnvironmentCheck[] = [];
+
+ // 1. CLI installed?
+ const cliCheck = await checkCliInstalled(command);
+ if (cliCheck) {
+ checks.push(cliCheck);
+ if (cliCheck.level === "error") {
+ return {
+ adapterType: ADAPTER_TYPE,
+ status: "fail",
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+ }
+ }
+
+ // 2. CLI version
+ const versionCheck = await checkCliVersion(command);
+ if (versionCheck) checks.push(versionCheck);
+
+ // 3. Python available?
+ const pythonCheck = await checkPython();
+ if (pythonCheck) checks.push(pythonCheck);
+
+ // 4. Model config
+ const modelCheck = checkModel(config);
+ if (modelCheck) checks.push(modelCheck);
+
+ // 5. Detect Hermes config once for the remaining checks.
+ let detectedConfig: Awaited<ReturnType<typeof detectModel>> | null = null;
+ try {
+ detectedConfig = await detectModel();
+ } catch {
+ // Non-fatal
+ }
+
+ // 6. API keys (check config.env — server resolves secrets before calling us)
+ const apiKeyCheck = await checkApiKeys(config, detectedConfig);
+ if (apiKeyCheck) checks.push(apiKeyCheck);
+
+ // 7. Provider/model consistency
+ const providerCheck = await checkProviderConsistency(config, detectedConfig);
+ if (providerCheck) checks.push(providerCheck);
+
+ // Determine overall status
+ const hasErrors = checks.some((c) => c.level === "error");
+ const hasWarnings = checks.some((c) => c.level === "warn");
+
+ return {
+ adapterType: ADAPTER_TYPE,
+ status: hasErrors ? "fail" : hasWarnings ? "warn" : "pass",
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/hermes/src/shared/constants.ts b/packages/adapters/hermes/src/shared/constants.ts
new file mode 100644
index 0000000000..25f57cd86e
--- /dev/null
+++ b/packages/adapters/hermes/src/shared/constants.ts
@@ -0,0 +1,104 @@
+/**
+ * Shared constants for the Hermes Agent adapter.
+ */
+
+/** Adapter type identifier registered with Paperclip. */
+export const ADAPTER_TYPE = "hermes_local";
+
+/** Human-readable label shown in the Paperclip UI. */
+export const ADAPTER_LABEL = "Hermes Agent";
+
+/** Default CLI binary name. */
+export const HERMES_CLI = "hermes";
+
+/** Default timeout for a single execution run (seconds). */
+export const DEFAULT_TIMEOUT_SEC = 1800;
+
+/** Grace period after SIGTERM before SIGKILL (seconds). */
+export const DEFAULT_GRACE_SEC = 10;
+
+/**
+ * Default model to use if none specified.
+ *
+ * Use "auto" so that Hermes resolves the model from the user's local
+ * ~/.hermes/config.yaml — preventing the adapter from overriding a
+ * user's configured default (e.g. MiniMax, OpenRouter, etc.) with a
+ * hardcoded Anthropic model during Paperclip onboarding.
+ */
+export const DEFAULT_MODEL = "auto";
+
+/**
+ * Valid --provider choices for the hermes CLI.
+ * Must stay in sync with `hermes chat --help`.
+ */
+export const VALID_PROVIDERS = [
+ "auto",
+ "openrouter",
+ "nous",
+ "openai-codex",
+ "copilot",
+ "copilot-acp",
+ "anthropic",
+ "huggingface",
+ "zai",
+ "kimi-coding",
+ "minimax",
+ "minimax-cn",
+ "kilocode",
+] as const;
+
+/**
+ * Model-name prefix → provider hint mapping.
+ * Used when no explicit provider is configured and we need to infer
+ * the correct provider from the model string alone.
+ *
+ * Keys are lowercased prefix patterns; values must be valid provider names.
+ * Longer prefixes are matched first (order matters).
+ */
+export const MODEL_PREFIX_PROVIDER_HINTS: [string, string][] = [
+ // OpenAI-native models
+ ["gpt-4", "openai-codex"],
+ ["gpt-5", "copilot"],
+ ["o1-", "openai-codex"],
+ ["o3-", "openai-codex"],
+ ["o4-", "openai-codex"],
+ // Anthropic models
+ ["claude", "anthropic"],
+ // Google models (via openrouter or direct)
+ ["gemini", "auto"],
+ // Nous models
+ ["hermes-", "nous"],
+ // Z.AI / GLM models
+ ["glm-", "zai"],
+ // Kimi / Moonshot
+ ["moonshot", "kimi-coding"],
+ ["kimi", "kimi-coding"],
+ // MiniMax
+ ["minimax", "minimax"],
+ // DeepSeek
+ ["deepseek", "auto"],
+ // Meta Llama
+ ["llama", "auto"],
+ // Qwen
+ ["qwen", "auto"],
+ // Mistral
+ ["mistral", "auto"],
+ // HuggingFace models (org/model format)
+ ["huggingface/", "huggingface"],
+];
+
+/** Regex to extract session ID from Hermes CLI output. */
+export const SESSION_ID_REGEX = /session[_ ](?:id|saved)[:\s]+([a-zA-Z0-9_-]+)/i;
+
+/** Regex to extract token usage from Hermes output. */
+export const TOKEN_USAGE_REGEX =
+ /tokens?[:\s]+(\d+)\s*(?:input|in)\b.*?(\d+)\s*(?:output|out)\b/i;
+
+/** Regex to extract cost from Hermes output. */
+export const COST_REGEX = /(?:cost|spent)[:\s]*\$?([\d.]+)/i;
+
+/** Prefix used by Hermes for tool output lines. */
+export const TOOL_OUTPUT_PREFIX = "┊";
+
+/** Prefix for Hermes thinking blocks. */
+export const THINKING_PREFIX = "💭";
diff --git a/packages/adapters/hermes/src/ui/build-config.ts b/packages/adapters/hermes/src/ui/build-config.ts
new file mode 100644
index 0000000000..ef9c5fb67a
--- /dev/null
+++ b/packages/adapters/hermes/src/ui/build-config.ts
@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+import {
+ DEFAULT_TIMEOUT_SEC,
+} from "../shared/constants.js";
+
+/**
+ * Build a Hermes Agent adapter config from the Paperclip UI form values.
+ */
+export function buildHermesConfig(
+ v: CreateConfigValues,
+): Record<string, unknown> {
+ const ac: Record<string, unknown> = {};
+
+ // Model
+ if (v.model.trim()) {
+ ac.model = v.model.trim();
+ }
+
+ // NOTE: Provider is NOT set here because the Paperclip UI form
+ // (CreateConfigValues) does not expose a provider field.
+ // Instead, provider is resolved at runtime in execute.ts using
+ // a priority chain:
+ // 1. adapterConfig.provider (if set via API directly)
+ // 2. ~/.hermes/config.yaml detection
+ // 3. Model-name prefix inference
+ // 4. "auto" fallback
+ // This ensures correct provider routing even for agents created
+ // before provider tracking existed.
+
+ // Execution limits — let the user configure these from the Paperclip UI.
+ // timeoutSec: wall-clock kill timeout for the hermes child process.
+ // maxTurnsPerRun: maps to Hermes's --max-turns (agent tool-calling iterations).
+ ac.timeoutSec = DEFAULT_TIMEOUT_SEC;
+ if (v.maxTurnsPerRun > 0) {
+ ac.maxTurnsPerRun = v.maxTurnsPerRun;
+ // Scale timeout to match: ~20s per tool turn is generous headroom.
+ // Never go below the default (1800s / 30 min).
+ ac.timeoutSec = Math.max(DEFAULT_TIMEOUT_SEC, v.maxTurnsPerRun * 20);
+ }
+
+ // Session persistence (default: on)
+ ac.persistSession = true;
+
+ // Working directory
+ if (v.cwd) {
+ ac.cwd = v.cwd;
+ }
+
+ // Custom hermes binary path
+ if (v.command) {
+ ac.hermesCommand = v.command;
+ }
+
+ // Extra CLI arguments
+ if (v.extraArgs) {
+ ac.extraArgs = v.extraArgs.split(/\s+/).filter(Boolean);
+ }
+
+ // Thinking/reasoning effort
+ if (v.thinkingEffort) {
+ const existing = (ac.extraArgs as string[]) || [];
+ existing.push("--reasoning-effort", String(v.thinkingEffort));
+ ac.extraArgs = existing;
+ }
+
+ // Prompt template
+ if (v.promptTemplate) {
+ ac.promptTemplate = v.promptTemplate;
+ }
+
+ // Heartbeat config is handled by Paperclip itself
+
+ return ac;
+}
diff --git a/packages/adapters/hermes/src/ui/index.ts b/packages/adapters/hermes/src/ui/index.ts
new file mode 100644
index 0000000000..3a49f11209
--- /dev/null
+++ b/packages/adapters/hermes/src/ui/index.ts
@@ -0,0 +1,7 @@
+/**
+ * UI module exports — used by Paperclip's dashboard for run viewing
+ * and agent configuration forms.
+ */
+
+export { parseHermesStdoutLine } from "./parse-stdout.js";
+export { buildHermesConfig } from "./build-config.js";
diff --git a/packages/adapters/hermes/src/ui/parse-stdout.ts b/packages/adapters/hermes/src/ui/parse-stdout.ts
new file mode 100644
index 0000000000..6e48b40ed4
--- /dev/null
+++ b/packages/adapters/hermes/src/ui/parse-stdout.ts
@@ -0,0 +1,283 @@
+/**
+ * Parse Hermes Agent stdout into TranscriptEntry objects for the Paperclip UI.
+ *
+ * Hermes CLI quiet-mode output patterns:
+ * Assistant: " ┊ 💬 {text}"
+ * Tool (TTY): " ┊ {emoji} {verb:9} {detail} {duration}"
+ * Tool (pipe): " [done] ┊ {emoji} {verb:9} {detail} {duration} ({total})"
+ * System: "[hermes] ..."
+ *
+ * We emit structured tool_call/tool_result pairs so Paperclip renders proper
+ * tool cards (with status icons, expand/collapse) instead of raw stdout blocks.
+ */
+
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+
+import { TOOL_OUTPUT_PREFIX } from "../shared/constants.js";
+
+// ── Kaomoji / noise stripping ──────────────────────────────────────────────
+
+/**
+ * Strip kawaii faces and decorative emoji from a tool summary line.
+ * Leaves meaningful emoji (💻 for terminal, 🔍 for search, etc.) intact
+ * by only stripping parenthesized kaomoji like (。◕‿◕。).
+ */
+function stripKaomoji(text: string): string {
+ // Strip parenthesized kaomoji faces: (。◕‿◕。), (★ω★), etc.
+ return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();
+}
+
+// ── Line classification ────────────────────────────────────────────────────
+
+/** Check if a ┊ line is an assistant message (┊ 💬 ...). */
+function isAssistantToolLine(stripped: string): boolean {
+ return /^┊\s*💬/.test(stripped);
+}
+
+/** Extract assistant text from a ┊ 💬 line. */
+function extractAssistantText(line: string): string {
+ return line.replace(/^[\s┊]*💬\s*/, "").trim();
+}
+
+/**
+ * Parse a tool completion line into structured data.
+ *
+ * Handles both TTY and pipe formats:
+ * TTY: ┊ 💻 $ curl -s "..." 0.1s
+ * Pipe: [done] ┊ 💻 $ curl -s "..." 0.1s (0.5s)
+ */
+function parseToolCompletionLine(
+ line: string,
+): { name: string; detail: string; duration: string; hasError: boolean } | null {
+ // Strip leading whitespace and [done] prefix
+ let cleaned = line.trim().replace(/^\[done\]\s*/, "");
+
+ // Must start with ┊
+ if (!cleaned.startsWith(TOOL_OUTPUT_PREFIX)) return null;
+
+ // Remove ┊ prefix and any leading kaomoji face
+ cleaned = cleaned.slice(TOOL_OUTPUT_PREFIX.length);
+ cleaned = stripKaomoji(cleaned).trim();
+
+ // Now format is: "{emoji} {verb:9} {detail} {duration}" or "{emoji} {verb:9} {detail} {duration} ({total})"
+ // Example: "💻 $ curl -s ..." or "🔍 search pattern 0.1s"
+ // The verb+detail are separated by whitespace, duration is at the end
+
+ // Match: emoji + verb + detail + duration
+ // Duration pattern: N.Ns (possibly followed by (N.Ns))
+ const durationMatch = cleaned.match(/([\d.]+s)\s*(?:\([\d.]+s\))?\s*$/);
+ const duration = durationMatch ? durationMatch[1] : "";
+
+ // Remove duration from the end to get verb + detail
+ let verbAndDetail = durationMatch
+ ? cleaned.slice(0, cleaned.lastIndexOf(durationMatch[0])).trim()
+ : cleaned;
+ verbAndDetail = verbAndDetail.replace(/^\p{Emoji_Presentation}\s*/u, "");
+
+ // Check for error suffixes
+ const hasError = /\[(?:exit \d+|error|full)\]/.test(verbAndDetail) ||
+ /\[error\]\s*$/.test(cleaned);
+
+ // The first token (after emoji) is the verb, rest is detail
+ // Verbs are always a single word or symbol ($ for terminal)
+ const parts = verbAndDetail.match(/^(\S+)\s+(.*)/);
+ if (!parts) {
+ return { name: "tool", detail: verbAndDetail, duration, hasError };
+ }
+
+ const verb = parts[1];
+ const detail = parts[2].trim();
+
+ // Map Hermes verbs to readable tool names
+ const nameMap: Record<string, string> = {
+ "$": "shell",
+ "exec": "shell",
+ "terminal": "shell",
+ "search": "search",
+ "fetch": "fetch",
+ "crawl": "crawl",
+ "navigate": "browser",
+ "snapshot": "browser",
+ "click": "browser",
+ "type": "browser",
+ "scroll": "browser",
+ "back": "browser",
+ "press": "browser",
+ "close": "browser",
+ "images": "browser",
+ "vision": "browser",
+ "read": "read",
+ "write": "write",
+ "patch": "patch",
+ "grep": "search",
+ "find": "search",
+ "plan": "plan",
+ "recall": "recall",
+ "proc": "process",
+ "delegate": "delegate",
+ "todo": "todo",
+ "memory": "memory",
+ "clarify": "clarify",
+ "session_search": "recall",
+ "code": "execute",
+ "execute": "execute",
+ "web_search": "search",
+ "web_extract": "fetch",
+ "browser_navigate": "browser",
+ "browser_click": "browser",
+ "browser_type": "browser",
+ "browser_snapshot": "browser",
+ "browser_vision": "browser",
+ "browser_scroll": "browser",
+ "browser_press": "browser",
+ "browser_back": "browser",
+ "browser_close": "browser",
+ "browser_get_images": "browser",
+ "read_file": "read",
+ "write_file": "write_file",
+ "search_files": "search",
+ "patch_file": "patch",
+ "execute_code": "execute",
+ };
+
+ const name = nameMap[verb.toLowerCase()] || verb;
+
+ return { name, detail, duration, hasError };
+}
+
+// ── Synthetic tool ID generation ────────────────────────────────────────────
+
+let toolCallCounter = 0;
+
+/**
+ * Generate a synthetic toolUseId for pairing tool_call with tool_result.
+ * Paperclip uses this to match them in normalizeTranscript.
+ */
+function syntheticToolUseId(): string {
+ return `hermes-tool-${++toolCallCounter}`;
+}
+
+// ── Thinking detection ─────────────────────────────────────────────────────
+
+function isThinkingLine(line: string): boolean {
+ return (
+ line.includes("💭") ||
+ line.startsWith("<thinking>") ||
+ line.startsWith("</thinking>") ||
+ line.startsWith("Thinking:")
+ );
+}
+
+// ── Main parser ────────────────────────────────────────────────────────────
+
+/**
+ * Parse a single line of Hermes stdout into transcript entries.
+ *
+ * Emits structured tool_call/tool_result pairs (with synthetic IDs) so
+ * Paperclip renders proper tool cards with status icons and expand/collapse.
+ *
+ * @param line Raw stdout line from Hermes CLI
+ * @param ts ISO timestamp for the entry
+ * @returns Array of TranscriptEntry objects (may be empty)
+ */
+export function parseHermesStdoutLine(
+ line: string,
+ ts: string,
+): TranscriptEntry[] {
+ const trimmed = line.trim();
+ if (!trimmed) return [];
+
+ // ── System/adapter messages ────────────────────────────────────────────
+ if (trimmed.startsWith("[hermes]") || trimmed.startsWith("[paperclip]")) {
+ return [{ kind: "system", ts, text: trimmed }];
+ }
+
+ // ── Non-quiet mode tool start lines: [tool] (kaomoji) emoji verb ... ──
+ // These are redundant — the tool_call/tool_result pair arrives later from
+ // the ┊ completion line. Skip them to avoid duplicate entries.
+ if (trimmed.startsWith("[tool]")) {
+ return [];
+ }
+
+ // ── MCP / server init noise reclassified from stderr by wrappedOnLog ──
+ // Pattern: [2026-03-25T10:40:53.941Z] INFO: ...
+ // Emit as stderr so Paperclip groups them into the amber accordion.
+ if (/^\[\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+ return [{ kind: "stderr", ts, text: trimmed }];
+ }
+
+ // ── Standalone spinner remnants: "💻 Completed", "💻\nCompleted", etc. ─
+ // These are non-quiet mode spinner frame leftovers — skip them.
+ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(trimmed)) {
+ return [];
+ }
+
+ // ── Session info line ────────────────────────────────────────────────
+ if (trimmed.startsWith("session_id:")) {
+ return [{ kind: "system", ts, text: trimmed }];
+ }
+
+ // ── Quiet-mode tool/message lines (prefixed with ┊) ────────────────────
+ if (trimmed.includes(TOOL_OUTPUT_PREFIX)) {
+ // Assistant message: ┊ 💬 {text}
+ if (isAssistantToolLine(trimmed)) {
+ return [{ kind: "assistant", ts, text: extractAssistantText(trimmed) }];
+ }
+
+ // Tool completion: ┊ {emoji} {verb} {detail} {duration}
+ const toolInfo = parseToolCompletionLine(trimmed);
+ if (toolInfo) {
+ const id = syntheticToolUseId();
+ const detailText = toolInfo.duration
+ ? `${toolInfo.detail} ${toolInfo.duration}`
+ : toolInfo.detail;
+
+ return [
+ {
+ kind: "tool_call" as const,
+ ts,
+ name: toolInfo.name,
+ input: { detail: toolInfo.detail },
+ toolUseId: id,
+ },
+ {
+ kind: "tool_result" as const,
+ ts,
+ toolUseId: id,
+ content: detailText,
+ isError: toolInfo.hasError,
+ },
+ ] as TranscriptEntry[];
+ }
+
+ // Fallback: raw ┊ line that doesn't match tool format
+ const stripped = trimmed
+ .replace(/^\[done\]\s*/, "")
+ .replace(new RegExp(`^${TOOL_OUTPUT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*`), "")
+ .trim();
+ return [{ kind: "stdout", ts, text: stripped }];
+ }
+
+ // ── Thinking blocks ────────────────────────────────────────────────────
+ if (isThinkingLine(trimmed)) {
+ return [
+ {
+ kind: "thinking",
+ ts,
+ text: trimmed.replace(/^💭\s*/, ""),
+ },
+ ];
+ }
+
+ // ── Error output ───────────────────────────────────────────────────────
+ if (
+ trimmed.startsWith("Error:") ||
+ trimmed.startsWith("ERROR:") ||
+ trimmed.startsWith("Traceback")
+ ) {
+ return [{ kind: "stderr", ts, text: trimmed }];
+ }
+
+ // ── Regular assistant output ───────────────────────────────────────────
+ return [{ kind: "assistant", ts, text: trimmed }];
+}
diff --git a/packages/adapters/hermes/tsconfig.json b/packages/adapters/hermes/tsconfig.json
new file mode 100644
index 0000000000..8fea361a34
--- /dev/null
+++ b/packages/adapters/hermes/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src",
+ "types": ["node"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/adapters/hermes/ui-parser.cjs b/packages/adapters/hermes/ui-parser.cjs
new file mode 100644
index 0000000000..618c37606c
--- /dev/null
+++ b/packages/adapters/hermes/ui-parser.cjs
@@ -0,0 +1,193 @@
+"use strict";
+
+const TOOL_OUTPUT_PREFIX = "\u250a";
+
+function stripKaomoji(text) {
+ return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();
+}
+
+function isAssistantToolLine(stripped) {
+ return /^\u250a\s*\u{1f4ac}/u.test(stripped);
+}
+
+function extractAssistantText(line) {
+ return line.replace(/^[\s\u250a]*\u{1f4ac}\s*/u, "").trim();
+}
+
+function parseToolCompletionLine(line) {
+ let cleaned = line.trim().replace(/^\[done\]\s*/, "");
+ if (!cleaned.startsWith(TOOL_OUTPUT_PREFIX)) return null;
+
+ cleaned = cleaned.slice(TOOL_OUTPUT_PREFIX.length);
+ cleaned = stripKaomoji(cleaned).trim();
+
+ const durationMatch = cleaned.match(/([\d.]+s)\s*(?:\([\d.]+s\))?\s*$/);
+ const duration = durationMatch ? durationMatch[1] : "";
+ const verbAndDetail = durationMatch
+ ? cleaned.slice(0, cleaned.lastIndexOf(durationMatch[0])).trim()
+ : cleaned;
+ const detailWithoutEmoji = verbAndDetail.replace(/^\p{Emoji_Presentation}\s*/u, "");
+
+ const hasError = /\[(?:exit \d+|error|full)\]/.test(detailWithoutEmoji) ||
+ /\[error\]\s*$/.test(cleaned);
+
+ const parts = detailWithoutEmoji.match(/^(\S+)\s+(.*)/);
+ if (!parts) {
+ return { name: "tool", detail: detailWithoutEmoji, duration, hasError };
+ }
+
+ const verb = parts[1];
+ const detail = parts[2].trim();
+ const nameMap = {
+ "$": "shell",
+ exec: "shell",
+ terminal: "shell",
+ search: "search",
+ fetch: "fetch",
+ crawl: "crawl",
+ navigate: "browser",
+ snapshot: "browser",
+ click: "browser",
+ type: "browser",
+ scroll: "browser",
+ back: "browser",
+ press: "browser",
+ close: "browser",
+ images: "browser",
+ vision: "browser",
+ read: "read",
+ write: "write",
+ patch: "patch",
+ grep: "search",
+ find: "search",
+ plan: "plan",
+ recall: "recall",
+ proc: "process",
+ delegate: "delegate",
+ todo: "todo",
+ memory: "memory",
+ clarify: "clarify",
+ session_search: "recall",
+ code: "execute",
+ execute: "execute",
+ web_search: "search",
+ web_extract: "fetch",
+ browser_navigate: "browser",
+ browser_click: "browser",
+ browser_type: "browser",
+ browser_snapshot: "browser",
+ browser_vision: "browser",
+ browser_scroll: "browser",
+ browser_press: "browser",
+ browser_back: "browser",
+ browser_close: "browser",
+ browser_get_images: "browser",
+ read_file: "read",
+ write_file: "write_file",
+ search_files: "search",
+ patch_file: "patch",
+ execute_code: "execute",
+ };
+
+ return {
+ name: nameMap[verb.toLowerCase()] || verb,
+ detail,
+ duration,
+ hasError,
+ };
+}
+
+let toolCallCounter = 0;
+
+function syntheticToolUseId() {
+ toolCallCounter += 1;
+ return `hermes-tool-${toolCallCounter}`;
+}
+
+function isThinkingLine(line) {
+ return (
+ line.includes("\u{1f4ad}") ||
+ line.startsWith("<thinking>") ||
+ line.startsWith("</thinking>") ||
+ line.startsWith("Thinking:")
+ );
+}
+
+function parseStdoutLine(line, ts) {
+ const trimmed = line.trim();
+ if (!trimmed) return [];
+
+ if (trimmed.startsWith("[hermes]") || trimmed.startsWith("[paperclip]")) {
+ return [{ kind: "system", ts, text: trimmed }];
+ }
+
+ if (trimmed.startsWith("[tool]")) {
+ return [];
+ }
+
+ if (/^\[\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+ return [{ kind: "stderr", ts, text: trimmed }];
+ }
+
+ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(trimmed)) {
+ return [];
+ }
+
+ if (trimmed.startsWith("session_id:")) {
+ return [{ kind: "system", ts, text: trimmed }];
+ }
+
+ if (trimmed.includes(TOOL_OUTPUT_PREFIX)) {
+ if (isAssistantToolLine(trimmed)) {
+ return [{ kind: "assistant", ts, text: extractAssistantText(trimmed) }];
+ }
+
+ const toolInfo = parseToolCompletionLine(trimmed);
+ if (toolInfo) {
+ const id = syntheticToolUseId();
+ const detailText = toolInfo.duration
+ ? `${toolInfo.detail} ${toolInfo.duration}`
+ : toolInfo.detail;
+
+ return [
+ {
+ kind: "tool_call",
+ ts,
+ name: toolInfo.name,
+ input: { detail: toolInfo.detail },
+ toolUseId: id,
+ },
+ {
+ kind: "tool_result",
+ ts,
+ toolUseId: id,
+ content: detailText,
+ isError: toolInfo.hasError,
+ },
+ ];
+ }
+
+ const escapedPrefix = TOOL_OUTPUT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ const stripped = trimmed
+ .replace(/^\[done\]\s*/, "")
+ .replace(new RegExp(`^${escapedPrefix}\\s*`), "")
+ .trim();
+ return [{ kind: "stdout", ts, text: stripped }];
+ }
+
+ if (isThinkingLine(trimmed)) {
+ return [{ kind: "thinking", ts, text: trimmed.replace(/^\u{1f4ad}\s*/u, "") }];
+ }
+
+ if (
+ trimmed.startsWith("Error:") ||
+ trimmed.startsWith("ERROR:") ||
+ trimmed.startsWith("Traceback")
+ ) {
+ return [{ kind: "stderr", ts, text: trimmed }];
+ }
+
+ return [{ kind: "assistant", ts, text: trimmed }];
+}
+
+module.exports = { parseStdoutLine };
diff --git a/packages/adapters/hermes/vitest.config.ts b/packages/adapters/hermes/vitest.config.ts
new file mode 100644
index 0000000000..ad7d95889a
--- /dev/null
+++ b/packages/adapters/hermes/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ exclude: ["dist/**", "node_modules/**"],
+ },
+});
diff --git a/packages/adapters/opencode-local/src/server/execute.remote.test.ts b/packages/adapters/opencode-local/src/server/execute.remote.test.ts
index f13fa4d5e6..dab6280423 100644
--- a/packages/adapters/opencode-local/src/server/execute.remote.test.ts
+++ b/packages/adapters/opencode-local/src/server/execute.remote.test.ts
@@ -1,7 +1,7 @@
import { mkdir, mkdtemp, rm } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const {
runChildProcess,
@@ -102,9 +102,19 @@ import { execute } from "./execute.js";
describe("opencode remote execution", () => {
const cleanupDirs: string[] = [];
+ const originalOpenCodeAllowAllModels = process.env.OPENCODE_ALLOW_ALL_MODELS;
+
+ beforeEach(() => {
+ delete process.env.OPENCODE_ALLOW_ALL_MODELS;
+ });
afterEach(async () => {
vi.clearAllMocks();
+ if (originalOpenCodeAllowAllModels === undefined) {
+ delete process.env.OPENCODE_ALLOW_ALL_MODELS;
+ } else {
+ process.env.OPENCODE_ALLOW_ALL_MODELS = originalOpenCodeAllowAllModels;
+ }
while (cleanupDirs.length > 0) {
const dir = cleanupDirs.pop();
if (!dir) continue;
diff --git a/packages/db/src/migrations/0124_agent_api_key_scope_config.sql b/packages/db/src/migrations/0124_agent_api_key_scope_config.sql
new file mode 100644
index 0000000000..52167d2526
--- /dev/null
+++ b/packages/db/src/migrations/0124_agent_api_key_scope_config.sql
@@ -0,0 +1 @@
+ALTER TABLE "agent_api_keys" ADD COLUMN IF NOT EXISTS "scope_config" jsonb;
diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.json
index 1956b93218..6c63f8b5d9 100644
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@@ -869,6 +869,13 @@
"when": 1781903700000,
"tag": "0123_document_annotation_source_trust",
"breakpoints": true
+ },
+ {
+ "idx": 124,
+ "version": "7",
+ "when": 1782440000000,
+ "tag": "0124_agent_api_key_scope_config",
+ "breakpoints": true
}
]
}
diff --git a/packages/db/src/schema/agent_api_keys.ts b/packages/db/src/schema/agent_api_keys.ts
index 025fab437f..8cc430ae00 100644
--- a/packages/db/src/schema/agent_api_keys.ts
+++ b/packages/db/src/schema/agent_api_keys.ts
@@ -1,4 +1,5 @@
-import { pgTable, uuid, text, timestamp, index } from "drizzle-orm/pg-core";
+import { pgTable, uuid, text, timestamp, index, jsonb } from "drizzle-orm/pg-core";
+import type { AgentApiKeyScope } from "@paperclipai/shared";
import { agents } from "./agents.js";
import { companies } from "./companies.js";
@@ -10,6 +11,7 @@ export const agentApiKeys = pgTable(
companyId: uuid("company_id").notNull().references(() => companies.id),
name: text("name").notNull(),
keyHash: text("key_hash").notNull(),
+ scopeConfig: jsonb("scope_config").$type<AgentApiKeyScope | null>(),
lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
revokedAt: timestamp("revoked_at", { withTimezone: true }),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index f4c9836762..8725947eca 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -35,6 +35,8 @@ export const AGENT_ADAPTER_TYPES = [
"codex_local",
"cursor_cloud",
"gemini_local",
+ "hermes_gateway",
+ "hermes_local",
"opencode_local",
"pi_local",
"cursor",
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index d098b39d00..07f4dd4256 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1052,6 +1052,10 @@ export {
updateAgentInstructionsBundleSchema,
upsertAgentInstructionsFileSchema,
updateAgentInstructionsPathSchema,
+ agentApiKeyScopeSchema,
+ normalizeAgentApiKeyScope,
+ standardAgentKeyScopeSchema,
+ taskBridgeAgentKeyScopeSchema,
createAgentKeySchema,
agentMineInboxQuerySchema,
wakeAgentSchema,
@@ -1065,6 +1069,8 @@ export {
type UpdateAgentInstructionsBundle,
type UpsertAgentInstructionsFile,
type UpdateAgentInstructionsPath,
+ type AgentApiKeyScope,
+ type TaskBridgeAgentKeyScope,
type CreateAgentKey,
type AgentMineInboxQuery,
type WakeAgent,
diff --git a/packages/shared/src/types/agent.ts b/packages/shared/src/types/agent.ts
index ad16c7dad8..38df57ba1e 100644
--- a/packages/shared/src/types/agent.ts
+++ b/packages/shared/src/types/agent.ts
@@ -14,6 +14,7 @@ import type {
TrustPreset,
} from "../trust-policy.js";
import type { AgentOrgChainHealth } from "../agent-eligibility.js";
+import type { AgentApiKeyScope } from "../validators/agent.js";
export interface AgentPermissions extends Record<string, unknown> {
canCreateAgents: boolean;
@@ -116,6 +117,7 @@ export type ClearAgentErrorResponse = Agent;
export interface AgentKeyCreated {
id: string;
name: string;
+ scope: AgentApiKeyScope;
token: string;
createdAt: Date;
}
diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.ts
index 69f1b5b233..65934b7e6d 100644
--- a/packages/shared/src/validators/agent.ts
+++ b/packages/shared/src/validators/agent.ts
@@ -114,8 +114,45 @@ export const updateAgentInstructionsPathSchema = z.object({
export type UpdateAgentInstructionsPath = z.infer<typeof updateAgentInstructionsPathSchema>;
+export const taskBridgeAgentKeyScopeSchema = z.object({
+ kind: z.literal("task_bridge"),
+ projectId: z.string().uuid().optional().nullable(),
+ projectIds: z.array(z.string().uuid()).max(50).optional(),
+ parentIssueId: z.string().uuid().optional().nullable(),
+ parentIssueIds: z.array(z.string().uuid()).max(50).optional(),
+ allowedAssigneeAgentIds: z.array(z.string().uuid()).max(50).optional(),
+}).strict().superRefine((value, ctx) => {
+ const hasProjectBoundary = Boolean(value.projectId) || Boolean(value.projectIds?.length);
+ const hasParentBoundary = Boolean(value.parentIssueId) || Boolean(value.parentIssueIds?.length);
+ if (!hasProjectBoundary && !hasParentBoundary) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "task_bridge keys require at least one project or parent issue boundary",
+ path: ["projectId"],
+ });
+ }
+});
+
+export const standardAgentKeyScopeSchema = z.object({
+ kind: z.literal("standard"),
+}).strict();
+
+export const agentApiKeyScopeSchema = z.union([
+ standardAgentKeyScopeSchema,
+ taskBridgeAgentKeyScopeSchema,
+]);
+
+export type AgentApiKeyScope = z.infer<typeof agentApiKeyScopeSchema>;
+export type TaskBridgeAgentKeyScope = z.infer<typeof taskBridgeAgentKeyScopeSchema>;
+
+export function normalizeAgentApiKeyScope(value: unknown): AgentApiKeyScope {
+ const parsed = agentApiKeyScopeSchema.safeParse(value);
+ return parsed.success ? parsed.data : { kind: "standard" };
+}
+
export const createAgentKeySchema = z.object({
name: z.string().min(1).default("default"),
+ scope: agentApiKeyScopeSchema.optional().default({ kind: "standard" }),
});
export type CreateAgentKey = z.infer<typeof createAgentKeySchema>;
diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts
index 43fcc8ac84..9e3fd62649 100644
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@@ -207,6 +207,10 @@ export {
updateAgentInstructionsBundleSchema,
upsertAgentInstructionsFileSchema,
updateAgentInstructionsPathSchema,
+ agentApiKeyScopeSchema,
+ normalizeAgentApiKeyScope,
+ standardAgentKeyScopeSchema,
+ taskBridgeAgentKeyScopeSchema,
createAgentKeySchema,
agentMineInboxQuerySchema,
wakeAgentSchema,
@@ -220,6 +224,8 @@ export {
type UpdateAgentInstructionsBundle,
type UpsertAgentInstructionsFile,
type UpdateAgentInstructionsPath,
+ type AgentApiKeyScope,
+ type TaskBridgeAgentKeyScope,
type CreateAgentKey,
type AgentMineInboxQuery,
type WakeAgent,
diff --git a/scripts/bootstrap-npm-package.mjs b/scripts/bootstrap-npm-package.mjs
index 9b1e01beb0..b255d59ab6 100644
--- a/scripts/bootstrap-npm-package.mjs
+++ b/scripts/bootstrap-npm-package.mjs
@@ -2,7 +2,7 @@
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
-import { dirname, join, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
import { buildReleasePackagePlan } from "./release-package-map.mjs";
@@ -187,13 +187,24 @@ function printNextSteps(pkg) {
);
}
-function publishPackage(pkg, otp) {
- const publishArgs = ["publish", "--access", "public"];
+function buildPublishArgs(pkg, { dryRun = false, otp = null } = {}) {
+ const args = ["publish", pkg.dir, "--no-git-checks", "--access", "public"];
+
+ if (dryRun) {
+ args.push("--dry-run");
+ }
+
if (otp) {
- publishArgs.push("--otp", otp);
+ args.push("--otp", otp);
}
- const result = runCommand("npm", publishArgs, { cwd: join(repoRoot, pkg.dir) });
+ return args;
+}
+
+function publishPackage(pkg, otp) {
+ const publishArgs = buildPublishArgs(pkg, { otp });
+
+ const result = runCommand("pnpm", publishArgs);
const stdout = result.stdout ?? "";
const stderr = result.stderr ?? "";
const output = `${stdout}\n${stderr}`.trim();
@@ -214,7 +225,7 @@ function publishPackage(pkg, otp) {
);
}
- throw new Error(`${formatCommand("npm", publishArgs)} failed with status ${result.status ?? "unknown"}`);
+ throw new Error(`${formatCommand("pnpm", publishArgs)} failed with status ${result.status ?? "unknown"}`);
}
function main(argv) {
@@ -255,7 +266,7 @@ function main(argv) {
}
process.stdout.write(`Previewing publish payload for ${pkg.name}...\n`);
- runChecked("npm", ["pack", "--dry-run"], { cwd: join(repoRoot, pkg.dir) });
+ runChecked("pnpm", buildPublishArgs(pkg, { dryRun: true }));
if (!publish) {
process.stdout.write(
@@ -286,6 +297,7 @@ if (isDirectRun) {
}
export {
+ buildPublishArgs,
ensureNpmAuth,
inspectNpmPackage,
parseArgs,
diff --git a/scripts/bootstrap-npm-package.test.mjs b/scripts/bootstrap-npm-package.test.mjs
index 32270f6be4..2f68662a90 100644
--- a/scripts/bootstrap-npm-package.test.mjs
+++ b/scripts/bootstrap-npm-package.test.mjs
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { parseArgs, resolveTargetPackage } from "./bootstrap-npm-package.mjs";
+import { buildPublishArgs, parseArgs, resolveTargetPackage } from "./bootstrap-npm-package.mjs";
test("parseArgs recognizes publish and skip-build flags", () => {
assert.deepEqual(parseArgs(["@paperclipai/adapter-acpx-local", "--publish", "--skip-build"]), {
@@ -58,3 +58,30 @@ test("resolveTargetPackage includes the workspace diff plugin bootstrap package"
assert.equal(pkg.dir, "packages/plugins/plugin-workspace-diff");
});
+
+test("buildPublishArgs publishes from the repo root through pnpm", () => {
+ const pkg = { dir: "packages/adapters/hermes", name: "@paperclipai/hermes-paperclip-adapter" };
+
+ assert.deepEqual(buildPublishArgs(pkg), [
+ "publish",
+ "packages/adapters/hermes",
+ "--no-git-checks",
+ "--access",
+ "public",
+ ]);
+});
+
+test("buildPublishArgs includes dry-run and otp flags when requested", () => {
+ const pkg = { dir: "packages/adapters/hermes", name: "@paperclipai/hermes-paperclip-adapter" };
+
+ assert.deepEqual(buildPublishArgs(pkg, { dryRun: true, otp: "123456" }), [
+ "publish",
+ "packages/adapters/hermes",
+ "--no-git-checks",
+ "--access",
+ "public",
+ "--dry-run",
+ "--otp",
+ "123456",
+ ]);
+});
diff --git a/scripts/generate-npm-package-json.mjs b/scripts/generate-npm-package-json.mjs
index f7be8cc04b..72fd63f443 100644
--- a/scripts/generate-npm-package-json.mjs
+++ b/scripts/generate-npm-package-json.mjs
@@ -32,6 +32,8 @@ const workspacePaths = [
"packages/adapter-utils",
"packages/adapters/claude-local",
"packages/adapters/codex-local",
+ "packages/adapters/hermes-gateway",
+ "packages/adapters/hermes",
"packages/adapters/opencode-local",
"packages/adapters/openclaw-gateway",
];
diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.json
index 9f85129782..d0c1e83579 100644
--- a/scripts/release-package-manifest.json
+++ b/scripts/release-package-manifest.json
@@ -39,6 +39,16 @@
"name": "@paperclipai/adapter-grok-local",
"publishFromCi": true
},
+ {
+ "dir": "packages/adapters/hermes",
+ "name": "@paperclipai/hermes-paperclip-adapter",
+ "publishFromCi": true
+ },
+ {
+ "dir": "packages/adapters/hermes-gateway",
+ "name": "@paperclipai/adapter-hermes-gateway",
+ "publishFromCi": false
+ },
{
"dir": "packages/adapters/opencode-local",
"name": "@paperclipai/adapter-opencode-local",
diff --git a/scripts/release-package-map.test.mjs b/scripts/release-package-map.test.mjs
index b632b92e8b..577186057b 100644
--- a/scripts/release-package-map.test.mjs
+++ b/scripts/release-package-map.test.mjs
@@ -24,6 +24,17 @@ test("release package list only contains CI-enrolled packages", () => {
assert.ok(enabledPackages.every((pkg) => pkg.publishFromCi === true));
});
+test("Hermes release surface publishes the unified built-in package and keeps gateway as a shim", () => {
+ const packages = buildReleasePackagePlan();
+ const hermes = packages.find((pkg) => pkg.name === "@paperclipai/hermes-paperclip-adapter");
+ const gatewayShim = packages.find((pkg) => pkg.name === "@paperclipai/adapter-hermes-gateway");
+
+ assert.equal(hermes?.dir, "packages/adapters/hermes");
+ assert.equal(hermes?.publishFromCi, true);
+ assert.equal(gatewayShim?.dir, "packages/adapters/hermes-gateway");
+ assert.equal(gatewayShim?.publishFromCi, false);
+});
+
test("release package configuration validates successfully", () => {
assert.doesNotThrow(() => checkConfiguration());
});
diff --git a/scripts/smoke/hermes-gateway-e2e.sh b/scripts/smoke/hermes-gateway-e2e.sh
new file mode 100755
index 0000000000..7aac9c1736
--- /dev/null
+++ b/scripts/smoke/hermes-gateway-e2e.sh
@@ -0,0 +1,1007 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() {
+ echo "[hermes-gateway-e2e] $*"
+}
+
+warn() {
+ echo "[hermes-gateway-e2e] WARN: $*" >&2
+}
+
+fail() {
+ echo "[hermes-gateway-e2e] ERROR: $*" >&2
+ if [[ -n "${HERMES_SMOKE_DIAG_DIR:-}" ]]; then
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR" 2>/dev/null || true
+ printf "%s\n" "$*" > "${HERMES_SMOKE_DIAG_DIR}/failure.txt" 2>/dev/null || true
+ fi
+ exit 1
+}
+
+require_cmd() {
+ local cmd="$1"
+ command -v "$cmd" >/dev/null 2>&1 || fail "missing required command: ${cmd}"
+}
+
+PAPERCLIP_API_URL="${PAPERCLIP_API_URL:-http://127.0.0.1:3100}"
+API_BASE="${PAPERCLIP_API_URL%/}/api"
+COMPANY_ID="${COMPANY_ID:-${PAPERCLIP_COMPANY_ID:-}}"
+COMPANY_SELECTOR="${COMPANY_SELECTOR:-}"
+
+RUN_SUFFIX="${HERMES_SMOKE_RUN_SUFFIX:-$(date +%Y%m%d-%H%M%S)-$$}"
+HERMES_IMAGE="${HERMES_IMAGE:-paperclip-hermes-gateway-smoke:local}"
+HERMES_VERSION="${HERMES_VERSION:-0.17.0}"
+HERMES_BUILD="${HERMES_BUILD:-1}"
+HERMES_DOCKER_CONTEXT="${HERMES_DOCKER_CONTEXT:-docker/hermes-gateway-smoke}"
+HERMES_CONTAINER_NAME="${HERMES_CONTAINER_NAME:-paperclip-hermes-gateway-smoke-${RUN_SUFFIX}}"
+HERMES_GATEWAY_PORT="${HERMES_GATEWAY_PORT:-8642}"
+HERMES_GATEWAY_API_BASE_URL="${HERMES_GATEWAY_API_BASE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT}}"
+HERMES_GATEWAY_PROBE_URL="${HERMES_GATEWAY_PROBE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT}}"
+HERMES_GATEWAY_API_KEY="${HERMES_GATEWAY_API_KEY:-${API_SERVER_KEY:-}}"
+HERMES_GATEWAY_ALLOW_INSECURE_HTTP="${HERMES_GATEWAY_ALLOW_INSECURE_HTTP:-0}"
+HERMES_GATEWAY_SESSION_KEY_STRATEGY="${HERMES_GATEWAY_SESSION_KEY_STRATEGY:-issue}"
+HERMES_ADAPTER_TIMEOUT_SEC="${HERMES_ADAPTER_TIMEOUT_SEC:-180}"
+HERMES_DIRECT_RUN_TIMEOUT_SEC="${HERMES_DIRECT_RUN_TIMEOUT_SEC:-180}"
+HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC="${HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC:-20}"
+HERMES_STOP_ASSERT="${HERMES_STOP_ASSERT:-auto}"
+HERMES_SMOKE_KEEP="${HERMES_SMOKE_KEEP:-0}"
+HERMES_SMOKE_NETWORK="${HERMES_SMOKE_NETWORK:-}"
+HERMES_DOCKER_ADD_HOST="${HERMES_DOCKER_ADD_HOST:-1}"
+HERMES_SMOKE_STATE_DIR="${HERMES_SMOKE_STATE_DIR:-${TMPDIR:-/tmp}/paperclip-hermes-gateway-smoke-${RUN_SUFFIX}}"
+HERMES_SMOKE_DIAG_DIR="${HERMES_SMOKE_DIAG_DIR:-${TMPDIR:-/tmp}/paperclip-hermes-gateway-e2e-diag-${RUN_SUFFIX}}"
+HERMES_SMOKE_MODEL_PROVIDER="${HERMES_SMOKE_MODEL_PROVIDER:-}"
+HERMES_SMOKE_MODEL_DEFAULT="${HERMES_SMOKE_MODEL_DEFAULT:-}"
+HERMES_SMOKE_MODEL_BASE_URL="${HERMES_SMOKE_MODEL_BASE_URL:-}"
+HERMES_AGENT_NAME="${HERMES_AGENT_NAME:-Hermes Gateway Smoke Agent ${RUN_SUFFIX}}"
+PAPERCLIP_API_URL_FOR_HERMES="${PAPERCLIP_API_URL_FOR_HERMES:-http://host.docker.internal:3100}"
+RUN_TIMEOUT_SEC="${RUN_TIMEOUT_SEC:-420}"
+CASE_TIMEOUT_SEC="${CASE_TIMEOUT_SEC:-420}"
+GATEWAY_READY_TIMEOUT_SEC="${GATEWAY_READY_TIMEOUT_SEC:-90}"
+STRICT_CASES="${STRICT_CASES:-1}"
+HERMES_PROVIDER_ENV_KEYS=(
+ OPENROUTER_API_KEY
+ OPENAI_API_KEY
+ ANTHROPIC_API_KEY
+ GEMINI_API_KEY
+ GOOGLE_API_KEY
+ MISTRAL_API_KEY
+)
+
+print_usage() {
+ cat <<'EOF'
+Hermes gateway Docker E2E smoke
+
+Builds a fresh Hermes gateway container, verifies the gateway API directly,
+joins it to Paperclip as a hermes_gateway agent, wakes that agent on a smoke
+issue, verifies the issue result, captures redacted diagnostics, and cleans up
+Paperclip and Docker state unless HERMES_SMOKE_KEEP=1.
+
+Required:
+ PAPERCLIP_API_URL=http://127.0.0.1:3100
+ PAPERCLIP_AUTH_HEADER='Bearer <board-token>' # or PAPERCLIP_COOKIE
+
+Common flags:
+ COMPANY_ID=<uuid> or COMPANY_SELECTOR=<prefix|name|uuid>
+ HERMES_VERSION=0.17.0
+ HERMES_IMAGE=paperclip-hermes-gateway-smoke:local
+ HERMES_GATEWAY_PORT=8642
+ HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642
+ HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642
+ PAPERCLIP_API_URL_FOR_HERMES=http://host.docker.internal:3100
+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 # dev-only non-loopback HTTP
+ HERMES_SMOKE_NETWORK=<docker-network>
+ HERMES_DOCKER_ADD_HOST=0|1
+ HERMES_SMOKE_KEEP=1 # keep diagnostics/container
+ HERMES_SMOKE_DIAG_DIR=/tmp/hermes-gateway-diag
+ HERMES_SMOKE_MODEL_PROVIDER=openrouter
+ HERMES_SMOKE_MODEL_DEFAULT=z-ai/glm-5.2
+ HERMES_SMOKE_MODEL_BASE_URL=https://openrouter.ai/api/v1
+
+Mode notes:
+ HERMES_GATEWAY_API_BASE_URL is the URL stored on the Paperclip adapter and
+ must be reachable by the Paperclip server. HERMES_GATEWAY_PROBE_URL is the URL
+ this operator shell uses for direct gateway checks. They can differ for Docker
+ network and reverse-proxy smoke runs.
+
+ Raw Hermes and Paperclip API keys are redacted from logs and diagnostic files.
+ The E2E helper seeds a minimal non-secret Hermes config in the fresh container
+ state, including command_allowlist: execute_code so gateway/API runs do not
+ pause on an interactive approval prompt.
+ The generated/claimed key material is kept only in the per-run state directory,
+ which is deleted on success unless HERMES_SMOKE_KEEP=1.
+
+See doc/HERMES_GATEWAY_SMOKE.md for Docker Desktop, Linux, same-network,
+LAN/private-network, and reverse-proxy/TLS examples.
+EOF
+}
+
+case "${1:-}" in
+ -h|--help)
+ print_usage
+ exit 0
+ ;;
+esac
+
+AUTH_HEADERS=()
+if [[ -n "${PAPERCLIP_AUTH_HEADER:-}" ]]; then
+ AUTH_HEADERS+=(-H "Authorization: ${PAPERCLIP_AUTH_HEADER}")
+elif [[ -n "${PAPERCLIP_API_KEY:-}" ]]; then
+ AUTH_HEADERS+=(-H "Authorization: Bearer ${PAPERCLIP_API_KEY}")
+fi
+if [[ -n "${PAPERCLIP_COOKIE:-}" ]]; then
+ AUTH_HEADERS+=(-H "Cookie: ${PAPERCLIP_COOKIE}")
+ PAPERCLIP_BROWSER_ORIGIN="${PAPERCLIP_BROWSER_ORIGIN:-${PAPERCLIP_API_URL%/}}"
+ AUTH_HEADERS+=(-H "Origin: ${PAPERCLIP_BROWSER_ORIGIN}" -H "Referer: ${PAPERCLIP_BROWSER_ORIGIN}/")
+fi
+
+RESPONSE_CODE=""
+RESPONSE_BODY=""
+AGENT_ID=""
+AGENT_API_KEY=""
+INVITE_ID=""
+JOIN_REQUEST_ID=""
+KEY_ID=""
+SMOKE_ISSUE_ID=""
+SMOKE_ISSUE_IDENTIFIER=""
+RUN_ID=""
+DIRECT_RUN_ID=""
+STOP_RUN_ID=""
+JOIN_OUTPUT_FILE="${HERMES_SMOKE_DIAG_DIR}/join-output.json"
+KEEP_ON_EXIT="$HERMES_SMOKE_KEEP"
+
+hash_prefix() {
+ local value="$1"
+ if command -v sha256sum >/dev/null 2>&1; then
+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'
+ elif command -v shasum >/dev/null 2>&1; then
+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'
+ else
+ printf "unavailable"
+ fi
+}
+
+generate_key() {
+ if command -v openssl >/dev/null 2>&1; then
+ openssl rand -hex 32
+ elif command -v node >/dev/null 2>&1; then
+ node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))'
+ else
+ fail "missing openssl or node for API_SERVER_KEY generation"
+ fi
+}
+
+redact_text() {
+ local text="$1"
+ local secret
+ for secret in \
+ "${HERMES_GATEWAY_API_KEY:-}" \
+ "${AGENT_API_KEY:-}" \
+ "${PAPERCLIP_API_KEY:-}" \
+ "${PAPERCLIP_AUTH_HEADER:-}" \
+ "${PAPERCLIP_COOKIE:-}"; do
+ if [[ -n "$secret" ]]; then
+ text="${text//$secret/[redacted len=${#secret}]}"
+ fi
+ done
+ local key
+ for key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do
+ secret="${!key-}"
+ if [[ -n "$secret" ]]; then
+ text="${text//$secret/[redacted len=${#secret}]}"
+ fi
+ done
+ printf "%s" "$text"
+}
+
+url_host() {
+ local url="$1"
+ local rest host_port host
+ rest="${url#http://}"
+ rest="${rest#https://}"
+ if [[ "$rest" == \[*\]* ]]; then
+ host="${rest#\[}"
+ host="${host%%\]*}"
+ else
+ host_port="${rest%%/*}"
+ host="${host_port%%:*}"
+ fi
+ printf "%s" "$host"
+}
+
+is_loopback_http_host() {
+ local host
+ host="$(printf "%s" "$1" | tr '[:upper:]' '[:lower:]')"
+ case "$host" in
+ localhost|0.0.0.0|::1|0:0:0:0:0:0:0:1) return 0 ;;
+ esac
+ [[ "$host" =~ ^127\.([0-9]{1,3}\.){2}[0-9]{1,3}$ ]]
+}
+
+is_remote_plain_http() {
+ local url="$1"
+ [[ "$url" == http://* ]] || return 1
+ ! is_loopback_http_host "$(url_host "$url")"
+}
+
+assert_gateway_api_base_url_allowed() {
+ if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL" && [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" != "1" ]]; then
+ fail "HERMES_GATEWAY_API_BASE_URL uses non-loopback http. Set HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 for local-only unsafe HTTP, or use HTTPS."
+ fi
+}
+
+api_request() {
+ local method="$1"
+ local path="$2"
+ local data="${3-}"
+ local tmp
+ tmp="$(mktemp)"
+
+ local url
+ if [[ "$path" == http://* || "$path" == https://* ]]; then
+ url="$path"
+ elif [[ "$path" == /api/* ]]; then
+ url="${PAPERCLIP_API_URL%/}${path}"
+ else
+ url="${API_BASE}${path}"
+ fi
+
+ if [[ -n "$data" ]]; then
+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" -H "Content-Type: application/json" "$url" --data "$data")"
+ else
+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" "$url")"
+ fi
+ RESPONSE_BODY="$(cat "$tmp")"
+ rm -f "$tmp"
+}
+
+assert_status() {
+ local expected="$1"
+ if [[ "$RESPONSE_CODE" != "$expected" ]]; then
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+ fail "expected HTTP ${expected}, got HTTP ${RESPONSE_CODE}"
+ fi
+}
+
+gateway_request() {
+ local method="$1"
+ local path="$2"
+ local data="${3-}"
+ local output_file="${4-}"
+ local tmp
+ tmp="$(mktemp)"
+
+ local url="${HERMES_GATEWAY_PROBE_URL%/}${path}"
+ if [[ -n "$data" ]]; then
+ RESPONSE_CODE="$(curl -s -o "$tmp" -w "%{http_code}" -X "$method" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" -H "Content-Type: application/json" "$url" --data "$data" || true)"
+ else
+ RESPONSE_CODE="$(curl -s -o "$tmp" -w "%{http_code}" -X "$method" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$url" || true)"
+ fi
+ RESPONSE_BODY="$(cat "$tmp")"
+ if [[ -n "$output_file" ]]; then
+ redact_text "$RESPONSE_BODY" > "$output_file"
+ fi
+ rm -f "$tmp"
+}
+
+wait_http_ready() {
+ local url="$1"
+ local timeout_sec="$2"
+ local started now code
+ started="$(date +%s)"
+ while true; do
+ code="$(curl -sS -o /dev/null -w "%{http_code}" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$url" || true)"
+ if [[ "$code" == "200" ]]; then
+ return 0
+ fi
+ now="$(date +%s)"
+ if (( now - started >= timeout_sec )); then
+ return 1
+ fi
+ sleep 1
+ done
+}
+
+require_board_auth() {
+ if [[ ${#AUTH_HEADERS[@]} -eq 0 ]]; then
+ fail "board/operator auth required. Set PAPERCLIP_COOKIE, PAPERCLIP_AUTH_HEADER, or a board-capable PAPERCLIP_API_KEY."
+ fi
+ api_request "GET" "/companies"
+ if [[ "$RESPONSE_CODE" != "200" ]]; then
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+ fail "board/operator auth invalid for /api/companies (HTTP ${RESPONSE_CODE})"
+ fi
+}
+
+resolve_company_id() {
+ if [[ -n "$COMPANY_ID" ]]; then
+ log "using company ${COMPANY_ID}"
+ return
+ fi
+
+ api_request "GET" "/companies"
+ assert_status "200"
+
+ if [[ -n "$COMPANY_SELECTOR" ]]; then
+ COMPANY_ID="$(jq -r --arg selector "$COMPANY_SELECTOR" '
+ map(select(
+ (.id == $selector)
+ or ((.issuePrefix // "") == $selector)
+ or ((.name // "") == $selector)
+ )) | .[0].id // empty
+ ' <<<"$RESPONSE_BODY")"
+ [[ -n "$COMPANY_ID" ]] || fail "no company matched COMPANY_SELECTOR=${COMPANY_SELECTOR}"
+ else
+ COMPANY_ID="$(jq -r '.[0].id // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$COMPANY_ID" ]] || fail "no companies found"
+ fi
+ log "resolved company ${COMPANY_ID}"
+}
+
+capture_container_logs() {
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+ docker logs --tail=2000 "$HERMES_CONTAINER_NAME" > "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log" 2>&1 || true
+ if [[ -s "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log" ]]; then
+ local redacted_tmp
+ redacted_tmp="$(mktemp)"
+ redact_text "$(cat "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log")" > "$redacted_tmp"
+ mv "$redacted_tmp" "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log"
+ fi
+}
+
+capture_run_diagnostics() {
+ local run_id="$1"
+ local label="${2:-run}"
+ [[ -n "$run_id" ]] || return 0
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+
+ api_request "GET" "/heartbeat-runs/${run_id}/events?limit=1000"
+ if [[ "$RESPONSE_CODE" == "200" ]]; then
+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-events.json"
+ fi
+
+ api_request "GET" "/heartbeat-runs/${run_id}/log?limitBytes=524288"
+ if [[ "$RESPONSE_CODE" == "200" ]]; then
+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-log.json"
+ jq -r '.content // ""' <<<"$RESPONSE_BODY" | while IFS= read -r line; do redact_text "$line"; echo; done > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-log.txt" 2>/dev/null || true
+ fi
+}
+
+capture_issue_diagnostics() {
+ local issue_id="$1"
+ local label="${2:-issue}"
+ [[ -n "$issue_id" ]] || return 0
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+
+ api_request "GET" "/issues/${issue_id}"
+ if [[ "$RESPONSE_CODE" == "200" ]]; then
+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${issue_id}.json"
+ fi
+
+ api_request "GET" "/issues/${issue_id}/comments"
+ if [[ "$RESPONSE_CODE" == "200" ]]; then
+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${issue_id}-comments.json"
+ fi
+}
+
+capture_diagnostics() {
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+ {
+ echo "runSuffix=${RUN_SUFFIX}"
+ echo "companyId=${COMPANY_ID:-}"
+ echo "agentId=${AGENT_ID:-}"
+ echo "inviteId=${INVITE_ID:-}"
+ echo "joinRequestId=${JOIN_REQUEST_ID:-}"
+ echo "container=${HERMES_CONTAINER_NAME}"
+ echo "image=${HERMES_IMAGE}"
+ echo "gateway=${HERMES_GATEWAY_API_BASE_URL}"
+ echo "gatewayProbe=${HERMES_GATEWAY_PROBE_URL}"
+ echo "paperclipApiUrl=${PAPERCLIP_API_URL}"
+ echo "paperclipApiUrlForHermes=${PAPERCLIP_API_URL_FOR_HERMES}"
+ echo "apiServerKeySha256=$(hash_prefix "${HERMES_GATEWAY_API_KEY:-}") len=${#HERMES_GATEWAY_API_KEY}"
+ echo "agentApiKeySha256=$(hash_prefix "${AGENT_API_KEY:-}") len=${#AGENT_API_KEY}"
+ } > "${HERMES_SMOKE_DIAG_DIR}/summary.env"
+
+ gateway_request "GET" "/health" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-health.json" || true
+ gateway_request "GET" "/v1/capabilities" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-capabilities.json" || true
+ capture_container_logs
+ capture_issue_diagnostics "$SMOKE_ISSUE_ID" "paperclip-smoke"
+ capture_run_diagnostics "$RUN_ID" "paperclip-smoke"
+}
+
+cleanup_paperclip_state() {
+ [[ "$KEEP_ON_EXIT" != "1" ]] || return 0
+
+ if [[ -n "$SMOKE_ISSUE_ID" ]]; then
+ log "deleting smoke issue ${SMOKE_ISSUE_ID}"
+ api_request "DELETE" "/issues/${SMOKE_ISSUE_ID}"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "204" ]]; then
+ warn "delete issue returned HTTP ${RESPONSE_CODE}"
+ fi
+ fi
+
+ if [[ -n "$AGENT_ID" ]]; then
+ log "terminating/deleting smoke agent ${AGENT_ID}"
+ api_request "POST" "/agents/${AGENT_ID}/terminate" "{}"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" ]]; then
+ warn "terminate agent returned HTTP ${RESPONSE_CODE}"
+ fi
+ api_request "DELETE" "/agents/${AGENT_ID}"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "204" ]]; then
+ warn "delete agent returned HTTP ${RESPONSE_CODE}"
+ fi
+ fi
+
+ if [[ -n "$JOIN_REQUEST_ID" && -n "$COMPANY_ID" ]]; then
+ api_request "POST" "/companies/${COMPANY_ID}/join-requests/${JOIN_REQUEST_ID}/reject" "{}"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "409" ]]; then
+ warn "reject join request returned HTTP ${RESPONSE_CODE}"
+ fi
+ fi
+}
+
+cleanup_local_state() {
+ [[ "$KEEP_ON_EXIT" != "1" ]] || return 0
+
+ docker rm -f "$HERMES_CONTAINER_NAME" >/dev/null 2>&1 || true
+ rm -rf "$HERMES_SMOKE_STATE_DIR"
+ rm -f "$JOIN_OUTPUT_FILE"
+}
+
+on_exit() {
+ local status=$?
+ if [[ "$status" -ne 0 ]]; then
+ KEEP_ON_EXIT=1
+ warn "smoke failed; preserving diagnostics/state"
+ capture_diagnostics || true
+ fi
+
+ cleanup_paperclip_state || true
+ cleanup_local_state || true
+
+ if [[ "$KEEP_ON_EXIT" == "1" ]]; then
+ warn "retained diagnostics: ${HERMES_SMOKE_DIAG_DIR}"
+ warn "retained state dir: ${HERMES_SMOKE_STATE_DIR}"
+ warn "retained container: ${HERMES_CONTAINER_NAME}"
+ fi
+ exit "$status"
+}
+trap on_exit EXIT
+
+build_image() {
+ if [[ "$HERMES_BUILD" != "1" ]]; then
+ log "HERMES_BUILD=${HERMES_BUILD}; reusing image ${HERMES_IMAGE}"
+ return
+ fi
+ log "building Hermes gateway image ${HERMES_IMAGE} (HERMES_VERSION=${HERMES_VERSION})"
+ docker build --build-arg "HERMES_VERSION=${HERMES_VERSION}" -t "$HERMES_IMAGE" "$HERMES_DOCKER_CONTEXT"
+}
+
+prepare_fresh_state() {
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+ if [[ -e "$HERMES_SMOKE_STATE_DIR" && "$HERMES_SMOKE_KEEP" != "1" ]]; then
+ rm -rf "$HERMES_SMOKE_STATE_DIR"
+ fi
+ mkdir -p \
+ "${HERMES_SMOKE_STATE_DIR}/hermes-home" \
+ "${HERMES_SMOKE_STATE_DIR}/workspace" \
+ "${HERMES_SMOKE_STATE_DIR}/fake-host-home/.hermes"
+ # These host-created bind mounts must be readable and writable by the
+ # non-root hermes user (uid 10001) inside the container.
+ chmod 777 "${HERMES_SMOKE_STATE_DIR}/hermes-home" "${HERMES_SMOKE_STATE_DIR}/workspace" || true
+ echo "host hermes sentinel ${RUN_SUFFIX}" > "${HERMES_SMOKE_STATE_DIR}/fake-host-home/.hermes/host-sentinel.txt"
+
+ if find "${HERMES_SMOKE_STATE_DIR}/hermes-home" -mindepth 1 -print -quit | grep -q .; then
+ fail "Hermes state dir is not empty: ${HERMES_SMOKE_STATE_DIR}/hermes-home"
+ fi
+}
+
+yaml_single_quote() {
+ local value="$1"
+ value="${value//\'/\'\'}"
+ printf "'%s'" "$value"
+}
+
+write_hermes_model_config() {
+ local has_model_config=0
+ if [[ -n "$HERMES_SMOKE_MODEL_PROVIDER" || -n "$HERMES_SMOKE_MODEL_DEFAULT" || -n "$HERMES_SMOKE_MODEL_BASE_URL" ]]; then
+ has_model_config=1
+ fi
+ if [[ "$has_model_config" == "1" && ( -z "$HERMES_SMOKE_MODEL_PROVIDER" || -z "$HERMES_SMOKE_MODEL_DEFAULT" ) ]]; then
+ fail "HERMES_SMOKE_MODEL_PROVIDER and HERMES_SMOKE_MODEL_DEFAULT must be set together"
+ fi
+
+ local config_file="${HERMES_SMOKE_STATE_DIR}/hermes-home/config.yaml"
+ if [[ -e "$config_file" ]]; then
+ fail "Hermes model config already exists in fresh state: ${config_file}"
+ fi
+
+ {
+ if [[ "$has_model_config" == "1" ]]; then
+ echo "model:"
+ printf " default: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_DEFAULT")"
+ printf " provider: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_PROVIDER")"
+ if [[ -n "$HERMES_SMOKE_MODEL_BASE_URL" ]]; then
+ printf " base_url: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_BASE_URL")"
+ fi
+ echo "providers: {}"
+ fi
+ echo "command_allowlist:"
+ echo "- execute_code"
+ } > "$config_file"
+ chmod 644 "$config_file"
+ if [[ "$has_model_config" == "1" ]]; then
+ log "seeded Hermes model config provider=${HERMES_SMOKE_MODEL_PROVIDER} model=${HERMES_SMOKE_MODEL_DEFAULT}"
+ else
+ log "seeded Hermes smoke config"
+ fi
+}
+
+start_container() {
+ docker rm -f "$HERMES_CONTAINER_NAME" >/dev/null 2>&1 || true
+
+ local args=(
+ run -d
+ --name "$HERMES_CONTAINER_NAME"
+ -p "127.0.0.1:${HERMES_GATEWAY_PORT}:8642"
+ -e API_SERVER_ENABLED=true
+ -e API_SERVER_KEY="$HERMES_GATEWAY_API_KEY"
+ -e API_SERVER_HOST=0.0.0.0
+ -e API_SERVER_PORT=8642
+ -e PAPERCLIP_API_URL="$PAPERCLIP_API_URL_FOR_HERMES"
+ -e NO_COLOR=1
+ -v "${HERMES_SMOKE_STATE_DIR}/hermes-home:/home/hermes/.hermes"
+ -v "${HERMES_SMOKE_STATE_DIR}/workspace:/home/hermes/workspace"
+ )
+ local provider_key
+ local provider_keys=()
+ for provider_key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do
+ if [[ -n "${!provider_key-}" ]]; then
+ args+=(-e "${provider_key}=${!provider_key}")
+ provider_keys+=("$provider_key")
+ fi
+ done
+ if [[ ${#provider_keys[@]} -gt 0 ]]; then
+ log "passing Hermes inference provider env keys: ${provider_keys[*]}"
+ else
+ warn "no Hermes inference provider env keys set; direct run will fail unless Hermes state config already has a provider"
+ fi
+ if [[ -n "$HERMES_SMOKE_NETWORK" ]]; then
+ args+=(--network "$HERMES_SMOKE_NETWORK")
+ fi
+ if [[ "$HERMES_DOCKER_ADD_HOST" == "1" ]]; then
+ args+=(--add-host=host.docker.internal:host-gateway)
+ fi
+ args+=("$HERMES_IMAGE")
+
+ log "starting container ${HERMES_CONTAINER_NAME}"
+ docker "${args[@]}" >/dev/null
+}
+
+assert_fresh_container_state() {
+ log "asserting container does not see host Hermes state"
+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'test ! -e "$HERMES_HOME/host-sentinel.txt"'
+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'env | sort | grep -E "^(HOME|HERMES_HOME|XDG_|API_SERVER_|PAPERCLIP_API_URL)=" || true' > "${HERMES_SMOKE_DIAG_DIR}/container-env.txt"
+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'find "$HERMES_HOME" -maxdepth 2 -type f -print | sort' > "${HERMES_SMOKE_DIAG_DIR}/container-hermes-home-files-before.txt" || true
+ if docker exec "$HERMES_CONTAINER_NAME" sh -lc 'env | grep -q "^PAPERCLIP_API_KEY="'; then
+ fail "container unexpectedly has PAPERCLIP_API_KEY before join/key claim"
+ fi
+}
+
+probe_container_to_paperclip() {
+ log "probing container-to-Paperclip connectivity at ${PAPERCLIP_API_URL_FOR_HERMES}/api/health"
+ if ! docker exec "$HERMES_CONTAINER_NAME" curl -fsS --max-time 8 "${PAPERCLIP_API_URL_FOR_HERMES%/}/api/health" > "${HERMES_SMOKE_DIAG_DIR}/container-paperclip-health.json"; then
+ fail "Hermes container cannot reach Paperclip. Set PAPERCLIP_API_URL_FOR_HERMES to a URL reachable from inside Docker, or keep HERMES_DOCKER_ADD_HOST=1 for Linux host.docker.internal."
+ fi
+}
+
+probe_gateway_readiness() {
+ log "waiting for Hermes gateway health at ${HERMES_GATEWAY_PROBE_URL%/}/health"
+ if [[ "$HERMES_GATEWAY_PROBE_URL" != "$HERMES_GATEWAY_API_BASE_URL" ]]; then
+ log "Paperclip will store Hermes gateway URL ${HERMES_GATEWAY_API_BASE_URL}"
+ fi
+ wait_http_ready "${HERMES_GATEWAY_PROBE_URL%/}/health" "$GATEWAY_READY_TIMEOUT_SEC" || fail "Hermes gateway health did not become ready"
+
+ gateway_request "GET" "/health" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-health.json"
+ assert_status "200"
+
+ local wrong_code
+ wrong_code="$(curl -sS -o /dev/null -w "%{http_code}" -H "Authorization: Bearer wrong-smoke-key" "${HERMES_GATEWAY_PROBE_URL%/}/v1/capabilities" || true)"
+ if [[ "$wrong_code" == "200" ]]; then
+ fail "Hermes protected endpoint accepted a wrong API key"
+ fi
+}
+
+assert_capabilities() {
+ log "asserting /v1/capabilities"
+ gateway_request "GET" "/v1/capabilities" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-capabilities.json"
+ assert_status "200"
+ if ! jq -e 'type == "object"' <<<"$RESPONSE_BODY" >/dev/null; then
+ fail "capabilities response is not a JSON object"
+ fi
+}
+
+poll_gateway_run_terminal() {
+ local run_id="$1"
+ local timeout_sec="$2"
+ local label="$3"
+ local started now status
+ started="$(date +%s)"
+ while true; do
+ gateway_request "GET" "/v1/runs/${run_id}" "" "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-status.json"
+ if [[ "$RESPONSE_CODE" == "200" ]]; then
+ status="$(jq -r '.status // empty' <<<"$RESPONSE_BODY")"
+ case "$status" in
+ completed|failed|error|cancelled|canceled|stopped|interrupted)
+ echo "$status"
+ return 0
+ ;;
+ esac
+ fi
+ now="$(date +%s)"
+ if (( now - started >= timeout_sec )); then
+ echo "timeout"
+ return 0
+ fi
+ sleep 2
+ done
+}
+
+assert_direct_gateway_run() {
+ local marker="HERMES_DIRECT_OK_${RUN_SUFFIX}"
+ local payload
+ payload="$(jq -nc \
+ --arg marker "$marker" \
+ --arg session "paperclip-smoke-direct-${RUN_SUFFIX}" \
+ '{input: ("Reply with exactly " + $marker + " and no other text."), instructions: "You are running a Paperclip Hermes gateway smoke direct API assertion.", session_id: $session}')"
+
+ log "asserting POST /v1/runs and SSE events"
+ gateway_request "POST" "/v1/runs" "$payload" "${HERMES_SMOKE_DIAG_DIR}/direct-run-create.json"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" ]]; then
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+ fail "expected HTTP 200 or 202, got HTTP ${RESPONSE_CODE}"
+ fi
+ DIRECT_RUN_ID="$(jq -r '.run_id // .runId // .id // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$DIRECT_RUN_ID" ]] || fail "direct run creation did not return run id"
+
+ local events_file="${HERMES_SMOKE_DIAG_DIR}/direct-run-${DIRECT_RUN_ID}-events.sse"
+ curl -sS --max-time "$HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC" -N \
+ -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" \
+ "${HERMES_GATEWAY_PROBE_URL%/}/v1/runs/${DIRECT_RUN_ID}/events" \
+ > "${events_file}.raw" || true
+ redact_text "$(cat "${events_file}.raw")" > "$events_file"
+ rm -f "${events_file}.raw"
+ local events_seen=0
+ if grep -Eq '(^event:|^data:)' "$events_file"; then
+ events_seen=1
+ else
+ warn "SSE stream produced no event/data frames within ${HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC}s; polling direct run status"
+ fi
+
+ local status
+ status="$(poll_gateway_run_terminal "$DIRECT_RUN_ID" "$HERMES_DIRECT_RUN_TIMEOUT_SEC" "direct-run")"
+ log "direct Hermes run ${DIRECT_RUN_ID} status=${status}"
+ [[ "$status" == "completed" ]] || fail "direct Hermes run did not complete successfully (status=${status})"
+ if [[ "$events_seen" != "1" ]]; then
+ warn "direct Hermes run completed, but the live SSE probe was quiet"
+ fi
+}
+
+assert_stop_behavior_if_deterministic() {
+ [[ "$HERMES_STOP_ASSERT" != "0" ]] || {
+ log "HERMES_STOP_ASSERT=0; skipping /stop assertion"
+ return
+ }
+
+ local payload
+ payload="$(jq -nc \
+ --arg session "paperclip-smoke-stop-${RUN_SUFFIX}" \
+ '{input: "Wait until stopped. If you cannot wait, emit a short acknowledgement.", instructions: "This run exists only to verify the Hermes gateway stop endpoint.", session_id: $session}')"
+
+ log "probing /stop behavior (mode=${HERMES_STOP_ASSERT})"
+ gateway_request "POST" "/v1/runs" "$payload" "${HERMES_SMOKE_DIAG_DIR}/stop-run-create.json"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" ]]; then
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+ fail "expected HTTP 200 or 202, got HTTP ${RESPONSE_CODE}"
+ fi
+ STOP_RUN_ID="$(jq -r '.run_id // .runId // .id // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$STOP_RUN_ID" ]] || fail "stop test run creation did not return run id"
+
+ gateway_request "POST" "/v1/runs/${STOP_RUN_ID}/stop" "{}" "${HERMES_SMOKE_DIAG_DIR}/stop-run-stop-response.json"
+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" && "$RESPONSE_CODE" != "204" ]]; then
+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then
+ warn "/stop returned HTTP ${RESPONSE_CODE}; treating stop assertion as non-deterministic"
+ return
+ fi
+ fail "/stop returned HTTP ${RESPONSE_CODE}"
+ fi
+
+ local status
+ status="$(poll_gateway_run_terminal "$STOP_RUN_ID" 45 "stop-run")"
+ case "$status" in
+ cancelled|canceled|stopped|interrupted)
+ log "stop run ${STOP_RUN_ID} reached ${status}"
+ ;;
+ completed)
+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then
+ warn "stop run completed before cancellation could be observed; treating stop assertion as non-deterministic"
+ else
+ fail "stop run completed instead of stopping"
+ fi
+ ;;
+ *)
+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then
+ warn "stop run terminal status ${status}; treating stop assertion as non-deterministic"
+ else
+ fail "stop run did not reach a stopped/cancelled terminal status (status=${status})"
+ fi
+ ;;
+ esac
+}
+
+join_hermes_agent() {
+ log "running join-only smoke helper"
+ local join_log="${HERMES_SMOKE_DIAG_DIR}/hermes-gateway-join.log"
+ HERMES_AGENT_NAME="$HERMES_AGENT_NAME" \
+ HERMES_GATEWAY_API_BASE_URL="$HERMES_GATEWAY_API_BASE_URL" \
+ HERMES_GATEWAY_PROBE_URL="$HERMES_GATEWAY_PROBE_URL" \
+ HERMES_GATEWAY_API_KEY="$HERMES_GATEWAY_API_KEY" \
+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP="$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" \
+ HERMES_GATEWAY_SESSION_KEY_STRATEGY="$HERMES_GATEWAY_SESSION_KEY_STRATEGY" \
+ HERMES_GATEWAY_TIMEOUT_SEC="$HERMES_ADAPTER_TIMEOUT_SEC" \
+ PAPERCLIP_API_URL="$PAPERCLIP_API_URL" \
+ PAPERCLIP_API_URL_FOR_HERMES="$PAPERCLIP_API_URL_FOR_HERMES" \
+ PAPERCLIP_AUTH_HEADER="${PAPERCLIP_AUTH_HEADER:-}" \
+ PAPERCLIP_API_KEY="${PAPERCLIP_API_KEY:-}" \
+ PAPERCLIP_COOKIE="${PAPERCLIP_COOKIE:-}" \
+ COMPANY_ID="$COMPANY_ID" \
+ COMPANY_SELECTOR="$COMPANY_SELECTOR" \
+ HERMES_JOIN_OUTPUT_FILE="$JOIN_OUTPUT_FILE" \
+ bash scripts/smoke/hermes-gateway-join.sh > "${join_log}.raw" 2>&1 || {
+ redact_text "$(cat "${join_log}.raw")" > "$join_log"
+ rm -f "${join_log}.raw"
+ fail "join helper failed; see ${join_log}"
+ }
+ redact_text "$(cat "${join_log}.raw")" > "$join_log"
+ rm -f "${join_log}.raw"
+
+ [[ -f "$JOIN_OUTPUT_FILE" ]] || fail "join helper did not write ${JOIN_OUTPUT_FILE}"
+ AGENT_ID="$(jq -r '.agentId // empty' "$JOIN_OUTPUT_FILE")"
+ AGENT_API_KEY="$(jq -r '.agentApiKey // empty' "$JOIN_OUTPUT_FILE")"
+ INVITE_ID="$(jq -r '.inviteId // empty' "$JOIN_OUTPUT_FILE")"
+ JOIN_REQUEST_ID="$(jq -r '.joinRequestId // empty' "$JOIN_OUTPUT_FILE")"
+ KEY_ID="$(jq -r '.keyId // empty' "$JOIN_OUTPUT_FILE")"
+ [[ -n "$AGENT_ID" && -n "$AGENT_API_KEY" ]] || fail "join output missing agent id or API key"
+ log "joined Hermes gateway agent ${AGENT_ID} keyId=${KEY_ID} agentKeySha256=$(hash_prefix "$AGENT_API_KEY")"
+}
+
+install_claimed_key_in_container() {
+ log "placing newly claimed Paperclip key in container workspace"
+ local key_file="${HERMES_SMOKE_STATE_DIR}/workspace/paperclip-claimed-api-key.json"
+ jq -nc --arg token "$AGENT_API_KEY" '{token:$token,apiKey:$token}' > "$key_file"
+ # The host-created bind-mounted file must be readable by the non-root hermes
+ # user inside the container. The state dir is still per-run and deleted on
+ # success unless HERMES_SMOKE_KEEP=1.
+ chmod 644 "$key_file"
+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'test -f /home/hermes/workspace/paperclip-claimed-api-key.json && test ! -e "$HERMES_HOME/host-sentinel.txt"'
+}
+
+patch_agent_instructions_with_claimed_key() {
+ log "patching Hermes agent instructions with claimed Paperclip API context"
+ api_request "GET" "/agents/${AGENT_ID}"
+ assert_status "200"
+
+ local instructions patch_payload
+ instructions="For this smoke run only, call Paperclip at ${PAPERCLIP_API_URL_FOR_HERMES}. Read /home/hermes/workspace/paperclip-claimed-api-key.json and use its token as PAPERCLIP_API_KEY for Paperclip API requests. Do not reveal this key. When mutating Paperclip, include X-Paperclip-Run-Id with the current Paperclip run id when available."
+ patch_payload="$(jq -c --arg instructions "$instructions" '
+ {adapterConfig: ((.adapterConfig // {}) + {instructions: $instructions})}
+ ' <<<"$RESPONSE_BODY")"
+ api_request "PATCH" "/agents/${AGENT_ID}" "$patch_payload"
+ assert_status "200"
+}
+
+create_smoke_issue() {
+ local marker="HERMES_PAPERCLIP_E2E_OK_${RUN_SUFFIX}"
+ local title="[Hermes Gateway Smoke] ${RUN_SUFFIX}"
+ local description
+ description="Hermes gateway full Docker e2e smoke.\n\n1. Read this issue.\n2. Post a Paperclip issue comment containing exactly: ${marker}\n3. Mark this issue done.\n\nUse the Paperclip API URL and key provided in your run instructions. Do not reveal secrets."
+
+ local payload
+ payload="$(jq -nc \
+ --arg title "$title" \
+ --arg description "$description" \
+ --arg assignee "$AGENT_ID" \
+ '{title:$title,description:$description,status:"todo",priority:"high",assigneeAgentId:$assignee}')"
+ api_request "POST" "/companies/${COMPANY_ID}/issues" "$payload"
+ assert_status "201"
+ SMOKE_ISSUE_ID="$(jq -r '.id // empty' <<<"$RESPONSE_BODY")"
+ SMOKE_ISSUE_IDENTIFIER="$(jq -r '.identifier // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$SMOKE_ISSUE_ID" ]] || fail "smoke issue create missing id"
+ log "created smoke issue ${SMOKE_ISSUE_ID} (${SMOKE_ISSUE_IDENTIFIER})"
+ echo "$marker" > "${HERMES_SMOKE_DIAG_DIR}/paperclip-marker.txt"
+}
+
+trigger_wakeup() {
+ local payload
+ payload="$(jq -nc --arg issueId "$SMOKE_ISSUE_ID" '{source:"on_demand",triggerDetail:"manual",reason:"hermes_gateway_docker_e2e_smoke",payload:{issueId:$issueId,taskId:$issueId}}')"
+ api_request "POST" "/agents/${AGENT_ID}/wakeup" "$payload"
+ if [[ "$RESPONSE_CODE" != "202" ]]; then
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+ fail "wakeup failed (HTTP ${RESPONSE_CODE})"
+ fi
+ RUN_ID="$(jq -r '.id // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$RUN_ID" ]] || fail "wakeup response missing run id"
+ log "triggered Paperclip run ${RUN_ID}"
+}
+
+get_run_status() {
+ local run_id="$1"
+ api_request "GET" "/companies/${COMPANY_ID}/heartbeat-runs?agentId=${AGENT_ID}&limit=200"
+ if [[ "$RESPONSE_CODE" != "200" ]]; then
+ echo ""
+ return 0
+ fi
+ jq -r --arg runId "$run_id" '.[] | select(.id == $runId) | .status' <<<"$RESPONSE_BODY" | head -n1
+}
+
+wait_for_run_terminal() {
+ local run_id="$1"
+ local timeout_sec="$2"
+ local started now status
+ started="$(date +%s)"
+ while true; do
+ status="$(get_run_status "$run_id")"
+ if [[ "$status" == "succeeded" || "$status" == "failed" || "$status" == "timed_out" || "$status" == "cancelled" ]]; then
+ echo "$status"
+ return
+ fi
+ now="$(date +%s)"
+ if (( now - started >= timeout_sec )); then
+ echo "timeout"
+ return
+ fi
+ sleep 3
+ done
+}
+
+get_issue_status() {
+ local issue_id="$1"
+ api_request "GET" "/issues/${issue_id}"
+ if [[ "$RESPONSE_CODE" != "200" ]]; then
+ echo ""
+ return 0
+ fi
+ jq -r '.status // empty' <<<"$RESPONSE_BODY"
+}
+
+wait_for_issue_terminal() {
+ local issue_id="$1"
+ local timeout_sec="$2"
+ local started now status
+ started="$(date +%s)"
+ while true; do
+ status="$(get_issue_status "$issue_id")"
+ if [[ "$status" == "done" || "$status" == "blocked" || "$status" == "cancelled" ]]; then
+ echo "$status"
+ return
+ fi
+ now="$(date +%s)"
+ if (( now - started >= timeout_sec )); then
+ echo "timeout"
+ return
+ fi
+ sleep 3
+ done
+}
+
+issue_comments_contain() {
+ local issue_id="$1"
+ local marker="$2"
+ api_request "GET" "/issues/${issue_id}/comments"
+ if [[ "$RESPONSE_CODE" != "200" ]]; then
+ echo "false"
+ return
+ fi
+ jq -r --arg marker "$marker" '[.[] | (.body // "") | contains($marker)] | any' <<<"$RESPONSE_BODY"
+}
+
+assert_paperclip_wake_success() {
+ local marker
+ marker="$(cat "${HERMES_SMOKE_DIAG_DIR}/paperclip-marker.txt")"
+
+ trigger_wakeup
+ local run_status issue_status marker_found
+ run_status="$(wait_for_run_terminal "$RUN_ID" "$RUN_TIMEOUT_SEC")"
+ log "Paperclip run ${RUN_ID} status=${run_status}"
+ issue_status="$(wait_for_issue_terminal "$SMOKE_ISSUE_ID" "$CASE_TIMEOUT_SEC")"
+ marker_found="$(issue_comments_contain "$SMOKE_ISSUE_ID" "$marker")"
+ log "smoke issue status=${issue_status} marker_found=${marker_found}"
+
+ if [[ "$run_status" != "succeeded" || "$issue_status" != "done" || "$marker_found" != "true" ]]; then
+ capture_diagnostics
+ fi
+ if [[ "$STRICT_CASES" == "1" ]]; then
+ [[ "$run_status" == "succeeded" ]] || fail "Paperclip Hermes gateway run did not succeed"
+ [[ "$issue_status" == "done" ]] || fail "smoke issue did not reach done"
+ [[ "$marker_found" == "true" ]] || fail "smoke marker was not found in issue comments"
+ fi
+}
+
+scan_diagnostics_for_secret_leaks() {
+ log "scanning diagnostics for raw secret leaks"
+ local secrets=()
+ [[ -n "$HERMES_GATEWAY_API_KEY" ]] && secrets+=("$HERMES_GATEWAY_API_KEY")
+ [[ -n "$AGENT_API_KEY" ]] && secrets+=("$AGENT_API_KEY")
+ local key
+ for key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do
+ [[ -n "${!key-}" ]] && secrets+=("${!key}")
+ done
+ [[ ${#secrets[@]} -gt 0 ]] || return
+ local file
+ while IFS= read -r file; do
+ [[ "$file" == "$JOIN_OUTPUT_FILE" ]] && continue
+ local secret
+ for secret in "${secrets[@]}"; do
+ if grep -Fq "$secret" "$file"; then
+ fail "raw secret leaked in diagnostics file ${file}"
+ fi
+ done
+ done < <(find "$HERMES_SMOKE_DIAG_DIR" -type f -print)
+}
+
+main() {
+ log "starting Hermes gateway Docker E2E smoke"
+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"
+ log "diagnostics dir: ${HERMES_SMOKE_DIAG_DIR}"
+
+ require_cmd curl
+ require_cmd docker
+ require_cmd jq
+
+ if [[ -z "$HERMES_GATEWAY_API_KEY" ]]; then
+ HERMES_GATEWAY_API_KEY="$(generate_key)"
+ fi
+ log "Hermes API key sha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"
+ assert_gateway_api_base_url_allowed
+
+ api_request "GET" "/health"
+ assert_status "200"
+ log "Paperclip health deploymentMode=$(jq -r '.deploymentMode // "unknown"' <<<"$RESPONSE_BODY") exposure=$(jq -r '.deploymentExposure // "unknown"' <<<"$RESPONSE_BODY")"
+ require_board_auth
+ resolve_company_id
+
+ prepare_fresh_state
+ write_hermes_model_config
+ build_image
+ start_container
+ assert_fresh_container_state
+ probe_container_to_paperclip
+ probe_gateway_readiness
+ assert_capabilities
+ assert_direct_gateway_run
+ assert_stop_behavior_if_deterministic
+ join_hermes_agent
+ install_claimed_key_in_container
+ patch_agent_instructions_with_claimed_key
+ create_smoke_issue
+ assert_paperclip_wake_success
+ capture_diagnostics
+ scan_diagnostics_for_secret_leaks
+
+ log "success"
+ log "companyId=${COMPANY_ID}"
+ log "agentId=${AGENT_ID}"
+ log "inviteId=${INVITE_ID}"
+ log "joinRequestId=${JOIN_REQUEST_ID}"
+ log "issueId=${SMOKE_ISSUE_ID}"
+ log "issueIdentifier=${SMOKE_ISSUE_IDENTIFIER}"
+ log "runId=${RUN_ID}"
+ log "directHermesRunId=${DIRECT_RUN_ID}"
+ log "diagnostics=${HERMES_SMOKE_DIAG_DIR}"
+}
+
+main "$@"
diff --git a/scripts/smoke/hermes-gateway-join.sh b/scripts/smoke/hermes-gateway-join.sh
new file mode 100755
index 0000000000..b646d97043
--- /dev/null
+++ b/scripts/smoke/hermes-gateway-join.sh
@@ -0,0 +1,450 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() {
+ echo "[hermes-gateway-join] $*"
+}
+
+warn() {
+ echo "[hermes-gateway-join] WARN: $*" >&2
+}
+
+fail() {
+ echo "[hermes-gateway-join] ERROR: $*" >&2
+ exit 1
+}
+
+require_cmd() {
+ local cmd="$1"
+ command -v "$cmd" >/dev/null 2>&1 || fail "missing required command: ${cmd}"
+}
+
+require_cmd curl
+require_cmd jq
+
+PAPERCLIP_API_URL="${PAPERCLIP_API_URL:-http://localhost:3100}"
+API_BASE="${PAPERCLIP_API_URL%/}/api"
+COMPANY_ID="${COMPANY_ID:-${PAPERCLIP_COMPANY_ID:-}}"
+COMPANY_SELECTOR="${COMPANY_SELECTOR:-}"
+
+HERMES_AGENT_NAME="${HERMES_AGENT_NAME:-Hermes Gateway Smoke Agent}"
+HERMES_GATEWAY_API_BASE_URL="${HERMES_GATEWAY_API_BASE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT:-8642}}"
+HERMES_GATEWAY_PROBE_URL="${HERMES_GATEWAY_PROBE_URL:-$HERMES_GATEWAY_API_BASE_URL}"
+HERMES_GATEWAY_API_KEY="${HERMES_GATEWAY_API_KEY:-${API_SERVER_KEY:-}}"
+HERMES_GATEWAY_ALLOW_INSECURE_HTTP="${HERMES_GATEWAY_ALLOW_INSECURE_HTTP:-0}"
+HERMES_GATEWAY_SESSION_KEY_STRATEGY="${HERMES_GATEWAY_SESSION_KEY_STRATEGY:-issue}"
+HERMES_GATEWAY_TIMEOUT_SEC="${HERMES_GATEWAY_TIMEOUT_SEC:-180}"
+PAPERCLIP_API_URL_FOR_HERMES="${PAPERCLIP_API_URL_FOR_HERMES:-}"
+GATEWAY_PROBE_TIMEOUT_SEC="${GATEWAY_PROBE_TIMEOUT_SEC:-4}"
+HERMES_JOIN_OUTPUT_FILE="${HERMES_JOIN_OUTPUT_FILE:-}"
+
+print_usage() {
+ cat <<'EOF'
+Hermes gateway join smoke
+
+Creates a Hermes gateway agent from an agent-only Paperclip invite, approves the
+join request, claims the one-time Paperclip API key, and verifies the stored
+adapter config without printing raw secrets.
+
+Required:
+ PAPERCLIP_API_URL=http://127.0.0.1:3100
+ PAPERCLIP_AUTH_HEADER='Bearer <board-token>' # or PAPERCLIP_COOKIE
+ HERMES_GATEWAY_API_KEY=<API_SERVER_KEY>
+
+Common flags:
+ COMPANY_ID=<uuid> or COMPANY_SELECTOR=<prefix|name|uuid>
+ HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642
+ HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642
+ PAPERCLIP_API_URL_FOR_HERMES=http://host.docker.internal:3100
+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 # dev-only non-loopback HTTP
+ HERMES_GATEWAY_SESSION_KEY_STRATEGY=issue|agent|run|none
+ HERMES_JOIN_OUTPUT_FILE=/secure/path/join-output.json
+
+Notes:
+ HERMES_GATEWAY_API_BASE_URL is stored on the Paperclip adapter and must be
+ reachable by the Paperclip server. HERMES_GATEWAY_PROBE_URL is only used by
+ this operator shell to preflight /health, which is useful when Paperclip talks
+ to the gateway over a Docker network name but the operator probes localhost.
+
+ Raw API keys are redacted from logs. HERMES_JOIN_OUTPUT_FILE contains the
+ claimed Paperclip agent API key and is written chmod 600.
+
+See doc/HERMES_GATEWAY_SMOKE.md for Docker Desktop, Linux, same-network,
+LAN/private-network, and reverse-proxy/TLS examples.
+EOF
+}
+
+case "${1:-}" in
+ -h|--help)
+ print_usage
+ exit 0
+ ;;
+esac
+
+AUTH_HEADERS=()
+if [[ -n "${PAPERCLIP_AUTH_HEADER:-}" ]]; then
+ AUTH_HEADERS+=(-H "Authorization: ${PAPERCLIP_AUTH_HEADER}")
+elif [[ -n "${PAPERCLIP_API_KEY:-}" ]]; then
+ AUTH_HEADERS+=(-H "Authorization: Bearer ${PAPERCLIP_API_KEY}")
+fi
+if [[ -n "${PAPERCLIP_COOKIE:-}" ]]; then
+ AUTH_HEADERS+=(-H "Cookie: ${PAPERCLIP_COOKIE}")
+fi
+
+RESPONSE_CODE=""
+RESPONSE_BODY=""
+CLAIM_SECRET=""
+AGENT_API_KEY=""
+
+hash_prefix() {
+ local value="$1"
+ if command -v sha256sum >/dev/null 2>&1; then
+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'
+ elif command -v shasum >/dev/null 2>&1; then
+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'
+ else
+ printf "unavailable"
+ fi
+}
+
+redact_text() {
+ local text="$1"
+ local secret
+ for secret in "${HERMES_GATEWAY_API_KEY:-}" "${CLAIM_SECRET:-}" "${AGENT_API_KEY:-}" "${PAPERCLIP_AUTH_HEADER:-}" "${PAPERCLIP_COOKIE:-}" "${PAPERCLIP_API_KEY:-}"; do
+ if [[ -n "$secret" ]]; then
+ text="${text//$secret/[redacted len=${#secret}]}"
+ fi
+ done
+ printf "%s" "$text"
+}
+
+print_response_error() {
+ redact_text "$RESPONSE_BODY" >&2
+ echo >&2
+}
+
+api_request() {
+ local method="$1"
+ local path="$2"
+ local data="${3-}"
+ local tmp
+ tmp="$(mktemp)"
+
+ local url
+ if [[ "$path" == http://* || "$path" == https://* ]]; then
+ url="$path"
+ elif [[ "$path" == /api/* ]]; then
+ url="${PAPERCLIP_API_URL%/}${path}"
+ else
+ url="${API_BASE}${path}"
+ fi
+
+ if [[ -n "$data" ]]; then
+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" -H "Content-Type: application/json" "$url" --data "$data")"
+ else
+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" "$url")"
+ fi
+ RESPONSE_BODY="$(cat "$tmp")"
+ rm -f "$tmp"
+}
+
+assert_status() {
+ local expected="$1"
+ if [[ "$RESPONSE_CODE" != "$expected" ]]; then
+ print_response_error
+ fail "expected HTTP ${expected}, got HTTP ${RESPONSE_CODE}"
+ fi
+}
+
+assert_json_has_string() {
+ local jq_expr="$1"
+ local value
+ value="$(jq -r "$jq_expr // empty" <<<"$RESPONSE_BODY")"
+ if [[ -z "$value" ]]; then
+ print_response_error
+ fail "expected JSON string at ${jq_expr}"
+ fi
+ echo "$value"
+}
+
+fail_board_auth_required() {
+ local operation="$1"
+ print_response_error
+ cat >&2 <<EOF
+[hermes-gateway-join] ERROR: ${operation} requires board/operator auth.
+
+Provide one of:
+ PAPERCLIP_AUTH_HEADER="Bearer <board-token>"
+ PAPERCLIP_COOKIE="<board-session-cookie>"
+
+Current auth context appears insufficient (HTTP ${RESPONSE_CODE}).
+EOF
+ exit 1
+}
+
+is_remote_plain_http() {
+ local url="$1"
+ [[ "$url" == http://* ]] || return 1
+ ! is_loopback_http_host "$(url_host "$url")"
+}
+
+url_host() {
+ local url="$1"
+ local rest host_port host
+ rest="${url#http://}"
+ rest="${rest#https://}"
+ if [[ "$rest" == \[*\]* ]]; then
+ host="${rest#\[}"
+ host="${host%%\]*}"
+ else
+ host_port="${rest%%/*}"
+ host="${host_port%%:*}"
+ fi
+ printf "%s" "$host"
+}
+
+is_loopback_http_host() {
+ local host
+ host="$(printf "%s" "$1" | tr '[:upper:]' '[:lower:]')"
+ case "$host" in
+ localhost|0.0.0.0|::1|0:0:0:0:0:0:0:1) return 0 ;;
+ esac
+ [[ "$host" =~ ^127\.([0-9]{1,3}\.){2}[0-9]{1,3}$ ]]
+}
+
+strip_trailing_slash() {
+ local value="$1"
+ while [[ "$value" == */ && "$value" != "http://" && "$value" != "https://" ]]; do
+ value="${value%/}"
+ done
+ printf "%s" "$value"
+}
+
+resolve_company_id() {
+ if [[ -n "$COMPANY_ID" ]]; then
+ return
+ fi
+
+ log "resolving company id"
+ api_request "GET" "/companies"
+ if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then
+ fail_board_auth_required "Company resolution"
+ fi
+ assert_status "200"
+
+ if [[ -n "$COMPANY_SELECTOR" ]]; then
+ COMPANY_ID="$(jq -r --arg selector "$COMPANY_SELECTOR" '
+ map(select(
+ (.id == $selector)
+ or ((.issuePrefix // "") == $selector)
+ or ((.name // "") == $selector)
+ )) | .[0].id // empty
+ ' <<<"$RESPONSE_BODY")"
+ [[ -n "$COMPANY_ID" ]] || fail "no company matched COMPANY_SELECTOR=${COMPANY_SELECTOR}"
+ else
+ COMPANY_ID="$(jq -r '.[0].id // empty' <<<"$RESPONSE_BODY")"
+ [[ -n "$COMPANY_ID" ]] || fail "no companies found; create one before running smoke test"
+ fi
+}
+
+assert_onboarding_contains() {
+ local body="$1"
+ local needle="$2"
+ if ! grep -Fq "$needle" <<<"$body"; then
+ echo "$body" >&2
+ fail "onboarding response missing expected text: ${needle}"
+ fi
+}
+
+probe_hermes_gateway() {
+ [[ -n "$HERMES_GATEWAY_API_BASE_URL" ]] || fail "HERMES_GATEWAY_API_BASE_URL is required"
+ [[ -n "$HERMES_GATEWAY_PROBE_URL" ]] || fail "HERMES_GATEWAY_PROBE_URL is required"
+ [[ -n "$HERMES_GATEWAY_API_KEY" ]] || fail "HERMES_GATEWAY_API_KEY or API_SERVER_KEY is required before any Paperclip state is mutated"
+
+ if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL" && [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" != "1" ]]; then
+ fail "HERMES_GATEWAY_API_BASE_URL uses non-loopback http. Set HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 for local-only unsafe HTTP, or use HTTPS."
+ fi
+
+ local health_url="${HERMES_GATEWAY_PROBE_URL%/}/health"
+ log "probing Hermes gateway health at ${health_url} with apiKey sha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"
+ if [[ "$HERMES_GATEWAY_PROBE_URL" != "$HERMES_GATEWAY_API_BASE_URL" ]]; then
+ log "Paperclip will store Hermes gateway URL ${HERMES_GATEWAY_API_BASE_URL}"
+ fi
+ local code
+ code="$(curl -sS -o /dev/null -w "%{http_code}" --max-time "$GATEWAY_PROBE_TIMEOUT_SEC" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$health_url" || true)"
+ if [[ "$code" != "200" ]]; then
+ fail "Hermes gateway health probe failed before mutating Paperclip state: ${health_url} returned HTTP ${code}. Start Hermes with API_SERVER_ENABLED=true API_SERVER_KEY=<key> hermes gateway run --replace --accept-hooks, or set HERMES_GATEWAY_API_BASE_URL/HERMES_GATEWAY_API_KEY."
+ fi
+}
+
+log "checking Paperclip health"
+api_request "GET" "/health"
+assert_status "200"
+log "deployment mode=$(jq -r '.deploymentMode // "unknown"' <<<"$RESPONSE_BODY") exposure=$(jq -r '.deploymentExposure // "unknown"' <<<"$RESPONSE_BODY")"
+
+resolve_company_id
+probe_hermes_gateway
+
+log "creating agent-only invite for company ${COMPANY_ID}"
+INVITE_PAYLOAD="$(jq -nc '{allowedJoinTypes:"agent"}')"
+api_request "POST" "/companies/${COMPANY_ID}/invites" "$INVITE_PAYLOAD"
+if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then
+ fail_board_auth_required "Invite creation"
+fi
+assert_status "201"
+INVITE_TOKEN="$(assert_json_has_string '.token')"
+INVITE_ID="$(assert_json_has_string '.id')"
+log "created invite ${INVITE_ID}"
+
+log "verifying onboarding JSON and text endpoints"
+api_request "GET" "/invites/${INVITE_TOKEN}/onboarding"
+assert_status "200"
+ONBOARDING_JSON="$RESPONSE_BODY"
+ONBOARDING_TEXT_PATH="$(jq -r '.invite.onboardingTextPath // empty' <<<"$ONBOARDING_JSON")"
+[[ -n "$ONBOARDING_TEXT_PATH" ]] || fail "onboarding manifest missing invite.onboardingTextPath"
+assert_onboarding_contains "$ONBOARDING_JSON" "hermes_gateway"
+assert_onboarding_contains "$ONBOARDING_JSON" "API_SERVER_ENABLED=true"
+assert_onboarding_contains "$ONBOARDING_JSON" "API_SERVER_KEY"
+assert_onboarding_contains "$ONBOARDING_JSON" "agentDefaultsPayload"
+
+api_request "GET" "/invites/${INVITE_TOKEN}/onboarding.txt"
+assert_status "200"
+ONBOARDING_TEXT="$RESPONSE_BODY"
+assert_onboarding_contains "$ONBOARDING_TEXT" 'adapterType: "hermes_gateway"'
+assert_onboarding_contains "$ONBOARDING_TEXT" "API_SERVER_ENABLED=true"
+assert_onboarding_contains "$ONBOARDING_TEXT" "API_SERVER_KEY"
+assert_onboarding_contains "$ONBOARDING_TEXT" "hermes gateway run --replace --accept-hooks"
+assert_onboarding_contains "$ONBOARDING_TEXT" "agentDefaultsPayload.apiBaseUrl"
+
+JOIN_PAYLOAD="$(jq -nc \
+ --arg name "$HERMES_AGENT_NAME" \
+ --arg apiBaseUrl "$HERMES_GATEWAY_API_BASE_URL" \
+ --arg apiKey "$HERMES_GATEWAY_API_KEY" \
+ --arg paperclipApiUrl "$PAPERCLIP_API_URL_FOR_HERMES" \
+ --arg sessionKeyStrategy "$HERMES_GATEWAY_SESSION_KEY_STRATEGY" \
+ --argjson timeoutSec "$HERMES_GATEWAY_TIMEOUT_SEC" \
+ --argjson allowInsecure "$(if [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" == "1" ]]; then echo true; else echo false; fi)" \
+ '{
+ requestType: "agent",
+ agentName: $name,
+ adapterType: "hermes_gateway",
+ capabilities: "Hermes gateway Docker smoke harness",
+ agentDefaultsPayload: {
+ apiBaseUrl: $apiBaseUrl,
+ apiKey: $apiKey,
+ sessionKeyStrategy: $sessionKeyStrategy,
+ timeoutSec: $timeoutSec
+ }
+ }
+ | if $paperclipApiUrl != "" then .agentDefaultsPayload.paperclipApiUrl = $paperclipApiUrl else . end
+ | if $allowInsecure then .agentDefaultsPayload.dangerouslyAllowInsecureRemoteHttp = true else . end')"
+
+log "submitting Hermes gateway agent join request"
+api_request "POST" "/invites/${INVITE_TOKEN}/accept" "$JOIN_PAYLOAD"
+if [[ "$RESPONSE_CODE" != "202" ]]; then
+ print_response_error
+fi
+assert_status "202"
+JOIN_REQUEST_ID="$(assert_json_has_string '.id')"
+CLAIM_SECRET="$(assert_json_has_string '.claimSecret')"
+CLAIM_API_PATH="$(assert_json_has_string '.claimApiKeyPath')"
+DIAGNOSTICS_JSON="$(jq -c '.diagnostics // []' <<<"$RESPONSE_BODY")"
+if [[ "$DIAGNOSTICS_JSON" != "[]" ]]; then
+ log "join diagnostics: $(redact_text "$DIAGNOSTICS_JSON")"
+fi
+
+if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL"; then
+ if ! jq -e '[.diagnostics[]? | select(.code == "hermes_gateway_plain_http_remote_unsafe_allowed")] | length > 0' <<<"$RESPONSE_BODY" >/dev/null; then
+ fail "expected hermes_gateway_plain_http_remote_unsafe_allowed diagnostic for non-loopback HTTP join"
+ fi
+fi
+
+log "approving join request ${JOIN_REQUEST_ID}"
+api_request "POST" "/companies/${COMPANY_ID}/join-requests/${JOIN_REQUEST_ID}/approve" "{}"
+if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then
+ fail_board_auth_required "Join approval"
+fi
+assert_status "200"
+CREATED_AGENT_ID="$(assert_json_has_string '.createdAgentId')"
+
+log "verifying invalid claim secret is rejected"
+api_request "POST" "/join-requests/${JOIN_REQUEST_ID}/claim-api-key" '{"claimSecret":"invalid-smoke-secret-value"}'
+if [[ "$RESPONSE_CODE" == "201" ]]; then
+ fail "invalid claim secret unexpectedly succeeded"
+fi
+
+log "claiming API key with one-time claim secret"
+CLAIM_PAYLOAD="$(jq -nc --arg secret "$CLAIM_SECRET" '{claimSecret:$secret}')"
+api_request "POST" "$CLAIM_API_PATH" "$CLAIM_PAYLOAD"
+assert_status "201"
+AGENT_API_KEY="$(assert_json_has_string '.token')"
+KEY_ID="$(assert_json_has_string '.keyId')"
+
+log "verifying replay claim is rejected"
+api_request "POST" "$CLAIM_API_PATH" "$CLAIM_PAYLOAD"
+if [[ "$RESPONSE_CODE" == "201" ]]; then
+ fail "claim secret replay unexpectedly succeeded"
+fi
+
+log "verifying stored Hermes gateway agent config"
+api_request "GET" "/agents/${CREATED_AGENT_ID}"
+assert_status "200"
+
+AGENT_ADAPTER_TYPE="$(jq -r '.adapterType // empty' <<<"$RESPONSE_BODY")"
+[[ "$AGENT_ADAPTER_TYPE" == "hermes_gateway" ]] || fail "expected adapterType=hermes_gateway, got ${AGENT_ADAPTER_TYPE}"
+
+STORED_API_BASE_URL="$(jq -r '.adapterConfig.apiBaseUrl // empty' <<<"$RESPONSE_BODY")"
+[[ -n "$STORED_API_BASE_URL" ]] || fail "stored adapterConfig.apiBaseUrl is missing"
+if [[ "$(strip_trailing_slash "$STORED_API_BASE_URL")" != "$(strip_trailing_slash "$HERMES_GATEWAY_API_BASE_URL")" ]]; then
+ fail "stored apiBaseUrl mismatch: expected $(strip_trailing_slash "$HERMES_GATEWAY_API_BASE_URL"), got $(strip_trailing_slash "$STORED_API_BASE_URL")"
+fi
+
+if jq -e --arg raw "$HERMES_GATEWAY_API_KEY" '.adapterConfig.apiKey == $raw' <<<"$RESPONSE_BODY" >/dev/null; then
+ fail "stored adapterConfig.apiKey leaked the raw Hermes API key"
+fi
+if ! jq -e '(.adapterConfig.apiKey.type // "") == "secret_ref"' <<<"$RESPONSE_BODY" >/dev/null; then
+ warn "stored adapterConfig.apiKey is not a visible secret_ref; response shape may redact it entirely"
+fi
+
+STORED_SESSION_STRATEGY="$(jq -r '.adapterConfig.sessionKeyStrategy // empty' <<<"$RESPONSE_BODY")"
+[[ "$STORED_SESSION_STRATEGY" == "$HERMES_GATEWAY_SESSION_KEY_STRATEGY" ]] || fail "stored sessionKeyStrategy mismatch: expected ${HERMES_GATEWAY_SESSION_KEY_STRATEGY}, got ${STORED_SESSION_STRATEGY:-<empty>}"
+
+if [[ -n "$PAPERCLIP_API_URL_FOR_HERMES" ]]; then
+ STORED_PAPERCLIP_API_URL="$(jq -r '.adapterConfig.paperclipApiUrl // empty' <<<"$RESPONSE_BODY")"
+ [[ "$STORED_PAPERCLIP_API_URL" == "$PAPERCLIP_API_URL_FOR_HERMES" || "$(strip_trailing_slash "$STORED_PAPERCLIP_API_URL")" == "$(strip_trailing_slash "$PAPERCLIP_API_URL_FOR_HERMES")" ]] \
+ || fail "stored paperclipApiUrl mismatch"
+fi
+
+log "success"
+log "companyId=${COMPANY_ID}"
+log "inviteId=${INVITE_ID}"
+log "joinRequestId=${JOIN_REQUEST_ID}"
+log "agentId=${CREATED_AGENT_ID}"
+log "keyId=${KEY_ID}"
+log "hermesGatewayApiKeySha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"
+log "agentApiKeySha256=$(hash_prefix "$AGENT_API_KEY") len=${#AGENT_API_KEY}"
+
+if [[ -n "$HERMES_JOIN_OUTPUT_FILE" ]]; then
+ mkdir -p "$(dirname "$HERMES_JOIN_OUTPUT_FILE")"
+ jq -nc \
+ --arg companyId "$COMPANY_ID" \
+ --arg inviteId "$INVITE_ID" \
+ --arg joinRequestId "$JOIN_REQUEST_ID" \
+ --arg agentId "$CREATED_AGENT_ID" \
+ --arg keyId "$KEY_ID" \
+ --arg agentApiKey "$AGENT_API_KEY" \
+ --arg hermesGatewayApiKeySha256 "$(hash_prefix "$HERMES_GATEWAY_API_KEY")" \
+ --arg agentApiKeySha256 "$(hash_prefix "$AGENT_API_KEY")" \
+ '{
+ companyId: $companyId,
+ inviteId: $inviteId,
+ joinRequestId: $joinRequestId,
+ agentId: $agentId,
+ keyId: $keyId,
+ agentApiKey: $agentApiKey,
+ hermesGatewayApiKeySha256: $hermesGatewayApiKeySha256,
+ agentApiKeySha256: $agentApiKeySha256
+ }' > "$HERMES_JOIN_OUTPUT_FILE"
+ chmod 600 "$HERMES_JOIN_OUTPUT_FILE"
+ log "wrote join metadata to ${HERMES_JOIN_OUTPUT_FILE} (contains secret material; chmod 600)"
+fi
diff --git a/scripts/smoke/hermes-gateway-smoke.test.mjs b/scripts/smoke/hermes-gateway-smoke.test.mjs
new file mode 100644
index 0000000000..49efa5d682
--- /dev/null
+++ b/scripts/smoke/hermes-gateway-smoke.test.mjs
@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const joinScript = path.join(repoRoot, "scripts", "smoke", "hermes-gateway-join.sh");
+const e2eScript = path.join(repoRoot, "scripts", "smoke", "hermes-gateway-e2e.sh");
+const entrypointScript = path.join(repoRoot, "docker", "hermes-gateway-smoke", "entrypoint.sh");
+
+function run(command, args, options = {}) {
+ return spawnSync(command, args, {
+ cwd: repoRoot,
+ encoding: "utf8",
+ ...options,
+ });
+}
+
+function assertSuccess(result, label) {
+ assert.equal(
+ result.status,
+ 0,
+ `${label} failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+ );
+}
+
+function extractFunction(scriptText, name) {
+ const lines = scriptText.split("\n");
+ const start = lines.findIndex((line) => line.trim() === `${name}() {`);
+ assert.notEqual(start, -1, `missing function ${name}`);
+
+ const collected = [];
+ for (let index = start; index < lines.length; index += 1) {
+ collected.push(lines[index]);
+ if (index > start && lines[index].trim() === "}") {
+ return collected.join("\n");
+ }
+ }
+ assert.fail(`unterminated function ${name}`);
+}
+
+function runBashFunctions(scriptPath, functionNames, body) {
+ const scriptText = fs.readFileSync(scriptPath, "utf8");
+ const functions = functionNames.map((name) => extractFunction(scriptText, name)).join("\n\n");
+ return run("bash", ["-c", `set -euo pipefail\n${functions}\n${body}`]);
+}
+
+test("Hermes gateway smoke shell scripts pass bash syntax validation", () => {
+ const result = run("bash", ["-n", joinScript, e2eScript, entrypointScript]);
+ assertSuccess(result, "bash -n");
+});
+
+test("Hermes gateway smoke help documents operator safety flags", () => {
+ for (const script of [joinScript, e2eScript]) {
+ const result = run("bash", [script, "--help"]);
+ assertSuccess(result, `${path.basename(script)} --help`);
+ assert.match(result.stdout, /HERMES_GATEWAY_API_BASE_URL/);
+ assert.match(result.stdout, /HERMES_GATEWAY_PROBE_URL/);
+ assert.match(result.stdout, /HERMES_GATEWAY_ALLOW_INSECURE_HTTP/);
+ assert.match(result.stdout, /redact|redacted|Raw .*keys are redacted/i);
+ }
+
+ const e2eHelp = run("bash", [e2eScript, "--help"]).stdout;
+ assert.match(e2eHelp, /HERMES_SMOKE_KEEP/);
+ assert.match(e2eHelp, /HERMES_SMOKE_NETWORK/);
+ assert.match(e2eHelp, /HERMES_SMOKE_MODEL_DEFAULT/);
+ assert.match(e2eHelp, /Docker/);
+});
+
+test("E2E helper can seed a minimal Hermes model config without secrets", () => {
+ const result = runBashFunctions(
+ e2eScript,
+ ["log", "fail", "yaml_single_quote", "write_hermes_model_config"],
+ `
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+HERMES_SMOKE_STATE_DIR="$tmp"
+HERMES_SMOKE_MODEL_PROVIDER="openrouter"
+HERMES_SMOKE_MODEL_DEFAULT="z-ai/glm-5.2"
+HERMES_SMOKE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
+mkdir -p "$HERMES_SMOKE_STATE_DIR/hermes-home"
+write_hermes_model_config
+config="$HERMES_SMOKE_STATE_DIR/hermes-home/config.yaml"
+grep -Fq "default: 'z-ai/glm-5.2'" "$config"
+grep -Fq "provider: 'openrouter'" "$config"
+grep -Fq "base_url: 'https://openrouter.ai/api/v1'" "$config"
+grep -Fq "command_allowlist:" "$config"
+grep -Fq -- "- execute_code" "$config"
+! grep -Eiq "api[_-]?key|token|secret" "$config"
+`,
+ );
+ assertSuccess(result, "write_hermes_model_config");
+});
+
+test("join helper redacts known secrets without exposing raw key material", () => {
+ const result = runBashFunctions(
+ joinScript,
+ ["redact_text"],
+ `
+HERMES_GATEWAY_API_KEY="gateway-secret"
+CLAIM_SECRET="claim-secret"
+AGENT_API_KEY="agent-secret"
+PAPERCLIP_API_KEY="paperclip-secret"
+PAPERCLIP_AUTH_HEADER="Bearer board-secret"
+PAPERCLIP_COOKIE="session=board-cookie"
+output="$(redact_text "gateway-secret claim-secret agent-secret paperclip-secret Bearer board-secret session=board-cookie")"
+[[ "$output" != *"gateway-secret"* ]]
+[[ "$output" != *"claim-secret"* ]]
+[[ "$output" != *"agent-secret"* ]]
+[[ "$output" != *"paperclip-secret"* ]]
+[[ "$output" != *"board-secret"* ]]
+[[ "$output" != *"board-cookie"* ]]
+[[ "$output" == *"[redacted len=14]"* ]]
+`,
+ );
+ assertSuccess(result, "redact_text");
+});
+
+test("URL helpers distinguish loopback HTTP from unsafe remote HTTP", () => {
+ for (const script of [joinScript, e2eScript]) {
+ const result = runBashFunctions(
+ script,
+ ["url_host", "is_loopback_http_host", "is_remote_plain_http"],
+ `
+is_remote_plain_http "http://192.168.1.20:8642"
+is_remote_plain_http "http://hermes-gateway.local:8642"
+is_remote_plain_http "http://127.example.com:8642"
+is_remote_plain_http "http://localhost.evil:8642"
+! is_remote_plain_http "https://192.168.1.20:8642"
+! is_remote_plain_http "http://127.0.0.1:8642"
+! is_remote_plain_http "http://127.44.55.66:8642"
+! is_remote_plain_http "http://localhost:8642"
+! is_remote_plain_http "http://[::1]:8642"
+[[ "$(url_host "http://[::1]:8642/health")" == "::1" ]]
+[[ "$(url_host "http://127.example.com:8642/health")" == "127.example.com" ]]
+`,
+ );
+ assertSuccess(result, `${path.basename(script)} URL helpers`);
+ }
+});
+
+test("join helper normalizes trailing slashes for URL comparisons", () => {
+ const result = runBashFunctions(
+ joinScript,
+ ["strip_trailing_slash"],
+ `
+[[ "$(strip_trailing_slash "http://127.0.0.1:8642///")" == "http://127.0.0.1:8642" ]]
+[[ "$(strip_trailing_slash "https://gateway.example.com/")" == "https://gateway.example.com" ]]
+[[ "$(strip_trailing_slash "https://gateway.example.com/path/")" == "https://gateway.example.com/path" ]]
+`,
+ );
+ assertSuccess(result, "strip_trailing_slash");
+});
diff --git a/server/package.json b/server/package.json
index 1c9d1cb276..a636d6b544 100644
--- a/server/package.json
+++ b/server/package.json
@@ -59,6 +59,7 @@
"@paperclipai/plugin-sdk": "workspace:*",
"@paperclipai/shared": "workspace:*",
"@paperclipai/skills-catalog": "workspace:*",
+ "@paperclipai/hermes-paperclip-adapter": "workspace:*",
"ajv": "^8.20.0",
"ajv-formats": "^3.0.1",
"better-auth": "1.6.20",
@@ -69,7 +70,6 @@
"drizzle-orm": "^0.45.2",
"embedded-postgres": "^18.1.0-beta.16",
"express": "^5.1.0",
- "hermes-paperclip-adapter": "^0.3.0",
"jsdom": "^28.1.0",
"multer": "^2.1.1",
"open": "^11.0.0",
diff --git a/server/src/__tests__/adapter-registry.test.ts b/server/src/__tests__/adapter-registry.test.ts
index 983011fe8e..23455f282e 100644
--- a/server/src/__tests__/adapter-registry.test.ts
+++ b/server/src/__tests__/adapter-registry.test.ts
@@ -2,28 +2,6 @@ import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
import { buildSandboxNpmInstallCommand } from "@paperclipai/adapter-utils";
import type { ServerAdapterModule } from "../adapters/index.js";
-const hermesExecuteMock = vi.hoisted(() =>
- vi.fn(async () => ({
- exitCode: 0,
- signal: null,
- timedOut: false,
- })),
-);
-
-vi.mock("hermes-paperclip-adapter/server", () => ({
- execute: hermesExecuteMock,
- testEnvironment: async () => ({
- adapterType: "hermes_local",
- status: "pass",
- checks: [],
- testedAt: new Date(0).toISOString(),
- }),
- sessionCodec: null,
- listSkills: async () => [],
- syncSkills: async () => ({ entries: [] }),
- detectModel: async () => null,
-}));
-
import {
detectAdapterModel,
findActiveServerAdapter,
@@ -59,17 +37,18 @@ const externalAdapter: ServerAdapterModule = {
describe("server adapter registry", () => {
beforeEach(() => {
unregisterServerAdapter("external_test");
+ unregisterServerAdapter("hermes_local");
+ unregisterServerAdapter("hermes_gateway");
unregisterServerAdapter("claude_local");
setOverridePaused("claude_local", false);
- setOverridePaused("hermes_local", true);
});
afterEach(() => {
unregisterServerAdapter("external_test");
+ unregisterServerAdapter("hermes_local");
+ unregisterServerAdapter("hermes_gateway");
unregisterServerAdapter("claude_local");
setOverridePaused("claude_local", false);
- setOverridePaused("hermes_local", false);
- hermesExecuteMock.mockClear();
});
it("registers external adapters and exposes them through lookup helpers", async () => {
@@ -151,6 +130,88 @@ describe("server adapter registry", () => {
]);
});
+ it("ships Hermes adapters as built-ins and still accepts external overrides", () => {
+ const builtInLocal = findServerAdapter("hermes_local");
+ const builtInGateway = findServerAdapter("hermes_gateway");
+
+ expect(builtInLocal).not.toBeNull();
+ expect(builtInLocal?.supportsLocalAgentJwt).toBe(true);
+ expect(builtInLocal?.supportsInstructionsBundle).toBe(true);
+ expect(builtInLocal?.requiresMaterializedRuntimeSkills).toBe(false);
+ expect(builtInLocal?.detectModel).toBeTypeOf("function");
+ expect(builtInLocal?.getConfigSchema).toBeTypeOf("function");
+
+ expect(builtInGateway).not.toBeNull();
+ expect(builtInGateway?.supportsLocalAgentJwt).toBe(false);
+ expect(builtInGateway?.supportsInstructionsBundle).toBe(false);
+ expect(builtInGateway?.requiresMaterializedRuntimeSkills).toBe(false);
+ expect(builtInGateway?.getConfigSchema).toBeTypeOf("function");
+
+ const hermesLocalExternalAdapter: ServerAdapterModule = {
+ type: "hermes_local",
+ execute: async () => ({ exitCode: 0, signal: null, timedOut: false }),
+ testEnvironment: async () => ({
+ adapterType: "hermes_local",
+ status: "pass",
+ checks: [],
+ testedAt: new Date(0).toISOString(),
+ }),
+ supportsLocalAgentJwt: true,
+ supportsInstructionsBundle: true,
+ instructionsPathKey: "instructionsFilePath",
+ requiresMaterializedRuntimeSkills: false,
+ listSkills: async () => ({
+ adapterType: "hermes_local",
+ supported: true,
+ mode: "ephemeral",
+ desiredSkills: [],
+ entries: [],
+ warnings: [],
+ }),
+ getConfigSchema: () => ({ fields: [{ key: "provider", label: "Provider", type: "text" }] }),
+ detectModel: async () => ({
+ model: "hermes-model",
+ provider: "openrouter",
+ source: "test",
+ }),
+ };
+
+ const hermesGatewayExternalAdapter: ServerAdapterModule = {
+ type: "hermes_gateway",
+ execute: async () => ({ exitCode: 0, signal: null, timedOut: false }),
+ testEnvironment: async () => ({
+ adapterType: "hermes_gateway",
+ status: "pass",
+ checks: [],
+ testedAt: new Date(0).toISOString(),
+ }),
+ supportsLocalAgentJwt: false,
+ supportsInstructionsBundle: false,
+ requiresMaterializedRuntimeSkills: false,
+ getConfigSchema: () => ({
+ fields: [{ key: "apiBaseUrl", label: "API URL", type: "text" }],
+ }),
+ };
+
+ registerServerAdapter(hermesLocalExternalAdapter);
+
+ expect(requireServerAdapter("hermes_local")).toBe(hermesLocalExternalAdapter);
+ expect(findActiveServerAdapter("hermes_local")?.supportsLocalAgentJwt).toBe(true);
+
+ unregisterServerAdapter("hermes_local");
+
+ expect(requireServerAdapter("hermes_local")).toBe(builtInLocal);
+
+ registerServerAdapter(hermesGatewayExternalAdapter);
+
+ expect(requireServerAdapter("hermes_gateway")).toBe(hermesGatewayExternalAdapter);
+ expect(findActiveServerAdapter("hermes_gateway")?.supportsLocalAgentJwt).toBe(false);
+
+ unregisterServerAdapter("hermes_gateway");
+
+ expect(requireServerAdapter("hermes_gateway")).toBe(builtInGateway);
+ });
+
it("exposes capability flags from registered adapters", () => {
const adapterWithCaps: ServerAdapterModule = {
type: "external_test",
@@ -308,279 +369,6 @@ describe("server adapter registry", () => {
expect(await detectAdapterModel("claude_local")).toBeNull();
expect(detectModel).toHaveBeenCalledTimes(1);
});
-
- it("injects the local agent JWT and Paperclip API auth guidance into Hermes", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- env: {
- OPENAI_API_KEY: "llm-token",
- },
- promptTemplate: "Existing prompt",
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.agent.adapterConfig).toMatchObject({
- env: {
- OPENAI_API_KEY: "llm-token",
- PAPERCLIP_API_KEY: "agent-run-jwt",
- PAPERCLIP_RUN_ID: "run-123",
- },
- });
- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain(
- "Authorization: Bearer $PAPERCLIP_API_KEY",
- );
- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain(
- "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID",
- );
- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain("Existing prompt");
- });
-
- it("preserves Hermes command normalization while injecting auth", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- command: "agent-hermes",
- },
- },
- runtime: {},
- config: {
- command: "runtime-hermes",
- },
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.config.hermesCommand).toBe("runtime-hermes");
- expect(patchedCtx.agent.adapterConfig.hermesCommand).toBe("agent-hermes");
- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");
- });
-
- it("passes Hermes custom providers through extraArgs while injecting auth", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- provider: "custom:paperclip-openai",
- extraArgs: ["--source", "tool"],
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.agent.adapterConfig.provider).toBe("custom:paperclip-openai");
- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([
- "--source",
- "tool",
- "--provider",
- "custom:paperclip-openai",
- ]);
- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");
- });
-
- it("does not duplicate an explicit Hermes provider extraArg", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- provider: "custom:paperclip-openai",
- extraArgs: ["--provider=custom:paperclip-openai"],
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([
- "--provider=custom:paperclip-openai",
- ]);
- });
-
- it("does not duplicate spaced Hermes provider extraArgs", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- provider: "custom:paperclip-openai",
- extraArgs: ["--provider", "custom:paperclip-openai"],
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([
- "--provider",
- "custom:paperclip-openai",
- ]);
- });
-
- it("passes the original Hermes context through when authToken is absent", async () => {
- const adapter = requireServerAdapter("hermes_local");
- const ctx = {
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- env: {
- PAPERCLIP_API_KEY: "server-level-key",
- },
- promptTemplate: "Existing prompt",
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- };
-
- await adapter.execute(ctx);
-
- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);
- expect(hermesExecuteMock).toHaveBeenCalledWith(ctx);
- });
-
- it("preserves an explicit Hermes Paperclip API key and does not set promptTemplate when none was configured", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {
- env: {
- PAPERCLIP_API_KEY: "explicit-agent-key",
- PAPERCLIP_RUN_ID: "stale-run-id",
- },
- },
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("explicit-agent-key");
- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_RUN_ID).toBe("run-123");
- // No custom promptTemplate was set — Hermes must use its built-in default.
- // Setting promptTemplate here would replace the full default with just the auth guard text,
- // stripping assigned issue / workflow instructions.
- expect(patchedCtx.agent.adapterConfig.promptTemplate).toBeUndefined();
- });
-
- it("does not set promptTemplate when no custom template is configured, preserving Hermes default", async () => {
- const adapter = requireServerAdapter("hermes_local");
-
- await adapter.execute({
- runId: "run-123",
- agent: {
- id: "agent-123",
- companyId: "company-123",
- name: "Hermes Agent",
- role: "engineer",
- adapterType: "hermes_local",
- adapterConfig: {},
- },
- runtime: {},
- config: {},
- context: {},
- onLog: async () => {},
- onMeta: async () => {},
- onSpawn: async () => {},
- authToken: "agent-run-jwt",
- });
-
- const [patchedCtx] = hermesExecuteMock.mock.calls[0];
- // promptTemplate must remain unset so Hermes uses its built-in heartbeat/task prompt.
- expect(patchedCtx.agent.adapterConfig.promptTemplate).toBeUndefined();
- // Auth token is still injected.
- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");
- });
});
describe("resolveExternalAdapterRegistration", () => {
diff --git a/server/src/__tests__/adapter-routes.test.ts b/server/src/__tests__/adapter-routes.test.ts
index ccc0edcb5e..13e57a3539 100644
--- a/server/src/__tests__/adapter-routes.test.ts
+++ b/server/src/__tests__/adapter-routes.test.ts
@@ -115,12 +115,14 @@ describe("adapter routes", () => {
adapterRoutes = routes.adapterRoutes;
errorHandler = middleware.errorHandler;
setOverridePaused("claude_local", false);
+ unregisterServerAdapter("hermes_local");
unregisterServerAdapter("claude_local");
registerServerAdapter(overridingConfigSchemaAdapter);
});
afterEach(() => {
setOverridePaused("claude_local", false);
+ unregisterServerAdapter("hermes_local");
unregisterServerAdapter("claude_local");
});
@@ -185,17 +187,25 @@ describe("adapter routes", () => {
requiresMaterializedRuntimeSkills: true,
});
- // hermes_local currently supports skills + local JWT, but not the managed
- // instructions bundle flow because the bundled adapter does not consume
- // instructionsFilePath at runtime.
- const hermesAdapter = res.body.find((a: any) => a.type === "hermes_local");
- expect(hermesAdapter).toBeDefined();
- expect(hermesAdapter.capabilities).toMatchObject({
- supportsInstructionsBundle: false,
+ const hermesLocal = res.body.find((a: any) => a.type === "hermes_local");
+ expect(hermesLocal).toBeDefined();
+ expect(hermesLocal.source).toBe("builtin");
+ expect(hermesLocal.capabilities).toMatchObject({
+ supportsInstructionsBundle: true,
supportsSkills: true,
supportsLocalAgentJwt: true,
requiresMaterializedRuntimeSkills: false,
});
+
+ const hermesGateway = res.body.find((a: any) => a.type === "hermes_gateway");
+ expect(hermesGateway).toBeDefined();
+ expect(hermesGateway.source).toBe("builtin");
+ expect(hermesGateway.capabilities).toMatchObject({
+ supportsInstructionsBundle: false,
+ supportsSkills: false,
+ supportsLocalAgentJwt: false,
+ requiresMaterializedRuntimeSkills: false,
+ });
});
it("GET /api/adapters derives supportsSkills from listSkills/syncSkills presence", async () => {
@@ -277,6 +287,28 @@ describe("adapter routes", () => {
expect(keys).not.toContain("bootstrapPromptTemplate");
});
+ it("serves built-in Hermes config schemas", async () => {
+ const app = createApp();
+
+ const local = await request(app).get("/api/adapters/hermes_local/config-schema");
+ expect(local.status, JSON.stringify(local.body)).toBe(200);
+ expect(local.body.fields).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ key: "provider" }),
+ expect.objectContaining({ key: "timeoutSec" }),
+ ]),
+ );
+
+ const gateway = await request(app).get("/api/adapters/hermes_gateway/config-schema");
+ expect(gateway.status, JSON.stringify(gateway.body)).toBe(200);
+ expect(gateway.body.fields).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ key: "apiBaseUrl", required: true }),
+ expect.objectContaining({ key: "apiKey", required: true }),
+ ]),
+ );
+ });
+
it("GET /api/adapters includes ACPX model availability", async () => {
const app = createApp();
diff --git a/server/src/__tests__/agent-permissions-routes.test.ts b/server/src/__tests__/agent-permissions-routes.test.ts
index 70eec87767..9aeda84ac5 100644
--- a/server/src/__tests__/agent-permissions-routes.test.ts
+++ b/server/src/__tests__/agent-permissions-routes.test.ts
@@ -709,7 +709,7 @@ describe.sequential("agent permission routes", () => {
model: "gpt-5.3-codex-spark",
env: expect.any(Object),
}),
- { strictMode: false },
+ { strictMode: false, adapterType: "codex_local" },
);
expect(mockAgentService.update).toHaveBeenCalledWith(
agentId,
diff --git a/server/src/__tests__/agents-service-secret-bindings.test.ts b/server/src/__tests__/agents-service-secret-bindings.test.ts
index 634086cf5b..d27cc58b5c 100644
--- a/server/src/__tests__/agents-service-secret-bindings.test.ts
+++ b/server/src/__tests__/agents-service-secret-bindings.test.ts
@@ -115,6 +115,65 @@ describeEmbeddedPostgres("agent service secret binding sync", () => {
});
});
+ it("converts Hermes gateway apiKey strings into persisted secret refs", async () => {
+ const companyId = await seedCompany();
+ const literalApiKey = `hermes-key-${randomUUID()}`;
+
+ const created = await agentService(db).create(companyId, {
+ name: "Hermes Gateway",
+ role: "engineer",
+ status: "idle",
+ adapterType: "hermes_gateway",
+ adapterConfig: {
+ apiBaseUrl: "https://hermes.example",
+ apiKey: literalApiKey,
+ },
+ runtimeConfig: {},
+ spentMonthlyCents: 0,
+ lastHeartbeatAt: null,
+ });
+
+ const persistedRows = await db
+ .select()
+ .from(agents)
+ .where(eq(agents.id, created.id));
+ const persistedConfig = persistedRows[0]?.adapterConfig as Record<string, unknown>;
+ expect(JSON.stringify(persistedConfig)).not.toContain(literalApiKey);
+ expect(persistedConfig.apiKey).toMatchObject({
+ type: "secret_ref",
+ version: "latest",
+ });
+
+ const secretId = (persistedConfig.apiKey as { secretId: string }).secretId;
+ const bindings = await db
+ .select()
+ .from(companySecretBindings)
+ .where(and(
+ eq(companySecretBindings.companyId, companyId),
+ eq(companySecretBindings.targetType, "agent"),
+ eq(companySecretBindings.targetId, created.id),
+ ));
+ expect(bindings).toHaveLength(1);
+ expect(bindings[0]).toMatchObject({
+ secretId,
+ configPath: "apiKey",
+ versionSelector: "latest",
+ required: true,
+ });
+
+ const resolved = await secretService(db).resolveAdapterConfigForRuntime(
+ companyId,
+ persistedConfig,
+ {
+ consumerType: "agent",
+ consumerId: created.id,
+ },
+ { adapterType: "hermes_gateway" },
+ );
+ expect(resolved.config.apiKey).toBe(literalApiKey);
+ expect(JSON.stringify(persistedConfig)).not.toContain(literalApiKey);
+ });
+
it("replaces agent secret bindings when adapterConfig env changes", async () => {
const companyId = await seedCompany();
const secrets = secretService(db);
diff --git a/server/src/__tests__/authorization-service.test.ts b/server/src/__tests__/authorization-service.test.ts
index 2c1dd29427..aba122f285 100644
--- a/server/src/__tests__/authorization-service.test.ts
+++ b/server/src/__tests__/authorization-service.test.ts
@@ -73,6 +73,8 @@ async function createIssue(
projectId?: string | null;
parentId?: string | null;
assigneeAgentId?: string | null;
+ originKind?: string | null;
+ originId?: string | null;
} = {},
) {
return db
@@ -86,6 +88,8 @@ async function createIssue(
projectId: input.projectId ?? null,
parentId: input.parentId ?? null,
assigneeAgentId: input.assigneeAgentId ?? null,
+ originKind: input.originKind ?? "manual",
+ originId: input.originId ?? null,
})
.returning()
.then((rows) => rows[0]!);
@@ -1187,4 +1191,118 @@ describeEmbeddedPostgres("authorization service", () => {
grant: { permissionKey: "tasks:assign" },
});
});
+
+ it("scopes task bridge keys away from company-wide reads and unrelated issue writes", async () => {
+ const company = await createCompany(db, "TaskBridge");
+ const bridgeAgent = await createAgent(db, company.id);
+ const targetAgent = await createAgent(db, company.id);
+ const project = await createProject(db, company.id, "Bridge");
+ const parentIssue = await createIssue(db, company.id, { projectId: project.id });
+ const assignedIssue = await createIssue(db, company.id, { assigneeAgentId: bridgeAgent.id });
+ const keyId = randomUUID();
+ const bridgeCreatedIssue = await createIssue(db, company.id, {
+ originKind: "task_bridge",
+ originId: keyId,
+ });
+ const unrelatedIssue = await createIssue(db, company.id);
+ const actor = {
+ type: "agent" as const,
+ agentId: bridgeAgent.id,
+ companyId: company.id,
+ source: "agent_key" as const,
+ keyId,
+ keyScope: {
+ kind: "task_bridge" as const,
+ parentIssueId: parentIssue.id,
+ allowedAssigneeAgentIds: [targetAgent.id],
+ },
+ };
+ const authz = authorizationService(db);
+
+ await expect(authz.decide({
+ actor,
+ action: "company_scope:read",
+ resource: { type: "company", companyId: company.id },
+ })).resolves.toMatchObject({
+ allowed: false,
+ reason: "deny_scope",
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "tasks:assign",
+ resource: {
+ type: "issue",
+ companyId: company.id,
+ parentIssueId: parentIssue.id,
+ assigneeAgentId: targetAgent.id,
+ },
+ })).resolves.toMatchObject({
+ allowed: true,
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "tasks:assign",
+ resource: {
+ type: "issue",
+ companyId: company.id,
+ projectId: project.id,
+ assigneeUserId: randomUUID(),
+ },
+ })).resolves.toMatchObject({
+ allowed: false,
+ reason: "deny_scope",
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "issue:comment",
+ resource: {
+ type: "issue",
+ companyId: company.id,
+ issueId: assignedIssue.id,
+ },
+ })).resolves.toMatchObject({
+ allowed: true,
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "issue:mutate",
+ resource: {
+ type: "issue",
+ companyId: company.id,
+ issueId: bridgeCreatedIssue.id,
+ },
+ })).resolves.toMatchObject({
+ allowed: true,
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "issue:mutate",
+ resource: {
+ type: "issue",
+ companyId: company.id,
+ issueId: unrelatedIssue.id,
+ },
+ })).resolves.toMatchObject({
+ allowed: false,
+ reason: "deny_scope",
+ });
+
+ await expect(authz.decide({
+ actor,
+ action: "agent_config:read",
+ resource: {
+ type: "agent",
+ companyId: company.id,
+ agentId: bridgeAgent.id,
+ },
+ })).resolves.toMatchObject({
+ allowed: false,
+ reason: "deny_scope",
+ });
+ });
});
diff --git a/server/src/__tests__/aws-secrets-manager-provider.test.ts b/server/src/__tests__/aws-secrets-manager-provider.test.ts
index 90fec29575..aa006f5e2e 100644
--- a/server/src/__tests__/aws-secrets-manager-provider.test.ts
+++ b/server/src/__tests__/aws-secrets-manager-provider.test.ts
@@ -12,6 +12,11 @@ describe("awsSecretsManagerProvider", () => {
AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY,
AWS_SESSION_TOKEN: process.env.AWS_SESSION_TOKEN,
+ AWS_PROFILE: process.env.AWS_PROFILE,
+ AWS_DEFAULT_PROFILE: process.env.AWS_DEFAULT_PROFILE,
+ AWS_CONFIG_FILE: process.env.AWS_CONFIG_FILE,
+ AWS_SHARED_CREDENTIALS_FILE: process.env.AWS_SHARED_CREDENTIALS_FILE,
+ AWS_SDK_LOAD_CONFIG: process.env.AWS_SDK_LOAD_CONFIG,
};
afterEach(() => {
@@ -169,6 +174,11 @@ describe("awsSecretsManagerProvider", () => {
});
it("signs AWS Secrets Manager JSON requests with default runtime credentials", async () => {
+ delete process.env.AWS_PROFILE;
+ delete process.env.AWS_DEFAULT_PROFILE;
+ delete process.env.AWS_CONFIG_FILE;
+ delete process.env.AWS_SHARED_CREDENTIALS_FILE;
+ delete process.env.AWS_SDK_LOAD_CONFIG;
process.env.AWS_ACCESS_KEY_ID = "AKIA_TEST_ACCESS";
process.env.AWS_SECRET_ACCESS_KEY = "test-secret-key";
process.env.AWS_SESSION_TOKEN = "test-session-token";
diff --git a/server/src/__tests__/company-portability.test.ts b/server/src/__tests__/company-portability.test.ts
index 8d58ea264f..f4283a0910 100644
--- a/server/src/__tests__/company-portability.test.ts
+++ b/server/src/__tests__/company-portability.test.ts
@@ -1537,7 +1537,7 @@ describe("company portability", () => {
},
},
}),
- { strictMode: false },
+ { strictMode: false, adapterType: "codex_local" },
);
expect(agentSvc.create).toHaveBeenCalledWith("company-1", expect.objectContaining({
adapterConfig: expect.objectContaining({
@@ -3490,7 +3490,7 @@ describe("company portability", () => {
expect(secretSvc.normalizeAdapterConfigForPersistence).toHaveBeenCalledWith(
"company-imported",
expect.anything(),
- { strictMode: false },
+ { strictMode: false, adapterType: "claude_local" },
);
expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({
adapterType: "claude_local",
@@ -3559,7 +3559,7 @@ describe("company portability", () => {
model: "gpt-5.4",
extraArgs: ["--skip-git-repo-check"],
}),
- { strictMode: false },
+ { strictMode: false, adapterType: "codex_local" },
);
expect(agentSvc.update).toHaveBeenCalledWith("agent-1", expect.objectContaining({
adapterType: "codex_local",
diff --git a/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts b/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
index fcde58f3e9..0b99064dc1 100644
--- a/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
+++ b/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
@@ -54,6 +54,11 @@ vi.mock("../adapters/index.js", () => ({
execute: adapterExecute,
supportsLocalAgentJwt: false,
}),
+ findActiveServerAdapter: () => ({
+ type: "codex_local",
+ execute: adapterExecute,
+ supportsLocalAgentJwt: false,
+ }),
listAdapterModelProfiles: async () => [],
runningProcesses: new Map(),
}));
diff --git a/server/src/__tests__/heartbeat-plugin-environment.test.ts b/server/src/__tests__/heartbeat-plugin-environment.test.ts
index deda0e9d61..ee7155bb78 100644
--- a/server/src/__tests__/heartbeat-plugin-environment.test.ts
+++ b/server/src/__tests__/heartbeat-plugin-environment.test.ts
@@ -38,6 +38,11 @@ vi.mock("../adapters/index.js", () => ({
execute: adapterExecute,
supportsLocalAgentJwt: false,
}),
+ findActiveServerAdapter: () => ({
+ type: "codex_local",
+ execute: adapterExecute,
+ supportsLocalAgentJwt: false,
+ }),
listAdapterModelProfiles: async () => [],
runningProcesses: new Map(),
}));
diff --git a/server/src/__tests__/invite-accept-gateway-defaults.test.ts b/server/src/__tests__/invite-accept-gateway-defaults.test.ts
index 3ff239f628..cec0f913b6 100644
--- a/server/src/__tests__/invite-accept-gateway-defaults.test.ts
+++ b/server/src/__tests__/invite-accept-gateway-defaults.test.ts
@@ -1,8 +1,36 @@
-import { describe, expect, it } from "vitest";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import {
+ companies,
+ companySecretProviderConfigs,
+ companySecretVersions,
+ companySecrets,
+ createDb,
+ invites,
+ joinRequests,
+} from "@paperclipai/db";
import {
buildJoinDefaultsPayloadForAccept,
normalizeAgentDefaultsForJoin,
+ prepareAgentDefaultsPayloadForJoinPersistence,
} from "../routes/access.js";
+import {
+ getEmbeddedPostgresTestSupport,
+ startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+ console.warn(
+ `Skipping embedded Postgres invite accept gateway defaults tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+ );
+}
describe("buildJoinDefaultsPayloadForAccept (openclaw_gateway)", () => {
it("leaves non-gateway payloads unchanged", () => {
@@ -117,3 +145,162 @@ describe("normalizeAgentDefaultsForJoin (openclaw_gateway)", () => {
expect(normalized.normalized?.devicePrivateKeyPem).toBeUndefined();
});
});
+
+describe("normalizeAgentDefaultsForJoin (hermes_gateway)", () => {
+ it("rejects remote plain HTTP by default", () => {
+ const normalized = normalizeAgentDefaultsForJoin({
+ adapterType: "hermes_gateway",
+ defaultsPayload: {
+ apiBaseUrl: "http://192.168.1.25:8642",
+ apiKey: "hermes-key-1234567890",
+ },
+ deploymentMode: "authenticated",
+ deploymentExposure: "private",
+ bindHost: "127.0.0.1",
+ allowedHostnames: [],
+ });
+
+ expect(normalized.fatalErrors.join("\n")).toContain("remote plain HTTP");
+ expect(normalized.diagnostics).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "hermes_gateway_plain_http_remote_denied",
+ }),
+ ]),
+ );
+ });
+
+ it("allows remote plain HTTP only with the explicit unsafe flag", () => {
+ const normalized = normalizeAgentDefaultsForJoin({
+ adapterType: "hermes_gateway",
+ defaultsPayload: {
+ apiBaseUrl: "http://192.168.1.25:8642",
+ apiKey: "hermes-key-1234567890",
+ dangerouslyAllowInsecureRemoteHttp: true,
+ },
+ deploymentMode: "authenticated",
+ deploymentExposure: "private",
+ bindHost: "127.0.0.1",
+ allowedHostnames: [],
+ });
+
+ expect(normalized.fatalErrors).toEqual([]);
+ expect(normalized.normalized?.apiBaseUrl).toBe("http://192.168.1.25:8642/");
+ expect(normalized.diagnostics).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",
+ }),
+ ]),
+ );
+ });
+});
+
+describeEmbeddedPostgres("prepareAgentDefaultsPayloadForJoinPersistence (hermes_gateway)", () => {
+ let stopDb: (() => Promise<void>) | null = null;
+ let db!: ReturnType<typeof createDb>;
+ const previousKeyFile = process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+ const secretsTmpDir = path.join(os.tmpdir(), `paperclip-hermes-join-defaults-${randomUUID()}`);
+
+ beforeAll(async () => {
+ mkdirSync(secretsTmpDir, { recursive: true });
+ process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = path.join(secretsTmpDir, "master.key");
+ const started = await startEmbeddedPostgresTestDatabase("hermes-join-defaults");
+ stopDb = started.cleanup;
+ db = createDb(started.connectionString);
+ }, 20_000);
+
+ afterEach(async () => {
+ await db.delete(joinRequests);
+ await db.delete(invites);
+ await db.delete(companySecretVersions);
+ await db.delete(companySecrets);
+ await db.delete(companySecretProviderConfigs);
+ await db.delete(companies);
+ });
+
+ afterAll(async () => {
+ await stopDb?.();
+ if (previousKeyFile === undefined) {
+ delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+ } else {
+ process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = previousKeyFile;
+ }
+ rmSync(secretsTmpDir, { recursive: true, force: true });
+ });
+
+ it("stores a secret ref instead of the literal apiKey in join request defaults", async () => {
+ const companyId = randomUUID();
+ const inviteId = randomUUID();
+ const joinRequestId = randomUUID();
+ const literalApiKey = `hermes-key-${randomUUID()}`;
+
+ await db.insert(companies).values({
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ });
+ await db.insert(invites).values({
+ id: inviteId,
+ companyId,
+ inviteType: "company_join",
+ tokenHash: `invite-token-${randomUUID()}`,
+ allowedJoinTypes: "agent",
+ defaultsPayload: null,
+ expiresAt: new Date("2027-03-10T00:00:00.000Z"),
+ });
+
+ const joinDefaults = normalizeAgentDefaultsForJoin({
+ adapterType: "hermes_gateway",
+ defaultsPayload: {
+ apiBaseUrl: "https://hermes.example",
+ apiKey: literalApiKey,
+ paperclipApiUrl: "https://paperclip.example",
+ },
+ deploymentMode: "authenticated",
+ deploymentExposure: "private",
+ bindHost: "127.0.0.1",
+ allowedHostnames: [],
+ });
+ expect(joinDefaults.fatalErrors).toEqual([]);
+
+ const persistedDefaults = await prepareAgentDefaultsPayloadForJoinPersistence({
+ db,
+ companyId,
+ adapterType: "hermes_gateway",
+ normalized: joinDefaults.normalized,
+ });
+
+ await db.insert(joinRequests).values({
+ id: joinRequestId,
+ inviteId,
+ companyId,
+ requestType: "agent",
+ status: "pending_approval",
+ requestIp: "127.0.0.1",
+ agentName: "Hermes Gateway",
+ adapterType: "hermes_gateway",
+ capabilities: "Hermes gateway agent",
+ agentDefaultsPayload: persistedDefaults,
+ claimSecretHash: "claim-secret-hash",
+ claimSecretExpiresAt: new Date("2027-03-11T00:00:00.000Z"),
+ });
+
+ const persistedJoinRequest = await db
+ .select()
+ .from(joinRequests)
+ .where(eq(joinRequests.id, joinRequestId))
+ .then((rows) => rows[0]);
+ const storedPayload = persistedJoinRequest?.agentDefaultsPayload as Record<string, unknown>;
+ expect(JSON.stringify(storedPayload)).not.toContain(literalApiKey);
+ expect(storedPayload.apiKey).toMatchObject({
+ type: "secret_ref",
+ version: "latest",
+ });
+
+ const storedSecrets = await db.select().from(companySecrets);
+ expect(storedSecrets).toHaveLength(1);
+ expect((storedPayload.apiKey as { secretId: string }).secretId).toBe(storedSecrets[0]?.id);
+ });
+});
diff --git a/server/src/__tests__/invite-onboarding-text.test.ts b/server/src/__tests__/invite-onboarding-text.test.ts
index 7d8407b608..e08828a907 100644
--- a/server/src/__tests__/invite-onboarding-text.test.ts
+++ b/server/src/__tests__/invite-onboarding-text.test.ts
@@ -51,6 +51,21 @@ describe("buildInviteOnboardingTextDocument", () => {
expect(text).toContain('"adapterType": "openclaw_gateway"');
expect(text).toContain("headers.x-openclaw-token");
expect(text).toContain("Do NOT use /v1/responses or /hooks/*");
+ expect(text).toContain('adapterType: "hermes_gateway"');
+ expect(text).toContain('"adapterType": "hermes_gateway"');
+ expect(text).toContain("API_SERVER_ENABLED=true");
+ expect(text).toContain("API_SERVER_KEY");
+ expect(text).toContain("hermes gateway run --replace --accept-hooks");
+ expect(text).toContain("Default Hermes API server port: 8642");
+ expect(text).toContain("agentDefaultsPayload.apiBaseUrl");
+ expect(text).toContain("agentDefaultsPayload.paperclipApiUrl");
+ expect(text).toContain("hermes_local");
+ expect(text).toContain("Hermes-originated Paperclip API usage");
+ expect(text).toContain("http://127.0.0.1:8642");
+ expect(text).toContain("http://192.168.1.25:8642");
+ expect(text).toContain("tailnet-name.ts.net:8642");
+ expect(text).toContain("http://host.docker.internal:8642");
+ expect(text).toContain("https://hermes-gateway.example");
expect(text).toContain("set the first reachable candidate as agentDefaultsPayload.paperclipApiUrl");
expect(text).toContain("PAPERCLIP_API_KEY");
expect(text).toContain("Use your runtime's normal skill or instruction installation path.");
diff --git a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
index f2aabc93e4..e810f3085a 100644
--- a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
+++ b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
@@ -669,6 +669,22 @@ describe("agent issue mutation checkout ownership", () => {
mockStorageService.deleteObject.mockResolvedValue(undefined);
});
+ it("denies company-wide issue list routes for task bridge keys", async () => {
+ const app = await createApp(peerActor({
+ keyId: "99999999-9999-4999-8999-999999999999",
+ keyScope: {
+ kind: "task_bridge",
+ parentIssueId: issueId,
+ },
+ }));
+
+ const res = await request(app).get(`/api/companies/${companyId}/issues`);
+
+ expect(res.status).toBe(403);
+ expect(res.body.error).toContain("Task bridge keys cannot use company-wide issue list APIs");
+ expect(mockIssueService.list).not.toHaveBeenCalled();
+ });
+
it("uses the company-scope fast path on the issue list route", async () => {
mockAccessService.decide.mockImplementation(async (input: { action: string }) => {
if (input.action === "company_scope:read") {
diff --git a/server/src/__tests__/llms-routes.test.ts b/server/src/__tests__/llms-routes.test.ts
index fa530d9292..6078d98893 100644
--- a/server/src/__tests__/llms-routes.test.ts
+++ b/server/src/__tests__/llms-routes.test.ts
@@ -72,4 +72,39 @@ describe("llm routes", () => {
expect(res.text).toContain("Timer heartbeats are opt-in for new hires.");
expect(res.text).toContain("Leave runtimeConfig.heartbeat.enabled false");
});
+
+ it("serves static Hermes Gateway configuration docs before the plugin is installed", async () => {
+ const app = await createApp({
+ type: "board",
+ userId: "board-user",
+ companyIds: ["company-1"],
+ source: "local_implicit",
+ isInstanceAdmin: true,
+ });
+
+ const indexRes = await request(app).get("/api/llms/agent-configuration.txt");
+ expect(indexRes.status).toBe(200);
+ expect(indexRes.text).toContain(
+ "- hermes_gateway: /llms/agent-configuration/hermes_gateway.txt",
+ );
+
+ const res = await request(app).get("/api/llms/agent-configuration/hermes_gateway.txt");
+
+ expect(res.status).toBe(200);
+ expect(res.text).toContain("Adapter: hermes_gateway");
+ expect(res.text).toContain('adapterType": "hermes_gateway"');
+ expect(res.text).toContain("API_SERVER_ENABLED=true");
+ expect(res.text).toContain("API_SERVER_KEY");
+ expect(res.text).toContain("hermes gateway run --replace --accept-hooks");
+ expect(res.text).toContain("Default Hermes API server port: 8642");
+ expect(res.text).toContain("agentDefaultsPayload.apiBaseUrl");
+ expect(res.text).toContain("agentDefaultsPayload.paperclipApiUrl");
+ expect(res.text).toContain("hermes_local");
+ expect(res.text).toContain("Hermes-originated Paperclip API usage");
+ expect(res.text).toContain("http://127.0.0.1:8642");
+ expect(res.text).toContain("http://192.168.1.25:8642");
+ expect(res.text).toContain("tailnet-name.ts.net:8642");
+ expect(res.text).toContain("http://host.docker.internal:8642");
+ expect(res.text).toContain("https://hermes-gateway.example");
+ });
});
diff --git a/server/src/__tests__/secrets-service.test.ts b/server/src/__tests__/secrets-service.test.ts
index 3bc48eb908..eda8c2f953 100644
--- a/server/src/__tests__/secrets-service.test.ts
+++ b/server/src/__tests__/secrets-service.test.ts
@@ -998,6 +998,11 @@ describeEmbeddedPostgres("secretService", () => {
version: 1,
},
}));
+
+ const persisted = await svc.getByName(companyId, "Create Rollback");
+ expect(persisted).toBeNull();
+ const versions = await db.select().from(companySecretVersions);
+ expect(versions).toHaveLength(0);
});
it("keeps a local cleanup handle when create rollback cleanup fails", async () => {
diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.ts
index bb96eb9962..505162f7ed 100644
--- a/server/src/adapters/builtin-adapter-types.ts
+++ b/server/src/adapters/builtin-adapter-types.ts
@@ -9,10 +9,11 @@ export const BUILTIN_ADAPTER_TYPES = new Set([
"cursor",
"gemini_local",
"grok_local",
+ "hermes_gateway",
+ "hermes_local",
"openclaw_gateway",
"opencode_local",
"pi_local",
- "hermes_local",
"process",
"http",
]);
diff --git a/server/src/adapters/hermes-gateway-doc.ts b/server/src/adapters/hermes-gateway-doc.ts
new file mode 100644
index 0000000000..8fc2716806
--- /dev/null
+++ b/server/src/adapters/hermes-gateway-doc.ts
@@ -0,0 +1,56 @@
+export const hermesGatewayAgentConfigurationDoc = `# hermes_gateway agent configuration
+
+Adapter: hermes_gateway
+
+Use when:
+- Hermes is already running outside Paperclip and exposes its API server.
+- Paperclip should invoke Hermes through the gateway HTTP API instead of spawning Hermes locally.
+- The Hermes runtime may live on another host, a private overlay, in Docker, or behind a TLS reverse proxy.
+
+Don't use when:
+- Paperclip should start the Hermes CLI directly on the same host. Use the built-in hermes_local adapter for that flow.
+- Hermes is the process calling Paperclip APIs after claiming its key. That is Hermes-originated Paperclip API usage, not the gateway adapter transport.
+
+Runtime distinction:
+- hermes_local: Paperclip starts Hermes on the Paperclip host through the built-in local adapter.
+- hermes_gateway: Paperclip calls an already-running Hermes API server using agentDefaultsPayload.apiBaseUrl.
+- Hermes-originated Paperclip API usage: Hermes calls Paperclip with PAPERCLIP_API_URL and PAPERCLIP_BRIDGE_API_KEY. Create that Paperclip key with scope.kind = "task_bridge" and an approved parent/project boundary; do not expose a normal claimed agent key to Hermes-facing chat/webhook surfaces. Do not use agentDefaultsPayload.apiBaseUrl for Paperclip API calls.
+
+Hermes gateway process setup:
+- Set API_SERVER_ENABLED=true.
+- Set API_SERVER_KEY to a generated secret value. Do not paste a real key into tickets, docs, screenshots, or tests.
+- Start Hermes with: hermes gateway run --replace --accept-hooks
+- Default Hermes API server port: 8642.
+
+Join request minimum:
+{
+ "requestType": "agent",
+ "agentName": "My Hermes Gateway Agent",
+ "adapterType": "hermes_gateway",
+ "capabilities": "Hermes gateway agent",
+ "agentDefaultsPayload": {
+ "apiBaseUrl": "http://127.0.0.1:8642",
+ "apiKey": "<same-value-as-API_SERVER_KEY>",
+ "paperclipApiUrl": "http://localhost:3100"
+ }
+}
+
+Core fields:
+- agentDefaultsPayload.apiBaseUrl (string, required): Base URL for the Hermes API server as reachable from the Paperclip server.
+- agentDefaultsPayload.apiKey (string, required unless the adapter package documents another auth field): Hermes API server key matching API_SERVER_KEY.
+- agentDefaultsPayload.paperclipApiUrl (string, strongly recommended): Paperclip base URL as reachable from Hermes for invite, claim, skill bootstrap, and later Paperclip API calls.
+- agentDefaultsPayload.timeoutSec or timeoutMs (number, optional): Runtime request timeout when supported by the installed Hermes gateway adapter.
+
+Network examples:
+- Local loopback on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642"; agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".
+- LAN/private network: agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642"; agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100". Use private IPs or hostnames reachable from both machines.
+- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm paperclipai allowed-hostname <host> when authenticated/private mode requires it.
+- Docker: if Hermes runs on the host and Paperclip runs in Docker, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642". If Hermes runs in another container, use the Compose service DNS name such as "http://hermes:8642".
+- Reverse proxy/TLS: publish Hermes behind HTTPS and set agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example"; set agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example". Keep API_SERVER_KEY required at the origin or proxy.
+
+Security notes:
+- Treat API_SERVER_KEY and PAPERCLIP_BRIDGE_API_KEY as secrets.
+- Never use a normal claimed Paperclip agent API key for internet-facing Hermes-originated task bridge calls; task_bridge keys cannot use company-wide issue list/search/read surfaces and can only mutate bridge-created or assigned issues.
+- Prefer private network or TLS for non-loopback gateway access.
+- Use placeholders such as <same-value-as-API_SERVER_KEY> in docs and tests.
+`;
diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.ts
index 315f02dd74..c60d91948a 100644
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -92,6 +92,10 @@ import {
agentConfigurationDoc as grokAgentConfigurationDoc,
models as grokModels,
} from "@paperclipai/adapter-grok-local";
+import {
+ createHermesGatewayServerAdapter,
+ createHermesLocalServerAdapter,
+} from "@paperclipai/hermes-paperclip-adapter";
import {
execute as openCodeExecute,
listOpenCodeSkills,
@@ -127,18 +131,6 @@ import {
agentConfigurationDoc as piAgentConfigurationDoc,
modelProfiles as piModelProfiles,
} 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";
@@ -184,55 +176,6 @@ function buildCursorRuntimeCommandSpec(config: Record<string, unknown>): Adapter
};
}
-function normalizeHermesConfig<T extends { config?: unknown; agent?: unknown }>(ctx: T): T {
- const config =
- ctx && typeof ctx === "object" && "config" in ctx && ctx.config && typeof ctx.config === "object"
- ? (ctx.config as Record<string, unknown>)
- : null;
- const agent =
- ctx && typeof ctx === "object" && "agent" in ctx && ctx.agent && typeof ctx.agent === "object"
- ? (ctx.agent as Record<string, unknown>)
- : null;
- const agentAdapterConfig =
- agent?.adapterConfig && typeof agent.adapterConfig === "object"
- ? (agent.adapterConfig as Record<string, unknown>)
- : null;
-
- const configCommand =
- typeof config?.command === "string" && config.command.length > 0 ? config.command : undefined;
- const agentCommand =
- typeof agentAdapterConfig?.command === "string" && agentAdapterConfig.command.length > 0
- ? agentAdapterConfig.command
- : undefined;
-
- if (config && !config.hermesCommand && configCommand) {
- config.hermesCommand = configCommand;
- }
- if (agentAdapterConfig && !agentAdapterConfig.hermesCommand && agentCommand) {
- agentAdapterConfig.hermesCommand = agentCommand;
- }
-
- return ctx;
-}
-
-function passHermesCustomProviderThroughExtraArgs(config: Record<string, unknown>): Record<string, unknown> {
- const provider = typeof config.provider === "string" ? config.provider.trim() : "";
- if (!provider.startsWith("custom:")) return config;
-
- const existingExtraArgs = Array.isArray(config.extraArgs)
- ? config.extraArgs.filter((arg): arg is string => typeof arg === "string")
- : [];
- const alreadyHasProviderArg = existingExtraArgs.some((arg) =>
- arg === "--provider" || arg.startsWith("--provider=")
- );
- if (alreadyHasProviderArg) return config;
-
- return {
- ...config,
- extraArgs: [...existingExtraArgs, "--provider", provider],
- };
-}
-
function dedupeAdapterModels(models: AdapterModel[]): AdapterModel[] {
const seen = new Set<string>();
const result: AdapterModel[] = [];
@@ -403,6 +346,10 @@ const grokLocalAdapter: ServerAdapterModule = {
agentConfigurationDoc: grokAgentConfigurationDoc,
};
+const hermesGatewayAdapter = createHermesGatewayServerAdapter();
+
+const hermesLocalAdapter = createHermesLocalServerAdapter();
+
const openclawGatewayAdapter: ServerAdapterModule = {
type: "openclaw_gateway",
execute: openclawGatewayExecute,
@@ -453,77 +400,6 @@ const piLocalAdapter: ServerAdapterModule = {
agentConfigurationDoc: piAgentConfigurationDoc,
};
-// hermes-paperclip-adapter v0.2.0 predates the authToken field; cast is
-// intentional until hermes ships a matching AdapterExecutionContext type.
-const executeHermesLocal = hermesExecute as unknown as ServerAdapterModule["execute"];
-// hermes-paperclip-adapter v0.2.0 still depends on the published @paperclipai/adapter-utils
-// that ships the "paperclip_required" origin; casts bridge until hermes upgrades.
-const listHermesSkills = hermesListSkills as unknown as ServerAdapterModule["listSkills"];
-const syncHermesSkills = hermesSyncSkills as unknown as ServerAdapterModule["syncSkills"];
-
-const hermesLocalAdapter: ServerAdapterModule = {
- type: "hermes_local",
- execute: async (ctx) => {
- const normalizedCtx = normalizeHermesConfig(ctx);
- if (!normalizedCtx.authToken) return executeHermesLocal(normalizedCtx);
-
- const existingConfig = (normalizedCtx.agent.adapterConfig ?? {}) as Record<string, unknown>;
- const existingEnv =
- typeof existingConfig.env === "object" && existingConfig.env !== null && !Array.isArray(existingConfig.env)
- ? (existingConfig.env as Record<string, string>)
- : {};
- const explicitApiKey =
- typeof existingEnv.PAPERCLIP_API_KEY === "string" && existingEnv.PAPERCLIP_API_KEY.trim().length > 0;
- const promptTemplate =
- typeof existingConfig.promptTemplate === "string" && existingConfig.promptTemplate.trim().length > 0
- ? existingConfig.promptTemplate
- : "";
- const authGuardPrompt = [
- "Paperclip API safety rule:",
- "Use Authorization: Bearer $PAPERCLIP_API_KEY on every Paperclip API request.",
- "Use X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on every Paperclip API request that writes or mutates data, including comments and issue updates.",
- "Never use a board, browser, or local-board session for Paperclip API writes.",
- ].join("\n");
-
- const patchedConfig: Record<string, unknown> = {
- ...existingConfig,
- env: {
- ...existingEnv,
- ...(!explicitApiKey ? { PAPERCLIP_API_KEY: normalizedCtx.authToken } : {}),
- PAPERCLIP_RUN_ID: normalizedCtx.runId,
- },
- };
- const effectivePatchedConfig = passHermesCustomProviderThroughExtraArgs(patchedConfig);
-
- // Only inject the auth guard into promptTemplate when a custom template already exists.
- // When no custom template is set, Hermes uses its built-in default heartbeat/task prompt —
- // overwriting it with only the auth guard text would strip the assigned issue/workflow instructions.
- if (promptTemplate) {
- effectivePatchedConfig.promptTemplate = `${authGuardPrompt}\n\n${promptTemplate}`;
- }
-
- const patchedCtx = {
- ...normalizedCtx,
- agent: {
- ...normalizedCtx.agent,
- adapterConfig: effectivePatchedConfig,
- },
- };
-
- return executeHermesLocal(patchedCtx);
- },
- testEnvironment: (ctx) => hermesTestEnvironment(normalizeHermesConfig(ctx) as never),
- sessionCodec: hermesSessionCodec,
- listSkills: listHermesSkills,
- syncSkills: syncHermesSkills,
- models: hermesModels,
- supportsLocalAgentJwt: true,
- supportsInstructionsBundle: false,
- requiresMaterializedRuntimeSkills: false,
- agentConfigurationDoc: hermesAgentConfigurationDoc,
- detectModel: () => detectModelFromHermes(),
-};
-
const adaptersByType = new Map<string, ServerAdapterModule>();
// For builtin types that are overridden by an external adapter, we keep the
@@ -546,8 +422,9 @@ function registerBuiltInAdapters() {
cursorLocalAdapter,
geminiLocalAdapter,
grokLocalAdapter,
- openclawGatewayAdapter,
+ hermesGatewayAdapter,
hermesLocalAdapter,
+ openclawGatewayAdapter,
processAdapter,
httpAdapter,
]) {
diff --git a/server/src/middleware/auth.ts b/server/src/middleware/auth.ts
index c0cbf954dd..46650a0beb 100644
--- a/server/src/middleware/auth.ts
+++ b/server/src/middleware/auth.ts
@@ -4,7 +4,7 @@ import { and, eq, isNull } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { agentApiKeys, agents, authUsers, companies, companyMemberships, instanceUserRoles } from "@paperclipai/db";
import { verifyLocalAgentJwt } from "../agent-auth-jwt.js";
-import type { DeploymentMode } from "@paperclipai/shared";
+import { normalizeAgentApiKeyScope, type DeploymentMode } from "@paperclipai/shared";
import type { BetterAuthSessionResult } from "../auth/better-auth.js";
import { logger } from "./logger.js";
import { boardAuthService } from "../services/board-auth.js";
@@ -192,6 +192,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa
agentId: key.agentId,
companyId: key.companyId,
keyId: key.id,
+ keyScope: normalizeAgentApiKeyScope(key.scopeConfig),
runId: runIdHeader || undefined,
source: "agent_key",
};
diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts
index a4a2fea15b..0de06e57c7 100644
--- a/server/src/routes/access.ts
+++ b/server/src/routes/access.ts
@@ -83,6 +83,7 @@ import {
} from "../board-claim.js";
import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
import { getStorageService } from "../storage/index.js";
+import { secretService } from "../services/secrets.js";
function hashToken(token: string) {
return createHash("sha256").update(token).digest("hex");
@@ -294,8 +295,14 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
}
function isLoopbackHost(hostname: string): boolean {
- const value = hostname.trim().toLowerCase();
- return value === "localhost" || value === "127.0.0.1" || value === "::1";
+ const value = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+ return (
+ value === "localhost" ||
+ value === "::1" ||
+ value === "0:0:0:0:0:0:0:1" ||
+ value === "127.0.0.1" ||
+ /^127(?:\.\d{1,3}){3}$/.test(value)
+ );
}
function normalizeHostname(value: string | null | undefined): string | null {
@@ -474,8 +481,8 @@ function parseBooleanLike(value: unknown): boolean | null {
if (typeof value === "boolean") return value;
if (typeof value !== "string") return null;
const normalized = value.trim().toLowerCase();
- if (normalized === "true" || normalized === "1") return true;
- if (normalized === "false" || normalized === "0") return false;
+ if (["true", "1", "yes", "on"].includes(normalized)) return true;
+ if (["false", "0", "no", "off"].includes(normalized)) return false;
return null;
}
@@ -676,6 +683,91 @@ export function normalizeAgentDefaultsForJoin(input: {
}) {
const fatalErrors: string[] = [];
const diagnostics: JoinDiagnostic[] = [];
+ if (input.adapterType === "hermes_gateway") {
+ if (!isPlainObject(input.defaultsPayload)) {
+ diagnostics.push({
+ code: "hermes_gateway_defaults_missing",
+ level: "warn",
+ message: "No Hermes gateway config was provided in agentDefaultsPayload.",
+ hint: "Include agentDefaultsPayload.apiBaseUrl and agentDefaultsPayload.apiKey for Hermes gateway joins.",
+ });
+ fatalErrors.push("agentDefaultsPayload is required for adapterType=hermes_gateway");
+ return { normalized: null as Record<string, unknown> | null, diagnostics, fatalErrors };
+ }
+
+ const defaults = input.defaultsPayload as Record<string, unknown>;
+ const normalized = { ...defaults };
+ const rawApiBaseUrl = nonEmptyTrimmedString(defaults.apiBaseUrl ?? defaults.url);
+ if (!rawApiBaseUrl) {
+ diagnostics.push({
+ code: "hermes_gateway_api_base_url_missing",
+ level: "warn",
+ message: "Hermes gateway apiBaseUrl is missing.",
+ hint: "Set agentDefaultsPayload.apiBaseUrl to the Hermes API server URL.",
+ });
+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl is required");
+ } else {
+ try {
+ const apiBaseUrl = new URL(rawApiBaseUrl);
+ if (apiBaseUrl.protocol !== "http:" && apiBaseUrl.protocol !== "https:") {
+ diagnostics.push({
+ code: "hermes_gateway_api_base_url_protocol",
+ level: "warn",
+ message: `Hermes gateway apiBaseUrl must use http:// or https:// (got ${apiBaseUrl.protocol}).`,
+ });
+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl must use http:// or https:// for hermes_gateway");
+ } else if (
+ apiBaseUrl.protocol === "http:" &&
+ !isLoopbackHost(apiBaseUrl.hostname) &&
+ parseBooleanLike(defaults.dangerouslyAllowInsecureRemoteHttp) !== true
+ ) {
+ diagnostics.push({
+ code: "hermes_gateway_plain_http_remote_denied",
+ level: "warn",
+ message: "Remote plain HTTP Hermes gateway traffic is denied by default.",
+ hint: "Use https:// or set agentDefaultsPayload.dangerouslyAllowInsecureRemoteHttp=true only for unsafe local development.",
+ });
+ fatalErrors.push(
+ "agentDefaultsPayload.apiBaseUrl uses remote plain HTTP; use HTTPS or set dangerouslyAllowInsecureRemoteHttp=true for unsafe local development",
+ );
+ } else {
+ normalized.apiBaseUrl = apiBaseUrl.toString();
+ if (apiBaseUrl.protocol === "http:" && !isLoopbackHost(apiBaseUrl.hostname)) {
+ diagnostics.push({
+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",
+ level: "warn",
+ message: "Unsafe dev escape hatch enabled for non-loopback HTTP Hermes traffic.",
+ });
+ } else {
+ diagnostics.push({
+ code: "hermes_gateway_api_base_url_configured",
+ level: "info",
+ message: `Hermes gateway endpoint set to ${apiBaseUrl.toString()}`,
+ });
+ }
+ }
+ } catch {
+ diagnostics.push({
+ code: "hermes_gateway_api_base_url_invalid",
+ level: "warn",
+ message: `Invalid Hermes gateway apiBaseUrl: ${rawApiBaseUrl}`,
+ });
+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl is not a valid URL");
+ }
+ }
+
+ if (!nonEmptyTrimmedString(defaults.apiKey)) {
+ diagnostics.push({
+ code: "hermes_gateway_api_key_missing",
+ level: "warn",
+ message: "Hermes gateway API key is missing.",
+ hint: "Set agentDefaultsPayload.apiKey to the Hermes API_SERVER_KEY value.",
+ });
+ fatalErrors.push("agentDefaultsPayload.apiKey is required");
+ }
+
+ return { normalized, diagnostics, fatalErrors };
+ }
if (input.adapterType !== "openclaw_gateway") {
const normalized = isPlainObject(input.defaultsPayload)
? (input.defaultsPayload as Record<string, unknown>)
@@ -919,6 +1011,24 @@ export function normalizeAgentDefaultsForJoin(input: {
return { normalized, diagnostics, fatalErrors };
}
+export async function prepareAgentDefaultsPayloadForJoinPersistence(input: {
+ db: Db;
+ companyId: string;
+ adapterType: string | null;
+ normalized: Record<string, unknown> | null;
+ actor?: { userId?: string | null; agentId?: string | null };
+}): Promise<Record<string, unknown> | null> {
+ if (input.adapterType !== "hermes_gateway" || !input.normalized) {
+ return input.normalized;
+ }
+
+ return secretService(input.db).normalizeAdapterConfigForPersistence(
+ input.companyId,
+ input.normalized,
+ { adapterType: input.adapterType, actor: input.actor },
+ );
+}
+
function toInviteSummaryResponse(
req: Request,
token: string,
@@ -1585,17 +1695,17 @@ function buildInviteOnboardingManifest(
),
onboarding: {
instructions:
- "Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token.",
+ "Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token. Hermes Gateway agents must use adapterType='hermes_gateway', start Hermes with API_SERVER_ENABLED=true, API_SERVER_KEY, and `hermes gateway run --replace --accept-hooks`, then set agentDefaultsPayload.apiBaseUrl and agentDefaultsPayload.paperclipApiUrl.",
inviteMessage: extractInviteMessage(invite),
recommendedAdapterType: null,
requiredFields: {
requestType: "agent",
agentName: "Display name for this agent",
adapterType:
- "Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents.",
+ "Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents. Use 'hermes_gateway' only for Hermes Gateway agents.",
capabilities: "Optional capability summary",
agentDefaultsPayload:
- "Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Other runtimes should include the config their adapter expects."
+ "Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Hermes Gateway agents must include apiBaseUrl, API_SERVER_KEY-backed auth, and paperclipApiUrl. Other runtimes should include the config their adapter expects."
},
registrationEndpoint: {
method: "POST",
@@ -1744,6 +1854,37 @@ export function buildInviteOnboardingTextDocument(
For OpenClaw Gateway, include agentDefaultsPayload.headers.x-openclaw-token with your gateway token. Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred. Do NOT use /v1/responses or /hooks/* in this gateway join flow.
+ Hermes Gateway setup:
+ - adapterType: "hermes_gateway"
+ - Start Hermes with API_SERVER_ENABLED=true and API_SERVER_KEY=<random-gateway-key>.
+ - Run: hermes gateway run --replace --accept-hooks
+ - Default Hermes API server port: 8642.
+ - Set agentDefaultsPayload.apiBaseUrl to the Hermes gateway URL Paperclip can reach.
+ - Set agentDefaultsPayload.paperclipApiUrl to the Paperclip base URL Hermes can reach.
+ - Use hermes_local when Paperclip should start Hermes on the Paperclip host.
+ - Use hermes_gateway when Paperclip should call an already-running Hermes API server.
+ - Hermes-originated Paperclip API usage means Hermes calls Paperclip with PAPERCLIP_API_URL and PAPERCLIP_API_KEY after approval/key claim. Do not confuse that with agentDefaultsPayload.apiBaseUrl, which points Paperclip to Hermes.
+
+ Hermes Gateway payload example:
+ {
+ "requestType": "agent",
+ "agentName": "My Hermes Gateway Agent",
+ "adapterType": "hermes_gateway",
+ "capabilities": "Hermes gateway agent",
+ "agentDefaultsPayload": {
+ "apiBaseUrl": "http://127.0.0.1:8642",
+ "apiKey": "<same-value-as-API_SERVER_KEY>",
+ "paperclipApiUrl": "http://localhost:3100"
+ }
+ }
+
+ Hermes Gateway network examples:
+ - Local loopback: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642" and agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".
+ - LAN/private network: use reachable private addresses, for example agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642" and agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100".
+ - Private overlay: use overlay DNS names, for example agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642" and agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100".
+ - Docker: if Paperclip runs in Docker and Hermes runs on the host, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642"; if both run in Compose, use the Hermes service name.
+ - Reverse proxy/TLS: use HTTPS origins, for example agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example" and agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example".
+
Expected response includes:
- request id
- one-time claimSecret
@@ -3565,6 +3706,20 @@ export function accessRoutes(
throw badRequest(joinDefaults.fatalErrors.join("; "));
}
+ const persistedJoinDefaultsPayload =
+ requestType === "agent"
+ ? await prepareAgentDefaultsPayloadForJoinPersistence({
+ db,
+ companyId,
+ adapterType,
+ normalized: joinDefaults.normalized,
+ actor: {
+ userId: req.actor.userId ?? null,
+ agentId: req.actor.agentId ?? null
+ }
+ })
+ : null;
+
if (requestType === "agent" && adapterType === "openclaw_gateway") {
logger.info(
{
@@ -3658,7 +3813,7 @@ export function accessRoutes(
? req.body.capabilities ?? null
: null,
agentDefaultsPayload:
- requestType === "agent" ? joinDefaults.normalized : null,
+ requestType === "agent" ? persistedJoinDefaultsPayload : null,
claimSecretHash,
claimSecretExpiresAt
})
@@ -3684,7 +3839,7 @@ export function accessRoutes(
: null,
adapterType: requestType === "agent" ? adapterType : null,
agentDefaultsPayload:
- requestType === "agent" ? joinDefaults.normalized : null,
+ requestType === "agent" ? persistedJoinDefaultsPayload : null,
updatedAt: new Date()
})
.where(eq(joinRequests.id, replayJoinRequestId as string))
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 055abfb5c1..57c63ea9ad 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -140,7 +140,6 @@ export function agentRoutes(
codex_local: "instructionsFilePath",
droid_local: "instructionsFilePath",
gemini_local: "instructionsFilePath",
- hermes_local: "instructionsFilePath",
opencode_local: "instructionsFilePath",
cursor: "instructionsFilePath",
pi_local: "instructionsFilePath",
@@ -1079,7 +1078,10 @@ export function agentRoutes(
const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
input.companyId,
input.adapterConfig,
- { strictMode: strictSecretsMode },
+ {
+ strictMode: strictSecretsMode,
+ adapterType: input.adapterType ?? null,
+ },
);
await assertAdapterConfigConstraints(
input.adapterType,
@@ -1617,11 +1619,13 @@ export function agentRoutes(
const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
companyId,
inputAdapterConfig,
- { strictMode: strictSecretsMode },
+ { strictMode: strictSecretsMode, adapterType: type },
);
const { config: runtimeAdapterConfig } = await secretsSvc.resolveAdapterConfigForRuntime(
companyId,
normalizedAdapterConfig,
+ undefined,
+ { adapterType: type },
);
const { executionTarget, environmentName, fallbackChecks, release } =
@@ -1943,6 +1947,18 @@ export function agentRoutes(
res.json(buildLowTrustSelfView(agent));
return;
}
+ if (req.actor.keyScope?.kind === "task_bridge") {
+ res.json({
+ id: agent.id,
+ companyId: agent.companyId,
+ name: agent.name,
+ role: agent.role,
+ title: agent.title,
+ status: agent.status,
+ keyScope: req.actor.keyScope,
+ });
+ return;
+ }
res.json(await buildAgentDetail(agent));
});
@@ -2572,7 +2588,7 @@ export function agentRoutes(
const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
existing.companyId,
syncedAdapterConfig,
- { strictMode: strictSecretsMode },
+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },
);
const actor = getActorInfo(req);
const agent = await svc.update(
@@ -2643,7 +2659,7 @@ export function agentRoutes(
const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
existing.companyId,
adapterConfig,
- { strictMode: strictSecretsMode },
+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },
);
await svc.update(
id,
@@ -2711,7 +2727,7 @@ export function agentRoutes(
const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
existing.companyId,
result.adapterConfig,
- { strictMode: strictSecretsMode },
+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },
);
await svc.update(
id,
@@ -3184,7 +3200,7 @@ export function agentRoutes(
if (!agent) {
return;
}
- const key = await svc.createApiKey(id, req.body.name);
+ const key = await svc.createApiKey(id, req.body.name, req.body.scope);
await logActivity(db, {
companyId: agent.companyId,
@@ -3193,7 +3209,7 @@ export function agentRoutes(
action: "agent.key_created",
entityType: "agent",
entityId: agent.id,
- details: { keyId: key.id, name: key.name },
+ details: { keyId: key.id, name: key.name, scope: key.scope },
});
res.status(201).json(key);
diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts
index 95e0a05cfa..2913a05fc0 100644
--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -1889,6 +1889,25 @@ export function issueRoutes(
throw forbidden(decision.explanation);
}
+ function isTaskBridgeKeyActor(req: Request) {
+ return req.actor.type === "agent" && req.actor.source === "agent_key" && req.actor.keyScope?.kind === "task_bridge";
+ }
+
+ function taskBridgeOriginForActor(req: Request) {
+ return isTaskBridgeKeyActor(req) && req.actor.keyId
+ ? { originKind: "task_bridge", originId: req.actor.keyId }
+ : null;
+ }
+
+ async function assertTaskBridgeCreateAllowed(
+ req: Request,
+ companyId: string,
+ assignmentScope: TaskAssignmentAuthorizationScope,
+ ) {
+ if (!isTaskBridgeKeyActor(req)) return;
+ await assertCanAssignTasks(req, companyId, assignmentScope);
+ }
+
async function decideIssueAccess(
req: Request,
issue: {
@@ -2966,6 +2985,10 @@ export function issueRoutes(
router.get("/companies/:companyId/issues", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
+ if (isTaskBridgeKeyActor(req)) {
+ res.status(403).json({ error: "Task bridge keys cannot use company-wide issue list APIs" });
+ return;
+ }
const assigneeUserFilterRaw = req.query.assigneeUserId as string | undefined;
const touchedByUserFilterRaw = req.query.touchedByUserId as string | undefined;
const inboxArchivedByUserFilterRaw = req.query.inboxArchivedByUserId as string | undefined;
@@ -3126,6 +3149,10 @@ export function issueRoutes(
router.get("/companies/:companyId/issues/count", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
+ if (isTaskBridgeKeyActor(req)) {
+ res.status(403).json({ error: "Task bridge keys cannot use company-wide issue count APIs" });
+ return;
+ }
const attention = req.query.attention as string | undefined;
const hasPlanDocument = parseOptionalBooleanQuery(req.query.hasPlanDocument);
if (attention !== "blocked") {
@@ -5050,7 +5077,7 @@ export function issueRoutes(
if (watchdogProductBugFollowUp === false) return;
const effectiveParentId = watchdogProductBugFollowUp ? null : rawCreateBody.parentId;
let createParent: Awaited<ReturnType<typeof svc.getById>> | null = null;
- if (req.actor.type === "agent" && !effectiveParentId && !watchdogProductBugFollowUp) {
+ if (req.actor.type === "agent" && !effectiveParentId && !watchdogProductBugFollowUp && !isTaskBridgeKeyActor(req)) {
const companyScopeDecision = await access.decide({
actor: req.actor,
action: "company_scope:read",
@@ -5067,7 +5094,7 @@ export function issueRoutes(
res.status(404).json({ error: "Parent issue not found" });
return;
}
- if (!(await assertIssueReadAllowed(req, res, createParent))) return;
+ if (!isTaskBridgeKeyActor(req) && !(await assertIssueReadAllowed(req, res, createParent))) return;
}
if (
!watchdogProductBugFollowUp &&
@@ -5113,17 +5140,19 @@ export function issueRoutes(
: {}),
};
if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, { companyId }, createBody))) return;
+ const createAssignmentScope = {
+ projectId: await resolveAssignmentProjectId({
+ companyId,
+ projectId: createBody.projectId,
+ parentIssueId: createBody.parentId,
+ }),
+ parentIssueId: createBody.parentId ?? null,
+ assigneeAgentId: createBody.assigneeAgentId ?? null,
+ assigneeUserId: rawCreateBody.assigneeUserId ?? null,
+ };
+ await assertTaskBridgeCreateAllowed(req, companyId, createAssignmentScope);
if (rawCreateBody.assigneeAgentId || rawCreateBody.assigneeUserId) {
- await assertCanAssignTasks(req, companyId, {
- projectId: await resolveAssignmentProjectId({
- companyId,
- projectId: createBody.projectId,
- parentIssueId: createBody.parentId,
- }),
- parentIssueId: createBody.parentId ?? null,
- assigneeAgentId: createBody.assigneeAgentId ?? null,
- assigneeUserId: rawCreateBody.assigneeUserId ?? null,
- });
+ await assertCanAssignTasks(req, companyId, createAssignmentScope);
}
await assertIssueEnvironmentSelection(companyId, createBody.executionWorkspaceSettings?.environmentId);
@@ -5141,6 +5170,7 @@ export function issueRoutes(
}, actor);
const issue = await svc.create(companyId, {
...createBody,
+ ...(taskBridgeOriginForActor(req) ?? {}),
id: issueId,
executionPolicy,
...(sourceTrust ? { sourceTrust } : {}),
@@ -5258,7 +5288,7 @@ export function issueRoutes(
return;
}
assertCompanyAccess(req, parent.companyId);
- if (!(await assertIssueReadAllowed(req, res, parent))) return;
+ if (!isTaskBridgeKeyActor(req) && !(await assertIssueReadAllowed(req, res, parent))) return;
if (!(await assertTaskWatchdogCreateIssueAllowed(req, res, parent.companyId, parent))) return;
if (await assertLowTrustControlPlaneDenied(req, res, parent.companyId, parent)) return;
assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
@@ -5271,13 +5301,15 @@ export function issueRoutes(
...(normalizedAssigneeAgentId !== undefined ? { assigneeAgentId: normalizedAssigneeAgentId } : {}),
};
if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, parent, createBody))) return;
+ const childAssignmentScope = {
+ projectId: createBody.projectId ?? parent.projectId ?? null,
+ parentIssueId: parent.id,
+ assigneeAgentId: createBody.assigneeAgentId ?? null,
+ assigneeUserId: createBody.assigneeUserId ?? null,
+ };
+ await assertTaskBridgeCreateAllowed(req, parent.companyId, childAssignmentScope);
if (req.body.assigneeAgentId || req.body.assigneeUserId) {
- await assertCanAssignTasks(req, parent.companyId, {
- projectId: createBody.projectId ?? parent.projectId ?? null,
- parentIssueId: parent.id,
- assigneeAgentId: createBody.assigneeAgentId ?? null,
- assigneeUserId: createBody.assigneeUserId ?? null,
- });
+ await assertCanAssignTasks(req, parent.companyId, childAssignmentScope);
}
await assertIssueEnvironmentSelection(parent.companyId, createBody.executionWorkspaceSettings?.environmentId);
@@ -5300,6 +5332,7 @@ export function issueRoutes(
}, actor);
const { issue, parentBlockerAdded } = await svc.createChild(parent.id, {
...createBody,
+ ...(taskBridgeOriginForActor(req) ?? {}),
id: issueId,
executionPolicy,
...(currentSerializedChild
diff --git a/server/src/routes/llms.ts b/server/src/routes/llms.ts
index ff5f36dca4..2d0d75eb60 100644
--- a/server/src/routes/llms.ts
+++ b/server/src/routes/llms.ts
@@ -3,8 +3,13 @@ import type { Db } from "@paperclipai/db";
import { AGENT_ICON_NAMES } from "@paperclipai/shared";
import { forbidden } from "../errors.js";
import { listServerAdapters } from "../adapters/index.js";
+import { hermesGatewayAgentConfigurationDoc } from "../adapters/hermes-gateway-doc.js";
import { agentService } from "../services/agents.js";
+const pluginOnlyAdapterDocs = new Map<string, string>([
+ ["hermes_gateway", hermesGatewayAgentConfigurationDoc],
+]);
+
function hasCreatePermission(agent: { role: string; permissions: Record<string, unknown> | null | undefined }) {
if (!agent.permissions || typeof agent.permissions !== "object") return false;
return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);
@@ -34,6 +39,15 @@ export function llmRoutes(db: Db) {
"Installed adapters:",
...adapters.map((adapter) => `- ${adapter.type}: /llms/agent-configuration/${adapter.type}.txt`),
"",
+ "Plugin-only adapter docs:",
+ ...Array.from(pluginOnlyAdapterDocs.keys())
+ .filter(
+ (adapterType) => !adapters.some((adapter) => adapter.type === adapterType),
+ )
+ .map(
+ (adapterType) => `- ${adapterType}: /llms/agent-configuration/${adapterType}.txt`,
+ ),
+ "",
"Related API endpoints:",
"- GET /api/companies/:companyId/agent-configurations",
"- GET /api/agents/:id/configuration",
@@ -72,6 +86,11 @@ export function llmRoutes(db: Db) {
const adapterType = req.params.adapterType as string;
const adapter = listServerAdapters().find((entry) => entry.type === adapterType);
if (!adapter) {
+ const pluginOnlyDoc = pluginOnlyAdapterDocs.get(adapterType);
+ if (pluginOnlyDoc) {
+ res.type("text/plain").send(pluginOnlyDoc);
+ return;
+ }
res.status(404).type("text/plain").send(`Unknown adapter type: ${adapterType}`);
return;
}
diff --git a/server/src/services/agent-secret-bindings.ts b/server/src/services/agent-secret-bindings.ts
index 4afb096b24..9e266f21b6 100644
--- a/server/src/services/agent-secret-bindings.ts
+++ b/server/src/services/agent-secret-bindings.ts
@@ -1,4 +1,18 @@
+import { envBindingSchema, type SecretVersionSelector } from "@paperclipai/shared";
+
interface AgentSecretBindingSyncService {
+ syncSecretRefsForTarget?: (
+ companyId: string,
+ target: { targetType: "agent"; targetId: string },
+ refs: Array<{
+ secretId: string;
+ configPath: string;
+ versionSelector?: SecretVersionSelector;
+ required?: boolean;
+ label?: string | null;
+ }>,
+ options?: { replaceAll?: boolean },
+ ) => Promise<unknown>;
syncEnvBindingsForTarget?: (
companyId: string,
target: { targetType: "agent"; targetId: string; pathPrefix?: string },
@@ -11,12 +25,63 @@ function asRecord(value: unknown): Record<string, unknown> | null {
return value as Record<string, unknown>;
}
+function collectSecretRefs(adapterConfig: unknown): Array<{
+ secretId: string;
+ configPath: string;
+ versionSelector?: SecretVersionSelector;
+}> {
+ const config = asRecord(adapterConfig);
+ if (!config) return [];
+ const refs: Array<{
+ secretId: string;
+ configPath: string;
+ versionSelector?: SecretVersionSelector;
+ }> = [];
+
+ const envValue = asRecord(config.env);
+ for (const [key, rawBinding] of Object.entries(envValue ?? {})) {
+ const parsed = envBindingSchema.safeParse(rawBinding);
+ if (!parsed.success) continue;
+ const binding = parsed.data;
+ if (typeof binding !== "object" || binding === null || binding.type !== "secret_ref") continue;
+ refs.push({
+ secretId: binding.secretId,
+ configPath: `env.${key}`,
+ versionSelector: binding.version ?? "latest",
+ });
+ }
+
+ for (const [key, rawBinding] of Object.entries(config)) {
+ if (key === "env") continue;
+ const parsed = envBindingSchema.safeParse(rawBinding);
+ if (!parsed.success) continue;
+ const binding = parsed.data;
+ if (typeof binding !== "object" || binding === null || binding.type !== "secret_ref") continue;
+ refs.push({
+ secretId: binding.secretId,
+ configPath: key,
+ versionSelector: binding.version ?? "latest",
+ });
+ }
+
+ return refs;
+}
+
export async function syncAgentAdapterEnvBindings(input: {
secretsSvc: AgentSecretBindingSyncService;
companyId: string;
agentId: string;
adapterConfig: unknown;
}) {
+ if (input.secretsSvc.syncSecretRefsForTarget) {
+ await input.secretsSvc.syncSecretRefsForTarget(
+ input.companyId,
+ { targetType: "agent", targetId: input.agentId },
+ collectSecretRefs(input.adapterConfig),
+ { replaceAll: true },
+ );
+ return;
+ }
const envValue = asRecord(asRecord(input.adapterConfig)?.env);
await input.secretsSvc.syncEnvBindingsForTarget?.(
input.companyId,
diff --git a/server/src/services/agents.ts b/server/src/services/agents.ts
index 2c69558944..9be0140503 100644
--- a/server/src/services/agents.ts
+++ b/server/src/services/agents.ts
@@ -20,8 +20,10 @@ import {
AGENT_DEFAULT_MAX_CONCURRENT_RUNS,
getAgentWorkEligibility,
isUuidLike,
+ normalizeAgentApiKeyScope,
normalizeAgentUrlKey,
type AgentEligibilityAgent,
+ type AgentApiKeyScope,
} from "@paperclipai/shared";
import { conflict, notFound, unprocessable } from "../errors.js";
import { syncAgentAdapterEnvBindings } from "./agent-secret-bindings.js";
@@ -428,6 +430,16 @@ export function agentService(db: Db) {
const role = (data.role ?? existing.role) as string;
normalizedPatch.permissions = normalizeAgentPermissions(data.permissions, role);
}
+ if (
+ Object.prototype.hasOwnProperty.call(normalizedPatch, "adapterConfig") &&
+ isPlainRecord(normalizedPatch.adapterConfig)
+ ) {
+ normalizedPatch.adapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(
+ existing.companyId,
+ normalizedPatch.adapterConfig,
+ { adapterType: (normalizedPatch.adapterType ?? existing.adapterType) as string },
+ );
+ }
const shouldRecordRevision = Boolean(options?.recordRevision) && hasConfigPatchFields(normalizedPatch);
const beforeConfig = shouldRecordRevision ? buildConfigSnapshot(existing) : null;
@@ -503,11 +515,24 @@ export function agentService(db: Db) {
const role = data.role ?? "general";
const normalizedPermissions = normalizeAgentPermissions(data.permissions, role);
const runtimeConfig = normalizeRuntimeConfigForNewAgent(data.runtimeConfig);
+ const adapterType = data.adapterType ?? "process";
+ const adapterConfig = isPlainRecord(data.adapterConfig)
+ ? await secretsSvc.normalizeAdapterConfigForPersistence(companyId, data.adapterConfig, { adapterType })
+ : {};
return db.transaction(async (tx) => {
const txDb = tx as unknown as Db;
const created = await tx
.insert(agents)
- .values({ ...data, name: uniqueName, companyId, role, permissions: normalizedPermissions, runtimeConfig })
+ .values({
+ ...data,
+ name: uniqueName,
+ companyId,
+ role,
+ adapterType,
+ adapterConfig,
+ permissions: normalizedPermissions,
+ runtimeConfig,
+ })
.returning()
.then((rows) => rows[0]);
await syncAgentSecretBindings(created, txDb);
@@ -733,7 +758,7 @@ export function agentService(db: Db) {
});
},
- createApiKey: async (id: string, name: string) => {
+ createApiKey: async (id: string, name: string, scope: AgentApiKeyScope = { kind: "standard" }) => {
const existing = await getById(id);
if (!existing) throw notFound("Agent not found");
if (existing.status === "pending_approval") {
@@ -752,6 +777,7 @@ export function agentService(db: Db) {
companyId: existing.companyId,
name,
keyHash,
+ scopeConfig: scope.kind === "standard" ? null : scope,
})
.returning()
.then((rows) => rows[0]);
@@ -759,6 +785,7 @@ export function agentService(db: Db) {
return {
id: created.id,
name: created.name,
+ scope: normalizeAgentApiKeyScope(created.scopeConfig),
token,
createdAt: created.createdAt,
};
@@ -769,11 +796,19 @@ export function agentService(db: Db) {
.select({
id: agentApiKeys.id,
name: agentApiKeys.name,
+ scopeConfig: agentApiKeys.scopeConfig,
createdAt: agentApiKeys.createdAt,
revokedAt: agentApiKeys.revokedAt,
})
.from(agentApiKeys)
- .where(eq(agentApiKeys.agentId, id)),
+ .where(eq(agentApiKeys.agentId, id))
+ .then((rows) => rows.map((row) => ({
+ id: row.id,
+ name: row.name,
+ scope: normalizeAgentApiKeyScope(row.scopeConfig),
+ createdAt: row.createdAt,
+ revokedAt: row.revokedAt,
+ }))),
getKeyById: async (keyId: string) =>
db
@@ -782,12 +817,21 @@ export function agentService(db: Db) {
agentId: agentApiKeys.agentId,
companyId: agentApiKeys.companyId,
name: agentApiKeys.name,
+ scopeConfig: agentApiKeys.scopeConfig,
createdAt: agentApiKeys.createdAt,
revokedAt: agentApiKeys.revokedAt,
})
.from(agentApiKeys)
.where(eq(agentApiKeys.id, keyId))
- .then((rows) => rows[0] ?? null),
+ .then((rows) => {
+ const row = rows[0] ?? null;
+ return row
+ ? {
+ ...row,
+ scope: normalizeAgentApiKeyScope(row.scopeConfig),
+ }
+ : null;
+ }),
revokeKey: async (agentId: string, keyId: string) => {
const rows = await db
diff --git a/server/src/services/authorization.ts b/server/src/services/authorization.ts
index a4c513009c..d3c2a2749c 100644
--- a/server/src/services/authorization.ts
+++ b/server/src/services/authorization.ts
@@ -10,7 +10,7 @@ import {
principalPermissionGrants,
projects,
} from "@paperclipai/db";
-import type { PermissionKey, PrincipalType } from "@paperclipai/shared";
+import type { AgentApiKeyScope, PermissionKey, PrincipalType, TaskBridgeAgentKeyScope } from "@paperclipai/shared";
import { LOW_TRUST_REVIEW_PRESET, extractAgentMentionIds, type LowTrustBoundary } from "@paperclipai/shared";
import {
LOW_TRUST_ISSUE_ANCESTRY_MAX_DEPTH,
@@ -29,6 +29,8 @@ export type AuthorizationActor =
isInstanceAdmin?: boolean;
agentId?: string | null;
companyId?: string | null;
+ keyId?: string | null;
+ keyScope?: AgentApiKeyScope | null;
runId?: string | null;
source?:
| "local_implicit"
@@ -66,6 +68,8 @@ export type AuthorizationResource =
parentIssueId?: string | null;
assigneeAgentId?: string | null;
assigneeUserId?: string | null;
+ originKind?: string | null;
+ originId?: string | null;
status?: string | null;
};
@@ -211,6 +215,8 @@ type IssueAuthorizationRow = {
assigneeUserId: string | null;
status: string;
executionPolicy: unknown;
+ originKind: string | null;
+ originId: string | null;
};
function evaluateAuthorizationPolicyForAssignment(
@@ -550,6 +556,8 @@ export function authorizationService(db: Db) {
assigneeUserId: issues.assigneeUserId,
status: issues.status,
executionPolicy: issues.executionPolicy,
+ originKind: issues.originKind,
+ originId: issues.originId,
})
.from(issues)
.where(eq(issues.id, issueId))
@@ -802,6 +810,130 @@ export function authorizationService(db: Db) {
return null;
}
+ function taskBridgeScopeIds(
+ scope: TaskBridgeAgentKeyScope,
+ singularKey: "projectId" | "parentIssueId",
+ pluralKey: "projectIds" | "parentIssueIds",
+ ) {
+ return [
+ ...(typeof scope[singularKey] === "string" ? [scope[singularKey]] : []),
+ ...(Array.isArray(scope[pluralKey]) ? scope[pluralKey] : []),
+ ].filter((value): value is string => typeof value === "string" && value.length > 0);
+ }
+
+ async function parentIssueMatchesTaskBridgeBoundary(
+ parentIssueId: string | null | undefined,
+ companyId: string,
+ allowedParentIssueIds: string[],
+ ) {
+ if (!parentIssueId || allowedParentIssueIds.length === 0) return false;
+ if (allowedParentIssueIds.includes(parentIssueId)) return true;
+ for (const rootIssueId of allowedParentIssueIds) {
+ if (await issueIdIsDescendantOf(parentIssueId, rootIssueId, companyId)) return true;
+ }
+ return false;
+ }
+
+ async function issueMatchesTaskBridgeCreateBoundary(
+ scope: TaskBridgeAgentKeyScope,
+ resource: Extract<AuthorizationResource, { type: "issue" }>,
+ ) {
+ const allowedProjectIds = taskBridgeScopeIds(scope, "projectId", "projectIds");
+ const allowedParentIssueIds = taskBridgeScopeIds(scope, "parentIssueId", "parentIssueIds");
+ if (resource.projectId && allowedProjectIds.includes(resource.projectId)) return true;
+ if (await parentIssueMatchesTaskBridgeBoundary(resource.parentIssueId, resource.companyId, allowedParentIssueIds)) {
+ return true;
+ }
+ if (resource.parentIssueId && allowedProjectIds.length > 0) {
+ const parent = await loadIssue(resource.parentIssueId);
+ if (parent?.companyId === resource.companyId && parent.projectId && allowedProjectIds.includes(parent.projectId)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ async function issueMatchesTaskBridgeWriteBoundary(input: {
+ actorAgentId: string;
+ keyId: string;
+ resource: Extract<AuthorizationResource, { type: "issue" }>;
+ }) {
+ const issue = input.resource.issueId ? await loadIssue(input.resource.issueId) : null;
+ const assigneeAgentId = issue?.assigneeAgentId ?? input.resource.assigneeAgentId ?? null;
+ if (assigneeAgentId === input.actorAgentId) return true;
+ const originKind = issue?.originKind ?? input.resource.originKind ?? null;
+ const originId = issue?.originId ?? input.resource.originId ?? null;
+ return originKind === "task_bridge" && originId === input.keyId;
+ }
+
+ async function decideTaskBridgeAccess(input: {
+ actorAgentId: string;
+ action: AuthorizationAction;
+ resource: AuthorizationResource;
+ scope: TaskBridgeAgentKeyScope;
+ keyId: string;
+ }): Promise<AuthorizationDecision | null> {
+ const denyBridge = (explanation: string) =>
+ deny({
+ action: input.action,
+ reason: "deny_scope",
+ explanation,
+ });
+ const allowBridge = (explanation: string) =>
+ allow({
+ action: input.action,
+ reason: "allow_explicit_grant",
+ explanation,
+ });
+
+ if (
+ input.action === "company_scope:read" ||
+ input.action === "agent:read" ||
+ input.action === "agent:wake" ||
+ input.action === "project:read" ||
+ input.action === "runtime:manage" ||
+ input.action === "secrets:read"
+ ) {
+ return denyBridge("Task bridge keys cannot use company-wide, peer-agent, project, runtime, or secret APIs.");
+ }
+
+ if (input.action === "tasks:assign") {
+ if (input.resource.type !== "issue") {
+ return denyBridge("Task bridge assignment requires an issue resource.");
+ }
+ if (!(await issueMatchesTaskBridgeCreateBoundary(input.scope, input.resource))) {
+ return denyBridge("Task bridge key is outside its approved parent or project boundary.");
+ }
+ if (input.resource.assigneeUserId) {
+ return denyBridge("Task bridge keys cannot assign work to board users.");
+ }
+ const allowedAssigneeAgentIds = input.scope.allowedAssigneeAgentIds ?? [];
+ if (
+ input.resource.assigneeAgentId &&
+ input.resource.assigneeAgentId !== input.actorAgentId &&
+ !allowedAssigneeAgentIds.includes(input.resource.assigneeAgentId)
+ ) {
+ return denyBridge("Task bridge key cannot assign work to that agent.");
+ }
+ return allowBridge("Allowed by task bridge create boundary.");
+ }
+
+ if (input.action === "issue:read" || input.action === "issue:comment" || input.action === "issue:mutate") {
+ if (input.resource.type !== "issue") {
+ return denyBridge("Task bridge issue access requires an issue resource.");
+ }
+ return await issueMatchesTaskBridgeWriteBoundary({
+ actorAgentId: input.actorAgentId,
+ keyId: input.keyId,
+ resource: input.resource,
+ })
+ ? allowBridge("Allowed for bridge-created or assigned issue.")
+ : denyBridge("Task bridge key can only access assigned or bridge-created issues.");
+ }
+
+ return denyBridge("Task bridge key cannot use this API action.");
+ }
+
async function assignmentTargetIsInCompany(resource: AuthorizationResource) {
if (resource.type !== "issue") return true;
if (resource.assigneeAgentId) {
@@ -1183,6 +1315,25 @@ export function authorizationService(db: Db) {
});
}
+ if (input.actor.source === "agent_key" && input.actor.keyScope?.kind === "task_bridge") {
+ const keyId = input.actor.keyId ?? null;
+ if (!keyId) {
+ return deny({
+ action: input.action,
+ reason: "deny_scope",
+ explanation: "Task bridge key context is missing.",
+ });
+ }
+ const taskBridgeDecision = await decideTaskBridgeAccess({
+ actorAgentId,
+ action: input.action,
+ resource: input.resource,
+ scope: input.actor.keyScope,
+ keyId,
+ });
+ if (taskBridgeDecision) return taskBridgeDecision;
+ }
+
const lowTrustDecision = await decideLowTrustAccess({
actorAgentId,
action: input.action,
diff --git a/server/src/services/company-portability.ts b/server/src/services/company-portability.ts
index 1024a871b7..b1c1c7216c 100644
--- a/server/src/services/company-portability.ts
+++ b/server/src/services/company-portability.ts
@@ -3050,7 +3050,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
const normalizedAdapterConfig = await secrets.normalizeAdapterConfigForPersistence(
companyId,
nextAdapterConfig,
- { strictMode: strictSecretsMode },
+ { strictMode: strictSecretsMode, adapterType: effectiveAdapterType },
);
await assertImportAdapterConfigConstraints(effectiveAdapterType, normalizedAdapterConfig);
return {
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 197b11d8c6..81c4a3af9f 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -412,7 +412,10 @@ const INLINE_BASE64_IMAGE_DATA_RE = /("type":"image","source":\{"type":"base64",
type RuntimeConfigSecretResolver = Pick<
ReturnType<typeof secretService>,
- "resolveAdapterConfigForRuntime" | "resolveEnvBindings" | "collectMissingRuntimeBindings"
+ | "resolveAdapterConfigForRuntime"
+ | "resolveEnvBindings"
+ | "collectMissingRuntimeBindings"
+ | "collectMissingAdapterConfigRuntimeBindings"
>;
function formatMissingBindingForOperator(missing: MissingRuntimeBinding): string {
@@ -494,6 +497,7 @@ function assertLowTrustEnvConfigAllowed(envValue: unknown, source: string) {
export async function resolveExecutionRunAdapterConfig(input: {
companyId: string;
agentId?: string | null;
+ adapterType?: string | null;
issueId?: string | null;
heartbeatRunId?: string | null;
environmentId?: string | null;
@@ -574,6 +578,16 @@ export async function resolveExecutionRunAdapterConfig(input: {
{ consumerType: "agent", consumerId: input.agentId },
)),
);
+ if (typeof input.secretsSvc.collectMissingAdapterConfigRuntimeBindings === "function") {
+ missingBindings.push(
+ ...(await input.secretsSvc.collectMissingAdapterConfigRuntimeBindings(
+ input.companyId,
+ executionRunConfig,
+ input.adapterType ?? null,
+ { consumerType: "agent", consumerId: input.agentId },
+ )),
+ );
+ }
}
if (projectEnv && input.projectId) {
missingBindings.push(
@@ -666,6 +680,7 @@ export async function resolveExecutionRunAdapterConfig(input: {
...(lowTrustAllowedBindingIds !== undefined ? { allowedBindingIds: lowTrustAllowedBindingIds } : {}),
}
: undefined,
+ { adapterType: input.adapterType ?? null },
);
if (Object.keys(environmentEnvResolution.env).length > 0) {
resolvedConfig.env = {
@@ -3140,6 +3155,13 @@ export function buildPaperclipTaskMarkdown(input: {
workMode?: string | null;
description?: string | null;
} | null;
+ ancestors?: Array<{
+ id: string;
+ identifier?: string | null;
+ title?: string | null;
+ status?: string | null;
+ priority?: string | null;
+ }> | null;
wakeComment?: {
id: string;
body: string;
@@ -3160,6 +3182,7 @@ export function buildPaperclipTaskMarkdown(input: {
return [fence + "text", value, fence].join("\n");
};
const issue = input.issue;
+ const ancestors = (input.ancestors ?? []).slice(0, 6);
const wakeComment = input.wakeComment ?? null;
const acceptedPlanContinuation =
!wakeComment &&
@@ -3212,6 +3235,19 @@ export function buildPaperclipTaskMarkdown(input: {
lines.push("", "Issue description:", fenceTaskText(description));
}
}
+ if (ancestors.length > 0) {
+ lines.push("", "Authoritative parent / ancestor context:");
+ for (const [index, ancestor] of ancestors.entries()) {
+ const label = ancestor.identifier || ancestor.id;
+ const status = ancestor.status ? ` (${ancestor.status})` : "";
+ const priority = ancestor.priority ? ` [${ancestor.priority}]` : "";
+ const title = ancestor.title ? ` ${ancestor.title}` : "";
+ lines.push(`- ${index === 0 ? "Parent" : `Ancestor ${index + 1}`}: ${label}${title}${status}${priority}`);
+ }
+ if ((input.ancestors ?? []).length > ancestors.length) {
+ lines.push(`- [ancestor context truncated after ${ancestors.length} entries]`);
+ }
+ }
if (wakeComment?.body.trim()) {
lines.push("", "Latest wake comment:", fenceTaskText(wakeComment.body.trim()));
}
@@ -8647,6 +8683,9 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
wakeCommentContext && !exposeLowTrustRaw
? sanitizeQuarantinedCommentForHigherTrust(wakeCommentContext)
: wakeCommentContext;
+ const issueAncestors = issueRef
+ ? await issuesSvc.getAncestors(issueRef.id)
+ : [];
if (continuationSummary) {
context.paperclipContinuationSummary = {
key: safeContinuationSummary!.key,
@@ -8692,6 +8731,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
description: issueRef.description,
}
: null,
+ ancestors: issueAncestors,
wakeComment: safeWakeCommentContext,
interaction: {
kind: readNonEmptyString(context.interactionKind),
@@ -8918,6 +8958,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
const { resolvedConfig, secretKeys, secretManifest } = await resolveExecutionRunAdapterConfig({
companyId: agent.companyId,
agentId: agent.id,
+ adapterType: agent.adapterType,
issueId,
heartbeatRunId: run.id,
environmentId: selectedEnvironmentForConfig?.id ?? null,
diff --git a/server/src/services/secrets.ts b/server/src/services/secrets.ts
index 25b1228d8e..69fefbbe3d 100644
--- a/server/src/services/secrets.ts
+++ b/server/src/services/secrets.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
import { and, desc, eq, inArray, like, ne, notInArray, or, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import {
@@ -55,6 +56,7 @@ import type {
} from "../secrets/types.js";
import { isSecretProviderClientError } from "../secrets/types.js";
import { authorizationService } from "./authorization.js";
+import { findActiveServerAdapter } from "../adapters/index.js";
const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
const SENSITIVE_ENV_KEY_RE =
@@ -64,6 +66,9 @@ const COMING_SOON_SECRET_PROVIDERS: ReadonlySet<SecretProvider> = new Set([
"gcp_secret_manager",
"vault",
]);
+const FALLBACK_ADAPTER_SCHEMA_SECRET_FIELDS: Readonly<Record<string, readonly string[]>> = {
+ hermes_gateway: ["apiKey"],
+};
type DbTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
type SecretBindingDb = Pick<Db | DbTransaction, "select" | "delete" | "insert">;
@@ -357,6 +362,11 @@ export function secretService(db: Db) {
strictMode?: boolean;
fieldPath?: string;
};
+ type NormalizeAdapterConfigOptions = {
+ strictMode?: boolean;
+ adapterType?: string | null;
+ actor?: { userId?: string | null; agentId?: string | null };
+ };
async function getById(id: string, source: Pick<Db | DbTransaction, "select"> = db) {
return source
@@ -809,16 +819,210 @@ export function secretService(db: Db) {
async function normalizeAdapterConfigForPersistenceInternal(
companyId: string,
adapterConfig: Record<string, unknown>,
- opts?: { strictMode?: boolean },
+ opts?: NormalizeAdapterConfigOptions,
) {
const normalized = { ...adapterConfig };
- if (!Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {
- return normalized;
+ if (Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {
+ normalized.env = await normalizeEnvConfig(companyId, adapterConfig.env, opts);
+ }
+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(opts?.adapterType);
+ for (const key of secretFieldKeys) {
+ if (!Object.prototype.hasOwnProperty.call(adapterConfig, key)) continue;
+ const value = await normalizeSchemaSecretFieldForPersistence(companyId, {
+ adapterType: opts?.adapterType ?? null,
+ key,
+ rawValue: adapterConfig[key],
+ actor: opts?.actor,
+ });
+ if (value === undefined) {
+ delete normalized[key];
+ } else {
+ normalized[key] = value;
+ }
}
- normalized.env = await normalizeEnvConfig(companyId, adapterConfig.env, opts);
return normalized;
}
+ async function listAdapterSchemaSecretFieldKeys(adapterType: string | null | undefined): Promise<string[]> {
+ if (!adapterType) return [];
+ const adapter = findActiveServerAdapter(adapterType);
+ const fallback = [...(FALLBACK_ADAPTER_SCHEMA_SECRET_FIELDS[adapterType] ?? [])];
+ if (!adapter?.getConfigSchema) return fallback;
+ try {
+ const schema = await adapter.getConfigSchema();
+ return [...new Set([
+ ...fallback,
+ ...schema.fields
+ .filter((field) => field.meta?.secret === true)
+ .map((field) => field.key),
+ ])];
+ } catch (err) {
+ logger.warn({ err, adapterType }, "adapter config schema unavailable while normalizing secret fields");
+ return fallback;
+ }
+ }
+
+ async function normalizeSchemaSecretFieldForPersistence(
+ companyId: string,
+ input: {
+ adapterType: string | null;
+ key: string;
+ rawValue: unknown;
+ actor?: { userId?: string | null; agentId?: string | null };
+ },
+ ): Promise<EnvBinding | undefined> {
+ if (input.rawValue === null || input.rawValue === undefined) return undefined;
+ const parsed = envBindingSchema.safeParse(input.rawValue);
+ if (!parsed.success) {
+ throw unprocessable(`${input.key} must be a string, plain binding, or secret reference`);
+ }
+ const binding = canonicalizeBinding(parsed.data as EnvBinding);
+ if (binding.type === "secret_ref") {
+ await assertSecretInCompany(companyId, binding.secretId);
+ return {
+ type: "secret_ref",
+ secretId: binding.secretId,
+ version: binding.version,
+ };
+ }
+ const value = binding.value.trim();
+ if (!value) return undefined;
+ if (value === REDACTED_SENTINEL) {
+ throw unprocessable(`Refusing to persist redacted placeholder for key: ${input.key}`);
+ }
+ const id = randomUUID();
+ const adapterPart = normalizeSecretKey(input.adapterType ?? "adapter");
+ const fieldPart = normalizeSecretKey(input.key);
+ const secret = await createManagedLocalSecret(companyId, {
+ name: `${adapterPart}.${fieldPart}.${id}`,
+ key: `${adapterPart}.${fieldPart}.${id}`,
+ value,
+ description: `Adapter config secret for ${input.adapterType ?? "adapter"}.${input.key}`,
+ }, input.actor);
+ return {
+ type: "secret_ref",
+ secretId: secret.id,
+ version: "latest",
+ };
+ }
+
+ async function createManagedLocalSecret(
+ companyId: string,
+ input: {
+ name: string;
+ key: string;
+ value: string;
+ description?: string | null;
+ },
+ actor?: { userId?: string | null; agentId?: string | null },
+ ) {
+ const existing = await getByName(companyId, input.name);
+ if (existing) throw conflict(`Secret already exists: ${input.name}`);
+ const key = normalizeSecretKey(input.key);
+ if (!key) throw unprocessable("Secret key is required");
+ const duplicateKey = await db
+ .select()
+ .from(companySecrets)
+ .where(and(
+ eq(companySecrets.companyId, companyId),
+ eq(companySecrets.key, key),
+ ne(companySecrets.status, "deleted"),
+ ))
+ .then((rows) => rows[0] ?? null);
+ if (duplicateKey) throw conflict(`Secret key already exists: ${key}`);
+
+ const provider = getSecretProvider("local_encrypted");
+ const providerConfig = await getSelectableRuntimeProviderConfig({
+ companyId,
+ provider: "local_encrypted",
+ providerConfigId: null,
+ });
+ const providerWriteContext = {
+ companyId,
+ secretKey: key,
+ secretName: input.name,
+ version: 1,
+ };
+ const reservedSecret = await db
+ .insert(companySecrets)
+ .values({
+ companyId,
+ key,
+ name: input.name,
+ provider: "local_encrypted",
+ providerConfigId: null,
+ status: "archived",
+ managedMode: "paperclip_managed",
+ externalRef: null,
+ providerMetadata: null,
+ latestVersion: 0,
+ description: input.description ?? null,
+ createdByAgentId: actor?.agentId ?? null,
+ createdByUserId: actor?.userId ?? null,
+ })
+ .returning()
+ .then((rows) => rows[0]);
+
+ let prepared: PreparedSecretVersion | null = null;
+ try {
+ prepared = await provider.createSecret({
+ value: input.value,
+ externalRef: null,
+ providerConfig,
+ context: providerWriteContext,
+ });
+ const preparedSecret = prepared;
+ await db.insert(companySecretVersions).values({
+ secretId: reservedSecret.id,
+ version: 1,
+ material: preparedSecret.material,
+ valueSha256: preparedSecret.valueSha256,
+ fingerprintSha256: preparedSecret.fingerprintSha256 ?? preparedSecret.valueSha256,
+ providerVersionRef: preparedSecret.providerVersionRef ?? null,
+ status: "disabled",
+ createdByAgentId: actor?.agentId ?? null,
+ createdByUserId: actor?.userId ?? null,
+ });
+ return await db.transaction(async (tx) => {
+ await tx
+ .update(companySecretVersions)
+ .set({ status: "current" })
+ .where(and(
+ eq(companySecretVersions.secretId, reservedSecret.id),
+ eq(companySecretVersions.version, 1),
+ ));
+ const secret = await tx
+ .update(companySecrets)
+ .set({
+ status: "active",
+ externalRef: preparedSecret.externalRef,
+ latestVersion: 1,
+ lastRotatedAt: new Date(),
+ updatedAt: new Date(),
+ })
+ .where(eq(companySecrets.id, reservedSecret.id))
+ .returning()
+ .then((rows) => rows[0]);
+ if (!secret) throw notFound("Secret not found");
+ return secret;
+ });
+ } catch (error) {
+ if (prepared) {
+ await cleanupPreparedProviderWrite({
+ provider,
+ prepared,
+ providerConfig,
+ context: providerWriteContext,
+ mode: "delete",
+ operation: "adapter_config_secret.create_rollback",
+ }).catch(() => false);
+ }
+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
+ await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
+ throw error;
+ }
+ }
+
function collectTargetIds(
bindings: Array<typeof companySecretBindings.$inferSelect>,
targetType: SecretBindingTargetType,
@@ -1817,9 +2021,11 @@ export function secretService(db: Db) {
operation: "create.prepare_rollback",
});
if (cleaned) {
+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
}
} else {
+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
}
throw error;
@@ -1862,9 +2068,11 @@ export function secretService(db: Db) {
operation: "create.rollback",
});
if (cleaned) {
+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
}
} else {
+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
}
throw error;
@@ -2159,6 +2367,7 @@ export function secretService(db: Db) {
required?: boolean;
label?: string | null;
}>,
+ options?: { replaceAll?: boolean },
) => {
const normalizedRefs: Array<{
secretId: string;
@@ -2181,7 +2390,17 @@ export function secretService(db: Db) {
const pathPrefixes = [...new Set(normalizedRefs.map((ref) => ref.configPath.split(".")[0]))];
await db.transaction(async (tx) => {
- if (pathPrefixes.length > 0) {
+ if (options?.replaceAll) {
+ await tx
+ .delete(companySecretBindings)
+ .where(
+ and(
+ eq(companySecretBindings.companyId, companyId),
+ eq(companySecretBindings.targetType, target.targetType),
+ eq(companySecretBindings.targetId, target.targetId),
+ ),
+ );
+ } else if (pathPrefixes.length > 0) {
for (const pathPrefix of pathPrefixes) {
await tx
.delete(companySecretBindings)
@@ -2351,7 +2570,7 @@ export function secretService(db: Db) {
normalizeAdapterConfigForPersistence: async (
companyId: string,
adapterConfig: Record<string, unknown>,
- opts?: { strictMode?: boolean },
+ opts?: NormalizeAdapterConfigOptions,
) => normalizeAdapterConfigForPersistenceInternal(companyId, adapterConfig, opts),
normalizeEnvBindingsForPersistence: async (
@@ -2363,7 +2582,7 @@ export function secretService(db: Db) {
normalizeHireApprovalPayloadForPersistence: async (
companyId: string,
payload: Record<string, unknown>,
- opts?: { strictMode?: boolean },
+ opts?: NormalizeAdapterConfigOptions,
) => {
const normalized = { ...payload };
const adapterConfig = asRecord(payload.adapterConfig);
@@ -2473,52 +2692,121 @@ export function secretService(db: Db) {
}));
},
+ collectMissingAdapterConfigRuntimeBindings: async (
+ companyId: string,
+ adapterConfig: Record<string, unknown>,
+ adapterType: string | null | undefined,
+ context: Omit<SecretConsumerContext, "configPath">,
+ ): Promise<MissingRuntimeBinding[]> => {
+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(adapterType);
+ const secretRefs = secretFieldKeys.flatMap((key) => {
+ const parsed = envBindingSchema.safeParse(adapterConfig[key]);
+ if (!parsed.success) return [];
+ const binding = canonicalizeBinding(parsed.data as EnvBinding);
+ if (binding.type !== "secret_ref") return [];
+ return [{ key, configPath: key, secretId: binding.secretId }];
+ });
+ if (secretRefs.length === 0) return [];
+ const bindingChecks = await Promise.all(secretRefs.map(async (entry) => ({
+ entry,
+ found: await getBinding({
+ companyId,
+ secretId: entry.secretId,
+ consumerType: context.consumerType,
+ consumerId: context.consumerId,
+ configPath: entry.configPath,
+ }),
+ })));
+ const missingEntries = bindingChecks
+ .filter((check) => !check.found)
+ .map((check) => check.entry);
+ if (missingEntries.length === 0) return [];
+
+ const secretRows = await Promise.all(
+ [...new Set(missingEntries.map((entry) => entry.secretId))].map(async (secretId) => [
+ secretId,
+ await getById(secretId).catch(() => null),
+ ] as const),
+ );
+ const secretsById = new Map(secretRows);
+
+ return missingEntries.map((entry) => ({
+ consumerType: context.consumerType,
+ consumerId: context.consumerId,
+ configPath: entry.configPath,
+ envKey: entry.key,
+ secretId: entry.secretId,
+ secretName: secretsById.get(entry.secretId)?.name ?? null,
+ }));
+ },
+
resolveAdapterConfigForRuntime: async (
companyId: string,
adapterConfig: Record<string, unknown>,
context?: Omit<SecretConsumerContext, "configPath">,
+ opts?: { adapterType?: string | null },
): Promise<{ config: Record<string, unknown>; secretKeys: Set<string>; manifest: RuntimeSecretManifestEntry[] }> => {
const resolved = { ...adapterConfig };
const secretKeys = new Set<string>();
const manifest: RuntimeSecretManifestEntry[] = [];
- if (!Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {
- return { config: resolved, secretKeys, manifest };
- }
- const record = asRecord(adapterConfig.env);
- if (!record) {
- resolved.env = {};
- return { config: resolved, secretKeys, manifest };
- }
- const env: Record<string, string> = {};
- for (const [key, rawBinding] of Object.entries(record)) {
- if (!ENV_KEY_RE.test(key)) {
- throw unprocessable(`Invalid environment variable name: ${key}`);
- }
- const parsed = envBindingSchema.safeParse(rawBinding);
- if (!parsed.success) {
- throw unprocessable(`Invalid environment binding for key: ${key}`);
- }
- const binding = canonicalizeBinding(parsed.data as EnvBinding);
- if (binding.type === "plain") {
- env[key] = binding.value;
+ if (Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {
+ const record = asRecord(adapterConfig.env);
+ if (!record) {
+ resolved.env = {};
} else {
- const secretResolution = await resolveSecretValueInternal(
- companyId,
- binding.secretId,
- binding.version,
- context
- ? {
- bindingContext: { ...context, configPath: `env.${key}` },
- accessContext: { ...context, configPath: `env.${key}` },
- }
- : undefined,
- );
- env[key] = secretResolution.value;
- manifest.push(secretResolution.manifestEntry);
- secretKeys.add(key);
+ const env: Record<string, string> = {};
+ for (const [key, rawBinding] of Object.entries(record)) {
+ if (!ENV_KEY_RE.test(key)) {
+ throw unprocessable(`Invalid environment variable name: ${key}`);
+ }
+ const parsed = envBindingSchema.safeParse(rawBinding);
+ if (!parsed.success) {
+ throw unprocessable(`Invalid environment binding for key: ${key}`);
+ }
+ const binding = canonicalizeBinding(parsed.data as EnvBinding);
+ if (binding.type === "plain") {
+ env[key] = binding.value;
+ } else {
+ const secretResolution = await resolveSecretValueInternal(
+ companyId,
+ binding.secretId,
+ binding.version,
+ context
+ ? {
+ bindingContext: { ...context, configPath: `env.${key}` },
+ accessContext: { ...context, configPath: `env.${key}` },
+ }
+ : undefined,
+ );
+ env[key] = secretResolution.value;
+ manifest.push(secretResolution.manifestEntry);
+ secretKeys.add(key);
+ }
+ }
+ resolved.env = env;
}
}
- resolved.env = env;
+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(opts?.adapterType);
+ for (const key of secretFieldKeys) {
+ const parsed = envBindingSchema.safeParse(adapterConfig[key]);
+ if (!parsed.success) continue;
+ const binding = canonicalizeBinding(parsed.data as EnvBinding);
+ if (binding.type === "plain") continue;
+ const secretResolution = await resolveSecretValueInternal(
+ companyId,
+ binding.secretId,
+ binding.version,
+ context
+ ? {
+ bindingContext: { ...context, configPath: key },
+ accessContext: { ...context, configPath: key },
+ }
+ : undefined,
+ );
+ resolved[key] = secretResolution.value;
+ manifest.push(secretResolution.manifestEntry);
+ secretKeys.add(key);
+ }
return { config: resolved, secretKeys, manifest };
},
};
diff --git a/server/src/types/express.d.ts b/server/src/types/express.d.ts
index 17f94e752e..4d04d1cc48 100644
--- a/server/src/types/express.d.ts
+++ b/server/src/types/express.d.ts
@@ -1,5 +1,7 @@
export {};
+import type { AgentApiKeyScope } from "@paperclipai/shared";
+
declare global {
namespace Express {
interface Request {
@@ -18,6 +20,7 @@ declare global {
}>;
isInstanceAdmin?: boolean;
keyId?: string;
+ keyScope?: AgentApiKeyScope;
runId?: string;
source?: "local_implicit" | "session" | "board_key" | "agent_key" | "agent_jwt" | "cloud_tenant" | "none";
};
diff --git a/tsconfig.json b/tsconfig.json
index e597c33111..e043a6a490 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -9,6 +9,8 @@
{ "path": "./packages/adapters/claude-local" },
{ "path": "./packages/adapters/codex-local" },
{ "path": "./packages/adapters/cursor-local" },
+ { "path": "./packages/adapters/hermes-gateway" },
+ { "path": "./packages/adapters/hermes" },
{ "path": "./packages/adapters/droid-local" },
{ "path": "./packages/adapters/openclaw-gateway" },
{ "path": "./packages/adapters/opencode-local" },
diff --git a/ui/package.json b/ui/package.json
index e20a5751ad..b52f0b6e32 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -46,13 +46,13 @@
"@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-utils": "workspace:*",
"@paperclipai/shared": "workspace:*",
+ "@paperclipai/hermes-paperclip-adapter": "workspace:*",
"@radix-ui/react-slot": "^1.2.4",
"@tailwindcss/typography": "^0.5.19",
"@tanstack/react-query": "^5.90.21",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
- "hermes-paperclip-adapter": "^0.3.0",
"i18next": "^26.3.1",
"lexical": "0.35.0",
"lucide-react": "^0.577.0",
diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.ts
index e710d07b9c..17a20dca8f 100644
--- a/ui/src/adapters/adapter-display-registry.ts
+++ b/ui/src/adapters/adapter-display-registry.ts
@@ -16,7 +16,6 @@ import {
Cpu,
} from "lucide-react";
import { OpenCodeLogoIcon } from "@/components/OpenCodeLogoIcon";
-import { HermesIcon } from "@/components/HermesIcon";
// ---------------------------------------------------------------------------
// Type suffix parsing
@@ -83,16 +82,22 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {
description: "Local Grok Build agent",
icon: Bot,
},
+ hermes_gateway: {
+ label: "Hermes",
+ description: "Remote Hermes API server",
+ icon: Bot,
+ hideFromVisualSelection: true,
+ },
+ hermes_local: {
+ label: "Hermes",
+ description: "Local Hermes agent",
+ icon: Bot,
+ },
opencode_local: {
label: "OpenCode",
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-gateway/index.ts b/ui/src/adapters/hermes-gateway/index.ts
new file mode 100644
index 0000000000..3aa46ec063
--- /dev/null
+++ b/ui/src/adapters/hermes-gateway/index.ts
@@ -0,0 +1,11 @@
+import type { UIAdapterModule } from "../types";
+import { parseStdoutLine as parseHermesGatewayStdoutLine } from "@paperclipai/hermes-paperclip-adapter/gateway/ui";
+import { SchemaConfigFields, buildSchemaAdapterConfig } from "../schema-config-fields";
+
+export const hermesGatewayUIAdapter: UIAdapterModule = {
+ type: "hermes_gateway",
+ label: "Hermes Gateway",
+ parseStdoutLine: parseHermesGatewayStdoutLine,
+ ConfigFields: SchemaConfigFields,
+ buildAdapterConfig: buildSchemaAdapterConfig,
+};
diff --git a/ui/src/adapters/hermes-local/config-fields.tsx b/ui/src/adapters/hermes-local/config-fields.tsx
deleted file mode 100644
index 4b80704365..0000000000
--- a/ui/src/adapters/hermes-local/config-fields.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-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.ts
index a74491748b..6eb325aeb7 100644
--- a/ui/src/adapters/hermes-local/index.ts
+++ b/ui/src/adapters/hermes-local/index.ts
@@ -1,11 +1,10 @@
import type { UIAdapterModule } from "../types";
-import { parseHermesStdoutLine } from "hermes-paperclip-adapter/ui";
-import { buildHermesConfig } from "hermes-paperclip-adapter/ui";
+import { parseHermesStdoutLine, buildHermesConfig } from "@paperclipai/hermes-paperclip-adapter/ui";
import { SchemaConfigFields } from "../schema-config-fields";
export const hermesLocalUIAdapter: UIAdapterModule = {
type: "hermes_local",
- label: "Hermes Agent",
+ label: "Hermes",
parseStdoutLine: parseHermesStdoutLine,
ConfigFields: SchemaConfigFields,
buildAdapterConfig: buildHermesConfig,
diff --git a/ui/src/adapters/registry.test.ts b/ui/src/adapters/registry.test.ts
index 6d30f6b0a6..2d36af655e 100644
--- a/ui/src/adapters/registry.test.ts
+++ b/ui/src/adapters/registry.test.ts
@@ -5,6 +5,7 @@ import {
getUIAdapter,
listUIAdapters,
registerUIAdapter,
+ syncExternalAdapters,
unregisterUIAdapter,
} from "./registry";
import { processUIAdapter } from "./process";
@@ -21,10 +22,12 @@ const externalUIAdapter: UIAdapterModule = {
describe("ui adapter registry", () => {
beforeEach(() => {
unregisterUIAdapter("external_test");
+ syncExternalAdapters([]);
});
afterEach(() => {
unregisterUIAdapter("external_test");
+ syncExternalAdapters([]);
});
it("registers adapters for lookup and listing", () => {
@@ -48,4 +51,30 @@ describe("ui adapter registry", () => {
// But it uses the schema-based config fields for external adapter forms.
expect(fallback.ConfigFields).toBe(SchemaConfigFields);
});
+
+ it("restores built-in Hermes adapters when external overrides are paused or removed", () => {
+ for (const type of ["hermes_local", "hermes_gateway"]) {
+ const builtin = getUIAdapter(type);
+
+ syncExternalAdapters([{ type, label: "External Hermes" }]);
+
+ const overridden = getUIAdapter(type);
+ expect(overridden).not.toBe(builtin);
+ expect(overridden.type).toBe(type);
+ expect(overridden.label).toBe("External Hermes");
+ expect(overridden.ConfigFields).toBe(builtin.ConfigFields);
+ expect(overridden.buildAdapterConfig).toBe(builtin.buildAdapterConfig);
+
+ syncExternalAdapters([{ type, label: "External Hermes", overrideDisabled: true }]);
+
+ expect(getUIAdapter(type)).toBe(builtin);
+
+ syncExternalAdapters([{ type, label: "External Hermes" }]);
+ expect(getUIAdapter(type)).not.toBe(builtin);
+
+ syncExternalAdapters([]);
+
+ expect(getUIAdapter(type)).toBe(builtin);
+ }
+ });
});
diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.ts
index 9b2476d3c8..d698e86b31 100644
--- a/ui/src/adapters/registry.ts
+++ b/ui/src/adapters/registry.ts
@@ -6,10 +6,11 @@ import { cursorCloudUIAdapter } from "./cursor-cloud";
import { cursorLocalUIAdapter } from "./cursor";
import { geminiLocalUIAdapter } from "./gemini-local";
import { grokLocalUIAdapter } from "./grok-local";
+import { hermesGatewayUIAdapter } from "./hermes-gateway";
+import { hermesLocalUIAdapter } from "./hermes-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, invalidateDynamicParser, setDynamicParserResultNotifier } from "./dynamic-loader";
@@ -58,6 +59,7 @@ function registerBuiltInUIAdapters() {
cursorCloudUIAdapter,
geminiLocalUIAdapter,
grokLocalUIAdapter,
+ hermesGatewayUIAdapter,
hermesLocalUIAdapter,
openCodeLocalUIAdapter,
piLocalUIAdapter,
diff --git a/ui/src/adapters/use-adapter-capabilities.ts b/ui/src/adapters/use-adapter-capabilities.ts
index 89f2c2b6c4..14e466e67a 100644
--- a/ui/src/adapters/use-adapter-capabilities.ts
+++ b/ui/src/adapters/use-adapter-capabilities.ts
@@ -24,7 +24,6 @@ const KNOWN_DEFAULTS: Record<string, AdapterCapabilities> = {
grok_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },
opencode_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },
pi_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },
- hermes_local: { supportsInstructionsBundle: false, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: false },
openclaw_gateway: ALL_FALSE,
};
diff --git a/ui/src/api/agents.ts b/ui/src/api/agents.ts
index fc29bac98e..45e134c3cd 100644
--- a/ui/src/api/agents.ts
+++ b/ui/src/api/agents.ts
@@ -15,6 +15,7 @@ import type {
Approval,
AgentConfigRevision,
ClearAgentErrorResponse,
+ AgentApiKeyScope,
} from "@paperclipai/shared";
import type {
AdapterModelProfileDefinition,
@@ -26,6 +27,7 @@ import { ApiError, api } from "./client";
export interface AgentKey {
id: string;
name: string;
+ scope: AgentApiKeyScope;
createdAt: Date;
revokedAt: Date | null;
}
@@ -178,8 +180,8 @@ export const agentsApi = {
api.get<AgentSkillSnapshot>(agentPath(id, companyId, "/skills")),
syncSkills: (id: string, desiredSkills: Array<string | AgentDesiredSkillEntry>, companyId?: string) =>
api.post<AgentSkillSnapshot>(agentPath(id, companyId, "/skills/sync"), { desiredSkills }),
- createKey: (id: string, name: string, companyId?: string) =>
- api.post<AgentKeyCreated>(agentPath(id, companyId, "/keys"), { name }),
+ createKey: (id: string, name: string, companyId?: string, scope?: AgentApiKeyScope) =>
+ api.post<AgentKeyCreated>(agentPath(id, companyId, "/keys"), { name, ...(scope ? { scope } : {}) }),
revokeKey: (agentId: string, keyId: string, companyId?: string) =>
api.delete<{ ok: true }>(agentPath(agentId, companyId, `/keys/${encodeURIComponent(keyId)}`)),
runtimeState: (id: string, companyId?: string) =>
diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsx
index 06f12521e9..1dafb6a6dc 100644
--- a/ui/src/components/AgentConfigForm.tsx
+++ b/ui/src/components/AgentConfigForm.tsx
@@ -436,8 +436,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
const [refreshModelsError, setRefreshModelsError] = useState<string | null>(null);
const [refreshingModels, setRefreshingModels] = useState(false);
const rawModels = fetchedModels ?? externalModels ?? [];
- const adapterCommandField =
- adapterType === "hermes_local" ? "hermesCommand" : "command";
+ const adapterCommandField = "command";
const acpxAgent =
adapterType === "acpx_local"
? isCreate
@@ -529,17 +528,6 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
if (adapterConfigPatch) {
Object.assign(next, adapterConfigPatch);
}
- if (adapterType === "hermes_local") {
- const hermesCommand =
- typeof next.hermesCommand === "string" && next.hermesCommand.length > 0
- ? next.hermesCommand
- : typeof next.command === "string" && next.command.length > 0
- ? next.command
- : undefined;
- if (hermesCommand) {
- next.hermesCommand = hermesCommand;
- }
- }
return next;
}
@@ -1201,9 +1189,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
"adapterConfig",
adapterCommandField,
String(
- (adapterType === "hermes_local"
- ? config.hermesCommand ?? config.command
- : config.command) ?? "",
+ config.command ?? "",
),
)
}
diff --git a/ui/src/components/HermesIcon.tsx b/ui/src/components/HermesIcon.tsx
deleted file mode 100644
index fb02623a22..0000000000
--- a/ui/src/components/HermesIcon.tsx
+++ /dev/null
@@ -1,43 +0,0 @@
-import { cn } from "../lib/utils";
-
-interface HermesIconProps {
- className?: string;
-}
-
-/**
- * Hermes caduceus icon — winged staff with two intertwined serpents.
- * Replaces the generic Zap icon for the hermes_local adapter type.
- *
- * ⚕️ inspired but as the proper caduceus (Hermes' symbol): staff + two snakes + wings.
- */
-export function HermesIcon({ className }: HermesIconProps) {
- return (
- <svg
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="1.5"
- strokeLinecap="round"
- strokeLinejoin="round"
- className={cn(className)}
- >
- {/* Central staff */}
- <line x1="12" y1="6" x2="12" y2="23" />
- {/* Left serpent curves */}
- <path d="M12 8 C10 9 9.5 11 10.5 13 C11.5 15 10 17 12 18" />
- {/* Right serpent curves */}
- <path d="M12 8 C14 9 14.5 11 13.5 13 C12.5 15 14 17 12 18" />
- {/* Snake heads facing outward */}
- <circle cx="10" cy="8" r="0.8" fill="currentColor" stroke="none" />
- <circle cx="14" cy="8" r="0.8" fill="currentColor" stroke="none" />
- {/* Wings at top of staff */}
- <path d="M12 6 L8 3 L6 5 L9 6" strokeWidth="1.2" />
- <path d="M12 6 L16 3 L18 5 L15 6" strokeWidth="1.2" />
- {/* Wing feather details */}
- <line x1="7.5" y1="4" x2="7" y2="5.2" strokeWidth="1" />
- <line x1="16.5" y1="4" x2="17" y2="5.2" strokeWidth="1" />
- {/* Staff sphere at top */}
- <circle cx="12" cy="6.5" r="1.2" />
- </svg>
- );
-}
diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsx
index f7c6eaac08..b68a7de9bb 100644
--- a/ui/src/components/OnboardingWizard.tsx
+++ b/ui/src/components/OnboardingWizard.tsx
@@ -271,7 +271,6 @@ export function OnboardingWizard() {
adapterType === "claude_local" ||
adapterType === "codex_local" ||
adapterType === "gemini_local" ||
- adapterType === "hermes_local" ||
adapterType === "opencode_local" ||
adapterType === "pi_local" ||
adapterType === "cursor";
@@ -298,7 +297,6 @@ export function OnboardingWizard() {
claude_local: "claude",
codex_local: "codex",
gemini_local: "gemini",
- hermes_local: "hermes",
pi_local: "pi",
cursor: "agent",
opencode_local: "opencode",
diff --git a/ui/src/lib/agent-onboarding-prompt.test.ts b/ui/src/lib/agent-onboarding-prompt.test.ts
new file mode 100644
index 0000000000..1166fce2ad
--- /dev/null
+++ b/ui/src/lib/agent-onboarding-prompt.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { buildAgentOnboardingPrompt } from "./agent-onboarding-prompt";
+
+describe("buildAgentOnboardingPrompt", () => {
+ it("includes Hermes Gateway setup guidance for external agents", () => {
+ const prompt = buildAgentOnboardingPrompt({
+ onboardingTextUrl: "http://localhost:3100/api/invites/token-123/onboarding.txt",
+ connectionCandidates: ["http://192.168.1.10:3100"],
+ });
+
+ expect(prompt).toContain('adapterType: "hermes_gateway"');
+ expect(prompt).toContain("API_SERVER_ENABLED=true");
+ expect(prompt).toContain("API_SERVER_KEY");
+ expect(prompt).toContain("hermes gateway run --replace --accept-hooks");
+ expect(prompt).toContain("default Hermes API server port is `8642`");
+ expect(prompt).toContain("agentDefaultsPayload.apiBaseUrl");
+ expect(prompt).toContain("agentDefaultsPayload.paperclipApiUrl");
+ expect(prompt).toContain("http://127.0.0.1:8642");
+ expect(prompt).toContain("http://<private-ip>:8642");
+ expect(prompt).toContain("http://<tailnet-host>:8642");
+ expect(prompt).toContain("http://host.docker.internal:8642");
+ expect(prompt).toContain("https://hermes-gateway.example");
+ expect(prompt).toContain("`hermes_local` runs Hermes on the Paperclip host");
+ expect(prompt).toContain("Hermes-originated Paperclip API calls");
+ });
+});
diff --git a/ui/src/lib/agent-onboarding-prompt.ts b/ui/src/lib/agent-onboarding-prompt.ts
index bac83f4600..3da1b65967 100644
--- a/ui/src/lib/agent-onboarding-prompt.ts
+++ b/ui/src/lib/agent-onboarding-prompt.ts
@@ -55,6 +55,13 @@ Join flow:
OpenClaw Gateway note:
If you are an OpenClaw Gateway agent, use \`adapterType: "openclaw_gateway"\`, set \`agentDefaultsPayload.url\` to your \`ws://\` or \`wss://\` gateway URL, and include \`agentDefaultsPayload.headers["x-openclaw-token"]\` with your gateway token. Do not use \`/v1/responses\` or \`/hooks/*\` in that join flow.
+Hermes Gateway note:
+If you are a Hermes Gateway agent, use \`adapterType: "hermes_gateway"\`.
+- Start Hermes with \`API_SERVER_ENABLED=true\` and \`API_SERVER_KEY=<random-gateway-key>\`, then run \`hermes gateway run --replace --accept-hooks\`. The default Hermes API server port is \`8642\`.
+- Set \`agentDefaultsPayload.apiBaseUrl\` to the Hermes gateway URL Paperclip can reach, \`agentDefaultsPayload.apiKey\` to the same value as \`API_SERVER_KEY\`, and \`agentDefaultsPayload.paperclipApiUrl\` to the Paperclip base URL Hermes can reach.
+- \`apiBaseUrl\` examples: local loopback \`http://127.0.0.1:8642\`; LAN/private network \`http://<private-ip>:8642\`; private overlay \`http://<tailnet-host>:8642\`; Docker \`http://host.docker.internal:8642\`; reverse proxy/TLS \`https://hermes-gateway.example\`.
+- Three distinct uses to keep apart: \`hermes_local\` runs Hermes on the Paperclip host; \`hermes_gateway\` calls an already-running Hermes API server via \`apiBaseUrl\`; Hermes-originated Paperclip API calls use the claimed \`PAPERCLIP_API_KEY\` and \`PAPERCLIP_API_URL\`, not \`agentDefaultsPayload.apiBaseUrl\`.
+
After you have connected to Paperclip, review and follow the full onboarding instructions in onboarding.txt.
`;
}