@arcgis/ai-components 5.2.0-next.12 → 5.2.0-next.121

package/dist/chunks/orchestrator.js

@@ -1,50 +1,65 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
-import R from "@arcgis/core/identity/IdentityManager.js";
-import C from "@arcgis/core/portal/Portal.js";
-import { n as I, o as v, D as k, p as A, q as M, W as F } from "./generateLayerDescriptions.js";
-import { isGraphInterrupt as D, StateGraph as L, START as W, END as $, MemorySaver as j } from "@langchain/langgraph/web";
-import { HumanMessage as q, AIMessage as H } from "@langchain/core/messages";
-import { s as l } from "./index.js";
-import * as P from "@arcgis/core/core/reactiveUtils.js";
-import U from "@arcgis/core/layers/FeatureLayer.js";
-import O from "@arcgis/core/request.js";
-const T = async (t) => {
-  const e = await N(), r = await I("default"), s = C.getDefault(), a = (await R.getCredential(`${s.url}/sharing`)).token, i = {
+import F from "@arcgis/core/identity/IdentityManager.js";
+import D from "@arcgis/core/portal/Portal.js";
+import { b as L, g as v, a as E, d as q } from "./aiFactory.js";
+import { isGraphInterrupt as W, StateGraph as $, START as P, END as T, MemorySaver as j } from "@langchain/langgraph/web";
+import { generateGuid as C } from "@arcgis/toolkit/string";
+import { g as I, D as H, b as U, W as O } from "./generateLayerDescriptions.js";
+import { HumanMessage as G, AIMessage as N } from "@langchain/core/messages";
+import { s as p } from "./index.js";
+import { BaseCallbackHandler as V } from "@langchain/core/callbacks/base";
+import * as z from "@arcgis/core/core/reactiveUtils.js";
+import B from "@arcgis/core/layers/FeatureLayer.js";
+import Q from "@arcgis/core/request.js";
+const K = async (t) => {
+  const e = await J(), r = await L("default"), s = D.getDefault(), a = (await F.getCredential(`${s.url}/sharing`)).token, o = {
     type: "generateEmbeddings",
     webmapEmbeddings: t,
     auth: { apiUrl: r, token: a }
   };
-  return e.postMessage(i), await new Promise((c, d) => {
-    const o = (u) => {
-      u.data === "completed" && (e.removeEventListener("message", o), c());
-    }, g = (u) => {
-      e.removeEventListener("message", o), d(u instanceof Error ? u : new Error("Embeddings worker error"));
+  return e.postMessage(o), await new Promise((i, c) => {
+    const u = (g) => {
+      g.data === "completed" && (e.removeEventListener("message", u), i());
+    }, d = (g) => {
+      e.removeEventListener("message", u), c(g instanceof Error ? g : new Error("Embeddings worker error"));
     };
-    e.addEventListener("message", o), e.addEventListener("error", g, { once: !0 });
+    e.addEventListener("message", u), e.addEventListener("error", d, { once: !0 });
   }), e;
-}, N = async () => {
+}, J = async () => {
   {
     const t = (await import("./embeddings.worker.js")).default;
     return new t();
   }
-}, G = (t) => {
+}, X = (t) => {
   t.currentIntent = "none";
-}, _ = async (t, e) => {
-  const r = v(e);
+}, Y = async (t, e) => {
+  const r = I(e), s = await v({
+    path: "./assets/orchestrator/t9n",
+    locale: E(e)
+  });
   if (t.agentExecutionContext.userRequest) {
-    const n = new q(t.agentExecutionContext.userRequest.trim());
-    t.agentExecutionContext.messages = [...t.agentExecutionContext.messages, n], G(t);
+    const a = new G(t.agentExecutionContext.userRequest.trim());
+    t.agentExecutionContext.messages = [...t.agentExecutionContext.messages, a], X(t);
   }
-  const s = r?.services.agentRegistry.list().map((n) => n.agent.id) ?? [];
-  return await l({ text: `Available agents: ${[...s].join(", ")}` }, e), await l({ text: "Analyzing user input" }, e), t;
-}, V = async (t, e) => (await l({ text: "Exiting..." }, e), t), w = (t) => typeof t == "object" && t !== null && !Array.isArray(t), z = (t, e) => {
-  if (!w(t)) {
+  const n = r?.services.agentRegistry.list().map((a) => a.agent.id) ?? [];
+  return await p(
+    { text: s.availableAgents.replace("{agentIds}", [...n].join(", ")) },
+    e
+  ), await p({ text: s.analyzingUserInput }, e), t;
+}, Z = async (t, e) => {
+  const r = await v({
+    path: "./assets/orchestrator/t9n",
+    locale: E(e)
+  });
+  return await p({ text: r.exiting }, e), t;
+}, x = (t) => typeof t == "object" && t !== null && !Array.isArray(t), ee = (t, e) => {
+  if (!x(t)) {
     t !== void 0 && console.warn(`Agent "${e}" returned invalid sharedStatePatch. Ignoring it.`);
     return;
   }
   const r = {};
   for (const [s, n] of Object.entries(t)) {
-    if (!w(n) || !("value" in n)) {
+    if (!x(n) || !("value" in n)) {
       console.warn(
         `Agent "${e}" returned invalid sharedStatePatch entry for key "${s}". Ignoring that entry.`
       );
@@ -53,28 +68,72 @@ const T = async (t) => {
     r[s] = { value: n.value };
   }
   return r;
-}, Q = (t) => {
+}, te = (t) => {
   const { previousSharedState: e, patch: r, agentId: s } = t;
   if (!r)
     return e;
   const n = Date.now(), a = {
     ...e
   };
-  for (const [i, c] of Object.entries(r))
-    c?.value !== void 0 && (a[i] = {
-      value: c.value,
+  for (const [o, i] of Object.entries(r))
+    i?.value !== void 0 && (a[o] = {
+      value: i.value,
       meta: {
         updatedByAgentId: s,
         updatedAt: n
       }
     });
   return a;
-}, f = (t) => {
+}, ne = 256, re = /* @__PURE__ */ new Set(["point", "polyline", "polygon", "extent", "custom"]), se = (t) => typeof t == "object" && t !== null && !Array.isArray(t), ae = (t, e) => {
+  if (t === void 0)
+    return;
+  if (!Array.isArray(t)) {
+    console.warn(`Agent "${e}" returned invalid sharedResourceAdditions. Ignoring it.`);
+    return;
+  }
+  const r = [];
+  for (const [s, n] of t.entries()) {
+    if (!se(n) || typeof n.kind != "string" || !re.has(n.kind) || typeof n.description != "string" || !n.description.trim() || !("payload" in n) || n.payload === void 0) {
+      console.warn(
+        `Agent "${e}" returned invalid sharedResourceAdditions entry at index ${s}. Ignoring that entry.`
+      );
+      continue;
+    }
+    let a;
+    try {
+      a = structuredClone(n.payload);
+    } catch {
+      console.warn(
+        `Agent "${e}" returned invalid sharedResourceAdditions entry at index ${s}. Ignoring that entry.`
+      );
+      continue;
+    }
+    r.push({
+      kind: n.kind,
+      description: n.description.trim().slice(0, ne),
+      payload: a
+    });
+  }
+  return r.length ? r : void 0;
+}, ie = (t) => {
+  const { previousSharedResources: e, additions: r, agentId: s } = t;
+  if (!r?.length)
+    return e;
+  const n = Date.now(), a = r.map((o) => ({
+    ...o,
+    id: C(),
+    meta: {
+      createdByAgentId: s,
+      createdAt: n
+    }
+  }));
+  return [...e, ...a].slice(-50);
+}, S = (t) => {
   if (typeof t != "string")
     return;
   const e = t.trim();
   return e || void 0;
-}, B = (t) => {
+}, oe = (t) => {
   switch (t) {
     case "failed":
       return "Agent failed without a summary.";
@@ -85,39 +144,50 @@ const T = async (t) => {
     default:
       return "Agent completed without a summary.";
   }
-}, J = (t, e) => {
-  const r = f(e?.outputMessage), s = f(e?.summary), n = e?.status, a = n === "success" || n === "failed" ? n : "unknown";
+}, ce = (t, e) => {
+  const r = S(e?.outputMessage), s = S(e?.summary), n = e?.status, a = n === "success" || n === "failed" ? n : "unknown";
   a === "unknown" && console.warn(`Agent "${t}" returned missing/invalid status. Defaulting to "unknown".`);
-  const i = z(e?.sharedStatePatch, t);
+  const o = ee(e?.sharedStatePatch, t), i = ae(e?.sharedResourceAdditions, t);
   return {
     outputMessage: r,
-    summary: s ?? r ?? B(a),
+    summary: s ?? r ?? oe(a),
     status: a,
-    sharedStatePatch: i
+    sharedStatePatch: o,
+    sharedResourceAdditions: i
   };
-}, E = 4e3, K = async (t, e) => {
-  const r = v(e);
-  if (r?.abortSignal?.aborted)
-    return await l({ text: "Run cancelled; skipping agent execution" }, e), {
+}, b = 4e3, de = async (t, e) => {
+  const r = I(e), s = await v({
+    path: "./assets/orchestrator/t9n",
+    locale: E(e)
+  });
+  if (e?.signal?.aborted)
+    return await p({ text: s.runCancelledAgentExecution }, e), {
       ...t,
       currentIntent: "none",
       requiresFollowUp: !1
     };
-  const { agentRegistry: s } = r?.services ?? {}, n = s?.get(t.currentIntent);
-  if (!n)
-    return console.warn(`No agent found for intent: ${t.currentIntent}`), t;
-  await l({ text: `Executing registered agent: ${n.agent.name}` }, e);
-  const a = {
+  const { agentRegistry: n } = r?.services ?? {}, a = n?.get(t.currentIntent);
+  if (!a)
+    return console.warn(s.noAgentFoundForIntent.replace("{intent}", t.currentIntent)), t;
+  await p(
+    { text: s.executingRegisteredAgent.replace("{agentName}", a.agent.name) },
+    e
+  );
+  const o = {
     ...e ?? {},
+    metadata: {
+      ...e?.metadata,
+      agentId: a.agent.id
+    },
     configurable: {
       ...r ?? {},
-      agentId: n.agent.id,
-      context: n.getContext ? await n.getContext() : void 0
+      agentId: a.agent.id,
+      context: a.getContext ? await a.getContext() : void 0
     }
   };
   let i;
   try {
-    const o = await n.agent.createGraph().compile().invoke(
+    const d = await a.agent.createGraph().compile().invoke(
       {
         agentExecutionContext: {
           ...t.agentExecutionContext,
@@ -125,58 +195,162 @@ const T = async (t) => {
           messages: [...t.agentExecutionContext.messages],
           // deep clone to prevent accidental mutations by agents
           priorSteps: structuredClone(t.agentExecutionContext.priorSteps ?? []),
-          sharedState: structuredClone(t.agentExecutionContext.sharedState ?? {})
+          sharedState: structuredClone(t.agentExecutionContext.sharedState ?? {}),
+          sharedResources: structuredClone(t.agentExecutionContext.sharedResources ?? [])
         }
       },
-      a
+      o
     );
-    i = J(n.agent.name, o), await l({ text: `Finished executing registered agent: ${n.agent.name}` }, e);
-  } catch (o) {
-    if (D(o))
-      throw o;
-    const g = o instanceof Error ? o.message : String(o);
-    console.error(`Agent "${n.agent.name}" failed:`, o), await l({ text: `Registered agent failed: ${n.agent.name}. ${g}` }, e), i = {
+    i = ce(a.agent.name, d), await p(
+      { text: s.finishedExecutingRegisteredAgent.replace("{agentName}", a.agent.name) },
+      e
+    );
+  } catch (d) {
+    if (W(d) || e?.signal?.aborted || d instanceof Error && d.name === "AbortError")
+      throw d;
+    const g = d instanceof Error ? d.message : String(d);
+    console.error(`Agent "${a.agent.name}" failed:`, d), await p(
+      {
+        text: s.registeredAgentFailed.replace("{agentName}", a.agent.name).replace("{error}", g)
+      },
+      e
+    ), i = {
       status: "failed",
-      outputMessage: `Agent execution failed: ${g}`,
-      summary: `Agent execution failed: ${g}`
+      outputMessage: s.agentExecutionFailed.replace("{error}", g),
+      summary: s.agentExecutionFailed.replace("{error}", g)
     };
   }
-  const c = i.outputMessage, d = [...t.agentExecutionContext.messages];
+  const c = i.outputMessage, u = [...t.agentExecutionContext.messages];
   if (c) {
-    const o = c.length > E ? `${c.slice(0, E - 14)}
+    const d = c.length > b ? `${c.slice(0, b - 14)}
 [truncated]` : c;
-    d.push(new H(o));
+    u.push(new N(d));
   }
   return {
     ...t,
     stepCount: t.stepCount + 1,
-    lastExecutedAgent: n.agent.id,
+    lastExecutedAgent: a.agent.id,
     requiresFollowUp: i.status === "failed" ? !0 : t.requiresFollowUp,
     finalOutputMessage: c ?? "",
     agentExecutionContext: {
       ...t.agentExecutionContext,
-      messages: d,
+      messages: u,
       priorSteps: [
         ...t.agentExecutionContext.priorSteps ?? [],
         {
-          agentId: n.agent.id,
+          agentId: a.agent.id,
           assignedTask: t.agentExecutionContext.assignedTask,
-          summary: i?.summary || "No summary provided.",
+          summary: i?.summary || s.noSummaryProvided,
           status: i?.status || "unknown"
         }
       ],
-      sharedState: Q({
+      sharedState: te({
         previousSharedState: t.agentExecutionContext.sharedState,
         patch: i.sharedStatePatch,
-        agentId: n.agent.id
+        agentId: a.agent.id
+      }),
+      sharedResources: ie({
+        previousSharedResources: t.agentExecutionContext.sharedResources,
+        additions: i.sharedResourceAdditions,
+        agentId: a.agent.id
       })
     }
   };
-}, X = 3, Y = () => new L(k).addNode("ingestInput", _).addNode("intentLLM", A).addNode("executeRegisteredAgent", K).addNode("exit", V).addEdge(W, "ingestInput").addEdge("ingestInput", "intentLLM").addConditionalEdges("intentLLM", (e) => e.currentIntent === "none" || e.currentIntent === e.lastExecutedAgent ? "exit" : "executeRegisteredAgent").addConditionalEdges(
-  "executeRegisteredAgent",
-  (e) => e.stepCount >= X || !e.requiresFollowUp ? "exit" : "intentLLM"
-).addEdge("exit", $);
-class Z {
+}, ue = async (t, e) => {
+  const r = await v({
+    path: "./assets/orchestrator/t9n",
+    locale: E(e)
+  });
+  if (t.routing.mode !== "direct")
+    throw new Error(r.directAgentAssignmentRequiresDirectRouting);
+  return await p({ text: r.directRouteToAgent.replace("{agentId}", t.routing.agentId) }, e), {
+    ...t,
+    currentIntent: t.routing.agentId,
+    requiresFollowUp: !1,
+    agentExecutionContext: {
+      ...t.agentExecutionContext,
+      assignedTask: t.agentExecutionContext.userRequest
+    }
+  };
+}, ge = 3, le = (t) => t.routing.mode === "direct" ? "assignDirectAgent" : "intentLLM", he = (t) => t.routing.mode === "direct" || t.stepCount >= ge || !t.requiresFollowUp ? "exit" : "intentLLM", pe = () => new $(H).addNode("ingestInput", Y).addNode("assignDirectAgent", ue).addNode("intentLLM", U).addNode("executeRegisteredAgent", de).addNode("exit", Z).addEdge(P, "ingestInput").addConditionalEdges("ingestInput", le).addEdge("assignDirectAgent", "executeRegisteredAgent").addConditionalEdges("intentLLM", (e) => e.currentIntent === "none" || e.currentIntent === e.lastExecutedAgent ? "exit" : "executeRegisteredAgent").addConditionalEdges("executeRegisteredAgent", he).addEdge("exit", T), me = (t, e) => {
+  const r = t.output?.usage_metadata ?? e.usage_metadata, s = t.output?.llmOutput?.tokenUsage, n = r?.input_tokens ?? s?.promptTokens, a = r?.output_tokens ?? s?.completionTokens, o = r?.total_tokens ?? s?.totalTokens;
+  if (n === void 0 || a === void 0 || o === void 0)
+    return;
+  const i = r?.input_token_details?.cache_read, c = r?.output_token_details?.reasoning;
+  return {
+    input: n,
+    output: a,
+    total: o,
+    ...i !== void 0 && { cacheRead: i },
+    ...c !== void 0 && { reasoning: c }
+  };
+}, ye = (t, e, r, s) => {
+  switch (t) {
+    case "chat_model":
+    case "llm":
+      return "model";
+    case "tool":
+    case "retriever":
+      return t;
+    case "chain":
+      return !s || e === "LangGraph" ? "workflow" : r === e ? "node" : "chain";
+    default:
+      return;
+  }
+}, fe = (t) => {
+  if (t instanceof Error)
+    return { message: t.message, name: t.name };
+  const e = t, r = typeof e?.message == "string" ? e.message : String(t ?? "Unknown runtime error"), s = typeof e?.name == "string" ? e.name : void 0;
+  return { message: r, ...s && { name: s } };
+}, we = ({
+  event: t,
+  runId: e,
+  parentSpanId: r,
+  timestamp: s
+}) => {
+  const n = /^on_(.+)_(start|end|error)$/u.exec(t.event);
+  if (!n)
+    return;
+  const [, a, o] = n, i = t.metadata ?? {}, c = i.langgraph_node, u = ye(a, t.name, c, r);
+  if (!u)
+    return;
+  const d = i.agentId, g = i.model ?? i.ls_model_name, l = t.data, f = o === "end" && u === "model" ? me(l, i) : void 0, h = t.tags?.includes("langsmith:hidden") || c === "__start__", R = {
+    ...g && { model: g },
+    ...f && { tokenUsage: f },
+    ...h && { internal: !0 }
+  }, w = {
+    id: t.run_id,
+    ...r && { parentId: r },
+    label: t.name,
+    type: u,
+    ...Object.keys(R).length && { metadata: R }
+  }, m = { runId: e, timestamp: s, type: "runtime", ...d && { agentId: d } };
+  switch (o) {
+    case "start":
+      return {
+        ...m,
+        phase: "started",
+        span: {
+          ...w,
+          ...l?.input !== void 0 && { input: l.input }
+        }
+      };
+    case "end":
+      return {
+        ...m,
+        phase: "completed",
+        span: {
+          ...w,
+          ...l?.output !== void 0 && { output: l.output }
+        }
+      };
+    case "error":
+      return { ...m, phase: "failed", span: { ...w, error: fe(l?.error) } };
+    default:
+      return;
+  }
+};
+class A {
   constructor() {
     this.agentRegistry = /* @__PURE__ */ new Map();
   }
@@ -193,7 +367,7 @@ class Z {
     return [...this.agentRegistry.values()];
   }
 }
-class ee {
+class ve {
   /**
    * Create a new InterruptHandler tied to a specific compiled graph and config.
    */
@@ -240,34 +414,34 @@ class ee {
     this.rejectWait && (this.rejectWait(new Error("Request cancelled by user.")), this.resolveWait = void 0, this.rejectWait = void 0);
   }
 }
-const te = async (t) => {
+const Ee = async (t) => {
   try {
-    return await (await M()).embedDocuments(t);
+    return await (await q()).embedDocuments(t);
   } catch (e) {
     throw console.error("Failed to generate embeddings:", e), e;
   }
-}, b = async (t, e) => {
+}, k = async (t, e) => {
   const r = e.get(t);
   if (r)
     return r;
-  const s = await te([t]);
+  const s = await Ee([t]);
   return e.set(t, s[0]), s[0];
 };
-async function re(t, e, r, s) {
-  const n = `req-${Date.now()}`, i = {
+async function Re(t, e, r, s) {
+  const n = `req-${Date.now()}`, o = {
     type: "layerSearch",
-    precomputedEmbedding: s ? await b(t, s) : void 0,
+    precomputedEmbedding: s ? await k(t, s) : void 0,
     requestId: n,
     minScore: r
   };
-  return await new Promise((c) => {
-    const d = (o) => {
-      o.data.requestId === n && c(o.data.results);
+  return await new Promise((i) => {
+    const c = (u) => {
+      u.data.requestId === n && i(u.data.results);
     };
-    e.addEventListener("message", d, { once: !0 }), e.postMessage(i);
+    e.addEventListener("message", c, { once: !0 }), e.postMessage(o);
   });
 }
-function ne(t) {
+function xe(t) {
   const { worker: e } = t;
   return {
     async searchLayers({
@@ -275,11 +449,11 @@ function ne(t) {
       minScore: s,
       embeddingCache: n
     }) {
-      return await re(r, e, s, n);
+      return await Re(r, e, s, n);
     }
   };
 }
-const se = async ({
+const Se = async ({
   combinedQuery: t,
   layerIds: e,
   embeddingsWorker: r,
@@ -287,51 +461,51 @@ const se = async ({
   topResults: n,
   embeddingCache: a
 }) => {
-  const i = `req-${Date.now()}`, c = a ? await b(t, a) : void 0, d = {
+  const o = `req-${Date.now()}`, i = a ? await k(t, a) : void 0, c = {
     type: "fieldSearch",
     layerIdForFieldsSearch: e,
-    precomputedEmbedding: c,
-    requestId: i,
+    precomputedEmbedding: i,
+    requestId: o,
     minScore: s,
     topResults: n
   };
-  return await new Promise((o) => {
-    const g = (u) => {
-      if (u.data.requestId !== i)
+  return await new Promise((u) => {
+    const d = (g) => {
+      if (g.data.requestId !== o)
         return;
-      const p = u.data.results.map(({ layerId: y, results: m }) => ({
-        layerId: y,
-        results: m
+      const l = g.data.results.map(({ layerId: f, results: h }) => ({
+        layerId: f,
+        results: h
       }));
-      o(p);
+      u(l);
     };
-    r.addEventListener("message", g, { once: !0 }), r.postMessage(d);
+    r.addEventListener("message", d, { once: !0 }), r.postMessage(c);
   });
 };
-function ae(t) {
+function be(t) {
   const { worker: e } = t;
   return {
-    async searchFields({ text: r, layerIds: s, minScore: n, topResults: a, embeddingCache: i }) {
-      return await se({
+    async searchFields({ text: r, layerIds: s, minScore: n, topResults: a, embeddingCache: o }) {
+      return await Se({
         combinedQuery: r,
         layerIds: s,
         embeddingsWorker: e,
         minScore: n,
         topResults: a,
-        embeddingCache: i
+        embeddingCache: o
       });
     }
   };
 }
-const ie = (t) => {
-  const e = F.safeParse(t);
+const Ae = (t) => {
+  const e = O.safeParse(t);
   if (!e.success)
     throw new Error("Embeddings response validation failed. Regenerate embeddings.");
   return e.data;
-}, oe = (t, e) => {
+}, Ce = (t, e) => {
   const r = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map();
   if (e.allLayers.forEach((n) => {
-    n instanceof U && s.set(n.id, n);
+    n instanceof B && s.set(n.id, n);
   }), t.length !== s.size)
     throw new Error("Layer count mismatch during registry restoration. Regenerate embeddings.");
   for (const n of t) {
@@ -344,53 +518,53 @@ const ie = (t) => {
       throw new Error(
         `Field count mismatch for layer ID ${n.id} during registry restoration. Regenerate embeddings.`
       );
-    const i = {
+    const o = {
       name: n.name,
       title: n.title,
       description: n.description
-    }, c = /* @__PURE__ */ new Map();
-    for (const d of n.fields) {
-      const o = a.fieldsIndex.get(d.name);
-      if (!o)
+    }, i = /* @__PURE__ */ new Map();
+    for (const c of n.fields) {
+      const u = a.fieldsIndex.get(c.name);
+      if (!u)
         throw new Error(
-          `Field with name ${d.name} not found in the original layer ${n.id} during registry restoration. Regenerate embeddings.`
+          `Field with name ${c.name} not found in the original layer ${n.id} during registry restoration. Regenerate embeddings.`
         );
-      c.set(d.name, {
-        name: d.name,
-        alias: a.getFieldAlias(d.name) ?? d.alias,
-        description: d.description,
-        type: o.type || "unknown",
-        valueType: o.valueType || "unknown",
-        domain: a.getFieldDomain(d.name) ?? void 0
+      i.set(c.name, {
+        name: c.name,
+        alias: a.getFieldAlias(c.name) ?? c.alias,
+        description: c.description,
+        type: u.type || "unknown",
+        valueType: u.valueType || "unknown",
+        domain: a.getFieldDomain(c.name) ?? void 0
       });
     }
     r.set(n.id, {
-      layerItem: i,
-      fieldRegistry: c
+      layerItem: o,
+      fieldRegistry: i
     });
   }
   return r;
-}, ce = async (t) => {
+}, Ie = async (t) => {
   try {
-    return (await O(t, {
+    return (await Q(t, {
       responseType: "json"
     })).data;
   } catch (e) {
     throw new Error(`Failed to fetch data from ${t}: ${String(e)}`);
   }
-}, de = async (t) => {
+}, ke = async (t) => {
   const e = t.map;
   if (!e?.portalItem)
     throw new Error("WebMap portal item is missing.");
-  const { resources: r } = await e.portalItem.fetchResources(), s = r.find((i) => i.resource.path === "embeddings-v01.json");
+  const { resources: r } = await e.portalItem.fetchResources(), s = r.find((o) => o.resource.path === "embeddings-v01.json");
   if (!s?.resource.url)
     throw new Error("Embeddings resource 'embeddings-v01.json' not found in the webmap portal item.");
-  const n = await ce(s.resource.url);
-  return ie(n);
+  const n = await Ie(s.resource.url);
+  return Ae(n);
 };
-class x {
+class M {
   constructor() {
-    this.orchestratorReady = !1, this.chatHistory = [], this.priorSteps = [], this.sharedState = {}, this.agentRegistry = new Z(), this.activeRunId = "", this.cancelledRunIds = /* @__PURE__ */ new Set(), this.streamEpoch = 0;
+    this.orchestratorReady = !1, this.chatHistory = [], this.priorSteps = [], this.sharedState = {}, this.sharedResources = [], this.agentRegistry = new A(), this.activeRunId = "", this.cancelledRunIds = /* @__PURE__ */ new Set(), this.parentRunIds = /* @__PURE__ */ new Map(), this.activeRuntimeSpans = /* @__PURE__ */ new Map(), this.runtimeEventsEnabled = !1, this.streamEpoch = 0;
   }
   /**
    * Creates and returns an AI-ready Orchestrator instance.
@@ -398,15 +572,16 @@ class x {
    * @returns Ready Orchestrator.
    */
   static async init(e) {
-    const r = new x();
+    const r = new M();
+    r.runtimeEventsEnabled = e.runtimeEventsEnabled ?? !1;
     try {
       if (e.view?.map) {
-        await P.whenOnce(() => e.view.ready);
-        const s = await de(e.view), n = oe(
+        await z.whenOnce(() => e.view.ready);
+        const s = await ke(e.view), n = Ce(
           s.layers,
           e.view.map
         );
-        r.layersAndFieldsRegistry = n, r.embeddingsWorker = await T(s);
+        r.layersAndFieldsRegistry = n, r.embeddingsWorker = await K(s);
       }
       return e.agents?.forEach((s) => {
         r.agentRegistry.register(s);
@@ -422,97 +597,109 @@ class x {
    *  - `interrupt`: HITL required, wait for `resumeInterrupt()`
    *  - `completed`: final result with chat history + layer styling
    *  - `cancelled`: user aborted the run
+   * @param userInput User request to process.
+   * @param options Agent selection and routing behavior and locale for this run.
    */
-  async *ask(e) {
+  async *ask(e, r = {}) {
     if (!this.orchestratorReady)
       throw new Error("Orchestrator is not ready yet.");
     if (!this.agentRegistry.list().length)
       throw new Error("Orchestrator has no registered agents.");
-    if (++this.streamEpoch, !e.trim())
+    const s = this.createRequestAgentRegistry(r);
+    if (!s.list().length)
+      throw new Error("Orchestrator has no agents selected for this request.");
+    if (++this.streamEpoch, !e.trim() && !r.inputParts?.length)
       return;
-    const r = crypto.randomUUID();
-    this.activeRunId = r, this.activeAbortController = new AbortController(), this.graph || (this.graph = Y().compile({ checkpointer: new j() }));
-    const s = this.embeddingsWorker ? ne({ worker: this.embeddingsWorker }) : void 0, n = this.embeddingsWorker ? ae({ worker: this.embeddingsWorker }) : void 0, a = /* @__PURE__ */ new Map(), c = {
+    if (!e.trim() && r.routing !== "direct")
+      throw new Error("Requests containing only structured input require direct agent routing.");
+    const n = C();
+    this.parentRunIds.clear(), this.activeRuntimeSpans.clear(), this.activeRunId = n, this.activeAbortController = new AbortController(), this.graph || (this.graph = pe().compile({ checkpointer: new j() }));
+    const a = this.embeddingsWorker ? xe({ worker: this.embeddingsWorker }) : void 0, o = this.embeddingsWorker ? be({ worker: this.embeddingsWorker }) : void 0, i = /* @__PURE__ */ new Map(), c = r.routing === "direct" ? { mode: "direct", agentId: r.agentId } : { mode: "auto" }, u = {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      thread_id: n,
+      locale: r.locale ?? "en",
+      hitlResponse: null,
+      services: {
+        layerSearch: a,
+        fieldSearch: o,
+        layersAndFieldsRegistry: this.layersAndFieldsRegistry,
+        agentRegistry: s,
+        embeddingCache: i
+      }
+    }, d = {
       version: "v2",
       streamMode: "custom",
-      configurable: {
-        // eslint-disable-next-line @typescript-eslint/naming-convention
-        thread_id: r,
-        abortSignal: this.activeAbortController.signal,
-        hitlResponse: null,
-        services: {
-          layerSearch: s,
-          fieldSearch: n,
-          layersAndFieldsRegistry: this.layersAndFieldsRegistry,
-          agentRegistry: this.agentRegistry,
-          embeddingCache: a
-        }
-      },
+      signal: this.activeAbortController.signal,
+      ...this.runtimeEventsEnabled && { callbacks: [this.createHierarchyCallback()] },
+      configurable: u,
       subgraphs: !0
-    }, d = this.graph?.streamEvents(
+    }, g = this.graph?.streamEvents(
       {
+        routing: c,
         agentExecutionContext: {
           userRequest: e,
+          inputParts: [...r.inputParts ?? []],
           messages: this.chatHistory,
           priorSteps: this.priorSteps,
-          sharedState: this.sharedState
+          sharedState: this.sharedState,
+          sharedResources: this.sharedResources
         }
       },
-      c
-    ), o = ++this.streamEpoch;
-    if (yield* this.pipeStream(d, o, r), this.isRunCancelled(r)) {
-      yield { runId: r, timestamp: Date.now(), type: "cancelled", reason: "user" };
+      d
+    ), l = ++this.streamEpoch;
+    if (yield* this.pipeStream(g, l, n), this.isRunCancelled(n)) {
+      yield* this.createCancellationEvents(n);
       return;
     }
     for (; ; ) {
-      if (this.isRunCancelled(r)) {
-        yield { runId: r, timestamp: Date.now(), type: "cancelled", reason: "user" };
+      if (this.isRunCancelled(n)) {
+        yield* this.createCancellationEvents(n);
         return;
       }
-      const m = (await this.graph.getState(c, { subgraphs: !0 })).tasks.find((h) => h.interrupts.length > 0)?.interrupts[0]?.value;
+      const m = (await this.graph.getState(d, { subgraphs: !0 })).tasks.find((y) => y.interrupts.length > 0)?.interrupts[0]?.value;
       if (!m)
         break;
-      this.currentInterrupt = m, this.interruptHandler = new ee(this.graph, c), yield { runId: r, timestamp: Date.now(), type: "interrupt", interrupt: m };
+      this.currentInterrupt = m, this.interruptHandler = new ve(this.graph, d), yield* this.closeActiveRuntimeSpans(n, "interrupted"), yield { runId: n, timestamp: Date.now(), type: "interrupt", interrupt: m };
       try {
-        const h = await this.interruptHandler.waitForUser(), S = ++this.streamEpoch;
-        yield* this.pipeStream(h, S, r);
-      } catch (h) {
-        if (this.isRunCancelled(r)) {
-          yield { runId: r, timestamp: Date.now(), type: "cancelled", reason: "user" };
+        const y = await this.interruptHandler.waitForUser(), _ = ++this.streamEpoch;
+        yield* this.pipeStream(y, _, n);
+      } catch (y) {
+        if (this.isRunCancelled(n)) {
+          yield* this.createCancellationEvents(n);
           return;
         }
-        if (h) {
+        if (y) {
           yield {
-            runId: r,
+            runId: n,
             timestamp: Date.now(),
             type: "error",
-            error: { message: h?.message }
+            error: { message: y?.message }
           };
           return;
         }
       }
     }
-    if (this.isRunCancelled(r)) {
-      yield { runId: r, timestamp: Date.now(), type: "cancelled", reason: "user" };
+    if (this.isRunCancelled(n)) {
+      yield* this.createCancellationEvents(n);
       return;
     }
-    const u = (await this.graph.getState(c, { subgraphs: !0 })).values;
-    if (this.isRunCancelled(r)) {
-      yield { runId: r, timestamp: Date.now(), type: "cancelled", reason: "user" };
+    const h = (await this.graph.getState(d, { subgraphs: !0 })).values;
+    if (this.isRunCancelled(n)) {
+      yield* this.createCancellationEvents(n);
       return;
     }
-    this.chatHistory = u.agentExecutionContext.messages.length ? u.agentExecutionContext.messages : this.chatHistory, this.priorSteps = u.agentExecutionContext.priorSteps?.slice(-5) ?? [], this.sharedState = u.agentExecutionContext.sharedState ?? {}, yield {
-      runId: r,
+    this.chatHistory = h.agentExecutionContext.messages.length ? h.agentExecutionContext.messages : this.chatHistory, this.priorSteps = h.agentExecutionContext.priorSteps?.slice(-5) ?? [], this.sharedState = h.agentExecutionContext.sharedState ?? {}, this.sharedResources = h.agentExecutionContext.sharedResources ?? [], yield {
+      runId: n,
       timestamp: Date.now(),
       type: "completed",
-      result: { content: u.finalOutputMessage }
+      result: { content: h.finalOutputMessage }
     };
   }
   /**
    * Start a new conversation by clearing chat history, prior steps, and shared state.
    */
   newConversation() {
-    this.chatHistory = [], this.priorSteps = [], this.sharedState = {};
+    this.chatHistory = [], this.priorSteps = [], this.sharedState = {}, this.sharedResources = [];
   }
   /**
    * Generic resume for any HITL interrupt.
@@ -540,29 +727,87 @@ class x {
     this.activeRunId && (this.cancelledRunIds.add(this.activeRunId), this.activeAbortController?.abort(), ++this.streamEpoch, this.interruptHandler?.cancel());
   }
   async *pipeStream(e, r, s) {
-    for await (const n of e) {
-      if (this.isRunCancelled(s) || r !== this.streamEpoch)
-        break;
-      n.event === "on_custom_event" && n.name === "trace_message" ? yield { runId: s, timestamp: Date.now(), type: "trace", data: n.data } : n.name === "graph_ux_suggestion" && (yield {
-        runId: s,
-        timestamp: Date.now(),
-        type: "ux-suggestion",
-        suggestion: n.data
-      });
+    try {
+      for await (const n of e) {
+        if (this.isRunCancelled(s) || r !== this.streamEpoch)
+          break;
+        if (this.runtimeEventsEnabled) {
+          const a = we({
+            event: n,
+            runId: s,
+            parentSpanId: this.parentRunIds.get(n.run_id),
+            timestamp: Date.now()
+          });
+          a && (a.phase === "started" ? this.activeRuntimeSpans.set(a.span.id, a) : this.activeRuntimeSpans.delete(a.span.id), yield a);
+        }
+        n.event === "on_custom_event" && n.name === "trace_message" ? yield { runId: s, timestamp: Date.now(), type: "trace", data: n.data } : n.name === "graph_ux_suggestion" && (yield {
+          runId: s,
+          timestamp: Date.now(),
+          type: "ux-suggestion",
+          suggestion: n.data
+        });
+      }
+    } catch (n) {
+      if (!this.isRunCancelled(s))
+        throw n;
+    }
+  }
+  *createCancellationEvents(e) {
+    yield* this.closeActiveRuntimeSpans(e, "cancelled"), yield { runId: e, timestamp: Date.now(), type: "cancelled", reason: "user" };
+  }
+  *closeActiveRuntimeSpans(e, r) {
+    const s = Date.now(), n = [...this.activeRuntimeSpans.values()].reverse();
+    this.activeRuntimeSpans.clear();
+    for (const a of n) {
+      const { input: o, ...i } = a.span;
+      yield {
+        type: "runtime",
+        phase: r,
+        runId: e,
+        timestamp: s,
+        ...a.agentId && { agentId: a.agentId },
+        span: i
+      };
     }
   }
+  // v2 stream events omit parent run IDs, so capture them through callbacks to preserve the normalized span hierarchy.
+  createHierarchyCallback() {
+    const e = (r, s) => {
+      s && this.parentRunIds.set(r, s);
+    };
+    return V.fromMethods({
+      handleLLMStart: (r, s, n, a) => e(n, a),
+      handleChatModelStart: (r, s, n, a) => e(n, a),
+      handleChainStart: (r, s, n, a) => e(n, a),
+      handleToolStart: (r, s, n, a) => e(n, a),
+      handleRetrieverStart: (r, s, n, a) => e(n, a)
+    });
+  }
   isRunCancelled(e) {
     return this.cancelledRunIds.has(e);
   }
+  /**
+   * Creates a request-scoped registry containing all agents by default,
+   * or only the explicitly selected agents when filtering is requested.
+   */
+  createRequestAgentRegistry(e) {
+    const r = e.routing === "direct" ? [e.agentId] : e.agentIds, s = r ? r.map((a) => {
+      const o = this.agentRegistry.get(a);
+      if (!o)
+        throw new Error(`Agent is not registered: ${a}`);
+      return o;
+    }) : this.agentRegistry.list(), n = new A();
+    return s.forEach((a) => n.register(a)), n;
+  }
   /**
    * Disposes this instance by terminating the embeddings worker
    * and cleaning up all related resources.
    */
   dispose() {
-    this.embeddingsWorker && (this.embeddingsWorker.terminate(), this.embeddingsWorker = void 0), this.orchestratorReady = !1;
+    this.sharedResources = [], this.embeddingsWorker && (this.embeddingsWorker.terminate(), this.embeddingsWorker = void 0), this.orchestratorReady = !1;
   }
 }
 export {
-  x as O,
-  te as g
+  M as O,
+  Ee as g
 };