@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/apps/frontend/src/AgentCatalogSettingsPage.tsx

@@ -0,0 +1,617 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type {
+  AgentCatalogAgent,
+  AgentCatalogSettings,
+  AgentReasoningEffort,
+  DashboardApiClient,
+} from "./dashboard-api.js";
+import "./agent-catalog-settings-page.css";
+
+const copy = {
+  "pt-BR": {
+    eyebrow: "Configurações",
+    title: "Catálogo de agentes",
+    intro: "Os agentes do framework possuem edições limitadas para garantir o funcionamento.",
+    add: "Adicionar agente",
+    edit: "Editar",
+    save: "Salvar agente",
+    saving: "Salvando e sincronizando…",
+    cancel: "Cancelar",
+    close: "Fechar",
+    back: "Voltar ao dashboard",
+    loading: "Carregando catálogo de agentes…",
+    framework: "Framework",
+    custom: "Customizado",
+    codexName: "Identidade técnica",
+    personaName: "Persona (nome)",
+    personaRole: "Persona (cargo)",
+    prompt: "Prompt base",
+    model: "Modelo preferido",
+    automaticPolicy: "Política automática (padrão: {value})",
+    effort: "Reasoning effort",
+    identityTitle: "Identidade e instrução",
+    runtimeTitle: "Configuração de execução",
+    runtimeHint: "Escolha um valor específico ou mantenha o padrão configurado no projeto.",
+    lockedHint: "Identidade e Prompt base são protegidos pelo framework.",
+    capabilities: "Capacidades",
+    capabilitiesHint: "Selecione uma capacidade; remova qualquer badge pelo botão ×.",
+    capabilitiesLockedHint: "As capacidades do framework são somente leitura.",
+    capabilitySelect: "Selecionar capacidade",
+    capabilityRemove: "Remover",
+    photoUrl: "URL da foto",
+    remove: "Remover agente",
+    removePending: "A remoção será aplicada somente ao salvar.",
+    saveRemoval: "Salvar remoção",
+    modelSummary: "Modelo",
+    effortSummary: "Esforço",
+    editTitle: "Editar agente",
+    createTitle: "Adicionar agente",
+    modalHint: "Revise a configuração e salve para sincronizar o catálogo central e os adapters.",
+    saved: "Catálogo salvo; adapters válidos e sem drift.",
+  },
+  "en-US": {
+    eyebrow: "Settings",
+    title: "Agent Catalog",
+    intro: "Framework agents have limited editing to ensure proper operation.",
+    add: "Add custom agent",
+    edit: "Edit",
+    save: "Save agent",
+    saving: "Saving and syncing…",
+    cancel: "Cancel",
+    close: "Close",
+    back: "Back to dashboard",
+    loading: "Loading agent catalog…",
+    framework: "Framework",
+    custom: "Custom",
+    codexName: "Technical identity",
+    personaName: "Persona (name)",
+    personaRole: "Persona (role)",
+    prompt: "Base prompt",
+    model: "Preferred model",
+    automaticPolicy: "Automatic policy (default: {value})",
+    effort: "Reasoning effort",
+    identityTitle: "Identity and instruction",
+    runtimeTitle: "Execution configuration",
+    runtimeHint: "Choose a specific value or keep the default configured for this project.",
+    lockedHint: "Identity and base prompt are protected by the framework.",
+    capabilities: "Capabilities",
+    capabilitiesHint: "Select a capability; remove any badge with its × button.",
+    capabilitiesLockedHint: "Framework capabilities are read-only.",
+    capabilitySelect: "Select capability",
+    capabilityRemove: "Remove",
+    photoUrl: "Photo URL",
+    remove: "Remove agent",
+    removePending: "Removal will be applied only when you save.",
+    saveRemoval: "Save removal",
+    modelSummary: "Model",
+    effortSummary: "Effort",
+    editTitle: "Edit agent",
+    createTitle: "Add agent",
+    modalHint: "Review the configuration and save to sync the central catalog and adapters.",
+    saved: "Catalog saved; adapters are valid with no drift.",
+  },
+} as const;
+
+export function AgentCatalogSettingsPage({
+  api,
+  locale,
+  onClose,
+}: {
+  api: DashboardApiClient;
+  locale: keyof typeof copy;
+  onClose: () => void;
+}) {
+  const text = copy[locale];
+  const [settings, setSettings] = useState<AgentCatalogSettings | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [editor, setEditor] = useState<AgentCatalogEditorState | null>(null);
+  const [localPortraitFallbacks, setLocalPortraitFallbacks] = useState<Set<string>>(
+    () => new Set(),
+  );
+  const [unavailablePortraits, setUnavailablePortraits] = useState<Set<string>>(() => new Set());
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+  const openerRef = useRef<HTMLButtonElement | null>(null);
+  const addButtonRef = useRef<HTMLButtonElement>(null);
+  const savingRef = useRef(saving);
+  const isEditorOpen = editor !== null;
+  const frameworkIds = useMemo(
+    () => new Set(settings?.framework_agent_ids ?? []),
+    [settings?.framework_agent_ids],
+  );
+
+  useEffect(() => {
+    void api
+      .agentCatalog()
+      .then(setSettings)
+      .catch((cause) => setError(cause instanceof Error ? cause.message : String(cause)));
+  }, [api]);
+
+  useEffect(() => {
+    savingRef.current = saving;
+  }, [saving]);
+
+  useEffect(() => {
+    if (!isEditorOpen) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape" && !savingRef.current) setEditor(null);
+      if (event.key !== "Tab") return;
+      const modal = closeButtonRef.current?.closest<HTMLElement>('[role="dialog"]');
+      const focusable = modal
+        ? [
+            ...modal.querySelectorAll<HTMLElement>(
+              'button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
+            ),
+          ]
+        : [];
+      const first = focusable[0];
+      const last = focusable.at(-1);
+      if (!first || !last) return;
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    document.addEventListener("keydown", onKeyDown);
+    closeButtonRef.current?.focus();
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener("keydown", onKeyDown);
+      restoreAgentCatalogFocus(openerRef.current, addButtonRef.current);
+    };
+  }, [isEditorOpen]);
+
+  const updateDraft = (update: (agent: AgentCatalogAgent) => AgentCatalogAgent) => {
+    setNotice(null);
+    setEditor((current) =>
+      current === null ? null : { ...current, agent: update(current.agent) },
+    );
+  };
+
+  if (settings === null) {
+    return (
+      <main className="agent-catalog-state">
+        <p>{text.eyebrow}</p>
+        <h1>{error ?? text.loading}</h1>
+        <button onClick={onClose} type="button">
+          {text.back}
+        </button>
+      </main>
+    );
+  }
+
+  const persistAgents = async (agents: AgentCatalogAgent[]) => {
+    setSaving(true);
+    setError(null);
+    setNotice(null);
+    try {
+      const updated = await api.saveAgentCatalog(agents);
+      setSettings(updated);
+      setEditor(null);
+      setNotice(text.saved);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const saveDraft = async () => {
+    if (editor === null) return;
+    const nextAgents = applyAgentEditorDraft(settings.catalog.agents, editor);
+    await persistAgents(nextAgents);
+  };
+
+  return (
+    <main className="agent-catalog-page">
+      <header className="agent-catalog-header">
+        <div className="agent-catalog-header-actions">
+          <button className="agent-catalog-back" onClick={onClose} type="button">
+            {text.back}
+          </button>
+          <button
+            className="agent-catalog-add"
+            onClick={(event) => {
+              openerRef.current = event.currentTarget;
+              setEditor({
+                sourceId: null,
+                agent: createCustomAgent(settings.catalog.agents),
+                removeOnSave: false,
+              });
+            }}
+            ref={addButtonRef}
+            type="button"
+          >
+            {text.add}
+          </button>
+        </div>
+        <div className="agent-catalog-header-copy">
+          <p>{text.eyebrow}</p>
+          <h1>{text.title}</h1>
+          <span>{text.intro}</span>
+        </div>
+      </header>
+
+      {error ? <div className="agent-catalog-error">{error}</div> : null}
+      {notice ? <div className="agent-catalog-success">{notice}</div> : null}
+
+      <div className="agent-catalog-grid">
+        {settings.catalog.agents.map((agent) => {
+          const isFramework = frameworkIds.has(agent.id);
+          const modelSummary = effectiveModelValue(agent.model.preferred[0]);
+          const displayedModelSummary =
+            modelSummary === "policy-selected"
+              ? automaticPolicyLabel(text.automaticPolicy, settings.default_model)
+              : modelSummary;
+          const effortSummary = effectiveEffortValue(agent.model.reasoning_effort);
+          const displayedEffortSummary =
+            effortSummary === "policy-selected"
+              ? automaticPolicyLabel(text.automaticPolicy, settings.default_reasoning_effort)
+              : effortSummary;
+          const externalPortrait = safePhotoUrl(agent.persona.foto_url);
+          const usesLocalPortrait =
+            externalPortrait === null || localPortraitFallbacks.has(agent.id);
+          const hasPortrait = !unavailablePortraits.has(agent.id);
+          return (
+            <article className="agent-catalog-card" key={agent.id}>
+              {hasPortrait ? (
+                <div className="agent-catalog-card-portrait">
+                  <img
+                    alt={`Retrato de ${humanizeAgentLabel(agent.persona.nome)}`}
+                    onError={() => {
+                      if (!usesLocalPortrait && externalPortrait !== null) {
+                        setLocalPortraitFallbacks((current) => new Set([...current, agent.id]));
+                        return;
+                      }
+                      setUnavailablePortraits((current) => new Set([...current, agent.id]));
+                    }}
+                    referrerPolicy="no-referrer"
+                    src={usesLocalPortrait ? api.agentPortraitUrl(agent.id) : externalPortrait}
+                  />
+                </div>
+              ) : null}
+              <div className="agent-catalog-card-heading">
+                <div className="agent-catalog-card-title">
+                  <span className={isFramework ? "is-framework" : "is-custom"}>
+                    {isFramework ? text.framework : text.custom}
+                  </span>
+                  <h2>
+                    {humanizeAgentLabel(agent.persona.nome)} ·{" "}
+                    {humanizeAgentLabel(agent.persona.cargo)}
+                  </h2>
+                  <code>{agent.codex_name}</code>
+                </div>
+              </div>
+              <div className="agent-catalog-card-body">
+                <p className="agent-catalog-card-prompt" title={agent.purpose}>
+                  {agent.purpose}
+                </p>
+                <dl className="agent-catalog-runtime-summary">
+                  <div>
+                    <dt>{text.modelSummary}</dt>
+                    <dd>{displayedModelSummary}</dd>
+                  </div>
+                  <div>
+                    <dt>{text.effortSummary}</dt>
+                    <dd>{displayedEffortSummary}</dd>
+                  </div>
+                </dl>
+                <button
+                  className="agent-catalog-edit"
+                  onClick={(event) => {
+                    openerRef.current = event.currentTarget;
+                    setEditor({
+                      sourceId: agent.id,
+                      agent: cloneAgent(agent),
+                      removeOnSave: false,
+                    });
+                  }}
+                  type="button"
+                >
+                  {text.edit}
+                </button>
+              </div>
+            </article>
+          );
+        })}
+      </div>
+
+      {editor ? (
+        /* biome-ignore lint/a11y/noStaticElementInteractions: the backdrop only detects an outside-pointer dismissal. */
+        <div
+          className="agent-catalog-modal-backdrop"
+          onMouseDown={(event) => {
+            if (event.target === event.currentTarget && !saving) setEditor(null);
+          }}
+        >
+          <section
+            aria-labelledby="agent-catalog-editor-title"
+            aria-modal="true"
+            className="agent-catalog-modal"
+            role="dialog"
+          >
+            <header className="agent-catalog-modal-header">
+              <div>
+                <span>{editor.sourceId === null ? text.custom : text.edit}</span>
+                <h2 id="agent-catalog-editor-title">
+                  {editor.sourceId === null ? text.createTitle : text.editTitle}
+                </h2>
+                <p>{text.modalHint}</p>
+              </div>
+              <button
+                aria-label={text.close}
+                className="agent-catalog-modal-close"
+                disabled={saving}
+                onClick={() => setEditor(null)}
+                ref={closeButtonRef}
+                type="button"
+              >
+                ×
+              </button>
+            </header>
+
+            <div className="agent-catalog-modal-body">
+              {frameworkIds.has(editor.sourceId ?? "") ? (
+                <p className="agent-catalog-card-lock">{text.lockedHint}</p>
+              ) : null}
+              <section className="agent-catalog-card-section">
+                <h3>{text.identityTitle}</h3>
+                <label>
+                  <span>{text.personaName}</span>
+                  <input
+                    onChange={(event) =>
+                      updateDraft((current) =>
+                        withPersona(current, event.target.value, current.persona.cargo),
+                      )
+                    }
+                    value={editor.agent.persona.nome}
+                  />
+                </label>
+                <label>
+                  <span>{text.personaRole}</span>
+                  <input
+                    onChange={(event) =>
+                      updateDraft((current) =>
+                        withPersona(current, current.persona.nome, event.target.value),
+                      )
+                    }
+                    value={editor.agent.persona.cargo}
+                  />
+                </label>
+              </section>
+
+              {error ? <div className="agent-catalog-error">{error}</div> : null}
+            </div>
+
+            <footer className="agent-catalog-modal-actions">
+              <div>
+                {editor.sourceId !== null && !frameworkIds.has(editor.sourceId) ? (
+                  <>
+                    <button
+                      aria-pressed={editor.removeOnSave}
+                      className="agent-catalog-remove"
+                      disabled={saving}
+                      onClick={() =>
+                        setEditor((current) =>
+                          current === null ? null : { ...current, removeOnSave: true },
+                        )
+                      }
+                      type="button"
+                    >
+                      {text.remove}
+                    </button>
+                    {editor.removeOnSave ? <small>{text.removePending}</small> : null}
+                  </>
+                ) : null}
+              </div>
+              <div>
+                <button
+                  className="agent-catalog-cancel"
+                  disabled={saving}
+                  onClick={() => setEditor(null)}
+                  type="button"
+                >
+                  {text.cancel}
+                </button>
+                <button
+                  className="agent-catalog-save"
+                  disabled={saving}
+                  onClick={() => void saveDraft()}
+                  type="button"
+                >
+                  {saving ? text.saving : editor.removeOnSave ? text.saveRemoval : text.save}
+                </button>
+              </div>
+            </footer>
+          </section>
+        </div>
+      ) : null}
+    </main>
+  );
+}
+
+export interface AgentCatalogEditorState {
+  sourceId: string | null;
+  agent: AgentCatalogAgent;
+  removeOnSave: boolean;
+}
+
+export function safePhotoUrl(value: string | undefined): string | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AgentCatalogFocusTarget {
+  isConnected: boolean;
+  focus(): void;
+}
+
+export function restoreAgentCatalogFocus(
+  opener: AgentCatalogFocusTarget | null,
+  fallback: AgentCatalogFocusTarget | null,
+): void {
+  if (opener?.isConnected) {
+    opener.focus();
+    return;
+  }
+  fallback?.focus();
+}
+
+export function applyAgentEditorDraft(
+  agents: readonly AgentCatalogAgent[],
+  editor: AgentCatalogEditorState,
+): AgentCatalogAgent[] {
+  if (editor.sourceId !== null && editor.removeOnSave) {
+    return agents.filter((candidate) => candidate.id !== editor.sourceId);
+  }
+  if (editor.sourceId === null) return [...agents, editor.agent];
+  return agents.map((agent) =>
+    agent.id === editor.sourceId
+      ? {
+          ...agent,
+          persona: {
+            ...agent.persona,
+            nome: editor.agent.persona.nome,
+            cargo: editor.agent.persona.cargo,
+          },
+        }
+      : agent,
+  );
+}
+
+export function cloneAgent(agent: AgentCatalogAgent): AgentCatalogAgent {
+  return {
+    ...agent,
+    persona: { ...agent.persona },
+    nickname_candidates: [...(agent.nickname_candidates as string[])],
+    capabilities: [...agent.capabilities],
+    model: {
+      ...agent.model,
+      preferred: [...agent.model.preferred],
+    },
+  };
+}
+
+export function createCustomAgent(existing: readonly AgentCatalogAgent[]): AgentCatalogAgent {
+  let suffix = 1;
+  let id = "agent-custom";
+  while (existing.some((agent) => agent.id === id)) {
+    suffix += 1;
+    id = `agent-custom-${suffix}`;
+  }
+  const name = id.replace(/^agent-/, "");
+  return {
+    id,
+    version: 1,
+    purpose: "Execute a bounded custom task and return structured evidence to the orchestrator.",
+    codex_name: `zaip-agent-${name}`,
+    codex_task_name: `zaip_agent_${name.replaceAll("-", "_")}`,
+    persona: { nome: "custom", cargo: suffix === 1 ? "agent" : `agent_${suffix}` },
+    nickname_candidates: [
+      `custom_${suffix === 1 ? "agent" : `agent_${suffix}`}_zaip_agent_${name.replaceAll("-", "_")}`,
+    ],
+    role: "task-executor",
+    priority: 50,
+    inherits: null,
+    capabilities: ["custom-task-delivery"],
+    execution_eligibility: ["delivery"],
+    tools: ["shell-read", "test-runner"],
+    skills: ["zaip-skill-change"],
+    write_scopes: ["declared-write-scope"],
+    permissions: {
+      filesystem: { allow: ["declared-write-scope"], deny: ["outside-workspace"] },
+      network: { allow: [], deny: ["external"] },
+      shell: { allow: ["tests", "validation"], deny: ["destructive", "deploy"] },
+      deployment: { allow: [], deny: ["all"] },
+    },
+    model: {
+      required_capabilities: ["tool-use", "structured-output"],
+      preferred: ["policy-selected"],
+    },
+    budget: { soft_cycles: 20 },
+    contract: {
+      inputs: ["task", "requirements", "context-pack"],
+      outputs: ["structured-outcome"],
+      evidence: ["acceptance-evidence"],
+    },
+    review: { can_approve: false, cannot_review_roles: ["task-executor"] },
+    escalation: ["agent-orchestrator"],
+  };
+}
+
+export function effectiveConfiguredValue(value: string | null): string {
+  return value ?? "—";
+}
+
+export function humanizeAgentLabel(value: string): string {
+  return value
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((part) =>
+      part.toLowerCase() === "qa" ? "QA" : `${part[0]?.toUpperCase()}${part.slice(1)}`,
+    )
+    .join(" ");
+}
+
+export function automaticPolicyLabel(template: string, configuredDefault: string | null): string {
+  return template.replace("{value}", effectiveConfiguredValue(configuredDefault));
+}
+
+export function effectiveModelValue(preferred: string | undefined): string {
+  return preferred ?? "policy-selected";
+}
+
+export function effectiveEffortValue(effort: AgentReasoningEffort | undefined): string {
+  return effort ?? "policy-selected";
+}
+
+export function withCustomName(agent: AgentCatalogAgent, rawName: string): AgentCatalogAgent {
+  return withPersona(agent, rawName, agent.persona.cargo);
+}
+
+export function withPersona(
+  agent: AgentCatalogAgent,
+  rawName: string,
+  rawRole: string,
+): AgentCatalogAgent {
+  const personaName = normalizePersonaPart(rawName);
+  const personaRole = normalizePersonaPart(rawRole);
+  if (!personaName || !personaRole) return agent;
+  return {
+    ...agent,
+    persona: { nome: personaName, cargo: personaRole },
+    nickname_candidates: [`${personaName}_${personaRole}_zaip_agent`],
+  };
+}
+
+function normalizePersonaPart(rawName: string): string {
+  const normalized = rawName
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replaceAll("-", "_");
+  return normalized;
+}
+
+function _commaSeparatedValues(value: string): string[] {
+  return [
+    ...new Set(
+      value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+  ];
+}