Session 与持久化

QitOS public API: sessions

通过 composition.session/restore/fork 或 Engine.session 获取 Session，不直接构造。run(steering=…) 执行并返回 EngineResult，inspect 返回 SessionInspection。pause 请求协作边界并返回 receipt，不保证立即终止。Session、Run、Snapshot/Checkpoint 身份不同。SQLite 支持跨进程恢复，Memory 仅进程内。未解决 approval 的恢复和 CLI live pause/steer 当前 unsupported。

完整可运行教程 / Complete tutorial · API index

以下签名和字段由固定源码提取；签名是参考，不是可直接运行的程序。每个条目的源码链接绑定同一 runtime baseline。类型中的 Any 不代表任意对象均受支持，应结合上述行为契约和教程使用。

​

Session

from qitos.engine.session_runtime import Session

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

session = composition.session("Index notes")
result = session.run()
inspection = session.inspect()
print(session.session_id.value, result.state.final_result)

Scoped client for one durable Session identity.

The facade stores identifiers and cooperative control only. Agent state is
reconstructed from the canonical snapshot and executed by ``Engine.run``.

Session(*, engine: 'Engine[Any, Any, Any]', session_id: SessionIdentity, run_id: RunIdentity, agent_id: AgentIdentity, references: Iterable[ResolverReference], created_at: str, state_type: type[StateSchema], work_item_id: WorkItemIdentity, attempt_id: AttemptIdentity, fork_receipt: Optional[SessionForkReceipt]=None) -> None

Parameter	Type	Default
engine	'Engine[Any, Any, Any]'	required
session_id	SessionIdentity	required
run_id	RunIdentity	required
agent_id	AgentIdentity	required
references	Iterable[ResolverReference]	required
created_at	str	required
state_type	type[StateSchema]	required
work_item_id	WorkItemIdentity	required
attempt_id	AttemptIdentity	required
fork_receipt	Optional[SessionForkReceipt]	None

​

Session.run

run(*, steering: Optional[str]=None) -> 'EngineResult[Any]'

Parameter	Type	Default
steering	Optional[str]	None

Run or resume through the one canonical Engine loop.

Source

​

Session.inspect

inspect() -> SessionInspection

Source

​

Session.pause

pause() -> PauseReceipt

Request cooperative pause; durable status is returned at a boundary.

Source

​

Session.steer

steer(text: str) -> SteeringReceipt

Parameter	Type	Default
text	str	required

Durably submit one canonical steering item to this Session.

Source

​

Session.fork

fork(snapshot: SessionSnapshot | SnapshotIdentity | str | None=None, *, operation_id: Optional[str]=None) -> 'Session'

Parameter	Type	Default
snapshot	SessionSnapshot | SnapshotIdentity | str | None	None
operation_id	Optional[str]	None

Create an isolated durable child from one verified immutable snapshot.

Source

​

Session.capabilities

capabilities() -> frozenset[str]

Source

​

SessionInspection

from qitos.engine.session_runtime import SessionInspection

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

inspection = session.inspect()
print(inspection.work_graph)

Read-only inspection result backed by the current durable head.

Field	Type	Default
head	SessionHead	required
lifecycle	SessionLifecycle	required
capabilities	tuple[str, ...]	required
snapshot_integrity	str	required
budget	Mapping[str, Any]	required
work_graph	Optional[Mapping[str, Any]]	required
last_request_view	Optional[RequestView]	required
task	str	required
tool_batch	Optional[ToolBatchSnapshot]	required

​

CheckpointStore

from qitos.checkpoint.store import CheckpointStore

Source @ 19f6258

用法与可执行示例

用法片段：接续上方完整教程中的对象，不是独立程序。

# From an open composition configured with SQLite:
store = composition.runtime.checkpoint_store
head = store.get_session_head(session.session_id.value)
print(head)

Abstract base class for checkpoint persistence.

Borrowed from LangGraph's ``BaseCheckpointSaver`` interface
(``references/langgraph/libs/checkpoint/langgraph/checkpoint/base/__init__.py``).

Every method has both sync and async variants.  Subclasses should
override the async variants; the sync ones delegate via ``asyncio.run``
by default.

​

CheckpointStore.get_session_head

get_session_head(session_id: str) -> Optional[SessionHeadRecord]

Parameter	Type	Default
session_id	str	required

Read the current mutable head for one session.

Source

​

CheckpointStore.commit_session_snapshot

commit_session_snapshot(request: SessionSnapshotCommit) -> SessionCommitReceipt

Parameter	Type	Default
request	SessionSnapshotCommit	required

Atomically persist an immutable snapshot and advance its head.

Source