chore: import upstream snapshot with attribution

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())