Skip to content

Commit 2a9392c

Browse files
johnnyfishjohnnyfish
committed
feat: add Hermes gateway support with skill, plugin, and Docker config
1 parent 68cf02a commit 2a9392c

6 files changed

Lines changed: 412 additions & 11 deletions

File tree

‎cmd/onecli/plugin_gateway_hermes.py‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
"""OneCLI Gateway plugin for Hermes.
2+
3+
Intercepts tool results containing auth errors (NOT_AUTHENTICATED, missing
4+
token, etc.) and appends gateway recovery instructions so the agent creates
5+
credential stubs instead of following manual OAuth/API-key setup flows.
6+
"""
7+
8+
import json
9+
import logging
10+
import os
11+
from typing import Any, Optional
12+
13+
log = logging.getLogger("onecli-gateway")
14+
15+
_AUTH_PATTERNS = [
16+
"not_authenticated",
17+
"no token at",
18+
"missing token",
19+
"oauth_client_disabled",
20+
"token_revoked",
21+
"token_invalid",
22+
"token_corrupt",
23+
"credentials not found",
24+
"authentication required",
25+
"not authenticated",
26+
]
27+
28+
_RECOVERY_HINT = """
29+
30+
=== OneCLI Gateway: Auth Error Recovery ===
31+
32+
This auth error is handled by the OneCLI gateway proxy.
33+
Do NOT follow OAuth setup, API key, or App Password instructions.
34+
35+
STEP 1 — Create a stub credential file at the path mentioned in the error.
36+
37+
For Google tokens (google_token.json):
38+
echo '{"type":"authorized_user","access_token":"onecli-managed","refresh_token":"onecli-managed","client_id":"onecli-managed","client_secret":"onecli-managed","token_uri":"https://oauth2.googleapis.com/token","expiry":"2099-01-01T00:00:00+00:00"}' > /root/.hermes/google_token.json && chmod 600 /root/.hermes/google_token.json
39+
40+
For other credentials:
41+
echo '{"api_key":"onecli-managed"}' > <path> && chmod 600 <path>
42+
43+
STEP 2 — Retry the failed operation. The gateway replaces "onecli-managed"
44+
placeholders with real credentials at the network level.
45+
46+
STEP 3 — If the retry returns app_not_connected, show the user the
47+
connect_url from the error response so they can connect the service.
48+
49+
=== End OneCLI Gateway ==="""
50+
51+
52+
def _is_gateway_active():
53+
proxy = os.environ.get("HTTPS_PROXY", "") + os.environ.get("https_proxy", "")
54+
active = "aoc_" in proxy or os.environ.get("ONECLI_GATEWAY") == "true"
55+
return active
56+
57+
58+
def _result_to_str(result):
59+
"""Convert result to a searchable string regardless of type."""
60+
if isinstance(result, str):
61+
return result
62+
if isinstance(result, dict):
63+
return json.dumps(result, default=str)
64+
return str(result) if result is not None else ""
65+
66+
67+
def _has_auth_error(text):
68+
lower = text.lower()
69+
return any(p in lower for p in _AUTH_PATTERNS)
70+
71+
72+
def _on_transform_tool_result(
73+
tool_name: str = "",
74+
args: Any = None,
75+
result: Any = None,
76+
**_: Any,
77+
) -> Optional[str]:
78+
if not _is_gateway_active():
79+
return None
80+
text = _result_to_str(result)
81+
if not _has_auth_error(text):
82+
return None
83+
log.warning("OneCLI gateway intercepted auth error in %s, injecting recovery hint", tool_name)
84+
if isinstance(result, str):
85+
return result + _RECOVERY_HINT
86+
return text + _RECOVERY_HINT
87+
88+
89+
def register(ctx) -> None:
90+
log.info("OneCLI gateway plugin registered (transform_tool_result)")
91+
ctx.register_hook("transform_tool_result", _on_transform_tool_result)

‎cmd/onecli/plugin_gateway_hermes.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
name: onecli-gateway
2+
version: "0.7.0"
3+
description: "Intercepts auth errors and injects OneCLI gateway recovery instructions"
4+
author: "OneCLI"
5+
hooks:
6+
- transform_tool_result

‎cmd/onecli/run.go‎

Lines changed: 158 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ var gatewaySkillFallback string
2626
//go:embed hook_gateway_detect.sh
2727
var gatewayDetectHook string
2828

29+
//go:embed plugin_gateway_hermes.yaml
30+
var hermesPluginManifest string
31+
32+
//go:embed plugin_gateway_hermes.py
33+
var hermesPluginHandler string
34+
2935
// RunCmd is `onecli run -- <command> [args...]`.
3036
type RunCmd struct {
3137
Project string `optional:"" short:"p" help:"Project slug."`
@@ -113,15 +119,18 @@ func (c *RunCmd) Run(out *output.Writer) error {
113119
// For known agents, fetch the agent-specific skill variant and install
114120
// to the agent's skill directory. Also optionally register a hook.
115121
agentFramework := strings.ToLower(filepath.Base(c.Args[0]))
116-
if name, dir, cfgDir, noHook, _, nativeProxy, ok := agentSkillDir(c.Args[0]); ok {
122+
if name, dir, cfgDir, noHook, plugin, nativeProxy, ok := agentSkillDir(c.Args[0]); ok {
117123
skillContent := gatewaySkillFallback
118-
if fetched, err := client.GetGatewaySkill(newContext()); err == nil && fetched != "" {
124+
if fetched, err := client.GetGatewaySkill(newContext(), agentFramework); err == nil && fetched != "" {
119125
skillContent = fetched
120126
}
121127
maybeInstallGatewaySkill(out, name, dir, skillContent)
122128
if !noHook {
123129
maybeInstallGatewayHook(out, name, dir)
124130
}
131+
if plugin {
132+
maybeInstallGatewayPlugin(out, name, dir)
133+
}
125134

126135
// Electron-based agents (e.g. Cursor) ignore embedded user:pass in
127136
// HTTPS_PROXY and show a native auth dialog. Inject proxy credentials
@@ -142,7 +151,7 @@ func (c *RunCmd) Run(out *output.Writer) error {
142151
// Unknown agent — install the skill to ~/.onecli/skills/ so the
143152
// framework can discover it via ONECLI_GATEWAY_SKILL_PATH.
144153
skillContent := gatewaySkillFallback
145-
if fetched, err := client.GetGatewaySkill(newContext()); err == nil && fetched != "" {
154+
if fetched, err := client.GetGatewaySkill(newContext(), agentFramework); err == nil && fetched != "" {
146155
skillContent = fetched
147156
}
148157
if p := installUniversalGatewaySkill(out, skillContent); p != "" {
@@ -502,6 +511,152 @@ func maybeInjectNativeProxyConfig(out *output.Writer, agentName, configRelDir st
502511
}
503512
}
504513

514+
// maybeInstallGatewayPlugin installs a transform_tool_result plugin that
515+
// intercepts auth errors and appends gateway recovery instructions.
516+
// It also enables the plugin in the agent's config.yaml.
517+
func maybeInstallGatewayPlugin(out *output.Writer, agentName, baseDir string) {
518+
home, err := os.UserHomeDir()
519+
if err != nil {
520+
return
521+
}
522+
pluginDir := filepath.Join(home, baseDir, "plugins", "onecli-gateway")
523+
524+
// Write plugin.yaml.
525+
manifestPath := filepath.Join(pluginDir, "plugin.yaml")
526+
existingManifest, _ := os.ReadFile(manifestPath)
527+
if !bytes.Equal(existingManifest, []byte(hermesPluginManifest)) {
528+
if err := os.MkdirAll(pluginDir, 0o750); err != nil {
529+
out.Stderr(fmt.Sprintf("onecli: warning: could not create plugin directory: %v", err))
530+
return
531+
}
532+
if err := os.WriteFile(manifestPath, []byte(hermesPluginManifest), 0o600); err != nil {
533+
out.Stderr(fmt.Sprintf("onecli: warning: could not write plugin manifest: %v", err))
534+
return
535+
}
536+
}
537+
538+
// Write __init__.py.
539+
handlerPath := filepath.Join(pluginDir, "__init__.py")
540+
existingHandler, _ := os.ReadFile(handlerPath)
541+
if !bytes.Equal(existingHandler, []byte(hermesPluginHandler)) {
542+
if err := os.WriteFile(handlerPath, []byte(hermesPluginHandler), 0o600); err != nil {
543+
out.Stderr(fmt.Sprintf("onecli: warning: could not write plugin handler: %v", err))
544+
return
545+
}
546+
out.Stderr(fmt.Sprintf("onecli: installed gateway plugin for %s.", agentName))
547+
}
548+
549+
// Enable the plugin in config.yaml if not already listed.
550+
configPath := filepath.Join(home, baseDir, "config.yaml")
551+
configData, _ := os.ReadFile(configPath)
552+
configStr := string(configData)
553+
554+
if !strings.Contains(configStr, "onecli-gateway") {
555+
// Append a plugins.enabled entry. If the file has no plugins section,
556+
// add one. If it does, append to the enabled list.
557+
if strings.Contains(configStr, "plugins:") {
558+
if strings.Contains(configStr, "enabled:") {
559+
// Add to existing enabled list — insert after "enabled:" line.
560+
configStr = strings.Replace(configStr, "enabled:", "enabled:\n - onecli-gateway", 1)
561+
} else {
562+
configStr = strings.Replace(configStr, "plugins:", "plugins:\n enabled:\n - onecli-gateway", 1)
563+
}
564+
} else {
565+
if configStr != "" && !strings.HasSuffix(configStr, "\n") {
566+
configStr += "\n"
567+
}
568+
configStr += "\nplugins:\n enabled:\n - onecli-gateway\n"
569+
}
570+
if err := os.WriteFile(configPath, []byte(configStr), 0o600); err != nil {
571+
out.Stderr(fmt.Sprintf("onecli: warning: could not enable plugin in config.yaml: %v", err))
572+
return
573+
}
574+
out.Stderr(fmt.Sprintf("onecli: enabled gateway plugin in %s config.", agentName))
575+
}
576+
577+
// Ensure proxy URL env vars are forwarded into Docker containers.
578+
// CA cert file-path vars are NOT forwarded — host paths don't exist
579+
// in the container. Instead we mount the CA bundle and set docker_env.
580+
proxyEnvs := []string{"HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy", "NO_PROXY", "no_proxy", "ONECLI_GATEWAY"}
581+
configData, _ = os.ReadFile(configPath)
582+
configStr = string(configData)
583+
changed := false
584+
for _, env := range proxyEnvs {
585+
if !strings.Contains(configStr, env) {
586+
configStr = strings.Replace(configStr, "docker_forward_env: []", "docker_forward_env:\n - "+env, 1)
587+
if !strings.Contains(configStr, env) {
588+
configStr = strings.Replace(configStr, "docker_forward_env:", "docker_forward_env:\n - "+env, 1)
589+
}
590+
changed = true
591+
}
592+
}
593+
594+
// Mount the CA bundle into the container and set CA env vars to the
595+
// container-side path so TLS works through the gateway proxy.
596+
caPath := filepath.Join(home, ".onecli", "ca-bundle.pem")
597+
const containerCAPath = "/etc/ssl/certs/onecli-ca-bundle.pem"
598+
volumeEntry := caPath + ":" + containerCAPath + ":ro"
599+
if !strings.Contains(configStr, "onecli-ca-bundle") {
600+
configStr = strings.Replace(configStr, "docker_volumes: []", "docker_volumes:\n - "+volumeEntry, 1)
601+
if !strings.Contains(configStr, "onecli-ca-bundle") {
602+
configStr = strings.Replace(configStr, "docker_volumes:", "docker_volumes:\n - "+volumeEntry, 1)
603+
}
604+
changed = true
605+
}
606+
607+
// Set CA env vars and proxy URLs inside Docker via docker_env.
608+
// docker_forward_env doesn't reliably forward to persistent containers,
609+
// so we inject the actual values directly.
610+
dockerEnvs := map[string]string{
611+
"SSL_CERT_FILE": containerCAPath,
612+
"NODE_EXTRA_CA_CERTS": containerCAPath,
613+
"REQUESTS_CA_BUNDLE": containerCAPath,
614+
"CURL_CA_BUNDLE": containerCAPath,
615+
"ONECLI_GATEWAY": "true",
616+
}
617+
for _, k := range []string{"HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy"} {
618+
if v := os.Getenv(k); v != "" {
619+
dockerEnvs[k] = v
620+
}
621+
}
622+
caEnvs := dockerEnvs
623+
for k, v := range caEnvs {
624+
entry := k + ": " + v
625+
if !strings.Contains(configStr, entry) {
626+
configStr = strings.Replace(configStr, "docker_env: {}", "docker_env:\n "+entry, 1)
627+
if !strings.Contains(configStr, entry) {
628+
configStr = strings.Replace(configStr, "docker_env:", "docker_env:\n "+entry, 1)
629+
}
630+
changed = true
631+
}
632+
}
633+
634+
if changed {
635+
if err := os.WriteFile(configPath, []byte(configStr), 0o600); err != nil {
636+
out.Stderr(fmt.Sprintf("onecli: warning: could not update Docker config: %v", err))
637+
} else {
638+
out.Stderr(fmt.Sprintf("onecli: configured Docker env and CA cert for %s.", agentName))
639+
removeStaleAgentContainers(out, agentName)
640+
}
641+
}
642+
}
643+
644+
// removeStaleAgentContainers removes persistent Docker containers that were
645+
// created before the config changed. The agent will recreate them with the
646+
// updated env vars and volume mounts on the next tool execution.
647+
func removeStaleAgentContainers(out *output.Writer, agentName string) {
648+
prefix := strings.ToLower(strings.ReplaceAll(agentName, " ", "-"))
649+
ids, err := exec.Command("docker", "ps", "-aq", "--filter", "name="+prefix).Output()
650+
if err != nil || len(bytes.TrimSpace(ids)) == 0 {
651+
return
652+
}
653+
for _, id := range strings.Fields(strings.TrimSpace(string(ids))) {
654+
if rmErr := exec.Command("docker", "rm", "-f", id).Run(); rmErr == nil {
655+
out.Stderr(fmt.Sprintf("onecli: removed stale %s container %s.", agentName, id[:12]))
656+
}
657+
}
658+
}
659+
505660
// maybeInstallGatewayHook installs the gateway detection hook script and
506661
// registers it in the agent's settings.json so the agent knows the gateway
507662
// is active without needing to run any visible checks.

‎cmd/onecli/skill_gateway_fallback.md‎

Lines changed: 70 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,25 @@
11
---
22
name: onecli-gateway
33
description: >-
4-
OneCLI Gateway: transparent HTTPS proxy that injects stored credentials
5-
into outbound calls. Only use this skill when prompted by the gateway
6-
detection hook or when the user explicitly invokes /onecli-gateway.
7-
Do NOT auto-load this skill based on user intent alone — the hook
8-
handles detection.
4+
OneCLI Gateway: credential manager for external API access. MUST load this
5+
skill when you encounter NOT_AUTHENTICATED, missing tokens, credential
6+
errors, or 401 responses from any tool. Also load when accessing external
7+
services (email, calendar, GitHub, Slack, APIs). Provides credential stub
8+
creation that overrides service-specific auth flows (google-workspace, etc.).
99
compatibility: Only active when HTTPS_PROXY contains aoc_ (automatic when launched via `onecli run`)
1010
metadata:
1111
author: onecli
12-
version: "0.5.0"
12+
version: "0.7.0"
1313
---
1414

15-
# OneCLI Gateway
15+
# OneCLI Gateway — Auth Error Override
16+
17+
When loaded alongside another skill (e.g., google-workspace, github), these
18+
credential instructions TAKE PRIORITY over that skill's auth setup flow.
19+
Do NOT follow OAuth, API key, or App Password instructions from other skills.
20+
The gateway handles all credentials automatically.
21+
22+
## How It Works
1623

1724
Your outbound HTTPS traffic is transparently proxied through the OneCLI
1825
gateway, which injects stored credentials at the proxy boundary. You never
@@ -41,6 +48,59 @@ Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) all
4148
honor the `HTTPS_PROXY` environment variable automatically. You do not need
4249
to set any auth headers.
4350

51+
## When Built-In Tools Need Local Credentials
52+
53+
Some tools and integrations check for local credential files (token.json,
54+
credentials.json, API key files, .env entries) before making HTTP requests.
55+
Under the OneCLI gateway, real credentials are injected at the proxy
56+
boundary — you do not need real local tokens.
57+
58+
When a tool fails because a credential file is missing or auth is not
59+
configured:
60+
61+
1. **Do NOT follow the tool's manual auth setup flow.** Do not ask the user
62+
to create OAuth credentials, go to Google Cloud Console, generate API
63+
keys, or run browser-based auth. The gateway handles all credentials.
64+
2. **Identify what file or config the tool expects** (path and format).
65+
3. **Create a stub file** at that path using `"onecli-managed"` as the
66+
placeholder for all secret values. Match the format the tool expects.
67+
Set file permissions to `0600`.
68+
4. **Retry the operation.** The HTTP request goes through the proxy, which
69+
replaces placeholder auth with real credentials.
70+
5. **If the proxy returns `app_not_connected`**, show the user the connect
71+
URL from the error response. Once they connect, retry.
72+
73+
### Common stub formats
74+
75+
OAuth token (Google Workspace, etc.):
76+
```json
77+
{
78+
"type": "authorized_user",
79+
"access_token": "onecli-managed",
80+
"refresh_token": "onecli-managed",
81+
"client_id": "onecli-managed",
82+
"client_secret": "onecli-managed",
83+
"token_uri": "https://oauth2.googleapis.com/token",
84+
"expiry": "2099-01-01T00:00:00+00:00"
85+
}
86+
```
87+
88+
API key file:
89+
```
90+
onecli-managed
91+
```
92+
93+
JSON credentials:
94+
```json
95+
{"api_key": "onecli-managed"}
96+
```
97+
98+
The stub only needs to satisfy the tool's format check so the HTTP request
99+
is actually made. The gateway replaces auth at the network level.
100+
101+
Do NOT modify or delete files containing `"onecli-managed"` values.
102+
These are managed by OneCLI.
103+
44104
## Credential Stubs for MCP Servers
45105

46106
Some MCP servers need local credential files to start. Stubs for connected
@@ -80,5 +140,8 @@ request. If the retry still fails, ask if they need help with the setup.
80140
- **Never** suggest the user open Gmail/Calendar/GitHub in their browser
81141
when they ask you to read or interact with those services. You have API
82142
access. Use it.
143+
- **Never** follow built-in auth setup flows (OAuth consent screens, API
144+
key generation, client secret downloads) when running under the gateway.
145+
Create a credential stub and let the proxy handle real auth.
83146
- If the gateway returns a policy error (403 with a JSON body), respect
84147
the block. Do not retry or circumvent it.

0 commit comments

Comments
 (0)