@nanobpm/urban 0.88.0 → 0.89.0

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

@@ -198,6 +198,10 @@ export type UserTaskState = "CREATED" | "COMPLETED" | "CANCELED" | "FAILED";
 export interface ProcessInstanceSnapshot {
     readonly processInstanceKey: string;
     readonly state: ProcessInstanceState;
+    /** The key of the deployed process definition this instance runs — the handle a caller feeds to
+     *  {@link EngineClient.getProcessDefinitionXml} to fetch the deployed BPMN (the instance →
+     *  `processDefinitionKey` → deployed XML path, no repo checkout). Absent when the engine omits it. */
+    readonly processDefinitionKey?: string;
 }
 /**
  * A single open user task as {@link EngineClient.searchUserTasks} reports it. Carries the
@@ -425,6 +429,72 @@ export interface FormSchema {
     readonly version?: number;
     readonly schema: Record<string, unknown>;
 }
+/**
+ * Selectors for a variable search: which process instance and/or scope to match, optionally
+ * narrowed to a single variable `name`. Used by {@link EngineClient.searchVariables}. An
+ * eventually consistent (zero-wait) read; an unset selector matches every variable in scope.
+ */
+export interface VariableFilter {
+    processInstanceKey?: string;
+    scopeKey?: string;
+    name?: string;
+}
+/**
+ * A single process variable as {@link EngineClient.searchVariables} reports it — the read
+ * counterpart to the write-only {@link EngineClient.setVariables}. Mirrors the engine's v2
+ * `/variables/search` row: the variable's own `variableKey`, its `name`, its serialized JSON
+ * `value` (a string — an object/array value arrives JSON-encoded, so a caller `JSON.parse`s it),
+ * the `scopeKey` it is directly defined in (a process-instance key for a process-level variable,
+ * an element-instance key for a local one) and the owning `processInstanceKey`. `isTruncated` is
+ * `true` when the engine clipped a large `value` for the read model — the caller then knows the
+ * `value` is a preview, not the whole payload. This is the only way to read a parked token's
+ * business payload (`prKey`, `round`, an escalation `question`/`answer`, `resolution`,
+ * `directive`); the ADR 0065 projections carry lifecycle/position, not the payload.
+ */
+export interface VariableSummary {
+    readonly variableKey: string;
+    readonly name: string;
+    readonly value: string;
+    readonly scopeKey: string;
+    readonly processInstanceKey: string;
+    readonly isTruncated: boolean;
+}
+/**
+ * Selectors for a job search: which process instance, lifecycle `state`, job `type`, `elementId`,
+ * and/or leasing `worker` to match. Used by {@link EngineClient.searchJobs}. `state` is kept a
+ * transport-agnostic bare string (the engine's job-state enum is broad and forward-looking — e.g.
+ * `CREATED`/`COMPLETED`/`FAILED`/`TIMED_OUT`), so a new engine state flows through without having
+ * to be enumerated here. An eventually consistent (zero-wait) read; an unset selector matches
+ * every job.
+ */
+export interface JobFilter {
+    processInstanceKey?: string;
+    state?: string;
+    type?: string;
+    elementId?: string;
+    worker?: string;
+}
+/**
+ * A single job as {@link EngineClient.searchJobs} reports it — mirrors the engine's v2
+ * `/jobs/search` row. Carries the `jobKey` a caller passes to
+ * {@link EngineClient.updateJobRetries} (the only source of a `jobKey` for a job NOT already
+ * behind a `jobNoRetries` incident, which {@link searchIncidents} surfaces), the job `type` and
+ * lifecycle `state` (a bare string — see {@link JobFilter}), the owning `processInstanceKey`, and
+ * the best-effort diagnostics `worker`/`retries`/`elementId`/`deadline`. The `worker` field is the
+ * "is it actually stuck" signal: a `CREATED` job WITH a `worker` set has been leased by an agent,
+ * while one with NONE set is merely queued — so `worker` is omitted (absent) when unset. `retries`,
+ * `elementId`, and `deadline` are likewise present when the engine reports them, omitted otherwise.
+ */
+export interface JobSummary {
+    readonly jobKey: string;
+    readonly type: string;
+    readonly state: string;
+    readonly processInstanceKey: string;
+    readonly worker?: string;
+    readonly retries?: number;
+    readonly elementId?: string;
+    readonly deadline?: string;
+}
 /**
  * EngineClient is the seam onto a Nano engine. The SDK/REST-backed adapter implements
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
@@ -560,6 +630,40 @@ export interface EngineClient {
      * they answer "how far has this instance progressed", this answers "why is it stuck".
      */
     searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    /**
+     * Search process variables by owning process instance and/or scope, optionally narrowed to a
+     * single `name` (`POST /v2/variables/search`). The read counterpart to the write-only
+     * {@link setVariables}: it is the only way to see a parked token's business payload (`prKey`,
+     * `round`, an escalation `question`/`answer`, `resolution`, `directive`) — the ADR 0065
+     * projections carry lifecycle/position, not the payload. An eventually consistent (zero-wait)
+     * read; each {@link VariableSummary} carries the variable's serialized JSON `value` (a string)
+     * and an `isTruncated` flag set when the engine clipped a large value for the read model.
+     */
+    searchVariables(filter?: VariableFilter): Promise<VariableSummary[]>;
+    /**
+     * Search jobs by owning process instance, lifecycle `state`, job `type`, `elementId`, and/or
+     * leasing `worker` (`POST /v2/jobs/search`). This is the "is it actually stuck" read: a
+     * `CREATED` job WITH a `worker` set has been leased by an agent, while one with NONE set is
+     * merely queued. It is also the on-tool source of a `jobKey` for {@link updateJobRetries} when
+     * the job is NOT behind an incident — {@link searchIncidents} only surfaces a `jobKey` for a
+     * job that already faulted (a `jobNoRetries` incident), so retrying an un-incidented job would
+     * otherwise be impossible without a direct engine-API call. An eventually consistent (zero-wait)
+     * read; each {@link JobSummary} carries the `jobKey` plus best-effort `worker`/`retries`/
+     * `elementId`/`deadline` diagnostics.
+     */
+    searchJobs(filter?: JobFilter): Promise<JobSummary[]>;
+    /**
+     * Fetch the deployed BPMN XML of a process definition by its `processDefinitionKey`
+     * (`GET /v2/process-definitions/{processDefinitionKey}/xml`), or `null` when the key is blank,
+     * unknown (a 404), or the definition carries no XML. This is the *deployed* model — the routing
+     * source of truth, including its FEEL gateway conditions — so an agent can reason about WHY an
+     * instance routed where it did without checking out `resources/processes/*.bpmn` from the app
+     * repo. An instance already carries its `processDefinitionKey` (via {@link searchProcessInstances}),
+     * so the path is instance → `processDefinitionKey` → deployed XML. A read is treated as absence
+     * (`null`) rather than propagating (mirroring {@link getForm}/{@link getElementInstance}), so a
+     * caller distinguishes "have it" from "don't" without a try/catch. A zero-wait read.
+     */
+    getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
     /**
      * 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
@@ -614,4 +718,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", "searchIncidents", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];
+export declare const ENGINE_CLIENT_METHODS: readonly ["deployResources", "createInstance", "cancelInstance", "publishMessage", "searchUserTasks", "openUserTasks", "getForm", "completeUserTask", "searchProcessInstances", "searchElementInstances", "searchElementInstanceWaitStates", "getElementInstance", "searchIncidents", "searchVariables", "searchJobs", "getProcessDefinitionXml", "resolveIncident", "updateJobRetries", "setVariables", "registerWorker", "close"];

package/dist/runtime/core/host.js

@@ -118,6 +118,9 @@ export const ENGINE_CLIENT_METHODS = [
     "searchElementInstanceWaitStates",
     "getElementInstance",
     "searchIncidents",
+    "searchVariables",
+    "searchJobs",
+    "getProcessDefinitionXml",
     "resolveIncident",
     "updateJobRetries",
     "setVariables",

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

@@ -536,6 +536,74 @@ function buildDebugTools(app) {
                 return app.engine.searchIncidents(filter);
             },
         },
+        {
+            name: `${DEBUG_PREFIX}search_variables`,
+            description: "Engine truth: search process variables by process instance and/or scope, optionally by name — the read counterpart to set_variables. Reads only, eventually consistent. This is the only way to see a parked token's business payload (prKey, round, an escalation question/answer, resolution, directive); the projections carry lifecycle/position, not the payload. Each result carries the variableKey/name/serialized-JSON value/scopeKey/processInstanceKey/isTruncated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    processInstanceKey: OPTIONAL_STRING,
+                    scopeKey: OPTIONAL_STRING,
+                    name: OPTIONAL_STRING,
+                },
+            },
+            run: (args) => {
+                const filter = {};
+                const pik = readPresentString(args, "processInstanceKey");
+                if (pik)
+                    filter.processInstanceKey = pik;
+                const scopeKey = readPresentString(args, "scopeKey");
+                if (scopeKey)
+                    filter.scopeKey = scopeKey;
+                const name = readPresentString(args, "name");
+                if (name)
+                    filter.name = name;
+                return app.engine.searchVariables(filter);
+            },
+        },
+        {
+            name: `${DEBUG_PREFIX}search_jobs`,
+            description: "Engine truth: search jobs by process instance, state, and/or type/elementId/worker. Reads only, eventually consistent. The 'is it actually stuck?' test: a CREATED job WITH a worker set has been leased by an agent, one with NONE set is merely queued. This is also the on-tool source of a jobKey for retry_job (the only other source is a jobNoRetries incident via search_incidents). Each result carries jobKey/type/state/processInstanceKey and the best-effort worker/retries/elementId/deadline.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    processInstanceKey: OPTIONAL_STRING,
+                    state: OPTIONAL_STRING,
+                    type: OPTIONAL_STRING,
+                    elementId: OPTIONAL_STRING,
+                    worker: OPTIONAL_STRING,
+                },
+            },
+            run: (args) => {
+                const filter = {};
+                const pik = readPresentString(args, "processInstanceKey");
+                if (pik)
+                    filter.processInstanceKey = pik;
+                const state = readPresentString(args, "state");
+                if (state)
+                    filter.state = state;
+                const type = readPresentString(args, "type");
+                if (type)
+                    filter.type = type;
+                const elementId = readPresentString(args, "elementId");
+                if (elementId)
+                    filter.elementId = elementId;
+                const worker = readPresentString(args, "worker");
+                if (worker)
+                    filter.worker = worker;
+                return app.engine.searchJobs(filter);
+            },
+        },
+        {
+            name: `${DEBUG_PREFIX}get_process_definition_xml`,
+            description: "Engine truth: return the deployed BPMN XML of a process definition by key (the routing source of truth, with its FEEL gateway conditions) — reason about WHY an instance routed where it did without a repo checkout. Reads only; null when the key is unknown. An instance carries its processDefinitionKey via search_process_instances, so the path is instance → processDefinitionKey → deployed XML; pair with get_element_instance to locate the parked element.",
+            inputSchema: {
+                type: "object",
+                properties: { processDefinitionKey: OPTIONAL_STRING },
+                required: ["processDefinitionKey"],
+            },
+            run: (args) => app.engine.getProcessDefinitionXml(requireString(args, "processDefinitionKey")),
+        },
         {
             name: `${DEBUG_PREFIX}cancel_instance`,
             description: "MUTATING: cancel a running process instance. Requires the shared-secret guard.",