@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "description": "agent-swarm.dev — an open-source operating system for AI work: a lead agent breaks goals into tasks, routes them to specialized workers such as Claude Code or Codex, runs each worker in an isolated container, and preserves shared memory, tools, schedules, and review gates so delegated work compounds across sessions.",
   "keywords": [
     "agent-swarm.dev",
@@ -80,6 +80,8 @@
     "sync:ai-toolbox-skills": "bun scripts/sync-ai-toolbox-skills.ts",
     "check:ai-toolbox-skills": "bun scripts/sync-ai-toolbox-skills.ts --check",
     "check:skill-sources": "bun scripts/check-skill-sources.ts",
+    "build:docs-index": "bun scripts/build-docs-index.ts",
+    "check:docs-index": "bun scripts/build-docs-index.ts --check",
     "check:operator-skill": "bun scripts/check-operator-skill.ts",
     "sync:telemetry-contract": "bun scripts/sync-telemetry-contract.ts",
     "check:telemetry-contract": "bun scripts/sync-telemetry-contract.ts --check",
@@ -185,7 +187,7 @@
     "@oxlint/plugins": "1.78.0",
     "@types/bun": "latest",
     "dependency-cruiser": "^18.0.0",
-    "happy-dom": "^20.14.5",
+    "happy-dom": "^21.0.4",
     "konsistent": "1.0.0-beta.1",
     "openapi-typescript": "^7",
     "oxlint": "1.78.0",
@@ -201,7 +203,7 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "2.0.2",
     "@ai-sdk/openai": "^3.0.41",
-    "@anthropic-ai/claude-agent-sdk": "0.3.310",
+    "@anthropic-ai/claude-agent-sdk": "0.3.311",
     "@anthropic-ai/sdk": "^1.3.0",
     "@asteasolutions/zod-to-openapi": "^8.0.0",
     "@aws-sdk/client-bedrock": "3.1048.0",
@@ -209,8 +211,8 @@
     "@chat-adapter/slack": "4.41.1",
     "@chat-adapter/teams": "4.41.1",
     "@chat-adapter/telegram": "4.41.1",
-    "@cursor/sdk": "1.0.40",
-    "@desplega.ai/agent-fs-just-bash": "0.18.5",
+    "@cursor/sdk": "1.1.0",
+    "@desplega.ai/agent-fs-just-bash": "0.18.9",
     "@desplega.ai/business-use": "^0.4.2",
     "@earendil-works/pi-agent-core": "^1.4.0",
     "@earendil-works/pi-ai": "^1.4.0",

package/src/be/automation-preflight.ts

@@ -3,6 +3,7 @@ import { getSlackConfiguration, isSlackConfigured } from "../slack/config";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { getDbClient } from "./db";
+import { emitRunFinished } from "./db/workflow-runs";
 import { getOAuthApp, getOAuthTokens } from "./db-queries/oauth";
 import { scrubJsonValue } from "./scrub-json";
 
@@ -446,6 +447,7 @@ export async function recordWorkflowPreflightFailure(input: {
         timestamp,
       ],
     );
+    emitRunFinished(runId, input.workflowId, "failed");
     // Claimed in this transaction, which also sees every child failure run
     // committed before it: concurrent failures alert exactly once a day.
     return {

package/src/be/connector-codes.ts

@@ -1,21 +1,34 @@
 /**
- * Single-use connect codes for the agent-swarm.dev ChatGPT connector.
+ * Single-use codes that a browser or connector trades once for an `aswt_` token.
  *
- * The dashboard asks for a code (`POST /api/users/:id/connector-codes`) and
- * opens the connector's connect page with it. The connector trades the code
- * once (`POST /api/connector/exchange`) for a user-bound `aswt_` token. The
- * token is minted only at exchange time, through the regular `mintToken`
- * path, so an unused code never leaves a token behind.
+ * Two kinds share the `connector_codes` table:
+ *
+ * - `connector`: the agent-swarm.dev ChatGPT connector. The dashboard asks for
+ *   a code (`POST /api/users/:id/connector-codes`) and opens the connector's
+ *   connect page with it. The connector trades the code once
+ *   (`POST /api/connector/exchange`).
+ * - `invite`: a teammate invite (`POST /api/invites`). The teammate's browser
+ *   trades it once (`POST /api/invites/exchange`). The exchange also flips the
+ *   user from `invited` to `active`, because `aswt_` auth admits only active
+ *   users.
+ *
+ * The token is minted only at exchange time, through the regular `mintToken`
+ * path, so an unused code never leaves a token behind. Each exchange redeems
+ * only its own kind.
  */
 
 import { createHash, randomBytes } from "node:crypto";
 import { getDbClient } from "./db";
-import { type IdentityActor, mintToken } from "./users";
+import { type IdentityActor, mintToken, recordIdentityEvent } from "./users";
+
+export type ConnectorCodeKind = "connector" | "invite";
 
 export const CONNECTOR_CODE_TTL_MS = 10 * 60 * 1000;
+export const INVITE_CODE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Expired rows stay this long before the heartbeat sweep deletes them. */
 const CONNECTOR_CODE_RETENTION_MS = 60 * 60 * 1000;
 export const DEFAULT_CONNECTOR_CODE_LABEL = "ChatGPT connector";
+export const DEFAULT_INVITE_CODE_LABEL = "Dashboard invite";
 
 function sha256Hex(input: string): string {
   return createHash("sha256").update(input).digest("hex");
@@ -27,27 +40,34 @@ export async function createConnectorCode(
   label: string,
   actor: IdentityActor,
   now = new Date(),
+  opts: { kind?: ConnectorCodeKind; ttlMs?: number } = {},
 ): Promise<{ code: string; expiresAt: string }> {
+  const kind = opts.kind ?? "connector";
+  const ttlMs = opts.ttlMs ?? CONNECTOR_CODE_TTL_MS;
   const code = randomBytes(32).toString("base64url");
-  const expiresAt = new Date(now.getTime() + CONNECTOR_CODE_TTL_MS).toISOString();
+  const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
   await getDbClient().run(
     `INSERT INTO connector_codes
-       (code_hash, user_id, label, actor_kind, actor_id, created_at, expires_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`,
-    [sha256Hex(code), userId, label, actor.kind, actor.id, now.toISOString(), expiresAt],
+       (code_hash, user_id, label, actor_kind, actor_id, created_at, expires_at, kind)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [sha256Hex(code), userId, label, actor.kind, actor.id, now.toISOString(), expiresAt, kind],
   );
   return { code, expiresAt };
 }
 
 /**
  * Consume a code and mint its token in one transaction. Returns null when the
- * code is unknown, expired, or already used (callers must not tell these apart).
+ * code is unknown, expired, already used, or of another kind (callers must not
+ * tell these apart). For an invite code, also returns null when the user is
+ * no longer `invited` (suspended or merged since): the code is spent and no
+ * token is minted.
  */
 export async function exchangeConnectorCode(
   code: string,
-  now = new Date(),
+  opts: { kind?: ConnectorCodeKind; now?: Date } = {},
 ): Promise<{ token: string; userId: string } | null> {
-  const nowIso = now.toISOString();
+  const kind = opts.kind ?? "connector";
+  const nowIso = (opts.now ?? new Date()).toISOString();
   return getDbClient().transaction(async (tx) => {
     const row = await tx.get<{
       user_id: string;
@@ -56,21 +76,44 @@ export async function exchangeConnectorCode(
       actor_id: string;
     }>(
       `UPDATE connector_codes SET used_at = ?
-        WHERE code_hash = ? AND used_at IS NULL AND expires_at > ?
+        WHERE code_hash = ? AND used_at IS NULL AND expires_at > ? AND kind = ?
         RETURNING user_id, label, actor_kind, actor_id`,
-      [nowIso, sha256Hex(code), nowIso],
+      [nowIso, sha256Hex(code), nowIso, kind],
     );
     if (!row) return null;
-    const { plaintext } = await mintToken(
-      row.user_id,
-      row.label,
-      { kind: row.actor_kind, id: row.actor_id },
-      { source: "connector_exchange" },
-    );
+    const actor: IdentityActor = { kind: row.actor_kind, id: row.actor_id };
+
+    if (kind === "invite") {
+      const activated = await tx.run(
+        "UPDATE users SET status = 'active', lastUpdatedAt = ? WHERE id = ? AND status = 'invited'",
+        [nowIso, row.user_id],
+      );
+      if (activated.changes === 0) return null;
+      await recordIdentityEvent(
+        row.user_id,
+        "status_changed",
+        actor,
+        { status: "invited" },
+        { status: "active", source: "invite_exchange" },
+      );
+    }
+
+    const { plaintext } = await mintToken(row.user_id, row.label, actor, {
+      source: kind === "invite" ? "invite_exchange" : "connector_exchange",
+    });
     return { token: plaintext, userId: row.user_id };
   });
 }
 
+/** Delete a user's unused invite codes, so a re-invite leaves one live link. */
+export async function deleteUnusedInviteCodes(userId: string): Promise<number> {
+  const result = await getDbClient().run(
+    "DELETE FROM connector_codes WHERE user_id = ? AND kind = 'invite' AND used_at IS NULL",
+    [userId],
+  );
+  return result.changes;
+}
+
 /** Delete codes that expired more than 1h ago. Returns the number of deleted rows. */
 export async function deleteExpiredConnectorCodes(now = new Date()): Promise<number> {
   const cutoff = new Date(now.getTime() - CONNECTOR_CODE_RETENTION_MS).toISOString();

package/src/be/db/api-keys.ts

@@ -110,6 +110,15 @@ export async function recordKeyValidation(
           now,
         ],
       );
+      // A passing test clears the key's rejection in every scope, since the
+      // suffix read in `getAvailableKeyIndices` matches them all.
+      if (key.ok) {
+        await tx.run(
+          `UPDATE api_key_status SET lastValidationError = NULL, lastValidationFailedAt = NULL, updatedAt = ?
+           WHERE keyType = ? AND keySuffix = ? AND lastValidationFailedAt IS NOT NULL`,
+          [now, keyType, key.keySuffix],
+        );
+      }
     }
     if (options.retireAbsent === false) return;
     const placeholders = keys.map(() => "?").join(", ");

package/src/be/db/workflow-runs.ts

@@ -465,7 +465,8 @@ export async function disarmWorkflowTreeRetries(
 /**
  * Mark the given runs that are still running or waiting `cancelled`, without
  * the per-run `workflow.child.finished` wake-up: it is for runs whose parent
- * step the same cancel closes. A terminal run keeps its status and reason.
+ * step the same cancel closes. Each run it cancels still emits
+ * `workflow.run.finished`. A terminal run keeps its status and reason.
  */
 export async function cancelLiveWorkflowTreeRuns(
   runIds: string[],
@@ -473,12 +474,14 @@ export async function cancelLiveWorkflowTreeRuns(
   finishedAt: string,
 ): Promise<void> {
   await forEachChunk(runIds, async (chunk, placeholders) => {
-    await getDbClient().run(
+    const cancelled = await getDbClient().query<{ id: string; workflowId: string }>(
       `UPDATE workflow_runs
           SET status = 'cancelled', error = ?, finishedAt = ?, lastUpdatedAt = ?
-        WHERE id IN (${placeholders}) AND status IN ('running', 'waiting')`,
+        WHERE id IN (${placeholders}) AND status IN ('running', 'waiting')
+        RETURNING id, workflowId`,
       [scrubSecrets(reason), finishedAt, finishedAt, ...chunk],
     );
+    for (const run of cancelled) emitRunFinished(run.id, run.workflowId, "cancelled");
   });
 }
 
@@ -643,14 +646,42 @@ export function emitChildRunFinished(
 }
 
 function emitAfterCommit(childRunId: string, parentStepId: string): void {
+  emitBusEventAfterCommit("workflow.child.finished", { childRunId, parentStepId });
+}
+
+/** Bus event every run emits once when it turns terminal. */
+export const WORKFLOW_RUN_FINISHED_EVENT = "workflow.run.finished";
+
+export function isTerminalWorkflowRunStatus(status: WorkflowRunStatus): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
+/**
+ * Announce after commit that a run turned terminal, top-level and child runs
+ * alike, so an event-mode `wait` can resume when any run ends. Callers emit
+ * only when a live run (running or waiting) turns terminal, never on a later
+ * update of a run that is already terminal. The id is `runId`, never `workflowRunId` or
+ * `_runId`: those would put the finished run in the waiting run's own `run`
+ * scope, so waiters use scope `global` and filter on `runId`.
+ */
+export function emitRunFinished(
+  runId: string,
+  workflowId: string,
+  status: WorkflowRunStatus,
+): void {
+  if (!TERMINAL_STATUSES.has(status)) return;
+  emitBusEventAfterCommit(WORKFLOW_RUN_FINISHED_EVENT, { runId, workflowId, status });
+}
+
+function emitBusEventAfterCommit(event: string, payload: Record<string, unknown>): void {
   getDbClient().afterCommit(() => {
     import("../../workflows/event-bus")
       .then(({ workflowEventBus }) => {
-        workflowEventBus.emit("workflow.child.finished", { childRunId, parentStepId });
+        workflowEventBus.emit(event, payload);
       })
       .catch((err) =>
         console.error(
-          "[db] workflow.child.finished event not emitted:",
+          `[db] ${event} event not emitted:`,
           scrubSecrets(err instanceof Error ? err.message : String(err)),
         ),
       );

package/src/be/db.ts

@@ -227,8 +227,10 @@ import { configureTaskWriteDependencies, failTask } from "./db/tasks/write";
 import { tombstoneWorkflowIdempotencyKeys } from "./db/workflow-idempotency";
 import {
   emitChildRunFinished,
+  emitRunFinished,
   getRunLineageBlock,
   getStepExecutionBlock,
+  isTerminalWorkflowRunStatus,
   rowToWorkflowRun,
   rowToWorkflowRunStep,
   WORKFLOW_RUN_SUMMARY_COLUMNS,
@@ -7994,16 +7996,33 @@ export async function updateWorkflowRun(
   updates.push("lastUpdatedAt = ?");
   params.push(new Date().toISOString());
   params.push(id);
-  const row = await getDbClient().get<WorkflowRunRow>(
-    `UPDATE workflow_runs SET ${updates.join(", ")} WHERE id = ? RETURNING *`,
-    params,
-  );
+  const update = () =>
+    getDbClient().get<WorkflowRunRow>(
+      `UPDATE workflow_runs SET ${updates.join(", ")} WHERE id = ? RETURNING *`,
+      params,
+    );
+  const endsRun = data.status !== undefined && isTerminalWorkflowRunStatus(data.status);
+  // A run that ends reads the status it replaces in the same transaction, so
+  // only a change out of a live status announces the end: a later terminal
+  // write, same status or not, does not announce it again.
+  const [previousStatus, row] = endsRun
+    ? await getDbClient().transaction(async () => {
+        const previous = await getDbClient().get<{ status: WorkflowRunStatus }>(
+          "SELECT status FROM workflow_runs WHERE id = ?",
+          [id],
+        );
+        return [previous?.status, await update()] as const;
+      })
+    : [undefined, await update()];
   if (!row) return null;
   const run = rowToWorkflowRun(row);
   if (data.status === "completed" || data.status === "failed") {
     emitWorkflowTerminalTelemetry(run);
   }
   if (row.parentStepId) emitChildRunFinished(id, row.parentStepId, run.status);
+  if (endsRun && previousStatus && !isTerminalWorkflowRunStatus(previousStatus)) {
+    emitRunFinished(id, run.workflowId, run.status);
+  }
   return run;
 }
 
@@ -11721,6 +11740,14 @@ export interface AvailableKeyIndicesResult {
  * whose `plan` cannot run the family (`planAllowsModelFamily`) is excluded
  * and reported in `seatBlockedIndices`, also when it is key-wide or
  * model-window blocked; a seat block has no reset time.
+ *
+ * With `keySuffixes` (the caller's own pool, in order), rows are matched by
+ * key suffix instead of the stored `keyIndex`, across every scope: a key has
+ * one state wherever it is pooled, and a key at the same index in another
+ * agent's pool is never blocked by it. A suffix listed more than once is read
+ * by `keyIndex` in `scope`/`scopeId`, as without the list. Returned indices
+ * are positions in `keySuffixes`. Without it, rows of `scope`/`scopeId` are
+ * read by `keyIndex`.
  */
 export async function getAvailableKeyIndices(
   keyType: string,
@@ -11728,41 +11755,58 @@ export async function getAvailableKeyIndices(
   scope = "global",
   scopeId: string | null = null,
   modelFamily?: ModelFamily,
+  keySuffixes?: string[],
 ): Promise<AvailableKeyIndicesResult> {
   const now = new Date().toISOString();
   const nowMs = Date.now();
   const client = getDbClient();
   const effectiveScopeId = scopeId ?? "";
+  const suffixes = keySuffixes?.length ? keySuffixes : undefined;
+  const rowFilter = suffixes
+    ? `keyType = ? AND keySuffix IN (${suffixes.map(() => "?").join(", ")})`
+    : "keyType = ? AND scope = ? AND scopeId = ?";
+  const rowParams = suffixes ? [keyType, ...suffixes] : [keyType, scope, effectiveScopeId];
 
   // Auto-clear expired rate limits. Never an auth bench: only `clearAuthBench` lifts it.
   await client.run(
     `UPDATE api_key_status
      SET status = 'available', rateLimitedUntil = NULL, updatedAt = ?
-     WHERE keyType = ? AND scope = ? AND scopeId = ?
+     WHERE ${rowFilter}
        AND status = 'rate_limited' AND rateLimitedUntil <= ? AND consecutiveAuthFailures < ?`,
-    [now, keyType, scope, effectiveScopeId, now, CODEX_AUTH_FAILURE_BENCH_THRESHOLD],
+    [now, ...rowParams, now, CODEX_AUTH_FAILURE_BENCH_THRESHOLD],
   );
 
   const rows = await client.query<{
     keyIndex: number;
+    keySuffix: string;
+    scope: string;
+    scopeId: string;
     status: string;
     rateLimitWindows: string | null;
     plan: string | null;
     authFailureSeq: number;
     lastValidationFailedAt: string | null;
   }>(
-    `SELECT keyIndex, status, rateLimitWindows, plan, authFailureSeq, lastValidationFailedAt FROM api_key_status
-       WHERE keyType = ? AND scope = ? AND scopeId = ?`,
-    [keyType, scope, effectiveScopeId],
-  );
+    `SELECT keyIndex, keySuffix, scope, scopeId, status, rateLimitWindows, plan, authFailureSeq, lastValidationFailedAt FROM api_key_status
+       WHERE ${rowFilter}`,
+    rowParams,
+  );
+  // Pool positions a row applies to: the position holding its suffix, or its stored index.
+  // A suffix held by several pool members cannot tell them apart, so it falls back to
+  // the index read: only a row of the requested scope, at its stored index.
+  const positionsOf = (row: (typeof rows)[number]): number[] => {
+    if (!suffixes) return [row.keyIndex];
+    const positions = suffixes.flatMap((suffix, i) => (suffix === row.keySuffix ? [i] : []));
+    if (positions.length < 2) return positions;
+    const sameScope = row.scope === scope && row.scopeId === effectiveScopeId;
+    return sameScope && positions.includes(row.keyIndex) ? [row.keyIndex] : [];
+  };
 
   const blockedIndices = new Set(
-    rows.filter((r) => r.status === "rate_limited").map((r) => r.keyIndex),
+    rows.filter((r) => r.status === "rate_limited").flatMap(positionsOf),
   );
   const rejectedIndices = [
-    ...new Set(
-      rows.filter((row) => row.lastValidationFailedAt !== null).map((row) => row.keyIndex),
-    ),
+    ...new Set(rows.filter((row) => row.lastValidationFailedAt !== null).flatMap(positionsOf)),
   ];
   for (const index of rejectedIndices) blockedIndices.add(index);
 
@@ -11773,14 +11817,17 @@ export async function getAvailableKeyIndices(
       // A key already blocked key-wide doesn't need a separate model-block
       // entry — it's excluded from availableIndices either way, and
       // modelBlockedIndices means "excluded only by a model-scoped block".
-      if (blockedIndices.has(row.keyIndex)) continue;
+      const positions = positionsOf(row).filter(
+        (i) => !blockedIndices.has(i) && !modelBlockedIndices.includes(i),
+      );
+      if (positions.length === 0) continue;
       const block = activeModelBlock(
         parseRateLimitWindowsJson(row.rateLimitWindows),
         modelFamily,
         nowMs,
       );
       if (!block) continue;
-      modelBlockedIndices.push(row.keyIndex);
+      modelBlockedIndices.push(...positions);
       if (earliestModelResetsAtSec === undefined || block.resetsAt < earliestModelResetsAtSec) {
         earliestModelResetsAtSec = block.resetsAt;
       }
@@ -11794,7 +11841,10 @@ export async function getAvailableKeyIndices(
   const seatBlockedIndices: number[] = [];
   if (modelFamily) {
     for (const row of rows) {
-      if (!planAllowsModelFamily(row.plan, modelFamily)) seatBlockedIndices.push(row.keyIndex);
+      if (planAllowsModelFamily(row.plan, modelFamily)) continue;
+      for (const i of positionsOf(row)) {
+        if (!seatBlockedIndices.includes(i)) seatBlockedIndices.push(i);
+      }
     }
   }
   const seatBlockedSet = new Set(seatBlockedIndices);
@@ -12143,22 +12193,30 @@ export async function clearKeyRateLimit(
   const effectiveScopeId = scopeId ?? "";
   const { keyIndex = -1, authFence = null } = opts;
   const clearAuthBench = opts.clearAuthBench === true && authFence !== null;
-  const key = [keyType, keySuffix, scope, effectiveScopeId];
   return await getDbClient().transaction(async (tx) => {
+    // The key's rows in every scope: `getAvailableKeyIndices` reads them all by suffix.
     const result = await tx.run(
       `UPDATE api_key_status
          SET status = 'available', rateLimitedUntil = NULL, updatedAt = ?
-         WHERE keyType = ? AND keySuffix = ? AND scope = ? AND scopeId = ?
+         WHERE keyType = ? AND keySuffix = ?
            AND status = 'rate_limited' AND ((? AND authFailureSeq <= ?) OR consecutiveAuthFailures < ?)`,
-      [now, ...key, clearAuthBench ? 1 : 0, authFence, CODEX_AUTH_FAILURE_BENCH_THRESHOLD],
+      [
+        now,
+        keyType,
+        keySuffix,
+        clearAuthBench ? 1 : 0,
+        authFence,
+        CODEX_AUTH_FAILURE_BENCH_THRESHOLD,
+      ],
     );
     const cleared = result.changes > 0;
     if (!clearAuthBench) return cleared;
     const lifted = await tx.query<{ keySuffix: string }>(
       `UPDATE api_key_status SET consecutiveAuthFailures = 0, updatedAt = ?1,
            status = CASE WHEN keySuffix = ?2 THEN status ELSE 'available' END, rateLimitedUntil = CASE WHEN keySuffix = ?2 THEN rateLimitedUntil END
-         WHERE keyType = ?3 AND scope = ?4 AND scopeId = ?5 AND (consecutiveAuthFailures > 0 OR status = 'rate_limited')
-           AND ((keySuffix = ?2 AND authFailureSeq <= ?7) OR (keySuffix != ?2 AND keyIndex = ?6)) RETURNING keySuffix`,
+         WHERE keyType = ?3 AND (consecutiveAuthFailures > 0 OR status = 'rate_limited')
+           AND ((keySuffix = ?2 AND authFailureSeq <= ?7)
+             OR (keySuffix != ?2 AND keyIndex = ?6 AND scope = ?4 AND scopeId = ?5)) RETURNING keySuffix`,
       [now, keySuffix, keyType, scope, effectiveScopeId, keyIndex, authFence],
     );
     const retired = lifted.filter((row) => row.keySuffix !== keySuffix);

package/src/be/memory/boot-reembed.ts

@@ -56,7 +56,10 @@ export async function runBootReembed(): Promise<void> {
   for (let i = 0; i < rows.length; i += BATCH_SIZE) {
     const batch = rows.slice(i, i + BATCH_SIZE);
     try {
-      const embeddings = await provider.embedBatch(batch.map((m) => m.content));
+      const embeddings = await provider.embedBatch(
+        batch.map((m) => m.content),
+        { kind: "document" },
+      );
       for (let j = 0; j < embeddings.length; j++) {
         if (embeddings[j]) {
           await store.updateEmbedding(batch[j]!.id, embeddings[j]!, provider.name);

package/src/be/memory/constants.ts

@@ -72,6 +72,12 @@ export function minSimilarity(): number {
   return numEnv("MEMORY_MIN_SIMILARITY", 0.1);
 }
 
+// Raw cosine at or above which a store-progress learning is a near duplicate of
+// an existing swarm memory and is not stored. Measured on production
+// `/learnings` rows: a confirmed twin pair scored 0.877, the closest distinct
+// pair 0.705.
+export const LEARNING_DUPLICATE_MIN_SIMILARITY = 0.8;
+
 // Reranking parameters
 export function accessBoostMaxMultiplier(): number {
   return numEnv("MEMORY_ACCESS_BOOST_MAX", 1.5);

package/src/be/memory/embedding-recovery.ts

@@ -0,0 +1,48 @@
+/**
+ * A memory or script written while the embeddings endpoint is down keeps no
+ * vector, and the backfills (`runBootReembed`, `runBootReembedScripts`) run
+ * only at boot or when a config reload turns embeddings on. When an embedding
+ * call works again after a failed one (for example, a local TEI restarted),
+ * run both backfills once more, so those rows do not wait for the next API
+ * restart.
+ */
+
+let failedSinceBackfill = false;
+let backfill: Promise<void> | null = null;
+
+/** An embedding call failed (network, server error, rejected request). */
+export function noteEmbeddingFailure(): void {
+  failedSinceBackfill = true;
+}
+
+/** An embedding call returned a vector. Starts the backfill after a failure. */
+export function noteEmbeddingSuccess(): void {
+  if (!failedSinceBackfill || backfill) return;
+  failedSinceBackfill = false;
+  const report = (what: string) => (err: unknown) => {
+    console.error(
+      `[memory] ${what} backfill after embeddings recovered failed:`,
+      (err as Error).message,
+    );
+  };
+  backfill = Promise.all([
+    import("./boot-reembed").then(({ runBootReembed }) => runBootReembed()).catch(report("Memory")),
+    import("../scripts/boot-reembed")
+      .then(({ runBootReembedScripts }) => runBootReembedScripts())
+      .catch(report("Script")),
+  ])
+    .then(() => undefined)
+    .finally(() => {
+      backfill = null;
+    });
+}
+
+/** The backfill started by the last recovery, if it still runs. For tests. */
+export function pendingRecoveryBackfill(): Promise<void> | null {
+  return backfill;
+}
+
+/** Forget a failure seen by an earlier test. */
+export function resetEmbeddingRecoveryForTests(): void {
+  failedSinceBackfill = false;
+}

package/src/be/memory/index-content.ts

@@ -104,7 +104,7 @@ export async function indexMemoryContent(
         intent: "re-index memory source path",
         changedByAgentId: agentId,
       });
-      const embedding = await provider.embed(result.memory.content);
+      const embedding = await provider.embed(result.memory.content, { kind: "document" });
       if (embedding) await store.updateEmbedding(result.memory.id, embedding, provider.name);
       try {
         // Re-index of an existing memory: prune stale content-derived links.
@@ -162,7 +162,10 @@ export async function indexMemoryContent(
   // Async batch embed (fire and forget)
   (async () => {
     try {
-      const embeddings = await provider.embedBatch(memories.map((m) => m.content));
+      const embeddings = await provider.embedBatch(
+        memories.map((m) => m.content),
+        { kind: "document" },
+      );
       for (let i = 0; i < embeddings.length; i++) {
         if (embeddings[i]) {
           await store.updateEmbedding(memories[i]!.id, embeddings[i]!, provider.name);