chore: import upstream snapshot with attribution

python/tests/observe/__init__.py

@@ -0,0 +1,13 @@
+# ========= 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. =========

python/tests/observe/test_append_disk.py

@@ -0,0 +1,49 @@
+# ========= 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 pathlib import Path
+
+from mirage.cache.index.ram import RAMIndexCacheStore
+from mirage.ops import Ops
+from mirage.ops.config import OpsMount
+from mirage.resource.disk import DiskResource
+from mirage.types import MountMode
+
+
+def _make_ops(tmp_path: Path) -> tuple[Ops, DiskResource]:
+    disk = DiskResource(root=tmp_path)
+    mount = OpsMount(
+        prefix="/disk/",
+        resource_type="disk",
+        accessor=disk.accessor,
+        index=RAMIndexCacheStore(),
+        mode=MountMode.WRITE,
+        ops=disk.ops_list(),
+    )
+    ops = Ops(mounts=[mount])
+    return ops, disk
+
+
+def test_append_creates_file(tmp_path):
+    ops, _ = _make_ops(tmp_path)
+    asyncio.run(ops.append("/disk/test.jsonl", b"line1\n"))
+    assert (tmp_path / "test.jsonl").read_bytes() == b"line1\n"
+
+
+def test_append_concatenates(tmp_path):
+    ops, _ = _make_ops(tmp_path)
+    (tmp_path / "test.jsonl").write_bytes(b"line1\n")
+    asyncio.run(ops.append("/disk/test.jsonl", b"line2\n"))
+    assert (tmp_path / "test.jsonl").read_bytes() == b"line1\nline2\n"

python/tests/observe/test_append_ram.py

@@ -0,0 +1,56 @@
+# ========= 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 mirage.cache.index.ram import RAMIndexCacheStore
+from mirage.ops import Ops
+from mirage.ops.config import OpsMount
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+
+
+def _make_ops() -> tuple[Ops, RAMResource]:
+    mem = RAMResource()
+    mount = OpsMount(
+        prefix="/data/",
+        resource_type="ram",
+        accessor=mem.accessor,
+        index=RAMIndexCacheStore(),
+        mode=MountMode.WRITE,
+        ops=mem.ops_list(),
+    )
+    ops = Ops(mounts=[mount])
+    return ops, mem
+
+
+def test_append_creates_file():
+    ops, mem = _make_ops()
+    asyncio.run(ops.append("/data/test.jsonl", b"line1\n"))
+    assert mem._store.files["/test.jsonl"] == b"line1\n"
+
+
+def test_append_concatenates():
+    ops, mem = _make_ops()
+    mem._store.files["/test.jsonl"] = b"line1\n"
+    asyncio.run(ops.append("/data/test.jsonl", b"line2\n"))
+    assert mem._store.files["/test.jsonl"] == b"line1\nline2\n"
+
+
+def test_append_records_op():
+    ops, mem = _make_ops()
+    asyncio.run(ops.append("/data/test.jsonl", b"hello"))
+    assert len(ops.records) == 1
+    assert ops.records[0].op == "append"
+    assert ops.records[0].bytes == 5

python/tests/observe/test_context.py

@@ -0,0 +1,205 @@
+# ========= 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. =========
+
+from mirage.observe.context import (RecordingScope, push_mount_prefix,
+                                    push_revisions, record, record_stream,
+                                    reset_revisions, revision_for)
+
+
+def test_record_no_context():
+    record("read", "/a.txt", "s3", 100, 0)
+
+
+def test_recording_scope_collects_records():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/a.txt", "s3", 100, 0)
+    scope.close()
+    assert len(records) == 1
+    assert records[0].op == "read"
+    assert records[0].bytes == 100
+
+
+def test_record_after_stop_is_noop():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/a.txt", "s3", 100, 0)
+    scope.close()
+    record("read", "/b.txt", "s3", 200, 0)
+    assert len(records) == 1
+
+
+def test_multiple_records():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/a.txt", "s3", 100, 0)
+    record("write", "/b.txt", "ram", 50, 0)
+    scope.close()
+    assert len(records) == 2
+    assert records[0].source == "s3"
+    assert records[1].source == "ram"
+
+
+def test_record_with_virtual_prefix():
+    scope = RecordingScope()
+    records = scope.records
+    push_mount_prefix("/s3")
+    record("read", "/data/file.json", "s3", 100, 0)
+    push_mount_prefix("")
+    scope.close()
+    assert records[0].path == "/s3/data/file.json"
+    assert records[0].mount_prefix == "/s3"
+
+
+def test_record_without_prefix():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/data/file.json", "s3", 100, 0)
+    scope.close()
+    assert records[0].path == "/data/file.json"
+    assert records[0].mount_prefix == ""
+
+
+def test_record_prefix_already_applied():
+    scope = RecordingScope()
+    records = scope.records
+    push_mount_prefix("/s3")
+    record("read", "/s3/data/file.json", "s3", 100, 0)
+    push_mount_prefix("")
+    scope.close()
+    assert records[0].path == "/s3/data/file.json"
+
+
+def test_push_mount_prefix_returns_previous():
+    scope = RecordingScope()
+    assert push_mount_prefix("/s3") == ""
+    assert push_mount_prefix("/r2") == "/s3"
+    push_mount_prefix("")
+    scope.close()
+
+
+def test_push_mount_prefix_no_recorder_is_noop():
+    assert push_mount_prefix("/s3") == ""
+
+
+def test_record_carries_fingerprint_when_passed():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/s3/x", "s3", 10, 0, fingerprint="abc")
+    scope.close()
+    assert records[0].fingerprint == "abc"
+    assert records[0].revision is None
+
+
+def test_record_carries_revision_when_passed():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/s3/x", "s3", 10, 0, revision="v1")
+    scope.close()
+    assert records[0].revision == "v1"
+    assert records[0].fingerprint is None
+
+
+def test_record_carries_both_when_passed():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/s3/x", "s3", 10, 0, fingerprint="abc", revision="v1")
+    scope.close()
+    assert records[0].fingerprint == "abc"
+    assert records[0].revision == "v1"
+
+
+def test_record_fingerprint_default_is_none():
+    scope = RecordingScope()
+    records = scope.records
+    record("read", "/s3/x", "s3", 10, 0)
+    scope.close()
+    assert records[0].fingerprint is None
+    assert records[0].revision is None
+
+
+def test_record_stream_carries_fingerprint_when_passed():
+    scope = RecordingScope()
+    records = scope.records
+    rec = record_stream("read", "/s3/x", "s3", fingerprint="abc")
+    scope.close()
+    assert rec is not None
+    assert records[0].fingerprint == "abc"
+
+
+def test_record_stream_carries_revision_when_passed():
+    scope = RecordingScope()
+    records = scope.records
+    rec = record_stream("read", "/s3/x", "s3", revision="v1")
+    scope.close()
+    assert rec is not None
+    assert records[0].revision == "v1"
+
+
+def test_record_stream_assignable_after_open():
+    scope = RecordingScope()
+    records = scope.records
+    rec = record_stream("read", "/s3/x", "s3")
+    assert rec.fingerprint is None
+    assert rec.revision is None
+    rec.fingerprint = "abc"
+    rec.revision = "v2"
+    scope.close()
+    assert records[0].fingerprint == "abc"
+    assert records[0].revision == "v2"
+
+
+def test_revision_for_no_context():
+    assert revision_for("/s3/a") is None
+
+
+def test_revision_for_with_context():
+    token = push_revisions({"/s3/a": "v1", "/s3/b": "v2"})
+    try:
+        assert revision_for("/s3/a") == "v1"
+        assert revision_for("/s3/b") == "v2"
+        assert revision_for("/s3/c") is None
+    finally:
+        reset_revisions(token)
+    assert revision_for("/s3/a") is None
+
+
+def test_revision_for_with_none_context():
+    token = push_revisions(None)
+    try:
+        assert revision_for("/s3/a") is None
+    finally:
+        reset_revisions(token)
+
+
+def test_nested_scope_close_restores_outer():
+    outer = RecordingScope()
+    record("read", "/a", "s3", 1, 0)
+    inner = RecordingScope()
+    record("read", "/b", "s3", 1, 0)
+    inner.close()
+    record("read", "/c", "s3", 1, 0)
+    outer.close()
+    assert [r.path for r in outer.records] == ["/a", "/c"]
+    assert [r.path for r in inner.records] == ["/b"]
+
+
+def test_inactive_scope_joins_enclosing():
+    outer = RecordingScope()
+    joined = RecordingScope(active=False)
+    record("read", "/a", "s3", 1, 0)
+    joined.close()
+    outer.close()
+    assert [r.path for r in outer.records] == ["/a"]
+    assert joined.records == []

python/tests/observe/test_core_recording.py

@@ -0,0 +1,55 @@
+# ========= 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 mirage.observe.context import RecordingScope
+from mirage.resource.ram import RAMResource
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def test_memory_read_records_bytes():
+    mem = RAMResource()
+    mem._store.files["/hello.txt"] = b"hello world"
+    scope = RecordingScope()
+    records = scope.records
+    data = _run(mem.read_bytes("/hello.txt"))
+    scope.close()
+    assert data == b"hello world"
+    assert len(records) == 1
+    assert records[0].op == "read"
+    assert records[0].bytes == 11
+    assert records[0].source == "ram"
+
+
+def test_memory_write_records_bytes():
+    mem = RAMResource()
+    mem._store.dirs.add("/")
+    scope = RecordingScope()
+    records = scope.records
+    _run(mem.write("/hello.txt", b"hello"))
+    scope.close()
+    assert len(records) == 1
+    assert records[0].op == "write"
+    assert records[0].bytes == 5
+
+
+def test_no_recording_context_is_noop():
+    mem = RAMResource()
+    mem._store.files["/hello.txt"] = b"hello"
+    data = _run(mem.read_bytes("/hello.txt"))
+    assert data == b"hello"

python/tests/observe/test_disk_store.py

@@ -0,0 +1,68 @@
+# ========= 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 mirage.observe.disk_store import DiskObserverStore
+from mirage.observe.observer import Observer
+from mirage.observe.store import ObserverStore
+
+
+def test_append_creates_and_extends(tmp_path):
+    store = DiskObserverStore(str(tmp_path / "obs"))
+    asyncio.run(store.append("/d/s.jsonl", b"a\n"))
+    asyncio.run(store.append("/d/s.jsonl", b"b\n"))
+    files = asyncio.run(store.read_all())
+    assert files == {"/d/s.jsonl": b"a\nb\n"}
+
+
+def test_write_overwrites(tmp_path):
+    store = DiskObserverStore(str(tmp_path / "obs"))
+    asyncio.run(store.append("/d/s.jsonl", b"old\n"))
+    asyncio.run(store.write("/d/s.jsonl", b"new\n"))
+    files = asyncio.run(store.read_all())
+    assert files == {"/d/s.jsonl": b"new\n"}
+
+
+def test_read_all_empty_root(tmp_path):
+    store = DiskObserverStore(str(tmp_path / "missing"))
+    assert asyncio.run(store.read_all()) == {}
+
+
+def test_observer_over_disk_round_trip(tmp_path):
+    obs = Observer(store=DiskObserverStore(str(tmp_path / "obs")))
+    asyncio.run(obs.log_clear(session="s1", agent="a"))
+    events = asyncio.run(obs.events())
+    assert events[-1]["type"] == "clear"
+    assert events[-1]["session"] == "s1"
+
+
+def test_disk_store_satisfies_protocol(tmp_path):
+    assert isinstance(DiskObserverStore(str(tmp_path)), ObserverStore)
+
+
+def test_read_matching_filters_by_suffix(tmp_path):
+    store = DiskObserverStore(str(tmp_path / "obs"))
+    asyncio.run(store.append("/d1/s1.jsonl", b"a\n"))
+    asyncio.run(store.append("/d1/s2.jsonl", b"b\n"))
+    asyncio.run(store.append("/d2/s1.jsonl", b"c\n"))
+    files = asyncio.run(store.read_matching("/s1.jsonl"))
+    assert files == {"/d1/s1.jsonl": b"a\n", "/d2/s1.jsonl": b"c\n"}
+
+
+def test_clear_empties_store(tmp_path):
+    store = DiskObserverStore(str(tmp_path / "obs"))
+    asyncio.run(store.append("/d/s.jsonl", b"a\n"))
+    asyncio.run(store.clear())
+    assert asyncio.run(store.read_all()) == {}

python/tests/observe/test_log_entry.py

@@ -0,0 +1,112 @@
+# ========= 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 json
+
+from mirage.observe import LogEntry, OpRecord
+from mirage.observe.log_entry import EVENT_COMMAND
+
+
+def test_from_op_record():
+    rec = OpRecord(
+        op="read",
+        path="/data/file.csv",
+        source="s3",
+        bytes=1024,
+        timestamp=1712145600000,
+        duration_ms=45,
+    )
+    entry = LogEntry.from_op_record(rec, agent="agent-1", session="sess-1")
+    assert entry.type == "op"
+    assert entry.agent == "agent-1"
+    assert entry.session == "sess-1"
+    assert entry.op == "read"
+    assert entry.path == "/data/file.csv"
+    assert entry.source == "s3"
+    assert entry.bytes == 1024
+    assert entry.duration_ms == 45
+
+
+def _command_entry(cwd: str | None = None) -> LogEntry:
+    return LogEntry(
+        type=EVENT_COMMAND,
+        agent="a",
+        session="s",
+        timestamp=1000,
+        cwd=cwd,
+        command="ls",
+        exit_code=0,
+        stdout="out",
+    )
+
+
+def test_to_json_line_op():
+    rec = OpRecord(
+        op="read",
+        path="/f.csv",
+        source="s3",
+        bytes=100,
+        timestamp=1000,
+        duration_ms=5,
+    )
+    entry = LogEntry.from_op_record(rec, agent="a", session="s")
+    line = entry.to_json_line()
+    parsed = json.loads(line)
+    assert parsed["type"] == "op"
+    assert parsed["agent"] == "a"
+    assert parsed["op"] == "read"
+    assert "command" not in parsed
+
+
+def test_to_json_line_command():
+    entry = _command_entry()
+    line = entry.to_json_line()
+    parsed = json.loads(line)
+    assert parsed["type"] == "command"
+    assert parsed["command"] == "ls"
+    assert "op" not in parsed
+
+
+def test_log_entry_includes_cwd_for_op():
+    rec = OpRecord(
+        op="read",
+        path="/f.csv",
+        source="s3",
+        bytes=100,
+        timestamp=1000,
+        duration_ms=5,
+    )
+    entry = LogEntry.from_op_record(rec, agent="a", session="s", cwd="/data")
+    parsed = json.loads(entry.to_json_line())
+    assert parsed["cwd"] == "/data"
+
+
+def test_log_entry_includes_cwd_for_command():
+    entry = _command_entry(cwd="/data")
+    parsed = json.loads(entry.to_json_line())
+    assert parsed["cwd"] == "/data"
+
+
+def test_log_entry_omits_cwd_when_not_provided():
+    rec = OpRecord(
+        op="read",
+        path="/f.csv",
+        source="s3",
+        bytes=100,
+        timestamp=1000,
+        duration_ms=5,
+    )
+    entry = LogEntry.from_op_record(rec, agent="a", session="s")
+    parsed = json.loads(entry.to_json_line())
+    assert "cwd" not in parsed

python/tests/observe/test_observer.py

@@ -0,0 +1,237 @@
+# ========= 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 json
+
+from mirage.io import IOResult
+from mirage.observe import OpRecord
+from mirage.observe.log_entry import EVENT_COMMAND, LogEntry
+from mirage.observe.observer import Observer
+from mirage.observe.store import RAMObserverStore
+from mirage.utils.dates import utc_date_folder
+
+
+def test_log_op_writes_jsonl():
+    store = RAMObserverStore()
+    obs = Observer(store=store)
+    rec = OpRecord(
+        op="read",
+        path="/data/f.csv",
+        source="s3",
+        bytes=100,
+        timestamp=1000,
+        duration_ms=5,
+    )
+    asyncio.run(obs.log_op(rec, agent="agent-1", session="sess-1"))
+    data = store.files[f"/{utc_date_folder()}/sess-1.jsonl"]
+    parsed = json.loads(data.decode().strip())
+    assert parsed["type"] == "op"
+    assert parsed["agent"] == "agent-1"
+    assert parsed["session"] == "sess-1"
+    assert parsed["op"] == "read"
+
+
+def test_log_execution_writes_jsonl():
+    store = RAMObserverStore()
+    obs = Observer(store=store)
+    io = IOResult(stdout=b"file.csv\n")
+    asyncio.run(
+        obs.log_execution("ls /data",
+                          io, [],
+                          agent="agent-1",
+                          session="sess-1"))
+    data = store.files[f"/{utc_date_folder()}/sess-1.jsonl"]
+    parsed = json.loads(data.decode().strip())
+    assert parsed["type"] == "command"
+    assert parsed["session"] == "sess-1"
+    assert parsed["command"] == "ls /data"
+    assert parsed["stdout"] == "file.csv\n"
+    assert parsed["exit_code"] == 0
+
+
+def test_multiple_entries_appended():
+    store = RAMObserverStore()
+    obs = Observer(store=store)
+    for i in range(3):
+        rec = OpRecord(
+            op="read",
+            path=f"/f{i}",
+            source="s3",
+            bytes=i,
+            timestamp=1000 + i,
+            duration_ms=1,
+        )
+        asyncio.run(obs.log_op(rec, agent="a", session="s"))
+    data = store.files[f"/{utc_date_folder()}/s.jsonl"]
+    lines = data.decode().strip().split("\n")
+    assert len(lines) == 3
+
+
+def _log_command(obs: Observer, command: str, session: str, ts: float) -> None:
+    entry = LogEntry(
+        type=EVENT_COMMAND,
+        agent="a",
+        session=session,
+        timestamp=int(ts * 1000),
+        command=command,
+        exit_code=0,
+    )
+    asyncio.run(obs._log(entry))
+
+
+def test_default_store_is_ram():
+    obs = Observer()
+    assert isinstance(obs.store, RAMObserverStore)
+
+
+def test_log_clear_appends_tombstone():
+    obs = Observer()
+    asyncio.run(obs.log_clear(session="s1", agent="a1"))
+    events = asyncio.run(obs.events())
+    assert events[-1]["type"] == "clear"
+    assert events[-1]["session"] == "s1"
+
+
+def test_command_events_all_sessions_timestamp_order():
+    obs = Observer()
+    _log_command(obs, "ls /a", "s2", 1.0)
+    _log_command(obs, "ls /b", "s1", 2.0)
+    op = OpRecord(
+        op="read",
+        path="/f",
+        source="ram",
+        bytes=0,
+        timestamp=1500,
+        duration_ms=1,
+    )
+    asyncio.run(obs.log_op(op, agent="a", session="s1"))
+    events = asyncio.run(obs.command_events())
+    assert [e["command"] for e in events] == ["ls /a", "ls /b"]
+    assert all(e["type"] == "command" for e in events)
+
+
+def test_session_same_timestamp_keeps_append_order():
+    obs = Observer()
+    _log_command(obs, "first", "s1", 1.0)
+    _log_command(obs, "second", "s1", 1.0)
+    _log_command(obs, "third", "s1", 1.0)
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["first", "second", "third"]
+
+
+def test_session_command_events_respects_last_clear():
+    obs = Observer()
+    _log_command(obs, "cmd A", "s1", 1.0)
+    asyncio.run(obs.log_clear(session="s1", agent="a"))
+    _log_command(obs, "cmd B", "s1", 2.0)
+    _log_command(obs, "cmd C", "s2", 3.0)
+    s1 = asyncio.run(obs.session_command_events("s1"))
+    s2 = asyncio.run(obs.session_command_events("s2"))
+    assert [e["command"] for e in s1] == ["cmd B"]
+    assert [e["command"] for e in s2] == ["cmd C"]
+
+
+def test_load_events_restores_and_resumes():
+    obs = Observer()
+    _log_command(obs, "old", "s1", 1.0)
+    events = asyncio.run(obs.events())
+    restored = Observer()
+    asyncio.run(restored.load_events(events))
+    _log_command(restored, "new", "s1", 2.0)
+    out = asyncio.run(restored.command_events())
+    assert [e["command"] for e in out] == ["old", "new"]
+
+
+def test_log_command_text_appends_single_entry():
+    obs = Observer()
+    asyncio.run(obs.log_command_text("a b c", session="s1"))
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["a b c"]
+    assert events[0]["exit_code"] == 0
+
+
+def test_delete_event_removes_entry_and_renumbers():
+    obs = Observer()
+    _log_command(obs, "one", "s1", 1.0)
+    _log_command(obs, "two", "s1", 2.0)
+    _log_command(obs, "three", "s1", 3.0)
+    asyncio.run(obs.log_delete(session="s1", offset=2))
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["one", "three"]
+
+
+def test_delete_negative_offset_counts_from_end():
+    obs = Observer()
+    _log_command(obs, "one", "s1", 1.0)
+    _log_command(obs, "two", "s1", 2.0)
+    asyncio.run(obs.log_delete(session="s1", offset=-1))
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["one"]
+
+
+def test_delete_applies_at_issue_time_position():
+    obs = Observer()
+    _log_command(obs, "one", "s1", 1.0)
+    asyncio.run(obs.log_delete(session="s1", offset=1))
+    _log_command(obs, "two", "s1", 2.0)
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["two"]
+
+
+def test_clear_discards_earlier_deletes():
+    obs = Observer()
+    _log_command(obs, "one", "s1", 1.0)
+    asyncio.run(obs.log_delete(session="s1", offset=1))
+    asyncio.run(obs.log_clear(session="s1"))
+    _log_command(obs, "two", "s1", 2.0)
+    events = asyncio.run(obs.session_command_events("s1"))
+    assert [e["command"] for e in events] == ["two"]
+
+
+def test_load_events_rewinds_pre_restore_timeline():
+    src = Observer()
+    _log_command(src, "snap-cmd", "snap", 2.0)
+    snapshot_events = asyncio.run(src.events())
+    obs = Observer()
+    _log_command(obs, "old-live", "live", 1.0)
+    asyncio.run(obs.load_events(snapshot_events))
+    out = asyncio.run(obs.command_events())
+    assert [e["command"] for e in out] == ["snap-cmd"]
+    assert {e["session"] for e in asyncio.run(obs.events())} == {"snap"}
+
+
+def test_load_events_empty_snapshot_still_clears():
+    obs = Observer()
+    _log_command(obs, "old", "s1", 1.0)
+    asyncio.run(obs.load_events([]))
+    assert asyncio.run(obs.events()) == []
+
+
+def test_load_events_skips_foreign_format_entries():
+    obs = Observer()
+    foreign = {
+        "agent": "default",
+        "command": "cat /a | wc -l",
+        "stdout": b"5\n",
+        "tree": {
+            "command": "cat /a | wc -l",
+            "children": []
+        },
+        "session_id": "default",
+    }
+    native = {"type": EVENT_COMMAND, "session": "s1", "command": "echo hi"}
+    asyncio.run(obs.load_events([foreign, native]))
+    events = asyncio.run(obs.command_events())
+    assert [e["command"] for e in events] == ["echo hi"]

python/tests/observe/test_op_record.py

@@ -0,0 +1,112 @@
+# ========= 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. =========
+
+from mirage.observe import OpRecord
+from mirage.workspace.types import ExecutionNode
+
+
+def test_op_record_fields():
+    r = OpRecord(
+        op="read",
+        path="/s3/data/file.csv",
+        source="s3",
+        bytes=1024,
+        timestamp=1711800000000,
+        duration_ms=150,
+    )
+    assert r.op == "read"
+    assert r.path == "/s3/data/file.csv"
+    assert r.source == "s3"
+    assert r.bytes == 1024
+    assert r.timestamp == 1711800000000
+    assert r.duration_ms == 150
+    assert r.fingerprint is None
+    assert r.revision is None
+
+
+def test_op_record_with_fingerprint():
+    r = OpRecord(
+        op="read",
+        path="/s3/data/file.csv",
+        source="s3",
+        bytes=1024,
+        timestamp=1711800000000,
+        duration_ms=150,
+        fingerprint="abc123",
+    )
+    assert r.fingerprint == "abc123"
+    assert r.revision is None
+
+
+def test_op_record_with_revision():
+    r = OpRecord(
+        op="read",
+        path="/s3/data/file.csv",
+        source="s3",
+        bytes=1024,
+        timestamp=1711800000000,
+        duration_ms=150,
+        revision="vL5_raa...",
+    )
+    assert r.revision == "vL5_raa..."
+    assert r.fingerprint is None
+
+
+def test_op_record_with_both():
+    r = OpRecord(
+        op="read",
+        path="/s3/data/file.csv",
+        source="s3",
+        bytes=1024,
+        timestamp=1711800000000,
+        duration_ms=150,
+        fingerprint="abc123",
+        revision="vL5_raa...",
+    )
+    assert r.fingerprint == "abc123"
+    assert r.revision == "vL5_raa..."
+
+
+def test_op_record_zero_bytes():
+    r = OpRecord(
+        op="stat",
+        path="/s3/data/file.csv",
+        source="s3",
+        bytes=0,
+        timestamp=1711800000000,
+        duration_ms=5,
+    )
+    assert r.bytes == 0
+
+
+def test_execution_node_has_records():
+    node = ExecutionNode(command="cat /s3/data/a.txt", exit_code=0)
+    assert node.records == []
+
+
+def test_execution_node_records_in_to_dict():
+    from mirage.workspace.types import ExecutionNode
+
+    r = OpRecord(
+        op="read",
+        path="/s3/a.txt",
+        source="s3",
+        bytes=100,
+        timestamp=1711800000000,
+        duration_ms=10,
+    )
+    node = ExecutionNode(command="cat /s3/a.txt", exit_code=0, records=[r])
+    d = node.to_dict()
+    assert len(d["records"]) == 1
+    assert d["records"][0]["op"] == "read"

python/tests/observe/test_ops_records.py

@@ -0,0 +1,75 @@
+# ========= 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 mirage.cache.index.ram import RAMIndexCacheStore
+from mirage.ops import Ops
+from mirage.ops.config import OpsMount
+from mirage.resource.ram import RAMResource
+from mirage.types import MountMode
+
+
+def _make_ops() -> tuple[Ops, RAMResource]:
+    mem = RAMResource()
+    mount = OpsMount(
+        prefix="/data/",
+        resource_type="ram",
+        accessor=mem.accessor,
+        index=RAMIndexCacheStore(),
+        mode=MountMode.WRITE,
+        ops=mem.ops_list(),
+    )
+    ops = Ops(mounts=[mount])
+    return ops, mem
+
+
+def test_read_records_op_record():
+    ops, mem = _make_ops()
+    mem._store.files["/hello.txt"] = b"hello world"
+    asyncio.run(ops.read("/data/hello.txt"))
+    assert len(ops.records) == 1
+    r = ops.records[0]
+    assert r.op == "read"
+    assert r.path == "/data/hello.txt"
+    assert r.bytes == 11
+    assert r.duration_ms >= 0
+
+
+def test_write_records_op_record():
+    ops, mem = _make_ops()
+    asyncio.run(ops.write("/data/hello.txt", b"hello"))
+    assert len(ops.records) == 1
+    r = ops.records[0]
+    assert r.op == "write"
+    assert r.bytes == 5
+
+
+def test_stat_records_op_record():
+    ops, mem = _make_ops()
+    mem._store.files["/hello.txt"] = b"hello"
+    asyncio.run(ops.stat("/data/hello.txt"))
+    assert len(ops.records) == 1
+    assert ops.records[0].op == "stat"
+    assert ops.records[0].bytes == 0
+
+
+def test_cache_hit_records_source_memory():
+    ops, mem = _make_ops()
+    mem._store.files["/hello.txt"] = b"hello world"
+    asyncio.run(ops.read("/data/hello.txt"))
+    asyncio.run(ops.read("/data/hello.txt"))
+    assert len(ops.records) == 2
+    assert ops.records[0].source == "ram"
+    assert ops.records[1].source == "ram"

python/tests/observe/test_redis_store.py

@@ -0,0 +1,81 @@
+# ========= 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 pytest
+import pytest_asyncio
+
+from mirage.observe.observer import Observer
+from mirage.observe.redis_store import RedisObserverStore
+from mirage.observe.store import ObserverStore
+
+REDIS_URL = os.environ.get("REDIS_URL", "")
+pytestmark = pytest.mark.skipif(not REDIS_URL, reason="REDIS_URL not set")
+
+
+@pytest_asyncio.fixture()
+async def store():
+    s = RedisObserverStore(url=REDIS_URL, key_prefix="test:observer:")
+    await s.clear()
+    yield s
+    await s.clear()
+
+
+@pytest.mark.asyncio
+async def test_append_creates_and_extends(store):
+    await store.append("/d/s.jsonl", b"a\n")
+    await store.append("/d/s.jsonl", b"b\n")
+    files = await store.read_all()
+    assert files == {"/d/s.jsonl": b"a\nb\n"}
+
+
+@pytest.mark.asyncio
+async def test_write_overwrites(store):
+    await store.append("/d/s.jsonl", b"old\n")
+    await store.write("/d/s.jsonl", b"new\n")
+    files = await store.read_all()
+    assert files == {"/d/s.jsonl": b"new\n"}
+
+
+@pytest.mark.asyncio
+async def test_clear_empties_namespace(store):
+    await store.append("/d/a.jsonl", b"x\n")
+    await store.append("/d/b.jsonl", b"y\n")
+    await store.clear()
+    assert await store.read_all() == {}
+
+
+@pytest.mark.asyncio
+async def test_observer_over_redis_round_trip(store):
+    obs = Observer(store=store)
+    await obs.log_clear(session="s1", agent="a")
+    events = await obs.events()
+    assert events[-1]["type"] == "clear"
+    assert events[-1]["session"] == "s1"
+
+
+def test_redis_store_satisfies_protocol():
+    assert isinstance(
+        RedisObserverStore(url=REDIS_URL, key_prefix="test:observer:"),
+        ObserverStore)
+
+
+@pytest.mark.asyncio
+async def test_read_matching_filters_by_suffix(store):
+    await store.append("/d1/s1.jsonl", b"a\n")
+    await store.append("/d1/s2.jsonl", b"b\n")
+    await store.append("/d2/s1.jsonl", b"c\n")
+    files = await store.read_matching("/s1.jsonl")
+    assert files == {"/d1/s1.jsonl": b"a\n", "/d2/s1.jsonl": b"c\n"}

python/tests/observe/test_store.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 asyncio
+
+from mirage.observe.store import ObserverStore, RAMObserverStore
+
+
+def test_append_creates_and_extends():
+    store = RAMObserverStore()
+    asyncio.run(store.append("/d/s.jsonl", b"a\n"))
+    asyncio.run(store.append("/d/s.jsonl", b"b\n"))
+    files = asyncio.run(store.read_all())
+    assert files == {"/d/s.jsonl": b"a\nb\n"}
+
+
+def test_write_overwrites():
+    store = RAMObserverStore()
+    asyncio.run(store.append("/d/s.jsonl", b"old\n"))
+    asyncio.run(store.write("/d/s.jsonl", b"new\n"))
+    files = asyncio.run(store.read_all())
+    assert files == {"/d/s.jsonl": b"new\n"}
+
+
+def test_read_all_returns_copy():
+    store = RAMObserverStore()
+    asyncio.run(store.append("/d/s.jsonl", b"a\n"))
+    files = asyncio.run(store.read_all())
+    files["/d/s.jsonl"] = b"mutated"
+    assert asyncio.run(store.read_all()) == {"/d/s.jsonl": b"a\n"}
+
+
+def test_ram_store_satisfies_protocol():
+    assert isinstance(RAMObserverStore(), ObserverStore)
+
+
+def test_read_matching_filters_by_suffix():
+    store = RAMObserverStore()
+    asyncio.run(store.append("/d1/s1.jsonl", b"a\n"))
+    asyncio.run(store.append("/d1/s2.jsonl", b"b\n"))
+    asyncio.run(store.append("/d2/s1.jsonl", b"c\n"))
+    files = asyncio.run(store.read_matching("/s1.jsonl"))
+    assert files == {"/d1/s1.jsonl": b"a\n", "/d2/s1.jsonl": b"c\n"}
+
+
+def test_clear_empties_store():
+    store = RAMObserverStore()
+    asyncio.run(store.append("/d/s.jsonl", b"a\n"))
+    asyncio.run(store.clear())
+    assert asyncio.run(store.read_all()) == {}

python/tests/observe/test_workspace_observe.py

@@ -0,0 +1,75 @@
+# ========= 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 json
+
+from mirage import MountMode, Workspace
+from mirage.observe.store import RAMObserverStore
+from mirage.resource.ram import RAMResource
+
+
+def test_workspace_creates_default_observer():
+    ws = Workspace({"/data/": RAMResource()}, mode=MountMode.WRITE)
+    assert ws.observer is not None
+    assert isinstance(ws.observer.store, RAMObserverStore)
+
+
+def test_workspace_custom_observe_store():
+    obs_store = RAMObserverStore()
+    ws = Workspace(
+        {"/data/": RAMResource()},
+        mode=MountMode.WRITE,
+        observe=obs_store,
+    )
+    assert ws.observer.store is obs_store
+
+
+def test_logs_populated_after_execute():
+    obs_store = RAMObserverStore()
+    ws = Workspace({"/data/": RAMResource()},
+                   mode=MountMode.WRITE,
+                   observe=obs_store)
+    asyncio.run(ws.execute("echo hello > /data/test.txt"))
+    session_files = [k for k in obs_store.files if k.endswith(".jsonl")]
+    assert len(session_files) >= 1
+    data = obs_store.files[session_files[0]]
+    lines = data.decode().strip().split("\n")
+    assert len(lines) >= 1
+    entry = json.loads(lines[-1])
+    assert entry["type"] == "command"
+
+
+def test_logs_contain_op_records():
+    obs_store = RAMObserverStore()
+    ws = Workspace({"/data/": RAMResource()},
+                   mode=MountMode.WRITE,
+                   observe=obs_store)
+    asyncio.run(ws.execute("echo hello > /data/test.txt"))
+    asyncio.run(ws.execute("cat /data/test.txt"))
+    session_files = [k for k in obs_store.files if k.endswith(".jsonl")]
+    data = obs_store.files[session_files[0]]
+    lines = data.decode().strip().split("\n")
+    types = {json.loads(line)["type"] for line in lines}
+    assert "op" in types
+    assert "command" in types
+
+
+def test_observer_store_not_mounted():
+    ws = Workspace({"/data/": RAMResource()}, mode=MountMode.WRITE)
+    asyncio.run(ws.execute("echo hi > /data/f.txt"))
+    result = asyncio.run(ws.execute("ls /.sessions"))
+    assert result.exit_code != 0
+    prefixes = {m.prefix for m in ws._registry.mounts()}
+    assert prefixes == {"/", "/data/", "/dev/", "/.bash_history/"}