xa.sessions

The unified Session domain model and multi-host discovery.

This layer is the single thing CLI / HTTP / UI renderers iterate over. Discovery and actions are delegated to xa.hosts; this module composes them into a host-agnostic API.

class xa.sessions.Session(id: str, claude_session_id: str | None, bridge_session_id: str | None, host: str, cwd: str | None, project_slug: str, state: Literal['live', 'archived', 'transcript_only'], live_pid: int | None, tmux_name: str | None, name: str | None, summary: str | None, first_user_message: str | None, turn_count: int, forked_from: str | None, created: float | None, modified: float | None, url: str | None, url_source: Literal['session_file', 'pane_capture'] | None, transcript_path: Path | None, pre_first_turn: bool = False)[source]

Canonical session record — valid across hosts and states.

Fields that don’t apply to a given state are None. Discovery functions return fresh instances; callers should treat it as immutable.

xa.sessions.get_session(session_id: str, *, hosts: Iterable | None = None, claude_home: Path | None = None) → Session | None[source]

Find one session by full ID or unique prefix.

Raises LookupError if the prefix is ambiguous.

xa.sessions.iter_local_sessions(*, claude_home: Path = PosixPath('/home/runner/.claude'), project_slug: str | None = None, include_live: bool = True, tmux_bin: str | None = None) → Iterator[Session][source]

Legacy local-only iterator.

Retained for backward compatibility and because some tests construct sessions directly from a fake ~/.claude/. Wraps a fresh LocalHost.

xa.sessions.kill_session(session: Session, *, hosts: Mapping[str, object] | None = None) → None[source]

Kill the backing tmux session of a live Session.

xa.sessions.list_sessions(*, hosts: Iterable | None = None, project: str | None = None, include_forks: bool = True, include_live: bool = True, state: Literal['live', 'archived', 'transcript_only'] | None = None, limit: int | None = None, claude_home: Path | None = None, tmux_bin: str | None = None) → list[Session][source]

Return sessions sorted by recency (live first, then newest-modified).

When hosts is None we default to a single LocalHost. If claude_home or tmux_bin are given, they’re forwarded into that default LocalHost — handy for fixture-based tests.

Filters:

  • project — substring match against cwd (case-insensitive)

  • include_forks=False — drop sessions with a forked_from

  • include_live=False — skip live discovery (per host)

  • state — one of "live" / "archived" / "transcript_only"

xa.sessions.resume(session: Session, *, cwd: str | None = None, name: str | None = None, hosts: Mapping[str, object] | None = None, **opts) → SpawnResult[source]

Resume a transcript / archived session on its originating host.