agent-pi.kdl

// Canonical hand-authored declaration for a pi agent.
//
// Copy st2's shipped `templates/bus.st2.md` into the publication bundle as `assets/bus.st2.md`.
// pi discovers `AGENTS.md` from the workspace natively, and the boot ritual st2 restores at session
// start is a pointer into that contract, not a standalone instruction — it says to set status and
// drain the inbox without naming the commands that do either.
//
// The contract alone is enough; no operator-composed persona is required. Measured twice against a
// live model, independently (`docs/vrs/.experiments/2026-08-18-pi-captures/run-h-live-provider.txt`,
// sections 6 and 7): with the contract copied verbatim, the agent set its status and drained its
// inbox on the first tool call, using the documented commands and without exploring the filesystem.
// Without it, the same prompt sent the agent hunting with `find /`, and it never set its status.
//
// To add a persona, put it in front of the contract in the same file — pi loads `AGENTS.md` or
// `CLAUDE.md` once per directory, so the workspace has exactly one slot.
//
// Unlike the Codex and Claude examples this one declares no `ding`: pi delivers natively. st2 hands
// each message to the live session through the channel extension it injects from its own verified
// hook set, so there is no screen inspection on the delivery path and nothing to render for it.
// `st2 hooks install` must have been run, exactly as for the other harnesses' lifecycle scripts.

agent "<identity>" {
  host "<host>"
  workspace "<workspace>"
  // Optional metadata:
  // role "worker"
  // supervisor "<host>.<supervisor-identity>"

  // The typed driver expands to one plain argv before task compilation; `st2 driver expand` prints
  // exactly what will run. `effort` is pi's thinking level verbatim. Anything st2 does not model
  // stays in `args`, which is passed through untouched and after the typed fields.
  pi {
    model "<provider/model>"
    effort "medium"
    prompt "<boot prompt>"
    // args "--tools" "read,bash,edit,write"
  }

  render {
    copy "assets/bus.st2.md" "AGENTS.md"
    git-exclude "AGENTS.md"
  }
}