@palettelab/cli 0.3.12 → 0.3.14

package/backend-sdk/palette_sdk/__init__.py

@@ -0,0 +1,48 @@
+"""Palette Platform SDK for building backend plugins."""
+
+from palette_sdk.plugin_router import PluginRouter
+from palette_sdk.plugin_context import PluginContext, get_plugin_context
+from palette_sdk.tool_definition import ToolDefinition
+from palette_sdk.manifest import PluginManifest, load_manifest
+from palette_sdk.schemas import (
+    SuccessResponse,
+    ErrorResponse,
+    PaginatedResponse,
+)
+from palette_sdk.db import OrgScopedTable, PluginBase, ensure_org_rls
+from palette_sdk.permissions import (
+    KNOWN_PERMISSIONS,
+    is_known_permission,
+    require_permission,
+)
+from palette_sdk.events import Event, subscribe_event
+from palette_sdk.config import get_config, require_config
+from palette_sdk.webhooks import sign_webhook, verify_webhook_signature
+from palette_sdk.testing import route_permission_issues
+
+__all__ = [
+    "PluginRouter",
+    "PluginContext",
+    "get_plugin_context",
+    "ToolDefinition",
+    "PluginManifest",
+    "load_manifest",
+    "SuccessResponse",
+    "ErrorResponse",
+    "PaginatedResponse",
+    "OrgScopedTable",
+    "PluginBase",
+    "ensure_org_rls",
+    "KNOWN_PERMISSIONS",
+    "is_known_permission",
+    "require_permission",
+    "Event",
+    "subscribe_event",
+    "get_config",
+    "require_config",
+    "sign_webhook",
+    "verify_webhook_signature",
+    "route_permission_issues",
+]
+
+__version__ = "0.1.3"

package/backend-sdk/palette_sdk/config.py

@@ -0,0 +1,21 @@
+"""Install-scoped plugin configuration helpers."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from palette_sdk.plugin_context import PluginContext
+
+T = TypeVar("T")
+
+
+def get_config(ctx: PluginContext, key: str, default: T | None = None) -> Any | T | None:
+    """Return a config value injected by the platform for this org install."""
+    return ctx.config.get(key, default)
+
+
+def require_config(ctx: PluginContext, key: str) -> Any:
+    """Return a config value or raise a clear runtime error."""
+    if key not in ctx.config:
+        raise KeyError(f"missing required plugin config key: {key}")
+    return ctx.config[key]

package/backend-sdk/palette_sdk/db/__init__.py

@@ -0,0 +1,38 @@
+"""Database primitives for Palette plugins.
+
+Plugins that declare a `database` block in their manifest get their own
+Postgres schema, owned by a dedicated low-privilege role, with row-level
+security enforcing per-organization isolation.
+
+Typical plugin usage:
+
+    # models.py
+    from palette_sdk.db import OrgScopedTable
+    from sqlalchemy import String
+    from sqlalchemy.orm import Mapped, mapped_column
+
+    class Expense(OrgScopedTable):
+        __tablename__ = "expenses"
+        title: Mapped[str] = mapped_column(String(200))
+        amount_cents: Mapped[int]
+
+    # migrations/versions/0001_init.py
+    from alembic import op
+    import sqlalchemy as sa
+    from palette_sdk.db import ensure_org_rls
+
+    def upgrade():
+        op.create_table(
+            "expenses",
+            sa.Column("id", sa.Integer, primary_key=True),
+            sa.Column("organization_id", sa.BigInteger, nullable=False, index=True),
+            sa.Column("title", sa.String(200), nullable=False),
+            sa.Column("amount_cents", sa.Integer, nullable=False),
+        )
+        ensure_org_rls(op, "expenses")
+"""
+
+from palette_sdk.db.base import OrgScopedTable, PluginBase
+from palette_sdk.db.rls import ensure_org_rls
+
+__all__ = ["OrgScopedTable", "PluginBase", "ensure_org_rls"]

package/backend-sdk/palette_sdk/db/alembic_env.py

@@ -0,0 +1,89 @@
+"""Alembic env template for plugin migrations.
+
+Plugins ship an `env.py` that is a one-liner:
+
+    from palette_sdk.db.alembic_env import run_migrations
+    run_migrations()
+
+The runner reads three environment variables set by the platform when it
+invokes Alembic:
+
+  - ``PALETTE_PLUGIN_ID``  — plugin id; determines the target schema
+                             (``app_<sanitized_id>``) and version table schema.
+  - ``PALETTE_DB_URL``     — SQLAlchemy async URL for the plugin's DB.
+  - ``PALETTE_PLUGIN_ROLE`` (optional) — role the migration should run as;
+                             defaults to the connecting user (so DDL works).
+
+Plugin devs running ``alembic upgrade head`` locally without those vars get
+a helpful error rather than a scribbled-on main DB.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool, text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+
+def _plugin_schema(plugin_id: str) -> str:
+    safe = re.sub(r"[^a-z0-9_]", "_", plugin_id.lower())
+    return f"app_{safe}"
+
+
+def _do_run_migrations(connection, schema: str, plugin_role: str | None) -> None:
+    if plugin_role:
+        connection.execute(text(f'SET ROLE "{plugin_role}"'))
+    connection.execute(text(f'SET search_path TO "{schema}"'))
+
+    context.configure(
+        connection=connection,
+        target_metadata=None,
+        version_table="alembic_version",
+        version_table_schema=schema,
+        include_schemas=False,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def _run_async(schema: str, db_url: str, plugin_role: str | None) -> None:
+    connectable = create_async_engine(db_url, poolclass=pool.NullPool)
+    try:
+        # `.begin()` (not `.connect()`): commits on clean exit, rolls back on
+        # exception. With `.connect()` the surrounding transaction is rolled
+        # back at close time, silently discarding every CREATE/ALTER the
+        # migration issued.
+        async with connectable.begin() as connection:
+            await connection.run_sync(
+                lambda sync_conn: _do_run_migrations(sync_conn, schema, plugin_role)
+            )
+    finally:
+        await connectable.dispose()
+
+
+def run_migrations() -> None:
+    plugin_id = os.environ.get("PALETTE_PLUGIN_ID")
+    db_url = os.environ.get("PALETTE_DB_URL")
+    plugin_role = os.environ.get("PALETTE_PLUGIN_ROLE") or None
+
+    if not plugin_id or not db_url:
+        raise RuntimeError(
+            "Plugin migrations require PALETTE_PLUGIN_ID and PALETTE_DB_URL "
+            "to be set. These are provided automatically by the platform; "
+            "use `palette dev` for local runs."
+        )
+
+    config = context.config
+    if config.config_file_name:
+        try:
+            fileConfig(config.config_file_name)
+        except Exception:
+            pass
+
+    schema = _plugin_schema(plugin_id)
+    asyncio.run(_run_async(schema, db_url, plugin_role))

package/backend-sdk/palette_sdk/db/base.py

@@ -0,0 +1,50 @@
+"""Declarative bases for plugin models.
+
+`OrgScopedTable` is the base every plugin table must inherit from. It adds
+`organization_id` automatically and registers the class so migration tooling
+and the build linter can verify RLS is in place.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import BigInteger, Index
+from sqlalchemy.orm import DeclarativeBase, Mapped, declared_attr, mapped_column
+
+
+class PluginBase(DeclarativeBase):
+    """Declarative base for plugin models.
+
+    Prefer `OrgScopedTable` for any table that stores org data. Use `PluginBase`
+    directly only for tables that are genuinely global to the plugin (e.g. a
+    lookup table seeded by a migration). Any such use still lives inside the
+    plugin's own schema and is not cross-org by design.
+    """
+
+
+class OrgScopedTable(PluginBase):
+    """Base for all per-organization plugin tables.
+
+    Inheriting from this gives you:
+      - An `organization_id BIGINT NOT NULL` column with an index.
+      - A row-level security policy, enforced at migration time via
+        `ensure_org_rls(op, "<tablename>")` in your Alembic migration.
+
+    Never write `WHERE organization_id = ?` in your queries — the database
+    will filter rows for you based on the session variable set by the
+    platform at request time.
+    """
+
+    __abstract__ = True
+
+    @declared_attr
+    def organization_id(cls) -> Mapped[int]:
+        return mapped_column(BigInteger, nullable=False, index=True)
+
+    @declared_attr.directive
+    def __table_args__(cls):
+        tablename = getattr(cls, "__tablename__", None)
+        if not tablename:
+            return ()
+        return (
+            Index(f"ix_{tablename}_org", "organization_id"),
+        )

package/backend-sdk/palette_sdk/db/rls.py

@@ -0,0 +1,34 @@
+"""Row-level security helpers for plugin migrations.
+
+Every plugin table that holds org data must call `ensure_org_rls(op, table)`
+in the migration that creates it. This enables RLS and installs the standard
+policy, which filters rows by the `app.current_org_id` session variable set
+by the platform at request time.
+
+The `palette build` CLI lints migrations and will reject any that:
+  - create an org table without a matching `ensure_org_rls` call,
+  - contain `DROP POLICY` or `DISABLE ROW LEVEL SECURITY`,
+  - reference the `public.` schema,
+  - set `FORCE ROW LEVEL SECURITY` off.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+ORG_POLICY_NAME = "org_isolation"
+
+
+def ensure_org_rls(op: Any, table_name: str, *, policy_name: str = ORG_POLICY_NAME) -> None:
+    """Enable RLS on `table_name` and install the org-isolation policy.
+
+    Idempotent: safe to call even if the policy already exists.
+    """
+    op.execute(f'ALTER TABLE "{table_name}" ENABLE ROW LEVEL SECURITY')
+    op.execute(f'ALTER TABLE "{table_name}" FORCE ROW LEVEL SECURITY')
+    op.execute(f'DROP POLICY IF EXISTS "{policy_name}" ON "{table_name}"')
+    op.execute(
+        f'CREATE POLICY "{policy_name}" ON "{table_name}" '
+        f"USING (organization_id = current_setting('app.current_org_id', true)::bigint) "
+        f"WITH CHECK (organization_id = current_setting('app.current_org_id', true)::bigint)"
+    )

package/backend-sdk/palette_sdk/events.py

@@ -0,0 +1,54 @@
+"""Plugin-side event subscribers.
+
+Plugins declare in-process handlers for platform events by calling
+`subscribe_event(topic, handler)` at import time (typically from the plugin's
+backend entrypoint). The platform's plugin loader picks these up after
+importing the plugin module and registers them with the core event bus.
+
+Usage::
+
+    from palette_sdk.events import subscribe_event, Event
+
+    async def on_task_created(event: Event) -> None:
+        print(event.payload["task_id"])
+
+    subscribe_event("task.created", on_task_created)
+
+Handlers run in the platform process — they share the asyncio loop with
+request handlers. Do not block; offload heavy work to background tasks or
+emit your own outbound HTTP call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+Handler = Callable[["Event"], Awaitable[None]]
+
+
+@dataclass
+class Event:
+    topic: str
+    organization_id: int | None
+    payload: dict[str, Any]
+    occurred_at: datetime
+
+
+# Plugin-declared subscribers are captured here during module import; the
+# platform drains the list after loading each plugin and attaches them to the
+# core bus with the plugin's id.
+_pending: list[tuple[str, Handler]] = []
+
+
+def subscribe_event(topic: str, handler: Handler) -> None:
+    _pending.append((topic, handler))
+
+
+def drain_pending() -> list[tuple[str, Handler]]:
+    """Platform-only. Return + clear the list of subscribers registered since last drain."""
+    out = list(_pending)
+    _pending.clear()
+    return out

package/backend-sdk/palette_sdk/manifest.py

@@ -0,0 +1,112 @@
+"""Plugin manifest loader and validator."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class AgentDefinition(BaseModel):
+    name: str
+    field: str
+    description: str
+    long_description: str = ""
+    category: str = "general"
+    tools: list[str] = Field(default_factory=list)
+    icon_name: str = "Robot"
+    color: str = "#6366f1"
+
+
+class ToolEntry(BaseModel):
+    name: str
+    description: str = ""
+    entry: str
+
+
+class FrontendEntry(BaseModel):
+    entry: str
+    sandbox: bool = True
+
+
+class BackendEntry(BaseModel):
+    entry: str
+    routes_prefix: str | None = None
+
+
+class GradientConfig(BaseModel):
+    bg: str
+    text: str = "#fff"
+
+
+class SdkCompat(BaseModel):
+    frontend: str | None = None
+    backend: str | None = None
+
+
+class PlatformCompat(BaseModel):
+    min_version: str | None = None
+    max_version: str | None = None
+
+
+class Capabilities(BaseModel):
+    frontend: bool = False
+    backend: bool = False
+    database: bool = False
+    webhooks: bool = False
+    scheduled_jobs: bool = False
+    file_uploads: bool = False
+    external_network: list[str] = Field(default_factory=list)
+
+
+class ScheduledJob(BaseModel):
+    name: str
+    schedule: str
+    handler: str
+
+
+class RateLimit(BaseModel):
+    per_minute: int = 60
+
+
+class PluginManifest(BaseModel):
+    """Validated plugin manifest from palette-plugin.json."""
+
+    manifest_version: Literal["1"] = "1"
+    id: str
+    name: str
+    version: str = "1.0.0"
+    developer: str = ""
+    category: str = "Productivity"
+    tagline: str = ""
+    description: str = ""
+    icon: str = "Puzzle"
+    gradient: GradientConfig = GradientConfig(bg="linear-gradient(135deg, #6366F1, #8B5CF6)")
+    sdk: SdkCompat | None = None
+    platform: PlatformCompat | None = None
+    capabilities: Capabilities = Field(default_factory=Capabilities)
+    public_routes: list[str] = Field(default_factory=list)
+    scheduled_jobs: list[ScheduledJob] = Field(default_factory=list)
+    rate_limit: RateLimit | None = None
+    frontend: FrontendEntry | None = None
+    backend: BackendEntry | None = None
+    agents: list[AgentDefinition] = Field(default_factory=list)
+    tools: list[ToolEntry] = Field(default_factory=list)
+    permissions: list[str] = Field(default_factory=list)
+    rating: float = 0.0
+    reviews: int = 0
+    featured: bool = False
+
+
+def load_manifest(plugin_dir: str | Path) -> PluginManifest:
+    """Load and validate a palette-plugin.json from a plugin directory."""
+    manifest_path = Path(plugin_dir) / "palette-plugin.json"
+    if not manifest_path.exists():
+        raise FileNotFoundError(f"No palette-plugin.json found in {plugin_dir}")
+
+    with open(manifest_path) as f:
+        data = json.load(f)
+
+    return PluginManifest(**data)

package/backend-sdk/palette_sdk/permissions.py

@@ -0,0 +1,94 @@
+"""Plugin permission enforcement.
+
+Plugins declare required permissions in their manifest. At route level they
+call `require_permission("resource:action")` as a dependency — the platform
+injected `request.state.plugin_permissions` (from the manifest) is checked
+against the required permission. Mismatch → 403.
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, Request, status
+
+# Known permission vocabulary. Platform code uses this to validate manifests;
+# plugin authors pick from this list. Extending the list is a platform change.
+KNOWN_PERMISSIONS: frozenset[str] = frozenset(
+    {
+        "tasks:read",
+        "tasks:write",
+        "data_rooms:read",
+        "data_rooms:write",
+        "agents:read",
+        "agents:write",
+        "chat:read",
+        "chat:write",
+        "routines:read",
+        "routines:write",
+        "members:read",
+        "resources:read",
+        "resources:write",
+    }
+)
+
+
+def is_known_permission(perm: str) -> bool:
+    return perm in KNOWN_PERMISSIONS
+
+
+#: Sentinel attribute the platform loader looks for when walking a route's
+#: dependency tree. Its presence on the `_check` closure is what proves the
+#: route is permission-gated.
+_PALETTE_PERMISSION_ATTR = "__palette_permission__"
+
+
+def require_permission(permission: str):
+    """Return a FastAPI dependency that asserts the plugin was granted `permission`.
+
+    Usage (inside a plugin's FastAPI router)::
+
+        @router.get("/my-endpoint", dependencies=[Depends(require_permission("tasks:read"))])
+        async def handler(...):
+            ...
+
+    Every plugin route MUST be gated by at least one `require_permission` call
+    (or be listed in the manifest's `public_routes`). The platform inspects the
+    dependency tree at mount time and refuses to load the plugin otherwise.
+
+    Raises 403 if the plugin's manifest doesn't list the permission. Raises 500
+    if the request wasn't dispatched through the plugin loader (no
+    plugin_permissions in request.state) — that indicates a misconfigured
+    deployment.
+    """
+
+    async def _check(request: Request) -> None:
+        granted = getattr(request.state, "plugin_permissions", None)
+        if granted is None:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="plugin permission context missing",
+            )
+        if permission not in granted:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"plugin lacks permission: {permission}",
+            )
+
+    # The loader walks route.dependant recursively and refuses to mount any
+    # route without at least one dep whose callable has this attribute set.
+    setattr(_check, _PALETTE_PERMISSION_ATTR, permission)
+    return Depends(_check)
+
+
+def is_permission_dep(callable_: object) -> str | None:
+    """Return the permission string if `callable_` was produced by
+    `require_permission(...)`, otherwise None. Used by the platform loader.
+    """
+    return getattr(callable_, _PALETTE_PERMISSION_ATTR, None)
+
+
+__all__ = [
+    "KNOWN_PERMISSIONS",
+    "is_known_permission",
+    "require_permission",
+    "is_permission_dep",
+]

package/backend-sdk/palette_sdk/plugin_context.py

@@ -0,0 +1,63 @@
+"""Plugin execution context — injected by the platform runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from fastapi import Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@dataclass
+class PluginContext:
+    """Context provided to plugin endpoints by the platform.
+
+    Attributes:
+        db: Async SQLAlchemy session. If the plugin declares a `database` block
+            in its manifest, this is a plugin-scoped session: `search_path` is
+            set to the plugin's schema and the `app.current_org_id` session
+            variable is applied, so row-level security filters queries to the
+            caller's organization automatically. Do not add `WHERE
+            organization_id = ?` — RLS already does it.
+        user_id: UUID of the authenticated user
+        organization_id: Current org ID
+        org_role: User's role in the org (owner/admin/member)
+        plugin_id: The plugin's ID from its manifest
+        permissions: List of permissions declared in the manifest
+        storage: Storage service for file upload/download
+    """
+    db: AsyncSession
+    user_id: str
+    organization_id: int
+    org_role: str | None = None
+    plugin_id: str = ""
+    permissions: list[str] = field(default_factory=list)
+    storage: Any = None  # Platform storage service injected at runtime
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+async def get_plugin_context(request: Request) -> PluginContext:
+    """FastAPI dependency that extracts plugin context from the request.
+
+    The platform's plugin loader injects the necessary state into
+    request.state before the plugin endpoint is called.
+
+    Usage:
+        @router.get("/data")
+        async def get_data(ctx: PluginContext = Depends(get_plugin_context)):
+            result = await ctx.db.execute(...)
+            return result
+    """
+    state = request.state
+
+    return PluginContext(
+        db=state.db,
+        user_id=str(state.user.id),
+        organization_id=state.user.organization_id,
+        org_role=getattr(state, "org_role", None),
+        plugin_id=getattr(state, "plugin_id", ""),
+        permissions=getattr(state, "plugin_permissions", []),
+        storage=getattr(state, "storage", None),
+        config=getattr(state, "plugin_config", {}),
+    )

package/backend-sdk/palette_sdk/plugin_router.py

@@ -0,0 +1,27 @@
+"""Plugin-scoped FastAPI router with automatic prefix and auth."""
+
+from fastapi import APIRouter
+
+
+class PluginRouter(APIRouter):
+    """A FastAPI router scoped to a plugin.
+
+    Routes defined on this router will be automatically mounted
+    under /api/v1/plugins/{plugin_id}/ by the platform loader.
+
+    Usage:
+        from palette_sdk import PluginRouter
+
+        router = PluginRouter(tags=["my-plugin"])
+
+        @router.get("/stats")
+        async def get_stats(ctx = Depends(get_plugin_context)):
+            # This will be available at /api/v1/plugins/my-plugin/stats
+            ...
+    """
+
+    def __init__(self, **kwargs):
+        # Inherit FastAPI's default response class (JSONResponse). The
+        # previous code set this to None, which broke both the response
+        # pipeline (TypeError at serialization) and OpenAPI generation.
+        super().__init__(**kwargs)

package/backend-sdk/palette_sdk/schemas.py

@@ -0,0 +1,30 @@
+"""Common response schemas for plugin APIs."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class SuccessResponse(BaseModel):
+    """Generic success response."""
+    success: bool = True
+    message: str = "OK"
+    data: Any = None
+
+
+class ErrorResponse(BaseModel):
+    """Generic error response."""
+    success: bool = False
+    detail: str
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Paginated list response."""
+    items: list[Any]
+    total: int
+    page: int = 1
+    page_size: int = 50

package/backend-sdk/palette_sdk/testing.py

@@ -0,0 +1,45 @@
+"""Testing helpers for Palette backend plugins."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+
+def route_permission_issues(router: APIRouter, public_routes: list[str] | None = None) -> list[str]:
+    """Return route paths that lack `require_permission`.
+
+    This mirrors the platform loader's mount-time check and lets plugin tests
+    fail before publish.
+    """
+    from palette_sdk.permissions import is_permission_dep
+
+    allowed = set(public_routes or [])
+    issues: list[str] = []
+
+    for route in router.routes:
+        path = getattr(route, "path", None)
+        if path is None or path in allowed:
+            continue
+        dependant = getattr(route, "dependant", None)
+        if dependant is None:
+            continue
+
+        stack = [dependant]
+        seen: set[int] = set()
+        gated = False
+        while stack:
+            dep = stack.pop()
+            if id(dep) in seen:
+                continue
+            seen.add(id(dep))
+            call = getattr(dep, "call", None)
+            if call is not None and is_permission_dep(call):
+                gated = True
+                break
+            stack.extend(getattr(dep, "dependencies", []) or [])
+
+        if not gated:
+            methods = ",".join(sorted(getattr(route, "methods", []) or [])) or "?"
+            issues.append(f"{methods} {path}")
+
+    return issues

package/backend-sdk/palette_sdk/tool_definition.py

@@ -0,0 +1,66 @@
+"""Base class for defining custom agent tools."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ToolDefinition(ABC):
+    """Base class for custom agent tools provided by plugins.
+
+    Subclass this to create tools that agents can use in chat conversations.
+
+    Example:
+        class ChartTool(ToolDefinition):
+            name = "generate_chart"
+            description = "Generate a chart from data"
+            input_schema = {
+                "type": "object",
+                "properties": {
+                    "chart_type": {"type": "string", "enum": ["bar", "line", "pie"]},
+                    "data": {"type": "array", "items": {"type": "object"}},
+                    "title": {"type": "string"},
+                },
+                "required": ["chart_type", "data"],
+            }
+
+            async def run(self, input_data: dict, context: dict) -> str:
+                # Generate chart and return result
+                return "Chart generated: https://..."
+    """
+
+    name: str = ""
+    description: str = ""
+    input_schema: dict[str, Any] = {}
+
+    @abstractmethod
+    async def run(self, input_data: dict[str, Any], context: dict[str, Any]) -> str:
+        """Execute the tool with the given input.
+
+        Args:
+            input_data: Validated input matching the input_schema
+            context: Runtime context with user_id, org_id, db session, etc.
+
+        Returns:
+            String result to be sent back to the agent
+        """
+        ...
+
+    def to_langchain_tool(self):
+        """Convert to a LangChain-compatible tool function.
+
+        Called by the platform when building an agent's tool list.
+        Plugin developers don't need to call this directly.
+        """
+        from langchain_core.tools import StructuredTool
+
+        async def _run(**kwargs):
+            return await self.run(kwargs, {})
+
+        return StructuredTool.from_function(
+            coroutine=_run,
+            name=self.name,
+            description=self.description,
+            args_schema=None,
+        )

package/backend-sdk/palette_sdk/webhooks.py

@@ -0,0 +1,17 @@
+"""Small webhook utilities for plugin authors."""
+
+from __future__ import annotations
+
+import hmac
+from hashlib import sha256
+
+
+def sign_webhook(secret: str, payload: bytes) -> str:
+    """Return a hex HMAC-SHA256 signature for `payload`."""
+    return hmac.new(secret.encode(), payload, sha256).hexdigest()
+
+
+def verify_webhook_signature(secret: str, payload: bytes, signature: str) -> bool:
+    """Constant-time HMAC-SHA256 verification."""
+    expected = sign_webhook(secret, payload)
+    return hmac.compare_digest(expected, signature)

package/backend-sdk/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "palette-sdk"
+version = "0.1.3"
+description = "Palette Platform SDK for building backend plugins"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Palette Platform" }]
+keywords = ["palette", "plugin", "sdk", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "fastapi>=0.129.0",
+    "pydantic>=2.12.0",
+    "sqlalchemy>=2.0.47",
+]
+
+[project.urls]
+Homepage = "https://github.com/palette-lab/palette-virtual-organization-backend/releases"
+Repository = "https://github.com/palette-lab/palette-virtual-organization-backend"
+Documentation = "https://github.com/palette-lab/palette-virtual-organization-backend/releases"
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["palette_sdk*"]

package/lib/commands/test.js

@@ -36,8 +36,11 @@ function reporter(json, results) {
 }
 
 function localBackendSdkPath() {
-  const candidate = path.resolve(__dirname, "..", "..", "..", "backend")
-  return fs.existsSync(path.join(candidate, "palette_sdk")) ? candidate : null
+  const candidates = [
+    path.resolve(__dirname, "..", "..", "..", "backend"),
+    path.resolve(__dirname, "..", "..", "backend-sdk"),
+  ]
+  return candidates.find((candidate) => fs.existsSync(path.join(candidate, "palette_sdk"))) || null
 }
 
 function localBackendSdkPython() {
@@ -432,7 +435,8 @@ function backendSdkVersionFromDependency(cwd) {
     const constrained = String(dep).match(/^palette-sdk\s*(?:[<>=~!]=?\s*)?(\d+\.\d+\.\d+)/)
     if (constrained) return constrained[1]
   }
-  const localPyproject = path.resolve(__dirname, "..", "..", "..", "backend", "pyproject.toml")
+  const sdkPath = localBackendSdkPath()
+  const localPyproject = sdkPath ? path.join(sdkPath, "pyproject.toml") : ""
   if (fs.existsSync(localPyproject)) {
     const match = fs.readFileSync(localPyproject, "utf8").match(/^version\s*=\s*["']([^"']+)["']/m)
     if (match) return match[1]

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"
   },
   "files": [
     "bin",
+    "backend-sdk",
     "lib",
     "platform-dev",
     "template-fallback",
+    "!backend-sdk/**/__pycache__",
+    "!backend-sdk/**/*.pyc",
     "!template-fallback/**/__pycache__",
     "!template-fallback/**/*.pyc",
     "palette.config.example.json",

package/template-fallback/pyproject.toml

@@ -14,5 +14,6 @@ requires-python = ">=3.12"
 dependencies = [
     "fastapi>=0.129.0",
     "sqlalchemy>=2.0.47",
-    "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-v0.1.0/palette_sdk-0.1.0-py3-none-any.whl",
+    # `pltt test` ships the backend SDK on PYTHONPATH. Pin a released
+    # palette-sdk package here only if you run backend tests outside the CLI.
 ]

package/template-fallback/templates/agent-tool/pyproject.toml

@@ -5,5 +5,6 @@ requires-python = ">=3.12"
 dependencies = [
   "fastapi>=0.129.0",
   "pydantic>=2.12.0",
-  "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-v0.1.0/palette_sdk-0.1.0-py3-none-any.whl",
+  "sqlalchemy>=2.0.47",
+  # `pltt test` ships the backend SDK on PYTHONPATH.
 ]

package/template-fallback/templates/dashboard/pyproject.toml

@@ -4,5 +4,6 @@ version = "1.0.0"
 requires-python = ">=3.12"
 dependencies = [
   "fastapi>=0.129.0",
-  "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-v0.1.0/palette_sdk-0.1.0-py3-none-any.whl",
+  "sqlalchemy>=2.0.47",
+  # `pltt test` ships the backend SDK on PYTHONPATH.
 ]

package/template-fallback/templates/database/pyproject.toml

@@ -6,5 +6,5 @@ dependencies = [
   "fastapi>=0.129.0",
   "sqlalchemy>=2.0.47",
   "alembic>=1.17.0",
-  "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-v0.1.0/palette_sdk-0.1.0-py3-none-any.whl",
+  # `pltt test` ships the backend SDK on PYTHONPATH.
 ]

package/template-fallback/templates/external-service/pyproject.toml

@@ -5,5 +5,6 @@ requires-python = ">=3.12"
 dependencies = [
   "fastapi>=0.129.0",
   "httpx>=0.28.0",
-  "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-v0.1.0/palette_sdk-0.1.0-py3-none-any.whl",
+  "sqlalchemy>=2.0.47",
+  # `pltt test` ships the backend SDK on PYTHONPATH.
 ]