feat: define AgentDO lifecycle contract (agent-do.contract.ts)

[stackbilt-admin]

Summary

Codify the alarm-driven autonomous agent DO lifecycle as a formal ODD contract in @stackbilt/contracts.

Background

Surveyed four existing agent DOs across the fleet (2026-06-25):

• MaraGovernorDO (colonyos) — continuous, alarm-driven, inbox polling ← source pattern
• SeraAgentDO (tarotscript) — continuous, TarotScript harness interior ← second instance
• ReviewSessionDO (codebeast) — one-shot terminal variant
• AgentSession (edgeclaw) — reactive chat session, not autonomous (out of scope)

MARA is the canonical pattern. Sera is the second concrete instance. The contract should be shaped by both, not just MARA, to avoid baking in Colony OS specifics.

Wiki canon: https://aegis.stackbilt.dev (slug: agent-do-contract-2026)

What to build

src/contracts/agent-do.contract.ts — ODD contract defining:

interface AgentDOState {
  goal: string;
  sessionId: string;
  lastObservation: string;
  // agents extend with domain fields
}

interface AgentDOContract {
  tick(state: AgentDOState): Promise<TickResult>;
  pollInbox?(): Promise<string>;
  onGoalUpdate?(newGoal: string): Promise<void>;
}

State machine: created → idle → ticking → idle (continuous) or ticking → terminal (one-shot).

Operations: create, setGoal, pause, resume, terminate.

Invariants:

• lastObservation MUST be persisted after every tick
• goal MUST be non-empty before tick fires
• Sole-writer: no cross-agent state access

Sequencing note

Do not extract until Sera's DO is built. The contract should be shaped by two concrete instances (MARA + Sera), not one. This issue tracks the contract definition; tarotscript#TBD tracks Sera's build.

OSS policy

Additive-only, no product logic, no domain state. The base interfaces are generic enough to publish.

🤖 Generated with Claude Code