stagent 0.9.6 → 0.11.0

package/src/hooks/__tests__/use-chat-autocomplete-tabs.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useChatAutocomplete } from "../use-chat-autocomplete";
+
+const TAB_KEY = "stagent.command-tab";
+
+describe("useChatAutocomplete — activeTab persistence", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("defaults to 'actions' when localStorage empty", () => {
+    const { result } = renderHook(() => useChatAutocomplete({ projectId: null }));
+    expect(result.current.activeTab).toBe("actions");
+  });
+
+  it("reads persisted tab from localStorage on mount", () => {
+    localStorage.setItem(TAB_KEY, "skills");
+    const { result } = renderHook(() => useChatAutocomplete({ projectId: null }));
+    expect(result.current.activeTab).toBe("skills");
+  });
+
+  it("ignores corrupt localStorage values", () => {
+    localStorage.setItem(TAB_KEY, "bogus");
+    const { result } = renderHook(() => useChatAutocomplete({ projectId: null }));
+    expect(result.current.activeTab).toBe("actions");
+  });
+
+  it("persists tab on setActiveTab", () => {
+    const { result } = renderHook(() => useChatAutocomplete({ projectId: null }));
+    act(() => result.current.setActiveTab("tools"));
+    expect(result.current.activeTab).toBe("tools");
+    expect(localStorage.getItem(TAB_KEY)).toBe("tools");
+  });
+
+  it("survives localStorage throwing on write", () => {
+    const setSpy = vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("QuotaExceeded");
+    });
+    const { result } = renderHook(() => useChatAutocomplete({ projectId: null }));
+    expect(() => {
+      act(() => result.current.setActiveTab("tools"));
+    }).not.toThrow();
+    expect(result.current.activeTab).toBe("tools");
+    setSpy.mockRestore();
+  });
+});

package/src/hooks/__tests__/use-saved-searches.test.ts

@@ -0,0 +1,70 @@
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useSavedSearches } from "../use-saved-searches";
+import { beforeEach, describe, expect, it, vi, afterEach } from "vitest";
+
+describe("useSavedSearches — rename", () => {
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    global.fetch = vi.fn(async (url: RequestInfo | URL, init?: RequestInit) => {
+      const u = String(url);
+      if (u.endsWith("/api/settings/chat/saved-searches") && (!init || init.method === undefined || init.method === "GET")) {
+        return new Response(
+          JSON.stringify({
+            searches: [
+              {
+                id: "s1",
+                surface: "task",
+                label: "Old label",
+                filterInput: "#status:blocked",
+                createdAt: "2026-04-14T00:00:00.000Z",
+              },
+            ],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      if (init?.method === "PUT") {
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      }
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("renames a saved search optimistically and persists via PUT", async () => {
+    const { result } = renderHook(() => useSavedSearches());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.searches[0].label).toBe("Old label");
+
+    await act(async () => {
+      result.current.rename("s1", "New label");
+    });
+
+    expect(result.current.searches[0].label).toBe("New label");
+
+    const putCall = (global.fetch as unknown as ReturnType<typeof vi.fn>).mock.calls.find(
+      ([, init]) => init?.method === "PUT"
+    );
+    expect(putCall).toBeDefined();
+    const body = JSON.parse((putCall![1] as RequestInit).body as string);
+    expect(body.searches[0].label).toBe("New label");
+    expect(body.searches[0].id).toBe("s1");
+  });
+
+  it("no-ops when id is not found", async () => {
+    const { result } = renderHook(() => useSavedSearches());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    const before = result.current.searches;
+
+    await act(async () => {
+      result.current.rename("does-not-exist", "Whatever");
+    });
+
+    expect(result.current.searches).toEqual(before);
+  });
+});

package/src/hooks/use-active-skills.ts

@@ -0,0 +1,110 @@
+"use client";
+
+/**
+ * `useActiveSkills` — surfaces the current conversation's composition
+ * state for UI affordances on the chat popover Skills tab.
+ *
+ * Returns the merged active skill IDs (legacy + composed), the runtime
+ * id, and the runtime's `supportsSkillComposition` + `maxActiveSkills`
+ * capability flags. Used by the `+ Add` action and active-count badge
+ * in `chat-command-popover.tsx`.
+ *
+ * See `features/chat-composition-ui-v1.md`.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { mergeActiveSkillIds } from "@/lib/chat/active-skills";
+import { getRuntimeFeatures, type AgentRuntimeId } from "@/lib/agents/runtime/catalog";
+
+interface ActiveSkillsState {
+  loading: boolean;
+  /** Resolved active skill IDs (legacy + composed, deduped, in order). */
+  activeIds: string[];
+  /** The conversation's runtime id, or null if not yet loaded / no conversation. */
+  runtimeId: AgentRuntimeId | null;
+  /** True iff the runtime supports composing 2+ skills concurrently. */
+  supportsComposition: boolean;
+  /** Max simultaneously-active skills for this runtime (1 for Ollama, 3 elsewhere). */
+  maxActive: number;
+  /** Re-fetch the conversation row. Call after a successful add/remove. */
+  refetch: () => Promise<void>;
+}
+
+const KNOWN_RUNTIMES = new Set<AgentRuntimeId>([
+  "claude-code",
+  "openai-codex-app-server",
+  "anthropic-direct",
+  "openai-direct",
+  "ollama",
+]);
+
+export function useActiveSkills(
+  conversationId: string | null
+): ActiveSkillsState {
+  const [activeIds, setActiveIds] = useState<string[]>([]);
+  const [runtimeId, setRuntimeId] = useState<AgentRuntimeId | null>(null);
+  const [loading, setLoading] = useState<boolean>(!!conversationId);
+
+  const fetchOnce = useCallback(async (): Promise<void> => {
+    if (!conversationId) {
+      setActiveIds([]);
+      setRuntimeId(null);
+      setLoading(false);
+      return;
+    }
+    try {
+      const r = await fetch(`/api/chat/conversations/${conversationId}`);
+      if (!r.ok) {
+        setActiveIds([]);
+        setRuntimeId(null);
+        return;
+      }
+      const data: {
+        activeSkillId?: string | null;
+        activeSkillIds?: string[] | null;
+        runtimeId?: string | null;
+      } = await r.json();
+      setActiveIds(
+        mergeActiveSkillIds(data.activeSkillId, data.activeSkillIds)
+      );
+      const rid = data.runtimeId as AgentRuntimeId | null | undefined;
+      setRuntimeId(rid && KNOWN_RUNTIMES.has(rid) ? rid : null);
+    } catch {
+      setActiveIds([]);
+      setRuntimeId(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [conversationId]);
+
+  useEffect(() => {
+    setLoading(true);
+    void fetchOnce();
+  }, [fetchOnce]);
+
+  // Derive capability flags from the catalog. Defaults match Ollama
+  // (most conservative) when the runtime is unknown — better to refuse
+  // composition than to crash on an unrecognized id.
+  const features = runtimeId
+    ? safeGetRuntimeFeatures(runtimeId)
+    : null;
+  const supportsComposition = features?.supportsSkillComposition ?? false;
+  const maxActive = features?.maxActiveSkills ?? 1;
+
+  return {
+    loading,
+    activeIds,
+    runtimeId,
+    supportsComposition,
+    maxActive,
+    refetch: fetchOnce,
+  };
+}
+
+function safeGetRuntimeFeatures(rid: AgentRuntimeId) {
+  try {
+    return getRuntimeFeatures(rid);
+  } catch {
+    return null;
+  }
+}

package/src/hooks/use-chat-autocomplete.ts

@@ -2,6 +2,11 @@
 
 import { useState, useCallback, useRef, useEffect } from "react";
 import { useCaretPosition } from "./use-caret-position";
+import {
+  isCommandTabId,
+  DEFAULT_COMMAND_TAB,
+  type CommandTabId,
+} from "@/lib/chat/command-tabs";
 
 export type AutocompleteMode = "slash" | "mention" | null;
 
@@ -32,6 +37,8 @@ export interface ChatAutocompleteReturn {
   entityResults: EntitySearchResult[];
   entityLoading: boolean;
   mentions: MentionReference[];
+  activeTab: CommandTabId;
+  setActiveTab: (tab: CommandTabId) => void;
   handleChange: (value: string, textarea: HTMLTextAreaElement | null) => void;
   handleKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => boolean;
   handleSelect: (item: { type: "slash" | "mention"; id: string; label: string; text?: string }) => string;
@@ -39,6 +46,19 @@ export interface ChatAutocompleteReturn {
   setTextareaRef: (el: HTMLTextAreaElement | null) => void;
 }
 
+const TAB_STORAGE_KEY = "stagent.command-tab";
+
+function readInitialTab(): CommandTabId {
+  if (typeof window === "undefined") return DEFAULT_COMMAND_TAB;
+  try {
+    const raw = window.localStorage.getItem(TAB_STORAGE_KEY);
+    if (raw && isCommandTabId(raw)) return raw;
+  } catch {
+    // localStorage unavailable — fall through
+  }
+  return DEFAULT_COMMAND_TAB;
+}
+
 const CLOSED_STATE: AutocompleteState = {
   open: false,
   mode: null,
@@ -47,21 +67,45 @@ const CLOSED_STATE: AutocompleteState = {
   anchorRect: null,
 };
 
+/** Compact size label for file popover rows (e.g., "1.4 KB", "23 B"). */
+function humanSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 /**
  * Detects "/" and "@" triggers in a textarea and manages autocomplete state.
  *
  * "/" triggers at position 0 or after a newline.
  * "@" triggers at position 0 or after whitespace.
  */
-export function useChatAutocomplete(): ChatAutocompleteReturn {
+export function useChatAutocomplete(
+  options: { projectId?: string | null } = {}
+): ChatAutocompleteReturn {
   const [state, setState] = useState<AutocompleteState>(CLOSED_STATE);
   const [entityResults, setEntityResults] = useState<EntitySearchResult[]>([]);
+  const [fileResults, setFileResults] = useState<EntitySearchResult[]>([]);
   const [entityLoading, setEntityLoading] = useState(false);
   const [mentions, setMentions] = useState<MentionReference[]>([]);
+  const [activeTab, setActiveTabState] = useState<CommandTabId>(readInitialTab);
+
+  const setActiveTab = useCallback((tab: CommandTabId) => {
+    setActiveTabState(tab);
+    try {
+      window.localStorage.setItem(TAB_STORAGE_KEY, tab);
+    } catch {
+      // quota / disabled — silent, in-memory only
+    }
+  }, []);
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
   const abortRef = useRef<AbortController | null>(null);
+  const fileAbortRef = useRef<AbortController | null>(null);
+  const fileDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const entityCacheRef = useRef<EntitySearchResult[] | null>(null);
   const getCaretCoordinates = useCaretPosition();
+  const projectIdRef = useRef(options.projectId ?? null);
+  projectIdRef.current = options.projectId ?? null;
 
   // Ref to let the keyboard handler access current state synchronously
   const stateRef = useRef(state);
@@ -74,9 +118,51 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
   const close = useCallback(() => {
     setState(CLOSED_STATE);
     setEntityResults([]);
+    setFileResults([]);
     setEntityLoading(false);
     entityCacheRef.current = null;
     if (abortRef.current) abortRef.current.abort();
+    if (fileAbortRef.current) fileAbortRef.current.abort();
+    if (fileDebounceRef.current) clearTimeout(fileDebounceRef.current);
+  }, []);
+
+  /**
+   * Query the file search API with debounce + abort. Results are stored
+   * in `fileResults` and merged into the popover stream alongside
+   * entity results. Query is bound to the active "@" typeahead text.
+   */
+  const loadFiles = useCallback((query: string) => {
+    // Debounce: wait 150ms after the last keystroke before firing.
+    if (fileDebounceRef.current) clearTimeout(fileDebounceRef.current);
+    fileDebounceRef.current = setTimeout(() => {
+      if (fileAbortRef.current) fileAbortRef.current.abort();
+      const controller = new AbortController();
+      fileAbortRef.current = controller;
+
+      const params = new URLSearchParams({ q: query, limit: "20" });
+      const projectId = projectIdRef.current;
+      if (projectId) params.set("projectId", projectId);
+
+      fetch(`/api/chat/files/search?${params}`, { signal: controller.signal })
+        .then((res) => (res.ok ? res.json() : { results: [] }))
+        .then(
+          (data: {
+            results?: Array<{ path: string; sizeBytes: number }>;
+          }) => {
+            const hits = data.results ?? [];
+            const mapped: EntitySearchResult[] = hits.map((h) => ({
+              entityType: "file",
+              entityId: h.path,
+              label: h.path,
+              description: humanSize(h.sizeBytes),
+            }));
+            setFileResults(mapped);
+          }
+        )
+        .catch(() => {
+          // Aborted or failed — leave previous results in place.
+        });
+    }, 150);
   }, []);
 
   // Fetch all recent entities once on "@" trigger, cache for cmdk client-side filtering
@@ -143,8 +229,15 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
         return;
       }
 
-      // Check for "@" trigger — must be at position 0 or after whitespace
-      const mentionMatch = textBeforeCursor.match(/(?:^|\s)(@[^\s]*)$/);
+      // Check for "@" trigger — must be at position 0 or after whitespace.
+      // The mention body stops at whitespace or `#` so the filter-namespace
+      // (`#key:value`) can chain after a space: `@foo #status:blocked`.
+      // Filter tokens are part of the same trigger span so the popover stays
+      // open while the user types them. Partial tokens (`@foo #` or
+      // `@foo #sta`) are accepted — the parser handles incomplete input.
+      const mentionMatch = textBeforeCursor.match(
+        /(?:^|\s)(@[^\s#]*(?:\s+#[A-Za-z]?[\w-]*:?[^\s#]*)*)\s*$/
+      );
       if (mentionMatch) {
         const triggerIndex = cursorPos - mentionMatch[1].length;
         const query = mentionMatch[1].substring(1); // text after "@"
@@ -157,6 +250,14 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
           anchorRect: coords,
         });
         loadEntities();
+        // File search fires only when the user has typed something after `@`
+        // — an empty query would return every tracked file in the repo, which
+        // is noisy and defeats the whole "type to narrow" interaction.
+        if (query.length > 0) {
+          loadFiles(query);
+        } else {
+          setFileResults([]);
+        }
         return;
       }
 
@@ -165,7 +266,7 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
         close();
       }
     },
-    [getCaretCoordinates, loadEntities, close]
+    [getCaretCoordinates, loadEntities, loadFiles, close]
   );
 
   /**
@@ -245,10 +346,15 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
       if (item.type === "slash") {
         replacement = item.text ?? item.label;
       } else {
-        // "@" mention — insert @type:Name
+        // "@" mention — format depends on entity type:
+        //   file:  @<path>           (CLI-style, matches what users type)
+        //   other: @<type>:<label>   (disambiguates entity types)
         const eType = item.entityType ?? item.id;
         const eId = item.entityId ?? item.id;
-        replacement = `@${eType}:${item.label} `;
+        replacement =
+          eType === "file"
+            ? `@${item.label} `
+            : `@${eType}:${item.label} `;
         // Track the mention
         setMentions((prev) => {
           if (prev.some((m) => m.entityId === eId)) return prev;
@@ -271,14 +377,21 @@ export function useChatAutocomplete(): ChatAutocompleteReturn {
   useEffect(() => {
     return () => {
       if (abortRef.current) abortRef.current.abort();
+      if (fileAbortRef.current) fileAbortRef.current.abort();
+      if (fileDebounceRef.current) clearTimeout(fileDebounceRef.current);
     };
   }, []);
 
   return {
     state,
-    entityResults,
+    // Merge entity results with file results so the popover's single
+    // group-by-entityType render path covers both — no second props
+    // channel needed.
+    entityResults: [...entityResults, ...fileResults],
     entityLoading,
     mentions,
+    activeTab,
+    setActiveTab,
     handleChange,
     handleKeyDown,
     handleSelect,

package/src/hooks/use-enriched-skills.ts

@@ -0,0 +1,19 @@
+"use client";
+import { useEffect, useState } from "react";
+import type { EnrichedSkill } from "@/lib/environment/skill-enrichment";
+
+export function useEnrichedSkills(open: boolean): EnrichedSkill[] {
+  const [skills, setSkills] = useState<EnrichedSkill[]>([]);
+  useEffect(() => {
+    if (!open) return;
+    const controller = new AbortController();
+    fetch("/api/environment/skills", { signal: controller.signal })
+      .then((r) => (r.ok ? r.json() : []))
+      .then((data) => {
+        if (Array.isArray(data)) setSkills(data);
+      })
+      .catch(() => {});
+    return () => controller.abort();
+  }, [open]);
+  return skills;
+}

package/src/hooks/use-pinned-entries.ts

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * `usePinnedEntries` — client-side store for chat mention-popover pins.
+ *
+ * Fetches once on mount, keeps an in-memory list in React state, and writes
+ * back via PUT on every mutation (full-list replacement — see
+ * `src/app/api/settings/chat/pins/route.ts` for design rationale).
+ *
+ * Exposes:
+ *  - `pins`: current pinned entries (stable identity per mount)
+ *  - `isPinned(id)`: fast membership check
+ *  - `pin(entry)` / `unpin(id)`: optimistic mutations with background sync
+ *  - `loading`: true while the initial GET is in flight
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+export interface PinnedEntry {
+  id: string;
+  type: string;
+  label: string;
+  description?: string;
+  status?: string;
+  pinnedAt: string;
+}
+
+interface UsePinnedEntriesReturn {
+  pins: PinnedEntry[];
+  loading: boolean;
+  isPinned: (id: string) => boolean;
+  pin: (entry: Omit<PinnedEntry, "pinnedAt">) => void;
+  unpin: (id: string) => void;
+}
+
+export function usePinnedEntries(): UsePinnedEntriesReturn {
+  const [pins, setPins] = useState<PinnedEntry[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch("/api/settings/chat/pins")
+      .then((r) => (r.ok ? r.json() : { pins: [] }))
+      .then((data: { pins?: PinnedEntry[] }) => {
+        if (!cancelled) setPins(data.pins ?? []);
+      })
+      .catch(() => {
+        // Network / parse failure: start with empty list. Subsequent writes
+        // will create the setting on first mutation.
+        if (!cancelled) setPins([]);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const pinnedIdSet = useMemo(() => new Set(pins.map((p) => p.id)), [pins]);
+
+  const isPinned = useCallback(
+    (id: string) => pinnedIdSet.has(id),
+    [pinnedIdSet]
+  );
+
+  const persist = useCallback(async (next: PinnedEntry[]) => {
+    try {
+      await fetch("/api/settings/chat/pins", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ pins: next }),
+      });
+    } catch {
+      // Optimistic update already applied; server sync failure is silently
+      // swallowed. A future follow-up can add a toast on persistent failure.
+    }
+  }, []);
+
+  const pin = useCallback(
+    (entry: Omit<PinnedEntry, "pinnedAt">) => {
+      if (pinnedIdSet.has(entry.id)) return;
+      const next: PinnedEntry[] = [
+        ...pins,
+        { ...entry, pinnedAt: new Date().toISOString() },
+      ];
+      setPins(next);
+      void persist(next);
+    },
+    [pins, pinnedIdSet, persist]
+  );
+
+  const unpin = useCallback(
+    (id: string) => {
+      if (!pinnedIdSet.has(id)) return;
+      const next = pins.filter((p) => p.id !== id);
+      setPins(next);
+      void persist(next);
+    },
+    [pins, pinnedIdSet, persist]
+  );
+
+  return { pins, loading, isPinned, pin, unpin };
+}

package/src/hooks/use-recent-user-messages.ts

@@ -0,0 +1,19 @@
+"use client";
+import { useMemo } from "react";
+import { useChatSession } from "@/components/chat/chat-session-provider";
+
+export function useRecentUserMessages(
+  conversationId: string | null | undefined,
+  limit: number = 20
+): string[] {
+  const { messages } = useChatSession();
+  return useMemo(() => {
+    if (!conversationId) return [];
+    return messages
+      .filter((m) => m.role === "user")
+      .slice(-limit)
+      .map((m) =>
+        typeof m.content === "string" ? m.content : JSON.stringify(m.content)
+      );
+  }, [messages, conversationId, limit]);
+}