@cursor/july 0.1.1 → 0.1.3

package/AGENTS.md

@@ -139,6 +139,13 @@ export default defineEvalConfig({
   (schema-validated, in-process, no model). `--session <id>` runs it inside
   an existing session and records it on that session's event stream.
 - `init` with no directory prints this setup guide (does not scaffold).
+  `init <dir>` scaffolds (skipping existing files), runs `npm install`,
+  offers to install/update package skills into
+  `~/.cursor/skills/agentkit/` (TTY only; always overwrites with the
+  package copy), runs `login` and waits when unsigned, then prints `cd`
+  (when needed) and bare `dev`. `--json` still installs but never blocks
+  on login or skill install; it prints
+  `{ ok, directory, created, skipped, installed, installError, next }`.
 - `chat --json --message "..."` talks to a running server and prints a trajectory.
 
 ## Agent-to-agent (MCP endpoint + peer MCP connections)
@@ -168,7 +175,7 @@ instructions so A→B→A recursion cannot happen (e.g. a parent agent that
 delegates *only* weather questions to a `weather-agent` peer).
 
 ```bash
-agent-serve serve --dir ./agents --dev
+agent-serve dev ./agents
 agent-serve chat --url http://127.0.0.1:3000/concierge --message "Weather in Paris?"
 ```
 
@@ -177,7 +184,10 @@ agent-serve chat --url http://127.0.0.1:3000/concierge --message "Weather in Par
 The Cursor Slack connection is the zero-setup default
 (`slackChannel({ cursorAccount: true, agentName: "…" })`). Sign the host
 in (`agent-serve login` / `CURSOR_API_KEY`), then `@Cursor <agentName> …`
-in Slack; thread replies stay with that agent. Import from
+in Slack; thread replies stay with that agent. `agentName` must be a
+**single token** (no whitespace) — prefer PascalCase (`ApprovalBuddy`);
+multi-word names fail typecheck for string literals and throw at
+construction / serve time. Import from
 `@cursor/july/channels/slack`.
 
 Dedicated Socket Mode apps (no public Request URL) live in a second
@@ -189,7 +199,7 @@ agent-serve slack setup
 agent-serve slack init --dir ./my-agent --name "My Agent" --channel-posts
 # writes envPrefix from the directory name (MY_AGENT_SLACK_*)
 agent-serve slack doctor --prefix MY_AGENT
-agent-serve serve --dir ./my-agent --dev
+agent-serve dev ./my-agent
 ```
 
 Multi-agent Socket Mode needs **one Slack app (and token pair) per agent**:
@@ -215,8 +225,8 @@ The web playground is a Vite + React SPA under `playground/` (entry
 
 - If `dist/playground/` is missing and the local vite toolchain is present,
   serve auto-runs `vite build` before listening.
-- `serve --dev` also starts Vite HMR (default `:5273`) and prints
-  `playground (HMR): …`. Single-agent proxies `/v1` to the serve URL;
+- `serve --dev` / `dev` also starts Vite HMR (default `:5273`) and prints
+  that URL as `playground`. Single-agent proxies `/v1` to the serve URL;
   multi-agent serves the agents index at `/` and each SPA at
   `/<slug>/playground` (pin one slug with `AGENT_SERVE_BASE=/<slug>`).
 
@@ -234,7 +244,12 @@ or pinned via `webhookEvents`) as `meta.githubWebhookEvents`. Auth default: with
 a secret → `allowAll()` + signature check; without one → `localDevStrict()`,
 except under `serve --dev` which admits unsigned loopback deliveries (so
 `gh webhook forward` and fixtures work with no secret). Outbound GitHub API
-calls prefer App installation tokens (`GITHUB_APP_ID` +
+calls can reuse the signed-in Cursor connection with
+`githubChannel({ cursorAccount: { repos: ["owner/repo"] } })`; this supplies
+events plus a refreshing repo-scoped credential to `ctx.github`,
+`ctx.host.github`, and child `gh` commands in dev and hosted deployments.
+Default `permissions: "pr-write"`; opt up to `"contents-write"` only to push.
+Without `cursorAccount`, calls prefer App installation tokens (`GITHUB_APP_ID` +
 `GITHUB_APP_PRIVATE_KEY` + webhook `installation.id` or
 `GITHUB_APP_INSTALLATION_ID`); serve warmup also exports that token as
 `GH_TOKEN` for tools that shell out to `gh`. For local testing, omit App
@@ -253,7 +268,7 @@ agent-serve github events --dir ./agents --json
 
 # forward live deliveries to a served agent (no secret needed against --dev;
 # set GITHUB_WEBHOOK_SECRET to verify signatures)
-agent-serve serve --dir ./my-agent --dev &
+agent-serve dev ./my-agent &
 agent-serve github forward --dir ./my-agent
 ```
 
@@ -283,8 +298,26 @@ Fixtures still work for offline replay: `POST` a saved payload with an
 
 ## Do not
 
+- Proactively add or update documentation (`docs/`, READMEs, this file) as
+  part of a code change. Docs are written intentionally, on explicit request
+  only — never as a side effect of a feature or fix. If a change makes docs
+  stale, say so in the PR description instead of editing them unprompted.
 - Put durable `--state-root` inside a large monorepo if you care about
   ambient `AGENTS.md` / `.cursor` rules leaking into the agent workspace.
   Prefer `defineAgent({ local: { cwd } })` pointing outside the monorepo
   (session harnesses land at `<cwd>/<sessionId>`), or a temp `--state-root`.
 - Expect `agent/evals/` to be loaded — evals live at the **project root** `evals/`.
+- Build optional object fields with a conditional empty-object spread.
+  Assign the property directly; `undefined` is fine on optional keys.
+
+  ```ts
+  // ❌ BAD
+  { ...(x === undefined ? {} : { x }) }
+  { ...(cond && { x }) }
+
+  // ✅ GOOD
+  { x } // may be undefined
+  ```
+
+  Only use a conditional spread when merging a real partial object
+  (`...overrides`), not to omit an optional key.

package/README.md

@@ -53,9 +53,10 @@ my-agent/
 ```
 
 Scaffold a starter project with `agent-serve init ./my-agent` — a minimal
-agent (`package.json`, `agent/agent.ts`, `agent/instructions.md`, and a demo
-`agent/tools/echo.ts`) that serves immediately. From there, grow it folder by
-folder; the [docs](./docs/README.md) walk a weather agent from a single
+agent (`package.json`, `tsconfig.json`, `agent/agent.ts`,
+`agent/instructions.md`, and a demo `agent/tools/echo.ts`) that serves
+immediately and type-checks with `npm run check`. From there, grow it folder
+by folder; the [docs](./docs/README.md) walk a weather agent from a single
 `get_weather` tool through skills, channels, evals, and deployment.
 
 Serve one project with `agent-serve serve --dir ./my-agent --dev`, or point
@@ -79,10 +80,8 @@ one port, each under its own slug (its directory name):
 
 ```bash
 agent-serve serve --dir ./agents --dev
-# 2 agents listening on http://127.0.0.1:3000
-#   index: http://127.0.0.1:3000/
-#   /weather-agent → /weather-agent/playground, /weather-agent/v1/*
-#   /concierge    → /concierge/playground, /concierge/v1/*
+# 2 agents listening
+#   playground  http://127.0.0.1:5273
 ```
 
 `serve` always uses multi-agent layout by default: agents are mounted under
@@ -377,8 +376,8 @@ own playground at `/<slug>/playground` and `/` is an index of them all (see
 
 ### Developing the playground
 
-`serve --dev` also starts Vite HMR (default `:5273`) and prints
-`playground (HMR): …`. Single-agent proxies `/v1` to the serve URL; multi-agent
+`serve --dev` / `dev` also starts Vite HMR (default `:5273`) and prints that
+URL as `playground`. Single-agent proxies `/v1` to the serve URL; multi-agent
 serves the agents index at `/` and each SPA at `/<slug>/playground`:
 
 ```bash
@@ -927,19 +926,22 @@ Approve/Deny cards and routes Socket Mode `interactive` clicks to
 (App-Level Token with `connections:write`).
 
 Most demos under `examples/` use the Cursor Slack connection
-(`cursorAccount: true`) with a unique `agentName` — `@Cursor Benny …`,
-`@Cursor Bugbot …`, etc. Sign the host in, then mention the agent; no
-per-agent Slack app required for chat. Agents that need channel watch or
-tool approvals keep a Socket Mode app in a second channel file (e.g.
-`slack-app.ts`) with their own env prefix (`<PREFIX>_SLACK_BOT_TOKEN` +
-`<PREFIX>_SLACK_APP_TOKEN`, derived from the directory name by `slack init`).
+(`cursorAccount: true`) with a unique single-token `agentName` —
+`@Cursor Benny …`, `@Cursor Bugbot …`, `@Cursor ApprovalBuddy …`, etc.
+Sign the host in, then mention the agent; no per-agent Slack app required
+for chat. Agents that need channel watch or tool approvals keep a Socket
+Mode app in a second channel file (e.g. `slack-app.ts`) with their own env
+prefix (`<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN`, derived
+from the directory name by `slack init`).
 
 | Agent | `@Cursor` name | Optional Socket Mode app |
 | --- | --- | --- |
 | `weather-agent` | Weather | `slack-app.ts` (`WEATHER_AGENT_SLACK_*`, tool approvals) |
-| `slack-agent` | Slack Agent | — |
+| `slack-agent` | SlackAgent | — |
 | `bugbot` | Bugbot | — |
 | `fsd` | FSD | — |
+| `benny` | Benny | `slack-app.ts` (`BENNY_SLACK_*`, channel watch) |
+| `approval-buddy` | ApprovalBuddy | — |
 
 PR-oriented demos (`bugbot`, `fsd`) extract a GitHub PR URL / `owner/repo#N`
 from the mention and run the same host path as their HTTP channels.
@@ -970,7 +972,10 @@ import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
 
 export default githubChannel({
   botName: "my-agent", // or GITHUB_APP_SLUG
-  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  cursorAccount: {
+    repos: ["owner/repo"],
+    // permissions?: "read" | "pr-write" | "contents-write" (default pr-write)
+  },
   onPullRequest: (ctx, pr) =>
     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
   onCheckSuite: (ctx, suite) =>
@@ -986,13 +991,17 @@ under `serve --dev`, which admits unsigned loopback deliveries so
 `{ auth }` to start a model turn as the actor, `{ task }` for host-side work
 (202 ACK, runs past GitHub's ~10s timeout), or `null` to skip.
 
-**Testing GitHub agents locally.** API auth prefers GitHub App installation
-tokens when `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` (and an installation id)
-are set; for local testing you can omit those and use `GITHUB_TOKEN` /
-`GH_TOKEN` or `gh auth login` instead. The channel publishes the webhook events
-it dispatches on (derived from the declared hooks, or pinned via
-`webhookEvents`), so `agent-serve github …` can forward live deliveries with
-zero hand-listing — it wraps [`gh webhook
+**Testing GitHub agents locally.** `cursorAccount` reuses `agent-serve login`
+for both Cursor SCM events and a refreshing repo-scoped GitHub credential used
+by `ctx.github`, `ctx.host.github`, and child `gh` commands. Default
+`permissions: "pr-write"` covers comments without `contents:write`; opt up to
+`"contents-write"` only when the agent must push. Without `cursorAccount`, API
+auth prefers GitHub App installation tokens when `GITHUB_APP_ID` /
+`GITHUB_APP_PRIVATE_KEY` (and an installation id) are set, then falls back to
+`GITHUB_TOKEN` / `GH_TOKEN` or `gh auth login`. The channel publishes the
+webhook events it dispatches on (derived from the declared hooks, or pinned
+via `webhookEvents`), so `agent-serve github …` can forward live
+deliveries with zero hand-listing — it wraps [`gh webhook
 forward`](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing):
 
 ```bash

package/dist/bin/agent-serve.d.ts

@@ -3,10 +3,12 @@
  * agent-serve CLI.
  *
  *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
+ *   agent-serve dev        [path] [--port 3000] [--host 127.0.0.1]
  *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
+ *   agent-serve resume    <sessionId> [--url | --prod] [--message "..."]
  *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
  *   agent-serve trajectory --events <file.ndjson>
- *   agent-serve init      [dir]
+ *   agent-serve init      [dir] [--json]
  *   agent-serve eval        [--dir .] [evalId...]
  *   agent-serve validate   [--dir .]
  *   agent-serve slack     <subcommand>

package/dist/bin/agent-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-serve.d.ts","sourceRoot":"","sources":["../../src/bin/agent-serve.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}
+{"version":3,"file":"agent-serve.d.ts","sourceRoot":"","sources":["../../src/bin/agent-serve.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}