docs(sdk): add normative invariants to architecture docs

[enyst]

HUMAN: I’ve been thinking for a while that maybe it will help LLMs to

• avoid weird behavior drift when they make PRs: if they have or can have a little better understanding of the relationships between components / classes / packages or intent behind them.
• see stricter language: reinforce intent by constraints in a more formal language. Here, OCL, an invariant-expressions language complementing UML - probably forgotten by humans, but LLMs know it. (and I think maybe it's simple enough to read as English)

I asked OH to model the first few layers of the SDK (I think it only did the first in-package layer, will come back to that if we want this) and add constraints in both natural language and, if simple, in good old OCL.

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

——

Summary of changes

• Added "Invariants (Normative)" sections across SDK architecture docs (design, agent, conversation, events, tool system, workspace)

• Included OCL-like invariants where simple and precise natural-language invariants where complex

• Fixed/maintained MDX structure so tables/mermaid blocks render correctly

• closes Analyze the SDK and model it software-agent-sdk#1815

@enyst can click here to continue refining the PR

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • .github/workflows/sync-agent-sdk-openapi.yml
  • .github/workflows/sync-docs-code-blocks.yml

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #274 at branch `openhands/sdk-arch-1815`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[enyst]

@OpenHands The trouble with this PR is that it displays our OCL constraints in the user-facing docs, but they are meant for AI agents, not for humans.

I think we have two options:

• either insert them as html comments or something that is invisible to the user, but accessible to LLMs when AI agents read the pages
• or, maybe we can create / modify / fix llms.txt and the full variant of it, so that it includes those sections, but the user-facing docs doesn't. (look up on the net the llms.txt emerging standard to see what it should work like)

WDYT? Answer me directly on github, in a comment you post to this PR. Note that it will be rendered as markdown.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

I did not make any repository changes in this interaction. I answered the PR comment question by recommending how to handle the OCL constraints so they’re available to AI agents but not shown in user-facing docs:

• Prefer option 1 as the immediate fix: keep the natural-language invariants visible, but move the OCL blocks into HTML comments (non-rendered) with clear sentinels like <!-- AI_INVARIANTS_BEGIN --> ... <!-- AI_INVARIANTS_END --> so agents can reliably extract them.
• Treat llms.txt / llms-full.txt as a potential follow-up packaging step (useful long-term, but adds maintenance/drift considerations), not the primary solution.
• I provided a ready-to-paste Markdown PR comment expressing that recommendation.

No git diff to review, no commits, and nothing to push.

[enyst]

@OpenHands Merge main and fix conflicts. Then read all comments to this PR, and implement Option 1: keep the natural-language invariants visible, but move the OCL blocks into HTML comments (non-rendered) with clear sentinels like ... so agents can reliably extract them.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Summary of new changes since my last update:

• Added an AGENTS.md note documenting the AI-only invariant comment convention (OCL blocks wrapped in AI_INVARIANTS_BEGIN/END HTML comments).

Checklist:

• Request fully addressed (documented the convention for future edits).
• Changes are concise (single AGENTS.md addition, no extraneous edits).
• Changes pushed to the remote branch.

Note: I did not re-check git diff here because you asked for no tool calls.

[enyst]

I moved these invariants in llms.txt, instead of human-facing .mdx files.

The docs pages are for humans, but this information is just a restatement in more formal language intended for agents, not for humans.

@xingyaoww WDYT about this solution?

[all-hands-bot]

🟡 Acceptable - Clean pattern, but needs verification and refinement

Taste Rating: The sidecar file pattern is elegant and the separation of concerns is good. However, the value proposition is speculative and some content needs refinement.

---

Verification Status

I cloned software-agent-sdk and verified key invariants against source code:

✅ Verified Correct:

• AgentBase has frozen=True in model_config
• Event has frozen=True and extra="forbid"
• Conversation factory returns RemoteConversation when workspace is RemoteWorkspace
• Tool naming: TerminalTool → terminal (via _camel_to_snake().removesuffix("_tool"))
• Workspace factory returns RemoteWorkspace when host is provided
• Multi-action batching: _combine_action_events asserts empty thought for all but first action

The invariants I spot-checked are accurate. Good work on verification.

---

Key Issues

🟠 Important: Value Proposition Unclear

The PR description says this "maybe" will help LLMs avoid drift, but provides no concrete evidence:

• No examples of drift this would prevent
• No measurement or testing against actual LLM behavior
• No comparison before/after

Recommendation: Either demonstrate measurable benefit (e.g., "this prevents X type of invalid PR") or frame this as an experiment to gather data.

🟡 Suggestion: Design Commentary vs Normative Constraints

Several invariant files include design discussions (especially workspace.ai-invariants.md pause/resume section). This is valuable context but blurs the line between "normative constraint" and "architectural commentary."

Consider:

• Creating a separate section for "Design Discussions" or "Open Questions"
• Keeping "Invariants (Normative)" strictly to verifiable contracts
• Moving design rationale to the main .mdx files where humans can also benefit

🟢 Acceptable: Unrelated Formatting Changes

Some .mdx files have whitespace changes (trailing newlines, blank line cleanup) that are unrelated to the main PR goal. Not a blocker, but ideally these would be in a separate cleanup commit.

[all-hands-bot]

🟡 Suggestion: This discussion is valuable but doesn't belong in "Invariants (Normative)".

Recommendation: Move this design smell discussion to either:

1. A "Design Rationale" section in workspace.mdx (where humans can see it)
2. A separate workspace.design-discussion.md file
3. Or at minimum, retitle this section "Design Discussion: pause/resume semantics"

Normative invariants should be contracts that can be verified/enforced, not open-ended design debates.

[all-hands-bot]

🟢 Nit: This entire "File Organization" section describes project conventions, not runtime invariants.

It's useful content, but consider whether it belongs in:

• The main tool-system.mdx page (for human readers)
• A separate "SDK Conventions" doc
• Or a different section title like "## Code Organization Patterns (Informative)"

Not a blocker, just a categorization question.

[xingyaoww]

My only concern here is how do we keep this up-to-date :(

We have a lot of docs (for human) and sometimes it is already hard to make sure they are accurate and up-to-date..

Maybe we will need some CI that runs periodically that updates these?