durar-ai 2026.4.4

package/docs/channels/zalo.md

@@ -0,0 +1,254 @@
+---
+summary: "Zalo bot support status, capabilities, and configuration"
+read_when:
+  - Working on Zalo features or webhooks
+title: "Zalo"
+---
+
+# Zalo (Bot API)
+
+Status: experimental. DMs are supported. The [Capabilities](#capabilities) section below reflects current Marketplace-bot behavior.
+
+## Bundled plugin
+
+Zalo ships as a bundled plugin in current Durar releases, so normal packaged
+builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Zalo, install it
+manually:
+
+- Install via CLI: `Durar plugins install @Durar/zalo`
+- Or from a source checkout: `Durar plugins install ./path/to/local/zalo-plugin`
+- Details: [Plugins](/tools/plugin)
+
+## Quick setup (beginner)
+
+1. Ensure the Zalo plugin is available.
+   - Current packaged Durar releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
+2. Set the token:
+   - Env: `ZALO_BOT_TOKEN=...`
+   - Or config: `channels.zalo.accounts.default.botToken: "..."`.
+3. Restart the gateway (or finish setup).
+4. DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          botToken: "12345689:abc-xyz",
+          dmPolicy: "pairing",
+        },
+      },
+    },
+  },
+}
+```
+
+## What it is
+
+Zalo is a Vietnam-focused messaging app; its Bot API lets the Gateway run a bot for 1:1 conversations.
+It is a good fit for support or notifications where you want deterministic routing back to Zalo.
+
+This page reflects current Durar behavior for **Zalo Bot Creator / Marketplace bots**.
+**Zalo Official Account (OA) bots** are a different Zalo product surface and may behave differently.
+
+- A Zalo Bot API channel owned by the Gateway.
+- Deterministic routing: replies go back to Zalo; the model never chooses channels.
+- DMs share the agent's main session.
+- The [Capabilities](#capabilities) section below shows current Marketplace-bot support.
+
+## Setup (fast path)
+
+### 1) Create a bot token (Zalo Bot Platform)
+
+1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in.
+2. Create a new bot and configure its settings.
+3. Copy the full bot token (typically `numeric_id:secret`). For Marketplace bots, the usable runtime token may appear in the bot's welcome message after creation.
+
+### 2) Configure the token (env or config)
+
+Example:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      accounts: {
+        default: {
+          botToken: "12345689:abc-xyz",
+          dmPolicy: "pairing",
+        },
+      },
+    },
+  },
+}
+```
+
+If you later move to a Zalo bot surface where groups are available, you can add group-specific config such as `groupPolicy` and `groupAllowFrom` explicitly. For current Marketplace-bot behavior, see [Capabilities](#capabilities).
+
+Env option: `ZALO_BOT_TOKEN=...` (works for the default account only).
+
+Multi-account support: use `channels.zalo.accounts` with per-account tokens and optional `name`.
+
+3. Restart the gateway. Zalo starts when a token is resolved (env or config).
+4. DM access defaults to pairing. Approve the code when the bot is first contacted.
+
+## How it works (behavior)
+
+- Inbound messages are normalized into the shared channel envelope with media placeholders.
+- Replies always route back to the same Zalo chat.
+- Long-polling by default; webhook mode available with `channels.zalo.webhookUrl`.
+
+## Limits
+
+- Outbound text is chunked to 2000 characters (Zalo API limit).
+- Media downloads/uploads are capped by `channels.zalo.mediaMaxMb` (default 5).
+- Streaming is blocked by default due to the 2000 char limit making streaming less useful.
+
+## Access control (DMs)
+
+### DM access
+
+- Default: `channels.zalo.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `Durar pairing list zalo`
+  - `Durar pairing approve zalo <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
+- `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available).
+
+## Access control (Groups)
+
+For **Zalo Bot Creator / Marketplace bots**, group support was not available in practice because the bot could not be added to a group at all.
+
+That means the group-related config keys below exist in the schema, but were not usable for Marketplace bots:
+
+- `channels.zalo.groupPolicy` controls group inbound handling: `open | allowlist | disabled`.
+- `channels.zalo.groupAllowFrom` restricts which sender IDs can trigger the bot in groups.
+- If `groupAllowFrom` is unset, Zalo falls back to `allowFrom` for sender checks.
+- Runtime note: if `channels.zalo` is missing entirely, runtime still falls back to `groupPolicy="allowlist"` for safety.
+
+The group policy values (when group access is available on your bot surface) are:
+
+- `groupPolicy: "disabled"` — blocks all group messages.
+- `groupPolicy: "open"` — allows any group member (mention-gated).
+- `groupPolicy: "allowlist"` — fail-closed default; only allowed senders are accepted.
+
+If you are using a different Zalo bot product surface and have verified working group behavior, document that separately rather than assuming it matches the Marketplace-bot flow.
+
+## Long-polling vs webhook
+
+- Default: long-polling (no public URL required).
+- Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`.
+  - The webhook secret must be 8-256 characters.
+  - Webhook URL must use HTTPS.
+  - Zalo sends events with `X-Bot-Api-Secret-Token` header for verification.
+  - Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL path).
+  - Requests must use `Content-Type: application/json` (or `+json` media types).
+  - Duplicate events (`event_name + message_id`) are ignored for a short replay window.
+  - Burst traffic is rate-limited per path/source and may return HTTP 429.
+
+**Note:** getUpdates (polling) and webhook are mutually exclusive per Zalo API docs.
+
+## Supported message types
+
+For a quick support snapshot, see [Capabilities](#capabilities). The notes below add detail where the behavior needs extra context.
+
+- **Text messages**: Full support with 2000 character chunking.
+- **Plain URLs in text**: Behave like normal text input.
+- **Link previews / rich link cards**: See the Marketplace-bot status in [Capabilities](#capabilities); they did not reliably trigger a reply.
+- **Image messages**: See the Marketplace-bot status in [Capabilities](#capabilities); inbound image handling was unreliable (typing indicator without a final reply).
+- **Stickers**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Voice notes / audio files / video / generic file attachments**: See the Marketplace-bot status in [Capabilities](#capabilities).
+- **Unsupported types**: Logged (for example, messages from protected users).
+
+## Capabilities
+
+This table summarizes current **Zalo Bot Creator / Marketplace bot** behavior in Durar.
+
+| Feature                     | Status                                  |
+| --------------------------- | --------------------------------------- |
+| Direct messages             | ✅ Supported                            |
+| Groups                      | ❌ Not available for Marketplace bots   |
+| Media (inbound images)      | ⚠️ Limited / verify in your environment |
+| Media (outbound images)     | ⚠️ Not re-tested for Marketplace bots   |
+| Plain URLs in text          | ✅ Supported                            |
+| Link previews               | ⚠️ Unreliable for Marketplace bots      |
+| Reactions                   | ❌ Not supported                        |
+| Stickers                    | ⚠️ No agent reply for Marketplace bots  |
+| Voice notes / audio / video | ⚠️ No agent reply for Marketplace bots  |
+| File attachments            | ⚠️ No agent reply for Marketplace bots  |
+| Threads                     | ❌ Not supported                        |
+| Polls                       | ❌ Not supported                        |
+| Native commands             | ❌ Not supported                        |
+| Streaming                   | ⚠️ Blocked (2000 char limit)            |
+
+## Delivery targets (CLI/cron)
+
+- Use a chat id as the target.
+- Example: `Durar message send --channel zalo --target 123456789 --message "hi"`.
+
+## Troubleshooting
+
+**Bot doesn't respond:**
+
+- Check that the token is valid: `Durar channels status --probe`
+- Verify the sender is approved (pairing or allowFrom)
+- Check gateway logs: `Durar logs --follow`
+
+**Webhook not receiving events:**
+
+- Ensure webhook URL uses HTTPS
+- Verify secret token is 8-256 characters
+- Confirm the gateway HTTP endpoint is reachable on the configured path
+- Check that getUpdates polling is not running (they're mutually exclusive)
+
+## Configuration reference (Zalo)
+
+Full configuration: [Configuration](/gateway/configuration)
+
+The flat top-level keys (`channels.zalo.botToken`, `channels.zalo.dmPolicy`, and similar) are a legacy single-account shorthand. Prefer `channels.zalo.accounts.<id>.*` for new configs. Both forms are still documented here because they exist in the schema.
+
+Provider options:
+
+- `channels.zalo.enabled`: enable/disable channel startup.
+- `channels.zalo.botToken`: bot token from Zalo Bot Platform.
+- `channels.zalo.tokenFile`: read token from a regular file path. Symlinks are rejected.
+- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.zalo.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`. The wizard will ask for numeric IDs.
+- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (default: allowlist). Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `channels.zalo.groupAllowFrom`: group sender allowlist (user IDs). Falls back to `allowFrom` when unset.
+- `channels.zalo.mediaMaxMb`: inbound/outbound media cap (MB, default 5).
+- `channels.zalo.webhookUrl`: enable webhook mode (HTTPS required).
+- `channels.zalo.webhookSecret`: webhook secret (8-256 chars).
+- `channels.zalo.webhookPath`: webhook path on the gateway HTTP server.
+- `channels.zalo.proxy`: proxy URL for API requests.
+
+Multi-account options:
+
+- `channels.zalo.accounts.<id>.botToken`: per-account token.
+- `channels.zalo.accounts.<id>.tokenFile`: per-account regular token file. Symlinks are rejected.
+- `channels.zalo.accounts.<id>.name`: display name.
+- `channels.zalo.accounts.<id>.enabled`: enable/disable account.
+- `channels.zalo.accounts.<id>.dmPolicy`: per-account DM policy.
+- `channels.zalo.accounts.<id>.allowFrom`: per-account allowlist.
+- `channels.zalo.accounts.<id>.groupPolicy`: per-account group policy. Present in config; see [Capabilities](#capabilities) and [Access control (Groups)](#access-control-groups) for current Marketplace-bot behavior.
+- `channels.zalo.accounts.<id>.groupAllowFrom`: per-account group sender allowlist.
+- `channels.zalo.accounts.<id>.webhookUrl`: per-account webhook URL.
+- `channels.zalo.accounts.<id>.webhookSecret`: per-account webhook secret.
+- `channels.zalo.accounts.<id>.webhookPath`: per-account webhook path.
+- `channels.zalo.accounts.<id>.proxy`: per-account proxy URL.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/zalouser.md

@@ -0,0 +1,195 @@
+---
+summary: "Zalo personal account support via native zca-js (QR login), capabilities, and configuration"
+read_when:
+  - Setting up Zalo Personal for Durar
+  - Debugging Zalo Personal login or message flow
+title: "Zalo Personal"
+---
+
+# Zalo Personal (unofficial)
+
+Status: experimental. This integration automates a **personal Zalo account** via native `zca-js` inside Durar.
+
+> **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
+
+## Bundled plugin
+
+Zalo Personal ships as a bundled plugin in current Durar releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes Zalo Personal,
+install it manually:
+
+- Install via CLI: `Durar plugins install @Durar/zalouser`
+- Or from a source checkout: `Durar plugins install ./path/to/local/zalouser-plugin`
+- Details: [Plugins](/tools/plugin)
+
+No external `zca`/`openzca` CLI binary is required.
+
+## Quick setup (beginner)
+
+1. Ensure the Zalo Personal plugin is available.
+   - Current packaged Durar releases already bundle it.
+   - Older/custom installs can add it manually with the commands above.
+2. Login (QR, on the Gateway machine):
+   - `Durar channels login --channel zalouser`
+   - Scan the QR code with the Zalo mobile app.
+3. Enable the channel:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+4. Restart the Gateway (or finish setup).
+5. DM access defaults to pairing; approve the pairing code on first contact.
+
+## What it is
+
+- Runs entirely in-process via `zca-js`.
+- Uses native event listeners to receive inbound messages.
+- Sends replies directly through the JS API (text/media/link).
+- Designed for “personal account” use cases where Zalo Bot API is not available.
+
+## 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.
+
+## Finding IDs (directory)
+
+Use the directory CLI to discover peers/groups and their IDs:
+
+```bash
+Durar directory self --channel zalouser
+Durar directory peers list --channel zalouser --query "name"
+Durar directory groups list --channel zalouser --query "work"
+```
+
+## Limits
+
+- Outbound text is chunked to ~2000 characters (Zalo client limits).
+- Streaming is blocked by default.
+
+## Access control (DMs)
+
+`channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
+
+`channels.zalouser.allowFrom` accepts user IDs or names. During setup, names are resolved to IDs using the plugin's in-process contact lookup.
+
+Approve via:
+
+- `Durar pairing list zalouser`
+- `Durar pairing approve zalouser <code>`
+
+## Group access (optional)
+
+- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Restrict to an allowlist with:
+  - `channels.zalouser.groupPolicy = "allowlist"`
+  - `channels.zalouser.groups` (keys should be stable group IDs; names are resolved to IDs on startup when possible)
+  - `channels.zalouser.groupAllowFrom` (controls which senders in allowed groups can trigger the bot)
+- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
+- The configure wizard can prompt for group allowlists.
+- On startup, Durar resolves group/user names in allowlists to IDs and logs the mapping.
+- Group allowlist matching is ID-only by default. Unresolved names are ignored for auth unless `channels.zalouser.dangerouslyAllowNameMatching: true` is enabled.
+- `channels.zalouser.dangerouslyAllowNameMatching: true` is a break-glass compatibility mode that re-enables mutable group-name matching.
+- If `groupAllowFrom` is unset, runtime falls back to `allowFrom` for group sender checks.
+- Sender checks apply to both normal group messages and control commands (for example `/new`, `/reset`).
+
+Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["1471383327500481391"],
+      groups: {
+        "123456789": { allow: true },
+        "Work Chat": { allow: true },
+      },
+    },
+  },
+}
+```
+
+### Group mention gating
+
+- `channels.zalouser.groups.<group>.requireMention` controls whether group replies require a mention.
+- Resolution order: exact group id/name -> normalized group slug -> `*` -> default (`true`).
+- This applies both to allowlisted groups and open group mode.
+- Authorized control commands (for example `/new`) can bypass mention gating.
+- When a group message is skipped because mention is required, Durar stores it as pending group history and includes it on the next processed group message.
+- Group history limit defaults to `messages.groupChat.historyLimit` (fallback `50`). You can override per account with `channels.zalouser.historyLimit`.
+
+Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groups: {
+        "*": { allow: true, requireMention: true },
+        "Work Chat": { allow: true, requireMention: false },
+      },
+    },
+  },
+}
+```
+
+## Multi-account
+
+Accounts map to `zalouser` profiles in Durar state. Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      defaultAccount: "default",
+      accounts: {
+        work: { enabled: true, profile: "work" },
+      },
+    },
+  },
+}
+```
+
+## Typing, reactions, and delivery acknowledgements
+
+- Durar sends a typing event before dispatching a reply (best-effort).
+- Message reaction action `react` is supported for `zalouser` in channel actions.
+  - Use `remove: true` to remove a specific reaction emoji from a message.
+  - Reaction semantics: [Reactions](/tools/reactions)
+- For inbound messages that include event metadata, Durar sends delivered + seen acknowledgements (best-effort).
+
+## Troubleshooting
+
+**Login doesn't stick:**
+
+- `Durar channels status --probe`
+- Re-login: `Durar channels logout --channel zalouser && Durar channels login --channel zalouser`
+
+**Allowlist/group name didn't resolve:**
+
+- Use numeric IDs in `allowFrom`/`groupAllowFrom`/`groups`, or exact friend/group names.
+
+**Upgraded from old CLI-based setup:**
+
+- Remove any old external `zca` process assumptions.
+- The channel now runs fully in Durar without external CLI binaries.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/ci.md

@@ -0,0 +1,66 @@
+---
+title: CI Pipeline
+summary: "CI job graph, scope gates, and local command equivalents"
+read_when:
+  - You need to understand why a CI job did or did not run
+  - You are debugging failing GitHub Actions checks
+---
+
+# CI Pipeline
+
+The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only unrelated areas changed.
+
+## Job Overview
+
+| Job                      | Purpose                                                                                  | When it runs                        |
+| ------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `preflight`              | Detect docs-only changes, changed scopes, changed extensions, and build the CI manifest  | Always on non-draft pushes and PRs  |
+| `security-fast`          | Private key detection, workflow audit via `zizmor`, production dependency audit          | Always on non-draft pushes and PRs  |
+| `build-artifacts`        | Build `dist/` and the Control UI once, upload reusable artifacts for downstream jobs     | Node-relevant changes               |
+| `checks-fast-core`       | Fast Linux correctness lanes such as bundled/plugin-contract/protocol checks             | Node-relevant changes               |
+| `checks-fast-extensions` | Aggregate the extension shard lanes after `checks-fast-extensions-shard` completes       | Node-relevant changes               |
+| `extension-fast`         | Focused tests for only the changed bundled plugins                                       | When extension changes are detected |
+| `check`                  | Main local gate in CI: `pnpm check` plus `pnpm build:strict-smoke`                       | Node-relevant changes               |
+| `check-additional`       | Architecture and boundary guards plus the gateway watch regression harness               | Node-relevant changes               |
+| `build-smoke`            | Built-CLI smoke tests and startup-memory smoke                                           | Node-relevant changes               |
+| `checks`                 | Heavier Linux Node lanes: full tests, channel tests, and push-only Node 22 compatibility | Node-relevant changes               |
+| `check-docs`             | Docs formatting, lint, and broken-link checks                                            | Docs changed                        |
+| `skills-python`          | Ruff + pytest for Python-backed skills                                                   | Python-skill-relevant changes       |
+| `checks-windows`         | Windows-specific test lanes                                                              | Windows-relevant changes            |
+| `macos-node`             | macOS TypeScript test lane using the shared built artifacts                              | macOS-relevant changes              |
+| `macos-swift`            | Swift lint, build, and tests for the macOS app                                           | macOS-relevant changes              |
+| `android`                | Android build and test matrix                                                            | Android-relevant changes            |
+
+## Fail-Fast Order
+
+Jobs are ordered so cheap checks fail before expensive ones run:
+
+1. `preflight` decides which lanes exist at all. The `docs-scope` and `changed-scope` logic are steps inside this job, not standalone jobs.
+2. `security-fast`, `check`, `check-additional`, `check-docs`, and `skills-python` fail quickly without waiting on the heavier artifact and platform matrix jobs.
+3. `build-artifacts` overlaps with the fast Linux lanes so downstream consumers can start as soon as the shared build is ready.
+4. Heavier platform and runtime lanes fan out after that: `checks-fast-core`, `checks-fast-extensions`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, and `android`.
+
+Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.
+The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It computes `run_install_smoke` from the narrower changed-smoke signal, so Docker/install smoke only runs for install, packaging, and container-relevant changes.
+
+On pushes, the `checks` matrix adds the push-only `compat-node22` lane. On pull requests, that lane is skipped and the matrix stays focused on the normal test/channel lanes.
+
+## Runners
+
+| Runner                           | Jobs                                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `blacksmith-16vcpu-ubuntu-2404`  | `preflight`, `security-fast`, `build-artifacts`, Linux checks, docs checks, Python skills, `android` |
+| `blacksmith-32vcpu-windows-2025` | `checks-windows`                                                                                     |
+| `macos-latest`                   | `macos-node`, `macos-swift`                                                                          |
+
+## Local Equivalents
+
+```bash
+pnpm check          # types + lint + format
+pnpm build:strict-smoke
+pnpm test:gateway:watch-regression
+pnpm test           # vitest tests
+pnpm test:channels
+pnpm check:docs     # docs format + lint + broken links
+pnpm build          # build dist when CI artifact/build-smoke lanes matter
+```