feat(appkit): introduce workspace-client wrapper over the Databricks SDK

Add packages/appkit/src/workspace-client/ — a facade over the legacy
@databricks/sdk-experimental client that mirrors the modular Databricks
SDK's multi-client shape. This prepares the library for an incremental,
per-service migration to the modular SDK without migrating anything yet.

- legacy.ts is the ONLY module importing @databricks/sdk-experimental;
  it constructs the client and re-exports the SDK symbols AppKit uses.
- The WorkspaceClient facade exposes per-service accessors (files,
  warehouses, genie, jobs, statementExecution, servingEndpoints,
  currentUser, config, apiClient), each legacy-typed and delegating to
  the underlying client. Migrating a service later is a localized swap:
  one getter + its accessor type + one connector.
- createWorkspaceClient() replaces every `new WorkspaceClient(...)` site
  (runtime + build-time type-generator); toLegacyWorkspaceClient() is the
  escape hatch for @databricks/lakebase.
- createApp({ client }) and the public index now expose the wrapper type
  instead of the raw SDK client.
- A Biome noRestrictedImports boundary rule forbids importing
  @databricks/sdk-experimental outside workspace-client/, keeping the seam
  enforceable. Tests mock the wrapper rather than the SDK.

Time is sourced off the SDK namespace (SDK.Time ?? SDK.default.Time)
because the SDK's CommonJS `Time` export is a getter that defeats Node's
static ESM named-export detection — a direct `export { Time }` throws at
link time.

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

Author: MarioCadenas

biome.json

@@ -41,6 +41,22 @@
       },
       "security": {
         "noDangerouslySetInnerHtml": "off"
+      },
+      "style": {
+        "noRestrictedImports": {
+          "level": "error",
+          "options": {
+            "patterns": [
+              {
+                "group": [
+                  "@databricks/sdk-experimental",
+                  "@databricks/sdk-experimental/**"
+                ],
+                "message": "Import the Databricks SDK only through the wrapper in packages/appkit/src/workspace-client. Add a re-export there if you need a new symbol."
+              }
+            ]
+          }
+        }
       }
     }
   },
@@ -56,5 +72,17 @@
         "organizeImports": "on"
       }
     }
-  }
+  },
+  "overrides": [
+    {
+      "includes": ["packages/appkit/src/workspace-client/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": "off"
+          }
+        }
+      }
+    }
+  ]
 }

docs/docs/api/appkit/Class.DatabricksAdapter.md

@@ -7,6 +7,7 @@ import type {
 } from "shared";
 import { stream as servingStream } from "../connectors/serving/client";
 import { APPKIT_USER_AGENT, getClientOptions } from "../context/client-options";
+import { createWorkspaceClient } from "../workspace-client";
 
 /** Default cap for a single incomplete SSE line tail (DoS guard). */
 const DEFAULT_MAX_SSE_LINE_CHARS = 1024 * 1024;
@@ -246,12 +247,11 @@ interface DeltaToolCall {
  *
  * @example Using the factory (recommended)
  * ```ts
- * import { createApp, createAgent, agents } from "@databricks/appkit";
+ * import { createApp, createAgent, agents, createWorkspaceClient } from "@databricks/appkit";
  * import { DatabricksAdapter } from "@databricks/appkit/beta";
- * import { WorkspaceClient } from "@databricks/sdk-experimental";
  *
  * const adapter = DatabricksAdapter.fromServingEndpoint({
- *   workspaceClient: new WorkspaceClient({}),
+ *   workspaceClient: createWorkspaceClient(),
  *   endpointName: "my-endpoint",
  * });
  *
@@ -405,11 +405,9 @@ export class DatabricksAdapter implements AgentAdapter {
     let workspaceClient: WorkspaceClientLike | undefined =
       options?.workspaceClient;
     if (!workspaceClient) {
-      const sdk = await import("@databricks/sdk-experimental");
-      workspaceClient = new sdk.WorkspaceClient(
-        {},
-        getClientOptions(),
-      ) as unknown as WorkspaceClientLike;
+      workspaceClient = createWorkspaceClient({
+        clientOptions: getClientOptions(),
+      }) as unknown as WorkspaceClientLike;
     }
 
     return DatabricksAdapter.fromServingEndpoint({

docs/docs/api/appkit/Function.createApp.md

@@ -999,11 +999,16 @@ describe("DatabricksAdapter.fromModelServing", () => {
   test("reads endpoint from DATABRICKS_SERVING_ENDPOINT_NAME env var", async () => {
     process.env.DATABRICKS_SERVING_ENDPOINT_NAME = "my-model";
 
-    vi.mock("@databricks/sdk-experimental", () => ({
-      WorkspaceClient: vi.fn().mockImplementation(() => ({
-        apiClient: { request: vi.fn() },
-      })),
-    }));
+    vi.mock("../../workspace-client", async (importOriginal) => {
+      const actual =
+        await importOriginal<typeof import("../../workspace-client")>();
+      return {
+        ...actual,
+        createWorkspaceClient: vi.fn().mockImplementation(() => ({
+          apiClient: { request: vi.fn() },
+        })),
+      };
+    });
 
     const adapter = await DatabricksAdapter.fromModelServing();
     expect(adapter).toBeInstanceOf(DatabricksAdapter);