chore: import upstream snapshot with attribution

python/mirage/workspace/session/__init__.py

@@ -0,0 +1,27 @@
+# ========= 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.runtime import (assert_mount_allowed, get_current_session,
+                            reset_current_session, set_current_session)
+from mirage.workspace.session.manager import SessionManager
+from mirage.workspace.session.session import Session
+
+__all__ = [
+    "Session",
+    "SessionManager",
+    "assert_mount_allowed",
+    "get_current_session",
+    "reset_current_session",
+    "set_current_session",
+]

python/mirage/workspace/session/manager.py

@@ -0,0 +1,83 @@
+# ========= 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.workspace.session.session import Session
+
+
+class SessionManager:
+
+    def __init__(self, default_session_id: str) -> None:
+        self._default_id = default_session_id
+        self._sessions: dict[str, Session] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._sessions[default_session_id] = Session(
+            session_id=default_session_id)
+        self._locks[default_session_id] = asyncio.Lock()
+
+    @property
+    def default_id(self) -> str:
+        return self._default_id
+
+    @property
+    def cwd(self) -> str:
+        return self._sessions[self._default_id].cwd
+
+    @cwd.setter
+    def cwd(self, value: str) -> None:
+        self._sessions[self._default_id].cwd = value
+
+    @property
+    def env(self) -> dict[str, str]:
+        return self._sessions[self._default_id].env
+
+    @env.setter
+    def env(self, value: dict[str, str]) -> None:
+        self._sessions[self._default_id].env = value
+
+    def create(self,
+               session_id: str,
+               allowed_mounts: frozenset[str] | None = None) -> Session:
+        if session_id in self._sessions:
+            raise ValueError(f"Session {session_id!r} already exists")
+        session = Session(session_id=session_id, allowed_mounts=allowed_mounts)
+        self._sessions[session_id] = session
+        self._locks[session_id] = asyncio.Lock()
+        return session
+
+    def get(self, session_id: str) -> Session:
+        return self._sessions[session_id]
+
+    def list(self) -> list[Session]:
+        return list(self._sessions.values())
+
+    async def close(self, session_id: str) -> None:
+        if session_id == self._default_id:
+            raise ValueError("Cannot close the default session")
+        if session_id not in self._sessions:
+            raise KeyError(session_id)
+        async with self._locks[session_id]:
+            del self._sessions[session_id]
+        del self._locks[session_id]
+
+    async def close_all(self) -> None:
+        session_ids = [
+            sid for sid in self._sessions if sid != self._default_id
+        ]
+        for sid in session_ids:
+            await self.close(sid)
+
+    def lock_for(self, session_id: str) -> asyncio.Lock:
+        return self._locks[session_id]

python/mirage/workspace/session/session.py

@@ -0,0 +1,77 @@
+# ========= 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 time
+from dataclasses import dataclass, field
+
+from mirage.io.async_line_iterator import AsyncLineIterator
+
+
+@dataclass
+class Session:
+    session_id: str
+    cwd: str = "/"
+    env: dict[str, str] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+    functions: dict[str, object] = field(default_factory=dict)
+    last_exit_code: int = 0
+    shell_options: dict[str, bool] = field(default_factory=dict)
+    readonly_vars: set[str] = field(default_factory=set)
+    arrays: dict[str, list[str]] = field(default_factory=dict)
+    allowed_mounts: frozenset[str] | None = None
+    pipeline_timeout_seconds: float | None = None
+    _stdin_buffer: AsyncLineIterator | None = field(default=None, repr=False)
+
+    def to_dict(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "cwd": self.cwd,
+            "env": self.env,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Session":
+        return cls(**data)
+
+    def fork(self, **overrides) -> "Session":
+        """Return a copy of this session with overrides applied.
+
+        Mutable containers (env, functions, readonly_vars, arrays,
+        shell_options) are shallow-copied so mutations on the fork do
+        not leak back into the source. Every field, including
+        capability fields like ``allowed_mounts``, is propagated, so
+        callers cannot accidentally forget one when adding new fields.
+
+        Args:
+            **overrides: Field-name kwargs to override on the copy.
+        """
+        defaults = {
+            "session_id": self.session_id,
+            "cwd": self.cwd,
+            "env": dict(self.env),
+            "created_at": self.created_at,
+            "functions": dict(self.functions),
+            "last_exit_code": self.last_exit_code,
+            "shell_options": dict(self.shell_options),
+            "readonly_vars": set(self.readonly_vars),
+            "arrays": {
+                k: list(v)
+                for k, v in self.arrays.items()
+            },
+            "allowed_mounts": self.allowed_mounts,
+            "pipeline_timeout_seconds": self.pipeline_timeout_seconds,
+        }
+        defaults.update(overrides)
+        return Session(**defaults)

python/mirage/workspace/session/shell_dirs.py

@@ -0,0 +1,44 @@
+# ========= 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.workspace.session.session import Session
+
+
+def home_dir(session: Session) -> str | None:
+    """Return the session home directory used for ``~`` expansion.
+
+    Args:
+        session: The shell session.
+
+    Returns:
+        ``$HOME`` from the session env, or ``None`` when unset/empty,
+        matching GNU bash (no implicit home; ``cd`` errors, ``~`` and
+        ``$HOME`` do not expand).
+    """
+    return session.env.get("HOME") or None
+
+
+def change_dir(session: Session, new_cwd: str) -> None:
+    """Move the session to ``new_cwd`` and record the previous cwd.
+
+    Sets ``$OLDPWD`` to the current cwd before switching, mirroring the
+    bash ``cd`` builtin. ``$PWD`` is resolved dynamically from
+    ``session.cwd`` at lookup time, so it is not stored here.
+
+    Args:
+        session: The shell session to mutate.
+        new_cwd: The absolute path to switch to.
+    """
+    session.env["OLDPWD"] = session.cwd
+    session.cwd = new_cwd