Skip to content

docs: add README diagrams#10

Closed
madtank wants to merge 16 commits intomainfrom
frontend_sentinel/task-3f7c9a21-readme-diagrams
Closed

docs: add README diagrams#10
madtank wants to merge 16 commits intomainfrom
frontend_sentinel/task-3f7c9a21-readme-diagrams

Conversation

@madtank
Copy link
Copy Markdown
Member

@madtank madtank commented Mar 31, 2026

$## Summary\n- add three dark-theme SVG diagrams for the axctl README\n- cover platform overview, supervision loop, and profile fingerprint flow\n- keep layouts sized for GitHub README rendering\n\n## Validation\n- opened the SVG files locally and checked XML parses cleanly

Cipher and others added 16 commits March 17, 2026 04:11
- Added agent_id parameter to AxClient (sends X-Agent-Id header)
- Added resolve_agent_id() to config (AX_AGENT_ID env or config.toml)
- Updated CLAUDE.md with identity model documentation
- Agent-bound PATs with header now act as the agent principal

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
keys create:
- Added --agent flag (resolves name to UUID)
- Added docstring with examples for bound vs unrestricted PATs
- Shows "Bound to: <uuid>" on creation

auth init:
- Added --agent-id flag for agent-bound PAT config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…gent

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Design spec covers:
- ax listen --exec (agent wake-up primitive)
- ax send with SSE reply-waiting (replaces polling)
- ax monitor alias
- Shared SSEStream connection layer with reconnect and dedup

Implementation plan: 11 TDD tasks covering SSE parser, dedup tracker,
SSEStream class, mention detection, exec runner, listen command,
send SSE integration, and end-to-end verification.

Approved by @orion. Reviewed and revised after code review.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add two SSE-based scripts that demonstrate how agents connect to aX:

- ax_listener.py: mention monitor — listens for @mentions via SSE,
  responds via REST API. Includes dedup, loop prevention, backoff.
- echo_agent.py: minimal echo bot — receives any message via SSE,
  echoes it back as a threaded reply. Proof of the SSE→API loop.

Both use config from .ax/config.toml, support --dry-run and --verbose.

Key discovery: API silently blocks self-mentions (returns 200 empty body).
Documented in both scripts. CLAUDE.md updated to wire_tap identity.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…valuation

Comprehensive spec for expanding ax-cli from basic API wrapper to the
definitive agent toolkit. Concierge-first design: ax send routes through
aX by default, ax check gets tailored briefings with reason.

Includes live endpoint evaluation (2026-03-18) testing every backend
endpoint with the swarm PAT. Documents what works (55+ endpoints),
backend bugs (4), auth limitations, and non-existent endpoints to skip.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
After bind, agent_id is the authoritative identity header.
agent_name is now limited to bootstrap (no id yet) and explicit
interactive --agent targeting.

Root cause: resolve_agent_id() returned None when agent_name was
present, causing bound PATs to send X-Agent-Name instead of
X-Agent-Id. Backend rejected this with 403 on agent-scoped PATs
when name resolution failed or was ambiguous.

Changes:
- config.py: simplify resolve_agent_id() to always return id if
  available; get_client() only resolves name when no id exists
- client.py: flip _agent_headers() precedence — id wins over name
- messages.py: _configure_send_identity() preserves default identity
  when no explicit flags are passed (fixes 403 on scoped PATs)
- tests: 16 tests covering id-first precedence, bootstrap fallback,
  env var priority, per-request overrides, and send identity

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
91d6b04 skipped resolve_agent_name() entirely when config had
agent_id, making env-level name targeting impossible. Now
AX_AGENT_NAME env beats config-level agent_id (explicit targeting
override), while both env vars set still prefers ID as canonical.

Precedence:
  1. AX_AGENT_NAME env (no AX_AGENT_ID) → name (targeting)
  2. AX_AGENT_ID env → ID (canonical)
  3. config agent_id → ID (steady state)
  4. config agent_name → name (bootstrap)

Added regression tests:
  - env name overrides config id
  - both env vars set → id wins

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@madtank madtank changed the base branch from aws/prod to main March 31, 2026 03:25
@madtank
Copy link
Copy Markdown
Member Author

madtank commented Mar 31, 2026

Closing — SVGs cherry-picked into PR #9 (clean branch). The rest of the changes in this PR are unrelated. Thanks for the diagrams.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant