durar-ai 2026.4.4

package/docs/concepts/session-tool.md

@@ -0,0 +1,141 @@
+---
+summary: "Agent tools for cross-session status, recall, messaging, and sub-agent orchestration"
+read_when:
+  - You want to understand what session tools the agent has
+  - You want to configure cross-session access or sub-agent spawning
+  - You want to inspect status or control spawned sub-agents
+title: "Session Tools"
+---
+
+# Session Tools
+
+Durar gives agents tools to work across sessions, inspect status, and
+orchestrate sub-agents.
+
+## Available tools
+
+| Tool               | What it does                                                                |
+| ------------------ | --------------------------------------------------------------------------- |
+| `sessions_list`    | List sessions with optional filters (kind, recency)                         |
+| `sessions_history` | Read the transcript of a specific session                                   |
+| `sessions_send`    | Send a message to another session and optionally wait                       |
+| `sessions_spawn`   | Spawn an isolated sub-agent session for background work                     |
+| `sessions_yield`   | End the current turn and wait for follow-up sub-agent results               |
+| `subagents`        | List, steer, or kill spawned sub-agents for this session                    |
+| `session_status`   | Show a `/status`-style card and optionally set a per-session model override |
+
+## Listing and reading sessions
+
+`sessions_list` returns sessions with their key, kind, channel, model, token
+counts, and timestamps. Filter by kind (`main`, `group`, `cron`, `hook`,
+`node`) or recency (`activeMinutes`).
+
+`sessions_history` fetches the conversation transcript for a specific session.
+By default, tool results are excluded -- pass `includeTools: true` to see them.
+The returned view is intentionally bounded and safety-filtered:
+
+- assistant text is normalized before recall:
+  - thinking tags are stripped
+  - `<relevant-memories>` / `<relevant_memories>` scaffolding blocks are stripped
+  - plain-text tool-call XML payload blocks such as `<tool_call>...</tool_call>`,
+    `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, and
+    `<function_calls>...</function_calls>` are stripped, including truncated
+    payloads that never close cleanly
+  - downgraded tool-call/result scaffolding such as `[Tool Call: ...]`,
+    `[Tool Result ...]`, and `[Historical context ...]` is stripped
+  - leaked model control tokens such as `<|assistant|>`, other ASCII
+    `<|...|>` tokens, and full-width `<｜...｜>` variants are stripped
+  - malformed MiniMax tool-call XML such as `<invoke ...>` /
+    `</minimax:tool_call>` is stripped
+- credential/token-like text is redacted before it is returned
+- long text blocks are truncated
+- very large histories can drop older rows or replace an oversized row with
+  `[sessions_history omitted: message too large]`
+- the tool reports summary flags such as `truncated`, `droppedMessages`,
+  `contentTruncated`, `contentRedacted`, and `bytes`
+
+Both tools accept either a **session key** (like `"main"`) or a **session ID**
+from a previous list call.
+
+If you need the exact byte-for-byte transcript, inspect the transcript file on
+disk instead of treating `sessions_history` as a raw dump.
+
+## Sending cross-session messages
+
+`sessions_send` delivers a message to another session and optionally waits for
+the response:
+
+- **Fire-and-forget:** set `timeoutSeconds: 0` to enqueue and return
+  immediately.
+- **Wait for reply:** set a timeout and get the response inline.
+
+After the target responds, Durar can run a **reply-back loop** where the
+agents alternate messages (up to 5 turns). The target agent can reply
+`REPLY_SKIP` to stop early.
+
+## Status and orchestration helpers
+
+`session_status` is the lightweight `/status`-equivalent tool for the current
+or another visible session. It reports usage, time, model/runtime state, and
+linked background-task context when present. Like `/status`, it can backfill
+sparse token/cache counters from the latest transcript usage entry, and
+`model=default` clears a per-session override.
+
+`sessions_yield` intentionally ends the current turn so the next message can be
+the follow-up event you are waiting for. Use it after spawning sub-agents when
+you want completion results to arrive as the next message instead of building
+poll loops.
+
+`subagents` is the control-plane helper for already spawned Durar
+sub-agents. It supports:
+
+- `action: "list"` to inspect active/recent runs
+- `action: "steer"` to send follow-up guidance to a running child
+- `action: "kill"` to stop one child or `all`
+
+## Spawning sub-agents
+
+`sessions_spawn` creates an isolated session for a background task. It is always
+non-blocking -- it returns immediately with a `runId` and `childSessionKey`.
+
+Key options:
+
+- `runtime: "subagent"` (default) or `"acp"` for external harness agents.
+- `model` and `thinking` overrides for the child session.
+- `thread: true` to bind the spawn to a chat thread (Discord, Slack, etc.).
+- `sandbox: "require"` to enforce sandboxing on the child.
+
+Default leaf sub-agents do not get session tools. When
+`maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive
+`sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they
+can manage their own children. Leaf runs still do not get recursive
+orchestration tools.
+
+After completion, an announce step posts the result to the requester's channel.
+Completion delivery preserves bound thread/topic routing when available, and if
+the completion origin only identifies a channel Durar can still reuse the
+requester session's stored route (`lastChannel` / `lastTo`) for direct
+delivery.
+
+For ACP-specific behavior, see [ACP Agents](/tools/acp-agents).
+
+## Visibility
+
+Session tools are scoped to limit what the agent can see:
+
+| Level   | Scope                                    |
+| ------- | ---------------------------------------- |
+| `self`  | Only the current session                 |
+| `tree`  | Current session + spawned sub-agents     |
+| `agent` | All sessions for this agent              |
+| `all`   | All sessions (cross-agent if configured) |
+
+Default is `tree`. Sandboxed sessions are clamped to `tree` regardless of
+config.
+
+## Further reading
+
+- [Session Management](/concepts/session) -- routing, lifecycle, maintenance
+- [ACP Agents](/tools/acp-agents) -- external harness spawning
+- [Multi-agent](/concepts/multi-agent) -- multi-agent architecture
+- [Gateway Configuration](/gateway/configuration) -- session tool config knobs

package/docs/concepts/session.md

@@ -0,0 +1,116 @@
+---
+summary: "How Durar manages conversation sessions"
+read_when:
+  - You want to understand session routing and isolation
+  - You want to configure DM scope for multi-user setups
+title: "Session Management"
+---
+
+# Session Management
+
+Durar organizes conversations into **sessions**. Each message is routed to a
+session based on where it came from -- DMs, group chats, cron jobs, etc.
+
+## How messages are routed
+
+| Source          | Behavior                  |
+| --------------- | ------------------------- |
+| Direct messages | Shared session by default |
+| Group chats     | Isolated per group        |
+| Rooms/channels  | Isolated per room         |
+| Cron jobs       | Fresh session per run     |
+| Webhooks        | Isolated per hook         |
+
+## DM isolation
+
+By default, all DMs share one session for continuity. This is fine for
+single-user setups.
+
+<Warning>
+If multiple people can message your agent, enable DM isolation. Without it, all
+users share the same conversation context -- Alice's private messages would be
+visible to Bob.
+</Warning>
+
+**The fix:**
+
+```json5
+{
+  session: {
+    dmScope: "per-channel-peer", // isolate by channel + sender
+  },
+}
+```
+
+Other options:
+
+- `main` (default) -- all DMs share one session.
+- `per-peer` -- isolate by sender (across channels).
+- `per-channel-peer` -- isolate by channel + sender (recommended).
+- `per-account-channel-peer` -- isolate by account + channel + sender.
+
+<Tip>
+If the same person contacts you from multiple channels, use
+`session.identityLinks` to link their identities so they share one session.
+</Tip>
+
+Verify your setup with `Durar security audit`.
+
+## Session lifecycle
+
+Sessions are reused until they expire:
+
+- **Daily reset** (default) -- new session at 4:00 AM local time on the gateway
+  host.
+- **Idle reset** (optional) -- new session after a period of inactivity. Set
+  `session.reset.idleMinutes`.
+- **Manual reset** -- type `/new` or `/reset` in chat. `/new <model>` also
+  switches the model.
+
+When both daily and idle resets are configured, whichever expires first wins.
+
+## Where state lives
+
+All session state is owned by the **gateway**. UI clients query the gateway for
+session data.
+
+- **Store:** `~/.Durar/agents/<agentId>/sessions/sessions.json`
+- **Transcripts:** `~/.Durar/agents/<agentId>/sessions/<sessionId>.jsonl`
+
+## Session maintenance
+
+Durar automatically bounds session storage over time. By default, it runs
+in `warn` mode (reports what would be cleaned). Set `session.maintenance.mode`
+to `"enforce"` for automatic cleanup:
+
+```json5
+{
+  session: {
+    maintenance: {
+      mode: "enforce",
+      pruneAfter: "30d",
+      maxEntries: 500,
+    },
+  },
+}
+```
+
+Preview with `Durar sessions cleanup --dry-run`.
+
+## Inspecting sessions
+
+- `Durar status` -- session store path and recent activity.
+- `Durar sessions --json` -- all sessions (filter with `--active <minutes>`).
+- `/status` in chat -- context usage, model, and toggles.
+- `/context list` -- what is in the system prompt.
+
+## Further reading
+
+- [Session Pruning](/concepts/session-pruning) -- trimming tool results
+- [Compaction](/concepts/compaction) -- summarizing long conversations
+- [Session Tools](/concepts/session-tool) -- agent tools for cross-session work
+- [Session Management Deep Dive](/reference/session-management-compaction) --
+  store schema, transcripts, send policy, origin metadata, and advanced config
+- [Multi-Agent](/concepts/multi-agent) — routing and session isolation across agents
+- [Background Tasks](/automation/tasks) — how detached work creates task records with session references
+- [Channel Routing](/channels/channel-routing) — how inbound messages are routed to sessions

package/docs/concepts/soul.md

@@ -0,0 +1,110 @@
+---
+summary: "Use SOUL.md to give your Durar agent an actual voice instead of generic assistant sludge"
+read_when:
+  - You want your agent to sound less generic
+  - You are editing SOUL.md
+  - You want a stronger personality without breaking safety or brevity
+title: "SOUL.md Personality Guide"
+---
+
+# SOUL.md Personality Guide
+
+`SOUL.md` is where your agent's voice lives.
+
+Durar injects it on normal sessions, so it has real weight. If your agent
+sounds bland, hedgy, or weirdly corporate, this is usually the file to fix.
+
+## What belongs in SOUL.md
+
+Put the stuff that changes how the agent feels to talk to:
+
+- tone
+- opinions
+- brevity
+- humor
+- boundaries
+- default level of bluntness
+
+Do **not** turn it into:
+
+- a life story
+- a changelog
+- a security policy dump
+- a giant wall of vibes with no behavioral effect
+
+Short beats long. Sharp beats vague.
+
+## Why this works
+
+This lines up with OpenAI's prompt guidance:
+
+- The prompt engineering guide says high-level behavior, tone, goals, and
+  examples belong in the high-priority instruction layer, not buried in the
+  user turn.
+- The same guide recommends treating prompts like something you iterate on,
+  pin, and evaluate, not magical prose you write once and forget.
+
+For Durar, `SOUL.md` is that layer.
+
+If you want better personality, write stronger instructions. If you want stable
+personality, keep them concise and versioned.
+
+OpenAI refs:
+
+- [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)
+- [Message roles and instruction following](https://developers.openai.com/api/docs/guides/prompt-engineering#message-roles-and-instruction-following)
+
+## The Molty prompt
+
+Paste this into your agent and let it rewrite `SOUL.md`.
+
+Path fixed for Durar workspaces: use `SOUL.md`, not `http://SOUL.md`.
+
+```md
+Read your `SOUL.md`. Now rewrite it with these changes:
+
+1. You have opinions now. Strong ones. Stop hedging everything with "it depends" - commit to a take.
+2. Delete every rule that sounds corporate. If it could appear in an employee handbook, it doesn't belong here.
+3. Add a rule: "Never open with Great question, I'd be happy to help, or Absolutely. Just answer."
+4. Brevity is mandatory. If the answer fits in one sentence, one sentence is what I get.
+5. Humor is allowed. Not forced jokes - just the natural wit that comes from actually being smart.
+6. You can call things out. If I'm about to do something dumb, say so. Charm over cruelty, but don't sugarcoat.
+7. Swearing is allowed when it lands. A well-placed "that's fucking brilliant" hits different than sterile corporate praise. Don't force it. Don't overdo it. But if a situation calls for a "holy shit" - say holy shit.
+8. Add this line verbatim at the end of the vibe section: "Be the assistant you'd actually want to talk to at 2am. Not a corporate drone. Not a sycophant. Just... good."
+
+Save the new `SOUL.md`. Welcome to having a personality.
+```
+
+## What good looks like
+
+Good `SOUL.md` rules sound like this:
+
+- have a take
+- skip filler
+- be funny when it fits
+- call out bad ideas early
+- stay concise unless depth is actually useful
+
+Bad `SOUL.md` rules sound like this:
+
+- maintain professionalism at all times
+- provide comprehensive and thoughtful assistance
+- ensure a positive and supportive experience
+
+That second list is how you get mush.
+
+## One warning
+
+Personality is not permission to be sloppy.
+
+Keep `AGENTS.md` for operating rules. Keep `SOUL.md` for voice, stance, and
+style. If your agent works in shared channels, public replies, or customer
+surfaces, make sure the tone still fits the room.
+
+Sharp is good. Annoying is not.
+
+## Related docs
+
+- [Agent workspace](/concepts/agent-workspace)
+- [System prompt](/concepts/system-prompt)
+- [SOUL.md template](/reference/templates/SOUL)

package/docs/concepts/streaming.md

@@ -0,0 +1,161 @@
+---
+summary: "Streaming + chunking behavior (block replies, channel preview streaming, mode mapping)"
+read_when:
+  - Explaining how streaming or chunking works on channels
+  - Changing block streaming or channel chunking behavior
+  - Debugging duplicate/early block replies or channel preview streaming
+title: "Streaming and Chunking"
+---
+
+# Streaming + chunking
+
+Durar has two separate streaming layers:
+
+- **Block streaming (channels):** emit completed **blocks** as the assistant writes. These are normal channel messages (not token deltas).
+- **Preview streaming (Telegram/Discord/Slack):** update a temporary **preview message** while generating.
+
+There is **no true token-delta streaming** to channel messages today. Preview streaming is message-based (send + edits/appends).
+
+## Block streaming (channel messages)
+
+Block streaming sends assistant output in coarse chunks as it becomes available.
+
+```
+Model output
+  └─ text_delta/events
+       ├─ (blockStreamingBreak=text_end)
+       │    └─ chunker emits blocks as buffer grows
+       └─ (blockStreamingBreak=message_end)
+            └─ chunker flushes at message_end
+                   └─ channel send (block replies)
+```
+
+Legend:
+
+- `text_delta/events`: model stream events (may be sparse for non-streaming models).
+- `chunker`: `EmbeddedBlockChunker` applying min/max bounds + break preference.
+- `channel send`: actual outbound messages (block replies).
+
+**Controls:**
+
+- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (default off).
+- Channel overrides: `*.blockStreaming` (and per-account variants) to force `"on"`/`"off"` per channel.
+- `agents.defaults.blockStreamingBreak`: `"text_end"` or `"message_end"`.
+- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
+- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send).
+- Channel hard cap: `*.textChunkLimit` (e.g., `channels.whatsapp.textChunkLimit`).
+- Channel chunk mode: `*.chunkMode` (`length` default, `newline` splits on blank lines (paragraph boundaries) before length chunking).
+- Discord soft cap: `channels.discord.maxLinesPerMessage` (default 17) splits tall replies to avoid UI clipping.
+
+**Boundary semantics:**
+
+- `text_end`: stream blocks as soon as chunker emits; flush on each `text_end`.
+- `message_end`: wait until assistant message finishes, then flush buffered output.
+
+`message_end` still uses the chunker if the buffered text exceeds `maxChars`, so it can emit multiple chunks at the end.
+
+## Chunking algorithm (low/high bounds)
+
+Block chunking is implemented by `EmbeddedBlockChunker`:
+
+- **Low bound:** don’t emit until buffer >= `minChars` (unless forced).
+- **High bound:** prefer splits before `maxChars`; if forced, split at `maxChars`.
+- **Break preference:** `paragraph` → `newline` → `sentence` → `whitespace` → hard break.
+- **Code fences:** never split inside fences; when forced at `maxChars`, close + reopen the fence to keep Markdown valid.
+
+`maxChars` is clamped to the channel `textChunkLimit`, so you can’t exceed per-channel caps.
+
+## Coalescing (merge streamed blocks)
+
+When block streaming is enabled, Durar can **merge consecutive block chunks**
+before sending them out. This reduces “single-line spam” while still providing
+progressive output.
+
+- Coalescing waits for **idle gaps** (`idleMs`) before flushing.
+- Buffers are capped by `maxChars` and will flush if they exceed it.
+- `minChars` prevents tiny fragments from sending until enough text accumulates
+  (final flush always sends remaining text).
+- Joiner is derived from `blockStreamingChunk.breakPreference`
+  (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → space).
+- Channel overrides are available via `*.blockStreamingCoalesce` (including per-account configs).
+- Default coalesce `minChars` is bumped to 1500 for Signal/Slack/Discord unless overridden.
+
+## Human-like pacing between blocks
+
+When block streaming is enabled, you can add a **randomized pause** between
+block replies (after the first block). This makes multi-bubble responses feel
+more natural.
+
+- Config: `agents.defaults.humanDelay` (override per agent via `agents.list[].humanDelay`).
+- Modes: `off` (default), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).
+- Applies only to **block replies**, not final replies or tool summaries.
+
+## "Stream chunks or everything"
+
+This maps to:
+
+- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emit as you go). Non-Telegram channels also need `*.blockStreaming: true`.
+- **Stream everything at end:** `blockStreamingBreak: "message_end"` (flush once, possibly multiple chunks if very long).
+- **No block streaming:** `blockStreamingDefault: "off"` (only final reply).
+
+**Channel note:** Block streaming is **off unless**
+`*.blockStreaming` is explicitly set to `true`. Channels can stream a live preview
+(`channels.<channel>.streaming`) without block replies.
+
+Config location reminder: the `blockStreaming*` defaults live under
+`agents.defaults`, not the root config.
+
+## Preview streaming modes
+
+Canonical key: `channels.<channel>.streaming`
+
+Modes:
+
+- `off`: disable preview streaming.
+- `partial`: single preview that is replaced with latest text.
+- `block`: preview updates in chunked/appended steps.
+- `progress`: progress/status preview during generation, final answer at completion.
+
+### Channel mapping
+
+| Channel  | `off` | `partial` | `block` | `progress`        |
+| -------- | ----- | --------- | ------- | ----------------- |
+| Telegram | ✅    | ✅        | ✅      | maps to `partial` |
+| Discord  | ✅    | ✅        | ✅      | maps to `partial` |
+| Slack    | ✅    | ✅        | ✅      | ✅                |
+
+Slack-only:
+
+- `channels.slack.nativeStreaming` toggles Slack native streaming API calls when `streaming=partial` (default: `true`).
+
+Legacy key migration:
+
+- Telegram: `streamMode` + boolean `streaming` auto-migrate to `streaming` enum.
+- Discord: `streamMode` + boolean `streaming` auto-migrate to `streaming` enum.
+- Slack: `streamMode` auto-migrates to `streaming` enum; boolean `streaming` auto-migrates to `nativeStreaming`.
+
+### Runtime behavior
+
+Telegram:
+
+- Uses `sendMessage` + `editMessageText` preview updates across DMs and group/topics.
+- Preview streaming is skipped when Telegram block streaming is explicitly enabled (to avoid double-streaming).
+- `/reasoning stream` can write reasoning to preview.
+
+Discord:
+
+- Uses send + edit preview messages.
+- `block` mode uses draft chunking (`draftChunk`).
+- Preview streaming is skipped when Discord block streaming is explicitly enabled.
+
+Slack:
+
+- `partial` can use Slack native streaming (`chat.startStream`/`append`/`stop`) when available.
+- `block` uses append-style draft previews.
+- `progress` uses status preview text, then final answer.
+
+## Related
+
+- [Messages](/concepts/messages) — message lifecycle and delivery
+- [Retry](/concepts/retry) — retry behavior on delivery failure
+- [Channels](/channels) — per-channel streaming support