@cursor/july 0.1.91 → 0.1.93

package/docs/reference/sessions.md

@@ -79,7 +79,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Phase | Events | What they tell you |
 | --- | --- | --- |
 | Session | `session.started`, [`ab.assigned`](../ab.md#assign-sticky-variants), `session.waiting`, `session.completed`, `session.failed` | Session creation, A/B enrollment, readiness, and task completion |
-| Agent | `agent.bound` | Cursor SDK agent ID and cloud conversation URL |
+| Agent | `agent.bound` | Cloud conversation URL |
 | Input | `message.received` | A user message was accepted |
 | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](./agent-config.md#concurrency), then turn status, final result, and token usage |
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
@@ -118,7 +118,7 @@ The Agent SDK creates a workspace before the first local turn:
 | ---------------------------------- | ----------------------------------------------------------------------- |
 | `instructions.*`                   | `AGENTS.md`                                                             |
 | `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
-| agent tools (`execution: "agent"`) | scripts under `.agent-serve/tools/`, with a catalog in `AGENTS.md` |
+| agent tools (`execution: "agent"`) | scripts in the session workspace, with a catalog in `AGENTS.md` |
 | `sandbox/workspace/**`             | copied in as seed files                                                 |
 | per-send `workspaceFiles`          | written before the turn                                                 |
 
@@ -133,34 +133,23 @@ inheritance rules.
 
 ## Where does the Agent SDK store session data?
 
-Local state uses one directory tree:
-
-```text
-<project>/.agent-serve/           # or <stateRoot>/<slug>/ under serve
-  sessions/<id>/session.json       # metadata: channel, mode, principal, tokens
-  sessions/<id>/events.ndjson      # the durable stream
-  sessions/<id>/workspace/         # the harness cwd
-  traces/<sessionId>.ndjson        # written by `run`
-  runner/                          # Cursor SDK conversation store
-  tool-calls/<callId>/             # ephemeral deterministic-call workspaces
-```
+Local state lives under `--state-root`. Slugged mounts store it under
+a subdirectory named for the slug.
 
 Deleting a session directory removes the session from the server: it
 disappears from listings and can no longer be streamed or continued.
-The `runner/` store keeps its own conversation copy until you remove it.
 Cloud conversations remain on the Cursor backend.
 
-Change the root with `--state-root` or `stateRoot`. Nested git checkouts
-already default `local.cwd` outside the enclosing repo. See
+Nested git checkouts already default `local.cwd` outside the enclosing
+repo. See
 [local session workspaces](../concepts.md#what-files-can-a-local-session-access).
 
 ## How do I inspect a saved event stream?
 
-Use `trajectory` with a trace or session event file:
+Use `trajectory` with a saved trace:
 
 ```bash
-agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
-agent-sdk trajectory --events <stateRoot>/<slug>/sessions/<id>/events.ndjson
+agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
 ```
 
 The command prints tool calls, the reply, and token usage in the same

package/docs/reference/skills.md

@@ -57,9 +57,9 @@ the engine copies the same SKILL.md tree onto an Agent Store for native
 discovery:
 
 - Hosted deployments write store-root `skills/<name>/`.
-- `agent-serve serve` / `run` with a personal `CURSOR_API_KEY` write
-  `agent-serve/<agent>/skills/<name>/` on the USER store, namespaced so
-  they cannot collide with the user's own skills.
+- `agent-sdk serve` / `run` with a personal `CURSOR_API_KEY` write
+  namespaced skills on the USER store so they cannot collide with the
+  user's own skills.
 
 `validate` still warns about the combination so the store path is
 visible. Cloud turns with neither a hosted store nor an API key see

package/docs/reference/tools.md

@@ -64,7 +64,7 @@ export default defineTool({
 });
 ```
 
-### The `ctx` parameter
+### Tool context
 
 `execute` receives a `ctx` with the runtime accessors:
 
@@ -76,7 +76,7 @@ export default defineTool({
 | `ctx.stateRoot` | The agent's durable state root, shared across every session |
 | `ctx.host` | Shared host services (see below) |
 | `ctx.send(channelId, message, options?)` | Start or resume a session on any channel: the cross-channel handoff primitive, e.g. a chat tool opening a `drive` cloud session for a PR. `auth` defaults to this call's session principal |
-| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel, e.g. refresh `sdkAgentId` after a turn |
+| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel |
 | `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
 
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
@@ -84,9 +84,7 @@ connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
 `host.files` (durable [storage](../storage.md)), `host.otel` (custom
 metrics and session tags; see [OpenTelemetry](../guides/opentelemetry.md)),
-`host.reminders` (per-session wakes, when attached), `host.evals`
-(playground eval batches, when attached), and `host.slackNudges`
-(Slack ask-dedupe helpers).
+`host.reminders` (per-session wakes, when attached).
 
 ### Return values
 
@@ -174,15 +172,15 @@ printf '%s\\n' "$message"
 });
 ```
 
-On the local runtime, scripts land under `.agent-serve/tools/` in the
-session workspace with a catalog in `AGENTS.md`. On cloud, the catalog
-and script bodies travel on the first prompt.
+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.
 
 ## 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
+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
@@ -259,15 +257,12 @@ const outcome = await handle.callTool("inspect_pr", {
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the call runs against an ephemeral scratch workspace under
-`<stateRoot>/tool-calls/<callId>`, materialized like a session workspace
-and removed when the call returns. Pass a `sessionId` (a body field over
+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 under
-a per-call `turnId`, visible in the playground and trajectories like
-any model-initiated call. Session-bound calls serialize with model
-turns and return `409 session_busy` while a turn runs.
+workspace, and the call is recorded on the session's event stream.
+Session-bound calls return `409 session_busy` while a turn runs.
 
 The error semantics match the model path. Unknown tools are rejected
 with the available names, agent-execution tools cannot be called on the

package/docs/scaffolding-agents.md

@@ -22,12 +22,11 @@ Where to find the file depends on how you got the package:
   injects the skill body into context instead of waiting for the
   model to pick it from the catalog. The `/` menu lists them as
   `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
-  copies with the package version. Set
-  `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the copy.
+  copies with the package version.
 - Installed `@cursor/july` as a dependency? The skill also ships inside
   the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
-- Working in the monorepo? It's at
-  `packages/agent-serve/skills/create-agent/SKILL.md`. Run
+- Working from this package's source? The skill is at
+  [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md). Run
   `agent-sdk install-skills` if you want the same copies in
   `~/.cursor/skills/agentsdk/` (the package postinstall skips the
   source checkout).
@@ -127,7 +126,7 @@ inputs again, and adds an eval for each improvement you keep.
 
 ## Related
 
-- [Build your first PR approver](./quickstart.md)
+- [Build your first PR reviewer](./quickstart.md)
 - [Convert a Cursor Automation](./guides/convert-automation.md)
 - [Building agents with agents](./building-with-agents.md)
 - [Evals](./evals.md)

package/docs/storage.md

@@ -7,15 +7,10 @@ description: "Point the Agent SDK's durable storage at a backend you own with de
 
 The Agent SDK owns durable storage for sessions, continuation tokens,
 reminders, playground eval history, and live A/B samples. It chooses the
-keys (under `agentkit/v1/`), when to read and write, and how to restore
-after restart.
+keys, when to read and write, and how to restore after restart.
 
-Keys have bounded length: caller-controlled segments (channel ids,
-continuation tokens) are URI-encoded, and any segment past 256 encoded
-bytes is replaced by its `sha256:…` digest — deterministically, so writes
-and lookups always agree. Backends can rely on this instead of imposing
-their own key-length caps (which would silently drop writes, since a
-throwing `put` is at-most-once).
+The Agent SDK owns key encoding. Backends must accept the keys they are
+given. Do not fail `put` to enforce a shorter cap.
 
 By default that storage lives under `--state-root` on local disk. Fine
 for one machine; it does not survive replacing the host.
@@ -23,8 +18,7 @@ for one machine; it does not survive replacing the host.
 To keep the same framework storage across hosts, plug in a key-value
 backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
 `list`. The optional `cas` group adds conditional writes (see
-[Conditional writes](#conditional-writes-the-cas-group)). The Agent SDK
-does the rest.
+[Conditional writes](#conditional-writes-the-cas-group)).
 
 ```ts
 // agent/storage.ts
@@ -44,15 +38,10 @@ export default defineStorage({
 });
 ```
 
-> [!NOTE]
-> Import paths here use `@cursor/july/storage`. On projects still
-> using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](/#run-the-cli) for the full rename table.
-
 ## Which fields to provide
 
-Implement the small KV core — `put`/`get`/`delete`/`list` plus the `cas`
-group — and you get **full functionality**: eval-run and A/B history are
+Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
+group) and you get **full functionality**: eval-run and A/B history are
 derived over the core automatically. The dedicated `evals` / `abs` groups
 are backend-native optimizations, not required-or-lose-history hooks.
 
@@ -60,13 +49,13 @@ are backend-native optimizations, not required-or-lose-history hooks.
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
 | `cas` | Optional | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
-| `get` | For restore | Look up one key (also: derived A/B snapshot backfill) |
-| `list` | For restore | Return entries under a prefix, in key order (also: derived eval-runs hydrate) |
-| `delete` | For cleanup | Remove a key (also: derived eval-runs pruning) |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
-| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
+| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
+| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
@@ -80,30 +69,20 @@ values. Both are **optional optimizations**: when a group is not
 authored, `defineStorage` derives it over the KV core, so a backend that
 implements only the core loses nothing. Author a group only when the
 backend has a better native shape (a real database table, an analytics
-pipeline) — the built-in `fileKv` and `cursorHostedStorage` both do.
+pipeline). The built-in `fileKv` and `cursorHostedStorage` both do.
 
 `evals` keeps playground eval batches across restarts (`put`, `delete`,
-`list` over run snapshots keyed by `runId`). The Agent SDK upserts a
-snapshot as a batch starts, progresses, and finishes, prunes runs past
-the playground history window, and lists everything back at serve start.
-**Derived form**: one key per run under
-`agentkit/v1/{agent}/eval-runs/{runId}` — needs core `put` + `delete` +
-`list`. Only a core missing `delete` or `list` leaves eval history in
-process memory (cleared on restart). See
-[Evals](./evals.md#configure-eval-runs).
+`list` over run snapshots keyed by `runId`). A core missing `delete` or
+`list` leaves eval history in memory until restart.
+See [Evals](./evals.md#configure-eval-runs).
 
 `abs` exports live A/B metrics: `putSample` appends one cumulative
 metric sample per enrolled experiment on each completed or failed turn;
 optional `putSnapshot` / `getSnapshot` store and serve back the latest
-aggregate so a replacement host with no local sessions can still serve
-the A/Bs surface. **Derived form**: each sample lands as its own key
-(`agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` — a
-blind append-only put, never a read-modify-write of one growing array)
-and the snapshot lives at the fixed `agentkit/v1/{agent}/ab-snapshot`
-key (last-write-wins is correct for "latest aggregate"). `putSample` and
-`putSnapshot` need only core `put`; `getSnapshot` needs core `get`.
-Session event logs remain the assignment source of truth either way. See
-[Live A/B metrics](./ab.md).
+aggregate so a replacement host can still serve the A/Bs surface.
+`putSample` and `putSnapshot` need only core `put`; `getSnapshot` needs
+core `get`. Session event logs remain the assignment source of truth
+either way. See [Live A/B metrics](./ab.md).
 
 ## Policy
 
@@ -137,8 +116,6 @@ follow-up arrives instead of at startup.
 With `get` and `list`, serve can rebuild local state from your store:
 
 - At startup, the Agent SDK loads recent sessions up to the restore caps.
-  Local disk wins when both sides have the same session. Reminders
-  hydrate the same way into `--state-root/reminders`.
 - On demand, a missing continuation token resolves through the store
   and resumes that session.
 - Playground eval history and A/B aggregates can load from the same
@@ -157,19 +134,16 @@ await ctx.host.kv.put("alert-memory/abc", { updated: "…" });
 const prior = await ctx.host.kv.get("alert-memory/abc");
 ```
 
-The Agent SDK prefixes author keys as `agentkit/v1/{agent}/kv/{key}` (same
-bounded encoding as continuation tokens). Writes **await** the sink and
-propagate errors — unlike session mirrors, which are at-most-once.
+Writes **await** the sink and propagate errors, unlike session mirrors,
+which are at-most-once.
 
-Without `agent/storage.ts`, `host.kv` falls back to files under
-`--state-root/kv`. That is fine for local dogfood; it does **not**
-survive replacing the host. For Cursor-managed hosting, prefer
-`@cursor/july/storage/cursor-hosted` so sessions and author KV share the
-platform Bugbot tables through a control-plane HTTP proxy (authenticated
-as the deployment pod credential — engines never receive a database URL).
+Without `agent/storage.ts`, `host.kv` is local-only and does not
+survive replacing the host. Hosted agents should author
+`cursorHostedStorage()` so session and `host.kv` records survive
+replace.
 
 ```ts
-// agent/storage.ts — Cursor-managed hosting
+// agent/storage.ts: Cursor-managed hosting
 import { defineStorage } from "@cursor/july/storage";
 import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
 
@@ -182,32 +156,18 @@ Built-in helpers:
 
 | Import | Backend |
 | --- | --- |
-| `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
-| `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
+| `@cursor/july/storage/file-kv` | File-per-key under the project state directory |
+| `@cursor/july/storage/cursor-hosted` | Cursor-managed hosting; records survive replace |
 
 ## Bring your own backend
 
-There is no built-in Postgres backend on purpose. Cursor's internal
-`agent_serve_*` tables are owned by the backend and reachable only
-through the hosted proxy, and this doc does not prescribe a schema —
-what you back the KV with is your call. Any durable store works:
-
-- **Local disk** — the built-in `fileKv` (single process only).
-- **Object storage (S3-class)** — one object per key; conditional
-  writes map directly onto the contract (`putIfAbsent` = put with
-  `If-None-Match: *`, `putIfVersion` = put with `If-Match: <etag>`,
-  the ETag is the version token, `listKeys` is a prefix listing).
-- **Redis, DynamoDB, a SQL table, …** — anything that can do an
-  atomic compare-and-set and a prefix listing.
-
-Implement the `StorageConfig` methods (and the optional `cas` group)
-against that store. The
-contract, defined at `@cursor/july/kv`: version tokens are opaque
-strings that change on every successful write — including plain
-`put`, so a stale token fences instead of clobbering; conditional
-writes are atomic; `listKeys` returns every key under the prefix.
-`@cursor/july/kv/memory` is a complete reference implementation to
-compare behavior against.
+Any durable store works if it can put, get, delete, list by prefix,
+and optionally compare-and-set. Implement the `StorageConfig` methods
+(and the optional `cas` group) against that store. The contract,
+defined at `@cursor/july/kv`: version tokens are opaque strings that
+change on every successful write, including plain `put`, so a stale
+token fences instead of clobbering; conditional writes are atomic;
+`listKeys` returns every key under the prefix.
 
 ## Conditional writes (the `cas` group)
 
@@ -215,10 +175,7 @@ The `cas` group is compare-and-swap over the same keyspace:
 `getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
 backend-agnostically at `@cursor/july/kv`. Plain storage works without
 it, so an existing backend keeps working across a platform upgrade.
-`defineStorage` rejects a partial group — implement all four methods or
+`defineStorage` rejects a partial group. Implement all four methods or
 none. Version tokens are opaque strings that must change on every write
 (a counter column, a row version, a content hash). The built-in backends
-both include it: `fileKv` uses content-hash tokens (single-process
-correctness) and `cursorHostedStorage` the control-plane proxy (a
-`version` counter on the server). `memoryCasTable()` is for test fixtures
-and inert sinks only.
+both include the group.

package/docs/templates/agentic-owners.md

@@ -32,7 +32,7 @@ agent-sdk login
 agent-sdk dev
 ```
 
-PR events stream through your Cursor account — no webhook or GitHub App
+PR events stream through your Cursor account. No webhook or GitHub App
 setup. Open a PR, or replay a real one deterministically (this also works
 with `repos` empty):
 
@@ -75,7 +75,7 @@ applies the deterministic decision:
 
 - **Approve** when the tier is low and no matched rule demands a human,
   bound to the head SHA.
-- **Request reviewers** otherwise — the policy owners (max 2, never the
+- **Request reviewers** otherwise: the policy owners (max 2, never the
   author), plus one status comment the agent keeps updated in place.
 
 The model never writes to GitHub. A broken policy file fails closed with

package/docs/templates/pr-autofixer.md

@@ -91,12 +91,9 @@ opted-in PR wakes the agent. A comment on a plain GitHub issue does
 not. The channel buffers about 3 seconds per PR. Payload details are
 dropped on purpose. The follow-up says something changed.
 
-Pending wakes snapshot to `host.kv` (`webhook-buffer`) before the
-webhook is ACKed, and restore on restart. Affinity is
-`affinity/{owner/repo#N}` → `bc-…` in the same store, written from
-`agent.bound`. `agent/storage.ts` uses `cursorHostedStorage`, so both
-survive host replace. Local serve without that plug-in falls back to
-`--state-root/kv`.
+Pending wakes and the PR-to-cloud-agent map persist in `host.kv` so
+they survive restart. `cursorHostedStorage` keeps both across replace.
+Without that plug-in, `host.kv` is local-only.
 
 Closing a PR cancels its merge-conflict reminder and drops buffered
 wakes.

package/docs/troubleshooting.md

@@ -12,8 +12,8 @@ Start with four checks, in order:
 3. What the playground or HTTP API shows
 4. The session event stream (trace)
 
-Match your symptom below. Keep the commands as `agent-sdk`; see
-[Run the CLI](/#run-the-cli) if you still need an alias.
+Match your symptom below. Keep the commands as `agent-sdk`. If it is
+not on `PATH`, use `npx @cursor/july`.
 
 ## What if serve or the playground looks wrong?
 
@@ -21,9 +21,9 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | `serve` won't start | Run `agent-sdk validate --dir .` and fix the reported errors. |
 | Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
-| Edits to the playground don't show up | Use `serve --dev` and open the printed playground HMR URL (often port `5273`), not only the static `:3000` URL. |
-| Sessions exist on disk but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…` or inspect `sessions/` under your state root. |
-| Port 3000 or 5273 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port. |
+| The playground UI looks stale | `serve --dev` prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY). |
+| Sessions exist but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…`. |
+| Port 3000 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port. |
 
 ## What if a model turn goes wrong?
 
@@ -31,7 +31,7 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
 | The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
-| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
+| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
 | Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or `hostOnly` hid the connection, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |
 | `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.91",
+  "version": "0.1.93",
   "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": {
@@ -47,6 +47,13 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./internal/hosted-delivery-protocol": {
+      "anysphere-source": "./src/internal/hosted-delivery-protocol.ts",
+      "bun": "./dist/internal/hosted-delivery-protocol.js",
+      "types": "./dist/internal/hosted-delivery-protocol.d.ts",
+      "import": "./dist/internal/hosted-delivery-protocol.js",
+      "default": "./dist/internal/hosted-delivery-protocol.js"
+    },
     "./tools": {
       "anysphere-source": "./src/tools.ts",
       "types": "./dist/tools.d.ts",
@@ -226,7 +233,7 @@
   },
   "dependencies": {
     "@bazel/runfiles": "6.5.0",
-    "@cursor/sdk": "1.0.28",
+    "@cursor/sdk": "1.0.30",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",

package/skills/ab/SKILL.md

@@ -9,6 +9,9 @@ description: >-
 
 # Agent SDK A/B metrics (`defineAB`)
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 `defineAB` is a **live metrics plug-in**. At session creation the engine runs
 `split` and appends durable `ab.assigned` events; the collector folds the
 session event stream and calls `onSample`. There is **no** `agent-sdk ab`

package/skills/create-agent/SKILL.md

@@ -11,6 +11,9 @@ paths:
 
 # Create an Agent SDK agent
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Stand up one new agent project via a short interview, scaffold it, get
 channels working
 with the user, prove a turn runs end-to-end, and set up the improvement loop.

package/skills/debug/SKILL.md

@@ -10,6 +10,9 @@ description: >-
 
 # Debugging the Agent SDK locally
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 This skill is **local** `agent-sdk serve` / playground. A **hosted**
 deployment that is stopped, slow to start, or failing `/v1/health` is
 `.cursor/skills/debugging/debug-agent-serve-deployment/SKILL.md`.

package/skills/evals/SKILL.md

@@ -9,6 +9,9 @@ description: >-
 
 # Agent SDK evals
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Evals are the ratchet that makes iteration trustworthy: a fixed input, a
 model turn, and gates over the recorded trajectory. They live at the
 **project root** `evals/**/*.eval.ts` (never `agent/evals/` — that slot is

package/skills/framework-map/SKILL.md

@@ -16,6 +16,9 @@ over HTTP/Slack/GitHub channels, with the Cursor SDK + harness as the
 execution engine. Ground truth is the package `README.md` (full reference)
 and `AGENTS.md` (coding-agent loop) — this skill is the map, not the spec.
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Run the CLI as `agent-sdk <cmd>`. In the everysphere monorepo there is no
 installed bin — use:
 

package/skills/github/SKILL.md

@@ -9,6 +9,9 @@ description: >-
 
 # GitHub channels in the Agent SDK
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Author `agent/channels/github.ts` with `githubChannel()` from
 `@cursor/july/channels/github`. It mounts
 `POST /<slug>/v1/channels/github` and publishes the events it dispatches on

package/skills/hillclimb/SKILL.md

@@ -11,6 +11,9 @@ paths:
 
 # Agent SDK hillclimb
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Optimize one Agent SDK agent project
 with a tight measure → change → remeasure loop. Do not redesign the
 whole framework; climb one concrete failure mode at a time. Sibling skills:

package/skills/mcp-auth/SKILL.md

@@ -8,6 +8,9 @@ description: >-
 
 # Host MCP OAuth (mcp auth)
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Use this skill when a human asks to authorize a remote MCP server on an
 Agent SDK host, store credentials for Cursor-managed hosting, or debug
 `host.mcp` auth failures for `oauth: true` connections.

package/skills/otel/SKILL.md

@@ -8,6 +8,9 @@ description: >-
 
 # Agent SDK OpenTelemetry (`defineOtel`)
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Push session, turn, tool, and subagent traces, plus token and cost
 metrics, from the serve process to an OTLP collector. Logs are off
 until you opt in.

package/skills/setup-slack/SKILL.md

@@ -9,6 +9,9 @@ description: >-
 
 # Setup Slack for the Agent SDK
 
+Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
+host serves the same index at `/docs/llms.txt`.
+
 Use this skill when a human asks to wire Slack to an Agent SDK agent.
 
 There are **two ways to connect**: