@cursor/july 0.1.96 → 0.1.99

package/dist/docs/llms-full.txt

@@ -693,9 +693,10 @@ use `UPPER_SNAKE_CASE`. Commit names only; set their values after
 creating the deployment. Names beginning with `CURSOR_` are reserved.
 
 For `defineConnection({ url, oauth: true })`, declare
-`MCP_OAUTH_<CONNECTION>_*` in `secretNames`, authorize with
-`agent-sdk mcp oauth <connection> --store`, then redeploy. See
-[Host MCP OAuth](/docs/guides/mcp-oauth.md).
+`MCP_OAUTH_<CONNECTION>_*` in `secretNames`. Finish Connect for the
+current process. Run `agent-sdk mcp oauth <connection> --store` and
+redeploy so the next pod sees the secrets.
+See [Host MCP OAuth](/docs/guides/mcp-oauth.md).
 
 Run `agent-sdk validate` before deploying. It reports invalid domains and
 secret names as warnings, so fix them even when validation exits zero.
@@ -943,7 +944,7 @@ A self-hosted server can read these credentials.
 | Slack tokens | Slack channels | `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent |
 | GitHub webhook secret | delivery signature verification | `GITHUB_WEBHOOK_SECRET`, same value on server and signer |
 | GitHub API | outbound API calls | a GitHub App (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` + installation id) or `GITHUB_TOKEN` / `gh auth login` |
-| MCP connection tokens | authored MCP connections | env vars your `mcp-connections/*.ts` read, or host OAuth secrets from `agent-sdk mcp oauth <name> --store` (`MCP_OAUTH_*`; see [Host MCP OAuth](/docs/guides/mcp-oauth.md)) |
+| MCP connection tokens | authored MCP connections | env vars your `mcp-connections/*.ts` read, or host OAuth secrets from hosted Connect / `agent-sdk mcp oauth <name> --store` (`MCP_OAUTH_*`; see [Host MCP OAuth](/docs/guides/mcp-oauth.md)) |
 
 Use a dedicated Cursor key per host. `agent-sdk whoami` shows the active
 credential. `logout` removes the stored key from the host; revoke the key
@@ -1087,414 +1088,1765 @@ Continue with these pages:
 
 ---
 
-Source: /docs/design/agsh.md
+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`:
 
-# agsh: a shell for deployed agents
+```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;
+}
 
-## What this is
+/**
+ * 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) };
+}
 
-`agsh` (agent shell) is a standalone CLI that connects to one agent-sdk
-deployment and turns the agent's live tool surface into commands. Every tool
-the deployment can execute (authored server tools and tools provided by the
-agent's MCP connections) becomes a subcommand with a synopsis derived from its
-input schema, a man-page style `--help`, and a place in an interactive shell.
+/**
+ * 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 });
+}
 
-It is a separate binary and a separate package from `agent-sdk`. The
-`agent-sdk` CLI stays what it is today: the developer workflow tool for
-authoring, validating, deploying, and debugging agent projects. `agsh` is the
-operator's tool for working *inside* one deployed agent. The split also keeps
-heavy presentation dependencies (markdown rendering, syntax highlighting, the
-shell interpreter) out of `@cursor/july`, which ships to every agent project.
+/**
+ * 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) };
+}
 
-## The experience
+function cloudRuntime(cloud: AgentCloudOptions): CloudRuntime {
+  return { kind: "cloud", cloud };
+}
 
+function grokbotRuntime(): GrokbotRuntime {
+  return { kind: "grokbot" };
+}
 ```
-$ agsh help                        # list of commands, man-page style
-$ agsh read --help                 # man-page style: NAME, SYNOPSIS, DESCRIPTION, OPTIONS
-$ agsh read /repo/README.md
-$ agsh datadog_list_monitors --query "service:api"
-$ agsh                             # bare: interactive shell on a TTY, script from stdin otherwise
-❯ ls /repo | grep -i readme
-❯ read /repo/config.json | jq .version
+
+`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" }],
+  }),
+});
 ```
 
-Every invocation binds to the deployment's latest session by default, with
-`--session` and `--continuation-token` overrides, and prints the session
-identifier as a final stderr line.
+`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.
 
-## Configuration
+### Backward compatibility
 
-`agsh` is a client only; it never boots an agent. Every invocation needs a
-target deployment, given by flags or by environment variables. Flags always
-win over the environment.
+Today's fields stay on `defineAgent` and on Cursor
+`AgentOptions`. Constructors sit beside them. Nothing that
+compiles today is broken by Phase 2.
 
-Global command line options, accepted on every command and on the bare shell
-launch:
+```ts
+// Still valid. Deprecated. Same agent as localRuntime(opts).
+defineAgent({
+  runtime: "local",
+  local: { workspaceDir: "/repo", sandbox: true },
+});
 
-| Option | Environment default | Meaning |
-| --- | --- | --- |
-| `--target <url \| name>` | `AGENT_SHELL_TARGET` | The deployment to talk to: a URL is a local deployment (`http://127.0.0.1:39400/executor`), a name a production one (`change-monitor-executor`). |
-| `--team <team>` | `AGENT_SHELL_TEAM` | Team override for production resolution, when the login spans several. |
-| `--bearer-token <token>` | `AGENT_SHELL_BEARER_TOKEN` | Explicit bearer auth for a deployment that is not behind the Cursor login. |
-| `--session <id>` | | Bind to a specific session instead of the latest. |
-| `--continuation-token <token>` | | Bind by continuation token instead of session id. |
-| `--output <text\|json>` | | Result rendering: human-friendly views (default) or raw JSON. |
-| `-h`, `--help` | | Per-command help. |
-
-One parameter carries the whole target selection, and the value's shape
-encodes the mode: a URL (`http://` or `https://`) targets a local
-deployment, anything else names a production one. Two options with a
-precedence rule would invite exactly the confusion a target selector must
-not have; with one parameter the only rule is that the flag beats the
-environment. A URL is self-contained down to the agent because one local
-agent-sdk serve process hosts every agent of the project (change-monitor's
-dev stack mounts `/executor` and `/planner` from a single port); a
-production deployment is a single agent, so its name is the complete
-address (`--team` narrows resolution when the login spans several).
-Authentication defaults to the stored Cursor login (the same engine-access
-credential agent-sdk uses); `--bearer-token` is the escape hatch for direct
-deployments. Session flags are per invocation and have no environment
-default: a session is state, not configuration. Color output follows the
-`NO_COLOR` convention and TTY detection; there is no agsh-specific color
-setting. No configuration file: one environment variable pins a working
-target for a terminal session
-(`AGENT_SHELL_TARGET=change-monitor-executor`, or a URL for a local stack),
-which is the whole persistent-configuration need.
-
-With no target from flags or environment, every command fails with a message
-naming both ways to provide one.
-
-## Architecture
-
-### A new package
-
-A new workspace package (working name `packages/agsh`, bin `agsh`) that
-depends on `@cursor/july` for target resolution, stored Cursor login, and the
-HTTP client plumbing. It owns the presentation stack: `marked` for terminal
-markdown (moved out of `@cursor/july`), with syntax highlighting (`shiki`)
-arriving in the phase that renders code; the shell interpreter is
-purpose-built (see Rationale).
-No new abstraction seam between the two packages; `agsh` imports what it
-needs until a second consumer justifies extracting a thin client.
-
-### The tool catalog
-
-At startup `agsh` fetches one live catalog of everything invocable on the
-deployment. This is the piece the current `/v1/info` cannot provide: `/v1/info`
-projects the authored manifest, and connection tools only exist at runtime,
-resolved per session under the connection's auth. A new endpoint provides the
-live view (see Backend changes).
-
-Catalog entries carry exactly one identifier each: the tool name exactly as
-the agent sees it. Authored server tools keep their authored name (`read`).
-Connection tools appear under their model-facing advertised name (the
-sanitized passthrough name from `advertise-tools.ts`, e.g.
-`datadog_list_monitors`). The CLI never invents a different naming format:
-a tool name copied from a session transcript is a valid `agsh` command, and
-vice versa. Where a tool came from — the upstream connector name when the
-tool declares one, the connection name otherwise — is a field on the
-catalog entry, not part of the identifier.
-
-### Two command tiers
-
-Each catalog entry becomes a command, through one of two shapes:
-
-**Curated commands for builtin tools.** The well-known tool names (`ls`,
-`read`, `grep`, `glob`, `diff`, ...) get hand-designed, POSIX-flavored
-command shapes, hardcoded in `agsh` next to their titles. These tools are
-what an operator types all day; their shapes should feel like the unix
-commands they mirror, not like generated bindings. A curated shape decides
-which schema fields are positional operands and which are flags, and every
-input has exactly one spelling: an operand is only an operand, never also a
-flag.
-
-```
-$ agsh read /repo/package.json --limit 2
-{
-  "name": "change-monitor",
-→ ses_a99d1b69c329eb75a2ec8603
-
-$ agsh grep -i -A 2 toolEffect /repo/src
-src/tool-policy.ts:12:export type ToolEffect = "read" | "write";
-...
-→ ses_a99d1b69c329eb75a2ec8603
-
-$ agsh ls /repo --ignore-globs '*.test.ts' --ignore-globs 'node_modules/**'
-```
-
-`read` takes its path as an operand mapped to the schema's `path` field, with
-`--offset` and `--limit` as integer flags. `grep` follows POSIX grep:
-`grep [options] <pattern> [path]`, with the rg-style options (`-i`, `-A`,
-`-B`, `-C`, `--output-mode`, `--head-limit`) mapping onto the schema fields
-of the same names (kebab-cased). `ls` shows array input: an array field's flag repeats once
-per element. A curated shape binds to the deployment's live schema at
-startup; when a deployment's tool lacks the expected field, the command
-degrades to the generic shape below rather than guessing.
-
-A curated shape may also reformat the tool's text result toward the unix
-command's own output conventions: the VFS ls tool returns the model-facing
-tree (`  - name/` rows under a header), and `agsh ls` prints it as standard
-ls does, one name per line with the trailing slash kept on directories. The
-tool's result string itself stays what the model sees; when a result does
-not match the expected shape it prints verbatim.
-
-**Generated commands for MCP tools.** Connection tools are dynamically
-discovered, so no special treatment is possible; they get a uniform
-schema-derived mapping:
-
-- Every schema property is accepted as one flag, spelled as the
-  kebab-cased property name (`org_slug` → `--org-slug`) — the unix
-  convention; kebab collisions gain a numeric suffix. Properties already
-  shaped like flags (grep's `-i`) stay literal. No positionals, no other
-  aliases.
-- Object-typed properties flatten recursively into one flag per leaf,
-  dash-joined (`--telemetry-context` for `telemetry.context`), so every
-  option reads as a plain value; a free-form object with no declared
-  properties stays one JSON-valued flag. A leaf is required only when its
-  whole ancestor chain is.
-- Values are coerced by schema type: booleans are valueless flags, numbers
-  and integers are parsed, arrays accept the flag repeated once per element,
-  enums are validated before the call.
-
-```
-$ agsh datadog_list_monitors --query "service:api" --limit 10
-```
-
-In both tiers `-h`/`--help` and the global target and session flags are
-reserved and injected, a flag that names no schema property fails before any
-request (listing the tool's actual properties), and the bound session prints
-as a final stderr line.
-
-### Result rendering
-
-Raw JSON on a terminal is not an experience for people, so `--output=text`
-(the default) renders structured results through a small set of views,
-selected automatically by the shape of the value each call actually returned;
-tool metadata plays no part, since most tools advertise no output schema, and
-many return structured data as JSON text. A string result that parses as a
-JSON object or array counts as structured. An array of objects renders as a
-table (columns are the union of keys, missing cells stay blank, the table
-clamps to the terminal width); a single object renders as a property view
-(aligned keys, scalar lists as bullets, nested structures indented); an
-object that is nothing but an error wrapper renders as an `Error:` line;
-plain text prints verbatim. `--output=json` renders the structured value as
-raw JSON. The rendering never depends on the TTY: piped and interactive
-output carry the same content, only color follows TTY detection.
-
-### Help rendering
-
-`--help` on a tool renders a man-page layout: NAME (the tool name, with the
-tool's `title` beside it when the catalog carries one; titles are curated
-data, never derived from the description), SYNOPSIS (operands from the
-curated shape; options never enumerate — they summarize as `[options...]`,
-man-page style, so the line stays bounded), DESCRIPTION (the tool
-description rendered as terminal markdown), OPERANDS (positional arguments,
-curated commands only), and OPTIONS. Descriptions of operands and options
-come from the schema's property descriptions. Effect and approval metadata
-render as notes when declared. Everything except the curated shape derives
-from `GET /v1/tools/:name`; nothing else is hand-written per tool.
-
-```
-$ agsh read --help
-NAME
-    read - Read a file
-
-SYNOPSIS
-    read [options...] <path>
-
-DESCRIPTION
-    Reads a file from the local filesystem. This tool can also read image
-    files when called with the appropriate path. Formats supported:
-    jpeg/jpg, png, gif, webp.
-
-OPERANDS
-    <path>
-        The absolute path of the file to read.
-
-OPTIONS
-    --offset <integer>
-        The line number to start reading from. Positive values are 1-indexed
-        from the start of the file. Negative values count backwards from the
-        end. Only provide if the file is too large to read at once.
-
-    --limit <integer>
-        The number of lines to read. Only provide if the file is too large
-        to read at once.
-
-NOTES
-    Effect: read (performs no writes).
-```
-
-`agsh help` lists the available command names grouped by source, authored
-tools first, then one group per upstream connector (its name is the group
-header — one aggregating connection can host tools from several connectors,
-and the connector name is what an operator recognizes). Each row is the
-name, with the title beside it when the tool declares one; everything else
-lives behind the command's `--help`:
-
-The agent's description renders as a DESCRIPTION section when the deployment
-declares one (`/v1/info` carries both name and description).
-
-```
-$ agsh help
-NAME
-    change-monitor-executor
-
-DESCRIPTION
-    Executes monitoring plans against changed code.
-
-COMMANDS
-    diff                     Show workspace changes
-    glob                     Find files by pattern
-    grep                     Search file contents
-    ls                       List a directory
-    read                     Read a file
-    report_change_issue
-    report_change_succeeded
-
-DATADOG
-    datadog_list_monitors    List monitors
-    ...
-
-Run any command with --help for its synopsis and options.
-```
-
-### Shell mode
-
-Invoked bare, `agsh` starts a shell. On a TTY this is a REPL; on a pipe it
-reads a script from stdin, so `echo 'ls /' | agsh` and here-docs work.
-
-The interpreter is purpose-built and minimal: tokenizing (quotes, escapes),
-pipelines, and `;` / `&&` / `||`. The command namespace is exactly the
-deployment's tool catalog plus a small curated set of local pipe filters
-(`head`, `tail`, `wc`, stdin-filtering `grep`), so a tool name can never be
-shadowed. There is no local filesystem, no variables, no control flow: agsh
-has nothing local to operate on, and every command is a single traced
-`POST /v1/tools/:name` call.
-
-The shell binds one session identity at launch (latest by default) and keeps
-it for the whole run, so a sequence of tool calls observes one consistent
-session context.
-
-## Backend changes on the agent-sdk runtime
-
-Two read endpoints, mirroring the invocation path:
-
-**`GET /v1/tools`: the live tool listing.** Returns the session's tool
-namespace exactly as a turn would assemble it: authored server tools plus the
-advertised passthrough tools synthesized from connections, under their
-model-facing names. Entries are light (name, source, and `title` when one is
-known); everything else lives behind the detail endpoint. Titles have two
-sources and no new authoring surface: connection tools inherit the upstream
-server's MCP title, which the host already propagates length-capped off
-listings; tools that do not come from MCP get theirs from a hardcoded
-name-to-title table in the runtime's endpoint implementation, covering the
-well-known tool names. A tool in neither place has no title. Accepts the same
-optional session binding as invocation (`session` or `continuationToken`)
-because advertised inventories can be tenant-scoped and resolved per session.
-Implementation reuses the existing plumbing: the discovered manifest for
-authored tools and the advertise-tools synthesis (`McpHost.listTools`, or the
-`oneOff` path when per-session auth substitution applies) for connection
-tools. This is not a duplicate of `/v1/info`: the info document stays the
-static authored manifest; the listing is the runtime view that only the
-running deployment can answer.
-
-**`GET /v1/tools/:name`: one tool's full description.** Description, input
-schema, output schema when declared, effect when declared, approval
-requirement, and source connection. Same path as invocation
-(`POST /v1/tools/:name`), different method: GET describes what POST executes,
-for the same identifier.
-
-Invocation needs no new naming scheme. Advertised connection tools are
-synthesized as ordinary server tools in the session's namespace, so
-`POST /v1/tools/:name` addresses them by their model-facing name like any
-authored tool, with the same session binding, policy checks, and per-call
-tracing. (The direct-call path did need the synthesis step added: it now
-resolves the advertised listing for the call's session identity when the
-authored lookup misses.)
-
-Phase 1 ships the minimal runtime surface agsh calls: the `effect`
-projection in `/v1/info` (rendered in per-tool help), the scratch-workspace
-fallback on direct calls, and `continuationToken` binding on
-`POST /v1/tools/:toolName`. The detail endpoint in phase 2 also closes the
-output-schema gap; `/v1/info` stays as it is.
-
-## Local development loop
-
-`factory/change-monitor` is the test bed. Its `pnpm start` already serves the
-planner and executor locally through the agent-sdk dev runtime
-(`agent-sdk serve --dir . --dev`). The loop:
-
-1. `cd factory/change-monitor && pnpm start` (local stack, both agents).
-2. `agsh --target http://127.0.0.1:<port>/<agent>` against it, via a dev shim
-   analogous to `agent-sdk-dev` so the CLI runs from the worktree.
-3. Iterate end to end: VFS verbs (`ls`, `read`, `grep`, `glob`, `diff`) for the
-   authored-tool path, and the planner's tenant connectors for the
-   connection-tool path once `GET /v1/tools` exists.
-
-## Removing the inspector surface from agent-sdk
-
-The inspector CLI is still on development branches, so nothing migrates: the
-CLI-side code is removed from `agent-sdk` and `agsh` is built in its place.
-
-- The verb commands (`ls`, `read`, `grep`, `glob`, `diff`) become the
-  curated tier: their hand-designed shapes, schema-binding logic (including
-  the candidate-field fallback), and session binding carry over. The
-  schema-to-argv flag mapping seeds the generated tier for MCP tools.
-- The `tools` and `skills` commands disappear entirely. `agsh help` and
-  per-tool `--help` are the discovery surface.
-- `marked` and `shiki` leave `@cursor/july`; agsh's help rendering takes
-  `marked`, and `shiki` returns when agsh ships syntax highlighting.
-  `agent-sdk` keeps its developer workflow commands unchanged.
-
-## Plan
-
-1. **Package and core invocation.** Create the package, port target
-   resolution, the schema-to-argv mapping, and help rendering from the
-   inspector code. Authored tools only, against the existing endpoints.
-   Verified end to end on the local change-monitor stack.
-2. **Live catalog.** Add `GET /v1/tools` and `GET /v1/tools/:name` to
-   the agent-sdk runtime, with the hardcoded title table for non-MCP tools, and verify
-   direct invocation resolves advertised connection tools by their
-   model-facing names. Connection tools appear as commands. Verified against
-   the planner's connectors.
-3. **Shell mode.** The purpose-built mini-shell: REPL on TTY, script on
-   stdin, tools as the command namespace, one session per shell run.
-4. **Cleanup.** Remove the inspector CLI surface and presentation
-   dependencies from `@cursor/july`.
-
-## Rationale and rejected alternatives
-
-**Why not extend `agent-sdk`.** The audiences differ: `agent-sdk` is for the
-person building and deploying an agent; this tool is for the person operating
-inside one. Bundling also forces every agent project to carry markdown
-rendering, syntax highlighting, and a bash interpreter it never uses.
-
-**Name.** `agsh` reads as "agent shell", is four characters, collides with
-nothing common, and works as a shell prompt name. Considered: `august`
-(pairs with `july` but says nothing about purpose), `toolsh` (awkward to
-pronounce), `cursor-shell` (too broad; this is scoped to one agent).
-
-**Why a REST catalog instead of the MCP endpoint.** The deployment already
-speaks MCP at `/v1/mcp/tools`, including a per-connection bridge, but the
-bridge is bound to an active turn and speaks JSON-RPC. The CLI wants a plain
-authenticated GET with session binding that returns the assembled tool
-namespace under the names the model sees. Wrapping that in MCP framing buys
-nothing for a first-party client.
-
-**Why a purpose-built interpreter instead of just-bash.** just-bash was the
-original plan (a full bash emulation with a custom-command extension point),
-and a prototype disproved it: custom commands replace its coreutils but can
-never shadow its shell builtins, and `read`, `test`, `type`, and `help` are
-builtins — so the flagship `read` tool is unreachable, and the precedence is
-not ours to control (vercel-labs owns the package). No other embeddable JS
-shell interpreter has a workable custom-command story (mvdan-sh's JS build
-does not expose one; bash-parser is a parser only). agsh also needs almost
-none of bash: no local filesystem, no variables, no control flow — just
-tokenizing, pipelines, and a command namespace it fully owns. A TypeScript
-REPL with tools as async functions (the shape of change-monitor's `script`
-tool) was considered and kept as a possible later addition; it trades away
-the unix muscle memory the curated commands exist for.
+// 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.
 
 ---
 
@@ -2795,8 +4147,9 @@ Source: /docs/guides/mcp-oauth.md
 Use host MCP OAuth when your agent talks to a remote MCP server that
 speaks OAuth, and you want credentials on the serve host (or the hosted
 engine) instead of a Cursor account connector. Local login writes tokens
-next to your Cursor credentials. `--store` copies them onto the
-deployment as secrets so prod can reconnect after a redeploy.
+next to your Cursor credentials. `--store` copies those tokens onto the
+deployment as secrets so prod can reconnect after a redeploy. Hosted
+Connect lets the current process retry.
 
 The companion skill is
 [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
@@ -2807,8 +4160,8 @@ The companion skill is
   flow (`agent-sdk mcp oauth <connection>`)
 - Keep tokens in `mcp-auth.json` under the CLI config directory, bound
   to that connection's resource URL
-- Upsert deployment secrets with `--store` so hosted engines seed the
-  same tokens from env
+- Upsert deployment secrets with `--store` so the next deploy seeds the
+  same tokens from env. Hosted Connect lets the current process retry.
 - Use `advertiseTools: true` when local turns should call the server by
   name. Host tools can still call it through `ctx.host.mcp`.
 
@@ -2888,7 +4241,16 @@ connection URL (tokens are bound to the resource URL).
 
 ## How do I store credentials on a hosted deployment?
 
-Authorize once, then push secrets to the deployment:
+Authorize once. Then get the tokens onto the deployment.
+
+On a hosted engine, finishing Connect lets the current process retry.
+Self-hosted serve writes tokens locally only.
+
+`--store` from a signed-in laptop is the reliable way to put
+`MCP_OAUTH_*` on the next deploy. If `agent-sdk secrets list` is
+empty, run `--store` and redeploy.
+
+From a laptop, push secrets with the CLI:
 
 ```bash
 agent-sdk mcp oauth inventory --store
@@ -2906,13 +4268,21 @@ agent-sdk mcp oauth inventory --store
 | `MCP_OAUTH_<NAME>_CLIENT_ID` | dynamic client id when registration returned one |
 
 You must be signed in (`agent-sdk login`) with permission to set secrets
-on that slug. Secrets apply on the **next** deploy; run
-`agent-sdk deploy` (or wait for your usual deploy path) after `--store`.
+on that slug. Secrets apply on the **next** deploy. Run
+`agent-sdk deploy` after `--store`. A fresh pod sees `MCP_OAUTH_*`
+only after that deploy.
 
 On the engine, when `mcp-auth.json` is empty, serve seeds the OAuth
 provider from those env vars so host MCP calls work without a browser
 on the pod.
 
+These secrets are deployment-wide. Anyone who can list or set secrets
+on that slug, and the hosted engine's runtime env, can use them. That
+is the same blast radius as `--store`. They are not scoped to the
+caller who clicked Connect. `cursorAccount: true` tokens stay on the
+Cursor backend for the deployment service account and do not use
+`MCP_OAUTH_*`.
+
 ## How do host tools call the server?
 
 ```ts
@@ -2932,7 +4302,7 @@ an allowlist or other deterministic gate.
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Add `oauth: true` on that connection, or pick the right connection name |
 | Callback never completes | Keep port `8787` free; finish the browser login on this machine |
-| Hosted calls unauthorized after `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
+| Hosted calls unauthorized after Connect or `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
 | Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
 
 ## What's next
@@ -3162,16 +4532,14 @@ Source: /docs/guides/slack.md
 
 # Slack agents
 
-The Slack channel puts your agent in Slack as its own Socket Mode bot.
-`agent-sdk slack create` opens the dashboard wizard and writes tokens
-to `.env.local`. To own the Slack app yourself, run
-`agent-sdk slack init --manual` and paste the manifests at
-[api.slack.com](https://api.slack.com/apps). Socket Mode has no
-public Request URL. Replies stream in threads, with tool "thinking" steps,
-suggested prompts, and opt-in approval buttons.
+The Slack channel is a Socket Mode bot. The app connects out, so you
+don't need a public Request URL. Mentions and DMs start a thread.
+Replies stream there, with thinking steps and suggested prompts.
 
-The companion skill is
-[`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
+Use `agent-sdk slack create` when Cursor should own the Slack app. Use
+`agent-sdk slack init --manual` when you own it. Commands and flags live
+in the [CLI reference](/docs/reference/cli.md#slack). Coding agents should
+follow [`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
 
 ## Define the channel
 
@@ -3181,35 +4549,23 @@ Author `agent/channels/slack.ts` with `slackChannel()` from
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN
 export default slackChannel();
-
-// Multi-agent serve: one Slack app (and token pair) per agent
-export default slackChannel({ envPrefix: "WEATHER_AGENT" });
-// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
 ```
 
-By default the channel connects over Socket Mode (the app connects
-outward, so it works from behind any firewall) and responds only to
-`app_mention` events and direct messages. It also refuses Slack Connect
-users, guests, and senders from other workspaces. Threads bind to
-sessions with `continuationToken = channelId:threadTs`, so a thread is
-one durable conversation. Replies stream (`chat.startStream` /
-`appendStream` / `stopStream`) with a plain-message fallback, a rotating
-status shows while the agent works, and the pack sets thread titles and
-suggested prompts. When a Slack API is unavailable (`method_not_found`,
-`missing_scope`), the pack degrades to `postMessage` instead of failing.
+`slackChannel()` reads `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. Pass
+`envPrefix: "WEATHER_AGENT"` to read `WEATHER_AGENT_SLACK_BOT_TOKEN`
+and `WEATHER_AGENT_SLACK_APP_TOKEN` instead. Use a prefix when one
+host serves several Slack bots.
 
-Missing tokens leave the channel idle (`channel idle … missing
-credentials`) rather than failing `serve`. That's useful when you mount
-many agents and only some have Slack apps.
+A thread is one conversation. The bot answers mentions and DMs. It
+refuses Slack Connect users, guests, and people from other workspaces.
+Missing tokens leave this channel idle. The rest of `serve` still
+starts.
 
 ## Control who can message the agent
 
-External senders are blocked by default. Slack Connect users, guests, and
-people whose home workspace is not the install team never reach the
-handler. Set `blockExternals: false` only when the agent should serve
-people outside your org:
+External senders are blocked. Set `blockExternals: false` only when
+people outside your org should reach the agent:
 
 ```ts
 export default slackChannel({
@@ -3217,9 +4573,8 @@ export default slackChannel({
 });
 ```
 
-Sessions are thread-scoped by default, so anyone in the thread can
-continue. Restrict follow-ups to the person who started the session with
-`respondTo: "author"`:
+Anyone in the thread can continue it. Restrict follow-ups to the person
+who started the session with `respondTo: "author"`:
 
 ```ts
 export default slackChannel({
@@ -3229,237 +4584,143 @@ export default slackChannel({
 
 ## Set it up
 
-For a dedicated Socket Mode bot, run `agent-sdk slack create`. The CLI
-opens the signed-in Cursor dashboard wizard. Slack consent, bot name,
-and admin-approval wait happen there. Tokens are stored as deployment
-secrets and written to `.env.local`. They are never shown. Do not paste
-a manifest at [api.slack.com](https://api.slack.com/apps) unless you
-are on the [manual setup](#manual-setup) path.
-
-Bots that already have tokens in `.env.local` keep working. Skip the
-wizard unless you want a Cursor-managed app.
+`slack create` opens the Cursor dashboard wizard. Finish Slack consent
+and the bot name there. The CLI writes tokens to `.env.local` and never
+prints them. Skip the wizard if those tokens are already set, unless
+you want a Cursor-managed app.
 
 ### Provision with the CLI
 
 ```bash
-agent-sdk slack create --dir .          # dev app (default)
-agent-sdk slack create --dir . --prod   # prod app
+agent-sdk slack create --dir .
+agent-sdk slack create --dir . --prod
 ```
 
-`slack create` needs a signed-in host (`agent-sdk login` or
-`CURSOR_API_KEY`). It scaffolds `agent/channels/slack.ts` when the file
-is missing, opens the dashboard wizard, and waits. Finish **Add Slack
-to this agent** in the browser as the same Cursor account. The CLI
-writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
-`<dir>/.env.local`, then runs `doctor`. Serve and smoke it as described
-[below](#wire-the-env-and-verify).
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Slack to this agent** as the same Cursor account. Then run
+`agent-sdk slack doctor --prefix MY_AGENT` and serve:
 
-If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request. Open Slack's
-**Request approval** page (the CLI prints the link; the same URL is
-**Send a reminder** after you submit). After an admin approves, click
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Invite the bot and mention it, or DM it. Expect a Thinking status,
+then a threaded streaming reply.
+
+If Slack needs a workspace admin, keep the CLI running. Open the
+**Request approval** link it prints. After an admin approves, click
 **Retry** in the wizard.
 
-Useful companions: `--name` / `--icon` / `--channel-posts` prefill the
-wizard. `--slack-team T0123ABCD` picks a workspace when several are
-connected. A second `slack create` for the same agent and env overwrites
-that Slack app. It keeps the Slack app id and replaces the manifest and
-tokens. `agent-sdk slack destroy` deletes the provisioned app.
-`agent-sdk slack icon <source>` updates the icon later.
+`slack destroy` deletes the Cursor-managed app. `slack icon` updates
+its icon. A second `slack create` for the same agent and environment
+replaces that app's manifest and tokens.
 
 ### Provision from the dashboard
 
 The same wizard is on [Deployed Agents](https://cursor.com/dashboard).
-Open **Integrations** on an agent and click **Add Slack to this agent**,
-or follow the URL `slack create` printed.
+Open **Integrations** and click **Add Slack to this agent**.
 
-A first-run agent that has no hosted engine yet shows **Not deployed
-yet**. Local `agent-sdk serve` works from `.env.local`. The next
-**Deploy** injects the stored secrets; there is no Slack-only Redeploy.
+Local `agent-sdk serve` reads `.env.local`. The next deploy injects the
+stored secrets.
 
-If Slack needs admin approval, the wizard waits. Click **Request
-approval** to file the request in Slack (that same page later sends a
-reminder). After an admin approves, click **Retry**.
+If Slack needs admin approval, click **Request approval**, then
+**Retry** after an admin approves.
 
-The app row's menu covers later care: rename, set an icon, rotate
-tokens, remove the app, or disconnect the workspace.
+The app row's menu covers rename, icon, token rotation, removal, and
+workspace disconnect.
 
-### Wire the env and verify
+### Create your own Slack app
 
-`agent-sdk slack create` already wrote the tokens to `.env.local`, so
-after provisioning skip straight to `doctor`. `serve` / `dev` /
-`slack doctor` load that file (real environment variables always win).
+`slack init --manual` is for an app you own. It writes the channel file
+and Slack manifests. When Slack CLI (`~/.slack/bin/slack`) is logged
+in, it installs the app. When it isn't, install the app yourself.
 
 ```bash
-agent-sdk slack doctor --prefix MY_AGENT
+agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-Proceed when `app_token`, `connections_open`, `bot_token`, and
-`auth_test` are all green. Then serve and smoke it:
+Install Slack CLI if you need it:
 
 ```bash
-agent-sdk serve --dir . --dev
-# expect: [agent-sdk/slack] Socket Mode connected
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
 ```
 
-Invite the bot to a channel and @mention it (or DM it). Expect the
-Thinking… status, then a threaded streaming reply, with correlated
-server logs (`inbound kind=app_mention`, `session start`,
-`reply delivered via stream|postMessage`).
+Log in with `slack login --no-prompt`. In Slack, send
+`/slackauthticket <ticket>`, then
+`slack login --ticket <ticket> --challenge <code>`. Install the
+workspace app with `slack app install`. Create a separate production
+app the same way.
 
-### Manual setup
+Or paste `.slack/manifest.dev.json` at
+[api.slack.com/apps](https://api.slack.com/apps) (**Create New App** →
+**From a manifest**). Repeat with `.slack/manifest.prod.json`. Dev and
+prod are separate Slack apps.
 
-`slack init --manual` is for a Slack app you own at api.slack.com. You
-paste the generated manifests and mint tokens yourself. Use this when
-you want an unmanaged app, or when the dashboard wizard is not an
-option.
-
-```bash
-agent-sdk slack init --manual --dir . --name "My Agent"
-```
+Then put a bot token (`xoxb-...`) and an app-level token with
+`connections:write` (`xapp-...`) in `.env.local`. Use the names
+`slack init --manual` printed. Run `slack doctor` and serve as above.
 
-That writes `agent/channels/slack.ts`, Slack manifests under the
-project state directory, `env.example`, and `setup-status.json`.
-`--no-prefix` uses shared `SLACK_*` variables on
-a single-agent host. `--prefix CUSTOM` overrides the directory-derived
-prefix. `--channel-posts` subscribes the manifests to channel-post
-events.
-
-`slack manifest --env both` regenerates the JSON files without
-touching the channel file.
-
-#### Create the apps
-
-This phase needs someone with permission to create Slack apps.
-
-1. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New
-   App** → **From a manifest**.
-2. Paste `manifest.dev.json` and create the dev app.
-3. Repeat with `manifest.prod.json`. Dev and prod are separate Slack
-   apps with separate tokens.
-
-#### Install and mint tokens
-
-For each app: **Install to Workspace** and copy the Bot User OAuth Token
-(`xoxb-…`). Then under **Basic Information → App-Level Tokens** create a
-token with scope `connections:write` and copy it (`xapp-…`).
-
-Put the pair in `.env.local` using the names from `env.example`, then
-run `slack doctor` and serve as [above](#wire-the-env-and-verify).
+Serve this app with Agent SDK. Do not run `slack deploy`.
 
 ## Choose when the agent engages
 
-Mentions and DMs are on by default. Watching channels means dispatching
-on new posts without a mention. That's an explicit opt-in:
+Mentions and DMs are on. Watching channel posts without a mention is
+opt-in:
 
 ```ts
 export default slackChannel({
   envPrefix: "TRIAGE",
   engagement: {
-    // mentions / directMessages default to true
     channelPosts: {
-      allow: ["#triage-alerts"], // use ["*"] for every joined channel
-      posts: "top-level",       // default: thread replies never dispatch
-      debounceMs: 15_000,       // optional: let rapid edits settle
-      includeBotPosts: false,   // default: bot-authored posts never dispatch
+      allow: ["#triage-alerts"],
+      posts: "top-level",
+      debounceMs: 15_000,
     },
   },
-  onChannelPost: async (ctx, message) => {
-    // same contract as onAppMention: return null to skip
+  onChannelPost: async (_ctx, message) => {
     return message.markdown.length > 20 ? {} : null;
   },
 });
 ```
 
-Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app. Pass `--channel-posts` on `slack create` or
-`slack init --manual`. The bot must also be a member of each watched
-channel.
-
-Set `allow: ["*"]` to watch every channel the bot has joined.
+Pass `--channel-posts` on `slack create` or `slack init --manual` so
+the Slack app receives those events. The bot must be in each watched
+channel. `allow: ["*"]` watches every joined channel.
 
-Set `includeBotPosts: true` when the posts worth watching come from bots:
-alert feeds, webhook integrations, or other agents posting notes. The
-watching app's own posts stay dropped either way, matched by the `bot_id`
-and bot user id from `auth.test`, so an agent can never dispatch on its
-own replies. Use this for a bot-fed alerts channel.
+Set `includeBotPosts: true` for alert feeds and other bots. This app
+never wakes on its own posts.
 
 ## Prepare work on the host
 
 Mention and DM handlers may return a prepared `message`,
-`workspaceFiles`, or `cloud` block. It's the same host-prep pattern as
+`workspaceFiles`, or `cloud` block. Use the same host-prep pattern as
 [custom channels](/docs/guides/webhooks.md#prepare-on-the-host-then-hand-off).
-PR agents use it: extract a PR URL from the mention text and run the
-same host path as the HTTP channel.
 
-Slack file uploads are attached automatically. Images become vision input.
+Slack file uploads attach automatically. Images become vision input.
 Supported documents become workspace files for the turn.
 
 ## Add approval buttons
 
-Tools with `needsApproval` park until a person decides. Route that
-through Slack with one flag:
+Tools with `needsApproval` park until a person decides. Post those
+decisions in Slack with one flag:
 
 ```ts
 export default slackChannel({
-  toolApprovals: true, // posts Block Kit Approve/Deny cards + routes clicks
+  toolApprovals: true,
 });
 ```
 
-Approval cards need interactivity on the Slack app. Recreate with
-`slack create` if clicks do nothing. Composing events by hand: spread
-`buildToolApprovalEvents({ credentials })` into `events` and set
-`interactivity: true` on the channel so Socket Mode routes the clicks.
-
-Cards show redacted, truncated arguments (Block Kit size limits);
-execution still uses the full validated input, so review sensitive tools
-in the playground when the arguments may exceed the card. Approvals
-exist for `execution: "server"` tools on the local runtime only, and
-parked calls do not survive a host restart. The full lifecycle is in
+The Slack app needs interactivity. Recreate it with `slack create` if
+clicks do nothing. Cards show redacted, truncated arguments. Execution
+still uses the full input, so review sensitive tools in the playground
+when the card may hide fields. The lifecycle is in
 [Human-in-the-loop](/docs/guides/human-in-the-loop.md).
 
 ## Run several agents on one host
 
-One Slack app and token pair per agent. Never share a pair across
-agents in the same process. `envPrefix` keeps them apart
-(`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`, …), and agents without tokens mount
-with their Slack channel idle while everything else serves normally.
-
-## Keep the channel healthy
-
-Two habits matter most.
-
-- Don't `await` long work inside Slack dispatch handlers. The pack
-  dispatches through `waitUntil` and streams as the turn progresses.
-- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
-  playground can list and stream Slack sessions and resolve their parked
-  approvals (the audit trail records the HTTP caller). Bearer-auth hosts
-  stay strict: Slack approvals must come from Slack interactivity or a
-  matching principal.
-
-## CLI reference
-
-The `slack` subcommands cover setup end to end.
-
-```bash
-agent-sdk slack setup                     # printed setup guide
-agent-sdk slack create --dir .            # dashboard wizard (dev app)
-agent-sdk slack create --dir . --prod     # prod app
-agent-sdk slack destroy --dir .           # delete the provisioned app
-agent-sdk slack icon ./icon.png --dir .   # set the provisioned app's icon
-agent-sdk slack init --manual --dir .     # manifests to paste at api.slack.com
-agent-sdk slack manifest --env both       # regenerate those JSON files
-agent-sdk slack doctor --prefix MY_AGENT  # token / connectivity checks
-```
-
-## What's next
-
-Continue with these pages:
-
-- [Human-in-the-loop](/docs/guides/human-in-the-loop.md): the approval lifecycle
-  behind `toolApprovals`
-- [Webhooks and custom channels](/docs/guides/webhooks.md): the mechanism this
-  pack is built on
+Give each agent its own Slack app and token pair. Set `envPrefix` so
+the names don't collide (`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`).
+Agents without tokens stay idle. The others still serve.
 
 ---
 
@@ -4058,7 +5319,7 @@ npx @cursor/july docs
 | Building a new agent with Cursor | [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) |
 | Turning a Cursor Automation into a project | [Convert a Cursor Automation](/docs/guides/convert-automation.md) |
 | Wiring an agent to Slack | [Slack guide](/docs/guides/slack.md) |
-| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
+| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
 | Wiring an agent to GitHub webhooks | [GitHub guide](/docs/guides/github.md) |
 | Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
 | Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
@@ -4086,6 +5347,8 @@ npx @cursor/july docs
   collects the PR, the model records, then comments.
 - [Keep a code wiki current after merge](/docs/templates/code-wiki.md):
   update in-repo `wiki/` pages when a pull request merges.
+- [Keep AGENTS.md current from last week's work](/docs/templates/agents-md.md):
+  pull rules out of merged PRs and Slack, then open a follow-up PR.
 - [Security reviewer](/docs/templates/security-reviewer.md): review pull
   requests for exploitable bugs and post one comment.
 - [Answer security questions in Slack](/docs/templates/security-help.md):
@@ -4119,8 +5382,8 @@ npx @cursor/july docs
 - [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): park a
   tool call until a person signs off.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): authorize
-  `oauth: true` connections, store tokens locally, and `--store` them
-  on hosted deployments.
+  `oauth: true` connections, store tokens locally, and persist them
+  on hosted deployments (`--store`).
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): every agent is an MCP
   server; agents can delegate to each other.
 - [Cloud runtime](/docs/guides/cloud-runtime.md): run turns on Cursor cloud
@@ -4727,8 +5990,8 @@ When every slot is busy, newly admitted turns queue FIFO instead of
 failing: the stream records a durable `turn.queued` event with the
 queue position, `GET /v1/sessions` reports `queued: true`, and each
 queued turn starts as soon as a slot frees. A queued turn still counts
-as running for busy semantics: follow-ups preempt it, and direct tool
-calls get `409 session_busy`. Omit for unlimited.
+as running for busy semantics: follow-ups preempt it, and direct
+write-effect tool calls get `409 session_busy`. Omit for unlimited.
 
 ```ts
 export default defineAgent({
@@ -5507,8 +6770,9 @@ the value before execution. A local call needs no inference credential.
 A hosted call still needs Cursor credentials to reach the deployment.
 
 `--session` runs the tool inside an existing session and records it on
-the event stream. If a model turn is active or pending, the server
-returns `session_busy`; retry after the turn finishes. The command
+the event stream. If a model turn is active or pending, a read-effect
+tool runs alongside it and a write-effect tool gets `session_busy`;
+retry after the turn finishes. The command
 prints the server's JSON response and exits non-zero unless the HTTP
 response succeeds with `ok: true`. See
 [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
@@ -5580,6 +6844,7 @@ non-zero when the reconstructed trajectory failed.
 agent-sdk init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
 agent-sdk init ./my-demo --template demo              # record a PR walkthrough
 agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
+agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
 agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
 agent-sdk init ./security-help --template security-help   # answer security questions in Slack
 agent-sdk init ./my-triage --template triage-linear   # comment on Linear issues
@@ -5597,8 +6862,9 @@ agent-sdk init                     # no directory: print the setup guide
 `@cursor/july` resolves for `dev` and `run`.
 
 Templates may ship `init.json`. On a TTY, `init` asks those questions
-before writing files. `code-wiki`, `pr-autofixer`, and `security-help`
-ask for GitHub repos. Repeat
+before writing files. `code-wiki`, `pr-autofixer`, `security-help`, and
+`agents-md` ask for GitHub repos. `agents-md` also asks for Slack
+channels. Repeat
 `--var id=value` to answer without a prompt.
 `--json` and non-TTY hosts skip the interview unless `--var` is set.
 
@@ -5756,7 +7022,8 @@ 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>]... [--no-wait] [--json]
+                [--allow-domain <domain>]...
+                [--no-wait] [--json]
 ```
 
 Managed hosting requires team-admin permission and the team's
@@ -5909,6 +7176,8 @@ URL connections run a browser PKCE flow. Tokens are written to
 `mcp-auth.json` under the CLI config directory (override with
 `AGENT_SERVE_CONFIG_DIR`). Pass `--store` to upsert matching
 `MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
+`--store` is the path for the next deploy. Hosted Connect lets the
+current process retry.
 
 Cursor-account connections authorize the hosted deployment's service
 account through the Cursor backend's connector consent flow. Those
@@ -5987,6 +7256,7 @@ agent-sdk slack icon <https-url-or-file> [--dir <path>] [--prod]
                     [--slack-team <T…>] [--team <id>] [--json]
 agent-sdk slack init --manual [--dir <path>] [--name <name>]
                     [--prefix <prefix> | --no-prefix] [--channel-posts]
+                    [--install | --no-install] [--slack-team <T…>] [--prod]
 agent-sdk slack manifest [--dir <path>] [--name <name>]
                     [--env dev|prod|both] [--channel-posts] [--print]
 agent-sdk slack doctor [--dir <path>] [--prefix <prefix> | --no-prefix] [--json]
@@ -6015,17 +7285,26 @@ a local png, jpg, or gif file of at most 512KB.
 
 `slack init` without `--manual` exits non-zero and writes no files. Use
 `slack create` for the dashboard wizard. `slack init --manual` writes
-the channel file, development and production manifests, `env.example`,
-and setup status under the project. You paste those manifests at
-api.slack.com. The command refuses to overwrite a target file. If a
-collision occurs, it exits non-zero; files created earlier in the run
-remain. The token prefix defaults to the directory basename normalized
-to uppercase snake case. Explicit `--prefix` values use the same
-normalization. For example, `pr-approver` becomes
-`PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix` uses shared
-`SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. `--channel-posts` subscribes
-the manifests to channel-post events. The command always prints a JSON
-summary.
+the channel file, development and production manifests, a Slack CLI
+`.slack/` project (hook + manifests, committed with the repo). When
+Slack CLI is logged in, it installs the app. Otherwise `next` asks
+you to install it. `--install` requires that install. `--no-install`
+skips it. `--prod` selects the deployed app.
+`--slack-team` picks the workspace. Slack CLI keeps install tokens in
+that process; copy `xoxb` and mint `xapp` (`connections:write`) into
+`.env.local`. Tokens that appear in `.env` during that install are
+copied onto the prefixed names. Paste `.slack/manifest.dev.json` at
+api.slack.com when the Slack CLI is missing. Do not run
+`slack deploy`. The command refuses to overwrite the channel file.
+It updates the Slack CLI hook and manifests when `.slack/` already
+exists. If a collision occurs, it exits non-zero; files created
+earlier in the run remain. The token prefix defaults to the directory
+basename normalized to uppercase snake case.
+Explicit `--prefix` values use the same normalization. For example,
+`pr-approver` becomes `PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix`
+uses shared `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
+`--channel-posts` subscribes the manifests to channel-post events.
+The command always prints a JSON summary.
 
 `slack manifest` regenerates selected manifest files. `--env` defaults
 to `both`, and `--name` defaults to the directory name. `--print` writes
@@ -6156,8 +7435,10 @@ Tokens come from env vars. Never hardcode them in the file.
 ## Host MCP OAuth
 
 For servers that speak OAuth, set `oauth: true` and authorize with the
-CLI. Tokens live in `mcp-auth.json` under the CLI config directory. `--store`
-copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
+CLI or mid-run Connect. Tokens live in `mcp-auth.json` under the CLI
+config directory. `--store` copies them onto the deployment as
+`MCP_OAUTH_<NAME>_*` secrets. Hosted Connect lets the current
+process retry.
 
 ```ts
 export default defineConnection({
@@ -6169,6 +7450,7 @@ export default defineConnection({
 ```bash
 agent-sdk mcp oauth inventory           # browser PKCE → local mcp-auth.json
 agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
+# Hosted Connect retries this process. Self-hosted stays file-only.
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
@@ -6387,7 +7669,7 @@ lazily on first use.
 
 Continue with these pages:
 
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, `--store`
+- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): peers in depth
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
@@ -6548,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 |
 
@@ -6629,7 +7912,8 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 It runs an authored server tool in-process: schema-validated, no model
 turn. An optional `"sessionId"` in the body runs it inside an existing
 session and records it on that session's stream (`409 session_busy`
-while a turn runs). Agent-execution tools are rejected with `400`, and
+for a write-effect call while a turn runs; reads run alongside the
+turn). Agent-execution tools are rejected with `400`, and
 unknown tools with `404` and the list of available names. For the
 semantics, see [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
 
@@ -7345,8 +8629,10 @@ message. Interrupted turns record `turn.failed` with
 Slack `stop` / `@agent stop` does the same for that thread and clears
 pending coalesced nudges.
 
-Session-bound deterministic tool calls share the same execution lock.
-They return `409 session_busy` while a model turn is running.
+Session-bound deterministic tool calls share the lock only for writes: a
+write-effect call returns `409 session_busy` while a model turn is
+running, a read-effect call runs alongside the turn (see
+[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn)).
 
 ## Which events can I stream?
 
@@ -7753,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
@@ -7869,7 +9180,14 @@ when the call returns. Pass a `sessionId` (a body field over
 HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
 run inside an existing session instead: the tool sees that session's
 workspace, and the call is recorded on the session's event stream.
-Session-bound calls return `409 session_busy` while a turn runs. When the
+While a model turn is running, a session-bound call is admitted by its
+effect: a read-effect call (a declared `effect: "read"`, or an advertised
+MCP tool whose server annotates it read-only) runs alongside the turn,
+reading the workspace as the turn has left it, and is recorded under its
+own per-call `turnId` so trajectories keep it apart from the turn's own
+calls; a write-effect call — including an undeclared tool, which counts
+as a write — returns `409 session_busy` until the turn finishes, because
+a running turn owns the workspace. When the
 session's harness cwd cannot be materialized, a read-effect call runs
 in a scratch workspace instead and the outcome carries
 `scratchWorkspace: true`; a write-effect call fails with
@@ -7879,7 +9197,7 @@ A session can also be addressed by its continuation token: an optional
 `continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
 mutually exclusive with `sessionId`). A token that maps to a live
 session behaves exactly like passing that session's id — same ownership
-check, same `409 session_busy`, same event recording. A token with no
+check, same busy semantics, same event recording. A token with no
 session behind it runs the call scratch-bound with the token's channel
 id and continuation key as the call's session identity, so a deployment
 whose tools resolve state from the continuation key can serve it with
@@ -8333,6 +9651,116 @@ sessions skip GitHub writes.
 
 ---
 
+Source: /docs/templates/agents-md.md
+
+# Keep AGENTS.md current from last week's work
+
+This agent runs every Monday at 09:00 UTC. It reads last week's merged
+pull requests and the Slack channels you list. When a durable rule
+showed up, `apply_agents` parks the write until a person approves it,
+then opens a draft follow-up pull request against the default branch.
+Chores and rules the file already states stay quiet.
+
+This template is one model turn: read the week, then call
+`apply_agents`.
+
+Init once per app. Pass a different repo and channel list each time.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./agents-md --template agents-md
+```
+
+`init` asks which GitHub repo to watch and which Slack channels to
+read. Pass `--var repos=acme/api --var slack=#eng-api,#api-private`
+to skip the prompt. Use `--var slack=none` when Slack is out of
+scope.
+
+The answers land in `agent/lib/config.ts`. Edit that file when the
+set changes.
+
+## Connect GitHub and Slack
+
+Connect GitHub in Cursor for that repository (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host
+in:
+
+```bash
+cd agents-md
+agent-sdk login
+```
+
+`cursorAccount` mints a short-lived, repo-scoped credential with
+`contents-write` so the agent can open the follow-up PR. See the
+[GitHub guide](/docs/guides/github.md).
+
+Create the Slack app and invite the bot to each listed channel,
+including private ones:
+
+```bash
+agent-sdk slack create --dir .
+```
+
+See the [Slack guide](/docs/guides/slack.md).
+
+## First weekly run
+
+```bash
+agent-sdk dev
+```
+
+Schedules never fire under `dev`. Dispatch the same path production
+uses:
+
+```bash
+curl -X POST http://127.0.0.1:3000/v1/dev/schedules/weekly
+```
+
+The playground can run `/queue/run` too.
+
+The host writes `week/prs.md`, `week/slack.md`, `week/window.txt`,
+and `week/tree/**.txt` snapshots of the current `AGENTS.md` files,
+then starts a model turn. The
+model calls `apply_agents` once. A skip finishes. An update parks in
+the playground until someone approves; then a draft PR opens against
+the repository default branch. Later updates to the same base stack
+on `agents-md/<base>`. Pull requests from those branches are ignored
+so the follow-up cannot feed the next week.
+
+Chat replies stay in the playground. `apply_agents` records a skip,
+or parks the write. Approve there or with
+`POST /v1/session/:id/approvals/:callId`.
+
+## What to edit
+
+- `agent/lib/config.ts`: repo and Slack channels
+- `agent/instructions.md`: what counts as an update
+- `evals/agents.eval.ts`: smoke cases
+
+## Evals
+
+Four smoke cases: a lint-only week, a billing rule that parks the
+write, the same rule already in `AGENTS.md`, and an empty week.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. Production fires the Monday cron. The deployment
+uses the team's Cursor GitHub connection for the watched repo.
+
+---
+
 Source: /docs/templates/code-wiki.md
 
 # Keep a code wiki current after merge
@@ -8939,7 +10367,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
-| `409 session_busy` on `call --session` | Wait for the model turn to finish, or omit `--session` for a one-off call. |
+| `409 session_busy` on `call --session` | The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit `--session` for a one-off call, or declare `effect: "read"` on a tool that only reads so it runs alongside turns. |
 | `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
 | Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |
 | A channel route fails to compile with a schema type error | `GET` routes need a Zod `querySchema`. `POST` / `PUT` / `PATCH` need a Zod `bodySchema`. Use `z.object({})` or `z.unknown()` for open shapes. |
@@ -8967,7 +10395,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
-| Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
+| Local auth works; hosted calls unauthorized | Finish Connect on the hosted engine, or run `agent-sdk mcp oauth <name> --store`. Confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
 | Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](/docs/guides/mcp-oauth.md) and