From 720c5b53fd0cc3a7bab435a0a5088f6a26f82c3e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 12 Jan 2026 01:16:46 +0000 Subject: [PATCH] docs: document plugin system --- docs/cli/index.md | 2 +- docs/plugin.md | 56 +++++++++++++++++++++- docs/plugins/voice-call.md | 96 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 docs/plugins/voice-call.md diff --git a/docs/cli/index.md b/docs/cli/index.md index c89c375bc..afcae3ae8 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -182,7 +182,7 @@ Manage extensions and their config: - `clawdbot plugins list` — discover plugins (use `--json` for machine output). - `clawdbot plugins info ` — show details for a plugin. -- `clawdbot plugins install ` — add a plugin path to `plugins.load.paths`. +- `clawdbot plugins install ` — install a plugin (or add a plugin path to `plugins.load.paths`). - `clawdbot plugins enable ` / `disable ` — toggle `plugins.entries..enabled`. - `clawdbot plugins doctor` — report plugin load errors. diff --git a/docs/plugin.md b/docs/plugin.md index 8fdb39a90..17c91a1b7 100644 --- a/docs/plugin.md +++ b/docs/plugin.md @@ -86,12 +86,43 @@ Fields: Config changes **require a gateway restart**. +## Control UI (schema + labels) + +The Control UI uses `config.schema` (JSON Schema + `uiHints`) to render better forms. + +Clawdbot augments `uiHints` at runtime based on discovered plugins: + +- Adds per-plugin labels for `plugins.entries.` / `.enabled` / `.config` +- Merges optional plugin-provided config field hints under: + `plugins.entries..config.` + +If you want your plugin config fields to show good labels/placeholders (and mark secrets as sensitive), +provide `configSchema.uiHints`. + +Example: + +```ts +export default { + id: "my-plugin", + configSchema: { + parse: (v) => v, + uiHints: { + "apiKey": { label: "API Key", sensitive: true }, + "region": { label: "Region", placeholder: "us-east-1" }, + }, + }, + register(api) {}, +}; +``` + ## CLI ```bash clawdbot plugins list clawdbot plugins info -clawdbot plugins install +clawdbot plugins install # add a local file/dir to plugins.load.paths +clawdbot plugins install ./plugin.tgz # install from a local tarball +clawdbot plugins install @clawdbot/voice-call # install from npm clawdbot plugins enable clawdbot plugins disable clawdbot plugins doctor @@ -171,6 +202,20 @@ Plugins can ship a skill in the repo (`skills//SKILL.md`). Enable it with `plugins.entries..enabled` (or other config gates) and ensure it’s present in your workspace/managed skills locations. +## Distribution (npm) + +Recommended packaging: + +- Main package: `clawdbot` (this repo) +- Plugins: separate npm packages under `@clawdbot/*` (example: `@clawdbot/voice-call`) + +Publishing contract: + +- Plugin `package.json` must include `clawdbot.extensions` with one or more entry files. +- Entry files can be `.js` or `.ts` (jiti loads TS at runtime). +- `clawdbot plugins install ` uses `npm pack`, extracts into `~/.clawdbot/extensions//`, and enables it in config. +- Config key stability: scoped packages are normalized to the **unscoped** id for `plugins.entries.*`. + ## Example plugin: Voice Call This repo includes a voice‑call plugin (Twilio or log fallback): @@ -183,7 +228,7 @@ This repo includes a voice‑call plugin (Twilio or log fallback): - Config (twilio): `provider: "twilio"` + `twilio.accountSid/authToken/from` (optional `statusCallbackUrl`, `twimlUrl`) - Config (dev): `provider: "log"` (no network) -See `extensions/voice-call/README.md` for setup and usage. +See [Voice Call](/plugins/voice-call) and `extensions/voice-call/README.md` for setup and usage. ## Safety notes @@ -192,3 +237,10 @@ Plugins run in-process with the Gateway. Treat them as trusted code: - Only install plugins you trust. - Prefer `plugins.allow` allowlists. - Restart the Gateway after changes. + +## Testing plugins + +Plugins can (and should) ship tests: + +- In-repo plugins can keep Vitest tests under `src/**` (example: `src/plugins/voice-call.plugin.test.ts`). +- Separately published plugins should run their own CI (lint/build/test) and validate `clawdbot.extensions` points at the built entrypoint (`dist/index.js`). diff --git a/docs/plugins/voice-call.md b/docs/plugins/voice-call.md new file mode 100644 index 000000000..c0c7cbb88 --- /dev/null +++ b/docs/plugins/voice-call.md @@ -0,0 +1,96 @@ +--- +summary: "Voice Call plugin: Twilio-backed outbound calls (plugin install + config + CLI)" +read_when: + - You want to place an outbound voice call from Clawdbot + - You are configuring or developing the voice-call plugin +--- + +# Voice Call (plugin) + +Outbound voice calls for Clawdbot via a plugin. + +Current providers: +- `twilio` (real calls) +- `log` (dev fallback; no network) + +If you haven’t read the general plugin docs yet, start with [Plugins](/plugin). + +## Install + +### Option A: install from npm (recommended) + +```bash +clawdbot plugins install @clawdbot/voice-call +``` + +This downloads the package, extracts it into `~/.clawdbot/extensions/`, and enables it in `clawdbot.json`. + +Restart the Gateway afterwards. + +### Option B: install from a local folder (dev) + +```bash +mkdir -p ~/.clawdbot/extensions +cp -R extensions/voice-call ~/.clawdbot/extensions/voice-call +cd ~/.clawdbot/extensions/voice-call && pnpm install +``` + +Restart the Gateway afterwards. + +## Config + +Set config under `plugins.entries.voice-call.config`: + +```json5 +{ + plugins: { + entries: { + "voice-call": { + enabled: true, + config: { + provider: "twilio", + twilio: { + accountSid: "ACxxxxxxxx", + authToken: "…", + from: "+15551234567", + statusCallbackUrl: "https://example.com/twilio-status", // optional + twimlUrl: "https://example.com/twiml" // optional + } + } + } + } + } +} +``` + +Dev fallback: + +```json5 +{ provider: "log" } +``` + +Notes: +- `twilio.authToken` is treated as sensitive in the Control UI schema hints. + +## CLI + +```bash +clawdbot voicecall start --to "+15555550123" --message "Hello from Clawdbot" +clawdbot voicecall status --sid CAxxxxxxxx +``` + +## Agent tool + +Tool name: `voice_call` + +- `mode`: `"call" | "status"` (default: `call`) +- `to`: required for `call` +- `sid`: required for `status` +- `message`: optional + +This repo ships a matching skill doc at `skills/voice-call/SKILL.md`. + +## Gateway RPC + +- `voicecall.start` (`to`, optional `message`) +- `voicecall.status` (`sid`)