@cursor/july 0.1.113 → 0.2.0

package/dist/docs/reference/agent-config.md

@@ -1,8 +1,8 @@
-# Agent config (`agent/agent.ts`)
+# Agent config
 
-`agent/agent.ts` default-exports `defineAgent(config)`: which model runs
-the agent, where turns execute, and runtime-specific defaults.
-Everything is optional on the root agent.
+`agent/agent.ts` default-exports `defineAgent(config)`, which sets the
+model, execution runtime, and runtime-specific defaults. Every root
+config field is optional.
 
 ```ts
 import { defineAgent } from "@cursor/july";
@@ -22,9 +22,7 @@ export default defineAgent({
 });
 ```
 
-## Fields on `defineAgent`
-
-`defineAgent` accepts these fields.
+## Agent fields
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -33,14 +31,14 @@ export default defineAgent({
 | `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
 | `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
 | `runtime` | `"local"` or `"cloud"` | Where turns execute. Default `"local"`. |
-| `cloud` | object | Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
+| `cloud` | object | Cloud agent defaults: repos, env, envVars. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
 | `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults; ignored for cloud turns. See [Local options](#local-options). |
-| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `agent-sdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
-| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `hosting` | `{ egressDomains?, secretNames? }` | `agent-sdk deploy` declarations for allowed egress domains and expected secret names. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Agent-wide turn admission limit. See [Concurrency](#concurrency). |
 | `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
-| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Allowlist built-in harness tools](#allowlist-built-in-harness-tools). |
+| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
 
-## Choose a model
+## Model
 
 `model` is a Cursor model id string, or `{ id, params }`. Effort and
 speed are params, not id suffixes. The SDK rejects suffix-style ids
@@ -62,24 +60,17 @@ A plain string works when you don't need params:
 model: "composer-2.5",
 ```
 
-## Choose a runtime
+## Runtime
 
-`runtime: "local"` (the default) runs turns on the Cursor SDK harness on
-this machine. Server tools, skills, sandbox seeds, and tool approvals
-all apply.
+`runtime: "local"` (the default) runs turns on this machine. Server
+tools, skills, sandbox seeds, and tool approvals all apply.
 
-`runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
-a `cloud` block with the repos the VM carries. Server tools stay
-reachable over authenticated HTTP MCP back to the serve host when
-`--public-url` or `--cloud-tools-url` is set (omitted with a warning
-otherwise), and instructions and agent-tool catalogs are prepended to
-the first prompt, because the local session workspace is not the cloud
-VM.
+`runtime: "cloud"` runs turns on Cursor cloud agents. Pass a `cloud`
+block with the repositories the VM needs. See [Tools](/docs/reference/tools.md) for
+server- and agent-tool behavior on cloud turns.
 
-`validate` warns when `runtime: "cloud"` is combined with agent tools
-(they are described on the first prompt instead of written to the VM),
-when skills or sandbox seeds are present (they sync onto an Agent Store
-rather than the session workspace), and when the `cloud` block is
+`validate` warns when `runtime: "cloud"` is combined with agent tools,
+when skills or sandbox seeds are present, and when the `cloud` block is
 missing.
 
 ## Local options
@@ -88,18 +79,15 @@ missing.
 
 `local.workspaceDir` points every session at one shared harness cwd,
 for agents that work inside an existing checkout. It takes precedence
-over `cwd`, and a per-send `workspaceDir` still wins over both. The SDK
-keys its local executor (rules, skills, MCP, ignore mappings) on the
-harness cwd, so a shared directory resolves the workspace once per
-serve process instead of once per session. The trade: sessions share a
-working tree, so a file one turn writes is visible to the next.
+over `cwd`, and a per-send `workspaceDir` still wins over both.
+Sessions share a working tree, so a file one turn writes is visible to
+the next.
 
 `local.sandbox` runs the harness inside Cursor's local sandbox. It's
-off by default, matching the SDK: shell then auto-approves and inherits
-the serve process environment, including any credentials the host
-holds. Turn it on for agents whose turns read untrusted input (webhook
-payloads, PR diffs, inbound chat); it's a real tool boundary rather
-than a prompt-level one.
+off by default: shell then auto-approves and inherits the serve process
+environment, including any credentials the host holds. Turn it on for
+agents whose turns read untrusted input (webhook payloads, PR diffs,
+inbound chat); it's a tool boundary, not a prompt-level one.
 
 ### Local cwd
 
@@ -115,13 +103,12 @@ does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
 
-## Allowlist built-in harness tools
+## Harness tools
 
 Use `tools` to limit which built-in Cursor harness tools the model can
 call. Omit it to keep the standard toolset. When you set it, the model
 gets only the tools you list. An empty list disables all native
-built-in tools. Because this field is an allowlist, new platform tools
-stay disabled until you add them.
+built-in tools. New platform tools stay disabled until you add them.
 
 ```ts
 export default defineAgent({
@@ -132,12 +119,13 @@ export default defineAgent({
 });
 ```
 
-The Agent SDK always adds `"mcp"` to a configured allowlist. Authored
-server tools in `agent/tools/` use MCP to reach the model. MCP can also
-expose declared connections and servers from the harness directory's
-ambient `.cursor` config. To exclude a checkout's MCP servers, point
-`local.cwd` outside the checkout. See [Local cwd](#local-cwd).
-`local.sandbox` makes MCP tool calls fail closed.
+The Agent SDK always adds `"mcp"` to a configured allowlist, because
+authored server tools in `agent/tools/` reach the model over MCP. MCP
+can also expose declared connections and servers from the harness
+directory's ambient `.cursor` config. To exclude a checkout's MCP
+servers, point `local.cwd` outside the checkout. See
+[Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
+closed.
 
 Use the SDK's public tool names, including `"shell"`, `"read"`,
 `"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
@@ -154,8 +142,7 @@ Two names have broader effects:
 Tool allowlists work only with the local runtime. A
 `runtime: "cloud"` agent that sets `tools` fails at serve startup.
 The Agent SDK also refuses per-send cloud sessions from a hybrid agent
-with an allowlist. It won't run those sessions with unrestricted tool
-access.
+with an allowlist.
 
 The allowlist controls which tools the model can call. It does not
 isolate the serve host. For agents that process untrusted input, also
@@ -163,10 +150,10 @@ set `local: { sandbox: true }`.
 
 ## Cloud options
 
-Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
-`{ url, startingRef? }`), environment selection, `envVars`, and the
-rest. A local agent uses the same block as the base config when a
-channel opens a cloud-attached session per send (the `cloud` option on
+The `cloud` block sets default repositories (each
+`{ url, startingRef? }`), environment selection, and `envVars`. A local
+agent uses the same block as the base config when a channel opens a
+cloud-attached session per send (the `cloud` option on
 [`send`](/docs/reference/channels.md#handler-arguments)).
 
 ## Concurrency
@@ -189,9 +176,8 @@ export default defineAgent({
 ## Built-in tools
 
 `builtinTools` opts into framework-provided model-facing tools. Each
-enabled capability materializes as ordinary server tools at discovery
-time, so turns, direct calls, `info`, and the playground treat them
-like authored tools. Authored tools with the same name win, with a
+enabled capability shows up as ordinary server tools, so turns, direct
+calls, `info`, and the playground treat them like authored tools. Authored tools with the same name win, with a
 warning, and like all server tools they run on the local runtime.
 
 `builtinTools: { reminders: true }` adds three tools bound to the
@@ -200,22 +186,6 @@ current conversation over `host.reminders`: `reminders_create`,
 continuation key can't arm reminders. See
 [Schedules and reminders](/docs/reference/schedules.md#reminders).
 
-## Generate instructions
-
-When the system prompt must be computed, author `agent/instructions.ts`
-instead of markdown:
-
-```ts
-import { defineInstructions } from "@cursor/july";
-
-export default defineInstructions({
-  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
-});
-```
-
-The directory form and the runtime mapping are in
-[Instructions](/docs/reference/instructions.md).
-
 ## Serve programmatically
 
 `serve(dirOrProject, options)` embeds the server in your own process:
@@ -225,7 +195,7 @@ import { serve } from "@cursor/july";
 
 const handle = await serve("./my-agent", {
   port: 3000,
-  apiKey: process.env.CURSOR_API_KEY, // optional; see credential order
+  apiKey: process.env.CURSOR_API_KEY,
 });
 console.log(`listening on ${handle.url}`);
 // handle.callTool(...), handle.dispatchSchedule("heartbeat"),
@@ -234,17 +204,14 @@ console.log(`listening on ${handle.url}`);
 
 Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
-`mode: "single" | "multi"`. The Cursor credential resolves in one order
-everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then
-`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
-when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the key stored by
-`agent-sdk login`. On a host that has both the service-account key and a
-bind file, the file principal wins.
-
-## What's next
+`mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
+credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
 
-Continue with these pages:
+## Related
 
 - [Instructions](/docs/reference/instructions.md): the required half of a minimal
   agent
 - [CLI](/docs/reference/cli.md): the `serve` flags `serve()` accepts
+- [Sessions](/docs/reference/sessions.md): workspaces, identifiers, and turn admission
+- [Schedules](/docs/reference/schedules.md): reminder tools opted in here