@stigmer/react 0.4.7 → 0.5.0

package/src/agent/steps/IdentityStep.tsx

@@ -0,0 +1,259 @@
+"use client";
+
+import { useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import { generateSlug } from "../../internal/slug";
+import type { AgentWizardData } from "./types";
+
+/** Props for {@link IdentityStep}. */
+export interface IdentityStepProps {
+  readonly data: AgentWizardData;
+  readonly updateData: (partial: Partial<AgentWizardData>) => void;
+  readonly validationError: string | null;
+}
+
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * Wizard step 1: Agent identity and instructions.
+ *
+ * Collects: name (required), slug (auto-derived), description,
+ * icon URL, visibility, and the instructions textarea.
+ *
+ * The slug auto-derives from the name until the user manually edits it.
+ * Follows the same pattern as `CreateOrganizationForm`.
+ */
+export function IdentityStep({
+  data,
+  updateData,
+  validationError,
+}: IdentityStepProps) {
+  const handleNameChange = useCallback(
+    (value: string) => {
+      if (!data.slugTouched) {
+        updateData({ name: value, slug: generateSlug(value) });
+      } else {
+        updateData({ name: value });
+      }
+    },
+    [data.slugTouched, updateData],
+  );
+
+  const handleSlugChange = useCallback(
+    (value: string) => {
+      updateData({ slug: value, slugTouched: true });
+    },
+    [updateData],
+  );
+
+  const slugError =
+    data.slug.length > 0 && !SLUG_PATTERN.test(data.slug)
+      ? "Slug must be lowercase letters, numbers, and hyphens only"
+      : null;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h2 className="text-lg font-semibold text-foreground">
+          Identity & Instructions
+        </h2>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Define what this agent is and what it does.
+        </p>
+      </div>
+
+      {validationError && (
+        <p className="text-sm text-destructive" role="alert">
+          {validationError}
+        </p>
+      )}
+
+      <div className="grid gap-4 sm:grid-cols-2">
+        {/* Name */}
+        <div className="space-y-1.5">
+          <label
+            htmlFor="stgm-wizard-agent-name"
+            className="text-sm font-medium text-foreground"
+          >
+            Name <span className="text-destructive">*</span>
+          </label>
+          <input
+            id="stgm-wizard-agent-name"
+            type="text"
+            value={data.name}
+            onChange={(e) => handleNameChange(e.target.value)}
+            placeholder="e.g. PR Review Bot"
+            autoFocus
+            className={cn(
+              "w-full rounded-md border border-input bg-input-bg px-3 py-2 text-sm text-foreground",
+              "placeholder:text-muted-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          />
+        </div>
+
+        {/* Slug */}
+        <div className="space-y-1.5">
+          <label
+            htmlFor="stgm-wizard-agent-slug"
+            className="text-sm font-medium text-foreground"
+          >
+            Slug
+          </label>
+          <input
+            id="stgm-wizard-agent-slug"
+            type="text"
+            value={data.slug}
+            onChange={(e) => handleSlugChange(e.target.value)}
+            placeholder="auto-generated"
+            className={cn(
+              "w-full rounded-md border px-3 py-2 font-mono text-sm text-foreground",
+              slugError
+                ? "border-destructive bg-input-bg"
+                : "border-input bg-input-bg",
+              "placeholder:text-muted-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          />
+          {slugError && (
+            <p className="text-xs text-destructive">{slugError}</p>
+          )}
+          {!slugError && data.slug && (
+            <p className="text-xs text-muted-foreground">
+              Referenced as <code className="font-mono">{data.slug}</code>
+            </p>
+          )}
+        </div>
+      </div>
+
+      {/* Description */}
+      <div className="space-y-1.5">
+        <label
+          htmlFor="stgm-wizard-agent-description"
+          className="text-sm font-medium text-foreground"
+        >
+          Description
+        </label>
+        <input
+          id="stgm-wizard-agent-description"
+          type="text"
+          value={data.description}
+          onChange={(e) => updateData({ description: e.target.value })}
+          placeholder="A brief description of what this agent does"
+          maxLength={200}
+          className={cn(
+            "w-full rounded-md border border-input bg-input-bg px-3 py-2 text-sm text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        />
+      </div>
+
+      {/* Icon URL + Visibility (same row) */}
+      <div className="grid gap-4 sm:grid-cols-2">
+        <div className="space-y-1.5">
+          <label
+            htmlFor="stgm-wizard-agent-icon"
+            className="text-sm font-medium text-foreground"
+          >
+            Icon URL
+          </label>
+          <input
+            id="stgm-wizard-agent-icon"
+            type="url"
+            value={data.iconUrl}
+            onChange={(e) => updateData({ iconUrl: e.target.value })}
+            placeholder="https://example.com/icon.png"
+            className={cn(
+              "w-full rounded-md border border-input bg-input-bg px-3 py-2 text-sm text-foreground",
+              "placeholder:text-muted-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          />
+        </div>
+
+        <fieldset className="space-y-1.5">
+          <legend className="text-sm font-medium text-foreground">
+            Visibility
+          </legend>
+          <div className="flex gap-2">
+            <VisibilityOption
+              value="private"
+              label="Private"
+              checked={data.visibility === "private"}
+              onChange={() => updateData({ visibility: "private" })}
+            />
+            <VisibilityOption
+              value="public"
+              label="Public"
+              checked={data.visibility === "public"}
+              onChange={() => updateData({ visibility: "public" })}
+            />
+          </div>
+        </fieldset>
+      </div>
+
+      {/* Instructions */}
+      <div className="space-y-1.5">
+        <label
+          htmlFor="stgm-wizard-agent-instructions"
+          className="text-sm font-medium text-foreground"
+        >
+          Instructions
+        </label>
+        <p className="text-xs text-muted-foreground">
+          The system prompt that defines this agent&apos;s behavior.
+        </p>
+        <textarea
+          id="stgm-wizard-agent-instructions"
+          value={data.instructions}
+          onChange={(e) => updateData({ instructions: e.target.value })}
+          placeholder="You are a helpful assistant that..."
+          rows={12}
+          className={cn(
+            "w-full resize-y rounded-md border border-input bg-input-bg px-3 py-2 font-mono text-sm text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        />
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Visibility radio option
+// ---------------------------------------------------------------------------
+
+function VisibilityOption({
+  value,
+  label,
+  checked,
+  onChange,
+}: {
+  readonly value: string;
+  readonly label: string;
+  readonly checked: boolean;
+  readonly onChange: () => void;
+}) {
+  return (
+    <label
+      className={cn(
+        "inline-flex cursor-pointer items-center rounded-md border px-3 py-1.5 text-sm transition-colors",
+        checked
+          ? "border-primary bg-primary-subtle text-primary font-medium"
+          : "border-input bg-input-bg text-muted-foreground hover:border-border hover:text-foreground",
+      )}
+    >
+      <input
+        type="radio"
+        name="stgm-wizard-agent-visibility"
+        value={value}
+        checked={checked}
+        onChange={onChange}
+        className="sr-only"
+      />
+      {label}
+    </label>
+  );
+}

package/src/agent/steps/ReviewStep.tsx

@@ -0,0 +1,211 @@
+"use client";
+
+import { useMemo } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import type { AgentInput } from "@stigmer/sdk";
+import { serializeAgentInputYaml } from "../../library/serialize-resource-yaml";
+import type { AgentWizardData } from "./types";
+
+/** Props for {@link ReviewStep}. */
+export interface ReviewStepProps {
+  readonly org: string;
+  readonly data: AgentWizardData;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+}
+
+/**
+ * Wizard step 3: Review and create.
+ *
+ * Shows a summary card with key configuration details and a full
+ * YAML preview of the agent that will be created. The "Create" action
+ * is in the WizardNav footer, not in this component.
+ */
+export function ReviewStep({
+  org,
+  data,
+  isCreating,
+  error,
+}: ReviewStepProps) {
+  const agentInput = useMemo(() => buildAgentInput(org, data), [org, data]);
+  const yamlPreview = useMemo(
+    () => serializeAgentInputYaml(agentInput),
+    [agentInput],
+  );
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h2 className="text-lg font-semibold text-foreground">
+          Review & Create
+        </h2>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Review the agent configuration below, then create it.
+        </p>
+      </div>
+
+      {/* Summary card */}
+      <div className="rounded-lg border border-border p-4">
+        <dl className="grid gap-x-6 gap-y-3 text-sm sm:grid-cols-2">
+          <SummaryItem label="Name" value={data.name} />
+          <SummaryItem label="Slug" value={data.slug} mono />
+          <SummaryItem label="Organization" value={org} mono />
+          <SummaryItem
+            label="Visibility"
+            value={data.visibility === "public" ? "Public" : "Private"}
+          />
+          {data.description && (
+            <SummaryItem
+              label="Description"
+              value={data.description}
+              className="sm:col-span-2"
+            />
+          )}
+          {data.instructions && (
+            <SummaryItem
+              label="Instructions"
+              value={truncate(data.instructions, 120)}
+              className="sm:col-span-2"
+            />
+          )}
+          <SummaryItem
+            label="MCP Servers"
+            value={
+              data.mcpServerUsages.length > 0
+                ? `${data.mcpServerUsages.length} configured`
+                : "None"
+            }
+          />
+          <SummaryItem
+            label="Skills"
+            value={
+              data.skillRefs.length > 0
+                ? `${data.skillRefs.length} attached`
+                : "None"
+            }
+          />
+          {data.env.length > 0 && (
+            <SummaryItem
+              label="Env Variables"
+              value={`${data.env.length} declared`}
+            />
+          )}
+        </dl>
+      </div>
+
+      {/* YAML preview */}
+      <div className="space-y-2">
+        <h3 className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+          YAML Preview
+        </h3>
+        <div className="max-h-80 overflow-auto rounded-lg border border-border bg-muted-faint">
+          <pre className="p-4 font-mono text-xs leading-relaxed text-foreground">
+            {yamlPreview}
+          </pre>
+        </div>
+      </div>
+
+      {/* Error display */}
+      {error && (
+        <div className="rounded-md border border-destructive bg-muted-faint px-4 py-3" role="alert">
+          <p className="text-sm font-medium text-destructive">
+            Failed to create agent
+          </p>
+          <p className="mt-1 text-xs text-muted-foreground">
+            {getUserMessage(error)}
+          </p>
+        </div>
+      )}
+
+      {/* Creating state */}
+      {isCreating && (
+        <p className="text-sm text-muted-foreground" aria-live="polite">
+          Creating agent…
+        </p>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Summary item
+// ---------------------------------------------------------------------------
+
+function SummaryItem({
+  label,
+  value,
+  mono,
+  className,
+}: {
+  readonly label: string;
+  readonly value: string;
+  readonly mono?: boolean;
+  readonly className?: string;
+}) {
+  return (
+    <div className={className}>
+      <dt className="text-xs text-muted-foreground">{label}</dt>
+      <dd
+        className={cn(
+          "mt-0.5 text-sm text-foreground",
+          mono && "font-mono",
+        )}
+      >
+        {value}
+      </dd>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength) + "…";
+}
+
+/**
+ * Transforms wizard data into the SDK `AgentInput` shape for submission.
+ * Exported for reuse by `AgentCreationWizard`.
+ */
+export function buildAgentInput(
+  org: string,
+  data: AgentWizardData,
+): AgentInput {
+  const input: AgentInput = {
+    name: data.name.trim(),
+    org,
+    ...(data.slug && { slug: data.slug }),
+    ...(data.description && { description: data.description.trim() }),
+    ...(data.iconUrl && { iconUrl: data.iconUrl.trim() }),
+    ...(data.instructions && { instructions: data.instructions }),
+  };
+
+  if (data.mcpServerUsages.length > 0) {
+    input.mcpServerUsages = data.mcpServerUsages;
+  }
+
+  if (data.skillRefs.length > 0) {
+    input.skillRefs = data.skillRefs;
+  }
+
+  if (data.env.length > 0) {
+    const env: Record<string, { isSecret?: boolean; description?: string; optional?: boolean }> = {};
+    for (const entry of data.env) {
+      if (!entry.key) continue;
+      env[entry.key] = {
+        ...(entry.isSecret && { isSecret: true }),
+        ...(entry.description && { description: entry.description }),
+        ...(entry.optional && { optional: true }),
+      };
+    }
+    if (Object.keys(env).length > 0) {
+      input.env = env;
+    }
+  }
+
+  return input;
+}

package/src/agent/steps/types.ts

@@ -0,0 +1,53 @@
+import type { McpServerUsageInput, ResourceRef } from "@stigmer/sdk";
+import type { EnvVarEntry } from "../../resource-creation/types";
+
+export type { EnvVarEntry } from "../../resource-creation/types";
+
+/**
+ * Accumulated form state for the agent creation wizard.
+ *
+ * Each field corresponds to a property on `AgentInput`. The wizard
+ * builds this incrementally across steps, then transforms it into
+ * an `AgentInput` for submission on the final step.
+ */
+export interface AgentWizardData {
+  // --- Step 1: Identity & Instructions ---
+  /** Agent display name (required). */
+  readonly name: string;
+  /** URL-friendly slug (auto-derived from name, editable). */
+  readonly slug: string;
+  /** Whether the slug has been manually edited by the user. */
+  readonly slugTouched: boolean;
+  /** Short description (optional). */
+  readonly description: string;
+  /** Icon URL (optional). */
+  readonly iconUrl: string;
+  /** Resource visibility. */
+  readonly visibility: "private" | "public";
+  /** System prompt / instructions (the agent's core content). */
+  readonly instructions: string;
+
+  // --- Step 2: Capabilities ---
+  /** MCP server usages with tool configuration. */
+  readonly mcpServerUsages: McpServerUsageInput[];
+  /** Skill references. */
+  readonly skillRefs: ResourceRef[];
+  /** Environment variable declarations. */
+  readonly env: EnvVarEntry[];
+}
+
+/** Creates the initial empty wizard data. */
+export function createInitialWizardData(): AgentWizardData {
+  return {
+    name: "",
+    slug: "",
+    slugTouched: false,
+    description: "",
+    iconUrl: "",
+    visibility: "private",
+    instructions: "",
+    mcpServerUsages: [],
+    skillRefs: [],
+    env: [],
+  };
+}

package/src/agent/useCreateAgent.ts

@@ -0,0 +1,76 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentInput } from "@stigmer/sdk";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreateAgent}. */
+export interface UseCreateAgentReturn {
+  /**
+   * Submit an {@link AgentInput} to create (or upsert) an agent blueprint.
+   *
+   * Uses `stigmer.agent.apply()` — the idempotent upsert operation.
+   * Resolves with the server-created/updated `Agent` proto including
+   * populated metadata (id, slug, audit timestamps).
+   */
+  readonly create: (input: AgentInput) => Promise<Agent>;
+  /** `true` while the apply request is in flight. */
+  readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `agent.apply()` with loading and error state.
+ *
+ * Creates an agent blueprint from an {@link AgentInput}. Uses `apply()`
+ * (upsert) rather than `create()` so re-submissions are idempotent —
+ * matching the CLI's `stigmer apply` semantics.
+ *
+ * Follows the established SDK mutation hook pattern: `isCreating` flag,
+ * `error` state, `clearError` reset, result returned from the promise
+ * (not stored in hook state).
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error, clearError } = useCreateAgent();
+ *
+ * const agent = await create({
+ *   name: "pr-review-bot",
+ *   org: "acme",
+ *   instructions: "Review pull requests for code quality...",
+ *   mcpServerUsages: [{ mcpServerRef: { org: "acme", slug: "github" } }],
+ * });
+ * // agent.metadata?.slug → "pr-review-bot"
+ * ```
+ */
+export function useCreateAgent(): UseCreateAgentReturn {
+  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: AgentInput): Promise<Agent> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.agent.apply(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/agent/useUpdateAgent.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useUpdateAgent}. */
+export interface UseUpdateAgentReturn {
+  /** Update an existing agent with a full input. Returns the updated resource. */
+  readonly update: (input: AgentInput) => Promise<Agent>;
+  /** `true` while the update RPC is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Clear the error state. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that updates an existing Agent resource.
+ *
+ * Wraps `stigmer.agent.update(input)` with loading and error state.
+ * The caller must provide a **complete** `AgentInput` — the backend
+ * performs full spec replacement. Use `agentToInput()` to reconstruct
+ * the input from a fetched agent, modify the desired field, and pass
+ * the result here.
+ */
+export function useUpdateAgent(): UseUpdateAgentReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const update = useCallback(
+    async (input: AgentInput): Promise<Agent> => {
+      setIsUpdating(true);
+      setError(null);
+
+      try {
+        return await stigmer.agent.update(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { update, isUpdating, error, clearError };
+}