@nanobpm/urban 0.7.0 → 0.9.0

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;
@@ -45,6 +64,22 @@ export interface SurfaceDecl {
     /** pages surface: the injected default datasource name. Default `app`. */
     sourceName?: string;
 }
+/**
+ * An app-authored action handler override (ADR 0055 phase 3). Each declaration binds a
+ * route to a handler module (default-exports an `ActionHandler`), letting an app wrap the
+ * generic pages start/cancel/message actions with business logic. Mounted before the
+ * generic pages action routes, so an exact override shadows the generic one.
+ */
+export interface ActionDecl {
+    /** Route path to serve, e.g. "/app/actions/cancel" or "/app/actions/start/convergence-loop". */
+    path: string;
+    /** Handler module path relative to the app root; default-exports an `ActionHandler`. */
+    module: string;
+    /** HTTP method to match. Default "POST". */
+    method?: string;
+    /** Match `path` as a prefix rather than exactly. Default false. */
+    prefix?: boolean;
+}
 export interface AppManifest {
     $schema?: string;
     schemaVersion: 1;
@@ -71,8 +106,9 @@ export interface AppManifest {
         [k: string]: unknown;
     }>;
     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/actions.d.ts

@@ -0,0 +1,45 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+/** The request handed to an action handler: the raw request plus its parsed JSON body. */
+export interface ActionRequest {
+    /** The raw HTTP request (method, path, query, headers). */
+    req: HttpRequest;
+    /**
+     * The request body parsed as JSON (`{}` when the body is empty). A body that is present
+     * but not valid JSON is rejected with `400` before the handler runs.
+     */
+    body: unknown;
+}
+/** What an action handler returns; the runtime serializes `body` as JSON. */
+export interface ActionResult {
+    /** HTTP status. Default `200`, or `204` when the handler returns nothing. */
+    status?: number;
+    /** Response payload, serialized as JSON. Omit for an empty response. */
+    body?: unknown;
+    /** Response headers merged over `content-type: application/json`. */
+    headers?: Record<string, string>;
+}
+/**
+ * An app-authored action handler: the parsed request plus the injected app API. Return an
+ * {@link ActionResult}, or nothing for an empty `204`. Throwing yields a `500` with the
+ * error message.
+ */
+export type ActionHandler = (input: ActionRequest, app: AppApi) => Promise<ActionResult | void> | ActionResult | void;
+/**
+ * Resolve an action handler from a loaded module, in priority order:
+ *   1. `default` (when it is a function — the common one-handler-per-file case)
+ *   2. a named export `handler`
+ */
+export declare function resolveActionHandler(mod: Record<string, unknown>): ActionHandler | undefined;
+export interface ActionsHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the declared action handlers. Each declaration contributes one route; the handler
+ * module is imported lazily (and cached) on first request, so a missing or malformed module
+ * surfaces as a clear `500` on that route rather than failing the whole boot.
+ */
+export declare function mountActions(ctx: RuntimeContext, app: AppApi): ActionsHandle;

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

@@ -0,0 +1,113 @@
+// actions — per-app action handler files (ADR 0055 phase 3). The pages surface serves
+// generic start/cancel/message actions; a real app usually needs to wrap those with
+// business logic (register a domain row before starting, reconcile app-owned rest state
+// on cancel, correlate a message to an aggregate). An app declares such overrides in the
+// manifest `actions[]` and authors a small module per action. Each module is injected with
+// the app's `AppApi` (typed datasource + engine + sdk + host utils) — the same contract as
+// a worker handler — so the handler code reads exactly like the app's own service layer.
+//
+// Precedence: action routes are mounted BEFORE the generic pages action routes (the router
+// is first-match-wins), so an override at `/app/actions/cancel` shadows the generic one,
+// while an unmatched process still falls through to the generic `/app/actions/start/` route.
+import { json, normalizeRoutePath } from "../router.js";
+/**
+ * Resolve an action handler from a loaded module, in priority order:
+ *   1. `default` (when it is a function — the common one-handler-per-file case)
+ *   2. a named export `handler`
+ */
+export function resolveActionHandler(mod) {
+    if (typeof mod.default === "function")
+        return mod.default;
+    if (typeof mod.handler === "function")
+        return mod.handler;
+    return undefined;
+}
+/**
+ * Mount the declared action handlers. Each declaration contributes one route; the handler
+ * module is imported lazily (and cached) on first request, so a missing or malformed module
+ * surfaces as a clear `500` on that route rather than failing the whole boot.
+ */
+export function mountActions(ctx, app) {
+    const decls = (ctx.manifest.actions ?? []);
+    const routes = [];
+    const mounted = [];
+    const joinRoot = (p) => p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+    // Cache module loads so a module reused across several declarations is imported once.
+    const moduleCache = new Map();
+    const loadModule = (path) => {
+        const key = joinRoot(path);
+        let pending = moduleCache.get(key);
+        if (!pending) {
+            // Evict the entry if the import rejects, so a transient failure doesn't
+            // permanently wedge the route (a cached rejected Promise would reject forever).
+            pending = ctx.host.importModule(key).catch((err) => {
+                moduleCache.delete(key);
+                throw err;
+            });
+            moduleCache.set(key, pending);
+        }
+        return pending;
+    };
+    for (const decl of decls) {
+        if (!decl?.path || !decl?.module) {
+            ctx.host.log("warn", "skipping action: needs both `path` and `module`", {
+                action: decl,
+            });
+            continue;
+        }
+        const method = (decl.method ?? "POST").trim().toUpperCase() || "POST";
+        const prefix = decl.prefix === true;
+        // The router's prefix match is a raw `startsWith`, so a prefix route needs a trailing
+        // slash to stay boundary-safe (otherwise "/hooks" would also match "/hooks2"). Exact
+        // routes keep the normalized (trailing-slash-stripped) path. Guard the root case so a
+        // prefix path of "/" doesn't become "//" (which would never match).
+        const base = normalizeRoutePath(decl.path, decl.path);
+        const path = prefix ? (base.endsWith("/") ? base : `${base}/`) : base;
+        routes.push({
+            method,
+            path,
+            prefix,
+            source: `actions:${decl.module}`,
+            handler: async (req) => {
+                const raw = await req.text();
+                let body;
+                try {
+                    body = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    return json({ error: "request body must be JSON" }, 400);
+                }
+                let handler;
+                try {
+                    handler = resolveActionHandler(await loadModule(decl.module));
+                }
+                catch (e) {
+                    ctx.host.log("error", "action handler module failed to load", {
+                        path,
+                        module: decl.module,
+                        error: String(e?.message ?? e),
+                    });
+                    return json({ error: `action handler ${decl.module} failed to load` }, 500);
+                }
+                if (!handler) {
+                    return json({ error: `action handler ${decl.module} exports no default function or named \`handler\`` }, 500);
+                }
+                try {
+                    const result = await handler({ req, body }, app);
+                    if (!result)
+                        return { status: 204 };
+                    return {
+                        status: result.status ?? 200,
+                        headers: { "content-type": "application/json", ...(result.headers ?? {}) },
+                        body: result.body === undefined ? undefined : JSON.stringify(result.body),
+                    };
+                }
+                catch (e) {
+                    return json({ error: String(e?.message ?? e) }, 500);
+                }
+            },
+        });
+        mounted.push({ path, method, module: decl.module, prefix });
+    }
+    return { name: "actions", routes, describe: () => ({ actions: mounted }) };
+}

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/surfaces.js

@@ -3,6 +3,7 @@
 // linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
 // (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
 import { html, json, normalizeRoutePath } from "../router.js";
+import { mountActions } from "./actions.js";
 import { mountPages } from "./pages.js";
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s) {
@@ -84,6 +85,14 @@ export function mountSurfaces(ctx, app) {
 <p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
         });
     }
+    // App-authored action overrides mount BEFORE the generic pages routes so an exact
+    // override (e.g. /app/actions/cancel) shadows the generic action; the router is
+    // first-match-wins.
+    const actions = mountActions(ctx, app);
+    if (actions.routes.length > 0) {
+        routes.push(...actions.routes);
+        enabled.push(`actions(${actions.routes.length})`);
+    }
     // The pages surface (the schema-driven page runtime) mounts its own routes.
     const pages = mountPages(ctx, app);
     if (pages.routes.length > 0) {

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 { 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";
@@ -12,8 +12,12 @@ export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, Row, TableMeta, } from "./core/modules/gateway.ts";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
 export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./core/modules/pages.ts";
+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

@@ -9,7 +9,9 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 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 { resolveHandler } from "./core/modules/workers.js";
+export { mountActions, resolveActionHandler } from "./core/modules/actions.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/dist/runtime/schema/nano-app.schema.json

@@ -52,6 +52,11 @@
       "additionalProperties": { "$ref": "#/$defs/connection" }
     },
     "surfaces": { "$ref": "#/$defs/surfaces" },
+    "actions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/action" },
+      "description": "App-authored action handler overrides (ADR 0055 §3): each binds an HTTP route to a handler module that wraps the generic pages start/cancel/message actions with business logic, injected with the app's runtime API."
+    },
     "workers": {
       "type": "array",
       "items": { "$ref": "#/$defs/worker" },
@@ -367,6 +372,33 @@
         }
       }
     },
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "module"],
+      "description": "An app-authored action handler override (ADR 0055 §3): binds a route to a handler module (default-exports an ActionHandler). Mounted before the generic pages action routes, so an exact override shadows the generic one.",
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Route path to serve, e.g. '/app/actions/cancel' or '/app/actions/start/convergence-loop'."
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Handler module path relative to the app root; default-exports (or names `handler`) an ActionHandler."
+        },
+        "method": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HTTP method to match. Default 'POST'."
+        },
+        "prefix": {
+          "type": "boolean",
+          "description": "Match `path` as a prefix rather than exactly. Default false."
+        }
+      }
+    },
     "llmBinding": {
       "type": "object",
       "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.7.0",
+  "version": "0.9.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",