@orkestrel/agent 0.0.21 → 0.0.23

package/dist/src/core/index.cjs

@@ -96,6 +96,56 @@ var MESSAGE_TOKEN_OVERHEAD = 4;
 * exact count.
 */
 var IMAGE_TOKEN_ESTIMATE = 512;
+/**
+* Holds the default provider deadline in milliseconds — `120_000`, the wall-clock bound a call
+* runs under when `AgentProviderInput.timeout` is omitted, folded with the caller's signal so
+* whichever trips first cancels the call.
+*/
+var DEFAULT_PROVIDER_TIMEOUT = 12e4;
+/**
+* Bounds the decoded error excerpt's input in bytes — `2048`, the leading bytes of a non-OK
+* response body handed to the decoder before the read cancels the remainder, so a `ProviderError`
+* message never carries a longer excerpt.
+*/
+var MAX_ERROR_BODY_LENGTH = 2048;
+/**
+* Holds the default relay request limit in bytes — `1_048_576`, the byte budget a relay applies
+* to an inbound body when `RelayOptions.limit` is omitted, refusing a body that reaches it.
+*/
+var DEFAULT_RELAY_LIMIT = 1048576;
+/**
+* Names the relay's newline-delimited JSON content type — `'application/x-ndjson; charset=utf-8'`,
+* the header a relay response carries beside `cache-control: no-store`.
+*/
+var RELAY_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+/**
+* Names the public message for an unexpected upstream relay failure — `'relay provider failed'`,
+* the fixed text every `error` frame carries, so an upstream failure's own message never reaches
+* the browser.
+*/
+var RELAY_PROVIDER_MESSAGE = "relay provider failed";
+/**
+* Names the status a relay answers when the `authorize` callback returns anything but `true` or throws —
+* `401`, carried with no body and reaching the browser as a `ProviderError` with the `HTTP` code.
+*/
+var UNAUTHORIZED_RELAY_STATUS = 401;
+/**
+* Names the status a relay answers when the upstream provider call cannot be constructed — `502`,
+* carried with no body after `provider.stream` was entered and threw before returning its
+* iterator.
+*/
+var UPSTREAM_RELAY_STATUS = 502;
+/**
+* Names the status a relay answers for a body that is missing, unreadable, or rejected by
+* `providerRequestContract` — `400`, carried with no body and reaching the browser as a
+* `ProviderError` with the `HTTP` code.
+*/
+var INVALID_RELAY_STATUS = 400;
+/**
+* Names the status a relay answers for a request body at or above its byte budget — `413`,
+* carried with no body and answered for an aborted inbound read as well.
+*/
+var OVERSIZED_RELAY_STATUS = 413;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -107,14 +157,16 @@ var IMAGE_TOKEN_ESTIMATE = 512;
 * Lets a caller recover the partial content (and any tool calls / usage seen so far)
 * on cancellation: `catch` the throw, narrow with {@link isProviderAbortError}, and
 * read `partial`. `code` is the machine-readable condition (`'ABORT'` — the only one this
-* error reports), so a `catch` branches on it rather than on the message string.
+* error reports), so a `catch` branches on it rather than on the message string. `cause`
+* holds the failure the cancel superseded when a throw raced the abort — the wire decoder's
+* {@link ProviderError}, say — and is undefined when the cancel was the only failure.
 */
 var ProviderAbortError = class extends Error {
 	/** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
 	code = "ABORT";
 	partial;
-	constructor(partial) {
-		super("provider stream aborted");
+	constructor(partial, options) {
+		super("provider stream aborted", options);
 		this.name = "ProviderAbortError";
 		this.partial = partial;
 	}
@@ -275,6 +327,142 @@ var AgentError = class extends Error {
 function isAgentError(value) {
 	return value instanceof AgentError;
 }
+/**
+* Reports a coded provider failure with its HTTP status and underlying cause when available.
+*
+* @remarks
+* The provider base throws this error for a non-OK HTTP response, a missing response
+* body, or a missing settled result when strict assembly is enabled. Concrete wire
+* decoders also use it for malformed records and relayed provider failures.
+* `status` is present only for an `HTTP` failure; other codes leave it undefined.
+*/
+var ProviderError = class extends Error {
+	/** Names the machine-readable condition — `'HTTP'`: a non-OK response, including a relay refusing an oversized request with 413; `'PROTOCOL'`: a missing response body, a malformed wire record, or a strict stream with no settled result; `'PROVIDER'`: an upstream failure carried by a relay error record. */
+	code;
+	/** Holds the response status for an HTTP failure, or undefined for other codes. */
+	status;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "ProviderError";
+		this.code = code;
+		this.status = options?.status;
+	}
+};
+/**
+* Narrows a caught value to the provider failure class through instanceof.
+*
+* @param value - The caught value
+* @returns True if the value is a provider failure; false otherwise
+* @example
+* ```ts
+* isProviderError(new ProviderError('HTTP', 'unavailable', { status: 503 })) // true
+* ```
+*/
+function isProviderError(value) {
+	return value instanceof ProviderError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* Describes a tool call's JSON wire projection.
+*
+* @remarks
+* The wire is strictly narrower than the domain: non-JSON arguments are refused.
+* Calls carry only id, name, and arguments; execution context stays local.
+* The guard refuses every extra member; the contract parser drops extra members.
+*/
+var toolCallShape = (0, _orkestrel_contract.objectShape)({
+	id: (0, _orkestrel_contract.stringShape)(),
+	name: (0, _orkestrel_contract.stringShape)(),
+	arguments: (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.jsonShape)())
+});
+/**
+* Describes a conversation message's JSON wire projection.
+*
+* @remarks
+* The wire is strictly narrower than Message: non-JSON call arguments are refused,
+* and execution context stays local. The guard refuses extra members; the parser drops them.
+*/
+var messageShape = (0, _orkestrel_contract.objectShape)({
+	id: (0, _orkestrel_contract.stringShape)(),
+	role: (0, _orkestrel_contract.literalShape)([
+		"system",
+		"user",
+		"assistant",
+		"tool"
+	]),
+	content: (0, _orkestrel_contract.stringShape)(),
+	calls: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(toolCallShape)),
+	images: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.stringShape)()))
+});
+/**
+* Describes a provider request's JSON wire projection.
+*
+* @remarks
+* The wire is strictly narrower than ProviderRequest: non-JSON arguments, parameters,
+* or schema members are refused. Execution context stays local; the guard refuses
+* extra members, and the parser drops them.
+*/
+var providerRequestShape = (0, _orkestrel_contract.objectShape)({
+	messages: (0, _orkestrel_contract.arrayShape)(messageShape),
+	tools: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.objectShape)({
+		name: (0, _orkestrel_contract.stringShape)(),
+		description: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)()),
+		parameters: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.jsonShape)()))
+	}))),
+	options: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.objectShape)({
+		think: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)()),
+		schema: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.jsonShape)()))
+	}))
+});
+/**
+* Describes a provider result's JSON wire projection.
+*
+* @remarks
+* The wire is strictly narrower than ProviderResult: non-JSON call arguments are
+* refused. Execution context stays local; the guard refuses extra members, and the parser drops them.
+*/
+var providerResultShape = (0, _orkestrel_contract.objectShape)({
+	content: (0, _orkestrel_contract.stringShape)(),
+	thinking: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)()),
+	tools: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(toolCallShape)),
+	usage: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.objectShape)({
+		prompt: (0, _orkestrel_contract.numberShape)(),
+		completion: (0, _orkestrel_contract.numberShape)(),
+		total: (0, _orkestrel_contract.numberShape)()
+	}))
+});
+/**
+* Describes the channel-discriminated JSON relay wire projection.
+*
+* @remarks
+* The wire is strictly narrower than RelayFrame through its result and partial
+* fields: non-JSON arguments are refused. Execution context stays local; the guard
+* refuses extra members, and the parser drops them.
+*/
+var relayFrameShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.objectShape)({
+	channel: (0, _orkestrel_contract.literalShape)(["content", "thinking"]),
+	text: (0, _orkestrel_contract.stringShape)()
+}), (0, _orkestrel_contract.objectShape)({
+	channel: (0, _orkestrel_contract.literalShape)(["result"]),
+	result: providerResultShape
+}), (0, _orkestrel_contract.objectShape)({
+	channel: (0, _orkestrel_contract.literalShape)(["abort"]),
+	partial: providerResultShape
+}), (0, _orkestrel_contract.objectShape)({
+	channel: (0, _orkestrel_contract.literalShape)(["error"]),
+	message: (0, _orkestrel_contract.stringShape)()
+}));
+//#endregion
+//#region src/core/contracts.ts
+/** Validates and projects conversation messages at a JSON wire boundary. */
+var messageContract = (0, _orkestrel_contract.createContract)(messageShape);
+/** Validates and projects provider requests at a JSON wire boundary. */
+var providerRequestContract = (0, _orkestrel_contract.createContract)(providerRequestShape);
+/** Validates and projects provider results at a JSON wire boundary. */
+var providerResultContract = (0, _orkestrel_contract.createContract)(providerResultShape);
+/** Validates and projects channel-discriminated relay frames at a JSON wire boundary. */
+var relayFrameContract = (0, _orkestrel_contract.createContract)(relayFrameShape);
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -582,11 +770,13 @@ function sanitizeUsage(usage) {
 * @example
 * ```ts
 * joinThinking(undefined, 'first') // 'first'
+* joinThinking('', 'x') // 'x'
 * joinThinking('first', 'second') // 'first\n\nsecond'
 * ```
 */
 function joinThinking(running, next) {
-	return running === void 0 ? next : `${running}\n\n${next}`;
+	if (running === void 0 || running.length === 0) return next;
+	return next.length === 0 ? running : `${running}\n\n${next}`;
 }
 /**
 * Adds two {@link TokenUsage} values field by field — the running total an agent run keeps
@@ -943,6 +1133,133 @@ function intersectKeys(parent, child) {
 	const allowed = new Set(parent);
 	return child.filter((key) => allowed.has(key));
 }
+/**
+* Assembles a provider result with only populated optional fields.
+*
+* @param content - The authoritative answer
+* @param thinking - The joined reasoning
+* @param tools - The accumulated calls
+* @param usage - The reported token usage
+* @returns The assembled result
+* @example
+* ```ts
+* buildProviderResult('ok', '', [], undefined) // { content: 'ok' }
+* ```
+*/
+function buildProviderResult(content, thinking, tools, usage) {
+	return {
+		content,
+		...thinking.length === 0 ? {} : { thinking },
+		...tools.length === 0 ? {} : { tools },
+		...usage === void 0 ? {} : { usage }
+	};
+}
+/**
+* Reads a UTF-8 prefix of a byte stream and cancels its remainder.
+*
+* @remarks
+* The `limit` parameter bounds bytes passed to the decoder, including a partial final
+* character. An omitted limit reads to completion. A source may deliver a chunk larger
+* than the remaining limit; its unused bytes are discarded without decoding.
+* The read can overshoot by one source chunk. An abort leaves completion false.
+*
+* @param body - The readable byte stream
+* @param limit - The maximum byte prefix, or undefined for the complete stream
+* @param signal - The optional cancellation bound; abort returns the decoded prefix
+* @returns The decoded prefix and whether EOF occurred within the byte budget
+* @example
+* ```ts
+* import { readText } from '@orkestrel/agent'
+*
+* const body = new Response('answer').body
+* if (body !== null) await readText(body, 3) // { text: 'ans', complete: false }
+* ```
+*/
+async function readText(body, limit, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const cleanup = new AbortController();
+	let remaining = limit ?? Infinity;
+	let text = "";
+	let complete = false;
+	try {
+		signal?.addEventListener("abort", () => {
+			reader.cancel(signal.reason).catch(() => {});
+		}, {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (signal?.aborted) await reader.cancel(signal.reason).catch(() => {});
+		while (remaining > 0) {
+			if (signal?.aborted) break;
+			const step = await reader.read();
+			if (signal?.aborted) break;
+			if (step.done) {
+				complete = true;
+				break;
+			}
+			const bytes = step.value.subarray(0, remaining);
+			text += decoder.decode(bytes, { stream: true });
+			remaining -= bytes.byteLength;
+		}
+		return {
+			text: text + decoder.decode(),
+			complete
+		};
+	} finally {
+		cleanup.abort();
+		try {
+			await reader.cancel();
+		} catch {} finally {
+			reader.releaseLock();
+		}
+	}
+}
+/**
+* Decodes UTF-8 chunks with a final flush and releases the stream on every exit.
+*
+* @param body - The readable byte stream
+* @param signal - The optional cancellation bound; abort ends iteration without further chunks
+* @returns Decoded text chunks, including a held decoder tail
+* @example
+* ```ts
+* const body = new Response('answer').body
+* if (body !== null) for await (const chunk of readChunks(body)) render(chunk)
+* ```
+*/
+async function* readChunks(body, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const cleanup = new AbortController();
+	try {
+		signal?.addEventListener("abort", () => {
+			reader.cancel(signal.reason).catch(() => {});
+		}, {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (signal?.aborted) {
+			await reader.cancel(signal.reason).catch(() => {});
+			return;
+		}
+		for (;;) {
+			const step = await reader.read();
+			if (signal?.aborted) return;
+			if (step.done) break;
+			const chunk = decoder.decode(step.value, { stream: true });
+			if (chunk.length > 0) yield chunk;
+		}
+		const tail = decoder.decode();
+		if (tail.length > 0) yield tail;
+	} finally {
+		cleanup.abort();
+		try {
+			await reader.cancel();
+		} catch {} finally {
+			reader.releaseLock();
+		}
+	}
+}
 //#endregion
 //#region src/core/conversations/Conversation.ts
 /**
@@ -1815,7 +2132,7 @@ var Agent = class {
 			} catch (error) {
 				if (abort.signal.aborted) {
 					if (isProviderAbortError(error)) {
-						if (error.partial.thinking !== void 0) thinking = joinThinking(thinking, error.partial.thinking);
+						if (error.partial.thinking !== void 0 && error.partial.thinking.length > 0) thinking = joinThinking(thinking, error.partial.thinking);
 						if (error.partial.usage !== void 0) {
 							const abortUsage = sanitizeUsage(error.partial.usage);
 							budget?.consume({
@@ -1848,13 +2165,19 @@ var Agent = class {
 				};
 			}
 			if (result.tools !== void 0 && result.tools.length > 0) {
+				const authorization = this.#authorize(result.tools);
+				if (abort.signal.aborted) {
+					partial = true;
+					broke = true;
+					break;
+				}
 				const assistant = this.#context.messages.add({
 					role: "assistant",
 					content: result.content,
 					calls: result.tools
 				});
 				messages.push(assistant);
-				const results = await this.#authorize(tools, result.tools);
+				const results = await this.#dispatch(tools, result.tools, abort.signal, authorization);
 				for (let index = 0; index < result.tools.length; index += 1) {
 					const call = result.tools[index];
 					const outcomeResult = results[index];
@@ -1914,8 +2237,8 @@ var Agent = class {
 		messages.splice(0, messages.length, ...this.#context.build(this.#provider.format));
 		return false;
 	}
-	async #authorize(tools, calls) {
-		if (this.#authority === void 0) return tools.execute(calls);
+	#authorize(calls) {
+		if (this.#authority === void 0) return void 0;
 		const authority = this.#authority;
 		const allowed = [];
 		const denials = /* @__PURE__ */ new Map();
@@ -1935,7 +2258,15 @@ var Agent = class {
 				this.#emitter.emit("deny", call, decision.reason);
 			}
 		}
-		const executed = allowed.length > 0 ? await tools.execute(allowed) : [];
+		return {
+			allowed,
+			denials
+		};
+	}
+	async #dispatch(tools, calls, signal, authorization) {
+		if (authorization === void 0) return tools.execute(calls, { signal });
+		const { allowed, denials } = authorization;
+		const executed = allowed.length > 0 ? await tools.execute(allowed, { signal }) : [];
 		const byId = new Map(denials);
 		for (const result of executed) byId.set(result.id, result);
 		return calls.map((call) => byId.get(call.id) ?? denyCall(call, void 0));
@@ -2126,41 +2457,32 @@ var Authority = class {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Checks whether an `unknown` is structurally a {@link Message} record — the per-message step of
-* the {@link isConversationSnapshot} and {@link isSection} read-boundary narrows, where a present
-* `calls` must be an array of valid {@link import('@orkestrel/tool').ToolCall}s. Total, never
-* throwing, and never an assertion; the conversation analogue of
-* {@link import('@orkestrel/workspace').isFile}.
+* Checks whether a value satisfies the domain conversation-message contract.
 *
 * @remarks
-* A total guard (it never throws — adversarial input returns `false`). It checks the message's
-* shape: a record with a `string` `id`, a `string` `role`, a `string` `content`, and — when present
-* — a `calls` array every element of which is a valid
-* {@link import('@orkestrel/tool').ToolCall} ({@link isToolCall} — the
-* fail-closed deepening: a tampered `calls` element rejects the message, so the snapshot
-* reads back as absent rather than replaying a malformed call) and an `images` that is an array
-* (an absent optional passes). The `role` is left as a broad `string` here (an open
-* {@link import('./types.js').MessageRole}, so any storage-read role string is accepted
-* defensively rather than rejected against the current literal set). Enough to safely impose the
-* {@link Message} type at
-* a storage boundary without a cast.
-*
-* @param value - The value to test (one element of a snapshot's `messages` / a section's `messages`)
-* @returns True if `value` has the structural shape of a {@link Message}; false otherwise
+* Roles belong to MessageRole and image elements are strings. Tool arguments may
+* carry non-JSON values, as the domain type permits; the message wire contract is
+* narrower. Unreadable fields and hostile inputs return false.
 *
+* @param value - The unknown message candidate
+* @returns True if the domain message fields are valid; false otherwise
 * @example
 * ```ts
 * isMessage({ id: '1', role: 'user', content: 'hi' }) // true
-* isMessage({ id: '1', role: 'assistant', content: '', calls: [] }) // true
-* isMessage({ id: '1', role: 'user' }) // false (missing content)
-* isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
+* isMessage({ id: '1', role: 'other', content: '' }) // false
+* isMessage({ id: '1', role: 'user', content: '', images: [1] }) // false
 * ```
 */
 function isMessage(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	if (!(0, _orkestrel_contract.isString)(value.id) || !(0, _orkestrel_contract.isString)(value.role) || !(0, _orkestrel_contract.isString)(value.content)) return false;
-	if (value.calls !== void 0 && !((0, _orkestrel_contract.isArray)(value.calls) && value.calls.every(_orkestrel_tool.isToolCall))) return false;
-	return value.images === void 0 || (0, _orkestrel_contract.isArray)(value.images);
+	const checked = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		const { id, role, content, calls, images } = value;
+		if (!(0, _orkestrel_contract.isString)(id) || !(0, _orkestrel_contract.isString)(content)) return false;
+		if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") return false;
+		if (calls !== void 0 && !(0, _orkestrel_contract.arrayOf)(_orkestrel_tool.isToolCall)(calls)) return false;
+		return images === void 0 || (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(images);
+	});
+	return checked.success && checked.value;
 }
 /**
 * Checks whether an `unknown` is structurally a {@link Section} record — a `string` `id` and
@@ -2386,6 +2708,494 @@ var MemoryConversationStore = class {
 	}
 };
 //#endregion
+//#region src/core/AgentProvider.ts
+/**
+* Implements bounded HTTP streaming and result assembly behind concrete wire seams.
+*
+* @remarks
+* Every call owns its parser, splitter, deadline, and accumulation. Success bodies
+* have no size limit. A qwen3 implicit-open reclassification corrects the final
+* content while content deltas already yielded cannot be recalled. A subclass fills
+* `name`, `frame`, `body`, `read`, and `finish`; the constructor takes the `split`
+* and `strict` switches to control reasoning separation and settled-result requirements.
+*
+* @example Writing a provider for a new wire
+* ```ts
+* import type {
+* 	ProviderIncrement,
+* 	ProviderOptions,
+* 	ProviderParserInterface,
+* 	ProviderRequest,
+* } from '@orkestrel/agent'
+* import { AgentProvider } from '@orkestrel/agent'
+*
+* class TextFrame implements ProviderParserInterface<string> {
+* 	parse(chunk: string): readonly string[] {
+* 		return [chunk]
+* 	}
+* 	clear(): void {} // Raw text retains no framing state.
+* }
+*
+* interface TextOptions extends ProviderOptions {
+* 	readonly url: string
+* }
+*
+* class TextProvider extends AgentProvider<string> {
+* 	readonly name = 'text'
+* 	constructor(options: TextOptions) {
+* 		super({ ...options, path: '/generate' })
+* 	}
+* 	frame(): ProviderParserInterface<string> {
+* 		return new TextFrame()
+* 	}
+* 	body(request: ProviderRequest): object {
+* 		return { messages: request.messages }
+* 	}
+* 	read(record: string): ProviderIncrement {
+* 		return { content: record, thinking: '', tools: [] }
+* 	}
+* 	finish(_parser: ProviderParserInterface<string>): readonly string[] {
+* 		return [] // Raw text retains no records at end of input.
+* 	}
+* }
+* ```
+*/
+var AgentProvider = class {
+	#id;
+	#url;
+	#path;
+	#timeout;
+	#transport;
+	#headers;
+	#format;
+	#split;
+	#strict;
+	constructor(input) {
+		this.#id = crypto.randomUUID();
+		this.#url = input.url;
+		this.#path = input.path ?? "";
+		this.#timeout = input.timeout ?? 12e4;
+		this.#transport = input.fetch ?? globalThis.fetch.bind(globalThis);
+		this.#headers = input.headers;
+		this.#format = input.format;
+		this.#split = input.split ?? true;
+		this.#strict = input.strict ?? false;
+	}
+	/** Exposes the instance's minted UUID. */
+	get id() {
+		return this.#id;
+	}
+	/** Exposes the context framing exactly as supplied. */
+	get format() {
+		return this.#format;
+	}
+	/**
+	* Generates a complete turn by draining the shared stream engine.
+	*
+	* @param messages - The conversation turns
+	* @param signal - The caller's cancellation bound
+	* @param tools - The advertised tool definitions
+	* @param options - The per-call generation configuration
+	* @returns The terminal stream result
+	*/
+	async generate(messages, signal, tools, options) {
+		const stream = this.stream(messages, signal, tools, options);
+		let step = await stream.next();
+		while (!step.done) step = await stream.next();
+		return step.value;
+	}
+	/**
+	* Streams decoded deltas and returns the authoritative or assembled turn result.
+	*
+	* @param messages - The conversation turns
+	* @param signal - The caller's cancellation bound
+	* @param tools - The advertised tool definitions
+	* @param options - The per-call generation configuration
+	* @returns Content and native thinking deltas followed by the settled result
+	* @throws ProviderAbortError Thrown when the combined cancellation bound fires
+	* @throws ProviderError Thrown for an HTTP or protocol failure
+	*/
+	async *stream(messages, signal, tools, options) {
+		if (signal.aborted) throw new ProviderAbortError({ content: "" });
+		const timeout = new _orkestrel_timeout.Timeout({ ms: this.#timeout });
+		timeout.start();
+		const combined = AbortSignal.any([timeout.signal, signal]);
+		let parser;
+		let splitter;
+		let state = {
+			content: "",
+			thinking: "",
+			tools: []
+		};
+		try {
+			parser = this.frame();
+			splitter = this.#split ? createThinkSplitter() : void 0;
+			const response = await this.#request({
+				messages,
+				...tools === void 0 ? {} : { tools },
+				...options === void 0 ? {} : { options }
+			}, combined);
+			if (response.body === null) throw new ProviderError("PROTOCOL", "provider error: no response body");
+			for await (const chunk of readChunks(response.body, combined)) {
+				combined.throwIfAborted();
+				for (const record of parser.parse(chunk)) {
+					yield* this.#fold(record, state, splitter, combined, (increment) => {
+						state = increment;
+					});
+					combined.throwIfAborted();
+					if (state.result !== void 0) return state.result;
+				}
+			}
+			combined.throwIfAborted();
+			for (const record of this.finish(parser)) {
+				yield* this.#fold(record, state, splitter, combined, (increment) => {
+					state = increment;
+				});
+				combined.throwIfAborted();
+				if (state.result !== void 0) return state.result;
+			}
+			const tail = splitter?.flush() ?? "";
+			if (tail.length > 0) yield {
+				channel: "content",
+				text: tail
+			};
+			combined.throwIfAborted();
+			if (this.#strict) throw new ProviderError("PROTOCOL", "provider error: missing settled result");
+			return buildProviderResult(splitter?.content ?? state.content, joinThinking(splitter?.thinking, state.thinking), state.tools, state.usage);
+		} catch (error) {
+			if (combined.aborted) {
+				splitter?.flush();
+				throw new ProviderAbortError(buildProviderResult(splitter?.content ?? state.content, joinThinking(splitter?.thinking, state.thinking), state.tools, state.usage), error === combined.reason ? void 0 : { cause: error });
+			}
+			throw error;
+		} finally {
+			try {
+				parser?.clear();
+			} finally {
+				timeout.clear();
+			}
+		}
+	}
+	*#fold(record, previous, splitter, signal, commit) {
+		const increment = this.read(record);
+		if (increment.result !== void 0) {
+			commit(increment);
+			return;
+		}
+		const content = splitter?.split(increment.content) ?? increment.content;
+		const usage = increment.usage ?? previous.usage;
+		commit({
+			content: previous.content + increment.content,
+			thinking: previous.thinking + increment.thinking,
+			tools: [...previous.tools, ...increment.tools],
+			...usage === void 0 ? {} : { usage }
+		});
+		if (content.length > 0) yield {
+			channel: "content",
+			text: content
+		};
+		signal.throwIfAborted();
+		if (increment.thinking.length > 0) yield {
+			channel: "thinking",
+			text: increment.thinking
+		};
+	}
+	async #request(request, signal) {
+		const headers = await this.#requestHeaders(signal);
+		signal.throwIfAborted();
+		const response = await this.#transport(this.#url + this.#path, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(this.body(request)),
+			signal
+		});
+		if (!response.ok) {
+			let detail;
+			try {
+				detail = response.body === null ? "" : (await readText(response.body, MAX_ERROR_BODY_LENGTH, signal)).text;
+			} catch (cause) {
+				throw new ProviderError("HTTP", `provider error: ${response.status} - (error body unavailable)`, {
+					status: response.status,
+					cause
+				});
+			}
+			signal.throwIfAborted();
+			throw new ProviderError("HTTP", `provider error: ${response.status}${detail === "" ? "" : ` - ${detail}`}`, { status: response.status });
+		}
+		return response;
+	}
+	async #requestHeaders(signal) {
+		const headers = new Headers({ "Content-Type": "application/json" });
+		if (this.#headers === void 0) return headers;
+		const cleanup = new AbortController();
+		const aborted = Promise.withResolvers();
+		signal.addEventListener("abort", () => aborted.reject(signal.reason), {
+			once: true,
+			signal: cleanup.signal
+		});
+		try {
+			signal.throwIfAborted();
+			const hook = this.#headers;
+			const entries = await Promise.race([Promise.resolve().then(() => hook(signal)), aborted.promise]);
+			for (const [key, value] of Object.entries(entries)) headers.set(key, value);
+			return headers;
+		} finally {
+			cleanup.abort();
+		}
+	}
+};
+//#endregion
+//#region src/core/providers/RelayProvider.ts
+/**
+* Carries provider calls over an authenticated NDJSON relay endpoint.
+*
+* @remarks
+* Tool execution context stays local; calls carry only `id`, `name`, and `arguments`.
+* The wire body is an owned snapshot of
+* the projection read through property descriptors, so a serializer reachable only through a
+* `get` trap or a prototype is never consulted; an own function-valued property such as a
+* `toJSON` method is a value outside JSON and is refused before fetching, with the clone's
+* failure as the refusal's `cause`. A remote abort reconstructs a `ProviderAbortError` instance
+* without aborting the
+* local signal; the `Agent` runtime treats that instance as an error unless its own bound
+* signal is aborted.
+* Content is preserved verbatim, including literal thinking tags.
+* A refusal reaches the browser as a `ProviderError` instance with the `HTTP` code and status.
+* This is the browser end alone; {@link createRelay} mounts the server end, and
+* {@link createRelayProvider}'s example is the browser half of that pair.
+*
+* @example
+* ```ts
+* import type { ProviderResult } from '@orkestrel/agent'
+* import { RelayProvider } from '@orkestrel/agent'
+* // The browser application supplies this parser dependency.
+* import { createNDJSONParser } from '@orkestrel/ndjson'
+*
+* export function ask(bearer: string, signal: AbortSignal): Promise<ProviderResult> {
+* 	const browser = new RelayProvider({
+* 		url: 'https://relay.example/relay',
+* 		parser: createNDJSONParser,
+* 		headers: () => ({ authorization: `Bearer ${bearer}` }),
+* 	})
+* 	return browser.generate([{ id: 'ask', role: 'user', content: 'ping' }], signal)
+* }
+* ```
+*/
+var RelayProvider = class extends AgentProvider {
+	#parser;
+	constructor(options) {
+		const { url, timeout, fetch, headers, format } = options;
+		super({
+			url,
+			split: false,
+			strict: true,
+			...timeout === void 0 ? {} : { timeout },
+			...fetch === void 0 ? {} : { fetch },
+			...headers === void 0 ? {} : { headers },
+			...format === void 0 ? {} : { format }
+		});
+		this.#parser = options.parser;
+	}
+	/** Identifies the relay backend. */
+	name = "relay";
+	/** Creates fresh framing state for each response. */
+	frame() {
+		return this.#parser();
+	}
+	/**
+	* Projects declared request fields and refuses values the JSON wire cannot carry.
+	*
+	* @remarks
+	* The snapshot is taken from property descriptors, so a custom serializer a projected
+	* value carries is ignored rather than consulted and cannot reach the wire.
+	*
+	* @param request - The domain conversation and call configuration
+	* @returns The validated wire request
+	* @throws {ProviderError} Thrown when the snapshot cannot be taken — a hostile read or a
+	* value outside JSON — carrying that failure as its `cause`, and when the snapshot the
+	* projection produced is not a valid wire request
+	*/
+	body(request) {
+		let snapshot;
+		try {
+			const projected = {
+				messages: request.messages.map((message) => ({
+					id: message.id,
+					role: message.role,
+					content: message.content,
+					...message.calls === void 0 ? {} : { calls: message.calls.map((call) => ({
+						id: call.id,
+						name: call.name,
+						arguments: call.arguments
+					})) },
+					...message.images === void 0 ? {} : { images: message.images }
+				})),
+				...request.tools === void 0 ? {} : { tools: request.tools.map((tool) => ({
+					name: tool.name,
+					...tool.description === void 0 ? {} : { description: tool.description },
+					...tool.parameters === void 0 ? {} : { parameters: tool.parameters }
+				})) },
+				...request.options === void 0 ? {} : { options: {
+					...request.options.think === void 0 ? {} : { think: request.options.think },
+					...request.options.schema === void 0 ? {} : { schema: request.options.schema }
+				} }
+			};
+			snapshot = (0, _orkestrel_contract.cloneJSONValue)(projected);
+		} catch (cause) {
+			throw new ProviderError("PROTOCOL", "relay request is not JSON", { cause });
+		}
+		if (!providerRequestContract.is(snapshot)) throw new ProviderError("PROTOCOL", "relay request is not JSON");
+		return snapshot;
+	}
+	/**
+	* Validates a relay frame and translates its channel into the shared stream engine.
+	*
+	* @param record - The framed wire record
+	* @returns A delta contribution or authoritative result
+	* @throws {ProviderAbortError} Thrown for a remote abort carrying its partial
+	* @throws {ProviderError} Thrown for a malformed frame or remote provider failure
+	*/
+	read(record) {
+		if (!relayFrameContract.is(record)) throw new ProviderError("PROTOCOL", "invalid relay frame");
+		switch (record.channel) {
+			case "content": return {
+				content: record.text,
+				thinking: "",
+				tools: []
+			};
+			case "thinking": return {
+				content: "",
+				thinking: record.text,
+				tools: []
+			};
+			case "result": return {
+				content: "",
+				thinking: "",
+				tools: [],
+				result: record.result
+			};
+			case "abort": throw new ProviderAbortError(record.partial);
+			case "error": throw new ProviderError("PROVIDER", record.message);
+		}
+	}
+	/**
+	* Recovers an unterminated final frame by completing its NDJSON line.
+	*
+	* @param parser - The call's retained framing state
+	* @returns Records completed by the final newline
+	*/
+	finish(parser) {
+		return parser.parse("\n");
+	}
+};
+//#endregion
+//#region src/core/RelayStream.ts
+/**
+* Streams a provider call as validated NDJSON frames under response backpressure.
+*
+* @remarks
+* Cancellation aborts upstream before returning its iterator. Request listeners are
+* released on settlement. Unexpected provider failures carry a fixed public message.
+* An inbound abort leaves the response body neither closed nor errored — a server runtime
+* cancels that body when the client disconnects — so a consumer that aborts the inbound
+* signal itself must cancel the body rather than keep reading it.
+*
+* @example
+* ```ts
+* import type { ProviderInterface } from '@orkestrel/agent'
+* import { RelayStream } from '@orkestrel/agent'
+*
+* export function respond(provider: ProviderInterface, signal: AbortSignal): Response {
+* 	return new RelayStream({ provider, request: { messages: [] }, signal }).response
+* }
+* ```
+*/
+var RelayStream = class {
+	#upstream = new AbortController();
+	#encoder = new TextEncoder();
+	#iterator;
+	#signal;
+	#listener;
+	#response;
+	#settled = false;
+	constructor(options) {
+		this.#signal = options.signal;
+		this.#listener = this.#cancel.bind(this);
+		if (this.#signal.aborted) this.#abortProvider();
+		this.#iterator = options.provider.stream(options.request.messages, this.#upstream.signal, options.request.tools, options.request.options);
+		this.#signal.addEventListener("abort", this.#listener, { once: true });
+		this.#response = new Response(new ReadableStream({
+			pull: this.#pull.bind(this),
+			cancel: this.#cancel.bind(this)
+		}), { headers: {
+			"content-type": RELAY_CONTENT_TYPE,
+			"cache-control": "no-store"
+		} });
+	}
+	/** Exposes the pull-driven response for the provider call. */
+	get response() {
+		return this.#response;
+	}
+	async #pull(controller) {
+		if (this.#settled) return;
+		try {
+			const step = await this.#iterator.next();
+			if (this.#settled) return;
+			this.#write(controller, step.done ? {
+				channel: "result",
+				result: step.value
+			} : step.value);
+			if (step.done) this.#finish(controller);
+		} catch (error) {
+			if (this.#settled) return;
+			const frame = error instanceof ProviderAbortError ? {
+				channel: "abort",
+				partial: error.partial
+			} : {
+				channel: "error",
+				message: RELAY_PROVIDER_MESSAGE
+			};
+			this.#write(controller, relayFrameContract.is(frame) ? frame : {
+				channel: "error",
+				message: RELAY_PROVIDER_MESSAGE
+			});
+			this.#finish(controller);
+			this.#abortProvider();
+			await this.#return();
+		}
+	}
+	async #cancel() {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#abortProvider();
+		try {
+			await this.#return();
+		} finally {
+			this.#release();
+		}
+	}
+	async #return() {
+		try {
+			await this.#iterator.return({ content: "" });
+		} catch {}
+	}
+	#write(controller, frame) {
+		if (!relayFrameContract.is(frame)) throw new ProviderError("PROTOCOL", "invalid relay frame");
+		controller.enqueue(this.#encoder.encode(`${JSON.stringify(frame)}\n`));
+	}
+	#finish(controller) {
+		this.#settled = true;
+		this.#release();
+		controller.close();
+	}
+	#abortProvider() {
+		this.#upstream.abort(this.#signal.reason);
+	}
+	#release() {
+		this.#signal.removeEventListener("abort", this.#listener);
+	}
+};
+//#endregion
 //#region src/core/scopes/Scope.ts
 /**
 * Represents a named, immutable filter over a richer context's items — an optional allow-list per
@@ -2640,6 +3450,105 @@ var ThinkSplitter = class {
 //#endregion
 //#region src/core/factories.ts
 /**
+* Creates an authorized relay handler that validates a bounded JSON request before streaming.
+*
+* @remarks
+* Answers with the `401` status when authorization refuses or throws, the `400`
+* status when the body is missing, unreadable, or invalid, the `413` status when
+* the body fills its byte budget or the inbound read is aborted, and the `502`
+* status when the upstream provider call cannot be constructed. Refusals carry no body.
+*
+* @param options - The upstream provider, authorization decision, and optional byte budget
+* @returns A fetch-standard handler suitable for a router
+* @example Mounting the relay on your server
+* ```ts
+* import type { ProviderInterface } from '@orkestrel/agent'
+* import { createRelay } from '@orkestrel/agent'
+* import { createDispatcher } from '@orkestrel/router'
+* import { createServer } from '@orkestrel/server'
+*
+* declare const upstream: ProviderInterface // the server-side provider holding the credential
+* declare const bearer: string
+*
+* const handler = createRelay({
+* 	provider: upstream,
+* 	authorize: (request) => request.headers.get('authorization') === `Bearer ${bearer}`,
+* })
+* const dispatcher = createDispatcher({
+* 	routes: [{ method: 'POST', path: '/relay', handler }],
+* })
+*
+* export function serve(request: Request): Promise<Response> {
+* 	return dispatcher.handle(request, undefined)
+* }
+*
+* const server = createServer({ dispatcher, state: () => undefined })
+* await server.start()
+* process.on('SIGTERM', () => server.stop()) // signal cancellation, drain, then close the listener
+* ```
+*/
+function createRelay(options) {
+	const { provider, authorize, limit } = options;
+	return async (request) => {
+		try {
+			if (await authorize(request) !== true) return new Response(void 0, { status: 401 });
+		} catch {
+			return new Response(void 0, { status: 401 });
+		}
+		if (request.body === null) return new Response(void 0, { status: 400 });
+		let read;
+		try {
+			read = await readText(request.body, limit ?? 1048576, request.signal);
+		} catch {
+			return new Response(void 0, { status: request.signal.aborted ? 413 : 400 });
+		}
+		if (!read.complete) return new Response(void 0, { status: 413 });
+		const parsed = (0, _orkestrel_contract.parseJSONAs)(read.text, providerRequestContract.is);
+		if (parsed === void 0) return new Response(void 0, { status: 400 });
+		try {
+			return new RelayStream({
+				provider,
+				request: parsed,
+				signal: request.signal
+			}).response;
+		} catch {
+			return new Response(void 0, { status: 502 });
+		}
+	};
+}
+/**
+* Creates a provider that carries calls through a relay endpoint.
+*
+* @remarks
+* This is the browser end alone. {@link createRelay} mounts the server end, and its example
+* is the server half this one pairs with.
+*
+* @param options - The endpoint, parser factory, and HTTP call configuration
+* @returns The concrete relay provider
+* @example Reaching the relay from the browser
+* ```ts
+* import type { ProviderInterface } from '@orkestrel/agent'
+* import { createRelayProvider } from '@orkestrel/agent'
+* import { createAbort } from '@orkestrel/abort'
+* // The browser application supplies this parser dependency.
+* import { createNDJSONParser } from '@orkestrel/ndjson'
+*
+* declare const bearer: string
+* const abort = createAbort()
+* const messages = [{ id: '1', role: 'user', content: 'Say hello.' }] as const
+*
+* const browser: ProviderInterface = createRelayProvider({
+* 	url: 'https://app.example/relay',
+* 	parser: createNDJSONParser,
+* 	headers: () => ({ authorization: `Bearer ${bearer}` }),
+* })
+* const result = await browser.generate(messages, abort.signal) // a ProviderResult like a local provider's
+* ```
+*/
+function createRelayProvider(options) {
+	return new RelayProvider(options);
+}
+/**
 * Creates a conversation — a {@link ConversationInterface} grouping messages above a flat
 * message store it owns directly, with compaction into summarized sections, a regenerated
 * rollup `summary`, on-demand `rehydrate`, and substring `search`, driven by a
@@ -2660,8 +3569,8 @@ var ThinkSplitter = class {
 *
 * @example Conversations & compaction
 * ```ts
-* import { createConversation } from '@orkestrel/agent'
 * import type { ProviderInterface } from '@orkestrel/agent'
+* import { createConversation } from '@orkestrel/agent'
 *
 * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
 * // The summarizer seam — built from the provider by the runtime; core stays provider-agnostic.
@@ -3222,6 +4131,7 @@ exports.Agent = Agent;
 exports.AgentContext = AgentContext;
 exports.AgentError = AgentError;
 exports.AgentJobError = AgentJobError;
+exports.AgentProvider = AgentProvider;
 exports.AgentRegistry = AgentRegistry;
 exports.Authority = Authority;
 exports.CONVERSATION_RECAP_PREFIX = CONVERSATION_RECAP_PREFIX;
@@ -3232,23 +4142,36 @@ exports.ConversationManager = ConversationManager;
 exports.DEFAULT_AGENT_LIMIT = DEFAULT_AGENT_LIMIT;
 exports.DEFAULT_AUTHORITY_ZONE = DEFAULT_AUTHORITY_ZONE;
 exports.DEFAULT_CONVERSATION_KEEP = DEFAULT_CONVERSATION_KEEP;
+exports.DEFAULT_PROVIDER_TIMEOUT = DEFAULT_PROVIDER_TIMEOUT;
+exports.DEFAULT_RELAY_LIMIT = DEFAULT_RELAY_LIMIT;
 exports.DatabaseConversationStore = DatabaseConversationStore;
 exports.IMAGE_TOKEN_ESTIMATE = IMAGE_TOKEN_ESTIMATE;
+exports.INVALID_RELAY_STATUS = INVALID_RELAY_STATUS;
 exports.Instruction = Instruction;
 exports.InstructionManager = InstructionManager;
+exports.MAX_ERROR_BODY_LENGTH = MAX_ERROR_BODY_LENGTH;
 exports.MESSAGE_TOKEN_OVERHEAD = MESSAGE_TOKEN_OVERHEAD;
 exports.MemoryConversationStore = MemoryConversationStore;
+exports.OVERSIZED_RELAY_STATUS = OVERSIZED_RELAY_STATUS;
 exports.ProviderAbortError = ProviderAbortError;
+exports.ProviderError = ProviderError;
+exports.RELAY_CONTENT_TYPE = RELAY_CONTENT_TYPE;
+exports.RELAY_PROVIDER_MESSAGE = RELAY_PROVIDER_MESSAGE;
+exports.RelayProvider = RelayProvider;
+exports.RelayStream = RelayStream;
 exports.Scope = Scope;
 exports.ScopeManager = ScopeManager;
 exports.THINK_CLOSE = THINK_CLOSE;
 exports.THINK_OPEN = THINK_OPEN;
 exports.ThinkSplitter = ThinkSplitter;
+exports.UNAUTHORIZED_RELAY_STATUS = UNAUTHORIZED_RELAY_STATUS;
+exports.UPSTREAM_RELAY_STATUS = UPSTREAM_RELAY_STATUS;
 exports.WORKSPACE_SECTION_HEADER = WORKSPACE_SECTION_HEADER;
 exports.agentResultToJSON = agentResultToJSON;
 exports.assembleResult = assembleResult;
 exports.attachImages = attachImages;
 exports.attachUserImages = attachUserImages;
+exports.buildProviderResult = buildProviderResult;
 exports.buildRecapMessage = buildRecapMessage;
 exports.buildSummaryMessage = buildSummaryMessage;
 exports.collectImageData = collectImageData;
@@ -3265,6 +4188,8 @@ exports.createDatabaseConversationStore = createDatabaseConversationStore;
 exports.createInstruction = createInstruction;
 exports.createInstructionManager = createInstructionManager;
 exports.createMemoryConversationStore = createMemoryConversationStore;
+exports.createRelay = createRelay;
+exports.createRelayProvider = createRelayProvider;
 exports.createScope = createScope;
 exports.createScopeManager = createScopeManager;
 exports.createThinkSplitter = createThinkSplitter;
@@ -3281,8 +4206,19 @@ exports.isConversationError = isConversationError;
 exports.isConversationSnapshot = isConversationSnapshot;
 exports.isMessage = isMessage;
 exports.isProviderAbortError = isProviderAbortError;
+exports.isProviderError = isProviderError;
 exports.isSection = isSection;
 exports.joinThinking = joinThinking;
+exports.messageContract = messageContract;
+exports.messageShape = messageShape;
+exports.providerRequestContract = providerRequestContract;
+exports.providerRequestShape = providerRequestShape;
+exports.providerResultContract = providerResultContract;
+exports.providerResultShape = providerResultShape;
+exports.readChunks = readChunks;
+exports.readText = readText;
+exports.relayFrameContract = relayFrameContract;
+exports.relayFrameShape = relayFrameShape;
 exports.renderFencedFile = renderFencedFile;
 exports.renderSection = renderSection;
 exports.resolveClose = resolveClose;
@@ -3292,5 +4228,6 @@ exports.sanitizeToken = sanitizeToken;
 exports.sanitizeUsage = sanitizeUsage;
 exports.settleAgentJob = settleAgentJob;
 exports.sumUsage = sumUsage;
+exports.toolCallShape = toolCallShape;
 
 //# sourceMappingURL=index.cjs.map