zubo 0.1.19 → 0.1.20

package/README.md

@@ -56,7 +56,7 @@ npm i -g zubo      # also works
 Then:
 
 ```bash
-zubo setup         # interactive config wizard
+zubo setup         # interactive config wizard (terminal or browser)
 zubo start         # launch the agent
 ```
 
@@ -118,7 +118,7 @@ Set secrets through natural conversation: *"Set my github_token to ghp_..."*
 ## CLI
 
 ```
-zubo setup                 Interactive configuration wizard
+zubo setup                 Interactive configuration wizard (terminal or browser)
 zubo start [--daemon]      Start the agent
 zubo stop                  Stop the background daemon
 zubo status                Show runtime status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zubo",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Your AI agent that never forgets. Persistent memory, 25+ tools, 7 channels, 11+ LLM providers — runs entirely on your machine.",
   "license": "MIT",
   "author": "thomaskanze",

package/site/docs/cli.html

@@ -88,9 +88,14 @@
       <h2>Core Commands</h2>
 
       <h3>zubo setup</h3>
-      <p>Interactive 4-step wizard for first-time configuration. Walks you through the full initial setup process:</p>
+      <p>Interactive 4-step wizard for first-time configuration. When you run it, you'll be asked to choose between two modes:</p>
+      <ul>
+        <li><strong>Terminal</strong> &mdash; Classic step-by-step prompts right in your terminal.</li>
+        <li><strong>Dashboard</strong> &mdash; Opens a beautiful browser-based wizard at <code>http://localhost:&lt;port&gt;</code> with the same steps, auto-detection of local providers (Ollama, LM Studio), and connection testing. Great for non-technical users or if you prefer a visual UI.</li>
+      </ul>
+      <p>Both modes walk you through 4 steps:</p>
       <ol>
-        <li><strong>LLM Provider</strong> &mdash; Choose from 12 supported providers (Anthropic, OpenAI, Google, Groq, Ollama, and more). Enter your API key and select a model. Optionally add a fallback provider for automatic failover.</li>
+        <li><strong>LLM Provider</strong> &mdash; Choose from 15 supported providers (Anthropic, OpenAI, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, MiniMax, Fireworks, Cerebras, LM Studio, Claude Code, Codex, or any OpenAI-compatible endpoint). Enter your API key and select a model. Optionally add a fallback provider for automatic failover.</li>
         <li><strong>Channels</strong> &mdash; Enable any of 7 messaging channels: Telegram, Discord, Slack, WhatsApp, Signal, and Email. WebChat is always enabled by default. Each channel prompts for its required credentials (bot tokens, webhook URLs, etc.).</li>
         <li><strong>Personalization</strong> &mdash; Name your agent and optionally describe its personality. The name and personality are used in the system prompt and across all channels.</li>
         <li><strong>Smart Routing</strong> &mdash; Optionally set up a fast provider for simple queries (e.g., greetings, factual lookups). Smart routing automatically directs simple messages to a cheaper, faster model while using the primary model for complex tasks &mdash; saving 50&ndash;80% on costs.</li>

package/site/docs/config.html

@@ -251,6 +251,98 @@ zubo config get rateLimit          # Show all rate limit settings</code></pre>
         </tbody>
       </table>
 
+      <!-- ================================================================ -->
+      <h3 id="local-models">Local Models (Ollama &amp; LM Studio)</h3>
+
+      <p>
+        Local models run entirely on your machine — no API keys, no usage fees, and your data never leaves your computer. They're ideal as a primary provider for privacy-focused setups, or as a failover when your internet is down.
+      </p>
+
+      <h4>Ollama</h4>
+
+      <p><a href="https://ollama.com" target="_blank">Ollama</a> is a lightweight runtime for running open-source models locally. It provides an OpenAI-compatible API out of the box.</p>
+
+      <p><strong>Installation:</strong></p>
+<pre><code># macOS (Homebrew)
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows — download from https://ollama.com/download</code></pre>
+
+      <p><strong>Getting started:</strong></p>
+<pre><code># Start the Ollama server (runs on port 11434)
+ollama serve
+
+# Pull a model
+ollama pull llama3.3       # Meta Llama 3.3 (good general-purpose)
+ollama pull mistral        # Mistral 7B (fast, lightweight)
+ollama pull qwen2.5        # Qwen 2.5 (strong multilingual)
+ollama pull deepseek-r1    # DeepSeek R1 (strong reasoning)
+ollama pull gemma2         # Google Gemma 2
+
+# List downloaded models
+ollama list</code></pre>
+
+      <p><strong>Zubo configuration:</strong></p>
+<pre><code>"ollama": {
+  "baseUrl": "http://localhost:11434/v1",
+  "model": "llama3.3",
+  "apiKey": "ollama"
+}</code></pre>
+      <p>The <code>apiKey</code> field is required by the OpenAI-compatible client but Ollama ignores it — any value works.</p>
+
+      <h4>LM Studio</h4>
+
+      <p><a href="https://lmstudio.ai" target="_blank">LM Studio</a> provides a graphical interface for downloading, managing, and running local models. It includes a built-in server that exposes an OpenAI-compatible API.</p>
+
+      <p><strong>Installation:</strong></p>
+      <ol>
+        <li>Download LM Studio from <a href="https://lmstudio.ai" target="_blank">lmstudio.ai</a> (macOS, Windows, Linux)</li>
+        <li>Open LM Studio and browse the model library to download a model</li>
+        <li>Go to the <strong>Local Server</strong> tab in the left sidebar</li>
+        <li>Select your model and click <strong>Start Server</strong> — it runs on port 1234 by default</li>
+      </ol>
+
+      <p><strong>Zubo configuration:</strong></p>
+<pre><code>"lmstudio": {
+  "baseUrl": "http://localhost:1234/v1",
+  "model": "your-model-name",
+  "apiKey": "lm-studio"
+}</code></pre>
+
+      <p><strong>Tip:</strong> Local models work great as a failover. Set a cloud provider as primary and Ollama/LM Studio as the fallback — if your API key runs out or the network drops, Zubo seamlessly falls back to your local model:</p>
+<pre><code>"activeProvider": "anthropic",
+"failover": ["ollama"]</code></pre>
+
+      <h4>CLI Providers (Claude Code &amp; OpenAI Codex)</h4>
+
+      <p>These providers use locally installed CLI tools that handle their own authentication — no API key configuration needed in Zubo.</p>
+
+      <table>
+        <thead>
+          <tr><th>Provider</th><th>CLI Tool</th><th>Install</th><th>Auth</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>claude-code</code></td>
+            <td><code>claude</code></td>
+            <td><code>npm install -g @anthropic-ai/claude-code</code></td>
+            <td>Run <code>claude</code> once to authenticate via browser</td>
+          </tr>
+          <tr>
+            <td><code>codex</code></td>
+            <td><code>codex</code></td>
+            <td><code>npm install -g @openai/codex</code></td>
+            <td>Run <code>codex auth login</code> to authenticate</td>
+          </tr>
+        </tbody>
+      </table>
+
+<pre><code>"claude-code": { "model": "claude-sonnet-4-5-20250929" }
+"codex": { "model": "o4-mini" }</code></pre>
+
       <h3>Multi-Provider Example with Failover</h3>
 
 <pre><code>{

package/site/docs/index.html

@@ -296,9 +296,11 @@ docker compose up -d</code></pre>
 
 <pre><code>zubo setup</code></pre>
 
-      <p>The interactive setup wizard walks you through 4 steps to get Zubo fully configured:</p>
+      <p>You'll be asked to choose between <strong>Terminal</strong> (classic prompts) or <strong>Dashboard</strong> (a browser-based wizard with visual provider cards, auto-detection, and connection testing). Both paths configure the same thing &mdash; pick whichever you prefer.</p>
+
+      <p>The wizard walks you through 4 steps:</p>
       <ul>
-        <li><strong>Step 1: LLM Provider</strong> &mdash; choose from 12 supported providers (Anthropic, OpenAI, Google Gemini, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, Fireworks, LM Studio, or any OpenAI-compatible endpoint) and enter your API key. Optionally configure a fallback provider for automatic failover.</li>
+        <li><strong>Step 1: LLM Provider</strong> &mdash; choose from 15 supported providers (Anthropic, OpenAI, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, MiniMax, Fireworks, Cerebras, LM Studio, Claude Code, Codex, or any OpenAI-compatible endpoint) and enter your API key. Optionally configure a fallback provider for automatic failover.</li>
         <li><strong>Step 2: Channels</strong> &mdash; enable any combination of Telegram, Discord, Slack, WhatsApp, Signal, and Email. Enter the required tokens and credentials for each. Web Chat is always on and requires no configuration.</li>
         <li><strong>Step 3: Personalization</strong> &mdash; set your agent's name and describe its personality. This shapes how Zubo talks to you across all channels.</li>
         <li><strong>Step 4: Smart Routing</strong> &mdash; optionally configure a fast model (e.g., Groq) for simple queries. Smart routing automatically detects low-complexity messages and routes them to the cheaper, faster model, saving 50&ndash;80% on costs without sacrificing quality for complex tasks.</li>

package/site/docs/webhooks.html

@@ -97,6 +97,23 @@
         Webhooks let external services push events to Zubo in real time. When a webhook receives an event, Zubo processes the payload through a configurable prompt template and takes action automatically. This turns Zubo into a reactive automation hub — connect GitHub for push notifications, Stripe for payment events, CI/CD pipelines for build results, or any service that can send HTTP POST requests.
       </p>
 
+      <!-- ================================================================ -->
+      <h2 id="network-requirements">Network Requirements</h2>
+
+      <div style="background: rgba(245,166,35,0.08); border-left: 3px solid #f5a623; padding: 14px 18px; border-radius: 6px; margin: 16px 0; font-size: 14px; line-height: 1.6;">
+        <strong style="color: #f5a623;">Localhost won't work for external services.</strong> Webhook URLs like <code>http://localhost:61939/api/webhook/...</code> are only reachable from your own machine. External services (GitHub, Stripe, etc.) cannot send events to localhost.
+      </div>
+
+      <p>To receive webhooks from external services, you need a publicly reachable URL. Options:</p>
+
+      <ul>
+        <li><strong>ngrok</strong> &mdash; Run <code>ngrok http 61939</code> to get a public HTTPS URL that tunnels to your local Zubo instance. Free tier available.</li>
+        <li><strong>Cloudflare Tunnel</strong> &mdash; Run <code>cloudflared tunnel --url http://localhost:61939</code> for a free, fast tunnel.</li>
+        <li><strong>Deploy Zubo</strong> &mdash; Run Zubo on a VPS or cloud server with a public IP and domain name.</li>
+      </ul>
+
+      <p>Once you have a public URL, configure the external service to send events to <code>https://your-public-url/api/webhook/&lt;webhook-id&gt;</code>.</p>
+
       <!-- ================================================================ -->
       <h2 id="creating-webhooks">Creating Webhooks</h2>
 

package/src/agent/compaction.ts

@@ -35,19 +35,35 @@ export function compactMessages(
     contextWindow: maxTokens,
   });
 
+  // Check if first message is a summary (preserve it during truncation)
+  const hasSummary =
+    messages.length > 0 &&
+    messages[0].role === "user" &&
+    typeof messages[0].content !== "string" &&
+    Array.isArray(messages[0].content) &&
+    messages[0].content.some(
+      (b: any) =>
+        b.type === "text" &&
+        typeof b.text === "string" &&
+        b.text.includes("Previous conversation summary:")
+    );
+
   // Find the start index where cumulative remaining tokens fit under target
-  let startIdx = 0;
+  // Skip index 0 if it's a summary message — we want to keep it
+  let startIdx = hasSummary ? 1 : 0;
   while (startIdx < messages.length - 2 && tokens > target) {
     tokens -= costs[startIdx];
     startIdx++;
   }
 
-  // Ensure first message is from user (Claude API requirement)
+  // Ensure first kept message (after summary) is from user (Claude API requirement)
   while (startIdx < messages.length && messages[startIdx].role !== "user") {
     startIdx++;
   }
 
-  const compacted = messages.slice(startIdx);
-  logger.info("Compaction done", { remainingMessages: compacted.length });
+  const compacted = hasSummary
+    ? [messages[0], ...messages.slice(startIdx)]
+    : messages.slice(startIdx);
+  logger.info("Compaction done", { remainingMessages: compacted.length, preservedSummary: hasSummary });
   return compacted;
 }

package/src/agent/history.ts

@@ -14,13 +14,18 @@ export function recordMessage(
 ): void {
   try {
     const db = getDb();
+    // Ensure thread exists before inserting message
+    db.run(
+      "INSERT OR IGNORE INTO threads (id, title, channel, message_count, created_at, updated_at) VALUES (?, ?, ?, 0, datetime('now'), datetime('now'))",
+      [threadId, threadId, channel ?? "webchat"]
+    );
     db.run(
       "INSERT INTO conversation_messages (thread_id, role, content, channel, timestamp) VALUES (?, ?, ?, ?, datetime('now'))",
       [threadId, role, content, channel ?? null]
     );
     db.run(
-      "UPDATE threads SET message_count = message_count + 1, updated_at = datetime('now') WHERE id = ?",
-      [threadId]
+      "UPDATE threads SET message_count = message_count + 1, updated_at = datetime('now'), channel = COALESCE(channel, ?) WHERE id = ?",
+      [channel ?? "webchat", threadId]
     );
     db.run(
       "INSERT INTO conversation_search (content, thread_id, role) VALUES (?, ?, ?)",

package/src/agent/loop.ts

@@ -1,9 +1,10 @@
 import type { LlmProvider, LlmMessage, LlmContentBlock, LlmResponse } from "../llm/provider";
 import { getAllToolDefs } from "../tools/registry";
 import { executeTool } from "../tools/executor";
-import { appendMessage } from "./session";
+import { appendMessage, loadSession } from "./session";
 import { assembleContext } from "./context";
 import { compactMessages } from "./compaction";
+import { maybeCompactSession } from "./summarizer";
 import { getDb } from "../db/connection";
 import { logger } from "../util/logger";
 
@@ -38,6 +39,14 @@ function resolveOptions(memoriesOrOptions: string | AgentLoopOptions): AgentLoop
     : memoriesOrOptions;
 }
 
+/** Detect simple greetings/chat that don't need tool definitions in context. */
+function looksConversational(text: string): boolean {
+  const t = text.trim().toLowerCase();
+  if (t.split(/\s+/).length > 8) return false; // longer messages likely need tools
+  const greetings = /^(h(ello|i|ey|owdy|ola)|yo|sup|good\s*(morning|afternoon|evening|night)|what'?s\s*up|gm|thanks|thank\s*you|ok(ay)?|bye|see\s*ya|cool|nice|wow|lol|haha)\b/;
+  return greetings.test(t);
+}
+
 async function prepareLoop(
   llm: LlmProvider,
   sessionId: string,
@@ -67,23 +76,21 @@ async function prepareLoop(
     ? (memories ? `${memories}\n\nKnown context:\n${kgContext}` : `Known context:\n${kgContext}`)
     : memories;
 
-  // Assemble context
+  // Assemble context (uses static import — no dynamic import overhead)
   const ctx = options.systemPromptOverride
-    ? { system: options.systemPromptOverride, messages: [] as LlmMessage[] }
+    ? { system: options.systemPromptOverride, messages: loadSession(sessionId, 50) }
     : assembleContext(sessionId, 50, fullMemories);
 
-  if (options.systemPromptOverride) {
-    const { loadSession } = await import("./session");
-    ctx.messages = loadSession(sessionId, 50);
-  }
-
   const messages = compactMessages(ctx.messages, llm.contextWindow);
 
-  // Filter tools
+  // Filter tools — skip for simple conversational messages to reduce context
+  // for small models. Tools are still available on subsequent rounds.
   let tools = getAllToolDefs();
   if (options.allowedTools) {
     const allowed = new Set(options.allowedTools);
     tools = tools.filter((t) => allowed.has(t.name));
+  } else if (looksConversational(userMessage)) {
+    tools = [];
   }
 
   return { system: ctx.system, messages, tools };
@@ -121,21 +128,25 @@ async function executeToolBlocks(
   onToolStart?: (name: string, id: string) => void,
   onToolEnd?: (name: string, id: string) => void
 ): Promise<{ results: LlmContentBlock[]; count: number }> {
-  const results: LlmContentBlock[] = [];
-  let count = 0;
+  // Signal all tool starts immediately
   for (const block of blocks) {
-    count++;
     onToolStart?.(block.name, block.id);
+  }
+
+  // Execute all tools in parallel
+  const resultPromises = blocks.map(async (block) => {
     const result = await executeTool(block.name, block.id, block.input, allowedTools);
-    results.push({
-      type: "tool_result",
+    onToolEnd?.(block.name, block.id);
+    return {
+      type: "tool_result" as const,
       tool_use_id: result.tool_use_id,
       content: result.content,
       is_error: result.is_error,
-    });
-    onToolEnd?.(block.name, block.id);
-  }
-  return { results, count };
+    };
+  });
+
+  const results: LlmContentBlock[] = await Promise.all(resultPromises);
+  return { results, count: blocks.length };
 }
 
 function persistToolRound(
@@ -169,6 +180,23 @@ function finishLoop(sessionId: string, reply: string): void {
 
 const MAX_ROUNDS_FALLBACK = "I've completed several tool operations. Let me know if you need anything else.";
 
+// --- Post-loop summarization ---
+
+const compactionInProgress = new Set<string>();
+
+function triggerPostLoopCompaction(llm: LlmProvider, sessionId: string): void {
+  if (compactionInProgress.has(sessionId)) return;
+  compactionInProgress.add(sessionId);
+
+  maybeCompactSession(llm, sessionId)
+    .catch((err) => {
+      logger.error("Post-loop compaction failed", { sessionId, error: String(err) });
+    })
+    .finally(() => {
+      compactionInProgress.delete(sessionId);
+    });
+}
+
 // --- Public API ---
 
 export async function agentLoop(
@@ -217,6 +245,7 @@ export async function agentLoop(
         .map((b) => b.text ?? "")
         .join("\n") || "";
       finishLoop(sessionId, reply);
+      triggerPostLoopCompaction(llm, sessionId);
       return { reply, toolCalls: totalToolCalls };
     }
 
@@ -227,6 +256,7 @@ export async function agentLoop(
   }
 
   finishLoop(sessionId, MAX_ROUNDS_FALLBACK);
+  triggerPostLoopCompaction(llm, sessionId);
   return { reply: MAX_ROUNDS_FALLBACK, toolCalls: totalToolCalls };
 }
 
@@ -309,6 +339,7 @@ export async function agentLoopStream(
           .join("\n") || roundText;
         fullReply += reply;
         finishLoop(sessionId, fullReply);
+        triggerPostLoopCompaction(llm, sessionId);
         callbacks.onDone({ reply: fullReply, toolCalls: totalToolCalls });
         return;
       }
@@ -325,6 +356,7 @@ export async function agentLoopStream(
     }
 
     finishLoop(sessionId, MAX_ROUNDS_FALLBACK);
+    triggerPostLoopCompaction(llm, sessionId);
     callbacks.onDone({ reply: MAX_ROUNDS_FALLBACK, toolCalls: totalToolCalls });
   } catch (err: any) {
     callbacks.onError(err);

package/src/agent/prompts.ts

@@ -5,6 +5,8 @@ const DEFAULT_PERSONALITY = `You are Zubo, a personal AI agent. You are friendly
 
 ## How you behave
 
+**Be natural.** You are a real conversational partner. When the user greets you, greet them back warmly. When they chat casually, chat back. Not everything requires a tool call or an action — sometimes the right response is just a friendly reply.
+
 **Act first.** When the user asks you to do something, do it immediately. Don't describe what you could do — use your tools and make it happen. Don't ask for permission to do what the user just asked you to do (e.g. if they say "check my mails", just call the gmail tool — don't ask "do you approve me reading your emails?"). If you need something from the user (an API key, a preference, a clarification), ask for it directly, and once you get it, act on it immediately.
 
 **Be concise.** Answer in the fewest words that fully address the question. No filler, no preamble. Long explanations only when explicitly asked.

package/src/agent/session.ts

@@ -1,12 +1,16 @@
 import { join } from "path";
+import { randomBytes } from "crypto";
 import { paths } from "../config/paths";
-import { existsSync, appendFileSync, readFileSync, statSync, openSync, readSync, closeSync } from "fs";
+import { existsSync, appendFileSync, readFileSync, writeFileSync, statSync, openSync, readSync, closeSync, renameSync } from "fs";
+import { tmpdir } from "os";
 import type { LlmMessage } from "../llm/provider";
 
 export interface SessionMessage {
   role: "user" | "assistant";
   content: any;
   timestamp: string;
+  __summary?: true;
+  __summarizedCount?: number;
 }
 
 function sessionPath(sessionId: string): string {
@@ -90,13 +94,76 @@ export function loadSession(
   if (!existsSync(path)) return [];
 
   const recent = readTailLines(path, maxTurns);
+  if (recent.length === 0) return [];
 
-  return recent.map((line) => {
+  const messages = recent.map((line) => {
     const msg: SessionMessage = JSON.parse(line);
     return { role: msg.role, content: msg.content };
   });
+
+  // If the tail-read missed a summary at line 0, prepend it.
+  // After summarization the file starts with a summary message — we must
+  // always include it or the whole point of summarization is lost.
+  const firstReturned = recent[0];
+  if (!firstReturned.includes('"__summary":true')) {
+    // We might have tail-read past the summary. Check line 0.
+    try {
+      const fd = openSync(path, "r");
+      try {
+        const buf = Buffer.alloc(4096);
+        const bytesRead = readSync(fd, buf, 0, 4096, 0);
+        const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n")[0];
+        if (firstLine && firstLine.includes('"__summary":true')) {
+          const summaryMsg: SessionMessage = JSON.parse(firstLine);
+          messages.unshift({ role: summaryMsg.role, content: summaryMsg.content });
+        }
+      } finally {
+        closeSync(fd);
+      }
+    } catch {
+      // If reading line 0 fails, proceed without it
+    }
+  }
+
+  return messages;
 }
 
 export function sessionExists(sessionId: string): boolean {
   return existsSync(sessionPath(sessionId));
 }
+
+/**
+ * Read the entire session file (not tail-limited).
+ * Used by the summarizer to make decisions about compaction.
+ */
+export function loadSessionFull(sessionId: string): SessionMessage[] {
+  const path = sessionPath(sessionId);
+  if (!existsSync(path)) return [];
+
+  const raw = readFileSync(path, "utf-8").trim();
+  if (!raw) return [];
+
+  const messages: SessionMessage[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line) continue;
+    try {
+      messages.push(JSON.parse(line) as SessionMessage);
+    } catch {
+      // Skip corrupted lines — don't crash summarization
+    }
+  }
+  return messages;
+}
+
+/**
+ * Atomically rewrite a session file with new messages.
+ * Writes to a temp file first, then renames (atomic on POSIX).
+ */
+export function rewriteSession(sessionId: string, messages: SessionMessage[]): void {
+  const path = sessionPath(sessionId);
+  const tmpPath = join(tmpdir(), `zubo-session-${sessionId}-${Date.now()}-${randomBytes(4).toString("hex")}.tmp`);
+
+  const data = messages.map((m) => JSON.stringify(m)).join("\n") + "\n";
+  writeFileSync(tmpPath, data);
+  renameSync(tmpPath, path);
+}