durar-ai 2026.4.4

package/docs/tools/image-generation.md

@@ -0,0 +1,139 @@
+---
+summary: "Generate and edit images using configured providers (OpenAI, Google Gemini, fal, MiniMax)"
+read_when:
+  - Generating images via the agent
+  - Configuring image generation providers and models
+  - Understanding the image_generate tool parameters
+title: "Image Generation"
+---
+
+# Image Generation
+
+The `image_generate` tool lets the agent create and edit images using your configured providers. Generated images are delivered automatically as media attachments in the agent's reply.
+
+<Note>
+The tool only appears when at least one image generation provider is available. If you don't see `image_generate` in your agent's tools, configure `agents.defaults.imageGenerationModel` or set up a provider API key.
+</Note>
+
+## Quick start
+
+1. Set an API key for at least one provider (for example `OPENAI_API_KEY` or `GEMINI_API_KEY`).
+2. Optionally set your preferred model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      imageGenerationModel: "openai/gpt-image-1",
+    },
+  },
+}
+```
+
+3. Ask the agent: _"Generate an image of a friendly lobster mascot."_
+
+The agent calls `image_generate` automatically. No tool allow-listing needed — it's enabled by default when a provider is available.
+
+## Supported providers
+
+| Provider | Default model                    | Edit support            | API key                                               |
+| -------- | -------------------------------- | ----------------------- | ----------------------------------------------------- |
+| OpenAI   | `gpt-image-1`                    | Yes (up to 5 images)    | `OPENAI_API_KEY`                                      |
+| Google   | `gemini-3.1-flash-image-preview` | Yes                     | `GEMINI_API_KEY` or `GOOGLE_API_KEY`                  |
+| fal      | `fal-ai/flux/dev`                | Yes                     | `FAL_KEY`                                             |
+| MiniMax  | `image-01`                       | Yes (subject reference) | `MINIMAX_API_KEY` or MiniMax OAuth (`minimax-portal`) |
+
+Use `action: "list"` to inspect available providers and models at runtime:
+
+```
+/tool image_generate action=list
+```
+
+## Tool parameters
+
+| Parameter     | Type     | Description                                                                           |
+| ------------- | -------- | ------------------------------------------------------------------------------------- |
+| `prompt`      | string   | Image generation prompt (required for `action: "generate"`)                           |
+| `action`      | string   | `"generate"` (default) or `"list"` to inspect providers                               |
+| `model`       | string   | Provider/model override, e.g. `openai/gpt-image-1`                                    |
+| `image`       | string   | Single reference image path or URL for edit mode                                      |
+| `images`      | string[] | Multiple reference images for edit mode (up to 5)                                     |
+| `size`        | string   | Size hint: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024`            |
+| `aspectRatio` | string   | Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
+| `resolution`  | string   | Resolution hint: `1K`, `2K`, or `4K`                                                  |
+| `count`       | number   | Number of images to generate (1–4)                                                    |
+| `filename`    | string   | Output filename hint                                                                  |
+
+Not all providers support all parameters. The tool passes what each provider supports and ignores the rest.
+
+## Configuration
+
+### Model selection
+
+```json5
+{
+  agents: {
+    defaults: {
+      // String form: primary model only
+      imageGenerationModel: "google/gemini-3.1-flash-image-preview",
+
+      // Object form: primary + ordered fallbacks
+      imageGenerationModel: {
+        primary: "openai/gpt-image-1",
+        fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
+      },
+    },
+  },
+}
+```
+
+### Provider selection order
+
+When generating an image, Durar tries providers in this order:
+
+1. **`model` parameter** from the tool call (if the agent specifies one)
+2. **`imageGenerationModel.primary`** from config
+3. **`imageGenerationModel.fallbacks`** in order
+4. **Auto-detection** — uses auth-backed provider defaults only:
+   - current default provider first
+   - remaining registered image-generation providers in provider-id order
+
+If a provider fails (auth error, rate limit, etc.), the next candidate is tried automatically. If all fail, the error includes details from each attempt.
+
+Notes:
+
+- Auto-detection is auth-aware. A provider default only enters the candidate list
+  when Durar can actually authenticate that provider.
+- Use `action: "list"` to inspect the currently registered providers, their
+  default models, and auth env-var hints.
+
+### Image editing
+
+OpenAI, Google, fal, and MiniMax support editing reference images. Pass a reference image path or URL:
+
+```
+"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
+```
+
+OpenAI and Google support up to 5 reference images via the `images` parameter. fal and MiniMax support 1.
+
+MiniMax image generation is available through both bundled MiniMax auth paths:
+
+- `minimax/image-01` for API-key setups
+- `minimax-portal/image-01` for OAuth setups
+
+## Provider capabilities
+
+| Capability            | OpenAI               | Google               | fal                 | MiniMax                    |
+| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- |
+| Generate              | Yes (up to 4)        | Yes (up to 4)        | Yes (up to 4)       | Yes (up to 9)              |
+| Edit/reference        | Yes (up to 5 images) | Yes (up to 5 images) | Yes (1 image)       | Yes (1 image, subject ref) |
+| Size control          | Yes                  | Yes                  | Yes                 | No                         |
+| Aspect ratio          | No                   | Yes                  | Yes (generate only) | Yes                        |
+| Resolution (1K/2K/4K) | No                   | Yes                  | Yes                 | No                         |
+
+## Related
+
+- [Tools Overview](/tools) — all available agent tools
+- [Configuration Reference](/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` config
+- [Models](/concepts/models) — model configuration and failover

package/docs/tools/index.md

@@ -0,0 +1,174 @@
+---
+summary: "Durar tools and plugins overview: what the agent can do and how to extend it"
+read_when:
+  - You want to understand what tools Durar provides
+  - You need to configure, allow, or deny tools
+  - You are deciding between built-in tools, skills, and plugins
+title: "Tools and Plugins"
+---
+
+# Tools and Plugins
+
+Everything the agent does beyond generating text happens through **tools**.
+Tools are how the agent reads files, runs commands, browses the web, sends
+messages, and interacts with devices.
+
+## Tools, skills, and plugins
+
+Durar has three layers that work together:
+
+<Steps>
+  <Step title="Tools are what the agent calls">
+    A tool is a typed function the agent can invoke (e.g. `exec`, `browser`,
+    `web_search`, `message`). Durar ships a set of **built-in tools** and
+    plugins can register additional ones.
+
+    The agent sees tools as structured function definitions sent to the model API.
+
+  </Step>
+
+  <Step title="Skills teach the agent when and how">
+    A skill is a markdown file (`SKILL.md`) injected into the system prompt.
+    Skills give the agent context, constraints, and step-by-step guidance for
+    using tools effectively. Skills live in your workspace, in shared folders,
+    or ship inside plugins.
+
+    [Skills reference](/tools/skills) | [Creating skills](/tools/creating-skills)
+
+  </Step>
+
+  <Step title="Plugins package everything together">
+    A plugin is a package that can register any combination of capabilities:
+    channels, model providers, tools, skills, speech, realtime transcription,
+    realtime voice, media understanding, image generation, video generation,
+    web fetch, web search, and more. Some plugins are **core** (shipped with
+    Durar), others are **external** (published on npm by the community).
+
+    [Install and configure plugins](/tools/plugin) | [Build your own](/plugins/building-plugins)
+
+  </Step>
+</Steps>
+
+## Built-in tools
+
+These tools ship with Durar and are available without installing any plugins:
+
+| Tool                                       | What it does                                                          | Page                                    |
+| ------------------------------------------ | --------------------------------------------------------------------- | --------------------------------------- |
+| `exec` / `process`                         | Run shell commands, manage background processes                       | [Exec](/tools/exec)                     |
+| `code_execution`                           | Run sandboxed remote Python analysis                                  | [Code Execution](/tools/code-execution) |
+| `browser`                                  | Control a Chromium browser (navigate, click, screenshot)              | [Browser](/tools/browser)               |
+| `web_search` / `x_search` / `web_fetch`    | Search the web, search X posts, fetch page content                    | [Web](/tools/web)                       |
+| `read` / `write` / `edit`                  | File I/O in the workspace                                             |                                         |
+| `apply_patch`                              | Multi-hunk file patches                                               | [Apply Patch](/tools/apply-patch)       |
+| `message`                                  | Send messages across all channels                                     | [Agent Send](/tools/agent-send)         |
+| `canvas`                                   | Drive node Canvas (present, eval, snapshot)                           |                                         |
+| `nodes`                                    | Discover and target paired devices                                    |                                         |
+| `cron` / `gateway`                         | Manage scheduled jobs; inspect, patch, restart, or update the gateway |                                         |
+| `image` / `image_generate`                 | Analyze or generate images                                            |                                         |
+| `tts`                                      | One-shot text-to-speech conversion                                    | [TTS](/tools/tts)                       |
+| `sessions_*` / `subagents` / `agents_list` | Session management, status, and sub-agent orchestration               | [Sub-agents](/tools/subagents)          |
+| `session_status`                           | Lightweight `/status`-style readback and session model override       | [Session Tools](/concepts/session-tool) |
+
+For image work, use `image` for analysis and `image_generate` for generation or editing. If you target `openai/*`, `google/*`, `fal/*`, or another non-default image provider, configure that provider's auth/API key first.
+
+`session_status` is the lightweight status/readback tool in the sessions group.
+It answers `/status`-style questions about the current session and can
+optionally set a per-session model override; `model=default` clears that
+override. Like `/status`, it can backfill sparse token/cache counters and the
+active runtime model label from the latest transcript usage entry.
+
+`gateway` is the owner-only runtime tool for gateway operations:
+
+- `config.schema.lookup` for one path-scoped config subtree before edits
+- `config.get` for the current config snapshot + hash
+- `config.patch` for partial config updates with restart
+- `config.apply` only for full-config replacement
+- `update.run` for explicit self-update + restart
+
+For partial changes, prefer `config.schema.lookup` then `config.patch`. Use
+`config.apply` only when you intentionally replace the entire config.
+The tool also refuses to change `tools.exec.ask` or `tools.exec.security`;
+legacy `tools.bash.*` aliases normalize to the same protected exec paths.
+
+### Plugin-provided tools
+
+Plugins can register additional tools. Some examples:
+
+- [Lobster](/tools/lobster) — typed workflow runtime with resumable approvals
+- [LLM Task](/tools/llm-task) — JSON-only LLM step for structured output
+- [Diffs](/tools/diffs) — diff viewer and renderer
+- [OpenProse](/prose) — markdown-first workflow orchestration
+
+## Tool configuration
+
+### Allow and deny lists
+
+Control which tools the agent can call via `tools.allow` / `tools.deny` in
+config. Deny always wins over allow.
+
+```json5
+{
+  tools: {
+    allow: ["group:fs", "browser", "web_search"],
+    deny: ["exec"],
+  },
+}
+```
+
+### Tool profiles
+
+`tools.profile` sets a base allowlist before `allow`/`deny` is applied.
+Per-agent override: `agents.list[].tools.profile`.
+
+| Profile     | What it includes                                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `full`      | No restriction (same as unset)                                                                                |
+| `coding`    | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate` |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`                     |
+| `minimal`   | `session_status` only                                                                                         |
+
+### Tool groups
+
+Use `group:*` shorthands in allow/deny lists:
+
+| Group              | Tools                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `group:runtime`    | exec, process, code_execution (`bash` is accepted as an alias for `exec`)                                 |
+| `group:fs`         | read, write, edit, apply_patch                                                                            |
+| `group:sessions`   | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
+| `group:memory`     | memory_search, memory_get                                                                                 |
+| `group:web`        | web_search, x_search, web_fetch                                                                           |
+| `group:ui`         | browser, canvas                                                                                           |
+| `group:automation` | cron, gateway                                                                                             |
+| `group:messaging`  | message                                                                                                   |
+| `group:nodes`      | nodes                                                                                                     |
+| `group:agents`     | agents_list                                                                                               |
+| `group:media`      | image, image_generate, tts                                                                                |
+| `group:Durar`   | All built-in Durar tools (excludes plugin tools)                                                       |
+
+`sessions_history` returns a bounded, safety-filtered recall view. It 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 from assistant text, then applies
+redaction/truncation and possible oversized-row placeholders instead of acting
+as a raw transcript dump.
+
+### Provider-specific restrictions
+
+Use `tools.byProvider` to restrict tools for specific providers without
+changing global defaults:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    byProvider: {
+      "google-antigravity": { profile: "minimal" },
+    },
+  },
+}
+```

package/docs/tools/kimi-search.md

@@ -0,0 +1,98 @@
+---
+summary: "Kimi web search via Moonshot web search"
+read_when:
+  - You want to use Kimi for web_search
+  - You need a KIMI_API_KEY or MOONSHOT_API_KEY
+title: "Kimi Search"
+---
+
+# Kimi Search
+
+Durar supports Kimi as a `web_search` provider, using Moonshot web search
+to produce AI-synthesized answers with citations.
+
+## Get an API key
+
+<Steps>
+  <Step title="Create a key">
+    Get an API key from [Moonshot AI](https://platform.moonshot.cn/).
+  </Step>
+  <Step title="Store the key">
+    Set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the Gateway environment, or
+    configure via:
+
+    ```bash
+    Durar configure --section web
+    ```
+
+  </Step>
+</Steps>
+
+When you choose **Kimi** during `Durar onboard` or
+`Durar configure --section web`, Durar can also ask for:
+
+- the Moonshot API region:
+  - `https://api.moonshot.ai/v1`
+  - `https://api.moonshot.cn/v1`
+- the default Kimi web-search model (defaults to `kimi-k2.5`)
+
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      moonshot: {
+        config: {
+          webSearch: {
+            apiKey: "sk-...", // optional if KIMI_API_KEY or MOONSHOT_API_KEY is set
+            baseUrl: "https://api.moonshot.ai/v1",
+            model: "kimi-k2.5",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "kimi",
+      },
+    },
+  },
+}
+```
+
+If you use the China API host for chat (`models.providers.moonshot.baseUrl`:
+`https://api.moonshot.cn/v1`), Durar reuses that same host for Kimi
+`web_search` when `tools.web.search.kimi.baseUrl` is omitted, so keys from
+[platform.moonshot.cn](https://platform.moonshot.cn/) do not hit the
+international endpoint by mistake (which often returns HTTP 401). Override
+with `tools.web.search.kimi.baseUrl` when you need a different search base URL.
+
+**Environment alternative:** set `KIMI_API_KEY` or `MOONSHOT_API_KEY` in the
+Gateway environment. For a gateway install, put it in `~/.Durar/.env`.
+
+If you omit `baseUrl`, Durar defaults to `https://api.moonshot.ai/v1`.
+If you omit `model`, Durar defaults to `kimi-k2.5`.
+
+## How it works
+
+Kimi uses Moonshot web search to synthesize answers with inline citations,
+similar to Gemini and Grok's grounded response approach.
+
+## Supported parameters
+
+Kimi search supports `query`.
+
+`count` is accepted for shared `web_search` compatibility, but Kimi still
+returns one synthesized answer with citations rather than an N-result list.
+
+Provider-specific filters are not currently supported.
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Moonshot AI](/providers/moonshot) -- Moonshot model + Kimi Coding provider docs
+- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers via Google grounding
+- [Grok Search](/tools/grok-search) -- AI-synthesized answers via xAI grounding

package/docs/tools/llm-task.md

@@ -0,0 +1,119 @@
+---
+summary: "JSON-only LLM tasks for workflows (optional plugin tool)"
+read_when:
+  - You want a JSON-only LLM step inside workflows
+  - You need schema-validated LLM output for automation
+title: "LLM Task"
+---
+
+# LLM Task
+
+`llm-task` is an **optional plugin tool** that runs a JSON-only LLM task and
+returns structured output (optionally validated against JSON Schema).
+
+This is ideal for workflow engines like Lobster: you can add a single LLM step
+without writing custom Durar code for each workflow.
+
+## Enable the plugin
+
+1. Enable the plugin:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  }
+}
+```
+
+2. Allowlist the tool (it is registered with `optional: true`):
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "allow": ["llm-task"] }
+      }
+    ]
+  }
+}
+```
+
+## Config (optional)
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": {
+        "enabled": true,
+        "config": {
+          "defaultProvider": "openai-codex",
+          "defaultModel": "gpt-5.4",
+          "defaultAuthProfileId": "main",
+          "allowedModels": ["openai-codex/gpt-5.4"],
+          "maxTokens": 800,
+          "timeoutMs": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+`allowedModels` is an allowlist of `provider/model` strings. If set, any request
+outside the list is rejected.
+
+## Tool parameters
+
+- `prompt` (string, required)
+- `input` (any, optional)
+- `schema` (object, optional JSON Schema)
+- `provider` (string, optional)
+- `model` (string, optional)
+- `thinking` (string, optional)
+- `authProfileId` (string, optional)
+- `temperature` (number, optional)
+- `maxTokens` (number, optional)
+- `timeoutMs` (number, optional)
+
+`thinking` accepts the standard Durar reasoning presets, such as `low` or `medium`.
+
+## Output
+
+Returns `details.json` containing the parsed JSON (and validates against
+`schema` when provided).
+
+## Example: Lobster workflow step
+
+```lobster
+Durar.invoke --tool llm-task --action json --args-json '{
+  "prompt": "Given the input email, return intent and draft.",
+  "thinking": "low",
+  "input": {
+    "subject": "Hello",
+    "body": "Can you help?"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "intent": { "type": "string" },
+      "draft": { "type": "string" }
+    },
+    "required": ["intent", "draft"],
+    "additionalProperties": false
+  }
+}'
+```
+
+## Safety notes
+
+- The tool is **JSON-only** and instructs the model to output only JSON (no
+  code fences, no commentary).
+- No tools are exposed to the model for this run.
+- Treat output as untrusted unless you validate with `schema`.
+- Put approvals before any side-effecting step (send, post, exec).