@wiro-ai/wiro-mcp 1.4.1 → 1.5.1

package/dist/tools/manage-agent-billing.js

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { ApiResultError, asString, errorResult, errorText, isPlainObject, requireApiSuccess, toNumber, unixToIso, } from '../utils/api.js';
-import { workspaceHint } from '../utils/agent-config.js';
+import { daysLeftText, readPlanChange, underOneDayLeft, workspaceHint } from '../utils/agent-config.js';
 import { DEFAULT_WAIT_SECONDS } from '../utils/poll.js';
 import { isPlainTeamMember, teamAgentBillingRefused } from '../utils/workspace.js';
-import { AMOUNT_TOLERANCE_USD, agentDashboardUrl, agentSummarySchema, asTier, chargeRoute, formatAgentSummaryLines, formatCredits, formatUsd, outcomeUnknown, readAgentDetail, roundUsd, sameAmount, toAgentDetail, toAgentSummary, } from '../utils/user-agent.js';
-import { nextActionSchema } from './schemas.js';
+import { AMOUNT_TOLERANCE_USD, WALLET_NOT_READ_NOTE, agentDashboardUrl, agentSummarySchema, asTier, chargeRoute, formatAgentSummaryLines, formatCredits, formatUsd, isTransitionalStatus, isWalletNotRead, outcomeUnknown, readAgentDetail, roundUsd, sameAmount, toAgentDetail, toAgentSummary, } from '../utils/user-agent.js';
+import { nextActionSchema, strictInput } from './schemas.js';
 const ACTIONS = ['subscribe', 'upgrade_to_pro', 'cancel', 'renew', 'buy_credits'];
 const quoteSchema = z.object({
     chargeNowUsd: z.number().nullable(),
@@ -13,6 +13,8 @@ const quoteSchema = z.object({
     maxChargeUsd: z.number().optional(),
     recurringUsd: z.number().nullable().optional(),
     monthlyCredits: z.number().nullable().optional(),
+    creditsNow: z.number().optional()
+        .describe('upgrade_to_pro: the credits this period gains now, below 0 when it loses them. monthlyCredits is what every renewal gives.'),
     creditsAdded: z.number().optional(),
     paidFrom: z.enum(['personal_wallet', 'team_wallet', 'card']),
     tier: z.enum(['starter', 'pro']).optional(),
@@ -22,6 +24,8 @@ const resultSchema = z.object({
     chargedUsd: z.number().nullable().optional(),
     monthlyPriceUsd: z.number().optional(),
     monthlyCredits: z.number().optional(),
+    creditsNow: z.number().optional()
+        .describe('upgrade_to_pro: the credits this period gained with it, below 0 when it lost them. monthlyCredits is what every renewal gives.'),
     creditsAdded: z.number().optional(),
     tier: z.string().optional(),
     previousTier: z.string().optional(),
@@ -46,20 +50,114 @@ function waitAction(guid, reason) {
         reason,
     };
 }
+/**
+ * The wait after an upgrade, a pack or a renewal, which keep a running agent up:
+ * only an agent on its way, one that was stopping (it starts again) or one queued
+ * or starting, is worth waiting for.
+ */
+function waitIfStarting(agent) {
+    return isTransitionalStatus(agent.status)
+        ? waitAction(agent.guid, 'Wait until the agent is running.')
+        : undefined;
+}
+/** After a renewal, Wiro queues a stopped or failed agent; a running one keeps running. */
+function renewWait(agent) {
+    if (agent.status === 0 || agent.status === 5)
+        return waitAction(agent.guid, 'Wait until the agent is running again.');
+    return waitIfStarting(agent);
+}
+/**
+ * A new plan queues a stopped or failed agent, and one waiting for setup; a
+ * running one keeps running, and one that was stopping starts again. An agent
+ * without a plan runs only while extra credits last.
+ */
+function subscribeStarts(status) {
+    return status !== 4;
+}
+function subscribeQuoteNote(status) {
+    switch (status) {
+        case 4:
+            return 'The agent keeps running: a new plan does not restart it.';
+        case 3:
+            return 'The agent is starting, and a new plan does not restart it.';
+        case 1:
+            return 'The agent is stopping, and it starts again right after the payment.';
+        case 2:
+            return 'The agent is already queued to start.';
+        default:
+            return 'The agent is queued to start right after the payment.';
+    }
+}
+function subscribeWait(agent) {
+    return subscribeStarts(agent.status) ? waitAction(agent.guid, 'Wait until the agent is running.') : undefined;
+}
+/** What an upgrade does to this period's credits. An allowance above Pro's is cut to Pro's for the time left. */
+function upgradeCreditsText(creditsNow, renewal, done) {
+    if (creditsNow > 0) {
+        return `${formatCredits(creditsNow)} credits ${done ? 'came with it' : 'come now'} for the rest of this period${renewal}. `;
+    }
+    if (creditsNow < 0)
+        return `This period ${done ? 'lost' : 'loses'} ${formatCredits(-creditsNow)} credits for the time left${renewal}. `;
+    return `This period ${done ? 'kept' : 'keeps'} the credits it ${done ? 'had' : 'has'}${renewal}. `;
+}
+/** What a change to the plan does to the agent: a running one keeps running, and one that was stopping starts again. */
+function planChangeAgentNote(status, what, quote = false) {
+    switch (status) {
+        case 4:
+            return `The agent keeps running: ${what} does not restart it.`;
+        case 3:
+            return `The agent is starting, and ${what} does not restart it.`;
+        case 1:
+            return quote
+                ? 'The agent is stopping; if it is still stopping when the payment goes through, it starts again.'
+                : 'The agent was stopping, and it starts again.';
+        case 2:
+            return 'The agent is queued to start.';
+        case 6:
+            return 'The agent still needs setup; the credits are there once it starts.';
+        case 0:
+            return 'The agent is stopped; the credits are there when it starts.';
+        case 5:
+            return 'The agent stopped with an error; the credits are there when it starts.';
+        default:
+            return 'The credits are there when the agent starts.';
+    }
+}
+/**
+ * The Pro price of this agent and what moving to it does today, as Wiro works it
+ * out on the plan the agent has now. null when it cannot be read: the quote then
+ * falls back to the Pro price the agent shows and to the most the upgrade can charge.
+ */
+async function readProPreview(client, guid, signal) {
+    try {
+        const body = requireApiSuccess(await client.post('/UserAgent/PricingPreview', { useragentguid: guid, tier: 'pro' }, signal), 'The Pro price could not be read.');
+        const priceUsd = toNumber(body.totalPriceUsd);
+        const monthlyCredits = toNumber(body.totalMonthlyCredits);
+        return {
+            price: priceUsd !== null && monthlyCredits !== null ? { priceUsd, monthlyCredits } : null,
+            change: readPlanChange(body.planChange),
+        };
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        return null;
+    }
+}
 function tierName(tier) {
     return tier === 'pro' ? 'Pro' : 'Starter';
 }
-/** The amount a confirmed call charges now, or null when it charges nothing. */
+/** The amount a confirmed call charges now, or at most when that is worked out only then; null when it charges nothing. */
 function chargeOf(quote) {
-    const amount = quote?.chargeNowUsd ?? null;
+    const amount = quote?.chargeNowUsd ?? quote?.maxChargeUsd ?? null;
     return amount !== null && amount > 0 ? amount : null;
 }
 /**
  * The amount the user approves with confirm_charge_usd, or null when the
- * call charges nothing. Wiro prorates an upgrade over the real length of
- * the billing period, which the 30-day estimate does not know, so an upgrade
- * is approved at its maximum: the full price difference, which the prorated
- * charge never exceeds.
+ * call charges nothing. An upgrade is approved at the most it can charge: the
+ * amount Wiro works out for a wallet plan, which only shrinks as the period
+ * runs on, or the full price difference when Wiro works the amount out only
+ * at the upgrade.
  */
 function approvalAmountOf(action, quote) {
     if (action !== 'upgrade_to_pro')
@@ -96,7 +194,7 @@ function changedLead(action, amount, approved, callerRequestId) {
     }
     return `${changed} Nothing was charged. Show the new amount to the user and ask again.`;
 }
-function planFor(client, action, agent, raw, input) {
+async function planFor(client, action, agent, raw, input, signal) {
     const guid = agent.guid;
     const active = raw?.status === 'active';
     const prepaid = raw?.provider === 'prepaid';
@@ -130,7 +228,7 @@ function planFor(client, action, agent, raw, input) {
                     tier,
                 },
                 message: `Subscribe on ${tierName(tier)}: ${formatUsd(price.priceUsd)} now from ${wallet}, then every 30 days until the plan is cancelled, with ${formatCredits(price.monthlyCredits)} credits per month. `
-                    + 'The agent is queued to start right after the payment.'
+                    + subscribeQuoteNote(agent.status)
                     + (missing.length > 0
                         ? ` Missing credentials (${missing.map(item => item.title).join(', ')}) can be added afterwards; until then the skills that need them fail.`
                         : ''),
@@ -144,9 +242,10 @@ function planFor(client, action, agent, raw, input) {
                     const credits = toNumber(body.monthlycredits) ?? price.monthlyCredits;
                     return {
                         outcome: 'done',
-                        message: `Subscribed on ${tierName(tier)} and charged ${formatUsd(charged)} from ${wallet}. The plan renews every 30 days until it is cancelled. The agent is starting.`,
+                        message: `Subscribed on ${tierName(tier)} and charged ${formatUsd(charged)} from ${wallet}. The plan renews every 30 days until it is cancelled. `
+                            + (subscribeStarts(agent.status) ? 'The agent is starting.' : 'The agent keeps running: a new plan does not restart it.'),
                         result: { chargedUsd: charged, monthlyPriceUsd: charged, monthlyCredits: credits, tier },
-                        nextAction: waitAction(guid, 'Wait until the agent is running.'),
+                        nextAction: subscribeWait(agent),
                     };
                 },
             };
@@ -177,10 +276,10 @@ function planFor(client, action, agent, raw, input) {
                 if (!cancelled) {
                     return { outcome: 'not_needed', message: 'The plan is active and renews by itself. Nothing to do.' };
                 }
-                const amount = agent.subscription?.amountUsd ?? agent.monthlyPriceUsd;
+                const amount = agent.monthlyPriceUsd || agent.subscription?.amountUsd;
                 return {
                     outcome: 'quote',
-                    quote: { chargeNowUsd: 0, estimated: false, recurringUsd: amount, monthlyCredits: agent.credits.monthly, paidFrom },
+                    quote: { chargeNowUsd: 0, estimated: false, recurringUsd: amount, monthlyCredits: agent.credits.renewal ?? agent.credits.monthly, paidFrom },
                     message: `Undo the cancellation: nothing is charged now. The plan then renews from ${wallet} for ${formatUsd(amount)} after ${periodEnd} and every 30 days after that until it is cancelled.`,
                     confirmReason: 'Ask the user to confirm first: the plan will charge the wallet again at each renewal.',
                     perform: async (signal) => {
@@ -240,7 +339,7 @@ function planFor(client, action, agent, raw, input) {
                             ...(credits !== null ? { monthlyCredits: credits } : {}),
                             renewal: 'renewed',
                         },
-                        nextAction: waitAction(guid, 'Wait until the agent is running again.'),
+                        nextAction: renewWait(agent),
                     };
                 },
             };
@@ -258,16 +357,17 @@ function planFor(client, action, agent, raw, input) {
                 };
             };
             if (!prepaid) {
-                if (agent.workspace === 'personal') {
+                // A plan moving to wallet billing has no cancel in the dashboard either: it can be cancelled once the wallet bills it.
+                if (raw?.nextprovider === 'prepaid') {
                     return {
                         outcome: 'refused',
-                        message: `This plan is billed by card. Card plans are cancelled from the dashboard: ${agent.dashboardUrl}`,
+                        message: `A switch to wallet billing is already scheduled for this plan, so it cannot be cancelled now. After ${periodEnd} it is billed from the wallet, and action cancel then stops its renewals.`,
                     };
                 }
-                if (raw?.nextprovider === 'prepaid') {
+                if (agent.workspace === 'personal') {
                     return {
                         outcome: 'refused',
-                        message: 'A switch to wallet billing is already scheduled for this plan, so it cannot be cancelled here.',
+                        message: `This plan is billed by card. Card plans are cancelled from the dashboard: ${agent.dashboardUrl}`,
                     };
                 }
                 if (agent.subscription?.cancelAtPeriodEnd) {
@@ -294,6 +394,14 @@ function planFor(client, action, agent, raw, input) {
         }
         case 'upgrade_to_pro': {
             if (!active) {
+                // A Pro plan that ended comes back at its own price with renew. Subscribe takes today's price.
+                if (agent.tier === 'pro' && raw?.status === 'expired' && prepaid) {
+                    return {
+                        outcome: 'refused',
+                        message: 'This agent is already on Pro, and its plan has ended. Action renew brings the plan back at its own price; subscribe starts a new plan at today\'s price.',
+                        nextAction: billingCall(guid, 'renew'),
+                    };
+                }
                 return {
                     outcome: 'refused',
                     message: 'Upgrading needs an active plan. Use action subscribe with tier pro instead.',
@@ -305,32 +413,42 @@ function planFor(client, action, agent, raw, input) {
             // No checkout pages are opened for card plans: the user pays them in the dashboard.
             if (route === 'card')
                 return { outcome: 'refused', message: cardPlan('upgrade it to Pro') };
-            const pro = agent.pricing?.pro;
+            const preview = await readProPreview(client, guid, signal);
+            const pro = preview?.price ?? agent.pricing?.pro;
             if (!pro)
                 throw new Error('The Pro price of this agent is not available right now. Try again later.');
-            const ending = `The plan is cancelled, so it ends about a day after ${periodEnd} and does not renew at the Pro price; this charge covers only the days left. To keep the plan, undo the cancellation first with action renew.`;
-            const current = agent.monthlyPriceUsd ?? agent.subscription?.amountUsd ?? 0;
-            const periodEndSeconds = toNumber(raw?.currentperiodend);
-            const daysLeft = periodEndSeconds !== null
-                ? Math.max(0, Math.round((periodEndSeconds - Date.now() / 1000) / 86_400))
-                : 30;
-            const maxCharge = roundUsd(Math.max(0, pro.priceUsd - current));
-            const estimate = roundUsd(Math.max(0, ((pro.priceUsd - current) / 30) * daysLeft));
+            const ending = `The plan is cancelled, so it ends about a day after ${periodEnd} and does not renew at the Pro price; this charge covers only the time left. To keep the plan, undo the cancellation first with action renew.`;
+            const current = agent.monthlyPriceUsd || agent.subscription?.amountUsd || 0;
+            const fullDifference = roundUsd(Math.max(0, pro.priceUsd - current));
+            // A wallet plan pays the amount Wiro works out on it now. A card plan moving to wallet billing is
+            // charged from the wallet for the time left of its card period, which Wiro works out at the upgrade.
+            const change = preview?.change?.wallet ? preview.change : null;
+            const exact = change?.chargeNowUsd ?? null;
+            const renewalCredits = change?.creditsFromRenewal ?? pro.monthlyCredits;
+            const creditsNow = change?.creditsNow ?? null;
+            const days = daysLeftText(change?.secondsLeft ?? null);
+            const money = exact !== null
+                ? `Upgrade to Pro: ${formatUsd(exact)} now from ${wallet} for the rest of this period`
+                    + `${exact > 0 && underOneDayLeft(change?.secondsLeft ?? null) ? ', at the one-day minimum' : days ? ` (${days})` : ''}. `
+                : `Upgrade to Pro: the difference for the rest of this period is taken from ${wallet} now. Wiro works it out from the time left when the upgrade is applied, and it is never more than ${formatUsd(fullDifference)}, so that is the amount to approve. `;
+            const credits = creditsNow !== null
+                ? upgradeCreditsText(creditsNow, cancelled ? '' : `, and every renewal gives ${formatCredits(renewalCredits)}`, false)
+                : `The added credits come for the time left in this period${cancelled ? '' : `, and every renewal gives ${formatCredits(renewalCredits)}`}. `;
             return {
                 outcome: 'quote',
                 quote: {
-                    chargeNowUsd: estimate,
-                    estimated: true,
-                    maxChargeUsd: maxCharge,
+                    chargeNowUsd: exact,
+                    estimated: exact === null,
+                    maxChargeUsd: exact ?? fullDifference,
                     recurringUsd: cancelled ? null : pro.priceUsd,
-                    monthlyCredits: pro.monthlyCredits,
+                    monthlyCredits: renewalCredits,
+                    ...(creditsNow !== null ? { creditsNow } : {}),
                     paidFrom,
                     tier: 'pro',
                 },
-                message: `Upgrade to Pro: about ${formatUsd(estimate)} now from ${wallet} for the ${daysLeft} days left in this period. `
-                    + `Wiro works out the exact amount from the real length of the billing period, and it is never more than ${formatUsd(maxCharge)}, so that is the amount to approve. `
+                message: money + credits
                     + (cancelled ? `${ending} ` : `From the next renewal the plan costs ${formatUsd(pro.priceUsd)} every 30 days. `)
-                    + `The monthly pool rises to ${formatCredits(pro.monthlyCredits)} credits at once and the agent restarts. To go back to Starter later, cancel, let the plan end, then subscribe to Starter.`,
+                    + `${planChangeAgentNote(agent.status, 'the upgrade', true)} To go back to Starter later, cancel, let the plan end, then subscribe to Starter.`,
                 perform: async (signal) => {
                     const body = requireApiSuccess(await client.post('/UserAgent/UpgradeTier', { guid, targetTier: 'pro' }, signal), 'The plan could not be upgraded.');
                     if (asString(body.url)) {
@@ -339,23 +457,28 @@ function planFor(client, action, agent, raw, input) {
                     }
                     const charged = toNumber(body.proratedCharge);
                     const newPrice = toNumber(body.newPriceUsd) ?? pro.priceUsd;
-                    const newCredits = toNumber(body.newMonthlyCredits) ?? pro.monthlyCredits;
+                    const fromRenewal = toNumber(body.creditsFromRenewal) ?? toNumber(body.newMonthlyCredits) ?? renewalCredits;
+                    const came = toNumber(body.creditsNow);
                     const previousTier = asString(body.previousTier);
                     return {
                         outcome: 'done',
                         message: `Upgraded to Pro and charged ${formatUsd(charged ?? 0)} from ${wallet}. `
+                            + (came !== null
+                                ? upgradeCreditsText(came, cancelled ? '' : `, and every renewal gives ${formatCredits(fromRenewal)}`, true)
+                                : '')
                             + (cancelled
                                 ? `The plan is still cancelled and ends about a day after ${periodEnd}; action renew undoes the cancellation. `
                                 : `The plan now costs ${formatUsd(newPrice)} every 30 days. `)
-                            + `The monthly pool is ${formatCredits(newCredits)} credits. The agent restarts.`,
+                            + planChangeAgentNote(agent.status, 'the upgrade'),
                         result: {
                             chargedUsd: charged,
                             monthlyPriceUsd: newPrice,
-                            monthlyCredits: newCredits,
+                            monthlyCredits: fromRenewal,
+                            ...(came !== null ? { creditsNow: came } : {}),
                             tier: 'pro',
                             ...(previousTier ? { previousTier } : {}),
                         },
-                        nextAction: waitAction(guid, 'Wait until the agent is running again.'),
+                        nextAction: waitIfStarting(agent),
                     };
                 },
             };
@@ -378,6 +501,7 @@ function planFor(client, action, agent, raw, input) {
             if (!input.pack) {
                 return {
                     outcome: 'refused',
+                    ...(packs.length > 0 ? { heading: 'Available packs' } : {}),
                     message: packs.length > 0 ? `Choose a pack: ${packList}.` : 'No extra credit packs are available for this agent yet.',
                     ...(packs[0] ? { nextAction: billingCall(guid, 'buy_credits', { pack: packs[0].pack }) } : {}),
                 };
@@ -392,7 +516,7 @@ function planFor(client, action, agent, raw, input) {
             return {
                 outcome: 'quote',
                 quote: { chargeNowUsd: chosen.priceUsd, estimated: false, creditsAdded: chosen.credits, paidFrom, pack: chosen.pack },
-                message: `Buy the ${chosen.pack} pack: ${formatUsd(chosen.priceUsd)} now from ${wallet} for ${formatCredits(chosen.credits)} extra credits, added at once. Extra credits are used after the monthly credits and do not reset each month. The agent restarts to pick them up. This is a one-time charge.`,
+                message: `Buy the ${chosen.pack} pack: ${formatUsd(chosen.priceUsd)} now from ${wallet} for ${formatCredits(chosen.credits)} extra credits, added at once. Extra credits are used after the monthly credits, do not reset each month and end 6 months (180 days) after purchase. ${planChangeAgentNote(agent.status, 'a credit pack', true)} This is a one-time charge.`,
                 perform: async (signal) => {
                     const body = requireApiSuccess(await client.post('/UserAgent/CreateExtraCreditCheckout', {
                         useragentguid: guid,
@@ -403,9 +527,9 @@ function planFor(client, action, agent, raw, input) {
                         return { outcome: 'refused', message: cardPlan('buy the pack') };
                     return {
                         outcome: 'done',
-                        message: `Bought the ${chosen.pack} pack: ${formatCredits(chosen.credits)} credits for ${formatUsd(chosen.priceUsd)} from ${wallet}. The credits are added and the agent restarts to pick them up.`,
+                        message: `Bought the ${chosen.pack} pack: ${formatCredits(chosen.credits)} credits for ${formatUsd(chosen.priceUsd)} from ${wallet}. The credits are added. ${planChangeAgentNote(agent.status, 'a credit pack')}`,
                         result: { chargedUsd: chosen.priceUsd, creditsAdded: chosen.credits },
-                        nextAction: waitAction(guid, 'Wait until the agent is running again.'),
+                        nextAction: waitIfStarting(agent),
                     };
                 },
             };
@@ -464,7 +588,6 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
     }
     const after = toAgentDetail(row);
     const charged = chargeOf(quote);
-    const restart = waitAction(before.guid, 'Wait until the agent is running again.');
     switch (action) {
         case 'subscribe':
             return after.subscription?.status === 'active'
@@ -473,7 +596,7 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
                     row,
                     text: 'The agent now has an active plan, so the payment went through. Do not subscribe again.',
                     result: { chargedUsd: charged, ...(quote?.tier ? { tier: quote.tier } : {}) },
-                    nextAction: waitAction(before.guid, 'Wait until the agent is running.'),
+                    nextAction: subscribeWait(before),
                 }
                 : { happened: false, text: 'The agent shows no active plan yet. Check get_my_agent again in a minute and the wallet balance with get_account before trying again; if the plan is still not active but the balance changed, contact Wiro support.' };
         case 'renew':
@@ -483,7 +606,7 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
                     row,
                     text: 'The plan is active again, so the renewal went through. Do not renew it again.',
                     result: { chargedUsd: charged, renewal: 'renewed' },
-                    nextAction: restart,
+                    nextAction: renewWait(before),
                 }
                 : { happened: false, text: 'The plan still shows as expired. Check get_my_agent again in a minute and the wallet balance with get_account before renewing again; if the plan is still expired but the balance changed, contact Wiro support.' };
         case 'upgrade_to_pro': {
@@ -493,7 +616,7 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
                     row,
                     text: `The agent is on Pro now, so the upgrade went through. Do not upgrade again. The prorated charge is not shown, and it is at most ${formatUsd(quote?.maxChargeUsd)}.`,
                     result: { chargedUsd: null, tier: 'pro' },
-                    nextAction: restart,
+                    nextAction: waitIfStarting(before),
                 };
             }
             const proPrice = before.pricing?.pro.priceUsd;
@@ -516,7 +639,7 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
                     row,
                     text: `The agent's extra credits rose by ${formatCredits(rose)}, so the purchase went through. Do not buy it again.`,
                     result: bought,
-                    nextAction: restart,
+                    nextAction: waitIfStarting(before),
                 };
             }
             const fresh = await freshPackShows(client, before.guid, credits, sentAtMs, signal);
@@ -541,8 +664,15 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
             return { happened: false, text: '' };
     }
 }
-function annotateKnownRefusal(error) {
+// Code 104: another payment from the same wallet, or another change to the agent's plan, was going through.
+const BUSY_NOTE = 'Nothing was charged or changed, and it is not a low balance. Offer to try again in a minute.';
+function annotateKnownRefusal(error, requestId) {
     const text = error.message;
+    if (error.codes.some(code => Number(code) === 104)) {
+        return new Error(`${text}\n\n${BUSY_NOTE}${requestId ? ` To try again, repeat the call with request_id "${requestId}"; that request id never charges twice.` : ''}`);
+    }
+    if (isWalletNotRead(error))
+        return new Error(`${text}\n\n${WALLET_NOT_READ_NOTE}`);
     if (/insufficient wallet balance/i.test(text)) {
         return new Error(`${text}\n\nNothing was charged. Funds are added at https://wiro.ai/panel/wallet/deposit/credit-card (for a team project, select that team in the dashboard first); once the user has added them and says yes, try again. get_account shows the balance.`);
     }
@@ -560,19 +690,23 @@ export function registerManageAgentBilling(server, client) {
         description: 'Pay for, renew, upgrade or cancel a deployed agent\'s plan, or buy extra credits. Charges '
             + 'come from the Wiro wallet of the agent\'s workspace (the team wallet for a team agent); the connected '
             + 'project must belong to that same workspace. Every call without confirm: true only returns what will happen '
-            + 'and the amount (for a prorated upgrade, an estimate and its maximum). Show it to the user, get '
+            + 'and the amount (for an upgrade, the prorated amount Wiro works out, or the most it can charge when '
+            + 'that is worked out only at the upgrade). Show it to the user, get '
             + 'their approval, then repeat the call with confirm: true and confirm_charge_usd set to the quoted '
-            + 'amount (for an upgrade, its maximum); if the price changed in between, nothing is charged and a '
+            + 'amount (for an upgrade, quote.maxChargeUsd); if the price changed in between, nothing is charged and a '
             + 'new quote comes back. Never repeat a confirmed charge that failed or timed out without checking '
             + 'get_my_agent first. '
             + 'subscribe starts a plan for an agent without one; renew undoes a cancellation or renews an expired '
             + 'wallet plan; upgrade_to_pro charges the prorated difference now; buy_credits adds a credit pack '
-            + '(Pro only); cancel stops renewals with no refund. Plans renew every 30 days until cancelled. An '
+            + '(Pro only); cancel stops renewals with no refund. Plans renew every 30 days until cancelled. Renewals, '
+            + 'upgrades and packs leave a running agent running. An '
             + 'agent whose plan is billed by card is upgraded and topped up in the Wiro dashboard, and a personal '
-            + 'card plan is cancelled there; the tool returns the link and charges nothing. On a team agent only a team '
+            + 'card plan is cancelled there; the tool returns the link and charges nothing. A card plan that is moving to '
+            + 'wallet billing pays upgrade_to_pro and buy_credits from the wallet, and cancel works once the wallet bills it. '
+            + 'On a team agent only a team '
             + 'admin, the organization\'s owner or the person who deployed the agent can pay for it or change its plan; '
             + 'other members are refused and nothing is charged.',
-        inputSchema: {
+        inputSchema: strictInput({
             agent_guid: z.string().min(1).max(100)
                 .describe('The deployed agent\'s guid, from list_my_agents or deploy_agent.'),
             action: z.enum(ACTIONS)
@@ -587,7 +721,7 @@ export function registerManageAgentBilling(server, client) {
                 .describe('With confirm: true, the amount the user approved, from the quote\'s nextAction (quote.chargeNowUsd, or quote.maxChargeUsd for upgrade_to_pro). Required for every action that charges: subscribe, upgrade_to_pro, buy_credits and renewing an expired plan. If a fresh quote no longer matches it, nothing is charged and the new quote is returned. For upgrade_to_pro it is the most the user agreed to pay now.'),
             confirm: z.boolean().default(false)
                 .describe('false returns only the quote. true performs the action. Set it only after the user approved it.'),
-        },
+        }),
         outputSchema: {
             action: z.enum(ACTIONS),
             agentGuid: z.string(),
@@ -618,7 +752,7 @@ export function registerManageAgentBilling(server, client) {
             const summary = toAgentSummary(payload.agentRow);
             const summaryLines = formatAgentSummaryLines(summary, plainMember);
             const dashboardUrl = before?.dashboardUrl ?? agentDashboardUrl(guid);
-            const heading = {
+            const heading = payload.heading ?? {
                 quote: 'Quote (nothing done yet)',
                 done: 'Done',
                 not_needed: 'Nothing to do',
@@ -657,9 +791,9 @@ export function registerManageAgentBilling(server, client) {
             before = agent;
             plainMember = await isPlainTeamMember(client, row, extra.signal);
             const raw = isPlainObject(row.subscription) ? row.subscription : null;
-            plan = planFor(client, action, agent, raw, { tier, pack, requestId: requestId ?? '' });
+            plan = await planFor(client, action, agent, raw, { tier, pack, requestId: requestId ?? '' }, extra.signal);
             if (plan.outcome !== 'quote' || !plan.perform) {
-                return respond({ outcome: plan.outcome, message: plan.message, nextAction: plan.nextAction, agentRow: row });
+                return respond({ outcome: plan.outcome, heading: plan.heading, message: plan.message, nextAction: plan.nextAction, agentRow: row });
             }
             // A team member without admin rights can still be the person who
             // deployed the agent, who may pay for it, so Wiro is asked before a quote.
@@ -728,6 +862,20 @@ export function registerManageAgentBilling(server, client) {
                         agentRow: after,
                     });
                 }
+                // A repeat adds no credits. A new pack can add none only when an older
+                // pack ends at the same moment with at least as many left, so an answer
+                // with no growth says only what holds in both cases.
+                if (fresh && extraAfter <= extraBefore) {
+                    return respond({
+                        outcome: 'done',
+                        heading: 'Pack in place',
+                        message: `The ${plan.quote?.pack} pack is in place: ${formatCredits(credits)} credits for ${formatUsd(plan.quote?.chargeNowUsd)} from ${agent.workspace === 'team' ? 'the team wallet' : 'the personal wallet'}. This request id is charged only once. The agent's extra credits did not grow in this call, so if the id had already completed in an earlier call, nothing new was bought or charged now. ${planChangeAgentNote(agent.status, 'a credit pack')} For another pack, get a new quote without request_id.`,
+                        quote: plan.quote,
+                        result: { chargedUsd: null },
+                        nextAction: performed.nextAction,
+                        agentRow: after,
+                    });
+                }
                 return respond({
                     outcome: 'done',
                     message: fresh
@@ -780,7 +928,7 @@ export function registerManageAgentBilling(server, client) {
                 return errorResult(new Error(`${text}\n\nThe request was sent and the answer does not show whether it went through. ${observed.text} ${retry}`));
             }
             if (error instanceof ApiResultError)
-                return errorResult(annotateKnownRefusal(error));
+                return errorResult(annotateKnownRefusal(error, sentAtMs > 0 ? requestId : undefined));
             return errorResult(error);
         }
     });