Skip to main content
Version 0.5 removes the previous SDK API without compatibility aliases. Update imports, execution, and result handling as follows.

​
Choose when to save

The factory defaults to LazySession or AsyncLazySession. Commands share a VM. Normal context exit saves pending files; an exception discards changes since the last snapshot. File requests through inspect() and read_file() now read the active VM without saving or stopping it. This requires contree-client>=0.5.1 and a server runtime with live inspection support. inspect() returns a session-bound view that selects the current source on each request. Use inspect_snapshot() for a stable image view and its image_uuid. Image metadata through inspect().info() also requires a snapshot and stops the VM. Close file and archive streams when stopping iteration early; snapshot waits for accepted live requests to finish. Call snapshot() before switching branches or rolling back. Select session_type=ContreeSession or ContreeAsyncSession for a separate VM per command. run(), spawn(), spawn_detached(), and RunRequest now default to disposable=False. run() and execute() commit completed results; after spawn(), wait and call commit_result() explicitly. Pass disposable=True to leave history unchanged. Snapshots are lightweight and can run after every command. They stop the VM; processes and memory do not survive. Unchanged files can produce the same image UUID. See Work with a Session for sync and async examples.

​
Check command results

An API-successful operation can return a nonzero process exit code. The default ApiSuccessCommitPolicy still commits its image. Use ZeroExitCommitPolicy to save only results with exit code zero; see Select a commit policy. Cancellation raises InterruptedError; operation failure raises FailedOperationError. Neither advances history. A PendingRun returned by async run() can be consumed once. See Handle failures and unexpected state for handling errors.

​
Preserve history and manage resources

The factory closes the client and memory store it creates. Close components you supply with with or async with; use matching sync or async implementations. Install contree-sdk[async] for async transport and SQLite dependencies. To resume after Python exits, supply a SQLite store and the same session_id. History stores image references; the images must remain available on the server. See Save and resume a session and Advanced: assemble a sandbox yourself. Commits preserve the parent selected when the operation started. Concurrent results form sibling nodes; they do not replace each other. Branch names and the selected node belong to each Session instance. Pass node_id to resume a specific position. See Select a late result for selecting a completed result without rerunning the command.

​
Update integrations and extensions

Use ContreeSandbox for sync executors and ContreeAsyncSandbox for async executors. See LangChain DeepAgents. The mini-swe-agent 2.4.6 adapter still uses the removed API; see mini-swe-agent. For Dockerfile builds, use Build a Docker image. Direct builder classes and custom directives are covered in Advanced usage and Customize the SDK. Move session overrides to prepare_request(), submit_request(), or create_operation(). Inject file I/O with file_transfer=. The operation’s source history position is available through operation.context.