@nanobpm/urban 0.4.0 → 0.5.1

package/dist/toolkit/derivers/worker-io.js

@@ -0,0 +1,135 @@
+// Deriver: BPMN models → `worker-io.d.ts`, the worker type map (ADR 0033 §3). Scans each
+// process for service tasks and extracts the Zeebe task type plus the data-envelope in/out
+// contract (io.nanobpm.dataEnvelope.in / .out, carried as zeebe:property). It emits the SAME
+// `worker-io.d.ts` the console generates (a faithful port of `emitWorkerBindings` in the
+// server's domain_types.ts), so the toolkit is a drop-in for the IDE's codegen (ADR 0053).
+import { GENERATED_DIR } from "../artifact.js";
+/** Filename the console uses; kept identical so the artifact is a drop-in. */
+export const WORKER_BINDINGS_DTS = "worker-io.d.ts";
+/** The domain type declarations `worker-io.d.ts` imports from (console: domain-rows.d.ts). */
+export const DOMAIN_DTS = "domain-rows.d.ts";
+const ENVELOPE_IN = "io.nanobpm.dataEnvelope.in";
+const ENVELOPE_OUT = "io.nanobpm.dataEnvelope.out";
+function attr(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return m ? m[1] : undefined;
+}
+function processId(xml) {
+    const m = xml.match(/<bpmn:process\b[^>]*>/);
+    return m ? attr(m[0], "id") : undefined;
+}
+/** Scan one BPMN document for service-task worker I/O. */
+export function scanModelWorkers(xml) {
+    const proc = processId(xml);
+    const out = [];
+    const blockRe = /<bpmn:serviceTask\b([^>]*)>([\s\S]*?)<\/bpmn:serviceTask>/g;
+    let m;
+    while ((m = blockRe.exec(xml)) !== null) {
+        const openAttrs = m[1];
+        const body = m[2];
+        const elementId = attr(`<x ${openAttrs}>`, "id");
+        const tdMatch = body.match(/<zeebe:taskDefinition\b[^>]*>/);
+        if (!tdMatch)
+            continue;
+        const taskType = attr(tdMatch[0], "type");
+        if (!taskType)
+            continue;
+        const io = { taskType, elementId, process: proc };
+        const propRe = /<zeebe:property\b[^>]*>/g;
+        let p;
+        while ((p = propRe.exec(body)) !== null) {
+            const pname = attr(p[0], "name");
+            const pvalue = attr(p[0], "value");
+            if (pname === ENVELOPE_IN && pvalue)
+                io.in = pvalue;
+            else if (pname === ENVELOPE_OUT && pvalue)
+                io.out = pvalue;
+        }
+        out.push(io);
+    }
+    return out;
+}
+// --- Faithful port of the console's emitWorkerBindings (domain_types.ts) so the emitted
+//     worker-io.d.ts is byte-compatible with the IDE's own codegen. ---
+function typeRefFor(id, declared) {
+    return id != null && declared.has(id) ? `DomainTypes[${JSON.stringify(id)}]` : undefined;
+}
+/** Emit `worker-io.d.ts` from worker bindings + the set of declared domain type ids. */
+export function emitWorkerBindings(workers, declaredTypeIds) {
+    const declared = new Set(declaredTypeIds);
+    const propKey = (t) => JSON.stringify(t);
+    const taskTypes = [
+        ...new Set(workers
+            .map((w) => w?.taskType)
+            .filter((t) => typeof t === "string" && t.length > 0)),
+    ];
+    const taskTypeUnion = taskTypes.length > 0
+        ? taskTypes.map((t) => JSON.stringify(t)).join(" | ")
+        : "string";
+    const inputs = [];
+    const outputs = [];
+    for (const w of workers) {
+        if (typeof w?.taskType !== "string" || w.taskType.length === 0)
+            continue;
+        const inRef = typeRefFor(w.inputType, declared);
+        if (inRef)
+            inputs.push(`  ${propKey(w.taskType)}: ${inRef};`);
+        const outRef = typeRefFor(w.outputType, declared);
+        if (outRef)
+            outputs.push(`  ${propKey(w.taskType)}: ${outRef};`);
+    }
+    const header = "// AUTO-GENERATED by nanobpmn from the App manifest (ADR 0033 §3).\n" +
+        "// The bridge from the process model to the worker type system: each declared\n" +
+        "// worker's `taskType` maps to the TS type of its input payload (`job.variables`)\n" +
+        "// and result, so the typed `defineWorker` types a handler by its job type. Do\n" +
+        "// not edit — regenerated from the manifest. Erased to plain JS at compile.\n" +
+        "// eslint-disable\n";
+    const needsRegistry = inputs.length > 0 || outputs.length > 0;
+    const importTypes = needsRegistry
+        ? `import type { DomainTypes } from "./${DOMAIN_DTS}";\n`
+        : "";
+    const inputsIface = inputs.length > 0
+        ? `export interface WorkerInputs {\n${inputs.join("\n")}\n}\n`
+        : `export interface WorkerInputs {}\n`;
+    const outputsIface = outputs.length > 0
+        ? `export interface WorkerOutputs {\n${outputs.join("\n")}\n}\n`
+        : `export interface WorkerOutputs {}\n`;
+    const headersIface = `export interface WorkerHeaders {}\n`;
+    return `${header}\n` +
+        importTypes +
+        `\n/** Untyped fallback for a job whose worker declares no input/output type. */\n` +
+        `export type WorkerVars = Record<string, unknown>;\n\n` +
+        `/** Untyped fallback for a job whose worker declares no custom headers. */\n` +
+        `export type WorkerHdrs = Record<string, unknown>;\n\n` +
+        `/** Every declared worker \`taskType\` (ADR 0033 §3): the model-derived set the\n` +
+        ` * typed \`defineWorker\` accepts, so \`type\` autocompletes and rejects unknown jobs. */\n` +
+        `export type WorkerTaskType = ${taskTypeUnion};\n\n` +
+        `/** Input payload (\`job.variables\`) per declared worker, keyed by \`taskType\`. */\n` +
+        inputsIface +
+        `\n/** Output payload (worker result) per declared worker, keyed by \`taskType\`. */\n` +
+        outputsIface +
+        `\n/** Custom headers (\`job.customHeaders\`) per declared worker, keyed by \`taskType\`.\n` +
+        ` * Header values are strings on the wire, so each declared key maps to \`string\`;\n` +
+        ` * the extra index signature keeps undeclared headers accessible (non-breaking). */\n` +
+        headersIface;
+}
+/**
+ * Derive `nano-generated/worker-io.d.ts` from BPMN models. `declaredTypeIds` is the set of
+ * domain type ids declared in the manifest `types` — an envelope in/out only becomes a typed
+ * ref when it names a declared type (matches the console's typeRefFor).
+ */
+export function deriveWorkerBindings(models, declaredTypeIds = []) {
+    const workers = [];
+    for (const model of [...models].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+        for (const w of scanModelWorkers(model.xml)) {
+            workers.push({ taskType: w.taskType, inputType: w.in, outputType: w.out });
+        }
+    }
+    const content = emitWorkerBindings(workers, declaredTypeIds);
+    return [{ path: `${GENERATED_DIR}/${WORKER_BINDINGS_DTS}`, content }];
+}
+export const workerIoDeriver = {
+    id: "model->worker-io",
+    describe: "Derive worker-io.d.ts (task type + data-envelope in/out) from BPMN models.",
+    derive: ({ models, declaredTypeIds }) => deriveWorkerBindings(models, declaredTypeIds),
+};

package/dist/toolkit/fsio.d.ts

@@ -0,0 +1,2 @@
+import type { GenIO } from "./gen.ts";
+export declare function createNodeGenIO(): GenIO;

package/dist/toolkit/fsio.js

@@ -0,0 +1,35 @@
+// Node/Deno filesystem implementation of the GenIO port. Uses node:fs/promises, which both
+// Node and Deno provide, so a single implementation serves both runtimes.
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export function createNodeGenIO() {
+    return {
+        async readText(path) {
+            return readFile(path, "utf8");
+        },
+        async writeText(path, content) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, content);
+        },
+        async listDir(path) {
+            try {
+                // The GenIO contract is file names only — exclude subdirectories so
+                // pattern expansion never hands a directory to readText()/JSON.parse.
+                const entries = await readdir(path, { withFileTypes: true });
+                return entries.filter((e) => e.isFile()).map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
+        async exists(path) {
+            try {
+                await stat(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/toolkit/gen.d.ts

@@ -0,0 +1,28 @@
+import type { DerivedArtifact } from "./artifact.ts";
+/** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
+export interface GenIO {
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    /** File names (not paths) in a directory; empty if it does not exist. */
+    listDir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+export interface GenOptions {
+    root: string;
+    io: GenIO;
+    manifestFile?: string;
+}
+export interface GenResult {
+    artifacts: DerivedArtifact[];
+    /** Paths that differ from disk (only populated by `check`). */
+    drift: string[];
+}
+declare function join(root: string, rel: string): string;
+declare function dirOf(p: string): string;
+/** Collect all artifacts a run would produce, without touching disk beyond reads. */
+export declare function collectArtifacts(opts: GenOptions): Promise<DerivedArtifact[]>;
+/** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
+export declare function runGen(opts: GenOptions & {
+    check?: boolean;
+}): Promise<GenResult>;
+export { dirOf, join as joinPath };

package/dist/toolkit/gen.js

@@ -0,0 +1,75 @@
+// The gen orchestrator: the one impure edge of the toolkit. It reads an app's manifest and
+// models, runs the pure derivers, and either writes the artifacts to disk (`urban gen`) or
+// compares them against what's on disk and reports drift (`urban gen --check`). The derivers stay
+// pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
+import { sortArtifacts } from "./artifact.js";
+import { deriveMigrations } from "./derivers/migrations.js";
+import { deriveWorkerBindings } from "./derivers/worker-io.js";
+function join(root, rel) {
+    // Trim either separator so callers may pass Windows-style paths; GenIO
+    // implementations accept forward slashes on all platforms.
+    return `${root.replace(/[/\\]+$/, "")}/${rel.replace(/^[/\\]+/, "")}`;
+}
+function dirOf(p) {
+    const i = p.lastIndexOf("/");
+    return i <= 0 ? "." : p.slice(0, i);
+}
+/** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
+async function expandPattern(root, io, pattern) {
+    const star = pattern.indexOf("*");
+    if (star === -1) {
+        return (await io.exists(join(root, pattern))) ? [pattern] : [];
+    }
+    const slash = pattern.lastIndexOf("/", star);
+    const dir = slash === -1 ? "." : pattern.slice(0, slash);
+    const tail = pattern.slice(slash + 1); // e.g. "*.bpmn"
+    const ext = tail.startsWith("*") ? tail.slice(1) : tail;
+    const names = await io.listDir(join(root, dir));
+    return names
+        .filter((n) => n.endsWith(ext))
+        .map((n) => (dir === "." ? n : `${dir}/${n}`))
+        .sort();
+}
+/** Collect all artifacts a run would produce, without touching disk beyond reads. */
+export async function collectArtifacts(opts) {
+    const { root, io } = opts;
+    const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
+    const manifest = JSON.parse(await io.readText(manifestPath));
+    const artifacts = [];
+    // 1. types → migrations
+    if (manifest.types && Object.keys(manifest.types).length > 0) {
+        artifacts.push(...deriveMigrations(manifest));
+    }
+    // 2. models → worker I/O index
+    const procPatterns = manifest.models?.processes ?? [];
+    const models = [];
+    for (const pat of procPatterns) {
+        for (const rel of await expandPattern(root, io, pat)) {
+            models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+        }
+    }
+    if (models.length > 0) {
+        const declaredTypeIds = Object.keys(manifest.types ?? {});
+        artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
+    }
+    return sortArtifacts(artifacts);
+}
+/** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
+export async function runGen(opts) {
+    const artifacts = await collectArtifacts(opts);
+    const { root, io } = opts;
+    const drift = [];
+    for (const a of artifacts) {
+        const abs = join(root, a.path);
+        if (opts.check) {
+            const current = (await io.exists(abs)) ? await io.readText(abs) : null;
+            if (current !== a.content)
+                drift.push(a.path);
+        }
+        else {
+            await io.writeText(abs, a.content);
+        }
+    }
+    return { artifacts, drift };
+}
+export { dirOf, join as joinPath };

package/dist/toolkit/index.d.ts

@@ -0,0 +1,13 @@
+export type { DerivedArtifact, Deriver } from "./artifact.ts";
+export { GENERATED_DIR, sortArtifacts } from "./artifact.ts";
+export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, } from "./derivers/migrations.ts";
+export type { ToolkitManifest, ToolkitType, ToolkitField } from "./derivers/migrations.ts";
+export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.ts";
+export type { ModelSource, WorkerIo, WorkerBindingDecl } from "./derivers/worker-io.ts";
+export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
+    models: import("./derivers/worker-io.ts").ModelSource[];
+    declaredTypeIds: Iterable<string>;
+}>];
+export { collectArtifacts, runGen, joinPath } from "./gen.ts";
+export type { GenIO, GenOptions, GenResult } from "./gen.ts";
+export { createNodeGenIO } from "./fsio.ts";

package/dist/toolkit/index.js

@@ -0,0 +1,15 @@
+// The Urban derivation toolkit — the shared derivation library. The IDE and the
+// `urban gen` CLI are peer callers of these pure derivers (ADR 0053). Code-first
+// process authoring is provided by `@nanobpm/workflow` (`defineFlow`), not here
+// (ADR 0054) — the toolkit derives migrations and worker I/O from the model.
+export { GENERATED_DIR, sortArtifacts } from "./artifact.js";
+// Derivers
+export { deriveMigrations, migrationsDeriver, sqlType, createTableSql, } from "./derivers/migrations.js";
+export { deriveWorkerBindings, emitWorkerBindings, workerIoDeriver, scanModelWorkers, WORKER_BINDINGS_DTS, DOMAIN_DTS, } from "./derivers/worker-io.js";
+// The registry of all derivers (for discovery / IDE migration).
+import { migrationsDeriver } from "./derivers/migrations.js";
+import { workerIoDeriver } from "./derivers/worker-io.js";
+export const DERIVERS = [migrationsDeriver, workerIoDeriver];
+// Gen orchestrator + IO
+export { collectArtifacts, runGen, joinPath } from "./gen.js";
+export { createNodeGenIO } from "./fsio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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",
@@ -19,27 +19,40 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jwulf/nano-ide.git",
+    "url": "git+https://github.com/jwulf/nano-ide.git",
     "directory": "packages/urban"
   },
   "engines": {
     "node": ">=22.6"
   },
   "bin": {
-    "urban": "./src/bin.mjs"
+    "urban": "src/bin.mjs"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./runtime": "./src/runtime/index.ts",
-    "./toolkit": "./src/toolkit/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./toolkit": {
+      "types": "./dist/toolkit/index.d.ts",
+      "default": "./dist/toolkit/index.js"
+    },
+    "./source": "./src/index.ts"
   },
   "files": [
+    "dist",
     "src",
     "README.md"
   ],
   "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs');fs.mkdirSync('dist/runtime/schema',{recursive:true});fs.copyFileSync('src/runtime/schema/nano-app.schema.json','dist/runtime/schema/nano-app.schema.json')\"",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "node --test --experimental-strip-types \"src/**/*.test.ts\"",
     "test:deno": "deno test -A --no-check src/"

package/src/bin.mjs

@@ -1,21 +1,16 @@
 #!/usr/bin/env node
-// Bootstrap for the `urban` CLI. The CLI is shipped as TypeScript source (one source of
-// truth, no build step). Node strips types natively, but versions < 23.6 need the
-// `--experimental-strip-types` flag, so we re-exec node with it when required.
+// Bootstrap for the `urban` CLI. Runs the compiled CLI (dist/cli.js). The package is
+// published as compiled JS + .d.ts because Node cannot strip types for files under
+// node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so no type-stripping flag
+// is needed here.
 
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
-const cli = join(dirname(fileURLToPath(import.meta.url)), "cli.ts");
-const [maj, min] = process.versions.node.split(".").map(Number);
-const needsFlag = maj < 23 || (maj === 23 && min < 6);
+const cli = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "cli.js");
 
-const args = needsFlag
-  ? ["--disable-warning=ExperimentalWarning", "--experimental-strip-types", cli, ...process.argv.slice(2)]
-  : [cli, ...process.argv.slice(2)];
-
-const r = spawnSync(process.execPath, args, { stdio: "inherit" });
+const r = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { stdio: "inherit" });
 if (r.error) {
   console.error(String(r.error.message ?? r.error));
   process.exit(1);

package/src/cli.ts

@@ -19,8 +19,21 @@ import {
 import { scaffold, slugify } from "create-urban-app";
 import { createNodeGenIO, runGen } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
+import { readFileSync } from "node:fs";
+
+// 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(): string {
+  try {
+    const url = new URL("../package.json", import.meta.url);
+    return (JSON.parse(readFileSync(url, "utf8")) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+const VERSION = readVersion();
 
-const VERSION = "0.2.0";
 
 interface Flags {
   root: string;

package/src/index.ts

@@ -15,6 +15,13 @@
 // Runtime — app materialization + hosting
 export * from "./runtime/index.ts";
 
+// The nano-sdk engine client factory: build a client to talk to a Nano/Camunda
+// engine directly, or type an `AppApi.sdk`. The runtime uses this same factory, so a
+// code-first author reaches the full engine surface without a separate
+// `@nanobpm/nano-sdk` dependency. (`EngineSdkClient`, its return type, is re-exported
+// from ./runtime/index.ts above.)
+export { createCamundaClient } from "@nanobpm/nano-sdk";
+
 // Toolkit — derivation library (`urban gen`)
 export * from "./toolkit/index.ts";
 

package/src/runtime/core/context.ts

@@ -1,5 +1,6 @@
 import type { AppManifest } from "./manifest.ts";
 import type { EngineClient, HostContext } from "./host.ts";
+import type { EngineSdkClient } from "../engine/sdk.ts";
 
 /** Everything a runtime module needs. Passed to each module's mount function. */
 export interface RuntimeContext {
@@ -30,6 +31,15 @@ export interface AppApi {
   manifest: AppManifest;
   data: DataLayer;
   engine: EngineClient;
+  /**
+   * The underlying `@nanobpm/nano-sdk` engine client, present when the app runs on
+   * the nano-sdk transport (the default). It exposes the full Camunda
+   * orchestration-cluster surface — decisions, cluster variables, incidents, user
+   * tasks, agents, batch operations — beyond the transport-agnostic `engine` seam,
+   * over the same connection. Undefined when a non-SDK engine is injected (e.g. an
+   * in-memory test double).
+   */
+  sdk?: EngineSdkClient;
   env(name: string): string | undefined;
   log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }

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

@@ -69,7 +69,7 @@ async function makeFixture(): Promise<string> {
     `export const handlers = {
       "wf.claim": async (job, app) => {
         app.data.repo("task").insert({ title: job.variables.title, status: "claimed" });
-        return { claimed: true };
+        return { claimed: true, hasSdk: !!app.sdk, sdkMarker: app.sdk?.__marker };
       },
     };`,
   );
@@ -154,6 +154,51 @@ test("runtime materializes the manifest end-to-end against a fake engine", async
   }
 });
 
+test("threads the engine SDK client onto app.sdk for handlers (SDK-backed engine)", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  class SdkEngine extends FakeEngine {
+    sdk = { __marker: "engine-sdk" };
+  }
+  const engine = new SdkEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+
+  try {
+    const out = (await engine.deliver("wf.claim", {
+      jobKey: "j1",
+      jobType: "wf.claim",
+      variables: { title: "Fix bug" },
+    })) as Record<string, unknown>;
+    assert.equal(out.hasSdk, true, "handler saw app.sdk");
+    assert.equal(out.sdkMarker, "engine-sdk", "app.sdk is the engine's own client");
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("app.sdk is undefined when the engine exposes no SDK client", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  await app.start();
+
+  try {
+    const out = (await engine.deliver("wf.claim", {
+      jobKey: "j1",
+      jobType: "wf.claim",
+      variables: { title: "Fix bug" },
+    })) as Record<string, unknown>;
+    assert.equal(out.hasSdk, false, "no app.sdk for a non-SDK engine");
+    assert.equal(out.sdkMarker, undefined);
+  } finally {
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("stop() resets state so the app can be cleanly restarted", async () => {
   const dir = await makeFixture();
   const host = createNodeHost({ cwd: dir, log: () => {} });

package/src/runtime/core/runtime.ts

@@ -5,6 +5,7 @@
 
 import type { AppApi, Mounted } from "./context.ts";
 import type { EngineClient, HostContext, HttpServer } from "./host.ts";
+import type { EngineSdkClient } from "../engine/sdk.ts";
 import { loadManifest, type AppManifest } from "./manifest.ts";
 import { validateManifest } from "./validate.ts";
 import { makeRouter, type Route } from "./router.ts";
@@ -27,6 +28,13 @@ export function resolvePort(explicit: number | undefined, envPort: string | unde
   return n;
 }
 
+/** Read the underlying nano-sdk client off an engine when it exposes one (the
+ *  `SdkEngineClient` does). Non-SDK engines (e.g. an in-memory test double) have no
+ *  `sdk`, so handlers get `undefined` and fall back to the transport-agnostic seam. */
+function engineSdk(engine: EngineClient): EngineSdkClient | undefined {
+  return (engine as { sdk?: EngineSdkClient }).sdk;
+}
+
 export interface MountFlags {
   deploy?: boolean;
   data?: boolean;
@@ -152,6 +160,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           manifest,
           data,
           engine,
+          sdk: engineSdk(engine),
           env: (n) => host.env(n),
           log: (l, m, f) => host.log(l, m, f),
         };

package/src/runtime/engine/nanosdk.test.ts

@@ -254,6 +254,12 @@ test("close stops every worker and closes the SDK client", async () => {
   assert.equal(client.closed, 1);
 });
 
+test("exposes the underlying nano-sdk client as .sdk", () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  assert.equal(engine.sdk, client, "sdk returns the exact client the adapter was built from");
+});
+
 test("createNanoSdkEngineClient uses an injected client", async () => {
   const client = fakeSdkClient();
   const engine = await createNanoSdkEngineClient({ restAddress: "http://x/v2", client });

package/src/runtime/engine/nanosdk.ts

@@ -17,6 +17,7 @@ import type {
   JobHandler,
   WorkerSubscription,
 } from "../core/host.ts";
+import type { EngineSdkClient } from "./sdk.ts";
 
 /** 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. */
@@ -113,6 +114,15 @@ export class SdkEngineClient implements EngineClient {
     this.log = log;
   }
 
+  /**
+   * The underlying `@nanobpm/nano-sdk` client — the full Camunda orchestration-cluster
+   * surface (decisions, cluster variables, incidents, agents, batch operations, …) over
+   * the same connection. Surfaced to handlers as `AppApi.sdk`.
+   */
+  get sdk(): EngineSdkClient {
+    return this.client as unknown as EngineSdkClient;
+  }
+
   async deployResources(
     resources: { name: string; content: string; contentType: string }[],
   ): Promise<{ deployed: number }> {

package/src/runtime/engine/sdk.ts

@@ -0,0 +1,18 @@
+// The full nano-sdk engine client, surfaced to code-first Urban authors.
+//
+// `AppApi.engine` is the transport-agnostic seam (deploy, create, message, user
+// tasks, workers). When the app runs on the nano-sdk transport, `AppApi.sdk` also
+// carries the underlying `@nanobpm/nano-sdk` client, giving handlers the whole
+// Camunda orchestration-cluster surface — decisions, cluster variables, incidents,
+// agents, batch operations, and more — over the same connection, without a separate
+// `@nanobpm/nano-sdk` dependency.
+//
+// This module is type-only: the `import(...)` type query resolves nano-sdk's types at
+// typecheck and is fully erased at runtime, so re-exporting it from the runtime barrel
+// adds no load-time dependency on nano-sdk.
+
+/** The full nano-sdk (Camunda orchestration-cluster) engine client type — the value
+ *  returned by `createCamundaClient`. */
+export type EngineSdkClient = ReturnType<
+  typeof import("@nanobpm/nano-sdk").createCamundaClient
+>;

package/src/runtime/index.ts

@@ -67,5 +67,6 @@ export type {
   NanoSdkJobWorker,
   NanoSdkJobWorkerConfig,
 } from "./engine/nanosdk.ts";
+export type { EngineSdkClient } from "./engine/sdk.ts";
 export { runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";