workspaceguard-cli 0.1.1__tar.gz

workspaceguard_cli-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.venv-freshinstall/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/

workspaceguard_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rudrendu Paul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workspaceguard_cli-0.1.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: workspaceguard-cli
+Version: 0.1.1
+Summary: Per-workspace usage metering and quota caps for shared self-hosted AI assistant deployments (Odysseus and compatible backends).
+Project-URL: Homepage, https://github.com/RudrenduPaul/workspaceguard
+Project-URL: Repository, https://github.com/RudrenduPaul/workspaceguard
+Project-URL: Bug Tracker, https://github.com/RudrenduPaul/workspaceguard/issues
+Project-URL: Changelog, https://github.com/RudrenduPaul/workspaceguard/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/RudrenduPaul/workspaceguard/blob/main/docs/getting-started.md
+Project-URL: Author - Rudrendu Paul, https://github.com/RudrenduPaul
+Project-URL: Author - Sourav Nandy, https://github.com/Sourav-nandy-ai
+Author: Rudrendu Paul, Sourav Nandy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-native,ai-assistant,billing,cli,multi-tenant,odysseus,quota,reverse-proxy,self-hosted,usage-metering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: cryptography<46,>=42
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest<9,>=7.0; extra == 'dev'
+Requires-Dist: twine<7,>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# workspaceguard-cli (Python)
+
+Per-workspace usage metering and quota caps for one shared self-hosted AI
+assistant deployment -- a genuine, independent Python port of the
+[`workspaceguard-cli`](https://github.com/RudrenduPaul/workspaceguard) npm
+package, not a wrapper around a Node binary.
+
+[![PyPI version](https://img.shields.io/pypi/v/workspaceguard-cli.svg)](https://pypi.org/project/workspaceguard-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/RudrenduPaul/workspaceguard/blob/main/LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/workspaceguard-cli.svg)](https://pypi.org/project/workspaceguard-cli/)
+
+## Why this exists
+
+Run [Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) (or a
+compatible self-hosted assistant) for your whole household or small team,
+and there is no way to see who sent how many messages this month, or to
+stop one person's usage from burning through everyone else's API budget.
+WorkspaceGuard is a thin sidecar that adds that layer: per-workspace
+message counts, optional monthly caps that fail closed, and a CLI report
+an admin (or another agent) can read.
+
+This project originally set out to add per-user workspace isolation
+(separate chat history, memory, API keys) to a self-hosted AI chat
+platform. A feasibility spike found that premise was false for the target
+platform's current default configuration: per-user ownership on chat
+history, memory, and API tokens is already enforced by default. Rather
+than ship a competing reimplementation of something the target platform
+already does correctly, this project keeps its tested isolation engine
+(namespace separation, an AES-256-GCM vault with real key rotation,
+fail-closed identity resolution, a self-healing circuit breaker) as the
+identity-resolution substrate, and builds the layer that platform
+genuinely does not have: usage metering and quota enforcement per
+workspace. See the [project README](https://github.com/RudrenduPaul/workspaceguard#readme)
+for the full story.
+
+## Install
+
+```bash
+pip install workspaceguard-cli
+```
+
+**Current status**: this Python port is fully built, tested (32/32 pytest
+tests passing), and packaged -- the wheel and sdist are built and verified,
+installing and running correctly end to end in a fresh virtual environment.
+The first PyPI publish is pending: PyPI's own account-level throttle on
+registering brand-new project names ("429 Too many new projects created")
+is currently blocking the upload, unrelated to any 2FA requirement (this
+account's PyPI publishing needs no human 2FA). It will publish as soon as
+that throttle window clears. Separately, the npm package (`workspaceguard-cli`)
+is built with CI green but not yet published to the npm registry either
+(blocked on a manual 2FA-gated publish step). Neither `pip install
+workspaceguard-cli` nor `npm install -g workspaceguard-cli` is live yet as
+of this writing -- check [PyPI](https://pypi.org/project/workspaceguard-cli/)
+for current availability. This package is a genuine, independent port --
+not a wrapper around the npm package -- so it will work regardless of npm's
+status once it publishes.
+
+## Quickstart
+
+```bash
+# Register the workspaces sharing one deployment (identity = the header
+# value your reverse proxy sets after authenticating, e.g. Cloudflare
+# Access).
+workspaceguard add-workspace alex --identity alex@example.com
+workspaceguard add-workspace jordan --identity jordan@example.com
+
+# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
+workspaceguard set-cap alex 1000
+
+# See usage for every workspace.
+workspaceguard usage
+```
+
+```
+$ workspaceguard usage --json
+{"ok": true, "usage": [{"workspaceId": "alex", "identity": "alex@example.com", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-07", "messageCount": 0, "estimatedBytes": 0}]}
+```
+
+## CLI reference
+
+Every command accepts `--json` for a structured, agent-native output shape
+instead of the human-readable text shown below. Identical command surface
+to the npm CLI.
+
+| Command | What it does |
+| --- | --- |
+| `workspaceguard init` | Initializes the data directory and vault for this deployment. |
+| `workspaceguard add-workspace <id> --identity <value>` | Registers a workspace, idempotent on repeat calls for the same id. |
+| `workspaceguard status [--json]` | Lists configured workspaces. |
+| `workspaceguard usage [--json]` | Per-workspace message count, cap, and percent-used for the current month. |
+| `workspaceguard set-cap <id> <count\|none>` | Sets or clears a workspace's monthly message cap. |
+| `workspaceguard rotate-key <id>` | Rotates a workspace's vault encryption key (invalidates the old ciphertext). |
+| `workspaceguard scan [--json]` | Isolation config scan (scaffold stub, carried over from the original build). |
+
+## Library API
+
+```python
+import asyncio
+from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError
+
+async def main():
+    guard = await create_workspace_guard(data_dir="./data", backend=MockAdapter())
+    await guard.add_workspace("alex", "alex@example.com")
+    await guard.set_cap("alex", 1000)
+
+    try:
+        await guard.chat("alex@example.com", "hello")
+    except QuotaExceededError:
+        pass  # alex is over their monthly cap
+
+    report = await guard.usage_report()
+
+asyncio.run(main())
+```
+
+The library API is async (`asyncio`), matching the async architecture of
+the original TypeScript source rather than flattening it to synchronous
+calls.
+
+## How it works
+
+```
+target: an inbound chat request with an identity header value
+   -> resolve_workspace() -- fail closed on any miss, never a default workspace
+   -> check_quota() -- QuotaExceededError if the workspace is at its cap
+   -> circuit breaker -- calls the BackendAdapter, opens after 3 consecutive
+      failures, self-heals via a half-open probe after a cooldown
+   -> record usage -- per-workspace, per-month counters with automatic
+      period rollover
+```
+
+- `workspaceguard/isolation_guard.py` -- the single choke point (`chat()`)
+  every request flows through: resolve workspace -> check quota -> call
+  backend -> record usage.
+- `workspaceguard/usage.py` -- the usage-metering engine this project adds:
+  per-workspace, per-month counters with automatic period rollover, and
+  `QuotaExceededError` enforcement.
+- `workspaceguard/vault.py`, `workspaceguard/namespace.py`,
+  `workspaceguard/circuit_breaker.py` -- the original isolation-engine
+  code, kept as the identity/workspace-boundary substrate the metering
+  layer reads from, not shipped as a competing isolation product.
+- `workspaceguard/adapters/` -- `BackendAdapter` abstract base class; a
+  real Odysseus HTTP adapter is the next step (currently `MockAdapter`
+  only, same as the TypeScript original).
+
+Backend-specific behavior never enters the core modules directly --
+everything goes through `BackendAdapter`.
+
+## Trust boundary
+
+WorkspaceGuard trusts an upstream identity header (default:
+`Cf-Access-Authenticated-User-Email`) to resolve the workspace. It must
+never be directly reachable from the network -- only from behind whatever
+trusted proxy sets that header (Cloudflare Access, Tailscale, etc.). This
+is documented, not code-enforced.
+
+## What's real vs. not yet built
+
+- Real, tested (28/28 pytest tests passing): usage metering, quota
+  enforcement, the original isolation engine (vault, namespace separation,
+  circuit breaker), CLI with `--json` mode.
+- Not yet built: a real Odysseus HTTP adapter (only `MockAdapter` exists so
+  far, same as the TypeScript original), a hosted managed billing
+  dashboard (deliberately out of scope for this MIT project).
+
+## Security
+
+The vault uses AES-256-GCM (via the `cryptography` package) with one
+derived key per workspace per generation -- rotating a workspace's key
+increments its generation, so old ciphertext genuinely can no longer be
+decrypted, not a no-op. See
+[SECURITY.md](https://github.com/RudrenduPaul/workspaceguard/blob/main/SECURITY.md)
+for the disclosure process and what's in/out of scope.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/RudrenduPaul/workspaceguard/blob/main/CONTRIBUTING.md).
+
+```bash
+cd python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/RudrenduPaul/workspaceguard/blob/main/LICENSE).

workspaceguard_cli-0.1.1/README.md

@@ -0,0 +1,188 @@
+# workspaceguard-cli (Python)
+
+Per-workspace usage metering and quota caps for one shared self-hosted AI
+assistant deployment -- a genuine, independent Python port of the
+[`workspaceguard-cli`](https://github.com/RudrenduPaul/workspaceguard) npm
+package, not a wrapper around a Node binary.
+
+[![PyPI version](https://img.shields.io/pypi/v/workspaceguard-cli.svg)](https://pypi.org/project/workspaceguard-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/RudrenduPaul/workspaceguard/blob/main/LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/workspaceguard-cli.svg)](https://pypi.org/project/workspaceguard-cli/)
+
+## Why this exists
+
+Run [Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) (or a
+compatible self-hosted assistant) for your whole household or small team,
+and there is no way to see who sent how many messages this month, or to
+stop one person's usage from burning through everyone else's API budget.
+WorkspaceGuard is a thin sidecar that adds that layer: per-workspace
+message counts, optional monthly caps that fail closed, and a CLI report
+an admin (or another agent) can read.
+
+This project originally set out to add per-user workspace isolation
+(separate chat history, memory, API keys) to a self-hosted AI chat
+platform. A feasibility spike found that premise was false for the target
+platform's current default configuration: per-user ownership on chat
+history, memory, and API tokens is already enforced by default. Rather
+than ship a competing reimplementation of something the target platform
+already does correctly, this project keeps its tested isolation engine
+(namespace separation, an AES-256-GCM vault with real key rotation,
+fail-closed identity resolution, a self-healing circuit breaker) as the
+identity-resolution substrate, and builds the layer that platform
+genuinely does not have: usage metering and quota enforcement per
+workspace. See the [project README](https://github.com/RudrenduPaul/workspaceguard#readme)
+for the full story.
+
+## Install
+
+```bash
+pip install workspaceguard-cli
+```
+
+**Current status**: this Python port is fully built, tested (32/32 pytest
+tests passing), and packaged -- the wheel and sdist are built and verified,
+installing and running correctly end to end in a fresh virtual environment.
+The first PyPI publish is pending: PyPI's own account-level throttle on
+registering brand-new project names ("429 Too many new projects created")
+is currently blocking the upload, unrelated to any 2FA requirement (this
+account's PyPI publishing needs no human 2FA). It will publish as soon as
+that throttle window clears. Separately, the npm package (`workspaceguard-cli`)
+is built with CI green but not yet published to the npm registry either
+(blocked on a manual 2FA-gated publish step). Neither `pip install
+workspaceguard-cli` nor `npm install -g workspaceguard-cli` is live yet as
+of this writing -- check [PyPI](https://pypi.org/project/workspaceguard-cli/)
+for current availability. This package is a genuine, independent port --
+not a wrapper around the npm package -- so it will work regardless of npm's
+status once it publishes.
+
+## Quickstart
+
+```bash
+# Register the workspaces sharing one deployment (identity = the header
+# value your reverse proxy sets after authenticating, e.g. Cloudflare
+# Access).
+workspaceguard add-workspace alex --identity alex@example.com
+workspaceguard add-workspace jordan --identity jordan@example.com
+
+# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
+workspaceguard set-cap alex 1000
+
+# See usage for every workspace.
+workspaceguard usage
+```
+
+```
+$ workspaceguard usage --json
+{"ok": true, "usage": [{"workspaceId": "alex", "identity": "alex@example.com", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-07", "messageCount": 0, "estimatedBytes": 0}]}
+```
+
+## CLI reference
+
+Every command accepts `--json` for a structured, agent-native output shape
+instead of the human-readable text shown below. Identical command surface
+to the npm CLI.
+
+| Command | What it does |
+| --- | --- |
+| `workspaceguard init` | Initializes the data directory and vault for this deployment. |
+| `workspaceguard add-workspace <id> --identity <value>` | Registers a workspace, idempotent on repeat calls for the same id. |
+| `workspaceguard status [--json]` | Lists configured workspaces. |
+| `workspaceguard usage [--json]` | Per-workspace message count, cap, and percent-used for the current month. |
+| `workspaceguard set-cap <id> <count\|none>` | Sets or clears a workspace's monthly message cap. |
+| `workspaceguard rotate-key <id>` | Rotates a workspace's vault encryption key (invalidates the old ciphertext). |
+| `workspaceguard scan [--json]` | Isolation config scan (scaffold stub, carried over from the original build). |
+
+## Library API
+
+```python
+import asyncio
+from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError
+
+async def main():
+    guard = await create_workspace_guard(data_dir="./data", backend=MockAdapter())
+    await guard.add_workspace("alex", "alex@example.com")
+    await guard.set_cap("alex", 1000)
+
+    try:
+        await guard.chat("alex@example.com", "hello")
+    except QuotaExceededError:
+        pass  # alex is over their monthly cap
+
+    report = await guard.usage_report()
+
+asyncio.run(main())
+```
+
+The library API is async (`asyncio`), matching the async architecture of
+the original TypeScript source rather than flattening it to synchronous
+calls.
+
+## How it works
+
+```
+target: an inbound chat request with an identity header value
+   -> resolve_workspace() -- fail closed on any miss, never a default workspace
+   -> check_quota() -- QuotaExceededError if the workspace is at its cap
+   -> circuit breaker -- calls the BackendAdapter, opens after 3 consecutive
+      failures, self-heals via a half-open probe after a cooldown
+   -> record usage -- per-workspace, per-month counters with automatic
+      period rollover
+```
+
+- `workspaceguard/isolation_guard.py` -- the single choke point (`chat()`)
+  every request flows through: resolve workspace -> check quota -> call
+  backend -> record usage.
+- `workspaceguard/usage.py` -- the usage-metering engine this project adds:
+  per-workspace, per-month counters with automatic period rollover, and
+  `QuotaExceededError` enforcement.
+- `workspaceguard/vault.py`, `workspaceguard/namespace.py`,
+  `workspaceguard/circuit_breaker.py` -- the original isolation-engine
+  code, kept as the identity/workspace-boundary substrate the metering
+  layer reads from, not shipped as a competing isolation product.
+- `workspaceguard/adapters/` -- `BackendAdapter` abstract base class; a
+  real Odysseus HTTP adapter is the next step (currently `MockAdapter`
+  only, same as the TypeScript original).
+
+Backend-specific behavior never enters the core modules directly --
+everything goes through `BackendAdapter`.
+
+## Trust boundary
+
+WorkspaceGuard trusts an upstream identity header (default:
+`Cf-Access-Authenticated-User-Email`) to resolve the workspace. It must
+never be directly reachable from the network -- only from behind whatever
+trusted proxy sets that header (Cloudflare Access, Tailscale, etc.). This
+is documented, not code-enforced.
+
+## What's real vs. not yet built
+
+- Real, tested (28/28 pytest tests passing): usage metering, quota
+  enforcement, the original isolation engine (vault, namespace separation,
+  circuit breaker), CLI with `--json` mode.
+- Not yet built: a real Odysseus HTTP adapter (only `MockAdapter` exists so
+  far, same as the TypeScript original), a hosted managed billing
+  dashboard (deliberately out of scope for this MIT project).
+
+## Security
+
+The vault uses AES-256-GCM (via the `cryptography` package) with one
+derived key per workspace per generation -- rotating a workspace's key
+increments its generation, so old ciphertext genuinely can no longer be
+decrypted, not a no-op. See
+[SECURITY.md](https://github.com/RudrenduPaul/workspaceguard/blob/main/SECURITY.md)
+for the disclosure process and what's in/out of scope.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/RudrenduPaul/workspaceguard/blob/main/CONTRIBUTING.md).
+
+```bash
+cd python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/RudrenduPaul/workspaceguard/blob/main/LICENSE).

workspaceguard_cli-0.1.1/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "workspaceguard-cli"
+version = "0.1.1"
+description = "Per-workspace usage metering and quota caps for shared self-hosted AI assistant deployments (Odysseus and compatible backends)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Rudrendu Paul" },
+  { name = "Sourav Nandy" },
+]
+keywords = ["self-hosted", "ai-assistant", "usage-metering", "quota", "billing", "multi-tenant", "reverse-proxy", "odysseus", "cli", "agent-native"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+  "PyYAML>=6.0,<7",
+  "cryptography>=42,<46",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0,<9",
+  "pytest-asyncio>=0.23,<1",
+  "build>=1.0,<2",
+  "twine>=5.0,<7",
+]
+
+[project.urls]
+Homepage = "https://github.com/RudrenduPaul/workspaceguard"
+Repository = "https://github.com/RudrenduPaul/workspaceguard"
+"Bug Tracker" = "https://github.com/RudrenduPaul/workspaceguard/issues"
+Changelog = "https://github.com/RudrenduPaul/workspaceguard/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/RudrenduPaul/workspaceguard/blob/main/docs/getting-started.md"
+"Author - Rudrendu Paul" = "https://github.com/RudrenduPaul"
+"Author - Sourav Nandy" = "https://github.com/Sourav-nandy-ai"
+
+[project.scripts]
+workspaceguard = "workspaceguard.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/workspaceguard"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/workspaceguard",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

workspaceguard_cli-0.1.1/src/workspaceguard/__init__.py

@@ -0,0 +1,78 @@
+"""
+Programmatic / agent-native entry point.
+
+    from workspaceguard import create_workspace_guard, MockAdapter
+
+    guard = await create_workspace_guard(data_dir="./data", backend=MockAdapter())
+    await guard.add_workspace("alex", "alex@example.com")
+    await guard.set_cap("alex", 1000)
+    report = await guard.usage_report()
+
+Same core isolation/metering logic as the `workspaceguard` CLI;
+workspaceguard/cli.py is a thin argument-parsing wrapper over this class.
+
+This is the Python port of the workspaceguard-cli npm package
+(https://www.npmjs.com/package/workspaceguard-cli, not yet published as of
+this port -- see README for current npm status). See
+https://github.com/RudrenduPaul/workspaceguard for the canonical
+documentation and the original TypeScript source.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .adapters.mock import MockAdapter
+from .config import DuplicateIdentityError, InvalidWorkspaceIdError
+from .isolation_guard import IsolationGuard, WorkspaceUsageReport
+from .types import (
+    BackendAdapter,
+    BackendCircuitOpenError,
+    BackendUnreachableError,
+    IdentityNotFoundError,
+    VaultDecryptionError,
+    WorkspaceNotFoundError,
+)
+from .usage import QuotaExceededError, WorkspaceUsage
+
+__version__ = "0.1.1"
+
+
+async def create_workspace_guard(
+    data_dir: str,
+    backend: BackendAdapter,
+    circuit_open_cooldown_ms: Optional[int] = None,
+) -> IsolationGuard:
+    """
+    The library entry point -- the "agent-native" surface. An orchestrator
+    process can call this directly instead of shelling out to the CLI. No
+    default backend -- a caller must be explicit about which adapter it
+    wants (the real Odysseus adapter ships once the feasibility spike
+    confirms clean HTTP interception; MockAdapter is exported for tests and
+    local experimentation).
+    """
+    guard = IsolationGuard(
+        data_dir=data_dir,
+        backend=backend,
+        circuit_open_cooldown_ms=circuit_open_cooldown_ms,
+    )
+    await guard.init()
+    return guard
+
+
+__all__ = [
+    "create_workspace_guard",
+    "IsolationGuard",
+    "WorkspaceUsageReport",
+    "BackendAdapter",
+    "MockAdapter",
+    "IdentityNotFoundError",
+    "VaultDecryptionError",
+    "BackendUnreachableError",
+    "BackendCircuitOpenError",
+    "WorkspaceNotFoundError",
+    "DuplicateIdentityError",
+    "InvalidWorkspaceIdError",
+    "QuotaExceededError",
+    "WorkspaceUsage",
+    "__version__",
+]

workspaceguard_cli-0.1.1/src/workspaceguard/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .mock import MockAdapter
+
+__all__ = ["MockAdapter"]

workspaceguard_cli-0.1.1/src/workspaceguard/adapters/mock.py

@@ -0,0 +1,39 @@
+"""
+In-memory mock backend, used for the scaffold-stage isolation tests only.
+Ported from src/adapters/mock.ts. The real Odysseus adapter is blocked on a
+feasibility spike: does Odysseus's HTTP API expose clean interception
+points, or does it read/write some of this directly from disk/DB in a way
+an HTTP-level proxy can't see? See docs/integrations/backends.md.
+"""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from ..types import BackendAdapter
+
+
+class MockAdapter(BackendAdapter):
+    name = "mock"
+
+    def __init__(self) -> None:
+        self._messages_by_workspace: Dict[str, List[str]] = {}
+        self._failures_remaining = 0
+
+    async def health_check(self) -> bool:
+        return True
+
+    async def forward_chat(self, workspace_id: str, message: str) -> str:
+        if self._failures_remaining > 0:
+            self._failures_remaining -= 1
+            raise RuntimeError("simulated backend failure")
+        existing = self._messages_by_workspace.setdefault(workspace_id, [])
+        existing.append(message)
+        return f"echo: {message}"
+
+    def _fail_next_calls(self, n: int) -> None:
+        """Test-only: makes the next N forward_chat calls fail, to exercise the circuit breaker."""
+        self._failures_remaining = n
+
+    def _messages_for(self, workspace_id: str) -> List[str]:
+        """Test-only inspection point -- never exposed through the public adapter interface."""
+        return self._messages_by_workspace.get(workspace_id, [])