Add ez-assistant and kerberos service folders
This commit is contained in:
kelin
96
docker-compose/ez-assistant/docs/plugins/agent-tools.md
Normal file
96
docker-compose/ez-assistant/docs/plugins/agent-tools.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
summary: "Write agent tools in a plugin (schemas, optional tools, allowlists)"
|
||||
read_when:
|
||||
- You want to add a new agent tool in a plugin
|
||||
- You need to make a tool opt-in via allowlists
|
||||
---
|
||||
# Plugin agent tools
|
||||
|
||||
Moltbot plugins can register **agent tools** (JSON‑schema functions) that are exposed
|
||||
to the LLM during agent runs. Tools can be **required** (always available) or
|
||||
**optional** (opt‑in).
|
||||
|
||||
Agent tools are configured under `tools` in the main config, or per‑agent under
|
||||
`agents.list[].tools`. The allowlist/denylist policy controls which tools the agent
|
||||
can call.
|
||||
|
||||
## Basic tool
|
||||
|
||||
```ts
|
||||
import { Type } from "@sinclair/typebox";
|
||||
|
||||
export default function (api) {
|
||||
api.registerTool({
|
||||
name: "my_tool",
|
||||
description: "Do a thing",
|
||||
parameters: Type.Object({
|
||||
input: Type.String(),
|
||||
}),
|
||||
async execute(_id, params) {
|
||||
return { content: [{ type: "text", text: params.input }] };
|
||||
},
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Optional tool (opt‑in)
|
||||
|
||||
Optional tools are **never** auto‑enabled. Users must add them to an agent
|
||||
allowlist.
|
||||
|
||||
```ts
|
||||
export default function (api) {
|
||||
api.registerTool(
|
||||
{
|
||||
name: "workflow_tool",
|
||||
description: "Run a local workflow",
|
||||
parameters: {
|
||||
type: "object",
|
||||
properties: {
|
||||
pipeline: { type: "string" },
|
||||
},
|
||||
required: ["pipeline"],
|
||||
},
|
||||
async execute(_id, params) {
|
||||
return { content: [{ type: "text", text: params.pipeline }] };
|
||||
},
|
||||
},
|
||||
{ optional: true },
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`):
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "main",
|
||||
tools: {
|
||||
allow: [
|
||||
"workflow_tool", // specific tool name
|
||||
"workflow", // plugin id (enables all tools from that plugin)
|
||||
"group:plugins" // all plugin tools
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Other config knobs that affect tool availability:
|
||||
- Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain
|
||||
enabled unless you also include core tools or groups in the allowlist.
|
||||
- `tools.profile` / `agents.list[].tools.profile` (base allowlist)
|
||||
- `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny)
|
||||
- `tools.sandbox.tools.*` (sandbox tool policy when sandboxed)
|
||||
|
||||
## Rules + tips
|
||||
|
||||
- Tool names must **not** clash with core tool names; conflicting tools are skipped.
|
||||
- Plugin ids used in allowlists must not clash with core tool names.
|
||||
- Prefer `optional: true` for tools that trigger side effects or require extra
|
||||
binaries/credentials.
|
||||
67
docker-compose/ez-assistant/docs/plugins/manifest.md
Normal file
67
docker-compose/ez-assistant/docs/plugins/manifest.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
summary: "Plugin manifest + JSON schema requirements (strict config validation)"
|
||||
read_when:
|
||||
- You are building a Moltbot plugin
|
||||
- You need to ship a plugin config schema or debug plugin validation errors
|
||||
---
|
||||
# Plugin manifest (moltbot.plugin.json)
|
||||
|
||||
Every plugin **must** ship a `moltbot.plugin.json` file in the **plugin root**.
|
||||
Moltbot uses this manifest to validate configuration **without executing plugin
|
||||
code**. Missing or invalid manifests are treated as plugin errors and block
|
||||
config validation.
|
||||
|
||||
See the full plugin system guide: [Plugins](/plugin).
|
||||
|
||||
## Required fields
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "voice-call",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Required keys:
|
||||
- `id` (string): canonical plugin id.
|
||||
- `configSchema` (object): JSON Schema for plugin config (inline).
|
||||
|
||||
Optional keys:
|
||||
- `kind` (string): plugin kind (example: `"memory"`).
|
||||
- `channels` (array): channel ids registered by this plugin (example: `["matrix"]`).
|
||||
- `providers` (array): provider ids registered by this plugin.
|
||||
- `skills` (array): skill directories to load (relative to the plugin root).
|
||||
- `name` (string): display name for the plugin.
|
||||
- `description` (string): short plugin summary.
|
||||
- `uiHints` (object): config field labels/placeholders/sensitive flags for UI rendering.
|
||||
- `version` (string): plugin version (informational).
|
||||
|
||||
## JSON Schema requirements
|
||||
|
||||
- **Every plugin must ship a JSON Schema**, even if it accepts no config.
|
||||
- An empty schema is acceptable (for example, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Schemas are validated at config read/write time, not at runtime.
|
||||
|
||||
## Validation behavior
|
||||
|
||||
- Unknown `channels.*` keys are **errors**, unless the channel id is declared by
|
||||
a plugin manifest.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny`, and `plugins.slots.*`
|
||||
must reference **discoverable** plugin ids. Unknown ids are **errors**.
|
||||
- If a plugin is installed but has a broken or missing manifest or schema,
|
||||
validation fails and Doctor reports the plugin error.
|
||||
- If plugin config exists but the plugin is **disabled**, the config is kept and
|
||||
a **warning** is surfaced in Doctor + logs.
|
||||
|
||||
## Notes
|
||||
|
||||
- The manifest is **required for all plugins**, including local filesystem loads.
|
||||
- Runtime still loads the plugin module separately; the manifest is only for
|
||||
discovery + validation.
|
||||
- If your plugin depends on native modules, document the build steps and any
|
||||
package-manager allowlist requirements (for example, pnpm `allow-build-scripts`
|
||||
+ `pnpm rebuild <package>`).
|
||||
239
docker-compose/ez-assistant/docs/plugins/voice-call.md
Normal file
239
docker-compose/ez-assistant/docs/plugins/voice-call.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
summary: "Voice Call plugin: outbound + inbound calls via Twilio/Telnyx/Plivo (plugin install + config + CLI)"
|
||||
read_when:
|
||||
- You want to place an outbound voice call from Moltbot
|
||||
- You are configuring or developing the voice-call plugin
|
||||
---
|
||||
|
||||
# Voice Call (plugin)
|
||||
|
||||
Voice calls for Moltbot via a plugin. Supports outbound notifications and
|
||||
multi-turn conversations with inbound policies.
|
||||
|
||||
Current providers:
|
||||
- `twilio` (Programmable Voice + Media Streams)
|
||||
- `telnyx` (Call Control v2)
|
||||
- `plivo` (Voice API + XML transfer + GetInput speech)
|
||||
- `mock` (dev/no network)
|
||||
|
||||
Quick mental model:
|
||||
- Install plugin
|
||||
- Restart Gateway
|
||||
- Configure under `plugins.entries.voice-call.config`
|
||||
- Use `moltbot voicecall ...` or the `voice_call` tool
|
||||
|
||||
## Where it runs (local vs remote)
|
||||
|
||||
The Voice Call plugin runs **inside the Gateway process**.
|
||||
|
||||
If you use a remote Gateway, install/configure the plugin on the **machine running the Gateway**, then restart the Gateway to load it.
|
||||
|
||||
## Install
|
||||
|
||||
### Option A: install from npm (recommended)
|
||||
|
||||
```bash
|
||||
moltbot plugins install @moltbot/voice-call
|
||||
```
|
||||
|
||||
Restart the Gateway afterwards.
|
||||
|
||||
### Option B: install from a local folder (dev, no copying)
|
||||
|
||||
```bash
|
||||
moltbot plugins install ./extensions/voice-call
|
||||
cd ./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", // or "telnyx" | "plivo" | "mock"
|
||||
fromNumber: "+15550001234",
|
||||
toNumber: "+15550005678",
|
||||
|
||||
twilio: {
|
||||
accountSid: "ACxxxxxxxx",
|
||||
authToken: "..."
|
||||
},
|
||||
|
||||
plivo: {
|
||||
authId: "MAxxxxxxxxxxxxxxxxxxxx",
|
||||
authToken: "..."
|
||||
},
|
||||
|
||||
// Webhook server
|
||||
serve: {
|
||||
port: 3334,
|
||||
path: "/voice/webhook"
|
||||
},
|
||||
|
||||
// Public exposure (pick one)
|
||||
// publicUrl: "https://example.ngrok.app/voice/webhook",
|
||||
// tunnel: { provider: "ngrok" },
|
||||
// tailscale: { mode: "funnel", path: "/voice/webhook" }
|
||||
|
||||
outbound: {
|
||||
defaultMode: "notify" // notify | conversation
|
||||
},
|
||||
|
||||
streaming: {
|
||||
enabled: true,
|
||||
streamPath: "/voice/stream"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Twilio/Telnyx require a **publicly reachable** webhook URL.
|
||||
- Plivo requires a **publicly reachable** webhook URL.
|
||||
- `mock` is a local dev provider (no network calls).
|
||||
- `skipSignatureVerification` is for local testing only.
|
||||
- If you use ngrok free tier, set `publicUrl` to the exact ngrok URL; signature verification is always enforced.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Use for local dev only.
|
||||
- Ngrok free tier URLs can change or add interstitial behavior; if `publicUrl` drifts, Twilio signatures will fail. For production, prefer a stable domain or Tailscale funnel.
|
||||
|
||||
## TTS for calls
|
||||
|
||||
Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
|
||||
streaming speech on calls. You can override it under the plugin config with the
|
||||
**same shape** — it deep‑merges with `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
tts: {
|
||||
provider: "elevenlabs",
|
||||
elevenlabs: {
|
||||
voiceId: "pMsXgVXv3BLzUgSXRplE",
|
||||
modelId: "eleven_multilingual_v2"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- **Edge TTS is ignored for voice calls** (telephony audio needs PCM; Edge output is unreliable).
|
||||
- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
|
||||
|
||||
### More examples
|
||||
|
||||
Use core TTS only (no override):
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
provider: "openai",
|
||||
openai: { voice: "alloy" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Override to ElevenLabs just for calls (keep core default elsewhere):
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"voice-call": {
|
||||
config: {
|
||||
tts: {
|
||||
provider: "elevenlabs",
|
||||
elevenlabs: {
|
||||
apiKey: "elevenlabs_key",
|
||||
voiceId: "pMsXgVXv3BLzUgSXRplE",
|
||||
modelId: "eleven_multilingual_v2"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Override only the OpenAI model for calls (deep‑merge example):
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"voice-call": {
|
||||
config: {
|
||||
tts: {
|
||||
openai: {
|
||||
model: "gpt-4o-mini-tts",
|
||||
voice: "marin"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Inbound calls
|
||||
|
||||
Inbound policy defaults to `disabled`. To enable inbound calls, set:
|
||||
|
||||
```json5
|
||||
{
|
||||
inboundPolicy: "allowlist",
|
||||
allowFrom: ["+15550001234"],
|
||||
inboundGreeting: "Hello! How can I help?"
|
||||
}
|
||||
```
|
||||
|
||||
Auto-responses use the agent system. Tune with:
|
||||
- `responseModel`
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
moltbot voicecall call --to "+15555550123" --message "Hello from Moltbot"
|
||||
moltbot voicecall continue --call-id <id> --message "Any questions?"
|
||||
moltbot voicecall speak --call-id <id> --message "One moment"
|
||||
moltbot voicecall end --call-id <id>
|
||||
moltbot voicecall status --call-id <id>
|
||||
moltbot voicecall tail
|
||||
moltbot voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
## Agent tool
|
||||
|
||||
Tool name: `voice_call`
|
||||
|
||||
Actions:
|
||||
- `initiate_call` (message, to?, mode?)
|
||||
- `continue_call` (callId, message)
|
||||
- `speak_to_user` (callId, message)
|
||||
- `end_call` (callId)
|
||||
- `get_status` (callId)
|
||||
|
||||
This repo ships a matching skill doc at `skills/voice-call/SKILL.md`.
|
||||
|
||||
## Gateway RPC
|
||||
|
||||
- `voicecall.initiate` (`to?`, `message`, `mode?`)
|
||||
- `voicecall.continue` (`callId`, `message`)
|
||||
- `voicecall.speak` (`callId`, `message`)
|
||||
- `voicecall.end` (`callId`)
|
||||
- `voicecall.status` (`callId`)
|
||||
75
docker-compose/ez-assistant/docs/plugins/zalouser.md
Normal file
75
docker-compose/ez-assistant/docs/plugins/zalouser.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
summary: "Zalo Personal plugin: QR login + messaging via zca-cli (plugin install + channel config + CLI + tool)"
|
||||
read_when:
|
||||
- You want Zalo Personal (unofficial) support in Moltbot
|
||||
- You are configuring or developing the zalouser plugin
|
||||
---
|
||||
|
||||
# Zalo Personal (plugin)
|
||||
|
||||
Zalo Personal support for Moltbot via a plugin, using `zca-cli` to automate a normal Zalo user account.
|
||||
|
||||
> **Warning:** Unofficial automation may lead to account suspension/ban. Use at your own risk.
|
||||
|
||||
## Naming
|
||||
Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
|
||||
|
||||
## Where it runs
|
||||
This plugin runs **inside the Gateway process**.
|
||||
|
||||
If you use a remote Gateway, install/configure it on the **machine running the Gateway**, then restart the Gateway.
|
||||
|
||||
## Install
|
||||
|
||||
### Option A: install from npm
|
||||
|
||||
```bash
|
||||
moltbot plugins install @moltbot/zalouser
|
||||
```
|
||||
|
||||
Restart the Gateway afterwards.
|
||||
|
||||
### Option B: install from a local folder (dev)
|
||||
|
||||
```bash
|
||||
moltbot plugins install ./extensions/zalouser
|
||||
cd ./extensions/zalouser && pnpm install
|
||||
```
|
||||
|
||||
Restart the Gateway afterwards.
|
||||
|
||||
## Prerequisite: zca-cli
|
||||
The Gateway machine must have `zca` on `PATH`:
|
||||
|
||||
```bash
|
||||
zca --version
|
||||
```
|
||||
|
||||
## Config
|
||||
Channel config lives under `channels.zalouser` (not `plugins.entries.*`):
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
zalouser: {
|
||||
enabled: true,
|
||||
dmPolicy: "pairing"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
moltbot channels login --channel zalouser
|
||||
moltbot channels logout --channel zalouser
|
||||
moltbot channels status --probe
|
||||
moltbot message send --channel zalouser --target <threadId> --message "Hello from Moltbot"
|
||||
moltbot directory peers list --channel zalouser --query "name"
|
||||
```
|
||||
|
||||
## Agent tool
|
||||
Tool name: `zalouser`
|
||||
|
||||
Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
|
||||
Reference in New Issue
Block a user