@cursor/bdk 0.2.18 → 0.2.20

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/opentelemetry.md

@@ -74,6 +74,25 @@ 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.
 
+### Computer use
+
+Each computer use batch is an `agent_sdk.tool` span with
+`cursor.tool.name` set to `computerUse`. Batches that the computer use
+subagent runs sit under its `agent_sdk.subagent` span. Four attributes
+describe each batch without typed text, coordinates, or screenshots:
+
+| Attribute | Value |
+| --- | --- |
+| `agent_sdk.computer.actions` | Action types in order, such as `click,type,screenshot` |
+| `agent_sdk.computer.action_count` | Number of actions the agent requested |
+| `agent_sdk.computer.completed_action_count` | Number of actions that ran |
+| `agent_sdk.computer.executor_duration_ms` | Time the executor spent on the batch |
+
+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

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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -35,6 +35,7 @@
     "!templates/pr-autofixer/README.md",
     "docs/**/*.md",
     "!docs/.cursor/**",
+    "!docs/design/**",
     "!docs/templates/pr-autofixer.md",
     "scripts/install-cursor-skills.mjs",
     "package.json",
@@ -299,7 +300,7 @@
   },
   "dependencies": {
     "@bazel/runfiles": "6.5.0",
-    "@cursor/sdk": "1.0.35",
+    "@cursor/sdk": "1.0.36",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",
@@ -363,9 +364,9 @@
     "vitest": "^4.0.18",
     "yaml": "^2.4.2",
     "zustand": "^5.0.9",
-    "@anysphere/agent-exec": "1.0.0",
     "@anysphere/agent-store-sync": "1.0.0",
     "@anysphere/context": "1.0.0",
+    "@anysphere/agent-exec": "1.0.0",
     "@anysphere/proto": "1.0.0",
     "@anysphere/ui": "1.0.0"
   },

package/templates/agentic-owners/bot/lib/owners/matching.ts

@@ -3,11 +3,43 @@
 
 import { minimatch } from "minimatch";
 
+export type PatternMatchOptions = {
+  /**
+   * When true, a `dir/` pattern whose directory is a glob claims the files
+   * under every directory the glob matches, as gitignore does. A directory
+   * that starts with `!` stays literal either way.
+   */
+  readonly globDirectoryPatterns?: boolean;
+};
+
+export const AO_GLOB_DIRECTORY_PATTERNS_ENV = "AO_GLOB_DIRECTORY_PATTERNS";
+
 /**
- * CODEOWNERS-style path matching. Complex prefixes before a terminal `/**`
+ * The glob-directory switch from `AO_GLOB_DIRECTORY_PATTERNS`: `1`, `true` or
+ * `yes` turns it on, and anything else, unset included, leaves it off. Turn it
+ * on only after the Origin shadow counter
+ * `origin.agentic_owners.glob_dir_shadow_mismatch` has run and its owner has
+ * reviewed the repos, files and patterns it reports.
+ */
+export function globDirectoryPatternsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): PatternMatchOptions {
+  const value = env[AO_GLOB_DIRECTORY_PATTERNS_ENV]?.trim().toLowerCase();
+  return { globDirectoryPatterns: value === "1" || value === "true" || value === "yes" };
+}
+
+/**
+ * CODEOWNERS-style path matching. While the glob-directory switch is off, a
+ * `dir/` pattern is read literally, a glob included: `src/d?cs/` claims only
+ * files under a directory named `src/d?cs`. With it on, the glob matches
+ * directories as in gitignore. Complex prefixes before a terminal `/**`
  * deliberately fall through to minimatch below.
  */
-export function patternMatchesFile(pattern: string, filepath: string): boolean {
+export function patternMatchesFile(
+  pattern: string,
+  filepath: string,
+  options: PatternMatchOptions = globDirectoryPatternsFromEnv(),
+): boolean {
   const patternIsRooted = pattern.startsWith("/");
   const normalizedPattern = pattern.replace(/^\/+/, "");
   const normalizedPath = filepath.replace(/^\/+/, "");
@@ -32,6 +64,16 @@ export function patternMatchesFile(pattern: string, filepath: string): boolean {
     return globMatches(normalizedPath, `${literalPrefix}*`);
   }
 
+  const globDirectory =
+    options.globDirectoryPatterns === true ? globDirectoryOf(normalizedPattern) : undefined;
+  if (globDirectory !== undefined) {
+    const rootLevelOnly = patternIsRooted && !globDirectory.includes("/");
+    return ancestorDirectories(normalizedPath).some(
+      (ancestor) =>
+        !(rootLevelOnly && ancestor.includes("/")) && globMatches(ancestor, globDirectory),
+    );
+  }
+
   if (normalizedPattern.endsWith("/")) {
     const prefix = normalizedPattern.replace(/\\(.)/g, "$1").replace(/\/+$/, "");
     if (!patternIsRooted && !prefix.includes("/")) {
@@ -63,6 +105,19 @@ function hasComplexGlob(pattern: string): boolean {
   return /[*?[\]{}!()+@]/.test(pattern);
 }
 
+function globDirectoryOf(normalizedPattern: string): string | undefined {
+  if (!normalizedPattern.endsWith("/")) {
+    return undefined;
+  }
+  const directory = normalizedPattern.replace(/\/+$/, "");
+  return hasComplexGlob(directory) && !directory.startsWith("!") ? directory : undefined;
+}
+
+function ancestorDirectories(filepath: string): string[] {
+  const segments = filepath.split("/").slice(0, -1);
+  return segments.map((_, index) => segments.slice(0, index + 1).join("/"));
+}
+
 /** Higher score means a more specific pattern (used to break ties within one policy.yml). */
 export function patternSpecificity(pattern: string): number {
   const normalized = pattern.replace(/^\/+/, "");