@nanobpm/urban 0.18.0 → 0.19.0

package/dist/cli.js

@@ -12,9 +12,10 @@
 //               --port <n>, -h/--help, -v/--version.
 import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
+import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
 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.
 function readVersion() {
@@ -28,7 +29,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -53,6 +54,10 @@ function parse(argv) {
             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") {
@@ -93,6 +98,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
@@ -268,6 +274,60 @@ async function cmdNew(f) {
         console.log(`  # or on Deno: deno task start`);
     return 0;
 }
+async function cmdAdd(f) {
+    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.message}`);
+        return 1;
+    }
+}
 export async function main(argv) {
     let f;
     try {
@@ -298,6 +358,8 @@ export async function main(argv) {
             return cmdDerive(f);
         case "stubs":
             return cmdStubs(f);
+        case "add":
+            return cmdAdd(f);
         case "run":
             return cmdRun(f);
         case "dev":

package/dist/runtime/adapters/node.js

@@ -9,11 +9,62 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { watch as fsWatch } 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";
+/** 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() {
+    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() {
+    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 = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
@@ -52,6 +103,15 @@ export function createNodeHost(opts = {}) {
             const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
             return import(__rewriteRelativeImportExtension(href));
         },
+        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(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return await startNodeServer(port, handler);
         },

package/dist/runtime/connector-worker-sdk.d.ts

@@ -0,0 +1,39 @@
+/** 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"];
+}
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export declare function defineWorker(opts: ConnectorWorkerOptions): void;
+/** 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 declare function drainDefinedWorkers(): DefinedConnectorWorker[];

package/dist/runtime/connector-worker-sdk.js

@@ -0,0 +1,40 @@
+// 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.
+// 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 = [];
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export function defineWorker(opts) {
+    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() {
+    const out = registered.splice(0, registered.length);
+    return out;
+}

package/dist/runtime/core/host.d.ts

@@ -60,6 +60,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>;
     /**
@@ -87,6 +97,26 @@ export interface EngineJob<In extends object = Record<string, unknown>> {
     variables: In;
 }
 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 declare class BpmnError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string, message?: string);
+}
+/** 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 declare function isBpmnError(err: unknown): err is {
+    errorCode: string;
+    message?: string;
+};
 /** A registered worker subscription. */
 export interface WorkerSubscription {
     readonly jobType: string;

package/dist/runtime/core/host.js

@@ -2,4 +2,29 @@
 // JavaScript runtime (Node or Deno) or the Nano engine. Everything under core/ is
 // written against these interfaces and MUST NOT import `node:*` or reference `Deno`.
 // The adapters/ directory supplies concrete implementations.
-export {};
+/**
+ * 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 {
+    errorCode;
+    constructor(errorCode, message) {
+        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) {
+    return (typeof err === "object" &&
+        err !== null &&
+        typeof err.errorCode === "string" &&
+        err.errorCode.length > 0);
+}

package/dist/runtime/core/modules/connectors.d.ts

@@ -0,0 +1,53 @@
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { type JobHandler } from "../host.ts";
+import { 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[];
+}
+/**
+ * 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 declare function resolveInstalledConnectors(ctx: RuntimeContext): Promise<Map<string, InstalledPack>>;
+/** 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 declare function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandler;
+/**
+ * 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 declare function mountConnectors(ctx: RuntimeContext, app: AppApi): Promise<ConnectorsHandle>;
+export {};

package/dist/runtime/core/modules/connectors.js

@@ -0,0 +1,204 @@
+// 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 { BpmnError } from "../host.js";
+import { workerJobType } from "../manifest.js";
+import { drainDefinedWorkers, } from "../../connector-worker-sdk.js";
+function joinRoot(root, p) {
+    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) {
+    const seen = new Set();
+    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(ctx, relPath, opts) {
+    const path = joinRoot(ctx.root, relPath);
+    if (!(await ctx.host.exists(path)))
+        return undefined;
+    try {
+        return JSON.parse(await ctx.host.readTextFile(path));
+    }
+    catch (err) {
+        if (opts?.strict) {
+            throw new Error(`failed to parse ${relPath}: ${err.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) {
+    const out = new Map();
+    const pkg = await readJson(ctx, "package.json", { strict: true });
+    if (!pkg)
+        return out;
+    const names = new Set([
+        ...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(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) {
+    return async (job) => {
+        let outcome;
+        const facade = {
+            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 : {};
+    };
+}
+/**
+ * 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, app) {
+    const decls = (ctx.manifest.workers ?? []).filter((w) => w.connector);
+    const subs = [];
+    const jobTypes = [];
+    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();
+    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();
+            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, jobTypes) {
+    return {
+        name: "connectors",
+        jobTypes,
+        async stop() {
+            await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+        },
+        describe: () => ({ jobTypes }),
+    };
+}

package/dist/runtime/core/modules/datasource.js

@@ -140,11 +140,26 @@ async function applyMigrations(host, db, root, migrationsDir) {
         if (applied.has(file))
             continue;
         const sql = await host.readTextFile(`${dir}/${file}`);
-        db.exec(sql);
-        db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
-            file,
-            new Date(host.now()).toISOString(),
-        ]);
+        // Apply the migration and record it in the ledger atomically. SQLite DDL is
+        // transactional, so wrapping both in one BEGIN/COMMIT makes a migration all-or-nothing:
+        // either the schema change AND its `_urban_migrations` row commit together, or neither
+        // does. Without this, an interruption (or an error later in the file's SQL) can leave the
+        // schema changed but the migration unrecorded — which poisons every future boot, because
+        // the runner then re-applies the "unapplied" migration and hits e.g. "duplicate column".
+        // Migration files must therefore not contain their own transaction-control statements.
+        db.exec("BEGIN");
+        try {
+            db.exec(sql);
+            db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+                file,
+                new Date(host.now()).toISOString(),
+            ]);
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            db.exec("ROLLBACK");
+            throw new Error(`migration "${file}" failed and was rolled back (no partial schema change, not recorded as applied): ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
         newlyApplied.push(file);
     }
     return newlyApplied;

package/dist/runtime/core/modules/workers.js

@@ -68,6 +68,11 @@ export async function mountWorkers(ctx, app) {
         const jobType = workerJobType(decl);
         if (!jobType)
             continue;
+        // Connector-backed workers (a `connector` field, no handler/llm) are mounted
+        // separately by mountConnectors — skip them here silently so they don't trip
+        // the "neither handler nor llm" warning below on every startup.
+        if (decl.connector)
+            continue;
         if (!decl.handler) {
             // LLM-backed worker (schema `oneOf` handler|llm): synthesise a handler that runs
             // the job through the bound LLM (and optional decision rails) instead of loading a