@databricks/appkit-ui 0.32.0 → 0.34.0

package/CLAUDE.md

@@ -43,6 +43,7 @@ npx @databricks/appkit docs <query>
 
 ## Plugins
 
+- [Agents](./docs/plugins/agents.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
 - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
@@ -59,11 +60,13 @@ npx @databricks/appkit docs <query>
 
 ## appkit API reference [collapsed]
 
-- [@databricks/appkit](./docs/api/appkit.md): Core library for building Databricks applications with type-safe SQL queries,
+- [@databricks/appkit](./docs/api/appkit.md): Documentation merge entry for Typedoc — combines the stable @databricks/appkit
 - [Abstract Class: AppKitError](./docs/api/appkit/Class.AppKitError.md): Base error class for all AppKit errors.
+- [Class: AppKitMcpClient](./docs/api/appkit/Class.AppKitMcpClient.md): Lightweight MCP client for Databricks-hosted MCP servers.
 - [Class: AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md): Error thrown when authentication fails.
 - [Class: ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md): Error thrown when configuration is missing or invalid.
 - [Class: ConnectionError](./docs/api/appkit/Class.ConnectionError.md): Error thrown when a connection or network operation fails.
+- [Class: DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md): Adapter that talks directly to Databricks Model Serving /invocations endpoint.
 - [Class: ExecutionError](./docs/api/appkit/Class.ExecutionError.md): Error thrown when an operation execution fails.
 - [Class: InitializationError](./docs/api/appkit/Class.InitializationError.md): Error thrown when a service or component is not properly initialized.
 - [Abstract Class: Plugin<TConfig>](./docs/api/appkit/Class.Plugin.md): Base abstract class for creating AppKit plugins.
@@ -74,12 +77,17 @@ npx @databricks/appkit docs <query>
 - [Class: ValidationError](./docs/api/appkit/Class.ValidationError.md): Error thrown when input validation fails.
 - [Enumeration: RequestedClaimsPermissionSet](./docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md): Permission set for Unity Catalog table access
 - [Enumeration: ResourceType](./docs/api/appkit/Enumeration.ResourceType.md): Resource types from schema $defs.resourceType.enum
+- [Function: agentIdFromMarkdownPath()](./docs/api/appkit/Function.agentIdFromMarkdownPath.md): Derives the logical agent id from a markdown path. When the file is named
 - [Function: appKitServingTypesPlugin()](./docs/api/appkit/Function.appKitServingTypesPlugin.md): Vite plugin to generate TypeScript types for AppKit serving endpoints.
 - [Function: appKitTypesPlugin()](./docs/api/appkit/Function.appKitTypesPlugin.md): Vite plugin to generate types for AppKit queries.
+- [Function: createAgent()](./docs/api/appkit/Function.createAgent.md): Pure factory for agent definitions. Returns the passed-in definition after
 - [Function: createApp()](./docs/api/appkit/Function.createApp.md): Bootstraps AppKit with the provided configuration.
 - [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
+- [Function: defineTool()](./docs/api/appkit/Function.defineTool.md): Defines a single tool entry for a plugin's internal registry.
+- [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
 - [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
+- [Function: functionToolToDefinition()](./docs/api/appkit/Function.functionToolToDefinition.md): Parameters
 - [Function: generateDatabaseCredential()](./docs/api/appkit/Function.generateDatabaseCredential.md): Generate OAuth credentials for Postgres database connection using the proper Postgres API.
 - [Function: getExecutionContext()](./docs/api/appkit/Function.getExecutionContext.md): Get the current execution context.
 - [Function: getLakebaseOrmConfig()](./docs/api/appkit/Function.getLakebaseOrmConfig.md): Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
@@ -88,13 +96,32 @@ npx @databricks/appkit docs <query>
 - [Function: getResourceRequirements()](./docs/api/appkit/Function.getResourceRequirements.md): Gets the resource requirements from a plugin's manifest.
 - [Function: getUsernameWithApiLookup()](./docs/api/appkit/Function.getUsernameWithApiLookup.md): Resolves the PostgreSQL username for a Lakebase connection.
 - [Function: getWorkspaceClient()](./docs/api/appkit/Function.getWorkspaceClient.md): Get workspace client from config or SDK default auth chain
+- [Function: isFunctionTool()](./docs/api/appkit/Function.isFunctionTool.md): Parameters
+- [Function: isHostedTool()](./docs/api/appkit/Function.isHostedTool.md): Parameters
 - [Function: isSQLTypeMarker()](./docs/api/appkit/Function.isSQLTypeMarker.md): Type guard to check if a value is a SQL type marker
+- [Function: isToolkitEntry()](./docs/api/appkit/Function.isToolkitEntry.md): Type guard for ToolkitEntry — used by the agents plugin to differentiate
+- [Function: loadAgentFromFile()](./docs/api/appkit/Function.loadAgentFromFile.md): Loads a single markdown agent file and resolves its frontmatter against
+- [Function: loadAgentsFromDir()](./docs/api/appkit/Function.loadAgentsFromDir.md): Scans a directory for one subdirectory per agent, each containing
+- [Function: mcpServer()](./docs/api/appkit/Function.mcpServer.md): Factory for declaring a custom MCP server tool.
+- [Function: parseTextToolCalls()](./docs/api/appkit/Function.parseTextToolCalls.md): Parses text-based tool calls from model output.
+- [Function: resolveHostedTools()](./docs/api/appkit/Function.resolveHostedTools.md): Parameters
+- [Function: runAgent()](./docs/api/appkit/Function.runAgent.md): Standalone agent execution without createApp. Resolves the adapter, binds
+- [Function: tool()](./docs/api/appkit/Function.tool.md): Factory for defining function tools with Zod schemas.
+- [Function: toolsFromRegistry()](./docs/api/appkit/Function.toolsFromRegistry.md): Produces the AgentToolDefinition[] a ToolProvider exposes to the LLM,
+- [Interface: AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md): Methods
+- [Interface: AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md): Properties
+- [Interface: AgentInput](./docs/api/appkit/Interface.AgentInput.md): Properties
+- [Interface: AgentRunContext](./docs/api/appkit/Interface.AgentRunContext.md): Properties
+- [Interface: AgentsPluginConfig](./docs/api/appkit/Interface.AgentsPluginConfig.md): Base configuration interface for AppKit plugins
+- [Interface: AgentToolDefinition](./docs/api/appkit/Interface.AgentToolDefinition.md): Properties
+- [Interface: AutoInheritToolsConfig](./docs/api/appkit/Interface.AutoInheritToolsConfig.md): Auto-inherit configuration. When enabled for a given agent origin, agents
 - [Interface: BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md): Base configuration interface for AppKit plugins
 - [Interface: CacheConfig](./docs/api/appkit/Interface.CacheConfig.md): Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
 - [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
 - [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
+- [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
@@ -102,28 +129,53 @@ npx @databricks/appkit docs <query>
 - [Interface: JobConfig](./docs/api/appkit/Interface.JobConfig.md): Per-job configuration options.
 - [Interface: JobsConnectorConfig](./docs/api/appkit/Interface.JobsConnectorConfig.md): Properties
 - [Interface: LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md): Configuration for creating a Lakebase connection pool
+- [Interface: McpConnectAllResult](./docs/api/appkit/Interface.McpConnectAllResult.md): Per-endpoint outcome of AppKitMcpClient.connectAll. Callers (the
+- [Interface: Message](./docs/api/appkit/Interface.Message.md): Properties
 - [Interface: PluginManifest<TName>](./docs/api/appkit/Interface.PluginManifest.md): Plugin manifest that declares metadata and resource requirements.
+- [Interface: PluginToolkitProvider](./docs/api/appkit/Interface.PluginToolkitProvider.md): Minimum shape every entry in the Plugins map must expose. Core
+- [Interface: PromptContext](./docs/api/appkit/Interface.PromptContext.md): Context passed to baseSystemPrompt callbacks.
+- [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
 - [Interface: RequestedResource](./docs/api/appkit/Interface.RequestedResource.md): Resource to request permissions for in Unity Catalog
 - [Interface: ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md): Internal representation of a resource in the registry.
 - [Interface: ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md): Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instancename, databasename or scope, key).
 - [Interface: ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md): Declares a resource requirement for a plugin.
+- [Interface: RunAgentInput](./docs/api/appkit/Interface.RunAgentInput.md): Properties
+- [Interface: RunAgentResult](./docs/api/appkit/Interface.RunAgentResult.md): Properties
 - [Interface: ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md): Shape of a single registry entry.
 - [Interface: ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md): Registry interface for serving endpoint type generation.
 - [Interface: StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md): Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
 - [Interface: TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md): OpenTelemetry configuration for AppKit applications
+- [Interface: Thread](./docs/api/appkit/Interface.Thread.md): Properties
+- [Interface: ThreadStore](./docs/api/appkit/Interface.ThreadStore.md): Methods
+- [Interface: ToolAnnotations](./docs/api/appkit/Interface.ToolAnnotations.md): Properties
+- [Interface: ToolConfig<S>](./docs/api/appkit/Interface.ToolConfig.md): Type Parameters
+- [Interface: ToolEntry<S>](./docs/api/appkit/Interface.ToolEntry.md): Single-tool entry for a plugin's internal tool registry.
+- [Interface: ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md): A tool reference produced by a plugin's .toolkit() call. The agents plugin
+- [Interface: ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md): Properties
+- [Interface: ToolProvider](./docs/api/appkit/Interface.ToolProvider.md): Methods
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
+- [Type Alias: AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md): Type Declaration
+- [Type Alias: AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md): Any tool an agent can invoke: inline function tools (tool()), hosted MCP
+- [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,
+- [Type Alias: AgentToolsFn()](./docs/api/appkit/TypeAlias.AgentToolsFn.md): Function form of AgentDefinition.tools. Receives the typed
+- [Type Alias: BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
 - [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
 - [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
 - [Type Alias: FilePolicy()](./docs/api/appkit/TypeAlias.FilePolicy.md): A policy function that decides whether user may perform action on
+- [Type Alias: HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md)
 - [Type Alias: IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md): Express router type for plugin route registration
 - [Type Alias: JobHandle](./docs/api/appkit/TypeAlias.JobHandle.md): Job handle returned by appkit.jobs("etl").
 - [Type Alias: JobsExport()](./docs/api/appkit/TypeAlias.JobsExport.md): Public API shape of the jobs plugin.
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
+- [Type Alias: Plugins](./docs/api/appkit/TypeAlias.Plugins.md): Plugin map passed to the function form of AgentDefinition.tools.
+- [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
 - [Type Alias: ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md): Factory function returned by AppKit.serving.
+- [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
+- [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Reads config/agents/*.md by default,
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
 - [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
 - [Variable: WRITE_ACTIONS](./docs/api/appkit/Variable.WRITE_ACTIONS.md): Actions that mutate data.

package/NOTICE.md

@@ -66,6 +66,7 @@ This Software contains code from the following open source projects:
 | [express](https://www.npmjs.com/package/express) | 4.22.0 | MIT | http://expressjs.com/ |
 | [get-port](https://www.npmjs.com/package/get-port) | 7.2.0 | MIT | https://github.com/sindresorhus/get-port#readme |
 | [input-otp](https://www.npmjs.com/package/input-otp) | 1.4.2 | MIT | https://input-otp.rodz.dev/ |
+| [js-yaml](https://www.npmjs.com/package/js-yaml) | 3.14.2, 4.1.1 | MIT | https://github.com/nodeca/js-yaml#readme |
 | [lucide-react](https://www.npmjs.com/package/lucide-react) | 0.554.0 | ISC | https://lucide.dev |
 | [marked](https://www.npmjs.com/package/marked) | 16.4.2, 17.0.3 | MIT | https://marked.js.org |
 | [next-themes](https://www.npmjs.com/package/next-themes) | 0.4.6 | MIT | https://github.com/pacocoursey/next-themes#readme |

package/dist/js/index.js

@@ -1,4 +1,5 @@
 import { isSQLTypeMarker, sql } from "../shared/src/sql/helpers.js";
+import "../shared/src/index.js";
 import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from "./constants.js";
 import { getArrowModule, initializeTypeIdSets } from "./arrow/lazy-arrow.js";
 import { ArrowClient } from "./arrow/arrow-client.js";

package/dist/react/hooks/index.d.ts

@@ -1,5 +1,6 @@
 import { UseChartDataOptions, UseChartDataResult, useChartData } from "./use-chart-data.js";
 import { AnalyticsFormat, InferResultByFormat, InferRowType, InferServingChunk, InferServingRequest, InferServingResponse, PluginRegistry, QueryRegistry, ServingAlias, ServingEndpointRegistry, TypedArrowTable, UseAnalyticsQueryOptions, UseAnalyticsQueryResult } from "./types.js";
+import { AgentChatEvent, UseAgentChatOptions, UseAgentChatResult, useAgentChat } from "./use-agent-chat.js";
 import { useAnalyticsQuery } from "./use-analytics-query.js";
 import { usePluginClientConfig } from "./use-plugin-config.js";
 import { UseServingInvokeOptions, UseServingInvokeResult, useServingInvoke } from "./use-serving-invoke.js";

package/dist/react/hooks/index.js

@@ -1,5 +1,6 @@
 import { useAnalyticsQuery } from "./use-analytics-query.js";
 import { useChartData } from "./use-chart-data.js";
+import { useAgentChat } from "./use-agent-chat.js";
 import { usePluginClientConfig } from "./use-plugin-config.js";
 import { useServingInvoke } from "./use-serving-invoke.js";
 import { useServingStream } from "./use-serving-stream.js";

package/dist/react/hooks/types.d.ts

@@ -1,8 +1,14 @@
 import { Table } from "apache-arrow";
 
 //#region src/react/hooks/types.d.ts
-/** Supported response formats for analytics queries */
-type AnalyticsFormat = "JSON" | "ARROW";
+/**
+ * Supported response formats for analytics queries.
+ *
+ * "JSON" and "ARROW" are legacy aliases kept for backwards compatibility
+ * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on
+ * a pre-0.33.0 version.
+ */
+type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM" /** @deprecated Use "JSON_ARRAY". Safe to remove once no consumer is on appkit-ui < 0.33.0. */ | "JSON" /** @deprecated Use "ARROW_STREAM". Safe to remove once no consumer is on appkit-ui < 0.33.0. */ | "ARROW";
 /**
  * Typed Arrow Table - preserves row type information for type inference.
  * At runtime this is just a regular Arrow Table, but TypeScript knows the row schema.
@@ -21,8 +27,8 @@ interface TypedArrowTable<TRow extends Record<string, unknown> = Record<string,
   readonly __rowType?: TRow;
 }
 /** Options for configuring an analytics SSE query */
-interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON"> {
-  /** Response format - "JSON" returns typed arrays, "ARROW" returns TypedArrowTable */
+interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON_ARRAY"> {
+  /** Response format - "JSON_ARRAY" returns typed arrays, "ARROW_STREAM" returns TypedArrowTable */
   format?: F;
   /** Maximum size of serialized parameters in bytes */
   maxParametersSize?: number;
@@ -86,7 +92,7 @@ type InferRowType<K> = K extends AugmentedRegistry<QueryRegistry> ? QueryRegistr
  * - JSON format: Returns the typed array from QueryRegistry
  * - ARROW format: Returns TypedArrowTable with row type preserved
  */
-type InferResultByFormat<T, K, F extends AnalyticsFormat> = F extends "ARROW" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
+type InferResultByFormat<T, K, F extends AnalyticsFormat> = F extends "ARROW_STREAM" | "ARROW" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
 /**
  * Infers parameters type from QueryRegistry[K]["parameters"]
  */

package/dist/react/hooks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/hooks/types.ts"],"mappings":";;;;KAOY,eAAA;AAAZ;;;;;AAYA;;;;;AAZA,UAYiB,eAAA,cACF,MAAA,oBAA0B,MAAA,2BAC/B,KAAA;EAAA;;;;EAAA,SAKC,SAAA,GAAY,IAAA;AAAA;;UAQN,wBAAA,WAAmC,eAAA;EAR7B;EAUrB,MAAA,GAAS,CAAA;EAVgB;EAazB,iBAAA;EALuC;EAQvC,SAAA;AAAA;;UAIe,uBAAA;EAVf;EAYA,IAAA,EAAM,CAAA;EATN;EAWA,OAAA;EARS;EAUT,KAAA;AAAA;;;;;;;;;;;AAqBF;;;;;;;;UAAiB,aAAA;EAAA,CACd,GAAA;IACC,IAAA;IACA,UAAA,EAAY,MAAA;IACZ,MAAA;EAAA;AAAA;;KAKQ,iBAAA,0BACE,CAAA,mBAAoB,CAAA,WAAY,CAAA,GAAI,CAAA,CAAE,CAAA;;KAIxC,QAAA,GAAW,iBAAA,CAAkB,aAAA,2BAErC,iBAAA,CAAkB,aAAA;;;;;KAMV,WAAA,SAAoB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACxD,aAAA,CAAc,CAAA;EAAa,MAAA;AAAA,IACzB,CAAA,GACA,CAAA,GACF,CAAA;;;AAZJ;;KAkBY,YAAA,MAAkB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACtD,aAAA,CAAc,CAAA;EAAa,MAAA,EAAQ,KAAA;AAAA,IACjC,CAAA,SAAU,MAAA,oBACR,CAAA,GACA,MAAA,oBACF,MAAA,oBACF,MAAA;;;;;;KAOQ,mBAAA,iBAGA,eAAA,IACR,CAAA,mBAAoB,eAAA,CAAgB,YAAA,CAAa,CAAA,KAAM,WAAA,CAAY,CAAA,EAAG,CAAA;;;;KAK9D,WAAA,MAAiB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACrD,aAAA,CAAc,CAAA;EAAa,UAAA;AAAA,IACzB,CAAA,GACA,MAAA,oBACF,MAAA;AAAA,UAEa,cAAA;EAAA,CACd,GAAA,WAAc,MAAA;AAAA;;;;;;;;;;;;;;;UA2BA,uBAAA;;KAGL,YAAA,GACV,iBAAA,CAAkB,uBAAA,2BAEd,iBAAA,CAAkB,uBAAA;;KAGZ,iBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,KAAA;AAAA,IACnC,CAAA;;KAKI,oBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,QAAA;AAAA,IACnC,CAAA;;KAKI,mBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,OAAA;AAAA,IACnC,GAAA,GACA,MAAA,oBACF,MAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/hooks/types.ts"],"mappings":";;;;;AAaA;;;;;KAAY,eAAA;;;;;;;;;;;UAkBK,eAAA,cACF,MAAA,oBAA0B,MAAA,2BAC/B,KAAA;EAKiB;AAQ3B;;;EAR2B,SAAhB,SAAA,GAAY,IAAA;AAAA;;UAQN,wBAAA,WACL,eAAA;EAGD;EAAT,MAAA,GAAS,CAAA;EAMT;EAHA,iBAAA;EAGS;EAAT,SAAA;AAAA;;UAIe,uBAAA;EAAwB;EAEvC,IAAA,EAAM,CAAA;EAAA;EAEN,OAAA;EAEA;EAAA,KAAA;AAAA;AAqBF;;;;;;;;;;;AASA;;;;;;;AATA,UAAiB,aAAA;EAAA,CACd,GAAA;IACC,IAAA;IACA,UAAA,EAAY,MAAA;IACZ,MAAA;EAAA;AAAA;;KAKQ,iBAAA,0BACE,CAAA,mBAAoB,CAAA,WAAY,CAAA,GAAI,CAAA,CAAE,CAAA;;KAIxC,QAAA,GAAW,iBAAA,CAAkB,aAAA,2BAErC,iBAAA,CAAkB,aAAA;;;;;KAMV,WAAA,SAAoB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACxD,aAAA,CAAc,CAAA;EAAa,MAAA;AAAA,IACzB,CAAA,GACA,CAAA,GACF,CAAA;;;;;KAMQ,YAAA,MAAkB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACtD,aAAA,CAAc,CAAA;EAAa,MAAA,EAAQ,KAAA;AAAA,IACjC,CAAA,SAAU,MAAA,oBACR,CAAA,GACA,MAAA,oBACF,MAAA,oBACF,MAAA;AAhBJ;;;;;AAAA,KAuBY,mBAAA,iBAAoC,eAAA,IAAmB,CAAA,oCAG/D,eAAA,CAAgB,YAAA,CAAa,CAAA,KAC7B,WAAA,CAAY,CAAA,EAAG,CAAA;;;;KAKP,WAAA,MAAiB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACrD,aAAA,CAAc,CAAA;EAAa,UAAA;AAAA,IACzB,CAAA,GACA,MAAA,oBACF,MAAA;AAAA,UAEa,cAAA;EAAA,CACd,GAAA,WAAc,MAAA;AAAA;;;;;;;;AA7BjB;;;;;;;UAwDiB,uBAAA;;KAGL,YAAA,GACV,iBAAA,CAAkB,uBAAA,2BAEd,iBAAA,CAAkB,uBAAA;;KAGZ,iBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,KAAA;AAAA,IACnC,CAAA;;KAKI,oBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,QAAA;AAAA,IACnC,CAAA;;KAKI,mBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,OAAA;AAAA,IACnC,GAAA,GACA,MAAA,oBACF,MAAA"}

package/dist/react/hooks/use-agent-chat.d.ts

@@ -0,0 +1,128 @@
+//#region src/react/hooks/use-agent-chat.d.ts
+/**
+ * One Responses-API-shaped event yielded by the agents plugin SSE stream.
+ *
+ * The hook handles the two paths every chat UI needs — accumulating
+ * `content` from `response.output_text.delta` and capturing `threadId`
+ * from `appkit.metadata` — and surfaces everything else (tool calls,
+ * approval gates, status events, etc.) through {@link UseAgentChatOptions.onEvent}.
+ *
+ * Fields beyond `type` are intentionally loose because the agents plugin
+ * forwards adapter-specific shapes verbatim. Treat unknown fields as
+ * opaque pass-through.
+ */
+interface AgentChatEvent {
+  type: string;
+  delta?: string;
+  item_id?: string;
+  item?: {
+    type?: string;
+    id?: string;
+    call_id?: string;
+    name?: string;
+    arguments?: string;
+    output?: string;
+    status?: string;
+  };
+  content?: string;
+  data?: Record<string, unknown>;
+  error?: string;
+  sequence_number?: number;
+  output_index?: number;
+  approval_id?: string;
+  stream_id?: string;
+  tool_name?: string;
+  args?: unknown;
+  annotations?: Record<string, unknown>;
+}
+interface UseAgentChatOptions {
+  /**
+   * Agent name registered with the `agents()` plugin (e.g. `"assistant"`,
+   * `"helper"`). Send-time payload includes this so the plugin routes the
+   * turn to the right `AgentDefinition`.
+   */
+  agent: string;
+  /**
+   * Override the chat endpoint. Default `"/api/agents/chat"` matches the
+   * route the agents plugin mounts under its prefix. Useful when the
+   * server mounts under a non-default base path or when proxying.
+   */
+  endpoint?: string;
+  /**
+   * Called for every parsed SSE event before any state update. Use this
+   * to drive tool-call rows, approval cards, inspectors, or anything
+   * beyond the streaming text content. Errors thrown here are swallowed
+   * so a buggy handler can't kill the stream.
+   */
+  onEvent?: (event: AgentChatEvent) => void;
+}
+interface UseAgentChatResult {
+  /** Accumulated assistant text from `response.output_text.delta` events. */
+  content: string;
+  /**
+   * Every parsed event, in order. Provided for components that need to
+   * render historical tool calls or replay state after a remount —
+   * lighter than re-deriving from message history. For one-off side
+   * effects prefer {@link UseAgentChatOptions.onEvent}.
+   */
+  events: AgentChatEvent[];
+  /**
+   * Thread id captured from the first `appkit.metadata` event of the
+   * stream. Subsequent `send()` calls automatically forward this so the
+   * server reuses the same thread.
+   */
+  threadId: string | null;
+  /** True while an SSE stream is open. */
+  isStreaming: boolean;
+  /** Last error message (cleared on next successful `send()`). */
+  error: string | null;
+  /**
+   * Send a user turn and stream the response. Aborts any in-flight
+   * stream. Resolves when the stream completes (success or error).
+   */
+  send: (message: string) => Promise<void>;
+  /**
+   * Discard accumulated content, events, and threadId. Aborts any
+   * in-flight stream. Use when switching agents or starting a fresh
+   * conversation.
+   */
+  reset: () => void;
+}
+/**
+ * React hook for chatting with an agent registered via the `agents()`
+ * plugin. Wraps {@link connectSSE} (which owns the buffer cap, abort
+ * composition, retry/backoff, and frame parsing) with the small amount
+ * of stateful glue every chat UI needs: accumulated assistant text,
+ * thread id, streaming flag, and an event callback.
+ *
+ * The hook is intentionally lower-level than a full chat component —
+ * it owns one stream at a time, not a multi-turn message history. The
+ * caller composes its own messages array (typically a `useState`) and
+ * appends to it via the `onEvent` callback for tool calls and via the
+ * `content` field for assistant text.
+ *
+ * @example
+ * ```tsx
+ * function Chat({ agent }: { agent: string }) {
+ *   const [messages, setMessages] = useState<Message[]>([]);
+ *   const { content, threadId, isStreaming, send, reset } = useAgentChat({
+ *     agent,
+ *     onEvent(ev) {
+ *       if (ev.type === "response.output_item.added" && ev.item?.type === "function_call") {
+ *         setMessages((m) => [...m, { role: "tool", name: ev.item?.name, args: ev.item?.arguments }]);
+ *       }
+ *     },
+ *   });
+ *   // `content` reflects the latest assistant turn; reset() between conversations.
+ *   // ...
+ * }
+ * ```
+ */
+declare function useAgentChat({
+  agent,
+  endpoint,
+  onEvent
+}: UseAgentChatOptions): UseAgentChatResult;
+//#endregion
+export { AgentChatEvent, UseAgentChatOptions, UseAgentChatResult, useAgentChat };
+//# sourceMappingURL=use-agent-chat.d.ts.map

package/dist/react/hooks/use-agent-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent-chat.d.ts","names":[],"sources":["../../../src/react/hooks/use-agent-chat.ts"],"mappings":";;AAeA;;;;;;;;;;;UAAiB,cAAA;EACf,IAAA;EACA,KAAA;EACA,OAAA;EACA,IAAA;IACE,IAAA;IACA,EAAA;IACA,OAAA;IACA,IAAA;IACA,SAAA;IACA,MAAA;IACA,MAAA;EAAA;EAEF,OAAA;EACA,IAAA,GAAO,MAAA;EACP,KAAA;EACA,eAAA;EACA,YAAA;EAEA,WAAA;EACA,SAAA;EACA,SAAA;EACA,IAAA;EACA,WAAA,GAAc,MAAA;AAAA;AAAA,UAGC,mBAAA;EAmBG;;;;AAGpB;EAhBE,KAAA;;;;;;EAMA,QAAA;EA2BA;;;;;;EApBA,OAAA,IAAW,KAAA,EAAO,cAAA;AAAA;AAAA,UAGH,kBAAA;EA+DW;EA7D1B,OAAA;EA8DA;;;;;;EAvDA,MAAA,EAAQ,cAAA;EAuDR;;;;;EAjDA,QAAA;EAoDC;EAlDD,WAAA;EAkDyC;EAhDzC,KAAA;;;;;EAKA,IAAA,GAAO,OAAA,aAAoB,OAAA;;;;;;EAM3B,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCc,YAAA,CAAA;EACd,KAAA;EACA,QAAA;EACA;AAAA,GACC,mBAAA,GAAsB,kBAAA"}

package/dist/react/hooks/use-agent-chat.js

@@ -0,0 +1,133 @@
+import { connectSSE } from "../../js/sse/connect-sse.js";
+import "../../js/index.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/react/hooks/use-agent-chat.ts
+/**
+* React hook for chatting with an agent registered via the `agents()`
+* plugin. Wraps {@link connectSSE} (which owns the buffer cap, abort
+* composition, retry/backoff, and frame parsing) with the small amount
+* of stateful glue every chat UI needs: accumulated assistant text,
+* thread id, streaming flag, and an event callback.
+*
+* The hook is intentionally lower-level than a full chat component —
+* it owns one stream at a time, not a multi-turn message history. The
+* caller composes its own messages array (typically a `useState`) and
+* appends to it via the `onEvent` callback for tool calls and via the
+* `content` field for assistant text.
+*
+* @example
+* ```tsx
+* function Chat({ agent }: { agent: string }) {
+*   const [messages, setMessages] = useState<Message[]>([]);
+*   const { content, threadId, isStreaming, send, reset } = useAgentChat({
+*     agent,
+*     onEvent(ev) {
+*       if (ev.type === "response.output_item.added" && ev.item?.type === "function_call") {
+*         setMessages((m) => [...m, { role: "tool", name: ev.item?.name, args: ev.item?.arguments }]);
+*       }
+*     },
+*   });
+*   // `content` reflects the latest assistant turn; reset() between conversations.
+*   // ...
+* }
+* ```
+*/
+function useAgentChat({ agent, endpoint = "/api/agents/chat", onEvent }) {
+	const [content, setContent] = useState("");
+	const [events, setEvents] = useState([]);
+	const [threadId, setThreadId] = useState(null);
+	const [isStreaming, setIsStreaming] = useState(false);
+	const [error, setError] = useState(null);
+	const threadIdRef = useRef(null);
+	const contentRef = useRef("");
+	const onEventRef = useRef(onEvent);
+	onEventRef.current = onEvent;
+	const abortControllerRef = useRef(null);
+	const reset = useCallback(() => {
+		abortControllerRef.current?.abort();
+		abortControllerRef.current = null;
+		threadIdRef.current = null;
+		contentRef.current = "";
+		setContent("");
+		setEvents([]);
+		setThreadId(null);
+		setIsStreaming(false);
+		setError(null);
+	}, []);
+	const send = useCallback(async (message) => {
+		abortControllerRef.current?.abort();
+		const controller = new AbortController();
+		abortControllerRef.current = controller;
+		contentRef.current = "";
+		setContent("");
+		setEvents([]);
+		setError(null);
+		setIsStreaming(true);
+		const payload = {
+			message,
+			agent,
+			...threadIdRef.current ? { threadId: threadIdRef.current } : {}
+		};
+		try {
+			await connectSSE({
+				url: endpoint,
+				payload,
+				signal: controller.signal,
+				maxRetries: 0,
+				onMessage: async ({ data }) => {
+					if (controller.signal.aborted) return;
+					if (!data || data === "[DONE]") return;
+					let event;
+					try {
+						event = JSON.parse(data);
+					} catch {
+						return;
+					}
+					if (!event.type) return;
+					try {
+						onEventRef.current?.(event);
+					} catch {}
+					setEvents((prev) => [...prev, event]);
+					if (event.type === "appkit.metadata") {
+						const tid = event.data?.threadId;
+						if (typeof tid === "string") {
+							threadIdRef.current = tid;
+							setThreadId(tid);
+						}
+					} else if (event.type === "response.output_text.delta" && typeof event.delta === "string") {
+						contentRef.current += event.delta;
+						setContent(contentRef.current);
+					}
+				},
+				onError: (err) => {
+					if (controller.signal.aborted) return;
+					setError(err instanceof Error ? err.message : "Chat stream failed");
+				}
+			});
+		} catch (err) {
+			if (!controller.signal.aborted) setError(err instanceof Error ? err.message : "Chat stream failed");
+		} finally {
+			if (abortControllerRef.current === controller) abortControllerRef.current = null;
+			setIsStreaming(false);
+		}
+	}, [agent, endpoint]);
+	useEffect(() => {
+		return () => {
+			abortControllerRef.current?.abort();
+		};
+	}, []);
+	return {
+		content,
+		events,
+		threadId,
+		isStreaming,
+		error,
+		send,
+		reset
+	};
+}
+
+//#endregion
+export { useAgentChat };
+//# sourceMappingURL=use-agent-chat.js.map

package/dist/react/hooks/use-agent-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent-chat.js","names":[],"sources":["../../../src/react/hooks/use-agent-chat.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\nimport { connectSSE } from \"@/js\";\n\n/**\n * One Responses-API-shaped event yielded by the agents plugin SSE stream.\n *\n * The hook handles the two paths every chat UI needs — accumulating\n * `content` from `response.output_text.delta` and capturing `threadId`\n * from `appkit.metadata` — and surfaces everything else (tool calls,\n * approval gates, status events, etc.) through {@link UseAgentChatOptions.onEvent}.\n *\n * Fields beyond `type` are intentionally loose because the agents plugin\n * forwards adapter-specific shapes verbatim. Treat unknown fields as\n * opaque pass-through.\n */\nexport interface AgentChatEvent {\n  type: string;\n  delta?: string;\n  item_id?: string;\n  item?: {\n    type?: string;\n    id?: string;\n    call_id?: string;\n    name?: string;\n    arguments?: string;\n    output?: string;\n    status?: string;\n  };\n  content?: string;\n  data?: Record<string, unknown>;\n  error?: string;\n  sequence_number?: number;\n  output_index?: number;\n  // `appkit.approval_pending` payload\n  approval_id?: string;\n  stream_id?: string;\n  tool_name?: string;\n  args?: unknown;\n  annotations?: Record<string, unknown>;\n}\n\nexport interface UseAgentChatOptions {\n  /**\n   * Agent name registered with the `agents()` plugin (e.g. `\"assistant\"`,\n   * `\"helper\"`). Send-time payload includes this so the plugin routes the\n   * turn to the right `AgentDefinition`.\n   */\n  agent: string;\n  /**\n   * Override the chat endpoint. Default `\"/api/agents/chat\"` matches the\n   * route the agents plugin mounts under its prefix. Useful when the\n   * server mounts under a non-default base path or when proxying.\n   */\n  endpoint?: string;\n  /**\n   * Called for every parsed SSE event before any state update. Use this\n   * to drive tool-call rows, approval cards, inspectors, or anything\n   * beyond the streaming text content. Errors thrown here are swallowed\n   * so a buggy handler can't kill the stream.\n   */\n  onEvent?: (event: AgentChatEvent) => void;\n}\n\nexport interface UseAgentChatResult {\n  /** Accumulated assistant text from `response.output_text.delta` events. */\n  content: string;\n  /**\n   * Every parsed event, in order. Provided for components that need to\n   * render historical tool calls or replay state after a remount —\n   * lighter than re-deriving from message history. For one-off side\n   * effects prefer {@link UseAgentChatOptions.onEvent}.\n   */\n  events: AgentChatEvent[];\n  /**\n   * Thread id captured from the first `appkit.metadata` event of the\n   * stream. Subsequent `send()` calls automatically forward this so the\n   * server reuses the same thread.\n   */\n  threadId: string | null;\n  /** True while an SSE stream is open. */\n  isStreaming: boolean;\n  /** Last error message (cleared on next successful `send()`). */\n  error: string | null;\n  /**\n   * Send a user turn and stream the response. Aborts any in-flight\n   * stream. Resolves when the stream completes (success or error).\n   */\n  send: (message: string) => Promise<void>;\n  /**\n   * Discard accumulated content, events, and threadId. Aborts any\n   * in-flight stream. Use when switching agents or starting a fresh\n   * conversation.\n   */\n  reset: () => void;\n}\n\n/**\n * React hook for chatting with an agent registered via the `agents()`\n * plugin. Wraps {@link connectSSE} (which owns the buffer cap, abort\n * composition, retry/backoff, and frame parsing) with the small amount\n * of stateful glue every chat UI needs: accumulated assistant text,\n * thread id, streaming flag, and an event callback.\n *\n * The hook is intentionally lower-level than a full chat component —\n * it owns one stream at a time, not a multi-turn message history. The\n * caller composes its own messages array (typically a `useState`) and\n * appends to it via the `onEvent` callback for tool calls and via the\n * `content` field for assistant text.\n *\n * @example\n * ```tsx\n * function Chat({ agent }: { agent: string }) {\n *   const [messages, setMessages] = useState<Message[]>([]);\n *   const { content, threadId, isStreaming, send, reset } = useAgentChat({\n *     agent,\n *     onEvent(ev) {\n *       if (ev.type === \"response.output_item.added\" && ev.item?.type === \"function_call\") {\n *         setMessages((m) => [...m, { role: \"tool\", name: ev.item?.name, args: ev.item?.arguments }]);\n *       }\n *     },\n *   });\n *   // `content` reflects the latest assistant turn; reset() between conversations.\n *   // ...\n * }\n * ```\n */\nexport function useAgentChat({\n  agent,\n  endpoint = \"/api/agents/chat\",\n  onEvent,\n}: UseAgentChatOptions): UseAgentChatResult {\n  const [content, setContent] = useState(\"\");\n  const [events, setEvents] = useState<AgentChatEvent[]>([]);\n  const [threadId, setThreadId] = useState<string | null>(null);\n  const [isStreaming, setIsStreaming] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n\n  // Refs avoid the standard \"stale closure\" problem with `send` and\n  // `onEvent`: `send` is a stable callback that reads the latest\n  // threadId/onEvent without re-mounting connectSSE on every render.\n  const threadIdRef = useRef<string | null>(null);\n  const contentRef = useRef(\"\");\n  const onEventRef = useRef(onEvent);\n  onEventRef.current = onEvent;\n  const abortControllerRef = useRef<AbortController | null>(null);\n\n  const reset = useCallback(() => {\n    abortControllerRef.current?.abort();\n    abortControllerRef.current = null;\n    threadIdRef.current = null;\n    contentRef.current = \"\";\n    setContent(\"\");\n    setEvents([]);\n    setThreadId(null);\n    setIsStreaming(false);\n    setError(null);\n  }, []);\n\n  const send = useCallback(\n    async (message: string) => {\n      // Abort any previous stream — only one chat turn in flight per hook.\n      abortControllerRef.current?.abort();\n      const controller = new AbortController();\n      abortControllerRef.current = controller;\n\n      contentRef.current = \"\";\n      setContent(\"\");\n      setEvents([]);\n      setError(null);\n      setIsStreaming(true);\n\n      const payload = {\n        message,\n        agent,\n        ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),\n      };\n\n      try {\n        await connectSSE({\n          url: endpoint,\n          payload,\n          signal: controller.signal,\n          // Chat turns aren't idempotent — re-sending the payload after a\n          // transient failure would either duplicate the user message or\n          // depend on server-side Last-Event-ID resumption (the agents\n          // plugin's StreamManager supports it, but failure-mode auditing\n          // is easier with retries off by default; callers can re-enable\n          // via the underlying connectSSE once they understand the\n          // resumption contract on their endpoint).\n          maxRetries: 0,\n          onMessage: async ({ data }) => {\n            if (controller.signal.aborted) return;\n            if (!data || data === \"[DONE]\") return;\n            let event: AgentChatEvent;\n            try {\n              event = JSON.parse(data) as AgentChatEvent;\n            } catch {\n              // Skip malformed payloads — the rest of the stream is\n              // still useful and the agents plugin recovers on the\n              // next event boundary.\n              return;\n            }\n            if (!event.type) return;\n\n            // Best-effort: never let an onEvent throw break the stream.\n            try {\n              onEventRef.current?.(event);\n            } catch {\n              // swallow\n            }\n\n            setEvents((prev) => [...prev, event]);\n\n            if (event.type === \"appkit.metadata\") {\n              const tid = event.data?.threadId;\n              if (typeof tid === \"string\") {\n                threadIdRef.current = tid;\n                setThreadId(tid);\n              }\n            } else if (\n              event.type === \"response.output_text.delta\" &&\n              typeof event.delta === \"string\"\n            ) {\n              contentRef.current += event.delta;\n              setContent(contentRef.current);\n            }\n          },\n          onError: (err) => {\n            if (controller.signal.aborted) return;\n            setError(err instanceof Error ? err.message : \"Chat stream failed\");\n          },\n        });\n      } catch (err) {\n        if (!controller.signal.aborted) {\n          setError(err instanceof Error ? err.message : \"Chat stream failed\");\n        }\n      } finally {\n        if (abortControllerRef.current === controller) {\n          abortControllerRef.current = null;\n        }\n        setIsStreaming(false);\n      }\n    },\n    [agent, endpoint],\n  );\n\n  // Abort any in-flight stream when the component unmounts.\n  useEffect(() => {\n    return () => {\n      abortControllerRef.current?.abort();\n    };\n  }, []);\n\n  return {\n    content,\n    events,\n    threadId,\n    isStreaming,\n    error,\n    send,\n    reset,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HA,SAAgB,aAAa,EAC3B,OACA,WAAW,oBACX,WAC0C;CAC1C,MAAM,CAAC,SAAS,cAAc,SAAS,GAAG;CAC1C,MAAM,CAAC,QAAQ,aAAa,SAA2B,EAAE,CAAC;CAC1D,MAAM,CAAC,UAAU,eAAe,SAAwB,KAAK;CAC7D,MAAM,CAAC,aAAa,kBAAkB,SAAS,MAAM;CACrD,MAAM,CAAC,OAAO,YAAY,SAAwB,KAAK;CAKvD,MAAM,cAAc,OAAsB,KAAK;CAC/C,MAAM,aAAa,OAAO,GAAG;CAC7B,MAAM,aAAa,OAAO,QAAQ;AAClC,YAAW,UAAU;CACrB,MAAM,qBAAqB,OAA+B,KAAK;CAE/D,MAAM,QAAQ,kBAAkB;AAC9B,qBAAmB,SAAS,OAAO;AACnC,qBAAmB,UAAU;AAC7B,cAAY,UAAU;AACtB,aAAW,UAAU;AACrB,aAAW,GAAG;AACd,YAAU,EAAE,CAAC;AACb,cAAY,KAAK;AACjB,iBAAe,MAAM;AACrB,WAAS,KAAK;IACb,EAAE,CAAC;CAEN,MAAM,OAAO,YACX,OAAO,YAAoB;AAEzB,qBAAmB,SAAS,OAAO;EACnC,MAAM,aAAa,IAAI,iBAAiB;AACxC,qBAAmB,UAAU;AAE7B,aAAW,UAAU;AACrB,aAAW,GAAG;AACd,YAAU,EAAE,CAAC;AACb,WAAS,KAAK;AACd,iBAAe,KAAK;EAEpB,MAAM,UAAU;GACd;GACA;GACA,GAAI,YAAY,UAAU,EAAE,UAAU,YAAY,SAAS,GAAG,EAAE;GACjE;AAED,MAAI;AACF,SAAM,WAAW;IACf,KAAK;IACL;IACA,QAAQ,WAAW;IAQnB,YAAY;IACZ,WAAW,OAAO,EAAE,WAAW;AAC7B,SAAI,WAAW,OAAO,QAAS;AAC/B,SAAI,CAAC,QAAQ,SAAS,SAAU;KAChC,IAAI;AACJ,SAAI;AACF,cAAQ,KAAK,MAAM,KAAK;aAClB;AAIN;;AAEF,SAAI,CAAC,MAAM,KAAM;AAGjB,SAAI;AACF,iBAAW,UAAU,MAAM;aACrB;AAIR,gBAAW,SAAS,CAAC,GAAG,MAAM,MAAM,CAAC;AAErC,SAAI,MAAM,SAAS,mBAAmB;MACpC,MAAM,MAAM,MAAM,MAAM;AACxB,UAAI,OAAO,QAAQ,UAAU;AAC3B,mBAAY,UAAU;AACtB,mBAAY,IAAI;;gBAGlB,MAAM,SAAS,gCACf,OAAO,MAAM,UAAU,UACvB;AACA,iBAAW,WAAW,MAAM;AAC5B,iBAAW,WAAW,QAAQ;;;IAGlC,UAAU,QAAQ;AAChB,SAAI,WAAW,OAAO,QAAS;AAC/B,cAAS,eAAe,QAAQ,IAAI,UAAU,qBAAqB;;IAEtE,CAAC;WACK,KAAK;AACZ,OAAI,CAAC,WAAW,OAAO,QACrB,UAAS,eAAe,QAAQ,IAAI,UAAU,qBAAqB;YAE7D;AACR,OAAI,mBAAmB,YAAY,WACjC,oBAAmB,UAAU;AAE/B,kBAAe,MAAM;;IAGzB,CAAC,OAAO,SAAS,CAClB;AAGD,iBAAgB;AACd,eAAa;AACX,sBAAmB,SAAS,OAAO;;IAEpC,EAAE,CAAC;AAEN,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}

package/dist/react/hooks/use-analytics-query.d.ts

@@ -6,8 +6,8 @@ import { AnalyticsFormat, InferParams, InferResultByFormat, QueryKey, UseAnalyti
  * Integration hook between client and analytics plugin.
  *
  * The return type is automatically inferred based on the format:
- * - `format: "JSON"` (default): Returns typed array from QueryRegistry
- * - `format: "ARROW"`: Returns TypedArrowTable with row type preserved
+ * - `format: "JSON_ARRAY"` (default): Returns typed array from QueryRegistry
+ * - `format: "ARROW_STREAM"`: Returns TypedArrowTable with row type preserved
  *
  * Note: User context execution is determined by query file naming:
  * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)
@@ -26,11 +26,11 @@ import { AnalyticsFormat, InferParams, InferResultByFormat, QueryKey, UseAnalyti
  *
  * @example Arrow format
  * ```typescript
- * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW" });
+ * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
  * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null
  * ```
  */
-declare function useAnalyticsQuery<T = unknown, K extends QueryKey = QueryKey, F extends AnalyticsFormat = "JSON">(queryKey: K, parameters?: InferParams<K> | null, options?: UseAnalyticsQueryOptions<F>): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>>;
+declare function useAnalyticsQuery<T = unknown, K extends QueryKey = QueryKey, F extends AnalyticsFormat = "JSON_ARRAY">(queryKey: K, parameters?: InferParams<K> | null, options?: UseAnalyticsQueryOptions<F>): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>>;
 //#endregion
 export { useAnalyticsQuery };
 //# sourceMappingURL=use-analytics-query.d.ts.map

package/dist/react/hooks/use-analytics-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-analytics-query.d.ts","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"mappings":";;;;;AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,iBAAA,wBAEJ,QAAA,GAAW,QAAA,YACX,eAAA,UAAA,CAEV,QAAA,EAAU,CAAA,EACV,UAAA,GAAa,WAAA,CAAY,CAAA,UACzB,OAAA,GAAS,wBAAA,CAAyB,CAAA,IACjC,uBAAA,CAAwB,mBAAA,CAAoB,CAAA,EAAG,CAAA,EAAG,CAAA"}
+{"version":3,"file":"use-analytics-query.d.ts","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"mappings":";;;;;AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,iBAAA,wBAEJ,QAAA,GAAW,QAAA,YACX,eAAA,gBAAA,CAEV,QAAA,EAAU,CAAA,EACV,UAAA,GAAa,WAAA,CAAY,CAAA,UACzB,OAAA,GAAS,wBAAA,CAAyB,CAAA,IACjC,uBAAA,CAAwB,mBAAA,CAAoB,CAAA,EAAG,CAAA,EAAG,CAAA"}

package/dist/react/hooks/use-analytics-query.js

@@ -17,8 +17,8 @@ function getArrowStreamUrl(id) {
 * Integration hook between client and analytics plugin.
 *
 * The return type is automatically inferred based on the format:
-* - `format: "JSON"` (default): Returns typed array from QueryRegistry
-* - `format: "ARROW"`: Returns TypedArrowTable with row type preserved
+* - `format: "JSON_ARRAY"` (default): Returns typed array from QueryRegistry
+* - `format: "ARROW_STREAM"`: Returns TypedArrowTable with row type preserved
 *
 * Note: User context execution is determined by query file naming:
 * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)
@@ -37,12 +37,12 @@ function getArrowStreamUrl(id) {
 *
 * @example Arrow format
 * ```typescript
-* const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW" });
+* const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
 * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null
 * ```
 */
 function useAnalyticsQuery(queryKey, parameters, options = {}) {
-	const format = options?.format ?? "JSON";
+	const format = options?.format ?? "JSON_ARRAY";
 	const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;
 	const autoStart = options?.autoStart ?? true;
 	const devMode = getDevMode();

package/dist/react/hooks/use-analytics-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-analytics-query.js","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { ArrowClient, connectSSE } from \"@/js\";\nimport type {\n  AnalyticsFormat,\n  InferParams,\n  InferResultByFormat,\n  QueryKey,\n  UseAnalyticsQueryOptions,\n  UseAnalyticsQueryResult,\n} from \"./types\";\nimport { useQueryHMR } from \"./use-query-hmr\";\n\nfunction getDevMode() {\n  const url = new URL(window.location.href);\n  const searchParams = url.searchParams;\n  const dev = searchParams.get(\"dev\");\n\n  return dev ? `?dev=${dev}` : \"\";\n}\n\nfunction getArrowStreamUrl(id: string) {\n  return `/api/analytics/arrow-result/${id}`;\n}\n\n/**\n * Subscribe to an analytics query over SSE and returns its latest result.\n * Integration hook between client and analytics plugin.\n *\n * The return type is automatically inferred based on the format:\n * - `format: \"JSON\"` (default): Returns typed array from QueryRegistry\n * - `format: \"ARROW\"`: Returns TypedArrowTable with row type preserved\n *\n * Note: User context execution is determined by query file naming:\n * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)\n * - `queryKey.sql`: Executes as service principal\n *\n * @param queryKey - Analytics query identifier\n * @param parameters - Query parameters (type-safe based on QueryRegistry)\n * @param options - Analytics query settings including format\n * @returns Query result state with format-appropriate data type\n *\n * @example JSON format (default)\n * ```typescript\n * const { data } = useAnalyticsQuery(\"spend_data\", params);\n * // data: Array<{ group_key: string; cost_usd: number; ... }> | null\n * ```\n *\n * @example Arrow format\n * ```typescript\n * const { data } = useAnalyticsQuery(\"spend_data\", params, { format: \"ARROW\" });\n * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null\n * ```\n */\nexport function useAnalyticsQuery<\n  T = unknown,\n  K extends QueryKey = QueryKey,\n  F extends AnalyticsFormat = \"JSON\",\n>(\n  queryKey: K,\n  parameters?: InferParams<K> | null,\n  options: UseAnalyticsQueryOptions<F> = {} as UseAnalyticsQueryOptions<F>,\n): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>> {\n  const format = options?.format ?? \"JSON\";\n  const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;\n  const autoStart = options?.autoStart ?? true;\n\n  const devMode = getDevMode();\n  const urlSuffix = `/api/analytics/query/${encodeURIComponent(queryKey)}${devMode}`;\n\n  type ResultType = InferResultByFormat<T, K, F>;\n  const [data, setData] = useState<ResultType | null>(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n  const abortControllerRef = useRef<AbortController | null>(null);\n\n  if (!queryKey || queryKey.trim().length === 0) {\n    throw new Error(\n      \"useAnalyticsQuery: 'queryKey' must be a non-empty string.\",\n    );\n  }\n\n  const payload = useMemo(() => {\n    try {\n      const serialized = JSON.stringify({ parameters, format });\n      const sizeInBytes = new Blob([serialized]).size;\n      if (sizeInBytes > maxParametersSize) {\n        throw new Error(\n          \"useAnalyticsQuery: Parameters size exceeds the maximum allowed size\",\n        );\n      }\n\n      return serialized;\n    } catch (error) {\n      console.error(\"useAnalyticsQuery: Failed to serialize parameters\", error);\n      return null;\n    }\n  }, [parameters, format, maxParametersSize]);\n\n  const start = useCallback(() => {\n    if (payload === null) {\n      setError(\"Failed to serialize query parameters\");\n      return;\n    }\n\n    // Abort previous request if exists\n    if (abortControllerRef.current) {\n      abortControllerRef.current.abort();\n    }\n\n    setLoading(true);\n    setError(null);\n    setData(null);\n\n    const abortController = new AbortController();\n    abortControllerRef.current = abortController;\n\n    connectSSE({\n      url: urlSuffix,\n      payload: payload,\n      signal: abortController.signal,\n      onMessage: async (message) => {\n        try {\n          const parsed = JSON.parse(message.data);\n\n          // success - JSON format\n          if (parsed.type === \"result\") {\n            setLoading(false);\n            setData(parsed.data as ResultType);\n            return;\n          }\n\n          // success - Arrow format\n          if (parsed.type === \"arrow\") {\n            try {\n              const arrowData = await ArrowClient.fetchArrow(\n                getArrowStreamUrl(parsed.statement_id),\n              );\n              const table = await ArrowClient.processArrowBuffer(arrowData);\n              setLoading(false);\n              // Table is cast to TypedArrowTable with row type from QueryRegistry\n              setData(table as ResultType);\n              return;\n            } catch (error) {\n              console.error(\n                \"[useAnalyticsQuery] Failed to fetch Arrow data\",\n                error,\n              );\n              setLoading(false);\n              setError(\"Unable to load data, please try again\");\n              return;\n            }\n          }\n\n          // error\n          if (parsed.type === \"error\" || parsed.error || parsed.code) {\n            const errorMsg =\n              parsed.error || parsed.message || \"Unable to execute query\";\n\n            setLoading(false);\n            setError(errorMsg);\n\n            if (parsed.code) {\n              console.error(\n                `[useAnalyticsQuery] Code: ${parsed.code}, Message: ${errorMsg}`,\n              );\n            }\n            return;\n          }\n        } catch (error) {\n          console.warn(\"[useAnalyticsQuery] Malformed message received\", error);\n        }\n      },\n      onError: (error) => {\n        if (abortController.signal.aborted) return;\n        setLoading(false);\n\n        let userMessage = \"Unable to load data, please try again\";\n\n        if (error instanceof Error) {\n          if (error.name === \"AbortError\") {\n            userMessage = \"Request timed out, please try again\";\n          } else if (error.message.includes(\"Failed to fetch\")) {\n            userMessage = \"Network error. Please check your connection.\";\n          }\n\n          console.error(\"[useAnalyticsQuery] Error\", {\n            queryKey,\n            error: error.message,\n            stack: error.stack,\n          });\n        }\n        setError(userMessage);\n      },\n    });\n  }, [queryKey, payload, urlSuffix]);\n\n  useEffect(() => {\n    if (autoStart) {\n      start();\n    }\n\n    return () => {\n      abortControllerRef.current?.abort();\n    };\n  }, [start, autoStart]);\n\n  // Enable HMR for query updates in dev mode\n  useQueryHMR(queryKey, start);\n\n  return { data, loading, error };\n}\n"],"mappings":"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"}
+{"version":3,"file":"use-analytics-query.js","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { ArrowClient, connectSSE } from \"@/js\";\nimport type {\n  AnalyticsFormat,\n  InferParams,\n  InferResultByFormat,\n  QueryKey,\n  UseAnalyticsQueryOptions,\n  UseAnalyticsQueryResult,\n} from \"./types\";\nimport { useQueryHMR } from \"./use-query-hmr\";\n\nfunction getDevMode() {\n  const url = new URL(window.location.href);\n  const searchParams = url.searchParams;\n  const dev = searchParams.get(\"dev\");\n\n  return dev ? `?dev=${dev}` : \"\";\n}\n\nfunction getArrowStreamUrl(id: string) {\n  return `/api/analytics/arrow-result/${id}`;\n}\n\n/**\n * Subscribe to an analytics query over SSE and returns its latest result.\n * Integration hook between client and analytics plugin.\n *\n * The return type is automatically inferred based on the format:\n * - `format: \"JSON_ARRAY\"` (default): Returns typed array from QueryRegistry\n * - `format: \"ARROW_STREAM\"`: Returns TypedArrowTable with row type preserved\n *\n * Note: User context execution is determined by query file naming:\n * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)\n * - `queryKey.sql`: Executes as service principal\n *\n * @param queryKey - Analytics query identifier\n * @param parameters - Query parameters (type-safe based on QueryRegistry)\n * @param options - Analytics query settings including format\n * @returns Query result state with format-appropriate data type\n *\n * @example JSON format (default)\n * ```typescript\n * const { data } = useAnalyticsQuery(\"spend_data\", params);\n * // data: Array<{ group_key: string; cost_usd: number; ... }> | null\n * ```\n *\n * @example Arrow format\n * ```typescript\n * const { data } = useAnalyticsQuery(\"spend_data\", params, { format: \"ARROW_STREAM\" });\n * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null\n * ```\n */\nexport function useAnalyticsQuery<\n  T = unknown,\n  K extends QueryKey = QueryKey,\n  F extends AnalyticsFormat = \"JSON_ARRAY\",\n>(\n  queryKey: K,\n  parameters?: InferParams<K> | null,\n  options: UseAnalyticsQueryOptions<F> = {} as UseAnalyticsQueryOptions<F>,\n): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>> {\n  const format = options?.format ?? \"JSON_ARRAY\";\n  const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;\n  const autoStart = options?.autoStart ?? true;\n\n  const devMode = getDevMode();\n  const urlSuffix = `/api/analytics/query/${encodeURIComponent(queryKey)}${devMode}`;\n\n  type ResultType = InferResultByFormat<T, K, F>;\n  const [data, setData] = useState<ResultType | null>(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n  const abortControllerRef = useRef<AbortController | null>(null);\n\n  if (!queryKey || queryKey.trim().length === 0) {\n    throw new Error(\n      \"useAnalyticsQuery: 'queryKey' must be a non-empty string.\",\n    );\n  }\n\n  const payload = useMemo(() => {\n    try {\n      const serialized = JSON.stringify({ parameters, format });\n      const sizeInBytes = new Blob([serialized]).size;\n      if (sizeInBytes > maxParametersSize) {\n        throw new Error(\n          \"useAnalyticsQuery: Parameters size exceeds the maximum allowed size\",\n        );\n      }\n\n      return serialized;\n    } catch (error) {\n      console.error(\"useAnalyticsQuery: Failed to serialize parameters\", error);\n      return null;\n    }\n  }, [parameters, format, maxParametersSize]);\n\n  const start = useCallback(() => {\n    if (payload === null) {\n      setError(\"Failed to serialize query parameters\");\n      return;\n    }\n\n    // Abort previous request if exists\n    if (abortControllerRef.current) {\n      abortControllerRef.current.abort();\n    }\n\n    setLoading(true);\n    setError(null);\n    setData(null);\n\n    const abortController = new AbortController();\n    abortControllerRef.current = abortController;\n\n    connectSSE({\n      url: urlSuffix,\n      payload: payload,\n      signal: abortController.signal,\n      onMessage: async (message) => {\n        try {\n          const parsed = JSON.parse(message.data);\n\n          // success - JSON format\n          if (parsed.type === \"result\") {\n            setLoading(false);\n            setData(parsed.data as ResultType);\n            return;\n          }\n\n          // success - Arrow format\n          if (parsed.type === \"arrow\") {\n            try {\n              const arrowData = await ArrowClient.fetchArrow(\n                getArrowStreamUrl(parsed.statement_id),\n              );\n              const table = await ArrowClient.processArrowBuffer(arrowData);\n              setLoading(false);\n              // Table is cast to TypedArrowTable with row type from QueryRegistry\n              setData(table as ResultType);\n              return;\n            } catch (error) {\n              console.error(\n                \"[useAnalyticsQuery] Failed to fetch Arrow data\",\n                error,\n              );\n              setLoading(false);\n              setError(\"Unable to load data, please try again\");\n              return;\n            }\n          }\n\n          // error\n          if (parsed.type === \"error\" || parsed.error || parsed.code) {\n            const errorMsg =\n              parsed.error || parsed.message || \"Unable to execute query\";\n\n            setLoading(false);\n            setError(errorMsg);\n\n            if (parsed.code) {\n              console.error(\n                `[useAnalyticsQuery] Code: ${parsed.code}, Message: ${errorMsg}`,\n              );\n            }\n            return;\n          }\n        } catch (error) {\n          console.warn(\"[useAnalyticsQuery] Malformed message received\", error);\n        }\n      },\n      onError: (error) => {\n        if (abortController.signal.aborted) return;\n        setLoading(false);\n\n        let userMessage = \"Unable to load data, please try again\";\n\n        if (error instanceof Error) {\n          if (error.name === \"AbortError\") {\n            userMessage = \"Request timed out, please try again\";\n          } else if (error.message.includes(\"Failed to fetch\")) {\n            userMessage = \"Network error. Please check your connection.\";\n          }\n\n          console.error(\"[useAnalyticsQuery] Error\", {\n            queryKey,\n            error: error.message,\n            stack: error.stack,\n          });\n        }\n        setError(userMessage);\n      },\n    });\n  }, [queryKey, payload, urlSuffix]);\n\n  useEffect(() => {\n    if (autoStart) {\n      start();\n    }\n\n    return () => {\n      abortControllerRef.current?.abort();\n    };\n  }, [start, autoStart]);\n\n  // Enable HMR for query updates in dev mode\n  useQueryHMR(queryKey, start);\n\n  return { data, loading, error };\n}\n"],"mappings":"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"}