@meridian-flow/runtime 0.0.0-stage → 0.1.1
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/LICENSE +202 -0
- package/README.md +67 -2
- package/dist/gateway/adapters/anthropic/adapter.d.ts +9 -0
- package/dist/gateway/adapters/anthropic/adapter.js +52 -0
- package/dist/gateway/adapters/anthropic/request-map.d.ts +46 -0
- package/dist/gateway/adapters/anthropic/request-map.js +285 -0
- package/dist/gateway/adapters/anthropic/stream-collect.d.ts +67 -0
- package/dist/gateway/adapters/anthropic/stream-collect.js +295 -0
- package/dist/gateway/adapters/anthropic/tool-schema.d.ts +8 -0
- package/dist/gateway/adapters/anthropic/tool-schema.js +68 -0
- package/dist/gateway/adapters/credentials.d.ts +25 -0
- package/dist/gateway/adapters/credentials.js +118 -0
- package/dist/gateway/adapters/gemini/adapter.d.ts +10 -0
- package/dist/gateway/adapters/gemini/adapter.js +90 -0
- package/dist/gateway/adapters/gemini/request-map.d.ts +29 -0
- package/dist/gateway/adapters/gemini/request-map.js +178 -0
- package/dist/gateway/adapters/gemini/stream-collect.d.ts +29 -0
- package/dist/gateway/adapters/gemini/stream-collect.js +116 -0
- package/dist/gateway/adapters/mock/response.d.ts +11 -0
- package/dist/gateway/adapters/mock/response.js +160 -0
- package/dist/gateway/adapters/mock/samples.d.ts +8 -0
- package/dist/gateway/adapters/mock/samples.js +133 -0
- package/dist/gateway/adapters/mock/script-queue.d.ts +10 -0
- package/dist/gateway/adapters/mock/script-queue.js +60 -0
- package/dist/gateway/adapters/mock/server.d.ts +16 -0
- package/dist/gateway/adapters/mock/server.js +342 -0
- package/dist/gateway/adapters/mock/write-directive.d.ts +15 -0
- package/dist/gateway/adapters/mock/write-directive.js +21 -0
- package/dist/gateway/adapters/openai/adapter.d.ts +3 -0
- package/dist/gateway/adapters/openai/adapter.js +35 -0
- package/dist/gateway/adapters/openai/request-map.d.ts +31 -0
- package/dist/gateway/adapters/openai/request-map.js +228 -0
- package/dist/gateway/adapters/openai/stream-collect.d.ts +63 -0
- package/dist/gateway/adapters/openai/stream-collect.js +490 -0
- package/dist/gateway/adapters/openai-compatible/adapter.d.ts +3 -0
- package/dist/gateway/adapters/openai-compatible/adapter.js +35 -0
- package/dist/gateway/adapters/openai-compatible/request-map.d.ts +31 -0
- package/dist/gateway/adapters/openai-compatible/request-map.js +180 -0
- package/dist/gateway/adapters/openai-compatible/stream-collect.d.ts +84 -0
- package/dist/gateway/adapters/openai-compatible/stream-collect.js +215 -0
- package/dist/gateway/adapters/provider-http-error.d.ts +65 -0
- package/dist/gateway/adapters/provider-http-error.js +188 -0
- package/dist/gateway/adapters/provider-stream.d.ts +23 -0
- package/dist/gateway/adapters/provider-stream.js +58 -0
- package/dist/gateway/attempt-stream.d.ts +27 -0
- package/dist/gateway/attempt-stream.js +329 -0
- package/dist/gateway/create-gateway.d.ts +25 -0
- package/dist/gateway/create-gateway.js +88 -0
- package/dist/gateway/deadline.d.ts +56 -0
- package/dist/gateway/deadline.js +120 -0
- package/dist/gateway/domain/index.d.ts +10 -0
- package/dist/gateway/domain/index.js +10 -0
- package/dist/gateway/domain/media.d.ts +62 -0
- package/dist/gateway/domain/media.js +126 -0
- package/dist/gateway/domain/metering.d.ts +7 -0
- package/dist/gateway/domain/metering.js +6 -0
- package/dist/gateway/domain/resolve-call.d.ts +24 -0
- package/dist/gateway/domain/resolve-call.js +39 -0
- package/dist/gateway/domain/types.d.ts +457 -0
- package/dist/gateway/domain/types.js +10 -0
- package/dist/gateway/helpers/messages.d.ts +17 -0
- package/dist/gateway/helpers/messages.js +29 -0
- package/dist/gateway/helpers/parse-tool-arguments.d.ts +9 -0
- package/dist/gateway/helpers/parse-tool-arguments.js +38 -0
- package/dist/gateway/helpers/tool-call-pairing.d.ts +13 -0
- package/dist/gateway/helpers/tool-call-pairing.js +25 -0
- package/dist/gateway/index.d.ts +12 -0
- package/dist/gateway/index.js +11 -0
- package/dist/gateway/mock-script.d.ts +129 -0
- package/dist/gateway/mock-script.js +129 -0
- package/dist/gateway/mock.d.ts +11 -0
- package/dist/gateway/mock.js +22 -0
- package/dist/gateway/ports/gateway.d.ts +18 -0
- package/dist/gateway/ports/gateway.js +1 -0
- package/dist/gateway/ports/provider-adapter.d.ts +21 -0
- package/dist/gateway/ports/provider-adapter.js +1 -0
- package/dist/gateway/routing.d.ts +28 -0
- package/dist/gateway/routing.js +48 -0
- package/dist/gateway/shapes/index.d.ts +7 -0
- package/dist/gateway/shapes/index.js +1 -0
- package/dist/gateway/shapes/json.d.ts +4 -0
- package/dist/gateway/shapes/json.js +1 -0
- package/dist/gateway/shapes/provider-error.d.ts +10 -0
- package/dist/gateway/shapes/provider-error.js +1 -0
- package/dist/gateway/shapes/usage.d.ts +41 -0
- package/dist/gateway/shapes/usage.js +29 -0
- package/dist/gateway/stream-events.d.ts +21 -0
- package/dist/gateway/stream-events.js +26 -0
- package/package.json +76 -3
|
@@ -0,0 +1,457 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Meridian-canonical gateway types (v1 public API): the provider-neutral request,
|
|
3
|
+
* result, stream-event, message, tool, and capability shapes. The vocabulary
|
|
4
|
+
* every adapter maps its provider SDK to and from; depends on nothing provider-specific.
|
|
5
|
+
*
|
|
6
|
+
* Why this boundary exists (see repo AGENTS.md): provider-specific types must
|
|
7
|
+
* stay inside adapter directories so the orchestrator, loop, and tool executors
|
|
8
|
+
* never import `openai` or `@anthropic-ai/sdk`. Every adapter translates to/from
|
|
9
|
+
* these types at the adapter boundary.
|
|
10
|
+
*
|
|
11
|
+
* Key design invariants:
|
|
12
|
+
* - JSON-natural: every field must survive `JSON.parse(JSON.stringify(x))`.
|
|
13
|
+
* No `Date`, `BigInt`, brand types, or instance objects.
|
|
14
|
+
* - Provider-specific metadata goes in `providerOptions`, never in top-level fields.
|
|
15
|
+
* - `partIndex` on stream deltas is the provider's content-block/output-item position
|
|
16
|
+
* index (Anthropic block `index`, OpenAI Responses `output_index`, OpenAI-Chat
|
|
17
|
+
* `tool_calls[].index`), used by adapters to reconstruct source order.
|
|
18
|
+
* - `GenerateRequest.promptCacheKey` is canonical prompt-cache *intent*, not
|
|
19
|
+
* provider syntax, so it stays top-level (never nested in `providerOptions`):
|
|
20
|
+
* the loop knows the thread's stable key but has no opinion on TTL or wire
|
|
21
|
+
* shape. Each adapter decides whether to forward it (a `prompt_cache_key`
|
|
22
|
+
* routing hint, or nothing). Cache breakpoints are not part of the request:
|
|
23
|
+
* the Anthropic adapter places them on the wire blocks itself.
|
|
24
|
+
*/
|
|
25
|
+
import type { ProviderErrorResponse, Usage } from "../shapes/index.js";
|
|
26
|
+
export type ProviderOptions = Record<string, Record<string, unknown>>;
|
|
27
|
+
/** Tokenizer family used for conservative model-input estimation. */
|
|
28
|
+
export type TokenizerFamily = "anthropic" | "o200k" | "gemini" | "deepseek";
|
|
29
|
+
/** What a model reads as input, in the models.dev vocabulary. */
|
|
30
|
+
export type InputModality = "text" | "image" | "pdf" | "audio" | "video";
|
|
31
|
+
/** Provider cache lifetimes are recorded as the provider states them, in seconds. Anything that must beat a lifetime computes its buffer from these values. */
|
|
32
|
+
export declare const DEFAULT_SUBAGENT_PROMPT_CACHE_TTL: number;
|
|
33
|
+
export declare const DEFAULT_PRIMARY_PROMPT_CACHE_TTL: number;
|
|
34
|
+
/** Registry-declared provider cache behavior and its best-known retention window. */
|
|
35
|
+
export interface PromptCacheDescriptor {
|
|
36
|
+
kind: "explicit" | "automatic";
|
|
37
|
+
/** Lifetime in seconds of a short-retention request (subagents); null means the provider documents none. */
|
|
38
|
+
shortTtlSeconds: number | null;
|
|
39
|
+
/** Lifetime of a long-retention request (primary chats); equals `shortTtlSeconds` when the provider offers one lifetime. */
|
|
40
|
+
longTtlSeconds: number | null;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Which cache lifetime a request wants: primary chats ask for long, subagents for short,
|
|
44
|
+
* and a one-shot call nothing reads again (a rolling summary) for none: no cache mark is sent.
|
|
45
|
+
*/
|
|
46
|
+
export type PromptCacheRetention = "none" | "short" | "long";
|
|
47
|
+
/** The TTL a request with this retention gets from a model, for adapters and warm/cold prediction. */
|
|
48
|
+
export declare function resolvePromptCacheTtlSeconds(cache: PromptCacheDescriptor, retention: PromptCacheRetention): number | null;
|
|
49
|
+
export declare const REASONING_EFFORTS: readonly ["low", "medium", "high", "max"];
|
|
50
|
+
export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
|
|
51
|
+
/**
|
|
52
|
+
* A model's reasoning controls, copied from its models.dev `reasoning_options`
|
|
53
|
+
* (`xhigh`, which Flow never requests, is omitted from `efforts`).
|
|
54
|
+
*/
|
|
55
|
+
export interface ReasoningSupport {
|
|
56
|
+
/** Effort levels the model accepts. */
|
|
57
|
+
efforts: readonly ReasoningEffort[];
|
|
58
|
+
/** Whether reasoning can be turned off: a `toggle` option or a `none` effort. */
|
|
59
|
+
canDisable?: true;
|
|
60
|
+
/**
|
|
61
|
+
* The model reasons unless switched off, so the Anthropic adapter must repair a replayed
|
|
62
|
+
* tool-use turn that lost its thinking block. Declared, not inferred from `canDisable`:
|
|
63
|
+
* a model can have a toggle and still not think by default.
|
|
64
|
+
*/
|
|
65
|
+
thinksByDefault?: true;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Static model metadata registered per provider. `provider` is the id of the
|
|
69
|
+
* ProviderConfig that declares the model.
|
|
70
|
+
*/
|
|
71
|
+
export interface ModelInfo {
|
|
72
|
+
/** The serving provider's adapter, which decides how media is placed and whether a link works. Set by the gateway. */
|
|
73
|
+
wire: BuiltinAdapter;
|
|
74
|
+
reasoning: ReasoningSupport;
|
|
75
|
+
/** The serving provider wants Anthropic's tool-schema projection (`anthropicToolSchema`); others get the schema as given. */
|
|
76
|
+
projectToolSchema?: true;
|
|
77
|
+
/** Whole-request input repricing threshold, if the model has one. */
|
|
78
|
+
inputTierTokens?: number;
|
|
79
|
+
/** Underlying tokenizer family. */
|
|
80
|
+
tokenizer: TokenizerFamily;
|
|
81
|
+
id: string;
|
|
82
|
+
provider: string;
|
|
83
|
+
displayName: string;
|
|
84
|
+
contextWindow: number;
|
|
85
|
+
maxOutputTokens: number;
|
|
86
|
+
promptCache: PromptCacheDescriptor;
|
|
87
|
+
/** Input kinds the model takes, copied from models.dev `modalities.input`. */
|
|
88
|
+
inputModalities: readonly InputModality[];
|
|
89
|
+
/** Largest file in bytes its provider fetches by link, where the provider documents one. */
|
|
90
|
+
maxLinkBytes?: number;
|
|
91
|
+
/** The serving host fetches image links on a wire that doesn't by default (`ProviderConfig.imageLinks`). Set by the gateway. */
|
|
92
|
+
imageLinks?: true;
|
|
93
|
+
}
|
|
94
|
+
/** A model as configured on a provider; the gateway adds the provider's wire format and link setting. */
|
|
95
|
+
export type ProviderModel = Omit<ModelInfo, "wire" | "imageLinks">;
|
|
96
|
+
/**
|
|
97
|
+
* Canonical content part — the building block of every gateway Message.
|
|
98
|
+
*
|
|
99
|
+
* Each variant corresponds to one provider concept:
|
|
100
|
+
* - TextPart: Anthropic `text` block, OpenAI Responses `output_text` item,
|
|
101
|
+
* OpenAI-Chat `delta.content`.
|
|
102
|
+
* - MediaPart: an image or PDF: Anthropic `image`/`document` block, OpenAI
|
|
103
|
+
* `input_image`/`input_file` or Chat `image_url`/`file`, Gemini `fileData`/`inlineData`. Allowed in a user message and
|
|
104
|
+
* inside a tool result.
|
|
105
|
+
* - ReasoningPart: Anthropic `thinking` / OpenAI `reasoning` items.
|
|
106
|
+
* Provider metadata (signature, encrypted_content) lives in providerOptions.
|
|
107
|
+
* - ToolUsePart: Anthropic `tool_use` / OpenAI `function_call` items.
|
|
108
|
+
* `toolCallId` is the provider call identifier used by tool_result to correlate.
|
|
109
|
+
* - ToolResultPart: the output of a tool execution. `isError` flags tool failures
|
|
110
|
+
* so the provider knows to retry or report the error.
|
|
111
|
+
*/
|
|
112
|
+
export interface TextPart {
|
|
113
|
+
type: "text";
|
|
114
|
+
text: string;
|
|
115
|
+
providerOptions?: ProviderOptions;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* A file the model reads. `mediaType` is required, never guessed from a URL. A link is `https`
|
|
119
|
+
* (a data URL is refused); bytes go in `data` as base64. A `reference` is a provider's own file
|
|
120
|
+
* id, sent only to the provider that issued it; no mapper sends one yet.
|
|
121
|
+
*/
|
|
122
|
+
export interface MediaPart {
|
|
123
|
+
type: "media";
|
|
124
|
+
mediaType: string;
|
|
125
|
+
filename?: string;
|
|
126
|
+
/** A PDF's page count. No adapter sends it; callers use it to estimate what the part costs. */
|
|
127
|
+
pageCount?: number;
|
|
128
|
+
source: {
|
|
129
|
+
url: string;
|
|
130
|
+
} | {
|
|
131
|
+
data: string;
|
|
132
|
+
} | {
|
|
133
|
+
reference: {
|
|
134
|
+
provider: string;
|
|
135
|
+
id: string;
|
|
136
|
+
};
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
export interface ReasoningPart {
|
|
140
|
+
type: "reasoning";
|
|
141
|
+
text: string;
|
|
142
|
+
providerOptions?: ProviderOptions;
|
|
143
|
+
}
|
|
144
|
+
export interface ToolUsePart {
|
|
145
|
+
type: "tool_use";
|
|
146
|
+
toolCallId: string;
|
|
147
|
+
toolName: string;
|
|
148
|
+
/**
|
|
149
|
+
* Parsed tool-call input. When `inputParseError` is present, this is `{}`
|
|
150
|
+
* because the provider emitted tool-call JSON that could not be parsed or
|
|
151
|
+
* repaired; downstream must surface a model-facing parse error rather than
|
|
152
|
+
* dispatching the tool.
|
|
153
|
+
*/
|
|
154
|
+
input: Record<string, unknown>;
|
|
155
|
+
inputParseError?: {
|
|
156
|
+
raw: string;
|
|
157
|
+
message: string;
|
|
158
|
+
};
|
|
159
|
+
providerOptions?: ProviderOptions;
|
|
160
|
+
}
|
|
161
|
+
export interface ToolResultPart {
|
|
162
|
+
type: "tool_result";
|
|
163
|
+
toolCallId: string;
|
|
164
|
+
content: Array<TextPart | MediaPart>;
|
|
165
|
+
isError?: boolean;
|
|
166
|
+
providerOptions?: ProviderOptions;
|
|
167
|
+
}
|
|
168
|
+
export type ContentPart = TextPart | MediaPart | ReasoningPart | ToolUsePart | ToolResultPart;
|
|
169
|
+
/**
|
|
170
|
+
* A canonical chat message — maps directly to Anthropic Messages and OpenAI
|
|
171
|
+
* Chat/Responses message shapes. The `tool` role carries tool_result parts
|
|
172
|
+
* back to the provider after execution.
|
|
173
|
+
*/
|
|
174
|
+
export interface Message {
|
|
175
|
+
role: "system" | "user" | "assistant" | "tool";
|
|
176
|
+
content: ContentPart[];
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* A tool Flow executes, with a JSON Schema input signature. The orchestrator
|
|
180
|
+
* sends these to the provider as part of the tool definitions, and the
|
|
181
|
+
* adapter translates them into the provider's tool schema format.
|
|
182
|
+
*/
|
|
183
|
+
export interface Tool {
|
|
184
|
+
type: "function";
|
|
185
|
+
name: string;
|
|
186
|
+
description: string;
|
|
187
|
+
inputSchema: Record<string, unknown>;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* The unified request shape that every adapter translates into its provider SDK call.
|
|
191
|
+
*
|
|
192
|
+
* Routing: `resolveRoute` in routing.ts picks the provider that declares the
|
|
193
|
+
* requested model in its config.
|
|
194
|
+
*
|
|
195
|
+
* Cancellation: the `signal` AbortSignal is propagated through the adapter chain
|
|
196
|
+
* and into the provider SDK call. The deadline helper in deadline.ts derives a
|
|
197
|
+
* per-attempt sub-signal from it, so a killed attempt still respects the parent
|
|
198
|
+
* signal for full-request cancellation.
|
|
199
|
+
*/
|
|
200
|
+
export interface GenerateRequest {
|
|
201
|
+
model?: string;
|
|
202
|
+
messages: Message[];
|
|
203
|
+
tools?: Tool[];
|
|
204
|
+
reasoning?: "disabled" | "adaptive" | {
|
|
205
|
+
effort: ReasoningEffort;
|
|
206
|
+
};
|
|
207
|
+
signal?: AbortSignal;
|
|
208
|
+
/**
|
|
209
|
+
* Stable per-thread cache-routing key (opaque, not a secret): unlike
|
|
210
|
+
* `correlation` below, adapters MAY map this into the provider request —
|
|
211
|
+
* e.g. OpenAI Responses `prompt_cache_key`, which improves cache-affinity
|
|
212
|
+
* routing for automatic caching. Anthropic has no equivalent concept and
|
|
213
|
+
* ignores it.
|
|
214
|
+
*/
|
|
215
|
+
promptCacheKey?: string;
|
|
216
|
+
/** Cache lifetime wanted; fixed per thread kind (`none` for one-shot calls nothing re-reads) so the cached prefix never changes mid-thread. */
|
|
217
|
+
promptCacheRetention: PromptCacheRetention;
|
|
218
|
+
/**
|
|
219
|
+
* Credentials for this call, keyed by provider id. The routed provider's entry replaces that
|
|
220
|
+
* provider's `ProviderConfig.auth`; other entries are ignored, so a request re-routed to
|
|
221
|
+
* another provider never carries this one's credential. Calls with the same `accessToken`
|
|
222
|
+
* function share one cached token; a credential object made fresh for each call is fine. An empty `apiKey` counts as no credential: the provider's own applies.
|
|
223
|
+
*/
|
|
224
|
+
auth?: Record<string, ProviderCredential>;
|
|
225
|
+
/** Observability-only context; adapters must never map it into provider requests. */
|
|
226
|
+
correlation?: {
|
|
227
|
+
/** Preallocated by callers that need to join request content to lifecycle evidence. */
|
|
228
|
+
gatewayCallId?: string;
|
|
229
|
+
threadId?: string;
|
|
230
|
+
turnId?: string;
|
|
231
|
+
iteration?: number;
|
|
232
|
+
agentSlug?: string;
|
|
233
|
+
};
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* Canonical error codes surfaced in StreamEvent.error and GatewayError.
|
|
237
|
+
*
|
|
238
|
+
* `provider_error` is the catch-all for unknown/unclassified provider failures,
|
|
239
|
+
* including timeouts (deadline.ts surfaces timeout as a retryable provider_error).
|
|
240
|
+
* `invalid_request` covers missing models, bad config, and upstream aborts.
|
|
241
|
+
*/
|
|
242
|
+
export type ErrorCode = "network_error" | "rate_limited" | "server_error" | "auth_error" | "invalid_request" | "content_filtered" | "context_overflow" | "provider_error";
|
|
243
|
+
/**
|
|
244
|
+
* Stream event — the canonical event set that every adapter emits and the
|
|
245
|
+
* orchestrator consumes. Each event is a complete, Meridian-typed value; the
|
|
246
|
+
* generator produces them one-at-a-time so subscribers receive them as they
|
|
247
|
+
* arrive from the provider without waiting for the full response.
|
|
248
|
+
*
|
|
249
|
+
* Ordering contract:
|
|
250
|
+
* - "start" is always first (emitted once per provider call).
|
|
251
|
+
* - Content deltas (text/reasoning/tool_call) are emitted in provider
|
|
252
|
+
* arrival order. `partIndex` is the provider content-block position: the
|
|
253
|
+
* Anthropic block `index`, OpenAI Responses `output_index`, or
|
|
254
|
+
* OpenAI-Chat-Compatible `tool_calls[].index`. It is set ONLY when the
|
|
255
|
+
* provider exposes a stable source-order position; the openai-compatible
|
|
256
|
+
* text deltas omit it because Chat Completions do not partition text into
|
|
257
|
+
* separate content blocks.
|
|
258
|
+
* - "usage" may appear zero, one, or multiple times depending on provider
|
|
259
|
+
* convention (e.g., Anthropic sends early usage at message_start + final at
|
|
260
|
+
* message_delta; OpenAI Responses only at response.completed).
|
|
261
|
+
* - "end" is always last on success; "error" terminates the stream on failure.
|
|
262
|
+
*/
|
|
263
|
+
export type StreamEvent = {
|
|
264
|
+
type: "start";
|
|
265
|
+
model: string;
|
|
266
|
+
provider: string;
|
|
267
|
+
} | {
|
|
268
|
+
type: "text.delta";
|
|
269
|
+
text: string;
|
|
270
|
+
partIndex?: number;
|
|
271
|
+
} | {
|
|
272
|
+
type: "reasoning.delta";
|
|
273
|
+
text: string;
|
|
274
|
+
partIndex?: number;
|
|
275
|
+
} | {
|
|
276
|
+
type: "tool_call.delta";
|
|
277
|
+
id: string;
|
|
278
|
+
name: string;
|
|
279
|
+
argumentsDelta: string;
|
|
280
|
+
partIndex?: number;
|
|
281
|
+
} | {
|
|
282
|
+
type: "usage";
|
|
283
|
+
usage: Usage;
|
|
284
|
+
} | {
|
|
285
|
+
type: "end";
|
|
286
|
+
result: GenerateResult;
|
|
287
|
+
} | {
|
|
288
|
+
type: "error";
|
|
289
|
+
code: ErrorCode;
|
|
290
|
+
/** Metered partial output when the provider terminates with an error. */
|
|
291
|
+
result?: GenerateResult;
|
|
292
|
+
message: string;
|
|
293
|
+
retryable: boolean;
|
|
294
|
+
retryAfterMs?: number;
|
|
295
|
+
/** Present when the provider answered; absent for network, timeout, and local failures. */
|
|
296
|
+
providerError?: ProviderErrorResponse;
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* A parsed tool call extracted from a provider response. `id` is the provider-
|
|
300
|
+
* specific call identifier (Anthropic `tool_use.id`, OpenAI Responses `call_id`,
|
|
301
|
+
* OpenAI-Chat `tool_calls[].id` or a synthesized `call_${index}` fallback).
|
|
302
|
+
* This ID is the stable key used by `tool_result` messages to correlate
|
|
303
|
+
* outputs back to the call.
|
|
304
|
+
*/
|
|
305
|
+
export interface ToolCall {
|
|
306
|
+
id: string;
|
|
307
|
+
name: string;
|
|
308
|
+
/**
|
|
309
|
+
* Parsed tool-call arguments. When `argumentsParseError` is present, this is
|
|
310
|
+
* `{}` because the provider emitted tool-call JSON that could not be parsed
|
|
311
|
+
* or repaired.
|
|
312
|
+
*/
|
|
313
|
+
arguments: Record<string, unknown>;
|
|
314
|
+
argumentsParseError?: {
|
|
315
|
+
raw: string;
|
|
316
|
+
message: string;
|
|
317
|
+
};
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Why the provider stopped generating.
|
|
321
|
+
*
|
|
322
|
+
* Provider mapping:
|
|
323
|
+
* - Anthropic StopReason → FinishReason: `end_turn`→`end_turn`, `tool_use`→`tool_use`,
|
|
324
|
+
* `max_tokens`→`max_tokens`, `stop_sequence`→`stop_sequence`, `refusal`→`error`.
|
|
325
|
+
* NOTE: Anthropic docs additionally list `model_context_window_exceeded` but the
|
|
326
|
+
* installed SDK 0.100.1 union does not include it; if that value arrives at runtime
|
|
327
|
+
* the adapter maps the wire string to the canonical `context_overflow` error.
|
|
328
|
+
* - OpenAI Responses status: `completed`→`end_turn`, `failed`/`cancelled`→`error`,
|
|
329
|
+
* `incomplete` maps to `max_tokens` or `error` depending on `incomplete_details.reason`.
|
|
330
|
+
* - OpenAI-Chat finish_reason: `stop`→`end_turn`, `tool_calls`→`tool_use`,
|
|
331
|
+
* `length`→`max_tokens`, `content_filter`→`error`.
|
|
332
|
+
*
|
|
333
|
+
* Precedence: `tool_use` wins over any terminal status when tool calls were
|
|
334
|
+
* actually assembled (the orchestrator must execute tools before considering
|
|
335
|
+
* the turn finished).
|
|
336
|
+
*/
|
|
337
|
+
export type FinishReason = "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "error";
|
|
338
|
+
/**
|
|
339
|
+
* The final, complete result of one provider call. Built by the adapter's
|
|
340
|
+
* stream accumulator after all stream events have been processed.
|
|
341
|
+
*
|
|
342
|
+
* `content` is ordered in provider source order (Anthropic block index,
|
|
343
|
+
* OpenAI Responses output_index), not grouped by part type. This preserves the
|
|
344
|
+
* model's intended content sequence: reasoning → text → tool_use interleaving.
|
|
345
|
+
*
|
|
346
|
+
* `toolCalls` is a flat list of every parsed ToolCall in the response; the
|
|
347
|
+
* orchestrator uses this to dispatch tool execution.
|
|
348
|
+
*/
|
|
349
|
+
export interface GenerateResult {
|
|
350
|
+
content: ContentPart[];
|
|
351
|
+
toolCalls: ToolCall[];
|
|
352
|
+
/** Null when the call was stopped: the adapter's finish reason then says nothing true. */
|
|
353
|
+
finishReason: FinishReason | null;
|
|
354
|
+
usage: Usage;
|
|
355
|
+
model: string;
|
|
356
|
+
provider: string;
|
|
357
|
+
/** Set on a cancelled stream that reported no usage: the call is unmetered, not free. */
|
|
358
|
+
meteringStatus?: "missing_usage";
|
|
359
|
+
/** Populated by the per-attempt gateway loop on a successful terminal event. */
|
|
360
|
+
timing?: ModelCallTiming;
|
|
361
|
+
}
|
|
362
|
+
/** Provider-arrival timing for one successful model request attempt. */
|
|
363
|
+
export interface ModelCallTiming {
|
|
364
|
+
/** Wall-clock start of this attempt, retained even under consumer backpressure. */
|
|
365
|
+
requestStartedAt: string;
|
|
366
|
+
/** Adapter invocation to stream-end arrival; null if the pump was already backpressured. */
|
|
367
|
+
latencyMs: number | null;
|
|
368
|
+
/** Adapter invocation to first output; null if absent or the pump was already backpressured. */
|
|
369
|
+
timeToFirstTokenMs: number | null;
|
|
370
|
+
/** First output to stream-end arrival; null if absent or any consumer backpressure occurred. */
|
|
371
|
+
generationMs: number | null;
|
|
372
|
+
}
|
|
373
|
+
/**
|
|
374
|
+
* A short-lived access token and when it stops being valid (Unix seconds; `null` when unknown,
|
|
375
|
+
* which the gateway treats as valid until a call fails with 401).
|
|
376
|
+
*/
|
|
377
|
+
export interface AccessToken {
|
|
378
|
+
token: string;
|
|
379
|
+
expiresAt: number | null;
|
|
380
|
+
}
|
|
381
|
+
/**
|
|
382
|
+
* Mints an access token. Structurally the Anthropic SDK's `AccessTokenProvider`, so
|
|
383
|
+
* `oidcFederationProvider(...)` plugs in unchanged. `forceRefresh` asks for a new token even if
|
|
384
|
+
* the provider holds an unexpired one. The gateway caches the result and calls this once at a
|
|
385
|
+
* time per token function.
|
|
386
|
+
*/
|
|
387
|
+
export type AccessTokenProvider = (opts?: {
|
|
388
|
+
forceRefresh?: boolean;
|
|
389
|
+
}) => Promise<AccessToken>;
|
|
390
|
+
/**
|
|
391
|
+
* What a call to one provider authenticates with: a static key, or a token provider for
|
|
392
|
+
* workload identity federation. Never serialized, traced or put in an error message by the
|
|
393
|
+
* gateway; the host must keep it out of anything it captures.
|
|
394
|
+
*/
|
|
395
|
+
export type ProviderCredential = {
|
|
396
|
+
apiKey: string;
|
|
397
|
+
} | {
|
|
398
|
+
accessToken: AccessTokenProvider;
|
|
399
|
+
};
|
|
400
|
+
/** The provider adapters createAdapter (create-gateway.ts) can build. */
|
|
401
|
+
export type BuiltinAdapter = "anthropic" | "openai" | "openai-compatible" | "gemini";
|
|
402
|
+
/**
|
|
403
|
+
* A configured provider entry. `adapter` selects the provider adapter factory
|
|
404
|
+
* in createAdapter (create-gateway.ts). `baseUrl` overrides the provider's
|
|
405
|
+
* default API endpoint.
|
|
406
|
+
*/
|
|
407
|
+
export interface ProviderConfig {
|
|
408
|
+
id: string;
|
|
409
|
+
adapter: BuiltinAdapter;
|
|
410
|
+
/** The provider's own credential, used by every call that carries none for this provider. */
|
|
411
|
+
auth?: ProviderCredential;
|
|
412
|
+
/** Extra headers sent on every request to this provider. Not a credential: nothing secret belongs here, since the host may log config. */
|
|
413
|
+
headers?: Record<string, string>;
|
|
414
|
+
baseUrl?: string;
|
|
415
|
+
/**
|
|
416
|
+
* The host fetches image links. Whether an OpenAI-compatible host does is its own fact, so
|
|
417
|
+
* the wire defaults to bytes only (as the Vercel AI SDK does); the other wires decide for
|
|
418
|
+
* themselves and ignore this.
|
|
419
|
+
*/
|
|
420
|
+
imageLinks?: true;
|
|
421
|
+
models: ProviderModel[];
|
|
422
|
+
}
|
|
423
|
+
/**
|
|
424
|
+
* Gateway configuration — the single input to createGateway().
|
|
425
|
+
*
|
|
426
|
+
* Policy knobs:
|
|
427
|
+
* - `attemptStallMs`: inactivity (stall) timeout for one provider attempt
|
|
428
|
+
* (default `DEFAULT_ATTEMPT_STALL_MS`). Enforced by the deadline helper, which aborts the in-flight
|
|
429
|
+
* provider stream when no progress arrives within the window. Every stream
|
|
430
|
+
* event re-arms it, so a slow-but-streaming model is never killed. 0 disables.
|
|
431
|
+
* - `attemptCeilingMs`: absolute backstop for one provider attempt (default
|
|
432
|
+
* `DEFAULT_ATTEMPT_CEILING_MS`), fixed from attempt start. Not the normal terminator; 0 disables it
|
|
433
|
+
* for self-hosted models. Timeouts are retryable.
|
|
434
|
+
* - `retry`: controls per-provider retry with exponential backoff. Only
|
|
435
|
+
* retries before committed output (visible text or a tool call) has been
|
|
436
|
+
* emitted to the caller; reasoning-only attempts are retryable.
|
|
437
|
+
*/
|
|
438
|
+
export interface GatewayConfig {
|
|
439
|
+
providers: ProviderConfig[];
|
|
440
|
+
defaultModel?: string;
|
|
441
|
+
/** Inactivity window for one provider attempt; re-armed on every event. 0 disables. */
|
|
442
|
+
attemptStallMs?: number;
|
|
443
|
+
/** Absolute ceiling for one provider attempt. 0 disables. Retry/backoff is outside this window. */
|
|
444
|
+
attemptCeilingMs?: number;
|
|
445
|
+
retry?: {
|
|
446
|
+
maxAttempts: number;
|
|
447
|
+
initialDelayMs: number;
|
|
448
|
+
maxDelayMs: number;
|
|
449
|
+
};
|
|
450
|
+
/** Registry build warnings (e.g. duplicate model IDs skipped). */
|
|
451
|
+
onWarning?: (span: TraceSpan) => void;
|
|
452
|
+
}
|
|
453
|
+
/** Minimal trace span passed to `GatewayConfig.onWarning`. */
|
|
454
|
+
export interface TraceSpan {
|
|
455
|
+
name: string;
|
|
456
|
+
attributes?: Record<string, unknown>;
|
|
457
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/** Provider cache lifetimes are recorded as the provider states them, in seconds. Anything that must beat a lifetime computes its buffer from these values. */
|
|
2
|
+
export const DEFAULT_SUBAGENT_PROMPT_CACHE_TTL = 5 * 60;
|
|
3
|
+
export const DEFAULT_PRIMARY_PROMPT_CACHE_TTL = 60 * 60;
|
|
4
|
+
/** The TTL a request with this retention gets from a model, for adapters and warm/cold prediction. */
|
|
5
|
+
export function resolvePromptCacheTtlSeconds(cache, retention) {
|
|
6
|
+
if (retention === "none")
|
|
7
|
+
return null;
|
|
8
|
+
return retention === "long" ? cache.longTtlSeconds : cache.shortTtlSeconds;
|
|
9
|
+
}
|
|
10
|
+
export const REASONING_EFFORTS = ["low", "medium", "high", "max"];
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Message-construction helpers: small builders (user/assistant/system/text/
|
|
3
|
+
* toolResult) for canonical gateway Message values. Convenience over the
|
|
4
|
+
* domain message types.
|
|
5
|
+
*
|
|
6
|
+
* These are simple constructors that produce well-formed Message/ContentPart
|
|
7
|
+
* values without boilerplate. Used by context-builder.ts in the loop and by
|
|
8
|
+
* tests.
|
|
9
|
+
*/
|
|
10
|
+
import type { ContentPart, MediaPart, Message, ProviderOptions, TextPart } from "../domain/index.js";
|
|
11
|
+
export declare function user(text: string): Message;
|
|
12
|
+
export declare function system(text: string): Message;
|
|
13
|
+
export declare function text(t: string, opts?: {
|
|
14
|
+
providerOptions?: ProviderOptions;
|
|
15
|
+
}): TextPart;
|
|
16
|
+
export declare function assistant(parts: ContentPart[]): Message;
|
|
17
|
+
export declare function toolResult(toolCallId: string, content: Array<TextPart | MediaPart>, isError?: boolean): Message;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Message-construction helpers: small builders (user/assistant/system/text/
|
|
3
|
+
* toolResult) for canonical gateway Message values. Convenience over the
|
|
4
|
+
* domain message types.
|
|
5
|
+
*
|
|
6
|
+
* These are simple constructors that produce well-formed Message/ContentPart
|
|
7
|
+
* values without boilerplate. Used by context-builder.ts in the loop and by
|
|
8
|
+
* tests.
|
|
9
|
+
*/
|
|
10
|
+
export function user(text) {
|
|
11
|
+
return { role: "user", content: [{ type: "text", text }] };
|
|
12
|
+
}
|
|
13
|
+
export function system(text) {
|
|
14
|
+
return { role: "system", content: [{ type: "text", text }] };
|
|
15
|
+
}
|
|
16
|
+
export function text(t, opts) {
|
|
17
|
+
return opts?.providerOptions
|
|
18
|
+
? { type: "text", text: t, providerOptions: opts.providerOptions }
|
|
19
|
+
: { type: "text", text: t };
|
|
20
|
+
}
|
|
21
|
+
export function assistant(parts) {
|
|
22
|
+
return { role: "assistant", content: parts };
|
|
23
|
+
}
|
|
24
|
+
export function toolResult(toolCallId, content, isError) {
|
|
25
|
+
return {
|
|
26
|
+
role: "tool",
|
|
27
|
+
content: [{ type: "tool_result", toolCallId, content, isError }],
|
|
28
|
+
};
|
|
29
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Repairs provider tool-call argument JSON when an LLM emits malformed object
|
|
3
|
+
* text. OpenAI-compatible models sometimes produce bare unquoted hash-like
|
|
4
|
+
* tokens (for example `"in": 6c4a`); repair confidently fixable JSON, and
|
|
5
|
+
* otherwise return an explicit typed parse failure so callers can keep parsed
|
|
6
|
+
* arguments separate from model-facing error reporting.
|
|
7
|
+
*/
|
|
8
|
+
import { jsonrepair } from "jsonrepair";
|
|
9
|
+
function isJsonObject(value) {
|
|
10
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
11
|
+
}
|
|
12
|
+
function messageFromError(error) {
|
|
13
|
+
return error instanceof Error ? error.message : String(error);
|
|
14
|
+
}
|
|
15
|
+
function parseError(raw, message) {
|
|
16
|
+
return { ok: false, raw, message };
|
|
17
|
+
}
|
|
18
|
+
export function parseToolCallArguments(raw) {
|
|
19
|
+
if (!raw)
|
|
20
|
+
return { ok: true, arguments: {} };
|
|
21
|
+
try {
|
|
22
|
+
const parsed = JSON.parse(raw);
|
|
23
|
+
if (isJsonObject(parsed))
|
|
24
|
+
return { ok: true, arguments: parsed };
|
|
25
|
+
return parseError(raw, "Tool arguments must be a JSON object");
|
|
26
|
+
}
|
|
27
|
+
catch (strictError) {
|
|
28
|
+
try {
|
|
29
|
+
const repaired = JSON.parse(jsonrepair(raw));
|
|
30
|
+
if (isJsonObject(repaired))
|
|
31
|
+
return { ok: true, arguments: repaired };
|
|
32
|
+
return parseError(raw, "Tool arguments must be a JSON object");
|
|
33
|
+
}
|
|
34
|
+
catch (repairError) {
|
|
35
|
+
return parseError(raw, messageFromError(repairError) || messageFromError(strictError));
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pairs tool results with their calls. A call id is the model's per response, so one id can recur
|
|
3
|
+
* within a turn: a result answers the latest call with its id before it. Feed calls and results in
|
|
4
|
+
* order (message order, or block `sequence` within a turn).
|
|
5
|
+
*/
|
|
6
|
+
export declare class ToolCallPairing<C> {
|
|
7
|
+
#private;
|
|
8
|
+
call(toolCallId: string, call: C): void;
|
|
9
|
+
/** The call this result answers, or undefined when no call with its id came before. */
|
|
10
|
+
answer(toolCallId: string): C | undefined;
|
|
11
|
+
/** Every call no result answered, in call order. */
|
|
12
|
+
unanswered(): C[];
|
|
13
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pairs tool results with their calls. A call id is the model's per response, so one id can recur
|
|
3
|
+
* within a turn: a result answers the latest call with its id before it. Feed calls and results in
|
|
4
|
+
* order (message order, or block `sequence` within a turn).
|
|
5
|
+
*/
|
|
6
|
+
export class ToolCallPairing {
|
|
7
|
+
#latest = new Map();
|
|
8
|
+
#all = [];
|
|
9
|
+
call(toolCallId, call) {
|
|
10
|
+
const entry = { call, answered: false };
|
|
11
|
+
this.#latest.set(toolCallId, entry);
|
|
12
|
+
this.#all.push(entry);
|
|
13
|
+
}
|
|
14
|
+
/** The call this result answers, or undefined when no call with its id came before. */
|
|
15
|
+
answer(toolCallId) {
|
|
16
|
+
const entry = this.#latest.get(toolCallId);
|
|
17
|
+
if (entry)
|
|
18
|
+
entry.answered = true;
|
|
19
|
+
return entry?.call;
|
|
20
|
+
}
|
|
21
|
+
/** Every call no result answered, in call order. */
|
|
22
|
+
unanswered() {
|
|
23
|
+
return this.#all.filter((entry) => !entry.answered).map((entry) => entry.call);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Barrel: the model gateway's public surface — the gateway factory, the provider-neutral
|
|
3
|
+
* domain types, message helpers and the shared data shapes. The mock provider is the
|
|
4
|
+
* separate `./gateway/mock` entry, which needs `node:http`.
|
|
5
|
+
*/
|
|
6
|
+
export { assertModelsOnWire, createGateway } from "./create-gateway.js";
|
|
7
|
+
export { DEFAULT_ATTEMPT_CEILING_MS, DEFAULT_ATTEMPT_STALL_MS } from "./deadline.js";
|
|
8
|
+
export * from "./domain/index.js";
|
|
9
|
+
export { assistant, system, text, toolResult, user } from "./helpers/messages.js";
|
|
10
|
+
export { ToolCallPairing } from "./helpers/tool-call-pairing.js";
|
|
11
|
+
export type { Gateway } from "./ports/gateway.js";
|
|
12
|
+
export * from "./shapes/index.js";
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Barrel: the model gateway's public surface — the gateway factory, the provider-neutral
|
|
3
|
+
* domain types, message helpers and the shared data shapes. The mock provider is the
|
|
4
|
+
* separate `./gateway/mock` entry, which needs `node:http`.
|
|
5
|
+
*/
|
|
6
|
+
export { assertModelsOnWire, createGateway } from "./create-gateway.js";
|
|
7
|
+
export { DEFAULT_ATTEMPT_CEILING_MS, DEFAULT_ATTEMPT_STALL_MS } from "./deadline.js";
|
|
8
|
+
export * from "./domain/index.js";
|
|
9
|
+
export { assistant, system, text, toolResult, user } from "./helpers/messages.js";
|
|
10
|
+
export { ToolCallPairing } from "./helpers/tool-call-pairing.js";
|
|
11
|
+
export * from "./shapes/index.js";
|