stagent 0.5.0 → 0.6.0

package/src/lib/chat/ollama-engine.ts

@@ -0,0 +1,198 @@
+/**
+ * Ollama chat engine — streams messages via the Ollama /api/chat endpoint.
+ *
+ * Follows the same ChatStreamEvent protocol as the main engine
+ * so the chat UI can render Ollama responses identically.
+ */
+
+import { db } from "@/lib/db";
+import { chatMessages, projects } from "@/lib/db/schema";
+import { eq } from "drizzle-orm";
+import { getSetting } from "@/lib/settings/helpers";
+import { SETTINGS_KEYS } from "@/lib/constants/settings";
+import {
+  getConversation,
+  addMessage,
+  updateMessageStatus,
+  updateMessageContent,
+} from "@/lib/data/chat";
+import { buildChatContext } from "./context-builder";
+import { getWorkspaceContext } from "@/lib/environment/workspace-context";
+import type { ChatStreamEvent } from "./types";
+
+/**
+ * Send a user message to Ollama and stream the response.
+ */
+export async function* sendOllamaMessage(
+  conversationId: string,
+  userContent: string,
+  signal?: AbortSignal
+): AsyncGenerator<ChatStreamEvent> {
+  const conversation = await getConversation(conversationId);
+  if (!conversation) {
+    yield { type: "error", message: "Conversation not found" };
+    return;
+  }
+
+  yield { type: "status", phase: "preparing", message: "Connecting to Ollama..." };
+
+  // Resolve Ollama base URL and model
+  const baseUrl =
+    (await getSetting(SETTINGS_KEYS.OLLAMA_BASE_URL)) || "http://localhost:11434";
+  const modelId =
+    conversation.modelId?.replace(/^ollama:/, "") ||
+    (await getSetting(SETTINGS_KEYS.OLLAMA_DEFAULT_MODEL)) ||
+    "llama3.2";
+
+  // Build context
+  let projectName: string | null = null;
+  let projectCwd: string | null = null;
+  if (conversation.projectId) {
+    const project = db
+      .select()
+      .from(projects)
+      .where(eq(projects.id, conversation.projectId))
+      .get();
+    if (project) {
+      projectName = project.name;
+      projectCwd = project.workingDirectory ?? null;
+    }
+  }
+
+  const workspace = getWorkspaceContext();
+  if (projectCwd) workspace.cwd = projectCwd;
+
+  const context = await buildChatContext({
+    conversationId,
+    projectId: conversation.projectId,
+    projectName,
+    workspace,
+  });
+
+  // Persist user message
+  await addMessage({
+    conversationId,
+    role: "user",
+    content: userContent,
+    status: "complete",
+  });
+
+  // Create assistant message placeholder
+  const assistantMsg = await addMessage({
+    conversationId,
+    role: "assistant",
+    content: "",
+    status: "streaming",
+  });
+
+  // Build message history for Ollama
+  const history = db
+    .select()
+    .from(chatMessages)
+    .where(eq(chatMessages.conversationId, conversationId))
+    .orderBy(chatMessages.createdAt)
+    .all();
+
+  const messages = [
+    // System prompt from context
+    ...(context.systemPrompt
+      ? [{ role: "system" as const, content: context.systemPrompt }]
+      : []),
+    // Conversation history (exclude the placeholder assistant msg)
+    ...history
+      .filter((m) => m.id !== assistantMsg.id && m.content)
+      .map((m) => ({
+        role: m.role as "user" | "assistant" | "system",
+        content: m.content!,
+      })),
+  ];
+
+  // Stream from Ollama
+  let accumulated = "";
+  try {
+    const response = await fetch(`${baseUrl}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: modelId,
+        messages,
+        stream: true,
+      }),
+      signal,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "Unknown error");
+      yield { type: "error", message: `Ollama error (${response.status}): ${errorText}` };
+      await updateMessageStatus(assistantMsg.id, "complete");
+      return;
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) {
+      yield { type: "error", message: "No response stream from Ollama" };
+      await updateMessageStatus(assistantMsg.id, "complete");
+      return;
+    }
+
+    yield { type: "status", phase: "streaming", message: "Streaming response..." };
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const parsed = JSON.parse(line);
+          const delta = parsed.message?.content ?? "";
+          if (delta) {
+            accumulated += delta;
+            yield { type: "delta", content: delta };
+          }
+          if (parsed.done) break;
+        } catch {
+          // Skip malformed lines
+        }
+      }
+    }
+
+    // Process any remaining buffer
+    if (buffer.trim()) {
+      try {
+        const parsed = JSON.parse(buffer);
+        const delta = parsed.message?.content ?? "";
+        if (delta) {
+          accumulated += delta;
+          yield { type: "delta", content: delta };
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    // Persist the complete response
+    await updateMessageContent(assistantMsg.id, accumulated);
+    await updateMessageStatus(assistantMsg.id, "complete");
+
+    yield { type: "done", messageId: assistantMsg.id, quickAccess: [] };
+  } catch (err) {
+    if (signal?.aborted) {
+      yield { type: "error", message: "Request cancelled" };
+    } else {
+      const msg = err instanceof Error ? err.message : "Ollama streaming failed";
+      yield { type: "error", message: msg };
+    }
+    if (accumulated) {
+      await updateMessageContent(assistantMsg.id, accumulated);
+    }
+    await updateMessageStatus(assistantMsg.id, "complete");
+  }
+}

package/src/lib/chat/stagent-tools.ts

@@ -1,5 +1,13 @@
-import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { tool as sdkTool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { type ToolContext } from "./tools/helpers";
+import {
+  type ToolDefinition,
+  type ToolResult,
+  toAnthropicToolDef,
+  toOpenAIFunctionDef,
+  type AnthropicToolDef,
+  type OpenAIFunctionDef,
+} from "./tool-registry";
 import { projectTools } from "./tools/project-tools";
 import { taskTools } from "./tools/task-tools";
 import { workflowTools } from "./tools/workflow-tools";
@@ -10,6 +18,98 @@ import { profileTools } from "./tools/profile-tools";
 import { usageTools } from "./tools/usage-tools";
 import { settingsTools } from "./tools/settings-tools";
 import { chatHistoryTools } from "./tools/chat-history-tools";
+import { handoffTools } from "./tools/handoff-tools";
+
+// ── Tool server types ────────────────────────────────────────────────
+
+export interface ProviderToolKit {
+  tools: AnthropicToolDef[] | OpenAIFunctionDef[];
+  /** Execute a tool handler by name. Throws if tool not found. */
+  executeHandler(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+
+export interface ToolServer {
+  /** Backward-compatible SDK MCP server for the chat engine. */
+  asMcpServer(): ReturnType<typeof createSdkMcpServer>;
+  /** Provider-formatted tool arrays + handler lookup for direct API runtimes. */
+  forProvider(provider: "anthropic" | "openai"): ProviderToolKit;
+  /** Raw tool definitions for inspection / testing. */
+  readonly definitions: ToolDefinition[];
+}
+
+// ── Factory ──────────────────────────────────────────────────────────
+
+function collectAllTools(ctx: ToolContext): ToolDefinition[] {
+  return [
+    ...projectTools(ctx),
+    ...taskTools(ctx),
+    ...workflowTools(ctx),
+    ...scheduleTools(ctx),
+    ...documentTools(ctx),
+    ...notificationTools(ctx),
+    ...profileTools(ctx),
+    ...usageTools(ctx),
+    ...settingsTools(ctx),
+    ...chatHistoryTools(ctx),
+    ...handoffTools(ctx),
+  ];
+}
+
+/**
+ * Create a tool server that supports both SDK MCP mode and direct API mode.
+ *
+ * - `.asMcpServer()` re-wraps definitions into SDK `tool()` calls for
+ *   backward compatibility with the chat engine.
+ * - `.forProvider("anthropic" | "openai")` returns provider-formatted
+ *   tool definitions + a handler lookup for direct API runtimes.
+ */
+export function createToolServer(
+  projectId?: string | null,
+  onToolResult?: (toolName: string, result: unknown) => void,
+): ToolServer {
+  const ctx: ToolContext = { projectId, onToolResult };
+  const allTools = collectAllTools(ctx);
+
+  // Handler lookup map (built once, shared across modes)
+  const handlerMap = new Map<string, ToolDefinition["handler"]>(
+    allTools.map((t) => [t.name, t.handler]),
+  );
+
+  async function executeHandler(
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<ToolResult> {
+    const handler = handlerMap.get(name);
+    if (!handler) throw new Error(`Unknown tool: ${name}`);
+    return handler(args);
+  }
+
+  return {
+    asMcpServer() {
+      // Re-wrap ToolDefinitions into SDK tool() format
+      const sdkTools = allTools.map((def) =>
+        sdkTool(def.name, def.description, def.zodShape, def.handler),
+      );
+      return createSdkMcpServer({
+        name: "stagent",
+        version: "1.0.0",
+        tools: sdkTools,
+      });
+    },
+
+    forProvider(provider) {
+      const tools =
+        provider === "anthropic"
+          ? allTools.map(toAnthropicToolDef)
+          : allTools.map(toOpenAIFunctionDef);
+      return { tools, executeHandler };
+    },
+
+    definitions: allTools,
+  };
+}
+
+// ── Backward-compatible export ───────────────────────────────────────
 
 /**
  * Create an in-process MCP server exposing all Stagent tools.
@@ -17,27 +117,13 @@ import { chatHistoryTools } from "./tools/chat-history-tools";
  * `onToolResult` is called after each successful CRUD operation with the
  * tool name and returned entity data — used by the entity detector to
  * generate deterministic Quick Access navigation links.
+ *
+ * @deprecated Use `createToolServer()` for new code. This wrapper exists
+ *   for backward compatibility with the chat engine.
  */
 export function createStagentMcpServer(
   projectId?: string | null,
-  onToolResult?: (toolName: string, result: unknown) => void
+  onToolResult?: (toolName: string, result: unknown) => void,
 ) {
-  const ctx: ToolContext = { projectId, onToolResult };
-
-  return createSdkMcpServer({
-    name: "stagent",
-    version: "1.0.0",
-    tools: [
-      ...projectTools(ctx),
-      ...taskTools(ctx),
-      ...workflowTools(ctx),
-      ...scheduleTools(ctx),
-      ...documentTools(ctx),
-      ...notificationTools(ctx),
-      ...profileTools(ctx),
-      ...usageTools(ctx),
-      ...settingsTools(ctx),
-      ...chatHistoryTools(ctx),
-    ],
-  });
+  return createToolServer(projectId, onToolResult).asMcpServer();
 }

package/src/lib/chat/tool-catalog.ts

@@ -12,6 +12,7 @@ import {
   Globe,
   Sun,
   CheckCheck,
+  Sparkles,
 } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 
@@ -25,6 +26,7 @@ export type ToolGroup =
   | "Documents"
   | "Notifications"
   | "Profiles"
+  | "Skills"
   | "Usage"
   | "Settings"
   | "Chat"
@@ -54,6 +56,7 @@ export const TOOL_GROUP_ICONS: Record<ToolGroup, LucideIcon> = {
   Documents: FileText,
   Notifications: Bell,
   Profiles: Bot,
+  Skills: Sparkles,
   Usage: Wallet,
   Settings: Settings,
   Chat: MessageSquare,
@@ -69,6 +72,7 @@ export const TOOL_GROUP_ORDER: ToolGroup[] = [
   "Documents",
   "Schedules",
   "Profiles",
+  "Skills",
   "Browser",
   "Notifications",
   "Chat",
@@ -174,6 +178,26 @@ export function getToolCatalog(opts?: { includeBrowser?: boolean }): ToolCatalog
   return cachedCatalog;
 }
 
+/**
+ * Get the tool catalog with dynamic project skills appended.
+ * NOT cached at module level because it depends on the active project.
+ */
+export function getToolCatalogWithSkills(opts?: {
+  includeBrowser?: boolean;
+  projectProfiles?: Array<{ id: string; name: string; description: string }>;
+}): ToolCatalogEntry[] {
+  const base = getToolCatalog(opts);
+  if (!opts?.projectProfiles?.length) return base;
+
+  const skillEntries: ToolCatalogEntry[] = opts.projectProfiles.map((p) => ({
+    name: p.id,
+    description: p.description,
+    group: "Skills" as ToolGroup,
+  }));
+
+  return [...base, ...skillEntries];
+}
+
 /** Group catalog entries by their ToolGroup */
 export function groupToolCatalog(entries: ToolCatalogEntry[]): Record<string, ToolCatalogEntry[]> {
   const groups: Record<string, ToolCatalogEntry[]> = {};

package/src/lib/chat/tool-registry.ts

@@ -0,0 +1,90 @@
+/**
+ * Provider-agnostic tool definition registry.
+ *
+ * `defineTool()` replaces the SDK's `tool()` so that tool definitions
+ * are decoupled from any specific provider SDK. The resulting
+ * `ToolDefinition` objects carry both the original Zod schema (for
+ * backward-compatible SDK wrapping) and a pre-computed JSON Schema
+ * (for direct API runtimes).
+ */
+
+import { z } from "zod";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+/** MCP-compatible tool result (matches ok/err helper output). */
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}
+
+/** Provider-neutral tool definition (type-erased for storage in arrays). */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  /** Original Zod shape — retained for SDK bridge wrapping. */
+  zodShape: z.ZodRawShape;
+  /** Pre-computed JSON Schema (Draft 2020-12) for direct API runtimes. */
+  inputSchema: Record<string, unknown>;
+  /** Async handler that receives validated args and returns MCP content. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handler: (args: any) => Promise<ToolResult>;
+}
+
+// ── Factory ──────────────────────────────────────────────────────────
+
+/**
+ * Define a provider-agnostic tool.
+ *
+ * Signature mirrors the SDK's `tool(name, description, zodShape, handler)`
+ * so that converting existing tool files is a simple import swap.
+ */
+export function defineTool<T extends z.ZodRawShape>(
+  name: string,
+  description: string,
+  inputShape: T,
+  handler: (args: z.infer<z.ZodObject<T>>) => Promise<ToolResult>,
+): ToolDefinition {
+  const zodObject = z.object(inputShape);
+  const inputSchema = z.toJSONSchema(zodObject) as Record<string, unknown>;
+
+  return { name, description, zodShape: inputShape, inputSchema, handler };
+}
+
+// ── Provider formatters ──────────────────────────────────────────────
+
+/** Format for Anthropic Messages API `tools` parameter. */
+export interface AnthropicToolDef {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export function toAnthropicToolDef(def: ToolDefinition): AnthropicToolDef {
+  return {
+    name: def.name,
+    description: def.description,
+    input_schema: def.inputSchema,
+  };
+}
+
+/** Format for OpenAI Responses API function tool. */
+export interface OpenAIFunctionDef {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+export function toOpenAIFunctionDef(def: ToolDefinition): OpenAIFunctionDef {
+  return {
+    type: "function",
+    function: {
+      name: def.name,
+      description: def.description,
+      parameters: def.inputSchema,
+    },
+  };
+}

package/src/lib/chat/tools/chat-history-tools.ts

@@ -1,4 +1,4 @@
-import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { ok, err, type ToolContext } from "./helpers";
 import {
@@ -11,7 +11,7 @@ import {
 export function chatHistoryTools(ctx: ToolContext) {
   return [
     // ── list_conversations ──────────────────────────────────────────
-    tool(
+    defineTool(
       "list_conversations",
       "List recent chat conversations. Use to find past discussions, filter by project or status, or search titles.",
       {
@@ -59,7 +59,7 @@ export function chatHistoryTools(ctx: ToolContext) {
     ),
 
     // ── get_conversation_messages ────────────────────────────────────
-    tool(
+    defineTool(
       "get_conversation_messages",
       "Get message history from a past conversation. Use to recall what was discussed, review decisions, or find specific information from a prior chat.",
       {
@@ -119,7 +119,7 @@ export function chatHistoryTools(ctx: ToolContext) {
     ),
 
     // ── search_messages ─────────────────────────────────────────────
-    tool(
+    defineTool(
       "search_messages",
       "Search across all conversations for specific content. Use when the user asks about prior discussions, decisions, or any topic from past chats.",
       {

package/src/lib/chat/tools/document-tools.ts

@@ -1,4 +1,4 @@
-import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { db } from "@/lib/db";
 import { documents } from "@/lib/db/schema";
@@ -44,7 +44,7 @@ function resolveMimeType(filename: string): string {
 
 export function documentTools(ctx: ToolContext) {
   return [
-    tool(
+    defineTool(
       "list_documents",
       "List documents, optionally filtered by project, task, direction, or status.",
       {
@@ -97,7 +97,7 @@ export function documentTools(ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "get_document",
       "Get metadata for a specific document (does not return file content).",
       {
@@ -134,7 +134,7 @@ export function documentTools(ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "upload_document",
       "Upload a file from the filesystem as a document. Use this to register files you create as documents in the Documents library. The file is copied to Stagent storage and queued for preprocessing (text extraction).",
       {
@@ -194,7 +194,7 @@ export function documentTools(ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "update_document",
       "Update document metadata or trigger reprocessing. Metadata is merged with existing values, not replaced.",
       {
@@ -255,7 +255,7 @@ export function documentTools(ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "delete_document",
       "Delete a document. If the document is linked to a task, you must set cascadeDelete to true to confirm deletion.",
       {
@@ -300,7 +300,7 @@ export function documentTools(ctx: ToolContext) {
         }
       }
     ),
-    tool(
+    defineTool(
       "read_document_content",
       "Read the full extracted text content of a document. Use this when you need to analyze, summarize, or answer questions about a document's contents.",
       {

package/src/lib/chat/tools/handoff-tools.ts

@@ -0,0 +1,70 @@
+import { defineTool } from "../tool-registry";
+import { z } from "zod";
+import { ok, err, type ToolContext } from "./helpers";
+import { sendHandoff } from "@/lib/agents/handoff/bus";
+
+export function handoffTools(_ctx: ToolContext) {
+  return [
+    defineTool(
+      "send_handoff",
+      "Hand off a task from one agent profile to another. Creates an async handoff request that the target agent will pick up. Use this when a task requires expertise from a different agent profile.",
+      {
+        toProfile: z
+          .string()
+          .describe("Target agent profile ID (e.g. code-reviewer, researcher, document-writer)"),
+        subject: z
+          .string()
+          .min(1)
+          .max(200)
+          .describe("Brief subject line for the handoff"),
+        body: z
+          .string()
+          .min(1)
+          .max(4000)
+          .describe("Detailed description of what the target agent should do"),
+        fromProfile: z
+          .string()
+          .optional()
+          .describe("Source agent profile ID. Defaults to 'general'."),
+        sourceTaskId: z
+          .string()
+          .optional()
+          .describe("Source task ID that initiated this handoff"),
+        priority: z
+          .number()
+          .min(0)
+          .max(3)
+          .optional()
+          .describe("Priority: 0 = critical, 1 = high, 2 = medium (default), 3 = low"),
+        requiresApproval: z
+          .boolean()
+          .optional()
+          .describe("Whether human approval is required before the handoff is processed. Defaults to false."),
+      },
+      async (args) => {
+        try {
+          const messageId = await sendHandoff({
+            fromProfileId: args.fromProfile ?? "general",
+            toProfileId: args.toProfile,
+            sourceTaskId: args.sourceTaskId ?? "",
+            subject: args.subject,
+            body: args.body,
+            priority: args.priority,
+            requiresApproval: args.requiresApproval,
+          });
+
+          return ok({
+            message: "Handoff created successfully",
+            messageId,
+            from: args.fromProfile ?? "general",
+            to: args.toProfile,
+            subject: args.subject,
+            requiresApproval: args.requiresApproval ?? false,
+          });
+        } catch (e) {
+          return err(e instanceof Error ? e.message : "Failed to create handoff");
+        }
+      }
+    ),
+  ];
+}

package/src/lib/chat/tools/notification-tools.ts

@@ -1,4 +1,4 @@
-import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { db } from "@/lib/db";
 import { notifications } from "@/lib/db/schema";
@@ -7,7 +7,7 @@ import { ok, err, type ToolContext } from "./helpers";
 
 export function notificationTools(_ctx: ToolContext) {
   return [
-    tool(
+    defineTool(
       "list_notifications",
       "List notifications. By default shows only pending approval requests. Set pendingOnly to false for all recent notifications.",
       {
@@ -58,7 +58,7 @@ export function notificationTools(_ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "respond_notification",
       "Respond to a pending permission or approval notification. Use 'allow' to approve or 'deny' to reject.",
       {
@@ -124,7 +124,7 @@ export function notificationTools(_ctx: ToolContext) {
       }
     ),
 
-    tool(
+    defineTool(
       "mark_notifications_read",
       "Mark all unread notifications as read.",
       {},