@stigmer/react 0.0.52 → 0.0.54

package/src/github/index.ts

@@ -13,6 +13,11 @@ export {
   type UseGitHubReposReturn,
 } from "./useGitHubRepos";
 
+export {
+  useGitHubSearch,
+  type UseGitHubSearchReturn,
+} from "./useGitHubSearch";
+
 export {
   GitHubRepoPicker,
   type GitHubRepoPickerProps,

package/src/github/useGitHubSearch.ts

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { GitHubRepo } from "./useGitHubRepos";
+
+const GITHUB_SEARCH_API = "https://api.github.com/search/repositories";
+const DEBOUNCE_MS = 350;
+const PER_PAGE = 30;
+
+export interface UseGitHubSearchReturn {
+  readonly results: readonly GitHubRepo[];
+  readonly isSearching: boolean;
+  readonly error: string | null;
+  readonly query: string;
+  readonly setQuery: (query: string) => void;
+  readonly totalCount: number;
+  readonly hasMore: boolean;
+  readonly loadMore: () => void;
+}
+
+function parseSearchItem(r: Record<string, unknown>): GitHubRepo {
+  const ownerObj = r.owner as Record<string, unknown>;
+  return {
+    id: r.id as number,
+    fullName: r.full_name as string,
+    name: r.name as string,
+    owner: ownerObj.login as string,
+    ownerType:
+      (ownerObj.type as string) === "Organization" ? "Organization" : "User",
+    htmlUrl: r.html_url as string,
+    cloneUrl: r.clone_url as string,
+    defaultBranch: r.default_branch as string,
+    isPrivate: r.private as boolean,
+    updatedAt: r.updated_at as string,
+  };
+}
+
+async function searchRepos(
+  query: string,
+  page: number,
+  token: string | null,
+): Promise<{ repos: GitHubRepo[]; totalCount: number; hasMore: boolean }> {
+  const params = new URLSearchParams({
+    q: query,
+    sort: "stars",
+    order: "desc",
+    per_page: String(PER_PAGE),
+    page: String(page),
+  });
+
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+  };
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const resp = await fetch(`${GITHUB_SEARCH_API}?${params}`, { headers });
+
+  if (!resp.ok) {
+    if (resp.status === 403) {
+      throw new Error("GitHub search rate limit exceeded. Try again shortly.");
+    }
+    throw new Error(`GitHub search error: ${resp.status}`);
+  }
+
+  const data = (await resp.json()) as {
+    total_count: number;
+    items: Record<string, unknown>[];
+  };
+
+  const repos = data.items.map(parseSearchItem);
+  const totalCount = data.total_count;
+  const hasMore = page * PER_PAGE < totalCount;
+
+  return { repos, totalCount, hasMore };
+}
+
+/**
+ * Data hook that searches GitHub's public repository index.
+ *
+ * Uses the GitHub Search API (`/search/repositories`) with debounced input.
+ * Finds repositories across all of GitHub, not just the user's own repos.
+ * Works with or without an auth token (auth: 30 req/min; unauth: 10 req/min).
+ */
+export function useGitHubSearch(
+  token: string | null,
+): UseGitHubSearchReturn {
+  const [query, setQuery] = useState("");
+  const [debouncedQuery, setDebouncedQuery] = useState("");
+  const [results, setResults] = useState<GitHubRepo[]>([]);
+  const [isSearching, setIsSearching] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [totalCount, setTotalCount] = useState(0);
+  const [hasMore, setHasMore] = useState(false);
+  const [page, setPage] = useState(1);
+  const debounceTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  useEffect(() => {
+    clearTimeout(debounceTimer.current);
+    if (!query.trim()) {
+      setDebouncedQuery("");
+      setResults([]);
+      setTotalCount(0);
+      setHasMore(false);
+      setError(null);
+      return;
+    }
+    debounceTimer.current = setTimeout(() => {
+      setDebouncedQuery(query.trim());
+      setPage(1);
+    }, DEBOUNCE_MS);
+    return () => clearTimeout(debounceTimer.current);
+  }, [query]);
+
+  useEffect(() => {
+    if (!debouncedQuery) return;
+
+    const cancelled = { current: false };
+
+    async function run() {
+      setIsSearching(true);
+      setError(null);
+      try {
+        const result = await searchRepos(debouncedQuery, page, token);
+        if (cancelled.current) return;
+        setResults((prev) =>
+          page === 1 ? result.repos : [...prev, ...result.repos],
+        );
+        setTotalCount(result.totalCount);
+        setHasMore(result.hasMore);
+      } catch (e) {
+        if (cancelled.current) return;
+        setError(e instanceof Error ? e.message : "Search failed");
+      } finally {
+        if (!cancelled.current) setIsSearching(false);
+      }
+    }
+
+    run();
+    return () => {
+      cancelled.current = true;
+    };
+  }, [debouncedQuery, page, token]);
+
+  const loadMore = useCallback(() => {
+    if (hasMore && !isSearching) {
+      setPage((prev) => prev + 1);
+    }
+  }, [hasMore, isSearching]);
+
+  return {
+    results,
+    isSearching,
+    error,
+    query,
+    setQuery,
+    totalCount,
+    hasMore,
+    loadMore,
+  };
+}

package/src/index.ts

@@ -5,6 +5,11 @@ export { StigmerContext } from "./context";
 // Hooks
 export { useStigmer } from "./hooks";
 
+// Deployment mode and resource availability
+export { useDeploymentMode, useResourceAvailable } from "./deployment-mode";
+export { type DeploymentMode, isResourceAvailable, ApiResourceKind } from "@stigmer/sdk";
+export { CloudFeatureNotice, type CloudFeatureNoticeProps } from "./internal/CloudFeatureNotice";
+
 // Models — data hook, styled component, and registry data
 export {
   MODEL_REGISTRY,
@@ -47,6 +52,8 @@ export {
   useSessionList,
   useSessionExecutions,
   useSessionConversation,
+  useSessionArtifacts,
+  useSessionWriteBacks,
   useAgentRefFromSession,
   groupSessionsByTime,
   PENDING_SUBJECT,
@@ -63,6 +70,10 @@ export type {
   UseSessionExecutionsReturn,
   SendFollowUpOptions,
   UseSessionConversationReturn,
+  SessionArtifactEntry,
+  UseSessionArtifactsReturn,
+  SessionWriteBackEntry,
+  UseSessionWriteBacksReturn,
   UseAgentRefFromSessionReturn,
   SessionGroup,
 } from "./session";
@@ -81,7 +92,10 @@ export {
   ExecutionCostSummary,
   ToolCallGroup,
   ToolCallDetail,
+  McpToolDetail,
+  parseMcpResult,
   formatDuration,
+  humanizeToolName,
   ToolCallItem,
   SubAgentSection,
   MessageEntry,
@@ -92,6 +106,10 @@ export {
   ArtifactContentRenderer,
   ArtifactPreviewModal,
   ArtifactsWidget,
+  WriteBacksWidget,
+  ToolArgsView,
+  McpArgsView,
+  McpMetadataRow,
   FilePathLink,
   FilePathContext,
   classifyPath,
@@ -101,6 +119,8 @@ export {
   SessionVariablesInput,
   useExecutionArtifacts,
   useArtifactContent,
+  useWorkspaceWriteBacks,
+  WriteBackCard,
   isTextArtifact,
   isArtifactExpired,
   formatArtifactSize,
@@ -121,6 +141,8 @@ export type {
   ExecutionCostSummaryProps,
   ToolCallGroupProps,
   ToolCallDetailProps,
+  McpToolDetailProps,
+  ToolArgsViewProps,
   ToolCallItemProps,
   SubAgentSectionProps,
   MessageEntryProps,
@@ -132,6 +154,7 @@ export type {
   ArtifactRenderMode,
   ArtifactPreviewModalProps,
   ArtifactsWidgetProps,
+  WriteBacksWidgetProps,
   FilePathLinkProps,
   FilePathContextValue,
   PathClassification,
@@ -141,6 +164,8 @@ export type {
   SessionVariablesInputProps,
   UseExecutionArtifactsReturn,
   UseArtifactContentReturn,
+  UseWorkspaceWriteBacksReturn,
+  WriteBackCardProps,
 } from "./execution";
 
 // Execution — proto type re-exports for artifact consumers
@@ -244,6 +269,7 @@ export type {
 export {
   useGitHubConnection,
   useGitHubRepos,
+  useGitHubSearch,
   GitHubRepoPicker,
   GITHUB_CALLBACK_MESSAGE_TYPE,
 } from "./github";
@@ -254,6 +280,7 @@ export type {
   GitHubRepo,
   GitHubBranch,
   UseGitHubReposReturn,
+  UseGitHubSearchReturn,
   GitHubRepoPickerProps,
 } from "./github";
 

package/src/internal/CloudFeatureNotice.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+
+export interface CloudFeatureNoticeProps {
+  /** Explanation of why the feature is unavailable and what to do instead. */
+  readonly children: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * Subdued info notice displayed in place of cloud-only feature content
+ * when the connected Stigmer backend does not support the feature.
+ *
+ * Renders an inline box with an info icon and the provided message.
+ * The parent section provides its own heading and description — this
+ * component is purely the "why it's absent" explanation.
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * No Console-specific dependencies — safe for platform builder embedding.
+ */
+export function CloudFeatureNotice({
+  children,
+  className,
+}: CloudFeatureNoticeProps) {
+  return (
+    <div
+      role="status"
+      className={cn(
+        "bg-muted/50 text-muted-foreground flex items-start gap-2.5 rounded-lg border border-transparent px-4 py-3",
+        className,
+      )}
+    >
+      <InfoIcon className="mt-0.5 size-4 shrink-0" />
+      <p className="text-xs leading-relaxed">{children}</p>
+    </div>
+  );
+}
+
+function InfoIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="8" r="6.25" />
+      <path d="M8 7v4" />
+      <circle cx="8" cy="5" r="0.5" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}

package/src/mcp-server/McpServerDetailView.tsx

@@ -46,6 +46,20 @@ export interface McpServerDetailViewProps {
   readonly onVisibilityChange?: (v: ApiResourceVisibility) => void;
   /** `true` while a visibility update RPC is in flight. */
   readonly isVisibilityPending?: boolean;
+  /**
+   * Called after the approval-policy generation session and execution
+   * have been created successfully.
+   *
+   * When provided, the component delegates post-trigger behavior to the
+   * consumer (e.g. navigating to a session page) instead of rendering
+   * the inline {@link ApprovalPolicyGeneratorPanel}.
+   *
+   * When omitted, the inline panel is shown as a fallback.
+   */
+  readonly onPolicySessionCreated?: (info: {
+    sessionId: string;
+    executionId: string;
+  }) => void;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -78,6 +92,7 @@ export function McpServerDetailView({
   onResourceLoad,
   onVisibilityChange,
   isVisibilityPending,
+  onPolicySessionCreated,
   className,
 }: McpServerDetailViewProps) {
   const { mcpServer, isLoading, error, refetch } = useMcpServer(org, slug);
@@ -149,11 +164,18 @@ export function McpServerDetailView({
     try {
       const yaml = serializeMcpServerYaml(mcpServer);
       const result = await policySession.trigger(yaml, org, slug);
-      setPolicyPanelExecutionId(result.executionId);
+      if (onPolicySessionCreated) {
+        onPolicySessionCreated({
+          sessionId: result.sessionId,
+          executionId: result.executionId,
+        });
+      } else {
+        setPolicyPanelExecutionId(result.executionId);
+      }
     } catch {
       // error state is managed by the hook
     }
-  }, [mcpServer, org, slug, policySession]);
+  }, [mcpServer, org, slug, policySession, onPolicySessionCreated]);
 
   const handlePolicyPanelComplete = useCallback(() => {
     refetch();

package/src/provider.tsx

@@ -1,15 +1,28 @@
 "use client";
 
 import type { ReactNode } from "react";
-import type { Stigmer } from "@stigmer/sdk";
+import type { Stigmer, DeploymentMode } from "@stigmer/sdk";
 import { cn, resolvePresetClass } from "@stigmer/theme";
 import type { ThemePresetId } from "@stigmer/theme";
 import { StigmerContext } from "./context";
+import { DeploymentModeContext } from "./deployment-mode";
 
 export interface StigmerProviderProps {
   /** A configured {@link Stigmer} client instance. */
   readonly client: Stigmer;
   readonly children: ReactNode;
+  /**
+   * Deployment mode of the connected Stigmer backend.
+   *
+   * - `"local"` — local Go CLI server (OSS). Cloud-only resources
+   *   (API keys, IAM, identity management) are unavailable.
+   * - `"cloud"` — Stigmer Cloud. All resources are available.
+   *
+   * Defaults to `"cloud"` so existing consumers see no change.
+   * The Stigmer Console derives this from the API URL hostname.
+   * Platform builders pass it based on their deployment context.
+   */
+  readonly deploymentMode?: DeploymentMode;
   /**
    * Built-in theme preset to apply.
    *
@@ -60,6 +73,7 @@ export interface StigmerProviderProps {
 export function StigmerProvider({
   client,
   children,
+  deploymentMode = "cloud",
   preset,
   className,
 }: StigmerProviderProps) {
@@ -67,7 +81,9 @@ export function StigmerProvider({
 
   return (
     <StigmerContext.Provider value={client}>
-      <div className={cn("stgm", presetClass, className)}>{children}</div>
+      <DeploymentModeContext.Provider value={deploymentMode}>
+        <div className={cn("stgm", presetClass, className)}>{children}</div>
+      </DeploymentModeContext.Provider>
     </StigmerContext.Provider>
   );
 }

package/src/session/index.ts

@@ -26,6 +26,18 @@ export type {
   UseSessionConversationReturn,
 } from "./useSessionConversation";
 
+export { useSessionArtifacts } from "./useSessionArtifacts";
+export type {
+  SessionArtifactEntry,
+  UseSessionArtifactsReturn,
+} from "./useSessionArtifacts";
+
+export { useSessionWriteBacks } from "./useSessionWriteBacks";
+export type {
+  SessionWriteBackEntry,
+  UseSessionWriteBacksReturn,
+} from "./useSessionWriteBacks";
+
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
 

package/src/session/useSessionArtifacts.ts

@@ -0,0 +1,143 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "../execution/execution-phases";
+
+/**
+ * A single artifact entry enriched with the execution context needed
+ * for content fetching and Apply/Push gating.
+ *
+ * The `executionId` identifies which execution produced (or last
+ * updated) this artifact — required by {@link useArtifactContent} and
+ * {@link ArtifactPreviewModal}. `isTerminal` controls whether the
+ * Apply CTA is enabled in the preview modal.
+ */
+export interface SessionArtifactEntry {
+  readonly artifact: ExecutionArtifact;
+  /** ID of the execution that produced this artifact version. */
+  readonly executionId: string;
+  /** Whether the producing execution is in a terminal phase. */
+  readonly isTerminal: boolean;
+  /**
+   * `true` when another artifact in the deduplicated list shares the
+   * same display `name` but has a different `sandbox_path`. Consumers
+   * use this to render path context for disambiguation.
+   */
+  readonly hasNameCollision: boolean;
+}
+
+export interface UseSessionArtifactsReturn {
+  /** Deduplicated, alphabetically-sorted artifacts from all executions. */
+  readonly artifacts: readonly SessionArtifactEntry[];
+  /** `true` when there is at least one artifact across all executions. */
+  readonly hasArtifacts: boolean;
+  /** Total number of deduplicated artifacts. */
+  readonly artifactCount: number;
+}
+
+/**
+ * Returns the dedup key for an artifact. Uses `sandbox_path` when
+ * available (stable filesystem identity within the session sandbox),
+ * falling back to `name` for older artifacts that predate the field.
+ */
+function dedupKey(artifact: ExecutionArtifact): string {
+  return artifact.sandboxPath || artifact.name;
+}
+
+/**
+ * Pure derivation hook that aggregates artifacts across all executions
+ * in a session into a unified, deduplicated, alphabetically-sorted
+ * list — like a file explorer showing the conversation's output.
+ *
+ * Follows the same `useMemo`-based pattern as
+ * {@link useExecutionArtifacts}: no side effects, no data fetching.
+ *
+ * **Dedup semantics:** Artifacts are keyed by `sandbox_path` (the
+ * original filesystem path in the agent sandbox). When multiple
+ * executions produce an artifact at the same path, the latest
+ * execution's version wins — matching filesystem overwrite semantics.
+ *
+ * **Sorting:** Entries are sorted alphabetically by display `name`
+ * (case-insensitive). This matches the file-explorer mental model
+ * where users scan by filename, not by creation order.
+ *
+ * **Name collision detection:** When two artifacts share the same
+ * display `name` but differ in `sandbox_path`, both entries are
+ * flagged with `hasNameCollision: true` so consumers can render path
+ * context for disambiguation.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order (as returned by `listBySession`). Pass both completed and
+ *   active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { artifacts, hasArtifacts } = useSessionArtifacts(allExecutions);
+ * ```
+ *
+ * @see useExecutionArtifacts — single-execution artifact derivation
+ * @see ArtifactsWidget — styled component that renders this data
+ */
+export function useSessionArtifacts(
+  executions: readonly AgentExecution[],
+): UseSessionArtifactsReturn {
+  return useMemo(() => {
+    const entryMap = new Map<string, SessionArtifactEntry>();
+
+    for (const execution of executions) {
+      const executionId = execution.metadata?.id ?? "";
+      const phase =
+        execution.status?.phase ??
+        ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      const terminal = isTerminalPhase(phase);
+
+      for (const artifact of execution.status?.artifacts ?? []) {
+        const key = dedupKey(artifact);
+        entryMap.set(key, {
+          artifact,
+          executionId,
+          isTerminal: terminal,
+          hasNameCollision: false,
+        });
+      }
+    }
+
+    const entries = Array.from(entryMap.values());
+
+    entries.sort((a, b) =>
+      a.artifact.name.localeCompare(b.artifact.name, undefined, {
+        sensitivity: "base",
+      }),
+    );
+
+    // Detect name collisions: entries that share a display name but
+    // have different sandbox paths need path context for disambiguation.
+    const nameCount = new Map<string, number>();
+    for (const entry of entries) {
+      const lower = entry.artifact.name.toLowerCase();
+      nameCount.set(lower, (nameCount.get(lower) ?? 0) + 1);
+    }
+
+    const result: SessionArtifactEntry[] = entries.map((entry) => {
+      const lower = entry.artifact.name.toLowerCase();
+      if ((nameCount.get(lower) ?? 0) > 1) {
+        return { ...entry, hasNameCollision: true };
+      }
+      return entry;
+    });
+
+    return {
+      artifacts: result,
+      hasArtifacts: result.length > 0,
+      artifactCount: result.length,
+    };
+  }, [executions]);
+}

package/src/session/useSessionWriteBacks.ts

@@ -0,0 +1,94 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+/**
+ * A single write-back entry enriched with the execution context that
+ * produced it.
+ *
+ * The `executionId` links the write-back to its originating execution
+ * for traceability in the UI (e.g., tooltip or detail view).
+ */
+export interface SessionWriteBackEntry {
+  readonly writeBack: WorkspaceWriteBack;
+  /** ID of the execution that produced this write-back. */
+  readonly executionId: string;
+}
+
+export interface UseSessionWriteBacksReturn {
+  /** All write-backs from the session, ordered by workspace entry name. */
+  readonly writeBacks: readonly SessionWriteBackEntry[];
+  /** `true` when there is at least one write-back across all executions. */
+  readonly hasWriteBacks: boolean;
+  /** Total number of write-backs. */
+  readonly writeBackCount: number;
+}
+
+/**
+ * Pure derivation hook that aggregates workspace write-backs across all
+ * executions in a session into a flat, deduplicated list.
+ *
+ * Follows the same pattern as {@link useSessionArtifacts}: `useMemo`-based
+ * derivation, no side effects, no data fetching. Takes the same
+ * `executions` array input.
+ *
+ * **Dedup semantics:** Write-backs are keyed by `workspace_entry_name`.
+ * When multiple executions write back to the same workspace entry (e.g.,
+ * a follow-up execution on the same git repo), the latest execution's
+ * write-back wins — each execution creates its own branch/PR, and the
+ * most recent one is the one users care about.
+ *
+ * **Sorting:** Entries are sorted alphabetically by workspace entry name.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order. Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { writeBacks, hasWriteBacks } = useSessionWriteBacks(allExecutions);
+ * ```
+ *
+ * @see useWorkspaceWriteBacks — single-execution write-back derivation
+ * @see WriteBackCard — component that renders a single write-back
+ */
+export function useSessionWriteBacks(
+  executions: readonly AgentExecution[],
+): UseSessionWriteBacksReturn {
+  return useMemo(() => {
+    const entryMap = new Map<string, SessionWriteBackEntry>();
+
+    for (const execution of executions) {
+      const executionId = execution.metadata?.id ?? "";
+
+      for (const wb of execution.status?.workspaceWriteBacks ?? []) {
+        entryMap.set(wb.workspaceEntryName, {
+          writeBack: wb,
+          executionId,
+        });
+      }
+    }
+
+    const entries = Array.from(entryMap.values());
+
+    entries.sort((a, b) =>
+      a.writeBack.workspaceEntryName.localeCompare(
+        b.writeBack.workspaceEntryName,
+        undefined,
+        { sensitivity: "base" },
+      ),
+    );
+
+    return {
+      writeBacks: entries,
+      hasWriteBacks: entries.length > 0,
+      writeBackCount: entries.length,
+    };
+  }, [executions]);
+}