milaidy 1.0.0

package/docs/plugins/agent-tools.md

@@ -0,0 +1,99 @@
+---
+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
+title: "Plugin Agent Tools"
+---
+
+# Plugin agent tools
+
+Milaidy 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.

package/docs/plugins/manifest.md

@@ -0,0 +1,71 @@
+---
+summary: "Plugin manifest + JSON schema requirements (strict config validation)"
+read_when:
+  - You are building a Milaidy plugin
+  - You need to ship a plugin config schema or debug plugin validation errors
+title: "Plugin Manifest"
+---
+
+# Plugin manifest (milaidy.plugin.json)
+
+Every plugin **must** ship a `milaidy.plugin.json` file in the **plugin root**.
+Milaidy 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>`).

package/docs/plugins/voice-call.md

@@ -0,0 +1,273 @@
+---
+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 Milaidy
+  - You are configuring or developing the voice-call plugin
+title: "Voice Call Plugin"
+---
+
+# Voice Call (plugin)
+
+Voice calls for Milaidy 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 `milaidy 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
+
+```bash
+milaidy plugins install @elizaos/plugin-voice-call
+```
+
+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",
+          },
+
+          // Webhook security (recommended for tunnels/proxies)
+          webhookSecurity: {
+            allowedHosts: ["voice.example.com"],
+            trustedProxyIPs: ["100.64.0.1"],
+          },
+
+          // 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.
+
+## Webhook Security
+
+When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the
+public URL for signature verification. These options control which forwarded
+headers are trusted.
+
+`webhookSecurity.allowedHosts` allowlists hosts from forwarding headers.
+
+`webhookSecurity.trustForwardingHeaders` trusts forwarded headers without an allowlist.
+
+`webhookSecurity.trustedProxyIPs` only trusts forwarded headers when the request
+remote IP matches the list.
+
+Example with a stable public host:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          publicUrl: "https://voice.example.com/voice/webhook",
+          webhookSecurity: {
+            allowedHosts: ["voice.example.com"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## 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-5-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
+milaidy voicecall call --to "+15555550123" --message "Hello from Milaidy"
+milaidy voicecall continue --call-id <id> --message "Any questions?"
+milaidy voicecall speak --call-id <id> --message "One moment"
+milaidy voicecall end --call-id <id>
+milaidy voicecall status --call-id <id>
+milaidy voicecall tail
+milaidy 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`)

package/docs/plugins/zalouser.md

@@ -0,0 +1,70 @@
+---
+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 Milaidy
+  - You are configuring or developing the zalouser plugin
+title: "Zalo Personal Plugin"
+---
+
+# Zalo Personal (plugin)
+
+Zalo Personal support for Milaidy 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
+
+```bash
+milaidy plugins install @elizaos/plugin-zalouser
+```
+
+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
+milaidy channels login --channel zalouser
+milaidy channels logout --channel zalouser
+milaidy channels status --probe
+milaidy message send --channel zalouser --target <threadId> --message "Hello from Milaidy"
+milaidy directory peers list --channel zalouser --query "name"
+```
+
+## Agent tool
+
+Tool name: `zalouser`
+
+Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`

package/docs/providers/anthropic.md

@@ -0,0 +1,152 @@
+---
+summary: "Use Anthropic Claude via API keys or setup-token in Milaidy"
+read_when:
+  - You want to use Anthropic models in Milaidy
+  - You want setup-token instead of API keys
+title: "Anthropic"
+---
+
+# Anthropic (Claude)
+
+Anthropic builds the **Claude** model family and provides access via an API.
+In Milaidy you can authenticate with an API key or a **setup-token**.
+
+## Option A: Anthropic API key
+
+**Best for:** standard API access and usage-based billing.
+Create your API key in the Anthropic Console.
+
+### CLI setup
+
+```bash
+milaidy onboard
+# choose: Anthropic API key
+
+# or non-interactive
+milaidy onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+### Config snippet
+
+```json5
+{
+  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+}
+```
+
+## Prompt caching (Anthropic API)
+
+Milaidy supports Anthropic's prompt caching feature. This is **API-only**; subscription auth does not honor cache settings.
+
+### Configuration
+
+Use the `cacheRetention` parameter in your model config:
+
+| Value   | Cache Duration | Description                         |
+| ------- | -------------- | ----------------------------------- |
+| `none`  | No caching     | Disable prompt caching              |
+| `short` | 5 minutes      | Default for API Key auth            |
+| `long`  | 1 hour         | Extended cache (requires beta flag) |
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-5": {
+          params: { cacheRetention: "long" },
+        },
+      },
+    },
+  },
+}
+```
+
+### Defaults
+
+When using Anthropic API Key authentication, Milaidy automatically applies `cacheRetention: "short"` (5-minute cache) for all Anthropic models. You can override this by explicitly setting `cacheRetention` in your config.
+
+### Legacy parameter
+
+The older `cacheControlTtl` parameter is still supported for backwards compatibility:
+
+- `"5m"` maps to `short`
+- `"1h"` maps to `long`
+
+We recommend migrating to the new `cacheRetention` parameter.
+
+Milaidy includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
+requests; keep it if you override provider headers (see [/gateway/configuration](/gateway/configuration)).
+
+## Option B: Claude setup-token
+
+**Best for:** using your Claude subscription.
+
+### Where to get a setup-token
+
+Setup-tokens are created by the **Claude Code CLI**, not the Anthropic Console. You can run this on **any machine**:
+
+```bash
+claude setup-token
+```
+
+Paste the token into Milaidy (wizard: **Anthropic token (paste setup-token)**), or run it on the gateway host:
+
+```bash
+milaidy models auth setup-token --provider anthropic
+```
+
+If you generated the token on a different machine, paste it:
+
+```bash
+milaidy models auth paste-token --provider anthropic
+```
+
+### CLI setup
+
+```bash
+# Paste a setup-token during onboarding
+milaidy onboard --auth-choice setup-token
+```
+
+### Config snippet
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+}
+```
+
+## Notes
+
+- Generate the setup-token with `claude setup-token` and paste it, or run `milaidy models auth setup-token` on the gateway host.
+- If you see “OAuth token refresh failed …” on a Claude subscription, re-auth with a setup-token. See [/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription](/gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription).
+- Auth details + reuse rules are in [/concepts/oauth](/concepts/oauth).
+
+## Troubleshooting
+
+**401 errors / token suddenly invalid**
+
+- Claude subscription auth can expire or be revoked. Re-run `claude setup-token`
+  and paste it into the **gateway host**.
+- If the Claude CLI login lives on a different machine, use
+  `milaidy models auth paste-token --provider anthropic` on the gateway host.
+
+**No API key found for provider "anthropic"**
+
+- Auth is **per agent**. New agents don’t inherit the main agent’s keys.
+- Re-run onboarding for that agent, or paste a setup-token / API key on the
+  gateway host, then verify with `milaidy models status`.
+
+**No credentials found for profile `anthropic:default`**
+
+- Run `milaidy models status` to see which auth profile is active.
+- Re-run onboarding, or paste a setup-token / API key for that profile.
+
+**No available auth profile (all in cooldown/unavailable)**
+
+- Check `milaidy models status --json` for `auth.unusableProfiles`.
+- Add another Anthropic profile or wait for cooldown.
+
+More: [/gateway/troubleshooting](/gateway/troubleshooting) and [/help/faq](/help/faq).