@wiro-ai/wiro-mcp 1.4.0 → 1.5.0

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

@@ -1,10 +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 { 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 { isPlainTeamMember, teamAgentBillingRefused } from '../utils/workspace.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(),
@@ -12,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(),
@@ -21,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(),
@@ -45,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')
@@ -91,11 +190,11 @@ function changedLead(action, amount, approved, callerRequestId) {
     if (action === 'buy_credits' && callerRequestId) {
         // Wiro binds a purchase request id to the price of its first attempt.
         return `${changed} Nothing was charged by this call. Show the new amount to the user and ask again. `
-            + `If an earlier call with request_id "${callerRequestId}" said the wallet was charged but the purchase is still pending, that purchase can only be finished at its original price, and Wiro refuses this request id at the new one. Do not approve the new amount for it; ask Wiro support to finish it.`;
+            + `If an earlier call with request_id "${callerRequestId}" ended without a clear result, do not approve the new amount for it: this request id works only at its original price. Check get_my_agent and the wallet balance with get_account, and if the balance changed, contact Wiro support.`;
     }
     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';
@@ -129,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.`
                         : ''),
@@ -143,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),
                     };
                 },
             };
@@ -160,23 +260,26 @@ function planFor(client, action, agent, raw, input) {
             }
             if (active) {
                 if (!prepaid) {
-                    // A card plan can be set to stop at its period end, by its payer or when the
-                    // payer's account is deleted.
+                    // A card plan can be set to stop at its period end.
+                    const atPeriodEnd = agent.subscription?.atPeriodEnd;
                     return {
                         outcome: 'refused',
-                        message: agent.subscription?.cancelAtPeriodEnd
+                        message: atPeriodEnd === 'ends'
                             ? `This plan is billed by card and is set to stop renewing after ${periodEnd}. Card plans are managed `
                                 + `from the dashboard, where it can be kept: ${agent.dashboardUrl}`
-                            : `This plan is billed by card and renews by itself. It is managed from the dashboard: ${agent.dashboardUrl}`,
+                            : atPeriodEnd === 'renews'
+                                ? `This plan is billed by card and renews by itself. It is managed from the dashboard: ${agent.dashboardUrl}`
+                                : `This plan is billed by card and is paid through ${periodEnd}. Card plans are renewed or cancelled `
+                                    + `from the dashboard: ${agent.dashboardUrl}`,
                     };
                 }
                 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) => {
@@ -236,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),
                     };
                 },
             };
@@ -254,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) {
@@ -290,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.',
@@ -301,57 +413,72 @@ 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)) {
-                        // A checkout link means the plan is paid by card. The link is a payment page for the owner's card, so it is not passed on.
+                        // A checkout link means the plan is paid by card, and card payments are made in the dashboard.
                         return { outcome: 'refused', message: cardPlan('upgrade it to Pro') };
                     }
                     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),
                     };
                 },
             };
@@ -374,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 }) } : {}),
                 };
@@ -388,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,
@@ -399,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),
                     };
                 },
             };
@@ -423,8 +551,8 @@ function confirmArguments(guid, action, quote, requestId) {
 }
 function retryPurchaseText(guid, quote, requestId) {
     const amount = chargeOf(quote);
-    return `To retry, call manage_agent_billing again with agent_guid "${guid}", action buy_credits, pack "${quote?.pack ?? ''}", request_id "${requestId}"${amount !== null ? `, confirm_charge_usd ${amount}` : ''} and confirm: true. That request id never charges twice, and it finishes a purchase that was charged but not completed. Do not get a new quote for this purchase: a new request id is a new purchase.`
-        + (amount !== null ? ` This works only while the pack still costs ${formatUsd(amount)}; Wiro refuses the id at any other price, and then Wiro support has to finish the purchase.` : '');
+    return `To retry, call manage_agent_billing again with agent_guid "${guid}", action buy_credits, pack "${quote?.pack ?? ''}", request_id "${requestId}"${amount !== null ? `, confirm_charge_usd ${amount}` : ''} and confirm: true. That request id never charges twice, and repeating it completes this same purchase. Do not get a new quote for this purchase: a new request id is a new purchase.`
+        + (amount !== null ? ` This request id works only while the pack costs ${formatUsd(amount)}. If the price changes, do not buy again: check get_my_agent and the wallet balance with get_account, and if the balance changed, contact Wiro support.` : '');
 }
 /**
  * Whether the agent's packs show an active one of this size bought since
@@ -447,9 +575,8 @@ async function freshPackShows(client, guid, credits, sentAtMs, signal) {
     }
 }
 /**
- * After a charging request whose outcome is open, reads the agent again and
- * says what it shows: the charge may have gone through, and the agent's
- * detail is where its result shows.
+ * After a paid request whose answer did not confirm it, reads the agent again
+ * and says what it shows.
  */
 async function observeOpenOutcome(client, action, before, quote, requestId, sentAtMs, signal) {
     let row;
@@ -457,11 +584,10 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
         row = await readAgentDetail(client, before.guid, signal);
     }
     catch {
-        return { happened: false, text: 'The agent could not be read afterwards to check it.' };
+        return { happened: false, text: 'The agent could not be read afterwards to check it. Check get_my_agent and the wallet balance with get_account first.' };
     }
     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'
@@ -470,9 +596,9 @@ 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 before trying again.' };
+                : { 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':
             return after.subscription?.status === 'active'
                 ? {
@@ -480,9 +606,9 @@ 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, but the wallet may have been charged anyway. Compare the wallet balance with get_account before renewing again.' };
+                : { 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': {
             if (after.tier === 'pro') {
                 return {
@@ -490,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;
@@ -499,8 +625,8 @@ async function observeOpenOutcome(client, action, before, quote, requestId, sent
             return {
                 happened: false,
                 text: priced
-                    ? 'The plan already shows the Pro price but not the Pro tier, so the upgrade was charged and did not finish. Do not upgrade again; ask Wiro support to finish it.'
-                    : 'The agent still shows Starter, but the wallet may have been charged anyway. Compare the wallet balance with get_account before trying again.',
+                    ? 'The agent does not show Pro yet. Do not upgrade again: check get_my_agent and the wallet balance with get_account, and if the balance changed, contact Wiro support.'
+                    : 'The agent still shows Starter. Check get_my_agent and the wallet balance with get_account before trying again; if the balance changed, contact Wiro support.',
             };
         }
         case 'buy_credits': {
@@ -513,18 +639,18 @@ 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);
             if (fresh) {
-                // The pack is paid for, but its credits are counted only when the
-                // purchase finishes, which the same request id does without a charge.
+                // The pack shows on the agent. If its credits do not show yet, the same
+                // request id completes the purchase without a second charge.
                 return {
                     happened: true,
                     row,
-                    text: 'A new pack of that size shows on the agent, so the purchase went through and the wallet was charged. Do not buy it again. '
-                        + `Its credits may not be counted yet. If get_my_agent still does not show them in a few minutes, repeating this purchase with the same request_id "${requestId ?? ''}" and confirm_charge_usd ${charged ?? ''} finishes it without a second charge.`,
+                    text: 'A new pack of that size shows on the agent, so the purchase went through. Do not buy it again. '
+                        + `If get_my_agent does not show its credits in a few minutes, repeat this purchase with the same request_id "${requestId ?? ''}" and confirm_charge_usd ${charged ?? ''}; that request id never charges twice.`,
                     result: bought,
                     nextAction: waitAction(before.guid, 'Check that the pack\'s credits show on the agent.'),
                 };
@@ -538,13 +664,20 @@ 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.`);
     }
     if (/purchase request id was already used/i.test(text)) {
-        return new Error(`${text}\n\nNothing was charged now. This request id belongs to an earlier purchase of another pack or at another price. For a new purchase, get a new quote without request_id. If an earlier call with this id said the wallet was charged but the purchase is still pending, do not buy again: that purchase can only be finished at its original price, so ask Wiro support to finish it.`);
+        return new Error(`${text}\n\nNothing was charged now. This request id belongs to an earlier purchase of another pack or at another price. For a new purchase, get a new quote without request_id. If the earlier purchase with this id ended without a clear result, do not buy again: check get_my_agent and the wallet balance with get_account, and if the balance changed, contact Wiro support.`);
     }
     const hint = workspaceHint(text);
     if (hint)
@@ -557,17 +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.',
-        inputSchema: {
+            + '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: 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)
@@ -582,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(),
@@ -608,10 +747,12 @@ export function registerManageAgentBilling(server, client) {
         let sentAtMs = 0;
         let before;
         let plan;
+        let plainMember = false;
         const respond = (payload) => {
             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',
@@ -625,7 +766,7 @@ export function registerManageAgentBilling(server, client) {
                             '',
                             payload.message,
                             '',
-                            ...formatAgentSummaryLines(summary),
+                            ...(payload.agentStale ? summaryLines.slice(0, 1) : summaryLines),
                             `Dashboard: ${dashboardUrl}`,
                         ].join('\n'),
                     }],
@@ -648,10 +789,22 @@ export function registerManageAgentBilling(server, client) {
             const row = await readAgentDetail(client, guid, extra.signal);
             const agent = toAgentDetail(row);
             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.
+            if (plainMember && await teamAgentBillingRefused(client, guid, extra.signal)) {
+                return respond({
+                    outcome: 'refused',
+                    message: 'Only a team admin, the organization\'s owner or the person who deployed this agent can pay for '
+                        + 'or change its plan, and this connection acts as a team member without those rights. Nothing was '
+                        + 'quoted or charged. Ask a team admin or the person who deployed the agent to do it.',
+                    agentRow: row,
+                });
             }
             const problem = confirm ? approvalProblem(action, plan.quote, confirm_charge_usd) : null;
             if (!confirm || problem) {
@@ -692,9 +845,9 @@ export function registerManageAgentBilling(server, client) {
                 // The action went through; the earlier snapshot still identifies the agent.
             }
             // A request id that already completed a purchase is answered with
-            // success again, without a charge and without new credits. A purchase
-            // also retires any pack past its end date, so the extra credits can
-            // grow by less than the pack, and the agent's packs decide.
+            // success again, without a new charge or new credits. An older pack can
+            // end at the same moment, so the extra credits can grow by less than
+            // the pack, and the agent's packs decide.
             const credits = plan.quote?.creditsAdded ?? 0;
             const extraBefore = toNumber(row.extracredits);
             const extraAfter = afterRead ? toNumber(after.extracredits) : null;
@@ -709,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
@@ -720,13 +887,18 @@ export function registerManageAgentBilling(server, client) {
                     agentRow: after,
                 });
             }
+            // Without the read-back, the row shows the agent as it was before the change.
+            const stale = !afterRead && performed.outcome === 'done';
             return respond({
                 outcome: performed.outcome,
-                message: performed.message,
+                message: stale
+                    ? `${performed.message} The agent could not be read afterwards; get_my_agent shows its new status, plan and credits.`
+                    : performed.message,
                 quote: plan.quote,
                 result: performed.result,
                 nextAction: performed.nextAction,
                 agentRow: after,
+                agentStale: stale,
             });
         }
         catch (error) {
@@ -743,7 +915,7 @@ export function registerManageAgentBilling(server, client) {
                 if (observed.happened && observed.row) {
                     return respond({
                         outcome: 'done',
-                        message: `Wiro answered with an error (${text}) after the request was sent, but reading the agent again shows that it went through. ${observed.text}`,
+                        message: `The answer did not confirm this request, so the agent was read again. ${observed.text}`,
                         quote,
                         result: observed.result,
                         nextAction: observed.nextAction,
@@ -753,10 +925,10 @@ export function registerManageAgentBilling(server, client) {
                 const retry = action === 'buy_credits' && requestId
                     ? retryPurchaseText(guid, quote, requestId)
                     : 'Do not repeat the call until this is checked.';
-                return errorResult(new Error(`${text}\n\nThe request was sent and the answer does not show whether it went through, so the wallet may have been charged. ${observed.text} ${retry}`));
+                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);
         }
     });