Fourth tool: one action='create'|'promote'|'discard' tool that forks a real
copy-on-write Postgres branch for one agent task (POST /v1/environments,
kind="preview", bounded TTL so it always lands in the control plane's
agent-branch slot pool), three-way merges it back into its parent on
action='promote' (POST .../branches/merge, reads the real
applied/clean/changes/conflicts/statements fields the compiled server
renders, and surfaces a real mfa_required rejection on a forced merge
instead of hiding it), or deletes it outright on action='discard' (DELETE
.../environments/{env}). Built from the real control-api source
(http/environments.rs, http/branches.rs, adapters/branch.rs,
adapters/usage.rs::AGENT_BRANCH_MAX_TTL_HOURS) and the public
docs.scribase.com environments/branches pages, not guessed.
Factored create_project's polling and API-keys/connection readback into
shared _poll_operation/_read_environment_access helpers, reused by both
tools; create_project's own behavior is unchanged (verified with a mocked
HTTP layer, happy path and warning path).
plugin.yaml bumped to 1.2.0, provides_tools now lists all 4 tools.
README rewritten with a one-line pitch, a demo-video pointer, and a real
example call + example response for every tool. HACKATHON-SUBMISSION
updated with the new tool, a fresh validator run (15/15, 0 warnings), and
an honest demo-coverage note for the branch-task tool including two live
production responses from the real public /v1/demo/branch endpoint this
tool's workflow mirrors (a transient 402, then the real 429 per-hour rate
limit — both genuine, neither invented).
120 lines
4.3 KiB
Python
120 lines
4.3 KiB
Python
"""Scribase plugin for Hermes Agent — registration.
|
|
|
|
Registers four tools against Scribase's public REST API
|
|
(https://api.scribase.com):
|
|
|
|
- `scribase_create_project` — provisions a new hosted Postgres backend
|
|
project and returns its connection string and API keys.
|
|
- `scribase_lint_migration` — submits a migration's SQL to Scribase's real
|
|
migration-safety linter (missing-RLS, unsafe grants/policies, etc.) and
|
|
returns Block/Warn findings. `apply` is always sent as `false`; this tool
|
|
can never run the migration, only check it.
|
|
- `scribase_query` — runs a single read-only SQL statement against a
|
|
project's database and returns the rows. The control plane enforces
|
|
read-only itself (a static check, then a Postgres `READ ONLY`
|
|
transaction), so this can never write or alter data.
|
|
- `scribase_branch_task` — gives an agent a real, throwaway, copy-on-write
|
|
Postgres branch for one task: `create` forks one from an existing
|
|
environment with a bounded TTL, `promote` three-way merges its schema
|
|
back into the parent (the control plane itself refuses a conflicting
|
|
merge unless `force`, which it also refuses for an MFA-protected
|
|
organization), `discard` deletes it outright. The parent is never touched
|
|
except through that one explicit, server-validated merge.
|
|
|
|
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 typing import Any, Callable, Dict
|
|
|
|
from agent.secret_scope import get_secret
|
|
|
|
from . import schemas, tools
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_DEFAULT_API_BASE = "https://api.scribase.com"
|
|
|
|
_MISSING_KEY_ERROR = {
|
|
"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."
|
|
),
|
|
}
|
|
|
|
|
|
def _api_base(ctx) -> str:
|
|
return str(
|
|
ctx.get_config("api_base_url", _DEFAULT_API_BASE) or _DEFAULT_API_BASE
|
|
).strip().rstrip("/")
|
|
|
|
|
|
def _make_handler(
|
|
ctx,
|
|
tool_name: str,
|
|
call: Callable[..., Dict[str, Any]],
|
|
) -> Callable[..., str]:
|
|
"""Builds a tool handler that resolves the API key/base once per call,
|
|
delegates to `call`, and always returns a JSON string — a handler must
|
|
never raise (dev guide, "Common mistakes")."""
|
|
|
|
def _handle(args: dict, **kwargs) -> str:
|
|
api_key = get_secret("SCRIBASE_API_KEY") or ""
|
|
if not api_key:
|
|
return json.dumps(_MISSING_KEY_ERROR)
|
|
try:
|
|
result = call(args, api_key=api_key, api_base=_api_base(ctx))
|
|
except Exception as exc: # noqa: BLE001 - handler contract: never raise
|
|
logger.exception("%s failed", tool_name)
|
|
result = {"error": f"unexpected error: {exc}"}
|
|
return json.dumps(result)
|
|
|
|
return _handle
|
|
|
|
|
|
def register(ctx) -> None:
|
|
"""Wires all four Scribase tools to the Scribase REST client."""
|
|
|
|
ctx.register_tool(
|
|
name="scribase_create_project",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_CREATE_PROJECT,
|
|
handler=_make_handler(ctx, "scribase_create_project", tools.create_project),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_lint_migration",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_LINT_MIGRATION,
|
|
handler=_make_handler(ctx, "scribase_lint_migration", tools.lint_migration),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_query",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_QUERY,
|
|
handler=_make_handler(ctx, "scribase_query", tools.run_query),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_branch_task",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_BRANCH_TASK,
|
|
handler=_make_handler(ctx, "scribase_branch_task", tools.branch_task),
|
|
)
|