@cursor/july 0.1.113 → 0.1.114

package/docs/reference/connections.md

@@ -1,21 +1,20 @@
 ---
-title: "MCP Connections"
+title: "MCP connections"
 description: "Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."
 ---
 
-# MCP Connections
+# MCP connections
 
-An MCP connection gives the agent tools from an MCP server. One file per
-server under `agent/mcp-connections/`, and the filename becomes the server
-name the model sees. An MCP connection default-exports `defineConnection`
-from `@cursor/july/connections`, and the transport comes in
-four shapes: remote HTTP, local stdio, the signed-in Cursor account's
-connectors, and peer agents on the same host.
+An MCP connection gives the agent tools from an MCP server. Define one
+file per server under `agent/mcp-connections/`; the filename becomes the
+server name. Default-export `defineConnection` from
+`@cursor/july/connections`. The transport is remote HTTP, local stdio,
+the signed-in Cursor account's connectors, or a peer agent on the same
+host.
 
-Put a server in `agent/host-connections/` when host tools should call it
-and the model should not. Same `defineConnection` shape. `agent-sdk mcp
-oauth` still works. The playground and the turn's MCP servers never see
-those files.
+Put a server in `agent/host-connections/` when only host tools should
+call it. Host connections use the same `defineConnection` shape and
+support `agent-sdk mcp oauth`; the model and playground don't see them.
 
 ## Remote MCP server
 
@@ -37,8 +36,7 @@ Tokens come from env vars. Never hardcode them in the file.
 For servers that speak OAuth, set `oauth: true` and authorize with the
 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.
+`MCP_OAUTH_<NAME>_*` secrets.
 
 ```ts
 export default defineConnection({
@@ -50,24 +48,17 @@ 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](../guides/mcp-oauth.md). Companion
 skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
-Account MCP (`cursorAccount: true`) is the right choice for connectors
-already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
-to forward every connected connector. If the model should call those
-tools by name on local turns, set `advertiseTools: true`.
+## Per-session auth
 
-## Per-session auth (`auth`)
-
-For http/sse connections whose credential depends on **who the session is
-for** (a multi-tenant agent asserting the tenant it is acting for),
-declare an `auth` callback instead of static headers. It runs host-side
-at turn-build time with the session's `SessionInfo` and returns headers
-merged over the static ones:
+For http/sse connections whose credential depends on who the session is
+for, declare an `auth` callback instead of static headers. It runs
+host-side with the session's `SessionInfo` and returns headers merged
+over the static ones:
 
 ```ts
 export default defineConnection({
@@ -75,39 +66,31 @@ export default defineConnection({
   auth: async (session) => ({
     headers: { Authorization: `Bearer ${await grantFor(session)}` },
   }),
-  advertiseTools: true, // optional — named tools instead of meta-tools
+  advertiseTools: true,
 });
 ```
 
-The callback is evaluated on **every local turn**, including reminder
-fires and post-restart follow-ups, so the identity always comes from the
-session itself, never from state parked in memory. The model never sees a
-tenant parameter and can never choose the tenant. A callback that throws
-fails the turn: a turn never silently runs without the connection's
-identity. Local runtime only; cloud turns are refused. `host.mcp` calls
-from server tools keep the static headers only. Not combinable with
-`oauth: true`; the host OAuth provider owns the Authorization header.
+The identity always comes from the session itself, never from a tenant
+parameter the model could invent. A callback that throws fails the
+turn; a cloud turn with `auth` is refused instead of running without
+that identity. `host.mcp` calls from server tools keep the static
+headers only. You can't combine `auth` with `oauth: true`.
 
 Derive the identity from durable session facts: `session.auth`,
-`session.id`, or your channel's own session state. Do **not** key it off
-`session.continuationKey`: the HTTP channel rotates the continuation key
-after every accepted follow-up, so a tenant mapping keyed on it silently
-breaks mid-conversation. (Channels that mint stable, parseable tokens by
-design are the exception.)
-
-`auth` works attached or advertised. Advertised connections open
-per-operation clients with the evaluated headers. Attached connections
-ride the turn's SDK `mcpServers`, passed on **every send** rather than
-pinned on the cached per-session agent handle, so a rotated credential is
-live on the very next turn. A stateful stdio server cannot share a
-process with an attached `auth` connection. Advertise the auth
-connection instead.
-
-## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
-
-Set `advertiseTools: true` when the model should call an MCP server's tools
-by name. The Agent SDK preserves each tool's name, description, input and
-output schemas, and MCP annotations.
+`session.id`, or your channel's own session state. Do not key it off
+`session.continuationKey`. The HTTP channel rotates that key after every
+accepted follow-up, so a tenant mapping keyed on it breaks
+mid-conversation.
+
+`auth` works attached or advertised. Advertise the auth connection
+instead of attaching it next to a stateful stdio server.
+
+## Advertise tools {#advertise-tools}
+
+Set `advertiseTools: true` when the model should call an MCP server's
+tools by name. The Agent SDK preserves each tool's description, input
+and output schemas, and MCP annotations. Exposed names normalize invalid
+characters and add numeric suffixes to avoid collisions.
 
 ```ts
 export default defineConnection({
@@ -117,20 +100,22 @@ export default defineConnection({
 });
 ```
 
-A listing failure, invalid tool name, or name collision fails the turn.
-Advertised tools follow the same runtime support as server tools. They cannot
-be called through the direct tool API.
+A listing or authentication failure fails the turn by default. Set
+`optional: true` to omit an unavailable connection instead. Advertised
+tools follow the same runtime support as server tools, and [direct tool
+calls](./tools.md#call-a-tool-without-a-model-turn) use the same names.
 
-In a dry-run session, MCP tools marked read-only run normally. Tools marked
-as writes are stubbed. Tools without effect annotations are unavailable.
+In a dry-run session, MCP tools marked read-only run normally. Tools
+marked as writes are stubbed. Tools without effect annotations are
+unavailable.
 
-## Restrict which tools a connection serves
+## Filter connection tools
 
 Use `tools` the same way you allowlist harness tools on the agent. When
 set, the connection serves only those names. Use `disallowedTools` to
-drop names instead. The two combine as deny-wins, same as the Cursor
-SDK. The model and `host.mcp` only see what remains. On a model-visible
-connection, set `advertiseTools: true` so the raw server is not attached.
+drop names instead. The two combine as deny-wins. The model and
+`host.mcp` only see what remains. A model-visible filter requires
+`advertiseTools: true`.
 
 ```ts
 export default defineConnection({
@@ -138,7 +123,9 @@ export default defineConnection({
   advertiseTools: true,
   tools: ["search_skus", "get_stock"],
 });
+```
 
+```ts
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   advertiseTools: true,
@@ -147,9 +134,9 @@ export default defineConnection({
 ```
 
 Names are the server's `tools/list` names. Unknown names are omitted. A
-filter that matches nothing on the server fails the turn. Combine with
-`effects: "read"` to keep only the listed tools the server classifies as
-reads.
+filter that matches nothing on the server fails the turn unless
+`optional: true`. Combine with `effects: "read"` to keep only the listed
+tools the server classifies as reads.
 
 A list of names is an allowlist. An object of handlers authors TypeScript
 tools. On `host-connections/`, a name list restricts `host.mcp` without
@@ -167,12 +154,8 @@ export default defineConnection({
 });
 ```
 
-This suits small purpose-built servers, like a `units` converter
-shipped next to the agent.
-
-To run TypeScript in the agent environment (including a repo-less cloud
-VM), author the tools on the connection instead. The Agent SDK packages
-them as stdio MCP. You write `execute`. The Agent SDK speaks the protocol.
+To run TypeScript in the agent environment, including a repo-less cloud
+VM, author the tools on the connection instead. You write `execute`:
 
 ```ts
 export default defineConnection({
@@ -190,12 +173,12 @@ export default defineConnection({
 ## Cursor account MCP connection
 
 `{ cursorAccount: true }` forwards the MCP connectors the signed-in
-Cursor account already authorized (dashboard → MCP): Linear, Notion,
-Slack, and the rest. You don't configure tokens. Every tool runs on the
+Cursor account already authorized (dashboard → MCP), such as Linear,
+Notion, and Slack. You don't configure tokens. Every tool runs on the
 Cursor backend with the account's stored OAuth credentials, so raw
-tokens never reach the serve host, session workspaces, or traces.
+tokens never reach the serving host, session workspaces, or traces.
 
-By default the agent gets **every** connected HTTP/SSE connector on the
+By default the agent gets every connected HTTP/SSE connector on the
 account. Pass `servers: "*"` (or `["*"]`) for the same all-connectors
 behavior in an explicit form. Pass a name list when you want a smaller
 set.
@@ -206,12 +189,9 @@ export default defineConnection({
   cursorAccount: true,
   advertiseTools: true,
 });
-// same, spelled out:
-export default defineConnection({
-  cursorAccount: true,
-  servers: "*",
-  advertiseTools: true,
-});
+```
+
+```ts
 // only Linear:
 export default defineConnection({
   cursorAccount: true,
@@ -222,17 +202,15 @@ export default defineConnection({
 
 Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
 MCP namespace. `advertiseTools: true` puts connector tools on local
-turns by name. Without it they sit behind harness meta-tools.
+turns by name.
 
 The host must be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`).
-`serve` fails fast at startup otherwise, and logs each connector's live
-status (`connected`, `needsAuth`, `error`) as it starts.
+`CURSOR_SERVICE_ACCOUNT_KEY`). `serve` fails at startup otherwise.
 
 Filtered account connections work on managed cloud deployments. A
-self-hosted cloud agent with a concrete `servers` list needs `--public-url`.
-Serve fails instead of ignoring the filter. Use a `{ command }` connection
-for stdio servers.
+self-hosted cloud agent with a concrete `servers` list needs
+`--public-url`. Serve fails instead of ignoring the filter. Use a
+`{ command }` connection for stdio servers.
 
 > [!CAUTION]
 > Whoever can talk to the agent can drive these connectors, because they
@@ -242,11 +220,11 @@ for stdio servers.
 > for example an SSO proxy or the hosted alias token). Prefer
 > `--bearer-token` on shared hosts.
 
-## Peer MCP connection
+## Peer MCP connection {#peer-mcp-connection}
 
 `{ agent: "<slug>" }` addresses another agent mounted on the same serve
-host. The model gets the peer's `ask` and `check` (and `call_tool`)
-tools and can delegate work to it:
+host. The model gets the peer's `ask` and `check` tools, plus
+`call_tool` when the peer has server tools, and can delegate work to it:
 
 ```ts
 export default defineConnection({
@@ -258,48 +236,34 @@ export default defineConnection({
 Unknown slugs and self-references fail `serve` at startup. Walkthrough:
 [Peer agents](../guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
-## Every model-visible MCP connection is available in three places
-
-A file under `agent/mcp-connections/` serves three consumers. Host
-connections skip the first one.
-
-1. **Cursor agent:** Attached connections ride SDK `mcpServers` behind
-   harness MCP meta-tools. Set `advertiseTools: true` so local turns see
-   named tools.
-2. **Server tools:** Deterministic host code composes MCP calls
-   through `ctx.host.mcp`:
-
-   ```ts
-   export default defineTool({
-     description: "Search Linear issues.",
-     inputSchema: z.object({ query: z.string() }),
-     async execute({ query }, ctx) {
-       return ctx.host.mcp.callTool("linear", "list_issues", { query });
-     },
-   });
-   ```
+## Call MCP from host code
 
-3. **Channel and schedule handlers:** Webhooks hit MCP servers with no
-   model turn at all, through `args.host.mcp`:
+A file under `agent/mcp-connections/` is available to the Cursor agent,
+to server tools through `ctx.host.mcp`, and to channel and schedule
+handlers through `args.host.mcp`. Host connections skip the model.
 
-   ```ts
-   POST("/sync", {
-     bodySchema: z.object({}),
-     handler: async (_req, { host }) => {
-       const result = await host.mcp.callTool("linear", "list_issues", {});
-       return Response.json(result);
-     },
-   });
-   ```
-
-The host registry is small: `host.mcp.names()` lists MCP connection names,
-and `listTools(name)` / `callTool(name, tool, args)` open the client
-lazily on first use.
+```ts
+// agent/tools/search_linear.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Search Linear issues.",
+  inputSchema: z.object({ query: z.string() }),
+  async execute({ query }, ctx) {
+    return ctx.host.mcp.callTool("linear", "list_issues", { query });
+  },
+});
+```
 
-## What's next
+`host.mcp.names()` lists connection names.
+`listTools(name)` / `callTool(name, tool, args)` call into a named
+connection.
 
-Continue with these pages:
+## Related
 
 - [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers
+- [Peer agents](../guides/agent-to-agent.md): when a specialist is its
+  own agent

package/docs/reference/evals.md

@@ -1,15 +1,17 @@
 ---
 title: "Evals"
-description: "Reference for eval discovery, cases, assertions, judges, configuration, fixtures, reporters, and runner output."
+description: "Define eval cases, drive turns, assert trajectories, and interpret results."
 ---
 
-# Evals reference
+# Evals
 
-This page is the complete authoring and runner contract for
-`@cursor/july/evals`. Start with the [Evals guide](../evals.md) for the
-workflow and first regression case.
+Evals run fixed cases against an agent and record whether its turns,
+tools, events, and output meet a contract. Files under the project-root
+`evals/` directory define cases with `@cursor/july/evals`; the runner
+discovers their IDs, executes them, and reports every assertion. See the
+[Evals guide](../evals.md) for the regression workflow.
 
-## Discovery and case IDs
+## Eval discovery and case IDs
 
 Eval files live under the project-root `evals/` directory and end in
 `.eval.ts` or `.eval.js`. The path under that directory becomes the
@@ -48,15 +50,15 @@ Those cases are `prs/checkout` and `prs/search` when the file is
 `evals/prs.eval.ts`. Case IDs must be unique single path segments.
 
 A file can also export an array of `defineEval` calls. The runner names
-them with zero-padded indexes such as `sql/0000`. Use named `cases` for
-handwritten scenarios and arrays for loaded datasets.
+them with zero-padded indexes such as `sql/0000`. Named `cases` give
+handwritten scenarios stable IDs; arrays fit loaded datasets.
 
 `iterations` repeats one datapoint from 1 to 100 times. For
 `iterations: 3`, `weather/nyc` expands to `weather/nyc/1`,
 `weather/nyc/2`, and `weather/nyc/3`; selecting `weather/nyc` runs all
 three.
 
-## Configuration
+## Eval configuration
 
 Every running suite needs `evals/evals.config.ts` with
 `maxConcurrency`:
@@ -77,38 +79,39 @@ export default defineEvalConfig({
 | `timeoutMs` | Per-case timeout; case/file, CLI, then config precedence |
 | `judge` | Default model for `t.judge` |
 | `reporters` | Objects notified as cases and runs complete |
-| `maxPlaygroundRuns` | Number of server-side batches kept in playground history |
+| `maxPlaygroundRuns` | Number of server-side batches kept in playground history; defaults to 20 |
 
 A case can override `description`, `tags`, `timeoutMs`, `iterations`,
 `judge`, `reporters`, and `metadata`. Case metadata merges over
 file-level metadata; case reporters add to the file's reporters.
 
-## Drive turns with `t.send`
+## Send turns in a case
 
 `await t.send(message, options?)` runs one turn and waits until it
 finishes, fails, or parks for approval. Several sends in one test share
 the session.
 
 The returned turn exposes its assistant `message`, `sessionId`,
-`events`, ordered `toolCalls`, `ok`, and turn `index`. Assertions on the
-turn inspect only that turn; assertions on `t` inspect the whole run.
-Useful run values include `t.reply`, `t.events`, `t.turns`,
-`t.sessionId`, and the timeout `t.signal`.
+`events`, ordered `toolCalls`, `ok`, and one-based `index`. Assertions
+on the turn inspect only that turn; assertions on `t` inspect the whole
+case. Run values include `t.reply`, `t.events`, `t.turns`,
+`t.sessionId`, `t.iteration`, `t.iterations`, and the timeout
+`t.signal`.
 
 These options apply on the first send because they shape the session:
 
 | Option | Contract |
 | --- | --- |
 | `workspaceFiles` | Relative path-to-content map seeded into the session workspace |
-| `workspaceDir` | Absolute local harness working directory |
+| `workspaceDir` | Absolute working directory for a new local session |
 | `cloud` | Cloud session options merged over the agent's static cloud config |
 
-Use `turn.expectOk()` when later test steps depend on that turn
-succeeding.
+Use `turn.expectOk()` when later test steps depend on the turn
+succeeding. It throws when the turn failed.
 
 ## Trajectory assertions
 
-Assertions record failures and let the test continue, so one case
+Assertions record failures without stopping the test, so one case
 reports every violated contract.
 
 | Assertion | Checks |
@@ -231,53 +234,43 @@ export default rows.map(row =>
 );
 ```
 
-Materialize API-backed evidence before running a large suite. Commit
-the exact payload, diff, or metadata revision and seed it with
-`workspaceFiles`.
-
 ## Reporters and results
 
 Built-in reporters include `JUnit({ filePath, suiteName? })` and
 `Artifacts({ dir })`. Custom reporters can expose `onRunStart`,
-`onEvalComplete`, and `onRunComplete`. Reporter errors are logged and
-do not change the eval verdict.
+`onEvalComplete`, and `onRunComplete`.
 
-JSON output contains run totals plus one result per case. A result can
-include the case ID, verdict, assertions, session ID, inputs, tool
-calls, metrics, logs, duration, metadata, tags, final text, and error or
-skip details.
+JSON output contains run totals and one result per case. Results include
+the case ID, verdict, assertions, session ID, inputs, final text, tools,
+tool calls, metrics, logs, duration, metadata, tags, and any error or
+skip reason.
 
-## CLI selection and artifacts
+## Select cases
 
 ```bash
 agent-sdk eval --dir . --list
 agent-sdk eval --dir .
 agent-sdk eval --dir . builds/checkout
 agent-sdk eval --dir . --tag smoke
-agent-sdk eval --dir . --verbose
 ```
 
 ID filters match an exact ID and its descendants. Repeated IDs use OR;
 repeated tags use OR. When both are present, a case must match both
 groups.
 
-The local runner starts an ephemeral server. Default artifacts go under
-`evals/<stamp>/` in the project state directory and include
+## Inspect run artifacts
+
+Default run artifacts go under `evals/<stamp>/` in the project state
+directory and include
 `summary.json`, `results.jsonl`, and `evals/<case-id>.json`.
 `--artifacts <dir>` chooses another destination; `--no-artifacts`
 disables them. This location is independent of `--state-root`.
 
-Model and judge turns resolve credentials in this order:
-`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
-`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`. Listing cases
-needs no credential.
-
-## Playground and hosted runs
+## Run evals against a server
 
-The playground **Evals** view starts batches on its running server and
-keeps their sessions in the normal session list. `--url` targets a
-named running server; `--prod --slug <slug>` targets a hosted
-deployment.
+The playground **Evals** view starts batches on its running server.
+`--url` targets a named running server, and `--prod --slug <slug>`
+targets a hosted deployment.
 
 ```bash
 agent-sdk eval --prod --slug vulnerability-scanner --tag smoke
@@ -285,14 +278,13 @@ agent-sdk eval status <eval-id> --prod --slug vulnerability-scanner
 agent-sdk eval cancel <eval-id> --prod --slug vulnerability-scanner
 ```
 
-Server-side batches use the target server's discovered evals and store
-results in its playground history. Local-only reporter and concurrency
-flags do not apply to `--url` or `--prod` runs.
+Server-side batches use the target's discovered cases and return an eval
+ID for `status` or `cancel`. Local reporter and concurrency flags don't
+apply to `--url` or `--prod` runs.
 
 ## Related
 
-- [Evals guide](../evals.md): author and run a regression workflow
-- [CLI reference](./cli.md#eval): every runner flag
-- [Sessions](./sessions.md): event vocabulary used by trajectory checks
-- [Artifacts](./artifacts.md): durable outputs asserted by
-  `taggedArtifact`
+- [Evals guide](../evals.md)
+- [CLI reference](./cli.md#eval)
+- [Sessions](./sessions.md)
+- [Artifacts](./artifacts.md)

package/docs/reference/extensions.md

@@ -35,10 +35,10 @@ The extension validates its configuration while the project loads.
 Missing or mistyped settings fail `agent-sdk validate` before a turn
 can call the contributed code.
 
-Extension instructions are appended to the agent's prompt. The root
-agent still needs its own `agent/instructions.md`.
+Extension instructions are appended to the root agent's instructions.
+The root agent still needs its own `agent/instructions.md`.
 
-## See what the extension added
+## Inspect a mount
 
 Run discovery after mounting or upgrading an extension:
 
@@ -126,18 +126,14 @@ server. OAuth-backed plugin servers use
 [Host MCP OAuth](../guides/mcp-oauth.md); transport and tool-filter
 details live in [MCP connections](./connections.md).
 
-## What an extension can contain
+## Extension contents
 
-Share capabilities that can safely join another agent under a
-namespace:
+| Ships under the namespace | Ignored |
+| --- | --- |
+| Instructions, tools, skills, MCP and host connections | `agent.ts`, storage, OpenTelemetry |
+| Hooks, channels, schedules, and subagents | Playground code, custom sandbox backends |
+| Artifact kinds and workspace seed files | Nested extensions |
 
-- Instructions, tools, skills, MCP and host connections
-- Hooks, channels, schedules, and subagents
-- Artifact kinds and local workspace seed files
-
-Agent-wide configuration does not compose through a mount.
-`agent.ts`, storage, OpenTelemetry, playground code, custom sandbox
-backends, and nested extensions are ignored in an extension package;
 `agent-sdk validate` reports unsupported paths.
 
 ## Build an extension