@databricks/appkit 0.31.0 → 0.32.0

package/dist/core/agent/tools/sql-policy.js

@@ -0,0 +1,256 @@
+//#region src/core/agent/tools/sql-policy.ts
+/**
+* Conservative SQL classifier used by agent-facing query tools to enforce
+* `readOnly: true` annotations at execution time.
+*
+* Why a hand-rolled tokenizer rather than `node-sql-parser` or `pgsql-parser`:
+*
+* - `node-sql-parser`'s Hive/Spark dialect coverage rejects common Databricks
+*   SQL patterns (three-part `catalog.schema.table` names, `SHOW TABLES IN`,
+*   `DESCRIBE EXTENDED`, `EXPLAIN`) that must be allowed by a read-only
+*   classifier. Its PostgreSQL grammar rejects `SHOW`/`DESCRIBE` too.
+* - `pgsql-parser` (libpg_query) is a native binding and fails to install
+*   cleanly on every Databricks App runtime we care about.
+*
+* We don't need to fully parse SQL — we only need to decide whether every
+* statement in the batch starts with a read-only keyword. A small tokenizer
+* that correctly strips strings, identifiers, and comments is enough and
+* costs no extra dependencies.
+*
+* What this classifier guarantees (when it returns `readOnly: true`):
+*
+* - Every semicolon-separated statement outside a string, identifier, or
+*   comment begins with `SELECT`, `WITH`, `SHOW`, `EXPLAIN`, `DESCRIBE`, or
+*   `DESC`.
+* - `SELECT 1; DROP TABLE x` is rejected (stacked write detected).
+* - `SELECT 'value; DROP TABLE x'` passes (literal inside a string).
+* - `-- DROP TABLE x\nSELECT 1` passes (comment stripped).
+* - `SELECT 1 <block-comment ; DROP block-comment>` passes (comment stripped).
+*
+* What this classifier does NOT guarantee:
+*
+* - A `SELECT` statement may still have side effects via function calls
+*   (`SELECT pg_advisory_lock(...)`, `SELECT lo_import('/etc/passwd')`, CTEs
+*   with DML in Postgres 9.1+). Callers that need stronger guarantees should
+*   combine this check with a runtime mechanism: for PostgreSQL, execute the
+*   statement inside a dedicated client's `BEGIN READ ONLY … ROLLBACK`
+*   transaction (see `LakebasePlugin.runReadOnlyStatement`). A batched
+*   `pool.query("BEGIN READ ONLY; <stmt>; ROLLBACK")` cannot be used because
+*   the Postgres Extended Query protocol rejects multi-statement prepared
+*   queries, which silently breaks parameterized SQL.
+*/
+const READ_ONLY_KEYWORDS = new Set([
+	"SELECT",
+	"WITH",
+	"SHOW",
+	"EXPLAIN",
+	"DESCRIBE",
+	"DESC"
+]);
+/**
+* Classify a SQL string as read-only or not. See module docstring for the
+* precise guarantee this offers.
+*/
+function classifyReadOnly(sql) {
+	const strip = stripCommentsAndQuoted(sql);
+	if (strip.unterminated) return {
+		readOnly: false,
+		reason: `SQL has an unterminated ${strip.unterminated} literal`
+	};
+	const statements = splitStatements(strip.cleaned);
+	if (statements.length === 0) return {
+		readOnly: false,
+		reason: "SQL is empty or contains only comments"
+	};
+	for (let i = 0; i < statements.length; i++) {
+		const stmt = statements[i];
+		const firstWord = firstKeyword(stmt);
+		if (!firstWord) return {
+			readOnly: false,
+			reason: `statement ${i + 1} of ${statements.length} is empty`
+		};
+		if (!READ_ONLY_KEYWORDS.has(firstWord.toUpperCase())) return {
+			readOnly: false,
+			reason: `statement starts with '${firstWord}'; only SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, DESC are allowed in read-only mode`
+		};
+	}
+	return {
+		readOnly: true,
+		statements: statements.length
+	};
+}
+/**
+* Assert `sql` is read-only or throw {@link ReadOnlySqlViolation}. Suitable
+* for calling from agent-tool handlers where the thrown string surfaces back
+* to the LLM as the tool's error output.
+*/
+function assertReadOnlySql(sql) {
+	const result = classifyReadOnly(sql);
+	if (!result.readOnly) throw new ReadOnlySqlViolation(result.reason);
+}
+var ReadOnlySqlViolation = class extends Error {
+	constructor(reason) {
+		super(`SQL read-only policy violation: ${reason}`);
+		this.name = "ReadOnlySqlViolation";
+	}
+};
+function stripCommentsAndQuoted(sql) {
+	const out = [];
+	let i = 0;
+	const n = sql.length;
+	let unterminated = null;
+	while (i < n) {
+		const ch = sql[i];
+		const next = i + 1 < n ? sql[i + 1] : "";
+		if (ch === "-" && next === "-") {
+			out.push("  ");
+			i += 2;
+			while (i < n && sql[i] !== "\n") {
+				out.push(" ");
+				i++;
+			}
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			out.push("  ");
+			i += 2;
+			let depth = 1;
+			while (i < n && depth > 0) {
+				if (sql[i] === "/" && sql[i + 1] === "*") {
+					out.push("  ");
+					i += 2;
+					depth++;
+					continue;
+				}
+				if (sql[i] === "*" && sql[i + 1] === "/") {
+					out.push("  ");
+					i += 2;
+					depth--;
+					continue;
+				}
+				out.push(sql[i] === "\n" ? "\n" : " ");
+				i++;
+			}
+			if (depth > 0) unterminated = "block comment";
+			continue;
+		}
+		if (ch === "'" || ch === "E" && next === "'" || ch === "e" && next === "'") {
+			if (ch === "E" || ch === "e") {
+				out.push(" ");
+				i++;
+			}
+			out.push(" ");
+			i++;
+			let closed = false;
+			while (i < n) {
+				if (sql[i] === "'" && sql[i + 1] === "'") {
+					out.push("  ");
+					i += 2;
+					continue;
+				}
+				if (sql[i] === "\\" && sql[i + 1]) {
+					out.push("  ");
+					i += 2;
+					continue;
+				}
+				if (sql[i] === "'") {
+					out.push(" ");
+					i++;
+					closed = true;
+					break;
+				}
+				out.push(sql[i] === "\n" ? "\n" : " ");
+				i++;
+			}
+			if (!closed) unterminated = "string";
+			continue;
+		}
+		if (ch === "\"") {
+			out.push(" ");
+			i++;
+			let closed = false;
+			while (i < n) {
+				if (sql[i] === "\"" && sql[i + 1] === "\"") {
+					out.push("  ");
+					i += 2;
+					continue;
+				}
+				if (sql[i] === "\"") {
+					out.push(" ");
+					i++;
+					closed = true;
+					break;
+				}
+				out.push(sql[i] === "\n" ? "\n" : " ");
+				i++;
+			}
+			if (!closed) unterminated = "identifier";
+			continue;
+		}
+		if (ch === "`") {
+			out.push(" ");
+			i++;
+			let closed = false;
+			while (i < n) {
+				if (sql[i] === "`" && sql[i + 1] === "`") {
+					out.push("  ");
+					i += 2;
+					continue;
+				}
+				if (sql[i] === "`") {
+					out.push(" ");
+					i++;
+					closed = true;
+					break;
+				}
+				out.push(sql[i] === "\n" ? "\n" : " ");
+				i++;
+			}
+			if (!closed) unterminated = "identifier";
+			continue;
+		}
+		if (ch === "$") {
+			const tagMatch = sql.slice(i).match(/^\$([A-Za-z_][A-Za-z0-9_]*)?\$/);
+			if (tagMatch) {
+				const tag = tagMatch[0];
+				out.push(" ".repeat(tag.length));
+				i += tag.length;
+				const closeIdx = sql.indexOf(tag, i);
+				if (closeIdx === -1) {
+					while (i < n) {
+						out.push(sql[i] === "\n" ? "\n" : " ");
+						i++;
+					}
+					unterminated = "dollar-quoted string";
+				} else {
+					while (i < closeIdx) {
+						out.push(sql[i] === "\n" ? "\n" : " ");
+						i++;
+					}
+					out.push(" ".repeat(tag.length));
+					i += tag.length;
+				}
+				continue;
+			}
+		}
+		out.push(ch);
+		i++;
+	}
+	return {
+		cleaned: out.join(""),
+		unterminated
+	};
+}
+/** Split on unquoted `;`, trim, drop empty segments. */
+function splitStatements(cleanedSql) {
+	return cleanedSql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** Return the first bareword keyword of a statement, or null if empty. */
+function firstKeyword(stmt) {
+	const match = stmt.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)/);
+	return match ? match[1] : null;
+}
+
+//#endregion
+export { assertReadOnlySql };
+//# sourceMappingURL=sql-policy.js.map

package/dist/core/agent/tools/sql-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-policy.js","names":[],"sources":["../../../../src/core/agent/tools/sql-policy.ts"],"sourcesContent":["/**\n * Conservative SQL classifier used by agent-facing query tools to enforce\n * `readOnly: true` annotations at execution time.\n *\n * Why a hand-rolled tokenizer rather than `node-sql-parser` or `pgsql-parser`:\n *\n * - `node-sql-parser`'s Hive/Spark dialect coverage rejects common Databricks\n *   SQL patterns (three-part `catalog.schema.table` names, `SHOW TABLES IN`,\n *   `DESCRIBE EXTENDED`, `EXPLAIN`) that must be allowed by a read-only\n *   classifier. Its PostgreSQL grammar rejects `SHOW`/`DESCRIBE` too.\n * - `pgsql-parser` (libpg_query) is a native binding and fails to install\n *   cleanly on every Databricks App runtime we care about.\n *\n * We don't need to fully parse SQL — we only need to decide whether every\n * statement in the batch starts with a read-only keyword. A small tokenizer\n * that correctly strips strings, identifiers, and comments is enough and\n * costs no extra dependencies.\n *\n * What this classifier guarantees (when it returns `readOnly: true`):\n *\n * - Every semicolon-separated statement outside a string, identifier, or\n *   comment begins with `SELECT`, `WITH`, `SHOW`, `EXPLAIN`, `DESCRIBE`, or\n *   `DESC`.\n * - `SELECT 1; DROP TABLE x` is rejected (stacked write detected).\n * - `SELECT 'value; DROP TABLE x'` passes (literal inside a string).\n * - `-- DROP TABLE x\\nSELECT 1` passes (comment stripped).\n * - `SELECT 1 <block-comment ; DROP block-comment>` passes (comment stripped).\n *\n * What this classifier does NOT guarantee:\n *\n * - A `SELECT` statement may still have side effects via function calls\n *   (`SELECT pg_advisory_lock(...)`, `SELECT lo_import('/etc/passwd')`, CTEs\n *   with DML in Postgres 9.1+). Callers that need stronger guarantees should\n *   combine this check with a runtime mechanism: for PostgreSQL, execute the\n *   statement inside a dedicated client's `BEGIN READ ONLY … ROLLBACK`\n *   transaction (see `LakebasePlugin.runReadOnlyStatement`). A batched\n *   `pool.query(\"BEGIN READ ONLY; <stmt>; ROLLBACK\")` cannot be used because\n *   the Postgres Extended Query protocol rejects multi-statement prepared\n *   queries, which silently breaks parameterized SQL.\n */\n\nconst READ_ONLY_KEYWORDS = new Set([\n  \"SELECT\",\n  \"WITH\",\n  \"SHOW\",\n  \"EXPLAIN\",\n  \"DESCRIBE\",\n  \"DESC\",\n]);\n\ntype SqlReadOnlyResult =\n  | { readOnly: true; statements: number }\n  | { readOnly: false; reason: string };\n\n/**\n * Classify a SQL string as read-only or not. See module docstring for the\n * precise guarantee this offers.\n */\nexport function classifyReadOnly(sql: string): SqlReadOnlyResult {\n  const strip = stripCommentsAndQuoted(sql);\n  if (strip.unterminated) {\n    return {\n      readOnly: false,\n      reason: `SQL has an unterminated ${strip.unterminated} literal`,\n    };\n  }\n  const statements = splitStatements(strip.cleaned);\n\n  if (statements.length === 0) {\n    return {\n      readOnly: false,\n      reason: \"SQL is empty or contains only comments\",\n    };\n  }\n\n  for (let i = 0; i < statements.length; i++) {\n    const stmt = statements[i];\n    const firstWord = firstKeyword(stmt);\n    if (!firstWord) {\n      return {\n        readOnly: false,\n        reason: `statement ${i + 1} of ${statements.length} is empty`,\n      };\n    }\n    if (!READ_ONLY_KEYWORDS.has(firstWord.toUpperCase())) {\n      return {\n        readOnly: false,\n        reason: `statement starts with '${firstWord}'; only SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, DESC are allowed in read-only mode`,\n      };\n    }\n  }\n\n  return { readOnly: true, statements: statements.length };\n}\n\n/**\n * Assert `sql` is read-only or throw {@link ReadOnlySqlViolation}. Suitable\n * for calling from agent-tool handlers where the thrown string surfaces back\n * to the LLM as the tool's error output.\n */\nexport function assertReadOnlySql(sql: string): void {\n  const result = classifyReadOnly(sql);\n  if (!result.readOnly) {\n    throw new ReadOnlySqlViolation(result.reason);\n  }\n}\n\nexport class ReadOnlySqlViolation extends Error {\n  constructor(reason: string) {\n    super(`SQL read-only policy violation: ${reason}`);\n    this.name = \"ReadOnlySqlViolation\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Tokenizer helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Walk `sql` character-by-character and replace every string literal,\n * identifier quote, and comment body with a single space of equivalent\n * length. Leaves structural tokens (semicolons, whitespace, identifiers,\n * operators) in place.\n *\n * Handles:\n * - `-- line comments` through end-of-line\n * - SQL block comments (slash-star ... star-slash) with correct nesting (PostgreSQL)\n * - `'single-quoted strings'` with `''` escape\n * - `\"double-quoted identifiers\"` with `\"\"` escape (ANSI)\n * - `` `backtick identifiers` `` (Databricks)\n * - `$tag$dollar quoted$tag$` strings (PostgreSQL)\n * - `E'escape-style'` strings (PostgreSQL)\n */\ntype StripResult = {\n  cleaned: string;\n  /** Non-null if tokenization ended inside an unterminated literal or comment. */\n  unterminated:\n    | null\n    | \"string\"\n    | \"identifier\"\n    | \"block comment\"\n    | \"dollar-quoted string\";\n};\n\nfunction stripCommentsAndQuoted(sql: string): StripResult {\n  const out: string[] = [];\n  let i = 0;\n  const n = sql.length;\n  let unterminated: StripResult[\"unterminated\"] = null;\n\n  while (i < n) {\n    const ch = sql[i];\n    const next = i + 1 < n ? sql[i + 1] : \"\";\n\n    if (ch === \"-\" && next === \"-\") {\n      out.push(\"  \");\n      i += 2;\n      while (i < n && sql[i] !== \"\\n\") {\n        out.push(\" \");\n        i++;\n      }\n      continue;\n    }\n\n    if (ch === \"/\" && next === \"*\") {\n      out.push(\"  \");\n      i += 2;\n      let depth = 1;\n      while (i < n && depth > 0) {\n        if (sql[i] === \"/\" && sql[i + 1] === \"*\") {\n          out.push(\"  \");\n          i += 2;\n          depth++;\n          continue;\n        }\n        if (sql[i] === \"*\" && sql[i + 1] === \"/\") {\n          out.push(\"  \");\n          i += 2;\n          depth--;\n          continue;\n        }\n        out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n        i++;\n      }\n      if (depth > 0) {\n        unterminated = \"block comment\";\n      }\n      continue;\n    }\n\n    if (\n      ch === \"'\" ||\n      (ch === \"E\" && next === \"'\") ||\n      (ch === \"e\" && next === \"'\")\n    ) {\n      if (ch === \"E\" || ch === \"e\") {\n        out.push(\" \");\n        i++;\n      }\n      out.push(\" \");\n      i++;\n      let closed = false;\n      while (i < n) {\n        if (sql[i] === \"'\" && sql[i + 1] === \"'\") {\n          out.push(\"  \");\n          i += 2;\n          continue;\n        }\n        if (sql[i] === \"\\\\\" && sql[i + 1]) {\n          out.push(\"  \");\n          i += 2;\n          continue;\n        }\n        if (sql[i] === \"'\") {\n          out.push(\" \");\n          i++;\n          closed = true;\n          break;\n        }\n        out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n        i++;\n      }\n      if (!closed) unterminated = \"string\";\n      continue;\n    }\n\n    if (ch === '\"') {\n      out.push(\" \");\n      i++;\n      let closed = false;\n      while (i < n) {\n        if (sql[i] === '\"' && sql[i + 1] === '\"') {\n          out.push(\"  \");\n          i += 2;\n          continue;\n        }\n        if (sql[i] === '\"') {\n          out.push(\" \");\n          i++;\n          closed = true;\n          break;\n        }\n        out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n        i++;\n      }\n      if (!closed) unterminated = \"identifier\";\n      continue;\n    }\n\n    if (ch === \"`\") {\n      out.push(\" \");\n      i++;\n      let closed = false;\n      while (i < n) {\n        if (sql[i] === \"`\" && sql[i + 1] === \"`\") {\n          out.push(\"  \");\n          i += 2;\n          continue;\n        }\n        if (sql[i] === \"`\") {\n          out.push(\" \");\n          i++;\n          closed = true;\n          break;\n        }\n        out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n        i++;\n      }\n      if (!closed) unterminated = \"identifier\";\n      continue;\n    }\n\n    if (ch === \"$\") {\n      const tagMatch = sql.slice(i).match(/^\\$([A-Za-z_][A-Za-z0-9_]*)?\\$/);\n      if (tagMatch) {\n        const tag = tagMatch[0];\n        out.push(\" \".repeat(tag.length));\n        i += tag.length;\n        const closeIdx = sql.indexOf(tag, i);\n        if (closeIdx === -1) {\n          while (i < n) {\n            out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n            i++;\n          }\n          unterminated = \"dollar-quoted string\";\n        } else {\n          while (i < closeIdx) {\n            out.push(sql[i] === \"\\n\" ? \"\\n\" : \" \");\n            i++;\n          }\n          out.push(\" \".repeat(tag.length));\n          i += tag.length;\n        }\n        continue;\n      }\n    }\n\n    out.push(ch);\n    i++;\n  }\n\n  return { cleaned: out.join(\"\"), unterminated };\n}\n\n/** Split on unquoted `;`, trim, drop empty segments. */\nfunction splitStatements(cleanedSql: string): string[] {\n  return cleanedSql\n    .split(\";\")\n    .map((s) => s.trim())\n    .filter((s) => s.length > 0);\n}\n\n/** Return the first bareword keyword of a statement, or null if empty. */\nfunction firstKeyword(stmt: string): string | null {\n  const match = stmt.match(/^\\s*([A-Za-z_][A-Za-z0-9_]*)/);\n  return match ? match[1] : null;\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,34 @@
+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> {
+  name: string;
+  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;
+  execute: (args: z.infer<S>) => Promise<string> | string;
+}
+/**
+ * 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;EACtC,IAAA;EACA,WAAA;EACA,MAAA,EAAQ,CAAA;EAHiB;;;;;;;;EAYzB,WAAA,GAAc,eAAA;EACd,OAAA,GAAU,IAAA,EAAM,CAAA,CAAE,KAAA,CAAM,CAAA,MAAO,OAAA;AAAA;;;;;;;;;;iBAYjB,IAAA,WAAe,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,UAAA,CAAW,CAAA,IAAK,YAAA"}

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

@@ -0,0 +1,41 @@
+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);
+	return {
+		type: "function",
+		name: config.name,
+		description: config.description ?? config.name,
+		parameters,
+		...config.annotations ? { annotations: config.annotations } : {},
+		execute: async (args) => {
+			const parsed = config.schema.safeParse(args);
+			if (!parsed.success) return formatZodError(parsed.error, config.name);
+			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  name: string;\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  execute: (args: z.infer<S>) => Promise<string> | string;\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) as unknown as Record<\n    string,\n    unknown\n  >;\n\n  return {\n    type: \"function\",\n    name: config.name,\n    description: config.description ?? config.name,\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, config.name);\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":";;;;;;;;;;;;AA8BA,SAAgB,KAA0B,QAAqC;CAC7E,MAAM,aAAa,iBAAiB,OAAO,OAAO;AAKlD,QAAO;EACL,MAAM;EACN,MAAM,OAAO;EACb,aAAa,OAAO,eAAe,OAAO;EAC1C;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,OAAO,KAAK;AAElD,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,214 @@
+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>;
+}
+/**
+ * Context passed to `baseSystemPrompt` callbacks.
+ */
+interface PromptContext {
+  agentName: string;
+  pluginNames: string[];
+  toolNames: string[];
+}
+type BaseSystemPromptOption = false | string | ((ctx: PromptContext) => string);
+interface AgentDefinition {
+  /** Filled in from the enclosing key when used in `agents: { foo: def }`. */
+  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. */
+  tools?: Record<string, AgentTool>;
+  /** 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:`, `toolkits:`, or `fromPlugin`.
+ *
+ * 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 destructive tool calls. When enabled
+   * (the default), the agents plugin emits an `appkit.approval_pending` SSE
+   * event before executing any tool annotated `destructive: true` 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 annotated `destructive: true`. 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, AgentsPluginConfig, AutoInheritToolsConfig, BaseSystemPromptOption, 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;;;;UAMM,aAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,KAGU,sBAAA,sBAGN,GAAA,EAAK,aAAA;AAAA,UAEM,eAAA;EAXa;EAa5B,IAAA;EAXA;EAaA,YAAA;EAZS;;AAGX;;;EAeE,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAZT;EActB,KAAA,GAAQ,MAAA,SAAe,SAAA;EAZO;EAc9B,MAAA,GAAS,MAAA,SAAe,eAAA;EAJhB;EAMR,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EANQ;;;;;;;;EAeR,SAAA;AAAA;;;;;;;;;;;UAae,sBAAA;EAtBf;EAwBA,IAAA;EAfS;EAiBT,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;;EAE1C,GAAA;EALI;EAOJ,MAAA,GAAS,MAAA,SAAe,eAAA;EAJU;EAMlC,YAAA;EAFwB;EAIxB,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EAAvB;EAEf,KAAA,GAAQ,MAAA,SAAe,SAAA;EAFO;EAI9B,gBAAA,aAA6B,sBAAA;EAFrB;EAIR,WAAA,GAAc,WAAA;EAAA;EAEd,gBAAA,GAAmB,sBAAA;EAOb;;;;;;EAAN,GAAA,GAAM,mBAAA;EAnBG;;;;;;;EA2BT,QAAA;IArBQ,uFAuBN,qBAAA,YArBF;IAuBE,SAAA;EAAA;EArBY;;;;;;;;EA+Bd,MAAA;IAME;;;;;IAAA,2BAAA;IA8BQ;;;;;IAxBR,YAAA;IAuCO;;;;;IAjCP,gBAAA;IAsBE;;;;;;;;;;;;IATF,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;EAS4B;EAP5B,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 * 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\nexport interface AgentDefinition {\n  /** Filled in from the enclosing key when used in `agents: { foo: def }`. */\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  /** Per-agent tool record. Key is the LLM-visible tool-call name. */\n  tools?: Record<string, AgentTool>;\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:`, `toolkits:`, or `fromPlugin`.\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 destructive tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool annotated `destructive: true` and waits\n   * for a `POST /chat/approve` decision from the same user who initiated the\n   * stream. A missing decision after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /** Require human approval for tools annotated `destructive: true`. Default: `true`. */\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":";;;;;AAuOA,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"}