@orkestrel/agent 0.0.21 → 0.0.22

package/dist/src/core/index.d.cts

@@ -1,16 +1,26 @@
+import { ArrayShape } from '@orkestrel/contract';
+import { BooleanShape } from '@orkestrel/contract';
 import type { BudgetInterface } from '@orkestrel/budget';
+import { ContractInterface } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
 import type { ControllerInterface } from '@orkestrel/workflow';
 import type { DriverInterface } from '@orkestrel/database';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
 import type { FileInterface } from '@orkestrel/workspace';
-import type { JSONValue } from '@orkestrel/contract';
+import { JSONShape } from '@orkestrel/contract';
+import { JSONValue } from '@orkestrel/contract';
+import { LiteralShape } from '@orkestrel/contract';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
 import type { QueueContext } from '@orkestrel/queue';
 import type { QueueInterface } from '@orkestrel/queue';
 import type { QueueStoreInterface } from '@orkestrel/queue';
 import type { RunnerInterface } from '@orkestrel/workflow';
 import type { SchedulerInterface } from '@orkestrel/workflow';
+import { StringShape } from '@orkestrel/contract';
 import type { TableInterface } from '@orkestrel/database';
 import type { TokenUsage } from '@orkestrel/budget';
 import type { ToolCall } from '@orkestrel/tool';
@@ -18,6 +28,7 @@ import type { ToolDefinition } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
 import type { ToolResult } from '@orkestrel/tool';
+import { UnionShape } from '@orkestrel/contract';
 import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
 
 /**
@@ -711,6 +722,126 @@ export declare interface AgentOptions {
     readonly strict?: boolean;
 }
 
+/**
+ * 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.
+ * 	}
+ * }
+ * ```
+ */
+export declare abstract class AgentProvider<TRecord = Readonly<Record<string, unknown>>> implements AgentProviderInterface<TRecord> {
+    #private;
+    constructor(input: AgentProviderInput);
+    /** Identifies the concrete backend. */
+    abstract readonly name: string;
+    /** Exposes the instance's minted UUID. */
+    get id(): string;
+    /** Exposes the context framing exactly as supplied. */
+    get format(): ContextFormat | undefined;
+    /** Creates fresh framing state for the call. */
+    abstract frame(): ProviderParserInterface<TRecord>;
+    /** Projects a domain request onto the concrete protocol's wire body. */
+    abstract body(request: ProviderRequest): object;
+    /** Decodes a framed record into a turn increment. */
+    abstract read(record: TRecord): ProviderIncrement;
+    /** Returns any records retained at end of input. */
+    abstract finish(parser: ProviderParserInterface<TRecord>): readonly TRecord[];
+    /**
+     * 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
+     */
+    generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    /**
+     * 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
+     */
+    stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+}
+
+/**
+ * Configures the HTTP destination and stream assembly of a provider base.
+ *
+ * @remarks
+ * `path` appends to `url`. If `split` is true, separates in-content reasoning;
+ * if false, preserves content verbatim. Default: true.
+ * If `strict` is true, requires a settled result record; if false, assembles at end of input.
+ * Default: false.
+ */
+export declare interface AgentProviderInput extends ProviderOptions {
+    readonly url: string;
+    readonly path?: string;
+    readonly split?: boolean;
+    readonly strict?: boolean;
+}
+
+/** Defines the wire-specific seams of the shared HTTP provider engine. */
+export declare interface AgentProviderInterface<TRecord = Readonly<Record<string, unknown>>> extends ProviderInterface {
+    /** Creates fresh framing state for a call. */
+    frame(): ProviderParserInterface<TRecord>;
+    /** Projects a request to the concrete protocol's serializable body. */
+    body(request: ProviderRequest): object;
+    /** Decodes a framed record into its contribution to the turn. */
+    read(record: TRecord): ProviderIncrement;
+    /** Returns records retained at end of input before the parser is cleared. */
+    finish(parser: ProviderParserInterface<TRecord>): readonly TRecord[];
+}
+
 /**
  * Configures `createAgentQueue` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createQueue`.
@@ -1211,6 +1342,21 @@ export declare interface AuthorityRule {
     readonly reason?: string;
 }
 
+/**
+ * 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' }
+ * ```
+ */
+export declare function buildProviderResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined): ProviderResult;
+
 /**
  * Builds the framed recap message for one compacted section — the same role and stable `id` as
  * {@link buildSummaryMessage}, with the content prefixed by {@link
@@ -2459,8 +2605,8 @@ export declare function createChannel<T>(): ChannelInterface<T>;
  *
  * @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.
@@ -2651,6 +2797,77 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  */
 export declare function createMemoryConversationStore(): ConversationStoreInterface;
 
+/**
+ * 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
+ * ```
+ */
+export declare function createRelay(options: RelayOptions): RelayHandler;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createRelayProvider(options: RelayProviderOptions): RelayProvider;
+
 /**
  * Creates a named scope — an immutable {@link ScopeInterface} from its `name` and its
  * per-category allow-lists, the `id` minted at construction.
@@ -2826,6 +3043,19 @@ export declare const DEFAULT_AUTHORITY_ZONE = "default";
  */
 export declare const DEFAULT_CONVERSATION_KEEP = 0;
 
+/**
+ * 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.
+ */
+export declare const DEFAULT_PROVIDER_TIMEOUT = 120000;
+
+/**
+ * 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.
+ */
+export declare const DEFAULT_RELAY_LIMIT = 1048576;
+
 /**
  * Synthesizes the denial {@link ToolResult} an authority-blocked call is fed back with — the
  * call's `id` / `name` keyed back, carrying a denial `error` instead of a value.
@@ -3223,6 +3453,13 @@ export declare interface InstructionManagerOptions {
  */
 export declare function intersectKeys(parent: readonly string[] | undefined, child: readonly string[] | undefined): readonly string[] | undefined;
 
+/**
+ * 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.
+ */
+export declare const INVALID_RELAY_STATUS = 400;
+
 /**
  * Narrows an unknown caught value to an {@link AgentError} through `instanceof`, so a `catch`
  * can branch on its `code`.
@@ -3312,34 +3549,20 @@ export declare function isConversationError(value: unknown): value is Conversati
 export declare function isConversationSnapshot(value: unknown): value is ConversationSnapshot;
 
 /**
- * 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
  * ```
  */
 export declare function isMessage(value: unknown): value is Message;
@@ -3362,6 +3585,18 @@ export declare function isMessage(value: unknown): value is Message;
  */
 export declare function isProviderAbortError(value: unknown): value is ProviderAbortError;
 
+/**
+ * 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
+ * ```
+ */
+export declare function isProviderError(value: unknown): value is ProviderError;
+
 /**
  * Checks whether an `unknown` is structurally a {@link Section} record — a `string` `id` and
  * `summary` beside a `messages` array of valid {@link Message}s, the per-section step of the
@@ -3403,11 +3638,19 @@ export declare function isSection(value: unknown): value is Section;
  * @example
  * ```ts
  * joinThinking(undefined, 'first') // 'first'
+ * joinThinking('', 'x') // 'x'
  * joinThinking('first', 'second') // 'first\n\nsecond'
  * ```
  */
 export declare function joinThinking(running: string | undefined, next: string): string;
 
+/**
+ * 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.
+ */
+export declare const MAX_ERROR_BODY_LENGTH = 2048;
+
 /**
  * Implements the {@link ConversationStoreInterface} in memory — a process-lifetime `Map` of
  * {@link ConversationSnapshot}s keyed by conversation id, the default store
@@ -3506,6 +3749,22 @@ export declare interface Message {
  */
 export declare const MESSAGE_TOKEN_OVERHEAD = 4;
 
+/** Validates and projects conversation messages at a JSON wire boundary. */
+export declare const messageContract: ContractInterface<Readonly<{
+id: string;
+role: "system" | "user" | "assistant" | "tool";
+content: string;
+} & {
+calls?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+images?: readonly string[];
+}>>;
+
 /**
  * Carries the minimal data needed to author a {@link Message} — the `id` is
  * assigned by the layer that stores it, so a caller supplies only role / content
@@ -3562,6 +3821,31 @@ export declare interface MessageManagerInterface {
 /** Names the role a {@link Message} plays in a conversation turn. */
 export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 
+/**
+ * Describes a conversation message's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than Message: non-JSON call arguments are refused,
+ * and caller context is refused by the guard or dropped by the parser.
+ */
+export declare const messageShape: ObjectShape<    {
+id: StringShape;
+role: LiteralShape<readonly ["system", "user", "assistant", "tool"]>;
+content: StringShape;
+calls: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+images: OptionalShape<ArrayShape<StringShape>>;
+}, boolean | ContractShape>;
+
+/**
+ * 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.
+ */
+export declare const OVERSIZED_RELAY_STATUS = 413;
+
 /**
  * Reports a provider stream cancelled mid-flight by its bound signal — thrown by a
  * {@link ProviderInterface}'s `stream`, carrying the {@link ProviderResult} assembled from
@@ -3571,13 +3855,15 @@ export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
  * 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.
  */
 export declare class ProviderAbortError extends Error {
     /** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
     readonly code: "ABORT";
     readonly partial: ProviderResult;
-    constructor(partial: ProviderResult);
+    constructor(partial: ProviderResult, options?: ErrorOptions);
 }
 
 /**
@@ -3603,6 +3889,47 @@ export declare type ProviderDelta = {
     readonly text: string;
 };
 
+/**
+ * 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.
+ */
+export declare class ProviderError 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. */
+    readonly code: ProviderErrorCode;
+    /** Holds the response status for an HTTP failure, or undefined for other codes. */
+    readonly status: number | undefined;
+    constructor(code: ProviderErrorCode, message: string, options?: ProviderErrorOptions);
+}
+
+/** Names the machine-readable provider failure conditions. */
+export declare type ProviderErrorCode = 
+/** Reports a non-OK HTTP response, including a relay request rejected with status 413. */
+'HTTP'
+/** Reports a missing body, malformed wire record, or missing required settled result. */
+| 'PROTOCOL'
+/** Reports an upstream provider failure carried by a relay error record. */
+| 'PROVIDER';
+
+/** Carries a provider failure's HTTP status and underlying cause. */
+export declare interface ProviderErrorOptions {
+    readonly status?: number;
+    readonly cause?: unknown;
+}
+
+/** Holds the decoded contribution of a wire record to a provider turn. */
+export declare interface ProviderIncrement {
+    readonly content: string;
+    readonly thinking: string;
+    readonly tools: readonly ToolCall[];
+    readonly usage?: TokenUsage;
+    readonly result?: ProviderResult;
+}
+
 /**
  * Defines the pluggable LLM inference boundary — the one contract every agent chunk depends on. A
  * provider turns a conversation (plus optional tools) into either a single assembled {@link
@@ -3659,6 +3986,101 @@ export declare interface ProviderInterface {
     stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
 }
 
+/**
+ * Configures a provider's deadline, transport, headers, and context framing.
+ *
+ * @remarks
+ * `timeout` is an integer duration in milliseconds. Default: 120_000.
+ * `fetch` defaults to the global transport bound to its global receiver.
+ * `headers` runs for each request inside its deadline and receives the combined caller
+ * and deadline signal so token requests can share that bound. It overrides the JSON
+ * content type only when it returns that header. `format` is exposed to context assembly.
+ */
+export declare interface ProviderOptions {
+    readonly timeout?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly headers?: (signal: AbortSignal) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+    readonly format?: ContextFormat;
+}
+
+/** Defines the structural framing seam supplied by a concrete provider. */
+export declare interface ProviderParserInterface<TRecord = Readonly<Record<string, unknown>>> {
+    /** Parses a decoded chunk into complete records. */
+    parse(chunk: string): readonly TRecord[];
+    /** Clears retained framing state. */
+    clear(): void;
+}
+
+/** Carries the conversation and per-call configuration sent to a provider. */
+export declare interface ProviderRequest {
+    readonly messages: readonly Message[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly options?: ProviderStreamOptions;
+}
+
+/** Validates and projects provider requests at a JSON wire boundary. */
+export declare const providerRequestContract: ContractInterface<Readonly<{
+messages: readonly Readonly<{
+id: string;
+role: "system" | "user" | "assistant" | "tool";
+content: string;
+} & {
+calls?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+images?: readonly string[];
+}>[];
+} & {
+tools?: readonly Readonly<{
+name: string;
+} & {
+description?: string;
+parameters?: {
+readonly [k: string]: JSONValue;
+};
+}>[];
+options?: Readonly<{} & {
+think?: boolean;
+schema?: {
+readonly [k: string]: JSONValue;
+};
+}>;
+}>>;
+
+/**
+ * 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, and caller context is refused or dropped.
+ */
+export declare const providerRequestShape: ObjectShape<    {
+messages: ArrayShape<ObjectShape<    {
+id: StringShape;
+role: LiteralShape<readonly ["system", "user", "assistant", "tool"]>;
+content: StringShape;
+calls: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+images: OptionalShape<ArrayShape<StringShape>>;
+}, boolean | ContractShape>>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+name: StringShape;
+description: OptionalShape<StringShape>;
+parameters: OptionalShape<ObjectShape<Record<never, never>, JSONShape>>;
+}, boolean | ContractShape>>>;
+options: OptionalShape<ObjectShape<    {
+think: OptionalShape<BooleanShape>;
+schema: OptionalShape<ObjectShape<Record<never, never>, JSONShape>>;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Holds a single inference turn's structured outcome — the assembled assistant content,
  * any reasoning the provider separated from it, any tool calls the model requested,
@@ -3684,6 +4106,47 @@ export declare interface ProviderResult {
     readonly usage?: TokenUsage;
 }
 
+/** Validates and projects provider results at a JSON wire boundary. */
+export declare const providerResultContract: ContractInterface<Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>>;
+
+/**
+ * Describes a provider result's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than ProviderResult: non-JSON call arguments are
+ * refused, and caller context is refused or dropped.
+ */
+export declare const providerResultShape: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Carries the per-call options threaded into a {@link ProviderInterface}'s `generate` / `stream` —
  * the bag a caller passes to influence one inference call without reconfiguring the provider
@@ -3707,6 +4170,299 @@ export declare interface ProviderStreamOptions {
     readonly schema?: Readonly<Record<string, unknown>>;
 }
 
+/**
+ * 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)
+ * ```
+ */
+export declare function readChunks(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<string>;
+
+/**
+ * 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 }
+ * ```
+ */
+export declare function readText(body: ReadableStream<Uint8Array>, limit?: number, signal?: AbortSignal): Promise<TextRead>;
+
+/**
+ * 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`.
+ */
+export declare const 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.
+ */
+export declare const RELAY_PROVIDER_MESSAGE = "relay provider failed";
+
+/** Carries a relay delta, settled result, remote abort, or remote failure. */
+export declare type RelayFrame = ProviderDelta | {
+    readonly channel: 'result';
+    readonly result: ProviderResult;
+} | {
+    readonly channel: 'abort';
+    readonly partial: ProviderResult;
+} | {
+    readonly channel: 'error';
+    readonly message: string;
+};
+
+/** Validates and projects channel-discriminated relay frames at a JSON wire boundary. */
+export declare const relayFrameContract: ContractInterface<Readonly<{
+channel: "content" | "thinking";
+text: string;
+} & {}> | Readonly<{
+channel: "result";
+result: Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>;
+} & {}> | Readonly<{
+channel: "abort";
+partial: Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>;
+} & {}> | Readonly<{
+channel: "error";
+message: string;
+} & {}>>;
+
+/**
+ * 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, and caller context is refused or dropped.
+ */
+export declare const relayFrameShape: UnionShape<readonly [ObjectShape<    {
+channel: LiteralShape<readonly ["content", "thinking"]>;
+text: StringShape;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["result"]>;
+result: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["abort"]>;
+partial: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["error"]>;
+message: StringShape;
+}, boolean | ContractShape>]>;
+
+/** Defines a host-independent relay request handler. */
+export declare type RelayHandler = (request: Request) => Promise<Response>;
+
+/** Configures the upstream provider, mandatory authorization, and request byte limit. */
+export declare interface RelayOptions {
+    readonly provider: ProviderInterface;
+    /**
+     * Authorizes the request before its body is read.
+     *
+     * @remarks
+     * The hook must not consume the request body; a body-reading hook locks the stream
+     * and the handler answers with the `400` status. The relay performs no origin or
+     * method check. An application trusting an ambient credential such as a cookie
+     * must compose origin and CSRF middleware before the handler to prevent cross-site calls.
+     */
+    readonly authorize: (request: Request) => boolean | Promise<boolean>;
+    /**
+     * Bounds the request body in bytes; the handler answers with the `413` status
+     * for a body at or above the limit.
+     */
+    readonly limit?: number;
+}
+
+/**
+ * Carries provider calls over an authenticated NDJSON relay endpoint.
+ *
+ * @remarks
+ * The `ToolCall.caller` member never crosses the hop. 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)
+ * }
+ * ```
+ */
+export declare class RelayProvider extends AgentProvider {
+    #private;
+    constructor(options: RelayProviderOptions);
+    /** Identifies the relay backend. */
+    readonly name = "relay";
+    /** Creates fresh framing state for each response. */
+    frame(): ProviderParserInterface;
+    /**
+     * 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 with caller context omitted
+     * @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: ProviderRequest): object;
+    /**
+     * 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: Readonly<Record<string, unknown>>): ProviderIncrement;
+    /**
+     * 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: ProviderParserInterface): ReadonlyArray<Readonly<Record<string, unknown>>>;
+}
+
+/** Configures a relay destination and its fresh structural parser factory. */
+export declare interface RelayProviderOptions extends ProviderOptions {
+    readonly url: string;
+    /** Creates a fresh parser for each relay response stream. */
+    readonly parser: () => ProviderParserInterface;
+}
+
+/**
+ * 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
+ * }
+ * ```
+ */
+export declare class RelayStream {
+    #private;
+    constructor(options: RelayStreamOptions);
+    /** Exposes the pull-driven response for the provider call. */
+    get response(): Response;
+}
+
+/** Carries the upstream call and cancellation bound of a relay response stream. */
+export declare interface RelayStreamOptions {
+    readonly provider: ProviderInterface;
+    readonly request: ProviderRequest;
+    readonly signal: AbortSignal;
+}
+
 /**
  * Renders a path-addressed text body as a fenced reference block — a `File: <path>` label line
  * over a language-tagged fence, the framing an
@@ -4182,6 +4938,16 @@ export declare interface StreamInterface<T, R> {
  */
 export declare function sumUsage(running: TokenUsage | undefined, next: TokenUsage): TokenUsage;
 
+/** Carries a decoded stream prefix and whether the stream ended within its byte budget. */
+export declare interface TextRead {
+    readonly text: string;
+    /**
+     * Reports true only when a read observes the `done` flag before exhausting the
+     * byte budget; an abort reports false.
+     */
+    readonly complete: boolean;
+}
+
 /**
  * Names the closing tag that ends a {@link THINK_OPEN} reasoning span — `'</think>'`. A span the
  * stream never closes (the model was cut off mid-reasoning) is treated as thinking to its end,
@@ -4294,6 +5060,33 @@ export declare interface ThinkSplitterInterface {
     flush(): string;
 }
 
+/**
+ * Describes a tool call's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than the domain: non-JSON arguments are refused.
+ * ToolCall.caller is not in this shape and never crosses a wire. The guard refuses
+ * that extra member; the contract parser drops it.
+ */
+export declare const toolCallShape: ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>;
+
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const UPSTREAM_RELAY_STATUS = 502;
+
 /**
  * Names the section header {@link import('./AgentContext.js').AgentContext}'s `build()` renders the
  * active workspace's text files under — `'## Workspace'`, the leading line of the dedicated