kosa8 0.1.0__tar.gz

kosa8-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 kosa8
+
+This license covers the source code in this repository (the kosa8
+TypeScript SDK packages, @kosa8/sdk and @kosa8/ai-sdk-sandbox) only. It does
+not cover kosa8 itself (the kosa8 CLI, the kosa8d daemon or any other kosa8
+software), which is licensed separately.
+
+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.

kosa8-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: kosa8
+Version: 0.1.0
+Summary: Python client for the kosa8 native API: microVM sandboxes for AI agents, with checkpoint, rewind, fork and explore.
+License: MIT
+Project-URL: Homepage, https://kosa8.com
+Project-URL: Documentation, https://docs.kosa8.com
+Project-URL: Source, https://github.com/kosa8ai/kosa8-py
+Keywords: kosa8,sandbox,microvm,ai-agents,security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# kosa8 for Python
+
+Python client for [kosa8](https://kosa8.com): microVM sandboxes for AI agents, with
+checkpoint, rewind, fork and explore. The counterpart of
+[`@kosa8/sdk`](https://www.npmjs.com/package/@kosa8/sdk), method for method.
+
+No dependencies. It talks to the local kosa8 daemon over its unix socket, or to a
+remote kosa8 worker.
+
+```sh
+pip install kosa8
+```
+
+## Quickstart
+
+```python
+from kosa8 import Kosa8Client
+
+k = Kosa8Client()
+k.create_sandbox(name="demo", egress="deny")   # a microVM with its own kernel, no network
+sb = k.sandbox("demo")
+
+sb.pull("alpine:latest")
+print(sb.run("alpine:latest", ["sh", "-c", "echo hello"]).stdout)
+
+sb.checkpoint(label="before the risky bit")    # memory, processes and disk
+sb.run("alpine:latest", ["sh", "-c", "rm -rf /data"])
+sb.rewind()                                    # back, processes resumed
+
+forks = sb.fork(4)                             # four live copies
+sb.delete()
+```
+
+## What's in it
+
+| Area | Methods |
+|---|---|
+| Status | `health`, `version` |
+| Sandboxes | `create_sandbox`, `list_sandboxes`, `get_sandbox`, `start_sandbox`, `stop_sandbox`, `delete_sandbox` |
+| Images | `pull`, `pull_into_sandbox`, `sandbox_images` |
+| Running code | `run`, `exec`, `exec_frames`, `start_container`, `start_interactive`, `write_stdin`, `attach` |
+| Network | `sandbox_egress`; `egress="deny" \| "any" \| "fakenet"` or `egress_allow=[...]` on create |
+| Snapshots | `snapshot`, `list_snapshots`, `restore_snapshot`, `delete_snapshot` |
+| Fork | `fork(sandbox, n)`, `explore(sandbox, variants)` (best-of-N) |
+| Checkpoints | `checkpoint`, `list_checkpoints`, `rewind` |
+
+`k.sandbox(id)` returns a handle with the same methods bound to one sandbox.
+
+Checkpoints share the CLI's store (`~/.kosa8/checkpoints.json`, under the same
+`flock`), so `kosa8 rewind` sees checkpoints taken here and the other way round.
+
+## Connecting
+
+| Setting | Default |
+|---|---|
+| `socket_path=` | `~/.kosa8/run/kosa8.sock` |
+| `host=` / `KOSA8_HOST` | a remote worker: `https://…`, `tcp://host:port`, `unix:///path` |
+| `token=` / `KOSA8_TOKEN` | the worker's bearer token |
+| `insecure=` / `KOSA8_INSECURE=1` | allow plain http to a non-loopback host (off) |
+| `actor=` | `tool`; recorded in the audit log as `human`, `agent` or `tool` |
+| `agent_token=` / `KOSA8_AGENT_TOKEN` | agent identity for the audit log |
+| `timeout=` | seconds per connect and read; `None` waits |
+
+## Errors
+
+Every daemon error is raised as a typed exception carrying the daemon's own
+message and remediation: `Kosa8BadRequestError` (400), `Kosa8AuthError` (401),
+`Kosa8PolicyError` (403), `Kosa8ApprovalRequiredError` (403 needing a signed
+approval: repeat the call with `approval=<id>`), `Kosa8NotFoundError` (404),
+`Kosa8ConflictError` (409), `Kosa8UnsupportedError` (501),
+`Kosa8ConnectionError`, `Kosa8StreamError` (output kept), `Kosa8TimeoutError`.
+
+## Tests
+
+```sh
+PYTHONPATH=src:tests python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT

kosa8-0.1.0/README.md

@@ -0,0 +1,81 @@
+# kosa8 for Python
+
+Python client for [kosa8](https://kosa8.com): microVM sandboxes for AI agents, with
+checkpoint, rewind, fork and explore. The counterpart of
+[`@kosa8/sdk`](https://www.npmjs.com/package/@kosa8/sdk), method for method.
+
+No dependencies. It talks to the local kosa8 daemon over its unix socket, or to a
+remote kosa8 worker.
+
+```sh
+pip install kosa8
+```
+
+## Quickstart
+
+```python
+from kosa8 import Kosa8Client
+
+k = Kosa8Client()
+k.create_sandbox(name="demo", egress="deny")   # a microVM with its own kernel, no network
+sb = k.sandbox("demo")
+
+sb.pull("alpine:latest")
+print(sb.run("alpine:latest", ["sh", "-c", "echo hello"]).stdout)
+
+sb.checkpoint(label="before the risky bit")    # memory, processes and disk
+sb.run("alpine:latest", ["sh", "-c", "rm -rf /data"])
+sb.rewind()                                    # back, processes resumed
+
+forks = sb.fork(4)                             # four live copies
+sb.delete()
+```
+
+## What's in it
+
+| Area | Methods |
+|---|---|
+| Status | `health`, `version` |
+| Sandboxes | `create_sandbox`, `list_sandboxes`, `get_sandbox`, `start_sandbox`, `stop_sandbox`, `delete_sandbox` |
+| Images | `pull`, `pull_into_sandbox`, `sandbox_images` |
+| Running code | `run`, `exec`, `exec_frames`, `start_container`, `start_interactive`, `write_stdin`, `attach` |
+| Network | `sandbox_egress`; `egress="deny" \| "any" \| "fakenet"` or `egress_allow=[...]` on create |
+| Snapshots | `snapshot`, `list_snapshots`, `restore_snapshot`, `delete_snapshot` |
+| Fork | `fork(sandbox, n)`, `explore(sandbox, variants)` (best-of-N) |
+| Checkpoints | `checkpoint`, `list_checkpoints`, `rewind` |
+
+`k.sandbox(id)` returns a handle with the same methods bound to one sandbox.
+
+Checkpoints share the CLI's store (`~/.kosa8/checkpoints.json`, under the same
+`flock`), so `kosa8 rewind` sees checkpoints taken here and the other way round.
+
+## Connecting
+
+| Setting | Default |
+|---|---|
+| `socket_path=` | `~/.kosa8/run/kosa8.sock` |
+| `host=` / `KOSA8_HOST` | a remote worker: `https://…`, `tcp://host:port`, `unix:///path` |
+| `token=` / `KOSA8_TOKEN` | the worker's bearer token |
+| `insecure=` / `KOSA8_INSECURE=1` | allow plain http to a non-loopback host (off) |
+| `actor=` | `tool`; recorded in the audit log as `human`, `agent` or `tool` |
+| `agent_token=` / `KOSA8_AGENT_TOKEN` | agent identity for the audit log |
+| `timeout=` | seconds per connect and read; `None` waits |
+
+## Errors
+
+Every daemon error is raised as a typed exception carrying the daemon's own
+message and remediation: `Kosa8BadRequestError` (400), `Kosa8AuthError` (401),
+`Kosa8PolicyError` (403), `Kosa8ApprovalRequiredError` (403 needing a signed
+approval: repeat the call with `approval=<id>`), `Kosa8NotFoundError` (404),
+`Kosa8ConflictError` (409), `Kosa8UnsupportedError` (501),
+`Kosa8ConnectionError`, `Kosa8StreamError` (output kept), `Kosa8TimeoutError`.
+
+## Tests
+
+```sh
+PYTHONPATH=src:tests python3 -m unittest discover -s tests
+```
+
+## License
+
+MIT

kosa8-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kosa8"
+version = "0.1.0"
+description = "Python client for the kosa8 native API: microVM sandboxes for AI agents, with checkpoint, rewind, fork and explore."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["kosa8", "sandbox", "microvm", "ai-agents", "security"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://kosa8.com"
+Documentation = "https://docs.kosa8.com"
+Source = "https://github.com/kosa8ai/kosa8-py"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kosa8 = ["py.typed"]

kosa8-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kosa8-0.1.0/src/kosa8/__init__.py

@@ -0,0 +1,69 @@
+"""kosa8: microVM sandboxes for AI agents, with checkpoint, rewind, fork and explore.
+
+The Python counterpart of ``@kosa8/sdk``. No dependencies: it speaks HTTP to the
+local kosa8 daemon over its unix socket, or to a remote worker (``KOSA8_HOST``).
+
+>>> from kosa8 import Kosa8Client
+>>> k = Kosa8Client()
+>>> sb = k.sandbox(k.create_sandbox(name="demo", egress="deny")["sandbox"]["id"])
+>>> sb.pull("alpine:latest")
+>>> sb.run("alpine:latest", ["echo", "hi"]).stdout
+'hi\\n'
+"""
+
+from .checkpoints import (
+    MAX_CHECKPOINTS_PER_SANDBOX,
+    CheckpointBook,
+    FileCheckpointStore,
+    MemoryCheckpointStore,
+)
+from .client import ExecResult, ExploreBranch, ExploreResult, Kosa8Client, Sandbox
+from .errors import (
+    Kosa8ApiError,
+    Kosa8ApprovalRequiredError,
+    Kosa8AuthError,
+    Kosa8BadRequestError,
+    Kosa8CheckpointError,
+    Kosa8ConflictError,
+    Kosa8ConnectionError,
+    Kosa8Error,
+    Kosa8NotFoundError,
+    Kosa8PolicyError,
+    Kosa8StreamError,
+    Kosa8TimeoutError,
+    Kosa8UnsupportedError,
+    error_from_response,
+)
+from .transport import Transport, default_socket_path, resolve_endpoint
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Kosa8Client",
+    "Sandbox",
+    "ExecResult",
+    "ExploreBranch",
+    "ExploreResult",
+    "Transport",
+    "default_socket_path",
+    "resolve_endpoint",
+    "CheckpointBook",
+    "FileCheckpointStore",
+    "MemoryCheckpointStore",
+    "MAX_CHECKPOINTS_PER_SANDBOX",
+    "Kosa8Error",
+    "Kosa8ConnectionError",
+    "Kosa8ApiError",
+    "Kosa8BadRequestError",
+    "Kosa8AuthError",
+    "Kosa8PolicyError",
+    "Kosa8ApprovalRequiredError",
+    "Kosa8NotFoundError",
+    "Kosa8ConflictError",
+    "Kosa8UnsupportedError",
+    "Kosa8StreamError",
+    "Kosa8CheckpointError",
+    "Kosa8TimeoutError",
+    "error_from_response",
+    "__version__",
+]

kosa8-0.1.0/src/kosa8/checkpoints.py

@@ -0,0 +1,195 @@
+"""Checkpoints: client-side bookkeeping over daemon snapshots, exactly as pkg/checkpoint.
+
+A checkpoint is a snapshot with the id ``<sandbox>-ckpt-<n>``; an ordered stack
+of them per sandbox records labels and order. The daemon has no checkpoint
+endpoint. The default store is the CLI's own ``~/.kosa8/checkpoints.json``,
+locked with the same ``flock`` on ``checkpoints.json.lock`` the Go tools take,
+so checkpoints taken here are seen by ``kosa8 rewind`` and the other way round.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import threading
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
+
+from .errors import Kosa8CheckpointError
+
+#: How many checkpoints are kept per sandbox; the oldest is evicted (pkg/checkpoint MaxPerSandbox).
+MAX_CHECKPOINTS_PER_SANDBOX = 10
+
+T = TypeVar("T")
+StoreData = Dict[str, List[Dict[str, Any]]]
+
+
+def validate_sandbox_name(name: str) -> None:
+    """Reject a name that could escape the store (pkg/checkpoint validSandbox)."""
+    if name in ("", ".", "..") or "/" in name or "\\" in name or name.startswith("."):
+        raise Kosa8CheckpointError(f"invalid sandbox name {json.dumps(name)}")
+
+
+class MemoryCheckpointStore:
+    """Keeps stacks in memory only; nothing is shared with the kosa8 CLI."""
+
+    def __init__(self) -> None:
+        self._data: StoreData = {}
+        self._mu = threading.Lock()
+
+    def load(self) -> StoreData:
+        with self._mu:
+            return copy.deepcopy(self._data)
+
+    def update(self, fn: Callable[[StoreData], T]) -> T:
+        with self._mu:
+            data = copy.deepcopy(self._data)
+            out = fn(data)
+            self._data = data
+            return out
+
+
+class FileCheckpointStore:
+    """The store the kosa8 CLI, MCP server and desk use (mode 0600, rewritten atomically)."""
+
+    def __init__(self, path: Optional[str] = None) -> None:
+        self.path = path or os.path.join(os.path.expanduser("~"), ".kosa8", "checkpoints.json")
+        self._mu = threading.Lock()
+
+    def load(self) -> StoreData:
+        try:
+            with open(self.path, "r", encoding="utf-8") as f:
+                raw = f.read()
+        except FileNotFoundError:
+            return {}
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            return {}  # a corrupt store must not make the sandbox unusable (as pkg/checkpoint)
+        return parsed if isinstance(parsed, dict) else {}
+
+    def update(self, fn: Callable[[StoreData], T]) -> T:
+        os.makedirs(os.path.dirname(self.path), mode=0o700, exist_ok=True)
+        with self._mu:
+            fd = os.open(self.path + ".lock", os.O_RDWR | os.O_CREAT, 0o600)
+            try:
+                try:
+                    import fcntl
+
+                    fcntl.flock(fd, fcntl.LOCK_EX)
+                except ImportError:  # Windows: in-process lock only, as pkg/checkpoint lock_other.go
+                    pass
+                data = self.load()
+                out = fn(data)
+                tmp = self.path + ".tmp"
+                with open(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600), "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+                os.replace(tmp, self.path)
+                return out
+            finally:
+                os.close(fd)  # closing drops the flock
+
+
+def _seq_of(cid: str, sandbox: str) -> int:
+    pre = sandbox + "-ckpt-"
+    if not cid.startswith(pre):
+        return 0
+    m = re.match(r"^(\d+)", cid[len(pre):])
+    return int(m.group(1)) if m else 0
+
+
+_FRAC = re.compile(r"\.(\d+)")
+
+
+def _ts(c: Dict[str, Any]) -> float:
+    # Go writes RFC 3339 with up to nine fractional digits; Python before 3.11
+    # takes exactly six and no "Z", so normalise both before parsing.
+    s = (c.get("created") or "").replace("Z", "+00:00")
+    s = _FRAC.sub(lambda m: "." + (m.group(1) + "000000")[:6], s, count=1)
+    try:
+        return datetime.fromisoformat(s).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def _sorted(lst: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    return [c for _, _, c in sorted(((_ts(c), i, c) for i, c in enumerate(lst)), key=lambda x: (x[0], x[1]))]
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+class CheckpointBook:
+    """The stack logic of pkg/checkpoint, over any store."""
+
+    def __init__(self, store: Any) -> None:
+        self.store = store
+
+    def next_id(self, sandbox: str) -> Tuple[str, List[str]]:
+        """The snapshot id the next checkpoint should use, and ids to evict to stay under the cap."""
+        validate_sandbox_name(sandbox)
+        lst = self.store.load().get(sandbox, [])
+        n = len(lst) + 1
+        for c in lst:
+            v = _seq_of(c.get("id", ""), sandbox)
+            if v >= n:
+                n = v + 1
+        over = len(lst) + 1 - MAX_CHECKPOINTS_PER_SANDBOX
+        evict = [c["id"] for c in lst[:over]] if over > 0 else []
+        return f"{sandbox}-ckpt-{n}", evict
+
+    def record(self, cid: str, sandbox: str, label: str = "", evicted: Optional[List[str]] = None) -> Dict[str, Any]:
+        validate_sandbox_name(sandbox)
+        rec = {"id": cid, "sandbox": sandbox, "label": label or "", "created": _now()}
+        drop = set(evicted or [])
+
+        def fn(s: StoreData) -> None:
+            s[sandbox] = [e for e in s.get(sandbox, []) if e.get("id") not in drop] + [rec]
+
+        self.store.update(fn)
+        return rec
+
+    def list(self, sandbox: str) -> List[Dict[str, Any]]:
+        return _sorted(list(self.store.load().get(sandbox, [])))
+
+    def latest(self, sandbox: str) -> Dict[str, Any]:
+        lst = self.list(sandbox)
+        if not lst:
+            raise Kosa8CheckpointError(
+                f"no checkpoints for {json.dumps(sandbox)} — take one with checkpoint() or `kosa8 checkpoint {sandbox}`"
+            )
+        return lst[-1]
+
+    def resolve(self, sandbox: str, ref: str) -> Dict[str, Any]:
+        """Find by id or (case-insensitive) label, newest match first."""
+        for c in reversed(self.list(sandbox)):
+            if c.get("id") == ref or (c.get("label") or "").lower() == ref.lower():
+                return c
+        raise Kosa8CheckpointError(f"no checkpoint {json.dumps(ref)} for sandbox {json.dumps(sandbox)}")
+
+    def pop(self, sandbox: str, cid: str) -> List[str]:
+        """Keep ``cid`` as the top of the stack; return the ids taken after it."""
+
+        def fn(s: StoreData) -> List[str]:
+            lst = s.get(sandbox, [])
+            idx = next((i for i, c in enumerate(lst) if c.get("id") == cid), -1)
+            if idx < 0:
+                raise Kosa8CheckpointError(f"no checkpoint {json.dumps(cid)} for sandbox {json.dumps(sandbox)}")
+            orphaned = [c["id"] for c in lst[idx + 1:]]
+            s[sandbox] = lst[: idx + 1]
+            return orphaned
+
+        return self.store.update(fn)
+
+    def forget(self, sandbox: str) -> List[str]:
+        """Drop every checkpoint of a sandbox; return the snapshot ids to delete."""
+
+        def fn(s: StoreData) -> List[str]:
+            ids = [c["id"] for c in s.get(sandbox, [])]
+            s.pop(sandbox, None)
+            return ids
+
+        return self.store.update(fn)