@nanobpm/urban 0.88.0 → 0.89.0

package/dist/runtime/engine/nanosdk.d.ts

@@ -1,4 +1,4 @@
-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 { EngineClient, ElementInstanceState, ElementInstanceSummary, ElementInstanceFilter, ElementInstanceWaitState, ElementInstanceWaitStateFilter, WaitStateType, FormSchema, IncidentFilter, IncidentState, IncidentSummary, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, 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. */
@@ -40,6 +40,21 @@ export declare function mapElementInstanceWaitStateRow(row: Record<string, unkno
  *  `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;
+/** Map one engine variable row onto a {@link VariableSummary}, or `undefined` when the row is
+ *  malformed (missing the `variableKey`, owning `processInstanceKey`, or `name` — the identity a
+ *  caller needs). `value` is the engine's serialized JSON value (a string); a non-string value is
+ *  JSON-encoded so the field is always a string a caller can `JSON.parse`. `scopeKey` falls back to
+ *  the process-instance key for a process-level variable that omits it. `isTruncated` is the
+ *  engine's large-value-clipped flag, defaulting to `false`. The single source of truth
+ *  `searchVariables` extracts through. */
+export declare function mapVariableRow(row: Record<string, unknown>, log: Log): VariableSummary | undefined;
+/** Map one engine job row onto a {@link JobSummary}, or `undefined` when the row is malformed
+ *  (missing the `jobKey`, `type`, or owning `processInstanceKey`). `worker`/`retries`/`elementId`/
+ *  `deadline` are best-effort diagnostics: present when the engine reports them, omitted otherwise
+ *  — an unset `worker` is the "queued, not leased" signal, so it must be absent rather than `""`.
+ *  `state` is passed through as a bare string (the engine's job-state enum is broad). The single
+ *  source of truth `searchJobs` extracts through. */
+export declare function mapJobRow(row: Record<string, unknown>, log: Log): JobSummary | 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 {
@@ -135,6 +150,17 @@ export interface NanoSdkClient {
         filter?: Record<string, unknown>;
         page?: Record<string, unknown>;
     }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchVariables(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    searchJobs(input: {
+        filter?: Record<string, unknown>;
+        page?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    getProcessDefinitionXml(input: {
+        processDefinitionKey: string;
+    }, consistency?: unknown, options?: unknown): Promise<unknown>;
     resolveIncident(input: {
         incidentKey: string;
     }, options?: unknown): Promise<unknown>;
@@ -215,6 +241,9 @@ export declare class SdkEngineClient implements EngineClient {
     searchElementInstanceWaitStates(filter?: ElementInstanceWaitStateFilter): Promise<ElementInstanceWaitState[]>;
     getElementInstance(elementInstanceKey: string): Promise<ElementInstanceSummary | null>;
     searchIncidents(filter?: IncidentFilter): Promise<IncidentSummary[]>;
+    searchVariables(filter?: VariableFilter): Promise<VariableSummary[]>;
+    searchJobs(filter?: JobFilter): Promise<JobSummary[]>;
+    getProcessDefinitionXml(processDefinitionKey: string): Promise<string | null>;
     resolveIncident(input: {
         incidentKey: string;
     }): Promise<void>;

package/dist/runtime/engine/nanosdk.js

@@ -320,6 +320,91 @@ export function mapIncidentRow(row, log) {
         state: normalizeIncidentState(row.state),
     };
 }
+/** Map one engine variable row onto a {@link VariableSummary}, or `undefined` when the row is
+ *  malformed (missing the `variableKey`, owning `processInstanceKey`, or `name` — the identity a
+ *  caller needs). `value` is the engine's serialized JSON value (a string); a non-string value is
+ *  JSON-encoded so the field is always a string a caller can `JSON.parse`. `scopeKey` falls back to
+ *  the process-instance key for a process-level variable that omits it. `isTruncated` is the
+ *  engine's large-value-clipped flag, defaulting to `false`. The single source of truth
+ *  `searchVariables` extracts through. */
+export function mapVariableRow(row, log) {
+    const variableKey = presentEngineKey(row.variableKey);
+    if (variableKey === undefined) {
+        log("warn", "skipping variable with no variableKey in engine response");
+        return undefined;
+    }
+    const processInstanceKey = presentEngineKey(row.processInstanceKey);
+    if (processInstanceKey === undefined) {
+        log("warn", "skipping variable with no processInstanceKey in engine response", {
+            variableKey,
+        });
+        return undefined;
+    }
+    const name = presentText(row.name);
+    if (name === undefined) {
+        log("warn", "skipping variable with no name in engine response", { variableKey });
+        return undefined;
+    }
+    // A process-level variable is scoped to the process instance itself; the engine may omit
+    // `scopeKey` for it, so fall back to the process-instance key rather than dropping the row.
+    const scopeKey = presentEngineKey(row.scopeKey) ?? processInstanceKey;
+    // The engine serializes `value` as a JSON string. Keep a string as-is; encode any other type
+    // (an object/array/number a permissive engine might inline) so the field is always a string the
+    // caller can `JSON.parse`.
+    const value = typeof row.value === "string" ? row.value : JSON.stringify(row.value ?? null);
+    return {
+        variableKey,
+        name,
+        value,
+        scopeKey,
+        processInstanceKey,
+        isTruncated: row.isTruncated === true,
+    };
+}
+/** Map one engine job row onto a {@link JobSummary}, or `undefined` when the row is malformed
+ *  (missing the `jobKey`, `type`, or owning `processInstanceKey`). `worker`/`retries`/`elementId`/
+ *  `deadline` are best-effort diagnostics: present when the engine reports them, omitted otherwise
+ *  — an unset `worker` is the "queued, not leased" signal, so it must be absent rather than `""`.
+ *  `state` is passed through as a bare string (the engine's job-state enum is broad). The single
+ *  source of truth `searchJobs` extracts through. */
+export function mapJobRow(row, log) {
+    const jobKey = presentEngineKey(row.jobKey);
+    if (jobKey === undefined) {
+        log("warn", "skipping job with no jobKey in engine response");
+        return undefined;
+    }
+    const type = presentText(row.type);
+    if (type === undefined) {
+        log("warn", "skipping job with no type in engine response", { jobKey });
+        return undefined;
+    }
+    const processInstanceKey = presentEngineKey(row.processInstanceKey);
+    if (processInstanceKey === undefined) {
+        log("warn", "skipping job with no processInstanceKey in engine response", { jobKey });
+        return undefined;
+    }
+    const state = presentText(row.state);
+    if (state === undefined) {
+        log("warn", "skipping job with no state in engine response", { jobKey });
+        return undefined;
+    }
+    const worker = presentText(row.worker);
+    const retries = typeof row.retries === "number" && Number.isFinite(row.retries)
+        ? row.retries
+        : undefined;
+    const elementId = presentText(row.elementId);
+    const deadline = presentText(row.deadline);
+    return {
+        jobKey,
+        type,
+        state,
+        processInstanceKey,
+        ...(worker ? { worker } : {}),
+        ...(retries !== undefined ? { retries } : {}),
+        ...(elementId ? { elementId } : {}),
+        ...(deadline ? { deadline } : {}),
+    };
+}
 /**
  * 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,7 +569,12 @@ export class SdkEngineClient {
                 });
                 return [];
             }
-            return [{ processInstanceKey: String(key), state }];
+            const processDefinitionKey = presentEngineKey(it.processDefinitionKey);
+            return [{
+                    processInstanceKey: String(key),
+                    state,
+                    ...(processDefinitionKey ? { processDefinitionKey } : {}),
+                }];
         });
     }
     async searchElementInstances(filter) {
@@ -575,6 +665,78 @@ export class SdkEngineClient {
             return mapped ? [mapped] : [];
         });
     }
+    async searchVariables(filter) {
+        // Same shape as `searchIncidents`: build the engine filter from the transport-agnostic
+        // selectors, read at zero-wait consistency (a variable search is eventually consistent), and
+        // map each row through the single `mapVariableRow` gate, dropping malformed rows.
+        const f = {};
+        const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+        if (processInstanceKey)
+            f.processInstanceKey = processInstanceKey;
+        const scopeKey = presentEngineKey(filter?.scopeKey);
+        if (scopeKey)
+            f.scopeKey = scopeKey;
+        const name = filter?.name?.trim();
+        if (name)
+            f.name = name;
+        const body = await this.client.searchVariables({ filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapVariableRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async searchJobs(filter) {
+        // Same shape as `searchIncidents`: build the engine filter from the transport-agnostic
+        // selectors, read at zero-wait consistency (a job search is eventually consistent), and map
+        // each row through the single `mapJobRow` gate, dropping malformed rows.
+        const f = {};
+        const processInstanceKey = presentEngineKey(filter?.processInstanceKey);
+        if (processInstanceKey)
+            f.processInstanceKey = processInstanceKey;
+        const state = filter?.state?.trim();
+        if (state)
+            f.state = state;
+        const type = filter?.type?.trim();
+        if (type)
+            f.type = type;
+        const elementId = filter?.elementId?.trim();
+        if (elementId)
+            f.elementId = elementId;
+        const worker = filter?.worker?.trim();
+        if (worker)
+            f.worker = worker;
+        const body = await this.client.searchJobs({ filter: f }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
+        return items.flatMap((it) => {
+            const mapped = mapJobRow(it, this.log);
+            return mapped ? [mapped] : [];
+        });
+    }
+    async getProcessDefinitionXml(processDefinitionKey) {
+        // A blank key can never address a definition — short-circuit to null rather than issue a
+        // `GET /v2/process-definitions//xml` with an empty segment. Normalize a padded-but-valid key so
+        // `" 5 "` addresses the same definition, mirroring `getElementInstance`.
+        const key = presentEngineKey(processDefinitionKey);
+        if (key === undefined)
+            return null;
+        let xml;
+        try {
+            xml = await this.client.getProcessDefinitionXml({ processDefinitionKey: key }, { consistency: { waitUpToMs: 0 } });
+        }
+        catch (err) {
+            // A 404 (no such definition) is an expected "not found", not a fault — mirror `getForm`/
+            // `getElementInstance`, which treat a failed fetch as absence (null) rather than propagating.
+            this.log("warn", "getProcessDefinitionXml: engine fetch failed", {
+                processDefinitionKey: key,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+        // The endpoint returns the raw BPMN XML as a string (204 → empty). Treat a blank/absent body
+        // as "no XML" (null) so a caller distinguishes "have it" from "don't".
+        return typeof xml === "string" && xml.trim() !== "" ? xml : null;
+    }
     async resolveIncident(input) {
         await this.client.resolveIncident({
             incidentKey: requireEngineKey(input.incidentKey, "incidentKey"),

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, IncidentState, EngineIncidentState, IncidentFilter, IncidentSummary, 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, JobFilter, JobHandler, JobSummary, ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb, UserTaskState, UserTaskSummary, UserTaskFilter, VariableFilter, VariableSummary, 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.88.0",
+	"version": "0.89.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/browser/runtime.browser.js

@@ -175,6 +175,74 @@ function installThemeBridge() {
   window.parent.postMessage({ type: "nano-app-ready" }, window.location.origin);
 }
 
+// ── App-View message relay (#518) ─────────────────────────────────────────
+// The App-View iframes this page currently mounts (renderAppView adds each one;
+// teardown removes it so a switched-away page's frames leave the relay set). The
+// bridge below uses this set as the trust membership: a message is only relayed
+// if ev.source is one of THESE frames' contentWindows (a nested App-View of this
+// page), never an arbitrary framed window.
+/** @type {Set<HTMLIFrameElement>} */
+const APP_VIEW_FRAMES = new Set();
+
+// The relay primitive. A nested App-View posts to `window.parent` (this page),
+// but this page installs no bridge, so the message is dropped: it never reaches
+// the console host (forward-UP) nor the page's other App-Views (relay-ACROSS).
+// This forwards a whitelisted `nano-navigate` UP to the host (chaining the same
+// hostNavigate boundary the page's own links use, so a nested App-View can drive
+// the console explorer — Preview DI, instance deep-links) and relays any other
+// App-View message ACROSS to the page's sibling App-Views (e.g. Library "Reuse"
+// → Compose fill). Deliberately generic (forward-up + broadcast-across), not a
+// per-message special case, so the whole cross-frame failure class is closed at
+// once rather than patched button-by-button.
+//
+// Trust boundary: the message must be same-origin AND from a known App-View
+// iframe of THIS page. `ev.source` alone is insufficient — the origin pin plus
+// the membership check are what actually gate the boundary, so a message from a
+// non-App-View source or a cross-origin frame is never relayed.
+/**
+ * @param {{ origin: string, source: any, data: any }} ev
+ * @param {Iterable<{ contentWindow: any }>} frames
+ * @param {{ origin: string, parent: any, embedded: boolean }} ctx
+ */
+function relayAppViewMessage(ev, frames, ctx) {
+  if (ev.origin !== ctx.origin) return;
+  const list = Array.isArray(frames) ? frames : [...frames];
+  let originFrame = null;
+  for (const f of list) {
+    if (f.contentWindow && f.contentWindow === ev.source) { originFrame = f; break; }
+  }
+  // Unknown source: not one of this page's App-Views — reject (trust boundary).
+  if (!originFrame) return;
+  const data = ev.data;
+  if (data && data.type === "nano-navigate") {
+    // Forward upward to the host/console, gated on the same same-origin embed
+    // boundary as hostNavigate: standalone (no same-origin console parent) there
+    // is nothing to forward to, so the message stays within the page.
+    if (ctx.embedded && ctx.parent) ctx.parent.postMessage(data, ctx.origin);
+    return;
+  }
+  // Relay across to the page's OTHER App-Views (never back to the originator).
+  for (const f of list) {
+    if (f === originFrame) continue;
+    const w = f.contentWindow;
+    if (w) w.postMessage(data, ctx.origin);
+  }
+}
+
+// Install the App-View relay as a single page-level `message` listener. Unlike
+// the theme bridge this is NOT gated on NANO_EMBEDDED: the sibling relay-across
+// works within a standalone page too; only the forward-up leg is embed-gated
+// (via ctx.embedded in relayAppViewMessage).
+function installAppViewBridge() {
+  window.addEventListener("message", (ev) => {
+    relayAppViewMessage(ev, APP_VIEW_FRAMES, {
+      origin: window.location.origin,
+      parent: window.parent,
+      embedded: NANO_EMBEDDED,
+    });
+  });
+}
+
 // Resolve every app endpoint against where THIS module was actually served from,
 // so absolute-looking "/app/…" paths work both at the origin root (direct run,
 // e.g. the CLI on :3000) and under a path-prefixed reverse proxy (the Nano
@@ -2769,6 +2837,13 @@ function renderAppView(node) {
   });
 
   const section = el("section", { class: "pc-appview" + (fill ? " pc-appview-fill" : "") });
+  // Register this frame in the App-View relay set (#518) so the page-level bridge
+  // can (a) recognise its outbound postMessages as coming from a known App-View of
+  // this page and (b) address it as a sibling target for another App-View's relay.
+  // A teardown disposer drops it again, so a switched-away page's frames don't
+  // linger as phantom relay endpoints.
+  APP_VIEW_FRAMES.add(frame);
+  disposers.push(() => APP_VIEW_FRAMES.delete(frame));
   // The title is an <h2> (the tag EVERY card renderer uses and makeCollapsible lifts into the
   // collapse header), not a <div>: a collapsible appView's title must be lifted out of the body,
   // otherwise it double-renders (header label + leftover in-body title). The .pc-appview-title CSS
@@ -2934,6 +3009,7 @@ function boot() {
   PARAM = parseRoute().param;
   NANO_EMBEDDED = computeEmbedded();
   installThemeBridge();
+  installAppViewBridge();
   window.addEventListener("hashchange", renderPage);
   // Re-render when the viewport crosses the mobile breakpoint so a Tier-2 'mobile'
   // variant swaps in/out on rotation or a window resize (the grid card flip, nav
@@ -2953,4 +3029,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, buildEngineForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, relayAppViewMessage, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, buildEngineForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };

package/src/runtime/browser/runtime.browser.test.ts

@@ -7,7 +7,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { PAGE_NODE_TYPES } from "../core/page-nodes.ts";
-import { RENDERERS, renderText, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
+import { RENDERERS, renderText, renderAppView, relayAppViewMessage, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -574,3 +574,128 @@ test("#338: a param-scoped nav badge with no route param degrades to 0 without q
   assert.equal(pill.textContent, "0", "badge degrades to 0 rather than an empty-string-filtered count");
   assert.equal(pill.hidden, false, "0 is shown (hideWhenZero is off) rather than a stale count");
 });
+
+// ── #518: App-View message relay (host-up + sibling-across bridge) ───────────
+// A nested App-View posts to `window.parent` (the Urban page). Before this fix
+// the page installed no bridge for those inbound postMessages, so a
+// `nano-navigate` never chained up to the console host (DI Preview did nothing)
+// and a sibling-directed message never reached the page's other App-Views
+// (Library "Reuse" filled nothing). relayAppViewMessage is the primitive that
+// closes that whole class: forward-up for nano-navigate, broadcast-across for
+// everything else, both behind a strict same-origin + known-App-View-source
+// trust boundary. These drive the primitive directly with fake frame windows.
+
+// A minimal Window stand-in that records its postMessage calls, used both as an
+// App-View iframe's contentWindow and as the host `window.parent`.
+function fakeWindow(): { posts: Array<{ data: unknown; origin: string }> } & {
+  postMessage(data: unknown, origin: string): void;
+} {
+  const posts: Array<{ data: unknown; origin: string }> = [];
+  return {
+    posts,
+    postMessage(data: unknown, origin: string): void {
+      posts.push({ data, origin });
+    },
+  };
+}
+
+// An App-View iframe stand-in exposing just the `.contentWindow` the relay reads.
+function fakeFrame(win: unknown): { contentWindow: unknown } {
+  return { contentWindow: win };
+}
+
+const ORIGIN = "https://app.test";
+
+test("#518: relayAppViewMessage forwards a child App-View's nano-navigate UP to the host", () => {
+  const parent = fakeWindow();
+  const composeWin = fakeWindow();
+  const compose = fakeFrame(composeWin);
+  const frames = [compose];
+  const data = { type: "nano-navigate", target: "definitionPreview", params: { xml: "<x/>" } };
+
+  relayAppViewMessage(
+    { origin: ORIGIN, source: composeWin, data },
+    frames,
+    { origin: ORIGIN, parent, embedded: true },
+  );
+
+  assert.equal(parent.posts.length, 1, "the host (window.parent) must receive the forwarded nano-navigate");
+  assert.deepEqual(parent.posts[0], { data, origin: ORIGIN });
+  // A forward-up is NOT also broadcast back into the page's App-Views.
+  assert.equal(composeWin.posts.length, 0, "nano-navigate is forwarded up, not relayed across");
+});
+
+test("#518: relayAppViewMessage relays a sibling-directed message ACROSS to the other App-Views only", () => {
+  const parent = fakeWindow();
+  const libraryWin = fakeWindow();
+  const composeWin = fakeWindow();
+  const stagedWin = fakeWindow();
+  const library = fakeFrame(libraryWin);
+  const compose = fakeFrame(composeWin);
+  const staged = fakeFrame(stagedWin);
+  const frames = [library, compose, staged];
+  const data = { type: "nano-delivery-graph-compose-fill", xml: "<definitions/>" };
+
+  relayAppViewMessage(
+    { origin: ORIGIN, source: libraryWin, data },
+    frames,
+    { origin: ORIGIN, parent, embedded: true },
+  );
+
+  // Delivered to BOTH siblings...
+  assert.deepEqual(composeWin.posts, [{ data, origin: ORIGIN }], "sibling Compose must receive the relayed message");
+  assert.deepEqual(stagedWin.posts, [{ data, origin: ORIGIN }], "sibling Staged must receive the relayed message");
+  // ...but never echoed back to the originator, nor forwarded up to the host.
+  assert.equal(libraryWin.posts.length, 0, "the originating App-View must not receive its own message back");
+  assert.equal(parent.posts.length, 0, "a sibling-directed (non-navigate) message must not be forwarded to the host");
+});
+
+test("#518: relayAppViewMessage does NOT forward up when the page is standalone (not embedded)", () => {
+  const parent = fakeWindow();
+  const composeWin = fakeWindow();
+  const compose = fakeFrame(composeWin);
+  const data = { type: "nano-navigate", target: "processExplorer", params: {} };
+
+  relayAppViewMessage(
+    { origin: ORIGIN, source: composeWin, data },
+    [compose],
+    { origin: ORIGIN, parent, embedded: false },
+  );
+
+  assert.equal(parent.posts.length, 0, "standalone: there is no same-origin console host to forward to");
+});
+
+test("#518: relayAppViewMessage rejects a message from a NON-App-View source (trust boundary)", () => {
+  const parent = fakeWindow();
+  const composeWin = fakeWindow();
+  const compose = fakeFrame(composeWin);
+  const strangerWin = fakeWindow(); // some other framed window, not one of our App-Views
+  const data = { type: "nano-navigate", target: "definitionPreview", params: {} };
+
+  relayAppViewMessage(
+    { origin: ORIGIN, source: strangerWin, data },
+    [compose],
+    { origin: ORIGIN, parent, embedded: true },
+  );
+
+  assert.equal(parent.posts.length, 0, "a message from an unknown source must not be forwarded up");
+  assert.equal(composeWin.posts.length, 0, "a message from an unknown source must not be relayed across");
+});
+
+test("#518: relayAppViewMessage rejects a CROSS-ORIGIN message even from a known App-View window", () => {
+  const parent = fakeWindow();
+  const composeWin = fakeWindow();
+  const stagedWin = fakeWindow();
+  const compose = fakeFrame(composeWin);
+  const staged = fakeFrame(stagedWin);
+  const data = { type: "nano-delivery-graph-compose-fill", xml: "<x/>" };
+
+  relayAppViewMessage(
+    { origin: "https://evil.test", source: composeWin, data },
+    [compose, staged],
+    { origin: ORIGIN, parent, embedded: true },
+  );
+
+  assert.equal(stagedWin.posts.length, 0, "a cross-origin message must not be relayed across");
+  assert.equal(parent.posts.length, 0, "a cross-origin message must not be forwarded up");
+});

package/src/runtime/core/host.ts

@@ -229,6 +229,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;
 }
 
 /**
@@ -487,6 +491,76 @@ export interface FormSchema {
   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.
@@ -616,6 +690,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
@@ -680,6 +788,9 @@ export const ENGINE_CLIENT_METHODS = [
   "searchElementInstanceWaitStates",
   "getElementInstance",
   "searchIncidents",
+  "searchVariables",
+  "searchJobs",
+  "getProcessDefinitionXml",
   "resolveIncident",
   "updateJobRetries",
   "setVariables",

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

@@ -37,6 +37,9 @@ const engine: EngineClient = {
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
   searchIncidents: async () => [],
+  searchVariables: async () => [],
+  searchJobs: async () => [],
+  getProcessDefinitionXml: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},

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

@@ -22,6 +22,9 @@ const fakeEngine: EngineClient = {
   searchElementInstanceWaitStates: async () => [],
   getElementInstance: async () => null,
   searchIncidents: async () => [],
+  searchVariables: async () => [],
+  searchJobs: async () => [],
+  getProcessDefinitionXml: async () => null,
   resolveIncident: async () => {},
   updateJobRetries: async () => {},
   setVariables: async () => {},