@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/approval.js

@@ -1 +1,199 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.ApprovalFlow=exports.CLIApprovalPresenter=exports.ApprovalError=exports.ApprovalErrorCode=void 0;const shared_1=require("../_deps/shared/index.js");var ApprovalErrorCode;!function(r){r.USER_DENIED="APPROVAL_USER_DENIED",r.TIMEOUT="APPROVAL_TIMEOUT",r.INVALID_DURATION="APPROVAL_INVALID_DURATION",r.SIGNATURE_FAILED="APPROVAL_SIGNATURE_FAILED",r.TOKEN_EXPIRED="APPROVAL_TOKEN_EXPIRED",r.TOKEN_REVOKED="APPROVAL_TOKEN_REVOKED",r.INVALID_TOKEN="APPROVAL_INVALID_TOKEN"}(ApprovalErrorCode||(exports.ApprovalErrorCode=ApprovalErrorCode={}));class ApprovalError extends Error{code;details;constructor(r,e,o){super(e),this.code=r,this.details=o,this.name="ApprovalError"}}exports.ApprovalError=ApprovalError;class CLIApprovalPresenter{async present(r){console.log("\n=== AGENT APPROVAL REQUEST ==="),console.log(`Agent: ${r.agentDid}`),console.log(`Duration: ${r.duration}`),console.log("\nRequested Scopes:");for(const e of r.scopes)console.log(`  - ${e}`);return r.limits&&(console.log("\nPolicy Limits:"),r.limits.amountPerTxn&&console.log(`  - Max per transaction: $${r.limits.amountPerTxn.toLocaleString()}`),r.limits.dailyAmount&&console.log(`  - Daily limit: $${r.limits.dailyAmount.toLocaleString()}`),r.limits.callsPerMinute&&console.log(`  - Rate limit: ${r.limits.callsPerMinute} calls/minute`)),r.description&&console.log(`\nDescription: ${r.description}`),console.log("\n[This is a mock presenter - auto-approving for development]"),console.log("In production, this would prompt for user input.\n"),(0,shared_1.ok)({approved:!0})}}exports.CLIApprovalPresenter=CLIApprovalPresenter;class ApprovalFlow{presenter;tokens=new Map;constructor(r={}){this.presenter=r.presenter??new CLIApprovalPresenter}async requestApproval(r){const e=this.parseDuration(r.duration);if(e<=0)return(0,shared_1.err)(new ApprovalError(ApprovalErrorCode.INVALID_DURATION,`Invalid duration: ${r.duration}`));const o=await this.presenter.present(r);if(!o.ok)return o;if(!o.value.approved)return(0,shared_1.ok)({approved:!1,reason:o.value.reason??"User denied approval"});const t=Date.now(),s={id:this.generateTokenId(),agentDid:r.agentDid,scopes:r.scopes,limits:r.limits,expiresAt:t+e,createdAt:t,valid:!0,signature:await this.signToken(r.agentDid,r.scopes,t+e)};return this.tokens.set(s.id,s),(0,shared_1.ok)({approved:!0,token:s})}verifyToken(r){const e=this.tokens.get(r);return e?e.valid?Date.now()>e.expiresAt?(0,shared_1.err)(new ApprovalError(ApprovalErrorCode.TOKEN_EXPIRED,`Token ${r} expired at ${new Date(e.expiresAt).toISOString()}`)):(0,shared_1.ok)(e):(0,shared_1.err)(new ApprovalError(ApprovalErrorCode.TOKEN_REVOKED,`Token ${r} has been revoked`)):(0,shared_1.err)(new ApprovalError(ApprovalErrorCode.INVALID_TOKEN,`Token ${r} not found`))}revokeToken(r){const e=this.tokens.get(r);e&&this.tokens.set(r,{...e,valid:!1})}parseDuration(r){if("number"==typeof r)return r;const e=r.match(/^(\d+)([smhd])$/);if(!e)return-1;const o=parseInt(e[1]??"0",10);switch(e[2]){case"s":return 1e3*o;case"m":return 60*o*1e3;case"h":return 60*o*60*1e3;case"d":return 24*o*60*60*1e3;default:return-1}}generateTokenId(){const r=new Uint8Array(12);crypto.getRandomValues(r);const e=Array.from(r,r=>r.toString(16).padStart(2,"0")).join("");return`appr_${Date.now()}_${e}`}async signToken(r,e,o){const t=JSON.stringify({agentDid:r,scopes:e,expiresAt:o});return btoa(t).substring(0,32)}}exports.ApprovalFlow=ApprovalFlow;
+"use strict";
+/**
+ * @module approval
+ * OAuth-style approval flow for agents
+ *
+ * Enterprise agents require explicit user consent before performing
+ * sensitive operations. This module implements OAuth-style consent
+ * screens and approval tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalFlow = exports.CLIApprovalPresenter = exports.ApprovalError = exports.ApprovalErrorCode = void 0;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Approval error codes
+ */
+var ApprovalErrorCode;
+(function (ApprovalErrorCode) {
+    ApprovalErrorCode["USER_DENIED"] = "APPROVAL_USER_DENIED";
+    ApprovalErrorCode["TIMEOUT"] = "APPROVAL_TIMEOUT";
+    ApprovalErrorCode["INVALID_DURATION"] = "APPROVAL_INVALID_DURATION";
+    ApprovalErrorCode["SIGNATURE_FAILED"] = "APPROVAL_SIGNATURE_FAILED";
+    ApprovalErrorCode["TOKEN_EXPIRED"] = "APPROVAL_TOKEN_EXPIRED";
+    ApprovalErrorCode["TOKEN_REVOKED"] = "APPROVAL_TOKEN_REVOKED";
+    ApprovalErrorCode["INVALID_TOKEN"] = "APPROVAL_INVALID_TOKEN";
+})(ApprovalErrorCode || (exports.ApprovalErrorCode = ApprovalErrorCode = {}));
+/**
+ * Approval error
+ */
+class ApprovalError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ApprovalError';
+    }
+}
+exports.ApprovalError = ApprovalError;
+/**
+ * CLI approval presenter (prints to console, reads stdin)
+ * This is a legitimate CLI interface - console output is intentional
+ */
+class CLIApprovalPresenter {
+    /* eslint-disable no-console */
+    async present(options) {
+        console.log('\n=== AGENT APPROVAL REQUEST ===');
+        console.log(`Agent: ${options.agentDid}`);
+        console.log(`Duration: ${options.duration}`);
+        console.log('\nRequested Scopes:');
+        for (const scope of options.scopes) {
+            console.log(`  - ${scope}`);
+        }
+        if (options.limits) {
+            console.log('\nPolicy Limits:');
+            if (options.limits.amountPerTxn) {
+                console.log(`  - Max per transaction: $${options.limits.amountPerTxn.toLocaleString()}`);
+            }
+            if (options.limits.dailyAmount) {
+                console.log(`  - Daily limit: $${options.limits.dailyAmount.toLocaleString()}`);
+            }
+            if (options.limits.callsPerMinute) {
+                console.log(`  - Rate limit: ${options.limits.callsPerMinute} calls/minute`);
+            }
+        }
+        if (options.description) {
+            console.log(`\nDescription: ${options.description}`);
+        }
+        console.log('\n[This is a mock presenter - auto-approving for development]');
+        console.log('In production, this would prompt for user input.\n');
+        // Auto-approve for development (production would prompt for y/n)
+        return (0, shared_1.ok)({
+            approved: true,
+        });
+    }
+}
+exports.CLIApprovalPresenter = CLIApprovalPresenter;
+/**
+ * Approval flow coordinator
+ *
+ * Orchestrates the consent flow: present to user → sign token → track expiry
+ */
+class ApprovalFlow {
+    presenter;
+    tokens = new Map();
+    constructor(options = {}) {
+        this.presenter = options.presenter ?? new CLIApprovalPresenter();
+    }
+    /**
+     * Request approval from user
+     *
+     * @param options - Approval request options
+     * @returns Approval result with token (if approved)
+     */
+    async requestApproval(options) {
+        // Validate duration
+        const durationMs = this.parseDuration(options.duration);
+        if (durationMs <= 0) {
+            return (0, shared_1.err)(new ApprovalError(ApprovalErrorCode.INVALID_DURATION, `Invalid duration: ${options.duration}`));
+        }
+        // Present to user
+        const result = await this.presenter.present(options);
+        if (!result.ok)
+            return result;
+        if (!result.value.approved) {
+            return (0, shared_1.ok)({
+                approved: false,
+                reason: result.value.reason ?? 'User denied approval',
+            });
+        }
+        // Generate approval token
+        const now = Date.now();
+        const token = {
+            id: this.generateTokenId(),
+            agentDid: options.agentDid,
+            scopes: options.scopes,
+            limits: options.limits,
+            expiresAt: now + durationMs,
+            createdAt: now,
+            valid: true,
+            signature: await this.signToken(options.agentDid, options.scopes, now + durationMs),
+        };
+        // Store token
+        this.tokens.set(token.id, token);
+        return (0, shared_1.ok)({
+            approved: true,
+            token,
+        });
+    }
+    /**
+     * Verify an approval token
+     *
+     * @param tokenId - Token ID to verify
+     * @returns Token if valid, error otherwise
+     */
+    verifyToken(tokenId) {
+        const token = this.tokens.get(tokenId);
+        if (!token) {
+            return (0, shared_1.err)(new ApprovalError(ApprovalErrorCode.INVALID_TOKEN, `Token ${tokenId} not found`));
+        }
+        if (!token.valid) {
+            return (0, shared_1.err)(new ApprovalError(ApprovalErrorCode.TOKEN_REVOKED, `Token ${tokenId} has been revoked`));
+        }
+        if (Date.now() > token.expiresAt) {
+            return (0, shared_1.err)(new ApprovalError(ApprovalErrorCode.TOKEN_EXPIRED, `Token ${tokenId} expired at ${new Date(token.expiresAt).toISOString()}`));
+        }
+        return (0, shared_1.ok)(token);
+    }
+    /**
+     * Revoke an approval token
+     *
+     * @param tokenId - Token ID to revoke
+     */
+    revokeToken(tokenId) {
+        const token = this.tokens.get(tokenId);
+        if (token) {
+            this.tokens.set(tokenId, { ...token, valid: false });
+        }
+    }
+    /**
+     * Parse duration string to milliseconds
+     */
+    parseDuration(duration) {
+        if (typeof duration === 'number')
+            return duration;
+        // Parse ISO 8601 duration or simple format
+        const matches = duration.match(/^(\d+)([smhd])$/);
+        if (!matches)
+            return -1;
+        const value = parseInt(matches[1] ?? '0', 10);
+        const unit = matches[2];
+        switch (unit) {
+            case 's': return value * 1000;
+            case 'm': return value * 60 * 1000;
+            case 'h': return value * 60 * 60 * 1000;
+            case 'd': return value * 24 * 60 * 60 * 1000;
+            default: return -1;
+        }
+    }
+    /**
+     * Generate a unique token ID
+     */
+    generateTokenId() {
+        const randomBytes = new Uint8Array(12);
+        crypto.getRandomValues(randomBytes);
+        const randomString = Array.from(randomBytes, b => b.toString(16).padStart(2, '0')).join('');
+        return `appr_${Date.now()}_${randomString}`;
+    }
+    /**
+     * Sign an approval token (stub - production would use Ed25519)
+     */
+    async signToken(agentDid, scopes, expiresAt) {
+        // Production would use Ed25519 signature over JSON.stringify({ agentDid, scopes, expiresAt })
+        // For now, return a mock signature
+        const payload = JSON.stringify({ agentDid, scopes, expiresAt });
+        return btoa(payload).substring(0, 32);
+    }
+}
+exports.ApprovalFlow = ApprovalFlow;

package/dist-standalone/cjs/async-iterators.js

@@ -1 +1,392 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.MessageStream=void 0,exports.collectMessages=collectMessages,exports.mapStream=mapStream,exports.filterStream=filterStream,exports.takeStream=takeStream,exports.mergeStreams=mergeStreams,exports.installAsyncIterators=installAsyncIterators;class MessageStream{agent;options;state;constructor(e,t={}){this.agent=e,this.options={from:t.from,scope:t.scope,bufferSize:t.bufferSize??100,signal:t.signal,allowCleartext:t.allowCleartext??!1},this.state={buffer:[],pending:[],done:!1},this.options.signal&&this.options.signal.addEventListener("abort",()=>{this.close(new Error("Stream aborted"))});const s=e=>{this.handleEnvelope(e)},r=this.agent.getTransports()[0];r&&(r.onReceive(s),this.state.cleanup=()=>{})}async handleEnvelope(e){if(this.state.done)return;const t=await this.agent.receive(e,{allowCleartext:this.options.allowCleartext});if(!t.ok)return;const s=t.value;if(!(this.options.from&&s.sender!==this.options.from||this.options.scope&&s.scope!==this.options.scope))if(this.state.pending.length>0){this.state.pending.shift()({value:s,done:!1})}else this.state.buffer.length<this.options.bufferSize&&this.state.buffer.push(s)}close(e){if(!this.state.done){this.state.done=!0,this.state.error=e;for(const e of this.state.pending)e({value:void 0,done:!0});this.state.pending=[],this.state.cleanup&&this.state.cleanup()}}async next(){if(this.state.done)return{value:void 0,done:!0};if(this.options.signal?.aborted)return this.close(new Error("Stream aborted")),{value:void 0,done:!0};if(this.state.buffer.length>0){return{value:this.state.buffer.shift(),done:!1}}return new Promise(e=>{this.state.pending.push(e)})}async return(e){return this.close(),{value:void 0,done:!0}}async throw(e){return this.close(e instanceof Error?e:new Error(String(e))),{value:void 0,done:!0}}[Symbol.asyncIterator](){return this}get bufferedCount(){return this.state.buffer.length}get closed(){return this.state.done}get error(){return this.state.error}}async function collectMessages(e,t={}){const s=[],r=new MessageStream(e,t);let a;t.timeout&&(a=setTimeout(()=>{r.return()},t.timeout));try{for await(const e of r)if(s.push(e),t.limit&&s.length>=t.limit)break}finally{a&&clearTimeout(a),r.closed||await r.return()}return s}async function*mapStream(e,t){for await(const s of e)yield await t(s)}async function*filterStream(e,t){for await(const s of e)await t(s)&&(yield s)}async function*takeStream(e,t){let s=0;for await(const r of e){if(s>=t)break;yield r,s++}}async function*mergeStreams(e){const t=e.map(e=>e[Symbol.asyncIterator]()),s=new Map;for(let e=0;e<t.length;e++)s.set(e,t[e].next());for(;s.size>0;){const e=Array.from(s.entries()),r=await Promise.race(e.map(async([e,t])=>({idx:e,result:await t})));s.delete(r.idx),r.result.done||(yield r.result.value,s.set(r.idx,t[r.idx].next()))}}function installAsyncIterators(e){"subscribe"in e.prototype||(e.prototype.subscribe=function(e){return new MessageStream(this,e)})}exports.MessageStream=MessageStream;
+"use strict";
+/**
+ * @fileoverview Async iterator API for xBind message streams.
+ *
+ * Provides modern async iteration patterns for consuming message streams
+ * with backpressure handling, stream cancellation, and error propagation.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to messages with async iteration
+ * for await (const message of agent.subscribe({ from: 'did:key:alice' })) {
+ *   console.log('Received:', message.payload);
+ * }
+ * ```
+ *
+ * @module async-iterators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageStream = void 0;
+exports.collectMessages = collectMessages;
+exports.mapStream = mapStream;
+exports.filterStream = filterStream;
+exports.takeStream = takeStream;
+exports.mergeStreams = mergeStreams;
+exports.installAsyncIterators = installAsyncIterators;
+/**
+ * Async iterable message stream.
+ *
+ * Implements AsyncIterableIterator for use with `for await...of` syntax.
+ * Handles backpressure, cancellation, and error propagation.
+ */
+class MessageStream {
+    agent;
+    options;
+    state;
+    constructor(agent, options = {}) {
+        this.agent = agent;
+        this.options = {
+            from: options.from,
+            scope: options.scope,
+            bufferSize: options.bufferSize ?? 100,
+            signal: options.signal,
+            allowCleartext: options.allowCleartext ?? false,
+        };
+        this.state = {
+            buffer: [],
+            pending: [],
+            done: false,
+        };
+        // Setup abort signal handler
+        if (this.options.signal) {
+            this.options.signal.addEventListener('abort', () => {
+                this.close(new Error('Stream aborted'));
+            });
+        }
+        // Register envelope handler
+        const handler = (envelope) => {
+            void this.handleEnvelope(envelope);
+        };
+        // Get first transport adapter and register handler
+        const transports = this.agent.getTransports();
+        const transport = transports[0];
+        if (transport) {
+            transport.onReceive(handler);
+            this.state.cleanup = () => {
+                // Remove handler by creating new transport without this handler
+                // (Transport interface doesn't support handler removal)
+            };
+        }
+    }
+    /**
+     * Handle incoming envelope from transport.
+     * @internal
+     */
+    async handleEnvelope(envelope) {
+        if (this.state.done)
+            return;
+        // Verify and decrypt the envelope
+        const result = await this.agent.receive(envelope, {
+            allowCleartext: this.options.allowCleartext,
+        });
+        if (!result.ok) {
+            // Ignore verification errors (not all envelopes are for this stream)
+            return;
+        }
+        const message = result.value;
+        // Apply filters
+        if (this.options.from && message.sender !== this.options.from) {
+            return;
+        }
+        if (this.options.scope && message.scope !== this.options.scope) {
+            return;
+        }
+        // Deliver message
+        if (this.state.pending.length > 0) {
+            // Consumer is waiting - deliver immediately
+            const resolve = this.state.pending.shift();
+            resolve({ value: message, done: false });
+        }
+        else if (this.state.buffer.length < this.options.bufferSize) {
+            // Buffer has space - enqueue
+            this.state.buffer.push(message);
+        }
+        // else: buffer full - drop message (backpressure)
+    }
+    /**
+     * Close the stream with optional error.
+     * @internal
+     */
+    close(error) {
+        if (this.state.done)
+            return;
+        this.state.done = true;
+        this.state.error = error;
+        // Resolve all pending next() calls
+        for (const resolve of this.state.pending) {
+            if (error) {
+                resolve({ value: undefined, done: true });
+            }
+            else {
+                resolve({ value: undefined, done: true });
+            }
+        }
+        this.state.pending = [];
+        // Cleanup resources
+        if (this.state.cleanup) {
+            this.state.cleanup();
+        }
+    }
+    /**
+     * Get next message from the stream.
+     *
+     * Returns a promise that resolves when:
+     * - A message is available in the buffer
+     * - A new message arrives from the transport
+     * - The stream is closed
+     *
+     * @returns Promise resolving to iterator result
+     */
+    async next() {
+        // Stream already done
+        if (this.state.done) {
+            return { value: undefined, done: true };
+        }
+        // Check abort signal
+        if (this.options.signal?.aborted) {
+            this.close(new Error('Stream aborted'));
+            return { value: undefined, done: true };
+        }
+        // Message available in buffer
+        if (this.state.buffer.length > 0) {
+            const message = this.state.buffer.shift();
+            return { value: message, done: false };
+        }
+        // Wait for next message
+        return new Promise((resolve) => {
+            this.state.pending.push(resolve);
+        });
+    }
+    /**
+     * Return method for iterator protocol.
+     * Closes the stream and completes iteration.
+     *
+     * @param value - Optional value (ignored)
+     * @returns Promise resolving to done result
+     */
+    async return(value) {
+        this.close();
+        return { value: undefined, done: true };
+    }
+    /**
+     * Throw method for iterator protocol.
+     * Closes the stream with error.
+     *
+     * @param error - Error to propagate
+     * @returns Promise resolving to done result
+     */
+    async throw(error) {
+        this.close(error instanceof Error ? error : new Error(String(error)));
+        return { value: undefined, done: true };
+    }
+    /**
+     * Make this object async iterable.
+     * Enables `for await...of` syntax.
+     *
+     * @returns This stream instance
+     */
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    /**
+     * Get number of buffered messages.
+     * Useful for monitoring backpressure.
+     */
+    get bufferedCount() {
+        return this.state.buffer.length;
+    }
+    /**
+     * Check if stream is closed.
+     */
+    get closed() {
+        return this.state.done;
+    }
+    /**
+     * Get stream error if any.
+     */
+    get error() {
+        return this.state.error;
+    }
+}
+exports.MessageStream = MessageStream;
+/**
+ * Collect messages from a stream into an array.
+ *
+ * Useful for batch processing or testing. Stream completes when:
+ * - Limit is reached
+ * - Timeout expires
+ * - Stream is aborted via signal
+ *
+ * @param agent - Agent instance to collect messages from
+ * @param options - Collection options
+ * @returns Promise resolving to array of messages
+ *
+ * @example
+ * ```typescript
+ * // Collect up to 10 messages with 5 second timeout
+ * const messages = await collectMessages(agent, {
+ *   from: 'did:key:alice',
+ *   limit: 10,
+ *   timeout: 5000
+ * });
+ * ```
+ */
+async function collectMessages(agent, options = {}) {
+    const messages = [];
+    const stream = new MessageStream(agent, options);
+    // Setup timeout if specified
+    let timeoutId;
+    if (options.timeout) {
+        timeoutId = setTimeout(() => {
+            void stream.return();
+        }, options.timeout);
+    }
+    try {
+        for await (const message of stream) {
+            messages.push(message);
+            if (options.limit && messages.length >= options.limit) {
+                break;
+            }
+        }
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        if (!stream.closed) {
+            await stream.return();
+        }
+    }
+    return messages;
+}
+/**
+ * Transform message stream with async mapping function.
+ *
+ * Enables functional-style stream processing with backpressure preservation.
+ *
+ * @param stream - Source message stream
+ * @param fn - Async transform function
+ * @returns Async iterable of transformed values
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe({ from: 'did:key:alice' });
+ * const payloads = mapStream(stream, async (msg) => msg.payload);
+ *
+ * for await (const payload of payloads) {
+ *   console.log('Payload:', payload);
+ * }
+ * ```
+ */
+async function* mapStream(stream, fn) {
+    for await (const value of stream) {
+        yield await fn(value);
+    }
+}
+/**
+ * Filter message stream with async predicate.
+ *
+ * Only yields messages that satisfy the predicate.
+ *
+ * @param stream - Source message stream
+ * @param predicate - Async filter predicate
+ * @returns Async iterable of filtered messages
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe({ scope: 'notifications' });
+ * const urgent = filterStream(stream, async (msg) =>
+ *   msg.payload.priority === 'high'
+ * );
+ *
+ * for await (const message of urgent) {
+ *   await handleUrgent(message);
+ * }
+ * ```
+ */
+async function* filterStream(stream, predicate) {
+    for await (const value of stream) {
+        if (await predicate(value)) {
+            yield value;
+        }
+    }
+}
+/**
+ * Take first N messages from stream.
+ *
+ * Stream completes after yielding N messages.
+ *
+ * @param stream - Source message stream
+ * @param count - Maximum messages to take
+ * @returns Async iterable with at most count messages
+ *
+ * @example
+ * ```typescript
+ * const stream = agent.subscribe();
+ * const first5 = takeStream(stream, 5);
+ *
+ * for await (const message of first5) {
+ *   console.log('Message:', message);
+ * }
+ * ```
+ */
+async function* takeStream(stream, count) {
+    let taken = 0;
+    for await (const value of stream) {
+        if (taken >= count)
+            break;
+        yield value;
+        taken++;
+    }
+}
+/**
+ * Merge multiple message streams into one.
+ *
+ * Yields messages from all streams as they arrive.
+ * Completes when all source streams complete.
+ *
+ * @param streams - Array of source streams
+ * @returns Async iterable of merged messages
+ *
+ * @example
+ * ```typescript
+ * const stream1 = agent.subscribe({ from: 'did:key:alice' });
+ * const stream2 = agent.subscribe({ from: 'did:key:bob' });
+ * const merged = mergeStreams([stream1, stream2]);
+ *
+ * for await (const message of merged) {
+ *   console.log('From:', message.sender);
+ * }
+ * ```
+ */
+async function* mergeStreams(streams) {
+    const iterators = streams.map((s) => s[Symbol.asyncIterator]());
+    const pending = new Map();
+    // Start all iterators
+    for (let i = 0; i < iterators.length; i++) {
+        pending.set(i, iterators[i].next());
+    }
+    while (pending.size > 0) {
+        // Race all pending next() calls
+        const entries = Array.from(pending.entries());
+        const winner = await Promise.race(entries.map(async ([idx, promise]) => ({ idx, result: await promise })));
+        pending.delete(winner.idx);
+        if (!winner.result.done) {
+            yield winner.result.value;
+            // Start next iteration for this stream
+            pending.set(winner.idx, iterators[winner.idx].next());
+        }
+    }
+}
+/**
+ * Add subscribe method to Agent prototype.
+ * @internal
+ */
+function installAsyncIterators(AgentClass) {
+    if ('subscribe' in AgentClass.prototype) {
+        return; // Already installed
+    }
+    AgentClass.prototype.subscribe = function (options) {
+        return new MessageStream(this, options);
+    };
+}