durar-ai 2026.4.4

package/docs/tools/multi-agent-sandbox-tools.md

@@ -0,0 +1,373 @@
+---
+summary: “Per-agent sandbox + tool restrictions, precedence, and examples”
+title: Multi-Agent Sandbox & Tools
+read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.”
+status: active
+---
+
+# Multi-Agent Sandbox & Tools Configuration
+
+Each agent in a multi-agent setup can override the global sandbox and tool
+policy. This page covers per-agent configuration, precedence rules, and
+examples.
+
+- **Sandbox backends and modes**: see [Sandboxing](/gateway/sandboxing).
+- **Debugging blocked tools**: see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and `Durar sandbox explain`.
+- **Elevated exec**: see [Elevated Mode](/tools/elevated).
+
+Auth is per-agent: each agent reads from its own `agentDir` auth store at
+`~/.Durar/agents/<agentId>/agent/auth-profiles.json`.
+Credentials are **not** shared between agents. Never reuse `agentDir` across agents.
+If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`.
+
+---
+
+## Configuration Examples
+
+### Example 1: Personal + Restricted Family Agent
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "name": "Personal Assistant",
+        "workspace": "~/.Durar/workspace",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "family",
+        "name": "Family Bot",
+        "workspace": "~/.Durar/workspace-family",
+        "sandbox": {
+          "mode": "all",
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
+        }
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "family",
+      "match": {
+        "provider": "whatsapp",
+        "accountId": "*",
+        "peer": {
+          "kind": "group",
+          "id": "120363424282127706@g.us"
+        }
+      }
+    }
+  ]
+}
+```
+
+**Result:**
+
+- `main` agent: Runs on host, full tool access
+- `family` agent: Runs in Docker (one container per agent), only `read` tool
+
+---
+
+### Example 2: Work Agent with Shared Sandbox
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "personal",
+        "workspace": "~/.Durar/workspace-personal",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "work",
+        "workspace": "~/.Durar/workspace-work",
+        "sandbox": {
+          "mode": "all",
+          "scope": "shared",
+          "workspaceRoot": "/tmp/work-sandboxes"
+        },
+        "tools": {
+          "allow": ["read", "write", "apply_patch", "exec"],
+          "deny": ["browser", "gateway", "discord"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Example 2b: Global coding profile + messaging-only agent
+
+```json
+{
+  "tools": { "profile": "coding" },
+  "agents": {
+    "list": [
+      {
+        "id": "support",
+        "tools": { "profile": "messaging", "allow": ["slack"] }
+      }
+    ]
+  }
+}
+```
+
+**Result:**
+
+- default agents get coding tools
+- `support` agent is messaging-only (+ Slack tool)
+
+---
+
+### Example 3: Different Sandbox Modes per Agent
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "non-main", // Global default
+        "scope": "session"
+      }
+    },
+    "list": [
+      {
+        "id": "main",
+        "workspace": "~/.Durar/workspace",
+        "sandbox": {
+          "mode": "off" // Override: main never sandboxed
+        }
+      },
+      {
+        "id": "public",
+        "workspace": "~/.Durar/workspace-public",
+        "sandbox": {
+          "mode": "all", // Override: public always sandboxed
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Configuration Precedence
+
+When both global (`agents.defaults.*`) and agent-specific (`agents.list[].*`) configs exist:
+
+### Sandbox Config
+
+Agent-specific settings override global:
+
+```
+agents.list[].sandbox.mode > agents.defaults.sandbox.mode
+agents.list[].sandbox.scope > agents.defaults.sandbox.scope
+agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
+agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
+agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
+agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
+agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
+```
+
+**Notes:**
+
+- `agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
+
+### Tool Restrictions
+
+The filtering order is:
+
+1. **Tool profile** (`tools.profile` or `agents.list[].tools.profile`)
+2. **Provider tool profile** (`tools.byProvider[provider].profile` or `agents.list[].tools.byProvider[provider].profile`)
+3. **Global tool policy** (`tools.allow` / `tools.deny`)
+4. **Provider tool policy** (`tools.byProvider[provider].allow/deny`)
+5. **Agent-specific tool policy** (`agents.list[].tools.allow/deny`)
+6. **Agent provider policy** (`agents.list[].tools.byProvider[provider].allow/deny`)
+7. **Sandbox tool policy** (`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`)
+8. **Subagent tool policy** (`tools.subagents.tools`, if applicable)
+
+Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
+If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
+If `agents.list[].tools.profile` is set, it overrides `tools.profile` for that agent.
+Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
+
+Tool policies support `group:*` shorthands that expand to multiple tools. See [Tool groups](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands) for the full list.
+
+Per-agent elevated overrides (`agents.list[].tools.elevated`) can further restrict elevated exec for specific agents. See [Elevated Mode](/tools/elevated) for details.
+
+---
+
+## Migration from Single Agent
+
+**Before (single agent):**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.Durar/workspace",
+      "sandbox": {
+        "mode": "non-main"
+      }
+    }
+  },
+  "tools": {
+    "sandbox": {
+      "tools": {
+        "allow": ["read", "write", "apply_patch", "exec"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+**After (multi-agent with different profiles):**
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "workspace": "~/.Durar/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    ]
+  }
+}
+```
+
+Legacy `agent.*` configs are migrated by `Durar doctor`; prefer `agents.defaults` + `agents.list` going forward.
+
+---
+
+## Tool Restriction Examples
+
+### Read-only Agent
+
+```json
+{
+  "tools": {
+    "allow": ["read"],
+    "deny": ["exec", "write", "edit", "apply_patch", "process"]
+  }
+}
+```
+
+### Safe Execution Agent (no file modifications)
+
+```json
+{
+  "tools": {
+    "allow": ["read", "exec", "process"],
+    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
+  }
+}
+```
+
+### Communication-only Agent
+
+```json
+{
+  "tools": {
+    "sessions": { "visibility": "tree" },
+    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
+    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
+  }
+}
+```
+
+`sessions_history` in this profile still returns a bounded, sanitized recall
+view rather than a raw transcript dump. Assistant recall strips thinking tags,
+`<relevant-memories>` scaffolding, plain-text tool-call XML payloads
+(including `<tool_call>...</tool_call>`,
+`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
+`<function_calls>...</function_calls>`, and truncated tool-call blocks),
+downgraded tool-call scaffolding, leaked ASCII/full-width model control
+tokens, and malformed MiniMax tool-call XML before redaction/truncation.
+
+---
+
+## Common Pitfall: "non-main"
+
+`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
+not the agent id. Group/channel sessions always get their own keys, so they
+are treated as non-main and will be sandboxed. If you want an agent to never
+sandbox, set `agents.list[].sandbox.mode: "off"`.
+
+---
+
+## Testing
+
+After configuring multi-agent sandbox and tools:
+
+1. **Check agent resolution:**
+
+   ```exec
+   Durar agents list --bindings
+   ```
+
+2. **Verify sandbox containers:**
+
+   ```exec
+   docker ps --filter "name=Durar-sbx-"
+   ```
+
+3. **Test tool restrictions:**
+   - Send a message requiring restricted tools
+   - Verify the agent cannot use denied tools
+
+4. **Monitor logs:**
+
+   ```exec
+   tail -f "${Durar_STATE_DIR:-$HOME/.Durar}/logs/gateway.log" | grep -E "routing|sandbox|tools"
+   ```
+
+---
+
+## Troubleshooting
+
+### Agent not sandboxed despite `mode: "all"`
+
+- Check if there's a global `agents.defaults.sandbox.mode` that overrides it
+- Agent-specific config takes precedence, so set `agents.list[].sandbox.mode: "all"`
+
+### Tools still available despite deny list
+
+- Check tool filtering order: global → agent → sandbox → subagent
+- Each level can only further restrict, not grant back
+- Verify with logs: `[tools] filtering tools for agent:${agentId}`
+
+### Container not isolated per agent
+
+- Set `scope: "agent"` in agent-specific sandbox config
+- Default is `"session"` which creates one container per session
+
+---
+
+## See also
+
+- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
+- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging "why is this blocked?"
+- [Elevated Mode](/tools/elevated)
+- [Multi-Agent Routing](/concepts/multi-agent)
+- [Sandbox Configuration](/gateway/configuration-reference#agentsdefaultssandbox)
+- [Session Management](/concepts/session)

package/docs/tools/ollama-search.md

@@ -0,0 +1,100 @@
+---
+summary: "Ollama Web Search via your configured Ollama host"
+read_when:
+  - You want to use Ollama for web_search
+  - You want a key-free web_search provider
+  - You need Ollama Web Search setup guidance
+title: "Ollama Web Search"
+---
+
+# Ollama Web Search
+
+Durar supports **Ollama Web Search** as a bundled `web_search` provider.
+It uses Ollama's experimental web-search API and returns structured results
+with titles, URLs, and snippets.
+
+Unlike the Ollama model provider, this setup does not need an API key by
+default. It does require:
+
+- an Ollama host that is reachable from Durar
+- `ollama signin`
+
+## Setup
+
+<Steps>
+  <Step title="Start Ollama">
+    Make sure Ollama is installed and running.
+  </Step>
+  <Step title="Sign in">
+    Run:
+
+    ```bash
+    ollama signin
+    ```
+
+  </Step>
+  <Step title="Choose Ollama Web Search">
+    Run:
+
+    ```bash
+    Durar configure --section web
+    ```
+
+    Then select **Ollama Web Search** as the provider.
+
+  </Step>
+</Steps>
+
+If you already use Ollama for models, Ollama Web Search reuses the same
+configured host.
+
+## Config
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "ollama",
+      },
+    },
+  },
+}
+```
+
+Optional Ollama host override:
+
+```json5
+{
+  models: {
+    providers: {
+      ollama: {
+        baseUrl: "http://ollama-host:11434",
+      },
+    },
+  },
+}
+```
+
+If no explicit Ollama base URL is set, Durar uses `http://127.0.0.1:11434`.
+
+If your Ollama host expects bearer auth, Durar reuses
+`models.providers.ollama.apiKey` (or the matching env-backed provider auth)
+for web-search requests too.
+
+## Notes
+
+- No web-search-specific API key field is required for this provider.
+- If the Ollama host is auth-protected, Durar reuses the normal Ollama
+  provider API key when present.
+- Durar warns during setup if Ollama is unreachable or not signed in, but
+  it does not block selection.
+- Runtime auto-detect can fall back to Ollama Web Search when no higher-priority
+  credentialed provider is configured.
+- The provider uses Ollama's experimental `/api/experimental/web_search`
+  endpoint.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Ollama](/providers/ollama) -- Ollama model setup and cloud/local modes

package/docs/tools/pdf.md

@@ -0,0 +1,176 @@
+---
+title: "PDF Tool"
+summary: "Analyze one or more PDF documents with native provider support and extraction fallback"
+read_when:
+  - You want to analyze PDFs from agents
+  - You need exact pdf tool parameters and limits
+  - You are debugging native PDF mode vs extraction fallback
+---
+
+# PDF tool
+
+`pdf` analyzes one or more PDF documents and returns text.
+
+Quick behavior:
+
+- Native provider mode for Anthropic and Google model providers.
+- Extraction fallback mode for other providers (extract text first, then page images when needed).
+- Supports single (`pdf`) or multi (`pdfs`) input, max 10 PDFs per call.
+
+## Availability
+
+The tool is only registered when Durar can resolve a PDF-capable model config for the agent:
+
+1. `agents.defaults.pdfModel`
+2. fallback to `agents.defaults.imageModel`
+3. fallback to the agent's resolved session/default model
+4. if native-PDF providers are auth-backed, prefer them ahead of generic image fallback candidates
+
+If no usable model can be resolved, the `pdf` tool is not exposed.
+
+Availability notes:
+
+- The fallback chain is auth-aware. A configured `provider/model` only counts if
+  Durar can actually authenticate that provider for the agent.
+- Native PDF providers are currently **Anthropic** and **Google**.
+- If the resolved session/default provider already has a configured vision/PDF
+  model, the PDF tool reuses that before falling back to other auth-backed
+  providers.
+
+## Input reference
+
+- `pdf` (`string`): one PDF path or URL
+- `pdfs` (`string[]`): multiple PDF paths or URLs, up to 10 total
+- `prompt` (`string`): analysis prompt, default `Analyze this PDF document.`
+- `pages` (`string`): page filter like `1-5` or `1,3,7-9`
+- `model` (`string`): optional model override (`provider/model`)
+- `maxBytesMb` (`number`): per-PDF size cap in MB
+
+Input notes:
+
+- `pdf` and `pdfs` are merged and deduplicated before loading.
+- If no PDF input is provided, the tool errors.
+- `pages` is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
+- `maxBytesMb` defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
+
+## Supported PDF references
+
+- local file path (including `~` expansion)
+- `file://` URL
+- `http://` and `https://` URL
+
+Reference notes:
+
+- Other URI schemes (for example `ftp://`) are rejected with `unsupported_pdf_reference`.
+- In sandbox mode, remote `http(s)` URLs are rejected.
+- With workspace-only file policy enabled, local file paths outside allowed roots are rejected.
+
+## Execution modes
+
+### Native provider mode
+
+Native mode is used for provider `anthropic` and `google`.
+The tool sends raw PDF bytes directly to provider APIs.
+
+Native mode limits:
+
+- `pages` is not supported. If set, the tool returns an error.
+- Multi-PDF input is supported; each PDF is sent as a native document block /
+  inline PDF part before the prompt.
+
+### Extraction fallback mode
+
+Fallback mode is used for non-native providers.
+
+Flow:
+
+1. Extract text from selected pages (up to `agents.defaults.pdfMaxPages`, default `20`).
+2. If extracted text length is below `200` chars, render selected pages to PNG images and include them.
+3. Send extracted content plus prompt to the selected model.
+
+Fallback details:
+
+- Page image extraction uses a pixel budget of `4,000,000`.
+- If the target model does not support image input and there is no extractable text, the tool errors.
+- If text extraction succeeds but image extraction would require vision on a
+  text-only model, Durar drops the rendered images and continues with the
+  extracted text.
+- Extraction fallback requires `pdfjs-dist` (and `@napi-rs/canvas` for image rendering).
+
+## Config
+
+```json5
+{
+  agents: {
+    defaults: {
+      pdfModel: {
+        primary: "anthropic/claude-opus-4-6",
+        fallbacks: ["openai/gpt-5.4-mini"],
+      },
+      pdfMaxBytesMb: 10,
+      pdfMaxPages: 20,
+    },
+  },
+}
+```
+
+See [Configuration Reference](/gateway/configuration-reference) for full field details.
+
+## Output details
+
+The tool returns text in `content[0].text` and structured metadata in `details`.
+
+Common `details` fields:
+
+- `model`: resolved model ref (`provider/model`)
+- `native`: `true` for native provider mode, `false` for fallback
+- `attempts`: fallback attempts that failed before success
+
+Path fields:
+
+- single PDF input: `details.pdf`
+- multiple PDF inputs: `details.pdfs[]` with `pdf` entries
+- sandbox path rewrite metadata (when applicable): `rewrittenFrom`
+
+## Error behavior
+
+- Missing PDF input: throws `pdf required: provide a path or URL to a PDF document`
+- Too many PDFs: returns structured error in `details.error = "too_many_pdfs"`
+- Unsupported reference scheme: returns `details.error = "unsupported_pdf_reference"`
+- Native mode with `pages`: throws clear `pages is not supported with native PDF providers` error
+
+## Examples
+
+Single PDF:
+
+```json
+{
+  "pdf": "/tmp/report.pdf",
+  "prompt": "Summarize this report in 5 bullets"
+}
+```
+
+Multiple PDFs:
+
+```json
+{
+  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
+  "prompt": "Compare risks and timeline changes across both documents"
+}
+```
+
+Page-filtered fallback model:
+
+```json
+{
+  "pdf": "https://example.com/report.pdf",
+  "pages": "1-3,7",
+  "model": "openai/gpt-5.4-mini",
+  "prompt": "Extract only customer-impacting incidents"
+}
+```
+
+## Related
+
+- [Tools Overview](/tools) — all available agent tools
+- [Configuration Reference](/gateway/configuration-reference#agent-defaults) — pdfMaxBytesMb and pdfMaxPages config