mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

adr: define stable agent platform interface contract (execute / getEvents / emitEvent / wake / provision) #36

New Issue
Open
opened 2026-06-05 18:39:35 +00:00 by mathias · 1 comment
mathias commented 2026-06-05 18:39:35 +00:00
Owner
Copy Link
Copy Source

Context

Anthropic's Managed Agents engineering blog (2026-04-08) documents a design decision directly applicable to the homelab platform: stable interfaces over stable implementations. The five canonical calls they settled on are:

  • execute(name, input) → string — invoke a hand (sandbox or tool)
  • getEvents(sessionId, slice) — read positional slices of the session log
  • emitEvent(sessionId, event) — write a durable event during the agent loop
  • wake(sessionId) — reboot a crashed harness and resume from last event
  • provision({resources}) — spin up a new sandbox on demand

The principle: these names stay constant; implementations underneath change freely. This is the OS-abstraction pattern — read() is agnostic whether it's a 1970s disk pack or an SSD. Same idea here.

The homelab currently has:

  • hyperguild as the harness layer
  • agentsquad as the many-brains/many-hands orchestration layer
  • mcp-chassis implementing the credential proxy pattern (structurally equivalent to Managed Agents' vault-backed MCP proxy)

None of these have an explicit, written interface contract that defines what names are stable across harness evolution. Without it, any harness change risks requiring data migration or breaking agentsquad ↔ hyperguild coordination.

Why now

This is a prerequisite to the skills platform overhaul (#25) and any future multi-agent work — those assume a stable calling convention. Defining the contract costs little now; retrofitting it after three harness generations costs a lot.

The brain note knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md has the full Managed Agents → homelab mapping table as a starting point.

Deliverable

An ADR written to docs/adr/NNNN-agent-platform-interface-contract.md in this repo (or mathias/infra, whichever is the canonical ADR home) covering:

  • The five interface names and their signatures, adapted for Go/homelab conventions
  • Which component owns each interface (e.g. session log → what backs it on koala; execute → routing pod? agentsquad?)
  • Credential isolation contract: what layer holds credentials, what layer never sees them
  • Session recovery contract: how a crashed harness resumes (wake equivalent)
  • Explicit statement of what is not stabilised (harness internals, model routing logic, sandbox implementation)

Relationship to open issues

  • Blocks or informs #25 (skills overhaul) — skill invocation is a "hand"; the interface name matters
  • Informs agentsquad design — flat peer-to-peer is the "many brains" pattern; the ADR should confirm agentsquad is the canonical many-hands layer
  • Does not block #35 (routing bootstrap) or #32 (brain injection) — those are independent

References

  • Anthropic engineering blog: https://www.anthropic.com/engineering/managed-agents
  • brain: knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md
  • mathias/agentsquad — homelab many-hands implementation
  • mathias/mcp-chassis — credential proxy (Managed Agents vault pattern equivalent)
## Context Anthropic's Managed Agents engineering blog (2026-04-08) documents a design decision directly applicable to the homelab platform: **stable interfaces over stable implementations**. The five canonical calls they settled on are: - `execute(name, input) → string` — invoke a hand (sandbox or tool) - `getEvents(sessionId, slice)` — read positional slices of the session log - `emitEvent(sessionId, event)` — write a durable event during the agent loop - `wake(sessionId)` — reboot a crashed harness and resume from last event - `provision({resources})` — spin up a new sandbox on demand The principle: these names stay constant; implementations underneath change freely. This is the OS-abstraction pattern — `read()` is agnostic whether it's a 1970s disk pack or an SSD. Same idea here. The homelab currently has: - **hyperguild** as the harness layer - **agentsquad** as the many-brains/many-hands orchestration layer - **mcp-chassis** implementing the credential proxy pattern (structurally equivalent to Managed Agents' vault-backed MCP proxy) None of these have an explicit, written interface contract that defines what names are stable across harness evolution. Without it, any harness change risks requiring data migration or breaking agentsquad ↔ hyperguild coordination. ## Why now This is a *prerequisite* to the skills platform overhaul (#25) and any future multi-agent work — those assume a stable calling convention. Defining the contract costs little now; retrofitting it after three harness generations costs a lot. The brain note `knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md` has the full Managed Agents → homelab mapping table as a starting point. ## Deliverable An ADR written to `docs/adr/NNNN-agent-platform-interface-contract.md` in this repo (or `mathias/infra`, whichever is the canonical ADR home) covering: - [ ] The five interface names and their signatures, adapted for Go/homelab conventions - [ ] Which component owns each interface (e.g. session log → what backs it on koala; execute → routing pod? agentsquad?) - [ ] Credential isolation contract: what layer holds credentials, what layer never sees them - [ ] Session recovery contract: how a crashed harness resumes (`wake` equivalent) - [ ] Explicit statement of what is **not** stabilised (harness internals, model routing logic, sandbox implementation) ## Relationship to open issues - Blocks or informs #25 (skills overhaul) — skill invocation is a "hand"; the interface name matters - Informs agentsquad design — flat peer-to-peer is the "many brains" pattern; the ADR should confirm agentsquad is the canonical many-hands layer - Does **not** block #35 (routing bootstrap) or #32 (brain injection) — those are independent ## References - Anthropic engineering blog: https://www.anthropic.com/engineering/managed-agents - brain: `knowledge/claude-managed-agents-architecture-notes-relevant-to-homelab-agent-platform.md` - `mathias/agentsquad` — homelab many-hands implementation - `mathias/mcp-chassis` — credential proxy (Managed Agents vault pattern equivalent)
mathias commented 2026-08-19 18:19:59 +00:00
Author
Owner
Copy Link
Copy Source

DECISION NEEDED

Question: Does a stable multi-harness interface contract (execute/getEvents/emitEvent/wake/provision) still make sense now that #75 consolidated to a single harness, or should this close/re-scope?

Context: This issue's whole premise is that hyperguild + agentsquad + mcp-chassis are separate harness/orchestration layers that need a stable calling convention between them so future harness evolution doesn't break their coordination. Per #75 (closed 2026-08-19): agentsquad's peer-to-peer/multi-agent capability was explicitly dropped, not carried forward into hyperguild ("icebox, no resurrection commitment"). The live harness is now cmd/hyperguild alone + brain-mcp + gitea-mcp. There may no longer be a second harness for this interface to mediate between.

Options:

  • A) Close as obsolete — a single-harness system doesn't need a stable-interface abstraction over harness variation; revisit if/when a second harness is ever added for real. Cheapest, honest given #75's decision.
  • B) Re-scope narrower — keep the ADR, but drop the agentsquad "many-hands" framing and write it as cmd/hyperguild ↔ mcp-chassis's own credential-proxy contract instead (still two real components, still worth stabilizing).
  • C) Leave as-is — the interface contract is still worth writing pre-emptively even with one harness today, as a discipline for whatever's added next.

Recommendation: A — #75's decision already answered the "how many harnesses" question this issue assumed was still open; a contract for a coordination problem that no longer exists is speculative work, and the general-purpose principle (stable names, swappable implementations) can be revisited cheaply if a second harness is ever actually built.

Blocks: nothing else currently — this issue isn't in another issue's dependency chain per my check. Not closing myself; this is your call, not an autonomous one. Cascade re-triage per hyperguild#75, 2026-08-19.

## DECISION NEEDED **Question:** Does a stable multi-harness interface contract (execute/getEvents/emitEvent/wake/provision) still make sense now that #75 consolidated to a single harness, or should this close/re-scope? **Context:** This issue's whole premise is that hyperguild + agentsquad + mcp-chassis are separate harness/orchestration layers that need a stable calling convention between them so future harness evolution doesn't break their coordination. Per #75 (closed 2026-08-19): agentsquad's peer-to-peer/multi-agent capability was explicitly dropped, not carried forward into hyperguild ("icebox, no resurrection commitment"). The live harness is now `cmd/hyperguild` alone + brain-mcp + gitea-mcp. There may no longer be a second harness for this interface to mediate between. **Options:** - A) Close as obsolete — a single-harness system doesn't need a stable-interface abstraction over harness variation; revisit if/when a second harness is ever added for real. Cheapest, honest given #75's decision. - B) Re-scope narrower — keep the ADR, but drop the agentsquad "many-hands" framing and write it as `cmd/hyperguild` ↔ `mcp-chassis`'s own credential-proxy contract instead (still two real components, still worth stabilizing). - C) Leave as-is — the interface contract is still worth writing pre-emptively even with one harness today, as a discipline for whatever's added next. **Recommendation:** A — #75's decision already answered the "how many harnesses" question this issue assumed was still open; a contract for a coordination problem that no longer exists is speculative work, and the general-purpose principle (stable names, swappable implementations) can be revisited cheaply if a second harness is ever actually built. **Blocks:** nothing else currently — this issue isn't in another issue's dependency chain per my check. Not closing myself; this is your call, not an autonomous one. Cascade re-triage per hyperguild#75, 2026-08-19.
mathias added the risk/lowsize/mtype/decision labels 2026-08-27 05:25:41 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels risk/low size/m type/decision
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#36