intellicrack.core.session

Session management for Intellicrack.

This module provides session state management including conversation history, binary analysis state, and persistence to SQLite database.

class SessionMetadata[source]

Bases: object

Metadata about a session.

Variables:

id (str) – Unique session identifier.
name (str) – Human-readable session name.
created_at (datetime) – When the session was created.
updated_at (datetime) – When the session was last modified.
provider (str) – LLM provider used.
model (str) – Model identifier.
binary_count (int) – Number of binaries loaded.
message_count (int) – Number of messages.

id: str

name: str

created_at: datetime

updated_at: datetime

provider: str

model: str

binary_count: int = 0

message_count: int = 0

__init__(id, name, created_at, updated_at, provider, model, binary_count=0, message_count=0)

Parameters:

id (str)
name (str)
created_at (datetime)
updated_at (datetime)
provider (str)
model (str)
binary_count (int)
message_count (int)

Return type:

None

class McpServerState[source]

Bases: object

What one Model Context Protocol server was doing during a session.

Recorded so reopening a session shows which third-party servers its work depended on, and which of them were healthy at the time. This is a separate field from Session.tool_states on purpose: that mapping is keyed by ToolName and deserialized with ToolName(key), so writing a server id into it would make the session fail to load.

Variables:

server_id (str) – The server’s configured id.
health (str) – The server’s health at the time, as its enum value.
tool_count (int) – Tools the server was publishing.
generation (str | None) – Digest of the server’s tool listing, or None.
last_error (str | None) – Why the server was not usable, or None.

server_id: str

health: str

tool_count: int = 0

generation: str | None = None

last_error: str | None = None

__init__(server_id, health, tool_count=0, generation=None, last_error=None)

Parameters:

server_id (str)
health (str)
tool_count (int)
generation (str | None)
last_error (str | None)

Return type:

None

class Session[source]

Bases: object

Complete session state.

Variables:

id (str) – Unique session identifier.
name (str) – Human-readable session name.
created_at (datetime) – Timestamp when the session was created.
updated_at (datetime) – Timestamp of the last session update.
provider (str) – Instance id of the LLM provider used for this session.
model (str) – Model identifier used for this session.
binaries (list[BinaryInfo]) – List of loaded binaries.
active_binary_index (int) – Index of active binary.
messages (list[Message]) – Conversation history.
tool_states (dict[ToolName, ToolState]) – State of each tool bridge.
patches (list[PatchInfo]) – Applied patches.
bridge_analyses (dict[str, BridgeAnalysisSummary]) – Mapping of binary names to their bridge analysis summary.
notes (str) – User notes.
tags (list[str]) – Session tags.
loaded_tools (list[str]) – Canonical dotted names of tool functions discovered via the tools.search meta-tool during dynamic tool loading, in insertion order with duplicates skipped on insert. Holds only discovered names; the always-on core tool set comes from configuration and is unioned in at advertise time, not stored here. An ordered list rather than a set so cap-trimming order stays deterministic.
mcp_servers (dict[str, McpServerState]) – State of each Model Context Protocol server that took part in this session, keyed by server id. Absent from a session file written before MCP support existed, which loads as an empty mapping.
root_folders (list[str]) – Folders the operator added to the session for MCP servers to work in, offered to them as roots alongside the loaded binaries’ folders.

id: str

name: str

created_at: datetime

updated_at: datetime

provider: str

model: str

binaries: list[BinaryInfo]

active_binary_index: int = -1

messages: list[Message]

tool_states: dict[ToolName, ToolState]

patches: list[PatchInfo]

bridge_analyses: dict[str, BridgeAnalysisSummary]

notes: str = ''

tags: list[str]

loaded_tools: list[str]

mcp_servers: dict[str, McpServerState]

root_folders: list[str]

set_root_folders(folders)[source]

Replace the folders the operator added for MCP servers to work in.

Parameters:: folders (list[str]) – The folders, in the order they are offered.
Returns:: True when they changed.
Return type:: bool

add_loaded_tool(canonical_name)[source]

Record a discovered tool-function name, skipping duplicates.

Parameters:: canonical_name (str) – Canonical dotted tool-function name discovered by a tools.search call (e.g. "frida.spawn").
Returns:: True if canonical_name was newly added; False if it was already present in loaded_tools.
Return type:: bool

set_mcp_server_state(state)[source]

Record the current state of one MCP server.

Parameters:: state (McpServerState) – The server state to store, replacing any earlier entry for the same server.
Return type:: None

clear_mcp_server_state(server_id)[source]

Forget one MCP server’s recorded state.

Parameters:: server_id (str) – The server to forget.
Returns:: True when an entry was removed.
Return type:: bool

classmethod create(provider, model, name=None)[source]

Create a new session.

Parameters:

provider (str) – Instance id of the LLM provider to use.
model (str) – Model identifier.
name (str | None) – Optional session name.

Returns:

New Session instance.

Return type:

Session

property active_binary: BinaryInfo | None

Currently active binary, when one is selected.

Returns:: Active BinaryInfo or None.
Return type:: BinaryInfo | None

add_binary(binary)[source]

Add a binary to the session.

Parameters:: binary (BinaryInfo) – Binary information to add.
Return type:: None

add_message(message)[source]

Add a message to the conversation.

Parameters:: message (Message) – Message to add.
Return type:: None

add_patch(patch)[source]

Add a patch to the session.

Parameters:: patch (PatchInfo) – Patch information to add.
Return type:: None

add_bridge_analysis(binary_name, analysis)[source]

Add bridge analysis summary for a binary.

Parameters:

binary_name (str) – Name of the analyzed binary.
analysis (BridgeAnalysisSummary) – Bridge analysis summary results.

Return type:

None

get_bridge_analysis(binary_name)[source]

Get bridge analysis summary for a binary.

Parameters:: binary_name (str) – Name of the binary.
Returns:: BridgeAnalysisSummary if available, None otherwise.
Return type:: BridgeAnalysisSummary | None

set_tool_state(state)[source]

Record or replace the tool bridge state for state.tool.

This is the canonical writer for Session.tool_states. Bridges call this whenever they connect, attach to a process, or surface an error so the persisted session reflects the current state of every integrated tool.

Parameters:: state (ToolState) – ToolState describing the bridge’s current connection, attachment, target, and last error.
Return type:: None

clear_tool_state(tool)[source]

Remove the recorded state for tool if present.

Parameters:: tool (ToolName) – Tool whose state should be cleared.
Returns:: True if a state was removed, False if no state existed.
Return type:: bool

add_tag(tag)[source]

Add a tag to the session.

Parameters:: tag (str) – Non-empty tag string. Whitespace-only tags are rejected.
Returns:: True if the tag was added, False if it was already present.
Return type:: bool
Raises:: ValueError – If tag is empty or whitespace-only.

remove_tag(tag)[source]

Remove a tag from the session if present.

Parameters:: tag (str) – Tag string to remove. Leading/trailing whitespace is stripped to match the normalisation performed by add_tag.
Returns:: True if the tag was removed, False if it was not present.
Return type:: bool

__init__(id, name, created_at, updated_at, provider, model, binaries=<factory>, active_binary_index=-1, messages=<factory>, tool_states=<factory>, patches=<factory>, bridge_analyses=<factory>, notes='', tags=<factory>, loaded_tools=<factory>, mcp_servers=<factory>, root_folders=<factory>)

Parameters:

id (str)
name (str)
created_at (datetime)
updated_at (datetime)
provider (str)
model (str)
binaries (list[BinaryInfo])
active_binary_index (int)
messages (list[Message])
tool_states (dict[ToolName, ToolState])
patches (list[PatchInfo])
bridge_analyses (dict[str, BridgeAnalysisSummary])
notes (str)
tags (list[str])
loaded_tools (list[str])
mcp_servers (dict[str, McpServerState])
root_folders (list[str])

Return type:

None

class SessionStore[source]

Bases: object

SQLite-based session persistence.

Handles storing and retrieving sessions from a SQLite database.

__init__(db_path)[source]

Initialize the SessionStore with a database path.

Parameters:: db_path (Path) – Path to the SQLite database file.
Return type:: None

save(session)[source]

Save a session to the database.

Persists the full session state inside a single SQLite transaction initiated with BEGIN IMMEDIATE so that the tag rewrite and the session upsert cannot be interleaved with a concurrent save (for example, from the auto-save loop). The payload is encoded before the transaction opens, so a value JSON cannot express fails the save without ever taking the write lock. Propagates sqlite3.Error from the database engine and OSError from the underlying SQLite file layer after the connection is closed.

Parameters:: session (Session) – Session to save.
Return type:: None

load(session_id)[source]

Load a session from the database.

Parameters:: session_id (str) – Session identifier.
Returns:: Session instance or None if not found.
Return type:: Session | None

delete(session_id)[source]

Delete a session from the database.

Parameters:: session_id (str) – Session identifier.
Returns:: True if deleted, False if not found.
Return type:: bool

list_all(limit=100)[source]

List all sessions.

Parameters:: limit (int) – Maximum number of sessions to return.
Returns:: List of session metadata.
Return type:: list[SessionMetadata]

search_by_tag(tag)[source]

Search sessions by tag.

Parameters:: tag (str) – Tag to search for.
Returns:: List of matching session metadata.
Return type:: list[SessionMetadata]

cleanup_old(days=30)[source]

Delete sessions older than specified days.

The cutoff timestamp is precomputed in Python and compared directly against the stored ISO-8601 updated_at column via lexicographic ordering so SQLite’s julianday does not need to parse timezone-aware ISO strings.

Parameters:: days (int) – Number of days to keep.
Returns:: Number of sessions deleted.
Return type:: int

export_to_json(session, path)[source]

Export a session to a JSON file.

Parameters:

session (Session) – Session to export.
path (Path) – Path to write the JSON file.

Return type:

None

import_from_json(path)[source]

Import a session from a JSON file.

Parameters:

path (Path) – Path to the JSON file.

Returns:

Imported Session instance.

Return type:

Session

Raises:

FileNotFoundError – If the file does not exist.
ValueError – If the file format is invalid.

class SessionManager[source]

Bases: object

Manages session lifecycle and persistence.

Coordinates between the active session and the session store.

Auto-save runs on a dedicated daemon thread rather than an asyncio.Task so start/stop/close remain safe when callers use different event loops (GUI bridge loop vs application main loop). SQLite access is serialised with a threading.Lock for the same reason: asyncio.Lock is loop-bound and cannot protect writers across loops or the auto-save thread.

__init__(store, *, auto_save=True, save_interval=300)[source]

Initialize the SessionManager with a store and save settings.

Parameters:

store (SessionStore) – Session persistence store.
auto_save (bool) – Whether to auto-save changes.
save_interval (int) – Interval between auto-saves in seconds.

Return type:

None

property current: Session | None

Current session, if one is active.

Returns:: Current session or None.
Return type:: Session | None

async create(provider, model, name=None)[source]

Create a new session.

Parameters:

provider (str) – Instance id of the LLM provider to use.
model (str) – Model identifier.
name (str | None) – Optional session name.

Returns:

New Session instance.

Return type:

Session

async load(session_id)[source]

Load a session.

Parameters:: session_id (str) – Session identifier.
Returns:: Session instance or None if not found.
Return type:: Session | None

async get(session_id)[source]

Get a session by ID without making it current.

Parameters:: session_id (str) – Session identifier.
Returns:: Session instance or None if not found.
Return type:: Session | None

async update(session)[source]

Update a session in the store.

SQLite I/O is offloaded to a worker thread so the event loop is never blocked by disk I/O, and serialised against every other writer through self._db_lock to keep SQLite from racing with the auto-save worker or concurrent update callers.

Parameters:: session (Session) – Session to update.
Return type:: None

async save()[source]

Save the current session.

Like update, the SQLite work is run via asyncio.to_thread under the same lock so save and update cannot interleave their transactions.

Return type:: None

async close()[source]

Close the current session.

Stops the auto-save worker (safe from any event loop), flushes the current session once, then clears it.

Return type:: None

async delete(session_id)[source]

Delete a session.

Parameters:: session_id (str) – Session identifier.
Returns:: True if deleted.
Return type:: bool

list_sessions(limit=100)[source]

List all sessions.

Parameters:: limit (int) – Maximum number to return.
Returns:: List of session metadata.
Return type:: list[SessionMetadata]

search_by_tag(tag)[source]

Search sessions by tag.

Parameters:: tag (str) – Tag to search for.
Returns:: List of matching session metadata.
Return type:: list[SessionMetadata]

async cleanup(days=30)[source]

Clean up old sessions.

Parameters:: days (int) – Number of days to keep.
Returns:: Number of sessions deleted.
Return type:: int

async export_json(session_id, path)[source]

Export a session to a JSON file.

Parameters:

session_id (str) – Session identifier to export.
path (Path) – Path to write the JSON file.

Raises:

ValueError – If the session is not found.

Return type:

None

async import_json(path, *, replace=False)[source]

Import a session from a JSON file.

Parameters:

path (Path) – Path to the JSON file.
replace (bool) – Whether to replace existing session with same ID.

Returns:

Imported Session instance.

Return type:

Session

Raises:

ValueError – If session with same ID already exists and replace=False.

async export_current(path)[source]

Export the current session to a JSON file.

Parameters:: path (Path) – Path to write the JSON file.
Raises:: ValueError – If no current session exists.
Return type:: None

property is_auto_saving: bool

Whether the auto-save background worker is currently running.

Returns:

True when an auto-save thread has been started and is: still alive.

Return type:

bool

async stop_auto_save()[source]

Stop the auto-save background worker.

Public counterpart to _stop_auto_save() for callers (test harnesses, embedding applications) that need to cleanly stop the background save loop without reaching into private members. No-op when no worker is currently running.

Return type:: None