@desplega.ai/agent-swarm 1.167.0 → 1.168.0

package/src/scheduler/scheduler.ts

@@ -15,6 +15,7 @@ import {
   getUserById,
   getWorkflow,
   getWorkflowRun,
+  recordInlineScriptRun,
   type UpdateScheduledTaskData,
   updateScheduledTask,
 } from "@/be/db";
@@ -32,6 +33,7 @@ import { startWorkflowExecution } from "@/workflows/engine";
 import type { ExecutorRegistry } from "@/workflows/executors/registry";
 import { handleScheduleTrigger } from "@/workflows/triggers";
 import { ensure } from "../utils/business-use";
+import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 
 import {
   dispatchDeferredTaskWait,
@@ -83,23 +85,90 @@ async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
   }
 
   const agentId = schedule.createdByAgentId ?? "schedule";
-  const output = await runScript({
-    source: script.source,
-    args: schedule.scriptArgs ?? {},
-    fsMode: "none",
+  const args = schedule.scriptArgs ?? {};
+  const record = {
     agentId,
-    egressSecrets: await buildScriptCredentialBindings({ agentId }),
-    apiConnections: getScriptApiConnectionDescriptors({ agentId }),
-    mcpConnections: getScriptMcpConnectionDescriptors({ agentId }),
-    timeoutMs: 60_000,
-  });
+    scriptName: schedule.scriptName,
+    // A pointer, not a copy: script schedules fire as often as every minute and
+    // script_runs has no retention sweep, so copying the source on every fire
+    // would grow the table by tens of MB a day. script_versions keeps the text.
+    source: `// Scheduled run of '${script.name}' v${script.version} (global, contentHash ${script.contentHash}) by schedule '${schedule.name}'.\n// Full source: script_versions row for this version.\n`,
+    args,
+    startedAt: new Date().toISOString(),
+  };
+
+  let output: Awaited<ReturnType<typeof runScript>>;
+  try {
+    output = await runScript({
+      source: script.source,
+      args,
+      fsMode: "none",
+      agentId,
+      egressSecrets: await buildScriptCredentialBindings({ agentId }),
+      apiConnections: getScriptApiConnectionDescriptors({ agentId }),
+      mcpConnections: getScriptMcpConnectionDescriptors({ agentId }),
+      timeoutMs: 60_000,
+    });
+  } catch (err) {
+    await recordScheduleScriptRun({
+      ...record,
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  }
 
   if (output.exitCode !== 0 || output.error) {
-    throw new Error(
+    const message =
       output.stderr ||
-        `Script '${schedule.scriptName}' exited with code ${output.exitCode}${
-          output.error ? ` (${output.error})` : ""
-        }`,
+      `Script '${schedule.scriptName}' exited with code ${output.exitCode}${
+        output.error ? ` (${output.error})` : ""
+      }`;
+    await recordScheduleScriptRun({
+      ...record,
+      status: "failed",
+      output: output.result,
+      error: message,
+    });
+    throw new Error(message);
+  }
+
+  await recordScheduleScriptRun({ ...record, status: "completed", output: output.result });
+}
+
+/**
+ * Persist a scheduled script fire as a terminal `script_runs` row, so script
+ * audits see schedule-driven runs the same way as POST /api/scripts/run.
+ * Best effort: a persistence error never changes the schedule's outcome.
+ */
+async function recordScheduleScriptRun(run: {
+  agentId: string;
+  scriptName: string;
+  source: string;
+  args: unknown;
+  startedAt: string;
+  status: "completed" | "failed";
+  output?: unknown;
+  error?: string;
+}): Promise<void> {
+  try {
+    await recordInlineScriptRun({
+      id: crypto.randomUUID(),
+      agentId: run.agentId,
+      scriptName: run.scriptName,
+      source: run.source,
+      args: scrubObject(run.args),
+      status: run.status,
+      output: scrubObject(run.output),
+      error: run.error === undefined ? undefined : scrubSecrets(run.error),
+      startedAt: run.startedAt,
+      finishedAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    console.warn(
+      `[scheduler] could not record script run for '${run.scriptName}': ${scrubSecrets(
+        err instanceof Error ? err.message : String(err),
+      )}`,
     );
   }
 }

package/src/scripts-runtime/executors/registry.ts

@@ -8,7 +8,7 @@ const EXECUTORS: Record<string, () => ScriptExecutor> = {
 };
 
 export function getScriptExecutor(name = process.env.SCRIPT_EXECUTOR ?? "native"): ScriptExecutor {
-  const factory = EXECUTORS[name];
+  const factory = EXECUTORS[name.trim()];
   if (!factory) {
     throw new Error(
       `Unknown SCRIPT_EXECUTOR: ${name}. Available: ${Object.keys(EXECUTORS).join(", ")}`,

package/src/tests/claude-background-keepalive-wiring.test.ts

@@ -0,0 +1,220 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { appendFile, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ClaudeAdapter } from "../providers/claude-adapter";
+import { BACKGROUND_KEEPALIVE_INTERVAL_MS } from "../providers/claude-background-keepalive";
+import type { ProviderResult, ProviderSession, ProviderSessionConfig } from "../providers/types";
+import { CHILD_PROCESS_TEST_BUDGET_MS } from "./test-proc";
+
+// These tests go through ClaudeAdapter.createSession, so they cover the wiring
+// in each transport: observe() on every parsed message and stop() at teardown.
+// A fake Claude binary ends its turn and goes silent; a local server records the
+// session heartbeats the keepalive sends while it waits.
+
+const fixturePath = join(import.meta.dir, "claude-background-keepalive.fixture.ts");
+const TICK_MS = 20;
+
+// The keepalive pings every 60s. Run its interval at TICK_MS instead; every
+// other timer keeps its real period.
+const realSetInterval = globalThis.setInterval;
+beforeAll(() => {
+  globalThis.setInterval = ((handler: TimerHandler, timeout?: number, ...rest: unknown[]) =>
+    realSetInterval(
+      handler,
+      timeout === BACKGROUND_KEEPALIVE_INTERVAL_MS ? TICK_MS : timeout,
+      ...rest,
+    )) as typeof setInterval;
+});
+afterAll(() => {
+  globalThis.setInterval = realSetInterval;
+});
+
+const heartbeats = new Map<string, number>();
+const server = Bun.serve({
+  port: 0,
+  fetch(req) {
+    const match = new URL(req.url).pathname.match(/^\/api\/active-sessions\/heartbeat\/(.+)$/);
+    if (req.method === "PUT" && match?.[1]) {
+      const taskId = decodeURIComponent(match[1]);
+      heartbeats.set(taskId, (heartbeats.get(taskId) ?? 0) + 1);
+    }
+    return Response.json({ updated: true });
+  },
+});
+afterAll(() => server.stop(true));
+
+const temporaryDirectories: string[] = [];
+let originalHome: string | undefined;
+
+beforeEach(async () => {
+  // Every session seeds Claude trust into `$HOME/.claude.json`; keep that off the real home.
+  originalHome = process.env.HOME;
+  const home = await mkdtemp(join(tmpdir(), "claude-bg-keepalive-home-"));
+  temporaryDirectories.push(home);
+  process.env.HOME = home;
+});
+
+afterEach(async () => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  await Promise.all(
+    temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+type Transport = "cli" | "sdk";
+
+interface Harness {
+  session: ProviderSession;
+  taskId: string;
+  send(command: "empty" | "exit" | "fail"): Promise<void>;
+  count(): number;
+  completed(): boolean;
+  turnEnded(): Promise<void>;
+}
+
+async function startSession(transport: Transport, withBackgroundTask: boolean): Promise<Harness> {
+  const directory = await mkdtemp(join(tmpdir(), "claude-bg-keepalive-"));
+  temporaryDirectories.push(directory);
+  const controlFile = join(directory, "control");
+  const logFile = join(directory, "session.jsonl");
+  const taskId = crypto.randomUUID();
+  const config: ProviderSessionConfig = {
+    prompt: "wait on the background job",
+    systemPrompt: "",
+    model: "claude-haiku-4-5",
+    role: "worker",
+    agentId: crypto.randomUUID(),
+    taskId,
+    apiUrl: `http://127.0.0.1:${server.port}`,
+    apiKey: "test-key",
+    cwd: directory,
+    logFile,
+    env: {
+      PATH: process.env.PATH ?? "/usr/bin:/bin",
+      CLAUDE_CODE_OAUTH_TOKEN: "example-fixture-oauth-token",
+      CLAUDE_TRANSPORT: transport,
+      CLAUDE_BINARY: `${process.execPath} ${fixturePath}`,
+      BG_FIXTURE_TRANSPORT: transport,
+      BG_FIXTURE_CONTROL: controlFile,
+      BG_FIXTURE_BACKGROUND: withBackgroundTask ? "1" : "0",
+    },
+  };
+  const session = await new ClaudeAdapter(async () => {}).createSession(config);
+  let completed = false;
+  void session.waitForCompletion().finally(() => {
+    completed = true;
+  });
+  return {
+    session,
+    taskId,
+    completed: () => completed,
+    send: (command) => appendFile(controlFile, `${command}\n`),
+    count: () => heartbeats.get(taskId) ?? 0,
+    // Both transports log every protocol line; the result line marks the end of the turn.
+    turnEnded: () =>
+      waitFor(async () => {
+        const file = Bun.file(logFile);
+        return (await file.exists()) && (await file.text()).includes('"type":"result"');
+      }, "the fixture's result message"),
+  };
+}
+
+async function waitFor(
+  condition: () => boolean | Promise<boolean>,
+  what: string,
+  timeoutMs = 5_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!(await condition())) {
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${what}`);
+    await Bun.sleep(TICK_MS / 2);
+  }
+}
+
+/** Waits out in-flight requests, then asserts no further heartbeat arrives. */
+async function expectHeartbeatsStopped(harness: Harness): Promise<void> {
+  await Bun.sleep(TICK_MS * 3);
+  const settled = harness.count();
+  await Bun.sleep(TICK_MS * 8);
+  expect(harness.count()).toBe(settled);
+}
+
+async function liveSessionWithHeartbeats(transport: Transport): Promise<Harness> {
+  const harness = await startSession(transport, true);
+  await harness.turnEnded();
+  // The turn is over and the process is silent; only the keepalive is sending.
+  await waitFor(() => harness.count() >= 3, "keepalive heartbeats after the turn ended");
+  return harness;
+}
+
+describe.each(["cli", "sdk"] as const)("Claude %s transport background keepalive", (transport) => {
+  test(
+    "heartbeats while a background task stays live after the turn ends, and stops when the set empties",
+    async () => {
+      const harness = await liveSessionWithHeartbeats(transport);
+      try {
+        await harness.send("empty");
+        await expectHeartbeatsStopped(harness);
+        // The session is still running: the empty set stopped the pings, not teardown.
+        expect(harness.completed()).toBe(false);
+      } finally {
+        await harness.send("exit");
+        await harness.session.waitForCompletion();
+      }
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "normal end stops the keepalive",
+    async () => {
+      const harness = await liveSessionWithHeartbeats(transport);
+      await harness.send("exit");
+      const result = await harness.session.waitForCompletion();
+      expect(result.isError).toBe(false);
+      await expectHeartbeatsStopped(harness);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "error end stops the keepalive",
+    async () => {
+      const harness = await liveSessionWithHeartbeats(transport);
+      await harness.send("fail");
+      const result: ProviderResult = await harness.session.waitForCompletion();
+      expect(result.exitCode).not.toBe(0);
+      await expectHeartbeatsStopped(harness);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "abort stops the keepalive",
+    async () => {
+      const harness = await liveSessionWithHeartbeats(transport);
+      await harness.session.abort();
+      await harness.session.waitForCompletion();
+      await expectHeartbeatsStopped(harness);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a session with no background work sends no keepalive heartbeats",
+    async () => {
+      const harness = await startSession(transport, false);
+      try {
+        await harness.turnEnded();
+        await Bun.sleep(TICK_MS * 10);
+        expect(harness.count()).toBe(0);
+      } finally {
+        await harness.send("exit");
+        await harness.session.waitForCompletion();
+      }
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+});

package/src/tests/claude-background-keepalive.fixture.ts

@@ -0,0 +1,162 @@
+// Fake Claude binary for the background-keepalive wiring tests. It speaks just
+// enough of both transports: the SDK initialize handshake on stdin, and the
+// stream-json stdout that the CLI and SDK sessions both parse. After one turn it
+// goes silent, the way Claude does while it waits on a background job, until the
+// test steps it through the control file (one command per line).
+const transport = process.env.BG_FIXTURE_TRANSPORT;
+const controlFile = process.env.BG_FIXTURE_CONTROL;
+const withBackgroundTask = process.env.BG_FIXTURE_BACKGROUND === "1";
+const sessionId = "22222222-2222-4222-8222-222222222222";
+
+if (process.argv.includes("--version")) {
+  console.log("2.1.263 (Claude Code)");
+  process.exit(0);
+}
+
+if ((transport !== "cli" && transport !== "sdk") || !controlFile) {
+  console.error("BG_FIXTURE_TRANSPORT (cli|sdk) and BG_FIXTURE_CONTROL are required");
+  process.exit(2);
+}
+
+function writeMessage(message: Record<string, unknown>): void {
+  console.log(JSON.stringify(message));
+}
+
+function backgroundTasksChanged(tasks: Array<Record<string, unknown>>): void {
+  writeMessage({
+    type: "system",
+    subtype: "background_tasks_changed",
+    tasks,
+    uuid: crypto.randomUUID(),
+    session_id: sessionId,
+  });
+}
+
+const usage = {
+  input_tokens: 10,
+  output_tokens: 1,
+  cache_read_input_tokens: 0,
+  cache_creation_input_tokens: 0,
+};
+
+let started = false;
+
+async function runTurn(): Promise<void> {
+  if (started) return;
+  started = true;
+  writeMessage({
+    type: "system",
+    subtype: "init",
+    session_id: sessionId,
+    model: "claude-haiku-4-5",
+    tools: [],
+    mcp_servers: [],
+    plugins: [],
+    permissionMode: "bypassPermissions",
+    slash_commands: [],
+    apiKeySource: "none",
+    cwd: process.cwd(),
+    claude_code_version: "2.1.263",
+    output_style: "default",
+    skills: [],
+    uuid: crypto.randomUUID(),
+  });
+  if (withBackgroundTask) {
+    backgroundTasksChanged([
+      { task_id: "bg-1", task_type: "local_bash", description: "Wait for TLC" },
+    ]);
+  }
+  writeMessage({
+    type: "assistant",
+    message: {
+      id: "message-1",
+      type: "message",
+      role: "assistant",
+      model: "claude-haiku-4-5",
+      content: [{ type: "text", text: "Waiting for the background job to finish." }],
+      stop_reason: "end_turn",
+      stop_sequence: null,
+      usage,
+    },
+    parent_tool_use_id: null,
+    uuid: crypto.randomUUID(),
+    session_id: sessionId,
+  });
+  writeMessage({
+    type: "result",
+    subtype: "success",
+    duration_ms: 1,
+    duration_api_ms: 1,
+    is_error: false,
+    num_turns: 1,
+    result: "Waiting for the background job to finish.",
+    stop_reason: "end_turn",
+    total_cost_usd: 0.001,
+    usage,
+    modelUsage: {},
+    permission_denials: [],
+    queued_turn_count: 0,
+    uuid: crypto.randomUUID(),
+    session_id: sessionId,
+  });
+
+  // Silent from here on, except for what the test asks for.
+  let handled = 0;
+  for (;;) {
+    const file = Bun.file(controlFile as string);
+    const commands = (await file.exists()) ? (await file.text()).split("\n").filter(Boolean) : [];
+    while (handled < commands.length) {
+      const command = commands[handled++];
+      if (command === "empty") backgroundTasksChanged([]);
+      if (command === "exit") process.exit(0);
+      if (command === "fail") {
+        console.error("Error: fixture process crashed");
+        process.exit(1);
+      }
+    }
+    await Bun.sleep(10);
+  }
+}
+
+async function readSdkInput(): Promise<void> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (!line) continue;
+      const message = JSON.parse(line) as {
+        type?: string;
+        request_id?: string;
+        request?: { subtype?: string };
+      };
+      if (message.type === "control_request" && message.request?.subtype === "initialize") {
+        writeMessage({
+          type: "control_response",
+          response: {
+            subtype: "success",
+            request_id: message.request_id ?? "fixture-initialize",
+            response: {
+              commands: [],
+              agents: [],
+              output_style: "default",
+              available_output_styles: [],
+              models: [],
+              account: {},
+            },
+          },
+        });
+      } else if (message.type === "user") {
+        void runTurn();
+      }
+    }
+  }
+}
+
+// The CLI transport passes the prompt with -p; the SDK sends it on stdin.
+if (transport === "sdk") void readSdkInput();
+else await runTurn();

package/src/tests/claude-background-keepalive.test.ts

@@ -0,0 +1,139 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { ClaudeBackgroundKeepalive } from "../providers/claude-background-keepalive";
+
+// The keepalive's contract is the HTTP heartbeat it sends while Claude idles on
+// background work. A local server records those requests; short intervals keep
+// the timing real without fake clocks.
+const INTERVAL_MS = 20;
+// Real timers under CI's parallel load can slip a tick; retry instead of
+// widening every window.
+const TIMING = { retry: 2 };
+const received: Array<{ method: string; path: string; auth: string | null; agent: string | null }> =
+  [];
+const server = Bun.serve({
+  port: 0,
+  fetch(req) {
+    const url = new URL(req.url);
+    received.push({
+      method: req.method,
+      path: url.pathname,
+      auth: req.headers.get("authorization"),
+      agent: req.headers.get("x-agent-id"),
+    });
+    return Response.json({ updated: true });
+  },
+});
+
+afterAll(() => server.stop(true));
+beforeEach(() => {
+  received.length = 0;
+});
+
+function keepalive(maxIdleMs?: number, apiUrl = `http://127.0.0.1:${server.port}`) {
+  return new ClaudeBackgroundKeepalive({
+    apiUrl,
+    apiKey: "key-123",
+    agentId: "agent-1",
+    taskId: "task-1",
+    intervalMs: INTERVAL_MS,
+    maxIdleMs,
+  });
+}
+
+const bgChanged = (tasks: Array<Record<string, unknown>>) => ({
+  type: "system",
+  subtype: "background_tasks_changed",
+  tasks,
+});
+
+describe("ClaudeBackgroundKeepalive", () => {
+  test(
+    "keeps heartbeating after the turn ends while a background Bash job is live",
+    async () => {
+      const k = keepalive();
+      // Message order from the stalled run: the backgrounded Bash joins the set,
+      // the assistant ends its turn, then the process goes silent.
+      k.observe(
+        bgChanged([{ task_id: "bscveebhn", task_type: "local_bash", description: "Wait for TLC" }]),
+      );
+      k.observe({ type: "assistant" });
+      k.observe({ type: "result", subtype: "success" });
+      await Bun.sleep(INTERVAL_MS * 6);
+      k.stop();
+
+      expect(received.length).toBeGreaterThanOrEqual(3);
+      expect(received[0]).toEqual({
+        method: "PUT",
+        path: "/api/active-sessions/heartbeat/task-1",
+        auth: "Bearer key-123",
+        agent: "agent-1",
+      });
+    },
+    TIMING,
+  );
+
+  test(
+    "a silent session with no background work sends nothing, so it still goes stale",
+    async () => {
+      const k = keepalive();
+      k.observe({ type: "assistant" });
+      k.observe({ type: "result", subtype: "success" });
+      // Ambient watchers are not activity either.
+      k.observe(bgChanged([{ task_id: "watcher", ambient: true }]));
+      await Bun.sleep(INTERVAL_MS * 5);
+      k.stop();
+      expect(received).toHaveLength(0);
+    },
+    TIMING,
+  );
+
+  test(
+    "stops when the background set empties",
+    async () => {
+      const k = keepalive();
+      k.observe(bgChanged([{ task_id: "a" }, { task_id: "b" }]));
+      await Bun.sleep(INTERVAL_MS * 3);
+      k.observe(bgChanged([]));
+      await Bun.sleep(INTERVAL_MS);
+      const settled = received.length;
+      expect(settled).toBeGreaterThan(0);
+      await Bun.sleep(INTERVAL_MS * 4);
+      k.stop();
+      expect(received).toHaveLength(settled);
+    },
+    TIMING,
+  );
+
+  test(
+    "a background job that never settles is covered only up to the idle cap",
+    async () => {
+      const k = keepalive(INTERVAL_MS * 3);
+      k.observe(bgChanged([{ task_id: "hung" }]));
+      await Bun.sleep(INTERVAL_MS * 6);
+      const capped = received.length;
+      expect(capped).toBeGreaterThan(0);
+      await Bun.sleep(INTERVAL_MS * 4);
+      expect(received).toHaveLength(capped);
+
+      // New output from the session restarts coverage while the job is live.
+      k.observe({ type: "assistant" });
+      await Bun.sleep(INTERVAL_MS * 2);
+      k.stop();
+      expect(received.length).toBeGreaterThan(capped);
+    },
+    TIMING,
+  );
+
+  test(
+    "stop() ends the keepalive and ignores later messages",
+    async () => {
+      const k = keepalive();
+      k.observe(bgChanged([{ task_id: "a" }]));
+      k.stop();
+      k.observe(bgChanged([{ task_id: "b" }]));
+      await Bun.sleep(INTERVAL_MS * 4);
+      expect(received).toHaveLength(0);
+    },
+    TIMING,
+  );
+});