@cursor/july 0.1.103 → 0.1.104

package/src/internal/testing/factory-resource-fixtures.ts

@@ -0,0 +1,85 @@
+/**
+ * Factory resource continuation fixtures shared by July and the control
+ * plane identity suite. Pure data: no imports, so server-shared can load
+ * this file by relative path without pulling `@cursor/july`.
+ */
+
+export const FACTORY_CHECKPOINT_NAME: string =
+  "changeMonitors/cm-1/checkpoints/cp-1";
+export const FACTORY_ISSUE_NAME: string = "issues/iss-1";
+
+export interface FactoryCheckpointResourceFixture {
+  name: string;
+  deployment: string;
+  runKey: string;
+  issues: { title: string };
+  evidenceSummary: string;
+  planRevision: string;
+  createTime: string;
+  description: string;
+}
+
+export interface FactoryIssueResourceFixture {
+  name: string;
+  title: string;
+  body: string;
+  state: "STATE_OPEN";
+  createTime: string;
+  updateTime: string;
+  path: string;
+  etag: string;
+}
+
+export interface CheckpointCreatedPayloadFixture {
+  eventId: string;
+  eventType: "checkpoint.created";
+  teamId: string;
+  occurredAtMs: number;
+  checkpoint: FactoryCheckpointResourceFixture;
+}
+
+export interface IssueCreatedPayloadFixture {
+  eventId: string;
+  eventType: "issue.created";
+  teamId: string;
+  occurredAtMs: number;
+  issue: FactoryIssueResourceFixture;
+}
+
+export const FACTORY_CHECKPOINT_RESOURCE: FactoryCheckpointResourceFixture = {
+  name: FACTORY_CHECKPOINT_NAME,
+  deployment: "deployments/11111111-1111-4111-8111-111111111111",
+  runKey: "t+1h",
+  issues: { title: "POST /checkout 500 rate elevated" },
+  evidenceSummary: "5xx rate rose after the deploy.",
+  planRevision: "changeMonitors/cm-1/planRevisions/3",
+  createTime: "2026-09-08T21:00:00Z",
+  description: "Checkout 500s are elevated.",
+};
+
+export const FACTORY_ISSUE_RESOURCE: FactoryIssueResourceFixture = {
+  name: FACTORY_ISSUE_NAME,
+  title: "Checkout 500s",
+  body: "5xx rate rose after the deploy.",
+  state: "STATE_OPEN",
+  createTime: "2026-09-08T21:00:00Z",
+  updateTime: "2026-09-08T21:00:00Z",
+  path: "checkout/500s",
+  etag: 'W/"1"',
+};
+
+export const CHECKPOINT_CREATED_PAYLOAD: CheckpointCreatedPayloadFixture = {
+  eventId: "evt-cp-1",
+  eventType: "checkpoint.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  checkpoint: FACTORY_CHECKPOINT_RESOURCE,
+};
+
+export const ISSUE_CREATED_PAYLOAD: IssueCreatedPayloadFixture = {
+  eventId: "evt-iss-1",
+  eventType: "issue.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  issue: FACTORY_ISSUE_RESOURCE,
+};

package/src/types.ts

@@ -11,6 +11,7 @@
 import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type { FileSystem } from "./filesystem.js";
 import type {
   ContinuationClaim,
   ContinuationIdentity,
@@ -169,6 +170,18 @@ export function toPublicCloudInfo(
   };
 }
 
+/**
+ * Session-scoped facts a `root` factory needs and does not otherwise
+ * have at `defineAgent` time. The factory returns a handle: each
+ * method must observe the current binding. Do not snapshot the tree.
+ */
+export interface RootContext {
+  sessionId: string;
+  agentName?: string;
+  continuationKey?: string;
+  host?: { files: HostFilesApi; reminders?: ReminderHostApi };
+}
+
 /** Input to `defineAgent` (authored at `agent/agent.ts`). */
 export interface AgentConfig {
   /**
@@ -190,10 +203,21 @@ export interface AgentConfig {
    */
   instructions?: string;
   /**
-   * Execution runtime. Defaults to `"local"`. Use `"cloud"` to run turns
-   * on Cursor cloud agents (see {@link cloud}).
+   * Execution runtime. Defaults to `"local"`. Compatibility strings
+   * `"cloud"` and `"grokbot"` remain for agents that already ship; they
+   * are not a product surface. New agents omit this field.
    */
   runtime?: AgentRuntime;
+  /**
+   * The FileSystem the model can see. Omit it and the root is the host
+   * disk. A static handle (`tempFs`, `unionFs`, ...) is that object on
+   * every session — writes are shared. Pass `(ctx) => …` and return a
+   * new handle per session when you want isolation. A factory that
+   * returns the same object still shares. Incompatible with
+   * {@link local} `cwd` / `workspaceDir` / `sandbox` and with
+   * {@link runtime} `"cloud"`.
+   */
+  root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
   /**
    * Cloud agent defaults. Used when {@link runtime} is `"cloud"`, and as
    * the base merged under per-session {@link SendMessageOptions.cloud}
@@ -262,7 +286,8 @@ export interface AgentConfig {
    * deploys onto the v2 control plane (v2 APIs and schemas). Omitted
    * channel `continuation` then inherits from declared events (`github.pr/v2`,
    * `github.issue/v2`, `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
-   * `deployments.deployment/v2`, `none/v2`). An explicit per-channel selector
+   * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
+   * `issues.issue/v2`, `none/v2`). An explicit per-channel selector
    * still overrides.
    *
    * ```ts
@@ -2520,6 +2545,13 @@ export interface ChannelMeta {
    * to dispatch on. Extracted into the deploy manifest as `eventTypes`.
    */
   deploymentEventTypes?: readonly string[];
+  /**
+   * For Change Monitor checkpoint and Factory issue packs: the factory
+   * event types this channel is wired to dispatch on. Extracted into the
+   * deploy manifest as `eventTypes`. Kept separate from
+   * `deploymentEventTypes`.
+   */
+  factoryEventTypes?: readonly string[];
   /**
    * For Slack packs with the opt-in channel watch: the allowlisted channels
    * (ids or `#names`) this channel dispatches on without a mention. Surfaced
@@ -3122,6 +3154,11 @@ export interface ResolvedAgent {
   instructions?: string;
   /** Execution runtime. Root agents default to `"local"`. */
   runtime: AgentRuntime;
+  /**
+   * Authored {@link AgentConfig.root}. The factory is persisted, not a
+   * serialized tree. A resumed session calls it again (or reuses the handle).
+   */
+  root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
   /** Cloud options when {@link runtime} is `"cloud"`. */
   cloud?: AgentCloudOptions;
   /**
@@ -3274,6 +3311,8 @@ export interface AgentProjectInfo {
     bitbucketWebhookEvents?: readonly string[];
     /** Factory deployment event types the channel dispatches on, when declared. */
     deploymentEventTypes?: readonly string[];
+    /** Change Monitor checkpoint or Factory issue event types the channel dispatches on, when declared. */
+    factoryEventTypes?: readonly string[];
     /** Slack channels watched for posts (opt-in channel watch), when declared. */
     slackChannelPosts?: readonly string[];
   }>;
@@ -3324,10 +3363,17 @@ export interface RunnerTurnRequest {
   sdkAgentId?: string;
   /** Absolute path of the session's materialized workspace. */
   workspaceDir: string;
+  /** Resolved FileSystem handle when {@link AgentConfig.root} is set. */
+  root?: FileSystem;
   /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
   sandbox?: boolean;
   /** Built-in tool allowlist ({@link AgentConfig.tools}, resolved). */
   tools?: ToolName[];
+  /**
+   * Native tools hidden on the Cursor SDK agent because synthesized
+   * FileSystem tools own those names. Host-default omitted `tools` only.
+   */
+  disallowedTools?: ToolName[];
   /** Absolute path for runner-owned durable state (conversation store). */
   runnerStateDir: string;
   prompt: string;