@cursor/july 0.1.28 → 0.1.29

package/src/internal/host-platforms.ts

@@ -13,7 +13,11 @@ import {
   tryResolveGhAuthToken,
 } from "../channels/github/auth.js";
 import type { GitHubChannelCredentials } from "../channels/github/types.js";
-import { tryResolveBotToken } from "../channels/slack/credentials.js";
+import {
+  slackEnvKeys,
+  tryResolveBotToken,
+} from "../channels/slack/credentials.js";
+import type { SlackCredentials } from "../channels/slack/types.js";
 import type { HostGitHubClient, HostSlackClient } from "../types.js";
 
 export interface HostPlatforms {
@@ -35,6 +39,37 @@ export type HostGitHubAuthSource =
 
 export interface HostPlatformsOptions {
   githubCredentials?: GitHubChannelCredentials;
+  /**
+   * Per-agent Slack credentials (usually from a channel `envPrefix`).
+   * When omitted, `getClient()` falls back to `SLACK_BOT_TOKEN`.
+   */
+  slackCredentials?: SlackCredentials;
+  /** Env prefix used only to name the missing-token error. */
+  slackEnvPrefix?: string;
+}
+
+/** Bot-token Slack client. Pass channel credentials so `envPrefix` is honored. */
+export function createHostSlackClient(
+  options: { credentials?: SlackCredentials; envPrefix?: string } = {}
+): HostSlackClient {
+  let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
+  return {
+    getClient: async () => {
+      slackPromise ??= (async () => {
+        const token = await tryResolveBotToken(options.credentials);
+        if (token === undefined) {
+          const botKey = slackEnvKeys(options.envPrefix).bot;
+          const hint =
+            options.envPrefix === undefined || options.envPrefix.trim() === ""
+              ? `${botKey} or a channel envPrefix`
+              : botKey;
+          throw new Error(`No Slack bot token available (set ${hint}).`);
+        }
+        return new WebClient(token);
+      })();
+      return slackPromise;
+    },
+  };
 }
 
 /**
@@ -46,7 +81,6 @@ export function createHostPlatforms(
   options: HostPlatformsOptions = {}
 ): HostPlatforms {
   let octokitPromise: ReturnType<HostGitHubClient["getOctokit"]> | undefined;
-  let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
 
   return {
     github: {
@@ -57,22 +91,10 @@ export function createHostPlatforms(
         return octokitPromise;
       },
     },
-    slack: {
-      getClient: async () => {
-        if (slackPromise === undefined) {
-          slackPromise = (async () => {
-            const token = await tryResolveBotToken(undefined);
-            if (token === undefined) {
-              throw new Error(
-                "No Slack bot token available (set SLACK_BOT_TOKEN or a channel envPrefix)."
-              );
-            }
-            return new WebClient(token);
-          })();
-        }
-        return slackPromise;
-      },
-    },
+    slack: createHostSlackClient({
+      credentials: options.slackCredentials,
+      envPrefix: options.slackEnvPrefix,
+    }),
   };
 }
 

package/src/internal/http-channel.ts

@@ -301,7 +301,9 @@ export function buildHttpChannelRoutes(args: {
       }
       const url = new URL(request.url);
       const asJson = url.searchParams.get("format") === "json";
-      const snapshot = await engine.listEvents(sessionId, 0);
+      const snapshot = await engine.listEvents(sessionId, 0, {
+        backfillCloudCost: true,
+      });
       if (asJson) {
         return jsonResponse({
           sessionId,

package/src/internal/local-control-plane.ts

@@ -0,0 +1,188 @@
+/**
+ * In-process control plane started with local `serve`. Owns schedule clocks
+ * and reminder documents + clocks, then fires into the kit the same way the
+ * Cursor backend does over HTTP when `--no-control-plane` is set.
+ */
+
+import { dirname, join } from "node:path";
+import { type CronExpression, parseCron } from "./cron.js";
+import type { PlatformTimers } from "./platform-timers.js";
+import { MAX_TIMER_MS } from "./reminder-schedule.js";
+import { type ReminderRecord, ReminderStore } from "./reminder-store.js";
+
+export interface LocalControlPlane extends PlatformTimers {
+  /** Arm persisted reminder clocks after the kit fire callback is live. */
+  startClocks(): void;
+  stop(): void;
+}
+
+export async function createLocalControlPlane(opts: {
+  fireSchedule: (name: string) => Promise<unknown>;
+  fireReminder: (id: string, fireCount: number) => Promise<unknown>;
+  /**
+   * Persist reminder documents under `<stateDir>/reminders`. Local serve
+   * passes `<stateRoot>/control-plane`; records previously stored at
+   * `<stateRoot>/reminders` are migrated in on first boot.
+   */
+  stateDir?: string;
+  /** Arm deadline timers. Off in `--dev`. Defaults to true. */
+  armReminderClocks?: boolean;
+  logger?: (line: string) => void;
+}): Promise<LocalControlPlane> {
+  const logger = opts.logger ?? (() => {});
+  const armReminderClocks = opts.armReminderClocks !== false;
+  const store =
+    opts.stateDir === undefined
+      ? undefined
+      : new ReminderStore(join(opts.stateDir, "reminders"));
+  const schedules = new Map<string, CronExpression>();
+  const reminderTimers = new Map<string, NodeJS.Timeout>();
+  const reminders = new Map<string, ReminderRecord>();
+  let scheduleTimer: NodeJS.Timeout | undefined;
+  let lastFiredMinute = -1;
+
+  if (store !== undefined) {
+    for (const record of await store.list()) {
+      reminders.set(record.id, record);
+    }
+    if (opts.stateDir !== undefined) {
+      const legacyStore = new ReminderStore(
+        join(dirname(opts.stateDir), "reminders")
+      );
+      for (const record of await legacyStore.list()) {
+        if (reminders.has(record.id)) {
+          await legacyStore.delete(record.id);
+          continue;
+        }
+        reminders.set(record.id, record);
+        await store.save(record);
+        await legacyStore.delete(record.id);
+      }
+    }
+  }
+
+  function armScheduleTicker(): void {
+    if (scheduleTimer !== undefined || schedules.size === 0) {
+      return;
+    }
+    const now = Date.now();
+    const nextMinute = (Math.floor(now / 60_000) + 1) * 60_000;
+    scheduleTimer = setTimeout(() => tickSchedules(), nextMinute - now + 250);
+    scheduleTimer.unref?.();
+  }
+
+  function stopScheduleTicker(): void {
+    if (scheduleTimer === undefined) {
+      return;
+    }
+    clearTimeout(scheduleTimer);
+    scheduleTimer = undefined;
+  }
+
+  function tickSchedules(): void {
+    scheduleTimer = undefined;
+    const now = new Date();
+    const minute = Math.floor(now.getTime() / 60_000);
+    if (minute !== lastFiredMinute) {
+      lastFiredMinute = minute;
+      for (const [name, cron] of schedules) {
+        if (!cron.matches(now)) {
+          continue;
+        }
+        void opts.fireSchedule(name).catch((error) => {
+          logger(
+            `[agentkit] schedule "${name}" dispatch failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          );
+        });
+      }
+    }
+    armScheduleTicker();
+  }
+
+  function clearReminderTimer(id: string): void {
+    const timer = reminderTimers.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      reminderTimers.delete(id);
+    }
+  }
+
+  function armReminder(record: ReminderRecord): void {
+    clearReminderTimer(record.id);
+    const delay = Math.min(
+      MAX_TIMER_MS,
+      Math.max(0, record.nextFireAtMs - Date.now())
+    );
+    const timer = setTimeout(() => {
+      reminderTimers.delete(record.id);
+      const current = reminders.get(record.id);
+      if (current === undefined || current.status !== "armed") {
+        return;
+      }
+      if (current.nextFireAtMs > Date.now() + 50) {
+        armReminder(current);
+        return;
+      }
+      void opts.fireReminder(current.id, current.fireCount).catch((error) => {
+        logger(
+          `[agentkit] reminder "${current.id}" dispatch failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      });
+    }, delay);
+    timer.unref?.();
+    reminderTimers.set(record.id, timer);
+  }
+
+  return {
+    async upsertSchedule(input) {
+      schedules.set(input.name, parseCron(input.cron));
+      armScheduleTicker();
+    },
+    async deleteSchedule(name) {
+      schedules.delete(name);
+      if (schedules.size === 0) {
+        stopScheduleTicker();
+      }
+    },
+    async putReminder(record) {
+      reminders.set(record.id, record);
+      await store?.save(record);
+      if (armReminderClocks && record.status === "armed") {
+        armReminder(record);
+        return;
+      }
+      clearReminderTimer(record.id);
+    },
+    async getReminder(id) {
+      return reminders.get(id);
+    },
+    async listReminders() {
+      return [...reminders.values()];
+    },
+    async deleteReminder(id) {
+      clearReminderTimer(id);
+      reminders.delete(id);
+      await store?.delete(id);
+    },
+    startClocks() {
+      if (!armReminderClocks) {
+        return;
+      }
+      for (const record of reminders.values()) {
+        if (record.status === "armed") {
+          armReminder(record);
+        }
+      }
+    },
+    stop() {
+      stopScheduleTicker();
+      for (const id of [...reminderTimers.keys()]) {
+        clearReminderTimer(id);
+      }
+    },
+  };
+}

package/src/internal/platform-schedule-sync.ts

@@ -0,0 +1,81 @@
+/**
+ * Keep control-plane Temporal calendars aligned with authored
+ * `agent/schedules/*`. Upsert current names and delete ones that disappeared
+ * since the last successful sync (persisted under the engine state root).
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import type { PlatformTimers } from "./platform-timers.js";
+
+export const PLATFORM_SCHEDULE_CATALOG_FILENAME =
+  "platform-schedule-names.json";
+
+export async function syncHostedPlatformSchedules(args: {
+  timers: PlatformTimers;
+  schedules: ReadonlyArray<{ name: string; cron: string }>;
+  catalogPath: string;
+  logger: (line: string) => void;
+}): Promise<void> {
+  const previous = await readScheduleCatalog(args.catalogPath);
+  const currentNames = args.schedules.map((schedule) => schedule.name);
+  const currentSet = new Set(currentNames);
+
+  const failedDeletes: string[] = [];
+  for (const name of previous) {
+    if (currentSet.has(name)) {
+      continue;
+    }
+    try {
+      await args.timers.deleteSchedule(name);
+    } catch (error) {
+      failedDeletes.push(name);
+      args.logger(
+        `[agentkit] platform timer delete failed for schedule "${name}": ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  for (const schedule of args.schedules) {
+    try {
+      await args.timers.upsertSchedule({
+        name: schedule.name,
+        cron: schedule.cron,
+      });
+    } catch (error) {
+      args.logger(
+        `[agentkit] platform timer upsert failed for schedule "${schedule.name}": ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  // Keep failed removals in the catalog so the next boot retries them.
+  await writeScheduleCatalog(args.catalogPath, [
+    ...new Set([...currentNames, ...failedDeletes]),
+  ]);
+}
+
+async function readScheduleCatalog(catalogPath: string): Promise<string[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(catalogPath, "utf8"));
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter((entry): entry is string => typeof entry === "string");
+  } catch {
+    return [];
+  }
+}
+
+async function writeScheduleCatalog(
+  catalogPath: string,
+  names: readonly string[]
+): Promise<void> {
+  await mkdir(dirname(catalogPath), { recursive: true });
+  await writeFile(catalogPath, `${JSON.stringify(names)}\n`, "utf8");
+}

package/src/internal/platform-timers.ts

@@ -0,0 +1,173 @@
+/**
+ * Timed-work client used by the kit. Local serve implements this in-process
+ * (`createLocalControlPlane`). Cursor hosting (`--no-control-plane`) uses
+ * the HTTP client below against the Cursor backend. Authors never see this
+ * surface.
+ *
+ * The control plane owns reminder *documents* and clocks. The kit only
+ * executes fires.
+ */
+
+import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
+
+const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+
+export interface PlatformTimers {
+  upsertSchedule(input: { name: string; cron: string }): Promise<void>;
+  deleteSchedule(name: string): Promise<void>;
+  putReminder(record: ReminderRecord): Promise<void>;
+  getReminder(id: string): Promise<ReminderRecord | undefined>;
+  listReminders(): Promise<ReminderRecord[]>;
+  deleteReminder(id: string): Promise<void>;
+}
+
+export interface CursorHostedPlatformTimersOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+}
+
+function resolveApiKey(options: CursorHostedPlatformTimersOptions): string {
+  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  if (key === undefined || key === "") {
+    throw new Error(
+      "platform timers require CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
+    );
+  }
+  return key;
+}
+
+function resolveBaseUrl(options: CursorHostedPlatformTimersOptions): string {
+  const raw = (
+    options.baseUrl ??
+    process.env.CURSOR_API_BASE_URL ??
+    DEFAULT_CURSOR_EXTERNAL_API_URL
+  ).trim();
+  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+
+async function timedWorkFetch(
+  options: CursorHostedPlatformTimersOptions,
+  method: "GET" | "PUT" | "DELETE",
+  path: string,
+  body?: unknown
+): Promise<Response> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("platform timers require fetch");
+  }
+  return fetchImpl(`${resolveBaseUrl(options)}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${resolveApiKey(options)}`,
+      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+}
+
+async function timedWorkRpc(
+  options: CursorHostedPlatformTimersOptions,
+  method: "PUT" | "DELETE",
+  path: string,
+  body?: unknown
+): Promise<void> {
+  const response = await timedWorkFetch(options, method, path, body);
+  if (response.ok) {
+    return;
+  }
+  const text = await response.text();
+  let detail = `HTTP ${response.status}`;
+  try {
+    const parsed: unknown = text.length === 0 ? {} : JSON.parse(text);
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "error" in parsed &&
+      typeof (parsed as { error: unknown }).error === "string"
+    ) {
+      detail = (parsed as { error: string }).error;
+    }
+  } catch {
+    // Keep the status-only detail.
+  }
+  throw new Error(`platform timers ${method} ${path}: ${detail}`);
+}
+
+export function createCursorHostedPlatformTimers(
+  options: CursorHostedPlatformTimersOptions = {}
+): PlatformTimers {
+  return {
+    async upsertSchedule(input) {
+      await timedWorkRpc(
+        options,
+        "PUT",
+        `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(input.name)}`,
+        { cron: input.cron }
+      );
+    },
+    async deleteSchedule(name) {
+      await timedWorkRpc(
+        options,
+        "DELETE",
+        `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(name)}`
+      );
+    },
+    async putReminder(record) {
+      await timedWorkRpc(
+        options,
+        "PUT",
+        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(record.id)}`,
+        record
+      );
+    },
+    async getReminder(id) {
+      const response = await timedWorkFetch(
+        options,
+        "GET",
+        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`
+      );
+      if (response.status === 404) {
+        return undefined;
+      }
+      if (!response.ok) {
+        throw new Error(
+          `platform timers GET /reminders/${id}: HTTP ${response.status}`
+        );
+      }
+      const parsed: unknown = await response.json();
+      return isReminderRecord(parsed) ? parsed : undefined;
+    },
+    async listReminders() {
+      const response = await timedWorkFetch(
+        options,
+        "GET",
+        "/internal/agent-serve/timed-work/reminders"
+      );
+      if (!response.ok) {
+        throw new Error(
+          `platform timers GET /reminders: HTTP ${response.status}`
+        );
+      }
+      const parsed: unknown = await response.json();
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        !("reminders" in parsed) ||
+        !Array.isArray((parsed as { reminders: unknown }).reminders)
+      ) {
+        return [];
+      }
+      return (parsed as { reminders: unknown[] }).reminders.filter(
+        isReminderRecord
+      );
+    },
+    async deleteReminder(id) {
+      await timedWorkRpc(
+        options,
+        "DELETE",
+        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`
+      );
+    },
+  };
+}