@providerkit/core 0.29.1 → 0.31.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.
- package/README.md +58 -9
- package/THIRD_PARTY_NOTICES +144 -0
- package/dist/auth/chatgpt-models.js.map +1 -1
- package/dist/auth/oauth.d.ts.map +1 -1
- package/dist/auth/oauth.js.map +1 -1
- package/dist/capability.js.map +1 -1
- package/dist/context.d.ts +4 -3
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +19 -5
- package/dist/context.js.map +1 -1
- package/dist/decisions.js.map +1 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +29 -2
- package/dist/errors.js.map +1 -1
- package/dist/fallback.d.ts +3 -0
- package/dist/fallback.d.ts.map +1 -1
- package/dist/fallback.js +9 -5
- package/dist/fallback.js.map +1 -1
- package/dist/gate.js.map +1 -1
- package/dist/hosted/anthropic.d.ts +30 -0
- package/dist/hosted/anthropic.d.ts.map +1 -0
- package/dist/hosted/anthropic.js +465 -0
- package/dist/hosted/anthropic.js.map +1 -0
- package/dist/hosted/gemini.d.ts +22 -0
- package/dist/hosted/gemini.d.ts.map +1 -0
- package/dist/hosted/gemini.js +440 -0
- package/dist/hosted/gemini.js.map +1 -0
- package/dist/hosted/openai.d.ts +33 -0
- package/dist/hosted/openai.d.ts.map +1 -0
- package/dist/hosted/openai.js +107 -0
- package/dist/hosted/openai.js.map +1 -0
- package/dist/hosted/responses.d.ts +28 -0
- package/dist/hosted/responses.d.ts.map +1 -0
- package/dist/hosted/responses.js +358 -0
- package/dist/hosted/responses.js.map +1 -0
- package/dist/hosted/shared.d.ts +107 -0
- package/dist/hosted/shared.d.ts.map +1 -0
- package/dist/hosted/shared.js +264 -0
- package/dist/hosted/shared.js.map +1 -0
- package/dist/hosted/types.d.ts +191 -0
- package/dist/hosted/types.d.ts.map +1 -0
- package/dist/hosted/types.js +10 -0
- package/dist/hosted/types.js.map +1 -0
- package/dist/hosted.d.ts +33 -0
- package/dist/hosted.d.ts.map +1 -0
- package/dist/hosted.js +61 -0
- package/dist/hosted.js.map +1 -0
- package/dist/index.d.ts +8 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -7
- package/dist/index.js.map +1 -1
- package/dist/key-pool.d.ts.map +1 -1
- package/dist/key-pool.js.map +1 -1
- package/dist/presets.d.ts +36 -5
- package/dist/presets.d.ts.map +1 -1
- package/dist/presets.js +32 -8
- package/dist/presets.js.map +1 -1
- package/dist/providers/anthropic.d.ts +75 -1
- package/dist/providers/anthropic.d.ts.map +1 -1
- package/dist/providers/anthropic.js +207 -135
- package/dist/providers/anthropic.js.map +1 -1
- package/dist/providers/deepgram-transcription.d.ts +24 -0
- package/dist/providers/deepgram-transcription.d.ts.map +1 -0
- package/dist/providers/deepgram-transcription.js +84 -0
- package/dist/providers/deepgram-transcription.js.map +1 -0
- package/dist/providers/factory.d.ts +10 -0
- package/dist/providers/factory.d.ts.map +1 -1
- package/dist/providers/factory.js +31 -23
- package/dist/providers/factory.js.map +1 -1
- package/dist/providers/gemini.d.ts +123 -1
- package/dist/providers/gemini.d.ts.map +1 -1
- package/dist/providers/gemini.js +114 -54
- package/dist/providers/gemini.js.map +1 -1
- package/dist/providers/hosted-codecs.d.ts +10 -0
- package/dist/providers/hosted-codecs.d.ts.map +1 -0
- package/dist/providers/hosted-codecs.js +8 -0
- package/dist/providers/hosted-codecs.js.map +1 -0
- package/dist/providers/openai-transcription.d.ts +21 -0
- package/dist/providers/openai-transcription.d.ts.map +1 -0
- package/dist/providers/openai-transcription.js +144 -0
- package/dist/providers/openai-transcription.js.map +1 -0
- package/dist/providers/openai.d.ts +69 -0
- package/dist/providers/openai.d.ts.map +1 -1
- package/dist/providers/openai.js +38 -14
- package/dist/providers/openai.js.map +1 -1
- package/dist/providers/responses.d.ts +123 -0
- package/dist/providers/responses.d.ts.map +1 -1
- package/dist/providers/responses.js +57 -22
- package/dist/providers/responses.js.map +1 -1
- package/dist/providers/speech-factory.js.map +1 -1
- package/dist/providers/transcription-factory.d.ts +30 -0
- package/dist/providers/transcription-factory.d.ts.map +1 -0
- package/dist/providers/transcription-factory.js +38 -0
- package/dist/providers/transcription-factory.js.map +1 -0
- package/dist/registry.d.ts +3 -0
- package/dist/registry.d.ts.map +1 -1
- package/dist/registry.js +8 -4
- package/dist/registry.js.map +1 -1
- package/dist/retry.js.map +1 -1
- package/dist/speech-core.d.ts +2 -17
- package/dist/speech-core.d.ts.map +1 -1
- package/dist/speech-core.js +10 -50
- package/dist/speech-core.js.map +1 -1
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js.map +1 -1
- package/dist/transcription-core.d.ts +146 -0
- package/dist/transcription-core.d.ts.map +1 -0
- package/dist/transcription-core.js +193 -0
- package/dist/transcription-core.js.map +1 -0
- package/dist/transcription.d.ts +7 -0
- package/dist/transcription.d.ts.map +1 -0
- package/dist/transcription.js +12 -0
- package/dist/transcription.js.map +1 -0
- package/dist/transport.d.ts +26 -0
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +57 -2
- package/dist/transport.js.map +1 -1
- package/dist/turn.d.ts +10 -1
- package/dist/turn.d.ts.map +1 -1
- package/dist/turn.js +53 -1
- package/dist/turn.js.map +1 -1
- package/dist/types.d.ts +51 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/usage.d.ts +10 -1
- package/dist/usage.d.ts.map +1 -1
- package/dist/usage.js +40 -2
- package/dist/usage.js.map +1 -1
- package/dist/watchdog.d.ts +6 -0
- package/dist/watchdog.d.ts.map +1 -1
- package/dist/watchdog.js +10 -2
- package/dist/watchdog.js.map +1 -1
- package/package.json +14 -5
- package/src/context.ts +21 -5
- package/src/errors.ts +35 -2
- package/src/fallback.ts +21 -6
- package/src/hosted/anthropic.ts +512 -0
- package/src/hosted/gemini.ts +510 -0
- package/src/hosted/openai.ts +137 -0
- package/src/hosted/responses.ts +420 -0
- package/src/hosted/shared.ts +341 -0
- package/src/hosted/types.ts +214 -0
- package/src/hosted.ts +101 -0
- package/src/index.ts +64 -7
- package/src/presets.ts +54 -8
- package/src/providers/anthropic.ts +252 -143
- package/src/providers/deepgram-transcription.ts +109 -0
- package/src/providers/factory.ts +127 -82
- package/src/providers/gemini.ts +184 -60
- package/src/providers/hosted-codecs.ts +29 -0
- package/src/providers/openai-transcription.ts +177 -0
- package/src/providers/openai.ts +52 -15
- package/src/providers/responses.ts +93 -24
- package/src/providers/transcription-factory.ts +68 -0
- package/src/registry.ts +14 -4
- package/src/speech-core.ts +9 -47
- package/src/transcription-core.ts +345 -0
- package/src/transcription.ts +24 -0
- package/src/transport.ts +77 -3
- package/src/turn.ts +55 -1
- package/src/types.ts +62 -1
- package/src/usage.ts +32 -2
- package/src/watchdog.ts +12 -2
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
// Provider-hosted tools: web search, web fetch, code execution, file search and
|
|
2
|
+
// image generation that the model's VENDOR runs, inside its own turn. The seam
|
|
3
|
+
// asks for them in one neutral shape (`StreamOptions.hostedTools`), each adapter
|
|
4
|
+
// sends them in its vendor's dialect or refuses them before any request goes
|
|
5
|
+
// out, and what they did comes back as records and citations on the turn. They
|
|
6
|
+
// are never function calls: the loop has nothing to run and nothing to answer.
|
|
7
|
+
//
|
|
8
|
+
// Refused, never dropped. A gateway that does not know a hosted tool can ignore
|
|
9
|
+
// it and answer unsearched, on the happy path, where nothing retries and
|
|
10
|
+
// nothing logs: the failure `fileRefused` exists for, one capability over. A
|
|
11
|
+
// restriction a wire can't apply (a domain filter, a use cap) is refused too,
|
|
12
|
+
// because sending the tool without it widens what the vendor does for the
|
|
13
|
+
// caller. `optional` is the way to decline that: it drops the WHOLE tool, which
|
|
14
|
+
// narrows what happens instead.
|
|
15
|
+
//
|
|
16
|
+
// The vendor's own record of the turn (`HostedItems`) is opaque and tagged with
|
|
17
|
+
// the provider that made it, like `reasoningItems`: only that provider replays
|
|
18
|
+
// it, and only while it still fits the message it rides on.
|
|
19
|
+
import type {
|
|
20
|
+
HostedToolType,
|
|
21
|
+
HostedTool,
|
|
22
|
+
HostedWire,
|
|
23
|
+
HostedInput,
|
|
24
|
+
HostedCallDelta,
|
|
25
|
+
} from "./types.ts";
|
|
26
|
+
export * from "./types.ts";
|
|
27
|
+
import { ProviderError } from "../errors.ts";
|
|
28
|
+
import type { ChatMessage, StreamOptions, ToolCall } from "../types.ts";
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* A hosted tool the wire can't send. Refused, never dropped: see the module
|
|
32
|
+
* comment. `wire` names the adapter, because `provider` is often a gateway's id.
|
|
33
|
+
*/
|
|
34
|
+
export function hostedRefused(
|
|
35
|
+
provider: string,
|
|
36
|
+
wire: string,
|
|
37
|
+
tool: HostedToolType,
|
|
38
|
+
why: string,
|
|
39
|
+
): ProviderError {
|
|
40
|
+
return new ProviderError(
|
|
41
|
+
provider,
|
|
42
|
+
"invalid",
|
|
43
|
+
`${provider}: the ${wire} adapter can't send ${tool}: ${why}`,
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const FORCED =
|
|
48
|
+
'a forced toolChoice can\'t be combined with hosted tools, because each vendor reads it differently. Use toolChoice "auto", or leave the hosted tools off this call.';
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The hosted tools one request sends: each tool the caller asked for that this
|
|
52
|
+
* wire can send with every field it set. One it can't is refused with an
|
|
53
|
+
* `invalid` error before any request, unless it is `optional`, which drops it.
|
|
54
|
+
*
|
|
55
|
+
* `toolChoice: "none"` sends none, on every wire. A forced choice (`required`
|
|
56
|
+
* or a named tool) with hosted tools is refused: Anthropic's `any` and
|
|
57
|
+
* Responses' `required` can be met by a vendor tool, Gemini's `ANY` cannot, so
|
|
58
|
+
* the pair has no one meaning. A type listed twice is refused everywhere.
|
|
59
|
+
*
|
|
60
|
+
* Ported from PydanticAI (MIT, Pydantic Services Inc.): the refusal rule and
|
|
61
|
+
* `optional`, models/__init__.py:4080-4130 and native_tools/__init__.py:155-207.
|
|
62
|
+
*/
|
|
63
|
+
export function planHostedTools(
|
|
64
|
+
provider: string,
|
|
65
|
+
wire: HostedWire,
|
|
66
|
+
opts: Pick<StreamOptions, "hostedTools" | "toolChoice">,
|
|
67
|
+
): HostedTool[] {
|
|
68
|
+
const asked = opts.hostedTools ?? [];
|
|
69
|
+
const seen = new Set<HostedToolType>();
|
|
70
|
+
for (const tool of asked) {
|
|
71
|
+
if (seen.has(tool.type)) {
|
|
72
|
+
throw hostedRefused(
|
|
73
|
+
provider,
|
|
74
|
+
wire.name,
|
|
75
|
+
tool.type,
|
|
76
|
+
"it is listed twice. List each type once.",
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
seen.add(tool.type);
|
|
80
|
+
}
|
|
81
|
+
if (opts.toolChoice === "none") return [];
|
|
82
|
+
const forced = opts.toolChoice === "required" || typeof opts.toolChoice === "object";
|
|
83
|
+
return asked.filter((tool) => {
|
|
84
|
+
const why = forced ? FORCED : unsendable(tool, wire);
|
|
85
|
+
if (why === undefined) return true;
|
|
86
|
+
if (tool.optional) return false;
|
|
87
|
+
throw hostedRefused(provider, wire.name, tool.type, why);
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function unsendable(tool: HostedTool, wire: HostedWire): string | undefined {
|
|
92
|
+
if (!wire.serves.includes(tool.type)) {
|
|
93
|
+
return (
|
|
94
|
+
"this endpoint doesn't run it. Send the request to one that does, list the type in " +
|
|
95
|
+
"servesHostedTools if this endpoint runs it, or mark the tool optional."
|
|
96
|
+
);
|
|
97
|
+
}
|
|
98
|
+
const applied = wire.fields[tool.type] ?? [];
|
|
99
|
+
const unapplied = Object.entries(tool)
|
|
100
|
+
.filter(([key, value]) => key !== "type" && key !== "optional" && value !== undefined)
|
|
101
|
+
.map(([key]) => key)
|
|
102
|
+
.filter((key) => !applied.includes(key));
|
|
103
|
+
if (unapplied.length > 0) {
|
|
104
|
+
const fields = unapplied.join(" and ");
|
|
105
|
+
return (
|
|
106
|
+
`this wire can't apply ${fields}, so the tool would run without ${fields}. ` +
|
|
107
|
+
`Remove ${fields}, or mark the tool optional.`
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
return wire.refuse?.(tool);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** The types an endpoint runs when its config doesn't say: the vendor's own API
|
|
114
|
+
* host runs its documented set, and every other host none. A gateway that
|
|
115
|
+
* ignores an unknown tool answers unsearched and says nothing, so a host runs
|
|
116
|
+
* hosted tools only once someone has measured it (`servesHostedTools`). */
|
|
117
|
+
export function servedAt(
|
|
118
|
+
baseUrl: string,
|
|
119
|
+
host: string,
|
|
120
|
+
types: readonly HostedToolType[],
|
|
121
|
+
): readonly HostedToolType[] {
|
|
122
|
+
try {
|
|
123
|
+
return new URL(baseUrl).hostname === host ? types : [];
|
|
124
|
+
} catch {
|
|
125
|
+
return [];
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** A search's input: one query as `query`, several as `queries`, so a reader
|
|
130
|
+
* that shows one string finds it in the same place on every wire. */
|
|
131
|
+
export function queryInput(queries: readonly (string | undefined | null)[]): HostedInput {
|
|
132
|
+
const stated = queries.filter((query): query is string => typeof query === "string" && !!query);
|
|
133
|
+
if (stated.length === 0) return {};
|
|
134
|
+
return stated.length === 1 ? { query: stated[0] } : { queries: stated };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The hosted calls one stream opened, keyed by the vendor's id, so a result
|
|
139
|
+
* finds its call and the end of the turn can settle the ones that never got
|
|
140
|
+
* one. It also counts what the stream showed, per type, for
|
|
141
|
+
* `TokenUsage.hostedCalls` on a wire that does not state its own counts.
|
|
142
|
+
*/
|
|
143
|
+
export class HostedRecorder {
|
|
144
|
+
private next = 0;
|
|
145
|
+
private readonly open = new Map<string, number>();
|
|
146
|
+
private readonly counts = new Map<HostedToolType, number>();
|
|
147
|
+
|
|
148
|
+
/** A call the vendor started. One with no id of its own gets `hosted_{index}`,
|
|
149
|
+
* which depends on nothing but its position (invariant 14). */
|
|
150
|
+
start(
|
|
151
|
+
id: string | undefined,
|
|
152
|
+
type: HostedToolType,
|
|
153
|
+
at: number,
|
|
154
|
+
input?: HostedInput,
|
|
155
|
+
): HostedCallDelta & { id: string } {
|
|
156
|
+
const index = this.next++;
|
|
157
|
+
const key = id || `hosted_${index}`;
|
|
158
|
+
this.open.set(key, index);
|
|
159
|
+
this.counts.set(type, (this.counts.get(type) ?? 0) + 1);
|
|
160
|
+
return { index, id: key, type, status: "running", at, ...(input ? { input } : {}) };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** A call the vendor reports only once it is over (Gemini's grounding, a
|
|
164
|
+
* backend that sends only the finished item), in one delta. */
|
|
165
|
+
whole(
|
|
166
|
+
id: string | undefined,
|
|
167
|
+
type: HostedToolType,
|
|
168
|
+
at: number,
|
|
169
|
+
delta: Omit<HostedCallDelta, "index" | "id" | "type" | "at">,
|
|
170
|
+
): HostedCallDelta {
|
|
171
|
+
const started = this.start(id, type, at);
|
|
172
|
+
this.open.delete(started.id);
|
|
173
|
+
return { ...started, ...delta };
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** The seam index of a call still open, by the vendor's id. */
|
|
177
|
+
indexOf(id: string | undefined): number | undefined {
|
|
178
|
+
return id === undefined ? undefined : this.open.get(id);
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** A call the vendor finished, or undefined for an id it never opened. */
|
|
182
|
+
end(id: string | undefined, delta: Omit<HostedCallDelta, "index">): HostedCallDelta | undefined {
|
|
183
|
+
if (id === undefined) return undefined;
|
|
184
|
+
const index = this.open.get(id);
|
|
185
|
+
if (index === undefined) return undefined;
|
|
186
|
+
this.open.delete(id);
|
|
187
|
+
return { index, ...delta };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** The ids still open. */
|
|
191
|
+
unsettled(): ReadonlySet<string> {
|
|
192
|
+
return new Set(this.open.keys());
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** Every call still open at the end of the turn, failed: the vendor never
|
|
196
|
+
* said how it went, so nothing it returned can be shown or replayed. */
|
|
197
|
+
settle(): HostedCallDelta[] {
|
|
198
|
+
const failed = [...this.open.values()].map((index): HostedCallDelta => ({
|
|
199
|
+
index,
|
|
200
|
+
status: "failed",
|
|
201
|
+
error: "no_result",
|
|
202
|
+
}));
|
|
203
|
+
this.open.clear();
|
|
204
|
+
return failed;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** The calls the stream showed, by type, or undefined when it showed none. */
|
|
208
|
+
shown(): Partial<Record<HostedToolType, number>> | undefined {
|
|
209
|
+
return this.counts.size > 0 ? Object.fromEntries(this.counts) : undefined;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** The counts a usage record carries, with the types at zero left out, or
|
|
214
|
+
* undefined when every type is. A turn that ran nothing keeps its usage
|
|
215
|
+
* exactly as it was before hosted tools existed. */
|
|
216
|
+
export function hostedCounts(
|
|
217
|
+
...counts: (Partial<Record<HostedToolType, number>> | undefined)[]
|
|
218
|
+
): Partial<Record<HostedToolType, number>> | undefined {
|
|
219
|
+
const merged: Partial<Record<HostedToolType, number>> = {};
|
|
220
|
+
for (const count of counts) Object.assign(merged, count);
|
|
221
|
+
const kept = Object.entries(merged).filter(([, count]) => (count ?? 0) > 0);
|
|
222
|
+
return kept.length > 0 ? Object.fromEntries(kept) : undefined;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
type AssistantMessage = Extract<ChatMessage, { role: "assistant" }>;
|
|
226
|
+
|
|
227
|
+
/** One recorded item with its placeholder filled back in. */
|
|
228
|
+
export type ReplayedItem =
|
|
229
|
+
| { text: string; slot: Record<string, unknown> }
|
|
230
|
+
| { call: ToolCall }
|
|
231
|
+
| { item: unknown };
|
|
232
|
+
|
|
233
|
+
/** A JSON object off the wire, as opposed to an array, a scalar or null. */
|
|
234
|
+
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
235
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** `{ length }`: answer text, cut back out of `content` on replay. A vendor item
|
|
239
|
+
* always carries a `type` or a part key of its own, so a placeholder can't be
|
|
240
|
+
* mistaken for one. */
|
|
241
|
+
function textSlot(item: unknown): { slot: Record<string, unknown>; length: number } | undefined {
|
|
242
|
+
if (!isRecord(item) || "type" in item) return undefined;
|
|
243
|
+
const { length } = item;
|
|
244
|
+
return typeof length === "number" ? { slot: item, length } : undefined;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** `{ call: i }`: the message's i-th tool call, whatever its id is now. */
|
|
248
|
+
function callSlot(item: unknown): number | undefined {
|
|
249
|
+
if (!isRecord(item) || "type" in item) return undefined;
|
|
250
|
+
const { call } = item;
|
|
251
|
+
return typeof call === "number" ? call : undefined;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* The hosted items a message replays to `provider`, placeholders filled back
|
|
256
|
+
* in, or undefined when it replays none: another provider made them, or the
|
|
257
|
+
* message no longer matches them. Matching means the recorded text lengths sum
|
|
258
|
+
* to `content.length` and every call placeholder names a distinct call the
|
|
259
|
+
* message still has. An edited answer fails that and goes back as plain text,
|
|
260
|
+
* because a citation replayed over edited text vouches for words its source
|
|
261
|
+
* never backed.
|
|
262
|
+
*
|
|
263
|
+
* ponytail: an edit that keeps the length passes. PydanticAI and TanStack use
|
|
264
|
+
* the same length test (anthropic/_citations.py:202-211, responses-text.ts:172-212);
|
|
265
|
+
* the upgrade is a hash of the text in each placeholder.
|
|
266
|
+
*/
|
|
267
|
+
export function hostedReplay(
|
|
268
|
+
message: AssistantMessage,
|
|
269
|
+
provider: string,
|
|
270
|
+
): ReplayedItem[] | undefined {
|
|
271
|
+
const recorded = message.hostedItems;
|
|
272
|
+
if (!recorded || recorded.provider !== provider) return undefined;
|
|
273
|
+
const calls = message.toolCalls ?? [];
|
|
274
|
+
let length = 0;
|
|
275
|
+
const paired = new Set<number>();
|
|
276
|
+
for (const item of recorded.items) {
|
|
277
|
+
const slot = textSlot(item);
|
|
278
|
+
if (slot) length += slot.length;
|
|
279
|
+
const call = callSlot(item);
|
|
280
|
+
if (call === undefined) continue;
|
|
281
|
+
if (!Number.isInteger(call) || call < 0 || call >= calls.length || paired.has(call)) {
|
|
282
|
+
return undefined;
|
|
283
|
+
}
|
|
284
|
+
paired.add(call);
|
|
285
|
+
}
|
|
286
|
+
if (length !== message.content.length || paired.size !== calls.length) return undefined;
|
|
287
|
+
|
|
288
|
+
let offset = 0;
|
|
289
|
+
return recorded.items.map((item): ReplayedItem => {
|
|
290
|
+
const text = textSlot(item);
|
|
291
|
+
if (text) {
|
|
292
|
+
offset += text.length;
|
|
293
|
+
return { text: message.content.slice(offset - text.length, offset), slot: text.slot };
|
|
294
|
+
}
|
|
295
|
+
const call = callSlot(item);
|
|
296
|
+
return call === undefined ? { item } : { call: calls[call]! };
|
|
297
|
+
});
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* A UTF-8 byte offset into `text` as a JS string index, or undefined when it
|
|
302
|
+
* falls inside a character or past the end. Gemini counts its grounding
|
|
303
|
+
* segments in bytes; a JS string counts UTF-16 units, so the two part at the
|
|
304
|
+
* first character outside ASCII.
|
|
305
|
+
*
|
|
306
|
+
* Ported from PydanticAI (MIT, Pydantic Services Inc.), models/google.py:2347-2405.
|
|
307
|
+
*/
|
|
308
|
+
export function utf8Index(text: string, bytes: number): number | undefined {
|
|
309
|
+
if (!Number.isInteger(bytes) || bytes < 0) return undefined;
|
|
310
|
+
let seen = 0;
|
|
311
|
+
let index = 0;
|
|
312
|
+
for (const char of text) {
|
|
313
|
+
if (seen >= bytes) break;
|
|
314
|
+
seen += utf8Length(char.codePointAt(0) ?? 0);
|
|
315
|
+
index += char.length;
|
|
316
|
+
}
|
|
317
|
+
return seen === bytes ? index : undefined;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** How many bytes UTF-8 spends on one code point. */
|
|
321
|
+
function utf8Length(point: number): number {
|
|
322
|
+
if (point < 0x80) return 1;
|
|
323
|
+
if (point < 0x800) return 2;
|
|
324
|
+
if (point < 0x10000) return 3;
|
|
325
|
+
return 4;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** A code point offset into `text` as a JS string index, or undefined past the
|
|
329
|
+
* end. OpenAI's annotation offsets count code points, which differ from JS
|
|
330
|
+
* indices at the first emoji or other character outside the BMP. */
|
|
331
|
+
export function codePointIndex(text: string, points: number): number | undefined {
|
|
332
|
+
if (!Number.isInteger(points) || points < 0) return undefined;
|
|
333
|
+
let seen = 0;
|
|
334
|
+
let index = 0;
|
|
335
|
+
for (const char of text) {
|
|
336
|
+
if (seen === points) return index;
|
|
337
|
+
seen += 1;
|
|
338
|
+
index += char.length;
|
|
339
|
+
}
|
|
340
|
+
return seen === points ? index : undefined;
|
|
341
|
+
}
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
import type { ImagePart } from "../types.ts";
|
|
2
|
+
|
|
3
|
+
/** Every hosted tool type, least to most invasive. The union derives from the
|
|
4
|
+
* array, so a runtime check and the type can never drift apart. */
|
|
5
|
+
export const HOSTED_TOOL_TYPES = [
|
|
6
|
+
"web_search",
|
|
7
|
+
"web_fetch",
|
|
8
|
+
"code_execution",
|
|
9
|
+
"file_search",
|
|
10
|
+
"image_generation",
|
|
11
|
+
] as const;
|
|
12
|
+
export type HostedToolType = (typeof HOSTED_TOOL_TYPES)[number];
|
|
13
|
+
|
|
14
|
+
/** Roughly where the person asking is, so a search can rank local results. */
|
|
15
|
+
export interface UserLocation {
|
|
16
|
+
city?: string;
|
|
17
|
+
region?: string;
|
|
18
|
+
/** Two-letter ISO country code, such as `US`. */
|
|
19
|
+
country?: string;
|
|
20
|
+
/** IANA time zone, such as `America/New_York`. */
|
|
21
|
+
timezone?: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* A tool the model vendor runs inside its own turn.
|
|
26
|
+
*
|
|
27
|
+
* Which wire runs which type, and which fields each applies, is in the hosted
|
|
28
|
+
* tools guide. A type the endpoint doesn't run, or a field the wire can't
|
|
29
|
+
* apply, is refused with an `invalid` error before any request goes out. Set
|
|
30
|
+
* `optional` to drop the tool there instead.
|
|
31
|
+
*/
|
|
32
|
+
export type HostedTool = {
|
|
33
|
+
/**
|
|
34
|
+
* Drop this tool, rather than refuse the request, where the endpoint can't
|
|
35
|
+
* run it or can't apply one of its fields. The whole tool goes, never one
|
|
36
|
+
* field: sending it without a domain filter or a use cap would widen what the
|
|
37
|
+
* vendor does, and leaving it out only narrows it.
|
|
38
|
+
*/
|
|
39
|
+
optional?: boolean;
|
|
40
|
+
} & (
|
|
41
|
+
| {
|
|
42
|
+
type: "web_search";
|
|
43
|
+
allowedDomains?: readonly string[];
|
|
44
|
+
blockedDomains?: readonly string[];
|
|
45
|
+
/** At most this many searches in one turn. */
|
|
46
|
+
maxUses?: number;
|
|
47
|
+
userLocation?: UserLocation;
|
|
48
|
+
}
|
|
49
|
+
| {
|
|
50
|
+
type: "web_fetch";
|
|
51
|
+
allowedDomains?: readonly string[];
|
|
52
|
+
blockedDomains?: readonly string[];
|
|
53
|
+
/** At most this many fetches in one turn. */
|
|
54
|
+
maxUses?: number;
|
|
55
|
+
/** Cut each fetched page to about this many tokens. */
|
|
56
|
+
maxContentTokens?: number;
|
|
57
|
+
}
|
|
58
|
+
| {
|
|
59
|
+
type: "code_execution";
|
|
60
|
+
/** Files the code may read, by the vendor's file id. */
|
|
61
|
+
fileIds?: readonly string[];
|
|
62
|
+
}
|
|
63
|
+
| {
|
|
64
|
+
type: "file_search";
|
|
65
|
+
/** The vendor's vector stores (Responses) or file search stores (Gemini). */
|
|
66
|
+
storeIds: readonly string[];
|
|
67
|
+
maxResults?: number;
|
|
68
|
+
}
|
|
69
|
+
| {
|
|
70
|
+
type: "image_generation";
|
|
71
|
+
size?: "auto" | "1024x1024" | "1024x1536" | "1536x1024";
|
|
72
|
+
quality?: "auto" | "low" | "medium" | "high";
|
|
73
|
+
format?: "png" | "jpeg" | "webp";
|
|
74
|
+
background?: "auto" | "opaque" | "transparent";
|
|
75
|
+
}
|
|
76
|
+
);
|
|
77
|
+
|
|
78
|
+
/** What a hosted call read: a web page, or a file in a store or a container. */
|
|
79
|
+
export interface Source {
|
|
80
|
+
type: "url" | "file";
|
|
81
|
+
url?: string;
|
|
82
|
+
title?: string;
|
|
83
|
+
fileId?: string;
|
|
84
|
+
containerId?: string;
|
|
85
|
+
/** The passage the vendor quoted from it, when it quoted one. */
|
|
86
|
+
excerpt?: string;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* A source tied to the answer.
|
|
91
|
+
*
|
|
92
|
+
* `start` and `end` are JS string indices into the turn's `content`, converted
|
|
93
|
+
* from whatever the vendor counts in (UTF-8 bytes on Gemini, code points on
|
|
94
|
+
* OpenAI) and checked against the text. A span that doesn't check out is left
|
|
95
|
+
* off, never guessed: the citation still names its source. `start` equal to
|
|
96
|
+
* `end` is a point.
|
|
97
|
+
*
|
|
98
|
+
* `anchor` says what the span covers. `claim` is text the source backs:
|
|
99
|
+
* Anthropic cites whole text blocks, Gemini sentences. `marker` is a link the
|
|
100
|
+
* model wrote into the answer, which is what OpenAI's offsets select.
|
|
101
|
+
*/
|
|
102
|
+
export interface Citation {
|
|
103
|
+
source: Source;
|
|
104
|
+
start?: number;
|
|
105
|
+
end?: number;
|
|
106
|
+
anchor?: "claim" | "marker";
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** What a hosted call was asked to do, in the fields its type uses. */
|
|
110
|
+
export interface HostedInput {
|
|
111
|
+
/** A search's query, when it ran one. */
|
|
112
|
+
query?: string;
|
|
113
|
+
/** A search's queries, when it ran several. */
|
|
114
|
+
queries?: string[];
|
|
115
|
+
/** The page a fetch read. */
|
|
116
|
+
url?: string;
|
|
117
|
+
/** The code a run executed. */
|
|
118
|
+
code?: string;
|
|
119
|
+
language?: string;
|
|
120
|
+
/** The file a code run's editor touched. */
|
|
121
|
+
path?: string;
|
|
122
|
+
/** What an image generation drew, in the vendor's words. */
|
|
123
|
+
prompt?: string;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** A file a hosted call made. Downloading it needs the vendor's own files or
|
|
127
|
+
* containers API, which this package does not wrap, and containers expire. */
|
|
128
|
+
export interface HostedFile {
|
|
129
|
+
id?: string;
|
|
130
|
+
url?: string;
|
|
131
|
+
name?: string;
|
|
132
|
+
containerId?: string;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export interface HostedOutput {
|
|
136
|
+
sources?: Source[];
|
|
137
|
+
stdout?: string;
|
|
138
|
+
stderr?: string;
|
|
139
|
+
exitCode?: number;
|
|
140
|
+
/** Images the call made, as base64. A generated image is an answer. */
|
|
141
|
+
images?: ImagePart[];
|
|
142
|
+
files?: HostedFile[];
|
|
143
|
+
/** Gemini's search suggestions, as the HTML Google sends for them. */
|
|
144
|
+
searchSuggestions?: string;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* One hosted run, assembled. Display data, with the sensitivity of `content`:
|
|
149
|
+
* an excerpt can quote the caller's own documents.
|
|
150
|
+
*
|
|
151
|
+
* A failed call is data (`status: "failed"`, `error` the vendor's code, such as
|
|
152
|
+
* `max_uses_exceeded`) and the turn goes on, as a failing function tool's does
|
|
153
|
+
* (invariant 7). A call the vendor never finished fails with `no_result`.
|
|
154
|
+
*/
|
|
155
|
+
export interface HostedCall {
|
|
156
|
+
id: string;
|
|
157
|
+
type: HostedToolType;
|
|
158
|
+
status: "running" | "completed" | "failed";
|
|
159
|
+
input?: HostedInput;
|
|
160
|
+
output?: HostedOutput;
|
|
161
|
+
error?: string;
|
|
162
|
+
/** Where in `content` the call ran: the text's length when it started. */
|
|
163
|
+
at: number;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* A fragment of a hosted call, assembled by `index` (`collectTurn` does it).
|
|
168
|
+
* Each field takes the last value stated, `codeDelta` appends to `input.code`,
|
|
169
|
+
* and `output` is always stated whole.
|
|
170
|
+
*/
|
|
171
|
+
export interface HostedCallDelta {
|
|
172
|
+
index: number;
|
|
173
|
+
id?: string;
|
|
174
|
+
type?: HostedToolType;
|
|
175
|
+
status?: HostedCall["status"];
|
|
176
|
+
input?: HostedInput;
|
|
177
|
+
codeDelta?: string;
|
|
178
|
+
output?: HostedOutput;
|
|
179
|
+
error?: string;
|
|
180
|
+
at?: number;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* The vendor's own record of a hosted turn, in the order it sent it: search
|
|
185
|
+
* results, fetched pages, code output. Opaque, provider-owned, and replayed
|
|
186
|
+
* only to the provider that made it, like `reasoningItems`. Never echo it to a
|
|
187
|
+
* browser, and drop it from history a browser hands back.
|
|
188
|
+
*
|
|
189
|
+
* Answer text is stored as `{ length }` and function calls as `{ call: i }`,
|
|
190
|
+
* so replay cuts the text from `content` and pairs the calls that
|
|
191
|
+
* `repairHistory` may have renamed. When the lengths no longer sum to
|
|
192
|
+
* `content.length`, or the calls no longer match, the message goes back as
|
|
193
|
+
* plain text instead.
|
|
194
|
+
*/
|
|
195
|
+
export interface HostedItems {
|
|
196
|
+
provider: string;
|
|
197
|
+
items: unknown[];
|
|
198
|
+
/** The code execution container the turn ran in, which the next request in
|
|
199
|
+
* the same turn has to name. */
|
|
200
|
+
container?: string;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** What one adapter, at one endpoint, can send. */
|
|
204
|
+
export interface HostedWire {
|
|
205
|
+
/** The adapter's name in a refusal: `Anthropic`, `Responses`, `Gemini`, `OpenAI chat`. */
|
|
206
|
+
name: string;
|
|
207
|
+
/** The types this endpoint runs. */
|
|
208
|
+
serves: readonly HostedToolType[];
|
|
209
|
+
/** The fields this wire applies, for each type it sends. Any other field set
|
|
210
|
+
* on a tool is one the wire would silently leave out. */
|
|
211
|
+
fields: Partial<Record<HostedToolType, readonly string[]>>;
|
|
212
|
+
/** This wire's own reason to refuse a tool, beyond the two above. */
|
|
213
|
+
refuse?: (tool: HostedTool) => string | undefined;
|
|
214
|
+
}
|
package/src/hosted.ts
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
// Explicit opt-in: plain chat imports no hosted encoder or parser.
|
|
2
|
+
import { anthropicHosted } from "./hosted/anthropic.ts";
|
|
3
|
+
import { geminiHosted } from "./hosted/gemini.ts";
|
|
4
|
+
import { openaiHosted } from "./hosted/openai.ts";
|
|
5
|
+
import { responsesHosted } from "./hosted/responses.ts";
|
|
6
|
+
import {
|
|
7
|
+
anthropicMessages,
|
|
8
|
+
anthropicProvider,
|
|
9
|
+
type AnthropicConfig,
|
|
10
|
+
} from "./providers/anthropic.ts";
|
|
11
|
+
import { geminiContents, geminiProvider, type GeminiConfig } from "./providers/gemini.ts";
|
|
12
|
+
import { openaiProvider, type OpenAIConfig } from "./providers/openai.ts";
|
|
13
|
+
import { responsesProvider, type ResponsesConfig } from "./providers/responses.ts";
|
|
14
|
+
import {
|
|
15
|
+
presetProvider,
|
|
16
|
+
buildPresetAdapter,
|
|
17
|
+
type PresetProviderConfig,
|
|
18
|
+
type PresetAdapterConfig,
|
|
19
|
+
} from "./providers/factory.ts";
|
|
20
|
+
import { configuredFallbacks, type ProviderFallbackConfig } from "./fallback.ts";
|
|
21
|
+
import type { HostedCodecs } from "./providers/hosted-codecs.ts";
|
|
22
|
+
import type { ProviderPresetId } from "./presets.ts";
|
|
23
|
+
import type { ChatMessage, Provider } from "./types.ts";
|
|
24
|
+
import { providerRegistry, type Registry, type RegistryOptions } from "./registry.ts";
|
|
25
|
+
|
|
26
|
+
export * from "./hosted/types.ts";
|
|
27
|
+
export { hostedRefused, planHostedTools } from "./hosted/shared.ts";
|
|
28
|
+
export type {
|
|
29
|
+
AnthropicConfig,
|
|
30
|
+
GeminiConfig,
|
|
31
|
+
OpenAIConfig,
|
|
32
|
+
ResponsesConfig,
|
|
33
|
+
PresetProviderConfig,
|
|
34
|
+
PresetAdapterConfig,
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
const codecs: HostedCodecs = {
|
|
38
|
+
anthropic: anthropicHosted,
|
|
39
|
+
gemini: geminiHosted,
|
|
40
|
+
openai: openaiHosted,
|
|
41
|
+
responses: responsesHosted,
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/** An Anthropic provider with hosted tools and paused-turn continuation. */
|
|
45
|
+
export function createAnthropicProvider(config: AnthropicConfig): Provider {
|
|
46
|
+
return anthropicProvider(config, codecs);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** A Gemini provider with built-in tools, grounding and replay. */
|
|
50
|
+
export function createGeminiProvider(config: GeminiConfig): Provider {
|
|
51
|
+
return geminiProvider(config, codecs);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** A Chat Completions provider with hosted search and citations. */
|
|
55
|
+
export function createOpenAIProvider(config: OpenAIConfig): Provider {
|
|
56
|
+
return openaiProvider(config, codecs);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** A Responses provider with hosted tools and generated images. */
|
|
60
|
+
export function createResponsesProvider(config: ResponsesConfig): Provider {
|
|
61
|
+
return responsesProvider(config, codecs);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** A preset provider whose model chain and preset fallbacks also opt in. */
|
|
65
|
+
export function createPresetProvider(id: ProviderPresetId, config: PresetProviderConfig): Provider {
|
|
66
|
+
return presetProvider(id, config, codecs);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** One bare preset adapter with hosted tools, without a pool or watchdog. */
|
|
70
|
+
export function presetAdapter(id: ProviderPresetId, config: PresetAdapterConfig): Provider {
|
|
71
|
+
return buildPresetAdapter(id, config, codecs);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Opt preset fallback specs in. Hand-built providers keep their own setup. */
|
|
75
|
+
export function withConfiguredFallbacks(
|
|
76
|
+
primary: Provider,
|
|
77
|
+
config?: ProviderFallbackConfig,
|
|
78
|
+
): Provider {
|
|
79
|
+
return configuredFallbacks(primary, config, codecs);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A registry whose connections, key rotation and token refresh keep the opt-in. */
|
|
83
|
+
export function createRegistry(options: RegistryOptions): Registry {
|
|
84
|
+
return providerRegistry(options, codecs);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Convert history with Anthropic's hosted replay records. */
|
|
88
|
+
export function toAnthropicMessages(
|
|
89
|
+
messages: readonly ChatMessage[],
|
|
90
|
+
provider = "anthropic",
|
|
91
|
+
): ReturnType<typeof anthropicMessages> {
|
|
92
|
+
return anthropicMessages(messages, provider, codecs.anthropic.replay);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Convert history with Gemini's hosted replay records. */
|
|
96
|
+
export function toGeminiContents(
|
|
97
|
+
messages: readonly ChatMessage[],
|
|
98
|
+
provider?: string,
|
|
99
|
+
): ReturnType<typeof geminiContents> {
|
|
100
|
+
return geminiContents(messages, provider, codecs.gemini.replay);
|
|
101
|
+
}
|