pushary 2.2.0__tar.gz → 2.3.0__tar.gz

{pushary-2.2.0 → pushary-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pushary
-Version: 2.2.0
+Version: 2.3.0
 Summary: The decision layer for AI agents. Your agent asks, your user decides on their phone.
 Project-URL: Homepage, https://pushary.com
 Project-URL: Documentation, https://pushary.com/docs
@@ -291,3 +291,8 @@ These keys intentionally differ from 2.0. Do not replay completed operations dur
 ### Upgrading to 2.2
 
 `ApprovalAsk` accepts `context`. The shared approval gate sends it with the decision, so the approver can read what the notification cannot fit, such as a tool's full arguments. Context is part of the approval identity when set. An ask without context keeps the key it had in 2.1, so pending approvals carry over.
+## Personal reminders
+
+On an active Agent workspace, `client.reminders.schedule("Check the deploy", in_minutes=30)` saves a one-time reminder that survives the agent exiting. Use `at` with an explicit UTC offset for calendar times, up to 30 days away. `client.reminders.list()` lists your pending reminders; `client.reminders.cancel(reminder_id)` cancels one before dispatch starts. Confirm the returned `reminder.fireAt`. Delivery requires a connected phone and can be about a minute late. These personal reminders do not schedule agent work or Partner customer campaigns.
+
+Personal reminder bodies must fit 180 UTF-16 units after secret redaction (most emoji use two); titles must fit 100. Oversized text is rejected. Listing and cancelling accepted reminders remain available when billing access closes.

{pushary-2.2.0 → pushary-2.3.0}/README.md

@@ -263,3 +263,8 @@ These keys intentionally differ from 2.0. Do not replay completed operations dur
 ### Upgrading to 2.2
 
 `ApprovalAsk` accepts `context`. The shared approval gate sends it with the decision, so the approver can read what the notification cannot fit, such as a tool's full arguments. Context is part of the approval identity when set. An ask without context keeps the key it had in 2.1, so pending approvals carry over.
+## Personal reminders
+
+On an active Agent workspace, `client.reminders.schedule("Check the deploy", in_minutes=30)` saves a one-time reminder that survives the agent exiting. Use `at` with an explicit UTC offset for calendar times, up to 30 days away. `client.reminders.list()` lists your pending reminders; `client.reminders.cancel(reminder_id)` cancels one before dispatch starts. Confirm the returned `reminder.fireAt`. Delivery requires a connected phone and can be about a minute late. These personal reminders do not schedule agent work or Partner customer campaigns.
+
+Personal reminder bodies must fit 180 UTF-16 units after secret redaction (most emoji use two); titles must fit 100. Oversized text is rejected. Listing and cancelling accepted reminders remain available when billing access closes.

{pushary-2.2.0 → pushary-2.3.0}/examples/dify/README.md

@@ -83,14 +83,20 @@ export DIFY_NODE_ID='review'
 second workflow. A pending result is reported as `blocked` with the SDK's reason.
 After approval, the result contains the released local order. Inspect `orders.db`
 inside the state directory: the business idempotency key is unique. Re-running
-`resume` after submission stops because the native form is already closed.
+`resume` after a committed order returns that order with `"recovered": true`, using
+read-only backend evidence even when the native form is closed or approval has expired.
+This reports an existing effect; it does not authorize another one.
 
 For your backend, import `start` and `resume` from [review.py](review.py). Supply
 tenant/customer IDs and the action from authenticated application state, never
 model output. The CLI's `demo-store` tenant and test order are demonstration data.
 Pass your business callback to `resume`; it receives a copy of the exact approved
 parameters and a stable idempotency key. Your downstream service must also enforce
-that key if it can retry internally.
+that key if it can retry internally. Optionally supply a trusted, read-only `lookup`
+callback with the same arguments: return the verified committed result, return `None`
+when completion is unconfirmed, or raise when evidence is unavailable or contradictory.
+Without `lookup`, the original stop-and-reconcile behavior is unchanged. Never use a
+Dify success flag, approval answer, or worker-local success cache as backend evidence.
 
 ## Trust and recovery limits
 
@@ -107,14 +113,57 @@ that key if it can retry internally.
   the one-hour Pushary request; both deadlines are checked before the effect.
 - The SDK consumes the remote one-use permit **before** native submission. Dify
   also makes forms one-shot. A lost submission response, native resume taking over
-  30 seconds, worker crash or uncertain business result needs operator reconciliation.
-  The spent permit is not reset and the effect is not automatically retried.
+  30 seconds, worker crash or uncertain business result needs reconciliation.
+  The SQLite demo automatically reads back a committed order and its matching backend
+  receipt. Without that evidence it stops for operator reconciliation. The spent
+  permit is not reset and the effect is not automatically retried.
 - If initial workflow creation fails before the pause is saved, inspect Dify's run
   logs. Do not delete the state directory and blindly start another operation.
 - Dify workspace administrators and anyone who controls your backend remain trusted.
   This example does not intercept arbitrary agent tools or secure a separate effect
   placed directly in Dify.
 
+## Recovery evidence and interruption checkpoints
+
+The demo's backend is `orders.db`, separate from Dify and the Pushary permit service.
+`release_order` commits the order and a receipt containing **all** approved parameters
+under the same binding in one SQLite transaction. `lookup_order` opens that database
+read-only and reads both rows in one snapshot. Both must match before it reports
+`released`; a missing row, mismatched parameters, corrupt database or legacy schema
+cannot become recovered success. Existing databases without the new receipt table
+require manual reconciliation; do not delete them to force a fresh execution.
+
+The binding includes tenant, customer, native run, workflow version, form, parameters
+and deadline. Caller identity and saved operation integrity are checked before lookup.
+Only the permit-protected callback writes orders. Lookup never submits a form, consumes
+a permit, executes an effect or changes a receipt. A late callback exception triggers
+another readback before the SDK reports an outcome. Verified completion therefore
+survives that exception. There is no mutable local completion status for an older
+worker to overwrite; the committed order and receipt remain the source of truth.
+
+| Interruption | Backend evidence | Restart outcome | New effect |
+| --- | --- | --- | --- |
+| Permit consumed, response lost | No order | Blocked/unconfirmed permit | None |
+| Native form committed, response lost | No order | Stop for reconciliation | None |
+| Worker dies before backend effect | No order | Stop for reconciliation | None |
+| Order and receipt commit, worker dies before returning | Matching order and receipt | `released`, `recovered: true` | None |
+| Worker B verifies completion before worker A's delayed exception | Matching order and receipt | B recovers; A reads back success; subsequent resumes recover | None |
+| SDK receipt reporting is unavailable | Matching order and receipt | Backend success remains recoverable | None |
+| Backend evidence is missing, inconsistent or unreadable | Unverified | Stop; never invent success | None |
+
+The backend receipt is distinct from Pushary's hosted execution receipt. A process
+killed before SDK reporting can leave the hosted permit marked running; this example
+**does not repair that hosted receipt** or claim that its status proves the business
+outcome. After a recoverable delayed callback exception, the still-running worker can
+report SDK success normally. An operator must reconcile a receipt left by a dead worker.
+
+This is a local synthetic comparison with [Mission's proposed checkpoint](https://github.com/langgenius/dify/discussions/42319#discussioncomment-18625206): backend
+commit → lost worker response → fresh-process lookup. It is not a Mission integration,
+a distributed exactly-once guarantee, or proof of live Dify/phone-service recovery.
+For a remote backend, implement lookup using that provider's authoritative operation
+identifier, exact subject and durable committed evidence; an absent lookup result alone
+must never authorize resending an uncertain operation.
+
 ## Verification
 
 ```bash
@@ -126,9 +175,14 @@ The checks use Dify's **real Graphon 0.7.0** Human Input node, graph engine and
 serialized runtime snapshots, plus the published Pushary SDK. They run fresh
 processes across pause/resume and cover pending, approval, denial, expiry,
 cancellation, customer/version/parameter changes, duplicate workers, a competing
-native submitter, lost permit/submission responses and a crash after the effect.
-
-Both hosted HTTP services and the order service are simulated in these checks.
+native submitter, lost permit/submission responses and crashes before/after the effect.
+They use the actual SQLite order writer and readback, compare restart with and without
+lookup, assert one order and one matching receipt, and exercise worker B's recovery
+before worker A's delayed error. They also reject corrupt, incomplete, legacy and
+mismatched evidence and verify readback after approval expiry.
+
+Both hosted HTTP services are simulated; the test backend uses real local SQLite
+transactions and the demo's order writer/readback.
 Dify Cloud import and a Studio pause → approve → resume smoke test were also
 verified on 2026-09-15. The automated checks do **not** prove its database/Celery
 delivery or live phone delivery. Run the test-phone procedure above against your deployment

{pushary-2.2.0 → pushary-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pushary"
-version = "2.2.0"
+version = "2.3.0"
 description = "The decision layer for AI agents. Your agent asks, your user decides on their phone."
 readme = "README.md"
 requires-python = ">=3.9"

{pushary-2.2.0 → pushary-2.3.0}/src/pushary/__init__.py

@@ -19,15 +19,17 @@ from ._util import deterministic_key, is_approved
 from .client import PusharyServer
 from .decisions import DecisionsResource
 from .keys import KeysResource
+from .reminders import RemindersResource
 from .errors import PusharyError
 from .webhook import SIGNATURE_HEADER, parse_decision_callback, verify_webhook_signature
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 __all__ = [
     "PusharyServer",
     "DecisionsResource",
     "KeysResource",
+    "RemindersResource",
     "PusharyError",
     "verify_webhook_signature",
     "parse_decision_callback",

{pushary-2.2.0 → pushary-2.3.0}/src/pushary/client.py

@@ -15,6 +15,7 @@ from urllib.parse import quote, urlencode
 
 from .decisions import DecisionsResource
 from .keys import KeysResource
+from .reminders import RemindersResource
 from .errors import PusharyError
 
 DEFAULT_BASE_URL = "https://pushary.com/api/v1/server"
@@ -24,14 +25,14 @@ DEFAULT_BASE_URL = "https://pushary.com/api/v1/server"
 # little above it to leave room for the round trip without hanging forever.
 DEFAULT_TIMEOUT_SECONDS = 65.0
 
-_SETTINGS_URL = "https://pushary.com/dashboard/settings"
+_SETTINGS_URL = "https://pushary.com/dashboard/agent/settings"
 
 
 class PusharyServer:
     """Client for the Pushary human-in-the-loop decisions API.
 
     Args:
-        api_key: The full API key in the form ``pk_xxx.sk_xxx``.
+        api_key: The full API key in the form ``pk_xxx.xxx``.
         base_url: Override the API base URL. Defaults to the public endpoint.
 
     Raises:
@@ -49,6 +50,7 @@ class PusharyServer:
         self._timeout = DEFAULT_TIMEOUT_SECONDS
         self.decisions = DecisionsResource(self._request)
         self.keys = KeysResource(self._request)
+        self.reminders = RemindersResource(self._request)
 
     def evaluate_authorization(
         self,
@@ -244,7 +246,7 @@ class PusharyServer:
             )
         if "." not in api_key:
             raise ValueError(
-                "Invalid API key format. Use the full API key (pk_xxx.sk_xxx). "
+                "Invalid API key format. Use the full API key (pk_xxx.xxx). "
                 f"Get your API key from {_SETTINGS_URL}"
             )
 

{pushary-2.2.0 → pushary-2.3.0}/src/pushary/keys.py

@@ -3,8 +3,10 @@
 For multi-tenant Partners. Call ``issue`` from your backend with your own
 (unbound, Partner-plan) key to mint a child key bound to a single end-user, hand
 that key to the agent runtime acting for that user, then ``revoke`` it when the
-session ends. A bound key can only create/resolve decisions and enroll that exact
-end-user, so a prompt-injected agent can never reach another of your users.
+session ends. A bound key can only create, read and cancel decisions for that
+exact end-user, so a prompt-injected agent can never reach another of your users.
+It cannot enroll devices or answer a decision; use your server-side full-access
+key for those operations.
 """
 
 from __future__ import annotations

pushary-2.3.0/src/pushary/reminders.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import Callable, Dict, Optional
+
+RequestFn = Callable[..., Dict[str, object]]
+
+
+class RemindersResource:
+    def __init__(self, request: RequestFn) -> None:
+        self._request = request
+
+    def schedule(
+        self, body: str, *, in_minutes: Optional[int] = None, at: Optional[str] = None,
+        title: Optional[str] = None, agent_name: Optional[str] = None,
+        session_id: Optional[str] = None, machine_id: Optional[str] = None,
+        env: Optional[str] = None,
+    ) -> Dict[str, object]:
+        values = {"body": body, "inMinutes": in_minutes, "at": at, "title": title,
+                  "agentName": agent_name, "sessionId": session_id, "machineId": machine_id, "env": env}
+        return self._request("POST", "/reminders", body={key: value for key, value in values.items() if value is not None})
+
+    def list(self) -> Dict[str, object]:
+        return self._request("GET", "/reminders")
+
+    def cancel(self, reminder_id: str) -> Dict[str, object]:
+        return self._request("POST", "/reminders", body={"cancelReminderId": reminder_id})

{pushary-2.2.0 → pushary-2.3.0}/tests/test_client.py

@@ -38,12 +38,12 @@ class ApiKeyValidationTests(unittest.TestCase):
     def test_empty_key_raises_value_error(self):
         with self.assertRaises(ValueError) as ctx:
             PusharyServer(api_key="")
-        self.assertIn("dashboard/settings", str(ctx.exception))
+        self.assertIn("dashboard/agent/settings", str(ctx.exception))
 
     def test_key_without_dot_raises_value_error(self):
         with self.assertRaises(ValueError) as ctx:
             PusharyServer(api_key="pk_live_only")
-        self.assertIn("pk_xxx.sk_xxx", str(ctx.exception))
+        self.assertIn("pk_xxx.xxx", str(ctx.exception))
 
     def test_valid_key_constructs(self):
         client = PusharyServer(api_key=VALID_KEY)

pushary-2.3.0/tests/test_reminders.py

@@ -0,0 +1,17 @@
+import unittest
+from unittest import mock
+from pushary import PusharyServer
+
+
+class ReminderTests(unittest.TestCase):
+    def test_schedule_list_and_cancel_use_authenticated_reminder_resource(self):
+        with mock.patch.object(PusharyServer, '_request', return_value={'pending': []}) as request:
+            client = PusharyServer('pk_test.secret')
+            client.reminders.schedule('Check deploy', in_minutes=30)
+            client.reminders.list()
+            client.reminders.cancel('id')
+        self.assertEqual(request.call_args_list, [
+            mock.call('POST', '/reminders', body={'body': 'Check deploy', 'inMinutes': 30}),
+            mock.call('GET', '/reminders'),
+            mock.call('POST', '/reminders', body={'cancelReminderId': 'id'}),
+        ])