@cursor/july 0.1.113 → 0.1.114

package/docs/reference/subagents.md

@@ -6,16 +6,15 @@ description: "Specialist child agents the model delegates to mid-turn, each its
 # Subagents
 
 A subagent is a specialist child agent the model can delegate to
-mid-turn. Each one is its own directory under `agent/subagents/<id>/`,
-with the same `agent.ts` + `instructions.md` shape as the root. On the
-Cursor harness, subagents run as SDK custom subagents: the parent model
-delegates through the harness `task` tool, and the stream records
-`subagent.called` and `subagent.completed`.
+mid-turn. Each one lives under `agent/subagents/<id>/` with a required
+`agent.ts`. Add `instructions.md` or inline `instructions` in `agent.ts`
+for a custom prompt. The parent model delegates through the `task` tool,
+and the stream records `subagent.called` and `subagent.completed`.
 
 ```text
 agent/subagents/researcher/
 ├── agent.ts            # description (required), model (optional)
-└── instructions.md     # the subagent's own system prompt
+└── instructions.md     # optional custom system prompt
 ```
 
 ```ts
@@ -31,44 +30,35 @@ export default defineAgent({
 
 ## Subagent rules
 
-`description` is required. It's the only thing the parent model reads
-when deciding whether to delegate, so write it as a routing rule
-("Background research: …"), the same discipline as a
-[skill](./skills.md) description. `model` is optional; omit it to
-inherit the parent's model, or set it to run the specialist on a
-different one.
+`description` is required. The parent model uses it to decide whether
+to delegate, so write it as a routing rule ("Background research: …"),
+following the same discipline as a [skill](./skills.md) description.
+`model` is optional; omit it to inherit the parent's model, or set it
+to run the specialist on a different model.
 
 Subagents inherit the parent's execution surface. Every per-subagent
 capability directory is reported as a warning and ignored: `tools/`,
-`skills/`, `mcp-connections/` (and the legacy `connections/` alias),
-`host-connections/`, `channels/`, `schedules/`, `hooks/`, `sandbox/`,
-and nested `subagents/`.
+`skills/`, `extensions/`, `mcp-connections/`, `host-connections/`,
+`channels/`, `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and
+nested `subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](./instructions.md) make it happen. "When a
 request needs background research, delegate to the `researcher`
-subagent."
+subagent." The parent routes; the specialist executes.
 
-## Subagent or peer?
+## Subagents and peers
 
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
 playground, make it a full agent. See
 [Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
 
-## Patterns
-
-Fan-out reviews: a PR-approval agent can delegate to two review
-subagents that read a host-prepared `pr/` evidence tree and report
-prioritized findings, which the parent embeds in its approval comment.
-
-Keep the parent lean: a subagent with focused instructions usually
-works better than a longer parent prompt with conditional sections. The
-parent routes; the specialist executes.
-
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Skills](./skills.md): when a procedure is enough and a child agent
   is overkill
+- [Peer agents](../guides/agent-to-agent.md): independently useful
+  specialists
+- [Agent config](./agent-config.md#harness-tools): `"task"` on the
+  parent's tool allowlist

package/docs/reference/tools.md

@@ -8,18 +8,16 @@ description: "Define typed actions the model can call, gate the sensitive ones o
 A tool is a typed action the model can call: hit an API, run a query,
 write a file. Each file in `agent/tools/` defines one tool, and the
 filename becomes the tool name the model sees. Tools come in two
-execution flavors: server tools run in-process on the serve host, and
+execution flavors: server tools run on the serving host, and
 agent tools run as scripts where the agent runs. Every server tool can
 also be called directly, with no model turn.
 
 ## Define a server tool
 
-By default, `execute` runs in-process on the serving host with full
-access to `process.env` and your `agent/lib/` code. Local turns call
-server tools as SDK custom tools. Cloud turns reach them over
-authenticated HTTP MCP back to the serve host when `--public-url` or
-`--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them.
+By default, `execute` runs on the serving host with full access to
+`process.env` and your `agent/lib/` code. Set `--public-url` or
+`--cloud-tools-url` to make server tools available to cloud turns;
+without either, startup warns and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -178,7 +176,7 @@ check nothing.
 ## Define an agent tool
 
 Set `execution: "agent"` and the tool materializes as a shell script
-that runs where the Cursor agent runs: the local harness workspace or
+that runs where the Cursor agent runs: the local session workspace or
 the cloud VM. The script receives JSON arguments on stdin and prints its
 result on stdout. Use this flavor when the tool must run next to the
 checkout the agent works in; on cloud, server tools stay available too
@@ -201,23 +199,16 @@ printf '%s\\n' "$message"
 ```
 
 On the local runtime, scripts land in the session workspace with a
-catalog in `AGENTS.md`. On cloud, the catalog and script bodies travel
-on the first prompt.
+catalog in `AGENTS.md`.
 
 ## Tools from an MCP connection, advertised by name
 
-Authored `agent/tools/` files are one catalog for every session. When
-the tools should come from an MCP server, including per-tenant toolsets
-resolved at runtime, declare the connection with
-`advertiseTools: true` (plus per-session `auth` when the credential
-depends on who the session is for) and the engine synthesizes named 1:1
-passthrough server tools from the connection's live `listTools` on every
-local turn. See
-[MCP Connections](connections.md#advertise-tools).
-Advertised tools ride the same execution path as authored server tools,
-and [direct tool calls](#call-a-tool-without-a-model-turn) address them
-by the same model-facing names: the call's session identity resolves the
-advertised listing when the authored lookup misses.
+Set `advertiseTools: true` on a connection to expose its MCP tools by
+name. Add per-session `auth` when credentials depend on the caller.
+Model calls and [direct tool calls](#call-a-tool-without-a-model-turn)
+use the same exposed names. See
+[MCP connections](./connections.md#advertise-tools) for the full
+contract.
 
 ## Gate a tool on human approval
 
@@ -248,8 +239,8 @@ runtime only, and parked calls don't survive a host restart.
 ## Call a tool without a model turn
 
 Server tools can be called deterministically. You pick the tool and the
-input. Validation and execution behave exactly as they would for a
-model-initiated call, and no Cursor API key is needed.
+input. Validation and execution match a model-initiated call, and no
+Cursor API key is needed.
 
 Over HTTP, with the same auth chain as the session API:
 
@@ -275,51 +266,43 @@ agent-sdk call inspect_pr \
 Programmatically, `callTool(toolName, input, options?)` is available on
 the serve handle, on channel route handlers and `onStart` args, and on
 schedule `run` handlers, so a channel can mix deterministic calls with
-model turns, fetching PR metadata deterministically and then `send()`ing
-the review prompt:
+model turns:
 
 ```ts
 const outcome = await handle.callTool("inspect_pr", {
   prUrl: "https://github.com/acme/checkout/pull/42",
 });
+if (outcome.isError) {
+  return outcome;
+}
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the call runs against an ephemeral workspace and is removed
-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.
-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
-`workspace_unavailable`.
-
-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 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
-no live session. Malformed tokens are rejected with
-`400 invalid_continuation_token`.
-
-The error semantics match the model path. Unknown tools are rejected
-with the available names, agent-execution tools cannot be called on the
-host (`400`), schema-invalid input is a `400` before the tool body runs
-(Zod validates; plain JSON Schema passes through unvalidated), and a
-tool body that throws reports `isError: true` in the same envelope the
-model would see.
+Omit both identifiers to run against an ephemeral workspace that is
+removed when the call returns. Pass `sessionId` (HTTP body, `--session`,
+or `options.sessionId`) or `continuationToken` (`<channelId>:<key>` as
+`/v1/sessions` lists it) to bind the call. The two are mutually
+exclusive.
+
+| Rule | What happens |
+| --- | --- |
+| Existing `sessionId`, or a token that maps to an existing session | Session workspace, owner check, and event recording |
+| Token with no matching session | Scratch workspace; the token's channel id and key are the call identity |
+| Busy session, `effect: "read"` (or an advertised MCP tool marked read-only) | Runs alongside the turn, reading the workspace as the turn left it; recorded under its own `turnId` |
+| Busy session, write or undeclared | `409 session_busy` until the turn finishes |
+| Session workspace cannot be created, read | Scratch workspace; the outcome has `scratchWorkspace: true` |
+| Session workspace cannot be created, write | `500 workspace_unavailable` |
+
+| Error | When |
+| --- | --- |
+| `404 unknown_tool` | Name is not a callable server tool; the response lists available names |
+| `400 tool_not_callable` | Agent-execution tools cannot run on the host |
+| `400 invalid_tool_input` | Zod rejected the input before `execute`. Plain JSON Schema is forwarded unvalidated |
+| `400 invalid_continuation_token` | Malformed token, or passed together with `sessionId` |
+| `404 session_not_found` | `sessionId` does not exist |
+| `409 session_busy` | Write-effect call while a model turn is running |
+| `500 workspace_unavailable` | Write-effect call when the session workspace cannot be created |
+| `isError: true` | The tool body threw; same envelope the model would see |
 
 ## Design habits
 
@@ -337,9 +320,7 @@ wrong, no instruction change fixes it.
 Gate side effects with `needsApproval`. Declare each tool's `effect` so
 dry-run sessions can execute reads and stub writes.
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [MCP connections](./connections.md): tools that come from MCP servers
   instead

package/docs/troubleshooting.md

@@ -32,7 +32,7 @@ Match the visible symptom below. If `agent-sdk` is not on `PATH`, use
 | File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
 | The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `agent-sdk login`. |
 | Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
-| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](./reference/agent-config.md#choose-a-runtime). |
+| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](./reference/agent-config.md#runtime). |
 
 ## A turn behaves unexpectedly
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.113",
+  "version": "0.1.114",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {