@checkstack/ai-backend 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @checkstack/ai-backend
 
+## 0.1.4
+
+### Patch Changes
+
+- b50916d: Fix "Date cannot be represented in JSON Schema" crashing the AI chat. Zod v4's
+  `toJSONSchema()` throws on `z.date()` (and even `z.coerce.date()`) by default,
+  and the chat hit this in TWO places:
+
+  - **`@checkstack/backend-api`** `toJsonSchema()` (the OpenAPI generator and AI
+    tool-introspection / MCP substrate) called it with no options.
+  - **`@checkstack/ai-backend`** the agent loop hands the Vercel AI SDK the raw
+    Zod tool input, and the SDK runs its OWN `toJSONSchema()` (throwing) to build
+    the model-facing tool schema - so a single date field in any tool input
+    crashed every chat turn (the whole tool list is projected before the model is
+    called).
+
+  Both now render dates as `{ type: "string", format: "date-time" }` (their wire
+  shape) and degrade other unrepresentable types to `{}` instead of throwing.
+
+  For the model boundary, a single `dateSafeModelSchema()` helper hands the SDK a
+  ready-made date-safe schema plus a validator that COERCES the ISO strings the
+  model emits back into real `Date`s before parsing with the original schema
+  (refinements and the downstream RPC client, which expects `Date`s, keep
+  working). A single `toModelSchema()` entry point applies this at EVERY point a
+  schema is handed to the model - chat tool inputs, the headless agent runner's
+  tool inputs (the automation "AI Action"), and `generateObject` structured
+  output - gated so non-date schemas are untouched, so individual tool / agent
+  definitions never special-case dates. Regression tests cover the converter, the
+  AI tool serializer, and the model-schema generation + coercion helper, including
+  the full inbound round-trip with the exact ISO shape a live model emits
+  (`...T22:00:00Z`, no milliseconds).
+
+  **Timezone correctness.** Because the model produces dates as text, the chat now
+  enforces an unambiguous wire contract: a date-time tool argument MUST be RFC 3339
+  with an explicit timezone offset. Zone-less (`2026-07-01T22:00:00`) and date-only
+  (`2026-07-01`) values are rejected with a model-readable error (the model
+  self-repairs), instead of being silently interpreted in the pod's local zone -
+  which would resolve the same string to different instants across pods. To resolve
+  an operator's bare "22:00", the browser's IANA timezone is sent with every chat
+  turn and folded into the system prompt, so each operator's times are interpreted
+  in their own zone by default. When no browser zone is available (a headless
+  automation AI Action), the reference zone falls back to the host/container
+  timezone (`TZ`), not UTC. A format-matrix test covers every common shape a model
+  might emit. The chat UI shows the operator which timezone is in use, and the
+  `TZ` override is documented for operators.
+
+  **Current time in context.** The model has no clock, so the system prompt now
+  includes the current instant (UTC plus the reference-zone wall clock), letting it
+  resolve relative dates like "today at 10:00" without asking. Applied to both the
+  chat and the headless agent runner, computed per turn/run so it is never stale.
+
+  **Less-strict topic classifier.** The chat's off-topic pre-classifier was
+  refusing legitimate requests like "create a maintenance" because maintenances
+  (and several other domains) were not listed. The classifier now enumerates the
+  full domain set and treats any create/list/update/delete action on a platform
+  resource as on-topic by default.
+
+- Updated dependencies [b50916d]
+  - @checkstack/backend-api@0.21.4
+  - @checkstack/integration-backend@0.4.4
+
 ## 0.1.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ai-backend",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -17,11 +17,11 @@
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
     "@checkstack/ai-common": "0.1.2",
-    "@checkstack/backend-api": "0.21.3",
+    "@checkstack/backend-api": "0.21.4",
     "@checkstack/common": "0.14.1",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/integration-backend": "0.4.3",
-    "@checkstack/sdk": "0.98.1",
+    "@checkstack/integration-backend": "0.4.4",
+    "@checkstack/sdk": "0.99.0",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",

package/src/agent-runner.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, mock } from "bun:test";
+import { asSchema } from "ai";
 import { z } from "zod";
 import type { AuthUser, RpcClient } from "@checkstack/backend-api";
 import type { OpenAiCompatibleConnection } from "@checkstack/ai-common";
@@ -108,6 +109,55 @@ describe("createAgentRunner", () => {
     expect(result.toolCalls).toEqual([{ tool: "plugin.read", ok: true }]);
   });
 
+  it("hands the model a date-safe schema for tools with Date inputs (no throw)", async () => {
+    // Regression: the AI Action (headless agent runner) builds its OWN tools.
+    // A `z.date()` input would make the SDK's Zod->JSON-Schema conversion throw
+    // "Date cannot be represented...", crashing the action - the same bug as the
+    // chat. The runner must gate date inputs through dateSafeModelSchema too.
+    const registry = createAiToolRegistry();
+    registry.register({
+      name: "plugin.history",
+      description: "history",
+      effect: "read",
+      input: z.object({ since: z.date() }),
+      requiredAccessRules: [],
+      execute: async () => ({ ok: true }),
+    } as RegisteredAiTool);
+    const resolver = createAiToolResolver({ registry });
+
+    let offeredSchema: unknown;
+    const generateText = mock(
+      async (args: {
+        tools?: Record<string, { inputSchema: unknown }>;
+      }) => {
+        const t = (args.tools ?? {})["plugin.history"];
+        // Exactly what the SDK does internally to build the model request; this
+        // threw before the fix.
+        offeredSchema = await asSchema(t.inputSchema as never).jsonSchema;
+        return { text: "ok", usage: {} };
+      },
+    );
+
+    const runner = createAgentRunner({
+      resolver,
+      resolveConnection: async () => connection,
+      modelFns: { generateText: generateText as never },
+    });
+
+    await runner({
+      principal,
+      rpcClient,
+      connectionId: "conn-1",
+      prompt: "go",
+    });
+
+    const props = (
+      offeredSchema as { properties: Record<string, Record<string, unknown>> }
+    ).properties;
+    expect(props.since?.type).toBe("string");
+    expect(props.since?.format).toBe("date-time");
+  });
+
   it("offers a projected read tool and routes it through the principal's client", async () => {
     const registry = createAiToolRegistry();
     registry.register({

package/src/agent-runner.ts

@@ -30,6 +30,8 @@ import {
   type LanguageModel,
 } from "ai";
 import { z } from "zod";
+import { toModelSchema } from "./chat/model-schema";
+import { buildDateTimeContext } from "./chat/system-prompt";
 import {
   createServiceRef,
   type AuthUser,
@@ -201,7 +203,8 @@ export function createAgentRunner({
 
       sdkTools[t.name] = aiTool({
         description: t.description,
-        inputSchema: t.input as z.ZodType,
+        // Single model-boundary date handling, same as the chat tool path.
+        inputSchema: toModelSchema(t.input as z.ZodType),
         execute: async (input: unknown) => {
           try {
             const result = await invoke(input);
@@ -237,9 +240,13 @@ export function createAgentRunner({
       });
     }
 
+    // Append the date/time context at call time (NOT module load) so the model
+    // gets the CURRENT instant and the host-zone wire contract. Headless: no
+    // operator, so the reference zone is the host/container TZ.
+    const dateContext = buildDateTimeContext({ audience: "headless" });
     const { text } = await gen({
       model: languageModel,
-      system: systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+      system: `${systemPrompt ?? DEFAULT_SYSTEM_PROMPT} ${dateContext}`,
       prompt,
       tools: sdkTools,
       stopWhen: stepCountIs(maxSteps ?? DEFAULT_MAX_STEPS),
@@ -249,7 +256,10 @@ export function createAgentRunner({
     if (outputSchema) {
       const res = await genObj({
         model: languageModel,
-        schema: outputSchema,
+        // Same single model-boundary date handling as the tool path: the
+        // structured-output schema's dates must serialize AND the model's ISO
+        // strings coerce back to Date.
+        schema: toModelSchema(outputSchema),
         system:
           "Produce the structured result from the analysis below. Use only information present in it; do not invent values.",
         prompt: `Task: ${prompt}\n\n--- Analysis ---\n${text}`,

package/src/chat/chat-handler.ts

@@ -10,6 +10,8 @@ const ChatTurnBodySchema = z.object({
   connectionId: z.string(),
   model: z.string().optional(),
   message: z.string().min(1),
+  /** Browser IANA timezone, used to resolve bare times the operator types. */
+  timeZone: z.string().optional(),
 });
 
 /**
@@ -25,6 +27,8 @@ const ChatDecisionBodySchema = z.object({
     token: z.string().min(1),
     kind: z.enum(["apply", "decline"]),
   }),
+  /** Browser IANA timezone, used to resolve bare times the operator types. */
+  timeZone: z.string().optional(),
 });
 
 /** A /chat POST is either a new user turn or a confirm-card decision turn. */
@@ -91,6 +95,7 @@ export function createChatRequestHandler({
           forwardHeaders,
           token: body.decision.token,
           decision: body.decision.kind,
+          timeZone: body.timeZone,
         });
       }
       return await chatService.streamTurn({
@@ -100,6 +105,7 @@ export function createChatRequestHandler({
         model: body.model,
         forwardHeaders,
         userText: body.message,
+        timeZone: body.timeZone,
       });
     } catch (error) {
       return Response.json(

package/src/chat/chat-service.ts

@@ -41,6 +41,7 @@ import {
   type AgentToolCallbacks,
 } from "./sdk-tools";
 import type { ChatReadInvoker } from "./read-invoker";
+import { buildChatSystemPrompt } from "./system-prompt";
 import { createUserScopedRpcClient } from "../user-rpc-client";
 
 type AiDatabase = SafeDatabase<typeof schema>;
@@ -200,6 +201,8 @@ export interface ChatTurnInput {
   forwardHeaders: Record<string, string>;
   /** The user's new message text. */
   userText: string;
+  /** The operator's IANA timezone (browser-detected) for resolving bare times. */
+  timeZone?: string;
 }
 
 /**
@@ -220,25 +223,10 @@ export interface ChatDecisionInput {
   token: string;
   /** Whether the operator applied or declined the card. */
   decision: DecisionKind;
+  /** The operator's IANA timezone (browser-detected) for resolving bare times. */
+  timeZone?: string;
 }
 
-const SYSTEM_PROMPT =
-  "You are Checkstack's built-in assistant. You ONLY help operators run " +
-  "Checkstack: incidents, health checks, anomalies, automations, and the " +
-  "monitoring and operations of THIS platform. Use the provided tools to read " +
-  "live data. For any change to the platform, call the appropriate tool: " +
-  "depending on the conversation's permission mode it either returns a " +
-  "confirmation card the operator must approve, or applies immediately and " +
-  "returns the applied result. Never claim a change took effect until the tool " +
-  "result confirms it (an applied result, or the operator approving the card). " +
-  "Call each change tool ONCE per request: a confirm-card result means the " +
-  "proposal succeeded and is awaiting the operator - do NOT call the tool again " +
-  "to retry; just tell the operator you are waiting for their decision. " +
-  "Politely DECLINE anything unrelated to operating Checkstack " +
-  "(general coding help, writing, or general knowledge) with a one-line " +
-  "redirect back to Checkstack monitoring and operations. Be concise and " +
-  "engineering-focused.";
-
 /** Max agent steps (tool-call round trips) per turn. */
 const MAX_STEPS = 8;
 
@@ -532,6 +520,7 @@ export function createChatService({
     languageModel,
     recordUsage,
     modelMessages,
+    timeZone,
   }: {
     principal: AuthUser;
     conversation: { permissionMode: AiPermissionMode };
@@ -541,6 +530,8 @@ export function createChatService({
     languageModel: ReturnType<typeof buildLanguageModel>;
     recordUsage: (usage: LanguageModelUsage) => Promise<void>;
     modelMessages: ModelMessage[];
+    /** The operator's IANA timezone (from the browser), folded into the prompt. */
+    timeZone?: string;
   }): Response => {
     // Build the SDK tools from the resolver-allowed set only. The model is never
     // offered a tool the principal cannot use. Tool callbacks (budget + audit +
@@ -568,7 +559,7 @@ export function createChatService({
 
     const result = streamText({
       model: languageModel,
-      system: SYSTEM_PROMPT,
+      system: buildChatSystemPrompt({ timeZone }),
       // Defensively normalize: drop empty-content rows and merge consecutive
       // same-role messages so a failed prior turn (which persists no assistant
       // reply, leaving consecutive `user` rows) cannot poison the history into a
@@ -680,6 +671,7 @@ export function createChatService({
         model,
         forwardHeaders,
         userText,
+        timeZone,
       } = input;
 
       // Ownership: the conversation MUST belong to the principal.
@@ -810,6 +802,7 @@ export function createChatService({
         languageModel,
         recordUsage,
         modelMessages,
+        timeZone,
       });
     },
 
@@ -831,6 +824,7 @@ export function createChatService({
         forwardHeaders,
         token,
         decision,
+        timeZone,
       } = input;
 
       const conversation = await loadOwnedConversation({
@@ -915,6 +909,7 @@ export function createChatService({
         languageModel,
         recordUsage,
         modelMessages,
+        timeZone,
       });
     },
   };

package/src/chat/classifier.logic.test.ts

@@ -48,6 +48,17 @@ describe("buildClassifierPrompt", () => {
     expect(system).toMatch(/clearly unrelated|CLEARLY unrelated/i);
   });
 
+  test("system prompt names maintenances and a CRUD-action allowance as ON_TOPIC", () => {
+    // Regression for the real bug: "Create a maintenance" was refused because
+    // maintenances were not listed and there was no generic action allowance.
+    const { system } = buildClassifierPrompt({
+      userText: "Create a maintenance",
+    });
+    expect(system.toLowerCase()).toContain("maintenance");
+    // Any create/list/update/delete request must be ON_TOPIC by default.
+    expect(system).toMatch(/create[^.]*list[^.]*update[^.]*delete/i);
+  });
+
   test("system prompt retains the 'when in doubt' ON_TOPIC default", () => {
     const { system } = buildClassifierPrompt({ userText: "???" });
     expect(system).toMatch(/when in doubt.*on_topic/i);

package/src/chat/classifier.logic.ts

@@ -19,18 +19,25 @@ export type ClassifierVerdict = "ON_TOPIC" | "OFF_TOPIC";
  * against any decoration regardless.
  */
 const CLASSIFIER_SYSTEM_PROMPT =
-  "You are a topical classifier for Checkstack, an incident, health-check, " +
-  "anomaly, automation, and monitoring/operations platform. Decide whether the " +
+  "You are a topical classifier for Checkstack, an operations platform covering " +
+  "incidents, health checks, anomalies, automations, maintenances/maintenance " +
+  "windows, dependencies, systems and services, notifications, SLOs, " +
+  "integrations, on-call, and general monitoring/operations. Decide whether the " +
   "user's message is ON_TOPIC or OFF_TOPIC. " +
-  "ON_TOPIC includes: operating or reasoning about Checkstack (incidents, " +
-  "health checks, anomalies, automations, monitoring, on-call, the platform's " +
-  "data and configuration); meta/capability questions about the assistant itself " +
-  "(\"what can you do\", \"who are you\", \"help\", \"what features do you have\"); " +
-  "greetings and conversational openers (\"hi\", \"hello\", \"hey\"); " +
+  "ON_TOPIC includes: operating or reasoning about Checkstack or any of its " +
+  "resources and configuration; meta/capability questions about the assistant " +
+  "itself (\"what can you do\", \"who are you\", \"help\", \"what features do you " +
+  "have\"); greetings and conversational openers (\"hi\", \"hello\", \"hey\"); " +
   "how-to or conceptual questions about using Checkstack features or workflows " +
   "(\"how do health checks work\", \"how do I create an automation\"). " +
-  "OFF_TOPIC means CLEARLY unrelated requests: general coding help unrelated to " +
-  "Checkstack, creative writing, and general trivia or knowledge questions. " +
+  "IMPORTANT: any request to create, add, list, show, view, find, update, edit, " +
+  "schedule, start, stop, resolve, acknowledge, or delete something is ON_TOPIC " +
+  "by default - it is almost certainly an action on a platform resource (e.g. " +
+  "\"create a maintenance\", \"list incidents\", \"schedule downtime\"), EVEN IF " +
+  "the resource type is not named in the list above. " +
+  "OFF_TOPIC means ONLY requests that are CLEARLY unrelated to operating this " +
+  "platform: general-purpose coding help, creative writing, math homework, and " +
+  "general trivia or knowledge questions. " +
   "When in doubt, reply ON_TOPIC. Reply with the token only.";
 
 /**

package/src/chat/model-schema.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, test } from "bun:test";
+import { tool as aiTool, asSchema } from "ai";
+import { z } from "zod";
+import {
+  dateSafeModelSchema,
+  coerceDateValues,
+  collectDateOffsetIssues,
+  schemaContainsDate,
+  toModelSchema,
+} from "./model-schema";
+
+describe("schemaContainsDate", () => {
+  test("detects dates in object / array / optional / coerce positions", () => {
+    expect(schemaContainsDate(z.object({ at: z.date() }))).toBe(true);
+    expect(schemaContainsDate(z.object({ at: z.date().optional() }))).toBe(true);
+    expect(schemaContainsDate(z.object({ at: z.coerce.date() }))).toBe(true);
+    expect(schemaContainsDate(z.object({ seen: z.array(z.date()) }))).toBe(true);
+    expect(
+      schemaContainsDate(z.object({ d: z.date() }).refine(() => true)),
+    ).toBe(true);
+  });
+
+  test("returns false when there is no date", () => {
+    expect(
+      schemaContainsDate(z.object({ name: z.string(), n: z.number() })),
+    ).toBe(false);
+  });
+});
+
+describe("coerceDateValues", () => {
+  test("coerces ISO strings to Date only at date positions", () => {
+    const schema = z.object({ at: z.date(), name: z.string() });
+    const out = coerceDateValues(
+      { at: "2026-01-02T03:04:05.000Z", name: "2026-01-02T03:04:05.000Z" },
+      schema,
+    ) as { at: unknown; name: unknown };
+    expect(out.at).toBeInstanceOf(Date);
+    // A string field that merely looks like a date is left a string.
+    expect(out.name).toBe("2026-01-02T03:04:05.000Z");
+  });
+
+  test("recurses arrays and optionals", () => {
+    const schema = z.object({
+      seen: z.array(z.date()),
+      at: z.date().optional(),
+    });
+    const out = coerceDateValues(
+      { seen: ["2026-01-02T00:00:00.000Z"], at: undefined },
+      schema,
+    ) as { seen: unknown[]; at: unknown };
+    expect(out.seen[0]).toBeInstanceOf(Date);
+    expect(out.at).toBeUndefined();
+  });
+});
+
+describe("dateSafeModelSchema", () => {
+  // The core regression: the AI SDK would throw "Date cannot be represented in
+  // JSON Schema" building the model-facing schema for these inputs.
+  test("produces a date-time string schema without throwing", async () => {
+    const schema = dateSafeModelSchema(
+      z.object({ id: z.string(), createdAt: z.date() }),
+    );
+    const js = (await schema.jsonSchema) as {
+      properties: Record<string, Record<string, unknown>>;
+      additionalProperties?: unknown;
+    };
+    expect(js.properties.createdAt?.type).toBe("string");
+    expect(js.properties.createdAt?.format).toBe("date-time");
+    // The model is told the offset contract right on the field.
+    expect(String(js.properties.createdAt?.description)).toContain(
+      "explicit timezone offset",
+    );
+    // Strict-provider friendly (matches the SDK's own zod adapter).
+    expect(js.additionalProperties).toBe(false);
+  });
+
+  test("validator coerces the model's ISO string into a Date", async () => {
+    const schema = dateSafeModelSchema(z.object({ at: z.date() }));
+    const result = await schema.validate?.({ at: "2026-01-02T03:04:05.000Z" });
+    expect(result?.success).toBe(true);
+    if (result?.success) {
+      expect((result.value as { at: Date }).at).toBeInstanceOf(Date);
+    }
+  });
+
+  test("validator preserves the original schema's refinement", async () => {
+    const schema = dateSafeModelSchema(
+      z
+        .object({ startAt: z.coerce.date(), endAt: z.coerce.date() })
+        .refine((v) => v.endAt > v.startAt, { message: "endAt after startAt" }),
+    );
+    const bad = await schema.validate?.({
+      startAt: "2026-01-02T00:00:00.000Z",
+      endAt: "2026-01-01T00:00:00.000Z",
+    });
+    expect(bad?.success).toBe(false);
+  });
+});
+
+describe("date format matrix (the wire contract)", () => {
+  // Run every case through BOTH a raw `z.date()` (which exercises OUR coercion)
+  // and a `z.coerce.date()` (whose own `new Date()` coercion is lenient and
+  // MUST still be gated). A model can emit any of these shapes; the contract is:
+  // only an RFC 3339 date-time WITH an explicit offset is accepted, and it maps
+  // to the one unambiguous instant. Zone-less, date-only, numeric and garbage
+  // values are rejected so the model self-repairs instead of us guessing a zone.
+  const schemas = {
+    "z.date()": z.object({ at: z.date() }),
+    "z.coerce.date()": z.object({ at: z.coerce.date() }),
+  };
+
+  // Offset-bearing inputs and the single UTC instant they must resolve to.
+  // Deterministic regardless of the machine's local timezone (each carries Z or
+  // an explicit offset), so the exact ISO is safe to assert in CI.
+  const accepted: Array<[input: string, iso: string]> = [
+    ["2026-07-01T22:00:00.000Z", "2026-07-01T22:00:00.000Z"],
+    ["2026-07-01T22:00:00Z", "2026-07-01T22:00:00.000Z"],
+    ["2026-07-01T22:00Z", "2026-07-01T22:00:00.000Z"], // no seconds
+    ["2026-07-01T22:00:00.123Z", "2026-07-01T22:00:00.123Z"], // sub-seconds
+    ["2026-07-01T22:00:00+00:00", "2026-07-01T22:00:00.000Z"],
+    ["2026-07-01T22:00:00+02:00", "2026-07-01T20:00:00.000Z"],
+    ["2026-07-01T22:00:00-05:00", "2026-07-02T03:00:00.000Z"],
+    ["2026-07-01T22:00:00+0200", "2026-07-01T20:00:00.000Z"], // offset w/o colon
+  ];
+
+  // Rejected: zone-less (would be interpreted server-local), date-only (drops
+  // the time), non-ISO human forms, and outright garbage.
+  const rejected = [
+    "2026-07-01T22:00:00", // no offset
+    "2026-07-01 22:00:00", // space + no offset
+    "2026-07-01", // date only
+    "2026/07/01", // slashes
+    "July 1, 2026", // human
+    "Wed, 01 Jul 2026 22:00:00 GMT", // RFC 1123 (no offset designator we accept)
+    "2026-13-01T00:00:00Z", // matches the offset shape but is not a real date
+    "not a date",
+    "",
+    "tomorrow",
+  ];
+
+  for (const [label, schema] of Object.entries(schemas)) {
+    for (const [input, iso] of accepted) {
+      test(`${label}: accepts "${input}" -> ${iso}`, async () => {
+        const result = await dateSafeModelSchema(schema).validate?.({
+          at: input,
+        });
+        expect(result?.success).toBe(true);
+        if (result?.success) {
+          const at = (result.value as { at: Date }).at;
+          expect(at).toBeInstanceOf(Date);
+          expect(at.toISOString()).toBe(iso);
+        }
+      });
+    }
+
+    for (const input of rejected) {
+      test(`${label}: rejects ${JSON.stringify(input)}`, async () => {
+        const result = await dateSafeModelSchema(schema).validate?.({
+          at: input,
+        });
+        expect(result?.success).toBe(false);
+      });
+    }
+
+    test(`${label}: rejects a bare epoch number`, async () => {
+      const result = await dateSafeModelSchema(schema).validate?.({
+        at: 1782000000000,
+      });
+      expect(result?.success).toBe(false);
+    });
+  }
+
+  test("rejection message names the field and the offset requirement", () => {
+    const issues = collectDateOffsetIssues(
+      { startAt: "2026-07-01T22:00:00" },
+      z.object({ startAt: z.date() }),
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toContain("startAt");
+    expect(issues[0]).toContain("explicit timezone offset");
+  });
+
+  test("a regex-shaped but impossible date reports an invalid-date message", () => {
+    const issues = collectDateOffsetIssues(
+      { at: "2026-13-01T00:00:00Z" },
+      z.object({ at: z.date() }),
+    );
+    expect(issues[0]).toContain("not a valid calendar date-time");
+  });
+
+  test("nested arrays and optionals are gated too", () => {
+    const schema = z.object({
+      windows: z.array(z.object({ at: z.date() })),
+      maybe: z.date().optional(),
+    });
+    const issues = collectDateOffsetIssues(
+      { windows: [{ at: "2026-07-01" }], maybe: "2026-07-01T00:00:00" },
+      schema,
+    );
+    expect(issues).toHaveLength(2);
+    expect(issues.some((m) => m.includes("windows[0].at"))).toBe(true);
+    expect(issues.some((m) => m.includes("maybe"))).toBe(true);
+  });
+
+  test("an absent optional date is not flagged", () => {
+    expect(
+      collectDateOffsetIssues({}, z.object({ at: z.date().optional() })),
+    ).toEqual([]);
+  });
+});
+
+describe("toModelSchema (the single boundary entry)", () => {
+  test("returns the raw Zod schema when there is no date", () => {
+    const schema = z.object({ q: z.string() });
+    expect(toModelSchema(schema)).toBe(schema);
+  });
+
+  test("returns a date-safe Schema when a date is present", () => {
+    const schema = z.object({ at: z.date() });
+    expect(toModelSchema(schema)).not.toBe(schema);
+  });
+
+  // The full inbound round-trip exactly as the AI SDK runtime drives it: the
+  // model emits an object with an ISO date STRING, the tool's inputSchema
+  // validates it, and `execute` is called with the validated value. We assert
+  // `execute` receives a real `Date` - i.e. the model can create date-bearing
+  // objects and they are parsed back to Date in our backend. Uses a raw
+  // `z.date()` (not coerce.date) so this proves OUR coercion, not Zod's.
+  //
+  // The input string is the EXACT shape a real model emits, captured from a
+  // live deepseek-v4-flash maintenance-window creation: ISO 8601 with a `Z`
+  // offset and NO milliseconds (`...T22:00:00Z`, not `...T22:00:00.000Z`). The
+  // less-precise form is what providers actually return, so the test asserts
+  // `new Date()` normalizes it to a real Date with the milliseconds filled in.
+  test("model's ISO date object (no millis) is parsed to a real Date for execute", async () => {
+    const schema = z.object({ startAt: z.date(), label: z.string() });
+    let received: { startAt: unknown; label: unknown } | undefined;
+    const t = aiTool({
+      inputSchema: toModelSchema(schema) as never,
+      execute: async (input: unknown) => {
+        received = input as { startAt: unknown; label: unknown };
+        return { ok: true };
+      },
+    });
+
+    const validated = await asSchema(t.inputSchema).validate?.({
+      startAt: "2026-07-01T22:00:00Z",
+      label: "window",
+    });
+    expect(validated?.success).toBe(true);
+    if (validated?.success) {
+      await t.execute?.(validated.value, {
+        toolCallId: "call-1",
+        messages: [],
+      });
+    }
+
+    expect(received?.startAt).toBeInstanceOf(Date);
+    expect((received?.startAt as Date).toISOString()).toBe(
+      "2026-07-01T22:00:00.000Z",
+    );
+    expect(received?.label).toBe("window");
+  });
+});