cred-openai-agents 0.1.0__tar.gz

cred_openai_agents-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+node_modules/
+dist/
+build/
+
+# Sprint artifacts
+.factory/
+.sprint-*
+.sprint-pid
+.rewire-done
+.content-rewrite-done
+.hubspot-done
+.integrations-done
+.done
+.validation-report.md
+.sprint-logs/
+.sprint-prompts/
+SESSION_PACKAGE.md
+run-sprint.sh
+validate.sh
+
+# Internal planning docs (not for public repo)
+CLAUDE.md
+PLAN.md
+HANDOFF.md
+VALIDATION.md
+MARKETING-VALIDATION.md
+FINAL-SUBMISSION-VALIDATION.md
+.next/
+out/
+coverage/
+*.tsbuildinfo
+.turbo/
+.DS_Store
+*.pem
+.env
+.env.local
+.env*.local
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+*.dist-info/
+packages/sdk-python/.venv/

cred_openai_agents-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: cred-openai-agents
+Version: 0.1.0
+Summary: Cred OpenAI Agents SDK integration — credential delegation FunctionTool
+Author-email: Cred <hello@cred.ninja>
+License: Apache-2.0
+Keywords: agents,ai-agents,cred,delegation,oauth,openai
+Requires-Python: >=3.9
+Requires-Dist: cred-auth>=0.1.0
+Requires-Dist: openai-agents>=0.1
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cred-openai-agents
+
+OpenAI Agents SDK integration for Cred. OAuth2 credential delegation for AI agents.
+
+## Install
+
+```bash
+pip install cred-openai-agents
+```
+
+## Quick Start
+
+```python
+import os
+from cred_openai_agents import cred_delegate_tool
+from agents import Agent
+
+tool = cred_delegate_tool(
+    agent_token=os.environ["CRED_AGENT_TOKEN"],
+    user_id="user_123",
+    app_client_id="my_app_client_id",
+)
+
+agent = Agent(
+    name="assistant",
+    tools=[tool],
+)
+```
+
+## Tool Schema
+
+The `cred_delegate` tool matches the Cred MCP tool spec:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `service` | `string` | Service slug (e.g. `google`, `github`) |
+| `scopes` | `string[]` | OAuth scopes to request |
+
+`user_id` and `app_client_id` are pre-configured at factory time, not agent-controlled.
+
+## Handling Consent
+
+When the user hasn't connected the service, the tool raises `ConsentRequiredError`.
+The error's `consent_url` attribute contains the URL to redirect the user.
+
+## Cred Cloud (Coming Soon)
+
+Managed cloud delegation is coming. [Join the waitlist](https://cred.ninja/waitlist).

cred_openai_agents-0.1.0/README.md

@@ -0,0 +1,48 @@
+# cred-openai-agents
+
+OpenAI Agents SDK integration for Cred. OAuth2 credential delegation for AI agents.
+
+## Install
+
+```bash
+pip install cred-openai-agents
+```
+
+## Quick Start
+
+```python
+import os
+from cred_openai_agents import cred_delegate_tool
+from agents import Agent
+
+tool = cred_delegate_tool(
+    agent_token=os.environ["CRED_AGENT_TOKEN"],
+    user_id="user_123",
+    app_client_id="my_app_client_id",
+)
+
+agent = Agent(
+    name="assistant",
+    tools=[tool],
+)
+```
+
+## Tool Schema
+
+The `cred_delegate` tool matches the Cred MCP tool spec:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `service` | `string` | Service slug (e.g. `google`, `github`) |
+| `scopes` | `string[]` | OAuth scopes to request |
+
+`user_id` and `app_client_id` are pre-configured at factory time, not agent-controlled.
+
+## Handling Consent
+
+When the user hasn't connected the service, the tool raises `ConsentRequiredError`.
+The error's `consent_url` attribute contains the URL to redirect the user.
+
+## Cred Cloud (Coming Soon)
+
+Managed cloud delegation is coming. [Join the waitlist](https://cred.ninja/waitlist).

cred_openai_agents-0.1.0/cred_openai_agents/__init__.py

@@ -0,0 +1,7 @@
+"""Cred OpenAI Agents SDK integration."""
+
+from .tool import cred_delegate_tool
+
+CredTool = cred_delegate_tool
+
+__all__ = ["cred_delegate_tool", "CredTool"]

cred_openai_agents-0.1.0/cred_openai_agents/tool.py

@@ -0,0 +1,125 @@
+"""Cred OpenAI Agents SDK integration.
+
+Returns a FunctionTool that agents can call to get delegated OAuth tokens.
+The tool schema matches the Cred MCP tool spec (Move 5):
+
+    name:   cred_delegate
+    params: { service: str, scopes: list[str] | None }
+
+user_id and app_client_id are pre-configured at factory time — they come from
+the authenticated user context and are not agent-controlled inputs.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Optional
+
+from agents import FunctionTool, RunContextWrapper
+
+from cred import Cred
+from cred.exceptions import ConsentRequiredError
+
+# JSON schema for the tool's input parameters
+_PARAMS_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "service": {
+            "type": "string",
+            "description": (
+                "Service slug to get a token for "
+                "(e.g. 'google', 'github', 'google-calendar')."
+            ),
+        },
+        "scopes": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": (
+                "OAuth scopes to request (e.g. ['calendar.readonly']). "
+                "Pass an empty list to use all consented scopes."
+            ),
+        },
+    },
+    "required": ["service", "scopes"],
+    "additionalProperties": False,
+}
+
+
+def cred_delegate_tool(
+    agent_token: str,
+    user_id: str,
+    app_client_id: str,
+    base_url: str = "https://api.cred.ninja",
+) -> FunctionTool:
+    """Create an OpenAI Agents SDK FunctionTool for credential delegation.
+
+    The returned tool is pre-configured with the user's identity and app context.
+    At runtime, the agent supplies ``service`` and ``scopes``.
+
+    Args:
+        agent_token:    Agent token issued by Cred (starts with ``cred_at_``).
+        user_id:        The user whose credentials to delegate.
+        app_client_id:  The Cred app client ID to delegate for.
+        base_url:       Override the API base URL.
+
+    Returns:
+        A ``FunctionTool`` ready to pass to ``Agent(tools=[...])``.
+
+    Raises:
+        ConsentRequiredError: (from the tool at runtime) when the user hasn't
+            connected the requested service. The error message includes
+            ``consent_url`` so the caller can redirect the user.
+
+    Example::
+
+        from cred_openai_agents import cred_delegate_tool
+        from agents import Agent
+
+        tool = cred_delegate_tool(
+            agent_token=os.environ["CRED_AGENT_TOKEN"],
+            user_id="user_123",
+            app_client_id="my_app",
+        )
+        agent = Agent(name="assistant", tools=[tool])
+    """
+    cred = Cred(agent_token=agent_token, base_url=base_url)
+
+    async def on_invoke_tool(
+        ctx: RunContextWrapper[Any],
+        args_json: str,
+    ) -> str:
+        args: dict[str, Any] = json.loads(args_json)
+        service: str = args["service"]
+        scopes: Optional[list[str]] = args.get("scopes") or None
+
+        # Cred SDK is sync — run in thread pool to avoid blocking event loop
+        result = await asyncio.to_thread(
+            cred.delegate,
+            service=service,
+            user_id=user_id,
+            app_client_id=app_client_id,
+            scopes=scopes,
+        )
+
+        return json.dumps({
+            "access_token": result.access_token,
+            "token_type": result.token_type,
+            "expires_in": result.expires_in,
+            "service": result.service,
+            "scopes": result.scopes,
+            "delegation_id": result.delegation_id,
+        })
+
+    return FunctionTool(
+        name="cred_delegate",
+        description=(
+            "Get a delegated OAuth access token for a third-party service "
+            "on behalf of the current user. "
+            "Returns access_token, token_type, expires_in, service, and scopes. "
+            "Raises an error with consent_url if the user hasn't connected the service."
+        ),
+        params_json_schema=_PARAMS_SCHEMA,
+        on_invoke_tool=on_invoke_tool,
+        strict_json_schema=False,  # allow scopes to be omitted at agent discretion
+    )

cred_openai_agents-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cred-openai-agents"
+version = "0.1.0"
+description = "Cred OpenAI Agents SDK integration — credential delegation FunctionTool"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+authors = [{ name = "Cred", email = "hello@cred.ninja" }]
+keywords = ["cred", "openai", "agents", "oauth", "delegation", "ai-agents"]
+dependencies = [
+    "cred-auth>=0.1.0",
+    "openai-agents>=0.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "hatchling"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cred_openai_agents"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cred_openai_agents-0.1.0/tests/test_tool.py

@@ -0,0 +1,221 @@
+"""Cred OpenAI Agents SDK integration tests.
+
+Tests focus on: FunctionTool shape, async invocation, output JSON,
+and error propagation. The Cred client is mocked — no real HTTP.
+"""
+
+import asyncio
+import json
+from datetime import datetime, timezone
+from typing import Optional
+import pytest
+import httpx
+from unittest.mock import MagicMock, patch
+
+from agents import FunctionTool
+
+from cred import DelegationResult, ConsentRequiredError, CredError
+from cred_openai_agents import cred_delegate_tool, CredTool
+
+TOKEN = "cred_at_test"
+USER_ID = "user_123"
+APP_CLIENT_ID = "app_1"
+
+
+def make_delegation_result(
+    *,
+    access_token: str = "at",
+    token_type: str = "Bearer",
+    expires_in: int = 3600,
+    service: str = "google",
+    scopes: Optional[list[str]] = None,
+    delegation_id: str = "del_1",
+) -> DelegationResult:
+    return DelegationResult(
+        access_token=access_token,
+        token_type=token_type,
+        expires_in=expires_in,
+        expires_at=datetime(2026, 3, 1, tzinfo=timezone.utc),
+        service=service,
+        scopes=scopes or [],
+        delegation_id=delegation_id,
+    )
+
+
+@pytest.fixture
+def mock_cred():
+    return MagicMock()
+
+
+@pytest.fixture
+def tool(mock_cred):
+    with patch("cred_openai_agents.tool.Cred", return_value=mock_cred):
+        return cred_delegate_tool(
+            agent_token=TOKEN,
+            user_id=USER_ID,
+            app_client_id=APP_CLIENT_ID,
+        )
+
+
+def run(coro):
+    """Run a coroutine synchronously (test helper)."""
+    return asyncio.run(coro)
+
+
+# ── factory function ──────────────────────────────────────────────────────────
+
+class TestFactory:
+    def test_returns_function_tool(self):
+        with patch("cred_openai_agents.tool.Cred"):
+            t = cred_delegate_tool(
+                agent_token=TOKEN,
+                user_id=USER_ID,
+                app_client_id=APP_CLIENT_ID,
+            )
+        assert isinstance(t, FunctionTool)
+
+    def test_tool_name_is_cred_delegate(self, tool):
+        assert tool.name == "cred_delegate"
+
+    def test_tool_description_mentions_oauth(self, tool):
+        assert "access token" in tool.description.lower()
+        assert "service" in tool.description.lower()
+
+    def test_params_schema_has_service_and_scopes(self, tool):
+        props = tool.params_json_schema["properties"]
+        assert "service" in props
+        assert "scopes" in props
+
+    def test_service_is_required(self, tool):
+        assert "service" in tool.params_json_schema.get("required", [])
+
+    def test_creates_cred_client_with_token_and_base_url(self):
+        with patch("cred_openai_agents.tool.Cred") as mock_cred_class:
+            cred_delegate_tool(
+                agent_token=TOKEN,
+                user_id=USER_ID,
+                app_client_id=APP_CLIENT_ID,
+                base_url="http://localhost:3001",
+            )
+            mock_cred_class.assert_called_once_with(
+                agent_token=TOKEN,
+                base_url="http://localhost:3001",
+            )
+
+    def test_exports_cred_tool_alias(self):
+        assert CredTool is cred_delegate_tool
+
+
+# ── on_invoke_tool ────────────────────────────────────────────────────────────
+
+class TestInvoke:
+    def test_returns_json_with_access_token(self, tool, mock_cred):
+        mock_cred.delegate.return_value = make_delegation_result(
+            access_token="ya29.mock",
+            expires_in=3600,
+            service="google",
+            scopes=["calendar.readonly"],
+            delegation_id="del_abc",
+        )
+
+        args_json = json.dumps({"service": "google", "scopes": ["calendar.readonly"]})
+        result_str = run(tool.on_invoke_tool(MagicMock(), args_json))
+        result = json.loads(result_str)
+
+        assert result["access_token"] == "ya29.mock"
+        assert result["token_type"] == "Bearer"
+        assert result["expires_in"] == 3600
+        assert result["service"] == "google"
+        assert result["scopes"] == ["calendar.readonly"]
+        assert result["delegation_id"] == "del_abc"
+
+    def test_passes_service_user_app_to_cred(self, tool, mock_cred):
+        mock_cred.delegate.return_value = make_delegation_result(service="github")
+
+        args_json = json.dumps({"service": "github", "scopes": ["repo"]})
+        run(tool.on_invoke_tool(MagicMock(), args_json))
+
+        mock_cred.delegate.assert_called_once_with(
+            service="github",
+            user_id=USER_ID,
+            app_client_id=APP_CLIENT_ID,
+            scopes=["repo"],
+        )
+
+    def test_passes_none_scopes_when_empty_list(self, tool, mock_cred):
+        mock_cred.delegate.return_value = make_delegation_result()
+
+        args_json = json.dumps({"service": "google", "scopes": []})
+        run(tool.on_invoke_tool(MagicMock(), args_json))
+
+        call_kwargs = mock_cred.delegate.call_args.kwargs
+        assert call_kwargs["scopes"] is None
+
+    def test_propagates_consent_required_error(self, tool, mock_cred):
+        mock_cred.delegate.side_effect = ConsentRequiredError(
+            "User has not consented",
+            "https://api.cred.ninja/api/connect/google/authorize?app_client_id=app_1",
+        )
+
+        args_json = json.dumps({"service": "google", "scopes": ["calendar.readonly"]})
+
+        with pytest.raises(ConsentRequiredError) as exc_info:
+            run(tool.on_invoke_tool(MagicMock(), args_json))
+
+        assert "/api/connect/google/authorize" in exc_info.value.consent_url
+
+    def test_propagates_cred_error_on_401(self, tool, mock_cred):
+        mock_cred.delegate.side_effect = CredError(
+            "Invalid agent token", "unauthorized", 401
+        )
+
+        args_json = json.dumps({"service": "google", "scopes": []})
+
+        with pytest.raises(CredError) as exc_info:
+            run(tool.on_invoke_tool(MagicMock(), args_json))
+
+        assert exc_info.value.status_code == 401
+
+    def test_runs_sync_cred_in_thread(self, tool, mock_cred):
+        """Verifies the handler doesn't block the event loop (delegate is sync)."""
+        call_count = 0
+
+        def sync_delegate(**kwargs):
+            nonlocal call_count
+            call_count += 1
+            return make_delegation_result()
+
+        mock_cred.delegate.side_effect = sync_delegate
+
+        args_json = json.dumps({"service": "google", "scopes": []})
+        run(tool.on_invoke_tool(MagicMock(), args_json))
+
+        assert call_count == 1
+
+    def test_real_cred_client_delegates_against_mock_server(self):
+        tool = cred_delegate_tool(
+            agent_token=TOKEN,
+            user_id=USER_ID,
+            app_client_id=APP_CLIENT_ID,
+            base_url="https://cred.example.com",
+        )
+
+        with patch("httpx.Client.request", return_value=httpx.Response(
+            200,
+            json={
+                "access_token": "ya29.real",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "service": "google",
+                "scopes": ["calendar.readonly"],
+                "delegation_id": "del_real",
+            },
+        )) as request_mock:
+            result_str = run(tool.on_invoke_tool(MagicMock(), json.dumps({
+                "service": "google",
+                "scopes": ["calendar.readonly"],
+            })))
+
+        payload = json.loads(result_str)
+        assert payload["access_token"] == "ya29.real"
+        assert request_mock.called