@nanobpm/urban 0.7.0 → 0.9.0

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/core/validate.test.ts

@@ -29,6 +29,14 @@ test("unknown top-level keys are rejected (additionalProperties:false)", () => {
   assert.ok(issues.some((i) => i.path === "bogus"));
 });
 
+test("an `actions` array is an accepted top-level key (ADR 0055 §3)", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    actions: [{ path: "/app/actions/cancel", module: "actions/cancel.ts" }],
+  });
+  assert.deepEqual(issues, []);
+});
+
 test("bad schemaVersion and bad slug id are reported", () => {
   const issues = collectManifestIssues({ ...valid, schemaVersion: 2, id: "Not A Slug" });
   assert.ok(issues.some((i) => i.path === "schemaVersion"));

package/src/runtime/index.ts

@@ -17,9 +17,11 @@ export {
   workerJobType,
 } from "./core/manifest.ts";
 export type {
+  ActionDecl,
   AppManifest,
   DataSource,
   DomainType,
+  LlmBinding,
   SurfaceDecl,
   TriggerDecl,
   TypeField,
@@ -63,8 +65,24 @@ export type {
 } 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";
 
 // Adapters + engine + run entrypoint

package/src/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,