@okostream/mcp 0.18.1 → 0.18.3

package/README.md

@@ -95,14 +95,21 @@ A new page is a draft: viewers of its public URL see "not published".
   `oko_start_session`, `oko_extend_session` and `oko_publish_telegram_post`
   state the charge (or the refund) when called without `confirm`, name the
   wallet that pays, and take nothing until the organizer confirms. The amount in
-  the preview is the amount charged; the public price list is at
+  the preview of a charge is the amount charged; the preview of a withdrawal
+  (`oko_unpublish_event`, the trash) says "up to", because part of the refund
+  may be forfeited and only the answer after confirmation gives the exact
+  figures. The public price list is at
   [okostream.app/pricing](https://okostream.app/pricing) and is not copied here.
-- **`oko_wallet` reads the wallet.** It returns the lumen balance, the grants and
-  the ledger of the organizer behind the key (scope `wallet:read`, included in
-  the `operator` and `full` presets, not in `readOnly`). Keys created before that scope existed get `SCOPE_REQUIRED` and
-  need a new key. A page in a shared workspace is paid from the workspace
-  owner's wallet: its balance is told, in the previews and refusals, to whoever
-  may spend from it; its grants and ledger are the owner's to read.
+- **`oko_wallet` reads the plan and the wallet.** It returns the plan (tier,
+  status, period end, source), the lumen balance, the grants and the ledger of
+  the organizer behind the key, with the link to the cabinet's Billing page
+  (scope `wallet:read`, included in the `operator` and `full` presets, not in
+  `readOnly`). It cannot buy, change or cancel anything: a plan or lumens are
+  bought only in that cabinet. Keys created before that scope existed get
+  `SCOPE_REQUIRED` and need a new key. A page in a shared workspace is paid from
+  the workspace owner's wallet: its balance is told, in the previews and
+  refusals, to whoever may spend from it; its grants and ledger are the owner's
+  to read.
 - **Payment and terms are web-only.** Plans and lumens are bought, and terms
   accepted, only in the OKO web cabinet, and no MCP tool collects a password,
   card or bank details, or agreement to terms on anyone's behalf.
@@ -137,8 +144,10 @@ Refusals are explicit and never require guessing:
   workspace owner does not hold another shared workspace, another member, or
   the capability at all. A refused invitation stays valid. Plans are bought only
   in the OKO cabinet, never through MCP.
-- `WORKSPACE_INACTIVE` — `oko_publish_event` in a shared workspace the plan no
-  longer publishes into (Pro: only the workspace its owner chose as active).
+- `WORKSPACE_INACTIVE` — `oko_publish_event` in a shared workspace the plan does
+  not hold open (only a new publication is closed): Core — shared workspaces are
+  not included (Pro); Pro — one active workspace (the owner's choice, or Max); no
+  live subscription — renew.
 
 **One install path.** Every supported client — Claude Code, Codex, and any
 MCP client that takes a command with arguments and env — runs the package
@@ -171,7 +180,7 @@ always works. The result's `sourceVia` says who fetched the image.
 - Read analytics, session reports, geography, engagement, and form submissions.
 - Manage workspaces, invitations, notifications, and Telegram publishing
   (5 lumens per post, shown in the confirmation preview).
-- Read the lumen balance and ledger of your own wallet (`oko_wallet`).
+- Read your own plan, lumen balance and ledger (`oko_wallet`).
 
 OKO MCP acts as the organizer represented by the selected access key. It does
 not inherit platform-owner privileges. Keys are scoped and revocable, and

package/dist/server.js

@@ -70718,7 +70718,7 @@ var GUIDE_RESOURCES = [
       "- `telegram:write`: link channels and manage Telegram posts.",
       "- `workspace:read` and `workspace:write`: workspaces, members, invites, and notifications.",
       "- `leads:read`: read form submissions; deletion also requires `setup:write`.",
-      "- `wallet:read`: read the lumen balance, grants and ledger of the organizer's own wallet (`oko_wallet`); nothing can be bought, granted or spent with it.",
+      "- `wallet:read`: read the plan, the lumen balance, grants and ledger of the organizer's own wallet (`oko_wallet`); nothing can be bought, changed, granted or spent with it.",
       "",
       "Payment and terms are web-only: no tool collects a password, card or bank details, or agreement to terms on anyone's behalf. Plans and lumens are bought, and terms accepted, only in the OKO web cabinet."
     ].join("\n")
@@ -116320,7 +116320,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.18.1";
+var OKO_MCP_VERSION = "0.18.3";
 
 // build/auth.js
 var state = null;
@@ -116565,6 +116565,9 @@ function sessionReportUrl(eventId, sessionId) {
 function inviteUrl(code) {
   return `${APP_ORIGIN}/invite/${code}`;
 }
+function billingUrl() {
+  return `${APP_ORIGIN}/app/billing`;
+}
 function eventLinks(eventId) {
   return {
     url: eventUrl(eventId),
@@ -118045,8 +118048,18 @@ var notificationsMarkOutputSchema = external_exports.object({
   markedRead: external_exports.number().int().nonnegative(),
   notificationIds: external_exports.array(external_exports.string())
 }).passthrough();
+var walletPlanSchema = external_exports.object({
+  tier: external_exports.enum(["core", "pro", "max", "legacy"]),
+  status: external_exports.enum(["active", "past_due", "canceled_at_period_end", "expired"]),
+  source: external_exports.enum(["lava", "operator", "legacy-exit", "transition-b", "smoke"]).nullable(),
+  periodEnd: external_exports.string().nullable(),
+  graceUntil: external_exports.string().nullable()
+});
 var walletOutputSchema = external_exports.object({
   uid: external_exports.string(),
+  billingUrl: external_exports.string().url(),
+  plan: walletPlanSchema.nullable().optional(),
+  planRead: external_exports.enum(["ok", "unreadable"]).optional(),
   hasWallet: external_exports.boolean(),
   balance: external_exports.number().int().nullable(),
   unit: external_exports.literal("lumens"),
@@ -118165,7 +118178,7 @@ var SCOPE_UNLOCKS = {
   "workspace:read": "listing workspaces, members, invites, notifications",
   "workspace:write": "workspace management, invites, profile edits",
   "leads:read": "reading and exporting leads",
-  "wallet:read": "reading the lumen balance, grants and ledger of the organizer's own wallet"
+  "wallet:read": "reading the plan, the lumen balance, grants and ledger of the organizer's own wallet"
 };
 function presetsWithScope(scope) {
   return Object.entries(MCP_PRESETS).filter(([, scopes]) => scopes.includes(scope)).map(([name7]) => name7);
@@ -119155,7 +119168,7 @@ function registerPublicationTools(server2) {
       examples: ["Call without confirm, show the organizer the bill from the preview, and call again with confirm: true after explicit consent."],
       notes: [
         "The wallet belongs to the workspace owner; a member publishing in a shared workspace spends the owner's lumens.",
-        "Refusals carry errorCode and whatToDo: ENTITLEMENT_REQUIRED, INSUFFICIENT_TOKENS, EVENT_DATE_REQUIRED, EVENT_WINDOW_PASSED (the event date is more than 48 hours in the past \u2014 move it forward), PAYER_UNRESOLVED, WORKSPACE_INACTIVE (the plan holds fewer shared workspaces than the owner has \u2014 on Pro only the workspace the owner chose as active takes NEW publications; the owner picks it on the OKO cabinet's Workspaces page, or moves to Max), EDIT_PERMISSION_REQUIRED, EVENT_NOT_FOUND, EVENT_IN_TRASH, EVENT_DATE_LOCKED (from oko_update_event, not this tool).",
+        "Refusals carry errorCode and whatToDo: ENTITLEMENT_REQUIRED, INSUFFICIENT_TOKENS, EVENT_DATE_REQUIRED, EVENT_WINDOW_PASSED (the event date is more than 48 hours in the past \u2014 move it forward), PAYER_UNRESOLVED, WORKSPACE_INACTIVE (only a NEW publication into a shared workspace is closed: Core \u2014 shared workspaces are not included (Pro); Pro \u2014 one active workspace (the owner's choice, or Max); no live subscription \u2014 renew; the owner makes a workspace the active one on the OKO cabinet's Workspaces page), EDIT_PERMISSION_REQUIRED, EVENT_NOT_FOUND, EVENT_IN_TRASH, EVENT_DATE_LOCKED (from oko_update_event, not this tool).",
         'Repeating confirm on a published page charges nothing and repairs viewer-side switches; on a page whose show is over ("held"/\u041F\u0440\u043E\u0432\u0435\u0434\u0435\u043D\u043E) it charges nothing either and starts nothing new \u2014 duplicate the page for a new show.',
         "Once published, the event date moves only inside the show window bought here (oko_update_event refuses EVENT_DATE_LOCKED outside it): for another date, unpublish with oko_unpublish_event first while the window has not opened, or duplicate the page."
       ]
@@ -121008,6 +121021,36 @@ function topUpsPaid(billing) {
 function topUpsNote(topUps) {
   return topUps > 0 ? `The ${topUps} lumens paid on top of the publication (blocks and control room turned on after it) are NOT returned; publishing again bills those blocks in the new show's bill.` : "";
 }
+var REFUND_UP_TO_NOTE = "Part of the charge may not come back: lumens that would already have burned by now (their plan period is over) are forfeited, not returned. The exact figures are known only after confirmation: the answer carries `refunded` (what came back to the wallet) and `forfeited` (what did not).";
+function forfeitedNote(forfeited) {
+  return forfeited > 0 ? `${forfeited} lumens of the charge were not returned (forfeited): lumens that would already have burned by now come back nowhere.` : "";
+}
+function forfeitedOf(outcome) {
+  const value = outcome.forfeited;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function unpublishPreviewNote(topUps) {
+  return [
+    "Unpublishing takes the page back to draft and returns UP TO the publication charge (`refundUpTo`) to the wallet that paid; the live layer (chat, presence, session start) closes immediately.",
+    REFUND_UP_TO_NOTE,
+    "If the page only needs another date inside its show window, oko_update_event moves it with no refund and no new charge \u2014 prefer that to unpublishing.",
+    topUpsNote(topUps)
+  ].filter(Boolean).join(" ");
+}
+function unpublishAnswerHints(outcome, topUps) {
+  const refunded = typeof outcome.refunded === "number" ? outcome.refunded : 0;
+  const forfeited = forfeitedOf(outcome);
+  if (refunded > 0) {
+    return [
+      `${refunded} lumens were refunded to payerUid ${safeString(outcome.payerUid)}.`,
+      forfeitedNote(forfeited),
+      ...topUps > 0 ? [topUpsNote(topUps)] : []
+    ].filter(Boolean);
+  }
+  if (outcome.alreadyUnpublished === true)
+    return ["The page was already a draft \u2014 nothing was refunded now."];
+  return [forfeitedNote(forfeited)].filter(Boolean);
+}
 function previewUnpublish(eventId, event, nowMs) {
   const billing = isRecord4(event.billing) ? event.billing : {};
   const state2 = billing.state === "published" || billing.state === "held" ? billing.state : "unpublished";
@@ -121067,18 +121110,19 @@ function registerUnpublicationTools(server2) {
   server2.registerTool("oko_unpublish_event", {
     title: "Unpublish event page",
     description: toolDescription({
-      summary: `Take a published OKO event page back to draft and refund its publication charge. Works only before the page's show window opens; once it has opened (or the page shows "held"/\u041F\u0440\u043E\u0432\u0435\u0434\u0435\u043D\u043E), the page stays published for good. Without confirm nothing is written: the call returns a preview \u2014 what will happen and how many lumens come back to which wallet, or the refusal if it cannot be done now. Built from the event document, not a server round trip: CF61 has no dry run of its own. With confirm: true the page becomes a draft and the charge is refunded in one step.`,
+      summary: `Take a published OKO event page back to draft and refund its publication charge. Works only before the page's show window opens; once it has opened (or the page shows "held"/\u041F\u0440\u043E\u0432\u0435\u0434\u0435\u043D\u043E), the page stays published for good. Without confirm nothing is written: the call returns a preview \u2014 what will happen and UP TO how many lumens come back (refundUpTo) to which wallet, or the refusal if it cannot be done now. Built from the event document, not a server round trip, so it cannot tell how much of the charge was forfeited (lumens that would already have burned): the exact refunded and forfeited figures come only after confirm. With confirm: true the page becomes a draft and the refund (up to the charge) is paid in one step.`,
       args: [
         "eventId: event to unpublish.",
         "confirm: true only after the organizer has seen the preview and agreed."
       ],
-      returns: "status unpublished with alreadyUnpublished, refunded, balanceAfter, mirrorsUpdated, plus title, links and hints.",
-      examples: ["Call without confirm, show the organizer what will be refunded and to whom, and call again with confirm: true after explicit consent."],
+      returns: "status unpublished with alreadyUnpublished, refunded (what came back), forfeited (what did not, only when above zero), balanceAfter, mirrorsUpdated, plus title, links and hints. The preview (no confirm) carries refundUpTo, not refunded.",
+      examples: ["Call without confirm, show the organizer UP TO how much comes back and to whom (never promise the whole charge), and call again with confirm: true after explicit consent; then tell the exact refunded and forfeited."],
       notes: [
         "Refunds go to the wallet that paid for this publication (billing.payerUid), which may not be the organizer behind this key in a shared workspace.",
+        "The refund is UP TO the charge: the share of it drawn from lumens that would already have burned (their plan period is over) is forfeited. The preview cannot see that, so it says refundUpTo; the answer after confirm says refunded and forfeited.",
         "Only the publication charge comes back. Lumens paid AFTER publication for blocks and the control room turned on later (oko_configure_blocks, oko_configure_cards with confirm) are NOT returned: the preview names them as topUpsNotRefunded, and publishing again bills those blocks in the new show's bill.",
         "Publishing again afterwards (oko_publish_event) is a new show and a new charge, with a fresh show window from the new date.",
-        "This is how the event date moves on a published page: unpublish (refund), change the date with oko_update_event, publish again (new charge) \u2014 oko_update_event refuses to move the date directly while the page stays published (EVENT_DATE_LOCKED).",
+        "A date INSIDE the page's show window moves with oko_update_event directly, with no refund and no new charge \u2014 prefer that when the charge may be partly forfeited. A date outside the window: unpublish (refund, up to the charge), change the date with oko_update_event, publish again (new charge); oko_update_event refuses the move otherwise (EVENT_DATE_LOCKED).",
         "One rule for every page: an old page that paid nothing is unpublished the same way before its window opens (the refund is 0 lumens) and refused the same way once it has taken place (WINDOW_OPEN, windowState after).",
         "Refusals carry errorCode and whatToDo: NOT_PUBLISHED, DATE_REQUIRED, WINDOW_OPEN, EDIT_PERMISSION_REQUIRED, EVENT_NOT_FOUND, EVENT_IN_TRASH."
       ]
@@ -121115,13 +121159,13 @@ function registerUnpublicationTools(server2) {
         requireConfirm(confirm, TOOL2, {
           eventId,
           title,
-          refunded: preview.tokensCharged,
+          refundUpTo: preview.tokensCharged,
           topUpsNotRefunded: preview.topUps,
           payerUid: preview.payerUid,
           showId: preview.showId,
           windowStart: preview.windowStart,
           windowEnd: preview.windowEnd,
-          note: ["Unpublishing returns this page's publication charge to the wallet that paid and takes the page back to draft; the live layer (chat, presence, session start) closes immediately.", topUpsNote(preview.topUps)].filter(Boolean).join(" ")
+          note: unpublishPreviewNote(preview.topUps)
         });
       }
     }
@@ -121135,9 +121179,7 @@ function registerUnpublicationTools(server2) {
         throw new ToolRefusal(named);
       throw error3;
     }
-    const refunded = typeof outcome.refunded === "number" ? outcome.refunded : 0;
-    const topUps = topUpsPaid(isRecord4(event.billing) ? event.billing : {});
-    const hints = refunded > 0 ? [`${refunded} lumens were refunded to payerUid ${safeString(outcome.payerUid)}.`, ...topUps > 0 ? [topUpsNote(topUps)] : []] : outcome.alreadyUnpublished === true ? ["The page was already a draft \u2014 nothing was refunded now."] : [];
+    const hints = unpublishAnswerHints(outcome, topUpsPaid(isRecord4(event.billing) ? event.billing : {}));
     return textResult({
       ...outcome,
       title,
@@ -121151,7 +121193,8 @@ function registerUnpublicationTools(server2) {
 var TRASH_OUTPUT_SCHEMA = external_exports.object({
   trashed: external_exports.string(),
   purgeAfter: external_exports.number().nullable(),
-  refunded: external_exports.number().nonnegative().optional()
+  refunded: external_exports.number().nonnegative().optional(),
+  forfeited: external_exports.number().nonnegative().optional()
 }).passthrough();
 function trashRefundWarning(event, nowMs) {
   const billing = event.billing && typeof event.billing === "object" && !Array.isArray(event.billing) ? event.billing : null;
@@ -121160,9 +121203,17 @@ function trashRefundWarning(event, nowMs) {
   const window2 = windowFromEvent(event, nowMs);
   if (window2 !== null && window2.state !== "before")
     return null;
-  const charge = typeof billing.tokensCharged === "number" ? `${billing.tokensCharged} lumens` : "its lumens";
+  const charge = typeof billing.tokensCharged === "number" ? `${billing.tokensCharged} lumens` : "what the publication paid";
   const topUps = topUpsNote(topUpsPaid(billing));
-  return `This page is published. Moving it to the trash also unpublishes it and refunds ${charge} to the wallet that paid, because its show window has not opened yet.${topUps ? ` ${topUps}` : ""}`;
+  return `This page is published. Moving it to the trash also unpublishes it and returns up to ${charge} to the wallet that paid, because its show window has not opened yet. ${REFUND_UP_TO_NOTE}${topUps ? ` ${topUps}` : ""}`;
+}
+function trashAnswerHints(data) {
+  const refunded = typeof data.refunded === "number" ? data.refunded : 0;
+  const forfeited = forfeitedOf(data);
+  return [
+    ...refunded > 0 ? [`${refunded} lumens were refunded to the wallet that paid for this page's publication: it was still inside its show window when it was trashed.`] : [],
+    ...forfeited > 0 ? [forfeitedNote(forfeited)] : []
+  ];
 }
 function registerLifecycleTools(server2) {
   const moveToTrash = async (toolName, { eventId, confirm }) => {
@@ -121177,7 +121228,7 @@ function registerLifecycleTools(server2) {
     const trash = httpsCallable(functions, "trashEvent");
     const data = (await trash({ eventId })).data;
     const refunded = typeof data.refunded === "number" ? data.refunded : 0;
-    const hints = refunded > 0 ? [`${refunded} lumens were refunded to the wallet that paid for this page's publication: it was still inside its show window when it was trashed.`] : [];
+    const hints = trashAnswerHints(data);
     return textResult({ ...data, refunded, ...hints.length ? { hints } : {} });
   };
   server2.registerTool("oko_delete_event", {
@@ -121189,7 +121240,7 @@ function registerLifecycleTools(server2) {
       examples: ["Use after showing the exact event title and asking the organizer to confirm moving it to trash."],
       notes: [
         "Recoverable for 30 days with oko_restore_event. This does not create an event lifecycle status.",
-        "A published, paid page still inside its show window is also unpublished and its charge refunded; the preview (without confirm) names it in `warning`, and the answer's `refunded` field says how much came back."
+        "A published, paid page still inside its show window is also unpublished and UP TO its charge refunded; the preview (without confirm) names it in `warning`, and the answer's `refunded` field says how much came back (`forfeited`, when above zero, how much did not)."
       ]
     }),
     inputSchema: { eventId: eventIdField, confirm: external_exports.boolean().optional().describe("Required true to move the event to trash.") },
@@ -121205,7 +121256,7 @@ function registerLifecycleTools(server2) {
       examples: ["Use after showing the exact event title and asking the organizer to confirm moving it to trash."],
       notes: [
         "End any active analytics session first. Restore with oko_restore_event before the purge deadline.",
-        "A published, paid page still inside its show window is also unpublished and its charge refunded; the preview (without confirm) names it in `warning`, and the answer's `refunded` field says how much came back."
+        "A published, paid page still inside its show window is also unpublished and UP TO its charge refunded; the preview (without confirm) names it in `warning`, and the answer's `refunded` field says how much came back (`forfeited`, when above zero, how much did not)."
       ]
     }),
     inputSchema: { eventId: eventIdField, confirm: external_exports.boolean().optional().describe("Required true to move the event to trash.") },
@@ -122772,6 +122823,88 @@ function ledgerRowForOutput(id, raw) {
     forgiven: isSessionRow ? readCount(raw.forgiven ?? ref2.forgiven) : null
   };
 }
+var PLAN_TIERS = ["core", "pro", "max", "legacy"];
+var PLAN_STATUSES = ["active", "past_due", "canceled_at_period_end", "expired"];
+var PLAN_SOURCES = ["lava", "operator", "legacy-exit", "transition-b", "smoke"];
+function momentMs(value) {
+  if (value instanceof Date)
+    return Number.isNaN(value.getTime()) ? null : value.getTime();
+  if (isRecord6(value) && typeof value.toMillis === "function") {
+    const ms = value.toMillis();
+    return typeof ms === "number" && Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}
+function readOrganizerPlan(accessData) {
+  if (!isRecord6(accessData))
+    return { state: "unreadable" };
+  const raw = accessData.plan;
+  if (raw === void 0 || raw === null)
+    return { state: "none" };
+  if (!isRecord6(raw))
+    return { state: "unreadable" };
+  const tier = PLAN_TIERS.find((candidate) => candidate === raw.tier);
+  const status = PLAN_STATUSES.find((candidate) => candidate === raw.status);
+  if (!tier || !status)
+    return { state: "unreadable" };
+  const dates = { periodStart: null, periodEnd: null, graceUntil: null };
+  for (const key of ["periodStart", "periodEnd", "graceUntil"]) {
+    const value = raw[key];
+    if (value === void 0 || value === null)
+      continue;
+    const ms = momentMs(value);
+    if (ms === null)
+      return { state: "unreadable" };
+    dates[key] = ms;
+  }
+  const seats = raw.seatsIncluded;
+  if (seats !== void 0 && seats !== null && !(Number.isInteger(seats) && seats > 0))
+    return { state: "unreadable" };
+  const iso2 = (ms) => ms === null ? null : new Date(ms).toISOString();
+  return {
+    state: "plan",
+    plan: {
+      tier,
+      status,
+      source: PLAN_SOURCES.find((candidate) => candidate === raw.source) ?? null,
+      periodEnd: iso2(dates.periodEnd),
+      graceUntil: iso2(dates.graceUntil)
+    }
+  };
+}
+function planAnswer(read) {
+  const url = billingUrl();
+  const reading = read.kind === "access" && read.exists ? readOrganizerPlan(read.data) : { state: "unreadable" };
+  const standing = `This tool only reads. A plan or lumens are bought, changed or cancelled only in the OKO web cabinet (${url}): send the organizer there, and never ask for card details or a password.`;
+  if (reading.state === "unreadable") {
+    return {
+      plan: null,
+      planRead: "unreadable",
+      hints: [
+        `The plan could not be read (the platform refused the read, or the stored plan is malformed). Do not guess it: the organizer sees the real plan in the OKO web cabinet (${url}).`,
+        standing
+      ]
+    };
+  }
+  if (reading.state === "none") {
+    return {
+      plan: null,
+      planRead: "ok",
+      hints: [`This organizer has no plan: the paid features and spending lumens stay unavailable until a plan is bought in the OKO web cabinet (${url}). This tool cannot buy one.`, standing]
+    };
+  }
+  const { plan } = reading;
+  const hints = [];
+  if (plan.status === "past_due") {
+    hints.push(`The last renewal payment failed. The plan keeps working until graceUntil${plan.graceUntil ? ` (${plan.graceUntil})` : ""}; the organizer renews it in the OKO web cabinet (${url}) before then.`);
+  } else if (plan.status === "canceled_at_period_end") {
+    hints.push(`The subscription is cancelled: the plan works until periodEnd${plan.periodEnd ? ` (${plan.periodEnd})` : ""} and does not renew. Any change to it is made only in the OKO web cabinet (${url}).`);
+  } else if (plan.status === "expired") {
+    hints.push(`The plan has ended. A new plan is bought only in the OKO web cabinet (${url}).`);
+  }
+  hints.push(standing);
+  return { plan, planRead: "ok", hints };
+}
 function walletReadRefusal() {
   return {
     ...textResult({
@@ -122788,7 +122921,7 @@ function walletReadRefusal() {
   };
 }
 function walletAnswer(input) {
-  const { uid, walletExists, walletData, grantDocs, ledgerDocs, max } = input;
+  const { uid, walletExists, walletData, grantDocs, ledgerDocs, max, planRead } = input;
   let balance = null;
   if (walletExists) {
     balance = readWalletBalance(walletData);
@@ -122818,6 +122951,7 @@ function walletAnswer(input) {
   const last = page.at(-1);
   const lastAt = isRecord6(last?.data) ? last.data.at : void 0;
   const nextCursor = hasMore ? timestampCursorFrom(lastAt, last?.id) : null;
+  const planBlock = planRead ? planAnswer(planRead) : null;
   const hints = [];
   if (grantDocs !== null && !walletExists)
     hints.push("This organizer has no wallet yet: nothing was ever granted. Plans and lumens are bought only in the OKO web cabinet.");
@@ -122825,8 +122959,12 @@ function walletAnswer(input) {
     hints.push("Some rows did not read (unreadableGrants / unreadableLedgerRows): tell the organizer, the balance is still the wallet's own figure.");
   if (hasMore && nextCursor === null)
     hints.push("There are more ledger rows but the page boundary could not be named: the listing stops here.");
+  if (planBlock)
+    hints.push(...planBlock.hints);
   return {
     uid,
+    billingUrl: billingUrl(),
+    ...planBlock ? { plan: planBlock.plan, planRead: planBlock.planRead } : {},
     hasWallet: walletExists,
     balance,
     unit: "lumens",
@@ -122838,16 +122976,26 @@ function walletAnswer(input) {
     hints
   };
 }
+async function readPlanDocument(uid) {
+  try {
+    const snap = await getDoc(doc(firestore, "organizerAccess", uid));
+    return { kind: "access", exists: snap.exists(), data: snap.data() };
+  } catch (error3) {
+    if (isFirestorePermissionDenied(error3))
+      return { kind: "refused" };
+    throw error3;
+  }
+}
 function registerWalletTools(server2) {
   server2.registerTool("oko_wallet", {
     title: "Read lumen wallet",
     description: toolDescription({
-      summary: "Read the lumen balance, the grants (buckets) and the ledger of the organizer's OWN wallet, the one behind this key. Read-only.",
+      summary: "Read the plan, the lumen balance, the grants (buckets) and the ledger of the organizer's OWN account, the one behind this key, with the link to the OKO cabinet's Billing page. Read-only: it cannot buy anything.",
       args: [
         "limit: ledger rows per page, default 20, max 50, newest first.",
-        "cursor: nextCursor returned by the previous page. The grants come with the first page only; the balance with every page."
+        "cursor: nextCursor returned by the previous page. The plan and the grants come with the first page only; the balance with every page."
       ],
-      returns: 'hasWallet, balance (whole lumens, null when the organizer has no wallet yet), unit "lumens", grants on the first page (id, bucket plan|rollover|topup, amount, remaining, expiresAt, createdAt), ledger rows (id, kind grant|charge|refund|expire|settlement, amount, delta, balanceAfter, by, at, eventId, showId, workspaceId, postId, sessionId, minutes, forgiven), unreadableGrants/unreadableLedgerRows (rows that did not read: say so, never hide them) and cursor pagination metadata.',
+      returns: `billingUrl (the cabinet's Billing page), plan on the first page (tier core|pro|max|legacy, status active|past_due|canceled_at_period_end|expired, source lava|operator|legacy-exit|transition-b|smoke or null, periodEnd and graceUntil as ISO times or null; plan is null when the organizer has no plan) with planRead ok|unreadable (unreadable: the plan could not be read, so null means unknown, not no plan), hasWallet, balance (whole lumens, null when the organizer has no wallet yet), unit "lumens", grants on the first page (id, bucket plan|rollover|topup, amount, remaining, expiresAt, createdAt), ledger rows (id, kind grant|charge|refund|expire|settlement, amount, delta, balanceAfter, by, at, eventId, showId, workspaceId, postId, sessionId, minutes, forgiven), unreadableGrants/unreadableLedgerRows (rows that did not read: say so, never hide them) and cursor pagination metadata.`,
       examples: [
         "Use before publishing a page or starting a session when the organizer asks how many lumens are left or what was charged.",
         "Use to explain a charge or a refund: every ledger row names what paid (eventId, sessionId, postId) and the balance after it."
@@ -122855,7 +123003,8 @@ function registerWalletTools(server2) {
       notes: [
         "Needs the wallet:read scope. A key created before that scope existed gets SCOPE_REQUIRED and its scopes cannot be changed: the organizer creates a new key in the OKO cabinet.",
         "Shows only the wallet of the organizer behind the key. A page in a shared workspace is paid from the WORKSPACE OWNER's wallet: the publish, session and Telegram previews and refusals name that payer and tell its balance to whoever may spend from it (publish, start a session, send posts); the owner's grants and ledger are theirs to read, not this key's.",
-        "This tool cannot buy, grant, top up or spend lumens. Plans, lumens and payment details belong to the OKO web cabinet only; never ask the organizer for card data or a password.",
+        "This tool cannot buy, change, cancel, grant, top up or spend anything. A plan and lumens are bought, changed and cancelled in the OKO web cabinet only (billingUrl): send the organizer there, and never ask for card data or a password.",
+        "The plan shown is the organizer's own, the one behind this key. A paid action on a page of a shared workspace is judged by the PAYER's plan (the workspace owner's), which this key cannot read: the refusal of the paid tool names what is missing.",
         "Refusals of the paid tools use the same codes as the web: ENTITLEMENT_REQUIRED (the plan does not include the feature) and INSUFFICIENT_TOKENS (not enough lumens); PLATFORM_REJECTED_READ here means the platform refused the read."
       ]
     }),
@@ -122872,10 +123021,11 @@ function registerWalletTools(server2) {
       const constraints = [orderBy("at", "desc"), limit(max + 1)];
       if (cursor)
         constraints.splice(1, 0, startAfter(...parseTimestampCursor(cursor)));
-      const [walletSnap, grantsSnap, ledgerSnap] = await Promise.all([
+      const [walletSnap, grantsSnap, ledgerSnap, planRead] = await Promise.all([
         getDoc(doc(firestore, "wallets", uid)),
         first ? getDocs(query2(collection(firestore, "wallets", uid, "grants"), orderBy("createdAt", "desc"), limit(GRANTS_LIMIT))) : Promise.resolve(null),
-        getDocs(query2(collection(firestore, "wallets", uid, "ledger"), ...constraints))
+        getDocs(query2(collection(firestore, "wallets", uid, "ledger"), ...constraints)),
+        first ? readPlanDocument(uid) : Promise.resolve(null)
       ]);
       return textResult(walletAnswer({
         uid,
@@ -122883,7 +123033,8 @@ function registerWalletTools(server2) {
         walletData: walletSnap.data(),
         grantDocs: grantsSnap ? grantsSnap.docs.map((item) => ({ id: item.id, data: item.data() })) : null,
         ledgerDocs: ledgerSnap.docs.map((item) => ({ id: item.id, data: item.data() })),
-        max
+        max,
+        planRead
       }));
     } catch (error3) {
       if (isFirestorePermissionDenied(error3))
@@ -122958,6 +123109,7 @@ function workspaceRefusalResult(tool, error3, subject = {}) {
 }
 
 // build/tools/workspaces.js
+var INVITE_EMAIL_PATTERN = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]{1,64}@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/;
 function registerWorkspaceTools(server2) {
   server2.registerTool("oko_list_workspaces", {
     title: "List workspaces",
@@ -123198,8 +123350,8 @@ function registerWorkspaceTools(server2) {
     description: toolDescription({
       summary: "List workspace invite links for a workspace owned by the organizer.",
       args: ["workspaceId: workspace owned by the organizer."],
-      returns: "invites array with code, claim status, permissions, and inviteUrl.",
-      examples: ["Use before revoking or sharing an invite code."]
+      returns: "invites array with code, claim status, permissions, and inviteUrl; for an invite created with an email also mailStatus (queued | sent | not_sent) and, when not_sent, mailReason (rate_limited | address | not_allowed | undeliverable) \u2014 what the platform did with the letter. No mailStatus on an invite with an email means the platform has not reported yet: do not read it as sent. sent means the provider accepted the letter, not that it was delivered.",
+      examples: ["Use before revoking or sharing an invite code, and to check whether the platform's letter went out."]
     }),
     inputSchema: { workspaceId: external_exports.string().min(1) },
     outputSchema: external_exports.object({ workspaceId: external_exports.string(), invites: external_exports.array(unknownRecordSchema), count: external_exports.number().int().nonnegative() }).passthrough(),
@@ -123271,20 +123423,23 @@ function registerWorkspaceTools(server2) {
   server2.registerTool("oko_create_workspace_invite", {
     title: "Create workspace invite",
     description: toolDescription({
-      summary: "Create a workspace invite for a known OKO workspace.",
+      summary: "Create a workspace invite for a known OKO workspace. When `email` is given, OKO Stream itself emails the invitation to that address: an external effect, not a note.",
       args: [
         "workspaceId: workspace owned by the authenticated organizer.",
         "code: optional invite code, 16-64 chars; omitted means generated (recommended).",
-        "email: optional intended recipient email.",
+        "email: optional email of the invitee, one plain address (`name@domain`). When given, the PLATFORM sends the invitation letter to it \u2014 the workspace name and the invite link, in the language of the account that owns that address when there is one and it has a language, otherwise in the inviter's language, otherwise English; the `comment` is never put into the letter. A letter cannot be recalled: confirm the exact address with the workspace owner first. Omit it to get only the link.",
         // The schema is `workspacePermissionsSchema`: nine booleans, all
         // required, no extra keys. "optional whitelist" read as "send the
         // ones you want", and every such call was rejected by validation
         // before it reached the platform.
         "permissions: required object of all nine workspace permission booleans (createEvents, editSetup, deleteEvents, controlLive, moderateChat, startSession, viewAnalytics, downloadReports, sendNotifications) \u2014 every key must be present, extra keys are rejected; set false for the ones the invitee should not get.",
-        "confirm: must be true."
+        "confirm: must be true. Without it the call is refused with a preview that names the address the platform would email."
       ],
-      returns: "workspaceId, invite code, inviteUrl, and created=true.",
-      examples: ["Use only after confirming the recipient and permission set with the workspace owner."]
+      returns: "workspaceId, invite code, inviteUrl, created=true, and emailRequested=true when an address was given: the platform queues the letter AFTER the invite exists, and this result does not say the letter was delivered \u2014 what became of it is mailStatus on the invite, read with oko_list_workspace_invites a moment later.",
+      examples: ["Use only after confirming the recipient and permission set with the workspace owner."],
+      notes: [
+        "The invite itself and its inviteUrl are always created and always work. The LETTER is held to limits and is checked again just before it goes out: at most 1 letter an hour for one workspace and address, 3 a day to one address, 20 a day per inviter; and none if the invite was revoked or accepted meanwhile, or the plan has no free seat. When no letter goes out the invite stays valid: pass inviteUrl on yourself \u2014 mailStatus not_sent says so (mailReason not_allowed means the invite cannot be accepted right now, so passing the link on would not help either)."
+      ]
     }),
     inputSchema: {
       workspaceId: external_exports.string().min(1),
@@ -123296,25 +123451,31 @@ function registerWorkspaceTools(server2) {
       // deliberately stays 4: they accept codes that ALREADY exist, including
       // the historical six-character ones.
       code: external_exports.string().min(16).max(MAX_WORKSPACE_INVITE_CODE_LENGTH).optional(),
-      email: external_exports.string().email().optional(),
+      email: external_exports.string().max(254).regex(INVITE_EMAIL_PATTERN, "One plain email address (name@domain), no names, lists or spaces.").optional().describe("Optional. When given, OKO Stream emails the invitation to this address."),
       comment: external_exports.string().max(500).default(""),
       permissions: workspacePermissionsSchema,
-      confirm: external_exports.boolean().optional()
+      confirm: external_exports.boolean().optional().describe("Required true. With an email, true also means the workspace owner has confirmed that address.")
     },
-    outputSchema: external_exports.object({ workspaceId: external_exports.string(), code: external_exports.string(), inviteUrl: external_exports.string().url(), created: external_exports.boolean() }).passthrough(),
+    outputSchema: external_exports.object({ workspaceId: external_exports.string(), code: external_exports.string(), inviteUrl: external_exports.string().url(), created: external_exports.boolean(), emailRequested: external_exports.boolean().optional() }).passthrough(),
     annotations: writeTool
   }, async (args) => {
     const { uid } = await authed(["workspace:write"]);
     const workspace = await readWorkspaceForOwner(args.workspaceId, uid);
     if (!isSharedWorkspaceId(args.workspaceId))
       throw new Error(personalWorkspaceLimitMessage("creating invites"));
-    requireConfirm(args.confirm, "oko_create_workspace_invite", { workspaceId: args.workspaceId, code: args.code, email: args.email });
+    requireConfirm(args.confirm, "oko_create_workspace_invite", {
+      workspaceId: args.workspaceId,
+      code: args.code,
+      email: args.email,
+      ...args.email ? { platformEmailsThisAddress: true } : {}
+    });
     const code = (args.code?.trim() || randomInviteCode()).toUpperCase();
     const url = inviteUrl(code);
+    const email2 = args.email?.trim() ?? "";
     await setDoc(doc(firestore, "workspaceInvites", code), {
       workspaceId: args.workspaceId,
       workspaceName: safeString(workspace.name, "Workspace"),
-      email: args.email ?? "",
+      email: email2,
       comment: args.comment,
       permissions: normalizeWorkspacePermissions(args.permissions),
       createdBy: uid,
@@ -123322,7 +123483,7 @@ function registerWorkspaceTools(server2) {
       claimed: false,
       claimedBy: null
     });
-    return textResult({ workspaceId: args.workspaceId, code, inviteUrl: url, created: true });
+    return textResult({ workspaceId: args.workspaceId, code, inviteUrl: url, created: true, ...email2 ? { emailRequested: true } : {} });
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {