@desplega.ai/agent-swarm 1.158.0 → 1.160.0

package/src/http/stats.ts

@@ -1,7 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
-  getAllAgents,
+  getAgentStatusCounts,
   getAllLogs,
   getAllServices,
   getConcurrentContext,
@@ -15,6 +15,7 @@ import { getDbRetentionStats } from "../be/db-retention";
 import { isSteeringEnabled } from "../be/steering";
 import type { AgentLog } from "../types";
 import { AgentLogSchema, ScheduledTaskSchema, ServiceSchema } from "../types";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
@@ -51,6 +52,7 @@ const DashboardStatsSchema = z.object({
   tasks: TaskCountsSchema,
   steeringEnabled: z.boolean(),
   multiRuntimeEnabled: z.boolean(),
+  devMode: z.boolean(),
 });
 
 /** Mirrors `DbRetentionTableStats` (src/be/db-retention.ts). */
@@ -247,16 +249,11 @@ export async function handleStats(
   }
 
   if (getStats.match(req.method, pathSegments)) {
-    const agents = await getAllAgents();
+    const agents = await getAgentStatusCounts();
     const taskStats = await getTaskStats();
 
     const stats = {
-      agents: {
-        total: agents.length,
-        idle: agents.filter((a) => a.status === "idle").length,
-        busy: agents.filter((a) => a.status === "busy").length,
-        offline: agents.filter((a) => a.status === "offline").length,
-      },
+      agents,
       tasks: {
         total: taskStats.total,
         unassigned: taskStats.unassigned,
@@ -271,6 +268,7 @@ export async function handleStats(
       // Authenticated home for the steering feature flag — deliberately NOT on
       // the unauthenticated /health endpoint (config must not leak).
       steeringEnabled: isSteeringEnabled(),
+      devMode: isEnvFlagEnabled("SWARM_DEV_MODE", false),
       // Same authenticated home, for the same reason. Read through the helper
       // the server itself branches on, and read PER REQUEST rather than
       // captured at module load, so the reported value tracks a `swarm_config`

package/src/http/status.ts

@@ -37,6 +37,7 @@ import { getEmbeddingProvider } from "../be/memory";
 import { getFileStorageProvider } from "../fs/registry";
 import { getSlackConfiguration } from "../slack/config";
 import { getSlackConnectionState } from "../slack/connection-state";
+import { isTelemetryEnabled } from "../telemetry";
 import { type AgentCredStatus, AutomationIntegrationIdSchema, ProviderNameSchema } from "../types";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -119,6 +120,16 @@ export const StatusActivitySchema = z.object({
 });
 export type StatusActivity = z.infer<typeof StatusActivitySchema>;
 
+/**
+ * Effective telemetry opt-out state (`ANONYMIZED_TELEMETRY`, on by default).
+ * The dashboard reads it to stop its own browser-side notification events when
+ * the operator opted out.
+ */
+export const StatusTelemetrySchema = z.object({
+  enabled: z.boolean(),
+});
+export type StatusTelemetry = z.infer<typeof StatusTelemetrySchema>;
+
 export const StatusAgentFsSchema = z.object({
   configured: z.boolean(),
   base_url: z.string().nullable(),
@@ -171,6 +182,8 @@ export const StatusResponseSchema = z.object({
   automations: z.array(AutomationStatusSchema),
   /** Phase 2: rolled-up health for the always-on header badge. */
   health: StatusHealthSchema,
+  /** Additive: absent on servers that predate it, so consumers treat missing as enabled. */
+  telemetry: StatusTelemetrySchema.optional(),
 });
 export type StatusResponse = z.infer<typeof StatusResponseSchema>;
 
@@ -692,6 +705,7 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
     },
     automations,
     health: computeHealth(setup),
+    telemetry: { enabled: isTelemetryEnabled() },
   };
 }
 
@@ -721,7 +735,7 @@ const getStatus = route({
   pattern: ["status"],
   summary: "Identity + setup readiness + live activity for the swarm dashboard",
   description:
-    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set.",
+    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set; telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
   tags: ["Status"],
   responses: {
     200: { description: "Status payload", schema: StatusResponseSchema },

package/src/http/tasks.ts

@@ -27,6 +27,7 @@ import {
   pauseTask,
   promoteDraftTask,
   resumeTask,
+  settleSupersededTaskDependents,
   supersedeTask,
   updateAgentStatusFromCapacity,
   updateTaskClaudeSessionId,
@@ -34,6 +35,7 @@ import {
   updateTaskTitle,
   updateTaskVcs,
 } from "../be/db";
+import { explicitModelErrorForAgent } from "../be/model-validation";
 import {
   getTaskSteeringFields,
   markSteeringUndeliverable,
@@ -102,6 +104,9 @@ const AgentTaskSummarySchema = AgentTaskSchema.pick({
   scheduleId: true,
   model: true,
   modelTier: true,
+  resolvedModel: true,
+  modelSource: true,
+  modelAlias: true,
   effort: true,
   provider: true,
   requestedByUserId: true,
@@ -264,8 +269,18 @@ const createTask = route({
       outputSchema: z.record(z.string(), z.unknown()).optional(),
       contextKey: z.string().optional(),
       requestedByUserId: z.string().optional(),
-      model: z.string().optional(),
+      model: z
+        .string()
+        .optional()
+        .describe(
+          "Concrete model override for this task, interpreted by the assignee's harness/provider. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected.",
+        ),
       modelTier: ModelTierSchema.optional(),
+      /**
+       * Accept a `model` the catalog does not list. Without it an unknown id is a 400; with it
+       * the id is stored as given (a fresh launch, a private deployment).
+       */
+      allowCustomModel: z.boolean().optional(),
       effort: ReasoningEffortSchema.optional(),
       /**
        * Create in `draft` status instead of the normal pending/unassigned/offered
@@ -287,7 +302,10 @@ const createTask = route({
     }),
   responses: {
     201: { description: "Task created", schema: AgentTaskSchema },
-    400: { description: "Validation error, or agentId/offeredTo targets an extension identity" },
+    400: {
+      description:
+        "Validation error, an unknown `model` (set `allowCustomModel` to store a custom id), or agentId/offeredTo targets an extension identity",
+    },
     422: {
       description: "Task creation blocked by an extension",
       schema: z.object({
@@ -358,6 +376,7 @@ const cancelTaskRoute = route({
   responses: {
     200: { description: "Task cancelled", schema: TaskActionResultSchema },
     400: { description: "Cannot cancel terminal task" },
+    403: { description: "Agent caller is neither a lead nor the task creator" },
     404: { description: "Task not found" },
   },
 });
@@ -524,6 +543,7 @@ const updateTaskProgressRoute = route({
   body: z.object({ progress: z.string().min(1) }),
   responses: {
     200: { description: "Progress updated", schema: z.object({ success: z.literal(true) }) },
+    403: { description: "Task is assigned to another agent" },
     404: { description: "Task not found" },
   },
 });
@@ -734,6 +754,24 @@ async function canActOnOwnTask(
   return can({ principal, verb: "task.action.own", resource, source: "http" }).allow;
 }
 
+/**
+ * Principal for task writes (progress, cancel). Workers share the swarm API
+ * key, so on an operator bearer the X-Agent-ID header is the caller's
+ * identity, as in POST /api/tasks/{id}/finish. A keyed call without it (the
+ * runner wrapper, the dashboard) stays the operator.
+ */
+async function resolveTaskWritePrincipal(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+): Promise<RbacPrincipal> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind === "user") return { kind: "user", userId: auth.userId };
+  const agentId = auth?.kind === "agent" ? auth.agentId : myAgentId;
+  if (!agentId) return { kind: "operator" };
+  const agent = await getAgentById(agentId);
+  return { kind: "agent", agentId, isLead: agent?.isLead === true };
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleTasks(
@@ -860,6 +898,17 @@ export async function handleTasks(
       if (lead) defaultAgentId = lead.id;
     }
 
+    const modelError = await explicitModelErrorForAgent({
+      model: splitLegacyModelAlias({ model: parsed.body.model, modelTier: parsed.body.modelTier })
+        .model,
+      allowCustomModel: parsed.body.allowCustomModel,
+      agentId: defaultAgentId,
+    });
+    if (modelError) {
+      jsonError(res, modelError, 400);
+      return true;
+    }
+
     const parentTask = parsed.body.parentTaskId
       ? await getTaskById(parsed.body.parentTaskId)
       : null;
@@ -916,7 +965,7 @@ export async function handleTasks(
           }),
           effort: parsed.body.effort,
         },
-        { origin: "rest" },
+        { origin: "rest", allowCustomModel: parsed.body.allowCustomModel },
       );
 
       ensure({
@@ -1011,6 +1060,22 @@ export async function handleTasks(
       return true;
     }
 
+    // Humans may cancel any task. Agents get the MCP cancel-task policy:
+    // lead or task creator.
+    const principal = await resolveTaskWritePrincipal(req, myAgentId);
+    if (
+      principal.kind === "agent" &&
+      !can({
+        principal,
+        verb: "task.cancel.any",
+        resource: { kind: "task", taskId: task.id, creatorAgentId: task.creatorAgentId },
+        source: "http",
+      }).allow
+    ) {
+      jsonError(res, "Only the lead or task creator can cancel tasks.", 403);
+      return true;
+    }
+
     if (isTerminalTaskStatus(task.status)) {
       jsonError(res, `Cannot cancel task with status '${task.status}'`, 400);
       return true;
@@ -1345,14 +1410,31 @@ export async function handleTasks(
   if (updateTaskProgressRoute.match(req.method, pathSegments)) {
     const parsed = await updateTaskProgressRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const task = await getTaskById(parsed.params.id);
+    const principal = await resolveTaskWritePrincipal(req, myAgentId);
+
+    // Check and write in one transaction so a reassignment cannot slip between.
+    const status = await getDbClient().transaction(async (): Promise<200 | 403 | 404> => {
+      const task = await getTaskById(parsed.params.id);
+      if (!task) return 404;
+      const decision = can({
+        principal,
+        verb: "task.progress.write",
+        resource: { kind: "task", taskId: task.id, agentId: task.agentId },
+        source: "http",
+      });
+      if (!decision.allow) return 403;
+      await updateTaskProgress(parsed.params.id, parsed.body.progress);
+      return 200;
+    });
 
-    if (!task) {
+    if (status === 404) {
       jsonError(res, "Task not found", 404);
       return true;
     }
-
-    await updateTaskProgress(parsed.params.id, parsed.body.progress);
+    if (status === 403) {
+      jsonError(res, "Task is assigned to another agent", 403);
+      return true;
+    }
     updateTaskProgressRoute.respond(res, 200, { success: true });
     return true;
   }
@@ -1750,6 +1832,7 @@ export async function handleTasks(
     // `skipped` covers parent_not_found / lead_not_found edge cases — the
     // supersede already landed, so log + roll forward without a resume task.
     if (followUp.kind !== "created") {
+      await settleSupersededTaskDependents(parsed.params.id, null);
       console.warn(
         `[Supersede] Task ${parsed.params.id.slice(0, 8)} superseded but resume creation skipped (${
           followUp.kind === "skipped" ? followUp.reason : followUp.kind

package/src/http/usage-cache.ts

@@ -3,30 +3,71 @@
  * `/api/attribution/by-person`). Each open usage page polls them, and every
  * reply aggregates the whole window.
  *
- * A key holds the request filters plus a data version (see
- * `getUsageDataVersion`), so a new session or task misses the cache at once.
- * Changes to existing rows (a task re-attributed to another requester) show
- * after at most `USAGE_CACHE_TTL_MS`. A credential plan or name change
- * clears the cache.
+ * A key holds only the request filters. An entry is fresh for
+ * `USAGE_CACHE_TTL_MS` (the time bucket). Past that it is served as-is while one
+ * background load revalidates it, until its total age reaches
+ * `USAGE_CACHE_MAX_STALE_MS`; an older or missing entry blocks on a load.
+ * Concurrent misses for one key share that load.
+ *
+ * The key deliberately carries no data version. The old one changed on every
+ * new task or session, and the swarm creates one every few seconds, so it
+ * almost never hit. The cost is staleness: the first request past the bucket
+ * still gets the old value and only starts the refresh, so a new session shows
+ * up on the request after that. A client polling once per bucket sees it about
+ * one poll later. A credential plan or name change clears the cache.
  */
 
 export const USAGE_CACHE_TTL_MS = 30_000;
+export const USAGE_CACHE_MAX_STALE_MS = 120_000;
 const MAX_ENTRIES = 100;
 
-const entries = new Map<string, { expiresAt: number; value: unknown }>();
+const entries = new Map<string, { fetchedAt: number; value: unknown }>();
+const loading = new Map<string, Promise<unknown>>();
+// Bumped by `clearUsageCache`, so a load that started before the clear cannot
+// write its (now outdated) result back.
+let generation = 0;
+
+function load<T>(key: string, loader: () => Promise<T>): Promise<T> {
+  const running = loading.get(key);
+  if (running) return running as Promise<T>;
+
+  const startedIn = generation;
+  const promise: Promise<T> = Promise.resolve()
+    .then(loader)
+    .then((value) => {
+      if (startedIn === generation) {
+        entries.delete(key);
+        // Map order is insertion order, so the first key is the oldest entry.
+        if (entries.size >= MAX_ENTRIES) entries.delete(entries.keys().next().value as string);
+        entries.set(key, { fetchedAt: Date.now(), value });
+      }
+      return value;
+    })
+    .finally(() => {
+      if (loading.get(key) === promise) loading.delete(key);
+    });
+  loading.set(key, promise);
+  return promise;
+}
 
-export async function cachedUsageReport<T>(key: string, load: () => Promise<T>): Promise<T> {
-  const now = Date.now();
+export async function cachedUsageReport<T>(key: string, loader: () => Promise<T>): Promise<T> {
   const hit = entries.get(key);
-  if (hit && hit.expiresAt > now) return hit.value as T;
-  const value = await load();
-  entries.delete(key);
-  // Map order is insertion order, so the first key is the oldest entry.
-  if (entries.size >= MAX_ENTRIES) entries.delete(entries.keys().next().value as string);
-  entries.set(key, { expiresAt: now + USAGE_CACHE_TTL_MS, value });
-  return value;
+  if (hit) {
+    const age = Date.now() - hit.fetchedAt;
+    if (age < USAGE_CACHE_TTL_MS) return hit.value as T;
+    if (age < USAGE_CACHE_MAX_STALE_MS) {
+      // Keep serving the stale value; a failed refresh retries on the next request.
+      load(key, loader).catch((error) => {
+        console.error(`[usage-cache] background refresh failed for ${key.split(":")[0]}:`, error);
+      });
+      return hit.value as T;
+    }
+  }
+  return load(key, loader);
 }
 
 export function clearUsageCache(): void {
+  generation++;
   entries.clear();
+  loading.clear();
 }

package/src/http/workflows.ts

@@ -21,6 +21,7 @@ import {
   CooldownConfigSchema,
   InputValueSchema,
   TriggerConfigSchema,
+  type WorkflowDefinition,
   WorkflowDefinitionSchema,
   WorkflowEdgeSchema,
   WorkflowNodePatchSchema,
@@ -36,7 +37,9 @@ import { getExecutorRegistry, startWorkflowExecution } from "../workflows";
 import { definitionNodeIds, generateEdges, validateDefinition } from "../workflows/definition";
 import { TriggerSchemaError } from "../workflows/engine";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
+import { workflowModelErrors } from "../workflows/model-validation";
 import { patchWorkflowDefinition } from "../workflows/patch-definition";
+import { workflowSaveWarnings } from "../workflows/readiness";
 import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
 import { handleWebhookTrigger, WebhookError } from "../workflows/triggers";
 import { snapshotAndUpdateWorkflow } from "../workflows/version";
@@ -49,6 +52,14 @@ import { jsonError, parseBody, triggerSchemaErrorResponse } from "./utils";
 /** `Workflow` decorated with the caller-scoped favorite flag (always set once `withFavoriteFlags` runs). */
 const WorkflowWithFavoriteSchema = WorkflowSchema.extend({ favorite: z.boolean() });
 
+/**
+ * `Workflow` returned by a save (create / update / patch). `warnings` is present only when the
+ * save succeeded but a node cannot run yet, e.g. a system-one-decision node whose provider key is not configured.
+ */
+const WorkflowSaveResponseSchema = WorkflowSchema.extend({
+  warnings: z.array(z.string()).optional(),
+});
+
 /** `/api/workflows` slim list item — mirrors `WorkflowSummary` in src/types.ts (no exported schema there). */
 const WorkflowSummarySchema = WorkflowSchema.omit({
   definition: true,
@@ -85,6 +96,14 @@ const WorkflowRunPageSchema = z.object({
 
 const SuccessResponseSchema = z.object({ success: z.literal(true) });
 
+/** Adds `warnings` to a just-saved workflow when a node in it cannot run yet. */
+async function withSaveWarnings<T extends { definition: WorkflowDefinition }>(
+  workflow: T,
+): Promise<T & { warnings?: string[] }> {
+  const warnings = await workflowSaveWarnings(workflow.definition, getExecutorRegistry());
+  return warnings.length > 0 ? { ...workflow, warnings } : workflow;
+}
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const listWorkflowsRoute = route({
@@ -137,7 +156,7 @@ const createWorkflowRoute = route({
     vcsRepo: z.string().min(1).optional(),
   }),
   responses: {
-    201: { description: "Workflow created", schema: WorkflowSchema },
+    201: { description: "Workflow created", schema: WorkflowSaveResponseSchema },
     400: { description: "Invalid definition" },
   },
 });
@@ -188,7 +207,10 @@ const updateWorkflowRoute = route({
     enabled: z.boolean().optional(),
   }),
   responses: {
-    200: { description: "Workflow updated (version snapshot created)", schema: WorkflowSchema },
+    200: {
+      description: "Workflow updated (version snapshot created)",
+      schema: WorkflowSaveResponseSchema,
+    },
     400: { description: "Invalid definition" },
     404: { description: "Workflow not found" },
   },
@@ -203,7 +225,10 @@ const patchWorkflowRoute = route({
   params: z.object({ id: z.string() }),
   body: WorkflowPatchSchema.extend({ key: AssetKeySchema.optional() }),
   responses: {
-    200: { description: "Workflow patched (version snapshot created)", schema: WorkflowSchema },
+    200: {
+      description: "Workflow patched (version snapshot created)",
+      schema: WorkflowSaveResponseSchema,
+    },
     400: { description: "Invalid patch or resulting definition" },
     404: { description: "Workflow not found" },
   },
@@ -218,7 +243,10 @@ const patchWorkflowNodeRoute = route({
   params: z.object({ id: z.string(), nodeId: z.string() }),
   body: WorkflowNodePatchSchema,
   responses: {
-    200: { description: "Node patched (version snapshot created)", schema: WorkflowSchema },
+    200: {
+      description: "Node patched (version snapshot created)",
+      schema: WorkflowSaveResponseSchema,
+    },
     400: { description: "Invalid patch or resulting definition" },
     404: { description: "Workflow or node not found" },
   },
@@ -548,6 +576,11 @@ export async function handleWorkflows(
       jsonError(res, `Invalid definition: ${validation.errors.join("; ")}`, 400);
       return true;
     }
+    const modelErrors = await workflowModelErrors(parsed.body.definition);
+    if (modelErrors.length > 0) {
+      jsonError(res, `Invalid definition: ${modelErrors.join("; ")}`, 400);
+      return true;
+    }
 
     const trustedUserId = await resolveHttpAuditUserId(req, myAgentId);
     let key: string | undefined;
@@ -583,7 +616,7 @@ export async function handleWorkflows(
       },
       "api",
     );
-    createWorkflowRoute.respond(res, 201, workflow);
+    createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
     return true;
   }
 
@@ -638,7 +671,7 @@ export async function handleWorkflows(
       );
       return true;
     }
-    patchWorkflowNodeRoute.respond(res, 200, result.workflow);
+    patchWorkflowNodeRoute.respond(res, 200, await withSaveWarnings(result.workflow));
     return true;
   }
 
@@ -695,7 +728,7 @@ export async function handleWorkflows(
       );
       return true;
     }
-    patchWorkflowRoute.respond(res, 200, result.workflow);
+    patchWorkflowRoute.respond(res, 200, await withSaveWarnings(result.workflow));
     return true;
   }
 
@@ -722,6 +755,11 @@ export async function handleWorkflows(
         jsonError(res, `Invalid definition: ${validation.errors.join("; ")}`, 400);
         return true;
       }
+      const modelErrors = await workflowModelErrors(body.definition);
+      if (modelErrors.length > 0) {
+        jsonError(res, `Invalid definition: ${modelErrors.join("; ")}`, 400);
+        return true;
+      }
     }
 
     const updatedBy2 = (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined;
@@ -766,7 +804,7 @@ export async function handleWorkflows(
       res.end();
       return true;
     }
-    updateWorkflowRoute.respond(res, 200, workflow);
+    updateWorkflowRoute.respond(res, 200, await withSaveWarnings(workflow));
     return true;
   }
 

package/src/mcp-client/http-client.ts

@@ -10,10 +10,15 @@ export interface McpTool {
   name: string;
   description?: string;
   inputSchema: Record<string, unknown>;
+  /** JSON Schema of `structuredContent`, when the server declares one. */
+  outputSchema?: Record<string, unknown>;
+  /** Server metadata, e.g. `anthropic/alwaysLoad` from task tool manifests. */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpToolCallResult {
   content: Array<{ type: string; text?: string }>;
+  structuredContent?: Record<string, unknown>;
   isError?: boolean;
 }
 

package/src/memory/recall-query.ts

@@ -0,0 +1,74 @@
+import { stripSiblingBlock } from "../tasks/sibling-block";
+
+const COMPLETED_INSTRUCTIONS =
+  "\n\nIMPORTANT: Do NOT re-delegate or re-answer the original request. The worker has already handled it. Your job is ONLY to:\n1. Review the output above\n2. Do not relay the worker's raw output to Slack; the engine owns the thread tree and outcome card\n3. Complete this follow-up task\n\nUse";
+const FAILED_INSTRUCTIONS = "\n\nDecide whether to reassign, retry, or handle the failure. Use";
+const DETAILS_PREFIX = ' `get-task-details` with taskId "';
+const DETAILS_SUFFIX = '" for full details.';
+
+/** Shape only pre-task search text; never alter the task or persisted memory. */
+export function buildRecallQuery(description: string): string {
+  // Bound every parsing operation, while leaving room for wrapper boilerplate.
+  let query = stripSiblingBlock(truncateUtf8(description, 65536));
+  // Only the fixed header uses a regex; content is parsed with linear searches.
+  const header = query.match(
+    /^Worker task (completed|failed) — (?:review|action) needed\.\n\nAgent: [^\n]*\nOriginal task created by agent [^\n]*\nTask: "/,
+  );
+  if (header) {
+    const taskStart = header[0].length;
+    const outputMarker = header[1] === "completed" ? '"\n\nOutput:\n' : '"\n\nFailure reason: ';
+    const taskEnd = query.indexOf(outputMarker, taskStart);
+    const outputStart = taskEnd + outputMarker.length;
+    const instructions = header[1] === "completed" ? COMPLETED_INSTRUCTIONS : FAILED_INSTRUCTIONS;
+    const outputEnd = query.indexOf(instructions + DETAILS_PREFIX, outputStart);
+    const idStart = outputEnd + instructions.length + DETAILS_PREFIX.length;
+    const idEnd = query.indexOf('"', idStart);
+    if (
+      taskEnd !== -1 &&
+      outputEnd !== -1 &&
+      idEnd !== -1 &&
+      !query.slice(idStart, idEnd).includes("\n") &&
+      query.startsWith(DETAILS_SUFFIX, idEnd)
+    ) {
+      const creatorInstructions = query.indexOf(
+        "\nAdditional instructions from the task creator:\n",
+        outputStart,
+      );
+      const contentEnd =
+        creatorInstructions !== -1 && creatorInstructions < outputEnd
+          ? creatorInstructions
+          : outputEnd;
+      const threadContext: string[] = [];
+      let cursor = idEnd + DETAILS_SUFFIX.length;
+      while (cursor < query.length) {
+        const start = query.indexOf("<thread_context>", cursor);
+        if (start === -1) break;
+        const end = query.indexOf("</thread_context>", start);
+        if (end === -1) break;
+        cursor = end + "</thread_context>".length;
+        threadContext.push(query.slice(start, cursor));
+      }
+      query = [
+        query.slice(taskStart, taskEnd),
+        query.slice(outputStart, contentEnd),
+        ...threadContext,
+      ].join("\n\n");
+    }
+  }
+  query = query.trim();
+  return truncateUtf8(query, 8191);
+}
+
+function truncateUtf8(query: string, maxBytes: number): string {
+  // OpenAI embeddings accept 8192 tokens. A UTF-8 byte budget of 8191 is
+  // conservative for the byte-level tokenizer, even for multilingual text.
+  // Iterate code points so truncation cannot split a surrogate pair.
+  let bytes = 0;
+  let end = 0;
+  for (const character of query) {
+    bytes += Buffer.byteLength(character, "utf8");
+    if (bytes > maxBytes) break;
+    end += character.length;
+  }
+  return query.slice(0, end);
+}