> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions and persistence

> QitOS public API: sessions

Obtain Session through composition.session/restore/fork or Engine.session; do not call its constructor directly. run(steering=...) executes and returns EngineResult; inspect reads a SessionInspection. pause requests a cooperative boundary and returns a receipt, not proof of immediate termination. Session identities, run identities and snapshot/checkpoint identities are distinct. SQLite supports clean-process recovery; Memory is process-local. Unresolved approvals and CLI live pause/steer remain unsupported.

[完整可运行教程 / Complete tutorial](/tutorials/checkpoint-and-fork) · [API index](/reference/api)

Signatures and fields below are extracted from the pinned source. Signatures are reference material, not standalone programs. Source links bind the same runtime baseline. Any does not imply arbitrary objects are supported; use the behavioral contract above and the linked tutorial.

<span id="qitos-engine-session_runtime-session" />

## Session

```python theme={null}
from qitos.engine.session_runtime import Session
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L119)

[Usage and executable example](/tutorials/checkpoint-and-fork)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
session = composition.session("Index notes")
result = session.run()
inspection = session.inspect()
print(session.session_id.value, result.state.final_result)
```

```text theme={null}
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``.
```

```text theme={null}
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`     |

<span id="qitos-engine-session_runtime-session-run" />

### Session.run

```text theme={null}
run(*, steering: Optional[str]=None) -> 'EngineResult[Any]'
```

| Parameter  | Type            | Default |
| ---------- | --------------- | ------- |
| `steering` | `Optional[str]` | `None`  |

```text theme={null}
Run or resume through the one canonical Engine loop.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L1508)

<span id="qitos-engine-session_runtime-session-inspect" />

### Session.inspect

```text theme={null}
inspect() -> SessionInspection
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L219)

<span id="qitos-engine-session_runtime-session-pause" />

### Session.pause

```text theme={null}
pause() -> PauseReceipt
```

```text theme={null}
Request cooperative pause; durable status is returned at a boundary.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L291)

<span id="qitos-engine-session_runtime-session-steer" />

### Session.steer

```text theme={null}
steer(text: str) -> SteeringReceipt
```

| Parameter | Type  | Default    |
| --------- | ----- | ---------- |
| `text`    | `str` | `required` |

```text theme={null}
Durably submit one canonical steering item to this Session.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L325)

<span id="qitos-engine-session_runtime-session-fork" />

### Session.fork

```text theme={null}
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`  |

```text theme={null}
Create an isolated durable child from one verified immutable snapshot.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L1728)

<span id="qitos-engine-session_runtime-session-capabilities" />

### Session.capabilities

```text theme={null}
capabilities() -> frozenset[str]
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L189)

<span id="qitos-engine-session_runtime-sessioninspection" />

## SessionInspection

```python theme={null}
from qitos.engine.session_runtime import SessionInspection
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/engine/session_runtime.py#L105)

[Usage and executable example](/tutorials/checkpoint-and-fork)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
inspection = session.inspect()
print(inspection.work_graph)
```

```text theme={null}
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` |

<span id="qitos-checkpoint-store-checkpointstore" />

## CheckpointStore

```python theme={null}
from qitos.checkpoint.store import CheckpointStore
```

[Source @ 19f6258](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/checkpoint/store.py#L174)

[Usage and executable example](/tutorials/checkpoint-and-fork)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
# From an open composition configured with SQLite:
store = composition.runtime.checkpoint_store
head = store.get_session_head(session.session_id.value)
print(head)
```

```text theme={null}
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.
```

<span id="qitos-checkpoint-store-checkpointstore-get-session-head" />

### CheckpointStore.get\_session\_head

```text theme={null}
get_session_head(session_id: str) -> Optional[SessionHeadRecord]
```

| Parameter    | Type  | Default    |
| ------------ | ----- | ---------- |
| `session_id` | `str` | `required` |

```text theme={null}
Read the current mutable head for one session.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/checkpoint/store.py#L241)

<span id="qitos-checkpoint-store-checkpointstore-commit-session-snapshot" />

### CheckpointStore.commit\_session\_snapshot

```text theme={null}
commit_session_snapshot(request: SessionSnapshotCommit) -> SessionCommitReceipt
```

| Parameter | Type                    | Default    |
| --------- | ----------------------- | ---------- |
| `request` | `SessionSnapshotCommit` | `required` |

```text theme={null}
Atomically persist an immutable snapshot and advance its head.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/19f62589a1724693a540a2e822694a2e86ccc2f3/qitos/checkpoint/store.py#L235)