@cursor/july 0.1.103 → 0.1.105

package/dist/docs/llms-full.txt

@@ -1089,6 +1089,387 @@ Continue with these pages:
 
 ---
 
+Source: /docs/design/filesystem.md
+
+# One FileSystem for every Agent SDK agent
+
+> **Status:** first implementation, this PR. `@cursor/july` only.
+> No Cursor SDK change.
+> **Audience:** Agent SDK maintainers.
+
+Every local turn binds a **FileSystem** and synthesizes native file
+tools from it. There is no "is there an override?" branch on the
+tool path. Authors pick the tree with `root`. Omit `root` and the
+tree is the host disk, through internal `localFileSystem`.
+
+```ts
+// Host disk. Relative paths resolve against the harness cwd.
+export default defineAgent({
+  name: "reviewer",
+});
+
+// Override. The model sees only this tree. Paths are posix `/`.
+export default defineAgent({
+  name: "notes",
+  root: tempFs({ "/notes.md": "hello" }),
+});
+```
+
+---
+
+## Names
+
+| Name | Kind | Meaning |
+| --- | --- | --- |
+| `FileSystem` | Type on `@cursor/july` | Path verbs. Authors provide this. |
+| `root` | Field on `defineAgent` | The FileSystem the agent runs on. Omit it and the root is the host disk. |
+
+No `root()` method and no public `Workspace` type.
+`local.workspaceDir` stays the harness cwd. `workspaceFiles` stays
+per-send seed files. Those names are not the path namespace.
+
+Do not pass `local.root` into `Agent.create`. The published SDK
+does not have that field.
+
+---
+
+## FileSystem
+
+```ts
+interface FileSystem {
+  list(prefix?: string): AsyncIterable<DirEntry>;
+  stat(path: string): Promise<FileInfo>;
+  glob(pattern: string, dir?: string): AsyncIterable<DirEntry>;
+  read(path: string): Promise<string | Uint8Array>;
+  grep(query: GrepQuery): AsyncIterable<GrepResult>;
+  write(path: string, contents: string): Promise<void>;
+  delete(path: string): Promise<void>;
+  search(query: SearchQuery): AsyncIterable<SearchResult>;
+}
+```
+
+Every method is required. A tree without an index yields nothing
+from `search`. Methods do not fall back to the host tree.
+Diagnostics are not a FileSystem verb.
+
+Path verbs take a path (and contents for `write`). Bags with two
+or more independent options (`grep`, `search`) take a
+named query object.
+
+`read` returns text as a string, or image bytes as a
+`Uint8Array` (`jpeg` / `png` / `gif` / `webp`). Native Read
+applies `offset` / `limit` and numbers lines on text. Images
+become a base64 image content part, the same shape the Cursor
+harness sends the model.
+
+FileSystem methods throw; they do not return a status envelope.
+`@cursor/july` does not export `FileSystemResult`.
+
+### Paths
+
+Authored `root` (`tempFs`, `unionFs`, `overlayFs`, `hostFs`, a custom tree) is one posix
+namespace rooted at `/`. Query paths and yielded paths are
+absolute (`/src/a.ts`). No trailing slash except `/`. `""`, `"/"`,
+and an omitted optional scope mean the root. Prefix tests are
+path-segment: `/agent` matches `/agent/skills`, not
+`/agent-tools`. `normalizeFsPath` resolves `..`. `/tmp` is
+reserved for turn-local scratch. See `/tmp` scratch.
+
+Host-default `localFileSystem` follows Cursor SDK natives:
+relative paths resolve against the harness cwd; absolute paths
+are used as-is. Yielded paths are host paths, not rewritten to
+`/`. `search` is empty (no host index).
+
+### Iterators
+
+Async iterators are already sorted. `unionFs` k-way merges them
+and does not re-sort a source.
+
+- `list` / `glob`: lexicographic by `path`. Paths are unique.
+- `grep`: by `path`, then `lineNumber` ascending. Keep every hit.
+- `search`: by `score` descending, then `path` ascending.
+
+A file is not under itself, so listing a file path is empty.
+Empty `list` is not "missing"; `stat` answers that.
+
+`glob(pattern, dir?)` matches relative to `dir`, not
+basename-anywhere (`*.ts` under `/src` is `/src/a.ts`, not
+`/src/nested/c.ts`).
+
+`grep` has no `output_mode` or `offset`. A slash-free `glob`
+(`*.ts`) matches the basename at any depth under `path`.
+`grep` / `search` take optional `maxResults` as predicate
+pushdown; implementations should stop after that many hits.
+Composers push the same cap to children and apply it again
+after the merge.
+
+Native-tool pagination (`head_limit`, `offset`, `output_mode`,
+`numResults`) stays on synthesized tools. Native `LS` is built
+from `list` + `stat`; there is no `ls` method.
+
+### Errors
+
+FileSystem methods throw `PathError`. `path` is the absolute
+posix path the error is about. Messages stay these contract
+strings so synthesized tools can show them as-is.
+
+- `list` / `stat` / `glob` must not throw for a missing path.
+  Missing is an empty iterator or `{ kind: "missing" }`.
+- `read` / `delete` missing file: `FileNotFoundError`
+  (`not found: ${path}`).
+- `write` has no `not found`. I/O uses the OS message or
+  `WriteFailedError` (`write failed: ${path}`). A read-only
+  mount uses `ReadOnlyMountError` (`read-only mount: ${path}`).
+- Synthesized StrReplace is `read` + exact replace + `write`.
+  Uniqueness failures throw `EditError` (`oldText is empty`,
+  `oldText and newText are exactly the same`, `The string to
+  replace was not found in the file`, and `The string to replace
+  was found multiple times in the file. Use replace_all to replace
+  all occurrences, or include more context to only edit one
+  occurrence.`). Write-back failures are `WriteFailedError`.
+- `grep` throws `InvalidGrepPatternError`
+  (`invalid grep pattern: ${pattern}`). A missing host search
+  root throws. A missing virtual path yields nothing.
+- `search` without an index is empty success.
+- `unionFs` with no mount throws `NoMountError`
+  (`no mount for path: ${path}`) on `read` / `write` /
+  `delete`. Walk verbs stay empty or missing.
+- `unionFs` catches `PathError` from a child and rethrows
+  `error.withPath(mountPrefix + childPath)`. Untyped `Error` still
+  gets a best-effort message rewrite.
+
+Invoke wraps FileSystem throws into the executor success / error
+envelope.
+
+### Write and StrReplace
+
+`write(path, contents)` creates or overwrites a file. Success is
+empty. Native Write maps `fileText` onto `contents` and prints
+`Wrote contents to ${path}`.
+
+StrReplace is not a FileSystem verb. The synthesized tool reads
+the file, applies an exact non-overlapping replace, and writes
+the result. It fails when `oldText` is empty, equals `newText`,
+is missing, or occurs more than once without `replaceAll`.
+Success is `{ occurrencesModified }`. Splice is literal; do not
+use `String.prototype.replace`. Native aliases (`old_string`,
+`new_string`, `replace_all`) map onto those fields at invoke
+time.
+
+---
+
+## Helpers
+
+| Helper | Role |
+| --- | --- |
+| `emptyFs()` | No files. Overlay leaf or missing catalog. Reads miss; writes are read-only. |
+| `tempFs(files)` | In-memory snapshot. Tests and fixtures. |
+| `unionFs({ "/repo": a, "/plans": b })` | Longest-prefix compose, path-segment match. Children are FileSystems rooted at `/`; `unionFs` strips the mount prefix on the way in and re-prefixes yields. List and glob use `unique` so an earlier mount shadows a later one. Grep and search keep every hit. Grep and search at `/` fan out to every child. |
+| `overlayFs([upper, lower])` | Same-root overlay. Earlier layers win. Read-only. A downed layer costs its own files, not the overlay — `stat` / `grep` / `search` only fail when no layer served. |
+| `hostFs(files, scope)` | `HostFilesApi` as a FileSystem rooted at `/`. Mount with `unionFs({ "/host": hostFs(files, scope) })`. `search` is empty (no index). Write without a cached etag is unconditional; after a successful read or write, write is CAS on that etag. |
+
+`localFileSystem({ cwd })` is the host-default handle. It is not
+exported from `@cursor/july`. Name helpers and `mergeSorted`
+stay private. `emptyFs`, `tempFs`, `unionFs`, `overlayFs`, `hostFs`, and
+the `PathError` classes (`FileNotFoundError`,
+`ReadOnlyMountError`, `NoMountError`, `InvalidGrepPatternError`,
+`WriteFailedError`, `EditError`,
+`DeleteNotSupportedError`) are the public helpers.
+
+---
+
+## Tool synthesis
+
+Local turns synthesize these natives from the bound FileSystem:
+`Read`, `LS`, `Grep`, `Glob`, `Write`, `StrReplace`, `Delete`,
+`SemanticSearch`. `list` + `stat` synthesize `LS`. `search`
+synthesizes `SemanticSearch`. `StrReplace` is `read` + exact
+replace + `write`. Other execute bodies call the matching
+FileSystem method.
+
+Authored `tools` can filter that set. `tools: ["read", "shell"]`
+on a host-default agent synthesizes `Read` only.
+`tools: ["edit"]` synthesizes `Write` and `StrReplace`.
+`tools: ["semSearch"]` synthesizes `SemanticSearch`.
+`tools: []` synthesizes nothing.
+
+Host-default does not synthesize `SemanticSearch`. Native
+`semSearch` stays on so the host index can run;
+`localFileSystem.search` is empty. Authored `root` synthesizes
+`SemanticSearch` from `FileSystem.search` and does not advertise
+native `semSearch`. `search` is not an allowlist alias, so an
+authored `search` tool is not treated as SemanticSearch.
+`ReadLints` is not a FileSystem verb. Authored
+`tools: ["readLints"]` fails closed so the host language service
+cannot run.
+
+Do not also ship `agent/tools/Read.ts` (and the other synthesized
+names). Discovery fails closed on that clash for host-default and
+authored `root`.
+
+A factory root re-resolves the handle before a turn. The session
+cache is the handle, not a tree snapshot. Unscoped `callTool`
+uses the invocation id and does not cache, so factories cannot
+share one tree across callers. A static `root` is the authored
+object on every session — Write / StrReplace / Delete /
+`workspaceFiles` are shared. Return a new handle from
+`(ctx) => …` when a session should have its own tree. A factory
+that returns the same object still shares.
+
+Per-send `workspaceFiles` write through the FileSystem.
+`memory/` is reserved (same as the host-default workspace
+symlink into durable agent memory) and is refused after
+normalize, including `./memory/x` and `foo/../memory/x`.
+Host-default `list` / `glob` / `grep` do not follow directory
+symlinks, including `memory/` — same as native LS/Glob/Grep.
+Exact-path `read` / `stat` still follow.
+
+Authored `root` skips session-directory materialize, git init,
+and host-cwd checks. First turns prepend `buildAgentsMdContent`
+and print `Workspace Path: /`. Host-default agents keep today's
+materialize path.
+
+---
+
+## Allowlist
+
+| `root` | `tools` | Model-facing harness |
+| --- | --- | --- |
+| omitted | omitted | The seven host-disk file tools (no synthesized `SemanticSearch`). Host shell / webSearch / sandbox / native `semSearch` stay. Host file natives are hidden with `disallowedTools: ["read","ls","grep","glob","edit","delete"]`. |
+| omitted | `["read", "shell"]` | Synthesized `Read` + SDK `shell` + `mcp`. |
+| omitted | `[]` | No synthesized file tools. |
+| set | omitted | All eight synthesized file tools (including `SemanticSearch`) + webSearch + webFetch + updateTodos + readTodos + `mcp`. Bind `/tmp` scratch. Not the host-default full catalog (no shell / sandbox / task / native semSearch). |
+| set | `["updateTodos"]` | All eight synthesized file tools + `updateTodos` + `mcp`. |
+| set | `["semSearch"]` | Synthesized `SemanticSearch` + `mcp`. Native host index stays off. |
+| set | `[]` | No synthesized file tools. Legal and empty. |
+| set | `["shell"]` / `["task"]` / `["readLints"]` | Fail closed. |
+| set | `["webSearch"]` / `["webFetch"]` | All eight synthesized file tools + the listed web tool + `mcp`. Bind `/tmp` scratch. |
+
+`mcp` is granted when any tools ride that path. File-family
+allowlist names are omitted from the SDK allowlist; the
+synthesized tools replace them.
+
+`local.sandbox` is Cursor's process sandbox around child
+processes on the host-default path. It is not a FileSystem.
+
+---
+
+## Fail closed
+
+| Combination | Result |
+| --- | --- |
+| `root` + `local.cwd` / `workspaceDir` / `sandbox` | Fail closed |
+| `root` + `runtime: "cloud"` or `"grokbot"` | Fail closed |
+| `root` + `tools` containing `"shell"` | Fail closed |
+| `root` + `tools` containing `"task"` | Fail closed. A child keeps the host toolset. Sharing `root` needs a Cursor SDK inherit, not an overridden Task. |
+| `root` + `tools` containing `"readLints"` | Fail closed. Diagnostics are not a FileSystem verb. |
+| `agent/tools/Read.ts` (etc.) | Fail closed on host-default and authored `root`. |
+
+---
+
+## `/tmp` scratch for webSearch and webFetch
+
+Native `WebSearch` and `WebFetch` stay native. They still scratch
+large output to `{harnessCwd}/agent-tools/{uuid}.txt` on the host
+disk. Under `root`, the turn composes
+`unionFs({ "/": authored, "/tmp": tempFs() })`, copies only the file
+the native tool wrote this turn, and drops that composed root at
+end of turn.
+
+### Why `/tmp`
+
+The FileSystem is the model's disk. Host `{cwd}/agent-tools/` is a
+harness path. Under `root`, the model never sees it.
+
+`/tmp` is the reserved scratch prefix. An authored `/tmp` is
+shadowed. Do not put durable files there. `{cwd}/agent-tools/` and
+`/tmp` are different namespaces.
+
+`/agent-tools` is not reserved. Prefix `/agent` does not cover
+`/agent-tools`. Those notes are path-prefix tests, not a mount.
+
+Process or VM death also loses `/tmp`. Same as POSIX `/tmp`. That
+is acceptable. Do not persist scratch across turns or process
+restarts.
+
+### Overlay
+
+| Piece | Rule |
+| --- | --- |
+| Native tool | Still searches and fetches. |
+| Bind | Per turn: `unionFs({ "/": authored, "/tmp": tempFs() })`. `/tmp` is a mount, not a FileSystem type. |
+| Session cache | Authored handle may stay cached. The composed root does not. |
+| Drop | End of turn. Next turn gets a new empty `/tmp`. |
+| Small results | Stay inline. No disk, no rewrite. |
+| Copy | Only a file the native tool wrote this turn under `{cwd}/agent-tools/`. |
+| Dest | `/tmp/{uuid}.txt`. Same uuid as the host file. |
+| Host file | Delete after copy. |
+| Other paths | Ignore. Do not copy from the result text at large. |
+
+Do not put that composed root on the session handle. A later turn
+must not read another turn's `/tmp`.
+
+### Result rewrite
+
+Keep the native tool descriptions. They do not mention spill.
+
+This package does not change the Cursor SDK. Native WebSearch /
+WebFetch results land in the AgentService conversation inside
+the local executor. That transcript is not rewritten here.
+
+What this package rewrites:
+
+| Surface | Overlay (`root` set) |
+| --- | --- |
+| `webSearch` / `webFetch` result | Host path and follow-up, in strings or structured fields (`output_location`). Other tools are untouched. |
+| Synthesized Read / Grep input | `{cwd}/agent-tools/{uuid}.txt` → `/tmp/{uuid}.txt` |
+
+| Field | Host path (`root` unset) | Overlay (`root` set) |
+| --- | --- | --- |
+| Path | `{cwd}/agent-tools/{uuid}.txt` | `/tmp/{uuid}.txt` |
+| Follow-up | Native text (today: shell / grep / `read_file`) | Read / Grep |
+
+Two modes, two paths. Do not invent a third.
+
+WebFetch proto has `output_location`. WebSearch only embeds the
+path in the chunk string. Rewrite whichever form the native tool
+used.
+
+The model follow path is Read / Grep on `/tmp/{uuid}.txt`,
+including when the model still holds the host path.
+
+### Out of scope here
+
+MCP `spillLargeMcpTextOutput` uses the same host `agent-tools`
+directory. The same overlay can cover it later. This section is
+webSearch and webFetch only.
+
+---
+
+## Live `root`
+
+When the tree depends on the conversation, pass a factory. The
+factory returns a handle. Agent SDK may reuse the object for the
+session. Reuse is not a snapshot of mount contents.
+
+```ts
+export default defineAgent({
+  name: "notes",
+  root: (ctx) => notesForSession(ctx.sessionId),
+});
+```
+
+```ts
+interface RootContext {
+  sessionId: string;
+  agentName?: string;
+  continuationKey?: string;
+  host?: { files: HostFilesApi; reminders?: ReminderHostApi };
+}
+```
+
+---
+
 Source: /docs/design/runtime-abstraction.md
 
 # Replacing `runtime: "local" | "cloud"` with a code interface
@@ -3966,6 +4347,11 @@ behavior. Reactions still default on; set `reactions: false` when the
 eyes emoji is noise. Descriptions are optional; defaults derive from
 `botName` or the check `context`.
 
+To match dashboard automations, set `detailsUrl(sessionId)`,
+`summaryLinkText: "View agent"`, and `outputTitle: "context"` so the
+check title is the check name, the summary includes `[View agent](…)`,
+and Details opens the session.
+
 A comment-only first wake has no head SHA, so the check waits for a
 PR or CI event. The banner still posts. A later turn on the same SHA
 creates a new check run; GitHub cannot reopen a completed run.
@@ -3986,6 +4372,99 @@ key. Handlers you author replace the matching defaults (same as
 
 ---
 
+Source: /docs/guides/grokbot-agents.md
+
+# Cursor Grok Bot agents
+
+The `cursor-grokbot-agents` extension lets an agent send a message to
+one of your Grok Bot agents and read the reply. The Grok Bot keeps its
+own conversation, memory, and tools. Your agent stays where it is and
+consults that bot the way you would in the Grok Bot app.
+
+This is different from moving this agent's turns onto a hosted Grok Bot.
+The extension keeps the agent where it is and lets it talk to *other*
+Grok Bot agents.
+
+## Mount it
+
+The extension ships with `@cursor/july`. Mount it with one file.
+
+```ts
+// agent/extensions/grokbot.ts
+import cursorGrokBotAgents from "@cursor/july/extensions/cursor-grokbot-agents";
+
+export default cursorGrokBotAgents({
+  agents: [
+    { name: "Plan Keeper", description: "Keeps or moves outdoor plans." },
+    { name: "Chief of Staff", description: "Routes work and tracks priorities." },
+  ],
+});
+```
+
+`agents` is the allowlist. List every Grok Bot the model may talk to;
+a name outside the list is refused. Calls run under the host's
+signed-in account (`agent-sdk login` or `CURSOR_API_KEY`). Keep
+approval on when you can't.
+
+Start from the [Grok Bot agents template](/docs/templates/grokbot-agents.md)
+when you want a project that already mounts this.
+
+## What the agent can do
+
+With the extension mounted, the agent can consult a Grok Bot and stay
+in its own conversation:
+
+- **Ask.** Send a self-contained message to a Grok Bot by the name
+  shown in the Grok Bot app. The message lands in your conversation
+  with that bot. The tool waits for the bot's reply.
+- **Keep waiting.** A long turn returns `status: "running"`. Call check
+  with the same name to read what arrived since the last look.
+- **Stop a turn.** Interrupt the bot's current work. The conversation
+  stays; a later ask continues it.
+- **See who you can talk to.** List the configured bots and the ones
+  this caller has already asked. Add a name to `agents` when you want
+  the model to reach another bot.
+
+A skill teaches the model when to bring a Grok Bot in, how to write a
+message the bot can act on alone, and how to wait or interrupt. The
+reply is what the Grok Bot sent to the person. If a turn finishes with
+no reply, the bot sent nothing; ask again with a clearer request, or
+open the bot in the Grok Bot app.
+
+The tools reach Grok Bot agents on the signed-in account. A bot another
+user owns is out of reach. That separation is only as fine as your
+host's auth; a shared bearer token or `--allow-anonymous` makes every
+caller one principal, so use
+[authored auth](/docs/reference/channels.md#auth-policies) when callers
+need their own.
+
+## Configure it
+
+| Option | What it controls |
+| --- | --- |
+| `agents` | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
+| `needsApproval` | Park asks for a [human decision](/docs/guides/human-in-the-loop.md). Defaults to `true` when no `agents` are configured, `false` otherwise. |
+| `apiKey` | A Cursor API key to call with instead of the host's own. |
+
+## Adjust it
+
+To take a capability away, such as interrupting a turn, mount as a
+directory and disable that tool; see
+[overlays](/docs/reference/extensions.md#adjust-a-mounted-extension).
+
+## What's next
+
+Continue with these pages:
+
+- [Grok Bot agents template](/docs/templates/grokbot-agents.md): scaffold
+  an agent that already mounts this
+- [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
+  overrides work
+- [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): where parked
+  asks get approved
+
+---
+
 Source: /docs/guides/human-in-the-loop.md
 
 # Human-in-the-loop approvals
@@ -5399,10 +5878,11 @@ npx @cursor/july docs
 | Building a new agent with Cursor | [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) |
 | Turning a Cursor Automation into a project | [Convert a Cursor Automation](/docs/guides/convert-automation.md) |
 | Wiring an agent to Slack | [Slack guide](/docs/guides/slack.md) |
-| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
+| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Grok Bot agents](/docs/templates/grokbot-agents.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
 | Wiring an agent to GitHub webhooks | [GitHub guide](/docs/guides/github.md) |
 | Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
 | Handing coding work to Cursor cloud agents | [Cursor cloud agents](/docs/guides/cloud-agents.md) |
+| Talking to your Grok Bot agents | [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md) |
 | Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
 | Making an existing agent measurably better | [Evals](/docs/evals.md), then [Hillclimbing](/docs/hillclimbing.md) |
 | Comparing variants on live traffic | [Live A/B metrics](/docs/ab.md) |
@@ -5426,6 +5906,8 @@ npx @cursor/july docs
 
 - [Record a walkthrough from a collected PR](/docs/templates/demo.md): host
   collects the PR, the model records, then comments.
+- [Talk to your Grok Bot agents](/docs/templates/grokbot-agents.md): name
+  the bots, then consult them from this agent's own conversation.
 - [Keep a code wiki current after merge](/docs/templates/code-wiki.md):
   update in-repo `wiki/` pages when a pull request merges.
 - [Keep AGENTS.md current from last week's work](/docs/templates/agents-md.md):
@@ -5469,6 +5951,8 @@ npx @cursor/july docs
   server; agents can delegate to each other.
 - [Cursor cloud agents](/docs/guides/cloud-agents.md): let the agent launch
   and steer cloud agents through the `cursor-cloud-agents` extension.
+- [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): let the agent
+  talk to Grok Bot agents through the `cursor-grokbot-agents` extension.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
   tool traces to an OTLP collector you run.
 
@@ -6496,6 +6980,26 @@ rather than dropping events. An empty `deploySourceUris` list mounts
 the channel but starts no pull, so an env-configured agent stays inert
 until its deploy sources are set.
 
+**Change Monitors** (`@cursor/july/channels/change-monitors`): Change
+Monitor Checkpoint events. The channel publishes Factory
+`checkpoint.created` for every Checkpoint create. The agent filters the
+result (for example to the `issues` arm). The payload contains the
+full Checkpoint resource. This channel is scoped to Change Monitors,
+not generic Factory Checkpoints. There is no repository filter or
+resource filter. Author `agent/channels/change-monitors.ts` with
+`changeMonitorsChannel()`. It uses the host credential. The v1 omitted
+continuation is `none/v1`. A v2 agent defaults to
+`change_monitors.checkpoint/v2`, which keys the session as
+`cont:change_monitors:{checkpointName}`.
+
+**Issues** (`@cursor/july/channels/issues`): Factory issue events.
+The channel publishes `issue.created` for every Issue create. The
+agent filters if it needs a subset. The payload contains the full
+Issue resource. There is no repository filter or resource filter.
+Author `agent/channels/issues.ts` with `issuesChannel()`. It uses the
+host credential. The v1 omitted continuation is `none/v1`. A v2 agent
+defaults to `issues.issue/v2`, which keys the session by issue name.
+
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.
 
@@ -6932,6 +7436,7 @@ non-zero when the reconstructed trajectory failed.
 ```bash
 agent-sdk init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
 agent-sdk init ./my-demo --template demo              # record a PR walkthrough
+agent-sdk init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
 agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
 agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
 agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
@@ -6953,7 +7458,7 @@ agent-sdk init                     # no directory: print the setup guide
 Templates may ship `init.json`. On a TTY, `init` asks those questions
 before writing files. `code-wiki`, `pr-autofixer`, `security-help`, and
 `agents-md` ask for GitHub repos. `agents-md` also asks for Slack
-channels. Repeat
+channels. `grokbot-agents` asks for Grok Bot names. Repeat
 `--var id=value` to answer without a prompt.
 `--json` and non-TTY hosts skip the interview unless `--var` is set.
 
@@ -8058,6 +8563,8 @@ Continue with these pages:
 
 - [Cursor cloud agents](/docs/guides/cloud-agents.md): the extension that
   lets an agent launch and steer cloud agents
+- [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): the extension
+  that lets an agent talk to Grok Bot agents
 - [Tools](/docs/reference/tools.md): the tool contract extensions contribute to
 - [Skills](/docs/reference/skills.md): the skill forms an extension can carry
 - [Project layout](/docs/reference/project-layout.md): where `agent/extensions/` sits
@@ -11543,6 +12050,59 @@ Playground and `/queue/pr` need the alias token. GitHub label and
 
 ---
 
+Source: /docs/templates/grokbot-agents.md
+
+# Talk to your Grok Bot agents
+
+This agent sends a message to a Grok Bot you already use and reads the
+reply. The Grok Bot keeps its conversation. This agent stays where it
+is.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+`init` asks for the names shown in the Grok Bot app. Every name is an
+allowlist entry. Pass `--var agents="Plan Keeper, Chief of Staff"` to
+skip the prompt.
+
+The names land in `agent/extensions/grokbot.ts`. A name outside that
+list is refused.
+
+## Log in
+
+Asks run under the signed-in account.
+
+```bash
+cd grokbot
+agent-sdk login
+agent-sdk dev
+```
+
+In the playground, ask it to talk to one of the names you entered.
+
+## What to edit
+
+- `agent/extensions/grokbot.ts`: who it may talk to. Add `needsApproval: true` to park each ask.
+- `agent/instructions.md`: when to consult them
+
+See [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md) for the
+extension, and [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md)
+for where a parked ask gets approved.
+
+## Evals
+
+```bash
+agent-sdk eval
+```
+
+The smoke case asks who it can talk to. It must list the configured
+bots and not send a message.
+
+---
+
 Source: /docs/templates/pr-autofixer.md
 
 # Fix pull requests on a Cursor cloud VM

package/dist/docs/llms.txt

@@ -12,6 +12,7 @@
 - [Building agents with agents](/docs/building-with-agents.md): Use the built-in skills to have a coding agent create, verify, and improve your agent.
 - [How the Agent SDK works](/docs/concepts.md): Understand projects, sessions, event streams, channels, and runtimes in plain language.
 - [Deployment](/docs/deployment.md): Deploy the Agent SDK with Cursor-managed hosting or on infrastructure you control.
+- [One FileSystem for every Agent SDK agent](/docs/design/filesystem.md)
 - [Replacing `runtime: "local" | "cloud"` with a code interface](/docs/design/runtime-abstraction.md)
 - [Evals](/docs/evals.md): Define repeatable checks with defineEval, run them with agent-sdk eval, and use them as regression checks.
 - [Hillclimbing](/docs/hillclimbing.md): Improve an agent one measured round at a time, with the hillclimb skill running the loop with you.
@@ -26,6 +27,7 @@
 - [Keep AGENTS.md current from last week's work](/docs/templates/agents-md.md): Scaffold the agent, pick a repo and Slack channels, dispatch the weekly job, and deploy.
 - [Keep a code wiki current after merge](/docs/templates/code-wiki.md): Scaffold the agent, pick repos, replay a merged PR, and deploy.
 - [Record a walkthrough from a collected PR](/docs/templates/demo.md): Scaffold the agent, seed the PR on the host, record a walkthrough, and comment the result.
+- [Talk to your Grok Bot agents](/docs/templates/grokbot-agents.md): Scaffold the agent, name the Grok Bot agents it may reach, and consult them from its own conversation.
 - [Fix pull requests on a Cursor cloud VM](/docs/templates/pr-autofixer.md): Scaffold the agent, point it at your repos, and opt in to auto-fix a PR.
 - [Answer security questions in Slack](/docs/templates/security-help.md): Scaffold the agent, connect Slack, and answer from your skills. Paste a GitHub pull request for a first look.
 - [Review pull requests for exploitable bugs](/docs/templates/security-reviewer.md): Scaffold the agent, pick repos, replay a PR, and deploy.
@@ -37,6 +39,7 @@
 - [Cursor cloud agents](/docs/guides/cloud-agents.md): Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.
 - [Convert a Cursor Automation](/docs/guides/convert-automation.md): Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.
 - [GitHub](/docs/guides/github.md): Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.
+- [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval.
 - [Human-in-the-loop](/docs/guides/human-in-the-loop.md): Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): Push session, turn, and tool traces from the serve process to an OTLP collector you run.