Upgrade to the 0.5 session API¶

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

Previous API	Replacement
`Contree` / `ContreeSync`	`create_sandbox_session` with `with` or `async with`.
SDK image and file managers	Image import, build helpers, and session file operations. Use the client for image listing and tags.
Image objects and `ContreeSessionSync`	An image UUID or tag passed to the factory; select a class with `session_type=` if needed.
`.run(...).wait().result`	`session.run(...)` returns `InstanceResult`; await it in async code.
SDK result wrappers	`result.state.exit_code`, `result.stdout.as_text()`, and `result.stderr.as_bytes()`. Optional API fields can be `Ellipsis`.
`.popen()`	Operation subprocesses, created through `session.spawn()`.
SDK auth/configuration	`contree_client` profiles and transports; see Connection sources.

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.