@cursor/july 0.1.103 → 0.1.105

package/src/internal/store-mirror.ts

@@ -1,7 +1,7 @@
 /**
  * Mirror an authored file tree onto an Agent Store prefix. Shared by the
- * skills and workspace seed syncs so both keep the same write-then-sweep
- * discipline and the same path refusals.
+ * skills, workspace seed, and session workspaceFile syncs so they keep the
+ * same write-then-sweep discipline and the same path refusals.
  */
 
 import { posix } from "node:path";

package/src/internal/tenant-slack/relay.ts

@@ -109,13 +109,22 @@ export async function postRelaySlackMessage(args: {
   resolve?: () => RelaySlackPostTarget | undefined;
   fetchImpl?: typeof fetch;
   timeoutMs?: number;
+  /** Diagnostic sink; defaults to `console.info`. */
+  log?: (line: string) => void;
 }): Promise<RelaySlackPostResult> {
   const channel = args.channel.trim();
+  const log = args.log ?? ((line: string) => console.info(line));
   if (channel === "") {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid}: empty channel`
+    );
     return { ok: false, channel, status: 0, error: "empty channel" };
   }
   const target = (args.resolve ?? resolveRelaySlackTarget)();
   if (target === undefined) {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid} channel=${channel}: no Cursor credential resolved (CURSOR_API_KEY / pod credential absent)`
+    );
     return {
       ok: false,
       channel,
@@ -128,6 +137,11 @@ export async function postRelaySlackMessage(args: {
     baseUrl: target.relayBaseUrl,
     automationUuid: args.automationUuid,
   });
+  const messageChars = args.message.length;
+  log(
+    `[agent-sdk-slack-relay-client] POST ${url} channel=${channel} messageChars=${String(messageChars)} truncated=${String(messageChars > AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS)} threaded=${String(args.threadTs !== undefined)} timeoutMs=${String(args.timeoutMs ?? DEFAULT_TIMEOUT_MS)}`
+  );
+  const startedAt = Date.now();
   let response: Response;
   try {
     response = await fetchImpl(url, {
@@ -145,6 +159,9 @@ export async function postRelaySlackMessage(args: {
       signal: AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
+    log(
+      `[agent-sdk-slack-relay-client] request failed before a response channel=${channel} automationUuid=${args.automationUuid} elapsedMs=${String(Date.now() - startedAt)}: ${describeError(error)}`
+    );
     return { ok: false, channel, status: 0, error: describeError(error) };
   }
   let body: unknown;
@@ -158,16 +175,23 @@ export async function postRelaySlackMessage(args: {
       ? (body as Record<string, unknown>)
       : {};
   if (!response.ok || record.ok !== true) {
+    const error =
+      typeof record.error === "string" && record.error !== ""
+        ? record.error
+        : `relay responded ${response.status}`;
+    log(
+      `[agent-sdk-slack-relay-client] relay denied channel=${channel} automationUuid=${args.automationUuid} status=${String(response.status)} bodyOk=${String(record.ok)} elapsedMs=${String(Date.now() - startedAt)}: ${error}`
+    );
     return {
       ok: false,
       channel,
       status: response.status,
-      error:
-        typeof record.error === "string" && record.error !== ""
-          ? record.error
-          : `relay responded ${response.status}`,
+      error,
     };
   }
+  log(
+    `[agent-sdk-slack-relay-client] relay posted channel=${typeof record.channel === "string" ? record.channel : channel} automationUuid=${args.automationUuid} status=${String(response.status)} ts=${typeof record.ts === "string" ? record.ts : "<none>"} elapsedMs=${String(Date.now() - startedAt)}`
+  );
   return {
     ok: true,
     channel: typeof record.channel === "string" ? record.channel : channel,

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/internal/workspace-sync.ts

@@ -1,10 +1,10 @@
 /**
- * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
- * cloud-runtime turns read them from the store mount (the first cloud prompt
- * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
- * write store-root `workspace/<path>`. Local `serve`/`run` with
- * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
- * USER store.
+ * Sync workspace trees onto an Agent Store so cloud-runtime turns read
+ * them from the store mount. Authored `agent/sandbox/workspace/**` seeds
+ * land at store-root `workspace/<path>` (see `buildCloudWorkspaceSection`).
+ * Per-turn `workspaceFiles` land at `sessions/<sessionId>/workspace/<path>`
+ * (see `buildCloudSessionWorkspaceSection`). Personal-key local+cloud
+ * nests both under `agent-serve/<agent>/`.
  */
 
 import { readFile } from "node:fs/promises";
@@ -13,6 +13,15 @@ import { MEMORY_DIR_NAME } from "../memory.js";
 import type { SeedFile } from "../types.js";
 import { mirrorToStore, storeRelPath } from "./store-mirror.js";
 
+export type WorkspaceFileBody =
+  | string
+  | { encoding: "base64"; data: string; mimeType?: string };
+
+/** Path or encoding that can never land. Distinct from a store outage. */
+export class WorkspaceFileRefusal extends Error {
+  override readonly name = "WorkspaceFileRefusal";
+}
+
 /**
  * Mirror the seed tree onto the store at its authored relative paths and
  * delete keys no seed claims so redeploys drop removed files. Every seed
@@ -30,7 +39,7 @@ export async function syncWorkspaceToStore(args: {
   for (const seed of args.seedFiles) {
     desired.set(
       agentStoreKeys.workspaceFile(
-        seedRelPath(seed.relativePath),
+        workspaceRelPath(seed.relativePath),
         workspacePrefix
       ),
       await readFile(seed.sourcePath)
@@ -39,17 +48,80 @@ export async function syncWorkspaceToStore(args: {
   await mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
 }
 
+/**
+ * Replace the session workspace prefix with this turn's `workspaceFiles`.
+ * Keys the map does not claim are deleted so a later send cannot leave a
+ * stale `pr.json`. Every path validates before the store is touched.
+ * Returns the relative paths that landed, in send order.
+ */
+export async function syncSessionWorkspaceFiles(args: {
+  sink: FileSink;
+  files: Record<string, WorkspaceFileBody>;
+  workspacePrefix: string;
+}): Promise<string[]> {
+  const desired = new Map<string, Uint8Array>();
+  const relPaths: string[] = [];
+  for (const [relativePath, contents] of Object.entries(args.files)) {
+    const rel = workspaceRelPath(relativePath);
+    desired.set(
+      agentStoreKeys.workspaceFile(rel, args.workspacePrefix),
+      workspaceFileBytes(relativePath, contents)
+    );
+    relPaths.push(rel);
+  }
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired,
+  });
+  return relPaths;
+}
+
+/** Delete every key under the session workspace prefix. */
+export async function wipeSessionWorkspace(args: {
+  sink: FileSink;
+  workspacePrefix: string;
+}): Promise<void> {
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired: new Map(),
+  });
+}
+
 /**
  * Same reservation as local materialization's `resolveWorkspaceWritePath`:
- * `memory/` is the shared cross-session journal, so a seed under it fails
- * the sync exactly as it fails a local first turn.
+ * `memory/` is the shared cross-session journal, so a seed or send under it
+ * fails the sync exactly as it fails a local first turn.
  */
-function seedRelPath(relPath: string): string {
-  const rel = storeRelPath(relPath, "workspace file");
+function workspaceRelPath(relPath: string): string {
+  let rel: string;
+  try {
+    rel = storeRelPath(relPath, "workspace file");
+  } catch (error) {
+    throw new WorkspaceFileRefusal(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
-    throw new Error(
+    throw new WorkspaceFileRefusal(
       `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`
     );
   }
   return rel;
 }
+
+function workspaceFileBytes(
+  relativePath: string,
+  contents: WorkspaceFileBody
+): Uint8Array {
+  if (typeof contents === "string") {
+    return new TextEncoder().encode(contents);
+  }
+  if (contents.encoding === "base64") {
+    return new Uint8Array(Buffer.from(contents.data, "base64"));
+  }
+  throw new WorkspaceFileRefusal(
+    `Unsupported workspace file encoding for ${relativePath}`
+  );
+}

package/src/internal/workspace.ts

@@ -80,6 +80,26 @@ export function buildCloudWorkspaceSection(dir: string): string {
   ].join("\n");
 }
 
+/**
+ * Per-turn preamble for cloud `workspaceFiles` after they land on the
+ * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
+ * the sync did not land.
+ *
+ * Same shared Agent Store mount as authored seeds — the session path is
+ * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
+ */
+export function buildCloudSessionWorkspaceSection(
+  dir: string,
+  relPaths: readonly string[]
+): string {
+  const listed = relPaths.map((path) => `\`${path}\``).join(", ");
+  return [
+    "## Session workspace files",
+    "",
+    `This turn's workspace files live at \`${dir}\` on this machine (${listed}). Read them with your normal file tools. They sit on the same shared Agent Store mount as authored workspace seeds; the session directory is replaced on the next send for this session, and task sessions remove it when they finish.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;

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
@@ -1901,8 +1926,9 @@ export interface SessionRecord {
    */
   workspaceOverride?: string;
   /**
-   * One-shot files to write into the harness cwd before the next turn
-   * (see {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
+   * One-shot files for the next turn (see {@link SendMessageOptions.workspaceFiles}).
+   * Local turns write them into the harness cwd. Cloud turns sync them onto
+   * the session Agent Store prefix. Cleared after apply.
    */
   pendingWorkspaceFiles?: Record<
     string,
@@ -2087,12 +2113,12 @@ export interface SendMessageOptions {
    */
   workspaceDir?: string;
   /**
-   * Relative path → contents written into the session harness cwd after
-   * scaffold materialize and before the next turn. On create, queued for
-   * the first turn; on resume, replaces any pending files. Prefer this
-   * over {@link workspaceDir} when you only need to inject a few
-   * host-prepared files (skills/AGENTS.md still land in the normal
-   * session workspace). Values may be utf8 strings or
+   * Relative path → contents for the next turn. Local turns write them into
+   * the harness cwd after scaffold materialize. Cloud turns sync them onto
+   * the session Agent Store prefix instead of the VM working directory. On
+   * create, queued for the first turn; on resume, merged into any pending
+   * files. Prefer this over {@link workspaceDir} when you only need to
+   * inject a few host-prepared files. Values may be utf8 strings or
    * `{ encoding: "base64", data }` blobs (Slack attachments, binary docs).
    */
   workspaceFiles?: Record<
@@ -2520,6 +2546,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 +3155,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 +3312,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 +3364,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;

package/templates/grokbot-agents/README.md

@@ -0,0 +1,26 @@
+# Grok Bot agents
+
+Consults the Grok Bot agents you name. This agent stays in its own
+conversation and reports the reply.
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+`init` asks for the names shown in the Grok Bot app. Skip the prompt
+with `--var agents="Plan Keeper, Chief of Staff"`.
+
+## Run
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+In the playground, ask it to talk to one of the names you entered. A
+name outside the list is refused.
+
+## Edit
+
+- `agent/extensions/grokbot.ts`: who it may talk to
+- `agent/instructions.md`: when to consult them

package/templates/grokbot-agents/agent/agent.ts

@@ -0,0 +1,6 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  // Empty allowlist: only the mounted Grok Bot tools.
+  tools: [],
+});

package/templates/grokbot-agents/agent/extensions/grokbot.ts

@@ -0,0 +1,5 @@
+import cursorGrokBotAgents from "@cursor/july/extensions/cursor-grokbot-agents";
+
+export default cursorGrokBotAgents({
+  agents: ["Plan Keeper"],
+});

package/templates/grokbot-agents/agent/instructions.md

@@ -0,0 +1,7 @@
+# Grok Bot agents
+
+Consult the Grok Bot agents named in `agent/extensions/grokbot.ts`. Stay in this conversation and report the reply.
+
+When someone asks who you can talk to, call `grokbot__list`. Do not send a message.
+
+When the question belongs to one of those agents, use the consult skill. A name outside the list is refused.

package/templates/grokbot-agents/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/grokbot-agents/evals/grokbot-agents.eval.ts

@@ -0,0 +1,18 @@
+import { defineEval } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "list",
+      description: "Asked who it can talk to, it lists and does not send.",
+      async test(t) {
+        await t.send("Who can you talk to? List them. Do not message anyone.");
+        t.succeeded();
+        t.calledTool("grokbot__list");
+        t.notCalledTool("grokbot__ask");
+        t.notCalledTool("grokbot__interrupt");
+      },
+    },
+  ],
+});

package/templates/grokbot-agents/init.json

@@ -0,0 +1,18 @@
+{
+  "questions": [
+    {
+      "id": "agents",
+      "prompt": "Which Grok Bot agents may this agent talk to?",
+      "hint": "Comma-separated names, as shown in the Grok Bot app.",
+      "placeholder": "Plan Keeper, Chief of Staff"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/extensions/grokbot.ts",
+      "find": "[\"Plan Keeper\"]",
+      "answer": "agents",
+      "as": "json-array"
+    }
+  ]
+}

package/templates/grokbot-agents/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "grokbot-agents",
+  "private": true,
+  "type": "module",
+  "description": "Consults the Grok Bot agents you name.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/grokbot-agents/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}