@desplega.ai/agent-swarm 2.6.0 → 2.7.0

package/src/tests/workflow-mcp-trigger-schema.test.ts

@@ -10,6 +10,7 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
   closeDb,
+  countWorkflowRuns,
   createAgent,
   createTaskExtended,
   createUser,
@@ -20,10 +21,13 @@ import {
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
   initDb,
+  updateWorkflow,
 } from "../be/db";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { handleWorkflows } from "../http/workflows";
 import { SCRIPT_LONG_TIMEOUT_HINT_MS } from "../scripts-runtime/executors/types";
+import { SwarmConfig } from "../scripts-runtime/swarm-config";
+import { createSwarmSdk } from "../scripts-runtime/swarm-sdk";
 import { WORKFLOW_LONG_SCRIPT_TIMEOUT_NUDGE } from "../tools/utils";
 import { registerCreateWorkflowTool } from "../tools/workflows/create-workflow";
 import { registerPatchWorkflowTool } from "../tools/workflows/patch-workflow";
@@ -56,6 +60,8 @@ type ToolResult = {
     versionCreated?: number;
     runId?: string;
     skipped?: boolean;
+    replayed?: boolean;
+    idempotencyConflict?: boolean;
     validationErrors?: string[];
     triggerSchema?: Record<string, unknown>;
   };
@@ -627,6 +633,209 @@ describe("MCP create-workflow / update-workflow / patch-workflow accept triggerS
     expect((await getTaskByWorkflowRunStepId(step!.id))?.requestedByUserId).toBe(requester.id);
   });
 
+  test("trigger-workflow wait:false returns the runId before the run's instant steps finish", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-detach"),
+      definition: {
+        nodes: [
+          {
+            id: "slow",
+            type: "script",
+            config: { runtime: "bash", script: "sleep 0.6; echo done", timeout: 10_000 },
+          },
+        ],
+      },
+    });
+    createdWorkflowIds.push(workflow.id);
+
+    const started = performance.now();
+    const triggered = await tools.callTrigger({ id: workflow.id, triggerData: {}, wait: false });
+    const elapsedMs = performance.now() - started;
+
+    expect(triggered.structuredContent?.success).toBe(true);
+    expect(triggered.structuredContent?.skipped).toBe(false);
+    const runId = triggered.structuredContent?.runId;
+    expect(runId).toBeString();
+    expect(elapsedMs).toBeLessThan(500);
+    expect((await getWorkflowRun(runId!))?.status).toBe("running");
+
+    const deadline = Date.now() + 10_000;
+    while ((await getWorkflowRun(runId!))?.status === "running" && Date.now() < deadline) {
+      await Bun.sleep(50);
+    }
+    expect((await getWorkflowRun(runId!))?.status).toBe("completed");
+  }, 15_000);
+
+  // A caller killed after its trigger committed (or while its request was in
+  // flight) retries with the same key: the retry must return that run and
+  // start no second one. Before idempotencyKey, the only guard was a separate
+  // claim the caller wrote first, which a kill between the two left held.
+  test("trigger-workflow idempotencyKey: a retry replays the accepted run and starts no second one", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = {
+      id: workflow.id,
+      triggerData: { pr: 7, sha: "a".repeat(40) },
+      wait: false,
+      idempotencyKey: "pr-review/repo/pr/7/aaaa",
+    };
+
+    const first = await tools.callTrigger(args, agentId);
+    expect(first.structuredContent?.success).toBe(true);
+    const runId = first.structuredContent?.runId;
+    expect(runId).toBeString();
+    expect(first.structuredContent?.replayed).toBeUndefined();
+
+    // The caller never saw `first` (killed): its retry replays it.
+    const retry = await tools.callTrigger(args, agentId);
+    expect(retry.structuredContent?.success).toBe(true);
+    expect(retry.structuredContent?.runId).toBe(runId);
+    expect(retry.structuredContent?.replayed).toBe(true);
+
+    // The same key with other data starts nothing either.
+    const conflict = await tools.callTrigger(
+      { ...args, triggerData: { pr: 7, sha: "b".repeat(40) } },
+      agentId,
+    );
+    expect(conflict.structuredContent?.success).toBe(false);
+    expect(conflict.structuredContent?.idempotencyConflict).toBe(true);
+
+    // The key is scoped to the caller: another agent's key does not collide.
+    const other = await tools.callTrigger(args, crypto.randomUUID());
+    expect(other.structuredContent?.runId).not.toBe(runId);
+
+    expect(await countWorkflowRuns(workflow.id)).toBe(2);
+  });
+
+  test("trigger-workflow idempotencyKey: concurrent triggers with one key start exactly one run", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent-race"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = { id: workflow.id, triggerData: { pr: 8 }, idempotencyKey: "race-key" };
+
+    const results = await Promise.all(
+      Array.from({ length: 6 }, () => tools.callTrigger(args, agentId)),
+    );
+    const runIds = new Set(results.map((r) => r.structuredContent?.runId));
+    expect(results.every((r) => r.structuredContent?.success === true)).toBe(true);
+    expect(runIds.size).toBe(1);
+    expect(results.filter((r) => r.structuredContent?.replayed !== true)).toHaveLength(1);
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+  });
+
+  test("trigger-workflow idempotencyKey: a key rejected before acceptance is not used up", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("mcp-trigger-idempotent-disabled"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+      enabled: false,
+    });
+    createdWorkflowIds.push(workflow.id);
+    const agentId = crypto.randomUUID();
+    const args = { id: workflow.id, triggerData: {}, idempotencyKey: "after-enable" };
+
+    expect((await tools.callTrigger(args, agentId)).structuredContent?.success).toBe(false);
+    expect(await countWorkflowRuns(workflow.id)).toBe(0);
+
+    await updateWorkflow(workflow.id, { enabled: true });
+    const accepted = await tools.callTrigger(args, agentId);
+    expect(accepted.structuredContent?.success).toBe(true);
+    expect(accepted.structuredContent?.replayed).toBeUndefined();
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+  });
+
+  // `ctx.swarm.workflow_trigger` in a script calls the REST trigger route, not
+  // the MCP tool, so `wait` and `idempotencyKey` must reach that route too.
+  const scriptSdk = (agentId: string) =>
+    createSwarmSdk(
+      new SwarmConfig({
+        system: {
+          apiKey: { value: "sdk-test-key", isSecret: true },
+          agentId: { value: agentId, isSecret: false },
+          mcpBaseUrl: { value: `http://127.0.0.1:${TEST_PORT}`, isSecret: false },
+        },
+        user: {},
+      }),
+    );
+  type SdkTriggerResult = { success: boolean; status: number; data: { runId?: string } };
+
+  test("ctx.swarm.workflow_trigger idempotencyKey: a retry after a kill replays the run", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("sdk-trigger-idempotent"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(workflow.id);
+    const sdk = scriptSdk(crypto.randomUUID());
+    const args = {
+      id: workflow.id,
+      triggerData: { pr: 9 },
+      wait: false,
+      idempotencyKey: "pr-review/repo/pr/9/sha",
+    };
+
+    const first = (await sdk.workflow_trigger(args)) as SdkTriggerResult;
+    const retry = (await sdk.workflow_trigger(args)) as SdkTriggerResult;
+    expect(first.success).toBe(true);
+    expect(first.data.runId).toBeString();
+    expect(retry.success).toBe(true);
+    expect(retry.data.runId).toBe(first.data.runId);
+    expect(await countWorkflowRuns(workflow.id)).toBe(1);
+
+    // Two concurrent calls (a killed attempt's in-flight request and its retry).
+    const racing = await createWorkflow({
+      name: uniqueName("sdk-trigger-idempotent-race"),
+      definition: { nodes: [{ id: "n", type: "property-match", config: { conditions: [] } }] },
+    });
+    createdWorkflowIds.push(racing.id);
+    const raced = (await Promise.all(
+      Array.from({ length: 4 }, () => sdk.workflow_trigger({ ...args, id: racing.id })),
+    )) as SdkTriggerResult[];
+    expect(new Set(raced.map((r) => r.data.runId)).size).toBe(1);
+    expect(await countWorkflowRuns(racing.id)).toBe(1);
+  });
+
+  test("ctx.swarm.workflow_trigger wait:false returns before the run's instant steps finish", async () => {
+    const workflow = await createWorkflow({
+      name: uniqueName("sdk-trigger-detach"),
+      definition: {
+        nodes: [
+          {
+            id: "slow",
+            type: "script",
+            config: { runtime: "bash", script: "sleep 0.6; echo done", timeout: 10_000 },
+          },
+        ],
+      },
+    });
+    createdWorkflowIds.push(workflow.id);
+
+    const started = performance.now();
+    const triggered = (await scriptSdk(crypto.randomUUID()).workflow_trigger({
+      id: workflow.id,
+      triggerData: {},
+      wait: false,
+    })) as SdkTriggerResult;
+    const elapsedMs = performance.now() - started;
+
+    expect(triggered.success).toBe(true);
+    const runId = triggered.data.runId;
+    expect(runId).toBeString();
+    expect(elapsedMs).toBeLessThan(500);
+    expect((await getWorkflowRun(runId!))?.status).toBe("running");
+
+    const deadline = Date.now() + 10_000;
+    while ((await getWorkflowRun(runId!))?.status === "running" && Date.now() < deadline) {
+      await Bun.sleep(50);
+    }
+    expect((await getWorkflowRun(runId!))?.status).toBe("completed");
+  }, 15_000);
+
   test("trigger-workflow with missing required field → structured TriggerSchemaError", async () => {
     const triggerSchema: Record<string, unknown> = {
       type: "object",

package/src/tests/workflow-run-finished-event.test.ts

@@ -0,0 +1,263 @@
+/**
+ * `workflow.run.finished`: every run, top-level or child, emits it once after
+ * commit when it turns terminal, so an event-mode `wait` can resume when any
+ * run ends.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { recordWorkflowPreflightFailure } from "../be/automation-preflight";
+import * as db from "../be/db";
+import {
+  closeDb,
+  createWorkflow,
+  createWorkflowRun,
+  getDbClient,
+  getWaitStateByStepId,
+  getWorkflowRun,
+  getWorkflowRunStepsByRunId,
+  initDb,
+  updateWorkflowRun,
+} from "../be/db";
+import { cancelLiveWorkflowTreeRuns } from "../be/db/workflow-runs";
+import type { Workflow, WorkflowDefinition } from "../types";
+import { startWorkflowExecution } from "../workflows/engine";
+import { workflowEventBus } from "../workflows/event-bus";
+import type { ExecutorDependencies } from "../workflows/executors/base";
+import { createExecutorRegistry } from "../workflows/executors/registry";
+import { _resetWaitBusSubscriptionsForTests, initWaitBusSubscriptions } from "../workflows/resume";
+
+const TEST_DB_PATH = "./test-workflow-run-finished-event.sqlite";
+const EVENT = "workflow.run.finished";
+
+const deps: ExecutorDependencies = {
+  db: db as typeof import("../be/db"),
+  eventBus: workflowEventBus,
+  interpolate: (t: string) => t,
+};
+
+type FinishedPayload = { runId: string; workflowId: string; status: string };
+
+const received: FinishedPayload[] = [];
+const onFinished = (data: unknown) => received.push(data as FinishedPayload);
+
+beforeAll(async () => {
+  await unlink(TEST_DB_PATH).catch(() => {});
+  initDb(TEST_DB_PATH);
+  workflowEventBus.on(EVENT, onFinished);
+});
+
+afterAll(async () => {
+  workflowEventBus.off(EVENT, onFinished);
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+});
+
+afterEach(() => {
+  _resetWaitBusSubscriptionsForTests();
+});
+
+async function makeWorkflow(name: string, def?: WorkflowDefinition): Promise<Workflow> {
+  return createWorkflow({
+    name: `${name}-${crypto.randomUUID()}`,
+    definition: def ?? {
+      nodes: [{ id: "n", type: "notify", config: { channel: "swarm", template: "x" } }],
+    },
+  });
+}
+
+async function newRun(workflowId: string): Promise<string> {
+  const id = crypto.randomUUID();
+  await createWorkflowRun({ id, workflowId });
+  return id;
+}
+
+const eventsFor = (runId: string) => received.filter((event) => event.runId === runId);
+
+// The emit goes through afterCommit and a dynamic import, so let it settle.
+const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
+
+async function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs = 2000) {
+  const t0 = Date.now();
+  while (!(await predicate())) {
+    if (Date.now() - t0 > timeoutMs) throw new Error("waitFor: timeout");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("workflow.run.finished", () => {
+  test("fires once per terminal transition, with the run id as runId", async () => {
+    const wf = await makeWorkflow("run-finished-once");
+    const runId = await newRun(wf.id);
+
+    await updateWorkflowRun(runId, { status: "waiting" });
+    await settle();
+    expect(eventsFor(runId)).toEqual([]);
+
+    await updateWorkflowRun(runId, { status: "failed", error: "boom" });
+    await waitFor(() => eventsFor(runId).length === 1);
+    expect(eventsFor(runId)[0]).toEqual({ runId, workflowId: wf.id, status: "failed" });
+    expect(eventsFor(runId)[0]).not.toHaveProperty("workflowRunId");
+    expect(eventsFor(runId)[0]).not.toHaveProperty("_runId");
+
+    // Later writes to the terminal run, with or without the same status, stay silent.
+    await updateWorkflowRun(runId, { context: { late: true } });
+    await updateWorkflowRun(runId, { status: "failed", error: "boom again" });
+    await settle();
+    expect(eventsFor(runId)).toHaveLength(1);
+
+    // A retry reopens the run; its next end is a new transition.
+    await updateWorkflowRun(runId, { status: "running" });
+    await updateWorkflowRun(runId, { status: "completed" });
+    await waitFor(() => eventsFor(runId).length === 2);
+    expect(eventsFor(runId)[1]?.status).toBe("completed");
+
+    // A terminal run moved to another terminal status, with no reopen, stays silent.
+    const relabelled = await newRun(wf.id);
+    await updateWorkflowRun(relabelled, { status: "completed" });
+    await waitFor(() => eventsFor(relabelled).length === 1);
+    await updateWorkflowRun(relabelled, { status: "failed", error: "late failure" });
+    await settle();
+    expect(eventsFor(relabelled)).toEqual([
+      { runId: relabelled, workflowId: wf.id, status: "completed" },
+    ]);
+  });
+
+  test("fires only after commit, and never for a rolled-back end", async () => {
+    const wf = await makeWorkflow("run-finished-commit");
+    const committed = await newRun(wf.id);
+    const rolledBack = await newRun(wf.id);
+
+    await getDbClient().transaction(async () => {
+      await updateWorkflowRun(committed, { status: "completed" });
+      await settle();
+      expect(eventsFor(committed)).toEqual([]);
+    });
+    await waitFor(() => eventsFor(committed).length === 1);
+
+    await expect(
+      getDbClient().transaction(async () => {
+        await updateWorkflowRun(rolledBack, { status: "skipped" });
+        throw new Error("roll back");
+      }),
+    ).rejects.toThrow("roll back");
+    await settle();
+    expect(eventsFor(rolledBack)).toEqual([]);
+    expect((await getWorkflowRun(rolledBack))?.status).toBe("running");
+  });
+
+  test("cancelLiveWorkflowTreeRuns fires for each run it cancels, not for terminal runs", async () => {
+    const wf = await makeWorkflow("run-finished-tree-cancel");
+    const live = await newRun(wf.id);
+    const waiting = await newRun(wf.id);
+    const done = await newRun(wf.id);
+    await updateWorkflowRun(waiting, { status: "waiting" });
+    await updateWorkflowRun(done, { status: "completed" });
+    await waitFor(() => eventsFor(done).length === 1);
+
+    const now = new Date().toISOString();
+    await getDbClient().transaction(() =>
+      cancelLiveWorkflowTreeRuns([live, waiting, done], "tree cancelled", now),
+    );
+
+    await waitFor(() => eventsFor(live).length === 1 && eventsFor(waiting).length === 1);
+    expect(eventsFor(live)[0]).toEqual({ runId: live, workflowId: wf.id, status: "cancelled" });
+    expect(eventsFor(waiting)[0]?.status).toBe("cancelled");
+    await settle();
+    expect(eventsFor(done)).toHaveLength(1);
+  });
+
+  test("a preflight failure run fires once, a deduplicated repeat does not", async () => {
+    const wf = await makeWorkflow("run-finished-preflight");
+    const input = {
+      workflowId: wf.id,
+      triggerType: "manual" as const,
+      triggerData: {},
+      failureReason: "needs_setup: slack",
+    };
+    const first = await recordWorkflowPreflightFailure(input);
+    await waitFor(() => eventsFor(first.runId).length === 1);
+    expect(eventsFor(first.runId)[0]?.status).toBe("failed");
+
+    const repeat = await recordWorkflowPreflightFailure(input);
+    expect(repeat.runId).toBe(first.runId);
+    await settle();
+    expect(eventsFor(first.runId)).toHaveLength(1);
+  });
+
+  test("a global wait filtered on a detached run's id resumes when that run ends", async () => {
+    const registry = createExecutorRegistry(deps);
+
+    // The detached run parks on a signal, so it stays live until the test ends it.
+    const target = await makeWorkflow("run-finished-target", {
+      nodes: [
+        {
+          id: "hold",
+          type: "wait",
+          config: { mode: "event", eventName: "test.release-target", scope: "global" },
+          next: { event: "end" },
+        },
+        { id: "end", type: "notify", config: { channel: "swarm", template: "released" } },
+      ],
+    });
+    const targetRunId = await startWorkflowExecution(target, {}, registry);
+    expect((await getWorkflowRun(targetRunId))?.status).toBe("waiting");
+
+    const waiter = await makeWorkflow("run-finished-waiter", {
+      nodes: [
+        {
+          id: "watch",
+          type: "wait",
+          config: {
+            mode: "event",
+            eventName: EVENT,
+            scope: "global",
+            filter: { runId: targetRunId },
+          },
+          next: { event: "after" },
+        },
+        { id: "after", type: "notify", config: { channel: "swarm", template: "target ended" } },
+      ],
+    });
+    const waiterRunId = await startWorkflowExecution(waiter, {}, registry);
+    // Control: a run-scoped wait on the same event must never match another run's end.
+    const scoped = await makeWorkflow("run-finished-run-scope", {
+      nodes: [
+        {
+          id: "watch",
+          type: "wait",
+          config: { mode: "event", eventName: EVENT, scope: "run" },
+        },
+      ],
+    });
+    const scopedRunId = await startWorkflowExecution(scoped, {}, registry);
+    await initWaitBusSubscriptions(registry);
+
+    const watchStep = async (runId: string) =>
+      (await getWorkflowRunStepsByRunId(runId)).find((step) => step.nodeId === "watch");
+    const watch = await watchStep(waiterRunId);
+    const scopedWatch = await watchStep(scopedRunId);
+    expect((await getWaitStateByStepId(watch!.id))?.status).toBe("pending");
+
+    // Another run ending does not match the filter.
+    const other = await newRun(target.id);
+    await updateWorkflowRun(other, { status: "completed" });
+    await waitFor(() => eventsFor(other).length === 1);
+    await settle();
+    expect((await getWaitStateByStepId(watch!.id))?.status).toBe("pending");
+
+    workflowEventBus.emit("test.release-target", {});
+    await waitFor(async () => (await getWorkflowRun(targetRunId))?.status === "completed");
+    await waitFor(async () => (await getWaitStateByStepId(watch!.id))?.status === "fired");
+
+    const fired = await getWaitStateByStepId(watch!.id);
+    expect(fired?.firedPayload).toEqual({
+      runId: targetRunId,
+      workflowId: target.id,
+      status: "completed",
+    });
+    await waitFor(async () => (await getWorkflowRun(waiterRunId))?.status === "completed");
+    expect((await getWaitStateByStepId(scopedWatch!.id))?.status).toBe("pending");
+  });
+});

package/src/tests/workflow-swarm-script.test.ts

@@ -760,6 +760,40 @@ describe("SwarmScriptExecutor", () => {
     expect(result.output?.exitCode).not.toBe(0);
   });
 
+  skip(
+    "meta.signal abort kills the script before its side effect",
+    async () => {
+      const marker = `/tmp/swarm-script-abort-${crypto.randomUUID()}`;
+      await saveScript(
+        "one-shot",
+        `export default async () => { await new Promise(r => setTimeout(r, 1500)); await Bun.write(${JSON.stringify(marker)}, "ran"); return { done: true }; };`,
+      );
+      const executor = new SwarmScriptExecutor(deps);
+      const wf = await makeWorkflow({ nodes: [] });
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(new Error("Step timed out")), 300);
+      const result = await executor.run({
+        config: { scriptName: "one-shot", timeoutMs: 30_000 },
+        context: {},
+        meta: {
+          runId: crypto.randomUUID(),
+          stepId: crypto.randomUUID(),
+          nodeId: "script",
+          workflowId: wf.id,
+          dryRun: false,
+          signal: controller.signal,
+        },
+      });
+
+      expect(result.status).toBe("failed");
+      expect(result.error).toContain("killed");
+      // Past the point where the script would have written the marker.
+      await Bun.sleep(1_800);
+      expect(await Bun.file(marker).exists()).toBe(false);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
   skip("Failure in the script surfaces as a workflow-node failure", async () => {
     await saveScript("throws", `export default async () => { throw new Error("boom"); };`);
     const executor = new SwarmScriptExecutor(deps);

package/src/tools/script-common.ts

@@ -16,6 +16,7 @@ export const SCRIPT_TRANSPORT_ERROR =
 export const scriptNameSchema = z.string().min(1).max(200);
 export const scriptScopeSchema = z.enum(["agent", "global"]);
 export const scriptFsModeSchema = z.enum(["none", "workspace-rw"]);
+export const scriptExecutorSchema = z.enum(["native", "quickjs"]);
 
 export const scriptToolOutputSchema = swarmToolOutputSchema({
   status: z.number().optional(),

package/src/tools/script-run.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -66,6 +67,12 @@ export const registerScriptRunTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional executor override ("native" or "quickjs"). When omitted, named scripts use their saved executor or SCRIPT_EXECUTOR.',
+          ),
         idempotencyKey: z
           .string()
           .max(200)

package/src/tools/script-upsert.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -33,6 +34,12 @@ export const registerScriptUpsertTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional per-script executor override ("native" or "quickjs"). Null or omitted inherits SCRIPT_EXECUTOR.',
+          ),
       }),
       outputSchema: scriptToolOutputSchema,
     },