@nanobpm/urban 0.18.0 → 0.19.0

package/dist/runtime/core/runtime.js

@@ -8,6 +8,7 @@ import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
 import { mountWorkers } from "./modules/workers.js";
+import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
 import { mountSecurity } from "./modules/security.js";
@@ -122,6 +123,12 @@ export async function createUrbanApp(opts) {
                     const w = await mountWorkers(ctx, api);
                     mounted.push(w);
                     describe.workers = w.describe?.();
+                    // Connector-pack workers share the `workers` flag: same lifecycle, same
+                    // engine, distinguished only by a `connector` field on the declaration.
+                    const c = await mountConnectors(ctx, api);
+                    mounted.push(c);
+                    if (c.jobTypes.length > 0)
+                        describe.connectors = c.describe?.();
                 }
                 const routes = [];
                 if (flags.surfaces) {

package/dist/runtime/core/validate.js

@@ -56,15 +56,41 @@ export function collectManifestIssues(m) {
             if (!workerJobType(w)) {
                 issues.push({ path: `workers[${i}]`, message: "missing taskType" });
             }
-            // The schema allows a worker backed by either a `handler` file or an `llm`
-            // binding (oneOf). Require exactly one — don't force `handler`.
-            const hasHandler = typeof w?.handler === "string" && w.handler.length > 0;
-            const hasLlm = typeof w?.llm === "string" && w.llm.length > 0;
-            if (!hasHandler && !hasLlm) {
-                issues.push({ path: `workers[${i}]`, message: "worker requires a `handler` or `llm`" });
+            // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
+            // or an installed `connector` pack (ADR 0050). The schema models these as a
+            // oneOf; enforce the "exactly one" here without forcing `handler`. Whether a
+            // `connector` actually resolves to an installed pack is a runtime seam check
+            // (mountConnectors), not something this static manifest check can see.
+            const backings = [];
+            if (typeof w?.handler === "string" && w.handler.length > 0)
+                backings.push("handler");
+            if (typeof w?.llm === "string" && w.llm.length > 0)
+                backings.push("llm");
+            if (typeof w?.connector === "string" && w.connector.length > 0)
+                backings.push("connector");
+            if (backings.length === 0) {
+                issues.push({
+                    path: `workers[${i}]`,
+                    message: "worker requires a `handler`, `llm`, or `connector`",
+                });
             }
-            else if (hasHandler && hasLlm) {
-                issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+            else if (backings.length > 1) {
+                issues.push({
+                    path: `workers[${i}]`,
+                    message: `worker declares ${backings.join(" + ")} (mutually exclusive)`,
+                });
+            }
+            // A `connection` must reference a declared top-level `connections` entry.
+            if (typeof w?.connection === "string" && w.connection.length > 0) {
+                const conns = man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
+                    ? man.connections
+                    : undefined;
+                if (!conns || !(w.connection in conns)) {
+                    issues.push({
+                        path: `workers[${i}].connection`,
+                        message: `no such connection "${w.connection}" (add it to connections)`,
+                    });
+                }
             }
         });
     }

package/dist/runtime/engine/nanosdk.d.ts

@@ -16,6 +16,13 @@ export interface NanoSdkActivatedJob {
         errorMessage: string;
         retries?: number;
     }): Promise<unknown>;
+    /** Raise a BPMN error (Zeebe `ThrowError`) routed to an error boundary/event.
+     *  Present on the nano-sdk enriched job at runtime; typed here so the adapter
+     *  can honour a handler's {@link BpmnError} (ADR 0050). */
+    error?(e: {
+        errorCode: string;
+        errorMessage?: string;
+    }): Promise<unknown>;
 }
 /** Config for a nano-sdk job worker (the subset this adapter sets). */
 export interface NanoSdkJobWorkerConfig {

package/dist/runtime/engine/nanosdk.js

@@ -18,6 +18,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { isBpmnError } from "../core/host.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export function requireProcessInstanceKey(key) {
@@ -121,6 +122,32 @@ export class SdkEngineClient {
                     return await job.complete(out ?? {});
                 }
                 catch (err) {
+                    // A handler-raised BPMN error is a modelled, non-retryable outcome:
+                    // report it as a BPMN error (routed to an error boundary/event) rather
+                    // than a plain failure. If the transport lacks `error` (older SDK) — or
+                    // the `error` call itself fails — fall through to the `fail` path below
+                    // so the job is still acknowledged rather than left to lock-timeout.
+                    if (isBpmnError(err) && typeof job.error === "function") {
+                        // `message` is typed loosely (the guard survives module duplication),
+                        // so coerce to a string before slicing to avoid a secondary crash.
+                        const raw = err.message;
+                        const message = typeof raw === "string" && raw.length > 0 ? raw : err.errorCode;
+                        this.log("info", `handler ${jobType} raised BPMN error`, {
+                            errorCode: err.errorCode,
+                        });
+                        try {
+                            return await job.error({
+                                errorCode: err.errorCode,
+                                errorMessage: message.slice(0, 500),
+                            });
+                        }
+                        catch (errReportErr) {
+                            this.log("warn", `handler ${jobType}: BPMN error report failed, failing the job`, {
+                                err: errReportErr instanceof Error ? errReportErr.message : String(errReportErr),
+                            });
+                            // fall through to the fail path
+                        }
+                    }
                     const message = err instanceof Error ? err.message : String(err);
                     this.log("error", `handler ${jobType} threw`, { err: message });
                     try {

package/dist/runtime/index.d.ts

@@ -6,6 +6,9 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+export { BpmnError, isBpmnError } from "./core/host.ts";
+export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
+export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";

package/dist/runtime/index.js

@@ -5,6 +5,11 @@ export { createUrbanApp } from "./core/runtime.js";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
+// error routed to an error boundary (ADR 0050), instead of a retryable failure.
+export { BpmnError, isBpmnError } from "./core/host.js";
+// Connector packs (ADR 0050, in-process port)
+export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.js";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";

package/dist/toolkit/addConnector.d.ts

@@ -0,0 +1,29 @@
+import type { GenIO } from "./gen.ts";
+export interface AddConnectorOptions {
+    /** App root directory. */
+    root: string;
+    /** The installed npm package name (already present under node_modules). */
+    pkg: string;
+    /** Manifest filename under root. Default "nano.app.json". */
+    manifestFile?: string;
+    io: GenIO;
+}
+export interface AddConnectorResult {
+    /** The pack id (`nano-ide.ext.json` `id`) written to each worker's `connector`. */
+    packId: string;
+    /** Workers considered, with whether one was already wired (idempotent). */
+    wired: {
+        taskType: string;
+        alreadyPresent: boolean;
+    }[];
+    /** The named connection created/reused, if the pack needs credentials. */
+    connection?: string;
+    /** Env vars the operator must set for the enabled workers to run. */
+    requiredEnv: string[];
+}
+/**
+ * Read the installed pack manifest, then wire its workers into the app manifest.
+ * Idempotent: re-running never duplicates a `workers[]`/`connections[]` entry.
+ * The app manifest object is mutated in place and written back.
+ */
+export declare function addConnector(opts: AddConnectorOptions): Promise<AddConnectorResult>;

package/dist/toolkit/addConnector.js

@@ -0,0 +1,170 @@
+// addConnector — enable an installed connector pack into an app's nano.app.json.
+//
+// A connector pack ships a `nano-ide.ext.json` manifest declaring one or more
+// workers (a `taskType`, a worker `entry`, and its config fields). "Enabling" it
+// means the pure, idempotent manifest edit the `urban add` CLI performs after
+// `npm install <pkg>` (ADR 0050 §5): for every worker the pack declares, append a
+// pack-backed `workers[]` entry (`{ taskType, connector: <pack-id>, connection }`)
+// and, when the pack needs credentials, a named `connections[]` entry whose values
+// are env-pointer templates (never inline secrets, ADR 0025 §1 / 0027 §5).
+//
+// This module only reads/writes files through the GenIO port — installing the
+// package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
+// unit-testable.
+const MANIFEST_FILE = "nano-ide.ext.json";
+function joinPath(a, b) {
+    // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
+    // root does not produce an invalid path.
+    return `${a.replace(/[/\\]+$/, "")}/${b.replace(/^[/\\]+/, "")}`;
+}
+/** A stable, slug-ish connection name for a pack id (kebab, no leading scope). */
+function connectionNameFor(packId) {
+    const base = packId.includes("/") ? packId.slice(packId.lastIndexOf("/") + 1) : packId;
+    return base.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || packId;
+}
+/**
+ * Read the installed pack manifest, then wire its workers into the app manifest.
+ * Idempotent: re-running never duplicates a `workers[]`/`connections[]` entry.
+ * The app manifest object is mutated in place and written back.
+ */
+export async function addConnector(opts) {
+    const { root, pkg, io } = opts;
+    const manifestFile = opts.manifestFile ?? "nano.app.json";
+    const packManifestPath = joinPath(joinPath(joinPath(root, "node_modules"), pkg), MANIFEST_FILE);
+    if (!(await io.exists(packManifestPath))) {
+        throw new Error(`"${pkg}" is not an Urban connector: no ${MANIFEST_FILE} found at ${packManifestPath}. ` +
+            `Install the package first (\`npm install ${pkg}\`), and check it is a connector pack.`);
+    }
+    let pack;
+    try {
+        pack = JSON.parse(await io.readText(packManifestPath));
+    }
+    catch (err) {
+        throw new Error(`failed to parse ${packManifestPath}: ${err.message}`);
+    }
+    if (typeof pack.id !== "string" || !pack.id) {
+        throw new Error(`${packManifestPath} has no string "id" (a pack must declare its id).`);
+    }
+    const specs = Array.isArray(pack.workers) ? pack.workers : [];
+    if (specs.length === 0) {
+        throw new Error(`connector pack "${pack.id}" declares no workers[] — nothing to enable.`);
+    }
+    // `type` comes from JSON; a malformed pack must fail loudly rather than wire an
+    // invalid worker entry (or manufacture a confusing conflict).
+    for (const spec of specs) {
+        if (typeof spec.type !== "string" || spec.type.length === 0) {
+            throw new Error(`connector pack "${pack.id}" has a worker with a missing/non-string "type" in ${packManifestPath}.`);
+        }
+    }
+    const appManifestPath = joinPath(root, manifestFile);
+    if (!(await io.exists(appManifestPath))) {
+        throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
+    }
+    let app;
+    try {
+        app = JSON.parse(await io.readText(appManifestPath));
+    }
+    catch (err) {
+        throw new Error(`failed to parse ${appManifestPath}: ${err.message}`);
+    }
+    if (app === null || typeof app !== "object" || Array.isArray(app)) {
+        throw new Error(`${appManifestPath} is not a JSON object.`);
+    }
+    if (app.workers !== undefined && !Array.isArray(app.workers)) {
+        throw new Error(`${appManifestPath} "workers" must be an array.`);
+    }
+    if (app.connections !== undefined &&
+        (app.connections === null || typeof app.connections !== "object" || Array.isArray(app.connections))) {
+        throw new Error(`${appManifestPath} "connections" must be an object.`);
+    }
+    const workers = (app.workers ??= []);
+    // Required env across the pack's workers (env-pointer fields without a default).
+    const envFields = [];
+    const requiredEnvSet = new Set();
+    for (const spec of specs) {
+        for (const f of spec.configFields ?? []) {
+            if (f.env) {
+                envFields.push(f);
+                if (f.default === undefined || f.default === "")
+                    requiredEnvSet.add(f.env);
+            }
+        }
+    }
+    // Create/reuse a named connection when the pack carries credential config, so the
+    // required env pointers are documented in the manifest (secrets stay templates).
+    let connection;
+    if (envFields.length > 0) {
+        connection = connectionNameFor(pack.id);
+        const connections = (app.connections ??= {});
+        const existing = connections[connection];
+        if (existing === undefined) {
+            const conn = { type: pack.id };
+            for (const f of envFields) {
+                if (!(f.key in conn) && f.env)
+                    conn[f.key] = `\${${f.env}}`;
+            }
+            connections[connection] = conn;
+        }
+        else {
+            // A pre-existing connection of this name must be a compatible object of the
+            // same pack `type`; otherwise wiring workers to it would produce an invalid
+            // or misleading manifest. Fail loudly instead of silently reusing it.
+            if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+                throw new Error(`connection "${connection}" already exists and is not an object.`);
+            }
+            const conn = existing;
+            if (conn.type !== undefined && conn.type !== pack.id) {
+                throw new Error(`connection "${connection}" already exists with type "${String(conn.type)}", ` +
+                    `not "${pack.id}".`);
+            }
+            // Backfill the pack's `type` and any missing env-pointer templates.
+            if (conn.type === undefined)
+                conn.type = pack.id;
+            for (const f of envFields) {
+                if (!(f.key in conn) && f.env)
+                    conn[f.key] = `\${${f.env}}`;
+            }
+        }
+    }
+    const wired = [];
+    for (const spec of specs) {
+        const existing = workers.find((w) => w.taskType === spec.type);
+        if (existing) {
+            // A same-taskType worker backed by a handler/llm or a different connector is
+            // a real conflict — enabling this pack would not take effect. Fail loudly
+            // instead of reporting a false success.
+            if (existing.connector !== pack.id) {
+                const backing = existing.handler
+                    ? `handler "${existing.handler}"`
+                    : existing.llm
+                        ? `llm "${existing.llm}"`
+                        : existing.connector
+                            ? `connector "${existing.connector}"`
+                            : "another backing";
+                throw new Error(`worker "${spec.type}" is already declared with ${backing}; ` +
+                    `remove it before enabling connector "${pack.id}" for that taskType.`);
+            }
+            wired.push({ taskType: spec.type, alreadyPresent: true });
+            // Heal an entry that references the pack but predates the connection.
+            if (connection && !existing.connection) {
+                existing.connection = connection;
+            }
+            continue;
+        }
+        const entry = {
+            taskType: spec.type,
+            connector: pack.id,
+        };
+        if (connection)
+            entry.connection = connection;
+        workers.push(entry);
+        wired.push({ taskType: spec.type, alreadyPresent: false });
+    }
+    await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+    return {
+        packId: pack.id,
+        wired,
+        connection,
+        requiredEnv: [...requiredEnvSet],
+    };
+}

package/dist/toolkit/index.d.ts

@@ -29,3 +29,5 @@ export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffo
 export type { ScaffoldWorker, SkippedWorker, SkipReason, StubManifestEntry, WorkerScaffoldPlan, WorkerStubPlan, } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
+export { addConnector } from "./addConnector.ts";
+export type { AddConnectorOptions, AddConnectorResult } from "./addConnector.ts";

package/dist/toolkit/index.js

@@ -25,3 +25,4 @@ export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFL
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.js";
 export { scaffoldWorkers } from "./scaffold.js";
+export { addConnector } from "./addConnector.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -64,7 +64,7 @@
   "dependencies": {
     "@nanobpm/nano-app-schema": "^0.1.0",
     "@nanobpm/nano-sdk": "^1.2.3",
-    "@nanobpm/workflow": "^0.7.0",
+    "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
     "create-urban-app": "^0.5.0"
   },

package/src/cli.ts

@@ -20,9 +20,10 @@ import {
   selectHost,
 } from "./runtime/index.ts";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 
 // Read the package version from package.json (one hop up from both src/cli.ts and the
 // compiled dist/cli.js) so `urban --version` never drifts from the published version.
@@ -47,6 +48,7 @@ interface Flags {
   deno: boolean;
   models: boolean;
   stdout: boolean;
+  install: boolean;
   style?: "model" | "code";
   help: boolean;
   version: boolean;
@@ -54,7 +56,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -70,6 +72,8 @@ function parse(argv: string[]): Flags {
     else if (a === "--no-models") f.models = false;
     else if (a === "--models") f.models = true;
     else if (a === "--stdout") f.stdout = true;
+    else if (a === "--no-install") f.install = false;
+    else if (a === "--install") f.install = true;
     else if (a === "--code-first") f.style = "code";
     else if (a === "--style") {
       const v = need(++i, a);
@@ -103,6 +107,7 @@ Usage:
   urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
                                     (--stdout: print {models,incomplete} JSON without writing)
   urban stubs [--write]             scaffold write-once handler stubs from the model
+  urban add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
@@ -281,6 +286,57 @@ async function cmdNew(f: Flags): Promise<number> {
   return 0;
 }
 
+async function cmdAdd(f: Flags): Promise<number> {
+  const pkg = f._[1];
+  if (!pkg) {
+    console.error("usage: urban add <pkg> [--no-install]");
+    return 1;
+  }
+  // Install the connector pack (a subprocess — the toolkit stays runtime-agnostic).
+  if (f.install) {
+    console.log(`Installing ${pkg} …`);
+    const res = spawnSync("npm", ["install", pkg], {
+      cwd: f.root,
+      stdio: "inherit",
+    });
+    if (res.error) {
+      console.error(`npm install failed: ${res.error.message}`);
+      return 1;
+    }
+    if (res.signal) {
+      console.error(`npm install was terminated by signal ${res.signal}`);
+      return 1;
+    }
+    if (res.status !== 0) {
+      console.error(`npm install exited with code ${res.status}`);
+      return res.status ?? 1;
+    }
+  }
+
+  try {
+    const result = await addConnector({
+      root: f.root,
+      pkg,
+      manifestFile: f.manifest,
+      io: createNodeGenIO(),
+    });
+    const added = result.wired.filter((w) => !w.alreadyPresent);
+    const kept = result.wired.filter((w) => w.alreadyPresent);
+    console.log(`✔ enabled connector "${result.packId}" from ${pkg}`);
+    for (const w of added) console.log(`  + worker ${w.taskType}`);
+    for (const w of kept) console.log(`  = worker ${w.taskType} (already wired)`);
+    if (result.connection) console.log(`  connection: ${result.connection}`);
+    if (result.requiredEnv.length > 0) {
+      console.log(`\nSet these environment variables before \`urban run\`:`);
+      for (const name of result.requiredEnv) console.log(`  ${name}`);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`✖ ${(err as Error).message}`);
+    return 1;
+  }
+}
+
 export async function main(argv: string[]): Promise<number> {
   let f: Flags;
   try {
@@ -310,6 +366,8 @@ export async function main(argv: string[]): Promise<number> {
       return cmdDerive(f);
     case "stubs":
       return cmdStubs(f);
+    case "add":
+      return cmdAdd(f);
     case "run":
       return cmdRun(f);
     case "dev":

package/src/runtime/adapters/node.ts

@@ -2,10 +2,12 @@
 // (with deno.ts) allowed to touch a concrete runtime.
 
 import { 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";
+import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import type {
   HostContext,
@@ -28,6 +30,57 @@ export interface NodeHostOptions {
   importNonce?: string;
 }
 
+/** Resolve the in-process `@nanobpm/worker` shim URL relative to this adapter,
+ *  tolerating both the compiled package (`.js`, the published/`urban run` path)
+ *  and a from-source run (`.ts`). */
+function connectorShimUrl(): string {
+  const js = new URL("../connector-worker-sdk.js", import.meta.url);
+  if (existsSync(fileURLToPath(js))) return js.href;
+  return new URL("../connector-worker-sdk.ts", import.meta.url).href;
+}
+
+let connectorHooksRegistered = false;
+
+/**
+ * Register (once per process) the ESM customization hooks that let a connector
+ * pack's worker `entry` be imported in-process (ADR 0050, in-process port):
+ *   - a **resolve** hook aliasing the bare `@nanobpm/worker` specifier the pack
+ *     imports to the runtime's shim, so its `defineWorker(...)` registers into the
+ *     registry the runtime drains;
+ *   - a **load** hook that strips TypeScript from ANY `.ts` module resolved under
+ *     `node_modules` (Node refuses to type-strip there by default). In practice
+ *     only a connector pack's `.ts` entry and its `.ts` imports travel this path,
+ *     but the hook is process-global once registered, so it applies to every
+ *     subsequent `node_modules` `.ts` import — a safe superset (Node would
+ *     otherwise throw on such a file). The module's real URL is preserved so its
+ *     own bare imports (npm deps) still resolve.
+ * The hooks run on a separate thread, so the shim URL is baked into the hook
+ * source; the shim itself loads on the main thread (shared registry instance).
+ */
+function ensureConnectorHooks(): void {
+  if (connectorHooksRegistered) return;
+  const shim = JSON.stringify(connectorShimUrl());
+  const src =
+    `import { readFileSync } from "node:fs";\n` +
+    `import { fileURLToPath } from "node:url";\n` +
+    `import { stripTypeScriptTypes } from "node:module";\n` +
+    `const SHIM = ${shim};\n` +
+    `export async function resolve(spec, ctx, next) {\n` +
+    `  if (spec === "@nanobpm/worker") return { url: SHIM, shortCircuit: true };\n` +
+    `  return next(spec, ctx);\n` +
+    `}\n` +
+    `export async function load(url, ctx, next) {\n` +
+    `  const path = url.split("?")[0];\n` +
+    `  if (path.endsWith(".ts") && path.includes("/node_modules/")) {\n` +
+    `    const source = stripTypeScriptTypes(readFileSync(fileURLToPath(path), "utf8"), { mode: "strip" });\n` +
+    `    return { format: "module", source, shortCircuit: true };\n` +
+    `  }\n` +
+    `  return next(url, ctx);\n` +
+    `}\n`;
+  register("data:text/javascript," + encodeURIComponent(src));
+  connectorHooksRegistered = true;
+}
+
 export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
   const cwd = opts.cwd ?? process.cwd();
   const abs = (p: string) => (isAbsolute(p) ? p : resolve(cwd, p));
@@ -69,6 +122,16 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
         pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
       return import(href) as Promise<Record<string, unknown>>;
     },
+    async importConnectorModule(entry) {
+      ensureConnectorHooks();
+      // Import for side effects only: the pack's top-level `defineWorker(...)` runs
+      // and registers into the shim registry, which the caller drains. Apply the
+      // dev `importNonce` cache-buster (as importModule does) so a hot-reloaded
+      // pack entry is re-evaluated instead of served stale from the ESM cache.
+      const href =
+        pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      await import(href);
+    },
     async serveHttp(port, handler) {
       return await startNodeServer(port, handler);
     },

package/src/runtime/connector-worker-sdk.test.ts

@@ -0,0 +1,56 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  defineWorker,
+  drainDefinedWorkers,
+  type ConnectorWorkerJob,
+} from "./connector-worker-sdk.ts";
+
+test("defineWorker records handlers that drainDefinedWorkers returns then clears", () => {
+  drainDefinedWorkers(); // start clean
+  defineWorker({ type: "a:one", maxParallelJobs: 3, handle: async () => ({}) });
+  defineWorker({ type: "a:two", handle: async () => {} });
+  const first = drainDefinedWorkers();
+  assert.deepEqual(
+    first.map((w) => w.type),
+    ["a:one", "a:two"],
+  );
+  assert.equal(first[0].maxParallelJobs, 3);
+  // Draining empties the registry: a second drain sees nothing.
+  assert.deepEqual(drainDefinedWorkers(), []);
+});
+
+test("defineWorker rejects a missing type or non-function handle", () => {
+  assert.throws(() => defineWorker({ type: "", handle: async () => ({}) }), /type` is required/);
+  assert.throws(
+    () => defineWorker({ type: "x" } as unknown as Parameters<typeof defineWorker>[0]),
+    /handle must be a function/,
+  );
+  // A failed defineWorker must not leave a partial registration behind.
+  assert.deepEqual(drainDefinedWorkers(), []);
+});
+
+test("a registered handle receives the job facade and can complete", async () => {
+  drainDefinedWorkers();
+  let seen: ConnectorWorkerJob | undefined;
+  defineWorker({
+    type: "a:three",
+    async handle(job) {
+      seen = job;
+      await job.complete({ ok: true });
+    },
+  });
+  const [w] = drainDefinedWorkers();
+  const completed: Record<string, unknown>[] = [];
+  await w.handle({
+    jobKey: "j1",
+    type: "a:three",
+    processInstanceKey: "p1",
+    variables: { n: 1 },
+    complete: async (v) => void completed.push(v ?? {}),
+    fail: async () => {},
+    error: async () => {},
+  });
+  assert.equal(seen?.jobKey, "j1");
+  assert.deepEqual(completed, [{ ok: true }]);
+});