@desplega.ai/agent-swarm 1.87.0 → 1.88.0

package/src/be/seed/registry.ts

@@ -3,14 +3,15 @@
  *
  * To make a new entity kind seedable: implement a `Seeder`, add it here, done.
  * The harness ({@link ./runner}) and the boot/CLI entry points pick it up
- * automatically. Scripts is the only kind today.
+ * automatically.
  */
 
 import { scriptsSeeder } from "../seed-scripts";
+import { skillsSeeder } from "../seed-skills";
 import { runSeeders } from "./runner";
 import type { Seeder, SeederResult } from "./types";
 
-export const SEEDERS: Seeder[] = [scriptsSeeder];
+export const SEEDERS: Seeder[] = [scriptsSeeder, skillsSeeder];
 
 /** Apply every registered seeder. Called at API boot and by the seed CLI. */
 export function runAllSeeders(opts?: { quiet?: boolean }): Promise<SeederResult[]> {

package/src/be/seed-skills/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Built-in swarm skills catalog.
+ *
+ * Skill templates live under `templates/skills/<name>/`. Entries with
+ * `runAllSeedersCandidate: true` are seeded into the DB at swarm scope and are
+ * versioned by the generic seeder harness, so pristine built-ins update while
+ * user-modified skills are preserved.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import artifactsConfig from "../../../templates/skills/artifacts/config.json" with { type: "text" };
+import artifactsContent from "../../../templates/skills/artifacts/content.md" with { type: "text" };
+import kvStorageConfig from "../../../templates/skills/kv-storage/config.json" with {
+  type: "text",
+};
+import kvStorageContent from "../../../templates/skills/kv-storage/content.md" with {
+  type: "text",
+};
+import pagesConfig from "../../../templates/skills/pages/config.json" with { type: "text" };
+import pagesContent from "../../../templates/skills/pages/content.md" with { type: "text" };
+import scheduledTaskResilienceConfig from "../../../templates/skills/scheduled-task-resilience/config.json" with {
+  type: "text",
+};
+import scheduledTaskResilienceContent from "../../../templates/skills/scheduled-task-resilience/content.md" with {
+  type: "text",
+};
+import swarmScriptsConfig from "../../../templates/skills/swarm-scripts/config.json" with {
+  type: "text",
+};
+import swarmScriptsContent from "../../../templates/skills/swarm-scripts/content.md" with {
+  type: "text",
+};
+import workflowIterateConfig from "../../../templates/skills/workflow-iterate/config.json" with {
+  type: "text",
+};
+import workflowIterateContent from "../../../templates/skills/workflow-iterate/content.md" with {
+  type: "text",
+};
+import workflowStructuredOutputConfig from "../../../templates/skills/workflow-structured-output/config.json" with {
+  type: "text",
+};
+import workflowStructuredOutputContent from "../../../templates/skills/workflow-structured-output/content.md" with {
+  type: "text",
+};
+import { computeContentHash, createSkill, getSkillByName, updateSkill } from "../db";
+import type { Seeder, SeedItem } from "../seed/types";
+
+type SkillTemplateConfig = {
+  name: string;
+  description: string;
+  runAllSeedersCandidate?: boolean;
+  systemDefault?: boolean;
+};
+
+export type SeedSkill = {
+  name: string;
+  description: string;
+  content: string;
+  systemDefault: boolean;
+};
+
+const BUILT_IN_SKILL_SOURCES = [
+  { config: artifactsConfig, body: artifactsContent },
+  { config: kvStorageConfig, body: kvStorageContent },
+  { config: pagesConfig, body: pagesContent },
+  { config: scheduledTaskResilienceConfig, body: scheduledTaskResilienceContent },
+  { config: swarmScriptsConfig, body: swarmScriptsContent },
+  { config: workflowIterateConfig, body: workflowIterateContent },
+  { config: workflowStructuredOutputConfig, body: workflowStructuredOutputContent },
+];
+
+function buildSkillContent(config: SkillTemplateConfig, body: string): string {
+  return `---\nname: ${config.name}\ndescription: ${config.description}\n---\n\n${body.trim()}\n`;
+}
+
+function skillSeedHash(content: string, systemDefault: boolean): string {
+  return computeContentHash(`${content}\n\n# seed:systemDefault=${systemDefault ? "1" : "0"}\n`);
+}
+
+function seedSkillFromSource(
+  configRaw: string | SkillTemplateConfig,
+  body: string,
+): SeedSkill | null {
+  const config =
+    typeof configRaw === "string" ? (JSON.parse(configRaw) as SkillTemplateConfig) : configRaw;
+  if (!config.runAllSeedersCandidate) return null;
+  return {
+    name: config.name,
+    description: config.description,
+    content: buildSkillContent(config, body),
+    systemDefault: config.systemDefault === true,
+  };
+}
+
+export function loadSeedSkills(templatesDir?: string): SeedSkill[] {
+  if (!templatesDir) {
+    return BUILT_IN_SKILL_SOURCES.map(({ config, body }) => seedSkillFromSource(config, body))
+      .filter((skill): skill is SeedSkill => skill !== null)
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  if (!existsSync(templatesDir)) return [];
+
+  const skills: SeedSkill[] = [];
+  for (const entry of readdirSync(templatesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const dir = join(templatesDir, entry.name);
+    const configPath = join(dir, "config.json");
+    const contentPath = join(dir, "content.md");
+    if (!existsSync(configPath) || !existsSync(contentPath)) continue;
+
+    const config = JSON.parse(readFileSync(configPath, "utf-8")) as SkillTemplateConfig;
+    if (!config.runAllSeedersCandidate) continue;
+
+    const body = readFileSync(contentPath, "utf-8");
+    skills.push({
+      name: config.name,
+      description: config.description,
+      content: buildSkillContent(config, body),
+      systemDefault: config.systemDefault === true,
+    });
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+type SkillSeedItem = SeedItem & { skill: SeedSkill };
+
+export const skillsSeeder: Seeder<SkillSeedItem> = {
+  kind: "skill",
+
+  items(): SkillSeedItem[] {
+    return loadSeedSkills().map((skill) => ({
+      key: skill.name,
+      contentHash: skillSeedHash(skill.content, skill.systemDefault),
+      skill,
+    }));
+  },
+
+  upstreamHash(item): string | null {
+    const existing = getSkillByName(item.key, "swarm");
+    return existing ? skillSeedHash(existing.content, existing.systemDefault) : null;
+  },
+
+  apply(item): void {
+    const { skill } = item;
+    const existing = getSkillByName(skill.name, "swarm");
+
+    if (existing) {
+      updateSkill(existing.id, {
+        name: skill.name,
+        description: skill.description,
+        content: skill.content,
+        scope: "swarm",
+        systemDefault: skill.systemDefault,
+      });
+      return;
+    }
+
+    createSkill({
+      name: skill.name,
+      description: skill.description,
+      content: skill.content,
+      type: "personal",
+      scope: "swarm",
+      ownerAgentId: undefined,
+      systemDefault: skill.systemDefault,
+    });
+  },
+};

package/src/cli.tsx

@@ -303,14 +303,43 @@ const COMMAND_HELP: Record<
       "  unpublish-template <template...>     Make E2B templates private",
       "  start-api --template <name>          Start the API in an E2B sandbox",
       "  start-worker --api-url <url>         Start a worker against a public API URL",
-      "  start-stack                         Start API plus one or more workers",
-      "  list | kill <sandbox-id...>          Inspect or clean up sandboxes",
-      "  -h, --help                          Show this help",
+      "  start-stack                          Start API + lead + N workers (wizard on a TTY)",
+      "  list                                 List dispatcher sandboxes",
+      "  swarms list|info|kill|add|logs       Group/inspect/teardown/grow/tail swarms by slug",
+      "  extend <sandbox-id...>               Extend a sandbox TTL (--timeout-sec <s>)",
+      "  kill <sandbox-id...> | --all         Clean up sandboxes (--all sweeps the fleet)",
+      "",
+      "  swarms options:",
+      "  swarms list                          Group sandboxes by metadata.swarm slug",
+      "  swarms info <slug>                   API URL, key source (masked), roles, TTL, health",
+      "  swarms kill <slug> | --all           Tear down a swarm (API last), or every swarm",
+      "  swarms add <slug> [--workers <n>]    Add worker(s)/--add-lead to an existing swarm",
+      "  swarms logs <slug> [--role r]        Stream a sandbox entrypoint log (--follow to tail)",
+      "  --reveal-key                         Embed the swarm key in the dashboard deep-link (raw)",
+      "",
+      "  start-stack options:",
+      "  --swarm <slug>                       Swarm name/slug (wizard + echoed one-shot command)",
+      "  --workers <n>                        Worker count (default 1)",
+      "  --no-lead                            Legacy topology: API + N workers, no lead",
+      "  --lead-agent-id <id>                 Lead agent ID (default e2b-lead-<sandbox-id>)",
+      "  --yes / --non-interactive            Skip the wizard; use flags + defaults (headless)",
+      "  --integrations <csv>                 Allowlist of integrations to keep on",
+      "  --no-slack|github|jira|linear        Disable an integration (sets API <NAME>_DISABLE)",
+      "",
+      "  --provider <name>                    Harness provider for workers (default claude)",
+      "  --timeout-sec <s>                    Sandbox TTL (default 3600)",
+      "  --env-file / --secret                Shared env/secrets applied to all roles (repeatable)",
+      "  --<api|lead|worker>-env-file <path>  Role-scoped env file, layers on the shared one (repeatable)",
+      "  --<api|lead|worker>-secret KEY=VAL   Role-scoped secret, layers on the shared one (repeatable)",
+      "  --json                               Machine-readable output",
+      "  --dry-run                            Derive planned work without touching E2B",
+      "  -h, --help                           Show this help",
     ].join("\n"),
     examples: [
       `  ${binName} e2b build-template --role worker`,
       `  ${binName} e2b start-worker --api-url https://swarm.example.com --api-key "$SWARM_API_KEY"`,
-      `  ${binName} e2b start-stack --workers 2 --api-key "$SWARM_API_KEY"`,
+      `  ${binName} e2b start-stack --yes --swarm demo --workers 2 --api-key "$SWARM_API_KEY"`,
+      `  ${binName} e2b start-stack --yes --no-lead --workers 2 --swarm demo`,
     ].join("\n"),
   },
 };

package/src/commands/e2b-stack-wizard.tsx

@@ -0,0 +1,394 @@
+import { Select, TextInput } from "@inkjs/ui";
+import { Box, Text, useApp } from "ink";
+import { useState } from "react";
+
+/**
+ * Interactive wizard for `e2b start-stack`. Collects the handful of decisions an
+ * operator makes when launching a swarm (name → slug, worker count, provider,
+ * TTL, env files, integrations), skipping any step whose flag was already
+ * provided on the command line. On finish it resolves a {@link StackWizardResult}
+ * back to the caller, which translates it into flags and (optionally) echoes the
+ * equivalent headless `--yes` command.
+ *
+ * Consistency with `onboard*.tsx`: Ink + `@inkjs/ui` `Select`/`TextInput`,
+ * one logical question per render, `useApp().exit()` to tear down on completion.
+ *
+ * Headless detection lives in the caller (`e2b.ts`) — this component is only
+ * ever rendered when interactive, so it always reads from stdin.
+ */
+
+/** Integrations the wizard can toggle. Each maps to an API-side `*_DISABLE` env. */
+export const STACK_INTEGRATIONS = ["slack", "github", "jira", "linear"] as const;
+export type StackIntegration = (typeof STACK_INTEGRATIONS)[number];
+
+/** Provider choices surfaced in the wizard picker (mirrors HARNESS_PROVIDER). */
+export const STACK_PROVIDERS = ["claude", "codex", "pi", "devin"] as const;
+
+export const DEFAULT_STACK_WORKERS = 1;
+export const DEFAULT_STACK_TIMEOUT_SEC = 3600;
+
+/**
+ * The shape the wizard resolves. `undefined` fields mean "the operator did not
+ * change the prebaked flag/default" — the caller already has the flag value, so
+ * it only overrides with wizard answers that were actually collected.
+ */
+export type StackWizardResult = {
+  swarmSlug: string;
+  workers: number;
+  provider: string;
+  timeoutSec: number;
+  /** Shared --env-file paths the operator typed (comma/space separated → array). */
+  envFiles: string[];
+  /** Map of integration → enabled. A disabled integration becomes `*_DISABLE=true`. */
+  integrations: Record<StackIntegration, boolean>;
+  noLead: boolean;
+};
+
+/** Which wizard steps to skip because their value already came from a flag. */
+export type StackWizardSkips = {
+  swarm?: boolean;
+  workers?: boolean;
+  provider?: boolean;
+  timeout?: boolean;
+  envFiles?: boolean;
+  integrations?: boolean;
+};
+
+export type StackWizardDefaults = {
+  swarmSlug?: string;
+  workers: number;
+  provider: string;
+  timeoutSec: number;
+  envFiles: string[];
+  integrations: Record<StackIntegration, boolean>;
+  noLead: boolean;
+};
+
+export type StackWizardProps = {
+  defaults: StackWizardDefaults;
+  skips: StackWizardSkips;
+  onComplete: (result: StackWizardResult) => void;
+};
+
+/** Lowercase, dash-separated slug suitable for a swarm name / metadata value. */
+export function slugify(input: string): string {
+  return (
+    input
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 48) || "swarm"
+  );
+}
+
+/** Human preview of when a TTL of `seconds` from now would expire. */
+function expiryPreview(seconds: number): string {
+  const expires = new Date(Date.now() + seconds * 1000);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const parts: string[] = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0 || hours === 0) parts.push(`${minutes}m`);
+  return `${parts.join(" ")} from now (~${expires.toLocaleTimeString()})`;
+}
+
+type WizardStep =
+  | "mode"
+  | "swarm"
+  | "workers"
+  | "provider"
+  | "timeout"
+  | "env_files"
+  | "integrations"
+  | "done";
+
+export function StackWizard({ defaults, skips, onComplete }: StackWizardProps) {
+  const { exit } = useApp();
+
+  // Accumulated answers, seeded from the flag-provided defaults.
+  const [result, setResult] = useState<StackWizardResult>({
+    swarmSlug: defaults.swarmSlug ?? "",
+    workers: defaults.workers,
+    provider: defaults.provider,
+    timeoutSec: defaults.timeoutSec,
+    envFiles: defaults.envFiles,
+    integrations: { ...defaults.integrations },
+    noLead: defaults.noLead,
+  });
+
+  // Determine the ordered list of steps, skipping any that are flag-satisfied.
+  const steps: WizardStep[] = ["mode"];
+  if (!skips.swarm) steps.push("swarm");
+  if (!skips.workers) steps.push("workers");
+  if (!skips.provider) steps.push("provider");
+  if (!skips.timeout) steps.push("timeout");
+  if (!skips.envFiles) steps.push("env_files");
+  if (!skips.integrations) steps.push("integrations");
+  steps.push("done");
+
+  const [stepIdx, setStepIdx] = useState(0);
+  const step = steps[stepIdx] ?? "done";
+  const [error, setError] = useState("");
+  // Toggle scratch state for the integrations multi-step.
+  const [integrationToggles, setIntegrationToggles] = useState<Record<StackIntegration, boolean>>({
+    ...defaults.integrations,
+  });
+
+  const advance = (partial?: Partial<StackWizardResult>) => {
+    setError("");
+    if (partial) setResult((r) => ({ ...r, ...partial }));
+    const nextIdx = stepIdx + 1;
+    setStepIdx(nextIdx);
+    if ((steps[nextIdx] ?? "done") === "done") {
+      // Resolve on the freshest result; merge any pending partial.
+      setResult((r) => {
+        const finalResult = { ...r, ...partial };
+        // Defer the callback so React finishes its commit before we exit.
+        queueMicrotask(() => {
+          onComplete(finalResult);
+          exit();
+        });
+        return finalResult;
+      });
+    }
+  };
+
+  if (step === "done") {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Text color="green">Configuration captured — launching…</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="cyan" bold>
+        Agent Swarm — E2B stack launcher
+      </Text>
+      {error && (
+        <Box marginTop={1}>
+          <Text color="red">{error}</Text>
+        </Box>
+      )}
+
+      {step === "mode" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>Create a new swarm or add to an existing one?</Text>
+          <Box marginTop={1}>
+            <Select
+              options={[
+                { label: "Create a new swarm", value: "create" },
+                // Phase 4: the add-to-existing flow lives in the standalone
+                // `e2b swarms add` command, which has its own TTY swarm picker,
+                // `--workers`/`--add-lead` flags, and TTL re-sync to the group's
+                // end. Rather than fork that whole flow into this wizard (which
+                // is scoped to *creating* a stack), we point the operator at it.
+                // This keeps a single, fully-working add path instead of a
+                // half-duplicated one.
+                { label: "Add to an existing swarm (run: e2b swarms add <slug>)", value: "add" },
+              ]}
+              onChange={(value) => {
+                if (value === "add") {
+                  setError(
+                    "To add to an existing swarm, exit and run: e2b swarms add <slug> " +
+                      "(no slug → it lists your swarms to pick from). Choose 'Create a new swarm' to continue here.",
+                  );
+                  return;
+                }
+                advance();
+              }}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "swarm" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>Swarm name:</Text>
+          <Text dimColor>Used as the group slug and dashboard name.</Text>
+          <Box marginTop={1}>
+            <TextInput
+              key="swarm-name"
+              placeholder="my-swarm"
+              defaultValue={result.swarmSlug}
+              onSubmit={(raw) => {
+                const slug = slugify(raw || "swarm");
+                advance({ swarmSlug: slug });
+              }}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "workers" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>How many workers?</Text>
+          <Box marginTop={1}>
+            <TextInput
+              key="workers"
+              placeholder={String(result.workers)}
+              defaultValue={String(result.workers)}
+              onSubmit={(raw) => {
+                const trimmed = raw.trim();
+                const parsed = trimmed ? Number.parseInt(trimmed, 10) : result.workers;
+                // Keep this in lock-step with the headless `integerFlag("workers")`
+                // contract, which requires a positive integer.
+                if (!Number.isFinite(parsed) || parsed < 1) {
+                  setError("Enter a positive integer (at least 1 worker).");
+                  return;
+                }
+                advance({ workers: parsed });
+              }}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "provider" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>Harness provider:</Text>
+          <Box marginTop={1}>
+            <Select
+              options={STACK_PROVIDERS.map((p) => ({ label: p, value: p }))}
+              onChange={(value) => advance({ provider: value })}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "timeout" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>Sandbox TTL (seconds):</Text>
+          <Text dimColor>
+            Default {result.timeoutSec}s — {expiryPreview(result.timeoutSec)}.
+          </Text>
+          <Box marginTop={1}>
+            <TextInput
+              key="timeout"
+              placeholder={String(result.timeoutSec)}
+              defaultValue={String(result.timeoutSec)}
+              onSubmit={(raw) => {
+                const trimmed = raw.trim();
+                const parsed = trimmed ? Number.parseInt(trimmed, 10) : result.timeoutSec;
+                if (!Number.isFinite(parsed) || parsed <= 0) {
+                  setError("Enter a positive integer (seconds).");
+                  return;
+                }
+                advance({ timeoutSec: parsed });
+              }}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "env_files" && (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>Shared env file(s):</Text>
+          <Text dimColor>Comma-separated paths applied to all roles, or leave blank.</Text>
+          <Box marginTop={1}>
+            <TextInput
+              key="env-files"
+              placeholder=".env"
+              defaultValue={result.envFiles.join(",")}
+              onSubmit={(raw) => {
+                const files = raw
+                  .split(",")
+                  .map((p) => p.trim())
+                  .filter(Boolean);
+                advance({ envFiles: files });
+              }}
+            />
+          </Box>
+        </Box>
+      )}
+
+      {step === "integrations" && (
+        <IntegrationToggleStep
+          toggles={integrationToggles}
+          setToggles={setIntegrationToggles}
+          onContinue={() => advance({ integrations: { ...integrationToggles } })}
+        />
+      )}
+    </Box>
+  );
+}
+
+/**
+ * One-shot picker over existing swarm slugs, used by `e2b swarms add` when no
+ * slug was passed on an interactive TTY. Resolves the chosen slug back to the
+ * caller via `onSelect`, then exits. Consistent with the wizard's Ink + Select.
+ */
+export type SwarmPickerOption = { slug: string; label: string };
+
+export function SwarmPicker({
+  slugs,
+  onSelect,
+}: {
+  slugs: SwarmPickerOption[];
+  onSelect: (slug: string) => void;
+}) {
+  const { exit } = useApp();
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="cyan" bold>
+        Add to which swarm?
+      </Text>
+      <Box marginTop={1}>
+        <Select
+          options={slugs.map((s) => ({ label: s.label, value: s.slug }))}
+          onChange={(value) => {
+            // Defer so React commits before we tear down the Ink instance.
+            queueMicrotask(() => {
+              onSelect(value);
+              exit();
+            });
+          }}
+        />
+      </Box>
+    </Box>
+  );
+}
+
+const CONTINUE_VALUE = "__continue__";
+
+function IntegrationToggleStep({
+  toggles,
+  setToggles,
+  onContinue,
+}: {
+  toggles: Record<StackIntegration, boolean>;
+  setToggles: (
+    update: (prev: Record<StackIntegration, boolean>) => Record<StackIntegration, boolean>,
+  ) => void;
+  onContinue: () => void;
+}) {
+  const options = [
+    ...STACK_INTEGRATIONS.map((key) => ({
+      label: `${toggles[key] ? "[x]" : "[ ]"} ${key}`,
+      value: key as string,
+    })),
+    { label: "Continue →", value: CONTINUE_VALUE },
+  ];
+
+  return (
+    <Box marginTop={1} flexDirection="column">
+      <Text bold>Integrations (enabled = on):</Text>
+      <Text dimColor>Disabled integrations set the matching *_DISABLE env on the API.</Text>
+      <Box marginTop={1}>
+        <Select
+          options={options}
+          onChange={(value) => {
+            if (value === CONTINUE_VALUE) {
+              onContinue();
+              return;
+            }
+            const key = value as StackIntegration;
+            setToggles((prev) => ({ ...prev, [key]: !prev[key] }));
+          }}
+        />
+      </Box>
+    </Box>
+  );
+}