@cursor/july 0.1.109 → 0.1.112

package/docs/concepts.md

@@ -1,171 +0,0 @@
----
-title: "How the Agent SDK works"
-description: "Understand projects, sessions, event streams, channels, and runtimes in plain language."
----
-
-# How the Agent SDK works
-
-An agent is a folder of instructions and capabilities. The Agent SDK
-discovers those files, runs conversations, and records what happened.
-
-## What happens when someone sends a message?
-
-Follow one message through the system:
-
-1. A channel receives the message from HTTP, Slack, GitHub, or another
-   webhook.
-2. The channel starts a session or continues an existing one.
-3. The runtime gives the model its instructions, tools, and workspace.
-4. The model replies and can call tools along the way.
-5. The Agent SDK appends every message and tool call to the session's
-   event stream.
-
-The channel is the front door. The runtime does the work. The event
-stream is the record you inspect later.
-
-## How do files become an agent?
-
-Each capability has a home in the project. The path tells
-the Agent SDK what to load. The filename becomes the capability's
-name. For example, `agent/tools/get_weather.ts` creates a tool named
-`get_weather`.
-
-| Path | What it is |
-| --- | --- |
-| `agent/agent.ts` | Model and runtime settings |
-| `agent/instructions.md` | The always-on system prompt |
-| `agent/tools/<name>.ts` | Typed actions the model can call |
-| `agent/skills/*` | Procedures loaded when needed |
-| `agent/mcp-connections/<name>.ts` | Tools from external MCP servers |
-| `agent/host-connections/<name>.ts` | Privileged MCP servers for host tools only |
-| `agent/channels/*.ts` | HTTP, Slack, and GitHub entry points |
-| `agent/result.ts` | Optional host `commit` on the final assistant text |
-| `evals/**/*.eval.ts` | Repeatable checks at the project root |
-
-Other folders add subagents, extensions, hooks, schedules, and workspace
-files. You don't register them elsewhere. Run `agent-sdk validate` to
-catch invalid files before serving the project.
-
-See [Project layout](./reference/project-layout.md) for the folder
-structure.
-
-## How does the Agent SDK identify a conversation?
-
-A session is one durable conversation. It has two identifiers:
-
-- **`continuationToken`** tells a channel which conversation to resume.
-  A Slack channel can use its thread ID. A GitHub channel can use the
-  pull request. The built-in HTTP API returns an opaque token and
-  rotates it after each accepted follow-up.
-- **`sessionId`** identifies the stored session. Use it to stream
-  events, inspect the session, resolve approvals, or bind a tool call to
-  the session.
-
-Use the continuation token to keep talking. Use the session ID to
-observe or manage the conversation.
-
-## How do I see what an agent did?
-
-Each session records an append-only event stream. It includes:
-
-- Messages and streamed text
-- Requested tool calls and their results
-- Approval requests and decisions
-- Turn completion and token usage
-
-Sessions and their event streams survive server restarts. The
-playground renders the stream. [Evals](./evals.md) assert against it.
-The `agent-sdk trajectory` command turns a saved stream into a short
-summary.
-
-When a run surprises you, inspect its event stream first. See
-[Sessions and streaming](./reference/sessions.md) for the event
-vocabulary.
-
-## What does a channel control?
-
-A channel connects the agent to a surface such as HTTP, Slack, GitHub,
-or a custom webhook. It controls:
-
-- Routes and input schemas
-- Authentication
-- Conversation identity
-- How replies return to the user
-
-The built-in HTTP session API is always available. Custom routes accept
-loopback callers by default. Add an auth policy before sharing them over
-a network.
-
-Channels should also prepare deterministic input for the model. For
-example, a GitHub channel can fetch the pull request, collect the diff,
-and seed the workspace before the turn starts. The model can then focus
-on the review instead of gathering files.
-
-See [Channels](./reference/channels.md) for route and authentication
-details.
-
-## Where does a turn run?
-
-Choose a runtime in `agent/agent.ts`:
-
-| | Local (default) | Cloud |
-| --- | --- | --- |
-| Turn runs on | The server host | A Cursor cloud agent |
-| Server tools | Supported | Supported when the server has `--public-url` or `--cloud-tools-url`; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them. |
-| Approvals (`needsApproval`) | Supported | Not supported (local runtime only) |
-| Agent tool scripts | Supported | Supported |
-| Skills | Added to the session workspace | Available automatically |
-| Seeded files | Added to the session workspace | Available in a shared directory the first prompt names |
-| Repository | You provide it | The cloud agent checks it out |
-
-Use the local runtime when the host has the tools and files the agent
-needs. Use the cloud runtime when each turn needs an isolated repository
-checkout. `agent-sdk validate` warns when a cloud agent uses a
-local-only capability.
-
-## What files can a local session access?
-
-Each local session gets its own workspace. The Agent SDK writes the
-instructions as `AGENTS.md`, installs authored skills, copies sandbox
-files, and adds agent tool scripts.
-
-The workspace is a real Cursor project. It can inherit `AGENTS.md` and
-`.cursor` settings from parent directories. Nested git checkouts default
-`local.cwd` to a per-project cache directory under `~/.cache`. Point
-`cwd` at a checkout only when the agent should inherit that tree. `run`
-and `eval` already use a temporary state root.
-
-Session files live under `--state-root`. See
-[Sessions](./reference/sessions.md#where-does-the-agent-sdk-store-session-data)
-for the layout.
-
-## How can one agent call another?
-
-Every mounted agent also serves MCP at `/<slug>/v1/mcp`. Another agent
-or MCP client can use `ask`, `check`, and `call_tool` to delegate work.
-A peer MCP connection such as
-`defineConnection({ agent: "weather-agent" })` adds those tools to the
-calling agent.
-
-See [Agent-to-agent](./guides/agent-to-agent.md) for a complete example.
-
-## Which rules prevent common setup problems?
-
-- Use Node 22.13 or newer. Bun isn't supported.
-- Put evals under the project-root `evals/` directory, not
-  `agent/evals/`.
-- Run a TypeScript check before shipping. `validate` and `run` execute
-  TypeScript but don't type-check it.
-- Return JSON-shaped values from tool `execute` functions.
-- Keep local session workspaces away from parent rules you don't want
-  the agent to inherit.
-- Sign in or set `CURSOR_API_KEY` before starting a model turn.
-  Discovery, validation, direct tool calls, and server startup work
-  without a credential.
-
-## Related
-
-- [Quickstart](./quickstart.md)
-- [Project layout](./reference/project-layout.md)
-- [Sessions and streaming](./reference/sessions.md)
-- [Channels](./reference/channels.md)

package/docs/design/filesystem.md

@@ -1,376 +0,0 @@
-# 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 };
-}
-```