@cursor/july 0.1.109 → 0.1.112

package/docs/guides/gitlab.md

@@ -1,40 +1,240 @@
 ---
 title: "GitLab"
-description: "Wake your agent from GitLab merge requests, notes, pipelines, and pushes on GitLab.com or self-managed GitLab."
+description: "Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab."
 ---
 
 # GitLab agents
 
-Use `gitlabChannel()` for GitLab.com and self-managed GitLab. The channel
-verifies project hooks, normalizes their payloads, and gives each hook a
-project-bound `ctx.gitlab` API client.
+A GitLab agent wakes from a verified project event, reads the current
+project or merge-request state, and writes the result back to GitLab.
+`gitlabChannel()` supports the same hooks on GitLab.com and self-managed
+GitLab.
 
-## Define the channel
+## Review a merge request
 
-Author `agent/channels/gitlab.ts`:
+Opening, reopening, or pushing commits to a merge request starts a
+review. The hook reads the latest diff through the project-bound GitLab
+client, the model returns a verdict, and the completed answer appears
+as a note on the merge request.
 
 ```ts
-import { gitlabChannel } from "@cursor/july/channels/gitlab";
+// agent/channels/gitlab.ts
+import {
+  createGitLabApi,
+  defaultGitLabAuth,
+  gitlabChannel,
+  gitlabChannelStateForEvent,
+} from "@cursor/july/channels/gitlab";
+import {
+  postMergeRequestNote,
+  setPipelineTriageStatus,
+} from "../lib/gitlab.js";
 
-export default gitlabChannel({});
+export default gitlabChannel({
+  projects: ["acme/platform"],
+  onMergeRequest: async (ctx, mergeRequest) => {
+    if (mergeRequest.draft) {
+      return null;
+    }
+    const hasNewCommits =
+      mergeRequest.action === "update" && mergeRequest.oldrev !== undefined;
+    if (
+      mergeRequest.action !== "open" &&
+      mergeRequest.action !== "reopen" &&
+      !hasNewCommits
+    ) {
+      return null;
+    }
+
+    const api = createGitLabApi(
+      ctx.gitlab,
+      ctx.project.pathWithNamespace
+    );
+    const diffs = await api.listMergeRequestDiffs(mergeRequest.iid);
+    return {
+      // `auth` starts a model turn running as the event sender.
+      auth: defaultGitLabAuth(ctx),
+      message: `Review ${ctx.project.pathWithNamespace}!${mergeRequest.iid}.`,
+      context: [`<gitlab_diffs>${JSON.stringify(diffs)}</gitlab_diffs>`],
+    };
+  },
+  events: {
+    async "message.completed"(event, channel, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      const mergeRequestIid = channel.state.mergeRequestIid;
+      if (
+        (channel.state.eventType !== "merge_request" &&
+          channel.state.eventType !== "note") ||
+        mergeRequestIid === null
+      ) {
+        return;
+      }
+      await postMergeRequestNote(
+        channel.state.projectPath,
+        mergeRequestIid,
+        event.data.text
+      );
+    },
+  },
+});
+```
+
+`postMergeRequestNote` is a small wrapper around the GitLab REST API.
+Configure it with the same API token and base described under
+[Connect](#connect). It uses the project and MR IID stored from the
+verified event, so the model never chooses where its review is posted.
+
+## Answer a note
+
+Mentioning `@cursor-reviewer` in an MR note resumes that merge
+request's conversation, and the reply sink from the first example posts
+the answer back to the same MR. The author guard drops notes written by
+the agent itself, preventing each reply from starting another turn.
+
+```ts
+const AGENT_USERNAME = "cursor-reviewer";
+
+onNote: (ctx, note) => {
+  if (note.author?.username === AGENT_USERNAME) {
+    return null;
+  }
+  if (!note.body.includes(`@${AGENT_USERNAME}`)) {
+    return null;
+  }
+  return {
+    auth: defaultGitLabAuth(ctx),
+    message: note.body,
+  };
+},
+```
+
+`onNote` receives merge-request notes by default. Add this property to
+the same `gitlabChannel()` declaration as the review handler.
+
+## Triage a failed pipeline
+
+When a pipeline fails, GitLab immediately shows a running
+`cursor/pipeline-triage` status on the commit. The webhook is
+acknowledged while the model investigates, then the status changes to
+success or failure based on whether that triage turn completed.
+
+```ts
+onPipeline: (ctx, pipeline) => {
+  if (pipeline.status !== "failed" || pipeline.sha === undefined) {
+    return null;
+  }
+  const sha = pipeline.sha;
+
+  return {
+    // `task` runs this host sequence after the webhook is acknowledged.
+    task: async ({ send }) => {
+      await ctx.gitlab.setCommitStatus({
+        sha,
+        state: "running",
+        name: "cursor/pipeline-triage",
+        description: "Investigating failed pipeline",
+      });
+
+      await send(
+        `Triage failed GitLab pipeline ${pipeline.id}.`,
+        {
+          auth: defaultGitLabAuth(ctx),
+          title: `GitLab pipeline ${pipeline.id}`,
+          state: {
+            ...gitlabChannelStateForEvent({
+              project: ctx.project,
+              headSha: sha,
+              eventType: ctx.eventType,
+            }),
+          },
+        }
+      );
+    },
+  };
+},
+```
+
+Extend the `events` map so the turn's terminal event concludes the
+status through the same provider wrapper:
+
+```ts
+async "message.completed"(event, channel, ctx) {
+  if (
+    ctx.session.purpose !== "eval" &&
+    channel.state.eventType === "pipeline" &&
+    channel.state.headSha !== null &&
+    event.data.finishReason !== "tool_call"
+  ) {
+    await setPipelineTriageStatus(
+      channel.state.projectPath,
+      channel.state.headSha,
+      "success",
+      "Pipeline triage complete"
+    );
+    return;
+  }
+
+  // Continue with the merge-request reply branch from the first example.
+},
+async "turn.failed"(_event, channel, ctx) {
+  if (
+    ctx.session.purpose === "eval" ||
+    channel.state.eventType !== "pipeline" ||
+    channel.state.headSha === null
+  ) {
+    return;
+  }
+  await setPipelineTriageStatus(
+    channel.state.projectPath,
+    channel.state.headSha,
+    "failed",
+    "Pipeline triage failed"
+  );
+},
 ```
 
-Without `onMergeRequest`, new and reopened merge requests start turns.
-Updates start turns only when they include new commits. Notes, pushes, and
-pipelines are opt-in through `onNote`, `onPush`, and `onPipeline`.
-Use `onEvent` for other GitLab event types. Set `webhookEvents` when managed
-event delivery must subscribe to an event that only `onEvent` handles.
+The status reports whether triage completed; it does not change the
+failed pipeline's own result.
+
+## Events
+
+Use `onMergeRequest`, `onNote`, or `onPipeline` for the events shown
+above. Each hook returns one of three decisions:
+
+| Return | What happens |
+| --- | --- |
+| `{ auth }` | Start a model turn as the GitLab event sender |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
+
+The [Channels reference](../reference/channels.md) covers the remaining
+hook and session behavior.
+
+## Merge request affinity
+
+Every merge-request event and note for the same project path and MR IID
+resumes one agent session. An open, a new commit, and a later mention
+therefore share the same conversation.
+
+## Call GitLab through `ctx.gitlab`
 
-Filter note hooks by author before starting a turn. This prevents comments
-posted by the agent from triggering another turn.
+Each hook receives a GitLab client already bound to the project from
+the verified delivery. Use `ctx.gitlab.request()` for REST calls,
+`setCommitStatus()` for one status update, or `createCheck()` when you
+need a status handle that changes throughout longer work.
 
-`ctx.gitlab` can call the project REST API and create commit statuses. See the
-[Channels reference](../reference/channels.md) for hook return values and
-session behavior.
+The project does not come from model output. Keep API calls on this
+bound client so the event decides where reads and writes go.
 
-## Connect GitLab
+## Connect
 
-On Cursor-managed hosting, use the signed-in Cursor account:
+On Cursor-managed hosting, use the signed-in Cursor account and list
+the GitLab.com projects that may wake the agent:
 
 ```ts
 export default gitlabChannel({
@@ -44,54 +244,53 @@ export default gitlabChannel({
 });
 ```
 
-For direct webhooks, set a project hook secret and API token:
+`cursorAccount` covers event delivery and API calls made through
+`ctx.gitlab` inside hooks. The `postMergeRequestNote` and
+`setPipelineTriageStatus` wrappers are separate REST clients, so
+configure their GitLab API credential too.
 
-```bash
-GITLAB_WEBHOOK_SECRET=...
-GITLAB_TOKEN=...
-```
-
-Add a project webhook for
-`https://<your-host>/<slug>/v1/channels/gitlab`. Use the same value for the
-GitLab secret token and `GITLAB_WEBHOOK_SECRET`. The channel checks
-`X-Gitlab-Token` before it parses the payload.
-
-Self-managed GitLab also needs its REST API base:
+For direct webhooks or self-managed GitLab, configure the project hook
+secret, API token, and allowed projects. Add the API base for a
+self-managed host:
 
 ```ts
 export default gitlabChannel({
-  apiBaseUrl: "https://gitlab.example.com/api/v4",
   projects: ["acme/platform"],
+  webhookSecret: () => process.env.GITLAB_WEBHOOK_SECRET,
+  token: () => process.env.GITLAB_TOKEN ?? "",
+  apiBaseUrl: "https://gitlab.example.com/api/v4",
 });
 ```
 
-You can set `GITLAB_API_BASE_URL` instead.
+Without `webhookSecret`, the direct production route stays
+loopback-only. Setting it admits deliveries that carry the matching
+project-hook secret; `token` authorizes the API reads and writes in the
+examples.
+
+Register the project webhook at
+`https://<your-host>/<slug>/v1/channels/gitlab` with the same secret.
+For GitLab.com, omit `apiBaseUrl`.
 
 ## Test locally
 
-Start the agent, then replay a merge request you can read:
+Replay lets you exercise the same channel hooks with a merge request
+you can read before registering a live project webhook.
 
 ```bash
 agent-sdk dev
 agent-sdk gitlab replay \
-  https://gitlab.example.com/acme/platform/-/merge_requests/42
-```
-
-`GITLAB_TOKEN` needs API read access. Replay reads the merge request,
-creates GitLab-shaped payloads, and sends them through the same channel route.
-Use `--events '*'` to replay the supported events declared by the channel.
-Use `--dry-run --out fixtures/gitlab` to save fixtures.
-
-```bash
-agent-sdk gitlab events --dir .
-agent-sdk gitlab forward --dir .
+  https://gitlab.example.com/acme/platform/-/merge_requests/42 \
+  --events '*'
 ```
 
-GitLab has no local webhook relay. `forward` prints the project-hook and HTTPS
-tunnel setup for live deliveries.
+Use `--dry-run --out fixtures/gitlab` to save the payloads instead of
+posting them. `GITLAB_TOKEN` needs read access to the merge request.
 
 ## Related
 
-- [Channels reference](../reference/channels.md)
-- [Webhooks and custom channels](./webhooks.md)
-- [Evals](../evals.md)
+- [Channels reference](../reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](./webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](../evals.md): turn saved GitLab payloads into regression
+  fixtures

package/docs/guides/grokbot-agents.md

@@ -1,22 +1,23 @@
 ---
 title: "Cursor Grok Bot agents"
-description: "Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval."
+description: "Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."
 ---
 
-# Cursor Grok Bot agents
+# Grok Bot agents
 
-The `cursor-grokbot-agents` extension lets an agent send a message to
-one of your Grok Bot agents and read the reply. The Grok Bot keeps its
-own conversation, memory, and tools. Your agent stays where it is and
-consults that bot the way you would in the Grok Bot app.
+The `cursor-grokbot-agents` extension lets an Agent SDK agent consult
+the Grok Bot agents on its serve host's Cursor account. The bot keeps
+its existing conversation, memory, and tools, while your agent carries
+the delivered reply back into the current conversation.
 
-This is different from moving this agent's turns onto a hosted Grok Bot.
-The extension keeps the agent where it is and lets it talk to *other*
-Grok Bot agents.
+Use this extension on the local runtime. It consults another Grok Bot;
+it does not move this agent onto a Grok Bot runtime.
 
 ## Mount it
 
-The extension ships with `@cursor/july`. Mount it with one file.
+List the bots your agent may contact and decide whether each new message
+needs approval. Descriptions teach the model when to choose one bot over
+another.
 
 ```ts
 // agent/extensions/grokbot.ts
@@ -24,70 +25,122 @@ import cursorGrokBotAgents from "@cursor/july/extensions/cursor-grokbot-agents";
 
 export default cursorGrokBotAgents({
   agents: [
-    { name: "Plan Keeper", description: "Keeps or moves outdoor plans." },
-    { name: "Chief of Staff", description: "Routes work and tracks priorities." },
+    {
+      name: "Plan Keeper",
+      description: "Decides whether outdoor plans should move.",
+    },
+    {
+      name: "Chief of Staff",
+      description: "Routes work and tracks priorities.",
+    },
   ],
+  needsApproval: true,
 });
 ```
 
-`agents` is the allowlist. List every Grok Bot the model may talk to;
-a name outside the list is refused. Calls run under the host's
-signed-in account (`agent-sdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`). Keep approval on when you can't.
-
-Start from the [Grok Bot agents template](../templates/grokbot-agents.md)
-when you want a project that already mounts this.
-
-## What the agent can do
-
-With the extension mounted, the agent can consult a Grok Bot and stay
-in its own conversation:
-
-- **Ask.** Send a self-contained message to a Grok Bot by the name
-  shown in the Grok Bot app. The message lands in your conversation
-  with that bot. The tool waits for the bot's reply.
-- **Keep waiting.** A long turn returns `status: "running"`. Call check
-  with the same name to read what arrived since the last look.
-- **Stop a turn.** Interrupt the bot's current work. The conversation
-  stays; a later ask continues it.
-- **See who you can talk to.** List the configured bots and the ones
-  this caller has already asked. Add a name to `agents` when you want
-  the model to reach another bot.
-
-A skill teaches the model when to bring a Grok Bot in, how to write a
-message the bot can act on alone, and how to wait or interrupt. The
-reply is what the Grok Bot sent to the person. If a turn finishes with
-no reply, the bot sent nothing; ask again with a clearer request, or
-open the bot in the Grok Bot app.
-
-The tools reach Grok Bot agents on the signed-in account. A bot another
-user owns is out of reach. That separation is only as fine as your
-host's auth; a shared bearer token or `--allow-anonymous` makes every
-caller one principal, so use
-[authored auth](../reference/channels.md#auth-policies) when callers
-need their own.
+Mounted as `grokbot`, the extension contributes `grokbot__ask`,
+`grokbot__check`, `grokbot__interrupt`, and `grokbot__list`, plus
+guidance for consulting them.
+
+You can also scaffold the packaged example:
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+## Ask a named bot
+
+When someone says, "Ask Plan Keeper whether we should move the picnic,"
+your agent prepares one self-contained message, requests approval, and
+waits for the bot's delivered reply. That reply appears in the current
+conversation as the consultation result.
+
+The message must include who is asking, the relevant facts, and the
+shape of the answer. The Grok Bot does not see the current Agent SDK
+conversation.
+
+> Netto is deciding whether to move Saturday's picnic. The forecast is
+> 70% rain from 1-4pm. Recommend keep or move, give one reason, and name
+> the best alternate time.
+
+When exactly one bot is configured, the model may omit its name.
+
+## Keep waiting for a long reply
+
+If the bot is still working when `ask` reaches its wait limit, the tool
+returns `status: "running"` and any reply received so far. Your agent
+calls `check` for the same bot and reports the final answer when it
+arrives.
+
+`check` advances this caller's read position, so it returns only replies
+not already consumed. Check when the answer is needed instead of
+polling in a tight loop.
+
+Earlier unread replies can arrive alongside the current result. Keep
+their order and pass them on when they still matter.
+
+## Interrupt a bot turn
+
+Use `interrupt` when the bot is pursuing the wrong task or the person
+changes direction. The active turn stops, but the host account's
+conversation with that bot remains, so a later `ask` continues with its
+existing memory.
+
+> Stop Plan Keeper's current turn. Then ask it to compare indoor venues
+> instead of changing the time.
+
+Only `ask` uses `needsApproval`. `check` and `interrupt` execute without
+an approval card, so expose this extension only to callers who may read
+or stop those bot conversations.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `agents` | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
-| `needsApproval` | Park asks for a [human decision](./human-in-the-loop.md). Defaults to `true` when no `agents` are configured, `false` otherwise. |
-| `apiKey` | A Cursor API key to call with instead of the host's own. |
+`agents` is a name allowlist, not an existence check. A name outside the
+list is refused, but a misspelled configured name may create a new empty
+bot on first use. If a result says `created: true`, tell the person and
+check the name before sending more work.
+
+With no `agents` list, any name is allowed and approval defaults on.
+Prefer an explicit list for a shared agent. `list` returns configured
+bots and bots this caller already contacted; it does not enumerate the
+whole account.
+
+Calls use the serve host credential: `CURSOR_API_KEY`,
+`CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, or
+`agent-sdk login`. Use `apiKey` only when the extension should run under
+a different account.
+
+`pollIntervalMs` changes how often a waiting tool reads for new bot
+output. Keep the default unless the service needs a different balance
+between response latency and request volume.
+
+## Account and caller boundaries
+
+Every tool reaches the serve host account's existing Grok Bot
+conversation. Authenticated Agent SDK callers have separate contact
+lists and read positions, but they do not get separate Grok Bot accounts
+or isolated bot memory.
+
+A shared bearer token or anonymous host also collapses callers into one
+Agent SDK principal. Use per-caller auth when contact history and read
+positions must remain separate.
+
+If `ask` finds the bot busy with an earlier message, it sends nothing.
+For a bot this caller already contacted, use `check` or `interrupt`.
+On first contact, wait for the existing turn in the Grok Bot app to
+finish, then ask again.
 
 ## Adjust it
 
-To take a capability away, such as interrupting a turn, mount as a
-directory and disable that tool; see
-[overlays](../reference/extensions.md#adjust-a-mounted-extension).
+To remove a capability such as `interrupt`, mount the extension as a
+directory and disable that tool. See
+[Adjust a mounted extension](../reference/extensions.md#adjust-a-mounted-extension).
 
 ## What's next
 
-Continue with these pages:
-
-- [Grok Bot agents template](../templates/grokbot-agents.md): scaffold
-  an agent that already mounts this
-- [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
-  asks get approved
+- [Extensions](../reference/extensions.md): namespaces, trust, and
+  overlays
+- [Tool approvals](../reference/tools.md#gate-a-tool-on-human-approval):
+  approve asks
+- [Agent config](../reference/agent-config.md#choose-a-runtime): local
+  and hosted runtimes