ap-lifecycle

Session Lifecycle (Kill, Restart, Archive, GC)

When to use

You need to end, pause, recover, hide, or bulk-clean agentproto sessions — distinct from spawning (ap-spawn-agent) or waiting on them (ap-wait-fanin). Covers the full state machine: live → interrupted/killed → restarted, and live → archived/gc'd → gone from the default listing.

MCP: ending or pausing a turn

agent_kill terminates a session outright.

{ "tool": "agent_kill", "args": { "sessionId": "sess_abc123" } }

agent_interrupt cancels the in-flight turn but keeps the session alive and idle — use this instead of agent_kill when you want to redirect the agent rather than end it.

{ "tool": "agent_interrupt", "args": { "sessionId": "sess_abc123" } }

MCP: recovery

session_restart respawns an exited or killed session with conversation continuity — it does not start fresh, it resumes.

{ "tool": "session_restart", "args": { "sessionId": "sess_abc123" } }

MCP: visibility and retention

{ "tool": "session_archive", "args": { "sessionId": "sess_abc123" } }

{ "tool": "session_unarchive", "args": { "sessionId": "sess_abc123" } }

Archiving hides a session from the default list; it's reversible via session_unarchive. session_archive refuses to archive a still-live session — kill or let it finish first.

{ "tool": "session_gc", "args": { "mode": "archive", "olderThanDays": 14 } }

Bulk archives (or bulk forgets, depending on mode) terminal sessions past a retention window. Never touches sessions that are still live.

{ "tool": "session_set_keepalive", "args": { "sessionId": "sess_abc123", "keepalive": true } }

Exempts a session from the idle-reaper — use for a long-running background watcher you don't want auto-archived out from under you.

{ "tool": "session_set_pinned", "args": { "sessionId": "sess_abc123", "pinned": true } }

Pins a session so it stays at the top of listings and survives casual GC sweeps.