stagent 0.10.0 → 0.11.1

package/src/lib/chat/skill-composition.ts

@@ -0,0 +1,210 @@
+/**
+ * Shared composition service — single source of truth for activate_skill /
+ * deactivate_skill logic, used by both the chat tool handler and the thin
+ * HTTP routes (POST /api/chat/conversations/[id]/skills/activate|deactivate).
+ *
+ * The chat tool delegates here so the UI can reach the same behaviour over
+ * HTTP without going through MCP.
+ *
+ * See `features/chat-composition-ui-v1.md`.
+ */
+
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db";
+import { conversations } from "@/lib/db/schema";
+import { mergeActiveSkillIds } from "@/lib/chat/active-skills";
+import type { SkillConflict } from "@/lib/chat/skill-conflict";
+
+export type ActivateSkillResult =
+  | {
+      kind: "ok";
+      activatedSkillId: string;
+      activeSkillIds: string[];
+      skillName: string;
+      note?: string;
+    }
+  | {
+      kind: "conflicts";
+      activeSkillIds: string[];
+      conflicts: SkillConflict[];
+      hint: string;
+    }
+  | { kind: "error"; message: string };
+
+export type DeactivateSkillResult =
+  | { kind: "ok"; previousSkillId: string | null }
+  | { kind: "error"; message: string };
+
+/**
+ * Activate a skill on a conversation, respecting runtime composition limits.
+ *
+ * @param conversationId  Target conversation.
+ * @param skillId         Opaque skill id from list_skills.
+ * @param mode            "replace" (default) clears prior active skills; "add"
+ *                        appends — runtime must support composition.
+ * @param force           When mode="add", skip conflict heuristic warnings.
+ */
+export async function activateSkill(args: {
+  conversationId: string;
+  skillId: string;
+  mode?: "replace" | "add";
+  force?: boolean;
+}): Promise<ActivateSkillResult> {
+  const { conversationId, skillId, mode = "replace", force = false } = args;
+
+  try {
+    const { getSkill } = await import("@/lib/environment/list-skills");
+    const skill = getSkill(skillId);
+    if (!skill) return { kind: "error", message: `Skill not found: ${skillId}` };
+
+    const existing = await db
+      .select({
+        id: conversations.id,
+        activeSkillId: conversations.activeSkillId,
+        activeSkillIds: conversations.activeSkillIds,
+        runtimeId: conversations.runtimeId,
+      })
+      .from(conversations)
+      .where(eq(conversations.id, conversationId))
+      .get();
+
+    if (!existing) {
+      return { kind: "error", message: `Conversation not found: ${conversationId}` };
+    }
+
+    if (mode === "add") {
+      const { getRuntimeFeatures } = await import("@/lib/agents/runtime/catalog");
+      let features;
+      try {
+        features = getRuntimeFeatures(
+          existing.runtimeId as Parameters<typeof getRuntimeFeatures>[0]
+        );
+      } catch {
+        return {
+          kind: "error",
+          message: `Unknown runtime '${existing.runtimeId ?? "(none)"}' — cannot determine composition support`,
+        };
+      }
+
+      if (!features.supportsSkillComposition) {
+        return {
+          kind: "error",
+          message: `Runtime '${existing.runtimeId}' does not support skill composition — switch to a Claude/Codex/direct runtime to compose skills`,
+        };
+      }
+
+      const currentIds = mergeActiveSkillIds(existing.activeSkillId, existing.activeSkillIds);
+
+      if (currentIds.includes(skillId)) {
+        return {
+          kind: "ok",
+          activatedSkillId: skillId,
+          activeSkillIds: currentIds,
+          skillName: skill.name,
+          note: "skill already active",
+        };
+      }
+
+      if (currentIds.length >= features.maxActiveSkills) {
+        return {
+          kind: "error",
+          message: `Max active skills (${features.maxActiveSkills}) reached on '${existing.runtimeId}' — deactivate one first`,
+        };
+      }
+
+      if (!force && currentIds.length > 0) {
+        const { detectSkillConflicts } = await import("@/lib/chat/skill-conflict");
+        const allConflicts: SkillConflict[] = [];
+        for (const otherId of currentIds) {
+          const other = getSkill(otherId);
+          if (!other) continue;
+          const conflicts = detectSkillConflicts(
+            { id: skill.id, name: skill.name, content: skill.content },
+            { id: other.id, name: other.name, content: other.content }
+          );
+          allConflicts.push(...conflicts);
+        }
+        if (allConflicts.length > 0) {
+          return {
+            kind: "conflicts",
+            activeSkillIds: currentIds,
+            conflicts: allConflicts,
+            hint: "Re-call with force=true to add anyway",
+          };
+        }
+      }
+
+      // Append: store ALL composed IDs in the new column. Keep legacy
+      // activeSkillId as-is so single-skill read paths still work.
+      const newComposed = [...(existing.activeSkillIds ?? []), skillId];
+      await db
+        .update(conversations)
+        .set({ activeSkillIds: newComposed, updatedAt: new Date() })
+        .where(eq(conversations.id, conversationId));
+
+      return {
+        kind: "ok",
+        activatedSkillId: skillId,
+        activeSkillIds: mergeActiveSkillIds(existing.activeSkillId, newComposed),
+        skillName: skill.name,
+      };
+    }
+
+    // mode === "replace" (legacy / default)
+    await db
+      .update(conversations)
+      .set({
+        activeSkillId: skillId,
+        activeSkillIds: [],
+        updatedAt: new Date(),
+      })
+      .where(eq(conversations.id, conversationId));
+
+    return {
+      kind: "ok",
+      activatedSkillId: skillId,
+      activeSkillIds: [skillId],
+      skillName: skill.name,
+    };
+  } catch (e) {
+    return {
+      kind: "error",
+      message: e instanceof Error ? e.message : "activate_skill failed",
+    };
+  }
+}
+
+/**
+ * Clear the active skill (and composed skills) on a conversation.
+ */
+export async function deactivateSkill(args: {
+  conversationId: string;
+}): Promise<DeactivateSkillResult> {
+  const { conversationId } = args;
+  try {
+    const existing = await db
+      .select({
+        id: conversations.id,
+        activeSkillId: conversations.activeSkillId,
+      })
+      .from(conversations)
+      .where(eq(conversations.id, conversationId))
+      .get();
+
+    if (!existing) {
+      return { kind: "error", message: `Conversation not found: ${conversationId}` };
+    }
+
+    await db
+      .update(conversations)
+      .set({ activeSkillId: null, activeSkillIds: [], updatedAt: new Date() })
+      .where(eq(conversations.id, conversationId));
+
+    return { kind: "ok", previousSkillId: existing.activeSkillId ?? null };
+  } catch (e) {
+    return {
+      kind: "error",
+      message: e instanceof Error ? e.message : "deactivate_skill failed",
+    };
+  }
+}

package/src/lib/chat/skill-conflict.ts

@@ -0,0 +1,105 @@
+/**
+ * Lightweight heuristic that flags when two SKILL.md bodies issue
+ * divergent directives on the same topic. Pure function — no I/O.
+ *
+ * Approach (v1):
+ *   1. For each skill, extract "directive lines" containing one of:
+ *      always | never | must | prefer | use | avoid | don't | do not
+ *   2. Tokenize each directive into content words (lowercase, drop
+ *      stopwords + the directive verb itself).
+ *   3. For each pair of directives across the two skills with significant
+ *      keyword overlap (≥2 shared content words ≥4 chars), check if their
+ *      directive verbs disagree (always vs never, prefer vs avoid, etc.).
+ *   4. Surface the disagreeing pair as a SkillConflict.
+ *
+ * False positives are acceptable — the consumer presents excerpts to the
+ * user, not a binary block. False negatives (semantic conflict without
+ * keyword overlap) await the embedding-based v2.
+ */
+
+export interface SkillMarkdown {
+  id: string;
+  name: string;
+  content: string;
+}
+
+export interface SkillConflict {
+  skillA: string;       // skill name
+  skillB: string;       // skill name
+  sharedTopic: string;  // joined keywords that overlapped
+  excerptA: string;     // the directive line from A
+  excerptB: string;     // the directive line from B
+}
+
+const POSITIVE_DIRECTIVES = new Set(["always", "must", "prefer", "use", "do"]);
+const NEGATIVE_DIRECTIVES = new Set(["never", "avoid", "don't", "dont", "skip"]);
+const ALL_DIRECTIVES = new Set([...POSITIVE_DIRECTIVES, ...NEGATIVE_DIRECTIVES]);
+
+const STOPWORDS = new Set([
+  "the", "a", "an", "and", "or", "but", "for", "with", "without",
+  "to", "of", "in", "on", "at", "by", "from", "as", "is", "are",
+  "be", "this", "that", "these", "those", "it", "its", "before",
+  "after", "during", "into", "out",
+]);
+
+interface DirectiveLine {
+  raw: string;
+  polarity: "positive" | "negative";
+  keywords: Set<string>;
+}
+
+function extractDirectives(content: string): DirectiveLine[] {
+  const lines = content.split(/\r?\n/);
+  const out: DirectiveLine[] = [];
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith("```")) continue;
+    const lower = line.toLowerCase();
+    let polarity: "positive" | "negative" | null = null;
+    for (const tok of lower.split(/\s+/)) {
+      const cleaned = tok.replace(/[^a-z']/g, "");
+      if (POSITIVE_DIRECTIVES.has(cleaned)) { polarity = "positive"; break; }
+      if (NEGATIVE_DIRECTIVES.has(cleaned)) { polarity = "negative"; break; }
+    }
+    if (!polarity) continue;
+    const keywords = new Set<string>();
+    for (const tok of lower.split(/[^a-z0-9]+/)) {
+      if (tok.length < 4) continue;
+      if (STOPWORDS.has(tok) || ALL_DIRECTIVES.has(tok)) continue;
+      keywords.add(tok);
+    }
+    if (keywords.size === 0) continue;
+    out.push({ raw: line, polarity, keywords });
+  }
+  return out;
+}
+
+function intersect(a: Set<string>, b: Set<string>): string[] {
+  const out: string[] = [];
+  for (const tok of a) if (b.has(tok)) out.push(tok);
+  return out;
+}
+
+export function detectSkillConflicts(
+  a: SkillMarkdown,
+  b: SkillMarkdown
+): SkillConflict[] {
+  const directivesA = extractDirectives(a.content);
+  const directivesB = extractDirectives(b.content);
+  const conflicts: SkillConflict[] = [];
+  for (const da of directivesA) {
+    for (const db of directivesB) {
+      if (da.polarity === db.polarity) continue;
+      const shared = intersect(da.keywords, db.keywords);
+      if (shared.length < 2) continue;
+      conflicts.push({
+        skillA: a.name,
+        skillB: b.name,
+        sharedTopic: shared.slice(0, 3).join(", "),
+        excerptA: da.raw,
+        excerptB: db.raw,
+      });
+    }
+  }
+  return conflicts;
+}

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

@@ -21,6 +21,8 @@ import { chatHistoryTools } from "./tools/chat-history-tools";
 import { handoffTools } from "./tools/handoff-tools";
 import { tableTools } from "./tools/table-tools";
 import { runtimeTools } from "./tools/runtime-tools";
+import { blueprintTools } from "./tools/blueprint-tools";
+import { skillTools } from "./tools/skill-tools";
 
 
 // ── Tool server types ────────────────────────────────────────────────
@@ -57,6 +59,8 @@ function collectAllTools(ctx: ToolContext): ToolDefinition[] {
     ...handoffTools(ctx),
     ...tableTools(ctx),
     ...runtimeTools(ctx),
+    ...blueprintTools(ctx),
+    ...skillTools(ctx),
   ];
 }
 
@@ -71,8 +75,9 @@ function collectAllTools(ctx: ToolContext): ToolDefinition[] {
 export function createToolServer(
   projectId?: string | null,
   onToolResult?: (toolName: string, result: unknown) => void,
+  projectDir?: string | null,
 ): ToolServer {
-  const ctx: ToolContext = { projectId, onToolResult };
+  const ctx: ToolContext = { projectId, projectDir, onToolResult };
   const allTools = collectAllTools(ctx);
 
   // Handler lookup map (built once, shared across modes)
@@ -114,21 +119,3 @@ export function createToolServer(
   };
 }
 
-// ── Backward-compatible export ───────────────────────────────────────
-
-/**
- * Create an in-process MCP server exposing all Stagent tools.
- * The `projectId` closure auto-scopes operations to the active project.
- * `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,
-) {
-  return createToolServer(projectId, onToolResult).asMcpServer();
-}

package/src/lib/chat/stream-telemetry.ts

@@ -23,11 +23,16 @@
  *   - stream.reconciled.stale — reconcileStreamingMessages swept an orphan
  *                               at chat page load (10-min cutoff)
  *
- * Three client-side reason codes (logged via console.info with a stable
+ * Four client-side reason codes (logged via console.info with a stable
  * prefix so tests and grep can find them):
- *   - client.stream.done        — reader.read() returned done: true
- *   - client.stream.user-abort  — user clicked Stop / AbortController fired
- *   - client.stream.reader-error — reader.read() or decode threw
+ *   - client.stream.done          — reader.read() returned done: true
+ *   - client.stream.user-abort    — user clicked Stop / AbortController fired
+ *   - client.stream.reader-error  — reader.read() or decode threw
+ *   - client.stream.view-remount  — a chat-consuming component unmounted
+ *                                    while a stream was in flight. The stream
+ *                                    itself continues in the provider; this
+ *                                    code exists so diagnostics can confirm
+ *                                    the provider-hoisting fix is holding.
  *
  * As of the `chat-session-persistence-provider` feature, the SSE reader
  * loop runs inside `ChatSessionProvider` (rendered from the root layout),

package/src/lib/chat/system-prompt.ts

@@ -1,6 +1,28 @@
 /**
  * Enhanced system prompt for the Stagent chat LLM.
  * Provides identity, tool catalog, and intent routing guidance.
+ *
+ * ## Tier 0 vs CLAUDE.md partition (DD-CE-002)
+ *
+ * When the chat engine runs on the `claude-code` runtime, the Claude Agent
+ * SDK loads project-level `CLAUDE.md` and user-level `~/.claude/CLAUDE.md`
+ * via `settingSources: ["user", "project"]`. To avoid double-prompting,
+ * this system prompt MUST stay scoped to:
+ *
+ *   (a) Stagent identity
+ *   (b) Stagent tool catalog and routing
+ *   (c) Stagent domain semantics (delay steps, enrich_table, workflow dedup)
+ *   (d) LLM interaction style
+ *
+ * Content that is project-specific (coding conventions, testing rules,
+ * git workflow, repo-specific gotchas) belongs in `CLAUDE.md` — NOT here.
+ *
+ * Audit (2026-04-13): every current block in this prompt passes the rubric.
+ * No content migration was required for Stagent's current CLAUDE.md state.
+ * The worktree note on line 110 is borderline and flagged for revisit if
+ * CLAUDE.md gains an explicit worktree section.
+ *
+ * Reference: features/chat-claude-sdk-skills.md (§"Tier 0 vs CLAUDE.md").
  */
 
 export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant for managing software projects, tasks, workflows, documents, and schedules. You are a full alternate UI for the Stagent app — users can do everything through chat that they can do in the GUI.

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

@@ -13,6 +13,7 @@ import {
   Sun,
   Sparkles,
   Table2,
+  Zap,
 } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 
@@ -32,7 +33,8 @@ export type ToolGroup =
   | "Settings"
   | "Chat"
   | "Browser"
-  | "Utility";
+  | "Utility"
+  | "Session";
 
 export interface ToolCatalogEntry {
   /** MCP tool name, e.g. "list_tasks" */
@@ -50,6 +52,7 @@ export interface ToolCatalogEntry {
 // ── Group → Icon mapping ─────────────────────────────────────────────────
 
 export const TOOL_GROUP_ICONS: Record<ToolGroup, LucideIcon> = {
+  Session: Zap,
   Tasks: ListTodo,
   Projects: FolderKanban,
   Workflows: GitBranch,
@@ -68,6 +71,7 @@ export const TOOL_GROUP_ICONS: Record<ToolGroup, LucideIcon> = {
 
 /** Display order for groups in the popover */
 export const TOOL_GROUP_ORDER: ToolGroup[] = [
+  "Session",
   "Tasks",
   "Projects",
   "Workflows",
@@ -109,6 +113,11 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "execute_workflow", description: "Start executing a workflow", group: "Workflows", paramHint: "workflowId" },
   { name: "delete_workflow", description: "Delete a workflow", group: "Workflows", paramHint: "workflowId" },
   { name: "get_workflow_status", description: "Get workflow execution progress", group: "Workflows", paramHint: "workflowId" },
+  { name: "list_blueprints", description: "List available workflow blueprints", group: "Workflows", paramHint: "domain, search" },
+  { name: "get_blueprint", description: "Get blueprint details and variables", group: "Workflows", paramHint: "blueprintId" },
+  { name: "instantiate_blueprint", description: "Create a workflow from a blueprint", group: "Workflows", paramHint: "blueprintId, variables" },
+  { name: "create_blueprint", description: "Create a custom workflow blueprint", group: "Workflows", paramHint: "yaml" },
+  { name: "delete_blueprint", description: "Delete a custom blueprint", group: "Workflows", paramHint: "blueprintId" },
 
   // ── Schedules ──
   { name: "list_schedules", description: "List scheduled prompt loops", group: "Schedules", paramHint: "status" },
@@ -133,6 +142,9 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   // ── Profiles ──
   { name: "list_profiles", description: "List available agent profiles", group: "Profiles" },
   { name: "get_profile", description: "Get agent profile configuration", group: "Profiles", paramHint: "profileId" },
+  { name: "create_profile", description: "Create a new agent profile", group: "Profiles", paramHint: "config, skillMd" },
+  { name: "update_profile", description: "Update a custom agent profile", group: "Profiles", paramHint: "profileId, config, skillMd" },
+  { name: "delete_profile", description: "Delete a custom agent profile", group: "Profiles", paramHint: "profileId" },
 
   // ── Usage ──
   { name: "get_usage_summary", description: "Get spending and token usage stats", group: "Usage", paramHint: "days" },
@@ -141,6 +153,12 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "get_settings", description: "Get current Stagent settings", group: "Settings", paramHint: "key" },
   { name: "set_settings", description: "Update a Stagent setting (approval required)", group: "Settings", paramHint: "key, value" },
 
+  // ── Skills ──
+  { name: "list_skills", description: "List all discoverable skills (user + project scopes)", group: "Skills" },
+  { name: "get_skill", description: "Get full SKILL.md content + metadata for one skill", group: "Skills", paramHint: "id" },
+  { name: "activate_skill", description: "Bind a skill to a conversation — SKILL.md is injected into every turn's system prompt. Pass mode='add' to compose (runtime-gated).", group: "Skills", paramHint: "conversationId, skillId, mode?" },
+  { name: "deactivate_skill", description: "Clear the active skill from a conversation", group: "Skills", paramHint: "conversationId" },
+
   // ── Tables ──
   { name: "list_tables", description: "List tables, filter by project or source", group: "Tables", paramHint: "projectId, source" },
   { name: "get_table_schema", description: "Get column definitions for a table", group: "Tables", paramHint: "tableId" },
@@ -188,6 +206,18 @@ const BROWSER_TOOLS: ToolCatalogEntry[] = [
   { name: "take_snapshot", description: "Take an accessibility snapshot", group: "Browser" },
 ];
 
+const SESSION_ENTRIES: ToolCatalogEntry[] = [
+  { name: "clear", description: "Start a new conversation", group: "Session", behavior: "execute_immediately" },
+  { name: "compact", description: "Summarize and compact conversation history", group: "Session", behavior: "execute_immediately" },
+  { name: "export", description: "Save current conversation as a document", group: "Session", behavior: "execute_immediately" },
+  { name: "help", description: "Show chat shortcuts and commands", group: "Session", behavior: "execute_immediately" },
+  { name: "settings", description: "Open Stagent settings", group: "Session", behavior: "execute_immediately" },
+  { name: "new-task", description: "Create a new task", group: "Session", paramHint: "title" },
+  { name: "new-workflow", description: "Create a new workflow", group: "Session", paramHint: "name" },
+  { name: "new-schedule", description: "Create a new schedule", group: "Session", paramHint: "name, interval" },
+  { name: "new-from-template", description: "Start a conversation from a workflow blueprint", group: "Session", behavior: "execute_immediately" },
+];
+
 const UTILITY_ENTRIES: ToolCatalogEntry[] = [
   { name: "toggle_theme", description: "Switch dark/light mode", group: "Utility", behavior: "execute_immediately" },
   { name: "mark_all_read", description: "Mark all notifications as read", group: "Utility", behavior: "execute_immediately" },
@@ -203,13 +233,13 @@ export function getToolCatalog(opts?: { includeBrowser?: boolean }): ToolCatalog
 
   if (withBrowser) {
     if (!cachedWithBrowser) {
-      cachedWithBrowser = [...STAGENT_TOOLS, ...BROWSER_TOOLS, ...UTILITY_ENTRIES];
+      cachedWithBrowser = [...SESSION_ENTRIES, ...STAGENT_TOOLS, ...BROWSER_TOOLS, ...UTILITY_ENTRIES];
     }
     return cachedWithBrowser;
   }
 
   if (!cachedCatalog) {
-    cachedCatalog = [...STAGENT_TOOLS, ...UTILITY_ENTRIES];
+    cachedCatalog = [...SESSION_ENTRIES, ...STAGENT_TOOLS, ...UTILITY_ENTRIES];
   }
   return cachedCatalog;
 }

package/src/lib/chat/tools/__tests__/profile-tools.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("@/lib/agents/profiles/list-fused-profiles", () => ({
+  listFusedProfiles: vi.fn(async (projectDir: string | null) =>
+    [
+      {
+        id: "general",
+        name: "General",
+        description: "Reg",
+        domain: "general",
+        tags: [],
+      },
+      projectDir
+        ? {
+            id: "project-only",
+            name: "Project Only",
+            description: "Proj",
+            domain: "skill",
+            tags: [],
+            origin: "filesystem-project",
+          }
+        : null,
+    ].filter(Boolean)
+  ),
+}));
+
+describe("list_profiles chat tool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns fused profiles when called with a projectDir", async () => {
+    const { getListProfilesTool } = await import("@/lib/chat/tools/profile-tools");
+    const tool = getListProfilesTool("/fake/project");
+    const result = await tool.handler({});
+    // ok() wraps data as MCP content — parse the JSON text back out
+    const text = result.content[0].text;
+    const list = JSON.parse(text) as { id: string }[];
+    expect(Array.isArray(list)).toBe(true);
+    expect(list.some((p) => p.id === "project-only")).toBe(true);
+  });
+
+  it("returns registry-only profiles when projectDir is null", async () => {
+    const { getListProfilesTool } = await import("@/lib/chat/tools/profile-tools");
+    const tool = getListProfilesTool(null);
+    const result = await tool.handler({});
+    const text = result.content[0].text;
+    const list = JSON.parse(text) as { id: string }[];
+    expect(list.every((p) => p.id !== "project-only")).toBe(true);
+  });
+});