@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/specialty-registry.ts

@@ -0,0 +1,236 @@
+/**
+ * admin/src/specialty-registry.ts
+ *
+ * Specialty manifest schema — the single source of truth for the
+ * `shipwright.dev/v1alpha1` / `Specialty` YAML manifest that declares an
+ * specialty's identity, crons, plugins, tools, env contract, membership,
+ * repos, and chat/voice toggles.
+ *
+ * Named "specialty-registry" (not "manifest") to avoid colliding with the
+ * two existing "manifest" concepts in this repo: the Kubernetes manifests in
+ * ./agent-manifest.ts and the Slack app manifest. This module is unrelated
+ * to either — it's a declarative spec fed into scripts/CLI tooling, not a
+ * wire type, so it uses plain `zod` rather than `@hono/zod-openapi`'s
+ * `.openapi()`-augmented `z` (kept simple for JSON Schema conversion).
+ *
+ * Manifests are treated as a trust boundary: they may originate from
+ * third-party contributors, so every object schema is `.strict()` (unknown
+ * keys rejected, not silently stripped) and the env contract is
+ * deliberately keys-only — no `value`/`default` field is permitted on an
+ * env entry, so a manifest can declare *that* a var is needed without ever
+ * carrying a real value.
+ */
+
+import { isOrgRepo } from "@app-vitals/agent-lib/org-repo";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+/** RFC1123 label pattern (see admin/src/agent-manifest.ts's sanitizeAgentName). */
+const RFC1123_NAME = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
+
+// ─── metadata.skills[] (A2A-aligned) ───────────────────────────────────────
+
+/**
+ * Minimal A2A (Agent2Agent) "skill" shape: what the specialty can do, as a
+ * small catalog entry. Kept intentionally narrow — id/name/description plus
+ * optional free-form tags — since this repo has no existing A2A convention
+ * to align with beyond the general shape of an agent capability card.
+ */
+const SpecialtySkillSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    tags: z.array(z.string()).optional(),
+  })
+  .strict();
+
+// ─── metadata ───────────────────────────────────────────────────────────────
+
+const SpecialtyMetadataSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(RFC1123_NAME, "metadata.name must be a valid RFC1123 label"),
+    displayName: z.string().min(1),
+    description: z.string().min(1),
+    version: z.string().min(1),
+    skills: z.array(SpecialtySkillSchema),
+  })
+  .strict();
+
+// ─── identity ───────────────────────────────────────────────────────────────
+
+const SpecialtyIdentitySchema = z
+  .object({
+    templatesDir: z.string().min(1),
+  })
+  .strict();
+
+// ─── crons[] ────────────────────────────────────────────────────────────────
+
+/**
+ * A single cron template declared inside a Specialty manifest. Distinct
+ * from the runtime, DB-backed AgentCronJobSchema (admin/src/openapi-schemas.ts)
+ * and CreateAgentCronJobInput (admin/src/agent-cron-jobs.ts) — those describe
+ * per-agent-instance rows already created in Postgres; this describes a
+ * *template* inside a versioned spec. `parentCron` here is a name reference
+ * resolved within this manifest's own crons[] array (validated by the
+ * top-level schema's superRefine below), not a DB id reference.
+ */
+const SpecialtyCronSchema = z
+  .object({
+    name: z.string().min(1),
+    schedule: z.string().min(1),
+    prompt: z.string().min(1),
+    preCheck: z.string().optional(),
+    silent: z.boolean().optional().default(false),
+    enabled: z.boolean().optional().default(true),
+    parentCron: z.string().optional(),
+  })
+  .strict();
+
+// ─── env contract ───────────────────────────────────────────────────────────
+
+/**
+ * A single env contract entry. Keys-only by design: a manifest declares that
+ * a var is needed (and whether it's secret) — it never carries a `value` or
+ * `default`. `.strict()` ensures an unexpected `value` key is rejected, not
+ * silently stripped, since manifests are potential third-party input.
+ */
+const SpecialtyEnvEntrySchema = z
+  .object({
+    key: z.string().min(1),
+    description: z.string().min(1),
+    secret: z.boolean(),
+  })
+  .strict();
+
+const SpecialtyEnvSchema = z
+  .object({
+    required: z.array(SpecialtyEnvEntrySchema),
+    optional: z.array(SpecialtyEnvEntrySchema),
+  })
+  .strict();
+
+// ─── resources override (optional) ─────────────────────────────────────────
+
+/**
+ * Optional override of the default agent container resources (see
+ * resolveAgentContainerResources in admin/src/agent-manifest.ts). All fields
+ * optional — a manifest may override just one of requests/limits.
+ *
+ * Not yet wired to any provisioner — parsed as part of
+ * SpecialtyManifestSchema.resources but inert until a future task consumes it
+ * ahead of resolveAgentContainerResources's env-override layer (see that
+ * function's precedence-rule doc comment).
+ */
+const SpecialtyResourceListSchema = z
+  .object({
+    cpu: z.string().optional(),
+    memory: z.string().optional(),
+    "ephemeral-storage": z.string().optional(),
+  })
+  .strict();
+
+const SpecialtyResourcesSchema = z
+  .object({
+    requests: SpecialtyResourceListSchema.optional(),
+    limits: SpecialtyResourceListSchema.optional(),
+  })
+  .strict();
+
+// ─── Top-level Specialty manifest ──────────────────────────────────────────
+
+export const SpecialtyManifestSchema = z
+  .object({
+    apiVersion: z.literal("shipwright.dev/v1alpha1"),
+    kind: z.literal("Specialty"),
+    metadata: SpecialtyMetadataSchema,
+    identity: SpecialtyIdentitySchema,
+    crons: z.array(SpecialtyCronSchema),
+    plugins: z.array(z.string()),
+    tools: z.array(z.string()),
+    env: SpecialtyEnvSchema,
+    members: z.array(z.string()),
+    repos: z.array(
+      z.string().refine(isOrgRepo, {
+        message: "each repo must be in org/repo format",
+      }),
+    ),
+    chat: z.boolean(),
+    voice: z.boolean(),
+    resources: SpecialtyResourcesSchema.optional(),
+  })
+  .strict()
+  .superRefine((manifest, ctx) => {
+    const cronNames = new Set(manifest.crons.map((c) => c.name));
+    manifest.crons.forEach((cron, index) => {
+      if (cron.parentCron === undefined) return;
+      if (cron.parentCron === cron.name) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["crons", index, "parentCron"],
+          message: `parentCron "${cron.parentCron}" cannot reference its own cron entry`,
+        });
+        return;
+      }
+      if (!cronNames.has(cron.parentCron)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["crons", index, "parentCron"],
+          message: `parentCron "${cron.parentCron}" does not match any cron name in this manifest`,
+        });
+      }
+    });
+  });
+
+export type SpecialtyManifest = z.infer<typeof SpecialtyManifestSchema>;
+
+// ─── Parsing ────────────────────────────────────────────────────────────────
+
+/**
+ * Parse and validate a YAML Specialty manifest string.
+ *
+ * Pure — no I/O. `content` is the already-read YAML text; throws a
+ * descriptive Error (with the underlying ZodError's field-path issues
+ * embedded in `message`, and the ZodError itself reachable via `cause`) if
+ * the manifest fails schema validation.
+ */
+export function parseSpecialtyManifest(content: string): SpecialtyManifest {
+  const raw: unknown = parseYaml(content);
+  const result = SpecialtyManifestSchema.safeParse(raw);
+  if (!result.success) {
+    const details = result.error.issues
+      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      .join("; ");
+    throw new Error(`invalid Specialty manifest — ${details}`, {
+      cause: result.error,
+    });
+  }
+  return result.data;
+}
+
+// ─── JSON Schema generation ─────────────────────────────────────────────────
+
+/**
+ * Build the JSON-serializable JSON Schema object for SpecialtyManifestSchema.
+ *
+ * Pure — no file I/O — so both scripts/generate-specialty-schema.ts's CLI
+ * entrypoint and its content test can call this directly instead of shelling
+ * out. Uses zod 4's built-in `z.toJSONSchema` (draft-07 target, to stay
+ * contract-compatible with the previous zod-to-json-schema output).
+ */
+export function buildSpecialtyJsonSchema(): Record<string, unknown> {
+  const { $schema, ...definition } = z.toJSONSchema(SpecialtyManifestSchema, {
+    target: "draft-7",
+    io: "input",
+  });
+  // Wrap as a named definition (`$ref` + `definitions`) — the shape the
+  // previous zod-to-json-schema output used, so consumers see no change.
+  return {
+    $ref: "#/definitions/SpecialtyManifest",
+    definitions: { SpecialtyManifest: definition },
+    $schema,
+  };
+}

package/src/specialty-registry.unit.test.ts

@@ -0,0 +1,272 @@
+/**
+ * admin/src/specialty-registry.unit.test.ts
+ * Unit tests for the pure Specialty manifest schema + parser. No I/O, no
+ * network, no fs — parseSpecialtyManifest takes a YAML string in memory and
+ * returns/throws in-process.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { stringify as stringifyYaml } from "yaml";
+import {
+  SpecialtyManifestSchema,
+  parseSpecialtyManifest,
+} from "./specialty-registry.ts";
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+/** A minimal valid manifest object. Pass overrides for the fields a test cares about. */
+function baseManifest(overrides: Record<string, unknown> = {}) {
+  return {
+    apiVersion: "shipwright.dev/v1alpha1",
+    kind: "Specialty",
+    metadata: {
+      name: "dude-agent",
+      displayName: "The Dude",
+      description: "A laid-back team member agent.",
+      version: "1.0.0",
+      skills: [],
+    },
+    identity: { templatesDir: "templates/dude" },
+    crons: [],
+    plugins: [],
+    tools: [],
+    env: { required: [], optional: [] },
+    members: [],
+    repos: [],
+    chat: true,
+    voice: false,
+    ...overrides,
+  };
+}
+
+/** Round-trips a manifest object through YAML so tests exercise the real parse path. */
+function parseManifestYaml(manifest: Record<string, unknown>) {
+  return parseSpecialtyManifest(stringifyYaml(manifest));
+}
+
+function expectThrowsWithMessage(manifest: Record<string, unknown>, ...fragments: string[]) {
+  expect(() => parseManifestYaml(manifest)).toThrow();
+  try {
+    parseManifestYaml(manifest);
+    throw new Error("expected parseSpecialtyManifest to throw");
+  } catch (err) {
+    const message = (err as Error).message;
+    for (const fragment of fragments) {
+      expect(message).toContain(fragment);
+    }
+  }
+}
+
+// ─── Valid manifest ─────────────────────────────────────────────────────────
+
+describe("parseSpecialtyManifest — valid manifest", () => {
+  it("parses a valid minimal manifest successfully", () => {
+    const manifest = parseManifestYaml(
+      baseManifest({
+        metadata: {
+          name: "dude-agent",
+          displayName: "The Dude",
+          description: "A laid-back team member agent.",
+          version: "1.0.0",
+          skills: [
+            {
+              id: "chill",
+              name: "Stay Chill",
+              description: "Keeps things mellow.",
+              tags: ["vibe"],
+            },
+          ],
+        },
+        crons: [
+          {
+            name: "morning-brief",
+            schedule: "0 9 * * 1-5",
+            prompt: "Run the morning brief.",
+          },
+        ],
+        plugins: ["@shipwright/plugin"],
+        tools: ["Read", "Write"],
+        env: {
+          required: [
+            {
+              key: "SHIPWRIGHT_API_URL",
+              description: "Base URL of the admin API.",
+              secret: false,
+            },
+          ],
+          optional: [
+            {
+              key: "GROQ_API_KEY",
+              description: "Optional Groq API key for voice.",
+              secret: true,
+            },
+          ],
+        },
+        members: ["alice"],
+        repos: ["my-org/my-repo"],
+      }),
+    );
+    expect(manifest.apiVersion).toBe("shipwright.dev/v1alpha1");
+    expect(manifest.kind).toBe("Specialty");
+    expect(manifest.metadata.name).toBe("dude-agent");
+    expect(manifest.identity.templatesDir).toBe("templates/dude");
+    expect(manifest.crons).toHaveLength(1);
+    expect(manifest.chat).toBe(true);
+    expect(manifest.voice).toBe(false);
+  });
+
+  it("accepts a cron whose parentCron resolves to a sibling cron name", () => {
+    const manifest = parseManifestYaml(
+      baseManifest({
+        crons: [
+          {
+            name: "parent-cron",
+            schedule: "0 9 * * 1-5",
+            prompt: "Parent prompt.",
+          },
+          {
+            name: "child-cron",
+            schedule: "0 10 * * 1-5",
+            prompt: "Child prompt.",
+            parentCron: "parent-cron",
+          },
+        ],
+      }),
+    );
+    expect(manifest.crons[1].parentCron).toBe("parent-cron");
+  });
+});
+
+// ─── Acceptance criterion 1 — failure cases ────────────────────────────────
+
+describe("parseSpecialtyManifest — invalid manifests fail with field-path errors", () => {
+  it("rejects a cron missing its required schedule field", () => {
+    expectThrowsWithMessage(
+      baseManifest({
+        crons: [{ name: "bad-cron", prompt: "Missing schedule." }],
+      }),
+      "crons",
+      "schedule",
+    );
+  });
+
+  it("rejects an unknown top-level field", () => {
+    expectThrowsWithMessage(
+      baseManifest({ unknownField: "surprise" }),
+      "unknownField",
+    );
+  });
+
+  it("rejects an env entry carrying a value key (trust boundary)", () => {
+    expectThrowsWithMessage(
+      baseManifest({
+        env: {
+          required: [
+            {
+              key: "SOME_KEY",
+              description: "has a value, which is forbidden",
+              secret: false,
+              value: "should not be allowed",
+            },
+          ],
+          optional: [],
+        },
+      }),
+      "env",
+      "value",
+    );
+  });
+
+  it("rejects a dangling parentCron reference", () => {
+    expectThrowsWithMessage(
+      baseManifest({
+        crons: [
+          {
+            name: "only-cron",
+            schedule: "0 9 * * 1-5",
+            prompt: "Prompt.",
+            parentCron: "does-not-exist",
+          },
+        ],
+      }),
+      "parentCron",
+    );
+  });
+
+  it("rejects a non-RFC1123 metadata.name", () => {
+    expectThrowsWithMessage(
+      baseManifest({
+        metadata: {
+          name: "Dude_Agent!",
+          displayName: "The Dude",
+          description: "desc",
+          version: "1.0.0",
+          skills: [],
+        },
+      }),
+      "metadata",
+      "name",
+    );
+  });
+});
+
+// ─── Schema-level checks (direct safeParse, matching repo convention) ──────
+
+describe("SpecialtyManifestSchema.safeParse", () => {
+  it("rejects a self-referencing parentCron", () => {
+    const result = SpecialtyManifestSchema.safeParse(
+      baseManifest({
+        crons: [
+          {
+            name: "self-cron",
+            schedule: "0 9 * * 1-5",
+            prompt: "Prompt.",
+            parentCron: "self-cron",
+          },
+        ],
+      }),
+    );
+    expect(result.success).toBe(false);
+  });
+
+  it("defaults silent/enabled on a cron entry when omitted", () => {
+    const result = SpecialtyManifestSchema.safeParse(
+      baseManifest({
+        crons: [
+          { name: "morning-brief", schedule: "0 9 * * 1-5", prompt: "Prompt." },
+        ],
+      }),
+    );
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.crons[0].silent).toBe(false);
+      expect(result.data.crons[0].enabled).toBe(true);
+    }
+  });
+
+  it("rejects a bad apiVersion literal", () => {
+    const result = SpecialtyManifestSchema.safeParse(
+      baseManifest({ apiVersion: "shipwright.dev/v1" }),
+    );
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a repos entry not in org/repo format", () => {
+    const result = SpecialtyManifestSchema.safeParse(
+      baseManifest({ repos: ["not-a-valid-repo"] }),
+    );
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts an optional resources override", () => {
+    const result = SpecialtyManifestSchema.safeParse(
+      baseManifest({
+        resources: {
+          requests: { cpu: "500m", memory: "2Gi", "ephemeral-storage": "1Gi" },
+          limits: { memory: "8Gi", "ephemeral-storage": "1Gi" },
+        },
+      }),
+    );
+    expect(result.success).toBe(true);
+  });
+});

package/src/startup-policy-reconcile.ts

@@ -0,0 +1,77 @@
+/**
+ * admin/src/startup-policy-reconcile.ts
+ *
+ * One-shot policy-only reconcile run on admin startup (ACP-1.3).
+ *
+ * The chart passes the Claude policy hash to admin as an env var, so a policy
+ * change restarts admin. On boot this pass walks every managed agent through
+ * `provisioner.reconcile(..., { policyOnly: true })`, which patches only the
+ * policy wiring (volume, mount, hash annotation) — so only agents whose policy
+ * actually changed roll. It runs whether or not a policy is configured, so
+ * agents lose the mount after the policy is disabled. The same pass applies
+ * the Anthropic workload identity federation wiring (ServiceAccount, projected
+ * token volume, mount, federation env), so turning federation on or off and
+ * restarting admin corrects existing agents.
+ *
+ * The startup pass never moves agents onto their own per-agent identity: that
+ * creates Anthropic and Kubernetes resources, which should not happen as a side
+ * effect of a boot. Operators run POST /agents/reconcile (with dryRun=true
+ * first); this pass only reports how many agents have no owner (noOwner).
+ *
+ * Never throws: a Kubernetes or database failure is logged and admin keeps
+ * serving. Called once from main.ts after Bun.serve.
+ */
+
+import type { AgentProvisioner, ReconcileTarget } from "./agent-provisioner.ts";
+import type { AgentService, AgentSummary } from "./agents.ts";
+
+interface StartupPolicyReconcileDeps {
+  agentService: Pick<AgentService, "list">;
+  provisioner: Pick<AgentProvisioner, "canProvision" | "reconcile">;
+  logger: Pick<Console, "log" | "error">;
+}
+
+/**
+ * The reconcile targets for a list of agents. Self-hosted agents manage their
+ * own workloads, so they are excluded from K8s reconciliation. Shared with
+ * POST /agents/reconcile so both paths select agents the same way.
+ */
+export function managedReconcileTargets(
+  agents: AgentSummary[],
+): ReconcileTarget[] {
+  return agents
+    .filter((a) => !a.selfHosted)
+    .map((a) => ({
+      id: a.id,
+      slug: a.name,
+      accountId: a.accountId,
+      ownerEmail: a.ownerEmail,
+      anthropicIdentityName: a.anthropicIdentityName,
+      anthropicServiceAccountId: a.anthropicServiceAccountId,
+      anthropicFederationRuleId: a.anthropicFederationRuleId,
+      k8sServiceAccountName: a.k8sServiceAccountName,
+    }));
+}
+
+export async function runStartupPolicyReconcile({
+  agentService,
+  provisioner,
+  logger,
+}: StartupPolicyReconcileDeps): Promise<void> {
+  if (!provisioner.canProvision) return;
+
+  try {
+    const targets = managedReconcileTargets(await agentService.list());
+    const result = await provisioner.reconcile(targets, { policyOnly: true });
+    logger.log(
+      `[startup-policy-reconcile] agents=${targets.length} updated=${result.updated.length} recreated=${result.recreated.length} orphans=${result.orphans.length} failed=${result.failed.length} noOwner=${result.noOwner.length}`,
+    );
+    for (const { agentId, error } of result.failed) {
+      logger.error(
+        `[startup-policy-reconcile] agent ${agentId} failed: ${error}`,
+      );
+    }
+  } catch (err) {
+    logger.error("[startup-policy-reconcile] reconcile failed:", err);
+  }
+}