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

package/dist/chunks/requireAgentServices.js

@@ -0,0 +1,11 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const t = (r, s) => (o, i) => {
+  const c = i?.configurable?.services;
+  for (const e of r)
+    if (!c?.[e])
+      throw new Error(`${s} requires services.${e} to be available.`);
+  return o;
+};
+export {
+  t as r
+};

package/dist/chunks/resolveGeometryFilter.js

@@ -0,0 +1,149 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import u from "@arcgis/core/geometry/Point.js";
+import p from "@arcgis/core/geometry/Polygon.js";
+import y from "@arcgis/core/geometry/Polyline.js";
+import * as f from "@arcgis/core/geometry/operators/unionOperator.js";
+import r from "zod";
+import { distanceUnitsSchema as m } from "../agents/tools/shared/types.js";
+const d = 750;
+function h(e) {
+  return "point" in e && e.point !== void 0;
+}
+function b(e) {
+  return "layerId" in e && e.layerId !== void 0;
+}
+function R(e) {
+  return "polygon" in e && e.polygon !== void 0;
+}
+function w(e) {
+  return "polyline" in e && e.polyline !== void 0;
+}
+const P = async (e, a) => {
+  if (h(e)) {
+    const { point: t } = e;
+    return { geometry: new u({
+      x: t.x,
+      y: t.y,
+      spatialReference: t.spatialReference ? { wkid: t.spatialReference.wkid } : a.spatialReference
+    }) };
+  }
+  if (R(e))
+    return {
+      geometry: new p({
+        rings: e.polygon.rings,
+        spatialReference: e.polygon.spatialReference
+      })
+    };
+  if (w(e))
+    return {
+      geometry: new y({
+        paths: e.polyline.paths,
+        spatialReference: e.polyline.spatialReference
+      })
+    };
+  if (b(e)) {
+    const t = a.map?.allLayers.find(
+      (n) => n.id === e.layerId
+    );
+    if (!t)
+      return { error: `Could not find geometry layer with ID: ${e.layerId}` };
+    const o = t.title ?? t.id, i = e.where?.trim() || "1=1";
+    try {
+      const n = await t.queryFeatures({
+        where: i,
+        returnGeometry: !0,
+        outSpatialReference: a.spatialReference,
+        num: d + 1
+      });
+      if (!n.features.length)
+        return {
+          error: `No features found in geometry layer "${o}" with the specified where clause: ${i}`
+        };
+      if (n.features.length > d)
+        return {
+          error: `Geometry filter for layer "${o}" matched too many features (${n.features.length}+). Please narrow the geometry layer filter.`
+        };
+      const s = n.features.map((c) => c.geometry).filter((c) => !!c);
+      if (!s.length)
+        return { error: "No valid geometries found for the matched geometry layer features." };
+      const l = s.length === 1 ? s[0] : f.executeMany(s);
+      return l ? (l.spatialReference || (l.spatialReference = a.spatialReference), { geometry: l }) : { error: "Failed to combine geometries from geometry layer." };
+    } catch (n) {
+      return { error: `Failed to query geometry: ${String(n)}` };
+    }
+  }
+  return { error: "Invalid geometry configuration provided" };
+}, I = r.object({ id: r.string() }), g = r.discriminatedUnion("kind", [
+  r.object({
+    id: r.string(),
+    kind: r.literal("point"),
+    payload: r.object({
+      x: r.number(),
+      y: r.number(),
+      spatialReference: r.object({ wkid: r.number() }).optional()
+    })
+  }),
+  r.object({
+    id: r.string(),
+    kind: r.literal("polyline"),
+    payload: r.object({
+      paths: r.array(r.array(r.array(r.number()))),
+      spatialReference: r.object({ wkid: r.number() }).optional()
+    })
+  }),
+  r.object({
+    id: r.string(),
+    kind: r.literal("polygon"),
+    payload: r.object({
+      rings: r.array(r.array(r.array(r.number()))),
+      spatialReference: r.object({ wkid: r.number() }).optional()
+    })
+  })
+]), $ = r.object({
+  sharedResourceId: r.string().describe("ID of a point, polyline, or polygon returned by listSharedResources."),
+  distance: r.number().optional().describe("Optional buffer distance around the geometry."),
+  units: m.optional().describe("The units for the distance buffer.")
+}), x = (e, a) => {
+  if (!e || !("sharedResourceId" in e))
+    return e;
+  if (!a)
+    throw new Error("Shared resources are unavailable in the tool runtime state.");
+  const t = a.find((i) => {
+    const n = I.safeParse(i);
+    return n.success && n.data.id === e.sharedResourceId;
+  });
+  if (!t)
+    throw new Error(`Shared resource not found: ${e.sharedResourceId}`);
+  const o = g.safeParse(t);
+  if (!o.success)
+    throw new Error(
+      `Shared resource ${e.sharedResourceId} does not contain valid point, polyline, or polygon geometry.`
+    );
+  switch (o.data.kind) {
+    case "point":
+      return {
+        point: o.data.payload,
+        distance: e.distance,
+        units: e.units
+      };
+    case "polyline":
+      return {
+        polyline: o.data.payload,
+        distance: e.distance,
+        units: e.units
+      };
+    case "polygon":
+      return {
+        polygon: o.data.payload,
+        distance: e.distance,
+        units: e.units
+      };
+  }
+};
+export {
+  h as a,
+  P as g,
+  b as i,
+  x as r,
+  $ as s
+};

package/dist/chunks/state.js

@@ -1,35 +1,33 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
 import { Annotation as s } from "@langchain/langgraph/web";
-const c = /* @__PURE__ */ new Set(["agentExecutionContext", "outputMessage", "summary", "status"]);
-function u() {
-  return {
-    assignedTask: "",
-    messages: [],
-    priorSteps: [],
-    sharedState: {},
-    userRequest: ""
-  };
-}
-function i(r) {
-  const n = [...new Set([...r].filter((t) => c.has(t)))];
+import { c as a } from "./baseAgentState.js";
+const i = /* @__PURE__ */ new Set([
+  "agentExecutionContext",
+  "outputMessage",
+  "summary",
+  "status",
+  "sharedResourceAdditions"
+]);
+function u(r) {
+  const n = [...new Set([...r].filter((t) => i.has(t)))];
   if (n.length !== 0)
-    throw new Error(`ADK custom state cannot define reserved runtime fields: ${n.join(", ")}.`);
+    throw new Error(`custom state cannot define reserved runtime fields: ${n.join(", ")}.`);
 }
-function f(r) {
+function d(r) {
   const n = Object.entries(r);
   return Object.fromEntries(
     n.map(([t, e]) => [
       t,
       s({
-        reducer: (o, a) => a,
+        reducer: (o, c) => c,
         default: () => e
       })
     ])
   );
 }
-function m(r = {}) {
-  i(Object.keys(r));
-  const n = f(r);
+function f(r = {}) {
+  u(Object.keys(r));
+  const n = d(r);
   return s.Root({
     ...n,
     agentExecutionContext: s({
@@ -37,7 +35,7 @@ function m(r = {}) {
         ...t,
         ...e
       }),
-      default: u
+      default: a
     }),
     outputMessage: s({
       // Preserve the last meaningful user-facing message produced by the graph.
@@ -54,18 +52,25 @@ function m(r = {}) {
       reducer: (t, e) => e ?? t,
       default: () => {
       }
+    }),
+    sharedResourceAdditions: s({
+      reducer: (t, e) => e,
+      default: () => {
+      }
     })
   });
 }
-function l(r) {
-  const n = /* @__PURE__ */ new Set();
-  for (const e of r)
-    for (const o of Object.keys(e.shape ?? {}))
-      n.add(o);
-  const t = Object.fromEntries([...n].map((e) => [e, void 0]));
-  return m(t);
+function g(r, n = []) {
+  const t = new Set(n);
+  for (const o of r)
+    for (const c of Object.keys(o.shape ?? {}))
+      t.add(c);
+  const e = Object.fromEntries([...t].map((o) => [o, void 0]));
+  return f(e);
 }
 export {
-  m as a,
-  l as c
+  f as a,
+  u as b,
+  g as c,
+  d
 };

package/dist/chunks/utils2.js

@@ -1,11 +1,11 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
 import { getClosestElement as i } from "@arcgis/toolkit/dom";
-import { g as r, a as o } from "./utils3.js";
+import { g as s, a as o } from "./utils3.js";
 function c(e, t) {
-  const s = r(e.el, e.referenceElement);
-  if (s)
-    return s;
-  const n = i(e.el, "arcgis-assistant"), a = r(e.el, n?.referenceElement);
+  const r = s(e.el, e.referenceElement);
+  if (r)
+    return r;
+  const n = i(e.el, "arcgis-assistant"), a = s(e.el, n?.referenceElement);
   if (a)
     return a;
   throw new Error(`${t}: Reference element not found`);
@@ -23,16 +23,16 @@ function g(e) {
   const t = i(e.el, "arcgis-assistant");
   if (t === void 0)
     throw new Error("arcgis-assistant-agent must be used within an arcgis-assistant element");
-  t.register({
+  return t.register({
     agent: e.agent,
     getContext: async () => await e.getContext?.() ?? e.context ?? {}
-  });
+  }), t;
 }
 function l(e) {
   const t = o(e.el, e.referenceElement);
   if (t)
     return t;
-  const s = i(e.el, "arcgis-assistant"), n = r(e.el, s?.referenceElement);
+  const r = i(e.el, "arcgis-assistant"), n = s(e.el, r?.referenceElement);
   return n || null;
 }
 function v(e) {
@@ -40,8 +40,8 @@ function v(e) {
   return t ? t.view : null;
 }
 export {
-  g as a,
-  v as b,
-  w as i,
+  v as a,
+  w as b,
+  g as i,
   m as r
 };

package/dist/components/arcgis-assistant/customElement.d.ts

@@ -1,7 +1,8 @@
 /// <reference path="../../index.d.ts" />
 import type Collection from "@arcgis/core/core/Collection.js";
+import type { RuntimeSpanEvent } from "../../orchestrator/orchestrator/orchestratorEvents.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
-import type { AssistantMessage, AssistantPromptSelectDetail, AssistantSlottableRequestDetail, ChatMessage, Interrupt } from "./types.js";
+import type { AssistantCommandProvider, AssistantEntityProvider, AssistantMessage, AssistantSubmission, AssistantPromptSelectDetail, AssistantSlottableRequestDetail, ChatMessage, Interrupt, SubmitMessageOptions } from "./types.js";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
 
@@ -41,6 +42,11 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * for the included ArcGIS agents to function properly, as they rely on the map context to perform their tasks. This is not
  * a requirement for [custom agents](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/).
  *
+ * ## Application Identification
+ * For applications that use the arcgis-assistant component, setting the [`applicationName`](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-applicationName) property on the ArcGIS config object [`esriConfig`](https://developers.arcgis.com/javascript/latest/references/core/config/) is recommended.
+ * When provided, this value can help associate assistant activity and feedback with a specific application, where supported.
+ * This can make it easier to understand usage patterns and troubleshoot feedback.
+ *
  * ## Context
  *
  * Use the [referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#referenceElement) property to provide a web map as context to the assistant and its agents.
@@ -82,15 +88,91 @@ export abstract class ArcgisAssistant extends LitElement {
   /** @internal */
   protected _messages: {
       assistantLabel: string;
+      multipleCommands: string;
+      partsOnlyRequiresAgent: string;
       stopButtonLabel: string;
       askButtonLabel: string;
+      stoppedByUserLabel: string;
+      noAgentsFoundMessage: string;
+      orchestratorInitializationErrorMessage: string;
+      signInErrorMessage: string;
+      signInRequiredMessage: string;
+      signInLabel: string;
+      signInToArcGISOnlineLabel: string;
+      noPortalInformationMessage: string;
+      readMoreLabel: string;
+      learnAboutWebMapEmbeddingsLabel: string;
+      waitingForUserInputMessage: string;
+      aiAssistantsNotEnabledMessage: string;
+      serviceUrlNotAvailableMessage: string;
+      userPrivilegesNotSufficientMessage: string;
   } & T9nMeta<{
       assistantLabel: string;
+      multipleCommands: string;
+      partsOnlyRequiresAgent: string;
       stopButtonLabel: string;
       askButtonLabel: string;
+      stoppedByUserLabel: string;
+      noAgentsFoundMessage: string;
+      orchestratorInitializationErrorMessage: string;
+      signInErrorMessage: string;
+      signInRequiredMessage: string;
+      signInLabel: string;
+      signInToArcGISOnlineLabel: string;
+      noPortalInformationMessage: string;
+      readMoreLabel: string;
+      learnAboutWebMapEmbeddingsLabel: string;
+      waitingForUserInputMessage: string;
+      aiAssistantsNotEnabledMessage: string;
+      serviceUrlNotAvailableMessage: string;
+      userPrivilegesNotSufficientMessage: string;
   }>;
   /**
-   * When `true`, disables the assistant avatar in the chat interface.
+   * The IDs of the agents available for automatic intent routing.
+   * A single ID still uses automatic routing and does not enable direct routing.
+   * This property cannot be used together with [alwaysUseAgentId](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#alwaysUseAgentId).
+   * If this property is not set, all registered agents are available for routing.
+   *
+   * > **Note:** Agent ids for custom agents are automatically created from the agent's
+   * > [BaseAgent.name](https://developers.arcgis.com/javascript/latest/references/ai-components/agent-utils/BaseAgent/#name) property.
+   * > For example, an agent with the name "My Custom Agent" will have the id "my-custom-agent".
+   *
+   * Agent ids for SDK agents are as follows:
+   *
+   * - Navigation Agent: `navigation`
+   * - Data Exploration Agent: `data-exploration`
+   * - Help Agent: `help`
+   * - Knowledge Agent: `arcgisKnowledge`
+   *
+   * @since 5.2
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * // only route user questions to either the navigation or help agents
+   * // even if other agents are registered to the assistant
+   * assistant.allowedAgentIds = ["navigation", "help"];
+   * ```
+   */
+  accessor allowedAgentIds: readonly string[] | undefined;
+  /**
+   * The ID of the agent that should process every user message without intent routing.
+   * When set, the assistant will route all user messages to the specified agent.
+   *
+   * This is useful for applications that want to bypass the orchestrator's default intent routing
+   * in favor of a single custom agent that directly handles its own intent orchestration to one or more sub-agents. This property
+   * should not be used to route requests to an SDK agent, as the SDK agents do not have their own intent routing outside of the orchestrator.
+   *
+   * This property cannot be used together with [allowedAgentIds](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#allowedAgentIds).
+   *
+   * @since 5.2
+   * @example
+   * ```html
+   * <arcgis-assistant always-use-agent-id="my-custom-orchestration-agent"></arcgis-assistant>
+   * ```
+   */
+  accessor alwaysUseAgentId: string | undefined;
+  /**
+   * When `true`, displays the assistant avatar in the chat interface.
    *
    * @default false
    * @since 5.1
@@ -111,6 +193,14 @@ export abstract class ArcgisAssistant extends LitElement {
    * @since 5.1
    */
   get awaitingResponseStep(): string;
+  /**
+   * Provider used by the built-in chat entry to suggest slash commands.
+   * Selected commands are included as structured input and removed from the prompt sent to the agent.
+   * A command with an `agentId` routes that request directly to the specified agent.
+   *
+   * @internal
+   */
+  accessor commandProvider: AssistantCommandProvider | undefined;
   /**
    * When `true`, enables the copy action that, when clicked, copies the content of the message to the clipboard. This can be helpful for users to easily copy and share
    * information provided by the assistant, such as a summary of findings, a set of instructions, or any other relevant details. Enabling this property can enhance the user experience by providing a convenient way for users to capture and utilize the information generated by the assistant.
@@ -144,6 +234,13 @@ export abstract class ArcgisAssistant extends LitElement {
    * ```
    */
   accessor description: string | undefined;
+  /**
+   * Providers used by the built-in chat entry to suggest structured entities.
+   * Selected entities remain in the prompt and do not affect agent routing.
+   *
+   * @internal
+   */
+  accessor entityProviders: readonly AssistantEntityProvider[] | undefined;
   /**
    * The instructions to display when the assistant is first loaded. This is intended to be a welcome or entry message that
    * provides guidance to users on how to interact with the assistant. Once the user submits their first message,
@@ -277,6 +374,21 @@ export abstract class ArcgisAssistant extends LitElement {
    * ```
    */
   accessor referenceElement: ArcgisMap | string | null;
+  /**
+   * When `true`, emits normalized runtime span events while processing requests.
+   *
+   * @default false
+   * @internal
+   * @since 5.2
+   */
+  accessor runtimeEventsEnabled: boolean;
+  /**
+   * When `true`, assistant text responses render after completion instead of streaming progressively.
+   *
+   * @default false
+   * @since 5.1
+   */
+  accessor streamingDisabled: boolean;
   /**
    * Prompts to suggest to the end user on load. These are intended to help users understand which questions they can ask.
    * This property should be set to establish boundaries for the end user. As all agents have limitations and LLMs can
@@ -298,6 +410,13 @@ export abstract class ArcgisAssistant extends LitElement {
    * ```
    */
   accessor suggestedPrompts: string[];
+  /**
+   * When `true`, displays the user avatar in the chat interface.
+   *
+   * @default false
+   * @since 5.2
+   */
+  accessor userAvatarEnabled: boolean;
   /**
    * Cancels the active interrupt, if one is pending.
    *
@@ -331,6 +450,7 @@ export abstract class ArcgisAssistant extends LitElement {
    * complex interactions and integrations with other components or services.
    *
    * @param message - The message to submit to the assistant. This should be a string containing the user's input or question they want to ask the assistant.
+   * @param options
    * @since 5.0
    * @example
    * ```js
@@ -338,7 +458,7 @@ export abstract class ArcgisAssistant extends LitElement {
    * assistant.submitMessage("What is the population of New York City?");
    * ```
    */
-  submitMessage(message: string): Promise<void>;
+  submitMessage(message: string, options?: SubmitMessageOptions): Promise<void>;
   /**
    * Emitted when the user cancels a message. This is typically invoked when a user submits a question while a previous question is still being processed.
    * This allows app developers to capture messages cancelled by the user and respond to them in custom ways, such as by providing additional information,
@@ -468,6 +588,12 @@ export abstract class ArcgisAssistant extends LitElement {
    * @since 5.1
    */
   readonly arcgisResponse: import("@arcgis/lumina").TargetedEvent<this, AssistantMessage>;
+  /**
+   * Emitted for each normalized runtime span lifecycle event produced while processing a request.
+   *
+   * @internal
+   */
+  readonly arcgisRuntime: import("@arcgis/lumina").TargetedEvent<this, RuntimeSpanEvent>;
   /**
    * Emitted when the assistant requests custom slotted content for an assistant message.
    *
@@ -512,7 +638,7 @@ export abstract class ArcgisAssistant extends LitElement {
    * });
    * ```
    */
-  readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string>;
+  readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, AssistantSubmission | string>;
   readonly "@eventTypes": {
     arcgisCancel: ArcgisAssistant["arcgisCancel"]["detail"];
     arcgisError: ArcgisAssistant["arcgisError"]["detail"];
@@ -523,6 +649,7 @@ export abstract class ArcgisAssistant extends LitElement {
     arcgisPromptSelect: ArcgisAssistant["arcgisPromptSelect"]["detail"];
     arcgisReady: ArcgisAssistant["arcgisReady"]["detail"];
     arcgisResponse: ArcgisAssistant["arcgisResponse"]["detail"];
+    arcgisRuntime: ArcgisAssistant["arcgisRuntime"]["detail"];
     arcgisSlottableRequest: ArcgisAssistant["arcgisSlottableRequest"]["detail"];
     arcgisSubmit: ArcgisAssistant["arcgisSubmit"]["detail"];
   };