@stigmer/react 0.0.36 → 0.0.40

package/src/agent-instance/useAgentInstanceList.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { ListAgentInstancesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseAgentInstanceListReturn {
+  readonly agentInstances: readonly AgentInstance[];
+  readonly totalCount: number;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a paginated list of {@link AgentInstance} entries
+ * for a given organization, with optional label filtering.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op). When the org
+ * or labels change, the previous in-flight request is discarded and a
+ * fresh fetch begins. Call `refetch()` to re-query after mutations.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**.
+ * For the managed "personal agent instance" convenience, see
+ * {@link usePersonalAgentInstance}.
+ *
+ * @example
+ * ```tsx
+ * const { agentInstances, isLoading } = useAgentInstanceList("acme", {
+ *   "stigmer.ai/personal": "true",
+ * });
+ * ```
+ */
+export function useAgentInstanceList(
+  org: string | null,
+  labels?: Record<string, string>,
+): UseAgentInstanceListReturn {
+  const stigmer = useStigmer();
+  const [agentInstances, setAgentInstances] = useState<AgentInstance[]>([]);
+  const [totalCount, setTotalCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const labelsRef = useRef(labels);
+  if (
+    labels !== labelsRef.current &&
+    JSON.stringify(labels) !== JSON.stringify(labelsRef.current)
+  ) {
+    labelsRef.current = labels;
+  }
+  const stableLabels = labelsRef.current;
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) {
+      setAgentInstances([]);
+      setTotalCount(0);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.agentInstance
+      .list(
+        create(ListAgentInstancesRequestSchema, {
+          org,
+          labels: stableLabels ?? {},
+        }),
+      )
+      .then(
+        (result) => {
+          if (cancelled.current) return;
+          setAgentInstances(result.items);
+          setTotalCount(result.totalCount);
+          setIsLoading(false);
+        },
+        (err) => {
+          if (cancelled.current) return;
+          setError(toError(err));
+          setIsLoading(false);
+        },
+      );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, stableLabels, stigmer, fetchKey]);
+
+  return { agentInstances, totalCount, isLoading, error, refetch };
+}

package/src/agent-instance/useCreateAgentInstance.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentInstanceInput } from "@stigmer/sdk";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseCreateAgentInstanceReturn {
+  readonly create: (input: AgentInstanceInput) => Promise<AgentInstance>;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `agentInstance.create()` with
+ * loading/error state.
+ *
+ * Creates an AgentInstance resource — a deployed configuration of an
+ * Agent blueprint bound to one or more Environments. The caller
+ * provides an {@link AgentInstanceInput} with `name`, `org`, and
+ * optionally `agentId`, `description`, and `environmentRefs`.
+ *
+ * Returns the full {@link AgentInstance} proto including
+ * server-generated metadata (id, version, timestamps) so callers
+ * can immediately reference the created resource.
+ *
+ * This is a Layer 1 building-block hook for the **Environment Flow**
+ * — agent instances bind Environment resources to Agent blueprints.
+ * For the managed "personal agent instance" convenience, see
+ * {@link usePersonalAgentInstance} which composes this hook with
+ * deterministic naming and label conventions.
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreateAgentInstance();
+ *
+ * const instance = await create({
+ *   name: "github-bot-prod",
+ *   org: "acme",
+ *   agentId: "agent-abc123",
+ *   description: "Production GitHub bot",
+ *   environmentRefs: [
+ *     { org: "acme", slug: "prod-credentials" },
+ *   ],
+ * });
+ * ```
+ */
+export function useCreateAgentInstance(): UseCreateAgentInstanceReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: AgentInstanceInput): Promise<AgentInstance> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentInstance.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/agent-instance/usePersonalAgentInstance.ts

@@ -0,0 +1,185 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { ResourceRef } from "@stigmer/sdk";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { useAgentInstanceList } from "./useAgentInstanceList";
+import { buildPersonalInstanceInput } from "./buildPersonalInstanceInput";
+
+const PERSONAL_LABELS: Record<string, string> = {
+  "stigmer.ai/personal": "true",
+};
+
+/**
+ * Input for creating a personal agent instance via
+ * {@link UsePersonalAgentInstanceReturn.getOrCreate}.
+ *
+ * The hook already knows `org` (from its first parameter) and
+ * `agentId` (from its second parameter). This input supplies the
+ * additional context needed only at creation time.
+ */
+export interface GetOrCreatePersonalInstanceInput {
+  /**
+   * The agent's slug, used to derive the instance display name and
+   * unique slug, and the `stigmer.ai/for-agent` label.
+   */
+  readonly agentSlug: string;
+  /**
+   * Reference to the caller's personal environment. The created
+   * instance will link to this environment via `environmentRefs`.
+   */
+  readonly personalEnvironmentRef: ResourceRef;
+}
+
+export interface UsePersonalAgentInstanceReturn {
+  /** The caller's personal agent instance, or `null` if not yet created or still loading. */
+  readonly agentInstance: AgentInstance | null;
+  /** `true` while the initial list query is in-flight. */
+  readonly isLoading: boolean;
+  /** Error from the most recent failed operation (fetch or mutation), or `null`. */
+  readonly error: Error | null;
+  /** Re-query personal agent instances from the server. */
+  readonly refetch: () => void;
+
+  /**
+   * Ensure a personal agent instance exists for this org and agent.
+   *
+   * If one already exists (matched by `agentId`), returns it immediately
+   * without a network call. Otherwise, creates a new instance with:
+   * - Name: `"{agentSlug} Personal"` (display-friendly, may be duplicate)
+   * - Slug: `"{agentSlug}-personal-{random}"` (unique per org)
+   * - Labels: `stigmer.ai/personal: "true"`, `stigmer.ai/for-agent: "{org}/{agentSlug}"`
+   * - Agent binding: the `agentId` passed to the hook
+   * - Environment linkage: `[personalEnvironmentRef]`
+   *
+   * Requires `agentId` to be set on the hook. Throws a descriptive
+   * error if called without it.
+   *
+   * @param input - Agent slug and personal environment reference.
+   * @returns The personal agent instance (existing or newly created).
+   */
+  readonly getOrCreate: (
+    input: GetOrCreatePersonalInstanceInput,
+  ) => Promise<AgentInstance>;
+
+  /** `true` while a `getOrCreate` mutation is in-flight. */
+  readonly isMutating: boolean;
+}
+
+/**
+ * Layer 2 orchestration hook that manages the caller's personal
+ * {@link AgentInstance} for a given organization, optionally scoped
+ * to a specific agent.
+ *
+ * Encapsulates the "personal agent instance" convention: unique slug
+ * per user, labels (`stigmer.ai/personal`, `stigmer.ai/for-agent`),
+ * and the get-or-create lifecycle. Composes {@link useAgentInstanceList}
+ * for declarative reading and the SDK client directly for mutations.
+ *
+ * Pass `null` as `org` to skip all operations (stable no-op).
+ * The `agentId` parameter is optional for read-only use (listing all
+ * personal instances) but required for {@link getOrCreate}.
+ *
+ * This is a Layer 2 **Environment Flow** hook. It provides the managed
+ * "personal agent instance" experience used by the Stigmer Console.
+ * Callers who pre-provision agent instances should use the Layer 1
+ * building-block hook {@link useCreateAgentInstance} directly.
+ *
+ * @example
+ * ```tsx
+ * // Read-only: check if a personal instance exists for an agent
+ * const { agentInstance, isLoading } = usePersonalAgentInstance(
+ *   "acme",
+ *   agent.metadata.id,
+ * );
+ *
+ * // Get-or-create: ensure a personal instance exists
+ * const { getOrCreate, isMutating } = usePersonalAgentInstance(
+ *   "acme",
+ *   agent.metadata.id,
+ * );
+ *
+ * const instance = await getOrCreate({
+ *   agentSlug: "my-github-bot",
+ *   personalEnvironmentRef: { org: "acme", slug: "env-personal-a1b2c3d4" },
+ * });
+ * ```
+ */
+export function usePersonalAgentInstance(
+  org: string | null,
+  agentId?: string,
+): UsePersonalAgentInstanceReturn {
+  const stigmer = useStigmer();
+  const { agentInstances, isLoading, error: listError, refetch } =
+    useAgentInstanceList(org, PERSONAL_LABELS);
+
+  const agentInstance = useMemo(() => {
+    if (agentInstances.length === 0) return null;
+    if (!agentId) return agentInstances[0] ?? null;
+    return (
+      agentInstances.find((ai) => ai.spec?.agentId === agentId) ?? null
+    );
+  }, [agentInstances, agentId]);
+
+  const [isMutating, setIsMutating] = useState(false);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+
+  const agentInstanceRef = useRef(agentInstance);
+  agentInstanceRef.current = agentInstance;
+
+  const error = mutationError ?? listError;
+
+  const getOrCreate = useCallback(
+    async (
+      input: GetOrCreatePersonalInstanceInput,
+    ): Promise<AgentInstance> => {
+      if (agentInstanceRef.current) return agentInstanceRef.current;
+
+      if (!org) {
+        throw new Error(
+          "usePersonalAgentInstance: cannot call getOrCreate when org is null.",
+        );
+      }
+      if (!agentId) {
+        throw new Error(
+          "usePersonalAgentInstance: agentId is required for getOrCreate. " +
+            "Pass the agent's ID as the second argument to the hook.",
+        );
+      }
+
+      setIsMutating(true);
+      setMutationError(null);
+
+      try {
+        const created = await stigmer.agentInstance.create(
+          buildPersonalInstanceInput({
+            org,
+            agentId,
+            agentSlug: input.agentSlug,
+            environmentRef: input.personalEnvironmentRef,
+          }),
+        );
+
+        refetch();
+        return created;
+      } catch (err) {
+        setMutationError(toError(err));
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [org, agentId, stigmer, refetch],
+  );
+
+  return {
+    agentInstance,
+    isLoading,
+    error,
+    refetch,
+    getOrCreate,
+    isMutating,
+  };
+}

package/src/api-key/ApiKeyCreatedAlert.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ApiKeyCreatedAlertProps {
+  /** The raw API key value to display. Shown exactly once. */
+  readonly rawKey: string;
+  /** Human-readable name of the key for context. */
+  readonly keyName: string;
+  /** Fired when the user dismisses the alert. */
+  readonly onDismiss: () => void;
+  readonly className?: string;
+}
+
+/**
+ * One-time reveal component displayed after a new API key is created.
+ *
+ * Shows the raw key value in a monospace read-only field with a
+ * **Copy** button. The key is only available at creation time — the
+ * server never returns it again — so this component prominently warns
+ * the user to copy it immediately.
+ *
+ * This is a standalone alert component, not a modal — the parent
+ * decides how to present and position it.
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ *
+ * @example
+ * ```tsx
+ * <ApiKeyCreatedAlert
+ *   rawKey="stgm_live_abc123..."
+ *   keyName="ci-deploy-key"
+ *   onDismiss={() => setRevealedKey(null)}
+ * />
+ * ```
+ */
+export function ApiKeyCreatedAlert({
+  rawKey,
+  keyName,
+  onDismiss,
+  className,
+}: ApiKeyCreatedAlertProps) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(rawKey);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Fallback: select the text so the user can manually copy
+      const el = document.getElementById("stgm-api-key-reveal");
+      if (el) {
+        const selection = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        selection?.removeAllRanges();
+        selection?.addRange(range);
+      }
+    }
+  }, [rawKey]);
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "rounded-lg border border-primary/30 bg-primary-subtle p-4",
+        className,
+      )}
+    >
+      <div className="mb-2 flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <p className="text-sm font-medium text-foreground">
+            API key created: {keyName}
+          </p>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            Copy this key now. It will not be shown again.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={onDismiss}
+          aria-label="Dismiss"
+          className={cn(
+            "shrink-0 rounded p-1",
+            "text-muted-foreground hover:text-foreground hover:bg-accent/50",
+            "transition-colors",
+          )}
+        >
+          <CloseIcon />
+        </button>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <code
+          id="stgm-api-key-reveal"
+          className={cn(
+            "min-w-0 flex-1 select-all truncate rounded-md",
+            "border border-input bg-background px-2.5 py-1.5",
+            "font-mono text-xs text-foreground",
+          )}
+        >
+          {rawKey}
+        </code>
+
+        <button
+          type="button"
+          onClick={handleCopy}
+          className={cn(
+            "inline-flex shrink-0 items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium",
+            "bg-primary text-primary-foreground hover:bg-primary/90",
+            "transition-colors",
+          )}
+        >
+          {copied ? <CheckIcon /> : <CopyIcon />}
+          {copied ? "Copied" : "Copy"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function CopyIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="5" y="5" width="9" height="9" rx="1.5" />
+      <path d="M5 11H3.5A1.5 1.5 0 0 1 2 9.5V3.5A1.5 1.5 0 0 1 3.5 2h6A1.5 1.5 0 0 1 11 3.5V5" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 8.5l3.5 3.5L13 5" />
+    </svg>
+  );
+}
+
+function CloseIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      aria-hidden="true"
+    >
+      <path d="M4 4l8 8M12 4l-8 8" />
+    </svg>
+  );
+}