@fabric-harness/databricks 0.16.1 → 1.0.0

package/dist/feature-serving.d.ts

@@ -0,0 +1,17 @@
+import type { JsonObject, ToolDef } from '@fabric-harness/sdk';
+import type { DatabricksRestClient } from './client.js';
+export interface DatabricksFeatureLookupToolOptions {
+    /** Feature Serving endpoint name (serves features from an online table / feature spec). */
+    endpoint: string;
+    name?: string;
+    description?: string;
+}
+/**
+ * Low-latency feature lookup from a Databricks **Feature Serving** endpoint (backed by an Online
+ * Table). The model passes primary-key records; the endpoint returns the served feature values.
+ * Drives serving consumption and keeps features governed by Unity Catalog under the bundle principal.
+ */
+export declare function databricksFeatureLookupTool(client: DatabricksRestClient, options: DatabricksFeatureLookupToolOptions): ToolDef<{
+    records: JsonObject[];
+}, unknown>;
+//# sourceMappingURL=feature-serving.d.ts.map

package/dist/feature-serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-serving.d.ts","sourceRoot":"","sources":["../src/feature-serving.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,kCAAkC;IACjD,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,EAAE,OAAO,CAAC,CAsBlK"}

package/dist/feature-serving.js

@@ -0,0 +1,29 @@
+/**
+ * Low-latency feature lookup from a Databricks **Feature Serving** endpoint (backed by an Online
+ * Table). The model passes primary-key records; the endpoint returns the served feature values.
+ * Drives serving consumption and keeps features governed by Unity Catalog under the bundle principal.
+ */
+export function databricksFeatureLookupTool(client, options) {
+    return {
+        name: options.name ?? 'databricks_feature_lookup',
+        description: options.description ?? 'Look up low-latency features for primary-key records from a Databricks Feature Serving endpoint.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                records: {
+                    type: 'array',
+                    items: { type: 'object', additionalProperties: true },
+                    minItems: 1,
+                    description: 'Primary-key records, e.g. [{ "user_id": 123 }].',
+                },
+            },
+            required: ['records'],
+        },
+        metadata: { effect: 'read', provider: 'databricks', service: 'feature-serving' },
+        execute: (input) => client.post(`/serving-endpoints/${encodeURIComponent(options.endpoint)}/invocations`, {
+            dataframe_records: input.records,
+        }),
+    };
+}
+//# sourceMappingURL=feature-serving.js.map

package/dist/feature-serving.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-serving.js","sourceRoot":"","sources":["../src/feature-serving.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAA4B,EAAE,OAA2C;IACnH,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,2BAA2B;QACjD,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,kGAAkG;QACtI,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,oBAAoB,EAAE,KAAK;YAC3B,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE;oBACrD,QAAQ,EAAE,CAAC;oBACX,WAAW,EAAE,iDAAiD;iBAC/D;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;QACD,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE;QAChF,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,EAAE;YACxG,iBAAiB,EAAE,KAAK,CAAC,OAAO;SACjC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/genie.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDef } from '@fabric-harness/sdk';
+import type { DatabricksRestClient } from './client.js';
+export interface DatabricksGenieToolOptions {
+    /** AI/BI Genie space id. */
+    spaceId: string;
+    name?: string;
+    description?: string;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * AI/BI Genie — delegate a natural-language analytics question to a governed Genie space. Genie
+ * generates and runs SQL on the warehouse and returns an answer; this tool returns the answer text,
+ * the generated SQL, and the result rows. Pass `conversationId` to continue a multi-turn thread.
+ *
+ * Genie response field names vary by API version — parsed defensively; smoke-test against a live space.
+ */
+export declare function databricksGenieTool(client: DatabricksRestClient, options: DatabricksGenieToolOptions): ToolDef<{
+    question: string;
+    conversationId?: string;
+}, unknown>;
+//# sourceMappingURL=genie.d.ts.map

package/dist/genie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"genie.d.ts","sourceRoot":"","sources":["../src/genie.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,0BAA0B;IACzC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,CAAC,CAoDtK"}

package/dist/genie.js

@@ -0,0 +1,60 @@
+const TERMINAL_STATES = new Set(['COMPLETED', 'FAILED', 'CANCELLED', 'QUERY_RESULT_EXPIRED']);
+const enc = encodeURIComponent;
+/**
+ * AI/BI Genie — delegate a natural-language analytics question to a governed Genie space. Genie
+ * generates and runs SQL on the warehouse and returns an answer; this tool returns the answer text,
+ * the generated SQL, and the result rows. Pass `conversationId` to continue a multi-turn thread.
+ *
+ * Genie response field names vary by API version — parsed defensively; smoke-test against a live space.
+ */
+export function databricksGenieTool(client, options) {
+    const intervalMs = options.pollIntervalMs ?? 2000;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const space = `/api/2.0/genie/spaces/${enc(options.spaceId)}`;
+    return {
+        name: options.name ?? 'databricks_genie_ask',
+        description: options.description ?? 'Ask a natural-language analytics question in a Databricks AI/BI Genie space; returns the answer, generated SQL, and result rows.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { question: { type: 'string' }, conversationId: { type: 'string' } },
+            required: ['question'],
+        },
+        metadata: { effect: 'execute', provider: 'databricks', service: 'genie' },
+        async execute(input) {
+            let conversationId = input.conversationId;
+            let messageId;
+            if (conversationId) {
+                const res = await client.post(`${space}/conversations/${enc(conversationId)}/messages`, { content: input.question });
+                messageId = String(res.message_id ?? res.id ?? '');
+            }
+            else {
+                const res = await client.post(`${space}/start-conversation`, { content: input.question });
+                conversationId = String(res.conversation_id ?? res.conversation?.id ?? '');
+                messageId = String(res.message_id ?? res.message?.id ?? '');
+            }
+            const messagePath = `${space}/conversations/${enc(conversationId)}/messages/${enc(messageId)}`;
+            const deadline = Date.now() + timeoutMs;
+            let message = await client.get(messagePath);
+            while (!TERMINAL_STATES.has(message.status ?? '') && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, intervalMs));
+                message = await client.get(messagePath);
+            }
+            const text = message.attachments?.map((a) => a.text?.content).filter(Boolean).join('\n') || undefined;
+            const sql = message.attachments?.find((a) => a.query?.query)?.query?.query;
+            let result;
+            if (sql) {
+                result = await client.get(`${messagePath}/query-result`).catch(() => undefined);
+            }
+            return {
+                conversationId,
+                messageId,
+                status: message.status,
+                ...(text ? { text } : {}),
+                ...(sql ? { sql } : {}),
+                ...(result !== undefined ? { result } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=genie.js.map

package/dist/genie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genie.js","sourceRoot":"","sources":["../src/genie.ts"],"names":[],"mappings":"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"}

package/dist/governance.d.ts

@@ -0,0 +1,70 @@
+import type { ApprovalPolicyRule, CapabilityPolicy, JsonObject, ToolDef } from '@fabric-harness/sdk';
+/**
+ * Governance for Databricks tools is **layered on top of Unity Catalog, never a replacement.** UC
+ * enforces table/row/column ACLs natively via the acting principal (see identity.ts). These helpers
+ * add the things UC doesn't: an **audit/lineage** stamp on every tool call, **approval routing** for
+ * sensitive operations, and an **egress allowlist** pinned to the workspace — all expressed through
+ * the SDK's existing `CapabilityPolicy`, so the loop enforces them without a bespoke engine.
+ */
+export interface DatabricksLineageRecord {
+    tool: string;
+    /** From the tool's `metadata.service` (e.g. 'sql', 'unity-catalog', 'jobs'). */
+    service?: string;
+    provider?: string;
+    /** Stable label for the acting principal — never the token. */
+    principal?: string;
+    /** Durable submission owning this tool call (v2 correlation, from the ambient submission context). */
+    submissionId?: string;
+    attemptId?: string;
+    tenantId?: string;
+    catalog?: string;
+    schema?: string;
+    input: JsonObject;
+    startedAt: string;
+    finishedAt: string;
+    ok: boolean;
+    error?: string;
+}
+export interface DatabricksGovernanceOptions {
+    /** Stable label for the acting principal, recorded in lineage. Never pass a token here. */
+    principal?: string;
+    /** Sink for lineage/audit records. Defaults to no-op; wire to OTel / `onEvent` at the app layer. */
+    onLineage?: (record: DatabricksLineageRecord) => void;
+    /**
+     * Optional belt-and-suspenders catalog allowlist. Calls whose input references a catalog outside
+     * the list are rejected before execution. UC remains the source of truth; this is defense in depth.
+     */
+    catalogs?: string[];
+    /** Clock injection for tests. */
+    now?: () => Date;
+}
+/** Wraps one Databricks tool to stamp lineage/audit and enforce the optional catalog allowlist. */
+export declare function withGovernance<I, O>(tool: ToolDef<I, O>, options?: DatabricksGovernanceOptions): ToolDef<I, O>;
+/** Wraps a set of Databricks tools with {@link withGovernance}. */
+export declare function withGovernanceTools(tools: ToolDef[], options?: DatabricksGovernanceOptions): ToolDef[];
+export interface DatabricksApprovalRuleOptions {
+    /** Opaque approval audience (e.g. 'data-steward'). */
+    audience: string;
+    /** Restrict to these `metadata.service` values. Default: gate every write/execute tool. */
+    services?: string[];
+    reason?: string;
+    ttlSeconds?: number;
+}
+/** Builds approval rules (one per gated tool) for `CapabilityPolicy.toolPolicy.approvalRules`. */
+export declare function databricksApprovalRules(tools: ToolDef[], options: DatabricksApprovalRuleOptions): ApprovalPolicyRule[];
+export interface DatabricksGovernancePolicyOptions {
+    tools: ToolDef[];
+    /** Workspace host(s) to pin outbound egress to (URL or bare host). */
+    host?: string | string[];
+    /** When set, sensitive tools route to this approval audience. */
+    stewardAudience?: string;
+    approvalServices?: string[];
+    ttlSeconds?: number;
+}
+/**
+ * Assembles a `CapabilityPolicy` for a Databricks tool set: approval routing for sensitive
+ * operations (if `stewardAudience` is set) plus an egress allowlist pinned to the workspace host(s).
+ * Used by the `databricks()` bundle; can also be merged into an agent's own policy.
+ */
+export declare function databricksGovernancePolicy(options: DatabricksGovernancePolicyOptions): CapabilityPolicy;
+//# sourceMappingURL=governance.d.ts.map

package/dist/governance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../src/governance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAErG;;;;;;GAMG;AAEH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAeD,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAkDlH;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,EAAE,CAE1G;AAED,MAAM,WAAW,6BAA6B;IAC5C,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAQD,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,6BAA6B,GAAG,kBAAkB,EAAE,CAUtH;AAED,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAcD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iCAAiC,GAAG,gBAAgB,CAcvG"}

package/dist/governance.js

@@ -0,0 +1,123 @@
+import { currentSubmissionContext, redactJson } from '@fabric-harness/sdk';
+function metaString(tool, key) {
+    const value = tool.metadata?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function inputString(input, key) {
+    if (input && typeof input === 'object' && key in input) {
+        const value = input[key];
+        if (typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
+/** Wraps one Databricks tool to stamp lineage/audit and enforce the optional catalog allowlist. */
+export function withGovernance(tool, options = {}) {
+    const inner = tool.execute;
+    if (!inner)
+        return tool;
+    const now = options.now ?? (() => new Date());
+    return {
+        ...tool,
+        metadata: { ...(tool.metadata ?? {}), governed: true },
+        async execute(input, context) {
+            const catalog = inputString(input, 'catalog');
+            const schema = inputString(input, 'schema');
+            if (options.catalogs && catalog && !options.catalogs.includes(catalog)) {
+                throw new Error(`databricks governance: catalog "${catalog}" is not in the allowed list (${options.catalogs.join(', ')}).`);
+            }
+            const startedAt = now().toISOString();
+            const service = metaString(tool, 'service');
+            const provider = metaString(tool, 'provider');
+            // Correlate with the durable submission owning this turn (set by the
+            // submission runner); the acting principal falls back to the actor's
+            // governed identity when no explicit label was configured.
+            const submission = currentSubmissionContext();
+            const principal = options.principal ?? submission?.actor?.principal?.id;
+            const base = {
+                tool: tool.name,
+                ...(service !== undefined ? { service } : {}),
+                ...(provider !== undefined ? { provider } : {}),
+                ...(principal !== undefined ? { principal } : {}),
+                ...(submission
+                    ? {
+                        submissionId: submission.submissionId,
+                        attemptId: submission.attemptId,
+                        ...(submission.tenantId !== undefined ? { tenantId: submission.tenantId } : {}),
+                    }
+                    : {}),
+                ...(catalog !== undefined ? { catalog } : {}),
+                ...(schema !== undefined ? { schema } : {}),
+                // Redact secret-ish keys before the input enters the audit/lineage record.
+                input: redactJson((input ?? {})),
+                startedAt,
+            };
+            try {
+                const result = await inner(input, context);
+                options.onLineage?.({ ...base, finishedAt: now().toISOString(), ok: true });
+                return result;
+            }
+            catch (error) {
+                options.onLineage?.({ ...base, finishedAt: now().toISOString(), ok: false, error: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+        },
+    };
+}
+/** Wraps a set of Databricks tools with {@link withGovernance}. */
+export function withGovernanceTools(tools, options = {}) {
+    return tools.map((tool) => withGovernance(tool, options));
+}
+function shouldGate(tool, services) {
+    if (services)
+        return services.includes(metaString(tool, 'service') ?? '');
+    const effect = tool.metadata?.effect;
+    return effect === 'write' || effect === 'execute';
+}
+/** Builds approval rules (one per gated tool) for `CapabilityPolicy.toolPolicy.approvalRules`. */
+export function databricksApprovalRules(tools, options) {
+    return tools
+        .filter((tool) => shouldGate(tool, options.services))
+        .map((tool) => ({
+        pattern: tool.name,
+        audience: options.audience,
+        // ${name} is templated by the policy layer at request time — keep it literal here.
+        reason: options.reason ?? 'Databricks ${name} requires data-steward approval.',
+        ...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}),
+    }));
+}
+function toHostPatterns(host) {
+    if (!host)
+        return [];
+    const list = Array.isArray(host) ? host : [host];
+    return list.map((entry) => {
+        try {
+            return new URL(entry.includes('://') ? entry : `https://${entry}`).host;
+        }
+        catch {
+            return entry;
+        }
+    });
+}
+/**
+ * Assembles a `CapabilityPolicy` for a Databricks tool set: approval routing for sensitive
+ * operations (if `stewardAudience` is set) plus an egress allowlist pinned to the workspace host(s).
+ * Used by the `databricks()` bundle; can also be merged into an agent's own policy.
+ */
+export function databricksGovernancePolicy(options) {
+    const policy = {};
+    if (options.stewardAudience) {
+        policy.toolPolicy = {
+            approvalRules: databricksApprovalRules(options.tools, {
+                audience: options.stewardAudience,
+                ...(options.approvalServices ? { services: options.approvalServices } : {}),
+                ...(options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {}),
+            }),
+        };
+    }
+    const hosts = toHostPatterns(options.host);
+    if (hosts.length > 0)
+        policy.network = { mode: 'allowlist', hosts };
+    return policy;
+}
+//# sourceMappingURL=governance.js.map

package/dist/governance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance.js","sourceRoot":"","sources":["../src/governance.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,72 @@
+import type { FabricPrincipal } from '@fabric-harness/sdk';
+/**
+ * A bearer-token resolver awaited per request. Shape matches what {@link DatabricksRestClient},
+ * {@link databricksFoundationModelProvider} (via `tokenProvider`), and the Lakebase store accept,
+ * so a single principal threads through model calls, data calls, and state.
+ */
+export type DatabricksTokenProvider = () => Promise<string>;
+export type DatabricksPrincipal = 
+/** Personal access token. Dev / single-user only. */
+{
+    kind: 'pat';
+    token: string;
+    label?: string;
+}
+/** OAuth machine-to-machine (client-credentials). The agent acts as one governed identity. */
+ | {
+    kind: 'service-principal';
+    host: string;
+    clientId: string;
+    clientSecret: string;
+    /** OAuth scope; defaults to `all-apis`. */
+    scope?: string;
+    /** Refresh this many seconds before expiry to avoid using a token that expires mid-flight. Default 60. */
+    refreshSkewSeconds?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * On-behalf-of a specific end user. The caller binds the user's token resolver (e.g. from a
+ * channel `actor`), so Unity Catalog enforces *that human's* grants. The resolver is responsible
+ * for its own caching/refresh.
+ */
+ | {
+    kind: 'on-behalf-of';
+    userToken: () => string | Promise<string>;
+    label?: string;
+};
+/** Builds a cached, auto-refreshing token provider for a Databricks principal. */
+export declare function databricksIdentity(principal: DatabricksPrincipal): DatabricksTokenProvider;
+/**
+ * The service principal a Databricks App runs as, from the standard app
+ * runtime environment (`DATABRICKS_HOST` / `DATABRICKS_CLIENT_ID` /
+ * `DATABRICKS_CLIENT_SECRET`). Returns `undefined` when any variable is
+ * missing, so callers can fall back to explicit configuration.
+ */
+export declare function appServicePrincipalFromEnv(env?: Record<string, string | undefined>): Extract<DatabricksPrincipal, {
+    kind: 'service-principal';
+}> | undefined;
+/**
+ * On-behalf-of principal from Databricks Apps user-authorization headers:
+ * the platform forwards the signed-in user's access token as
+ * `x-forwarded-access-token` (plus `x-forwarded-email`/`x-forwarded-user`).
+ * Returns `undefined` when the request carries no user token (e.g. app
+ * service-to-service traffic) so callers fall back to the app principal.
+ */
+export declare function onBehalfOfFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): Extract<DatabricksPrincipal, {
+    kind: 'on-behalf-of';
+}> | undefined;
+export interface FabricPrincipalOverrides {
+    id?: string;
+    /** Unity Catalog principal name, when it differs from the id. */
+    ucPrincipal?: string;
+    displayName?: string;
+    /** Mark a service principal as the hosting app's own identity. */
+    asAppPrincipal?: boolean;
+}
+/**
+ * Map a Databricks principal onto the SDK's {@link FabricPrincipal} so the
+ * governed identity rides submissions → tool calls → lineage/cost records.
+ * Never carries a token — ids and labels only.
+ */
+export declare function fabricPrincipalFor(principal: DatabricksPrincipal, overrides?: FabricPrincipalOverrides): FabricPrincipal;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,MAAM,mBAAmB;AAC7B,qDAAqD;AACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAChD,8FAA8F;GAC5F;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AACH;;;;GAIG;GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAQxF,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,GAAG,uBAAuB,CAU1F;AA+CD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAqD,GAC1F,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,GAAG,SAAS,CAWzE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,GAAG,SAAS,CAUpE;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,EAAE,SAAS,GAAE,wBAA6B,GAAG,eAAe,CAiB5H"}

package/dist/identity.js

@@ -0,0 +1,119 @@
+import { redactText } from '@fabric-harness/sdk';
+/** Builds a cached, auto-refreshing token provider for a Databricks principal. */
+export function databricksIdentity(principal) {
+    if (principal.kind === 'pat') {
+        const { token } = principal;
+        return async () => token;
+    }
+    if (principal.kind === 'on-behalf-of') {
+        const { userToken } = principal;
+        return async () => userToken();
+    }
+    return servicePrincipalProvider(principal);
+}
+function servicePrincipalProvider(principal) {
+    const host = principal.host.replace(/\/$/, '');
+    const scope = principal.scope ?? 'all-apis';
+    const skewMs = (principal.refreshSkewSeconds ?? 60) * 1000;
+    const fetchImpl = principal.fetchImpl ?? fetch;
+    const basic = base64(`${principal.clientId}:${principal.clientSecret}`);
+    let cached;
+    let inflight;
+    const refresh = async () => {
+        const response = await fetchImpl(`${host}/oidc/v1/token`, {
+            method: 'POST',
+            headers: {
+                authorization: `Basic ${basic}`,
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: `grant_type=client_credentials&scope=${encodeURIComponent(scope)}`,
+        });
+        if (!response.ok) {
+            const text = redactText(await response.text(), { additionalSecrets: [principal.clientSecret] });
+            throw new Error(`databricks oauth: ${response.status} ${response.statusText}: ${text.slice(0, 500)}`);
+        }
+        const json = (await response.json());
+        if (!json.access_token)
+            throw new Error('databricks oauth: response missing access_token.');
+        const ttlMs = (json.expires_in ?? 3600) * 1000;
+        cached = { token: json.access_token, refreshAtMs: Date.now() + Math.max(0, ttlMs - skewMs) };
+        return json.access_token;
+    };
+    return async () => {
+        if (cached && Date.now() < cached.refreshAtMs)
+            return cached.token;
+        // Dedupe concurrent refreshes so a burst of requests triggers a single token exchange.
+        if (!inflight)
+            inflight = refresh().finally(() => { inflight = undefined; });
+        return inflight;
+    };
+}
+function base64(value) {
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(value, 'utf8').toString('base64');
+    return btoa(value);
+}
+// ─── Identity propagation (v2, workstream C3) ───────────────────────────────
+/**
+ * The service principal a Databricks App runs as, from the standard app
+ * runtime environment (`DATABRICKS_HOST` / `DATABRICKS_CLIENT_ID` /
+ * `DATABRICKS_CLIENT_SECRET`). Returns `undefined` when any variable is
+ * missing, so callers can fall back to explicit configuration.
+ */
+export function appServicePrincipalFromEnv(env = typeof process !== 'undefined' ? process.env : {}) {
+    const host = env.DATABRICKS_HOST;
+    const clientId = env.DATABRICKS_CLIENT_ID;
+    const clientSecret = env.DATABRICKS_CLIENT_SECRET;
+    if (!host || !clientId || !clientSecret)
+        return undefined;
+    return {
+        kind: 'service-principal',
+        host: host.includes('://') ? host : `https://${host}`,
+        clientId,
+        clientSecret,
+    };
+}
+/**
+ * On-behalf-of principal from Databricks Apps user-authorization headers:
+ * the platform forwards the signed-in user's access token as
+ * `x-forwarded-access-token` (plus `x-forwarded-email`/`x-forwarded-user`).
+ * Returns `undefined` when the request carries no user token (e.g. app
+ * service-to-service traffic) so callers fall back to the app principal.
+ */
+export function onBehalfOfFromHeaders(headers) {
+    const read = (name) => {
+        if (typeof headers.get === 'function')
+            return headers.get(name) ?? undefined;
+        const value = headers[name];
+        return Array.isArray(value) ? value[0] : value;
+    };
+    const token = read('x-forwarded-access-token');
+    if (!token)
+        return undefined;
+    const label = read('x-forwarded-email') ?? read('x-forwarded-user');
+    return { kind: 'on-behalf-of', userToken: () => token, ...(label ? { label } : {}) };
+}
+/**
+ * Map a Databricks principal onto the SDK's {@link FabricPrincipal} so the
+ * governed identity rides submissions → tool calls → lineage/cost records.
+ * Never carries a token — ids and labels only.
+ */
+export function fabricPrincipalFor(principal, overrides = {}) {
+    if (principal.kind === 'service-principal') {
+        const id = overrides.id ?? principal.clientId;
+        return {
+            kind: overrides.asAppPrincipal ? 'app-principal' : 'service-principal',
+            id,
+            ucPrincipal: overrides.ucPrincipal ?? id,
+            ...(overrides.displayName ? { displayName: overrides.displayName } : {}),
+        };
+    }
+    const id = overrides.id ?? principal.label ?? (principal.kind === 'pat' ? 'pat-user' : 'on-behalf-of-user');
+    return {
+        kind: 'user',
+        id,
+        ...(overrides.ucPrincipal ? { ucPrincipal: overrides.ucPrincipal } : {}),
+        ...(overrides.displayName ? { displayName: overrides.displayName } : {}),
+    };
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}