nodmix 2026.5.25

package/docs/concepts/personal-agent-benchmark-pack.md

@@ -0,0 +1,74 @@
+---
+summary: "Local qa-channel scenarios for privacy-preserving personal assistant workflow checks."
+read_when:
+  - Running local personal agent reliability checks
+  - Extending the repo-backed QA scenario catalog
+  - Verifying reminder, reply, memory, redaction, safe tool followthrough, task status, share-safe diagnostics, proof-backed completion claims, and failure recovery
+title: "Personal agent benchmark pack"
+---
+
+The Personal Agent Benchmark Pack is a small repo-backed QA scenario pack for
+local personal assistant workflows. It is not a generic model benchmark and it
+does not require a new runner. The pack reuses the private QA stack described in
+[QA overview](/concepts/qa-e2e-automation), the synthetic
+[QA channel](/channels/qa-channel), and the existing `qa/scenarios` markdown
+catalog.
+
+The first pack is intentionally narrow:
+
+- fake personal reminders through local cron delivery
+- fake DM and thread reply routing through `qa-channel`
+- fake preference recall from the temporary QA workspace memory files
+- fake secret no-echo checks
+- safe read-backed tool followthrough after a short approval-style turn
+- approval denial stop behavior for a sensitive local read request
+- proof-backed task status reporting that keeps pending, blocked, and done separate
+- share-safe diagnostics artifacts that keep useful status while omitting raw personal content
+- proof-backed completion claims that avoid fake progress before local evidence exists
+- failure recovery that reports partial status and keeps retry boundaries clear
+
+## Scenarios
+
+The machine-readable pack metadata lives in
+`extensions/qa-lab/src/scenario-packs.ts`. Run the pack with
+`--pack personal-agent`:
+
+```bash
+NODMIX_ENABLE_PRIVATE_QA_CLI=1 pnpm nodmix qa suite \
+  --provider-mode mock-openai \
+  --pack personal-agent \
+  --concurrency 1
+```
+
+`--pack` is additive with repeated `--scenario` flags. Explicit scenarios run
+first, then the pack scenarios run in `QA_PERSONAL_AGENT_SCENARIO_IDS` order with
+duplicates removed.
+
+The pack is designed for `qa-channel` with `mock-openai` or another local QA
+provider lane. It should not be pointed at live chat services or real personal
+accounts.
+
+## Privacy Model
+
+The scenarios use only fake users, fake preferences, fake secrets, and the
+temporary QA gateway workspace created by the suite. They must not read or write
+real Nodmix user memory, sessions, credentials, launch agents, global configs,
+or live gateway state.
+
+Artifacts stay under the existing QA suite artifact directory and should be
+treated like test output. Redaction checks use fake markers so failures are safe
+to inspect and file in issues.
+
+## Extending The Pack
+
+Add new cases under `qa/scenarios/personal/`, then add the scenario id to
+`QA_PERSONAL_AGENT_SCENARIO_IDS`. Keep each case small, local, deterministic in
+`mock-openai`, and focused on one personal assistant behavior.
+
+Good follow-up candidates:
+
+- redacted trajectory export checks
+- local-only plugin workflow checks
+
+Avoid adding a new runner, plugin, dependency, live transport, or model judge
+until the scenario catalog has enough stable cases to justify that surface.

package/docs/concepts/presence.md

@@ -0,0 +1,117 @@
+---
+summary: "How Nodmix presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+title: "Presence"
+---
+
+Nodmix "presence" is a lightweight, best-effort view of:
+
+- the **Gateway** itself, and
+- **clients connected to the Gateway** (mac app, WebChat, CLI, etc.)
+
+Presence is used primarily to render the macOS app's **Instances** tab and to
+provide quick operator visibility.
+
+## Presence fields (what shows up)
+
+Presence entries are structured objects with fields like:
+
+- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
+- `host`: human-friendly host name
+- `ip`: best-effort IP address
+- `version`: client version string
+- `deviceFamily` / `modelIdentifier`: hardware hints
+- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
+- `lastInputSeconds`: "seconds since last user input" (if known)
+- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and **merged**.
+
+### 1) Gateway self entry
+
+The Gateway always seeds a "self" entry at startup so UIs show the gateway host
+even before any clients connect.
+
+### 2) WebSocket connect
+
+Every WS client begins with a `connect` request. On successful handshake the
+Gateway upserts a presence entry for that connection.
+
+#### Why one-off CLI commands do not show up
+
+The CLI often connects for short, one-off commands. To avoid spamming the
+Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
+
+### 3) `system-event` beacons
+
+Clients can send richer periodic beacons via the `system-event` method. The mac
+app uses this to report host name, IP, and `lastInputSeconds`.
+
+### 4) Node connects (role: node)
+
+When a node connects over the Gateway WebSocket with `role: node`, the Gateway
+upserts a presence entry for that node (same flow as other WS clients).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+Presence entries are stored in a single in-memory map:
+
+- Entries are keyed by a **presence key**.
+- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
+- Keys are case-insensitive.
+
+If a client reconnects without a stable `instanceId`, it may show up as a
+**duplicate** row.
+
+## TTL and bounded size
+
+Presence is intentionally ephemeral:
+
+- **TTL:** entries older than 5 minutes are pruned
+- **Max entries:** 200 (oldest dropped first)
+
+This keeps the list fresh and avoids unbounded memory growth.
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may
+see the remote address as `127.0.0.1`. To avoid overwriting a good client-reported
+IP, loopback remote addresses are ignored.
+
+## Consumers
+
+### macOS Instances tab
+
+The macOS app renders the output of `system-presence` and applies a small status
+indicator (Active/Idle/Stale) based on the age of the last update.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the Gateway.
+- If you see duplicates:
+  - confirm clients send a stable `client.instanceId` in the handshake
+  - confirm periodic beacons use the same `instanceId`
+  - check whether the connection-derived entry is missing `instanceId` (duplicates are expected)
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Typing indicators" href="/concepts/typing-indicators" icon="ellipsis">
+    When typing indicators are sent and how to tune them.
+  </Card>
+  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
+    Outbound streaming, chunking, and per-channel formatting.
+  </Card>
+  <Card title="Gateway architecture" href="/concepts/architecture" icon="diagram-project">
+    Gateway components and the WebSocket protocol that drives presence updates.
+  </Card>
+  <Card title="Gateway protocol" href="/gateway/protocol" icon="plug">
+    The wire protocol for `connect`, `system-event`, and `system-presence`.
+  </Card>
+</CardGroup>

package/docs/concepts/progress-drafts.md

@@ -0,0 +1,362 @@
+---
+summary: "Progress drafts: one visible work-in-progress message that updates while an agent runs"
+read_when:
+  - Configuring visible progress updates for long-running chat turns
+  - Choosing between partial, block, and progress streaming modes
+  - Explaining how Nodmix updates one channel message while work is in progress
+  - Troubleshooting progress drafts, standalone progress messages, or finalization fallback
+title: "Progress drafts"
+---
+
+Progress drafts make long-running agent turns feel alive in chat without turning
+the conversation into a stack of temporary status replies.
+
+When progress drafts are enabled, Nodmix creates one visible work-in-progress
+message only after the turn proves it is doing real work, updates it while the
+agent reads, plans, calls tools, or waits for approval, and then turns that draft
+into the final answer when the channel can do that safely.
+
+```text
+Shelling...
+📖 from docs/concepts/progress-drafts.md
+🔎 Web Search: for "discord edit message"
+🛠️ Bash: run tests
+```
+
+Use progress drafts when you want one tidy status message during tool-heavy work
+and the final answer when the turn is done.
+
+## Quick start
+
+Enable progress drafts per channel with `streaming.mode: "progress"`:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+      },
+    },
+  },
+}
+```
+
+That is usually enough. Nodmix will pick an automatic one-word label, wait
+until work lasts at least five seconds or emits a second work event, add compact
+progress lines while useful work happens, and suppress duplicate standalone
+progress chatter for that turn.
+
+## What users see
+
+A progress draft has two parts:
+
+| Part           | Purpose                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| Label          | A short starter/status line such as `Working` or `Shelling`.                          |
+| Progress lines | Compact run updates using the same tool icons and detail formatter as verbose output. |
+
+The label appears after the agent starts meaningful work and either remains busy
+for five seconds or emits a second work event. It is part of the rolling progress
+line list, so the starter status scrolls away once enough concrete work appears.
+Plain text-only replies do not show a progress draft. Progress lines are added
+only when the agent emits useful work updates, for example `🛠️ Bash: run tests`,
+`🔎 Web Search: for "discord edit message"`, or `✍️ Write: to /tmp/file`.
+By default they use the same compact explain mode as `/verbose`; set
+`agents.defaults.toolProgressDetail: "raw"` when debugging and you also want raw
+commands/details appended.
+The final answer replaces the draft when possible; otherwise
+Nodmix sends the final answer normally and cleans up or stops updating the
+draft according to the channel's transport.
+
+## Choose a mode
+
+`channels.<channel>.streaming.mode` controls the visible in-progress behavior:
+
+| Mode       | Best for                         | What appears in chat                              |
+| ---------- | -------------------------------- | ------------------------------------------------- |
+| `off`      | Quiet channels                   | Only the final answer.                            |
+| `partial`  | Watching answer text appear      | One draft edited with the latest answer text.     |
+| `block`    | Larger answer-preview chunks     | One preview updated or appended in bigger chunks. |
+| `progress` | Tool-heavy or long-running turns | One status draft, then the final answer.          |
+
+Choose `progress` when users care more about "what is happening" than watching
+the answer text stream token by token.
+
+Choose `partial` when the answer itself is the progress signal.
+
+Choose `block` when you want draft preview updates in larger text chunks. On
+Discord and Telegram, `streaming.mode: "block"` is still preview streaming, not
+normal block delivery. Use `streaming.block.enabled` or legacy
+`blockStreaming` when you want normal block replies.
+
+## Configure labels
+
+Progress labels live under `channels.<channel>.streaming.progress`.
+
+The default label is `auto`, which chooses from Nodmix's built-in
+single-word label pool:
+
+```text
+Working
+Shelling
+Scuttling
+Clawing
+Pinching
+Molting
+Bubbling
+Tiding
+Reefing
+Cracking
+Sifting
+Brining
+Nautiling
+Krilling
+Barnacling
+Lobstering
+Tidepooling
+Pearling
+Snapping
+Surfacing
+```
+
+Use a fixed label:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: "Investigating",
+        },
+      },
+    },
+  },
+}
+```
+
+Use your own automatic label pool:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: "auto",
+          labels: ["Checking", "Reading", "Testing", "Finishing"],
+        },
+      },
+    },
+  },
+}
+```
+
+Hide the label and show only progress lines:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          label: false,
+        },
+      },
+    },
+  },
+}
+```
+
+## Control progress lines
+
+Progress lines are enabled by default in progress mode. They come from real run
+events: tool starts, item updates, task plans, approvals, command output, patch
+summaries, and similar agent activity.
+
+Nodmix uses the same formatter for progress drafts and `/verbose`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      toolProgressDetail: "explain", // explain | raw
+    },
+  },
+}
+```
+
+`"explain"` is the default and keeps drafts stable with concise labels like
+`🛠️ check JS syntax for /tmp/app.js`. `"raw"` appends the underlying
+command/detail when available, which is useful while debugging but noisier in
+chat.
+
+For example, the same command appears differently depending on the detail mode:
+
+| Mode      | Progress line                                                  |
+| --------- | -------------------------------------------------------------- |
+| `explain` | `🛠️ check JS syntax for /tmp/app.js`                           |
+| `raw`     | `🛠️ check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
+
+Limit how many lines stay visible:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          maxLines: 4,
+        },
+      },
+    },
+  },
+}
+```
+
+Progress lines are compacted automatically to reduce chat-bubble reflow while the draft is edited.
+
+Nodmix truncates long progress lines by default so repeated draft edits do not
+wrap differently on every update. The default per-line budget is 120 characters.
+Prose cuts at a word boundary, while long details such as paths or raw commands
+are shortened with a middle ellipsis so the suffix remains visible.
+
+Tune the per-line budget:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          maxLineChars: 160,
+        },
+      },
+    },
+  },
+}
+```
+
+Slack can render progress lines as structured Block Kit fields instead of a
+single text body:
+
+```json5
+{
+  channels: {
+    slack: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          render: "rich",
+        },
+      },
+    },
+  },
+}
+```
+
+Rich rendering keeps the same plain-text fallback so channels and clients that
+do not support the richer shape can still show the compact progress text.
+
+Keep the single progress draft but hide tool and task lines:
+
+```json5
+{
+  channels: {
+    discord: {
+      streaming: {
+        mode: "progress",
+        progress: {
+          toolProgress: false,
+        },
+      },
+    },
+  },
+}
+```
+
+With `toolProgress: false`, Nodmix still suppresses the older standalone
+tool-progress messages for that turn. The channel stays visually quiet until the
+final answer, except for the label if one is configured.
+
+## Channel behavior
+
+Each channel uses the cleanest transport it supports:
+
+| Channel         | Progress transport                     | Notes                                                                 |
+| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
+| Discord         | Send one message, then edit it.        | Final text edits in place when it fits one safe preview message.      |
+| Matrix          | Send one event, then edit it.          | Account-level streaming config controls account-level drafts.         |
+| Microsoft Teams | Native Teams stream in personal chats. | `streaming.mode: "block"` maps to Teams block delivery.               |
+| Slack           | Native stream or editable draft post.  | Thread availability affects whether native streaming can be used.     |
+| Telegram        | Send one message, then edit it.        | Older visible drafts may be replaced so final timestamps stay useful. |
+| Mattermost      | Editable draft post.                   | Tool activity is folded into the same draft-style post.               |
+
+Channels without safe edit support usually fall back to typing indicators or
+final-only delivery.
+
+## Finalization
+
+When the final answer is ready, Nodmix tries to keep the chat clean:
+
+- If the draft can safely become the final answer, Nodmix edits it in place.
+- If the channel uses native progress streaming, Nodmix finalizes that stream
+  when the native transport accepts the final text.
+- If the final answer has media, an approval prompt, an explicit reply target,
+  too many chunks, or a failed edit/send, Nodmix sends the final answer through
+  the normal channel delivery path.
+
+The fallback path is intentional. It is better to send a fresh final answer than
+to lose text, mis-thread a reply, or overwrite a draft with a payload the channel
+cannot represent safely.
+
+## Troubleshooting
+
+**I only see the final answer.**
+
+Check that `channels.<channel>.streaming.mode` is set to `progress` for the
+account or channel that handled the message. Some group or quote-reply paths may
+disable draft previews for a turn when the channel cannot safely edit the right
+message.
+
+**I see the label but no tool lines.**
+
+Check `streaming.progress.toolProgress`. If it is `false`, Nodmix keeps the
+single draft behavior but hides tool and task progress lines.
+
+**I see a fresh final message instead of an edited draft.**
+
+That is a safety fallback. It can happen for media replies, long answers,
+explicit reply targets, old Telegram drafts, missing Slack thread targets,
+deleted preview messages, or failed native stream finalization.
+
+**I still see standalone progress messages.**
+
+Progress mode suppresses default standalone tool-progress messages when a draft
+is active. If standalone messages still appear, verify that the turn is actually
+using progress mode and not `streaming.mode: "off"` or a channel path that
+cannot create a draft for that message.
+
+**Teams behaves differently from Discord or Telegram.**
+
+Microsoft Teams uses a native stream in personal chats instead of the generic
+send-and-edit preview transport. Teams also treats `streaming.mode: "block"` as
+Teams block delivery because it does not have the same draft-preview block mode
+used by Discord and Telegram.
+
+## Related
+
+- [Streaming and chunking](/concepts/streaming)
+- [Messages](/concepts/messages)
+- [Channel configuration](/gateway/config-channels)
+- [Discord](/channels/discord)
+- [Matrix](/channels/matrix)
+- [Microsoft Teams](/channels/msteams)
+- [Slack](/channels/slack)
+- [Telegram](/channels/telegram)