@copilotkit/shared 1.72.0 → 1.73.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/LICENSE +21 -0
  2. package/dist/finalize-events.cjs +92 -71
  3. package/dist/finalize-events.cjs.map +1 -1
  4. package/dist/finalize-events.d.cts +20 -1
  5. package/dist/finalize-events.d.cts.map +1 -1
  6. package/dist/finalize-events.d.mts +20 -1
  7. package/dist/finalize-events.d.mts.map +1 -1
  8. package/dist/finalize-events.mjs +92 -72
  9. package/dist/finalize-events.mjs.map +1 -1
  10. package/dist/index.cjs +7 -0
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +4 -3
  13. package/dist/index.d.cts.map +1 -1
  14. package/dist/index.d.mts +4 -3
  15. package/dist/index.d.mts.map +1 -1
  16. package/dist/index.mjs +4 -3
  17. package/dist/index.mjs.map +1 -1
  18. package/dist/index.umd.js +218 -72
  19. package/dist/index.umd.js.map +1 -1
  20. package/dist/package.cjs +1 -1
  21. package/dist/package.mjs +1 -1
  22. package/dist/telemetry/events.d.cts +33 -0
  23. package/dist/telemetry/events.d.cts.map +1 -1
  24. package/dist/telemetry/events.d.mts +33 -0
  25. package/dist/telemetry/events.d.mts.map +1 -1
  26. package/dist/telemetry/index.cjs +3 -0
  27. package/dist/telemetry/index.d.cts +2 -2
  28. package/dist/telemetry/index.d.mts +2 -2
  29. package/dist/telemetry/index.mjs +2 -2
  30. package/dist/telemetry/model-host.cjs +104 -0
  31. package/dist/telemetry/model-host.cjs.map +1 -0
  32. package/dist/telemetry/model-host.d.cts +26 -0
  33. package/dist/telemetry/model-host.d.cts.map +1 -0
  34. package/dist/telemetry/model-host.d.mts +26 -0
  35. package/dist/telemetry/model-host.d.mts.map +1 -0
  36. package/dist/telemetry/model-host.mjs +102 -0
  37. package/dist/telemetry/model-host.mjs.map +1 -0
  38. package/dist/telemetry/sampling.cjs +22 -0
  39. package/dist/telemetry/sampling.cjs.map +1 -1
  40. package/dist/telemetry/sampling.d.cts +22 -2
  41. package/dist/telemetry/sampling.d.cts.map +1 -1
  42. package/dist/telemetry/sampling.d.mts +22 -2
  43. package/dist/telemetry/sampling.d.mts.map +1 -1
  44. package/dist/telemetry/sampling.mjs +20 -1
  45. package/dist/telemetry/sampling.mjs.map +1 -1
  46. package/dist/telemetry/telemetry-client.cjs +18 -11
  47. package/dist/telemetry/telemetry-client.cjs.map +1 -1
  48. package/dist/telemetry/telemetry-client.d.cts +3 -3
  49. package/dist/telemetry/telemetry-client.d.cts.map +1 -1
  50. package/dist/telemetry/telemetry-client.d.mts +3 -3
  51. package/dist/telemetry/telemetry-client.d.mts.map +1 -1
  52. package/dist/telemetry/telemetry-client.mjs +19 -12
  53. package/dist/telemetry/telemetry-client.mjs.map +1 -1
  54. package/package.json +1 -1
  55. package/src/finalize-events.test.ts +146 -0
  56. package/src/finalize-events.ts +124 -124
  57. package/src/index.ts +9 -1
  58. package/src/telemetry/events.ts +33 -0
  59. package/src/telemetry/model-host.test.ts +145 -0
  60. package/src/telemetry/model-host.ts +155 -0
  61. package/src/telemetry/sampling.ts +39 -6
  62. package/src/telemetry/telemetry-blank-license-identity.test.ts +11 -4
  63. package/src/telemetry/telemetry-client.test.ts +107 -39
  64. package/src/telemetry/telemetry-client.ts +48 -27
@@ -0,0 +1,146 @@
1
+ import type {
2
+ BaseEvent,
3
+ RunErrorEvent,
4
+ ToolCallResultEvent,
5
+ } from "@ag-ui/client";
6
+ import { EventType } from "@ag-ui/client";
7
+ import { describe, expect, it } from "vitest";
8
+
9
+ import { createRunEventFinalizer, finalizeRunEvents } from "./finalize-events";
10
+
11
+ const event = (value: Record<string, unknown>): BaseEvent => value as BaseEvent;
12
+
13
+ describe("createRunEventFinalizer", () => {
14
+ it("closes what is still open and adds a terminal event", () => {
15
+ const source = [
16
+ event({ type: EventType.TEXT_MESSAGE_START, messageId: "message-1" }),
17
+ event({ type: EventType.TOOL_CALL_START, toolCallId: "tool-1" }),
18
+ event({ type: EventType.TOOL_CALL_END, toolCallId: "tool-1" }),
19
+ ];
20
+
21
+ for (const options of [{ stopRequested: true }, {}]) {
22
+ const finalizer = createRunEventFinalizer();
23
+ for (const value of source) finalizer.observe(value);
24
+ const appended = finalizer.finalize(options);
25
+
26
+ expect(appended.map(({ type }) => type)).toEqual([
27
+ EventType.TEXT_MESSAGE_END,
28
+ EventType.TOOL_CALL_RESULT,
29
+ options.stopRequested ? EventType.RUN_FINISHED : EventType.RUN_ERROR,
30
+ ]);
31
+ const result = appended[1] as ToolCallResultEvent;
32
+ expect(JSON.parse(result.content)).toMatchObject({
33
+ status: options.stopRequested ? "stopped" : "error",
34
+ reason: options.stopRequested
35
+ ? "stop_requested"
36
+ : "missing_terminal_event",
37
+ });
38
+ expect(finalizer.finalize(options)).toEqual([]);
39
+ }
40
+ });
41
+
42
+ it.each([EventType.RUN_FINISHED, EventType.RUN_ERROR])(
43
+ "appends nothing once %s was observed",
44
+ (terminal) => {
45
+ const finalizer = createRunEventFinalizer();
46
+ finalizer.observe(
47
+ event({ type: EventType.TEXT_MESSAGE_START, messageId: "message-1" }),
48
+ );
49
+ finalizer.observe(
50
+ event({ type: terminal, message: "finished upstream" }),
51
+ );
52
+ finalizer.observe(
53
+ event({ type: EventType.TEXT_MESSAGE_START, messageId: "message-2" }),
54
+ );
55
+
56
+ expect(finalizer.finalize()).toEqual([]);
57
+ },
58
+ );
59
+
60
+ it("forgets a lifecycle as soon as it closes", () => {
61
+ const finalizer = createRunEventFinalizer();
62
+ for (let index = 0; index < 1000; index += 1) {
63
+ const messageId = `message-${index}`;
64
+ const toolCallId = `tool-${index}`;
65
+ for (const value of [
66
+ event({ type: EventType.TEXT_MESSAGE_START, messageId }),
67
+ event({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: "x" }),
68
+ event({ type: EventType.TEXT_MESSAGE_END, messageId }),
69
+ event({ type: EventType.TOOL_CALL_START, toolCallId }),
70
+ event({ type: EventType.TOOL_CALL_RESULT, toolCallId, content: "x" }),
71
+ event({ type: EventType.TOOL_CALL_END, toolCallId }),
72
+ ]) {
73
+ finalizer.observe(value);
74
+ }
75
+ }
76
+ finalizer.observe(
77
+ event({ type: EventType.TEXT_MESSAGE_START, messageId: "open" }),
78
+ );
79
+
80
+ expect(finalizer.finalize()).toEqual([
81
+ { type: EventType.TEXT_MESSAGE_END, messageId: "open" },
82
+ expect.objectContaining({ type: EventType.RUN_ERROR }),
83
+ ]);
84
+ });
85
+
86
+ it.each([
87
+ [EventType.TOOL_CALL_END, EventType.TOOL_CALL_RESULT],
88
+ [EventType.TOOL_CALL_RESULT, EventType.TOOL_CALL_END],
89
+ ])("preserves %s across a repeated start before %s", (first, last) => {
90
+ const finalizer = createRunEventFinalizer();
91
+ for (const type of [
92
+ EventType.TOOL_CALL_START,
93
+ first,
94
+ EventType.TOOL_CALL_START,
95
+ last,
96
+ ]) {
97
+ finalizer.observe(event({ type, toolCallId: "tool-1" }));
98
+ }
99
+
100
+ expect(finalizer.finalize().map(({ type }) => type)).toEqual([
101
+ EventType.RUN_ERROR,
102
+ ]);
103
+ });
104
+
105
+ it("ignores start events without an id so finalize never emits an empty id", () => {
106
+ const finalizer = createRunEventFinalizer();
107
+ finalizer.observe(
108
+ event({ type: EventType.TEXT_MESSAGE_START, messageId: "" }),
109
+ );
110
+ finalizer.observe(
111
+ event({ type: EventType.TOOL_CALL_START, toolCallId: "" }),
112
+ );
113
+ finalizer.observe(event({ type: EventType.TOOL_CALL_START }));
114
+
115
+ expect(finalizer.finalize().map((e) => e.type)).toEqual([
116
+ EventType.RUN_ERROR,
117
+ ]);
118
+ });
119
+ });
120
+
121
+ describe("finalizeRunEvents", () => {
122
+ it("appends the closers in place and keeps the interruption message", () => {
123
+ const events = [
124
+ event({ type: EventType.TOOL_CALL_START, toolCallId: "tool-1" }),
125
+ event({
126
+ type: EventType.TOOL_CALL_RESULT,
127
+ toolCallId: "tool-1",
128
+ messageId: "result-1",
129
+ role: "tool",
130
+ content: "done",
131
+ }),
132
+ ];
133
+ const appended = finalizeRunEvents(events, {
134
+ interruptionMessage: "Gateway connection failed",
135
+ });
136
+
137
+ expect(appended.map(({ type }) => type)).toEqual([
138
+ EventType.TOOL_CALL_END,
139
+ EventType.RUN_ERROR,
140
+ ]);
141
+ expect((appended[1] as RunErrorEvent).message).toBe(
142
+ "Gateway connection failed",
143
+ );
144
+ expect(events.slice(-2)).toEqual(appended);
145
+ });
146
+ });
@@ -1,164 +1,164 @@
1
1
  import type { BaseEvent, RunErrorEvent } from "@ag-ui/client";
2
2
  import { EventType } from "@ag-ui/client";
3
- import { randomUUID } from "./utils";
4
3
 
5
- interface FinalizeRunOptions {
4
+ export interface FinalizeRunOptions {
6
5
  stopRequested?: boolean;
7
6
  interruptionMessage?: string;
8
7
  }
9
8
 
9
+ export interface RunEventFinalizer {
10
+ /** Observe one streamed event. Only the ids of open lifecycles are kept. */
11
+ observe(event: BaseEvent): void;
12
+ /** Return the events that close an interrupted or abruptly ended stream. */
13
+ finalize(options?: FinalizeRunOptions): BaseEvent[];
14
+ }
15
+
10
16
  const defaultStopMessage = "Run stopped by user";
11
17
  const defaultAbruptEndMessage = "Run ended without emitting a terminal event";
12
18
 
13
- export function finalizeRunEvents(
14
- events: BaseEvent[],
15
- options: FinalizeRunOptions = {},
16
- ): BaseEvent[] {
17
- const { stopRequested = false, interruptionMessage } = options;
18
-
19
- const resolvedStopMessage = interruptionMessage ?? defaultStopMessage;
20
- const resolvedAbruptMessage =
21
- interruptionMessage && interruptionMessage !== defaultStopMessage
22
- ? interruptionMessage
23
- : defaultAbruptEndMessage;
24
-
25
- const appended: BaseEvent[] = [];
19
+ interface OpenToolCall {
20
+ hasEnd: boolean;
21
+ hasResult: boolean;
22
+ }
26
23
 
24
+ /**
25
+ * Incremental finalizer for a streamed AG-UI run. Feed every event to
26
+ * `observe`; when the stream ends without a terminal event, `finalize` returns
27
+ * the closers for text messages and tool calls still open plus a terminal
28
+ * event. Closed lifecycles are forgotten at once and payloads are never kept,
29
+ * so a caller does not have to retain the event array for this purpose.
30
+ */
31
+ export function createRunEventFinalizer(): RunEventFinalizer {
27
32
  const openMessageIds = new Set<string>();
28
- const openToolCalls = new Map<
29
- string,
30
- {
31
- hasEnd: boolean;
32
- hasResult: boolean;
33
- }
34
- >();
33
+ const openToolCalls = new Map<string, OpenToolCall>();
34
+ let terminalEventObserved = false;
35
+
36
+ const observe = (event: BaseEvent) => {
37
+ if (terminalEventObserved) return;
35
38
 
36
- for (const event of events) {
37
39
  switch (event.type) {
38
40
  case EventType.TEXT_MESSAGE_START: {
39
41
  const messageId = (event as { messageId?: string }).messageId;
40
- if (typeof messageId === "string") {
41
- openMessageIds.add(messageId);
42
- }
42
+ if (messageId) openMessageIds.add(messageId);
43
43
  break;
44
44
  }
45
45
  case EventType.TEXT_MESSAGE_END: {
46
46
  const messageId = (event as { messageId?: string }).messageId;
47
- if (typeof messageId === "string") {
48
- openMessageIds.delete(messageId);
49
- }
47
+ if (typeof messageId === "string") openMessageIds.delete(messageId);
50
48
  break;
51
49
  }
52
50
  case EventType.TOOL_CALL_START: {
53
51
  const toolCallId = (event as { toolCallId?: string }).toolCallId;
54
- if (typeof toolCallId === "string") {
55
- openToolCalls.set(toolCallId, {
56
- hasEnd: false,
57
- hasResult: false,
58
- });
59
- }
60
- break;
61
- }
62
- case EventType.TOOL_CALL_END: {
63
- const toolCallId = (event as { toolCallId?: string }).toolCallId;
64
- const info = toolCallId ? openToolCalls.get(toolCallId) : undefined;
65
- if (info) {
66
- info.hasEnd = true;
52
+ if (toolCallId && !openToolCalls.has(toolCallId)) {
53
+ openToolCalls.set(toolCallId, { hasEnd: false, hasResult: false });
67
54
  }
68
55
  break;
69
56
  }
57
+ case EventType.TOOL_CALL_END:
70
58
  case EventType.TOOL_CALL_RESULT: {
71
59
  const toolCallId = (event as { toolCallId?: string }).toolCallId;
72
- const info = toolCallId ? openToolCalls.get(toolCallId) : undefined;
73
- if (info) {
74
- info.hasResult = true;
75
- }
60
+ if (!toolCallId) break;
61
+ const info = openToolCalls.get(toolCallId);
62
+ if (!info) break;
63
+
64
+ if (event.type === EventType.TOOL_CALL_END) info.hasEnd = true;
65
+ else info.hasResult = true;
66
+ if (info.hasEnd && info.hasResult) openToolCalls.delete(toolCallId);
76
67
  break;
77
68
  }
69
+ case EventType.RUN_FINISHED:
70
+ case EventType.RUN_ERROR:
71
+ terminalEventObserved = true;
72
+ openMessageIds.clear();
73
+ openToolCalls.clear();
74
+ break;
78
75
  default:
79
76
  break;
80
77
  }
81
- }
82
-
83
- const hasTerminalEvent = events.some(
84
- (event) =>
85
- event.type === EventType.RUN_FINISHED ||
86
- event.type === EventType.RUN_ERROR,
87
- );
88
-
89
- // Once a run has emitted a terminal event (RUN_FINISHED or RUN_ERROR), the
90
- // AG-UI spec forbids any further events for that run — the verifier rejects a
91
- // trailing TEXT_MESSAGE_END / TOOL_CALL_END with "the run has already
92
- // errored/finished with '…'. No further events can be sent." (issue #5812).
93
- // These finalization events are streamed *after* everything the agent already
94
- // emitted, so appending closers here would place them after that terminal.
95
- // When a terminal already exists we therefore append nothing: any message or
96
- // tool call still open when the terminal arrived is implicitly closed by the
97
- // terminal on the client. We only synthesize closers + a terminal for a
98
- // stream that ended abruptly without a terminal of its own (below).
99
- if (hasTerminalEvent) {
100
- return appended;
101
- }
102
-
103
- for (const messageId of openMessageIds) {
104
- const endEvent = {
105
- type: EventType.TEXT_MESSAGE_END,
106
- messageId,
107
- } as BaseEvent;
108
- events.push(endEvent);
109
- appended.push(endEvent);
110
- }
111
-
112
- for (const [toolCallId, info] of openToolCalls) {
113
- if (!info.hasEnd) {
114
- const endEvent = {
115
- type: EventType.TOOL_CALL_END,
116
- toolCallId,
117
- } as BaseEvent;
118
- events.push(endEvent);
119
- appended.push(endEvent);
78
+ };
79
+
80
+ const finalize = (options: FinalizeRunOptions = {}): BaseEvent[] => {
81
+ if (terminalEventObserved) return [];
82
+
83
+ const { stopRequested = false, interruptionMessage } = options;
84
+ const resolvedStopMessage = interruptionMessage ?? defaultStopMessage;
85
+ const resolvedAbruptMessage =
86
+ interruptionMessage && interruptionMessage !== defaultStopMessage
87
+ ? interruptionMessage
88
+ : defaultAbruptEndMessage;
89
+ const appended: BaseEvent[] = [];
90
+
91
+ for (const messageId of openMessageIds) {
92
+ appended.push({
93
+ type: EventType.TEXT_MESSAGE_END,
94
+ messageId,
95
+ } as BaseEvent);
96
+ }
97
+
98
+ for (const [toolCallId, info] of openToolCalls) {
99
+ if (!info.hasEnd) {
100
+ appended.push({
101
+ type: EventType.TOOL_CALL_END,
102
+ toolCallId,
103
+ } as BaseEvent);
104
+ }
105
+
106
+ if (!info.hasResult) {
107
+ appended.push({
108
+ type: EventType.TOOL_CALL_RESULT,
109
+ toolCallId,
110
+ messageId: `${toolCallId}-result`,
111
+ role: "tool",
112
+ content: JSON.stringify(
113
+ stopRequested
114
+ ? {
115
+ status: "stopped",
116
+ reason: "stop_requested",
117
+ message: resolvedStopMessage,
118
+ }
119
+ : {
120
+ status: "error",
121
+ reason: "missing_terminal_event",
122
+ message: resolvedAbruptMessage,
123
+ },
124
+ ),
125
+ } as BaseEvent);
126
+ }
120
127
  }
121
128
 
122
- if (!info.hasResult) {
123
- const resultEvent = {
124
- type: EventType.TOOL_CALL_RESULT,
125
- toolCallId,
126
- messageId: `${toolCallId ?? randomUUID()}-result`,
127
- role: "tool",
128
- content: JSON.stringify(
129
- stopRequested
130
- ? {
131
- status: "stopped",
132
- reason: "stop_requested",
133
- message: resolvedStopMessage,
134
- }
135
- : {
136
- status: "error",
137
- reason: "missing_terminal_event",
138
- message: resolvedAbruptMessage,
139
- },
140
- ),
141
- } as BaseEvent;
142
- events.push(resultEvent);
143
- appended.push(resultEvent);
129
+ if (stopRequested) {
130
+ appended.push({ type: EventType.RUN_FINISHED } as BaseEvent);
131
+ } else {
132
+ const errorEvent: RunErrorEvent = {
133
+ type: EventType.RUN_ERROR,
134
+ message: resolvedAbruptMessage,
135
+ code: "INCOMPLETE_STREAM",
136
+ };
137
+ appended.push(errorEvent);
144
138
  }
145
- }
146
-
147
- if (stopRequested) {
148
- const finishedEvent = {
149
- type: EventType.RUN_FINISHED,
150
- } as BaseEvent;
151
- events.push(finishedEvent);
152
- appended.push(finishedEvent);
153
- } else {
154
- const errorEvent: RunErrorEvent = {
155
- type: EventType.RUN_ERROR,
156
- message: resolvedAbruptMessage,
157
- code: "INCOMPLETE_STREAM",
158
- };
159
- events.push(errorEvent);
160
- appended.push(errorEvent);
161
- }
162
139
 
140
+ terminalEventObserved = true;
141
+ openMessageIds.clear();
142
+ openToolCalls.clear();
143
+ return appended;
144
+ };
145
+
146
+ return { observe, finalize };
147
+ }
148
+
149
+ /**
150
+ * Array form of {@link createRunEventFinalizer} for callers that already keep
151
+ * the run's events (runners persist them). Appends the closers to `events` in
152
+ * place and returns them.
153
+ */
154
+ export function finalizeRunEvents(
155
+ events: BaseEvent[],
156
+ options: FinalizeRunOptions = {},
157
+ ): BaseEvent[] {
158
+ const finalizer = createRunEventFinalizer();
159
+ for (const event of events) finalizer.observe(event);
160
+
161
+ const appended = finalizer.finalize(options);
162
+ events.push(...appended);
163
163
  return appended;
164
164
  }
package/src/index.ts CHANGED
@@ -13,6 +13,9 @@ export * from "./constants";
13
13
  // This mirrors the license-verifier note below.
14
14
  export { isTelemetryDisabled } from "./telemetry/telemetry-disabled";
15
15
  export * from "./telemetry/sampling";
16
+ // Pure string classification with no imports, so it carries no runtime edge
17
+ // into browser builds — same reasoning as `sampling` above.
18
+ export * from "./telemetry/model-host";
16
19
  export {
17
20
  firstNonBlankTelemetryId,
18
21
  lambdaClient,
@@ -31,7 +34,12 @@ export * from "./standard-schema";
31
34
  export * from "./attachments";
32
35
 
33
36
  export { logger } from "./logger";
34
- export { finalizeRunEvents } from "./finalize-events";
37
+ export {
38
+ createRunEventFinalizer,
39
+ finalizeRunEvents,
40
+ type FinalizeRunOptions,
41
+ type RunEventFinalizer,
42
+ } from "./finalize-events";
35
43
 
36
44
  export {
37
45
  TranscriptionErrorCode,
@@ -1,3 +1,5 @@
1
+ import type { ModelHostClass } from "./model-host";
2
+
1
3
  export type AnalyticsEvents = {
2
4
  "oss.runtime.instance_created": RuntimeInstanceCreatedInfo;
3
5
  "oss.runtime.copilot_request_created": {
@@ -13,8 +15,29 @@ export type AnalyticsEvents = {
13
15
  hashedLgcKey?: string;
14
16
  error?: string;
15
17
  };
18
+ /**
19
+ * A managed Channel lost its gateway link. Carries only the cause we already
20
+ * compute for the log line — never the Channel name, which is a
21
+ * customer-chosen identifier, and never message content.
22
+ */
23
+ "oss.runtime.channel_session_dropped": ChannelSessionDroppedInfo;
24
+ /** A managed Channel's gateway link came back, and how long it was gone. */
25
+ "oss.runtime.channel_session_recovered": { downForMs: number };
16
26
  };
17
27
 
28
+ /**
29
+ * Kept identical to the v2 runtime's catalog in
30
+ * `packages/runtime/src/v2/runtime/telemetry/events.ts`. The v1 entrypoint
31
+ * hands its capture scope to the V2 runtime it builds, so that scope has to
32
+ * accept every event the V2 runtime can send, channel events included.
33
+ */
34
+ export interface ChannelSessionDroppedInfo {
35
+ /** Diagnosis of the drop, e.g. `the gateway host answered HTTP 502`. */
36
+ reason?: string;
37
+ /** Transport/OS code when the transport named one, e.g. `ECONNRESET`. */
38
+ code?: string;
39
+ }
40
+
18
41
  export interface RuntimeInstanceCreatedInfo {
19
42
  actionsAmount: number;
20
43
  endpointTypes: string[];
@@ -27,6 +50,16 @@ export interface RuntimeInstanceCreatedInfo {
27
50
  }
28
51
 
29
52
  export interface AgentExecutionResponseInfo {
53
+ /**
54
+ * Which vendor the runtime actually sent the completion to, as a closed
55
+ * vocabulary — see `classifyModelHost`. Distinct from `provider` below,
56
+ * which the upstream reports as a model name and which cannot tell Azure,
57
+ * OpenRouter or a local server apart from OpenAI.
58
+ *
59
+ * `unknown` when the developer handed us an already-built model, because
60
+ * the endpoint is unrecoverable from one.
61
+ */
62
+ llmHostClass?: ModelHostClass;
30
63
  provider?: string;
31
64
  model?: string;
32
65
  langGraphHost?: string;
@@ -0,0 +1,145 @@
1
+ import { describe, it, expect } from "vitest";
2
+ import {
3
+ classifyModelHost,
4
+ MODEL_HOST_CLASSES,
5
+ type ModelHostClass,
6
+ } from "./model-host";
7
+
8
+ describe("classifyModelHost", () => {
9
+ describe("the case this exists for: an OpenAI-shaped client aimed elsewhere", () => {
10
+ // Every row below reports `provider: "openai.responses"` from the AI SDK,
11
+ // so the provider label cannot tell them apart. The host can.
12
+ it.each([
13
+ ["https://api.openai.com/v1", "openai"],
14
+ ["https://myresource.openai.azure.com/openai/v1", "azure"],
15
+ ["https://myresource.services.ai.azure.com/models", "azure"],
16
+ ["https://myresource.cognitiveservices.azure.com/", "azure"],
17
+ ["https://openrouter.ai/api/v1", "openrouter"],
18
+ ["http://localhost:11434/v1", "local"],
19
+ ["https://llm.internal.acme.example/v1", "other"],
20
+ ])("classifies %s as %s", (baseUrl, expected) => {
21
+ expect(classifyModelHost(baseUrl, "openai")).toBe(expected);
22
+ });
23
+ });
24
+
25
+ describe("absent base URL falls back to the provider default", () => {
26
+ it("returns the provider default when the base URL is undefined", () => {
27
+ expect(classifyModelHost(undefined, "openai")).toBe("openai");
28
+ expect(classifyModelHost(undefined, "anthropic")).toBe("anthropic");
29
+ });
30
+
31
+ it("returns the provider default for null and empty string", () => {
32
+ expect(classifyModelHost(null, "vertex")).toBe("vertex");
33
+ expect(classifyModelHost("", "vertex")).toBe("vertex");
34
+ expect(classifyModelHost(" ", "vertex")).toBe("vertex");
35
+ });
36
+
37
+ it("defaults to unknown when the caller supplies no provider default", () => {
38
+ // This is the pre-built LanguageModel case: nobody knows the host.
39
+ expect(classifyModelHost(undefined)).toBe("unknown");
40
+ });
41
+ });
42
+
43
+ describe("known vendor hosts", () => {
44
+ it.each([
45
+ ["https://api.anthropic.com", "anthropic"],
46
+ ["https://generativelanguage.googleapis.com/v1beta", "google"],
47
+ ["https://us-central1-aiplatform.googleapis.com/v1", "vertex"],
48
+ ["https://bedrock-runtime.us-east-1.amazonaws.com", "bedrock"],
49
+ ["https://api.groq.com/openai/v1", "groq"],
50
+ ["https://api.unify.ai/v0/", "unify"],
51
+ ["https://api.minimax.io/v1", "minimax"],
52
+ ])("classifies %s as %s", (baseUrl, expected) => {
53
+ expect(classifyModelHost(baseUrl)).toBe(expected);
54
+ });
55
+ });
56
+
57
+ describe("local and private endpoints", () => {
58
+ it.each([
59
+ "http://localhost:1234/v1",
60
+ "http://127.0.0.1:8000/v1",
61
+ "http://[::1]:11434/v1",
62
+ "http://0.0.0.0:11434/v1",
63
+ "http://10.1.2.3:8000/v1",
64
+ "http://192.168.1.50:8000/v1",
65
+ "http://172.16.0.9:8000/v1",
66
+ "http://172.31.255.254:8000/v1",
67
+ "http://host.docker.internal:11434/v1",
68
+ "http://ollama.local:11434/v1",
69
+ ])("treats %s as local", (baseUrl) => {
70
+ expect(classifyModelHost(baseUrl, "openai")).toBe("local");
71
+ });
72
+
73
+ it("does not mistake a public 172.x address for a private one", () => {
74
+ // 172.32.x is outside the 172.16.0.0/12 private block.
75
+ expect(classifyModelHost("http://172.32.0.1:8000/v1", "openai")).toBe(
76
+ "other",
77
+ );
78
+ });
79
+ });
80
+
81
+ describe("it never leaks the host", () => {
82
+ it.each([
83
+ "https://myresource.openai.azure.com/openai/v1",
84
+ "https://acme-secret-gateway.internal.example/v1",
85
+ "not a url at all",
86
+ "://malformed",
87
+ "ftp://weird.example/v1",
88
+ ])("returns a closed-vocabulary value for %s", (baseUrl) => {
89
+ const result = classifyModelHost(baseUrl, "openai");
90
+ expect(MODEL_HOST_CLASSES).toContain(result);
91
+ // The customer's resource name must never reach telemetry.
92
+ expect(result).not.toContain("myresource");
93
+ expect(result).not.toContain("acme");
94
+ });
95
+
96
+ it("classifies an unparseable base URL as other, not unknown", () => {
97
+ // `unknown` means "we could not observe a host". A malformed string
98
+ // means we did observe one and failed to read it. Those differ.
99
+ expect(classifyModelHost("not a url at all", "openai")).toBe("other");
100
+ });
101
+ });
102
+
103
+ describe("normalization", () => {
104
+ it("ignores case and trailing whitespace", () => {
105
+ expect(
106
+ classifyModelHost(" HTTPS://MyResource.OpenAI.Azure.COM/openai/v1 "),
107
+ ).toBe("azure");
108
+ });
109
+
110
+ it("ignores port, path and query", () => {
111
+ expect(
112
+ classifyModelHost("https://api.openai.com:443/v1/chat?x=1#frag"),
113
+ ).toBe("openai");
114
+ });
115
+
116
+ it("does not match a lookalike suffix", () => {
117
+ // `evil-openai.azure.com.attacker.example` must not read as azure.
118
+ expect(
119
+ classifyModelHost("https://myresource.openai.azure.com.attacker.test/"),
120
+ ).toBe("other");
121
+ // A bare substring is not a suffix match either.
122
+ expect(classifyModelHost("https://notapi.openai.com.example/")).toBe(
123
+ "other",
124
+ );
125
+ });
126
+ });
127
+
128
+ describe("the vocabulary is closed", () => {
129
+ it("exposes unknown and other as members", () => {
130
+ expect(MODEL_HOST_CLASSES).toContain("unknown");
131
+ expect(MODEL_HOST_CLASSES).toContain("other");
132
+ });
133
+
134
+ it("has no duplicate members", () => {
135
+ expect(new Set(MODEL_HOST_CLASSES).size).toBe(MODEL_HOST_CLASSES.length);
136
+ });
137
+
138
+ it("accepts every member as a provider default", () => {
139
+ for (const member of MODEL_HOST_CLASSES) {
140
+ const value: ModelHostClass = classifyModelHost(undefined, member);
141
+ expect(value).toBe(member);
142
+ }
143
+ });
144
+ });
145
+ });