@stigmer/react 0.0.36 → 0.0.40

package/src/agent/useAgentSetup.ts

@@ -0,0 +1,434 @@
+"use client";
+
+import { useCallback, useEffect, useReducer } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { EnvVarInput, ResourceRef, Stigmer } from "@stigmer/sdk";
+import { ListAgentInstancesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/io_pb";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
+import { buildPersonalInstanceInput } from "../agent-instance/buildPersonalInstanceInput";
+import { diffEnvSpec } from "../environment/diffEnvSpec";
+import {
+  agentSetupReducer,
+  INITIAL_STATE,
+  type AgentResolution,
+  type AgentSetupResult,
+  type AgentSetupReadyResult,
+  type AgentSetupState,
+} from "./agentSetupReducer";
+
+const PERSONAL_LABEL = "stigmer.ai/personal";
+const FOR_AGENT_LABEL = "stigmer.ai/for-agent";
+
+/**
+ * Re-checks for an existing personal instance immediately before
+ * creating one. Narrows the race window when multiple clients
+ * (tabs, double-clicks) attempt to create simultaneously.
+ */
+async function findOrCreatePersonalInstance(
+  stigmer: Stigmer,
+  params: {
+    org: string;
+    agentId: string;
+    agentSlug: string;
+    agentLabel: string;
+    environmentRef: ResourceRef;
+  },
+): Promise<AgentInstance> {
+  const { org, agentId, agentSlug, agentLabel, environmentRef } = params;
+
+  const recheck = await stigmer.agentInstance.list(
+    create(ListAgentInstancesRequestSchema, {
+      org,
+      labels: {
+        [PERSONAL_LABEL]: "true",
+        [FOR_AGENT_LABEL]: agentLabel,
+      },
+    }),
+  );
+
+  if (recheck.items.length > 0) {
+    return recheck.items[0];
+  }
+
+  return stigmer.agentInstance.create(
+    buildPersonalInstanceInput({ org, agentId, agentSlug, environmentRef }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public types (re-exported from agentSetupReducer for convenience)
+// ---------------------------------------------------------------------------
+
+export type {
+  AgentResolution,
+  AgentSetupResult,
+  AgentSetupReadyResult,
+  AgentSetupState,
+  AgentSetupPhase,
+} from "./agentSetupReducer";
+
+export interface SubmitEnvVarsOptions {
+  /**
+   * When `true` (default), the provided values are saved to the user's
+   * personal environment and a personal agent instance is created.
+   * Subsequent runs of the same agent will reuse these credentials.
+   *
+   * When `false`, the values are collected as `runtimeEnv` for this
+   * execution only — no data is persisted and no agent instance is
+   * created. This path is instant (no network calls).
+   *
+   * @default true
+   */
+  readonly saveForFuture?: boolean;
+}
+
+export interface UseAgentSetupReturn {
+  /**
+   * Current state of the agent setup flow.
+   *
+   * A discriminated union on `status`:
+   * - `"idle"` — no agent selected
+   * - `"resolving"` — evaluating an agent's requirements
+   * - `"needsEnvVars"` — waiting for user to provide missing variables
+   * - `"submitting"` — saving environment / creating instance
+   * - `"ready"` — agent resolved, `resolution` describes how to proceed
+   *
+   * `error` is available on all variants (orthogonal to phase).
+   */
+  readonly state: AgentSetupState;
+
+  /**
+   * Evaluate whether an agent is ready to use or needs env var collection.
+   *
+   * Fetches the full agent to read its `env_spec`, checks for an existing
+   * personal instance, and diffs env_spec keys against the personal
+   * environment. Returns `"ready"` when the agent can be used immediately,
+   * or `"needsEnvVars"` when the caller should present {@link AgentEnvForm}.
+   */
+  readonly resolveAgent: (ref: ResourceRef) => Promise<AgentSetupResult>;
+
+  /**
+   * Complete the env var collection flow for the pending agent.
+   *
+   * Behavior depends on `options.saveForFuture`:
+   * - `true` (default) — Creates or updates the personal environment
+   *   with the provided values, then creates a personal agent instance.
+   *   Returns `{ resolution: { mode: "saved", instanceId } }`.
+   * - `false` — Collects values as `runtimeEnv` without any API calls.
+   *   Returns `{ resolution: { mode: "oneTime", runtimeEnv } }`.
+   *
+   * Must only be called when `state.status === "needsEnvVars"`.
+   */
+  readonly submitEnvVars: (
+    values: Record<string, EnvVarInput>,
+    options?: SubmitEnvVarsOptions,
+  ) => Promise<AgentSetupReadyResult>;
+
+  /** Clear the error without changing the current phase. */
+  readonly clearError: () => void;
+
+  /** Reset to `idle` state, clearing all phase data and errors. */
+  readonly reset: () => void;
+}
+
+/**
+ * Layer 2 behavior hook that encapsulates the agent selection,
+ * personal environment resolution, and secret delivery routing flow.
+ *
+ * When a user picks an agent in the {@link AgentPicker}, this hook
+ * determines whether the agent requires credentials (via its
+ * `env_spec`), checks what the user has already provided in their
+ * personal environment, and either reports the agent as ready or
+ * identifies the missing variables so the caller can render
+ * {@link AgentEnvForm}.
+ *
+ * The hook supports two secret delivery paths via the `saveForFuture`
+ * option on {@link submitEnvVars}:
+ * - **Saved** — secrets are persisted to the personal environment and
+ *   a personal agent instance is created for reuse.
+ * - **One-time** — secrets are returned as `runtimeEnv` for a single
+ *   execution, with no data persisted.
+ *
+ * State is managed by a `useReducer` state machine with five phases:
+ * `idle → resolving → needsEnvVars → submitting → ready`.
+ *
+ * Composes {@link usePersonalEnvironment} for personal environment
+ * operations and calls the Stigmer client directly for agent and
+ * agent instance queries.
+ *
+ * > **Why not compose `usePersonalAgentInstance`?**
+ * > `resolveAgent` is an imperative async callback that needs
+ * > immediate results within a single invocation. Hook state
+ * > updates require a render cycle. Instance creation is delegated
+ * > through the shared `buildPersonalInstanceInput` helper instead.
+ *
+ * Pass `null` as `org` to disable all operations (stable no-op).
+ *
+ * @param org - Organization slug. Pass `null` to disable.
+ * @param poolKeys - Optional set of env-var keys already available
+ *   from the session env pool (manual secrets, one-time env vars from
+ *   other components). When provided, agents whose `env_spec` keys
+ *   are fully covered by `poolKeys` + personal env auto-resolve to
+ *   `ready` without prompting. Reactive — when `poolKeys` changes,
+ *   `needsEnvVars` is re-evaluated.
+ *
+ * @example
+ * ```tsx
+ * const { state, resolveAgent, submitEnvVars } = useAgentSetup("acme", pool.availableKeys);
+ *
+ * const result = await resolveAgent({ org: "acme", slug: "code-reviewer" });
+ *
+ * if (result.status === "needsEnvVars") {
+ *   // Render AgentEnvForm with result.missingVariables
+ *   // On form submit:
+ *   const ready = await submitEnvVars(formValues, { saveForFuture: true });
+ *   // ready.resolution.mode === "saved" | "oneTime"
+ * }
+ * ```
+ */
+export function useAgentSetup(
+  org: string | null,
+  poolKeys?: Set<string>,
+): UseAgentSetupReturn {
+  const stigmer = useStigmer();
+  const personalEnv = usePersonalEnvironment(org);
+
+  const [state, dispatch] = useReducer(agentSetupReducer, INITIAL_STATE);
+
+  const clearError = useCallback(() => dispatch({ type: "CLEAR_ERROR" }), []);
+  const reset = useCallback(() => dispatch({ type: "RESET" }), []);
+
+  // -------------------------------------------------------------------------
+  // resolveAgent
+  // -------------------------------------------------------------------------
+
+  const resolveAgent = useCallback(
+    async (ref: ResourceRef): Promise<AgentSetupResult> => {
+      if (!org) {
+        throw new Error(
+          "useAgentSetup: cannot resolve agent when org is null.",
+        );
+      }
+
+      dispatch({ type: "RESOLVE_START", agentRef: ref });
+
+      try {
+        const agent = await stigmer.agent.getByReference(ref);
+        const agentName = agent.metadata?.name ?? ref.slug;
+        const envSpecData = agent.spec?.envSpec?.data;
+
+        // No env_spec — agent is immediately ready (direct mode).
+        if (!envSpecData || Object.keys(envSpecData).length === 0) {
+          const resolution: AgentResolution = { mode: "direct" };
+          dispatch({
+            type: "RESOLVE_READY",
+            agentRef: ref,
+            agentName,
+            resolution,
+          });
+          return { status: "ready", agentRef: ref, agentName, resolution };
+        }
+
+        // Agent has env_spec — check for existing personal instance.
+        const agentLabel = `${ref.org}/${ref.slug}`;
+        const instanceList = await stigmer.agentInstance.list(
+          create(ListAgentInstancesRequestSchema, {
+            org,
+            labels: {
+              [PERSONAL_LABEL]: "true",
+              [FOR_AGENT_LABEL]: agentLabel,
+            },
+          }),
+        );
+
+        if (instanceList.items.length > 0) {
+          const resolution: AgentResolution = {
+            mode: "saved",
+            instanceId: instanceList.items[0].metadata!.id,
+          };
+          dispatch({
+            type: "RESOLVE_READY",
+            agentRef: ref,
+            agentName,
+            resolution,
+          });
+          return { status: "ready", agentRef: ref, agentName, resolution };
+        }
+
+        // No personal instance — diff against existing env keys + pool.
+        const existingKeys = new Set(
+          Object.keys(personalEnv.environment?.spec?.data ?? {}),
+        );
+        const personalOnlyMissing = diffEnvSpec(envSpecData, existingKeys);
+        const missingVariables = diffEnvSpec(envSpecData, existingKeys, poolKeys);
+
+        if (personalOnlyMissing.length === 0) {
+          // Personal env covers all keys — create personal instance.
+          const env = await personalEnv.getOrCreate();
+          const envRef: ResourceRef = {
+            org,
+            slug: env.metadata!.slug,
+            kind: ApiResourceKind.environment,
+          };
+
+          const instance = await findOrCreatePersonalInstance(stigmer, {
+            org,
+            agentId: agent.metadata!.id,
+            agentSlug: ref.slug,
+            agentLabel,
+            environmentRef: envRef,
+          });
+
+          const resolution: AgentResolution = {
+            mode: "saved",
+            instanceId: instance.metadata!.id,
+          };
+          dispatch({
+            type: "RESOLVE_READY",
+            agentRef: ref,
+            agentName,
+            resolution,
+          });
+          return { status: "ready", agentRef: ref, agentName, resolution };
+        }
+
+        if (missingVariables.length === 0) {
+          // Pool covers remaining keys — use default instance, pool
+          // values flow via sessionVariables.toRuntimeEnv() at submit.
+          const resolution: AgentResolution = { mode: "direct" };
+          dispatch({
+            type: "RESOLVE_READY",
+            agentRef: ref,
+            agentName,
+            resolution,
+          });
+          return { status: "ready", agentRef: ref, agentName, resolution };
+        }
+
+        // Missing variables — transition to needsEnvVars.
+        dispatch({
+          type: "RESOLVE_NEEDS_ENV",
+          agentRef: ref,
+          agentId: agent.metadata!.id,
+          agentName,
+          missingVariables,
+        });
+        return {
+          status: "needsEnvVars",
+          agentRef: ref,
+          agentName,
+          missingVariables,
+        };
+      } catch (err) {
+        dispatch({ type: "ERROR", error: toError(err) });
+        throw err;
+      }
+    },
+    [org, stigmer, personalEnv, poolKeys],
+  );
+
+  // -------------------------------------------------------------------------
+  // Pool re-evaluation — auto-resolve needsEnvVars when pool changes
+  // -------------------------------------------------------------------------
+
+  const agentMissingVars =
+    state.status === "needsEnvVars" ? state.missingVariables : null;
+
+  useEffect(() => {
+    if (!poolKeys || poolKeys.size === 0) return;
+    if (!agentMissingVars) return;
+
+    const stillMissing = agentMissingVars.filter(
+      (v) => !poolKeys.has(v.key),
+    );
+
+    dispatch({ type: "POOL_RESOLVE", missingVariables: stillMissing });
+  }, [poolKeys, agentMissingVars]);
+
+  // -------------------------------------------------------------------------
+  // submitEnvVars
+  // -------------------------------------------------------------------------
+
+  const submitEnvVars = useCallback(
+    async (
+      values: Record<string, EnvVarInput>,
+      options?: SubmitEnvVarsOptions,
+    ): Promise<AgentSetupReadyResult> => {
+      if (state.status !== "needsEnvVars") {
+        throw new Error(
+          "useAgentSetup: submitEnvVars requires state.status === 'needsEnvVars'. " +
+            `Current status is '${state.status}'. Call resolveAgent() first ` +
+            "and ensure it returned status 'needsEnvVars'.",
+        );
+      }
+      if (!org) {
+        throw new Error(
+          "useAgentSetup: cannot submit env vars when org is null.",
+        );
+      }
+
+      const { agentRef, agentId, agentName } = state;
+      const saveForFuture = options?.saveForFuture ?? true;
+
+      // ----- One-time path: no API calls, instant result -----
+      if (!saveForFuture) {
+        const resolution: AgentResolution = {
+          mode: "oneTime",
+          runtimeEnv: values,
+        };
+        dispatch({
+          type: "SUBMIT_READY",
+          agentRef,
+          agentName,
+          resolution,
+        });
+        return { status: "ready", agentRef, agentName, resolution };
+      }
+
+      // ----- Save path: persist to environment + create instance -----
+      dispatch({ type: "SUBMIT_START" });
+
+      try {
+        const env = await personalEnv.getOrCreate();
+        await personalEnv.addVariables(values);
+
+        const envRef: ResourceRef = {
+          org,
+          slug: env.metadata!.slug,
+          kind: ApiResourceKind.environment,
+        };
+
+        const agentLabel = `${agentRef.org}/${agentRef.slug}`;
+        const instance = await findOrCreatePersonalInstance(stigmer, {
+          org,
+          agentId,
+          agentSlug: agentRef.slug,
+          agentLabel,
+          environmentRef: envRef,
+        });
+
+        const resolution: AgentResolution = {
+          mode: "saved",
+          instanceId: instance.metadata!.id,
+        };
+        dispatch({
+          type: "SUBMIT_READY",
+          agentRef,
+          agentName,
+          resolution,
+        });
+        return { status: "ready", agentRef, agentName, resolution };
+      } catch (err) {
+        dispatch({ type: "ERROR", error: toError(err) });
+        throw err;
+      }
+    },
+    [org, stigmer, personalEnv, state],
+  );
+
+  return { state, resolveAgent, submitEnvVars, clearError, reset };
+}

package/src/agent/useDefaultAgent.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { GetDefaultAgentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseDefaultAgentReturn {
+  /** The platform default agent, or null while loading / on error. */
+  readonly agent: Agent | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the platform's default agent.
+ *
+ * The default agent is the one labeled `stigmer.ai/default-agent: "true"`
+ * with `visibility_public`. It enables session-first UX where users
+ * start a conversation without choosing an agent.
+ *
+ * Pass `null` for `org` to skip fetching (stable no-op). The hook
+ * fetches once on mount and caches the result — the default agent
+ * rarely changes within a session.
+ *
+ * @example
+ * ```tsx
+ * const { agent: defaultAgent, isLoading } = useDefaultAgent("acme");
+ *
+ * // Use defaultAgent.status.defaultInstanceId for session creation
+ * // when the user hasn't explicitly selected an agent.
+ * ```
+ */
+export function useDefaultAgent(org: string | null): UseDefaultAgentReturn {
+  const stigmer = useStigmer();
+  const [agent, setAgent] = useState<Agent | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) {
+      setAgent(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.agent.getDefault(create(GetDefaultAgentRequestSchema, { org })).then(
+      (result) => {
+        if (cancelled.current) return;
+        setAgent(result);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(toError(err));
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, stigmer, fetchKey]);
+
+  return { agent, isLoading, error, refetch };
+}

package/src/agent-instance/buildPersonalInstanceInput.ts

@@ -0,0 +1,40 @@
+import type { AgentInstanceInput, ResourceRef } from "@stigmer/sdk";
+import { generateSlugSuffix } from "../internal/slug";
+
+const PERSONAL_LABEL = "stigmer.ai/personal";
+const FOR_AGENT_LABEL = "stigmer.ai/for-agent";
+
+export interface PersonalInstanceParams {
+  readonly org: string;
+  readonly agentId: string;
+  readonly agentSlug: string;
+  readonly environmentRef: ResourceRef;
+}
+
+/**
+ * Builds the {@link AgentInstanceInput} for creating a personal agent
+ * instance. Centralizes the naming convention, unique slug generation,
+ * and label assignment so that every call site produces consistent
+ * personal instances.
+ *
+ * The slug includes a random suffix to guarantee uniqueness within
+ * the org (multiple users can each have their own personal instance
+ * for the same agent). Lookup is always label-based via FGA-scoped
+ * list queries, so the slug is never used for retrieval.
+ */
+export function buildPersonalInstanceInput(
+  params: PersonalInstanceParams,
+): AgentInstanceInput {
+  const { org, agentId, agentSlug, environmentRef } = params;
+  return {
+    name: `${agentSlug} Personal`,
+    slug: `${agentSlug}-personal-${generateSlugSuffix()}`,
+    org,
+    agentId,
+    labels: {
+      [PERSONAL_LABEL]: "true",
+      [FOR_AGENT_LABEL]: `${org}/${agentSlug}`,
+    },
+    environmentRefs: [environmentRef],
+  };
+}

package/src/agent-instance/index.ts

@@ -0,0 +1,11 @@
+export { useAgentInstance } from "./useAgentInstance";
+export type { UseAgentInstanceReturn } from "./useAgentInstance";
+export { useAgentInstanceList } from "./useAgentInstanceList";
+export type { UseAgentInstanceListReturn } from "./useAgentInstanceList";
+export { useCreateAgentInstance } from "./useCreateAgentInstance";
+export type { UseCreateAgentInstanceReturn } from "./useCreateAgentInstance";
+export { usePersonalAgentInstance } from "./usePersonalAgentInstance";
+export type {
+  GetOrCreatePersonalInstanceInput,
+  UsePersonalAgentInstanceReturn,
+} from "./usePersonalAgentInstance";

package/src/agent-instance/useAgentInstance.ts

@@ -0,0 +1,87 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import type { ResourceRef } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface UseAgentInstanceReturn {
+  readonly agentInstance: AgentInstance | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single AgentInstance by resource reference.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the reference
+ * fields change, the previous in-flight request is discarded and a
+ * fresh fetch begins. Call `refetch()` to re-query after mutating the
+ * agent instance through a separate hook or API call.
+ *
+ * Returns the full proto {@link AgentInstance} resource so consumers
+ * have access to metadata, spec (including `environment_refs` and
+ * agent reference), and status without additional calls.
+ *
+ * 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}.
+ *
+ * @example
+ * ```tsx
+ * const { agentInstance, isLoading, error } = useAgentInstance({
+ *   org: "acme",
+ *   slug: "my-agent-personal",
+ * });
+ * ```
+ */
+export function useAgentInstance(
+  ref: ResourceRef | null,
+): UseAgentInstanceReturn {
+  const stigmer = useStigmer();
+  const [agentInstance, setAgentInstance] = useState<AgentInstance | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  const org = ref?.org;
+  const slug = ref?.slug;
+  const version = ref?.version;
+
+  useEffect(() => {
+    if (!org || !slug) {
+      setAgentInstance(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.agentInstance.getByReference({ org, slug, version }).then(
+      (result) => {
+        if (cancelled.current) return;
+        setAgentInstance(result);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(toError(err));
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [org, slug, version, stigmer, fetchKey]);
+
+  return { agentInstance, isLoading, error, refetch };
+}