Skip to content
YosoiDocs

Yosoi 0.4.0 release notes

Yosoi 0.4.0 introduces Surfaces: bounded views of documents and video that callers can explore before choosing what to read or do. Rust, Python and the CLI share the underlying index, reference checks and evidence model. Surface outcomes can be saved in portable files and inspected without the original session.

This release brings together Surfaces, portable Archive outcomes, optional Firefox and Moli support, and explicit network routing. Discovery integration and live recording remain future work.

Start with an overview, search literal text, then inspect a returned reference. Continuations keep replies bounded without treating a partial page as the whole source. Video adds timeline navigation, requested frames and crops. Start with the Surface walkthrough.

The live web adapter lets an agent act through the CLI after attaching, acquiring control and validating current evidence. An action is confirmed only when its declared postcondition is observed.

Enable archive retention to keep observations, operation receipts and incomplete outcomes. Export a self-contained .yosoi file, move it to another directory, and reload it without the original Archive. Offline replay reads evidence; a live rerun opens fresh sources and resolves targets again. Saved evidence never grants permission to act. See Archiving a surface.

Chrome/CDP remains the default. The optional native BiDi controller supports qualified Firefox and Moli configurations, with explicit capability limits and no silent fallback. Choosing a browser explains engine selection.

Requests and owned browser Sessions can opt into IPv4 or IPv6, a local source address, and authenticated HTTP, HTTPS or SOCKS proxies. Destination TLS remains between the client and site. A proxy controls its own destination DNS and egress; selecting a family or source address controls the connection to that proxy. See Network routing.

The built-in USD-only Money and Currency types have been removed. Keep extracted prices as String or str, then interpret them in application code. Python Contracts continue to use ordinary Pydantic types, constraints and custom validators.

This is a breaking change: Money imports, money.usd runtime schemas, saved money_usd values and money-specific rejection payloads are no longer supported. There is no automatic archive migration. Keep 0.3.0 available to read existing money-bearing records and export the application data you need before upgrading.

Rust callers that construct UntilScope with a struct literal must supply its new optional protocol field. Existing serialized CDP scopes remain readable. Surface references remain bound to their original observation and cannot be reused as permits in a new session.

cargo add yosoi@=0.4.0 --features browser-bidi,surface-connections

Enable only the features your workflow needs. A document-only Surface does not need browser features. Async examples also need Tokio’s macros and rt features.

uv add 'yosoi==0.4.0'

For the standalone CLI:

uv tool install 'yosoi-cli==0.4.0'
yosoi --version

Use --force with uv tool install when replacing an existing CLI installation. Rust 1.99 or newer and Python 3.12 through 3.15 are supported. Python wheels include supported free-threaded 3.14 and 3.15 variants.

Browser programs need installed compatible engines. The live Surface web adapter separately needs ChromeDriver and regular Chrome or Chromium. Video decoding needs FFmpeg and FFprobe. Local Archive storage requires Unix.

Video is read-only and does not provide OCR, transcription, audio capture or live streaming. The Surface web transport is separate from the native BiDi controller. Firefox and Moli do not provide every Chrome capability; consult the browser guide before requesting accessibility or network evidence.

Thanks to everyone who contributed to this release.

Full Changelog: https://github.com/CascadingLabs/Yosoi/compare/v0.3.0...v0.4.0