chore: import upstream snapshot with attribution

examples/python/agents/agno/agno_example.py

@@ -0,0 +1,59 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+from dotenv import load_dotenv
+
+from mirage import MountMode, RAMResource, Workspace
+from mirage.agents.agno import MirageToolkit
+
+load_dotenv(".env.development")
+
+ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)
+
+agent = Agent(
+    model=OpenAIChat(id="gpt-4o"),
+    tools=[MirageToolkit(ws)],
+    instructions=("You have access to a virtual filesystem via shell "
+                  "tools. Use them to explore and read files."),
+    markdown=True,
+)
+
+TASK = "List all files under /data and show the contents of each one."
+
+
+def main() -> None:
+    asyncio.run(ws.execute('echo "hello from mirage" | tee /data/hello.txt'))
+    agent.print_response(TASK)
+
+
+async def amain() -> None:
+    await ws.execute('echo "hello from mirage" | tee /data/hello.txt')
+    await agent.aprint_response(TASK)
+
+    records = ws.ops.records
+    if records:
+        total = sum(r.bytes for r in records)
+        print(f"\n--- {len(records)} ops, {total:,} bytes ---")
+        for r in records:
+            print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+                  f"{r.duration_ms:>5} ms  {r.path}")
+
+
+if __name__ == "__main__":
+    main()
+    asyncio.run(amain())

examples/python/agents/camel/sandbox_agent.py

@@ -0,0 +1,67 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from camel.agents import ChatAgent
+from camel.messages import BaseMessage
+from camel.models import ModelFactory
+from camel.types import ModelPlatformType, ModelType
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.agents.camel import MirageFileToolkit, MirageTerminalToolkit
+from mirage.resource.ram import RAMResource
+
+load_dotenv(".env.development")
+
+ram = RAMResource()
+ws = Workspace({"/": ram}, mode=MountMode.WRITE)
+
+terminal = MirageTerminalToolkit(ws)
+files = MirageFileToolkit(ws)
+
+model = ModelFactory.create(
+    model_platform=ModelPlatformType.OPENAI,
+    model_type=ModelType.GPT_5_MINI,
+)
+
+agent = ChatAgent(
+    system_message=BaseMessage.make_assistant_message(
+        role_name="Mirage Camel Agent",
+        content=("You operate over a Mirage virtual filesystem mounted at /. "
+                 "Use the file toolkit to write structured files and the "
+                 "terminal toolkit to run shell commands. Paths start at /."),
+    ),
+    model=model,
+    tools=[*terminal.get_tools(), *files.get_tools()],
+)
+
+task = ("Write a CSV at /data/numbers.csv with columns name,value and 3 rows. "
+        "Then list /data and read the file back.")
+
+
+async def main():
+    response = await asyncio.to_thread(agent.step, task)
+    print(response.msgs[-1].content)
+    listing = await ws.execute("find / -type f")
+    print((listing.stdout or b"").decode())
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    finally:
+        terminal.close()
+        files.close()

examples/python/agents/claude_agent_sdk/all_tools.py

@@ -0,0 +1,85 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+"""Drive every Mirage tool through the Claude Agent SDK.
+
+Gives a Sonnet agent a task that exercises all six tools the Mirage
+MCP server exposes (execute_command, read, write, edit, ls, grep)
+against a RAM-backed workspace, prints each tool call, and verifies
+the final file contents.
+
+Usage:
+    uv add 'mirage-ai[claude-agent-sdk]'
+    python examples/python/agents/claude_agent_sdk/all_tools.py
+"""
+
+import asyncio
+
+from claude_agent_sdk import (AssistantMessage, ResultMessage, ToolUseBlock,
+                              query)
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.agents.claude_agent_sdk import build_options
+from mirage.resource.ram import RAMResource
+
+load_dotenv(".env.development")
+
+PROMPT = """\
+You are operating on a Mirage virtual filesystem via the mirage tools.
+Use exactly one mirage tool per step and do them in order:
+1. Use the ls tool on '/'.
+2. Use the write tool to create '/notes.txt' with lines: alpha, beta, gamma.
+3. Use the read tool on '/notes.txt'.
+4. Use the edit tool on '/notes.txt' to replace 'beta' with 'BETA'.
+5. Use the grep tool to search for 'a' in '/notes.txt'.
+6. Use the execute_command tool to run: cat /notes.txt | sort | wc -l
+Briefly report what each step returned.
+"""
+
+EXPECTED = {
+    f"mcp__mirage__{name}"
+    for name in ("execute_command", "read", "write", "edit", "ls", "grep")
+}
+
+
+async def main() -> None:
+    ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+    options = build_options(ws)
+    options.model = "claude-sonnet-4-6"
+    options.permission_mode = "bypassPermissions"
+
+    used: list[str] = []
+    async for msg in query(prompt=PROMPT, options=options):
+        if isinstance(msg, AssistantMessage):
+            for block in msg.content:
+                if isinstance(block, ToolUseBlock):
+                    used.append(block.name)
+                    print(f"  -> {block.name}  {block.input}")
+        elif isinstance(msg, ResultMessage):
+            print("\n=== final report ===")
+            print(msg.result)
+
+    print("\n=== tools used ===")
+    print(used)
+    missing = EXPECTED - set(used)
+    print("all six tools exercised:", not missing, "| missing:", missing
+          or "none")
+
+    final = await ws.ops.read("/notes.txt")
+    print("\n=== /notes.txt final content (from the Mirage workspace) ===")
+    print(final.decode("utf-8"))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/agents/langchain/databricks_volume_deepagent.py

@@ -0,0 +1,61 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+
+from databricks_langchain import ChatDatabricks
+from deepagents import create_deep_agent
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.agents.langchain import (LangchainWorkspace, build_system_prompt,
+                                     extract_text)
+from mirage.resource.databricks_volume import (DatabricksVolumeConfig,
+                                               DatabricksVolumeResource)
+
+load_dotenv(".env.development")
+
+resource = DatabricksVolumeResource(
+    DatabricksVolumeConfig(
+        catalog=os.environ["DATABRICKS_VOLUME_CATALOG"],
+        schema=os.environ["DATABRICKS_VOLUME_SCHEMA"],
+        volume=os.environ["DATABRICKS_VOLUME_NAME"],
+        root_path=os.environ.get("DATABRICKS_VOLUME_ROOT_PATH", "/"),
+        host=os.environ.get("DATABRICKS_HOST"),
+        token=os.environ.get("DATABRICKS_TOKEN"),
+        profile=os.environ.get("DATABRICKS_CONFIG_PROFILE"),
+    ))
+
+ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)
+
+agent = create_deep_agent(
+    model=ChatDatabricks(endpoint=os.environ["DATABRICKS_CHAT_ENDPOINT"], ),
+    system_prompt=build_system_prompt(workspace=ws),
+    backend=LangchainWorkspace(ws),
+)
+
+task = ("Inspect /dbx/, identify the most relevant text or markdown files, "
+        "and summarize their contents. Use head for large files.")
+result = agent.invoke({"messages": [{"role": "user", "content": task}]})
+
+for text in extract_text(result["messages"]):
+    print(text)
+
+records = ws.ops.records
+if records:
+    total = sum(record.bytes for record in records)
+    print(f"\n--- {len(records)} ops, {total:,} bytes ---")
+    for record in records:
+        print(f"  {record.op:<8} {record.source:<18} {record.bytes:>10,} B "
+              f"{record.duration_ms:>5} ms  {record.path}")

examples/python/agents/langchain/s3_deepagent.py

@@ -0,0 +1,65 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+
+from deepagents import create_deep_agent
+from dotenv import load_dotenv
+from langchain_anthropic import ChatAnthropic
+
+from mirage import MountMode, Workspace
+from mirage.agents.langchain import (LangchainWorkspace, build_system_prompt,
+                                     extract_text)
+from mirage.resource.s3 import S3Config, S3Resource
+
+load_dotenv(".env.development")
+
+config = S3Config(
+    bucket=os.environ["AWS_S3_BUCKET"],
+    region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+    aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+    aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+)
+
+s3 = S3Resource(config)
+ws = Workspace({"/s3/": s3}, mode=MountMode.READ)
+
+agent = create_deep_agent(
+    model=ChatAnthropic(model="claude-sonnet-4-20250514"),
+    system_prompt=build_system_prompt(
+        mount_info={"/s3/": "S3 bucket (CSV, Parquet, JSONL)"}, ),
+    backend=LangchainWorkspace(ws),
+)
+
+task = ("Explore and summarize the data in /s3/data/."
+        " Use head command for large files.")
+result = agent.invoke({"messages": [{"role": "user", "content": task}]})
+
+for text in extract_text(result["messages"]):
+    print(text)
+
+task2 = ("How many rows are in the parquet, orc, and h5 files"
+         " under /s3/data/? ")
+result2 = agent.invoke({"messages": [{"role": "user", "content": task2}]})
+
+for text in extract_text(result2["messages"]):
+    print(text)
+
+records = ws.ops.records
+if records:
+    total = sum(r.bytes for r in records)
+    print(f"\n--- {len(records)} ops, {total:,} bytes ---")
+    for r in records:
+        print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+              f"{r.duration_ms:>5} ms  {r.path}")

examples/python/agents/openai_agents/multimodal_agent.py

@@ -0,0 +1,104 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+from pathlib import Path
+
+from agents import Agent
+from dotenv import load_dotenv
+from openai import AsyncOpenAI
+
+from mirage import MountMode, Workspace
+from mirage.agents.openai_agents import MirageRunner, build_system_prompt
+from mirage.resource.disk import DiskResource
+from mirage.resource.ram import RAMResource
+
+load_dotenv(".env.development")
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+LOGO_PATH = REPO_ROOT / "logo" / "mirage-text-logo-light.svg"
+
+ram = RAMResource()
+disk = DiskResource(root=str(REPO_ROOT))
+ws = Workspace({"/ram": ram, "/disk": disk}, mode=MountMode.READ)
+
+agent = Agent(
+    name="Multimodal Mirage Agent",
+    model="gpt-5.4-mini",
+    instructions=build_system_prompt(
+        mount_info={
+            "/ram": "In-memory filesystem",
+            "/disk": "Read-only repo files",
+        },
+        extra_instructions=("You will be shown attachments inline. "
+                            "Describe what you see in 1-2 sentences."),
+    ),
+)
+
+
+async def main():
+    if not os.environ.get("OPENAI_API_KEY"):
+        print("OPENAI_API_KEY not set; skipping live agent run.")
+        return
+
+    png_path = "/ram/diagram.png"
+    png_bytes = LOGO_PATH.read_bytes() if LOGO_PATH.exists() else b""
+    if png_bytes:
+        await ws.ops.write(png_path, png_bytes)
+
+    txt_path = "/ram/notes.txt"
+    await ws.ops.write(txt_path,
+                       b"Status: green. INP < 200ms across all routes.\n")
+
+    client = AsyncOpenAI()
+    runner = MirageRunner(ws, client=client)
+
+    paths: list[str] = [txt_path]
+    if png_bytes:
+        paths.append(png_path)
+
+    print("=== build_blocks ===")
+    blocks = await runner.build_blocks(
+        "Summarize the attachments. List each by type.", paths)
+    for b in blocks:
+        kind = b["type"]
+        head = (b.get("text") or b.get("image_url") or b.get("file_id")
+                or "")[:60]
+        print(f"  {kind}: {head}...")
+
+    print()
+    print("=== Runner.run ===")
+    result = await runner.run_with_attachments(
+        agent,
+        "Summarize the attachments. List each by type.",
+        paths,
+    )
+    print(result.final_output)
+
+
+# Same flow works against any mounted resource. Example variants:
+#
+#   from mirage.resource.s3 import S3Resource, S3Config
+#   ws = Workspace({"/s3": S3Resource(S3Config(...))}, mode=MountMode.READ)
+#   await runner.run_with_attachments(agent, "...", ["/s3/bucket/img.png"])
+#
+#   from mirage.resource.slack import SlackResource, SlackConfig
+#   ws = Workspace({"/slack": SlackResource(SlackConfig(...))})
+#   await runner.run_with_attachments(
+#       agent, "Summarize the PDF",
+#       ["/slack/channels/general__C1/2026-04-28/files/report__F1.pdf"])
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/agents/openai_agents/ram_agent.py

@@ -0,0 +1,79 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from agents import Agent, ApplyPatchTool, Runner, ShellTool
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.agents.openai_agents import (MirageEditor, MirageShellExecutor,
+                                         build_system_prompt)
+from mirage.resource.ram import RAMResource
+
+load_dotenv(".env.development")
+
+ram = RAMResource()
+ws = Workspace({"/": ram}, mode=MountMode.WRITE)
+
+system_prompt = build_system_prompt(
+    mount_info={"/": "In-memory filesystem (read/write)"},
+    extra_instructions=("All file paths start from /. "
+                        "For example: /hello.txt, /data/numbers.csv. "
+                        "Use the shell tool to run commands like: "
+                        "echo 'content' > /hello.txt, mkdir /data, "
+                        "cat /hello.txt, ls /."),
+)
+
+agent = Agent(
+    name="Mirage RAM Agent",
+    model="gpt-5.5-mini",
+    instructions=system_prompt,
+    tools=[
+        ShellTool(executor=MirageShellExecutor(ws)),
+        ApplyPatchTool(editor=MirageEditor(ws)),
+    ],
+)
+
+task = ("Create a file /hello.txt with the content 'Hello from Mirage!'. "
+        "Then create a directory /data and write a CSV file /data/numbers.csv "
+        "with columns: name, value. Add 3 rows of sample data. "
+        "Finally, list all files and cat the CSV.")
+
+
+async def main():
+    result = await Runner.run(agent, task)
+    print(result.final_output)
+
+    print("\n--- Verifying files in workspace ---")
+    find_all = await ws.execute("find / -type f")
+    print(f"find / -type f:\n{(find_all.stdout or b'').decode()}")
+
+    for path in (find_all.stdout or b"").decode().strip().split("\n"):
+        path = path.strip()
+        if not path:
+            continue
+        cat_result = await ws.execute(f"cat {path}")
+        print(f"cat {path}:\n{(cat_result.stdout or b'').decode()}")
+
+    records = ws.ops.records
+    if records:
+        total = sum(r.bytes for r in records)
+        print(f"--- {len(records)} ops, {total:,} bytes ---")
+        for r in records:
+            print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+                  f"{r.duration_ms:>5} ms  {r.path}")
+
+
+asyncio.run(main())

examples/python/agents/openai_agents/sandbox_agent.py

@@ -0,0 +1,155 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from agents import Runner
+from agents.run import RunConfig
+from agents.sandbox import SandboxAgent, SandboxRunConfig
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.agents.openai_agents import MirageSandboxClient
+from mirage.resource.ram import RAMResource
+from mirage.resource.s3 import S3Config, S3Resource
+from mirage.resource.slack import SlackConfig, SlackResource
+
+load_dotenv(".env.development")
+
+ram = RAMResource()
+s3 = S3Resource(
+    S3Config(
+        bucket=os.environ["AWS_S3_BUCKET"],
+        region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+        aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+        aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+    ))
+slack = SlackResource(config=SlackConfig(
+    token=os.environ["SLACK_BOT_TOKEN"],
+    search_token=os.environ.get("SLACK_USER_TOKEN"),
+))
+
+ws = Workspace(
+    {
+        "/": (ram, MountMode.WRITE),
+        "/s3": (s3, MountMode.READ),
+        "/slack": (slack, MountMode.READ),
+    },
+    mode=MountMode.WRITE,
+)
+
+client = MirageSandboxClient(ws)
+
+agent = SandboxAgent(
+    name="Mirage Sandbox Agent",
+    model="gpt-5.5",
+    instructions=ws.file_prompt,
+)
+
+task = ("1. Find the date of the latest Slack message in the general channel. "
+        "2. Summarize the parquet file in /s3/data/. "
+        "Write your findings to /report.txt.")
+
+
+async def main():
+    result = await Runner.run(
+        agent,
+        task,
+        run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
+    )
+    print(result.final_output)
+
+    ws = client._ws
+    find_all = await ws.execute("find / -type f")
+    print("\n--- Files in workspace ---")
+    print((find_all.stdout or b"").decode())
+
+    # ── persist/hydrate via the OpenAI Agents sandbox API ──────────
+    # MirageSandboxSession.persist_workspace returns a BytesIO with a
+    # tar; hydrate_workspace mutates an existing session's workspace
+    # in place. Build a fresh session (with the same mount shape) and
+    # restore the snapshot into it.
+    print("\n--- persist / hydrate via sandbox API ---")
+    session = await client.create()
+    snapshot = await session.persist_workspace()
+    snapshot_size = snapshot.getbuffer().nbytes
+    print(f"  persisted snapshot: {snapshot_size:,} bytes")
+
+    # Fresh client with the same mount shape — required so hydrate
+    # finds the same prefixes to restore content into.
+    fresh_ws = Workspace(
+        {
+            "/": (RAMResource(), MountMode.WRITE),
+            "/s3": (S3Resource(
+                S3Config(
+                    bucket=os.environ["AWS_S3_BUCKET"],
+                    region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+                    aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+                    aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+                )), MountMode.READ),
+            "/slack": (SlackResource(config=SlackConfig(
+                token=os.environ["SLACK_BOT_TOKEN"],
+                search_token=os.environ.get("SLACK_USER_TOKEN"),
+            )), MountMode.READ),
+        },
+        mode=MountMode.WRITE,
+    )
+    fresh_client = MirageSandboxClient(fresh_ws)
+    fresh_session = await fresh_client.create()
+    await fresh_session.hydrate_workspace(snapshot)
+
+    fresh_find = await fresh_ws.execute("find / -type f")
+    print("--- Files in hydrated workspace ---")
+    print((fresh_find.stdout or b"").decode())
+
+    orig_files = set((find_all.stdout or b"").decode().strip().splitlines())
+    fresh_files = set((fresh_find.stdout or b"").decode().strip().splitlines())
+    diff = orig_files.symmetric_difference(fresh_files)
+    print(f"--- file list diff: {len(diff)} files differ "
+          f"{'(OK)' if not diff else '(' + str(diff) + ')'} ---")
+
+    # Verify content (not just names) for every file the agent created.
+    print("\n--- content match per file ---")
+    n_match = 0
+    n_diff = 0
+    for path in sorted(orig_files):
+        if not path:
+            continue
+        orig = await ws.execute(f"cat {path}")
+        fresh = await fresh_ws.execute(f"cat {path}")
+        orig_bytes = orig.stdout or b""
+        fresh_bytes = fresh.stdout or b""
+        if orig_bytes == fresh_bytes:
+            print(f"  ✓ {path}  ({len(orig_bytes)} bytes match)")
+            n_match += 1
+        else:
+            print(f"  ✗ {path}")
+            print(f"      orig  ({len(orig_bytes)} bytes): "
+                  f"{orig_bytes[:120]!r}")
+            print(f"      fresh ({len(fresh_bytes)} bytes): "
+                  f"{fresh_bytes[:120]!r}")
+            n_diff += 1
+    print(f"\n--- content summary: {n_match} match, {n_diff} differ ---")
+
+    # Show /report.txt explicitly so the user can read what the agent wrote
+    if "/report.txt" in orig_files:
+        report = await fresh_ws.execute("cat /report.txt")
+        body = (report.stdout or b"").decode()
+        print(f"\n--- /report.txt from hydrated workspace "
+              f"({len(body)} chars) ---")
+        print(body)
+
+
+asyncio.run(main())

examples/python/agents/openai_agents/slack_vision_agent.py

@@ -0,0 +1,134 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from agents import Runner
+from agents.run import RunConfig
+from agents.sandbox import SandboxAgent, SandboxRunConfig
+from dotenv import load_dotenv
+from openai import AsyncOpenAI
+
+from mirage import MountMode, Workspace
+from mirage.agents.openai_agents import MirageRunner, MirageSandboxClient
+from mirage.resource.slack import SlackConfig, SlackResource
+
+load_dotenv(".env.development")
+
+slack = SlackResource(config=SlackConfig(
+    token=os.environ["SLACK_BOT_TOKEN"],
+    search_token=os.environ.get("SLACK_USER_TOKEN"),
+))
+ws = Workspace({"/slack": (slack, MountMode.READ)}, mode=MountMode.READ)
+client = MirageSandboxClient(ws)
+
+navigator = SandboxAgent(
+    name="path-resolver",
+    model="gpt-5.4-mini",
+    instructions=(f"{ws.file_prompt}\n\n"
+                  "Use shell tools (ls, find) to locate files. "
+                  "Reply with absolute paths only, one per line."),
+)
+
+analyst = SandboxAgent(
+    name="analyst",
+    model="gpt-5.4-mini",
+    instructions=(
+        f"{ws.file_prompt}\n\n"
+        "You have shell tools (ls, find, cat, grep, ...) and view_image. "
+        "Some files may already be attached to this message — read them "
+        "directly. For images you discover later, call view_image. "
+        "Answer using only attachments and confirmed file contents."),
+)
+
+
+async def mirage_run(task: str) -> str:
+    """Run a task with both pre-attached multimodal context and live tools.
+
+    Pipeline:
+      1. Navigator agent uses shell tools to resolve which paths the task
+         needs.
+      2. MirageRunner pre-attaches every resolved path as a multimodal
+         block — input_image (PNG/JPEG/GIF, base64 data URI), input_file
+         (PDF, uploaded via OpenAI Files API), or input_text otherwise.
+      3. The analyst SandboxAgent receives those blocks AND retains all
+         shell tools + native view_image. It can read the pre-attached
+         content directly OR call view_image / cat for anything else
+         it discovers mid-run.
+
+    Args:
+        task (str): Natural-language task referring to files in the VFS.
+
+    Returns:
+        str: The analyst's final output.
+    """
+    nav = await Runner.run(
+        navigator,
+        f"Find every file this request refers to: {task}",
+        run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
+        max_turns=20,
+    )
+    print("  navigator raw output:")
+    for line in nav.final_output.strip().splitlines():
+        print(f"    {line!r}")
+    paths = [
+        line.strip().strip("`").strip()
+        for line in nav.final_output.strip().splitlines()
+        if line.strip().startswith("/")
+    ]
+    print(f"  resolved paths: {paths}")
+
+    runner = MirageRunner(ws, client=AsyncOpenAI())
+    blocks = await runner.build_blocks(task, paths)
+    out = await Runner.run(
+        analyst,
+        [{
+            "role": "user",
+            "content": blocks
+        }],
+        run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
+        max_turns=20,
+    )
+    return out.final_output
+
+
+async def main():
+    task = "Summarize the latest PNG and PDF in the slack general channel."
+    print(f"=== Task: {task} ===")
+    print()
+    result = await mirage_run(task)
+    print()
+    print("=== Analyst output ===")
+    print(result)
+
+
+# Why both pre-attach AND view_image?
+#
+# - PNG/JPEG/GIF: either path works. view_image is convenient for images
+#   the agent discovers mid-run; pre-attach is convenient for images
+#   already known up front.
+# - PDF: ONLY pre-attach works. The OpenAI Agents SDK has no view_file
+#   builtin for tool outputs (issue #341). PDFs must be uploaded to the
+#   Files API and added as input_file blocks in a user message. We do
+#   that before the agent run so the model receives full PDF text and
+#   rendered pages.
+# - input_text: any non-binary content the agent might want pre-loaded.
+#
+# Resource-agnostic: ws.ops.read(path) routes via the workspace mount
+# registry, so the same flow works for /s3/...png, /disk/...pdf,
+# /slack/.../files/..., etc.
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/agents/openhands/README.md

@@ -0,0 +1,75 @@
+# OpenHands + Mirage — agents that just use a shell
+
+This example wires the OpenHands SDK to a Mirage `Workspace` and gives the agent **one** tool: `terminal`. No SaaS-specific tools, no MCP servers, no per-vendor schemas. Slack, S3, Gmail, GitHub, Linear — Mirage mounts each as a directory tree, and the agent treats them like a filesystem.
+
+## Run
+
+```bash
+./python/.venv/bin/python examples/python/agents/openhands/sandbox_agent.py
+```
+
+The task: *"Find Slack messages containing 'hello' in #general."* The agent finishes in **2 commands**:
+
+```
+$ ls /slack/channels/
+general__C04KEPWF6V7  random__C04JVGZM7UN  test__C0AS76ABXMK
+
+$ grep -i hello /slack/channels/general__C04KEPWF6V7/*.jsonl
+.../2026-04-16.jsonl:[zechengzhang97] hello
+.../2026-04-04.jsonl:[demo app] Hello from MIRAGE Slack provider!
+```
+
+That's it. The agent never learned about Slack's API. It used `ls` and `grep`.
+
+## Why this matters: Mirage vs. the alternatives
+
+The same task, three ways. Same answer; very different agent surface.
+
+### With Mirage (this example)
+
+- **Agent's tool list:** `terminal`. One tool, one schema.
+- **Agent's vocabulary:** every shell command it already knows — `ls`, `cat`, `grep`, `head`, `wc`, `jq`, `find`, pipes, redirection.
+- **What changed when we added Slack:** mount it at `/slack`. No new tools, no new prompts, no new agent code.
+
+### With a Slack MCP server
+
+- **Agent's tool list:** typically 6–12 Slack-specific tools — `slack_search_messages`, `slack_list_channels`, `slack_get_channel_history`, `slack_get_user_info`, `slack_post_message`, `slack_add_reaction`, …
+- **Agent's vocabulary per tool:** every tool has its own JSON schema, parameter names, return shape. The model has to *learn the API*, then translate user intent into the right tool + the right params.
+- **Composition:** want to filter messages with `jq` then count with `wc`? You can't — MCP tools are atomic; you get back what they return.
+- **Adding Discord:** another MCP server with its own 6–12 tools. The agent's prompt now juggles two parallel APIs.
+
+### With the Slack CLI
+
+- **Agent's tool list:** `terminal` (good — same as Mirage), but...
+- **Agent's vocabulary:** `slack search ...`, `slack chat send ...`, `slack auth login ...`. Vendor-specific subcommands, vendor-specific output formats, vendor-specific auth handling. The agent has to know the Slack CLI exists *and* how to invoke it.
+- **Composition:** the CLI's stdout is its own format. Pipe it through `jq` if it happens to emit JSON, otherwise parse text.
+- **Adding Discord:** install the Discord CLI. Now the agent needs to know two CLIs and pick correctly.
+
+### Side-by-side
+
+|                                        | Mirage                                                                                                  | Slack MCP                                   | Slack CLI                                |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------- |
+| Tools the agent sees                   | 1 (`terminal`)                                                                                          | 6–12 per backend                            | 1 (`terminal`)                           |
+| Vocabulary the agent must learn        | shell + Mirage's filesystem layout                                                                      | each tool's schema                          | each CLI's subcommand grammar            |
+| Composability (pipe / redirect / loop) | yes — real shell                                                                                        | no — atomic calls                           | partial — depends on CLI's stdout format |
+| Adding a new backend                   | mount it; nothing else changes                                                                          | new MCP server, new tool list, prompt churn | install new CLI; agent must learn it     |
+| Pushdown to native APIs (search, etc.) | automatic, in the builtin (Mirage rewrites `grep` over a Slack channel into one `search.messages` call) | only what the MCP exposes                   | none — text in, text out                 |
+
+## What Mirage gives the agent
+
+- **One stable tool surface** (`terminal`) regardless of how many backends are mounted.
+- **Pipes and composability** because everything is a stream of bytes — `cat /s3/data/2026-04.parquet | grep error | jq '.user' | sort | uniq -c`.
+- **Format-aware reads** — `cat` on `.parquet` / `.feather` / `.orc` returns a formatted table; `head -n 5` on `.jsonl` returns the first 5 messages; `grep` on a Slack channel directory pushes down to `search.messages` automatically.
+- **One mental model** for the agent: *"the workspace is a filesystem; use shell."*
+- **One mental model** for you: *"if I can mount it, the agent can use it."*
+
+## Configure
+
+The script loads `.env.development` from the repo root. Required:
+
+| Var                                                                                 | What it's for                                                                                                                                      |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LLM_API_KEY`                                                                       | OpenHands `LLM` (defaults to Anthropic — set to your `ANTHROPIC_API_KEY`)                                                                          |
+| `AWS_S3_BUCKET`, `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | `/s3` mount                                                                                                                                        |
+| `SLACK_BOT_TOKEN`                                                                   | `/slack` mount                                                                                                                                     |
+| `SLACK_USER_TOKEN` *(recommended)*                                                  | enables Slack's `search.messages` push-down so `grep` over `/slack/channels/<channel>/*.jsonl` runs in one API call instead of fanning out per day |

examples/python/agents/openhands/sandbox_agent.py

@@ -0,0 +1,80 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+
+from dotenv import load_dotenv
+from openhands.sdk import LLM, Agent, Conversation, Tool
+
+from mirage import MountMode, Workspace
+from mirage.agents.openhands import MirageWorkspace, register_mirage_terminal
+from mirage.resource.ram import RAMResource
+from mirage.resource.s3 import S3Config, S3Resource
+from mirage.resource.slack import SlackConfig, SlackResource
+
+load_dotenv(".env.development")
+
+TASK = (
+    "Find any Slack messages containing the word 'hello' (case-insensitive) "
+    "in the general channel. The channel directory is at "
+    "/slack/channels/ and starts with 'general'. Each day's messages live "
+    "in a <yyyy-mm-dd>.jsonl file. Use `ls` to discover the exact channel "
+    "directory, then `grep -i hello` across its jsonl files. Report the "
+    "matching message texts and stop.")
+
+
+def build_workspace() -> Workspace:
+    s3 = S3Resource(
+        S3Config(
+            bucket=os.environ["AWS_S3_BUCKET"],
+            region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+            aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+            aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+        ))
+    slack = SlackResource(config=SlackConfig(
+        token=os.environ["SLACK_BOT_TOKEN"],
+        search_token=os.environ.get("SLACK_USER_TOKEN"),
+    ))
+    return Workspace(
+        {
+            "/": (RAMResource(), MountMode.WRITE),
+            "/s3": (s3, MountMode.READ),
+            "/slack": (slack, MountMode.READ),
+        },
+        mode=MountMode.WRITE,
+    )
+
+
+def main() -> None:
+    ws = build_workspace()
+    llm = LLM(
+        model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-6"),
+        api_key=os.getenv("LLM_API_KEY"),
+        base_url=os.getenv("LLM_BASE_URL", None),
+    )
+
+    with MirageWorkspace(workspace=ws, working_dir="/") as mirage_ws:
+        tool_name = register_mirage_terminal(mirage_ws)
+        agent = Agent(
+            llm=llm,
+            tools=[Tool(name=tool_name)],
+            system_message=ws.file_prompt,
+        )
+        conversation = Conversation(agent=agent, workspace=mirage_ws)
+        conversation.send_message(TASK)
+        conversation.run()
+
+
+if __name__ == "__main__":
+    main()

examples/python/agents/pydantic_ai/s3_agent.py

@@ -0,0 +1,65 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+from pydantic_ai import Agent
+from pydantic_ai_backends import create_console_toolset
+
+from mirage import MountMode, Workspace
+from mirage.agents.pydantic_ai import PydanticAIWorkspace, build_system_prompt
+from mirage.resource.s3 import S3Config, S3Resource
+
+load_dotenv(".env.development")
+
+config = S3Config(
+    bucket=os.environ["AWS_S3_BUCKET"],
+    region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+    aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+    aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+)
+
+s3 = S3Resource(config)
+ws = Workspace({"/s3/": s3}, mode=MountMode.READ)
+
+
+@dataclass
+class Deps:
+    backend: PydanticAIWorkspace
+
+
+backend = PydanticAIWorkspace(ws)
+
+agent = Agent(
+    "openai:gpt-4.1",
+    system_prompt=build_system_prompt(
+        mount_info={"/s3/": "S3 bucket (CSV, Parquet, JSONL)"}),
+    deps_type=Deps,
+    toolsets=[create_console_toolset()],
+)
+
+task = ("Explore and summarize the data in /s3/data/."
+        " Use head command for large files and do not write anything.")
+result = agent.run_sync(task, deps=Deps(backend=backend))
+print(result.output)
+
+records = ws.ops.records
+if records:
+    total = sum(r.bytes for r in records)
+    print(f"\n--- {len(records)} ops, {total:,} bytes ---")
+    for r in records:
+        print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+              f"{r.duration_ms:>5} ms  {r.path}")

examples/python/agents/pydantic_ai/s3_pdf_agent.py

@@ -0,0 +1,76 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+from dataclasses import dataclass
+
+import anthropic.types.beta.beta_web_search_tool_20250305_param as _ws_mod
+from dotenv import load_dotenv
+
+if not hasattr(_ws_mod, "UserLocation"):
+
+    class _UserLocation:
+
+        def __init__(self, **kwargs):
+            self.__dict__.update(kwargs)
+
+    _ws_mod.UserLocation = _UserLocation
+
+from pydantic_ai import Agent
+from pydantic_ai_backends import create_console_toolset
+
+from mirage import MountMode, Workspace
+from mirage.agents.pydantic_ai import PydanticAIWorkspace, build_system_prompt
+from mirage.resource.s3 import S3Config, S3Resource
+
+load_dotenv(".env.development")
+
+config = S3Config(
+    bucket=os.environ["AWS_S3_BUCKET"],
+    region=os.environ.get("AWS_DEFAULT_REGION", "us-east-1"),
+    aws_access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
+    aws_secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
+)
+
+s3 = S3Resource(config)
+ws = Workspace({"/s3/": s3}, mode=MountMode.READ)
+
+
+@dataclass
+class Deps:
+    backend: PydanticAIWorkspace
+
+
+backend = PydanticAIWorkspace(ws)
+
+agent = Agent(
+    "anthropic:claude-sonnet-4-20250514",
+    system_prompt=build_system_prompt(
+        mount_info={"/s3/": "S3 bucket with PDF documents"}),
+    deps_type=Deps,
+    toolsets=[create_console_toolset()],
+)
+
+task = ("Read the PDF at /s3/data/example.pdf."
+        " Summarize the first 5 pages of the paper.")
+result = agent.run_sync(task, deps=Deps(backend=backend))
+print(result.output)
+
+records = ws.ops.records
+if records:
+    total = sum(r.bytes for r in records)
+    print(f"\n--- {len(records)} ops, {total:,} bytes ---")
+    for r in records:
+        print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+              f"{r.duration_ms:>5} ms  {r.path}")

examples/python/agents/pydantic_ai/slack_pdf_agent.py

@@ -0,0 +1,91 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import os
+import time
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+from pydantic_ai import Agent
+from pydantic_ai_backends import create_console_toolset
+
+from mirage import MountMode, Workspace
+from mirage.agents.pydantic_ai import PydanticAIWorkspace
+from mirage.resource.slack import SlackConfig, SlackResource
+
+load_dotenv(".env.development")
+
+slack = SlackResource(
+    config=SlackConfig(token=os.environ["SLACK_BOT_TOKEN"],
+                       search_token=os.environ.get("SLACK_USER_TOKEN")))
+ws = Workspace({"/slack": slack}, mode=MountMode.READ)
+
+
+@dataclass
+class Deps:
+    backend: PydanticAIWorkspace
+
+
+backend = PydanticAIWorkspace(ws)
+
+agent = Agent(
+    "openai:gpt-5.4-mini",
+    system_prompt=ws.file_prompt,
+    deps_type=Deps,
+    toolsets=[
+        create_console_toolset(require_execute_approval=False,
+                               image_support=True)
+    ],
+)
+
+
+def main():
+    task = (
+        "Read and summarize the latest PNG and PDF in the slack "
+        "general channel. Open each file with read_file before responding.")
+    print(f"=== Task: {task} ===")
+    print()
+    t0 = time.perf_counter()
+    result = agent.run_sync(task, deps=Deps(backend=backend))
+    elapsed = time.perf_counter() - t0
+    print(result.output)
+    print()
+    print(f"--- {elapsed:.1f}s ---")
+
+    records = ws.ops.records
+    if records:
+        total = sum(r.bytes for r in records)
+        print(f"--- {len(records)} ops, {total:,} bytes ---")
+        for r in records:
+            print(f"  {r.op:<8} {r.source:<8} {r.bytes:>10,} B "
+                  f"{r.duration_ms:>5} ms  {r.path}")
+
+
+# Single-agent flow.
+#
+# Pydantic AI's tool channel accepts multimodal `BinaryContent` blocks in
+# `ToolReturn.content`, so the agent's `read()` tool can return rendered
+# PDF pages and image bytes inline in its context. No two-phase
+# orchestration needed — unlike the OpenAI Agents SDK, where tool
+# returns are text-only (issue #341) and PDFs require pre-attach via
+# the Files API in a separate user-message turn.
+#
+# Mirage wiring is done by mirage.agents.pydantic_ai.PydanticAIWorkspace
+# in backend.py: when `read(path)` ends in .pdf, it routes through
+# `pages_to_images` and packs each page as
+# `BinaryContent(media_type="image/png")`. Resource-agnostic: the same
+# flow works for /s3, /disk, /slack/.../files/, etc.
+
+if __name__ == "__main__":
+    main()