npm - @cursor/july - Versions diffs - 0.1.35 → 0.1.36 - Mend

@cursor/july 0.1.35 → 0.1.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (195) hide show

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-D7OV8B_H.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-DOb96C0M.css">
+    <script type="module" crossorigin src="./assets/index-DOnKC85G.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-DoQjqj5w.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/README.md CHANGED Viewed

@@ -36,7 +36,19 @@ my-agent/
 └── evals/                   # filesystem evals (regression checks)
 ```
-Browse it locally without serving an agent:
+Bootstrap a project with nothing installed beyond Node:
+```bash
+npx @cursor/july init ./my-agent
+cd my-agent
+npx agent-sdk dev
+```
+`init` scaffolds the project, runs `npm install`, and offers a Cursor
+sign-in. The install puts the `agent-sdk` bin on the project's path, so
+`npx agent-sdk` resolves locally from then on.
+Browse the docs locally without serving an agent:
 ```bash
 npx @cursor/july docs
@@ -80,6 +92,8 @@ Pick your entry point based on your goal.
   evals as regression checks.
 - [Live A/B metrics](./ab.md): assign sticky variants and compare
   cumulative metrics on live sessions.
+- [Storage](./storage.md): point durable storage at a backend you own
+  with `defineStorage`.
 - [Hillclimbing](./hillclimbing.md): make an agent better one measured
   round at a time.
@@ -102,7 +116,7 @@ Pick your entry point based on your goal.
 **Example agents**
-- [Choose the right example](./example-agents/index.md): compare all eleven
+- [Choose the right example](./example-agents/index.md): compare all twelve
   agents by runtime, channels, tools, state, and architecture.
 - [Weather agent](./example-agents/weather-agent.md): explore tools, MCP,
   approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.
@@ -112,6 +126,8 @@ Pick your entry point based on your goal.
   with its own context and sessions.
 - [Playbook router](./example-agents/benny.md): route Slack intake through inherited
   repository playbooks.
+- [Alert investigator](./example-agents/oncall.md): watch a Slack alerts
+  channel and pin a self-rechecking investigation to every alert thread.
 - [PR evidence reviewer](./example-agents/bugbot.md): review a host-prepared,
   diff-first pull-request evidence tree.
 - [Approval Buddy](./example-agents/approval-buddy.md): keep approval policy
@@ -154,7 +170,14 @@ Pick your entry point based on your goal.
 ## Run the CLI
 The docs write commands as `agent-sdk <command>`. Where that command
-comes from depends on where you run.
+comes from depends on where you run. Starting fresh? This works with no
+prior install:
+```bash
+npx @cursor/july init ./my-agent
+cd my-agent
+npx agent-sdk dev
+```
 > [!NOTE]
 > When running from a source checkout there is no installed bin. Alias it from
@@ -171,22 +194,18 @@ comes from depends on where you run.
 > runs the `july` bin with that command (no local install required).
 > [!NOTE]
-> The framework is being renamed from agent-serve to the Agent SDK,
-> and CLI examples use the new `agent-sdk` name. Paths, package imports,
-> and environment variables keep their current names until the code rename
-> ships:
+> The framework is being renamed from agent-serve to the Agent SDK. The
+> `agent-sdk` bin already ships (alongside `july`, `agentkit`, and the
+> legacy `agent-serve` alias), and projects already import from
+> `@cursor/july`. A few on-disk names keep their old form until the code
+> rename ships:
 >
-> | Docs say | Current name |
+> | Future name | Current name |
 > | --- | --- |
-> | `@cursor/july` imports and dependency | `@cursor/july` |
-> | `agent-sdk` bin | `agent-serve` |
-> | `dist/bin/agent-sdk.js` | `dist/bin/agent-serve.js` |
 > | `.agent-sdk/` state directory | `.agent-serve/` |
 > | `/var/lib/agent-sdk` (deploy state root) | `/var/lib/agent-serve` |
 > | `CURSOR_AGENT_SDK_*` env vars | `AGENT_SERVE_*` |
-> | `agent-sdk (<hostname>)` API key name | `agent-serve (<hostname>)` |
 > | Package path `packages/agent-sdk` | `packages/agent-serve` |
-> | Package skills `packages/agent-sdk/skills/` | `packages/agent-serve/skills/` |
 > [!WARNING]
 > Run the Agent SDK with Node 22.13 or newer, and never with Bun.

package/docs/ab.md CHANGED Viewed

@@ -19,7 +19,7 @@ on fixed inputs.
 > [!NOTE]
 > Import paths here use `@cursor/july/ab`. On projects still
-> using `@cursor/july`, swap the import. See
+> using `@anysphere/agent-serve`, swap the import. See
 > [Run the CLI](./README.md#run-the-cli) for the full rename table.
 ## Choose live A/B metrics or evals
@@ -208,6 +208,7 @@ turn and tool events into its own counters.
 | `toolErrors` | Adds one when `action.result.data.isError` is true |
 | `inputTokens`, `outputTokens` | Adds usage from completed turns |
 | `cacheReadTokens`, `cacheWriteTokens` | Adds cache usage from completed turns |
+| `costUsd` | Sums the estimated turn cost recorded on `turn.completed` (turns whose model has no known rates contribute 0) |
 | `wallTimeMs` | Sums the time from `turn.started` to its completed or failed event |
 | `custom` | Sums finite numeric deltas returned by `derive` |
@@ -254,44 +255,30 @@ too. This include-all behavior can still apply to `GET /v1/abs` in dev
 when bearer or custom auth keeps `GET /v1/sessions` owner-scoped.
 Session `events.ndjson` is the source of truth for assignment + fold.
-`GET /v1/abs` recomputes aggregates from those logs. Use
-`agent/ab.config.ts` (and/or each experiment's `onSample`) when you want
-author-controlled sample/snapshot exports — same idea as eval
-`persistRuns`.
+`GET /v1/abs` recomputes aggregates from those logs. For durable
+sample and snapshot export, declare an `abs` table in
+`agent/storage.ts` — same idea as the eval-runs table. See
+[Storage](./storage.md#eval-and-ab-tables).
-## Configure retention and persistence
+## Configure the playground fold window
-Optional project defaults in `agent/ab.config.ts`:
+Assignments and foldable metrics already persist in each session's
+`events.ndjson` under `--state-root`. The optional `agent/ab.config.ts`
+only caps how many sessions the playground and `GET /v1/abs` fold:
 ```ts
-import {
-  defineABConfig,
-  persistABSamplesToDir,
-  persistABSnapshotsToDir,
-} from "@cursor/july/ab";
+import { defineABConfig } from "@cursor/july/ab";
 export default defineABConfig({
   // Optional — defaults to 200. Only affects GET /v1/abs / A/Bs tab.
-  // maxPlaygroundSessions: 200,
-  // retainSnapshots: 20, // prune budget for persistABSnapshotsToDir
-  // Append onSample payloads (in addition to each experiment's onSample)
-  persistSamples: persistABSamplesToDir(".agent-serve/ab-samples"),
-  // Save aggregate snapshots whenever GET /v1/abs runs
-  persistSnapshots: persistABSnapshotsToDir(".agent-serve/ab-snapshots"),
+  maxPlaygroundSessions: 500,
 });
 ```
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `maxPlaygroundSessions` | `200` | Max newest sessions folded into the playground / `GET /v1/abs` (not session logs or `persistSamples`) |
-| `persistSamples` | unset | Durable sink for metric samples (`save(sample, ctx)`) |
-| `persistSnapshots` | unset | Durable store for aggregate snapshots (`load` / `save` / optional `delete`) |
-| `retainSnapshots` | `20` when snapshots persist | Snapshot files kept after prune (`persistABSnapshotsToDir` honors this) |
-Implement your own `{ save }` / `{ load, save, delete? }` for S3, a DB, or
-your metrics vendor. Without `persistSamples` / `persistSnapshots`,
-samples only go where each experiment's `onSample` sends them, and
-aggregates exist only as a live fold over session logs.
+`maxPlaygroundSessions` keeps the newest sessions in the fold. It does
+not prune session logs or change assignment. For export to S3, a DB, or
+your metrics vendor, send samples from `onSample` or declare a storage
+`abs` table.
 ## Keep assignments durable
@@ -301,8 +288,8 @@ metrics come from the turn and tool events that follow it.
 After a server restart or a parked session resumes, the live collector
 replays the stream to rebuild cumulative counters. Replay does not call
-`onSample` (or `persistSamples`) for historical turns. Only a new
-completed or failed turn emits another sample.
+`onSample` (or write to the storage `abs` table) for historical turns.
+Only a new completed or failed turn emits another sample.
 The snapshot API also replays `derive` across the full stream, so
 custom totals match the current extractor. Changing a derive function
@@ -332,12 +319,12 @@ does not provide:
 - Statistical significance calculations
 - An experiment rollout or lifecycle service
 - Per-variant model or runtime configuration
-- A built-in analytics warehouse (bring your own via `persistSamples` /
-  `persistSnapshots` / `onSample`)
+- A built-in analytics warehouse (bring your own via `onSample` or the
+  storage `abs` table)
-Use [evals](./evals.md) to protect known behavior. Configure
-`agent/ab.config.ts` (or `onSample`) when you need sample/snapshot
-exports beyond the session event log.
+Use [evals](./evals.md) to protect known behavior. Use `onSample` or a
+storage `abs` table when you need sample/snapshot exports beyond the
+session event log.
 ## What's next

package/docs/building-with-agents.md CHANGED Viewed

@@ -37,7 +37,7 @@ project, and verifies the result.
 For example:
-> Use the agent-serve create-agent skill to build a PR triage agent
+> Use the Agent SDK create-agent skill to build a PR triage agent
 > reachable through GitHub. It should summarize failed checks, require
 > approval before posting a review, and include one smoke eval.
@@ -83,7 +83,7 @@ agent-sdk call inspect_pr --dir . \
 agent-sdk run --dir . \
   --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
-agent-sdk trajectory --events .agent-sdk/traces/<sessionId>.ndjson
+agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
 agent-sdk eval --dir . --list
 agent-sdk eval --dir . --json

package/docs/concepts.md CHANGED Viewed

@@ -110,7 +110,8 @@ Choose a runtime in `agent/agent.ts`:
 | | Local (default) | Cloud |
 | --- | --- | --- |
 | Turn runs on | The server host | A Cursor cloud agent |
-| Server tools and approvals | Supported | Not supported |
+| Server tools | Supported | Supported when the server has `--public-url` or `--cloud-tools-url`; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them. |
+| Approvals (`needsApproval`) | Supported | Not supported (local runtime only) |
 | Agent tool scripts | Supported | Supported |
 | Skills and seeded files | Added to the session workspace | Must exist in the cloud repository |
 | Repository | You provide it | The cloud agent checks it out |
@@ -137,7 +138,7 @@ commands already use temporary state.
 Durable local state uses this shape:
 ```text
-<project>/.agent-sdk/
+<project>/.agent-serve/
   sessions/<id>/events.ndjson
   sessions/<id>/workspace/
   traces/<sessionId>.ndjson

package/docs/deployment.md CHANGED Viewed

@@ -305,7 +305,7 @@ A self-hosted server can read these credentials.
 Use a dedicated Cursor key per host. `agent-sdk whoami` shows the active
 credential. `logout` removes the stored key from the host; revoke the key
 in the Cursor dashboard to invalidate it. See
-[CLI authentication](./reference/cli.md#login--logout--whoami) for
+[CLI authentication](./reference/cli.md#login-logout-whoami) for
 credential resolution.
 ### State

package/docs/evals.md CHANGED Viewed

@@ -18,7 +18,7 @@ accepted a message, and did what you asserted.
 > [!NOTE]
 > Import paths here use `@cursor/july/evals`. On projects still
-> using `@cursor/july`, swap the import and run
+> using `@anysphere/agent-serve`, swap the import and run
 > `agent-serve eval`. See
 > [Run the CLI](./README.md#run-the-cli) for the full rename table.
@@ -118,35 +118,39 @@ issues real model-provider requests, so concurrency is capped hard at
 without this file, but running a case does not.
 ```ts
-import {
-  defineEvalConfig,
-  persistEvalRunsToDir,
-} from "@cursor/july/evals";
+import { defineEvalConfig } from "@cursor/july/evals";
 export default defineEvalConfig({
   maxConcurrency: 20, // required
   // timeoutMs: 180_000, // optional project-wide default
+  // judge: { model: "..." }, // default judge model for t.judge.*
+  // reporters: [], // destinations that observe every case
   // maxPlaygroundRuns: 50, // playground /v1/dev/evals history only (default 20)
-  //
-  // Playground batches default to **process memory only** — they disappear
-  // when `serve` exits. Opt into durable storage:
-  // persistRuns: persistEvalRunsToDir(".agent-serve/eval-runs"),
-  // Or implement { load, save, delete } yourself (S3, DB, …).
 });
 ```
 The timeout order is case or file `timeoutMs`, CLI `--timeout-ms`,
 project config `timeoutMs`, then the 180-second runner default.
-Playground batch retention is separate from case concurrency:
+The optional fields:
 | Option | Default | Meaning |
 | --- | --- | --- |
+| `timeoutMs` | `180_000` | Project-wide per-case timeout |
+| `judge` | unset | Default judge model for `t.judge.*`; see [Judge free-form output](#judge-free-form-output) |
+| `reporters` | unset | Destinations that observe every case; `--skip-report` suppresses them |
 | `maxPlaygroundRuns` | `20` | Max batches in the playground / `/v1/dev/evals*` history (not CLI `eval`) |
-| `persistRuns` | unset | Optional `{ load, save, delete }` so batches survive process restart (`delete` required for durable prune) |
-Without `persistRuns`, navigating away and back still works while the same
-`serve` process is up; a restart clears history.
+Reporters come from `@cursor/july/evals/reporters`: `JUnit` writes a
+JUnit XML file for CI, `Artifacts` writes per-case files, and
+`combineReporters` merges several into one (`renderJUnitXml` renders
+the XML for a custom destination). A file or case can add its own
+`reporters` on top of the config list.
+Playground batches live in process memory and disappear when `serve`
+exits. Navigating away and back still works while the process is up.
+To keep batches across restarts, declare an `evals` table in
+`agent/storage.ts`; see [Storage](./storage.md#eval-and-ab-tables).
 ## Drive and assert with `t`
@@ -155,33 +159,71 @@ control flow, sending turns and asserting inline.
 Drive the agent with `t.send(message, options?)`. It runs one turn and
 waits for the session to park or fail. Multiple sends in one case share
-the session, which is how you write multi-turn evals. The return value
-contains the turn's `message`, `sessionId`, `events`, `toolCalls`, and
-`ok` state.
+the session, which is how you write multi-turn evals.
+Each `t.send` resolves to a turn result with `message`, `sessionId`,
+`events`, `toolCalls`, `ok`, and `index`. The turn carries the same
+assertion vocabulary as `t`, scoped to that turn, so you can grade an
+intermediate turn before the next send overwrites `t.reply`.
+`turn.expectOk()` throws when the turn failed, for later steps that
+depend on it.
 Read the full case state with `t.reply` (the last assistant text),
-`t.events` (every captured session event across turns), and
-`t.sessionId`.
+`t.events` (every captured session event across turns), `t.turns`
+(settled turns, oldest first), and `t.sessionId`. `t.signal` aborts
+when the case hits its timeout; pass it to your own async work.
 Assert with the gates:
 | Gate | Checks |
 | --- | --- |
-| `t.succeeded()` | the captured trajectory has at least one turn and did not fail |
-| `t.calledTool(name)` | `name` appears in the captured tool calls |
-| `t.notCalledTool(name)` | `name` does not appear in the captured tool calls |
-| `t.messageIncludes(token)` | the last assistant reply matches a string or `RegExp` |
+| `t.succeeded()` | the run did not fail and is not parked on an unanswered approval |
+| `t.parked()` | the run cleanly parked on an unanswered approval request |
+| `t.messageIncludes(token)` | the joined assistant text matches a string or `RegExp` |
+| `t.calledTool(name, matcher?)` | a matching call to `name` happened |
+| `t.notCalledTool(name)` | no request for `name`, in any lifecycle state |
+| `t.loadedSkill(name)` | the agent opened the skill's `SKILL.md` (read, grep, or shell `cat`) |
+| `t.toolOrder(names)` | tool requests appear in this relative order (extra calls allowed) |
+| `t.usedNoTools()` | no tool calls at all |
+| `t.maxToolCalls(max)` | at most `max` tool calls |
+| `t.noFailedActions()` | no tool call reported an error |
+| `t.calledSubagent(name, matcher?)` | a matching subagent delegation happened |
+| `t.taggedArtifact(kind?, predicate?)` | at least one [artifact](./reference/artifacts.md) was tagged |
+| `t.event(type, matcher?)` | at least one matching event of `type` occurred |
+| `t.notEvent(type, matcher?)` | no matching event of `type` occurred |
+| `t.eventOrder(matchers)` | matching event groups occur in this relative order |
+| `t.eventsSatisfy(label, predicate)` | your predicate over the typed event stream |
 | `t.check(value, expectation)` | any value, against a builder |
+| `t.score(name, value)` | records a 0–1 score you computed; soft until you add a bar |
+| `t.requireToolCall(name, matcher?)` | gates on a matching call and returns it, so later code can read its input and output |
+| `t.requireInputRequest(filter?)` | gates on exactly one pending approval request and returns it |
+Every gate returns a handle: `.soft()` demotes it to tracked-only,
+`.atLeast(0.7)` adds a soft score bar, and `.gate(0.8)` promotes a
+scored assertion into a hard gate.
-`calledTool` reads the recorded trajectory. A requested call counts even
-when its result has not arrived. To require a completed result, inspect
-`t.events` for an `action.result` event.
+With no matcher, `calledTool` is request-based: a requested call counts
+even when its result has not arrived. Pass
+`t.calledTool("inspect_pr", { status: "completed" })` to require the
+call to return. `input`, `output`, and `count` matcher fields accept a
+literal, a `RegExp`, or a predicate.
 The expectation builders are `includes(string | RegExp)`,
-`equals(value)`, and `satisfies(predicate, label)`. `includes`
-stringifies its input, `equals` compares values deeply, and `satisfies`
-runs your predicate. `t.log(message)` records a debug line for the CLI
-and playground result.
+`equals(value)`, `matches(schema)`, `similarity(expected)`, and
+`satisfies(predicate, label)`. `includes` stringifies its input,
+`equals` compares values deeply, `matches` validates against a Standard
+Schema (or anything with `safeParse`, like Zod), `similarity` scores
+normalized text similarity, and `satisfies` runs your predicate. The
+plain function `normalizedSimilarity(actual, expected)` returns the
+same 0–1 score for use with `t.score`.
+A few more context members shape a case: `t.require(value, expectation)`
+records a gate and stops the test body when it fails, without a
+duplicate execution error. `t.skip(reason)` ends the case as skipped
+(reported separately, never changes the exit code; call it before
+sending messages). `t.metric(name, value)` records a structured score
+for the playground case card. `t.log(message)` records a debug line for
+the CLI and playground result.
 Three `t.send` options apply on session create (first `t.send` only):
@@ -205,6 +247,26 @@ A case with no explicit gates falls back to whether at least one turn
 completed successfully. Add `t.succeeded()` and behavior-specific gates
 anyway. They make the contract visible during review.
+### Judge free-form output
+When wording matters and no regex captures it, `t.judge` grades the
+reply with an LLM. The built-in graders are `factuality(expected)`,
+`summarizes(expected)`, `closedQA(criteria)`, and `sql(expected)`. Each
+scores `t.reply` by default; pass `{ on }` to grade another value.
+```ts
+t.judge.factuality("It is 54°F in NYC right now.").atLeast(0.7);
+```
+Judge assertions are soft by default, so a judge never fails a build
+until you give it a bar with `.atLeast(0.7)` or promote it with
+`.gate(0.8)`. The judge model comes from `defineEvalConfig({ judge })`,
+`defineEval({ judge })`, a case-level `judge`, or a per-call
+`{ model }` override; the nearest one wins. For a domain-specific judge
+whose verdict is not a single score, `t.judge.model(prompt)` sends a
+raw prompt to the same model and returns the reply. You then record the
+parsed result with `t.score` or `t.check`.
 ## Run evals from the CLI
 The `eval` command discovers, filters, and runs cases.
@@ -230,7 +292,7 @@ match both groups.
 `eval` boots an ephemeral server on port 0 with a temp state root
 outside the project, so cases don't inherit ambient monorepo rules and
-don't pollute `.agent-sdk/`. Point `--url` at a running server to eval
+don't pollute `.agent-serve/`. Point `--url` at a running server to eval
 a live agent instead:
 ```bash
@@ -299,8 +361,9 @@ agent-sdk serve --dir . --dev
 Playground runs target the live server instead of an ephemeral one.
 Their sessions appear in the session list. One eval batch can run at a
 time. By default those batches are **in-memory only** (capped by
-`maxPlaygroundRuns`); set `persistRuns` in `evals.config.ts` if you need them
-after a serve restart — see [Configure eval runs](#configure-eval-runs).
+`maxPlaygroundRuns`); declare an `evals` table in `agent/storage.ts` if
+you need them after a serve restart — see
+[Storage](./storage.md#eval-and-ab-tables).
 The UI uses the playground eval routes (available without `--dev`):
 `GET /v1/dev/evals` lists datapoints and config (includes `maxPlaygroundRuns` /
@@ -378,6 +441,12 @@ once and commit the rendered fixture before you expand the suite.
 3. Assert decisions and output shape against the saved evidence.
 4. Keep a small `smoke` subset for any remaining live pipeline checks.
+Read committed fixtures with `@cursor/july/evals/loaders`: `loadJson`,
+`loadJsonl`, and `loadYaml` resolve relative paths against the project
+root the runner discovered, not the cwd the CLI was invoked from
+(`resolveFixturePath` and `evalFixtureRoot` expose the same
+resolution for other file formats).
 `maxConcurrency` limits parallel datapoints. It does not limit model or
 API fan-out inside one datapoint. Materialized fixtures prevent a large
 suite from exhausting provider and GitHub rate limits. The

package/docs/example-agents/approval-buddy.md CHANGED Viewed

@@ -70,10 +70,11 @@ approving the PR.
 | Deterministic policy | [`agent/lib/approve.ts`](../../examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](../../examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
 | Review subagents | [`agent/subagents/`](../../examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
 | Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage` (Bugbot `agent_serve_*`). |
+| Live A/B experiment | [`agent/ab.ts`](../../examples/approval-buddy/agent/ab.ts) | Compare baseline responses with a concise, presentation-only treatment (`concise-results`). |
 | Evals and unit tests | [`evals/`](../../examples/approval-buddy/evals/), [`agent/lib/`](../../examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
 There are no authored skills, MCP connections, schedules, reminders, hooks,
-A/B experiments, sandbox seeds, or tool approvals.
+sandbox seeds, or tool approvals.
 ## Prepare credentials

package/docs/example-agents/benny.md CHANGED Viewed

@@ -52,6 +52,8 @@ need the watched-channel path.
 | [`agent/instructions.md`](../../examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
 | [`agent/channels/slack.ts`](../../examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
 | [`agent/channels/slack-app.ts`](../../examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
+| [`agent/storage.ts`](../../examples/benny/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/benny/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/smoke.eval.ts`](../../examples/benny/evals/smoke.eval.ts) | Checks the agent identity and expected triage route. |
 The playbook router authors no tools, MCP connections, subagents, schedules, hooks, A/B

package/docs/example-agents/bugbot.md CHANGED Viewed

@@ -58,6 +58,9 @@ mid-turn. That form writes the same files into the active session workspace.
 | [`agent/channels/review.ts`](../../examples/bugbot/agent/channels/review.ts) | Provides the loopback-only prepare-and-send HTTP route. |
 | [`agent/channels/slack.ts`](../../examples/bugbot/agent/channels/slack.ts) | Extracts PR references and prepares evidence for mentions and direct messages. |
 | [`agent/skills/pr-review.md`](../../examples/bugbot/agent/skills/pr-review.md) | Sets finding limits, severities, and the machine-readable review format. |
+| [`agent/lib/log.ts`](../../examples/bugbot/agent/lib/log.ts) | Writes timing logs for the host tools to stderr. |
+| [`agent/storage.ts`](../../examples/bugbot/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/bugbot/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/review/smoke.eval.ts`](../../examples/bugbot/evals/review/smoke.eval.ts) | Seeds fake evidence and checks the review path without GitHub. |
 There is no authored GitHub channel, MCP connection, subagent, schedule,

package/docs/example-agents/codebase-wiki.md CHANGED Viewed

@@ -67,6 +67,8 @@ tool, which writes the digest into the active session workspace.
 | [`agent/skills/feature-mapping.md`](../../examples/codebase-wiki/agent/skills/feature-mapping.md) | Maps changes onto features and fixes the page and changelog shape. |
 | [`agent/schedules/daily-digest.md`](../../examples/codebase-wiki/agent/schedules/daily-digest.md) | Writes `digests/<date>`, rebuilds the index, and flags stale pages. |
 | [`agent/channels/github.ts`](../../examples/codebase-wiki/agent/channels/github.ts) | Acknowledges closed PRs and starts merged-only ingest turns. |
+| [`agent/storage.ts`](../../examples/codebase-wiki/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/codebase-wiki/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/ingest.eval.ts`](../../examples/codebase-wiki/evals/ingest.eval.ts) | Gates ingest decisions against the wiki filesystem. |
 There is no MCP connection, subagent, hook, A/B experiment, or custom

package/docs/example-agents/codeowners-review.md CHANGED Viewed

@@ -74,6 +74,8 @@ APPROVE and commit statuses on top of the same shape.
 | [`agent/subagents/area-reviewer/`](../../examples/codeowners-review/agent/subagents/area-reviewer/) | Defines the one-area, one-playbook reviewer contract. |
 | [`agent/channels/github.ts`](../../examples/codeowners-review/agent/channels/github.ts) | Reviews opened, reopened, synchronized, and undrafted PRs. |
 | [`fixtures/`](../../examples/codeowners-review/fixtures/) | Ships two reviewable PRs with known planted findings. |
+| [`agent/storage.ts`](../../examples/codeowners-review/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/codeowners-review/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/review.eval.ts`](../../examples/codeowners-review/evals/review.eval.ts) | Gates routing, fan-out, planted bugs, and verdicts. |
 There is no MCP connection, schedule, hook, A/B experiment, or custom

package/docs/example-agents/concierge.md CHANGED Viewed

@@ -68,6 +68,7 @@ share Concierge's conversation history.
 | [`agent/agent.ts`](../../examples/concierge/agent/agent.ts) | Describes the root agent and selects the local runtime. |
 | [`agent/instructions.md`](../../examples/concierge/agent/instructions.md) | Draws a strict weather-only delegation boundary. |
 | [`agent/mcp-connections/weather.ts`](../../examples/concierge/agent/mcp-connections/weather.ts) | Resolves the peer by its `weather-agent` slug. |
+| [`agent/storage.ts`](../../examples/concierge/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
 Concierge doesn't author channels, tools, skills, subagents, schedules,
 hooks, A/B experiments, or evals. The built-in HTTP and MCP surfaces still

package/docs/example-agents/fsd.md CHANGED Viewed

@@ -74,6 +74,7 @@ has `status: "finished"` and no remote session.
 | Affinity and buffering | [`agent/lib/pr-affinity.ts`](../../examples/fsd/agent/lib/pr-affinity.ts), [`agent/lib/webhook-buffer.ts`](../../examples/fsd/agent/lib/webhook-buffer.ts) | Persist PR identity, sticky mode, and pending wakes. |
 | Reminders | [`agent/lib/merge-conflict-watch.ts`](../../examples/fsd/agent/lib/merge-conflict-watch.ts) | Recheck merge conflicts every 30 minutes. |
 | Workflow client | [`agent/lib/fsd-platform.ts`](../../examples/fsd/agent/lib/fsd-platform.ts) | Enroll external runs and read or record findings. |
+| Storage | [`agent/storage.ts`](../../examples/fsd/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. |
 The coordinator has no authored skill, subagent, MCP connection, static
 schedule, A/B experiment, eval, custom storage definition, or tool approval.

package/docs/example-agents/knowledge-base.md CHANGED Viewed

@@ -65,6 +65,8 @@ one-off questions and to ask before saving anything borderline.
 | [`agent/skills/wiki-conventions.md`](../../examples/knowledge-base/agent/skills/wiki-conventions.md) | Names pages, shapes them, and dates every fact. |
 | [`agent/schedules/gardener.md`](../../examples/knowledge-base/agent/schedules/gardener.md) | Merges duplicates, rebuilds the index, and flags stale facts daily. |
 | [`agent/lib/wiki-store.test.ts`](../../examples/knowledge-base/agent/lib/wiki-store.test.ts) | Unit-tests slug safety and store round-trips. |
+| [`agent/storage.ts`](../../examples/knowledge-base/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/knowledge-base/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/knowledge.eval.ts`](../../examples/knowledge-base/evals/knowledge.eval.ts) | Seeds a temp knowledge base and gates recall, save, and no-write decisions. |
 There is no authored channel, MCP connection, subagent, hook, A/B

package/docs/example-agents/oncall.md CHANGED Viewed

@@ -51,6 +51,8 @@ Mentions and DMs skip the watch entirely and behave like ordinary chat.
 | [`agent/lib/slack-api.ts`](../../examples/oncall/agent/lib/slack-api.ts) | Reactions and thread posts on this agent's own token pair. |
 | [`agent/tools/reminders_create.ts`](../../examples/oncall/agent/tools/reminders_create.ts) | Self-scheduled wakes bound to the thread (plus `reminders_list` and `reminders_cancel`). |
 | [`agent/tools/post_thread_update.ts`](../../examples/oncall/agent/tools/post_thread_update.ts) | Interim updates to the thread mid-turn. |
+| [`agent/storage.ts`](../../examples/oncall/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
+| [`evals/evals.config.ts`](../../examples/oncall/evals/evals.config.ts) | Caps eval run concurrency. |
 | [`evals/smoke.eval.ts`](../../examples/oncall/evals/smoke.eval.ts) | Checks identity and the reminder-tool route. |
 ## Let bot posts through the watch

package/docs/example-agents/slack-agent.md CHANGED Viewed

@@ -49,6 +49,7 @@ or tool routing.
 | [`agent/agent.ts`](../../examples/slack-agent/agent/agent.ts) | Names the agent and selects the model. The omitted `runtime` defaults to local. |
 | [`agent/instructions.md`](../../examples/slack-agent/agent/instructions.md) | Sets the always-on response style. |
 | [`agent/channels/slack.ts`](../../examples/slack-agent/agent/channels/slack.ts) | Connects the signed-in host account to Slack. |
+| [`agent/storage.ts`](../../examples/slack-agent/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
 There are no authored tools, skills, MCP connections, subagents, schedules,
 hooks, A/B experiments, or evals. This small surface is the lesson.

package/docs/example-agents/weather-agent.md CHANGED Viewed

@@ -141,10 +141,15 @@ first prompt; the cloud model writes and invokes the script in its VM.
 ## Verify cloud custom-tool execution
-Ask the agent to run `probe_cloud_tool`. It writes a deployment-scoped marker
-and returns the complete session id, tool-call id, and marker path. Correlate
-those ids with `actions.requested` / `action.result` in the session stream and
-the host's `cloud HTTP MCP tool ... dispatch/complete` log lines.
+Ask the agent to run `probe_cloud_tool`. On cloud that tool is MCP on
+`agentsdk-tools`, not a local script. A real call writes a deployment-scoped
+marker at `tool-observations/<sessionId>/<toolCallId>.json` and returns those
+ids. Correlate them with `actions.requested` / `action.result` for
+`probe_cloud_tool` (not `shell`) and the host's
+`cloud HTTP MCP tool ... dispatch/complete` log lines.
+A local `.agent-serve/tools/probe_cloud_tool.sh` or a marker under `probes/`
+means the model invented a substitute and the host never ran.
 For a body-only smoke test:

package/docs/guides/cloud-runtime.md CHANGED Viewed

@@ -62,17 +62,24 @@ mapping shifts:
 | Folder or file | Local runtime | Cloud runtime |
 | --- | --- | --- |
 | `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
-| Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host |
+| Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
 | Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
 | `skills/*` | `.cursor/skills/` in the workspace | only if present in the cloud repo |
 | `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
 | `sandbox/workspace/**` | seeded into the session workspace | ignored |
-| Tool approvals (`needsApproval`) | supported | supported for server tools |
+| Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
-Hosted deployments configure the server-tool MCP URL automatically. A
+Hosted deployments configure the server-tool MCP URL automatically
+(`cloudToolsUrl`, authenticated with the resolved Cursor API key). A
 self-hosted public server needs `--public-url` (and `--bearer-token` when the
 host is not behind another trusted authentication boundary) so cloud turns
-can reach those tools.
+can reach those tools. Without either, the server warns at startup and
+cloud turns omit the server tools.
+Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
+call rides one HTTP MCP request from the VM, and a parked call would
+hold that request open until it times out; there is no durable approval
+flow for cloud turns.
 Two more behaviors are cloud-specific. Sessions persist a separate SDK
 agent id (`bc-…`), emitted on the stream as `agent.bound` with a URL to