hermes-agent

mirrors/hermes-agent

Fork 0

mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-19 04:52:06 +00:00

Commit graph

Author	SHA1	Message	Date
Teknium	fef1a41248	docs: round 2 audit — messaging, developer-guide, guides, integrations (#22858 ) Cross-checked 75 docs pages under user-guide/messaging/, developer-guide/, guides/, and integrations/ against the live registries and gateway code. messaging/ - index.md: API Server toolset is hermes-api-server (was 'hermes (default)'); Google Chat slug is hermes-google_chat (underscore — plugin name uses _). - google_chat.md: drop bogus 'pip install hermes-agent[google_chat]' (no such extra); list the actual deps (google-cloud-pubsub, google-api-python-client, google-auth, google-auth-oauthlib). - qqbot.md: config namespace is platforms.qqbot (was platforms.qq, which is silently ignored by the adapter); QQ_STT_BASE_URL is not read directly — baseUrl lives under platforms.qqbot.extra.stt. - teams-meetings.md: 'hermes teams-pipeline' is plugin-gated (teams_pipeline plugin must be enabled), not a built-in subcommand. - sms.md: example log line 0.0.0.0:8080 -> 127.0.0.1:8080 (default SMS_WEBHOOK_HOST). - open-webui.md: API_SERVER_* are env vars, not YAML keys — write them to per-profile .env, not 'hermes config set' (same pattern fixed in api-server.md last round). Also bumped example ports to 8650+ to dodge the default webhook (8644)/wecom-callback (8645)/msgraph-webhook (8646) collision. developer-guide/ - architecture.md: tool/toolset counts (61/52 -> 70+/~28); LOC stamps for run_agent.py, cli.py, hermes_cli/main.py, setup.py, mcp_tool.py, gateway/run.py replaced with 'large file' to stop drifting. - agent-loop.md: same LOC drift (~13,700 -> 'a large file (15k+ lines)'). - gateway-internals.md: '14+ external messaging platforms' -> '20+'; gateway platform tree updated (qqbot is a sub-package, not qqbot.py; added yuanbao.py, feishu_comment.py, msgraph_webhook.py); 'gateway/builtin_hooks/ (always active)' was wrong — it's an empty extension point and _register_builtin_hooks() is a no-op stub. - acp-internals.md: drop fictional 'message_callback' from the bridged- callbacks list; clarify thinking_callback is currently set to None. - provider-runtime.md: provider list was missing AWS Bedrock, Azure Foundry, NVIDIA NIM, xAI, Arcee, GMI Cloud, StepFun, Qwen OAuth, Xiaomi, Ollama Cloud, LM Studio, Tencent TokenHub. Fallback section described only the legacy single-pair model — corrected to the canonical list-form fallback_providers chain. - environments.md: parsers list missing llama4_json and the deepseek_v31 alias; both register via @register_parser. - browser-supervisor.md: drop reference to scripts/browser_supervisor_e2e.py which doesn't exist in-repo. - contributing.md: tinker-atropos is a git submodule — note that 'git submodule update --init' is required if cloning without --recurse-submodules. guides/ - operate-teams-meeting-pipeline.md: cron flags were all wrong — schedule is positional (not --schedule), the script-only flag is --no-agent (not --script-only), and there's no --command flag. Replaced with a real example that creates the script under ~/.hermes/scripts/ and uses the actual flags. Also replaced fictional 'hermes cron show <name>' with 'hermes cron status'. - automation-templates.md: 'cron create --skills "a,b"' doesn't work — the flag is --skill (singular, repeatable). Fixed all 5 occurrences via AST rewrite. - minimax-oauth.md: 'hermes auth add minimax-oauth --region cn' silently fails because --region isn't registered on the auth-add argparse spec. Pointed users at the minimax-cn provider (or MINIMAX_CN_API_KEY env) for China-region access. - cron-script-only.md: 'hermes send' is fictional — replaced the comparison- table mention with a webhook-subscription pointer; also fixed the dead link to /guides/pipe-script-output (page doesn't exist). - cron-troubleshooting.md: 'hermes serve' isn't a real subcommand. Pointed at 'hermes gateway' (foreground) / 'hermes gateway start' (service). - local-ollama-setup.md: 'agent.api_timeout' is not a config key. The right knob is the HERMES_API_TIMEOUT env var. - python-library.md: run_conversation() return dict has only final_response and messages — task_id is stored on the agent instance, not echoed back. - use-mcp-with-hermes.md: '--args /c "npx -y …"' wraps the npx command in one quoted string, so cmd.exe gets a single arg instead of the multi-token command line it needs. Removed the surrounding quotes — argparse nargs='*' collects each token correctly. integrations/ - providers.md: Bedrock guardrail YAML keys were 'id'/'version' (don't exist); actual keys are guardrail_identifier/guardrail_version (matches DEFAULT_CONFIG and the run_agent.py reader). GMI default base URL (api.gmi.ai/v1 -> api.gmi-serving.com/v1) and portal URL (inference.gmi.ai -> www.gmicloud.ai) refreshed. Fallback section rewritten to lead with the canonical fallback_providers list form (was leading with the legacy fallback_model single dict); supported-providers list extended to include azure-foundry, alibaba-coding-plan, lmstudio. index.md - '68 built-in tools' -> '70+'; '15+ platforms' was both inconsistent with integrations/index.md ('19+') and undercounted — bumped to 20+ and added Weixin/QQ Bot/Yuanbao/Google Chat to the list. Validation: 'npm run build' clean (exit 0); broken-link count unchanged at 155 (same as round-1 post-skill-regen baseline). 24 files, +132/-89.	2026-05-09 15:00:24 -07:00
Ramón Fernández	44cd79e798	feat(plugins/google_chat): Google Chat platform adapter as a bundled plugin Adds Google Chat as a new gateway platform, shipped under plugins/platforms/google_chat/ following the canonical bundled-plugin pattern (Teams, IRC). Rewired from the original PR #18425 to use the new env_enablement_fn + cron_deliver_env_var plugin interfaces landed in the preceding commit, so the adapter touches ZERO core files. What it does: - Inbound DM + group messages via Cloud Pub/Sub pull subscription (no public URL needed), with attachments (PDFs, images, audio, video) downloaded through an SSRF-guarded Google-host allowlist. - Outbound text replies with the 'Hermes is thinking…' patch-in-place pattern — no tombstones. - Native file attachment delivery via per-user OAuth. Google Chat's media.upload endpoint rejects service-account auth, so each user runs /setup-files once in their own DM to grant chat.messages.create for themselves; the adapter then uploads as them. Tokens stored per email at ~/.hermes/google_chat_user_tokens/<email>.json. - Thread isolation: side-threads get isolated sessions, top-level DM messages share one continuous session. Persistent thread-count store survives gateway restart. - Supervisor reconnect with exponential backoff. - Multi-user out of the box. How it plugs in (no core edits): - env_enablement_fn seeds PlatformConfig.extra with project_id, subscription_name, service_account_json, and the home_channel dict (which the core hook turns into a HomeChannel dataclass). Reads GOOGLE_CHAT_PROJECT_ID (falls back to GOOGLE_CLOUD_PROJECT), GOOGLE_CHAT_SUBSCRIPTION_NAME (falls back to GOOGLE_CHAT_SUBSCRIPTION), GOOGLE_CHAT_SERVICE_ACCOUNT_JSON (falls back to GOOGLE_APPLICATION_CREDENTIALS), GOOGLE_CHAT_HOME_CHANNEL. - cron_deliver_env_var='GOOGLE_CHAT_HOME_CHANNEL' gets cron delivery for free — cron/scheduler.py consults the platform registry for any name not in its hardcoded built-in sets. - plugin.yaml's rich requires_env / optional_env blocks auto-populate OPTIONAL_ENV_VARS via the new hermes_cli/config.py injector, so 'hermes config' UI surfaces them with description / url / prompt / password metadata. - Module-level Platform('google_chat') call in adapter.py triggers the Platform._missing_() registration so Platform.GOOGLE_CHAT attribute access works without an enum entry. Distribution: ships inside the existing hermes-agent package. Users opt in via 'pip install hermes-agent[google_chat]' and follow the 8-step GCP walkthrough at website/docs/user-guide/messaging/google_chat.md. Test coverage: 153 tests in tests/gateway/test_google_chat.py, all passing. Spans platform registration, env config loading, Pub/Sub envelope routing, outbound send + chunking + typing patch-in-place, attachment send paths, SSRF guard, thread/session model, supervisor reconnect, authorization, per-user OAuth, and the new plugin-registry cron delivery wiring. Credit: adapter + OAuth + tests + docs authored by @donramon77 (PR #18425). Rewire onto the new plugin hooks + salvage commit by Teknium. Co-Authored-By: Ramón Fernández <112875006+donramon77@users.noreply.github.com>	2026-05-07 07:15:44 -07:00

Author

SHA1

Message

Date

Teknium

fef1a41248

docs: round 2 audit — messaging, developer-guide, guides, integrations (#22858 )

Cross-checked 75 docs pages under user-guide/messaging/, developer-guide/,
guides/, and integrations/ against the live registries and gateway code.

messaging/
- index.md: API Server toolset is hermes-api-server (was 'hermes (default)');
  Google Chat slug is hermes-google_chat (underscore — plugin name uses _).
- google_chat.md: drop bogus 'pip install hermes-agent[google_chat]' (no such
  extra); list the actual deps (google-cloud-pubsub, google-api-python-client,
  google-auth, google-auth-oauthlib).
- qqbot.md: config namespace is platforms.qqbot (was platforms.qq, which is
  silently ignored by the adapter); QQ_STT_BASE_URL is not read directly —
  baseUrl lives under platforms.qqbot.extra.stt.
- teams-meetings.md: 'hermes teams-pipeline' is plugin-gated (teams_pipeline
  plugin must be enabled), not a built-in subcommand.
- sms.md: example log line 0.0.0.0:8080 -> 127.0.0.1:8080 (default
  SMS_WEBHOOK_HOST).
- open-webui.md: API_SERVER_* are env vars, not YAML keys — write them to
  per-profile .env, not 'hermes config set' (same pattern fixed in
  api-server.md last round). Also bumped example ports to 8650+ to dodge the
  default webhook (8644)/wecom-callback (8645)/msgraph-webhook (8646)
  collision.

developer-guide/
- architecture.md: tool/toolset counts (61/52 -> 70+/~28); LOC stamps for
  run_agent.py, cli.py, hermes_cli/main.py, setup.py, mcp_tool.py,
  gateway/run.py replaced with 'large file' to stop drifting.
- agent-loop.md: same LOC drift (~13,700 -> 'a large file (15k+ lines)').
- gateway-internals.md: '14+ external messaging platforms' -> '20+'; gateway
  platform tree updated (qqbot is a sub-package, not qqbot.py; added
  yuanbao.py, feishu_comment.py, msgraph_webhook.py); 'gateway/builtin_hooks/
  (always active)' was wrong — it's an empty extension point and
  _register_builtin_hooks() is a no-op stub.
- acp-internals.md: drop fictional 'message_callback' from the bridged-
  callbacks list; clarify thinking_callback is currently set to None.
- provider-runtime.md: provider list was missing AWS Bedrock, Azure Foundry,
  NVIDIA NIM, xAI, Arcee, GMI Cloud, StepFun, Qwen OAuth, Xiaomi, Ollama
  Cloud, LM Studio, Tencent TokenHub. Fallback section described only the
  legacy single-pair model — corrected to the canonical list-form
  fallback_providers chain.
- environments.md: parsers list missing llama4_json and the deepseek_v31
  alias; both register via @register_parser.
- browser-supervisor.md: drop reference to scripts/browser_supervisor_e2e.py
  which doesn't exist in-repo.
- contributing.md: tinker-atropos is a git submodule — note that
  'git submodule update --init' is required if cloning without
  --recurse-submodules.

guides/
- operate-teams-meeting-pipeline.md: cron flags were all wrong — schedule is
  positional (not --schedule), the script-only flag is --no-agent (not
  --script-only), and there's no --command flag. Replaced with a real example
  that creates the script under ~/.hermes/scripts/ and uses the actual flags.
  Also replaced fictional 'hermes cron show <name>' with 'hermes cron status'.
- automation-templates.md: 'cron create --skills "a,b"' doesn't work —
  the flag is --skill (singular, repeatable). Fixed all 5 occurrences via AST
  rewrite.
- minimax-oauth.md: 'hermes auth add minimax-oauth --region cn' silently
  fails because --region isn't registered on the auth-add argparse spec.
  Pointed users at the minimax-cn provider (or MINIMAX_CN_API_KEY env) for
  China-region access.
- cron-script-only.md: 'hermes send' is fictional — replaced the comparison-
  table mention with a webhook-subscription pointer; also fixed the dead link
  to /guides/pipe-script-output (page doesn't exist).
- cron-troubleshooting.md: 'hermes serve' isn't a real subcommand. Pointed
  at 'hermes gateway' (foreground) / 'hermes gateway start' (service).
- local-ollama-setup.md: 'agent.api_timeout' is not a config key. The right
  knob is the HERMES_API_TIMEOUT env var.
- python-library.md: run_conversation() return dict has only final_response
  and messages — task_id is stored on the agent instance, not echoed back.
- use-mcp-with-hermes.md: '--args /c "npx -y …"' wraps the npx command in
  one quoted string, so cmd.exe gets a single arg instead of the multi-token
  command line it needs. Removed the surrounding quotes — argparse nargs='*'
  collects each token correctly.

integrations/
- providers.md: Bedrock guardrail YAML keys were 'id'/'version' (don't exist);
  actual keys are guardrail_identifier/guardrail_version (matches DEFAULT_CONFIG
  and the run_agent.py reader). GMI default base URL (api.gmi.ai/v1 ->
  api.gmi-serving.com/v1) and portal URL (inference.gmi.ai -> www.gmicloud.ai)
  refreshed. Fallback section rewritten to lead with the canonical
  fallback_providers list form (was leading with the legacy fallback_model
  single dict); supported-providers list extended to include azure-foundry,
  alibaba-coding-plan, lmstudio.

index.md
- '68 built-in tools' -> '70+'; '15+ platforms' was both inconsistent with
  integrations/index.md ('19+') and undercounted — bumped to 20+ and added
  Weixin/QQ Bot/Yuanbao/Google Chat to the list.

Validation: 'npm run build' clean (exit 0); broken-link count unchanged at
155 (same as round-1 post-skill-regen baseline). 24 files, +132/-89.

2026-05-09 15:00:24 -07:00

Ramón Fernández

44cd79e798

feat(plugins/google_chat): Google Chat platform adapter as a bundled plugin

Adds Google Chat as a new gateway platform, shipped under
plugins/platforms/google_chat/ following the canonical bundled-plugin
pattern (Teams, IRC).  Rewired from the original PR #18425 to use the
new env_enablement_fn + cron_deliver_env_var plugin interfaces landed
in the preceding commit, so the adapter touches ZERO core files.

What it does:
- Inbound DM + group messages via Cloud Pub/Sub pull subscription (no
  public URL needed), with attachments (PDFs, images, audio, video)
  downloaded through an SSRF-guarded Google-host allowlist.
- Outbound text replies with the 'Hermes is thinking…' patch-in-place
  pattern — no tombstones.
- Native file attachment delivery via per-user OAuth.  Google Chat's
  media.upload endpoint rejects service-account auth, so each user
  runs /setup-files once in their own DM to grant
  chat.messages.create for themselves; the adapter then uploads as
  them.  Tokens stored per email at
  ~/.hermes/google_chat_user_tokens/<email>.json.
- Thread isolation: side-threads get isolated sessions, top-level DM
  messages share one continuous session.  Persistent thread-count
  store survives gateway restart.
- Supervisor reconnect with exponential backoff.
- Multi-user out of the box.

How it plugs in (no core edits):
- env_enablement_fn seeds PlatformConfig.extra with project_id,
  subscription_name, service_account_json, and the home_channel dict
  (which the core hook turns into a HomeChannel dataclass).  Reads
  GOOGLE_CHAT_PROJECT_ID (falls back to GOOGLE_CLOUD_PROJECT),
  GOOGLE_CHAT_SUBSCRIPTION_NAME (falls back to GOOGLE_CHAT_SUBSCRIPTION),
  GOOGLE_CHAT_SERVICE_ACCOUNT_JSON (falls back to
  GOOGLE_APPLICATION_CREDENTIALS), GOOGLE_CHAT_HOME_CHANNEL.
- cron_deliver_env_var='GOOGLE_CHAT_HOME_CHANNEL' gets cron delivery
  for free — cron/scheduler.py consults the platform registry for any
  name not in its hardcoded built-in sets.
- plugin.yaml's rich requires_env / optional_env blocks auto-populate
  OPTIONAL_ENV_VARS via the new hermes_cli/config.py injector, so
  'hermes config' UI surfaces them with description / url / prompt /
  password metadata.
- Module-level Platform('google_chat') call in adapter.py triggers the
  Platform._missing_() registration so Platform.GOOGLE_CHAT attribute
  access works without an enum entry.

Distribution: ships inside the existing hermes-agent package.  Users
opt in via 'pip install hermes-agent[google_chat]' and follow the
8-step GCP walkthrough at
website/docs/user-guide/messaging/google_chat.md.

Test coverage: 153 tests in tests/gateway/test_google_chat.py, all
passing.  Spans platform registration, env config loading, Pub/Sub
envelope routing, outbound send + chunking + typing patch-in-place,
attachment send paths, SSRF guard, thread/session model,
supervisor reconnect, authorization, per-user OAuth, and the new
plugin-registry cron delivery wiring.

Credit: adapter + OAuth + tests + docs authored by @donramon77
(PR #18425).  Rewire onto the new plugin hooks + salvage commit by
Teknium.

Co-Authored-By: Ramón Fernández <112875006+donramon77@users.noreply.github.com>

2026-05-07 07:15:44 -07:00

2 commits