@nanobpm/urban 0.83.0 → 0.84.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/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
+import type { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobHandler, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, WorkerSubscription } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -19,6 +19,11 @@ export declare function normalizeElementInstanceState(raw: unknown): ElementInst
  *  {@link WaitStateType} union, or `undefined` for an unrecognized value. Case-insensitive
  *  so a casing tweak doesn't silently drop parks. */
 export declare 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 declare function normalizeIncidentState(raw: unknown): IncidentState;
 /** Map one engine element-instance row onto an {@link ElementInstanceSummary}, or `undefined`
  *  when the row is malformed (missing key/elementId/process instance, or an unrecognized
  *  state). The single source of truth both `searchElementInstances` and `getElementInstance`
@@ -29,6 +34,12 @@ export declare function mapElementInstanceRow(row: Record<string, unknown>, log:
  *  Camunda SDK nests the park-specific fields under `details`; a plain REST body may inline
  *  them — read `details` first, then fall back to the row itself, so both wire shapes map. */
 export declare function mapElementInstanceWaitStateRow(row: Record<string, unknown>, log: Log): ElementInstanceWaitState | undefined;
+/** 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 declare function mapIncidentRow(row: Record<string, unknown>, log: Log): IncidentSummary | undefined;
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
@@ -120,6 +131,22 @@ export interface NanoSdkClient {
     getElementInstance(input: {
         elementInstanceKey: string;
     }, 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
@@ -187,6 +214,19 @@ export declare class SdkEngineClient implements EngineClient {
     searchElementInstances(filter?: ElementInstanceFilter): Promise<ElementInstanceSummary[]>;
     searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
     getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
+    searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    resolveIncident(input: {
+        incidentKey: string;
+    }): Promise<void>;
+    updateJobRetries(input: {
+        jobKey: string;
+        retries: number;
+    }): Promise<void>;
+    setVariables(input: {
+        scopeKey: string;
+        variables: Record<string, unknown>;
+        local?: boolean;
+    }): Promise<void>;
     registerWorker(jobType: string, handler: JobHandler, options?: {
         workerName?: string;
         maxParallelJobs?: number;

package/dist/runtime/engine/nanosdk.js

@@ -91,6 +91,26 @@ export function normalizeWaitStateType(raw) {
             return 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) {
+    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
@@ -105,6 +125,19 @@ function presentEngineKey(value) {
     const trimmed = value.trim();
     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, name) {
+    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
@@ -253,6 +286,40 @@ export function mapElementInstanceWaitStateRow(row, log) {
             return { ...base, waitStateType };
     }
 }
+/** 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, log) {
+    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),
+    };
+}
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers
@@ -484,6 +551,57 @@ export class SdkEngineClient {
             return null;
         return mapElementInstanceRow(body, this.log) ?? null;
     }
+    async searchIncidents(filter) {
+        // 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 = {};
+        // 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) {
+        await this.client.resolveIncident({
+            incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),
+        });
+    }
+    async updateJobRetries(input) {
+        // 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) {
+        // 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, handler, options) {
         const worker = this.client.createJobWorker({
             jobType,

package/dist/runtime/index.d.ts

@@ -8,7 +8,7 @@ export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, p
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, InstanceTracking, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-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";
+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";
 export { buildFormSchema, parseFormSchema, pickFormLinkage, presentFormIdentifier, resolveFormIdentifier, } from "./core/form-contract.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { createLogger } from "./core/logger.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.83.0",
+	"version": "0.84.0",
 	"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.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/host.ts

@@ -359,6 +359,55 @@ export interface ElementInstanceWaitStateFilter {
   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
@@ -483,6 +532,42 @@ export interface EngineClient {
   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,
@@ -520,6 +605,10 @@ export const ENGINE_CLIENT_METHODS = [
   "searchElementInstances",
   "searchElementInstanceWaitStates",
   "getElementInstance",
+  "searchIncidents",
+  "resolveIncident",
+  "updateJobRetries",
+  "setVariables",
   "registerWorker",
   "close",
 ] as const satisfies readonly (keyof EngineClient)[];

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

@@ -36,6 +36,10 @@ const engine: EngineClient = {
   searchElementInstances: async () => [],
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

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

@@ -21,6 +21,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 () => {},
 };

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

@@ -34,6 +34,10 @@ const engine: EngineClient = {
   searchElementInstances: async () => [],
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   completeUserTask: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},

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

@@ -88,6 +88,10 @@ function cancelEngine(opts: {
     searchElementInstances: notUsed("searchElementInstances"),
     searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
     getElementInstance: notUsed("getElementInstance"),
+    searchIncidents: notUsed("searchIncidents"),
+    resolveIncident: notUsed("resolveIncident"),
+    updateJobRetries: notUsed("updateJobRetries"),
+    setVariables: notUsed("setVariables"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };

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

@@ -24,6 +24,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, handler: JobHandler): Promise<WorkerSubscription> {
     this.workers.set(jobType, handler);
     return { jobType, unsubscribe: async () => void this.workers.delete(jobType) };

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -23,6 +23,10 @@ const noEngine: EngineClient = {
   searchElementInstances: async () => [],
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
+  searchIncidents: async () => [],
+  resolveIncident: async () => {},
+  updateJobRetries: async () => {},
+  setVariables: async () => {},
   registerWorker: async (jobType) => ({ jobType, unsubscribe: async () => {} }),
   close: async () => {},
 };

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -93,6 +93,10 @@ function fakeEngine(
     searchElementInstances: notUsed("searchElementInstances"),
     searchElementInstanceWaitStates: notUsed("searchElementInstanceWaitStates"),
     getElementInstance: notUsed("getElementInstance"),
+    searchIncidents: notUsed("searchIncidents"),
+    resolveIncident: notUsed("resolveIncident"),
+    updateJobRetries: notUsed("updateJobRetries"),
+    setVariables: notUsed("setVariables"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };

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 () => {},
 };

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,