Skip to content

docs(agent): improve module docstrings with architecture overview - #118

Closed
Bartok9 wants to merge 1 commit into
NousResearch:mainfrom
Bartok9:docs/improve-agent-module-docstrings
Closed

docs(agent): improve module docstrings with architecture overview#118
Bartok9 wants to merge 1 commit into
NousResearch:mainfrom
Bartok9:docs/improve-agent-module-docstrings

Conversation

@Bartok9

@Bartok9 Bartok9 commented Feb 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Enhance documentation in the agent/ package to help contributors understand the architecture.

Changes

agent/init.py

  • Add comprehensive Module Overview section describing each submodule
  • Add Architecture section explaining design principles:
    • Stateless utilities
    • No circular imports
    • Single responsibility
    • AIAgent as orchestrator

agent/auxiliary_client.py

  • Document the purpose (cheap/fast side tasks)
  • Explain resolution order for text and vision clients
  • Document public API with usage example

agent/model_metadata.py

  • Add function-level documentation explaining what each utility provides
  • Document the fallback defaults dictionary

agent/trajectory.py

  • Document each function's purpose
  • Add ShareGPT output format example
  • Explain the completed/failed trajectory separation

Why

The agent package contains key infrastructure but lacked comprehensive documentation explaining:

  • How the modules relate to each other
  • What each module's responsibility is
  • How to use the public APIs

This makes onboarding easier for new contributors.

Checklist

  • Documentation only - no behavior changes
  • Follows existing docstring style
  • Preserves all existing functionality

Bartok9
docs(agent): improve module docstrings with architecture overview
1ac6bb6 
Enhance documentation in the agent/ package:

- agent/__init__.py: Add comprehensive module overview and architecture
  description explaining the role of each submodule
- agent/auxiliary_client.py: Document purpose, resolution order, and
  public API with usage example
- agent/model_metadata.py: Add function-level documentation explaining
  what each utility provides
- agent/trajectory.py: Document the ShareGPT output format and explain
  what each function does

These improvements help contributors understand the agent package
architecture without reading all the implementation code.
@teknium1 teknium1 closed this Feb 27, 2026
@shang-vikas shang-vikas mentioned this pull request Jun 23, 2026
Merged
Meraniya pushed a commit to Meraniya/hermes-agent that referenced this pull request Aug 6, 2026
@dizhaky
fix(security): harden _sanitize_env_lines against env injection (GHSA…
9d05974 
…-mv8x-fg99-32mf) (NousResearch#118)

- Replace concatenated-KEY splitter with safe no-split normalizer per
  upstream 0.19.0. Values after the first '=' are now opaque data —
  embedded KEY= patterns can no longer synthesize assignments.
- Bump package version to 0.18.0 (Dependabot floor for CVE-2026-10222).
- Update docstrings, migrate message, and comments to reflect semantics-
  preserving behavior (GHSA-mv8x-fg99-32mf / CVE-2026-10222).
- Port full upstream sanitize test suite (17 tests) validating:
  - known KEY= inside values remains opaque
  - leading 'export ' prefix preserved
  - load_env never synthesizes variables from values
  - save_env_value / sanitize_env_file preserve value semantics

Closes Dependabot alert NousResearch#100 (LOW).
Meraniya pushed a commit to Meraniya/hermes-agent that referenced this pull request Aug 6, 2026
@dizhaky @claude
chore(security): allowlist concatenated env-injection test fixtures i…
d941351 
…n gitleaks (NousResearch#131)

The _sanitize_env_lines test fixtures glue a provider key name onto preceding value text (e.g. sk1ANTHROPIC_API_KEY=sk2) to exercise env-injection handling; gitleaks generic-api-key flags them (3 findings across NousResearch#118/NousResearch#122 commits). Adds one narrow shape-based allowlist regex: a key name not at a boundary is the fixture shape, never a real assignment. Verified: the previously failing range scans clean; boundary-anchored real keys still fire.


Claude-Session: https://claude.ai/code/session_01T48zpYeRonsn4kTHHwLiMi

Co-authored-by: Claude <noreply@anthropic.com>
Meraniya pushed a commit to Meraniya/hermes-agent that referenced this pull request Aug 6, 2026
@dizhaky @claude
fix(secrets): recover hardening orphaned when PR NousResearch#106 was…
eea21ce 
… closed (NousResearch#130)

* fix(secrets): recover hardening orphaned when PR NousResearch#106 was closed

PR NousResearch#127 landed NousResearch#106's tree as it stood at commit aa74dd6 — main's
onepassword.py, secrets_cli.py and local.py are byte-identical to that
commit. The branch then had 8 further commits, all hardening, and
closing NousResearch#106 dropped every one of them.

This replays `git diff aa74dd6..18af401` onto current main, scoped to
the feature's own files. Recovered:

- local.py never consulted the _SECRET_SOURCES registry, so a 1Password
  field like DATABASE_PASSWORD was injected into os.environ and flowed
  straight into model-issued subprocesses. NousResearch#127 did not touch local.py.
- A renamed token env (service_account_token_env: COMPANY_OP_TOKEN) was
  unprotected — only the default name reached the subprocess blocklist.
- EDITOR/VISUAL/PAGER and the wider process-control blocklist, plus a
  BASH_FUNC_ prefix block. `hermes config edit` execs $EDITOR directly.
- Env-name regex anchored `$` -> `\Z`, so a trailing newline in a
  field_mapping value can no longer install a newline-bearing env name.
- Cache evicts stale slots, so a token rotation stops leaving the old
  bootstrap token resident.
- Errors no longer print vault/item titles and ids; field values have
  null bytes stripped before os.environ assignment.
- Two clear-text-logging sinks reduced to counts.
- Secrets are relinquished when the source is disabled.
- Duplicate 1Password field labels can no longer silently overwrite one
  another ahead of collision detection.
- Nine-subclass exception hierarchy replacing str(exc) display.

Deliberately NOT ported — NousResearch#106 predates NousResearch#118 and three of its hunks are
regressions against today's main: config.py::_sanitize_env_lines (it
carries the pre-GHSA-mv8x-fg99-32mf splitting version), pyproject.toml
(0.15.0 vs 0.18.0), and main.py's missing --legacy-peer-deps. All three
verified intact after the patch.

Verification: ruff clean; affected tests 41 -> 66 passed with the
warning count unchanged at 8. Positive control on the headline fix —
reverting only local.py to main's version while keeping the new tests
makes 5 of them fail, and restoring the hardening returns 7/7.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012689txgT12g2hjRczcUZi8

* fix: route field-label warnings through the warnings list, not logger.warning

CodeQL's clear-text-logging taint tracking treats any attribute of a
1Password item field (title/label) as tainted, the same as .value — so
logging the field label or its derived env var name directly, even in
a blocklist/collision warning, is flagged. Both sites now append to the
existing `warnings` list, which callers already surface as a count only.

---------

Co-authored-by: Claude <noreply@anthropic.com>
@leonzinger leonzinger mentioned this pull request Aug 13, 2026
Closed
fabiosiqueira added a commit to fabiosiqueira/hermes-engine that referenced this pull request Aug 18, 2026
@fabiosiqueira @claude
merge: fabiosiqueira/epic-124-118 into local/all-fixes
8165a7f 
Adds the gateway message:sent hook and outbound flood guard
(issues NousResearch#118 and NousResearch#124), approved via /issue-qa gate.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Bartok9 @teknium1