Skip to content

docs(protocol): Atem response to the agent control API proposal - #74

Draft
guohai wants to merge 3 commits into
mainfrom
docs/agent-control-api
Draft

guohai wants to merge 3 commits into
mainfrom
docs/agent-control-api

Conversation

@guohai

@guohai guohai commented Oct 17, 2026

Copy link
Copy Markdown
Contributor

Atem's answer to Astation's agent-control API proposal r1 (Astation #53, issue #52). Design only. Each section is marked today (in main at af56d39) or proposed.

  • Q1, providers:
  • Q2, history:
    • A sequenced history_end, carrying the next cursor, an end state, the oldest retained message and a truncation flag.
    • Older pages through a separate request that never touches live sequence numbers.
    • The actual retention limits.
  • Q3, recovery:
    • A completed prompt receipt carries result{turn_id, user_message_id, outcome, reply_message_ids}, journaled as ids only.
    • Lookup by turn or request id. After eviction the answer is unavailable, and the request is never rerun.
  • Q4, approval cards: the exact states, plus a reason on final cards. The session inbox stays authoritative.
  • Q5, versioning: r8 adds revision and features to welcome. Shared fixtures for each feature land before either side emits it.

The doc also lists Atem defects found while writing it; their fixes are in progress separately. It flags these risks in the proposal:

  • "completed" doesn't mean success yet;
  • one host conversation per API reader runs into the 8-per-session cap;
  • history and approval cards don't fully survive a broker restart today.

Generated with SMT smt@agora.build

Answers Astation's five questions: providers and capabilities (Codex
chat built, Atem session rules for Codex), an explicit history end and
unsequenced history pages, receipt results with turn and message ids,
approval card lifecycle, and an r8 revision with welcome features and
fixtures first. Marks what exists today versus what is proposed.

🤖 Built with SMT <smt@agora.build>
🤖 Built with SMT <smt@agora.build>
…fixtures

Answer Astation's review of response r1 with the controller's rulings:
- Version admission: hello carries revision 8; an r8 host refuses a hello
  without it with unsupported_version before any attachment; welcome
  echoes revision and features; removed forms (open.before,
  open.generation, status.page) are refused explicitly. Envelope stays v:1.
- Ordering: every history page is snapshotted and enqueued in one broker
  step in the conversation's sequenced stream; a message's sequence is its
  position, so a page never replaces a newer version.
- Bounded recovery: one selector of before/turn_id/request_id/next,
  validated; pages bounded by 50 messages, 256 KiB content and 1 MiB
  serialized; opaque context-bound next tokens (stale_target); end and
  coverage complete|partial|unavailable; reply_message_ids <= 32 + more.
- Truncation is persistent coverage information; backlog holes are
  persistent holes; resync only on a sequence gap, fence, generation
  change or close with a reason. The gap reload's error + close (#75)
  becomes reload + coverage event in r8.

atem-session-v1.md gains an "r8 draft" appendix (r7.2 stays
authoritative). Twelve r8-* fixtures, marked requires: "r8" in schema.md;
the fixture runners parse them and report them NOT RUN (requires r8).

🤖 Built with SMT <smt@agora.build>
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