@cursor/july 0.1.97 → 0.1.100

package/dist/docs/llms-full.txt

@@ -336,7 +336,7 @@ Continue with these pages:
   `ab.assigned` event and durable log
 - [Playground](/docs/reference/playground.md): the A/Bs tab
 - [HTTP API](/docs/reference/http-api.md): `GET /v1/abs`
-- [Live A/B metrics skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/SKILL.md): have a coding agent
+- [Live A/B metrics skill](/docs/skills/ab.md): have a coding agent
   wire an experiment
 
 ---
@@ -367,7 +367,7 @@ and verify the result without reading terminal prose.
 ## How do I create an agent with the built-in skill?
 
 Have the coding agent read
-[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) and
+[`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md) and
 follow it.
 
 The skill asks about your agent's purpose, runtime, model, channels, MCP
@@ -386,18 +386,20 @@ the first end-to-end turn works.
 
 ## Which built-in skill should I use?
 
-The package ships task-specific guides under [`skills/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/skills/):
+The package ships task-specific guides under [`skills/`](/docs/skills/index.md):
 
 | What you want to do | Skill |
 | --- | --- |
-| Understand the project layout and runtimes | [`framework-map`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/framework-map/SKILL.md) |
-| Create and verify a new agent | [`create-agent`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) |
-| Write fixtures and regression checks | [`evals`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) |
-| Live A/B metrics on traffic (`defineAB`) | [`ab`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/SKILL.md) |
-| Improve an agent against fixed inputs | [`hillclimb`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md) |
-| Add GitHub webhooks and replay events | [`github`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md) |
-| Connect an agent to Slack | [`setup-slack`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md) |
-| Diagnose a local run | [`debug`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+| Understand the project layout and runtimes | [`framework-map`](/docs/skills/framework-map.md) |
+| Create and verify a new agent | [`create-agent`](/docs/skills/create-agent.md) |
+| Write fixtures and regression checks | [`evals`](/docs/skills/evals.md) |
+| Live A/B metrics on traffic (`defineAB`) | [`ab`](/docs/skills/ab.md) |
+| Export OpenTelemetry traces | [`otel`](/docs/skills/otel.md) |
+| Improve an agent against fixed inputs | [`hillclimb`](/docs/skills/hillclimb.md) |
+| Add GitHub webhooks and replay events | [`github`](/docs/skills/github.md) |
+| Connect an agent to Slack | [`setup-slack`](/docs/skills/setup-slack.md) |
+| Authorize host MCP OAuth | [`mcp-auth`](/docs/skills/mcp-auth.md) |
+| Diagnose a local run | [`debug`](/docs/skills/debug.md) |
 
 Point your coding agent at the matching `SKILL.md`. The guide contains
 the workflow, commands, and common mistakes for that task.
@@ -450,7 +452,7 @@ smoke turn passes, give the hillclimb skill:
    evals that must stay unchanged
 
 Have the coding agent read
-[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md). It measures
+[`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md). It measures
 the current run, proposes one change, remeasures the same fixtures, and
 adds an eval for each kept improvement.
 
@@ -458,6 +460,7 @@ adds an eval for each kept improvement.
 
 - [Create your first agent](/docs/quickstart.md)
 - [Scaffold an agent with Cursor](/docs/scaffolding-agents.md)
+- [Coding-agent skills](/docs/skills/index.md)
 - [Evals](/docs/evals.md)
 - [Hillclimbing](/docs/hillclimbing.md)
 - [CLI reference](/docs/reference/cli.md)
@@ -1088,6 +1091,1768 @@ Continue with these pages:
 
 ---
 
+Source: /docs/design/runtime-abstraction.md
+
+# Replacing `runtime: "local" | "cloud"` with a code interface
+
+> **Status:** design proposal for review. No product code in this PR.
+> Implementation is split across later PRs (see §8). Do not start those
+> until this document has been reviewed.
+> **Audience:** Agent SDK and cursor-sdk maintainers; change-monitor as the
+> first consumer that is already faking a third runtime.
+> **Companions:** [cloud-runtime.md](/docs/guides/cloud-runtime.md) (today's
+> user-facing contract),
+> [factory/change-monitor/docs/tools.md](https://github.com/cursor/cursor/blob/main/factory/change-monitor/docs/tools.md)
+> (why change-monitor is pinned to local),
+> [factory/change-monitor/docs/computer-use.md](https://github.com/cursor/cursor/blob/main/factory/change-monitor/docs/computer-use.md)
+> (why a cloud VM as the *workspace* is not `runtime: "cloud"`).
+> **Checked against:** `@cursor/july` (`packages/agent-serve`) and
+> `@cursor/sdk` (`packages/cursor-sdk`) on `origin/main` as of 2026-08-31.
+
+## Goals
+
+1. **Stay compatible with agents that already ship.**
+   The current `defineAgent` / `AgentOptions` shape keeps
+   working: string `runtime`, sibling `local`, sibling
+   `cloud`. Existing files do not need a rewrite.
+   Constructors are additive (`localRuntime(opts)` takes
+   today's `AgentLocalOptions`). The old fields are
+   **deprecated and still supported** — JSDoc `@deprecated`
+   plus published-docs notes — not removed in Phases 1–4.
+
+2. **Default to `localRuntime()`.**
+   That is today's default and the one developers mean when
+   they omit `runtime`: local loop, host workspace, full
+   harness toolset. `defineAgent({})` and
+   `defineAgent({ runtime: "local" })` both become
+   `localRuntime()`.
+
+3. **Refuse incoherent pairs at discovery.**
+   The string let authors write `runtime: "cloud"` next to
+   `local: { sandbox, cwd, … }`, or `tools` on a cloud
+   agent, and only some of those failed. `Runtime` is a
+   closed union. `workspace` exists only on the local arm,
+   so `cloudRuntime` cannot take one. `virtualRuntime`
+   refuses `send({ runtime: cloudRuntime(...) })`.
+   Combinations an arm cannot honor are errors, not
+   ignored fields.
+
+4. **Replace the enum with an extensible interface.**
+   External users of `@cursor/july` / `@cursor/sdk` should
+   be able to bring their own workspace (a `FileSystem`, a test
+   map, a remote machine mount) without waiting for a new
+   string value. `Workspace` is that interface.
+   Do not grow `"local" | "cloud" | "virtual" | …`.
+
+The Agent SDK exposes execution as a string on `defineAgent`:
+
+```ts
+runtime?: "local" | "cloud" | "grokbot";
+```
+
+`"local"` and `"cloud"` look like two places the same agent can run.
+They are not. The string selects a **loop backend**, a **workspace**, and
+an **artifact-delivery path** at once, and it already has a third value
+(`"grokbot"`) that fits neither name. Change-monitor then takes
+`"local"` and hollows it out: native shell off, native `read`/`grep`/
+`glob`/`ls` replaced by server tools over a virtual filesystem. That is
+a virtual workspace on the local loop, forced to claim it is local
+because there is no other legal value.
+
+This document replaces the string with a closed `Runtime` union.
+The local arm carries a **workspace**. Cloud and grokbot do not.
+The workspace is one object whose optional methods (`read`,
+`ls`, `shell`, …) are the capabilities. Presence enables the
+matching tool. All methods share one path namespace.
+`workspace` exists only on the local arm, so `cloudRuntime`
+cannot take one.
+
+The first implementation cut is native redirection in Cursor SDK
+(`AgentOptions.local.workspace` rebound through local-exec). Agent
+SDK then authors that workspace as `virtualRuntime(fs)`.
+
+Lookalike server tools are not good enough. Change-monitor's
+`read` is an Agent SDK server tool, which the local harness
+exposes as MCP (`custom-user-tools`). The model gets
+`GetMcpTools` / `CallMcpTool`, not a builtin `read`. That is
+the bug. Copying native schemas does not fix the tool the
+model is offered. The SDK change exists so the model calls
+harness `read` against the injected workspace.
+
+---
+
+## 1. Chosen abstraction
+
+```ts
+/**
+ * Native tool args, open for fields the harness adds later.
+ * Known keys match the model-facing input schema. Extra keys
+ * are forwarded, not stripped.
+ */
+type NativeArgs<T> = T & { [key: string]: unknown };
+
+/**
+ * Path-namespace verbs. Method names match `@cursor/sdk`
+ * `ToolName`s (`read`, `semSearch`, `readLints`). The model
+ * sees the harness names (`Read`, `SemanticSearch`,
+ * `ReadLints`). `write` is the exception: the model tool is
+ * `Write`, but proto folded it into `edit_tool_call` — there
+ * is no public `tools: ["write"]`. Args and results are those
+ * tools' input/output schemas. `@cursor/sdk` owns this type.
+ */
+interface FileSystem {
+  ls?(args: NativeArgs<LsArgs>): Promise<LsResult>;
+  glob?(args: NativeArgs<GlobArgs>): Promise<GlobResult>;
+  read?(args: NativeArgs<ReadArgs>): Promise<ReadResult>;
+  grep?(args: NativeArgs<GrepArgs>): Promise<GrepResult>;
+  /** Native Write tool: create or overwrite a whole file. */
+  write?(args: NativeArgs<WriteArgs>): Promise<WriteResult>;
+  /** Native Edit tool: str-replace / multi-replace / apply-patch. */
+  edit?(args: NativeArgs<EditArgs>): Promise<EditResult>;
+  delete?(args: NativeArgs<DeleteArgs>): Promise<DeleteResult>;
+  semSearch?(args: NativeArgs<SemSearchArgs>): Promise<SemSearchResult>;
+  readLints?(args: NativeArgs<ReadLintsArgs>): Promise<ReadLintsResult>;
+}
+
+/**
+ * One namespace. File verbs and shell are optional methods —
+ * presence is the capability. They must share `root()`.
+ * Do not implement `read` against Origin and `shell` against
+ * host bash.
+ */
+interface Workspace extends FileSystem {
+  shell?(args: NativeArgs<ShellArgs>): Promise<ShellResult>;
+  root(): string;
+  brief?(ctx: WorkspaceBriefContext): string;
+}
+
+/**
+ * Closed union. `kind` is internal dispatch. Authors call
+ * constructors. Each constructor returns its arm, not
+ * `Runtime`, so `send({ runtime })` can require
+ * `CloudRuntime | LocalRuntime` and exclude grokbot.
+ * `workspace` exists only on the local arm.
+ */
+type LocalRuntime = { kind: "local"; workspace: Workspace };
+type CloudRuntime = { kind: "cloud"; cloud: AgentCloudOptions };
+type GrokbotRuntime = { kind: "grokbot" };
+type Runtime = LocalRuntime | CloudRuntime | GrokbotRuntime;
+
+function localRuntime(opts?: AgentLocalOptions): LocalRuntime {
+  return { kind: "local", workspace: localWorkspace(opts) };
+}
+
+/**
+ * Host-local with Cursor's local sandbox on. Same
+ * `kind: "local"` family as `localRuntime` / `virtualRuntime`.
+ * `cwd` / `workspaceDir` still configure the host tree.
+ * The workspace omits `shell`: this object cannot honor
+ * `sandboxOptions`. Host+sandbox turns keep the SDK's
+ * `LocalShellExecutor` and do not inject the workspace.
+ */
+function sandboxRuntime(
+  opts?: Omit<AgentLocalOptions, "sandbox">
+): LocalRuntime {
+  return localRuntime({ ...opts, sandbox: true });
+}
+
+/**
+ * Local arm + a virtual workspace. Default is empty: `root()`
+ * is `/`, no file/shell methods, no materialization, no
+ * skills mount. Pass a `FileSystem` (or an async per-session
+ * factory) to compose mounts. Authors pass a `FileSystem`,
+ * not a `Workspace` — the lift is not a knob.
+ */
+function virtualRuntime(
+  fs?: FileSystem | ((ctx: SessionWorkspaceContext) => Promise<FileSystem>)
+): LocalRuntime {
+  return { kind: "local", workspace: virtualWorkspace(fs) };
+}
+
+function cloudRuntime(cloud: AgentCloudOptions): CloudRuntime {
+  return { kind: "cloud", cloud };
+}
+
+function grokbotRuntime(): GrokbotRuntime {
+  return { kind: "grokbot" };
+}
+```
+
+`cwd` / `workspaceDir` are arguments to `localRuntime` and
+`sandboxRuntime`, same as `repos` on `cloudRuntime`. They
+configure the host tree `localWorkspace(opts)` wraps. They
+are not a `Workspace` and they are not on `virtualRuntime`.
+Prefer `sandboxRuntime()` when the harness should run
+sandboxed. `localRuntime({ sandbox: true })` and sibling
+`local.sandbox` stay as equivalent deprecated sugar.
+The injected object on the Cursor SDK is
+`AgentOptions.local.workspace`. Cursor SDK's existing
+`WorkspaceRuntime` is the session factory, not `Workspace`.
+Host+sandbox turns do not inject: a Workspace that claimed
+`shell` would replace `LocalShellExecutor`.
+
+Authoring:
+
+```ts
+export default defineAgent({
+  runtime: localRuntime(),
+});
+
+export default defineAgent({
+  runtime: sandboxRuntime({ workspaceDir: "/repo" }),
+});
+
+export default defineAgent({
+  runtime: virtualRuntime(async (ctx) =>
+    unionFs({
+      "/repo": originRepoFs(bindingFor(ctx)),
+      "/host": hostFilesFs(),
+      "/agent/skills": skillsFs(),
+    })
+  ),
+});
+
+export default defineAgent({
+  runtime: cloudRuntime({
+    repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
+  }),
+});
+```
+
+`localRuntime` / `sandboxRuntime` / `virtualRuntime` /
+`cloudRuntime` / `grokbotRuntime` are constructors over that
+union. They are not five implementations of one `fs()` +
+`shell()` pair. `sandboxRuntime` stays on the local arm.
+
+### Backward compatibility
+
+Today's fields stay on `defineAgent` and on Cursor
+`AgentOptions`. Constructors sit beside them. Nothing that
+compiles today is broken by Phase 2.
+
+```ts
+// Still valid. Deprecated. Same agent as localRuntime(opts).
+defineAgent({
+  runtime: "local",
+  local: { workspaceDir: "/repo", sandbox: true },
+});
+
+// Preferred.
+defineAgent({
+  runtime: sandboxRuntime({ workspaceDir: "/repo" }),
+});
+
+// Still valid. Deprecated. Same agent as cloudRuntime(opts).
+defineAgent({
+  runtime: "cloud",
+  cloud: { repos: [{ url: "https://github.com/org/repo", startingRef: "main" }] },
+});
+
+// Preferred.
+defineAgent({
+  runtime: cloudRuntime({
+    repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
+  }),
+});
+```
+
+| Today's field | Still does | Preferred |
+|---|---|---|
+| omit `runtime` / `runtime: "local"` | `localRuntime(agent.local)` | `runtime: localRuntime(opts)` |
+| `runtime: "cloud"` | `cloudRuntime(agent.cloud)` | `runtime: cloudRuntime(opts)` |
+| `runtime: "grokbot"` | `grokbotRuntime()` | `runtime: grokbotRuntime()` |
+| `local: { cwd, workspaceDir, sandbox }` | Host options when the string / omitted runtime is local | `localRuntime(opts)` or `sandboxRuntime(opts)`. Same `AgentLocalOptions`. |
+| `cloud: { repos, … }` | Payload for `runtime: "cloud"` | `cloudRuntime(opts)` |
+| `send({ cloud })` | This session becomes cloud; options merge over agent `cloud` | `send({ runtime: cloudRuntime(opts) })`. No merge. |
+| `send({ workspaceDir })` | Harness cwd for this local session | `send({ runtime: localRuntime({ workspaceDir }) })` |
+
+Runtime payloads live on constructors: `AgentLocalOptions`
+on `localRuntime`, `AgentCloudOptions` on `cloudRuntime`.
+These stay on `defineAgent` / `send` / `Agent.create`, not
+on `Runtime`: `model`, `tools`, `builtinTools`, `hosting`,
+`architecture`, `workspaceFiles`.
+
+`virtualRuntime` does not take `AgentLocalOptions`. There is
+no host cwd to point. `local.workspaceDir` / `sandbox` +
+`virtualRuntime` is still a discovery error.
+
+Cursor SDK stays on `AgentOptions.local` / `.cloud` for
+Phases 1–4. Presence of `cloud` still dispatches. Phase 1
+**adds** `local.workspace`. july `localRuntime(opts)` writes
+cwd / sandbox / workspaceDir into that bag. Constructors on
+`Agent.create` are a later SDK deprecation, after july has
+shipped the same types. Do not leave “`cloud` means cloud”
+as the forever SDK contract — just do not do that cut in
+Phase 1.
+
+Deprecation is documentation and JSDoc (`@deprecated` with
+the constructor equivalent). Do not delete the string or
+the sibling fields in Phases 1–4. Removal is a later
+window after Phase 4 has taught constructors. Subagents
+keep today's behavior, stored internally as `Runtime`
+(`G12`).
+
+If a constructor and a sibling disagree (`localRuntime(a)`
+plus `local: b`; `cloudRuntime(a)` plus `cloud: b`;
+`virtualRuntime` plus `local.workspaceDir`), fail closed.
+If only the deprecated form is present, accept it.
+
+`kind` is internal dispatch. Authors never write it; they
+call a constructor. `AgentRunner` stays on
+`StartServerInternalOptions` for replay and eval fakes. It
+is not a `Runtime` arm and not a `defineAgent` field.
+
+`virtualRuntime` is an empty local+virtual workspace until the
+author unions mounts in. `root()` is always `/`. Nothing is
+materialized onto a host scratch dir; every path is served
+lazily from the `FileSystem`. The framework does not inject
+skills, `/repo`, or a fake cwd. `skillsFs()` is a july
+helper that returns a `FileSystem` the application mounts if
+it wants skills on the workspace.
+
+Change-monitor's `search` (regex = `grep`, tags on
+`/issues`, reserved keyword / semantic) stays a consumer
+authored tool if they still want it. The framework does not
+grow a `search` method. `grep` and optional `semSearch`
+cover retrieval.
+
+`virtualWorkspace` is an internal lift: take the `FileSystem`,
+set `root()` to `/`, derive `brief()` from the mount table
+when there is one, omit `shell` unless a mount is
+shell-backed. Authors do not compose that lift, and they
+cannot pass `localWorkspace()` in.
+
+**Session factory.** `defineAgent` has no PR/SHA. A function
+argument runs **once per session**, not at discovery and not
+per turn. It is always async (`Promise<FileSystem>`). The
+returned `FileSystem` is reused for every turn and disposed
+with the session. Per-wake data (tenant plugin skills) is a
+lazy layer *inside* that filesystem, not a new Workspace. A
+stable tree (`memoryFs({ "/a.txt": "hi" })`) is passed
+directly and needs no factory.
+
+```ts
+interface SessionWorkspaceContext {
+  sessionId: string;
+  agentName?: string;
+  /** Channel continuation key when the session is addressable. */
+  continuationKey?: string;
+  /** Host services already on tool context. */
+  host?: { files: HostFilesApi; reminders?: ReminderHostApi };
+}
+```
+
+`sessionId` is the session when one exists. Unscoped
+`callTool` / `agent-sdk call` has no session row; the
+framework must not invent a shared default id that would
+collapse distinct callers onto one factory-backed store.
+
+### One workspace, one namespace
+
+File verbs and `shell` live on **`Workspace`**, not on `Runtime`.
+The local arm holds that object. Cloud and grokbot have no
+`workspace` field. Putting `read()` on `Runtime` re-bundles
+the string this document takes apart.
+
+`FileSystem` is the shared file-verb type (`@cursor/sdk`).
+`Workspace` adds `shell` / `root` / `brief`. July authors pass
+a `FileSystem`; helpers (`memoryFs`, `unionFs`, `skillsFs`)
+return one. That is not an attachable `Shell`: `shell` stays
+on `Workspace` so it cannot be pointed at a different tree
+than `read`. Change-monitor avoids the split today by having
+no shell. computer-use.md avoids it by deriving every
+`/workspace` verb from one `RemoteMachine.exec`.
+
+`unionFs(mounts)` composes FileSystems under absolute
+prefixes. Paths resolve by **longest prefix**. Method
+presence is the **union**: `write` is offered if any mount
+implements it. `shell` is not a FileSystem method and is
+not synthesized.
+
+Unifying the type does **not** enforce the coupling. Two methods
+on one object can still have two backends. The rule is semantic:
+
+**All Workspace methods share one path namespace, rooted at
+`root()`.** For `virtualRuntime`, that root is `/`.
+`ls({ path: "/repo" })` and `shell({ command: "ls /repo" })`
+see the same entries. Same tree, not the same formatter: the
+`ls` tool's ignore/dotfile rules and `shell({ command: "ls -la" })`
+may still render differently, as they do on a real machine.
+
+The framework cannot typecheck that. The public constructors keep
+the invariant by not taking a raw `Workspace`:
+
+```ts
+// Host. File verbs and shell wrap the same cwd.
+localRuntime(opts) → localWorkspace(opts)
+
+// Host + Cursor sandbox. Workspace omits shell.
+sandboxRuntime(opts) → localWorkspace({ ...opts, sandbox: true })
+
+// Empty virtual. `/`, no methods, no mounts, no skills.
+virtualRuntime()
+
+// Composed virtual. Application unions what it needs.
+virtualRuntime(unionFs({
+  "/repo": originRepoFs(binding),
+  "/host": hostFilesFs(),
+  "/agent/skills": skillsFs(),
+  "/workspace": cloudFs(remoteMachine),
+}))
+
+// Tests.
+virtualRuntime(memoryFs({ "/a.txt": "hi" }))
+```
+
+A shell-primary mount (`cloudFs`) is a `FileSystem`
+implementation, not a second runtime argument. You union it
+in. `shell` appears on the lifted Workspace only when that
+mount (or the union) is shell-backed — same tree as `ls` /
+`read` under `/workspace`. A TypeScript isolate (tools.md §8)
+is an authored `script` tool, not a `{ script: true }` flag
+on `virtualRuntime`.
+
+Do not put `shell` on a separate type the caller attaches later.
+Do not take `Workspace` as a public argument to `virtualRuntime`:
+that is how `virtualRuntime(localWorkspace())` happens.
+
+### Capability is method presence
+
+Every Workspace method above except `root` is optional.
+The framework exposes the matching tool iff the method is
+implemented. A missing method is a missing tool. This is
+change-monitor's optional-write rule ("optionality is earned")
+applied to the whole workspace.
+
+| Method present | Model-facing tool | Method absent |
+|---|---|---|
+| `read` | `Read` | not offered |
+| `ls` | `LS` | not offered |
+| `glob` | `Glob` | not offered |
+| `grep` | `Grep` | not offered |
+| `write` | `Write` | not offered |
+| `edit` | `StrReplace` | not offered |
+| `delete` | `Delete` | not offered |
+| `semSearch` | `SemanticSearch` | not offered |
+| `readLints` | `ReadLints` | not offered |
+| `shell` | `Shell` | not offered |
+
+Those are the latest/default harness names. Some prompt
+versions rename them (`read_file`, `search_replace`,
+`list_dir`, `codebase_search`, `run_terminal_cmd`). The
+binding does not invent a fourth name.
+
+`@cursor/sdk` `AgentOptions.tools` and stream `tool_call`
+events stay camelCase (`read`, `edit`, `semSearch`,
+`readLints`, `shell`, …). There is no public
+`tools: ["write"]`. `Write` and `StrReplace` both travel as
+proto `edit_tool_call`.
+
+`tools: ["edit"]` means the **envelope**, not
+`workspace.edit`. It is satisfied if `write` **or** `edit`
+is present. A write-only workspace with `tools: ["edit"]`
+is valid and offers `Write` only. `tools: ["edit"]` on a
+workspace with neither method is a discovery error. Method
+presence still decides which of `Write` / `StrReplace` are
+registered. A harness that already offers `MultiStrReplace`
+or `ApplyPatch` for that model keeps doing so when `edit`
+is present, and omits them when it is not.
+
+Cursor SDK binding: derive `AgentOptions.tools` from the
+presence set (`write` or `edit` contributes `edit` on the
+allowlist), then re-point those natives at the workspace.
+The model calls harness `Read`, not MCP `read` on
+`custom-user-tools`.
+
+**Presence means a function, not a stub.**
+`read() { throw new Error("unsupported") }` still enables `read`.
+Omit the method.
+
+**This gates the file/shell family only.**
+Do not grow Workspace to enumerate every harness builtin.
+`updateTodos` and `webSearch` do not share `root()`. Putting
+them on Workspace breaks the namespace rule and still does not
+make them work on `cloudRuntime` (that arm has no workspace
+field). Availability is not injectability.
+
+**`tools` may only narrow, fail-closed.**
+
+```
+workspaceCaps = methodsPresent(workspace)   // { read, ls, grep, … }
+fileRequested    = agent.tools?.filter(isFileOrShell)
+harnessRequested = agent.tools?.filter(isHarnessBuiltin)
+
+fileExposed =
+  fileRequested === undefined ? workspaceCaps : fileRequested
+
+harnessExposed =
+  agent.tools === undefined
+    ? (virtualRuntime ? ∅ : runtime.defaultHarnessTools)
+    : harnessRequested ∩ runtime.harnessTools
+```
+
+If `agent.tools` names `grep` and `workspace.grep` is missing,
+refuse at discovery — same posture as today's "restriction that
+silently does not apply." `tools: ["edit"]` is the exception:
+it names the envelope, so refuse only when both `write` and
+`edit` are missing. If it names `webSearch` and the loop
+does not have that builtin (grokbot), refuse the same way.
+If `agent.tools` is unset, the workspace *is* the file/shell
+allowlist. `"mcp"` is still granted when server tools or
+connections exist; it is transport, not a file verb and not a
+harness builtin.
+
+Host `localRuntime()` implements every file/shell method and
+keeps today's default harness set, so the toolset does not
+shrink. `virtualRuntime` with `read` + `ls` + `grep` + `glob`
+and no `shell` is change-monitor without a redundant
+`tools: ["read", …]` line. Harness builtins stay off that
+default; opt in:
+
+```ts
+defineAgent({
+  runtime: virtualRuntime(fs),
+  tools: ["read", "ls", "grep", "glob", "webSearch", "updateTodos"],
+});
+```
+
+`tools` is one allowlist. Listing only `["webSearch"]` turns
+file/shell natives off, even if the workspace implements them.
+
+`tools: []` is an empty allowlist, not "legacy suppress
+natives." `[] ∩ workspaceCaps = ∅`. Phase 2 must omit
+`tools` on `virtualRuntime` agents so workspace methods
+become the file/shell allowlist. List harness builtins
+only to opt those in. Change-monitor drops today's
+`tools: []` when it cuts over (Phase 3).
+
+### Three tool families
+
+| Family | Examples | Owner | How the model gets the native tool |
+|---|---|---|---|
+| **Workspace** | `read`, `ls`, `grep`, `glob`, `write`, `edit`, `delete`, `semSearch`, `readLints`, `shell` | Injected `Workspace` (`FileSystem` + `shell`) | Method presence → native tool. Args are that tool's schema. Omit the method if this workspace cannot honor it. |
+| **Harness** | `webSearch`, `webFetch`, `updateTodos`, `readTodos`, `askQuestion`, `await`, `generateImage` | The **Runtime arm's** Cursor harness | `defineAgent({ tools })`. Same builtin name. Do not put these on Workspace. |
+| **Transport / spawn** | `mcp`, `task` | Runtime arm | `mcp` when server tools or connections exist. `task` is subagents (`G12`). |
+
+**Framework server tools.** Agent SDK `builtinTools`
+  (`reminders`, …) are `execution: "server"`. Local
+  in-process; cloud via HTTP MCP; grokbot blocked. They are
+  not Cursor `ToolName`s and not Workspace methods.
+
+No `Harness` interface on `Runtime`. `webSearch` is the
+backend; there is nothing to inject. `updateTodos` is
+conversation state the local harness already keeps. A third
+object would re-bundle the string (Runtime arm + workspace +
+"the rest") and still could not be honored on cloud.
+
+If a later consumer needs a custom todo store or a stub
+`webSearch` in evals, add executor overrides on
+`AgentOptions.local` the same way Workspace landed — a rebind
+seam, not a constructor argument.
+
+### What each constructor actually offers
+
+`virtual` and `local` share the **local loop**. Harness
+builtins are the same implementations: backend `webSearch`,
+in-process todos. The workspace is what changes. Cloud is a
+different harness that already includes those builtins and
+cannot select them.
+
+| | `localRuntime()` | `virtualRuntime(fs)` | `cloudRuntime(opts)` | `grokbotRuntime()` |
+|---|---|---|---|---|
+| File/shell natives | Host workspace; `tools` narrows | Workspace methods only | VM workspace; cannot restrict | Box workspace; cannot restrict |
+| `webSearch` / `webFetch` | Default on; `tools` narrows | Off until listed in `tools` | On (VM default); `tools` refused | Fail closed if listed |
+| `updateTodos` / `readTodos` | Same | Off until listed | On (VM default); `tools` refused | Fail closed if listed |
+| `task` | Default on | Off until listed; children inherit parent workspace (`G12`) | On; cannot restrict | Blocked |
+| `mcp` | Granted for server tools / connections | Same (local loop) | Bridged HTTP MCP when configured | Blocked |
+| `edit` / `delete` / `semSearch` / `readLints` | Default on (`localWorkspace`) | Off unless the `FileSystem` implements the method | On (VM tree) | Box default |
+
+`sandboxRuntime()` is the same local loop as `localRuntime()`,
+with Cursor sandbox on. The workspace omits `shell`. Host+sandbox
+turns keep `LocalShellExecutor` and do not inject the workspace.
+
+One agent file cannot express the same *selected* toolset on
+all three constructors until the cloud API honors `tools`
+(non-goal, §10). `tools: ["webSearch", "updateTodos"]` on
+`cloudRuntime` is still a discovery error: we cannot prove the
+VM will offer only those, and we must not run unrestricted
+and pretend we selected.
+
+What *is* true without that API:
+
+- Local (including today's `tools: []` agents): list the
+  harness names. That already works. `virtualRuntime` does
+  not unlock `updateTodos` / `webSearch`; the allowlist does.
+- Cloud: those names are already on the VM. Authors who need
+  them on a cloud agent omit `tools` and accept the rest of
+  the VM workspace.
+- Do not special-case "harness-only `tools` + cloud" as
+  silently honored. That is the hybrid footgun with extra
+  steps.
+
+**Do not synthesize omitted verbs.**
+Change-monitor's current mounts require `grep` on every *mount* because
+it is derivable from `glob` + `read`. That is a mount-quality
+rule, not a Workspace-to-tool rule. If the workspace omits `grep`,
+the model does not get a generated grep that secretly scans via
+`read`. An implementation that has `glob` and `read` should
+usually implement `grep` (delegate to `scanGrep`); the framework
+does not invent it.
+
+**`write` and `edit` are two native tools, not one.**
+
+Str-replace `edit` cannot create a file (`oldText: ""`
+errors). The harness still offers a **Write** tool
+(`{ path, fileText }`) for create-or-overwrite. Apply-patch
+`edit` can create via `*** Add File:`. Proto `WriteToolCall`
+was folded into the `EditToolCall` envelope; the model-facing
+Write tool remains.
+
+Workspace keeps both methods, matching those two tools:
+
+- `write` — native Write schema (`path`, `fileText`, open for
+  later fields). Create or replace a whole file.
+- `edit` — native Edit schema (`path`, plus `oldText` /
+  `newText`, `edits[]`, or `patchContent`). Change an
+  existing file; apply-patch may add.
+- `grep` — native result kinds are `"content"` | `"files"` |
+  `"count"` (not `"files_with_matches"`).
+
+Presence of one does not synthesize the other. A
+`FileSystem` that implements `write` and omits `edit` offers
+Write only. That workspace may still list `tools: ["edit"]`
+(envelope). It must not register `StrReplace`.
+Change-monitor's CAS `write` / authored str-replace stay
+authored tools until the mount implements these native
+schemas. Do not keep a third write contract.
+
+**`edit`, `delete`, `semSearch`, `readLints` are Workspace
+methods.** They see `root()`. Optional: `localWorkspace()`
+implements what the host harness already has;
+`virtualWorkspace(fs)` omits a method until that
+`FileSystem` can honor it. The type includes them now. A
+tree that cannot index or lint simply leaves the method off.
+
+- `delete` — path verb. `DeleteExecutor` exists; Phase 1 adds
+  the override and fail-closed omission.
+- `edit` — same tree as `write`. Native schema stays native.
+  Phase 1 fail-closed-omits host `edit` when the method is
+  missing so a virtual tree cannot be patched on disk.
+  Implementing the virtual body can wait for a writable
+  mount (change-monitor Phase 3).
+- `semSearch` — native schema. Host walks a **codebase index**,
+  then `read`s snippets. A virtual `FileSystem` omits it
+  until that tree has an index. Do not leave host
+  `semSearch` registered against a virtual workspace. Do not
+  alias change-monitor's authored `search` (tags / regex)
+  onto this method.
+- `readLints` — `diagnosticsExecutor` (LSP against the tree).
+  Same presence rule. A virtual tree has no language service
+  unless a mount provides one.
+
+### Effect and approvals stay outside Workspace
+
+Defaults do not change. `localRuntime()` / no `workspace` is
+today's `LocalWriteExecutor` + `permissionsService` +
+pending-decision cards.
+
+Two planes already exist. Workspace implements neither.
+
+| Plane | What it is | Who configures it | Virtual |
+|---|---|---|---|
+| **Effect** (`read` / `write`) | Dry-run and trace: reads run, writes stub. Native file/shell verbs keep today's effects (`read`/`ls`/`grep`/`glob`/`semSearch`/`readLints` = read; `write`/`edit`/`delete`/`shell` = write). | Existing tool `effect` for authored tools. Natives keep harness defaults. | Same defaults. A Workspace method cannot relabel `edit` as read. |
+| **Approval policy** | Human-in-the-loop before an effectful call runs. | Today's Agent SDK / harness approval config. | Same policy. The adapter runs **after** the approval gate, not instead of `LocalWriteExecutor`. |
+
+```
+tool call → effect / dry-run → approval policy → Workspace method
+```
+
+Host path allowlists, `.cursorignore`, and worktree guards
+live on **`localWorkspace` only**. They key on host paths.
+Virtual paths (`/repo/…`) are a different namespace; wrapping
+them in `permissionsService.shouldBlockWrite` would block or
+prompt every virtual call. Mount policy (CAS, publish ladder)
+stays inside the `FileSystem`.
+
+Eval `memoryFs` uses the same gates. If the agent's approval
+policy is off (today's default for many local agents), no new
+cards appear.
+
+`@cursor/sdk` exports `FileSystem` and `Workspace`. July
+authors pass a `FileSystem` into `virtualRuntime`. Helpers
+return `FileSystem`. Do not add a `search` method: the regex
+arm is `grep`, `semSearch` is already on `FileSystem`,
+keyword has no implementation, and tags is an unproven
+change-monitor issues-mount feature. If they still want tag
+lookup, it stays an authored tool on their mounts.
+
+Phase 1 does not need virtual implementations of these four.
+It does need the omit path: when a workspace is set and the
+method is absent, the host executor is not registered.
+
+### Environment brief is not `Runtime.instructions()`
+
+The workspace owns facts the model must know — `root()`,
+mount table, "there is no checkout," grep dialect. Change-monitor
+currently writes those into `agent/instructions.md` because there
+is nowhere else to put them. Cloud already injects loop-owned
+prose the same way (`buildAgentsMdContent` prepends a server-tool
+MCP catalog and a memory-mount path).
+
+That is a real injection point. It is not
+`Runtime.instructions() -> string`.
+
+`defineAgent({ instructions })` / `instructions.md` is the
+agent's job: role, steering, what to publish. A method with the
+same name implies it replaces that file. Today's prompt is
+already layered, and the layers have different owners:
+
+| Layer | Owner | When / where |
+|---|---|---|
+| `instructions.md` | Agent author | Always; identity of the agent |
+| `## About you` | Framework | Folded into AGENTS.md / preamble |
+| Server-tool MCP catalog, "write the script if missing" | **Runtime arm / delivery** | Cloud first prompt; grokbot `createSession({ instructions })` |
+| `<agentkit_context>` (session, channel, time) | Framework | First user prompt only |
+| Harness `<user_info>` `Workspace Path` | **Workspace** (today: cwd) | Local harness, every turn |
+| Mount table, dialects, "no shell" | **Workspace** | Missing as an API; stuffed into instructions.md |
+
+A string on `Runtime` re-bundles those layers and cannot say
+which channel to use. Returning prose does not update harness
+`Workspace Path`. `virtualRuntime` sets `root()` to `/` and
+does not materialize a scratch cwd. `local.workspaceDir` +
+virtual is a discovery error. `root()` is the contract; if it
+disagrees with `brief()`, the model gets two maps.
+
+Ownership rules:
+
+1. **Agent instructions stay authored.** The framework never asks
+   a runtime to supply the agent's job description.
+2. **Workspace brief is an addendum.** Mount-table paragraphs move
+   here; "You write a monitoring plan for one PR" does not.
+3. **Arm-owned catalogs stay on the arm.** Cloud's
+   `agentsdk-tools` preamble and grokbot's composed blob are
+   delivery, not `Workspace.brief()`.
+4. **Brief is session-scoped.** Planner mounts depend on the
+   dispatcher's binding (repo, SHA, which mounts exist).
+   `brief(ctx)` runs when the session workspace is built.
+5. **Prefer structure over a blob.** `root()` is what
+   the harness honors. Do not grow `brief()` into a second
+   instructions.md.
+
+### What `shell` is allowed to be
+
+`shell` is "run a program, return stdout/stderr/exit." Language
+and isolation are implementation details. The namespace is not:
+`shell` must see the same tree as `ls` / `read`.
+
+| Implementation | Language | Isolation | How the tree stays one |
+|---|---|---|---|
+| Host | bash / zsh / cmd | Serve-host process, optional sandbox | Same cwd as file verbs |
+| Script isolate (tools.md §8) | TypeScript | Host-side isolate; only bound Workspace methods | `shell` *is* those methods |
+| Remote machine (computer-use.md) | bash on the pod | anyrun microVM, no host secrets | File verbs are commands over the same `shell` |
+
+A virtual workspace may omit `shell` (change-monitor today). The
+loop does not change.
+
+A TypeScript isolate and host bash are different trust classes.
+Do not overload one `shell` method for both. Omit `shell` and
+keep `script` as an authored tool (tools.md §8). A shell-backed
+mount (`cloudFs`) is the other `shell`. If those two ever
+need one method, add a `kind` then — not as a staged "v2."
+
+### What stays off `Runtime`
+
+- **Inference.** Local Connect client stays framework-owned.
+- **`AgentRunner`.** Internal `startServer` test/host seam.
+  Not a `Runtime` arm.
+- **MCP / OAuth / peer URLs.** Host capabilities, already on
+  `ctx.host` and connection files.
+- **Server tools / `builtinTools`.** Host-side,
+  `execution: "server"`. They are not workspace verbs.
+- **`ctx.host.files`.** Durable store. A workspace *may* mount it
+  (change-monitor `/host`); the store API itself is not FS.
+
+### Composition rules
+
+1. **`localRuntime(opts?)`** → `{ kind: "local", workspace: localWorkspace(opts) }`
+   (today). Sibling `local` is deprecated sugar for `opts`.
+   **`sandboxRuntime(opts?)`** is the named constructor for
+   host-local + Cursor sandbox: `localRuntime({ ...opts, sandbox: true })`.
+   The workspace omits `shell`. Host+sandbox turns do not
+   inject that workspace into the SDK.
+2. **`virtualRuntime(fs?)`** → local arm + that workspace.
+   Each implemented method exposes that tool. Authored
+   `execution: "server"` tools stay on the host. Effect and
+   approval policy wrap the tool call, then the Workspace
+   runs. `tools` may only narrow, fail-closed.
+   `local.workspaceDir` / `sandbox` + virtual is a discovery
+   error.
+3. **`cloudRuntime` / `grokbotRuntime` have no `workspace`
+   field.** Those arms own their tree. A machine API would
+   add a field on that arm later, not a sibling we then
+   refuse.
+4. **`tools` allowlist + cloud/grokbot** → same fail-closed
+   errors as today.
+5. **Per-send `runtime?: CloudRuntime | LocalRuntime`.**
+   Host-local + `cloudRuntime` → attach. Host-local +
+   `localRuntime(opts)` / `sandboxRuntime(opts)` → overlay
+   cwd / sandbox / workspaceDir. Cloud + `cloudRuntime` → replace the
+   session cloud payload (no merge). Virtual + either →
+   refuse. Cloud / grokbot + `localRuntime` → refuse.
+   Grokbot + `cloudRuntime` → refuse (today's throw).
+   `grokbotRuntime` is not in the field type. Deprecated
+   `send({ cloud })` / `send({ workspaceDir })` stay as
+   shims. `send({ runtime, cloud })` and
+   `send({ runtime, workspaceDir })` fail closed.
+6. **Delivery** is derived from the arm and, on local, which
+   workspace: host → materialize; virtual → no host
+   workspace, `Workspace Path` is `/`, skills only if the
+   author mounted `skillsFs()`; cloud → preamble + store;
+   grokbot → session instructions.
+
+---
+
+## 2. What the string actually selects
+
+`AgentRuntime` lives on the Agent SDK config
+(`packages/agent-serve/src/types.ts`). The Cursor SDK has **no**
+`runtime` field on `AgentOptions`. It routes on `options.cloud`
+(or a `bc-` agent id) in `createDefaultAgent` /
+`resumeDefaultAgent` (`packages/cursor-sdk/src/agent/platform.ts`).
+The Agent SDK string is a product-level selector that then builds
+different SDK option bags.
+
+There are already three values, plus a hybrid, plus a consumer
+that forges a fourth:
+
+| | Local loop | Cloud loop | Grok Bot loop | Change-monitor today |
+|---|---|---|---|---|
+| **Turn runner** | Cursor SDK local harness on the serve host (`sdk-runner.ts`) | Cursor cloud API (`POST /v1/agents`, SSE) | Hosted `/v0/grokbot` client (`grokbot/runner.ts`) | Local harness |
+| **Inference** | Backend `AgentService` via Connect; model from `defineAgent` | Coupled inside the cloud agent service; model optional | Hosted harness picks the model; `defineAgent.model` ignored | Same as local |
+| **Workspace (builtins)** | Host OS via `LocalResourceProvider` | Cloud VM; SDK is an event client only | The account's Sand box | Authored server tools over a consumer filesystem |
+| **`tools` allowlist** | Enforced (`x-cursor-agent-allowed-tools`) | `ConfigurationError` if set; discovery / hybrid turn fail closed | Fail closed at discovery | `tools: []` so natives never fire |
+| **Server tools** | SDK `customTools` in-process | HTTP MCP `agentsdk-tools` back to the host | Blocked at discovery | In-process (this is why they stay local) |
+| **Approvals** | Supported | Not supported | N/A | Supported |
+| **Instructions** | Host `AGENTS.md` (or inline if cwd is borrowed) | First-prompt preamble | `createSession({ instructions })` | Instructions + skills index; cwd is a fake `/repo` |
+| **Skills** | Materialized into `.cursor/skills/` | Synced to Agent Store | Warned: not on the box | Advertised in instructions, not harness files |
+| **Sandbox seeds** | Written into the session workspace | Ignored | Ignored | Unused (`tools: []`) |
+| **MCP** | Loopback / per-send auth | Bridged or forwarded; needs `--public-url` | Blocked | Used (sandbox stays off so MCP does not fail closed) |
+| **Subagents** | SDK `agents` | SDK `agents` | Blocked | Off (`tools: []` strands `task`) |
+| **`send({ runtime })`** | Host-local → attach or overlay; cloud → replace payload | Replace payload | Refused | Not used |
+
+The string is checked in roughly fifteen Agent SDK sites. The
+concentrated ones:
+
+- `discovery.ts` — compile-time capability errors/warnings per value.
+- `cloud-merge.ts` `resolveSessionRuntime` — per-session cloud attach
+  forces `"cloud"`; grokbot throws.
+- `session-engine.ts` `buildTurnRequest` — one function assembles
+  tools, customTools, MCP, instructions, skills sync, and the
+  fail-closed hybrid guards.
+- `sdk-runner.ts` `openAgent` — `cloud:` block vs local `cwd` /
+  `sandbox` / `tools`.
+- `runtime-dispatch-runner.ts` — grokbot vs everything else.
+
+There is no plugin registry. `StartServerInternalOptions.runner`
+can replace the whole `AgentRunner`, which is too coarse to inject
+a filesystem.
+
+---
+
+## 3. Change-monitor is already a virtual workspace
+
+Planner, executor, and curator all do the same thing
+(`factory/change-monitor/{planner,executor,curator}/agent/agent.ts`):
+
+```ts
+export default defineAgent({
+  runtime: "local",
+  tools: [],
+  local: {
+    workspaceDir: "/repo", // does not need to exist
+    sandbox: false,        // sandbox makes MCP fail closed
+  },
+});
+```
+
+Then `src/vfs/tools.ts` reimplements `ls` / `glob` / `read` /
+`grep` as server tools whose descriptions and parameter schemas
+are copied **verbatim** from the native harness
+(`tools.contract.test.ts` pins the equality). Bodies call
+`mountVfsForSession` and today's consumer filesystem type
+(they named it `VFS`; Phase 3 replaces it with `FileSystem`):
+
+```ts
+interface VFS {
+  list(dir: string): Promise<VFSEntry[]>;
+  glob(pattern: string, dir?: string): Promise<string[]>;
+  read(path: string): Promise<string>;
+  grep(query: GrepQuery): Promise<GrepResult>;
+  search(query: SearchQuery): Promise<GrepResult>;
+  write?(path: string, contents: string): Promise<void>;
+}
+```
+
+That type is **not** a july type. `search` (regex = `grep`,
+tags on issues, reserved keyword / semantic) stays theirs if
+they still want the authored tool. The framework cutover is
+`FileSystem` + native tools.
+
+Mounts (`src/vfs/session.ts`) compose into one namespace: `/repo`
+(Origin at a pinned SHA), `/host` (`ctx.host.files`), plus plans /
+issues / checkpoints / skills. The model thinks it has a
+filesystem. The serve host has no checkout and no shell.
+
+Two follow-on designs stay on this local-loop + virtual-workspace
+posture rather than flipping the string:
+
+- **Tool scripting** (tools.md §8, not implemented): a `script`
+  server tool that runs TypeScript against a capability-bounded
+  tool bridge. Authored tool, still under
+  `virtualRuntime(fs)`. Not a new loop.
+- **Computer use** (computer-use.md, not implemented): a
+  writable `/workspace` mount (`cloudFs`) whose file verbs are
+  commands on a lazily-provisioned anyrun microVM. Union it into
+  the same `FileSystem`. Explicitly **not** `runtime: "cloud"`: cloud
+  turns cannot restrict tools, cannot run server tools
+  in-process, and cannot park approvals.
+
+So "virtual" is one constructor with many filesystems. A third
+string value would repeat the original mistake.
+
+---
+
+## 4. Constraints the string hid
+
+### 4.1 Cloud is not a different workspace on the same loop
+
+A local turn: the serve host runs the agent loop, the backend
+runs inference, tools run against a workspace (host or injected).
+
+A cloud turn: the SDK is a REST + SSE client (`CloudApiClient`).
+`createAgent` / `createRun` take a prompt. Tool execution happens
+on the VM; the SDK surfaces `tool_call` events. There is no
+in-process `read` or `shell` to swap. The public cloud surface has
+no `Exec` RPC (computer-use.md Gap 1). Driving the VM by
+prompting it is "execution by persuasion" — rejected as an exec
+backend.
+
+`cloudRuntime` growing a `workspace` field would be either:
+
+1. **Lies** — methods that do not run, because that arm owns
+   the tree and the SDK cannot reach it, or
+2. **A new product** — a machine primitive (create / exec / read /
+   hibernate, no model attached) that does not exist on the
+   public API.
+
+Until (2) exists, `cloudRuntime` is a **Runtime arm that
+owns its tree**. It has no `workspace` field.
+
+### 4.2 Inference does not belong on `Runtime`
+
+Local already separates inference from tools:
+`AgentConnectClient` streams the model, `resources`
+(`ResourceAccessor`) execute side effects
+(`packages/cursor-sdk/src/agent/local-executor.ts`). Cloud and
+Grok Bot couple them inside a remote service.
+
+Putting `infer()` on `Runtime` would be true for local, false
+for cloud/grokbot, and unused by change-monitor. Keep inference
+off the workspace. Replay / eval fakes keep using
+`StartServerInternalOptions.runner`.
+
+### 4.3 Delivery is a third axis
+
+| Artifact | Local | Cloud | Grok Bot | Virtual |
+|---|---|---|---|---|
+| Instructions | `AGENTS.md` in cwd | First-prompt preamble | Session `instructions` | Authored instructions + optional `brief()` |
+| Skills | `.cursor/skills/` | Agent Store sync | Not on the box | Nothing unless the author mounts `skillsFs()` |
+| `execution: "agent"` scripts | Files in workspace | Prompt bodies | Prompt bodies | Banned without `shell` |
+| Sandbox seeds | Copied into cwd | Dropped | Dropped | Skip; put data in the `FileSystem` if the model should see it |
+| Workspace Path | Host cwd | VM | Box | `/` |
+
+`virtualRuntime` does not materialize a scratch dir and does
+not fake `/repo`. Everything is lazy from the `FileSystem`.
+Empty `virtualRuntime()` is a workspace at `/` with no methods.
+
+Skills are the sharp case. Authoring is one tree
+(`agent/skills/`). Discovery loads it the same way on every
+constructor. After that the pipes diverge. The model does
+not get the same catalog, the same load path, or the same
+ambient extras.
+
+| | How the catalog is advertised | Where `SKILL.md` bytes live | How the model loads the body | Ambient extras the author did not write |
+|---|---|---|---|---|
+| **`localRuntime()`** | Harness native catalog from `.cursor/skills/<name>/SKILL.md` in the session cwd (`materializeWorkspace`, rewritten every turn) | Those files on the host workspace | Harness skill loader; "Using {name}" | Project / user (`~/.cursor/skills`) / team / plugin / Cursor-managed layers if the cwd is a real checkout |
+| **`cloudRuntime()`** | Native store discovery (`--agent-store-skills-dir`) after `syncSkillsToStore` | Hosted: deployment store `skills/<name>/`. Local serve + personal key: USER store `agent-serve/<agent>/skills/`. Re-copied on every first cloud turn (the mount is writable; a once-per-process copy would let one session edit the definition) | Harness skill loader on the VM | Skills already in the cloud repo. If the store is unreachable or sync fails, **only** those — the turn still runs |
+| **`grokbotRuntime()`** | Discovery **warning** only: the box does not see authored skills | Nowhere on the box | It cannot | Whatever the hosted Grok Bot box already has. `GET /v1/info` still lists the agent's skills |
+| **`virtualRuntime`** | None by default. If the author mounts `skillsFs()`, they advertise (instructions index, `brief`, or a later catalog-path override) | Only on that mount, e.g. `/agent/skills/…` | Workspace `read` of the mount path | None. No host `.cursor/skills/` materialization |
+
+This is why delivery is derived from the **Runtime arm** and,
+on local, which workspace — not from `Workspace` alone:
+
+- local + host workspace → materialize `.cursor/skills/` (today).
+- local + virtual workspace → no host workspace. Skills exist
+  only if the author unions `skillsFs()` (or their own
+  mount) and advertises it. `read` hits `/`.
+- cloud → store sync. No cwd to write.
+- grokbot → warn. Do not pretend the box has them.
+
+Do not put `skills()` on `Workspace`. `skillsFs()` is a
+`FileSystem` the application may mount. The harness catalog
+is not pointed at a fake `/repo`.
+
+### 4.4 Capability gates stay fail-closed
+
+`tools` + cloud throws in the Cursor SDK
+(`assertNoCloudToolsRestriction`). The Agent SDK repeats the
+guard at discovery and again on hybrid turns
+(`session-engine.ts` ~2020). `advertiseTools` / per-session MCP
+auth are local-only for the same reason.
+
+If a workspace cannot honor an allowlist, the turn is refused.
+Do not invent a "virtual cloud" that claims `tools: ["read"]`
+and then runs a VM with a full shell.
+
+### 4.5 `send({ runtime })` overlays or attaches
+
+Two jobs, one field:
+
+```ts
+SendMessageOptions.runtime?: CloudRuntime | LocalRuntime;
+```
+
+**Attach (hybrid).** Host-local agent, this session on a
+VM. Same continuation token, different turn backend.
+
+```ts
+await send("fix the CI failure", {
+  runtime: cloudRuntime({
+    repos: [{ url, startingRef }],
+  }),
+});
+```
+
+**Overlay.** Host-local agent, this session's host options
+(PR worktree, etc.). Today's `send({ workspaceDir })`.
+
+```ts
+await send("review this PR", {
+  runtime: localRuntime({ workspaceDir: worktree }),
+});
+```
+
+`virtualRuntime` is not a send argument (`virtualRuntime`
+returns `LocalRuntime`, but a new tree mid-session is
+refused). Types cannot tell host `localRuntime` from
+`virtualRuntime`. Virtual + `cloudRuntime` or
+`localRuntime({ workspaceDir })` fails at session start.
+
+| Agent default | `send({ runtime })` | |
+|---|---|---|
+| host `localRuntime` | `cloudRuntime(opts)` | Attach. Today's hybrid. |
+| host `localRuntime` | `localRuntime(opts)` | Overlay cwd / sandbox / workspaceDir. |
+| `virtualRuntime` | `cloudRuntime` / `localRuntime({ workspaceDir })` | Type-ok, refuse at start. |
+| `cloudRuntime` | `cloudRuntime(opts)` | Replace session cloud payload. No merge. |
+| `cloudRuntime` | `localRuntime` | Refuse. |
+| grokbot | `cloudRuntime` / `localRuntime` | Refuse. Today's throw. |
+| anything | `grokbotRuntime` | Type error. |
+
+Overlay uses today's cwd resolution: send overlay →
+agent `localRuntime` opts → `cwd/<sessionId>` → durable
+session dir. Cloud ignores a `workspaceDir` overlay.
+
+Preferred `cloudRuntime(opts)` on send is the full session
+payload. It does not merge over `agent.cloud`. A cloud-default
+agent that wants today's per-session merge keeps the
+deprecated shim.
+
+Deprecated shims: `send({ cloud: opts })` →
+`cloudRuntime(merge(agent.cloud, opts))`, then the table
+(so a cloud-default agent still merges; grokbot still
+refuses). `send({ workspaceDir })` →
+`localRuntime({ workspaceDir })` when the agent is
+host-local; ignored on cloud; refused on virtual / grokbot.
+`send({ runtime, cloud })` and
+`send({ runtime, workspaceDir })` fail closed.
+
+This is a session override, not a subagent (`task` /
+`G12`). A process-wide singleton cannot express this.
+
+### 4.6 Workspace is a product surface, not `ResourceAccessor`
+
+The harness workspace is `ResourceAccessor`
+(`packages/agent-exec`): read, write/edit, grep, ls, glob (via
+grep), shell, shell-stdin, MCP, computer-use, and more.
+`LocalResourceProviderOptions` exposes overrides for **three**
+of ~fifteen tools. Grep, ls, and glob have no public override.
+
+`FileSystem` is the public file-verb type: native tool names,
+native arg schemas (`NativeArgs<T>`). `Workspace` adds `shell`
+/ `root` / `brief`. It is not a drop-in for
+`ResourceAccessor`. Streaming stdin, MCP, and computer-use
+stay off the type.
+
+### 4.7 The model must call native `read`
+
+Models are trained on first-class `read` / `ls` / `grep` /
+`glob`. Change-monitor copies those texts into server tools
+because there is no supported way to keep the native tool
+*name* and swap the *implementation* (computer-use.md Gap 2).
+
+That copy is not the real miss. Agent SDK server tools become
+Cursor `customTools`. Those are a synthetic MCP server
+(`custom-user-tools`). Local SDK defaults
+`mcpMetaToolEnabled` to true, so the model's tool list is
+`GetMcpTools` and `CallMcpTool`. After discovery the tool on
+that server is `read`. The call is MCP, not `ReadToolCall`.
+The stream event is `name: "mcp"`, not `name: "read"`.
+`custom-user-tools-read` is the internal wire id, not a
+top-level tool.
+
+Cursor SDK executor overrides keep the native tool, the
+native schema, and the native `tool_call`. Only the
+implementation is swapped. Callers of
+`virtualRuntime(unionFs(…))` never see the binding. If
+Workspace only registered the same per-agent server tools
+change-monitor already ships, the model would still be on
+MCP. That is not a fix.
+
+---
+
+## 5. Existing seams (use them; do not invent a fourth)
+
+```
+Agent SDK          defineAgent({ runtime })     product selector
+        ↓
+Cursor SDK         AgentOptions { local?, cloud? }    dispatch
+        ↓
+local-runtime      WorkspaceRuntime / SessionRuntime  session factory
+        ↓
+local-exec         LocalResourceProvider              workspace
+        ↓
+agent-exec         ResourceAccessor / ExecResource    verb registry
+```
+
+Change-monitor sits *above* all of this, as
+`execution: "server"` tools, because the bottom two layers are
+not plumbed to `AgentOptions`.
+
+| Seam | What it is | Why it is not enough today |
+|---|---|---|
+| `AgentRunner` | Internal `startServer` turn replacement (`runTurn` / `prewarm`) | Replaces the whole turn; no workspace. Not a `Runtime` arm. |
+| `RuntimeDispatchingRunner` | grokbot vs SDK | Hard-coded third case |
+| `AgentOptions.local` / `.cloud` | Parallel config blocks | Presence of `cloud` *is* the runtime until later `Agent.create({ runtime })` |
+| `LocalResourceProvider` overrides | Swap read/write/shell | Private; 3 of ~15 tools; not on `AgentOptions` |
+| `ResourceAccessor` | The agent loop's workspace | Correct internal interface; not a public SDK type |
+| Change-monitor filesystem | Product FS | Consumer-side; duplicated native schemas |
+| `ctx.host.files` | Durable KV, file-shaped | Explicitly not a filesystem; natives cannot see the hosted sink |
+
+The first code PR promotes a public `Workspace` on
+`AgentOptions.local`, bound as executor overrides. Agent SDK
+then passes that workspace through `virtualRuntime`. Do not add
+`runtime: "virtual"`. Do not monkey-patch
+`sessionRuntime.resources` from `@cursor/july`.
+
+---
+
+## 6. Gaps and risks
+
+**G1. Cloud cannot honor an injected workspace.**
+Public `CloudApiClient` is prompt-only. Exec-daemon
+`ControlService.Exec` exists but needs per-pod credentials a
+public caller cannot mint (computer-use.md Gap 1). Treat cloud
+as an opaque loop. Do not ship Workspace methods on
+`cloudRuntime`.
+
+**G2. Builtin redirection is not a public SDK feature.**
+Overrides exist on `LocalResourceProviderOptions` and are not
+passed through `createDefaultLocalWorkspaceRuntime` or
+`AgentOptions` (computer-use.md Gap 2). Grep/ls/glob have no
+override. This is the first code PR: add the missing
+overrides, put `Workspace` on `AgentOptions.local`, and derive
+the tools allowlist from method presence. The authoring API
+in `@cursor/july` waits on that seam. Do not ship
+`virtualRuntime` on lookalike server tools first.
+
+**G3. Native tool schemas vs consumer extras.**
+A redirected `read` must keep the native schema. Verbs that
+are not Cursor tools (`diff`, change-monitor `search`, CAS
+`write`) stay authored tools. Do not widen native schemas to
+carry mount-table prose; that belongs in `brief()` /
+instructions.md (tools.md §6). Do not add `search` to
+`FileSystem` for tags or keyword.
+
+**G4. Hybrid + virtual is easy to get wrong.**
+A planner with a virtual workspace that also
+`send({ runtime: cloudRuntime(...) })` would run
+unrestricted on the VM. Refuse the attach, or require an
+explicit second agent as the delegation target
+(tools.md §3). `send({ runtime })` is not an open override.
+
+**G5. Grokbot is a third Runtime arm, not a workspace.**
+It has no MCP, no server tools, no model override, no v2
+architecture. Keep `grokbotRuntime()` as an arm with no
+`workspace` field.
+
+**G6. Delivery / `Workspace Path`.**
+`virtualRuntime` prints `/`. No scratch dir, no
+`workspaceDir: "/repo"`. A `brief()` that names mounts the
+`FileSystem` does not have is two maps; `root()` wins.
+
+**G7. Security: workspace isolation ≠ host isolation.**
+Injecting a `FileSystem` does not sandbox the serve host. Server tools
+still run in-process with host credentials. Host `shell` is
+still host bash. Document the blast radius on each
+implementation. Prompt-injected writes hit `/host` (or a
+disposable VM), never the serve host's disk or secrets.
+
+**G8. `script` is not host `shell`.**
+A TypeScript isolate that can only call bound Workspace methods
+is a different trust class from `/bin/bash`. Do not overload
+one `shell` method for both until two in-tree implementations
+need a shared `shell` with a `kind`.
+
+**G9. Two public surfaces.**
+`@cursor/sdk` owns `FileSystem` / `Workspace` (native schemas).
+`@cursor/july` owns `virtualRuntime` and helpers that return
+`FileSystem`. Phase 1 does not put constructors on
+`Agent.create`. A later SDK deprecation uses the same
+`Runtime` types. A july-only filesystem cannot re-point
+natives without the SDK seam. Do not ship the authoring API
+against lookalikes and flip the binding later.
+
+**G10. Test and eval story.**
+A virtual workspace must work in `run` / `eval` without Origin.
+Change-monitor already has in-memory filesystem fakes; those become
+`virtualRuntime(memoryFs(…))` in tests.
+
+**G11. Versioning and published docs.**
+String `runtime`, sibling `local` / `cloud`, and
+`send({ cloud })` / `send({ workspaceDir })` are a shipped
+user contract. Replacement is additive:
+`localRuntime(opts)` / `cloudRuntime(opts)` plus `@deprecated`
+on the old selector, sibling bags, and send shims. Do not
+break existing `defineAgent({ runtime: "cloud", cloud })` or
+`defineAgent({ local: { workspaceDir } })`. Do not document
+constructors until they ship (Phase 4 / §9).
+
+**G12. Subagents keep today's behavior, stored as `Runtime`.**
+Discovery still loads a child as a Cursor SDK custom
+subagent (`task`: prompt + description + model). Authored
+`runtime`, `tools/`, skills, MCP under `agent/subagents/`
+are warned and ignored. The child gets the harness default
+toolset on the parent's workspace. Empty july `tools: []`
+does not mean the child is empty-tooled — those slots are
+inert.
+
+Do not change that product. Internally, stop storing
+`runtime: "local"` + `tools: []` as the child's july
+config. Express the same forced host-local inherit as
+`localRuntime()` whose workspace is the parent's (host
+`localWorkspace` or the virtual tree). Authors do not get
+a `Runtime` field on subagents in this design.
+
+A child with its own cwd, own cloud VM, or real july tools
+is a later product. If that product ever honors a child
+`Runtime`, default to inheriting the parent workspace so a
+virtual parent does not spawn host `read`.
+
+**G13. Independently implemented `read` + `shell`.**
+Flattening onto Workspace removes the attach-a-different-shell
+footgun; it does not prove the backends share a namespace.
+Prefer `virtualRuntime(unionFs(…))` / `localRuntime()`.
+`virtualWorkspace` stays private.
+
+---
+
+## 7. Why Cursor SDK first
+
+A july-only cut can generate server tools from Workspace
+methods and pin one schema pack. That is change-monitor
+today, moved into the framework. The model would still call
+`CallMcpTool` on `custom-user-tools` / `read`.
+`tools: ["read"]` would still enable host `read`, not virtual
+`read`. Stream consumers that key on `name === "read"`
+would still miss the calls.
+
+That is the problem this work exists to fix. Do not ship
+`virtualRuntime` on lookalikes and flip the binding later.
+The first code PR opens `AgentOptions.local.workspace` and
+rebounds the native executors.
+
+---
+
+## 8. Plan
+
+Each phase is its own PR. Today's `runtime` string keeps
+working until a later deprecation window. Do not start Phase
+1 until this document (Phase 0) has been reviewed.
+
+### Phase 0 — this document (this PR)
+
+Publish the design. No product code.
+
+Reviewers: Agent SDK and cursor-sdk maintainers; change-monitor
+owners as the first consumer.
+
+Agree before any code PR:
+
+- The four goals at the top (compat — old fields deprecated
+  but kept, `localRuntime` default, fail-closed pairs,
+  `Workspace` instead of a longer enum)
+- `Runtime` is a closed union; `workspace` only on the local
+  arm
+- **Runtime arm** vs **workspace** vs **delivery**
+- Workspace is one object, optional methods, one namespace
+- Cloud/grokbot do not grow a `workspace` field until a
+  machine API exists
+- Native redirection in Cursor SDK is the first code cut
+- Change-monitor is the first workspace, in a later PR
+
+**Review asks** (comment on these):
+
+1. Phase 1 adds `Workspace` on **Cursor SDK**
+   `Agent.create({ local: { workspace } })`
+   (`LocalAgentOptions`, next to `cwd` / `dirs`). That is
+   not `defineAgent({ local })`. july constructors stay in
+   Phase 2. Same-shape `Agent.create({ runtime })` is a
+   later SDK deprecation, not Phase 1. Agree?
+2. Method presence as the file/shell allowlist: fail-closed
+   when `tools` names a missing method?
+3. `virtualRuntime(fs?)` only; no public
+   `virtualRuntime(workspace)`? Empty default, `root()` is `/`.
+   No public `search` method. `FileSystem` is the file-verb
+   type. Agree?
+4. Session factory runs once per session, always async
+   (`Promise<FileSystem>`), with `SessionWorkspaceContext`
+   (`sessionId`, `agentName?`, `continuationKey?`, `host?`).
+   Per-wake data stays inside the `FileSystem`. Agree?
+5. Rejecting host executors for omitted methods when a
+   workspace is set (defense in depth), or tools-header only?
+6. Harness builtins (`webSearch`, `updateTodos`, …) stay off
+   Workspace and off `virtualRuntime`'s default. Opt in via
+   `tools`. Cloud still refuses `tools`. Agree?
+7. `edit` / `delete` / `semSearch` / `readLints` on Workspace
+   now (optional). Phase 1 only fail-closed-omits host
+   executors. Virtual bodies wait for a consumer. Agree?
+8. `Runtime` is a closed union. `workspace` only on
+   `{ kind: "local" }`. Agree?
+9. String `runtime` + sibling `local` / `cloud` stay
+   supported and are marked deprecated. Host options move
+   to `localRuntime(opts)` (`AgentLocalOptions`). Published
+   docs wait for Phase 4 (§9). Agree?
+10. `send({ runtime?: CloudRuntime | LocalRuntime })`.
+    Host-local + `cloudRuntime` = attach. Host-local +
+    `localRuntime(opts)` = overlay. Cloud + `cloudRuntime`
+    = replace payload (no merge). Grokbot + cloud refused.
+    `send({ cloud })` / `send({ workspaceDir })` deprecated
+    shims (`send({ cloud })` still merges).
+    `send({ runtime, cloud })` fail-closed. Agree?
+
+**Out of this PR:** types, executors, discovery, change-monitor
+code, published user docs.
+
+### Phase 1 — Cursor SDK: inject a workspace
+
+Packages: `cursor-sdk`, `cursor-sdk-local-runtime`,
+`local-exec`. No `@cursor/july` authoring change.
+
+`AgentOptions` in this phase is `@cursor/sdk`'s
+`Agent.create` bag (`packages/cursor-sdk/src/agent/options.ts`).
+It is not `defineAgent`'s `AgentLocalOptions`. Agent SDK
+does not grow a `local.workspace` field here. Phase 2's
+`virtualRuntime` writes the `FileSystem` into this SDK
+field when july builds `Agent.create({ local })`.
+
+- Add `FileSystem` / `Workspace` on Cursor SDK
+  `LocalAgentOptions.workspace` (next to `cwd` / `dirs`).
+  Method args are `NativeArgs<T>` matching each tool schema.
+- Derive `tools` from method presence when the caller omitted
+  `tools`. Intersect fail-closed when they passed one.
+- Add `overrideGrepExecutor` / `overrideLsExecutor` /
+  `overrideDeleteExecutor` on `LocalResourceProvider`. Glob
+  rides the grep executor. `edit` rides the write executor.
+  `readLints` rides `diagnosticsExecutor`. `semSearch` has
+  no local-exec override today; when a workspace is set and
+  `semSearch` is omitted, do not register the host index
+  tool.
+- Plumb overrides through
+  `createDefaultLocalWorkspaceRuntime` → the resource
+  provider factory → `createLocalExecutor`.
+- When a workspace is set, bind present methods and reject
+  omitted path-namespace natives (do not leave host `read` /
+  `edit` / `delete` / `semSearch` / `readLints` / `shell`
+  registered behind a virtual tree). Virtual implementations
+  of `edit` / `delete` / `semSearch` / `readLints` are not
+  required in this PR.
+- Cloud + `local.workspace` throws, same posture as
+  `tools` + cloud.
+- Unit tests: a map-backed workspace serves native `read` /
+  `ls` / `grep` / `glob` through the executor adapters. No
+  model turn.
+
+**Not in this PR:** `defineAgent({ runtime })` object form,
+constructors on `Agent.create`, `virtualRuntime`,
+`memoryFs`, change-monitor, published docs. Presence of
+`cloud` still dispatches.
+
+Acceptance:
+
+- `Agent.create({ local: { workspace }, tools })` rebinds
+  natives; a missing method is absent from the toolset and
+  errors if invoked.
+- Existing local agents (no `workspace`) are unchanged.
+- `workspace` + `cloud` is a `ConfigurationError`.
+
+### Phase 2 — Agent SDK: `runtime` accepts a `Runtime` object
+
+Packages: `@cursor/july` (`packages/agent-serve`). Depends on
+Phase 1.
+
+```ts
+runtime?: AgentRuntime | Runtime;
+local?: AgentLocalOptions;   // still supported
+cloud?: AgentCloudOptions;   // still supported
+```
+
+`"local"` / omitted → `localRuntime(agent.local)` (`{ kind:
+"local", workspace: localWorkspace(opts) }`; today's
+default). `"cloud"` → `cloudRuntime(agent.cloud)`.
+`"grokbot"` → `grokbotRuntime()`. Those constructors return
+the `Runtime` union in §1. JSDoc marks the string and
+sibling `local` / `cloud` `@deprecated` in favor of
+`localRuntime(opts)` / `cloudRuntime(opts)`. The fields
+stay.
+
+`virtualRuntime(fs?)` lifts a `FileSystem` (or an async
+per-session factory) to `AgentOptions.local.workspace`. Empty
+`virtualRuntime()` is `/` and no file methods. Omit `tools`
+so workspace methods are the file/shell allowlist; do not
+keep `tools: []`. Discovery validates the composition rules
+in §1. `brief(ctx)` folds into the prompt. `<user_info>`
+Workspace Path is `/`. No `materializeWorkspace`.
+`local.workspaceDir` + virtual fails closed.
+`SendMessageOptions.runtime?: CloudRuntime | LocalRuntime`.
+Host-local + `cloudRuntime` attaches. Host-local +
+`localRuntime(opts)` overlays cwd / sandbox / workspaceDir.
+Virtual + either fails closed. Deprecated `send({ cloud })`
+still merges over `agent.cloud`. Deprecated
+`send({ workspaceDir })` still overlays a host-local agent.
+
+`memoryFs` and `skillsFs` ship here as `FileSystem`
+helpers. The latter is opt-in.
+
+**Not in this PR:** change-monitor cutover, `unionFs` unless
+a test needs it, published user-guide rewrite.
+
+Acceptance:
+
+- Existing string agents unchanged.
+- A fixture agent with
+  `virtualRuntime(memoryFs({ "/a.txt": "hi" }))` can
+  `agent-sdk call read` and get `hi` from the native `read`
+  tool.
+- `virtualRuntime(...)` + `send({ runtime: cloudRuntime(...) })`
+  still fails closed.
+- `send({ cloud })` still attaches a local agent to cloud
+  (merge). On a cloud-default agent it still merges.
+  `send({ runtime: cloudRuntime(opts) })` replaces, no merge.
+- Grokbot + `send({ cloud })` / `send({ runtime: cloudRuntime })`
+  still refuses.
+- `send({ runtime: localRuntime({ workspaceDir }) })` overlays
+  a host-local agent. `send({ workspaceDir })` still works.
+- `send({ runtime, cloud })` fails closed.
+- Discovery matrix: object-form runtimes produce the same
+  fail-closed errors as today's string (tools + cloud,
+  advertiseTools + cloud, grokbot + server tools).
+
+### Phase 3 — change-monitor adopts `virtualRuntime`
+
+Depends on Phase 2. Session binding is the hard part:
+planner/executor filesystem is per-session (PR, SHA, which mounts
+exist), and `defineAgent` runs before that is known.
+
+Replace `tools: []` + copied `src/vfs/tools.ts` schemas for
+`ls` / `glob` / `read` / `grep` with
+`virtualRuntime(async (ctx) => unionFs({ … }))`. Mount
+`skillsFs()` if they still want `/agent/skills`. Writable
+mounts implement native `write` / `edit` and omit
+`delete` / `semSearch` / `readLints` unless a mount earns
+them. Keep authored tools that have no FileSystem method
+(`diff`, CAS extras, plugin telemetry, tag `search` if they
+still want it). Drop `workspaceDir: "/repo"`. `root()` is
+`/`.
+
+Acceptance:
+
+- Change-monitor does not ship a second copy of native
+  schemas.
+- Planner/executor still have no host shell and no checkout.
+- Native `read` / `ls` / `grep` / `glob` hit the mounted `FileSystem`.
+
+### Phase 4 — docs and templates
+
+Ship the published-docs plan in §9. Constructors become the
+authoring vocabulary. The string and sibling `local` /
+`cloud` stay in the pages as deprecated-but-supported.
+Do this after Phase 2 is real. Do not document constructors
+that have not shipped.
+
+### After Phase 4 — not a "v2" of this type
+
+This design is the end state of the authoring type.
+`Workspace` already lists every path-namespace verb. Phases
+1–4 ship that type and the first workspaces. There is no
+second abstraction waiting behind "v1."
+
+What remains is implementation of methods a given workspace
+omits, or **other products** that plug into the same
+constructors.
+
+**Already in this type; a workspace implements when it can**
+
+| Gap | Who fills it | Not |
+|---|---|---|
+| Virtual `edit` / `write` | Change-monitor writable mounts (Phase 3) | A new Workspace field |
+| Virtual `delete` | A mount that can delete | Host `delete` behind a virtual tree |
+| Virtual `semSearch` | A `FileSystem` that owns an index of `root()` | Host index of the serve disk |
+| Virtual `readLints` | A mount that owns diagnostics | Host LSP against a fake cwd |
+| `unionFs` as a public helper | Phase 3 if the factory needs it; otherwise when a second consumer unions mounts | A new runtime |
+
+**Other designs, same constructors**
+
+| Work | Home | How it uses this type |
+|---|---|---|
+| anyrun `/workspace` (`cloudFs`) | factory/change-monitor `computer-use.md` | A shell-backed mount inside `virtualRuntime(unionFs(…))`. Not `cloudRuntime`. |
+| TypeScript `script` isolate | factory/change-monitor `tools.md` §8 | Authored server tool. Not `Workspace.shell`. |
+| Cloud `tools` allowlist | Cursor cloud agent API | Then `defineAgent({ tools })` means the same on `cloudRuntime`. Fail closed until that API exists. |
+| Machine without a model (create / exec / read / hibernate) | New backend surface | The only way `cloudRuntime` can accept a `workspace` for inspection. Do not prompt the VM. |
+| Child with its own `Runtime` | Later product | Today's inherit stays (`G12`). Internally already `localRuntime()` on the parent workspace. No authoring `runtime` on `agent/subagents/` in this design. |
+| `Agent.create({ runtime })` | `@cursor/sdk` after Phase 4 | Same constructors as july. Sibling `local` / `cloud` deprecated as the dispatcher. Not Phase 1. |
+| Deprecate `runtime: "local" \| "cloud"` | After Phase 4 has shipped | Additive constructors first. |
+
+**Not a follow-on. Do not build.**
+
+- `{ kind: "custom"; runner: AgentRunner }` on `Runtime`
+- A `Harness` type / `Runtime.webSearch()`
+- `infer()` on `Runtime`
+- `virtualRuntime(workspace: Workspace)`
+- `cloudRuntime` Workspace methods that prompt the VM
+- Lookalike server tools as a stepping stone
+
+---
+
+## 9. Documentation
+
+Phase 4 work. Published Agent SDK docs live under
+`packages/agent-serve/docs/` (VitePress). They never say
+`agent-serve`. Product name is Agent SDK; package is
+`@cursor/july`; CLI is `agent-sdk`. This design file stays
+internal (`srcExclude: ["design/**"]`).
+
+Do not rewrite user docs in Phases 0–3. Constructors that
+have not shipped must not appear on cursor.com / the
+VitePress site.
+
+### How we talk about runtime
+
+Lead with what the reader is choosing: where the turn runs,
+and (for local) which files the model sees. Constructors
+are the vocabulary.
+
+| Say | Do not say |
+|---|---|
+| `localRuntime()` runs turns on this machine | "the local loop" / `kind: "local"` |
+| `sandboxRuntime()` runs those turns inside Cursor's local sandbox | `localRuntime({ sandbox: true })` as the preferred form |
+| `cloudRuntime({ repos })` runs turns on a Cursor cloud agent | "cloud is the other filesystem" / `runtime: "cloud"` as the only form |
+| `virtualRuntime(fs)` runs locally against a filesystem you pass | `runtime: "virtual"` / `Workspace` / `Computer` |
+| String `runtime` and sibling `local` / `cloud` still work | That they are gone, or that they are the preferred form |
+
+Omit internals: `Runtime` union arms, `kind`, `FileSystem` vs
+`Workspace` lift, `AgentRunner`, `virtualWorkspace`,
+`AgentOptions.local.workspace`, MCP lookalikes, executor
+overrides. Those belong in this design file and in JSDoc for
+SDK maintainers, not in the user guide.
+
+`virtualRuntime` is a real user feature (tests, hosted
+trees, change-monitor-style agents). Document it as "pass
+the files the agent may see." Show `memoryFs` for tests.
+Show a mount table only when `unionFs` has shipped. Do not
+teach readers to implement `FileSystem` from scratch on the
+first page.
+
+Deprecated fields get one short note and a link to the
+constructor, not a second tutorial:
+
+> `runtime: "cloud"` is still accepted. Prefer
+> `cloudRuntime({ repos })`.
+
+Document host options on `localRuntime({ cwd, workspaceDir,
+sandbox })`, next to `cloudRuntime({ repos })`. Sibling
+`local` / `cloud` get a deprecated note and a link.
+
+### Pages to update (Phase 4)
+
+**Own the contract (rewrite the runtime sections)**
+
+| Page | Change |
+|---|---|
+| [reference/agent-config.md](/docs/reference/agent-config.md) | `runtime` type becomes constructors **or** the deprecated string. Table + "Choose a runtime" show `localRuntime(opts)` / `cloudRuntime(opts)` / `virtualRuntime(fs)` first. Move cwd / sandbox / workspaceDir onto the `localRuntime` section. Mark sibling `local` / `cloud` and string `runtime` deprecated. |
+| [guides/cloud-runtime.md](/docs/guides/cloud-runtime.md) | Open with `cloudRuntime({ repos })`. Keep `runtime: "cloud"` as the still-supported form. Cloud is a turn host, not a filesystem. Hybrid is `send({ runtime: cloudRuntime(opts) })`; local overlay is `send({ runtime: localRuntime(opts) })`. `send({ cloud })` / `send({ workspaceDir })` deprecated. |
+| [concepts.md](/docs/concepts.md) | Local vs cloud table: same facts, constructor names. Add one line that `virtualRuntime` is local-with-your-files, not a third host. |
+
+**New page**
+
+| Page | Change |
+|---|---|
+| `guides/virtual-runtime.md` (new) | When to use `virtualRuntime`: no host checkout, tests (`memoryFs`), composed mounts. Empty default (`/`, no methods). Skills only if you mount them. No `workspaceDir`. Fail-closed hybrid cloud attach. Link from agent-config and concepts. |
+
+**Fix examples and cross-links only**
+
+| Page | Change |
+|---|---|
+| [quickstart.md](/docs/quickstart.md) | Default scaffold stays `localRuntime()` or omit `runtime` (same default). Do not mention virtual. |
+| [scaffolding-agents.md](/docs/scaffolding-agents.md) | Same. |
+| [reference/instructions.md](/docs/reference/instructions.md) / [reference/skills.md](/docs/reference/skills.md) | "On the cloud runtime" → "On `cloudRuntime`" where it is a code choice; keep the delivery facts. |
+| [reference/tools.md](/docs/reference/tools.md) | `tools` + cloud still fail closed. Mention it works the same on `cloudRuntime`. |
+| [reference/cli.md](/docs/reference/cli.md) | `agent-sdk call read` against a virtual fixture if we add one in Phase 2. |
+| [troubleshooting.md](/docs/troubleshooting.md) | Discovery errors: string+incoherent pair, `virtualRuntime` + `workspaceDir`, hybrid attach or local overlay on virtual. |
+| `templates/*.md` (e.g. [code-wiki.md](/docs/templates/code-wiki.md)) | Examples that set `runtime: "cloud"` get a constructor form; leave a one-line deprecated equivalent if the template is copy-paste for existing agents. |
+| [building-with-agents.md](/docs/building-with-agents.md) / [deployment.md](/docs/deployment.md) | Wording only if they name the string as the way to choose a host. |
+
+**Do not document here**
+
+- Cursor SDK `AgentOptions.local.workspace` (SDK maintainer JSDoc).
+- Change-monitor mount tables (their repo docs).
+- Grok Bot unless a public template already ships `grokbot`.
+- `kind`, `Workspace`, `FileSystem` method lists (JSDoc on
+  `@cursor/sdk` is enough for authors who implement a mount).
+
+### JSDoc (Phase 2, with the types)
+
+On `@cursor/july`:
+
+- `runtime?: AgentRuntime | Runtime` — constructors first.
+  String values `@deprecated Use localRuntime(opts) / cloudRuntime(opts) / grokbotRuntime()`.
+- `local?` — `@deprecated Use localRuntime(opts)`. Still
+  read when `runtime` is omitted or `"local"`. Error with
+  `virtualRuntime` or `cloudRuntime`.
+- `cloud?` — `@deprecated Use cloudRuntime(opts)`.
+- `SendMessageOptions.cloud` — `@deprecated Use
+  send({ runtime: cloudRuntime(opts) })`. Compat shim still
+  merges over `agent.cloud`.
+- `SendMessageOptions.workspaceDir` — `@deprecated Use
+  send({ runtime: localRuntime({ workspaceDir }) })`.
+- `SendMessageOptions.runtime?: CloudRuntime | LocalRuntime`
+  — attach, overlay, or replace cloud payload. Virtual +
+  either, and grokbot + cloud, fail at start. Together with
+  sibling `cloud` / `workspaceDir` fails closed.
+
+On `@cursor/sdk` (Phase 1):
+
+- New `local.workspace` documented as the injection seam.
+- Existing `local` / `cloud` blocks stay unmarked. Same-shape
+  `Agent.create({ runtime })` is after Phase 4.
+
+### Deprecation window
+
+Phase 4 publishes constructors and marks the string
+deprecated. A later PR, after that has shipped, may set a
+removal date. This design does not pick one.
+
+---
+
+## 10. Non-goals
+
+- Rewriting the cloud agent API or making `tools` work on `bc-`
+  agents. Fail closed stays until the API can honor it.
+- Unifying Grok Bot into Workspace methods.
+- Promoting `AgentRunner` onto `defineAgent` / `Runtime`.
+  Replay and eval fakes keep `StartServerInternalOptions.runner`.
+- A user-authored `infer()` on `Runtime`.
+- `Runtime.instructions()` or `Runtime.read()` — those belong
+  on Workspace, or they re-bundle the string.
+- A `Shell` type the caller attaches next to `FileSystem`.
+  `shell` stays on `Workspace`.
+- `virtualRuntime(workspace: Workspace)`. The lift is
+  internal; authors pass a `FileSystem`. Change-monitor
+  `search` / tags stay authored if needed.
+- Moving server tools, MCP, or `ctx.host.files` behind
+  Workspace.
+- A `runtime: "virtual"` string.
+- `SendMessageOptions.runtime?: Runtime` (the full union,
+  including grokbot). The field is `CloudRuntime |
+  LocalRuntime`. Honoring every pair is still a non-goal.
+- Removing string `runtime` or sibling `local` / `cloud` in
+  Phases 1–4. Deprecate in docs and JSDoc; delete later.
+- Letting `cloudRuntime` pretend to implement Workspace methods
+  by prompting the VM.
+- Shipping lookalike server tools as the first binding.
+- One PR that lands SDK plumbing, july constructors, and
+  change-monitor together.
+- A `Harness` / `Runtime.webSearch()` surface so todos and
+  search look like Workspace methods. Availability is
+  `defineAgent({ tools })`. Rebind later via local executor
+  overrides if a consumer needs a stub.
+
+---
+
+## 11. Proof each code PR owes
+
+Phase 0 has no experiment. Later PRs prove the seam they
+open, not the whole stack.
+
+1. **Phase 1.** Cursor SDK unit test: `overrideReadExecutor`
+   (and ls/grep) serve a map. `Agent.create` with an injected
+   workspace advertises only the present methods.
+2. **Phase 2.** Fixture agent with
+   `virtualRuntime(memoryFs({ "/a.txt": "hi" }))`.
+   `agent-sdk call read` returns `hi` from native `read`.
+   Discovery matrix matches today's fail-closed errors.
+3. **Phase 3.** Change-monitor planner/executor typecheck
+   against `virtualRuntime(unionFs(…))`. No second schema copy.
+   No host checkout.
+
+---
+
+## 12. Decision summary
+
+| Question | Answer |
+|---|---|
+| Design goals? | Compat with today's `defineAgent` / `AgentOptions` shape. Default `localRuntime()`. Fail-closed incoherent pairs. Extensibility via `Workspace`, not a longer enum. |
+| What replaces the string? | Closed `Runtime` union. `workspace` only on `{ kind: "local" }`. `localRuntime(opts)` / `cloudRuntime(opts)` take today's option bags. String + sibling `local` / `cloud` stay, deprecated. |
+| Where do file/shell verbs live? | `FileSystem` in `@cursor/sdk` (native tool names + `NativeArgs<T>`). `Workspace` adds `shell` / `root` / `brief`. No public `search` method. |
+| How do new files get created? | Native **Write** tool (`write` on FileSystem). Str-replace `edit` cannot create. Apply-patch `edit` can via `Add File`. |
+| Empty `virtualRuntime()`? | `/`, no methods, no mounts, no skills, no materialization. Application unions what it needs (`skillsFs()` is opt-in). |
+| Session filesystem? | `virtualRuntime(async (ctx) => fs)` once per session. Always `Promise<FileSystem>`. `SessionWorkspaceContext`: `sessionId`, `agentName?`, `continuationKey?`, `host?`. Per-wake data is a lazy layer. |
+| Effect / approvals? | Unchanged defaults. Gate wraps the tool call, then Workspace runs. Host path allowlists stay on `localWorkspace` only. |
+| Does method presence enable tools? | Yes, for Workspace methods. `tools` may only narrow, fail-closed. |
+| Where do `webSearch` / `updateTodos` live? | Off Workspace. Loop-owned harness builtins. `tools` opts them in on local/virtual. Cloud already has them and cannot select. No `Harness` type. |
+| Should those methods live on `Runtime`? | No. That re-bundles the arm and the workspace. |
+| Should `Runtime.instructions()` exist? | No. Workspace gets `root()` + optional session-scoped `brief()`. |
+| Should inference live on `Runtime`? | No. |
+| What about Grok Bot? | `grokbotRuntime()` — a Runtime arm, no `workspace` field. |
+| How does change-monitor fit? | `virtualRuntime(async (ctx) => unionFs({ /repo, /host, /agent/skills: skillsFs(), … }))`. |
+| How does computer-use.md's VM fit? | A `cloudFs` mount in that same union. |
+| How does `runtime: "cloud"` fit? | `cloudRuntime(opts)` — opaque Runtime arm that owns its tree. |
+| `send({ runtime })`? | `CloudRuntime \| LocalRuntime`. Host-local + cloud = attach. Host-local + `localRuntime` = overlay. Cloud + `cloudRuntime` = replace (no merge). Grokbot + cloud refused. Virtual + either refused. `send({ cloud })` still merges (deprecated). |
+| What stays off `Runtime`? | `model`, `tools`, `builtinTools`, `hosting`, `architecture`, `workspaceFiles`. |
+| Subagents? | Behavior unchanged (`G12`). Internally `localRuntime()` on the parent workspace. No authoring `Runtime` on children. |
+| Can this ship without Cursor SDK changes? | No. Lookalikes put the model on MCP `CallMcpTool`, not native `read`. |
+| First PR? | This design document. |
+| First code PR? | Cursor SDK `local.workspace` + executor overrides (Phase 1). |
+| Then? | Agent SDK object form (Phase 2), change-monitor (Phase 3), published docs (Phase 4 / §9). After that: `Agent.create({ runtime })` on the SDK; other products plug into this type; see §8. |
+
+The string was a convenient name for a bundle that no longer
+bundles cleanly. The replacement is a local Runtime arm you
+can point at any workspace, and two remote arms that have no
+`workspace` field until those products grow a machine API.
+Native tools bind to the injected workspace. That seam opens
+in Cursor SDK before `defineAgent` grows constructors.
+
+---
+
 Source: /docs/evals.md
 
 # Evals
@@ -1515,7 +3280,7 @@ resolution for other file formats).
 `maxConcurrency` limits parallel datapoints. It does not limit model or
 API fan-out inside one datapoint. Materialized fixtures prevent a large
 suite from exhausting provider and GitHub rate limits. The
-[evals skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) has the full fixture workflow.
+[evals skill](/docs/skills/evals.md) has the full fixture workflow.
 
 ## Keep improvements with regression evals
 
@@ -1977,7 +3742,7 @@ event stream for repos you've connected to Cursor. You still declare a
 `githubChannel` so hooks decide what each event does.
 
 The companion skill for coding agents is
-[`skills/github/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md).
+[`skills/github/SKILL.md`](/docs/skills/github.md).
 
 ## Pull events from Cursor
 
@@ -2390,7 +4155,7 @@ deployment as secrets so prod can reconnect after a redeploy. Hosted
 Connect lets the current process retry.
 
 The companion skill is
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 ## What can host MCP OAuth do?
 
@@ -2642,7 +4407,7 @@ You can also pass the same object to `serve(dir, { otel })`. Precedence
 is `serve({ otel })` over `agent/otel.ts` over env. An empty
 `defineOtel()` still enables export when `OTEL_EXPORTER_OTLP_*` is set.
 
-The companion skill is [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md).
+The companion skill is [`skills/otel/SKILL.md`](/docs/skills/otel.md).
 
 ## What spans does a session produce?
 
@@ -2757,7 +4522,7 @@ through `serve({ otel })` or env.
 
 ## What's next
 
-- [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md): compact
+- [`skills/otel/SKILL.md`](/docs/skills/otel.md): compact
   `defineOtel` reference for coding agents
 - [Hooks](/docs/reference/hooks.md): observe the same session event stream
   in-process
@@ -2777,7 +4542,7 @@ Replies stream there, with thinking steps and suggested prompts.
 Use `agent-sdk slack create` when Cursor should own the Slack app. Use
 `agent-sdk slack init --manual` when you own it. Commands and flags live
 in the [CLI reference](/docs/reference/cli.md#slack). Coding agents should
-follow [`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
+follow [`skills/setup-slack/SKILL.md`](/docs/skills/setup-slack.md).
 
 ## Define the channel
 
@@ -2820,6 +4585,85 @@ export default slackChannel({
 });
 ```
 
+## Choose how the reply arrives
+
+Slack gives an agent two places to show progress while a turn runs: the
+status chip under the thread ("Running grep…") and the reply message
+itself. It won't fill both at once. While a message is streaming, Slack
+shows its own "is working…" chip and hides any status text you set. Cards
+only exist inside a streamed message. `reply.mode` picks which one you get.
+
+### `post` (default): status chip, then one message
+
+Tool calls and the first line of each reasoning block show in the chip as
+they happen. The answer lands as a single message when the turn finishes.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "post",
+    status: {
+      reasoning: true,
+      tools: true,
+      idle: ["Checking the monorepo…", "Poking Datadog…"],
+    },
+  },
+});
+```
+
+`idle` is the rotation Slack cycles through when nothing more specific is
+known, up to 5 lines of 50 characters. Pass a function to `tools` to write
+your own line from the calls in flight.
+
+### `stream`: live text, with cards
+
+The answer streams into one message as the model writes it. Slack owns the
+chip for the duration, so live feedback inside the message comes from
+cards. Both are off unless you turn them on.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "stream",
+    reasoningCard: true,
+    toolCards: { group: "per-tool" },
+  },
+  toolLabels: { grep: "Searching code", read: "Reading files" },
+});
+```
+
+The reasoning card is one task card, titled "Thinking", that receives the
+model's reasoning as it streams and completes when the answer text starts.
+`maxChars` (default 1500) caps how much it collects. Slack caps a streamed
+message near 12k characters including cards; when an answer outgrows that,
+the streamed message closes where it stands and the rest continues in a
+new message.
+
+Tool cards default to one card per tool name with a call count in the title
+(`grep ×3`), updated in place as calls finish. `group: "per-call"` shows one
+card per call instead.
+
+Cards are collapsible by default: each call adds one line under the title,
+the same summary the playground shows in a tool's header (the grep pattern,
+the file path, the shell command), and the group expands the same way the
+reasoning card does. `collapsible: false` keeps cards to their titles. On a
+collapsible card, `details(call)` returns the line to add when a call starts
+and `output(result)` the text to add when it finishes.
+
+`toolLabels` renames tools everywhere they appear: the chip, card titles,
+and the default `Running …` line.
+
+### Migrating from `streaming` and `thinkingSteps`
+
+`streaming: false` is `reply: { mode: "post" }`. `streaming: true` is
+`reply: { mode: "stream", toolCards: { group: "per-call", collapsible:
+false } }`, the title-only cards it used to show. `loadingMessages` moves
+to `reply.status.idle`. The old options still work and `agent-sdk validate`
+prints the rewrite for each one.
+
+A channel that set none of these used to stream. It now posts. Set
+`reply: { mode: "stream" }` to keep streaming.
+
 ## Set it up
 
 `slack create` opens the Cursor dashboard wizard. Finish Slack consent
@@ -3451,7 +5295,7 @@ flowchart LR
 
 ## How do I hillclimb an agent with a coding agent?
 
-Have Cursor read [`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md).
+Have Cursor read [`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md).
 
 Tell it:
 
@@ -3465,10 +5309,10 @@ Other skills cover the edges:
 
 | When you need… | Skill |
 | --- | --- |
-| The measured improvement loop | [`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md) |
-| An eval that locks a kept win | [`skills/evals/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) |
-| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md) |
-| A run that misbehaves | [`skills/debug/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+| The measured improvement loop | [`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md) |
+| An eval that locks a kept win | [`skills/evals/SKILL.md`](/docs/skills/evals.md) |
+| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](/docs/skills/github.md) |
+| A run that misbehaves | [`skills/debug/SKILL.md`](/docs/skills/debug.md) |
 
 See [Building agents with agents](/docs/building-with-agents.md) for every framework skill and a good first prompt.
 
@@ -3673,7 +5517,7 @@ Confirm `agent-sdk whoami` shows the expected account.
 ## Related documentation
 
 - Package reference: [`README.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/README.md)
-- Coding-agent workflows: [`skills/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/skills/)
+- Coding-agent workflows: [`skills/`](/docs/skills/index.md)
 
 ---
 
@@ -3689,7 +5533,7 @@ review. Add GitHub event handling so pull requests can trigger reviews.
 
 - **Get started with an agent in Cursor:** follow
   [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) and ask Cursor
-  to read [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md).
+  to read [`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md).
 - **Get started in the CLI:** continue below.
 
 ## Prerequisites
@@ -5260,7 +7104,7 @@ commands with an explicit `--json` flag skip this automatic check.
 agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
                 [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
                 [--cursor-events-repo owner/name]...
-                [--allow-domain <domain>]... [--multi-tenant]
+                [--allow-domain <domain>]...
                 [--no-wait] [--json]
 ```
 
@@ -5288,12 +7132,6 @@ be a lowercase hostname with at least two labels and an alphabetic
 top-level domain. One leading `*.` wildcard is allowed. A deployment
 can declare at most 20 domains.
 
-`--multi-tenant` adds a release to an existing Cursor-managed
-(multi-tenant) product such as `security-reviewer`. It is valid only
-for `architecture: "v2"` and cannot create a new multi-tenant
-application — those stay on the operator seed path. Without the flag,
-HTTP deploy stays single-tenant and a managed slug 409s.
-
 By default, the command polls every three seconds for up to ten minutes
 and succeeds only when the deployment reaches `running`. `--no-wait`
 returns after the deployment request is accepted. Multi-agent deploys
@@ -5698,7 +7536,7 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
-skill: [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+skill: [`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 Account MCP (`cursorAccount: true`) is the right choice for connectors
 already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
@@ -6074,6 +7912,7 @@ and `playgroundUrl` deep-links the session in the playground.
 | `message` | Required user message |
 | `title` | Session title |
 | `dryRun` | Run read tools and stub write tools |
+| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tools declaring `timeArgs` refuse calls not bounded at or before it. `400` when unusable |
 | `workspaceFiles` | UTF-8 files written into the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
 
@@ -7282,6 +9121,31 @@ export default defineTool({
 `dryRunResult` keeps the result shape stable. Without it, a stubbed write
 returns `"Operation acknowledged."`. Traces mark the result as stubbed.
 
+### Bound time arguments under `asOf`
+
+Declare `timeArgs` with the input properties that carry time bounds. In a
+session created with `asOf`, every named argument must be an absolute
+ISO-8601 instant with a timezone, no later than the session's frozen
+instant. A call that omits one, or supplies a relative or later value, is
+refused with an error telling the model to retry with absolute bounds.
+Sessions without `asOf` ignore the declaration.
+
+```ts
+export default defineTool({
+  description: "Query telemetry between two instants.",
+  inputSchema: z.object({ since: z.string(), until: z.string() }),
+  effect: "read",
+  timeArgs: ["since", "until"],
+  async execute({ since, until }) {
+    return queryTelemetry(since, until);
+  },
+});
+```
+
+Every name in `timeArgs` must exist in the input schema; a session with
+`asOf` refuses to start otherwise, because a misspelled name would silently
+check nothing.
+
 ## Define an agent tool
 
 Set `execution: "agent"` and the tool materializes as a shell script
@@ -7467,7 +9331,7 @@ decision.
 ## What does the create-agent skill do?
 
 The bundled
-[`create-agent` skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) turns your goal
+[`create-agent` skill](/docs/skills/create-agent.md) turns your goal
 into a small working project. Have Cursor read that file and follow it.
 
 Where to find the file depends on how you got the package:
@@ -7482,7 +9346,7 @@ Where to find the file depends on how you got the package:
 - Installed `@cursor/july` as a dependency? The skill also ships inside
   the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
 - Working from this package's source? The skill is at
-  [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md). Run
+  [`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md). Run
   `agent-sdk install-skills` if you want the same copies in
   `~/.cursor/skills/agentsdk/` (the package postinstall skips the
   source checkout).
@@ -7575,7 +9439,7 @@ without a Cursor credential. Model turns and evals need
 
 Choose one to three fixed inputs, define what should improve, and name
 what must stay unchanged. Then have Cursor follow
-[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md).
+[`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md).
 
 The hillclimb skill measures a baseline, changes one lever, runs the same
 inputs again, and adds an eval for each improvement you keep.
@@ -7591,6 +9455,935 @@ inputs again, and adds an eval for each improvement you keep.
 
 ---
 
+Source: /docs/skills/ab.md
+
+# Agent SDK A/B metrics (`defineAB`)
+
+Live metrics plug-in. No `agent-sdk ab` CLI. No assertion API.
+Reference: `docs/ab.md`.
+
+| | `defineEval` | `defineAB` |
+| --- | --- | --- |
+| Job | Gates on frozen fixtures | Metrics on live runs |
+| Location | `evals/**/*.eval.ts` | `agent/ab.ts` or `agent/ab/<name>.ts` |
+| How it runs | `agent-sdk eval` | Under `serve` / `run` |
+
+```ts
+import { defineAB, splitBySessionHash } from "@cursor/july/ab";
+
+export default defineAB({
+  name: "concise-instructions",
+  variants: {
+    control: { label: "Baseline" },
+    treatment: {
+      label: "Shorter",
+      instructions: "Keep replies to one short paragraph.",
+    },
+  },
+  split: splitBySessionHash({ holdout: 0.1 }),
+  derive: {
+    weatherCalls: (event) =>
+      event.type === "action.result" && event.data.toolName === "get_weather"
+        ? 1
+        : null,
+  },
+  onSample(sample) {
+    console.log(sample.variant, sample.metrics.toolCalls, sample.metrics.wallTimeMs);
+  },
+});
+```
+
+```ts
+async execute(input, ctx) {
+  if (ctx.session.abs?.["concise-instructions"] === "treatment") {
+    // treatment-specific behavior
+  }
+}
+```
+
+Enrollment is at session creation. Eval sessions skip it. Do not
+use `splitIf` to filter evals. Split helpers and `onSample`
+fields: `docs/ab.md`.
+
+Pick a name, arm labels, a split, and a real `onSample` sink. Do
+not invent credentials.
+
+---
+
+Source: /docs/skills/create-agent.md
+
+# Create an Agent SDK agent
+
+1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
+2. **Scaffold.** `agent-sdk init`, then shape the files.
+3. **Verify.** `validate` / `info` / `call`, then a model turn.
+4. **Channels.** Slack, GitHub, webhook, or schedule as chosen.
+5. **Hillclimb.** `skills/hillclimb/SKILL.md`.
+
+Read `skills/framework-map/SKILL.md` if you have not. CLI is
+`agent-sdk`. Public docs:
+`node_modules/@cursor/july/dist/docs/llms.txt` or `/docs/llms.txt`
+on a running host.
+
+## Interview
+
+`AskQuestion`: batched, recommended option first and labeled
+`(recommended)`.
+
+- Mine the invoking message. Target: two rounds, then files.
+- Round 1 is identity. Round 2 is the surface, tailored by round 1.
+- Multi-select for channels, MCP, capabilities. Other where a
+  custom answer is plausible.
+- Ask decisions, not how to build it. File layout, tool names,
+  env prefix, and eval shape are yours.
+- If `AskQuestion` is missing or the user skips, state defaults
+  in one list and proceed.
+
+### Round 1: identity
+
+| Question | Options |
+| --- | --- |
+| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |
+| **Name** | 2–3 slugs from the purpose + Other. Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
+| **Location** | `./<slug>` (default) · another directory |
+
+### Round 2: surface
+
+| Question | Options | Guidance |
+| --- | --- | --- |
+| **Runtime** | `local` (default) · `cloud` | Cloud needs `cloud.repos`. Approvals and sandbox seeds are local only. Recommend local unless the job needs a cloud checkout. |
+| **Model** | `grok-4.5` + `effort=high`, `fast=true` · Other id | Params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` |
+| **Channels** (multi) | playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule | Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook. |
+| **MCP** (multi) | none · remote URL · local stdio · Cursor account connectors · Other | One file under `agent/mcp-connections/`. Account file is `account.ts`, never `cursor.ts`. Named local tools need `advertiseTools: true`. Privileged servers go in `agent/host-connections/`. |
+| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend) | Always recommend one smoke eval. |
+
+Close with the plan and file tree, then "Scaffold it" / "Adjust
+something". Write files only after approval.
+
+## Fill the blanks
+
+| Purpose | Shape |
+| --- | --- |
+| Slack chat | `slackChannel({ envPrefix })` + suggested prompts. `agent-sdk slack create` mints the bot. Prefix: `skills/setup-slack/SKILL.md` |
+| PR review with host prep | Channel `callTool` into a trimmed workspace `pr/` tree |
+| GitHub automation | `githubChannel()` hooks, replay fixtures |
+| Domain assistant | Server tools + one MCP connection + a skill |
+| Wrap an existing pipeline | GitHub `{ task }` over a thin `agent/lib/` loop |
+
+Defaults:
+
+- Instructions + 1–2 tools + chosen channels + one smoke eval.
+- `local.cwd` stays outside a monorepo checkout (default: a cache
+  directory under `~/.cache`) unless the agent must inherit that
+  tree.
+- `agent/instructions.md`: identity, when to use which tool,
+  output shape.
+- One tool per file. Prefer `execution: "server"` + zod
+  `inputSchema`. Gate side effects with `needsApproval: true`.
+- Long prompts: `prompt\`…\`` / `prompt.lines\`…\`` from
+  `@cursor/july`.
+- Host prep is for evidence (`callTool`, `workspaceFiles`), not
+  judgment, formatting, or replies.
+
+### Deterministic-path budget
+
+Default to instructions and skills. Promote to TypeScript only
+when it earns the left column:
+
+| Code owns | Model owns |
+| --- | --- |
+| Side-effect gates (approve, deploy, post) | Human-facing output to a stated shape |
+| Dedupe of external writes | Summarizing, classifying, wording |
+| Auth and signature checks | What to do next from ground truth |
+| Evidence seeding | Soft-failure retries |
+| Hard API caps | Formatting under those caps |
+
+Smells: prose builders in `.ts` (write `.md`); `agent/lib/` +
+`tools/` dwarfing instructions + skills on a first cut.
+
+## Scaffold
+
+```bash
+agent-sdk init ./<slug>
+```
+
+`init` writes the project, runs `npm install`, and may wait on
+`login`. Then shape it:
+
+1. `defineAgent` with the chosen model/runtime. Add
+   `cloud: { repos: [...] }` for cloud.
+2. Real `instructions.md`. Replace `echo.ts`.
+3. Chosen `channels/`, `mcp-connections/`, `skills/`,
+   `subagents/<id>/` (needs `description`), `schedules/`, `hooks/`.
+   Slack: `agent-sdk slack create --dir ./<slug> --name "<Name>"`,
+   not a hand-written channel. Manual Slack app:
+   `agent-sdk slack init --manual` (Slack CLI, or paste at
+   api.slack.com).
+4. `evals/evals.config.ts` with `maxConcurrency: 20` (required;
+   cap 200) plus `evals/**/*.eval.ts`. Assert `t.succeeded()` +
+   `t.calledTool(...)`. API: `skills/evals/SKILL.md`.
+
+Stay on deps the Agent SDK already ships (`zod`,
+`@modelcontextprotocol/sdk`, `tsx`).
+
+## Verify
+
+```bash
+agent-sdk validate --dir ./<slug>
+agent-sdk info --dir ./<slug> --json
+agent-sdk call <tool> --dir ./<slug> --input '{…}'
+agent-sdk eval --dir ./<slug> --list
+npx tsc --noEmit -p ./<slug>
+```
+
+tsx does not typecheck. Tool `execute` must return JSON-shaped
+values: object literals or `type` aliases, not `interface` types.
+
+Model turns need `CURSOR_API_KEY`. Without one, finish the
+key-free checks, confirm `run` fails with only the API-key error,
+and hand these over:
+
+```bash
+agent-sdk run --dir ./<slug> --message "<fixture prompt>"
+agent-sdk serve --dir ./<slug> --mode single --dev
+# http://127.0.0.1:3000/playground
+agent-sdk eval --dir ./<slug>
+```
+
+Serve only this agent's directory. Session files land in the
+project state directory (`--state-root`). That is not harness cwd.
+
+## Channel setup
+
+- **Slack.** `skills/setup-slack/SKILL.md`
+- **GitHub.** `skills/github/SKILL.md`
+- **Custom webhook.** `POST /v1/channels/<id>/<route>`.
+  Loopback-only until you add `bearerAuth(...)`.
+- **Schedules.** Never auto-fire under `--dev`.
+  `POST /v1/dev/schedules/<id>`.
+
+## Hillclimb handoff
+
+Once a smoke turn passes, agree fixtures, success criteria, and a
+freeze line, then follow `skills/hillclimb/SKILL.md`. Seed from
+the smoke session under the project state directory. GitHub:
+snapshot `agent-sdk github replay ... --dry-run --out fixtures/github`.
+
+Do not deploy or post to real Slack/GitHub beyond the smoke the
+user asked for. If the plan grows past ~10 files, cut scope.
+Re-check the budget at hand-off.
+
+---
+
+Source: /docs/skills/debug.md
+
+# Debugging the Agent SDK locally
+
+Local `agent-sdk serve`. Hosted start or health failures:
+`docs/troubleshooting.md` and `docs/deployment.md`.
+
+1. **Validate.** `agent-sdk validate --dir <project>`
+2. **Info.** `curl -s http://127.0.0.1:3000/<slug>/v1/info | jq .`
+3. **Trace.** Session events under the project state directory.
+   Then match the table.
+
+| Symptom | Fix |
+| --- | --- |
+| Playground blank / "no agents" | Start `serve`. A built SPA with no backend serves nothing. |
+| Playground UI edits do not show | Open the URL `serve --dev` prints as `playground`, not `:3000`. |
+| Sessions on disk, empty playground list | List is the calling principal. `--dev` or `--allow-anonymous` shows all. Or `?sessionId=ses_...`. |
+| Built-in read/grep fail; retry loops | Bun. Rerun under Node. The tell is `NGHTTP2_FRAME_SIZE_ERROR`. |
+| `github forward` 401s; hook created | Blank `GITHUB_TOKEN`/`GH_TOKEN`. Relay uses `gh` login. |
+| `Hook already exists` | One forwarder per repo. `forward --dir <parent>`. |
+| Answers cite ancestor `AGENTS.md` | Nested checkout. Default `local.cwd` is a cache directory under `~/.cache`. |
+| Model lists IDE `cursor` tools, never MCP | `advertiseTools: true`. Check `GET /v1/info`. |
+| Port 3000 in use | `lsof -iTCP:3000 -sTCP:LISTEN` and kill that pid. |
+| Approval vanished after restart | Parked calls do not survive restart. Re-run. |
+| Schedule / reminder silent under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>`. |
+| `409` on follow-up | Stale `continuationToken`, busy session, or a task session. |
+| `409 session_busy` on `call --session` | Wait, or drop `--session`. |
+| `403` on stream | Wrong principal. Same auth as create; beyond loopback send `--bearer-token`. |
+| Works on loopback, blocked via tunnel | `localDevStrict()` rejects forwarded headers. Use `--bearer-token`. Never `--allow-anonymous` with account MCP. |
+| Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
+| Immediate API-key error | Model turns need `CURSOR_API_KEY`. |
+| Approvals or sandbox seeds missing | `runtime: "cloud"`. Those are local only. `validate` warns. |
+| `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+
+Count `action.result` by `toolName` before blaming latency.
+`turn.failed` + `"turn interrupted"` is a follow-up or stop, not a
+crash. `agent-sdk trajectory --events <file>` renders a saved
+trace.
+
+---
+
+Source: /docs/skills/evals.md
+
+# Agent SDK evals
+
+Fixed input, model turn, gates on the trajectory. Files live at
+project-root `evals/**/*.eval.ts`. `agent/evals/` is ignored.
+
+Live traffic variants: `skills/ab/SKILL.md`. That is not a test
+runner.
+
+```bash
+agent-sdk eval --dir . --list
+agent-sdk eval --dir . --json
+agent-sdk eval --dir . weather/nyc
+agent-sdk eval --dir . --tag smoke
+```
+
+| Form | Case id |
+| --- | --- |
+| `evals/weather.eval.ts` + `test` | `weather` |
+| `evals/weather/nyc.eval.ts` + `test` | `weather/nyc` |
+| `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
+
+`eval` boots an ephemeral server and a temp state root. `--url`
+points at a running agent. Model turns need `CURSOR_API_KEY`.
+
+## Seeding
+
+Creating or expanding cases: `AskQuestion` first.
+
+| Question | Options |
+| --- | --- |
+| **How should we get eval samples?** | Generate test eval samples for me `(recommended)` · I will add / upload the data manually |
+
+1. **Manual.** They provide files or paste. Show the shape below.
+   Do not invent cases. Then `eval --list` and wire gates.
+   API-backed pointers (PR URLs, SHAs, gold labels): materialize
+   under `fixtures/` first.
+2. **Generated.** Ask count (`3` recommended). Append to an
+   existing `cases` array when it fits. Never overwrite or weaken
+   a datapoint. Create `evals/evals.config.ts` if missing
+   (`maxConcurrency: 20`; cap 200).
+
+## API
+
+```ts
+import { defineEval, includes, satisfies } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke", "weather"],
+  cases: [
+    {
+      id: "nyc",
+      description: "NYC temperature.",
+      async test(t) {
+        await t.send("What's the temperature in NYC?");
+        t.succeeded();
+        t.calledTool("get_weather");
+        t.notCalledTool("save_weather_note");
+        t.check(t.reply, includes(/°|[FC]/));
+      },
+    },
+  ],
+});
+```
+
+```ts
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 20,
+});
+```
+
+Either `test(t)` or `cases`, not both. `t.send` waits for park/fail.
+`workspaceFiles` seeds the first turn. Assert with `t.succeeded()`,
+`calledTool` / `notCalledTool`, `t.check(t.reply, …)`, `t.metric`.
+
+## What to gate
+
+Decisions and shape, not prose.
+
+1. `t.succeeded()` first
+2. Intended tool + the tempting wrong one
+3. A shape regex or `satisfies` on parsed fields
+4. If formatting keeps failing, tighten instructions. Do not move
+   rendering into a host tool.
+
+Anti-patterns: exact phrasing; more than ~5 gates (split); live
+drifting inputs (pin them).
+
+| Surface | Fixture |
+| --- | --- |
+| Chat | One frozen prompt |
+| Tool-heavy | `agent-sdk call` first, then the prompt |
+| GitHub | `github replay … --dry-run --out fixtures/github` |
+| Host-prep PR review | A team-owned PR; gate findings shape, not counts |
+| Workspace | `workspaceFiles` in `t.send` |
+
+Every kept hillclimb change lands an eval that would have failed
+before it. Never weaken a gate to pass a round.
+
+---
+
+Source: /docs/skills/framework-map.md
+
+# Agent SDK framework map
+
+`@cursor/july` discovers files under `agent/` and serves the agent
+over HTTP, Slack, and GitHub. Markdown is prose. TypeScript is typed
+behavior. Ground truth: package `README.md` and `AGENTS.md`.
+
+CLI is `agent-sdk` (Node, never Bun).
+
+Public docs: `node_modules/@cursor/july/dist/docs/llms.txt` or
+`/docs/llms.txt` on a running host.
+
+## Invariants
+
+1. **Node 22.13+, never Bun.** Bun corrupts harness tool-result
+   streams (`NGHTTP2_FRAME_SIZE_ERROR`).
+2. **Evals live at project-root `evals/`.** `agent/evals/` is ignored.
+3. **tsx does not typecheck.** Tool `execute` must return JSON-shaped
+   values: object literals or `type` aliases, not `interface` types.
+4. **Nested git checkouts.** Discovery sets `local.cwd` to a
+   per-project cache directory under `~/.cache`. Point cwd at a
+   checkout only when the agent must inherit that tree.
+5. **Attached MCP is nameless** until `advertiseTools: true`.
+6. **Model turns need `CURSOR_API_KEY`.** `validate`, `info`, `call`,
+   and `serve` bring-up do not.
+
+## Folder structure
+
+Path is identity. Full list: README "Folder structure".
+
+| Path | Role |
+| --- | --- |
+| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })` |
+| `agent/instructions.md` | Always-on system prompt (required) |
+| `agent/tools/<name>.ts` | One tool. `execution: "server"` or `"agent"` |
+| `agent/skills/*` | On-demand procedures |
+| `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
+| `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
+| `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
+| `agent/hooks/*.ts` | Observe-only |
+| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
+| `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
+| `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
+| `agent/sandbox/workspace/` | Session seed files (local only) |
+| `agent/lib/` | Import-only. Never discovered |
+| `evals/**/*.eval.ts` | Case id is the path under `evals/` |
+
+## Local vs cloud
+
+`runtime: "local"` (default) runs on the serve host.
+`runtime: "cloud"` needs `cloud: { repos: [...] }`.
+
+| Capability | local | cloud |
+| --- | --- | --- |
+| Server tools | yes | yes on managed hosting; self-hosted needs `--public-url` |
+| Tool approvals | yes | no |
+| Agent tools / skills | yes | yes |
+| sandbox seeds | yes | no |
+| Checkout | you arrange it | the VM carries it |
+
+Use cloud when the job needs a checkout at scale. `validate` warns
+when cloud is combined with local-only capabilities.
+
+## Sessions
+
+- **continuationToken** continues a conversation. HTTP follow-ups
+  rotate it. Stale tokens return `409`.
+- **sessionId** is the inspect handle
+  (`GET /v1/session/:id/stream?startIndex=N`).
+
+A follow-up to a busy HTTP/MCP session interrupts the in-flight
+turn. Slack coalesces. Routes: `docs/reference/http-api.md`.
+Session files live under the project state directory
+(`--state-root`).
+
+## Where logic belongs
+
+Code: side-effect gates, write dedupe, auth, evidence seeding, hard
+API caps. Model: formatting, summarizing, classification, replies.
+Budget: `skills/create-agent/SKILL.md`.
+
+Loop: `validate` / `info` / `call` / `run` / `eval` / `serve`. Serve
+only this agent's directory.
+
+| Task | Skill |
+| --- | --- |
+| Scaffold | `skills/create-agent/SKILL.md` |
+| Evals | `skills/evals/SKILL.md` |
+| Live A/B | `skills/ab/SKILL.md` |
+| OpenTelemetry | `skills/otel/SKILL.md` |
+| GitHub | `skills/github/SKILL.md` |
+| Slack | `skills/setup-slack/SKILL.md` |
+| Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Local triage | `skills/debug/SKILL.md` |
+| Measured improvement | `skills/hillclimb/SKILL.md` |
+
+---
+
+Source: /docs/skills/github.md
+
+# GitHub channels in the Agent SDK
+
+Author `agent/channels/github.ts`. Production wakes:
+`cursorAccount` + `serve --cursor-events`. No public webhook URL.
+Use the HTTP route for fixtures, replay, and hosts that already
+terminate GitHub webhooks.
+
+Guide: `docs/guides/github.md`.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+  cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
+
+  onPullRequest: (ctx, pr) =>
+    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+  onCheckSuite: (ctx, suite) =>
+    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
+});
+```
+
+Hooks: `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
+`onCheckRun`, `onWorkflowRun`, `onStatus`, plus `onEvent` and
+`onStart`/`onStop`.
+
+| Return | Meaning |
+| --- | --- |
+| `{ auth }` | Model turn. Session shows in the playground. `workspaceFiles` can be a function. |
+| `{ task }` | Host work. No chat session. Use when the work can outlive a webhook timeout. |
+| `null` | Skip |
+
+To keep repo scope in deploy config, use `cursorAccount: true`
+and pass `--repo owner/name` at serve / `--cursor-events-repo`
+at deploy. Repos must share one GitHub owner.
+
+## Event sources
+
+| Source | When |
+| --- | --- |
+| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login` / `CURSOR_API_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
+| HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256` |
+| HTTP, no secret | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward) |
+
+`permissions`: `"read"` inspect; `"pr-write"` (default) comments /
+PR writes; `"contents-write"` push or merge-box checks.
+`progress.commitStatus` needs check-write; see the GitHub guide.
+Set `checks: true` when channel code posts its own Checks API
+runs through `ctx.github.createCheck`. The flag grants access.
+It does not post a check.
+
+Without `cursorAccount`, outbound calls prefer App installation
+tokens (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`). Local tests
+can use `GITHUB_TOKEN` / `gh auth login`.
+
+The Cursor stream is metadata, not full webhook bodies. Re-read
+the PR from GitHub.
+
+## Test locally
+
+1. **Fixtures** (offline, `--dev`, no signature):
+
+```bash
+curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
+  -H 'content-type: application/json' \
+  -H 'x-github-event: pull_request' \
+  -d @fixtures/github/pull_request.synchronize.json
+```
+
+2. **Replay** (hillclimb tier; pull access is enough):
+
+```bash
+agent-sdk github replay owner/repo#123 --dir <project>
+agent-sdk github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
+```
+
+3. **Forward** (live; repo admin). One forwarder per repo. Blank
+   `GITHUB_TOKEN`/`GH_TOKEN` or every delivery 401s:
+
+```bash
+agent-sdk github doctor --install
+GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward --dir <project>
+```
+
+4. **Cursor pull** (same as production):
+
+```bash
+agent-sdk serve --dir <project> --cursor-events --repo owner/repo
+```
+
+Volume, debounce, and `progress.commitStatus` / `progress.banner`
+live in `docs/guides/github.md`. Do not preinstall them.
+
+---
+
+Source: /docs/skills/hillclimb.md
+
+# Agent SDK hillclimb
+
+Measure → change one lever → remeasure. One failure mode per round.
+
+Siblings: `skills/evals/SKILL.md`, `skills/github/SKILL.md`,
+`skills/debug/SKILL.md`.
+
+## Preconditions
+
+From the user or the invoking message:
+
+1. **Target.** Path or slug
+2. **Fixtures.** Fixed inputs
+3. **Success.** What better means this round
+4. **Freeze line.** What must not change
+
+Ask before editing if any are missing. A moving fixture is noise.
+
+| Surface | Pin it |
+| --- | --- |
+| GitHub | `agent-sdk github replay <pr> --dir <project>` (`--dry-run --out fixtures/github`) |
+| One tool | `agent-sdk call <tool> --dir <project> --input '{...}'` |
+| Chat | `agent-sdk run --dir <project> --message "<fixture>"` |
+
+## Loop
+
+1. **Serve.** `agent-sdk serve --dir <project> --mode single --dev`
+   Playground: `http://127.0.0.1:3000/playground`.
+2. **Hit it.** Same path a user would. Record status, wall time,
+   `sessionId`, output, and `action.result` counts by `toolName`.
+3. **Name the failure.** Score correctness, efficiency, harness
+   fit. One dominant failure this round.
+4. **Change one lever.** Smallest first. Delete the code or prompt
+   that caused it. Then instructions / skills, evidence shape,
+   host prep (`workspaceFiles`, channel `callTool`) for wandering
+   and latency (not formatting or judgment), remove or gate
+   wandering tools, framework only if the agent cannot express
+   the fix. Hypothesis: *If we X, metric Y should move because Z.*
+5. **Remeasure.** Same fixtures. Keep only if the target metric
+   improves and the freeze line holds.
+6. **Lock.** A kept change gets an eval that would have failed
+   before it (`skills/evals/SKILL.md`). Never weaken a gate to
+   pass a round.
+
+```markdown
+### Hillclimb round N. `<slug>`
+- Fixture(s): …
+- Hypothesis: …
+- Change: …
+- Before → after: tools …; wall …; quality …
+- Verdict: keep | revert | narrow
+- Next failure mode:
+```
+
+Do not deploy or post real GitHub reviews unless asked.
+
+---
+
+Source: /docs/skills/index.md
+
+# Coding-agent skills
+
+Each skill is a procedure a coding agent can follow. Installing
+`@cursor/july` copies them into `~/.cursor/skills/agentsdk/`. This site
+publishes the same files.
+
+See [Building agents with agents](/docs/building-with-agents.md) for when
+to use each one.
+
+| Skill | Use it to |
+| --- | --- |
+| [framework-map](/docs/skills/framework-map.md) | Learn the project layout and runtimes |
+| [create-agent](/docs/skills/create-agent.md) | Scaffold and verify a new agent |
+| [evals](/docs/skills/evals.md) | Write fixtures and regression checks |
+| [ab](/docs/skills/ab.md) | Compare variants on live traffic |
+| [otel](/docs/skills/otel.md) | Export OpenTelemetry traces |
+| [hillclimb](/docs/skills/hillclimb.md) | Improve an agent against fixed inputs |
+| [github](/docs/skills/github.md) | Add GitHub webhooks and replay events |
+| [setup-slack](/docs/skills/setup-slack.md) | Connect an agent to Slack |
+| [mcp-auth](/docs/skills/mcp-auth.md) | Authorize host MCP OAuth |
+| [debug](/docs/skills/debug.md) | Diagnose a local run |
+
+---
+
+Source: /docs/skills/mcp-auth.md
+
+# Host MCP OAuth
+
+Guide: `docs/guides/mcp-oauth.md`.
+
+| Need | Use |
+| --- | --- |
+| Connector already in the Cursor dashboard | `defineConnection({ cursorAccount: true })` or `servers: "*"` / `servers: […]` |
+| Remote URL that speaks OAuth; host holds tokens | `defineConnection({ url, oauth: true })` + this skill |
+| Static bearer / API key | `headers` / env on `{ url }` |
+
+`advertiseTools: true` puts named tools on local turns. Host tools
+can still call `ctx.host.mcp`.
+
+## Checklist
+
+1. **Declare the connection.** `agent/mcp-connections/<name>.ts`
+   with `url` + `oauth: true`. Use `agent/host-connections/` when
+   the model must not see it.
+2. **Name the secrets** if you will `--store`:
+   `hosting.secretNames` lists
+   `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}`.
+3. **Allow egress** on hosted non-bootstrap hosts:
+   `hosting.egressDomains`.
+4. **Authorize.** Local: `agent-sdk mcp oauth <name>`. Hosted:
+   finish Connect so the current process can retry, then
+   `agent-sdk mcp oauth <name> --store` and `agent-sdk deploy` so
+   the next pod gets `MCP_OAUTH_*`. `secrets list` shows the names.
+   Secrets are deployment-wide, not per caller. `cursorAccount: true`
+   stays on the Cursor backend.
+
+```ts
+// agent/mcp-connections/inventory.ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+});
+```
+
+```ts
+// agent/agent.ts
+export default defineAgent({
+  hosting: {
+    secretNames: [
+      "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
+      "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
+      "MCP_OAUTH_INVENTORY_CLIENT_ID",
+    ],
+    egressDomains: ["mcp.example.com"],
+  },
+});
+```
+
+File `inventory.ts` → prefix `MCP_OAUTH_INVENTORY`. Do not put
+`CURSOR_*` names in `secretNames`.
+
+```bash
+agent-sdk mcp oauth <connection>
+agent-sdk mcp oauth <connection> --store [--slug <slug>]
+agent-sdk secrets list <slug>
+agent-sdk deploy
+```
+
+Browser callback: `http://127.0.0.1:8787/callback`. Tokens live in
+the CLI config directory (`mcp-auth.json` or
+`$AGENT_SERVE_CONFIG_DIR`). URL change drops the old entry; re-run.
+`--store` does not restart a running engine.
+
+| Symptom | Fix |
+| --- | --- |
+| `must be defineConnection({ url, oauth: true })` | Wrong name or missing `oauth: true` |
+| `Unknown MCP connection` | Filename must match the CLI arg |
+| Callback hang | Free port 8787; finish the browser flow here |
+| Hosted 401 | `secrets list`; Connect or `--store`; redeploy |
+| Model invents `mcp_auth` / IDE MCP | `advertiseTools: true` on local turns |
+
+No raw tokens in git.
+
+---
+
+Source: /docs/skills/otel.md
+
+# Agent SDK OpenTelemetry (`defineOtel`)
+
+Push traces and metrics from the serve process to an OTLP
+collector. Logs are off until you opt in.
+
+Guide: `docs/guides/opentelemetry.md`.
+
+## Enable
+
+Any one of:
+
+1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
+   `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
+   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
+2. `agent/otel.ts`:
+
+```ts
+import { defineOtel } from "@cursor/july/otel";
+
+export default defineOtel({
+  serviceName: "cursor",
+  exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
+});
+```
+
+3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
+   authored config.
+
+| Signal | Default |
+| --- | --- |
+| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
+| Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
+
+Prompt text and tool payloads stay off the wire unless you set
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`.
+
+## Custom metrics
+
+```ts
+ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420);
+```
+
+Prefix names with team or agent. No custom spans. Join on
+`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
+own process when Agent SDK should own the destination.
+
+---
+
+Source: /docs/skills/setup-slack.md
+
+# Setup Slack for the Agent SDK
+
+Dedicated Socket Mode bot. `agent-sdk slack create` opens the
+signed-in dashboard wizard. Tokens land in `.env.local` and as
+deployment secrets. Never print token values.
+
+Do not generate manifests or ask anyone to paste tokens unless
+they asked for `slack init --manual`.
+
+Existing `<PREFIX>_SLACK_BOT_TOKEN` + `_SLACK_APP_TOKEN` in
+`.env.local` keep working. Do not force those onto the wizard.
+
+Guide: `docs/guides/slack.md`.
+
+## 1. Wizard (default)
+
+```bash
+agent-sdk login
+agent-sdk slack create --dir .
+```
+
+Same Cursor account in the browser. **Add Slack to this agent**,
+approve Slack, pick the bot name. CLI writes
+`<PREFIX>_SLACK_BOT_TOKEN` / `<PREFIX>_SLACK_APP_TOKEN` and runs
+`doctor`.
+
+Prefix is the directory basename in upper snake (`jenny` →
+`JENNY`, `pr-approver` → `PR_APPROVER` → `PR_APPROVER_SLACK_*`).
+`--prefix` / `--no-prefix` override. Dev and prod are separate
+apps; `--prod` is the prod app. `--name` / `--icon` /
+`--channel-posts` / `--slack-team` prefill the wizard.
+
+If Slack needs workspace-admin approval, keep the CLI running.
+Open the **Request approval** link it prints. Managed install
+does not file the request. After approval, **Retry** in the
+wizard.
+
+`create` scaffolds `agent/channels/slack.ts` when missing:
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  suggestedPrompts: [{ title: "Help", message: "How can you help me?" }],
+});
+```
+
+Return from dispatch handlers. Do not await long work in the
+handler.
+
+A second `slack create` for the same agent and env overwrites the
+app (same Slack app id, new manifest and tokens).
+`agent-sdk slack destroy` deletes it.
+
+Local serve does not need a hosted engine. Next
+`agent-sdk deploy` injects the stored secrets.
+
+## 2. Manual (`slack init --manual`)
+
+Only when they own the app. Preferred: Slack CLI
+(`~/.slack/bin/slack`). Paste at api.slack.com if the CLI is
+missing. Never `slack deploy`; Agent SDK serve owns Socket Mode.
+
+```bash
+agent-sdk slack init --manual --dir . --name "My Agent"
+# --slack-team T0123ABCD when several workspaces are logged in
+# --no-install to scaffold only
+```
+
+Writes `agent/channels/slack.ts` (`envPrefix` from the directory),
+manifests, a `.slack/` project (`get-manifest` → those JSON files),
+and `env.example`. `--channel-posts` subscribes `message.channels`
+/ `message.groups`. If Slack CLI is logged in, this installs the
+app. `--install` fails when that cannot run.
+
+Human gates, one at a time. Stop after each.
+
+1. **Install the app.** If `next` starts with "Ask the user to
+   install this Slack app", stop and prompt them. Slack CLI: they
+   run `slack login --no-prompt`, send `/slackauthticket <ticket>`,
+   then `slack login --ticket <ticket> --challenge <code>`, then
+   `slack app install --environment local --team <T> --force`.
+   Prod: `SLACK_ENV=deployed slack app install --environment
+   deployed --team <T> --force`. Fallback: Create New App → From a
+   manifest, start with `.slack/manifest.dev.json`.
+2. **Tokens.** Slack CLI leaves xoxb / xapp in that process only.
+   Copy the bot token from the app's OAuth page. Mint an app-level
+   token with `connections:write`. Put both in `.env.local` using
+   `env.example` names. If Slack CLI wrote `SLACK_*` to `.env`,
+   copy those values to the prefixed keys.
+3. **Doctor.**
+
+## 3. Doctor and smoke
+
+```bash
+agent-sdk slack doctor --prefix JENNY
+agent-sdk serve --dir . --dev
+```
+
+Green: `app_token`, `connections_open`, `bot_token`, `auth_test`.
+Log: `[agent-sdk/slack] Socket Mode connected`. Missing tokens
+idle the channel; `serve` continues.
+
+1. Invite the bot
+2. `@mention` or DM
+3. Thinking / Working, then a threaded reply
+4. Logs: `inbound kind=app_mention`, `session start`,
+   `reply delivered via postMessage|stream`
+
+## Watch channels (opt-in)
+
+Default is mentions + DMs only. To wake on new posts:
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  engagement: {
+    channelPosts: {
+      allow: ["#alerts"], // ["*"] for every joined channel
+      posts: "top-level",
+    },
+  },
+  onChannelPost: async (ctx, message) => ({}), // null = skip
+});
+```
+
+Pass `--channel-posts` on `create` / `init --manual`. Invite the
+bot to each watched channel. Mentions stay on `app_mention`; a
+later mention continues the watch thread.
+
+## Approvals (opt-in)
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  toolApprovals: true,
+});
+```
+
+Wizard enables interactivity when this is set. Server tools on
+`local` only. Parked calls die on host restart. Cards truncate
+args; execution uses the full input.
+
+---
+
 Source: /docs/storage.md
 
 # Storage
@@ -8617,7 +11410,7 @@ not on `PATH`, use `npx @cursor/july`.
 | Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](/docs/guides/mcp-oauth.md) and
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 ## What if a secret showed up in a terminal transcript?