ppsspp_session
Manage PPSSPP debug sessions: start, stop, list, or inspect them, and wait until the emulated CPU boots before any memory or disassembly call.
Instructions
PURPOSE: Start / stop / inspect PPSSPP debug sessions — action=list / start / stop / get / wait_ready; wait_ready blocks until the emulated CPU is up.
USAGE: action='list' takes no other params and returns {sessions, count} (idle sessions >30min are auto-GC'd as a side effect; NOT a per-session health probe — use ppsspp_health(session_id=...) for that); action='start' needs iso_path (pass wait_ready=true to block until the CPU is up in the same call); stop/get/wait_ready need session_id. Call wait_ready AFTER start and BEFORE any memory tool — PPSSPP answers WebSocket before the CPU boots. start(resilient=true) self-heals boot wedges (blacklist quarantine + relaunch with the same session_id, ≤2 retries).
BEHAVIOR: STATE-CHANGE. start spawns a PPSSPP subprocess + WS debugger; stop terminates it (never taskkill the process yourself); wait_ready polls the probe lock-free and fails [BOOT_TIMEOUT] on wedge suspicion; list/get are read-only.
RETURNS: action=start/get → SessionResponse {session_id, iso_path, pid, ws_url, created_at, last_active_at, exec_count, ws_connected, recovered, restored (1 = session record was restored from sessions.json after a server restart, 0 = created in this process), ppsspp_version}; action=wait_ready → {action, ready, elapsed_s, probe_addr, probe_value, note} — elapsed_s is THIS call's wait duration, not the start→ready total; action=list → {sessions: [SessionResponse...], count}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Session operation. Valid values: - 'list': list all active sessions (no other params). Idle sessions (>30 min) are auto-GC'd as a side effect; returns {sessions, count}. NOT a per-session health probe — use ppsspp_health(session_id=…) for that. - 'start': launch a new PPSSPP session (requires iso_path). Set wait_ready=true to block until the emulated CPU is up (same probe/budget semantics as 'wait_ready'). - 'stop': terminate an existing session (requires session_id). - 'get': query session health (requires session_id). - 'wait_ready': block until the emulated CPU has started (requires session_id). Call this after 'start' BEFORE any memory/disassembly tool — PPSSPP answers WebSocket before the ISO finishes booting, and early reads fail with 'CPU not started'. | |
| iso_path | No | Absolute path to the ISO file (required when action=start). | |
| resilient | No | action=start only: self-healing boot — on wedge evidence (CPU-ready probe exhausted, handshake never accepted, process died) the launcher is torn down, the GPU-backend failure blacklist is quarantined (rename), and the session relaunches with the SAME session_id up to 2 retries; the response carries recovered=N (0 = first launch). Exhaustion raises [BOOT_TIMEOUT]. Ignored in fake mode. | |
| timeout_s | No | Boot budget in seconds (action=wait_ready, action=start with wait_ready=true, or the per-attempt CPU-ready budget when action=start with resilient=true; default 75, clamped to [1, 300]). | |
| probe_addr | No | Hex address polled by the readiness probe (action=wait_ready, action=start with wait_ready=true, or the resilient-start gate; default '0x08804000', the project's top.prx load base). | 0x08804000 |
| session_id | No | Session ID (required when action=stop / get / wait_ready). | |
| wait_ready | No | action=start only: block until the emulated CPU is ready before returning (same probe/budget as action=wait_ready; raises [BOOT_TIMEOUT] on wedge suspicion). Fake test mode is ready immediately. Default true: start() returns a session that is ready to use, so the first tool call does not fail with a version-handshake timeout. Pass false only when you want the raw launch without waiting. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pid | No | PPSSPP process PID (None if stopped). | |
| note | No | Optional human context (e.g. fake-mode short-circuit). | |
| count | No | Number of sessions. | |
| ready | No | True when the CPU-start probe succeeded. | |
| action | No | Literal 'wait_ready' (echoes the session action). | |
| ws_url | No | WebSocket URL (ws://host:port/debugger). | |
| iso_path | No | Absolute path to the ISO file. | |
| restored | No | 1 when this session was restored from sessions.json (a previous server run left it behind) rather than started fresh in this process — its game state may be stale. | |
| sessions | No | Active sessions. | |
| elapsed_s | No | Wall-clock seconds spent polling. | |
| recovered | No | resilient-start relaunch count (0 = the first launch succeeded; >0 means the game state was reset by a wedge heal — breakpoints need re-arming). | |
| created_at | No | ISO 8601 timestamp of session creation. | |
| exec_count | No | Number of tool calls made against this session. | |
| probe_addr | No | Polled address, hex string (default top.prx base). | |
| session_id | No | Session UUID-like identifier. | |
| probe_value | No | u32 read at probe_addr once ready, hex string (None in fake mode). | |
| ws_connected | No | True if WebSocket is currently connected. | |
| last_active_at | No | ISO 8601 timestamp of last tool call. | |
| ppsspp_version | No | PPSSPP build fingerprint captured from the version handshake (None until the session transport binds). |