@databricks/appkit 0.31.0 → 0.33.0

package/dist/plugins/agents/thread-store.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+
+//#region src/plugins/agents/thread-store.ts
+/**
+* In-memory thread store backed by a nested Map.
+*
+* Outer key: userId, inner key: threadId. Thread history is retained for the
+* lifetime of the process with no eviction, caps, or TTL — a chatty user will
+* grow the in-memory footprint monotonically, and the server loses every
+* thread on restart. **This implementation is intended for local development
+* and single-process demos only.**
+*
+* For any real deployment, pass a persistent `ThreadStore` to `agents({ ... })`
+* (e.g. a Lakebase- or Postgres-backed implementation). A bounded
+* `InMemoryThreadStore` with eviction policies is tracked as a follow-up.
+*/
+var InMemoryThreadStore = class {
+	store = /* @__PURE__ */ new Map();
+	async create(userId) {
+		const now = /* @__PURE__ */ new Date();
+		const thread = {
+			id: randomUUID(),
+			userId,
+			messages: [],
+			createdAt: now,
+			updatedAt: now
+		};
+		this.userMap(userId).set(thread.id, thread);
+		return thread;
+	}
+	async get(threadId, userId) {
+		return this.userMap(userId).get(threadId) ?? null;
+	}
+	async list(userId) {
+		return Array.from(this.userMap(userId).values()).sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+	}
+	async addMessage(threadId, userId, message) {
+		const thread = this.userMap(userId).get(threadId);
+		if (!thread) throw new Error(`Thread ${threadId} not found`);
+		thread.messages.push(message);
+		thread.updatedAt = /* @__PURE__ */ new Date();
+	}
+	async delete(threadId, userId) {
+		return this.userMap(userId).delete(threadId);
+	}
+	userMap(userId) {
+		let map = this.store.get(userId);
+		if (!map) {
+			map = /* @__PURE__ */ new Map();
+			this.store.set(userId, map);
+		}
+		return map;
+	}
+};
+
+//#endregion
+export { InMemoryThreadStore };
+//# sourceMappingURL=thread-store.js.map

package/dist/plugins/agents/thread-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-store.js","names":[],"sources":["../../../src/plugins/agents/thread-store.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { Message, Thread, ThreadStore } from \"shared\";\n\n/**\n * In-memory thread store backed by a nested Map.\n *\n * Outer key: userId, inner key: threadId. Thread history is retained for the\n * lifetime of the process with no eviction, caps, or TTL — a chatty user will\n * grow the in-memory footprint monotonically, and the server loses every\n * thread on restart. **This implementation is intended for local development\n * and single-process demos only.**\n *\n * For any real deployment, pass a persistent `ThreadStore` to `agents({ ... })`\n * (e.g. a Lakebase- or Postgres-backed implementation). A bounded\n * `InMemoryThreadStore` with eviction policies is tracked as a follow-up.\n */\nexport class InMemoryThreadStore implements ThreadStore {\n  private store = new Map<string, Map<string, Thread>>();\n\n  async create(userId: string): Promise<Thread> {\n    const now = new Date();\n    const thread: Thread = {\n      id: randomUUID(),\n      userId,\n      messages: [],\n      createdAt: now,\n      updatedAt: now,\n    };\n    this.userMap(userId).set(thread.id, thread);\n    return thread;\n  }\n\n  async get(threadId: string, userId: string): Promise<Thread | null> {\n    return this.userMap(userId).get(threadId) ?? null;\n  }\n\n  async list(userId: string): Promise<Thread[]> {\n    return Array.from(this.userMap(userId).values()).sort(\n      (a, b) => b.updatedAt.getTime() - a.updatedAt.getTime(),\n    );\n  }\n\n  async addMessage(\n    threadId: string,\n    userId: string,\n    message: Message,\n  ): Promise<void> {\n    const thread = this.userMap(userId).get(threadId);\n    if (!thread) throw new Error(`Thread ${threadId} not found`);\n    thread.messages.push(message);\n    thread.updatedAt = new Date();\n  }\n\n  async delete(threadId: string, userId: string): Promise<boolean> {\n    return this.userMap(userId).delete(threadId);\n  }\n\n  private userMap(userId: string): Map<string, Thread> {\n    let map = this.store.get(userId);\n    if (!map) {\n      map = new Map();\n      this.store.set(userId, map);\n    }\n    return map;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAa,sBAAb,MAAwD;CACtD,AAAQ,wBAAQ,IAAI,KAAkC;CAEtD,MAAM,OAAO,QAAiC;EAC5C,MAAM,sBAAM,IAAI,MAAM;EACtB,MAAM,SAAiB;GACrB,IAAI,YAAY;GAChB;GACA,UAAU,EAAE;GACZ,WAAW;GACX,WAAW;GACZ;AACD,OAAK,QAAQ,OAAO,CAAC,IAAI,OAAO,IAAI,OAAO;AAC3C,SAAO;;CAGT,MAAM,IAAI,UAAkB,QAAwC;AAClE,SAAO,KAAK,QAAQ,OAAO,CAAC,IAAI,SAAS,IAAI;;CAG/C,MAAM,KAAK,QAAmC;AAC5C,SAAO,MAAM,KAAK,KAAK,QAAQ,OAAO,CAAC,QAAQ,CAAC,CAAC,MAC9C,GAAG,MAAM,EAAE,UAAU,SAAS,GAAG,EAAE,UAAU,SAAS,CACxD;;CAGH,MAAM,WACJ,UACA,QACA,SACe;EACf,MAAM,SAAS,KAAK,QAAQ,OAAO,CAAC,IAAI,SAAS;AACjD,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,UAAU,SAAS,YAAY;AAC5D,SAAO,SAAS,KAAK,QAAQ;AAC7B,SAAO,4BAAY,IAAI,MAAM;;CAG/B,MAAM,OAAO,UAAkB,QAAkC;AAC/D,SAAO,KAAK,QAAQ,OAAO,CAAC,OAAO,SAAS;;CAG9C,AAAQ,QAAQ,QAAqC;EACnD,IAAI,MAAM,KAAK,MAAM,IAAI,OAAO;AAChC,MAAI,CAAC,KAAK;AACR,yBAAM,IAAI,KAAK;AACf,QAAK,MAAM,IAAI,QAAQ,IAAI;;AAE7B,SAAO"}

package/dist/plugins/agents/tool-approval-gate.js

@@ -0,0 +1,75 @@
+//#region src/plugins/agents/tool-approval-gate.ts
+var ToolApprovalGate = class {
+	pending = /* @__PURE__ */ new Map();
+	/**
+	* Register a pending approval and return a promise that resolves with the
+	* user's decision or with `"deny"` when the timeout elapses. The returned
+	* promise never rejects.
+	*/
+	wait(args) {
+		const { approvalId, streamId, userId, timeoutMs } = args;
+		return new Promise((resolve) => {
+			const timeout = setTimeout(() => {
+				if (this.pending.delete(approvalId)) resolve("deny");
+			}, timeoutMs);
+			this.pending.set(approvalId, {
+				resolve,
+				userId,
+				streamId,
+				timeout
+			});
+		});
+	}
+	/**
+	* Settle an approval with a user decision. Returns:
+	* - `{ ok: true }` if the pending record existed, the userId matched, and
+	*   the promise was resolved.
+	* - `{ ok: false, reason: "unknown" }` if no pending record matches the id.
+	* - `{ ok: false, reason: "forbidden" }` if the userId does not match the
+	*   user who initiated the stream.
+	*/
+	submit(args) {
+		const { approvalId, userId, decision } = args;
+		const p = this.pending.get(approvalId);
+		if (!p) return {
+			ok: false,
+			reason: "unknown"
+		};
+		if (p.userId !== userId) return {
+			ok: false,
+			reason: "forbidden"
+		};
+		clearTimeout(p.timeout);
+		this.pending.delete(approvalId);
+		p.resolve(decision);
+		return { ok: true };
+	}
+	/**
+	* Cancel all pending gates for a specific stream (e.g., when the user
+	* cancels the stream). Each gate resolves with `"deny"` so the adapter
+	* unwinds cleanly.
+	*/
+	abortStream(streamId) {
+		for (const [id, p] of this.pending) if (p.streamId === streamId) {
+			clearTimeout(p.timeout);
+			this.pending.delete(id);
+			p.resolve("deny");
+		}
+	}
+	/** Cancel every pending gate. Used at plugin shutdown. */
+	abortAll() {
+		for (const [id, p] of this.pending) {
+			clearTimeout(p.timeout);
+			this.pending.delete(id);
+			p.resolve("deny");
+		}
+	}
+	/** Number of pending approvals (test/diagnostic helper). */
+	get size() {
+		return this.pending.size;
+	}
+};
+
+//#endregion
+export { ToolApprovalGate };
+//# sourceMappingURL=tool-approval-gate.js.map

package/dist/plugins/agents/tool-approval-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-approval-gate.js","names":[],"sources":["../../../src/plugins/agents/tool-approval-gate.ts"],"sourcesContent":["/**\n * Server-side state for the human-in-the-loop approval gate on mutating\n * agent tool calls — tools annotated with `effect: \"write\" | \"update\" |\n * \"destructive\"` (preferred) or the legacy `destructive: true` boolean.\n *\n * Lifecycle:\n *\n * 1. `wait(...)` is called from inside `executeTool` when a mutating tool\n *    is about to execute. A `Pending` record is registered and a timer is\n *    scheduled for auto-deny. The returned promise is what blocks the\n *    adapter until the decision arrives.\n * 2. The client receives an `appkit.approval_pending` SSE event carrying the\n *    `approvalId` + `streamId` and posts a decision to `POST /chat/approve`.\n *    The route calls {@link ToolApprovalGate.submit} which resolves the\n *    pending promise and clears the timer.\n * 3. If no submit arrives within `timeoutMs`, the timer fires and the\n *    promise resolves with `\"deny\"`.\n *\n * Security invariants:\n *\n * - `submit` verifies that the decider's user id matches the user who\n *   initiated the stream (set by `wait`). Mismatches are rejected without\n *   resolving the pending promise — this prevents a second user from\n *   approving (or denying) another user's destructive action.\n * - `abort(streamId)` cancels every pending gate for a stream and denies\n *   each one. Used when the enclosing stream is cancelled or the plugin is\n *   shutting down.\n */\ntype ApprovalDecision = \"approve\" | \"deny\";\n\ninterface Pending {\n  resolve: (decision: ApprovalDecision) => void;\n  userId: string;\n  streamId: string;\n  timeout: ReturnType<typeof setTimeout>;\n}\n\ntype ApprovalSubmitResult =\n  | { ok: true }\n  | { ok: false; reason: \"unknown\" | \"forbidden\" };\n\nexport class ToolApprovalGate {\n  private pending = new Map<string, Pending>();\n\n  /**\n   * Register a pending approval and return a promise that resolves with the\n   * user's decision or with `\"deny\"` when the timeout elapses. The returned\n   * promise never rejects.\n   */\n  wait(args: {\n    approvalId: string;\n    streamId: string;\n    userId: string;\n    timeoutMs: number;\n  }): Promise<ApprovalDecision> {\n    const { approvalId, streamId, userId, timeoutMs } = args;\n    return new Promise<ApprovalDecision>((resolve) => {\n      const timeout = setTimeout(() => {\n        if (this.pending.delete(approvalId)) {\n          resolve(\"deny\");\n        }\n      }, timeoutMs);\n      this.pending.set(approvalId, {\n        resolve,\n        userId,\n        streamId,\n        timeout,\n      });\n    });\n  }\n\n  /**\n   * Settle an approval with a user decision. Returns:\n   * - `{ ok: true }` if the pending record existed, the userId matched, and\n   *   the promise was resolved.\n   * - `{ ok: false, reason: \"unknown\" }` if no pending record matches the id.\n   * - `{ ok: false, reason: \"forbidden\" }` if the userId does not match the\n   *   user who initiated the stream.\n   */\n  submit(args: {\n    approvalId: string;\n    userId: string;\n    decision: ApprovalDecision;\n  }): ApprovalSubmitResult {\n    const { approvalId, userId, decision } = args;\n    const p = this.pending.get(approvalId);\n    if (!p) return { ok: false, reason: \"unknown\" };\n    if (p.userId !== userId) return { ok: false, reason: \"forbidden\" };\n    clearTimeout(p.timeout);\n    this.pending.delete(approvalId);\n    p.resolve(decision);\n    return { ok: true };\n  }\n\n  /**\n   * Cancel all pending gates for a specific stream (e.g., when the user\n   * cancels the stream). Each gate resolves with `\"deny\"` so the adapter\n   * unwinds cleanly.\n   */\n  abortStream(streamId: string): void {\n    for (const [id, p] of this.pending) {\n      if (p.streamId === streamId) {\n        clearTimeout(p.timeout);\n        this.pending.delete(id);\n        p.resolve(\"deny\");\n      }\n    }\n  }\n\n  /** Cancel every pending gate. Used at plugin shutdown. */\n  abortAll(): void {\n    for (const [id, p] of this.pending) {\n      clearTimeout(p.timeout);\n      this.pending.delete(id);\n      p.resolve(\"deny\");\n    }\n  }\n\n  /** Number of pending approvals (test/diagnostic helper). */\n  get size(): number {\n    return this.pending.size;\n  }\n}\n"],"mappings":";AAyCA,IAAa,mBAAb,MAA8B;CAC5B,AAAQ,0BAAU,IAAI,KAAsB;;;;;;CAO5C,KAAK,MAKyB;EAC5B,MAAM,EAAE,YAAY,UAAU,QAAQ,cAAc;AACpD,SAAO,IAAI,SAA2B,YAAY;GAChD,MAAM,UAAU,iBAAiB;AAC/B,QAAI,KAAK,QAAQ,OAAO,WAAW,CACjC,SAAQ,OAAO;MAEhB,UAAU;AACb,QAAK,QAAQ,IAAI,YAAY;IAC3B;IACA;IACA;IACA;IACD,CAAC;IACF;;;;;;;;;;CAWJ,OAAO,MAIkB;EACvB,MAAM,EAAE,YAAY,QAAQ,aAAa;EACzC,MAAM,IAAI,KAAK,QAAQ,IAAI,WAAW;AACtC,MAAI,CAAC,EAAG,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAW;AAC/C,MAAI,EAAE,WAAW,OAAQ,QAAO;GAAE,IAAI;GAAO,QAAQ;GAAa;AAClE,eAAa,EAAE,QAAQ;AACvB,OAAK,QAAQ,OAAO,WAAW;AAC/B,IAAE,QAAQ,SAAS;AACnB,SAAO,EAAE,IAAI,MAAM;;;;;;;CAQrB,YAAY,UAAwB;AAClC,OAAK,MAAM,CAAC,IAAI,MAAM,KAAK,QACzB,KAAI,EAAE,aAAa,UAAU;AAC3B,gBAAa,EAAE,QAAQ;AACvB,QAAK,QAAQ,OAAO,GAAG;AACvB,KAAE,QAAQ,OAAO;;;;CAMvB,WAAiB;AACf,OAAK,MAAM,CAAC,IAAI,MAAM,KAAK,SAAS;AAClC,gBAAa,EAAE,QAAQ;AACvB,QAAK,QAAQ,OAAO,GAAG;AACvB,KAAE,QAAQ,OAAO;;;;CAKrB,IAAI,OAAe;AACjB,SAAO,KAAK,QAAQ"}

package/dist/plugins/analytics/analytics.d.ts

@@ -1,16 +1,19 @@
+import { AgentToolDefinition, ToolProvider } from "../../shared/src/agent.js";
 import { IAppRouter, ToPlugin } from "../../shared/src/plugin.js";
 import { SQLTypeMarker } from "../../shared/src/sql/types.js";
 import "../../shared/src/index.js";
+import { ToolkitEntry, ToolkitOptions } from "../../core/agent/types.js";
 import { Plugin } from "../../plugin/plugin.js";
 import "../../plugin/index.js";
 import { PluginManifest } from "../../registry/types.js";
 import "../../registry/index.js";
+import "../agents/index.js";
 import { IAnalyticsConfig } from "./types.js";
 import { WorkspaceClient } from "@databricks/sdk-experimental";
 import express from "express";
 
 //#region src/plugins/analytics/analytics.d.ts
-declare class AnalyticsPlugin extends Plugin {
+declare class AnalyticsPlugin extends Plugin implements ToolProvider {
   /** Plugin manifest declaring metadata and resource requirements */
   static manifest: PluginManifest<"analytics">;
   protected static description: string;
@@ -50,6 +53,17 @@ declare class AnalyticsPlugin extends Plugin {
    */
   protected getArrowData(workspaceClient: WorkspaceClient, jobId: string, signal?: AbortSignal): Promise<ReturnType<typeof this.SQLClient.getArrowData>>;
   shutdown(): Promise<void>;
+  private tools;
+  getAgentTools(): AgentToolDefinition[];
+  executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
+  /**
+   * Returns the plugin's tools as a keyed record of `ToolkitEntry` markers.
+   * Called by the agents plugin (via `resolveToolkitFromProvider`) to spread
+   * a filtered, renamed view of the plugin's tools into an agent's tool
+   * index. Inside the function form of `AgentDefinition.tools`, callers
+   * reach this method via `plugins.analytics.toolkit(opts)`.
+   */
+  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;
   /**
    * Returns the public exports for the analytics plugin.
    * Note: `asUser()` is automatically added by AppKit.

package/dist/plugins/analytics/analytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;cAwBa,eAAA,SAAwB,MAAA;;SAE5B,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EApBS;;;;EAgDxB,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EADI;;;;EAuCD,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA8G2B;;;;;;;;;;;;;;;EAFxB,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EA/MsC;;;EAAA,UAuOzB,YAAA,CACd,eAAA,EAAiB,eAAA,EACjB,KAAA,UACA,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,UAAA,aAAuB,SAAA,CAAU,YAAA;EAItC,QAAA,CAAA,GAAY,OAAA;EA3OD;;;;EAmPjB,OAAA,CAAA;;;;2BA5Ce,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAqDQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}
+{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;;;;cAmCa,eAAA,SAAwB,MAAA,YAAkB,YAAA;;SAE9C,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EAtBV;;;;EAkDL,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA1CiB;;;;EAgFd,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAFI;;;;;;;;;;;;;;;EAgHD,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EAmEO;;;EAAA,UA3CM,YAAA,CACd,eAAA,EAAiB,eAAA,EACjB,KAAA,UACA,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,UAAA,aAAuB,SAAA,CAAU,YAAA;EAItC,QAAA,CAAA,GAAY,OAAA;EAAA,QAIV,KAAA;EAuBR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EApRgC;;;;;;;EA+RnC,OAAA,CAAQ,IAAA,GAXE,cAAA,GAWoD,MAAA,SAAA,YAAA;EA3R7C;;;;EAmSjB,OAAA,CAAA;;;;2BA1Fe,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAmGQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}

package/dist/plugins/analytics/analytics.js

@@ -6,9 +6,14 @@ import { toPlugin } from "../../plugin/to-plugin.js";
 import "../../plugin/index.js";
 import { SQLWarehouseConnector } from "../../connectors/sql-warehouse/client.js";
 import "../../connectors/index.js";
+import { buildToolkitEntries } from "../../core/agent/build-toolkit.js";
+import { defineTool, executeFromRegistry, toolsFromRegistry } from "../../core/agent/tools/define-tool.js";
+import { assertReadOnlySql } from "../../core/agent/tools/sql-policy.js";
 import { queryDefaults } from "./defaults.js";
 import manifest_default from "./manifest.js";
 import { QueryProcessor } from "./query.js";
+import { normalizeAnalyticsFormat } from "./types.js";
+import { z } from "zod";
 
 //#region src/plugins/analytics/analytics.ts
 init_context();
@@ -79,7 +84,8 @@ var AnalyticsPlugin = class extends Plugin {
 	*/
 	async _handleQueryRoute(req, res) {
 		const { query_key } = req.params;
-		const { parameters, format = "JSON" } = req.body;
+		const { parameters, format: rawFormat = "JSON_ARRAY" } = req.body;
+		const format = normalizeAnalyticsFormat(rawFormat);
 		logger.debug(req, "Executing query: %s (format=%s)", query_key, format);
 		logger.event(req)?.setComponent("analytics", "executeQuery").setContext("analytics", {
 			query_key,
@@ -99,7 +105,7 @@ var AnalyticsPlugin = class extends Plugin {
 		const { query, isAsUser } = queryResult;
 		const executor = isAsUser ? this.asUser(req) : this;
 		const executorKey = isAsUser ? this.resolveUserId(req) : "global";
-		const queryParameters = format === "ARROW" ? {
+		const queryParameters = format === "ARROW_STREAM" ? {
 			formatParameters: {
 				disposition: "EXTERNAL_LINKS",
 				format: "ARROW_STREAM"
@@ -165,6 +171,35 @@ var AnalyticsPlugin = class extends Plugin {
 	async shutdown() {
 		this.streamManager.abortAll();
 	}
+	tools = { query: defineTool({
+		description: "Execute a read-only SQL query against the Databricks SQL warehouse. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted; writes are rejected. Returns the query results as JSON.",
+		schema: z.object({ query: z.string().describe("The SQL query to execute. Must be a SELECT, WITH, SHOW, EXPLAIN, or DESCRIBE statement.") }),
+		annotations: {
+			effect: "read",
+			requiresUserContext: true
+		},
+		autoInheritable: true,
+		execute: (args, signal) => {
+			assertReadOnlySql(args.query);
+			return this.query(args.query, void 0, void 0, signal);
+		}
+	}) };
+	getAgentTools() {
+		return toolsFromRegistry(this.tools);
+	}
+	async executeAgentTool(name, args, signal) {
+		return executeFromRegistry(this.tools, name, args, signal);
+	}
+	/**
+	* Returns the plugin's tools as a keyed record of `ToolkitEntry` markers.
+	* Called by the agents plugin (via `resolveToolkitFromProvider`) to spread
+	* a filtered, renamed view of the plugin's tools into an agent's tool
+	* index. Inside the function form of `AgentDefinition.tools`, callers
+	* reach this method via `plugins.analytics.toolkit(opts)`.
+	*/
+	toolkit(opts) {
+		return buildToolkitEntries(this.name, this.tools, opts);
+	}
 	/**
 	* Returns the public exports for the analytics plugin.
 	* Note: `asUser()` is automatically added by AppKit.

package/dist/plugins/analytics/analytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.js","names":["manifest"],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport { getWarehouseId, getWorkspaceClient } from \"../../context\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { queryDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\nexport class AnalyticsPlugin extends Plugin {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"analytics\">;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Arrow data downloads always run as service principal and bypass the\n    // interceptor chain (execute/executeStream). The original query execution\n    // handles OBO via executeStream(); this endpoint fetches pre-computed\n    // results by job ID.\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format = \"JSON\" } = req.body as IAnalyticsQueryRequest;\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const executorKey = isAsUser ? this.resolveUserId(req) : \"global\";\n\n    const queryParameters =\n      format === \"ARROW\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await executor.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await executor.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin(AnalyticsPlugin);\n"],"mappings":"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"}
+{"version":3,"file":"analytics.js","names":["manifest"],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n  ToolProvider,\n} from \"shared\";\nimport { z } from \"zod\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport { getWarehouseId, getWorkspaceClient } from \"../../context\";\nimport { buildToolkitEntries } from \"../../core/agent/build-toolkit\";\nimport {\n  defineTool,\n  executeFromRegistry,\n  toolsFromRegistry,\n} from \"../../core/agent/tools/define-tool\";\nimport { assertReadOnlySql } from \"../../core/agent/tools/sql-policy\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { queryDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\nimport { normalizeAnalyticsFormat } from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\nexport class AnalyticsPlugin extends Plugin implements ToolProvider {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"analytics\">;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Arrow data downloads always run as service principal and bypass the\n    // interceptor chain (execute/executeStream). The original query execution\n    // handles OBO via executeStream(); this endpoint fetches pre-computed\n    // results by job ID.\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format: rawFormat = \"JSON_ARRAY\" } =\n      req.body as IAnalyticsQueryRequest;\n    const format = normalizeAnalyticsFormat(rawFormat);\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const executorKey = isAsUser ? this.resolveUserId(req) : \"global\";\n\n    const queryParameters =\n      format === \"ARROW_STREAM\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await executor.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await executor.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  private tools = {\n    query: defineTool({\n      description:\n        \"Execute a read-only SQL query against the Databricks SQL warehouse. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted; writes are rejected. Returns the query results as JSON.\",\n      schema: z.object({\n        query: z\n          .string()\n          .describe(\n            \"The SQL query to execute. Must be a SELECT, WITH, SHOW, EXPLAIN, or DESCRIBE statement.\",\n          ),\n      }),\n      annotations: {\n        effect: \"read\",\n        requiresUserContext: true,\n      },\n      autoInheritable: true,\n      execute: (args, signal) => {\n        assertReadOnlySql(args.query);\n        return this.query(args.query, undefined, undefined, signal);\n      },\n    }),\n  };\n\n  getAgentTools(): AgentToolDefinition[] {\n    return toolsFromRegistry(this.tools);\n  }\n\n  async executeAgentTool(\n    name: string,\n    args: unknown,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    return executeFromRegistry(this.tools, name, args, signal);\n  }\n\n  /**\n   * Returns the plugin's tools as a keyed record of `ToolkitEntry` markers.\n   * Called by the agents plugin (via `resolveToolkitFromProvider`) to spread\n   * a filtered, renamed view of the plugin's tools into an agent's tool\n   * index. Inside the function form of `AgentDefinition.tools`, callers\n   * reach this method via `plugins.analytics.toolkit(opts)`.\n   */\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin(AnalyticsPlugin);\n"],"mappings":"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"}

package/dist/plugins/analytics/index.js

@@ -1,3 +1,4 @@
+import { normalizeAnalyticsFormat } from "./types.js";
 import { AnalyticsPlugin, analytics } from "./analytics.js";
 
 export {  };

package/dist/plugins/analytics/types.js

@@ -0,0 +1,15 @@
+//#region src/plugins/analytics/types.ts
+/**
+* Map a (possibly legacy) AnalyticsFormat to its canonical form.
+* Legacy values come from appkit/appkit-ui < 0.33.0 and can be removed
+* along with the deprecated aliases once no such consumer remains.
+*/
+function normalizeAnalyticsFormat(f) {
+	if (f === "JSON") return "JSON_ARRAY";
+	if (f === "ARROW") return "ARROW_STREAM";
+	return f;
+}
+
+//#endregion
+export { normalizeAnalyticsFormat };
+//# sourceMappingURL=types.js.map

package/dist/plugins/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/plugins/analytics/types.ts"],"sourcesContent":["import type { BasePluginConfig } from \"shared\";\n\nexport interface IAnalyticsConfig extends BasePluginConfig {\n  timeout?: number;\n}\n\n/**\n * Supported response formats for analytics queries.\n *\n * \"JSON\" and \"ARROW\" are legacy aliases kept for backwards compatibility\n * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on\n * a pre-0.33.0 version. The route handler normalizes them to their\n * canonical equivalents before any downstream code reads the value.\n */\nexport type AnalyticsFormat =\n  | \"JSON_ARRAY\"\n  | \"ARROW_STREAM\"\n  /** @deprecated Use \"JSON_ARRAY\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"JSON\"\n  /** @deprecated Use \"ARROW_STREAM\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"ARROW\";\n\n/** Canonical (post-normalization) analytics format values. */\ntype CanonicalAnalyticsFormat = \"JSON_ARRAY\" | \"ARROW_STREAM\";\n\n/**\n * Map a (possibly legacy) AnalyticsFormat to its canonical form.\n * Legacy values come from appkit/appkit-ui < 0.33.0 and can be removed\n * along with the deprecated aliases once no such consumer remains.\n */\nexport function normalizeAnalyticsFormat(\n  f: AnalyticsFormat,\n): CanonicalAnalyticsFormat {\n  if (f === \"JSON\") return \"JSON_ARRAY\";\n  if (f === \"ARROW\") return \"ARROW_STREAM\";\n  return f;\n}\n\nexport interface IAnalyticsQueryRequest {\n  parameters?: Record<string, any>;\n  format?: AnalyticsFormat;\n}\n\nexport interface AnalyticsQueryResponse {\n  chunk_index: number;\n  row_offset: number;\n  row_count: number;\n  data: any[];\n}\n"],"mappings":";;;;;;AA8BA,SAAgB,yBACd,GAC0B;AAC1B,KAAI,MAAM,OAAQ,QAAO;AACzB,KAAI,MAAM,QAAS,QAAO;AAC1B,QAAO"}

package/dist/plugins/beta-exports.generated.d.ts

@@ -0,0 +1,2 @@
+import { agents } from "./agents/agents.js";
+import "./agents/index.js";

package/dist/plugins/beta-exports.generated.js

@@ -0,0 +1,4 @@
+import { agents } from "./agents/agents.js";
+import "./agents/index.js";
+
+export {  };

package/dist/plugins/files/plugin.d.ts

@@ -1,14 +1,17 @@
+import { AgentToolDefinition, ToolProvider } from "../../shared/src/agent.js";
 import { IAppRouter, ToPlugin } from "../../shared/src/plugin.js";
 import "../../shared/src/index.js";
+import { ToolkitEntry, ToolkitOptions } from "../../core/agent/types.js";
 import { Plugin } from "../../plugin/plugin.js";
 import "../../plugin/index.js";
-import { FilePolicy, FilePolicyUser } from "./policy.js";
 import { PluginManifest, ResourceRequirement } from "../../registry/types.js";
 import "../../registry/index.js";
+import "../agents/index.js";
+import { FilePolicy, FilePolicyUser } from "./policy.js";
 import { FilesExport, IFilesConfig, VolumeAPI, VolumeConfig } from "./types.js";
 
 //#region src/plugins/files/plugin.d.ts
-declare class FilesPlugin extends Plugin {
+declare class FilesPlugin extends Plugin implements ToolProvider {
   name: string;
   /** Plugin manifest declaring metadata and resource requirements. */
   static manifest: PluginManifest;
@@ -17,6 +20,7 @@ declare class FilesPlugin extends Plugin {
   private volumeConnectors;
   private volumeConfigs;
   private volumeKeys;
+  private tools;
   /**
    * Scans `process.env` for `DATABRICKS_VOLUME_*` keys and merges them with
    * any explicitly configured volumes. Explicit config wins for per-volume
@@ -98,9 +102,23 @@ declare class FilesPlugin extends Plugin {
   protected createVolumeAPI(volumeKey: string, user: FilePolicyUser, options?: {
     bypassPolicy?: boolean;
   }): VolumeAPI;
+  /**
+   * Builds the agent-tool registry entries for a single volume. One set of
+   * tools per configured volume, keyed by `${volumeKey}.${method}`.
+   *
+   * Each handler resolves the caller's identity from the current execution
+   * context (OBO user when the agent run is wrapped in `asUser(req)`, service
+   * principal otherwise in local dev) and dispatches through
+   * `createVolumeAPI(volumeKey, user)` so the volume's policy is enforced
+   * uniformly for agent and HTTP callers.
+   */
+  private _defineVolumeTools;
   private inflightWrites;
   private trackWrite;
   shutdown(): Promise<void>;
+  getAgentTools(): AgentToolDefinition[];
+  executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
+  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;
   /**
    * Returns the programmatic API for the Files plugin.
    * Callable with a volume key to get a volume-scoped handle.

package/dist/plugins/files/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;;cA2Ca,WAAA,SAAoB,MAAA;EAC/B,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAJkB;;;;;EAAA,OAWnB,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAuIzC;;;;EAAA,OAhHb,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAs9B3C;;;;EAAA,QAh8BH,YAAA;EA9DuB;;;;EAAA,QAiFjB,YAAA;EA3EI;;;;;EAAA,QA4GJ,cAAA;cAsCF,MAAA,EAAQ,YAAA;EA8CpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EArLyB;;;;EAAA,QAmTtC,cAAA;EA5R8C;;;;EAAA,QAmT9C,YAAA;EAAA,QAQA,aAAA;EA3MI;;;;;;;;;EAAA,QA+NJ,oBAAA;EAAA,QAgBA,eAAA;EAAA,QAqCA,gBAAA;EAAA,QAOM,WAAA;EAAA,QA8BA,WAAA;EAAA,QAmCA,eAAA;EAAA,QAWA,UAAA;EAqIA;;;;;EAAA,QArHA,UAAA;EAAA,QAiFA,aAAA;EAAA,QAoCA,eAAA;EAAA,QAoCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QAgHA,YAAA;EAAA,QA0CA,aAAA;EA4GN;;;;;;;;;;EAAA,UAxDE,eAAA,CACR,SAAA,UACA,IAAA,EAAM,cAAA,EACN,OAAA;IAAY,YAAA;EAAA,IACX,SAAA;EAAA,QAoDK,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EA6EF;;;;;;;;;;;;;;;;EA1ChB,OAAA,CAAA,GAAW,WAAA;EAkCX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAQL,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA;;gCAAA,UAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;;;;;cA4Da,WAAA,SAAoB,MAAA,YAAkB,YAAA;EACjD,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAAA,QACA,KAAA;;;;;;SAOD,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAuBtB;;;;EAAA,OAAhC,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAs3BnD;;;;EAAA,QAh2BK,YAAA;EA8hCE;;;;EAAA,QA3gCI,YAAA;EAlFiB;;;;;EAAA,QAmHjB,cAAA;cAsCF,MAAA,EAAQ,YAAA;EA8CpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EAnMS;;;;EAAA,QAiUtB,cAAA;EA5TA;;;;EAAA,QAmVA,YAAA;EAAA,QAQA,aAAA;EAlVsC;;;;;;;;;EAAA,QAsWtC,oBAAA;EAAA,QAgBA,eAAA;EAAA,QAqCA,gBAAA;EAAA,QAOM,WAAA;EAAA,QA8BA,WAAA;EAAA,QAmCA,eAAA;EAAA,QAWA,UAAA;EApKN;;;;;EAAA,QAoLM,UAAA;EAAA,QAiFA,aAAA;EAAA,QAoCA,eAAA;EAAA,QAoCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QAgHA,YAAA;EAAA,QA0CA,aAAA;EA9LA;;;;;;;;;;EAAA,UAkPJ,eAAA,CACR,SAAA,UACA,IAAA,EAAM,cAAA,EACN,OAAA;IAAY,YAAA;EAAA,IACX,SAAA;EA4JK;;;;;;;;;;EAAA,QA9FA,kBAAA;EAAA,QA4FA,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EAmBlB,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EAIH,OAAA,CAAQ,IAAA,GAJE,cAAA,GAIoD,MAAA,SAAA,YAAA;EAoBnD;;;;;AA0Cb;;;;;;;;;;;EA1CE,OAAA,CAAA,GAAW,WAAA;EAkCX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAQL,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA;;gCAAA,UAAA"}

package/dist/plugins/files/plugin.js

@@ -1,7 +1,8 @@
 import { createLogger } from "../../logging/logger.js";
 import { AuthenticationError } from "../../errors/authentication.js";
 import { init_errors } from "../../errors/index.js";
-import { getCurrentUserId, getWorkspaceClient } from "../../context/execution-context.js";
+import { init_user_context, isUserContext } from "../../context/user-context.js";
+import { getCurrentUserId, getExecutionContext, getWorkspaceClient } from "../../context/execution-context.js";
 import { init_context } from "../../context/index.js";
 import { ResourceType } from "../../registry/types.generated.js";
 import "../../registry/index.js";
@@ -12,15 +13,19 @@ import { PolicyDeniedError, policy } from "./policy.js";
 import { contentTypeFromPath, isSafeInlineContentType, validateCustomContentTypes } from "../../connectors/files/defaults.js";
 import { FilesConnector } from "../../connectors/files/client.js";
 import "../../connectors/files/index.js";
+import { buildToolkitEntries } from "../../core/agent/build-toolkit.js";
+import { defineTool, executeFromRegistry, toolsFromRegistry } from "../../core/agent/tools/define-tool.js";
 import { FILES_DOWNLOAD_DEFAULTS, FILES_MAX_UPLOAD_SIZE, FILES_READ_DEFAULTS, FILES_WRITE_DEFAULTS } from "./defaults.js";
 import { parentDirectory, sanitizeFilename } from "./helpers.js";
 import manifest_default from "./manifest.js";
 import { ApiError } from "@databricks/sdk-experimental";
+import { z } from "zod";
 import { STATUS_CODES } from "node:http";
 import { Readable } from "node:stream";
 
 //#region src/plugins/files/plugin.ts
 init_context();
+init_user_context();
 init_errors();
 const logger = createLogger("files");
 var FilesPlugin = class FilesPlugin extends Plugin {
@@ -31,6 +36,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	volumeConnectors = {};
 	volumeConfigs = {};
 	volumeKeys = [];
+	tools = {};
 	/**
 	* Scans `process.env` for `DATABRICKS_VOLUME_*` keys and merges them with
 	* any explicitly configured volumes. Explicit config wins for per-volume
@@ -162,8 +168,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 				telemetry: config.telemetry,
 				customContentTypes: mergedConfig.customContentTypes
 			});
+			Object.assign(this.tools, this._defineVolumeTools(key));
+			if (!volumeCfg.policy) logger.warn("Volume \"%s\" has no explicit policy — defaulting to publicRead(). Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.", key, key);
 		}
-		for (const key of this.volumeKeys) if (!volumes[key].policy) logger.warn("Volume \"%s\" has no explicit policy — defaulting to publicRead(). Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.", key, key);
 	}
 	injectRoutes(router) {
 		this.route(router, {
@@ -707,6 +714,108 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			}
 		};
 	}
+	/**
+	* Builds the agent-tool registry entries for a single volume. One set of
+	* tools per configured volume, keyed by `${volumeKey}.${method}`.
+	*
+	* Each handler resolves the caller's identity from the current execution
+	* context (OBO user when the agent run is wrapped in `asUser(req)`, service
+	* principal otherwise in local dev) and dispatches through
+	* `createVolumeAPI(volumeKey, user)` so the volume's policy is enforced
+	* uniformly for agent and HTTP callers.
+	*/
+	_defineVolumeTools(volumeKey) {
+		const buildUser = () => {
+			const ctx = getExecutionContext();
+			return isUserContext(ctx) ? { id: ctx.userId } : {
+				id: ctx.serviceUserId,
+				isServicePrincipal: true
+			};
+		};
+		const api = () => this.createVolumeAPI(volumeKey, buildUser());
+		return {
+			[`${volumeKey}.list`]: defineTool({
+				description: `List files and directories in the "${volumeKey}" volume`,
+				schema: z.object({ path: z.string().optional().describe("Directory path to list (optional, defaults to root)") }),
+				annotations: {
+					effect: "read",
+					requiresUserContext: true
+				},
+				autoInheritable: true,
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().list(args.path);
+				}
+			}),
+			[`${volumeKey}.read`]: defineTool({
+				description: `Read a text file from the "${volumeKey}" volume`,
+				schema: z.object({ path: z.string().describe("File path to read") }),
+				annotations: {
+					effect: "read",
+					requiresUserContext: true
+				},
+				autoInheritable: true,
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().read(args.path);
+				}
+			}),
+			[`${volumeKey}.exists`]: defineTool({
+				description: `Check if a file or directory exists in the "${volumeKey}" volume`,
+				schema: z.object({ path: z.string().describe("Path to check") }),
+				annotations: {
+					effect: "read",
+					requiresUserContext: true
+				},
+				autoInheritable: true,
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().exists(args.path);
+				}
+			}),
+			[`${volumeKey}.metadata`]: defineTool({
+				description: `Get metadata (size, type, last modified) for a file in the "${volumeKey}" volume`,
+				schema: z.object({ path: z.string().describe("File path") }),
+				annotations: {
+					effect: "read",
+					requiresUserContext: true
+				},
+				autoInheritable: true,
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().metadata(args.path);
+				}
+			}),
+			[`${volumeKey}.upload`]: defineTool({
+				description: `Upload a text file to the "${volumeKey}" volume`,
+				schema: z.object({
+					path: z.string().describe("Destination file path"),
+					contents: z.string().describe("File contents as a string"),
+					overwrite: z.boolean().optional().describe("Whether to overwrite existing file")
+				}),
+				annotations: {
+					effect: "destructive",
+					requiresUserContext: true
+				},
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().upload(args.path, args.contents, { overwrite: args.overwrite });
+				}
+			}),
+			[`${volumeKey}.delete`]: defineTool({
+				description: `Delete a file from the "${volumeKey}" volume`,
+				schema: z.object({ path: z.string().describe("File path to delete") }),
+				annotations: {
+					effect: "destructive",
+					requiresUserContext: true
+				},
+				execute: (args, signal) => {
+					signal?.throwIfAborted();
+					return api().delete(args.path);
+				}
+			})
+		};
+	}
 	inflightWrites = 0;
 	trackWrite(fn) {
 		this.inflightWrites++;
@@ -723,6 +832,15 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		if (this.inflightWrites > 0) logger.warn("Shutdown deadline reached with %d in-flight write(s) still pending.", this.inflightWrites);
 		this.streamManager.abortAll();
 	}
+	getAgentTools() {
+		return toolsFromRegistry(this.tools);
+	}
+	async executeAgentTool(name, args, signal) {
+		return executeFromRegistry(this.tools, name, args, signal);
+	}
+	toolkit(opts) {
+		return buildToolkitEntries(this.name, this.tools, opts);
+	}
 	/**
 	* Returns the programmatic API for the Files plugin.
 	* Callable with a volume key to get a volume-scoped handle.