session.*

The gateway exposes two parallel session namespaces — sessions.* (the live database-backed store) and session.* (singular; per-session runtime RPCs). Both are wired in register_session_handlers (src/bin/aleph-server/commands/start/builder/handlers/session.rs) at server boot and live in src/gateway/handlers/session/.

The sessions.* surface targets the SessionStore (a SQLite-backed implementation in src/gateway/session_store/); the session.* surface targets per-session state plus the artifact store, where the per-call API differs from the CRUD surface.

The runtime keeps an events_retired counter on every state-mutating call: sessions.reset / sessions.delete retire the canonical session_events log before the projection, so a deleted conversation cannot surface through replay, BM25 search, or the next boot's ProjectionReconciler.

sessions.* (database store)

sessions.list

List every session. Internal task and ephemeral sessions are filtered out so the sidebar never surfaces cron / heartbeat cruft.

Response: { "sessions": [ ...SessionInfo... ], "count": N }. Each row carries key, agent_id, session_type, message_count, created_at (RFC3339), last_active_at (RFC3339), updated_at (Unix epoch seconds — drives the Panel's sort), topic (resolved: topic → identity_meta.custom.topic → non-leaked derived_title), status, state, label, input_tokens, output_tokens, model, model_provider, parent_session_key, compaction_count, channel (origin: telegram / discord / gui:chat / null), project_root, exec_tier (per-session override or null), mode (per-session override or null).

sessions.history

Fetch the message history of a session.

Response: { "session_key", "messages": [ ...HistoryMessage... ], "count": N }. Each HistoryMessage is { role, content, timestamp, metadata? }.

sessions.new

Close the current session under an optional topic and create a new epoch of the same key.

Response: { "old_session_key", "new_session_key", "topic" | null }. Autonomous continuations keyed under the old epoch are terminated first, so a sessions.new always returns a clean slate.

sessions.reset

Clear a session's message history. The session_events log is retired before the messages projection, so the conversation cannot be replayed by any later read path.

Response: { "session_key", "reset", "events_retired" }.

sessions.delete

Delete a session and everything tied to it. The default sessions.delete is the macro-generated entry; a *_with_capture variant fires the SessionEnd extension hook and writes a SessionEnd raw memory row before the transcript is dropped (so CompressionService / ProfileSynthesizer can mine durable knowledge from the dying session). The captured tail then purges the session's artifacts and the event log.

Response: { "session_key", "deleted", "events_retired" }.

sessions.preview

A bounded preview of a session's recent history with full metadata.

Response: { "session_key", "meta": { ...SessionMeta... }, "messages": [ ...{role, content, timestamp, metadata?}... ], "message_count": N }. meta carries key, agent_id, session_type, message_count, total_tokens, state, label, input_tokens, output_tokens, model, model_provider, parent_session_key, compaction_count, derived_title, last_message_preview, runtime_ms, estimated_cost_usd, checkpoints, created_at, last_active_at.

sessions.patch

Patch session metadata. Executes validation in-band: an exec_tier or session_mode id that the run loop cannot resolve is refused (INVALID_PARAMS) so a junk override cannot silently disarm the security control. null clears an override.

Response: { "session_key", "updated" }.

sessions.set_topic

Set the session topic (the auto-naming target). Truncated to 100 chars on a character boundary.

Response: { "session_key", "updated": true }.

sessions.set_project_root

Pin a project working directory onto a session. null / absent clears the override (revert to the default ~/.aleph/workspaces/{agent_id}). Path validation (absolute / exists / directory) happens at run time in agent.run — this RPC only records the preference, so a not-yet-existing folder can be remembered without failing the call.

Response: { "session_key", "project_root", "updated": true }.

sessions.compaction.list

List a session's compaction checkpoints.

Response: { "session_key", "checkpoints": [ ...{checkpoint_id, created_at, message_count, retained_message_count}... ] }.

sessions.compaction.restore

Restore a session to a checkpoint.

Response: { "session_key", "checkpoint_id", "message_count", "updated": true }.

sessions.compaction.branch

Branch a new session from a checkpoint.

Response: { "session_key", "checkpoint_id", "new_session_key", "message_count", "created": true }.

session.* (per-session runtime)

session.create

Create a new session and return the canonical key. A name parameter is accepted as a human-readable hint but does not name a stored entity (the new session key is generated as session_<unix_ms>).

Response: { "session_key", "name" }.

session.usage

Get the token / message statistics for a session, with a real per-model USD cost computed from the in-core price table (the duplicate price table in the shell was deleted). The cost is null when the provider/model pair is unpriced.

Response: { "session_key", "tokens", "input_tokens", "output_tokens", "messages", "created_at" | null, "last_active_at" | null, "cost_usd" | null, "cost_status": "unknown" | "complete" | "partial_missing_price" }.

session.compact

Manually trigger a compaction. The KeepLastN strategy is hard-coded (SESSION_COMPACT_KEEP_LAST_N); the agent loop's automatic compaction uses the same strategy.

Response: { "message", "before_messages", "after_messages", "tokens_saved" }. tokens_saved is a rough estimate (deleted * 50).

session.truncate

Truncate a session's history to the first keep_count messages, oldest-first. Drives the TUI /undo command's "drop the most recent user+assistant turn pair" path.

Response: { "messages_removed", "tokens_removed_estimate" }.

session.export_html

Export a session as a self-contained HTML document. The bytes are written through ArtifactStore (no second delivery mechanism), so the file is listed, capability-addressed, and evicted exactly like any other artifact of the session.

Response: { "url", "filename", "size" }. The url is /artifact/<cap>/<id>/<filename>; the capability is scoped to the session so an operator cannot read another session's export.

Artifacts (companion surface)

artifacts.list and artifacts.read_text are wired by register_artifact_handlers alongside session.export_html. They are not under session.* but are the natural read-only companions to the per-session runtime.

| Method | Parameters | Description | |--------|------|------------|------| | artifacts.list | session_key | List every artifact of a session, newest first. Each row carries id, filename, mime_type, size, origin, run_id, created_at, url. | | artifacts.read_text | session_key, id | Read a text-artifact preview (≤ 512 KB) with content + truncated. Refuses non-text MIME types with INVALID_PARAMS (so PNG returns cannot be confused for "binary-not-yet-rendered"). |

See Also

• Methods Reference -- All currently registered namespaces
• Session routes -- Session-key encoding (Main / DM / Group / Task / Subagent / Ephemeral)
• Events reference -- session.* / session_events topics