docs(computeragent): add info.md — architecture + harness protocol tour#15
Merged
Conversation
352-line companion to the README focused on what's architecturally
interesting under the hood. Twelve numbered sections, each with an
ASCII diagram or table where it helps.
Contents:
- TL;DR: four orthogonal ports diagram (IdentityLoader / EngineDriver
/ Substrate / SessionStore / AuditSink)
- 1. Git URL as agent identity (no registry, no UUIDs)
- 2. Substrate-agnostic agent code (Local / Bwrap / E2B / VZ)
- 3. Harness protocol — full SSE+HTTP wire diagram + why a separate
process + the HarnessEvent type
- 4. AuditSink: telemetry as a one-method protocol; gen_ai.* OTel
- 5. Library-mode vs server-mode side-by-side
- 6. Cost semantics: cumulative vs delta aggregation (the subtle bit)
- 7. JSONL session replay (audit-friendly by accident)
- 8. SessionStore swap (memory / file / mongo / sqlite)
- 9. IRSA + Bedrock without static keys (the 9-env-var allow-list)
- 10. Permission protocol audit diagram + SIEM integration
- 11. Conformance suite for third-party plug-ins
- 12. OTLP everywhere, vendor nowhere
- End-to-end flow: single chat turn diagram
- See also: links to README, protocol package, sdk, harness, etc.
Designed for: slide decks, talks, HN comments, customer architecture
reviews. Pairs with README.md which is the install + quickstart.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
packages/computeragent/info.md(~350 lines, 12 sections) as the "what's actually going on under the hood" companion to the install-flavoredREADME.md.Covers — with an ASCII diagram or table per section — the parts that read interesting in a slide deck or talk:
HarnessEventdiscriminated union@computeragent/testingfor plug-in authorsPlus a "See also" block linking to the relevant packages + the de-risk spike report.
No code changes.