skillstate-kit 0.1.1__py3-none-any.whl

skillstate/providers.py

@@ -0,0 +1,89 @@
+"""Optional, stateless JSON adapter for compatible chat-completions endpoints."""
+
+from __future__ import annotations
+
+import math
+from urllib.parse import urlsplit
+
+from .errors import BudgetExceeded, ValidationError
+from .jsonio import dumps, loads
+
+
+class JSONChatModel:
+    """User-configured endpoint; never reads an IDE's session credentials.
+
+    Install the http extra. Each call sends only the supplied context. Endpoint
+    compatibility must include messages and response_format=json_object.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key: str | None = None,
+        timeout: float = 120,
+        *,
+        transport=None,
+    ):
+        parsed = urlsplit(base_url)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+        ):
+            raise ValidationError("Use an http(s) endpoint without credentials in the URL")
+        if not isinstance(model, str) or not model:
+            raise ValidationError("A model name is required")
+        if not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValidationError("Model timeout must be positive and finite")
+        self.url = base_url.rstrip("/") + "/chat/completions"
+        self.model, self.api_key, self.timeout, self.transport = model, api_key, timeout, transport
+
+    async def __call__(self, context: dict) -> dict:
+        try:
+            import httpx
+        except ImportError as exc:
+            raise ValidationError("Install skillstate-kit[http] for HTTP model access") from exc
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        payload = {
+            "model": self.model,
+            "response_format": {"type": "json_object"},
+            "messages": [
+                {
+                    "role": "system",
+                    "content": "Return only the requested JSON object. Do not include reasoning traces.",
+                },
+                {"role": "user", "content": dumps(context, 1_000_000)},
+            ],
+        }
+        try:
+            async with (
+                httpx.AsyncClient(
+                    timeout=self.timeout,
+                    transport=self.transport,
+                    trust_env=False,
+                    follow_redirects=False,
+                ) as client,
+                client.stream("POST", self.url, headers=headers, json=payload) as response,
+            ):
+                if response.status_code != 200:
+                    raise ValidationError(f"Model endpoint returned HTTP {response.status_code}")
+                chunks, size = [], 0
+                async for chunk in response.aiter_bytes():
+                    size += len(chunk)
+                    if size > 1_000_000:
+                        raise BudgetExceeded("Model HTTP response exceeds 1000000 bytes")
+                    chunks.append(chunk)
+        except httpx.HTTPError as exc:
+            raise ValidationError(
+                f"Model endpoint transport failed ({type(exc).__name__})"
+            ) from exc
+        try:
+            envelope = loads(b"".join(chunks).decode("utf-8"))
+            content = envelope["choices"][0]["message"]["content"]
+            if not isinstance(content, str):
+                raise ValidationError("Model response content must be JSON text")
+            return loads(content, 256_000)
+        except (KeyError, IndexError, TypeError, UnicodeError) as exc:
+            raise ValidationError("Model endpoint returned an incompatible response") from exc

skillstate/runtime.py

@@ -0,0 +1,179 @@
+"""History-free managed execution with bounded inputs and durable tool intents."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import math
+from collections.abc import Callable
+from typing import Any
+
+from .errors import ConflictError, OperationUncertain, StepLimitExceeded, ValidationError
+from .jsonio import dumps, loads, normalize
+from .models import Skill, Tool, ToolResult
+from .schema import apply_patch, check_schema, validate
+from .store import SQLiteStore
+
+CONTRACT = {
+    "patch": [{"op": "set or delete", "path": "/field", "value": "set only"}],
+    "action": {"name": "registered tool", "arguments": {}},
+    "done": False,
+}
+
+
+def context(snapshot: dict, tools: list[dict] | None = None, feedback: str | None = None) -> dict:
+    skill = Skill.from_dict(snapshot["skill"])
+    value = {
+        "instructions": skill.instructions,
+        "state_schema": skill.state_schema,
+        "state": snapshot["state"],
+        "observation": snapshot["observation"],
+        "tools": tools or [],
+        "response_contract": CONTRACT,
+        "response_rules": "Return only JSON with patch, action, done. To finish, set done=true and action=null. Do not include reasoning traces.",
+    }
+    if feedback is not None:
+        value["validation_feedback"] = feedback[:2000]
+    return loads(dumps(value, skill.limits.context_bytes))
+
+
+async def _call(function: Callable, *args):
+    if inspect.iscoroutinefunction(function):
+        return await function(*args)
+    result = await asyncio.to_thread(function, *args)
+    return await result if inspect.isawaitable(result) else result
+
+
+class SkillRuntime:
+    def __init__(
+        self,
+        store: SQLiteStore,
+        model: Callable,
+        tools: list[Tool],
+        *,
+        max_retries: int = 2,
+        model_timeout: float = 120,
+        completion_check: Callable[[dict], bool] | None = None,
+    ):
+        if type(max_retries) is not int or not 0 <= max_retries <= 10:
+            raise ValidationError("max_retries must be an integer from 0 to 10")
+        if (
+            not isinstance(model_timeout, (int, float))
+            or not math.isfinite(model_timeout)
+            or model_timeout <= 0
+        ):
+            raise ValidationError("model_timeout must be positive and finite")
+        self.store, self.model = store, model
+        self.tools = {}
+        for tool in tools:
+            if not tool.name or tool.name in self.tools:
+                raise ValidationError("Tool names must be nonempty and unique")
+            check_schema(tool.input_schema)
+            if tool.output_schema is not None:
+                check_schema(tool.output_schema)
+            if not math.isfinite(tool.timeout) or tool.timeout <= 0:
+                raise ValidationError("Tool timeout must be positive and finite")
+            self.tools[tool.name] = tool
+        self.max_retries, self.model_timeout = max_retries, model_timeout
+        self.completion_check = completion_check
+
+    def _decision(self, raw: Any, snapshot: dict) -> dict:
+        skill = Skill.from_dict(snapshot["skill"])
+        decision = (
+            loads(raw, skill.limits.output_bytes)
+            if isinstance(raw, str)
+            else loads(dumps(raw, skill.limits.output_bytes))
+        )
+        if type(decision) is not dict or set(decision) != {"patch", "action", "done"}:
+            raise ValidationError("Decision requires exactly patch, action, done")
+        if type(decision["done"]) is not bool:
+            raise ValidationError("done must be boolean")
+        candidate = apply_patch(snapshot["state"], decision["patch"])
+        validate(skill.state_schema, candidate)
+        dumps(candidate, skill.limits.state_bytes)
+        action = decision["action"]
+        if decision["done"]:
+            if action is not None:
+                raise ValidationError("A final decision must have action=null")
+            if self.completion_check is not None and self.completion_check(candidate) is not True:
+                raise ValidationError("Application completion check did not pass")
+        else:
+            if (
+                type(action) is not dict
+                or set(action) != {"name", "arguments"}
+                or type(action["name"]) is not str
+                or action["name"] not in self.tools
+            ):
+                raise ValidationError("Action must name a registered tool")
+            validate(self.tools[action["name"]].input_schema, action["arguments"])
+        return decision
+
+    async def step(self, run_id: str, owner: str) -> dict:
+        snapshot = self.store.get(run_id)
+        if (
+            snapshot["owner"] != owner
+            or snapshot["pending_operation"]
+            or snapshot["status"] != "ready"
+        ):
+            raise ConflictError("Run is not ready for this owner")
+        feedback = None
+        for attempt in range(self.max_retries + 1):
+            payload = context(snapshot, [t.specification() for t in self.tools.values()], feedback)
+            raw = await asyncio.wait_for(_call(self.model, payload), self.model_timeout)
+            try:
+                decision = self._decision(raw, snapshot)
+                break
+            except ValidationError as exc:
+                if attempt == self.max_retries:
+                    raise
+                feedback = str(exc)
+        if decision["done"]:
+            return self.store.update(
+                run_id,
+                owner,
+                snapshot["revision"],
+                decision["patch"],
+                snapshot["observation"],
+                done=True,
+            )
+        reservation = self.store.reserve(
+            run_id, owner, snapshot["revision"], decision["action"], decision["patch"]
+        )
+        op_id = reservation["operation_id"]
+        tool = self.tools[decision["action"]["name"]]
+        try:
+            result = await asyncio.wait_for(
+                _call(tool.handler, normalize(decision["action"]["arguments"]), op_id), tool.timeout
+            )
+            if type(result) is not ToolResult or type(result.success) is not bool:
+                raise ValidationError("Tool must return ToolResult with boolean success")
+            if tool.output_schema is not None:
+                validate(tool.output_schema, result.observation)
+            return self.store.record_result(
+                op_id, owner, result.success, result.observation, origin="runtime_observed"
+            )
+        except BaseException as exc:
+            # Cancellation/timeout does not imply the external side effect stopped.
+            # If persistence itself is broken, the prior pending intent is retained.
+            try:
+                if self.store.operation(op_id)["status"] in ("pending", "unknown"):
+                    self.store.mark_unknown(op_id, owner, type(exc).__name__)
+            except Exception:
+                pass
+            if isinstance(exc, (asyncio.CancelledError, KeyboardInterrupt, SystemExit)):
+                raise
+            raise OperationUncertain(
+                f"Operation {op_id} needs reconciliation ({type(exc).__name__})"
+            ) from exc
+
+    async def run(self, run_id: str, owner: str, *, max_steps: int = 30) -> dict:
+        if type(max_steps) is not int or not 1 <= max_steps <= 10_000:
+            raise ValidationError("max_steps must be an integer between 1 and 10000")
+        snapshot = self.store.get(run_id)
+        if snapshot["status"] == "completed":
+            return snapshot
+        for _ in range(max_steps):
+            snapshot = await self.step(run_id, owner)
+            if snapshot["status"] == "completed":
+                return snapshot
+        raise StepLimitExceeded("Step budget exhausted; checkpoint retained for an explicit resume")

skillstate/schema.py

@@ -0,0 +1,91 @@
+"""Inline JSON Schema validation and explicit dictionary patches."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import SchemaError
+from jsonschema.exceptions import ValidationError as JSONSchemaError
+
+from .errors import ValidationError
+from .jsonio import dumps, normalize
+
+
+def check_schema(schema: dict) -> None:
+    dumps(schema, 128_000)
+    if type(schema) is not dict or schema.get("type") != "object":
+        raise ValidationError("Root schema must have type=object")
+    if (
+        schema.get("$schema", "https://json-schema.org/draft/2020-12/schema")
+        != "https://json-schema.org/draft/2020-12/schema"
+    ):
+        raise ValidationError("Only JSON Schema draft 2020-12 is supported")
+
+    def visit(node: Any) -> None:
+        if isinstance(node, dict):
+            if "$ref" in node or "$dynamicRef" in node:
+                raise ValidationError("Use inline schemas; references are disabled")
+            if "patternProperties" in node:
+                raise ValidationError("patternProperties is disabled; use named properties")
+            if "pattern" in node and node["pattern"] not in ("^[a-z0-9-]+$",):
+                raise ValidationError(
+                    "Unrestricted regex patterns are disabled; use enum or a trusted application validator"
+                )
+            for value in node.values():
+                visit(value)
+        elif isinstance(node, list):
+            for value in node:
+                visit(value)
+
+    visit(schema)
+    try:
+        Draft202012Validator.check_schema(schema)
+    except SchemaError as exc:
+        raise ValidationError(f"Invalid schema: {exc.message}") from exc
+
+
+def validate(schema: dict, value: Any) -> None:
+    check_schema(schema)
+    value = normalize(value)
+    try:
+        Draft202012Validator(schema, format_checker=FormatChecker()).validate(value)
+    except (JSONSchemaError, RecursionError) as exc:
+        message = exc.message if isinstance(exc, JSONSchemaError) else "schema recursion"
+        raise ValidationError(f"State/arguments do not match schema: {message}") from exc
+
+
+def apply_patch(state: dict, operations: list[dict]) -> dict:
+    """Set/delete dictionary keys using JSON Pointer; replace arrays as a whole."""
+    state = normalize(state)
+    operations = normalize(operations)
+    if type(state) is not dict or type(operations) is not list or len(operations) > 128:
+        raise ValidationError("Expected object state and at most 128 patch operations")
+    result = deepcopy(state)
+    for op in operations:
+        if not isinstance(op, dict) or op.get("op") not in ("set", "delete"):
+            raise ValidationError("Patch operation must be set or delete")
+        expected = {"op", "path", "value"} if op["op"] == "set" else {"op", "path"}
+        if set(op) != expected:
+            raise ValidationError("Unexpected patch fields")
+        path = op["path"]
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise ValidationError("Patch path must be a non-root JSON Pointer")
+        segments = path[1:].split("/")
+        for segment in segments:
+            if "~" in segment.replace("~0", "").replace("~1", ""):
+                raise ValidationError("Invalid JSON Pointer escape")
+        segments = [s.replace("~1", "/").replace("~0", "~") for s in segments]
+        parent = result
+        for segment in segments[:-1]:
+            if segment not in parent or type(parent[segment]) is not dict:
+                raise ValidationError("Patch parent must be an existing object")
+            parent = parent[segment]
+        if op["op"] == "set":
+            parent[segments[-1]] = deepcopy(op["value"])
+        else:
+            if segments[-1] not in parent:
+                raise ValidationError("Cannot delete a missing key")
+            del parent[segments[-1]]
+    return result

skillstate/service.py

@@ -0,0 +1,59 @@
+"""One project-bound facade shared by CLI and MCP."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from . import compiler
+from .errors import SourceChanged, ValidationError
+from .jsonio import within
+from .models import Skill
+from .runtime import context
+from .store import SQLiteStore
+
+
+class ProjectService:
+    def __init__(self, project: Path):
+        self.project = project.resolve()
+        if not self.project.is_dir():
+            raise ValidationError("Project root must be an existing directory")
+
+    def store(self) -> SQLiteStore:
+        return SQLiteStore(within(self.project, ".skillstate/local/state.sqlite3"))
+
+    def open_run(self, name: str, owner: str, run_id: str | None = None, observation=None) -> dict:
+        bundle = compiler.load_bundle(self.project, name)
+        skill = Skill.from_dict(bundle["skill"])
+        with self.store() as store:
+            return store.create(run_id or uuid.uuid4().hex, skill, owner, observation)
+
+    def run_context(self, run_id: str) -> dict:
+        with self.store() as store:
+            snapshot = store.get(run_id)
+        drift = None
+        try:
+            bundle = compiler.load_bundle(self.project, snapshot["skill"]["name"])
+            if (
+                Skill.from_dict(bundle["skill"]).fingerprint
+                != Skill.from_dict(snapshot["skill"]).fingerprint
+            ):
+                drift = "Definition changed; this run keeps its original immutable definition"
+        except SourceChanged as exc:
+            drift = str(exc)
+        return {
+            "run_id": run_id,
+            "owner": snapshot["owner"],
+            "revision": snapshot["revision"],
+            "status": snapshot["status"],
+            "pending_operation": snapshot["pending_operation"],
+            "source_drift": drift,
+            "context": context(snapshot),
+        }
+
+    def handoff(self, run_id: str, owner: str, revision: int, target: str) -> dict:
+        snapshot = self.run_context(run_id)
+        if snapshot["source_drift"]:
+            raise SourceChanged("Resolve source/definition drift before handing off")
+        with self.store() as store:
+            return store.handoff(run_id, owner, revision, target)