amkernel 0.1.0__py3-none-any.whl

amkernel/workspace.py

@@ -0,0 +1,305 @@
+"""Descriptor-confined workspace and environment prelude helpers.
+
+These helpers are a safe default for generated code, not a sandbox. User Python
+retains unrestricted access to ordinary same-user filesystem and process APIs.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import stat
+from dataclasses import dataclass
+from typing import Final, cast
+
+MAX_READ_BYTES: Final = 67_108_864
+_ENV_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class WorkspaceError(ValueError):
+    """A confined workspace operation is invalid or unsafe."""
+
+
+class ReadError(WorkspaceError):
+    """A confined read could not safely return a regular file."""
+
+
+class ReadLimitError(ReadError):
+    """A regular file exceeds the requested read limit."""
+
+
+class WriteError(WorkspaceError):
+    """A confined atomic write could not safely replace a regular file."""
+
+
+class EnvError(ValueError):
+    """An environment helper argument is invalid."""
+
+
+class _Missing:
+    def __repr__(self) -> str:
+        return "<missing>"
+
+
+_MISSING = _Missing()
+
+
+@dataclass(frozen=True, slots=True)
+class _RootIdentity:
+    device: int
+    inode: int
+
+
+class Workspace:
+    """Pin one launch directory and create fresh callable prelude helpers."""
+
+    def __init__(self, launch_directory: str) -> None:
+        self._require_platform_support()
+        canonical = launch_directory
+        flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+        try:
+            descriptor = os.open(".", flags)
+            metadata = os.fstat(descriptor)
+        except OSError as error:
+            raise WorkspaceError("workspace initialization failed") from error
+        if not stat.S_ISDIR(metadata.st_mode):
+            os.close(descriptor)
+            raise WorkspaceError("workspace root is not a regular directory")
+        self._canonical = canonical
+        self._descriptor = descriptor
+        self._identity = _RootIdentity(metadata.st_dev, metadata.st_ino)
+
+    def close(self) -> None:
+        descriptor = self._descriptor
+        if descriptor < 0:
+            return
+        self._descriptor = -1
+        os.close(descriptor)
+
+    def helpers(self) -> tuple[ReadHelper, WriteHelper, EnvHelper]:
+        return ReadHelper(self), WriteHelper(self), EnvHelper()
+
+    def read(self, path: object, *, binary: bool, limit: int) -> str | bytes:
+        if type(binary) is not bool:
+            raise ReadError("binary must be a boolean")
+        if type(limit) is not int or not 0 <= limit <= MAX_READ_BYTES:
+            raise ReadError("limit must be an integer from 0 through 67108864")
+        parent, name = self._open_parent(path, ReadError)
+        descriptor = -1
+        try:
+            descriptor = os.open(
+                name,
+                os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK,
+                dir_fd=parent,
+            )
+            metadata = os.fstat(descriptor)
+            if not stat.S_ISREG(metadata.st_mode):
+                raise ReadError("read target is not a regular file")
+            remaining = limit + 1
+            data = bytearray()
+            while remaining:
+                chunk = os.read(descriptor, min(65_536, remaining))
+                if not chunk:
+                    break
+                data.extend(chunk)
+                remaining -= len(chunk)
+            if len(data) > limit:
+                raise ReadLimitError("read target exceeds limit")
+            raw = bytes(data)
+            if binary:
+                return raw
+            try:
+                return raw.decode("utf-8", errors="strict")
+            except UnicodeDecodeError as error:
+                raise ReadError("read target is not valid UTF-8") from error
+        except ReadError:
+            raise
+        except OSError as error:
+            raise ReadError("workspace read failed") from error
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+            os.close(parent)
+
+    def write(self, path: object, content: object) -> int:
+        data = self._write_bytes(content)
+        parent, name = self._open_parent(path, WriteError)
+        temporary = f".amkernel-write-{secrets.token_hex(16)}"
+        descriptor = -1
+        temporary_created = False
+        try:
+            before = self._destination_identity(parent, name)
+            descriptor = os.open(
+                temporary,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=parent,
+            )
+            temporary_created = True
+            view = memoryview(data)
+            while view:
+                written = os.write(descriptor, view)
+                if written <= 0:
+                    raise WriteError("workspace write made no progress")
+                view = view[written:]
+            os.fchmod(descriptor, 0o600)
+            os.close(descriptor)
+            descriptor = -1
+            if self._destination_identity(parent, name) != before:
+                raise WriteError("write destination changed during replacement")
+            os.rename(temporary, name, src_dir_fd=parent, dst_dir_fd=parent)
+            temporary = ""
+            final = os.stat(name, dir_fd=parent, follow_symlinks=False)
+            if not stat.S_ISREG(final.st_mode):
+                raise WriteError("write destination is not a regular file")
+            return len(data)
+        except WriteError:
+            raise
+        except OSError as error:
+            raise WriteError("workspace write failed") from error
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
+            if temporary_created and temporary:
+                try:
+                    os.unlink(temporary, dir_fd=parent)
+                except FileNotFoundError:
+                    pass
+                except OSError:
+                    pass
+            os.close(parent)
+
+    def _open_parent(self, path: object, error_type: type[WorkspaceError]) -> tuple[int, str]:
+        components = self._components(path, error_type)
+        current = os.dup(self._descriptor)
+        try:
+            for component in components[:-1]:
+                following = os.open(
+                    component,
+                    os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                    dir_fd=current,
+                )
+                metadata = os.fstat(following)
+                if not stat.S_ISDIR(metadata.st_mode):
+                    os.close(following)
+                    raise error_type("workspace parent is not a regular directory")
+                os.close(current)
+                current = following
+            return current, components[-1]
+        except error_type:
+            os.close(current)
+            raise
+        except OSError as error:
+            os.close(current)
+            raise error_type("workspace path resolution failed") from error
+
+    def _components(self, path: object, error_type: type[WorkspaceError]) -> tuple[str, ...]:
+        try:
+            raw = os.fspath(cast(str | os.PathLike[str], path))
+        except TypeError as error:
+            raise error_type("path must be a string or path-like value") from error
+        if not isinstance(raw, str) or not raw or "\x00" in raw:
+            raise error_type("path must be a nonempty NUL-free text path")
+        if os.path.isabs(raw):
+            try:
+                if os.path.commonpath((self._canonical, raw)) != self._canonical:
+                    raise error_type("absolute path is outside the launch workspace")
+            except ValueError as error:
+                raise error_type("absolute path is outside the launch workspace") from error
+            relative = raw[len(self._canonical) :]
+            if relative.startswith(os.sep):
+                relative = relative[1:]
+        else:
+            relative = raw
+        components = tuple(relative.split(os.sep))
+        if not components or any(part in {"", ".", ".."} for part in components):
+            raise error_type("path contains an empty or traversal component")
+        return components
+
+    @staticmethod
+    def _write_bytes(content: object) -> bytes:
+        if isinstance(content, str):
+            return content.encode("utf-8", errors="strict")
+        if isinstance(content, bytes):
+            return content
+        raise WriteError("content must be text or bytes")
+
+    @staticmethod
+    def _destination_identity(parent: int, name: str) -> tuple[int, int] | None:
+        try:
+            metadata = os.stat(name, dir_fd=parent, follow_symlinks=False)
+        except FileNotFoundError:
+            return None
+        if not stat.S_ISREG(metadata.st_mode):
+            raise WriteError("write destination is not a regular file")
+        return metadata.st_dev, metadata.st_ino
+
+    @staticmethod
+    def _require_platform_support() -> None:
+        required = (os.open, os.stat, os.unlink)
+        if not hasattr(os, "O_DIRECTORY") or not hasattr(os, "O_NOFOLLOW"):
+            raise WorkspaceError("descriptor-relative no-follow workspace helpers are unavailable")
+        if any(function not in os.supports_dir_fd for function in required):
+            raise WorkspaceError("descriptor-relative no-follow workspace helpers are unavailable")
+        if os.replace not in os.supports_dir_fd and os.rename not in os.supports_dir_fd:
+            raise WorkspaceError("descriptor-relative atomic replacement is unavailable")
+
+
+class ReadHelper:
+    """Descriptor-confined convenience read; unrestricted Python is not sandboxed."""
+
+    def __init__(self, workspace: Workspace) -> None:
+        self._workspace = workspace
+
+    def __call__(
+        self, path: object, *, binary: bool = False, limit: int = 1_048_576
+    ) -> str | bytes:
+        return self._workspace.read(path, binary=binary, limit=limit)
+
+    def __repr__(self) -> str:
+        return "<AMKernel helper read>"
+
+
+class WriteHelper:
+    """Descriptor-confined atomic write; unrestricted Python is not sandboxed."""
+
+    def __init__(self, workspace: Workspace) -> None:
+        self._workspace = workspace
+
+    def __call__(self, path: object, content: object) -> int:
+        return self._workspace.write(path, content)
+
+    def __repr__(self) -> str:
+        return "<AMKernel helper write>"
+
+
+class EnvHelper:
+    """Convenient process environment access; this is not a credential boundary."""
+
+    def __call__(self, key: object = _MISSING, value: object = _MISSING) -> object:
+        if key is _MISSING:
+            if value is not _MISSING:
+                raise EnvError("value requires a key")
+            return dict(os.environ)
+        if value is _MISSING:
+            name = self._key(key)
+            return os.environ.get(name)
+        name = self._key(key)
+        previous = os.environ.get(name)
+        if value is None:
+            os.environ.pop(name, None)
+            return previous
+        if not isinstance(value, str) or "\x00" in value:
+            raise EnvError("environment value must be NUL-free text or None")
+        os.environ[name] = value
+        return previous
+
+    def __repr__(self) -> str:
+        return "<AMKernel helper env>"
+
+    @staticmethod
+    def _key(key: object) -> str:
+        if not isinstance(key, str) or _ENV_KEY.fullmatch(key) is None:
+            raise EnvError("environment key must be a portable nonempty name")
+        return key

amkernel-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.3
+Name: amkernel
+Version: 0.1.0
+Summary: Persistent Python execution for agentic automation.
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: mcp>=2.3,<3
+Requires-Dist: pillow>=12,<13
+Requires-Dist: pydantic>=2.14,<3
+Requires-Dist: tomlkit>=0.13,<1
+Requires-Python: >=3.11, <3.14
+Description-Content-Type: text/markdown
+
+# AMKernel
+
+**AMKernel — Automation MCP Kernel**
+
+> Persistent Python execution for agentic automation.
+>
+> 面向 Agent 自动化的持久 Python Execution MCP。
+
+AMKernel is a persistent Python execution MCP for agentic automation. Mobile automation through Appium is its first experimental vertical.
+
+AMKernel 是一个面向 Agent 自动化的持久 Python Execution MCP。基于 Appium 的移动自动化是它的第一个实验方向。
+
+Agents use ordinary Python automation libraries while retaining live objects, imports, and state across tool calls.
+
+## Why the name
+
+- **Automation** — Appium, Playwright, Windows, macOS, and other automation environments. / Appium、Playwright、Windows、macOS 等自动化场景。
+- **MCP** — the standard interface that attaches AMKernel to different Coding Agents. / 挂载到不同 Coding Agent 的标准接口。
+- **Kernel** — a persistent Python namespace with object reuse, incremental execution, and interrupt recovery. / 持久 Python namespace、对象复用、增量执行和中断恢复。
+
+```text
+Coding Agent
+  → MCP
+  → persistent Python kernel
+  → automation library
+  → external system
+```
+
+The first experimental vertical is mobile automation through Appium:
+
+```text
+Coding Agent
+  → AMKernel
+  → Appium Python Client
+  → Appium Server
+  → XCUITest / UiAutomator2
+  → mobile device
+```
+
+Future experiments may apply the same kernel to Playwright, Selenium, pywinauto, PyAutoGUI, macOS Accessibility, and other Python automation ecosystems. Those platforms do not belong in the core until experiments establish shared requirements.
+
+## Project principles
+
+- Python execution is the primary Agent interface.
+- State persists across MCP calls.
+- The Agent uses official automation libraries directly.
+- The kernel reports truthful execution and survival state.
+- Text, structured values, images, and large artifacts are first-class outputs.
+- Platform knowledge starts in project skills and experiments, not core abstractions.
+- AMKernel is local stdio code execution first, not a remote multi-tenant sandbox.
+- The core grows from measured experimental needs, not hypothetical platform unification.
+
+## Install for a project
+
+AMKernel uses one user-level `uv`-managed Runtime and project-scoped Agent activation. From the project directory, run:
+
+```bash
+uvx --from amkernel amkernel install
+```
+
+The installer explains the changes, installs `.agents/skills/amkernel`, writes the detected OMP, Pi, or Codex project MCP entry, and asks you to restart the Coding Agent. It does not modify the project's `.venv`, install Appium Server or platform drivers, start a device, or create a session.
+
+Use `amkernel status`, `amkernel doctor`, `amkernel update`, and `amkernel uninstall` for the managed lifecycle. `amkernel uninstall --global` is explicit because it affects every activated project.
+
+## Current phase
+
+Stage 2 agent-quality output is implemented through the packaged stdio server and the single `python_exec` tool. One persistent Runtime now provides bounded live progress, recoverable stream artifacts, strict JSON and raster displays, explicit artifacts, requested-package diagnostics, descriptor-rooted workspace helpers, hard output-limit intervention, and truthful lifecycle/cleanup results.
+
+Artifact resource URIs are ephemeral. Read and verify every manifest part before another large-output call or server shutdown. AMKernel detects Store tampering when a resource is read, but unrestricted same-user Python can access host-visible files; AMKernel is not a sandbox.
+
+### Supported environments
+
+- CPython 3.11, 3.12, and 3.13.
+- Current GitHub-hosted Ubuntu and macOS environments, where the native lifecycle and installed-wheel official-client matrices are required release evidence.
+
+CPython 3.14, Windows, and other operating systems remain unsupported. The support claim is intentionally narrower than generic Linux or macOS package classifiers.
+
+Canonical documents:
+
+- [`docs/architecture.md`](docs/architecture.md) — generic AMKernel core architecture.
+- [`docs/development.md`](docs/development.md) — agent roles, change ownership, development workflow, and quality gates.
+- [`docs/stage-1-implementation-plan.md`](docs/stage-1-implementation-plan.md) — accepted Stage 1 contracts, dependency order, ownership, behavior scenarios, and risk traceability.
+- [`docs/stage-2-implementation-plan.md`](docs/stage-2-implementation-plan.md) — accepted Stage 2 output, artifact, lifecycle, evidence, and support contracts.
+- [`docs/project-management.md`](docs/project-management.md) — GitHub-backed workflow, Kanban semantics, task contracts, ADR, and risk governance.
+- [GitHub Project](https://github.com/orgs/FSQ-lab/projects/2) — canonical milestone, status, stage, type, priority, and queue.
+- [GitHub Issues](https://github.com/FSQ-lab/amkernel/issues) — canonical work-item, dependency, blocker, risk, and verification records.
+- [`docs/decisions/`](docs/decisions/) — accepted architecture and implementation decisions.
+- [`docs/experiments/mobile-appium.md`](docs/experiments/mobile-appium.md) — first Appium/mobile experiment and success criteria.
+
+Implementation follows the interfaces, invariants, and delivery order accepted in these documents.

amkernel-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+amkernel/__init__.py,sha256=NZ2VfLSZOXUHDLzkcMCAEN0-O83vjS0WY5hyZRb0Q6g,126
+amkernel/__main__.py,sha256=kIn6W2lkzwpctvu7ty50ImtePhM1nIj6SLUnN4gvPEc,96
+amkernel/artifact_store.py,sha256=6auaHmX03UKpJvPVhEEESlejOdqhr-bynlFMc3aU38w,57315
+amkernel/cli.py,sha256=SMxSCGeMJcpQ3E4_-i-auy2cMs8Ff6bOJHKx_OB_Y-s,7064
+amkernel/distribution.py,sha256=W4YdHOk11CWugahHeGE4JK23SRITQ6vo2xqrT9XBqzg,23049
+amkernel/output.py,sha256=Rv3H-U9IhXMTjlxG0XPILx9P5DJIXJgwO1pBK49Fovw,16370
+amkernel/protocol.py,sha256=prvE52snNbVpxeyLHXJExc6au0SkRnlGC0Xtv5Plsp8,54431
+amkernel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amkernel/runner.py,sha256=FyLRe_Ki9-8u49W0P79tM3ZClRyZq1kc-IubREwPsRg,42279
+amkernel/runtime.py,sha256=_W2lH0ha9SK7p142CiUlyjfT04uqr8ZyGAEgQfTwqus,22227
+amkernel/server.py,sha256=55MNmvsq1G15MssaD6ogF-hxGPAhNsS6FVZrRL7Popk,26755
+amkernel/skill/SKILL.md,sha256=GB-PcyXqXHXSgcAdhYb51BvPSBGLFbXGjOG9TsGWM7Y,10838
+amkernel/skill/references/amkernel-appium.md,sha256=s2yd34H-DcwimEk2CMVuLQIn_-xluSar4BhrBXLlVYw,2462
+amkernel/skill/references/official-skills.json,sha256=W7T8_uhDKyC3KnelqklLNAxAJwjRD859LLQU5mwcMrI,22440
+amkernel/skill/references/official-sources.json,sha256=tbbHj-duz3FQD87FZ8HhoB5gwsa24CTQYyhmA_qQNIU,834
+amkernel/skill/scripts/verify_official_skills.py,sha256=BJ2-nPUgWNVKMEgkJJSwfLFsHMbmAB0OtciNgfG0RuU,9889
+amkernel/structured_output.py,sha256=cjY4AXWhxiRWHrTIbyw_s0OS6HKe_rMDjQjHSFGwoAk,11937
+amkernel/supervisor.py,sha256=PyevwQsgV5AhqKUTWGRnAOPNxpTjx762EtpD7Bf5BN8,54853
+amkernel/workspace.py,sha256=HFMh-FQ-Q6EP38YeeGaYLS9D5WiavKL5NvYDmq8WQP0,11344
+amkernel-0.1.0.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+amkernel-0.1.0.dist-info/entry_points.txt,sha256=-kjjp2LXqOgnIRsKrR3WQwd_usST1EGfGx_xAcB30c4,48
+amkernel-0.1.0.dist-info/METADATA,sha256=NY7Qqx25pK5SwCvLz2CNpGiIoOmTkObzWmQ_ksxNGtM,5802
+amkernel-0.1.0.dist-info/RECORD,,

amkernel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.5
+Root-Is-Purelib: true
+Tag: py3-none-any

amkernel-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+amkernel = amkernel.cli:main
+