durar-ai 2026.4.4

package/docs/web/tui.md

@@ -0,0 +1,176 @@
+---
+summary: "Terminal UI (TUI): connect to the Gateway from any machine"
+read_when:
+  - You want a beginner-friendly walkthrough of the TUI
+  - You need the complete list of TUI features, commands, and shortcuts
+title: "TUI"
+---
+
+# TUI (Terminal UI)
+
+## Quick start
+
+1. Start the Gateway.
+
+```bash
+Durar gateway
+```
+
+2. Open the TUI.
+
+```bash
+Durar tui
+```
+
+3. Type a message and press Enter.
+
+Remote Gateway:
+
+```bash
+Durar tui --url ws://<host>:<port> --token <gateway-token>
+```
+
+Use `--password` if your Gateway uses password auth.
+
+## What you see
+
+- Header: connection URL, current agent, current session.
+- Chat log: user messages, assistant replies, system notices, tool cards.
+- Status line: connection/run state (connecting, running, streaming, idle, error).
+- Footer: connection state + agent + session + model + think/fast/verbose/reasoning + token counts + deliver.
+- Input: text editor with autocomplete.
+
+## Mental model: agents + sessions
+
+- Agents are unique slugs (e.g. `main`, `research`). The Gateway exposes the list.
+- Sessions belong to the current agent.
+- Session keys are stored as `agent:<agentId>:<sessionKey>`.
+  - If you type `/session main`, the TUI expands it to `agent:<currentAgent>:main`.
+  - If you type `/session agent:other:main`, you switch to that agent session explicitly.
+- Session scope:
+  - `per-sender` (default): each agent has many sessions.
+  - `global`: the TUI always uses the `global` session (the picker may be empty).
+- The current agent + session are always visible in the footer.
+
+## Sending + delivery
+
+- Messages are sent to the Gateway; delivery to providers is off by default.
+- Turn delivery on:
+  - `/deliver on`
+  - or the Settings panel
+  - or start with `Durar tui --deliver`
+
+## Pickers + overlays
+
+- Model picker: list available models and set the session override.
+- Agent picker: choose a different agent.
+- Session picker: shows only sessions for the current agent.
+- Settings: toggle deliver, tool output expansion, and thinking visibility.
+
+## Keyboard shortcuts
+
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+G: agent picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility (reloads history)
+
+## Slash commands
+
+Core:
+
+- `/help`
+- `/status`
+- `/agent <id>` (or `/agents`)
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/models`)
+
+Session controls:
+
+- `/think <off|minimal|low|medium|high>`
+- `/fast <status|on|off>`
+- `/verbose <on|full|off>`
+- `/reasoning <on|off|stream>`
+- `/usage <off|tokens|full>`
+- `/elevated <on|off|ask|full>` (alias: `/elev`)
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+
+Session lifecycle:
+
+- `/new` or `/reset` (reset the session)
+- `/abort` (abort the active run)
+- `/settings`
+- `/exit`
+
+Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
+
+## Local shell commands
+
+- Prefix a line with `!` to run a local shell command on the TUI host.
+- The TUI prompts once per session to allow local execution; declining keeps `!` disabled for the session.
+- Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent `cd`/env).
+- Local shell commands receive `Durar_SHELL=tui-local` in their environment.
+- A lone `!` is sent as a normal message; leading spaces do not trigger local exec.
+
+## Tool output
+
+- Tool calls show as cards with args + results.
+- Ctrl+O toggles between collapsed/expanded views.
+- While tools run, partial updates stream into the same card.
+
+## Terminal colors
+
+- The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
+- If your terminal uses a light background and auto-detection is wrong, set `Durar_THEME=light` before launching `Durar tui`.
+- To force the original dark palette instead, set `Durar_THEME=dark`.
+
+## History + streaming
+
+- On connect, the TUI loads the latest history (default 200 messages).
+- Streaming responses update in place until finalized.
+- The TUI also listens to agent tool events for richer tool cards.
+
+## Connection details
+
+- The TUI registers with the Gateway as `mode: "tui"`.
+- Reconnects show a system message; event gaps are surfaced in the log.
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:<port>`)
+- `--token <token>`: Gateway token (if required)
+- `--password <password>`: Gateway password (if required)
+- `--session <key>`: Session key (default: `main`, or `global` when scope is global)
+- `--deliver`: Deliver assistant replies to the provider (default off)
+- `--thinking <level>`: Override thinking level for sends
+- `--message <text>`: Send an initial message after connecting
+- `--timeout-ms <ms>`: Agent timeout in ms (defaults to `agents.defaults.timeoutSeconds`)
+- `--history-limit <n>`: History entries to load (default `200`)
+
+Note: when you set `--url`, the TUI does not fall back to config or environment credentials.
+Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+## Troubleshooting
+
+No output after sending a message:
+
+- Run `/status` in the TUI to confirm the Gateway is connected and idle/busy.
+- Check the Gateway logs: `Durar logs --follow`.
+- Confirm the agent can run: `Durar status` and `Durar models status`.
+- If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`).
+
+## Connection troubleshooting
+
+- `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct.
+- No agents in picker: check `Durar agents list` and your routing config.
+- Empty session picker: you might be in global scope or have no sessions yet.
+
+## Related
+
+- [Control UI](/web/control-ui) — web-based control interface
+- [CLI Reference](/cli) — full CLI command reference

package/docs/web/webchat.md

@@ -0,0 +1,77 @@
+---
+summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
+read_when:
+  - Debugging or configuring WebChat access
+title: "WebChat"
+---
+
+# WebChat (Gateway WebSocket UI)
+
+Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
+
+## What it is
+
+- A native chat UI for the gateway (no embedded browser and no local static server).
+- Uses the same sessions and routing rules as other channels.
+- Deterministic routing: replies always go back to WebChat.
+
+## Quick start
+
+1. Start the gateway.
+2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
+3. Ensure a valid gateway auth path is configured (shared-secret by default,
+   even on loopback).
+
+## How it works (behavior)
+
+- The UI connects to the Gateway WebSocket and uses `chat.history`, `chat.send`, and `chat.inject`.
+- `chat.history` is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with `[chat.history omitted: message too large]`.
+- `chat.history` is also display-normalized: inline delivery directive tags
+  such as `[[reply_to_*]]` and `[[audio_as_voice]]`, 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), and
+  leaked ASCII/full-width model control tokens are stripped from visible text,
+  and assistant entries whose whole visible text is only the exact silent
+  token `NO_REPLY` / `no_reply` are omitted.
+- `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).
+- Aborted runs can keep partial assistant output visible in the UI.
+- Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.
+- History is always fetched from the gateway (no local file watching).
+- If the gateway is unreachable, WebChat is read-only.
+
+## Control UI agents tools panel
+
+- The Control UI `/agents` Tools panel has two separate views:
+  - **Available Right Now** uses `tools.effective(sessionKey=...)` and shows what the current
+    session can actually use at runtime, including core, plugin, and channel-owned tools.
+  - **Tool Configuration** uses `tools.catalog` and stays focused on profiles, overrides, and
+    catalog semantics.
+- Runtime availability is session-scoped. Switching sessions on the same agent can change the
+  **Available Right Now** list.
+- The config editor does not imply runtime availability; effective access still follows policy
+  precedence (`allow`/`deny`, per-agent and provider/channel overrides).
+
+## Remote use
+
+- Remote mode tunnels the gateway WebSocket over SSH/Tailscale.
+- You do not need to run a separate WebChat server.
+
+## Configuration reference (WebChat)
+
+Full configuration: [Configuration](/gateway/configuration)
+
+WebChat options:
+
+- `gateway.webchat.chatHistoryMaxChars`: maximum character count for text fields in `chat.history` responses. When a transcript entry exceeds this limit, Gateway truncates long text fields and may replace oversized messages with a placeholder. Per-request `maxChars` can also be sent by the client to override this default for a single `chat.history` call.
+
+Related global options:
+
+- `gateway.port`, `gateway.bind`: WebSocket host/port.
+- `gateway.auth.mode`, `gateway.auth.token`, `gateway.auth.password`:
+  shared-secret WebSocket auth.
+- `gateway.auth.allowTailscale`: browser Control UI chat tab can use Tailscale
+  Serve identity headers when enabled.
+- `gateway.auth.mode: "trusted-proxy"`: reverse-proxy auth for browser clients behind an identity-aware **non-loopback** proxy source (see [Trusted Proxy Auth](/gateway/trusted-proxy-auth)).
+- `gateway.remote.url`, `gateway.remote.token`, `gateway.remote.password`: remote gateway target.
+- `session.*`: session storage and main key defaults.

package/durar.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { access } from "node:fs/promises";
+import module from "node:module";
+import { fileURLToPath } from "node:url";
+
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 12;
+const MIN_NODE_VERSION = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
+
+const parseNodeVersion = (rawVersion) => {
+  const [majorRaw = "0", minorRaw = "0"] = rawVersion.split(".");
+  return {
+    major: Number(majorRaw),
+    minor: Number(minorRaw),
+  };
+};
+
+const isSupportedNodeVersion = (version) =>
+  version.major > MIN_NODE_MAJOR ||
+  (version.major === MIN_NODE_MAJOR && version.minor >= MIN_NODE_MINOR);
+
+const ensureSupportedNodeVersion = () => {
+  if (isSupportedNodeVersion(parseNodeVersion(process.versions.node))) {
+    return;
+  }
+
+  process.stderr.write(
+    `openclaw: Node.js v${MIN_NODE_VERSION}+ is required (current: v${process.versions.node}).\n` +
+      "If you use nvm, run:\n" +
+      `  nvm install ${MIN_NODE_MAJOR}\n` +
+      `  nvm use ${MIN_NODE_MAJOR}\n` +
+      `  nvm alias default ${MIN_NODE_MAJOR}\n`,
+  );
+  process.exit(1);
+};
+
+ensureSupportedNodeVersion();
+
+// https://nodejs.org/api/module.html#module-compile-cache
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors
+  }
+}
+
+const isModuleNotFoundError = (err) =>
+  err && typeof err === "object" && "code" in err && err.code === "ERR_MODULE_NOT_FOUND";
+
+const isDirectModuleNotFoundError = (err, specifier) => {
+  if (!isModuleNotFoundError(err)) {
+    return false;
+  }
+
+  const expectedUrl = new URL(specifier, import.meta.url);
+  if ("url" in err && err.url === expectedUrl.href) {
+    return true;
+  }
+
+  const message = "message" in err && typeof err.message === "string" ? err.message : "";
+  const expectedPath = fileURLToPath(expectedUrl);
+  return (
+    message.includes(`Cannot find module '${expectedPath}'`) ||
+    message.includes(`Cannot find module "${expectedPath}"`)
+  );
+};
+
+const installProcessWarningFilter = async () => {
+  // Keep bootstrap warnings consistent with the TypeScript runtime.
+  for (const specifier of ["./dist/warning-filter.js", "./dist/warning-filter.mjs"]) {
+    try {
+      const mod = await import(specifier);
+      if (typeof mod.installProcessWarningFilter === "function") {
+        mod.installProcessWarningFilter();
+        return;
+      }
+    } catch (err) {
+      if (isDirectModuleNotFoundError(err, specifier)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+};
+
+const tryImport = async (specifier) => {
+  try {
+    await import(specifier);
+    return true;
+  } catch (err) {
+    // Only swallow direct entry misses; rethrow transitive resolution failures.
+    if (isDirectModuleNotFoundError(err, specifier)) {
+      return false;
+    }
+    throw err;
+  }
+};
+
+const exists = async (specifier) => {
+  try {
+    await access(new URL(specifier, import.meta.url));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const buildMissingEntryErrorMessage = async () => {
+  const lines = ["openclaw: missing dist/entry.(m)js (build output)."];
+  if (!(await exists("./src/entry.ts"))) {
+    return lines.join("\n");
+  }
+
+  lines.push("This install looks like an unbuilt source tree or GitHub source archive.");
+  lines.push(
+    "Build locally with `pnpm install && pnpm build`, or install a built package instead.",
+  );
+  lines.push(
+    "For pinned GitHub installs, use `npm install -g github:openclaw/openclaw#<ref>` instead of a raw `/archive/<ref>.tar.gz` URL.",
+  );
+  lines.push("For releases, use `npm install -g openclaw@latest`.");
+  return lines.join("\n");
+};
+
+const isBareRootHelpInvocation = (argv) =>
+  argv.length === 3 && (argv[2] === "--help" || argv[2] === "-h");
+
+const loadPrecomputedRootHelpText = () => {
+  try {
+    const raw = readFileSync(new URL("./dist/cli-startup-metadata.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.rootHelpText === "string" && parsed.rootHelpText.length > 0
+      ? parsed.rootHelpText
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const tryOutputBareRootHelp = async () => {
+  if (!isBareRootHelpInvocation(process.argv)) {
+    return false;
+  }
+  const precomputed = loadPrecomputedRootHelpText();
+  if (precomputed) {
+    process.stdout.write(precomputed);
+    return true;
+  }
+  for (const specifier of ["./dist/cli/program/root-help.js", "./dist/cli/program/root-help.mjs"]) {
+    try {
+      const mod = await import(specifier);
+      if (typeof mod.outputRootHelp === "function") {
+        mod.outputRootHelp();
+        return true;
+      }
+    } catch (err) {
+      if (isDirectModuleNotFoundError(err, specifier)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+  return false;
+};
+
+if (await tryOutputBareRootHelp()) {
+  // OK
+} else {
+  await installProcessWarningFilter();
+  if (await tryImport("./dist/entry.js")) {
+    // OK
+  } else if (await tryImport("./dist/entry.mjs")) {
+    // OK
+  } else {
+    throw new Error(await buildMissingEntryErrorMessage());
+  }
+}