@cursor/july 0.1.99 → 0.1.100

package/docs/guides/github.md

@@ -11,7 +11,7 @@ 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).
+[`skills/github/SKILL.md`](../skills/github.md).
 
 ## Pull events from Cursor
 

package/docs/guides/mcp-oauth.md

@@ -13,7 +13,7 @@ deployment as secrets so prod can reconnect after a redeploy. Hosted
 Connect lets the current process retry.
 
 The companion skill is
-[`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
 
 ## What can host MCP OAuth do?
 

package/docs/guides/opentelemetry.md

@@ -91,7 +91,7 @@ You can also pass the same object to `serve(dir, { otel })`. Precedence
 is `serve({ otel })` over `agent/otel.ts` over env. An empty
 `defineOtel()` still enables export when `OTEL_EXPORTER_OTLP_*` is set.
 
-The companion skill is [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md).
+The companion skill is [`skills/otel/SKILL.md`](../skills/otel.md).
 
 ## What spans does a session produce?
 
@@ -206,7 +206,7 @@ through `serve({ otel })` or env.
 
 ## What's next
 
-- [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md): compact
+- [`skills/otel/SKILL.md`](../skills/otel.md): compact
   `defineOtel` reference for coding agents
 - [Hooks](../reference/hooks.md): observe the same session event stream
   in-process

package/docs/guides/slack.md

@@ -12,7 +12,7 @@ Replies stream there, with thinking steps and suggested prompts.
 Use `agent-sdk slack create` when Cursor should own the Slack app. Use
 `agent-sdk slack init --manual` when you own it. Commands and flags live
 in the [CLI reference](../reference/cli.md#slack). Coding agents should
-follow [`skills/setup-slack/SKILL.md`](../../skills/setup-slack/SKILL.md).
+follow [`skills/setup-slack/SKILL.md`](../skills/setup-slack.md).
 
 ## Define the channel
 
@@ -55,6 +55,85 @@ export default slackChannel({
 });
 ```
 
+## Choose how the reply arrives
+
+Slack gives an agent two places to show progress while a turn runs: the
+status chip under the thread ("Running grep…") and the reply message
+itself. It won't fill both at once. While a message is streaming, Slack
+shows its own "is working…" chip and hides any status text you set. Cards
+only exist inside a streamed message. `reply.mode` picks which one you get.
+
+### `post` (default): status chip, then one message
+
+Tool calls and the first line of each reasoning block show in the chip as
+they happen. The answer lands as a single message when the turn finishes.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "post",
+    status: {
+      reasoning: true,
+      tools: true,
+      idle: ["Checking the monorepo…", "Poking Datadog…"],
+    },
+  },
+});
+```
+
+`idle` is the rotation Slack cycles through when nothing more specific is
+known, up to 5 lines of 50 characters. Pass a function to `tools` to write
+your own line from the calls in flight.
+
+### `stream`: live text, with cards
+
+The answer streams into one message as the model writes it. Slack owns the
+chip for the duration, so live feedback inside the message comes from
+cards. Both are off unless you turn them on.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "stream",
+    reasoningCard: true,
+    toolCards: { group: "per-tool" },
+  },
+  toolLabels: { grep: "Searching code", read: "Reading files" },
+});
+```
+
+The reasoning card is one task card, titled "Thinking", that receives the
+model's reasoning as it streams and completes when the answer text starts.
+`maxChars` (default 1500) caps how much it collects. Slack caps a streamed
+message near 12k characters including cards; when an answer outgrows that,
+the streamed message closes where it stands and the rest continues in a
+new message.
+
+Tool cards default to one card per tool name with a call count in the title
+(`grep ×3`), updated in place as calls finish. `group: "per-call"` shows one
+card per call instead.
+
+Cards are collapsible by default: each call adds one line under the title,
+the same summary the playground shows in a tool's header (the grep pattern,
+the file path, the shell command), and the group expands the same way the
+reasoning card does. `collapsible: false` keeps cards to their titles. On a
+collapsible card, `details(call)` returns the line to add when a call starts
+and `output(result)` the text to add when it finishes.
+
+`toolLabels` renames tools everywhere they appear: the chip, card titles,
+and the default `Running …` line.
+
+### Migrating from `streaming` and `thinkingSteps`
+
+`streaming: false` is `reply: { mode: "post" }`. `streaming: true` is
+`reply: { mode: "stream", toolCards: { group: "per-call", collapsible:
+false } }`, the title-only cards it used to show. `loadingMessages` moves
+to `reply.status.idle`. The old options still work and `agent-sdk validate`
+prints the rewrite for each one.
+
+A channel that set none of these used to stream. It now posts. Set
+`reply: { mode: "stream" }` to keep streaming.
+
 ## Set it up
 
 `slack create` opens the Cursor dashboard wizard. Finish Slack consent

package/docs/hillclimbing.md

@@ -22,7 +22,7 @@ flowchart LR
 
 ## How do I hillclimb an agent with a coding agent?
 
-Have Cursor read [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md).
+Have Cursor read [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md).
 
 Tell it:
 
@@ -36,10 +36,10 @@ Other skills cover the edges:
 
 | When you need… | Skill |
 | --- | --- |
-| The measured improvement loop | [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md) |
-| An eval that locks a kept win | [`skills/evals/SKILL.md`](../skills/evals/SKILL.md) |
-| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](../skills/github/SKILL.md) |
-| A run that misbehaves | [`skills/debug/SKILL.md`](../skills/debug/SKILL.md) |
+| The measured improvement loop | [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md) |
+| An eval that locks a kept win | [`skills/evals/SKILL.md`](./skills/evals.md) |
+| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](./skills/github.md) |
+| A run that misbehaves | [`skills/debug/SKILL.md`](./skills/debug.md) |
 
 See [Building agents with agents](./building-with-agents.md) for every framework skill and a good first prompt.
 

package/docs/quickstart.md

@@ -13,7 +13,7 @@ review. Add GitHub event handling so pull requests can trigger reviews.
 
 - **Get started with an agent in Cursor:** follow
   [Scaffold an agent with Cursor](./scaffolding-agents.md) and ask Cursor
-  to read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md).
+  to read [`skills/create-agent/SKILL.md`](./skills/create-agent.md).
 - **Get started in the CLI:** continue below.
 
 ## Prerequisites

package/docs/reference/connections.md

@@ -54,7 +54,7 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 ```
 
 Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
-skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
+skill: [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
 
 Account MCP (`cursorAccount: true`) is the right choice for connectors
 already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)

package/docs/scaffolding-agents.md

@@ -11,7 +11,7 @@ decision.
 ## What does the create-agent skill do?
 
 The bundled
-[`create-agent` skill](../skills/create-agent/SKILL.md) turns your goal
+[`create-agent` skill](./skills/create-agent.md) turns your goal
 into a small working project. Have Cursor read that file and follow it.
 
 Where to find the file depends on how you got the package:
@@ -26,7 +26,7 @@ Where to find the file depends on how you got the package:
 - Installed `@cursor/july` as a dependency? The skill also ships inside
   the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
 - Working from this package's source? The skill is at
-  [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md). Run
+  [`skills/create-agent/SKILL.md`](./skills/create-agent.md). Run
   `agent-sdk install-skills` if you want the same copies in
   `~/.cursor/skills/agentsdk/` (the package postinstall skips the
   source checkout).
@@ -119,7 +119,7 @@ without a Cursor credential. Model turns and evals need
 
 Choose one to three fixed inputs, define what should improve, and name
 what must stay unchanged. Then have Cursor follow
-[`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md).
+[`skills/hillclimb/SKILL.md`](./skills/hillclimb.md).
 
 The hillclimb skill measures a baseline, changes one lever, runs the same
 inputs again, and adds an eval for each improvement you keep.

package/docs/skills/index.md

@@ -0,0 +1,26 @@
+---
+title: "Coding-agent skills"
+description: "Task guides that ship with the Agent SDK for scaffolding, evals, channels, and hillclimbing."
+---
+
+# Coding-agent skills
+
+Each skill is a procedure a coding agent can follow. Installing
+`@cursor/july` copies them into `~/.cursor/skills/agentsdk/`. This site
+publishes the same files.
+
+See [Building agents with agents](../building-with-agents.md) for when
+to use each one.
+
+| Skill | Use it to |
+| --- | --- |
+| [framework-map](./framework-map.md) | Learn the project layout and runtimes |
+| [create-agent](./create-agent.md) | Scaffold and verify a new agent |
+| [evals](./evals.md) | Write fixtures and regression checks |
+| [ab](./ab.md) | Compare variants on live traffic |
+| [otel](./otel.md) | Export OpenTelemetry traces |
+| [hillclimb](./hillclimb.md) | Improve an agent against fixed inputs |
+| [github](./github.md) | Add GitHub webhooks and replay events |
+| [setup-slack](./setup-slack.md) | Connect an agent to Slack |
+| [mcp-auth](./mcp-auth.md) | Authorize host MCP OAuth |
+| [debug](./debug.md) | Diagnose a local run |

package/docs/troubleshooting.md

@@ -74,7 +74,7 @@ not on `PATH`, use `npx @cursor/july`.
 | Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) and
-[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](./skills/mcp-auth.md).
 
 ## What if a secret showed up in a terminal transcript?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.99",
+  "version": "0.1.100",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/channels/github/defaults.ts

@@ -27,9 +27,18 @@ export function buildDefaultGitHubEvents(
   options: BuildDefaultGitHubEventsOptions = {}
 ): ChannelEventHandlers<GitHubChannelState> {
   const deliverReplies = options.deliverReplies !== false;
+  const requiredSuccessfulTools = new Set(
+    options.progress?.requireSuccessfulTools
+      ?.map((toolName) => toolName.trim())
+      .filter((toolName) => toolName !== "") ?? []
+  );
+  const toolOutcomesBySession = new Map<string, Map<string, boolean>>();
 
   return {
-    async "turn.started"(_event, channel) {
+    async "turn.started"(event, channel) {
+      if (requiredSuccessfulTools.size > 0) {
+        toolOutcomesBySession.set(event.sessionId, new Map());
+      }
       await applyGitHubProgress({
         phase: "pending",
         channel,
@@ -52,9 +61,31 @@ export function buildDefaultGitHubEvents(
       }
     },
 
-    async "turn.completed"(_event, channel) {
+    async "action.result"(event) {
+      if (
+        event.data.parentCallId !== undefined ||
+        !requiredSuccessfulTools.has(event.data.toolName)
+      ) {
+        return;
+      }
+      const outcomes = toolOutcomesBySession.get(event.sessionId) ?? new Map();
+      outcomes.set(
+        event.data.toolName,
+        !event.data.isError && event.data.stubbed !== true
+      );
+      toolOutcomesBySession.set(event.sessionId, outcomes);
+    },
+
+    async "turn.completed"(event, channel) {
+      const outcomes = toolOutcomesBySession.get(event.sessionId);
+      const pipelineSucceeded =
+        requiredSuccessfulTools.size === 0 ||
+        [...requiredSuccessfulTools].every(
+          (toolName) => outcomes?.get(toolName) === true
+        );
+      toolOutcomesBySession.delete(event.sessionId);
       await applyGitHubProgress({
-        phase: "success",
+        phase: pipelineSucceeded ? "success" : "failure",
         channel,
         options,
       });
@@ -82,6 +113,7 @@ export function buildDefaultGitHubEvents(
     },
 
     async "turn.failed"(event, channel) {
+      toolOutcomesBySession.delete(event.sessionId);
       await applyGitHubProgress({
         phase: "failure",
         channel,
@@ -91,6 +123,7 @@ export function buildDefaultGitHubEvents(
     },
 
     async "session.failed"(event, channel) {
+      toolOutcomesBySession.delete(event.sessionId);
       await applyGitHubProgress({
         phase: "failure",
         channel,

package/src/channels/github/progress.ts

@@ -35,6 +35,13 @@ export type GitHubBannerProgress = GitHubProgressPhaseCopy;
 export interface GitHubProgressConfig {
   /** When false, skip the eyes reaction on turn.started. Defaults to true. */
   reactions?: boolean;
+  /**
+   * Top-level tools that must each finish successfully before a completed
+   * turn is reported as successful. A missing, stubbed, or ultimately failed
+   * tool reports failure instead. Later successful retries replace an earlier
+   * failure for the same tool.
+   */
+  requireSuccessfulTools?: readonly string[];
   /**
    * Opt-in Checks API run on the PR head. Omit or `false` keeps today's
    * behavior (no check from default events). With `cursorAccount`, enabling

package/src/channels/slack/api.ts

@@ -16,7 +16,7 @@ import {
 } from "./constants.js";
 import { tryResolveAppToken, tryResolveBotToken } from "./credentials.js";
 import { defaultSlackLog, type SlackLog } from "./log.js";
-import type { StreamTaskChunk } from "./stream.js";
+import type { StreamChunk } from "./stream.js";
 import type {
   SlackApiTransport,
   SlackBinding,
@@ -194,10 +194,18 @@ export function truncateTitle(title: string, max?: number): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Show or clear the Working chip. Agent UX ignores empty
- * `assistant.threads.setStatus`; `agents.sessions.setStatus` `active` is
- * what actually clears it. The assistant call stays for loading_messages
- * and older workspaces.
+ * Show or clear the status chip under the thread.
+ *
+ * Status text goes through `assistant.threads.setStatus` alone. The agent
+ * session is only written when clearing: Agent UX ignores an empty assistant
+ * status, so `agents.sessions.setStatus` `active` is what actually drops the
+ * chip. That same write must not accompany status text — Slack applies it
+ * asynchronously and it blanks the chip when it lands after the text, which
+ * reads as flicker between updates. A `processing` write would be worse:
+ * Agent UX paints its own generic "is working…" over the assistant text
+ * while the session is `processing`. An open `chat.startStream` also flips
+ * the session to `processing` on Slack's side, so status text only shows on
+ * non-streaming turns. The empty assistant call stays for older workspaces.
  */
 export async function setThreadStatus(args: {
   botToken: SlackBotToken | undefined;
@@ -210,21 +218,12 @@ export async function setThreadStatus(args: {
     return { ok: false, error: "missing_channel_or_thread" };
   }
   const status = truncateTypingStatus(args.status);
-  const sessionResult = await callSlackApiSoft({
-    botToken: args.botToken,
-    operation: "agents.sessions.setStatus",
-    body: {
-      channel_id: args.channelId,
-      thread_ts: args.threadTs,
-      status: status.length > 0 ? "processing" : "active",
-    },
-  });
-
   const body: Record<string, unknown> = {
     channel_id: args.channelId,
     thread_ts: args.threadTs,
     status,
   };
+
   if (status.length > 0) {
     const loadingRaw =
       args.loadingMessages !== undefined && args.loadingMessages.length > 0
@@ -237,7 +236,22 @@ export async function setThreadStatus(args: {
     if (loading_messages.length > 0) {
       body.loading_messages = loading_messages;
     }
+    return callSlackApiSoft({
+      botToken: args.botToken,
+      operation: "assistant.threads.setStatus",
+      body,
+    });
   }
+
+  const sessionResult = await callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "agents.sessions.setStatus",
+    body: {
+      channel_id: args.channelId,
+      thread_ts: args.threadTs,
+      status: "active",
+    },
+  });
   const assistantResult = await callSlackApiSoft({
     botToken: args.botToken,
     operation: "assistant.threads.setStatus",
@@ -300,7 +314,7 @@ export async function startChatStream(args: {
   channel: string;
   thread_ts?: string;
   markdown_text?: string;
-  chunks?: StreamTaskChunk[];
+  chunks?: StreamChunk[];
   recipient_user_id?: string;
   recipient_team_id?: string;
 }): Promise<SoftSlackResult<{ ts: string; channel: string }>> {
@@ -346,7 +360,7 @@ export async function appendChatStream(args: {
   channel: string;
   ts: string;
   markdown_text?: string;
-  chunks?: StreamTaskChunk[];
+  chunks?: StreamChunk[];
 }): Promise<SoftSlackResult> {
   const body: Record<string, unknown> = {
     channel: args.channel,
@@ -370,6 +384,7 @@ export async function stopChatStream(args: {
   channel: string;
   ts: string;
   markdown_text?: string;
+  chunks?: StreamChunk[];
   blocks?: unknown[];
 }): Promise<SoftSlackResult> {
   const body: Record<string, unknown> = {
@@ -379,6 +394,9 @@ export async function stopChatStream(args: {
   if (args.markdown_text !== undefined) {
     body.markdown_text = args.markdown_text;
   }
+  if (args.chunks !== undefined && args.chunks.length > 0) {
+    body.chunks = args.chunks;
+  }
   if (args.blocks !== undefined && args.blocks.length > 0) {
     body.blocks = args.blocks;
   }

package/src/channels/slack/constants.ts

@@ -13,6 +13,12 @@ export const SLACK_LOADING_MESSAGE_MAX_LEN = 50;
 /** Slack `assistant.threads.setStatus` accepts at most 5 `loading_messages`. */
 export const SLACK_LOADING_MESSAGES_MAX = 5;
 export const SLACK_TITLE_MAX_LEN = 80;
+/**
+ * `markdown_text` (and so a streamed message, cards included) tops out near
+ * 12k characters; past it Slack answers `msg_too_long`. Plain `text` allows
+ * about 40k.
+ */
+export const SLACK_MARKDOWN_TEXT_MAX_LEN = 12_000;
 
 /** Rotating assistant status lines (Slack `loading_messages`). */
 export const SLACK_DEFAULT_LOADING_MESSAGES = [