@cursor/july 0.1.5 → 0.1.7

package/docs/example-agents/security-reviewer.md

@@ -0,0 +1,296 @@
+---
+title: "Run staged security reviews from GitHub events"
+description: "Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics."
+---
+
+# Run staged security reviews from GitHub events
+
+Security Reviewer turns a pull request into a staged host-side review. One
+tool prepares the diff and selects modules. A second fans out specialized
+reviewers and triages candidates as they arrive. A third deduplicates the
+confirmed findings, writes artifacts, and may publish a GitHub review.
+
+Use this example when the workflow needs several model workers, but the host
+must own orchestration, progress, artifacts, and the final write.
+
+[Browse the Security Reviewer source.](../../examples/security-reviewer/)
+
+## Run a three-stage host pipeline
+
+Security Reviewer is a pipeline, not one long agent turn:
+
+| Stage | Tool | Result |
+| --- | --- | --- |
+| Prepare | `prepare_review` | Fetch metadata and diff, create a `runId`, and select security modules. |
+| Review and triage | `run_reviewers` | Run module reviewers in parallel and start triage as each candidate arrives. |
+| Finalize | `finalize_review` | Apply thresholds, deduplicate findings, write artifacts, and optionally post a review. |
+
+`run_triage` remains available as a compatibility stage. In the normal flow,
+triage has already completed inside `run_reviewers`, so it reports existing
+results. If candidates exist without triage output, it starts triage workers
+and writes their state.
+
+The configured root agent chooses and sequences tools in chat. The review
+workers use a model selected by the host pipeline. They are
+created programmatically with the agent SDK, not discovered from
+`agent/subagents/`.
+
+## Follow a GitHub wake
+
+1. A non-draft `pull_request.opened` or `pull_request.synchronize` event
+   arrives for an allowlisted repository.
+2. The GitHub channel returns a host `{ task }`, so the webhook gets a 202
+   response before the long review starts.
+3. Host code tries to post a pending commit status and creates a playground
+   session.
+4. The root model sends one acknowledgement. It doesn't run review tools on
+   this path.
+5. The task calls `prepare_review`, `run_reviewers`, and `finalize_review`
+   deterministically inside that session.
+6. Reviewer candidates stream into duplicate gating and triage.
+7. Finalization writes artifacts and tries to post the GitHub review.
+8. The host tries to set a success commit status when no findings remain, a
+   failure status when findings remain, or an error status when the pipeline
+   throws.
+9. The final response is appended to the session as an assistant message.
+
+The session records each stage as a normal tool event, even though host code
+selected the tools.
+
+Review and status posting are best-effort. The channel chooses its final
+status from the finding count even when the review posting result says
+`posted: false`.
+
+## Map the framework features
+
+| Capability | Source | Role |
+| --- | --- | --- |
+| Root agent | [`agent/agent.ts`](../../examples/security-reviewer/agent/agent.ts), [`agent/instructions.md`](../../examples/security-reviewer/agent/instructions.md) | Configure local chat and explain the three-stage contract. |
+| Server tools | [`agent/tools/`](../../examples/security-reviewer/agent/tools/) | Expose each review stage to chat and host orchestration. |
+| GitHub channel | [`agent/channels/github.ts`](../../examples/security-reviewer/agent/channels/github.ts) | Filter wakes, run background tasks, and publish status. |
+| Progress channel | [`agent/channels/asr-progress.ts`](../../examples/security-reviewer/agent/channels/asr-progress.ts) | Serve live reviewer and triage state by `runId`. |
+| Playground renderer | [`agent/playground/tools/run_reviewers.tsx`](../../examples/security-reviewer/agent/playground/tools/run_reviewers.tsx) | Replace the generic tool chip with live module rows. |
+| SDK review pipeline | [`agent/lib/asr/`](../../examples/security-reviewer/agent/lib/asr/), [`review-stages.ts`](../../examples/security-reviewer/agent/lib/review-stages.ts) | Select modules, call model workers, triage, deduplicate, and write artifacts. |
+| Storage | [`agent/storage.ts`](../../examples/security-reviewer/agent/storage.ts) | Persist framework sessions through a custom adapter with lazy restore. |
+| A/B | [`agent/ab.ts`](../../examples/security-reviewer/agent/ab.ts), [`agent/ab.config.ts`](../../examples/security-reviewer/agent/ab.config.ts) | Compare all-severity versus high-only GitHub comments. |
+| Eval | [`evals/`](../../examples/security-reviewer/evals/) | Check stage-tool presence against a pinned sample. |
+
+There is no Slack channel, authored skill, discovered subagent, MCP
+connection, schedule, reminder, hook, tool approval, or cloud runtime.
+
+## Prepare the host
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime credential for the root turn and review workers.
+- GitHub read access for preparation.
+- GitHub write access for webhook-driven reviews and commit statuses.
+
+The pipeline exposes settings for:
+
+- the worker model,
+- reviewer and triage parallelism,
+- reviewer, triage, duplicate-gate, and final-dedupe timeouts, and
+- prior-comment loading.
+
+The active names live beside the orchestration in
+[`review-stages.ts`](../../examples/security-reviewer/agent/lib/review-stages.ts).
+
+## Validate the discovered agent
+
+```bash
+agentkit validate --dir examples/security-reviewer
+agentkit info --dir examples/security-reviewer --json
+agentkit eval --dir examples/security-reviewer --list
+```
+
+The manifest should show four server tools, two authored channels, one
+storage definition, and one A/B experiment. The eval listing should show one
+case.
+
+## Know the chat path's write boundary
+
+In chat, the root instructions ask the model to use this order:
+
+```text
+prepare_review -> run_reviewers -> finalize_review
+```
+
+They also ask the model to set `postComment: true` only on request. This is
+prompt policy, not a deterministic safety gate. The model chooses tool
+arguments, and `finalize_review` has no human approval. Use the direct stage
+calls below when a no-post proof must be enforced.
+
+## Call stages directly without publishing
+
+Call each stage and pass `postComment: false` yourself:
+
+```bash
+agentkit call prepare_review \
+  --dir examples/security-reviewer \
+  --input '{"prUrl":"https://github.com/owner/repo/pull/123"}'
+
+agentkit call run_reviewers \
+  --dir examples/security-reviewer \
+  --input '{"runId":"<run-id>"}'
+
+agentkit call finalize_review \
+  --dir examples/security-reviewer \
+  --input '{"runId":"<run-id>","postComment":false}'
+```
+
+Review state lives under the project's run-artifact directory, so later
+stages can open the prepared `runId`.
+
+> [!CAUTION]
+> `finalize_review` with `postComment: true` writes to GitHub. The webhook
+> path always requests that write. Chat instructions alone don't prevent it.
+
+## Watch parallel work in the playground
+
+Run the dev server:
+
+```bash
+agentkit dev examples/security-reviewer
+```
+
+Open the printed playground and start a review. The custom
+`run_reviewers` renderer polls the progress channel's `GET /:runId` route.
+
+It refreshes every 500 ms while the stage runs. Each row shows a reviewer
+module's state, candidates, reviewed areas, and failure. A second section
+shows triage jobs and confirmed or rejected counts.
+
+This is an authored playground extension. Agentkit discovers it by the tool
+name, so the generic `run_reviewers` chip becomes a domain-specific view
+without changing the framework playground.
+
+## Fan out reviewers while triage starts
+
+Module selection uses repository and path rules. The current module set
+covers:
+
+- agent tooling trust boundaries,
+- privileged service RPCs,
+- product-specific security risks,
+- dependency and supply-chain changes,
+- deployment and infrastructure code,
+- filesystem and workspace boundaries,
+- privacy, and
+- general security review.
+
+Selected modules may run more than once. Candidates pass through a duplicate
+gate, then bounded triage. Reviewer or triage failures can produce partial
+results. A final dedupe failure stops finalization.
+
+The pipeline writes JSONL journals as work completes. Final artifacts include
+the review bundle, patch, reviewer outputs, candidates, triage decisions,
+findings, accounting, and audit events.
+
+## Separate session storage from review artifacts
+
+`defineStorage` sends agentkit session and event records to a custom durable
+store. Security Reviewer sets `restore: "off"` so startup doesn't load old
+review sessions in bulk. A continuation lookup can still fetch a needed
+session.
+
+The staged review files are separate from session storage. Session-store
+durability doesn't preserve those files. All stages for one `runId` must see
+the same filesystem.
+
+This split is useful when conversation history needs shared durability but
+large review artifacts belong on attached storage or an object store.
+
+## Compare live comment variants
+
+The comment-severity experiment uses sticky session assignment with a 5%
+holdout:
+
+- `control` posts every finding.
+- `treatment` posts only high and critical findings.
+
+Finalization enforces the comment filter. The treatment also adds an
+instruction overlay asking chat and playground summaries to lead with high
+and critical findings. Full artifacts, `finalResponse`, finding counts, and
+status still include every finding. Stage-tool counters appear in the
+playground A/B view. Local sample and snapshot files persist under
+`.agent-serve/`.
+
+When a treatment session has only low or medium findings, the filtered review
+body currently says no vulnerabilities were found even though artifacts and
+status retain findings. Account for that mismatch before using this
+experiment as a publishing policy.
+
+Eval sessions skip A/B enrollment.
+
+## Test the GitHub channel carefully
+
+The channel currently accepts two configured repositories. It wakes on
+`opened` and `synchronize`, skips drafts, and requests `pr-write` access.
+
+Inspect its event surface:
+
+```bash
+agentkit github events \
+  --dir examples/security-reviewer \
+  --json
+```
+
+Replay reaches the full publishing path:
+
+```bash
+TEST_PR_URL=https://github.com/your-org/allowlisted-test-repo/pull/123
+agentkit github replay \
+  "$TEST_PR_URL" \
+  --dir examples/security-reviewer \
+  --action opened
+```
+
+Set `TEST_PR_URL` to a PR in the channel's configured repository allowlist.
+Run the command only against a PR intended for test reviews. It posts a commit
+status and may post findings.
+
+## Inspect the eval before running it
+
+```bash
+agentkit eval --dir examples/security-reviewer --list
+```
+
+The case reads pinned metadata from the committed fixture and checks for all
+three tool names. It doesn't assert their order. The current `prepare_review`
+still fetches the live PR, so the case needs GitHub access and isn't fully
+offline. It also doesn't assert finding location, severity, agreement with
+`gold.json`, or `postComment: false`.
+
+Don't use this committed case as a no-post proof with write-capable GitHub
+credentials. The prompt asks for no comment, but the model can still pass
+`postComment: true`.
+
+When you adapt the pipeline, add assertions for confirmed findings and make
+the prepare stage accept a materialized fixture if repeatable offline evals
+matter.
+
+## Build another staged pipeline
+
+Use staged host orchestration when:
+
+- each phase needs its own timeout and artifact,
+- model workers should run in bounded parallel,
+- later work can start as soon as partial results arrive,
+- a webhook must acknowledge before the work finishes, or
+- operators need live progress beyond one tool spinner.
+
+Keep external writes in finalization. Pass a `runId` between stages, journal
+progress before publishing, and make partial-worker failures visible in the
+result.
+
+## Where to go next
+
+- [GitHub](../guides/github.md)
+- [Tools](../reference/tools.md)
+- [Channels](../reference/channels.md)
+- [Playground](../reference/playground.md)
+- [Storage](../storage.md)
+- [Live A/B metrics](../ab.md)
+- [Evals](../evals.md)

package/docs/example-agents/slack-agent.md

@@ -0,0 +1,146 @@
+---
+title: "Put a minimal agent in Slack"
+description: "Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel."
+---
+
+# Put a minimal agent in Slack
+
+Slack agent is the smallest channel example. It has one runtime config, one
+instruction file, and one authored channel. A teammate mentions the agent,
+the local runtime harness runs a turn, and the answer
+returns to the same Slack thread.
+
+Use it to learn the minimum needed for a Slack agent before adding tools,
+workflows, or a dedicated app.
+
+[Browse the Slack agent source.](../../examples/slack-agent/)
+
+## Keep the Slack channel small
+
+Slack agent delegates transport details to the host connection. The authored
+file selects the account-linked transport, gives the agent a single-token
+router name and icon, and supplies suggested prompts.
+
+The complete channel lives in
+[`agent/channels/slack.ts`](../../examples/slack-agent/agent/channels/slack.ts).
+The framework supplies message intake, thread-scoped sessions, delivery,
+status updates, and suggested prompts.
+
+## Follow a Slack message
+
+1. A user mentions the agent or sends the host app a direct message naming
+   it.
+2. The Slack relay selects this channel by its single-token `agentName`.
+3. Agentkit maps the Slack channel and thread timestamp to a continuation
+   key.
+4. The local harness runs with
+   [`instructions.md`](../../examples/slack-agent/agent/instructions.md).
+5. The response returns to the triggering thread.
+6. A later message in the same thread resumes the durable session.
+
+The prompt asks for concise threaded replies. It doesn't define domain policy
+or tool routing.
+
+## Map the Slack agent files
+
+| File | Purpose |
+| --- | --- |
+| [`package.json`](../../examples/slack-agent/package.json) | Declares the example package and agentkit dependency. |
+| [`agent/agent.ts`](../../examples/slack-agent/agent/agent.ts) | Names the agent and selects the model. The omitted `runtime` defaults to local. |
+| [`agent/instructions.md`](../../examples/slack-agent/agent/instructions.md) | Sets the always-on response style. |
+| [`agent/channels/slack.ts`](../../examples/slack-agent/agent/channels/slack.ts) | Connects the signed-in host account to Slack. |
+
+There are no authored tools, skills, MCP connections, subagents, schedules,
+hooks, A/B experiments, or evals. This small surface is the lesson.
+
+## Connect the host
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime credential.
+- Slack connected through the selected channel transport.
+
+Sign in and confirm the active account:
+
+```bash
+agentkit login
+agentkit whoami
+```
+
+The selected transport owns Slack credential setup. See the
+[Slack guide](../guides/slack.md) for account-linked and dedicated-app
+options.
+
+## Validate and start the server
+
+```bash
+agentkit validate --dir examples/slack-agent
+agentkit info --dir examples/slack-agent --json
+agentkit dev examples/slack-agent
+```
+
+The dev command prints the playground URL. It also mounts the Slack channel
+and waits for relayed messages.
+
+In Slack, address the configured host app and router name, then send:
+
+> `<host-app mention> <router name>` Explain agentkit in three bullets.
+
+Reply in the generated thread:
+
+> Make the second bullet simpler.
+
+The second message reaches the same session. You can open that session in the
+playground to inspect the received message, model events, final reply, and
+usage.
+
+## Test without Slack
+
+Every project gets the built-in HTTP channel even when no HTTP file exists.
+Run a one-shot turn through it:
+
+```bash
+agentkit run --dir examples/slack-agent \
+  --message "Explain agentkit simply."
+```
+
+The same project also exposes an MCP endpoint. Since this agent has no server
+tools, its MCP surface contains `ask` and `check`, but not `call_tool`.
+
+These automatic surfaces let you test the prompt from the CLI and let another
+agent delegate to it later. The authored Slack channel only changes how work
+arrives and where replies go.
+
+## Know when to add a dedicated app
+
+An account-linked Slack transport is a fit for mentions, direct messages, thread
+continuity, and agent-branded replies. Move to a dedicated Socket Mode channel
+when you need:
+
+- top-level channel watching,
+- interactive approval buttons,
+- a separate bot identity, or
+- Slack app events unsupported by the account-linked relay.
+
+Compare this example with [Playbook router](./benny.md), which adds allowlisted channel
+watching, and [Weather agent](./weather-agent.md), which adds approval buttons
+through a second Slack channel.
+
+## Turn the channel into your own Slack agent
+
+Copy the three authored files, then change:
+
+- `name` in `agent.ts` for the harness identity,
+- `agentName` in `slack.ts` for the single-token router name,
+- the instructions for your domain, and
+- suggested prompts for the tasks teammates should try.
+
+Keep `agentName` free of whitespace. Use PascalCase for multiword names.
+
+## Where to go next
+
+- [Slack](../guides/slack.md)
+- [Channels](../reference/channels.md)
+- [Sessions and streaming](../reference/sessions.md)
+- [Playground](../reference/playground.md)