@cursor/july 0.1.68 → 0.1.73

package/skills/create-agent/SKILL.md

@@ -62,7 +62,7 @@ questions, concrete options, the recommended option listed first and labeled
 | **Runtime** | `local` (default) · `cloud` | Local = Cursor SDK harness on this machine; server tools, skills, sandbox seeds, and tool approvals all work. Cloud = Cursor cloud agents; needs `cloud.repos`, no server tools/skills/sandbox seeds (instructions are prepended to the first prompt). Recommend local unless the purpose needs a repo checkout on a cloud VM. |
 | **Model** | `grok-4.5` with `effort=high`, `fast=true` (default) · Other model id | Effort and fast are params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` — the SDK rejects suffix-style ids. |
 | **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack has two connections: the Cursor-hosted connection (`cursorAccount: true` — zero Slack admin, recommended default) and a dedicated Socket Mode app (own bot user + one app/token pair per agent; needed for channel watching or approval buttons). When Slack is picked, resolve the connection with the Step 0 gate in `setup-slack/SKILL.md` — either fold its AskQuestion into this round or ask it before channel setup; default to Cursor-hosted when you cannot ask. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
-| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Other | One file per server under `agent/mcp-connections/`; filename = server name; tokens via env vars, never hardcoded. MCP connections serve the model **and** host code (`ctx.host.mcp`, channel `host.mcp`). |
+| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Set `hostOnly: true` only when host tools call the server and the playground must not. |
 | **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Server tools, skills, sandbox seeds, approvals are local-runtime only. Agent tools (`execution: "agent"`) work on both runtimes. Always recommend at least one smoke eval. |
 
 Close the round with a one-screen plan — chosen options plus the file tree you
@@ -87,6 +87,10 @@ Defaults that make first cuts good:
 
 - **Minimal surface.** Instructions + 1–2 real tools + the chosen channels +
   one smoke eval. Unpicked capabilities are follow-ups, not scope.
+- **`local.cwd`.** Keep the harness outside a monorepo checkout
+  (`~/.cache/agent-serve/<slug>`). Discovery does this for nested git
+  projects. Point cwd at a checkout only when the agent must inherit that
+  tree.
 - **Instructions** (`agent/instructions.md`, required): a few lines — identity,
   when to use which tool, output shape. Not an essay.
 - **Tool per file**, filename = tool name the model sees. Prefer
@@ -139,9 +143,9 @@ agent-sdk init ./<slug>
 ```
 
 `init` writes `package.json` (with `typescript` dev deps and a
-`check` script), `tsconfig.json`, `agent/agent.ts`, `agent/instructions.md`,
-a demo `agent/tools/echo.ts`, and empty capability folders
-(`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
+`check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
+`agent/instructions.md`, a demo `agent/tools/echo.ts`, and empty capability
+folders (`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
 files are left alone (`exist`) and missing ones are filled in. It then
 runs `npm install`, and when the host is unsigned runs `login` and waits
 before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
@@ -149,8 +153,7 @@ plan:
 
 1. `tsconfig.json` — init writes a strict, `noEmit` config covering `agent/`
    and `evals/`; extend it only when the project needs more.
-2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`; add the
-   `cloud: { repos: [...] }` block for cloud runtime.
+2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`. Nested git checkouts get `local.cwd` under `~/.cache/agent-serve/<slug>` at discovery even if omitted. Add the `cloud: { repos: [...] }` block for cloud runtime.
 3. `agent/instructions.md` — real instructions; delete or replace `echo.ts`
    with the real tools.
 4. Add the chosen `channels/`, `mcp-connections/`, `skills/`, `subagents/<id>/`
@@ -210,9 +213,9 @@ agent-sdk eval --dir ./<slug>
 
 Serve only the new agent's directory during bring-up — pointing `serve` at a
 parent folder also mounts every sibling agent it contains.
-Runtime state lands in `<project>/.agent-serve/` (gitignored); keep durable
-`--state-root` outside the monorepo so sessions don't inherit ambient
-`AGENTS.md`.
+Runtime state lands in `<project>/.agent-serve/` (gitignored). Nested
+checkouts default `local.cwd` to `~/.cache/agent-serve/<slug>` at
+discovery. `--state-root` is for session files, not harness cwd.
 
 ## Channel setup with the user
 

package/skills/debug/SKILL.md

@@ -47,7 +47,8 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | Every built-in read/grep the model makes fails; turns crawl through retry loops | You ran the CLI under **Bun**. Kill it, rerun under Node/tsx. (`NGHTTP2_FRAME_SIZE_ERROR` in SDK logs is the tell.) |
 | `gh webhook forward` / `agent-sdk github forward` deliveries all 401 — but hook creation succeeded | `GITHUB_TOKEN`/`GH_TOKEN` in the env. The relay authenticates with the gh CLI login and rejects env tokens. `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...` |
 | `Hook already exists` starting a forwarder | GitHub allows one forwarder per repo. Use one `github forward --dir <parent>` (it fans out to every matching channel) instead of N processes; kill stale forwarders. |
-| Agent's answers reference monorepo rules / AGENTS.md it shouldn't know | Session workspace sits inside the monorepo, so the harness loaded ancestor config. `defineAgent({ local: { cwd } })` outside the repo, or `--state-root` under `/tmp`. |
+| Agent's answers reference monorepo rules / AGENTS.md it shouldn't know | Session workspace sits inside another git checkout, so the harness loaded ancestor config. Nested projects default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point cwd at a checkout only when the agent should inherit that tree. |
+| Yellow box lists Datadog/Linear tools; model recites `GetDynamicTools` / IDE `cursor` tools and never calls MCP | Attached MCP is behind meta-tools, or `hostOnly` hid it, or cwd still leaked IDE MCP. Set `advertiseTools: true` for named tools on local turns. Confirm `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Port 3000/5273 in use; stray processes after crashes | `lsof -iTCP:3000 -sTCP:LISTEN`, kill the pids; also check companion processes (e.g. vite). |
 | Pending tool approval vanished after server restart | By design: parked SDK calls don't survive host restart; they resolve as interrupted. Re-run the turn. |
 | Schedule / reminder never fires under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>` or `POST /<slug>/v1/dev/reminders/<id>` (list at `GET /v1/dev/reminders`). |

package/skills/framework-map/SKILL.md

@@ -38,11 +38,11 @@ pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
    before shipping. Classic miss: a tool `execute` return that fails
    `ToolExecuteResult` — returns must be JSON-shaped, so use object
    literals or `type` aliases, not `interface` types.
-4. **Keep session state out of big monorepos.** Session workspaces are real
-   Cursor project directories and inherit ambient `AGENTS.md`/`.cursor`
-   rules from **ancestors**. Set `defineAgent({ local: { cwd } })` outside
-   the monorepo or pass a temp `--state-root`. (`run`/`eval` already use a
-   temp state root.)
+4. **Harness cwd in a nested git repo.** Discovery defaults `local.cwd` to
+   `~/.cache/agent-serve/<dir>` so ancestor `AGENTS.md` / `.cursor` / IDE
+   MCP do not leak into playground turns. Set cwd at a checkout only when
+   the agent must inherit that tree. Attached MCP is invisible by name
+   until `advertiseTools: true`. `hostOnly` hides it from the model.
 5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
    (`validate`, `info`, `call`, `serve` bring-up) works without one.
 
@@ -57,7 +57,7 @@ path live under README "Folder structure".
 | `agent/instructions.md` | Always-on system prompt (required; `.ts`/dir forms exist) |
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (script that runs where the agent runs) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand |
-| `agent/mcp-connections/<name>.ts` | MCP servers — available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`). `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP for the agent environment. |
+| `agent/mcp-connections/<name>.ts` | MCP servers. Do not name an account connection `cursor.ts`. `advertiseTools: true` for named tools on local turns; `hostOnly` keeps them off the model. `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP. |
 | `agent/subagents/<id>/` | Child agent dir (`description` required; per-subagent tools/skills/MCP connections ignored for now) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` / `github.ts` use the platform packs |
 | `agent/hooks/*.ts` | Observe-only event subscribers (never fatal) |

package/skills/mcp-auth/SKILL.md

@@ -3,7 +3,7 @@ name: agentkit-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
   agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
-  hostOnly, and egress. Read when wiring or debugging MCP auth.
+  hostOnly, advertiseTools, and egress. Read when wiring or debugging MCP auth.
 ---
 
 # Host MCP OAuth (mcp auth)
@@ -26,13 +26,15 @@ Docs: `docs/guides/mcp-oauth.md`, `docs/reference/connections.md`,
 | Remote URL that speaks OAuth; host must hold tokens | `defineConnection({ url, oauth: true })` + this skill |
 | Static bearer / API key | `headers` / env on a plain `{ url }` connection |
 
-Prefer `hostOnly: true` when only host tools / channel handlers should
-call the server (admin APIs, privileged writes). The model will not see
-those tools.
+Set `hostOnly: true` only when host tools / channel handlers should call
+the server and the model should not (admin APIs, privileged writes).
+Playground chat will not see those tools. For connectors the model should
+call on local turns (Linear, Datadog, account MCP), omit `hostOnly` and
+set `advertiseTools: true`.
 
 ## Goal checklist
 
-- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (+ `hostOnly` if privileged)
+- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (`hostOnly` if privileged; `advertiseTools` if the model should call it)
 - [ ] `hosting.secretNames` lists `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}` when you will `--store`
 - [ ] Hosted engines that reach non-bootstrap hosts declare `hosting.egressDomains`
 - [ ] Local: `agent-sdk mcp oauth <name>` succeeds
@@ -127,7 +129,7 @@ redeploy completed, then exercise the same host tool once.
 | `Unknown MCP connection` | Filename under `agent/mcp-connections/` must match CLI arg |
 | Callback hang | Free port 8787; finish browser flow on this machine |
 | Hosted 401 / unauthorized | `secrets list`; re-run `--store`; redeploy |
-| Model invents `mcp_auth` / IDE MCP | Connection is `hostOnly`; fix instructions + use host tools |
+| Model invents `mcp_auth` / IDE MCP | `hostOnly` hid it, or attached MCP is behind meta-tools. Use host tools for privileged servers. Set `advertiseTools: true` for named tools on local turns. |
 | Tokens ignored after URL edit | Expected; run `mcp oauth` again for the new resource URL |
 
 ## Don't

package/src/bin/agent-serve.ts

@@ -1260,7 +1260,8 @@ async function main(argv: string[]): Promise<number> {
           values["cursor-events"] === true
             ? { repos: values.repo ?? [] }
             : undefined,
-        // Soft boot logs (GitHub auth, etc.) stay secondary to the banner.
+        // Soft boot logs stay secondary to the banner. `dim` is a no-op on
+        // already-styled lines (the MCP warning box).
         logger: (line: string) => {
           process.stdout.write(`${style.dim(line)}\n`);
         },
@@ -1700,7 +1701,7 @@ installTransportErrorGuards();
 
 // Authored agent files are TypeScript imported at runtime; install the tsx
 // loader (and the framework import aliases on compiled runs) before any
-// command touches a project.
+// command touches a project. In-repo CLI is `bin/agentsdk`.
 registerAuthoredModuleLoaders()
   .then(() => main(process.argv.slice(2)))
   .then(

package/src/channels/github/api.ts

@@ -535,7 +535,12 @@ function isOctokitRequestError(error: unknown): error is {
   );
 }
 
-function wrapOctokitError(error: unknown, method: string, path: string): Error {
+/** Normalize an Octokit request failure into {@link GitHubApiError}. */
+export function wrapOctokitError(
+  error: unknown,
+  method: string,
+  path: string
+): Error {
   if (isOctokitRequestError(error)) {
     return new GitHubApiError({
       body: error.response?.data,

package/src/channels/github/binding.ts

@@ -17,6 +17,11 @@ import {
   type GitHubPostedComment,
   type GitHubReactionContent,
 } from "./api.js";
+import {
+  createGitHubCheck,
+  type GitHubCheck,
+  type GitHubCheckCreateInput,
+} from "./checks.js";
 import type {
   GitHubChannelCredentials,
   GitHubConversationKind,
@@ -79,6 +84,14 @@ export interface GitHubHandle {
     description?: string;
     targetUrl?: string;
   }): Promise<GitHubApiResponse>;
+  /**
+   * Open a CI check run (Checks API) on `sha` and get a handle for updating
+   * and concluding it. Needs `checks:write` — with `cursorAccount`, declare
+   * `githubChannel({ checks: true })` to opt the lease up.
+   */
+  createCheck(
+    input: Omit<GitHubCheckCreateInput, "github" | "owner" | "repo">
+  ): Promise<GitHubCheck>;
 }
 
 /** Thread-scoped operations for the current conversation (`ctx.thread`). */
@@ -149,6 +162,14 @@ export function buildGitHubBinding(input: {
           : { targetUrl: status.targetUrl }),
       });
     },
+    createCheck(check) {
+      return createGitHubCheck({
+        ...check,
+        github: { getOctokit },
+        owner: state.owner,
+        repo: state.repo,
+      });
+    },
   };
 
   const thread: GitHubThread = {

package/src/channels/github/checks.ts

@@ -0,0 +1,179 @@
+/**
+ * Generic CI checks (GitHub Checks API) for agent authors.
+ *
+ * `createGitHubCheck` opens a merge-box check run on a commit and returns a
+ * handle for updating and concluding it, so an agent can report its own CI
+ * result (name, summary, and a "Details" link — e.g. the agent session run).
+ * Works with any client exposing `getOctokit()` (`ctx.github`,
+ * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
+ *
+ * Posting checks needs `checks:write`. With `cursorAccount`, declare
+ * `githubChannel({ checks: true })` so the hosted lease is minted on the
+ * `contents-write` tier; GitHub App / PAT credentials need the equivalent
+ * permission.
+ */
+
+import type { Octokit } from "@octokit/rest";
+import {
+  type GitHubCheckRunConclusion,
+  type GitHubCheckRunStatus,
+  wrapOctokitError,
+} from "./api.js";
+
+/** Any client that can hand out an authenticated Octokit. */
+export interface GitHubCheckClient {
+  getOctokit(): Promise<Octokit>;
+}
+
+/** Output shown on the check page (both fields required by GitHub). */
+export interface GitHubCheckOutput {
+  /** Heading on the check page. */
+  title: string;
+  /** Markdown body (supports links, e.g. `[View session](…)`). */
+  summary: string;
+}
+
+export interface GitHubCheckCreateInput {
+  /** Client used for every API call on the returned handle. */
+  github: GitHubCheckClient;
+  /** Repository owner login, e.g. `"acme"`. */
+  owner: string;
+  /** Repository name, e.g. `"widgets"`. */
+  repo: string;
+  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
+  name: string;
+  /** Commit the check attaches to (usually the PR head SHA). */
+  sha: string;
+  /** Initial status. Defaults to `"in_progress"`. */
+  status?: "queued" | "in_progress";
+  /** "Details" link on the check, e.g. the agent session run URL. */
+  detailsUrl?: string;
+  /** Title + markdown summary shown on the check page. */
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckUpdateInput {
+  status?: GitHubCheckRunStatus;
+  conclusion?: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckConcludeInput {
+  /** Final result shown in the merge box. */
+  conclusion: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+/** A created check run. All methods throw `GitHubApiError` on API failure. */
+export interface GitHubCheck {
+  /** Check run id (for reuse across process restarts). */
+  readonly id: number;
+  /** GitHub web URL of the check run page, when returned by the API. */
+  readonly url: string | undefined;
+  /** Patch status / output / details link while the check is running. */
+  update(input: GitHubCheckUpdateInput): Promise<void>;
+  /** Complete the check with a conclusion (sets `completed_at`). */
+  conclude(input: GitHubCheckConcludeInput): Promise<void>;
+}
+
+/**
+ * Create a CI check run on a commit and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createGitHubCheck({
+ *   github: ctx.github,
+ *   owner: ctx.repository.owner,
+ *   repo: ctx.repository.name,
+ *   name: "Cursor Security Review",
+ *   sha: pr.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
+ * });
+ * // …do the work…
+ * await check.conclude({ conclusion: "success", output: { … } });
+ * ```
+ */
+export async function createGitHubCheck(
+  input: GitHubCheckCreateInput
+): Promise<GitHubCheck> {
+  const octokit = await input.github.getOctokit();
+  let created: { id: number; html_url?: string | null };
+  try {
+    const response = await octokit.rest.checks.create({
+      owner: input.owner,
+      repo: input.repo,
+      name: input.name,
+      head_sha: input.sha,
+      status: input.status ?? "in_progress",
+      started_at: new Date().toISOString(),
+      details_url: input.detailsUrl,
+      output: input.output,
+    });
+    created = response.data;
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/check-runs`
+    );
+  }
+  return resumeGitHubCheck({
+    github: input.github,
+    owner: input.owner,
+    repo: input.repo,
+    name: input.name,
+    checkRunId: created.id,
+    url: typeof created.html_url === "string" ? created.html_url : undefined,
+  });
+}
+
+/**
+ * Rebuild a {@link GitHubCheck} handle for an existing check run id (e.g.
+ * after a process restart). No API call is made until the first update.
+ */
+export function resumeGitHubCheck(input: {
+  github: GitHubCheckClient;
+  owner: string;
+  repo: string;
+  name: string;
+  checkRunId: number;
+  url?: string;
+}): GitHubCheck {
+  const patch = async (update: GitHubCheckUpdateInput): Promise<void> => {
+    const octokit = await input.github.getOctokit();
+    try {
+      await octokit.rest.checks.update({
+        owner: input.owner,
+        repo: input.repo,
+        check_run_id: input.checkRunId,
+        name: input.name,
+        status: update.status,
+        conclusion: update.conclusion,
+        completed_at:
+          update.status === "completed" ? new Date().toISOString() : undefined,
+        details_url: update.detailsUrl,
+        output: update.output,
+      });
+    } catch (error) {
+      throw wrapOctokitError(
+        error,
+        "PATCH",
+        `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`
+      );
+    }
+  };
+  return {
+    id: input.checkRunId,
+    url: input.url,
+    update: patch,
+    conclude: (conclude) =>
+      patch({
+        status: "completed",
+        conclusion: conclude.conclusion,
+        detailsUrl: conclude.detailsUrl,
+        output: conclude.output,
+      }),
+  };
+}

package/src/channels/github/cursor-account.ts

@@ -119,22 +119,25 @@ export function parseCursorGithubRepoScope(
 
 /**
  * Hosted `cursorAccount` mints `checks:write` on the `contents-write` tier.
- * Enabling `progress.commitStatus` opts a `pr-write` (or omitted) channel up
- * to that tier so github-proxy / `/github-token` can post Checks API runs.
- * `"read"` cannot post merge-box checks.
+ * Enabling `progress.commitStatus` or `checks: true` opts a `pr-write` (or
+ * omitted) channel up to that tier so github-proxy / `/github-token` can
+ * post Checks API runs. `"read"` cannot post merge-box checks.
  */
 export function cursorGithubPermissionsForChannel(
-  options: Pick<GitHubChannelOptions, "progress">,
+  options: Pick<GitHubChannelOptions, "progress" | "checks">,
   authored: CursorGithubPermissions | undefined = "pr-write"
 ): CursorGithubPermissions {
   const base = authored ?? "pr-write";
   const commitStatus = options.progress?.commitStatus;
-  if (commitStatus === undefined || commitStatus === false) {
+  const wantsChecks =
+    options.checks === true ||
+    (commitStatus !== undefined && commitStatus !== false);
+  if (!wantsChecks) {
     return base;
   }
   if (base === "read") {
     throw new Error(
-      'progress.commitStatus needs checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".'
+      'progress.commitStatus / checks need checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".'
     );
   }
   return "contents-write";

package/src/channels/github/index.ts

@@ -43,6 +43,7 @@
 export * from "./api.js";
 export * from "./auth.js";
 export * from "./binding.js";
+export * from "./checks.js";
 export * from "./defaults.js";
 export * from "./events.js";
 export * from "./forward.js";

package/src/channels/github/types.ts

@@ -546,6 +546,14 @@ export interface GitHubChannelOptions {
    * and sticky banner are opt-in via `commitStatus` / `banner`.
    */
   progress?: GitHubProgressConfig;
+  /**
+   * Declare that this channel posts its own CI checks
+   * (`ctx.github.createCheck` / `createGitHubCheck`). With `cursorAccount`,
+   * opts the minted token up to `permissions: "contents-write"` so the
+   * hosted lease includes `checks:write` — same opt-up as
+   * `progress.commitStatus`. Has no effect on App / PAT credentials.
+   */
+  checks?: boolean;
   /**
    * When false, skip posting assistant / error comments back to GitHub.
    * Defaults to true.

package/src/channels/slack/manifest.ts

@@ -29,8 +29,8 @@ export interface SlackAppManifest {
       display_name: string;
       always_online: boolean;
     };
-    assistant_view?: {
-      assistant_description: string;
+    agent_view?: {
+      agent_description: string;
       suggested_prompts: Array<{ title: string; message: string }>;
     };
     app_home?: {
@@ -135,9 +135,9 @@ export function buildSlackManifest(
       : options.name;
   const botName = options.botDisplayName ?? toBotDisplayName(options.name, env);
   const description = options.description ?? defaultDescription(options.name);
-  const includeAssistant = options.assistant !== false;
+  const includeAgentView = options.assistant !== false;
 
-  const botScopes = includeAssistant
+  const botScopes = includeAgentView
     ? [...BOT_SCOPES]
     : BOT_SCOPES.filter((scope) => scope !== "assistant:write");
 
@@ -164,14 +164,12 @@ export function buildSlackManifest(
         messages_tab_enabled: true,
         messages_tab_read_only_enabled: false,
       },
-      ...(includeAssistant
+      agent_view: includeAgentView
         ? {
-            assistant_view: {
-              assistant_description: description,
-              suggested_prompts: suggested,
-            },
+            agent_description: description,
+            suggested_prompts: suggested,
           }
-        : {}),
+        : undefined,
     },
     oauth_config: {
       scopes: {

package/src/channels/slack/types.ts

@@ -651,7 +651,7 @@ export interface SlackManifestOptions {
   env: "dev" | "prod";
   /** Optional short description shown in the Slack app. */
   description?: string;
-  /** Include `assistant_view` + `assistant:write` for typing status. */
+  /** Include `agent_view` + `assistant:write` for typing status. */
   assistant?: boolean;
   /**
    * Enable Slack interactivity (needed for Approve/Deny cards).
@@ -663,7 +663,7 @@ export interface SlackManifestOptions {
    * channel watch (`engagement.channelPosts`). Defaults to `false`.
    */
   channelPosts?: boolean;
-  /** Seed suggested prompts into the manifest `assistant_view`. */
+  /** Seed suggested prompts into the manifest `agent_view`. */
   suggestedPrompts?: Array<{ title: string; message: string }>;
   /**
    * Emit `settings.managed_app_settings`. Defaults to `true` — Cursor

package/src/connections.ts

@@ -4,7 +4,8 @@
  * A connection gives tools from an external MCP server. The filename
  * becomes the connection (server) name. Available to the agent (SDK
  * `mcpServers`), host (`ctx.host.mcp`), and channel/schedule handlers.
- * Pass `hostOnly: true` to keep it off the model (still on `host.mcp`).
+ * Pass `advertiseTools: true` for named tools on local turns. Pass
+ * `hostOnly: true` to keep it off the model (still on `host.mcp`).
  *
  * ```ts
  * import { defineConnection } from "@anysphere/agent-serve/connections";
@@ -42,13 +43,24 @@
  * to be signed in (`agent-serve login` or `CURSOR_API_KEY`):
  *
  * ```ts
- * // agent/mcp-connections/cursor.ts — every connected server (no allowlist)
- * export default defineConnection({ cursorAccount: true });
+ * // agent/mcp-connections/account.ts — every connected server (no allowlist)
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   advertiseTools: true,
+ * });
  * // equivalent explicit form:
- * export default defineConnection({ cursorAccount: true, servers: "*" });
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   servers: "*",
+ *   advertiseTools: true,
+ * });
  *
  * // or restrict to specific connectors by name
- * export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
+ * export default defineConnection({
+ *   cursorAccount: true,
+ *   servers: ["Linear"],
+ *   advertiseTools: true,
+ * });
  * ```
  *
  * A **peer MCP connection** addresses another agent mounted on the same serve