@cursor/july 0.1.103 → 0.1.104

package/src/index.ts

@@ -66,6 +66,34 @@ export {
   disableSubagent,
   disableTool,
 } from "./extensions.js";
+export type {
+  DirEntry,
+  EditQuery,
+  EditResult,
+  FileInfo,
+  FileSystem,
+  GrepQuery,
+  GrepResult,
+  SearchQuery,
+  SearchResult,
+} from "./filesystem.js";
+export {
+  DeleteNotSupportedError,
+  EditError,
+  emptyFs,
+  FileNotFoundError,
+  hostFs,
+  InvalidGrepPatternError,
+  isFileNotFoundError,
+  NoMountError,
+  overlayFs,
+  PathError,
+  ReadOnlyMountError,
+  strReplaceOnFileSystem,
+  tempFs,
+  unionFs,
+  WriteFailedError,
+} from "./filesystem.js";
 export { defineHook } from "./hooks.js";
 export {
   InvalidAsOfError,

package/src/internal/continuation-channel.ts

@@ -1,7 +1,9 @@
 import { getBitbucketChannelOptions } from "../channels/bitbucket/bitbucket-channel.js";
+import { getChangeMonitorsChannelOptions } from "../channels/change-monitors/change-monitors-channel.js";
 import { getDeploymentsChannelOptions } from "../channels/deployments/deployments-channel.js";
 import { getGitHubChannelOptions } from "../channels/github/github-channel.js";
 import { getGitLabChannelOptions } from "../channels/gitlab/gitlab-channel.js";
+import { getIssuesChannelOptions } from "../channels/issues/issues-channel.js";
 import { getOriginChannelOptions } from "../channels/origin/origin-channel.js";
 import { getSlackChannelOptions } from "../channels/slack/slack-channel.js";
 import type {
@@ -17,6 +19,7 @@ import {
   handshakeContinuation,
   normalizeIdentity,
   omittedV2MembershipDowngrade,
+  omittedV2TypedType,
 } from "./continuation-identity.js";
 
 type ContinuationChannelOptions = {
@@ -24,7 +27,15 @@ type ContinuationChannelOptions = {
 };
 
 const CONTINUATION_CHANNEL_PACKS: ReadonlyArray<{
-  kind: "github" | "slack" | "origin" | "gitlab" | "bitbucket" | "deployments";
+  kind:
+    | "github"
+    | "slack"
+    | "origin"
+    | "gitlab"
+    | "bitbucket"
+    | "deployments"
+    | "change_monitors"
+    | "issues";
   getOptions: (definition: object) => ContinuationChannelOptions | undefined;
   usesDeclaredEvents: boolean;
 }> = [
@@ -58,6 +69,16 @@ const CONTINUATION_CHANNEL_PACKS: ReadonlyArray<{
     getOptions: getDeploymentsChannelOptions,
     usesDeclaredEvents: true,
   },
+  {
+    kind: "change_monitors",
+    getOptions: getChangeMonitorsChannelOptions,
+    usesDeclaredEvents: true,
+  },
+  {
+    kind: "issues",
+    getOptions: getIssuesChannelOptions,
+    usesDeclaredEvents: true,
+  },
 ];
 
 export function channelContinuationIdentity(
@@ -85,8 +106,10 @@ export function httpContinuationIdentity(
  * Stamp `/v2` continuation defaults onto channel constructors that omitted
  * `continuation` when the agent deploys onto v2 architecture. GitHub/Origin
  * type (`pr` / `issue` / `none`) follows declared webhook events.
- * Deployments default to `deployments.deployment/v2`. Explicit per-channel
- * selectors are left alone. Idempotent.
+ * Deployments default to `deployments.deployment/v2`. Change Monitors
+ * and issues default to `change_monitors.checkpoint/v2` and
+ * `issues.issue/v2`.
+ * Explicit per-channel selectors are left alone. Idempotent.
  */
 export function applyAgentContinuationDefaults(project: {
   agent: { architecture?: AgentArchitecture };
@@ -155,14 +178,7 @@ function omittedContinuationDowngradeMessage(
     unexpected: readonly string[];
   }
 ): string {
-  const membership =
-    kind === "github"
-      ? "pr"
-      : kind === "origin"
-        ? "origin-pr"
-        : kind === "deployments"
-          ? "deployment"
-          : kind;
+  const membership = omittedV2TypedType(kind) ?? kind;
   return (
     `omitted continuation stamped ${downgrade.selector} because ` +
     `${downgrade.unexpected.join(", ")} ${
@@ -205,7 +221,8 @@ export function channelDeclaredEventTypes(
     meta?.originWebhookEvents ??
     meta?.gitlabWebhookEvents ??
     meta?.bitbucketWebhookEvents ??
-    meta?.deploymentEventTypes
+    meta?.deploymentEventTypes ??
+    meta?.factoryEventTypes
   );
 }
 

package/src/internal/continuation-identity.ts

@@ -3,14 +3,16 @@
  * on a channel constructor stays `/v1` (engine pack minting) so existing
  * agents do not change: `githubChannel()` → `github.pr/v1`, `slackChannel()`
  * → `slack.thread/v1`, `originChannel()` → `origin.pr/v1`,
- * `deploymentsChannel()` → `deployments.none/v1`, `httpChannel()` →
+ * `deploymentsChannel()` → `deployments.none/v1`, `changeMonitorsChannel()`
+ * → `none/v1`, `issuesChannel()` → `none/v1`, `httpChannel()` →
  * `none/v1`.
  *
  * Opt the whole agent into the v2 control plane with
  * `defineAgent({ architecture: "v2" })`. That stamps `/v2` defaults from
  * the channel kind and declared events (`github.pr/v2`, `github.issue/v2`,
  * `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
- * `deployments.deployment/v2`, …) onto every channel that omitted a
+ * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
+ * `issues.issue/v2`, …) onto every channel that omitted a
  * selector. An explicit per-channel selector still overrides. JSONPath
  * and per-agent format strings are rejected.
  */
@@ -24,7 +26,9 @@ export type ConversationType =
   | "origin-pr"
   | "gitlab-mr"
   | "bitbucket-pr"
-  | "deployment";
+  | "deployment"
+  | "change-monitor-checkpoint"
+  | "factory-issue";
 
 export type ContinuationKind =
   | "github"
@@ -33,6 +37,8 @@ export type ContinuationKind =
   | "gitlab"
   | "bitbucket"
   | "deployments"
+  | "change_monitors"
+  | "issues"
   | "http";
 
 export const CONTINUATION_SELECTORS = [
@@ -54,6 +60,8 @@ export const CONTINUATION_SELECTORS = [
   "deployments.none/v1",
   "deployments.none/v2",
   "deployments.deployment/v2",
+  "change_monitors.checkpoint/v2",
+  "issues.issue/v2",
   "none/v1",
   "none/v2",
 ] as const;
@@ -76,7 +84,9 @@ export type ContinuationClaim = {
     | { owner: string; repo: string; number: number }
     | { channelId: string; threadTs: string }
     | { fullName: string; number: number }
-    | { deploymentId: string };
+    | { deploymentId: string }
+    | { checkpointName: string }
+    | { issueName: string };
 };
 
 export type MailboxContinuation = {
@@ -167,6 +177,18 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
     events: ["deployment.created", "deployment.succeeded", "deployment.failed"],
     format: "deployments:{deploymentId}",
   },
+  {
+    type: "change-monitor-checkpoint",
+    kind: "change_monitors",
+    events: ["checkpoint.created"],
+    format: "change_monitors:{checkpointName}",
+  },
+  {
+    type: "factory-issue",
+    kind: "issues",
+    events: ["issue.created"],
+    format: "issues:{issueName}",
+  },
 ] as const;
 
 export class V2EngineError extends Error {
@@ -201,6 +223,16 @@ const SELECTOR_FIELDS: {
     type: "deployment",
     kind: "deployments",
   },
+  "change_monitors.checkpoint/v2": {
+    version: 2,
+    type: "change-monitor-checkpoint",
+    kind: "change_monitors",
+  },
+  "issues.issue/v2": {
+    version: 2,
+    type: "factory-issue",
+    kind: "issues",
+  },
   "none/v1": { version: 1, type: "none", kind: "http" },
   "none/v2": { version: 2, type: "none", kind: "http" },
 };
@@ -234,7 +266,12 @@ export function defaultContinuationSelector(
     case "slack":
       return "slack.thread/v2";
     case "origin":
-      return originV2Default(eventTypes);
+      return membershipOrNone(
+        eventTypes,
+        "origin-pr",
+        "origin.pr/v2",
+        "origin.none/v2"
+      );
     case "gitlab":
       return membershipOrNone(
         eventTypes,
@@ -250,7 +287,26 @@ export function defaultContinuationSelector(
         "bitbucket.none/v2"
       );
     case "deployments":
-      return deploymentsV2Default(eventTypes);
+      return membershipOrNone(
+        eventTypes,
+        "deployment",
+        "deployments.deployment/v2",
+        "deployments.none/v2"
+      );
+    case "change_monitors":
+      return membershipOrNone(
+        eventTypes,
+        "change-monitor-checkpoint",
+        "change_monitors.checkpoint/v2",
+        "none/v2"
+      );
+    case "issues":
+      return membershipOrNone(
+        eventTypes,
+        "factory-issue",
+        "issues.issue/v2",
+        "none/v2"
+      );
     default:
       return "none/v2";
   }
@@ -283,13 +339,17 @@ function githubV2Default(eventTypes?: readonly string[]): ContinuationSelector {
   return "github.pr/v2";
 }
 
-function originV2Default(eventTypes?: readonly string[]): ContinuationSelector {
-  const events = eventTypes ?? [];
-  const prEvents = new Set(builtinForType("origin-pr")?.events ?? []);
-  if (events.some((event) => !prEvents.has(event))) {
-    return "origin.none/v2";
-  }
-  return "origin.pr/v2";
+const OMITTED_V2_TYPED_TYPE = {
+  github: "pr",
+  origin: "origin-pr",
+  deployments: "deployment",
+  change_monitors: "change-monitor-checkpoint",
+  issues: "factory-issue",
+} as const satisfies Partial<Record<string, ConversationType>>;
+
+/** Typed membership used when an omitted `/v2` selector becomes type `none`. */
+export function omittedV2TypedType(kind: string): ConversationType | undefined {
+  return OMITTED_V2_TYPED_TYPE[kind as keyof typeof OMITTED_V2_TYPED_TYPE];
 }
 
 /**
@@ -312,14 +372,8 @@ export function omittedV2MembershipDowngrade(
   if (parsed === undefined || parsed.type !== "none") {
     return undefined;
   }
-  const typed =
-    kind === "github"
-      ? builtinForType("pr")
-      : kind === "origin"
-        ? builtinForType("origin-pr")
-        : kind === "deployments"
-          ? builtinForType("deployment")
-          : undefined;
+  const typedType = omittedV2TypedType(kind);
+  const typed = typedType === undefined ? undefined : builtinForType(typedType);
   if (typed === undefined) {
     return undefined;
   }
@@ -331,17 +385,6 @@ export function omittedV2MembershipDowngrade(
   return { selector, unexpected };
 }
 
-function deploymentsV2Default(
-  eventTypes?: readonly string[]
-): ContinuationSelector {
-  const events = eventTypes ?? [];
-  const deploymentEvents = new Set(builtinForType("deployment")?.events ?? []);
-  if (events.some((event) => !deploymentEvents.has(event))) {
-    return "deployments.none/v2";
-  }
-  return "deployments.deployment/v2";
-}
-
 export function parseContinuationSelector(
   selector: string
 ): ParsedContinuation | undefined {
@@ -403,6 +446,8 @@ function formatConversationKey(
     channelId?: string;
     threadTs?: string;
     deploymentId?: string;
+    checkpointName?: string;
+    issueName?: string;
   }
 ): string {
   switch (type) {
@@ -420,6 +465,10 @@ function formatConversationKey(
       return `${fields.channelId}:${fields.threadTs}`;
     case "deployment":
       return `deployments:${fields.deploymentId}`;
+    case "change-monitor-checkpoint":
+      return `change_monitors:${fields.checkpointName}`;
+    case "factory-issue":
+      return `issues:${fields.issueName}`;
   }
 }
 
@@ -441,6 +490,22 @@ export function mintClaim(claim: ContinuationClaim): string {
       }
       return `cont:${formatConversationKey("deployment", resource)}`;
     }
+    case "change-monitor-checkpoint": {
+      const resource = claim.resource;
+      if (!("checkpointName" in resource)) {
+        throw new V2EngineError(
+          "v2: change-monitor-checkpoint claim requires checkpointName"
+        );
+      }
+      return `cont:${formatConversationKey("change-monitor-checkpoint", resource)}`;
+    }
+    case "factory-issue": {
+      const resource = claim.resource;
+      if (!("issueName" in resource)) {
+        throw new V2EngineError("v2: factory-issue claim requires issueName");
+      }
+      return `cont:${formatConversationKey("factory-issue", resource)}`;
+    }
     case "pr":
     case "issue":
     case "origin-pr":
@@ -551,7 +616,21 @@ export function extractContinuation(
     case "bitbucket-pr":
       return extractBitbucket(payload);
     case "deployment":
-      return extractDeployment(payload);
+      return extractNamedResource("deployment", "deploymentId", payload);
+    case "change-monitor-checkpoint":
+      return extractNamedResource(
+        "change-monitor-checkpoint",
+        "checkpointName",
+        payload,
+        "checkpoint"
+      );
+    case "factory-issue":
+      return extractNamedResource(
+        "factory-issue",
+        "issueName",
+        payload,
+        "issue"
+      );
   }
 }
 
@@ -847,13 +926,19 @@ function bitbucketFullName(
   return `${projectKey}/${slug}`.toLowerCase();
 }
 
-function extractDeployment(payload: unknown): string | undefined {
+function extractNamedResource(
+  type: "deployment" | "change-monitor-checkpoint" | "factory-issue",
+  field: "deploymentId" | "checkpointName" | "issueName",
+  payload: unknown,
+  wrapper?: "checkpoint" | "issue"
+): string | undefined {
   const record = asRecord(payload);
-  const deploymentId = nonEmpty(record?.deploymentId);
-  if (deploymentId === undefined) {
+  const source = wrapper === undefined ? record : asRecord(record?.[wrapper]);
+  const value = nonEmpty(source?.[wrapper === undefined ? field : "name"]);
+  if (value === undefined) {
     return undefined;
   }
-  return `cont:${formatConversationKey("deployment", { deploymentId })}`;
+  return `cont:${formatConversationKey(type, { [field]: value })}`;
 }
 
 function githubFullName(payload: Record<string, unknown>): string | undefined {

package/src/internal/discovery/agent.ts

@@ -3,6 +3,12 @@
  */
 
 import { join } from "node:path";
+import {
+  canonicalizeFileSystemToolName,
+  FileSystemConfigError,
+  resolveFileSystemTools,
+  resolveRootHarnessAllowlist,
+} from "../../filesystem.js";
 import {
   type ArtifactsDefinition,
   DEFAULT_MODEL,
@@ -12,6 +18,7 @@ import {
   type DiscoveredSchedule,
   type ResolvedAgent,
 } from "../../types.js";
+import { synthesizedFileSystemToolNames } from "../filesystem/tools.js";
 import { withIdentityPreamble } from "../workspace.js";
 import {
   isValidModelSetting,
@@ -135,10 +142,88 @@ export async function loadAgent(
   // second layer (authored tools, mcp-connections, the harness cwd's
   // ambient config).
   const authoredAllowlist = config?.tools;
-  const allowedTools =
+  const root = config?.root;
+  const hasRoot = root !== undefined;
+  if (hasRoot) {
+    if (
+      config?.local?.cwd !== undefined ||
+      config?.local?.workspaceDir !== undefined ||
+      config?.local?.sandbox === true
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          "`root` cannot be combined with `local.cwd`, `local.workspaceDir`, or `local.sandbox`. Those fields configure the host tree the override replaced.",
+      });
+    }
+    if (runtime === "cloud" || runtime === "grokbot") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `\`root\` cannot be combined with runtime: "${runtime}".`,
+      });
+    }
+    if (
+      authoredAllowlist?.includes("shell") === true ||
+      authoredAllowlist?.includes("Shell") === true
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          '`root` cannot be combined with `tools` containing `"shell"`. Shell is not a FileSystem method and must not bind the host shell onto a virtual tree.',
+      });
+    }
+  }
+  const reservedNames = new Set<string>(
+    synthesizedFileSystemToolNames({
+      hasRoot,
+      tools: authoredAllowlist,
+    })
+  );
+  const clash = tools.find((tool) => {
+    if (reservedNames.has(tool.name)) {
+      return true;
+    }
+    const canonical = canonicalizeFileSystemToolName(tool.name);
+    return canonical !== undefined && reservedNames.has(canonical);
+  });
+  if (clash !== undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "tools", `${clash.name}.ts`)),
+      message: `agent/tools/${clash.name}.ts: that name is reserved for the synthesized FileSystem tool.`,
+    });
+  }
+  let allowedTools =
     authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
       ? authoredAllowlist
       : [...authoredAllowlist, "mcp" as const];
+  if (hasRoot) {
+    try {
+      if (typeof root !== "function") {
+        resolveFileSystemTools({
+          root,
+          tools: authoredAllowlist,
+        });
+      } else {
+        resolveRootHarnessAllowlist(authoredAllowlist);
+      }
+      allowedTools = authoredAllowlist;
+    } catch (error) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          error instanceof FileSystemConfigError
+            ? error.message
+            : error instanceof Error
+              ? error.message
+              : String(error),
+      });
+    }
+  }
   // The allowlist states runtime-agnostic intent, but only the local
   // harness can enforce it (the Cursor SDK rejects tool restrictions on
   // cloud agents, and the Grok Bot harness has its own fixed toolset) — a
@@ -247,6 +332,7 @@ export async function loadAgent(
       model: isValidModelSetting(config?.model) ? config.model : DEFAULT_MODEL,
       instructions,
       runtime,
+      ...(root === undefined ? {} : { root }),
       cloud,
       local,
       ...(allowedTools === undefined ? {} : { allowedTools }),

package/src/internal/discovery/info.ts

@@ -137,6 +137,9 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
         if (meta?.deploymentEventTypes !== undefined) {
           info.deploymentEventTypes = meta.deploymentEventTypes;
         }
+        if (meta?.factoryEventTypes !== undefined) {
+          info.factoryEventTypes = meta.factoryEventTypes;
+        }
         if (meta?.slackChannelPosts !== undefined) {
           info.slackChannelPosts = meta.slackChannelPosts;
         }

package/src/internal/factory-resource-channel.ts

@@ -0,0 +1,122 @@
+import type { z } from "zod";
+import { defineChannel, localDevStrict, POST } from "../channels.js";
+import type { ChannelDefinition, ChannelHandlerArgs } from "../types.js";
+import { tagOutcome } from "./channel-dispatch.js";
+import type { ContinuationIdentity } from "./continuation-identity.js";
+import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
+import { bindLocalIngressSend } from "./local-ingress.js";
+
+type FactoryResourceChannelOptions<TEvent> = {
+  onEvent: (
+    event: TEvent,
+    args: ChannelHandlerArgs
+  ) => Promise<unknown> | unknown;
+  continuation?: ContinuationIdentity;
+  path?: string;
+  auth?: ChannelDefinition["auth"];
+  onStart?: ChannelDefinition["onStart"];
+  onStop?: ChannelDefinition["onStop"];
+};
+
+type FactoryResourceChannelSpec<TEvent extends { eventType: string }> = {
+  kind: string;
+  eventTypes: readonly string[];
+  eventSchema: z.ZodType<TEvent>;
+  replayDescription: string;
+  invalidError: string;
+};
+
+type FactoryResourceChannelPack<TEvent> = {
+  channel: (
+    options: FactoryResourceChannelOptions<TEvent>
+  ) => ChannelDefinition;
+  getOptions: (
+    definition: object
+  ) => FactoryResourceChannelOptions<TEvent> | undefined;
+};
+
+/**
+ * Shared pack for Factory resource channels that have one event type, no
+ * subscription filter, and the same local-replay / hosted-admission path.
+ */
+export function createFactoryResourceChannel<
+  TEvent extends { eventType: string },
+>(
+  spec: FactoryResourceChannelSpec<TEvent>
+): FactoryResourceChannelPack<TEvent> {
+  const optionsByDefinition = new WeakMap<
+    object,
+    FactoryResourceChannelOptions<TEvent>
+  >();
+
+  async function dispatchEvent(input: {
+    options: FactoryResourceChannelOptions<TEvent>;
+    event: TEvent;
+    args: ChannelHandlerArgs;
+  }): Promise<Response> {
+    await input.options.onEvent(
+      input.event,
+      bindLocalIngressSend(input.args, {
+        identity: input.options.continuation,
+        kind: spec.kind,
+        eventType: input.event.eventType,
+        payload: input.event,
+      })
+    );
+    return tagOutcome(Response.json({ ok: true }), "task");
+  }
+
+  function channel(
+    options: FactoryResourceChannelOptions<TEvent>
+  ): ChannelDefinition {
+    const routePath = options.path ?? "/";
+    const definition = defineChannel({
+      auth: options.auth ?? [localDevStrict()],
+      meta: {
+        kind: spec.kind,
+        factoryEventTypes: spec.eventTypes,
+      },
+      onStart: options.onStart,
+      onStop: options.onStop,
+      routes: [
+        POST(routePath, {
+          description: spec.replayDescription,
+          bodySchema: spec.eventSchema,
+          handler: async (_request, args) =>
+            dispatchEvent({
+              options,
+              event: args.body,
+              args,
+            }),
+        }),
+      ],
+    });
+    optionsByDefinition.set(definition, options);
+    attachHostedAdmissionAdapter(definition, {
+      kind: spec.kind,
+      dispatch: async ({ payload, args }) => {
+        const parsed = spec.eventSchema.safeParse(payload);
+        if (!parsed.success) {
+          return Response.json(
+            { ok: false, error: spec.invalidError },
+            { status: 400 }
+          );
+        }
+        return dispatchEvent({
+          options,
+          event: parsed.data,
+          args,
+        });
+      },
+    });
+    return definition;
+  }
+
+  function getOptions(
+    definition: object
+  ): FactoryResourceChannelOptions<TEvent> | undefined {
+    return optionsByDefinition.get(definition);
+  }
+
+  return { channel, getOptions };
+}