@cursor/bdk 0.2.1

package/docs/reference/instructions.md

@@ -0,0 +1,68 @@
+---
+title: "Instructions"
+description: "The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."
+---
+
+# Instructions
+
+Agent instructions form the always-on system prompt and reach the model
+on every turn. A root agent requires them; a subagent may inline
+`instructions` in `agent.ts` instead.
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+## Authoring forms
+
+| Form | Use it when |
+| --- | --- |
+| `bot/instructions.md` | Plain Markdown for most agents |
+| `bot/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string |
+| `bot/instructions/` directory | A long prompt split across files, composed in filename order |
+
+```ts
+// bot/instructions.ts
+import { defineInstructions } from "@cursor/bdk";
+
+export default defineInstructions({
+  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
+});
+```
+
+## Delivery
+
+Instructions land in the session workspace as `AGENTS.md`, and the
+harness loads them natively. Parent directories can still contribute
+ambient `AGENTS.md` and `.cursor` settings;
+[Agent config: local cwd](./agent-config.md#local-cwd) covers how to
+control that.
+
+## Contents
+
+Keep them a few lines: identity, when to use which tool, and the output
+shape. The [quickstart PR approver](../quickstart.md) is the pattern:
+
+```md
+# PR approver
+
+You review GitHub pull requests. Be specific and brief.
+
+1. Call `inspect_pr` first. Never judge a change you haven't fetched.
+2. Match your review to the complexity it reports.
+3. Never approve a draft.
+
+End with one sentence: the verdict and why.
+```
+
+Name the tools and the decision rule ("use X before answering about
+Y"), not general encouragement. State the output contract, including
+length, format, and fences, so your [evals](../evals.md) can gate it.
+Put multi-step workflows the model only sometimes needs in
+`bot/skills/`; they load on demand and keep the always-on prompt small.
+
+## Related
+
+- [Skills](./skills.md): procedures the model loads only when relevant
+- [Agent config](./agent-config.md): the file next to this one
+- [Hillclimbing](../hillclimbing.md): iterating on instructions with
+  evidence

package/docs/reference/playground.md

@@ -0,0 +1,47 @@
+---
+title: "Playground"
+description: "The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."
+---
+
+# Playground
+
+`bdk serve` enables a web playground at
+`http://127.0.0.1:3000/<slug>/playground` (or `/playground` in single
+mode). In multi-agent mode, each agent has its own playground, and `/`
+lists them all.
+
+The `bdk` commands on this page are docs-ahead until `@cursor/bdk` is
+published; see [BDK package availability](/#bdk-package-availability).
+
+## Playground surfaces
+
+| Surface | What you can do |
+| --- | --- |
+| Chat | Talk to the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state |
+| Slash commands | Custom channel routes without path parameters become composer commands; GitHub and Slack ingress routes are excluded. A `drive` route becomes `/drive <pr-url>`, with `/help` and autocomplete |
+| Try | Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint, copies curl, and opens a session when the route creates one |
+| Runs | Browse the sessions you own and eval runs. Search by title or identifier; open sessions in Chat, Trace, or Raw and eval runs in Evals |
+| Approvals | Parked `needsApproval` tool calls render Approve / Deny buttons |
+| Evals | List and run filesystem evals from the browser |
+| Agent | Inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks |
+| Raw | Inspect the selected session's event stream |
+| Logs | Recent server log lines, polled from `GET /v1/logs` |
+
+In `--dev` on loopback, or with `--allow-anonymous`, the session list
+includes every principal.
+
+## Remote access
+
+The default `localDevStrict()` auth admits direct loopback calls only
+and rejects proxy-forwarding headers, so a tunnel or LAN address won't
+work until you pass `--bearer-token <secret>` (or
+`serve(dir, { authToken })`). Open the playground on the remote device
+and paste the token into the token field in the navbar.
+`--allow-anonymous` is the demo-only alternative for trusted networks.
+
+## Related
+
+- [HTTP API](./http-api.md): the HTTP surface the playground uses
+- [Sessions and streaming](./sessions.md): the streams it renders
+- [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval):
+  the approval buttons in context

package/docs/reference/project-layout.md

@@ -0,0 +1,120 @@
+---
+title: "Project layout"
+description: "The canonical bot/ folder layout and its path-derived naming rules."
+---
+
+# Project layout
+
+The Grok Bot Development Kit (BDK) builds a project by walking the
+filesystem under `bot/`. The path a file lands in determines how BDK
+loads it.
+
+Existing projects rooted at `agent/` remain supported.
+
+## Folder structure
+
+For the capabilities below, identity comes from the path.
+
+| Path under `bot/` | Resolves to |
+| --- | --- |
+| `tools/approve_pr.ts` | tool `approve_pr` |
+| `mcp-connections/linear.ts` | MCP connection `linear` (model + host) |
+| `host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
+| `skills/pr-review.md` | skill `pr-review` |
+| `subagents/reviewer/` | subagent `reviewer` |
+| `extensions/ci.ts` | extension mount `ci`; its contributions become `ci__<name>` |
+| `extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
+| `channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
+
+The root agent takes its name from `package.json` `name`, falling back
+to the directory name. When serving multiple agents, the slug is the
+directory name and must match `[A-Za-z0-9][A-Za-z0-9_-]*` (and not the
+reserved `v1`, `playground`, or `docs` segments).
+
+## Project tree
+
+Most projects start with this shape.
+
+```text
+my-agent/
+├── package.json
+├── bot/
+│   ├── agent.ts               # model and local harness config
+│   ├── instructions.md        # always-on system prompt (required)
+│   ├── tools/
+│   │   └── approve_pr.ts      # one typed tool per file
+│   ├── skills/
+│   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)
+│   ├── mcp-connections/
+│   │   └── linear.ts          # tools from external MCP servers
+│   ├── host-connections/
+│   │   └── anytool.ts         # privileged MCP, host tools only
+│   ├── subagents/
+│   │   └── reviewer/
+│   │       ├── agent.ts
+│   │       └── instructions.md
+│   ├── channels/
+│   │   └── github.ts          # messages and external events
+│   └── hooks/
+│       └── audit.ts           # observe session events
+└── evals/
+    └── readiness.eval.ts      # regression cases
+```
+
+Evals stay in `evals/` at the project root, as a sibling of `bot/`, never
+inside it. See [Evals](../evals.md).
+
+## Folder reference
+
+Each path maps to a capability and a reference page.
+
+| Path under `bot/` | What it is | Reference |
+| --- | --- | --- |
+| `agent.ts` | `defineAgent({ model?, local? })`; the model defaults to `grok-4.5` with `effort=high`, `fast=true` | [Agent config](./agent-config.md) |
+| `instructions.md` | Always-on system prompt, required on the root agent (`.ts` and directory forms exist) | [Instructions](./instructions.md) |
+| `tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (a script that runs where the agent runs) | [Tools](./tools.md) |
+| `skills/*` | SKILL.md-convention procedures, loaded on demand | [Skills](./skills.md) |
+| `mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
+| `host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](./connections.md) |
+| `subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
+| `extensions/<ns>.ts` or `extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](./extensions.md) |
+| `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 |
+
+Evals use project-root paths:
+
+| Project-root path | What it is | Reference |
+| --- | --- | --- |
+| `evals/evals.config.ts` | Shared eval settings (e.g. `maxConcurrency`); required when evals exist | [Evals](../evals.md) |
+| `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](../evals.md) |
+
+Use `bot/lib/` for shared imports. A `.ts` file in one of the listed
+discovery folders loads as a definition; unrecognized directories produce
+a validation warning.
+
+## Inspect discovery
+
+Run `bdk validate --dir .` and `bdk info --dir .`.
+`validate` prints diagnostics, and `serve` refuses to start on
+error-severity ones. Warnings print but don't block. `info` lists the discovered
+surface, so a missing tool or channel shows up immediately. From
+there, check the folder reference: the file is usually in the wrong directory
+or has the wrong extension.
+
+```text
+bdk validate --dir .    # diagnostics; non-zero exit on errors
+bdk info --dir .        # human-readable surface
+bdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)
+```
+
+## Related
+
+- [Agent config](./agent-config.md): the config at the project root
+- [Tools](./tools.md): add typed actions under `tools/`
+- [CLI](./cli.md): commands that discover this tree

package/docs/reference/prompt.md

@@ -0,0 +1,55 @@
+---
+title: "Prompt strings"
+description: "Write indented multi-line strings without carrying source indentation into their values."
+---
+
+# Prompt strings
+
+The `prompt` template tag keeps multi-line strings aligned with the
+surrounding TypeScript while returning dedented text. Use it for tool
+descriptions, reminder prompts, channel context, and errors. Import it
+from the package root or the dedicated entrypoint:
+
+```ts
+import { prompt } from "@cursor/bdk";
+// or: import { prompt } from "@cursor/bdk/prompt";
+```
+
+The `@cursor/bdk` imports on this page are docs-ahead until publication;
+see [BDK package availability](/#bdk-package-availability).
+
+## Dedented strings
+
+`prompt` returns one string. It removes the common leading whitespace
+and one newline immediately after the opening backtick.
+
+```ts
+throw new Error(prompt`
+  It is outside business hours (Mon-Fri 9am-5pm ET).
+  Use request_author_approval, or pass approval=human_request.
+`);
+```
+
+Blank lines inside the body are preserved. Relative indentation after the
+common prefix is preserved, so nested lists keep their shape.
+
+When interpolating multi-line values (for example a list of services), give
+those lines the same indent as the `prompt` body so dedent stays consistent.
+
+## Line arrays
+
+`prompt.lines` applies the same rules and returns `string[]`, with one
+entry per line. Use it when an API accepts separate context lines:
+
+```ts
+context: prompt.lines`
+  Merged PR detected: ${pr.url} by ${author}.
+
+  Call plan_deploy, then follow its nextStep.
+`
+```
+
+## Related
+
+- [Tools](./tools.md)
+- [Channels](./channels.md)

package/docs/reference/schedules.md

@@ -0,0 +1,175 @@
+---
+title: "Schedules & reminders"
+description: "Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."
+---
+
+# Schedules and reminders
+
+An agent can act without an inbound message in two ways. A schedule is
+deploy-time cron: "every weekday at 09:00, summarize open incidents." A
+reminder is a runtime wake bound to one conversation: "re-check this
+PR's CI in two hours." Schedules live in the filesystem; reminders are
+created by running code.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/#bdk-package-availability).
+
+## Schedules
+
+Cron expressions are standard 5-field, evaluated in UTC with minute
+granularity.
+
+### Markdown schedules
+
+A markdown file with `cron:` frontmatter is a fire-and-forget task:
+
+```md
+---
+cron: "0 9 * * 1-5"
+---
+
+Pull open incidents and post a summary to the metrics endpoint.
+```
+
+Each firing starts a task-mode session: the body is the prompt, the
+session runs to `session.completed` or `session.failed`, and it isn't
+followable.
+
+### Schedule handlers
+
+Use `defineSchedule` with a `run` handler to call tools or hand work into
+a channel so its delivery events fire:
+
+```ts
+import { defineSchedule } from "@cursor/bdk/schedules";
+import webhook from "../channels/webhook.js";
+
+export default defineSchedule({
+  cron: "*/30 * * * *",
+  async run({ receive, waitUntil, appAuth, host }) {
+    waitUntil(
+      receive(webhook, {
+        message:
+          "Check for new critical alerts. Report only when there are any.",
+        auth: appAuth,
+      })
+    );
+  },
+});
+```
+
+`defineSchedule` requires exactly one of `markdown` or `run`. The `run`
+handler receives `receive` (hand off into a channel), `callTool`
+(deterministic server-tool calls), `waitUntil`, `appAuth` (a
+schedule-scoped principal for work the agent does on its own behalf),
+and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
+`host.reminders`).
+
+### Dispatch a schedule
+
+| Mode | What fires |
+| --- | --- |
+| Production `bdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
+| `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
+# {"scheduleId":"heartbeat","sessionIds":["ses_…"]}
+```
+
+The playground can dispatch schedules in dev mode too, and
+`handle.dispatchSchedule("heartbeat")` does it programmatically.
+
+## Reminders
+
+A reminder is created at runtime and bound to a channel continuation. A
+prompt reminder wakes that conversation when it fires; a handler reminder
+runs host code, which can call `followup` to wake it. Recurring reminders
+behave like `setInterval`, and one-shots behave like `setTimeout`. Prompt
+and named-handler reminders stay armed across restarts.
+
+```ts
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:acme/checkout#42",
+  delay: "2h",
+  prompt: "Re-check CI. Only act if still failing.",
+  until: "Cancel once CI is green or the PR is merged.",
+});
+```
+
+When host code must decide what happens on each tick, author a named
+handler and pass its default export with serializable `args`:
+
+```ts
+// bot/reminders/ci_recheck.ts
+import { defineReminder } from "@cursor/bdk/reminders";
+
+export default defineReminder({
+  async run({ args, followup }) {
+    await followup({
+      message: `Re-check CI for ${String(args.prUrl)}. Report only if the status changed.`,
+    });
+    return { action: "delivered" };
+  },
+});
+```
+
+```ts
+import ciRecheck from "./bot/reminders/ci_recheck.js";
+
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:acme/checkout#42",
+  every: "30m",
+  handler: ciRecheck,
+  args: { prUrl: "https://github.com/acme/checkout/pull/42" },
+});
+```
+
+Use an anonymous `run` handler only for legacy projects that can re-arm
+it after a restart. New projects should use a named handler.
+
+| Form | What it does | After a restart |
+| --- | --- | --- |
+| Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
+| Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
+| Anonymous `run` | Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
+
+The same API is `host.reminders` on channel handlers, tools, and
+schedule runs. `builtinTools: { reminders: true }` adds
+`reminders_create`, `reminders_list`, and `reminders_cancel` on the
+current conversation; see
+[Agent config: built-in tools](./agent-config.md#built-in-tools).
+
+`--dev` does not auto-fire reminders. Dispatch one by hand:
+
+```bash
+curl http://127.0.0.1:3000/<slug>/v1/dev/reminders             # list
+curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id>  # fire one
+```
+
+`handle.dispatchReminder(id)` is the programmatic equivalent.
+
+Cancel reminders when their subject dies, for example on
+`pull_request.closed`. Keep wake prompts generic so the agent re-reads
+live state instead of replaying a stale payload.
+
+## Schedules vs reminders
+
+|          | Schedule                                                   | Reminder                                        |
+| -------- | ---------------------------------------------------------- | ----------------------------------------------- |
+| Defined  | at deploy time, `bot/schedules/*`                        | at runtime, `createReminder` / `host.reminders` |
+| Scope    | global to the agent                                        | one channel continuation (one conversation)     |
+| Session  | starts a new task session (or hands off through `receive`) | wakes an existing conversation                  |
+| Cadence  | cron (UTC)                                                 | `every`, `cron`, `delay`, or `at`                |
+| Dev mode | manual dispatch only                                       | manual dispatch only (timers off)               |
+
+## Related
+
+- [Channels](./channels.md): `receive` and the delivery events
+- [GitHub guide](../guides/github.md): reminders in a real webhook loop
+- [HTTP API](./http-api.md#dev-mode-routes): the dev
+  dispatch routes

package/docs/reference/sessions.md

@@ -0,0 +1,165 @@
+---
+title: "Sessions, events, and streaming"
+description: "Understand how conversations continue, how events stream, and where session data lives."
+---
+
+# Sessions, events, and streaming
+
+A session keeps one conversation, its workspace, and an append-only
+record of every message and tool call. Continue it with a continuation
+token, inspect it with a session ID, and follow progress on the NDJSON
+stream. Chat sessions wait for follow-ups; task sessions run once and
+stop.
+
+The `bdk` commands on this page are docs-ahead until `@cursor/bdk` is
+published; see [BDK package availability](/#bdk-package-availability).
+
+## Session contents
+
+Each session combines:
+
+- A channel and authenticated caller
+- A conversation the caller can continue
+- A workspace for local turns
+- An NDJSON event stream
+- State that lets the conversation resume after a restart
+
+Sessions belong to the principal that created them. Follow-up, stream,
+and list routes return `403` when another caller tries to access one.
+
+## Session identifiers
+
+Sessions have two identifiers because conversation routing and
+inspection are different jobs.
+
+| Identifier | Use it for |
+| --- | --- |
+| `continuationToken` | Continue a conversation through its channel |
+| `sessionId` | Stream events, inspect state, resolve approvals, or run a session-bound tool call |
+
+Channels decide what a continuation token looks like. Slack uses its
+thread identity. A PR channel can use a key such as `pr:owner/repo#1`.
+The built-in HTTP API returns an opaque token and rotates it after each
+accepted follow-up. Reusing a stale HTTP token returns `409`.
+
+Use the continuation token to keep talking. Use the session ID to
+observe or manage the stored session.
+
+## Session modes
+
+| Mode | Created by | What happens after a turn |
+| --- | --- | --- |
+| `chat` | HTTP sessions, channel `send`, Slack, or MCP `ask` | Waits in `session.waiting` and accepts follow-ups |
+| `task` | Markdown schedules and fire-and-forget dispatch | Ends in `session.completed` or `session.failed` |
+
+Task sessions don't accept follow-ups. Trying one returns `409`.
+
+## Follow-ups
+
+A follow-up to an idle chat session starts another turn. Admission when
+the session is already busy depends on the channel:
+
+| Path | Busy-session policy |
+| --- | --- |
+| HTTP playground / `POST /v1/session/:id` / MCP `ask` | **Preempt** (default): interrupt the in-flight turn, wait for it to settle, then run the new message |
+| Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running and queue the follow-up. The running turn may receive it at a tool boundary; any asks that remain become one follow-up turn when it finishes |
+
+Pass `admission: "coalesce"` on `send()` to opt into the Slack policy from
+other callers. Omit it (or pass `"preempt"`) to keep interrupt semantics.
+
+`POST /v1/session/:id/stop` interrupts a turn without sending a new
+message. The stream records `turn.failed` with `status: "cancelled"`;
+the session stays a chat session and can take another follow-up. A
+whole-message Slack `stop` / `@agent stop` does the same for that thread
+and clears pending coalesced follow-ups.
+
+See [Tools](./tools.md#call-a-tool-without-a-model-turn) for direct-call
+behavior while a session is busy.
+
+## Stream events
+
+Each NDJSON line uses this envelope:
+`{ type, index, sessionId, turnId?, at, data }`. The `index` increases
+within one session. The `at` field is an ISO-8601 timestamp.
+
+| Phase | Events | What they tell you |
+| --- | --- | --- |
+| Session | `session.started`, `session.waiting`, `session.completed`, `session.failed` | Session creation, readiness, and task completion |
+| 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 |
+| Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
+| Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
+| Tools | `actions.requested`, `action.result` | Tool names, validated arguments, outputs, and errors |
+| Approvals | `action.approval_requested`, `action.approval_resolved` | A parked tool call and the human decision |
+| Subagents | `subagent.called`, `subagent.completed` | Delegated work |
+| Artifacts | `artifact.tagged` | A durable [artifact](./artifacts.md) was tagged for this session, by host code or `tag_artifact` |
+
+Pair `actions.requested` with `action.result` to reconstruct the tool
+trajectory. 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.
+
+## Stream or replay events
+
+One endpoint handles both live streaming and replay:
+
+```bash
+curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
+```
+
+Pass `startIndex` to continue after the last event you received,
+including after a server restart. Omit it or pass `0` to replay the
+full session before following new events.
+`GET /v1/session/:id/events` returns a one-time dump without staying
+connected.
+
+## Local session workspace
+
+BDK creates a workspace before the first local turn:
+
+| Source path                        | Lands as                                                                |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `skills/*`                         | `.cursor/skills/<name>/SKILL.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                                                 |
+
+Instructions reach the model as its system prompt; they aren't written
+into the workspace. See [Instructions](./instructions.md#delivery).
+
+Local turns use this workspace as their working directory. Parent
+directories can contribute `AGENTS.md` and `.cursor` settings. Set
+`local.cwd` when you need a clean parent directory. A channel can also
+provide a different working directory for one session, such as a PR
+worktree.
+
+See [Agent config: local cwd](./agent-config.md#local-cwd) for the
+inheritance rules.
+
+## Session storage
+
+Local session state lives under `--state-root`. A slugged mount stores
+it in 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.
+
+## Inspect a saved event stream
+
+Use `trajectory` with a saved trace:
+
+```text
+bdk trajectory --events <state-root>/traces/<sessionId>.ndjson
+```
+
+The command prints tool calls, the reply, and token usage in the same
+JSON shape as `run`. Open the session's **Trace** view in the playground
+for a visual timeline.
+
+## Related
+
+- [HTTP API](./http-api.md)
+- [Hooks](./hooks.md)
+- [Tools](./tools.md)