nullprotocol 0.3.0__tar.gz → 0.4.0__tar.gz

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.0
+
+- Add sync/async Knowledge wait_until_ready for exact revisions, metadata polling and bounded timeouts; async task cancellation cancels reads.
+- Send action parameter schemas as first-class choices (API0.24+) so the engine can repair them before success; reject schema-invalid successful server replies.
+- Clarify Context key/value errors and JSON null support. Align the exported __version__ with package metadata.
+
 ## 0.3.0
 
 - Add images to all four sync/async operations, with HTTPS URL validation, explicit model capability refusals and unchanged text requests.

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullprotocol
-Version: 0.3.0
+Version: 0.4.0
 Summary: Focused AI tasks with managed context, Knowledge and observable results
 Project-URL: Homepage, https://nullprotocol.ai
 Project-URL: Documentation, https://nullprotocol.ai/docs/python
@@ -156,9 +156,8 @@ shared = agent.space.knowledge.add(
     name="Returns policy",
     text="# Returns\nUnused goods may be returned within 30 days.",
 )
-source = agent.space.knowledge.get(shared["id"])
-if source["state"] == "ready":
-    agent.knowledge.connect(shared["id"])
+agent.space.knowledge.wait_until_ready(shared)
+agent.knowledge.connect(shared["id"])
 
 own = agent.knowledge.add(name="FAQ", text="We ship on weekdays.")
 changed = agent.knowledge.update(
@@ -171,7 +170,7 @@ agent.knowledge.delete(own["id"], if_version=changed["version"])
 
 Use these snippets inside the client context above. `add`/`update` return `id`, `revision` and `version`; preparation is asynchronous. Inspect `get(id)["state"]`: preparing, ready or failed, plus `activeRevision`, `error` and `retryScheduled`. For a live agent, stage a new document in the Space library and connect it after it is ready. An unprepared new agent-owned/connected source refuses Knowledge calls; calls without Knowledge continue. A replacement keeps the previous prepared revision in use until the new one is ready.
 
-Both stores provide `add`, `list`, `get`, `update`, `delete` and `retry`. `agent.knowledge.list()` lists only agent-owned documents. `agent.space.knowledge.list()` lists the shared library, and `agent.knowledge.connections()` lists connected Space sources. Read/update/delete through the owning store; connecting does not copy a document. Use `connect(id)`/`disconnect(id)` on `agent.knowledge`. Scope IDs do not change Knowledge ownership or connections.
+Both stores provide `add`, `list`, `get`, `wait_until_ready`, `update`, `delete` and `retry`. `agent.knowledge.list()` lists only agent-owned documents. `agent.space.knowledge.list()` lists the shared library, and `agent.knowledge.connections()` lists connected Space sources. Read/update/delete through the owning store; connecting does not copy a document. Use `connect(id)`/`disconnect(id)` on `agent.knowledge`. Scope IDs do not change Knowledge ownership or connections.
 
 Updates and deletes require `if_version`; a competing edit raises `APIError` with code `version_conflict`. The SDK never silently substitutes a newer version. A rename changes the version but not the text revision. `retry(id)` explicitly restarts failed preparation and returns a `retrying` flag; it does not wait or reindex a ready document. Preparation and searches can use embedding tokens. `agent.space.knowledge.usage()` returns 30-day Space totals: `preparation`, `search`, `uncounted` and `requests`, preserving unknown sums as None and reported sums as decimal strings.
 
@@ -206,7 +205,7 @@ if decision.success:
     print(execution.success, execution.outcome, execution.history_error)
 ```
 
-Handlers receive `(parameters, ActionContext)`. `context.input` is the original task; `context.decision` is a copy of its decision snapshot. The SDK supplies registered parameter schemas as structured data in the decision's `context` because the HTTP endpoint only accepts action names and descriptions. The original task and schema contract are visible in History. Automatic Knowledge queries still use the original task, not that schema wrapper.
+Handlers receive `(parameters, ActionContext)`. `context.input` is the original task; `context.decision` is a copy of its decision snapshot. Registered parameter schemas travel with the action choices. The hosted engine checks and repairs them before a successful decision, and execute rechecks them locally. Inline choices may also provide `parameters: schema`. The original task stays unchanged and is the input for automatic Knowledge search. These schema-bearing choices require API 0.24 or later.
 
 Before a handler runs, `execute` rereads pause/disabled settings, validates its parameters against the registered JSON Schema and checks the optional guard. A guard must return exactly `True`. Changing the returned result or values in a guard does not change the checked execution snapshot. Only an original successful decision from that agent object can be executed; a JSON/HTTP response loaded elsewhere is not executable. There is no implicit `chat` action or automatic tool loop.
 
@@ -280,3 +279,11 @@ result = agent.extract(
 Use the loaded agent inside your client context. All four operations support up to four reachable HTTPS photo URLs of at most 2048 UTF-16 characters. Async clients accept the same keyword. Select a Vision-capable model. Empty text is allowed for photo-only input; validate still needs criteria and decide needs its actions. Inline base64, browser blob URLs and local files are not supported.
 
 History retains URLs, not immutable copies of remote images. Knowledge uses a text query, not the photo or its URL; supply an explicit query for a photo-only search. Generation usage includes provider-reported image tokens. The gateway conservatively holds credit against the model context ceiling for photo calls, settles actual reported usage and releases the unused reserve. [Photo guide](https://nullprotocol.ai/docs/images?lang=python).
+
+## Wait for preparation
+
+`agent.knowledge.wait_until_ready(source, timeout=120)` accepts the revision returned by `add`, `update` or `get` and waits for that exact version using metadata only. Timeout is seconds. Both agent and Space stores support it. On an async agent, await the method; cancelling the task cancels waiting and the in-flight read. Server preparation continues.
+
+The method waits through server-scheduled retries without starting new ones. It raises `KnowledgeError` with code `version_conflict`, `knowledge_not_found`, `knowledge_prepare_failed` or `knowledge_wait_timeout`. The returned dictionary contains metadata, not the full text.
+
+Saved Context keys have 1–64 lowercase letters, digits, dots, underscores or hyphens, starting with a letter. JSON `None` is a stored null value; use `delete` to remove it.

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/README.md

@@ -126,9 +126,8 @@ shared = agent.space.knowledge.add(
     name="Returns policy",
     text="# Returns\nUnused goods may be returned within 30 days.",
 )
-source = agent.space.knowledge.get(shared["id"])
-if source["state"] == "ready":
-    agent.knowledge.connect(shared["id"])
+agent.space.knowledge.wait_until_ready(shared)
+agent.knowledge.connect(shared["id"])
 
 own = agent.knowledge.add(name="FAQ", text="We ship on weekdays.")
 changed = agent.knowledge.update(
@@ -141,7 +140,7 @@ agent.knowledge.delete(own["id"], if_version=changed["version"])
 
 Use these snippets inside the client context above. `add`/`update` return `id`, `revision` and `version`; preparation is asynchronous. Inspect `get(id)["state"]`: preparing, ready or failed, plus `activeRevision`, `error` and `retryScheduled`. For a live agent, stage a new document in the Space library and connect it after it is ready. An unprepared new agent-owned/connected source refuses Knowledge calls; calls without Knowledge continue. A replacement keeps the previous prepared revision in use until the new one is ready.
 
-Both stores provide `add`, `list`, `get`, `update`, `delete` and `retry`. `agent.knowledge.list()` lists only agent-owned documents. `agent.space.knowledge.list()` lists the shared library, and `agent.knowledge.connections()` lists connected Space sources. Read/update/delete through the owning store; connecting does not copy a document. Use `connect(id)`/`disconnect(id)` on `agent.knowledge`. Scope IDs do not change Knowledge ownership or connections.
+Both stores provide `add`, `list`, `get`, `wait_until_ready`, `update`, `delete` and `retry`. `agent.knowledge.list()` lists only agent-owned documents. `agent.space.knowledge.list()` lists the shared library, and `agent.knowledge.connections()` lists connected Space sources. Read/update/delete through the owning store; connecting does not copy a document. Use `connect(id)`/`disconnect(id)` on `agent.knowledge`. Scope IDs do not change Knowledge ownership or connections.
 
 Updates and deletes require `if_version`; a competing edit raises `APIError` with code `version_conflict`. The SDK never silently substitutes a newer version. A rename changes the version but not the text revision. `retry(id)` explicitly restarts failed preparation and returns a `retrying` flag; it does not wait or reindex a ready document. Preparation and searches can use embedding tokens. `agent.space.knowledge.usage()` returns 30-day Space totals: `preparation`, `search`, `uncounted` and `requests`, preserving unknown sums as None and reported sums as decimal strings.
 
@@ -176,7 +175,7 @@ if decision.success:
     print(execution.success, execution.outcome, execution.history_error)
 ```
 
-Handlers receive `(parameters, ActionContext)`. `context.input` is the original task; `context.decision` is a copy of its decision snapshot. The SDK supplies registered parameter schemas as structured data in the decision's `context` because the HTTP endpoint only accepts action names and descriptions. The original task and schema contract are visible in History. Automatic Knowledge queries still use the original task, not that schema wrapper.
+Handlers receive `(parameters, ActionContext)`. `context.input` is the original task; `context.decision` is a copy of its decision snapshot. Registered parameter schemas travel with the action choices. The hosted engine checks and repairs them before a successful decision, and execute rechecks them locally. Inline choices may also provide `parameters: schema`. The original task stays unchanged and is the input for automatic Knowledge search. These schema-bearing choices require API 0.24 or later.
 
 Before a handler runs, `execute` rereads pause/disabled settings, validates its parameters against the registered JSON Schema and checks the optional guard. A guard must return exactly `True`. Changing the returned result or values in a guard does not change the checked execution snapshot. Only an original successful decision from that agent object can be executed; a JSON/HTTP response loaded elsewhere is not executable. There is no implicit `chat` action or automatic tool loop.
 
@@ -250,3 +249,11 @@ result = agent.extract(
 Use the loaded agent inside your client context. All four operations support up to four reachable HTTPS photo URLs of at most 2048 UTF-16 characters. Async clients accept the same keyword. Select a Vision-capable model. Empty text is allowed for photo-only input; validate still needs criteria and decide needs its actions. Inline base64, browser blob URLs and local files are not supported.
 
 History retains URLs, not immutable copies of remote images. Knowledge uses a text query, not the photo or its URL; supply an explicit query for a photo-only search. Generation usage includes provider-reported image tokens. The gateway conservatively holds credit against the model context ceiling for photo calls, settles actual reported usage and releases the unused reserve. [Photo guide](https://nullprotocol.ai/docs/images?lang=python).
+
+## Wait for preparation
+
+`agent.knowledge.wait_until_ready(source, timeout=120)` accepts the revision returned by `add`, `update` or `get` and waits for that exact version using metadata only. Timeout is seconds. Both agent and Space stores support it. On an async agent, await the method; cancelling the task cancels waiting and the in-flight read. Server preparation continues.
+
+The method waits through server-scheduled retries without starting new ones. It raises `KnowledgeError` with code `version_conflict`, `knowledge_not_found`, `knowledge_prepare_failed` or `knowledge_wait_timeout`. The returned dictionary contains metadata, not the full text.
+
+Saved Context keys have 1–64 lowercase letters, digits, dots, underscores or hyphens, starting with a letter. JSON `None` is a stored null value; use `delete` to remove it.

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/examples/knowledge_management.py

@@ -1,7 +1,5 @@
 """Set NULLPROTOCOL_KEY and create support first. Uses hosted tokens; cleans up its source."""
 
-import time
-
 from nullprotocol import NullProtocol, NullProtocolError
 
 with NullProtocol() as client:
@@ -12,18 +10,7 @@ with NullProtocol() as client:
     )
     connected = False
     try:
-        deadline = time.monotonic() + 30
-        while True:
-            status = agent.space.knowledge.get(source["id"])
-            if status["version"] != source["version"]:
-                raise RuntimeError("The source was edited by another client.")
-            if status["state"] == "ready":
-                break
-            if status["state"] == "failed":
-                raise RuntimeError(f"Preparation failed: {status['error']}")
-            if time.monotonic() >= deadline:
-                raise TimeoutError("Knowledge is still preparing. Try again later.")
-            time.sleep(0.25)
+        agent.space.knowledge.wait_until_ready(source, timeout=30)
         agent.knowledge.connect(source["id"])
         connected = True
         result = agent.extract(

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nullprotocol"
-version = "0.3.0"
+version = "0.4.0"
 description = "Focused AI tasks with managed context, Knowledge and observable results"
 readme = "README.md"
 requires-python = ">=3.10"

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/__init__.py

@@ -2,11 +2,11 @@
 
 from ._agent import Agent, AsyncAgent
 from ._client import AsyncNullProtocol, NullProtocol
-from ._errors import APIError, NullProtocolError, ProtocolError, TransportError
+from ._errors import APIError, KnowledgeError, NullProtocolError, ProtocolError, TransportError
 from ._knowledge import AgentKnowledge, AsyncAgentKnowledge, AsyncKnowledgeLibrary, KnowledgeLibrary
 from ._types import ActionContext, Execution, KnowledgeUsage, Result, Usage
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __all__ = [
     "AgentKnowledge",
     "KnowledgeLibrary",
@@ -19,6 +19,7 @@ __all__ = [
     "AsyncNullProtocol",
     "Execution",
     "KnowledgeUsage",
+    "KnowledgeError",
     "NullProtocol",
     "NullProtocolError",
     "ProtocolError",

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/_agent.py

@@ -27,7 +27,7 @@ from ._stores import (
     MemoryStore,
     SpaceContextStore,
 )
-from ._transport import _UNSET, AsyncTransport, Transport, json_body
+from ._transport import _UNSET, AsyncTransport, Transport
 from ._types import ActionContext, Execution, Result
 
 
@@ -61,20 +61,6 @@ def _result(response: dict[str, Any], task_id: str, operation: str) -> Result[An
     return result
 
 
-def _knowledge_for_decision(
-    context: Any,
-    values: dict[str, Any],
-    knowledge: Knowledge | None,
-) -> Knowledge | None:
-    if (
-        knowledge is True
-        and isinstance(values["context"], dict)
-        and "actionParameterSchemas" in values["context"]
-    ):
-        return {"query": context if isinstance(context, str) else json_body(context).decode()}
-    return knowledge
-
-
 def _changes(values: dict[str, Any]) -> dict[str, Any]:
     mapping = {"disabled_actions": "disabledActions", "if_revision": "ifRevision"}
     body = {mapping.get(k, k): v for k, v in values.items() if v is not None}
@@ -273,12 +259,12 @@ class Agent(AgentState):
         result = self._run(
             "decide",
             values,
-            _knowledge_for_decision(original, values, knowledge),
+            knowledge,
             context_keys,
             idempotency_key,
             images,
         )
-        return self._remember(result, original)
+        return self._remember(result, original, values["actions"])
 
     def execute(self, decision: Result[Any]) -> Execution:
         made, problem = self._consume(decision)
@@ -481,12 +467,12 @@ class AsyncAgent(AgentState):
         result = await self._run(
             "decide",
             values,
-            _knowledge_for_decision(original, values, knowledge),
+            knowledge,
             context_keys,
             idempotency_key,
             images,
         )
-        return self._remember(result, original)
+        return self._remember(result, original, values["actions"])
 
     async def execute(self, decision: Result[Any]) -> Execution:
         made, problem = self._consume(decision)

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/_common.py

@@ -16,7 +16,7 @@ from ._transport import identifier, json_body, request_id, scope_id, utf16_lengt
 from ._types import Result
 
 Knowledge = bool | dict[str, str]
-ActionChoice = str | dict[str, str]
+ActionChoice = str | dict[str, Any]
 
 
 def object_field(body: dict[str, Any], field: str) -> dict[str, Any]:
@@ -244,12 +244,16 @@ class AgentState:
     def _choices(self, context: Any, actions: list[ActionChoice]) -> dict[str, Any]:
         if not isinstance(actions, list) or not 1 <= len(actions) <= 32:
             raise ValueError("actions must contain 1–32 action choices.")
-        choices, schemas = [], {}
+        choices = []
         for offered in actions:
             if isinstance(offered, str):
                 name = offered
                 description = None
-            elif isinstance(offered, dict) and set(offered) <= {"action", "description"}:
+            elif isinstance(offered, dict) and set(offered) <= {
+                "action",
+                "description",
+                "parameters",
+            }:
                 name = offered.get("action", "")
                 description = offered.get("description")
             else:
@@ -260,21 +264,39 @@ class AgentState:
             registered = self._actions.get(name)
             if description is None and registered is not None:
                 description = registered.description
-            choice = {"action": name}
+            choice: dict[str, Any] = {"action": name}
             if description is not None:
                 if not isinstance(description, str) or utf16_length(description) > 1000:
                     raise ValueError("Action description must have at most 1000 UTF-16 characters.")
                 choice["description"] = description
+            schema = registered.schema if registered is not None else None
+            if schema is None and isinstance(offered, dict):
+                if "parameters" in offered:
+                    schema = offered["parameters"]
+                    schema_validator(schema)
+            if schema is not None:
+                choice["parameters"] = deepcopy(schema)
             choices.append(choice)
-            if registered is not None and registered.schema is not None:
-                schemas[name] = deepcopy(registered.schema)
-        # The HTTP endpoint accepts action descriptions, not schemas. Send schema
-        # contracts as structured task data and enforce them locally before execution.
-        prepared = {"task": context, "actionParameterSchemas": schemas} if schemas else context
-        return {"context": prepared, "actions": choices}
-
-    def _remember(self, result: Result[Any], original: Any) -> Result[Any]:
+        return {"context": context, "actions": choices}
+
+    def _remember(
+        self, result: Result[Any], original: Any, choices: list[dict[str, Any]]
+    ) -> Result[Any]:
         if result.success:
+            from ._errors import ProtocolError
+
+            chosen = next((choice for choice in choices if choice["action"] == result.action), None)
+            if chosen is None:
+                raise ProtocolError(
+                    "The server returned an action that was not offered.",
+                    request_id=result.request_id,
+                )
+            schema = chosen.get("parameters")
+            if schema is not None and not schema_validator(schema).is_valid(result.parameters):
+                raise ProtocolError(
+                    "The server returned parameters that do not match the action schema.",
+                    request_id=result.request_id,
+                )
             snapshot = Result.from_response(
                 {"result": result.raw, "operationId": result.operation_id},
                 result.request_id,

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/_errors.py

@@ -7,6 +7,16 @@ class NullProtocolError(Exception):
     """Base SDK error. Failed model operations are returned as Result, not raised."""
 
 
+class KnowledgeError(NullProtocolError):
+    """Preparation waiting failed locally; no model operation was run."""
+
+    def __init__(
+        self, code: str, message: str, *, source_id: str, version: str, reason: str | None = None
+    ) -> None:
+        self.code, self.source_id, self.version, self.reason = code, source_id, version, reason
+        super().__init__(message)
+
+
 class APIError(NullProtocolError):
     """An HTTP failure. Keep request_id when retrying an uncertain run."""
 
@@ -24,7 +34,17 @@ class APIError(NullProtocolError):
         self.request_id = request_id
         self.details = details or {}
         self.retry_after = retry_after
-        super().__init__(f"NullProtocol HTTP {status_code}: {code}")
+        messages = {
+            "invalid_context_key": (
+                "A Context key must have 1–64 lowercase letters, digits, dots, underscores or "
+                "hyphens, starting with a letter; for example order_id."
+            ),
+            "invalid_context_value": (
+                "Context value must be JSON-serializable. JSON null is allowed; "
+                "use delete to remove an entry."
+            ),
+        }
+        super().__init__(f"NullProtocol HTTP {status_code}: {messages.get(code, code)}")
 
 
 class TransportError(NullProtocolError):

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/_knowledge.py

@@ -1,11 +1,66 @@
 from __future__ import annotations
 
+import asyncio
+import math
+import time
 from typing import Any
 
 from ._common import checked_text, list_field, object_field, version
+from ._errors import KnowledgeError
 from ._transport import AsyncTransport, Transport
 
 
+def _target(source: dict[str, Any], timeout: float) -> tuple[str, str, int]:
+    if (
+        not isinstance(source, dict)
+        or type(source.get("revision")) is not int
+        or source["revision"] < 1
+    ):
+        raise ValueError("Pass the Knowledge revision returned by add, update or get.")
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ValueError("Knowledge timeout must be a positive number of seconds.")
+    source_id, expected = source.get("id"), source.get("version")
+    if not isinstance(source_id, str) or not isinstance(expected, str):
+        raise ValueError("Pass the Knowledge revision returned by add, update or get.")
+    return version(source_id), version(expected), source["revision"]
+
+
+def _prepared(
+    sources: list[dict[str, Any]], source_id: str, expected: str, revision: int
+) -> dict[str, Any] | None:
+    source = next((item for item in sources if item.get("id") == source_id), None)
+    if source is None:
+        raise KnowledgeError(
+            "knowledge_not_found",
+            "This Knowledge document was deleted or is not accessible.",
+            source_id=source_id,
+            version=expected,
+        )
+    if source.get("version") != expected:
+        raise KnowledgeError(
+            "version_conflict",
+            "The Knowledge document changed while waiting. Read its current revision first.",
+            source_id=source_id,
+            version=source["version"],
+        )
+    if source.get("state") == "ready" and source.get("activeRevision") == revision:
+        return source
+    if source.get("state") == "failed" and not source.get("retryScheduled"):
+        raise KnowledgeError(
+            "knowledge_prepare_failed",
+            "Knowledge preparation failed. Inspect the document and explicitly retry it.",
+            source_id=source_id,
+            version=expected,
+            reason=source.get("error"),
+        )
+    return None
+
+
 def _fields(
     name: str | None, text: str | None, *, update: bool = False, if_version: str | None = None
 ) -> dict[str, Any]:
@@ -33,8 +88,29 @@ class _Documents:
     def __init__(self, transport: Transport, path: str, scope: str) -> None:
         self._transport, self._path, self._scope = transport, path, scope
 
-    def _all(self) -> list[dict[str, Any]]:
-        return list_field(self._transport.request("GET", self._path), "sources")
+    def _all(self, *, deadline: float | None = None) -> list[dict[str, Any]]:
+        return list_field(self._transport.request("GET", self._path, deadline=deadline), "sources")
+
+    def wait_until_ready(self, source: dict[str, Any], *, timeout: float = 120) -> dict[str, Any]:
+        """Wait for this exact version using metadata reads. Timeout is seconds."""
+        source_id, expected, revision = _target(source, timeout)
+        deadline = time.monotonic() + timeout
+        try:
+            while True:
+                rows = self._all(deadline=deadline)
+                if time.monotonic() >= deadline:
+                    raise TimeoutError
+                ready = _prepared(rows, source_id, expected, revision)
+                if ready is not None:
+                    return ready
+                time.sleep(min(0.5, max(0, deadline - time.monotonic())))
+        except TimeoutError as exc:
+            raise KnowledgeError(
+                "knowledge_wait_timeout",
+                "Knowledge preparation did not finish within the timeout.",
+                source_id=source_id,
+                version=expected,
+            ) from exc
 
     def list(self) -> list[dict[str, Any]]:
         """List documents owned by this scope. Connections are listed separately."""
@@ -46,7 +122,7 @@ class _Documents:
         )
 
     def add(self, *, name: str, text: str) -> dict[str, Any]:
-        """Save text and begin preparation. Inspect get(id)['state'] for readiness."""
+        """Save text and begin preparation. Use wait_until_ready to await this version."""
         return self._transport.request("POST", self._path, body=_fields(name, text))
 
     def update(
@@ -102,8 +178,36 @@ class _AsyncDocuments:
     def __init__(self, transport: AsyncTransport, path: str, scope: str) -> None:
         self._transport, self._path, self._scope = transport, path, scope
 
-    async def _all(self) -> list[dict[str, Any]]:
-        return list_field(await self._transport.request("GET", self._path), "sources")
+    async def _all(self, *, deadline: float | None = None) -> list[dict[str, Any]]:
+        return list_field(
+            await self._transport.request("GET", self._path, deadline=deadline), "sources"
+        )
+
+    async def wait_until_ready(
+        self, source: dict[str, Any], *, timeout: float = 120
+    ) -> dict[str, Any]:
+        """Wait for this version; cancelling the task cancels the HTTP request too."""
+        source_id, expected, revision = _target(source, timeout)
+        deadline = time.monotonic() + timeout
+        try:
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError
+                rows = await asyncio.wait_for(self._all(deadline=deadline), timeout=remaining)
+                if time.monotonic() >= deadline:
+                    raise TimeoutError
+                ready = _prepared(rows, source_id, expected, revision)
+                if ready is not None:
+                    return ready
+                await asyncio.sleep(min(0.5, max(0, deadline - time.monotonic())))
+        except (TimeoutError, asyncio.TimeoutError) as exc:
+            raise KnowledgeError(
+                "knowledge_wait_timeout",
+                "Knowledge preparation did not finish within the timeout.",
+                source_id=source_id,
+                version=expected,
+            ) from exc
 
     async def list(self) -> list[dict[str, Any]]:
         return [source for source in await self._all() if source.get("scope") == self._scope]

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/src/nullprotocol/_transport.py

@@ -35,6 +35,11 @@ def utf16_length(value: str) -> int:
 def identifier(value: str, kind: str) -> str:
     pattern = r"[a-z0-9][a-z0-9._-]{0,63}" if kind == "agent ID" else r"[a-z][a-z0-9._-]{0,63}"
     if not isinstance(value, str) or not re.fullmatch(pattern, value):
+        if kind == "context key":
+            raise ValueError(
+                "Invalid context key. Use 1–64 lowercase letters, digits, dots, underscores or "
+                "hyphens, starting with a letter; for example order_id."
+            )
         raise ValueError(f"Invalid {kind}.")
     return value
 
@@ -156,6 +161,15 @@ def _retryable(response: httpx.Response) -> bool:
     return False
 
 
+def _budget(timeout: float, deadline: float | None) -> float:
+    if deadline is None:
+        return timeout
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise TimeoutError("Knowledge preparation wait timed out.")
+    return min(timeout, remaining)
+
+
 class Transport:
     def __init__(self, config: _Config, client: httpx.Client | None = None) -> None:
         self.config = config
@@ -177,6 +191,7 @@ class Transport:
         body: Any = _UNSET,
         params: dict[str, str] | None = None,
         task_id: str | None = None,
+        deadline: float | None = None,
     ) -> dict[str, Any]:
         if self.closed:
             raise TransportError("This NullProtocol client is closed.", request_id=task_id)
@@ -188,6 +203,7 @@ class Transport:
             headers["Idempotency-Key"] = task_id
         retries = self.config.max_retries if method == "GET" or task_id is not None else 0
         for attempt in range(retries + 1):
+            timeout = _budget(self.config.timeout, deadline)
             response = None
             try:
                 response = self.client.request(
@@ -196,23 +212,25 @@ class Transport:
                     headers=headers,
                     content=content,
                     params=params,
-                    timeout=self.config.timeout,
+                    timeout=timeout,
                     follow_redirects=False,
                 )
             except httpx.TransportError as exc:
+                _budget(self.config.timeout, deadline)
                 if attempt == retries:
                     raise TransportError(
                         "NullProtocol could not be reached. "
                         "Preserve request_id before retrying a run.",
                         request_id=task_id,
                     ) from exc
+            _budget(self.config.timeout, deadline)
             if response is not None and (attempt == retries or not _retryable(response)):
                 return _decode(response, task_id)
             delay = _delay(response, attempt)
             if delay is None:
                 assert response is not None
                 return _decode(response, task_id)
-            time.sleep(delay)
+            time.sleep(_budget(delay, deadline))
         raise AssertionError("Unreachable transport state")
 
 
@@ -237,6 +255,7 @@ class AsyncTransport:
         body: Any = _UNSET,
         params: dict[str, str] | None = None,
         task_id: str | None = None,
+        deadline: float | None = None,
     ) -> dict[str, Any]:
         if self.closed:
             raise TransportError("This NullProtocol client is closed.", request_id=task_id)
@@ -248,6 +267,7 @@ class AsyncTransport:
             headers["Idempotency-Key"] = task_id
         retries = self.config.max_retries if method == "GET" or task_id is not None else 0
         for attempt in range(retries + 1):
+            timeout = _budget(self.config.timeout, deadline)
             response = None
             try:
                 response = await self.client.request(
@@ -256,21 +276,23 @@ class AsyncTransport:
                     headers=headers,
                     content=content,
                     params=params,
-                    timeout=self.config.timeout,
+                    timeout=timeout,
                     follow_redirects=False,
                 )
             except httpx.TransportError as exc:
+                _budget(self.config.timeout, deadline)
                 if attempt == retries:
                     raise TransportError(
                         "NullProtocol could not be reached. "
                         "Preserve request_id before retrying a run.",
                         request_id=task_id,
                     ) from exc
+            _budget(self.config.timeout, deadline)
             if response is not None and (attempt == retries or not _retryable(response)):
                 return _decode(response, task_id)
             delay = _delay(response, attempt)
             if delay is None:
                 assert response is not None
                 return _decode(response, task_id)
-            await asyncio.sleep(delay)
+            await asyncio.sleep(_budget(delay, deadline))
         raise AssertionError("Unreachable transport state")

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/tests/test_knowledge.py

@@ -205,3 +205,135 @@ def test_async_management_matches_sync_routes():
                 assert await agent.space.knowledge.retry(shared["id"]) == {"retrying": False}
 
     asyncio.run(run())
+
+
+def test_wait_pins_revision_reads_metadata_and_observes_scheduled_retry():
+    from nullprotocol import KnowledgeError
+
+    api = KnowledgeAPI()
+    source = api.documents["agent"].copy()
+    count = 0
+
+    def handler(request):
+        nonlocal count
+        if request.url.path.endswith("/knowledge") and request.method == "GET":
+            count += 1
+            current = {**source, "state": "failed", "retryScheduled": True}
+            if count > 1:
+                current.update(state="ready", activeRevision=1, retryScheduled=False)
+            return httpx.Response(200, json={"sources": [current]})
+        return api(request)
+
+    with httpx.Client(transport=httpx.MockTransport(handler)) as http:
+        with NullProtocol(
+            key="fixture", endpoint="https://example.test", http_client=http
+        ) as client:
+            agent = client.load("support")
+            ready = agent.knowledge.wait_until_ready(source, timeout=2)
+            assert ready["activeRevision"] == 1
+            assert count == 2
+            assert all(not str(req.url).endswith(source["id"]) for req in api.requests)
+            changed = {**source, "version": str(uuid4())}
+            with pytest.raises(KnowledgeError) as conflict:
+                agent.knowledge.wait_until_ready(changed)
+            assert conflict.value.code == "version_conflict"
+
+
+@pytest.mark.parametrize(
+    "state,code",
+    [
+        ("failed", "knowledge_prepare_failed"),
+        ("missing", "knowledge_not_found"),
+        ("preparing", "knowledge_wait_timeout"),
+    ],
+)
+def test_wait_terminal_states_and_timeout(state, code):
+    from nullprotocol import KnowledgeError
+
+    api = KnowledgeAPI()
+    source = api.documents["space"]
+
+    def handler(request):
+        if request.url.path == "/v1/knowledge":
+            rows = (
+                [] if state == "missing" else [{**source, "state": state, "retryScheduled": False}]
+            )
+            return httpx.Response(200, json={"sources": rows})
+        return api(request)
+
+    with httpx.Client(transport=httpx.MockTransport(handler)) as http:
+        with NullProtocol(
+            key="fixture", endpoint="https://example.test", http_client=http
+        ) as client:
+            with pytest.raises(KnowledgeError) as error:
+                client.load("support").space.knowledge.wait_until_ready(source, timeout=0.02)
+            assert error.value.code == code
+
+
+def test_wait_async_cancellation_aborts_http_and_timeout_is_bounded():
+    from nullprotocol import KnowledgeError
+
+    async def run():
+        api = KnowledgeAPI()
+        entered = asyncio.Event()
+        cancelled = asyncio.Event()
+
+        async def handler(request):
+            if request.url.path.endswith("/knowledge"):
+                entered.set()
+                try:
+                    await asyncio.Event().wait()
+                finally:
+                    cancelled.set()
+            return api(request)
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+            async with AsyncNullProtocol(
+                key="fixture", endpoint="https://example.test", http_client=http
+            ) as client:
+                agent = await client.load("support")
+                task = asyncio.create_task(agent.knowledge.wait_until_ready(api.documents["agent"]))
+                await entered.wait()
+                task.cancel()
+                with pytest.raises(asyncio.CancelledError):
+                    await task
+                assert cancelled.is_set()
+                cancelled.clear()
+                with pytest.raises(KnowledgeError) as timeout:
+                    await agent.knowledge.wait_until_ready(api.documents["agent"], timeout=0.02)
+                assert timeout.value.code == "knowledge_wait_timeout"
+                assert cancelled.is_set()
+
+    asyncio.run(run())
+
+
+def test_wait_async_ready_and_busy_retry_respects_deadline():
+    from nullprotocol import KnowledgeError
+
+    async def run():
+        api = KnowledgeAPI()
+        source = api.documents["agent"]
+        source.update(state="ready", activeRevision=1)
+        busy = False
+        requests = 0
+
+        async def handler(request):
+            nonlocal requests
+            if busy and request.url.path.endswith("/knowledge"):
+                requests += 1
+                return httpx.Response(503, json={"error": "busy"})
+            return api(request)
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+            async with AsyncNullProtocol(
+                key="fixture", endpoint="https://example.test", http_client=http
+            ) as client:
+                agent = await client.load("support")
+                assert (await agent.knowledge.wait_until_ready(source))["activeRevision"] == 1
+                busy = True
+                with pytest.raises(KnowledgeError) as timeout:
+                    await agent.knowledge.wait_until_ready(source, timeout=0.02)
+                assert timeout.value.code == "knowledge_wait_timeout"
+                assert requests == 1
+
+    asyncio.run(run())

{nullprotocol-0.3.0 → nullprotocol-0.4.0}/tests/test_sdk.py

@@ -384,8 +384,9 @@ def test_decide_execute_schema_guard_snapshot_and_recording(api):
         )
         decision = agent.decide("Good morning", ["send_message"], knowledge=True)
         posted = json.loads(api.requests[-1].content)
-        assert posted["knowledge"] == {"query": "Good morning"}
-        assert posted["context"]["actionParameterSchemas"]["send_message"] == SCHEMA
+        assert posted["knowledge"] is True
+        assert posted["context"] == "Good morning"
+        assert posted["actions"][0]["parameters"] == SCHEMA
         decision.parameters["text"] = "tampered"
         outcome = agent.execute(decision)
         assert outcome.success and outcome.result == {"sent": True}
@@ -431,14 +432,13 @@ def test_execution_refusals_and_failures(api, mode, code):
         agent = c.load("support")
         if mode != "unregistered":
             agent.register_action("send_message", handler, input_schema=SCHEMA, guard=guard)
-        if mode == "schema":
-            api.result_override = {
-                "success": True,
-                "action": "send_message",
-                "parameters": {"wrong": 1},
-                "reasoning": "x",
-            }
         result = agent.decide("Hello", ["send_message"])
+        if mode == "schema":
+            agent.register_action(
+                "send_message",
+                handler,
+                input_schema={"type": "object", "required": ["new_required_field"]},
+            )
         if mode == "paused":
             api.settings["paused"] = True
         if mode == "disabled":
@@ -610,7 +610,8 @@ def test_action_format_validation_and_local_references(api):
             "parameters": {"date": "2026-02-29"},
             "reasoning": "x",
         }
-        assert agent.execute(agent.decide("x", ["send_message"])).error_code == "invalid_parameters"
+        with pytest.raises(ProtocolError, match="parameters"):
+            agent.decide("x", ["send_message"])
         api.result_override = {
             "success": True,
             "action": "send_message",
@@ -692,3 +693,32 @@ def test_nonfinite_or_missing_response_metadata_is_protocol_error(api):
         )
         with pytest.raises(ProtocolError):
             agent.extract("x", {})
+
+
+def test_context_null_and_key_errors_are_unambiguous(api):
+    with client(api) as c:
+        agent = c.load("support")
+        assert agent.context.set("order", None)["value"] is None
+        assert json.loads(api.requests[-1].content)["value"] is None
+        count = len(api.requests)
+        with pytest.raises(ValueError, match="lowercase"):
+            agent.context.set("privateProbe", {})
+        assert len(api.requests) == count
+
+
+def test_inline_parameter_contracts_stay_out_of_context_and_reject_bad_server_success(api):
+    with client(api) as c:
+        agent = c.load("support")
+        result = agent.decide("Hello", [{"action": "send_message", "parameters": SCHEMA}])
+        assert result.success
+        body = json.loads(api.requests[-1].content)
+        assert body["context"] == "Hello"
+        assert body["actions"][0]["parameters"] == SCHEMA
+        api.result_override = {
+            "success": True,
+            "action": "send_message",
+            "parameters": {"text": 42},
+            "reasoning": "test",
+        }
+        with pytest.raises(ProtocolError, match="parameters"):
+            agent.decide("Hello", [{"action": "send_message", "parameters": SCHEMA}])