[Feature]: Support Hermes Agent through local ACP (no gateway or T3 Work)

[DiscoStew6082]

Before submitting

• I searched existing issues and pull requests. Issue #4412 is related, but it was closed as not planned after a vague request; this proposal defines a narrower local-ACP use case, boundaries, and validation evidence.
• I am describing a concrete problem and use case.

Area

apps/server

Problem or use case

I want to use T3 Code as the frontend for the local Hermes Agent runtime, replacing the Hermes Desktop frontend without replacing Hermes itself. Hermes Desktop has been unreliable in my setup, while I still want the Hermes agent harness and its state.

Using T3's Codex or another model provider directly is not equivalent. Hermes remains the agent harness that owns its identity, provider authentication and routing, model inventory, memory, skills, tools, and state. T3 would own the project/thread UI, approval UI, and ACP session lifecycle.

Hermes already supports this host/agent split through stdio ACP. Its documentation describes ACP as the path for keeping Hermes' identity, provider setup, memory, skills, and tools while another application owns the conversation transport. The supported launch command is hermes acp.

This request is specifically not for:

• Hermes Desktop integration
• the Hermes gateway
• Telegram, Discord, or other Hermes transports
• T3 Work, session import, cron management, or a second general-purpose workspace

Proposed solution

Let a T3 server run an installed Hermes CLI as a local ACP provider:

T3 web / desktop / mobile client
             |
        T3 server
             |
       ACP over stdio
             |
       hermes acp

The smallest complete behavior would be:

1. Add or configure a provider instance that launches hermes acp on the machine running the T3 server.
2. Preserve normal T3 thread behavior: start, prompt/steer, streamed output, tool activity, permission requests, cancellation, and process cleanup.
3. Discover Hermes' authenticated model catalog from ACP, show the current model, and support in-session session/set_model using Hermes' provider-qualified model IDs.
4. Surface Hermes' reasoning option when ACP advertises it, and apply it through the advertised session configuration option.
5. Reuse Hermes' existing configuration and credentials, including Hermes' openai-codex OAuth route for a ChatGPT/Codex subscription. Do not ask T3 to own or copy those credentials.
6. Support an explicit Hermes binary path and, if the chosen provider architecture allows it, HERMES_HOME, profile, launch arguments, and provider-instance environment settings.

I am not proposing that an unreviewed large implementation be merged as-is. I would like maintainer direction on whether this should be:

• a featured entry in the generic ACP provider path proposed by #6071, with the Hermes-specific capability handling above;
• a small first-class Hermes driver; or
• deferred until orchestration V2 in #2829.

Why this matters

This lets users who depend on Hermes' agent behavior replace an unreliable or unwanted desktop frontend without giving up Hermes' durable memory, skills, tools, model routing, local-model access, or provider authentication.

Because the integration is server-side ACP, the same provider can be controlled through T3's web, desktop, and mobile clients, including remote clients, without coupling T3 to Hermes Desktop or the Hermes gateway.

It also gives a concrete answer to the concern raised on #4412 that users could configure the same underlying model provider directly in T3: the value being preserved is the Hermes harness and state, not merely access to OpenAI or another model endpoint.

Smallest useful scope

Chat sessions through the local hermes acp subprocess only:

• local process launch and health reporting;
• ACP session lifecycle and event streaming;
• approvals and cancellation;
• model discovery/switching and advertised reasoning controls;
• Hermes-owned auth/configuration;
• provider availability across T3 clients through the existing server architecture.

Out of scope for the first version:

• Hermes Desktop and gateway functionality;
• messaging transports, session import, cron, and T3 Work;
• T3-owned Hermes credential management;
• automatic Hermes updates;
• provider-side rollback unless Hermes ACP advertises it;
• Hermes-backed auxiliary title, branch, commit, or change-request generation until Hermes offers a guaranteed no-tools/non-interactive mode. Hermes one-shot mode currently loads tools and bypasses approvals, so silently using it for background generation would be unsafe.

Alternatives considered

• Use T3's Codex provider directly. This reuses the ChatGPT subscription but loses Hermes memory, skills, tools, configuration, and multi-provider routing.
• Keep using Hermes Desktop. This does not solve the frontend reliability/replacement use case.
• Use the Hermes gateway. This adds a transport and lifecycle that are not needed for a local coding-agent frontend.
• Merge one of the existing large PRs. Prior attempts mixed Hermes with Pi/OpenClaw or with the much broader T3 Work/gateway product. The repository's contribution guidance asks for issue-first, narrow scope.
• Use generic ACP only. This is probably the smallest long-term architecture, but the current proposal in feat(providers): add ACP registry for Gemini, Pi, and more #6071 has open correctness/security review findings and does not yet expose Hermes' advertised reasoning configuration. It should be evaluated as the likely architecture, not treated as already-complete Hermes support.

Risks or tradeoffs

• Architecture churn: previous Hermes provider PRs were closed because orchestration V2 replaces the current adapter contract. Maintainer direction is needed before more implementation work.
• Maintenance surface: a bespoke driver duplicates a large amount of ACP adapter behavior; a generic ACP driver has less permanent surface but must still preserve agent-specific protocol semantics.
• Permissions: Hermes ACP exposes terminal and code-execution tools. T3 must faithfully mediate the option IDs Hermes advertises and must not synthesize unsupported approval outcomes.
• Process lifecycle: notification drains must live for the ACP session, and stop/replacement paths must not leak child processes.
• Model identity: Hermes advertises IDs such as openai-codex:gpt-5.6-sol; any T3 display normalization must round-trip back to the exact ACP ID before session/set_model.
• Auxiliary generation: background title/branch/commit/PR generation must stay disabled for Hermes until there is a genuinely tool-free invocation path.

Examples or references

• Hermes ACP host integration documentation
• T3 contribution guidance
• Prior broad Hermes request #4412
• Prior Hermes + Pi ACP PR #2748, closed in favor of orchestration V2 / a generic ACP registry
• Prior Hermes provider PR #2965
• Hermes gateway PR #4678 and broader T3 Work PR #4604, both outside this request's scope
• Open multi-provider PR #5505, currently size:XXL and merge-conflicting
• Open generic ACP registry PR #6071
• Focused proof branch at commit 92ecd9039

Proof-of-feasibility validation

Validated locally on macOS with Hermes Agent v0.20.0 (2026.8.3):

• hermes acp --check returned Hermes ACP check OK.
• A real ACP handshake advertised 57 models and selected openai-codex:gpt-5.6-sol from the existing Hermes configuration.
• A real T3 → Hermes ACP → Codex OAuth turn returned the expected HERMES_T3_OK response.
• In-session switching to lmstudio:qwen3.5-9b-mtp succeeded without sending an extra prompt.
• 56 focused tests across 9 test files passed.
• Changed-file lint, formatting, git diff --check, and affected package typechecks passed.
• The production desktop build/package, Electron smoke test, and strict macOS code-sign verification passed.
• Independent review verified fixes for four Hermes-specific findings from feat(provider): add OpenClaw, Hermes, and PiAgent harnesses with reasoning controls #5505: ACP notification lifetime, permission option IDs, model-ID round-tripping, and duplicate prompt-history settlement.
• Independent follow-up review found no remaining blocker in the focused implementation. It also confirmed auxiliary one-shot generation is deliberately disabled.

The proof branch is evidence that the narrow integration works; it is not a request to bypass the issue-first architecture decision.

Contribution

• I would be open to helping implement this after maintainers choose the provider architecture and acceptable scope.

Questions for maintainers

1. Is local Hermes ACP support within T3 Code's intended provider scope if gateway/Desktop/T3 Work features are excluded?
2. Should this land through the generic ACP registry, as a dedicated Hermes driver, or only after orchestration V2?
3. If the generic path is preferred, are model-ID round-tripping, advertised reasoning configuration, approval mediation, and safe auxiliary-generation behavior the right Hermes acceptance criteria?