@desplega.ai/agent-swarm 1.161.0 → 1.162.0

package/src/commands/runner.ts

@@ -35,6 +35,7 @@ import {
 } from "../providers/index.ts";
 import type { SteerDeliveryResult } from "../providers/types.ts";
 import { initTelemetry, telemetry } from "../telemetry.ts";
+import { mapTriggerSurface } from "../telemetry-context.ts";
 import {
   isTerminalTaskStatus,
   type ModelTierOverrides,
@@ -45,6 +46,7 @@ import {
   resolveTaskModelSelection,
   type SteeringMessage,
 } from "../types.ts";
+import { isApiDrainingResponse } from "../utils/api-drain.ts";
 import { getApiKey } from "../utils/api-key.ts";
 import { computeBudgetBackoffMs } from "../utils/budget-backoff.ts";
 import { isCodexAuthFailureReason } from "../utils/codex-auth-failure.ts";
@@ -716,8 +718,12 @@ export function scheduleSteeringDispatch(
   return true;
 }
 
-/** Ping the server to indicate activity and update status */
-async function pingServer(config: ApiConfig, _role: string): Promise<void> {
+/**
+ * Ping the server to indicate activity and update status. Resolves to whether
+ * the API is draining, or undefined when it did not answer (down, or a 5xx
+ * from a proxy), so a gap in service never reads as "stopped draining".
+ */
+export async function pingServer(config: ApiConfig, _role: string): Promise<boolean | undefined> {
   const headers: Record<string, string> = {
     "X-Agent-ID": config.agentId,
   };
@@ -729,12 +735,15 @@ async function pingServer(config: ApiConfig, _role: string): Promise<void> {
   }
 
   try {
-    await fetch(`${config.apiUrl}/ping`, {
+    const response = await fetch(`${config.apiUrl}/ping`, {
       method: "POST",
       headers,
     });
+    if (response.status >= 500) return undefined;
+    return isApiDrainingResponse(response);
   } catch {
     // Silently fail - server might not be running
+    return undefined;
   }
 }
 
@@ -1577,7 +1586,7 @@ async function validateProviderOutputIfNeeded(
   config: ApiConfig,
   taskId: string,
   providerOutput: string,
-): Promise<{ ok: true } | { ok: false; failReason: string }> {
+): Promise<{ ok: true; output?: string } | { ok: false; failReason: string }> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
   };
@@ -1598,29 +1607,65 @@ async function validateProviderOutputIfNeeded(
       return { ok: true };
     }
 
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(providerOutput);
-    } catch {
-      return {
-        ok: false,
-        failReason:
-          "Structured output required by outputSchema but provider output was not valid JSON",
-      };
+    // The first candidate is the raw text, so a final message that is already
+    // bare JSON keeps its exact bytes. Later candidates recover JSON that the
+    // model wrapped in a ```json fence or a line of prose.
+    let firstValidationErrors: string[] | undefined;
+    for (const [index, candidate] of jsonOutputCandidates(providerOutput).entries()) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(candidate);
+      } catch {
+        continue;
+      }
+      const validationErrors = validateJsonSchema(taskData.outputSchema, parsed);
+      if (validationErrors.length === 0) {
+        return index === 0 ? { ok: true } : { ok: true, output: candidate };
+      }
+      firstValidationErrors ??= validationErrors;
     }
 
-    const validationErrors = validateJsonSchema(taskData.outputSchema, parsed);
-    if (validationErrors.length > 0) {
+    if (firstValidationErrors) {
       return {
         ok: false,
-        failReason: `Structured output did not match outputSchema: ${validationErrors.join("; ")}`,
+        failReason: `Structured output did not match outputSchema: ${firstValidationErrors.join("; ")}`,
       };
     }
+    return {
+      ok: false,
+      failReason:
+        "Structured output required by outputSchema but provider output was not valid JSON",
+    };
   } catch {
     return { ok: true };
   }
+}
 
-  return { ok: true };
+/**
+ * Texts that may hold the JSON in an agent's final message, in the order to
+ * try them: the whole message, each fenced code block from last to first, then
+ * the span from the first `{` (or `[`) to the last `}` (or `]`). Agents often
+ * answer a schema-bound task with "Here is the result:" plus a ```json block
+ * instead of calling store-progress, and `JSON.parse` on the whole message
+ * fails on that. Fences run last to first because an earlier fence is often an
+ * example or a draft that also matches the schema, and the answer comes last.
+ */
+function jsonOutputCandidates(text: string): string[] {
+  const candidates = [text];
+  const fenced: string[] = [];
+  for (const match of text.matchAll(/```[a-zA-Z]*[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*```/g)) {
+    if (match[1]?.trim()) fenced.push(match[1].trim());
+  }
+  candidates.push(...fenced.reverse());
+  for (const [open, close] of [
+    ["{", "}"],
+    ["[", "]"],
+  ] as const) {
+    const start = text.indexOf(open);
+    const end = text.lastIndexOf(close);
+    if (start >= 0 && end > start) candidates.push(text.slice(start, end + 1));
+  }
+  return [...new Set(candidates)];
 }
 
 export async function ensureTaskFinished(
@@ -1658,7 +1703,7 @@ export async function ensureTaskFinished(
   // the no-providerOutput path and the providerOutput-failed-schema-validation
   // path below, so a schema'd task ending in free-form prose falls through to
   // the same extraction fallback instead of hard-failing.
-  const applyFallback = (fallback: FallbackResult) => {
+  const applyFallback = (fallback: FallbackResult, rejectedOutputReason?: string) => {
     console.log(`[${role}] Task ${taskId.slice(0, 8)} fallback result: ${fallback.kind}`);
     switch (fallback.kind) {
       case "extracted":
@@ -1677,7 +1722,11 @@ export async function ensureTaskFinished(
       case "schema-fail":
         status = "failed";
         body.status = "failed";
-        body.failureReason = fallback.failReason;
+        // Keep why the provider's final message was rejected; the fallback's
+        // own reason alone ("not provided via store-progress") hides it.
+        body.failureReason = rejectedOutputReason
+          ? `${fallback.failReason}. Final message rejected: ${rejectedOutputReason}`
+          : fallback.failReason;
         break;
       case "fetch-error":
         body.output = `Process completed (could not verify task state: ${fallback.error})`;
@@ -1693,7 +1742,7 @@ export async function ensureTaskFinished(
   } else if (providerOutput) {
     const validation = await validateProviderOutputIfNeeded(config, taskId, providerOutput);
     if (validation.ok) {
-      body.output = providerOutput;
+      body.output = validation.output ?? providerOutput;
     } else {
       // The task declared an outputSchema but the provider's final message
       // is free-form prose that doesn't satisfy it. Don't convert this into
@@ -1707,7 +1756,7 @@ export async function ensureTaskFinished(
         adapterType,
         providerOutput,
       );
-      applyFallback(fallback);
+      applyFallback(fallback, validation.failReason);
     }
   } else {
     // Try structured output fallback if the task has an outputSchema
@@ -2310,6 +2359,8 @@ function setupShutdownHandlers(
           `[${role}] Superseding ${state.activeTasks.size} remaining task(s) for resume after restart...`,
         );
         for (const [taskId, task] of state.activeTasks) {
+          // Already superseded (or terminal) server-side, e.g. by the API-drain handoff.
+          if (task.serverTerminalStatus) continue;
           console.log(`[${role}] Superseding task ${taskId.slice(0, 8)}`);
           task.session.abort("graceful_shutdown").catch(() => {});
           if (apiConfig) {
@@ -2348,6 +2399,9 @@ function setupShutdownHandlers(
     if (apiConfig) {
       telemetry.session("ended", {
         agentId: apiConfig.agentId,
+        // A runner session spans many tasks, so it belongs to none.
+        taskId: null,
+        trigger_surface: null,
         durationMs: state ? Date.now() - state.startedAt : undefined,
         tasksProcessed: state?.tasksProcessed ?? 0,
       });
@@ -2412,6 +2466,10 @@ export interface RunningTask {
   promise: Promise<ProviderResult>;
   /** The trigger type that caused this task to be spawned */
   triggerType?: string;
+  /** Surface that started the task's whole chain (root task source); tags session telemetry */
+  triggerSurface?: string | null;
+  /** `users.id` of the requester; hashed into `user_ref` on session telemetry */
+  requestedByUserId?: string;
   /** Set when the promise resolves, enabling non-blocking completion checks */
   result: ProviderResult | null;
   /** Deferred cursor updates for channel_activity triggers — committed after success */
@@ -2459,10 +2517,14 @@ export interface RunningTask {
   abortRequestedAt?: number;
   /**
    * Terminal status the server already holds for this task, found by
-   * `reconcileActiveTasks`. Completion then only frees the slot and leaves
-   * the server's output and failureReason alone.
+   * `reconcileActiveTasks` or set by an API-drain handoff. Completion then only
+   * frees the slot and leaves the server's output and failureReason alone.
    */
   serverTerminalStatus?: string;
+  /** API-drain handoff calls made for this task (see `handOffTasksForApiDrain`). */
+  drainHandoffAttempts?: number;
+  /** The API answered the drain handoff for this task, so it is not retried. */
+  drainHandoffSettled?: boolean;
 }
 
 /** Runner state for tracking concurrent tasks */
@@ -2494,6 +2556,12 @@ export interface RunnerState {
    * value is the reset time in ms. Read by `selectCredential` (T5).
    */
   modelWindowBlocks: Map<string, number>;
+  /**
+   * The API is draining (it sent `X-Swarm-Draining`): in-flight tasks are handed
+   * off and no new work is taken until a response arrives without the header.
+   * Unset against an API that never drains.
+   */
+  apiDraining?: boolean;
 }
 
 /** Buffer for session logs */
@@ -2937,6 +3005,15 @@ async function triggerHeartbeatSweep(config: ApiConfig): Promise<boolean> {
   }
 }
 
+/**
+ * `trigger_surface` for a worker event: the server-resolved root surface of the
+ * task, or null when the server did not send one (an older server, or a
+ * session with no task).
+ */
+function workerTriggerSurface(raw: string | null | undefined) {
+  return raw ? mapTriggerSurface(raw) : null;
+}
+
 /** Trigger types returned by the poll API */
 interface Trigger {
   type:
@@ -2947,6 +3024,8 @@ interface Trigger {
     | "channel_activity"
     | "budget_refused";
   taskId?: string;
+  /** Surface that started the task's whole chain (server-resolved); tags session telemetry. */
+  triggerSurface?: string;
   task?: unknown;
   mentionsCount?: number;
   count?: number;
@@ -2992,7 +3071,7 @@ interface Trigger {
 }
 
 /** Options for polling */
-interface PollOptions {
+export interface PollOptions {
   apiUrl: string;
   apiKey: string;
   agentId: string;
@@ -3003,6 +3082,8 @@ interface PollOptions {
   since?: string; // Optional: for filtering finished tasks
   /** Live harness provider; keys the MODEL_TIER_* overrides sent with the poll. */
   harnessProvider?: ProviderName;
+  /** Told, on every answered poll, whether the API is draining. */
+  onApiDrainSignal?: (draining: boolean) => void;
 }
 
 /**
@@ -3197,8 +3278,8 @@ export async function registerAgent(opts: {
   return {};
 }
 
-/** Poll for triggers via HTTP API */
-async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
+/** Poll for triggers via HTTP API. Exported for tests. */
+export async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
   if (!isPollTracingEnabled()) {
     return pollForTriggerOnce(opts);
   }
@@ -3262,10 +3343,15 @@ async function pollForTriggerOnce(opts: PollOptions): Promise<Trigger | null> {
         continue;
       }
 
+      const draining = isApiDrainingResponse(response);
+      opts.onApiDrainSignal?.(draining);
+
       const data = (await response.json()) as { trigger: Trigger | null };
       if (data.trigger) {
         return data.trigger;
       }
+      // A draining API dispatches nothing: end the window so the loop can hand off.
+      if (draining) return null;
     } catch (error) {
       console.warn(`[runner] Poll request error: ${error}`);
     }
@@ -3722,6 +3808,10 @@ async function spawnProviderProcess(
     runnerSessionId: string;
     iteration: number;
     taskId?: string;
+    /** Surface that started the task chain, for session telemetry. */
+    triggerSurface?: string | null;
+    /** `users.id` of the requester; hashed into `user_ref` on session telemetry. */
+    requestedByUserId?: string;
     model?: string;
     modelTier?: string;
     /** Server claim-time resolution (task.resolvedModel); wins over the local one. */
@@ -4496,21 +4586,28 @@ async function spawnProviderProcess(
             "gen_ai.usage.output_tokens": result.cost.outputTokens ?? 0,
             "agentswarm.cost.total_usd": result.cost.totalCostUsd ?? 0,
           });
-          telemetry.session("cost", {
-            agentId: opts.agentId,
-            model: result.cost.model,
-            provider: result.cost.provider ?? opts.harnessProvider,
-            inputTokens: result.cost.inputTokens ?? 0,
-            outputTokens: result.cost.outputTokens ?? 0,
-            cacheReadTokens: result.cost.cacheReadTokens,
-            cacheWriteTokens: result.cost.cacheWriteTokens,
-            reasoningOutputTokens: result.cost.reasoningOutputTokens,
-            thinkingTokens: result.cost.thinkingTokens,
-            totalCostUsd: result.cost.totalCostUsd,
-            durationMs: result.cost.durationMs,
-            numTurns: result.cost.numTurns,
-            isError: result.cost.isError,
-          });
+          telemetry.session(
+            "cost",
+            {
+              agentId: opts.agentId,
+              // Lets cost be split by the surface that started the work.
+              taskId: realTaskId ?? null,
+              trigger_surface: workerTriggerSurface(opts.triggerSurface),
+              model: result.cost.model,
+              provider: result.cost.provider ?? opts.harnessProvider,
+              inputTokens: result.cost.inputTokens ?? 0,
+              outputTokens: result.cost.outputTokens ?? 0,
+              cacheReadTokens: result.cost.cacheReadTokens,
+              cacheWriteTokens: result.cost.cacheWriteTokens,
+              reasoningOutputTokens: result.cost.reasoningOutputTokens,
+              thinkingTokens: result.cost.thinkingTokens,
+              totalCostUsd: result.cost.totalCostUsd,
+              durationMs: result.cost.durationMs,
+              numTurns: result.cost.numTurns,
+              isError: result.cost.isError,
+            },
+            { userId: opts.requestedByUserId ?? null },
+          );
           try {
             await saveCostData(
               { ...result.cost, taskId: realTaskId, sessionId: opts.runnerSessionId },
@@ -4635,6 +4732,8 @@ async function spawnProviderProcess(
     startTime: new Date(),
     promise,
     result: null,
+    triggerSurface: opts.triggerSurface,
+    requestedByUserId: opts.requestedByUserId,
     credentialInfo,
     // Snapshot the provider + local-env trait of the adapter this session is
     // spawned on, so the session-end sync decision survives a live provider
@@ -4697,6 +4796,69 @@ function requestSessionAbort(task: RunningTask, reason: string, at: number): voi
     .catch(() => {});
 }
 
+/** Handoff calls per task while the API drains; a call the API answered is never repeated. */
+export const API_DRAIN_HANDOFF_MAX_ATTEMPTS = 3;
+
+/**
+ * Fold the API's drain signal (the `X-Swarm-Draining` header on a ping or poll
+ * answer) into `state`. `undefined` means the API did not answer: keep the last
+ * known state. Exported for tests.
+ */
+export function applyApiDrainSignal(
+  state: RunnerState,
+  role: string,
+  draining: boolean | undefined,
+): void {
+  if (draining === undefined) return;
+  if (draining && !state.apiDraining) {
+    console.log(`[${role}] API is draining: handing off in-flight tasks, taking no new work`);
+  } else if (!draining && state.apiDraining) {
+    console.log(`[${role}] API stopped draining: resuming normal polling`);
+  }
+  state.apiDraining = draining;
+}
+
+/**
+ * The API is draining, so it still serves but will stop soon: supersede each
+ * in-flight task now, while the call can land, instead of in the SIGTERM
+ * handler, which compose runs after the API is gone. Same API call and reason
+ * as the SIGTERM handoff, so the resume follow-up is identical.
+ *
+ * A task the API superseded is marked server-terminal and its session aborted;
+ * completion then frees the slot without a finish call. A failed call leaves
+ * the task running, up to `API_DRAIN_HANDOFF_MAX_ATTEMPTS`, and the SIGTERM
+ * handler stays the fallback. Exported for tests.
+ */
+export async function handOffTasksForApiDrain(
+  state: RunnerState,
+  role: string,
+  apiConfig: ApiConfig,
+): Promise<void> {
+  for (const [taskId, task] of state.activeTasks) {
+    // A settled session reports its own result through `checkCompletedProcesses`.
+    if (task.result !== null || task.drainHandoffSettled) continue;
+    const attempts = task.drainHandoffAttempts ?? 0;
+    if (attempts >= API_DRAIN_HANDOFF_MAX_ATTEMPTS) continue;
+    task.drainHandoffAttempts = attempts + 1;
+
+    const outcome = await supersedeTaskViaAPI(apiConfig, role, taskId, "graceful_shutdown");
+    if (!outcome.ok) {
+      console.warn(
+        `[${role}] Drain handoff for task ${taskId.slice(0, 8)} failed (attempt ${attempts + 1}/${API_DRAIN_HANDOFF_MAX_ATTEMPTS}); the task keeps running`,
+      );
+      continue;
+    }
+    task.drainHandoffSettled = true;
+    if (outcome.kind === "resumed" || outcome.kind === "workflow-failed") {
+      task.serverTerminalStatus = outcome.kind === "resumed" ? "superseded" : "failed";
+      console.log(`[${role}] Handed off task ${taskId.slice(0, 8)} ahead of the API stopping`);
+      requestSessionAbort(task, "graceful_shutdown", Date.now());
+    }
+    // "alreadyFinished": the task ended on its own. "rejected": the API refused
+    // the supersede on purpose. Either way the session follows its normal path.
+  }
+}
+
 /**
  * Keep `state.activeTasks` in line with the server, so a session whose promise
  * never settles cannot hold an execution slot forever:
@@ -4794,6 +4956,8 @@ export async function checkCompletedProcesses(
     taskId: string;
     result: ProviderResult;
     triggerType?: string;
+    triggerSurface?: string | null;
+    requestedByUserId?: string;
     cursorUpdates?: Array<{ channelId: string; ts: string }>;
     workingDir?: string;
     credentialInfo?: RunningTask["credentialInfo"];
@@ -4817,6 +4981,8 @@ export async function checkCompletedProcesses(
         taskId,
         result: task.result,
         triggerType: task.triggerType,
+        triggerSurface: task.triggerSurface,
+        requestedByUserId: task.requestedByUserId,
         cursorUpdates: task.cursorUpdates,
         workingDir: task.workingDir,
         credentialInfo: task.credentialInfo,
@@ -4836,6 +5002,8 @@ export async function checkCompletedProcesses(
   for (const {
     taskId,
     result,
+    triggerSurface,
+    requestedByUserId,
     cursorUpdates,
     workingDir,
     credentialInfo,
@@ -4951,31 +5119,44 @@ export async function checkCompletedProcesses(
           ),
       );
 
-      telemetry.taskEvent("session_completed", {
-        taskId,
-        agentId: apiConfig.agentId,
-        provider: result.cost?.provider ?? harnessProvider,
-        model: result.cost?.model ?? model,
-        harnessVariant,
-        harnessVersion:
-          typeof harnessVariantMeta?.version === "string" ||
-          typeof harnessVariantMeta?.version === "number"
-            ? String(harnessVariantMeta.version)
-            : undefined,
-        exitCode: result.exitCode,
-        isError: result.exitCode !== 0,
-        durationMs,
-      });
-      const sessionTelemetryEvent = resolveSessionTelemetryEvent(result);
-      if (sessionTelemetryEvent) {
-        telemetry.session(sessionTelemetryEvent, {
+      const sessionTriggerSurface = workerTriggerSurface(triggerSurface);
+      const sessionActor = { userId: requestedByUserId ?? null };
+      telemetry.taskEvent(
+        "session_completed",
+        {
+          taskId,
+          trigger_surface: sessionTriggerSurface,
           agentId: apiConfig.agentId,
-          errorCategory: normalizeSessionErrorCategory(result.errorCategory),
           provider: result.cost?.provider ?? harnessProvider,
-          model: result.cost?.model ?? model,
-          durationMs: result.cost?.durationMs ?? durationMs,
-          wasRateLimited: result.rateLimitResetAt != null,
-        });
+          model: result.cost?.model ?? model ?? "unknown",
+          harnessVariant,
+          harnessVersion:
+            typeof harnessVariantMeta?.version === "string" ||
+            typeof harnessVariantMeta?.version === "number"
+              ? String(harnessVariantMeta.version)
+              : undefined,
+          exitCode: result.exitCode,
+          isError: result.exitCode !== 0,
+          durationMs,
+        },
+        sessionActor,
+      );
+      const sessionTelemetryEvent = resolveSessionTelemetryEvent(result);
+      if (sessionTelemetryEvent) {
+        telemetry.session(
+          sessionTelemetryEvent,
+          {
+            agentId: apiConfig.agentId,
+            taskId,
+            trigger_surface: sessionTriggerSurface,
+            errorCategory: normalizeSessionErrorCategory(result.errorCategory),
+            provider: result.cost?.provider ?? harnessProvider,
+            model: result.cost?.model ?? model ?? "unknown",
+            durationMs: result.cost?.durationMs ?? durationMs,
+            wasRateLimited: result.rateLimitResetAt != null,
+          },
+          sessionActor,
+        );
       }
       state.tasksProcessed += 1;
 
@@ -5245,6 +5426,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   }
   telemetry.session("started", {
     agentId,
+    // The boot session is not tied to a task.
+    taskId: null,
+    trigger_surface: null,
     harnessProvider: bootProvider,
     model: bootModel || undefined,
     role,
@@ -6307,8 +6491,13 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   const taskReconcileIntervalMs = resolveTaskReconcileIntervalMs();
 
   while (true) {
-    // Ping server on each iteration to keep status updated
-    await pingServer(apiConfig, role);
+    // Ping server on each iteration to keep status updated. The answer also
+    // carries the API's drain signal, which reaches workers at capacity that
+    // do not poll.
+    applyApiDrainSignal(state, role, await pingServer(apiConfig, role));
+    if (state.apiDraining) {
+      await handOffTasksForApiDrain(state, role, apiConfig);
+    }
 
     // Check for completed processes first and ensure tasks are marked as finished
     await checkCompletedProcesses(state, role, apiConfig, cancelledSignaled);
@@ -6412,8 +6601,10 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       }
     }
 
-    // Only poll if we have capacity
-    if (state.activeTasks.size < state.maxConcurrent) {
+    // Only poll if we have capacity and the API is not draining
+    if (state.apiDraining) {
+      await Bun.sleep(1000);
+    } else if (state.activeTasks.size < state.maxConcurrent) {
       if (Date.now() - lastOrphanRecoveryAt > ORPHAN_RECOVERY_INTERVAL_MS) {
         lastOrphanRecoveryAt = Date.now();
         const recoveredOrphans = await recoverOrphanedInProgressTasks(apiConfig);
@@ -6439,6 +6630,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         runtimeInstanceId,
         pollTimeout: effectiveTimeout,
         harnessProvider: state.harnessProvider,
+        onApiDrainSignal: (draining) => applyApiDrainSignal(state, role, draining),
       });
 
       if (trigger) {
@@ -6792,6 +6984,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               runnerSessionId: taskRunnerSessionId,
               iteration,
               taskId: trigger.taskId,
+              triggerSurface: trigger.triggerSurface,
+              requestedByUserId: trigger.requestedBy?.id,
               model: taskModel,
               modelTier: taskModelTier,
               resolvedModel: (trigger.task as { resolvedModel?: string } | undefined)

package/src/commands/templates.ts

@@ -72,6 +72,16 @@ Audit event: {{event_id}}. {{recovery_guidance}}
   category: "task_lifecycle",
 });
 
+// Sent at most once per session by the pi adapter when the model's final turn
+// carries no text and no tool call (see PiMonoSession.repromptAfterEmptyFinalTurn).
+registerTemplate({
+  eventType: "task.nudge.empty_final_turn",
+  header: "",
+  defaultBody: `Your last turn returned no text and no tool call. Finish now: if the task needs a result, call store-progress with it.`,
+  variables: [],
+  category: "task_lifecycle",
+});
+
 registerTemplate({
   eventType: "task.trigger.unread_mentions",
   header: "",