Mirage 0.0.3

We are excited to announce the release of Mirage 0.0.3 🎉🎉🎉

Mirage 0.0.3 is a large parity and platform release. It lands a GNU-aligned shell environment (history, cwd/env, subshell isolation), a unified command factory shared across every backend, cache read-through with warm serving, the Claude Agent SDK integration, and four new/upgraded backends (SharePoint, Qdrant, OneDrive parity, MongoDB on PyMongo Async). Python and TypeScript are kept mirrored throughout.

pip install mirage-ai==0.0.3 · npm install @struktoai/mirage-core@0.0.3 (and -node, -browser, -server, -cli, -agents)

Highlights

• GNU history subsystem (Python + TypeScript). A hidden Observer records every top-level command as timestamp-ordered events; /.bash_history is a read-only view in GNU histfile format and the history shell builtin (-c -d -a -n -r -w -s -p + count) routes through the same mount, so the file and the builtin never disagree. History is captured into snapshots and restored on load. (#313)
• Claude Agent SDK integration. MirageServer + build_options wire a Mirage workspace into the Claude Agent SDK as a tool surface, mirrored in both languages with Python and TypeScript all-tools examples. (#322, #216)
• GNU-aligned cwd/env and subshell isolation. HOME/PWD/OLDPWD mirrors, cd/tilde/CDPATH GNU semantics, relative-path display, and subshell isolation. (#331)
• Unified command factory. Backend shell commands are now generated from one shared factory instead of per-backend wrappers, across disk, redis, ram, s3, ssh, google/chat, the database and SaaS families, notion, dify, nextcloud, onedrive, hf, box, dropbox, and email. Flag interpretation lives in the generics; wrappers are wiring only.
• Cache read-through and warm serving. Warm reads are served in place through shared read-through consumers, with invalidation done at the write site via CacheManager; the file cache is now a store rather than a mount. (#329)
• New and upgraded backends: SharePoint multi-site discovery (#365), a Qdrant resource (#367), full OneDrive S3-parity, and MongoDB migrated to PyMongo Async with client metadata (#330).
• Virtual root is now a real mount. /_default is replaced by a real / mount that callers can override with their own / mount.

Breaking Changes

• /_default is removed. The default scratch space is now a real virtual root mounted at /, overridable by a user-provided / mount.
• File cache is no longer a mount. It is exposed as a store; the cache-mount read redirect is removed and warm reads are served in place.
• MongoDB driver migrated from Motor to PyMongo Async (#330).
• Workspace config: the removed history field is dropped from configs; foreign history formats are tolerated on cross-language snapshot load.
• Cache API: invalidate_index_dirs is deleted in favor of write-site invalidation (#329); the factory drops unsupported_commands and per-command requires tuples.

Features

• sed: GNU-aligned engine: ^/$ anchors, s/// numeric count and p flag, y (transliterate) and c (change), BRE by default with ERE under -E/-r, multiple -e expressions, -f script files, and address negation (addr!cmd) (#340, #326).
• diff: full GNU-style recursive diff -r (py + ts).
• find: aligned with GNU coreutils across all backends: GNU start-path emission, -empty, -not, and unknown-predicate errors (#393, #312).
• FUSE: per-mount Mount spec with FuseManager ownership across both languages, in-memory xattr support, and caller-owned mountpoint cleanup (#345).
• github: grep/rg narrowing via code search on subdirs and regex, with a -l short-circuit (#406).
• mongodb: tail -f follows the change stream and stops caching live reads.
• Wasmer and Microsandbox examples running over a Mirage FUSE mount.

Bugfixes

• Many Python/TypeScript divergence fixes: stat on slack/discord/gdrive, du walk fallback, and assorted GNU command semantics (#419).
• csplit -f cwd resolution, ssh write recording, and disk mkdir invalidation ordering (#419).
• sed: honor ^/$ line anchors in TS substitution and addresses; pattern space excludes the trailing newline (#326).
• onedrive: ls trailing newline (#354), index-cache metadata (#361), and S3-parity command suite (#357).
• databricks_volume: stat reads content_length/last_modified (#355); record mount-relative write keys in touch/mkdir (#356).
• s3/nextcloud: populate ls -l / stat mtime across object-store and API backends (#362).
• Cache invalidation completed at every mutation site for create/copy/rm/rmdir (#329).
• Multi-pattern grep -e / rg -e routed through the generic on search-pushdown backends.
• tar: load bzip2/xz codecs via createRequire for ESM compatibility; redis read enoent preserves the virtual path; fixed open()/os interception hijacking real paths under the virtual root.

Changes

• Cross-mount commands (cp/mv/diff/cmp + read family) reuse the generics through a dispatch-backed adapter, split into per-command modules.
• Shared epoch_to_iso/epochToIso util dedups mtime ISO formatting and enforces second precision; diff flags grouped into a frozen struct.
• Dead-code and dead-test sweep (#359, #348).
• Security: resolved CodeQL code-scanning alerts (path-injection, request-forgery, ReDoS), cleared Dependabot vulnerabilities, added server rate limiting, and confined snapshot/load paths (#323, #324, #325, #342, #358, #360).
• Dependencies: bumped joserfc, pyjwt, nodemailer, undici, js-yaml, pypdf, fast-xml-parser, langchain, aiohttp (<3.14 cap lifted), and several GitHub Actions; added an informational uv audit CI job (#346, #352).
• Expanded the cross-language integ harness (history/observer, cache coherence, cross-mount, sed/find/diff, notion database, onedrive).

Contributors

Thanks to everyone who contributed to this release: @zechengz, @sonhmai, @MarshuMax, @hieu650002, @alexbevi, @ki3nd, @Anush008, @C1-BA-B1-F3, and @dependabot.

New Contributors

• @MarshuMax made their first contribution: Notion database browsing support (#21)
• @alexbevi made their first contribution: MongoDB PyMongo Async migration + client metadata (#330)
• @hieu650002 made their first contribution: SharePoint multi-site discovery (#365) and OneDrive metadata (#361)
• @Anush008 made their first contribution: Qdrant resource (#367)
• @C1-BA-B1-F3 made their first contribution: GNU find alignment (#393) and compact JSON rendering (#391)

Full Changelog: v0.0.2...v0.0.3