chore: import upstream snapshot with attribution

python/mirage/core/github_ci/__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/mirage/core/github_ci/_client.py

@@ -0,0 +1,69 @@
+# ========= 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 aiohttp
+
+from mirage.core.github._client import github_headers, github_url
+
+
+async def ci_get(token: str,
+                 path: str,
+                 params: dict | None = None,
+                 **kwargs: str) -> dict:
+    url = github_url(path, **kwargs)
+    headers = github_headers(token)
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=headers, params=params) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+
+async def ci_get_bytes(token: str, path: str, **kwargs: str) -> bytes:
+    url = github_url(path, **kwargs)
+    headers = github_headers(token)
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url, headers=headers,
+                               allow_redirects=True) as resp:
+            resp.raise_for_status()
+            return await resp.read()
+
+
+async def ci_get_paginated(token: str,
+                           path: str,
+                           list_key: str,
+                           params: dict | None = None,
+                           max_results: int | None = None,
+                           **kwargs: str) -> list[dict]:
+    params = dict(params or {})
+    params.setdefault("per_page", 100)
+    page = 1
+    results: list[dict] = []
+    url = github_url(path, **kwargs)
+    headers = github_headers(token)
+    async with aiohttp.ClientSession() as session:
+        while True:
+            params["page"] = page
+            async with session.get(url, headers=headers,
+                                   params=params) as resp:
+                resp.raise_for_status()
+                data = await resp.json()
+            batch = data[list_key]
+            results.extend(batch)
+            if max_results is not None and len(results) >= max_results:
+                results = results[:max_results]
+                break
+            if len(batch) < params["per_page"]:
+                break
+            page += 1
+    return results

python/mirage/core/github_ci/annotations.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.core.github_ci._client import ci_get
+from mirage.resource.github_ci.config import GitHubCIConfig
+
+
+async def list_annotations(config: GitHubCIConfig,
+                           check_run_id: str) -> list[dict]:
+    return await ci_get(
+        config.token,
+        "/repos/{owner}/{repo}/check-runs/{check_run_id}/annotations",
+        owner=config.owner,
+        repo=config.repo,
+        check_run_id=check_run_id,
+    )

python/mirage/core/github_ci/artifacts.py

@@ -0,0 +1,37 @@
+# ========= 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.core.github_ci._client import ci_get_bytes, ci_get_paginated
+from mirage.resource.github_ci.config import GitHubCIConfig
+
+
+async def list_artifacts(config: GitHubCIConfig, run_id: str) -> list[dict]:
+    return await ci_get_paginated(
+        config.token,
+        "/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts",
+        list_key="artifacts",
+        owner=config.owner,
+        repo=config.repo,
+        run_id=run_id,
+    )
+
+
+async def download_artifact(config: GitHubCIConfig, artifact_id: str) -> bytes:
+    return await ci_get_bytes(
+        config.token,
+        "/repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip",
+        owner=config.owner,
+        repo=config.repo,
+        artifact_id=artifact_id,
+    )

python/mirage/core/github_ci/glob.py

@@ -0,0 +1,41 @@
+# ========= 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.accessor.github_ci import GitHubCIAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import SCOPE_ERROR
+from mirage.core.github_ci.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+from mirage.utils.key_prefix import mount_prefix_of
+
+
+def is_cross_run_root(path: PathSpec) -> bool:
+    original = path.virtual if isinstance(path, PathSpec) else path
+    prefix = mount_prefix_of(path.virtual, path.resource_path) if isinstance(
+        path, PathSpec) else ""
+    if prefix and original.startswith(prefix):
+        rest = original[len(prefix):]
+        if prefix.endswith("/") or rest == "" or rest.startswith("/"):
+            original = rest or "/"
+    return original.strip("/") in ("", "runs")
+
+
+async def resolve_glob(
+    accessor: GitHubCIAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore | None = None,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/github_ci/read.py

@@ -0,0 +1,119 @@
+# ========= 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.accessor.github_ci import GitHubCIAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.github_ci.annotations import list_annotations
+from mirage.core.github_ci.artifacts import download_artifact
+from mirage.core.github_ci.runs import (download_job_log, get_job, get_run,
+                                        list_jobs_for_run)
+from mirage.core.github_ci.workflows import get_workflow
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_prefix_of
+
+
+async def read(
+    accessor: GitHubCIAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    key = path.resource_path
+    parts = key.split("/")
+
+    # /workflows/<name>_<id>.json
+    if len(parts) == 2 and parts[0] == "workflows" and parts[1].endswith(
+            ".json"):
+        if index is None:
+            raise enoent(virtual)
+        virtual_key = prefix + "/" + key
+        lookup = await index.get(virtual_key)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        wf = await get_workflow(accessor.config, lookup.entry.id)
+        return json.dumps(wf, indent=2, ensure_ascii=False).encode()
+
+    # /runs/<workflow>_<run-id>/run.json
+    if (len(parts) == 3 and parts[0] == "runs" and parts[2] == "run.json"):
+        if index is None:
+            raise enoent(virtual)
+        run_virtual = prefix + "/" + f"{parts[0]}/{parts[1]}"
+        lookup = await index.get(run_virtual)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        run = await get_run(accessor.config, lookup.entry.id)
+        return json.dumps(run, indent=2, ensure_ascii=False).encode()
+
+    # /runs/<workflow>_<run-id>/annotations.jsonl
+    if (len(parts) == 3 and parts[0] == "runs"
+            and parts[2] == "annotations.jsonl"):
+        if index is None:
+            raise enoent(virtual)
+        run_virtual = prefix + "/" + f"{parts[0]}/{parts[1]}"
+        lookup = await index.get(run_virtual)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        jobs = await list_jobs_for_run(accessor.config, lookup.entry.id)
+        lines = []
+        for j in jobs:
+            anns = await list_annotations(accessor.config, str(j["id"]))
+            for a in anns:
+                lines.append(
+                    json.dumps(a, ensure_ascii=False, separators=(",", ":")))
+        if lines:
+            return ("\n".join(lines) + "\n").encode()
+        return b""
+
+    # /runs/<workflow>_<run-id>/jobs/<job>_<job-id>.json
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "jobs"
+            and parts[3].endswith(".json")):
+        if index is None:
+            raise enoent(virtual)
+        virtual_key = prefix + "/" + key
+        lookup = await index.get(virtual_key)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        job = await get_job(accessor.config, lookup.entry.id)
+        return json.dumps(job, indent=2, ensure_ascii=False).encode()
+
+    # /runs/<workflow>_<run-id>/jobs/<job>_<job-id>.log
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "jobs"
+            and parts[3].endswith(".log")):
+        if index is None:
+            raise enoent(virtual)
+        virtual_key = prefix + "/" + key
+        lookup = await index.get(virtual_key)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return await download_job_log(accessor.config, lookup.entry.id)
+
+    # /runs/<workflow>_<run-id>/artifacts/<name>_<id>.zip
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "artifacts"):
+        if index is None:
+            raise enoent(virtual)
+        virtual_key = prefix + "/" + key
+        lookup = await index.get(virtual_key)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return await download_artifact(accessor.config, lookup.entry.id)
+
+    raise enoent(virtual)

python/mirage/core/github_ci/readdir.py

@@ -0,0 +1,222 @@
+# ========= 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.accessor.github_ci import GitHubCIAccessor
+from mirage.cache.index import IndexCacheStore, IndexEntry
+from mirage.core.github_ci.artifacts import list_artifacts
+from mirage.core.github_ci.runs import list_jobs_for_run, list_runs
+from mirage.core.github_ci.workflows import list_workflows
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+def _safe_name(name: str) -> str:
+    if not name:
+        return "unknown"
+    return name.replace("/", "\u2215")
+
+
+async def readdir(
+    accessor: GitHubCIAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    path = (path.dir if path.pattern else path).mount_path
+    key = path.strip("/")
+    virtual_key = prefix + "/" + key if key else prefix or "/"
+
+    if not key:
+        return [f"{prefix}/workflows", f"{prefix}/runs"]
+
+    parts = key.split("/")
+
+    # /workflows
+    if len(parts) == 1 and parts[0] == "workflows":
+        if index is not None:
+            listing = await index.list_dir(virtual_key)
+            if listing.entries is not None:
+                return listing.entries
+        workflows = await list_workflows(accessor.config)
+        entries = []
+        names = []
+        for wf in workflows:
+            name = _safe_name(wf.get("name", str(wf["id"])))
+            filename = f"{name}_{wf['id']}.json"
+            entry = IndexEntry(
+                id=str(wf["id"]),
+                name=wf.get("name", ""),
+                resource_type="ci/workflow",
+                vfs_name=filename,
+                remote_time=wf.get("updated_at", ""),
+            )
+            entries.append((filename, entry))
+            names.append(f"{prefix}/{key}/{filename}")
+        if index is not None:
+            await index.set_dir(virtual_key, entries)
+        return names
+
+    # /runs
+    if len(parts) == 1 and parts[0] == "runs":
+        if index is not None:
+            listing = await index.list_dir(virtual_key)
+            if listing.entries is not None:
+                return listing.entries
+        runs = await list_runs(accessor.config, days=accessor.config.days)
+        entries = []
+        names = []
+        for r in runs:
+            wf_name = _safe_name(r.get("name", str(r["id"])))
+            dirname = f"{wf_name}_{r['id']}"
+            entry = IndexEntry(
+                id=str(r["id"]),
+                name=r.get("name", ""),
+                resource_type="ci/run",
+                vfs_name=dirname,
+                remote_time=r.get("updated_at", ""),
+            )
+            entries.append((dirname, entry))
+            names.append(f"{prefix}/{key}/{dirname}")
+        if index is not None:
+            await index.set_dir(virtual_key, entries)
+        return names
+
+    # /runs/<workflow>_<run-id>
+    if len(parts) == 2 and parts[0] == "runs":
+        if index is not None:
+            lookup = await index.get(virtual_key)
+            if lookup.entry is None:
+                parent = PathSpec(
+                    virtual=prefix + "/runs",
+                    directory=prefix + "/runs",
+                    resource_path=mount_key(prefix + "/runs", prefix),
+                )
+                await readdir(accessor, parent, index)
+                lookup = await index.get(virtual_key)
+            if lookup.entry is None:
+                raise enoent(virtual)
+        base = f"{prefix}/{key}"
+        return [
+            f"{base}/run.json",
+            f"{base}/jobs",
+            f"{base}/annotations.jsonl",
+            f"{base}/artifacts",
+        ]
+
+    # /runs/<workflow>_<run-id>/jobs
+    if len(parts) == 3 and parts[0] == "runs" and parts[2] == "jobs":
+        if index is not None:
+            listing = await index.list_dir(virtual_key)
+            if listing.entries is not None:
+                return listing.entries
+            run_virtual = prefix + "/" + f"{parts[0]}/{parts[1]}"
+            run_lookup = await index.get(run_virtual)
+            if run_lookup.entry is None:
+                parent = PathSpec(
+                    virtual=prefix + "/runs",
+                    directory=prefix + "/runs",
+                    resource_path=mount_key(prefix + "/runs", prefix),
+                )
+                await readdir(accessor, parent, index)
+                run_lookup = await index.get(run_virtual)
+            if run_lookup.entry is None:
+                raise enoent(virtual)
+            run_id = run_lookup.entry.id
+        else:
+            raise enoent(virtual)
+        jobs = await list_jobs_for_run(accessor.config, run_id)
+        entries = []
+        names = []
+        for j in jobs:
+            name = _safe_name(j.get("name", str(j["id"])))
+            json_filename = f"{name}_{j['id']}.json"
+            log_filename = f"{name}_{j['id']}.log"
+            entry_json = IndexEntry(
+                id=str(j["id"]),
+                name=j.get("name", ""),
+                resource_type="ci/job",
+                vfs_name=json_filename,
+                remote_time=j.get("completed_at", ""),
+            )
+            entry_log = IndexEntry(
+                id=str(j["id"]),
+                name=j.get("name", ""),
+                resource_type="ci/job_log",
+                vfs_name=log_filename,
+                remote_time=j.get("completed_at", ""),
+            )
+            entries.append((json_filename, entry_json))
+            entries.append((log_filename, entry_log))
+            names.append(f"{prefix}/{key}/{json_filename}")
+            names.append(f"{prefix}/{key}/{log_filename}")
+        if index is not None:
+            await index.set_dir(virtual_key, entries)
+        return names
+
+    # /runs/<workflow>_<run-id>/artifacts
+    if len(parts) == 3 and parts[0] == "runs" and parts[2] == "artifacts":
+        if index is not None:
+            listing = await index.list_dir(virtual_key)
+            if listing.entries is not None:
+                return listing.entries
+            run_virtual = prefix + "/" + f"{parts[0]}/{parts[1]}"
+            run_lookup = await index.get(run_virtual)
+            if run_lookup.entry is None:
+                parent = PathSpec(
+                    virtual=prefix + "/runs",
+                    directory=prefix + "/runs",
+                    resource_path=mount_key(prefix + "/runs", prefix),
+                )
+                await readdir(accessor, parent, index)
+                run_lookup = await index.get(run_virtual)
+            if run_lookup.entry is None:
+                raise enoent(virtual)
+            run_id = run_lookup.entry.id
+        else:
+            raise enoent(virtual)
+        artifacts = await list_artifacts(accessor.config, run_id)
+        entries = []
+        names = []
+        for a in artifacts:
+            name = _safe_name(a.get("name", str(a["id"])))
+            filename = f"{name}_{a['id']}.zip"
+            entry = IndexEntry(
+                id=str(a["id"]),
+                name=a.get("name", ""),
+                resource_type="ci/artifact",
+                vfs_name=filename,
+                size=a.get("size_in_bytes"),
+                remote_time=a.get("updated_at", ""),
+            )
+            entries.append((filename, entry))
+            names.append(f"{prefix}/{key}/{filename}")
+        if index is not None:
+            await index.set_dir(virtual_key, entries)
+        return names
+
+    return []
+
+
+def is_dir_name(child: str) -> bool:
+    # Entries are recognized by extension, so classification never needs
+    # the stat fallback.
+    name = child.rsplit("/", 1)[-1]
+    return not (name.endswith(".json") or name.endswith(".jsonl")
+                or name.endswith(".log") or name.endswith(".zip"))

python/mirage/core/github_ci/runs.py

@@ -0,0 +1,74 @@
+# ========= 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 datetime import datetime, timedelta, timezone
+
+from mirage.core.github_ci._client import (ci_get, ci_get_bytes,
+                                           ci_get_paginated)
+from mirage.resource.github_ci.config import GitHubCIConfig
+
+
+async def list_runs(config: GitHubCIConfig, days: int = 30) -> list[dict]:
+    since = (datetime.now(timezone.utc) -
+             timedelta(days=days)).strftime("%Y-%m-%d")
+    return await ci_get_paginated(
+        config.token,
+        "/repos/{owner}/{repo}/actions/runs",
+        list_key="workflow_runs",
+        params={"created": f">={since}"},
+        max_results=config.max_runs,
+        owner=config.owner,
+        repo=config.repo,
+    )
+
+
+async def get_run(config: GitHubCIConfig, run_id: str) -> dict:
+    return await ci_get(
+        config.token,
+        "/repos/{owner}/{repo}/actions/runs/{run_id}",
+        owner=config.owner,
+        repo=config.repo,
+        run_id=run_id,
+    )
+
+
+async def list_jobs_for_run(config: GitHubCIConfig, run_id: str) -> list[dict]:
+    return await ci_get_paginated(
+        config.token,
+        "/repos/{owner}/{repo}/actions/runs/{run_id}/jobs",
+        list_key="jobs",
+        owner=config.owner,
+        repo=config.repo,
+        run_id=run_id,
+    )
+
+
+async def get_job(config: GitHubCIConfig, job_id: str) -> dict:
+    return await ci_get(
+        config.token,
+        "/repos/{owner}/{repo}/actions/jobs/{job_id}",
+        owner=config.owner,
+        repo=config.repo,
+        job_id=job_id,
+    )
+
+
+async def download_job_log(config: GitHubCIConfig, job_id: str) -> bytes:
+    return await ci_get_bytes(
+        config.token,
+        "/repos/{owner}/{repo}/actions/jobs/{job_id}/logs",
+        owner=config.owner,
+        repo=config.repo,
+        job_id=job_id,
+    )

python/mirage/core/github_ci/stat.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. =========
+
+from mirage.accessor.github_ci import GitHubCIAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.github_ci.readdir import readdir as _readdir
+from mirage.types import FileStat, FileType, PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+VIRTUAL_DIRS = {"workflows", "runs", "jobs", "artifacts"}
+
+
+async def _lookup_with_fallback(
+    accessor: GitHubCIAccessor,
+    virtual_key: str,
+    prefix: str,
+    index: IndexCacheStore,
+):
+    result = await index.get(virtual_key)
+    if result.entry is not None:
+        return result
+    parent_virtual = virtual_key.rsplit("/", 1)[0] or "/"
+    try:
+        await _readdir(
+            accessor,
+            PathSpec(virtual=parent_virtual,
+                     directory=parent_virtual,
+                     resource_path=mount_key(parent_virtual, prefix)),
+            index=index,
+        )
+    # best-effort cache populate; canonical ENOENT raised below
+    except Exception:
+        pass
+    return await index.get(virtual_key)
+
+
+async def stat(
+    accessor: GitHubCIAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> FileStat:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    key = path.resource_path
+
+    if not key:
+        return FileStat(name="/", type=FileType.DIRECTORY)
+
+    parts = key.split("/")
+    virtual_key = prefix + "/" + key
+
+    if len(parts) == 1 and parts[0] in VIRTUAL_DIRS:
+        return FileStat(name=parts[0], type=FileType.DIRECTORY)
+
+    if len(parts) == 2 and parts[0] == "workflows" and parts[1].endswith(
+            ".json"):
+        if index is None:
+            raise enoent(virtual)
+        lookup = await _lookup_with_fallback(accessor, virtual_key, prefix,
+                                             index)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return FileStat(
+            name=lookup.entry.vfs_name or lookup.entry.name,
+            type=FileType.JSON,
+            modified=lookup.entry.remote_time or None,
+            extra={"workflow_id": lookup.entry.id},
+        )
+
+    if len(parts) == 2 and parts[0] == "runs":
+        if index is None:
+            raise enoent(virtual)
+        lookup = await _lookup_with_fallback(accessor, virtual_key, prefix,
+                                             index)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return FileStat(
+            name=lookup.entry.vfs_name or lookup.entry.name,
+            type=FileType.DIRECTORY,
+            modified=lookup.entry.remote_time or None,
+            extra={"run_id": lookup.entry.id},
+        )
+
+    if len(parts) == 3 and parts[0] == "runs" and parts[2] in VIRTUAL_DIRS:
+        return FileStat(name=parts[2], type=FileType.DIRECTORY)
+
+    if len(parts) == 3 and parts[0] == "runs" and parts[2] == "run.json":
+        return FileStat(name="run.json", type=FileType.JSON)
+
+    if (len(parts) == 3 and parts[0] == "runs"
+            and parts[2] == "annotations.jsonl"):
+        return FileStat(name="annotations.jsonl", type=FileType.TEXT)
+
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "jobs"
+            and parts[3].endswith(".json")):
+        if index is None:
+            raise enoent(virtual)
+        lookup = await _lookup_with_fallback(accessor, virtual_key, prefix,
+                                             index)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return FileStat(
+            name=lookup.entry.vfs_name or lookup.entry.name,
+            type=FileType.JSON,
+            modified=lookup.entry.remote_time or None,
+            extra={"job_id": lookup.entry.id},
+        )
+
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "jobs"
+            and parts[3].endswith(".log")):
+        if index is None:
+            raise enoent(virtual)
+        lookup = await _lookup_with_fallback(accessor, virtual_key, prefix,
+                                             index)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return FileStat(
+            name=lookup.entry.vfs_name or lookup.entry.name,
+            type=FileType.TEXT,
+            modified=lookup.entry.remote_time or None,
+            extra={"job_id": lookup.entry.id},
+        )
+
+    if (len(parts) == 4 and parts[0] == "runs" and parts[2] == "artifacts"):
+        if index is None:
+            raise enoent(virtual)
+        lookup = await _lookup_with_fallback(accessor, virtual_key, prefix,
+                                             index)
+        if lookup.entry is None:
+            raise enoent(virtual)
+        return FileStat(
+            name=lookup.entry.vfs_name or lookup.entry.name,
+            type=FileType.ZIP,
+            size=lookup.entry.size,
+            modified=lookup.entry.remote_time or None,
+            extra={"artifact_id": lookup.entry.id},
+        )
+
+    raise enoent(virtual)

python/mirage/core/github_ci/workflows.py

@@ -0,0 +1,36 @@
+# ========= 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.core.github_ci._client import ci_get, ci_get_paginated
+from mirage.resource.github_ci.config import GitHubCIConfig
+
+
+async def list_workflows(config: GitHubCIConfig) -> list[dict]:
+    return await ci_get_paginated(
+        config.token,
+        "/repos/{owner}/{repo}/actions/workflows",
+        list_key="workflows",
+        owner=config.owner,
+        repo=config.repo,
+    )
+
+
+async def get_workflow(config: GitHubCIConfig, workflow_id: str) -> dict:
+    return await ci_get(
+        config.token,
+        "/repos/{owner}/{repo}/actions/workflows/{workflow_id}",
+        owner=config.owner,
+        repo=config.repo,
+        workflow_id=workflow_id,
+    )