@databricks/appkit 0.66.1 → 0.68.0

package/dist/core/agent/skills/resolve-catalog.js

@@ -0,0 +1,78 @@
+import { createLogger } from "../../../logging/logger.js";
+
+//#region src/core/agent/skills/resolve-catalog.ts
+const logger = createLogger("agents:skills");
+/** Qualified-name scope prefix per source, used only on cross-source collision. */
+const SCOPE_BY_SOURCE = {
+	"bundle-agent": "agent",
+	"bundle-global": "bundle",
+	volume: "volume"
+};
+/**
+* Applies visibility (per-agent auto; global opt-in or auto-inherit) then
+* collision handling: a unique name is addressable bare; a name provided by
+* multiple sources becomes `<scope>:name` per source and the bare name is
+* marked ambiguous (addressing it errors with the alternatives). Two skills
+* with the same name from the *same* source is a fatal config error.
+*/
+function resolveSkillCatalog(input) {
+	const { agentName, agentSkillNames, perAgentSkills, globalSkills, autoInherit } = input;
+	const visible = [...perAgentSkills];
+	if (autoInherit) visible.push(...globalSkills);
+	else if (agentSkillNames && agentSkillNames.length > 0) {
+		const wanted = new Set(agentSkillNames);
+		for (const skill of globalSkills) if (wanted.has(skill.name)) visible.push(skill);
+		const localNames = new Set(perAgentSkills.map((s) => s.name));
+		const globalNames = new Set(globalSkills.map((s) => s.name));
+		for (const want of agentSkillNames) if (!globalNames.has(want) && !localNames.has(want)) logger.warn("Agent '%s' lists skill '%s' in 'skills:', but no global or per-agent skill with that name exists.", agentName, want);
+	}
+	const byName = /* @__PURE__ */ new Map();
+	for (const skill of visible) {
+		const group = byName.get(skill.name) ?? [];
+		group.push(skill);
+		byName.set(skill.name, group);
+	}
+	const byAddress = /* @__PURE__ */ new Map();
+	const ambiguous = /* @__PURE__ */ new Map();
+	for (const [name, group] of byName) {
+		if (group.length === 1) {
+			byAddress.set(name, group[0]);
+			continue;
+		}
+		const alternatives = [];
+		for (const skill of group) {
+			const qualified = `${SCOPE_BY_SOURCE[skill.source]}:${name}`;
+			const existing = byAddress.get(qualified);
+			if (existing) throw new Error(`Agent '${agentName}': two '${skill.source}' skills are both named '${name}' (${existing.dir} and ${skill.dir}). Skill names must be unique within a source.`);
+			byAddress.set(qualified, skill);
+			alternatives.push(qualified);
+		}
+		alternatives.sort();
+		ambiguous.set(name, alternatives);
+		logger.warn("Agent '%s': skill name '%s' is provided by multiple sources; address it as %s.", agentName, name, alternatives.join(" or "));
+	}
+	return {
+		byAddress,
+		ambiguous,
+		catalog: [...byAddress.entries()].map(([address, skill]) => ({
+			name: address,
+			description: skill.description
+		})).sort((a, b) => a.name.localeCompare(b.name))
+	};
+}
+/**
+* Resolves a requested skill name (bare or qualified) against a catalog.
+* Throws a helpful error on ambiguous or unknown names.
+*/
+function resolveSkill(catalog, requested) {
+	const direct = catalog.byAddress.get(requested);
+	if (direct) return direct;
+	const alternatives = catalog.ambiguous.get(requested);
+	if (alternatives) throw new Error(`Skill '${requested}' is ambiguous; specify one of: ${alternatives.join(", ")}.`);
+	const available = [...catalog.byAddress.keys()].sort().join(", ") || "<none>";
+	throw new Error(`Unknown skill '${requested}'. Available: ${available}.`);
+}
+
+//#endregion
+export { resolveSkill, resolveSkillCatalog };
+//# sourceMappingURL=resolve-catalog.js.map

package/dist/core/agent/skills/resolve-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-catalog.js","names":[],"sources":["../../../../src/core/agent/skills/resolve-catalog.ts"],"sourcesContent":["import { createLogger } from \"../../../logging/logger\";\nimport type {\n  ResolvedSkillCatalog,\n  SkillCatalogEntry,\n  SkillDefinition,\n  SkillSource,\n} from \"./types\";\n\nconst logger = createLogger(\"agents:skills\");\n\n/** Qualified-name scope prefix per source, used only on cross-source collision. */\nconst SCOPE_BY_SOURCE: Record<SkillSource, string> = {\n  \"bundle-agent\": \"agent\",\n  \"bundle-global\": \"bundle\",\n  volume: \"volume\",\n};\n\ninterface ResolveCatalogInput {\n  agentName: string;\n  /** The agent's `skills:` frontmatter — opt-in selection from the global pool. */\n  agentSkillNames?: string[];\n  /** Skills private to this agent (`<id>/skills/`), always visible. */\n  perAgentSkills: SkillDefinition[];\n  /** Shared pool (bundle-global + volume), visible only when opted in or inherited. */\n  globalSkills: SkillDefinition[];\n  /** When true, every global skill is visible without an explicit `skills:` list. */\n  autoInherit: boolean;\n}\n\n/**\n * Applies visibility (per-agent auto; global opt-in or auto-inherit) then\n * collision handling: a unique name is addressable bare; a name provided by\n * multiple sources becomes `<scope>:name` per source and the bare name is\n * marked ambiguous (addressing it errors with the alternatives). Two skills\n * with the same name from the *same* source is a fatal config error.\n */\nexport function resolveSkillCatalog(\n  input: ResolveCatalogInput,\n): ResolvedSkillCatalog {\n  const {\n    agentName,\n    agentSkillNames,\n    perAgentSkills,\n    globalSkills,\n    autoInherit,\n  } = input;\n\n  const visible: SkillDefinition[] = [...perAgentSkills];\n  if (autoInherit) {\n    visible.push(...globalSkills);\n  } else if (agentSkillNames && agentSkillNames.length > 0) {\n    const wanted = new Set(agentSkillNames);\n    for (const skill of globalSkills) {\n      if (wanted.has(skill.name)) visible.push(skill);\n    }\n    const localNames = new Set(perAgentSkills.map((s) => s.name));\n    const globalNames = new Set(globalSkills.map((s) => s.name));\n    for (const want of agentSkillNames) {\n      if (!globalNames.has(want) && !localNames.has(want)) {\n        logger.warn(\n          \"Agent '%s' lists skill '%s' in 'skills:', but no global or per-agent skill with that name exists.\",\n          agentName,\n          want,\n        );\n      }\n    }\n  }\n\n  const byName = new Map<string, SkillDefinition[]>();\n  for (const skill of visible) {\n    const group = byName.get(skill.name) ?? [];\n    group.push(skill);\n    byName.set(skill.name, group);\n  }\n\n  const byAddress = new Map<string, SkillDefinition>();\n  const ambiguous = new Map<string, string[]>();\n\n  for (const [name, group] of byName) {\n    if (group.length === 1) {\n      byAddress.set(name, group[0]);\n      continue;\n    }\n\n    const alternatives: string[] = [];\n    for (const skill of group) {\n      const qualified = `${SCOPE_BY_SOURCE[skill.source]}:${name}`;\n      const existing = byAddress.get(qualified);\n      if (existing) {\n        throw new Error(\n          `Agent '${agentName}': two '${skill.source}' skills are both named '${name}' ` +\n            `(${existing.dir} and ${skill.dir}). Skill names must be unique within a source.`,\n        );\n      }\n      byAddress.set(qualified, skill);\n      alternatives.push(qualified);\n    }\n    alternatives.sort();\n    ambiguous.set(name, alternatives);\n    logger.warn(\n      \"Agent '%s': skill name '%s' is provided by multiple sources; address it as %s.\",\n      agentName,\n      name,\n      alternatives.join(\" or \"),\n    );\n  }\n\n  const catalog: SkillCatalogEntry[] = [...byAddress.entries()]\n    .map(([address, skill]) => ({\n      name: address,\n      description: skill.description,\n    }))\n    .sort((a, b) => a.name.localeCompare(b.name));\n\n  return { byAddress, ambiguous, catalog };\n}\n\n/**\n * Resolves a requested skill name (bare or qualified) against a catalog.\n * Throws a helpful error on ambiguous or unknown names.\n */\nexport function resolveSkill(\n  catalog: ResolvedSkillCatalog,\n  requested: string,\n): SkillDefinition {\n  const direct = catalog.byAddress.get(requested);\n  if (direct) return direct;\n\n  const alternatives = catalog.ambiguous.get(requested);\n  if (alternatives) {\n    throw new Error(\n      `Skill '${requested}' is ambiguous; specify one of: ${alternatives.join(\", \")}.`,\n    );\n  }\n\n  const available = [...catalog.byAddress.keys()].sort().join(\", \") || \"<none>\";\n  throw new Error(`Unknown skill '${requested}'. Available: ${available}.`);\n}\n"],"mappings":";;;AAQA,MAAM,SAAS,aAAa,gBAAgB;;AAG5C,MAAM,kBAA+C;CACnD,gBAAgB;CAChB,iBAAiB;CACjB,QAAQ;CACT;;;;;;;;AAqBD,SAAgB,oBACd,OACsB;CACtB,MAAM,EACJ,WACA,iBACA,gBACA,cACA,gBACE;CAEJ,MAAM,UAA6B,CAAC,GAAG,eAAe;AACtD,KAAI,YACF,SAAQ,KAAK,GAAG,aAAa;UACpB,mBAAmB,gBAAgB,SAAS,GAAG;EACxD,MAAM,SAAS,IAAI,IAAI,gBAAgB;AACvC,OAAK,MAAM,SAAS,aAClB,KAAI,OAAO,IAAI,MAAM,KAAK,CAAE,SAAQ,KAAK,MAAM;EAEjD,MAAM,aAAa,IAAI,IAAI,eAAe,KAAK,MAAM,EAAE,KAAK,CAAC;EAC7D,MAAM,cAAc,IAAI,IAAI,aAAa,KAAK,MAAM,EAAE,KAAK,CAAC;AAC5D,OAAK,MAAM,QAAQ,gBACjB,KAAI,CAAC,YAAY,IAAI,KAAK,IAAI,CAAC,WAAW,IAAI,KAAK,CACjD,QAAO,KACL,qGACA,WACA,KACD;;CAKP,MAAM,yBAAS,IAAI,KAAgC;AACnD,MAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,IAAI,EAAE;AAC1C,QAAM,KAAK,MAAM;AACjB,SAAO,IAAI,MAAM,MAAM,MAAM;;CAG/B,MAAM,4BAAY,IAAI,KAA8B;CACpD,MAAM,4BAAY,IAAI,KAAuB;AAE7C,MAAK,MAAM,CAAC,MAAM,UAAU,QAAQ;AAClC,MAAI,MAAM,WAAW,GAAG;AACtB,aAAU,IAAI,MAAM,MAAM,GAAG;AAC7B;;EAGF,MAAM,eAAyB,EAAE;AACjC,OAAK,MAAM,SAAS,OAAO;GACzB,MAAM,YAAY,GAAG,gBAAgB,MAAM,QAAQ,GAAG;GACtD,MAAM,WAAW,UAAU,IAAI,UAAU;AACzC,OAAI,SACF,OAAM,IAAI,MACR,UAAU,UAAU,UAAU,MAAM,OAAO,2BAA2B,KAAK,KACrE,SAAS,IAAI,OAAO,MAAM,IAAI,gDACrC;AAEH,aAAU,IAAI,WAAW,MAAM;AAC/B,gBAAa,KAAK,UAAU;;AAE9B,eAAa,MAAM;AACnB,YAAU,IAAI,MAAM,aAAa;AACjC,SAAO,KACL,kFACA,WACA,MACA,aAAa,KAAK,OAAO,CAC1B;;AAUH,QAAO;EAAE;EAAW;EAAW,SAPM,CAAC,GAAG,UAAU,SAAS,CAAC,CAC1D,KAAK,CAAC,SAAS,YAAY;GAC1B,MAAM;GACN,aAAa,MAAM;GACpB,EAAE,CACF,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,KAAK,CAAC;EAEP;;;;;;AAO1C,SAAgB,aACd,SACA,WACiB;CACjB,MAAM,SAAS,QAAQ,UAAU,IAAI,UAAU;AAC/C,KAAI,OAAQ,QAAO;CAEnB,MAAM,eAAe,QAAQ,UAAU,IAAI,UAAU;AACrD,KAAI,aACF,OAAM,IAAI,MACR,UAAU,UAAU,kCAAkC,aAAa,KAAK,KAAK,CAAC,GAC/E;CAGH,MAAM,YAAY,CAAC,GAAG,QAAQ,UAAU,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;AACrE,OAAM,IAAI,MAAM,kBAAkB,UAAU,gBAAgB,UAAU,GAAG"}

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

@@ -0,0 +1,50 @@
+//#region src/core/agent/skills/types.d.ts
+/** Where a skill was discovered. Drives the qualified name used on collision. */
+type SkillSource = "bundle-agent" | "bundle-global" | "volume";
+/**
+ * A single skill: a `SKILL.md` (frontmatter `name`+`description` + Markdown
+ * body) plus any bundled resource files in the same directory. The body is
+ * loaded into model context on demand (via the `load_skill` tool or a forced
+ * `/skill-name` invocation); only `name`+`description` are always-on in the
+ * prompt catalog.
+ */
+interface SkillDefinition {
+  /** Frontmatter `name`. The addressable skill id. */
+  name: string;
+  /** Frontmatter `description`. Injected into the always-on prompt catalog. */
+  description: string;
+  /** Markdown body — the instructions loaded on demand. */
+  body: string;
+  /** Where the skill came from. */
+  source: SkillSource;
+  /** Absolute directory containing `SKILL.md` and any bundled resources. */
+  dir: string;
+  /** Relative posix paths of bundled resource files (excludes `SKILL.md`). */
+  files: string[];
+  /**
+   * Optional advisory tool allowlist from frontmatter `allowed-tools`. Surfaced
+   * as a hint in v1 — NOT enforced (loading a skill does not restrict the
+   * agent's callable tools).
+   */
+  allowedTools?: string[];
+}
+/** The always-on prompt entry for a skill (what the model sees before loading). */
+interface SkillCatalogEntry {
+  /** Addressable name — bare when unique, `<scope>:name` when collided. */
+  name: string;
+  description: string;
+}
+/**
+ * Per-agent resolved skill catalog: visibility + collision rules applied.
+ * `byAddress` maps every addressable name (bare or qualified) to its skill;
+ * `ambiguous` maps a bare name shadowed by multiple sources to the qualified
+ * alternatives; `catalog` is the always-on prompt list (one entry per address).
+ */
+interface ResolvedSkillCatalog {
+  byAddress: Map<string, SkillDefinition>;
+  ambiguous: Map<string, string[]>;
+  catalog: SkillCatalogEntry[];
+}
+//#endregion
+export { ResolvedSkillCatalog };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../src/core/agent/skills/types.ts"],"mappings":";;KACY,WAAA;;;;;AASZ;;;UAAiB,eAAA;EAEf;EAAA,IAAA;EAIA;EAFA,WAAA;EAIQ;EAFR,IAAA;EAMA;EAJA,MAAA,EAAQ,WAAA;EAUI;EARZ,GAAA;EAYe;EAVf,KAAA;;;;AAsBF;;EAhBE,YAAA;AAAA;;UAIe,iBAAA;EAeN;EAbT,IAAA;EACA,WAAA;AAAA;;;;;;;UASe,oBAAA;EACf,SAAA,EAAW,GAAA,SAAY,eAAA;EACvB,SAAA,EAAW,GAAA;EACX,OAAA,EAAS,iBAAA;AAAA"}

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

@@ -5,6 +5,7 @@ import { HostedSupervisorTool, SupervisorTool } from "../../agents/supervisor-ap
 import { GenerationParams } from "../../agents/databricks.js";
 import { McpHostPolicyConfig } from "../../connectors/mcp/host-policy.js";
 import "../../connectors/mcp/index.js";
+import { ResolvedSkillCatalog } from "./skills/types.js";
 import { FunctionTool } from "./tools/function-tool.js";
 import { HostedTool } from "./tools/hosted-tools.js";
 
@@ -155,6 +156,13 @@ interface AgentDefinition {
   tools?: AgentTools | AgentToolsFn;
   /** Sub-agents, exposed as `agent-<key>` tools on this agent. */
   agents?: Record<string, AgentDefinition>;
+  /**
+   * Names of global skills (shared `skills/` pool or catalog volume) to make
+   * visible to this agent. Per-agent skills under `<id>/skills/` are always
+   * visible and need not be listed. Ignored when the plugin's
+   * `autoInheritSkills` makes every global skill visible.
+   */
+  skills?: string[];
   /** Override the plugin's baseSystemPrompt for this agent only. */
   baseSystemPrompt?: BaseSystemPromptOption;
   maxSteps?: number;
@@ -213,6 +221,28 @@ interface AgentsPluginConfig extends BasePluginConfig {
   tools?: Record<string, AgentTool>;
   /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */
   autoInheritTools?: boolean | AutoInheritToolsConfig;
+  /**
+   * Whether every global skill (shared `skills/` pool or catalog volume) is
+   * visible to an agent without listing it in `skills:` frontmatter. Off by
+   * default so each agent's always-on skill catalog stays lean; accepts a
+   * boolean shorthand or a per-origin `{ file, code }` config, mirroring
+   * {@link autoInheritTools}.
+   */
+  autoInheritSkills?: boolean | AutoInheritToolsConfig;
+  /**
+   * Unity Catalog Volume path for catalog-sourced skills (e.g.
+   * `/Volumes/<catalog>/<schema>/<volume>`). Falls back to the
+   * `DATABRICKS_VOLUME_AGENT_SKILLS` env var. Skills at `<volume>/<name>/SKILL.md`
+   * are discovered at boot and on `reload()` and read as the service principal.
+   */
+  skillsVolume?: string;
+  /**
+   * Identity used to read catalog (volume) skills. v1 supports `"sp"` (default —
+   * a shared, service-principal-readable curated pool). `"obo"` is the reserved
+   * switch point for per-user skill volumes and is not wired yet (falls back to
+   * `"sp"` with a warning).
+   */
+  skillCredentialMode?: "sp" | "obo";
   /** Persistent thread store. Default: in-memory. */
   threadStore?: ThreadStore;
   /** Customize or disable the AppKit base system prompt. */
@@ -316,6 +346,17 @@ type ResolvedToolEntry = {
   source: "hosted-supervisor";
   spec: SupervisorTool;
   def: AgentToolDefinition;
+} | {
+  /**
+   * Built-in skill tools (`load_skill`, `read_skill_file`) injected into
+   * any agent that has a visible skill catalog. Executed in-process by the
+   * agents plugin against the agent's resolved catalog; read-only, so they
+   * bypass the approval gate.
+   */
+  source: "skill";
+  builtin: "load_skill" | "read_skill_file";
+  catalog: ResolvedSkillCatalog;
+  def: AgentToolDefinition;
 };
 interface RegisteredAgent {
   name: string;
@@ -329,6 +370,12 @@ interface RegisteredAgent {
   generationParams?: GenerationParams;
   /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */
   ephemeral?: boolean;
+  /**
+   * Resolved per-agent skill catalog (visibility + collision rules applied).
+   * Present when any skill is visible to this agent; drives the always-on
+   * prompt catalog and `load_skill` dispatch.
+   */
+  skills?: ResolvedSkillCatalog;
 }
 /**
  * Type guard for `ToolkitEntry` — used by the agents plugin to differentiate

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/core/agent/types.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAoBiB,YAAA;EAAA,SACN,YAAA;EACT,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;EACL,WAAA,GAAc,eAAA;EAFd;;;;;;EASA,eAAA;AAAA;AASF;;;;;;AAAA,KAAY,SAAA,GACR,YAAA,GACA,UAAA,GACA,YAAA,GAAY,oBAAA;AAAA,UAGC,cAAA;EAF6C;EAI5D,MAAA;EANE;EAQF,IAAA;EAPc;EASd,MAAA;EATc;EAWd,MAAA,GAAS,MAAA;AAAA;;;;;;;;UAUM,qBAAA;EACf,OAAA,CAAQ,IAAA,GAAO,cAAA,GAAiB,MAAA,SAAe,YAAA;AAAA;;;;;;;;;;;;;;;AA2BjD;;;;;AAKA;;;;;KALY,OAAA,GAAU,MAAA,SAAe,qBAAA;;;;UAKpB,aAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,KAGU,sBAAA,sBAGN,GAAA,EAAK,aAAA;;;;;KAMC,UAAA,GAAa,MAAA,SAAe,SAAA;;;;;;;;;AAaxC;KAFY,YAAA,IAAgB,OAAA,EAAS,OAAA,KAAY,UAAA;AAAA,UAEhC,eAAA;EAmCP;;;;;;;;;;;;;;;;;;EAhBR,IAAA;EA4BQ;;;;;;;EApBR,OAAA;EAgCA;EA9BA,YAAA;EAuCA;;;;;EAjCA,KAAA,GAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA;EAwDM;;;;AAOvC;;;;;;;EAnDE,KAAA,GAAQ,UAAA,GAAa,YAAA;EAmEE;EAjEvB,MAAA,GAAS,MAAA,SAAe,eAAA;EAmEK;;;;;;EA5D7B,MAAA;EA0C0D;EAxC1D,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;EAgDwB;;;;;;;EAxCxB,gBAAA,GAAmB,gBAAA;EA8CI;;;;;;;;EArCvB,SAAA;AAAA;;;;;;;;;;;;UAce,sBAAA;EAqHI;EAnHnB,IAAA;EAwH2B;EAtH3B,IAAA;AAAA;AAAA,UAGe,kBAAA,SAA2B,gBAAA;EA6HjC;;;;;;;;;EAnHT,MAAA,GAAS,MAAA,SAAe,eAAA;EA4GpB;EA1GJ,YAAA;EA4GI;EA1GJ,YAAA,GAAe,YAAA,GAAe,OAAA,CAAQ,YAAA;EA6GlC;EA3GJ,KAAA,GAAQ,MAAA,SAAe,SAAA;EA4GL;EA1GlB,gBAAA,aAA6B,sBAAA;EA2GpB;;;;;;;EAnGT,iBAAA,aAA8B,sBAAA;EA6GrB;;;;;;EAtGT,YAAA;EA+HI;;;;;;EAxHJ,mBAAA;EA6He;EA3Hf,WAAA,GAAc,WAAA;;EAEd,gBAAA,GAAmB,sBAAA;EA6HI;;;;;;EAtHvB,GAAA,GAAM,mBAAA;EAmHN;;;;;;;;;EAzGA,QAAA;IA+GA;;;;;IAzGE,qBAAA,YAmH2B;IAjH3B,SAAA;EAAA;EAwH0B;;;;;;;;EA9G5B,MAAA;;;;;;IAME,2BAAA;;;;;;IAMA,YAAA;;;;;;IAMA,gBAAA;;;;;;;;;;;;;IAaA,iBAAA;EAAA;AAAA;;KAKQ,iBAAA;EAEN,MAAA;EACA,UAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,YAAA,EAAc,YAAA;EACd,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,WAAA;EACA,GAAA,EAAK,mBAAA;AAAA;EAGL,MAAA;EACA,SAAA;EACA,GAAA,EAAK,mBAAA;AAAA;;;;;;;;;;;EAaL,MAAA;EACA,IAAA,EAdwB,cAAA;EAexB,GAAA,EAAK,mBAAA;AAAA;;;;;;;EASL,MAAA;EACA,OAAA;EACA,OAAA,EAAS,oBAAA;EACT,GAAA,EAAK,mBAAA;AAAA;AAAA,UAGM,eAAA;EACf,IAAA;EACA,YAAA;EACA,OAAA,EAAS,YAAA;EACT,SAAA,EAAW,GAAA,SAAY,iBAAA;EACvB,gBAAA,GAAmB,sBAAA;EACnB,QAAA;EACA,SAAA;;EAEA,gBAAA,GAAmB,gBAAA;;EAEnB,SAAA;;;;;;EAMA,MAAA,GAAS,oBAAA;AAAA;;;;;iBAOK,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA"}

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

@@ -1 +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\";\n\nimport type { GenerationParams } from \"../../agents/databricks\";\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), toolkit references from plugins\n * (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools\n * (`supervisorTools.*`).\n */\nexport type AgentTool =\n  | FunctionTool\n  | HostedTool\n  | ToolkitEntry\n  | import(\"../../agents/supervisor-api\").HostedSupervisorTool;\n\nexport interface ToolkitOptions {\n  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */\n  prefix?: string;\n  /** Only include tools whose local name matches one of these. */\n  only?: string[];\n  /** Exclude tools whose local name matches one of these. */\n  except?: string[];\n  /** Remap specific local names to different keys (applied after prefix). */\n  rename?: Record<string, string>;\n}\n\n/**\n * Minimum shape every entry in the {@link Plugins} map must expose. Core\n * plugins (analytics, files, genie, lakebase) implement this directly via\n * their `.toolkit()` method. The agents plugin and standalone `runAgent`\n * synthesize this shape for any registered plugin that doesn't implement\n * `.toolkit()` directly (falling back to `getAgentTools()` walking).\n */\nexport interface PluginToolkitProvider {\n  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;\n}\n\n/**\n * Plugin map passed to the function form of {@link AgentDefinition.tools}.\n * Each entry exposes a `.toolkit(opts?)` method that returns a record of\n * {@link ToolkitEntry} markers ready to be spread into a tool record.\n *\n * AppKit does not statically know which plugins the surrounding\n * `createApp` will register, so this is a plain string-keyed record.\n * Refer to plugins by the name used in `createApp({ plugins: [...] })`;\n * unknown names resolve to `undefined` at runtime.\n *\n * @example\n * ```ts\n * const support = createAgent({\n *   instructions: \"...\",\n *   tools(plugins) {\n *     return {\n *       get_weather: tool({ ... }),\n *       ...plugins.analytics.toolkit(),\n *       ...plugins.files.toolkit({ only: [\"uploads.read\"] }),\n *     };\n *   },\n * });\n * ```\n */\nexport type Plugins = Record<string, PluginToolkitProvider>;\n\n/**\n * Context passed to `baseSystemPrompt` callbacks.\n */\nexport interface PromptContext {\n  agentName: string;\n  pluginNames: string[];\n  toolNames: string[];\n}\n\nexport type BaseSystemPromptOption =\n  | false\n  | string\n  | ((ctx: PromptContext) => string);\n\n/**\n * Per-agent tool record. String keys map to inline tools, toolkit entries,\n * hosted tools, etc.\n */\nexport type AgentTools = Record<string, AgentTool>;\n\n/**\n * Function form of `AgentDefinition.tools`. Receives the typed\n * {@link Plugins} map and returns a tool record. Invoked exactly once at\n * setup (or once per `runAgent` call in standalone mode); the result is\n * cached as the agent's resolved tool record.\n *\n * Use the function form when an agent needs tools from registered plugins.\n * The bare object form is fine when an agent only uses inline tools.\n */\nexport type AgentToolsFn = (plugins: Plugins) => AgentTools;\n\nexport interface AgentDefinition {\n  /**\n   * Stable identifier for the agent. **Optional and informational** —\n   * when the definition is registered via `agents: { foo: def }` (code) or\n   * lives at `server/agents/<id>/agent.md` (markdown), the **registry key\n   * always wins** and `name` is ignored. The agent will be reachable as\n   * `foo` (or `<id>`) regardless of what this field contains.\n   *\n   * Set `name` when:\n   *   - Running standalone via `runAgent({ agent: def })`, where there is\n   *     no enclosing key. The runtime uses it for the agent's slot in\n   *     error messages and OTel spans.\n   *   - Building a definition that may be passed to either form and you\n   *     want a consistent fallback label.\n   *\n   * Setting `name` to a value that differs from the registry key is\n   * harmless but confusing — prefer keeping them aligned or omitting `name`\n   * entirely.\n   */\n  name?: string;\n  /**\n   * Marks this agent as the default one chosen when a client doesn't name an\n   * agent. Mirrors markdown frontmatter `default: true`. When several agents\n   * set it, a code (discovered) agent wins over a markdown one, then the\n   * lowest id; an explicit `agents({ defaultAgent })` always overrides it.\n   * Defaults to `false`.\n   */\n  default?: boolean;\n  /** System prompt body. For markdown-loaded agents this is the file body. */\n  instructions: string;\n  /**\n   * Model adapter (or endpoint-name string sugar for\n   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —\n   * falls back to the plugin's `defaultModel`.\n   */\n  model?: AgentAdapter | Promise<AgentAdapter> | string;\n  /**\n   * Per-agent tool record. Key is the LLM-visible tool-call name.\n   *\n   * Accepts either a plain record (for agents that only use inline tools)\n   * or a function `(plugins) => Record<string, AgentTool>` that receives\n   * the typed {@link Plugins} map and returns a tool record (for agents\n   * that pull tools from registered plugins).\n   *\n   * The function is invoked once at agent setup; the result is cached.\n   * Don't put per-request logic in there.\n   */\n  tools?: AgentTools | AgentToolsFn;\n  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */\n  agents?: Record<string, AgentDefinition>;\n  /** Override the plugin's baseSystemPrompt for this agent only. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /**\n   * Optional generation parameters (`temperature`, `top_p`, `stop`,\n   * `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible\n   * serving request body. Only set keys are sent. Applied only when AppKit\n   * builds the adapter itself (string or omitted `model`); when you pass a\n   * pre-built `AgentAdapter`, configure generation params on it directly.\n   */\n  generationParams?: GenerationParams;\n  /**\n   * When true, the thread used for a chat request against this agent is\n   * deleted from `ThreadStore` after the stream completes (success or\n   * failure). Use for stateless one-shot agents — e.g. autocomplete, where\n   * each request is independent and retaining history would both poison\n   * future calls and accumulate unbounded state in the default\n   * `InMemoryThreadStore`. Defaults to `false`.\n   */\n  ephemeral?: boolean;\n}\n\n/**\n * Auto-inherit configuration. When enabled for a given agent origin, agents\n * with no explicit `tools:` declaration receive every registered ToolProvider\n * plugin tool whose author marked `autoInheritable: true`. Tools without that\n * flag — destructive, state-mutating, or privilege-sensitive — never spread\n * automatically and must be wired via `tools:` (object or function form in\n * code, `plugin:NAME` entries in markdown frontmatter).\n *\n * Defaults are `false` for both origins (safe-by-default): developers must\n * consciously opt an origin in to any auto-inherit behaviour.\n */\nexport interface AutoInheritToolsConfig {\n  /** Default for agents loaded from markdown files. Default: `false`. */\n  file?: boolean;\n  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */\n  code?: boolean;\n}\n\nexport interface AgentsPluginConfig extends BasePluginConfig {\n  /**\n   * @deprecated Put each code agent in its own folder under\n   * `server/agents/<id>/agent.ts` (`export default createAgent({ ... })`); it is\n   * discovered automatically at startup and the call collapses to\n   * `agents({ ... })` with no map. Still honored for backward compatibility\n   * (emits a one-time deprecation warning) but will be removed in a future\n   * minor. If both discovery and this map define the same id, discovery wins\n   * and the map entry is ignored.\n   */\n  agents?: Record<string, AgentDefinition>;\n  /** Agent used when clients don't specify one. Precedence: this value, else a code agent with `default: true`, else a markdown agent with `default: true`, else the first-registered agent. */\n  defaultAgent?: string;\n  /** Default model for agents that don't specify their own (in code or frontmatter). */\n  defaultModel?: AgentAdapter | Promise<AgentAdapter> | string;\n  /** Ambient tool library. Keys may be referenced by markdown frontmatter via `tools: [key1, key2]`. */\n  tools?: Record<string, AgentTool>;\n  /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */\n  autoInheritTools?: boolean | AutoInheritToolsConfig;\n  /** Persistent thread store. Default: in-memory. */\n  threadStore?: ThreadStore;\n  /** Customize or disable the AppKit base system prompt. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  /**\n   * MCP server host policy. By default only same-origin Databricks workspace\n   * URLs may be used as MCP endpoints; custom hosts must be explicitly\n   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded\n   * to non-workspace hosts.\n   */\n  mcp?: McpHostPolicyConfig;\n  /**\n   * Human-in-the-loop approval gate for mutating tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool whose annotation flags it as mutating —\n   * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n   * `destructive: true` boolean — and waits for a `POST /api/agents/approve`\n   * decision from the same user who initiated the stream. A missing decision\n   * after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /**\n     * Require human approval for tools that mutate state. Triggered by\n     * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n     * `destructive: true` boolean. Default: `true`.\n     */\n    requireForDestructive?: boolean;\n    /** Milliseconds to wait before auto-denying. Default: 60_000. */\n    timeoutMs?: number;\n  };\n  /**\n   * Runtime resource limits applied during agent execution. Defaults are\n   * tuned to protect a single-instance deployment from a misbehaving user or\n   * a runaway prompt injection; tighten or relax as appropriate for the\n   * deployment's scale and trust model. Request-body caps (chat message\n   * size, invocations input size / length) are enforced statically by the\n   * Zod schemas and are not configurable here.\n   */\n  limits?: {\n    /**\n     * Max concurrent chat streams a single user may have open. Subsequent\n     * `POST /chat` requests from that user while at-limit are rejected with\n     * HTTP 429. Default: `5`.\n     */\n    maxConcurrentStreamsPerUser?: number;\n    /**\n     * Max tool invocations per agent run (across the full tool-call graph,\n     * including sub-agent invocations). A run that exceeds the budget is\n     * aborted with a terminal error event. Default: `50`.\n     */\n    maxToolCalls?: number;\n    /**\n     * Max sub-agent recursion depth. Protects against a prompt-injected\n     * agent that delegates to a sub-agent which in turn delegates back to\n     * itself (directly or transitively). Default: `3`.\n     */\n    maxSubAgentDepth?: number;\n    /**\n     * Per-call timeout for tools dispatched through `PluginContext`\n     * (toolkit-routed tools — analytics SQL warehouse queries, Genie\n     * messages, Lakebase queries). Independent of `maxToolCalls`: the\n     * budget caps how many tools fire per run, this caps how long any\n     * single tool call may run. The signal handed to plugin tool\n     * implementations combines this timeout with the parent stream's\n     * abort signal via `AbortSignal.any`. Function and MCP tools have\n     * their own timeouts in their respective adapters and ignore this\n     * setting. Default: `300_000` (5 minutes) — generous enough for cold\n     * SQL Warehouse round-trips and long Genie conversations.\n     */\n    toolCallTimeoutMs?: number;\n  };\n}\n\n/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */\nexport type ResolvedToolEntry =\n  | {\n      source: \"toolkit\";\n      pluginName: string;\n      localName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"function\";\n      functionTool: FunctionTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"mcp\";\n      mcpToolName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"subagent\";\n      agentName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      /**\n       * Adapter-side hosted tool (executed by the model-host, not by the\n       * Node process). Today: Supervisor API hosted tools (Genie spaces,\n       * UC functions, etc.). The `spec` is opaque to the agents plugin —\n       * it routes the entry into `AgentInput.extensions` for the adapter\n       * that declared the matching `acceptsExtensions` key. `def` is a\n       * synthetic placeholder kept so the index has a uniform shape; it\n       * is intentionally NOT included in the `tools` array passed to\n       * `adapter.run()` (those entries are not callable functions).\n       */\n      source: \"hosted-supervisor\";\n      spec: import(\"../../agents/supervisor-api\").SupervisorTool;\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.generationParams`. */\n  generationParams?: GenerationParams;\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":";;;;;AA6WA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}
+{"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\";\n\nimport type { GenerationParams } from \"../../agents/databricks\";\nimport type { McpHostPolicyConfig } from \"../../connectors/mcp\";\nimport type { ResolvedSkillCatalog } from \"./skills/types\";\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), toolkit references from plugins\n * (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools\n * (`supervisorTools.*`).\n */\nexport type AgentTool =\n  | FunctionTool\n  | HostedTool\n  | ToolkitEntry\n  | import(\"../../agents/supervisor-api\").HostedSupervisorTool;\n\nexport interface ToolkitOptions {\n  /** Key prefix to prepend to each tool's local name. Defaults to `${pluginName}.`. */\n  prefix?: string;\n  /** Only include tools whose local name matches one of these. */\n  only?: string[];\n  /** Exclude tools whose local name matches one of these. */\n  except?: string[];\n  /** Remap specific local names to different keys (applied after prefix). */\n  rename?: Record<string, string>;\n}\n\n/**\n * Minimum shape every entry in the {@link Plugins} map must expose. Core\n * plugins (analytics, files, genie, lakebase) implement this directly via\n * their `.toolkit()` method. The agents plugin and standalone `runAgent`\n * synthesize this shape for any registered plugin that doesn't implement\n * `.toolkit()` directly (falling back to `getAgentTools()` walking).\n */\nexport interface PluginToolkitProvider {\n  toolkit(opts?: ToolkitOptions): Record<string, ToolkitEntry>;\n}\n\n/**\n * Plugin map passed to the function form of {@link AgentDefinition.tools}.\n * Each entry exposes a `.toolkit(opts?)` method that returns a record of\n * {@link ToolkitEntry} markers ready to be spread into a tool record.\n *\n * AppKit does not statically know which plugins the surrounding\n * `createApp` will register, so this is a plain string-keyed record.\n * Refer to plugins by the name used in `createApp({ plugins: [...] })`;\n * unknown names resolve to `undefined` at runtime.\n *\n * @example\n * ```ts\n * const support = createAgent({\n *   instructions: \"...\",\n *   tools(plugins) {\n *     return {\n *       get_weather: tool({ ... }),\n *       ...plugins.analytics.toolkit(),\n *       ...plugins.files.toolkit({ only: [\"uploads.read\"] }),\n *     };\n *   },\n * });\n * ```\n */\nexport type Plugins = Record<string, PluginToolkitProvider>;\n\n/**\n * Context passed to `baseSystemPrompt` callbacks.\n */\nexport interface PromptContext {\n  agentName: string;\n  pluginNames: string[];\n  toolNames: string[];\n}\n\nexport type BaseSystemPromptOption =\n  | false\n  | string\n  | ((ctx: PromptContext) => string);\n\n/**\n * Per-agent tool record. String keys map to inline tools, toolkit entries,\n * hosted tools, etc.\n */\nexport type AgentTools = Record<string, AgentTool>;\n\n/**\n * Function form of `AgentDefinition.tools`. Receives the typed\n * {@link Plugins} map and returns a tool record. Invoked exactly once at\n * setup (or once per `runAgent` call in standalone mode); the result is\n * cached as the agent's resolved tool record.\n *\n * Use the function form when an agent needs tools from registered plugins.\n * The bare object form is fine when an agent only uses inline tools.\n */\nexport type AgentToolsFn = (plugins: Plugins) => AgentTools;\n\nexport interface AgentDefinition {\n  /**\n   * Stable identifier for the agent. **Optional and informational** —\n   * when the definition is registered via `agents: { foo: def }` (code) or\n   * lives at `server/agents/<id>/agent.md` (markdown), the **registry key\n   * always wins** and `name` is ignored. The agent will be reachable as\n   * `foo` (or `<id>`) regardless of what this field contains.\n   *\n   * Set `name` when:\n   *   - Running standalone via `runAgent({ agent: def })`, where there is\n   *     no enclosing key. The runtime uses it for the agent's slot in\n   *     error messages and OTel spans.\n   *   - Building a definition that may be passed to either form and you\n   *     want a consistent fallback label.\n   *\n   * Setting `name` to a value that differs from the registry key is\n   * harmless but confusing — prefer keeping them aligned or omitting `name`\n   * entirely.\n   */\n  name?: string;\n  /**\n   * Marks this agent as the default one chosen when a client doesn't name an\n   * agent. Mirrors markdown frontmatter `default: true`. When several agents\n   * set it, a code (discovered) agent wins over a markdown one, then the\n   * lowest id; an explicit `agents({ defaultAgent })` always overrides it.\n   * Defaults to `false`.\n   */\n  default?: boolean;\n  /** System prompt body. For markdown-loaded agents this is the file body. */\n  instructions: string;\n  /**\n   * Model adapter (or endpoint-name string sugar for\n   * `DatabricksAdapter.fromServingEndpoint({ endpointName })`). Optional —\n   * falls back to the plugin's `defaultModel`.\n   */\n  model?: AgentAdapter | Promise<AgentAdapter> | string;\n  /**\n   * Per-agent tool record. Key is the LLM-visible tool-call name.\n   *\n   * Accepts either a plain record (for agents that only use inline tools)\n   * or a function `(plugins) => Record<string, AgentTool>` that receives\n   * the typed {@link Plugins} map and returns a tool record (for agents\n   * that pull tools from registered plugins).\n   *\n   * The function is invoked once at agent setup; the result is cached.\n   * Don't put per-request logic in there.\n   */\n  tools?: AgentTools | AgentToolsFn;\n  /** Sub-agents, exposed as `agent-<key>` tools on this agent. */\n  agents?: Record<string, AgentDefinition>;\n  /**\n   * Names of global skills (shared `skills/` pool or catalog volume) to make\n   * visible to this agent. Per-agent skills under `<id>/skills/` are always\n   * visible and need not be listed. Ignored when the plugin's\n   * `autoInheritSkills` makes every global skill visible.\n   */\n  skills?: string[];\n  /** Override the plugin's baseSystemPrompt for this agent only. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  maxSteps?: number;\n  maxTokens?: number;\n  /**\n   * Optional generation parameters (`temperature`, `top_p`, `stop`,\n   * `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible\n   * serving request body. Only set keys are sent. Applied only when AppKit\n   * builds the adapter itself (string or omitted `model`); when you pass a\n   * pre-built `AgentAdapter`, configure generation params on it directly.\n   */\n  generationParams?: GenerationParams;\n  /**\n   * When true, the thread used for a chat request against this agent is\n   * deleted from `ThreadStore` after the stream completes (success or\n   * failure). Use for stateless one-shot agents — e.g. autocomplete, where\n   * each request is independent and retaining history would both poison\n   * future calls and accumulate unbounded state in the default\n   * `InMemoryThreadStore`. Defaults to `false`.\n   */\n  ephemeral?: boolean;\n}\n\n/**\n * Auto-inherit configuration. When enabled for a given agent origin, agents\n * with no explicit `tools:` declaration receive every registered ToolProvider\n * plugin tool whose author marked `autoInheritable: true`. Tools without that\n * flag — destructive, state-mutating, or privilege-sensitive — never spread\n * automatically and must be wired via `tools:` (object or function form in\n * code, `plugin:NAME` entries in markdown frontmatter).\n *\n * Defaults are `false` for both origins (safe-by-default): developers must\n * consciously opt an origin in to any auto-inherit behaviour.\n */\nexport interface AutoInheritToolsConfig {\n  /** Default for agents loaded from markdown files. Default: `false`. */\n  file?: boolean;\n  /** Default for code-defined agents (via `agents: { foo: createAgent(...) }`). Default: `false`. */\n  code?: boolean;\n}\n\nexport interface AgentsPluginConfig extends BasePluginConfig {\n  /**\n   * @deprecated Put each code agent in its own folder under\n   * `server/agents/<id>/agent.ts` (`export default createAgent({ ... })`); it is\n   * discovered automatically at startup and the call collapses to\n   * `agents({ ... })` with no map. Still honored for backward compatibility\n   * (emits a one-time deprecation warning) but will be removed in a future\n   * minor. If both discovery and this map define the same id, discovery wins\n   * and the map entry is ignored.\n   */\n  agents?: Record<string, AgentDefinition>;\n  /** Agent used when clients don't specify one. Precedence: this value, else a code agent with `default: true`, else a markdown agent with `default: true`, else the first-registered agent. */\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  /**\n   * Whether every global skill (shared `skills/` pool or catalog volume) is\n   * visible to an agent without listing it in `skills:` frontmatter. Off by\n   * default so each agent's always-on skill catalog stays lean; accepts a\n   * boolean shorthand or a per-origin `{ file, code }` config, mirroring\n   * {@link autoInheritTools}.\n   */\n  autoInheritSkills?: boolean | AutoInheritToolsConfig;\n  /**\n   * Unity Catalog Volume path for catalog-sourced skills (e.g.\n   * `/Volumes/<catalog>/<schema>/<volume>`). Falls back to the\n   * `DATABRICKS_VOLUME_AGENT_SKILLS` env var. Skills at `<volume>/<name>/SKILL.md`\n   * are discovered at boot and on `reload()` and read as the service principal.\n   */\n  skillsVolume?: string;\n  /**\n   * Identity used to read catalog (volume) skills. v1 supports `\"sp\"` (default —\n   * a shared, service-principal-readable curated pool). `\"obo\"` is the reserved\n   * switch point for per-user skill volumes and is not wired yet (falls back to\n   * `\"sp\"` with a warning).\n   */\n  skillCredentialMode?: \"sp\" | \"obo\";\n  /** Persistent thread store. Default: in-memory. */\n  threadStore?: ThreadStore;\n  /** Customize or disable the AppKit base system prompt. */\n  baseSystemPrompt?: BaseSystemPromptOption;\n  /**\n   * MCP server host policy. By default only same-origin Databricks workspace\n   * URLs may be used as MCP endpoints; custom hosts must be explicitly\n   * allowlisted here. Workspace credentials (SP / OBO) are never forwarded\n   * to non-workspace hosts.\n   */\n  mcp?: McpHostPolicyConfig;\n  /**\n   * Human-in-the-loop approval gate for mutating tool calls. When enabled\n   * (the default), the agents plugin emits an `appkit.approval_pending` SSE\n   * event before executing any tool whose annotation flags it as mutating —\n   * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n   * `destructive: true` boolean — and waits for a `POST /api/agents/approve`\n   * decision from the same user who initiated the stream. A missing decision\n   * after `timeoutMs` auto-denies the call.\n   */\n  approval?: {\n    /**\n     * Require human approval for tools that mutate state. Triggered by\n     * `effect: \"write\" | \"update\" | \"destructive\"` (preferred) or the legacy\n     * `destructive: true` boolean. Default: `true`.\n     */\n    requireForDestructive?: boolean;\n    /** Milliseconds to wait before auto-denying. Default: 60_000. */\n    timeoutMs?: number;\n  };\n  /**\n   * Runtime resource limits applied during agent execution. Defaults are\n   * tuned to protect a single-instance deployment from a misbehaving user or\n   * a runaway prompt injection; tighten or relax as appropriate for the\n   * deployment's scale and trust model. Request-body caps (chat message\n   * size, invocations input size / length) are enforced statically by the\n   * Zod schemas and are not configurable here.\n   */\n  limits?: {\n    /**\n     * Max concurrent chat streams a single user may have open. Subsequent\n     * `POST /chat` requests from that user while at-limit are rejected with\n     * HTTP 429. Default: `5`.\n     */\n    maxConcurrentStreamsPerUser?: number;\n    /**\n     * Max tool invocations per agent run (across the full tool-call graph,\n     * including sub-agent invocations). A run that exceeds the budget is\n     * aborted with a terminal error event. Default: `50`.\n     */\n    maxToolCalls?: number;\n    /**\n     * Max sub-agent recursion depth. Protects against a prompt-injected\n     * agent that delegates to a sub-agent which in turn delegates back to\n     * itself (directly or transitively). Default: `3`.\n     */\n    maxSubAgentDepth?: number;\n    /**\n     * Per-call timeout for tools dispatched through `PluginContext`\n     * (toolkit-routed tools — analytics SQL warehouse queries, Genie\n     * messages, Lakebase queries). Independent of `maxToolCalls`: the\n     * budget caps how many tools fire per run, this caps how long any\n     * single tool call may run. The signal handed to plugin tool\n     * implementations combines this timeout with the parent stream's\n     * abort signal via `AbortSignal.any`. Function and MCP tools have\n     * their own timeouts in their respective adapters and ignore this\n     * setting. Default: `300_000` (5 minutes) — generous enough for cold\n     * SQL Warehouse round-trips and long Genie conversations.\n     */\n    toolCallTimeoutMs?: number;\n  };\n}\n\n/** Internal tool-index entry after a tool record has been resolved to a dispatchable form. */\nexport type ResolvedToolEntry =\n  | {\n      source: \"toolkit\";\n      pluginName: string;\n      localName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"function\";\n      functionTool: FunctionTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"mcp\";\n      mcpToolName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      source: \"subagent\";\n      agentName: string;\n      def: AgentToolDefinition;\n    }\n  | {\n      /**\n       * Adapter-side hosted tool (executed by the model-host, not by the\n       * Node process). Today: Supervisor API hosted tools (Genie spaces,\n       * UC functions, etc.). The `spec` is opaque to the agents plugin —\n       * it routes the entry into `AgentInput.extensions` for the adapter\n       * that declared the matching `acceptsExtensions` key. `def` is a\n       * synthetic placeholder kept so the index has a uniform shape; it\n       * is intentionally NOT included in the `tools` array passed to\n       * `adapter.run()` (those entries are not callable functions).\n       */\n      source: \"hosted-supervisor\";\n      spec: import(\"../../agents/supervisor-api\").SupervisorTool;\n      def: AgentToolDefinition;\n    }\n  | {\n      /**\n       * Built-in skill tools (`load_skill`, `read_skill_file`) injected into\n       * any agent that has a visible skill catalog. Executed in-process by the\n       * agents plugin against the agent's resolved catalog; read-only, so they\n       * bypass the approval gate.\n       */\n      source: \"skill\";\n      builtin: \"load_skill\" | \"read_skill_file\";\n      catalog: ResolvedSkillCatalog;\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.generationParams`. */\n  generationParams?: GenerationParams;\n  /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */\n  ephemeral?: boolean;\n  /**\n   * Resolved per-agent skill catalog (visibility + collision rules applied).\n   * Present when any skill is visible to this agent; drives the always-on\n   * prompt catalog and `load_skill` dispatch.\n   */\n  skills?: ResolvedSkillCatalog;\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":";;;;;AA6ZA,SAAgB,eAAe,OAAuC;AACpE,QACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB"}

package/dist/database/contract/index.js

@@ -1,3 +1,3 @@
-import { DEFAULT_LIMIT, FILTER_OPERATORS, IN_CAP, MAX_INCLUDES, MAX_LIMIT, MAX_OFFSET, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, MAX_WHERE_GROUP_ITEMS, isFilterOperator } from "./wire.js";
+import { DEFAULT_LIMIT, FILTER_OPERATORS, IN_CAP, MAX_INCLUDES, MAX_INCLUDE_DEPTH, MAX_INCLUDE_NODES, MAX_LIMIT, MAX_OFFSET, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, MAX_WHERE_GROUP_ITEMS, isFilterOperator } from "./wire.js";
 
 export {  };

package/dist/database/contract/wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wire.d.ts","names":[],"sources":["../../../src/database/contract/wire.ts"],"mappings":";;KAkBY,OAAA;;KAEA,cAAA"}
+{"version":3,"file":"wire.d.ts","names":[],"sources":["../../../src/database/contract/wire.ts"],"mappings":";;KAsBY,OAAA;;KAEA,cAAA"}

package/dist/database/contract/wire.js

@@ -15,6 +15,10 @@ const MAX_WHERE_DEPTH = 5;
 const MAX_WHERE_GROUP_ITEMS = 20;
 /** Max column conditions accepted across one runtime predicate tree. */
 const MAX_WHERE_CONDITIONS = 50;
+/** Max number of relation edges one include path may traverse. */
+const MAX_INCLUDE_DEPTH = 2;
+/** Max number of relation nodes across a complete include tree. */
+const MAX_INCLUDE_NODES = 25;
 /** Filter operators usable in the runtime WHERE translator and the `where` spec type. */
 const FILTER_OPERATORS = Object.freeze([
 	"eq",
@@ -33,5 +37,5 @@ function isFilterOperator(token) {
 }
 
 //#endregion
-export { DEFAULT_LIMIT, FILTER_OPERATORS, IN_CAP, MAX_INCLUDES, MAX_LIMIT, MAX_OFFSET, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, MAX_WHERE_GROUP_ITEMS, isFilterOperator };
+export { DEFAULT_LIMIT, FILTER_OPERATORS, IN_CAP, MAX_INCLUDES, MAX_INCLUDE_DEPTH, MAX_INCLUDE_NODES, MAX_LIMIT, MAX_OFFSET, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, MAX_WHERE_GROUP_ITEMS, isFilterOperator };
 //# sourceMappingURL=wire.js.map

package/dist/database/contract/wire.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire.js","names":[],"sources":["../../../src/database/contract/wire.ts"],"sourcesContent":["/** Max number of values allowed in an `in.(…)` list. */\nexport const IN_CAP = 100;\n/** Hard ceiling for a runtime query limit. */\nexport const MAX_LIMIT = 500;\n/** Hard ceiling for a runtime query offset. OFFSET scans are unbounded in cost. */\nexport const MAX_OFFSET = 10_000;\n/** Default page size when no `.limit()` is supplied. */\nexport const DEFAULT_LIMIT = 50;\n/** Max number of relations resolvable in a single `.include()`. */\nexport const MAX_INCLUDES = 10;\n/** Max nesting depth of `and`/`or` groups in one runtime predicate. */\nexport const MAX_WHERE_DEPTH = 5;\n/** Max members accepted by one runtime `and`/`or` group. */\nexport const MAX_WHERE_GROUP_ITEMS = 20;\n/** Max column conditions accepted across one runtime predicate tree. */\nexport const MAX_WHERE_CONDITIONS = 50;\n\n/** Scalar values accepted by primary-key operations. */\nexport type IdValue = string | number | bigint;\n/** Ordering accepted by typed clients and the runtime adapter. */\nexport type OrderDirection = \"asc\" | \"desc\";\n/** Filter operators usable in the runtime WHERE translator and the `where` spec type. */\nexport const FILTER_OPERATORS = Object.freeze([\n  \"eq\",\n  \"neq\",\n  \"gt\",\n  \"gte\",\n  \"lt\",\n  \"lte\",\n  \"like\",\n  \"ilike\",\n  \"in\",\n  \"is\",\n] as const);\n\nexport type FilterOperator = (typeof FILTER_OPERATORS)[number];\n\nexport function isFilterOperator(token: string): token is FilterOperator {\n  return (FILTER_OPERATORS as readonly string[]).includes(token);\n}\n"],"mappings":";;AACA,MAAa,SAAS;;AAEtB,MAAa,YAAY;;AAEzB,MAAa,aAAa;;AAE1B,MAAa,gBAAgB;;AAE7B,MAAa,eAAe;;AAE5B,MAAa,kBAAkB;;AAE/B,MAAa,wBAAwB;;AAErC,MAAa,uBAAuB;;AAOpC,MAAa,mBAAmB,OAAO,OAAO;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAU;AAIX,SAAgB,iBAAiB,OAAwC;AACvE,QAAQ,iBAAuC,SAAS,MAAM"}
+{"version":3,"file":"wire.js","names":[],"sources":["../../../src/database/contract/wire.ts"],"sourcesContent":["/** Max number of values allowed in an `in.(…)` list. */\nexport const IN_CAP = 100;\n/** Hard ceiling for a runtime query limit. */\nexport const MAX_LIMIT = 500;\n/** Hard ceiling for a runtime query offset. OFFSET scans are unbounded in cost. */\nexport const MAX_OFFSET = 10_000;\n/** Default page size when no `.limit()` is supplied. */\nexport const DEFAULT_LIMIT = 50;\n/** Max number of relations resolvable in a single `.include()`. */\nexport const MAX_INCLUDES = 10;\n/** Max nesting depth of `and`/`or` groups in one runtime predicate. */\nexport const MAX_WHERE_DEPTH = 5;\n/** Max members accepted by one runtime `and`/`or` group. */\nexport const MAX_WHERE_GROUP_ITEMS = 20;\n/** Max column conditions accepted across one runtime predicate tree. */\nexport const MAX_WHERE_CONDITIONS = 50;\n/** Max number of relation edges one include path may traverse. */\nexport const MAX_INCLUDE_DEPTH = 2;\n/** Max number of relation nodes across a complete include tree. */\nexport const MAX_INCLUDE_NODES = 25;\n\n/** Scalar values accepted by primary-key operations. */\nexport type IdValue = string | number | bigint;\n/** Ordering accepted by typed clients and the runtime adapter. */\nexport type OrderDirection = \"asc\" | \"desc\";\n/** Filter operators usable in the runtime WHERE translator and the `where` spec type. */\nexport const FILTER_OPERATORS = Object.freeze([\n  \"eq\",\n  \"neq\",\n  \"gt\",\n  \"gte\",\n  \"lt\",\n  \"lte\",\n  \"like\",\n  \"ilike\",\n  \"in\",\n  \"is\",\n] as const);\n\nexport type FilterOperator = (typeof FILTER_OPERATORS)[number];\n\nexport function isFilterOperator(token: string): token is FilterOperator {\n  return (FILTER_OPERATORS as readonly string[]).includes(token);\n}\n"],"mappings":";;AACA,MAAa,SAAS;;AAEtB,MAAa,YAAY;;AAEzB,MAAa,aAAa;;AAE1B,MAAa,gBAAgB;;AAE7B,MAAa,eAAe;;AAE5B,MAAa,kBAAkB;;AAE/B,MAAa,wBAAwB;;AAErC,MAAa,uBAAuB;;AAEpC,MAAa,oBAAoB;;AAEjC,MAAa,oBAAoB;;AAOjC,MAAa,mBAAmB,OAAO,OAAO;CAC5C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAU;AAIX,SAAgB,iBAAiB,OAAwC;AACvE,QAAQ,iBAAuC,SAAS,MAAM"}

package/dist/database/errors.js

@@ -9,6 +9,10 @@ const definitions = {
 		message: "Invalid database request",
 		statusCode: 400
 	},
+	NOT_FOUND: {
+		message: "Database record not found",
+		statusCode: 404
+	},
 	CONFLICT: {
 		message: "Database conflict",
 		statusCode: 409
@@ -21,6 +25,10 @@ const definitions = {
 		message: "Database operation temporarily unavailable",
 		statusCode: 503
 	},
+	PAYLOAD_TOO_LARGE: {
+		message: "Database response is too large",
+		statusCode: 413
+	},
 	INTERNAL: {
 		message: "Database operation failed",
 		statusCode: 500
@@ -33,7 +41,9 @@ const definitions = {
 const categoryByStatus = {
 	400: "INVALID_REQUEST",
 	403: "FORBIDDEN",
+	404: "NOT_FOUND",
 	409: "CONFLICT",
+	413: "PAYLOAD_TOO_LARGE",
 	503: "TRANSIENT"
 };
 /** AppKit-facing database failure with stable metadata and no driver details. */
@@ -41,11 +51,12 @@ var DatabasePluginError = class extends AppKitError {
 	code = "DATABASE_PLUGIN_ERROR";
 	isRetryable;
 	statusCode;
-	constructor(category, phase, runtimeMessage) {
+	constructor(category, phase, runtimeMessage, details) {
 		const definition = definitions[category];
 		super(phase === "runtime" && runtimeMessage ? runtimeMessage : definition.message, { clientMessage: definition.message });
 		this.category = category;
 		this.phase = phase;
+		this.details = details;
 		this.statusCode = definition.statusCode;
 		this.isRetryable = category === "TRANSIENT";
 		this.name = "DatabasePluginError";
@@ -55,10 +66,35 @@ var DatabasePluginError = class extends AppKitError {
 function invalidDatabaseRequest(runtimeMessage) {
 	return new DatabasePluginError("INVALID_REQUEST", "runtime", runtimeMessage);
 }
+/** Refuse to publish a plugin whose configuration cannot be honored. */
+function databaseSetupFailed() {
+	return new DatabasePluginError("SETUP_FAILED", "setup");
+}
+/** Reject untrusted request input, naming the field but never its value. */
+function invalidDatabaseInput(path, message) {
+	return new DatabasePluginError("INVALID_REQUEST", "read", void 0, [{
+		path,
+		message
+	}]);
+}
+/**
+* Name an unknown failure without its payload. A driver error carries the SQL
+* text and its bound row values (for example a `DrizzleQueryError` retains
+* `query` and `params`), so only constructor names walk into the log.
+*/
+function describeUnclassifiedError(error) {
+	const names = [];
+	let current = error;
+	for (let depth = 0; depth < 5 && current instanceof Error; depth++) {
+		names.push(current.name);
+		current = current.cause;
+	}
+	return names.length > 0 ? names.join(" <- ") : typeof error;
+}
 /** Add operation context without retaining an unknown error's details. */
 function classifyDatabaseError(error, phase) {
 	if (error instanceof DatabasePluginError) return error.phase === phase ? error : new DatabasePluginError(error.category, phase);
-	logger.error("Unclassified database error during %s: %O", phase, error);
+	logger.error("Unclassified database error during %s (%s)", phase, describeUnclassifiedError(error));
 	return new DatabasePluginError("INTERNAL", phase);
 }
 /** Restore the safe database category carried through `Plugin.execute()`. */
@@ -67,5 +103,5 @@ function databaseErrorFromStatus(status, phase) {
 }
 
 //#endregion
-export { DatabasePluginError, classifyDatabaseError, databaseErrorFromStatus, invalidDatabaseRequest };
+export { DatabasePluginError, classifyDatabaseError, databaseErrorFromStatus, databaseSetupFailed, invalidDatabaseInput, invalidDatabaseRequest };
 //# sourceMappingURL=errors.js.map

package/dist/database/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../../src/database/errors.ts"],"sourcesContent":["import { AppKitError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"database\");\n\nexport type DatabaseErrorCategory =\n  | \"INVALID_REQUEST\"\n  | \"CONFLICT\"\n  | \"FORBIDDEN\"\n  | \"TRANSIENT\"\n  | \"INTERNAL\"\n  | \"SETUP_FAILED\";\n\ntype DatabaseErrorPhase =\n  | \"setup\"\n  | \"shutdown\"\n  | \"read\"\n  | \"write\"\n  | \"transaction\"\n  | \"runtime\";\n\nconst definitions: Record<\n  DatabaseErrorCategory,\n  { readonly message: string; readonly statusCode: number }\n> = {\n  INVALID_REQUEST: { message: \"Invalid database request\", statusCode: 400 },\n  CONFLICT: { message: \"Database conflict\", statusCode: 409 },\n  FORBIDDEN: { message: \"Database operation forbidden\", statusCode: 403 },\n  TRANSIENT: {\n    message: \"Database operation temporarily unavailable\",\n    statusCode: 503,\n  },\n  INTERNAL: { message: \"Database operation failed\", statusCode: 500 },\n  SETUP_FAILED: { message: \"Database setup failed\", statusCode: 500 },\n};\n\nconst categoryByStatus: Readonly<Record<number, DatabaseErrorCategory>> = {\n  400: \"INVALID_REQUEST\",\n  403: \"FORBIDDEN\",\n  409: \"CONFLICT\",\n  503: \"TRANSIENT\",\n};\n\n/** AppKit-facing database failure with stable metadata and no driver details. */\nexport class DatabasePluginError extends AppKitError {\n  readonly code = \"DATABASE_PLUGIN_ERROR\";\n  readonly isRetryable: boolean;\n  readonly statusCode: number;\n\n  constructor(\n    readonly category: DatabaseErrorCategory,\n    readonly phase: DatabaseErrorPhase,\n    runtimeMessage?: string,\n  ) {\n    const definition = definitions[category];\n    // Plugin boundaries replace runtime diagnostics with the stable message.\n    super(\n      phase === \"runtime\" && runtimeMessage\n        ? runtimeMessage\n        : definition.message,\n      {\n        clientMessage: definition.message,\n      },\n    );\n    this.statusCode = definition.statusCode;\n    this.isRetryable = category === \"TRANSIENT\";\n    this.name = \"DatabasePluginError\";\n  }\n}\n\n/** Keep runtime diagnostics internal until a plugin boundary classifies them. */\nexport function invalidDatabaseRequest(\n  runtimeMessage?: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"runtime\", runtimeMessage);\n}\n\n/** Add operation context without retaining an unknown error's details. */\nexport function classifyDatabaseError(\n  error: unknown,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  if (error instanceof DatabasePluginError) {\n    return error.phase === phase\n      ? error\n      : new DatabasePluginError(error.category, phase);\n  }\n  logger.error(\"Unclassified database error during %s: %O\", phase, error);\n  return new DatabasePluginError(\"INTERNAL\", phase);\n}\n\n/** Restore the safe database category carried through `Plugin.execute()`. */\nexport function databaseErrorFromStatus(\n  status: number,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  const category = categoryByStatus[status] ?? \"INTERNAL\";\n  return new DatabasePluginError(category, phase);\n}\n"],"mappings":";;;;;AAGA,MAAM,SAAS,aAAa,WAAW;AAkBvC,MAAM,cAGF;CACF,iBAAiB;EAAE,SAAS;EAA4B,YAAY;EAAK;CACzE,UAAU;EAAE,SAAS;EAAqB,YAAY;EAAK;CAC3D,WAAW;EAAE,SAAS;EAAgC,YAAY;EAAK;CACvE,WAAW;EACT,SAAS;EACT,YAAY;EACb;CACD,UAAU;EAAE,SAAS;EAA6B,YAAY;EAAK;CACnE,cAAc;EAAE,SAAS;EAAyB,YAAY;EAAK;CACpE;AAED,MAAM,mBAAoE;CACxE,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACN;;AAGD,IAAa,sBAAb,cAAyC,YAAY;CACnD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CAET,YACE,AAAS,UACT,AAAS,OACT,gBACA;EACA,MAAM,aAAa,YAAY;AAE/B,QACE,UAAU,aAAa,iBACnB,iBACA,WAAW,SACf,EACE,eAAe,WAAW,SAC3B,CACF;EAbQ;EACA;AAaT,OAAK,aAAa,WAAW;AAC7B,OAAK,cAAc,aAAa;AAChC,OAAK,OAAO;;;;AAKhB,SAAgB,uBACd,gBACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,WAAW,eAAe;;;AAI9E,SAAgB,sBACd,OACA,OACqB;AACrB,KAAI,iBAAiB,oBACnB,QAAO,MAAM,UAAU,QACnB,QACA,IAAI,oBAAoB,MAAM,UAAU,MAAM;AAEpD,QAAO,MAAM,6CAA6C,OAAO,MAAM;AACvE,QAAO,IAAI,oBAAoB,YAAY,MAAM;;;AAInD,SAAgB,wBACd,QACA,OACqB;AAErB,QAAO,IAAI,oBADM,iBAAiB,WAAW,YACJ,MAAM"}
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/database/errors.ts"],"sourcesContent":["import { AppKitError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"database\");\n\nexport type DatabaseErrorCategory =\n  | \"INVALID_REQUEST\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"FORBIDDEN\"\n  | \"TRANSIENT\"\n  | \"PAYLOAD_TOO_LARGE\"\n  | \"INTERNAL\"\n  | \"SETUP_FAILED\";\n\n/** Which request field a rejection concerns; it never carries caller values. */\nexport interface DatabaseErrorDetail {\n  readonly path: readonly string[];\n  readonly message: string;\n}\n\ntype DatabaseErrorPhase =\n  | \"setup\"\n  | \"shutdown\"\n  | \"read\"\n  | \"write\"\n  | \"transaction\"\n  | \"runtime\";\n\nconst definitions: Record<\n  DatabaseErrorCategory,\n  { readonly message: string; readonly statusCode: number }\n> = {\n  INVALID_REQUEST: { message: \"Invalid database request\", statusCode: 400 },\n  NOT_FOUND: { message: \"Database record not found\", statusCode: 404 },\n  CONFLICT: { message: \"Database conflict\", statusCode: 409 },\n  FORBIDDEN: { message: \"Database operation forbidden\", statusCode: 403 },\n  TRANSIENT: {\n    message: \"Database operation temporarily unavailable\",\n    statusCode: 503,\n  },\n  PAYLOAD_TOO_LARGE: {\n    message: \"Database response is too large\",\n    statusCode: 413,\n  },\n  INTERNAL: { message: \"Database operation failed\", statusCode: 500 },\n  SETUP_FAILED: { message: \"Database setup failed\", statusCode: 500 },\n};\n\nconst categoryByStatus: Readonly<Record<number, DatabaseErrorCategory>> = {\n  400: \"INVALID_REQUEST\",\n  403: \"FORBIDDEN\",\n  404: \"NOT_FOUND\",\n  409: \"CONFLICT\",\n  413: \"PAYLOAD_TOO_LARGE\",\n  503: \"TRANSIENT\",\n};\n\n/** AppKit-facing database failure with stable metadata and no driver details. */\nexport class DatabasePluginError extends AppKitError {\n  readonly code = \"DATABASE_PLUGIN_ERROR\";\n  readonly isRetryable: boolean;\n  readonly statusCode: number;\n\n  constructor(\n    readonly category: DatabaseErrorCategory,\n    readonly phase: DatabaseErrorPhase,\n    runtimeMessage?: string,\n    readonly details?: readonly DatabaseErrorDetail[],\n  ) {\n    const definition = definitions[category];\n    // Plugin boundaries replace runtime diagnostics with the stable message.\n    super(\n      phase === \"runtime\" && runtimeMessage\n        ? runtimeMessage\n        : definition.message,\n      {\n        clientMessage: definition.message,\n      },\n    );\n    this.statusCode = definition.statusCode;\n    this.isRetryable = category === \"TRANSIENT\";\n    this.name = \"DatabasePluginError\";\n  }\n}\n\n/** Keep runtime diagnostics internal until a plugin boundary classifies them. */\nexport function invalidDatabaseRequest(\n  runtimeMessage?: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"runtime\", runtimeMessage);\n}\n\n/** Refuse to publish a plugin whose configuration cannot be honored. */\nexport function databaseSetupFailed(): DatabasePluginError {\n  return new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n}\n\n/** Reject untrusted request input, naming the field but never its value. */\nexport function invalidDatabaseInput(\n  path: readonly string[],\n  message: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"read\", undefined, [\n    { path, message },\n  ]);\n}\n\n/**\n * Name an unknown failure without its payload. A driver error carries the SQL\n * text and its bound row values (for example a `DrizzleQueryError` retains\n * `query` and `params`), so only constructor names walk into the log.\n */\nfunction describeUnclassifiedError(error: unknown): string {\n  const names: string[] = [];\n  let current: unknown = error;\n  for (let depth = 0; depth < 5 && current instanceof Error; depth++) {\n    names.push(current.name);\n    current = current.cause;\n  }\n  return names.length > 0 ? names.join(\" <- \") : typeof error;\n}\n\n/** Add operation context without retaining an unknown error's details. */\nexport function classifyDatabaseError(\n  error: unknown,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  if (error instanceof DatabasePluginError) {\n    return error.phase === phase\n      ? error\n      : new DatabasePluginError(error.category, phase);\n  }\n  logger.error(\n    \"Unclassified database error during %s (%s)\",\n    phase,\n    describeUnclassifiedError(error),\n  );\n  return new DatabasePluginError(\"INTERNAL\", phase);\n}\n\n/** Restore the safe database category carried through `Plugin.execute()`. */\nexport function databaseErrorFromStatus(\n  status: number,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  const category = categoryByStatus[status] ?? \"INTERNAL\";\n  return new DatabasePluginError(category, phase);\n}\n"],"mappings":";;;;;AAGA,MAAM,SAAS,aAAa,WAAW;AA0BvC,MAAM,cAGF;CACF,iBAAiB;EAAE,SAAS;EAA4B,YAAY;EAAK;CACzE,WAAW;EAAE,SAAS;EAA6B,YAAY;EAAK;CACpE,UAAU;EAAE,SAAS;EAAqB,YAAY;EAAK;CAC3D,WAAW;EAAE,SAAS;EAAgC,YAAY;EAAK;CACvE,WAAW;EACT,SAAS;EACT,YAAY;EACb;CACD,mBAAmB;EACjB,SAAS;EACT,YAAY;EACb;CACD,UAAU;EAAE,SAAS;EAA6B,YAAY;EAAK;CACnE,cAAc;EAAE,SAAS;EAAyB,YAAY;EAAK;CACpE;AAED,MAAM,mBAAoE;CACxE,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACN;;AAGD,IAAa,sBAAb,cAAyC,YAAY;CACnD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CAET,YACE,AAAS,UACT,AAAS,OACT,gBACA,AAAS,SACT;EACA,MAAM,aAAa,YAAY;AAE/B,QACE,UAAU,aAAa,iBACnB,iBACA,WAAW,SACf,EACE,eAAe,WAAW,SAC3B,CACF;EAdQ;EACA;EAEA;AAYT,OAAK,aAAa,WAAW;AAC7B,OAAK,cAAc,aAAa;AAChC,OAAK,OAAO;;;;AAKhB,SAAgB,uBACd,gBACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,WAAW,eAAe;;;AAI9E,SAAgB,sBAA2C;AACzD,QAAO,IAAI,oBAAoB,gBAAgB,QAAQ;;;AAIzD,SAAgB,qBACd,MACA,SACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,QAAQ,QAAW,CACnE;EAAE;EAAM;EAAS,CAClB,CAAC;;;;;;;AAQJ,SAAS,0BAA0B,OAAwB;CACzD,MAAM,QAAkB,EAAE;CAC1B,IAAI,UAAmB;AACvB,MAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,mBAAmB,OAAO,SAAS;AAClE,QAAM,KAAK,QAAQ,KAAK;AACxB,YAAU,QAAQ;;AAEpB,QAAO,MAAM,SAAS,IAAI,MAAM,KAAK,OAAO,GAAG,OAAO;;;AAIxD,SAAgB,sBACd,OACA,OACqB;AACrB,KAAI,iBAAiB,oBACnB,QAAO,MAAM,UAAU,QACnB,QACA,IAAI,oBAAoB,MAAM,UAAU,MAAM;AAEpD,QAAO,MACL,8CACA,OACA,0BAA0B,MAAM,CACjC;AACD,QAAO,IAAI,oBAAoB,YAAY,MAAM;;;AAInD,SAAgB,wBACd,QACA,OACqB;AAErB,QAAO,IAAI,oBADM,iBAAiB,WAAW,YACJ,MAAM"}

package/dist/database/runtime/data-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-path.js","names":[],"sources":["../../../src/database/runtime/data-path.ts"],"sourcesContent":["import {\n  DEFAULT_LIMIT,\n  type FilterOperator,\n  type IdValue,\n  MAX_LIMIT,\n  MAX_OFFSET,\n  type OrderDirection,\n} from \"../contract\";\nimport { invalidDatabaseRequest } from \"../errors\";\nimport type { AppKitTable, ColumnMeta } from \"../schema-builder\";\n\nexport type { IdValue, OrderDirection };\nexport type ScalarValue = string | number | bigint | boolean | null;\n/** Operators for one column; array operands are reserved for `in`. */\nexport type FilterOps = Partial<\n  Record<FilterOperator, ScalarValue | readonly ScalarValue[]>\n>;\nexport type WhereValue = ScalarValue | readonly ScalarValue[] | FilterOps;\n/** Direct-column predicates with explicit `and` and `or` predicate groups. */\nexport type WhereClause = Readonly<\n  Record<string, WhereValue | readonly WhereClause[]>\n>;\n\nexport type OrderSpec = Readonly<Record<string, OrderDirection>>;\n\nexport interface IncludeOptions {\n  readonly select?: readonly string[];\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly limit?: number;\n}\n\n/** Selection and bounds for one declared relation edge. */\nexport type IncludeSpec = Readonly<Record<string, boolean | IncludeOptions>>;\n\n/** A bounded root read; adapters apply defaults and validate explicit bounds. */\nexport interface QuerySpec {\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly select?: readonly string[];\n  readonly include?: IncludeSpec;\n  readonly limit?: number;\n  readonly offset?: number;\n}\n\nexport type Row = Record<string, unknown>;\n\n/** Combine predicates without making callers understand the wire shape. */\nexport function andWhere(\n  existing: WhereClause | undefined,\n  next: WhereClause,\n): WhereClause {\n  return existing === undefined ? next : { and: [existing, next] };\n}\n\n/** Internal AppKit execution port; field names are schema-owned identifiers. */\nexport interface DataPath {\n  /** Read a bounded collection from one finalized table. */\n  select(table: AppKitTable, spec: QuerySpec): Promise<Row[]>;\n  /** Read by the sole primary key while preserving supported query state. */\n  findOne(\n    table: AppKitTable,\n    id: IdValue,\n    spec?: Pick<QuerySpec, \"where\" | \"select\" | \"include\">,\n  ): Promise<Row | null>;\n  count(table: AppKitTable, where?: WhereClause): Promise<number>;\n  /** Return exactly one inserted row; zero or many is an invariant failure. */\n  insert(table: AppKitTable, values: Row): Promise<Row>;\n  /** Return null for zero updated rows and reject more than one. */\n  update(table: AppKitTable, id: IdValue, values: Row): Promise<Row | null>;\n  /** Return exactly one row for a validated primary-key or unique conflict. */\n  upsert(table: AppKitTable, values: Row, onConflict: string): Promise<Row>;\n  /** Return false for zero deleted rows, true for one, and reject many. */\n  delete(table: AppKitTable, id: IdValue): Promise<boolean>;\n  /** Execute tagged SQL whose interpolations are parameter values, not SQL. */\n  raw<T = Row>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ): Promise<T[]>;\n  /** Run the callback with one transaction-bound DataPath. */\n  transaction<T>(callback: (tx: DataPath) => Promise<T>): Promise<T>;\n}\n\n/** Validate an explicit root or relation row limit. */\nexport function validateLimit(limit: number): number {\n  if (!Number.isInteger(limit) || limit < 0 || limit > MAX_LIMIT) {\n    throw invalidDatabaseRequest(\n      `limit must be an integer between 0 and ${MAX_LIMIT}`,\n    );\n  }\n  return limit;\n}\n\n/** Apply the conservative collection default when no limit is supplied. */\nexport function limitOrDefault(limit?: number): number {\n  return limit === undefined ? DEFAULT_LIMIT : validateLimit(limit);\n}\n\n/** Validate an explicit root or relation row offset. */\nexport function validateOffset(offset: number): number {\n  if (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_OFFSET) {\n    throw invalidDatabaseRequest(\n      `offset must be an integer between 0 and ${MAX_OFFSET}`,\n    );\n  }\n  return offset;\n}\n\n/** Resolve the sole primary key required by keyed operations. */\nexport function primaryKeyMeta(table: AppKitTable): ColumnMeta {\n  const primaryKeys = Object.values(table.$columns).filter(\n    (column) => column.primaryKey,\n  );\n  if (primaryKeys.length !== 1) {\n    throw invalidDatabaseRequest(`Table \"${table.$name}\" has no primary key`);\n  }\n  return primaryKeys[0];\n}\n\n/** Resolve an upsert target that PostgreSQL can use for conflict detection. */\nexport function conflictTargetMeta(\n  table: AppKitTable,\n  columnName: string,\n): ColumnMeta {\n  const column = table.$columns[columnName];\n  if (!column || (!column.primaryKey && !column.unique)) {\n    throw invalidDatabaseRequest(\n      `Column \"${table.$name}.${columnName}\" is not a conflict target`,\n    );\n  }\n  return column;\n}\n"],"mappings":";;;;;;AAgDA,SAAgB,SACd,UACA,MACa;AACb,QAAO,aAAa,SAAY,OAAO,EAAE,KAAK,CAAC,UAAU,KAAK,EAAE;;;AAgClE,SAAgB,cAAc,OAAuB;AACnD,KAAI,CAAC,OAAO,UAAU,MAAM,IAAI,QAAQ,KAAK,QAAQ,UACnD,OAAM,uBACJ,0CAA0C,YAC3C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAwB;AACrD,QAAO,UAAU,SAAY,gBAAgB,cAAc,MAAM;;;AAInE,SAAgB,eAAe,QAAwB;AACrD,KAAI,CAAC,OAAO,cAAc,OAAO,IAAI,SAAS,KAAK,SAAS,WAC1D,OAAM,uBACJ,2CAA2C,aAC5C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAgC;CAC7D,MAAM,cAAc,OAAO,OAAO,MAAM,SAAS,CAAC,QAC/C,WAAW,OAAO,WACpB;AACD,KAAI,YAAY,WAAW,EACzB,OAAM,uBAAuB,UAAU,MAAM,MAAM,sBAAsB;AAE3E,QAAO,YAAY;;;AAIrB,SAAgB,mBACd,OACA,YACY;CACZ,MAAM,SAAS,MAAM,SAAS;AAC9B,KAAI,CAAC,UAAW,CAAC,OAAO,cAAc,CAAC,OAAO,OAC5C,OAAM,uBACJ,WAAW,MAAM,MAAM,GAAG,WAAW,4BACtC;AAEH,QAAO"}
+{"version":3,"file":"data-path.js","names":[],"sources":["../../../src/database/runtime/data-path.ts"],"sourcesContent":["import {\n  DEFAULT_LIMIT,\n  type FilterOperator,\n  type IdValue,\n  MAX_LIMIT,\n  MAX_OFFSET,\n  type OrderDirection,\n} from \"../contract\";\nimport { invalidDatabaseRequest } from \"../errors\";\nimport type { AppKitTable, ColumnMeta } from \"../schema-builder\";\n\nexport type { IdValue, OrderDirection };\nexport type ScalarValue = string | number | bigint | boolean | null;\n/** Operators for one column; array operands are reserved for `in`. */\nexport type FilterOps = Partial<\n  Record<FilterOperator, ScalarValue | readonly ScalarValue[]>\n>;\nexport type WhereValue = ScalarValue | readonly ScalarValue[] | FilterOps;\n/** Direct-column predicates with explicit `and` and `or` predicate groups. */\nexport type WhereClause = Readonly<\n  Record<string, WhereValue | readonly WhereClause[]>\n>;\n\nexport type OrderSpec = Readonly<Record<string, OrderDirection>>;\n\nexport interface IncludeOptions {\n  readonly select?: readonly string[];\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly limit?: number;\n  readonly include?: IncludeSpec;\n}\n\n/** Selection and bounds for one declared relation edge. */\nexport type IncludeSpec = Readonly<Record<string, boolean | IncludeOptions>>;\n\n/** A bounded root read; adapters apply defaults and validate explicit bounds. */\nexport interface QuerySpec {\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly select?: readonly string[];\n  readonly include?: IncludeSpec;\n  readonly limit?: number;\n  readonly offset?: number;\n}\n\nexport type Row = Record<string, unknown>;\n\n/** Combine predicates without making callers understand the wire shape. */\nexport function andWhere(\n  existing: WhereClause | undefined,\n  next: WhereClause,\n): WhereClause {\n  return existing === undefined ? next : { and: [existing, next] };\n}\n\n/** Internal AppKit execution port; field names are schema-owned identifiers. */\nexport interface DataPath {\n  /** Read a bounded collection from one finalized table. */\n  select(table: AppKitTable, spec: QuerySpec): Promise<Row[]>;\n  /** Read by the sole primary key while preserving supported query state. */\n  findOne(\n    table: AppKitTable,\n    id: IdValue,\n    spec?: Pick<QuerySpec, \"where\" | \"select\" | \"include\">,\n  ): Promise<Row | null>;\n  count(table: AppKitTable, where?: WhereClause): Promise<number>;\n  /** Return exactly one inserted row; zero or many is an invariant failure. */\n  insert(table: AppKitTable, values: Row): Promise<Row>;\n  /** Return null for zero updated rows and reject more than one. */\n  update(table: AppKitTable, id: IdValue, values: Row): Promise<Row | null>;\n  /** Return exactly one row for a validated primary-key or unique conflict. */\n  upsert(table: AppKitTable, values: Row, onConflict: string): Promise<Row>;\n  /** Return false for zero deleted rows, true for one, and reject many. */\n  delete(table: AppKitTable, id: IdValue): Promise<boolean>;\n  /** Execute tagged SQL whose interpolations are parameter values, not SQL. */\n  raw<T = Row>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ): Promise<T[]>;\n  /** Run the callback with one transaction-bound DataPath. */\n  transaction<T>(callback: (tx: DataPath) => Promise<T>): Promise<T>;\n}\n\n/** Validate an explicit root or relation row limit. */\nexport function validateLimit(limit: number): number {\n  if (!Number.isInteger(limit) || limit < 0 || limit > MAX_LIMIT) {\n    throw invalidDatabaseRequest(\n      `limit must be an integer between 0 and ${MAX_LIMIT}`,\n    );\n  }\n  return limit;\n}\n\n/** Apply the conservative collection default when no limit is supplied. */\nexport function limitOrDefault(limit?: number): number {\n  return limit === undefined ? DEFAULT_LIMIT : validateLimit(limit);\n}\n\n/** Validate an explicit root or relation row offset. */\nexport function validateOffset(offset: number): number {\n  if (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_OFFSET) {\n    throw invalidDatabaseRequest(\n      `offset must be an integer between 0 and ${MAX_OFFSET}`,\n    );\n  }\n  return offset;\n}\n\n/** Resolve the sole primary key required by keyed operations. */\nexport function primaryKeyMeta(table: AppKitTable): ColumnMeta {\n  const primaryKeys = Object.values(table.$columns).filter(\n    (column) => column.primaryKey,\n  );\n  if (primaryKeys.length !== 1) {\n    throw invalidDatabaseRequest(`Table \"${table.$name}\" has no primary key`);\n  }\n  return primaryKeys[0];\n}\n\n/** Resolve an upsert target that PostgreSQL can use for conflict detection. */\nexport function conflictTargetMeta(\n  table: AppKitTable,\n  columnName: string,\n): ColumnMeta {\n  const column = table.$columns[columnName];\n  if (!column || (!column.primaryKey && !column.unique)) {\n    throw invalidDatabaseRequest(\n      `Column \"${table.$name}.${columnName}\" is not a conflict target`,\n    );\n  }\n  return column;\n}\n"],"mappings":";;;;;;AAiDA,SAAgB,SACd,UACA,MACa;AACb,QAAO,aAAa,SAAY,OAAO,EAAE,KAAK,CAAC,UAAU,KAAK,EAAE;;;AAgClE,SAAgB,cAAc,OAAuB;AACnD,KAAI,CAAC,OAAO,UAAU,MAAM,IAAI,QAAQ,KAAK,QAAQ,UACnD,OAAM,uBACJ,0CAA0C,YAC3C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAwB;AACrD,QAAO,UAAU,SAAY,gBAAgB,cAAc,MAAM;;;AAInE,SAAgB,eAAe,QAAwB;AACrD,KAAI,CAAC,OAAO,cAAc,OAAO,IAAI,SAAS,KAAK,SAAS,WAC1D,OAAM,uBACJ,2CAA2C,aAC5C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAgC;CAC7D,MAAM,cAAc,OAAO,OAAO,MAAM,SAAS,CAAC,QAC/C,WAAW,OAAO,WACpB;AACD,KAAI,YAAY,WAAW,EACzB,OAAM,uBAAuB,UAAU,MAAM,MAAM,sBAAsB;AAE3E,QAAO,YAAY;;;AAIrB,SAAgB,mBACd,OACA,YACY;CACZ,MAAM,SAAS,MAAM,SAAS;AAC9B,KAAI,CAAC,UAAW,CAAC,OAAO,cAAc,CAAC,OAAO,OAC5C,OAAM,uBACJ,WAAW,MAAM,MAAM,GAAG,WAAW,4BACtC;AAEH,QAAO"}

package/dist/database/runtime/engine/drizzle-data-path.js

@@ -65,7 +65,7 @@ function sqlStateOf(error) {
 /** Classify SQLSTATE without retaining the driver error or its properties. */
 function classifyDriverError(error) {
 	const code = sqlStateOf(error);
-	const category = code === "40001" || code === "40P01" ? "TRANSIENT" : code === "42501" ? "FORBIDDEN" : code?.startsWith("23") ? "CONFLICT" : "INTERNAL";
+	const category = code === "40001" || code === "40P01" || code === "57014" ? "TRANSIENT" : code === "42501" ? "FORBIDDEN" : code?.startsWith("23") ? "CONFLICT" : "INTERNAL";
 	logger.error("Database driver error classified as %s (SQLSTATE %s)", category, code ?? "unknown");
 	return new DatabasePluginError(category, "runtime");
 }