overlord/AGENTS.md

Repository instructions for AI agents

These instructions apply to the entire repository.

Wire protocol changes

The server and client share a versioned MessagePack contract. Treat protocol/wire-contract.json as the canonical source of truth. Do not manually edit either generated artifact:

• Overlord-Server/src/generated/wire-contract.ts
• Overlord-Client/cmd/agent/wire/wire_contract_generated.go

When adding a command or message type, update the appropriate array in protocol/wire-contract.json in the same change as its implementation.

Breaking changes to a specific command

A breaking change to an existing command must receive a new command version. Never silently change the version 1 payload or semantics.

Changes that require a new command version include:

• removing or renaming a field;
• changing a field's type, units, default, valid range, or meaning;
• making a previously optional field required;
• changing command result or failure semantics.

For the affected command, update commandVersioning.overrides in protocol/wire-contract.json:

1. If the command has no override, add one with latestVersion: 2.
2. If it already has an override, increment latestVersion by exactly one.
3. Add a changes entry whose key is the new version.
4. Set breaking to true and provide non-empty summary and migration text describing the wire change and how an older payload maps to the new one.
5. Keep versions contiguous. Do not delete or rewrite documentation for an already released version.

Example for a command moving from version 1 to version 2:

"desktop_start": {
  "latestVersion": 2,
  "changes": {
    "2": {
      "breaking": true,
      "summary": "Replace numeric quality with a named profile",
      "migration": "Map quality 1-40 to low, 41-80 to balanced, and 81-100 to high"
    }
  }
}

Implement and retain handlers for every supported version. At target-aware server send sites, use versionCommandForClient so the server selects the highest mutually supported version. Once a command supports multiple versions, it must not be encoded without an explicit negotiated commandVersion.

Add compatibility tests covering at least:

• the old command version and payload;
• the new command version and payload;
• version negotiation with old and new clients;
• migration or rejection behavior at the compatibility boundary.

Update tests that intentionally assert version ranges, including Overlord-Server/src/protocol-contract.test.ts, Overlord-Server/src/command-compatibility.test.ts, and Overlord-Client/cmd/agent/wire/wire_contract_test.go, when applicable.

Additive and protocol-wide changes

Adding an optional field without changing existing behavior is additive and does not require a command-version bump.

Removing or redefining a non-command wire value, changing message framing or encoding, or otherwise breaking the overall wire contract requires incrementing protocolVersion in protocol/wire-contract.json. Preserve compatibility with older protocol versions or add an explicit rejection path and tests. Increment schemaVersion only when the structure of wire-contract.json itself changes; update protocol/wire-contract.schema.json in the same change.

Generate and verify protocol artifacts

After every edit to protocol/wire-contract.json, run these commands from the repository root:

bun scripts/generate-wire-protocol.ts
bun scripts/generate-wire-protocol.ts --check

Commit the JSON contract and both regenerated artifacts together. Before finishing, also run:

cd Overlord-Server
bun run typecheck
bun test src/protocol-contract.test.ts src/command-compatibility.test.ts

cd ../Overlord-Client
go test ./cmd/agent/wire

Run additional focused tests for every server sender, client handler, and payload migration changed by the new command version. Consult protocol/README.md for the complete compatibility policy.