generic-ml-wrapper 0.1.0__py3-none-any.whl

generic_ml_wrapper/adapter/outbound/status/cursor_status_parser.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Parse cursor-agent's status-line payload into a ``ClientStatus``."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from generic_ml_wrapper.application.domain.model.client_status import ClientStatus
+from generic_ml_wrapper.application.port.outbound.client_status import ClientStatusParserPort
+
+
+def _dig(payload: object, *keys: str) -> object:
+    current: object = payload
+    for key in keys:
+        if not isinstance(current, dict):
+            return None
+        current = cast("dict[str, object]", current).get(key)
+    return current
+
+
+class CursorStatusParser(ClientStatusParserPort):
+    """Read model and context fill from cursor-agent's status payload.
+
+    cursor-agent pipes a Claude-Code-compatible payload, so ``model.display_name``
+    and ``context_window.used_percentage`` parse just like Claude's. cursor is
+    subscription-metered, so there is no per-session cost on the wire (``None``).
+
+    Its allowance block -- the plan pools (auto/api %) -- is NOT in the status
+    payload; cursor exposes that only via its dashboard API. ``extras`` therefore
+    carries the plan block only if a payload happens to include a ``plan`` table;
+    otherwise it is omitted (the dashboard-API fetch is a separate concern).
+    """
+
+    def parse(self, payload: dict[str, object]) -> ClientStatus:
+        """Parse cursor-agent's status payload.
+
+        Args:
+            payload: The decoded JSON cursor-agent pipes to the status-line command
+                (``model.display_name``, ``context_window.used_percentage``, and --
+                if present -- a ``plan`` table).
+
+        Returns:
+            The parsed status.
+        """
+        return ClientStatus(
+            model=_as_str(_dig(payload, "model", "display_name")),
+            context_pct=_as_pct(_dig(payload, "context_window", "used_percentage")),
+            session_cost_usd=None,
+            extras=_plan_extras(_dig(payload, "plan")),
+        )
+
+
+def _plan_extras(plan: object) -> tuple[str, ...]:
+    """Cursor's plan-pool allowance block, if the payload carries one (auto/api %)."""
+    parts: list[str] = []
+    for label, key in (("auto", "auto_pct"), ("api", "api_pct")):
+        pct = _as_pct(_dig(plan, key))
+        if pct is not None:
+            parts.append(f"{label} {pct}%")
+    return (f"plan {' · '.join(parts)}",) if parts else ()
+
+
+def _as_str(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _as_pct(value: object) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return round(value)

generic_ml_wrapper/adapter/outbound/store/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem persistence adapters."""

generic_ml_wrapper/adapter/outbound/store/filesystem_transcript_store.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem ``TranscriptPort``: the self-contained per-call in/out/usage trio.
+
+Each metered call writes three files under ``<root>/<job>/<session>/``::
+
+    call_001.in.json     the request body forwarded upstream
+    call_001.out.sse     the raw response body
+    call_001.usage.json  tokens, cost, model, and timing
+
+The folder is self-identifying, so it can be copied out and analysed with no
+knowledge of the ledger. ``usage.json`` deliberately duplicates the metering row --
+that is what makes the folder portable.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.application.port.outbound.transcript import TranscriptCall, TranscriptPort
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+
+
+class FilesystemTranscriptStore(TranscriptPort):
+    """Persist each call's in/out/usage trio under a per-session folder."""
+
+    def __init__(self, root: Path) -> None:
+        """Bind the store to its transcript root.
+
+        Args:
+            root: The directory under which ``<job>/<session>/`` folders are written.
+        """
+        self._root = root
+
+    def record(self, call: TranscriptCall) -> None:
+        """Write the call's request, response, and usage as the three trio files."""
+        directory = self._root / call.job / call.session
+        directory.mkdir(parents=True, exist_ok=True)
+        stem = f"call_{call.call_seq:03d}"
+        (directory / f"{stem}.in.json").write_bytes(call.request)
+        (directory / f"{stem}.out.sse").write_bytes(call.response)
+        (directory / f"{stem}.usage.json").write_text(
+            json.dumps(_usage_dict(call.usage), indent=2), encoding="utf-8"
+        )
+
+
+def _usage_dict(usage: TurnUsage | None) -> dict[str, object]:
+    if usage is None:
+        return {}
+    return {
+        "input_tokens": usage.input_tokens,
+        "output_tokens": usage.output_tokens,
+        "cache_creation_tokens": usage.cache_creation_tokens,
+        "cache_read_tokens": usage.cache_read_tokens,
+        "cost_usd": usage.cost_usd,
+        "model": usage.model,
+        "timestamp": usage.timestamp,
+        "duration_s": usage.duration_s,
+        "turn_id": usage.turn_id,
+    }

generic_ml_wrapper/adapter/outbound/store/ledger.py

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The SQLite ledger: the one ``~/.gmlw/ledger.db`` behind the store adapters.
+
+A connection is opened per operation: WAL mode lets concurrent sessions -- and the
+metering relay's threads -- read and write without a shared, thread-bound
+connection, and transactions give crash-consistency for free (no temp-file dance).
+Pre-1.0 the schema is a single create-from-final-state file; a schema change is a
+full store reset (one user, resets freely), so real per-version migrations wait for
+the 1.0 backwards-compatibility promise. See docs/storage-design.md.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from pathlib import Path
+
+SCHEMA_VERSION = 1
+
+_SCHEMA = """
+CREATE TABLE jobs (
+    job        TEXT PRIMARY KEY,
+    kind       TEXT NOT NULL DEFAULT 'work',   -- 'work' | 'authoring'
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE sessions (
+    id         INTEGER PRIMARY KEY,
+    session_id TEXT NOT NULL UNIQUE,           -- <job>_NNN
+    job        TEXT NOT NULL,
+    client     TEXT NOT NULL,
+    uuid       TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX idx_sessions_job ON sessions(job);
+
+CREATE TABLE turns (
+    id                    INTEGER PRIMARY KEY,
+    job                   TEXT NOT NULL,
+    session_id            TEXT NOT NULL,
+    turn_id               TEXT,
+    input_tokens          INTEGER NOT NULL,
+    output_tokens         INTEGER NOT NULL,
+    cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+    cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+    cost_usd              REAL,
+    model                 TEXT,
+    timestamp             REAL NOT NULL DEFAULT 0,
+    duration_s            REAL NOT NULL DEFAULT 0
+);
+CREATE INDEX idx_turns_job ON turns(job);
+
+CREATE TABLE session_costs (
+    session_id TEXT PRIMARY KEY,
+    job        TEXT NOT NULL,
+    cost_usd   REAL NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX idx_session_costs_job ON session_costs(job);
+"""
+
+
+class Ledger:
+    """Owns the SQLite database file and hands out ready-to-use connections."""
+
+    def __init__(self, path: Path) -> None:
+        """Bind the ledger to its database file.
+
+        Args:
+            path: The ``ledger.db`` file (created, with its parent, on first use).
+        """
+        self._path = path
+
+    @contextmanager
+    def connect(self) -> Generator[sqlite3.Connection]:
+        """Yield a WAL connection with the schema ensured, committing on success.
+
+        Yields:
+            An open connection whose row factory is :class:`sqlite3.Row`.
+        """
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        connection = sqlite3.connect(self._path, timeout=5.0)
+        try:
+            connection.row_factory = sqlite3.Row
+            connection.execute("PRAGMA journal_mode=WAL")
+            connection.execute("PRAGMA foreign_keys=ON")
+            _ensure_schema(connection)
+            yield connection
+            connection.commit()
+        finally:
+            connection.close()
+
+
+def _ensure_schema(connection: sqlite3.Connection) -> None:
+    version = int(connection.execute("PRAGMA user_version").fetchone()[0])
+    if version >= SCHEMA_VERSION:
+        return
+    connection.executescript(_SCHEMA)
+    connection.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")

generic_ml_wrapper/adapter/outbound/store/sqlite_per_turn_store.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""SQLite ``PerTurnMeteringPort``: metered turns in the shared ``ledger.db``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.application.domain.model.turn_usage import TurnUsage
+from generic_ml_wrapper.application.port.outbound.per_turn_metering import PerTurnMeteringPort
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.adapter.outbound.store.ledger import Ledger
+
+
+class SqlitePerTurnStore(PerTurnMeteringPort):
+    """Append and read metered turns, keyed by job, in the ledger."""
+
+    def __init__(self, ledger: Ledger) -> None:
+        """Bind the store to the shared SQLite ledger."""
+        self._ledger = ledger
+
+    def record(self, job: str, turn: TurnUsage) -> None:
+        """Append one metered turn for a job."""
+        with self._ledger.connect() as connection:
+            connection.execute(
+                "INSERT INTO turns (job, session_id, turn_id, input_tokens, output_tokens, "
+                "cache_creation_tokens, cache_read_tokens, cost_usd, model, timestamp, duration_s) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    job,
+                    turn.session_id,
+                    turn.turn_id,
+                    turn.input_tokens,
+                    turn.output_tokens,
+                    turn.cache_creation_tokens,
+                    turn.cache_read_tokens,
+                    turn.cost_usd,
+                    turn.model,
+                    turn.timestamp,
+                    turn.duration_s,
+                ),
+            )
+
+    def turns_for_job(self, job: str) -> list[TurnUsage]:
+        """Return every recorded turn for a job, in the order recorded."""
+        with self._ledger.connect() as connection:
+            rows = connection.execute(
+                "SELECT session_id, turn_id, input_tokens, output_tokens, cache_creation_tokens, "
+                "cache_read_tokens, cost_usd, model, timestamp, duration_s "
+                "FROM turns WHERE job = ? ORDER BY id",
+                (job,),
+            ).fetchall()
+        return [
+            TurnUsage(
+                row["session_id"],
+                row["input_tokens"],
+                row["output_tokens"],
+                row["cost_usd"],
+                row["model"],
+                cache_creation_tokens=row["cache_creation_tokens"],
+                cache_read_tokens=row["cache_read_tokens"],
+                timestamp=row["timestamp"],
+                duration_s=row["duration_s"],
+                turn_id=row["turn_id"],
+            )
+            for row in rows
+        ]

generic_ml_wrapper/adapter/outbound/store/sqlite_session_store.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""SQLite ``SessionStorePort``: sessions in the shared ``ledger.db``.
+
+The store is scoped to a ``kind`` (``work`` or ``authoring``): recording tags the
+job with it and :meth:`jobs` filters by it, so authoring sessions stay out of
+``gmlw jobs`` -- the same separation the old parallel filesystem root gave, without
+a second store.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.application.domain.model.session import Session
+from generic_ml_wrapper.application.port.outbound.session_store import SessionStorePort
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.adapter.outbound.store.ledger import Ledger
+
+
+class SqliteSessionStore(SessionStorePort):
+    """Persist and read sessions in the ledger, scoped to a job ``kind``."""
+
+    def __init__(self, ledger: Ledger, kind: str = "work") -> None:
+        """Bind the store to the ledger and the job kind it owns.
+
+        Args:
+            ledger: The shared SQLite ledger.
+            kind: The job kind this store records and lists (``work`` | ``authoring``).
+        """
+        self._ledger = ledger
+        self._kind = kind
+
+    def jobs(self) -> list[str]:
+        """Return the ids of this kind's jobs that have recorded sessions, sorted."""
+        with self._ledger.connect() as connection:
+            rows = connection.execute(
+                "SELECT DISTINCT s.job FROM sessions s JOIN jobs j ON s.job = j.job "
+                "WHERE j.kind = ? ORDER BY s.job",
+                (self._kind,),
+            ).fetchall()
+        return [row["job"] for row in rows]
+
+    def record(self, session: Session) -> None:
+        """Persist a session, creating its job (tagged with this store's kind) if new."""
+        with self._ledger.connect() as connection:
+            connection.execute(
+                "INSERT OR IGNORE INTO jobs (job, kind) VALUES (?, ?)",
+                (session.job, self._kind),
+            )
+            connection.execute(
+                "INSERT INTO sessions (session_id, job, client, uuid) VALUES (?, ?, ?, ?)",
+                (session.session_id, session.job, session.client, session.uuid),
+            )
+
+    def sessions_for_job(self, job: str) -> list[Session]:
+        """Return the sessions recorded for a job, oldest first."""
+        with self._ledger.connect() as connection:
+            rows = connection.execute(
+                "SELECT session_id, job, client, uuid FROM sessions WHERE job = ? ORDER BY id",
+                (job,),
+            ).fetchall()
+        return [Session(row["session_id"], row["job"], row["client"], row["uuid"]) for row in rows]
+
+    def ids_for_job(self, job: str) -> list[str]:
+        """Return the session ids recorded for a job, oldest first."""
+        return [session.session_id for session in self.sessions_for_job(job)]
+
+    def latest_for_job(self, job: str) -> Session | None:
+        """Return the most recently recorded session for a job, or ``None``."""
+        sessions = self.sessions_for_job(job)
+        return sessions[-1] if sessions else None

generic_ml_wrapper/adapter/outbound/store/sqlite_usage_store.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""SQLite ``UsageStorePort``: per-session cumulative cost in the shared ``ledger.db``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from generic_ml_wrapper.application.port.outbound.usage_store import UsageStorePort
+
+if TYPE_CHECKING:
+    from generic_ml_wrapper.adapter.outbound.store.ledger import Ledger
+
+
+class SqliteUsageStore(UsageStorePort):
+    """Persist and read per-session cumulative cost (monotonic) in the ledger.
+
+    Each session owns its own row, so two sessions of one job recording concurrently
+    update different rows -- no read-modify-write of a shared map, no lost update.
+    """
+
+    def __init__(self, ledger: Ledger) -> None:
+        """Bind the store to the shared SQLite ledger."""
+        self._ledger = ledger
+
+    def record_session_cost(self, job: str, session: str, cost_usd: float) -> None:
+        """Record a session's cumulative cost, keeping the highest value seen."""
+        with self._ledger.connect() as connection:
+            connection.execute(
+                "INSERT INTO session_costs (session_id, job, cost_usd) VALUES (?, ?, ?) "
+                "ON CONFLICT(session_id) DO UPDATE SET "
+                "cost_usd = excluded.cost_usd, updated_at = datetime('now') "
+                "WHERE excluded.cost_usd > session_costs.cost_usd",
+                (session, job, cost_usd),
+            )
+
+    def session_costs(self, job: str) -> dict[str, float]:
+        """Return the recorded cost per session for a job."""
+        with self._ledger.connect() as connection:
+            rows = connection.execute(
+                "SELECT session_id, cost_usd FROM session_costs WHERE job = ?",
+                (job,),
+            ).fetchall()
+        return {row["session_id"]: float(row["cost_usd"]) for row in rows}

generic_ml_wrapper/adapter/outbound/workflow/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Workflow source adapters."""

generic_ml_wrapper/adapter/outbound/workflow/filesystem_workflow_source.py

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Filesystem ``WorkflowSourcePort``: workflows under ``~/.gmlw/workflows``."""
+
+from __future__ import annotations
+
+from importlib import resources
+from importlib.resources.abc import Traversable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from generic_ml_wrapper.application.domain.service.interceptor_chain import InterceptorChain
+from generic_ml_wrapper.application.domain.service.rule_cleaner import clean_rule
+from generic_ml_wrapper.application.port.outbound.workflow_source import WorkflowSourcePort
+
+_COMMON = "_common"
+_META = "create-workflow"
+_HIDDEN = frozenset({_COMMON, _META})
+_PROFILE_SUBDIRS = ("me", "company")
+_STRIP_SECTIONS = ("Origin", "Notes")
+
+
+class FilesystemWorkflowSource(WorkflowSourcePort):
+    """Read workflows from ``<root>/<name>/workflow.md``; seed packaged defaults.
+
+    ``compile`` assembles a workflow's operating context from several locations —
+    the shared base, the user's profile, the global and per-workflow rules, and the
+    workflow's steps.
+    """
+
+    def __init__(
+        self,
+        root: Path,
+        profile_root: Path | None = None,
+        rules_root: Path | None = None,
+        interceptors: InterceptorChain | None = None,
+    ) -> None:
+        """Bind the source to its roots.
+
+        Args:
+            root: The directory holding one folder per workflow.
+            profile_root: The user's profile directory, or ``None`` to omit it.
+            rules_root: The global rules directory, or ``None`` to omit it.
+            interceptors: The per-section interceptor chain, or ``None`` for none.
+        """
+        self._root = root
+        self._profile_root = profile_root
+        self._rules_root = rules_root
+        self._interceptors = interceptors or InterceptorChain(())
+
+    def seed(self) -> None:
+        """Copy the packaged default workflows into ``root``, never overwriting."""
+        packaged = resources.files("generic_ml_wrapper").joinpath("resources", "workflows")
+        self._copy_tree(packaged, self._root)
+
+    def _copy_tree(self, source: Traversable, destination: Path) -> None:
+        destination.mkdir(parents=True, exist_ok=True)
+        for entry in source.iterdir():
+            target = destination / entry.name
+            if entry.is_dir():
+                self._copy_tree(entry, target)
+            elif not target.exists():
+                target.write_bytes(entry.read_bytes())
+
+    def names(self) -> list[str]:
+        """Return the runnable workflow names, sorted.
+
+        A runnable workflow is a folder with a ``workflow.md`` that is neither the
+        shared base nor the create-workflow meta-workflow.
+
+        Returns:
+            The runnable workflow names (empty if none exist).
+        """
+        if not self._root.is_dir():
+            return []
+        return sorted(
+            child.name
+            for child in self._root.iterdir()
+            if child.name not in _HIDDEN and (child / "workflow.md").is_file()
+        )
+
+    def exists(self, name: str) -> bool:
+        """Return whether ``<root>/<name>/workflow.md`` exists.
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            ``True`` if the workflow has a ``workflow.md``.
+        """
+        return (self._root / name / "workflow.md").is_file()
+
+    def create(self, name: str) -> str:
+        """Create ``<root>/<name>/`` (and its ``rules/`` folder).
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            The absolute path to the created folder.
+        """
+        folder = self._root / name
+        (folder / "rules").mkdir(parents=True, exist_ok=True)
+        return str(folder)
+
+    def compile(self, name: str) -> str:
+        """Compile a workflow's operating context, in a fixed order.
+
+        The order is: shared base, the user's profile, the global rules, the
+        workflow's own rules, then the workflow's steps. Missing sections are
+        skipped; rules are cleaned (frontmatter and human-only notes dropped). Each
+        section passes through the interceptor chain for its target, and the joined
+        result through the ``context`` target.
+
+        Args:
+            name: The workflow name.
+
+        Returns:
+            The concatenated context (sections that exist, joined by blank lines).
+        """
+        profile = self._interceptors.apply("profile", self._profile())
+        rules = self._interceptors.apply("rules", self._combined_rules(name))
+        workflow = self._interceptors.apply(
+            "workflow", self._read(self._root / name / "workflow.md")
+        )
+        parts = [self._read(self._root / _COMMON / "base.md"), profile, rules, workflow]
+        context = "\n\n\n".join(part for part in parts if part)
+        return self._interceptors.apply("context", context)
+
+    def _combined_rules(self, name: str) -> str:
+        parts = [self._rules(self._rules_root), self._rules(self._root / name / "rules")]
+        return "\n\n\n".join(part for part in parts if part)
+
+    def _profile(self) -> str:
+        if self._profile_root is None:
+            return ""
+        pieces = [self._concat_dir(self._profile_root / subdir) for subdir in _PROFILE_SUBDIRS]
+        return "\n\n".join(piece for piece in pieces if piece)
+
+    def _concat_dir(self, directory: Path) -> str:
+        """Concatenate every ``*.md`` in a profile subfolder, sorted by filename."""
+        if not directory.is_dir():
+            return ""
+        files = [self._read(path) for path in sorted(directory.glob("*.md"))]
+        return "\n\n".join(text for text in files if text)
+
+    def _rules(self, directory: Path | None) -> str:
+        if directory is None or not directory.is_dir():
+            return ""
+        cleaned: list[str] = []
+        for path in sorted(directory.glob("*.rule.md")):
+            raw = path.read_text(encoding="utf-8").strip()
+            if raw and "status: draft" not in raw:
+                rule = clean_rule(raw, _STRIP_SECTIONS)
+                if rule:
+                    cleaned.append(rule)
+        return "\n\n---\n\n".join(cleaned)
+
+    @staticmethod
+    def _read(path: Path) -> str:
+        if not path.is_file():
+            return ""
+        return path.read_text(encoding="utf-8").strip()

generic_ml_wrapper/adapter/outbound/workspace/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Working-environment inspection adapters."""

generic_ml_wrapper/adapter/outbound/workspace/local_workspace_inspector.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""``LocalGitWorkspaceInspector``: read the folder and git state from the cwd."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from generic_ml_wrapper.application.domain.model.workspace import Workspace
+from generic_ml_wrapper.application.port.outbound.workspace import WorkspaceInspectorPort
+
+_GIT_TIMEOUT_SECONDS = 2
+
+
+class LocalGitWorkspaceInspector(WorkspaceInspectorPort):
+    """Inspect the working directory and, when it is a git repository, git state.
+
+    The status-line command runs in the client's working directory, so the folder
+    comes from :func:`Path.cwd` and the git facts from ``git`` invoked there. Git
+    calls are best-effort: any failure (not a repository, git absent, a slow call)
+    leaves that field empty rather than raising.
+    """
+
+    def inspect(self) -> Workspace:
+        """Inspect the current working directory and its git state.
+
+        Returns:
+            The folder (home abbreviated) and git state; git fields are ``None``
+            outside a repository and ``dirty`` is ``0`` when clean or unknown.
+        """
+        branch = _git("branch", "--show-current")
+        if branch is None:
+            return Workspace(folder=_folder(), repo=None, branch=None, short_sha=None, dirty=0)
+        toplevel = _git("rev-parse", "--show-toplevel")
+        porcelain = _git("status", "--porcelain")
+        return Workspace(
+            folder=_folder(),
+            repo=Path(toplevel).name if toplevel else None,
+            branch=branch,
+            short_sha=_git("rev-parse", "--short", "HEAD"),
+            dirty=len(porcelain.splitlines()) if porcelain else 0,
+        )
+
+
+def _folder() -> str | None:
+    try:
+        cwd = Path.cwd()
+    except OSError:
+        return None
+    home = Path.home()
+    if cwd == home:
+        return "~"
+    try:
+        return "~/" + cwd.relative_to(home).as_posix()
+    except ValueError:
+        return str(cwd)
+
+
+def _git(*args: str) -> str | None:
+    try:
+        # Trusted argv: a fixed ``git`` program with our own literal arguments.
+        completed = subprocess.run(  # noqa: S603
+            ["git", *args],  # noqa: S607
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    stripped = completed.stdout.strip()
+    return stripped or None