@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/be/memory/providers/openai-embedding.ts

@@ -2,7 +2,8 @@ import OpenAI from "openai";
 import { selectCredential } from "../../../utils/credentials";
 import { getOpenRouterAttributionHeaders } from "../../../utils/openrouter-base-url";
 import { DEFAULT_EMBEDDING_MODEL, EMBEDDING_DIMENSIONS } from "../constants";
-import type { EmbeddingProvider } from "../types";
+import { noteEmbeddingFailure, noteEmbeddingSuccess } from "../embedding-recovery";
+import type { EmbeddingInputKind, EmbeddingProvider, EmbedOptions } from "../types";
 
 // text-embedding-3-* reject any input over 8,192 tokens with a 400, and one
 // such input fails every input in its request. There is no tokenizer here, and
@@ -18,13 +19,19 @@ interface OpenAIEmbeddingConfig {
   apiKey?: string;
   model?: string;
   dimensions?: number;
+  queryPrefix?: string;
+  documentPrefix?: string;
 }
 
-function cleanInput(text: string): string {
-  return text
-    .replace(/[\n\r]/g, " ")
-    .trim()
-    .slice(0, MAX_EMBEDDING_INPUT_CHARS);
+/**
+ * Flatten and trim the input, then prepend the task prefix. The cleaned text
+ * is cut so that prefix plus text stays within MAX_EMBEDDING_INPUT_CHARS. An
+ * empty input stays empty, so it is skipped and never embeds a bare prefix.
+ */
+function cleanInput(text: string, prefix = ""): string {
+  const cleaned = text.replace(/[\n\r]/g, " ").trim();
+  if (!cleaned) return "";
+  return prefix + cleaned.slice(0, Math.max(0, MAX_EMBEDDING_INPUT_CHARS - prefix.length));
 }
 
 /** A 400 is about the request's inputs, so the other inputs can still embed. */
@@ -32,12 +39,36 @@ function isInputRejection(err: unknown): boolean {
   return err instanceof OpenAI.APIError && err.status === 400;
 }
 
+/**
+ * The server rejected the request for its size, not for an input: a 413, or a
+ * 422 about the batch size (TEI: "batch size 70 > maximum allowed batch size
+ * 32"). One request per input then fits. Any other 422 (TEI also answers 422
+ * for a bad `dimensions` value) stays a plain failure, so it is not repeated
+ * once per input.
+ */
+function isBatchTooLarge(err: unknown): boolean {
+  if (!(err instanceof OpenAI.APIError)) return false;
+  if (err.status === 413) return true;
+  return err.status === 422 && /batch size/i.test(err.message ?? "");
+}
+
 function isInputTooLong(err: unknown): boolean {
   return (
     isInputRejection(err) && /maximum (context|input) length/i.test((err as Error).message ?? "")
   );
 }
 
+/**
+ * The endpoint was down or overloaded (no HTTP response, a 5xx or a 429), so the
+ * same input can embed later. Only these start a backfill once calls work again:
+ * an input the endpoint rejects would fail again on every backfill.
+ */
+function isOutage(err: unknown): boolean {
+  if (!(err instanceof OpenAI.APIError)) return true;
+  const status = err.status;
+  return status === undefined || status === 429 || status >= 500;
+}
+
 export class OpenAIEmbeddingProvider implements EmbeddingProvider {
   readonly name: string;
   readonly dimensions: number;
@@ -45,6 +76,8 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
   private client: OpenAI | null = null;
   private readonly model: string;
   private readonly apiKey: string | undefined;
+  private readonly queryPrefix: string;
+  private readonly documentPrefix: string;
 
   constructor(config?: OpenAIEmbeddingConfig) {
     const apiKey = config?.apiKey ?? process.env.EMBEDDING_API_KEY ?? process.env.OPENAI_API_KEY;
@@ -59,6 +92,17 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
     this.name = config?.model
       ? `openai/${config.model}`
       : (process.env.EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL);
+
+    // Read once here: a config reload builds a new provider. Used verbatim,
+    // so a trailing space (nomic: "search_query: ") is kept.
+    this.queryPrefix = config?.queryPrefix ?? process.env.EMBEDDING_QUERY_PREFIX ?? "";
+    this.documentPrefix = config?.documentPrefix ?? process.env.EMBEDDING_DOCUMENT_PREFIX ?? "";
+  }
+
+  private prefixFor(kind: EmbeddingInputKind | undefined): string {
+    if (kind === "query") return this.queryPrefix;
+    if (kind === "document") return this.documentPrefix;
+    return "";
   }
 
   isConfigured(): boolean {
@@ -107,7 +151,9 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
     while (true) {
       try {
         const response = await this.request(client, input);
-        return this.toVector(response.data[0]?.embedding, "Embedding");
+        const vector = this.toVector(response.data[0]?.embedding, "Embedding");
+        if (vector) noteEmbeddingSuccess();
+        return vector;
       } catch (err) {
         const message = (err as Error).message;
         if (isInputTooLong(err) && input.length > MIN_EMBEDDING_INPUT_CHARS) {
@@ -119,26 +165,28 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
           continue;
         }
         console.error("[memory] Embedding failed:", message);
+        if (isOutage(err)) noteEmbeddingFailure();
         return null;
       }
     }
   }
 
-  async embed(text: string): Promise<Float32Array | null> {
+  async embed(text: string, opts?: EmbedOptions): Promise<Float32Array | null> {
     const client = this.getClient();
     if (!client) return null;
 
-    const cleaned = cleanInput(text);
+    const cleaned = cleanInput(text, this.prefixFor(opts?.kind));
     if (!cleaned) return null;
     return this.embedOne(client, cleaned);
   }
 
-  async embedBatch(texts: string[]): Promise<(Float32Array | null)[]> {
+  async embedBatch(texts: string[], opts?: EmbedOptions): Promise<(Float32Array | null)[]> {
     const results: (Float32Array | null)[] = texts.map(() => null);
     const client = this.getClient();
     if (!client) return results;
 
-    const cleaned = texts.map(cleanInput);
+    const prefix = this.prefixFor(opts?.kind);
+    const cleaned = texts.map((text) => cleanInput(text, prefix));
     const groups: number[][] = [];
     let group: number[] = [];
     let groupChars = 0;
@@ -166,13 +214,16 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
           if (originalIndex === undefined) continue;
           results[originalIndex] = this.toVector(item.embedding, "Batch embedding");
         }
+        if (indices.some((i) => results[i])) noteEmbeddingSuccess();
       } catch (err) {
-        if (!isInputRejection(err)) {
+        if (!isInputRejection(err) && !isBatchTooLarge(err)) {
           console.error("[memory] Batch embedding failed:", (err as Error).message);
+          if (isOutage(err)) noteEmbeddingFailure();
           continue;
         }
-        // One rejected input fails the whole request: embed each input alone so
-        // only that input is cut down, and the rest embed as they are.
+        // One rejected input fails the whole request, and a server with a low
+        // batch cap rejects the request for its size: embed each input alone so
+        // only a bad input is cut down, and the rest embed as they are.
         console.warn(
           `[memory] Batch embedding rejected, embedding ${indices.length} inputs one by one: ${(err as Error).message}`,
         );

package/src/be/memory/task-learning.ts

@@ -0,0 +1,257 @@
+/**
+ * Learnings captured through `store-progress`: one swarm-scope `manual` memory
+ * per learning, keyed `/learnings/<workstream>/<slug>` and tied to its task by
+ * `sourceTaskId`, so "what did we learn doing X" is one `keyPrefix` search.
+ *
+ * Source stays `manual` so nightly curation (memtax B1 reads only manual and
+ * file_index rows) picks learnings up without a new source value.
+ *
+ * A learning close to an existing swarm memory (raw cosine at or above
+ * LEARNING_DUPLICATE_MIN_SIMILARITY) is not stored: the existing row gets a
+ * positive rating instead. Known gap: embeddings are written in the background,
+ * so two near-identical learnings seconds apart can both pass the check.
+ * Nightly curation catches those.
+ */
+import { getDbClient } from "@/be/db";
+import { getEmbeddingProvider, getMemoryStore } from "@/be/memory";
+import { LEARNING_DUPLICATE_MIN_SIMILARITY } from "@/be/memory/constants";
+import { indexMemoryContent } from "@/be/memory/index-content";
+import { applyRating } from "@/be/memory/raters/store";
+import { contentSha256 } from "@/commands/profile-sync";
+import type { AgentTask } from "@/types";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+
+/** ~500 tokens at ceil(chars / 4); also keeps a learning to one memory chunk. */
+export const LEARNING_MAX_CHARS = 2000;
+export const LEARNING_MAX_TAGS = 5;
+const LEARNINGS_ROOT = "/learnings";
+const SEGMENT_MAX_CHARS = 60;
+const KEY_ATTEMPTS = 4;
+/** Where a near duplicate can already live: any workstream's learnings and the workstream digests. */
+const DUPLICATE_SEARCH_PREFIXES = [`${LEARNINGS_ROOT}/`, "/longterm/workstreams/"];
+/** memory_rating.source for the positive rating a duplicate gives the existing row. */
+export const LEARNING_DUPLICATE_RATING_SOURCE = "learning-duplicate";
+
+export type TaskLearningInput = string | { text: string; workstream?: string; tags?: string[] };
+
+export type TaskLearningResult =
+  | { status: "stored"; memoryId: string; key: string; workstream: string }
+  | { status: "replayed"; memoryId: string; key: string }
+  | { status: "duplicate"; memoryId: string; key: string; similarity: number }
+  | { status: "failed"; error: string };
+
+/** Lowercase kebab slug: `Agent Swarm!` -> `agent-swarm`. Empty when nothing usable is left. */
+export function toKebab(value: string, maxChars = SEGMENT_MAX_CHARS): string {
+  return value
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, maxChars)
+    .replace(/-+$/, "");
+}
+
+/** Explicit workstream, else the repo name from `vcsRepo` (`owner/name` or a URL), else `general`. */
+export function resolveLearningWorkstream(
+  explicit: string | undefined,
+  vcsRepo: string | undefined,
+): string {
+  const fromExplicit = explicit ? toKebab(explicit) : "";
+  if (fromExplicit) return fromExplicit;
+  const repoName = vcsRepo
+    ?.trim()
+    .replace(/\/+$/, "")
+    .split("/")
+    .pop()
+    ?.replace(/\.git$/, "");
+  const fromRepo = repoName ? toKebab(repoName) : "";
+  return fromRepo || "general";
+}
+
+export async function storeTaskLearning(params: {
+  agentId: string;
+  isLead: boolean;
+  task: Pick<AgentTask, "id" | "vcsRepo">;
+  learning: TaskLearningInput;
+}): Promise<TaskLearningResult> {
+  const { agentId, isLead, task } = params;
+  const input = typeof params.learning === "string" ? { text: params.learning } : params.learning;
+  // Scrub before anything is derived: a token in the title, workstream or a tag
+  // would otherwise survive (kebab-cased) in the key and tags, and the replay
+  // hash must match the hash of the scrubbed content the store persists.
+  const text = scrubSecrets(input.text).trim();
+  if (!text) return { status: "failed", error: "learning text is empty" };
+  if (text.length > LEARNING_MAX_CHARS) {
+    return {
+      status: "failed",
+      error: `learning text is over ~500 tokens (${LEARNING_MAX_CHARS} characters); shorten it`,
+    };
+  }
+  const tags = [
+    ...new Set((input.tags ?? []).map((tag) => toKebab(scrubSecrets(tag))).filter(Boolean)),
+  ].filter((tag) => tag !== "learning");
+  if (tags.length > LEARNING_MAX_TAGS) {
+    return { status: "failed", error: `learning takes at most ${LEARNING_MAX_TAGS} tags` };
+  }
+
+  const workstream = resolveLearningWorkstream(
+    input.workstream === undefined ? undefined : scrubSecrets(input.workstream),
+    task.vcsRepo === undefined ? undefined : scrubSecrets(task.vcsRepo),
+  );
+
+  try {
+    // Replay first: the same text on the same task is a retry, not a duplicate.
+    const replay = await findReplay(task.id, contentSha256(text));
+    if (replay) return replay;
+    // Outside the write transaction: the embedding call goes over the network.
+    const duplicate = await findNearDuplicate({ agentId, isLead, text });
+    if (duplicate) {
+      await rateDuplicate(duplicate, task.id);
+      return duplicate;
+    }
+    // One write transaction for the replay check and the insert, so two
+    // overlapping calls with the same learning store it once.
+    return await getDbClient().transaction(() =>
+      insertLearning({ agentId, isLead, taskId: task.id, text, tags, workstream }),
+    );
+  } catch (err) {
+    return {
+      status: "failed",
+      error: scrubSecrets(err instanceof Error ? err.message : String(err)),
+    };
+  }
+}
+
+async function findReplay(
+  taskId: string,
+  contentHash: string,
+): Promise<Extract<TaskLearningResult, { status: "replayed" }> | null> {
+  const replay = await getDbClient().get<{ id: string; key: string }>(
+    `SELECT id, key FROM agent_memory
+     WHERE sourceTaskId = ? AND contentHash = ? AND key LIKE '${LEARNINGS_ROOT}/%'
+     LIMIT 1`,
+    [taskId, contentHash],
+  );
+  return replay ? { status: "replayed", memoryId: replay.id, key: replay.key } : null;
+}
+
+/**
+ * The closest swarm memory under the duplicate prefixes when its raw cosine to
+ * the learning reaches the threshold. No `queryText`, so the store takes the
+ * vector or brute-force path and `similarity` is raw cosine, not an FTS rank or
+ * a fused score. Any failure (no embedding provider, a search error) returns
+ * null so the learning is stored as usual.
+ */
+async function findNearDuplicate(params: {
+  agentId: string;
+  isLead: boolean;
+  text: string;
+}): Promise<Extract<TaskLearningResult, { status: "duplicate" }> | null> {
+  try {
+    const embedding = await getEmbeddingProvider().embed(params.text);
+    if (!embedding) return null;
+    const store = getMemoryStore();
+    const results = await Promise.all(
+      DUPLICATE_SEARCH_PREFIXES.map((keyPrefix) =>
+        store.search(embedding, params.agentId, {
+          scope: "swarm",
+          isLead: params.isLead,
+          keyPrefix,
+          limit: 1,
+        }),
+      ),
+    );
+    const best = results
+      .flat()
+      .filter((candidate) => candidate.key)
+      .sort((a, b) => b.similarity - a.similarity)[0];
+    if (!best || best.similarity < LEARNING_DUPLICATE_MIN_SIMILARITY) return null;
+    return {
+      status: "duplicate",
+      memoryId: best.id,
+      key: best.key!,
+      similarity: Math.round(best.similarity * 1000) / 1000,
+    };
+  } catch (err) {
+    console.warn(
+      "[task-learning] near-duplicate check failed; storing the learning:",
+      scrubSecrets(err instanceof Error ? err.message : String(err)),
+    );
+    return null;
+  }
+}
+
+/** A repeated lesson is evidence the existing row is useful. A failed rating never fails the call. */
+async function rateDuplicate(
+  duplicate: Extract<TaskLearningResult, { status: "duplicate" }>,
+  taskId: string,
+): Promise<void> {
+  try {
+    await applyRating(
+      [
+        {
+          memoryId: duplicate.memoryId,
+          signal: 1,
+          weight: 1,
+          source: LEARNING_DUPLICATE_RATING_SOURCE,
+          reasoning: `store-progress learning matched at cosine ${duplicate.similarity}`,
+        },
+      ],
+      { taskId },
+    );
+  } catch (err) {
+    console.warn(
+      "[task-learning] duplicate rating failed:",
+      scrubSecrets(err instanceof Error ? err.message : String(err)),
+    );
+  }
+}
+
+async function insertLearning(params: {
+  agentId: string;
+  isLead: boolean;
+  taskId: string;
+  text: string;
+  tags: string[];
+  workstream: string;
+}): Promise<TaskLearningResult> {
+  const { agentId, isLead, taskId, text, tags, workstream } = params;
+  // indexMemoryContent stores text this short as one trimmed chunk, so this
+  // hash is the row's contentHash: a replayed call finds its own earlier write.
+  const replay = await findReplay(taskId, contentSha256(text));
+  if (replay) return replay;
+
+  const title = text.split(/\r?\n/, 1)[0]!.trim().slice(0, 200);
+  const baseKey = `${LEARNINGS_ROOT}/${workstream}/${toKebab(title) || "learning"}`;
+
+  // Keys are unique per owner and a reused key fails rather than upserts.
+  // Keep the path unique across the swarm: on a taken key, add a short suffix.
+  for (let attempt = 0; attempt < KEY_ATTEMPTS; attempt++) {
+    const key = attempt === 0 ? baseKey : `${baseKey}-${crypto.randomUUID().slice(0, 6)}`;
+    const taken = await getDbClient().get<{ id: string }>(
+      "SELECT id FROM agent_memory WHERE scope = 'swarm' AND key = ? LIMIT 1",
+      [key],
+    );
+    if (taken) continue;
+    try {
+      const result = await indexMemoryContent({
+        agentId,
+        content: text,
+        name: title,
+        scope: "swarm",
+        source: "manual",
+        sourceTaskId: taskId,
+        tags: ["learning", ...tags],
+        intent: "store-progress learning",
+        key,
+        writer: { principal: { kind: "agent", agentId, isLead }, source: "mcp" },
+      });
+      return { status: "stored", memoryId: result.memoryIds[0]!, key, workstream };
+    } catch (err) {
+      // The key is taken after all: try a suffixed one.
+      if (/UNIQUE constraint failed/i.test((err as Error).message)) continue;
+      throw err;
+    }
+  }
+  return { status: "failed", error: `no free key under ${baseKey}` };
+}

package/src/be/memory/types.ts

@@ -4,11 +4,22 @@ import type { AgentMemory, AgentMemoryScope, AgentMemorySource } from "@/types";
 // EmbeddingProvider — text to vector, swappable
 // ============================================================================
 
+/**
+ * What an input is for. Some models (nomic-embed) need a task prefix on each
+ * input: one for search queries, another for stored documents. No kind means
+ * no prefix.
+ */
+export type EmbeddingInputKind = "query" | "document";
+
+export interface EmbedOptions {
+  kind?: EmbeddingInputKind;
+}
+
 export interface EmbeddingProvider {
   readonly name: string;
   readonly dimensions: number;
-  embed(text: string): Promise<Float32Array | null>;
-  embedBatch(texts: string[]): Promise<(Float32Array | null)[]>;
+  embed(text: string, opts?: EmbedOptions): Promise<Float32Array | null>;
+  embedBatch(texts: string[], opts?: EmbedOptions): Promise<(Float32Array | null)[]>;
   /** True when the provider has a usable API key — no network call. */
   isConfigured(): boolean;
 }

package/src/be/migrations/245_script_executor.sql

@@ -0,0 +1,3 @@
+-- Optional per-script executor override ("native" | "quickjs").
+-- When NULL, the deployment's SCRIPT_EXECUTOR default applies.
+ALTER TABLE scripts ADD COLUMN executor TEXT DEFAULT NULL;

package/src/be/migrations/246_connector_code_kind.sql

@@ -0,0 +1,11 @@
+-- Kind of single-use code in connector_codes.
+--
+-- `connector`: the agent-swarm.dev ChatGPT connector code (10 minute TTL).
+-- `invite`: a teammate invite from `POST /api/invites` (7 day TTL). Its
+-- exchange at `POST /api/invites/exchange` also flips the user from
+-- `invited` to `active`.
+--
+-- Each exchange route redeems only its own kind. Existing rows are connector
+-- codes, so they keep today's behavior.
+ALTER TABLE connector_codes ADD COLUMN kind TEXT NOT NULL DEFAULT 'connector'
+  CHECK (kind IN ('connector', 'invite'));

package/src/be/oauth-refresh-sweep.ts

@@ -20,6 +20,7 @@
  * same per-authorization locks in ensure-token, so overlap is safe.
  */
 import { forceRefreshAuthorizationOrThrow } from "../oauth/ensure-token";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import {
   type AuthorizationSweepRow,
@@ -138,7 +139,7 @@ async function runSweepTick(trigger: "startup" | "interval"): Promise<void> {
  * already running.
  */
 export function startOAuthRefreshSweep(): void {
-  if (process.env.OAUTH_REFRESH_SWEEP_DISABLE === "true") {
+  if (isEnvFlagEnabled("OAUTH_REFRESH_SWEEP_DISABLE", false)) {
     console.log("[oauth-refresh-sweep] Disabled via OAUTH_REFRESH_SWEEP_DISABLE");
     return;
   }