@nanobpm/urban 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export * from "./runtime/index.ts";
 export { createCamundaClient } from "@nanobpm/nano-sdk";
 export * from "./toolkit/index.ts";
 export { defineFlow, declarativeToBpmn, declarativeToLayoutedBpmn, externalJobTypes, envelope, layoutBpmn, toBpmn, toDeployableBpmn, Worker, WorkflowClient, WorkflowError, } from "@nanobpm/workflow";
-export type { FlowBuilder, Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, WorkerOptions, ActivityEvent, } from "@nanobpm/workflow";
+export type { FlowBuilder, TimerStart, Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, WorkerOptions, ActivityEvent, } from "@nanobpm/workflow";

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

@@ -22,6 +22,25 @@ export interface WorkerDecl {
     /** Name of an `llm[]` binding used as the worker (LLM-as-worker). Mutually exclusive with `handler`. */
     llm?: string;
 }
+/**
+ * One named LLM binding (`llm.<id>` in the manifest). A binding is usable as a worker
+ * (LLM-as-worker, ADR 0022 §E role 1) or as a chat surface agent. `provider` selects how
+ * the endpoint is resolved (`"env"` reads it from the environment); `model` is typically
+ * an env template. When `output.decision` is set, the model's JSON reply is fed through
+ * that DMN decision (the "rails") and the decision's output is returned instead.
+ */
+export interface LlmBinding {
+    /** Provider selector. `"env"` resolves an OpenAI-compatible endpoint from the environment. */
+    provider: string;
+    /** Model id, typically an env template (e.g. `${NANO_APP_LLM_MODEL}`). */
+    model: string;
+    /** Constrains the model's structured output — currently a DMN decision id (the rails). */
+    output?: {
+        decision?: string;
+    };
+    /** Action-API tools the agent may call (chat-agent role; unused by the worker role). */
+    tools?: string[];
+}
 export interface TriggerDecl {
     id: string;
     type: string;
@@ -89,7 +108,7 @@ export interface AppManifest {
     surfaces?: Record<string, SurfaceDecl>;
     actions?: ActionDecl[];
     workers?: WorkerDecl[];
-    llm?: Record<string, unknown>;
+    llm?: Record<string, LlmBinding>;
     security?: Record<string, unknown>;
     [k: string]: unknown;
 }

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

@@ -0,0 +1,65 @@
+import type { LlmBinding } from "../manifest.ts";
+/** Job variables/headers default to untyped JSON. */
+export type LlmVars = Record<string, unknown>;
+/** Reads an environment variable (routed through the host seam). */
+export type EnvLookup = (name: string) => string | undefined;
+/** One chat message on the wire. */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** A resolved provider endpoint (OpenAI-compatible chat completions). */
+export interface ProviderConfig {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+}
+/**
+ * Evaluate a DMN decision (the output "rails"), returning its already-parsed output.
+ * Injected by the caller so this module stays free of any engine/SDK coupling.
+ */
+export type DecisionEvaluator = (decisionId: string, variables: Record<string, unknown>) => Promise<unknown>;
+/** Everything running one LLM job needs, injected for host-agnosticism + testability. */
+export interface LlmRuntime {
+    env: EnvLookup;
+    /** Fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Decision-rails evaluator; required only when a binding sets `output.decision`. */
+    evaluateDecision?: DecisionEvaluator;
+}
+/**
+ * Resolve an OpenAI-compatible endpoint for a binding. `provider: "env"` (the only
+ * built-in today) reads:
+ *   - NANO_APP_LLM_BASE_URL  (default http://localhost:11434/v1 — Ollama's
+ *                             OpenAI-compatible endpoint; override for any host)
+ *   - NANO_APP_LLM_API_KEY   (optional; sent as `Authorization: Bearer` if set)
+ *   - NANO_APP_LLM_MODEL     (fallback when the binding's `model` resolves empty)
+ * The binding's `model` is env-templated (`${VAR}` / `${VAR:-default}`).
+ */
+export declare function resolveProvider(binding: LlmBinding, env: EnvLookup): ProviderConfig;
+/**
+ * Build the chat messages for a job's variables. Input contract:
+ *   - `messages`: a ready `{role,content}[]` (used verbatim), or
+ *   - `prompt`:   a user-message string.
+ * An optional `system` string is prepended.
+ */
+export declare function buildMessages(vars: LlmVars): ChatMessage[];
+/**
+ * Call the model's chat-completions endpoint. When `json` is set, requests a JSON object
+ * response (`response_format`) so structured output can be parsed. Returns the assistant
+ * message text.
+ */
+export declare function callLlm(provider: ProviderConfig, messages: ChatMessage[], opts?: {
+    json?: boolean;
+    fetch?: typeof fetch;
+}): Promise<string>;
+/**
+ * Run one job through the LLM (and optional decision rails). Returns the output variables
+ * the job is completed with.
+ *
+ * - No `output` binding → returns `{ text }` (the raw completion).
+ * - `output` set → requests JSON, parses it; the parsed object is the output.
+ * - `output.decision` set → the parsed JSON is fed to that DMN decision and the decision's
+ *   output is returned (object as-is, scalar wrapped as `{ result }`).
+ */
+export declare function runLlmJob(vars: LlmVars, binding: LlmBinding, rt: LlmRuntime): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,146 @@
+// LLM-as-worker runtime (ADR 0022 §E role 1) — the batteries-included implementation of
+// the manifest's `llm` seam. For every `workers[]` entry that carries an `llm` binding
+// (instead of a `handler` file), `workers.ts` registers a job worker on that task type
+// whose handler is an LLM call — no external connector runtime required.
+//
+// A worker's contract:
+//   { "taskType": "classify", "llm": "classifier" }              // workers[]
+//   "llm": { "classifier": { "provider": "env",                  // llm registry
+//                            "model": "${NANO_APP_LLM_MODEL}",
+//                            "output": { "decision": "risk" } } }
+//
+// The job's input variables drive the prompt (`prompt` string and/or `messages` array,
+// optional `system`); the model's reply becomes the job's output variables. When the
+// binding declares `output.decision`, the model's JSON is fed through that DMN decision
+// (the rails) and the decision's output is returned instead — the LLM proposes, the
+// decision disposes.
+//
+// Provider is configuration, not code: `provider: "env"` resolves an OpenAI-compatible
+// endpoint from the environment, so a fully-local model (Ollama, LM Studio, llama.cpp,
+// vLLM, …) or a hosted API both work unchanged. This module is host-agnostic: env and
+// fetch are injected (env always via the host seam), never read from a concrete runtime.
+import { expandEnvString } from "../manifest.js";
+/**
+ * Resolve an OpenAI-compatible endpoint for a binding. `provider: "env"` (the only
+ * built-in today) reads:
+ *   - NANO_APP_LLM_BASE_URL  (default http://localhost:11434/v1 — Ollama's
+ *                             OpenAI-compatible endpoint; override for any host)
+ *   - NANO_APP_LLM_API_KEY   (optional; sent as `Authorization: Bearer` if set)
+ *   - NANO_APP_LLM_MODEL     (fallback when the binding's `model` resolves empty)
+ * The binding's `model` is env-templated (`${VAR}` / `${VAR:-default}`).
+ */
+export function resolveProvider(binding, env) {
+    if (binding.provider !== "env") {
+        throw new Error(`llm worker: unsupported provider "${binding.provider}" (only "env" is built in — ` +
+            `it resolves an OpenAI-compatible endpoint from NANO_APP_LLM_* env)`);
+    }
+    const baseUrl = (env("NANO_APP_LLM_BASE_URL") ?? "http://localhost:11434/v1").replace(/\/+$/, "");
+    const apiKey = env("NANO_APP_LLM_API_KEY") || undefined;
+    const model = expandEnvString(binding.model ?? "", env) || env("NANO_APP_LLM_MODEL") || "";
+    if (!model) {
+        throw new Error(`llm worker: no model resolved for binding (model="${binding.model}"); ` +
+            `set NANO_APP_LLM_MODEL or a literal model`);
+    }
+    return { baseUrl, apiKey, model };
+}
+/**
+ * Build the chat messages for a job's variables. Input contract:
+ *   - `messages`: a ready `{role,content}[]` (used verbatim), or
+ *   - `prompt`:   a user-message string.
+ * An optional `system` string is prepended.
+ */
+export function buildMessages(vars) {
+    const system = typeof vars.system === "string" ? vars.system : undefined;
+    let msgs;
+    if (Array.isArray(vars.messages)) {
+        if (vars.messages.length === 0) {
+            throw new Error("llm worker: 'messages' must not be an empty array");
+        }
+        msgs = vars.messages.map((m, i) => {
+            const o = m;
+            if (typeof o.content !== "string" ||
+                (o.role !== "user" && o.role !== "assistant" && o.role !== "system")) {
+                throw new Error(`llm worker: messages[${i}] must be { role: user|assistant|system, content: string }`);
+            }
+            return { role: o.role, content: o.content };
+        });
+    }
+    else if (typeof vars.prompt === "string") {
+        msgs = [{ role: "user", content: vars.prompt }];
+    }
+    else {
+        throw new Error("llm worker: job needs a 'prompt' string or a 'messages' array in its variables");
+    }
+    return system ? [{ role: "system", content: system }, ...msgs] : msgs;
+}
+/**
+ * Call the model's chat-completions endpoint. When `json` is set, requests a JSON object
+ * response (`response_format`) so structured output can be parsed. Returns the assistant
+ * message text.
+ */
+export async function callLlm(provider, messages, opts = {}) {
+    const doFetch = opts.fetch ?? fetch;
+    const headers = { "content-type": "application/json" };
+    if (provider.apiKey)
+        headers.authorization = `Bearer ${provider.apiKey}`;
+    const body = { model: provider.model, messages };
+    if (opts.json)
+        body.response_format = { type: "json_object" };
+    const res = await doFetch(`${provider.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        throw new Error(`llm provider returned ${res.status}: ${detail.slice(0, 500)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices?.[0]?.message?.content;
+    if (typeof content !== "string") {
+        throw new Error("llm provider returned no message content");
+    }
+    return content;
+}
+/**
+ * Run one job through the LLM (and optional decision rails). Returns the output variables
+ * the job is completed with.
+ *
+ * - No `output` binding → returns `{ text }` (the raw completion).
+ * - `output` set → requests JSON, parses it; the parsed object is the output.
+ * - `output.decision` set → the parsed JSON is fed to that DMN decision and the decision's
+ *   output is returned (object as-is, scalar wrapped as `{ result }`).
+ */
+export async function runLlmJob(vars, binding, rt) {
+    const wantJson = !!binding.output;
+    const provider = resolveProvider(binding, rt.env);
+    const messages = buildMessages(vars);
+    const text = await callLlm(provider, messages, { json: wantJson, fetch: rt.fetch });
+    if (!wantJson)
+        return { text };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`llm worker: expected JSON output but got: ${text.slice(0, 300)}`);
+    }
+    // response_format asks for a JSON object, but a provider can still return a scalar, array,
+    // or null — none of which is a valid variable map (nor valid decision-rails input).
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`llm worker: expected a JSON object output but got: ${text.slice(0, 300)}`);
+    }
+    const obj = parsed;
+    const decisionId = binding.output?.decision;
+    if (decisionId) {
+        if (!rt.evaluateDecision) {
+            throw new Error(`llm worker: binding declares output.decision "${decisionId}" but no decision ` +
+                `evaluator is available (the engine SDK surface is required for decision rails)`);
+        }
+        const out = await rt.evaluateDecision(decisionId, obj);
+        return out !== null && typeof out === "object" && !Array.isArray(out)
+            ? out
+            : { result: out };
+    }
+    return obj;
+}

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

@@ -1,5 +1,11 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import type { EngineJob } from "../host.ts";
+import { type DecisionEvaluator } from "./llm.ts";
+/** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
+ *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
+ *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
+ *  "is not a function" / `JSON.parse` error. */
+export declare function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator;
 /** A handler as authored by an app: the job plus the injected app API. */
 export type AppJobHandler = (job: EngineJob, app: AppApi) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 /**

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

@@ -2,6 +2,30 @@
 // on the engine. Handlers are resolved by a small, documented contract and are injected
 // with the app's runtime API (datasource + engine + host utils).
 import { workerJobType } from "../manifest.js";
+import { runLlmJob } from "./llm.js";
+/** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
+ *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
+ *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
+ *  "is not a function" / `JSON.parse` error. */
+export function sdkDecisionEvaluator(sdk) {
+    const client = sdk;
+    return async (decisionId, variables) => {
+        if (typeof client.evaluateDecision !== "function") {
+            throw new Error(`llm worker: the engine SDK does not support evaluateDecision ` +
+                `(needed for decision rails "${decisionId}")`);
+        }
+        const res = await client.evaluateDecision({ decisionDefinitionId: decisionId, variables });
+        const out = res?.output;
+        if (typeof out !== "string")
+            return out;
+        try {
+            return JSON.parse(out);
+        }
+        catch {
+            throw new Error(`llm worker: decision "${decisionId}" returned unparseable JSON output: ${out.slice(0, 300)}`);
+        }
+    };
+}
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
@@ -45,12 +69,31 @@ export async function mountWorkers(ctx, app) {
         if (!jobType)
             continue;
         if (!decl.handler) {
-            // llm-backed workers (schema `oneOf` handler|llm) are validated but not yet
-            // executed by the runtime. Skip with a clear warning rather than crashing.
-            ctx.host.log("warn", "skipping worker: llm-backed workers are not yet implemented", {
-                jobType,
-                llm: decl.llm,
+            // 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
+            // handler module. A declared-but-unknown binding is a manifest error → fail loudly.
+            if (!decl.llm) {
+                ctx.host.log("warn", "skipping worker: neither a handler nor an llm binding declared", {
+                    jobType,
+                });
+                continue;
+            }
+            const binding = (ctx.manifest.llm ?? {})[decl.llm];
+            if (!binding) {
+                throw new Error(`worker "${jobType}" references unknown llm binding "${decl.llm}" ` +
+                    `(no llm["${decl.llm}"] in the manifest)`);
+            }
+            const rt = {
+                env: (n) => app.env(n),
+                evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
+            };
+            const wrapped = (job) => runLlmJob(job.variables, binding, rt);
+            const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+                workerName: `${ctx.manifest.id}:${jobType}`,
             });
+            subs.push(sub);
+            jobTypes.push(jobType);
+            ctx.host.log("info", "llm worker registered", { jobType, llm: decl.llm });
             continue;
         }
         const mod = await loadModule(decl.handler);

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
 export { createUrbanApp } from "./core/runtime.ts";
 export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.ts";
-export type { ActionDecl, AppManifest, DataSource, DomainType, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
+export type { ActionDecl, AppManifest, DataSource, DomainType, LlmBinding, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WorkerSubscription, } from "./core/host.ts";
@@ -15,7 +15,9 @@ export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./co
 export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
 export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
-export { resolveHandler } from "./core/modules/workers.ts";
+export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts";
+export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";
+export type { ChatMessage, DecisionEvaluator, EnvLookup, LlmRuntime, LlmVars, ProviderConfig, } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 export { createNodeHost } from "./adapters/node.ts";
 export { createDenoHost } from "./adapters/deno.ts";

package/dist/runtime/index.js

@@ -10,7 +10,8 @@ export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.js";
-export { resolveHandler } from "./core/modules/workers.js";
+export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
+export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.8.0",
+  "version": "0.10.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",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/nano-sdk": "^1.2.0",
-    "@nanobpm/workflow": "^0.6.0",
+    "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
     "create-urban-app": "^0.2.0"
   },

package/src/index.ts

@@ -41,6 +41,7 @@ export {
 } from "@nanobpm/workflow";
 export type {
   FlowBuilder,
+  TimerStart,
   Envelope,
   EnvelopeType,
   EnvelopeField,

package/src/runtime/core/manifest.ts

@@ -32,6 +32,24 @@ export interface WorkerDecl {
   llm?: string;
 }
 
+/**
+ * One named LLM binding (`llm.<id>` in the manifest). A binding is usable as a worker
+ * (LLM-as-worker, ADR 0022 §E role 1) or as a chat surface agent. `provider` selects how
+ * the endpoint is resolved (`"env"` reads it from the environment); `model` is typically
+ * an env template. When `output.decision` is set, the model's JSON reply is fed through
+ * that DMN decision (the "rails") and the decision's output is returned instead.
+ */
+export interface LlmBinding {
+  /** Provider selector. `"env"` resolves an OpenAI-compatible endpoint from the environment. */
+  provider: string;
+  /** Model id, typically an env template (e.g. `${NANO_APP_LLM_MODEL}`). */
+  model: string;
+  /** Constrains the model's structured output — currently a DMN decision id (the rails). */
+  output?: { decision?: string };
+  /** Action-API tools the agent may call (chat-agent role; unused by the worker role). */
+  tools?: string[];
+}
+
 export interface TriggerDecl {
   id: string;
   type: string;
@@ -86,7 +104,7 @@ export interface AppManifest {
   surfaces?: Record<string, SurfaceDecl>;
   actions?: ActionDecl[];
   workers?: WorkerDecl[];
-  llm?: Record<string, unknown>;
+  llm?: Record<string, LlmBinding>;
   security?: Record<string, unknown>;
   [k: string]: unknown;
 }

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

@@ -0,0 +1,237 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { LlmBinding } from "../manifest.ts";
+import {
+  buildMessages,
+  callLlm,
+  type ChatMessage,
+  type EnvLookup,
+  resolveProvider,
+  runLlmJob,
+} from "./llm.ts";
+
+const noEnv: EnvLookup = () => undefined;
+const envOf =
+  (m: Record<string, string>): EnvLookup =>
+  (k) =>
+    m[k];
+
+/** A minimal fetch double returning a fixed chat-completion. */
+function fakeFetch(
+  content: string,
+  opts: { ok?: boolean; status?: number; capture?: (url: string, init: RequestInit) => void } = {},
+): typeof fetch {
+  return (async (url: string, init: RequestInit) => {
+    opts.capture?.(String(url), init);
+    return {
+      ok: opts.ok ?? true,
+      status: opts.status ?? 200,
+      json: async () => ({ choices: [{ message: { content } }] }),
+      text: async () => content,
+    };
+  }) as unknown as typeof fetch;
+}
+
+// --- resolveProvider -------------------------------------------------------
+
+test("resolveProvider defaults to the local Ollama endpoint and env-templates the model", () => {
+  const binding: LlmBinding = { provider: "env", model: "${NANO_APP_LLM_MODEL}" };
+  const p = resolveProvider(binding, envOf({ NANO_APP_LLM_MODEL: "llama3" }));
+  assert.equal(p.baseUrl, "http://localhost:11434/v1");
+  assert.equal(p.model, "llama3");
+  assert.equal(p.apiKey, undefined);
+});
+
+test("resolveProvider honours NANO_APP_LLM_BASE_URL (trailing slash trimmed) + api key", () => {
+  const p = resolveProvider(
+    { provider: "env", model: "gpt-4o-mini" },
+    envOf({ NANO_APP_LLM_BASE_URL: "https://api.example.com/v1/", NANO_APP_LLM_API_KEY: "sk-x" }),
+  );
+  assert.equal(p.baseUrl, "https://api.example.com/v1");
+  assert.equal(p.model, "gpt-4o-mini");
+  assert.equal(p.apiKey, "sk-x");
+});
+
+test("resolveProvider falls back to NANO_APP_LLM_MODEL when the binding model is empty", () => {
+  const p = resolveProvider({ provider: "env", model: "" }, envOf({ NANO_APP_LLM_MODEL: "phi3" }));
+  assert.equal(p.model, "phi3");
+});
+
+test("resolveProvider throws when no model resolves", () => {
+  assert.throws(() => resolveProvider({ provider: "env", model: "" }, noEnv), /no model resolved/);
+});
+
+test("resolveProvider throws on an unsupported provider", () => {
+  assert.throws(
+    () => resolveProvider({ provider: "openai", model: "gpt" }, noEnv),
+    /unsupported provider "openai"/,
+  );
+});
+
+// --- buildMessages ---------------------------------------------------------
+
+test("buildMessages wraps a prompt string as a single user message", () => {
+  assert.deepEqual(buildMessages({ prompt: "hi" }), [{ role: "user", content: "hi" }]);
+});
+
+test("buildMessages prepends an optional system message", () => {
+  assert.deepEqual(buildMessages({ prompt: "hi", system: "be terse" }), [
+    { role: "system", content: "be terse" },
+    { role: "user", content: "hi" },
+  ]);
+});
+
+test("buildMessages uses a messages array verbatim", () => {
+  const messages: ChatMessage[] = [
+    { role: "user", content: "a" },
+    { role: "assistant", content: "b" },
+  ];
+  assert.deepEqual(buildMessages({ messages }), messages);
+});
+
+test("buildMessages rejects a malformed messages entry", () => {
+  assert.throws(() => buildMessages({ messages: [{ role: "user" }] }), /messages\[0\]/);
+  assert.throws(() => buildMessages({ messages: [{ role: "bogus", content: "x" }] }), /messages\[0\]/);
+});
+
+test("buildMessages requires a prompt or messages", () => {
+  assert.throws(() => buildMessages({}), /needs a 'prompt' string or a 'messages' array/);
+});
+
+test("buildMessages rejects an empty messages array", () => {
+  assert.throws(() => buildMessages({ messages: [] }), /must not be an empty array/);
+});
+
+// --- callLlm ---------------------------------------------------------------
+
+test("callLlm posts to /chat/completions and returns the message content", async () => {
+  let seen: { url: string; init: RequestInit } | undefined;
+  const f = fakeFetch("hello world", { capture: (url, init) => (seen = { url, init }) });
+  const out = await callLlm({ baseUrl: "http://h/v1", model: "m", apiKey: "k" }, [
+    { role: "user", content: "hi" },
+  ], { fetch: f });
+  assert.equal(out, "hello world");
+  assert.equal(seen?.url, "http://h/v1/chat/completions");
+  assert.equal(seen?.init.method, "POST");
+  const headers = seen?.init.headers as Record<string, string>;
+  assert.equal(headers.authorization, "Bearer k");
+  const body = JSON.parse(String(seen?.init.body));
+  assert.equal(body.model, "m");
+  assert.equal(body.response_format, undefined);
+});
+
+test("callLlm requests a JSON object response when json:true", async () => {
+  let body: Record<string, unknown> = {};
+  const f = fakeFetch("{}", { capture: (_u, init) => (body = JSON.parse(String(init.body))) });
+  await callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], {
+    json: true,
+    fetch: f,
+  });
+  assert.deepEqual(body.response_format, { type: "json_object" });
+});
+
+test("callLlm throws on a non-ok provider response", async () => {
+  const f = fakeFetch("boom", { ok: false, status: 500 });
+  await assert.rejects(
+    callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], { fetch: f }),
+    /llm provider returned 500/,
+  );
+});
+
+test("callLlm throws when the provider returns no content", async () => {
+  const f = (async () => ({ ok: true, status: 200, json: async () => ({ choices: [] }) })) as unknown as typeof fetch;
+  await assert.rejects(
+    callLlm({ baseUrl: "http://h/v1", model: "m" }, [{ role: "user", content: "hi" }], { fetch: f }),
+    /no message content/,
+  );
+});
+
+// --- runLlmJob -------------------------------------------------------------
+
+const model = envOf({ NANO_APP_LLM_MODEL: "m" });
+
+test("runLlmJob returns raw text when the binding has no output schema", async () => {
+  const out = await runLlmJob({ prompt: "hi" }, { provider: "env", model: "" }, {
+    env: model,
+    fetch: fakeFetch("plain answer"),
+  });
+  assert.deepEqual(out, { text: "plain answer" });
+});
+
+test("runLlmJob parses JSON output when the binding sets output", async () => {
+  const out = await runLlmJob(
+    { prompt: "classify" },
+    { provider: "env", model: "", output: {} },
+    { env: model, fetch: fakeFetch('{"decision":"risk","score":0.9}') },
+  );
+  assert.deepEqual(out, { decision: "risk", score: 0.9 });
+});
+
+test("runLlmJob throws when JSON output is expected but not returned", async () => {
+  await assert.rejects(
+    runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: {} }, {
+      env: model,
+      fetch: fakeFetch("not json"),
+    }),
+    /expected JSON output/,
+  );
+});
+
+test("runLlmJob rejects a non-object JSON output (scalar/array/null)", async () => {
+  for (const bad of ["42", "[1,2]", "null", '"just a string"']) {
+    await assert.rejects(
+      runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: {} }, {
+        env: model,
+        fetch: fakeFetch(bad),
+      }),
+      /expected a JSON object output/,
+      `should reject ${bad}`,
+    );
+  }
+});
+
+test("runLlmJob feeds parsed JSON through the decision rails and returns its output", async () => {
+  const calls: Array<{ id: string; vars: Record<string, unknown> }> = [];
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    {
+      env: model,
+      fetch: fakeFetch('{"amount":100}'),
+      evaluateDecision: async (id, vars) => {
+        calls.push({ id, vars });
+        return { approved: true };
+      },
+    },
+  );
+  assert.deepEqual(out, { approved: true });
+  assert.deepEqual(calls, [{ id: "risk", vars: { amount: 100 } }]);
+});
+
+test("runLlmJob wraps a scalar decision output as { result }", async () => {
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    { env: model, fetch: fakeFetch("{}"), evaluateDecision: async () => "APPROVE" },
+  );
+  assert.deepEqual(out, { result: "APPROVE" });
+});
+
+test("runLlmJob wraps an array decision output as { result } (not a var map)", async () => {
+  const out = await runLlmJob(
+    { prompt: "x" },
+    { provider: "env", model: "", output: { decision: "risk" } },
+    { env: model, fetch: fakeFetch("{}"), evaluateDecision: async () => [1, 2] },
+  );
+  assert.deepEqual(out, { result: [1, 2] });
+});
+
+test("runLlmJob throws when decision rails are declared but no evaluator is available", async () => {
+  await assert.rejects(
+    runLlmJob({ prompt: "x" }, { provider: "env", model: "", output: { decision: "risk" } }, {
+      env: model,
+      fetch: fakeFetch("{}"),
+    }),
+    /no decision evaluator is available/,
+  );
+});

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

@@ -0,0 +1,209 @@
+// LLM-as-worker runtime (ADR 0022 §E role 1) — the batteries-included implementation of
+// the manifest's `llm` seam. For every `workers[]` entry that carries an `llm` binding
+// (instead of a `handler` file), `workers.ts` registers a job worker on that task type
+// whose handler is an LLM call — no external connector runtime required.
+//
+// A worker's contract:
+//   { "taskType": "classify", "llm": "classifier" }              // workers[]
+//   "llm": { "classifier": { "provider": "env",                  // llm registry
+//                            "model": "${NANO_APP_LLM_MODEL}",
+//                            "output": { "decision": "risk" } } }
+//
+// The job's input variables drive the prompt (`prompt` string and/or `messages` array,
+// optional `system`); the model's reply becomes the job's output variables. When the
+// binding declares `output.decision`, the model's JSON is fed through that DMN decision
+// (the rails) and the decision's output is returned instead — the LLM proposes, the
+// decision disposes.
+//
+// Provider is configuration, not code: `provider: "env"` resolves an OpenAI-compatible
+// endpoint from the environment, so a fully-local model (Ollama, LM Studio, llama.cpp,
+// vLLM, …) or a hosted API both work unchanged. This module is host-agnostic: env and
+// fetch are injected (env always via the host seam), never read from a concrete runtime.
+
+import type { LlmBinding } from "../manifest.ts";
+import { expandEnvString } from "../manifest.ts";
+
+/** Job variables/headers default to untyped JSON. */
+export type LlmVars = Record<string, unknown>;
+
+/** Reads an environment variable (routed through the host seam). */
+export type EnvLookup = (name: string) => string | undefined;
+
+/** One chat message on the wire. */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+/** A resolved provider endpoint (OpenAI-compatible chat completions). */
+export interface ProviderConfig {
+  baseUrl: string;
+  apiKey?: string;
+  model: string;
+}
+
+/**
+ * Evaluate a DMN decision (the output "rails"), returning its already-parsed output.
+ * Injected by the caller so this module stays free of any engine/SDK coupling.
+ */
+export type DecisionEvaluator = (
+  decisionId: string,
+  variables: Record<string, unknown>,
+) => Promise<unknown>;
+
+/** Everything running one LLM job needs, injected for host-agnosticism + testability. */
+export interface LlmRuntime {
+  env: EnvLookup;
+  /** Fetch implementation. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** Decision-rails evaluator; required only when a binding sets `output.decision`. */
+  evaluateDecision?: DecisionEvaluator;
+}
+
+/**
+ * Resolve an OpenAI-compatible endpoint for a binding. `provider: "env"` (the only
+ * built-in today) reads:
+ *   - NANO_APP_LLM_BASE_URL  (default http://localhost:11434/v1 — Ollama's
+ *                             OpenAI-compatible endpoint; override for any host)
+ *   - NANO_APP_LLM_API_KEY   (optional; sent as `Authorization: Bearer` if set)
+ *   - NANO_APP_LLM_MODEL     (fallback when the binding's `model` resolves empty)
+ * The binding's `model` is env-templated (`${VAR}` / `${VAR:-default}`).
+ */
+export function resolveProvider(binding: LlmBinding, env: EnvLookup): ProviderConfig {
+  if (binding.provider !== "env") {
+    throw new Error(
+      `llm worker: unsupported provider "${binding.provider}" (only "env" is built in — ` +
+        `it resolves an OpenAI-compatible endpoint from NANO_APP_LLM_* env)`,
+    );
+  }
+  const baseUrl = (env("NANO_APP_LLM_BASE_URL") ?? "http://localhost:11434/v1").replace(/\/+$/, "");
+  const apiKey = env("NANO_APP_LLM_API_KEY") || undefined;
+  const model = expandEnvString(binding.model ?? "", env) || env("NANO_APP_LLM_MODEL") || "";
+  if (!model) {
+    throw new Error(
+      `llm worker: no model resolved for binding (model="${binding.model}"); ` +
+        `set NANO_APP_LLM_MODEL or a literal model`,
+    );
+  }
+  return { baseUrl, apiKey, model };
+}
+
+/**
+ * Build the chat messages for a job's variables. Input contract:
+ *   - `messages`: a ready `{role,content}[]` (used verbatim), or
+ *   - `prompt`:   a user-message string.
+ * An optional `system` string is prepended.
+ */
+export function buildMessages(vars: LlmVars): ChatMessage[] {
+  const system = typeof vars.system === "string" ? vars.system : undefined;
+
+  let msgs: ChatMessage[];
+  if (Array.isArray(vars.messages)) {
+    if (vars.messages.length === 0) {
+      throw new Error("llm worker: 'messages' must not be an empty array");
+    }
+    msgs = (vars.messages as unknown[]).map((m, i) => {
+      const o = m as { role?: unknown; content?: unknown };
+      if (
+        typeof o.content !== "string" ||
+        (o.role !== "user" && o.role !== "assistant" && o.role !== "system")
+      ) {
+        throw new Error(
+          `llm worker: messages[${i}] must be { role: user|assistant|system, content: string }`,
+        );
+      }
+      return { role: o.role, content: o.content };
+    });
+  } else if (typeof vars.prompt === "string") {
+    msgs = [{ role: "user", content: vars.prompt }];
+  } else {
+    throw new Error(
+      "llm worker: job needs a 'prompt' string or a 'messages' array in its variables",
+    );
+  }
+
+  return system ? [{ role: "system", content: system }, ...msgs] : msgs;
+}
+
+/**
+ * Call the model's chat-completions endpoint. When `json` is set, requests a JSON object
+ * response (`response_format`) so structured output can be parsed. Returns the assistant
+ * message text.
+ */
+export async function callLlm(
+  provider: ProviderConfig,
+  messages: ChatMessage[],
+  opts: { json?: boolean; fetch?: typeof fetch } = {},
+): Promise<string> {
+  const doFetch = opts.fetch ?? fetch;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (provider.apiKey) headers.authorization = `Bearer ${provider.apiKey}`;
+  const body: Record<string, unknown> = { model: provider.model, messages };
+  if (opts.json) body.response_format = { type: "json_object" };
+
+  const res = await doFetch(`${provider.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`llm provider returned ${res.status}: ${detail.slice(0, 500)}`);
+  }
+  const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> };
+  const content = data.choices?.[0]?.message?.content;
+  if (typeof content !== "string") {
+    throw new Error("llm provider returned no message content");
+  }
+  return content;
+}
+
+/**
+ * Run one job through the LLM (and optional decision rails). Returns the output variables
+ * the job is completed with.
+ *
+ * - No `output` binding → returns `{ text }` (the raw completion).
+ * - `output` set → requests JSON, parses it; the parsed object is the output.
+ * - `output.decision` set → the parsed JSON is fed to that DMN decision and the decision's
+ *   output is returned (object as-is, scalar wrapped as `{ result }`).
+ */
+export async function runLlmJob(
+  vars: LlmVars,
+  binding: LlmBinding,
+  rt: LlmRuntime,
+): Promise<Record<string, unknown>> {
+  const wantJson = !!binding.output;
+  const provider = resolveProvider(binding, rt.env);
+  const messages = buildMessages(vars);
+  const text = await callLlm(provider, messages, { json: wantJson, fetch: rt.fetch });
+
+  if (!wantJson) return { text };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`llm worker: expected JSON output but got: ${text.slice(0, 300)}`);
+  }
+  // response_format asks for a JSON object, but a provider can still return a scalar, array,
+  // or null — none of which is a valid variable map (nor valid decision-rails input).
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`llm worker: expected a JSON object output but got: ${text.slice(0, 300)}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+
+  const decisionId = binding.output?.decision;
+  if (decisionId) {
+    if (!rt.evaluateDecision) {
+      throw new Error(
+        `llm worker: binding declares output.decision "${decisionId}" but no decision ` +
+          `evaluator is available (the engine SDK surface is required for decision rails)`,
+      );
+    }
+    const out = await rt.evaluateDecision(decisionId, obj);
+    return out !== null && typeof out === "object" && !Array.isArray(out)
+      ? (out as Record<string, unknown>)
+      : { result: out };
+  }
+  return obj;
+}

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

@@ -0,0 +1,158 @@
+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 type { AppManifest } from "../manifest.ts";
+import { mountWorkers, sdkDecisionEvaluator } from "./workers.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);
+  }
+}
+
+function makeCtx(
+  manifest: Partial<AppManifest>,
+  engine: MiniEngine,
+): { ctx: RuntimeContext; logs: Array<{ level: string; msg: string }> } {
+  const logs: Array<{ level: string; msg: string }> = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
+    engine: engine as unknown as RuntimeContext["engine"],
+    host: {
+      log: (level: string, msg: string) => logs.push({ level, msg }),
+      importModule: () => Promise.reject(new Error("no modules in this test")),
+    },
+  } as unknown as RuntimeContext;
+  return { ctx, logs };
+}
+
+function makeApp(over: Partial<AppApi> = {}): AppApi {
+  return {
+    env: (n) => ({ NANO_APP_LLM_MODEL: "m" } as Record<string, string>)[n],
+    log: () => {},
+    ...over,
+  } as AppApi;
+}
+
+function fakeFetch(content: string): typeof fetch {
+  return (async () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ choices: [{ message: { content } }] }),
+    text: async () => content,
+  })) as unknown as typeof fetch;
+}
+
+const orig = globalThis.fetch;
+function withFetch(content: string, fn: () => Promise<void>): Promise<void> {
+  globalThis.fetch = fakeFetch(content);
+  return fn().finally(() => {
+    globalThis.fetch = orig;
+  });
+}
+
+test("mountWorkers registers an llm-bound worker and runs the job through the model", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    {
+      workers: [{ taskType: "classify", llm: "classifier" }],
+      llm: { classifier: { provider: "env", model: "" } },
+    },
+    engine,
+  );
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, ["classify"]);
+  assert.ok(logs.some((l) => l.msg === "llm worker registered"));
+
+  await withFetch("hi there", async () => {
+    const out = await engine.deliver("classify", {
+      jobKey: "j1",
+      jobType: "classify",
+      variables: { prompt: "who are you" },
+    });
+    assert.deepEqual(out, { text: "hi there" });
+  });
+  await handle.stop();
+});
+
+test("mountWorkers throws when an llm worker references an unknown binding", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx(
+    { workers: [{ taskType: "classify", llm: "missing" }], llm: {} },
+    engine,
+  );
+  await assert.rejects(mountWorkers(ctx, makeApp()), /unknown llm binding "missing"/);
+});
+
+test("mountWorkers skips (with a warning) a worker with neither handler nor llm", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx({ workers: [{ taskType: "orphan" }] }, engine);
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, []);
+  assert.ok(logs.some((l) => l.level === "warn" && /neither a handler nor an llm/.test(l.msg)));
+});
+
+test("an llm worker with decision rails uses app.sdk to evaluate the decision", async () => {
+  const engine = new MiniEngine();
+  const evaluated: Array<{ id: string; vars: Record<string, unknown> }> = [];
+  const sdk = {
+    evaluateDecision: async (input: { decisionDefinitionId: string; variables: Record<string, unknown> }) => {
+      evaluated.push({ id: input.decisionDefinitionId, vars: input.variables });
+      return { output: JSON.stringify({ approved: true }) };
+    },
+  };
+  const { ctx } = makeCtx(
+    {
+      workers: [{ taskType: "risk", llm: "risker" }],
+      llm: { risker: { provider: "env", model: "", output: { decision: "risk-table" } } },
+    },
+    engine,
+  );
+  await mountWorkers(ctx, makeApp({ sdk: sdk as unknown as AppApi["sdk"] }));
+
+  await withFetch('{"amount":100}', async () => {
+    const out = await engine.deliver("risk", {
+      jobKey: "j1",
+      jobType: "risk",
+      variables: { prompt: "score it" },
+    });
+    assert.deepEqual(out, { approved: true });
+  });
+  assert.deepEqual(evaluated, [{ id: "risk-table", vars: { amount: 100 } }]);
+});
+
+test("sdkDecisionEvaluator parses the decision's JSON-string output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: JSON.stringify({ ok: 1 }) }),
+  });
+  assert.deepEqual(await evaluate("d", {}), { ok: 1 });
+});
+
+test("sdkDecisionEvaluator passes through a non-string output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: { ok: 2 } }),
+  });
+  assert.deepEqual(await evaluate("d", {}), { ok: 2 });
+});
+
+test("sdkDecisionEvaluator throws with decision context on unparseable output", async () => {
+  const evaluate = sdkDecisionEvaluator({
+    evaluateDecision: async () => ({ output: "not json" }),
+  });
+  await assert.rejects(evaluate("risk", {}), /decision "risk" returned unparseable JSON/);
+});
+
+test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecision", async () => {
+  const evaluate = sdkDecisionEvaluator({});
+  await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
+});

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

@@ -5,6 +5,42 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import { workerJobType, type WorkerDecl } from "../manifest.ts";
+import { type DecisionEvaluator, type LlmRuntime, runLlmJob } from "./llm.ts";
+
+/** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
+ *  whose `output` comes back as a JSON string (the orchestration-cluster contract). */
+interface DecisionCapableSdk {
+  evaluateDecision(input: {
+    decisionDefinitionId: string;
+    variables: Record<string, unknown>;
+  }): Promise<{ output?: unknown }>;
+}
+
+/** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
+ *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
+ *  SDK shape and adds decision context to a parse failure rather than surfacing a raw
+ *  "is not a function" / `JSON.parse` error. */
+export function sdkDecisionEvaluator(sdk: unknown): DecisionEvaluator {
+  const client = sdk as Partial<DecisionCapableSdk>;
+  return async (decisionId, variables) => {
+    if (typeof client.evaluateDecision !== "function") {
+      throw new Error(
+        `llm worker: the engine SDK does not support evaluateDecision ` +
+          `(needed for decision rails "${decisionId}")`,
+      );
+    }
+    const res = await client.evaluateDecision({ decisionDefinitionId: decisionId, variables });
+    const out = res?.output;
+    if (typeof out !== "string") return out;
+    try {
+      return JSON.parse(out);
+    } catch {
+      throw new Error(
+        `llm worker: decision "${decisionId}" returned unparseable JSON output: ${out.slice(0, 300)}`,
+      );
+    }
+  };
+}
 
 /** A handler as authored by an app: the job plus the injected app API. */
 export type AppJobHandler = (
@@ -59,12 +95,33 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
     const jobType = workerJobType(decl);
     if (!jobType) continue;
     if (!decl.handler) {
-      // llm-backed workers (schema `oneOf` handler|llm) are validated but not yet
-      // executed by the runtime. Skip with a clear warning rather than crashing.
-      ctx.host.log("warn", "skipping worker: llm-backed workers are not yet implemented", {
-        jobType,
-        llm: decl.llm,
+      // 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
+      // handler module. A declared-but-unknown binding is a manifest error → fail loudly.
+      if (!decl.llm) {
+        ctx.host.log("warn", "skipping worker: neither a handler nor an llm binding declared", {
+          jobType,
+        });
+        continue;
+      }
+      const binding = (ctx.manifest.llm ?? {})[decl.llm];
+      if (!binding) {
+        throw new Error(
+          `worker "${jobType}" references unknown llm binding "${decl.llm}" ` +
+            `(no llm["${decl.llm}"] in the manifest)`,
+        );
+      }
+      const rt: LlmRuntime = {
+        env: (n) => app.env(n),
+        evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
+      };
+      const wrapped: JobHandler = (job) => runLlmJob(job.variables, binding, rt);
+      const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+        workerName: `${ctx.manifest.id}:${jobType}`,
       });
+      subs.push(sub);
+      jobTypes.push(jobType);
+      ctx.host.log("info", "llm worker registered", { jobType, llm: decl.llm });
       continue;
     }
     const mod = await loadModule(decl.handler);

package/src/runtime/index.ts

@@ -21,6 +21,7 @@ export type {
   AppManifest,
   DataSource,
   DomainType,
+  LlmBinding,
   SurfaceDecl,
   TriggerDecl,
   TypeField,
@@ -67,7 +68,21 @@ export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./co
 export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
 export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
-export { resolveHandler } from "./core/modules/workers.ts";
+export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts";
+export {
+  buildMessages,
+  callLlm,
+  resolveProvider,
+  runLlmJob,
+} from "./core/modules/llm.ts";
+export type {
+  ChatMessage,
+  DecisionEvaluator,
+  EnvLookup,
+  LlmRuntime,
+  LlmVars,
+  ProviderConfig,
+} from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
 // Adapters + engine + run entrypoint