@openephemeris/mcp-server 4.2.0 → 4.3.1

package/CHANGELOG.md

@@ -7,6 +7,107 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.3.1] — 2026-07-29
+
+Two rendering fixes surfaced by the Phase-0 v4.3 audit, plus a companion
+server-side fix that unblocks the tool this release advertised.
+
+### Fixed
+
+- **`account_usage` no longer tells unlimited-plan customers they have "0 remaining".**
+  A service-tier row reports `included_units = -1` (the sentinel for unlimited);
+  the tool rendered it literally as *"Credits: 993 used of -1 included — 0 remaining
+  (0% used)"* — three mutually contradictory statements about the same quota, and
+  the "0 remaining" reading a paid customer as cut off. Unlimited plans now render
+  as *"Credits: 993 used · unlimited plan"* with no synthesized percentage.
+  NEW-11 from the audit.
+- **Companion:** `ephemeris_house_cusps` accepts the `timezone` companion the
+  4.3.0 schema advertised. The Go server rejected the field at the JSON decode
+  layer with *"unknown field provided in DateTimeInput"*, so an agent following
+  OE's own naive-datetime error message hit a second error. Fixed server-side
+  in [`openephemeris/openephemeris#466`](https://github.com/openephemeris/openephemeris/pull/466)
+  (no MCP change) — the schema, generated struct, and handler were all correct;
+  only the bespoke JSON decoder's allowlist was out of sync. NEW-10 from the
+  audit.
+
+### Added
+
+- **`account_usage` now prints a `Server version` line.** External audits and
+  eval runs could not previously attribute a score to a specific published
+  build — the version is set in `serverInfo.version` on `initialize` but was
+  not surfaced anywhere a human-readable tool response could echo. NEW-9 from
+  the audit.
+
+---
+
+## [4.3.0] — 2026-07-29
+
+The bodygraph iframes get the same view toggle across every mode (natal, transit,
+connection), the datetime contract stops being repeated on every datetime tool,
+and eleven tools stop lying about which zone the caller named.
+
+### Added
+
+- **Bodygraph mandala layout works on transit and connection overlay iframes.**
+  The natal bodygraph iframe has had a graph ↔ mandala toggle since 3.19.0;
+  the transit and connection overlays did not, because the overlay render path
+  dropped `layout` on the floor. The mandala scene builder already delegates
+  channel and center rendering to the same overlay-aware helpers the graph
+  layout uses, so this was purely a matter of wiring: openapi
+  `VisualRenderConfig` gains an optional `layout` (`graph` | `mandala`),
+  `visualConfigFromRender` copies it through, `RenderBodygraphOverlayEmbed`
+  applies the same mandala scaling the natal path already had, and both
+  `explore_human_design_transit` and `explore_human_design_connection` accept
+  a `layout` argument that forwards to `visual_config.layout`. The iframe's
+  existing view-toggle button renders on overlay payloads too now, and
+  reroutes via the `_refetch` metadata so the model never sees the switch.
+  Overlay attributes (`data-connection-type`, `data-transit-new`, the overlay
+  legend) survive the mandala switch — the mandala inherits the overlay-aware
+  channel builder unchanged.
+
+### Changed
+
+- **The datetime contract paragraph moved off every tool description and into the
+  server `instructions` field.** The 130-token contract text used to be sent on
+  every datetime-accepting tool and re-sent on every model pass — ~40 sites'
+  worth of pure repetition. It's now stated once, up front, in `instructions`
+  (both stdio and HTTP transports), with each parameter description carrying a
+  one-sentence rule + a pointer back. The 400 rejection still rewrites the
+  caller's own value into each remedy, so a host that fails to propagate
+  `instructions` learns the rule from the first violation. Core surface dropped
+  from ~18.7k to ~17.2k tokens (−1.5k, 8%); full surface dropped from ~35.1k to
+  ~29.9k (−5.2k, 15%). NEW-4 from the Phase-0 v4.1 audit.
+
+### Fixed
+
+- **`ephemeris_house_cusps` (and ten other DateTimeInput tools) lied about how the
+  caller supplied the zone.** Calling with `datetime="1987-07-15T09:01:00"` +
+  `timezone="America/Chicago"` came back with `datetime_zone: "UTC"` and
+  `datetime_zone_source: "offset"` — because the tool converted the value to a
+  Z-suffixed UTC string on the client before sending it, and the server (correctly)
+  described what it received. `ephemeris_natal_chart` reported the same input as
+  `America/Chicago` / `timezone`, so the two tools disagreed about the same fact,
+  and the mislabelled `"UTC"` was the exact wrong value the naive-datetime contract
+  was written to catch — a false alarm on a correct call.
+
+  The 11 tools that take a `DateTimeInput` body field (`ephemeris_house_cusps`,
+  `ephemeris_planet_position`, `ephemeris_dignities`, `ephemeris_retrograde_status`,
+  `ephemeris_midpoints`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`,
+  `ephemeris_angles_points`, `ephemeris_solar_return`, `ephemeris_lunar_return`,
+  `ephemeris_natal_transits`) now pass a naive datetime + IANA zone through as
+  `{ iso, timezone: { iana_name } }` — the shape the Go handler already resolves
+  correctly and stamps as `datetime_zone_source: "timezone"`. Endpoints whose body
+  field is named `*_utc` (`vedic_chart`, Human Design, the ACG `epoch`) still
+  pre-convert client-side, because their Go types are strict RFC 3339 `time.Time`
+  and cannot accept a companion zone.
+
+  Contract test asserts, for every fixed tool, that the wire body carries the naive
+  datetime and the IANA name — not a synthesized Z-suffixed value — and the Go
+  handler test proves all three input forms (`Z`, `±HH:MM`, naive + IANA) resolve
+  to the same instant and each self-describes its provenance correctly.
+
+---
+
 ## [4.2.0] — 2026-07-29
 
 `ephemeris_next_lunar_phase` could not answer the question it exists to answer. The

package/dist/index.js

@@ -6,6 +6,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, SERVER_VERSION } from "./tools/index.js";
+import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
 import { captureEvent, distinctIdFor } from "./analytics.js";
 import { listPrompts, getPromptContent } from "./prompts.js";
 // ── MCP App resource imports ────────────────────────────────────────────────
@@ -62,6 +63,15 @@ const server = new Server({
             },
         },
     },
+    instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
+        "or approximate positions yourself; always call a tool. " +
+        "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
+        "prefer the explore_* tools — they render interactive visuals inline. " +
+        "ephemeris_* tools return data; use format='llm' on them for compact output. " +
+        "If the user has no birth data handy, start with the sky right now — " +
+        "explore_moon_phase and ephemeris_retrograde_status need none. " +
+        "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
+        DATETIME_CONTRACT_INSTRUCTIONS,
 });
 // Which slice of the registry this process advertises. Tools outside the core
 // surface stay callable by name — this only controls what tools/list returns.

package/dist/server-sse.js

@@ -24,6 +24,7 @@ import { InMemoryEventStore } from "./event-store.js";
 import { captureEvent, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface } from "./tools/index.js";
+import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
@@ -269,7 +270,8 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
             "ephemeris_* tools return data; use format='llm' on them for compact output. " +
             "If the user has no birth data handy, start with the sky right now — " +
             "explore_moon_phase and ephemeris_retrograde_status need none. " +
-            "See the 'welcome_to_open_ephemeris' prompt for orientation.",
+            "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
+            DATETIME_CONTRACT_INSTRUCTIONS,
     });
     // --- Tool handlers ---
     server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/dist/tools/apps/bodygraph-app.js

@@ -1321,6 +1321,14 @@ registerTool({
                 description: "Visual theme for the overlay bodygraph. Set automatically by the embedded app to match " +
                     "the host; defaults to dark. You normally never need to pass this.",
             },
+            layout: {
+                type: "string",
+                enum: ["graph", "mandala"],
+                description: "Overlay composition. 'graph' (default) is the classic bodygraph rectangle with the " +
+                    "transit's activated channels highlighted; 'mandala' nests the same overlay inside the " +
+                    "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
+                    "the model.",
+            },
         },
         required: ["datetime"],
     },
@@ -1363,9 +1371,10 @@ registerTool({
         // dark MCP hosts — mirror the natal path's explicit dark default. The
         // iframe re-calls this tool with theme once it detects the host theme.
         const theme = args.theme === "light" ? "light" : "dark";
+        const layout = args.layout === "mandala" ? "mandala" : undefined;
         if (bundleAvailable) {
             body.include_visual = true;
-            body.visual_config = { theme };
+            body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
         const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
         const transit = (resp?.transit ?? {});
@@ -1443,6 +1452,14 @@ registerTool({
                 description: "Visual theme for the overlay bodygraph. Set automatically by the embedded app to match " +
                     "the host; defaults to dark. You normally never need to pass this.",
             },
+            layout: {
+                type: "string",
+                enum: ["graph", "mandala"],
+                description: "Overlay composition. 'graph' (default) is the classic bodygraph rectangle with connected " +
+                    "channels classified by connection type; 'mandala' nests the same overlay inside the " +
+                    "concentric ring set the natal chart uses. Set by the in-iframe layout toggle, never by " +
+                    "the model.",
+            },
         },
         required: ["person_a", "person_b"],
     },
@@ -1472,9 +1489,10 @@ registerTool({
         const bundleAvailable = Boolean(getBodygraphBundle());
         // Mirror the transit tool: explicit dark default, host-theme refetch.
         const theme = args.theme === "light" ? "light" : "dark";
+        const layout = args.layout === "mandala" ? "mandala" : undefined;
         if (bundleAvailable) {
             body.include_visual = true;
-            body.visual_config = { theme };
+            body.visual_config = { theme, ...(layout ? { layout } : {}) };
         }
         const resp = await client.request("POST", "/human-design/composite", { data: body });
         const connections = Array.isArray(resp?.connections) ? resp.connections : [];

package/dist/tools/datetime.d.ts

@@ -27,19 +27,30 @@ export declare function hasZoneSuffix(value: string): boolean;
 /** The canonical description for a birth / chart-moment datetime parameter. */
 export declare const DATETIME_DESC: string;
 /** The canonical description for the companion `timezone` parameter. */
-export declare const TIMEZONE_DESC: string;
+export declare const TIMEZONE_DESC = "IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.";
 /** The canonical description for a search-window date parameter (date or datetime). */
-export declare const WINDOW_DATE_DESC: string;
+export declare const WINDOW_DATE_DESC = "ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.";
 /** The `timezone` property to spread into a tool's inputSchema. */
 export declare const TIMEZONE_PROPERTY: {
     readonly type: "string";
-    readonly description: string;
+    readonly description: "IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.";
 };
 /** Build a `<prefix>_timezone` property with a tailored example. */
 export declare function timezoneProperty(label: string, example?: string): {
     readonly type: "string";
-    readonly description: string;
+    readonly description: `IANA timezone for ${string} (e.g. \`${string}\`); required when the datetime is naive.`;
 };
+/**
+ * The full statement of the datetime contract, for the server `instructions`
+ * field. Every datetime-accepting tool's parameter description points here.
+ *
+ * Setting this on the server (both stdio and HTTP transports) surfaces the
+ * contract to the model once, up front, instead of re-sending it on every
+ * tool description. Clients that fail to propagate `instructions` still get
+ * the rule enforced by the 400 rejection, whose detail rewrites the caller's
+ * own value into each remedy — the model learns from the first violation.
+ */
+export declare const DATETIME_CONTRACT_INSTRUCTIONS: string;
 /**
  * The rejection message. Names both remedies, rewriting the caller's own value
  * into each — the commonest failure is not realising the value was ambiguous.
@@ -53,6 +64,39 @@ export declare function ambiguousDatetimeMessage(field: string, value: string, t
  * resolved server-side (or by `localToUtcIso` for the `*_utc` endpoints).
  */
 export declare function assertZonedDatetime(field: string, value: unknown, timezone?: unknown, timezoneField?: string): void;
+/**
+ * Body shape for a `DateTimeInput`-typed request field (`date_time`,
+ * `birth_datetime`, `target_datetime`, `transit_datetime`, …). The Go type
+ * carries an optional `timezone` companion, so a naive local wall-clock time
+ * plus its IANA name is a legitimate value the server resolves itself.
+ */
+export type DateTimeInputBody = {
+    iso: string;
+    timezone?: {
+        iana_name: string;
+    };
+};
+/**
+ * Build a `DateTimeInput` body that PRESERVES zone provenance.
+ *
+ * Use this in place of `localToUtcIso` for any endpoint whose body field is a
+ * `DateTimeInput` (i.e. `{ iso, timezone?, components?, julian_day? }`). Those
+ * endpoints already resolve a naive datetime plus an inner `timezone.iana_name`
+ * server-side and stamp `datetime_zone_source: "timezone"` on the response.
+ * Pre-converting to UTC on the client makes the server believe the caller
+ * supplied a Z-suffixed offset — the metadata then reports
+ * `datetime_zone: "UTC", datetime_zone_source: "offset"` for a call that
+ * actually named "America/Chicago", and `house_cusps` and `natal_chart`
+ * disagree about the same fact (NEW-8).
+ *
+ * - Zone-suffixed input passes through (with `±HHMM` normalised to `±HH:MM`);
+ *   server records `source: "offset"`.
+ * - Naive input + `tz` returns `{ iso, timezone: { iana_name: tz } }`; server
+ *   records `source: "timezone", zone: tz`.
+ * - Naive input with no `tz` throws (same behaviour as `localToUtcIso`).
+ * - Date-only or unrecognised strings pass through untouched.
+ */
+export declare function toDateTimeInputBody(field: string, dt: string, tz?: string, timezoneField?: string): DateTimeInputBody;
 /**
  * Convert a datetime to a UTC ISO 8601 string for the endpoints whose field is
  * named `*_utc` and whose Go type is a strict RFC 3339 `time.Time`.
@@ -61,5 +105,10 @@ export declare function assertZonedDatetime(field: string, value: unknown, timez
  * appends a bare "Z" to a zone-less value — it throws instead. Appending Z
  * asserts the input was UTC, which is exactly the silent assumption that made
  * the original defect invisible.
+ *
+ * For endpoints that take a `DateTimeInput` body field (not `*_utc`), prefer
+ * `toDateTimeInputBody` — pre-converting to UTC erases the zone name the
+ * caller supplied, and the response metadata then lies about how the moment
+ * was named.
  */
 export declare function localToUtcIso(field: string, dt: string, tz?: string, timezoneField?: string): string;

package/dist/tools/datetime.js

@@ -34,26 +34,26 @@ export function hasZoneSuffix(value) {
     return ZONE_SUFFIX.test((value ?? "").trim());
 }
 // ─── Canonical parameter documentation ───────────────────────────────────────
-// Every tool that accepts a datetime uses these strings verbatim, so the contract
-// reads identically everywhere. `test/datetime-contract.test.ts` fails if a tool
-// description grows an ISO example that violates it.
+// Every datetime-accepting tool uses these constants verbatim, so the contract
+// reads identically everywhere and `test/datetime-contract.test.ts` can gate
+// on the exact string. They deliberately point at the server `instructions`
+// field (spelled out in DATETIME_CONTRACT_INSTRUCTIONS below) rather than
+// restating the contract inline: the previous ~130-token paragraph was repeated
+// on every datetime tool, so each character cost ~40x across the surface and
+// was re-sent on every model pass. NEW-4 in the Phase-0 v4.1 audit asked for
+// it back.
+//
+// The full rule still lives somewhere the model can see it: `instructions`
+// carries the expanded text, and the 400 rejection rewrites the caller's own
+// value into each remedy — the model learns from the first violation even
+// when a host fails to propagate `instructions`.
 /** The canonical description for a birth / chart-moment datetime parameter. */
-// Kept deliberately terse: this string is repeated on every datetime-accepting
-// tool, so each character costs ~40x across the surface and is re-sent on every
-// model pass. Every RULE stays; the rationale for the rule lives in the module
-// docstring above, which the model never sees.
-export const DATETIME_DESC = "ISO 8601 datetime that states its zone. Either put the zone on the value " +
-    "('1987-07-15T09:01:00-05:00', or '...T14:01:00Z' for UTC), or pass local " +
-    "wall-clock time plus the `timezone` argument. A zone-less time is REJECTED. " +
-    "A date with no time ('1987-07-15') resolves to 12:00 UTC.";
+export const DATETIME_DESC = "ISO 8601 datetime; zone required — a `Z`/±HH:MM suffix or the `timezone` argument. " +
+    "Date-only resolves to 12:00 UTC. Full rule: server `instructions`.";
 /** The canonical description for the companion `timezone` parameter. */
-export const TIMEZONE_DESC = "IANA timezone name for the birth/observation location, e.g. 'America/Chicago'. " +
-    "Required when the datetime has no 'Z' or ±HH:MM offset; ignored when it does. " +
-    "Historical DST is resolved correctly.";
+export const TIMEZONE_DESC = "IANA timezone (e.g. `America/Chicago`); required when the datetime is naive, ignored otherwise.";
 /** The canonical description for a search-window date parameter (date or datetime). */
-export const WINDOW_DATE_DESC = "ISO 8601 date ('2026-01-01') or a zoned datetime ('2026-01-01T00:00:00Z'). " +
-    "A date with no time resolves to 12:00 UTC. A time without a 'Z' or ±HH:MM offset " +
-    "is rejected as ambiguous.";
+export const WINDOW_DATE_DESC = "ISO 8601 date or zoned datetime; a naive clock time is rejected. Date-only resolves to 12:00 UTC.";
 /** The `timezone` property to spread into a tool's inputSchema. */
 export const TIMEZONE_PROPERTY = {
     type: "string",
@@ -63,10 +63,25 @@ export const TIMEZONE_PROPERTY = {
 export function timezoneProperty(label, example = "America/Chicago") {
     return {
         type: "string",
-        description: `IANA timezone name for ${label}, e.g. '${example}'. ` +
-            "Required when that datetime has no 'Z' or ±HH:MM offset; ignored when it does.",
+        description: `IANA timezone for ${label} (e.g. \`${example}\`); required when the datetime is naive.`,
     };
 }
+/**
+ * The full statement of the datetime contract, for the server `instructions`
+ * field. Every datetime-accepting tool's parameter description points here.
+ *
+ * Setting this on the server (both stdio and HTTP transports) surfaces the
+ * contract to the model once, up front, instead of re-sending it on every
+ * tool description. Clients that fail to propagate `instructions` still get
+ * the rule enforced by the 400 rejection, whose detail rewrites the caller's
+ * own value into each remedy — the model learns from the first violation.
+ */
+export const DATETIME_CONTRACT_INSTRUCTIONS = "Datetime contract: every clock time needs a zone. Either put the zone on the value " +
+    "(`1987-07-15T09:01:00-05:00` for a local time, or `...T14:01:00Z` for UTC), or pass " +
+    "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.";
 // ─── Enforcement ─────────────────────────────────────────────────────────────
 /**
  * The rejection message. Names both remedies, rewriting the caller's own value
@@ -98,6 +113,39 @@ export function assertZonedDatetime(field, value, timezone, timezoneField = "tim
         return;
     throw new Error(ambiguousDatetimeMessage(field, value, timezoneField));
 }
+/**
+ * Build a `DateTimeInput` body that PRESERVES zone provenance.
+ *
+ * Use this in place of `localToUtcIso` for any endpoint whose body field is a
+ * `DateTimeInput` (i.e. `{ iso, timezone?, components?, julian_day? }`). Those
+ * endpoints already resolve a naive datetime plus an inner `timezone.iana_name`
+ * server-side and stamp `datetime_zone_source: "timezone"` on the response.
+ * Pre-converting to UTC on the client makes the server believe the caller
+ * supplied a Z-suffixed offset — the metadata then reports
+ * `datetime_zone: "UTC", datetime_zone_source: "offset"` for a call that
+ * actually named "America/Chicago", and `house_cusps` and `natal_chart`
+ * disagree about the same fact (NEW-8).
+ *
+ * - Zone-suffixed input passes through (with `±HHMM` normalised to `±HH:MM`);
+ *   server records `source: "offset"`.
+ * - Naive input + `tz` returns `{ iso, timezone: { iana_name: tz } }`; server
+ *   records `source: "timezone", zone: tz`.
+ * - Naive input with no `tz` throws (same behaviour as `localToUtcIso`).
+ * - Date-only or unrecognised strings pass through untouched.
+ */
+export function toDateTimeInputBody(field, dt, tz, timezoneField = "timezone") {
+    const value = (dt ?? "").trim();
+    if (hasZoneSuffix(value)) {
+        return { iso: value.replace(/([+-]\d{2})(\d{2})$/, "$1:$2") };
+    }
+    if (!isNaiveClockTime(value)) {
+        return { iso: value };
+    }
+    if (!tz || tz.trim() === "") {
+        throw new Error(ambiguousDatetimeMessage(field, value, timezoneField));
+    }
+    return { iso: value, timezone: { iana_name: tz } };
+}
 /**
  * Convert a datetime to a UTC ISO 8601 string for the endpoints whose field is
  * named `*_utc` and whose Go type is a strict RFC 3339 `time.Time`.
@@ -106,6 +154,11 @@ export function assertZonedDatetime(field, value, timezone, timezoneField = "tim
  * appends a bare "Z" to a zone-less value — it throws instead. Appending Z
  * asserts the input was UTC, which is exactly the silent assumption that made
  * the original defect invisible.
+ *
+ * For endpoints that take a `DateTimeInput` body field (not `*_utc`), prefer
+ * `toDateTimeInputBody` — pre-converting to UTC erases the zone name the
+ * caller supplied, and the response metadata then lies about how the moment
+ * was named.
  */
 export function localToUtcIso(field, dt, tz, timezoneField = "timezone") {
     const value = (dt ?? "").trim();

package/dist/tools/specialized/account.js

@@ -1,4 +1,4 @@
-import { registerTool } from "../index.js";
+import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient, BackendError, DASHBOARD_ACCOUNT_URL, LOGIN_SIGNUP_URL, UPGRADE_URL, WALLET_TOPUP_URL, } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 // Tiers where the primary next step is a wallet top-up rather than a plan change.
@@ -63,6 +63,10 @@ registerTool({
         const period = row.month || args?.month || new Date().toISOString().substring(0, 7);
         const used = row.total_units ?? 0;
         const included = row.included_units ?? 0;
+        // `included_units < 0` is a sentinel for unlimited (service/enterprise plans).
+        // Rendering it literally as "0 remaining (0% used)" tells a paid customer they
+        // are cut off — the exact opposite of the truth. NEW-11 from the audit.
+        const unlimited = included < 0;
         const remaining = Math.max(included - used, 0);
         const percent = row.percent_units_used ?? (included > 0 ? Math.round((used / included) * 1000) / 10 : 0);
         const totalCalls = row.total_calls ?? 0;
@@ -71,7 +75,9 @@ registerTool({
             ``,
             `- **Plan:** ${tier}`,
             `- **Period:** ${period}`,
-            `- **Credits:** ${used.toLocaleString()} used of ${included.toLocaleString()} included — **${remaining.toLocaleString()} remaining** (${percent}% used)`,
+            unlimited
+                ? `- **Credits:** ${used.toLocaleString()} used · unlimited plan`
+                : `- **Credits:** ${used.toLocaleString()} used of ${included.toLocaleString()} included — **${remaining.toLocaleString()} remaining** (${percent}% used)`,
             `- **Total API calls:** ${totalCalls.toLocaleString()}`,
         ];
         if ((row.overage_units ?? 0) > 0) {
@@ -86,6 +92,10 @@ registerTool({
                 lines.push(`- **Renews:** ${renewal.toISOString().substring(0, 10)}`);
             }
         }
+        // Verifiable build identifier so external evals can attribute every score to
+        // a specific published version rather than trusting the tester's word.
+        // NEW-9 from the audit.
+        lines.push(`- **Server version:** ${SERVER_VERSION}`);
         lines.push(``);
         if (WALLET_TIERS.has(tier)) {
             lines.push(`**Need more credits?** Top up your wallet at ${WALLET_TOPUP_URL} (from $5), ` +

package/dist/tools/specialized/comparative.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, assertZonedDatetime, localToUtcIso, timezoneProperty } from "../datetime.js";
+import { DATETIME_DESC, assertZonedDatetime, toDateTimeInputBody, timezoneProperty } from "../datetime.js";
 /** Reject a zone-less person datetime here, before a credit is spent on it. */
 function assertPersonZoned(prefix, args) {
     assertZonedDatetime(`${prefix}_datetime`, args[`${prefix}_datetime`], args[`${prefix}_timezone`], `${prefix}_timezone`);
@@ -203,12 +203,10 @@ registerTool({
             subject: buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
         };
         if (args.transit_datetime) {
-            // transit_datetime is a DateTimeInput on the backend, and unlike the
-            // subject it has no timezone companion — so , which
-            // was declared but never read, is resolved here.
-            body.transit_datetime = {
-                iso: localToUtcIso("transit_datetime", args.transit_datetime, args.transit_timezone, "transit_timezone"),
-            };
+            // transit_datetime is a DateTimeInput — pass the caller's zone name
+            // through so the response's datetime_zone_source reads "timezone",
+            // not "offset" (NEW-8).
+            body.transit_datetime = toDateTimeInputBody("transit_datetime", args.transit_datetime, args.transit_timezone, "transit_timezone");
         }
         const query = {};
         if (args.format)

package/dist/tools/specialized/ephemeris_core.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, toDateTimeInputBody } from "../datetime.js";
 // POST /ephemeris/planet-position — OE-016
 registerTool({
     name: "ephemeris_planet_position",
@@ -45,7 +45,7 @@ registerTool({
         validateRequired(args, ["planet_id", "datetime"]);
         const body = {
             planet_id: args.planet_id,
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
         };
         if (args.latitude != null)
             body.latitude = args.latitude;
@@ -93,7 +93,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         };

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 function buildSubject(name, datetime, lat, lon) {
     return {
         name,
@@ -78,7 +78,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         return await getActiveClient().post("/ephemeris/dignities", {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
         });
     },
 });
@@ -121,14 +121,14 @@ registerTool({
         // If a specific planet is requested, delegate directly.
         if (args.planet_id != null) {
             return await client.post("/ephemeris/retrograde-status", {
-                date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+                date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
                 planet_id: args.planet_id,
             });
         }
         // 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", {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             planet_id: pid,
         }).catch(() => null)));
         // Merge into a keyed object: { planet_name: {...status} }
@@ -169,7 +169,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/midpoints", {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         });
@@ -218,7 +218,7 @@ registerTool({
         // the exact failure this tool exists to avoid — reject it instead.
         validateCoordinates(args, "latitude", "longitude");
         const body = {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
         };
         if (args.latitude != null)
             body.latitude = args.latitude;
@@ -258,7 +258,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/hermetic-lots", {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         });
@@ -286,7 +286,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/angles-points", {
-            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
+            date_time: toDateTimeInputBody("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         });

package/dist/tools/specialized/returns.js

@@ -1,7 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON, OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, toDateTimeInputBody } from "../datetime.js";
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
@@ -71,8 +71,8 @@ registerTool({
         // Default target to current year if not provided
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
-            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
+            birth_datetime: toDateTimeInputBody("birth_datetime", args.birth_datetime, args.timezone),
+            target_datetime: toDateTimeInputBody("target_datetime", targetDt, args.timezone),
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -143,8 +143,8 @@ registerTool({
         assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
-            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
+            birth_datetime: toDateTimeInputBody("birth_datetime", args.birth_datetime, args.timezone),
+            target_datetime: toDateTimeInputBody("target_datetime", targetDt, args.timezone),
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {