@desplega.ai/agent-swarm 1.49.0 → 1.52.0

package/src/gitlab/handlers.ts

@@ -9,8 +9,11 @@
  */
 
 import { createTaskExtended, failTask, findTaskByVcs, getAllAgents } from "../be/db";
+import { resolveTemplate } from "../prompts/resolver";
 import { GITLAB_BOT_NAME } from "./auth";
 import { addGitLabNoteReaction, addGitLabReaction } from "./reactions";
+// Side-effect import: registers all GitLab event templates in the in-memory registry
+import "./templates";
 import type { IssueEvent, MergeRequestEvent, NoteEvent, PipelineEvent } from "./types";
 
 // ── Dedup cache (same pattern as GitHub) ──
@@ -30,9 +33,6 @@ function isDuplicate(key: string): boolean {
 
 // ── Helpers ──
 
-const DELEGATION_INSTRUCTION =
-  "\n\n**Delegation instruction:** As the lead agent, analyze this and decide whether to handle it yourself or delegate to a worker agent. Use `send-task` to delegate with clear instructions.";
-
 function detectMention(text: string | null | undefined): boolean {
   if (!text) return false;
   return new RegExp(`@${GITLAB_BOT_NAME}\\b`, "i").test(text);
@@ -51,17 +51,6 @@ function findLeadAgent() {
   );
 }
 
-function getCommandSuggestions(type: string): string {
-  switch (type) {
-    case "mr":
-      return "Suggested commands: `/review-pr` to review the MR, `/implement-issue` to implement changes.";
-    case "issue":
-      return "Suggested commands: `/implement-issue` to implement, `/close-issue` to close.";
-    default:
-      return "";
-  }
-}
-
 // ── Event Handlers ──
 
 export async function handleMergeRequest(
@@ -91,9 +80,23 @@ export async function handleMergeRequest(
       }
 
       const context = mr.description ? extractMentionContext(mr.description) : "";
-      const taskDesc = `[GitLab MR #${mr.iid}] ${mr.title}\n\nRepo: ${repo}\nAuthor: @${user.username}\nBranch: ${mr.source_branch} → ${mr.target_branch}\nURL: ${mr.url}\n\n${context ? `Context: ${context}\n\n` : ""}${getCommandSuggestions("mr")}${DELEGATION_INSTRUCTION}`;
+      const contextSection = context ? `Context: ${context}\n\n` : "";
+      const result = resolveTemplate("gitlab.merge_request.opened", {
+        mr_iid: mr.iid,
+        mr_title: mr.title,
+        repo,
+        username: user.username,
+        source_branch: mr.source_branch,
+        target_branch: mr.target_branch,
+        mr_url: mr.url,
+        context_section: contextSection,
+      });
 
-      const task = createTaskExtended(taskDesc, {
+      if (result.skipped) {
+        return { created: false };
+      }
+
+      const task = createTaskExtended(result.text, {
         agentId: lead?.id ?? null,
         source: "gitlab",
         vcsProvider: "gitlab",
@@ -172,9 +175,21 @@ export async function handleIssue(
       }
 
       const context = issue.description ? extractMentionContext(issue.description) : "";
-      const taskDesc = `[GitLab Issue #${issue.iid}] ${issue.title}\n\nRepo: ${repo}\nAuthor: @${user.username}\nURL: ${issue.url}\n\n${context ? `Context: ${context}\n\n` : ""}${getCommandSuggestions("issue")}${DELEGATION_INSTRUCTION}`;
+      const contextSection = context ? `Context: ${context}\n\n` : "";
+      const result = resolveTemplate("gitlab.issue.assigned", {
+        issue_iid: issue.iid,
+        issue_title: issue.title,
+        repo,
+        username: user.username,
+        issue_url: issue.url,
+        context_section: contextSection,
+      });
 
-      const task = createTaskExtended(taskDesc, {
+      if (result.skipped) {
+        return { created: false };
+      }
+
+      const task = createTaskExtended(result.text, {
         agentId: lead?.id ?? null,
         source: "gitlab",
         vcsProvider: "gitlab",
@@ -250,9 +265,24 @@ export async function handleNote(event: NoteEvent): Promise<{ created: boolean;
   // Check if there's already an active task for this entity
   const existingTask = targetNumber ? findTaskByVcs(repo, targetNumber) : null;
 
-  const taskDesc = `[GitLab Comment on ${entityLabel}] @${user.username} mentioned bot\n\nRepo: ${repo}\nURL: ${targetUrl}\n\nComment:\n${context}${existingTask ? `\n\n_Note: There's an active task (${existingTask.id}) for this ${entityLabel}._` : ""}${DELEGATION_INSTRUCTION}`;
+  const existingTaskNote = existingTask
+    ? `\n\n_Note: There's an active task (${existingTask.id}) for this ${entityLabel}._`
+    : "";
+
+  const noteResult = resolveTemplate("gitlab.comment.mentioned", {
+    entity_label: entityLabel,
+    username: user.username,
+    repo,
+    target_url: targetUrl,
+    context,
+    existing_task_note: existingTaskNote,
+  });
+
+  if (noteResult.skipped) {
+    return { created: false };
+  }
 
-  const task = createTaskExtended(taskDesc, {
+  const task = createTaskExtended(noteResult.text, {
     agentId: lead?.id ?? null,
     source: "gitlab",
     vcsProvider: "gitlab",
@@ -308,9 +338,20 @@ export async function handlePipeline(
   }
 
   const lead = findLeadAgent();
-  const taskDesc = `[GitLab CI Failed] Pipeline #${pipeline.id} failed for MR #${mrIid}\n\nRepo: ${repo}\nMR: ${event.merge_request.title}\nURL: ${event.merge_request.url}\nBranch: ${event.merge_request.source_branch}\n\nThe CI pipeline has failed. Please investigate and fix the issues.${DELEGATION_INSTRUCTION}`;
+  const pipelineResult = resolveTemplate("gitlab.pipeline.failed", {
+    pipeline_id: pipeline.id,
+    mr_iid: mrIid,
+    repo,
+    mr_title: event.merge_request.title,
+    mr_url: event.merge_request.url,
+    source_branch: event.merge_request.source_branch,
+  });
+
+  if (pipelineResult.skipped) {
+    return { created: false };
+  }
 
-  const task = createTaskExtended(taskDesc, {
+  const task = createTaskExtended(pipelineResult.text, {
     agentId: lead?.id ?? null,
     source: "gitlab",
     vcsProvider: "gitlab",

package/src/gitlab/templates.ts

@@ -0,0 +1,140 @@
+/**
+ * GitLab event prompt template definitions.
+ *
+ * Each template is registered at module load time via registerTemplate().
+ * Handlers import this module for the side-effect of registration.
+ *
+ * Template text uses {{variable}} syntax. The resolver interpolates variables
+ * and expands {{@template[id]}} references before returning the final text.
+ */
+
+import { registerTemplate } from "../prompts/registry";
+
+// ============================================================================
+// Common building blocks (GitLab-specific)
+// ============================================================================
+
+registerTemplate({
+  eventType: "common.delegation_instruction.gitlab",
+  header: "",
+  defaultBody:
+    "\n\n**Delegation instruction:** As the lead agent, analyze this and decide whether to handle it yourself or delegate to a worker agent. Use `send-task` to delegate with clear instructions.",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.gitlab_mr",
+  header: "",
+  defaultBody:
+    "Suggested commands: `/review-pr` to review the MR, `/implement-issue` to implement changes.",
+  variables: [],
+  category: "common",
+});
+
+registerTemplate({
+  eventType: "common.command_suggestions.gitlab_issue",
+  header: "",
+  defaultBody: "Suggested commands: `/implement-issue` to implement, `/close-issue` to close.",
+  variables: [],
+  category: "common",
+});
+
+// ============================================================================
+// Merge Request events
+// ============================================================================
+
+registerTemplate({
+  eventType: "gitlab.merge_request.opened",
+  header: "[GitLab MR #{{mr_iid}}] {{mr_title}}",
+  defaultBody: `Repo: {{repo}}
+Author: @{{username}}
+Branch: {{source_branch}} \u2192 {{target_branch}}
+URL: {{mr_url}}
+
+{{context_section}}{{@template[common.command_suggestions.gitlab_mr]}}{{@template[common.delegation_instruction.gitlab]}}`,
+  variables: [
+    { name: "mr_iid", description: "Merge request IID" },
+    { name: "mr_title", description: "Merge request title" },
+    { name: "repo", description: "Project path with namespace" },
+    { name: "username", description: "Event sender username" },
+    { name: "source_branch", description: "Source branch name" },
+    { name: "target_branch", description: "Target branch name" },
+    { name: "mr_url", description: "Merge request URL" },
+    { name: "context_section", description: "Context section with description or empty string" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Issue events
+// ============================================================================
+
+registerTemplate({
+  eventType: "gitlab.issue.assigned",
+  header: "[GitLab Issue #{{issue_iid}}] {{issue_title}}",
+  defaultBody: `Repo: {{repo}}
+Author: @{{username}}
+URL: {{issue_url}}
+
+{{context_section}}{{@template[common.command_suggestions.gitlab_issue]}}{{@template[common.delegation_instruction.gitlab]}}`,
+  variables: [
+    { name: "issue_iid", description: "Issue IID" },
+    { name: "issue_title", description: "Issue title" },
+    { name: "repo", description: "Project path with namespace" },
+    { name: "username", description: "Event sender username" },
+    { name: "issue_url", description: "Issue URL" },
+    { name: "context_section", description: "Context section with description or empty string" },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Comment (Note) events
+// ============================================================================
+
+registerTemplate({
+  eventType: "gitlab.comment.mentioned",
+  header: "[GitLab Comment on {{entity_label}}] @{{username}} mentioned bot",
+  defaultBody: `Repo: {{repo}}
+URL: {{target_url}}
+
+Comment:
+{{context}}{{existing_task_note}}{{@template[common.delegation_instruction.gitlab]}}`,
+  variables: [
+    { name: "entity_label", description: "Entity label (e.g. 'MR #1' or 'Issue #2')" },
+    { name: "username", description: "Comment author username" },
+    { name: "repo", description: "Project path with namespace" },
+    { name: "target_url", description: "Target entity URL" },
+    { name: "context", description: "Extracted mention context from comment" },
+    {
+      name: "existing_task_note",
+      description: "Note about existing active task, or empty string",
+    },
+  ],
+  category: "event",
+});
+
+// ============================================================================
+// Pipeline events
+// ============================================================================
+
+registerTemplate({
+  eventType: "gitlab.pipeline.failed",
+  header: "[GitLab CI Failed] Pipeline #{{pipeline_id}} failed for MR #{{mr_iid}}",
+  defaultBody: `Repo: {{repo}}
+MR: {{mr_title}}
+URL: {{mr_url}}
+Branch: {{source_branch}}
+
+The CI pipeline has failed. Please investigate and fix the issues.{{@template[common.delegation_instruction.gitlab]}}`,
+  variables: [
+    { name: "pipeline_id", description: "Pipeline ID" },
+    { name: "mr_iid", description: "Merge request IID" },
+    { name: "repo", description: "Project path with namespace" },
+    { name: "mr_title", description: "Merge request title" },
+    { name: "mr_url", description: "Merge request URL" },
+    { name: "source_branch", description: "Source branch name" },
+  ],
+  category: "event",
+});

package/src/heartbeat/heartbeat.ts

@@ -15,9 +15,12 @@ import {
   releaseStaleReviewingTasks,
   updateAgentStatus,
 } from "../be/db";
+import { resolveTemplate } from "../prompts/resolver";
 import type { AgentTask } from "../types";
 import { getExecutorRegistry } from "../workflows";
 import { recoverIncompleteRuns } from "../workflows/recovery";
+// Side-effect import: registers heartbeat event templates in the in-memory registry
+import "./templates";
 
 // ============================================================================
 // Configuration (env var overrides)
@@ -256,29 +259,35 @@ function escalateToLead(findings: HeartbeatFindings): void {
     return;
   }
 
-  const sections: string[] = [
-    "Task Type: Triage\nGoal: Investigate heartbeat findings that need human reasoning\n",
-  ];
-
+  // Build stalled tasks section
+  let stalledTasksSection = "";
   if (findings.stalledTasks.length > 0) {
-    sections.push("## Stalled Tasks");
+    const lines: string[] = ["## Stalled Tasks"];
     for (const task of findings.stalledTasks) {
       const agentSlice = task.agentId?.slice(0, 8) ?? "unassigned";
-      sections.push(
+      lines.push(
         `- Task ${task.id.slice(0, 8)} (agent: ${agentSlice}): last updated ${task.lastUpdatedAt}`,
       );
     }
-    sections.push(
+    lines.push(
       "\nCheck if these tasks are genuinely stuck or just working without calling store-progress. " +
         "If stuck, consider cancelling and reassigning.",
     );
+    stalledTasksSection = lines.join("\n");
   }
 
-  sections.push(`\n${HEARTBEAT_ESCALATION_MARKER} ${escalationKey}`);
+  const escalationMarker = `\n${HEARTBEAT_ESCALATION_MARKER} ${escalationKey}`;
+
+  const result = resolveTemplate("heartbeat.escalation.stalled", {
+    stalled_tasks_section: stalledTasksSection,
+    escalation_marker: escalationMarker,
+  });
 
-  const taskDescription = sections.join("\n");
+  if (result.skipped) {
+    return;
+  }
 
-  createTaskExtended(taskDescription, {
+  createTaskExtended(result.text, {
     agentId: lead.id,
     taskType: "heartbeat",
     tags: ["heartbeat", "triage", "auto-generated"],

package/src/heartbeat/templates.ts

@@ -0,0 +1,30 @@
+/**
+ * Heartbeat event prompt template definitions.
+ *
+ * Each template is registered at module load time via registerTemplate().
+ * Handlers import this module for the side-effect of registration.
+ */
+
+import { registerTemplate } from "../prompts/registry";
+
+// ============================================================================
+// Escalation events
+// ============================================================================
+
+registerTemplate({
+  eventType: "heartbeat.escalation.stalled",
+  header: "",
+  defaultBody: `Task Type: Triage
+Goal: Investigate heartbeat findings that need human reasoning
+
+{{stalled_tasks_section}}
+{{escalation_marker}}`,
+  variables: [
+    {
+      name: "stalled_tasks_section",
+      description: "Markdown section listing stalled tasks with details",
+    },
+    { name: "escalation_marker", description: "Heartbeat escalation marker with key" },
+  ],
+  category: "event",
+});

package/src/http/active-sessions.ts

@@ -8,6 +8,7 @@ import {
   getActiveSessions,
   heartbeatActiveSession,
   insertActiveSession,
+  updateActiveSessionProviderSessionId,
 } from "../be/db";
 import { route } from "./route-def";
 import { json } from "./utils";
@@ -40,6 +41,7 @@ const createActiveSession = route({
     triggerType: z.string().min(1),
     inboxMessageId: z.string().optional(),
     taskDescription: z.string().optional(),
+    runnerSessionId: z.string().optional(),
   }),
   responses: {
     201: { description: "Session created" },
@@ -83,6 +85,19 @@ const heartbeatSession = route({
   },
 });
 
+const updateProviderSession = route({
+  method: "put",
+  path: "/api/active-sessions/provider-session/{taskId}",
+  pattern: ["api", "active-sessions", "provider-session", null],
+  summary: "Update provider session ID on an active session",
+  tags: ["Active Sessions"],
+  params: z.object({ taskId: z.string() }),
+  body: z.object({ providerSessionId: z.string().min(1) }),
+  responses: {
+    200: { description: "Provider session ID updated" },
+  },
+});
+
 const cleanupSessions = route({
   method: "post",
   path: "/api/active-sessions/cleanup",
@@ -126,6 +141,7 @@ export async function handleActiveSessions(
       triggerType: parsed.body.triggerType,
       inboxMessageId: parsed.body.inboxMessageId,
       taskDescription: parsed.body.taskDescription,
+      runnerSessionId: parsed.body.runnerSessionId,
     });
     json(res, { session }, 201);
     return true;
@@ -155,6 +171,17 @@ export async function handleActiveSessions(
     return true;
   }
 
+  if (updateProviderSession.match(req.method, pathSegments)) {
+    const parsed = await updateProviderSession.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const updated = updateActiveSessionProviderSessionId(
+      parsed.params.taskId,
+      parsed.body.providerSessionId,
+    );
+    json(res, { updated });
+    return true;
+  }
+
   if (cleanupSessions.match(req.method, pathSegments)) {
     const parsed = await cleanupSessions.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/http/approval-requests.ts

@@ -0,0 +1,247 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  createApprovalRequest,
+  getApprovalRequestById,
+  listApprovalRequests,
+  resolveApprovalRequest,
+} from "../be/db";
+import { workflowEventBus } from "../workflows/event-bus";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const QuestionSchema = z.object({
+  id: z.string(),
+  type: z.enum(["approval", "text", "single-select", "multi-select", "boolean"]),
+  label: z.string(),
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+  placeholder: z.string().optional(),
+  multiline: z.boolean().optional(),
+  options: z
+    .array(
+      z.object({
+        value: z.string(),
+        label: z.string(),
+        description: z.string().optional(),
+      }),
+    )
+    .optional(),
+  minSelections: z.number().int().min(0).optional(),
+  maxSelections: z.number().int().min(1).optional(),
+  defaultValue: z.boolean().optional(),
+});
+
+const createRoute = route({
+  method: "post",
+  path: "/api/approval-requests",
+  pattern: ["api", "approval-requests"],
+  summary: "Create a new approval request",
+  tags: ["ApprovalRequests"],
+  body: z.object({
+    title: z.string().min(1),
+    questions: z.array(QuestionSchema).min(1),
+    approvers: z.object({
+      users: z.array(z.string()).optional(),
+      roles: z.array(z.string()).optional(),
+      policy: z.union([
+        z.literal("any"),
+        z.literal("all"),
+        z.object({ min: z.number().int().min(1) }),
+      ]),
+    }),
+    workflowRunId: z.string().uuid().optional(),
+    workflowRunStepId: z.string().uuid().optional(),
+    sourceTaskId: z.string().uuid().optional(),
+    timeoutSeconds: z.number().int().min(1).optional(),
+    notifications: z
+      .array(
+        z.object({
+          channel: z.enum(["slack", "email"]),
+          target: z.string(),
+        }),
+      )
+      .optional(),
+  }),
+  responses: {
+    201: { description: "Approval request created" },
+    400: { description: "Validation error" },
+  },
+  auth: { apiKey: true },
+});
+
+const getByIdRoute = route({
+  method: "get",
+  path: "/api/approval-requests/{id}",
+  pattern: ["api", "approval-requests", null],
+  summary: "Get approval request details",
+  tags: ["ApprovalRequests"],
+  params: z.object({ id: z.string().uuid() }),
+  responses: {
+    200: { description: "Approval request details" },
+    404: { description: "Not found" },
+  },
+  auth: { apiKey: true },
+});
+
+const respondRoute = route({
+  method: "post",
+  path: "/api/approval-requests/{id}/respond",
+  pattern: ["api", "approval-requests", null, "respond"],
+  summary: "Submit a response to an approval request",
+  tags: ["ApprovalRequests"],
+  params: z.object({ id: z.string().uuid() }),
+  body: z.object({
+    responses: z.record(z.string(), z.unknown()),
+    respondedBy: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Response recorded" },
+    400: { description: "Validation error" },
+    404: { description: "Not found" },
+    409: { description: "Already resolved" },
+  },
+  auth: { apiKey: true },
+});
+
+const listRoute = route({
+  method: "get",
+  path: "/api/approval-requests",
+  pattern: ["api", "approval-requests"],
+  summary: "List approval requests with optional filters",
+  tags: ["ApprovalRequests"],
+  query: z.object({
+    status: z.string().optional(),
+    workflowRunId: z.string().optional(),
+    limit: z.coerce.number().optional(),
+  }),
+  responses: {
+    200: { description: "List of approval requests" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleApprovalRequests(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  // 4-segment: POST /api/approval-requests/{id}/respond
+  if (respondRoute.match(req.method, pathSegments)) {
+    const parsed = await respondRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const existing = getApprovalRequestById(parsed.params.id);
+    if (!existing) {
+      jsonError(res, "Approval request not found", 404);
+      return true;
+    }
+
+    if (existing.status !== "pending") {
+      jsonError(res, `Approval request already resolved with status: ${existing.status}`, 409);
+      return true;
+    }
+
+    // Determine status from responses: if any approval question has approved: false → rejected
+    const questions = existing.questions as Array<{ id: string; type: string }>;
+    let status: "approved" | "rejected" = "approved";
+    for (const q of questions) {
+      if (q.type === "approval") {
+        const answer = parsed.body.responses[q.id] as { approved?: boolean } | undefined;
+        if (answer && answer.approved === false) {
+          status = "rejected";
+          break;
+        }
+      }
+    }
+
+    const updated = resolveApprovalRequest(parsed.params.id, {
+      status,
+      responses: parsed.body.responses,
+      resolvedBy: parsed.body.respondedBy,
+    });
+
+    if (!updated) {
+      jsonError(
+        res,
+        "Failed to resolve approval request (may have been resolved concurrently)",
+        409,
+      );
+      return true;
+    }
+
+    // Emit event for workflow resume
+    if (updated.workflowRunId && updated.workflowRunStepId) {
+      workflowEventBus.emit("approval.resolved", {
+        requestId: updated.id,
+        status: updated.status,
+        responses: updated.responses,
+        workflowRunId: updated.workflowRunId,
+        workflowRunStepId: updated.workflowRunStepId,
+      });
+    }
+
+    json(res, { approvalRequest: updated });
+    return true;
+  }
+
+  // 3-segment with param: GET /api/approval-requests/{id}
+  if (getByIdRoute.match(req.method, pathSegments)) {
+    const parsed = await getByIdRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const request = getApprovalRequestById(parsed.params.id);
+    if (!request) {
+      jsonError(res, "Approval request not found", 404);
+      return true;
+    }
+
+    json(res, { approvalRequest: request });
+    return true;
+  }
+
+  // 2-segment: POST /api/approval-requests (create)
+  if (createRoute.match(req.method, pathSegments)) {
+    const parsed = await createRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const id = crypto.randomUUID();
+    const request = createApprovalRequest({
+      id,
+      title: parsed.body.title,
+      questions: parsed.body.questions,
+      approvers: parsed.body.approvers,
+      workflowRunId: parsed.body.workflowRunId,
+      workflowRunStepId: parsed.body.workflowRunStepId,
+      sourceTaskId: parsed.body.sourceTaskId,
+      timeoutSeconds: parsed.body.timeoutSeconds,
+      notificationChannels: parsed.body.notifications,
+    });
+
+    res.writeHead(201, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ approvalRequest: request }));
+    return true;
+  }
+
+  // 2-segment: GET /api/approval-requests (list)
+  if (listRoute.match(req.method, pathSegments)) {
+    const parsed = await listRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const requests = listApprovalRequests({
+      status: parsed.query.status || undefined,
+      workflowRunId: parsed.query.workflowRunId || undefined,
+      limit: parsed.query.limit || undefined,
+    });
+
+    json(res, { approvalRequests: requests });
+    return true;
+  }
+
+  return false;
+}

package/src/http/config.ts

@@ -69,12 +69,12 @@ const upsertConfig = route({
   tags: ["Config"],
   body: z.object({
     scope: z.enum(["global", "agent", "repo"]),
-    scopeId: z.string().optional(),
+    scopeId: z.string().nullish(),
     key: z.string().min(1),
     value: z.unknown(),
     isSecret: z.boolean().optional(),
-    envPath: z.string().optional(),
-    description: z.string().optional(),
+    envPath: z.string().nullish(),
+    description: z.string().nullish(),
   }),
   responses: {
     200: { description: "Config entry upserted" },