@myagentroam/agent 0.9.159 → 0.9.160

package/dist/agent-core/extensions/mcp.js

@@ -0,0 +1,433 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { MarAgentError } from '../error.js';
+import { assertMcpToolCatalog } from '../tools/mcp/catalog.js';
+import { cloneCoreJson } from './data.js';
+import { ExtensionResourceScope } from './resources.js';
+/** One Session's declarations and owned Client leases feed its sole tool registry. */
+export class ExtensionMcp {
+    tools;
+    hooks;
+    getTools;
+    toolRef;
+    isMcpRef;
+    invoke;
+    diagnose;
+    #declarations = [];
+    #serverRefs = new WeakMap();
+    #connectionRefs = new WeakMap();
+    #connections = new Set();
+    #calling = new AsyncLocalStorage();
+    constructor(tools, hooks, getTools, toolRef, isMcpRef, invoke, diagnose) {
+        this.tools = tools;
+        this.hooks = hooks;
+        this.getTools = getTools;
+        this.toolRef = toolRef;
+        this.isMcpRef = isMcpRef;
+        this.invoke = invoke;
+        this.diagnose = diagnose;
+    }
+    bind(owner, extensionId, backend, run) {
+        return {
+            register: (definition) => this.#register(owner, extensionId, definition),
+            servers: () => Object.freeze(this.#declarations
+                .filter((entry) => entry.owner === owner && this.#declared(entry))
+                .map((entry) => entry.ref)),
+            connections: () => Object.freeze([...this.#connections]
+                .filter((entry) => entry.owner === owner && !entry.closed)
+                .map((entry) => entry.ref)),
+            connect: async (input) => {
+                const request = captureInput(input, ['server', 'signal']);
+                return run((call) => this.hooks.invoke('mcp.connect', request, call, async (input, effective) => {
+                    const server = this.#server(owner, input.server);
+                    return this.#connect(owner, extensionId, server.ref, backend, effective);
+                }), request.signal);
+            },
+            catalog: async (input) => {
+                const request = captureInput(input, ['connection', 'signal']);
+                return run((call) => this.hooks.invoke('mcp.catalog', request, call, async (input, effective) => {
+                    const connection = this.#connection(input.connection);
+                    await this.#refresh(connection, effective);
+                    const bindings = this.getTools(effective);
+                    const result = Object.freeze({
+                        revision: connection.catalog.revision,
+                        servers: connection.catalog.servers,
+                        tools: Object.freeze(connection.catalog.tools.flatMap((tool) => {
+                            const binding = bindings.get(tool.definition.name);
+                            return binding?.mcp && binding.mcp.sourceIdentity === tool.sourceIdentity
+                                ? [this.toolRef(binding)]
+                                : [];
+                        }))
+                    });
+                    await this.hooks.emit('mcp.completed', {
+                        operation: 'catalog',
+                        connectionId: connection.ref.id,
+                        toolCount: connection.catalog.tools.length
+                    }, effective);
+                    return result;
+                }), request.signal);
+            },
+            call: async (input) => {
+                const captured = captureInput(input, ['tool', 'arguments', 'callId', 'signal']);
+                let arguments_;
+                try {
+                    arguments_ = structuredClone(captured.arguments);
+                }
+                catch {
+                    throw new MarAgentError('MAR_AGENT_MCP_INPUT_INVALID', 'MCP arguments cannot be copied.');
+                }
+                return run(async (call) => {
+                    if (!this.isMcpRef(captured.tool))
+                        throw new MarAgentError('MAR_AGENT_MCP_REFERENCE_INVALID', 'MCP tool reference is invalid.');
+                    return this.invoke({
+                        name: captured.tool.definition.name,
+                        ref: captured.tool,
+                        arguments: arguments_,
+                        ...(captured.callId === undefined ? {} : { callId: captured.callId })
+                    }, call);
+                }, captured.signal);
+            },
+            disconnect: async (input) => {
+                const request = captureInput(input, ['connection', 'signal']);
+                return run((call) => this.hooks.invoke('mcp.disconnect', request, call, async (input, effective) => {
+                    const connection = this.#connectionRefs.get(input.connection);
+                    if (!connection)
+                        throw new MarAgentError('MAR_AGENT_MCP_REFERENCE_INVALID', 'MCP connection reference is invalid.');
+                    const active = this.#calling.getStore();
+                    if (active?.active && active.connection === connection)
+                        throw new MarAgentError('MAR_AGENT_MCP_CONNECTION_BUSY', 'MCP connection cannot close from its active call.');
+                    await connection.registration.dispose();
+                    await this.hooks.emit('mcp.completed', { operation: 'disconnect', connectionId: connection.ref.id }, effective);
+                }), request.signal);
+            }
+        };
+    }
+    servers() {
+        return [...this.#connections]
+            .filter((entry) => !entry.closed)
+            .flatMap((entry) => [...entry.catalog.servers]);
+    }
+    async #connect(owner, extensionId, server, backend, call) {
+        if (typeof backend.connect !== 'function')
+            throw new MarAgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Dynamic MCP port is unavailable.');
+        let connection;
+        const registration = owner.effect(() => async () => {
+            if (connection)
+                await this.#close(connection);
+        });
+        await registration.ready;
+        try {
+            call.signal.throwIfAborted();
+            const lease = await backend.connect(server.definition, call);
+            if (!lease || typeof lease.close !== 'function')
+                throw new MarAgentError('MAR_AGENT_MCP_BACKEND_INVALID', 'MCP backend did not return a closeable Client lease.');
+            const scope = new ExtensionResourceScope();
+            scope.activate();
+            const ref = Object.freeze({
+                id: randomUUID(),
+                serverId: server.definition.id,
+                source: Object.freeze({
+                    extensionId,
+                    ownerInstanceId: owner.instanceId,
+                    revision: randomUUID()
+                })
+            });
+            connection = {
+                owner,
+                ref,
+                backend: lease,
+                scope,
+                signal: owner.signal,
+                registration,
+                catalog: { revision: '', servers: [], tools: [] },
+                sources: [],
+                closed: false,
+                abort: () => {
+                    void registration.dispose().catch(() => this.diagnose());
+                }
+            };
+            owner.signal.addEventListener('abort', connection.abort, { once: true });
+            if (call.signal !== owner.signal)
+                call.signal.addEventListener('abort', connection.abort, { once: true });
+            if (typeof lease.catalog !== 'function' || typeof lease.call !== 'function')
+                throw new MarAgentError('MAR_AGENT_MCP_BACKEND_INVALID', 'MCP Client lease is missing catalog or call.');
+            call.signal.throwIfAborted();
+            await this.#refresh(connection, call);
+            call.signal.throwIfAborted();
+            this.#connectionRefs.set(ref, connection);
+            this.#connections.add(connection);
+            await this.hooks.emit('mcp.completed', { operation: 'connect', connectionId: ref.id, toolCount: connection.catalog.tools.length }, call);
+            return ref;
+        }
+        catch (error) {
+            try {
+                await registration.dispose();
+            }
+            catch {
+                this.diagnose();
+            }
+            throw error;
+        }
+        finally {
+            // Only the owning scope, not a completed acquisition, controls the delivered lease.
+            if (connection && call.signal !== connection.signal)
+                call.signal.removeEventListener('abort', connection.abort);
+        }
+    }
+    #refresh(connection, call) {
+        const result = (connection.tail ?? Promise.resolve()).then(async () => {
+            if (connection.closed)
+                throw new MarAgentError('MAR_AGENT_MCP_REFERENCE_INVALID', 'MCP connection is unavailable.');
+            await runMcpConnection(connection, call, async (signal) => {
+                const raw = await connection.backend.catalog(Object.freeze({ ...call, signal }));
+                let catalog;
+                try {
+                    catalog = structuredClone(raw);
+                }
+                catch {
+                    throw new MarAgentError('MAR_AGENT_MCP_CATALOG_INVALID', 'MCP catalog cannot be copied.');
+                }
+                assertMcpToolCatalog(catalog, { nativeToolNames: true });
+                catalog = freeze({
+                    ...catalog,
+                    tools: catalog.tools.map((tool) => ({
+                        ...tool,
+                        definition: {
+                            ...tool.definition,
+                            allowedCallers: tool.definition.allowedCallers ?? ['direct', 'programmatic']
+                        }
+                    }))
+                });
+                signal.throwIfAborted();
+                if (isDeepStrictEqual(catalog, connection.catalog))
+                    return;
+                const next = [];
+                const previous = connection.sources;
+                try {
+                    for (const tool of catalog.tools) {
+                        let source;
+                        const binding = Object.freeze({
+                            definition: tool.definition,
+                            mcp: tool,
+                            source: Object.freeze({
+                                kind: 'mcp',
+                                id: tool.sourceIdentity,
+                                revision: tool.definitionRevision,
+                                instanceId: connection.owner.instanceId
+                            }),
+                            registered: () => source.live,
+                            available: () => source.live &&
+                                !connection.closed &&
+                                connection.owner.state !== 'RETIRING' &&
+                                connection.owner.state !== 'DISPOSED',
+                            invoke: async (input, operation) => {
+                                if (!source.live || connection.closed)
+                                    throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'MCP tool source is unavailable.');
+                                const frame = { connection, active: true };
+                                const result = await runMcpConnection(connection, operation, async (signal) => {
+                                    signal.throwIfAborted();
+                                    if (!source.live)
+                                        throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'MCP tool source is unavailable.');
+                                    return this.#calling.run(frame, async () => {
+                                        try {
+                                            return await connection.backend.call({
+                                                name: tool.definition.name,
+                                                serverId: tool.serverId,
+                                                rawName: tool.rawName,
+                                                arguments: input.arguments,
+                                                ...(input.callId === undefined ? {} : { callId: input.callId }),
+                                                expectedTool: {
+                                                    sourceIdentity: tool.sourceIdentity,
+                                                    definitionRevision: tool.definitionRevision
+                                                }
+                                            }, Object.freeze({ ...operation, signal }));
+                                        }
+                                        finally {
+                                            frame.active = false;
+                                        }
+                                    });
+                                });
+                                await this.hooks.emit('mcp.completed', {
+                                    operation: 'call',
+                                    connectionId: connection.ref.id,
+                                    toolName: tool.definition.name
+                                }, operation);
+                                return result;
+                            }
+                        });
+                        source = {
+                            binding,
+                            live: false,
+                            registration: this.tools.contributeSource(connection.owner, binding)
+                        };
+                        next.push(source);
+                    }
+                    await Promise.all(next.map((source) => source.registration.ready));
+                    signal.throwIfAborted();
+                    for (const source of previous)
+                        source.live = false;
+                    for (const source of next)
+                        source.live = true;
+                    // Validation is synchronous: no other operation observes the tentative catalog.
+                    try {
+                        this.getTools(call);
+                    }
+                    catch (error) {
+                        for (const source of previous)
+                            source.live = true;
+                        for (const source of next)
+                            source.live = false;
+                        throw error;
+                    }
+                    connection.sources = next;
+                    connection.catalog = catalog;
+                }
+                catch (error) {
+                    for (const source of next)
+                        source.live = false;
+                    await Promise.all(next.map((source) => source.registration.dispose()));
+                    throw error;
+                }
+                await Promise.all(previous.map((source) => source.registration.dispose()));
+            });
+        });
+        connection.tail = result.catch(() => undefined);
+        return result;
+    }
+    #close(connection) {
+        if (connection.closing)
+            return connection.closing;
+        connection.closed = true;
+        this.#connections.delete(connection);
+        connection.signal.removeEventListener('abort', connection.abort);
+        connection.scope.retire();
+        for (const source of connection.sources)
+            source.live = false;
+        connection.closing = (async () => {
+            // Close the Client concurrently so non-cooperative transport waits can settle.
+            const results = await Promise.allSettled([
+                Promise.resolve().then(() => connection.backend.close()),
+                connection.scope.dispose(),
+                ...connection.sources.map((source) => source.registration.dispose())
+            ]);
+            const failure = results.find((result) => result.status === 'rejected');
+            if (failure?.status === 'rejected') {
+                if (failure.reason instanceof MarAgentError)
+                    throw failure.reason;
+                throw new MarAgentError('MAR_AGENT_MCP_CLEANUP_FAILED', 'MCP Client lease did not close.', {
+                    cause: failure.reason
+                });
+            }
+        })();
+        return connection.closing;
+    }
+    #register(owner, extensionId, input) {
+        const { id, configuration } = captureInput(input, ['id', 'configuration']);
+        if (typeof id !== 'string' || !id.trim())
+            throw new MarAgentError('MAR_AGENT_MCP_DEFINITION_INVALID', 'MCP declaration identity is invalid.');
+        let copied;
+        try {
+            copied = cloneCoreJson(configuration);
+        }
+        catch {
+            throw new MarAgentError('MAR_AGENT_MCP_DEFINITION_INVALID', 'MCP configuration must be serializable JSON.');
+        }
+        if (this.#declarations.some((entry) => this.#declared(entry) && entry.ref.definition.id === id && entry.owner !== owner))
+            throw new MarAgentError('MAR_AGENT_MCP_DEFINITION_CONFLICT', 'MCP declaration identity conflicts.');
+        const ref = Object.freeze({
+            definition: freeze({ id, configuration: copied }),
+            source: Object.freeze({
+                extensionId,
+                ownerInstanceId: owner.instanceId,
+                revision: randomUUID()
+            })
+        });
+        const entry = { owner, ref, live: true };
+        const registration = owner.effect(() => () => {
+            entry.live = false;
+            const index = this.#declarations.indexOf(entry);
+            if (index !== -1)
+                this.#declarations.splice(index, 1);
+        });
+        this.#declarations.push(entry);
+        this.#serverRefs.set(ref, entry);
+        return Object.freeze({ ...registration, ref });
+    }
+    #declared(entry) {
+        return (entry.live &&
+            (entry.owner.state === 'ACTIVE' ||
+                (entry.owner.state === 'STAGED' && ExtensionResourceScope.initializing)));
+    }
+    #server(owner, ref) {
+        const entry = typeof ref === 'string'
+            ? this.#declarations.findLast((entry) => entry.owner === owner && entry.ref.definition.id === ref && this.#declared(entry))
+            : this.#serverRefs.get(ref);
+        if (!entry || !this.#declared(entry))
+            throw new MarAgentError('MAR_AGENT_MCP_REFERENCE_INVALID', 'MCP declaration is unavailable.');
+        return entry;
+    }
+    #connection(ref) {
+        const connection = this.#connectionRefs.get(ref);
+        if (!connection || connection.closed)
+            throw new MarAgentError('MAR_AGENT_MCP_REFERENCE_INVALID', 'MCP connection is unavailable.');
+        return connection;
+    }
+}
+/** Project the same captured bindings used by invocation; never rediscover a backend by name. */
+export function coreMcpCatalog(servers, bindings) {
+    const descriptions = new Map();
+    for (const server of servers) {
+        const previous = descriptions.get(server.id);
+        if (previous && !isDeepStrictEqual(previous, server))
+            throw new MarAgentError('MAR_AGENT_MCP_CATALOG_INVALID', 'MCP server identities conflict.');
+        descriptions.set(server.id, server);
+    }
+    const tools = [...bindings.values()]
+        .filter((binding) => binding.mcp !== undefined)
+        .map((binding) => ({
+        ...binding.mcp,
+        definition: binding.definition,
+        sourceIdentity: binding.source.kind === 'mcp'
+            ? binding.mcp.sourceIdentity
+            : digest([binding.source.id, binding.mcp.sourceIdentity]),
+        definitionRevision: binding.source.kind === 'mcp'
+            ? binding.mcp.definitionRevision
+            : digest([binding.source.revision, binding.mcp.definitionRevision, binding.definition])
+    }));
+    const catalog = { servers: [...descriptions.values()], tools };
+    return {
+        ...catalog,
+        revision: createHash('sha256').update(JSON.stringify(catalog)).digest('hex')
+    };
+}
+async function runMcpConnection(connection, call, operation) {
+    try {
+        return await connection.scope.run(operation, call.signal);
+    }
+    catch (error) {
+        // A Client may wrap the abort reason. The owned lease, not transport error identity,
+        // decides whether teardown cancelled this operation; preserve the original cause.
+        if (connection.scope.signal.aborted || connection.owner.signal.aborted)
+            throw new MarAgentError('MAR_AGENT_CANCELLED', 'MCP operation was cancelled.', {
+                cause: error
+            });
+        throw error;
+    }
+}
+function captureInput(input, keys) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new MarAgentError('MAR_AGENT_MCP_INPUT_INVALID', 'MCP input must be an object.');
+    return Object.freeze(Object.fromEntries(keys.map((key) => [key, input[key]])));
+}
+function digest(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function freeze(value) {
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            freeze(item);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/agent-core/extensions/model-request.d.ts

@@ -0,0 +1,60 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+import type { ModelRequest, ModelTextBlock } from '../model/contracts.js';
+import type { ClientToolDefinition } from '../tools/contracts.js';
+/** Provider-private context is retained through opaque references, never exposed as payloads. */
+export type CoreModelMessage = {
+    readonly role: 'opaque';
+    readonly sourceRef: string;
+} | {
+    readonly role: 'user' | 'assistant' | 'tool' | 'tool_call';
+    readonly content: string;
+    readonly textBlocks?: readonly ModelTextBlock[];
+    readonly sourceRef?: string;
+    readonly callId?: string;
+    readonly name?: string;
+    readonly arguments?: unknown;
+    readonly images?: readonly {
+        readonly mimeType: string;
+        readonly dataBase64: string;
+    }[];
+};
+export interface CoreModelRequest {
+    readonly modelId: string;
+    readonly system: string;
+    readonly systemBlocks?: readonly ModelTextBlock[];
+    readonly messages: readonly CoreModelMessage[];
+    readonly tools: readonly ClientToolDefinition[];
+    readonly toolChoice?: 'auto' | 'none';
+    readonly reasoningEffort?: MarAgentReasoningEffort;
+    readonly images?: readonly {
+        readonly mimeType: string;
+        readonly dataBase64: string;
+    }[];
+}
+export interface CoreRequestSnapshot {
+    readonly id: string;
+    readonly request: CoreModelRequest;
+}
+/** Only actual SDK model dispatch records snapshots; public views carry no raw payload authority. */
+export declare class ExtensionRequestSnapshots {
+    #private;
+    record(modelId: string, request: ModelRequest): CoreRequestSnapshot;
+    complete(snapshot: CoreRequestSnapshot): void;
+    capture(input?: {
+        readonly completed?: boolean;
+    }): CoreRequestSnapshot | undefined;
+    resolve(snapshot: CoreRequestSnapshot): {
+        modelId: string;
+        request: ModelRequest;
+        view: CoreModelRequest;
+    };
+}
+/** One conversion per actual request; references are valid only for this candidate. */
+export declare class ExtensionRequestBridge {
+    #private;
+    readonly modelId: string;
+    readonly original: ModelRequest;
+    readonly view: CoreModelRequest;
+    constructor(modelId: string, original: ModelRequest, sourceMessages?: readonly CoreModelMessage[]);
+    lower(view: CoreModelRequest): ModelRequest;
+}

package/dist/agent-core/extensions/model-request.js

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveModelTextBlocks } from '../model/text-blocks.js';
+import { MarAgentError } from '../error.js';
+/** Only actual SDK model dispatch records snapshots; public views carry no raw payload authority. */
+export class ExtensionRequestSnapshots {
+    #requests = new WeakMap();
+    #current;
+    #completed;
+    record(modelId, request) {
+        const { onAttemptDiagnostic: _diagnostic, ...serializable } = request;
+        const retained = structuredClone(serializable);
+        let view;
+        // Preserve dispatch-time isolation without projecting unused public views.
+        const snapshot = Object.freeze({
+            id: randomUUID(),
+            get request() {
+                return (view ??= freezeSnapshot(new ExtensionRequestBridge(modelId, retained).view));
+            }
+        });
+        this.#requests.set(snapshot, { modelId, request: retained });
+        this.#current = snapshot;
+        return snapshot;
+    }
+    complete(snapshot) {
+        if (!this.#requests.has(snapshot))
+            throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+        this.#completed = snapshot;
+    }
+    capture(input = {}) {
+        if (!input ||
+            typeof input !== 'object' ||
+            Array.isArray(input) ||
+            (input.completed !== undefined && typeof input.completed !== 'boolean'))
+            throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot selection is invalid.');
+        return input.completed === true ? this.#completed : this.#current;
+    }
+    resolve(snapshot) {
+        const entry = this.#requests.get(snapshot);
+        if (!entry)
+            throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot does not belong to the current Session.');
+        return {
+            modelId: entry.modelId,
+            request: structuredClone(entry.request),
+            view: snapshot.request
+        };
+    }
+}
+function freezeSnapshot(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freezeSnapshot(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** One conversion per actual request; references are valid only for this candidate. */
+export class ExtensionRequestBridge {
+    modelId;
+    original;
+    #messages = new Map();
+    view;
+    constructor(modelId, original, sourceMessages) {
+        this.modelId = modelId;
+        this.original = original;
+        const messages = original.messages.map((original, index) => {
+            const sourceRef = sourceMessages?.[index]?.sourceRef ?? randomUUID();
+            const view = original.role === 'provider'
+                ? { role: 'opaque', sourceRef }
+                : {
+                    role: original.role,
+                    content: original.content,
+                    ...(original.textBlocks === undefined
+                        ? {}
+                        : { textBlocks: structuredClone(original.textBlocks) }),
+                    sourceRef,
+                    ...(original.callId !== undefined ? { callId: original.callId } : {}),
+                    ...(original.name !== undefined ? { name: original.name } : {}),
+                    ...(original.arguments !== undefined
+                        ? { arguments: structuredClone(original.arguments) }
+                        : {}),
+                    ...(original.images !== undefined ? { images: structuredClone(original.images) } : {})
+                };
+            this.#messages.set(sourceRef, { original, view: structuredClone(view) });
+            return view;
+        });
+        this.view = {
+            modelId,
+            system: original.system,
+            ...(original.systemBlocks === undefined
+                ? {}
+                : { systemBlocks: structuredClone(original.systemBlocks) }),
+            messages,
+            tools: structuredClone(original.tools),
+            ...(original.toolChoice ? { toolChoice: original.toolChoice } : {}),
+            ...(original.reasoningEffort ? { reasoningEffort: original.reasoningEffort } : {}),
+            ...(original.images ? { images: structuredClone(original.images) } : {})
+        };
+    }
+    lower(view) {
+        if (!view ||
+            view.modelId !== this.modelId ||
+            typeof view.system !== 'string' ||
+            !Array.isArray(view.messages) ||
+            !Array.isArray(view.tools) ||
+            view.tools.some((tool) => !tool ||
+                typeof tool !== 'object' ||
+                typeof tool.name !== 'string' ||
+                typeof tool.description !== 'string' ||
+                !tool.inputSchema ||
+                typeof tool.inputSchema !== 'object' ||
+                Array.isArray(tool.inputSchema)))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Model request view is invalid.');
+        const seen = new Set();
+        const messages = view.messages.map((message) => {
+            if (!message || typeof message !== 'object')
+                throw new MarAgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message view is invalid.');
+            const source = message.sourceRef ? this.#messages.get(message.sourceRef) : undefined;
+            if (message.sourceRef) {
+                if (!source || seen.has(message.sourceRef))
+                    throw new MarAgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message source reference is invalid.');
+                seen.add(message.sourceRef);
+            }
+            if (source && isDeepStrictEqual(message, source.view))
+                return source.original;
+            if (message.role === 'opaque' ||
+                typeof message.content !== 'string' ||
+                !['user', 'assistant', 'tool', 'tool_call'].includes(message.role))
+                throw new MarAgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message view is invalid.');
+            if (message.textBlocks !== undefined && message.role === 'tool_call')
+                throw new MarAgentError('MAR_AGENT_MODEL_CAPABILITY_UNAVAILABLE', 'Text blocks cannot replace structured tool-call arguments.');
+            return {
+                role: message.role,
+                content: message.content,
+                ...(message.textBlocks === undefined
+                    ? {}
+                    : { textBlocks: resolveModelTextBlocks(message.content, message.textBlocks) }),
+                ...(message.callId !== undefined ? { callId: message.callId } : {}),
+                ...(message.name !== undefined ? { name: message.name } : {}),
+                ...(message.role === 'tool' &&
+                    source?.original.role === 'tool' &&
+                    message.callId === source.original.callId &&
+                    message.name === source.original.name &&
+                    source.original.isError !== undefined
+                    ? { isError: source.original.isError }
+                    : {}),
+                ...(message.arguments !== undefined
+                    ? { arguments: structuredClone(message.arguments) }
+                    : {}),
+                ...(message.images !== undefined ? { images: structuredClone(message.images) } : {})
+            };
+        });
+        const { toolChoice: _toolChoice, reasoningEffort: _reasoningEffort, images: _images, systemBlocks: _systemBlocks, ...retained } = this.original;
+        return {
+            ...retained,
+            system: view.system,
+            ...(view.systemBlocks === undefined
+                ? {}
+                : { systemBlocks: resolveModelTextBlocks(view.system, view.systemBlocks) }),
+            messages,
+            tools: structuredClone(view.tools),
+            ...(view.toolChoice ? { toolChoice: view.toolChoice } : {}),
+            ...(view.reasoningEffort ? { reasoningEffort: view.reasoningEffort } : {}),
+            ...(view.images ? { images: structuredClone(view.images) } : {})
+        };
+    }
+}

package/dist/agent-core/extensions/model-stream.d.ts

@@ -0,0 +1,9 @@
+import type { ModelEvent } from '../model/contracts.js';
+export type CoreModelEvent = Exclude<ModelEvent, {
+    type: 'response.item';
+}> | {
+    readonly type: 'opaque';
+    readonly sourceRef: string;
+};
+/** Pull-through transformation: no speculative reads, background producer, or stream replay. */
+export declare function transformCoreModelStream(start: (signal: AbortSignal) => AsyncIterable<ModelEvent>, parent: AbortSignal, transform: (event: CoreModelEvent, signal: AbortSignal) => Promise<CoreModelEvent | undefined>, diagnoseCleanup?: () => void): AsyncIterable<ModelEvent>;