optimizely-opal.opal-tools-sdk 0.1.40.dev0__tar.gz → 0.1.42.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.40.dev0 → optimizely_opal_opal_tools_sdk-0.1.42.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.40.dev0
+Version: 0.1.42.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

optimizely_opal_opal_tools_sdk-0.1.42.dev0/opal_tools_sdk/__init__.py

@@ -0,0 +1,82 @@
+from .auth import EpiHmac, requires_auth
+from .config import SdkConfig
+from .context import ToolExecutionContext
+from .decorators import interaction, resource, rollback, tool
+from .logging import register_logger_factory
+from .models import (
+    AuthData,
+    AuthRequirement,
+    Credentials,
+    Environment,
+    InteractionContext,
+    IslandConfig,
+    IslandResponse,
+)
+from .proteus import UI
+from .response import (
+    DISCOVERY_MIME_TYPE,
+    RESPONSE_MIME_TYPE,
+    AffectedObject,
+    AsyncCallback,
+    CallbackDeliveryError,
+    ComposableToolResponse,
+    OperationResult,
+    ProblemDetail,
+    RollbackSpec,
+    ToolResponse,
+    async_timeout,
+    authentication_required,
+    permission_denied,
+    provider_error,
+    rate_limited,
+    resource_conflict,
+    resource_not_found,
+    validation_error,
+)
+from .service import ToolsService
+
+__version__ = "0.1.14-dev"
+__all__ = [
+    "ToolsService",
+    "tool",
+    "resource",
+    "interaction",
+    "rollback",
+    "requires_auth",
+    "register_logger_factory",
+    # Auth (v2)
+    "SdkConfig",
+    "EpiHmac",
+    # Context
+    "ToolExecutionContext",
+    "AsyncCallback",
+    "CallbackDeliveryError",
+    # Models
+    "AuthData",
+    "AuthRequirement",
+    "Credentials",
+    "Environment",
+    "InteractionContext",
+    "IslandConfig",
+    "IslandResponse",
+    # Response envelope (v2)
+    "ComposableToolResponse",
+    "ToolResponse",
+    "OperationResult",
+    "RollbackSpec",
+    "AffectedObject",
+    "ProblemDetail",
+    "DISCOVERY_MIME_TYPE",
+    "RESPONSE_MIME_TYPE",
+    # Error helpers
+    "validation_error",
+    "authentication_required",
+    "resource_not_found",
+    "permission_denied",
+    "resource_conflict",
+    "rate_limited",
+    "provider_error",
+    "async_timeout",
+    # UI
+    "UI",
+]

optimizely_opal_opal_tools_sdk-0.1.42.dev0/opal_tools_sdk/config.py

@@ -0,0 +1,61 @@
+"""SDK configuration for authentication modes."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Literal
+
+from pydantic import BaseModel, SecretStr, model_validator
+
+
+class SdkConfig(BaseModel):
+    """Configuration for Opal Tools SDK authentication.
+
+    Only needed when the tool provider requires request authentication.
+    All other v2 features are auto-detected from usage.
+    """
+
+    auth_mode: Literal["static_token", "hmac", "turnstile"] | None = None
+    bearer_token: str | None = None
+    hmac_app_key: str | None = None
+    hmac_secret: SecretStr | None = None  # base64-encoded, masked in logs/repr
+
+    @model_validator(mode="after")
+    def _require_credentials_for_auth_mode(self) -> SdkConfig:
+        """Fail closed on misconfiguration so authentication can't silently no-op.
+
+        A configured ``auth_mode`` must carry the credentials it needs:
+
+        - ``static_token`` -> a non-empty ``bearer_token``
+        - ``hmac`` / ``turnstile`` -> a non-empty ``hmac_app_key`` and a
+          non-empty, valid base64 ``hmac_secret``
+
+        Without this, e.g. ``SdkConfig(auth_mode="hmac")`` would build an
+        EpiHmac with an empty secret and accept/produce signatures that no
+        real caller can match — an auth bypass that looks configured.
+        """
+        if self.auth_mode is None:
+            return self
+
+        if self.auth_mode == "static_token":
+            if not (self.bearer_token and self.bearer_token.strip()):
+                raise ValueError("auth_mode='static_token' requires a non-empty bearer_token")
+            return self
+
+        # hmac / turnstile
+        if not (self.hmac_app_key and self.hmac_app_key.strip()):
+            raise ValueError(f"auth_mode='{self.auth_mode}' requires a non-empty hmac_app_key")
+        if not self.hmac_secret:
+            raise ValueError(f"auth_mode='{self.auth_mode}' requires a non-empty hmac_secret")
+        secret_value = self.hmac_secret.get_secret_value()
+        if not secret_value.strip():
+            raise ValueError(f"auth_mode='{self.auth_mode}' requires a non-empty hmac_secret")
+        try:
+            base64.b64decode(secret_value, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError(
+                f"auth_mode='{self.auth_mode}' hmac_secret must be valid base64"
+            ) from exc
+
+        return self

optimizely_opal_opal_tools_sdk-0.1.42.dev0/opal_tools_sdk/context.py

@@ -0,0 +1,40 @@
+"""Execution context for Opal tool handlers."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from .models import Environment
+from .response import AsyncCallback
+
+
+class ToolExecutionContext(BaseModel):
+    """Execution context passed to tool handlers as an optional third parameter.
+
+    Provides typed access to the execution environment and async callback.
+    Unknown environment properties are silently ignored for forward compatibility.
+
+    Usage::
+
+        @tool(name="report", mode="async", timeout=600)
+        async def report(params: ReportParams, auth_data: AuthData, context: ToolExecutionContext):
+            # context.environment["execution_mode"]  → "headless" | "interactive"
+            # context.callback.url                   → callback URL (async tools only)
+            # context.callback is None               → sync tools
+            # context.thread_id / workflow_execution_id / agent_execution_id
+            #                                        → caller identity (from x-opal-* headers)
+            # context.auth                           → auth payload (same as the auth_data param)
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    environment: Environment | None = None
+    callback: AsyncCallback | None = None
+    # Caller identity, populated from the x-opal-*-id request headers. Exactly one
+    # of these is typically set depending on the execution path (chat thread,
+    # workflow execution, or specialized-agent execution).
+    thread_id: str | None = None
+    workflow_execution_id: str | None = None
+    agent_execution_id: str | None = None
+    # Auth payload (mirrors the legacy `auth_data` handler parameter).
+    auth: dict | None = None

{optimizely_opal_opal_tools_sdk-0.1.40.dev0 → optimizely_opal_opal_tools_sdk-0.1.42.dev0}/opal_tools_sdk/decorators.py

@@ -95,7 +95,11 @@ def tool(
     description: str,
     auth_requirements: list[dict[str, Any]] | None = None,
     ui_resource: str | None = None,
+    mode: str = "sync",
+    timeout: int | None = None,
+    sensitive: str | bool | None = None,
     wait: bool = False,
+    skippable_interaction: bool = False,
 ):
     """Decorator to register a function as an Opal tool.
 
@@ -111,6 +115,8 @@ def tool(
             Example: "ui://my-app/create-form"
         wait: When True, invoking this tool pauses the agent execution until the caller
             signals completion.
+        skippable_interaction: When True, the tool's confirmation interaction (card) can be
+            skipped; a user who opts out has the tool run headless instead.
 
     Returns:
         Decorator function
@@ -122,6 +128,11 @@ def tool(
 
         If ui_resource is specified, the frontend can fetch the resource to render a dynamic UI
         for this tool without hardcoded integrations.
+
+        sensitive marks an action that needs user awareness/confirmation. Pass an
+        advisory string (e.g. "Verify the recipient") or True (a generic advisory
+        is substituted). It is published in discovery as a single nullable
+        string — present means sensitive, absent means not.
     """
 
     def decorator(func: Callable):
@@ -297,9 +308,53 @@ def tool(
                 endpoint=endpoint,
                 auth_requirements=auth_req_list,
                 ui_resource=ui_resource,
+                mode=mode,
+                timeout=timeout,
+                sensitive=sensitive,
                 wait=wait,
+                skippable_interaction=skippable_interaction,
+            )
+
+        return func
+
+    return decorator
+
+
+def rollback(name: str):
+    """Decorator to register a rollback (undo) handler.
+
+    The handler is auto-routed to ``POST /tools/rollbacks/{name}`` and
+    advertised in the ``rollbacks`` array of the discovery document. TMS calls
+    this endpoint to undo a previously executed operation.
+
+    Args:
+        name: The rollback handler's id — independent of any tool name. A tool
+              opts into rollback by returning an ``OperationResult`` whose
+              ``rollback.tool_name`` equals this value; several tools may share one
+              handler. Decorate the handler with ``@requires_auth`` to attach
+              OAuth requirements (published in discovery and forwarded on
+              invocation). Handlers must be idempotent: the invocation body
+              carries the originating ``operation_id`` (injected when the handler
+              declares an ``operation_id`` parameter) so retries can be
+              deduplicated.
+    """
+
+    def decorator(func: Callable):
+        endpoint = f"/tools/rollbacks/{name}"
+
+        logger.info(f"Registering rollback {name} with endpoint {endpoint}")
+
+        from . import _registry
+
+        if not _registry.services:
+            logger.warning(
+                "No services registered in registry! "
+                "Make sure to create ToolsService before decorating functions."
             )
 
+        for service in _registry.services:
+            service.register_rollback(name=name, handler=func)
+
         return func
 
     return decorator

{optimizely_opal_opal_tools_sdk-0.1.40.dev0 → optimizely_opal_opal_tools_sdk-0.1.42.dev0}/opal_tools_sdk/models.py

@@ -1,8 +1,9 @@
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Literal, TypedDict
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field
+from typing_extensions import NotRequired, TypedDict  # pydantic requires this on Python < 3.12
 
 
 class ParameterType(str, Enum):
@@ -86,9 +87,13 @@ class Environment(TypedDict):
     """Execution environment for an Opal tool.
 
     Interactive mode provides interaction islands, while headless does not.
+    `execution_mode` is always sent by TMS — required. `is_proteus_enabled`
+    was added later, so older TMS versions may omit it; mark it `NotRequired`
+    for cross-version forward compatibility.
     """
 
     execution_mode: Literal["headless", "interactive"]
+    is_proteus_enabled: NotRequired[bool]
 
 
 @dataclass
@@ -102,7 +107,22 @@ class Function:
     auth_requirements: list[AuthRequirement] | None = None
     http_method: str = "POST"
     ui_resource: str | None = None  # UI resource URI for dynamic UI rendering
+    mode: str = "sync"  # "sync" or "async"
+    timeout: int | None = None  # seconds
+    # Ergonomic input (True | advisory str | None); normalized in __post_init__
+    # to a non-empty advisory string when sensitive, else None.
+    sensitive: str | bool | None = None
     wait: bool = False  # When True, pauses the agent until the caller signals completion
+    skippable_interaction: bool = False  # When True, the tool's confirmation card can be skipped
+
+    def __post_init__(self) -> None:
+        # Normalize `sensitive` to the wire shape: a single nullable advisory
+        # string. True -> a generic advisory; non-empty string -> itself;
+        # False / None / empty / whitespace -> None (not sensitive).
+        if self.sensitive is True:
+            self.sensitive = "This tool performs a sensitive action."
+        elif not (isinstance(self.sensitive, str) and self.sensitive.strip()):
+            self.sensitive = None
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for the discovery endpoint."""
@@ -120,8 +140,16 @@ class Function:
         if self.ui_resource:
             result["ui_resource"] = self.ui_resource
 
+        if self.mode != "sync":
+            result["mode"] = self.mode
+        if self.timeout:
+            result["timeout"] = self.timeout
+        if self.sensitive:
+            result["sensitive"] = self.sensitive
         if self.wait:
             result["wait"] = self.wait
+        if self.skippable_interaction:
+            result["skippable_interaction"] = self.skippable_interaction
 
         return result