@agirails/sdk 3.3.0 → 3.5.3

package/dist/negotiation/BuyerOrchestrator.js

@@ -22,17 +22,142 @@ const agirailsApp_1 = require("../api/agirailsApp");
 const PolicyEngine_1 = require("./PolicyEngine");
 const DecisionEngine_1 = require("./DecisionEngine");
 const SessionStore_1 = require("./SessionStore");
-// ============================================================================
-// BuyerOrchestrator
-// ============================================================================
+const QuoteBuilder_1 = require("../builders/QuoteBuilder");
+const CounterOfferBuilder_1 = require("../builders/CounterOfferBuilder");
+const NonceManager_1 = require("../utils/NonceManager");
+const verifyQuoteOnChain_1 = require("./verifyQuoteOnChain");
+const NegotiationChannel_1 = require("./NegotiationChannel");
 class BuyerOrchestrator {
-    constructor(policy, runtime, requesterAddress, actpDir) {
+    constructor(policy, runtime, requesterAddress, actpDir, negotiation = {}) {
+        /**
+         * Per-txId inbound message queue. Channel callbacks push here; the
+         * orchestrator's negotiation loop drains via `_waitForNextMessage`.
+         * Bounded implicitly by `_cleanupTxState` at terminal outcomes.
+         */
+        this.inboundQueues = new Map();
+        /**
+         * Per-txId resolver for the orchestrator's "wait for next message"
+         * await. When a message arrives and a resolver is set, the message
+         * is delivered immediately instead of queued.
+         */
+        this.inboundResolvers = new Map();
+        /**
+         * Active subscriptions opened by `negotiate()`. Closed at end of
+         * each negotiation. Multiple concurrent calls are supported.
+         */
+        this.activeSubscriptions = new Map();
+        // Fail-fast on partial negotiation context. Pre-fix bug: a developer
+        // who set `negotiationChannel: new RelayChannel(...)` but forgot
+        // `signer` or `chainId` got NO error — every tx silently fell
+        // through to fixed-price flow with the channel subscription
+        // opened-and-immediately-closed for nothing. (P1 audit finding: G.)
+        if (negotiation.negotiationChannel) {
+            const missing = [];
+            if (!negotiation.signer)
+                missing.push('signer');
+            if (!negotiation.kernelAddress)
+                missing.push('kernelAddress');
+            if (!negotiation.chainId)
+                missing.push('chainId');
+            if (missing.length > 0) {
+                throw new Error(`BuyerNegotiationContext: negotiationChannel was provided but the following required field(s) are missing: ${missing.join(', ')}. ` +
+                    `Multi-round negotiation needs all of: signer, kernelAddress, chainId, negotiationChannel. ` +
+                    `Omit negotiationChannel for fixed-price-only flow.`);
+            }
+        }
         this.policy = policy;
         this.runtime = runtime;
         this.requesterAddress = requesterAddress;
         this.policyEngine = new PolicyEngine_1.PolicyEngine(policy, actpDir);
         this.decisionEngine = new DecisionEngine_1.DecisionEngine(policy.selection.weights);
         this.sessionStore = new SessionStore_1.SessionStore(actpDir);
+        this.negotiation = negotiation;
+        if (negotiation.signer) {
+            this.counterBuilder = new CounterOfferBuilder_1.CounterOfferBuilder(negotiation.signer, negotiation.nonceManager ?? new NonceManager_1.InMemoryNonceManager());
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Channel inbound dispatch
+    // --------------------------------------------------------------------------
+    /**
+     * Channel delivered a verified message for `txId`. If a round is
+     * awaiting the next message, hand it directly; otherwise queue.
+     *
+     * NOTE: the channel has already verified EIP-712 signature + chainId
+     * before invoking us. This handler is concerned only with routing.
+     */
+    _onChannelMessage(txId, delivered) {
+        const resolver = this.inboundResolvers.get(txId);
+        if (resolver) {
+            this.inboundResolvers.delete(txId);
+            resolver(delivered.envelope);
+            return;
+        }
+        const queue = this.inboundQueues.get(txId) ?? [];
+        queue.push(delivered.envelope);
+        this.inboundQueues.set(txId, queue);
+    }
+    /**
+     * Await the next inbound message matching one of `acceptedTypes`.
+     * Returns null on timeout (caller decides how to handle: cancel,
+     * accept-if-affordable, etc).
+     *
+     * Drains the queue first so messages buffered while we were busy
+     * processing the previous round are picked up immediately.
+     */
+    _waitForNextMessage(txId, acceptedTypes, timeoutMs) {
+        return new Promise((resolve) => {
+            // Drain queue first — non-matching types stay queued for later.
+            const queue = this.inboundQueues.get(txId) ?? [];
+            const idx = queue.findIndex((m) => acceptedTypes.includes(m.type));
+            if (idx >= 0) {
+                const [msg] = queue.splice(idx, 1);
+                if (queue.length === 0)
+                    this.inboundQueues.delete(txId);
+                else
+                    this.inboundQueues.set(txId, queue);
+                resolve(msg);
+                return;
+            }
+            const timer = setTimeout(() => {
+                if (this.inboundResolvers.get(txId) === filteredResolver) {
+                    this.inboundResolvers.delete(txId);
+                }
+                resolve(null);
+            }, timeoutMs);
+            const filteredResolver = (msg) => {
+                if (acceptedTypes.includes(msg.type)) {
+                    clearTimeout(timer);
+                    resolve(msg);
+                }
+                else {
+                    // Wrong type — push back to queue, then re-drain queue
+                    // BEFORE re-registering as resolver. Pre-fix race (P1
+                    // audit finding: H): another correct-type message could
+                    // arrive in the same microtask between the resolver being
+                    // detached at _onChannelMessage and re-registered here,
+                    // landing in the queue and never waking us — we'd time out
+                    // with a correct-type message sitting unread.
+                    const q = this.inboundQueues.get(txId) ?? [];
+                    q.push(msg);
+                    const correctIdx = q.findIndex((m) => acceptedTypes.includes(m.type));
+                    if (correctIdx >= 0) {
+                        const [found] = q.splice(correctIdx, 1);
+                        if (q.length === 0)
+                            this.inboundQueues.delete(txId);
+                        else
+                            this.inboundQueues.set(txId, q);
+                        clearTimeout(timer);
+                        resolve(found);
+                    }
+                    else {
+                        this.inboundQueues.set(txId, q);
+                        this.inboundResolvers.set(txId, filteredResolver);
+                    }
+                }
+            };
+            this.inboundResolvers.set(txId, filteredResolver);
+        });
     }
     /**
      * Execute the full negotiation flow.
@@ -169,6 +294,14 @@ class BuyerOrchestrator {
                 emit({ type: 'round_end', round: round + 1, action: 'error', reason });
                 continue;
             }
+            // Open negotiation channel subscription for this txId. All inbound
+            // quote / counteraccept messages from the provider will land in
+            // our internal queue (via _onChannelMessage) for the negotiation
+            // round loop to consume. Subscription is closed in _cleanupTxState.
+            if (this.negotiation.negotiationChannel) {
+                const sub = this.negotiation.negotiationChannel.subscribeTxId(txId, (delivered) => this._onChannelMessage(txId, delivered));
+                this.activeSubscriptions.set(txId, sub);
+            }
             // 3c. Wait for quote or direct commit (ACTP allows INITIATED → COMMITTED fast path)
             emit({ type: 'waiting_quote', txId, ttlSeconds: quoteTtlSeconds });
             const reachedState = await this.waitForState(txId, ['QUOTED', 'COMMITTED'], quoteTtlSeconds * 1000, pollInterval);
@@ -189,6 +322,10 @@ class BuyerOrchestrator {
                     tx_id: txId,
                 });
                 emit({ type: 'round_end', round: round + 1, action: 'timeout', reason: 'Quote TTL expired' });
+                // External caller may have pushed a quote between createTransaction
+                // and timeout — clear so a long-running daemon doesn't accumulate
+                // entries in receivedQuotes / sentCounters.
+                this._cleanupTxState(txId);
                 continue;
             }
             emit({ type: 'quote_received', txId });
@@ -213,6 +350,48 @@ class BuyerOrchestrator {
             catch {
                 // Non-fatal — price tracking is best-effort
             }
+            // 3d-bis. AIP-2.1 negotiation branch: if the orchestrator has a
+            // negotiationChannel configured, drain the inbound queue for any
+            // quote that arrived via the channel and run the multi-round
+            // counter-offer loop. The branch ONLY triggers when reachedState
+            // === 'QUOTED' — the COMMITTED fast-path below bypasses negotiation
+            // entirely because the provider already locked the deal at buyer's
+            // offered amount.
+            if (reachedState === 'QUOTED' && this.negotiation.negotiationChannel) {
+                const negResult = await this._runNegotiationRound({
+                    txId,
+                    candidateSlug: candidate.slug,
+                    providerAddress,
+                    offer,
+                    round,
+                    rounds,
+                    emit,
+                });
+                if (negResult.done) {
+                    // Negotiation reached a terminal decision (accept or
+                    // reject) — short-circuit the existing escrow logic below.
+                    if (negResult.success) {
+                        this.sessionStore.linkTransaction(session.commerce_session_id, txId, candidate.slug);
+                        const negReason = negResult.reason ?? 'Negotiation complete';
+                        emit({ type: 'complete', success: true, reason: negReason });
+                        return {
+                            success: true,
+                            commerce_session_id: session.commerce_session_id,
+                            actp_tx_id: txId,
+                            selected_provider: candidate.slug,
+                            rounds_used: round + 1,
+                            reason: negReason,
+                            rounds,
+                            deadlock_detected: deadlockDetected,
+                        };
+                    }
+                    // negResult.success === false → candidate rejected; continue
+                    // outer loop to try the next one. The existing code below
+                    // would attempt linkEscrow at buyer's offered price, which
+                    // would happily succeed and silently ignore our rejection.
+                    continue;
+                }
+            }
             // 3e. Reserve budget and link escrow (or recognize already-committed).
             // ACTP invariant: tx.amount is immutable (set at createTransaction).
             // Policy was already validated pre-round, so offer.unit_price
@@ -239,6 +418,10 @@ class BuyerOrchestrator {
                 });
                 emit({ type: 'round_end', round: round + 1, action: 'accepted', reason });
                 emit({ type: 'complete', success: true, reason: 'Negotiation complete' });
+                // COMMITTED fast-path bypassed _runNegotiationRound (which is
+                // the usual cleanup site) — drop any stashed quote/counter
+                // state so daemon callers don't leak across negotiations.
+                this._cleanupTxState(txId);
                 return {
                     success: true,
                     commerce_session_id: session.commerce_session_id,
@@ -269,6 +452,9 @@ class BuyerOrchestrator {
                 });
                 emit({ type: 'round_end', round: round + 1, action: 'accepted', reason });
                 emit({ type: 'complete', success: true, reason: 'Negotiation complete' });
+                // Symmetric to the COMMITTED fast-path above — this success exit
+                // also bypassed _runNegotiationRound's cleanup site.
+                this._cleanupTxState(txId);
                 return {
                     success: true,
                     commerce_session_id: session.commerce_session_id,
@@ -294,6 +480,8 @@ class BuyerOrchestrator {
                     quoted_price: quotedPrice,
                 });
                 emit({ type: 'round_end', round: round + 1, action: 'error', reason });
+                // Same daemon-leak rationale as the timeout `continue` above.
+                this._cleanupTxState(txId);
                 continue;
             }
         }
@@ -313,6 +501,344 @@ class BuyerOrchestrator {
         };
     }
     // ============================================================================
+    // AIP-2.1 negotiation round
+    // ============================================================================
+    /**
+     * Run the multi-round AIP-2.1 negotiation flow for one provider/txId.
+     *
+     * Channel-driven: this method never reads `setReceivedQuote` state;
+     * all inbound messages flow through the orchestrator's NegotiationChannel
+     * subscription (opened in `_negotiate` after createTransaction).
+     *
+     * Inner loop walks up to `policy.negotiation.rounds_per_provider`
+     * counter exchanges:
+     *
+     *   await first quote (channel)
+     *   for round in 0..rounds_per_provider:
+     *     evaluate(currentQuote, roundsUsedSoFar = round)
+     *     accept  → on-chain acceptQuote+linkEscrow, return success
+     *     reject  → on-chain CANCELLED, return failure
+     *     counter → channel.post(counter), await NEXT message:
+     *               counteraccept → bind to last counter, on-chain accept+link, return success
+     *               new quote     → currentQuote = new quote, loop
+     *               timeout       → on-chain CANCELLED, return failure
+     *
+     * Returns `{done: false}` when the channel has no quote but the tx
+     * reached QUOTED via raw transitionState (legacy flow caller wants
+     * to fall through to fixed-price). Returns `{done: true, success?,
+     * reason?}` for any terminal outcome.
+     */
+    async _runNegotiationRound(args) {
+        const { txId, candidateSlug, providerAddress, offer, round, rounds, emit } = args;
+        // Cleanup hook fires on any `done: true` return — closes the channel
+        // subscription opened in _negotiate so daemon callers don't leak.
+        const terminate = (result) => {
+            this._cleanupTxState(txId);
+            return result;
+        };
+        if (!this.counterBuilder || !this.negotiation.kernelAddress || !this.negotiation.chainId) {
+            // Channel was provided but not the rest of the negotiation context.
+            // Fall through to fixed-price flow rather than try to negotiate.
+            this._cleanupTxState(txId);
+            return { done: false };
+        }
+        const counterTtlSec = this.policy.negotiation.counter_response_ttl_seconds
+            ?? PolicyEngine_1.PolicyEngine.parseTtl(this.policy.negotiation.quote_ttl);
+        const counterTtlMs = counterTtlSec * 1000;
+        const roundsBudget = this.policy.negotiation.rounds_per_provider ?? 1;
+        // Wait for the FIRST quote on the channel. The provider posts it
+        // after on-chain submitQuote — channel + chain may race so we
+        // also tolerate the quote arriving slightly before the kernel
+        // hash is readable (we re-read on-chain inside the loop).
+        const firstQuoteEnv = await this._waitForNextMessage(txId, ['agirails.quote.v1'], counterTtlMs);
+        if (!firstQuoteEnv || !(0, NegotiationChannel_1.isQuoteEnvelope)(firstQuoteEnv)) {
+            // No quote arrived on the channel within TTL — fall through to
+            // fixed-price (the on-chain hash + waitForState already proved
+            // the tx hit QUOTED, so this is a legacy-provider scenario).
+            this._cleanupTxState(txId);
+            return { done: false };
+        }
+        let currentQuote = firstQuoteEnv.message;
+        // Multi-round inner loop. Each iteration:
+        //  - on FIRST round: cross-check on-chain hash (anchored proof that
+        //    the off-chain quote we're seeing matches what provider committed
+        //    on-chain via submitQuote — defense against MITM substitution).
+        //  - on subsequent rounds: trust the channel's EIP-712 verify alone.
+        //    Re-quotes are off-chain only by design (kernel forbids QUOTED →
+        //    QUOTED on-chain transitions per Q4 audit). The provider DID is
+        //    already authenticated by the channel's signature recovery, and
+        //    the FINAL agreed amount is anchored on acceptQuote+linkEscrow.
+        let hashSource = 'aip2';
+        for (let counterRound = 0; counterRound < roundsBudget; counterRound++) {
+            if (counterRound === 0) {
+                const onChainTx = await this.runtime.getTransaction(txId);
+                const onChainHash = onChainTx && onChainTx.quoteHash;
+                if (!onChainHash) {
+                    // No anchored quote — fall through to fixed-price.
+                    this._cleanupTxState(txId);
+                    return { done: false };
+                }
+                const verify = (0, verifyQuoteOnChain_1.verifyQuoteHashOnChain)(currentQuote, onChainHash, {
+                    providerAddress: providerAddress,
+                });
+                if (!verify.match) {
+                    rounds.push({
+                        round: round + 1,
+                        provider_slug: candidateSlug,
+                        provider_address: providerAddress,
+                        action: 'error',
+                        reason: `Quote hash mismatch: expected ${verify.canonicalHash}, on-chain ${onChainHash}`,
+                        tx_id: txId,
+                    });
+                    emit({ type: 'round_end', round: round + 1, action: 'error', reason: 'Quote hash mismatch' });
+                    return terminate({ done: true, success: false, reason: 'hash mismatch' });
+                }
+                hashSource = verify.source;
+            }
+            else {
+                // Subsequent re-quotes: guard against two attacker-controlled
+                // mutations the channel-level EIP-712 verify cannot catch on
+                // its own (same provider can sign anything, including poisoned
+                // re-quotes):
+                //
+                //   (a) provider DID switched mid-negotiation
+                //   (b) maxPrice inflated mid-negotiation — without this
+                //       guard, the buyer's `evaluateQuote` accept-if-affordable
+                //       branch on the last round would compare against the
+                //       attacker's inflated max, committing the buyer above
+                //       its own policy ceiling. (P0 audit finding.)
+                //
+                // We anchor BOTH provider and maxPrice to the FIRST quote
+                // (which already cross-checked on-chain hash on round 0).
+                if (currentQuote.provider !== firstQuoteEnv.message.provider) {
+                    try {
+                        await this.runtime.transitionState(txId, 'CANCELLED');
+                    }
+                    catch { /* best-effort */ }
+                    rounds.push({
+                        round: round + 1,
+                        provider_slug: candidateSlug,
+                        provider_address: providerAddress,
+                        action: 'error',
+                        reason: `Re-quote provider mismatch: ${currentQuote.provider} vs original ${firstQuoteEnv.message.provider}`,
+                        tx_id: txId,
+                    });
+                    emit({ type: 'round_end', round: round + 1, action: 'error', reason: 'provider mismatch on re-quote' });
+                    return terminate({ done: true, success: false, reason: 'provider mismatch' });
+                }
+                if (currentQuote.maxPrice !== firstQuoteEnv.message.maxPrice) {
+                    try {
+                        await this.runtime.transitionState(txId, 'CANCELLED');
+                    }
+                    catch { /* best-effort */ }
+                    rounds.push({
+                        round: round + 1,
+                        provider_slug: candidateSlug,
+                        provider_address: providerAddress,
+                        action: 'error',
+                        reason: `Re-quote maxPrice mismatch: ${currentQuote.maxPrice} vs original ${firstQuoteEnv.message.maxPrice} — provider may not raise the ceiling mid-negotiation`,
+                        tx_id: txId,
+                    });
+                    emit({ type: 'round_end', round: round + 1, action: 'error', reason: 'maxPrice substitution attempt on re-quote' });
+                    return terminate({ done: true, success: false, reason: 'maxPrice substitution' });
+                }
+                hashSource = 'aip2';
+            }
+            const evaluation = this.decisionEngine.evaluateQuote(currentQuote, this.policy, counterRound);
+            // ----- reject -----
+            if (evaluation.action === 'reject') {
+                try {
+                    await this.runtime.transitionState(txId, 'CANCELLED');
+                }
+                catch { /* best-effort */ }
+                rounds.push({
+                    round: round + 1,
+                    provider_slug: candidateSlug,
+                    provider_address: providerAddress,
+                    action: 'rejected',
+                    reason: `${evaluation.reason} (round ${counterRound + 1}/${roundsBudget}, source: ${hashSource})`,
+                    tx_id: txId,
+                    quoted_price: this._baseUnitsForLog(currentQuote.quotedAmount),
+                });
+                emit({ type: 'round_end', round: round + 1, action: 'rejected', reason: evaluation.reason });
+                return terminate({ done: true, success: false, reason: evaluation.reason });
+            }
+            // ----- accept (at provider's quoted amount) -----
+            if (evaluation.action === 'accept') {
+                const result = await this._commitAtAmount(txId, currentQuote.quotedAmount, candidateSlug, providerAddress, offer, round, rounds, emit, hashSource, counterRound);
+                return terminate(result);
+            }
+            // ----- counter -----
+            // Build counter, post on channel, await next message.
+            let counter;
+            try {
+                const consumerDID = `did:ethr:${this.negotiation.chainId}:${(await this.negotiation.signer.getAddress()).toLowerCase()}`;
+                const now = Math.floor(Date.now() / 1000);
+                // inReplyTo is the canonical hash of the quote we're countering
+                // — recompute on every round (subsequent re-quotes have their
+                // own hash, distinct from the on-chain anchored first quote).
+                const currentQuoteHash = new QuoteBuilder_1.QuoteBuilder().computeHash(currentQuote);
+                counter = await this.counterBuilder.build({
+                    txId,
+                    consumer: consumerDID,
+                    provider: currentQuote.provider,
+                    quoteAmount: currentQuote.quotedAmount,
+                    counterAmount: evaluation.amountBaseUnits,
+                    maxPrice: currentQuote.maxPrice,
+                    inReplyTo: currentQuoteHash,
+                    chainId: this.negotiation.chainId,
+                    kernelAddress: this.negotiation.kernelAddress,
+                    expiresAt: now + counterTtlSec,
+                });
+            }
+            catch (err) {
+                const reason = `Counter build failed on round ${counterRound + 1}: ${err instanceof Error ? err.message : String(err)}`;
+                rounds.push({ round: round + 1, provider_slug: candidateSlug, provider_address: providerAddress, action: 'error', reason, tx_id: txId });
+                emit({ type: 'round_end', round: round + 1, action: 'error', reason });
+                return terminate({ done: true, success: false, reason });
+            }
+            try {
+                await this.negotiation.negotiationChannel.post(txId, {
+                    type: 'agirails.counteroffer.v1', message: counter,
+                });
+            }
+            catch (err) {
+                const reason = `Counter post failed on round ${counterRound + 1}: ${err instanceof Error ? err.message : String(err)}`;
+                rounds.push({ round: round + 1, provider_slug: candidateSlug, provider_address: providerAddress, action: 'error', reason, tx_id: txId });
+                emit({ type: 'round_end', round: round + 1, action: 'error', reason });
+                return terminate({ done: true, success: false, reason });
+            }
+            // Await provider's response: counteraccept (deal closed) or new quote (provider re-quote → next round).
+            const next = await this._waitForNextMessage(txId, ['agirails.counteraccept.v1', 'agirails.quote.v1'], counterTtlMs);
+            if (!next) {
+                try {
+                    await this.runtime.transitionState(txId, 'CANCELLED');
+                }
+                catch { /* best-effort */ }
+                const reason = `No response within ${counterTtlSec}s on round ${counterRound + 1}`;
+                rounds.push({ round: round + 1, provider_slug: candidateSlug, provider_address: providerAddress, action: 'timeout', reason, tx_id: txId });
+                emit({ type: 'round_end', round: round + 1, action: 'timeout', reason });
+                return terminate({ done: true, success: false, reason });
+            }
+            if ((0, NegotiationChannel_1.isCounterAcceptEnvelope)(next)) {
+                // Provider accepted our counter — verify binding (channel already
+                // verified EIP-712, here we bind to the counter WE sent).
+                const accept = next.message;
+                const counterHash = new CounterOfferBuilder_1.CounterOfferBuilder().computeHash(counter);
+                if (accept.txId !== txId ||
+                    accept.inReplyTo !== counterHash ||
+                    accept.acceptedAmount !== counter.counterAmount) {
+                    const reason = `CounterAccept binding mismatch on round ${counterRound + 1}`;
+                    rounds.push({ round: round + 1, provider_slug: candidateSlug, provider_address: providerAddress, action: 'error', reason, tx_id: txId });
+                    emit({ type: 'round_end', round: round + 1, action: 'error', reason });
+                    return terminate({ done: true, success: false, reason });
+                }
+                const result = await this._commitAtAmount(txId, accept.acceptedAmount, candidateSlug, providerAddress, offer, round, rounds, emit, 'counteraccept', counterRound);
+                return terminate(result);
+            }
+            if ((0, NegotiationChannel_1.isQuoteEnvelope)(next)) {
+                // Provider re-quoted — replace currentQuote and loop.
+                currentQuote = next.message;
+                continue;
+            }
+        }
+        // Budget exhausted without accept — DecisionEngine's last-round
+        // branch should have triggered accept-if-affordable; reaching here
+        // implies provider re-quoted to the very last round and we still
+        // saw 'counter'. Cancel.
+        try {
+            await this.runtime.transitionState(txId, 'CANCELLED');
+        }
+        catch { /* best-effort */ }
+        const reason = `Negotiation budget (${roundsBudget} rounds) exhausted without accept`;
+        rounds.push({ round: round + 1, provider_slug: candidateSlug, provider_address: providerAddress, action: 'timeout', reason, tx_id: txId });
+        emit({ type: 'round_end', round: round + 1, action: 'timeout', reason });
+        return terminate({ done: true, success: false, reason });
+    }
+    /**
+     * Shared accept+linkEscrow with atomic rollback. Used by both the
+     * "accept the quote" and "accept the counter" terminal branches.
+     */
+    async _commitAtAmount(txId, amountBaseUnits, candidateSlug, providerAddress, offer, round, rounds, emit, sourceTag, counterRound) {
+        let acceptQuoteSucceeded = false;
+        try {
+            await this.runtime.acceptQuote(txId, amountBaseUnits);
+            acceptQuoteSucceeded = true;
+            await this.runtime.linkEscrow(txId, amountBaseUnits);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            if (acceptQuoteSucceeded) {
+                try {
+                    await this.runtime.transitionState(txId, 'CANCELLED');
+                }
+                catch { /* best-effort */ }
+            }
+            rounds.push({
+                round: round + 1,
+                provider_slug: candidateSlug,
+                provider_address: providerAddress,
+                action: 'error',
+                reason: `Commit failed (round ${counterRound + 1}): ${reason}`,
+                tx_id: txId,
+            });
+            emit({ type: 'round_end', round: round + 1, action: 'error', reason });
+            return { done: true, success: false, reason };
+        }
+        try {
+            this.policyEngine.reserve(offer.commerce_session_id || '', this._baseUnitsForLog(amountBaseUnits), offer.currency);
+        }
+        catch { /* best-effort budget bookkeeping */ }
+        const reason = `Committed at ${amountBaseUnits} base units (round ${counterRound + 1}, source: ${sourceTag})`;
+        rounds.push({
+            round: round + 1,
+            provider_slug: candidateSlug,
+            provider_address: providerAddress,
+            action: 'accepted',
+            reason,
+            tx_id: txId,
+            quoted_price: this._baseUnitsForLog(amountBaseUnits),
+        });
+        emit({ type: 'round_end', round: round + 1, action: 'accepted', reason });
+        return { done: true, success: true, reason };
+    }
+    /**
+     * Free per-tx negotiation state at terminal outcomes (accept commits,
+     * reject CANCELLED, timeout). Closes the channel subscription too so
+     * long-running daemon callers don't leak inbound-message resolvers.
+     *
+     * Idempotent — safe to call from multiple cleanup sites.
+     */
+    _cleanupTxState(txId) {
+        this.inboundQueues.delete(txId);
+        const pending = this.inboundResolvers.get(txId);
+        if (pending) {
+            // No more messages will arrive for this tx; resolve waiter as
+            // a timeout-equivalent so awaiters don't hang.
+            this.inboundResolvers.delete(txId);
+            // Note: pending resolver expects a NegotiationMessage; we let
+            // the timeout in _waitForNextMessage fire instead by NOT
+            // calling pending here. The resolver is removed; setTimeout
+            // wins on its own clock.
+            void pending;
+        }
+        const sub = this.activeSubscriptions.get(txId);
+        if (sub) {
+            sub.unsubscribe();
+            this.activeSubscriptions.delete(txId);
+        }
+    }
+    /**
+     * Display-only downcast: USDC base-units string → Number for the
+     * RoundResult.quoted_price log field. Loses precision above
+     * Number.MAX_SAFE_INTEGER / 1e6 (~$9 quadrillion) but every
+     * comparison the orchestrator actually MAKES uses the bigint
+     * string. The on-chain tx.amount is the source of truth.
+     */
+    _baseUnitsForLog(baseUnitsStr) {
+        return Number(BigInt(baseUnitsStr)) / 1000000;
+    }
+    // ============================================================================
     // Helpers
     // ============================================================================
     /**