Skip to content

feat(agent): add system facts, routes, fact references, and validation#227

Merged
retr0h merged 10 commits intomainfrom
feat/agent-facts-routes-factref
Mar 6, 2026
Merged

feat(agent): add system facts, routes, fact references, and validation#227
retr0h merged 10 commits intomainfrom
feat/agent-facts-routes-factref

Conversation

@retr0h
Copy link
Collaborator

@retr0h retr0h commented Mar 6, 2026

Summary

  • Add route collection (Linux /proc/net/route, Darwin netstat -rn) and primary interface detection to agent facts
  • Add @fact.* reference resolution in job parameters — agents resolve @fact.interface.primary, @fact.hostname, @fact.arch, @fact.kernel, @fact.fqdn, and @fact.custom.* before executing operations
  • Add ip_or_fact and alphanum_or_fact validators with known-key checking to reject invalid fact references at the API level
  • Propagate fact resolution errors to KV so clients get immediate errors instead of 30s timeouts
  • Consolidate split test methods into single table-driven suites per function
  • Close coverage gaps across agent handler, factref, network providers, and darwin routes
  • Add system facts documentation page and update feature docs

Test Plan

  • just go::unit — all 26 packages pass
  • Validator rejects unknown fact keys (@fact.primary_interface → 400)
  • Validator accepts known fact keys (@fact.interface.primary → pass)
  • Handler writes error to KV when fact resolution fails (no client timeout)
  • Nil cached facts returns "facts not available" error
  • HTTP wiring tests for unknown fact key rejection (ping, DNS GET, DNS PUT)
  • All test names follow "when" prefix convention

🤖 Generated with Claude Code

retr0h and others added 5 commits March 5, 2026 17:01
Merge split test methods into single table-driven methods
following the one-suite-method-per-function convention:

- metrics_test: 3 InitMeter methods → TestInitMeter
- telemetry_test: 3 InitTracer methods → TestInitTracer
- slog_public_test: merge PreservesTraceID into TestNewTraceHandler
- target_public_test: merge CacheHit into TestValidTarget

Also remove two obsolete backlog tasks superseded by the
osapi-orchestrator (sdk-response-types, declarative-playbook).

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Add ip_or_fact custom validator so ping address fields accept @fact.
prefixed references. Update OpenAPI spec, regenerate, and add
comprehensive HTTP wiring tests for @fact across ping, DNS GET, and
DNS PUT endpoints.

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add handler tests for @fact resolution success and failure paths
- Add factref test for custom key missing from non-nil facts map
- Add darwin routes test for Internet6: before IPv4 header

Brings internal/agent to 100% and netinfo to 95% (remainder is
factory function and mock packages).

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Exercise NewDarwinProvider factory closures in netinfo (route reader,
interface addrs) and ping (pinger creation) packages. Add missing
listallhardwareports error test in DNS update. All modified packages
now at 100% statement coverage.

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions
Copy link
Contributor

github-actions bot commented Mar 6, 2026

Thank you for contributing to this project! 😊🕹️

- Add isKnownFactKey() to reject unknown @fact keys at API validation
  level (e.g., @fact.primary_interface now returns 400)
- Propagate fact resolution errors to KV so clients get immediate
  error responses instead of 30s timeouts
- Remove cachedFacts nil guard so @fact references always attempt
  resolution (returns "facts not available" error when nil)
- Normalize test names to "when" prefix convention across handler,
  ping, and DNS test suites
- Add HTTP wiring tests for unknown fact key rejection
- Truncate long exec command logs

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@retr0h retr0h force-pushed the feat/agent-facts-routes-factref branch from 7203d34 to 1729033 Compare March 6, 2026 05:54
retr0h and others added 2 commits March 5, 2026 21:57
- Fix relative path to system-facts.md from exec CLI docs
- Remove osapi-sdk replace directive, use published module

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
The "when using default route reader" test expected an error because
/proc/net/route doesn't exist on macOS. On Linux CI it succeeds.
Skip error assertion for platform-dependent default reader tests.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@retr0h retr0h force-pushed the feat/agent-facts-routes-factref branch from 885fd30 to 2539683 Compare March 6, 2026 06:06
@codecov
Copy link

codecov bot commented Mar 6, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #227      +/-   ##
==========================================
+ Coverage   98.94%   99.98%   +1.03%     
==========================================
  Files         161      166       +5     
  Lines        5611     6009     +398     
==========================================
+ Hits         5552     6008     +456     
+ Misses         50        1      -49     
+ Partials        9        0       -9     
Files with missing lines Coverage Δ
internal/agent/condition.go 100.00% <ø> (ø)
internal/agent/consumer.go 100.00% <100.00%> (ø)
internal/agent/factory.go 100.00% <100.00%> (ø)
internal/agent/factref.go 100.00% <100.00%> (ø)
internal/agent/facts.go 100.00% <100.00%> (ø)
internal/agent/handler.go 100.00% <100.00%> (ø)
internal/agent/heartbeat.go 100.00% <100.00%> (ø)
internal/api/agent/agent_list.go 100.00% <100.00%> (+22.38%) ⬆️
internal/api/node/node_load_get.go 100.00% <ø> (ø)
internal/api/node/node_memory_get.go 100.00% <ø> (ø)
... and 35 more

... and 3 files with indirect coverage changes


Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a76f54e...cf6acce. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

retr0h and others added 2 commits March 5, 2026 22:16
Darwin DNS GET was silently falling back to the first resolver
(system default) when the requested interface didn't match any
scutil resolver block. Now returns an error consistent with the
Ubuntu provider behavior.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Add test for interface found in scutil but missing from
networksetup hardware ports (e.g., virtual tunnel interface).

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@retr0h retr0h merged commit d916601 into main Mar 6, 2026
9 checks passed
@retr0h retr0h deleted the feat/agent-facts-routes-factref branch March 6, 2026 17:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant