@checkstack/backend-api 0.21.3 → 0.21.4

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @checkstack/backend-api
 
+## 0.21.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.
+
 ## 0.21.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",

package/src/schema-utils.test.ts

@@ -42,3 +42,36 @@ describe("toJsonSchema x-* metadata", () => {
     expect(json.properties.secretEnv?.["x-secret-env"]).toBe(true);
   });
 });
+
+describe("toJsonSchema unrepresentable types", () => {
+  // Regression: Zod v4 throws "Date cannot be represented in JSON Schema" for
+  // `z.date()` by default. This converter feeds the OpenAPI generator AND the
+  // AI tool projection, so a single date field (timestamps are everywhere)
+  // would crash the whole AI chat. Dates must serialize as date-time strings.
+  test("represents z.date() as a date-time string instead of throwing", () => {
+    const schema = z.object({
+      createdAt: z.date(),
+      note: z.string(),
+    });
+
+    const json = toJsonSchema(schema) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+
+    expect(json.properties.createdAt?.type).toBe("string");
+    expect(json.properties.createdAt?.format).toBe("date-time");
+    expect(json.properties.note?.type).toBe("string");
+  });
+
+  test("handles a top-level / optional / array date without throwing", () => {
+    expect(() => toJsonSchema(z.date())).not.toThrow();
+    const json = toJsonSchema(
+      z.object({ seen: z.array(z.date()), at: z.date().optional() }),
+    ) as { properties: Record<string, Record<string, unknown>> };
+    expect(
+      (json.properties.seen?.items as Record<string, unknown> | undefined)
+        ?.format,
+    ).toBe("date-time");
+    expect(json.properties.at?.format).toBe("date-time");
+  });
+});

package/src/schema-utils.ts

@@ -101,8 +101,25 @@ function addSchemaMetadata(
  * dropdowns for optionsResolver fields, hidden for auto-populated fields).
  */
 export function toJsonSchema(zodSchema: z.ZodTypeAny): Record<string, unknown> {
-  // Use Zod's native JSON Schema conversion
-  const jsonSchema = zodSchema.toJSONSchema() as Record<string, unknown>;
+  // Use Zod's native JSON Schema conversion.
+  //
+  // Zod v4 throws "Date cannot be represented in JSON Schema" for `z.date()`
+  // by default (`unrepresentable: "throw"`). Many platform contracts carry
+  // date fields (timestamps), and this converter is the substrate for the
+  // OpenAPI generator AND the AI tool projection - so a single date field
+  // would crash the whole AI chat (every turn projects the full tool list)
+  // and break OpenAPI. Dates serialize as ISO strings over the wire, so we
+  // represent them as `{ type: "string", format: "date-time" }` and let any
+  // other unrepresentable type degrade to `{}` (any) rather than throw.
+  const jsonSchema = z.toJSONSchema(zodSchema, {
+    unrepresentable: "any",
+    override: (ctx) => {
+      if (ctx.zodSchema instanceof z.ZodDate) {
+        ctx.jsonSchema.type = "string";
+        ctx.jsonSchema.format = "date-time";
+      }
+    },
+  }) as Record<string, unknown>;
   addSchemaMetadata(zodSchema, jsonSchema);
   return jsonSchema;
 }