@data-club/ai-hub 0.0.1

package/src/components/DataClubAIHubAdmin/AgentEditorModal.tsx

@@ -0,0 +1,505 @@
+/**
+ * `<AgentEditorModal />` — shared create + edit modal for the Agents sub-page
+ * ([06-admin-agents.md]).
+ *
+ * Required fields: `display_name` and `letta_agent_id`. **Model / provider /
+ * system prompt / tools / memory blocks are intentionally absent** — they
+ * live in Letta's ADE per §1, §6.4.1.
+ *
+ * Step-12.5 — adds an optional "Specialized agent" sub-section below the
+ * required fields:
+ *
+ *   - `sandbox_seed_name` — name of a folder under `AI_HUB_FILES_DIR/seeds/`
+ *     to copy into each new session's working directory.
+ *   - `fork_source_conversation_id` — Letta conversation id to fork from
+ *     at session create.
+ *
+ * Both new fields are optional and independent — see
+ * [docs/server/session-sandboxes.md](../../../../../docs/server/session-sandboxes.md).
+ *
+ * The modal owns local validation (required fields) + the in-flight submit
+ * button label; the parent page owns the network call so it can swap the
+ * row in / out of its table state on success.
+ *
+ * Errors are surfaced two ways: inline on the relevant field when the server
+ * returns a field-targeted error code (`letta_agent_not_found`,
+ * `seed_name_invalid`, `seed_dir_not_found`, `fork_source_not_found`,
+ * `fork_source_agent_mismatch`), and as a generic banner above the buttons
+ * for anything else.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 — admin agents endpoints
+ * @see ui-sketches/06-admin-agents.md — modal layout
+ * @see docs/server/session-sandboxes.md — Step-12.5 specialized-agent levers
+ */
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+
+import type { AIHubAdminTexts } from "../../auth/texts.js";
+import { AIHubRequestError, type AdminRotatingMessageView } from "../../client/AIHubClient.js";
+import { useAIHub } from "../../context/useAIHub.js";
+
+/** Modal mode — create-new vs. edit-existing. */
+export type AgentEditorMode = "create" | "edit";
+
+/**
+ * How the operator is specifying the base conversation:
+ * - `none`     — no base; every session starts fresh.
+ * - `rotating` — pick a rotating starting message (stored as its `rmsg-…` id).
+ * - `manual`   — paste a raw Letta `conv-…` id.
+ */
+type ForkMode = "none" | "rotating" | "manual";
+
+/** Derives the initial fork mode from a stored fork-source value. */
+function initialForkMode(value: string | null | undefined): ForkMode {
+  if (!value) return "none";
+  return value.startsWith("rmsg-") ? "rotating" : "manual";
+}
+
+/** Initial values for the edit variant. */
+interface EditorInitial {
+  displayName: string;
+  lettaAgentId: string;
+  /** Step-12.5 — null when no sandbox configured for this agent. */
+  sandboxSeedName: string | null;
+  /** Step-12.5 — null when no fork source configured for this agent. */
+  forkSourceConversationId: string | null;
+}
+
+/** Submit-body shape passed up to the parent page. */
+export interface AgentEditorSubmitBody {
+  displayName: string;
+  lettaAgentId: string;
+  /**
+   * Step-12.5 — `null` when the admin cleared the field (or left it blank);
+   * `string` when present. The parent's `createAdminAgent` / `patchAdminAgent`
+   * call forwards this verbatim — null becomes a `sandbox_seed_name: null`
+   * over the wire, which the server treats as "clear the column".
+   */
+  sandboxSeedName: string | null;
+  /** Step-12.5 — same shape semantics as `sandboxSeedName`. */
+  forkSourceConversationId: string | null;
+}
+
+/** Props for `<AgentEditorModal />`. */
+export interface AgentEditorModalProps {
+  /** Which variant to render. */
+  mode: AgentEditorMode;
+  /**
+   * Initial form values. Required on `mode === "edit"`; ignored on
+   * `mode === "create"`.
+   */
+  initial?: EditorInitial;
+  /** Resolved admin texts. */
+  texts: AIHubAdminTexts;
+  /**
+   * Submits the form. Throws the SDK's `AIHubRequestError` on failure
+   * (the modal surfaces it inline / as a banner depending on the error
+   * code).
+   */
+  onSubmit: (body: AgentEditorSubmitBody) => Promise<void>;
+  /** Dismisses the modal without submitting. */
+  onCancel: () => void;
+}
+
+/**
+ * Renders the shared create / edit form.
+ *
+ * @param props - see {@link AgentEditorModalProps}.
+ * @returns the modal markup.
+ */
+export function AgentEditorModal(props: AgentEditorModalProps): ReactNode {
+  const isEdit = props.mode === "edit";
+  const [displayName, setDisplayName] = useState(props.initial?.displayName ?? "");
+  const [lettaAgentId, setLettaAgentId] = useState(
+    props.initial?.lettaAgentId ?? "",
+  );
+  // Step-12.5 — controlled inputs, empty string = "field cleared".
+  const [sandboxSeedName, setSandboxSeedName] = useState(
+    props.initial?.sandboxSeedName ?? "",
+  );
+  // Base-conversation control: a mode + the value for the active mode. The
+  // stored `fork_source_conversation_id` is either an `rmsg-…` reference or a
+  // raw `conv-…` id; we split it back into mode + value for editing.
+  const initialFork = props.initial?.forkSourceConversationId ?? null;
+  const [forkMode, setForkMode] = useState<ForkMode>(initialForkMode(initialFork));
+  const [selectedRmsgId, setSelectedRmsgId] = useState<string | null>(
+    initialFork && initialFork.startsWith("rmsg-") ? initialFork : null,
+  );
+  const [manualConvId, setManualConvId] = useState(
+    initialFork && !initialFork.startsWith("rmsg-") ? initialFork : "",
+  );
+  const [rmsgList, setRmsgList] = useState<AdminRotatingMessageView[] | null>(null);
+  const [rmsgSearch, setRmsgSearch] = useState("");
+  const { client } = useAIHub();
+  const [nameError, setNameError] = useState<string | null>(null);
+  const [idError, setIdError] = useState<string | null>(null);
+  const [seedError, setSeedError] = useState<string | null>(null);
+  const [forkError, setForkError] = useState<string | null>(null);
+  const [banner, setBanner] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const firstFieldRef = useRef<HTMLInputElement | null>(null);
+
+  useEffect(() => {
+    firstFieldRef.current?.focus();
+  }, []);
+
+  // Prefetch the rotating-message catalog so the "Rotating message" picker is
+  // ready. Best-effort: an empty list just shows the empty-state copy.
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = await client.listAdminRotatingMessages();
+        if (!cancelled) setRmsgList(rows.filter((r) => !r.is_archived));
+      } catch {
+        if (!cancelled) setRmsgList([]);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client]);
+
+  /** Rotating messages matching the search box (by name or id). */
+  const filteredRmsgs = useMemo(() => {
+    const list = rmsgList ?? [];
+    const q = rmsgSearch.trim().toLowerCase();
+    if (q.length === 0) return list;
+    return list.filter(
+      (r) => r.display_name.toLowerCase().includes(q) || r.id.toLowerCase().includes(q),
+    );
+  }, [rmsgList, rmsgSearch]);
+
+  /** The fork-source value to submit, derived from the active mode. */
+  function computeForkValue(): string | null {
+    if (forkMode === "none") return null;
+    if (forkMode === "rotating") return selectedRmsgId;
+    const trimmed = manualConvId.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+
+  async function handleSubmit(event: React.FormEvent): Promise<void> {
+    event.preventDefault();
+    setBanner(null);
+    setNameError(null);
+    setIdError(null);
+    setSeedError(null);
+    setForkError(null);
+    const trimmedName = displayName.trim();
+    const trimmedId = lettaAgentId.trim();
+    const trimmedSeed = sandboxSeedName.trim();
+    if (trimmedName.length === 0) {
+      setNameError(props.texts.agentNameRequiredError);
+      return;
+    }
+    if (trimmedId.length === 0) {
+      setIdError(props.texts.agentLettaIdRequiredError);
+      return;
+    }
+    setSubmitting(true);
+    try {
+      await props.onSubmit({
+        displayName: trimmedName,
+        lettaAgentId: trimmedId,
+        sandboxSeedName: trimmedSeed.length > 0 ? trimmedSeed : null,
+        forkSourceConversationId: computeForkValue(),
+      });
+    } catch (err) {
+      // Field-targeted error codes go inline; everything else goes
+      // to the generic banner.
+      if (err instanceof AIHubRequestError) {
+        switch (err.code) {
+          case "letta_agent_not_found":
+            setIdError(props.texts.agentLettaIdNotFoundError);
+            break;
+          case "seed_name_invalid":
+            setSeedError(props.texts.agentSandboxSeedInvalidError);
+            break;
+          case "seed_dir_not_found":
+            setSeedError(props.texts.agentSandboxSeedNotFoundError);
+            break;
+          case "fork_source_not_found":
+            setForkError(props.texts.agentForkSourceNotFoundError);
+            break;
+          case "fork_source_agent_mismatch":
+            setForkError(props.texts.agentForkSourceAgentMismatchError);
+            break;
+          case "rotating_message_not_found":
+            setForkError(props.texts.agentForkSourceRotatingNotFoundError);
+            break;
+          case "rotating_message_agent_mismatch":
+            setForkError(props.texts.agentForkSourceRotatingMismatchError);
+            break;
+          default: {
+            const message =
+              err.message.length > 0
+                ? err.message
+                : props.texts.agentSubmitGenericError;
+            setBanner(message);
+          }
+        }
+      } else {
+        const message =
+          err instanceof Error && err.message.length > 0
+            ? err.message
+            : props.texts.agentSubmitGenericError;
+        setBanner(message);
+      }
+      setSubmitting(false);
+    }
+  }
+
+  const titleText = isEdit
+    ? props.texts.editAgentModalTitle.replace(
+        "{name}",
+        props.initial?.displayName ?? "",
+      )
+    : props.texts.createAgentModalTitle;
+  const submitText = submitting
+    ? props.texts.agentModalSubmittingButton
+    : isEdit
+      ? props.texts.agentModalSaveButton
+      : props.texts.agentModalCreateButton;
+
+  return (
+    <div
+      className="data-club-ai-hub-admin__modal-backdrop"
+      role="presentation"
+      onMouseDown={(event) => {
+        if (event.target === event.currentTarget) props.onCancel();
+      }}
+    >
+      <div
+        className="data-club-ai-hub-admin__modal"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="agent-editor-title"
+        data-testid={`admin-agent-${props.mode}-modal`}
+      >
+        <h2
+          id="agent-editor-title"
+          className="data-club-ai-hub-admin__modal-title"
+        >
+          {titleText}
+        </h2>
+        <form onSubmit={(event) => void handleSubmit(event)} noValidate>
+          <label className="data-club-ai-hub-admin__form-field">
+            <span className="data-club-ai-hub-admin__form-label">
+              {props.texts.agentNameLabel}
+            </span>
+            <input
+              ref={firstFieldRef}
+              type="text"
+              className="data-club-ai-hub-admin__form-input"
+              data-testid="admin-agent-name-input"
+              value={displayName}
+              onChange={(event) => setDisplayName(event.target.value)}
+              required
+              maxLength={255}
+              disabled={submitting}
+            />
+            <span className="data-club-ai-hub-admin__form-helper">
+              {props.texts.agentNameHelper}
+            </span>
+            {nameError !== null ? (
+              <span
+                className="data-club-ai-hub-admin__form-error"
+                role="alert"
+                data-testid="admin-agent-name-error"
+              >
+                {nameError}
+              </span>
+            ) : null}
+          </label>
+          <label className="data-club-ai-hub-admin__form-field">
+            <span className="data-club-ai-hub-admin__form-label">
+              {props.texts.agentLettaIdLabel}
+            </span>
+            <input
+              type="text"
+              className="data-club-ai-hub-admin__form-input"
+              data-testid="admin-agent-letta-id-input"
+              value={lettaAgentId}
+              onChange={(event) => setLettaAgentId(event.target.value)}
+              required
+              maxLength={255}
+              disabled={submitting}
+            />
+            <span className="data-club-ai-hub-admin__form-helper">
+              {isEdit
+                ? props.texts.agentLettaIdReassignHelper
+                : props.texts.agentLettaIdHelper}
+            </span>
+            {idError !== null ? (
+              <span
+                className="data-club-ai-hub-admin__form-error"
+                role="alert"
+                data-testid="admin-agent-letta-id-error"
+              >
+                {idError}
+              </span>
+            ) : null}
+          </label>
+
+          <hr className="data-club-ai-hub-admin__form-divider" />
+          <h3
+            className="data-club-ai-hub-admin__form-subheading"
+            data-testid="admin-agent-specialized-heading"
+          >
+            {props.texts.agentSpecializedSectionHeading}
+          </h3>
+          <p className="data-club-ai-hub-admin__form-section-helper">
+            {props.texts.agentSpecializedSectionHelper}
+          </p>
+
+          <label className="data-club-ai-hub-admin__form-field">
+            <span className="data-club-ai-hub-admin__form-label">
+              {props.texts.agentSandboxSeedLabel}
+            </span>
+            <input
+              type="text"
+              className="data-club-ai-hub-admin__form-input"
+              data-testid="admin-agent-sandbox-seed-input"
+              value={sandboxSeedName}
+              onChange={(event) => setSandboxSeedName(event.target.value)}
+              maxLength={128}
+              disabled={submitting}
+            />
+            <span className="data-club-ai-hub-admin__form-helper">
+              {props.texts.agentSandboxSeedHelper}
+            </span>
+            {seedError !== null ? (
+              <span
+                className="data-club-ai-hub-admin__form-error"
+                role="alert"
+                data-testid="admin-agent-sandbox-seed-error"
+              >
+                {seedError}
+              </span>
+            ) : null}
+          </label>
+
+          <div className="data-club-ai-hub-admin__form-field" data-testid="admin-agent-fork-source">
+            <span className="data-club-ai-hub-admin__form-label">
+              {props.texts.agentForkSourceLabel}
+            </span>
+            <select
+              className="data-club-ai-hub-admin__form-input"
+              data-testid="admin-agent-fork-mode"
+              value={forkMode}
+              onChange={(event) => setForkMode(event.target.value as ForkMode)}
+              disabled={submitting}
+            >
+              <option value="none">{props.texts.agentForkSourceModeNone}</option>
+              <option value="rotating">{props.texts.agentForkSourceModeRotating}</option>
+              <option value="manual">{props.texts.agentForkSourceModeManual}</option>
+            </select>
+
+            {forkMode === "rotating" ? (
+              <div className="data-club-ai-hub-admin__fork-rotating">
+                <input
+                  type="text"
+                  className="data-club-ai-hub-admin__form-input"
+                  data-testid="admin-agent-fork-rotating-search"
+                  placeholder={props.texts.agentForkSourceRotatingSearchPlaceholder}
+                  value={rmsgSearch}
+                  onChange={(event) => setRmsgSearch(event.target.value)}
+                  disabled={submitting}
+                />
+                {filteredRmsgs.length === 0 ? (
+                  <p
+                    className="data-club-ai-hub-admin__form-helper"
+                    data-testid="admin-agent-fork-rotating-empty"
+                  >
+                    {props.texts.agentForkSourceRotatingEmpty}
+                  </p>
+                ) : (
+                  <ul
+                    className="data-club-ai-hub-admin__fork-rotating-list"
+                    data-testid="admin-agent-fork-rotating-list"
+                    role="listbox"
+                  >
+                    {filteredRmsgs.map((r) => (
+                      <li key={r.id}>
+                        <button
+                          type="button"
+                          role="option"
+                          aria-selected={selectedRmsgId === r.id}
+                          className={
+                            selectedRmsgId === r.id
+                              ? "data-club-ai-hub-admin__fork-rotating-item data-club-ai-hub-admin__fork-rotating-item--selected"
+                              : "data-club-ai-hub-admin__fork-rotating-item"
+                          }
+                          data-testid={`admin-agent-fork-rotating-option-${r.id}`}
+                          onClick={() => setSelectedRmsgId(r.id)}
+                          disabled={submitting}
+                        >
+                          <span>{r.display_name}</span>
+                          <code className="data-club-ai-hub-admin__mono">{r.id}</code>
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+              </div>
+            ) : null}
+
+            {forkMode === "manual" ? (
+              <input
+                type="text"
+                className="data-club-ai-hub-admin__form-input"
+                data-testid="admin-agent-fork-source-input"
+                placeholder="conv-…"
+                value={manualConvId}
+                onChange={(event) => setManualConvId(event.target.value)}
+                maxLength={255}
+                disabled={submitting}
+              />
+            ) : null}
+
+            <span className="data-club-ai-hub-admin__form-helper">
+              {props.texts.agentForkSourceHelper}
+            </span>
+            {forkError !== null ? (
+              <span
+                className="data-club-ai-hub-admin__form-error"
+                role="alert"
+                data-testid="admin-agent-fork-source-error"
+              >
+                {forkError}
+              </span>
+            ) : null}
+          </div>
+
+          {banner !== null ? (
+            <div
+              className="data-club-ai-hub-admin__error"
+              role="alert"
+              data-testid="admin-agent-modal-banner"
+            >
+              {banner}
+            </div>
+          ) : null}
+          <div className="data-club-ai-hub-admin__modal-actions">
+            <button
+              type="button"
+              className="data-club-ai-hub-admin__button"
+              data-testid="admin-agent-modal-cancel"
+              onClick={props.onCancel}
+              disabled={submitting}
+            >
+              {props.texts.agentModalCancelButton}
+            </button>
+            <button
+              type="submit"
+              className="data-club-ai-hub-admin__button data-club-ai-hub-admin__button--primary"
+              data-testid="admin-agent-modal-submit"
+              disabled={submitting}
+            >
+              {submitText}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}