@quantumclaw/quantumclaw 2026.3.22

package/docs/plugins/voice-call.md

@@ -0,0 +1,380 @@
+---
+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 QuantumClaw
+  - You are configuring or developing the voice-call plugin
+title: "Voice Call Plugin"
+---
+
+# Voice Call (plugin)
+
+Voice calls for QuantumClaw 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 `quantumclaw 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
+quantumclaw plugins install @quantumclaw/voice-call
+```
+
+Restart the Gateway afterwards.
+
+### Option B: install from a local folder (dev, no copying)
+
+```bash
+quantumclaw 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: "...",
+          },
+
+          telnyx: {
+            apiKey: "...",
+            connectionId: "...",
+            // Telnyx webhook public key from the Telnyx Mission Control Portal
+            // (Base64 string; can also be set via TELNYX_PUBLIC_KEY).
+            publicKey: "...",
+          },
+
+          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",
+            preStartTimeoutMs: 5000,
+            maxPendingConnections: 32,
+            maxPendingConnectionsPerIp: 4,
+            maxConnections: 128,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+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).
+- Telnyx requires `telnyx.publicKey` (or `TELNYX_PUBLIC_KEY`) unless `skipSignatureVerification` is true.
+- `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.
+- Streaming security defaults:
+  - `streaming.preStartTimeoutMs` closes sockets that never send a valid `start` frame.
+  - `streaming.maxPendingConnections` caps total unauthenticated pre-start sockets.
+  - `streaming.maxPendingConnectionsPerIp` caps unauthenticated pre-start sockets per source IP.
+  - `streaming.maxConnections` caps total open media stream sockets (pending + active).
+
+## Stale call reaper
+
+Use `staleCallReaperSeconds` to end calls that never receive a terminal webhook
+(for example, notify-mode calls that never complete). The default is `0`
+(disabled).
+
+Recommended ranges:
+
+- **Production:** `120`–`300` seconds for notify-style flows.
+- Keep this value **higher than `maxDurationSeconds`** so normal calls can
+  finish. A good starting point is `maxDurationSeconds + 30–60` seconds.
+
+Example:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          maxDurationSeconds: 300,
+          staleCallReaperSeconds: 360,
+        },
+      },
+    },
+  },
+}
+```
+
+## 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.
+
+Webhook replay protection is enabled for Twilio and Plivo. Replayed valid webhook
+requests are acknowledged but skipped for side effects.
+
+Twilio conversation turns include a per-turn token in `<Gather>` callbacks, so
+stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
+
+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 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:
+
+- **Microsoft speech is ignored for voice calls** (telephony audio needs PCM; the current Microsoft transport does not expose telephony PCM output).
+- Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.
+- If a Twilio media stream is already active, Voice Call does not fall back to TwiML `<Say>`. If telephony TTS is unavailable in that state, the playback request fails instead of mixing two playback paths.
+
+### 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?",
+}
+```
+
+`inboundPolicy: "allowlist"` is a low-assurance caller-ID screen. The plugin
+normalizes the provider-supplied `From` value and compares it to `allowFrom`.
+Webhook verification authenticates provider delivery and payload integrity, but
+it does not prove PSTN/VoIP caller-number ownership. Treat `allowFrom` as
+caller-ID filtering, not strong caller identity.
+
+Auto-responses use the agent system. Tune with:
+
+- `responseModel`
+- `responseSystemPrompt`
+- `responseTimeoutMs`
+
+### Spoken output contract
+
+For auto-responses, Voice Call appends a strict spoken-output contract to the system prompt:
+
+- `{"spoken":"..."}`
+
+Voice Call then extracts speech text defensively:
+
+- Ignores payloads marked as reasoning/error content.
+- Parses direct JSON, fenced JSON, or inline `"spoken"` keys.
+- Falls back to plain text and removes likely planning/meta lead-in paragraphs.
+
+This keeps spoken playback focused on caller-facing text and avoids leaking planning text into audio.
+
+### Conversation startup behavior
+
+For outbound `conversation` calls, first-message handling is tied to live playback state:
+
+- Barge-in queue clear and auto-response are suppressed only while the initial greeting is actively speaking.
+- If initial playback fails, the call returns to `listening` and the initial message remains queued for retry.
+- Initial playback for Twilio streaming starts on stream connect without extra delay.
+
+### Twilio stream disconnect grace
+
+When a Twilio media stream disconnects, Voice Call waits `2000ms` before auto-ending the call:
+
+- If the stream reconnects during that window, auto-end is canceled.
+- If no stream is re-registered after the grace period, the call is ended to prevent stuck active calls.
+
+## CLI
+
+```bash
+quantumclaw voicecall call --to "+15555550123" --message "Hello from QuantumClaw"
+quantumclaw voicecall start --to "+15555550123"   # alias for call
+quantumclaw voicecall continue --call-id <id> --message "Any questions?"
+quantumclaw voicecall speak --call-id <id> --message "One moment"
+quantumclaw voicecall end --call-id <id>
+quantumclaw voicecall status --call-id <id>
+quantumclaw voicecall tail
+quantumclaw voicecall latency                     # summarize turn latency from logs
+quantumclaw voicecall expose --mode funnel
+```
+
+`latency` reads `calls.jsonl` from the default voice-call storage path. Use
+`--file <path>` to point at a different log and `--last <n>` to limit analysis
+to the last N records (default 200). Output includes p50/p90/p99 for turn
+latency and listen-wait times.
+
+## 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,77 @@
+---
+summary: "Zalo Personal plugin: QR login + messaging via native zca-js (plugin install + channel config + tool)"
+read_when:
+  - You want Zalo Personal (unofficial) support in QuantumClaw
+  - You are configuring or developing the zalouser plugin
+title: "Zalo Personal Plugin"
+---
+
+# Zalo Personal (plugin)
+
+Zalo Personal support for QuantumClaw via a plugin, using native `zca-js` 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.
+
+No external `zca`/`openzca` CLI binary is required.
+
+## Install
+
+### Option A: install from npm
+
+```bash
+quantumclaw plugins install @quantumclaw/zalouser
+```
+
+Restart the Gateway afterwards.
+
+### Option B: install from a local folder (dev)
+
+```bash
+quantumclaw plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
+```
+
+Restart the Gateway afterwards.
+
+## Config
+
+Channel config lives under `channels.zalouser` (not `plugins.entries.*`):
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## CLI
+
+```bash
+quantumclaw channels login --channel zalouser
+quantumclaw channels logout --channel zalouser
+quantumclaw channels status --probe
+quantumclaw message send --channel zalouser --target <threadId> --message "Hello from QuantumClaw"
+quantumclaw directory peers list --channel zalouser --query "name"
+```
+
+## Agent tool
+
+Tool name: `zalouser`
+
+Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
+
+Channel message actions also support `react` for message reactions.

package/docs/prose.md

@@ -0,0 +1,134 @@
+---
+summary: "OpenProse: .prose workflows, slash commands, and state in QuantumClaw"
+read_when:
+  - You want to run or write .prose workflows
+  - You want to enable the OpenProse plugin
+  - You need to understand state storage
+title: "OpenProse"
+---
+
+# OpenProse
+
+OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In QuantumClaw it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
+
+Official site: [https://www.prose.md](https://www.prose.md)
+
+## What it can do
+
+- Multi-agent research + synthesis with explicit parallelism.
+- Repeatable approval-safe workflows (code review, incident triage, content pipelines).
+- Reusable `.prose` programs you can run across supported agent runtimes.
+
+## Install + enable
+
+Bundled plugins are disabled by default. Enable OpenProse:
+
+```bash
+quantumclaw plugins enable open-prose
+```
+
+Restart the Gateway after enabling the plugin.
+
+Dev/local checkout: `quantumclaw plugins install ./extensions/open-prose`
+
+Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
+
+## Slash command
+
+OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses QuantumClaw tools under the hood.
+
+Common commands:
+
+```
+/prose help
+/prose run <file.prose>
+/prose run <handle/slug>
+/prose run <https://example.com/file.prose>
+/prose compile <file.prose>
+/prose examples
+/prose update
+```
+
+## Example: a simple `.prose` file
+
+```prose
+# Research + synthesis with two agents running in parallel.
+
+input topic: "What should we research?"
+
+agent researcher:
+  model: sonnet
+  prompt: "You research thoroughly and cite sources."
+
+agent writer:
+  model: opus
+  prompt: "You write a concise summary."
+
+parallel:
+  findings = session: researcher
+    prompt: "Research {topic}."
+  draft = session: writer
+    prompt: "Summarize {topic}."
+
+session "Merge the findings + draft into a final answer."
+context: { findings, draft }
+```
+
+## File locations
+
+OpenProse keeps state under `.prose/` in your workspace:
+
+```
+.prose/
+├── .env
+├── runs/
+│   └── {YYYYMMDD}-{HHMMSS}-{random}/
+│       ├── program.prose
+│       ├── state.md
+│       ├── bindings/
+│       └── agents/
+└── agents/
+```
+
+User-level persistent agents live at:
+
+```
+~/.prose/agents/
+```
+
+## State modes
+
+OpenProse supports multiple state backends:
+
+- **filesystem** (default): `.prose/runs/...`
+- **in-context**: transient, for small programs
+- **sqlite** (experimental): requires `sqlite3` binary
+- **postgres** (experimental): requires `psql` and a connection string
+
+Notes:
+
+- sqlite/postgres are opt-in and experimental.
+- postgres credentials flow into subagent logs; use a dedicated, least-privileged DB.
+
+## Remote programs
+
+`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
+Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST).
+
+## QuantumClaw runtime mapping
+
+OpenProse programs map to QuantumClaw primitives:
+
+| OpenProse concept         | QuantumClaw tool    |
+| ------------------------- | ---------------- |
+| Spawn session / Task tool | `sessions_spawn` |
+| File read/write           | `read` / `write` |
+| Web fetch                 | `web_fetch`      |
+
+If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](/tools/skills-config).
+
+## Security + approvals
+
+Treat `.prose` files like code. Review before running. Use QuantumClaw tool allowlists and approval gates to control side effects.
+
+For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).