feat(appkit): tool primitives and ToolProvider surfaces on core plugins

[MarioCadenas]

Second layer of the agents feature. Adds the primitives for defining
agent tools and implements them on every core ToolProvider plugin.

User-facing factories

• tool(config) — inline function tools backed by a Zod schema. Auto-
  generates JSON Schema for the LLM via z.toJSONSchema() (stripping
  the top-level $schema annotation that Gemini rejects), runtime-
  validates tool-call arguments, returns an LLM-friendly error string
  on validation failure so the model can self-correct.
• mcpServer(name, url) — tiny factory for hosted custom MCP server
  configs. Replaces the verbose
  { type: "custom_mcp_server", custom_mcp_server: { app_name, app_url } }
  wrapper.
• FunctionTool / HostedTool types + isFunctionTool / isHostedTool
  type guards. HostedTool is a union of Genie, VectorSearch, custom
  MCP, and external-connection configs.
• ToolkitEntry + ToolkitOptions types + isToolkitEntry guard.
  AgentTool = FunctionTool | HostedTool | ToolkitEntry is the canonical
  union later PRs spread into agent definitions.

Internal registry + JSON Schema helper

• defineTool(config) + ToolRegistry — plugin authors' internal shape
  for declaring a keyed set of tools with Zod-typed handlers.
• toolsFromRegistry() — produces the AgentToolDefinition[] exposed
  via ToolProvider.getAgentTools().
• executeFromRegistry() — validates args then dispatches to the
  handler. Returns LLM-friendly errors on bad args.
• toToolJSONSchema() — shared helper at
  packages/appkit/src/plugins/agents/tools/json-schema.ts that wraps
  toJSONSchema() and strips $schema. Used by tool(),
  toolsFromRegistry(), and buildToolkitEntries().
• buildToolkitEntries(pluginName, registry, opts?) — converts a
  plugin's internal ToolRegistry into a keyed record of ToolkitEntry
  markers, honoring prefix / only / except / rename.

MCP client

• AppKitMcpClient — minimal JSON-RPC 2.0 client over SSE, zero deps.
  Handles auth refresh, per-server connection pooling, and tool
  definition aggregation.
• resolveHostedTools() — maps HostedTool configs to Databricks MCP
  endpoint URLs.

ToolProvider surfaces on core plugins

• analytics — query tool (Zod-typed, asUser dispatch)
• files — per-volume tool family: ${volumeKey}.{list,read,exists,metadata,upload,delete} (dynamically named from the plugin's volume config)
• genie — per-space tool family: ${alias}.{sendMessage,getConversation} (dynamically named from the plugin's spaces config)
• lakebase — query tool

Each plugin gains getAgentTools() + executeAgentTool() satisfying
the ToolProvider interface, plus a .toolkit(opts?) method that
returns a record of ToolkitEntry markers for later spread into agent
definitions.

Test plan

• 58 new tests across tool primitives + plugin ToolProvider surfaces
• Full appkit vitest suite: 1212 tests passing
• Typecheck clean
• Build clean, publint clean

Signed-off-by: MarioCadenas MarioCadenas@users.noreply.github.com

PR Stack

1. Shared agent types + LLM adapters — feat(appkit): shared agent types and LLM adapter implementations #301
2. Tool primitives + ToolProvider surfaces (this PR)
3. Plugin infrastructure (attachContext + PluginContext) — feat(appkit): plugin infrastructure — attachContext + PluginContext mediator #303
4. agents() plugin + createAgent(def) + markdown-driven agents — feat(appkit): agents() plugin, createAgent(def), and markdown-driven agents #304
5. fromPlugin() DX + runAgent plugins arg + toolkit-resolver — feat(appkit): fromPlugin() DX, runAgent plugins arg, shared toolkit-resolver #305
6. Reference app + dev-playground + docs — feat(appkit): reference agent-app, dev-playground chat UI, docs, and template #306

Demo

agent-demo.mp4