@nanobpm/urban 0.83.0 → 0.85.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/runtime/core/host.d.ts +87 -1
- package/dist/runtime/core/host.js +4 -0
- package/dist/runtime/core/modules/api.d.ts +5 -0
- package/dist/runtime/core/modules/api.js +2 -2
- package/dist/runtime/core/modules/mcp.d.ts +57 -0
- package/dist/runtime/core/modules/mcp.js +709 -0
- package/dist/runtime/core/modules/surfaces.js +11 -0
- package/dist/runtime/engine/nanosdk.d.ts +41 -1
- package/dist/runtime/engine/nanosdk.js +118 -0
- package/dist/runtime/index.d.ts +1 -1
- package/package.json +2 -1
- package/src/runtime/core/host.ts +89 -0
- package/src/runtime/core/modules/actions.test.ts +4 -0
- package/src/runtime/core/modules/agent.test.ts +4 -0
- package/src/runtime/core/modules/api.test.ts +4 -0
- package/src/runtime/core/modules/api.ts +2 -2
- package/src/runtime/core/modules/cancel.test.ts +4 -0
- package/src/runtime/core/modules/connectors.test.ts +4 -0
- package/src/runtime/core/modules/datasource.migrations.test.ts +4 -0
- package/src/runtime/core/modules/instance-tracking.test.ts +4 -0
- package/src/runtime/core/modules/mcp.test.ts +687 -0
- package/src/runtime/core/modules/mcp.ts +814 -0
- package/src/runtime/core/modules/pages.test.ts +4 -0
- package/src/runtime/core/modules/surfaces.test.ts +24 -0
- package/src/runtime/core/modules/surfaces.ts +11 -0
- package/src/runtime/core/modules/triggers.test.ts +4 -0
- package/src/runtime/core/modules/workers.test.ts +4 -0
- package/src/runtime/core/runtime.extensions.test.ts +6 -0
- package/src/runtime/core/runtime.test.ts +6 -0
- package/src/runtime/engine/nanosdk.test.ts +103 -0
- package/src/runtime/engine/nanosdk.ts +152 -0
- package/src/runtime/index.ts +4 -0
|
@@ -12,6 +12,7 @@ import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
|
|
|
12
12
|
import { mountActions } from "./actions.js";
|
|
13
13
|
import { mountAgent } from "./agent.js";
|
|
14
14
|
import { mountApi } from "./api.js";
|
|
15
|
+
import { mountMcp } from "./mcp.js";
|
|
15
16
|
import { mountPages } from "./pages.js";
|
|
16
17
|
/** Escape HTML-significant characters before embedding a value in markup. */
|
|
17
18
|
function escapeHtml(s) {
|
|
@@ -190,6 +191,16 @@ export function mountSurfaces(ctx, app) {
|
|
|
190
191
|
const agent = mountAgent(ctx);
|
|
191
192
|
routes.push(...agent.routes);
|
|
192
193
|
enabled.push("agent@/app/agent");
|
|
194
|
+
// The runtime-served MCP surface (ADR 0067): `/app/mcp`, a Streamable-HTTP MCP endpoint mounted
|
|
195
|
+
// unconditionally (like `/app/agent`) so an MCP client always has a stable address. It projects
|
|
196
|
+
// the app's read-only OpenAPI operations as tools from the SAME enumeration `mountApi` routes
|
|
197
|
+
// from, plus framework-owned read-only process-debugging tools — zero app-side MCP code.
|
|
198
|
+
const mcp = mountMcp(ctx, app, api.routes);
|
|
199
|
+
routes.push(...mcp.routes);
|
|
200
|
+
// The route is always mounted (stable address), but only claim MCP as an active surface when it
|
|
201
|
+
// actually answers — a config-disabled surface 404s, so listing it here would be inaccurate.
|
|
202
|
+
if (mcp.enabled)
|
|
203
|
+
enabled.push("mcp@/app/mcp");
|
|
193
204
|
// The pages surface (the schema-driven page runtime) mounts its own routes.
|
|
194
205
|
const pages = mountPages(ctx, app);
|
|
195
206
|
if (pages.routes.length > 0) {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
|
|
1
|
+
import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
|
|
2
2
|
import type { EngineSdkClient } from "./sdk.ts";
|
|
3
3
|
/** Coerce an engine response's process-instance key to a non-empty string, or
|
|
4
4
|
* throw — a missing key means a malformed/partial response, not a real instance. */
|
|
@@ -19,6 +19,11 @@ export declare function normalizeElementInstanceState(raw: unknown): ElementInst
|
|
|
19
19
|
* {@link WaitStateType} union, or `undefined` for an unrecognized value. Case-insensitive
|
|
20
20
|
* so a casing tweak doesn't silently drop parks. */
|
|
21
21
|
export declare function normalizeWaitStateType(raw: unknown): WaitStateType | undefined;
|
|
22
|
+
/** Map the engine's incident `state` onto the transport-agnostic {@link IncidentState} union,
|
|
23
|
+
* falling back to `"UNKNOWN"` for an unrecognized/absent value (an incident is never dropped
|
|
24
|
+
* for an odd state — unlike element/process rows, whose state is a hard identity field — so a
|
|
25
|
+
* caller still sees the fault). Case-insensitive so a casing tweak doesn't mis-map. */
|
|
26
|
+
export declare function normalizeIncidentState(raw: unknown): IncidentState;
|
|
22
27
|
/** Map one engine element-instance row onto an {@link ElementInstanceSummary}, or `undefined`
|
|
23
28
|
* when the row is malformed (missing key/elementId/process instance, or an unrecognized
|
|
24
29
|
* state). The single source of truth both `searchElementInstances` and `getElementInstance`
|
|
@@ -29,6 +34,12 @@ export declare function mapElementInstanceRow(row: Record<string, unknown>, log:
|
|
|
29
34
|
* Camunda SDK nests the park-specific fields under `details`; a plain REST body may inline
|
|
30
35
|
* them — read `details` first, then fall back to the row itself, so both wire shapes map. */
|
|
31
36
|
export declare function mapElementInstanceWaitStateRow(row: Record<string, unknown>, log: Log): ElementInstanceWaitState | undefined;
|
|
37
|
+
/** Map one engine incident row onto an {@link IncidentSummary}, or `undefined` when the row is
|
|
38
|
+
* malformed (missing the `incidentKey` or the owning `processInstanceKey` — the two identity
|
|
39
|
+
* fields a caller needs to resolve/act on it). `jobKey`/`elementInstanceKey`/`errorType`/
|
|
40
|
+
* `errorMessage` are best-effort diagnostics: present when the engine reports them, omitted
|
|
41
|
+
* otherwise. The single source of truth `searchIncidents` extracts through. */
|
|
42
|
+
export declare function mapIncidentRow(row: Record<string, unknown>, log: Log): IncidentSummary | undefined;
|
|
32
43
|
/** A job as delivered to a nano-sdk job handler: the frame fields plus the
|
|
33
44
|
* acknowledgement actions the handler must call. */
|
|
34
45
|
export interface NanoSdkActivatedJob {
|
|
@@ -120,6 +131,22 @@ export interface NanoSdkClient {
|
|
|
120
131
|
getElementInstance(input: {
|
|
121
132
|
elementInstanceKey: string;
|
|
122
133
|
}, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
|
|
134
|
+
searchIncidents(input: {
|
|
135
|
+
filter?: Record<string, unknown>;
|
|
136
|
+
page?: Record<string, unknown>;
|
|
137
|
+
}, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
|
|
138
|
+
resolveIncident(input: {
|
|
139
|
+
incidentKey: string;
|
|
140
|
+
}, options?: unknown): Promise<unknown>;
|
|
141
|
+
updateJob(input: {
|
|
142
|
+
jobKey: string;
|
|
143
|
+
changeset: Record<string, unknown>;
|
|
144
|
+
}, options?: unknown): Promise<unknown>;
|
|
145
|
+
createElementInstanceVariables(input: {
|
|
146
|
+
elementInstanceKey: string;
|
|
147
|
+
variables: Record<string, unknown>;
|
|
148
|
+
local?: boolean;
|
|
149
|
+
}, options?: unknown): Promise<unknown>;
|
|
123
150
|
createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
|
|
124
151
|
/** Stop every worker created on this client. Used on teardown to also drain a
|
|
125
152
|
* REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
|
|
@@ -187,6 +214,19 @@ export declare class SdkEngineClient implements EngineClient {
|
|
|
187
214
|
searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
|
|
188
215
|
searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
|
|
189
216
|
getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
|
|
217
|
+
searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
|
|
218
|
+
resolveIncident(input: {
|
|
219
|
+
incidentKey: string;
|
|
220
|
+
}): Promise<void>;
|
|
221
|
+
updateJobRetries(input: {
|
|
222
|
+
jobKey: string;
|
|
223
|
+
retries: number;
|
|
224
|
+
}): Promise<void>;
|
|
225
|
+
setVariables(input: {
|
|
226
|
+
scopeKey: string;
|
|
227
|
+
variables: Record<string, unknown>;
|
|
228
|
+
local?: boolean;
|
|
229
|
+
}): Promise<void>;
|
|
190
230
|
registerWorker(jobType: string, handler: JobHandler, options?: {
|
|
191
231
|
workerName?: string;
|
|
192
232
|
maxParallelJobs?: number;
|
|
@@ -91,6 +91,26 @@ export function normalizeWaitStateType(raw) {
|
|
|
91
91
|
return undefined;
|
|
92
92
|
}
|
|
93
93
|
}
|
|
94
|
+
/** Map the engine's incident `state` onto the transport-agnostic {@link IncidentState} union,
|
|
95
|
+
* falling back to `"UNKNOWN"` for an unrecognized/absent value (an incident is never dropped
|
|
96
|
+
* for an odd state — unlike element/process rows, whose state is a hard identity field — so a
|
|
97
|
+
* caller still sees the fault). Case-insensitive so a casing tweak doesn't mis-map. */
|
|
98
|
+
export function normalizeIncidentState(raw) {
|
|
99
|
+
if (typeof raw !== "string")
|
|
100
|
+
return "UNKNOWN";
|
|
101
|
+
switch (raw.toUpperCase()) {
|
|
102
|
+
case "ACTIVE":
|
|
103
|
+
return "ACTIVE";
|
|
104
|
+
case "MIGRATED":
|
|
105
|
+
return "MIGRATED";
|
|
106
|
+
case "PENDING":
|
|
107
|
+
return "PENDING";
|
|
108
|
+
case "RESOLVED":
|
|
109
|
+
return "RESOLVED";
|
|
110
|
+
default:
|
|
111
|
+
return "UNKNOWN";
|
|
112
|
+
}
|
|
113
|
+
}
|
|
94
114
|
/** A non-empty string form of an engine key/id, or `undefined` when absent/blank (including a
|
|
95
115
|
* whitespace-only string). Coerces a numeric key to a string (the engine may serialize a key
|
|
96
116
|
* either way) but never `String(...)`-coerces an arbitrary object into a garbage
|
|
@@ -105,6 +125,19 @@ function presentEngineKey(value) {
|
|
|
105
125
|
const trimmed = value.trim();
|
|
106
126
|
return trimmed === "" ? undefined : trimmed;
|
|
107
127
|
}
|
|
128
|
+
/** The non-empty, trimmed string form of a *required* engine key, or throws when the value is
|
|
129
|
+
* absent/blank (including a whitespace-only string). A mutating seam operation addresses a
|
|
130
|
+
* single entity by key, so a blank key is a caller bug that must fail fast with an actionable
|
|
131
|
+
* message rather than reach the engine as an empty path segment / invalid changeset and surface
|
|
132
|
+
* an opaque transport error. Reuses {@link presentEngineKey}'s trim-and-coerce rule so a padded
|
|
133
|
+
* key like `" 5 "` is normalized identically to how read paths resolve it. */
|
|
134
|
+
function requireEngineKey(value, name) {
|
|
135
|
+
const key = presentEngineKey(value);
|
|
136
|
+
if (key === undefined) {
|
|
137
|
+
throw new Error(`${name} must be a non-empty key`);
|
|
138
|
+
}
|
|
139
|
+
return key;
|
|
140
|
+
}
|
|
108
141
|
/** A required text field (a wait-state discriminator's `jobType`/`messageName`/`signalName`),
|
|
109
142
|
* or `undefined` when absent or blank — the caller skips the row rather than emitting a typed
|
|
110
143
|
* wait state carrying an empty required string. Returns the trimmed value, matching the
|
|
@@ -253,6 +286,40 @@ export function mapElementInstanceWaitStateRow(row, log) {
|
|
|
253
286
|
return { ...base, waitStateType };
|
|
254
287
|
}
|
|
255
288
|
}
|
|
289
|
+
/** Map one engine incident row onto an {@link IncidentSummary}, or `undefined` when the row is
|
|
290
|
+
* malformed (missing the `incidentKey` or the owning `processInstanceKey` — the two identity
|
|
291
|
+
* fields a caller needs to resolve/act on it). `jobKey`/`elementInstanceKey`/`errorType`/
|
|
292
|
+
* `errorMessage` are best-effort diagnostics: present when the engine reports them, omitted
|
|
293
|
+
* otherwise. The single source of truth `searchIncidents` extracts through. */
|
|
294
|
+
export function mapIncidentRow(row, log) {
|
|
295
|
+
const incidentKey = presentEngineKey(row.incidentKey);
|
|
296
|
+
if (incidentKey === undefined) {
|
|
297
|
+
log("warn", "skipping incident with no incidentKey in engine response");
|
|
298
|
+
return undefined;
|
|
299
|
+
}
|
|
300
|
+
const processInstanceKey = presentEngineKey(row.processInstanceKey);
|
|
301
|
+
if (processInstanceKey === undefined) {
|
|
302
|
+
log("warn", "skipping incident with no processInstanceKey in engine response", {
|
|
303
|
+
incidentKey,
|
|
304
|
+
});
|
|
305
|
+
return undefined;
|
|
306
|
+
}
|
|
307
|
+
const elementId = presentText(row.elementId);
|
|
308
|
+
const elementInstanceKey = presentEngineKey(row.elementInstanceKey);
|
|
309
|
+
const jobKey = presentEngineKey(row.jobKey);
|
|
310
|
+
const errorType = presentText(row.errorType);
|
|
311
|
+
const errorMessage = presentText(row.errorMessage);
|
|
312
|
+
return {
|
|
313
|
+
incidentKey,
|
|
314
|
+
processInstanceKey,
|
|
315
|
+
...(elementId ? { elementId } : {}),
|
|
316
|
+
...(elementInstanceKey ? { elementInstanceKey } : {}),
|
|
317
|
+
...(jobKey ? { jobKey } : {}),
|
|
318
|
+
...(errorType ? { errorType } : {}),
|
|
319
|
+
...(errorMessage ? { errorMessage } : {}),
|
|
320
|
+
state: normalizeIncidentState(row.state),
|
|
321
|
+
};
|
|
322
|
+
}
|
|
256
323
|
/**
|
|
257
324
|
* An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
|
|
258
325
|
* message, and user-task calls map one-to-one onto the SDK's client methods; workers
|
|
@@ -484,6 +551,57 @@ export class SdkEngineClient {
|
|
|
484
551
|
return null;
|
|
485
552
|
return mapElementInstanceRow(body, this.log) ?? null;
|
|
486
553
|
}
|
|
554
|
+
async searchIncidents(filter) {
|
|
555
|
+
// Same shape as `searchElementInstances`: build the engine filter from the transport-agnostic
|
|
556
|
+
// selectors, read at zero-wait consistency (an incident search is eventually consistent), and
|
|
557
|
+
// map each row through the single `mapIncidentRow` gate, dropping malformed rows.
|
|
558
|
+
const f = {};
|
|
559
|
+
// Normalize the request selectors the same way the response mapper normalizes keys: a
|
|
560
|
+
// whitespace-only/padded `processInstanceKey` must not reach the engine as a garbage filter
|
|
561
|
+
// segment (which would silently return surprising empty results).
|
|
562
|
+
const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
|
|
563
|
+
if (processInstanceKey)
|
|
564
|
+
f.processInstanceKey = processInstanceKey;
|
|
565
|
+
if (filter?.state)
|
|
566
|
+
f.state = filter.state;
|
|
567
|
+
const body = await this.client.searchIncidents({ filter: f }, { consistency: { waitUpToMs: 0 } });
|
|
568
|
+
const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
|
|
569
|
+
return items.flatMap((it) => {
|
|
570
|
+
const mapped = mapIncidentRow(it, this.log);
|
|
571
|
+
return mapped ? [mapped] : [];
|
|
572
|
+
});
|
|
573
|
+
}
|
|
574
|
+
async resolveIncident(input) {
|
|
575
|
+
await this.client.resolveIncident({
|
|
576
|
+
incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),
|
|
577
|
+
});
|
|
578
|
+
}
|
|
579
|
+
async updateJobRetries(input) {
|
|
580
|
+
// The "retry a failed job" operation: a job's remaining retries are the `retries` field of
|
|
581
|
+
// the `updateJob` changeset. Bumping them back above zero makes a failed job activatable so a
|
|
582
|
+
// paired `resolveIncident` can return it to the pool.
|
|
583
|
+
const jobKey = requireEngineKey(input.jobKey, "jobKey");
|
|
584
|
+
// `retries` serializes straight into the engine changeset, and `number` admits `NaN`,
|
|
585
|
+
// fractional, and negative values — none of which is a valid retry count. Reject them up
|
|
586
|
+
// front so a tool-driven call fails with a clear message instead of an opaque engine error.
|
|
587
|
+
if (!Number.isInteger(input.retries) || input.retries < 0) {
|
|
588
|
+
throw new Error("retries must be a non-negative integer");
|
|
589
|
+
}
|
|
590
|
+
await this.client.updateJob({
|
|
591
|
+
jobKey,
|
|
592
|
+
changeset: { retries: input.retries },
|
|
593
|
+
});
|
|
594
|
+
}
|
|
595
|
+
async setVariables(input) {
|
|
596
|
+
// A scope is addressed by its element-instance key (the process instance's root scope is an
|
|
597
|
+
// element instance too), so `scopeKey` maps straight onto `elementInstanceKey`. `local`
|
|
598
|
+
// defaults to engine behaviour (propagate to the outermost scope) when unset.
|
|
599
|
+
await this.client.createElementInstanceVariables({
|
|
600
|
+
elementInstanceKey: requireEngineKey(input.scopeKey, "scopeKey"),
|
|
601
|
+
variables: input.variables,
|
|
602
|
+
...(input.local === undefined ? {} : { local: input.local }),
|
|
603
|
+
});
|
|
604
|
+
}
|
|
487
605
|
async registerWorker(jobType, handler, options) {
|
|
488
606
|
const worker = this.client.createJobWorker({
|
|
489
607
|
jobType,
|
package/dist/runtime/index.d.ts
CHANGED
|
@@ -8,7 +8,7 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
|
|
|
8
8
|
export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
|
|
9
9
|
export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
|
|
10
10
|
export type { ValidationIssue } from "./core/validate.ts";
|
|
11
|
-
export type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
|
|
11
|
+
export type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, EngineJob, FormSchema, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, WatchHandle, WorkerSubscription, } from "./core/host.ts";
|
|
12
12
|
export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
|
|
13
13
|
export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
|
|
14
14
|
export { createLogger } from "./core/logger.ts";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nanobpm/urban",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.85.0",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -99,6 +99,7 @@
|
|
|
99
99
|
"test:deno": "deno test -A --no-check src/"
|
|
100
100
|
},
|
|
101
101
|
"dependencies": {
|
|
102
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
102
103
|
"@nanobpm/nano-app-schema": "^0.9.0",
|
|
103
104
|
"@nanobpm/nano-sdk": "^1.2.5",
|
|
104
105
|
"@nanobpm/workflow": "^0.14.0",
|
package/src/runtime/core/host.ts
CHANGED
|
@@ -359,6 +359,55 @@ export interface ElementInstanceWaitStateFilter {
|
|
|
359
359
|
waitStateType?: WaitStateType;
|
|
360
360
|
}
|
|
361
361
|
|
|
362
|
+
/**
|
|
363
|
+
* The engine's own incident-state enum — the lifecycle states an engine actually reports and
|
|
364
|
+
* that are valid as a search selector. An `ACTIVE` incident is an open fault a human/agent can
|
|
365
|
+
* act on (resolve/retry); the other values are terminal or transitional. This is the single
|
|
366
|
+
* source of truth for real engine states; {@link IncidentState} derives from it.
|
|
367
|
+
*/
|
|
368
|
+
export type EngineIncidentState = "ACTIVE" | "MIGRATED" | "PENDING" | "RESOLVED";
|
|
369
|
+
|
|
370
|
+
/**
|
|
371
|
+
* The lifecycle state of an incident, as {@link EngineClient.searchIncidents} reports it.
|
|
372
|
+
* Extends {@link EngineIncidentState} with the client-side `"UNKNOWN"` sentinel — a fallback
|
|
373
|
+
* used when the engine returns an unrecognized/absent value, so an incident is surfaced rather
|
|
374
|
+
* than dropped for an odd state. Because `"UNKNOWN"` is not a real engine state, it is not a
|
|
375
|
+
* valid {@link IncidentFilter} selector. A caller narrows on this union rather than probing a
|
|
376
|
+
* raw string.
|
|
377
|
+
*/
|
|
378
|
+
export type IncidentState = EngineIncidentState | "UNKNOWN";
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Selectors for an incident search: which process instance and/or lifecycle state to match.
|
|
382
|
+
* Used by {@link EngineClient.searchIncidents}. An eventually consistent (zero-wait) read; an
|
|
383
|
+
* unset selector matches every incident.
|
|
384
|
+
*/
|
|
385
|
+
export interface IncidentFilter {
|
|
386
|
+
processInstanceKey?: string;
|
|
387
|
+
state?: EngineIncidentState;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* A single incident (a stuck token — a job out of retries, an unhandled error, a failed
|
|
392
|
+
* gateway evaluation) as {@link EngineClient.searchIncidents} reports it. Carries the
|
|
393
|
+
* `incidentKey` a caller passes to {@link EngineClient.resolveIncident}, the owning
|
|
394
|
+
* `processInstanceKey`, and — when the incident is job-backed — the `jobKey` a caller passes
|
|
395
|
+
* to {@link EngineClient.updateJobRetries} to make the job retriable before resolving.
|
|
396
|
+
* `errorType`/`errorMessage` are the engine's fault description; they are free-form across
|
|
397
|
+
* engines (the live SDK reports a Camunda error-type enum, the in-process engine a coarser
|
|
398
|
+
* `kind`), so treat them as diagnostic text, not a stable taxonomy.
|
|
399
|
+
*/
|
|
400
|
+
export interface IncidentSummary {
|
|
401
|
+
readonly incidentKey: string;
|
|
402
|
+
readonly processInstanceKey: string;
|
|
403
|
+
readonly elementId?: string;
|
|
404
|
+
readonly elementInstanceKey?: string;
|
|
405
|
+
readonly jobKey?: string;
|
|
406
|
+
readonly errorType?: string;
|
|
407
|
+
readonly errorMessage?: string;
|
|
408
|
+
readonly state: IncidentState;
|
|
409
|
+
}
|
|
410
|
+
|
|
362
411
|
/**
|
|
363
412
|
* A deployed form's form-js schema plus its identifying metadata, as
|
|
364
413
|
* {@link EngineClient.getForm} returns it. `schema` is the parsed form-js document
|
|
@@ -483,6 +532,42 @@ export interface EngineClient {
|
|
|
483
532
|
getElementInstance(
|
|
484
533
|
elementInstanceKey: string,
|
|
485
534
|
): Promise<ElementInstanceSummary | null>;
|
|
535
|
+
/**
|
|
536
|
+
* Search incidents by owning process instance and/or lifecycle state
|
|
537
|
+
* (`POST /v2/incidents/search`) — the open faults blocking one or more instances (a job out
|
|
538
|
+
* of retries, an unhandled error, a failed gateway evaluation). An eventually consistent
|
|
539
|
+
* (zero-wait) read; each {@link IncidentSummary} carries the `incidentKey` to pass to
|
|
540
|
+
* {@link resolveIncident} and, for a job-backed incident, the `jobKey` to pass to
|
|
541
|
+
* {@link updateJobRetries}. The debugging counterpart to the read accessors above: where
|
|
542
|
+
* they answer "how far has this instance progressed", this answers "why is it stuck".
|
|
543
|
+
*/
|
|
544
|
+
searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
|
|
545
|
+
/**
|
|
546
|
+
* Resolve an open incident by key (`POST /v2/incidents/{incidentKey}/resolution`), unblocking
|
|
547
|
+
* the parked token: a job incident returns the job to the activatable pool (so it must have
|
|
548
|
+
* retries left first — see {@link updateJobRetries}), a gateway incident re-evaluates, an
|
|
549
|
+
* uncaught-error incident re-creates the service-task job. A mutating operation.
|
|
550
|
+
*/
|
|
551
|
+
resolveIncident(input: { incidentKey: string }): Promise<void>;
|
|
552
|
+
/**
|
|
553
|
+
* Update the remaining retries of a job (`PATCH /v2/jobs/{jobKey}`) — the "retry a failed
|
|
554
|
+
* job" operation. Setting a failed job's retries back above zero makes it activatable again;
|
|
555
|
+
* paired with {@link resolveIncident}, this is how a stuck `jobNoRetries` incident is cleared
|
|
556
|
+
* (bump retries, then resolve). A mutating operation.
|
|
557
|
+
*/
|
|
558
|
+
updateJobRetries(input: { jobKey: string; retries: number }): Promise<void>;
|
|
559
|
+
/**
|
|
560
|
+
* Set (merge) variables into a scope (`PUT /v2/element-instances/{scopeKey}/variables`).
|
|
561
|
+
* `scopeKey` is a process-instance key or an element-instance key; when `local` is `true` the
|
|
562
|
+
* variables are merged strictly into that local scope, otherwise (the default) they propagate
|
|
563
|
+
* to the outermost scope. A mutating operation used to repair state before resolving an
|
|
564
|
+
* incident or to steer an instance during debugging.
|
|
565
|
+
*/
|
|
566
|
+
setVariables(input: {
|
|
567
|
+
scopeKey: string;
|
|
568
|
+
variables: Record<string, unknown>;
|
|
569
|
+
local?: boolean;
|
|
570
|
+
}): Promise<void>;
|
|
486
571
|
/** Register a push worker for a job type. Draining is handled by the adapter. */
|
|
487
572
|
registerWorker(
|
|
488
573
|
jobType: string,
|
|
@@ -520,6 +605,10 @@ export const ENGINE_CLIENT_METHODS = [
|
|
|
520
605
|
"searchElementInstances",
|
|
521
606
|
"searchElementInstanceWaitStates",
|
|
522
607
|
"getElementInstance",
|
|
608
|
+
"searchIncidents",
|
|
609
|
+
"resolveIncident",
|
|
610
|
+
"updateJobRetries",
|
|
611
|
+
"setVariables",
|
|
523
612
|
"registerWorker",
|
|
524
613
|
"close",
|
|
525
614
|
] as const satisfies readonly (keyof EngineClient)[];
|
|
@@ -36,6 +36,10 @@ const engine: EngineClient = {
|
|
|
36
36
|
searchElementInstances: async () => [],
|
|
37
37
|
searchElementInstanceWaitStates: async () => [],
|
|
38
38
|
getElementInstance: async () => null,
|
|
39
|
+
searchIncidents: async () => [],
|
|
40
|
+
resolveIncident: async () => {},
|
|
41
|
+
updateJobRetries: async () => {},
|
|
42
|
+
setVariables: async () => {},
|
|
39
43
|
registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
|
|
40
44
|
close: async () => {},
|
|
41
45
|
};
|
|
@@ -21,6 +21,10 @@ const fakeEngine: EngineClient = {
|
|
|
21
21
|
searchElementInstances: async () => [],
|
|
22
22
|
searchElementInstanceWaitStates: async () => [],
|
|
23
23
|
getElementInstance: async () => null,
|
|
24
|
+
searchIncidents: async () => [],
|
|
25
|
+
resolveIncident: async () => {},
|
|
26
|
+
updateJobRetries: async () => {},
|
|
27
|
+
setVariables: async () => {},
|
|
24
28
|
registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
|
|
25
29
|
close: async () => {},
|
|
26
30
|
};
|
|
@@ -34,6 +34,10 @@ const engine: EngineClient = {
|
|
|
34
34
|
searchElementInstances: async () => [],
|
|
35
35
|
searchElementInstanceWaitStates: async () => [],
|
|
36
36
|
getElementInstance: async () => null,
|
|
37
|
+
searchIncidents: async () => [],
|
|
38
|
+
resolveIncident: async () => {},
|
|
39
|
+
updateJobRetries: async () => {},
|
|
40
|
+
setVariables: async () => {},
|
|
37
41
|
completeUserTask: async () => {},
|
|
38
42
|
registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
|
|
39
43
|
close: async () => {},
|
|
@@ -55,7 +55,7 @@ export interface ApiBinding {
|
|
|
55
55
|
/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
|
|
56
56
|
* live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
|
|
57
57
|
* stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
|
|
58
|
-
const API_BASE = "/app/api";
|
|
58
|
+
export const API_BASE = "/app/api";
|
|
59
59
|
|
|
60
60
|
/** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
|
|
61
61
|
* Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
|
|
@@ -250,7 +250,7 @@ export function resolveOperationHandler(mod: Record<string, unknown>): Operation
|
|
|
250
250
|
return undefined;
|
|
251
251
|
}
|
|
252
252
|
|
|
253
|
-
function readApiBinding(manifest: unknown): ApiBinding | undefined {
|
|
253
|
+
export function readApiBinding(manifest: unknown): ApiBinding | undefined {
|
|
254
254
|
const raw = manifest && typeof manifest === "object" ? Reflect.get(manifest, "api") : undefined;
|
|
255
255
|
if (!raw || typeof raw !== "object") return undefined;
|
|
256
256
|
const spec = Reflect.get(raw, "spec");
|
|
@@ -88,6 +88,10 @@ function cancelEngine(opts: {
|
|
|
88
88
|
searchElementInstances: notUsed("searchElementInstances"),
|
|
89
89
|
searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
|
|
90
90
|
getElementInstance: notUsed("getElementInstance"),
|
|
91
|
+
searchIncidents: notUsed("searchIncidents"),
|
|
92
|
+
resolveIncident: notUsed("resolveIncident"),
|
|
93
|
+
updateJobRetries: notUsed("updateJobRetries"),
|
|
94
|
+
setVariables: notUsed("setVariables"),
|
|
91
95
|
registerWorker: notUsed("registerWorker"),
|
|
92
96
|
close: notUsed("close"),
|
|
93
97
|
};
|
|
@@ -24,6 +24,10 @@ class MiniEngine implements EngineClient {
|
|
|
24
24
|
async searchElementInstances(): Promise<[]> { return []; }
|
|
25
25
|
async searchElementInstanceWaitStates(): Promise<[]> { return []; }
|
|
26
26
|
async getElementInstance(): Promise<null> { return null; }
|
|
27
|
+
async searchIncidents(): Promise<never[]> { return []; }
|
|
28
|
+
async resolveIncident(): Promise<void> {}
|
|
29
|
+
async updateJobRetries(): Promise<void> {}
|
|
30
|
+
async setVariables(): Promise<void> {}
|
|
27
31
|
async registerWorker(jobType: string, handler: JobHandler): Promise<WorkerSubscription> {
|
|
28
32
|
this.workers.set(jobType, handler);
|
|
29
33
|
return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };
|
|
@@ -23,6 +23,10 @@ const noEngine: EngineClient = {
|
|
|
23
23
|
searchElementInstances: async () => [],
|
|
24
24
|
searchElementInstanceWaitStates: async () => [],
|
|
25
25
|
getElementInstance: async () => null,
|
|
26
|
+
searchIncidents: async () => [],
|
|
27
|
+
resolveIncident: async () => {},
|
|
28
|
+
updateJobRetries: async () => {},
|
|
29
|
+
setVariables: async () => {},
|
|
26
30
|
registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
|
|
27
31
|
close: async () => {},
|
|
28
32
|
};
|
|
@@ -93,6 +93,10 @@ function fakeEngine(
|
|
|
93
93
|
searchElementInstances: notUsed("searchElementInstances"),
|
|
94
94
|
searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
|
|
95
95
|
getElementInstance: notUsed("getElementInstance"),
|
|
96
|
+
searchIncidents: notUsed("searchIncidents"),
|
|
97
|
+
resolveIncident: notUsed("resolveIncident"),
|
|
98
|
+
updateJobRetries: notUsed("updateJobRetries"),
|
|
99
|
+
setVariables: notUsed("setVariables"),
|
|
96
100
|
registerWorker: notUsed("registerWorker"),
|
|
97
101
|
close: notUsed("close"),
|
|
98
102
|
};
|