Session

from peteos.conversation.session import Session

A session represents a single interaction thread. It wraps a JSON dict as the source of truth and holds the active Context.

Factory Methods

Session.create(parent_dir: str, system_prompt_message: SystemPromptMessage | None = None, tool_definitions_message: ToolDefinitionsMessage | None = None) -> Session

Create a new session with a freshly created context.

Parameter	Type	Default	Description
parent_dir	str	—	The agent directory on disk.
system_prompt_message	SystemPromptMessage | None	None	Optional system prompt for this session.
tool_definitions_message	ToolDefinitionsMessage | None	None	Optional tool definitions for this session.

Session.load(parent_dir: str, session_uuid: str) -> Session

Load a session from parent_dir / session_uuid / session.json.

Parameter	Type	Description
parent_dir	str	The agent directory.
session_uuid	str	The session UUID (also the subdirectory name).

Raises: FileNotFoundError if session.json does not exist.

Instance Properties

Property	Type	Description
uuid	str	The session UUID.
session_dir	Path	The session directory path (parent_dir / uuid).
active_context	Context | None	The currently active context Python object.
active_context_id	str | None	The active context ID from the JSON dict.
auto_approve_tools	list[str]	List of tool names auto-approved by this session.
raw_dict	dict	The wrapped serialized dict.

Instance Methods

set_active_context(context: Context) -> None

Set the active context, synchronizing both the JSON dict ID and the Python object reference.

save() -> None

Save the session and its active context to disk. Creates the session directory if needed.

rolling_sequence_window(count: int) -> Context | None

Apply a rolling sequence window to the active context, keeping the last count non-special messages.

Parameter	Type	Description
count	int	Number of messages to keep from the end.

Returns: The new active Context, or None if no messages were dropped.

rolling_token_window(max_tokens: int, encoding: str = "cl100k_base") -> Context | None

Apply a rolling token window to the active context, keeping messages from the end until total tokens ≤ max_tokens.

Parameter	Type	Default	Description
max_tokens	int	—	Maximum token count.
encoding	str	"cl100k_base"	Tiktoken encoding name.

Returns: The new active Context, or None if no messages were dropped.