@cursor/july 0.1.109 → 0.1.111

package/dist/docs/design/runtime-abstraction.md

@@ -1,1756 +0,0 @@
-# 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:** [agent-config.md](/docs/reference/agent-config.md#choose-a-runtime)
-> (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. |
-| [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.