commit dfce6f241d84503f882985daa0e73c5828d24ef9 Author: Caelum Date: Thu Nov 5 18:52:29 2026 +0300 feat: Scribase plugin for Hermes Agent — scribase_create_project tool Provisions a hosted Postgres backend project on Scribase (api.scribase.com) via its public REST API and returns the new environment's connection string and API keys. Registers a single tool (ctx.register_tool) and reads its API key through Hermes's secret scope (agent.secret_scope.get_secret); no other Hermes surfaces, no third-party dependencies. Co-Authored-By: Claude Sonnet 5 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e52f13f --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Scribase + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..aeccd84 --- /dev/null +++ b/README.md @@ -0,0 +1,76 @@ +# Scribase plugin for Hermes Agent + +Lets a [Hermes Agent](https://github.com/NousResearch/hermes-agent) provision +a real hosted Postgres backend on [Scribase](https://scribase.com) — a +Postgres-as-a-service with a Supabase-API-compatible REST/Auth/Storage/ +Realtime/Functions surface — without the user leaving the chat. + +## What it does + +Registers one tool, `scribase_create_project`, that: + +1. Creates (or confirms) a project inside an existing Scribase organization. +2. Creates the project's first environment (`production` by default). +3. Polls until the environment finishes provisioning (bounded: it returns a + `"status": "provisioning"` result with the operation id instead of + hanging forever if it isn't ready yet — see "Disclosure" below). +4. Returns the new environment's Postgres connection URI and its API keys + (`anon_key`, `service_role_key`, `publishable_key`, `secret_key`, + `api_url`). + +That's it — no other tools, no hooks, no middleware, no CLI/slash commands. + +## Setup + +1. Have a Scribase account and organization (`scribase.com`). +2. Create an organization API key: console → **Organization → API tokens**, + or `POST /v1/organizations/{org}/api-keys` against the [Scribase Control + API](https://docs.scribase.com/docs/api). +3. Install the plugin and set `SCRIBASE_API_KEY` when Hermes prompts for it + (or add it to your Hermes profile's `.env`). + +```bash +hermes plugins install scribase +``` + +### Optional: self-hosted Scribase + +If you run your own Scribase cluster instead of the hosted +`api.scribase.com`, set the plugin's `api_base_url` config key to your +gateway's base URL (e.g. `https://api.your-domain.com`). This is a plain +URL, not a secret. + +## Disclosure (Hermes plugin-catalog rule 13) + +- **Hermes surfaces used:** `ctx.register_tool` only. No hooks, no + middleware, no CLI/slash commands, no runtime overrides of Hermes + internals. +- **Network calls:** only to the Scribase management API + (`https://api.scribase.com` by default, or the operator's own + `api_base_url` for a self-hosted cluster). No other host is contacted and + no telemetry is sent anywhere. +- **Credentials:** the plugin stores no credentials of its own. It reads + `SCRIBASE_API_KEY` exclusively through Hermes's secret scope + (`agent.secret_scope.get_secret`), never from `os.environ` directly, a + `.env` file, or any other local store. +- **Side effects:** calling the tool creates real, billable resources in + the user's Scribase organization (a project and a Postgres environment). + It does not delete, suspend, or modify anything that already exists. +- **Long-running behavior:** the tool call itself blocks for up to roughly + 30 seconds while polling the new environment's provisioning operation. If + provisioning is not done by then, it returns a `"status": "provisioning"` + result with the operation id instead of blocking indefinitely, so it + cannot hang an unattended run (cron, messaging gateway). +- **No UI:** this is a pure tool-call plugin. No screens, no Desktop + surface. +- **No self-updating code:** the plugin does not fetch or replace its own + files. Updates reach users only through a new pinned commit in the + Hermes plugin catalog. + +## Dependencies + +None beyond the Python standard library (`urllib`, `json`, `uuid`, `time`). + +## License + +MIT — see [LICENSE](./LICENSE). diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..fa46d15 --- /dev/null +++ b/__init__.py @@ -0,0 +1,64 @@ +"""Scribase plugin for Hermes Agent — registration. + +Registers exactly one tool, `scribase_create_project`, that provisions a +new hosted Postgres backend project on Scribase (https://api.scribase.com) +through its public REST API and returns the new environment's connection +string and API keys. + +Hermes surfaces used: `ctx.register_tool` only. No hooks, no middleware, no +CLI/slash commands, no runtime overrides of Hermes internals. + +Network calls: only to `api_base_url` (default `https://api.scribase.com`, +overridable for a self-hosted Scribase cluster via the plugin's +`api_base_url` config key, never a secret) — see tools.py. + +Credentials: the Scribase organization API key is read through Hermes's +secret scope (`agent.secret_scope.get_secret("SCRIBASE_API_KEY")`), per the +plugin-catalog's credential rule. This plugin never reads `.env` files or +`os.environ` directly, and stores no credentials of its own. +""" + +from __future__ import annotations + +import json +import logging + +from agent.secret_scope import get_secret + +from . import schemas, tools + +logger = logging.getLogger(__name__) + +_DEFAULT_API_BASE = "https://api.scribase.com" + + +def register(ctx) -> None: + """Wire the `scribase_create_project` tool to the Scribase REST client.""" + + def _handle_create_project(args: dict, **kwargs) -> str: + api_key = get_secret("SCRIBASE_API_KEY") or "" + if not api_key: + return json.dumps({ + "error": ( + "SCRIBASE_API_KEY is not set. Create a Scribase organization " + "API key (console: Organization -> API tokens, or " + "POST /v1/organizations/{org}/api-keys) and configure it for " + "this plugin." + ), + }) + api_base = str( + ctx.get_config("api_base_url", _DEFAULT_API_BASE) or _DEFAULT_API_BASE + ).strip().rstrip("/") + try: + result = tools.create_project(args, api_key=api_key, api_base=api_base) + except Exception as exc: # a tool handler must never raise (dev guide, "Common mistakes") + logger.exception("scribase_create_project failed") + result = {"error": f"unexpected error: {exc}"} + return json.dumps(result) + + ctx.register_tool( + name="scribase_create_project", + toolset="scribase", + schema=schemas.SCRIBASE_CREATE_PROJECT, + handler=_handle_create_project, + ) diff --git a/plugin.yaml b/plugin.yaml new file mode 100644 index 0000000..825b0a2 --- /dev/null +++ b/plugin.yaml @@ -0,0 +1,16 @@ +name: scribase +version: "1.0.0" +description: "Provision a hosted Postgres backend project on Scribase (api.scribase.com) and get back its connection string and API keys." +author: Scribase +requires_hermes: ">=0.20.0" +provides_tools: + - scribase_create_project +requires_env: + - name: SCRIBASE_API_KEY + description: "Scribase organization API key. Create one under Organization -> API tokens in the Scribase console, or via POST /v1/organizations/{org}/api-keys." + url: "https://docs.scribase.com/docs/api" + secret: true +config_schema: + api_base_url: + type: str + required: false diff --git a/schemas.py b/schemas.py new file mode 100644 index 0000000..50ca080 --- /dev/null +++ b/schemas.py @@ -0,0 +1,50 @@ +"""Tool schema for `scribase_create_project` — this is what the LLM reads to +decide when and how to call the tool.""" + +SCRIBASE_CREATE_PROJECT = { + "name": "scribase_create_project", + "description": ( + "Provision a new hosted Postgres backend project on Scribase " + "(api.scribase.com) and return its connection string and API keys. " + "Creates the project, creates its first environment (production by " + "default), waits for it to finish provisioning, then reads back the " + "Postgres connection URI and the environment's anon/service-role API " + "keys. Use this when a user wants a real Postgres database plus a " + "REST/Auth/Storage/Realtime API for an app and doesn't want to set " + "up a database by hand. Requires an existing Scribase organization " + "id and an organization API key configured as SCRIBASE_API_KEY." + ), + "parameters": { + "type": "object", + "properties": { + "organization_id": { + "type": "string", + "description": ( + "The Scribase organization this project belongs to " + "(lowercase alphanumeric + hyphens, 2-64 chars). The " + "organization must already exist." + ), + }, + "project_id": { + "type": "string", + "description": ( + "A new, unique project id within the organization " + "(lowercase alphanumeric + hyphens, 2-64 chars)." + ), + }, + "environment_id": { + "type": "string", + "description": "Name for the project's first environment. Defaults to 'production'.", + }, + "region": { + "type": "string", + "description": "Region to provision in. Defaults to 'eu-frankfurt' (hosted Scribase's region).", + }, + "postgres_major": { + "type": "integer", + "description": "Postgres major version. Only 17 is currently supported; defaults to 17.", + }, + }, + "required": ["organization_id", "project_id"], + }, +} diff --git a/tools.py b/tools.py new file mode 100644 index 0000000..c7a3eef --- /dev/null +++ b/tools.py @@ -0,0 +1,183 @@ +"""HTTP client for Scribase's public /v1 management API. + +Every function here takes an already-resolved `api_key`/`api_base` and +returns a plain dict — never raises. The caller (`__init__.py`'s tool +handler) is responsible for the handler contract (always return a JSON +string, success or error alike). This module makes network calls only to +`api_base` (default `https://api.scribase.com`, overridable via the +plugin's optional `api_base_url` config key for self-hosted Scribase +clusters) and uses only the Python standard library — no third-party +dependencies. +""" + +from __future__ import annotations + +import json +import time +import urllib.error +import urllib.request +import uuid +from typing import Any, Dict, Optional, Tuple + +_TIMEOUT = 20 # seconds per HTTP call +_POLL_ATTEMPTS = 8 +_POLL_INTERVAL = 3 # seconds +_DEFAULT_REGION = "eu-frankfurt" +_DEFAULT_POSTGRES_MAJOR = 17 +_DEFAULT_ENVIRONMENT_ID = "production" +_TERMINAL_STATES = ("succeeded", "failed", "cancelled") + + +def _request( + method: str, url: str, api_key: str, + body: Optional[Dict[str, Any]] = None, + extra_headers: Optional[Dict[str, str]] = None, +) -> Tuple[int, Any]: + """One HTTP call against the Scribase management API. + + Returns ``(status, parsed_body)``. ``status`` is 0 when the request + could not be sent at all (DNS/connection failure); callers treat that + as a terminal error, never a retryable one, to avoid hanging an + unattended run (plugin-catalog rule 12). + """ + data = json.dumps(body).encode("utf-8") if body is not None else None + headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"} + if data is not None: + headers["Content-Type"] = "application/json" + if extra_headers: + headers.update(extra_headers) + req = urllib.request.Request(url, data=data, method=method, headers=headers) + try: + with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp: + raw = resp.read().decode("utf-8", "replace") + status = resp.status + except urllib.error.HTTPError as exc: + raw = exc.read().decode("utf-8", "replace") + status = exc.code + except urllib.error.URLError as exc: + return 0, {"error": f"could not reach the Scribase API: {exc.reason}"} + if not raw: + return status, {} + try: + return status, json.loads(raw) + except json.JSONDecodeError: + return status, {"error": raw[:500]} + + +def _idempotency_key() -> str: + return str(uuid.uuid4()) + + +def create_project(args: Dict[str, Any], *, api_key: str, api_base: str) -> Dict[str, Any]: + """Create a Scribase project and its first environment, then return connection info. + + Required args: ``organization_id``, ``project_id``. Optional: + ``environment_id`` (default "production"), ``region`` (default + "eu-frankfurt", hosted Scribase's region), ``postgres_major`` (default + 17, the only currently supported version). + """ + org = str(args.get("organization_id") or "").strip() + project = str(args.get("project_id") or "").strip() + environment = str(args.get("environment_id") or "").strip() or _DEFAULT_ENVIRONMENT_ID + region = str(args.get("region") or "").strip() or _DEFAULT_REGION + try: + postgres_major = int(args.get("postgres_major") or _DEFAULT_POSTGRES_MAJOR) + except (TypeError, ValueError): + return {"error": "postgres_major must be an integer (only 17 is currently supported)."} + + if not org: + return {"error": "organization_id is required (the existing Scribase org this project belongs to)."} + if not project: + return {"error": "project_id is required."} + + # 1. Create (or confirm) the project — idempotent PUT. + status, body = _request( + "PUT", f"{api_base}/v1/organizations/{org}/projects/{project}", api_key, + body={"region": region, "postgres_major": postgres_major}, + extra_headers={"Idempotency-Key": _idempotency_key()}, + ) + if status == 0: + return body + if status not in (200, 201): + return {"error": "failed to create project", "status": status, "detail": body} + + # 2. Create its first environment — async; returns an operation to poll. + status, body = _request( + "POST", f"{api_base}/v1/environments", api_key, + body={ + "organization_id": org, "project_id": project, "environment_id": environment, + "kind": "production", "data_mode": "schema_only", + "region": region, "postgres_major": postgres_major, "ttl_hours": None, + }, + extra_headers={"Idempotency-Key": _idempotency_key()}, + ) + if status == 0: + return body + if status != 202: + return {"error": "failed to create environment", "status": status, "detail": body} + operation_id = body.get("id") + + # 3. Poll the operation until it leaves pending/running/waiting_retry, bounded so an + # unattended run (cron, gateway) can never hang on this tool call (rule 12). + final_state = None + last_op_body: Dict[str, Any] = {} + for _ in range(_POLL_ATTEMPTS): + time.sleep(_POLL_INTERVAL) + op_status, op_body = _request( + "GET", f"{api_base}/v1/operations/{operation_id}", api_key, + extra_headers={"X-Scribase-Organization-ID": org}, + ) + if op_status == 200: + last_op_body = op_body + final_state = op_body.get("state") + if final_state in _TERMINAL_STATES: + break + + if final_state != "succeeded": + still_going = final_state not in ("failed", "cancelled") + return { + "status": "provisioning" if still_going else "failed", + "organization_id": org, "project_id": project, "environment_id": environment, + "operation_id": operation_id, + "message": ( + f"Environment is still provisioning (state={final_state!r}). Call this tool " + f"again shortly, or poll GET /v1/operations/{operation_id} directly." + if still_going else + f"Environment provisioning failed (state={final_state!r})." + ), + "operation": last_op_body, + } + + # 4. Fetch the new environment's API keys and connection string. + status, keys = _request( + "GET", + f"{api_base}/v1/organizations/{org}/projects/{project}/environments/{environment}/api-keys", + api_key, + ) + if status != 200: + return { + "status": "ready", + "warning": "environment created, but failed to read its API keys", + "detail": keys, + } + + status, conn = _request( + "GET", + f"{api_base}/v1/organizations/{org}/projects/{project}/environments/{environment}/connection", + api_key, + ) + connection_uri = conn.get("connection_uri") if status == 200 else None + + return { + "status": "ready", + "organization_id": org, + "project_id": project, + "environment_id": environment, + "region": region, + "api_url": keys.get("api_url"), + "anon_key": keys.get("anon_key"), + "publishable_key": keys.get("publishable_key"), + "service_role_key": keys.get("service_role_key"), + "secret_key": keys.get("secret_key"), + "connection_uri": connection_uri, + }