@openephemeris/mcp-server 4.17.0 → 4.19.0

package/dist/tools/apps/ui-resource.d.ts

@@ -0,0 +1,43 @@
+export declare const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Versioned resource URI: `ui://openephemeris/<slug>?v=<server version>`.
+ *
+ * ChatGPT caches a `ui://` resource per connector and never re-reads it for a
+ * URI it has seen — a deploy alone does not refresh the widget. Stamping the
+ * package version into the URI makes every release a new URI, so hosts fetch
+ * the new bundle on their own. Caveat: a widget change must ship with a
+ * version bump to bust the cache (same version ⇒ same URI).
+ *
+ * The SAME string is used in the tool `_meta` (ui.resourceUri and its aliases),
+ * in resources/list and in resources/read, on both transports.
+ */
+export declare function uiResourceUri(slug: string): string;
+/** The URI without its `?v=` query — what resources/read matches on. */
+export declare function uiResourceBase(uri: string): string;
+/**
+ * CSP the bundles actually need: none. Every bundle is a single self-contained
+ * HTML file (JS/CSS inlined, images and icons as data: URIs), and the apps talk
+ * to the host over postMessage only — no fetch, no remote script, style, image
+ * or font. Empty lists are the spec's secure default; declaring them explicitly
+ * documents that this is deliberate, not forgotten.
+ */
+export declare const UI_RESOURCE_CSP: {
+    connectDomains: string[];
+    resourceDomains: string[];
+};
+/**
+ * `_meta` for a `ui://` resource (resources/list entry and resources/read
+ * content item). Two wire forms, same values:
+ *
+ *   ui.*       — MCP Apps (SEP-1865) McpUiResourceMeta.
+ *   openai/*   — ChatGPT's aliases for the same fields.
+ *
+ * prefersBorder: true — the host draws the card border and background; the apps
+ * therefore paint no card, border or glow of their own (shared/tokens.css).
+ *
+ * ui.domain / openai/widgetDomain are deliberately NOT set: their format is
+ * host-specific (a hash subdomain on Claude, a derived *.oaiusercontent.com on
+ * ChatGPT) and a wrong value can stop the widget rendering. Omitted = the
+ * host's default sandbox origin, which is what every live render uses today.
+ */
+export declare function uiResourceMeta(widgetDescription: string): Record<string, unknown>;

package/dist/tools/apps/ui-resource.js

@@ -0,0 +1,66 @@
+/**
+ * ui-resource.ts — identity and `_meta` of the seven MCP App `ui://` resources.
+ *
+ * Imported by every `*-app.ts` (for its resource URI) and by ui-resources.ts
+ * (the list/read registry both transports serve). Kept free of app imports so
+ * the app modules can depend on it without a cycle.
+ */
+import { SERVER_VERSION } from "../index.js";
+export const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Versioned resource URI: `ui://openephemeris/<slug>?v=<server version>`.
+ *
+ * ChatGPT caches a `ui://` resource per connector and never re-reads it for a
+ * URI it has seen — a deploy alone does not refresh the widget. Stamping the
+ * package version into the URI makes every release a new URI, so hosts fetch
+ * the new bundle on their own. Caveat: a widget change must ship with a
+ * version bump to bust the cache (same version ⇒ same URI).
+ *
+ * The SAME string is used in the tool `_meta` (ui.resourceUri and its aliases),
+ * in resources/list and in resources/read, on both transports.
+ */
+export function uiResourceUri(slug) {
+    return `ui://openephemeris/${slug}?v=${SERVER_VERSION}`;
+}
+/** The URI without its `?v=` query — what resources/read matches on. */
+export function uiResourceBase(uri) {
+    const q = uri.indexOf("?");
+    return q === -1 ? uri : uri.slice(0, q);
+}
+/**
+ * CSP the bundles actually need: none. Every bundle is a single self-contained
+ * HTML file (JS/CSS inlined, images and icons as data: URIs), and the apps talk
+ * to the host over postMessage only — no fetch, no remote script, style, image
+ * or font. Empty lists are the spec's secure default; declaring them explicitly
+ * documents that this is deliberate, not forgotten.
+ */
+export const UI_RESOURCE_CSP = {
+    connectDomains: [],
+    resourceDomains: [],
+};
+/**
+ * `_meta` for a `ui://` resource (resources/list entry and resources/read
+ * content item). Two wire forms, same values:
+ *
+ *   ui.*       — MCP Apps (SEP-1865) McpUiResourceMeta.
+ *   openai/*   — ChatGPT's aliases for the same fields.
+ *
+ * prefersBorder: true — the host draws the card border and background; the apps
+ * therefore paint no card, border or glow of their own (shared/tokens.css).
+ *
+ * ui.domain / openai/widgetDomain are deliberately NOT set: their format is
+ * host-specific (a hash subdomain on Claude, a derived *.oaiusercontent.com on
+ * ChatGPT) and a wrong value can stop the widget rendering. Omitted = the
+ * host's default sandbox origin, which is what every live render uses today.
+ */
+export function uiResourceMeta(widgetDescription) {
+    return {
+        ui: {
+            prefersBorder: true,
+            csp: UI_RESOURCE_CSP,
+        },
+        "openai/widgetPrefersBorder": true,
+        "openai/widgetCSP": { connect_domains: [], resource_domains: [] },
+        "openai/widgetDescription": widgetDescription,
+    };
+}

package/dist/tools/apps/ui-resources.d.ts

@@ -0,0 +1,22 @@
+export interface UiResourceEntry {
+    uri: string;
+    /** Short name used in the "bundle not found" error. */
+    label: string;
+    name: string;
+    description: string;
+    /** Tells the model what the widget already shows (ChatGPT openai/widgetDescription). */
+    widgetDescription: string;
+    getBundle: () => string | null;
+}
+export declare const UI_RESOURCES: UiResourceEntry[];
+/** resources/list — only bundles that are actually built. */
+export declare function listUiResources(): Array<Record<string, unknown>>;
+/**
+ * resources/read. Matches on the URI WITHOUT its `?v=` so a host holding an
+ * older (or unversioned) URI from a cached tools/list still gets the current
+ * bundle; the content item echoes the URI that was asked for. Returns null for
+ * a URI that is not one of ours.
+ */
+export declare function readUiResource(uri: string): {
+    contents: Array<Record<string, unknown>>;
+} | null;

package/dist/tools/apps/ui-resources.js

@@ -0,0 +1,105 @@
+/**
+ * ui-resources.ts — the resources/list + resources/read registry for the seven
+ * MCP App bundles, shared by BOTH transports (src/index.ts stdio and
+ * src/server-sse.ts HTTP). They used to carry copy-paste twins of the same
+ * seven if-blocks; one table keeps URI, name, description and `_meta` in step.
+ */
+import { UI_RESOURCE_MIME_TYPE, uiResourceBase, uiResourceMeta } from "./ui-resource.js";
+import { CHART_WHEEL_RESOURCE_URI, getChartWheelBundle } from "./chart-wheel-app.js";
+import { BODYGRAPH_RESOURCE_URI, getBodygraphBundle } from "./bodygraph-app.js";
+import { BI_WHEEL_RESOURCE_URI, getBiWheelBundle } from "./bi-wheel-app.js";
+import { MOON_PHASE_RESOURCE_URI, getMoonPhaseBundle } from "./moon-phase-app.js";
+import { TRANSIT_TIMELINE_RESOURCE_URI, getTransitTimelineBundle } from "./transit-timeline-app.js";
+import { VEDIC_CHART_RESOURCE_URI, getVedicChartBundle } from "./vedic-chart-app.js";
+import { BAZI_RESOURCE_URI, getBaziBundle } from "./bazi-app.js";
+export const UI_RESOURCES = [
+    {
+        uri: CHART_WHEEL_RESOURCE_URI,
+        label: "Chart Wheel",
+        name: "Chart Wheel Explorer",
+        description: "Interactive natal chart wheel with clickable planets, houses, and aspects.",
+        widgetDescription: "Shows the full natal chart wheel — every planet, house cusp and aspect line — and lets the user click any of them for a reading. Don't repeat the placements as a list; highlight what stands out and invite them to explore the wheel.",
+        getBundle: getChartWheelBundle,
+    },
+    {
+        uri: BODYGRAPH_RESOURCE_URI,
+        label: "Bodygraph",
+        name: "Human Design Bodygraph Explorer",
+        description: "Interactive Human Design Bodygraph with clickable centers, gates, and channels.",
+        widgetDescription: "Shows the Human Design bodygraph with type, profile and authority, and lets the user click centers, channels and gates for their meaning. Don't redraw or list the whole chart; interpret the key points and point them to the graph.",
+        getBundle: getBodygraphBundle,
+    },
+    {
+        uri: BI_WHEEL_RESOURCE_URI,
+        label: "Bi-Wheel",
+        name: "Bi-Wheel Explorer",
+        description: "Interactive synastry or transit bi-wheel with cross-aspect lines and clickable planets.",
+        widgetDescription: "Shows two charts as a bi-wheel (natal inside, transits or a second person outside) with the cross-aspects drawn, each clickable. Don't list every cross-aspect; summarize the strongest contacts.",
+        getBundle: getBiWheelBundle,
+    },
+    {
+        uri: MOON_PHASE_RESOURCE_URI,
+        label: "Moon Phase",
+        name: "Moon Phase Explorer",
+        description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
+        widgetDescription: "Shows the current moon: phase, illumination, sign, void-of-course status, speed and the next new and full moon. Don't restate those numbers; add meaning or answer the user's question.",
+        getBundle: getMoonPhaseBundle,
+    },
+    {
+        uri: TRANSIT_TIMELINE_RESOURCE_URI,
+        label: "Transit Timeline",
+        name: "Transit Timeline Explorer",
+        description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
+        widgetDescription: "Shows a dated timeline of upcoming transits to the natal chart, grouped by month, each clickable. Don't re-list the dates; call out the few that matter most.",
+        getBundle: getTransitTimelineBundle,
+    },
+    {
+        uri: VEDIC_CHART_RESOURCE_URI,
+        label: "Vedic Chart",
+        name: "Vedic Chart Explorer",
+        description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
+        widgetDescription: "Shows the sidereal South Indian Rashi chart with every graha in its sign, each clickable. Don't re-list placements; interpret the notable ones.",
+        getBundle: getVedicChartBundle,
+    },
+    {
+        uri: BAZI_RESOURCE_URI,
+        label: "BaZi",
+        name: "BaZi Four Pillars Explorer",
+        description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
+        widgetDescription: "Shows the Four Pillars (year, month, day, hour stems and branches) with the Day Master, each pillar clickable. Don't re-list the pillars; interpret the balance.",
+        getBundle: getBaziBundle,
+    },
+];
+/** resources/list — only bundles that are actually built. */
+export function listUiResources() {
+    return UI_RESOURCES.filter((r) => r.getBundle()).map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: UI_RESOURCE_MIME_TYPE,
+        _meta: uiResourceMeta(r.widgetDescription),
+    }));
+}
+/**
+ * resources/read. Matches on the URI WITHOUT its `?v=` so a host holding an
+ * older (or unversioned) URI from a cached tools/list still gets the current
+ * bundle; the content item echoes the URI that was asked for. Returns null for
+ * a URI that is not one of ours.
+ */
+export function readUiResource(uri) {
+    const base = uiResourceBase(uri);
+    const entry = UI_RESOURCES.find((r) => uiResourceBase(r.uri) === base);
+    if (!entry)
+        return null;
+    const bundle = entry.getBundle();
+    if (!bundle)
+        throw new Error(`${entry.label} UI bundle not found. Run \`npm run build:ui\` to build it.`);
+    return {
+        contents: [{
+                uri,
+                mimeType: UI_RESOURCE_MIME_TYPE,
+                text: bundle,
+                _meta: uiResourceMeta(entry.widgetDescription),
+            }],
+    };
+}

package/dist/tools/apps/vedic-chart-app.d.ts

@@ -17,7 +17,7 @@
  * Also exports resource helpers (getVedicChartBundle, etc.) for use in
  * index.ts and server-sse.ts.
  */
-export declare const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
+export declare const VEDIC_CHART_RESOURCE_URI: string;
 export declare const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getVedicChartBundle(): string | null;

package/dist/tools/apps/vedic-chart-app.js

@@ -21,13 +21,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
+import { UI_RESOURCE_MIME_TYPE, uiResourceUri } from "./ui-resource.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
+import { RENDER_TOKEN_PROPERTY, renderTokenFromVisual, renderTokenHeaders } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
-export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
+export const VEDIC_CHART_RESOURCE_URI = uiResourceUri("vedic-chart");
+export const VEDIC_CHART_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "vedic-chart.html"),
@@ -75,12 +77,14 @@ function buildVedicModelPayload(chartData, birthParams, theme) {
         is_retrograde: retrogradeSet.has(String(p.planet ?? "")),
     }));
     const visual = chartData.visual;
+    const renderToken = renderTokenFromVisual(visual);
     return {
         ayanamsa: String(meta.ayanamsha ?? "lahiri").replace(/\b\w/g, (c) => c.toUpperCase()),
         lagna: lagnaSign,
         planets,
         _svg: visual?.data,
         _theme: theme,
+        ...(renderToken ? { _render_token: renderToken } : {}),
         _birth_params: birthParams,
     };
 }
@@ -237,6 +241,7 @@ registerTool({
                 enum: ["light", "dark"],
                 description: "Render palette for the Rashi grid SVG. Mirrors the MCP host's light/dark color scheme.",
             },
+            render_token: RENDER_TOKEN_PROPERTY,
         },
         required: ["datetime"],
     },
@@ -259,7 +264,12 @@ registerTool({
         };
         if (ayanamsa)
             body.ayanamsa = ayanamsa;
-        const chartData = await client.request("POST", "/vedic/chart", { data: body });
+        // A theme reconcile of the chart explore_vedic_chart just rendered presents
+        // that render's token and is not billed again (same account + inputs).
+        const chartData = await client.request("POST", "/vedic/chart", {
+            data: body,
+            headers: renderTokenHeaders(args.render_token),
+        });
         const modelPayload = buildVedicModelPayload(chartData, {
             datetime,
             location: null,

package/dist/tools/datetime-historical.js

@@ -23,7 +23,7 @@
  * beats an outage; the server remains the single authority whenever it is
  * reachable.
  */
-import { getActiveClient } from "../backend/client.js";
+import { getActiveClient, isBillingOrAuthError } from "../backend/client.js";
 import { hasZoneSuffix, isNaiveClockTime, localToUtcIso } from "./datetime.js";
 /** Where IANA tzdata stops being reference-city best effort. */
 export const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
@@ -69,7 +69,12 @@ export async function localToUtcIsoHistorical(field, dt, tz, coords, timezoneFie
             return res.resolved_utc;
         }
     }
-    catch {
+    catch (err) {
+        // Out of credits / signed out / tier-gated: surface the credit wall
+        // now rather than silently converting with the pre-1970-wrong tzdata
+        // offset (the chart call that follows would hit the same wall anyway).
+        if (isBillingOrAuthError(err))
+            throw err;
         // Server unreachable or rejected the request — fall through to the
         // local conversion rather than failing the chart call.
     }

package/dist/tools/datetime.js

@@ -81,7 +81,8 @@ export const DATETIME_CONTRACT_INSTRUCTIONS = "Datetime contract: every clock ti
     "the naive local time and name the zone in the sibling `timezone` argument (IANA name, " +
     "e.g. `America/Chicago`). A zone-less clock time is a hard 400 — the engine never " +
     "guesses UTC, because an unstated zone shifts the Ascendant by ~15° per hour and moves " +
-    "every house placement. A bare date (no clock time) resolves to 12:00 UTC.\n\n" +
+    "every house placement. A bare date (no clock time) resolves to 12:00 UTC. A pre-1970 " +
+    "local time with coordinates adds 1 credit (historical timezone lookup).\n\n" +
     "PREFER the local-time + `timezone` form over converting to UTC yourself. The server " +
     "resolves the IANA zone against the actual date, including historical DST rules — that " +
     "arithmetic (which offset applied on that specific day, in that specific year) is easy " +

package/dist/tools/dev.js

@@ -46,10 +46,11 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
     // Prices mirror go-sidecar/internal/api/auth/usage_meter.go; tiers mirror
     // auth/middleware.go requiredTierForPath. /iching/* aliases /human-design/*.
-    "CREDIT COST: 1 for most GET calls; /calendar/* 10; /acg/* 10 (Pro tier); /electional/* 5 " +
-    "(find-window and aspect-search are Pro tier; moment-analysis and station-tracker are free); " +
-    "/human-design/* and /iching/* 2; catalogs/health 0; requests over 30s add 1 " +
-    "per 30s. Pass query {format: 'llm'} for compact output.\n\n";
+    "CREDIT COST: 1 for most; /predictive/* 5 (transits/search 5-70 by span); /comparative/* 3; " +
+    "/calendar/* 10 (moon-phases, lunar-standstill 2; cross-quarter 5); /acg/* 10 (Pro); " +
+    "/electional/* 5 (Pro, span-priced searches; moment-analysis, station-tracker free); " +
+    "/human-design/*, /iching/* 2 (composite, transit-chart 3; penta 2/member); catalogs 0; " +
+    "4xx/5xx refunded. Query {format: 'llm'} = compact output.\n\n";
 const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
     "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
@@ -60,13 +61,13 @@ const READ_COMMON_CALLS = "COMMON CALLS:\n" +
     "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
     "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
     "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
-    "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+    "  GET  /calendar/astrology/moon-phases   — next New/Quarter/Full Moon after a date or jd\n" +
     "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
     "  GET  /catalogs/bodies                  — List all supported celestial bodies\n";
 const WRITE_COMMON_CALLS = "COMMON CALLS:\n" +
     "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +
-    "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
+    "  POST /ephemeris/natal/batch            — Up to 100 natal charts in one request (Startup tier)\n" +
     "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
     "  POST /predictive/transits/search       — Transit event search over a date range\n" +
     "  POST /predictive/returns/solar         — Solar return chart\n" +

package/dist/tools/specialized/electional.js

@@ -10,7 +10,8 @@ registerTool({
         "date range, 'find me a good day next month' or 'pick an auspicious window'. Returns the best " +
         "continuous timing windows in the range, scored hourly on essential dignity, aspect quality, sect " +
         "and void-of-course Moon penalties, with optional filters (avoid_voc, lunar_phase).\n\n" +
-        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
+        "CREDIT COST: ≤30 days 5, ≤60 days 8, ≤120 days 12. Pro tier; max window Pro 30 days, Startup " +
+        "60, Scale 120.\n\n" +
         "Do not use to score one specific moment or 'right now' — use electional_moment_analysis; for " +
         "retrograde dates use electional_station_tracker.",
     inputSchema: {
@@ -222,7 +223,7 @@ registerTool({
     description: "Find all active aspects between planets at a specific moment. Returns aspect type, " +
         "orb, quality score, and whether it's applying or separating. Great for checking " +
         "the 'weather' of a given day.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call. Pro tier.\n\n" +
         "EXAMPLE: What aspects are active on March 21, 2026?\n" +
         "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
@@ -276,7 +277,7 @@ registerTool({
         "Sun, Moon, Mercury, Venus, Mars and the lunar nodes — the same body set and formula the CCG hybrid " +
         "transit map (/acg/ccg mode=ccg_hybrid) draws with; every other body stays a transit. Progressed " +
         "crossings carry progressed: true and search_summary.progression names what was progressed.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "CREDIT COST: priced by start→end span — ≤1 month 5, ≤3 months 8, ≤6 months 10, ≤1 year 12. Pro tier.\n\n" +
         "EXAMPLE: When does Mercury cross the Descendant over Warsaw on 2026-07-30?\n" +
         "  latitude=52.2297, longitude=21.0122, bodies='Mercury', angles='DC',\n" +
         "  start='2026-07-30T00:00:00Z', end='2026-07-31T00:00:00Z'",

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 // `field`/`timezoneField` name the caller's own argument path (e.g.
@@ -134,10 +134,19 @@ registerTool({
         }
         // Fan-out: the backend only handles one planet per call; query all 10 in parallel.
         const PLANET_IDS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
-        const results = await Promise.all(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
+        const settled = await Promise.allSettled(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
             date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             planet_id: pid,
-        }).catch(() => null)));
+        })));
+        // Out of credits / signed out / tier-gated: throw the credit-wall (or
+        // auth) error so its top-up link reaches the assistant. Swallowing it
+        // used to return `{planets: {}, success: true}` at zero credits.
+        rethrowBillingOrAuth(settled);
+        const results = settled.map((s) => (s.status === "fulfilled" ? s.value : null));
+        if (results.every((r) => r == null)) {
+            // Every planet failed for a non-billing reason — never report success with no data.
+            throw settled[0].reason;
+        }
         // Merge into a keyed object: { planet_name: {...status} }
         const merged = {};
         for (const res of results) {
@@ -151,7 +160,13 @@ registerTool({
                 };
             }
         }
-        return { planets: merged, datetime: args.datetime, success: true };
+        const failed = PLANET_IDS.filter((_, i) => results[i] == null);
+        return {
+            planets: merged,
+            datetime: args.datetime,
+            success: true,
+            ...(failed.length ? { failed_planet_ids: failed } : {}),
+        };
     },
 });
 // POST /ephemeris/midpoints

package/dist/tools/specialized/hd_group.js

@@ -8,7 +8,7 @@ registerTool({
     name: "human_design_composite",
     description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
         "to show shared channels, authority dynamics, and relationship type.\n\n" +
-        "CREDIT COST: 4 credits per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE (local times + zones):\n" +
         "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
         "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles'\n" +
@@ -74,7 +74,7 @@ registerTool({
     name: "human_design_penta",
     description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
         "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
-        "CREDIT COST: 6 credits per call.\n\n" +
+        "CREDIT COST: 2 credits per member (6-10 for 3-5 people).\n\n" +
         "EXAMPLE (3 people — each datetime states its zone):\n" +
         "  group_name='Team Alpha',\n" +
         "  members=[\n" +

package/dist/tools/specialized/moon.d.ts

@@ -1 +1 @@
-export {};
+export declare const NEXT_LUNAR_PHASE_MAX_COUNT = 12;

package/dist/tools/specialized/moon.js

@@ -1,5 +1,5 @@
 import { registerTool, validateCoordinates } from "../index.js";
-import { getActiveClient } from "../../backend/client.js";
+import { getActiveClient, rethrowBillingOrAuth } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
@@ -53,8 +53,15 @@ registerTool({
             getActiveClient().request("GET", "/ephemeris/moon/phase", { params }),
             getActiveClient().request("GET", "/ephemeris/moon/void-of-course", { params }),
         ]);
+        // Out of credits / signed out / tier-gated must reach the assistant as
+        // the thrown credit-wall (or auth) error with its top-up link — never
+        // as an `error` string tucked inside a success-shaped result.
+        rethrowBillingOrAuth([phase, voc]);
+        // The phase IS the answer; with it gone there is nothing to degrade to.
+        if (phase.status === "rejected")
+            throw phase.reason;
         return {
-            phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+            phase: phase.value,
             void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
         };
     },
@@ -65,7 +72,7 @@ registerTool({
         "date is the next quarter moon' or 'list the next 3 full moons'. Returns the exact UTC datetime " +
         "of each upcoming occurrence of the requested phase (phase = new_moon | full_moon | first_quarter " +
         "| last_quarter), optionally after a given date and for count occurrences.\n\n" +
-        "CREDIT COST: 10-20 credits per occurrence (calendar endpoint); keep count=1 unless asked.\n\n" +
+        "CREDIT COST: 2 credits per occurrence; count max 12.\n\n" +
         "Do not use for the phase or sign the Moon is in right now — use ephemeris_moon_phase; for " +
         "eclipses use ephemeris_next_eclipse.",
     inputSchema: {
@@ -86,7 +93,7 @@ registerTool({
             },
             count: {
                 type: "integer",
-                description: "Number of upcoming occurrences to return (1-12). Default 1.",
+                description: "Number of upcoming occurrences to return (1-12, 2 credits each). Default 1.",
             },
         },
         required: ["phase"],
@@ -113,55 +120,24 @@ registerTool({
         if (!wanted) {
             throw new Error(`Unknown phase '${args.phase}'. Use one of: ${Object.keys(PHASE_IDS).join(", ")}.`);
         }
-        const count = Math.max(1, Math.min(12, args.count ?? 1));
+        const requested = Number.isFinite(Number(args.count)) ? Math.trunc(Number(args.count)) : 1;
+        const count = Math.max(1, Math.min(NEXT_LUNAR_PHASE_MAX_COUNT, requested));
         const startDate = (args.after_date ?? new Date().toISOString()).substring(0, 10);
         const startMs = Date.parse(startDate + "T00:00:00Z");
         if (Number.isNaN(startMs)) {
             throw new Error(`after_date must be an ISO date like '2026-06-01', got '${args.after_date}'.`);
         }
-        const HALF_DAY = 12 * 60 * 60 * 1000;
-        // The calendar endpoint takes a single `date` (it searches forward from noon UTC
-        // that day) and returns the first occurrence of each principal phase within the
-        // following ~30 days. So one request yields at most one hit for the phase we want.
-        async function phaseTimesFrom(probeDay) {
-            const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", { params: { date: probeDay } });
-            const events = Array.isArray(result?.data?.events) ? result.data.events : [];
-            // The endpoint prepends the Moon's *current* 8-phase bucket, stamped with the
-            // query instant (noon UTC of `date`) rather than an event time. Left in, it
-            // reads as a real phase occurring at exactly 12:00:00. Computed moments always
-            // carry sub-second precision, so an exact hit on noon is that placeholder.
-            const probeNoonMs = Date.parse(probeDay + "T12:00:00Z");
-            return events
-                .filter((e) => wanted.includes(String(e?.phase ?? e?.phase_name ?? "").toLowerCase()))
-                .map((e) => Date.parse(e?.time ?? e?.iso_time ?? ""))
-                .filter((ms) => !Number.isNaN(ms) && ms !== probeNoonMs)
-                .sort((a, b) => a - b);
-        }
-        // Probe from the day containing `afterMs - 12h`, so its noon-UTC search origin is
-        // always at or before `afterMs` and an occurrence earlier the same day is still
-        // visible. That leaves under a day of slack behind the cursor, which can hold at
-        // most one occurrence (they are ~29.5 days apart) — hence a single re-probe.
-        async function findNext(afterMs) {
-            let probeMs = afterMs - HALF_DAY;
-            for (let probe = 0; probe < 2; probe++) {
-                const hits = await phaseTimesFrom(new Date(probeMs).toISOString().substring(0, 10));
-                const next = hits.find((ms) => ms > afterMs);
-                if (next != null)
-                    return next;
-                if (hits.length === 0)
-                    return null;
-                probeMs = hits[hits.length - 1] + HALF_DAY;
-            }
-            return null;
-        }
+        const client = getActiveClient();
         const results = [];
-        let cursorMs = startMs - 1; // include an occurrence at exactly 00:00 on after_date
+        // Include an occurrence at exactly 00:00 on after_date: the engine
+        // reports phases strictly after the probe instant.
+        let probeMs = startMs - 1000;
         for (let i = 0; i < count; i++) {
-            const hitMs = await findNext(cursorMs);
+            const hitMs = await nextPhaseAfter(client, probeMs, wanted);
             if (hitMs == null)
                 break;
             results.push({ phase: args.phase, datetime: new Date(hitMs).toISOString() });
-            cursorMs = hitMs;
+            probeMs = hitMs + PROBE_STEP_PAST_HIT_MS;
         }
         // Every principal phase recurs every ~29.5 days, so an empty result is impossible.
         // Fail loudly rather than handing back a plausible "there isn't one" non-answer.
@@ -179,3 +155,35 @@ registerTool({
         };
     },
 });
+// ── Next-lunar-phase lookup ─────────────────────────────────────────────────
+//
+// /calendar/astrology/moon-phases is the engine's exact principal-phase
+// finder. It takes a single instant (`jd`, or a `date` = noon UTC), not a
+// range, and returns the first New / First Quarter / Full / Third Quarter
+// strictly after it within 30 days — so one call yields exactly one
+// occurrence of each phase. The Go meter prices it at a flat 2 credits (one
+// fixed 30-day span; usage_meter.go). There is no range form to widen, so
+// `count` occurrences of one phase take `count` calls: 2 credits each.
+//
+// Probing with `jd` (the exact instant) rather than `date` (noon UTC) is what
+// makes it one call per occurrence: the search origin sits exactly on the
+// cursor, so no occurrence between midnight and noon can be skipped and no
+// re-probe is needed.
+export const NEXT_LUNAR_PHASE_MAX_COUNT = 12;
+const UNIX_EPOCH_JD = 2440587.5;
+const DAY_MS = 86_400_000;
+/** Step past a found root before the next probe, so the solver's tolerance cannot return it again. */
+const PROBE_STEP_PAST_HIT_MS = 60_000;
+async function nextPhaseAfter(client, afterMs, wanted) {
+    const jd = afterMs / DAY_MS + UNIX_EPOCH_JD;
+    const result = await client.request("GET", "/calendar/astrology/moon-phases", {
+        params: { jd: jd.toFixed(6) },
+    });
+    const events = Array.isArray(result?.data?.events) ? result.data.events : [];
+    const hits = events
+        .filter((e) => wanted.includes(String(e?.phase ?? e?.phase_name ?? "").toLowerCase()))
+        .map((e) => Date.parse(e?.time ?? e?.iso_time ?? ""))
+        .filter((ms) => !Number.isNaN(ms) && ms > afterMs)
+        .sort((a, b) => a - b);
+    return hits.length ? hits[0] : null;
+}