@cursor/july 0.1.73 → 0.1.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/AGENTS.md +13 -8
  2. package/dist/bin/agent-serve.js +7 -5
  3. package/dist/channels/checks.d.ts +111 -0
  4. package/dist/channels/checks.d.ts.map +1 -0
  5. package/dist/channels/checks.js +86 -0
  6. package/dist/channels/deployments/deployments-channel.d.ts +44 -0
  7. package/dist/channels/deployments/deployments-channel.d.ts.map +1 -0
  8. package/dist/channels/deployments/deployments-channel.js +92 -0
  9. package/dist/channels/deployments/index.d.ts +26 -0
  10. package/dist/channels/deployments/index.d.ts.map +1 -0
  11. package/dist/channels/deployments/index.js +25 -0
  12. package/dist/channels/deployments/types.d.ts +69 -0
  13. package/dist/channels/deployments/types.d.ts.map +1 -0
  14. package/dist/channels/deployments/types.js +6 -0
  15. package/dist/channels/github/checks.d.ts +13 -48
  16. package/dist/channels/github/checks.d.ts.map +1 -1
  17. package/dist/channels/github/checks.js +56 -64
  18. package/dist/channels/origin/api.d.ts +100 -0
  19. package/dist/channels/origin/api.d.ts.map +1 -0
  20. package/dist/channels/origin/api.js +225 -0
  21. package/dist/channels/origin/binding.d.ts +44 -0
  22. package/dist/channels/origin/binding.d.ts.map +1 -0
  23. package/dist/channels/origin/binding.js +45 -0
  24. package/dist/channels/origin/checks.d.ts +107 -0
  25. package/dist/channels/origin/checks.d.ts.map +1 -0
  26. package/dist/channels/origin/checks.js +145 -0
  27. package/dist/channels/origin/index.d.ts +3 -0
  28. package/dist/channels/origin/index.d.ts.map +1 -1
  29. package/dist/channels/origin/index.js +3 -0
  30. package/dist/channels/origin/origin-channel.d.ts +4 -4
  31. package/dist/channels/origin/origin-channel.d.ts.map +1 -1
  32. package/dist/channels/origin/origin-channel.js +12 -2
  33. package/dist/channels/origin/types.d.ts +36 -0
  34. package/dist/channels/origin/types.d.ts.map +1 -1
  35. package/dist/channels.d.ts +1 -0
  36. package/dist/channels.d.ts.map +1 -1
  37. package/dist/channels.js +1 -0
  38. package/dist/docs/404.html +2 -2
  39. package/dist/docs/ab.html +3 -3
  40. package/dist/docs/assets/{app.CdbcFD8T.js → app.b8bhB2SV.js} +1 -1
  41. package/dist/docs/assets/chunks/@localSearchIndexroot.DGZeXVqn.js +1 -0
  42. package/dist/docs/assets/chunks/{VPLocalSearchBox.D_NKImM7.js → VPLocalSearchBox.lLSeIyWw.js} +1 -1
  43. package/dist/docs/assets/chunks/{theme.CMvz7cu9.js → theme.C_owesa-.js} +2 -2
  44. package/dist/docs/assets/{reference_channels.md.MN8iDy8V.js → reference_channels.md.G5GysZ7e.js} +2 -2
  45. package/dist/docs/assets/{reference_channels.md.MN8iDy8V.lean.js → reference_channels.md.G5GysZ7e.lean.js} +1 -1
  46. package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.js → reference_cli.md.TAaYU8br.js} +3 -3
  47. package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.lean.js → reference_cli.md.TAaYU8br.lean.js} +1 -1
  48. package/dist/docs/assets/scaffolding-agents.md.CiGsJ1aw.js +1 -0
  49. package/dist/docs/assets/{scaffolding-agents.md.CrWSA0Ko.lean.js → scaffolding-agents.md.CiGsJ1aw.lean.js} +1 -1
  50. package/dist/docs/building-with-agents.html +3 -3
  51. package/dist/docs/concepts.html +3 -3
  52. package/dist/docs/deployment.html +3 -3
  53. package/dist/docs/evals.html +3 -3
  54. package/dist/docs/example-agents/approval-buddy.html +3 -3
  55. package/dist/docs/example-agents/benny.html +3 -3
  56. package/dist/docs/example-agents/bugbot.html +3 -3
  57. package/dist/docs/example-agents/codebase-wiki.html +3 -3
  58. package/dist/docs/example-agents/codeowners-review.html +3 -3
  59. package/dist/docs/example-agents/concierge.html +3 -3
  60. package/dist/docs/example-agents/fsd.html +3 -3
  61. package/dist/docs/example-agents/index.html +3 -3
  62. package/dist/docs/example-agents/knowledge-base.html +3 -3
  63. package/dist/docs/example-agents/oncall.html +3 -3
  64. package/dist/docs/example-agents/security-reviewer.html +3 -3
  65. package/dist/docs/example-agents/slack-agent.html +3 -3
  66. package/dist/docs/example-agents/weather-agent.html +3 -3
  67. package/dist/docs/guides/agent-to-agent.html +3 -3
  68. package/dist/docs/guides/cloud-runtime.html +3 -3
  69. package/dist/docs/guides/convert-automation.html +3 -3
  70. package/dist/docs/guides/github.html +3 -3
  71. package/dist/docs/guides/human-in-the-loop.html +3 -3
  72. package/dist/docs/guides/mcp-oauth.html +3 -3
  73. package/dist/docs/guides/opentelemetry.html +3 -3
  74. package/dist/docs/guides/slack.html +3 -3
  75. package/dist/docs/guides/webhooks.html +3 -3
  76. package/dist/docs/hashmap.json +1 -1
  77. package/dist/docs/hillclimbing.html +3 -3
  78. package/dist/docs/index.html +3 -3
  79. package/dist/docs/quickstart.html +3 -3
  80. package/dist/docs/reference/agent-config.html +3 -3
  81. package/dist/docs/reference/artifacts.html +3 -3
  82. package/dist/docs/reference/channels.html +5 -5
  83. package/dist/docs/reference/cli.html +6 -6
  84. package/dist/docs/reference/connections.html +3 -3
  85. package/dist/docs/reference/hooks.html +3 -3
  86. package/dist/docs/reference/http-api.html +3 -3
  87. package/dist/docs/reference/instructions.html +3 -3
  88. package/dist/docs/reference/playground.html +3 -3
  89. package/dist/docs/reference/project-layout.html +3 -3
  90. package/dist/docs/reference/prompt.html +3 -3
  91. package/dist/docs/reference/schedules.html +3 -3
  92. package/dist/docs/reference/sessions.html +3 -3
  93. package/dist/docs/reference/skills.html +3 -3
  94. package/dist/docs/reference/subagents.html +3 -3
  95. package/dist/docs/reference/tools.html +3 -3
  96. package/dist/docs/scaffolding-agents.html +5 -5
  97. package/dist/docs/storage.html +3 -3
  98. package/dist/docs/templates/agentic-owners.html +3 -3
  99. package/dist/docs/templates/demo.html +3 -3
  100. package/dist/docs/templates/pr-autofixer.html +3 -3
  101. package/dist/docs/templates/security-reviewer.html +3 -3
  102. package/dist/docs/templates/triage.html +3 -3
  103. package/dist/docs/troubleshooting.html +3 -3
  104. package/dist/internal/cli-skills.d.ts +4 -2
  105. package/dist/internal/cli-skills.d.ts.map +1 -1
  106. package/dist/internal/cli-skills.js +8 -3
  107. package/dist/internal/cursor-deployment-relay.d.ts +77 -0
  108. package/dist/internal/cursor-deployment-relay.d.ts.map +1 -0
  109. package/dist/internal/cursor-deployment-relay.js +201 -0
  110. package/dist/internal/distribution.d.ts.map +1 -1
  111. package/dist/internal/distribution.js +1 -0
  112. package/dist/internal/install-cursor-skills.d.ts +71 -16
  113. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  114. package/dist/internal/install-cursor-skills.js +160 -48
  115. package/dist/internal/sdk-runner.d.ts.map +1 -1
  116. package/dist/internal/sdk-runner.js +6 -2
  117. package/dist/internal/server.d.ts.map +1 -1
  118. package/dist/internal/server.js +114 -5
  119. package/dist/playground/assets/index-BJy9UJrF.js +85 -0
  120. package/dist/playground/assets/index-BrSd5vff.css +1 -0
  121. package/dist/playground/index.html +2 -2
  122. package/docs/reference/channels.md +15 -0
  123. package/docs/reference/cli.md +16 -8
  124. package/docs/scaffolding-agents.md +14 -6
  125. package/package.json +9 -1
  126. package/scripts/install-cursor-skills.mjs +36 -0
  127. package/skills/ab/SKILL.md +1 -1
  128. package/skills/create-agent/SKILL.md +1 -1
  129. package/skills/debug/SKILL.md +1 -1
  130. package/skills/evals/SKILL.md +1 -1
  131. package/skills/framework-map/SKILL.md +1 -1
  132. package/skills/github/SKILL.md +1 -1
  133. package/skills/hillclimb/SKILL.md +1 -1
  134. package/skills/mcp-auth/SKILL.md +1 -1
  135. package/skills/otel/SKILL.md +1 -1
  136. package/skills/setup-slack/SKILL.md +1 -1
  137. package/src/bin/agent-serve.ts +7 -5
  138. package/src/channels/checks.ts +185 -0
  139. package/src/channels/deployments/deployments-channel.ts +109 -0
  140. package/src/channels/deployments/index.ts +26 -0
  141. package/src/channels/deployments/types.ts +80 -0
  142. package/src/channels/github/checks.ts +90 -115
  143. package/src/channels/origin/api.ts +318 -0
  144. package/src/channels/origin/binding.ts +96 -0
  145. package/src/channels/origin/checks.ts +250 -0
  146. package/src/channels/origin/index.ts +3 -0
  147. package/src/channels/origin/origin-channel.ts +18 -6
  148. package/src/channels/origin/types.ts +37 -0
  149. package/src/channels.ts +16 -0
  150. package/src/internal/cli-skills.ts +10 -2
  151. package/src/internal/cursor-deployment-relay.ts +274 -0
  152. package/src/internal/distribution.ts +1 -0
  153. package/src/internal/install-cursor-skills.ts +204 -49
  154. package/src/internal/sdk-runner.ts +6 -3
  155. package/src/internal/server.ts +149 -0
  156. package/dist/docs/assets/chunks/@localSearchIndexroot.DQad--_z.js +0 -1
  157. package/dist/docs/assets/scaffolding-agents.md.CrWSA0Ko.js +0 -1
  158. package/dist/playground/assets/index-77uhu5Kr.css +0 -1
  159. package/dist/playground/assets/index-D4buox4m.js +0 -85
package/dist/playground/index.html CHANGED
@@ -8,8 +8,8 @@
8
8
  />
9
9
  <meta name="viewport" content="width=device-width, initial-scale=1" />
10
10
  <title>agent-serve playground</title>
11
- <script type="module" crossorigin src="./assets/index-D4buox4m.js"></script>
12
- <link rel="stylesheet" crossorigin href="./assets/index-77uhu5Kr.css">
11
+ <script type="module" crossorigin src="./assets/index-BJy9UJrF.js"></script>
12
+ <link rel="stylesheet" crossorigin href="./assets/index-BrSd5vff.css">
13
13
  </head>
14
14
  <body>
15
15
  <div id="root"></div>
package/docs/reference/channels.md CHANGED
@@ -217,6 +217,21 @@ replay and live forwarding. Author `agent/channels/github.ts` with
217
217
  converge a merge-box check and sticky PR comment from default stream
218
218
  events. Guide: [GitHub](../guides/github.md).
219
219
 
220
+ **Deployments** (`@cursor/july/channels/deployments`): pull transport
221
+ over `/v0/deployment-events`. Subscribe per repository with `repos`,
222
+ narrow with `environments` / `events`, and handle each event in
223
+ `onEvent`. `repos` must match `Deployment.repository` as your deployment
224
+ writer records it; the field has no format, and matching is
225
+ case-insensitive but otherwise literal.
226
+ Author `agent/channels/deployments.ts` with `deploymentsChannel()`. The
227
+ serve host discovers every mounted deployments channel, runs one relay
228
+ for the process against the union of their repositories, and routes each
229
+ event to the channels that asked for it — the same ownership the Slack
230
+ and SCM relays have. It authenticates with the host credential and keeps
231
+ a durable offset, so a restart resumes rather than dropping events. An
232
+ empty `repos` list mounts the channel but starts no relay for it, so an
233
+ env-configured agent stays inert until its repositories are set.
234
+
220
235
  For other platforms like Discord or Teams, use the authored
221
236
  `defineChannel` webhook form.
222
237
 
package/docs/reference/cli.md CHANGED
@@ -35,7 +35,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
35
35
  | [`trajectory`](#trajectory) | Summarize a saved `events.ndjson` file |
36
36
  | [`init`](#init) | Scaffold a project, or print the setup guide |
37
37
  | [`convert-automation`](#convert-automation) | Export a Cursor Automation into an agent project |
38
- | [`install-skills`](#install-skills) | Install the coding-agent skills without running `init` |
38
+ | [`install-skills`](#install-skills) | Refresh coding-agent skills (`npm install` already copies them) |
39
39
  | [`info`](#info) | Print the discovered agent surface |
40
40
  | [`validate`](#validate) | Check a project and fail on errors |
41
41
  | [`login` / `logout` / `whoami`](#login-logout-whoami) | Manage the host's Cursor credential |
@@ -441,10 +441,11 @@ before writing files. `pr-autofixer` asks for GitHub repos. Repeat
441
441
  `--var id=value` to answer without a prompt.
442
442
  `--json` and non-TTY hosts skip the interview unless `--var` is set.
443
443
 
444
- On a TTY, `init` also asks whether to install or update the coding-agent
445
- skills in `~/.cursor/skills/agentkit/`. If accepted, it overwrites them
446
- with the version bundled in the installed package. The prompt is skipped
447
- for `--json` and non-interactive hosts.
444
+ On a TTY, `init` also asks whether to refresh the coding-agent skills in
445
+ `~/.cursor/skills/agentsdk/`. Installing `@cursor/july` already copies
446
+ them via postinstall (with `alwaysApply: true` so Cursor injects the
447
+ bodies), so this prompt is a chance to overwrite with the package
448
+ version. The prompt is skipped for `--json` and non-interactive hosts.
448
449
 
449
450
  If the host isn't signed in, `init` runs `agent-sdk login` and waits for
450
451
  the browser flow. It then prints the `cd`, `agent-sdk login`, and
@@ -492,8 +493,12 @@ covers generated files and behavior the converter cannot reproduce.
492
493
 
493
494
  ## install-skills
494
495
 
495
- `install-skills` installs the package's coding-agent skills into
496
- `~/.cursor/skills/agentkit/`.
496
+ `install-skills` copies the package's coding-agent skills into
497
+ `~/.cursor/skills/agentsdk/` with `alwaysApply: true` so Cursor loads
498
+ them as global rules. Installing `@cursor/july` already does this in
499
+ postinstall (`npm install`, `npx`, a version bump). Use this command
500
+ to refresh without reinstalling the package, or from a monorepo
501
+ source checkout (postinstall skips that tree).
497
502
 
498
503
  ```bash
499
504
  agent-sdk install-skills [--print] [--json]
@@ -501,11 +506,14 @@ agent-sdk install-skills [--print] [--json]
501
506
 
502
507
  Running the command is the confirmation: it never prompts, and it
503
508
  overwrites the installed skills with the version bundled in the
504
- package. `init` offers the same install once, interactively. `--print`
509
+ package. `init` offers the same refresh once, interactively. `--print`
505
510
  previews the skills, the removals, and the install path without writing
506
511
  anything. `--json` prints
507
512
  `{ ok, dryRun, directory, firstInstall, skills, removed }`.
508
513
 
514
+ Set `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the postinstall copy.
515
+ `CURSOR_JULY_SKILLS_HOME` overrides the `~/.cursor/skills` directory.
516
+
509
517
  ## info
510
518
 
511
519
  `info` prints the discovered agent surface.
package/docs/scaffolding-agents.md CHANGED
@@ -16,13 +16,21 @@ into a small working project. Have Cursor read that file and follow it.
16
16
 
17
17
  Where to find the file depends on how you got the package:
18
18
 
19
- - Reading these docs on a hosted site? Run `agent-sdk install-skills`
20
- to copy every package skill into `~/.cursor/skills/agentkit/`, where
21
- Cursor discovers them by name.
22
- - Installed `@cursor/july` as a dependency? The skill ships inside the
23
- package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
19
+ - Installing `@cursor/july` (`npm install`, `npx @cursor/july`, a
20
+ version bump) copies every package skill into
21
+ `~/.cursor/skills/agentsdk/` with `alwaysApply: true`, so Cursor
22
+ injects the skill body into context instead of waiting for the
23
+ model to pick it from the catalog. The `/` menu lists them as
24
+ `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
25
+ copies with the package version. Set
26
+ `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the copy.
27
+ - Installed `@cursor/july` as a dependency? The skill also ships inside
28
+ the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
24
29
  - Working in the monorepo? It's at
25
- `packages/agent-serve/skills/create-agent/SKILL.md`.
30
+ `packages/agent-serve/skills/create-agent/SKILL.md`. Run
31
+ `agent-sdk install-skills` if you want the same copies in
32
+ `~/.cursor/skills/agentsdk/` (the package postinstall skips the
33
+ source checkout).
26
34
 
27
35
  Cursor will:
28
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cursor/july",
3
- "version": "0.1.73",
3
+ "version": "0.1.75",
4
4
  "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "repository": {
@@ -34,6 +34,7 @@
34
34
  "templates/**/*",
35
35
  "docs/**/*.md",
36
36
  "!docs/.cursor/**",
37
+ "scripts/install-cursor-skills.mjs",
37
38
  "package.json",
38
39
  "LICENSE.md",
39
40
  "README.md",
@@ -76,6 +77,12 @@
76
77
  "import": "./dist/channels/origin/index.js",
77
78
  "default": "./dist/channels/origin/index.js"
78
79
  },
80
+ "./channels/deployments": {
81
+ "anysphere-source": "./src/channels/deployments/index.ts",
82
+ "types": "./dist/channels/deployments/index.d.ts",
83
+ "import": "./dist/channels/deployments/index.js",
84
+ "default": "./dist/channels/deployments/index.js"
85
+ },
79
86
  "./skills": {
80
87
  "anysphere-source": "./src/skills.ts",
81
88
  "types": "./dist/skills.d.ts",
@@ -203,6 +210,7 @@
203
210
  },
204
211
  "scripts": {
205
212
  "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && pnpm run build:playground && pnpm run docs:build",
213
+ "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
206
214
  "build:playground": "vite build --config playground/vite.config.ts",
207
215
  "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
208
216
  "dev:playground": "vite --config playground/vite.config.ts",
package/scripts/install-cursor-skills.mjs ADDED
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * postinstall: copy Agent SDK coding-agent skills into ~/.cursor/skills/agentsdk
4
+ * so Cursor discovers them after `npm install` / `npx @cursor/july`.
5
+ *
6
+ * Never fails the package install. No-op in the monorepo source checkout
7
+ * (package root is not under node_modules) and when dist is missing.
8
+ */
9
+
10
+ import { existsSync } from "node:fs";
11
+ import { dirname, join } from "node:path";
12
+ import { fileURLToPath, pathToFileURL } from "node:url";
13
+
14
+ const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
15
+ const distEntry = join(
16
+ packageRoot,
17
+ "dist",
18
+ "internal",
19
+ "install-cursor-skills.js"
20
+ );
21
+
22
+ try {
23
+ if (!existsSync(distEntry)) {
24
+ process.exit(0);
25
+ }
26
+ // Windows: Node's ESM loader rejects bare drive-letter paths
27
+ // (`ERR_UNSUPPORTED_ESM_URL_SCHEME`). file:// is valid on every platform.
28
+ const { syncCursorSkillsOnPackageInstall } = await import(
29
+ pathToFileURL(distEntry).href
30
+ );
31
+ await syncCursorSkillsOnPackageInstall({ packageRoot });
32
+ } catch {
33
+ // Swallow: a skill copy must not fail `npm install`.
34
+ }
35
+
36
+ process.exit(0);
package/skills/ab/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-ab
2
+ name: agentsdk-ab
3
3
  description: >-
4
4
  Author defineAB live A/B metrics plug-ins under agent/ab. Splits traffic into
5
5
  sticky variants and calls onSample with performance metrics as the agent runs
package/skills/create-agent/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-create-agent
2
+ name: agentsdk-create-agent
3
3
  description: >-
4
4
  Scaffold a new Agent SDK agent through a guided AskQuestion interview —
5
5
  purpose, name, runtime, model, channels, MCP connections, capabilities —
package/skills/debug/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-debug
2
+ name: agentsdk-debug
3
3
  description: >-
4
4
  Diagnose a misbehaving Agent SDK agent, server, or playground — blank
5
5
  playground, sessions missing, HMR not reloading, failing reads/retry
package/skills/evals/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-evals
2
+ name: agentsdk-evals
3
3
  description: >-
4
4
  Author and run Agent SDK defineEval cases (single- or multi-datapoint).
5
5
  Use when writing, fixing, seeding, or hillclimbing evals; AskQuestion
package/skills/framework-map/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-framework-map
2
+ name: agentsdk-framework-map
3
3
  description: >-
4
4
  Orientation for @cursor/july — folder structure, local vs cloud
5
5
  runtimes, sessions, state layout, and invariants (Node not Bun, root
package/skills/github/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-github
2
+ name: agentsdk-github
3
3
  description: >-
4
4
  Build and test GitHub-webhook-driven Agent SDK agents: githubChannel
5
5
  hooks (auth turn vs host task), signature modes, and testing tiers
package/skills/hillclimb/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-hillclimb
2
+ name: agentsdk-hillclimb
3
3
  description: >-
4
4
  Iterate on a specific Agent SDK agent by running the local server,
5
5
  sending real requests, measuring correctness/efficiency, and proposing
package/skills/mcp-auth/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-mcp-auth
2
+ name: agentsdk-mcp-auth
3
3
  description: >-
4
4
  Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
5
5
  agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
package/skills/otel/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-otel
2
+ name: agentsdk-otel
3
3
  description: >-
4
4
  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
5
5
  traces/metrics/logs, ctx.host.otel). Use when adding observability,
package/skills/setup-slack/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: agentkit-setup-slack
2
+ name: agentsdk-setup-slack
3
3
  description: >-
4
4
  Wire Slack to an Agent SDK agent. Gate Cursor-hosted vs a dedicated
5
5
  Socket Mode app, then finish that path: cursorAccount sign-in + smoke,
package/src/bin/agent-serve.ts CHANGED
@@ -216,11 +216,13 @@ Commands:
216
216
  -> MCP). Review the project, then run \`validate\` / \`dev\`.
217
217
  Warnings never fail the command.
218
218
  install-skills
219
- Install (or refresh) the Agent SDK skills for coding agents in
220
- ~/.cursor/skills/agentkit and print where they landed. \`init\`
221
- offers this once, interactively, and skips it when the prompt
222
- goes unanswered; this command never asks. --print previews
223
- without writing.
219
+ Refresh the Agent SDK skills for coding agents in
220
+ ~/.cursor/skills/agentsdk and print where they landed.
221
+ Installed copies set alwaysApply so Cursor injects them
222
+ into context. \`npm install\` / \`npx\` already copies them
223
+ (postinstall); this command overwrites with the package
224
+ version without asking. \`init\` also offers a TTY refresh.
225
+ --print previews without writing.
224
226
  mcp Serve this agent's MCP endpoint over stdio for MCP clients
225
227
  that spawn local servers (e.g. Cursor). Proxies
226
228
  newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
package/src/channels/checks.ts ADDED
@@ -0,0 +1,185 @@
1
+ /**
2
+ * CI checks, shared across SCMs.
3
+ *
4
+ * The check lifecycle lives here once: `openCiCheck` opens a run (defaults
5
+ * `in_progress`, stamps `startedAt`), the returned {@link CiCheck} handle
6
+ * patches it (`update`) and completes it (`conclude`, stamps `completedAt`),
7
+ * and `resumeCiCheck` rebuilds a handle after a restart. Each SCM plugs in
8
+ * with one {@link CiCheckWriter} — a function that persists a single desired
9
+ * check state on its API (GitHub Checks API create/patch, Origin's keyed
10
+ * upsert, …) and owns any transport state such as a server-assigned run id.
11
+ *
12
+ * Agent code should usually stay one level higher, on {@link CiChecksClient}:
13
+ * both `ctx.github` and `ctx.origin` satisfy it, so a check reporter written
14
+ * once works on either forge:
15
+ *
16
+ * ```ts
17
+ * async function reportCheck(checks: CiChecksClient, sha: string) {
18
+ * const check = await checks.createCheck({ name: "My Agent", sha });
19
+ * // …do the work…
20
+ * await check.conclude({
21
+ * conclusion: "success",
22
+ * output: { title: "Done", summary: "All good." },
23
+ * });
24
+ * }
25
+ * ```
26
+ *
27
+ * {@link CiCheckConclusion} is the common subset every SCM accepts; an SCM
28
+ * with extras widens it through the generic parameter (e.g. Origin's
29
+ * `CiCheck<CiCheckConclusion | "stale">`).
30
+ */
31
+
32
+ /** Output shown on the check page. */
33
+ export interface CiCheckOutput {
34
+ /** Heading on the check page. */
35
+ title: string;
36
+ /** Markdown body (supports links, e.g. `[View session](…)`). */
37
+ summary: string;
38
+ /** Optional detailed markdown body. */
39
+ text?: string;
40
+ }
41
+
42
+ export type CiCheckStatus = "queued" | "in_progress" | "completed";
43
+
44
+ /** Final results accepted by every SCM. */
45
+ export type CiCheckConclusion =
46
+ | "action_required"
47
+ | "cancelled"
48
+ | "failure"
49
+ | "neutral"
50
+ | "skipped"
51
+ | "success"
52
+ | "timed_out";
53
+
54
+ export interface CiCheckUpdateInput<
55
+ TConclusion extends string = CiCheckConclusion,
56
+ > {
57
+ status?: CiCheckStatus;
58
+ conclusion?: TConclusion;
59
+ detailsUrl?: string;
60
+ output?: CiCheckOutput;
61
+ }
62
+
63
+ export interface CiCheckConcludeInput<
64
+ TConclusion extends string = CiCheckConclusion,
65
+ > {
66
+ /** Final result shown in the merge box. */
67
+ conclusion: TConclusion;
68
+ detailsUrl?: string;
69
+ output?: CiCheckOutput;
70
+ }
71
+
72
+ /** SCM-side reference to a check run, when the SCM reports one. */
73
+ export interface CiCheckRef {
74
+ /** Server-assigned run id (GitHub check-run number, Origin `cr_…`). */
75
+ id?: number | string;
76
+ /** Web URL of the check run page. */
77
+ url?: string;
78
+ }
79
+
80
+ /** A created check run, whichever SCM it lives on. */
81
+ export interface CiCheck<TConclusion extends string = CiCheckConclusion> {
82
+ /** Patch status / output / details link while the check is running. */
83
+ update(input: CiCheckUpdateInput<TConclusion>): Promise<void>;
84
+ /** Complete the check with a conclusion (stamps `completedAt`). */
85
+ conclude(input: CiCheckConcludeInput<TConclusion>): Promise<void>;
86
+ }
87
+
88
+ export interface CiCheckCreateInput {
89
+ /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
90
+ name: string;
91
+ /** Commit the check attaches to (usually the PR head SHA). */
92
+ sha: string;
93
+ /** Initial status. Defaults to `"in_progress"`. */
94
+ status?: "queued" | "in_progress";
95
+ /** "Details" link on the check, e.g. the agent session run URL. */
96
+ detailsUrl?: string;
97
+ /** Title + markdown summary shown on the check page. */
98
+ output?: CiCheckOutput;
99
+ }
100
+
101
+ /**
102
+ * Anything that can open a CI check on its bound repository — `ctx.github`,
103
+ * `ctx.origin`, or the `bindOriginChecks` adapter.
104
+ */
105
+ export interface CiChecksClient<
106
+ TConclusion extends string = CiCheckConclusion,
107
+ > {
108
+ createCheck(input: CiCheckCreateInput): Promise<CiCheck<TConclusion>>;
109
+ }
110
+
111
+ /** One desired check state for a writer to persist. */
112
+ export interface CiCheckWrite<TConclusion extends string = CiCheckConclusion>
113
+ extends CiCheckUpdateInput<TConclusion> {
114
+ startedAt?: string;
115
+ completedAt?: string;
116
+ }
117
+
118
+ /**
119
+ * The per-SCM extension point: persist one {@link CiCheckWrite} on the SCM
120
+ * (create-then-patch, keyed upsert, …). Bound to a repo + check identity at
121
+ * construction; owns transport state (e.g. the created run id) across calls.
122
+ * May return a {@link CiCheckRef} to expose on the handle.
123
+ */
124
+ export type CiCheckWriter<TConclusion extends string = CiCheckConclusion> = (
125
+ write: CiCheckWrite<TConclusion>
126
+ ) => Promise<CiCheckRef | undefined>;
127
+
128
+ /**
129
+ * Open a check run through `writer` and return a handle for later updates.
130
+ * SCM modules wrap this (`createGitHubCheck`, `createOriginCheck`); channels
131
+ * expose it repo-bound as `ctx.github.createCheck` / `ctx.origin.createCheck`.
132
+ */
133
+ export async function openCiCheck<
134
+ TConclusion extends string = CiCheckConclusion,
135
+ >(
136
+ writer: CiCheckWriter<TConclusion>,
137
+ input?: Pick<CiCheckCreateInput, "status" | "detailsUrl" | "output">
138
+ ): Promise<CiCheck<TConclusion> & CiCheckRef> {
139
+ const ref = await writer({
140
+ status: input?.status ?? "in_progress",
141
+ startedAt: new Date().toISOString(),
142
+ detailsUrl: input?.detailsUrl,
143
+ output: input?.output,
144
+ });
145
+ return resumeCiCheck(writer, ref);
146
+ }
147
+
148
+ /**
149
+ * Rebuild a {@link CiCheck} handle around an existing run (e.g. after a
150
+ * process restart). No write happens until the first update.
151
+ */
152
+ export function resumeCiCheck<TConclusion extends string = CiCheckConclusion>(
153
+ writer: CiCheckWriter<TConclusion>,
154
+ ref?: CiCheckRef
155
+ ): CiCheck<TConclusion> & CiCheckRef {
156
+ let id = ref?.id;
157
+ let url = ref?.url;
158
+ const write = async (write: CiCheckWrite<TConclusion>): Promise<void> => {
159
+ const next = await writer(write);
160
+ id = next?.id ?? id;
161
+ url = next?.url ?? url;
162
+ };
163
+ return {
164
+ get id() {
165
+ return id;
166
+ },
167
+ get url() {
168
+ return url;
169
+ },
170
+ update: (update) =>
171
+ write({
172
+ ...update,
173
+ completedAt:
174
+ update.status === "completed" ? new Date().toISOString() : undefined,
175
+ }),
176
+ conclude: (conclude) =>
177
+ write({
178
+ status: "completed",
179
+ conclusion: conclude.conclusion,
180
+ completedAt: new Date().toISOString(),
181
+ detailsUrl: conclude.detailsUrl,
182
+ output: conclude.output,
183
+ }),
184
+ };
185
+ }
package/src/channels/deployments/deployments-channel.ts ADDED
@@ -0,0 +1,109 @@
1
+ import { z } from "zod";
2
+
3
+ import { defineChannel, localDevStrict, POST } from "../../channels.js";
4
+ import { resolveDeploymentSubscriptions } from "../../internal/cursor-deployment-relay.js";
5
+ import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
6
+ import {
7
+ DEPLOYMENT_EVENT_TYPES,
8
+ DEPLOYMENTS_CHANNEL_KIND,
9
+ type DeploymentEvent,
10
+ type DeploymentsChannelOptions,
11
+ } from "./types.js";
12
+
13
+ const deploymentEventSchema = z.object({
14
+ eventType: z.enum(DEPLOYMENT_EVENT_TYPES),
15
+ eventId: z.string().min(1),
16
+ teamId: z.number(),
17
+ repo: z.string().min(1),
18
+ deploymentId: z.string().min(1),
19
+ environment: z.string().min(1),
20
+ service: z.string().min(1).optional(),
21
+ sha: z.string().min(1),
22
+ status: z.enum(["pending", "in_progress", "success", "failed"]),
23
+ occurredAtMs: z.number(),
24
+ });
25
+
26
+ /** Options used to construct a deployments channel — for host-level fan-out. */
27
+ const deploymentsChannelOptionsByDefinition = new WeakMap<
28
+ object,
29
+ DeploymentsChannelOptions
30
+ >();
31
+
32
+ /**
33
+ * Recover the {@link DeploymentsChannelOptions} used to build a channel
34
+ * definition, if it was created via {@link deploymentsChannel}.
35
+ */
36
+ export function getDeploymentsChannelOptions(
37
+ definition: object
38
+ ): DeploymentsChannelOptions | undefined {
39
+ return deploymentsChannelOptionsByDefinition.get(definition);
40
+ }
41
+
42
+ /**
43
+ * Core deployment-event dispatch, used by the channel's replay route and by
44
+ * the serve host's relay fan-out. Whether the event matches this channel's
45
+ * subscriptions is the caller's decision.
46
+ */
47
+ export async function dispatchDeploymentEvent(input: {
48
+ options: DeploymentsChannelOptions;
49
+ event: DeploymentEvent;
50
+ args: ChannelHandlerArgs;
51
+ }): Promise<Response> {
52
+ await input.options.onEvent(input.event, input.args);
53
+ return Response.json({ ok: true });
54
+ }
55
+
56
+ /**
57
+ * Deployment events channel.
58
+ *
59
+ * ```ts
60
+ * import { deploymentsChannel } from "@cursor/july/channels/deployments";
61
+ *
62
+ * export default deploymentsChannel({
63
+ * repos: ["repos/anysphere/everysphere"], // as your writer records it
64
+ * environments: ["prod"],
65
+ * onEvent: async (event, { send }) => {
66
+ * await send(`${event.repo}@${event.sha} shipped to ${event.environment}`);
67
+ * },
68
+ * });
69
+ * ```
70
+ *
71
+ * Declarative: the channel names what it wants and handles what arrives. The
72
+ * serve host discovers every mounted deployments channel, opens one
73
+ * `/v0/deployment-events` relay for the process, and routes each event to the
74
+ * channels subscribed to it — the same ownership the Slack and SCM relays
75
+ * have. Nothing is pushed to this deployment and no shared secret exists on
76
+ * either side.
77
+ *
78
+ * The route on this channel exists for local replay (`agent-sdk` and tests):
79
+ * POST an event body and it runs the same `onEvent`.
80
+ */
81
+ export function deploymentsChannel(
82
+ options: DeploymentsChannelOptions
83
+ ): ChannelDefinition {
84
+ // Throws here rather than at startup, so a malformed `repos` entry fails
85
+ // when the channel module is authored instead of when the host mounts it.
86
+ resolveDeploymentSubscriptions(options);
87
+ const routePath = options.path ?? "/";
88
+
89
+ const definition = defineChannel({
90
+ auth: options.auth ?? [localDevStrict()],
91
+ meta: { kind: DEPLOYMENTS_CHANNEL_KIND },
92
+ ...(options.onStart === undefined ? {} : { onStart: options.onStart }),
93
+ ...(options.onStop === undefined ? {} : { onStop: options.onStop }),
94
+ routes: [
95
+ POST(routePath, {
96
+ description: "Replay one deployment event onto this channel",
97
+ bodySchema: deploymentEventSchema,
98
+ handler: async (_request, args) =>
99
+ dispatchDeploymentEvent({
100
+ options,
101
+ event: args.body as DeploymentEvent,
102
+ args,
103
+ }),
104
+ }),
105
+ ],
106
+ });
107
+ deploymentsChannelOptionsByDefinition.set(definition, options);
108
+ return definition;
109
+ }
package/src/channels/deployments/index.ts ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Deployment events channel pack for agent-serve.
3
+ *
4
+ * ```ts
5
+ * import { deploymentsChannel } from "@cursor/july/channels/deployments";
6
+ *
7
+ * export default deploymentsChannel({
8
+ * repos: ["repos/anysphere/everysphere"], // as your writer records it
9
+ * environments: ["prod"],
10
+ * onEvent: (event, { send }) => send(`${event.sha} shipped`),
11
+ * });
12
+ * ```
13
+ *
14
+ * The serve host owns the transport, as it does for Slack and SCM events: it
15
+ * discovers every mounted deployments channel, opens one `/v0/deployment-events`
16
+ * relay for the process with the host's Cursor credential, and routes each
17
+ * event to the channels subscribed to it. The relay long-polls with a durable
18
+ * client-owned offset, so a restart resumes rather than dropping events.
19
+ *
20
+ * An agent whose sessions live on another channel forwards from `onEvent`
21
+ * into that channel rather than starting sessions here, the way a GitHub
22
+ * relay channel dispatches into an origin channel.
23
+ */
24
+
25
+ export * from "./deployments-channel.js";
26
+ export * from "./types.js";