@arcgis/ai-components 5.2.0-next.98 → 6.0.0-next.0

package/dist/orchestrator/orchestrator/orchestratorEvents.d.ts

@@ -1,78 +1,172 @@
-export type RuntimeSpanEvent = RuntimeSpanCancelledEvent | RuntimeSpanCompletedEvent | RuntimeSpanFailedEvent | RuntimeSpanInterruptedEvent | RuntimeSpanStartedEvent;
+import type { TraceEventData, UXSuggestion } from "../signals.js";
+import type { UiInterrupt } from "../types.js";
+
+/**
+ * Events emitted by the Orchestrator during a chat run.
+ *
+ * - `"trace"`: intermediate model output to display.
+ * - `"interrupt"`: human-in-the-loop input required; UI should call `resumeInterrupt()`.
+ * - `"completed"`: run finished successfully; includes final chat history and optional smart-mapping result.
+ * - `"cancelled"`: run aborted by the user.
+ * - `"runtime"`: runtime span lifecycle update; inspect `phase` for the lifecycle stage.
+ * - `"ux-suggestion"`: optional suggestion for the UX to display (e.g., show legend).
+ * - `"error"`: an error occurred during orchestration.
+ * Consumers should handle all cases when iterating the async generator from `ask()`.
+ *
+ * @internal
+ */
+export type OrchestratorEvent = RuntimeSpanEvent | (OrchestratorEventBase & {
+    type: "cancelled";
+    reason?: CancelReason;
+}) | (OrchestratorEventBase & {
+    type: "completed";
+    result: CompletedEventResult;
+}) | (OrchestratorEventBase & {
+    type: "error";
+    error: OrchestratorError;
+}) | (OrchestratorEventBase & {
+    type: "interrupt";
+    interrupt: UiInterrupt;
+}) | (OrchestratorEventBase & {
+    type: "trace";
+    data: TraceEventData;
+}) | (OrchestratorEventBase & {
+    type: "ux-suggestion";
+    suggestion: UXSuggestion;
+});
+
+/**
+ * Runtime category for one traced execution span.
+ *
+ * @internal
+ */
+export type RuntimeSpanType = "chain" | "model" | "node" | "retriever" | "tool" | "workflow";
+
+/**
+ * Token usage reported by a model runtime span.
+ *
+ * @internal
+ */
+export type RuntimeTokenUsage = {
+  input: number;
+  output: number;
+  total: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  reasoning?: number;
+};
+
+/**
+ * Optional runtime context associated with a traced span.
+ *
+ * @internal
+ */
+export type RuntimeSpanMetadata = {
+  model?: string;
+  tokenUsage?: RuntimeTokenUsage;
+  internal?: boolean;
+};
+
+/**
+ * Error emitted by a failed runtime span.
+ *
+ * @internal
+ */
+export type RuntimeSpanError = {
+  name?: string;
+  message: string;
+};
 
-/** Lifecycle event for one runtime execution span. */
+/**
+ * Properties shared by runtime span lifecycle events.
+ *
+ * @internal
+ */
+export type RuntimeSpanBase = {
+  id: string;
+  parentId?: string;
+  label: string;
+  type: RuntimeSpanType;
+  metadata?: RuntimeSpanMetadata;
+};
+
+/**
+ * Lifecycle event for one runtime execution span.
+ *
+ * @internal
+ */
 export type RuntimeSpanCancelledEvent = RuntimeSpanEventBase
   & {
   phase: "cancelled";
   span: RuntimeSpanBase;
 };
 
+/** @internal */
 export type RuntimeSpanCompletedEvent = RuntimeSpanEventBase
   & {
   phase: "completed";
   span: RuntimeSpanBase & { output?: unknown; };
 };
 
+/** @internal */
 export type RuntimeSpanFailedEvent = RuntimeSpanEventBase
   & {
   phase: "failed";
   span: RuntimeSpanBase & { error: RuntimeSpanError; };
 };
 
+/** @internal */
 export type RuntimeSpanInterruptedEvent = RuntimeSpanEventBase
   & {
   phase: "interrupted";
   span: RuntimeSpanBase;
 };
 
+/** @internal */
 export type RuntimeSpanStartedEvent = RuntimeSpanEventBase
   & {
   phase: "started";
   span: RuntimeSpanBase & { input?: unknown; };
 };
 
+/** @internal */
+export type RuntimeSpanEvent = RuntimeSpanCancelledEvent | RuntimeSpanCompletedEvent | RuntimeSpanFailedEvent | RuntimeSpanInterruptedEvent | RuntimeSpanStartedEvent;
+
+/** @internal */
 export type RuntimeSpanEventBase = OrchestratorEventBase
   & {
   type: "runtime";
   agentId?: string;
 };
 
-/** Base properties for all orchestrator events */
+/**
+ * Base properties for all orchestrator events.
+ *
+ * @internal
+ */
 export type OrchestratorEventBase = {
   runId: string;
   timestamp: number;
 };
 
-/** Error emitted by a failed runtime span. */
-export type RuntimeSpanError = {
-  name?: string;
-  message: string;
-};
+/** @internal */
+export interface CompletedEventResult {
+  content: string;
+}
 
-/** Properties shared by runtime span lifecycle events. */
-export type RuntimeSpanBase = {
-  id: string;
-  parentId?: string;
-  label: string;
-  type: RuntimeSpanType;
-  metadata?: RuntimeSpanMetadata;
-};
+/**
+ * Cancel reasons for orchestrator events:
+ * - "user": the user explicitly cancelled the run.
+ *
+ * @internal
+ */
+export type CancelReason = "user";
 
-/** Runtime category for one traced execution span. */
-export type RuntimeSpanType = "chain" | "model" | "node" | "retriever" | "tool" | "workflow";
-
-/** Optional runtime context associated with a traced span. */
-export type RuntimeSpanMetadata = {
-  model?: string;
-  tokenUsage?: RuntimeTokenUsage;
-  internal?: boolean;
-};
-
-/** Token usage reported by a model runtime span. */
-export type RuntimeTokenUsage = {
-  input: number;
-  output: number;
-  total: number;
-  cacheRead?: number;
-  reasoning?: number;
+/**
+ * Error information for orchestrator events.
+ *
+ * @internal
+ */
+export type OrchestratorError = {
+  message: string;
 };

package/dist/orchestrator/orchestrator/orchestratorEvents.js

@@ -0,0 +1,2 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+

package/dist/orchestrator/providers/arcgis/aiFactory.d.ts

@@ -0,0 +1,17 @@
+import type { OpenAIEmbeddings } from "@langchain/openai";
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { EmbeddingModelTier } from "../../models/modelConfig.js";
+
+/** @internal */
+export type CreateEmbeddingModelOptions = {
+  tier?: EmbeddingModelTier;
+  config?: RunnableConfig;
+};
+
+/**
+ * Creates a configured OpenAIEmbeddings instance pointing to the ArcGIS Utility Service.
+ *
+ * @param opts
+ * @internal
+ */
+export function createEmbeddingModel(opts?: CreateEmbeddingModelOptions): Promise<OpenAIEmbeddings>;

package/dist/orchestrator/registry/agentRegistry.d.ts

@@ -0,0 +1,10 @@
+import type { AgentWithContext } from "../types.js";
+
+/** @internal */
+export class AgentRegistry {
+  /** @param id */
+  get(id: string): AgentWithContext | undefined;
+  list(): AgentWithContext[];
+  /** @param entry */
+  register<TContext extends Record<string, unknown>>(entry: AgentWithContext<TContext>): void;
+}

package/dist/orchestrator/services/fieldSearch.d.ts

@@ -0,0 +1,17 @@
+import type { QueryEmbeddingCache, VectorSearchFieldResults } from "../types.js";
+
+/**
+ * Service for semantic field matching within one or more layers.
+ * Hides the embeddings worker from callers.
+ *
+ * @internal
+ */
+export interface FieldSearchService {
+  searchFields: (input: {
+      text: string;
+      layerIds: string[];
+      minScore: number;
+      topResults: number;
+      embeddingCache: QueryEmbeddingCache;
+  }) => Promise<VectorSearchFieldResults>;
+}

package/dist/orchestrator/services/layerSearch.d.ts

@@ -0,0 +1,18 @@
+import type { QueryEmbeddingCache } from "../types.js";
+
+/**
+ * Service for semantic layer matching.
+ * Hides the embeddings worker from callers.
+ *
+ * @internal
+ */
+export interface LayerSearchService {
+  searchLayers: (input: {
+      text: string;
+      minScore: number;
+      embeddingCache?: QueryEmbeddingCache;
+  }) => Promise<{
+      id: string;
+      score: number;
+  }[]>;
+}

package/dist/orchestrator/signals.d.ts

@@ -0,0 +1,66 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+
+/**
+ * Dispatches a graph trace message to the log in the chat interface. This allows agents to emit trace
+ * messages during graph execution, providing users with insights into the intermediate steps, decisions,
+ * and actions taken by the agent. These trace messages can help users understand the agent's thought
+ * process and behavior as it executes its graph. It can also be useful for debugging and
+ * transparency purposes.
+ *
+ * @param data - Trace event data to display in the chat log, including the message, agent, and tool if applicable.
+ * @param config - Optional runnable configuration
+ *   [as defined in LangChain](https://reference.langchain.com/javascript/interfaces/_langchain_core.runnables.RunnableConfig.html),
+ *   which can include additional context or variables to associate with the trace message.
+ * @returns A promise that resolves once the event has been dispatched.
+ * @see [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled)
+ * @see [RunnableConfig documentation](https://reference.langchain.com/javascript/interfaces/_langchain_core.runnables.RunnableConfig.html)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ */
+export function sendTraceMessage(data: TraceEventData, config?: RunnableConfig): Promise<void>;
+
+/**
+ * Sends an optional UX suggestion from an agent run to the host application.
+ * Use this for non-blocking hints (for example, recommended next actions or UI prompts) that the app may choose to display.
+ *
+ * @param suggestion - The UX suggestion payload.
+ * @param config - Runnable LangChain config to pass through to the dispatcher.
+ * @returns A promise that resolves once the suggestion has been dispatched.
+ */
+export function sendUXSuggestion(suggestion: UXSuggestion, config?: RunnableConfig): Promise<void>;
+
+/**
+ * Data structure for trace messages emitted by agents during graph execution.
+ * This is used to send trace messages to the log in the chat interface, allowing users to see the
+ * intermediate steps and thought processes of the agent as it executes its graph.
+ * This log will only be visible if the [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled) property is set to `true`.
+ *
+ * @see [ArcGISAssistant](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#logEnabled)
+ */
+export interface TraceEventData {
+  /**
+   * The text content of the trace message. This should provide information about the agent's current state,
+   * the actions it is taking, the decisions it is making, or any other relevant details that can help users
+   * understand the agent's behavior and thought process.
+   */
+  text: string;
+  /**
+   * The name of the agent associated with this trace message. This can help provide
+   * additional context to users about which agent is emitting the trace message, especially in scenarios
+   * where multiple agents are involved in a conversation or workflow.
+   */
+  agentName?: string;
+  /**
+   * The name of the tool associated with the trace message. This can help provide
+   * additional context to users about which tool (e.g. function defined in the client) is being invoked or
+   * referenced in the trace message, especially when the agent is using multiple tools in its workflow.
+   */
+  toolName?: string;
+}
+
+/** The suggestions emitted by the agent to the user interface. */
+export type UXSuggestion = {
+  /** The type of suggestion being made. */
+  type: string;
+  /** Optional additional data associated with the suggestion. */
+  data?: Record<string, unknown>;
+};

package/dist/orchestrator/signals.js

@@ -0,0 +1,12 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const e = async (t, s) => {
+  const { dispatchCustomEvent: a } = await import("@langchain/core/callbacks/dispatch/web");
+  await a("trace_message", t, s);
+}, n = async (t, s) => {
+  const { dispatchCustomEvent: a } = await import("@langchain/core/callbacks/dispatch/web");
+  await a("graph_ux_suggestion", t, s);
+};
+export {
+  e as sendTraceMessage,
+  n as sendUXSuggestion
+};

package/dist/orchestrator/state/runtime.d.ts

@@ -0,0 +1,31 @@
+/** Creates custom agent graph state. */
+import type { BaseChannel } from "@langchain/langgraph/web";
+import type { AgentExecutionContext, AgentStatus } from "../types.js";
+import type { SharedState, SharedStatePatch, SharedResourceInput } from "./types.js";
+
+/**
+ * Creates the standard runtime state channel definitions for a custom agent graph.
+ * Returns LangGraph channels, not initialized state values.
+ * Includes common fields used by the assistant flow and channels for shared state and shared resource updates, so you only add your agent-specific state.
+ *
+ * @since 5.1
+ */
+export function createAgentRuntimeState<TState extends Record<string, unknown> = Record<string, unknown>>(): AgentBaseState<TState>;
+
+/**
+ * Use `createAgentRuntimeState` instead.
+ *
+ * @deprecated Use `createAgentRuntimeState` instead.
+ * @internal
+ */
+export function createAgentRuntimeStateWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>>(): AgentBaseState<TState>;
+
+/** Base state channel definitions */
+export type AgentBaseState<TState extends Record<string, unknown> = Record<string, unknown>> = {
+  agentExecutionContext: BaseChannel<AgentExecutionContext<SharedState<TState>>, unknown, unknown>;
+  outputMessage: BaseChannel<string, unknown, unknown>;
+  summary: BaseChannel<string, unknown, unknown>;
+  status: BaseChannel<AgentStatus | undefined, unknown, unknown>;
+  sharedStatePatch: BaseChannel<SharedStatePatch<TState> | undefined, unknown, unknown>;
+  sharedResourceAdditions: BaseChannel<readonly SharedResourceInput[] | undefined, unknown, unknown>;
+};

package/dist/orchestrator/state/runtime.js

@@ -0,0 +1,8 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import "@langchain/langgraph/web";
+import { a as n, b as r, c } from "../../chunks/runtime2.js";
+export {
+  n as createAgentRuntimeState,
+  r as createAgentRuntimeStateWithSharedState,
+  c as createDefaultAgentExecutionContext
+};

package/dist/orchestrator/state/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared state that can be read and updated during agent execution.
+ *
+ * @since 5.1
+ */
+export type SharedState<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStateEntry<T[K]>;
+};
+
+/**
+ * Partial shared state returned by an agent for merging into the current run state.
+ *
+ * @since 5.1
+ */
+export type SharedStatePatch<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStatePatchEntry<T[K]>;
+};
+
+/**
+ * Kinds of resources an agent can share with subsequent agents.
+ *
+ * @since 5.2
+ */
+export type SharedResourceKind = "custom" | "extent" | "point" | "polygon" | "polyline";
+
+/**
+ * Resource available to agents during a conversation.
+ *
+ * @remarks Descriptions are limited to 256 characters. Payloads must be compatible with the structured clone algorithm.
+ * @since 5.2
+ */
+export type SharedResource = Readonly<{
+    id: string;
+    kind: SharedResourceKind;
+    description: string;
+    payload: unknown;
+    meta: {
+        createdByAgentId: string;
+        createdAt: number;
+    };
+}>;
+
+/**
+ * Resource supplied by an agent before the orchestrator adds identity and metadata.
+ *
+ * @remarks Description values longer than 256 characters are truncated. Payloads are cloned using the structured clone algorithm.
+ * @since 5.2
+ */
+export type SharedResourceInput = Readonly<{
+    kind: SharedResourceKind;
+    description: string;
+    payload: unknown;
+}>;
+
+/** Stored shared state entry. `meta` is added by the orchestrator. */
+export type SharedStateEntry<T = unknown> = {
+  value: T;
+  meta: {
+      updatedByAgentId: string;
+      updatedAt: number;
+  };
+};
+
+/** Patch shape returned by agents. `meta` is intentionally omitted. */
+export type SharedStatePatchEntry<T = unknown> = {
+  value: T;
+};

package/dist/orchestrator/state/types.js

@@ -0,0 +1,2 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+