pi-server AGENTS.md

AGENTS.md — Crystallized Learnings for pi-server

This document captures patterns, anti-patterns, and gotchas discovered during development. Read this before working on pi-server.

Because parent/global AGENTS files are concatenated into every session, keep this file repo-specific and prefer pointing to canonical docs instead of duplicating large policy blocks.

---

Canonical References

Start here before changing behavior that crosses repo boundaries:

• README.md — package shape, architecture overview, release flow
• PROTOCOL.md — wire contract and client-visible semantics
• docs/release-policy.md — commit, changelog, and breaking-change policy
• next_session_prompt.md — current handoff / immediate priorities

---

Architecture Principles

1. The protocol IS the architecture — types.ts is the single source of truth
2. Server should be thin — AgentSession does the work, we just multiplex
3. Pass-through pattern — Session commands are thin wrappers around AgentSession methods
4. Handler map > switch — Record<string, CommandHandler> for O(1) dispatch, easy extension
5. Extract to stores — State with independent lifecycle gets its own module
6. SessionResolver is the NEXUS seam — Interface for session access enables test doubles

---

ADR-0001: Atomic Outcome Storage

Status: Accepted (2026-02-22)

Full ADR: docs/adr/0001-atomic-outcome-storage.md

The Invariant

Same command ID must ALWAYS return the same response. Not "usually." Not "after the callback completes." ALWAYS.

Three Critical Rules

1. Store BEFORE return — Outcomes are stored before the response is returned, not in async callbacks
2. Timeout IS a response — Timeout responses are stored as valid outcomes (with timedOut: true)
3. Replay is FREE — Replay operations are O(1) lookups, exempt from rate limiting

Code Pattern

// WRONG: Async callback creates race condition
commandExecution.then((response) => {
  this.storeOutcome(commandId, response);  // After return
});
return withTimeout(commandExecution, ...);

// CORRECT: Atomic storage before return
let response: RpcResponse;
try {
  response = await executeWithTimeout(commandExecution, ...);
} catch (error) {
  response = { success: false, error: error.message, timedOut: true };
}
this.storeOutcome(commandId, response);  // BEFORE return
return response;