@cursor/july 0.1.5 → 0.1.6

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

@@ -0,0 +1,174 @@
+---
+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 cloud 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. |
+| [`evals/ingest.eval.ts`](../../examples/codebase-wiki/evals/ingest.eval.ts) | Gates ingest decisions against the wiki filesystem. |
+
+There is no MCP connection, subagent, hook, A/B experiment, or custom
+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 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
+agentkit validate --dir examples/codebase-wiki
+agentkit 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
+agentkit dev examples/codebase-wiki
+
+agentkit 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
+agentkit 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 `agentkit 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
+agentkit eval --dir examples/codebase-wiki --list
+agentkit 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

@@ -0,0 +1,195 @@
+---
+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. |
+| [`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
+agentkit validate --dir examples/codeowners-review
+agentkit 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
+agentkit call list_review_areas --dir examples/codeowners-review --input '{}'
+
+agentkit 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
+agentkit 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
+agentkit 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
+agentkit eval --dir examples/codeowners-review --list
+agentkit 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

@@ -0,0 +1,205 @@
+---
+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. Agentkit 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. Agentkit 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. |
+
+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
+agentkit validate --dir examples/concierge
+agentkit 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/"
+agentkit 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
+agentkit 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
+agentkit 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
+
+Agentkit 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
+agentkit serve --dir "$PAIR_DIR" \
+  --public-url https://agents.example.com \
+  --bearer-token "$AGENT_TOKEN"
+```
+
+Agentkit 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)