Release 3.0.1

Author: mykolademyanov

examples/README.md

@@ -288,7 +288,7 @@ This agent CANNOT call:
   ✗ stripe.charge
   ✗ delete_user
 
-If the agent tries to call a blocked tool, the API will return a 403.
+If the agent tries to call a blocked tool via `ai.run_tool`, you'll get `allowed=False` with a `policy_reason`.
 ```
 
 **When to use:**
@@ -917,7 +917,7 @@ max_spend_usd_per_day = 500.00
 ## 📚 Additional Resources
 
 - **Main README:** [`../README.md`](../README.md)
-- **API Docs:** https://docs.onceonly.tech/api
+- **API Docs:** https://docs.onceonly.tech/reference/idempotency/
 - **SDK Reference:** https://docs.onceonly.tech/sdk/python
 - **Dashboard:** https://onceonly.tech/dashboard
 - **Governance Guide:** https://docs.onceonly.tech/governance
@@ -932,7 +932,7 @@ max_spend_usd_per_day = 500.00
 | 200 | — | Success | ✅ Proceed |
 | 401 | `UnauthorizedError` | Invalid API key | Check `ONCEONLY_API_KEY` |
 | 402 | `OverLimitError` | Usage/budget limit | Upgrade plan or increase budget |
-| 403 | `PolicyBlockedError` | Agent blocked by policy | Check governance logs |
+| 403 | `ApiError` | Forbidden / feature gating | Check plan + `error=feature_not_available` |
 | 422 | `ValidationError` | Bad request | Fix parameters |
 | 429 | `RateLimitError` | Rate limit | Enable retries |
 | 500+ | `ApiError` | Server error | Retry or fail-open |

examples/ai/agent_full_flow_no_onceonly.py

@@ -12,7 +12,7 @@
 import os
 import random
 import time
-import requests
+import httpx
 
 LLM_API_KEY = os.getenv("LLM_API_KEY")
 TOOL_ENDPOINT = os.getenv("TOOL_ENDPOINT", "https://example.com/tools/charge")
@@ -23,9 +23,10 @@ def llm_decide() -> dict:
 
 def call_tool(payload: dict) -> dict:
     # No idempotency key. A retry repeats the charge.
-    resp = requests.post(TOOL_ENDPOINT, json=payload, timeout=10)
-    resp.raise_for_status()
-    return resp.json()
+    with httpx.Client(timeout=10.0) as c:
+        resp = c.post(TOOL_ENDPOINT, json=payload)
+        resp.raise_for_status()
+        return resp.json()
 
 def main() -> None:
     decision = llm_decide()

examples/ai/governance.py

@@ -47,7 +47,7 @@
 st1 = client.gov.disable_agent(agent_id, reason="Manual safety stop (example)")
 print("Status after disable:", st1)
 
-print("Agent disabled. All tool calls should now return 403 until enabled.")
+print("Agent disabled. Tool calls should now be blocked (ai.run_tool -> allowed=False) until enabled.")
 
 print("Re-enabling agent...")
 st2 = client.gov.enable_agent(agent_id, reason="Resume operations (example)")

examples/ai/tool_permissions.py

@@ -27,7 +27,7 @@
 print("  ✗ stripe.charge")
 print("  ✗ delete_user")
 
-print("\nIf the agent tries to call a blocked tool, the API will return a 403.")
+print("\nIf the agent tries to call a blocked tool via ai.run_tool(), you'll get allowed=False with a policy_reason.")
 
 # Optional: execute a tool (requires the tool to be registered in your account)
 # res = client.ai.run_tool(

onceonly/_http.py

@@ -42,7 +42,18 @@ def _parse_retry_after(resp: httpx.Response) -> Optional[float]:
 
 def parse_json_or_raise(resp: httpx.Response) -> Dict[str, Any]:
     # typed errors
-    if resp.status_code in (401, 403):
+    if resp.status_code == 401:
+        raise UnauthorizedError(error_text(resp, "Invalid API Key (Unauthorized)."))
+
+    if resp.status_code == 403:
+        d = try_extract_detail(resp)
+        # Backend uses 403 both for invalid/disabled API keys and for feature gating.
+        if isinstance(d, dict) and d.get("error") == "feature_not_available":
+            raise ApiError(
+                error_text(resp, "Feature not available for this plan."),
+                status_code=403,
+                detail=d,
+            )
         raise UnauthorizedError(error_text(resp, "Invalid API Key (Unauthorized)."))
 
     if resp.status_code == 402:

onceonly/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from urllib.parse import urlparse
 from typing import Optional, Dict, Any
 
 import httpx
@@ -52,7 +53,16 @@ def __init__(
         async_transport: Optional[httpx.AsyncBaseTransport] = None,
     ):
         self.api_key = api_key
-        self.base_url = base_url.rstrip("/")
+        base_url = base_url.rstrip("/")
+        # Accept both "https://api.onceonly.tech" and ".../v1" (and keep custom paths intact).
+        try:
+            p = urlparse(base_url)
+            if (p.path or "") in ("", "/"):
+                base_url = base_url + "/v1"
+        except Exception:
+            pass
+
+        self.base_url = base_url
         self.timeout = timeout
         self.fail_open = fail_open