List running emulated PET sessions (name, model, pid, monitor port).

Boot a fresh emulated PET (headless, warp). Models: pet2001-4k, pet2001, pet3032, pet4032, pet8032, pet8296. Optionally attach a d64/d80/d82 disk image.

Stop a running PET session (the only one if name is omitted).

Reset the PET (soft, or hard power-cycle). Leaves the machine running.

The session and whether the machine is running or stopped right now. state is answered by the session daemon's own tracking (no emulator traffic); "unknown" without a daemon.

Read the PET screen as plain text. This is the PREFERRED way to see program output — faster and more reliable than screenshots for AI use.

Save a PNG screenshot. Prefer pet_screen_text for reading output; use this only when pixel-level appearance matters.

Read emulated memory. addr accepts $hex, 0xhex, decimal, or a symbol from the loaded label file. Returns hex-encoded bytes plus "bytes" as a decimal int array.

Search memory for a byte pattern (values: one or more $hex/decimal bytes). Returns match addresses; "truncated" is true when limit clipped the list. Does not disturb run/stop state.

Write bytes to emulated memory. addr accepts $hex/0xhex/decimal/symbol.

Read CPU registers. PC is annotated with the nearest symbol when a label file is loaded.

Set a CPU register (e.g. PC, A, X, Y). value accepts $hex/0xhex/decimal.

Set a breakpoint at an address or symbol. Machine keeps running; use pet_wait_break to block until it fires.

List breakpoints/watchpoints with hit counts.

Remove a breakpoint/watchpoint by id.

Remove ALL breakpoints (exec checkpoints); watchpoints are kept. Checkpoints persist across pet_run/rebuilds — clear stale ones or duplicates accumulate.

Remove ALL watchpoints (load/store checkpoints); breakpoints are kept.

Set a watchpoint on a memory range (default: both load and store).

Execute N instructions. The machine STAYS STOPPED afterwards; use pet_continue to resume.

Run until the current subroutine returns. Machine stays stopped.

Resume execution after a breakpoint/step.

Run until an address/symbol is executed count times; machine stays stopped there. count>1 = deterministic frame stepping on a loop label. On timeout: raises with the machine LEFT RUNNING and the checkpoint removed.

Block until TEXT appears on the screen. A timeout returns {"fired": null, "screen": ...} (not an error) so you can inspect what the program actually displayed.

Block until the byte at addr equals the value ($hex/decimal accepted).

Block until a breakpoint/watchpoint fires; reports checkpoint id, PC, and registers. Machine is left stopped when it fires. On timeout the machine is LEFT RUNNING (your checkpoints remain set) and the result is {"fired": null, "machine": "running", ...} — data, not an error.

Assemble 6502 source (ca65 syntax) to a .prg + VICE label file.

Package a .s/.bas/.prg into an artifact any VICE user can run: a .prg, or (when output ends in .d64/.d80/.d82) a disk image whose first file is the program so xpet out.d64 autostarts it. Returns the exact run command in "run".

Build/tokenize a .bas/.s/.prg as needed, then load and RUN it on the running PET. Registers assembly symbols on the session automatically.

Load a .prg via autostart (optionally without RUN); optionally register a VICE label file for symbolic debugging.

Type BASIC program text into the running PET via the keyboard (keywords may be upper or lower case; each line ends with \n). Set run=true to type RUN afterwards.

Create a blank d64/d80/d82 disk image.

List the directory of a disk image.

Copy a host file onto a disk image.

Copy a file off a disk image to the host.

Attach a disk image to the running PET and LOAD+RUN its first file.

Identify the loaded ROM set (names + content hashes).

Disassemble live memory with ROM + session symbol annotations. start accepts $hex/0xhex/decimal or a symbol (e.g. CHROUT).

Run a declarative YAML test (boots its own fresh PET; see spec §8).

Run every example-program directory (program + expect.txt) as a test.