@nanobpm/urban 0.18.0 → 0.19.0

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

@@ -0,0 +1,78 @@
+// The in-process `@nanobpm/worker` shim (ADR 0050, in-process port).
+//
+// A connector pack's `worker.ts` is a self-contained program that imports the
+// host-provided `@nanobpm/worker` SDK and calls `defineWorker({ type, handle })`.
+// The old Rust host ran each such worker as its own supervised child process. The
+// @nanobpm/urban runtime hosts app workers IN-PROCESS, so it hosts connector
+// workers the same way: it aliases the pack's `@nanobpm/worker` import to THIS
+// module, imports the pack entry, and reads back the registered handler(s) —
+// which it then registers on the engine like any other worker.
+//
+// `defineWorker` here does NOT connect to anything. It only records the handler in
+// a module-level registry that the runtime drains (`drainDefinedWorkers`). Because
+// the pack and the runtime resolve `@nanobpm/worker` to the SAME module URL, they
+// share this registry instance.
+//
+// This module is deliberately runtime-agnostic (no `node:*`, no `Deno`): it is the
+// contract surface, and the Node/Deno specifics of aliasing the import live in the
+// adapters.
+
+/** One activated job handed to a connector worker's `handle` (the subset the
+ *  `@nanobpm/worker` contract exposes; mirrors packages/connector-slack/types). */
+export interface ConnectorWorkerJob {
+  readonly jobKey: string;
+  readonly type: string;
+  readonly processInstanceKey: string;
+  readonly elementId?: string;
+  readonly variables: Record<string, unknown>;
+  /** Complete the job, optionally with output variables. */
+  complete(variables?: Record<string, unknown>): Promise<void>;
+  /** Fail the job (retryable). */
+  fail(message: string, retries?: number): Promise<void>;
+  /** Raise a BPMN error (routed to an error boundary event). */
+  error(code: string, message?: string): Promise<void>;
+}
+
+/** The options a connector worker passes to `defineWorker`. */
+export interface ConnectorWorkerOptions {
+  type: string;
+  maxParallelJobs?: number;
+  timeoutMs?: number;
+  /** Ignored in-process: the runtime owns the engine connection. Accepted so a
+   *  pack authored against the standalone SDK still type-checks and imports. */
+  baseUrl?: string;
+  worker?: string;
+  handle(job: ConnectorWorkerJob): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+}
+
+/** A worker the runtime will register on the engine, drained from the registry. */
+export interface DefinedConnectorWorker {
+  type: string;
+  maxParallelJobs?: number;
+  handle: ConnectorWorkerOptions["handle"];
+}
+
+// Module-level registry. Shared across every importer of this module URL, which is
+// exactly how the pack's `defineWorker` call reaches the runtime's drain: both
+// resolve `@nanobpm/worker` to this file.
+const registered: DefinedConnectorWorker[] = [];
+
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export function defineWorker(opts: ConnectorWorkerOptions): void {
+  if (!opts || typeof opts.type !== "string" || opts.type.length === 0) {
+    throw new Error("defineWorker: `type` is required");
+  }
+  if (typeof opts.handle !== "function") {
+    throw new Error(`defineWorker("${opts.type}"): handle must be a function`);
+  }
+  registered.push({ type: opts.type, maxParallelJobs: opts.maxParallelJobs, handle: opts.handle });
+}
+
+/** Return every worker registered since the last drain, and clear the registry.
+ *  The runtime calls this immediately after importing one pack entry, so the
+ *  returned set belongs to that pack. */
+export function drainDefinedWorkers(): DefinedConnectorWorker[] {
+  const out = registered.splice(0, registered.length);
+  return out;
+}

package/src/runtime/core/host.ts

@@ -68,6 +68,16 @@ export interface HostContext {
    * between runtimes, so it lives behind the host seam.
    */
   importModule(path: string): Promise<Record<string, unknown>>;
+  /**
+   * Import a connector pack's worker `entry` (ADR 0050) with the bare
+   * `@nanobpm/worker` specifier the pack imports aliased to the runtime's
+   * in-process shim (`connector-worker-sdk.ts`), so its top-level
+   * `defineWorker(...)` registers into the shared registry. `entry` is an
+   * absolute path (already resolved from the installed pack). Hosts that cannot
+   * alias a bare specifier (or run no connector workers) may omit this; the
+   * connector mount then reports the workers as unsupported rather than crashing.
+   */
+  importConnectorModule?(entry: string): Promise<void>;
   /** Start an HTTP server. Routing is done by the caller inside `handler`. */
   serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
   /**
@@ -100,6 +110,36 @@ export type JobHandler = (
   job: EngineJob,
 ) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 
+/**
+ * A BPMN error raised by a job handler. When a handler throws this, the engine
+ * adapter reports it to the engine as a BPMN error (`throwError`) — routed to a
+ * matching error boundary/event subprocess — instead of a plain job failure
+ * (which retries then raises an incident). This is the runtime face of a
+ * connector worker's `job.error(code, message)` (ADR 0050): a non-retryable,
+ * modelled outcome. Handlers that throw any other error are failed (retried).
+ */
+export class BpmnError extends Error {
+  readonly errorCode: string;
+  constructor(errorCode: string, message?: string) {
+    super(message ?? errorCode);
+    this.name = "BpmnError";
+    this.errorCode = errorCode;
+  }
+}
+
+/** Structural guard: true for a {@link BpmnError} or any error carrying a
+ *  non-empty string `errorCode`, so the check survives module-duplication (a
+ *  BpmnError constructed against a different copy of this module still routes as
+ *  a BPMN error rather than a generic failure). */
+export function isBpmnError(err: unknown): err is { errorCode: string; message?: string } {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    typeof (err as { errorCode?: unknown }).errorCode === "string" &&
+    (err as { errorCode: string }).errorCode.length > 0
+  );
+}
+
 /** A registered worker subscription. */
 export interface WorkerSubscription {
   readonly jobType: string;

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

@@ -0,0 +1,206 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
+import { BpmnError } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+import { defineWorker } from "../../connector-worker-sdk.ts";
+import { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors } from "./connectors.ts";
+
+/** A tiny engine that records registrations and can deliver a job to a handler. */
+class MiniEngine {
+  workers = new Map<string, JobHandler>();
+  async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
+    this.workers.set(jobType, handler);
+    return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
+  }
+  deliver(jobType: string, job: EngineJob) {
+    const h = this.workers.get(jobType);
+    if (!h) throw new Error(`no worker for ${jobType}`);
+    return h(job);
+  }
+}
+
+interface FakeHostOptions {
+  files?: Record<string, string>;
+  env?: Record<string, string>;
+  /** Called on importConnectorModule(entry): register the pack's workers. */
+  onImport?: (entry: string) => void;
+  /** Omit importConnectorModule entirely (host cannot host connectors). */
+  noConnectorHost?: boolean;
+}
+
+function makeCtx(
+  manifest: Partial<AppManifest>,
+  engine: MiniEngine,
+  opts: FakeHostOptions = {},
+): { ctx: RuntimeContext; logs: Array<{ level: string; msg: string }> } {
+  const logs: Array<{ level: string; msg: string }> = [];
+  const files = opts.files ?? {};
+  const host: Record<string, unknown> = {
+    runtime: "node",
+    log: (level: string, msg: string) => logs.push({ level, msg }),
+    exists: async (p: string) => p in files,
+    readTextFile: async (p: string) => {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    importModule: () => Promise.reject(new Error("no modules in this test")),
+  };
+  if (!opts.noConnectorHost) {
+    host.importConnectorModule = async (entry: string) => {
+      opts.onImport?.(entry);
+    };
+  }
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
+    engine: engine as unknown as RuntimeContext["engine"],
+    host,
+  } as unknown as RuntimeContext;
+  return { ctx, logs };
+}
+
+function makeApp(env: Record<string, string> = {}): AppApi {
+  return { env: (n: string) => env[n], log: () => {} } as unknown as AppApi;
+}
+
+const PKG = "@nanobpm/nano-ide-connector-slack";
+const PACK_ID = "nano-ide-connector-slack";
+
+function slackFiles(): Record<string, string> {
+  return {
+    "/app/package.json": JSON.stringify({ dependencies: { [PKG]: "^1.0.0" } }),
+    [`/app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [
+        {
+          type: "slack:send-message",
+          entry: "worker.ts",
+          configFields: [{ key: "botToken", env: "SLACK_BOT_TOKEN" }],
+        },
+      ],
+    }),
+  };
+}
+
+test("resolveInstalledConnectors indexes packs by their manifest id", async () => {
+  const { ctx } = makeCtx({}, new MiniEngine(), { files: slackFiles() });
+  const packs = await resolveInstalledConnectors(ctx);
+  assert.deepEqual([...packs.keys()], [PACK_ID]);
+  assert.equal(packs.get(PACK_ID)?.dir, `node_modules/${PKG}`);
+});
+
+test("mountConnectors imports the pack entry and registers the drained worker", async () => {
+  const engine = new MiniEngine();
+  let importedEntry: string | undefined;
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    {
+      files: slackFiles(),
+      onImport: (entry) => {
+        importedEntry = entry;
+        defineWorker({
+          type: "slack:send-message",
+          async handle(job) {
+            await job.complete({ echoed: job.variables.text });
+          },
+        });
+      },
+    },
+  );
+  const handle = await mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "xoxb-1" }));
+  assert.deepEqual(handle.jobTypes, ["slack:send-message"]);
+  assert.equal(importedEntry, `/app/node_modules/${PKG}/worker.ts`);
+  assert.ok(logs.some((l) => l.msg === "connector worker registered"));
+
+  const out = await engine.deliver("slack:send-message", {
+    jobKey: "j1",
+    jobType: "slack:send-message",
+    variables: { text: "hi" },
+  });
+  assert.deepEqual(out, { echoed: "hi" });
+});
+
+test("mountConnectors skips a worker whose required env is unset", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: slackFiles(), onImport: () => assert.fail("must not import when env is missing") },
+  );
+  const handle = await mountConnectors(ctx, makeApp()); // no SLACK_BOT_TOKEN
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.msg === "skipping connector worker: required env unset"));
+});
+
+test("mountConnectors fails closed when the connector pack is not installed", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: { "/app/package.json": JSON.stringify({ dependencies: {} }) } },
+  );
+  await assert.rejects(
+    () => mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" })),
+    /not installed/,
+  );
+});
+
+test("mountConnectors reports unsupported when the host cannot host connectors", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    { files: slackFiles(), noConnectorHost: true },
+  );
+  const handle = await mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" }));
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.msg === "skipping connector worker: host cannot host connector packs"));
+});
+
+test("resolveInstalledConnectors surfaces a malformed app package.json", async () => {
+  const { ctx } = makeCtx({}, new MiniEngine(), {
+    files: { "/app/package.json": "{ not json" },
+  });
+  await assert.rejects(() => resolveInstalledConnectors(ctx), /failed to parse package\.json/);
+});
+
+test("mountConnectors fails closed on a duplicate worker type in one pack entry", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: PACK_ID }] },
+    engine,
+    {
+      files: slackFiles(),
+      onImport: () => {
+        defineWorker({ type: "slack:send-message", async handle(job) { await job.complete({}); } });
+        defineWorker({ type: "slack:send-message", async handle(job) { await job.complete({}); } });
+      },
+    },
+  );
+  await assert.rejects(
+    () => mountConnectors(ctx, makeApp({ SLACK_BOT_TOKEN: "x" })),
+    /more than once/,
+  );
+});
+
+test("adaptConnectorHandler maps complete/fail/error(BpmnError) and a returned value", async () => {
+  const job: EngineJob = { jobKey: "j", jobType: "t", variables: {} };
+
+  const completes = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.complete({ a: 1 })) });
+  assert.deepEqual(await completes(job), { a: 1 });
+
+  const returns = adaptConnectorHandler({ type: "t", handle: async () => ({ b: 2 }) });
+  assert.deepEqual(await returns(job), { b: 2 });
+
+  const fails = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.fail("nope")) });
+  await assert.rejects(() => Promise.resolve(fails(job)), /nope/);
+
+  const errors = adaptConnectorHandler({ type: "t", handle: async (j) => void (await j.error("CODE", "boom")) });
+  await assert.rejects(
+    () => Promise.resolve(errors(job)),
+    (e: unknown) => e instanceof BpmnError && e.errorCode === "CODE",
+  );
+});

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

@@ -0,0 +1,269 @@
+// connectors — mount connector-pack workers (ADR 0050, in-process port).
+//
+// A connector is an installed npm pack that ships a `nano-ide.ext.json` manifest
+// and a worker `entry` program. The app enables it by adding a `workers[]` entry
+// with a `connector: <pack-id>` field (no `handler`/`llm`) — see `urban add` and
+// `addConnector`. This module resolves each such enabled worker to its installed
+// pack, imports the pack `entry` in-process (via the host's `@nanobpm/worker`
+// alias), and registers the drained handler on the engine like any other worker.
+//
+// The old Rust host supervised each connector worker as its own child process
+// (ADR 0050 §4). The @nanobpm/urban runtime hosts app workers in-process, so it
+// hosts connector workers the same way — trading process isolation for a simpler,
+// single-process model. `job.error(code)` still routes to a real BPMN error.
+//
+// This file is runtime-agnostic (core purity): the Node/Deno specifics of aliasing
+// the pack's `@nanobpm/worker` import live behind `host.importConnectorModule`.
+
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { BpmnError, type EngineJob, type JobHandler, type WorkerSubscription } from "../host.ts";
+import { workerJobType, type Worker } from "../manifest.ts";
+import {
+  drainDefinedWorkers,
+  type ConnectorWorkerJob,
+  type DefinedConnectorWorker,
+} from "../../connector-worker-sdk.ts";
+
+/** A config field a pack declares (subset of ext-types `ConfigField`): an env
+ *  pointer with an optional default. */
+interface PackConfigField {
+  key: string;
+  env?: string;
+  default?: string;
+}
+
+/** A worker a pack declares (subset of ext-types `WorkerSpec`). */
+interface PackWorkerSpec {
+  type: string;
+  entry: string;
+  maxParallelJobs?: number;
+  configFields?: PackConfigField[];
+}
+
+/** The pack manifest (`nano-ide.ext.json`) fields the runtime reads. */
+interface PackManifest {
+  id: string;
+  workers?: PackWorkerSpec[];
+}
+
+/** An installed connector pack, indexed by its manifest `id`. */
+interface InstalledPack {
+  id: string;
+  /** Pack dir relative to the app root, e.g. `node_modules/@nanobpm/nano-ide-connector-slack`. */
+  dir: string;
+  manifest: PackManifest;
+}
+
+export interface ConnectorsHandle extends Mounted {
+  readonly jobTypes: string[];
+}
+
+function joinRoot(root: string, p: string): string {
+  return p.startsWith("/") ? p : `${root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+}
+
+/** Env vars a pack worker requires before it can be imported/run: every config
+ *  field that points at an env var and has no baked default. In-process, a missing
+ *  var would let the pack's top-level guard `process.exit` the whole app, so the
+ *  runtime skips the worker instead. */
+function requiredEnv(spec: PackWorkerSpec): string[] {
+  const seen = new Set<string>();
+  for (const f of spec.configFields ?? []) {
+    if (f.env && (f.default === undefined || f.default === "")) seen.add(f.env);
+  }
+  return [...seen];
+}
+
+/** Read + parse a JSON file under the app root; undefined if absent. In `strict`
+ *  mode a malformed file throws a named parse error (used for the app's own files);
+ *  otherwise a malformed file is treated as absent (used for third-party packs). */
+async function readJson<T>(
+  ctx: RuntimeContext,
+  relPath: string,
+  opts?: { strict?: boolean },
+): Promise<T | undefined> {
+  const path = joinRoot(ctx.root, relPath);
+  if (!(await ctx.host.exists(path))) return undefined;
+  try {
+    return JSON.parse(await ctx.host.readTextFile(path)) as T;
+  } catch (err) {
+    if (opts?.strict) {
+      throw new Error(`failed to parse ${relPath}: ${(err as Error).message}`);
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Discover installed connector packs: read the app `package.json` dependencies,
+ * and for each that ships a `nano-ide.ext.json` with a worker, index it by its
+ * declared pack `id` (the value a manifest `worker.connector` field carries — NOT
+ * the npm package name).
+ */
+export async function resolveInstalledConnectors(
+  ctx: RuntimeContext,
+): Promise<Map<string, InstalledPack>> {
+  const out = new Map<string, InstalledPack>();
+  const pkg = await readJson<{
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+  }>(ctx, "package.json", { strict: true });
+  if (!pkg) return out;
+  const names = new Set<string>([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+    ...Object.keys(pkg.optionalDependencies ?? {}),
+  ]);
+  for (const name of names) {
+    const dir = `node_modules/${name}`;
+    const manifest = await readJson<PackManifest>(ctx, `${dir}/nano-ide.ext.json`);
+    if (!manifest || typeof manifest.id !== "string" || !manifest.id) continue;
+    if (!Array.isArray(manifest.workers) || manifest.workers.length === 0) continue;
+    out.set(manifest.id, { id: manifest.id, dir, manifest });
+  }
+  return out;
+}
+
+/** Wrap a pack's `DefinedConnectorWorker.handle` as an engine `JobHandler`,
+ *  bridging the `@nanobpm/worker` job facade (complete/fail/error) to the engine
+ *  seam. `job.error(code)` becomes a thrown {@link BpmnError} (routed to a BPMN
+ *  error boundary by the engine adapter); `job.fail(msg)` a plain throw (retry). */
+export function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandler {
+  return async (job: EngineJob) => {
+    let outcome:
+      | { kind: "complete"; vars?: Record<string, unknown> }
+      | { kind: "fail"; message: string }
+      | { kind: "error"; code: string; message?: string }
+      | undefined;
+    const facade: ConnectorWorkerJob = {
+      jobKey: job.jobKey,
+      type: job.jobType,
+      processInstanceKey: job.processInstanceKey ?? "",
+      elementId: job.elementId,
+      variables: job.variables,
+      async complete(vars) {
+        outcome = { kind: "complete", vars };
+      },
+      async fail(message) {
+        outcome = { kind: "fail", message };
+      },
+      async error(code, message) {
+        outcome = { kind: "error", code, message };
+      },
+    };
+    const ret = await worker.handle(facade);
+    if (outcome?.kind === "error") throw new BpmnError(outcome.code, outcome.message);
+    if (outcome?.kind === "fail") throw new Error(outcome.message);
+    if (outcome?.kind === "complete") return outcome.vars ?? {};
+    // No explicit outcome: fall back to the handle's return value (SDK-style).
+    return ret && typeof ret === "object" ? (ret as Record<string, unknown>) : {};
+  };
+}
+
+/**
+ * Mount every enabled connector worker (`workers[]` entries carrying a
+ * `connector` field). Fails closed on a seam mismatch (an enabled connector whose
+ * pack or worker type is not installed); skips-with-warning a worker whose
+ * required env is unset (so a missing credential does not crash the app), or when
+ * the host cannot host connector workers (`importConnectorModule` absent).
+ */
+export async function mountConnectors(ctx: RuntimeContext, app: AppApi): Promise<ConnectorsHandle> {
+  const decls = (ctx.manifest.workers ?? []).filter((w) => (w as Worker).connector) as Worker[];
+  const subs: WorkerSubscription[] = [];
+  const jobTypes: string[] = [];
+  if (decls.length === 0) return makeHandle(subs, jobTypes);
+
+  const packs = await resolveInstalledConnectors(ctx);
+  // Cache drained workers per imported entry (an entry may register several).
+  const drainedByEntry = new Map<string, Map<string, DefinedConnectorWorker>>();
+
+  for (const decl of decls) {
+    const jobType = workerJobType(decl);
+    if (!jobType) continue;
+    const packId = decl.connector!;
+    const pack = packs.get(packId);
+    if (!pack) {
+      throw new Error(
+        `connector worker "${jobType}" references pack "${packId}", which is not installed ` +
+          `(no dependency exposes a nano-ide.ext.json with id "${packId}"). Run \`urban add <pkg>\`.`,
+      );
+    }
+    const spec = pack.manifest.workers?.find((w) => w.type === jobType);
+    if (!spec) {
+      throw new Error(
+        `connector worker "${jobType}" is not provided by pack "${packId}" ` +
+          `(its nano-ide.ext.json declares no worker of that type).`,
+      );
+    }
+
+    const missing = requiredEnv(spec).filter((name) => !app.env(name));
+    if (missing.length > 0) {
+      ctx.host.log("warn", "skipping connector worker: required env unset", {
+        jobType,
+        connector: packId,
+        missing: missing.join(", "),
+      });
+      continue;
+    }
+
+    if (!ctx.host.importConnectorModule) {
+      ctx.host.log("warn", "skipping connector worker: host cannot host connector packs", {
+        jobType,
+        connector: packId,
+        runtime: ctx.host.runtime,
+      });
+      continue;
+    }
+
+    const entryAbs = joinRoot(ctx.root, `${pack.dir}/${spec.entry}`);
+    let drained = drainedByEntry.get(entryAbs);
+    if (!drained) {
+      await ctx.host.importConnectorModule(entryAbs);
+      // Fail closed on a duplicate worker `type` within one pack entry: silently
+      // keeping the last registration would bind an arbitrary handler.
+      drained = new Map<string, ReturnType<typeof drainDefinedWorkers>[number]>();
+      for (const w of drainDefinedWorkers()) {
+        if (drained.has(w.type)) {
+          throw new Error(
+            `connector pack "${packId}" entry "${spec.entry}" registered the worker ` +
+              `type "${w.type}" more than once (duplicate defineWorker call).`,
+          );
+        }
+        drained.set(w.type, w);
+      }
+      drainedByEntry.set(entryAbs, drained);
+    }
+    const worker = drained.get(jobType);
+    if (!worker) {
+      throw new Error(
+        `connector pack "${packId}" entry "${spec.entry}" did not register a worker for ` +
+          `"${jobType}" (its defineWorker call declares a different type).`,
+      );
+    }
+
+    const wrapped = adaptConnectorHandler(worker);
+    const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+      workerName: `${ctx.manifest.id}:${jobType}`,
+      // The pack's `defineWorker({ maxParallelJobs })` is the authoritative runtime
+      // value; the ext.json spec is a design-time default when the code omits it.
+      maxParallelJobs: worker.maxParallelJobs ?? spec.maxParallelJobs,
+    });
+    subs.push(sub);
+    jobTypes.push(jobType);
+    ctx.host.log("info", "connector worker registered", { jobType, connector: packId });
+  }
+
+  return makeHandle(subs, jobTypes);
+}
+
+function makeHandle(subs: WorkerSubscription[], jobTypes: string[]): ConnectorsHandle {
+  return {
+    name: "connectors",
+    jobTypes,
+    async stop() {
+      await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+    },
+    describe: () => ({ jobTypes }),
+  };
+}