Module session 

Compatibility path for canonical sessions and native codecs.

Structs

CrossSurface

ORCH-3: a conversation moved to another surface (Hermes handoff_*).

OpenCodeSqliteStoreStats

Cheap store-level counts — COUNT(*) only, no row hydration — for inspect’s “reports the audited real store’s sessions, messages, and parts” summary (PARITY-3 AC01).

OrchestrationNouns

ORCH-6: the ORCH-3 conversation nouns as one additive wire block, carried by harness.v1.sessions.discover / sessions.load rows and by crate::catalog::SessionDescriptor. Every field is optional so an older client sees exactly the shape it already knows.

Recurrence

ORCH-3: the job a recurring session belongs to.

Session

A normalized, replayable conversation loaded from a tool’s session log.

SessionMeta

SurfaceKey

ORCH-3: the conversation identity on a surface. Full tuple on a channel; degenerate (all None) on a terminal.

WorkspaceRef

ORCH-6: the wire form of [SessionMeta::workspace] — a typed workspace carried on a discovered or loaded row. The D2 precedence that produces it lives in workspace() (ORCH-3’s contract); this only names the result.

Enums

OpenCodeStorageSurface

Which on-disk OpenCode storage surface is present under a data root (docs/interop/opencode-pi-spec.md §1.2/S9a): SQLite opencode*.db (or $OPENCODE_DB), legacy JSON tree generation B, or legacy JSON tree generation A. This is a filesystem classifier only — it answers “which generation is this?” for a corpus-discovery tool; it does not itself read/parse the surface. See Session::from_opencode_str’s docs for the envelope form any of these three surfaces synthesizes into, and Session::from_opencode_sqlite (PARITY-3/PARITY-16) for the rusqlite reader that reconstructs that same envelope form from Sqlite’s rows — JsonTreeA/JsonTreeB remain classifier-only (their session_diff round-trips via the JSON store per upstream’s own behavior even on a SQLite install, so nothing is silently lost by not reading the legacy trees directly).

SessionFormat

An on-disk session format supercode can both read and write.

SessionSource

Which tool produced a session log.

Trigger

ORCH-3: why a session exists (the trigger noun; docs/HERMES-IDEAL-SUPPORT-DESIGN.md §3).

WorkspaceKind

ORCH-3 / UNI-9: the typed workspace, derived — never stored.

Constants

OPENCODE_COMPACTED_TOOL_PLACEHOLDER

The placeholder opencode’s own replay substitutes for a tool part’s output once state.completed.time.compacted is set (message-v2.ts:293-296 @fd9ee43) — the REAL output is never actually erased from the record (S1); it survives in raw and in this loader’s metadata["oc_tool_output_compacted"].

Functions

detect_opencode_storage_surface

Probe data_root (e.g. ~/.local/share/opencode) for the OpenCode storage surface present, per the discovery rules frozen in docs/interop/opencode-pi-spec.md §1.2/S9a: $OPENCODE_DB wins outright; otherwise glob opencode*.db (not just opencode.db — dev/beta channels suffix the filename, database.ts:43-55); otherwise look for the JSON tree generation-B marker (storage/migration); otherwise generation-A’s project/ subtree. Returns None if nothing is found.

hermes_cron_job_id

Hermes cron fire session ids are minted as cron_<job_id>_<YYYYMMDD_HHMMSS> (cron/scheduler.py); recover the job id.

hermes_trigger_for_source

Hermes sessions.source → trigger. Cron fires are tagged cron; the CLI, TUI and ACP adapter are human surfaces; api_server is the HTTP API; webhook is inbound; every other value is a messaging platform.

looks_like_sqlite

Whether path should be routed to the OpenCode SQLite loader instead of the UTF-8 text path (PARITY-16): true when the file’s first 16 bytes are the SQLite magic, OR its extension is .db — the latter so a corrupted/truncated opencode*.db still gets rusqlite’s own “not a database” diagnostic (PARITY-3 AC03) instead of a confusing UTF-8 error. A non-existent path is NOT considered SQLite here — the missing-file diagnostic in that case comes from the normal load path (with_context at the CLI call sites), which already names the path clearly.

openclaw_agent_id_from_path

OpenClaw sessions live under agents/<agentId>/…; the agent id is the profile.

opencode_sqlite_corpus_envelope_text

Combined envelope text spanning every session in db_path (or up to limit_sessions) — for corpus-style scanning (the OpenCode SQLite corpus-audit path, PARITY-4). Safe to concatenate multiple sessions’ records into one text even though Session::from_opencode_str itself only keeps the LAST session line (single-session semantics) — the audit line-classifier (audit_opencode_line) scores each line independently and doesn’t care about session boundaries. Use Session::from_opencode_sqlite to load one session as a real Session.

opencode_sqlite_primary_id

D6: the same “most-recently-updated top-level session” selection Session::load/Session::from_opencode_sqlite make by default when no explicit session id is given — exposed so a CLI-level warning can name which one was chosen.

opencode_sqlite_session_ids

D6: list every session id in an OpenCode SQLite store (oldest first) — exposed so CLI callers (convert, inspect) can detect a multi-session store and warn before Session::load/Session::from_opencode_sqlite silently picks just the primary one. Previously nothing surfaced this: convert opencode.db --to X converted 1-of-N sessions with no warning and no way to name a different one.

opencode_sqlite_store_stats

Count sessions/messages/parts/todos in a real OpenCode SQLite store without loading any of them (PARITY-3 AC01).

parse_hermes_session_key

Parse a Hermes gateway session key (agent:<profile|main>:<platform>:<chat_type>[:<chat_id>][:<thread_id>][:<participant>]). Returns the surface and the profile namespace (None for main).

parse_openclaw_session_key

Parse an OpenClaw gateway session key. Shapes (docs/channels/channel-routing.md, docs/automation/cron-jobs.md, docs/cli/acp.md upstream): agent:<id>:main, agent:<id>:<channel>:<group|channel>:<cid>[:thread|topic:<tid>], cron:<jobId>, hook:<name>:<id>, acp-bridge:<uuid>.

resolve_opencode_parent_tool_use_ids

Resolve each opencode subagent (task) child session’s meta.parent_tool_use_id from its parent’s own task tool part callID (docs/interop/opencode-pi-spec.md §2.1 — the analogue of Claude Code’s agentId/parent_tool_use_id linkage, opencode-fields.md task.ts:145,171-176).