@nanobpm/urban 0.94.2 → 0.96.0

package/src/runtime/adapters/deno.ts

@@ -45,12 +45,17 @@ interface DenoHttpServer {
 interface DenoFsWatcher extends AsyncIterable<{ kind: string; paths: string[] }> {
   close(): void;
 }
+interface DenoFsFile {
+  stat(): Promise<{ isFile: boolean }>;
+  close(): void;
+}
 interface DenoGlobal {
   env: { get(name: string): string | undefined };
   cwd(): string;
   readTextFile(path: string): Promise<string>;
   readDir(path: string): AsyncIterable<{ name: string; isFile: boolean; isDirectory: boolean }>;
-  stat(path: string): Promise<unknown>;
+  stat(path: string): Promise<{ isFile: boolean }>;
+  open(path: string, options?: { read?: boolean }): Promise<DenoFsFile>;
   watchFs(paths: string | string[], options?: { recursive?: boolean }): DenoFsWatcher;
   serve(
     opts: { port: number; hostname?: string; onListen?: (a: { port: number }) => void },
@@ -124,6 +129,32 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
         return false;
       }
     },
+    async statFile(p) {
+      // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+      // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+      // waiting for a writer, so opening before the type check would hang every shell request on
+      // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+      // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+      // open/stat still answers the real serving condition — a file `stat` reports as regular can
+      // be unreadable (ACLs / permissions), and the shell must not link an asset that then 404s.
+      // Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+      try {
+        const meta = await Deno.stat(abs(p));
+        if (!meta.isFile) return { isFile: false };
+      } catch {
+        return null;
+      }
+      let file: DenoFsFile | undefined;
+      try {
+        file = await Deno.open(abs(p), { read: true });
+        const s = await file.stat();
+        return { isFile: s.isFile };
+      } catch {
+        return null;
+      } finally {
+        file?.close();
+      }
+    },
     openSqlite(path) {
       const db = new DatabaseSync(abs(path));
       return wrapSqlite(db);

package/src/runtime/adapters/node.test.ts

@@ -1,9 +1,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import * as http from "node:http";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFile, fork } from "node:child_process";
+import { promisify } from "node:util";
 import { createNodeHost } from "./node.ts";
+import { isDeno } from "./detect.ts";
 import type { HttpServer } from "../core/host.ts";
 
+const execFileAsync = promisify(execFile);
+const nodeImportsTs = Number(process.versions.node.split(".")[0]) >= 22;
+
 // Issue #235: the node adapter must bind the interface it is handed so the manifest's
 // `network.bind` setting actually controls off-box reachability. We assert the *listen host*
 // the socket bound to for each setting by reading the native server's address.
@@ -65,3 +74,147 @@ test("serveHttp rejects when the port is already in use (does not hang)", async
     await first.stop();
   }
 });
+
+// PR #579: `statFile` is the shell's readable-regular-file probe for app assets (pages/app.css,
+// pages/app.js). It MUST classify the entry's type with a non-blocking `stat` BEFORE opening the
+// path for reading: a POSIX read-only open of a FIFO waits forever for a writer, so probing a FIFO
+// at the asset path would hang every shell request. This guards that a special-file entry returns
+// a non-regular verdict promptly instead of blocking. (POSIX-only: `mkfifo` isn't on Windows.)
+const hasMkfifo = process.platform !== "win32";
+// A blocked read-only `open` of a FIFO sits in libuv and CANNOT be cancelled from within the
+// process: `Promise.race` against a timeout would leave the losing probe running, and unlinking
+// the FIFO does not release it — the suite process would never exit, so the regression would not
+// actually fail fast. Run the probe in a killable CHILD process instead: the parent races the
+// child's verdict message against a timeout and SIGKILLs the child on timeout, so a blocking-open
+// regression fails this test fast (child startup + a ~2s probe budget) instead of wedging the runner.
+//
+// Two separate budgets, deliberately: the child first strip-types `node.ts` and its transitive
+// imports on a cold `--experimental-strip-types` start, which is HUNDREDS of ms and — crucially —
+// load-sensitive (observed >2s under the full parallel suite, #579). If a single timeout covered
+// both startup AND the `statFile` call, that cold-start cost would contaminate the probe budget and
+// the test would fail spuriously under load. So the child emits a `ready` message AFTER its imports
+// resolve; the parent only arms the (short) probe timeout once ready. Startup gets its own generous,
+// load-insensitive guard, and the probe budget then measures ONLY `statFile` — the blocking-open
+// regression (which manifests inside `statFile`, after `ready`) still fails fast.
+//
+// Node-only: the child is forked from `process.execPath` with Node-only flags
+// (`--experimental-strip-types`, `--input-type=module`). Under Deno, `child_process.fork` spawns
+// the DENO binary, which wraps the `--eval` source in a CJS shim (`$deno$eval.mts` →
+// `runInThisContext`) — the ESM `import` in the probe source is then a SyntaxError and the child
+// dies before `ready`. The probe is a guard for the NODE host adapter's blocking-open regression,
+// and the node-based suite (`npm test`, run by the `build` CI job) exercises it on every PR; the
+// Deno job runs this same file, so it must skip there rather than fail on the runtime mismatch.
+const PROBE_STARTUP_TIMEOUT_MS = 30_000;
+type FifoReadyMsg = { ready: true };
+type FifoVerdictMsg = { verdict: { isFile: boolean } | null };
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+function isFifoReadyMsg(value: unknown): value is FifoReadyMsg {
+  return isRecord(value) && value.ready === true;
+}
+function isFifoVerdictMsg(value: unknown): value is FifoVerdictMsg {
+  if (!isRecord(value) || !("verdict" in value)) return false;
+  const verdict = value.verdict;
+  if (verdict === null) return true;
+  return isRecord(verdict) && typeof verdict.isFile === "boolean";
+}
+function probeInChild(cwd: string, asset: string, probeTimeoutMs: number): Promise<FifoVerdictMsg | "timeout"> {
+  // `node --eval` places the first user argument at process.argv[1] (argv[0] is the node
+  // binary), so cwd is argv[1] and the asset path is argv[2] — NOT [2]/[3]. `ready` is sent once
+  // the host module is imported and built, BEFORE the (possibly blocking) `statFile` probe.
+  const source = `import { createNodeHost } from ${JSON.stringify(new URL("./node.ts", import.meta.url).href)};
+const host = createNodeHost({ cwd: process.argv[1], log: () => {} });
+process.send({ ready: true });
+const verdict = await host.statFile(process.argv[2]);
+process.send({ verdict });
+process.exit(0);`;
+  return new Promise((resolve, reject) => {
+    const child = fork(
+      "--input-type=module",
+      ["--experimental-strip-types", "--no-warnings", "--eval", source, cwd, asset],
+      { stdio: ["ignore", "ignore", "inherit", "ipc"] },
+    );
+    let probeTimer: ReturnType<typeof setTimeout> | undefined;
+    // Generous, load-insensitive guard: the child must finish importing and emit `ready` within
+    // this. A startup slower than 30s means a genuine hang in module load, not the FIFO probe.
+    const startupTimer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("probe child did not become ready (startup) in time"));
+    }, PROBE_STARTUP_TIMEOUT_MS);
+    const clearTimers = () => {
+      clearTimeout(startupTimer);
+      if (probeTimer !== undefined) clearTimeout(probeTimer);
+    };
+    child.on("message", (msg: unknown) => {
+      if (isFifoReadyMsg(msg)) {
+        // Startup done — now time ONLY the statFile call. A blocking-open regression blocks here
+        // and this short budget SIGKILLs the child, failing the test fast.
+        clearTimeout(startupTimer);
+        probeTimer = setTimeout(() => {
+          child.kill("SIGKILL");
+          resolve("timeout");
+        }, probeTimeoutMs);
+        return;
+      }
+      clearTimers();
+      child.disconnect();
+      if (isFifoVerdictMsg(msg)) resolve(msg);
+      else reject(new Error(`unexpected probe message: ${JSON.stringify(msg)}`));
+    });
+    child.once("error", (err) => {
+      clearTimers();
+      reject(err);
+    });
+    // Fail fast with the real cause when the child dies without messaging (e.g. a
+    // syntax/runtime crash during module load) instead of waiting out the startup
+    // timeout and reporting a misleading "did not become ready".
+    child.once("exit", (code, signal) => {
+      clearTimers();
+      reject(
+        new Error(
+          `probe child exited before reporting (code=${String(code)}, signal=${String(signal)})`,
+        ),
+      );
+    });
+  });
+}
+test(
+  "statFile classifies a FIFO as non-regular without blocking (does not hang)",
+  { skip: !hasMkfifo || !nodeImportsTs || isDeno() },
+  async () => {
+    const dir = await mkdtemp(join(tmpdir(), "urban-fifo-"));
+    try {
+      const fifo = join(dir, "app.css");
+      await execFileAsync("mkfifo", [fifo]);
+      const msg = await probeInChild(dir, "app.css", 2000);
+      assert.notEqual(msg, "timeout", "statFile must not block on a FIFO");
+      // Require a POSITIVE non-regular verdict. Accepting `null` (the probe-error path) would
+      // let the test pass vacuously without ever probing the FIFO — e.g. if the child crashed
+      // or read the wrong argv index and statFile swallowed the resulting path error.
+      assert.ok(
+        msg !== "timeout" && msg.verdict !== null && msg.verdict.isFile === false,
+        `a FIFO must positively probe as a non-regular file (got ${JSON.stringify(msg)})`,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+// Companion to the FIFO guard: a real regular file still probes as `isFile: true`, and a directory
+// at the asset path probes as non-regular — the two verdicts `mountPages` relies on to link only
+// genuinely servable assets.
+test("statFile reports a regular file as isFile and a directory as non-regular", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-stat-"));
+  try {
+    await writeFile(join(dir, "app.js"), "export {};");
+    await mkdir(join(dir, "app.css"), { recursive: true });
+    const host = createNodeHost({ cwd: dir, log: () => {} });
+    assert.deepEqual(await host.statFile!("app.js"), { isFile: true });
+    assert.deepEqual(await host.statFile!("app.css"), { isFile: false });
+    assert.equal(await host.statFile!("missing.css"), null);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/adapters/node.ts

@@ -1,7 +1,7 @@
 // Node adapter — implements HostContext against `node:*`. This is one of only two files
 // (with deno.ts) allowed to touch a concrete runtime.
 
-import { readFile, readdir, stat } from "node:fs/promises";
+import { open, readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
@@ -154,6 +154,32 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         return false;
       }
     },
+    async statFile(p) {
+      // Classify with a bare `stat` FIRST, then only open a *regular file* to confirm it is
+      // readable. The order matters: a read-only open of a FIFO (named pipe) blocks indefinitely
+      // waiting for a writer, so opening before the type check would hang every shell request on
+      // a FIFO sitting at this conventional asset path. A plain `stat` never blocks, so it safely
+      // rejects non-regular entries (directory, FIFO, socket, device) up front. The subsequent
+      // handle open/stat still answers the real serving condition — a file `stat` reports as
+      // regular can be unreadable (ACLs / permissions), and the shell must not link an asset that
+      // then 404s. Missing path → `null`; non-regular → `isFile: false`; unreadable → `null`.
+      try {
+        const meta = await stat(abs(p));
+        if (!meta.isFile()) return { isFile: false };
+      } catch {
+        return null;
+      }
+      let handle: Awaited<ReturnType<typeof open>> | undefined;
+      try {
+        handle = await open(abs(p), "r");
+        const s = await handle.stat();
+        return { isFile: s.isFile() };
+      } catch {
+        return null;
+      } finally {
+        await handle?.close();
+      }
+    },
     openSqlite(path) {
       const db = new DatabaseSync(abs(path));
       return wrapNodeSqlite(db);

package/src/runtime/core/glob.test.ts

@@ -16,6 +16,12 @@ function fakeHost(files: Record<string, string[]>): HostContext {
       const name = slash >= 0 ? p.slice(slash + 1) : p;
       return (files[dir] ?? []).includes(name);
     },
+    statFile: async (p) => {
+      const slash = p.lastIndexOf("/");
+      const dir = slash >= 0 ? p.slice(0, slash) : "";
+      const name = slash >= 0 ? p.slice(slash + 1) : p;
+      return (files[dir] ?? []).includes(name) ? { isFile: true } : null;
+    },
     openSqlite: () => {
       throw new Error("n/a");
     },

package/src/runtime/core/host.ts

@@ -101,6 +101,25 @@ export interface HostContext {
   listSubdirs?(dir: string): Promise<string[]>;
   /** True if the path exists (file or directory). */
   exists(path: string): Promise<boolean>;
+  /**
+   * Probe a path as a READABLE REGULAR FILE without reading its bytes: `{ isFile }` when it
+   * can be opened for reading, or `null` when it is absent or unreadable. The pages surface
+   * uses this to probe the app-owned `app.css`/`app.js` convention on the per-request shell
+   * hot path: `exists` is too broad (true for a DIRECTORY, which the shell would then link and
+   * the browser would 404 on), and probing via `readTextFile` reads and allocates a
+   * potentially large file just to answer "is it there?". A bare metadata `stat` is not
+   * enough either — it can succeed for a regular file that `readTextFile` cannot open (ACLs /
+   * permissions), so the shell would link an asset that then 404s on serving. Implementations
+   * therefore OPEN the file for reading (consuming no bytes) and stat the open handle, so this
+   * answers the same success condition as serving.
+   *
+   * OPTIONAL: `HostContext` is a public, externally-implementable seam (re-exported from
+   * `runtime/index.ts`, documented in the README as a supported custom-host extension point),
+   * so a new required member would be source-breaking. The pages surface falls back to a
+   * read-based probe when a host does not provide it; the built-in adapters do, as an
+   * allocation-free optimization on the hot path.
+   */
+  statFile?(path: string): Promise<{ isFile: boolean } | null>;
   /** Open (creating if needed) a SQLite database at a filesystem path. */
   openSqlite(path: string): SqliteDb;
   /**
@@ -238,14 +257,35 @@ export type ProcessInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED";
  */
 export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 
-/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
-export interface ProcessInstanceSnapshot {
-  readonly processInstanceKey: string;
-  readonly state: ProcessInstanceState;
+/**
+ * Which deployed process definition an instance runs — shared by the instance a
+ * {@link EngineClient.createInstance} starts and the {@link ProcessInstanceSnapshot} a
+ * {@link EngineClient.searchProcessInstances} reports, so the two describe the same instance
+ * identically. Each field is absent when the engine omits it (or reports it blank/malformed).
+ */
+export interface ProcessDefinitionIdentity {
   /** The key of the deployed process definition this instance runs — the handle a caller feeds to
    *  {@link EngineClient.getProcessDefinitionXml} to fetch the deployed BPMN (the instance →
-   *  `processDefinitionKey` → deployed XML path, no repo checkout). Absent when the engine omits it. */
+   *  `processDefinitionKey` → deployed XML path, no repo checkout). Unique per deployed version. */
   readonly processDefinitionKey?: string;
+  /** The BPMN process id (`<bpmn:process id>`) — stable across versions; the selector
+   *  {@link EngineClient.searchProcessInstances} accepts as `processDefinitionId`. */
+  readonly processDefinitionId?: string;
+  /** The deployed version of `processDefinitionId` this instance runs (1-based). */
+  readonly processDefinitionVersion?: number;
+}
+
+/** The instance {@link EngineClient.createInstance} started: its key, the exact deployed
+ *  definition version it runs, and — when `awaitCompletion` was requested — its final variables. */
+export interface CreatedProcessInstance extends ProcessDefinitionIdentity {
+  readonly processInstanceKey: string;
+  readonly variables?: Record<string, unknown>;
+}
+
+/** A single process instance's lifecycle snapshot returned by {@link EngineClient.searchProcessInstances}. */
+export interface ProcessInstanceSnapshot extends ProcessDefinitionIdentity {
+  readonly processInstanceKey: string;
+  readonly state: ProcessInstanceState;
   /** The key of this instance's *immediate* parent process instance — the caller that instantiated
    *  it as a native child (a `<bpmn:callActivity>`). `undefined` for a top-level (root) instance,
    *  and absent when the engine omits it (same optional/engine-provided convention as
@@ -722,12 +762,14 @@ export interface EngineClient {
   deployResources(
     resources: { name: string; content: string; contentType: string }[],
   ): Promise<{ deployed: number }>;
-  /** Start a process instance. */
+  /** Start a process instance of the latest deployed version of `processDefinitionId`. Returns
+   *  the new instance's key plus the {@link ProcessDefinitionIdentity} (key, id, version) of the
+   *  definition it actually runs. */
   createInstance(input: {
     processDefinitionId: string;
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
-  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }>;
+  }): Promise<CreatedProcessInstance>;
   /** Cancel a running process instance (the pages surface's row-cancel action). */
   cancelInstance(input: { processInstanceKey: string }): Promise<void>;
   /** Publish a message for correlation. */
@@ -775,7 +817,8 @@ export interface EngineClient {
   /** Complete a user task. */
   completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
   /**
-   * Search process instances by key and/or lifecycle state. The instance-tracking
+   * Search process instances by key, BPMN process id (`processDefinitionId`, any version),
+   * and/or lifecycle state. The instance-tracking
    * reconciler uses this to detect a tracked instance reaching a terminal state
    * (`TERMINATED`/`COMPLETED`) even though no completion worker ran for it — the
    * read-model row it backs would otherwise stay "active" forever. An eventually
@@ -785,6 +828,9 @@ export interface EngineClient {
   searchProcessInstances(filter?: {
     processInstanceKeys?: string[];
     state?: ProcessInstanceState;
+    /** Select only instances of this BPMN process id (every deployed version). A blank or
+     *  whitespace-only value is treated as absent (no filter). */
+    processDefinitionId?: string;
     /** Select only instances whose *immediate* parent is this process instance — the reduced-path
      *  query for "the native children spawned by this subject". */
     parentProcessInstanceKey?: string;

package/src/runtime/core/modules/actions.test.ts

@@ -82,6 +82,7 @@ function build(
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -262,6 +263,7 @@ test("a rejected import is evicted from the cache so a later load can succeed",
     readTextFile: async () => "",
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

package/src/runtime/core/modules/agent.test.ts

@@ -47,6 +47,7 @@ function ctxWithFiles(files: Record<string, string>): RuntimeContext {
     },
     listDir: async () => [],
     exists: async (p: string) => p in files,
+    statFile: async (p: string) => (p in files ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

package/src/runtime/core/modules/api.test.ts

@@ -115,6 +115,7 @@ function build(
     readTextFile: async () => specText,
     listDir: async () => [],
     exists: async (p: string) => existsSet.has(p),
+    statFile: async (p: string) => (existsSet.has(p) ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },
@@ -645,6 +646,7 @@ test("a failed initial spec load is retried, not cached as a permanent 500", asy
     },
     listDir: async () => [],
     exists: async () => false,
+    statFile: async () => null,
     openSqlite: () => {
       throw new Error("sqlite not used in this test");
     },

package/src/runtime/core/modules/connectors.test.ts

@@ -67,6 +67,7 @@ function makeCtx(
     env: (name) => opts.env?.[name],
     log: (level: string, msg: string) => logs.push({ level, msg }),
     exists: async (p: string) => p in files,
+    statFile: async (p: string) => (p in files ? { isFile: true } : null),
     readTextFile: async (p: string) => {
       if (!(p in files)) throw new Error(`ENOENT ${p}`);
       return files[p];

package/src/runtime/core/modules/datasource.test.ts

@@ -98,6 +98,7 @@ test("applyMigrations joins each migration file onto its dir without reintroduci
     env: () => undefined,
     now: () => 0,
     exists: async () => true,
+    statFile: async () => ({ isFile: true }),
     listDir: async () => ["002_b.sql", "001_a.sql"],
     readTextFile: async (path: string) => {
       readPaths.push(path);

package/src/runtime/core/modules/mcp.test.ts

@@ -144,6 +144,7 @@ function buildHarness(opts: {
     },
     listDir: async () => [],
     exists: async (p: string) => (p === BRIEF_PATH ? briefExists : false),
+    statFile: async (p: string) => (p === BRIEF_PATH && briefExists ? { isFile: true } : null),
     openSqlite: () => {
       throw new Error("sqlite not used in this harness");
     },
@@ -616,6 +617,30 @@ test("the framework debug tools appear and return engine truth", async () => {
   assert.deepEqual(JSON.parse(text), [snapshot]);
 });
 
+test("urban_debug_search_process_instances forwards a processDefinitionId selector", async () => {
+  const seen: unknown[] = [];
+  const engine = fakeEngine({
+    searchProcessInstances: async (filter) => {
+      seen.push(filter);
+      return [];
+    },
+  });
+  const { router } = buildHarness({ engine });
+  const session = await connect(router);
+  const list = await rpc(router, session, "tools/list", {});
+  const tools = list.result?.tools;
+  assert.ok(Array.isArray(tools));
+  const tool = tools.find((t) => Reflect.get(t, "name") === "urban_debug_search_process_instances");
+  const props = Reflect.get(Reflect.get(tool ?? {}, "inputSchema") ?? {}, "properties");
+  assert.ok(props && typeof props === "object" && "processDefinitionId" in props);
+
+  await rpc(router, session, "tools/call", {
+    name: "urban_debug_search_process_instances",
+    arguments: { processDefinitionId: "order", state: "ACTIVE" },
+  });
+  assert.deepEqual(seen, [{ state: "ACTIVE", processDefinitionId: "order" }]);
+});
+
 test("urban_debug_search_variables / search_jobs / get_process_definition_xml are read tools returning engine truth", async () => {
   const variable = {
     variableKey: "v-1",

package/src/runtime/core/modules/mcp.ts

@@ -70,6 +70,7 @@ import type {
   HttpResponse,
   IncidentFilter,
   JobFilter,
+  EngineClient,
   ProcessInstanceState,
   SqliteDb,
   UserTaskFilter,
@@ -544,20 +545,24 @@ function buildDebugTools(app: AppApi): DebugTool[] {
   return [
     {
       name: `${DEBUG_PREFIX}search_process_instances`,
-      description: "Engine truth: search process instances by key and/or lifecycle state.",
+      description:
+        "Engine truth: search process instances by key, BPMN process id (processDefinitionId, any version), and/or lifecycle state.",
       inputSchema: {
         type: "object",
         properties: {
           processInstanceKeys: { type: "array", items: OPTIONAL_STRING },
+          processDefinitionId: OPTIONAL_STRING,
           state: { type: "string", enum: ["ACTIVE", "COMPLETED", "TERMINATED"] },
         },
       },
       run: (args) => {
-        const filter: { processInstanceKeys?: string[]; state?: ProcessInstanceState } = {};
+        const filter: NonNullable<Parameters<EngineClient["searchProcessInstances"]>[0]> = {};
         const keys = readStringArray(args, "processInstanceKeys");
         if (keys) filter.processInstanceKeys = keys;
         const state = readProcessInstanceState(args, "state");
         if (state) filter.state = state;
+        const processDefinitionId = readPresentString(args, "processDefinitionId");
+        if (processDefinitionId) filter.processDefinitionId = processDefinitionId;
         return app.engine.searchProcessInstances(filter);
       },
     },