@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/server/metadata.js

@@ -0,0 +1,193 @@
+/**
+ * Read request-scoped secrets from the fctr metadata directory.
+ *
+ * In RPC mode the OE delivers per-tool secrets via `SetMetadata` before each
+ * tool call and clears them after (when restriction is enabled). fctr
+ * materializes the keyset as files at `/run/meta/<KEY>`. This module reads
+ * those files so the tool server can inject them into `process.env` for the
+ * duration of the call — or permanently when restriction is disabled.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.metadata`.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.metadata");
+const METADATA_DIR = "/run/meta";
+// Overlap accounting for applied-env regions. process.env is process-global:
+// if a region overlaps one that has secrets applied, its snapshot captures
+// those secrets as baseline and its restore re-installs them permanently
+// while deleting the other call's live ones. The ToolServer's
+// per-instance executeGate serializes its own routes, but that
+// invariant lives in the caller — these counters make the module itself fail
+// closed (throw before any env mutation) if any future call site overlaps a
+// secret-bearing region. Secret-less overlap stays allowed: the snapshots
+// are then identical to the live env and restore is idempotent, which is
+// what the cross-instance ToolServer overlap contract relies on.
+let activeRegions = 0;
+let activeSecretRegions = 0;
+/**
+ * Read all key-value pairs from the metadata directory.
+ *
+ * Returns a record mapping filename (the secret name) to file content (the
+ * secret value). Skips files that cannot be read and logs a warning. Returns
+ * an empty record when the directory does not exist.
+ */
+export function readMetadataSecrets(metadataDir = METADATA_DIR) {
+    let entries;
+    try {
+        entries = readdirSync(metadataDir, { withFileTypes: true });
+    }
+    catch {
+        return {};
+    }
+    const secrets = {};
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        try {
+            secrets[entry.name] = readFileSync(join(metadataDir, entry.name), "utf-8");
+        }
+        catch (e) {
+            logger.warn(`failed to read metadata file ${entry.name}`, e);
+        }
+    }
+    return secrets;
+}
+/**
+ * Overwrite `process.env` from `/run/meta`; no restore or prune.
+ */
+export function mergeMetadataEnv(metadataDir = METADATA_DIR) {
+    const secrets = readMetadataSecrets(metadataDir);
+    const count = Object.keys(secrets).length;
+    if (count === 0)
+        return;
+    Object.assign(process.env, secrets);
+    logger.debug(`merged ${count} metadata secret(s) into process.env (no restore)`);
+}
+/**
+ * Snapshot `process.env`, merge in the metadata secrets, and return a
+ * `restore()` that reverts `process.env`.
+ *
+ * What `restore()` does depends on how the region was entered:
+ *
+ * - *clean* (no other region was active — the serialized production flow):
+ *   full snapshot restore. Keys the region added are removed, overwritten
+ *   keys are reverted, and keys the callback deleted are reinstated.
+ * - *tainted* (entered while another, necessarily secret-less, region was
+ *   active): delete-only restore. Keys added since the snapshot are removed,
+ *   but no values are written back, since the snapshot holds the other
+ *   region's request-scoped state and rewriting it could outlive that
+ *   region's own restore. A tainted callback's overwrite of a pre-existing
+ *   key therefore survives the region.
+ *
+ * @throws if the region overlaps a concurrent secret-bearing region — either
+ * another region already has secrets applied, or this region carries secrets
+ * while any region is active. Thrown before `process.env` is touched (fail
+ * closed), so callers see a per-request error instead of a silent
+ * cross-request credential swap. Production call sites (`/execute`,
+ * `/invoke_llm`, `/invoke_llm/stream`) are serialized by the ToolServer's
+ * per-instance execute gate and do not hit this.
+ */
+function applyMetadataEnv(metadataDir) {
+    const secrets = readMetadataSecrets(metadataDir);
+    const count = Object.keys(secrets).length;
+    if (activeSecretRegions > 0 || (count > 0 && activeRegions > 0)) {
+        // Fail closed before mutating anything: proceeding would snapshot or
+        // clobber another request's live secrets.
+        throw new Error("metadata env region overlaps a concurrent secret-bearing region; " +
+            "refusing to apply request secrets to the shared process.env");
+    }
+    const snapshot = { ...process.env };
+    // A region that entered on a quiet environment owns the true baseline:
+    // its restore is a full snapshot restore — deleting added keys, reverting
+    // overwritten ones, and reinstating keys the callback deleted — the
+    // documented contract for the serialized (production) flow. A region that
+    // entered while another was active holds a snapshot tainted with that
+    // region's request-scoped state: writing any value from it could
+    // permanently reassert the other request's data after its restore, so a
+    // tainted restore only deletes the keys added since its snapshot and
+    // never writes values. (Tainted regions are secret-less by the guard
+    // above, so at worst a tainted callback's own overwrite of a pre-existing
+    // key outlives it.)
+    const enteredClean = activeRegions === 0;
+    const restoreEnv = () => {
+        for (const key of Object.keys(process.env)) {
+            if (!(key in snapshot))
+                delete process.env[key];
+        }
+        if (enteredClean) {
+            Object.assign(process.env, snapshot);
+        }
+    };
+    try {
+        Object.assign(process.env, secrets);
+    }
+    catch (e) {
+        // Node rejects some values (e.g. containing NUL) and Object.assign may
+        // have applied a prefix of the keys before throwing: roll the partial
+        // application back, and only count the region once the apply succeeded —
+        // otherwise the counters stay unbalanced and every later region rejects.
+        restoreEnv();
+        throw e;
+    }
+    activeRegions += 1;
+    if (count > 0) {
+        activeSecretRegions += 1;
+        logger.debug(`applied ${count} metadata secret(s) to process.env`);
+    }
+    let restored = false;
+    return {
+        restore() {
+            if (restored)
+                return;
+            restored = true;
+            activeRegions -= 1;
+            if (count > 0)
+                activeSecretRegions -= 1;
+            restoreEnv();
+        },
+    };
+}
+/**
+ * Run `fn` with metadata secrets merged into `process.env`, restoring the
+ * environment afterwards (even on throw).
+ *
+ * Mirrors Python's `applied_metadata_env` context manager for non-streaming
+ * call paths.
+ *
+ * @throws if this region overlaps a concurrent secret-bearing region; see
+ * {@link applyMetadataEnv} for the fail-closed rule and the clean-vs-tainted
+ * restore semantics.
+ */
+export async function withMetadataEnv(fn, metadataDir = METADATA_DIR) {
+    const applied = applyMetadataEnv(metadataDir);
+    try {
+        return await fn();
+    }
+    finally {
+        applied.restore();
+    }
+}
+/**
+ * Wrap an async generator so metadata secrets are present in `process.env`
+ * for the lifetime of the iteration, restoring the environment when iteration
+ * completes, throws, or is closed early.
+ *
+ * Mirrors Python's `applied_metadata_env` context manager for streaming call
+ * paths.
+ *
+ * @throws if this region overlaps a concurrent secret-bearing region — note a
+ * stream holds its region open for the whole iteration; see
+ * {@link applyMetadataEnv} for the fail-closed rule and the clean-vs-tainted
+ * restore semantics.
+ */
+export async function* withMetadataEnvGen(genFactory, metadataDir = METADATA_DIR) {
+    const applied = applyMetadataEnv(metadataDir);
+    try {
+        yield* genFactory();
+    }
+    finally {
+        applied.restore();
+    }
+}

package/dist/server/oe_url.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Trusted resolution of the Orchestration Engine callback URL.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.oe_url`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * `/execute` accepts a `platform_api_url` field, and that value used to
+ * become the base for every outbound call the runner made during an
+ * execution: tool and LLM approval requests, stream chunks, terminal
+ * results, node execution records. The runner then treats those responses
+ * as authoritative — as both the real tool/LLM result and the policy
+ * approval decision — so a caller-chosen URL could exfiltrate prompts and
+ * checkpointed history while injecting fabricated tool output and forged
+ * "approved" decisions back into the agent's reasoning, which are then
+ * persisted into session state.
+ *
+ * The runner already knows where its OE is: ECP stamps `OE_URL` on every
+ * runner component at deploy time. Preferring that over the request field
+ * removes the callback-hijack and SSRF surface rather than trying to
+ * validate an attacker-supplied string.
+ */
+/**
+ * Returns the OE base URL to use for callbacks during an execution.
+ *
+ * The runner's own `OE_URL` wins whenever it is configured. A differing
+ * request value is discarded and logged rather than honoured — quietly
+ * ignoring it would hide an attempted hijack.
+ *
+ * When `OE_URL` is unset the requested value is used. That is the local
+ * `agentengine dev` and unit-test path, where no deploy-time environment exists
+ * and the request originates from the developer's own stack; a warning is
+ * emitted so the weaker configuration is visible.
+ */
+export declare function resolveOeUrl(requested: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=oe_url.d.ts.map

package/dist/server/oe_url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oe_url.d.ts","sourceRoot":"","sources":["../../src/server/oe_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAiBR"}

package/dist/server/oe_url.js

@@ -0,0 +1,50 @@
+/**
+ * Trusted resolution of the Orchestration Engine callback URL.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.oe_url`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its
+ * Python twin must be changed together.
+ *
+ * `/execute` accepts a `platform_api_url` field, and that value used to
+ * become the base for every outbound call the runner made during an
+ * execution: tool and LLM approval requests, stream chunks, terminal
+ * results, node execution records. The runner then treats those responses
+ * as authoritative — as both the real tool/LLM result and the policy
+ * approval decision — so a caller-chosen URL could exfiltrate prompts and
+ * checkpointed history while injecting fabricated tool output and forged
+ * "approved" decisions back into the agent's reasoning, which are then
+ * persisted into session state.
+ *
+ * The runner already knows where its OE is: ECP stamps `OE_URL` on every
+ * runner component at deploy time. Preferring that over the request field
+ * removes the callback-hijack and SSRF surface rather than trying to
+ * validate an attacker-supplied string.
+ */
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.oe_url");
+/**
+ * Returns the OE base URL to use for callbacks during an execution.
+ *
+ * The runner's own `OE_URL` wins whenever it is configured. A differing
+ * request value is discarded and logged rather than honoured — quietly
+ * ignoring it would hide an attempted hijack.
+ *
+ * When `OE_URL` is unset the requested value is used. That is the local
+ * `agentengine dev` and unit-test path, where no deploy-time environment exists
+ * and the request originates from the developer's own stack; a warning is
+ * emitted so the weaker configuration is visible.
+ */
+export function resolveOeUrl(requested, env = process.env) {
+    const configured = (env["OE_URL"] ?? "").trim();
+    if (!configured) {
+        logger.warn("OE_URL is not configured; falling back to the caller-supplied " +
+            "platform_api_url. Set OE_URL so the callback target cannot be " +
+            "chosen by the request.");
+        return requested;
+    }
+    if (requested && requested !== configured) {
+        logger.warn(`Discarding caller-supplied platform_api_url ${JSON.stringify(requested)}; ` +
+            `using the configured OE_URL ${JSON.stringify(configured)}.`);
+    }
+    return configured;
+}

package/dist/server/owner_url.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Validation of a request-supplied replica-specific OE owner callback URL.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.owner_url`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its Python
+ * twin must be changed together.
+ *
+ * Dark-ship owner-callback fallback: the OE may stamp a `*_owner_url`
+ * onto the execute / tool request naming the specific OE replica that owns the
+ * execution. The runner delivers stream chunks, terminal callbacks and tool
+ * results straight to that replica and falls back to the trusted service URL
+ * when that owner-specific callback attempt is unusable.
+ *
+ * That owner URL is request-supplied, which reopens the callback-hijack / SSRF
+ * surface that `resolveOeUrl` (see `oe_url.ts`) exists to close. Unlike the OE
+ * base URL — where the runner's own deploy-time `OE_URL` is simply preferred —
+ * the owner URL has no trusted counterpart to fall back to, so it is accepted
+ * only when it is provably the headless-service address of one replica *behind
+ * the already-trusted service URL*: identical scheme, identical port (explicit
+ * or scheme default), and a host of exactly
+ * `<one-dns-label>.<service-label>-headless.<rest>` when the service host is
+ * `<service-label>.<rest>`. Anything else is logged and discarded — never an
+ * error — and the caller keeps using the trusted service URL.
+ */
+/**
+ * Return the canonical bare origin of `ownerUrl` when it is a valid replica of
+ * `serviceUrl`, else `null`.
+ *
+ * `null` means "no usable owner URL"; the caller sends to the trusted
+ * `serviceUrl` instead. A malformed or forged owner URL is logged at WARNING
+ * and discarded rather than thrown — a rejected value must degrade to the safe
+ * default, never fail the callback.
+ */
+export declare function resolveOwnerUrl(ownerUrl: string | null | undefined, serviceUrl: string): string | null;
+//# sourceMappingURL=owner_url.d.ts.map

package/dist/server/owner_url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner_url.d.ts","sourceRoot":"","sources":["../../src/server/owner_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAqDH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAqFf"}

package/dist/server/owner_url.js

@@ -0,0 +1,146 @@
+/**
+ * Validation of a request-supplied replica-specific OE owner callback URL.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.owner_url`. Both runtimes are parallel
+ * implementations of the same server architecture, so this file and its Python
+ * twin must be changed together.
+ *
+ * Dark-ship owner-callback fallback: the OE may stamp a `*_owner_url`
+ * onto the execute / tool request naming the specific OE replica that owns the
+ * execution. The runner delivers stream chunks, terminal callbacks and tool
+ * results straight to that replica and falls back to the trusted service URL
+ * when that owner-specific callback attempt is unusable.
+ *
+ * That owner URL is request-supplied, which reopens the callback-hijack / SSRF
+ * surface that `resolveOeUrl` (see `oe_url.ts`) exists to close. Unlike the OE
+ * base URL — where the runner's own deploy-time `OE_URL` is simply preferred —
+ * the owner URL has no trusted counterpart to fall back to, so it is accepted
+ * only when it is provably the headless-service address of one replica *behind
+ * the already-trusted service URL*: identical scheme, identical port (explicit
+ * or scheme default), and a host of exactly
+ * `<one-dns-label>.<service-label>-headless.<rest>` when the service host is
+ * `<service-label>.<rest>`. Anything else is logged and discarded — never an
+ * error — and the caller keeps using the trusted service URL.
+ */
+import { getLogger } from "../logger.js";
+const logger = getLogger("agent_engine_runner_shared.server.owner_url");
+// WHATWG URL protocols carry a trailing colon.
+const DEFAULT_PORTS = { "http:": 80, "https:": 443 };
+// A single DNS label: alphanumerics plus interior hyphens. A dashed pod IP such
+// as `10-1-2-3` — the label the OE actually stamps — qualifies. WHATWG URL
+// lowercases the host, so a lowercase-only pattern is sufficient.
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+/** Stable, non-secret URL summary safe for warning logs. */
+function describeUrlForLog(url) {
+    return JSON.stringify(url.port === ""
+        ? `${url.protocol}//${url.hostname}`
+        : `${url.protocol}//${url.hostname}:${url.port}`);
+}
+/** Effective port for `url` — explicit if present, else the scheme default. */
+function effectivePort(url) {
+    if (url.port !== "")
+        return Number(url.port);
+    return DEFAULT_PORTS[url.protocol] ?? null;
+}
+/** Canonical bare origin for `url`, omitting scheme-default ports. */
+function canonicalOrigin(url) {
+    const port = effectivePort(url);
+    const defaultPort = DEFAULT_PORTS[url.protocol] ?? null;
+    return port === null || port === defaultPort
+        ? `${url.protocol}//${url.hostname}`
+        : `${url.protocol}//${url.hostname}:${port}`;
+}
+function hasAsciiControl(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** Split a host on its first dot into `[label, rest]`, or null if there is none. */
+function partitionHost(host) {
+    const idx = host.indexOf(".");
+    if (idx === -1)
+        return null;
+    return [host.slice(0, idx), host.slice(idx + 1)];
+}
+/**
+ * Return the canonical bare origin of `ownerUrl` when it is a valid replica of
+ * `serviceUrl`, else `null`.
+ *
+ * `null` means "no usable owner URL"; the caller sends to the trusted
+ * `serviceUrl` instead. A malformed or forged owner URL is logged at WARNING
+ * and discarded rather than thrown — a rejected value must degrade to the safe
+ * default, never fail the callback.
+ */
+export function resolveOwnerUrl(ownerUrl, serviceUrl) {
+    if (!ownerUrl)
+        return null;
+    if (hasAsciiControl(ownerUrl)) {
+        logger.warn("Discarding owner URL (contains control characters); " +
+            "using configured service URL");
+        return null;
+    }
+    let owner;
+    let service;
+    try {
+        owner = new URL(ownerUrl);
+        service = new URL(serviceUrl);
+    }
+    catch {
+        logger.warn("Discarding unparseable owner URL; " + "using configured service URL");
+        return null;
+    }
+    const serviceSummary = describeUrlForLog(service);
+    const reject = (reason) => {
+        logger.warn(`Discarding owner URL (${reason}); ` +
+            `using service URL ${serviceSummary}`);
+    };
+    // The OE stamps a bare origin. Credentials, a path, a query, or a fragment
+    // are never expected and would ride along when a callback path is appended,
+    // so treat their presence as a forged value. WHATWG URL yields a "/" pathname
+    // for a bare origin, so "" and "/" are the only acceptable paths.
+    if (owner.username ||
+        owner.password ||
+        (owner.pathname !== "" && owner.pathname !== "/") ||
+        owner.search ||
+        owner.hash) {
+        reject("not a bare origin");
+        return null;
+    }
+    if (owner.protocol !== service.protocol) {
+        reject("scheme mismatch");
+        return null;
+    }
+    const ownerPort = effectivePort(owner);
+    const servicePort = effectivePort(service);
+    if (ownerPort === null || ownerPort !== servicePort) {
+        reject("port mismatch");
+        return null;
+    }
+    const ownerHost = owner.hostname;
+    const serviceHost = service.hostname;
+    if (!ownerHost || !serviceHost) {
+        reject("missing host");
+        return null;
+    }
+    const servicePart = partitionHost(serviceHost);
+    if (servicePart === null || !servicePart[0] || !servicePart[1]) {
+        reject("service host is not <label>.<rest>");
+        return null;
+    }
+    const [serviceLabel, serviceRest] = servicePart;
+    // partitionHost() splits on the first dot, so this guarantees exactly one
+    // leading label; the exact-match on the remainder enforces the full shape.
+    const ownerPart = partitionHost(ownerHost);
+    if (ownerPart === null || !DNS_LABEL.test(ownerPart[0])) {
+        reject("owner host is not <label>.<rest>");
+        return null;
+    }
+    if (ownerPart[1] !== `${serviceLabel}-headless.${serviceRest}`) {
+        reject("owner host is not a headless replica of the service host");
+        return null;
+    }
+    return canonicalOrigin(owner);
+}

package/dist/server/query.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Framework-agnostic query plugin protocol for the AER.
+ *
+ * The AER hosts two read endpoints that surface framework-specific persisted
+ * state — per-session summary and conversation messages. The implementations
+ * live in framework adapter packages (e.g. `agent-engine-sdk-langgraph-ts`); the
+ * AER itself only hosts the routes and delegates to whichever plugin the
+ * framework SDK registered via `registerQueryPlugin()`.
+ *
+ * Mirrors Python's `agent_engine_runner_shared/server/query.py`.
+ *
+ * Trust model
+ * -----------
+ *
+ * These endpoints take no workspace identifier on the wire. The AER trusts its
+ * caller (the platform's Orchestration Engine proxy) to pass only session_ids
+ * that belong to the caller's workspace; the OE establishes that scope by
+ * consulting the `executions` collection — which is tagged with
+ * `workspace_id` — before issuing the request. The framework plugin then
+ * narrows reads by its own session key. For the LangGraph plugin that key is
+ * the workspace-scoped composite `session_id:workspace_id`. The workspace is
+ * workspace is resolved the same way on read and write — `APP_ID` when set,
+ * otherwise the wire `workspace_id` from the most recent `/execute` — so a
+ * plugin keyed to one workspace cannot read another's checkpoints even if a
+ * stray session_id slipped past the proxy — defense in depth, not a substitute
+ * for the upstream ownership check.
+ */
+import type { SessionMessagesResponse, SessionsSummaryResponse } from "@mongodb-js/agent-engine-sdk";
+/**
+ * Read-side plugin that surfaces framework-specific session state.
+ *
+ * Implementations live alongside framework adapters and read from the
+ * adapter's persistence (LangGraph checkpoint collections, ADK state
+ * store, etc.).
+ */
+export interface AERQueryPlugin {
+    /** Given a list of session_ids, return a SessionsSummaryResponse. */
+    getSummariesForSessions(sessionIds: string[]): Promise<SessionsSummaryResponse>;
+    /** Given a session_id, return a SessionMessagesResponse. */
+    getMessagesForSession(sessionId: string): Promise<SessionMessagesResponse>;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/server/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/server/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,uBAAuB,CACrB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEpC,4DAA4D;IAC5D,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC5E"}

package/dist/server/query.js

@@ -0,0 +1,28 @@
+/**
+ * Framework-agnostic query plugin protocol for the AER.
+ *
+ * The AER hosts two read endpoints that surface framework-specific persisted
+ * state — per-session summary and conversation messages. The implementations
+ * live in framework adapter packages (e.g. `agent-engine-sdk-langgraph-ts`); the
+ * AER itself only hosts the routes and delegates to whichever plugin the
+ * framework SDK registered via `registerQueryPlugin()`.
+ *
+ * Mirrors Python's `agent_engine_runner_shared/server/query.py`.
+ *
+ * Trust model
+ * -----------
+ *
+ * These endpoints take no workspace identifier on the wire. The AER trusts its
+ * caller (the platform's Orchestration Engine proxy) to pass only session_ids
+ * that belong to the caller's workspace; the OE establishes that scope by
+ * consulting the `executions` collection — which is tagged with
+ * `workspace_id` — before issuing the request. The framework plugin then
+ * narrows reads by its own session key. For the LangGraph plugin that key is
+ * the workspace-scoped composite `session_id:workspace_id`. The workspace is
+ * workspace is resolved the same way on read and write — `APP_ID` when set,
+ * otherwise the wire `workspace_id` from the most recent `/execute` — so a
+ * plugin keyed to one workspace cannot read another's checkpoints even if a
+ * stray session_id slipped past the proxy — defense in depth, not a substitute
+ * for the upstream ownership check.
+ */
+export {};