@stigmer/react 0.0.36 → 0.0.40

package/src/execution/useSessionVariables.ts

@@ -0,0 +1,189 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { EnvVarInput } from "@stigmer/sdk";
+
+/**
+ * A single entry in the session variables editor.
+ *
+ * Each entry maps to one environment variable. When `saveForFuture`
+ * is `false` (default), the value is injected into the agent sandbox
+ * for a single execution only. When `true`, the value is persisted
+ * to the user's personal environment for reuse across sessions.
+ */
+export interface SessionVariableEntry {
+  readonly id: string;
+  readonly key: string;
+  readonly value: string;
+  readonly isSecret: boolean;
+  readonly saveForFuture: boolean;
+}
+
+export interface UseSessionVariablesReturn {
+  /** Current entries in the editor. */
+  readonly entries: readonly SessionVariableEntry[];
+  /** Append a blank entry. Defaults to `isSecret: true` (safer default). */
+  readonly addEntry: () => void;
+  /** Remove an entry by its unique ID. */
+  readonly removeEntry: (id: string) => void;
+  /** Patch one or more fields on an existing entry. */
+  readonly updateEntry: (
+    id: string,
+    patch: { key?: string; value?: string; isSecret?: boolean; saveForFuture?: boolean },
+  ) => void;
+  /** Remove all entries. Call after submission to prevent stale values. */
+  readonly clear: () => void;
+  /** True when there are no entries at all. */
+  readonly isEmpty: boolean;
+  /**
+   * True when at least one entry has a non-empty key AND non-empty value.
+   * Use this to decide whether to include `runtimeEnv` in the execution.
+   */
+  readonly hasValidEntries: boolean;
+  /**
+   * Convert valid entries to the SDK input shape for execution-scoped
+   * runtime env.
+   *
+   * Includes all entries with non-empty keys and values, regardless of
+   * `saveForFuture`. When duplicate keys exist, the last entry wins
+   * (consistent with environment semantics).
+   */
+  readonly toRuntimeEnv: () => Record<string, EnvVarInput>;
+  /**
+   * Convert valid save-for-future entries (saveForFuture === true) to
+   * the SDK input shape for personal environment persistence.
+   *
+   * Filters out entries with empty keys or values. When duplicate keys
+   * exist, the last entry wins.
+   */
+  readonly toSaveForFutureEnv: () => Record<string, EnvVarInput>;
+  /**
+   * True when at least one valid entry has `saveForFuture === true`.
+   */
+  readonly hasSaveForFutureEntries: boolean;
+}
+
+let nextId = 0;
+function uid(): string {
+  return `sv-${++nextId}-${Date.now()}`;
+}
+
+/**
+ * Behavior hook that manages an array of session variable entries for
+ * execution-scoped environment variables.
+ *
+ * Session variables are injected into the agent sandbox at execution
+ * time. By default they are ephemeral (single execution), but users
+ * can opt into persisting individual entries to their personal
+ * environment via the `saveForFuture` flag.
+ *
+ * Follows the same controlled-state pattern as {@link useWorkspaceEntries}:
+ * the consumer owns the hook instance, passes it to UI components, reads
+ * the output during submission, and calls {@link UseSessionVariablesReturn.clear}
+ * after sending to prevent stale values on the next follow-up.
+ *
+ * @example
+ * ```tsx
+ * function Chat({ sessionId, org }: { sessionId: string; org: string }) {
+ *   const conv = useSessionConversation(sessionId, org);
+ *   const sessionVariables = useSessionVariables();
+ *
+ *   const handleSubmit = (message: string, model?: string) => {
+ *     const runtimeEnv = sessionVariables.isEmpty
+ *       ? undefined
+ *       : sessionVariables.toRuntimeEnv();
+ *     conv.sendFollowUp(message, { modelName: model, runtimeEnv });
+ *     sessionVariables.clear();
+ *   };
+ *
+ *   return (
+ *     <SessionComposer
+ *       onSubmit={handleSubmit}
+ *       sessionVariables={sessionVariables}
+ *       disabled={!conv.canSendFollowUp}
+ *       isSubmitting={conv.isSending}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useSessionVariables(): UseSessionVariablesReturn {
+  const [entries, setEntries] = useState<SessionVariableEntry[]>([]);
+
+  const addEntry = useCallback(() => {
+    setEntries((prev) => [
+      ...prev,
+      { id: uid(), key: "", value: "", isSecret: true, saveForFuture: false },
+    ]);
+  }, []);
+
+  const removeEntry = useCallback((id: string) => {
+    setEntries((prev) => prev.filter((e) => e.id !== id));
+  }, []);
+
+  const updateEntry = useCallback(
+    (
+      id: string,
+      patch: { key?: string; value?: string; isSecret?: boolean; saveForFuture?: boolean },
+    ) => {
+      setEntries((prev) =>
+        prev.map((e) => (e.id === id ? { ...e, ...patch } : e)),
+      );
+    },
+    [],
+  );
+
+  const clear = useCallback(() => {
+    setEntries([]);
+  }, []);
+
+  const hasValidEntries = useMemo(
+    () => entries.some((e) => e.key.trim() !== "" && e.value.trim() !== ""),
+    [entries],
+  );
+
+  const toRuntimeEnv = useCallback((): Record<string, EnvVarInput> => {
+    const result: Record<string, EnvVarInput> = {};
+    for (const entry of entries) {
+      const key = entry.key.trim();
+      if (key === "" || entry.value.trim() === "") continue;
+      result[key] = { value: entry.value, isSecret: entry.isSecret };
+    }
+    return result;
+  }, [entries]);
+
+  const toSaveForFutureEnv = useCallback((): Record<string, EnvVarInput> => {
+    const result: Record<string, EnvVarInput> = {};
+    for (const entry of entries) {
+      const key = entry.key.trim();
+      if (key === "" || entry.value.trim() === "") continue;
+      if (!entry.saveForFuture) continue;
+      result[key] = { value: entry.value, isSecret: entry.isSecret };
+    }
+    return result;
+  }, [entries]);
+
+  const hasSaveForFutureEntries = useMemo(
+    () =>
+      entries.some(
+        (e) =>
+          e.saveForFuture &&
+          e.key.trim() !== "" &&
+          e.value.trim() !== "",
+      ),
+    [entries],
+  );
+
+  return {
+    entries,
+    addEntry,
+    removeEntry,
+    updateEntry,
+    clear,
+    isEmpty: entries.length === 0,
+    hasValidEntries,
+    toRuntimeEnv,
+    toSaveForFutureEnv,
+    hasSaveForFutureEntries,
+  };
+}

package/src/execution/useSubmitApproval.ts

@@ -0,0 +1,98 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseSubmitApprovalReturn {
+  /**
+   * Submit an approval decision for a specific tool call within an
+   * execution. Resolves when the backend accepts the decision; the
+   * execution stream will deliver the updated state.
+   */
+  readonly submitApproval: (
+    executionId: string,
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => Promise<void>;
+  /**
+   * Set of tool call IDs currently being submitted. Enables per-button
+   * loading state in batch approval scenarios where the user may
+   * approve one tool while another decision is still in flight.
+   */
+  readonly submittingToolCallIds: ReadonlySet<string>;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `agentExecution.submitApproval()` with
+ * per-tool-call loading state and error management.
+ *
+ * Tracks submitting state per tool call ID (not a single boolean)
+ * because batch approvals allow concurrent decisions on different
+ * tool calls within the same execution.
+ *
+ * Platform builders who need full control over the approval UI use
+ * this hook directly. Those who prefer drop-in components use
+ * {@link ApprovalCard} which accepts the callback shape produced
+ * by this hook.
+ *
+ * @example
+ * ```tsx
+ * const { submitApproval, submittingToolCallIds, error } = useSubmitApproval();
+ *
+ * await submitApproval(executionId, toolCallId, ApprovalAction.APPROVAL_ACTION_APPROVE);
+ * ```
+ */
+export function useSubmitApproval(): UseSubmitApprovalReturn {
+  const stigmer = useStigmer();
+  const [submittingIds, setSubmittingIds] = useState<ReadonlySet<string>>(
+    new Set(),
+  );
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const submitApproval = useCallback(
+    async (
+      executionId: string,
+      toolCallId: string,
+      action: ApprovalAction,
+      comment?: string,
+    ): Promise<void> => {
+      setSubmittingIds((prev) => {
+        const next = new Set(prev);
+        next.add(toolCallId);
+        return next;
+      });
+      setError(null);
+
+      try {
+        const input = create(SubmitApprovalInputSchema, {
+          agentExecutionId: executionId,
+          toolCallId,
+          action,
+          comment: comment ?? "",
+        });
+        await stigmer.agentExecution.submitApproval(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setSubmittingIds((prev) => {
+          const next = new Set(prev);
+          next.delete(toolCallId);
+          return next;
+        });
+      }
+    },
+    [stigmer],
+  );
+
+  return { submitApproval, submittingToolCallIds: submittingIds, error, clearError };
+}