@cursor/bdk 0.2.18 → 0.2.21

package/docs/guides/export-grokbot.md

@@ -0,0 +1,244 @@
+---
+title: "Export a Grok Bot"
+description: "Turn a Grok Bot recipe into a BDK project, preview what maps, and finish secrets and connector sign-ins."
+---
+
+# Export a Grok Bot to a BDK project
+
+`bdk init --from-grokbot` turns a Grok Bot recipe into a project you can
+review, run locally, and keep in source control. It carries over the bot's
+profile, selected skills and routines, memory, and connectors where BDK has a
+matching project surface.
+
+## Preview the export
+
+Start with `--dry-run`. The command resolves the same defaults as a real
+export and shows every planned file, warning, secret name, and follow-up
+without creating the target directory or installing packages.
+
+```bash
+bdk init ./launch-desk \
+  --from-grokbot ./launch-desk.recipe.json \
+  --dry-run
+```
+
+Selected lines from the example recipe's non-interactive preview look like
+this:
+
+```text
+Dry run: "Launch Desk" → ./launch-desk (nothing written)
+
+  bot/agent.ts                                   profile
+  bot/channels/slack.ts                          routines/launch-questions, routines/blocker-watch, routines/ship-it
+  bot/instructions.md                            profile, gettingStarted, routines/launch-questions, routines/blocker-watch, routines/ship-it, memory
+  bot/mcp-connections/linear.ts                  plugins/linear
+  bot/schedules/morning-launch-brief.md          routines/morning-launch-brief
+  bot/skills/release-checklist/SKILL.md          skills/release-checklist
+  SECRETS.md                                     answers
+  ...
+
+Defaulted without asking:
+  - name
+  - description
+  - model
+  ...
+
+Not carried over:
+  - profile.avatar: BDK agents have no avatar; kept in grokbot-export.json for the Slack app icon.
+
+Secrets to set (names only; see SECRETS.md):
+  - LAUNCH_DESK_SLACK_APP_TOKEN
+  - LAUNCH_DESK_SLACK_BOT_TOKEN
+```
+
+Each file row names the recipe parts that produced it. The remaining sections
+list defaults, answers the recipe ignored, excluded items, unmapped behavior,
+routine placeholders, fresh connector sign-ins, warnings, and setup steps.
+
+Add `--json` when a script needs the preview:
+
+```bash
+bdk init ./launch-desk \
+  --from-grokbot ./launch-desk.recipe.json \
+  --dry-run \
+  --json
+```
+
+The core JSON shape is:
+
+```json
+{
+  "ok": true,
+  "dryRun": true,
+  "directory": "/work/launch-desk",
+  "preview": {
+    "files": [],
+    "defaulted": [],
+    "ignored": [],
+    "excluded": [],
+    "unmapped": [],
+    "fillIns": [],
+    "secrets": { "names": [], "reauth": [] },
+    "warnings": [],
+    "setupSteps": []
+  }
+}
+```
+
+See [`bdk init`](../reference/cli.md#init) for the complete preview fields and
+flag behavior.
+
+## Choose an answers file or the terminal interview
+
+Run the command in a terminal when you want to review each choice once. Press
+Enter to accept a default.
+
+```bash
+bdk init ./launch-desk \
+  --from-grokbot ./launch-desk.recipe.json
+```
+
+Use `--answers` for a repeatable export or a non-interactive environment. This
+minimal file validates against the published schema and accepts every recipe
+default:
+
+```json
+{
+  "$schema": "./node_modules/@cursor/bdk/schemas/grokbot-answers.schema.json",
+  "version": 1
+}
+```
+
+Save it as `grokbot-answers.json`, then run:
+
+```bash
+bdk init ./launch-desk \
+  --from-grokbot ./launch-desk.recipe.json \
+  --answers ./grokbot-answers.json
+```
+
+The `$schema` property is an optional editor hint. Add only the choices you
+want to override; any answer present in the file is not asked again. A
+positional directory such as `./launch-desk` overrides `location` in the
+answers file.
+
+When stdin or stdout is not a TTY, the command never prompts. `--json` also
+uses this non-interactive path. Missing fields take their defaults and appear
+under **Defaulted without asking** or `preview.defaulted`. If a required
+conditional answer has no default, such as the time for a scheduled decision,
+the command stops and names the field to add to the answers file.
+
+## Write and check the project
+
+Remove `--dry-run` after the preview matches your intent. The command writes
+the project, installs its npm dependencies, and prints the next commands.
+Export into a fresh directory; a project previously created with
+`bdk init --template` is rejected.
+
+```bash
+bdk init ./launch-desk \
+  --from-grokbot ./launch-desk.recipe.json \
+  --answers ./grokbot-answers.json
+
+cd ./launch-desk
+bdk validate
+bdk dev
+```
+
+Open the playground from `bdk dev` and try the routines you plan to keep
+before connecting live channels.
+
+## Review what maps where
+
+| Grok Bot recipe part | BDK project result |
+| --- | --- |
+| Profile or persona | The name and description become `bot/agent.ts` and the opening of `bot/instructions.md`. |
+| Skills | Each selected skill becomes `bot/skills/<slug>/SKILL.md`. An enabled, valid skill schedule also becomes `bot/schedules/<slug>.md` when the schedule channel is on. |
+| Getting-started skill | `bot/instructions.md` tells the agent to use this skill for a new conversation. |
+| Cron routines | A selected routine with a valid, enabled cron trigger becomes `bot/schedules/<slug>.md` when the schedule channel is on. |
+| Slack routines | When the Slack channel is on, the routine text becomes a section in `bot/instructions.md`; mentions, channel watches, keywords, and reactions are wired in `bot/channels/slack.ts`. Missing trigger values remain as warnings or TODOs. |
+| GitHub or webhook routines | When the corresponding channel is on, the preview adds a setup step to wire the trigger. A routine with no other wired trigger also becomes an on-request skill. |
+| Other routines | A routine without a wired trigger becomes an on-request skill. The preview explains which trigger still needs work. |
+| Memory | The default is `bot/skills/knowledge/SKILL.md`. Choose `memory: "kv"` for `bot/lib/memory-seed.json`, or `memory: "drop"` to leave it out. |
+| Plugins and connectors | Each selected plugin becomes `bot/mcp-connections/<slug>.ts` using Cursor-account auth, OAuth, or a named bearer-token secret. |
+| Routine placeholders | Values under `fillIns.<routine-slug>` replace placeholders such as `{slack_channel}`. Unfilled placeholders remain visible and produce warnings. |
+| Export decisions | Resolved answers and recipe metadata are recorded in `grokbot-export.json`. |
+
+The generated project also includes the standard package, TypeScript, eval,
+memory-hook, and ignore files needed to run it.
+
+## Resolve what does not map
+
+The preview separates choices you made from behavior the converter could not
+carry over:
+
+| Preview result | What it means | What to do |
+| --- | --- | --- |
+| **Left out** | An answer excluded a skill, routine, plugin, or memory. | Change the matching `include` or `exclude` answer, or change `memory` from `"drop"`, then rerun; otherwise leave the item behind. |
+| `BDK agents have no avatar` | The profile avatar is not an agent setting. Its metadata remains in `grokbot-export.json`. | Set an icon separately if the destination needs one. |
+| `Unknown recipe field; ignored.` | The recipe contains a field this BDK version does not map. | Inspect the field and add its behavior to the generated project when needed. |
+| `Paused schedule ...` | A paused cron trigger does not produce a schedule file. | Leave it paused, or add a schedule under `bot/schedules/`. |
+| `trigger dropped: the ... channel is off.` | The answers disabled the channel used by a trigger. | Enable the channel in the answers or add the trigger manually after export. |
+| `trigger has no BDK channel.` | The trigger type has no direct BDK channel mapping. | Add a supported channel or custom wake; use the generated on-request skill when one is present. |
+| `is not a five-field cron expression.` | The source cron cannot become a BDK schedule. | Correct the expression and add the schedule before enabling it. |
+| `placeholders ... are unfilled` | A routine still contains values such as `{slack_channel}`. | Set `fillIns.<routine-slug>` in the answers or edit the generated text. |
+| `BDK has no built-in KV seed` | `memory: "kv"` writes data but does not load it into hosted KV. | Add your own `ctx.host.kv` seeding code, or use `memory: "skill"`. |
+
+Treat setup steps and warnings as the checklist for restoring the source
+behavior. A generated project is ready for review, not automatically ready for
+live traffic.
+
+## Set secrets and reconnect OAuth
+
+The export carries secret names only, never values. `SECRETS.md` lists each
+name, where it is read, and every connector that needs a fresh sign-in.
+
+Set local values in the environment where you run `bdk dev`. For a hosted
+deployment, let `bdk` prompt for each value:
+
+```bash
+bdk secrets set launch-desk LINEAR_API_KEY
+```
+
+OAuth tokens do not move with the recipe. Sign in to each OAuth connector
+again:
+
+```bash
+bdk mcp oauth notion
+```
+
+Add `--store` when the sign-in is for a hosted deployment.
+
+## Check cron schedules in UTC
+
+BDK evaluates cron schedules in UTC. A recipe routine that asks for a
+timezone produces a warning like:
+
+```text
+routines/morning-launch-brief: BDK runs `0 8 * * 1-5` in UTC, not America/Los_Angeles; adjust the cron in bot/schedules/morning-launch-brief.md if the time matters.
+```
+
+The timezone answer documents the source intent; it does not rewrite the cron.
+Check each generated file under `bot/schedules/` and translate local
+wall-clock times to UTC. For locations that observe daylight saving time,
+also decide how you will handle the offset change.
+
+## Use the handoff files
+
+| File | Purpose |
+| --- | --- |
+| `AGENTS.md` | Gives a coding agent the project commands and points it to the export handoff. |
+| `SECRETS.md` | Lists secret names and connector sign-ins, without values. |
+| `SLACK.md` | When Slack is selected, holds the Slack app setup notes. |
+| `.cursor/skills/finish-grokbot-export/SKILL.md` | Guides a coding agent through the remaining setup, warnings, validation, and local test. |
+| `.cursor/environment.json` | Tells a Cursor cloud agent to install the project with `npm install`. |
+
+Server-side secret transfer, automatic moves of existing Slack apps, and
+self-deploy are not shipped, so this guide does not cover those flows.
+
+## Related
+
+- [`bdk init`](../reference/cli.md#init): flags, JSON output, and failures
+- [Project layout](../reference/project-layout.md): generated project files
+- [Schedules and reminders](../reference/schedules.md): cron behavior
+- [MCP connections](../reference/connections.md): connector auth choices

package/docs/guides/hooks.md

@@ -98,9 +98,11 @@ replay recorded events into hooks.
 | --- | --- |
 | Add context before the model | `instructions.md`, skills, or `workspaceFiles` |
 | Deliver to Slack or a PR | Channel [`events`](../reference/channels.md#events) or packs |
-| Gate final assistant text | `defineResult` |
 | Gate behavior | [Evals](../evals.md) |
 
+To act on a turn's decision, have the model record it with an authored
+[tool](../reference/tools.md), then act on it from a `turn.completed` hook.
+
 [Cursor Agent hooks](https://cursor.com/docs/agent/hooks) in
 `.cursor/hooks.json` are a different product. They can observe, block, or
 modify the local agent loop.

package/docs/guides/opentelemetry.md

@@ -51,7 +51,9 @@ await serve(".", {
 
 Use environment variables when you start the agent with
 `bdk serve`. Use `serve({ otel })` when your TypeScript
-application starts the server itself.
+application starts the server itself. When that application
+already uses OpenTelemetry, BDK sends its traces, metrics, and
+logs to the collector configured here.
 
 ## Follow one conversation
 
@@ -74,6 +76,35 @@ turn: agent_sdk.turn
 A conversation can produce several turn traces, so use the session ID
 as the join key instead of expecting one long-lived session span.
 
+### Subagents
+
+A subagent's tool calls are `agent_sdk.tool` spans under its
+`agent_sdk.subagent` span. Its `reasoning.completed` and
+`message.completed` events sit on that span too, so the subagent span
+shows where its time went. Time between two tool spans is the model
+choosing the next step. A subagent that fails or is cancelled ends its
+span with ERROR status when it stops.
+
+### Computer use
+
+Each computer use action is an `agent_sdk.tool` span with
+`cursor.tool.name` set to `computerUse`, under the computer use
+subagent's span. A failed action has ERROR status. These attributes
+describe the action without typed text, coordinates, or screenshots:
+
+| Attribute | Value |
+| --- | --- |
+| `agent_sdk.computer.actions` | The action type, such as `click`, `type`, or `screenshot` |
+| `agent_sdk.computer.executor_duration_ms` | Time the desktop took to run the action and capture the screen |
+| `agent_sdk.computer.settle_ms` | Part of that time spent waiting for the screen to settle |
+
+The two durations appear only on actions that succeed.
+
+To export the full actions, turn on tool content as shown in
+[Control what leaves the process](#control-what-leaves-the-process).
+Tool content includes the text the agent typed, which can contain
+passwords.
+
 ## Add domain telemetry
 
 Use `ctx.host.otel` when your dashboard should answer questions the
@@ -124,10 +155,11 @@ The first metrics to look for are `cursor.token.usage`,
 
 ## Control what leaves the process
 
-User prompts, tool arguments, tool results, and failure text stay off
-the wire by default. You still get trace structure, tool names and
-status, usage metrics, and generic failure status without exporting the
-underlying content.
+Traces include structure, tool names, usage metrics, and span
+status. A failed tool's status includes a short failure reason.
+A tool or subagent that is still open when the turn ends gets
+ERROR status with the reason `no result`. User prompts, tool
+arguments, and full tool results stay off the wire until you opt in.
 
 Turn on logs first, then opt into prompt or tool content separately:
 

package/docs/reference/cli.md

@@ -136,6 +136,7 @@ bdk serve [--dir <path>] [--port <n>] [--host <host>]
   [--allow-anonymous-cursor-account-mcp]
   [--allow-anonymous-grokbot]
   [--public-url <url>]
+  [--peers-url <url>]
   [--no-schedules] [--no-playground] [--no-docs]
   [--cursor-events --repo <owner/name>]...
 ```
@@ -145,7 +146,7 @@ bdk serve [--dir <path>] [--port <n>] [--host <host>]
 | `--port <n>` | Listen on this port. The default is `3000`; `0` selects an available port. When an omitted default is occupied, the CLI selects the next port. An occupied explicit port fails with a next-port hint. |
 | `--host <host>` | Bind this host. The default is loopback-only `127.0.0.1`. |
 | `--mode multi` | Mount projects at `/<slug>/v1/*` and `/<slug>/playground`, with an index at `/`. This is the default. |
-| `--mode single` | Mount one project at `/v1/*` and `/playground`. |
+| `--mode single` | Mount one project at `/v1/*` and `/playground`. Declared peers are omitted with a warning unless `--peers-url` is set. |
 | `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and enable local playground access. |
 | `--state-root <path>` | Store local sessions, streams, workspaces, and channel state here. Keep durable state outside a repository whose rules shouldn't reach agent workspaces. |
 | `--bearer-token <secret>` | Require this token on routes without authored authentication. Mutually exclusive with `--allow-anonymous`. |
@@ -154,6 +155,7 @@ bdk serve [--dir <path>] [--port <n>] [--host <host>]
 | `--allow-anonymous-cursor-account-mcp` | Let anonymous callers use Cursor account MCP connections. Requires an authenticating proxy. |
 | `--allow-anonymous-grokbot` | Let anonymous callers drive hosted Grok Bot runtime agents. Requires an authenticating proxy. |
 | `--public-url <url>` | Set the externally reachable base URL that turns running off the serve host use for peer MCP and host bridges. It does not expose the server; configure the listener or proxy separately. Local-runtime peers use loopback. |
+| `--peers-url <url>` | Resolve declared peers for a single-agent serve through a hosting-provided peer service. Cursor-managed hosting sets this option automatically; a multi-agent serve rejects it. |
 | `--no-schedules` | Disable schedule firing outside dev mode. |
 | `--no-playground` | Skip the playground. |
 | `--no-docs` | Skip the documentation site at `/docs`. |
@@ -447,6 +449,8 @@ requires an ID. The `status` and `cancel` subcommands require `--url`.
 
 ```text
 bdk init [directory] [--template <name>] [--var id=value]... [--json]
+bdk init [directory] --from-grokbot <recipe.json>
+  [--answers <file>] [--dry-run] [--json]
 ```
 
 Without a directory, `init` prints the setup guide and changes no files. With
@@ -463,6 +467,40 @@ On a TTY, templates with questions run their interview before writing files.
 `init` also offers to refresh the bundled coding-agent skills and starts login
 when the host has no Cursor credential.
 
+#### Export a Grok Bot recipe
+
+`--from-grokbot` reads a Grok Bot recipe and maps its profile, selected skills
+and routines, memory, channels, and connectors into a BDK project. The target
+directory defaults to the resolved `location` answer; a positional directory
+overrides it. A target previously created with `bdk init --template` is
+rejected; export into a fresh directory instead.
+
+| Option | Contract |
+| --- | --- |
+| `--from-grokbot <recipe.json>` | Read the recipe to export. |
+| `--answers <file>` | Read export decisions from a JSON object. Fields present in the file are not asked again. The published schema is `schemas/grokbot-answers.schema.json`. |
+| `--dry-run` | Print the planned files, defaults, exclusions, unmapped behavior, placeholders, secret names, warnings, and setup steps without writing files or installing dependencies. |
+| `--json` | Never prompt and print machine-readable output. Combine it with `--dry-run` for a machine-readable preview. |
+
+On a TTY, the command asks for missing decisions and offers recipe-derived
+defaults. Off a TTY, it never prompts, takes defaults where possible, and
+lists the fields it defaulted.
+
+`--dry-run --json` prints `{ ok, dryRun, directory, preview }`. The preview
+contains `version`, `name`, resolved `answers`, `defaulted`, `ignored`, `files`
+as `{ path, from }`, `excluded`, `unmapped` as `{ from, reason }`, `fillIns`,
+`secrets` as `{ names, reauth }`, `warnings`, and `setupSteps`. A write with
+`--json` also reports `files`, `installed`, and `installError`. A dependency
+install failure leaves `ok: true`, sets `installed: false`, reports
+`installError`, and exits `0`. Other errors print `{ ok: false, error }` and
+exit nonzero.
+
+`--answers` and `--dry-run` require `--from-grokbot`. This export mode does
+not accept `--template` or `--var`.
+
+See [Export a Grok Bot](../guides/export-grokbot.md) for the preview-first
+workflow, mapping table, and post-export checklist.
+
 ### Convert an Automation {#convert-automation}
 
 ```text

package/docs/reference/connections.md

@@ -9,8 +9,8 @@ An MCP connection gives the agent tools from an MCP server. Define one
 file per server under `bot/mcp-connections/`; the filename becomes the
 server name. Default-export `defineConnection` from
 `@cursor/bdk/connections`. The transport is remote HTTP, local stdio,
-the signed-in Cursor account's connectors, or a peer agent on the same
-host.
+the signed-in Cursor account's connectors, or a peer agent addressed by
+slug.
 
 Put a server in `bot/host-connections/` when only host tools should
 call it. Host connections use the same `defineConnection` shape and
@@ -254,9 +254,14 @@ Use a `{ command }` connection for stdio servers.
 
 ## Peer MCP connection {#peer-mcp-connection}
 
-`{ agent: "<slug>" }` addresses another agent mounted on the same serve
-host. The model gets the peer's `ask` and `check` tools, plus
-`call_tool` when the peer has server tools, and can delegate work to it:
+`{ agent: "<slug>" }` addresses another agent without configuring a URL,
+headers, or secrets. On a local multi-agent serve, the target is another
+mount slug. On Cursor-managed hosting, it is the lowercase deployment slug
+of another agent on the same team.
+
+On a local multi-agent serve, the model gets the peer's `ask` and `check`
+tools, plus `call_tool` when the peer has server tools, and can delegate work
+to it:
 
 ```ts
 export default defineConnection({
@@ -265,7 +270,12 @@ export default defineConnection({
 });
 ```
 
-Unknown slugs and self-references fail `serve` at startup. Walkthrough:
+Declare the connection only on the caller. The specialist needs no matching
+configuration.
+
+In a local multi-agent serve, unknown slugs and self-references fail at
+startup. A single-agent serve omits peers with a warning unless its hosting
+platform sets `--peers-url`. Walkthrough:
 [Peer agents](../guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
 ## Call MCP from host code

package/docs/reference/hooks.md

@@ -58,7 +58,8 @@ reports all three. An extension mounts its hooks as `<ns>__<name>`, and
 
 `bdk init` scaffolds `bot/hooks/memory.ts`, which exports
 `memoryHook()` from `@cursor/bdk/memory` and journals every turn for
-later sessions to read. Delete the file to opt out.
+later sessions to read. Delete the file to opt out. See
+[Memory](./memory.md).
 
 ## Events and payloads
 
@@ -164,9 +165,12 @@ All three consume the same stream, for different jobs:
 | Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
 | Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
 | Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see [GitHub agents](../guides/github.md)                 |
-| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
 | Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
 
+To act on a turn's decision, such as a label or a ticket, have the model
+record it with an authored [tool](./tools.md). A `turn.completed` hook then
+reads the recorded decision and acts on it through `ctx.host`.
+
 ## Test a hook
 
 A hook definition is a plain object, so a unit test calls

package/docs/reference/memory.md

@@ -0,0 +1,119 @@
+---
+title: "Memory"
+description: "Journal every turn so later sessions can read what earlier ones did."
+---
+
+# Memory
+
+Memory lets an agent recall work from earlier sessions. A memory hook
+appends one record per turn to a shared journal, and the model reads
+that journal with its normal file tools when its instructions send it
+there. Every session and every user of the agent shares one journal.
+
+## Memory is on by default
+
+`bdk init` scaffolds `bot/hooks/memory.ts`:
+
+```ts
+// bot/hooks/memory.ts
+import { memoryHook } from "@cursor/bdk/memory";
+
+export default memoryHook();
+```
+
+It also adds a `## Memory` section to `bot/instructions.md`. The model
+has no recall tool, so that section is what sends it to the journal:
+it says when to read `memory/`, and it tells the model to treat records
+as untrusted history. To add memory to an existing project, create the
+hook file and copy the `## Memory` section from a fresh `bdk init`
+project into your instructions. To turn memory off, delete the hook
+file and the `## Memory` section.
+
+## Journal records
+
+The hook appends one JSON line to `memory/journal.jsonl` after each
+turn completes or fails:
+
+```json
+{"at":"2026-10-01T16:42:09.118Z","sessionId":"5f0c2a9e-7d1b-4c43-9a6e-2b8f1e0d7c35","channelId":"slack","status":"completed","title":"Checkout flaky test","userMessage":"Why does acme/checkout fail on main?","result":"The cart test races the price service mock...","usage":{"inputTokens":18234,"outputTokens":912,"cacheReadTokens":15002,"cacheWriteTokens":0}}
+```
+
+| Field | Contract |
+| --- | --- |
+| `at` | ISO-8601 time the turn finished |
+| `sessionId` | Session that ran the turn |
+| `channelId` | Channel that started the session, such as `http` for the session API |
+| `status` | `"completed"` or `"failed"` |
+| `title` | Session title, when the channel set one |
+| `userMessage` | The message that started the turn, truncated to `maxTextLength` |
+| `result` | Final assistant text, or the failure message, truncated to `maxTextLength` |
+| `usage` | Token usage for completed turns; see [Events and payloads](./hooks.md#events-and-payloads) |
+
+As the journal grows, older records move to `journal-*.jsonl` files
+beside it. Point the model at the whole `memory/` directory when it
+needs history beyond the latest segment.
+
+## Read memory
+
+Local turns find the journal at `memory/` in the session workspace. On
+a Cursor-hosted deployment, the first prompt of each session names the
+journal's path on that machine. A session on a server you run yourself
+can't reach the journal.
+
+`memory` is a reserved workspace path. BDK rejects per-send
+`workspaceFiles` and `sandbox/workspace/` seed files under `memory/`,
+so callers can't write records through the workspace.
+
+Local servers keep the journal in the project state directory. `bdk
+run` and `bdk eval` start an ephemeral server with a fresh state
+directory unless you pass `--state-root`, so each run starts with
+empty memory. Use `bdk serve` or `bdk dev`, or pass the same
+`--state-root`, to keep memory across runs. Hosted deployments keep
+the journal across redeploys.
+
+## Who sees memory
+
+Records from every session and every user land in the same journal, so
+one person's messages and the agent's replies to them can surface in
+another person's session. Turn memory off for an agent whose users
+shouldn't see each other's requests. Turning it off stops new records,
+but the journal keeps the records it already has. On a local server,
+delete the `memory/` directory in the project state directory to clear
+them. On Cursor-managed hosting, the journal is deployment data, so
+[Privacy Mode](../deployment.md#privacy-mode) applies to it.
+
+Anyone who can message the agent can put text in the journal. The
+scaffolded instructions tell the model never to follow instructions
+found inside records; keep that rule if you write your own section.
+
+## Memory and host state
+
+Memory is advisory. A record can be dropped, and records written by
+concurrent sessions can show up only in a later session. Keep state
+your code depends on, such as dedupe records and cursors, in
+`ctx.host.kv` or `ctx.host.files`; see
+[Handler context](./hooks.md#handler-context).
+
+## Options
+
+`memoryHook(options?)` accepts:
+
+| Option | Contract |
+| --- | --- |
+| `maxTextLength` | Truncation cap for `userMessage` and `result`. Default `2000` characters. |
+| `backend` | A `MemoryBackend` that replaces the default journal |
+
+A `MemoryBackend` has `appendTurn(record, { stateRoot, agentName })`,
+which receives each record, and an optional
+`prepareSession({ stateRoot, agentName })`, which runs when a session
+starts. Records go only where `appendTurn` sends them, but the
+`memory/` directory and the hosted first-prompt path still point at the
+default journal. Give the model a tool or file to read your records,
+and write instructions that send it there instead of `memory/`.
+
+## Related
+
+- [Hooks](./hooks.md)
+- [Instructions](./instructions.md)
+- [Sessions](./sessions.md)
+- [Deployment](../deployment.md)

package/docs/reference/project-layout.md

@@ -80,12 +80,15 @@ Each path maps to a capability and a reference page.
 | `channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
 | `artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
-| `result.ts` | `defineResult` host `commit` on the final assistant text (`throw` or `ctx.reject`) | None |
 | `schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
 | `reminders/*.ts` | Named reminder handlers that stay armed across restarts | [Schedules](./schedules.md#reminders) |
 | `sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#local-session-workspace) |
 | `lib/` | Import-only shared code, never discovered | None |
 
+Discovery rejects a `bot/result.ts` file. To act on a turn's decision, have
+the model record it with an authored [tool](./tools.md), then act on it from a
+`turn.completed` [hook](./hooks.md).
+
 Evals use project-root paths:
 
 | Project-root path | What it is | Reference |

package/docs/reference/sessions.md

@@ -94,9 +94,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 Pair `actions.requested` with `actions.completed` for each model-step
 batch. `action.result` is the live per-call envelope. Read
 `turn.completed.data.usage` for input, output, and
-cache token counts. With `bot/result.ts`, `turn.failed` is emitted when
-`commit` throws, the turn has no assistant text, or `ctx.reject(message)`
-doesn't lead to an accepted revision.
+cache token counts.
 
 ## Stream or replay events
 

package/docs/reference/subagents.md

@@ -10,6 +10,8 @@ mid-turn. Each one lives under `bot/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`.
+`subagent.completed` has `isError: true` when the subagent failed or was
+cancelled.
 
 ```text
 bot/subagents/researcher/

package/docs/troubleshooting.md

@@ -69,7 +69,7 @@ Match the visible symptom below.
 | `run --prod --session <sessionId>` reports the session belongs to another channel | `--session` continues only sessions that `run --prod` or `session --prod` started. Reach Slack, SCM, and custom-route sessions through their own channel. |
 | A custom route returns `202` with no body | Expected on managed hosting. The handler runs after the response, so deliver results from the channel. See [Route responses](./reference/channels.md#route-responses). |
 | External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `bdk rotate-token <slug>` and replace it everywhere. |
-| `deploy` says deployments are not available under legacy privacy mode | The team uses Privacy Mode (Legacy), which does not let Cursor store code. Managed hosting is not available with this setting. |
+| `deploy`, a hosted session, or an eval run says it is not available with Privacy Mode (Legacy) | Switch to Privacy Mode, or ask a team admin if your team enforces this setting. A refused session does not store the message. See [Privacy Mode](./deployment.md#privacy-mode). |
 | `deploy` says persistent deployments are limited to 1 per team | Another deployment of the team already sets `persistent: true`. Remove the setting from one agent, or delete that deployment. |
 | A schedule does not fire on the hosted deployment | Make sure the deployment is running and its release has the schedule. Deploy again with `@cursor/bdk` 0.2.14 or newer. |
 | A request to a custom route gets `429` | The deployment received more requests than its limit. Wait for the time in `Retry-After`, then send the request again. |