@nanobpm/urban 0.4.0 → 0.5.0

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

@@ -0,0 +1,128 @@
+/** A minimal HTTP request as seen by a mounted surface/trigger handler. */
+export interface HttpRequest {
+    method: string;
+    /** Path portion of the URL, e.g. "/tasks". */
+    path: string;
+    /** Parsed query parameters. */
+    query: URLSearchParams;
+    headers: Headers;
+    /** Read the raw request body as text (empty string when there is none). */
+    text(): Promise<string>;
+}
+/** A minimal HTTP response returned by a handler. */
+export interface HttpResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse> | HttpResponse;
+/** A running HTTP server handle. */
+export interface HttpServer {
+    readonly port: number;
+    stop(): Promise<void>;
+}
+/** A tiny synchronous SQLite handle — the subset the runtime needs. */
+export interface SqliteDb {
+    /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
+    exec(sql: string): void;
+    /** Run a parameterised statement, returning the changed-row count. */
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Run a query, returning all rows as plain objects. */
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    close(): void;
+}
+/**
+ * HostContext is the runtime-agnostic capability surface. A Node adapter and a Deno
+ * adapter each implement it; core code depends only on this.
+ */
+export interface HostContext {
+    /** Which concrete runtime is backing this host. */
+    readonly runtime: "node" | "deno";
+    /** Read an environment variable. */
+    env(name: string): string | undefined;
+    /** Read a UTF-8 text file relative to the app root. */
+    readTextFile(path: string): Promise<string>;
+    /** List file names (not directories) directly under `dir`. Returns [] if missing. */
+    listDir(dir: string): Promise<string[]>;
+    /** True if the path exists (file or directory). */
+    exists(path: string): Promise<boolean>;
+    /** Open (creating if needed) a SQLite database at a filesystem path. */
+    openSqlite(path: string): SqliteDb;
+    /**
+     * Dynamically import a handler/module by app-relative path. Path resolution differs
+     * between runtimes, so it lives behind the host seam.
+     */
+    importModule(path: string): Promise<Record<string, unknown>>;
+    /** Start an HTTP server. Routing is done by the caller inside `handler`. */
+    serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+    /** Current wall-clock time in ms since epoch (seam for tests). */
+    now(): number;
+    /** Structured log sink. */
+    log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
+}
+/** A job handed to a worker handler, plus the ack/fail callbacks. */
+export interface EngineJob {
+    jobKey: string;
+    jobType: string;
+    processInstanceKey?: string;
+    elementId?: string;
+    variables: Record<string, unknown>;
+}
+export type JobHandler = (job: EngineJob) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/** A registered worker subscription. */
+export interface WorkerSubscription {
+    readonly jobType: string;
+    unsubscribe(): Promise<void>;
+}
+/**
+ * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
+ * it against a live engine; tests implement it in-memory. Core modules depend only on this.
+ */
+export interface EngineClient {
+    /** Deploy model resources (BPMN/DMN/forms). Returns the number deployed. */
+    deployResources(resources: {
+        name: string;
+        content: string;
+        contentType: string;
+    }[]): Promise<{
+        deployed: number;
+    }>;
+    /** Start a process instance. */
+    createInstance(input: {
+        processDefinitionId: string;
+        variables?: Record<string, unknown>;
+        awaitCompletion?: boolean;
+    }): Promise<{
+        processInstanceKey: string;
+        variables?: Record<string, unknown>;
+    }>;
+    /** Publish a message for correlation. */
+    publishMessage(input: {
+        name: string;
+        correlationKey?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Search open user tasks (optionally by process instance). */
+    searchUserTasks(filter?: {
+        processInstanceKey?: string;
+        assignee?: string;
+        candidateGroup?: string;
+    }): Promise<{
+        userTaskKey: string;
+        elementId?: string;
+        variables?: Record<string, unknown>;
+    }[]>;
+    /** Complete a user task. */
+    completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    /** Register a push worker for a job type. Draining is handled by the adapter. */
+    registerWorker(jobType: string, handler: JobHandler, options?: {
+        workerName?: string;
+        maxParallelJobs?: number;
+        fetchVariables?: string[];
+    }): Promise<WorkerSubscription>;
+    /** Tear down all connections. */
+    close(): Promise<void>;
+}

package/dist/runtime/core/host.js

@@ -0,0 +1,5 @@
+// The host contract — the ONLY seam through which the runtime touches a concrete
+// JavaScript runtime (Node or Deno) or the Nano engine. Everything under core/ is
+// written against these interfaces and MUST NOT import `node:*` or reference `Deno`.
+// The adapters/ directory supplies concrete implementations.
+export {};

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

@@ -0,0 +1,83 @@
+import type { HostContext } from "./host.ts";
+export interface DataSource {
+    driver: string;
+    url: string;
+    migrations?: string;
+}
+export interface TypeField {
+    type: string;
+    optional?: boolean;
+}
+export interface DomainType {
+    name?: string;
+    table?: string;
+    fields?: Record<string, TypeField>;
+}
+export interface WorkerDecl {
+    /** Job/task type the worker subscribes to. Schema allows `taskType` or `type`. */
+    taskType?: string;
+    type?: string;
+    /** Path to the handler module, relative to the app root. Mutually exclusive with `llm`. */
+    handler?: string;
+    /** Name of an `llm[]` binding used as the worker (LLM-as-worker). Mutually exclusive with `handler`. */
+    llm?: string;
+}
+export interface TriggerDecl {
+    id: string;
+    type: string;
+    path?: string;
+    auth?: string;
+    action?: {
+        message?: string;
+        correlationKey?: string;
+    };
+}
+export interface SurfaceDecl {
+    enabled?: boolean;
+    path?: string;
+    agent?: string;
+}
+export interface AppManifest {
+    $schema?: string;
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    codename?: string;
+    runtime?: {
+        engine?: string;
+        node?: string;
+    };
+    models?: {
+        processes?: string[];
+        decisions?: string[];
+        forms?: string[];
+    };
+    data?: {
+        default?: string;
+        sources?: Record<string, DataSource>;
+    };
+    types?: Record<string, DomainType>;
+    triggers?: TriggerDecl[];
+    connections?: Record<string, {
+        type: string;
+        [k: string]: unknown;
+    }>;
+    surfaces?: Record<string, SurfaceDecl>;
+    workers?: WorkerDecl[];
+    llm?: Record<string, unknown>;
+    security?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** The normalised job type for a worker declaration (`taskType` preferred, `type` fallback). */
+export declare function workerJobType(w: WorkerDecl): string | undefined;
+/**
+ * Expand `${VAR}` and `${VAR:-default}` placeholders in a string using `lookup`.
+ * Unset vars with no default expand to "" (matching common shell semantics).
+ */
+export declare function expandEnvString(input: string, lookup: (name: string) => string | undefined): string;
+/** Recursively expand env placeholders across every string in a JSON-ish value. */
+export declare function expandEnv<T>(value: T, lookup: (name: string) => string | undefined): T;
+/** Parse a manifest from JSON text and expand env placeholders. Does not validate. */
+export declare function parseManifest(json: string, lookup?: (name: string) => string | undefined): AppManifest;
+/** Load and parse the manifest from the app root using the host (env-expanded). */
+export declare function loadManifest(host: HostContext, manifestPath: string): Promise<AppManifest>;

package/dist/runtime/core/manifest.js

@@ -0,0 +1,45 @@
+// Manifest types (a hand-mirrored subset of nano-app.schema.json — the block shapes the
+// runtime actually consumes) plus env-placeholder expansion and a host-driven loader.
+// The schema itself (src/schema/nano-app.schema.json) remains the source of truth for
+// validation; see validate.ts.
+/** The normalised job type for a worker declaration (`taskType` preferred, `type` fallback). */
+export function workerJobType(w) {
+    return w.taskType ?? w.type;
+}
+const ENV_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+ * Expand `${VAR}` and `${VAR:-default}` placeholders in a string using `lookup`.
+ * Unset vars with no default expand to "" (matching common shell semantics).
+ */
+export function expandEnvString(input, lookup) {
+    return input.replace(ENV_RE, (_m, name, dflt) => {
+        const v = lookup(name);
+        if (v !== undefined && v !== "")
+            return v;
+        return dflt ?? "";
+    });
+}
+/** Recursively expand env placeholders across every string in a JSON-ish value. */
+export function expandEnv(value, lookup) {
+    if (typeof value === "string")
+        return expandEnvString(value, lookup);
+    if (Array.isArray(value))
+        return value.map((v) => expandEnv(v, lookup));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = expandEnv(v, lookup);
+        return out;
+    }
+    return value;
+}
+/** Parse a manifest from JSON text and expand env placeholders. Does not validate. */
+export function parseManifest(json, lookup = () => undefined) {
+    const raw = JSON.parse(json);
+    return expandEnv(raw, lookup);
+}
+/** Load and parse the manifest from the app root using the host (env-expanded). */
+export async function loadManifest(host, manifestPath) {
+    const text = await host.readTextFile(manifestPath);
+    return parseManifest(text, (n) => host.env(n));
+}

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

@@ -0,0 +1,38 @@
+import type { RuntimeContext } from "../context.ts";
+import type { SqliteDb } from "../host.ts";
+import type { DomainType } from "../manifest.ts";
+/** A typed accessor over a table declared in manifest `types`. */
+export declare class TypeRepo {
+    private readonly db;
+    readonly typeName: string;
+    private readonly def;
+    constructor(db: SqliteDb, typeName: string, def: DomainType);
+    private table;
+    private assertFields;
+    insert(row: Record<string, unknown>): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    all<T = Record<string, unknown>>(): T[];
+    query<T = Record<string, unknown>>(where: Record<string, unknown>): T[];
+}
+export interface ProvisionedSource {
+    readonly name: string;
+    readonly driver: string;
+    readonly db: SqliteDb;
+    readonly migrationsApplied: string[];
+    close(): void;
+}
+export declare class DataLayer {
+    private readonly sources;
+    private readonly defaultSource;
+    private readonly types;
+    constructor(sources: Map<string, ProvisionedSource>, defaultSource: string | undefined, types: Record<string, DomainType>);
+    source(name?: string): ProvisionedSource;
+    /** A typed accessor for a declared domain type (uses the default source). */
+    repo(typeName: string, sourceName?: string): TypeRepo;
+    describe(): Record<string, unknown>;
+    closeAll(): void;
+}
+/** Provision every declared source and return the typed data layer. */
+export declare function provisionData(ctx: RuntimeContext): Promise<DataLayer>;

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

@@ -0,0 +1,172 @@
+// datasource — provision the manifest `data` sources and expose typed accessors for the
+// `types` domain model. Only the `sqlite` driver is implemented; other drivers hit an
+// explicit seam (they are declared in the manifest but not yet provisioned). This is the
+// runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
+function sqlitePathFromUrl(url) {
+    // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
+    return url.replace(/^(file|sqlite):(\/\/)?/, "");
+}
+/** A safe unquoted SQL identifier. Table/column names are interpolated directly into SQL,
+ * so reject anything that isn't a plain identifier to prevent invalid SQL / injection. */
+const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertSqlIdent(kind, name) {
+    if (!SQL_IDENT.test(name)) {
+        throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);
+    }
+    return name;
+}
+function parentDir(path) {
+    const i = path.lastIndexOf("/");
+    return i > 0 ? path.slice(0, i) : "";
+}
+/** A typed accessor over a table declared in manifest `types`. */
+export class TypeRepo {
+    db;
+    typeName;
+    def;
+    constructor(db, typeName, def) {
+        this.db = db;
+        this.typeName = typeName;
+        this.def = def;
+    }
+    table() {
+        if (!this.def.table)
+            throw new Error(`type "${this.typeName}" has no table`);
+        return assertSqlIdent("table name", this.def.table);
+    }
+    assertFields(row) {
+        const declared = this.def.fields;
+        if (!declared)
+            return;
+        for (const key of Object.keys(row)) {
+            if (!(key in declared)) {
+                throw new Error(`field "${key}" is not declared on type "${this.typeName}" (guards schema drift)`);
+            }
+            assertSqlIdent("field name", key);
+        }
+    }
+    insert(row) {
+        this.assertFields(row);
+        const keys = Object.keys(row);
+        if (keys.length === 0) {
+            return this.db.run(`INSERT INTO ${this.table()} DEFAULT VALUES`, []);
+        }
+        const cols = keys.join(", ");
+        const placeholders = keys.map(() => "?").join(", ");
+        const sql = `INSERT INTO ${this.table()} (${cols}) VALUES (${placeholders})`;
+        return this.db.run(sql, keys.map((k) => row[k]));
+    }
+    all() {
+        return this.db.all(`SELECT * FROM ${this.table()}`);
+    }
+    query(where) {
+        this.assertFields(where);
+        const keys = Object.keys(where);
+        if (keys.length === 0)
+            return this.all();
+        const clause = keys.map((k) => `${k} = ?`).join(" AND ");
+        return this.db.all(`SELECT * FROM ${this.table()} WHERE ${clause}`, keys.map((k) => where[k]));
+    }
+}
+export class DataLayer {
+    sources;
+    defaultSource;
+    types;
+    constructor(sources, defaultSource, types) {
+        this.sources = sources;
+        this.defaultSource = defaultSource;
+        this.types = types;
+    }
+    source(name) {
+        const key = name ?? this.defaultSource;
+        if (!key)
+            throw new Error("no data source specified and no default configured");
+        const s = this.sources.get(key);
+        if (!s)
+            throw new Error(`no such data source "${key}"`);
+        return s;
+    }
+    /** A typed accessor for a declared domain type (uses the default source). */
+    repo(typeName, sourceName) {
+        const def = this.types[typeName];
+        if (!def)
+            throw new Error(`no such type "${typeName}"`);
+        return new TypeRepo(this.source(sourceName).db, typeName, def);
+    }
+    describe() {
+        return {
+            default: this.defaultSource,
+            sources: [...this.sources.values()].map((s) => ({
+                name: s.name,
+                driver: s.driver,
+                migrations: s.migrationsApplied.length,
+            })),
+        };
+    }
+    closeAll() {
+        for (const s of this.sources.values())
+            s.close();
+    }
+}
+async function applyMigrations(host, db, root, migrationsDir) {
+    const dir = `${root.replace(/\/+$/, "")}/${migrationsDir.replace(/^\/+/, "")}`;
+    if (!(await host.exists(dir)))
+        return [];
+    const files = (await host.listDir(dir)).filter((f) => f.endsWith(".sql")).sort();
+    db.exec("CREATE TABLE IF NOT EXISTS _urban_migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)");
+    const applied = new Set(db.all("SELECT name FROM _urban_migrations").map((r) => r.name));
+    const newlyApplied = [];
+    for (const file of files) {
+        if (applied.has(file))
+            continue;
+        const sql = await host.readTextFile(`${dir}/${file}`);
+        db.exec(sql);
+        db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+            file,
+            new Date(host.now()).toISOString(),
+        ]);
+        newlyApplied.push(file);
+    }
+    return newlyApplied;
+}
+async function provisionSqlite(ctx, name, src) {
+    const dbPath = sqlitePathFromUrl(src.url);
+    const abs = dbPath.startsWith("/") ? dbPath : `${ctx.root.replace(/\/+$/, "")}/${dbPath}`;
+    const dir = parentDir(abs);
+    if (dir && !(await ctx.host.exists(dir))) {
+        // The host API doesn't expose mkdir and openSqlite won't create parent dirs,
+        // so fail fast with a clear, actionable message instead of a low-level
+        // "cannot open" error.
+        throw new Error(`datasource "${name}": directory "${dir}" does not exist — create it before running (the SQLite file cannot be opened otherwise)`);
+    }
+    const db = ctx.host.openSqlite(abs);
+    db.exec("PRAGMA journal_mode=WAL");
+    const migrationsApplied = src.migrations
+        ? await applyMigrations(ctx.host, db, ctx.root, src.migrations)
+        : [];
+    ctx.host.log("info", `datasource: provisioned "${name}"`, {
+        driver: "sqlite",
+        path: abs,
+        migrationsApplied,
+    });
+    return {
+        name,
+        driver: "sqlite",
+        db,
+        migrationsApplied,
+        close: () => db.close(),
+    };
+}
+/** Provision every declared source and return the typed data layer. */
+export async function provisionData(ctx) {
+    const data = ctx.manifest.data;
+    const sources = new Map();
+    for (const [name, src] of Object.entries(data?.sources ?? {})) {
+        if (src.driver !== "sqlite") {
+            throw new Error(`data source "${name}" uses driver "${src.driver}"; only "sqlite" is implemented ` +
+                `(the driver seam is intentionally open for future drivers)`);
+        }
+        sources.set(name, await provisionSqlite(ctx, name, src));
+    }
+    return new DataLayer(sources, data?.default, ctx.manifest.types ?? {});
+}

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

@@ -0,0 +1,6 @@
+import type { RuntimeContext } from "../context.ts";
+/** Deploy all processes, decisions and forms declared under `models`. */
+export declare function deployModels(ctx: RuntimeContext): Promise<{
+    deployed: number;
+    files: string[];
+}>;

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

@@ -0,0 +1,37 @@
+// deploy — resolve the manifest `models` patterns and deploy the resources to the engine.
+import { expandPatterns } from "../glob.js";
+function contentTypeFor(path) {
+    if (path.endsWith(".bpmn"))
+        return "text/xml";
+    if (path.endsWith(".dmn"))
+        return "text/xml";
+    if (path.endsWith(".form"))
+        return "application/json";
+    return "application/octet-stream";
+}
+function baseName(path) {
+    const i = path.lastIndexOf("/");
+    return i >= 0 ? path.slice(i + 1) : path;
+}
+/** Deploy all processes, decisions and forms declared under `models`. */
+export async function deployModels(ctx) {
+    const models = ctx.manifest.models ?? {};
+    const patterns = [
+        ...(models.processes ?? []),
+        ...(models.decisions ?? []),
+        ...(models.forms ?? []),
+    ];
+    const files = await expandPatterns(ctx.host, ctx.root, patterns);
+    if (files.length === 0) {
+        ctx.host.log("info", "deploy: no model files matched", { patterns });
+        return { deployed: 0, files: [] };
+    }
+    const resources = await Promise.all(files.map(async (path) => ({
+        name: baseName(path),
+        content: await ctx.host.readTextFile(path),
+        contentType: contentTypeFor(path),
+    })));
+    const { deployed } = await ctx.engine.deployResources(resources);
+    ctx.host.log("info", "deploy: models deployed", { deployed, files });
+    return { deployed, files };
+}

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

@@ -0,0 +1,11 @@
+import type { RuntimeContext } from "../context.ts";
+export interface SecurityPolicy {
+    readonly mode: string;
+    readonly roles: string[];
+    /** Roles allowed to reach a surface path (empty/undefined ⇒ open). */
+    surfaceRoles(path: string): string[] | undefined;
+    /** Roles allowed to perform an action key (supports `prefix/*` rules). */
+    actionRoles(action: string): string[] | undefined;
+    describe(): Record<string, unknown>;
+}
+export declare function mountSecurity(ctx: RuntimeContext): SecurityPolicy;

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

@@ -0,0 +1,32 @@
+// security — parse the manifest `security` block into a policy the runtime can consult
+// (ADR 0028). Provider login (OIDC/password) is out of scope for this slice; what we
+// materialize is the declarative role→action/surface/data rule set plus a `local` mode
+// fallback, so hosts can enforce access consistently. Enforcement middleware can layer on
+// this policy later.
+function matchRule(rules, key) {
+    if (!rules)
+        return undefined;
+    if (rules[key])
+        return rules[key];
+    // support "prefix/*" wildcard rules
+    for (const [pat, roles] of Object.entries(rules)) {
+        if (pat.endsWith("/*") && key.startsWith(pat.slice(0, -1)))
+            return roles;
+    }
+    return undefined;
+}
+export function mountSecurity(ctx) {
+    const sec = (ctx.manifest.security ?? {});
+    const mode = sec.mode ?? "local";
+    const roles = sec.roles ?? [];
+    const surfaces = sec.rules?.surfaces;
+    const actions = sec.rules?.actions;
+    ctx.host.log("info", "security policy loaded", { mode, roles });
+    return {
+        mode,
+        roles,
+        surfaceRoles: (path) => matchRule(surfaces, path),
+        actionRoles: (action) => matchRule(actions, action),
+        describe: () => ({ mode, roles, surfaces: surfaces ?? {}, actions: actions ?? {} }),
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import { type Route } from "../router.ts";
+export interface SurfacesHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/** Mount the enabled surfaces and return their routes. */
+export declare function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle;

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

@@ -0,0 +1,88 @@
+// surfaces — the hosted human surfaces (ADR 0026). Implements the `taskInbox` surface: a
+// small JSON+HTML task list backed by the engine's user-task search, that renders the
+// 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";
+/** Escape HTML-significant characters before embedding a value in markup. */
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+function inboxPage(basePath) {
+    return `<!doctype html><meta charset="utf-8"><title>Task inbox</title>
+<style>body{font:14px system-ui,sans-serif;margin:2rem;max-width:52rem}
+li{margin:.4rem 0}code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}</style>
+<h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
+<script>
+fetch(${JSON.stringify(basePath)}+'/api/tasks').then(r=>r.json()).then(ts=>{
+  const ul=document.getElementById('tasks');
+  ul.replaceChildren();
+  if(!ts.length){const li=document.createElement('li');li.textContent='No open tasks.';ul.appendChild(li);return;}
+  for(const t of ts){const li=document.createElement('li');
+    const code=document.createElement('code');
+    code.textContent=t.elementId||t.userTaskKey;
+    li.appendChild(code);
+    li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
+    ul.appendChild(li);}
+});
+</script>`;
+}
+/** Mount the enabled surfaces and return their routes. */
+export function mountSurfaces(ctx, app) {
+    const routes = [];
+    const surfaces = ctx.manifest.surfaces ?? {};
+    const enabled = [];
+    const inbox = surfaces.taskInbox;
+    if (inbox?.enabled) {
+        const base = normalizeRoutePath(inbox.path, "/tasks");
+        enabled.push(`taskInbox@${base}`);
+        routes.push({
+            method: "GET",
+            path: base,
+            source: "surface:taskInbox",
+            handler: () => html(inboxPage(base)),
+        });
+        routes.push({
+            method: "GET",
+            path: `${base}/api/tasks`,
+            source: "surface:taskInbox",
+            handler: async (req) => {
+                const pik = req.query.get("processInstanceKey") ?? undefined;
+                const tasks = await app.engine.searchUserTasks(pik ? { processInstanceKey: pik } : undefined);
+                return json(tasks);
+            },
+        });
+        routes.push({
+            method: "POST",
+            path: `${base}/api/complete`,
+            source: "surface:taskInbox",
+            handler: async (req) => {
+                let body;
+                try {
+                    body = JSON.parse((await req.text()) || "{}");
+                }
+                catch {
+                    return json({ error: "invalid JSON body" }, 400);
+                }
+                if (!body.userTaskKey)
+                    return json({ error: "userTaskKey required" }, 400);
+                await app.engine.completeUserTask(body.userTaskKey, body.variables);
+                return json({ ok: true });
+            },
+        });
+    }
+    const chat = surfaces.chat;
+    if (chat?.enabled) {
+        const base = normalizeRoutePath(chat.path, "/chat");
+        enabled.push(`chat@${base}`);
+        routes.push({
+            method: "GET",
+            path: base,
+            source: "surface:chat",
+            handler: () => html(`<!doctype html><meta charset="utf-8"><title>Chat</title>
+<body style="font:14px system-ui;margin:2rem"><h1>Chat</h1>
+<p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
+        });
+    }
+    ctx.host.log("info", "surfaces mounted", { enabled });
+    return { name: "surfaces", routes, describe: () => ({ enabled }) };
+}