Documentation
¶
Overview ¶
Package agentsession implements the AgentSessionUser locust test: each VU is one coding-agent session replaying a scripted step sequence (a YAML file under scripts/, selected by --agentsession-script) against a glutton actor. After every step the actor is suspended for the step's "LLM thinking" gap; by default the next step's first request wakes it through the atenet router (request parking), so the benchmark measures the user-visible wake latency Substrate's oversubscription story rests on.
Per-step timings land in locust stats as Step_<name>. The first request after each suspend is additionally recorded as WakeFirstTouch — in implicit resume mode that row IS the parking wake latency distribution.
Index ¶
Constants ¶
const DefaultScript = "coding-session"
DefaultScript is the variant a run uses when --agentsession-script is unset: the 20-step coding session.
Variables ¶
This section is empty.
Functions ¶
func Encode ¶
Encode renders a Script as YAML in the form Decode reads, with one flow-style line per op so the file reads like the step table it is.
func FormatSize ¶
FormatSize renders a byte count as a Kubernetes quantity (32Mi, 1Gi).
func Validate ¶
Validate pins a script's invariants: a usable name, a memory floor that covers what the script declares, unique non-empty steps with positive think times, and no op that consumes a sandbox object before an earlier step created it. A broken ordering would fail at run time with NotFound from glutton; this catches it when the script is loaded.
Types ¶
type Budget ¶
Budget is what a script declares it will hold in the sandbox: resident RAM (the largest fill per array) and files in the data dir (the largest object per key). The data dir is tmpfs, so both come out of the actor's memory limit. It does not model the guest's real peak: kernel, kata-agent, and Go allocator transients sit on top.
type Script ¶
type Script struct {
Name string
// MinActorMemory is the smallest actor memory limit the script is known
// to run under, in bytes. The driver refuses to start against a smaller
// template. Required, and at least the script's declared RAM plus disk
// (the data dir is tmpfs).
MinActorMemory int64
Steps []Step
}
Script is a loaded agent-session script: a named step sequence plus the actor memory it needs.
The YAML form is a direct transcription of the Go types:
name: coding-session
min_actor_memory: 1Gi
steps:
- name: 01_read_task
agent: Boots, reads the task prompt, loads its context window
think: 2s
ops:
- fill_ram: {key: agent_context, size: 32Mi}
- ping: {}
Each op is a one-key map whose key is the op kind and whose value holds that kind's arguments. Sizes are Kubernetes quantities (16Mi, 64Ki); think times are Go durations (2s, 1.5s). Unknown kinds, unknown fields, and arguments a kind does not take are errors.
type Step ¶
type Step struct {
// Name keys the step's locust stats row: Step_<Name>.
Name string
// Agent says what the coding agent is doing, for humans.
Agent string
// Think is how long the LLM "thinks" before this step. The actor is
// suspended for this gap (scaled by --agentsession-think-scale).
Think time.Duration
// Ops are the resource effects, executed in order.
Ops []op
}
Step is one agent action: what a coding agent would be doing, the think time that precedes it (the LLM producing this step), and the resource operations acting it out.
Source Files