@nanobpm/urban 0.83.0 → 0.85.0

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

@@ -51,6 +51,10 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
     async searchElementInstances() { return []; },
     async searchElementInstanceWaitStates() { return []; },
     async getElementInstance() { return null; },
+    async searchIncidents() { return []; },
+    async resolveIncident() {},
+    async updateJobRetries() {},
+    async setVariables() {},
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
     async close() {},
   };

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

@@ -37,6 +37,10 @@ function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurf
     searchElementInstances: async () => [],
     searchElementInstanceWaitStates: async () => [],
     getElementInstance: async () => null,
+    searchIncidents: async () => [],
+    resolveIncident: async () => {},
+    updateJobRetries: async () => {},
+    setVariables: async () => {},
     registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
     close: async () => {},
   };
@@ -56,6 +60,10 @@ const fakeEngine: EngineClient = {
   searchElementInstances: async () => [],
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };
@@ -400,3 +408,19 @@ test("/api/complete rejects a body with no userTaskKey", async () => {
   assert.equal(res.status, 400);
 });
 
+
+test("MCP is listed as an active surface only when config-enabled, but its route is always mounted", () => {
+  // Default: MCP enabled -> listed as an active surface.
+  const on = mountSurfaces(ctxWith({}), fakeApp);
+  const onEnabled = on.describe().enabled;
+  assert.ok(Array.isArray(onEnabled) && onEnabled.includes("mcp@/app/mcp"), "an enabled MCP surface is listed as active");
+
+  // Config-disabled (URBAN_MCP_ENABLED=false): the handler 404s, so it must NOT appear as active,
+  // yet the route stays mounted for a stable address.
+  const base = ctxWith({});
+  const offCtx = { ...base, host: { ...base.host, env: (v: string) => (v === "URBAN_MCP_ENABLED" ? "false" : undefined) } };
+  const off = mountSurfaces(offCtx, fakeApp);
+  const offEnabled = off.describe().enabled;
+  assert.ok(Array.isArray(offEnabled) && !offEnabled.includes("mcp@/app/mcp"), "a disabled MCP surface must not be listed as active");
+  assert.ok(off.routes.some((r) => r.path === "/app/mcp"), "the MCP route stays mounted even when disabled");
+});

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

@@ -14,6 +14,7 @@ import { completeUserTaskResponse, resolveFormResponse } from "./forms.ts";
 import { mountActions } from "./actions.ts";
 import { mountAgent } from "./agent.ts";
 import { mountApi } from "./api.ts";
+import { mountMcp } from "./mcp.ts";
 import { mountPages } from "./pages.ts";
 
 /** Escape HTML-significant characters before embedding a value in markup. */
@@ -211,6 +212,16 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
   routes.push(...agent.routes);
   enabled.push("agent@/app/agent");
 
+  // The runtime-served MCP surface (ADR 0067): `/app/mcp`, a Streamable-HTTP MCP endpoint mounted
+  // unconditionally (like `/app/agent`) so an MCP client always has a stable address. It projects
+  // the app's read-only OpenAPI operations as tools from the SAME enumeration `mountApi` routes
+  // from, plus framework-owned read-only process-debugging tools — zero app-side MCP code.
+  const mcp = mountMcp(ctx, app, api.routes);
+  routes.push(...mcp.routes);
+  // The route is always mounted (stable address), but only claim MCP as an active surface when it
+  // actually answers — a config-disabled surface 404s, so listing it here would be inaccurate.
+  if (mcp.enabled) enabled.push("mcp@/app/mcp");
+
   // The pages surface (the schema-driven page runtime) mounts its own routes.
   const pages = mountPages(ctx, app);
   if (pages.routes.length > 0) {

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

@@ -38,6 +38,10 @@ class MiniEngine implements EngineClient {
   async searchElementInstances(): Promise<[]> { return []; }
   async searchElementInstanceWaitStates(): Promise<[]> { return []; }
   async getElementInstance(): Promise<null> { return null; }
+  async searchIncidents(): Promise<never[]> { return []; }
+  async resolveIncident(): Promise<void> {}
+  async updateJobRetries(): Promise<void> {}
+  async setVariables(): Promise<void> {}
   async registerWorker(jobType: string): Promise<{ jobType: string; unsubscribe(): Promise<void> }> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -35,6 +35,10 @@ class MiniEngine implements EngineClient {
   async searchElementInstances(): Promise<[]> { return []; }
   async searchElementInstanceWaitStates(): Promise<[]> { return []; }
   async getElementInstance(): Promise<null> { return null; }
+  async searchIncidents(): Promise<never[]> { return []; }
+  async resolveIncident(): Promise<void> {}
+  async updateJobRetries(): Promise<void> {}
+  async setVariables(): Promise<void> {}
   async close(): Promise<void> {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);

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

@@ -41,6 +41,12 @@ class NoopEngine implements EngineClient {
   async getElementInstance() {
     return null;
   }
+  async searchIncidents() {
+    return [];
+  }
+  async resolveIncident() {}
+  async updateJobRetries() {}
+  async setVariables() {}
   async registerWorker(jobType: string): Promise<WorkerSubscription> {
     return { jobType, unsubscribe: async () => {} };
   }

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

@@ -62,6 +62,12 @@ class FakeEngine implements EngineClient {
   async getElementInstance() {
     return null;
   }
+  async searchIncidents() {
+    return [];
+  }
+  async resolveIncident() {}
+  async updateJobRetries() {}
+  async setVariables() {}
   async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };

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

@@ -88,6 +88,22 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("getElementInstance");
       return {};
     },
+    async searchIncidents() {
+      calls.push("searchIncidents");
+      return { items: [] };
+    },
+    async resolveIncident(input) {
+      calls.push("resolveIncident");
+      return { ...input };
+    },
+    async updateJob(input) {
+      calls.push("updateJob");
+      return { ...input };
+    },
+    async createElementInstanceVariables(input) {
+      calls.push("createElementInstanceVariables");
+      return { ...input };
+    },
     async completeUserTask() {
       calls.push("completeUserTask");
       return {};
@@ -729,6 +745,93 @@ test("getElementInstance returns a mapped summary, and null for a blank key or a
   assert.equal(await engine.getElementInstance("missing"), null);
 });
 
+test("searchIncidents normalizes the processInstanceKey selector (trims, drops blank)", async () => {
+  let seenInput: { filter?: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    async searchIncidents(input) {
+      seenInput = input;
+      return { items: [] };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  // A padded key is trimmed before it reaches the engine filter.
+  await engine.searchIncidents({ processInstanceKey: "  7  " });
+  assert.deepEqual(seenInput?.filter, { processInstanceKey: "7" });
+
+  // A whitespace-only key is treated as absent, not forwarded as a garbage filter segment.
+  await engine.searchIncidents({ processInstanceKey: "   " });
+  assert.deepEqual(seenInput?.filter, {});
+
+  // The state selector still passes through untouched.
+  await engine.searchIncidents({ state: "ACTIVE" });
+  assert.deepEqual(seenInput?.filter, { state: "ACTIVE" });
+});
+
+test("resolveIncident normalizes the incidentKey and rejects a blank one", async () => {
+  let seen: { incidentKey: string } | undefined;
+  const client = fakeSdkClient({
+    async resolveIncident(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.resolveIncident({ incidentKey: "  inc-1  " });
+  assert.deepEqual(seen, { incidentKey: "inc-1" });
+
+  await assert.rejects(
+    engine.resolveIncident({ incidentKey: "   " }),
+    /incidentKey must be a non-empty key/,
+  );
+});
+
+test("setVariables normalizes the scopeKey and rejects a blank one", async () => {
+  let seen: Record<string, unknown> | undefined;
+  const client = fakeSdkClient({
+    async createElementInstanceVariables(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.setVariables({ scopeKey: "  ei-9  ", variables: { fixed: true } });
+  assert.deepEqual(seen, { elementInstanceKey: "ei-9", variables: { fixed: true } });
+
+  await assert.rejects(
+    engine.setVariables({ scopeKey: "  ", variables: { fixed: true } }),
+    /scopeKey must be a non-empty key/,
+  );
+});
+
+test("updateJobRetries normalizes the jobKey and rejects a blank key or an invalid retry count", async () => {
+  let seen: { jobKey: string; changeset: Record<string, unknown> } | undefined;
+  const client = fakeSdkClient({
+    async updateJob(input) {
+      seen = input;
+      return { ...input };
+    },
+  });
+  const engine = new SdkEngineClient(client);
+
+  await engine.updateJobRetries({ jobKey: "  j-1  ", retries: 3 });
+  assert.deepEqual(seen, { jobKey: "j-1", changeset: { retries: 3 } });
+
+  await assert.rejects(
+    engine.updateJobRetries({ jobKey: "   ", retries: 3 }),
+    /jobKey must be a non-empty key/,
+  );
+  for (const retries of [-1, 1.5, Number.NaN]) {
+    await assert.rejects(
+      engine.updateJobRetries({ jobKey: "j-1", retries }),
+      /retries must be a non-negative integer/,
+      `retries=${retries} must be rejected`,
+    );
+  }
+});
+
 test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);

package/src/runtime/engine/nanosdk.ts

@@ -21,6 +21,9 @@ import type {
   WaitStateType,
   EngineJob,
   FormSchema,
+  IncidentFilter,
+  IncidentState,
+  IncidentSummary,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
@@ -114,6 +117,26 @@ export function normalizeWaitStateType(raw: unknown): WaitStateType | undefined
   }
 }
 
+/** Map the engine's incident `state` onto the transport-agnostic {@link IncidentState} union,
+ *  falling back to `"UNKNOWN"` for an unrecognized/absent value (an incident is never dropped
+ *  for an odd state — unlike element/process rows, whose state is a hard identity field — so a
+ *  caller still sees the fault). Case-insensitive so a casing tweak doesn't mis-map. */
+export function normalizeIncidentState(raw: unknown): IncidentState {
+  if (typeof raw !== "string") return "UNKNOWN";
+  switch (raw.toUpperCase()) {
+    case "ACTIVE":
+      return "ACTIVE";
+    case "MIGRATED":
+      return "MIGRATED";
+    case "PENDING":
+      return "PENDING";
+    case "RESOLVED":
+      return "RESOLVED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
 /** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
  *  whitespace-only string). Coerces a numeric key to a string (the engine may serialize a key
  *  either way) but never `String(...)`-coerces an arbitrary object into a garbage
@@ -128,6 +151,20 @@ function presentEngineKey(value: unknown): string | undefined {
   return trimmed === "" ? undefined : trimmed;
 }
 
+/** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
+ *  absent/blank (including a whitespace-only string). A mutating seam operation addresses a
+ *  single entity by key, so a blank key is a caller bug that must fail fast with an actionable
+ *  message rather than reach the engine as an empty path segment / invalid changeset and surface
+ *  an opaque transport error. Reuses {@link presentEngineKey}'s trim-and-coerce rule so a padded
+ *  key like `" 5 "` is normalized identically to how read paths resolve it. */
+function requireEngineKey(value: unknown, name: string): string {
+  const key = presentEngineKey(value);
+  if (key === undefined) {
+    throw new Error(`${name} must be a non-empty key`);
+  }
+  return key;
+}
+
 /** A required text field (a wait-state discriminator's `jobType`/`messageName`/`signalName`),
  *  or `undefined` when absent or blank — the caller skips the row rather than emitting a typed
  *  wait state carrying an empty required string. Returns the trimmed value, matching the
@@ -285,6 +322,44 @@ export function mapElementInstanceWaitStateRow(
   }
 }
 
+/** Map one engine incident row onto an {@link IncidentSummary}, or `undefined` when the row is
+ *  malformed (missing the `incidentKey` or the owning `processInstanceKey` — the two identity
+ *  fields a caller needs to resolve/act on it). `jobKey`/`elementInstanceKey`/`errorType`/
+ *  `errorMessage` are best-effort diagnostics: present when the engine reports them, omitted
+ *  otherwise. The single source of truth `searchIncidents` extracts through. */
+export function mapIncidentRow(
+  row: Record<string, unknown>,
+  log: Log,
+): IncidentSummary | undefined {
+  const incidentKey = presentEngineKey(row.incidentKey);
+  if (incidentKey === undefined) {
+    log("warn", "skipping incident with no incidentKey in engine response");
+    return undefined;
+  }
+  const processInstanceKey = presentEngineKey(row.processInstanceKey);
+  if (processInstanceKey === undefined) {
+    log("warn", "skipping incident with no processInstanceKey in engine response", {
+      incidentKey,
+    });
+    return undefined;
+  }
+  const elementId = presentText(row.elementId);
+  const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
+  const jobKey = presentEngineKey(row.jobKey);
+  const errorType = presentText(row.errorType);
+  const errorMessage = presentText(row.errorMessage);
+  return {
+    incidentKey,
+    processInstanceKey,
+    ...(elementId ? { elementId } : {}),
+    ...(elementInstanceKey ? { elementInstanceKey } : {}),
+    ...(jobKey ? { jobKey } : {}),
+    ...(errorType ? { errorType } : {}),
+    ...(errorMessage ? { errorMessage } : {}),
+    state: normalizeIncidentState(row.state),
+  };
+}
+
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -383,6 +458,23 @@ export interface NanoSdkClient {
     consistency?: unknown,
     options?: unknown,
   ): Promise<Record<string, unknown>>;
+  searchIncidents(
+    input: { filter?: Record<string, unknown>; page?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  resolveIncident(
+    input: { incidentKey: string },
+    options?: unknown,
+  ): Promise<unknown>;
+  updateJob(
+    input: { jobKey: string; changeset: Record<string, unknown> },
+    options?: unknown,
+  ): Promise<unknown>;
+  createElementInstanceVariables(
+    input: { elementInstanceKey: string; variables: Record<string, unknown>; local?: boolean },
+    options?: unknown,
+  ): Promise<unknown>;
   createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
   /** Stop every worker created on this client. Used on teardown to also drain a
    * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
@@ -666,6 +758,66 @@ export class SdkEngineClient implements EngineClient {
     return mapElementInstanceRow(body, this.log) ?? null;
   }
 
+  async searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]> {
+    // Same shape as `searchElementInstances`: build the engine filter from the transport-agnostic
+    // selectors, read at zero-wait consistency (an incident search is eventually consistent), and
+    // map each row through the single `mapIncidentRow` gate, dropping malformed rows.
+    const f: Record<string, unknown> = {};
+    // Normalize the request selectors the same way the response mapper normalizes keys: a
+    // whitespace-only/padded `processInstanceKey` must not reach the engine as a garbage filter
+    // segment (which would silently return surprising empty results).
+    const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+    if (processInstanceKey) f.processInstanceKey = processInstanceKey;
+    if (filter?.state) f.state = filter.state;
+    const body = await this.client.searchIncidents(
+      { filter: f },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+    return items.flatMap((it) => {
+      const mapped = mapIncidentRow(it, this.log);
+      return mapped ? [mapped] : [];
+    });
+  }
+
+  async resolveIncident(input: { incidentKey: string }): Promise<void> {
+    await this.client.resolveIncident({
+      incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),
+    });
+  }
+
+  async updateJobRetries(input: { jobKey: string; retries: number }): Promise<void> {
+    // The "retry a failed job" operation: a job's remaining retries are the `retries` field of
+    // the `updateJob` changeset. Bumping them back above zero makes a failed job activatable so a
+    // paired `resolveIncident` can return it to the pool.
+    const jobKey = requireEngineKey(input.jobKey, "jobKey");
+    // `retries` serializes straight into the engine changeset, and `number` admits `NaN`,
+    // fractional, and negative values — none of which is a valid retry count. Reject them up
+    // front so a tool-driven call fails with a clear message instead of an opaque engine error.
+    if (!Number.isInteger(input.retries) || input.retries < 0) {
+      throw new Error("retries must be a non-negative integer");
+    }
+    await this.client.updateJob({
+      jobKey,
+      changeset: { retries: input.retries },
+    });
+  }
+
+  async setVariables(input: {
+    scopeKey: string;
+    variables: Record<string, unknown>;
+    local?: boolean;
+  }): Promise<void> {
+    // A scope is addressed by its element-instance key (the process instance's root scope is an
+    // element instance too), so `scopeKey` maps straight onto `elementInstanceKey`. `local`
+    // defaults to engine behaviour (propagate to the outermost scope) when unset.
+    await this.client.createElementInstanceVariables({
+      elementInstanceKey: requireEngineKey(input.scopeKey, "scopeKey"),
+      variables: input.variables,
+      ...(input.local === undefined ? {} : { local: input.local }),
+    });
+  }
+
   async registerWorker(
     jobType: string,
     handler: JobHandler,

package/src/runtime/index.ts

@@ -96,6 +96,10 @@ export type {
   HttpRequest,
   HttpResponse,
   HttpServer,
+  IncidentState,
+  EngineIncidentState,
+  IncidentFilter,
+  IncidentSummary,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,