@cursor/july 0.1.92 → 0.1.94

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

@@ -1,175 +0,0 @@
----
-title: "Build a feature wiki from merged pull requests"
-description: "Ingest every merged PR into per-feature wiki pages, consolidate with a daily digest schedule, and answer codebase questions with page citations."
----
-
-# Build a feature wiki from merged pull requests
-
-Codebase wiki keeps a living, feature-organized wiki of a repository.
-The GitHub channel acknowledges every closed pull request instantly,
-fetches a compact digest on the host, and spends a model turn only on
-merged PRs. The turn maps the change onto feature pages; a daily
-schedule writes a digest of what changed and rebuilds the index. Chat
-sessions answer codebase questions from the wiki with page citations.
-
-Use this project when documentation should accumulate from merges
-instead of being regenerated from scratch. Use
-[Knowledge base](./knowledge-base.md) when people should curate
-organizational context through conversation.
-
-[Browse the codebase wiki source.](../../examples/codebase-wiki/)
-
-## Treat PRs as evidence and features as pages
-
-The wiki refuses to become a merge log:
-
-- The page tree is rigid: `index`, `features/<slug>`, and
-  `digests/<yyyy-mm-dd>`. The store rejects anything else, so the wiki
-  can't sprawl.
-- The `feature-mapping` skill requires a `wiki_search` before every
-  write. A PR updates the page that owns its feature; a new page needs
-  a genuinely new feature; chores change nothing.
-- Every touched page gets a dated changelog entry citing the PR
-  number, so each fact traces back to a merge.
-
-The wiki itself is markdown on the serve host, in `.agent-serve/wiki/`
-by default with a `CODEBASE_WIKI_DIR` override. Sessions are
-disposable; the wiki is the durable state.
-
-## Follow a merged PR
-
-1. GitHub delivers `pull_request` with action `closed`. The channel
-   returns a task acknowledgement immediately.
-2. The task fetches the digest with the host `gh` CLI: title, body,
-   labels, changed files, and a bounded diff excerpt. No checkout.
-3. The webhook payload can't say whether the PR merged, so the host
-   checks `mergedAt` and skips abandoned PRs without a model turn.
-4. For merged PRs, the task starts the turn with `pr/DIGEST.md` seeded
-   through `workspaceFiles` and a `pr:<owner/repo#N>` continuation
-   token, so redeliveries resume instead of double-ingesting.
-5. The model follows `feature-mapping`: search, update or create
-   feature pages, add changelog entries, and refresh `index` when pages
-   were added.
-
-In chat, "ingest PR #123" runs the same flow through the `ingest_pr`
-tool, which writes the digest into the active session workspace.
-
-## Map the wiki files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](../../examples/codebase-wiki/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](../../examples/codebase-wiki/agent/instructions.md) | Splits the job into merge ingestion and wiki-cited Q&A. |
-| [`agent/lib/wiki-store.ts`](../../examples/codebase-wiki/agent/lib/wiki-store.ts) | Enforces the rigid page tree and owns reads, writes, and search. |
-| [`agent/lib/pr-digest.ts`](../../examples/codebase-wiki/agent/lib/pr-digest.ts) | Fetches PR metadata and diff, and formats `pr/DIGEST.md`. |
-| [`agent/tools/ingest_pr.ts`](../../examples/codebase-wiki/agent/tools/ingest_pr.ts) | Exposes host digest preparation for chat-driven backfills. |
-| [`agent/tools/wiki_read.ts`](../../examples/codebase-wiki/agent/tools/wiki_read.ts), [`wiki_search.ts`](../../examples/codebase-wiki/agent/tools/wiki_search.ts), [`wiki_write.ts`](../../examples/codebase-wiki/agent/tools/wiki_write.ts) | Read, search, and rewrite wiki pages. |
-| [`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, or A/B experiment.
-
-## Prepare credentials and services
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-- `gh` on `PATH` with read access to the PRs you ingest.
-
-The channel verifies webhook signatures when `GITHUB_WEBHOOK_SECRET` is
-set and narrows repositories with
-`CODEBASE_WIKI_REPOS=owner/repo,owner/other`. The agent never writes to
-GitHub. Its only side effects are wiki files on the serve host.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/codebase-wiki
-agent-sdk info --dir examples/codebase-wiki --json
-```
-
-The manifest should report four server tools, one skill, one schedule,
-and the authored GitHub channel.
-
-## Ingest without webhook plumbing
-
-Replay a real merged PR as a closed delivery:
-
-```bash
-agent-sdk dev examples/codebase-wiki
-
-agent-sdk github replay https://github.com/owner/repo/pull/123 \
-  --dir examples/codebase-wiki --action closed
-```
-
-The reply is a 202 acknowledgement; the ingest continues in the task.
-Watch the session in the playground, then read the result on disk:
-
-```bash
-ls examples/codebase-wiki/.agent-serve/wiki/features/
-```
-
-Each ingested feature page carries an overview, a "How it works"
-section, and a changelog line citing the PR. Deterministic digest
-preparation works without a model turn:
-
-```bash
-agent-sdk call ingest_pr \
-  --dir examples/codebase-wiki \
-  --input '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-A PR closed without merging returns `merged: false` and a note telling
-the model to change nothing.
-
-## Run the daily digest
-
-The schedule fires at 07:00 UTC. Under `agent-sdk dev`, trigger it by
-hand:
-
-```bash
-curl -s -X POST http://127.0.0.1:3000/codebase-wiki/v1/dev/schedules/daily-digest
-```
-
-The turn reads every feature changelog, writes
-`digests/<today>` grouped by feature with PR citations, rebuilds
-`index`, and reports one line per page it wrote. Entries dated today
-always count; a digest only claims a quiet day when no entry qualifies.
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/codebase-wiki --list
-agent-sdk eval --dir examples/codebase-wiki ingest/update-existing
-```
-
-The cases seed a temp wiki through `CODEBASE_WIKI_DIR` and build
-digests with the same formatter the channel uses, so they run without
-GitHub or network access. The gates check the filesystem, not prose:
-a new feature page lands on a new slug, a related PR updates the
-existing page instead of duplicating it, an unmerged PR changes
-nothing, and the daily pass writes a digest naming both seeded
-features.
-
-## Reuse the merge-ingestion pattern
-
-Copy this shape when events should accumulate into curated state:
-
-- Acknowledge webhooks with a task and decide host-side whether a
-  model turn is worth spending.
-- Seed evidence through `workspaceFiles` so the model never fetches.
-- Constrain the durable store's shape in code and its content in a
-  skill.
-- Add a consolidation schedule so incremental writes stay coherent.
-
-## Where to go next
-
-- [GitHub webhooks](../guides/github.md)
-- [Schedules](../reference/schedules.md)
-- [Tools](../reference/tools.md)
-- [Evals](../evals.md)

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

@@ -1,197 +0,0 @@
----
-title: "Route PR reviews by code ownership"
-description: "Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision."
----
-
-# Route PR reviews by code ownership
-
-Codeowners review gives each part of a codebase its own review. A
-CODEOWNERS-style table maps changed paths to review areas; each area
-has a markdown playbook with the team's rules for that domain; and one
-`area-reviewer` subagent runs per routed area, in parallel. A billing
-change gets the billing review, a migration gets the migration review,
-and an author's personal style rides along as advisory notes. The lead
-aggregates: approve only when every area approves.
-
-Use this project when review quality depends on domain-specific values
-instead of one generic checklist.
-
-[Browse the codeowners review source.](../../examples/codeowners-review/)
-
-## Keep routing in code and judgment in playbooks
-
-The pipeline separates three concerns:
-
-- `reviews/REVIEWERS` routes. Host code matches every changed path
-  against the table; every matching rule applies, and unmatched paths
-  fall back to the `general` playbook. Routing is glob code with unit
-  tests, not model judgment.
-- `reviews/<area>.md` judges. Each playbook is a severity-ordered rule
-  list the team owns: billing mandates integer cents and idempotent
-  webhooks, migrations forbid destructive DDL beside code changes,
-  background jobs demand idempotency and dead-letter paths.
-- Subagents review. The lead reads nothing but the manifest and
-  routes; each `area-reviewer` reads one playbook plus its files' diff
-  hunks and returns a mechanical verdict: request changes on any High
-  finding or two Mediums.
-
-Personal styles extend the same mechanism. `reviews/people/<login>.md`
-attaches automatically, as advisory notes, whenever that person authors
-the PR. Adding an area or a style is a markdown file plus at most one
-routing line.
-
-## Follow a review
-
-1. A PR arrives: a GitHub `pull_request` event, a chat message, or a
-   bundled fixture reference.
-2. `prepare_review` fetches metadata and the diff with the host `gh`
-   CLI, routes every changed file, and writes the `pr/` evidence tree:
-   `MANIFEST.md`, `ROUTES.md`, `diff.patch`, and a copy of each matched
-   playbook.
-3. The lead follows the `review-process` skill and issues one
-   `area-reviewer` delegation per routed area, plus one per personal
-   style, all in one step so they run in parallel.
-4. Each reviewer reads its playbook, reviews only its files, and
-   returns a verdict line with at most three findings.
-5. The lead aggregates per-area sections and the overall verdict:
-   APPROVE only when every non-advisory area approved.
-
-Nothing posts to GitHub. Verdicts live in the session; the
-[Approval Buddy guide](./approval-buddy.md) shows how to wire a real
-APPROVE and commit statuses on top of the same shape.
-
-## Map the review files
-
-| File | Purpose |
-| --- | --- |
-| [`reviews/REVIEWERS`](../../examples/codeowners-review/reviews/REVIEWERS) | Routes path patterns to review areas. |
-| [`reviews/`](../../examples/codeowners-review/reviews/) | Holds the area playbooks and `people/<login>.md` styles. |
-| [`agent/lib/routing.ts`](../../examples/codeowners-review/agent/lib/routing.ts) | Parses the table, matches globs, and unions areas per file. |
-| [`agent/lib/prepare-review.ts`](../../examples/codeowners-review/agent/lib/prepare-review.ts) | Fetches PRs or fixtures and builds the evidence tree. |
-| [`agent/tools/prepare_review.ts`](../../examples/codeowners-review/agent/tools/prepare_review.ts) | Exposes host preparation as a typed server tool. |
-| [`agent/tools/list_review_areas.ts`](../../examples/codeowners-review/agent/tools/list_review_areas.ts) | Answers routing questions deterministically. |
-| [`agent/skills/review-process.md`](../../examples/codeowners-review/agent/skills/review-process.md) | Fixes the fan-out procedure and the verdict rule. |
-| [`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
-storage.
-
-## Prepare credentials and services
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-- `gh` on `PATH` with read access to real PRs you review. The bundled
-  fixtures need no network at all.
-
-The channel verifies webhook signatures when `GITHUB_WEBHOOK_SECRET` is
-set and narrows repositories with
-`CODEOWNERS_REVIEW_REPOS=owner/repo,owner/other`. Pushes re-review in
-the same session through the `pr:<label>` continuation token.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/codeowners-review
-agent-sdk info --dir examples/codeowners-review --json
-```
-
-The manifest should report two server tools, one skill, one subagent,
-and the authored GitHub channel.
-
-## Inspect routing without a model turn
-
-```bash
-agent-sdk call list_review_areas --dir examples/codeowners-review --input '{}'
-
-agent-sdk call prepare_review \
-  --dir examples/codeowners-review \
-  --input '{"pr":"fixture:multi-area"}'
-```
-
-The fixture routes to `billing`, `database-migrations`, and `frontend`,
-attaches `people/alice` because alice authored it, and returns the full
-evidence map. Point the same tool at a real PR URL and the routing runs
-against the live file list. The example table maps a hypothetical
-`src/` layout, so most real repositories route to `general` until you
-adapt `reviews/REVIEWERS`.
-
-## Review the planted fixture
-
-```bash
-agent-sdk dev examples/codeowners-review
-```
-
-In the playground:
-
-> Review fixture:multi-area
-
-The fixture plants one violation per area: float dollar math in
-`src/billing/invoice.ts`, a `DROP COLUMN` plus a non-concurrent index
-in the migration, and a clickable `div` without loading states in the
-UI. The trace shows `prepare_review`, the evidence reads, four parallel
-`area-reviewer` cards, and an aggregated CHANGES REQUESTED verdict with
-each planted bug filed under its own area. The second fixture,
-`fixture:jobs-clean`, routes to `background-jobs` alone and ends in
-APPROVE.
-
-Review a real PR the same way:
-
-> Review https://github.com/owner/repo/pull/123
-
-Or replay one as a webhook delivery:
-
-```bash
-agent-sdk github replay https://github.com/owner/repo/pull/123 \
-  --dir examples/codeowners-review --action opened
-```
-
-## See how the verdict stays mechanical
-
-The reviewer contract computes verdicts from findings instead of
-letting the model pick a mood: findings first, then
-`request-changes` if any High exists or two Mediums do, otherwise
-`approve`. Pre-existing issues visible in context are scoped out, at
-most one advisory Low. The lead applies one rule on top: the PR is
-APPROVE only when every non-advisory area approved.
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/codeowners-review --list
-agent-sdk eval --dir examples/codeowners-review review/multi-area
-```
-
-`review/multi-area` gates the whole pipeline: `prepare_review` runs, at
-least three subagent delegations happen, the reply carries every area
-section plus alice's advisory notes, the planted billing and migration
-bugs surface, and the verdict requests changes. `review/clean-approve`
-proves the approval path on the clean fixture, and
-`review/routing-question` gates that routing answers come from
-`list_review_areas`.
-
-## Reuse the ownership-routing pattern
-
-Copy this shape when different code deserves different judgment:
-
-- Route with data and code, not prompt instructions. Tables and globs
-  are testable.
-- Write one playbook per domain and keep each reviewer blind to the
-  others.
-- Make verdicts mechanical so aggregation is arithmetic, not
-  negotiation.
-- Ship fixtures with planted findings so the review quality itself is
-  testable offline.
-
-## Where to go next
-
-- [Approval Buddy](./approval-buddy.md) for posting real approvals
-- [Subagents](../reference/subagents.md)
-- [GitHub webhooks](../guides/github.md)
-- [Evals](../evals.md)

package/docs/example-agents/concierge.md

@@ -1,206 +0,0 @@
----
-title: "Compose agents with a concierge"
-description: "Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions."
----
-
-# Compose agents with a concierge
-
-Concierge answers general questions itself and sends every weather question
-to the weather agent. The connection is one file. The Agent SDK turns the target
-agent's MCP endpoint into tools the concierge can call.
-
-Use this example when two agents are useful on their own and one should
-delegate a narrow class of work to the other.
-
-[Browse the Concierge source.](../../examples/concierge/)
-
-## Delegate through a peer MCP connection
-
-Concierge has no domain tool of its own. Its capability comes from a peer MCP
-connection:
-
-```ts
-export default defineConnection({
-  agent: "weather-agent",
-  description:
-    "The weather-agent peer: delegate weather questions with ask; it runs its own tools (live Open-Meteo data) in its own context.",
-});
-```
-
-The filename
-[`weather.ts`](../../examples/concierge/agent/mcp-connections/weather.ts)
-makes the MCP server name `weather`. The `agent` field points to the sibling
-project's mount slug.
-
-This differs from a subagent. A peer keeps its own:
-
-- root instructions,
-- tools and MCP connections,
-- durable sessions,
-- playground, and
-- public MCP endpoint.
-
-An SDK subagent inherits the parent's execution surface and only its parent
-can invoke it. See [Agent-to-agent](../guides/agent-to-agent.md) for the full
-comparison.
-
-## Follow a delegated request
-
-1. A user asks Concierge what to pack for Paris.
-2. [`instructions.md`](../../examples/concierge/agent/instructions.md)
-   classifies packing advice as weather-related.
-3. The model calls `weather.ask` with the city, timeframe, units, and the
-   complete question.
-4. The Agent SDK creates an MCP-channel session inside `weather-agent`.
-5. Weather agent calls its own Open-Meteo tools and returns a reply.
-6. If the turn exceeds the bounded MCP wait, `ask` returns
-   `status: "running"`. Concierge calls `weather.check` with the returned
-   `sessionId`.
-7. Concierge relays the result and may add one sentence of travel advice.
-
-The weather session appears in the weather agent's playground. It doesn't
-share Concierge's conversation history.
-
-## Map the delegation files
-
-| File | Purpose |
-| --- | --- |
-| [`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
-exist.
-
-Its own MCP endpoint exposes `ask` and `check`. It doesn't expose
-`call_tool` because Concierge has no server tools. The target weather agent
-does expose `call_tool`, so that tool also appears under Concierge's
-`weather` connection.
-
-## Mount both agents
-
-A peer can only resolve within a multi-agent serve host. Validating Concierge
-alone checks its files, but serving it alone fails because `weather-agent`
-isn't mounted.
-
-From `packages/agent-serve`, validate both projects:
-
-```bash
-agent-sdk validate --dir examples/concierge
-agent-sdk validate --dir examples/weather-agent
-```
-
-Don't serve the repository's whole `examples/` directory for this proof.
-Several advanced examples subscribe to live GitHub events. Create an ignored
-two-project mount instead. Copy only the authored files needed for this proof,
-leaving Weather's Slack channels out:
-
-```bash
-mkdir -p "$PWD/.agent-serve"
-PAIR_DIR=$(mktemp -d "$PWD/.agent-serve/concierge-weather.XXXXXX")
-mkdir -p "$PAIR_DIR/concierge" "$PAIR_DIR/weather-agent/agent"
-cp -R examples/concierge/agent "$PAIR_DIR/concierge/"
-cp examples/concierge/package.json "$PAIR_DIR/concierge/"
-cp examples/weather-agent/agent/{agent.ts,instructions.md,ab.ts,ab.config.ts} \
-  "$PAIR_DIR/weather-agent/agent/"
-cp -R examples/weather-agent/agent/{tools,skills,mcp-connections,subagents,schedules,hooks,lib} \
-  "$PAIR_DIR/weather-agent/agent/"
-cp -R examples/weather-agent/mcp "$PAIR_DIR/weather-agent/"
-cp examples/weather-agent/package.json "$PAIR_DIR/weather-agent/"
-agent-sdk dev "$PAIR_DIR"
-```
-
-The host resolves the peer after it knows every mount. The local peer URL is
-`http://127.0.0.1:3000/weather-agent/v1/mcp`. You still need an agent-runtime
-credential for both model turns.
-
-## Exercise delegation
-
-Send a weather request to the running Concierge:
-
-```bash
-agent-sdk chat \
-  --url http://127.0.0.1:3000/concierge \
-  --message "What should I pack for Paris tomorrow?"
-```
-
-Open both playgrounds:
-
-- `http://127.0.0.1:3000/concierge/playground`
-- `http://127.0.0.1:3000/weather-agent/playground`
-
-The Concierge transcript shows the MCP call. The weather playground shows a
-separate session on the `mcp` channel with live weather tool calls.
-
-Now send a general request:
-
-```bash
-agent-sdk chat \
-  --url http://127.0.0.1:3000/concierge \
-  --message "Give me three ideas for a quiet weekend."
-```
-
-The instructions tell Concierge to answer without delegating. This contrast is
-the proof loop: weather goes to the peer, unrelated work stays local.
-
-## Preserve peer context
-
-`weather.ask` returns a peer `sessionId`. Passing it back to a later `ask`
-continues the same weather conversation. Concierge's instructions require
-this for follow-ups dependent on an earlier answer.
-
-Use a fresh call when the tasks are independent. Reuse the peer session when
-the second question needs facts or choices from the first.
-
-## Keep delegation bounded
-
-The Agent SDK rejects unknown peer slugs and self-references during startup. It
-doesn't stop a cycle across several valid peers. If agent A delegates all work
-to B and B delegates all work to A, they can recurse.
-
-The prompt provides the guardrail here:
-
-- delegate every weather request,
-- include complete context, and
-- never delegate unrelated work.
-
-Write similarly narrow routing rules for each peer. A tool description helps
-the model choose the connection, but the always-on instructions own the
-policy.
-
-## Use peers from cloud turns
-
-Local turns reach peers over loopback. A cloud VM can't reach the serve
-host's loopback address. Set a public URL when a cloud agent needs the peer:
-
-```bash
-agent-sdk serve --dir "$PAIR_DIR" \
-  --public-url https://agents.example.com \
-  --bearer-token "$AGENT_TOKEN"
-```
-
-The Agent SDK attaches the bearer token to peer calls. Without `--public-url`,
-cloud turns omit peer connections and the server logs a warning.
-
-## Compose your own pair
-
-To compose your own agents:
-
-1. Give each project a stable directory slug.
-2. Add `agent/mcp-connections/<name>.ts` to the caller.
-3. Set `agent` to the target slug.
-4. Describe the exact work the peer owns.
-5. Mount both projects from their parent directory.
-6. Add evals for delegated and non-delegated requests.
-
-Keep the peer independently useful. If the specialist only makes sense inside
-one parent and needs no independent sessions, use a subagent instead.
-
-## Where to go next
-
-- [Agent-to-agent](../guides/agent-to-agent.md)
-- [MCP connections](../reference/connections.md)
-- [Subagents](../reference/subagents.md)
-- [Sessions and streaming](../reference/sessions.md)