@checkstack/ai-backend 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @checkstack/ai-backend
 
+## 0.1.5
+
+### Patch Changes
+
+- 56e7c75: Hide navigation, actions and links that the current user cannot use, so anonymous
+  and read-only users no longer see entries that lead to "Access Denied" or to
+  actions the server would reject.
+
+  - **Sidebar**: a nav entry can now declare a dynamic `nav.isVisible({ accessRules, isAuthenticated })` predicate (in addition to the static `accessRule`). A group whose every entry is filtered out is no longer rendered. The filtering/grouping logic is extracted to a pure, unit-tested helper.
+  - **Infrastructure**: its sidebar entry is shown only when the user can READ at least one contributed tab (queue, cache, …), instead of always (it previously had no static rule because tabs are contributed at runtime).
+  - **Notification Settings**: hidden from anonymous users - notifications are per-user, so an anonymous visitor can't have any.
+  - **Anomaly Mute / Suppress**: the "Mute" / "Mute all" controls (a per-user preference) are hidden from anonymous visitors; the "Suppress" control is gated on `anomalyAccess.feed.manage`. Both were previously always visible.
+  - **Dashboard**: the "Open Catalog" actions (which open the manage-only Catalog config page) are hidden from users without `catalogAccess.system.manage`, and the "View catalog" link is gated on `catalogAccess.system.read`.
+  - **Dashboard status signals**: the per-system status rows contributed by plugins (`SystemSignalsSlot`) now render as a LINK only when the user can open the target, and as plain text otherwise. `SystemSignal` gains an optional `accessRule`; the healthcheck, anomaly, and dependency fillers set it for their gated targets (check-history / assignments / dependency-map). Signals pointing at ungated pages (incident / maintenance / SLO detail) stay links.
+  - **Plugin Manager**: the "Install plugin" button (which opens the install-gated page) is hidden from users with only `plugin` view access.
+  - **Satellites**: the page is entirely manage-gated, but its route/sidebar entry was gated on `read`, so read-only users saw the nav item and hit "Access Denied" on click. The route and nav entry now require `satellite.manage`.
+
+  The `@checkstack/ai-backend` bump is only the regenerated bundled docs index
+  (the frontend routing guide gained the `nav.isVisible` section); no code change.
+
+  **BREAKING (`@checkstack/frontend-api`):** the `AccessApi` interface gains a
+  required `useIsAuthenticated()` method. Custom `AccessApi` implementations must
+  add it (it returns `{ loading, isAuthenticated }`). The built-in auth
+  implementation and the no-auth fallback already do. `NavEntry` also gains an
+  optional `isVisible` predicate (purely additive).
+
+- Updated dependencies [0626782]
+- Updated dependencies [56e7c75]
+  - @checkstack/backend-api@0.21.5
+  - @checkstack/common@0.15.0
+  - @checkstack/ai-common@0.1.3
+  - @checkstack/integration-backend@0.4.5
+  - @checkstack/sdk@0.100.1
+
+## 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.5",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -16,12 +16,12 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@checkstack/ai-common": "0.1.2",
-    "@checkstack/backend-api": "0.21.3",
-    "@checkstack/common": "0.14.1",
+    "@checkstack/ai-common": "0.1.3",
+    "@checkstack/backend-api": "0.21.5",
+    "@checkstack/common": "0.15.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/integration-backend": "0.4.3",
-    "@checkstack/sdk": "0.98.1",
+    "@checkstack/integration-backend": "0.4.5",
+    "@checkstack/sdk": "0.100.1",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",
@@ -31,7 +31,7 @@
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.6.0",
+    "@checkstack/scripts": "0.6.1",
     "@checkstack/tsconfig": "0.0.7",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.20.0",

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.";
 
 /**