@databricks/appkit 0.45.0 → 0.46.0

package/dist/stream/stream-registry.js

@@ -1,50 +1,56 @@
-import { RingBuffer } from "./buffers.js";
 import { SSEErrorCode } from "./types.js";
+import { clearGraceTimer, clearRemovalTimer } from "./timers.js";
 
 //#region src/stream/stream-registry.ts
 var StreamRegistry = class {
 	streams;
+	maxActiveStreams;
 	constructor(maxActiveStreams) {
-		this.streams = new RingBuffer(maxActiveStreams, (entry) => entry.streamId);
+		this.streams = /* @__PURE__ */ new Map();
+		this.maxActiveStreams = maxActiveStreams;
 	}
 	add(entry) {
-		if (this.streams.getSize() >= this.streams.capacity) this._evictOldestStream(entry.streamId);
-		this.streams.add(entry);
+		if (!this.streams.has(entry.streamId) && this.streams.size >= this.maxActiveStreams) this._evictOldestStream(entry.streamId);
+		this.streams.set(entry.streamId, entry);
 	}
 	get(streamId) {
-		return this.streams.get(streamId);
+		return this.streams.get(streamId) ?? null;
 	}
 	has(streamId) {
 		return this.streams.has(streamId);
 	}
 	remove(streamId) {
-		this.streams.remove(streamId);
+		this.streams.delete(streamId);
 	}
 	size() {
-		return this.streams.getSize();
+		return this.streams.size;
 	}
 	clear() {
-		const allStreams = this.streams.getAll();
-		for (const stream of allStreams) {
-			this._clearGraceTimer(stream);
+		for (const stream of this.streams.values()) {
 			stream.abortController.abort("Server shutdown");
+			clearGraceTimer(stream);
+			clearRemovalTimer(stream);
 		}
 		this.streams.clear();
 	}
-	_clearGraceTimer(stream) {
-		if (stream.disconnectGraceTimer) {
-			clearTimeout(stream.disconnectGraceTimer);
-			stream.disconnectGraceTimer = void 0;
-		}
-	}
 	_evictOldestStream(excludeStreamId) {
-		const allStreams = this.streams.getAll();
+		const allStreams = this.streams.values();
 		let oldestStream = null;
 		let oldestAccess = Infinity;
-		for (const stream of allStreams) if (stream.streamId !== excludeStreamId && stream.lastAccess < oldestAccess) {
-			oldestStream = stream;
-			oldestAccess = stream.lastAccess;
+		let oldestCompletedStream = null;
+		let oldestCompletedAccess = Infinity;
+		for (const stream of allStreams) {
+			if (stream.streamId === excludeStreamId) continue;
+			if (stream.lastAccess < oldestAccess) {
+				oldestStream = stream;
+				oldestAccess = stream.lastAccess;
+			}
+			if (stream.isCompleted && stream.lastAccess < oldestCompletedAccess) {
+				oldestCompletedStream = stream;
+				oldestCompletedAccess = stream.lastAccess;
+			}
 		}
+		oldestStream = oldestCompletedStream ?? oldestStream;
 		if (oldestStream) {
 			for (const client of oldestStream.clients) if (!client.writableEnded) try {
 				client.write(`event: error\n`);
@@ -53,9 +59,10 @@ var StreamRegistry = class {
 					code: SSEErrorCode.STREAM_EVICTED
 				})}\n\n`);
 			} catch (_error) {}
-			this._clearGraceTimer(oldestStream);
-			oldestStream.abortController.abort("Stream evicted");
-			this.streams.remove(oldestStream.streamId);
+			clearGraceTimer(oldestStream);
+			oldestStream.abortController.abort(new DOMException("Stream evicted", "AbortError"));
+			clearRemovalTimer(oldestStream);
+			this.streams.delete(oldestStream.streamId);
 		}
 	}
 };

package/dist/stream/stream-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-registry.js","names":[],"sources":["../../src/stream/stream-registry.ts"],"sourcesContent":["import { RingBuffer } from \"./buffers\";\nimport { SSEErrorCode, type StreamEntry } from \"./types\";\n\nexport class StreamRegistry {\n  private streams: RingBuffer<StreamEntry>;\n\n  constructor(maxActiveStreams: number) {\n    this.streams = new RingBuffer<StreamEntry>(\n      maxActiveStreams,\n      (entry) => entry.streamId,\n    );\n  }\n\n  // add a stream to the registry\n  add(entry: StreamEntry): void {\n    // enforce hard cap\n    if (this.streams.getSize() >= this.streams.capacity) {\n      this._evictOldestStream(entry.streamId);\n    }\n\n    this.streams.add(entry);\n  }\n\n  // get a stream from the registry\n  get(streamId: string): StreamEntry | null {\n    return this.streams.get(streamId);\n  }\n\n  // check if a stream exists in the registry\n  has(streamId: string): boolean {\n    return this.streams.has(streamId);\n  }\n\n  // remove a stream from the registry\n  remove(streamId: string): void {\n    this.streams.remove(streamId);\n  }\n\n  // get the number of streams in the registry\n  size(): number {\n    return this.streams.getSize();\n  }\n\n  clear(): void {\n    const allStreams = this.streams.getAll();\n\n    for (const stream of allStreams) {\n      this._clearGraceTimer(stream);\n      stream.abortController.abort(\"Server shutdown\");\n    }\n\n    this.streams.clear();\n  }\n\n  // clear a pending grace timer so a removed stream isn't pinned until it fires\n  private _clearGraceTimer(stream: StreamEntry): void {\n    if (stream.disconnectGraceTimer) {\n      clearTimeout(stream.disconnectGraceTimer);\n      stream.disconnectGraceTimer = undefined;\n    }\n  }\n\n  // evict the oldest stream from the registry\n  private _evictOldestStream(excludeStreamId: string): void {\n    const allStreams = this.streams.getAll();\n    let oldestStream: StreamEntry | null = null;\n    let oldestAccess = Infinity;\n\n    // find the least recently accessed stream\n    for (const stream of allStreams) {\n      if (\n        stream.streamId !== excludeStreamId &&\n        stream.lastAccess < oldestAccess\n      ) {\n        oldestStream = stream;\n        oldestAccess = stream.lastAccess;\n      }\n    }\n\n    // abort the oldest stream\n    if (oldestStream) {\n      // broadcast stream eviction error to all clients\n      for (const client of oldestStream.clients) {\n        if (!client.writableEnded) {\n          try {\n            client.write(`event: error\\n`);\n            client.write(\n              `data: ${JSON.stringify({ error: \"Stream evicted\", code: SSEErrorCode.STREAM_EVICTED })}\\n\\n`,\n            );\n          } catch (_error) {\n            // ignore\n          }\n        }\n      }\n      this._clearGraceTimer(oldestStream);\n      oldestStream.abortController.abort(\"Stream evicted\");\n      this.streams.remove(oldestStream.streamId);\n    }\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,iBAAb,MAA4B;CAC1B,AAAQ;CAER,YAAY,kBAA0B;AACpC,OAAK,UAAU,IAAI,WACjB,mBACC,UAAU,MAAM,SAClB;;CAIH,IAAI,OAA0B;AAE5B,MAAI,KAAK,QAAQ,SAAS,IAAI,KAAK,QAAQ,SACzC,MAAK,mBAAmB,MAAM,SAAS;AAGzC,OAAK,QAAQ,IAAI,MAAM;;CAIzB,IAAI,UAAsC;AACxC,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,IAAI,UAA2B;AAC7B,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,OAAO,UAAwB;AAC7B,OAAK,QAAQ,OAAO,SAAS;;CAI/B,OAAe;AACb,SAAO,KAAK,QAAQ,SAAS;;CAG/B,QAAc;EACZ,MAAM,aAAa,KAAK,QAAQ,QAAQ;AAExC,OAAK,MAAM,UAAU,YAAY;AAC/B,QAAK,iBAAiB,OAAO;AAC7B,UAAO,gBAAgB,MAAM,kBAAkB;;AAGjD,OAAK,QAAQ,OAAO;;CAItB,AAAQ,iBAAiB,QAA2B;AAClD,MAAI,OAAO,sBAAsB;AAC/B,gBAAa,OAAO,qBAAqB;AACzC,UAAO,uBAAuB;;;CAKlC,AAAQ,mBAAmB,iBAA+B;EACxD,MAAM,aAAa,KAAK,QAAQ,QAAQ;EACxC,IAAI,eAAmC;EACvC,IAAI,eAAe;AAGnB,OAAK,MAAM,UAAU,WACnB,KACE,OAAO,aAAa,mBACpB,OAAO,aAAa,cACpB;AACA,kBAAe;AACf,kBAAe,OAAO;;AAK1B,MAAI,cAAc;AAEhB,QAAK,MAAM,UAAU,aAAa,QAChC,KAAI,CAAC,OAAO,cACV,KAAI;AACF,WAAO,MAAM,iBAAiB;AAC9B,WAAO,MACL,SAAS,KAAK,UAAU;KAAE,OAAO;KAAkB,MAAM,aAAa;KAAgB,CAAC,CAAC,MACzF;YACM,QAAQ;AAKrB,QAAK,iBAAiB,aAAa;AACnC,gBAAa,gBAAgB,MAAM,iBAAiB;AACpD,QAAK,QAAQ,OAAO,aAAa,SAAS"}
+{"version":3,"file":"stream-registry.js","names":[],"sources":["../../src/stream/stream-registry.ts"],"sourcesContent":["import { clearGraceTimer, clearRemovalTimer } from \"./timers\";\nimport { SSEErrorCode, type StreamEntry } from \"./types\";\n\nexport class StreamRegistry {\n  // keyed storage with explicit, policy-driven eviction. A ring buffer is\n  // unsuitable here: it overwrites by insertion slot, so evicting an entry\n  // chosen by policy (e.g. a completed stream) and then adding would\n  // silently clobber an unrelated live stream sitting in the oldest slot.\n  private streams: Map<string, StreamEntry>;\n  private maxActiveStreams: number;\n\n  constructor(maxActiveStreams: number) {\n    this.streams = new Map();\n    this.maxActiveStreams = maxActiveStreams;\n  }\n\n  // add a stream to the registry\n  add(entry: StreamEntry): void {\n    // enforce hard cap, but only when inserting a genuinely new key:\n    // re-adding an existing streamId updates in place and doesn't grow the\n    // map, so evicting another stream for it would destroy an innocent one\n    if (\n      !this.streams.has(entry.streamId) &&\n      this.streams.size >= this.maxActiveStreams\n    ) {\n      this._evictOldestStream(entry.streamId);\n    }\n\n    this.streams.set(entry.streamId, entry);\n  }\n\n  // get a stream from the registry\n  get(streamId: string): StreamEntry | null {\n    return this.streams.get(streamId) ?? null;\n  }\n\n  // check if a stream exists in the registry\n  has(streamId: string): boolean {\n    return this.streams.has(streamId);\n  }\n\n  // remove a stream from the registry\n  remove(streamId: string): void {\n    this.streams.delete(streamId);\n  }\n\n  // get the number of streams in the registry\n  size(): number {\n    return this.streams.size;\n  }\n\n  clear(): void {\n    for (const stream of this.streams.values()) {\n      stream.abortController.abort(\"Server shutdown\");\n      clearGraceTimer(stream);\n      clearRemovalTimer(stream);\n    }\n\n    this.streams.clear();\n  }\n\n  // evict the oldest stream from the registry, preferring completed streams.\n  // Completed streams waiting out their buffer TTL can look recently\n  // accessed, so plain LRU could evict a live stream while dead ones\n  // survive. Prefer the oldest completed stream when one exists and fall\n  // back to LRU over all streams otherwise.\n  private _evictOldestStream(excludeStreamId: string): void {\n    const allStreams = this.streams.values();\n    let oldestStream: StreamEntry | null = null;\n    let oldestAccess = Infinity;\n    let oldestCompletedStream: StreamEntry | null = null;\n    let oldestCompletedAccess = Infinity;\n\n    // find the least recently accessed stream (overall and completed-only)\n    for (const stream of allStreams) {\n      if (stream.streamId === excludeStreamId) continue;\n\n      if (stream.lastAccess < oldestAccess) {\n        oldestStream = stream;\n        oldestAccess = stream.lastAccess;\n      }\n\n      if (stream.isCompleted && stream.lastAccess < oldestCompletedAccess) {\n        oldestCompletedStream = stream;\n        oldestCompletedAccess = stream.lastAccess;\n      }\n    }\n\n    oldestStream = oldestCompletedStream ?? oldestStream;\n\n    // abort the evicted stream\n    if (oldestStream) {\n      // broadcast stream eviction error to all clients\n      for (const client of oldestStream.clients) {\n        if (!client.writableEnded) {\n          try {\n            client.write(`event: error\\n`);\n            client.write(\n              `data: ${JSON.stringify({ error: \"Stream evicted\", code: SSEErrorCode.STREAM_EVICTED })}\\n\\n`,\n            );\n          } catch (_error) {\n            // ignore\n          }\n        }\n      }\n      clearGraceTimer(oldestStream);\n      // abort with a DOMException AbortError so the error categorizer routes\n      // eviction as an abort (matching the manager's terminal paths) rather\n      // than a stream failure\n      oldestStream.abortController.abort(\n        new DOMException(\"Stream evicted\", \"AbortError\"),\n      );\n      // a pending removal timer would otherwise pin the evicted entry\n      clearRemovalTimer(oldestStream);\n      this.streams.delete(oldestStream.streamId);\n    }\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,iBAAb,MAA4B;CAK1B,AAAQ;CACR,AAAQ;CAER,YAAY,kBAA0B;AACpC,OAAK,0BAAU,IAAI,KAAK;AACxB,OAAK,mBAAmB;;CAI1B,IAAI,OAA0B;AAI5B,MACE,CAAC,KAAK,QAAQ,IAAI,MAAM,SAAS,IACjC,KAAK,QAAQ,QAAQ,KAAK,iBAE1B,MAAK,mBAAmB,MAAM,SAAS;AAGzC,OAAK,QAAQ,IAAI,MAAM,UAAU,MAAM;;CAIzC,IAAI,UAAsC;AACxC,SAAO,KAAK,QAAQ,IAAI,SAAS,IAAI;;CAIvC,IAAI,UAA2B;AAC7B,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,OAAO,UAAwB;AAC7B,OAAK,QAAQ,OAAO,SAAS;;CAI/B,OAAe;AACb,SAAO,KAAK,QAAQ;;CAGtB,QAAc;AACZ,OAAK,MAAM,UAAU,KAAK,QAAQ,QAAQ,EAAE;AAC1C,UAAO,gBAAgB,MAAM,kBAAkB;AAC/C,mBAAgB,OAAO;AACvB,qBAAkB,OAAO;;AAG3B,OAAK,QAAQ,OAAO;;CAQtB,AAAQ,mBAAmB,iBAA+B;EACxD,MAAM,aAAa,KAAK,QAAQ,QAAQ;EACxC,IAAI,eAAmC;EACvC,IAAI,eAAe;EACnB,IAAI,wBAA4C;EAChD,IAAI,wBAAwB;AAG5B,OAAK,MAAM,UAAU,YAAY;AAC/B,OAAI,OAAO,aAAa,gBAAiB;AAEzC,OAAI,OAAO,aAAa,cAAc;AACpC,mBAAe;AACf,mBAAe,OAAO;;AAGxB,OAAI,OAAO,eAAe,OAAO,aAAa,uBAAuB;AACnE,4BAAwB;AACxB,4BAAwB,OAAO;;;AAInC,iBAAe,yBAAyB;AAGxC,MAAI,cAAc;AAEhB,QAAK,MAAM,UAAU,aAAa,QAChC,KAAI,CAAC,OAAO,cACV,KAAI;AACF,WAAO,MAAM,iBAAiB;AAC9B,WAAO,MACL,SAAS,KAAK,UAAU;KAAE,OAAO;KAAkB,MAAM,aAAa;KAAgB,CAAC,CAAC,MACzF;YACM,QAAQ;AAKrB,mBAAgB,aAAa;AAI7B,gBAAa,gBAAgB,MAC3B,IAAI,aAAa,kBAAkB,aAAa,CACjD;AAED,qBAAkB,aAAa;AAC/B,QAAK,QAAQ,OAAO,aAAa,SAAS"}

package/dist/stream/timers.js

@@ -0,0 +1,17 @@
+//#region src/stream/timers.ts
+function clearGraceTimer(entry) {
+	if (entry.disconnectGraceTimer) {
+		clearTimeout(entry.disconnectGraceTimer);
+		entry.disconnectGraceTimer = void 0;
+	}
+}
+function clearRemovalTimer(entry) {
+	if (entry.removalTimer) {
+		clearTimeout(entry.removalTimer);
+		entry.removalTimer = void 0;
+	}
+}
+
+//#endregion
+export { clearGraceTimer, clearRemovalTimer };
+//# sourceMappingURL=timers.js.map

package/dist/stream/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.js","names":[],"sources":["../../src/stream/timers.ts"],"sourcesContent":["import type { StreamEntry } from \"./types\";\n\n// clear a pending disconnect-grace timer so a removed/reconnected stream\n// isn't pinned until it fires\nexport function clearGraceTimer(entry: StreamEntry): void {\n  if (entry.disconnectGraceTimer) {\n    clearTimeout(entry.disconnectGraceTimer);\n    entry.disconnectGraceTimer = undefined;\n  }\n}\n\n// clear a pending registry-removal timer so a reconnected/evicted stream\n// isn't pulled out from under a client\nexport function clearRemovalTimer(entry: StreamEntry): void {\n  if (entry.removalTimer) {\n    clearTimeout(entry.removalTimer);\n    entry.removalTimer = undefined;\n  }\n}\n"],"mappings":";AAIA,SAAgB,gBAAgB,OAA0B;AACxD,KAAI,MAAM,sBAAsB;AAC9B,eAAa,MAAM,qBAAqB;AACxC,QAAM,uBAAuB;;;AAMjC,SAAgB,kBAAkB,OAA0B;AAC1D,KAAI,MAAM,cAAc;AACtB,eAAa,MAAM,aAAa;AAChC,QAAM,eAAe"}

package/dist/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n  STREAM_FORBIDDEN: \"STREAM_FORBIDDEN\",\n  UPSTREAM_ERROR: \"UPSTREAM_ERROR\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n  /**\n   * Upstream-domain structured code (e.g. `RESULT_TOO_LARGE_FOR_JSON_FALLBACK`,\n   * `NOT_IMPLEMENTED`). UI code should branch on this instead of parsing\n   * the human-readable `error` string.\n   */\n  errorCode?: string;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  /**\n   * Identifier of the principal that created the stream (e.g. end-user ID\n   * or service principal user ID). When set, only requests sharing the\n   * same owner key may reconnect to the stream.\n   */\n  ownerKey?: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n  // pending grace-window abort, set while the last client is disconnected\n  disconnectGraceTimer?: NodeJS.Timeout;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CAChB,kBAAkB;CAClB,gBAAgB;CACjB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n  STREAM_FORBIDDEN: \"STREAM_FORBIDDEN\",\n  UPSTREAM_ERROR: \"UPSTREAM_ERROR\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n  /**\n   * Upstream-domain structured code (e.g. `RESULT_TOO_LARGE_FOR_JSON_FALLBACK`,\n   * `NOT_IMPLEMENTED`). UI code should branch on this instead of parsing\n   * the human-readable `error` string.\n   */\n  errorCode?: string;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  /**\n   * Identifier of the principal that created the stream (e.g. end-user ID\n   * or service principal user ID). When set, only requests sharing the\n   * same owner key may reconnect to the stream.\n   */\n  ownerKey?: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n  // pending grace-window abort, set while the last client is disconnected\n  disconnectGraceTimer?: NodeJS.Timeout;\n  /**\n   * Pending registry-removal timer. At most one removal timer exists per\n   * stream; scheduling a new one clears any previous timer first.\n   */\n  removalTimer?: NodeJS.Timeout;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CAChB,kBAAkB;CAClB,gBAAgB;CACjB"}

package/dist/telemetry/telemetry-manager.js

@@ -19,6 +19,7 @@ var TelemetryManager = class TelemetryManager {
 	static DEFAULT_FALLBACK_APP_NAME = "databricks-app";
 	static instance;
 	sdk;
+	shutdownPromise;
 	/**
 	* Create a scoped telemetry provider for a specific plugin.
 	* The plugin's name will be used as the default tracer/meter name.
@@ -54,7 +55,6 @@ var TelemetryManager = class TelemetryManager {
 				instrumentations: this.getDefaultInstrumentations()
 			});
 			this.sdk.start();
-			this.registerShutdown();
 			logger.debug("Initialized successfully");
 		} catch (error) {
 			logger.error("Failed to initialize: %O", error);
@@ -90,21 +90,27 @@ var TelemetryManager = class TelemetryManager {
 			"@opentelemetry/instrumentation-net": { enabled: false }
 		})];
 	}
-	registerShutdown() {
-		const shutdownFn = async () => {
-			await TelemetryManager.getInstance().shutdown();
-		};
-		process.once("SIGTERM", shutdownFn);
-		process.once("SIGINT", shutdownFn);
-	}
+	/**
+	* Flush and shut down the OpenTelemetry SDK.
+	*
+	* Idempotent: the SDK reference is cleared synchronously and concurrent
+	* or repeated calls await the same in-flight flush. Awaited by the core
+	* lifecycle manager during graceful shutdown — that manager owns the
+	* process signal handlers, so telemetry no longer registers its own.
+	*/
 	async shutdown() {
-		if (!this.sdk) return;
-		try {
-			await this.sdk.shutdown();
+		if (this.sdk) {
+			const sdk = this.sdk;
 			this.sdk = void 0;
-		} catch (error) {
-			logger.error("Error shutting down: %O", error);
+			this.shutdownPromise = (async () => {
+				try {
+					await sdk.shutdown();
+				} catch (error) {
+					logger.error("Error shutting down: %O", error);
+				}
+			})();
 		}
+		return this.shutdownPromise;
 	}
 };
 

package/dist/telemetry/telemetry-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport type { TelemetryOptions } from \"shared\";\nimport { createLogger } from \"../logging/logger\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport { AppKitSampler } from \"./trace-sampler\";\nimport type { TelemetryConfig } from \"./types\";\n\nconst logger = createLogger(\"telemetry\");\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AppKitSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      this.registerShutdown();\n      logger.debug(\"Initialized successfully\");\n    } catch (error) {\n      logger.error(\"Failed to initialize: %O\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  private registerShutdown() {\n    const shutdownFn = async () => {\n      await TelemetryManager.getInstance().shutdown();\n    };\n    process.once(\"SIGTERM\", shutdownFn);\n    process.once(\"SIGINT\", shutdownFn);\n  }\n\n  private async shutdown(): Promise<void> {\n    if (!this.sdk) {\n      return;\n    }\n\n    try {\n      await this.sdk.shutdown();\n      this.sdk = undefined;\n    } catch (error) {\n      logger.error(\"Error shutting down: %O\", error);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,MAAM,SAAS,aAAa,YAAY;AAExC,IAAa,mBAAb,MAAa,iBAAiB;CAC5B,OAAwB,6BAA6B;CACrD,OAAwB,4BAA4B;CAEpD,OAAe;CACf,AAAQ;;;;;;;;CASR,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,eAAe;IAC5B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,QAAK,kBAAkB;AACvB,UAAO,MAAM,2BAA2B;WACjC,OAAO;AACd,UAAO,MAAM,4BAA4B,MAAM;;;;;;;;CASnD,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;CAGH,AAAQ,mBAAmB;EACzB,MAAM,aAAa,YAAY;AAC7B,SAAM,iBAAiB,aAAa,CAAC,UAAU;;AAEjD,UAAQ,KAAK,WAAW,WAAW;AACnC,UAAQ,KAAK,UAAU,WAAW;;CAGpC,MAAc,WAA0B;AACtC,MAAI,CAAC,KAAK,IACR;AAGF,MAAI;AACF,SAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM;WACJ,OAAO;AACd,UAAO,MAAM,2BAA2B,MAAM"}
+{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport type { TelemetryOptions } from \"shared\";\nimport { createLogger } from \"../logging/logger\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport { AppKitSampler } from \"./trace-sampler\";\nimport type { TelemetryConfig } from \"./types\";\n\nconst logger = createLogger(\"telemetry\");\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n  private shutdownPromise?: Promise<void>;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AppKitSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      logger.debug(\"Initialized successfully\");\n    } catch (error) {\n      logger.error(\"Failed to initialize: %O\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  /**\n   * Flush and shut down the OpenTelemetry SDK.\n   *\n   * Idempotent: the SDK reference is cleared synchronously and concurrent\n   * or repeated calls await the same in-flight flush. Awaited by the core\n   * lifecycle manager during graceful shutdown — that manager owns the\n   * process signal handlers, so telemetry no longer registers its own.\n   */\n  async shutdown(): Promise<void> {\n    if (this.sdk) {\n      const sdk = this.sdk;\n      this.sdk = undefined;\n      this.shutdownPromise = (async () => {\n        try {\n          await sdk.shutdown();\n        } catch (error) {\n          logger.error(\"Error shutting down: %O\", error);\n        }\n      })();\n    }\n\n    return this.shutdownPromise;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,MAAM,SAAS,aAAa,YAAY;AAExC,IAAa,mBAAb,MAAa,iBAAiB;CAC5B,OAAwB,6BAA6B;CACrD,OAAwB,4BAA4B;CAEpD,OAAe;CACf,AAAQ;CACR,AAAQ;;;;;;;;CASR,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,eAAe;IAC5B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,UAAO,MAAM,2BAA2B;WACjC,OAAO;AACd,UAAO,MAAM,4BAA4B,MAAM;;;;;;;;CASnD,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;;;;;;;;;CAWH,MAAM,WAA0B;AAC9B,MAAI,KAAK,KAAK;GACZ,MAAM,MAAM,KAAK;AACjB,QAAK,MAAM;AACX,QAAK,mBAAmB,YAAY;AAClC,QAAI;AACF,WAAM,IAAI,UAAU;aACb,OAAO;AACd,YAAO,MAAM,2BAA2B,MAAM;;OAE9C;;AAGN,SAAO,KAAK"}

package/dist/utils/safe-handler.js

@@ -0,0 +1,28 @@
+//#region src/utils/safe-handler.ts
+/**
+* Wrap an Express handler so synchronous throws and async rejections are
+* forwarded to the error-handling middleware via `next(err)`.
+*
+* Express 4 does not catch rejected promises from async handlers — a
+* rejection (e.g. `asUser()` throwing `AuthenticationError` before any
+* response is written) escapes as an unhandledRejection, which leaves the
+* request hanging and crashes Node by default.
+*
+* Error-handling middleware (arity 4, `(err, req, res, next)`) is returned
+* unchanged: Express identifies it by function arity, so wrapping it would
+* silently turn it into a regular handler.
+*
+* Note: handlers must RETURN their promise (e.g. `(req, res) =>
+* this._handle(req, res)` or `async (req, res) => { await ... }`) for
+* rejections to be caught — a fire-and-forget body like
+* `(req, res) => { this._handle(req, res); }` hides the promise from the
+* wrapper and rejections escape as unhandledRejection again.
+*/
+function forwardAsyncErrors(handler) {
+	if (handler.length > 3) return handler;
+	return (req, res, next) => Promise.resolve().then(() => handler(req, res, next)).catch(next);
+}
+
+//#endregion
+export { forwardAsyncErrors };
+//# sourceMappingURL=safe-handler.js.map

package/dist/utils/safe-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-handler.js","names":[],"sources":["../../src/utils/safe-handler.ts"],"sourcesContent":["import type express from \"express\";\n\n/**\n * Wrap an Express handler so synchronous throws and async rejections are\n * forwarded to the error-handling middleware via `next(err)`.\n *\n * Express 4 does not catch rejected promises from async handlers — a\n * rejection (e.g. `asUser()` throwing `AuthenticationError` before any\n * response is written) escapes as an unhandledRejection, which leaves the\n * request hanging and crashes Node by default.\n *\n * Error-handling middleware (arity 4, `(err, req, res, next)`) is returned\n * unchanged: Express identifies it by function arity, so wrapping it would\n * silently turn it into a regular handler.\n *\n * Note: handlers must RETURN their promise (e.g. `(req, res) =>\n * this._handle(req, res)` or `async (req, res) => { await ... }`) for\n * rejections to be caught — a fire-and-forget body like\n * `(req, res) => { this._handle(req, res); }` hides the promise from the\n * wrapper and rejections escape as unhandledRejection again.\n */\nexport function forwardAsyncErrors(\n  handler: (\n    req: express.Request,\n    res: express.Response,\n    next: express.NextFunction,\n  ) => unknown,\n): express.RequestHandler {\n  if (handler.length > 3) return handler as express.RequestHandler;\n  return (req, res, next) =>\n    Promise.resolve()\n      .then(() => handler(req, res, next))\n      .catch(next);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,mBACd,SAKwB;AACxB,KAAI,QAAQ,SAAS,EAAG,QAAO;AAC/B,SAAQ,KAAK,KAAK,SAChB,QAAQ,SAAS,CACd,WAAW,QAAQ,KAAK,KAAK,KAAK,CAAC,CACnC,MAAM,KAAK"}

package/docs/api/appkit/Class.Plugin.md

@@ -224,6 +224,8 @@ abortActiveOperations(): void;
 
 ```
 
+Cancel in-flight work (abort signals, SSE streams). Runs in the first phase of graceful shutdown, BEFORE any plugin's `shutdown()` hook — so it must not tear down shared resources (e.g. connection pools) that other plugins' hooks may still need. Put teardown in `shutdown()`.
+
 #### Returns[​](#returns-1 "Direct link to Returns")
 
 `void`

package/docs/api/appkit/Class.ResourceRegistry.md

@@ -249,7 +249,7 @@ const registry = ResourceRegistry.getInstance();
 const result = registry.validate();
 
 if (!result.valid) {
-  console.error("Missing resources:", result.missing.map(r => Object.values(r.fields).map(f => f.env)));
+  console.error(ResourceRegistry.formatMissingResources(result.missing));
 }
 
 ```

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -35,6 +35,17 @@ When true, the thread used for a chat request against this agent is deleted from
 
 ***
 
+### generationParams?[​](#generationparams "Direct link to generationParams?")
+
+```ts
+optional generationParams: GenerationParams;
+
+```
+
+Optional generation parameters (`temperature`, `top_p`, `stop`, `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible serving request body. Only set keys are sent. Applied only when AppKit builds the adapter itself (string or omitted `model`); when you pass a pre-built `AgentAdapter`, configure generation params on it directly.
+
+***
+
 ### instructions[​](#instructions "Direct link to instructions")
 
 ```ts

package/docs/api/appkit/Interface.GenerationParams.md

@@ -0,0 +1,58 @@
+# Interface: GenerationParams
+
+Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### frequency\_penalty?[​](#frequency_penalty "Direct link to frequency_penalty?")
+
+```ts
+optional frequency_penalty: number;
+
+```
+
+Penalize tokens by frequency.
+
+***
+
+### presence\_penalty?[​](#presence_penalty "Direct link to presence_penalty?")
+
+```ts
+optional presence_penalty: number;
+
+```
+
+Penalize tokens by prior presence.
+
+***
+
+### stop?[​](#stop "Direct link to stop?")
+
+```ts
+optional stop: string | string[];
+
+```
+
+Stop sequence(s) that end generation.
+
+***
+
+### temperature?[​](#temperature "Direct link to temperature?")
+
+```ts
+optional temperature: number;
+
+```
+
+Sampling temperature.
+
+***
+
+### top\_p?[​](#top_p "Direct link to top_p?")
+
+```ts
+optional top_p: number;
+
+```
+
+Nucleus sampling probability mass (`top_p`).

package/docs/api/appkit/Interface.RegisteredAgent.md

@@ -31,6 +31,17 @@ Mirrors `AgentDefinition.ephemeral` — skip thread persistence.
 
 ***
 
+### generationParams?[​](#generationparams "Direct link to generationParams?")
+
+```ts
+optional generationParams: GenerationParams;
+
+```
+
+Mirrors `AgentDefinition.generationParams`.
+
+***
+
 ### instructions[​](#instructions "Direct link to instructions")
 
 ```ts

package/docs/api/appkit.md

@@ -47,6 +47,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [FileResource](./docs/api/appkit/Interface.FileResource.md)                                           | Describes the file or directory being acted upon.                                                                                                                                                                                                                                                                                                                                                                                          |
 | [FunctionTool](./docs/api/appkit/Interface.FunctionTool.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                                                                                                                                                                                               |
+| [GenerationParams](./docs/api/appkit/Interface.GenerationParams.md)                                   | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates.                                                                                                                                     |
 | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md)                                             | Configuration for the Jobs plugin.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                                                                                                                                                                                                |
 | [JobAPI](./docs/api/appkit/Interface.JobAPI.md)                                                       | User-facing API for a single configured job.                                                                                                                                                                                                                                                                                                                                                                                               |

package/llms.txt

@@ -125,6 +125,7 @@ npx @databricks/appkit docs <query>
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
+- [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {