pushary-crewai 0.1.0__tar.gz

pushary_crewai-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+.next/
+out/
+build/
+dist/
+
+# python
+__pycache__/
+*.pyc
+*.egg-info/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel
+
+# local Cursor MCP config (holds the Pushary API key)
+.cursor/mcp.json
+
+# generated at build time: Cursor plugin bundled into the agent-hooks package
+packages/agent-hooks/data/cursor-plugin/
+
+# typescript
+*.tsbuild info
+
+# turbo
+.turbo
+
+# Old Shopify extension directory (deprecated)
+shopify-theme-extension/
+*.egg-info/
+
+# Prospect/outreach data
+prospect_list.csv
+prospect_research_report.txt
+
+# Launch planning docs
+PRODUCTHUNT_LAUNCH_PLAN.md
+AI-CODING-REMODEL-PLAN.md
+
+# HyperFrames launch video (separate project)
+video-launch/
+
+# Remotion render outputs
+video/public/logos/out/
+.gstack/
+
+# local AI-agent tooling (installed skills + plugin config, machine-local)
+.agents/
+.claude/
+.cursor/rules/
+pushary-app/.agents/
+pushary-app/skills-lock.json
+
+# stray empty Expo stub at repo root (real config is pushary-app/app.config.ts)
+/app.json
+
+# Play Store listing assets (large, iterating screenshots - keep local)
+pushary-app/play-assets/

pushary_crewai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pushary_crewai-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: pushary-crewai
+Version: 0.1.0
+Summary: Human-in-the-loop for CrewAI: a BaseTool that asks a real human on their phone and blocks on a fail-closed answer, instead of the console human_input prompt.
+Project-URL: Homepage, https://pushary.com
+Project-URL: Documentation, https://pushary.com/docs/agents/adapters
+Author-email: Pushary <business@pushary.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,approvals,basetool,crewai,human-in-the-loop
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: crewai<2,>=1.0
+Requires-Dist: pushary>=1.3.2
+Description-Content-Type: text/markdown
+
+# pushary-crewai
+
+Human-in-the-loop for [CrewAI](https://www.crewai.com). Replace the console
+`human_input=True` prompt with a tool that reaches a real person on their phone and
+blocks until they answer, fail-closed.
+
+Requires the Pushary [Partner plan](https://pushary.com/agent-notifications-integration).
+
+## Install
+
+```bash
+pip install pushary-crewai
+```
+
+Set `PUSHARY_API_KEY` (get it in your [dashboard](https://pushary.com/dashboard/settings)).
+
+## Connect a phone once
+
+```python
+from pushary_crewai import connect
+
+link = connect("user_123")  # show this to your end-user; one tap connects their phone
+```
+
+## Give an agent an ask-human tool
+
+```python
+from crewai import Agent, Task, Crew
+from pushary_crewai import make_ask_human_tool
+
+agent = Agent(
+    role="Ops",
+    goal="Ship safely",
+    backstory="Careful operator.",
+    tools=[make_ask_human_tool("user_123")],
+)
+task = Task(
+    description="Draft the release. Before finalizing, call ask_human to get approval.",
+    expected_output="approved release notes",
+    agent=agent,
+)
+Crew(agents=[agent], tasks=[task]).kickoff()
+```
+
+The tool blocks until the person answers and returns a fail-closed instruction. The
+`external_id` is bound when you build the tool, never taken from the model, so a
+prompt-injected agent cannot ask the wrong person.
+
+## Lower-level helpers
+
+```python
+from pushary_crewai import ask_human
+
+d = ask_human("Approve this refund?", external_id="user_123", type="confirm")
+if d["approved"]:
+    issue_refund()
+```
+
+## API
+
+- `connect(external_id, *, api_key=None, base_url=None)` — enroll an end-user's phone.
+- `make_ask_human_tool(external_id, *, name=..., ...)` — a CrewAI `BaseTool` bound to that user.
+- `ask_human(question, *, external_id, type="confirm", ...)` — blocking, returns the decision dict.
+- `resolve_pushary_callback(raw_body, signature, secret)` — verify + parse a callback for a durable path.
+- `describe_answer(type, result)`, `is_affirmative(answer)`, `deterministic_key(parts)`, `SIGNATURE_HEADER`.
+
+## License
+
+MIT

pushary_crewai-0.1.0/README.md

@@ -0,0 +1,69 @@
+# pushary-crewai
+
+Human-in-the-loop for [CrewAI](https://www.crewai.com). Replace the console
+`human_input=True` prompt with a tool that reaches a real person on their phone and
+blocks until they answer, fail-closed.
+
+Requires the Pushary [Partner plan](https://pushary.com/agent-notifications-integration).
+
+## Install
+
+```bash
+pip install pushary-crewai
+```
+
+Set `PUSHARY_API_KEY` (get it in your [dashboard](https://pushary.com/dashboard/settings)).
+
+## Connect a phone once
+
+```python
+from pushary_crewai import connect
+
+link = connect("user_123")  # show this to your end-user; one tap connects their phone
+```
+
+## Give an agent an ask-human tool
+
+```python
+from crewai import Agent, Task, Crew
+from pushary_crewai import make_ask_human_tool
+
+agent = Agent(
+    role="Ops",
+    goal="Ship safely",
+    backstory="Careful operator.",
+    tools=[make_ask_human_tool("user_123")],
+)
+task = Task(
+    description="Draft the release. Before finalizing, call ask_human to get approval.",
+    expected_output="approved release notes",
+    agent=agent,
+)
+Crew(agents=[agent], tasks=[task]).kickoff()
+```
+
+The tool blocks until the person answers and returns a fail-closed instruction. The
+`external_id` is bound when you build the tool, never taken from the model, so a
+prompt-injected agent cannot ask the wrong person.
+
+## Lower-level helpers
+
+```python
+from pushary_crewai import ask_human
+
+d = ask_human("Approve this refund?", external_id="user_123", type="confirm")
+if d["approved"]:
+    issue_refund()
+```
+
+## API
+
+- `connect(external_id, *, api_key=None, base_url=None)` — enroll an end-user's phone.
+- `make_ask_human_tool(external_id, *, name=..., ...)` — a CrewAI `BaseTool` bound to that user.
+- `ask_human(question, *, external_id, type="confirm", ...)` — blocking, returns the decision dict.
+- `resolve_pushary_callback(raw_body, signature, secret)` — verify + parse a callback for a durable path.
+- `describe_answer(type, result)`, `is_affirmative(answer)`, `deterministic_key(parts)`, `SIGNATURE_HEADER`.
+
+## License
+
+MIT

pushary_crewai-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pushary-crewai"
+version = "0.1.0"
+description = "Human-in-the-loop for CrewAI: a BaseTool that asks a real human on their phone and blocks on a fail-closed answer, instead of the console human_input prompt."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Pushary", email = "business@pushary.com" }]
+keywords = [
+    "crewai",
+    "human-in-the-loop",
+    "ai-agents",
+    "approvals",
+    "basetool",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pushary>=1.3.2",
+    "crewai>=1.0,<2",
+]
+
+[project.urls]
+Homepage = "https://pushary.com"
+Documentation = "https://pushary.com/docs/agents/adapters"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pushary_crewai"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pushary_crewai",
+    "README.md",
+    "LICENSE",
+    "tests",
+]

pushary_crewai-0.1.0/src/pushary_crewai/__init__.py

@@ -0,0 +1,180 @@
+"""Human-in-the-loop for CrewAI, powered by Pushary.
+
+Replace CrewAI's console ``human_input=True`` prompt with a tool that reaches a real
+person on their phone. ``make_ask_human_tool`` returns a ``BaseTool`` you hand to an
+``Agent``; it blocks until the person answers and fails closed.
+
+Zero framework import at module load: CrewAI is imported lazily inside the tool
+factory, so the core helpers work (and test) without it installed.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+from pushary import (
+    PusharyServer,
+    SIGNATURE_HEADER,
+    deterministic_key,
+    is_approved,
+    parse_decision_callback,
+    verify_webhook_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "connect",
+    "ask_human",
+    "make_ask_human_tool",
+    "describe_answer",
+    "resolve_pushary_callback",
+    "is_affirmative",
+    "deterministic_key",
+    "SIGNATURE_HEADER",
+    "__version__",
+]
+
+_DEFAULT_DESCRIPTION = "Ask a real human to approve, choose, or answer. Blocks until they reply on their phone."
+
+
+def _client(api_key: Optional[str] = None, base_url: Optional[str] = None) -> PusharyServer:
+    key = api_key or os.environ.get("PUSHARY_API_KEY")
+    if not key:
+        raise ValueError("Pushary: set PUSHARY_API_KEY or pass api_key=... to the CrewAI helpers.")
+    return PusharyServer(api_key=key, base_url=base_url)
+
+
+def _idempotency_key(external_id: str, node: str, question: str) -> str:
+    return deterministic_key([external_id, node, question])
+
+
+def is_affirmative(answer: Optional[str]) -> bool:
+    """Fail-closed yes/no check for a confirm answer."""
+    return is_approved("answered", "confirm", answer)
+
+
+def connect(external_id: str, *, api_key: Optional[str] = None, base_url: Optional[str] = None) -> str:
+    """Connect one end-user's phone (keyless). Returns a single-use link to show them."""
+    return _client(api_key, base_url).enroll(external_id)["universalLink"]
+
+
+def ask_human(
+    question: str,
+    *,
+    external_id: str,
+    type: str = "confirm",
+    options: Optional[List[str]] = None,
+    node: str = "ask-human",
+    context: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    timeout_seconds: Optional[float] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Blocking ask: create a decision and poll durably until answered or the deadline.
+
+    Returns the decision dict with a fail-closed ``approved`` flag. Idempotency is
+    keyed by external_id + node + question.
+    """
+    return _client(api_key, base_url).decisions.ask(
+        question,
+        type=type,
+        options=options,
+        external_id=external_id,
+        context=context,
+        agent_name=agent_name,
+        timeout_seconds=timeout_seconds,
+        idempotency_key=_idempotency_key(external_id, node, question),
+    )
+
+
+def describe_answer(type: str, result: Dict[str, Any]) -> str:
+    """Turn a decision outcome into an unambiguous instruction for the agent."""
+    if not result.get("answered"):
+        return (
+            f"No answer (status: {result.get('status')}). "
+            "Treat this as NOT approved and do not proceed."
+        )
+    if type == "confirm":
+        return (
+            "The human approved. You may proceed."
+            if result.get("approved")
+            else "The human declined. Do not proceed."
+        )
+    return f"The human answered: {result.get('value') or ''}"
+
+
+def resolve_pushary_callback(
+    raw_body: Any, signature: Optional[str], secret: str
+) -> Optional[Dict[str, Any]]:
+    """Verify a callback signature and parse it, or return None."""
+    if not verify_webhook_signature(raw_body, signature, secret):
+        return None
+    cb = parse_decision_callback(raw_body)
+    if not cb:
+        return None
+    return {
+        "correlationId": cb.get("correlationId"),
+        "answer": cb.get("answer"),
+        "value": cb.get("value"),
+        "approved": is_affirmative(cb.get("answer")),
+        "context": cb.get("context"),
+        "answeredAt": cb.get("answeredAt"),
+    }
+
+
+def make_ask_human_tool(
+    external_id: str,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    name: str = "ask_human",
+    description: Optional[str] = None,
+    node: str = "ask-human",
+):
+    """Return a CrewAI ``BaseTool`` that asks ``external_id`` and blocks on their answer.
+
+    ``external_id`` is bound here, never taken from the model, so a prompt-injected
+    agent cannot redirect an approval to another user. Give the returned tool to an
+    ``Agent(tools=[...])`` and drop ``human_input=True``.
+
+    ```python
+    agent = Agent(role="Ops", goal="Ship safely", tools=[make_ask_human_tool("user_123")])
+    ```
+    """
+    # Lazy import so the module loads (and tests) without CrewAI installed.
+    from crewai.tools import BaseTool
+    from pydantic import BaseModel, Field
+    from typing import Type
+
+    tool_name = name or "ask_human"
+    tool_description = description or _DEFAULT_DESCRIPTION
+
+    class _AskHumanInput(BaseModel):
+        question: str = Field(..., description="The exact question to put to the human.")
+        type: str = Field(
+            "confirm",
+            description="confirm = yes/no, select = pick an option, input = free text.",
+        )
+
+    class AskHumanTool(BaseTool):
+        name: str = tool_name
+        description: str = tool_description
+        args_schema: Type[BaseModel] = _AskHumanInput
+
+        def _run(self, question: str, type: str = "confirm", **_: Any) -> str:
+            result = ask_human(
+                question,
+                external_id=external_id,
+                type=type,
+                node=node,
+                agent_name=agent_name,
+                api_key=api_key,
+                base_url=base_url,
+            )
+            return describe_answer(type, result)
+
+    return AskHumanTool()

pushary_crewai-0.1.0/tests/test_crewai.py

@@ -0,0 +1,108 @@
+"""Tests for pushary_crewai. Framework-free: CrewAI is never imported here (the tool
+factory imports it lazily), so the core helpers are exercised without it installed.
+"""
+
+import hashlib
+import hmac
+import json
+import unittest
+
+import pushary_crewai as pc
+
+
+class FakeDecisions:
+    def __init__(self, ask_result=None):
+        self.ask_calls = []
+        self._ask_result = ask_result or {}
+
+    def ask(self, question, **kwargs):
+        self.ask_calls.append({"question": question, **kwargs})
+        return self._ask_result
+
+
+class FakeClient:
+    def __init__(self, decisions=None, enroll_result=None):
+        self.decisions = decisions or FakeDecisions()
+        self._enroll_result = enroll_result or {}
+        self.enroll_calls = []
+
+    def enroll(self, external_id):
+        self.enroll_calls.append(external_id)
+        return self._enroll_result
+
+
+class WithFakeClient:
+    def __init__(self, client):
+        self.client = client
+        self._orig = None
+
+    def __enter__(self):
+        self._orig = pc._client
+        pc._client = lambda *a, **k: self.client
+        return self.client
+
+    def __exit__(self, *exc):
+        pc._client = self._orig
+
+
+SECRET = "whsec_test"
+
+
+def sign(body: str) -> str:
+    return hmac.new(SECRET.encode(), body.encode(), hashlib.sha256).hexdigest()
+
+
+class ConnectTests(unittest.TestCase):
+    def test_connect_returns_universal_link(self):
+        client = FakeClient(enroll_result={"universalLink": "https://pushary.com/e/tok"})
+        with WithFakeClient(client):
+            self.assertEqual(pc.connect("user_1"), "https://pushary.com/e/tok")
+
+
+class AskHumanTests(unittest.TestCase):
+    def test_ask_human_forwards_deterministic_key_and_returns_dict(self):
+        decisions = FakeDecisions(ask_result={"answered": True, "value": "yes", "approved": True})
+        with WithFakeClient(FakeClient(decisions=decisions)):
+            out = pc.ask_human("Approve?", external_id="user_1", node="gate")
+        self.assertTrue(out["approved"])
+        self.assertEqual(
+            decisions.ask_calls[0]["idempotency_key"],
+            pc.deterministic_key(["user_1", "gate", "Approve?"]),
+        )
+
+
+class MakeToolTests(unittest.TestCase):
+    def test_factory_lazily_imports_crewai(self):
+        # CrewAI is not installed in this env, so building the tool raises ImportError
+        # from the lazy import (proving the module itself loads without CrewAI).
+        with self.assertRaises(ImportError):
+            pc.make_ask_human_tool("user_1")
+
+
+class DescribeAnswerTests(unittest.TestCase):
+    def test_formats_every_outcome(self):
+        self.assertIn("approved", pc.describe_answer("confirm", {"answered": True, "approved": True}))
+        self.assertIn("declined", pc.describe_answer("confirm", {"answered": True, "approved": False}))
+        self.assertIn("NOT approved", pc.describe_answer("confirm", {"answered": False, "status": "expired"}))
+        self.assertIn("B", pc.describe_answer("select", {"answered": True, "value": "B"}))
+
+
+class ResolveCallbackTests(unittest.TestCase):
+    def test_verifies_and_folds_approved(self):
+        body = json.dumps({"correlationId": "d1", "answer": "yes", "answeredAt": ""})
+        self.assertTrue(pc.resolve_pushary_callback(body, sign(body), SECRET)["approved"])
+
+    def test_rejects_bad_signature(self):
+        body = json.dumps({"correlationId": "d1", "answer": "yes", "answeredAt": ""})
+        self.assertIsNone(pc.resolve_pushary_callback(body, "nope", SECRET))
+
+
+class IsAffirmativeTests(unittest.TestCase):
+    def test_fail_closed(self):
+        self.assertTrue(pc.is_affirmative("yes"))
+        self.assertFalse(pc.is_affirmative("no"))
+        self.assertFalse(pc.is_affirmative(None))
+
+
+if __name__ == "__main__":
+    unittest.main()