list_sessions

List discoverable sessions, optionally filtered by agent.

Results are sorted by date (newest first) and paginated with limit/offset so the payload stays small. The default limit guards against dumping an unbounded number of sessions.

Each summary carries kind ("agent" for a top-level session, "subagent" for a spawned subagent/sidechain) and parent_uuid (the parent session's uuid for subagents, else None). Subagent detection covers Claude, OpenCode, Codex and Pi; Antigravity's format has no parent signal, so it always reports kind="agent".

Each summary also carries the F1.4 origin fields, None when the source format has no signal (never fabricated):

• project_dir — the project directory the session ran in (Claude: transcript cwd / Desktop metadata / verified slug decode; Codex: session_meta.cwd; OpenCode: session.directory; Pi: header cwd; Antigravity: no signal).

• launch_surface — where the session was driven from (Claude: "claude-cli" | "claude-desktop"; Codex: the raw originator, e.g. "codex_vscode"; Antigravity: "antigravity-ide" | "antigravity-cli"; OpenCode/Pi: no signal).

Each summary also carries models — the unique model ids observed in the session, in order of first appearance (Claude: assistant message.model; Codex: turn_context.model; OpenCode: message.data.modelID; Pi: assistant message.model; Antigravity records no model signal). [] when the format carries no signal — honest absence, never fabricated.

Each summary also carries the A3 recency signal, measured against a single wall-clock now sampled once for the whole call:

• last_activity — the last-activity timestamp as an explicit ISO string (same instant as date; date is kept for backward compatibility);

• age_sec — whole seconds since last_activity (clamped at 0 when a future timestamp implies writer/reader clock skew);

• activity — "fresh" if age_sec is at or under the AI_R_STALL_SEC threshold (default 600 s = 10 min), "stale" if past it.

Honest contract (F1.1): activity describes only the recency of the last written record. It is not a claim about process liveness — a session file cannot show whether its producer is still running. "Running but silent" vs. "crashed" is a consumer-side inference (correlate activity == "stale" with an OS pid-alive check); ai-r does not fabricate it.

Args: agent: One of claude, codex, opencode, antigravity, pi. When omitted, every supported agent is queried. limit: Max sessions in this page. 0 means no cap (use with care: may return a very large payload). Defaults to 100. offset: Zero-based index of the first session to return. Use with limit to page through total. kind: Optional filter. "agent" returns only top-level sessions, "subagent" returns only subagent sessions. When omitted (default), both kinds are returned. noise: Noise filter — a session is noise when it is a spawned subagent (kind == "subagent" or parent_uuid set). "include" (default) returns everything, "exclude" drops noise sessions, "only" returns only noise sessions. kind and noise compose (AND). project_dir: Keep only sessions whose project_dir equals this path or is a descendant of it (path-boundary aware: /a/b matches /a/b and /a/b/sub, never /a/bc); trailing slashes ignored. Sessions without a project_dir signal never match. Composes with the other filters (AND). redact: When True (default) secrets in emitted title / extra values are masked as [REDACTED_<TYPE>] and the response carries a redactions type→count dict when any replacement happened; False returns raw titles.

Returns: {"sessions": [...], "total": int, "offset": int, "limit": int, "truncated": bool}. total is the full count matching the agent (and kind/noise) filter; truncated is True when more sessions remain beyond this page. When total == 0 the dict additionally carries diagnostics (scanned agents + session counts, source-dir presence, cause hints) so an empty inventory is explainable.