@symerian/symi 3.0.20 → 3.0.22

package/docs/plugins/manifest.md

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

@@ -1,322 +0,0 @@
----
-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 Symi
-  - You are configuring or developing the voice-call plugin
-title: "Voice Call Plugin"
----
-
-# Voice Call (plugin)
-
-Voice calls for Symi 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 `symi 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
-symi plugins install @symi/voice-call
-```
-
-Restart the Gateway afterwards.
-
-### Option B: install from a local folder (dev, no copying)
-
-```bash
-symi 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",
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-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.
-
-## 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.
-
-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-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
-symi voicecall call --to "+15555550123" --message "Hello from Symi"
-symi voicecall continue --call-id <id> --message "Any questions?"
-symi voicecall speak --call-id <id> --message "One moment"
-symi voicecall end --call-id <id>
-symi voicecall status --call-id <id>
-symi voicecall tail
-symi 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

@@ -1,81 +0,0 @@
----
-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 Symi
-  - You are configuring or developing the zalouser plugin
-title: "Zalo Personal Plugin"
----
-
-# Zalo Personal (plugin)
-
-Zalo Personal support for Symi 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
-symi plugins install @symi/zalouser
-```
-
-Restart the Gateway afterwards.
-
-### Option B: install from a local folder (dev)
-
-```bash
-symi 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
-symi channels login --channel zalouser
-symi channels logout --channel zalouser
-symi channels status --probe
-symi message send --channel zalouser --target <threadId> --message "Hello from Symi"
-symi directory peers list --channel zalouser --query "name"
-```
-
-## Agent tool
-
-Tool name: `zalouser`
-
-Actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`

package/docs/prose.md

@@ -1,134 +0,0 @@
----
-summary: "OpenProse: .prose workflows, slash commands, and state in Symi"
-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 Symi 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
-symi plugins enable open-prose
-```
-
-Restart the Gateway after enabling the plugin.
-
-Dev/local checkout: `symi 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 Symi 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).
-
-## Symi runtime mapping
-
-OpenProse programs map to Symi primitives:
-
-| OpenProse concept         | Symi 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 Symi tool allowlists and approval gates to control side effects.
-
-For deterministic, approval-gated workflows, compare with [Pipeline](/tools/pipeline).