@cursor/july 0.1.1

package/src/internal/reminder-schedule.ts

@@ -0,0 +1,106 @@
+/**
+ * Schedule resolution for reminders (`every` / `cron` / `delay` / `at`).
+ */
+
+import type { ReminderCreateInput, ReminderScheduleKind } from "../types.js";
+import { parseCron } from "./cron.js";
+import { parseDuration } from "./duration.js";
+
+export class ReminderValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReminderValidationError";
+  }
+}
+
+/** Node setTimeout overflows past ~2^31-1 ms (~24.8d); chunk long waits. */
+export const MAX_TIMER_MS = 2_147_483_647;
+
+export interface ResolvedSchedule {
+  kind: ReminderScheduleKind;
+  value: string;
+  intervalMs?: number;
+  nextFireAtMs: number;
+}
+
+/** Resolve create-input schedule fields into a concrete next-fire plan. */
+export function resolveSchedule(input: ReminderCreateInput): ResolvedSchedule {
+  const shapes = [
+    input.every !== undefined,
+    input.cron !== undefined,
+    input.delay !== undefined,
+    input.at !== undefined,
+  ].filter(Boolean);
+  if (shapes.length !== 1) {
+    throw new ReminderValidationError(
+      "reminders.create requires exactly one of every, cron, delay, or at"
+    );
+  }
+
+  const now = Date.now();
+  if (input.every !== undefined) {
+    const intervalMs = parseDuration(input.every);
+    if (intervalMs <= 0) {
+      throw new ReminderValidationError(
+        `every must be > 0 (got ${input.every})`
+      );
+    }
+    return {
+      kind: "every",
+      value: String(input.every),
+      intervalMs,
+      nextFireAtMs: now + intervalMs,
+    };
+  }
+  if (input.cron !== undefined) {
+    parseCron(input.cron); // validate
+    return {
+      kind: "cron",
+      value: input.cron,
+      nextFireAtMs: nextCronFireMs(input.cron, now),
+    };
+  }
+  if (input.delay !== undefined) {
+    const delayMs = parseDuration(input.delay);
+    return {
+      kind: "delay",
+      value: String(input.delay),
+      nextFireAtMs: now + delayMs,
+    };
+  }
+  const atMs =
+    typeof input.at === "number"
+      ? input.at
+      : input.at instanceof Date
+        ? input.at.getTime()
+        : Date.parse(String(input.at));
+  if (!Number.isFinite(atMs)) {
+    throw new ReminderValidationError(`Invalid at time: ${String(input.at)}`);
+  }
+  return {
+    kind: "at",
+    value:
+      typeof input.at === "string" ? input.at : new Date(atMs).toISOString(),
+    nextFireAtMs: atMs,
+  };
+}
+
+/** Next UTC fire strictly after `afterMs` for a 5-field cron. */
+export function nextCronFireMs(cronSource: string, afterMs: number): number {
+  try {
+    return parseCron(cronSource).nextFire(new Date(afterMs)).getTime();
+  } catch (error) {
+    throw new ReminderValidationError(
+      error instanceof Error
+        ? error.message
+        : `Could not find next fire for cron "${cronSource}"`
+    );
+  }
+}
+
+/** Default busy policy: recurring may skip; one-shots queue behind the turn. */
+export function defaultBusyPolicy(
+  kind: ReminderScheduleKind
+): "skipIfBusy" | "queueBehindTurn" {
+  return kind === "every" || kind === "cron" ? "skipIfBusy" : "queueBehindTurn";
+}

package/src/internal/reminder-store.ts

@@ -0,0 +1,145 @@
+/**
+ * Durable reminder instance store under `<stateRoot>/reminders/`.
+ *
+ * Handlers (`run` / function `until`) are not serializable — they live only
+ * in the in-memory {@link ReminderRunner} registry. Disk holds schedule,
+ * prompt, target, and status so one-shots / recurring ticks survive restart
+ * for prompt-form reminders.
+ */
+
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  ReminderBusyPolicy,
+  ReminderScheduleKind,
+  ReminderStatus,
+} from "../types.js";
+
+export const REMINDER_SNAPSHOT_VERSION = 1 as const;
+
+export type {
+  ReminderBusyPolicy,
+  ReminderScheduleKind,
+  ReminderStatus,
+} from "../types.js";
+
+/** Serializable reminder record (no function bodies). */
+export interface ReminderRecord {
+  version: typeof REMINDER_SNAPSHOT_VERSION;
+  id: string;
+  purpose: string;
+  /** Channel that owns the target session (e.g. `drive`, `http`). */
+  channelId: string;
+  /** Channel-local continuation key (not the wire `channel:key` token). */
+  continuationToken: string;
+  /** Optional opaque target metadata (e.g. `{ prUrl }`). */
+  target?: Record<string, unknown>;
+  scheduleKind: ReminderScheduleKind;
+  /** Raw schedule value: every/delay string, cron expression, or ISO `at`. */
+  scheduleValue: string;
+  intervalMs?: number;
+  /** Prompt form — mutually exclusive with in-memory `run`. */
+  prompt?: string;
+  /**
+   * True when create() registered a `run` handler. Handlers are not
+   * serializable; after restart, armed records with this flag and no live
+   * handler are disarmed instead of falling back to a generic prompt.
+   */
+  hasRunHandler: boolean;
+  /** True when create() registered a function `until` (in-memory only). */
+  hasUntilFn: boolean;
+  /** Natural-language until (agent-facing); function until is in-memory only. */
+  untilPrompt?: string;
+  busyPolicy: ReminderBusyPolicy;
+  status: ReminderStatus;
+  disarmReason?: string;
+  fireCount: number;
+  nextFireAtMs: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export class ReminderStore {
+  constructor(private readonly rootDir: string) {}
+
+  private filePath(id: string): string {
+    return join(this.rootDir, `${id}.json`);
+  }
+
+  async ensureRoot(): Promise<void> {
+    await mkdir(this.rootDir, { recursive: true });
+  }
+
+  async list(): Promise<ReminderRecord[]> {
+    await this.ensureRoot();
+    let names: string[];
+    try {
+      names = await readdir(this.rootDir);
+    } catch {
+      return [];
+    }
+    const records: ReminderRecord[] = [];
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue;
+      const record = await this.get(name.slice(0, -".json".length));
+      if (record !== undefined) {
+        records.push(record);
+      }
+    }
+    return records;
+  }
+
+  async listArmed(): Promise<ReminderRecord[]> {
+    const all = await this.list();
+    return all.filter((r) => r.status === "armed");
+  }
+
+  async get(id: string): Promise<ReminderRecord | undefined> {
+    try {
+      const raw = await readFile(this.filePath(id), "utf8");
+      const parsed = JSON.parse(raw) as ReminderRecord;
+      if (parsed.version !== REMINDER_SNAPSHOT_VERSION) {
+        return undefined;
+      }
+      if (typeof parsed.id !== "string" || parsed.id !== id) {
+        return undefined;
+      }
+      return parsed;
+    } catch (error) {
+      if (
+        error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        (error as { code?: string }).code === "ENOENT"
+      ) {
+        return undefined;
+      }
+      return undefined;
+    }
+  }
+
+  async save(record: ReminderRecord): Promise<void> {
+    await this.ensureRoot();
+    const path = this.filePath(record.id);
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    const body = `${JSON.stringify(record, null, 2)}\n`;
+    try {
+      await writeFile(tmp, body, "utf8");
+      await rename(tmp, path);
+    } catch (error) {
+      await rm(tmp, { force: true }).catch(() => {});
+      throw error;
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    await rm(this.filePath(id), { force: true });
+  }
+}

package/src/internal/resolved-connections.ts

@@ -0,0 +1,145 @@
+/**
+ * Serve-time connection resolution for one mounted agent: once the host is
+ * listening (port known), symbolic transports — peers and the Cursor
+ * account bridge — resolve to concrete URLs and join the engine's
+ * resolved-connection set. Local turns call both over loopback; cloud
+ * turns use the serve `publicUrl` for peers and the account's native
+ * connectors instead of the bridge.
+ */
+
+import type { AgentProject } from "../types.js";
+import {
+  type CursorAccountConnectionRef,
+  type CursorAccountMcpBridge,
+  resolveCursorAccountConnections,
+} from "./cursor/account-mcp.js";
+import {
+  type PeerConnectionRef,
+  resolvePeerConnections,
+} from "./peer-connections.js";
+import type { EngineResolvedConnection } from "./session-engine.js";
+
+/** Fail fast before listen when static cloud config cannot honor `servers`. */
+export function validateMountConnectionsConfig(args: {
+  slug: string;
+  project: AgentProject;
+  accountRefs?: CursorAccountConnectionRef[];
+  publicUrl?: string;
+}): void {
+  if (args.accountRefs === undefined || args.accountRefs.length === 0) {
+    return;
+  }
+  const agent = args.project.agent;
+  const cloudCapable = agent.runtime === "cloud" || agent.cloud !== undefined;
+  if (!cloudCapable || args.publicUrl !== undefined) {
+    return;
+  }
+  const label = args.slug === "" ? args.project.name : args.slug;
+  const filteredRefs = args.accountRefs.filter(
+    (ref) => ref.servers !== undefined
+  );
+  if (filteredRefs.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[agent-serve] agent "${label}" has Cursor account MCP connections with \`servers\` filters (${filteredRefs
+      .map((ref) => ref.name)
+      .join(
+        ", "
+      )}) but no --public-url; cloud-runtime turns cannot honor those filters without a public bridge URL. Set --public-url or remove the \`servers\` filter.`
+  );
+}
+
+/** Fail closed when a cloud turn cannot honor a `servers` filter. */
+export function assertCloudCanHonorAccountServersFilters(args: {
+  runtime: "local" | "cloud";
+  resolvedConnections: readonly EngineResolvedConnection[];
+}): void {
+  if (args.runtime !== "cloud") {
+    return;
+  }
+  const blocked = args.resolvedConnections.filter(
+    (connection) =>
+      connection.accountServersFilter !== undefined &&
+      connection.cloudUrl === undefined
+  );
+  if (blocked.length === 0) {
+    return;
+  }
+  throw new Error(
+    `[agent-serve] cloud turn cannot honor Cursor account \`servers\` filters (${blocked
+      .map((connection) => connection.name)
+      .join(
+        ", "
+      )}) without --public-url; set --public-url so cloud turns reach the filtered account bridge instead of falling back to native connectors.`
+  );
+}
+
+/** Fail closed when anonymous HTTP admission would expose account connectors. */
+export function assertAccountConnectionsNotAnonymous(args: {
+  allowAnonymous?: boolean;
+  hasAccountConnections: boolean;
+}): void {
+  if (args.allowAnonymous === true && args.hasAccountConnections) {
+    throw new Error(
+      "[agent-serve] --allow-anonymous cannot be used with Cursor account MCP connections (defineConnection({ cursorAccount: true })); use --bearer-token or remove the account MCP connections."
+    );
+  }
+}
+
+export function resolveMountConnections(args: {
+  slug: string;
+  project: AgentProject;
+  serverUrl: string;
+  peerRefs?: PeerConnectionRef[];
+  accountRefs?: CursorAccountConnectionRef[];
+  accountBridge?: CursorAccountMcpBridge;
+  publicUrl?: string;
+  authToken?: string;
+  logger: (line: string) => void;
+}): EngineResolvedConnection[] {
+  const agent = args.project.agent;
+  const cloudCapable = agent.runtime === "cloud" || agent.cloud !== undefined;
+  const label = args.slug === "" ? args.project.name : args.slug;
+  const resolved: EngineResolvedConnection[] = [];
+
+  if (args.peerRefs !== undefined && args.peerRefs.length > 0) {
+    const peers = resolvePeerConnections({
+      refs: args.peerRefs,
+      serverUrl: args.serverUrl,
+      ...(args.publicUrl === undefined ? {} : { publicUrl: args.publicUrl }),
+      ...(args.authToken === undefined ? {} : { authToken: args.authToken }),
+    });
+    resolved.push(...peers);
+    if (cloudCapable && args.publicUrl === undefined) {
+      args.logger(
+        `[agent-serve] warning: agent "${label}" has peer MCP connections (${peers
+          .map((peer) => peer.name)
+          .join(
+            ", "
+          )}) but no --public-url; cloud-runtime turns cannot reach this host's loopback address, so peers are omitted from cloud turns.`
+      );
+    }
+  }
+
+  if (args.accountRefs !== undefined && args.accountBridge !== undefined) {
+    resolved.push(
+      ...resolveCursorAccountConnections({
+        refs: args.accountRefs,
+        serverUrl: args.serverUrl,
+        basePath: args.slug === "" ? "" : `/${args.slug}`,
+        bridgeSecret: args.accountBridge.secret,
+        ...(args.publicUrl === undefined ? {} : { publicUrl: args.publicUrl }),
+      })
+    );
+    // Non-blocking startup DX: connector statuses land in the serve log.
+    args.accountBridge.logPreflight(args.accountRefs);
+    if (cloudCapable && args.publicUrl === undefined) {
+      args.logger(
+        `[agent-serve] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`
+      );
+    }
+  }
+
+  return resolved;
+}

package/src/internal/review-comments.ts

@@ -0,0 +1,268 @@
+import { spawn } from "node:child_process";
+
+export type ReviewCommentPublisher = "local_gh";
+
+export type ReviewCommentPostResult = {
+  posted: boolean;
+  publisher: ReviewCommentPublisher;
+  mode: "review_with_inline_comments" | "review_body_only" | "skipped";
+  inlineCommentCount: number;
+  detail: string;
+};
+
+export type ReviewInlineComment = {
+  file: string;
+  line: number;
+  start_line?: number;
+  body: string;
+};
+
+export type ReviewCommentPostArgs = {
+  prUrl: string;
+  reviewedHeadSha: string;
+  message: string;
+  comments: ReviewInlineComment[];
+  cleanupPrevious?: boolean;
+  signal?: AbortSignal;
+};
+
+export type ReviewCommentsRequest = {
+  provider: "github";
+  repo: string;
+  prNumber: number;
+  headSha: string;
+  message: string;
+  comments: ReviewInlineComment[];
+  cleanupPrevious: boolean;
+};
+
+export type ReviewCommentPublisherImplementation = {
+  postReview: (args: ReviewCommentPostArgs) => Promise<ReviewCommentPostResult>;
+};
+
+type ParsedGithubPrUrl = {
+  repo: string;
+  prNumber: number;
+};
+
+/**
+ * Prepares the provider-neutral review payload used by local `gh` posting.
+ */
+export function prepareReviewCommentsRequest(
+  args: ReviewCommentPostArgs
+):
+  | { kind: "prepared"; request: ReviewCommentsRequest }
+  | { kind: "skipped"; result: ReviewCommentPostResult } {
+  const target = parseGithubPrUrl(args.prUrl);
+  if (target.kind === "invalid") {
+    return { kind: "skipped", result: skipped(target.detail) };
+  }
+
+  return {
+    kind: "prepared",
+    request: {
+      provider: "github",
+      repo: target.value.repo,
+      prNumber: target.value.prNumber,
+      headSha: args.reviewedHeadSha,
+      message: args.message,
+      comments: args.comments,
+      cleanupPrevious: args.cleanupPrevious ?? true,
+    },
+  };
+}
+
+/**
+ * Posts a PR review with the local `gh` credentials (`gh auth` / GITHUB_TOKEN /
+ * GH_TOKEN). Does not use the security-bugbot comments service.
+ */
+export function createLocalGhReviewPublisher(): ReviewCommentPublisherImplementation {
+  return {
+    async postReview(args) {
+      return postReviewViaLocalGh(args);
+    },
+  };
+}
+
+async function postReviewViaLocalGh(
+  args: ReviewCommentPostArgs
+): Promise<ReviewCommentPostResult> {
+  const prepared = prepareReviewCommentsRequest(args);
+  if (prepared.kind === "skipped") {
+    return prepared.result;
+  }
+
+  const { request } = prepared;
+  const path = `repos/${request.repo}/pulls/${request.prNumber}/reviews`;
+  const payload = {
+    commit_id: request.headSha,
+    body: request.message,
+    event: "COMMENT",
+    comments: request.comments.map(toGithubReviewComment),
+  };
+
+  try {
+    args.signal?.throwIfAborted();
+    const response = await ghApiPostJson(path, payload, args.signal);
+    const htmlUrl =
+      typeof response.html_url === "string" ? response.html_url : undefined;
+    const inlineCommentCount = request.comments.length;
+    return {
+      posted: true,
+      publisher: "local_gh",
+      mode:
+        inlineCommentCount > 0
+          ? "review_with_inline_comments"
+          : "review_body_only",
+      inlineCommentCount,
+      detail: htmlUrl
+        ? `posted via local gh: ${htmlUrl}`
+        : `posted via local gh with ${inlineCommentCount} inline comment(s)`,
+    };
+  } catch (error) {
+    if (args.signal?.aborted) {
+      throw error;
+    }
+    return skipped(
+      `local gh review post failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+function toGithubReviewComment(
+  comment: ReviewInlineComment
+): Record<string, string | number> {
+  const body: Record<string, string | number> = {
+    path: comment.file,
+    body: comment.body,
+    line: comment.line,
+    side: "RIGHT",
+  };
+  if (
+    comment.start_line !== undefined &&
+    comment.start_line > 0 &&
+    comment.start_line !== comment.line
+  ) {
+    body.start_line = comment.start_line;
+    body.start_side = "RIGHT";
+  }
+  return body;
+}
+
+function skipped(detail: string): ReviewCommentPostResult {
+  return {
+    posted: false,
+    publisher: "local_gh",
+    mode: "skipped",
+    inlineCommentCount: 0,
+    detail,
+  };
+}
+
+function parseGithubPrUrl(
+  prUrl: string
+):
+  | { kind: "valid"; value: ParsedGithubPrUrl }
+  | { kind: "invalid"; detail: string } {
+  let url: URL;
+  try {
+    url = new URL(prUrl);
+  } catch (error) {
+    return {
+      kind: "invalid",
+      detail: `unparseable PR URL: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  if (url.hostname !== "github.com") {
+    return {
+      kind: "invalid",
+      detail: "local gh publisher only supports github.com PRs",
+    };
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length !== 4 || parts[2] !== "pull") {
+    return {
+      kind: "invalid",
+      detail:
+        "unparseable PR URL: expected https://github.com/{owner}/{repo}/pull/{number}",
+    };
+  }
+
+  const prNumber = Number(parts[3]);
+  if (!Number.isInteger(prNumber) || prNumber <= 0) {
+    return {
+      kind: "invalid",
+      detail:
+        "unparseable PR URL: pull request number must be a positive integer",
+    };
+  }
+
+  return {
+    kind: "valid",
+    value: {
+      repo: `${parts[0]}/${parts[1]}`,
+      prNumber,
+    },
+  };
+}
+
+async function ghApiPostJson(
+  path: string,
+  payload: unknown,
+  signal?: AbortSignal
+): Promise<Record<string, unknown>> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(
+      "gh",
+      ["api", path, "--method", "POST", "--input", "-"],
+      {
+        env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+      }
+    );
+    let stdout = "";
+    let stderr = "";
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      rejectPromise(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      signal?.removeEventListener("abort", onAbort);
+      rejectPromise(error);
+    });
+    child.on("close", (code) => {
+      signal?.removeEventListener("abort", onAbort);
+      if (code !== 0) {
+        rejectPromise(
+          new Error(
+            `gh api ${path} exited with ${code}: ${stderr.trim().slice(0, 2000)}`
+          )
+        );
+        return;
+      }
+      if (!stdout.trim()) {
+        resolvePromise({});
+        return;
+      }
+      try {
+        resolvePromise(JSON.parse(stdout) as Record<string, unknown>);
+      } catch (error) {
+        rejectPromise(
+          new Error(
+            `gh api ${path} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+          )
+        );
+      }
+    });
+    child.stdin.end(JSON.stringify(payload));
+  });
+}