@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/agent-manifest.ts

@@ -0,0 +1,685 @@
+/**
+ * admin/src/agent-manifest.ts
+ *
+ * Pure builders for the Kubernetes manifests that provision a single Shipwright
+ * agent: a per-agent Deployment, its Opaque token Secret, and the RFC1123 name
+ * derivation that ties them together.
+ *
+ * These functions are PURE — no fs, no network, no clock. They only shape wire
+ * objects. The actual k8s API calls live in ./kubernetes-client.ts; this module
+ * returns the same `KubernetesDeployment` / `KubernetesSecret` wire types so the
+ * two stay structurally consistent.
+ */
+
+import { createHash } from "node:crypto";
+import type {
+  KubernetesDeployment,
+  KubernetesEnvVar,
+  KubernetesPvc,
+  KubernetesSecret,
+} from "./kubernetes-client.ts";
+import type { ServiceEnvSpec } from "./service-integration.ts";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Agent health/liveness port (matches the agent's `SHIPWRIGHT_HEALTH_PORT`). */
+export const AGENT_HEALTH_PORT = 3459;
+
+/** Where the agent's persistent home volume is mounted in the container. */
+export const AGENT_HOME_MOUNT_PATH = "/data/agent-home";
+
+/**
+ * Repo clones and git worktrees must live on the PVC. The plugin commands
+ * default to `$HOME/src` / `$HOME/worktrees`, which sit on the container's
+ * ephemeral overlay layer — a single worktree with node_modules can exceed
+ * the pod's ephemeral-storage limit and get the pod evicted.
+ */
+const AGENT_REPO_DIR = `${AGENT_HOME_MOUNT_PATH}/workspace/repos`;
+const AGENT_WORKTREE_DIR = `${AGENT_HOME_MOUNT_PATH}/workspace/worktrees`;
+
+/**
+ * Optional per-field overrides for the agent container's resources. Any field
+ * left unset falls back to the default in `resolveAgentContainerResources`.
+ */
+export interface AgentContainerResourceOverrides {
+  /** CPU request, e.g. "500m". */
+  cpuRequest?: string;
+  /**
+   * CPU limit, e.g. "2". Applied to tenant pods ONLY (agents with an
+   * accountId); platform agents never get a CPU limit.
+   */
+  cpuLimit?: string;
+  /** Memory request, e.g. "2Gi". */
+  memoryRequest?: string;
+  /** Memory limit, e.g. "8Gi". */
+  memoryLimit?: string;
+  /**
+   * ephemeral-storage, applied to BOTH request and limit (kept equal — see
+   * rationale below). e.g. "4Gi".
+   */
+  ephemeralStorage?: string;
+}
+
+/** Default CPU limit for tenant pods (agents with an accountId). */
+const DEFAULT_TENANT_CPU_LIMIT = "2";
+
+/**
+ * Resolve the agent container's resources.requests/limits, applying any
+ * caller-supplied overrides on top of today's defaults (500m cpu / 2Gi memory
+ * request / 8Gi memory limit / 4Gi ephemeral storage, no CPU limit). Called
+ * from `buildAgentDeploymentManifest` with `opts.resources` — omitted or
+ * partial overrides fall back field-by-field to the default below.
+ *
+ * Precedence (highest wins): specialty override > env override > default.
+ * `overrides` here is the ENV layer (populated in admin/src/main.ts's
+ * buildProvisioner from SHIPWRIGHT_K8S_AGENT_* vars). The per-type
+ * SpecialtyResourcesSchema in specialty-registry.ts is already parsed as
+ * part of SpecialtyManifestSchema.resources but is NOT consumed here or by
+ * any provisioner — it stays inert until a future task wires specialty-level
+ * resource resolution in ahead of this function's env layer.
+ *
+ * Defaults: requests mirror the GKE Autopilot defaults the agent ran with
+ * before these were explicit. The memory limit exists to contain a runaway
+ * Claude run to its own container (OOM-kill) rather than letting it grow
+ * until the kubelet evicts neighbouring pods under node memory pressure
+ * (observed: ~11.6Gi used against the 2Gi request). No CPU limit for
+ * platform agents — CPU contention throttles instead of evicting. Tenant pods
+ * (`tenant: true`) get `DEFAULT_TENANT_CPU_LIMIT` (or `overrides.cpuLimit`) so
+ * one account's agent cannot starve neighbours in the shared namespace; with
+ * no ResourceQuota, per-account bounds are maxAgents x these fixed limits.
+ *
+ * ephemeral-storage defaults to 4Gi, not the 1Gi Autopilot default: 1Gi left
+ * no room for a single build step's scratch space, and agents were evicted
+ * mid-run ("Pod ephemeral local storage usage exceeds the total limit of
+ * containers 1Gi"), losing the in-flight task. Tool caches are pinned to the
+ * PVC in the agent's runMiseStartup, so this budget only has to cover
+ * genuinely transient writes — e.g. a scan skill staging tool binaries in a
+ * mktemp dir. Requests and limits are kept equal because Autopilot bills the
+ * request either way.
+ */
+export function resolveAgentContainerResources(
+  overrides?: AgentContainerResourceOverrides,
+  tenant = false,
+): { requests: Record<string, string>; limits: Record<string, string> } {
+  const ephemeralStorage = overrides?.ephemeralStorage ?? "4Gi";
+  return {
+    requests: {
+      cpu: overrides?.cpuRequest ?? "500m",
+      memory: overrides?.memoryRequest ?? "2Gi",
+      "ephemeral-storage": ephemeralStorage,
+    },
+    limits: {
+      ...(tenant
+        ? { cpu: overrides?.cpuLimit ?? DEFAULT_TENANT_CPU_LIMIT }
+        : {}),
+      memory: overrides?.memoryLimit ?? "8Gi",
+      "ephemeral-storage": ephemeralStorage,
+    },
+  };
+}
+
+/** Non-root uid/gid the agent runs as (matches the agent image). */
+const AGENT_RUN_AS = 1000;
+
+/** RFC1123 label length cap. */
+const MAX_NAME_LEN = 63;
+
+/** Length of the appended disambiguation hash suffix. */
+const HASH_SUFFIX_LEN = 8;
+
+const NAME_LABEL = "app.kubernetes.io/name";
+const INSTANCE_LABEL = "app.kubernetes.io/instance";
+const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
+const AGENT_ID_LABEL = "shipwright.dev/agent-id";
+/** Marks pods belonging to a tenant account (set only when accountId is present). */
+export const TENANT_LABEL = "shipwright.dev/tenant";
+const AGENT_APP_NAME = "shipwright-agent";
+
+/** Volume name, mount dir, and ConfigMap key for the Claude Code managed policy. */
+export const CLAUDE_POLICY_VOLUME = "claude-policy";
+export const CLAUDE_POLICY_MOUNT_PATH = "/etc/claude-code";
+const CLAUDE_POLICY_FILE = "managed-settings.json";
+/** Pod-template annotation carrying the policy hash so a policy change rolls pods. */
+export const CLAUDE_POLICY_HASH_ANNOTATION =
+  "shipwright.dev/claude-policy-hash";
+/** 0444 — policy is read-only to the agent user. */
+const CLAUDE_POLICY_FILE_MODE = 292;
+
+/** Volume name and mount dir for the projected Anthropic identity token. */
+export const ANTHROPIC_TOKEN_VOLUME = "anthropic-token";
+export const ANTHROPIC_TOKEN_MOUNT_PATH = "/var/run/secrets/anthropic.com";
+const ANTHROPIC_TOKEN_FILE = "token";
+
+/**
+ * Every env var the federation wiring may inject, in manifest order. The
+ * reconcile patch walks this list so a var that is no longer desired (feature
+ * off, or workspace id unset) is deleted from live Deployments.
+ */
+export const ANTHROPIC_FEDERATION_ENV_NAMES = [
+  "ANTHROPIC_IDENTITY_TOKEN_FILE",
+  "ANTHROPIC_FEDERATION_RULE_ID",
+  "ANTHROPIC_ORGANIZATION_ID",
+  "ANTHROPIC_SERVICE_ACCOUNT_ID",
+  "ANTHROPIC_WORKSPACE_ID",
+] as const;
+
+// ─── Name sanitization ──────────────────────────────────────────────────────
+
+/**
+ * Derive an RFC1123-compliant, collision-resistant Kubernetes object name from
+ * an arbitrary agent id.
+ *
+ * RFC1123 labels must be lowercase alphanumerics or `-`, start/end alphanumeric,
+ * and be ≤63 chars.
+ *
+ * Collision strategy: sanitization is inherently lossy — `agent_1`, `agent.1`,
+ * and `Agent-1` all reduce to the same `agent-1` base, and long ids must be
+ * truncated. Whenever the cleaned base is NOT a byte-for-byte match of the
+ * original id (i.e. any lowercasing, char replacement, collapsing, trimming, or
+ * truncation happened), we append `-<8-hex>` where the hex is the leading bytes
+ * of `sha256(originalId)`. The hash is over the FULL original id, so two ids
+ * that share a cleaned prefix still get distinct suffixes. A lossless id (already
+ * valid RFC1123) is returned unchanged. The base is truncated as needed so that
+ * `base + "-" + suffix` still fits within 63 chars.
+ */
+export function sanitizeAgentName(id: string): string {
+  const base = cleanBase(id);
+
+  // Lossless: the id was already a valid RFC1123 label — return as-is.
+  if (base === id && base.length > 0 && base.length <= MAX_NAME_LEN) {
+    return base;
+  }
+
+  const suffix = createHash("sha256")
+    .update(id)
+    .digest("hex")
+    .slice(0, HASH_SUFFIX_LEN);
+
+  // Reserve room for "-" + suffix, then re-trim any dash exposed at the new end.
+  const room = MAX_NAME_LEN - (suffix.length + 1);
+  const truncated = trimDashes(base.slice(0, Math.max(0, room)));
+  const prefix = truncated.length > 0 ? `${truncated}-` : "";
+  return `${prefix}${suffix}`;
+}
+
+/** Lowercase, replace invalid runs with a single dash, trim dash padding. */
+function cleanBase(id: string): string {
+  const lowered = id.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return trimDashes(lowered);
+}
+
+function trimDashes(s: string): string {
+  return s.replace(/^-+/, "").replace(/-+$/, "");
+}
+
+// ─── PVC builder ────────────────────────────────────────────────────────────
+
+export interface AgentPvcOpts {
+  name: string;
+  namespace: string;
+  sizeGi: number;
+  storageClassName?: string;
+}
+
+export function buildAgentPvcManifest(opts: AgentPvcOpts): KubernetesPvc {
+  const manifest: KubernetesPvc = {
+    apiVersion: "v1",
+    kind: "PersistentVolumeClaim",
+    metadata: {
+      name: opts.name,
+      namespace: opts.namespace,
+    },
+    spec: {
+      accessModes: ["ReadWriteOnce"],
+      resources: { requests: { storage: `${opts.sizeGi}Gi` } },
+    },
+  };
+  if (opts.storageClassName !== undefined) {
+    manifest.spec.storageClassName = opts.storageClassName;
+  }
+  return manifest;
+}
+
+// ─── Deployment builder ─────────────────────────────────────────────────────
+
+export interface AgentDeploymentOpts {
+  /** Original agent id (used verbatim in env + label, sanitized for the name). */
+  agentId: string;
+  namespace: string;
+  /** Agent container image (without tag). */
+  image: string;
+  /** Image tag, joined as `image:tag`. */
+  imageTag: string;
+  /** In-cluster admin/API base URL the agent calls home to. */
+  apiUrl: string;
+  /** Name of the pre-provisioned PersistentVolumeClaim for the agent home. */
+  pvcName: string;
+  /** Name of the Secret holding the per-agent token. */
+  secretName: string;
+  /** Key within the Secret's data that holds the token. Defaults to "token". */
+  tokenSecretKey?: string;
+  /** Replica count. Defaults to 1. */
+  replicas?: number;
+  /**
+   * Owning account. When set the pod is a tenant pod: the tenant label is added
+   * to the Deployment and pod template, and a CPU limit is applied. Omit for
+   * platform agents (manifest unchanged).
+   */
+  accountId?: string | null;
+  /**
+   * Optional container resource overrides, merged field-by-field over the
+   * defaults in `resolveAgentContainerResources`. Omit (or leave individual
+   * fields unset) to keep today's values for those fields.
+   */
+  resources?: AgentContainerResourceOverrides;
+  /**
+   * Optional agent-voice (STT/TTS) configuration. When omitted, the provisioned
+   * agent pod gets only the 3 base env vars (voice disabled). When present, the
+   * relevant vars are appended after the base vars:
+   *   - whisperServiceUrl → WHISPER_SERVICE_URL (provider=whisper)
+   *   - groqApiKey        → GROQ_API_KEY        (provider=groq)
+   *   - elevenLabsApiKey  → ELEVENLABS_API_KEY  (TTS, either provider)
+   *   - voiceId           → ELEVENLABS_VOICE_ID (optional TTS voice override)
+   * Only the keys that are set are injected — this mirrors the agent's own
+   * env contract (agent/src/runtime/config.ts).
+   */
+  voice?: AgentVoiceEnv;
+  /**
+   * Optional service integrations (see service-integration.ts), in order. Each
+   * entry with a `url` injects its `tokenEnv` (secretKeyRef from the agent
+   * Secret, key `secretKey`) then its `urlEnv` (plain value). Placed after the
+   * base vars and before the built-in chat-service env vars.
+   */
+  serviceIntegrations?: ServiceEnvSpec[];
+  /**
+   * When set, inject SHIPWRIGHT_CHAT_SERVICE_TOKEN (via secretKeyRef from the
+   * agent Secret) and SHIPWRIGHT_CHAT_SERVICE_URL (as a plain value) into the
+   * agent Deployment. Placed after the service-integration env vars and before voice env vars.
+   */
+  chatServiceUrl?: string;
+  /**
+   * Key within the agent Secret under which the chat-service token is stored.
+   * Defaults to "chat-service-token".
+   */
+  chatServiceTokenSecretKey?: string;
+  /**
+   * When set, mount the named ConfigMap's `managed-settings.json` read-only at
+   * /etc/claude-code (Claude Code's managed-policy directory). `hash` is
+   * optional: when non-empty it is stamped on the pod template as an annotation
+   * so a policy change rolls the pods; when absent/empty no annotation is added.
+   * Omit entirely for an unchanged manifest.
+   */
+  claudePolicy?: { configMapName: string; hash?: string };
+  /**
+   * When set, the pod runs as `serviceAccountName` and carries a projected
+   * service-account token (volume `anthropic-token`, mounted read-only at
+   * /var/run/secrets/anthropic.com) plus the env the Anthropic client needs to
+   * exchange that token for a short-lived access token (workload identity
+   * federation). Omit for an unchanged manifest.
+   */
+  anthropicFederation?: AgentAnthropicFederation;
+}
+
+/**
+ * Anthropic Workload Identity Federation settings for provisioned agent pods.
+ * Parsed from the admin's SHIPWRIGHT_K8S_AGENT_* env in main.ts.
+ */
+export interface AgentAnthropicFederation {
+  /** Kubernetes ServiceAccount the pod runs as (the token's subject). */
+  serviceAccountName: string;
+  /** → ANTHROPIC_FEDERATION_RULE_ID */
+  ruleId: string;
+  /** → ANTHROPIC_ORGANIZATION_ID */
+  organizationId: string;
+  /** → ANTHROPIC_SERVICE_ACCOUNT_ID */
+  serviceAccountId: string;
+  /** → ANTHROPIC_WORKSPACE_ID (only injected when set). */
+  workspaceId?: string;
+  /** Audience of the projected token. */
+  audience: string;
+  /** Lifetime of the projected token; Kubernetes requires >= 600. */
+  expirationSeconds: number;
+}
+
+/**
+ * Build the federation env entries, in ANTHROPIC_FEDERATION_ENV_NAMES order.
+ * Returns an empty array when federation is disabled.
+ */
+function anthropicFederationEnvEntries(
+  fed: AgentAnthropicFederation | undefined,
+): { name: string; value: string }[] {
+  if (!fed) return [];
+  return [
+    {
+      name: "ANTHROPIC_IDENTITY_TOKEN_FILE",
+      value: `${ANTHROPIC_TOKEN_MOUNT_PATH}/${ANTHROPIC_TOKEN_FILE}`,
+    },
+    { name: "ANTHROPIC_FEDERATION_RULE_ID", value: fed.ruleId },
+    { name: "ANTHROPIC_ORGANIZATION_ID", value: fed.organizationId },
+    { name: "ANTHROPIC_SERVICE_ACCOUNT_ID", value: fed.serviceAccountId },
+    ...(fed.workspaceId
+      ? [{ name: "ANTHROPIC_WORKSPACE_ID", value: fed.workspaceId }]
+      : []),
+  ];
+}
+
+/**
+ * The subset of voice env an admin provisioner flows into a provisioned agent
+ * pod. The admin reads these from its OWN env (sourced from the chart's voice
+ * Secret + whisper Service URL); this builder only shapes the pod env from them.
+ */
+export interface AgentVoiceEnv {
+  /** http(s) URL of the self-hosted Whisper pod (provider=whisper). */
+  whisperServiceUrl?: string;
+  /** Groq API key (provider=groq). */
+  groqApiKey?: string;
+  /** ElevenLabs API key (TTS). */
+  elevenLabsApiKey?: string;
+  /** Optional ElevenLabs voice id override. */
+  voiceId?: string;
+}
+
+/**
+ * Build the ordered voice env entries from a partial voice config. Only set
+ * keys are emitted; an empty/undefined config yields no entries (voice
+ * disabled). Order is stable for deterministic manifests/tests.
+ */
+function voiceEnvEntries(
+  voice: AgentVoiceEnv | undefined,
+): { name: string; value: string }[] {
+  if (!voice) return [];
+  const entries: { name: string; value: string }[] = [];
+  if (voice.whisperServiceUrl) {
+    entries.push({
+      name: "WHISPER_SERVICE_URL",
+      value: voice.whisperServiceUrl,
+    });
+  }
+  if (voice.groqApiKey) {
+    entries.push({ name: "GROQ_API_KEY", value: voice.groqApiKey });
+  }
+  if (voice.elevenLabsApiKey) {
+    entries.push({ name: "ELEVENLABS_API_KEY", value: voice.elevenLabsApiKey });
+  }
+  if (voice.voiceId) {
+    entries.push({ name: "ELEVENLABS_VOICE_ID", value: voice.voiceId });
+  }
+  return entries;
+}
+
+/**
+ * Build env entries for the optional service integrations, in list order. Each
+ * configured integration (url set) yields two entries: its token env
+ * (secretKeyRef from the agent Secret) then its URL env (plain value).
+ * Unconfigured integrations yield nothing.
+ */
+function serviceIntegrationEnvEntries(
+  opts: AgentDeploymentOpts,
+): KubernetesEnvVar[] {
+  return (opts.serviceIntegrations ?? []).flatMap((svc) => {
+    if (!svc.url) return [];
+    return [
+      {
+        name: svc.tokenEnv,
+        valueFrom: {
+          secretKeyRef: { name: opts.secretName, key: svc.secretKey },
+        },
+      },
+      { name: svc.urlEnv, value: svc.url },
+    ];
+  });
+}
+
+/**
+ * Build chat-service env entries when chatServiceUrl is configured. Returns two
+ * entries: SHIPWRIGHT_CHAT_SERVICE_TOKEN (secretKeyRef from the agent Secret)
+ * and SHIPWRIGHT_CHAT_SERVICE_URL (plain value). Returns an empty array when
+ * chatServiceUrl is absent (chat-service wiring disabled).
+ */
+function chatServiceEnvEntries(opts: AgentDeploymentOpts): KubernetesEnvVar[] {
+  if (!opts.chatServiceUrl) return [];
+  const csKey = opts.chatServiceTokenSecretKey ?? "chat-service-token";
+  return [
+    {
+      name: "SHIPWRIGHT_CHAT_SERVICE_TOKEN",
+      valueFrom: {
+        secretKeyRef: { name: opts.secretName, key: csKey },
+      },
+    },
+    {
+      name: "SHIPWRIGHT_CHAT_SERVICE_URL",
+      value: opts.chatServiceUrl,
+    },
+  ];
+}
+
+export function buildAgentDeploymentManifest(
+  opts: AgentDeploymentOpts,
+): KubernetesDeployment {
+  const name = sanitizeAgentName(opts.agentId);
+  const tokenKey = opts.tokenSecretKey ?? "token";
+  const volumeName = "agent-home";
+
+  const labels: Record<string, string> = {
+    [NAME_LABEL]: AGENT_APP_NAME,
+    [INSTANCE_LABEL]: name,
+    [MANAGED_BY_LABEL]: "shipwright-admin",
+    [AGENT_ID_LABEL]: opts.agentId,
+  };
+
+  const tenant = Boolean(opts.accountId);
+  if (tenant) labels[TENANT_LABEL] = "true";
+
+  // Selectors are immutable post-create and must not include volatile values;
+  // the instance label is the stable per-agent identity.
+  const selectorLabels: Record<string, string> = {
+    [NAME_LABEL]: AGENT_APP_NAME,
+    [INSTANCE_LABEL]: name,
+  };
+
+  const policy = opts.claudePolicy;
+  const federation = opts.anthropicFederation;
+
+  return {
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: {
+      name,
+      namespace: opts.namespace,
+      labels,
+    },
+    spec: {
+      replicas: opts.replicas ?? 1,
+      // Recreate: Slack Socket Mode allows only one active connection per token.
+      // RollingUpdate would briefly create a second pod that fights for the socket.
+      strategy: { type: "Recreate" },
+      selector: { matchLabels: selectorLabels },
+      template: {
+        metadata: {
+          labels: tenant
+            ? { ...selectorLabels, [TENANT_LABEL]: "true" }
+            : selectorLabels,
+          ...(policy?.hash
+            ? { annotations: { [CLAUDE_POLICY_HASH_ANNOTATION]: policy.hash } }
+            : {}),
+        },
+        spec: {
+          // Federation: the projected token's subject is this ServiceAccount.
+          ...(federation
+            ? { serviceAccountName: federation.serviceAccountName }
+            : {}),
+          securityContext: {
+            fsGroup: AGENT_RUN_AS,
+            fsGroupChangePolicy: "OnRootMismatch",
+            runAsNonRoot: true,
+            runAsUser: AGENT_RUN_AS,
+          },
+          // 120s grace period mirrors the Helm-managed agent template and gives
+          // the agent time to finish an in-flight Claude response before SIGKILL.
+          terminationGracePeriodSeconds: 120,
+          volumes: [
+            {
+              name: volumeName,
+              persistentVolumeClaim: { claimName: opts.pvcName },
+            },
+            ...(policy
+              ? [
+                  {
+                    name: CLAUDE_POLICY_VOLUME,
+                    configMap: {
+                      name: policy.configMapName,
+                      items: [
+                        { key: CLAUDE_POLICY_FILE, path: CLAUDE_POLICY_FILE },
+                      ],
+                      defaultMode: CLAUDE_POLICY_FILE_MODE,
+                    },
+                  },
+                ]
+              : []),
+            ...(federation
+              ? [
+                  {
+                    name: ANTHROPIC_TOKEN_VOLUME,
+                    projected: {
+                      sources: [
+                        {
+                          serviceAccountToken: {
+                            audience: federation.audience,
+                            expirationSeconds: federation.expirationSeconds,
+                            path: ANTHROPIC_TOKEN_FILE,
+                          },
+                        },
+                      ],
+                    },
+                  },
+                ]
+              : []),
+          ],
+          containers: [
+            {
+              name: AGENT_APP_NAME,
+              image: `${opts.image}:${opts.imageTag}`,
+              ports: [{ containerPort: AGENT_HEALTH_PORT, protocol: "TCP" }],
+              resources: resolveAgentContainerResources(opts.resources, tenant),
+              env: [
+                { name: "SHIPWRIGHT_AGENT_ID", value: opts.agentId },
+                { name: "SHIPWRIGHT_API_URL", value: opts.apiUrl },
+                {
+                  name: "SHIPWRIGHT_AGENT_API_KEY",
+                  valueFrom: {
+                    secretKeyRef: { name: opts.secretName, key: tokenKey },
+                  },
+                },
+                // Tell the agent where its persistent home directory is mounted.
+                { name: "AGENT_HOME", value: AGENT_HOME_MOUNT_PATH },
+                // Route repo clones and worktrees to the PVC (see constants).
+                { name: "SHIPWRIGHT_REPO_DIR", value: AGENT_REPO_DIR },
+                { name: "SHIPWRIGHT_WORKTREE_DIR", value: AGENT_WORKTREE_DIR },
+                // Service-integration env (e.g. task-store, registered by the
+                // coding extension) — injected after the base vars for each
+                // configured integration; omitted entirely when none are.
+                ...serviceIntegrationEnvEntries(opts),
+                // Chat-service env — injected after integration vars when chat
+                // service is configured; omitted entirely when chatServiceUrl is absent.
+                ...chatServiceEnvEntries(opts),
+                // Voice (STT/TTS) env — appended only for the keys that are set
+                // (none when voice is disabled, preserving the 6 base vars).
+                ...voiceEnvEntries(opts.voice),
+                // Workload identity federation env — none when disabled.
+                ...anthropicFederationEnvEntries(federation),
+              ],
+              volumeMounts: [
+                { name: volumeName, mountPath: AGENT_HOME_MOUNT_PATH },
+                // Directory mount (not subPath) so ConfigMap updates propagate.
+                ...(policy
+                  ? [
+                      {
+                        name: CLAUDE_POLICY_VOLUME,
+                        mountPath: CLAUDE_POLICY_MOUNT_PATH,
+                        readOnly: true,
+                      },
+                    ]
+                  : []),
+                ...(federation
+                  ? [
+                      {
+                        name: ANTHROPIC_TOKEN_VOLUME,
+                        mountPath: ANTHROPIC_TOKEN_MOUNT_PATH,
+                        readOnly: true,
+                      },
+                    ]
+                  : []),
+              ],
+              // Gate liveness/readiness until the agent's health server binds.
+              // Startup runs `mise install` + plugin install, which can exceed a
+              // minute on a cold/contended node; without this, liveness would
+              // restart the container (~75s in) before startup ever finished.
+              // 18 × 10s = 180s grace, aligned with the entrypoint startup
+              // watchdog (DEFAULT_STARTUP_TIMEOUT_MS in agent/src/runtime/entrypoint.ts).
+              startupProbe: {
+                httpGet: { path: "/health", port: AGENT_HEALTH_PORT },
+                periodSeconds: 10,
+                failureThreshold: 18,
+              },
+              livenessProbe: {
+                httpGet: { path: "/health", port: AGENT_HEALTH_PORT },
+                initialDelaySeconds: 15,
+                periodSeconds: 30,
+                // Explicit, not the 1s k8s default — the health server shares
+                // its process with claude -p child spawns and check-helpers.ts's
+                // spawnSync("gh", ...) calls, which block the whole process for
+                // the duration of the gh CLI call (network round-trip to GitHub,
+                // not just local CPU work). 15s is a bridge until SIO-1.2 converts
+                // those to async spawn; no fixed timeout is truly safe against a
+                // slow gh response, so this isn't a permanent fix.
+                timeoutSeconds: 15,
+                failureThreshold: 3,
+              },
+              readinessProbe: {
+                httpGet: { path: "/health", port: AGENT_HEALTH_PORT },
+                initialDelaySeconds: 10,
+                periodSeconds: 10,
+                timeoutSeconds: 15,
+                failureThreshold: 3,
+              },
+              securityContext: {
+                runAsNonRoot: true,
+                runAsUser: AGENT_RUN_AS,
+                allowPrivilegeEscalation: false,
+              },
+            },
+          ],
+        },
+      },
+    },
+  };
+}
+
+// ─── Secret builder ─────────────────────────────────────────────────────────
+
+export interface AgentSecretOpts {
+  name: string;
+  namespace: string;
+  /** Plaintext per-agent token; base64-encoded into the Secret's `data`. */
+  token: string;
+  /** Key under which the token is stored. Defaults to "token". */
+  tokenKey?: string;
+}
+
+export function buildAgentSecretManifest(
+  opts: AgentSecretOpts,
+): KubernetesSecret {
+  const tokenKey = opts.tokenKey ?? "token";
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    type: "Opaque",
+    metadata: {
+      name: opts.name,
+      namespace: opts.namespace,
+    },
+    data: {
+      [tokenKey]: Buffer.from(opts.token).toString("base64"),
+    },
+  };
+}