@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/packages/local-runtime/src/agent-catalog-settings.test.ts

@@ -0,0 +1,224 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseAgentCatalog, parseYaml, WorkspaceFileSystem } from "@zaip-ai/core";
+import { describe, expect, it } from "vitest";
+import {
+  AgentCatalogUpdateError,
+  FRAMEWORK_AGENT_IDS,
+  prepareAgentCatalogUpdate,
+  readAgentCatalogSettings,
+} from "./agent-catalog-settings.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+
+async function currentCatalog() {
+  return parseAgentCatalog(
+    parseYaml(await readFile(resolve(workspaceRoot, ".agents/config/agents/catalog.yaml"), "utf8")),
+  );
+}
+
+describe("agent catalog settings", () => {
+  it("protects exactly the 18 current catalog agents as framework agents", async () => {
+    const current = await currentCatalog();
+
+    expect(FRAMEWORK_AGENT_IDS).toHaveLength(18);
+    expect(FRAMEWORK_AGENT_IDS).toEqual(current.agents.map((agent) => agent.id));
+  });
+
+  it("exposes configured project defaults alongside allowed options", async () => {
+    const settings = await readAgentCatalogSettings(new WorkspaceFileSystem(workspaceRoot));
+
+    expect(settings).toMatchObject({
+      default_model: "gpt-5.6-terra",
+      default_reasoning_effort: "medium",
+      allowed_models: ["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"],
+      allowed_reasoning_efforts: ["low", "medium", "high", "xhigh"],
+    });
+  });
+
+  it("keeps automatic policy semantic and assigns the approved models by role", async () => {
+    const current = await currentCatalog();
+    expect(
+      current.agents.map((agent) => [
+        agent.id,
+        agent.model.preferred[0],
+        agent.model.reasoning_effort,
+      ]),
+    ).toEqual(
+      expect.arrayContaining([
+        ["agent-orchestrator", "gpt-5.6-terra", "medium"],
+        ["agent-builder", "gpt-5.6-terra", "medium"],
+        ["agent-task-executor", "gpt-5.6-terra", "medium"],
+        ["agent-analyst", "gpt-5.6-sol", "medium"],
+        ["agent-finalizer", "gpt-5.6-terra", "medium"],
+        ["agent-reviewer", "gpt-5.6-terra", "medium"],
+        ["agent-integrator", "gpt-5.6-terra", "high"],
+        ["agent-auditor", "gpt-5.6-sol", "high"],
+        ["agent-text-summarizer", "gpt-5.6-terra", "medium"],
+        ["agent-data-analyst", "gpt-5.6-terra", "medium"],
+        ["agent-refactoring-specialist", "gpt-5.6-terra", "medium"],
+      ]),
+    );
+    expect(current.agents.some((agent) => agent.model.preferred[0] === "policy-selected")).toBe(
+      false,
+    );
+  });
+
+  it("rejects model and reasoning effort changes for every existing framework agent", async () => {
+    const current = await currentCatalog();
+    const agents = current.agents.map((agent) =>
+      FRAMEWORK_AGENT_IDS.includes(agent.id as (typeof FRAMEWORK_AGENT_IDS)[number])
+        ? {
+            ...agent,
+            model: {
+              ...agent.model,
+              preferred: ["gpt-5.6-terra"],
+              reasoning_effort: "high" as const,
+            },
+          }
+        : agent,
+    );
+
+    expect(() => prepareAgentCatalogUpdate(current, { agents })).toThrow(
+      /only allows persona name and role changes/,
+    );
+  });
+
+  it.each(FRAMEWORK_AGENT_IDS)("rejects removal of framework agent %s", async (id) => {
+    const current = await currentCatalog();
+
+    expect(() =>
+      prepareAgentCatalogUpdate(current, {
+        agents: current.agents.filter((agent) => agent.id !== id),
+      }),
+    ).toThrow(new RegExp(`cannot be removed: ${id}`));
+  });
+
+  it("rejects framework prompt and identity changes on the server", async () => {
+    const current = await currentCatalog();
+    const target = current.agents.find((agent) => agent.id === "agent-orchestrator");
+    if (target === undefined) throw new Error("Fixture is missing agent-orchestrator");
+
+    for (const changed of [
+      { ...target, purpose: "Injected prompt" },
+      {
+        ...target,
+        codex_name: "zaip-agent-replaced",
+        codex_task_name: "dave_product_owner_zaip_agent",
+        nickname_candidates: ["dave_product_owner_zaip_agent"],
+      },
+    ]) {
+      expect(() =>
+        prepareAgentCatalogUpdate(current, {
+          agents: current.agents.map((agent) => (agent.id === target.id ? changed : agent)),
+        }),
+      ).toThrow(/only allows persona name and role changes/);
+    }
+  });
+
+  it("allows a framework persona edit while preserving technical identity and deriving its only nickname", async () => {
+    const current = await currentCatalog();
+    const target = current.agents.find((agent) => agent.id === "agent-orchestrator");
+    if (target === undefined) throw new Error("Fixture is missing agent-orchestrator");
+    const updated = prepareAgentCatalogUpdate(current, {
+      agents: current.agents.map((agent) =>
+        agent.id === target.id
+          ? (() => {
+              const { nickname_candidates: _derived, ...personaOnlyAgent } = agent;
+              return { ...personaOnlyAgent, persona: { nome: "renata", cargo: "product_owner" } };
+            })()
+          : agent,
+      ),
+    });
+    const saved = updated.agents.find((agent) => agent.id === target.id);
+    expect(saved).toMatchObject({
+      codex_name: "zaip-agent-orchestrator",
+      codex_task_name: "renata_product_owner_zaip_agent",
+      persona: { nome: "renata", cargo: "product_owner" },
+      nickname_candidates: ["renata_product_owner_zaip_agent"],
+    });
+  });
+
+  it("rejects an external persona photo change for an existing agent", async () => {
+    const current = await currentCatalog();
+    const target = current.agents.find((agent) => agent.id === "agent-orchestrator");
+    if (target === undefined) throw new Error("Fixture is missing agent-orchestrator");
+
+    expect(() =>
+      prepareAgentCatalogUpdate(current, {
+        agents: current.agents.map((agent) =>
+          agent.id === target.id
+            ? {
+                ...agent,
+                persona: { ...agent.persona, foto_url: "https://example.test/renata.png" },
+              }
+            : agent,
+        ),
+      }),
+    ).toThrow(/only allows persona name and role changes/);
+  });
+
+  it("derives the nickname from persona instead of accepting a raw alteration", async () => {
+    const current = await currentCatalog();
+    const target = current.agents[0];
+    if (target === undefined) throw new Error("Catalog must contain an agent");
+    const updated = prepareAgentCatalogUpdate(current, {
+      agents: current.agents.map((agent) =>
+        agent.id === target.id ? { ...agent, nickname_candidates: ["tampered"] } : agent,
+      ),
+    });
+    expect(updated.agents.find((agent) => agent.id === target.id)?.nickname_candidates).toEqual(
+      target.nickname_candidates,
+    );
+  });
+
+  it("rejects squad mutations and catalog findings", async () => {
+    const current = await currentCatalog();
+
+    expect(() =>
+      prepareAgentCatalogUpdate(current, {
+        agents: current.agents,
+        squads: [],
+      }),
+    ).toThrow(new AgentCatalogUpdateError("Only the agents collection may be updated", 400));
+
+    expect(() =>
+      prepareAgentCatalogUpdate(current, {
+        agents: [
+          ...current.agents,
+          {
+            ...current.agents.at(-1),
+            id: "agent-duplicate-name",
+          },
+        ],
+      }),
+    ).toThrow(/duplicate-codex-name/);
+  });
+
+  it("enforces the active project model and effort allowlists", async () => {
+    const current = await currentCatalog();
+    const target = current.agents[0];
+    if (target === undefined) throw new Error("Catalog must contain an agent");
+    const options = {
+      allowed_models: ["gpt-5.6-terra"],
+      allowed_reasoning_efforts: ["low", "medium", "high", "xhigh"],
+    };
+
+    for (const model of [
+      { ...target.model, preferred: ["unsupported-model"] },
+      { ...target.model, reasoning_effort: "ultra" as const },
+    ]) {
+      expect(() =>
+        prepareAgentCatalogUpdate(
+          current,
+          {
+            agents: current.agents.map((agent) =>
+              agent.id === target.id ? { ...agent, model } : agent,
+            ),
+          },
+          options,
+        ),
+      ).toThrow(/only allows persona name and role changes/);
+    }
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/agent-catalog-settings.ts

@@ -0,0 +1,320 @@
+import { isDeepStrictEqual } from "node:util";
+import {
+  type AgentCatalog,
+  type AgentDefinition,
+  parseAgentCatalog,
+  parseProjectConfig,
+  parseYaml,
+  serializeYaml,
+  validateAgentCatalog,
+  type WorkspaceFileSystem,
+} from "@zaip-ai/core";
+
+export const AGENT_CATALOG_PATH = ".agents/config/agents/catalog.yaml";
+
+export const FRAMEWORK_AGENT_IDS = [
+  "agent-orchestrator",
+  "agent-builder",
+  "agent-task-executor",
+  "agent-analyst",
+  "agent-finalizer",
+  "agent-reviewer",
+  "agent-integrator",
+  "agent-auditor",
+  "agent-text-summarizer",
+  "agent-data-analyst",
+  "agent-refactoring-specialist",
+  "agent-frontend",
+  "agent-backend",
+  "agent-website-developer",
+  "agent-designer",
+  "agent-cloud-engineer",
+  "agent-security-auditor",
+  "agent-marketing-analyst",
+] as const;
+
+const frameworkAgentIds = new Set<string>(FRAMEWORK_AGENT_IDS);
+
+export interface AgentCatalogSettings {
+  catalog: AgentCatalog;
+  framework_agent_ids: readonly string[];
+  default_model: string | null;
+  default_reasoning_effort: string | null;
+  allowed_models: readonly string[];
+  allowed_reasoning_efforts: readonly string[];
+  sync: {
+    required: true;
+    valid: boolean | null;
+    drifted: readonly string[];
+  };
+}
+
+export interface AgentAdapterSyncResult {
+  valid: boolean;
+  drifted: readonly string[];
+}
+
+export class AgentCatalogUpdateError extends Error {
+  override readonly name = "AgentCatalogUpdateError";
+
+  constructor(
+    message: string,
+    readonly status: 400 | 409 | 500,
+  ) {
+    super(message);
+  }
+}
+
+export async function readAgentCatalogSettings(
+  filesystem: WorkspaceFileSystem,
+): Promise<AgentCatalogSettings> {
+  const modelOptions = await readAgentModelOptions(filesystem);
+  return {
+    catalog: await readAgentCatalog(filesystem),
+    framework_agent_ids: FRAMEWORK_AGENT_IDS,
+    ...modelOptions,
+    sync: { required: true, valid: null, drifted: [] },
+  };
+}
+
+export async function persistAgentCatalogUpdate(
+  filesystem: WorkspaceFileSystem,
+  rawInput: unknown,
+  syncAdapters: () => Promise<AgentAdapterSyncResult>,
+): Promise<AgentCatalogSettings> {
+  const previousSource = await filesystem.readText(AGENT_CATALOG_PATH);
+  const previous = parseAgentCatalog(parseYaml(previousSource));
+  const modelOptions = await readAgentModelOptions(filesystem);
+  const candidate = prepareAgentCatalogUpdate(previous, rawInput, modelOptions);
+  await filesystem.writeTextAtomic(AGENT_CATALOG_PATH, serializeYaml(candidate));
+
+  try {
+    const sync = await syncAdapters();
+    if (!sync.valid || sync.drifted.length > 0) {
+      throw new Error(`Adapter parity failed; drifted: ${sync.drifted.join(", ") || "unknown"}`);
+    }
+    return {
+      catalog: candidate,
+      framework_agent_ids: FRAMEWORK_AGENT_IDS,
+      ...modelOptions,
+      sync: { required: true, valid: true, drifted: [] },
+    };
+  } catch (cause) {
+    await filesystem.writeTextAtomic(AGENT_CATALOG_PATH, previousSource);
+    try {
+      await syncAdapters();
+    } catch {
+      // Preserve the original sync failure. The catalog itself has already been rolled back.
+    }
+    throw new AgentCatalogUpdateError(
+      `Agent catalog was not saved because adapter synchronization failed: ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`,
+      500,
+    );
+  }
+}
+
+export function prepareAgentCatalogUpdate(
+  current: AgentCatalog,
+  rawInput: unknown,
+  modelOptions?: {
+    allowed_models: readonly string[];
+    allowed_reasoning_efforts: readonly string[];
+  },
+): AgentCatalog {
+  if (!isRecord(rawInput) || !Array.isArray(rawInput.agents)) {
+    throw new AgentCatalogUpdateError("Request body must contain an agents array", 400);
+  }
+  if (Object.keys(rawInput).some((key) => key !== "agents")) {
+    throw new AgentCatalogUpdateError("Only the agents collection may be updated", 400);
+  }
+
+  let candidate: AgentCatalog;
+  try {
+    const normalizedAgents = rawInput.agents.map((rawAgent) => derivePersonaNickname(rawAgent));
+    candidate = parseAgentCatalog({
+      schema_version: current.schema_version,
+      agents: normalizedAgents,
+      squads: current.squads,
+    });
+  } catch (cause) {
+    throw new AgentCatalogUpdateError(cause instanceof Error ? cause.message : String(cause), 400);
+  }
+
+  assertFrameworkAgentsProtected(current, candidate);
+  assertTechnicalIdentitiesStable(current, candidate);
+  assertExistingAgentsOnlyChangePersona(current, candidate);
+  if (modelOptions !== undefined) assertAllowedAgentModels(candidate, modelOptions);
+  const findings = validateAgentCatalog(candidate);
+  if (findings.length > 0) {
+    throw new AgentCatalogUpdateError(
+      findings.map((finding) => `${finding.rule}: ${finding.message}`).join("; "),
+      409,
+    );
+  }
+  return candidate;
+}
+
+/** The nickname is presentation output, never a client-controlled catalog field. */
+function derivePersonaNickname(rawAgent: unknown): unknown {
+  if (!isRecord(rawAgent) || !isRecord(rawAgent.persona)) return rawAgent;
+  const nome = rawAgent.persona.nome;
+  const cargo = rawAgent.persona.cargo;
+  if (typeof nome !== "string" || typeof cargo !== "string") {
+    return rawAgent;
+  }
+  const expected = `${nome}_${cargo}_zaip_agent`;
+  return {
+    ...rawAgent,
+    codex_task_name: expected,
+    nickname_candidates: [expected],
+  };
+}
+
+async function readAgentModelOptions(filesystem: WorkspaceFileSystem): Promise<{
+  default_model: string | null;
+  default_reasoning_effort: string | null;
+  allowed_models: readonly string[];
+  allowed_reasoning_efforts: readonly string[];
+}> {
+  const config = parseProjectConfig(
+    parseYaml(await filesystem.readText(".agents/config/project.yaml")),
+  );
+  const orchestration = config.model_orchestration;
+  return orchestration?.mode === "auto"
+    ? {
+        default_model: orchestration.default_model,
+        default_reasoning_effort: orchestration.default_effort,
+        allowed_models: orchestration.allowed_models,
+        allowed_reasoning_efforts: orchestration.allowed_efforts,
+      }
+    : {
+        default_model: orchestration?.default_model ?? null,
+        default_reasoning_effort: orchestration?.default_effort ?? null,
+        allowed_models: [],
+        allowed_reasoning_efforts: [],
+      };
+}
+
+function assertAllowedAgentModels(
+  catalog: AgentCatalog,
+  options: {
+    allowed_models: readonly string[];
+    allowed_reasoning_efforts: readonly string[];
+  },
+): void {
+  for (const agent of catalog.agents) {
+    const invalidModel = agent.model.preferred.find(
+      (model) => model !== "policy-selected" && !options.allowed_models.includes(model),
+    );
+    if (options.allowed_models.length > 0 && invalidModel !== undefined) {
+      throw new AgentCatalogUpdateError(
+        `Agent ${agent.id} uses a model outside project.allowed_models: ${invalidModel}`,
+        400,
+      );
+    }
+    if (
+      agent.model.reasoning_effort !== undefined &&
+      options.allowed_reasoning_efforts.length > 0 &&
+      !options.allowed_reasoning_efforts.includes(agent.model.reasoning_effort)
+    ) {
+      throw new AgentCatalogUpdateError(
+        `Agent ${agent.id} uses reasoning effort outside project.allowed_efforts: ${agent.model.reasoning_effort}`,
+        400,
+      );
+    }
+  }
+}
+
+async function readAgentCatalog(filesystem: WorkspaceFileSystem): Promise<AgentCatalog> {
+  return parseAgentCatalog(parseYaml(await filesystem.readText(AGENT_CATALOG_PATH)));
+}
+
+function assertFrameworkAgentsProtected(current: AgentCatalog, candidate: AgentCatalog): void {
+  for (const id of frameworkAgentIds) {
+    const existing = current.agents.find((agent) => agent.id === id);
+    const updated = candidate.agents.find((agent) => agent.id === id);
+    if (existing === undefined || updated === undefined) {
+      throw new AgentCatalogUpdateError(`Framework agent cannot be removed: ${id}`, 409);
+    }
+    if (!isDeepStrictEqual(protectedAgentShape(existing), protectedAgentShape(updated))) {
+      throw new AgentCatalogUpdateError(
+        `Framework agent ${id} only allows persona name and role changes`,
+        409,
+      );
+    }
+  }
+}
+
+function protectedAgentShape(agent: AgentDefinition): AgentDefinition {
+  const {
+    persona,
+    codex_task_name: _taskName,
+    nickname_candidates: _nicknames,
+    ...protectedShape
+  } = agent;
+  return {
+    ...protectedShape,
+    // Persona is presentation data; it is separately constrained by the schema-derived nickname.
+    persona: { nome: "protected", cargo: "protected" },
+    codex_task_name: "protected_protected_zaip_agent",
+    nickname_candidates: ["protected_protected_zaip_agent"],
+    model: {
+      ...agent.model,
+      preferred: [],
+      reasoning_effort: undefined,
+    },
+  } as AgentDefinition;
+}
+
+function assertExistingAgentsOnlyChangePersona(
+  current: AgentCatalog,
+  candidate: AgentCatalog,
+): void {
+  for (const existing of current.agents) {
+    const updated = candidate.agents.find((agent) => agent.id === existing.id);
+    if (updated === undefined) continue;
+    if (
+      !isDeepStrictEqual(
+        existingAgentTechnicalShape(existing),
+        existingAgentTechnicalShape(updated),
+      )
+    ) {
+      throw new AgentCatalogUpdateError(
+        `Existing agent ${existing.id} only allows persona name and role changes`,
+        409,
+      );
+    }
+  }
+}
+
+function existingAgentTechnicalShape(agent: AgentDefinition): AgentDefinition {
+  const {
+    persona,
+    codex_task_name: _taskName,
+    nickname_candidates: _nicknames,
+    ...technicalShape
+  } = agent;
+  return {
+    ...technicalShape,
+    persona: { ...persona, nome: "protected", cargo: "protected" },
+  } as AgentDefinition;
+}
+
+function assertTechnicalIdentitiesStable(current: AgentCatalog, candidate: AgentCatalog): void {
+  for (const existing of current.agents) {
+    const updated = candidate.agents.find((agent) => agent.id === existing.id);
+    if (updated === undefined) continue;
+    if (existing.codex_name !== updated.codex_name) {
+      throw new AgentCatalogUpdateError(
+        `Technical identity is stable and cannot be changed: ${existing.id}`,
+        409,
+      );
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/templates/.agents/dashboard/packages/local-runtime/src/export/index.ts

@@ -0,0 +1,7 @@
+export {
+  createExportSnapshot,
+  exportPartCount,
+  exportSnapshotToXlsxParts,
+  pipeRowsWithBackpressure,
+  writeXlsxStream,
+} from "@zaip-ai/dashboard-data-export";