Nextclaw HTTP Agent Runtime Integration

Integrating HTTP Agent Runtime

Overview

Use this skill to connect an external agent runtime into NextClaw through the generic narp-http path.

Default architecture:

• Keep NextClaw core generic.
• Reuse the existing builtin narp-http runtime provider and HTTP client.
• Treat Hermes or any other backend as an external runtime behind an HTTP adapter.
• End with a real selectable session type in NextClaw, not just a design note.

Read these first when the task is non-trivial:

• docs/VISION.md
• docs/plans/2026-04-15-http-backed-agent-runtime-design.md
• docs/logs/v0.16.28-http-backed-agent-runtime-mvp/README.md

When To Use

Use this skill when any of these are true:

• The user wants Hermes to appear as a NextClaw session type.
• The user wants to connect an external agent runtime by HTTP address.
• The user wants “just configure it” runtime onboarding instead of hard-coding a new runtime.
• The user wants the AI to debug why an HTTP runtime is not ready, not visible, not streaming, or returning errors.

Do not use this skill for:

• MCP server integration
• ordinary tool/plugin integration that does not create an agent runtime
• adding a brand-new non-HTTP runtime family

Core Rule

Prefer this split unless the user explicitly asks for something else:

• NextClaw owns the generic narp-http provider and session-type experience.
• The external runtime owns its private protocol.
• An adapter server translates the private protocol into the shared HTTP/SSE contract.

Do not create a Hermes-specific runtime kind if narp-http can solve it.

First Decision

Classify the task into exactly one path:

Path A: Existing HTTP runtime is already ready

Choose this when the target already exposes the expected endpoints:

• POST /send
• GET /stream?sessionId=...
• POST /abort
• optional GET /health

In this path, the AI should mostly do configuration and verification.

Path B: Adapter server is still required

Choose this when the target runtime only exposes:

• private SDK calls
• OpenAI-compatible APIs
• CLI commands
• ACP or another private wire protocol

In this path, the AI should first add or update an adapter server, then wire NextClaw to the adapter URL.

Files To Reuse

Start from the existing implementation before inventing new structure:

• packages/nextclaw-ncp-runtime-http-client
• packages/nextclaw-ncp-runtime-adapter-hermes-http
• packages/nextclaw/src/cli/commands/ncp/runtime/create-ui-ncp-agent.http-runtime.test.ts
• packages/nextclaw/src/cli/commands/ncp/runtime/create-ui-ncp-agent.hermes-http-runtime.test.ts

Important current boundary:

• narp-http is already the generic runtime kind.
• Hermes is already implemented as an external adapter, not as a core runtime kind.
• Current MVP is configuration-driven for one plugin entry, not yet a full multi-instance runtime catalog.

Path A Workflow

When the external runtime already serves the HTTP contract:

1. Add or update an agents.runtimes.entries.<id> entry with type: "narp-http".
2. Point config.baseUrl at the external runtime or adapter.
3. Set label to the user-facing runtime name, for example Hermes.
4. Optionally set:
   • basePath
   • healthcheckUrl
   • recommendedModel
   • supportedModels
   • headers
5. Verify that the session type becomes visible and ready.
6. Run a real message smoke, not only static config inspection.

Example config:

{
  "agents": {
    "runtimes": {
      "entries": {
        "hermes": {
          "enabled": true,
          "label": "Hermes",
          "type": "narp-http",
          "config": {
            "baseUrl": "http://127.0.0.1:18765",
            "basePath": "/ncp/agent",
            "healthcheckUrl": "http://127.0.0.1:18765/health",
            "recommendedModel": "hermes-agent"
          }
        }
      }
    }
  }
}

Path B Workflow

When an adapter is needed:

1. Keep NextClaw side generic.
2. Add or update a standalone adapter package under packages/extensions/.
3. Make the adapter expose the shared HTTP/SSE contract.
4. Keep target-runtime-specific translation inside the adapter package.
5. Only after the adapter is runnable, point narp-http config at its baseUrl.

For Hermes, prefer the existing adapter package instead of rebuilding another integration path.