@palettelab/cli 0.3.42 → 0.3.43

package/README.md

@@ -276,11 +276,12 @@ async def create_invoice(body: InvoiceIn, ctx: PluginContext = Depends(get_plugi
 Backend SDK features for app-owned data:
 
 - `PluginRouter`, `PluginContext`, and `get_plugin_context` provide the FastAPI route and request-context surface.
-- `PluginContext` exposes `user_id`, `organization_id`, `org_role`, `plugin_id`, `permissions`, `storage`, `ctx.db`, `ctx.data_rooms`, `ctx.members`, `ctx.redis`, `ctx.vector`, `ctx.config`, and `ctx.logger`.
+- `PluginContext` exposes `user_id`, `organization_id`, `org_role`, `plugin_id`, `permissions`, `storage`, `ctx.db`, `ctx.data_rooms`, `ctx.connections`, `ctx.members`, `ctx.redis`, `ctx.vector`, `ctx.config`, and `ctx.logger`.
 - `ctx.db` is the full scoped SQLAlchemy `AsyncSession` for app-owned database data.
 - `ctx.repo(Model)` gives org-safe CRUD helpers for app tables.
 - `ctx.data_rooms` gives backend access to Palette Data Rooms without importing platform internals.
 - `ctx.members` gives backend access to current organisation members; it exposes list/get/invite/update-role helpers, but no delete/remove helper.
+- `ctx.connections.status(id)`, `ctx.connections.require(id)`, and `ctx.connections.access_token(id)` read Palette-managed third-party connections declared in `palette-plugin.json`.
 - `ctx.has_permission("...")`, `ctx.has_any_permission([...])`, and `ctx.has_all_permissions([...])` check declared permissions.
 - `ctx.config_value("key")` and `ctx.require_config("key")` read app install/config values.
 - `ctx.secret("KEY")` reads app secrets from config or environment variables.
@@ -663,7 +664,7 @@ pltt test
 pltt test --json
 ```
 
-Checks include manifest validity, SDK/platform compatibility, semver bump detection, forbidden platform imports, frontend bundling and size limits, sandbox bridge smoke, backend dependency installation/import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`. The default frontend bundle limit is 2 MiB; set `PALETTE_MAX_FRONTEND_BUNDLE_BYTES` for reviewed exceptions.
+Checks include manifest validity, SDK/platform compatibility, semver bump detection, forbidden platform imports, frontend bundling and size limits, sandbox bridge smoke, backend dependency installation/import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`. The default frontend and backend bundle limits are 15 MiB; set `PALETTE_MAX_FRONTEND_BUNDLE_BYTES` or `PALETTE_MAX_BACKEND_BUNDLE_BYTES` for reviewed exceptions.
 
 ### `pltt package`
 

package/backend-sdk/palette_sdk/__init__.py

@@ -3,6 +3,8 @@
 from palette_sdk.plugin_router import PluginRouter
 from palette_sdk.plugin_context import MissingSecretError, PluginContext, get_plugin_context
 from palette_sdk.data_rooms import DataRoomsClient
+from palette_sdk.connections import ConnectionStatus, MissingConnectionError, PluginConnectionsClient
+from palette_sdk.apps import AppInteropClient, AppServiceClient, MissingAppServiceError
 from palette_sdk.members import OrganizationMembersClient
 from palette_sdk.platform_services import (
     LocalRedisService,
@@ -32,7 +34,7 @@ from palette_sdk.permissions import (
     is_known_permission,
     require_permission,
 )
-from palette_sdk.events import Event, subscribe_event
+from palette_sdk.events import Event, EventPublisher, 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
@@ -44,6 +46,12 @@ __all__ = [
     "MissingSecretError",
     "get_plugin_context",
     "DataRoomsClient",
+    "ConnectionStatus",
+    "MissingConnectionError",
+    "PluginConnectionsClient",
+    "AppInteropClient",
+    "AppServiceClient",
+    "MissingAppServiceError",
     "OrganizationMembersClient",
     "LocalRedisService",
     "LocalVectorService",
@@ -67,6 +75,7 @@ __all__ = [
     "is_known_permission",
     "require_permission",
     "Event",
+    "EventPublisher",
     "subscribe_event",
     "get_config",
     "require_config",

package/backend-sdk/palette_sdk/apps.py

@@ -0,0 +1,66 @@
+"""App-to-app communication helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MissingAppServiceError(RuntimeError):
+    """Raised when the platform did not inject app-to-app helpers."""
+
+
+class AppServiceClient:
+    def __init__(self, adapter: Any, service_id: str):
+        self._adapter = adapter
+        self.service_id = service_id
+
+    async def call(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        json: Any = None,
+        timeout: float = 30.0,
+    ) -> Any:
+        if self._adapter is None:
+            raise MissingAppServiceError("Palette app service helpers are not available in this runtime")
+        return await self._adapter.call_service(
+            self.service_id,
+            path,
+            method=method,
+            json_body=json,
+            timeout=timeout,
+        )
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        return await self.call(path, method="GET", **kwargs)
+
+    async def post(self, path: str, json: Any = None, **kwargs: Any) -> Any:
+        return await self.call(path, method="POST", json=json, **kwargs)
+
+
+class AppInteropClient:
+    def __init__(self, adapter: Any = None):
+        self._adapter = adapter
+
+    def service(self, service_id: str) -> AppServiceClient:
+        return AppServiceClient(self._adapter, service_id)
+
+    async def call(
+        self,
+        app_id: str,
+        path: str,
+        *,
+        method: str = "GET",
+        json: Any = None,
+        timeout: float = 30.0,
+    ) -> Any:
+        if self._adapter is None:
+            raise MissingAppServiceError("Palette app service helpers are not available in this runtime")
+        return await self._adapter.call(
+            app_id,
+            path,
+            method=method,
+            json_body=json,
+            timeout=timeout,
+        )

package/backend-sdk/palette_sdk/connections.py

@@ -0,0 +1,83 @@
+"""Palette-managed third-party connection helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+class MissingConnectionError(RuntimeError):
+    """Raised when plugin code requires a connection that is not connected."""
+
+
+@dataclass
+class ConnectionStatus:
+    id: str
+    provider: str
+    label: str
+    auth: str = "oauth2"
+    scopes: list[str] = field(default_factory=list)
+    required: bool = False
+    status: str = "available"
+    account_label: str | None = None
+    granted_scopes: list[str] = field(default_factory=list)
+    expires_at: str | None = None
+    connected_at: str | None = None
+    last_error: str | None = None
+
+    @property
+    def connected(self) -> bool:
+        return self.status in {"connected", "expiring"}
+
+
+def _to_status(raw: dict[str, Any]) -> ConnectionStatus:
+    return ConnectionStatus(
+        id=str(raw.get("id") or raw.get("connection_id") or ""),
+        provider=str(raw.get("provider") or "custom"),
+        label=str(raw.get("label") or raw.get("id") or raw.get("connection_id") or ""),
+        auth=str(raw.get("auth") or "oauth2"),
+        scopes=list(raw.get("scopes") or []),
+        required=bool(raw.get("required") or False),
+        status=str(raw.get("status") or "available"),
+        account_label=raw.get("account_label"),
+        granted_scopes=list(raw.get("granted_scopes") or []),
+        expires_at=raw.get("expires_at"),
+        connected_at=raw.get("connected_at"),
+        last_error=raw.get("last_error"),
+    )
+
+
+class PluginConnectionsClient:
+    """Access install-scoped third-party connections for a plugin."""
+
+    def __init__(self, adapter: Any | None = None, local_connections: dict[str, Any] | None = None):
+        self._adapter = adapter
+        self._local_connections = local_connections or {}
+
+    async def list(self) -> list[ConnectionStatus]:
+        if self._adapter is not None and hasattr(self._adapter, "list"):
+            return [_to_status(item) for item in await self._adapter.list()]
+        return [_to_status(item) for item in self._local_connections.values()]
+
+    async def status(self, connection_id: str) -> ConnectionStatus:
+        if self._adapter is not None and hasattr(self._adapter, "status"):
+            return _to_status(await self._adapter.status(connection_id))
+        raw = self._local_connections.get(connection_id) or {"id": connection_id, "status": "available"}
+        return _to_status(raw)
+
+    async def require(self, connection_id: str) -> ConnectionStatus:
+        status = await self.status(connection_id)
+        if not status.connected:
+            raise MissingConnectionError(f"Palette connection is not configured: {connection_id}")
+        return status
+
+    async def access_token(self, connection_id: str) -> str:
+        if self._adapter is not None and hasattr(self._adapter, "access_token"):
+            token = await self._adapter.access_token(connection_id)
+            if token:
+                return str(token)
+        status = await self.require(connection_id)
+        if status.connected:
+            return f"palette-local-token:{connection_id}:{int(datetime.now(timezone.utc).timestamp())}"
+        raise MissingConnectionError(f"Palette connection is not configured: {connection_id}")

package/backend-sdk/palette_sdk/events.py

@@ -52,3 +52,15 @@ def drain_pending() -> list[tuple[str, Handler]]:
     out = list(_pending)
     _pending.clear()
     return out
+
+
+class EventPublisher:
+    """Publish app-owned events declared in palette-plugin.json provides.events."""
+
+    def __init__(self, adapter: Any = None):
+        self._adapter = adapter
+
+    async def publish(self, topic: str, payload: dict[str, Any] | None = None) -> None:
+        if self._adapter is None:
+            raise RuntimeError("Palette event publisher is not available in this runtime")
+        await self._adapter.publish(topic, payload or {})

package/backend-sdk/palette_sdk/manifest.py

@@ -83,6 +83,57 @@ class SecretSpec(BaseModel):
     validate_pattern: str | None = Field(default=None, alias="validate")
 
 
+class ConnectionSpec(BaseModel):
+    id: str
+    provider: Literal["google", "instagram", "slack", "linear", "hubspot", "stripe", "zendesk", "custom"]
+    label: str
+    auth: Literal["oauth2", "api_key"] = "oauth2"
+    scopes: list[str] = Field(default_factory=list)
+    required: bool = False
+
+
+class AppServiceRouteSpec(BaseModel):
+    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+    path: str
+    operation_id: str | None = None
+    description: str = ""
+
+
+class ProvidedAppServiceSpec(BaseModel):
+    id: str
+    version: str | None = None
+    label: str | None = None
+    description: str = ""
+    permissions: list[str] = Field(default_factory=list)
+    routes: list[AppServiceRouteSpec] = Field(default_factory=list)
+
+
+class AppDependencySpec(BaseModel):
+    id: str
+    version: str | None = None
+    required: bool = True
+    reason: str = ""
+
+
+class ServiceDependencySpec(BaseModel):
+    id: str
+    version: str | None = None
+    required: bool = True
+    reason: str = ""
+    provider: str | None = None
+
+
+class ProvidesSpec(BaseModel):
+    services: list[ProvidedAppServiceSpec] = Field(default_factory=list)
+    events: list[str] = Field(default_factory=list)
+
+
+class RequiresSpec(BaseModel):
+    apps: list[AppDependencySpec] = Field(default_factory=list)
+    services: list[ServiceDependencySpec] = Field(default_factory=list)
+    events: list[str] = Field(default_factory=list)
+
+
 class PlatformServiceSpec(BaseModel):
     required: bool = False
     billing: Literal["org_wallet", "plugin_owner", "platform"] | None = None
@@ -113,6 +164,9 @@ class PluginManifest(BaseModel):
     tools: list[ToolEntry] = Field(default_factory=list)
     permissions: list[str] = Field(default_factory=list)
     secrets: dict[str, SecretSpec] = Field(default_factory=dict)
+    connections: list[ConnectionSpec] = Field(default_factory=list)
+    provides: ProvidesSpec | None = None
+    requires: RequiresSpec | None = None
     platform_services: list[Literal["llm", "redis", "storage", "vector"]] | dict[str, PlatformServiceSpec] = Field(default_factory=list)
     rating: float = 0.0
     reviews: int = 0

package/backend-sdk/palette_sdk/plugin_context.py

@@ -11,8 +11,11 @@ from fastapi import Depends, Request
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from palette_sdk.data_rooms import DataRoomsClient
+from palette_sdk.connections import PluginConnectionsClient
+from palette_sdk.apps import AppInteropClient
 from palette_sdk.members import OrganizationMembersClient
 from palette_sdk.platform_services import UnavailablePlatformService
+from palette_sdk.events import EventPublisher
 
 
 class MissingSecretError(KeyError):
@@ -46,9 +49,12 @@ class PluginContext:
     permissions: list[str] = field(default_factory=list)
     storage: Any = None  # Platform storage service injected at runtime
     data_rooms: DataRoomsClient = field(default_factory=DataRoomsClient)
+    connections: PluginConnectionsClient = field(default_factory=PluginConnectionsClient)
+    apps: AppInteropClient = field(default_factory=AppInteropClient)
     members: OrganizationMembersClient = field(default_factory=OrganizationMembersClient)
     redis: Any = field(default_factory=lambda: UnavailablePlatformService("redis"))
     vector: Any = field(default_factory=lambda: UnavailablePlatformService("vector"))
+    events: EventPublisher = field(default_factory=EventPublisher)
     config: dict[str, Any] = field(default_factory=dict)
     logger: logging.Logger = field(default_factory=lambda: logging.getLogger("palette_sdk.plugin"))
 
@@ -113,12 +119,18 @@ async def get_plugin_context(request: Request) -> PluginContext:
         permissions=getattr(state, "plugin_permissions", []),
         storage=getattr(state, "storage", None) or UnavailablePlatformService("storage"),
         data_rooms=DataRoomsClient(getattr(state, "data_rooms", None)),
+        connections=PluginConnectionsClient(
+            getattr(state, "plugin_connections", None),
+            getattr(state, "plugin_local_connections", None),
+        ),
+        apps=AppInteropClient(getattr(state, "plugin_apps", None)),
         members=OrganizationMembersClient(
             getattr(state, "org_members", None),
             getattr(state, "plugin_permissions", []),
         ),
         redis=getattr(state, "redis", None) or UnavailablePlatformService("redis"),
         vector=getattr(state, "vector", None) or UnavailablePlatformService("vector"),
+        events=EventPublisher(getattr(state, "plugin_events", None)),
         config=getattr(state, "plugin_config", {}),
         logger=getattr(state, "plugin_logger", logging.getLogger(f"palette_sdk.plugin.{getattr(state, 'plugin_id', 'unknown')}")),
     )

package/docs/python-backend-sdk.md

@@ -112,7 +112,10 @@ Available context values:
 | `ctx.permissions` | Permissions granted from `palette-plugin.json` |
 | `ctx.storage` | Runtime storage service, when available |
 | `ctx.data_rooms` | Backend Data Room client |
+| `ctx.connections` | Palette-managed third-party connection client |
 | `ctx.members` | Current organisation member client |
+| `ctx.apps` | Governed app-to-app calls through declared `requires` contracts |
+| `ctx.events` | Publish event topics declared in `provides.events` |
 | `ctx.redis` | Plugin/org-scoped Redis-style service when `platform_services` includes `redis` |
 | `ctx.vector` | Plugin/org-scoped vector service when `platform_services` includes `vector` |
 | `ctx.config` | App install/config values |
@@ -138,6 +141,7 @@ These are the public Python helpers exported by `palette_sdk`.
 | `KNOWN_PERMISSIONS`, `is_known_permission(...)` | Permission vocabulary checks for manifests/tools |
 | `DataRoomsClient`, `ctx.data_rooms` | Backend Data Room room/folder/file helpers |
 | `OrganizationMembersClient`, `ctx.members` | Current-organization member lookup, invite, and role helpers |
+| `AppInteropClient`, `ctx.apps` | Call required apps/services without direct database access |
 | `OrgRepository`, `ctx.repo(Model)` | Org-safe convenience CRUD for app-owned models |
 | `PluginBase`, `OrgScopedTable` | SQLAlchemy declarative bases for plugin-owned tables |
 | `ensure_org_rls(op, table)` | Alembic helper that enables org row-level security |
@@ -146,7 +150,7 @@ These are the public Python helpers exported by `palette_sdk`.
 | `LocalRedisService`, `LocalVectorService` | Local `pltt dev` service emulators and test fakes |
 | `PlatformServiceUnavailable`, `UnavailablePlatformService` | Clear errors when an undeclared platform service is used |
 | `LifecycleHooks` | Install/update/enable/disable/uninstall callbacks |
-| `Event`, `subscribe_event(...)` | In-process platform event subscriptions |
+| `Event`, `EventPublisher`, `subscribe_event(...)` | In-process event subscriptions and declared app event publishing |
 | `sign_webhook(...)`, `verify_webhook_signature(...)` | HMAC-SHA256 webhook signing and verification |
 | `ToolDefinition` | Base class for custom agent tools |
 | `PluginManifest`, `load_manifest(...)` | Typed manifest parsing from `palette-plugin.json` |
@@ -654,6 +658,88 @@ Palette scopes every Redis key and vector operation by `plugin_id` and
 `organization_id`; hosted previews also include the publish id. Plugin code
 cannot read, list, update, or delete records owned by another app or org.
 
+## 10. Managed Connections
+
+Declare third-party OAuth or API-key connections in `palette-plugin.json`.
+Palette renders them in the installed app's Settings > Connect tab and stores
+connected token state encrypted per organisation install.
+
+```json
+{
+  "connections": [
+    {
+      "id": "google_calendar",
+      "provider": "google",
+      "label": "Google Calendar",
+      "auth": "oauth2",
+      "scopes": ["https://www.googleapis.com/auth/calendar.readonly"]
+    }
+  ]
+}
+```
+
+```python
+status = await ctx.connections.status("google_calendar")
+connected = await ctx.connections.require("google_calendar")
+token = await ctx.connections.access_token("google_calendar")
+```
+
+`pltt dev` mocks declared connections. Override local states with
+`.palette/connections.local.json`.
+
+## 11. App-To-App Services
+
+Apps can expose governed services and depend on services from other installed
+apps. Declare provider capabilities with `provides`:
+
+```json
+{
+  "provides": {
+    "services": [
+      {
+        "id": "org.hierarchy",
+        "version": "1.0.0",
+        "routes": [
+          { "method": "GET", "path": "/hierarchy/approval-chain/{user_id}" }
+        ]
+      }
+    ],
+    "events": ["hierarchy.updated"]
+  }
+}
+```
+
+Consumers declare dependencies with `requires`:
+
+```json
+{
+  "requires": {
+    "services": [
+      { "id": "org.hierarchy", "version": "^1.0.0", "reason": "Approval routing" }
+    ]
+  }
+}
+```
+
+Then call through `ctx.apps`; never read another app's database directly. If
+the same app emits `leave.requested`, declare that topic under its own
+`provides.events` first:
+
+```python
+chain = await ctx.apps.service("org.hierarchy").get(f"/hierarchy/approval-chain/{ctx.user_id}")
+await ctx.events.publish("leave.requested", {"next_approver_id": chain["next_approver_id"]})
+```
+
+Local mocks live in `.palette/app-services.local.json`:
+
+```json
+{
+  "org.hierarchy GET /hierarchy/approval-chain/dev-user": {
+    "next_approver_id": "manager-1"
+  }
+}
+```
+
 Palette scopes storage the same way. Files written through `ctx.storage` or the
 frontend storage client live under:
 

package/lib/commands/test.js

@@ -8,8 +8,8 @@ const { bundleFrontend, bundleBackend } = require("../bundler")
 const { declaredSecrets, loadLocalEnv } = require("../secrets")
 const buildCommand = require("./build")
 
-const DEFAULT_FRONTEND_BUNDLE_LIMIT = 2 * 1024 * 1024
-const DEFAULT_BACKEND_BUNDLE_LIMIT = 5 * 1024 * 1024
+const DEFAULT_FRONTEND_BUNDLE_LIMIT = 15 * 1024 * 1024
+const DEFAULT_BACKEND_BUNDLE_LIMIT = 15 * 1024 * 1024
 
 function reporter(json, results) {
   return {
@@ -705,6 +705,17 @@ async function run(args, { cwd }) {
   }
   if ((manifest.permissions || []).length) out.ok("declared permissions are known")
 
+  if (manifest.provides || manifest.requires) {
+    const providedServices = manifest.provides?.services?.map((item) => item.id).filter(Boolean) || []
+    const requiredServices = manifest.requires?.services?.map((item) => item.id).filter(Boolean) || []
+    const requiredApps = manifest.requires?.apps?.map((item) => item.id).filter(Boolean) || []
+    out.ok("app-to-app contracts are valid", {
+      provides_services: providedServices,
+      requires_services: requiredServices,
+      requires_apps: requiredApps,
+    })
+  }
+
   if (manifest.frontend?.entry && manifest.frontend.sandbox === false) {
     failures += out.fail(
       "appstore frontend must be sandboxed",

package/lib/dev-simulator.js

@@ -51,6 +51,58 @@ function needsDatabase(manifest) {
   return Boolean(manifest.database || manifest.capabilities?.database)
 }
 
+function loadLocalConnections(cwd, manifest) {
+  const declared = Array.isArray(manifest.connections) ? manifest.connections : []
+  const out = {}
+  for (const conn of declared) {
+    if (!conn || !conn.id) continue
+    out[conn.id] = {
+      id: conn.id,
+      provider: conn.provider || "custom",
+      label: conn.label || conn.id,
+      auth: conn.auth || "oauth2",
+      scopes: conn.scopes || [],
+      required: Boolean(conn.required),
+      status: "available",
+      account_label: null,
+      granted_scopes: [],
+      expires_at: null,
+      connected_at: null,
+      last_error: null,
+    }
+  }
+  const localPath = path.join(cwd, ".palette", "connections.local.json")
+  if (!fs.existsSync(localPath)) return out
+  try {
+    const raw = JSON.parse(fs.readFileSync(localPath, "utf8"))
+    const overrides = Array.isArray(raw) ? raw : Object.entries(raw).map(([id, value]) => ({ id, ...(value || {}) }))
+    for (const item of overrides) {
+      if (!item || !item.id || !out[item.id]) continue
+      out[item.id] = {
+        ...out[item.id],
+        ...item,
+        id: item.id,
+        granted_scopes: item.granted_scopes || item.scopes || out[item.id].scopes || [],
+      }
+    }
+  } catch (err) {
+    console.warn(`[pltt] could not parse .palette/connections.local.json: ${err.message}`)
+  }
+  return out
+}
+
+function loadLocalAppServiceMocks(cwd) {
+  const mockPath = path.join(cwd, ".palette", "app-services.local.json")
+  if (!fs.existsSync(mockPath)) return {}
+  try {
+    const parsed = JSON.parse(fs.readFileSync(mockPath, "utf8"))
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  } catch (err) {
+    console.warn(`[pltt] could not parse .palette/app-services.local.json: ${err.message}`)
+    return {}
+  }
+}
+
 function ensurePythonEnv(cwd, devDir, manifest) {
   const hostPython = process.env.PALETTE_PYTHON || "python3"
   const venvDir = path.join(devDir, "backend-venv")
@@ -98,6 +150,8 @@ function writeBackendRunner(cwd, devDir, manifest, backendEntry) {
   const sdkPath = localBackendSdkPath()
   const databasePath = path.join(devDir, `${manifest.id}.sqlite3`)
   const devSecrets = loadLocalEnv(cwd, { apply: false })
+  const devConnections = loadLocalConnections(cwd, manifest)
+  const devAppMocks = loadLocalAppServiceMocks(cwd)
   const content = `from __future__ import annotations
 
 import importlib
@@ -119,6 +173,8 @@ SDK_PATH = ${JSON.stringify(sdkPath || "")}
 DATABASE_ENABLED = bool(MANIFEST.get("database") or MANIFEST.get("capabilities", {}).get("database"))
 DATABASE_URL = os.environ.get("PALETTE_DEV_DATABASE_URL", "sqlite+aiosqlite:///${databasePath.replace(/\\/g, "/")}")
 DEV_SECRETS = json.loads(${JSON.stringify(JSON.stringify(devSecrets))})
+DEV_CONNECTIONS = json.loads(${JSON.stringify(JSON.stringify(devConnections))})
+DEV_APP_MOCKS = json.loads(${JSON.stringify(JSON.stringify(devAppMocks))})
 
 def _service_enabled(name: str) -> bool:
     services = MANIFEST.get("platform_services") or []
@@ -153,6 +209,39 @@ if _service_enabled("storage"):
         organization_name="Palette Dev",
     )
 
+class LocalAppInteropService:
+    def service(self, service_id: str):
+        return LocalAppServiceClient(service_id)
+
+    async def call(self, app_id: str, path: str, *, method: str = "GET", json_body=None, timeout: float = 30.0):
+        key = app_id + " " + method.upper() + " " + path
+        if key in DEV_APP_MOCKS:
+            return DEV_APP_MOCKS[key]
+        raise RuntimeError("No local app mock configured for " + key)
+
+    async def call_service(self, service_id: str, path: str, *, method: str = "GET", json_body=None, timeout: float = 30.0):
+        key = service_id + " " + method.upper() + " " + path
+        if key in DEV_APP_MOCKS:
+            return DEV_APP_MOCKS[key]
+        raise RuntimeError("No local app service mock configured for " + key)
+
+class LocalAppServiceClient:
+    def __init__(self, service_id: str):
+        self.service_id = service_id
+
+    async def call(self, path: str, *, method: str = "GET", json=None, timeout: float = 30.0):
+        return await LocalAppInteropService().call_service(self.service_id, path, method=method, json_body=json, timeout=timeout)
+
+    async def get(self, path: str, **kwargs):
+        return await self.call(path, method="GET", **kwargs)
+
+    async def post(self, path: str, json=None, **kwargs):
+        return await self.call(path, method="POST", json=json, **kwargs)
+
+class LocalEventPublisher:
+    async def publish(self, topic: str, payload=None):
+        print("[palette-event]", topic, json.dumps(payload or {}, sort_keys=True))
+
 spec = importlib.util.spec_from_file_location("palette_local_backend", ENTRY)
 module = importlib.util.module_from_spec(spec)
 assert spec and spec.loader
@@ -190,6 +279,9 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
             "secret_specs": MANIFEST.get("secrets") or {},
             "secret_scope": "dev",
         }
+        request.state.plugin_local_connections = DEV_CONNECTIONS
+        request.state.plugin_apps = LocalAppInteropService()
+        request.state.plugin_events = LocalEventPublisher()
         request.state.storage = DEV_STORAGE
         if DEV_REDIS is not None:
             request.state.redis = DEV_REDIS
@@ -251,7 +343,8 @@ function startBackend(cwd, devDir, manifest, backendPort) {
   return child
 }
 
-function simulatorEntrySource(pluginEntry, manifest, backendPort) {
+function simulatorEntrySource(cwd, pluginEntry, manifest, backendPort) {
+  const localConnections = loadLocalConnections(cwd, manifest)
   return `
 import React from "react"
 import { createRoot } from "react-dom/client"
@@ -259,9 +352,45 @@ import { PluginProvider } from "@palettelab/sdk"
 import Plugin from ${JSON.stringify(pluginEntry)}
 
 const backendBase = "http://127.0.0.1:${backendPort}"
+const localConnections = ${JSON.stringify(localConnections)}
+
+function connectionListResponse() {
+  return new Response(JSON.stringify(Object.values(localConnections)), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  })
+}
 
 async function apiFetch(path, init) {
   const target = String(path || "")
+  const method = String(init?.method || "GET").toUpperCase()
+  const connectionPrefix = "/api/v1/app-installs/" + encodeURIComponent(${JSON.stringify(manifest.id)}) + "/connections"
+  if (target === connectionPrefix && method === "GET") {
+    return connectionListResponse()
+  }
+  if (target.startsWith(connectionPrefix + "/") && target.endsWith("/authorize") && method === "POST") {
+    const id = decodeURIComponent(target.slice((connectionPrefix + "/").length, -"/authorize".length))
+    if (localConnections[id]) {
+      localConnections[id] = {
+        ...localConnections[id],
+        status: "connected",
+        account_label: localConnections[id].account_label || "Local mock account",
+        granted_scopes: localConnections[id].granted_scopes?.length ? localConnections[id].granted_scopes : localConnections[id].scopes,
+        connected_at: new Date().toISOString(),
+      }
+    }
+    return new Response(JSON.stringify({ connection_id: id, authorize_url: "palette-local://connected", mode: "mock" }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+  if (target.startsWith(connectionPrefix + "/") && method === "DELETE") {
+    const id = decodeURIComponent(target.slice((connectionPrefix + "/").length))
+    if (localConnections[id]) {
+      localConnections[id] = { ...localConnections[id], status: "available", account_label: null, connected_at: null, granted_scopes: [] }
+    }
+    return new Response(null, { status: 204 })
+  }
   if (target.startsWith("http://") || target.startsWith("https://")) {
     return fetch(target, init)
   }
@@ -404,7 +533,7 @@ async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
   if (!fs.existsSync(absEntry)) throw new Error(`frontend entry not found: ${entry}`)
   const generatedEntry = path.join(devDir, "simulator-entry.jsx")
   const bundlePath = path.join(devDir, "simulator.js")
-  fs.writeFileSync(generatedEntry, simulatorEntrySource(absEntry, manifest, backendPort))
+  fs.writeFileSync(generatedEntry, simulatorEntrySource(cwd, absEntry, manifest, backendPort))
   const buildConfig = frontendBuildConfig(cwd, { ...(manifest.frontend || {}), entry })
 
   const esbuild = loadEsbuild()

package/lib/manifest.js

@@ -49,7 +49,10 @@ const TOP_LEVEL_KEYS = new Set([
   "database",
   "scheduled_jobs",
   "secrets",
+  "connections",
   "platform_services",
+  "provides",
+  "requires",
 ])
 
 function loadManifest(cwd) {
@@ -173,6 +176,205 @@ function validatePlatformServices(value, errors) {
   }
 }
 
+const CONNECTION_PROVIDERS = new Set([
+  "google",
+  "instagram",
+  "slack",
+  "linear",
+  "hubspot",
+  "stripe",
+  "zendesk",
+  "custom",
+])
+
+function validateConnections(value, errors) {
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    errors.push("connections must be an array")
+    return
+  }
+  const seen = new Set()
+  value.forEach((conn, i) => {
+    const label = `connections[${i}]`
+    if (!isObject(conn)) {
+      errors.push(`${label} must be an object`)
+      return
+    }
+    unknownKeys(conn, new Set(["id", "provider", "label", "auth", "scopes", "required"]), label, errors)
+    if (!conn.id || typeof conn.id !== "string" || !/^[a-z0-9][a-z0-9_-]*[a-z0-9]$/.test(conn.id)) {
+      errors.push(`${label}.id must be lowercase snake/kebab case`)
+    } else if (seen.has(conn.id)) {
+      errors.push(`duplicate connection id: ${conn.id}`)
+    }
+    seen.add(conn.id)
+    if (!conn.provider || typeof conn.provider !== "string" || !CONNECTION_PROVIDERS.has(conn.provider)) {
+      errors.push(`${label}.provider must be one of ${Array.from(CONNECTION_PROVIDERS).join(", ")}`)
+    }
+    if (!conn.label || typeof conn.label !== "string") errors.push(`${label}.label is required`)
+    if (conn.auth !== undefined && conn.auth !== "oauth2" && conn.auth !== "api_key") {
+      errors.push(`${label}.auth must be oauth2 or api_key`)
+    }
+    if (conn.scopes !== undefined) {
+      if (!Array.isArray(conn.scopes)) {
+        errors.push(`${label}.scopes must be an array`)
+      } else {
+        const scopeSeen = new Set()
+        for (const scope of conn.scopes) {
+          if (typeof scope !== "string" || scope.trim() === "") {
+            errors.push(`${label}.scopes entries must be non-empty strings`)
+          } else if (scopeSeen.has(scope)) {
+            errors.push(`${label}.scopes contains duplicate scope: ${scope}`)
+          }
+          scopeSeen.add(scope)
+        }
+      }
+    }
+    requireBoolean(conn, "required", label, errors)
+  })
+}
+
+function isCapabilityId(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value)
+}
+
+function validateServiceRoutes(value, label, errors) {
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    errors.push(`${label}.routes must be an array`)
+    return
+  }
+  const methods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"])
+  value.forEach((route, i) => {
+    const routeLabel = `${label}.routes[${i}]`
+    if (!isObject(route)) {
+      errors.push(`${routeLabel} must be an object`)
+      return
+    }
+    unknownKeys(route, new Set(["method", "path", "operation_id", "description"]), routeLabel, errors)
+    if (!methods.has(String(route.method || "").toUpperCase())) {
+      errors.push(`${routeLabel}.method must be one of ${Array.from(methods).join(", ")}`)
+    }
+    if (typeof route.path !== "string" || !route.path.startsWith("/")) {
+      errors.push(`${routeLabel}.path must start with '/'`)
+    }
+    requireString(route, "operation_id", routeLabel, errors)
+    requireString(route, "description", routeLabel, errors)
+  })
+}
+
+function validateProvides(value, errors) {
+  if (value === undefined) return
+  if (!isObject(value)) {
+    errors.push("provides must be an object")
+    return
+  }
+  unknownKeys(value, new Set(["services", "events"]), "provides", errors)
+  if (value.services !== undefined) {
+    if (!Array.isArray(value.services)) {
+      errors.push("provides.services must be an array")
+    } else {
+      const seen = new Set()
+      value.services.forEach((service, i) => {
+        const label = `provides.services[${i}]`
+        if (!isObject(service)) {
+          errors.push(`${label} must be an object`)
+          return
+        }
+        unknownKeys(service, new Set(["id", "version", "label", "description", "permissions", "routes"]), label, errors)
+        if (!isCapabilityId(service.id)) {
+          errors.push(`${label}.id must be a dotted lowercase capability id`)
+        } else if (seen.has(service.id)) {
+          errors.push(`duplicate provided service id: ${service.id}`)
+        }
+        seen.add(service.id)
+        if (service.version !== undefined && !isSemverRange(service.version)) errors.push(`${label}.version must be a semver range`)
+        requireString(service, "label", label, errors)
+        requireString(service, "description", label, errors)
+        if (service.permissions !== undefined) {
+          if (!Array.isArray(service.permissions)) {
+            errors.push(`${label}.permissions must be an array`)
+          } else {
+            for (const permission of service.permissions) {
+              if (typeof permission !== "string" || !KNOWN_PERMISSIONS.has(permission)) {
+                errors.push(`${label}.permissions contains unknown permission: ${permission}`)
+              }
+            }
+          }
+        }
+        validateServiceRoutes(service.routes, label, errors)
+      })
+    }
+  }
+  if (value.events !== undefined) {
+    if (!Array.isArray(value.events)) {
+      errors.push("provides.events must be an array")
+    } else {
+      for (const event of value.events) {
+        if (!isCapabilityId(event)) errors.push(`provides.events entries must be dotted lowercase topics: ${event}`)
+      }
+    }
+  }
+}
+
+function validateRequires(value, errors) {
+  if (value === undefined) return
+  if (!isObject(value)) {
+    errors.push("requires must be an object")
+    return
+  }
+  unknownKeys(value, new Set(["apps", "services", "events"]), "requires", errors)
+  if (value.apps !== undefined) {
+    if (!Array.isArray(value.apps)) {
+      errors.push("requires.apps must be an array")
+    } else {
+      value.apps.forEach((dep, i) => {
+        const label = `requires.apps[${i}]`
+        if (!isObject(dep)) {
+          errors.push(`${label} must be an object`)
+          return
+        }
+        unknownKeys(dep, new Set(["id", "version", "required", "reason"]), label, errors)
+        if (typeof dep.id !== "string" || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(dep.id)) {
+          errors.push(`${label}.id must be lowercase kebab-case`)
+        }
+        if (dep.version !== undefined && !isSemverRange(dep.version)) errors.push(`${label}.version must be a semver range`)
+        requireBoolean(dep, "required", label, errors)
+        requireString(dep, "reason", label, errors)
+      })
+    }
+  }
+  if (value.services !== undefined) {
+    if (!Array.isArray(value.services)) {
+      errors.push("requires.services must be an array")
+    } else {
+      value.services.forEach((dep, i) => {
+        const label = `requires.services[${i}]`
+        if (!isObject(dep)) {
+          errors.push(`${label} must be an object`)
+          return
+        }
+        unknownKeys(dep, new Set(["id", "version", "required", "reason", "provider"]), label, errors)
+        if (!isCapabilityId(dep.id)) errors.push(`${label}.id must be a dotted lowercase capability id`)
+        if (dep.version !== undefined && !isSemverRange(dep.version)) errors.push(`${label}.version must be a semver range`)
+        requireBoolean(dep, "required", label, errors)
+        requireString(dep, "reason", label, errors)
+        if (dep.provider !== undefined && (typeof dep.provider !== "string" || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(dep.provider))) {
+          errors.push(`${label}.provider must be lowercase kebab-case`)
+        }
+      })
+    }
+  }
+  if (value.events !== undefined) {
+    if (!Array.isArray(value.events)) {
+      errors.push("requires.events must be an array")
+    } else {
+      for (const event of value.events) {
+        if (!isCapabilityId(event)) errors.push(`requires.events entries must be dotted lowercase topics: ${event}`)
+      }
+    }
+  }
+}
+
 function validateManifest(m) {
   const errors = []
   if (!isObject(m)) return ["manifest must be an object"]
@@ -239,7 +441,10 @@ function validateManifest(m) {
   }
 
   validateSecrets(m.secrets, errors)
+  validateConnections(m.connections, errors)
   validatePlatformServices(m.platform_services, errors)
+  validateProvides(m.provides, errors)
+  validateRequires(m.requires, errors)
 
   if (m.sdk) {
     if (!isObject(m.sdk)) errors.push("sdk must be an object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.42",
+  "version": "0.3.43",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.16"
+    "@palettelab/sdk": "^0.1.17"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/palette-plugin.json

@@ -42,6 +42,7 @@
   },
   "agents": [],
   "tools": [],
+  "connections": [],
   "permissions": [
     "data_rooms:read",
     "tasks:read",

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.16",
+    "@palettelab/sdk": "^0.1.17",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.16", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.17", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/README.md

@@ -2,3 +2,7 @@
 
 Calls a third-party API. Notice the manifest declares `capabilities.external_network`
 — the platform enforces this allowlist at runtime.
+
+It also declares a Palette-managed `connections` entry. In `pltt dev`, use
+`.palette/connections.local.json` to mock connection states. After install,
+org admins connect the real service from the app Settings > Connect tab.

package/template-fallback/templates/external-service/backend/api/main.py

@@ -20,9 +20,10 @@ EXTERNAL_HOST = "https://api.example.com"
 async def proxy(ctx: PluginContext = Depends(get_plugin_context)) -> dict:
     import httpx
 
+    connection = await ctx.connections.status("example_oauth")
     token = os.environ.get("EXAMPLE_API_TOKEN")
     if not token:
         raise HTTPException(status_code=500, detail="EXAMPLE_API_TOKEN not configured")
     async with httpx.AsyncClient() as client:
         r = await client.get(f"{EXTERNAL_HOST}/v1/ping", headers={"Authorization": f"Bearer {token}"})
-        return {"upstream_status": r.status_code, "body": r.text[:200]}
+        return {"connection": connection.status, "upstream_status": r.status_code, "body": r.text[:200]}

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.16", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.17", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/palette-plugin.json

@@ -22,5 +22,15 @@
   },
   "frontend": { "entry": "./frontend/src/index.tsx", "sandbox": true },
   "backend": { "entry": "./backend/api/main.py" },
-  "permissions": ["resources:read"]
+  "permissions": ["resources:read"],
+  "connections": [
+    {
+      "id": "example_oauth",
+      "provider": "custom",
+      "label": "Example OAuth",
+      "auth": "oauth2",
+      "scopes": ["read"],
+      "required": false
+    }
+  ]
 }

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.16",
+    "@palettelab/sdk": "^0.1.17",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/next/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.16",
+    "@palettelab/sdk": "^0.1.17",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/palette-app/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.16",
+    "@palettelab/sdk": "^0.1.17",
     "react": "^19.0.0"
   },
   "devDependencies": {