@cursor/july 0.1.1

package/docs/guides/github.md

@@ -0,0 +1,172 @@
+---
+title: "GitHub"
+description: "Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."
+---
+
+# GitHub agents
+
+Wake your agent from repository events without exposing a public webhook
+URL. Prefer `serve --cursor-events`: the host long-polls Cursor's SCM
+event stream for repos you've connected to Cursor. You still declare a
+`githubChannel` so hooks decide what each event does.
+
+The companion skill for coding agents is
+[`skills/github/SKILL.md`](../../skills/github/SKILL.md).
+
+## Pull events from Cursor
+
+Connect GitHub in Cursor for the repositories you care about (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). That gives your
+account access and lets Cursor receive the repo's webhooks. Sign the host
+in (`agentkit login` or `CURSOR_API_KEY`), define a GitHub
+channel, then serve with `--cursor-events` and at least one `--repo`:
+
+```bash
+agentkit serve --dir . --cursor-events --repo owner/repo
+```
+
+Repeat `--repo` for each repository. The stream is read as the host's
+Cursor user. `serve` refuses to start signed out rather than run a relay
+that can never receive events.
+
+Offset and consumer id live under `<state-root>/cursor-events/`.
+`CURSOR_API_BASE_URL` overrides the backend. The stream carries event
+metadata, not full webhook bodies, so your agent should re-read the PR
+or checks from GitHub instead of trusting a snapshot in the wake.
+
+This is the preferred production path: no public URL, no repo admin
+webhook, and no inbound network for GitHub deliveries.
+
+## Define the channel
+
+Author `agent/channels/github.ts` with `githubChannel()` from
+`@cursor/july/channels/github`. It mounts
+`POST /<slug>/v1/channels/github` and publishes the events it
+dispatches on. That event set comes from the hooks you declare, or you
+pin it with `webhookEvents`. Cursor event pull and local replay both use
+it.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+
+export default githubChannel({
+  botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
+  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  onPullRequest: (ctx, pr) =>
+    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+  onCheckSuite: (ctx, suite) =>
+    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
+});
+```
+
+The hooks are `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
+`onCheckRun`, `onWorkflowRun`, `onStatus`, the catch-all `onEvent`, and
+the lifecycle pair `onStart` / `onStop`. Each hook returns one of three
+things:
+
+| Return | Meaning |
+| --- | --- |
+| `{ auth }` | Start or continue a model turn as that actor. A chat session exists and shows up in the playground. |
+| `{ task }` | Host-side work. The delivery is 202-ACKed immediately and the task runs past GitHub's ~10-second timeout. No chat session. |
+| `null` | Skip this delivery. |
+
+Return `{ task }` when the wake drives deterministic code. A security
+reviewer can run its whole review loop this way and report
+through commit statuses. Return `{ auth }` when the model needs to reason
+about the event.
+
+Outbound GitHub API calls prefer App installation tokens when
+`GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` are set (with an
+installation id from the event or `GITHUB_APP_INSTALLATION_ID`). On
+serve warmup, App-backed hosts also export a short-lived installation
+token as `GH_TOKEN` so tools that shell out to `gh` (a host-side
+`prepare_review` tool, say) authenticate without a PAT. For
+local testing, skip the App credentials and use `GITHUB_TOKEN`,
+`GH_TOKEN`, or `gh auth login`.
+
+## Test wakes locally
+
+Use fixtures and `github replay` so you can develop without waiting on
+live pushes. Both target the same channel route the Cursor relay uses.
+
+### Post a saved fixture
+
+For offline tests, POST a saved payload with an `x-github-event` header.
+A `--dev` server does not require a signature:
+
+```bash
+curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
+  -H 'content-type: application/json' \
+  -H 'x-github-event: pull_request' \
+  -d @fixtures/github/pull_request.synchronize.json
+```
+
+Don't hand-write payloads. Snapshot real ones with replay's
+`--dry-run --out`, below.
+
+### Test with `github replay`
+
+Use `replay` for deterministic tests and
+[hillclimbing](../hillclimbing.md). It reads a real PR with `gh api`,
+synthesizes GitHub-shaped payloads, signs them when a secret is
+configured, and POSTs them at the channel. Pull access is enough: no
+admin, and an env `GITHUB_TOKEN` is fine here. The same input produces
+the same delivery.
+
+```bash
+# Replay a pull_request delivery for a PR
+agentkit github replay https://github.com/owner/repo/pull/123 --dir .
+
+# Replay everything the channel listens for, with CI failing
+agentkit github replay owner/repo#123 --dir . --events '*' --conclusion failure
+
+# Inspect payloads without POSTing, and snapshot them as fixtures
+agentkit github replay owner/repo#123 --dir . --events '*' --dry-run --out fixtures/github
+```
+
+`--events` defaults to `pull_request`, and `'*'` means the channel's
+declared set. `--action`, `--conclusion`, `--comment`, and `--context`
+shape each synthesized event. `--secret` (or `GITHUB_WEBHOOK_SECRET`)
+signs them.
+
+## Receive webhooks directly
+
+Most hosts should pull events from Cursor instead. Use the HTTP channel
+route when you already terminate GitHub webhooks yourself, or when you
+are POSTing fixtures and replay locally.
+
+With a webhook secret configured, the route admits everyone
+(`allowAll()`) and the channel verifies `X-Hub-Signature-256` before
+parsing. The HMAC becomes the request principal. Without a secret, the
+route is loopback-only. The exception is `serve --dev`, which admits
+unsigned loopback deliveries so fixtures and replay work with zero
+config. Non-dev targets that accept real GitHub POSTs always need the
+secret, and the same value must live on the server and on whatever signs
+deliveries.
+
+## Handle high event volume
+
+These patterns come from running a PR agent against real traffic:
+
+- Debounce per PR (~3 seconds, latest event wins), and re-buffer while
+  CI settles. Skip a flush when a turn for that PR is already running.
+- Persist the buffer before you acknowledge a wake, and restore it on
+  channel start. A restart must not drop buffered wakes.
+- Key sessions with a stable continuation token (`pr:owner/repo#N`) so
+  every wake resumes the PR's conversation. Cross-channel resume needs
+  an affinity store mapping PR → SDK agent id; write one from an
+  `agent.bound` hook.
+- Keep payload details out of wake prompts. Send a generic "re-check
+  the PR" and let the agent re-read source of truth instead of trusting a
+  stale snapshot.
+- Cancel PR-scoped reminders on `pull_request.closed`.
+- Decide explicitly which repos the agent may act on. Without an
+  allowlist the channel wakes for whatever deliveries reach it, and
+  every wake spends real model budget.
+
+## Related
+
+- [Webhooks and custom channels](./webhooks.md): the HTTP mechanism under
+  this pack
+- [Evals](../evals.md): turn replay snapshots into regression fixtures
+- [Cloud runtime](./cloud-runtime.md): attach PRs to cloud VMs

package/docs/guides/human-in-the-loop.md

@@ -0,0 +1,131 @@
+---
+title: "Human-in-the-loop"
+description: "Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."
+---
+
+# Human-in-the-loop approvals
+
+Some tools must wait for human review: promoting a build, approving a PR,
+spending money. Mark those tools `needsApproval` and the host parks the
+in-flight call until a person approves or denies it, from the
+playground, over HTTP, or with Slack buttons. The turn stays running;
+nothing executes until someone decides.
+
+## Gate a tool
+
+Mark the tool with `needsApproval` and export it like any other tool.
+
+```ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Promote a verified build to production.",
+  needsApproval: true,
+  inputSchema: z.object({
+    service: z.string(),
+    buildId: z.string(),
+  }),
+  async execute({ service, buildId }) {
+    return {
+      promoted: true,
+      service,
+      buildId,
+      environment: "production",
+    };
+  },
+});
+```
+
+`needsApproval` also takes a predicate over the validated input, so you
+can gate only the dangerous shapes:
+
+```ts
+needsApproval: (input) => input.amountUsd > 100,
+```
+
+## What happens to a gated call
+
+When the model calls a `needsApproval` tool, the call parks and the
+session's stream emits `action.approval_requested` with the `callId`,
+tool name, and arguments. The turn stays running and waits. When a
+person resolves it, the stream emits `action.approval_resolved` with the
+decision and, where known, who decided. On approval, `execute` runs and
+`action.result` follows exactly as if the tool had run immediately. On
+denial, the model receives the denial as the tool result and continues
+the turn. It can explain, adjust, or try something else.
+
+Approvals exist for `execution: "server"` tools on the local runtime
+only. Parked calls do not survive a host restart: pending approvals left
+after a crash resolve as interrupted, and you re-run the turn.
+
+## Resolve from the playground
+
+Parked calls render Approve / Deny buttons inline in the conversation.
+Nothing to configure.
+
+## Resolve over HTTP
+
+List and resolve programmatically. The routes run the same auth chain as
+the rest of the session API, and the caller must be the session owner:
+
+```bash
+curl http://127.0.0.1:3000/<slug>/v1/session/ses_.../approvals
+# {"approvals":[{"callId":"...","toolName":"approve_pr","args":{...}}]}
+
+curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_.../approvals/<callId> \
+  -H 'content-type: application/json' \
+  -d '{"decision":"approve"}'   # or "deny"
+```
+
+## Resolve from Slack
+
+Set `toolApprovals: true` on the Slack channel and the pack posts Block
+Kit Approve/Deny cards and routes the button clicks back to the parked
+call:
+
+```ts
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel({
+  toolApprovals: true,
+});
+```
+
+The Slack app manifest needs interactivity enabled. Cards show redacted,
+truncated arguments because of Block Kit size limits. Execution still
+uses the full validated input, so review sensitive tools in the
+playground when the arguments may exceed the card. Details in the
+[Slack guide](./slack.md#add-approval-buttons).
+
+In `serve --dev`, the playground can also list Slack sessions and
+resolve their parked tools (the audit trail records the HTTP caller).
+That bridge does not open cross-owner approval for HTTP sessions, and
+production and bearer-auth hosts stay strict: Slack approvals must come
+from Slack interactivity or a matching principal.
+
+## Design principles for approvals
+
+Park/resume is independent of delivery: `needsApproval` works with no
+Slack channel at all, because the playground and HTTP surfaces are
+always there.
+
+Prefer approval gates over trust in instructions. "Only call this tool
+when…" is a suggestion; `needsApproval` is a guarantee. And pair
+approvals with dry-run defaults for destructive integrations: post real
+PR reviews only behind an explicit env flag like `MY_AGENT_LIVE=1`, no
+matter who approved.
+
+Deterministic tool calls (`agentkit call`, `POST /v1/tools/:name`)
+execute directly without parking. There the human is the caller.
+Approval parking applies to model-initiated calls.
+
+## What's next
+
+Continue with these pages:
+
+- [Tools](../reference/tools.md): the full tool API `needsApproval`
+  lives on
+- [Slack](./slack.md): the approval cards in context
+- [Sessions and streaming](../reference/sessions.md): the
+  `action.approval_*` events on the wire

package/docs/guides/slack.md

@@ -0,0 +1,245 @@
+---
+title: "Slack"
+description: "Put the agent in Slack over Socket Mode: manifests, tokens, doctor, engagement rules, and approval buttons."
+---
+
+# Slack agents
+
+The Slack channel puts your agent in Slack over Socket Mode: no public
+Request URL, streaming replies in threads, tool "thinking" steps,
+suggested prompts, and opt-in approval buttons. Setup is four short
+phases. Two are yours, and two need a human with Slack admin access.
+
+The companion skill is
+[`skills/setup-slack/SKILL.md`](../../skills/setup-slack/SKILL.md).
+
+## Define the channel
+
+Author `agent/channels/slack.ts` with `slackChannel()` from
+`@cursor/july/channels/slack`:
+
+```ts
+import { slackChannel } from "@cursor/july/channels/slack";
+
+// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+export default slackChannel();
+
+// Multi-agent serve: one Slack app (and token pair) per agent
+export default slackChannel({ envPrefix: "WEATHER_AGENT" });
+// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
+```
+
+By default the channel connects over Socket Mode (the app connects
+outward, so it works from behind any firewall) and responds only to
+`app_mention` events and direct messages. Threads bind to sessions with
+`continuationToken = channelId:threadTs`, so a thread is one durable
+conversation. Replies stream (`chat.startStream` / `appendStream` /
+`stopStream`) with a plain-message fallback, a rotating status shows
+while the agent works, and the pack sets thread titles and suggested
+prompts. When a Slack API is unavailable (`method_not_found`,
+`missing_scope`), the pack degrades to `postMessage` instead of failing.
+
+Missing tokens leave the channel idle (`channel idle … missing
+credentials`) rather than failing `serve`. That's useful when you mount
+many agents and only some have Slack apps.
+
+## Use the Cursor Slack connection
+
+If the Cursor Slack app is already installed in your workspace and linked
+to your Cursor account, skip the dedicated Slack app:
+
+```ts
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel({
+  cursorAccount: true,
+  agentName: "Weatherbot", // defaults to a name derived from the mount slug
+  agentIcon: { emoji: ":robot_face:" },
+});
+```
+
+Sign the host in (`agentkit login` or `CURSOR_API_KEY`), then mention the
+agent in Slack as `@Cursor Weatherbot …`. Thread replies and DMs keep going to
+the same agent. Messages appear as the Cursor app under that agent's name
+and icon, with live updates as the turn progresses.
+
+Use a dedicated Socket Mode Slack app when you need your own bot user,
+channel watching (`engagement.channelPosts`), or approval buttons. On
+`cursorAccount`, agents must be explicitly addressed (@mention, DM, or
+claimed-thread reply). Channel watching and `toolApprovals` /
+`interactivity` are Socket Mode only; the Cursor connection does not relay
+Block Kit clicks. Agent names must be unique on the host; an unmatched
+`@Cursor <name>` stays on Cursor's normal Slack agent.
+
+## Set it up
+
+### Generate the app assets
+
+One command generates the channel file, the app manifests, and the env template.
+
+```bash
+agentkit slack init --dir . --name "My Agent"
+```
+
+This writes `agent/channels/slack.ts` (with an `envPrefix` derived from
+the directory name), importable app manifests at
+`.agentkit/slack/manifest.{dev,prod}.json`, and
+`.agentkit/slack/env.example`. Use `--no-prefix` for the shared
+`SLACK_*` variables on single-agent hosts, `--prefix CUSTOM` to
+override, and `--channel-posts` if you plan to watch channels.
+
+### Create the apps (human, Slack admin)
+
+This phase needs a human with permission to create Slack apps.
+
+1. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New
+   App** → **From a manifest**.
+2. Paste `manifest.dev.json` and create the dev app.
+3. Repeat with `manifest.prod.json`. Dev and prod are separate Slack
+   apps with separate tokens.
+
+### Install and mint tokens (human)
+
+For each app: **Install to Workspace** and copy the Bot User OAuth Token
+(`xoxb-…`), then under **Basic Information → App-Level Tokens** create a
+token with scope `connections:write` and copy it (`xapp-…`).
+
+### Wire the env and verify
+
+Export the tokens in the shell that runs `serve`, using the names from
+`env.example`. The CLI doesn't load `.env` files itself, so use your
+usual env manager if you keep them in one:
+
+```bash
+export MY_AGENT_SLACK_BOT_TOKEN=xoxb-…
+export MY_AGENT_SLACK_APP_TOKEN=xapp-…
+```
+
+```bash
+agentkit slack doctor --prefix MY_AGENT
+```
+
+Proceed when `app_token`, `connections_open`, `bot_token`, and
+`auth_test` are all green. Then serve and smoke it:
+
+```bash
+agentkit serve --dir . --dev
+# expect: [agentkit/slack] Socket Mode connected
+```
+
+Invite the bot to a channel and @mention it (or DM it). Expect the
+Thinking… status, then a threaded streaming reply, with correlated
+server logs (`inbound kind=app_mention`, `session start`,
+`reply delivered via stream|postMessage`).
+
+## Choose when the agent engages
+
+Mentions and DMs are on by default. Watching channels means dispatching
+on new posts without a mention. That's an explicit opt-in:
+
+```ts
+export default slackChannel({
+  envPrefix: "TRIAGE",
+  engagement: {
+    // mentions / directMessages default to true
+    channelPosts: {
+      allow: ["#triage-alerts"], // explicit allowlist; no wildcard exists
+      posts: "top-level",       // default: thread replies never dispatch
+      debounceMs: 15_000,       // optional: let rapid edits settle
+    },
+  },
+  onChannelPost: async (ctx, message) => {
+    // same contract as onAppMention: return null to skip
+    return message.markdown.length > 20 ? {} : null;
+  },
+});
+```
+
+Channel watching needs the `message.channels` / `message.groups` events
+on the Slack app (Socket Mode only — not available with
+`cursorAccount: true`). Generate manifests with `slack init --channel-posts`,
+or add the events and re-import. The bot must also be a member of each
+watched channel. Posts that mention the bot stay on the `app_mention`
+path, bot-authored posts never dispatch, and deleting a post inside the
+debounce window cancels its dispatch. Watched posts reuse the
+thread-scoped principal, so a later @mention continues the same session.
+Set `engagement.mentions` or `engagement.directMessages` to `false` to
+turn those surfaces off.
+
+## Prepare work on the host
+
+Mention and DM handlers may return a prepared `message`,
+`workspaceFiles`, or `cloud` block. It's the same host-prep pattern as
+[custom channels](./webhooks.md#prepare-on-the-host-then-hand-off).
+PR agents use it: extract a PR URL from the mention text and run the
+same host path as the HTTP channel.
+
+## Add approval buttons
+
+Tools with `needsApproval` park until a person decides. Route that
+through Slack with one flag:
+
+```ts
+export default slackChannel({
+  toolApprovals: true, // posts Block Kit Approve/Deny cards + routes clicks
+});
+```
+
+The Slack app manifest must have interactivity enabled. Regenerate with
+`buildSlackManifest({ interactivity: true })` (or edit and re-import) if
+your app predates it. Composing events by hand instead: spread
+`buildToolApprovalEvents({ credentials })` into `events` and set
+`interactivity: true` on the channel so Socket Mode routes the clicks.
+
+Approval buttons need Socket Mode. `slackChannel({ cursorAccount: true })`
+rejects `toolApprovals` and `interactivity` at construction, since the
+Cursor Slack connection does not relay Block Kit clicks. Use a dedicated
+Slack app to run approvals for a cursor-account agent.
+
+Cards show redacted, truncated arguments (Block Kit size limits);
+execution still uses the full validated input, so review sensitive tools
+in the playground when the arguments may exceed the card. Approvals
+exist for `execution: "server"` tools on the local runtime only, and
+parked calls do not survive a host restart. The full lifecycle is in
+[Human-in-the-loop](./human-in-the-loop.md).
+
+## Run several agents on one host
+
+One Slack app and token pair per agent. Never share a pair across
+agents in the same process. `envPrefix` keeps them apart
+(`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`, …), and agents without tokens mount
+with their Slack channel idle while everything else serves normally.
+
+## Keep the channel healthy
+
+Two habits matter most.
+
+- Don't `await` long work inside Slack dispatch handlers. The pack
+  dispatches through `waitUntil` and streams as the turn progresses.
+- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
+  playground can list and stream Slack sessions and resolve their parked
+  approvals (the audit trail records the HTTP caller). Bearer-auth hosts
+  stay strict: Slack approvals must come from Slack interactivity or a
+  matching principal.
+
+## CLI reference
+
+The `slack` subcommands cover setup end to end.
+
+```bash
+agentkit slack setup                     # guided checklist
+agentkit slack init --dir . --name "My Agent"
+agentkit slack init --dir . --no-prefix  # shared SLACK_* vars
+agentkit slack init --dir . --channel-posts
+agentkit slack manifest --env both       # regenerate manifests
+agentkit slack doctor --prefix MY_AGENT  # token / connectivity checks
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Human-in-the-loop](./human-in-the-loop.md): the approval lifecycle
+  behind `toolApprovals`
+- [Webhooks and custom channels](./webhooks.md): the mechanism this
+  pack is built on