@stigmer/react 0.0.42 → 0.0.44

package/src/mcp-server/useMcpServerCredentials.ts

@@ -0,0 +1,108 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import type { EnvVarInput } from "@stigmer/sdk";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
+import { diffEnvSpec } from "../environment/diffEnvSpec";
+import type { EnvVarFormVariable } from "../environment/EnvVarForm";
+
+export interface UseMcpServerCredentialsReturn {
+  /**
+   * Variables required by the MCP server that are missing from the
+   * user's personal environment. Empty when all variables are present
+   * or the server has no `env_spec`.
+   *
+   * Suitable as direct input to {@link EnvVarForm}.
+   */
+  readonly missingVariables: EnvVarFormVariable[];
+  /** `true` when all required credentials are available. */
+  readonly isReady: boolean;
+  /** `true` while the personal environment is being fetched. */
+  readonly isLoading: boolean;
+  /** Error from the personal environment fetch, or `null`. */
+  readonly error: Error | null;
+  /**
+   * Save the provided credentials to the user's personal environment.
+   * Creates the personal environment if it doesn't exist yet.
+   */
+  readonly saveCredentials: (
+    values: Record<string, EnvVarInput>,
+  ) => Promise<void>;
+  /** `true` while a save operation is in flight. */
+  readonly isSaving: boolean;
+  /** Re-check the personal environment. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Checks the user's personal environment against an MCP server's
+ * `env_spec` and provides a mechanism to save missing credentials.
+ *
+ * Designed for the discovery flow on the MCP server detail page:
+ * before triggering discovery, the UI needs to ensure all required
+ * environment variables (API keys, tokens) are present. This hook
+ * computes the missing set and exposes `saveCredentials` to persist
+ * them.
+ *
+ * Unlike {@link useMcpServerSetup} which manages multi-server setup
+ * for session creation, this hook is scoped to a single server and
+ * always persists to the personal environment (no one-time option).
+ *
+ * Pass `null` for `mcpServer` while loading.
+ *
+ * @example
+ * ```tsx
+ * const { missingVariables, isReady, saveCredentials, isSaving } =
+ *   useMcpServerCredentials("acme", mcpServer);
+ *
+ * if (!isReady) {
+ *   return (
+ *     <EnvVarForm
+ *       variables={missingVariables}
+ *       onSubmit={(values) => saveCredentials(values)}
+ *       isSubmitting={isSaving}
+ *       hideSaveToggle
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useMcpServerCredentials(
+  org: string | null,
+  mcpServer: McpServer | null,
+): UseMcpServerCredentialsReturn {
+  const personalEnv = usePersonalEnvironment(org);
+
+  const missingVariables = useMemo(() => {
+    if (!mcpServer) return [];
+    const envSpecData = mcpServer.spec?.envSpec?.data;
+    if (!envSpecData || Object.keys(envSpecData).length === 0) return [];
+
+    const existingKeys = new Set(
+      Object.keys(personalEnv.environment?.spec?.data ?? {}),
+    );
+    return diffEnvSpec(envSpecData, existingKeys);
+  }, [mcpServer, personalEnv.environment]);
+
+  const isReady =
+    !personalEnv.isLoading && missingVariables.length === 0;
+
+  const saveCredentials = useCallback(
+    async (values: Record<string, EnvVarInput>): Promise<void> => {
+      await personalEnv.getOrCreate();
+      await personalEnv.addVariables(values);
+    },
+    [personalEnv],
+  );
+
+  return {
+    missingVariables,
+    isReady,
+    isLoading: personalEnv.isLoading,
+    error: personalEnv.error,
+    saveCredentials,
+    isSaving: personalEnv.isMutating,
+    refetch: personalEnv.refetch,
+  };
+}

package/src/mcp-server/useTriggerApprovalPolicySession.ts

@@ -0,0 +1,161 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { UploadAttachmentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { PENDING_SUBJECT } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface TriggerApprovalPolicyResult {
+  readonly sessionId: string;
+  readonly executionId: string;
+}
+
+export interface UseTriggerApprovalPolicySessionReturn {
+  /**
+   * Create an agent session with the `mcp-server-creator` agent, attach the
+   * current MCP server YAML, and start an execution that generates approval
+   * policies for the discovered tools.
+   *
+   * @param mcpServerYaml - Serialized MCP server YAML to attach as input.
+   * @param org - Organization slug.
+   * @param mcpServerSlug - MCP server slug (for context in the prompt).
+   */
+  readonly trigger: (
+    mcpServerYaml: string,
+    org: string,
+    mcpServerSlug: string,
+  ) => Promise<TriggerApprovalPolicyResult>;
+  readonly isTriggering: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+  readonly result: TriggerApprovalPolicyResult | null;
+}
+
+const MCP_SERVER_CREATOR_SLUG = "mcp-server-creator";
+const MCP_SERVER_CREATOR_ORG = "stigmer";
+
+/**
+ * Orchestration hook that auto-creates a session with the `mcp-server-creator`
+ * agent and starts an execution with a pre-filled prompt and YAML attachment.
+ *
+ * The prompt instructs the agent to read the attached YAML, query the
+ * discovered tools for this MCP server, classify each tool's risk level,
+ * and generate `default_tool_approvals` entries with appropriate approval
+ * messages. The agent applies the result using the `apply_mcp_server` tool.
+ *
+ * @example
+ * ```tsx
+ * const { trigger, isTriggering, result } = useTriggerApprovalPolicySession();
+ *
+ * async function handleGenerate() {
+ *   const yaml = serializeMcpServer(mcpServer);
+ *   await trigger(yaml, org, slug);
+ *   // result.sessionId and result.executionId are now available
+ * }
+ * ```
+ */
+export function useTriggerApprovalPolicySession(): UseTriggerApprovalPolicySessionReturn {
+  const stigmer = useStigmer();
+  const [isTriggering, setIsTriggering] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [result, setResult] = useState<TriggerApprovalPolicyResult | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const trigger = useCallback(
+    async (
+      mcpServerYaml: string,
+      org: string,
+      mcpServerSlug: string,
+    ): Promise<TriggerApprovalPolicyResult> => {
+      setIsTriggering(true);
+      setError(null);
+
+      try {
+        const agent = await stigmer.agent.getByReference({
+          org: MCP_SERVER_CREATOR_ORG,
+          slug: MCP_SERVER_CREATOR_SLUG,
+        });
+
+        const defaultInstanceId = agent.status?.defaultInstanceId;
+        if (!defaultInstanceId) {
+          throw new Error(
+            `Agent "${MCP_SERVER_CREATOR_ORG}/${MCP_SERVER_CREATOR_SLUG}" does not have a ` +
+              "default instance. Ensure the mcp-server-creator agent is properly set up.",
+          );
+        }
+
+        const session = await stigmer.session.create({
+          name: `approval-policy-${mcpServerSlug}-${Date.now()}`,
+          org,
+          subject: PENDING_SUBJECT,
+          agentInstanceId: defaultInstanceId,
+        });
+
+        const sessionId = session.metadata!.id;
+        const fileName = `${mcpServerSlug}.yaml`;
+
+        const attachment = await stigmer.agentExecution.uploadAttachment(
+          create(UploadAttachmentRequestSchema, {
+            filename: fileName,
+            content: new TextEncoder().encode(mcpServerYaml),
+            contentType: "application/x-yaml",
+          }),
+        );
+
+        const prompt = buildApprovalPolicyPrompt(mcpServerSlug, org);
+
+        const execution = await stigmer.agentExecution.create({
+          name: `gen-approval-policy-${Date.now()}`,
+          org,
+          sessionId,
+          message: prompt,
+          attachments: [
+            {
+              storageKey: attachment.storageKey,
+              filename: fileName,
+            },
+          ],
+        });
+
+        const triggerResult: TriggerApprovalPolicyResult = {
+          sessionId,
+          executionId: execution.metadata!.id,
+        };
+
+        setResult(triggerResult);
+        return triggerResult;
+      } catch (err) {
+        const wrapped = toError(err);
+        setError(wrapped);
+        throw wrapped;
+      } finally {
+        setIsTriggering(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { trigger, isTriggering, error, clearError, result };
+}
+
+function buildApprovalPolicyPrompt(slug: string, org: string): string {
+  return [
+    `Generate default tool approval policies for the MCP server "${org}/${slug}".`,
+    "",
+    "Instructions:",
+    "1. Read the attached YAML file — it contains the full MCP server definition.",
+    `2. Use the get_mcp_server tool to fetch the latest version of "${org}/${slug}" including its discovered capabilities.`,
+    "3. For each discovered tool, classify its risk level:",
+    "   - **Low risk** (read-only queries, searches): No approval needed — do NOT add an entry.",
+    "   - **Medium risk** (creates/modifies resources): Add an entry with a clear approval message.",
+    "   - **High risk** (deletes, destructive operations): Add an entry with a detailed approval message including relevant parameter placeholders ({{args.field}}).",
+    "4. Generate the `default_tool_approvals` section in the YAML.",
+    "5. Apply the updated YAML using the apply_mcp_server tool.",
+    "",
+    "The approval message should be human-readable and explain what the tool will do,",
+    "using {{args.field}} placeholders for dynamic content where appropriate.",
+  ].join("\n");
+}

package/src/session/__tests__/useSessionConversation.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { renderHook, act, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { create } from "@bufbuild/protobuf";
@@ -7,7 +7,8 @@ import {
   AgentExecutionStatusSchema,
   type AgentExecution,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import type { Stigmer } from "@stigmer/sdk";
@@ -33,6 +34,13 @@ function makeExecution(id: string, phase: ExecutionPhase): AgentExecution {
   return exec;
 }
 
+function addPendingApproval(exec: AgentExecution, toolCallId: string) {
+  const pa = create(PendingApprovalSchema);
+  pa.toolCallId = toolCallId;
+  pa.toolName = "test_tool";
+  exec.status!.pendingApprovals.push(pa);
+}
+
 /**
  * Creates a controllable async generator for streaming.
  */
@@ -302,4 +310,349 @@ describe("useSessionConversation", () => {
       expect(result.current.pendingUserMessage).toBeNull();
     });
   });
+
+  // -------------------------------------------------------------------------
+  // Task 3: Exponential backoff polling for missing approval data
+  // -------------------------------------------------------------------------
+
+  describe("approval poll backoff", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    async function renderWaitingHook(
+      m: MockMethods,
+      client: Stigmer,
+      exec: AgentExecution,
+    ) {
+      m.listBySession.mockResolvedValue({ entries: [exec] });
+      const pollStream = createControllableStream<AgentExecution>();
+      m.subscribe.mockReturnValue(pollStream.generator);
+
+      const hook = renderHook(
+        () => useSessionConversation("session-1", "org"),
+        { wrapper: createWrapper(client) },
+      );
+
+      await act(async () => {});
+      act(() => {
+        pollStream.push(exec);
+      });
+      await act(async () => {});
+
+      return { ...hook, pollStream };
+    }
+
+    it("polls with exponential backoff when WAITING_FOR_APPROVAL with empty raw approvals", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+
+      const { result } = await renderWaitingHook(methods, mockStigmer, exec);
+
+      expect(result.current.activePhase).toBe(
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+      expect(result.current.pendingApprovals).toHaveLength(0);
+
+      const baseline = methods.listBySession.mock.calls.length;
+
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline + 1);
+
+      await act(async () => {
+        vi.advanceTimersByTime(6000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline + 2);
+
+      await act(async () => {
+        vi.advanceTimersByTime(12000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline + 3);
+    });
+
+    it("stops polling when raw approvals arrive via stream", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+
+      const { result, pollStream } = await renderWaitingHook(
+        methods,
+        mockStigmer,
+        exec,
+      );
+
+      const baseline = methods.listBySession.mock.calls.length;
+
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline + 1);
+
+      const updated = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+      addPendingApproval(updated, "tc-1");
+      act(() => {
+        pollStream.push(updated);
+      });
+      await act(async () => {});
+
+      expect(result.current.pendingApprovals).toHaveLength(1);
+
+      const afterArrival = methods.listBySession.mock.calls.length;
+
+      await act(async () => {
+        vi.advanceTimersByTime(60000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(afterArrival);
+    });
+
+    it("stops polling when phase transitions away", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+
+      const { pollStream } = await renderWaitingHook(
+        methods,
+        mockStigmer,
+        exec,
+      );
+
+      const completed = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_COMPLETED,
+      );
+      act(() => {
+        pollStream.push(completed);
+      });
+      await act(async () => {});
+
+      const afterTransition = methods.listBySession.mock.calls.length;
+
+      await act(async () => {
+        vi.advanceTimersByTime(60000);
+      });
+      // Terminal-phase effect fires one refetch; no further polling.
+      expect(methods.listBySession.mock.calls.length).toBeLessThanOrEqual(
+        afterTransition + 1,
+      );
+    });
+
+    it("does not poll when raw approvals exist but are all dismissed", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+      addPendingApproval(exec, "tc-1");
+
+      const { result } = await renderWaitingHook(methods, mockStigmer, exec);
+
+      expect(result.current.pendingApprovals).toHaveLength(1);
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+      expect(result.current.pendingApprovals).toHaveLength(0);
+
+      const baseline = methods.listBySession.mock.calls.length;
+
+      // At 3s (poll initial delay) — should NOT fire because raw approvals
+      // are non-empty; only the staleness mechanism handles this case.
+      await act(async () => {
+        vi.advanceTimersByTime(3000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline);
+    });
+
+    it("cleans up timeout on unmount", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+
+      const { unmount } = await renderWaitingHook(methods, mockStigmer, exec);
+
+      const baseline = methods.listBySession.mock.calls.length;
+
+      unmount();
+
+      await act(async () => {
+        vi.advanceTimersByTime(60000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBe(baseline);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Task 4: Staleness detection for optimistic dismissals
+  // -------------------------------------------------------------------------
+
+  describe("staleness detection", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    async function renderWithApproval(
+      m: MockMethods,
+      client: Stigmer,
+    ) {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      );
+      addPendingApproval(exec, "tc-1");
+      m.listBySession.mockResolvedValue({ entries: [exec] });
+
+      const testStream = createControllableStream<AgentExecution>();
+      m.subscribe.mockReturnValue(testStream.generator);
+
+      const hook = renderHook(
+        () => useSessionConversation("session-1", "org"),
+        { wrapper: createWrapper(client) },
+      );
+
+      await act(async () => {});
+      act(() => {
+        testStream.push(exec);
+      });
+      await act(async () => {});
+
+      return { ...hook, testStream, exec };
+    }
+
+    it("reappears dismissed approval card after staleness threshold", async () => {
+      const { result } = await renderWithApproval(methods, mockStigmer);
+
+      expect(result.current.pendingApprovals).toHaveLength(1);
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+      expect(result.current.pendingApprovals).toHaveLength(0);
+      expect(result.current.dismissedApprovalIds.has("tc-1")).toBe(true);
+
+      // Before threshold: card stays hidden (15s covers interval ticks at 5s, 10s, 15s)
+      await act(async () => {
+        vi.advanceTimersByTime(15000);
+      });
+      expect(result.current.pendingApprovals).toHaveLength(0);
+
+      // Past threshold: interval fires at 20s, age > 15s → stale → card reappears
+      await act(async () => {
+        vi.advanceTimersByTime(5000);
+      });
+      expect(result.current.pendingApprovals).toHaveLength(1);
+      expect(result.current.dismissedApprovalIds.has("tc-1")).toBe(false);
+    });
+
+    it("does not run staleness check when phase is not WAITING_FOR_APPROVAL", async () => {
+      const exec = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_IN_PROGRESS,
+      );
+      addPendingApproval(exec, "tc-1");
+      methods.listBySession.mockResolvedValue({ entries: [exec] });
+
+      const testStream = createControllableStream<AgentExecution>();
+      methods.subscribe.mockReturnValue(testStream.generator);
+
+      const { result } = renderHook(
+        () => useSessionConversation("session-1", "org"),
+        { wrapper: createWrapper(mockStigmer) },
+      );
+
+      await act(async () => {});
+      act(() => {
+        testStream.push(exec);
+      });
+      await act(async () => {});
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+      expect(result.current.dismissedApprovalIds.has("tc-1")).toBe(true);
+
+      // Advance well past threshold — staleness detection should not run
+      await act(async () => {
+        vi.advanceTimersByTime(60000);
+      });
+      expect(result.current.dismissedApprovalIds.has("tc-1")).toBe(true);
+    });
+
+    it("triggers refetch when stale entries are detected", async () => {
+      const { result } = await renderWithApproval(methods, mockStigmer);
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+
+      const baseline = methods.listBySession.mock.calls.length;
+
+      // Advance to 20s — staleness fires, should call refetch
+      await act(async () => {
+        vi.advanceTimersByTime(20000);
+      });
+      expect(methods.listBySession.mock.calls.length).toBeGreaterThan(
+        baseline,
+      );
+    });
+
+    it("dismissedApprovalIds remains a ReadonlySet<string>", async () => {
+      const { result } = await renderWithApproval(methods, mockStigmer);
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+
+      const ids = result.current.dismissedApprovalIds;
+      expect(ids).toBeInstanceOf(Set);
+      expect(ids.has("tc-1")).toBe(true);
+      expect(typeof ids.has).toBe("function");
+      // Verify it behaves as a Set (not a Map)
+      expect([...ids]).toEqual(["tc-1"]);
+    });
+
+    it("resets dismissed state on new execution", async () => {
+      const { result, testStream } = await renderWithApproval(
+        methods,
+        mockStigmer,
+      );
+
+      await act(async () => {
+        await result.current.submitApproval("tc-1", ApprovalAction.APPROVE);
+      });
+      expect(result.current.dismissedApprovalIds.size).toBe(1);
+
+      // Stream delivers terminal phase
+      const completed = makeExecution(
+        "e1",
+        ExecutionPhase.EXECUTION_COMPLETED,
+      );
+      // Update mock so the refetch sees the completed execution — this
+      // causes listActiveId to clear, which changes activeExecutionId
+      // and triggers the dismissed-state reset effect.
+      methods.listBySession.mockResolvedValue({ entries: [completed] });
+      act(() => {
+        testStream.push(completed);
+      });
+      await act(async () => {});
+
+      expect(result.current.dismissedApprovalIds.size).toBe(0);
+    });
+  });
 });