@databricks/appkit 0.31.0 → 0.33.0

package/dist/core/agent/tools/tool.d.ts

@@ -0,0 +1,63 @@
+import { ToolAnnotations } from "../../../shared/src/agent.js";
+import "../../../shared/src/index.js";
+import { FunctionTool } from "./function-tool.js";
+import { z } from "zod";
+
+//#region src/core/agent/tools/tool.d.ts
+interface ToolConfig<S extends z.ZodType> {
+  /**
+   * Optional. When the tool is placed in a keyed record (the standard
+   * `tools: { my_tool: tool({...}) }` form, or the function form
+   * `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin
+   * overrides the tool's LLM-visible name with the record key. Set
+   * `name` explicitly only if you're constructing a `FunctionTool`
+   * outside any keyed-record context — otherwise the record key wins.
+   */
+  name?: string;
+  /**
+   * What the tool does, what it expects, and when the LLM should call it.
+   * The model reads this verbatim when deciding whether to invoke the tool,
+   * so write it for an LLM, not for a human reader of your code: spell out
+   * the inputs, the return shape, and any pre-conditions or side effects.
+   *
+   * Required. Earlier versions silently fell back to the tool's name when
+   * omitted, which surfaced cryptic identifiers like `"get_weather"` as the
+   * description — the model then had no signal about expected use and
+   * either skipped the tool or called it speculatively. Making this
+   * mandatory at the type level forces a real description at authoring
+   * time instead of debugging a confused agent later.
+   */
+  description: string;
+  schema: S;
+  /**
+   * Behavioural hints forwarded to the resolved tool definition. Prefer
+   * `effect` (`"read" | "write" | "update" | "destructive"`) — any mutating
+   * value forces the agents-plugin approval gate before `execute()` runs
+   * and the client's approval card will colour itself accordingly. Legacy
+   * `destructive: true` still gates. Dropped silently before the fix that
+   * added this field.
+   */
+  annotations?: ToolAnnotations;
+  /**
+   * Returning a non-string value is fine: the agent runtime serializes
+   * the result via `normalizeToolResult` before handing it to the LLM
+   * (strings pass through; `null` becomes `"null"`; everything else gets
+   * `JSON.stringify`'d; `undefined` becomes `""`). Return whatever shape
+   * is most natural for your tool — typically an object — and let the
+   * runtime handle the wire format.
+   */
+  execute: (args: z.infer<S>) => unknown | Promise<unknown>;
+}
+/**
+ * Factory for defining function tools with Zod schemas.
+ *
+ * - Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.
+ * - Infers the `execute` argument type from the schema.
+ * - Validates tool call arguments at runtime. On validation failure, returns
+ *   a formatted error string to the LLM instead of throwing, so the model
+ *   can self-correct on its next turn.
+ */
+declare function tool<S extends z.ZodType>(config: ToolConfig<S>): FunctionTool;
+//#endregion
+export { ToolConfig, tool };
+//# sourceMappingURL=tool.d.ts.map

package/dist/core/agent/tools/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"mappings":";;;;;;UAKiB,UAAA,WAAqB,CAAA,CAAE,OAAA;;;AAAxC;;;;;;EASE,IAAA;EAiCkB;;;;;;;;;;;;;EAnBlB,WAAA;EACA,MAAA,EAAQ,CAAA;EAkBU;;;;;;AAYpB;;EArBE,WAAA,GAAc,eAAA;EAqBiB;;;;;;;;EAZ/B,OAAA,GAAU,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,gBAAiB,OAAA;AAAA;;;;;;;;;;iBAY3B,IAAA,WAAe,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,UAAA,CAAW,CAAA,IAAK,YAAA"}

package/dist/core/agent/tools/tool.js

@@ -0,0 +1,42 @@
+import { toToolJSONSchema } from "./json-schema.js";
+
+//#region src/core/agent/tools/tool.ts
+/**
+* Factory for defining function tools with Zod schemas.
+*
+* - Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.
+* - Infers the `execute` argument type from the schema.
+* - Validates tool call arguments at runtime. On validation failure, returns
+*   a formatted error string to the LLM instead of throwing, so the model
+*   can self-correct on its next turn.
+*/
+function tool(config) {
+	const parameters = toToolJSONSchema(config.schema);
+	const labelForErrors = config.name ?? "tool";
+	return {
+		type: "function",
+		...config.name !== void 0 ? { name: config.name } : {},
+		description: config.description,
+		parameters,
+		...config.annotations ? { annotations: config.annotations } : {},
+		execute: async (args) => {
+			const parsed = config.schema.safeParse(args);
+			if (!parsed.success) return formatZodError(parsed.error, labelForErrors);
+			return config.execute(parsed.data);
+		}
+	};
+}
+/**
+* Formats a Zod validation error into an LLM-friendly string.
+*
+* Example: `Invalid arguments for get_weather: city: Invalid input: expected string, received undefined`
+*/
+function formatZodError(error, toolName) {
+	return `Invalid arguments for ${toolName}: ${error.issues.map((issue) => {
+		return `${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
+	}).join("; ")}`;
+}
+
+//#endregion
+export { formatZodError, tool };
+//# sourceMappingURL=tool.js.map

package/dist/core/agent/tools/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","names":[],"sources":["../../../../src/core/agent/tools/tool.ts"],"sourcesContent":["import type { ToolAnnotations } from \"shared\";\nimport type { z } from \"zod\";\nimport type { FunctionTool } from \"./function-tool\";\nimport { toToolJSONSchema } from \"./json-schema\";\n\nexport interface ToolConfig<S extends z.ZodType> {\n  /**\n   * Optional. When the tool is placed in a keyed record (the standard\n   * `tools: { my_tool: tool({...}) }` form, or the function form\n   * `tools(plugins) => ({ my_tool: tool({...}) })`), the agents plugin\n   * overrides the tool's LLM-visible name with the record key. Set\n   * `name` explicitly only if you're constructing a `FunctionTool`\n   * outside any keyed-record context — otherwise the record key wins.\n   */\n  name?: string;\n  /**\n   * What the tool does, what it expects, and when the LLM should call it.\n   * The model reads this verbatim when deciding whether to invoke the tool,\n   * so write it for an LLM, not for a human reader of your code: spell out\n   * the inputs, the return shape, and any pre-conditions or side effects.\n   *\n   * Required. Earlier versions silently fell back to the tool's name when\n   * omitted, which surfaced cryptic identifiers like `\"get_weather\"` as the\n   * description — the model then had no signal about expected use and\n   * either skipped the tool or called it speculatively. Making this\n   * mandatory at the type level forces a real description at authoring\n   * time instead of debugging a confused agent later.\n   */\n  description: string;\n  schema: S;\n  /**\n   * Behavioural hints forwarded to the resolved tool definition. Prefer\n   * `effect` (`\"read\" | \"write\" | \"update\" | \"destructive\"`) — any mutating\n   * value forces the agents-plugin approval gate before `execute()` runs\n   * and the client's approval card will colour itself accordingly. Legacy\n   * `destructive: true` still gates. Dropped silently before the fix that\n   * added this field.\n   */\n  annotations?: ToolAnnotations;\n  /**\n   * Returning a non-string value is fine: the agent runtime serializes\n   * the result via `normalizeToolResult` before handing it to the LLM\n   * (strings pass through; `null` becomes `\"null\"`; everything else gets\n   * `JSON.stringify`'d; `undefined` becomes `\"\"`). Return whatever shape\n   * is most natural for your tool — typically an object — and let the\n   * runtime handle the wire format.\n   */\n  execute: (args: z.infer<S>) => unknown | Promise<unknown>;\n}\n\n/**\n * Factory for defining function tools with Zod schemas.\n *\n * - Generates JSON Schema (for the LLM) from the Zod schema via `z.toJSONSchema()`.\n * - Infers the `execute` argument type from the schema.\n * - Validates tool call arguments at runtime. On validation failure, returns\n *   a formatted error string to the LLM instead of throwing, so the model\n *   can self-correct on its next turn.\n */\nexport function tool<S extends z.ZodType>(config: ToolConfig<S>): FunctionTool {\n  const parameters = toToolJSONSchema(config.schema);\n\n  // `name` is only used for the zod-validation error message and the\n  // FunctionTool's `name` field; the agents plugin overrides the latter\n  // with the record key (`tools: { my_tool: ... }` -> \"my_tool\") at\n  // index-build time. Fall back to a generic label so errors are still\n  // legible when `name` is omitted.\n  const labelForErrors = config.name ?? \"tool\";\n\n  return {\n    type: \"function\",\n    ...(config.name !== undefined ? { name: config.name } : {}),\n    description: config.description,\n    parameters,\n    ...(config.annotations ? { annotations: config.annotations } : {}),\n    execute: async (args: Record<string, unknown>) => {\n      const parsed = config.schema.safeParse(args);\n      if (!parsed.success) {\n        return formatZodError(parsed.error, labelForErrors);\n      }\n      return config.execute(parsed.data as z.infer<S>);\n    },\n  };\n}\n\n/**\n * Formats a Zod validation error into an LLM-friendly string.\n *\n * Example: `Invalid arguments for get_weather: city: Invalid input: expected string, received undefined`\n */\nexport function formatZodError(error: z.ZodError, toolName: string): string {\n  const parts = error.issues.map((issue) => {\n    const field = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n    return `${field}: ${issue.message}`;\n  });\n  return `Invalid arguments for ${toolName}: ${parts.join(\"; \")}`;\n}\n"],"mappings":";;;;;;;;;;;;AA2DA,SAAgB,KAA0B,QAAqC;CAC7E,MAAM,aAAa,iBAAiB,OAAO,OAAO;CAOlD,MAAM,iBAAiB,OAAO,QAAQ;AAEtC,QAAO;EACL,MAAM;EACN,GAAI,OAAO,SAAS,SAAY,EAAE,MAAM,OAAO,MAAM,GAAG,EAAE;EAC1D,aAAa,OAAO;EACpB;EACA,GAAI,OAAO,cAAc,EAAE,aAAa,OAAO,aAAa,GAAG,EAAE;EACjE,SAAS,OAAO,SAAkC;GAChD,MAAM,SAAS,OAAO,OAAO,UAAU,KAAK;AAC5C,OAAI,CAAC,OAAO,QACV,QAAO,eAAe,OAAO,OAAO,eAAe;AAErD,UAAO,OAAO,QAAQ,OAAO,KAAmB;;EAEnD;;;;;;;AAQH,SAAgB,eAAe,OAAmB,UAA0B;AAK1E,QAAO,yBAAyB,SAAS,IAJ3B,MAAM,OAAO,KAAK,UAAU;AAExC,SAAO,GADO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,SAC7C,IAAI,MAAM;GAC1B,CACiD,KAAK,KAAK"}

package/dist/core/agent/types.d.ts

@@ -0,0 +1,299 @@
+import { AgentAdapter, AgentToolDefinition, ThreadStore, ToolAnnotations } from "../../shared/src/agent.js";
+import { BasePluginConfig } from "../../shared/src/plugin.js";
+import "../../shared/src/index.js";
+import { McpHostPolicyConfig } from "../../connectors/mcp/host-policy.js";
+import "../../connectors/mcp/index.js";
+import { FunctionTool } from "./tools/function-tool.js";
+import { HostedTool } from "./tools/hosted-tools.js";
+
+//#region src/core/agent/types.d.ts
+/**
+ * A tool reference produced by a plugin's `.toolkit()` call. The agents plugin
+ * recognizes the `__toolkitRef` brand and dispatches tool invocations through
+ * `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving
+ * OBO (asUser) and telemetry spans.
+ */
+interface ToolkitEntry {
+  readonly __toolkitRef: true;
+  pluginName: string;
+  localName: string;
+  def: AgentToolDefinition;
+  annotations?: ToolAnnotations;
+  /**
+   * Whether this tool is eligible for `autoInheritTools` spreading. Mirrors
+   * {@link ToolEntry.autoInheritable} from the source registry so the agents
+   * plugin can filter auto-inherited tools without re-walking the provider's
+   * internal registry.
+   */
+  autoInheritable?: boolean;
+}
+/**
+ * Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP
+ * tools (`mcpServer()` / raw hosted), or toolkit references from plugins
+ * (`analytics().toolkit()`).
+ */
+type AgentTool = FunctionTool | HostedTool | ToolkitEntry;
+interface ToolkitOptions {
+  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */
+  prefix?: string;
+  /** Only include tools whose local name matches one of these. */
+  only?: string[];
+  /** Exclude tools whose local name matches one of these. */
+  except?: string[];
+  /** Remap specific local names to different keys (applied after prefix). */
+  rename?: Record<string, string>;
+}
+/**
+ * Minimum shape every entry in the {@link Plugins} map must expose. Core
+ * plugins (analytics, files, genie, lakebase) implement this directly via
+ * their `.toolkit()` method. The agents plugin and standalone `runAgent`
+ * synthesize this shape for any registered plugin that doesn't implement
+ * `.toolkit()` directly (falling back to `getAgentTools()` walking).
+ */
+interface PluginToolkitProvider {
+  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;
+}
+/**
+ * Plugin map passed to the function form of {@link AgentDefinition.tools}.
+ * Each entry exposes a `.toolkit(opts?)` method that returns a record of
+ * {@link ToolkitEntry} markers ready to be spread into a tool record.
+ *
+ * AppKit does not statically know which plugins the surrounding
+ * `createApp` will register, so this is a plain string-keyed record.
+ * Refer to plugins by the name used in `createApp({ plugins: [...] })`;
+ * unknown names resolve to `undefined` at runtime.
+ *
+ * @example
+ * ```ts
+ * const support = createAgent({
+ *   instructions: "...",
+ *   tools(plugins) {
+ *     return {
+ *       get_weather: tool({ ... }),
+ *       ...plugins.analytics.toolkit(),
+ *       ...plugins.files.toolkit({ only: ["uploads.read"] }),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+type Plugins = Record<string, PluginToolkitProvider>;
+/**
+ * Context passed to `baseSystemPrompt` callbacks.
+ */
+interface PromptContext {
+  agentName: string;
+  pluginNames: string[];
+  toolNames: string[];
+}
+type BaseSystemPromptOption = false | string | ((ctx: PromptContext) => string);
+/**
+ * Per-agent tool record. String keys map to inline tools, toolkit entries,
+ * hosted tools, etc.
+ */
+type AgentTools = Record<string, AgentTool>;
+/**
+ * Function form of `AgentDefinition.tools`. Receives the typed
+ * {@link Plugins} map and returns a tool record. Invoked exactly once at
+ * setup (or once per `runAgent` call in standalone mode); the result is
+ * cached as the agent's resolved tool record.
+ *
+ * Use the function form when an agent needs tools from registered plugins.
+ * The bare object form is fine when an agent only uses inline tools.
+ */
+type AgentToolsFn = (plugins: Plugins) => AgentTools;
+interface AgentDefinition {
+  /**
+   * Stable identifier for the agent. **Optional and informational** —
+   * when the definition is registered via `agents: { foo: def }` (code) or
+   * lives at `config/agents/<id>/agent.md` (markdown), the **registry key
+   * always wins** and `name` is ignored. The agent will be reachable as
+   * `foo` (or `<id>`) regardless of what this field contains.
+   *
+   * Set `name` when:
+   *   - Running standalone via `runAgent({ agent: def })`, where there is
+   *     no enclosing key. The runtime uses it for the agent's slot in
+   *     error messages and OTel spans.
+   *   - Building a definition that may be passed to either form and you
+   *     want a consistent fallback label.
+   *
+   * Setting `name` to a value that differs from the registry key is
+   * harmless but confusing — prefer keeping them aligned or omitting `name`
+   * entirely.
+   */
+  name?: string;
+  /** System prompt body. For markdown-loaded agents this is the file body. */
+  instructions: string;
+  /**
+   * Model adapter (or endpoint-name string sugar for
+   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —
+   * falls back to the plugin's `defaultModel`.
+   */
+  model?: AgentAdapter | Promise<AgentAdapter> | string;
+  /**
+   * Per-agent tool record. Key is the LLM-visible tool-call name.
+   *
+   * Accepts either a plain record (for agents that only use inline tools)
+   * or a function `(plugins) => Record<string, AgentTool>` that receives
+   * the typed {@link Plugins} map and returns a tool record (for agents
+   * that pull tools from registered plugins).
+   *
+   * The function is invoked once at agent setup; the result is cached.
+   * Don't put per-request logic in there.
+   */
+  tools?: AgentTools | AgentToolsFn;
+  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */
+  agents?: Record<string, AgentDefinition>;
+  /** Override the plugin's baseSystemPrompt for this agent only. */
+  baseSystemPrompt?: BaseSystemPromptOption;
+  maxSteps?: number;
+  maxTokens?: number;
+  /**
+   * When true, the thread used for a chat request against this agent is
+   * deleted from `ThreadStore` after the stream completes (success or
+   * failure). Use for stateless one-shot agents — e.g. autocomplete, where
+   * each request is independent and retaining history would both poison
+   * future calls and accumulate unbounded state in the default
+   * `InMemoryThreadStore`. Defaults to `false`.
+   */
+  ephemeral?: boolean;
+}
+/**
+ * Auto-inherit configuration. When enabled for a given agent origin, agents
+ * with no explicit `tools:` declaration receive every registered ToolProvider
+ * plugin tool whose author marked `autoInheritable: true`. Tools without that
+ * flag — destructive, state-mutating, or privilege-sensitive — never spread
+ * automatically and must be wired via `tools:` (object or function form in
+ * code, `plugin:NAME` entries in markdown frontmatter).
+ *
+ * Defaults are `false` for both origins (safe-by-default): developers must
+ * consciously opt an origin in to any auto-inherit behaviour.
+ */
+interface AutoInheritToolsConfig {
+  /** Default for agents loaded from markdown files. Default: `false`. */
+  file?: boolean;
+  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */
+  code?: boolean;
+}
+interface AgentsPluginConfig extends BasePluginConfig {
+  /** Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable. */
+  dir?: string | false;
+  /** Code-defined agents, merged with file-loaded ones (code wins on key collision). */
+  agents?: Record<string, AgentDefinition>;
+  /** Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter. */
+  defaultAgent?: string;
+  /** Default model for agents that don't specify their own (in code or frontmatter). */
+  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string;
+  /** Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`. */
+  tools?: Record<string, AgentTool>;
+  /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */
+  autoInheritTools?: boolean | AutoInheritToolsConfig;
+  /** Persistent thread store. Default: in-memory. */
+  threadStore?: ThreadStore;
+  /** Customize or disable the AppKit base system prompt. */
+  baseSystemPrompt?: BaseSystemPromptOption;
+  /**
+   * MCP server host policy. By default only same-origin Databricks workspace
+   * URLs may be used as MCP endpoints; custom hosts must be explicitly
+   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded
+   * to non-workspace hosts.
+   */
+  mcp?: McpHostPolicyConfig;
+  /**
+   * Human-in-the-loop approval gate for mutating tool calls. When enabled
+   * (the default), the agents plugin emits an `appkit.approval_pending` SSE
+   * event before executing any tool whose annotation flags it as mutating —
+   * `effect: "write" | "update" | "destructive"` (preferred) or the legacy
+   * `destructive: true` boolean — and waits for a `POST /chat/approve`
+   * decision from the same user who initiated the stream. A missing decision
+   * after `timeoutMs` auto-denies the call.
+   */
+  approval?: {
+    /**
+     * Require human approval for tools that mutate state. Triggered by
+     * `effect: "write" | "update" | "destructive"` (preferred) or the legacy
+     * `destructive: true` boolean. Default: `true`.
+     */
+    requireForDestructive?: boolean; /** Milliseconds to wait before auto-denying. Default: 60_000. */
+    timeoutMs?: number;
+  };
+  /**
+   * Runtime resource limits applied during agent execution. Defaults are
+   * tuned to protect a single-instance deployment from a misbehaving user or
+   * a runaway prompt injection; tighten or relax as appropriate for the
+   * deployment's scale and trust model. Request-body caps (chat message
+   * size, invocations input size / length) are enforced statically by the
+   * Zod schemas and are not configurable here.
+   */
+  limits?: {
+    /**
+     * Max concurrent chat streams a single user may have open. Subsequent
+     * `POST /chat` requests from that user while at-limit are rejected with
+     * HTTP 429. Default: `5`.
+     */
+    maxConcurrentStreamsPerUser?: number;
+    /**
+     * Max tool invocations per agent run (across the full tool-call graph,
+     * including sub-agent invocations). A run that exceeds the budget is
+     * aborted with a terminal error event. Default: `50`.
+     */
+    maxToolCalls?: number;
+    /**
+     * Max sub-agent recursion depth. Protects against a prompt-injected
+     * agent that delegates to a sub-agent which in turn delegates back to
+     * itself (directly or transitively). Default: `3`.
+     */
+    maxSubAgentDepth?: number;
+    /**
+     * Per-call timeout for tools dispatched through `PluginContext`
+     * (toolkit-routed tools — analytics SQL warehouse queries, Genie
+     * messages, Lakebase queries). Independent of `maxToolCalls`: the
+     * budget caps how many tools fire per run, this caps how long any
+     * single tool call may run. The signal handed to plugin tool
+     * implementations combines this timeout with the parent stream's
+     * abort signal via `AbortSignal.any`. Function and MCP tools have
+     * their own timeouts in their respective adapters and ignore this
+     * setting. Default: `300_000` (5 minutes) — generous enough for cold
+     * SQL Warehouse round-trips and long Genie conversations.
+     */
+    toolCallTimeoutMs?: number;
+  };
+}
+/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */
+type ResolvedToolEntry = {
+  source: "toolkit";
+  pluginName: string;
+  localName: string;
+  def: AgentToolDefinition;
+} | {
+  source: "function";
+  functionTool: FunctionTool;
+  def: AgentToolDefinition;
+} | {
+  source: "mcp";
+  mcpToolName: string;
+  def: AgentToolDefinition;
+} | {
+  source: "subagent";
+  agentName: string;
+  def: AgentToolDefinition;
+};
+interface RegisteredAgent {
+  name: string;
+  instructions: string;
+  adapter: AgentAdapter;
+  toolIndex: Map<string, ResolvedToolEntry>;
+  baseSystemPrompt?: BaseSystemPromptOption;
+  maxSteps?: number;
+  maxTokens?: number;
+  /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */
+  ephemeral?: boolean;
+}
+/**
+ * Type guard for `ToolkitEntry` — used by the agents plugin to differentiate
+ * toolkit references from inline tools in a mixed `tools` record.
+ */
+declare function isToolkitEntry(value: unknown): value is ToolkitEntry;
+//#endregion
+export { AgentDefinition, AgentTool, AgentTools, AgentToolsFn, AgentsPluginConfig, AutoInheritToolsConfig, BaseSystemPromptOption, PluginToolkitProvider, Plugins, PromptContext, RegisteredAgent, ResolvedToolEntry, ToolkitEntry, ToolkitOptions, isToolkitEntry };
+//# sourceMappingURL=types.d.ts.map

package/dist/core/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":";;;;;;;;;;;;;;AAiBA;UAAiB,YAAA;EAAA,SACN,YAAA;EACT,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;EACL,WAAA,GAAc,eAAA;EADd;;;;;;EAQA,eAAA;AAAA;;;;;;KAQU,SAAA,GAAY,YAAA,GAAe,UAAA,GAAa,YAAA;AAAA,UAEnC,cAAA;EAFO;EAItB,MAAA;EAJkD;EAMlD,IAAA;EAN8D;EAQ9D,MAAA;EAN6B;EAQ7B,MAAA,GAAS,MAAA;AAAA;;;;;;;;UAUM,qBAAA;EACf,OAAA,CAAQ,IAAA,GAAO,cAAA,GAAiB,MAAA,SAAe,YAAA;AAAA;;;;;;;;;;;;;AA2BjD;;;;;AAKA;;;;;;;KALY,OAAA,GAAU,MAAA,SAAe,qBAAA;;AAWrC;;UANiB,aAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,KAGU,sBAAA,sBAGN,GAAA,EAAK,aAAA;;;AAiBX;;KAXY,UAAA,GAAa,MAAA,SAAe,SAAA;;;;;;;AAaxC;;;KAFY,YAAA,IAAgB,OAAA,EAAS,OAAA,KAAY,UAAA;AAAA,UAEhC,eAAA;EA2BQ;;;;;;;;;;;;;;;;;;EARvB,IAAA;EAsBwB;EApBxB,YAAA;EAsBmB;;;;;EAhBnB,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAyChB;;;;;AAOjB;;;;;;EApCE,KAAA,GAAQ,UAAA,GAAa,YAAA;EA4CS;EA1C9B,MAAA,GAAS,MAAA,SAAe,eAAA;EA4ChB;EA1CR,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EAqDM;;;;;;;;EA5CN,SAAA;AAAA;;;;;;;;;;;;UAce,sBAAA;EAuBI;EArBnB,IAAA;EA4BM;EA1BN,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;EAmD1C;EAjDA,GAAA;EA6DE;EA3DF,MAAA,GAAS,MAAA,SAAe,eAAA;EA8EtB;EA5EF,YAAA;EA4EmB;EA1EnB,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EA+EX;EA7E3B,KAAA,GAAQ,MAAA,SAAe,SAAA;EAkFd;EAhFT,gBAAA,aAA6B,sBAAA;EAqFpB;EAnFT,WAAA,GAAc,WAAA;EA6FL;EA3FT,gBAAA,GAAmB,sBAAA;EA2FS;;;;;;EApF5B,GAAA,GAAM,mBAAA;EAyEF;;;;;;;;;EA/DJ,QAAA;IA0EI;;;;AAGN;IAvEI,qBAAA,YAuE4B;IArE5B,SAAA;EAAA;EAyES;;;;;;;;EA/DX,MAAA;IA+DW;;;;;IAzDT,2BAAA;IA8DF;;;AAOF;;IA/DI,YAAA;IA+DiE;;;;;IAzDjE,gBAAA;;;;;;;;;;;;;IAaA,iBAAA;EAAA;AAAA;;KAKQ,iBAAA;EAEN,MAAA;EACA,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,YAAA,EAAc,YAAA;EACd,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,WAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;AAAA,UAGM,eAAA;EACf,IAAA;EACA,YAAA;EACA,OAAA,EAAS,YAAA;EACT,SAAA,EAAW,GAAA,SAAY,iBAAA;EACvB,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;;EAEA,SAAA;AAAA;;;;;iBAOc,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA"}

package/dist/core/agent/types.js

@@ -0,0 +1,12 @@
+//#region src/core/agent/types.ts
+/**
+* Type guard for `ToolkitEntry` — used by the agents plugin to differentiate
+* toolkit references from inline tools in a mixed `tools` record.
+*/
+function isToolkitEntry(value) {
+	return typeof value === "object" && value !== null && value.__toolkitRef === true;
+}
+
+//#endregion
+export { isToolkitEntry };
+//# sourceMappingURL=types.js.map

package/dist/core/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/core/agent/types.ts"],"sourcesContent":["import type {\n  AgentAdapter,\n  AgentToolDefinition,\n  BasePluginConfig,\n  ThreadStore,\n  ToolAnnotations,\n} from \"shared\";\nimport type { McpHostPolicyConfig } from \"../../connectors/mcp\";\nimport type { FunctionTool } from \"./tools/function-tool\";\nimport type { HostedTool } from \"./tools/hosted-tools\";\n\n/**\n * A tool reference produced by a plugin's `.toolkit()` call. The agents plugin\n * recognizes the `__toolkitRef` brand and dispatches tool invocations through\n * `PluginContext.executeTool(req, pluginName, localName, ...)`, preserving\n * OBO (asUser) and telemetry spans.\n */\nexport interface ToolkitEntry {\n  readonly __toolkitRef: true;\n  pluginName: string;\n  localName: string;\n  def: AgentToolDefinition;\n  annotations?: ToolAnnotations;\n  /**\n   * Whether this tool is eligible for `autoInheritTools` spreading. Mirrors\n   * {@link ToolEntry.autoInheritable} from the source registry so the agents\n   * plugin can filter auto-inherited tools without re-walking the provider's\n   * internal registry.\n   */\n  autoInheritable?: boolean;\n}\n\n/**\n * Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP\n * tools (`mcpServer()` / raw hosted), or toolkit references from plugins\n * (`analytics().toolkit()`).\n */\nexport type AgentTool = FunctionTool | HostedTool | ToolkitEntry;\n\nexport interface ToolkitOptions {\n  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */\n  prefix?: string;\n  /** Only include tools whose local name matches one of these. */\n  only?: string[];\n  /** Exclude tools whose local name matches one of these. */\n  except?: string[];\n  /** Remap specific local names to different keys (applied after prefix). */\n  rename?: Record<string, string>;\n}\n\n/**\n * Minimum shape every entry in the {@link Plugins} map must expose. Core\n * plugins (analytics, files, genie, lakebase) implement this directly via\n * their `.toolkit()` method. The agents plugin and standalone `runAgent`\n * synthesize this shape for any registered plugin that doesn't implement\n * `.toolkit()` directly (falling back to `getAgentTools()` walking).\n */\nexport interface PluginToolkitProvider {\n  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;\n}\n\n/**\n * Plugin map passed to the function form of {@link AgentDefinition.tools}.\n * Each entry exposes a `.toolkit(opts?)` method that returns a record of\n * {@link ToolkitEntry} markers ready to be spread into a tool record.\n *\n * AppKit does not statically know which plugins the surrounding\n * `createApp` will register, so this is a plain string-keyed record.\n * Refer to plugins by the name used in `createApp({ plugins: [...] })`;\n * unknown names resolve to `undefined` at runtime.\n *\n * @example\n * ```ts\n * const support = createAgent({\n *   instructions: \"...\",\n *   tools(plugins) {\n *     return {\n *       get_weather: tool({ ... }),\n *       ...plugins.analytics.toolkit(),\n *       ...plugins.files.toolkit({ only: [\"uploads.read\"] }),\n *     };\n *   },\n * });\n * ```\n */\nexport type Plugins = Record<string, PluginToolkitProvider>;\n\n/**\n * Context passed to `baseSystemPrompt` callbacks.\n */\nexport interface PromptContext {\n  agentName: string;\n  pluginNames: string[];\n  toolNames: string[];\n}\n\nexport type BaseSystemPromptOption =\n  | false\n  | string\n  | ((ctx: PromptContext) => string);\n\n/**\n * Per-agent tool record. String keys map to inline tools, toolkit entries,\n * hosted tools, etc.\n */\nexport type AgentTools = Record<string, AgentTool>;\n\n/**\n * Function form of `AgentDefinition.tools`. Receives the typed\n * {@link Plugins} map and returns a tool record. Invoked exactly once at\n * setup (or once per `runAgent` call in standalone mode); the result is\n * cached as the agent's resolved tool record.\n *\n * Use the function form when an agent needs tools from registered plugins.\n * The bare object form is fine when an agent only uses inline tools.\n */\nexport type AgentToolsFn = (plugins: Plugins) => AgentTools;\n\nexport interface AgentDefinition {\n  /**\n   * Stable identifier for the agent. **Optional and informational** —\n   * when the definition is registered via `agents: { foo: def }` (code) or\n   * lives at `config/agents/<id>/agent.md` (markdown), the **registry key\n   * always wins** and `name` is ignored. The agent will be reachable as\n   * `foo` (or `<id>`) regardless of what this field contains.\n   *\n   * Set `name` when:\n   *   - Running standalone via `runAgent({ agent: def })`, where there is\n   *     no enclosing key. The runtime uses it for the agent's slot in\n   *     error messages and OTel spans.\n   *   - Building a definition that may be passed to either form and you\n   *     want a consistent fallback label.\n   *\n   * Setting `name` to a value that differs from the registry key is\n   * harmless but confusing — prefer keeping them aligned or omitting `name`\n   * entirely.\n   */\n  name?: string;\n  /** System prompt body. For markdown-loaded agents this is the file body. */\n  instructions: string;\n  /**\n   * Model adapter (or endpoint-name string sugar for\n   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —\n   * falls back to the plugin's `defaultModel`.\n   */\n  model?: AgentAdapter | Promise<AgentAdapter> | string;\n  /**\n   * Per-agent tool record. Key is the LLM-visible tool-call name.\n   *\n   * Accepts either a plain record (for agents that only use inline tools)\n   * or a function `(plugins) => Record<string, AgentTool>` that receives\n   * the typed {@link Plugins} map and returns a tool record (for agents\n   * that pull tools from registered plugins).\n   *\n   * The function is invoked once at agent setup; the result is cached.\n   * Don't put per-request logic in there.\n   */\n  tools?: AgentTools | AgentToolsFn;\n  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */\n  agents?: Record<string, AgentDefinition>;\n  /** Override the plugin's baseSystemPrompt for this agent only. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /**\n   * When true, the thread used for a chat request against this agent is\n   * deleted from `ThreadStore` after the stream completes (success or\n   * failure). Use for stateless one-shot agents — e.g. autocomplete, where\n   * each request is independent and retaining history would both poison\n   * future calls and accumulate unbounded state in the default\n   * `InMemoryThreadStore`. Defaults to `false`.\n   */\n  ephemeral?: boolean;\n}\n\n/**\n * Auto-inherit configuration. When enabled for a given agent origin, agents\n * with no explicit `tools:` declaration receive every registered ToolProvider\n * plugin tool whose author marked `autoInheritable: true`. Tools without that\n * flag — destructive, state-mutating, or privilege-sensitive — never spread\n * automatically and must be wired via `tools:` (object or function form in\n * code, `plugin:NAME` entries in markdown frontmatter).\n *\n * Defaults are `false` for both origins (safe-by-default): developers must\n * consciously opt an origin in to any auto-inherit behaviour.\n */\nexport interface AutoInheritToolsConfig {\n  /** Default for agents loaded from markdown files. Default: `false`. */\n  file?: boolean;\n  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */\n  code?: boolean;\n}\n\nexport interface AgentsPluginConfig extends BasePluginConfig {\n  /** Directory of agent packages (`<id>/agent.md` each). Default `./config/agents`. Set to `false` to disable. */\n  dir?: string | false;\n  /** Code-defined agents, merged with file-loaded ones (code wins on key collision). */\n  agents?: Record<string, AgentDefinition>;\n  /** Agent used when clients don't specify one. Defaults to the first-registered agent or the file with `default: true` frontmatter. */\n  defaultAgent?: string;\n  /** Default model for agents that don't specify their own (in code or frontmatter). */\n  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string;\n  /** Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`. */\n  tools?: Record<string, AgentTool>;\n  /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */\n  autoInheritTools?: boolean | AutoInheritToolsConfig;\n  /** Persistent thread store. Default: in-memory. */\n  threadStore?: ThreadStore;\n  /** Customize or disable the AppKit base system prompt. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  /**\n   * MCP server host policy. By default only same-origin Databricks workspace\n   * URLs may be used as MCP endpoints; custom hosts must be explicitly\n   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded\n   * to non-workspace hosts.\n   */\n  mcp?: McpHostPolicyConfig;\n  /**\n   * Human-in-the-loop approval gate for mutating tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool whose annotation flags it as mutating —\n   * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n   * `destructive: true` boolean — and waits for a `POST /chat/approve`\n   * decision from the same user who initiated the stream. A missing decision\n   * after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /**\n     * Require human approval for tools that mutate state. Triggered by\n     * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n     * `destructive: true` boolean. Default: `true`.\n     */\n    requireForDestructive?: boolean;\n    /** Milliseconds to wait before auto-denying. Default: 60_000. */\n    timeoutMs?: number;\n  };\n  /**\n   * Runtime resource limits applied during agent execution. Defaults are\n   * tuned to protect a single-instance deployment from a misbehaving user or\n   * a runaway prompt injection; tighten or relax as appropriate for the\n   * deployment's scale and trust model. Request-body caps (chat message\n   * size, invocations input size / length) are enforced statically by the\n   * Zod schemas and are not configurable here.\n   */\n  limits?: {\n    /**\n     * Max concurrent chat streams a single user may have open. Subsequent\n     * `POST /chat` requests from that user while at-limit are rejected with\n     * HTTP 429. Default: `5`.\n     */\n    maxConcurrentStreamsPerUser?: number;\n    /**\n     * Max tool invocations per agent run (across the full tool-call graph,\n     * including sub-agent invocations). A run that exceeds the budget is\n     * aborted with a terminal error event. Default: `50`.\n     */\n    maxToolCalls?: number;\n    /**\n     * Max sub-agent recursion depth. Protects against a prompt-injected\n     * agent that delegates to a sub-agent which in turn delegates back to\n     * itself (directly or transitively). Default: `3`.\n     */\n    maxSubAgentDepth?: number;\n    /**\n     * Per-call timeout for tools dispatched through `PluginContext`\n     * (toolkit-routed tools — analytics SQL warehouse queries, Genie\n     * messages, Lakebase queries). Independent of `maxToolCalls`: the\n     * budget caps how many tools fire per run, this caps how long any\n     * single tool call may run. The signal handed to plugin tool\n     * implementations combines this timeout with the parent stream's\n     * abort signal via `AbortSignal.any`. Function and MCP tools have\n     * their own timeouts in their respective adapters and ignore this\n     * setting. Default: `300_000` (5 minutes) — generous enough for cold\n     * SQL Warehouse round-trips and long Genie conversations.\n     */\n    toolCallTimeoutMs?: number;\n  };\n}\n\n/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */\nexport type ResolvedToolEntry =\n  | {\n      source: \"toolkit\";\n      pluginName: string;\n      localName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"function\";\n      functionTool: FunctionTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"mcp\";\n      mcpToolName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"subagent\";\n      agentName: string;\n      def: AgentToolDefinition;\n    };\n\nexport interface RegisteredAgent {\n  name: string;\n  instructions: string;\n  adapter: AgentAdapter;\n  toolIndex: Map<string, ResolvedToolEntry>;\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */\n  ephemeral?: boolean;\n}\n\n/**\n * Type guard for `ToolkitEntry` — used by the agents plugin to differentiate\n * toolkit references from inline tools in a mixed `tools` record.\n */\nexport function isToolkitEntry(value: unknown): value is ToolkitEntry {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as { __toolkitRef?: unknown }).__toolkitRef === true\n  );\n}\n"],"mappings":";;;;;AA+TA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}

package/dist/core/appkit.d.ts

@@ -48,6 +48,7 @@ declare function createApp<T extends PluginData<PluginConstructor, unknown, stri
   cache?: CacheConfig;
   client?: WorkspaceClient;
   onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
+  disableInternalTelemetry?: boolean;
 }): Promise<PluginMap<T>>;
 //#endregion
 export { createApp };

package/dist/core/appkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appkit.d.ts","names":[],"sources":["../../src/core/appkit.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgRsB,SAAA,WACV,UAAA,CAAW,iBAAA,qBAAA,CAErB,MAAA;EACE,OAAA,GAAU,CAAA;EACV,SAAA,GAAY,eAAA;EACZ,KAAA,GAAQ,WAAA;EACR,MAAA,GAAS,eAAA;EACT,cAAA,IAAkB,MAAA,EAAQ,SAAA,CAAU,CAAA,aAAc,OAAA;AAAA,IAEnD,OAAA,CAAQ,SAAA,CAAU,CAAA"}
+{"version":3,"file":"appkit.d.ts","names":[],"sources":["../../src/core/appkit.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2TsB,SAAA,WACV,UAAA,CAAW,iBAAA,qBAAA,CAErB,MAAA;EACE,OAAA,GAAU,CAAA;EACV,SAAA,GAAY,eAAA;EACZ,KAAA,GAAQ,WAAA;EACR,MAAA,GAAS,eAAA;EACT,cAAA,IAAkB,MAAA,EAAQ,SAAA,CAAU,CAAA,aAAc,OAAA;EAClD,wBAAA;AAAA,IAED,OAAA,CAAQ,SAAA,CAAU,CAAA"}

package/dist/core/appkit.js

@@ -2,11 +2,16 @@ import { createLogger } from "../logging/logger.js";
 import { TelemetryManager } from "../telemetry/telemetry-manager.js";
 import "../telemetry/index.js";
 import { CacheManager } from "../cache/index.js";
+import { version } from "../appkit/package.js";
 import { ServiceContext } from "../context/service-context.js";
 import { init_context } from "../context/index.js";
+import { isInternalTelemetryEnabled } from "../internal-telemetry/config.js";
+import { TelemetryReporter } from "../internal-telemetry/reporter.js";
+import "../internal-telemetry/index.js";
 import { ResourceType } from "../registry/types.generated.js";
 import { ResourceRegistry } from "../registry/resource-registry.js";
 import "../registry/index.js";
+import { PluginContext, isToolProvider } from "./plugin-context.js";
 
 //#region src/core/appkit.ts
 init_context();
@@ -14,28 +19,37 @@ const logger = createLogger("appkit");
 var AppKit = class AppKit {
 	#pluginInstances = {};
 	#setupPromises = [];
+	#context;
 	constructor(config) {
 		const { plugins, ...globalConfig } = config;
+		this.#context = new PluginContext();
 		const pluginEntries = Object.entries(plugins);
 		const corePlugins = pluginEntries.filter(([_, p]) => {
 			return (p?.plugin?.phase ?? "normal") === "core";
 		});
 		const normalPlugins = pluginEntries.filter(([_, p]) => (p?.plugin?.phase ?? "normal") === "normal");
 		const deferredPlugins = pluginEntries.filter(([_, p]) => (p?.plugin?.phase ?? "normal") === "deferred");
-		for (const [name, pluginData] of corePlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData);
-		for (const [name, pluginData] of normalPlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData);
-		for (const [name, pluginData] of deferredPlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData, { plugins: this.#pluginInstances });
+		for (const [name, pluginData] of corePlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData, { context: this.#context });
+		for (const [name, pluginData] of normalPlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData, { context: this.#context });
+		for (const [name, pluginData] of deferredPlugins) if (pluginData) this.createAndRegisterPlugin(globalConfig, name, pluginData, { context: this.#context });
 	}
 	createAndRegisterPlugin(config, name, pluginData, extraData) {
 		const { plugin: Plugin, config: pluginConfig } = pluginData;
-		const pluginInstance = new Plugin({
+		const baseConfig = {
 			...config,
 			...Plugin.DEFAULT_CONFIG,
 			...pluginConfig,
 			name,
 			...extraData
+		};
+		const pluginInstance = new Plugin(baseConfig);
+		if (typeof pluginInstance.attachContext === "function") pluginInstance.attachContext({
+			context: this.#context,
+			telemetryConfig: baseConfig.telemetry
 		});
 		this.#pluginInstances[name] = pluginInstance;
+		this.#context.registerPlugin(name, pluginInstance);
+		if (isToolProvider(pluginInstance)) this.#context.registerToolProvider(name, pluginInstance);
 		this.#setupPromises.push(pluginInstance.setup());
 		const self = this;
 		Object.defineProperty(this, name, {
@@ -101,16 +115,29 @@ var AppKit = class AppKit {
 		registry.enforceValidation();
 		const instance = new AppKit({ plugins: AppKit.preparePlugins(rawPlugins) });
 		await Promise.all(instance.#setupPromises);
+		await instance.#context.emitLifecycle("setup:complete");
 		const handle = instance;
 		if (config.onPluginsReady) {
 			logger.debug("Running onPluginsReady hook");
 			await config.onPluginsReady(handle);
 			logger.debug("onPluginsReady hook completed");
 		}
+		if (isInternalTelemetryEnabled(config)) AppKit.bootstrapInternalTelemetry();
 		const serverPlugin = instance.#pluginInstances.server;
 		if (serverPlugin && typeof serverPlugin.start === "function") await serverPlugin.start();
 		return handle;
 	}
+	static bootstrapInternalTelemetry() {
+		const serviceCtx = ServiceContext.get();
+		const reporter = TelemetryReporter.initialize({
+			workspaceId: serviceCtx.workspaceId,
+			client: serviceCtx.client,
+			appId: process.env.DATABRICKS_CLIENT_ID || "",
+			appkitVersion: version
+		});
+		reporter.start();
+		reporter.sendStartup().catch(() => {});
+	}
 	static preparePlugins(plugins) {
 		const result = {};
 		for (const currentPlugin of plugins) result[currentPlugin.name] = {

package/dist/core/appkit.js.map

@@ -1 +1 @@
-{"version":3,"file":"appkit.js","names":["#pluginInstances","#setupPromises"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type {\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport { createLogger } from \"../logging/logger\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\n\nconst logger = createLogger(\"appkit\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData);\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData);\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          plugins: this.#pluginInstances,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (AppKit.isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return pluginExports;\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return objExports;\n    }\n\n    return {\n      ...objExports,\n      /**\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) => {\n        const userPlugin = (plugin as any).asUser(req);\n        const userExports = (userPlugin.exports?.() ?? {}) as Record<\n          string,\n          unknown\n        >;\n        this.bindExportMethods(userExports, userPlugin);\n        return userExports;\n      },\n    };\n  }\n\n  /**\n   * Returns true if the value is a plain object (not an array, Date, etc.).\n   */\n  private static isPlainObject(\n    value: unknown,\n  ): value is Record<string, unknown> {\n    if (typeof value !== \"object\" || value === null) return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n    } = {},\n  ): Promise<PluginMap<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const rawPlugins = config.plugins as T;\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      { warehouseId: needsWarehouse },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n\n    const handle = instance as unknown as PluginMap<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(handle);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    return handle;\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n  } = {},\n): Promise<PluginMap<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":"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"}
+{"version":3,"file":"appkit.js","names":["#context","#pluginInstances","#setupPromises","productVersion"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type {\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\nimport { version as productVersion } from \"../../package.json\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport {\n  isInternalTelemetryEnabled,\n  TelemetryReporter,\n} from \"../internal-telemetry\";\nimport { createLogger } from \"../logging/logger\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\nimport { isToolProvider, PluginContext } from \"./plugin-context\";\n\nconst logger = createLogger(\"appkit\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n  #context: PluginContext;\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    this.#context = new PluginContext();\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    if (typeof pluginInstance.attachContext === \"function\") {\n      pluginInstance.attachContext({\n        context: this.#context,\n        telemetryConfig: baseConfig.telemetry,\n      });\n    }\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#context.registerPlugin(name, pluginInstance);\n    if (isToolProvider(pluginInstance)) {\n      this.#context.registerToolProvider(name, pluginInstance);\n    }\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (AppKit.isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return pluginExports;\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return objExports;\n    }\n\n    return {\n      ...objExports,\n      /**\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) => {\n        const userPlugin = (plugin as any).asUser(req);\n        const userExports = (userPlugin.exports?.() ?? {}) as Record<\n          string,\n          unknown\n        >;\n        this.bindExportMethods(userExports, userPlugin);\n        return userExports;\n      },\n    };\n  }\n\n  /**\n   * Returns true if the value is a plain object (not an array, Date, etc.).\n   */\n  private static isPlainObject(\n    value: unknown,\n  ): value is Record<string, unknown> {\n    if (typeof value !== \"object\" || value === null) return false;\n    const proto = Object.getPrototypeOf(value);\n    return proto === Object.prototype || proto === null;\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n      disableInternalTelemetry?: boolean;\n    } = {},\n  ): Promise<PluginMap<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const rawPlugins = config.plugins as T;\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      { warehouseId: needsWarehouse },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n    await instance.#context.emitLifecycle(\"setup:complete\");\n\n    const handle = instance as unknown as PluginMap<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(handle);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    if (isInternalTelemetryEnabled(config)) {\n      AppKit.bootstrapInternalTelemetry();\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    return handle;\n  }\n\n  private static bootstrapInternalTelemetry(): void {\n    const serviceCtx = ServiceContext.get();\n    const reporter = TelemetryReporter.initialize({\n      workspaceId: serviceCtx.workspaceId,\n      client: serviceCtx.client,\n      appId: process.env.DATABRICKS_CLIENT_ID || \"\",\n      appkitVersion: productVersion,\n    });\n    reporter.start();\n    reporter.sendStartup().catch(() => {});\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n    disableInternalTelemetry?: boolean;\n  } = {},\n): Promise<PluginMap<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":"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"}