feat(mirage): Add Mirage integration as Agent tool

[bogdankostic]

Related Issues

• related to https://github.com/deepset-ai/haystack-private/issues/353

Proposed Changes:

Adds a new mirage-haystack integration that exposes Mirage — a unified virtual filesystem that mounts heterogeneous backends (object storage, databases, SaaS apps, local disk) as one filesystem. It lets an Agent operate over all of those backends with plain bash through a single tool.

• MirageMount — a declarative, serializable description of one mounted backend (path, resource registry name, config, read_only). A single generic constructor covers all of Mirage's backends uniformly; config values may be plain values, Haystack Secrets, or an OAuth token source, and are resolved only when the live workspace is built.
• MirageWorkspace — holds the mount tree and cache configuration, lazily builds a live mirage.Workspace on first use via Mirage's resource registry, serializes cleanly (resolving Secrets / token sources only at build time), and exposes run / run_async that normalize and truncate output for an LLM.
• MirageShellTool — a Haystack Tool that gives an Agent one guarded bash command surface across every mount.

How did you test it?

• Unit tests: 40 tests across tests/test_workspace.py and tests/test_shell_tool.py, covering mount/workspace construction and validation, Secret and OAuth-token-source serialization round-trips (no plaintext leakage), per-mount read-only enforcement, RAM/disk command execution, output truncation, tool shape and to_dict/from_dict, and the command guard — including the substitution/backtick/subshell bypass cases and fail-closed behavior for quoted or variable command names.
• Manual verification against live Google Drive and OneDrive backends (mounting, listing, cross-backend file copy, and an Agent driving the shell tool end to end).

Notes for the reviewer

• Pins mirage-ai==0.0.3: Mirage is pre-1.0 and has shipped breaking changes across 0.0.x releases.

Checklist

• I have read the contributors guidelines and the code of conduct
• I have updated the related issue with new insights and changes
• I added unit tests and updated the docstrings
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.

[github-actions]

Coverage report (mirage)

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
integrations/mirage/src/haystack_integrations/tools/mirage
_async.py					40-41, 61-64, 73-78
errors.py
shell_tool.py					154
workspace.py					102, 224, 233-235, 252-253, 335, 345, 348
Project Total

This report was generated by python-coverage-comment-action

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​mirage-ai@​0.0.3

View full report

[julian-risch]

Looks good to me in general. I have two remarks on the more complex parts where I am not entirely sure if what I expect should be in scope. I believe it should.