@nanobpm/urban 0.83.0 → 0.85.0

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

@@ -318,6 +318,51 @@ export interface ElementInstanceWaitStateFilter {
     elementId?: string;
     waitStateType?: WaitStateType;
 }
+/**
+ * The engine's own incident-state enum — the lifecycle states an engine actually reports and
+ * that are valid as a search selector. An `ACTIVE` incident is an open fault a human/agent can
+ * act on (resolve/retry); the other values are terminal or transitional. This is the single
+ * source of truth for real engine states; {@link IncidentState} derives from it.
+ */
+export type EngineIncidentState = "ACTIVE" | "MIGRATED" | "PENDING" | "RESOLVED";
+/**
+ * The lifecycle state of an incident, as {@link EngineClient.searchIncidents} reports it.
+ * Extends {@link EngineIncidentState} with the client-side `"UNKNOWN"` sentinel — a fallback
+ * used when the engine returns an unrecognized/absent value, so an incident is surfaced rather
+ * than dropped for an odd state. Because `"UNKNOWN"` is not a real engine state, it is not a
+ * valid {@link IncidentFilter} selector. A caller narrows on this union rather than probing a
+ * raw string.
+ */
+export type IncidentState = EngineIncidentState | "UNKNOWN";
+/**
+ * Selectors for an incident search: which process instance and/or lifecycle state to match.
+ * Used by {@link EngineClient.searchIncidents}. An eventually consistent (zero-wait) read; an
+ * unset selector matches every incident.
+ */
+export interface IncidentFilter {
+    processInstanceKey?: string;
+    state?: EngineIncidentState;
+}
+/**
+ * A single incident (a stuck token — a job out of retries, an unhandled error, a failed
+ * gateway evaluation) as {@link EngineClient.searchIncidents} reports it. Carries the
+ * `incidentKey` a caller passes to {@link EngineClient.resolveIncident}, the owning
+ * `processInstanceKey`, and — when the incident is job-backed — the `jobKey` a caller passes
+ * to {@link EngineClient.updateJobRetries} to make the job retriable before resolving.
+ * `errorType`/`errorMessage` are the engine's fault description; they are free-form across
+ * engines (the live SDK reports a Camunda error-type enum, the in-process engine a coarser
+ * `kind`), so treat them as diagnostic text, not a stable taxonomy.
+ */
+export interface IncidentSummary {
+    readonly incidentKey: string;
+    readonly processInstanceKey: string;
+    readonly elementId?: string;
+    readonly elementInstanceKey?: string;
+    readonly jobKey?: string;
+    readonly errorType?: string;
+    readonly errorMessage?: string;
+    readonly state: IncidentState;
+}
 /**
  * A deployed form's form-js schema plus its identifying metadata, as
  * {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
@@ -447,6 +492,47 @@ export interface EngineClient {
      * {@link searchElementInstances}.
      */
     getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
+    /**
+     * Search incidents by owning process instance and/or lifecycle state
+     * (`POST /v2/incidents/search`) — the open faults blocking one or more instances (a job out
+     * of retries, an unhandled error, a failed gateway evaluation). An eventually consistent
+     * (zero-wait) read; each {@link IncidentSummary} carries the `incidentKey` to pass to
+     * {@link resolveIncident} and, for a job-backed incident, the `jobKey` to pass to
+     * {@link updateJobRetries}. The debugging counterpart to the read accessors above: where
+     * they answer "how far has this instance progressed", this answers "why is it stuck".
+     */
+    searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    /**
+     * Resolve an open incident by key (`POST /v2/incidents/{incidentKey}/resolution`), unblocking
+     * the parked token: a job incident returns the job to the activatable pool (so it must have
+     * retries left first — see {@link updateJobRetries}), a gateway incident re-evaluates, an
+     * uncaught-error incident re-creates the service-task job. A mutating operation.
+     */
+    resolveIncident(input: {
+        incidentKey: string;
+    }): Promise<void>;
+    /**
+     * Update the remaining retries of a job (`PATCH /v2/jobs/{jobKey}`) — the "retry a failed
+     * job" operation. Setting a failed job's retries back above zero makes it activatable again;
+     * paired with {@link resolveIncident}, this is how a stuck `jobNoRetries` incident is cleared
+     * (bump retries, then resolve). A mutating operation.
+     */
+    updateJobRetries(input: {
+        jobKey: string;
+        retries: number;
+    }): Promise<void>;
+    /**
+     * Set (merge) variables into a scope (`PUT /v2/element-instances/{scopeKey}/variables`).
+     * `scopeKey` is a process-instance key or an element-instance key; when `local` is `true` the
+     * variables are merged strictly into that local scope, otherwise (the default) they propagate
+     * to the outermost scope. A mutating operation used to repair state before resolving an
+     * incident or to steer an instance during debugging.
+     */
+    setVariables(input: {
+        scopeKey: string;
+        variables: Record<string, unknown>;
+        local?: boolean;
+    }): Promise<void>;
     /** Register a push worker for a job type. Draining is handled by the adapter. */
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
@@ -470,4 +556,4 @@ export interface EngineClient {
  * and `getForm` before it) that a purely structural `implements EngineClient` check no
  * longer catches once the fake is published/compiled against an older `@nanobpm/urban`.
  */
-export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "registerWorker", "close"];
+export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];

package/dist/runtime/core/host.js

@@ -69,6 +69,10 @@ export const ENGINE_CLIENT_METHODS = [
     "searchElementInstances",
     "searchElementInstanceWaitStates",
     "getElementInstance",
+    "searchIncidents",
+    "resolveIncident",
+    "updateJobRetries",
+    "setVariables",
     "registerWorker",
     "close",
 ];

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

@@ -13,6 +13,10 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;
 }
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+export declare const API_BASE = "/app/api";
 /**
  * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
  * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
@@ -97,6 +101,7 @@ export declare class NotImplemented extends Error {
 export declare function defineOperation<Req extends OperationContract = DefaultContract, Res = unknown>(_id: string, handler: OperationHandler<Req, Res>): OperationHandler<Req, Res>;
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export declare function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined;
+export declare function readApiBinding(manifest: unknown): ApiBinding | undefined;
 /** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
  *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
  *  the docs without re-deriving the path. */

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

@@ -19,7 +19,7 @@ import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWi
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
-const API_BASE = "/app/api";
+export const API_BASE = "/app/api";
 /** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
  *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
  *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
@@ -147,7 +147,7 @@ export function resolveOperationHandler(mod) {
         return mod.handler;
     return undefined;
 }
-function readApiBinding(manifest) {
+export function readApiBinding(manifest) {
     const raw = manifest && typeof manifest === "object" ? Reflect.get(manifest, "api") : undefined;
     if (!raw || typeof raw !== "object")
         return undefined;

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

@@ -0,0 +1,57 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+export interface McpHandle {
+    readonly name: string;
+    routes: Route[];
+    /** Whether the surface actually answers vs. 404s (config-enabled). The route is always mounted
+     *  for a stable address, so callers deriving an "active surfaces" list must gate on this. */
+    readonly enabled: boolean;
+    describe(): Record<string, unknown>;
+}
+/** Mint a fresh MCP session id, host-agnostically. Prefers the Web Crypto `randomUUID` (a global,
+ *  not `node:crypto`) where present, with a time+random fallback so a host without `crypto` never
+ *  throws — mirroring how core treats Web Crypto as optional (see `mintRootRequestKey`). */
+export declare function newSessionId(): string;
+/** Bound the live-session map to `max` by evicting least-recently-used entries (the `Map`'s leading
+ *  keys, given `touchSession` re-inserts on use), closing each victim best-effort so its transport /
+ *  server releases. This is the categorical fix for the unbounded-growth vector: no client can pin
+ *  more than `max` server/transport pairs, whatever its `initialize` cadence. Exported for a direct
+ *  unit test of the LRU eviction contract. */
+export declare function evictExcessSessions<S>(sessions: Map<string, S>, max: number, close: (session: S) => Promise<void>): Promise<void>;
+/** The resolved MCP access policy for this app. */
+interface McpConfig {
+    /** Whether the MCP surface answers at all. Defaults ON. */
+    readonly enabled: boolean;
+    /** Whether non-loopback callers are allowed. Defaults OFF (loopback-only). */
+    readonly allowRemote: boolean;
+}
+/**
+ * Resolve the MCP access policy from the manifest (`mcp: { enabled?, allowRemote? }`, read
+ * reflectively until the app schema folds the field in — mirroring how `readApiBinding` reads
+ * `api`) and the environment (`URBAN_MCP_ENABLED`, `URBAN_MCP_ALLOW_REMOTE`). The env flags win so
+ * an operator can force the surface off (or open it to a non-loopback bind) without editing the
+ * manifest. Enabled defaults ON and access defaults to loopback-only ("defaults ON for loopback").
+ */
+export declare function readMcpConfig(manifest: unknown, env: (name: string) => string | undefined): McpConfig;
+/** Whether the request targets a loopback host — the best-effort loopback signal available at the
+ *  host seam (which carries no peer address). A missing Host header is treated as loopback (a direct
+ *  local client that sent none). */
+export declare function isLoopbackRequest(req: HttpRequest): boolean;
+/** The `required` keys a tool's `inputSchema` declares but the call omitted. Presence is decided
+ *  solely by {@link isBlankArg} — the single source of truth also used for path args — so a value is
+ *  "provided" unless it is absent (`undefined`/`null`) or a blank/whitespace-only string. A required
+ *  non-string input (e.g. a numeric/boolean/object arg) that is present is therefore accepted, not
+ *  wrongly reported missing. Derived from the schema's own `required` array so declaring a field
+ *  required is enough to have missing (or whitespace-only) calls rejected rather than silently
+ *  substituted with an empty string. */
+export declare function missingRequiredArgs(inputSchema: Record<string, unknown>, args: Record<string, unknown>): string[];
+/**
+ * Mount the runtime-served MCP surface at `/app/mcp` (ADR 0067). Returns a single `*`-method route
+ * (mounted unconditionally, like `/app/agent`); the handler bridges the host request/response seam
+ * to the SDK's Web-Standard Streamable-HTTP transport, maintaining one MCP session per
+ * `mcp-session-id`. The tool projection reuses the SAME OpenAPI enumeration and dispatch path as
+ * `mountApi`, so a tool call is equivalent to the corresponding HTTP call.
+ */
+export declare function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]): McpHandle;
+export {};