stagent 0.5.0 → 0.6.0

package/src/lib/channels/telegram-adapter.ts

@@ -0,0 +1,218 @@
+import type { ChannelAdapter, ChannelMessage, ChannelDeliveryResult, InboundMessage } from "./types";
+
+/**
+ * Escape special characters for Telegram MarkdownV2 format.
+ */
+function escapeMarkdownV2(text: string): string {
+  return text.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, "\\$&");
+}
+
+/**
+ * Convert basic Markdown to Telegram MarkdownV2.
+ * We escape special chars first, then re-apply bold/code formatting.
+ */
+function toTelegramMarkdownV2(subject: string, body: string): string {
+  const escapedSubject = escapeMarkdownV2(subject);
+  const escapedBody = escapeMarkdownV2(body);
+  return `*${escapedSubject}*\n\n${escapedBody}`;
+}
+
+export const telegramAdapter: ChannelAdapter = {
+  channelType: "telegram",
+
+  async send(message: ChannelMessage, config: Record<string, unknown>): Promise<ChannelDeliveryResult> {
+    const botToken = config.botToken as string;
+    const chatId = config.chatId as string;
+
+    if (!botToken || !chatId) {
+      return { success: false, error: "Missing botToken or chatId in config" };
+    }
+
+    const text = message.format === "markdown"
+      ? toTelegramMarkdownV2(message.subject, message.body)
+      : `${message.subject}\n\n${message.body}`;
+
+    const parseMode = message.format === "markdown" ? "MarkdownV2" : undefined;
+
+    try {
+      const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text,
+          ...(parseMode ? { parse_mode: parseMode } : {}),
+        }),
+      });
+
+      const data = await res.json() as { ok: boolean; result?: { message_id: number }; description?: string };
+
+      if (!data.ok) {
+        return { success: false, error: data.description ?? `Telegram API error (${res.status})` };
+      }
+
+      return { success: true, externalId: String(data.result?.message_id) };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+
+  async testConnection(config: Record<string, unknown>): Promise<{ ok: boolean; error?: string }> {
+    const botToken = config.botToken as string;
+    const chatId = config.chatId as string;
+    if (!botToken || !chatId) {
+      return { ok: false, error: "Missing botToken or chatId" };
+    }
+
+    try {
+      const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text: "Stagent channel test \\- connection OK",
+          parse_mode: "MarkdownV2",
+        }),
+      });
+      const data = await res.json() as { ok: boolean; description?: string };
+
+      if (!data.ok) {
+        return { ok: false, error: data.description ?? "Telegram sendMessage failed" };
+      }
+
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+
+  // ── Bidirectional support ────────────────────────────────────────────
+
+  parseInbound(rawBody: unknown): InboundMessage | null {
+    const update = rawBody as TelegramUpdate;
+    const msg = update?.message;
+    if (!msg?.text) return null;
+
+    return {
+      text: msg.text,
+      senderName: msg.from?.first_name
+        ? `${msg.from.first_name}${msg.from.last_name ? ` ${msg.from.last_name}` : ""}`
+        : undefined,
+      senderId: msg.from?.id ? String(msg.from.id) : undefined,
+      externalThreadId: String(msg.chat.id),
+      externalMessageId: String(msg.message_id),
+      isBot: msg.from?.is_bot ?? false,
+      raw: rawBody,
+    };
+  },
+
+  async sendReply(
+    message: ChannelMessage,
+    config: Record<string, unknown>,
+    threadId?: string
+  ): Promise<ChannelDeliveryResult> {
+    const botToken = config.botToken as string;
+    const chatId = threadId ?? (config.chatId as string);
+
+    if (!botToken || !chatId) {
+      return { success: false, error: "Missing botToken or chatId for reply" };
+    }
+
+    // For replies, send body directly (subject is empty in gateway context)
+    const text = message.body || message.subject;
+    if (!text) {
+      return { success: false, error: "Empty message body" };
+    }
+
+    try {
+      const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text,
+          // Skip MarkdownV2 for replies — raw text avoids escape issues with agent output
+        }),
+      });
+
+      const data = await res.json() as { ok: boolean; result?: { message_id: number }; description?: string };
+
+      if (!data.ok) {
+        return { success: false, error: data.description ?? `Telegram API error (${res.status})` };
+      }
+
+      return { success: true, externalId: String(data.result?.message_id) };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+};
+
+// ── Telegram types (minimal subset) ────────────────────────────────────
+
+interface TelegramUpdate {
+  update_id: number;
+  message?: {
+    message_id: number;
+    from?: {
+      id: number;
+      is_bot: boolean;
+      first_name: string;
+      last_name?: string;
+      username?: string;
+    };
+    chat: {
+      id: number;
+      type: string;
+    };
+    date: number;
+    text?: string;
+  };
+}
+
+/**
+ * Register a Telegram webhook for bidirectional mode.
+ * Call this when a channel config is set to direction="bidirectional".
+ */
+export async function registerTelegramWebhook(
+  botToken: string,
+  webhookUrl: string
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    const url = `https://api.telegram.org/bot${botToken}/setWebhook`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: webhookUrl }),
+    });
+    const data = await res.json() as { ok: boolean; description?: string };
+    if (!data.ok) {
+      return { ok: false, error: data.description ?? "setWebhook failed" };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Remove a Telegram webhook (revert to outbound-only).
+ */
+export async function removeTelegramWebhook(
+  botToken: string
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    const url = `https://api.telegram.org/bot${botToken}/deleteWebhook`;
+    const res = await fetch(url, { method: "POST" });
+    const data = await res.json() as { ok: boolean; description?: string };
+    if (!data.ok) {
+      return { ok: false, error: data.description ?? "deleteWebhook failed" };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/lib/channels/types.ts

@@ -0,0 +1,43 @@
+/**
+ * Channel adapter types for multi-channel delivery and bidirectional chat.
+ */
+
+export interface ChannelAdapter {
+  channelType: string;
+  send(message: ChannelMessage, config: Record<string, unknown>): Promise<ChannelDeliveryResult>;
+  testConnection(config: Record<string, unknown>): Promise<{ ok: boolean; error?: string }>;
+
+  // ── Bidirectional support (optional) ────────────────────────────────
+  /** Parse an inbound webhook payload into a normalized message. */
+  parseInbound?(rawBody: unknown, headers: Record<string, string>): InboundMessage | null;
+  /** Verify webhook signature authenticity. */
+  verifySignature?(rawBody: string, headers: Record<string, string>, config: Record<string, unknown>): boolean;
+  /** Send a reply in-thread (distinct from fire-and-forget send). */
+  sendReply?(message: ChannelMessage, config: Record<string, unknown>, threadId?: string): Promise<ChannelDeliveryResult>;
+}
+
+export interface ChannelMessage {
+  subject: string;
+  body: string;
+  format: "text" | "markdown";
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChannelDeliveryResult {
+  success: boolean;
+  channelId?: string;
+  externalId?: string;
+  error?: string;
+}
+
+/** Normalized inbound message from any channel. */
+export interface InboundMessage {
+  text: string;
+  senderName?: string;
+  senderId?: string;
+  externalThreadId?: string;
+  externalMessageId?: string;
+  isBot?: boolean;
+  /** Raw channel-specific payload for adapter-level access. */
+  raw?: unknown;
+}

package/src/lib/channels/webhook-adapter.ts

@@ -0,0 +1,74 @@
+import type { ChannelAdapter, ChannelMessage, ChannelDeliveryResult } from "./types";
+
+export const webhookAdapter: ChannelAdapter = {
+  channelType: "webhook",
+
+  async send(message: ChannelMessage, config: Record<string, unknown>): Promise<ChannelDeliveryResult> {
+    const url = config.url as string;
+    if (!url) {
+      return { success: false, error: "Missing url in config" };
+    }
+
+    const customHeaders = (config.headers ?? {}) as Record<string, string>;
+
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...customHeaders,
+        },
+        body: JSON.stringify({
+          subject: message.subject,
+          body: message.body,
+          format: message.format,
+          metadata: message.metadata ?? {},
+          timestamp: new Date().toISOString(),
+          source: "stagent",
+        }),
+      });
+
+      if (!res.ok) {
+        const body = await res.text();
+        return { success: false, error: `Webhook returned ${res.status}: ${body.slice(0, 200)}` };
+      }
+
+      return { success: true };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+
+  async testConnection(config: Record<string, unknown>): Promise<{ ok: boolean; error?: string }> {
+    const url = config.url as string;
+    if (!url) {
+      return { ok: false, error: "Missing url" };
+    }
+
+    const customHeaders = (config.headers ?? {}) as Record<string, string>;
+
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...customHeaders,
+        },
+        body: JSON.stringify({
+          test: true,
+          source: "stagent",
+          timestamp: new Date().toISOString(),
+        }),
+      });
+
+      if (!res.ok) {
+        const body = await res.text();
+        return { ok: false, error: `Webhook returned ${res.status}: ${body.slice(0, 200)}` };
+      }
+
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+};

package/src/lib/chat/context-builder.ts

@@ -2,6 +2,7 @@ import { db } from "@/lib/db";
 import { projects, tasks, workflows, documents, schedules } from "@/lib/db/schema";
 import { eq, desc, and } from "drizzle-orm";
 import { getMessages } from "@/lib/data/chat";
+import { getProfile } from "@/lib/agents/profiles/registry";
 import { STAGENT_SYSTEM_PROMPT } from "./system-prompt";
 import type { WorkspaceContext } from "@/lib/environment/workspace-context";
 
@@ -254,8 +255,27 @@ async function buildTier3(mentions: MentionReference[]): Promise<string> {
         break;
       }
       case "profile": {
-        parts.push(`\n### Profile: ${mention.label}`);
-        parts.push(`Profile ID: ${mention.entityId}`);
+        const profile = getProfile(mention.entityId);
+        if (profile) {
+          parts.push(`\n### Agent Profile: ${profile.name}`);
+          parts.push(`Domain: ${profile.domain}`);
+          if (profile.description) parts.push(`Description: ${profile.description}`);
+          if (profile.tags?.length) parts.push(`Tags: ${profile.tags.join(", ")}`);
+          if (profile.allowedTools?.length) parts.push(`Allowed Tools: ${profile.allowedTools.join(", ")}`);
+          if (profile.maxTurns) parts.push(`Max Turns: ${profile.maxTurns}`);
+          if (profile.outputFormat) parts.push(`Output Format: ${profile.outputFormat}`);
+          if (profile.skillMd) {
+            if (profile.skillMd.length <= 4000) {
+              parts.push(`\nProfile Instructions (SKILL.md):\n${profile.skillMd}`);
+            } else {
+              parts.push(`\nProfile Instructions (SKILL.md, preview):\n${profile.skillMd.slice(0, 3000)}`);
+              parts.push(`\n...(truncated — use the get_profile tool with profileId "${profile.id}" for full content)`);
+            }
+          }
+        } else {
+          parts.push(`\n### Profile: ${mention.label}`);
+          parts.push(`Profile ID: ${mention.entityId} (not found in registry)`);
+        }
         break;
       }
     }

package/src/lib/chat/engine.ts

@@ -43,8 +43,12 @@ import { createStagentMcpServer } from "./stagent-tools";
 import {
   getBrowserMcpServers,
   getBrowserAllowedToolPatterns,
+  getExternalMcpServers,
+  getExternalAllowedToolPatterns,
   isBrowserTool,
   isBrowserReadOnly,
+  isExaTool,
+  isExaReadOnly,
 } from "@/lib/agents/browser-mcp";
 
 // ── Streaming input wrapper (required for MCP tools) ─────────────────
@@ -58,6 +62,46 @@ async function* generatePrompt(text: string) {
   };
 }
 
+// ── Error diagnostics ──────────────────────────────────────────────────
+
+/**
+ * Translate a raw SDK / process error + stderr into an actionable message.
+ * The Claude Code subprocess can exit with code 1 for many reasons;
+ * stderr output usually reveals the real cause.
+ */
+function diagnoseProcessError(rawMessage: string, stderr: string): string {
+  const combined = `${rawMessage}\n${stderr}`.toLowerCase();
+
+  if (combined.includes("authentication") || combined.includes("not logged in") || combined.includes("oauth") || combined.includes("token expired")) {
+    return "Authentication failed — please check your API key or run `claude login` to refresh OAuth tokens. (Settings → Authentication)";
+  }
+  if (combined.includes("rate limit") || combined.includes("rate_limit") || combined.includes("429")) {
+    return "Rate limit reached — please wait a moment before sending another message.";
+  }
+  if (combined.includes("billing") || combined.includes("insufficient") || combined.includes("payment")) {
+    return "Billing issue — your account may need a payment method or has exceeded its budget.";
+  }
+  if (combined.includes("enoent") || combined.includes("not found") || combined.includes("command not found")) {
+    return "Claude Code CLI not found — please install it with `npm install -g @anthropic-ai/claude-code`.";
+  }
+  if (combined.includes("model") && (combined.includes("not available") || combined.includes("invalid"))) {
+    return "The selected model is not available for your account. Try switching to a different model.";
+  }
+
+  // Generic process exit — append stderr hint if available
+  if (/process exited with code \d+/i.test(rawMessage)) {
+    if (stderr) {
+      // Extract last meaningful line from stderr
+      const lines = stderr.split("\n").filter((l) => l.trim());
+      const lastLine = lines[lines.length - 1] ?? "";
+      return `${rawMessage}${lastLine ? ` — ${lastLine}` : ""}. Check Settings → Authentication if this persists.`;
+    }
+    return `${rawMessage}. This usually means an authentication or configuration issue — check Settings → Authentication.`;
+  }
+
+  return rawMessage;
+}
+
 // ── Public API ─────────────────────────────────────────────────────────
 
 /**
@@ -87,6 +131,13 @@ export async function* sendMessage(
     return;
   }
 
+  // Route to Ollama for local models
+  if (conversation.runtimeId === "ollama") {
+    const { sendOllamaMessage } = await import("./ollama-engine");
+    yield* sendOllamaMessage(conversationId, userContent, signal);
+    return;
+  }
+
   const runtimeId = conversation.runtimeId;
   const providerId = getProviderForRuntime(runtimeId);
 
@@ -181,6 +232,8 @@ export async function* sendMessage(
   const startedAt = new Date();
   let usage: UsageSnapshot = {};
   let fullText = "";
+  // Capture stderr for diagnostics when the Claude Code process fails
+  const stderrChunks: string[] = [];
 
   try {
     const authEnv = await getAuthEnv();
@@ -206,9 +259,14 @@ export async function* sendMessage(
     const maxTurnsSetting = await getSetting(SETTINGS_KEYS.MAX_TURNS);
     const maxTurns = maxTurnsSetting ? parseInt(maxTurnsSetting, 10) || 30 : 30;
 
-    // Merge browser MCP servers when enabled in settings
-    const browserServers = await getBrowserMcpServers();
-    const browserToolPatterns = await getBrowserAllowedToolPatterns();
+    // Merge browser + external MCP servers when enabled in settings
+    const [browserServers, browserToolPatterns, externalServers, externalToolPatterns] =
+      await Promise.all([
+        getBrowserMcpServers(),
+        getBrowserAllowedToolPatterns(),
+        getExternalMcpServers(),
+        getExternalAllowedToolPatterns(),
+      ]);
 
     const response = query({
       prompt: generatePrompt(fullPrompt),
@@ -219,8 +277,13 @@ export async function* sendMessage(
         includePartialMessages: true,
         cwd: workspace.cwd,
         env: buildClaudeSdkEnv(authEnv),
-        mcpServers: { stagent: stagentServer, ...browserServers },
-        allowedTools: ["mcp__stagent__*", ...browserToolPatterns],
+        stderr: (data: string) => {
+          stderrChunks.push(data);
+          // Keep only last 50 chunks to avoid unbounded memory
+          if (stderrChunks.length > 50) stderrChunks.shift();
+        },
+        mcpServers: { stagent: stagentServer, ...browserServers, ...externalServers },
+        allowedTools: ["mcp__stagent__*", ...browserToolPatterns, ...externalToolPatterns],
         // @ts-expect-error Agent SDK canUseTool types are incomplete — our async handler is compatible at runtime
         canUseTool: async (
           toolName: string,
@@ -248,6 +311,17 @@ export async function* sendMessage(
             return { behavior: "allow", updatedInput: input };
           }
 
+          // Exa tools: auto-allow read-only (all Exa tools are read-only)
+          if (isExaTool(toolName) && isExaReadOnly(toolName)) {
+            const shortName = toolName.replace("mcp__exa__", "").replace(/_/g, " ");
+            emitSideChannelEvent(conversationId, {
+              type: "status",
+              phase: "tool_use",
+              message: `Exa: ${shortName}...`,
+            });
+            return { behavior: "allow", updatedInput: input };
+          }
+
           // Browser tools: auto-allow read-only, gate mutations
           if (isBrowserTool(toolName)) {
             if (isBrowserReadOnly(toolName)) {
@@ -419,19 +493,23 @@ export async function* sendMessage(
             }
           }
         }
-      } else if (raw.type === "result" && "result" in raw) {
+      } else if (raw.type === "result") {
         if (raw.is_error && raw.subtype !== "error_max_turns") {
-          throw new Error(
-            typeof raw.result === "string"
-              ? raw.result
-              : "Agent SDK returned an error"
-          );
+          // SDKResultError has `errors: string[]`; SDKResultSuccess has `result: string`
+          const errors = (raw as Record<string, unknown>).errors as string[] | undefined;
+          const result = (raw as Record<string, unknown>).result as string | undefined;
+          const errorDetail = errors?.length
+            ? errors.join("; ")
+            : typeof result === "string"
+              ? result
+              : "Agent SDK returned an error";
+          throw new Error(errorDetail);
         }
         // Only emit result text as fallback when streaming didn't deliver content.
         // When deltas were active, fullText is already complete — re-emitting
         // the result would duplicate the entire response.
         if (!hasStreamedDeltas || !fullText) {
-          const result = raw.result;
+          const result = (raw as Record<string, unknown>).result;
           if (typeof result === "string" && result.length > 0) {
             if (result !== fullText) {
               const remainder = result.startsWith(fullText)
@@ -502,9 +580,13 @@ export async function* sendMessage(
       quickAccess,
     };
   } catch (error) {
-    const errorMessage =
+    const rawMessage =
       error instanceof Error ? error.message : "Unknown error";
 
+    // Enrich the error with stderr diagnostics when available
+    const stderrTail = stderrChunks.join("").trim();
+    const errorMessage = diagnoseProcessError(rawMessage, stderrTail);
+
     if (fullText && fullText.length > 50) {
       // Substantial content was already streamed — complete gracefully with warning
       const warning = `\n\n---\n\n*Response may be incomplete: ${errorMessage}*`;