@meridian-flow/runtime 0.1.2 → 0.3.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 +7 -6
- package/dist/gateway/adapters/anthropic/request-map.js +4 -6
- package/dist/gateway/adapters/anthropic/stream-collect.d.ts +0 -9
- package/dist/gateway/adapters/anthropic/stream-collect.js +0 -5
- package/dist/gateway/adapters/openai/stream-collect.js +1 -2
- package/dist/gateway/adapters/provider-http-error.d.ts +5 -1
- package/dist/gateway/adapters/provider-http-error.js +9 -2
- package/dist/gateway/domain/types.d.ts +14 -8
- package/dist/gateway/helpers/messages.d.ts +2 -2
- package/dist/gateway/mock-script.d.ts +36 -36
- package/dist/mcp/client.d.ts +2 -0
- package/dist/mcp/client.js +279 -0
- package/dist/mcp/content.d.ts +7 -0
- package/dist/mcp/content.js +54 -0
- package/dist/mcp/fault.d.ts +6 -0
- package/dist/mcp/fault.js +48 -0
- package/dist/mcp/index.d.ts +4 -0
- package/dist/mcp/index.js +3 -0
- package/dist/mcp/pin.d.ts +31 -0
- package/dist/mcp/pin.js +153 -0
- package/dist/mcp/reply-limit.d.ts +14 -0
- package/dist/mcp/reply-limit.js +59 -0
- package/dist/mcp/session.d.ts +96 -0
- package/dist/mcp/session.js +280 -0
- package/dist/mcp/types.d.ts +182 -0
- package/dist/mcp/types.js +1 -0
- package/package.json +19 -12
package/README.md
CHANGED
|
@@ -11,12 +11,13 @@ Node 20 or newer, ESM only.
|
|
|
11
11
|
|
|
12
12
|
## Entries
|
|
13
13
|
|
|
14
|
-
| Entry | What it is
|
|
15
|
-
| -------------------------------------------- |
|
|
16
|
-
| `@meridian-flow/runtime/gateway` | One streaming `Gateway` over Anthropic, OpenAI, Gemini and OpenAI-compatible providers: retries, deadlines, usage normalization and a credential per call.
|
|
17
|
-
| `@meridian-flow/runtime/gateway/shapes` | The gateway's usage, provider-error and JSON types. No Node built-ins and no SDKs, so a browser bundle can import them.
|
|
18
|
-
| `@meridian-flow/runtime/gateway/mock` | A mock provider server for tests and local development (needs `node:http`).
|
|
19
|
-
| `@meridian-flow/runtime/gateway/mock-script` | The zod schemas of the mock's scripts.
|
|
14
|
+
| Entry | What it is |
|
|
15
|
+
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
16
|
+
| `@meridian-flow/runtime/gateway` | One streaming `Gateway` over Anthropic, OpenAI, Gemini and OpenAI-compatible providers: retries, deadlines, usage normalization and a credential per call. |
|
|
17
|
+
| `@meridian-flow/runtime/gateway/shapes` | The gateway's usage, provider-error and JSON types. No Node built-ins and no SDKs, so a browser bundle can import them. |
|
|
18
|
+
| `@meridian-flow/runtime/gateway/mock` | A mock provider server for tests and local development (needs `node:http`). |
|
|
19
|
+
| `@meridian-flow/runtime/gateway/mock-script` | The zod schemas of the mock's scripts. |
|
|
20
|
+
| `@meridian-flow/runtime/mcp` | A client for MCP servers over stdio and Streamable HTTP: list, call and check, with replies read off the wire, plus pure functions that pin tools for a model. Needs Node. |
|
|
20
21
|
|
|
21
22
|
The package reads no environment variable: keys, URLs and policy come in through config or the call.
|
|
22
23
|
|
|
@@ -203,7 +203,7 @@ function mergeConsecutiveSameRole(messages) {
|
|
|
203
203
|
// turns it into a single marked text block (see `markCachePrefix`).
|
|
204
204
|
//
|
|
205
205
|
function extractSystem(messages) {
|
|
206
|
-
const system = textFromParts(messages.
|
|
206
|
+
const system = textFromParts(messages.flatMap((m) => (m.role === "system" ? m.content : [])));
|
|
207
207
|
return system.length > 0 ? system : undefined;
|
|
208
208
|
}
|
|
209
209
|
// ── Cache marking ─────────────────────────────────────────────────
|
|
@@ -219,13 +219,11 @@ function markCachePrefix(system, messages, cacheControl) {
|
|
|
219
219
|
const marked = [...messages];
|
|
220
220
|
let remaining = 2;
|
|
221
221
|
for (let index = marked.length - 1; index >= 0 && remaining > 0; index--) {
|
|
222
|
-
|
|
222
|
+
const message = marked[index];
|
|
223
|
+
if (message.role !== "user")
|
|
223
224
|
continue;
|
|
224
225
|
remaining--;
|
|
225
|
-
marked[index] = {
|
|
226
|
-
...marked[index],
|
|
227
|
-
content: markLastBlock(marked[index].content, cacheControl),
|
|
228
|
-
};
|
|
226
|
+
marked[index] = { ...message, content: markLastBlock(message.content, cacheControl) };
|
|
229
227
|
}
|
|
230
228
|
return {
|
|
231
229
|
system: system && [{ type: "text", text: system, cache_control: cacheControl }],
|
|
@@ -22,10 +22,6 @@
|
|
|
22
22
|
* not user-visible, arrives just before `content_block_stop`),
|
|
23
23
|
* `input_json_delta` (partial JSON for tool input — must be concatenated
|
|
24
24
|
* before parsing).
|
|
25
|
-
* - StopReason mismatch: current Anthropic docs list
|
|
26
|
-
* `model_context_window_exceeded`, but the SDK's
|
|
27
|
-
* `StopReason` union is `'end_turn' | 'max_tokens' | 'stop_sequence' |
|
|
28
|
-
* 'tool_use' | 'pause_turn' | 'refusal'` — that value is not present.
|
|
29
25
|
*/
|
|
30
26
|
import type Anthropic from "@anthropic-ai/sdk";
|
|
31
27
|
import type { ContentPart, FinishReason, GenerateResult, StreamEvent } from "../../domain/index.js";
|
|
@@ -54,11 +50,6 @@ interface ReasoningBlockEntry {
|
|
|
54
50
|
export declare function createStreamAccumulator(model: string, provider: string, longCacheWrites: boolean): StreamAccumulator;
|
|
55
51
|
/**
|
|
56
52
|
* Map Anthropic stop reasons to the canonical FinishReason.
|
|
57
|
-
*
|
|
58
|
-
* The SDK's StopReason union is:
|
|
59
|
-
* 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal'
|
|
60
|
-
* Current Anthropic docs additionally list `model_context_window_exceeded`,
|
|
61
|
-
* but that value is not in the SDK union; accept the wire string at this boundary.
|
|
62
53
|
*/
|
|
63
54
|
export declare function mapStopReason(reason: string | null | undefined): FinishReason;
|
|
64
55
|
export declare function mapUsage(usage: Anthropic.Messages.Usage | Anthropic.Messages.MessageDeltaUsage, longCacheWrites: boolean, fallback?: Usage): Usage;
|
|
@@ -19,11 +19,6 @@ export function createStreamAccumulator(model, provider, longCacheWrites) {
|
|
|
19
19
|
// ── Finish reason mapping ─────────────────────────────────────────
|
|
20
20
|
/**
|
|
21
21
|
* Map Anthropic stop reasons to the canonical FinishReason.
|
|
22
|
-
*
|
|
23
|
-
* The SDK's StopReason union is:
|
|
24
|
-
* 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal'
|
|
25
|
-
* Current Anthropic docs additionally list `model_context_window_exceeded`,
|
|
26
|
-
* but that value is not in the SDK union; accept the wire string at this boundary.
|
|
27
22
|
*/
|
|
28
23
|
export function mapStopReason(reason) {
|
|
29
24
|
// Anthropic stop reasons mostly line up with the canonical FinishReason. `refusal`
|
|
@@ -103,8 +103,7 @@ export function mapUsage(usage, longCacheWrites) {
|
|
|
103
103
|
//
|
|
104
104
|
// GPT-5.6+ also bills cache writes: `cache_write_tokens` is their total, split by
|
|
105
105
|
// lifetime in `cache_write_tokens_details` (`ttl_30m_tokens` + `ttl_12h_tokens`), and
|
|
106
|
-
// `cached_tokens` excludes them.
|
|
107
|
-
// the `cache_write_tokens_details` split, so that is read through a local shape.
|
|
106
|
+
// `cached_tokens` excludes them. Models before GPT-5.6 omit both at runtime, whatever the SDK's types say.
|
|
108
107
|
const details = usage.input_tokens_details;
|
|
109
108
|
const result = {
|
|
110
109
|
inputTokens: usage.input_tokens,
|
|
@@ -49,10 +49,14 @@ export declare function providerClientOptions(config: ProviderConfig, defaultBas
|
|
|
49
49
|
maxRetries: number;
|
|
50
50
|
fetch: typeof fetch;
|
|
51
51
|
};
|
|
52
|
-
/**
|
|
52
|
+
/**
|
|
53
|
+
* Anthropic client options that default from the environment, set to "none".
|
|
54
|
+
* `openTelemetry: false` stops the `ANTHROPIC_OPEN_TELEMETRY*` variables and the SDK's spans and trace headers.
|
|
55
|
+
*/
|
|
53
56
|
export declare const ANTHROPIC_ENV_OPTOUT: {
|
|
54
57
|
authToken: null;
|
|
55
58
|
webhookKey: null;
|
|
59
|
+
openTelemetry: false;
|
|
56
60
|
};
|
|
57
61
|
/** OpenAI client options that default from the environment, set to "none". */
|
|
58
62
|
export declare const OPENAI_ENV_OPTOUT: {
|
|
@@ -96,8 +96,15 @@ export function providerClientOptions(config, defaultBaseUrl) {
|
|
|
96
96
|
fetch: providerFetch,
|
|
97
97
|
};
|
|
98
98
|
}
|
|
99
|
-
/**
|
|
100
|
-
|
|
99
|
+
/**
|
|
100
|
+
* Anthropic client options that default from the environment, set to "none".
|
|
101
|
+
* `openTelemetry: false` stops the `ANTHROPIC_OPEN_TELEMETRY*` variables and the SDK's spans and trace headers.
|
|
102
|
+
*/
|
|
103
|
+
export const ANTHROPIC_ENV_OPTOUT = {
|
|
104
|
+
authToken: null,
|
|
105
|
+
webhookKey: null,
|
|
106
|
+
openTelemetry: false,
|
|
107
|
+
};
|
|
101
108
|
/** OpenAI client options that default from the environment, set to "none". */
|
|
102
109
|
export const OPENAI_ENV_OPTOUT = {
|
|
103
110
|
adminAPIKey: null,
|
|
@@ -101,7 +101,7 @@ export type ProviderModel = Omit<ModelInfo, "wire" | "imageLinks">;
|
|
|
101
101
|
* OpenAI-Chat `delta.content`.
|
|
102
102
|
* - MediaPart: an image or PDF: Anthropic `image`/`document` block, OpenAI
|
|
103
103
|
* `input_image`/`input_file` or Chat `image_url`/`file`, Gemini `fileData`/`inlineData`. Allowed in a user message and
|
|
104
|
-
* inside a tool result.
|
|
104
|
+
* inside a tool result, never in an assistant message.
|
|
105
105
|
* - ReasoningPart: Anthropic `thinking` / OpenAI `reasoning` items.
|
|
106
106
|
* Provider metadata (signature, encrypted_content) lives in providerOptions.
|
|
107
107
|
* - ToolUsePart: Anthropic `tool_use` / OpenAI `function_call` items.
|
|
@@ -171,10 +171,18 @@ export type ContentPart = TextPart | MediaPart | ReasoningPart | ToolUsePart | T
|
|
|
171
171
|
* Chat/Responses message shapes. The `tool` role carries tool_result parts
|
|
172
172
|
* back to the provider after execution.
|
|
173
173
|
*/
|
|
174
|
-
export
|
|
175
|
-
role: "system" | "user"
|
|
176
|
-
content:
|
|
177
|
-
}
|
|
174
|
+
export type Message = {
|
|
175
|
+
role: "system" | "user";
|
|
176
|
+
content: Array<TextPart | MediaPart>;
|
|
177
|
+
} | {
|
|
178
|
+
role: "tool";
|
|
179
|
+
content: ToolResultPart[];
|
|
180
|
+
} | {
|
|
181
|
+
role: "assistant";
|
|
182
|
+
content: AssistantContentPart[];
|
|
183
|
+
};
|
|
184
|
+
/** What a model produces. No provider takes media in an assistant turn, so the type has none. */
|
|
185
|
+
export type AssistantContentPart = TextPart | ReasoningPart | ToolUsePart;
|
|
178
186
|
/**
|
|
179
187
|
* A tool the caller executes, with a JSON Schema input signature. The request carries these as
|
|
180
188
|
* the tool definitions, and the adapter translates them into the provider's tool schema format.
|
|
@@ -321,9 +329,7 @@ export interface ToolCall {
|
|
|
321
329
|
* Provider mapping:
|
|
322
330
|
* - Anthropic StopReason → FinishReason: `end_turn`→`end_turn`, `tool_use`→`tool_use`,
|
|
323
331
|
* `max_tokens`→`max_tokens`, `stop_sequence`→`stop_sequence`, `refusal`→`error`.
|
|
324
|
-
*
|
|
325
|
-
* `StopReason` union in `@anthropic-ai/sdk` 0.106 does not include it; if that value arrives at runtime
|
|
326
|
-
* the adapter maps the wire string to the canonical `context_overflow` error.
|
|
332
|
+
* `model_context_window_exceeded` maps to the canonical `context_overflow` error.
|
|
327
333
|
* - OpenAI Responses status: `completed`→`end_turn`, `failed`/`cancelled`→`error`,
|
|
328
334
|
* `incomplete` maps to `max_tokens` or `error` depending on `incomplete_details.reason`.
|
|
329
335
|
* - OpenAI-Chat finish_reason: `stop`→`end_turn`, `tool_calls`→`tool_use`,
|
|
@@ -6,11 +6,11 @@
|
|
|
6
6
|
* These are simple constructors that produce well-formed Message/ContentPart
|
|
7
7
|
* values without boilerplate. Hosts and tests use them to build requests.
|
|
8
8
|
*/
|
|
9
|
-
import type {
|
|
9
|
+
import type { AssistantContentPart, MediaPart, Message, ProviderOptions, TextPart } from "../domain/index.js";
|
|
10
10
|
export declare function user(text: string): Message;
|
|
11
11
|
export declare function system(text: string): Message;
|
|
12
12
|
export declare function text(t: string, opts?: {
|
|
13
13
|
providerOptions?: ProviderOptions;
|
|
14
14
|
}): TextPart;
|
|
15
|
-
export declare function assistant(parts:
|
|
15
|
+
export declare function assistant(parts: AssistantContentPart[]): Message;
|
|
16
16
|
export declare function toolResult(toolCallId: string, content: Array<TextPart | MediaPart>, isError?: boolean): Message;
|
|
@@ -8,10 +8,10 @@ import { z } from "zod";
|
|
|
8
8
|
export declare const mockModelDefaultResponseSchema: z.ZodObject<{
|
|
9
9
|
text: z.ZodOptional<z.ZodString>;
|
|
10
10
|
sample: z.ZodOptional<z.ZodEnum<{
|
|
11
|
-
scene: "scene";
|
|
12
11
|
critique: "critique";
|
|
13
|
-
outline: "outline";
|
|
14
12
|
markdown: "markdown";
|
|
13
|
+
outline: "outline";
|
|
14
|
+
scene: "scene";
|
|
15
15
|
}>>;
|
|
16
16
|
lorem: z.ZodOptional<z.ZodObject<{
|
|
17
17
|
words: z.ZodNumber;
|
|
@@ -29,27 +29,12 @@ export type MockModelDefaultResponse = z.infer<typeof mockModelDefaultResponseSc
|
|
|
29
29
|
* is sticky, so gateway retries and fallbacks fail deterministically.
|
|
30
30
|
*/
|
|
31
31
|
export declare const mockModelStepSchema: z.ZodObject<{
|
|
32
|
-
toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
33
|
-
name: z.ZodString;
|
|
34
|
-
id: z.ZodOptional<z.ZodString>;
|
|
35
|
-
args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
36
|
-
rawArgs: z.ZodOptional<z.ZodString>;
|
|
37
|
-
}, z.core.$strict>>>;
|
|
38
|
-
finishReason: z.ZodOptional<z.ZodEnum<{
|
|
39
|
-
length: "length";
|
|
40
|
-
content_filter: "content_filter";
|
|
41
|
-
}>>;
|
|
42
|
-
error: z.ZodOptional<z.ZodObject<{
|
|
43
|
-
status: z.ZodDefault<z.ZodNumber>;
|
|
44
|
-
message: z.ZodDefault<z.ZodString>;
|
|
45
|
-
}, z.core.$strict>>;
|
|
46
|
-
times: z.ZodOptional<z.ZodNumber>;
|
|
47
32
|
text: z.ZodOptional<z.ZodString>;
|
|
48
33
|
sample: z.ZodOptional<z.ZodEnum<{
|
|
49
|
-
scene: "scene";
|
|
50
34
|
critique: "critique";
|
|
51
|
-
outline: "outline";
|
|
52
35
|
markdown: "markdown";
|
|
36
|
+
outline: "outline";
|
|
37
|
+
scene: "scene";
|
|
53
38
|
}>>;
|
|
54
39
|
lorem: z.ZodOptional<z.ZodObject<{
|
|
55
40
|
words: z.ZodNumber;
|
|
@@ -60,32 +45,32 @@ export declare const mockModelStepSchema: z.ZodObject<{
|
|
|
60
45
|
delayMs: z.ZodOptional<z.ZodNumber>;
|
|
61
46
|
chunkSize: z.ZodOptional<z.ZodNumber>;
|
|
62
47
|
chunkDelayMs: z.ZodOptional<z.ZodNumber>;
|
|
48
|
+
toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
49
|
+
name: z.ZodString;
|
|
50
|
+
id: z.ZodOptional<z.ZodString>;
|
|
51
|
+
args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
52
|
+
rawArgs: z.ZodOptional<z.ZodString>;
|
|
53
|
+
}, z.core.$strict>>>;
|
|
54
|
+
finishReason: z.ZodOptional<z.ZodEnum<{
|
|
55
|
+
content_filter: "content_filter";
|
|
56
|
+
length: "length";
|
|
57
|
+
}>>;
|
|
58
|
+
error: z.ZodOptional<z.ZodObject<{
|
|
59
|
+
status: z.ZodDefault<z.ZodNumber>;
|
|
60
|
+
message: z.ZodDefault<z.ZodString>;
|
|
61
|
+
}, z.core.$strict>>;
|
|
62
|
+
times: z.ZodOptional<z.ZodNumber>;
|
|
63
63
|
}, z.core.$strict>;
|
|
64
64
|
export type MockModelStep = z.infer<typeof mockModelStepSchema>;
|
|
65
65
|
export declare const mockModelScriptSchema: z.ZodObject<{
|
|
66
66
|
match: z.ZodOptional<z.ZodString>;
|
|
67
67
|
steps: z.ZodArray<z.ZodObject<{
|
|
68
|
-
toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
69
|
-
name: z.ZodString;
|
|
70
|
-
id: z.ZodOptional<z.ZodString>;
|
|
71
|
-
args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
72
|
-
rawArgs: z.ZodOptional<z.ZodString>;
|
|
73
|
-
}, z.core.$strict>>>;
|
|
74
|
-
finishReason: z.ZodOptional<z.ZodEnum<{
|
|
75
|
-
length: "length";
|
|
76
|
-
content_filter: "content_filter";
|
|
77
|
-
}>>;
|
|
78
|
-
error: z.ZodOptional<z.ZodObject<{
|
|
79
|
-
status: z.ZodDefault<z.ZodNumber>;
|
|
80
|
-
message: z.ZodDefault<z.ZodString>;
|
|
81
|
-
}, z.core.$strict>>;
|
|
82
|
-
times: z.ZodOptional<z.ZodNumber>;
|
|
83
68
|
text: z.ZodOptional<z.ZodString>;
|
|
84
69
|
sample: z.ZodOptional<z.ZodEnum<{
|
|
85
|
-
scene: "scene";
|
|
86
70
|
critique: "critique";
|
|
87
|
-
outline: "outline";
|
|
88
71
|
markdown: "markdown";
|
|
72
|
+
outline: "outline";
|
|
73
|
+
scene: "scene";
|
|
89
74
|
}>>;
|
|
90
75
|
lorem: z.ZodOptional<z.ZodObject<{
|
|
91
76
|
words: z.ZodNumber;
|
|
@@ -96,6 +81,21 @@ export declare const mockModelScriptSchema: z.ZodObject<{
|
|
|
96
81
|
delayMs: z.ZodOptional<z.ZodNumber>;
|
|
97
82
|
chunkSize: z.ZodOptional<z.ZodNumber>;
|
|
98
83
|
chunkDelayMs: z.ZodOptional<z.ZodNumber>;
|
|
84
|
+
toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
85
|
+
name: z.ZodString;
|
|
86
|
+
id: z.ZodOptional<z.ZodString>;
|
|
87
|
+
args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
|
|
88
|
+
rawArgs: z.ZodOptional<z.ZodString>;
|
|
89
|
+
}, z.core.$strict>>>;
|
|
90
|
+
finishReason: z.ZodOptional<z.ZodEnum<{
|
|
91
|
+
content_filter: "content_filter";
|
|
92
|
+
length: "length";
|
|
93
|
+
}>>;
|
|
94
|
+
error: z.ZodOptional<z.ZodObject<{
|
|
95
|
+
status: z.ZodDefault<z.ZodNumber>;
|
|
96
|
+
message: z.ZodDefault<z.ZodString>;
|
|
97
|
+
}, z.core.$strict>>;
|
|
98
|
+
times: z.ZodOptional<z.ZodNumber>;
|
|
99
99
|
}, z.core.$strict>>;
|
|
100
100
|
}, z.core.$strict>;
|
|
101
101
|
export type MockModelScript = z.infer<typeof mockModelScriptSchema>;
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
import { faultOf, sessionForgotten } from "./fault.js";
|
|
2
|
+
import { Session } from "./session.js";
|
|
3
|
+
const MAX_LIST_PAGES = 100;
|
|
4
|
+
const CANCELLED = Symbol("cancelled");
|
|
5
|
+
/** A start that failed; calls within `failFastMs` get the same answer without trying again. */
|
|
6
|
+
class StartFailure extends Error {
|
|
7
|
+
fault;
|
|
8
|
+
constructor(fault) {
|
|
9
|
+
super(fault.message);
|
|
10
|
+
this.fault = fault;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
/** The host's signal and one deadline, as one signal, with the cause of whichever fired first. */
|
|
14
|
+
function control(host, timeoutMs) {
|
|
15
|
+
const own = new AbortController();
|
|
16
|
+
let cause;
|
|
17
|
+
const fire = (why) => {
|
|
18
|
+
cause ??= why;
|
|
19
|
+
own.abort();
|
|
20
|
+
};
|
|
21
|
+
const onHost = () => fire("host");
|
|
22
|
+
if (host?.aborted)
|
|
23
|
+
fire("host");
|
|
24
|
+
else
|
|
25
|
+
host?.addEventListener("abort", onHost, { once: true });
|
|
26
|
+
const timer = timeoutMs === undefined ? undefined : setTimeout(() => fire("timeout"), timeoutMs);
|
|
27
|
+
const cancelled = new Promise((_, reject) => {
|
|
28
|
+
if (own.signal.aborted)
|
|
29
|
+
reject(CANCELLED);
|
|
30
|
+
else
|
|
31
|
+
own.signal.addEventListener("abort", () => reject(CANCELLED), { once: true });
|
|
32
|
+
});
|
|
33
|
+
cancelled.catch(() => { });
|
|
34
|
+
return {
|
|
35
|
+
signal: own.signal,
|
|
36
|
+
get cause() {
|
|
37
|
+
return cause;
|
|
38
|
+
},
|
|
39
|
+
race: (work) => Promise.race([work, cancelled]),
|
|
40
|
+
dispose() {
|
|
41
|
+
clearTimeout(timer);
|
|
42
|
+
host?.removeEventListener("abort", onHost);
|
|
43
|
+
},
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
export function createMcpClient(options) {
|
|
47
|
+
const connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
|
|
48
|
+
const idleCloseMs = options.idleCloseMs ?? 5 * 60_000;
|
|
49
|
+
const failFastMs = options.failFastMs ?? 10_000;
|
|
50
|
+
const maxReplyBytes = options.maxReplyBytes ?? 10 * 1024 * 1024;
|
|
51
|
+
const cfg = {
|
|
52
|
+
clientInfo: options.clientInfo,
|
|
53
|
+
maxReplyBytes,
|
|
54
|
+
// Passed explicitly so the SDK never falls back to a global the host did not choose.
|
|
55
|
+
fetch: options.fetch ?? ((input, init) => fetch(input, init)),
|
|
56
|
+
...(options.onEvent ? { onEvent: options.onEvent } : {}),
|
|
57
|
+
};
|
|
58
|
+
const entries = new Map();
|
|
59
|
+
function entryFor(key) {
|
|
60
|
+
let entry = entries.get(key);
|
|
61
|
+
if (!entry) {
|
|
62
|
+
entry = {};
|
|
63
|
+
entries.set(key, entry);
|
|
64
|
+
}
|
|
65
|
+
return entry;
|
|
66
|
+
}
|
|
67
|
+
/** The key's live session, started if there is none. Callers that arrive during a start share it. */
|
|
68
|
+
function acquire(server) {
|
|
69
|
+
const entry = entryFor(server.key);
|
|
70
|
+
if (entry.session && !entry.session.ended)
|
|
71
|
+
return Promise.resolve(entry.session);
|
|
72
|
+
if (entry.starting)
|
|
73
|
+
return entry.starting;
|
|
74
|
+
if (entry.failed) {
|
|
75
|
+
if (Date.now() - entry.failed.at < failFastMs)
|
|
76
|
+
return Promise.reject(entry.failed.failure);
|
|
77
|
+
entry.failed = undefined;
|
|
78
|
+
}
|
|
79
|
+
const starting = Session.open(server, cfg, { timeoutMs: connectTimeoutMs, idleCloseMs }).then((session) => {
|
|
80
|
+
entry.starting = undefined;
|
|
81
|
+
entry.session = session;
|
|
82
|
+
session.onEnded = () => {
|
|
83
|
+
if (entry.session === session)
|
|
84
|
+
entry.session = undefined;
|
|
85
|
+
};
|
|
86
|
+
return session;
|
|
87
|
+
}, (error) => {
|
|
88
|
+
entry.starting = undefined;
|
|
89
|
+
entry.failed = { at: Date.now(), failure: new StartFailure(faultOf(error, "start")) };
|
|
90
|
+
throw entry.failed.failure;
|
|
91
|
+
});
|
|
92
|
+
starting.catch(() => { }); // every caller may have given up; the failure is still recorded
|
|
93
|
+
entry.starting = starting;
|
|
94
|
+
return starting;
|
|
95
|
+
}
|
|
96
|
+
const unreachable = (fault, sent, ms) => ({
|
|
97
|
+
kind: "unreachable",
|
|
98
|
+
...fault,
|
|
99
|
+
sent,
|
|
100
|
+
ms,
|
|
101
|
+
});
|
|
102
|
+
const aborted = (sent, ms) => ({ kind: "aborted", sent, ms });
|
|
103
|
+
/** The outcome of an acquire that did not give a session. */
|
|
104
|
+
function startOutcome(error, ctl, ms) {
|
|
105
|
+
if (error === CANCELLED) {
|
|
106
|
+
if (ctl.cause === "host")
|
|
107
|
+
return aborted(false, ms);
|
|
108
|
+
return unreachable({ reason: "call_timeout", message: "timed out before the session was ready" }, false, ms);
|
|
109
|
+
}
|
|
110
|
+
if (error instanceof StartFailure)
|
|
111
|
+
return unreachable(error.fault, false, ms);
|
|
112
|
+
throw error;
|
|
113
|
+
}
|
|
114
|
+
/** The outcome of one request, decided from the raw message off the wire when there is one. */
|
|
115
|
+
function outcomeOf(exchange, ctl, ms) {
|
|
116
|
+
const { raw } = exchange;
|
|
117
|
+
if (raw && "result" in raw)
|
|
118
|
+
return { kind: "answered", isError: raw.result.isError === true, reply: raw.result, ms };
|
|
119
|
+
if (raw) {
|
|
120
|
+
const { code, message } = raw.error;
|
|
121
|
+
return {
|
|
122
|
+
kind: "rejected",
|
|
123
|
+
code: typeof code === "number" ? code : 0,
|
|
124
|
+
message: typeof message === "string" ? message : "",
|
|
125
|
+
reply: raw.error,
|
|
126
|
+
ms,
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
if (exchange.tooLarge !== undefined)
|
|
130
|
+
return { kind: "too_large", bytes: exchange.tooLarge, limit: maxReplyBytes, ms };
|
|
131
|
+
if (ctl.cause === "host")
|
|
132
|
+
return aborted(exchange.sent, ms);
|
|
133
|
+
if (ctl.cause === "timeout")
|
|
134
|
+
return unreachable({ reason: "call_timeout", message: "the call timed out" }, exchange.sent, ms);
|
|
135
|
+
if (exchange.lost)
|
|
136
|
+
return unreachable({ reason: "disconnected", message: "the connection ended" }, exchange.sent, ms);
|
|
137
|
+
if (exchange.error === undefined)
|
|
138
|
+
return unreachable({
|
|
139
|
+
reason: "bad_reply",
|
|
140
|
+
message: "the SDK returned a reply the client could not read off the wire",
|
|
141
|
+
}, exchange.sent, ms);
|
|
142
|
+
return unreachable(faultOf(exchange.error, "call"), exchange.sent, ms);
|
|
143
|
+
}
|
|
144
|
+
/** Whether a request can be sent again on a new session without risking a second run. */
|
|
145
|
+
function resendable(exchange, session, ctl) {
|
|
146
|
+
if (exchange.raw || exchange.tooLarge !== undefined || ctl.cause)
|
|
147
|
+
return false;
|
|
148
|
+
if (!exchange.sent && session.ended)
|
|
149
|
+
return true;
|
|
150
|
+
return session.hasServerSession && sessionForgotten(exchange.error);
|
|
151
|
+
}
|
|
152
|
+
/** Runs `request` on the key's session, once more on a new session when the first one is gone. */
|
|
153
|
+
async function viaSession(server, ctl, t0, request) {
|
|
154
|
+
for (let attempt = 0;; attempt++) {
|
|
155
|
+
let session;
|
|
156
|
+
try {
|
|
157
|
+
session = await ctl.race(acquire(server));
|
|
158
|
+
}
|
|
159
|
+
catch (error) {
|
|
160
|
+
return { start: startOutcome(error, ctl, Math.round(performance.now() - t0)) };
|
|
161
|
+
}
|
|
162
|
+
const exchange = await request(session);
|
|
163
|
+
if (attempt === 0 && resendable(exchange, session, ctl)) {
|
|
164
|
+
void session.close("forgotten");
|
|
165
|
+
continue;
|
|
166
|
+
}
|
|
167
|
+
return { exchange, session };
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
return {
|
|
171
|
+
async call(server, { tool, arguments: args }, { signal, timeoutMs }) {
|
|
172
|
+
const t0 = performance.now();
|
|
173
|
+
const ctl = control(signal, timeoutMs);
|
|
174
|
+
try {
|
|
175
|
+
// A fresh copy of the arguments per attempt: its identity is how the reply is matched to this call.
|
|
176
|
+
const done = await viaSession(server, ctl, t0, (session) => session.call(tool.listed, tool.name, { ...args }, ctl.signal));
|
|
177
|
+
if ("start" in done)
|
|
178
|
+
return done.start;
|
|
179
|
+
return outcomeOf(done.exchange, ctl, Math.round(performance.now() - t0));
|
|
180
|
+
}
|
|
181
|
+
finally {
|
|
182
|
+
ctl.dispose();
|
|
183
|
+
}
|
|
184
|
+
},
|
|
185
|
+
async list(server, opts) {
|
|
186
|
+
const t0 = performance.now();
|
|
187
|
+
const ctl = control(opts?.signal, opts?.timeoutMs ?? connectTimeoutMs);
|
|
188
|
+
const ms = () => Math.round(performance.now() - t0);
|
|
189
|
+
try {
|
|
190
|
+
const tools = [];
|
|
191
|
+
let cursor;
|
|
192
|
+
for (let page = 0; page < MAX_LIST_PAGES; page++) {
|
|
193
|
+
const done = await viaSession(server, ctl, t0, (session) => session.listPage(cursor, ctl.signal));
|
|
194
|
+
if ("start" in done)
|
|
195
|
+
return done.start;
|
|
196
|
+
const outcome = outcomeOf(done.exchange, ctl, ms());
|
|
197
|
+
if (outcome.kind === "rejected" ||
|
|
198
|
+
outcome.kind === "unreachable" ||
|
|
199
|
+
outcome.kind === "aborted")
|
|
200
|
+
return outcome;
|
|
201
|
+
if (outcome.kind === "too_large")
|
|
202
|
+
return unreachable({
|
|
203
|
+
reason: "bad_reply",
|
|
204
|
+
message: `a tool list page is larger than ${maxReplyBytes} bytes`,
|
|
205
|
+
}, true, ms());
|
|
206
|
+
const { tools: listed, nextCursor } = outcome.reply;
|
|
207
|
+
if (!Array.isArray(listed))
|
|
208
|
+
return unreachable({ reason: "bad_reply", message: "the tool list has no tools array" }, true, ms());
|
|
209
|
+
tools.push(...listed);
|
|
210
|
+
if (typeof nextCursor !== "string" || nextCursor === "") {
|
|
211
|
+
const { session } = done;
|
|
212
|
+
return {
|
|
213
|
+
server: session.server,
|
|
214
|
+
protocolVersion: session.protocolVersion,
|
|
215
|
+
...(session.instructions === undefined ? {} : { instructions: session.instructions }),
|
|
216
|
+
tools,
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
cursor = nextCursor;
|
|
220
|
+
}
|
|
221
|
+
return unreachable({ reason: "bad_reply", message: `the tool list has more than ${MAX_LIST_PAGES} pages` }, true, ms());
|
|
222
|
+
}
|
|
223
|
+
finally {
|
|
224
|
+
ctl.dispose();
|
|
225
|
+
}
|
|
226
|
+
},
|
|
227
|
+
async check(server, opts) {
|
|
228
|
+
const t0 = performance.now();
|
|
229
|
+
const ms = () => Math.round(performance.now() - t0);
|
|
230
|
+
const timeoutMs = opts?.timeoutMs ?? connectTimeoutMs;
|
|
231
|
+
const live = entries.get(server.key)?.session;
|
|
232
|
+
if (live && !live.ended) {
|
|
233
|
+
// Half the time for the ping; the handshake after it gets what is left, so the whole
|
|
234
|
+
// check stays within `timeoutMs`.
|
|
235
|
+
const ctl = control(opts?.signal, timeoutMs / 2);
|
|
236
|
+
try {
|
|
237
|
+
const { raw } = await live.ping(ctl.signal);
|
|
238
|
+
// A server without ping answers with an error, which still shows the session is alive.
|
|
239
|
+
if (raw)
|
|
240
|
+
return { kind: "reachable", server: live.server, ms: ms() };
|
|
241
|
+
if (ctl.cause === "host")
|
|
242
|
+
return aborted(true, ms());
|
|
243
|
+
}
|
|
244
|
+
finally {
|
|
245
|
+
ctl.dispose();
|
|
246
|
+
}
|
|
247
|
+
// No reply to the ping: calls on the live session are left alone, and the answer comes
|
|
248
|
+
// from a handshake of its own.
|
|
249
|
+
}
|
|
250
|
+
const ctl = control(opts?.signal);
|
|
251
|
+
try {
|
|
252
|
+
const session = await Session.open(server, cfg, {
|
|
253
|
+
signal: ctl.signal,
|
|
254
|
+
timeoutMs: Math.max(1, timeoutMs - ms()),
|
|
255
|
+
idleCloseMs: 0,
|
|
256
|
+
});
|
|
257
|
+
await session.close();
|
|
258
|
+
return { kind: "reachable", server: session.server, ms: ms() };
|
|
259
|
+
}
|
|
260
|
+
catch (error) {
|
|
261
|
+
if (ctl.cause === "host")
|
|
262
|
+
return aborted(false, ms());
|
|
263
|
+
return unreachable(faultOf(error, "start"), false, ms());
|
|
264
|
+
}
|
|
265
|
+
finally {
|
|
266
|
+
ctl.dispose();
|
|
267
|
+
}
|
|
268
|
+
},
|
|
269
|
+
async close(key) {
|
|
270
|
+
const targets = key === undefined ? [...entries.keys()] : [key];
|
|
271
|
+
await Promise.all(targets.map(async (target) => {
|
|
272
|
+
const entry = entries.get(target);
|
|
273
|
+
entries.delete(target);
|
|
274
|
+
const session = (await entry?.starting?.catch(() => undefined)) ?? entry?.session;
|
|
275
|
+
await session?.close();
|
|
276
|
+
}));
|
|
277
|
+
},
|
|
278
|
+
};
|
|
279
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { ContentPart, JsonObject } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* What a model can read from a tool's raw reply. Blocks it cannot carry become a line saying what
|
|
4
|
+
* was left out. A reply with only structured content becomes that JSON as text. Cutting a long
|
|
5
|
+
* reply to size and storing media are the host's.
|
|
6
|
+
*/
|
|
7
|
+
export declare function toContent(reply: JsonObject): ContentPart[];
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
2
|
+
const str = (value) => typeof value === "string" ? value : undefined;
|
|
3
|
+
const text = (value) => ({ type: "text", text: value });
|
|
4
|
+
function block(item) {
|
|
5
|
+
if (!isObject(item))
|
|
6
|
+
return text("[a content block that is not an object was left out]");
|
|
7
|
+
const type = str(item.type);
|
|
8
|
+
switch (type) {
|
|
9
|
+
case "text": {
|
|
10
|
+
const value = str(item.text);
|
|
11
|
+
return value === undefined ? text('[a "text" block with no text was left out]') : text(value);
|
|
12
|
+
}
|
|
13
|
+
case "image": {
|
|
14
|
+
const data = str(item.data);
|
|
15
|
+
const mediaType = str(item.mimeType);
|
|
16
|
+
if (data === undefined || mediaType === undefined)
|
|
17
|
+
return text('[an "image" block with no data or type was left out]');
|
|
18
|
+
return { type: "media", mediaType, source: { data } };
|
|
19
|
+
}
|
|
20
|
+
case "audio":
|
|
21
|
+
return text(`[audio${typeNote(item.mimeType)} was left out]`);
|
|
22
|
+
case "resource_link": {
|
|
23
|
+
const name = str(item.name) ?? "(unnamed)";
|
|
24
|
+
return text(`${name}: ${str(item.uri) ?? "(no uri)"}`);
|
|
25
|
+
}
|
|
26
|
+
case "resource": {
|
|
27
|
+
const resource = item.resource;
|
|
28
|
+
if (isObject(resource)) {
|
|
29
|
+
const embedded = str(resource.text);
|
|
30
|
+
if (embedded !== undefined)
|
|
31
|
+
return text(embedded);
|
|
32
|
+
return text(`[binary resource ${str(resource.uri) ?? "(no uri)"}${typeNote(resource.mimeType)} was left out]`);
|
|
33
|
+
}
|
|
34
|
+
return text('[a "resource" block with no resource was left out]');
|
|
35
|
+
}
|
|
36
|
+
default:
|
|
37
|
+
return text(`[a content block of type ${JSON.stringify(type ?? null)} was left out]`);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
function typeNote(mimeType) {
|
|
41
|
+
const value = str(mimeType);
|
|
42
|
+
return value === undefined ? "" : ` (${value})`;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* What a model can read from a tool's raw reply. Blocks it cannot carry become a line saying what
|
|
46
|
+
* was left out. A reply with only structured content becomes that JSON as text. Cutting a long
|
|
47
|
+
* reply to size and storing media are the host's.
|
|
48
|
+
*/
|
|
49
|
+
export function toContent(reply) {
|
|
50
|
+
const parts = Array.isArray(reply.content) ? reply.content.map(block) : [];
|
|
51
|
+
if (parts.length === 0 && reply.structuredContent !== undefined)
|
|
52
|
+
return [text(JSON.stringify(reply.structuredContent))];
|
|
53
|
+
return parts;
|
|
54
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Unreachable } from "./types.js";
|
|
2
|
+
export type Fault = Pick<Unreachable, "reason" | "httpStatus" | "message">;
|
|
3
|
+
/** What the SDK or the network threw when no reply arrived, as an `unreachable` reason. */
|
|
4
|
+
export declare function faultOf(error: unknown, phase: "start" | "call"): Fault;
|
|
5
|
+
/** The server said it does not know this session (a 404, or a 400 "not initialized"): the call did not run. */
|
|
6
|
+
export declare function sessionForgotten(error: unknown): boolean;
|