@desplega.ai/agent-swarm 2.6.0 → 2.7.1

package/src/be/onboarding.ts

@@ -2,7 +2,13 @@ import { telemetry } from "../telemetry";
 import { ProviderNameSchema } from "../types";
 import { getCurrentRequestUserId } from "../utils/request-auth-context";
 import { z } from "../utils/zod-openapi";
-import { getDbClient, getSwarmConfigs, getTaskById, upsertSwarmConfig } from "./db";
+import {
+  deleteSwarmConfigByKey,
+  getDbClient,
+  getSwarmConfigs,
+  getTaskById,
+  upsertSwarmConfig,
+} from "./db";
 import { validateConfigValue } from "./swarm-config-guard";
 
 const ONBOARDING_CONFIG_KEY = "onboarding_state";
@@ -14,6 +20,7 @@ export const OnboardingStepIdSchema = z.enum([
   "agents",
   "memory",
   "integrations",
+  "files",
   "first_task",
 ]);
 export type OnboardingStepId = z.infer<typeof OnboardingStepIdSchema>;
@@ -54,6 +61,19 @@ export const OnboardingMemoryPresetSchema = z.enum([
   "custom",
   "existing",
 ]);
+/**
+ * Where the embeddings endpoint runs: `local` (this server or its private
+ * network), the hosted preset whose host it calls, or `custom` (another host).
+ */
+export const OnboardingMemoryProviderSchema = z.enum([
+  "local",
+  "openai",
+  "openrouter",
+  "vercel",
+  "azure",
+  "custom",
+]);
+export type OnboardingMemoryProvider = z.infer<typeof OnboardingMemoryProviderSchema>;
 export const OnboardingIntegrationMethodSchema = z.enum([
   "slack",
   "github",
@@ -62,6 +82,8 @@ export const OnboardingIntegrationMethodSchema = z.enum([
   "linear_oauth",
   "jira_oauth",
 ]);
+/** `created`: the Files step registered a new agent-fs account. `connected`: it reused one. */
+export const OnboardingFilesMethodSchema = z.enum(["created", "connected"]);
 export const OnboardingFirstTaskMethodSchema = z.enum(["suggestion", "free_form"]);
 export const OnboardingStepMethodSchema = z.union([
   OnboardingConnectMethodSchema,
@@ -70,6 +92,7 @@ export const OnboardingStepMethodSchema = z.union([
   OnboardingAgentsMethodSchema,
   OnboardingMemoryPresetSchema,
   OnboardingIntegrationMethodSchema,
+  OnboardingFilesMethodSchema,
   OnboardingFirstTaskMethodSchema,
 ]);
 export type OnboardingStepMethod = z.infer<typeof OnboardingStepMethodSchema>;
@@ -98,6 +121,7 @@ const OnboardingMemoryStepStateSchema = onboardingStepStateSchema(OnboardingMemo
 const OnboardingIntegrationStepStateSchema = onboardingStepStateSchema(
   OnboardingIntegrationMethodSchema,
 );
+const OnboardingFilesStepStateSchema = onboardingStepStateSchema(OnboardingFilesMethodSchema);
 const OnboardingFirstTaskStepStateSchema = onboardingStepStateSchema(
   OnboardingFirstTaskMethodSchema,
 );
@@ -118,6 +142,7 @@ export const OnboardingStateSchema = z.object({
     agents: OnboardingAgentsStepStateSchema,
     memory: OnboardingMemoryStepStateSchema,
     integrations: OnboardingIntegrationStepStateSchema,
+    files: OnboardingFilesStepStateSchema,
     first_task: OnboardingFirstTaskStepStateSchema,
   }),
 });
@@ -139,6 +164,21 @@ export const OnboardingSignalsSchema = z.object({
   embeddings: z.object({
     configured: z.boolean(),
     dimensions: z.number().int().positive(),
+    /** The embedding model memory search uses. Null while it is off. */
+    model: z.string().nullable(),
+    /**
+     * The endpoint runs on this server or its private network (loopback, a
+     * private address, or a single-label host such as `tei`). False while off.
+     */
+    local: z.boolean(),
+    /** Where the endpoint runs, from its host only (never the URL). Null while off. */
+    provider: OnboardingMemoryProviderSchema.nullable(),
+    /**
+     * The local setup of the deployment environment, also while a stored
+     * hosted setup replaces it, so `/setup` can offer it again: the model of
+     * its local endpoint. Null when the environment has no local endpoint.
+     */
+    localDefault: z.object({ model: z.string() }).nullable(),
   }),
   integrations: z.object({
     slack: z.boolean(),
@@ -153,6 +193,8 @@ export const OnboardingSignalsSchema = z.object({
     workersOnline: z.number().int().nonnegative(),
   }),
   firstTask: z.object({ id: z.string(), status: z.string() }).nullable(),
+  /** The Files step applies: Comb is on, so the browser can create an agent-fs account. */
+  files: z.object({ enabled: z.boolean() }),
 });
 export type OnboardingSignals = z.infer<typeof OnboardingSignalsSchema>;
 
@@ -198,10 +240,17 @@ export const OnboardingActionSchema = z.union([
       method: OnboardingIntegrationMethodSchema,
     })
     .strict(),
+  z
+    .object({
+      action: z.literal("complete"),
+      step: z.literal("files"),
+      method: OnboardingFilesMethodSchema,
+    })
+    .strict(),
   z
     .object({
       action: z.literal("skip"),
-      step: z.enum(["name", "ai", "agents", "memory", "integrations", "first_task"]),
+      step: z.enum(["name", "ai", "agents", "memory", "integrations", "files", "first_task"]),
     })
     .strict(),
   z
@@ -243,8 +292,18 @@ export const OnboardingMemoryRequestSchema = z
     model: z.string().trim().min(1).optional(),
     apiKey: z.string().min(1).optional(),
     reuseKey: z.enum(["OPENAI_API_KEY", "OPENROUTER_API_KEY"]).optional(),
+    /**
+     * With preset `existing`: test the setup of the deployment environment,
+     * and when it works, delete the stored embeddings config so that setup
+     * applies again. A failed test changes no config.
+     */
+    restoreDefault: z.boolean().optional(),
   })
-  .strict();
+  .strict()
+  .refine((body) => !body.restoreDefault || body.preset === "existing", {
+    message: "restoreDefault needs preset existing",
+    path: ["restoreDefault"],
+  });
 export type OnboardingMemoryRequest = z.infer<typeof OnboardingMemoryRequestSchema>;
 
 export const OnboardingMemoryResponseSchema = z.object({
@@ -320,6 +379,7 @@ function freshState(now: string, autoCompleted: boolean): OnboardingState {
       agents: emptyStep(),
       memory: emptyStep(),
       integrations: emptyStep(),
+      files: emptyStep(),
       first_task: emptyStep(),
     },
   };
@@ -535,6 +595,20 @@ function deriveState(
   return changed;
 }
 
+/**
+ * The response view of the state. Without Comb the Files step cannot run, so a
+ * stored `todo` reads as `skipped`. Response only: never persisted and never a
+ * `step_skipped` event, so installs without Comb send no funnel noise and the
+ * step comes back as `todo` once Comb is turned on.
+ */
+function presentState(state: OnboardingState, signals: OnboardingSignals): OnboardingState {
+  if (signals.files.enabled || state.steps.files.status !== "todo") return state;
+  return {
+    ...state,
+    steps: { ...state.steps, files: { ...state.steps.files, status: "skipped" } },
+  };
+}
+
 export class OnboardingTaskNotFoundError extends Error {}
 
 async function applyAction(
@@ -612,7 +686,8 @@ export async function readOrUpdateOnboarding(
     const read = await client.transaction(async () => await loadAndDerive(loadSignals, []), {
       readOnly: true,
     });
-    if (!read.dirty) return { state: read.state, signals: read.signals };
+    if (!read.dirty)
+      return { state: presentState(read.state, read.signals), signals: read.signals };
   }
 
   return await client.transaction(async () => {
@@ -627,14 +702,43 @@ export async function readOrUpdateOnboarding(
     }
     if (dirty) await persistState(state);
     queueTelemetry(events);
-    return { state, signals };
+    return { state: presentState(state, signals), signals };
   });
 }
 
+/** The embeddings rows a memory probe writes or deletes. */
+export const EMBEDDING_PREFIX_KEYS = [
+  "EMBEDDING_QUERY_PREFIX",
+  "EMBEDDING_DOCUMENT_PREFIX",
+] as const;
+export const EMBEDDING_CONFIG_KEYS = [
+  "EMBEDDING_API_BASE_URL",
+  "EMBEDDING_MODEL",
+  "EMBEDDING_API_KEY",
+  ...EMBEDDING_PREFIX_KEYS,
+] as const;
+
+/**
+ * The config change of a passed memory probe:
+ * - `save`: store the tested endpoint. `prefixes` sets a task prefix to an
+ *   empty value (`""`), or deletes its stored row (`null`).
+ * - `restore`: delete the stored embeddings rows, so the deployment
+ *   environment applies again.
+ */
+export type MemoryConfigChange =
+  | {
+      kind: "save";
+      baseUrl: string;
+      model: string;
+      apiKey?: string;
+      prefixes: ReadonlyArray<{ key: (typeof EMBEDDING_PREFIX_KEYS)[number]; value: "" | null }>;
+    }
+  | { kind: "restore" };
+
 export async function updateOnboardingMemory(
   preset: OnboardingMemoryPreset,
   result: { ok: true } | { ok: false; errorClass: OnboardingErrorClass },
-  saveConfig?: { baseUrl: string; model: string; apiKey?: string },
+  change?: MemoryConfigChange,
 ): Promise<boolean> {
   return await getDbClient().transaction(async () => {
     const events: PendingTelemetry[] = [];
@@ -642,11 +746,11 @@ export async function updateOnboardingMemory(
     let dirty = loaded.dirty;
     const eventsForState = loaded.state.autoCompleted ? [] : events;
 
-    if (saveConfig) {
+    if (change?.kind === "save") {
       const configValues = [
-        ["EMBEDDING_API_BASE_URL", saveConfig.baseUrl],
-        ["EMBEDDING_MODEL", saveConfig.model],
-        ...(saveConfig.apiKey ? [["EMBEDDING_API_KEY", saveConfig.apiKey]] : []),
+        ["EMBEDDING_API_BASE_URL", change.baseUrl],
+        ["EMBEDDING_MODEL", change.model],
+        ...(change.apiKey ? [["EMBEDDING_API_KEY", change.apiKey]] : []),
       ] as const;
       for (const [key, value] of configValues) {
         const validationError = validateConfigValue(key, value);
@@ -655,17 +759,23 @@ export async function updateOnboardingMemory(
       await upsertSwarmConfig({
         scope: "global",
         key: "EMBEDDING_API_BASE_URL",
-        value: saveConfig.baseUrl,
+        value: change.baseUrl,
       });
-      await upsertSwarmConfig({ scope: "global", key: "EMBEDDING_MODEL", value: saveConfig.model });
-      if (saveConfig.apiKey) {
+      await upsertSwarmConfig({ scope: "global", key: "EMBEDDING_MODEL", value: change.model });
+      if (change.apiKey) {
         await upsertSwarmConfig({
           scope: "global",
           key: "EMBEDDING_API_KEY",
-          value: saveConfig.apiKey,
+          value: change.apiKey,
           isSecret: true,
         });
       }
+      for (const { key, value } of change.prefixes) {
+        if (value === null) await deleteSwarmConfigByKey("global", null, key);
+        else await upsertSwarmConfig({ scope: "global", key, value });
+      }
+    } else if (change?.kind === "restore") {
+      for (const key of EMBEDDING_CONFIG_KEYS) await deleteSwarmConfigByKey("global", null, key);
     }
 
     if (result.ok) {
@@ -676,7 +786,7 @@ export async function updateOnboardingMemory(
 
     if (dirty) await persistState(loaded.state);
     queueTelemetry(events);
-    return saveConfig !== undefined;
+    return change !== undefined;
   });
 }
 

package/src/be/rbac-roles.ts

@@ -38,6 +38,9 @@ export const BUILTIN_ROLES = [
       "favorite.write.own",
       "session.share",
       "session.presence",
+      "task.steer.own",
+      "comb.presence",
+      "fs.join.own",
     ],
   },
   {
@@ -46,7 +49,7 @@ export const BUILTIN_ROLES = [
     description: "Read-only: no task, approval or script writes.",
     isBuiltin: true,
     grantsAll: false,
-    verbs: ["favorite.write.own", "session.presence"],
+    verbs: ["favorite.write.own", "session.presence", "comb.presence", "fs.join.own"],
   },
 ] satisfies (BuiltinRoleDefinition & { isBuiltin: true })[];
 

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

@@ -26,6 +26,7 @@ type ScriptRow = {
   isScratch: number;
   typeChecked: number;
   fsMode: "none" | "workspace-rw";
+  executor: "native" | "quickjs" | null;
   createdByAgentId: string | null;
   createdAt: string;
   updatedAt: string;
@@ -37,6 +38,7 @@ function toScriptRecord(row: ScriptRow) {
     scopeId: row.scopeId ?? null,
     isScratch: row.isScratch === 1,
     typeChecked: row.typeChecked === 1,
+    executor: row.executor ?? null,
     createdByAgentId: row.createdByAgentId ?? null,
   };
 }

package/src/be/scripts/db.ts

@@ -3,6 +3,7 @@ import type {
   ScriptApiAuthMode,
   ScriptApiRecord,
   ScriptApiWithSecret,
+  ScriptExecutorName,
   ScriptFsMode,
   ScriptRecord,
   ScriptScope,
@@ -36,6 +37,7 @@ type ScriptWriteArgs = ScriptIdentity & {
   isScratch?: boolean;
   typeChecked?: boolean;
   fsMode?: ScriptFsMode;
+  executor?: ScriptExecutorName | null;
   agentId?: string | null;
   changeReason?: string | null;
   embeddingMode?: "sync" | "skip";
@@ -62,6 +64,7 @@ function rowToScript(row: ScriptRow): ScriptRecord {
     scopeId: row.scopeId ?? null,
     isScratch: row.isScratch === 1,
     typeChecked: row.typeChecked === 1,
+    executor: row.executor ?? null,
     createdByAgentId: row.createdByAgentId ?? null,
   };
 }
@@ -113,6 +116,7 @@ export async function insertScript(args: ScriptWriteArgs): Promise<ScriptRecord>
   const scopeId = normalizeScopeId(args.scope, args.scopeId);
   const contentHash = computeContentHash(args.source);
   const fsMode = args.fsMode ?? "none";
+  const executor = args.executor ?? null;
   const isScratch = args.isScratch ? 1 : 0;
   const typeChecked = args.typeChecked ? 1 : 0;
 
@@ -120,10 +124,10 @@ export async function insertScript(args: ScriptWriteArgs): Promise<ScriptRecord>
     const row = await tx.get<ScriptRow>(
       `INSERT INTO scripts (
           id, "key", name, scope, scopeId, source, description, intent, signatureJson,
-          argsJsonSchema, contentHash, isScratch, typeChecked, fsMode, createdByAgentId, createdAt, updatedAt,
+          argsJsonSchema, contentHash, isScratch, typeChecked, fsMode, executor, createdByAgentId, createdAt, updatedAt,
           created_by, updated_by
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         RETURNING *`,
       [
         id,
@@ -140,6 +144,7 @@ export async function insertScript(args: ScriptWriteArgs): Promise<ScriptRecord>
         isScratch,
         typeChecked,
         fsMode,
+        executor,
         args.agentId ?? null,
         now,
         now,
@@ -189,6 +194,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
   const contentHash = computeContentHash(args.source);
   if (existing.contentHash === contentHash) {
     const fsMode = args.fsMode ?? existing.fsMode;
+    const executor = args.executor !== undefined ? args.executor : existing.executor;
     const isScratch = args.isScratch ?? existing.isScratch;
     const typeChecked = args.typeChecked ?? existing.typeChecked;
     const argsJsonSchema =
@@ -206,6 +212,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
       isScratch;
     if (
       fsMode !== existing.fsMode ||
+      executor !== existing.executor ||
       isScratch !== existing.isScratch ||
       typeChecked !== existing.typeChecked ||
       trackedMetadataChanged ||
@@ -214,7 +221,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
       const row = await getDbClient().get<ScriptRow>(
         `UPDATE scripts
         SET description = ?, intent = ?, signatureJson = ?, argsJsonSchema = ?,
-          isScratch = ?, typeChecked = ?, fsMode = ?, updatedAt = ?, updated_by = ?
+          isScratch = ?, typeChecked = ?, fsMode = ?, executor = ?, updatedAt = ?, updated_by = ?
         WHERE id = ?
         RETURNING *`,
         [
@@ -225,6 +232,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
           isScratch ? 1 : 0,
           typeChecked ? 1 : 0,
           fsMode,
+          executor ?? null,
           new Date().toISOString(),
           args.createdBy ?? null,
           existing.id,
@@ -253,6 +261,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
   const now = new Date().toISOString();
   const newVersion = existing.version + 1;
   const fsMode = args.fsMode ?? existing.fsMode;
+  const executor = args.executor !== undefined ? args.executor : existing.executor;
   const isScratch = args.isScratch ?? existing.isScratch;
   const typeChecked = args.typeChecked ?? existing.typeChecked;
   const argsJsonSchema =
@@ -262,7 +271,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
     const row = await tx.get<ScriptRow>(
       `UPDATE scripts
         SET source = ?, description = ?, intent = ?, signatureJson = ?, argsJsonSchema = ?,
-          contentHash = ?, version = ?, isScratch = ?, typeChecked = ?, fsMode = ?, updatedAt = ?, updated_by = ?
+          contentHash = ?, version = ?, isScratch = ?, typeChecked = ?, fsMode = ?, executor = ?, updatedAt = ?, updated_by = ?
         WHERE id = ?
         RETURNING *`,
       [
@@ -276,6 +285,7 @@ export async function upsertScriptByName(args: ScriptWriteArgs): Promise<UpsertS
         isScratch ? 1 : 0,
         typeChecked ? 1 : 0,
         fsMode,
+        executor ?? null,
         now,
         args.createdBy ?? null,
         existing.id,

package/src/be/scripts/embeddings.ts

@@ -28,6 +28,7 @@ type ScriptEmbeddingCandidateRow = ScriptEmbeddingRow & {
   isScratch: number;
   typeChecked: number;
   fsMode: "none" | "workspace-rw";
+  executor: "native" | "quickjs" | null;
   createdByAgentId: string | null;
   createdAt: string;
   updatedAt: string;
@@ -70,6 +71,7 @@ function rowToScript(row: ScriptEmbeddingCandidateRow): ScriptRecord {
     isScratch: row.isScratch === 1,
     typeChecked: row.typeChecked === 1,
     fsMode: row.fsMode,
+    executor: row.executor ?? null,
     createdByAgentId: row.createdByAgentId ?? null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
@@ -79,7 +81,7 @@ function rowToScript(row: ScriptEmbeddingCandidateRow): ScriptRecord {
 export async function embedScript(script: ScriptRecord): Promise<void> {
   const text = scriptEmbeddingText(script);
   const provider = embeddingProvider();
-  const embedding = await provider.embed(text);
+  const embedding = await provider.embed(text, { kind: "document" });
   if (!embedding) return;
 
   if (embedding.length !== provider.dimensions) {
@@ -205,7 +207,7 @@ export async function searchScripts(args: {
   limit?: number;
 }): Promise<ScriptSearchResult[]> {
   const provider = embeddingProvider();
-  const queryEmbedding = await provider.embed(args.query);
+  const queryEmbedding = await provider.embed(args.query, { kind: "query" });
   if (!queryEmbedding) return lexicalFallback(args);
 
   const candidates = await candidateRows(args.scope, args.scopeId);

package/src/be/scripts/run-saved.ts

@@ -50,6 +50,7 @@ export async function runSavedScriptAsAgent(
         source: args.script.source,
         args: args.input,
         fsMode: args.script.fsMode,
+        executor: args.script.executor,
         agentId: args.agentId,
         egressSecrets: credentials.egressSecrets,
         failedBindings: credentials.failedBindings,

package/src/be/scripts/typecheck.ts

@@ -33,6 +33,7 @@ export const SCRIPT_SDK_TYPES = `
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type ScriptScope = "agent" | "global";
 export type ScriptFsMode = "none" | "workspace-rw";
+export type ScriptExecutorName = "native" | "quickjs";
 export type ScriptApiRawOptions = { raw: true };
 export type ScriptApiDefaultOptions = { raw?: false };
 export type RoutingReason = "skill" | "continuity" | "overflow" | "human_pinned" | "reroute_fault";
@@ -224,7 +225,7 @@ export interface SwarmSdk {
   schedule_list(args?: { enabled?: boolean; name?: string; scheduleType?: "recurring" | "one_time"; targetType?: "agent-task" | "workflow" | "script"; workflowId?: string; scriptName?: string; hideCompleted?: boolean; consecutiveErrorsMin?: number; lastRunStatus?: "failed" | "succeeded"; includeFull?: boolean }): Promise<unknown>;
   // --- scripts ---
   script_search(args: { query?: string; scope?: ScriptScope; limit?: number }): Promise<unknown>;
-  script_run(args: { name?: string; source?: string; args?: unknown; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode; idempotencyKey?: string }): Promise<unknown>;
+  script_run(args: { name?: string; source?: string; args?: unknown; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode; executor?: ScriptExecutorName | null; idempotencyKey?: string }): Promise<unknown>;
   // --- swarm / agent ---
   swarm_get(args?: { includeFull?: boolean }): Promise<unknown>;
   agent_info(args?: Record<string, unknown>): Promise<unknown>;
@@ -341,7 +342,12 @@ export interface SwarmSdk {
   workflow_patch(args: Record<string, unknown>): Promise<unknown>;
   workflow_patchNode(args: Record<string, unknown>): Promise<unknown>;
   workflow_delete(args: { id: string }): Promise<unknown>;
-  workflow_trigger(args: { id: string; triggerData?: Record<string, unknown> }): Promise<unknown>;
+  workflow_trigger(args: {
+    id: string;
+    triggerData?: Record<string, unknown>;
+    wait?: boolean;
+    idempotencyKey?: string;
+  }): Promise<unknown>;
   workflow_retryRun(args: { id: string }): Promise<unknown>;
   workflow_cancelRun(args: { id: string }): Promise<unknown>;
 
@@ -351,7 +357,7 @@ export interface SwarmSdk {
   prompt_preview(args: Record<string, unknown>): Promise<unknown>;
 
   // --- write: scripts ---
-  script_upsert(args: { name: string; source: string; description?: string; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode }): Promise<unknown>;
+  script_upsert(args: { name: string; source: string; description?: string; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode; executor?: ScriptExecutorName | null }): Promise<unknown>;
   script_delete(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
   script_queryTypes(args: { name: string; scope?: ScriptScope }): Promise<unknown>;
   script_launchRun(args: { source: string; args?: unknown; idempotencyKey?: string; scriptName?: string; requestedByUserId?: string }): Promise<unknown>;