@cursor/july 0.1.97 → 0.1.99

package/dist/docs/llms-full.txt

@@ -1088,6 +1088,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
@@ -5260,7 +7022,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 +7050,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
@@ -6074,6 +7830,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 +9039,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