@data-club/ai-hub 0.0.1

package/src/components/DataClubAIHubAdmin/AgentsPage.tsx

@@ -0,0 +1,342 @@
+/**
+ * `<AdminAgentsPage />` — the Agents sub-page mounted inside
+ * `<DataClubAIHubAdmin />` ([06-admin-agents.md]).
+ *
+ * Lists the ai-hub agents catalog with per-row `[Edit]` + `[Archive]` /
+ * `[Unarchive]` actions, top-right `[+ Create agent]` + `[↗ Open Letta ADE]`,
+ * and a `[☐ Show archived]` toggle. **No TPM⚙ button** — TPM-recovery was
+ * removed in Step 11.5 (§6.5); the column is retained on the DB schema but
+ * the UI doesn't surface it. **No 🗑 button** — agents cannot be hard-deleted
+ * in v1 (§6.3.4).
+ *
+ * Visible to `power_user`+ per §8.2. The component itself does not gate
+ * — that's the shell's job — but it expects to be mounted only inside the
+ * admin shell.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.3 / §11
+ * @see ui-sketches/06-admin-agents.md
+ */
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+
+import type { AIHubAdminTexts } from "../../auth/texts.js";
+import type { AdminAgentView } from "../../client/AIHubClient.js";
+import { useAIHub } from "../../context/useAIHub.js";
+import { useAIHubAuth } from "../../context/useAIHubAuth.js";
+
+import {
+  AgentEditorModal,
+  type AgentEditorMode,
+  type AgentEditorSubmitBody,
+} from "./AgentEditorModal.js";
+
+/** State of the editor modal: closed, or open in one of two modes. */
+type EditorState =
+  | { kind: "closed" }
+  | { kind: "create" }
+  | { kind: "edit"; agent: AdminAgentView };
+
+/** Resolves the deployment's ADE URL or derives one from the base URL. */
+function deriveAdeUrl(adeUrl: string | undefined): string | null {
+  if (!adeUrl) return null;
+  return adeUrl.replace(/\/$/, "");
+}
+
+/** Sort comparator — alphabetical by display_name, stable. */
+function byDisplayName(a: AdminAgentView, b: AdminAgentView): number {
+  return a.display_name.localeCompare(b.display_name);
+}
+
+/** Props for `<AdminAgentsPage />`. */
+export interface AdminAgentsPageProps {
+  /** Resolved admin texts. */
+  texts: AIHubAdminTexts;
+}
+
+/**
+ * Renders the Agents sub-page.
+ *
+ * @param props - see {@link AdminAgentsPageProps}.
+ * @returns the rendered page.
+ */
+export function AdminAgentsPage(props: AdminAgentsPageProps): ReactNode {
+  const { client } = useAIHub();
+  const auth = useAIHubAuth();
+  const adeUrl = deriveAdeUrl(auth.deployment?.letta_ade_url);
+
+  const [agents, setAgents] = useState<AdminAgentView[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [showArchived, setShowArchived] = useState(false);
+  const [editor, setEditor] = useState<EditorState>({ kind: "closed" });
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = await client.listAdminAgents();
+        if (!cancelled) {
+          setAgents([...rows].sort(byDisplayName));
+          setLoadError(null);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setLoadError(
+            err instanceof Error && err.message.length > 0
+              ? err.message
+              : props.texts.agentsGenericError,
+          );
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, props.texts.agentsGenericError]);
+
+  const visibleAgents = useMemo(() => {
+    if (agents === null) return null;
+    return showArchived ? agents : agents.filter((a) => !a.is_archived);
+  }, [agents, showArchived]);
+
+  async function handleCreateSubmit(body: AgentEditorSubmitBody): Promise<void> {
+    const created = await client.createAdminAgent({
+      displayName: body.displayName,
+      lettaAgentId: body.lettaAgentId,
+      sandboxSeedName: body.sandboxSeedName,
+      forkSourceConversationId: body.forkSourceConversationId,
+    });
+    setAgents((prev) => {
+      const next = prev === null ? [created] : [...prev, created];
+      return next.sort(byDisplayName);
+    });
+    setEditor({ kind: "closed" });
+  }
+
+  async function handleEditSubmit(
+    target: AdminAgentView,
+    body: AgentEditorSubmitBody,
+  ): Promise<void> {
+    const updated = await client.patchAdminAgent(target.id, {
+      displayName: body.displayName,
+      lettaAgentId: body.lettaAgentId,
+      sandboxSeedName: body.sandboxSeedName,
+      forkSourceConversationId: body.forkSourceConversationId,
+    });
+    setAgents((prev) =>
+      prev === null
+        ? [updated]
+        : prev.map((a) => (a.id === updated.id ? updated : a)).sort(byDisplayName),
+    );
+    setEditor({ kind: "closed" });
+  }
+
+  async function handleArchive(target: AdminAgentView): Promise<void> {
+    const prompt = props.texts.agentArchiveConfirmPrompt.replace(
+      "{name}",
+      target.display_name,
+    );
+    // Native confirm is fine for v1 per [06-admin-agents.md].
+    // eslint-disable-next-line no-alert
+    const ok =
+      typeof window !== "undefined" && typeof window.confirm === "function"
+        ? window.confirm(prompt)
+        : true;
+    if (!ok) return;
+    const updated = await client.patchAdminAgent(target.id, { isArchived: true });
+    setAgents((prev) =>
+      prev === null
+        ? [updated]
+        : prev.map((a) => (a.id === updated.id ? updated : a)),
+    );
+  }
+
+  async function handleUnarchive(target: AdminAgentView): Promise<void> {
+    const updated = await client.patchAdminAgent(target.id, { isArchived: false });
+    setAgents((prev) =>
+      prev === null
+        ? [updated]
+        : prev.map((a) => (a.id === updated.id ? updated : a)),
+    );
+  }
+
+  return (
+    <div
+      className="data-club-ai-hub-admin__agents-page"
+      data-testid="admin-agents-page"
+    >
+      <header className="data-club-ai-hub-admin__page-header">
+        <h1
+          className="data-club-ai-hub-admin__page-heading"
+          data-testid="admin-agents-heading"
+        >
+          {props.texts.agentsHeading}
+        </h1>
+        <div className="data-club-ai-hub-admin__page-header-actions">
+          {adeUrl !== null ? (
+            <a
+              className="data-club-ai-hub-admin__button"
+              data-testid="admin-agents-open-ade"
+              href={adeUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              {props.texts.openLettaAdeButton}
+            </a>
+          ) : null}
+          <button
+            type="button"
+            className="data-club-ai-hub-admin__button data-club-ai-hub-admin__button--primary"
+            data-testid="admin-agents-create"
+            onClick={() => setEditor({ kind: "create" })}
+          >
+            {props.texts.createAgentButton}
+          </button>
+        </div>
+      </header>
+      {loadError !== null ? (
+        <div
+          className="data-club-ai-hub-admin__error"
+          data-testid="admin-agents-error"
+          role="alert"
+        >
+          {loadError}
+        </div>
+      ) : null}
+      {agents === null && loadError === null ? (
+        <p
+          className="data-club-ai-hub-admin__loading"
+          data-testid="admin-agents-loading"
+        >
+          {props.texts.agentsLoading}
+        </p>
+      ) : null}
+      {visibleAgents !== null && visibleAgents.length === 0 ? (
+        <p
+          className="data-club-ai-hub-admin__empty"
+          data-testid="admin-agents-empty"
+        >
+          {props.texts.agentsEmpty}
+        </p>
+      ) : null}
+      {visibleAgents !== null && visibleAgents.length > 0 ? (
+        <table
+          className="data-club-ai-hub-admin__agents-table"
+          data-testid="admin-agents-table"
+        >
+          <thead>
+            <tr>
+              <th>{props.texts.agentColumnName}</th>
+              <th>{props.texts.agentColumnLettaId}</th>
+              <th>{props.texts.agentColumnStatus}</th>
+              <th>{props.texts.agentColumnActions}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {visibleAgents.map((a) => (
+              <tr
+                key={a.id}
+                data-testid={`admin-agent-row-${a.id}`}
+                data-archived={a.is_archived ? "true" : "false"}
+                className={
+                  a.is_archived
+                    ? "data-club-ai-hub-admin__agents-row data-club-ai-hub-admin__agents-row--archived"
+                    : "data-club-ai-hub-admin__agents-row"
+                }
+              >
+                <td>{a.display_name}</td>
+                <td>
+                  <code className="data-club-ai-hub-admin__mono">
+                    {a.letta_agent_id}
+                  </code>
+                </td>
+                <td>
+                  <span
+                    className={
+                      a.is_archived
+                        ? "data-club-ai-hub-admin__status-pill data-club-ai-hub-admin__status-pill--archived"
+                        : "data-club-ai-hub-admin__status-pill data-club-ai-hub-admin__status-pill--active"
+                    }
+                  >
+                    {a.is_archived
+                      ? props.texts.agentStatusArchived
+                      : props.texts.agentStatusActive}
+                  </span>
+                </td>
+                <td>
+                  <button
+                    type="button"
+                    className="data-club-ai-hub-admin__row-action"
+                    data-testid={`admin-agent-row-${a.id}-edit`}
+                    onClick={() => setEditor({ kind: "edit", agent: a })}
+                  >
+                    {props.texts.agentEditButton}
+                  </button>
+                  {a.is_archived ? (
+                    <button
+                      type="button"
+                      className="data-club-ai-hub-admin__row-action"
+                      data-testid={`admin-agent-row-${a.id}-unarchive`}
+                      onClick={() => {
+                        void handleUnarchive(a);
+                      }}
+                    >
+                      {props.texts.agentUnarchiveButton}
+                    </button>
+                  ) : (
+                    <button
+                      type="button"
+                      className="data-club-ai-hub-admin__row-action"
+                      data-testid={`admin-agent-row-${a.id}-archive`}
+                      onClick={() => {
+                        void handleArchive(a);
+                      }}
+                    >
+                      {props.texts.agentArchiveButton}
+                    </button>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      ) : null}
+      <label className="data-club-ai-hub-admin__filter-toggle">
+        <input
+          type="checkbox"
+          data-testid="admin-agents-show-archived"
+          checked={showArchived}
+          onChange={(event) => setShowArchived(event.target.checked)}
+        />
+        <span>{props.texts.agentShowArchivedToggle}</span>
+      </label>
+      <p
+        className="data-club-ai-hub-admin__footnote"
+        data-testid="admin-agents-footnote"
+      >
+        {props.texts.agentsAdeFootnote}
+      </p>
+
+      {editor.kind === "create" ? (
+        <AgentEditorModal
+          mode={"create" satisfies AgentEditorMode}
+          texts={props.texts}
+          onSubmit={handleCreateSubmit}
+          onCancel={() => setEditor({ kind: "closed" })}
+        />
+      ) : null}
+      {editor.kind === "edit" ? (
+        <AgentEditorModal
+          mode={"edit" satisfies AgentEditorMode}
+          initial={{
+            displayName: editor.agent.display_name,
+            lettaAgentId: editor.agent.letta_agent_id,
+            sandboxSeedName: editor.agent.sandbox_seed_name,
+            forkSourceConversationId: editor.agent.fork_source_conversation_id,
+          }}
+          texts={props.texts}
+          onSubmit={(body) => handleEditSubmit(editor.agent, body)}
+          onCancel={() => setEditor({ kind: "closed" })}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/DataClubAIHubAdmin/CreateUserModal.tsx

@@ -0,0 +1,214 @@
+/**
+ * `<CreateUserModal />` — Phase-1 form for the create-user flow.
+ *
+ * Submitting POSTs `/admin/users` (server generates the password); the
+ * one-time plaintext is returned in the response and surfaced via
+ * `<PasswordRevealModal />` afterward — the parent owns the phase
+ * transition because the password is the parent's state to keep until
+ * dismissed.
+ *
+ * Role-option filtering ([05-admin-users.md]):
+ *
+ * - `admin` callers see `user / power_user / admin`. They cannot create
+ *   `super_admin`s — server enforces and the dropdown hides the option.
+ * - `super_admin` callers additionally see `super_admin`.
+ *
+ * @see SPECIFICATIONS.md §6.3.4 / §8.5
+ * @see ui-sketches/05-admin-users.md — create_user_modal
+ */
+import { useState, type FormEvent, type ReactNode } from "react";
+
+import type { AIHubAdminTexts } from "../../auth/texts.js";
+import { AIHubRequestError } from "../../client/AIHubClient.js";
+import type { AIHubRole } from "../../types.js";
+
+/** The role options each caller role can offer. */
+function roleOptionsForCaller(role: AIHubRole | null): AIHubRole[] {
+  if (role === "super_admin") {
+    return ["user", "power_user", "admin", "super_admin"];
+  }
+  return ["user", "power_user", "admin"];
+}
+
+/**
+ * Props for `<CreateUserModal />`.
+ */
+export interface CreateUserModalProps {
+  /** Caller's role — drives the role-option filter. */
+  callerRole: AIHubRole | null;
+  /** Resolved admin texts. */
+  texts: AIHubAdminTexts;
+  /**
+   * Submits the form. Resolves on success; throws `AIHubRequestError` on
+   * validation / forbidden / `username_taken` so the modal can surface the
+   * right inline message.
+   */
+  onSubmit: (input: {
+    username: string;
+    displayName: string | null;
+    role: AIHubRole;
+  }) => Promise<void>;
+  /** Fired when the admin clicks Cancel (no server call). */
+  onCancel: () => void;
+}
+
+/**
+ * Renders the create-user modal.
+ *
+ * @param props - see `CreateUserModalProps`.
+ * @returns the rendered modal.
+ */
+export function CreateUserModal(props: CreateUserModalProps): ReactNode {
+  const options = roleOptionsForCaller(props.callerRole);
+  const [username, setUsername] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [role, setRole] = useState<AIHubRole>(options[0] ?? "user");
+  const [submitting, setSubmitting] = useState(false);
+  const [errorText, setErrorText] = useState<string | null>(null);
+
+  function roleLabel(r: AIHubRole): string {
+    if (r === "super_admin") return props.texts.roleOptionSuperAdmin;
+    if (r === "admin") return props.texts.roleOptionAdmin;
+    if (r === "power_user") return props.texts.roleOptionPowerUser;
+    return props.texts.roleOptionUser;
+  }
+
+  async function handleSubmit(e: FormEvent<HTMLFormElement>): Promise<void> {
+    e.preventDefault();
+    const trimmed = username.trim();
+    if (trimmed.length === 0) {
+      setErrorText(props.texts.createUserUsernameRequiredError);
+      return;
+    }
+    setErrorText(null);
+    setSubmitting(true);
+    try {
+      await props.onSubmit({
+        username: trimmed,
+        displayName: displayName.trim().length > 0 ? displayName.trim() : null,
+        role,
+      });
+      // Parent unmounts us on success → no further state work here.
+    } catch (err) {
+      // Map known error codes to localized strings; fall back to generic.
+      if (err instanceof AIHubRequestError) {
+        if (err.code === "username_taken" || err.status === 409) {
+          setErrorText(props.texts.createUserUsernameTakenError);
+        } else if (err.message) {
+          setErrorText(err.message);
+        } else {
+          setErrorText(props.texts.createUserGenericError);
+        }
+      } else {
+        setErrorText(props.texts.createUserGenericError);
+      }
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div
+      className="data-club-ai-hub-admin__modal-backdrop"
+      role="presentation"
+    >
+      <form
+        className="data-club-ai-hub-admin__modal"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="create-user-modal-title"
+        data-testid="create-user-modal"
+        onSubmit={(e) => {
+          void handleSubmit(e);
+        }}
+      >
+        <h2
+          id="create-user-modal-title"
+          className="data-club-ai-hub-admin__modal-title"
+        >
+          {props.texts.createUserModalTitle}
+        </h2>
+        {errorText !== null ? (
+          <div
+            className="data-club-ai-hub-admin__modal-error"
+            data-testid="create-user-error"
+            role="alert"
+          >
+            {errorText}
+          </div>
+        ) : null}
+        <label
+          className="data-club-ai-hub-admin__modal-field"
+        >
+          <span className="data-club-ai-hub-admin__modal-label">
+            {props.texts.createUserUsernameLabel}
+          </span>
+          <input
+            type="text"
+            value={username}
+            onChange={(e) => setUsername(e.target.value)}
+            className="data-club-ai-hub-admin__modal-input"
+            data-testid="create-user-username"
+            autoFocus
+            disabled={submitting}
+          />
+        </label>
+        <label
+          className="data-club-ai-hub-admin__modal-field"
+        >
+          <span className="data-club-ai-hub-admin__modal-label">
+            {props.texts.createUserDisplayLabel}
+          </span>
+          <input
+            type="text"
+            value={displayName}
+            onChange={(e) => setDisplayName(e.target.value)}
+            className="data-club-ai-hub-admin__modal-input"
+            data-testid="create-user-display"
+            disabled={submitting}
+          />
+        </label>
+        <label
+          className="data-club-ai-hub-admin__modal-field"
+        >
+          <span className="data-club-ai-hub-admin__modal-label">
+            {props.texts.createUserRoleLabel}
+          </span>
+          <select
+            value={role}
+            onChange={(e) => setRole(e.target.value as AIHubRole)}
+            className="data-club-ai-hub-admin__modal-input"
+            data-testid="create-user-role"
+            disabled={submitting}
+          >
+            {options.map((r) => (
+              <option key={r} value={r}>
+                {roleLabel(r)}
+              </option>
+            ))}
+          </select>
+        </label>
+        <div className="data-club-ai-hub-admin__modal-actions">
+          <button
+            type="button"
+            className="data-club-ai-hub-admin__button"
+            data-testid="create-user-cancel"
+            onClick={props.onCancel}
+            disabled={submitting}
+          >
+            {props.texts.createUserCancelButton}
+          </button>
+          <button
+            type="submit"
+            className="data-club-ai-hub-admin__button data-club-ai-hub-admin__button--primary"
+            data-testid="create-user-submit"
+            disabled={submitting || username.trim().length === 0}
+          >
+            {submitting
+              ? props.texts.createUserSubmittingButton
+              : props.texts.createUserSubmitButton}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}