@wiro-ai/wiro-mcp 1.4.1 → 1.5.0

package/dist/tools/apply-agent-skills.js

@@ -1,17 +1,27 @@
 import { z } from 'zod';
 import { asString, errorResult, errorText, isPlainObject, requireApiSuccess, toNumber, unixToIso, } from '../utils/api.js';
-import { agentStatusLabel, agentStatusOf, checkSkillSet, credentialsNeededFor, describeSkillsApplyError, diffSkills, enabledSkillNames, estimateProratedUsd, formatUsd, isAgentRunning, loadSkillRegistry, newSkillChangeKey, parseSkillChangeKey, planBilling, planSkillChanges, readUserAgent, restartNote, skillChangeDigest, skillPriceTag, workspaceHint, } from '../utils/agent-config.js';
-import { asTier, outcomeUnknown, toTierPricing } from '../utils/user-agent.js';
+import { agentStatusLabel, agentStatusOf, checkSkillSet, credentialsNeededFor, daysLeftText, describeSkillsApplyError, diffSkills, enabledSkillNames, formatUsd, isAgentRunning, loadSkillRegistry, newSkillChangeKey, parseSkillChangeKey, planBilling, planSkillChanges, readPlanChange, readUserAgent, underOneDayLeft, restartNote, skillChangeDigest, skillPriceTag, workspaceHint, } from '../utils/agent-config.js';
+import { asTier, bindProjectStep, formatCredits, outcomeUnknown, toTierPricing, WIRO_PROJECT_CREDENTIAL } from '../utils/user-agent.js';
 import { DEFAULT_WAIT_SECONDS } from '../utils/poll.js';
 import { isPlainTeamMember, teamAgentBillingRefused } from '../utils/workspace.js';
-import { nextActionSchema } from './schemas.js';
+import { nextActionSchema, strictInput } from './schemas.js';
 const pricingSchema = z.object({
     currentMonthlyUsd: z.number().nullable(),
     newMonthlyUsd: z.number().nullable(),
     deltaMonthlyUsd: z.number().nullable(),
-    currentMonthlyCredits: z.number().nullable(),
-    newMonthlyCredits: z.number().nullable(),
+    currentMonthlyCredits: z.number().nullable()
+        .describe('The monthly credits each renewal grants now.'),
+    newMonthlyCredits: z.number().nullable()
+        .describe('The monthly credits each renewal grants after the change.'),
     deltaMonthlyCredits: z.number().nullable(),
+    creditsNow: z.number().optional()
+        .describe('The credits this period gains now, below 0 when it loses them: the change counts for the time left in the period.'),
+    creditsThisPeriod: z.number().optional()
+        .describe('The monthly credits this period grants in all after the change.'),
+    creditsFromRenewal: z.number().optional()
+        .describe('The monthly credits every renewal grants after the change.'),
+    periodEnd: z.string().optional()
+        .describe('When the current period ends.'),
     note: z.string().optional(),
 });
 const outputSchema = {
@@ -34,7 +44,12 @@ const outputSchema = {
         plan: z.enum(['prepaid', 'card', 'none']),
         subscriptionStatus: z.string().nullable(),
         wallet: z.enum(['team', 'personal']),
-        estimatedChargeNowUsd: z.number().nullable().optional(),
+        estimatedChargeNowUsd: z.number().nullable().optional()
+            .describe('What a wallet plan pays now at list price, as Wiro works it out, before any discount on the wallet; 0 on a card plan, whose difference goes to the card subscription.'),
+        creditNowUsd: z.number().nullable().optional()
+            .describe('For a drop on a wallet plan, what goes back to the balances that paid; null when it is worked out when the change is applied.'),
+        usedCreditsUsd: z.number().nullable().optional()
+            .describe('The part of a credit that comes off for credits already used above what the plan keeps.'),
         chargedNowUsd: z.number().nullable().optional(),
         note: z.string(),
     }),
@@ -56,9 +71,64 @@ const outputSchema = {
     nextAction: nextActionSchema.optional(),
 };
 const UNCHANGED_RESTART = 'Nothing changed, so the agent does not restart.';
-// A credit for skills turned off goes to the wallet with an end date: it can be
-// spent until the plan's current period ends.
-const CREDIT_SPEND_BY = 'It can be spent until this period ends.';
+// The tier and the price live with Wiro, and the agent reads neither: only a skill that turns on or off restarts it.
+const TIER_ONLY_RESTART = 'No skill turns on or off, so a change of the tier alone does not restart the agent.';
+function roundCents(usd) {
+    return Math.round(usd * 100) / 100;
+}
+/**
+ * How long an applied credit lasts, from the parts Wiro says it split into. Each
+ * part went back to the balance that paid it and keeps that balance's end date,
+ * except the part whose source has ended since (each ...UntilPeriodEndUsd): that
+ * part lasts until the plan's current period ends. The two amounts add up to the
+ * credit, and parts that come to nothing say nothing.
+ */
+function creditTerms(parts) {
+    if (!isPlainObject(parts))
+        return '';
+    const usd = (key) => toNumber(parts[key]) ?? 0;
+    const untilEnd = roundCents(usd('couponUntilPeriodEndUsd') + usd('storeUntilPeriodEndUsd') + usd('depositUntilPeriodEndUsd'));
+    const keepsEnd = roundCents(roundCents(usd('couponUsd') + usd('storeUsd') + usd('depositUsd')) - untilEnd);
+    if (keepsEnd > 0 && untilEnd > 0) {
+        return `${formatUsd(keepsEnd)} of it went back to the balances that paid and keeps their end dates, and ${formatUsd(untilEnd)} lasts until this period ends, because the credit that paid it has ended.`;
+    }
+    if (keepsEnd > 0)
+        return 'It went back to the balances that paid and keeps their end dates.';
+    return untilEnd > 0 ? 'It lasts until this period ends, because the credit that paid it has ended.' : '';
+}
+/** A count of credits with its sign, such as +97 or -690. */
+function signedCredits(credits) {
+    return `${credits > 0 ? '+' : ''}${formatCredits(credits)}`;
+}
+/** The fields of Wiro's plan change that the pricing output carries. */
+function periodFields(change) {
+    if (!change)
+        return {};
+    const periodEnd = unixToIso(change.periodEnd);
+    return {
+        ...(change.creditsNow !== null ? { creditsNow: change.creditsNow } : {}),
+        ...(change.creditsThisPeriod !== null ? { creditsThisPeriod: change.creditsThisPeriod } : {}),
+        ...(change.creditsFromRenewal !== null ? { creditsFromRenewal: change.creditsFromRenewal } : {}),
+        ...(periodEnd ? { periodEnd } : {}),
+    };
+}
+/**
+ * What a change does to this period's credits when none come with it: those it takes away end for the
+ * time left, and the period keeps the rest. A plan priced again at today's rates can also keep its
+ * credits, or gain some, while its price drops.
+ */
+function creditsEndNote(skillsOff, creditsNow, creditsThisPeriod) {
+    if (creditsNow !== null && creditsNow > 0) {
+        return `This period gains ${formatCredits(creditsNow)} credits for the time left${creditsThisPeriod !== null ? `, ${formatCredits(creditsThisPeriod)} in all` : ''}.`;
+    }
+    if (creditsNow === 0) {
+        return creditsThisPeriod !== null ? `This period keeps its ${formatCredits(creditsThisPeriod)} credits.` : 'This period keeps its credits.';
+    }
+    const keeps = creditsThisPeriod !== null ? `, and this period keeps ${formatCredits(creditsThisPeriod)}` : '';
+    if (skillsOff === 0)
+        return `The credits the change takes away end now for the time left${keeps}.`;
+    return `${skillsOff === 1 ? 'Its' : 'Their'} credits for the time left end now${keeps}.`;
+}
 function difference(next, current) {
     return next === null || current === null ? null : Math.round((next - current) * 100) / 100;
 }
@@ -66,9 +136,10 @@ function difference(next, current) {
  * A skill change prices the plan at today's prices for all its skills, so a
  * plan that started at other prices also changes for the skills it already
  * has, and so do its monthly credits. The agent's tiers carry today's prices
- * and credits for those skills. An agent without a plan has no price of its
- * own to move from, and a move to Pro prices the whole plan at today's Pro
- * prices, which the quote already shows.
+ * and credits for those skills. They are the base of the new price, not a price
+ * the plan reaches. An agent without an active plan cannot take the change yet,
+ * and a move to Pro prices the whole plan at today's Pro prices, which the quote
+ * already shows.
  */
 function todayPriceNote(row, billing, currentPrice, currentCredits, tierChange) {
     if (tierChange)
@@ -76,12 +147,12 @@ function todayPriceNote(row, billing, currentPrice, currentCredits, tierChange)
     const tier = asTier(row.tier);
     const tiers = toTierPricing(isPlainObject(row.agent) ? row.agent.tiers : undefined);
     const today = tier && tiers ? tiers[tier] : null;
-    if (billing.plan === 'none' || currentPrice === null || today === null || !difference(today.priceUsd, currentPrice))
+    if (billing.status !== 'active' || currentPrice === null || today === null || !difference(today.priceUsd, currentPrice))
         return null;
-    const credits = currentCredits !== null && today.monthlyCredits !== currentCredits
-        ? `, and its monthly credits from ${currentCredits} to ${today.monthlyCredits}`
-        : '';
-    return `The change also moves the plan from its current ${formatUsd(currentPrice)} a month to ${formatUsd(today.priceUsd)} a month, today's ${tier === 'pro' ? 'Pro' : 'Starter'} price for the skills it already has${credits}.`;
+    const versus = currentCredits !== null && today.monthlyCredits !== currentCredits
+        ? ` with ${formatCredits(today.monthlyCredits)} monthly credits, not its current ${formatUsd(currentPrice)} and ${formatCredits(currentCredits)}`
+        : `, not its current ${formatUsd(currentPrice)}`;
+    return `Today's ${tier === 'pro' ? 'Pro' : 'Starter'} price for the skills this plan already has is ${formatUsd(today.priceUsd)} a month${versus}. A skill change counts from today's price, and the new price in this quote already includes that.`;
 }
 /**
  * The wallet of the agent's workspace, which Wiro charges or credits for a
@@ -92,56 +163,175 @@ function todayPriceNote(row, billing, currentPrice, currentCredits, tierChange)
 function walletName(billing) {
     return billing.wallet === 'team' ? 'the team wallet' : 'your personal wallet';
 }
-/** For a cancelled plan, a skill change only covers the days left: nothing renews at the new price. */
+/** When the new monthly credits come: a plan set to end renews only if it is kept, and an agent without a plan gets them once it is subscribed. */
+function creditsWhen(billing) {
+    if (billing.plan === 'none')
+        return 'a month once it is subscribed';
+    return billing.status === 'active' && billing.cancelAtPeriodEnd === true
+        ? 'at each renewal after the change, if the plan is kept'
+        : 'at each renewal after the change';
+}
+/** When an active plan's next renewal gives the new monthly credits. A card plan whose renewal is not known names it as a condition. */
+function renewalWhen(billing) {
+    if (billing.cancelAtPeriodEnd === true)
+        return 'from the next renewal, if the plan is kept';
+    return billing.cancelAtPeriodEnd === null ? 'from the next renewal, if the plan renews' : 'from the next renewal';
+}
+/** What renewals give after an applied change: a plan that may not renew names it as a condition, as its quote did. */
+function renewalGives(billing, credits) {
+    return billing.cancelAtPeriodEnd === false ? `every renewal gives ${formatCredits(credits)}` : `${formatCredits(credits)} ${renewalWhen(billing)}`;
+}
+/** For a cancelled plan, a skill change only covers the time left: nothing renews at the new price. */
 function cancelledNote(billing) {
     const end = billing.periodEnd !== null ? unixToIso(billing.periodEnd) : undefined;
     if (billing.plan === 'card') {
         return `The plan is set to end${end ? ` after ${end}` : ' with this period'} and does not renew.`;
     }
-    return `The plan is cancelled and ends about a day after ${end ?? 'the end of this period'}, so this covers only the days left and the new price is not renewed. Undo the cancellation with manage_agent_billing (renew) to keep the plan.`;
+    return `The plan is cancelled and ends about a day after ${end ?? 'the end of this period'}, so this covers only the time left and the new price is not renewed. Undo the cancellation with manage_agent_billing (renew) to keep the plan.`;
+}
+/** A card subscription that ends with this period: the plan is set to end, or it moves to wallet billing. */
+function cardEndsWithPeriod(billing) {
+    return billing.plan === 'card' && (billing.cancelAtPeriodEnd === true || billing.switchingToWallet);
 }
-function quoteBillingNote(billing, delta, estimate, nextPrice) {
+function walletSwitchNote(billing, price) {
+    return `When this period ends, the plan moves to wallet billing and renews from ${walletName(billing)}${price !== null ? ` at ${formatUsd(price)} a month` : ''}.`;
+}
+// A card subscription that ends with this period is not renewed by card, so its notes point to no next invoice.
+const CARD_ENDS_QUOTE = 'Nothing is charged now. The card subscription is updated to the new price for the rest of this period.';
+// A card plan whose renewal is not known may also end with this period, so its next invoice is named only for a plan that renews by card.
+const CARD_UNKNOWN_QUOTE = 'Nothing is charged now. The card subscription is updated to the new price, and a plan that renews by card shows the prorated difference on its next invoice.';
+/** Only a wallet plan that has ended comes back with renew; any other plan that is not active takes a new one (manage_agent_billing). */
+function renewsBack(billing) {
+    return billing.plan === 'prepaid' && billing.status === 'expired';
+}
+/** What a price drop on a wallet plan gives back now, from Wiro's own plan change. */
+function walletCreditNote(change) {
+    const used = change.usedCreditsUsd ?? 0;
+    // A credit is at most 1 cent for each credit the change takes away unused, so one that takes none away gives nothing back.
+    if (change.creditNowUsd === 0 && used > 0 && change.creditsNow !== null && change.creditsNow >= 0) {
+        return 'Nothing comes back: the change takes no credits away.';
+    }
+    if (change.creditNowUsd === null) {
+        return 'What comes back is worked out when the change is applied: what the time left is worth, less 1 cent for each credit already used above what the plan keeps.';
+    }
+    if (change.creditNowUsd > 0) {
+        return `${formatUsd(change.creditNowUsd)} goes back to the balances that paid, and each keeps its own end date.`
+            + (used > 0 ? ` ${formatUsd(used)} comes off for credits already used above what the plan keeps.` : '');
+    }
+    return used > 0
+        ? 'Nothing comes back: the credits already used are worth more than the time left.'
+        : 'Nothing comes back to the wallet now.';
+}
+/**
+ * The quote's billing line. An active plan's money and credits come from the
+ * plan change Wiro works out on the plan as it is now (change); without it,
+ * the line says what happens without a number.
+ */
+function quoteBillingNote(billing, delta, change, nextPrice, skillsOff) {
     // A card plan whose renewal is not known gets the new price without a renewal claim.
     const after = billing.cancelAtPeriodEnd === true
         ? ` ${cancelledNote(billing)}`
-        : nextPrice === null
-            ? ''
-            : billing.cancelAtPeriodEnd === false
-                ? ` The plan then renews at ${formatUsd(nextPrice)} a month.`
-                : ` The new monthly price is ${formatUsd(nextPrice)}.`;
+        : billing.switchingToWallet
+            ? ` ${walletSwitchNote(billing, nextPrice)}`
+            : nextPrice === null
+                ? ''
+                : billing.cancelAtPeriodEnd === false
+                    ? ` The plan then renews at ${formatUsd(nextPrice)} a month.`
+                    : ` The new monthly price is ${formatUsd(nextPrice)}.`;
     if (billing.plan === 'none') {
         return 'The agent has no subscription yet, so nothing is charged now. The new monthly price applies once it is subscribed.';
     }
     if (billing.status !== 'active') {
-        return `The subscription is ${billing.status ?? 'not active'}. Skills can only change on an active subscription, so renew it with manage_agent_billing first.`;
+        return renewsBack(billing)
+            ? `The subscription is ${billing.status ?? 'not active'}. Skills can only change on an active subscription, so renew it with manage_agent_billing first.`
+            : `The subscription is ${billing.status ?? 'not active'}. Skills can only change on an active subscription, so start a new plan with manage_agent_billing (subscribe) first.`;
     }
-    if (delta === null) {
+    if (delta !== null && Math.abs(delta) < 0.005)
+        return 'The monthly price does not change, so nothing is charged.';
+    if (delta === null || change === null) {
         return billing.plan === 'prepaid'
-            ? `The difference for the rest of this period is taken from, or credited to, ${walletName(billing)} when the change is applied. A credit can be spent until this period ends.${after}`
-            : `Any prorated difference appears on the next invoice.${after}`;
+            ? `The difference for the rest of this period is taken from, or credited to, ${walletName(billing)} when the change is applied. A credit goes back to the balances that paid, and each keeps its own end date.${after}`
+            : cardEndsWithPeriod(billing)
+                ? `${CARD_ENDS_QUOTE}${after}`
+                : billing.cancelAtPeriodEnd === null
+                    ? `${CARD_UNKNOWN_QUOTE}${after}`
+                    : `Any prorated difference appears on the next invoice.${after}`;
     }
-    if (Math.abs(delta) < 0.005)
-        return 'The monthly price does not change, so nothing is charged.';
-    if (billing.plan === 'card') {
-        return `Nothing is charged now. The card subscription is updated and the prorated difference appears on the next invoice.${after}`;
+    const ends = creditsEndNote(skillsOff, change.creditsNow, change.creditsThisPeriod);
+    // Credits come with a rise when this period gains them. A plan priced again at today's rates can also
+    // lose credits, or keep them, while its price rises.
+    const gained = change.creditsNow !== null && change.creditsNow > 0 ? change.creditsNow : null;
+    const notGained = change.creditsNow !== null && change.creditsNow <= 0 ? ` ${ends}` : '';
+    if (!change.wallet) {
+        if (delta > 0) {
+            const added = gained !== null ? ` ${formatCredits(gained)} credits come now for the rest of this period.` : notGained;
+            if (cardEndsWithPeriod(billing))
+                return `${CARD_ENDS_QUOTE}${added}${after}`;
+            if (billing.cancelAtPeriodEnd === null)
+                return `${CARD_UNKNOWN_QUOTE}${added}${after}`;
+            return gained !== null
+                ? `Nothing is charged now. The prorated difference appears on the next invoice, and ${formatCredits(gained)} credits come now for the rest of this period.${after}`
+                : `Nothing is charged now. The prorated difference appears on the next invoice.${notGained}${after}`;
+        }
+        if (cardEndsWithPeriod(billing))
+            return `${CARD_ENDS_QUOTE} ${ends}${after}`;
+        if (billing.cancelAtPeriodEnd === null)
+            return `${CARD_UNKNOWN_QUOTE} ${ends}${after}`;
+        return `The prorated difference comes off the next invoice. ${ends}${after}`;
     }
-    const days = billing.daysRemaining !== null ? ` for the ${billing.daysRemaining} days left in this period` : ' for the rest of this period';
     if (delta > 0) {
-        return `About ${formatUsd(estimate ?? 0)} is taken from ${walletName(billing)} now${days}.${after}`;
+        const charge = formatUsd(change.chargeNowUsd ?? 0);
+        const credits = gained !== null ? `, and ${formatCredits(gained)} credits come with it` : '';
+        const days = daysLeftText(change.secondsLeft);
+        return underOneDayLeft(change.secondsLeft)
+            ? `${charge} is taken from ${walletName(billing)} now at the one-day minimum${credits}.${notGained}${after}`
+            : `${charge} is taken from ${walletName(billing)} now for the rest of this period${days ? ` (${days})` : ''}${credits}.${notGained}${after}`;
     }
-    return `About ${formatUsd(Math.abs(estimate ?? 0))} is credited back to ${walletName(billing)} now${days}. ${CREDIT_SPEND_BY}${after}`;
+    return `${walletCreditNote(change)} ${ends}${after}`;
 }
 function chargeNote(billing, body) {
     const charged = toNumber(body.prepaidWalletDelta);
+    const used = toNumber(body.usedCreditsUsd) ?? 0;
+    const creditsNow = isPlainObject(body.pricing) ? toNumber(body.pricing.creditsNow) : null;
     const cancelled = billing.cancelAtPeriodEnd === true && billing.status === 'active' ? ` ${cancelledNote(billing)}` : '';
     if (charged !== null && charged > 0) {
-        return { charged, note: `${formatUsd(charged)} was taken from ${walletName(billing)} for the rest of this period.${cancelled}` };
+        const credits = creditsNow !== null && creditsNow > 0 ? `, and ${formatCredits(creditsNow)} credits came with it` : '';
+        return { charged, note: `${formatUsd(charged)} was taken from ${walletName(billing)} for the rest of this period${credits}.${cancelled}` };
     }
     if (charged !== null && charged < 0) {
-        return { charged, note: `${formatUsd(Math.abs(charged))} was credited to ${walletName(billing)}. ${CREDIT_SPEND_BY}${cancelled}` };
+        const terms = creditTerms(body.prepaidCreditParts);
+        const usedNote = used > 0 ? ` ${formatUsd(used)} came off for credits already used above what the plan keeps.` : '';
+        return { charged, note: `${formatUsd(Math.abs(charged))} was credited to ${walletName(billing)}.${terms ? ` ${terms}` : ''}${usedNote}${cancelled}` };
+    }
+    // A change that took no credits away had nothing to credit, and nothing failed.
+    if (billing.plan === 'prepaid' && used > 0 && creditsNow !== null && creditsNow >= 0) {
+        return { charged: null, note: `Nothing came back: the change took no credits away.${cancelled}` };
+    }
+    // The credits already used came to more than the time left was worth: no credit, and nothing failed.
+    // A part Wiro could not add (prepaidCreditFailedUsd) was due all the same: its warning follows, and the
+    // credits used took only what Wiro names.
+    if (billing.plan === 'prepaid' && used > 0) {
+        return (toNumber(body.prepaidCreditFailedUsd) ?? 0) > 0
+            ? { charged: null, note: `Nothing came back now. ${formatUsd(used)} came off for credits already used above what the plan keeps.${cancelled}` }
+            : { charged: null, note: `Nothing came back: the credits already used were worth more than the time left.${cancelled}` };
     }
     if (body.stripeProrationApplied === true) {
-        return { charged: null, note: `The card subscription was updated; any prorated difference appears on the next invoice.${cancelled}` };
+        const moved = isPlainObject(body.pricing) ? toNumber(body.pricing.deltaUsd) : null;
+        if (moved !== null && Math.abs(moved) < 0.005) {
+            return { charged: null, note: `The monthly price did not change, so nothing was charged.${cancelled}` };
+        }
+        const added = moved !== null && moved > 0 && creditsNow !== null && creditsNow > 0
+            ? ` ${formatCredits(creditsNow)} credits came now for the rest of this period.`
+            : '';
+        if (cardEndsWithPeriod(billing)) {
+            const price = isPlainObject(body.pricing) ? toNumber(body.pricing.newPriceUsd) : null;
+            const switching = billing.switchingToWallet ? ` ${walletSwitchNote(billing, price)}` : '';
+            return { charged: null, note: `Nothing was charged now. The card subscription was updated to the new price for the rest of this period.${added}${cancelled}${switching}` };
+        }
+        if (billing.cancelAtPeriodEnd === null) {
+            return { charged: null, note: `Nothing was charged now. The card subscription was updated to the new price, and a plan that renews by card shows the prorated difference on its next invoice.${added}` };
+        }
+        return { charged: null, note: `The card subscription was updated; any prorated difference appears on the next invoice.${added}${cancelled}` };
     }
     if (billing.plan === 'none') {
         return { charged: null, note: 'Nothing was charged: the agent has no subscription yet.' };
@@ -156,6 +346,21 @@ function appliedBillingNote(billing, body) {
         .filter((warning) => Boolean(warning));
     return warnings.length > 0 ? { ...result, note: [result.note, ...warnings].join(' ') } : result;
 }
+/** The sentence for a change whose skills need a Wiro project. */
+function bindProjectNote(needed) {
+    return needed.some(entry => entry.credentials.includes(WIRO_PROJECT_CREDENTIAL))
+        ? ' bind_agent_project connects a Wiro project, with no key to paste.'
+        : '';
+}
+/** How to give the new skills what they still need. A Wiro project comes first, since it takes no key. */
+function stillNeededSteps(needed) {
+    const keys = needed.flatMap(entry => entry.credentials);
+    const fields = 'set_agent_credentials or connect_agent_oauth.';
+    if (!keys.includes(WIRO_PROJECT_CREDENTIAL))
+        return `Set them with ${fields}`;
+    const others = keys.some(key => key !== WIRO_PROJECT_CREDENTIAL) ? ` Set the others with ${fields}` : '';
+    return `Connect the Wiro project with bind_agent_project, with no key to paste.${others}`;
+}
 function listLine(label, names) {
     return names.length > 0 ? `**${label}:** ${names.join(', ')}` : null;
 }
@@ -180,21 +385,26 @@ export function registerApplyAgentSkills(server, client) {
             + 'On a team agent only a team admin or the person who deployed the agent can change its skills; other '
             + 'members are refused and nothing is charged. '
             + 'Steps: 1) call without confirm. The tool checks the names, adds the skills they '
-            + 'depend on, and returns the current and new monthly price, an estimate of what is '
-            + 'charged now and an idempotency_key. Nothing changes yet. 2) Show the price to the '
+            + 'depend on, and returns the current and new monthly price, what Wiro charges or credits now, '
+            + 'the credits this period gains or loses, and an idempotency_key. Nothing changes yet. 2) Show the price to the '
             + 'user. 3) After they approve, call again with confirm: true and that idempotency_key. '
-            + 'The key is tied to the quoted prices: if the price changed since the quote, nothing '
-            + 'is applied and a new quote with a new key comes back. Reusing the key after a timeout '
+            + 'The key is tied to the quoted prices and, on a prepaid plan, the billing period: if '
+            + 'either changed since the quote, nothing is applied and a new quote with a new key comes back. Reusing the key after a timeout '
             + 'is safe, the change is applied once. Billing: on a prepaid plan the monthly difference '
-            + 'for the days left in the period is taken from the wallet at once, or credited to it '
-            + 'when the price drops, and that credit can be spent until the period ends; on a card '
-            + 'plan it is added to the next invoice. A running agent '
-            + 'restarts once to load the skills. Newly enabled skills may still need credentials '
-            + '(set_agent_credentials, connect_agent_oauth) and do not create scheduled tasks '
+            + 'for the time left in the period is taken from the wallet at once, and the added credits come '
+            + 'for that same time; every renewal gives all of them. When the price drops, what the time left '
+            + 'is worth goes back to the balances that paid, less 1 cent for each credit already used above '
+            + 'what the plan keeps, and each balance keeps its own end date. A skill that comes off loses its '
+            + 'credits for the time left; the ones the time already passed paid for stay until the renewal. '
+            + 'On a card plan nothing is charged at once: the card subscription is updated to the new price, '
+            + 'a plan that renews by card shows the difference on its next invoice, and the added credits come '
+            + 'for the time left. A running agent restarts once when a skill turns on or off; a change of the '
+            + 'tier alone leaves it running. Newly enabled skills may still need credentials '
+            + '(set_agent_credentials, connect_agent_oauth, bind_agent_project for a Wiro project) and do not create scheduled tasks '
             + '(manage_agent_custom_skill does). Find skill names with list_agent_skills and the '
             + 'agent\'s current skills with get_my_agent. The agents playbook (get_playbook) has the '
             + 'full setup walkthrough.',
-        inputSchema: {
+        inputSchema: strictInput({
             agent_guid: z.string().min(1).describe('The deployed agent\'s guid, from list_my_agents.'),
             skills: z.record(z.string(), z.boolean())
                 .describe('Skills to change, as name: true to turn on or name: false to turn off, for example {"int-instagram-post": true}. Registry names only (list_agent_skills). Custom skills and scheduled tasks (cs-...) are managed with manage_agent_custom_skill; channels such as Telegram turn on through set_agent_credentials.'),
@@ -205,12 +415,12 @@ export function registerApplyAgentSkills(server, client) {
             confirm: z.boolean().default(false)
                 .describe('false (default) only returns the quote. true applies the change and charges it; it needs the idempotency_key from the quote.'),
             idempotency_key: z.string().min(8).max(128).optional()
-                .describe('With confirm: true, the key from the quote the user approved. It ties the approval to the quoted prices, and repeating the call with it after a timeout never applies the change twice. Omit it to get a quote.'),
-        },
+                .describe('With confirm: true, the key from the quote the user approved. It ties the approval to the quoted prices and, on a prepaid plan, the billing period, and repeating the call with it after a timeout never applies the change twice. Omit it to get a quote.'),
+        }),
         outputSchema,
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
@@ -257,7 +467,9 @@ export function registerApplyAgentSkills(server, client) {
                 alreadySet: diff.alreadySet.filter(name => !plan.addedDependencies.includes(name)),
             };
             const credentialsNeeded = credentialsNeededFor(diff.enable, registry, row);
-            const nothingToDo = Object.keys(diff.changes).length === 0 && !tierChange;
+            // A running agent restarts only for a skill that turns on or off.
+            const skillsMove = Object.keys(diff.changes).length > 0;
+            const nothingToDo = !skillsMove && !tierChange;
             const base = {
                 agentGuid: agent_guid,
                 changes,
@@ -281,7 +493,8 @@ export function registerApplyAgentSkills(server, client) {
                 };
             }
             const currentPrice = toNumber(row.monthlypriceusd);
-            const currentCredits = toNumber(row.monthlycredits);
+            // The plan's monthly figure is what each renewal grants. This period's can differ after a change inside it.
+            const currentCredits = toNumber(row.renewalcredits) ?? toNumber(row.monthlycredits);
             const key = idempotency_key?.trim() ?? '';
             // Every team member can read a team agent and price a change, but only a
             // team admin or the person who deployed it can apply one. The credit
@@ -314,19 +527,19 @@ export function registerApplyAgentSkills(server, client) {
                 if (newPrice === null) {
                     throw new Error('Wiro did not return the new monthly price of this change, so it cannot be quoted. Try again later.');
                 }
-                const priceTag = skillPriceTag(currentPrice, newPrice);
+                const priceTag = skillPriceTag(currentPrice, newPrice, billing.plan === 'prepaid' ? billing.periodEnd : null);
                 const approved = confirm && givenKey !== null && givenKey.priceTag === priceTag;
                 if (!approved) {
                     const newCredits = toNumber(preview.totalMonthlyCredits);
                     const delta = difference(newPrice, currentPrice);
-                    const estimate = billing.plan === 'prepaid' && billing.status === 'active' && delta !== null
-                        ? estimateProratedUsd(delta, billing.periodEnd)
-                        : null;
-                    const note = quoteBillingNote(billing, delta, estimate, newPrice);
+                    // What Wiro works out for this change on the plan as it is now. Only an active plan has one.
+                    const change = billing.plan !== 'none' && billing.status === 'active' ? readPlanChange(preview.planChange) : null;
+                    const note = quoteBillingNote(billing, delta, change, newPrice, changes.disable.length);
+                    const walletDrop = change !== null && change.wallet && delta !== null && delta < 0;
                     const quoteKey = givenKey?.priceTag === priceTag ? key : newSkillChangeKey(digest, priceTag);
                     const priceChanged = confirm && givenKey !== null;
                     const blocked = billing.plan !== 'none' && billing.status !== 'active';
-                    const restart = restartNote(status, 'skill change');
+                    const restart = skillsMove ? restartNote(status, 'skill change') : TIER_ONLY_RESTART;
                     const priceNote = todayPriceNote(row, billing, currentPrice, currentCredits, tierChange);
                     const pricing = {
                         currentMonthlyUsd: currentPrice,
@@ -335,12 +548,13 @@ export function registerApplyAgentSkills(server, client) {
                         currentMonthlyCredits: currentCredits,
                         newMonthlyCredits: newCredits,
                         deltaMonthlyCredits: difference(newCredits, currentCredits),
+                        ...periodFields(change),
                         ...(priceNote ? { note: priceNote } : {}),
                     };
                     const nextAction = blocked
                         ? {
                             tool: 'manage_agent_billing',
-                            arguments: { agent_guid, action: 'renew' },
+                            arguments: { agent_guid, action: renewsBack(billing) ? 'renew' : 'subscribe' },
                             reason: 'The subscription must be active before skills can change.',
                         }
                         : {
@@ -360,7 +574,7 @@ export function registerApplyAgentSkills(server, client) {
                     const lead = !confirm
                         ? null
                         : priceChanged
-                            ? 'The price changed since the quote, so nothing was applied or charged. This is the new quote with a new idempotency_key; show it to the user and ask again.'
+                            ? 'The price or the billing period changed since the quote, so nothing was applied or charged. This is the new quote with a new idempotency_key; show it to the user and ask again.'
                             : 'Nothing was applied: confirming needs the idempotency_key of a quote, which ties the approval to the price. This is the quote; show it to the user first.';
                     const lines = [
                         '## Skill change quote',
@@ -374,15 +588,20 @@ export function registerApplyAgentSkills(server, client) {
                         tierChange ? `**Plan:** ${currentTier ?? 'unknown'} to ${tierChange}` : null,
                         `**Monthly price:** ${currentPrice !== null ? formatUsd(currentPrice) : 'unknown'} now, ${formatUsd(newPrice)} after the change${delta !== null ? ` (${delta >= 0 ? '+' : ''}${formatUsd(delta)})` : ''}`,
                         priceNote ? `**Price update:** ${priceNote}` : null,
-                        newCredits !== null ? `**Monthly credits:** ${currentCredits ?? 'unknown'} now, ${newCredits} after the change` : null,
+                        change?.creditsFromRenewal !== null && change?.creditsFromRenewal !== undefined
+                            ? `**Monthly credits:** ${currentCredits !== null ? formatCredits(currentCredits) : 'unknown'} now, ${formatCredits(change.creditsFromRenewal)} ${renewalWhen(billing)}`
+                            : newCredits !== null ? `**Monthly credits:** ${currentCredits !== null ? formatCredits(currentCredits) : 'unknown'} now, ${formatCredits(newCredits)} ${creditsWhen(billing)}` : null,
+                        change && change.creditsNow !== null && change.creditsThisPeriod !== null
+                            ? `**This period:** ${signedCredits(change.creditsNow)} credits now, ${formatCredits(change.creditsThisPeriod)} in all until ${unixToIso(change.periodEnd) ?? 'the period ends'}`
+                            : null,
                         `**Billing:** ${note}`,
                         `**Restart:** ${restart}`,
                         credentialsNeeded.length > 0
-                            ? `**Credentials the new skills need:** ${credentialsNeeded.map(entry => `${entry.skill} (${entry.credentials.join(', ')})`).join('; ')}`
+                            ? `**Credentials the new skills need:** ${credentialsNeeded.map(entry => `${entry.skill} (${entry.credentials.join(', ')})`).join('; ')}.${bindProjectNote(credentialsNeeded)}`
                             : null,
                         '',
                         blocked
-                            ? 'Renew the subscription with manage_agent_billing before applying this change.'
+                            ? `${renewsBack(billing) ? 'Renew the subscription' : 'Start a new plan'} with manage_agent_billing before applying this change.`
                             : `Nothing has changed yet. After the user approves, call apply_agent_skills again with confirm: true and idempotency_key \`${quoteKey}\`.`,
                     ].filter((line) => line !== null);
                     return {
@@ -393,7 +612,12 @@ export function registerApplyAgentSkills(server, client) {
                             idempotencyKey: quoteKey,
                             ...(priceChanged ? { priceChanged: true } : {}),
                             pricing,
-                            billing: { ...billingBase, estimatedChargeNowUsd: estimate, note },
+                            billing: {
+                                ...billingBase,
+                                estimatedChargeNowUsd: change ? change.chargeNowUsd : null,
+                                ...(walletDrop ? { creditNowUsd: change.creditNowUsd, usedCreditsUsd: change.usedCreditsUsd } : {}),
+                                note,
+                            },
                             ...(Array.isArray(preview.enabledSkills) ? { enabledSkills: preview.enabledSkills.map(String) } : {}),
                             restart,
                             nextAction,
@@ -416,8 +640,15 @@ export function registerApplyAgentSkills(server, client) {
                     throw error;
                 if (!outcomeUnknown(error)) {
                     const failure = describeSkillsApplyError(error, billing.plan);
+                    // Code 110 is the whole outcome: the next step reads the agent, and the call is not repeated.
+                    const failedChange = failure.code === 110;
+                    const nextAction = failedChange
+                        ? { tool: 'get_my_agent', arguments: { agent_guid }, reason: 'Check the agent\'s skills and monthly price. Do not repeat the change.' }
+                        : failure.code === 107
+                            ? { tool: 'apply_agent_skills', arguments: { agent_guid, skills, ...(tier ? { tier } : {}), add_dependencies }, reason: 'Get a new quote for this change, with a new key.' }
+                            : undefined;
                     const text = [
-                        '## Skill change not applied',
+                        failedChange ? '## Skill change failed' : '## Skill change not applied',
                         '',
                         failure.message,
                         failure.guidance ? `\n${failure.guidance}` : '',
@@ -430,7 +661,7 @@ export function registerApplyAgentSkills(server, client) {
                             status: 'refused',
                             idempotencyKey: key,
                             billing: { ...billingBase, note: failure.guidance || failure.message },
-                            restart: UNCHANGED_RESTART,
+                            restart: failedChange ? 'The agent does not restart for this change.' : UNCHANGED_RESTART,
                             error: {
                                 code: failure.code,
                                 message: failure.message,
@@ -439,6 +670,7 @@ export function registerApplyAgentSkills(server, client) {
                                 ...(failure.requiredUsd !== undefined ? { requiredUsd: failure.requiredUsd } : {}),
                                 ...(failure.availableUsd !== undefined ? { availableUsd: failure.availableUsd } : {}),
                             },
+                            ...(nextAction ? { nextAction } : {}),
                         },
                         isError: true,
                     };
@@ -446,7 +678,9 @@ export function registerApplyAgentSkills(server, client) {
                 const message = errorText(error);
                 if (sentEmpty) {
                     const note = 'The agent\'s skills already match the request, so the change is in place. Do not repeat it. '
-                        + 'What the earlier call with this idempotency_key charged is not shown here; get_agent_activity with kind usage shows it.';
+                        + (billing.plan === 'prepaid'
+                            ? `What the earlier call with this idempotency_key took from, or credited to, ${walletName(billing)} is not shown here; get_account with recent_transactions shows it.`
+                            : 'Any price difference follows the plan\'s usual billing.');
                     return {
                         content: [{ type: 'text', text: `## No change needed\n\n${note}` }],
                         structuredContent: {
@@ -462,7 +696,7 @@ export function registerApplyAgentSkills(server, client) {
                 // before anything is reported.
                 const holds = await changeHolds(client, agent_guid, plan.requested, tierChange, extra.signal);
                 if (holds === true) {
-                    const note = `The agent's skills now match the request, so the change is in place. Do not repeat it. ${billing.plan === 'prepaid' && billing.status === 'active' ? `The difference for the rest of this period was probably taken from, or credited to, ${walletName(billing)}, and a credit can be spent until this period ends; get_agent_activity with kind usage and get_account show it.` : 'Any price difference follows the plan\'s usual billing.'}`;
+                    const note = `The agent's skills now match the request, so the change is in place. Do not repeat it. ${billing.plan === 'prepaid' && billing.status === 'active' ? `The difference for the rest of this period was probably taken from, or credited to, ${walletName(billing)}; a credit goes back to the balances that paid. get_account with recent_transactions shows the amount, and get_agent_activity with kind usage the credits it moved.` : 'Any price difference follows the plan\'s usual billing.'}`;
                     return {
                         content: [{ type: 'text', text: [
                                     '## Skills updated',
@@ -471,14 +705,14 @@ export function registerApplyAgentSkills(server, client) {
                                     listLine('Turned on', changes.enable),
                                     listLine('Turned off', changes.disable),
                                     `**Billing:** ${note}`,
-                                    `**Restart:** ${restartNote(status, 'skill change')}`,
+                                    `**Restart:** ${skillsMove ? restartNote(status, 'skill change') : TIER_ONLY_RESTART}`,
                                 ].filter((line) => line !== null).join('\n') }],
                         structuredContent: {
                             ...base,
                             status: 'applied',
                             idempotencyKey: key,
                             billing: { ...billingBase, chargedNowUsd: null, note },
-                            restart: restartNote(status, 'skill change'),
+                            restart: skillsMove ? restartNote(status, 'skill change') : TIER_ONLY_RESTART,
                         },
                     };
                 }
@@ -493,7 +727,7 @@ export function registerApplyAgentSkills(server, client) {
                         status: 'refused',
                         idempotencyKey: key,
                         billing: { ...billingBase, note },
-                        restart: unverified ? 'The agent restarts if the change was saved.' : UNCHANGED_RESTART,
+                        restart: !unverified ? UNCHANGED_RESTART : skillsMove ? 'The agent restarts if the change was saved.' : TIER_ONLY_RESTART,
                         error: { code: null, message },
                     },
                     isError: true,
@@ -527,6 +761,13 @@ export function registerApplyAgentSkills(server, client) {
             // result of the earlier call with this key, not a new charge.
             const replayed = sentEmpty && !applied.noOp;
             const serverPricing = applied.pricing ?? {};
+            // An agent with no plan has no period and no renewal yet, as its quote says.
+            const appliedChange = billing.plan === 'none' ? null : readPlanChange({
+                creditsNow: serverPricing.creditsNow,
+                creditsThisPeriod: serverPricing.creditsThisPeriod,
+                creditsFromRenewal: serverPricing.creditsFromRenewal,
+                periodEnd: serverPricing.periodEnd,
+            });
             const pricing = applied.noOp
                 ? undefined
                 : {
@@ -536,30 +777,36 @@ export function registerApplyAgentSkills(server, client) {
                     currentMonthlyCredits: toNumber(serverPricing.previousMonthlyCredits),
                     newMonthlyCredits: toNumber(serverPricing.newMonthlyCredits),
                     deltaMonthlyCredits: toNumber(serverPricing.deltaCredits),
+                    ...periodFields(appliedChange),
                 };
             const charge = appliedBillingNote(billing, applied);
+            const usedCreditsUsd = toNumber(applied.usedCreditsUsd);
             const billingNote = replayed
                 ? `This change was already applied by an earlier call with this idempotency_key, and nothing new was charged now. That call's billing: ${charge.note}`
                 : charge.note;
+            // Wiro says whether this change restarts a running agent; an answer without it goes by the skills that move.
+            const restarts = typeof applied.restartTriggered === 'boolean' ? applied.restartTriggered : skillsMove;
             const restart = applied.noOp || replayed
                 ? UNCHANGED_RESTART
-                : restartNote(status, 'skill change');
+                : restarts ? restartNote(status, 'skill change') : TIER_ONLY_RESTART;
             const firstCredential = credentialsNeeded[0]?.credentials[0];
             const nextAction = applied.noOp || replayed
                 ? undefined
-                : firstCredential
-                    ? {
-                        tool: 'set_agent_credentials',
-                        arguments: { agent_guid, credential: firstCredential },
-                        reason: `See what ${firstCredential} needs before asking the user for it.`,
-                    }
-                    : running
+                : firstCredential === WIRO_PROJECT_CREDENTIAL
+                    ? bindProjectStep(agent_guid, 'Connect the Wiro project the new skills need.')
+                    : firstCredential
                         ? {
-                            tool: 'get_my_agent',
-                            arguments: { agent_guid, wait_seconds: DEFAULT_WAIT_SECONDS },
-                            reason: 'Check that the agent is running again with the new skills.',
+                            tool: 'set_agent_credentials',
+                            arguments: { agent_guid, credential: firstCredential },
+                            reason: `See what ${firstCredential} needs before asking the user for it.`,
                         }
-                        : undefined;
+                        : running && restarts
+                            ? {
+                                tool: 'get_my_agent',
+                                arguments: { agent_guid, wait_seconds: DEFAULT_WAIT_SECONDS },
+                                reason: 'Check that the agent is running again with the new skills.',
+                            }
+                            : undefined;
             const lines = [
                 applied.noOp ? '## No change needed' : replayed ? '## Already applied' : '## Skills updated',
                 '',
@@ -571,11 +818,14 @@ export function registerApplyAgentSkills(server, client) {
                 pricing?.newMonthlyUsd !== undefined && pricing.newMonthlyUsd !== null
                     ? `**Monthly price:** ${formatUsd(pricing.newMonthlyUsd)}${pricing.currentMonthlyUsd !== null ? ` (was ${formatUsd(pricing.currentMonthlyUsd)})` : ''}`
                     : null,
+                pricing && appliedChange?.creditsNow !== null && appliedChange?.creditsNow !== undefined && appliedChange.creditsThisPeriod !== null
+                    ? `**This period:** ${signedCredits(appliedChange.creditsNow)} credits, ${formatCredits(appliedChange.creditsThisPeriod)} in all until ${unixToIso(appliedChange.periodEnd) ?? 'the period ends'}${appliedChange.creditsFromRenewal !== null ? `; ${renewalGives(billing, appliedChange.creditsFromRenewal)}` : ''}`
+                    : null,
                 `**Billing:** ${billingNote}`,
                 `**Restart:** ${restart}`,
                 holds === null ? 'The agent could not be read afterwards to confirm the new skills; get_my_agent shows them.' : null,
                 credentialsNeeded.length > 0
-                    ? `**Still needed:** credentials for ${credentialsNeeded.map(entry => `${entry.skill} (${entry.credentials.join(', ')})`).join('; ')}. Set them with set_agent_credentials or connect_agent_oauth.`
+                    ? `**Still needed:** credentials for ${credentialsNeeded.map(entry => `${entry.skill} (${entry.credentials.join(', ')})`).join('; ')}. ${stillNeededSteps(credentialsNeeded)}`
                     : null,
             ].filter((line) => line !== null);
             return {
@@ -585,7 +835,13 @@ export function registerApplyAgentSkills(server, client) {
                     status: applied.noOp ? 'no_change' : 'applied',
                     idempotencyKey: key,
                     ...(pricing ? { pricing } : {}),
-                    billing: { ...billingBase, chargedNowUsd: charge.charged, note: billingNote },
+                    // The saved answer of an earlier call: its charge is in the note, and this call charged nothing.
+                    billing: {
+                        ...billingBase,
+                        chargedNowUsd: replayed ? 0 : charge.charged,
+                        ...(usedCreditsUsd !== null && usedCreditsUsd > 0 ? { usedCreditsUsd } : {}),
+                        note: billingNote,
+                    },
                     ...(Array.isArray(serverPricing.enabledSkills) ? { enabledSkills: serverPricing.enabledSkills.map(String) } : {}),
                     restart,
                     ...(nextAction ? { nextAction } : {}),