@openephemeris/mcp-server 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -7,6 +7,111 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+tool's response shape changes with this fix, hence a minor rather than a patch.
+
+### Fixed
+
+- **`ephemeris_next_lunar_phase` returned zero results for every query.** "When is the
+  next full moon?" answered `result_count: 0` with the note *"No matching phase found in
+  window"* — an empty result that reads like a real one, so the answer came back as
+  "there is no full moon in the next month". Four faults stacked up:
+
+  - the tool sent `start_date`/`end_date`, but the calendar endpoint takes a single
+    `date`, so the search window was silently ignored;
+  - it looked for the phase array at `phases`/`data`/`events`, while the response nests
+    it at `data.events`, so the list was always empty;
+  - it matched phase names as `"full moon"` against the engine's `"full_moon"`, so
+    nothing would have matched even once the list was found;
+  - `last_quarter` had no match at all, because the engine names it `third_quarter`.
+
+  The search now walks the calendar forward one lunation at a time, so `count` above 1
+  works. An empty result is no longer reported as an answer: since every principal phase
+  recurs about every 29.5 days, zero results is a fault and the tool now says so instead
+  of handing back a plausible non-answer.
+
+### Changed
+
+- **`ephemeris_retrograde_status` now leads with the single-planet path.** The
+  description opened on the all-planets sweep and mentioned `planet_id` last, so "is
+  Mercury retrograde?" tended to take the 10-credit route instead of the 1-credit one.
+  `planet_id` now carries the planet-id table and both costs are stated up front.
+- **`ephemeris_next_lunar_phase` no longer claims to return the zodiac sign and degree.**
+  It never did — it returns exact UTC datetimes. It now points at `ephemeris_moon_phase`
+  for the sign, and states that cost scales with `count`.
+
+---
+
 ## [4.1.0] — 2026-07-26
 
 Follow-up to 4.0.0. The new `400` was telling REST callers to do something that, on

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/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),
         });
     },
 });
@@ -88,19 +88,27 @@ registerTool({
 // the documented "all planets" behaviour works correctly.
 registerTool({
     name: "ephemeris_retrograde_status",
-    description: "Get retrograde/direct status and speed for all planets at a given date/time. " +
-        "Returns is_retrograde flag, longitude speed, and station proximity for every planet.\n\n" +
-        "✅  Answers 'is X retrograde?' at ONE instant. For WHEN a planet turns retrograde or " +
-        "direct, or whether it stations anywhere in a date range, use electional_station_tracker.\n\n" +
-        "CREDIT COST: for a single planet — the common case — pass planet_id (0-9, e.g. 2 for " +
-        "Mercury): 1 credit. Omitting planet_id runs the all-planets sweep: 10 credits (the " +
-        "backend bills one credit per body and this fans out to 10).",
+    description: "Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all " +
+        "ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station " +
+        "proximity.\n\n" +
+        "✅  Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; " +
+        "'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns " +
+        "retrograde or direct, or whether it stations anywhere in a date range, use " +
+        "electional_station_tracker.\n\n" +
+        "CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the " +
+        "all-planets sweep and costs 10 credits — the backend bills one credit per body and this " +
+        "fans out to 10. Only omit it when the question really is about every planet.",
     inputSchema: {
         type: "object",
         properties: {
             datetime: { type: "string", description: DATETIME_DESC },
             timezone: TIMEZONE_PROPERTY,
-            planet_id: { type: "integer", description: "Optional single planet ID (0-9). Omit for all planets." },
+            planet_id: {
+                type: "integer",
+                description: "Single planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, " +
+                    "6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto). Pass this whenever the question " +
+                    "names a planet — 1 credit. Omit only to sweep all ten — 10 credits.",
+            },
         },
         required: ["datetime"],
         additionalProperties: false,
@@ -113,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} }
@@ -161,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,
         });
@@ -210,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;
@@ -250,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,
         });
@@ -278,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,
         });