@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 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.filter((m) => m.role === "system").flatMap((m) => m.content));
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
- if (marked[index].role !== "user")
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. The installed SDK types `cache_write_tokens` but not
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
- /** Anthropic client options that default from the environment, set to "none". */
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
- /** Anthropic client options that default from the environment, set to "none". */
100
- export const ANTHROPIC_ENV_OPTOUT = { authToken: null, webhookKey: null };
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 interface Message {
175
- role: "system" | "user" | "assistant" | "tool";
176
- content: ContentPart[];
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
- * NOTE: Anthropic docs additionally list `model_context_window_exceeded` but the
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 { ContentPart, MediaPart, Message, ProviderOptions, TextPart } from "../domain/index.js";
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: ContentPart[]): Message;
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,2 @@
1
+ import type { McpClient, McpClientOptions } from "./types.js";
2
+ export declare function createMcpClient(options: McpClientOptions): McpClient;
@@ -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;