@tritard/waterbrother 0.15.4 → 0.15.6

package/README.md

@@ -1,6 +1,6 @@
 # waterbrother
 
-A local coding CLI that connects to Grok (`api.x.ai`) with codex/claude-style interactive workflows, local tool calls, session persistence, and approval controls.
+A local coding CLI with codex/claude-style interactive workflows, local tool calls, session persistence, approval controls, and bring-your-own-model provider support across OpenAI, Anthropic, OpenRouter, Ollama, xAI, and compatible APIs.
 
 ## Web docs interface
 
@@ -8,6 +8,7 @@ This repo includes a static docs web interface:
 
 - `/` landing page
 - `/onboarding` onboarding + API key guide
+- `/channels` messaging-channel guide
 - `/install` install instructions
 - `/usage` usage guide
 - `/commands` command reference
@@ -26,10 +27,10 @@ It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
   - `waterbrother resume [session-id] [prompt]`
   - `waterbrother resume --last`
 - First-run onboarding wizard in terminal
-  - asks for API key
-  - offers opening `https://console.x.ai/`
+  - asks for provider first
+  - asks for API key when the selected provider requires one
   - prompts for default model and agent profile
-- Grok API integration (`/chat/completions`)
+- Multi-provider chat integration through provider adapters and model registry
 - Vision command for local images: `waterbrother vision <image-path> <prompt>`
 - Authenticated GitHub repo reading for GitHub URLs, including private repos when `gh` is logged in
 - Built-in webpage reading and web search tools for pasted URLs and open-web research prompts
@@ -39,6 +40,9 @@ It is Vercel-ready via `vercel.json` (clean URLs, no build step required).
 - Agent profiles: `coder`, `designer`, `reviewer`, `planner`
 - Model discovery command (`waterbrother models list`)
 - Local model catalog (`waterbrother models catalog`)
+- Active runtime model status (`waterbrother models status`)
+- Named runtime provider/model presets (`waterbrother runtime-profiles ...`)
+- Messaging gateway and channel readiness commands (`waterbrother gateway status`, `waterbrother channels status`)
 - Onboarding guide command (`waterbrother onboarding`)
 - Local self-update command (`waterbrother update`)
   - git-clone installs pull latest source, install deps, and run checks
@@ -169,6 +173,10 @@ Utility commands:
 waterbrother doctor
 waterbrother models list
 waterbrother models catalog
+waterbrother models status
+waterbrother runtime-profiles list
+waterbrother channels status
+waterbrother gateway status
 waterbrother mcp list
 waterbrother onboarding
 waterbrother update
@@ -177,15 +185,82 @@ waterbrother update
 Web research examples:
 
 ```bash
-waterbrother "Read https://console.x.ai and summarize how to create an API key"
-waterbrother "Search the web for the latest xAI API docs about vision support and cite the sources"
+waterbrother "Read https://docs.anthropic.com/en/api/messages and summarize tool use"
+waterbrother "Search the web for the latest model provider docs about tool calling and cite the sources"
 
 # interactive
-/read https://console.x.ai/
-/search latest xAI vision docs
+/provider
+/provider anthropic
+/providers
+/runtime
+/channels
+/gateway
+/onboarding telegram
+/runtime-profile save review-anthropic
+/runtime-profile load review-anthropic
+/runtime-profiles
+/model anthropic/claude-sonnet-4-20250514
+/models
+
+# config
+waterbrother config set provider anthropic --scope project
+waterbrother config set model anthropic/claude-sonnet-4-20250514 --scope project
+
+# inspect runtime
+waterbrother models status
+waterbrother runtime-profiles show review-anthropic
+waterbrother channels status
+waterbrother gateway status
+
+# interactive
+/read https://docs.anthropic.com/en/api/messages
+/search latest model provider tool calling docs
 /open 1
 ```
 
+## Messaging foundation
+
+Waterbrother now includes the first messaging-control foundation.
+
+- Services targeted first:
+  - Telegram
+  - Discord
+  - Signal
+- Current scope:
+  - normalized channel config
+  - gateway/channel readiness reporting
+  - service-specific onboarding
+- Live now:
+  - Telegram single-user remote control
+- Not shipped yet:
+  - Discord live adapter
+  - Signal live adapter
+  - group DM collaboration
+
+Use the new commands to prepare and validate channel setup:
+
+```bash
+waterbrother channels list
+waterbrother channels status
+waterbrother channels show telegram
+waterbrother gateway status
+waterbrother gateway run telegram
+waterbrother onboarding telegram
+waterbrother onboarding discord
+waterbrother onboarding signal
+```
+
+Rollout order:
+1. single-user remote terminal control
+2. status and observation from linked channels
+3. approvals over messaging
+4. only then group DM collaboration
+
+Current Telegram limitation:
+- remote prompts run with `approval=never`
+- status, runtime inspection, and read-oriented prompts work best
+- mutating and approval-heavy work stay local until remote approvals land
+
 ## Release flow
 
 Partners should ship updates by pushing a version tag, not by running `npm publish` locally.
@@ -240,7 +315,8 @@ Long-running session controls:
 waterbrother config set autoCompactThreshold 0.9
 waterbrother config set traceMode verbose
 waterbrother config set receiptMode verbose
-waterbrother config set model grok-4.20-beta-0309-reasoning --scope project
+waterbrother config set provider openai --scope project
+waterbrother config set model openai/gpt-4.1 --scope project
 waterbrother config set-json approvalPolicy '{"autoApprovePaths":["src/**"],"askPaths":["package.json"],"denyShellPatterns":["git\\s+reset\\s+--hard"]}' --scope project
 waterbrother config set-json verification '{"commands":["npm run lint","npm test"],"timeoutMs":180000}' --scope project
 waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}}' --scope project

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.15.4",
-  "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
+  "version": "0.15.6",
+  "description": "Waterbrother: bring-your-own-model coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {
     "waterbrother": "bin/waterbrother.js"
@@ -33,7 +33,6 @@
   },
   "keywords": [
     "cli",
-    "grok",
     "coding-agent",
     "terminal",
     "ai",

package/src/agent.js

@@ -1,4 +1,4 @@
-import { createChatCompletion, createChatCompletionStream } from "./grok-client.js";
+import { createChatCompletion, createChatCompletionStream } from "./model-client.js";
 import { getAutonomyModePrompt, getExperienceModePrompt, normalizeAutonomyMode, normalizeExperienceMode } from "./modes.js";
 import { createToolRuntime } from "./tools.js";
 
@@ -363,6 +363,11 @@ export class Agent {
     this.model = model;
   }
 
+  setTransport({ apiKey, baseUrl } = {}) {
+    if (apiKey !== undefined) this.apiKey = apiKey;
+    if (baseUrl !== undefined) this.baseUrl = baseUrl;
+  }
+
   getModel() {
     return this.model;
   }

package/src/channels.js

@@ -0,0 +1,238 @@
+const CHANNEL_SPECS = {
+  telegram: {
+    id: "telegram",
+    label: "Telegram",
+    docsPath: "/onboarding/telegram",
+    envKeys: ["TELEGRAM_BOT_TOKEN"],
+    requiredFields: ["botToken"]
+  },
+  discord: {
+    id: "discord",
+    label: "Discord",
+    docsPath: "/onboarding/discord",
+    envKeys: ["DISCORD_BOT_TOKEN", "DISCORD_APPLICATION_ID"],
+    requiredFields: ["botToken", "applicationId"]
+  },
+  signal: {
+    id: "signal",
+    label: "Signal",
+    docsPath: "/onboarding/signal",
+    envKeys: ["SIGNAL_PHONE_NUMBER"],
+    requiredFields: ["phoneNumber"]
+  }
+};
+
+const CHANNEL_IDS = Object.keys(CHANNEL_SPECS);
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => String(item || "").trim()).filter(Boolean);
+}
+
+function normalizePairingMode(value, fallback = "manual") {
+  const next = String(value || fallback).trim().toLowerCase();
+  return ["manual", "allowlist"].includes(next) ? next : fallback;
+}
+
+function normalizePort(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.max(1, Math.min(65535, Math.floor(parsed))) : fallback;
+}
+
+function normalizeCommonChannelConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    enabled: Boolean(source.enabled),
+    pairingMode: normalizePairingMode(source.pairingMode),
+    defaultRuntimeProfile: String(source.defaultRuntimeProfile || "").trim(),
+    linkedSessionId: String(source.linkedSessionId || "").trim(),
+    allowedUserIds: asStringArray(source.allowedUserIds)
+  };
+}
+
+function normalizeTelegramConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  const common = normalizeCommonChannelConfig(source);
+  return {
+    ...common,
+    botToken: String(source.botToken || "").trim()
+  };
+}
+
+function normalizeDiscordConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  const common = normalizeCommonChannelConfig(source);
+  return {
+    ...common,
+    botToken: String(source.botToken || "").trim(),
+    applicationId: String(source.applicationId || "").trim(),
+    allowedGuildIds: asStringArray(source.allowedGuildIds)
+  };
+}
+
+function normalizeSignalConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  const common = normalizeCommonChannelConfig(source);
+  return {
+    ...common,
+    phoneNumber: String(source.phoneNumber || "").trim(),
+    signalCliPath: String(source.signalCliPath || "signal-cli").trim()
+  };
+}
+
+export function normalizeChannelsConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    telegram: normalizeTelegramConfig(source.telegram),
+    discord: normalizeDiscordConfig(source.discord),
+    signal: normalizeSignalConfig(source.signal)
+  };
+}
+
+export function normalizeGatewayConfig(value = {}) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    enabled: Boolean(source.enabled),
+    bindAddress: String(source.bindAddress || "127.0.0.1").trim() || "127.0.0.1",
+    port: normalizePort(source.port, 4581),
+    controlMode: String(source.controlMode || "single-user").trim().toLowerCase() === "group" ? "group" : "single-user",
+    defaultRuntimeProfile: String(source.defaultRuntimeProfile || "").trim(),
+    startupChannels: asStringArray(source.startupChannels).filter((item) => CHANNEL_IDS.includes(item)),
+    requirePairing: source.requirePairing !== false
+  };
+}
+
+function summarizeChannel(serviceId, config = {}) {
+  const spec = CHANNEL_SPECS[serviceId];
+  const missing = [];
+
+  if (config.enabled) {
+    for (const field of spec.requiredFields) {
+      if (!String(config[field] || "").trim()) missing.push(field);
+    }
+    if (config.pairingMode === "allowlist" && (config.allowedUserIds || []).length === 0) {
+      missing.push("allowedUserIds");
+    }
+  }
+
+  const configured = spec.requiredFields.some((field) => String(config[field] || "").trim());
+  const ready = Boolean(config.enabled) && missing.length === 0;
+  const state = !config.enabled ? "disabled" : ready ? "ready" : "partial";
+
+  return {
+    id: spec.id,
+    label: spec.label,
+    docsPath: spec.docsPath,
+    enabled: Boolean(config.enabled),
+    configured,
+    ready,
+    state,
+    pairingMode: config.pairingMode || "manual",
+    defaultRuntimeProfile: config.defaultRuntimeProfile || "",
+    linkedSessionId: config.linkedSessionId || "",
+    missing,
+    requiredFields: [...spec.requiredFields],
+    envKeys: [...spec.envKeys]
+  };
+}
+
+export function getChannelSpec(serviceId) {
+  return CHANNEL_SPECS[String(serviceId || "").trim().toLowerCase()] || null;
+}
+
+export function getChannelStatuses(runtime = {}) {
+  const channels = normalizeChannelsConfig(runtime.channels || {});
+  return CHANNEL_IDS.map((serviceId) => summarizeChannel(serviceId, channels[serviceId]));
+}
+
+export function getGatewayStatus(runtime = {}) {
+  const gateway = normalizeGatewayConfig(runtime.gateway || {});
+  const channels = getChannelStatuses(runtime);
+  const enabledChannels = channels.filter((channel) => channel.enabled);
+  const readyChannels = enabledChannels.filter((channel) => channel.ready);
+  return {
+    enabled: gateway.enabled,
+    bindAddress: gateway.bindAddress,
+    port: gateway.port,
+    controlMode: gateway.controlMode,
+    requirePairing: gateway.requirePairing,
+    defaultRuntimeProfile: gateway.defaultRuntimeProfile,
+    startupChannels: gateway.startupChannels,
+    enabledChannelCount: enabledChannels.length,
+    readyChannelCount: readyChannels.length,
+    ready: gateway.enabled && enabledChannels.length > 0 && readyChannels.length === enabledChannels.length,
+    channels
+  };
+}
+
+export function buildChannelOnboardingPayload(serviceId) {
+  const spec = getChannelSpec(serviceId);
+  if (!spec) return null;
+
+  if (serviceId === "telegram") {
+    return {
+      id: spec.id,
+      label: spec.label,
+      docsPath: spec.docsPath,
+      summary: "Single-user Telegram control through a bot token and DM pairing.",
+      prerequisites: [
+        "Create a Telegram bot with BotFather",
+        "Capture the bot token",
+        "Choose manual pairing or an allowlist"
+      ],
+      commands: [
+        "waterbrother config set-json channels '{\"telegram\":{\"enabled\":true,\"botToken\":\"YOUR_BOT_TOKEN\",\"pairingMode\":\"manual\",\"allowedUserIds\":[]}}'",
+        "waterbrother channels status",
+        "waterbrother gateway status"
+      ],
+      notes: [
+        "Start with direct messages only.",
+        "Keep pairing manual until remote-control approvals are stable."
+      ]
+    };
+  }
+
+  if (serviceId === "discord") {
+    return {
+      id: spec.id,
+      label: spec.label,
+      docsPath: spec.docsPath,
+      summary: "Single-user Discord control through a bot token, application id, and DM-first policy.",
+      prerequisites: [
+        "Create a Discord application and bot",
+        "Capture the bot token and application id",
+        "Enable only the intents you actually need"
+      ],
+      commands: [
+        "waterbrother config set-json channels '{\"discord\":{\"enabled\":true,\"botToken\":\"YOUR_BOT_TOKEN\",\"applicationId\":\"YOUR_APP_ID\",\"pairingMode\":\"manual\",\"allowedUserIds\":[]}}'",
+        "waterbrother channels status",
+        "waterbrother gateway status"
+      ],
+      notes: [
+        "Start with direct messages before any guild or channel workflow.",
+        "Prefer explicit user allowlists."
+      ]
+    };
+  }
+
+  return {
+    id: spec.id,
+    label: spec.label,
+    docsPath: spec.docsPath,
+    summary: "Single-user Signal control through signal-cli and a paired local account.",
+    prerequisites: [
+      "Install signal-cli locally",
+      "Register or link a Signal number/device",
+      "Choose manual pairing or an allowlist"
+    ],
+    commands: [
+      "waterbrother config set-json channels '{\"signal\":{\"enabled\":true,\"phoneNumber\":\"+15551234567\",\"signalCliPath\":\"signal-cli\",\"pairingMode\":\"manual\",\"allowedUserIds\":[]}}'",
+      "waterbrother channels status",
+      "waterbrother gateway status"
+    ],
+    notes: [
+      "Signal is operationally heavier than Telegram or Discord.",
+      "Treat it as a controlled adapter, not a zero-config bot."
+    ]
+  };
+}