nodmix 2026.5.25

package/docs/plugins/webhooks.md

@@ -0,0 +1,192 @@
+---
+summary: "Webhooks plugin: authenticated TaskFlow ingress for trusted external automation"
+read_when:
+  - You want to trigger or drive TaskFlows from an external system
+  - You are configuring the bundled webhooks plugin
+title: "Webhooks plugin"
+---
+
+The Webhooks plugin adds authenticated HTTP routes that bind external
+automation to Nodmix TaskFlows.
+
+Use it when you want a trusted system such as Zapier, n8n, a CI job, or an
+internal service to create and drive managed TaskFlows without writing a custom
+plugin first.
+
+## Where it runs
+
+The Webhooks plugin runs inside the Gateway process.
+
+If your Gateway runs on another machine, install and configure the plugin on
+that Gateway host, then restart the Gateway.
+
+## Configure routes
+
+Set config under `plugins.entries.webhooks.config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      webhooks: {
+        enabled: true,
+        config: {
+          routes: {
+            zapier: {
+              path: "/plugins/webhooks/zapier",
+              sessionKey: "agent:main:main",
+              secret: {
+                source: "env",
+                provider: "default",
+                id: "NODMIX_WEBHOOK_SECRET",
+              },
+              controllerId: "webhooks/zapier",
+              description: "Zapier TaskFlow bridge",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Route fields:
+
+- `enabled`: optional, defaults to `true`
+- `path`: optional, defaults to `/plugins/webhooks/<routeId>`
+- `sessionKey`: required session that owns the bound TaskFlows
+- `secret`: required shared secret or SecretRef
+- `controllerId`: optional controller id for created managed flows
+- `description`: optional operator note
+
+Supported `secret` inputs:
+
+- Plain string
+- SecretRef with `source: "env" | "file" | "exec"`
+
+If a secret-backed route cannot resolve its secret at startup, the plugin skips
+that route and logs a warning instead of exposing a broken endpoint.
+
+## Security model
+
+Each route is trusted to act with the TaskFlow authority of its configured
+`sessionKey`.
+
+This means the route can inspect and mutate TaskFlows owned by that session, so
+you should:
+
+- Use a strong unique secret per route
+- Prefer secret references over inline plaintext secrets
+- Bind routes to the narrowest session that fits the workflow
+- Expose only the specific webhook path you need
+
+The plugin applies:
+
+- Shared-secret authentication
+- Request body size and timeout guards
+- Fixed-window rate limiting
+- In-flight request limiting
+- Owner-bound TaskFlow access through `api.runtime.tasks.managedFlows.bindSession(...)`
+
+## Request format
+
+Send `POST` requests with:
+
+- `Content-Type: application/json`
+- `Authorization: Bearer <secret>` or `x-nodmix-webhook-secret: <secret>`
+
+Example:
+
+```bash
+curl -X POST https://gateway.example.com/plugins/webhooks/zapier \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \
+  -d '{"action":"create_flow","goal":"Review inbound queue"}'
+```
+
+## Supported actions
+
+The plugin currently accepts these JSON `action` values:
+
+- `create_flow`
+- `get_flow`
+- `list_flows`
+- `find_latest_flow`
+- `resolve_flow`
+- `get_task_summary`
+- `set_waiting`
+- `resume_flow`
+- `finish_flow`
+- `fail_flow`
+- `request_cancel`
+- `cancel_flow`
+- `run_task`
+
+### `create_flow`
+
+Creates a managed TaskFlow for the route's bound session.
+
+Example:
+
+```json
+{
+  "action": "create_flow",
+  "goal": "Review inbound queue",
+  "status": "queued",
+  "notifyPolicy": "done_only"
+}
+```
+
+### `run_task`
+
+Creates a managed child task inside an existing managed TaskFlow.
+
+Allowed runtimes are:
+
+- `subagent`
+- `acp`
+
+Example:
+
+```json
+{
+  "action": "run_task",
+  "flowId": "flow_123",
+  "runtime": "acp",
+  "childSessionKey": "agent:main:acp:worker",
+  "task": "Inspect the next message batch"
+}
+```
+
+## Response shape
+
+Successful responses return:
+
+```json
+{
+  "ok": true,
+  "routeId": "zapier",
+  "result": {}
+}
+```
+
+Rejected requests return:
+
+```json
+{
+  "ok": false,
+  "routeId": "zapier",
+  "code": "not_found",
+  "error": "TaskFlow not found.",
+  "result": {}
+}
+```
+
+The plugin intentionally scrubs owner/session metadata from webhook responses.
+
+## Related docs
+
+- [Plugin runtime SDK](/plugins/sdk-runtime)
+- [Hooks and webhooks overview](/automation/hooks)
+- [CLI webhooks](/cli/webhooks)

package/docs/plugins/zalouser.md

@@ -0,0 +1,86 @@
+---
+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 Nodmix
+  - You are configuring or developing the zalouser plugin
+title: "Zalo personal plugin"
+---
+
+Zalo Personal support for Nodmix via a plugin, using native `zca-js` to automate a normal Zalo user account.
+
+<Warning>
+Unofficial automation may lead to account suspension or ban. Use at your own risk.
+</Warning>
+
+## 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
+nodmix plugins install @nodmix/zalouser
+```
+
+Use the bare package to follow the current official release tag. Pin an exact
+version only when you need a reproducible install.
+
+Restart the Gateway afterwards.
+
+### Option B: install from a local folder (dev)
+
+```bash
+PLUGIN_SRC=./path/to/local/zalouser-plugin
+nodmix plugins install "$PLUGIN_SRC"
+cd "$PLUGIN_SRC" && 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
+nodmix channels login --channel zalouser
+nodmix channels logout --channel zalouser
+nodmix channels status --probe
+nodmix message send --channel zalouser --target <threadId> --message "Hello from Nodmix"
+nodmix 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.
+
+## Related
+
+- [Building plugins](/plugins/building-plugins)
+- [ClawHub](/clawhub)

package/docs/prose.md

@@ -0,0 +1,137 @@
+---
+summary: "OpenProse: .prose workflows, slash commands, and state in Nodmix"
+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 is a portable, markdown-first workflow format for orchestrating AI sessions. In Nodmix 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
+nodmix plugins enable open-prose
+```
+
+Restart the Gateway after enabling the plugin.
+
+Dev/local checkout: `nodmix plugins install ./path/to/local/open-prose-plugin`
+
+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 Nodmix 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).
+
+## Nodmix runtime mapping
+
+OpenProse programs map to Nodmix primitives:
+
+| OpenProse concept         | Nodmix 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 Nodmix tool allowlists and approval gates to control side effects.
+
+For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).
+
+## Related
+
+- [Text-to-speech](/tools/tts)
+- [Markdown formatting](/concepts/markdown-formatting)

package/docs/providers/alibaba.md

@@ -0,0 +1,158 @@
+---
+summary: "Alibaba Model Studio Wan video generation in Nodmix"
+title: "Alibaba Model Studio"
+read_when:
+  - You want to use Alibaba Wan video generation in Nodmix
+  - You need Model Studio or DashScope API key setup for video generation
+---
+
+Nodmix ships a bundled `alibaba` plugin that registers a video-generation provider for Wan models on Alibaba Model Studio (the international name for DashScope). The plugin is enabled by default; you only need to set an API key.
+
+| Property         | Value                                                                           |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Provider id      | `alibaba`                                                                       |
+| Plugin           | bundled, `enabledByDefault: true`                                               |
+| Auth env vars    | `MODELSTUDIO_API_KEY` → `DASHSCOPE_API_KEY` → `QWEN_API_KEY` (first match wins) |
+| Onboarding flag  | `--auth-choice alibaba-model-studio-api-key`                                    |
+| Direct CLI flag  | `--alibaba-model-studio-api-key <key>`                                          |
+| Default model    | `alibaba/wan2.6-t2v`                                                            |
+| Default base URL | `https://dashscope-intl.aliyuncs.com`                                           |
+
+## Getting started
+
+<Steps>
+  <Step title="Set an API key">
+    Use onboarding to store the key against the `alibaba` provider:
+
+    ```bash
+    nodmix onboard --auth-choice alibaba-model-studio-api-key
+    ```
+
+    Or pass the key directly during install/onboarding:
+
+    ```bash
+    nodmix onboard --alibaba-model-studio-api-key <your-key>
+    ```
+
+    Or export any of the accepted env vars before starting the Gateway:
+
+    ```bash
+    export MODELSTUDIO_API_KEY=sk-...
+    # or DASHSCOPE_API_KEY=...
+    # or QWEN_API_KEY=...
+    ```
+
+  </Step>
+  <Step title="Set a default video model">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          videoGenerationModel: {
+            primary: "alibaba/wan2.6-t2v",
+          },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Verify the provider is configured">
+    ```bash
+    nodmix models list --provider alibaba
+    ```
+
+    The list should include all five bundled Wan models. If `MODELSTUDIO_API_KEY` is unresolved, `nodmix models status --json` reports the missing credential under `auth.unusableProfiles`.
+
+  </Step>
+</Steps>
+
+<Note>
+  The Alibaba plugin and the [Qwen plugin](/providers/qwen) both authenticate against DashScope and accept overlapping env vars. Use `alibaba/...` model ids to drive the dedicated Wan video surface; use `qwen/...` ids when you want Qwen's chat, embedding, or media-understanding surface.
+</Note>
+
+## Built-in Wan models
+
+| Model ref                  | Mode                      |
+| -------------------------- | ------------------------- |
+| `alibaba/wan2.6-t2v`       | Text-to-video (default)   |
+| `alibaba/wan2.6-i2v`       | Image-to-video            |
+| `alibaba/wan2.6-r2v`       | Reference-to-video        |
+| `alibaba/wan2.6-r2v-flash` | Reference-to-video (fast) |
+| `alibaba/wan2.7-r2v`       | Reference-to-video        |
+
+## Capabilities and limits
+
+The bundled provider mirrors DashScope's Wan video API caps. All three modes share the same per-request video count and duration cap; only the input shape differs.
+
+| Mode               | Max output videos | Max input images | Max input videos | Max duration | Supported controls                                        |
+| ------------------ | ----------------- | ---------------- | ---------------- | ------------ | --------------------------------------------------------- |
+| Text-to-video      | 1                 | n/a              | n/a              | 10 s         | `size`, `aspectRatio`, `resolution`, `audio`, `watermark` |
+| Image-to-video     | 1                 | 1                | n/a              | 10 s         | `size`, `aspectRatio`, `resolution`, `audio`, `watermark` |
+| Reference-to-video | 1                 | n/a              | 4                | 10 s         | `size`, `aspectRatio`, `resolution`, `audio`, `watermark` |
+
+When a request omits `durationSeconds`, the provider sends DashScope's accepted default of **5 seconds**. Set `durationSeconds` explicitly on the [video generation tool](/tools/video-generation) to extend up to 10 s.
+
+<Warning>
+  Reference image and video inputs must be remote `http(s)` URLs. Local file paths are not accepted by DashScope's reference modes; upload to object storage first or use the [media tool](/tools/media-overview) flow that already produces a public URL.
+</Warning>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Override the DashScope base URL">
+    The provider defaults to the international DashScope endpoint. To target the China-region endpoint, set:
+
+    ```json5
+    {
+      models: {
+        providers: {
+          alibaba: {
+            baseUrl: "https://dashscope.aliyuncs.com",
+          },
+        },
+      },
+    }
+    ```
+
+    The provider strips trailing slashes before constructing AIGC task URLs.
+
+  </Accordion>
+
+  <Accordion title="Auth env priority">
+    Nodmix resolves the Alibaba API key from environment variables in this order, taking the first non-empty value:
+
+    1. `MODELSTUDIO_API_KEY`
+    2. `DASHSCOPE_API_KEY`
+    3. `QWEN_API_KEY`
+
+    Configured `auth.profiles` entries (set via `nodmix models auth login`) override env-var resolution. See [Auth profiles in the models FAQ](/help/faq-models#what-is-an-auth-profile) for profile rotation, cooldown, and override mechanics.
+
+  </Accordion>
+
+  <Accordion title="Relationship to the Qwen plugin">
+    Both bundled plugins talk to DashScope and accept overlapping API keys. Use:
+
+    - `alibaba/wan*.*` ids to drive the dedicated Wan video provider documented on this page.
+    - `qwen/*` ids for Qwen chat, embedding, and media understanding (see [Qwen](/providers/qwen)).
+
+    Setting `MODELSTUDIO_API_KEY` once authenticates both plugins because the auth env var list intentionally overlaps; you do not need to onboard each plugin separately.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Shared video tool parameters and provider selection.
+  </Card>
+  <Card title="Qwen" href="/providers/qwen" icon="microchip">
+    Qwen chat, embedding, and media-understanding setup on the same DashScope auth.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
+    Agent defaults and model configuration.
+  </Card>
+  <Card title="Models FAQ" href="/help/faq-models" icon="circle-question">
+    Auth profiles, switching models, and resolving "no profile" errors.
+  </Card>
+</CardGroup>