@cursor/july 0.1.19 → 0.1.20
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.
- package/AGENTS.md +10 -0
- package/dist/docs/404.html +1 -1
- package/dist/docs/ab.html +2 -2
- package/dist/docs/assets/{app.CrsWMchO.js → app.T-5ImnM3.js} +1 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.CvejISXF.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.D1JqzSh8.js → VPLocalSearchBox.OMGMWH6H.js} +1 -1
- package/dist/docs/assets/chunks/{theme.DaBvZYwl.js → theme.DLg4yB4D.js} +2 -2
- package/dist/docs/building-with-agents.html +2 -2
- package/dist/docs/concepts.html +2 -2
- package/dist/docs/deployment.html +2 -2
- package/dist/docs/evals.html +2 -2
- package/dist/docs/example-agents/approval-buddy.html +2 -2
- package/dist/docs/example-agents/benny.html +2 -2
- package/dist/docs/example-agents/bugbot.html +2 -2
- package/dist/docs/example-agents/codebase-wiki.html +2 -2
- package/dist/docs/example-agents/codeowners-review.html +2 -2
- package/dist/docs/example-agents/concierge.html +2 -2
- package/dist/docs/example-agents/fsd.html +2 -2
- package/dist/docs/example-agents/index.html +2 -2
- package/dist/docs/example-agents/knowledge-base.html +2 -2
- package/dist/docs/example-agents/oncall.html +2 -2
- package/dist/docs/example-agents/security-reviewer.html +2 -2
- package/dist/docs/example-agents/slack-agent.html +2 -2
- package/dist/docs/example-agents/weather-agent.html +2 -2
- package/dist/docs/guides/agent-to-agent.html +2 -2
- package/dist/docs/guides/cloud-runtime.html +2 -2
- package/dist/docs/guides/github.html +2 -2
- package/dist/docs/guides/human-in-the-loop.html +2 -2
- package/dist/docs/guides/mcp-oauth.html +2 -2
- package/dist/docs/guides/slack.html +2 -2
- package/dist/docs/guides/webhooks.html +2 -2
- package/dist/docs/hillclimbing.html +2 -2
- package/dist/docs/index.html +2 -2
- package/dist/docs/quickstart.html +2 -2
- package/dist/docs/reference/agent-config.html +2 -2
- package/dist/docs/reference/channels.html +2 -2
- package/dist/docs/reference/cli.html +2 -2
- package/dist/docs/reference/connections.html +2 -2
- package/dist/docs/reference/hooks.html +2 -2
- package/dist/docs/reference/http-api.html +2 -2
- package/dist/docs/reference/instructions.html +2 -2
- package/dist/docs/reference/playground.html +2 -2
- package/dist/docs/reference/project-layout.html +2 -2
- package/dist/docs/reference/prompt.html +2 -2
- package/dist/docs/reference/schedules.html +2 -2
- package/dist/docs/reference/sessions.html +2 -2
- package/dist/docs/reference/skills.html +2 -2
- package/dist/docs/reference/subagents.html +2 -2
- package/dist/docs/reference/tools.html +2 -2
- package/dist/docs/scaffolding-agents.html +2 -2
- package/dist/docs/storage.html +2 -2
- package/dist/docs/troubleshooting.html +2 -2
- package/dist/playground/assets/index-CuiAKZaP.js +85 -0
- package/dist/playground/index.html +1 -1
- package/package.json +2 -2
- package/skills/create-agent/SKILL.md +36 -4
- package/skills/evals/SKILL.md +3 -0
- package/skills/framework-map/SKILL.md +14 -0
- package/skills/github/SKILL.md +6 -1
- package/skills/hillclimb/SKILL.md +28 -7
- package/dist/docs/assets/chunks/@localSearchIndexroot.BnHRjfoe.js +0 -1
- package/dist/playground/assets/index-C2SU2xV5.js +0 -85
|
@@ -8,7 +8,7 @@
|
|
|
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-
|
|
11
|
+
<script type="module" crossorigin src="./assets/index-CuiAKZaP.js"></script>
|
|
12
12
|
<link rel="stylesheet" crossorigin href="./assets/index-CidizGZv.css">
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cursor/july",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.20",
|
|
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": {
|
|
@@ -197,7 +197,7 @@
|
|
|
197
197
|
"node": ">=22.13"
|
|
198
198
|
},
|
|
199
199
|
"dependencies": {
|
|
200
|
-
"@cursor/sdk": "1.0.
|
|
200
|
+
"@cursor/sdk": "1.0.26",
|
|
201
201
|
"@modelcontextprotocol/sdk": "1.25.1",
|
|
202
202
|
"@octokit/auth-app": "^7.2.0",
|
|
203
203
|
"@octokit/rest": "^21.1.1",
|
|
@@ -99,9 +99,38 @@ Defaults that make first cuts good:
|
|
|
99
99
|
- **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
|
|
100
100
|
`MY_AGENT_SLACK_*`); `agentkit slack init` derives it for you.
|
|
101
101
|
Dedicated-app path only — the Cursor-hosted connection has no tokens.
|
|
102
|
-
- **Host prep beats model wandering
|
|
103
|
-
setup step (fetch a PR, seed files), do it in
|
|
104
|
-
`callTool` / `workspaceFiles` rather than
|
|
102
|
+
- **Host prep beats model wandering — for evidence, not judgment.** When the
|
|
103
|
+
purpose has a deterministic setup step (fetch a PR, seed files), do it in
|
|
104
|
+
the channel handler via `callTool` / `workspaceFiles` rather than
|
|
105
|
+
instructing the model to do it. Stop there: host code that formats,
|
|
106
|
+
summarizes, classifies, or composes replies is the model's job specified
|
|
107
|
+
badly, and it never comes off the books.
|
|
108
|
+
|
|
109
|
+
### The deterministic-path budget
|
|
110
|
+
|
|
111
|
+
TypeScript on the deterministic path is a permanent liability — every line
|
|
112
|
+
brings types, tests, restarts, and drift against the framework; prose is
|
|
113
|
+
cheap to change. Default every behavior to instructions/skills and promote
|
|
114
|
+
it to code only when it earns a row on the left:
|
|
115
|
+
|
|
116
|
+
| Code owns (earns its keep) | Model owns (keep out of code) |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| Side-effect gates and actuation (approve, deploy, post) | Composing human-facing output — replies, reports, comments, tables — to a shape stated in instructions |
|
|
119
|
+
| Idempotency / dedupe of external writes | Summarizing, classifying, wording, judgment calls |
|
|
120
|
+
| Auth, secrets, signature verification | Deciding what to do next from ground truth |
|
|
121
|
+
| Evidence seeding (`workspaceFiles`, channel `callTool` prep) | Interpreting soft failures and choosing retries |
|
|
122
|
+
| Hard caps at API boundaries (chunk limits, truncation) | Formatting niceties (links, emphasis, ordering) under those caps |
|
|
123
|
+
|
|
124
|
+
Two smells to check before scaffolding and again before hand-off:
|
|
125
|
+
|
|
126
|
+
- **Prose in TS.** An `instructions.ts` / `prompt.ts` string builder is a
|
|
127
|
+
skill file wearing a trench coat — write `.md` and interpolate only what
|
|
128
|
+
is truly dynamic.
|
|
129
|
+
- **Inverted ratio.** A first cut whose `agent/lib/` + `tools/` dwarf its
|
|
130
|
+
instructions + skills (~3:1 or worse) is either wrapping an existing
|
|
131
|
+
deterministic pipeline (fine — keep the wrapper thin and say so) or
|
|
132
|
+
building a service with a vestigial model turn. Move procedure back into
|
|
133
|
+
prompts, or question whether this should be an agent at all.
|
|
105
134
|
|
|
106
135
|
## Scaffold
|
|
107
136
|
|
|
@@ -234,4 +263,7 @@ loop starts deterministic.
|
|
|
234
263
|
- Do not deploy, post to real Slack/GitHub surfaces beyond the smoke tests the
|
|
235
264
|
user asked for, or commit without being asked.
|
|
236
265
|
- Keep the first cut reviewable: if the plan grows past ~10 files, cut scope
|
|
237
|
-
and say what you deferred.
|
|
266
|
+
and say what you deferred. Re-check the deterministic-path budget at
|
|
267
|
+
hand-off — behavior that crept into `lib/` during bring-up (formatting,
|
|
268
|
+
reply shaping, classification) goes back into instructions before you call
|
|
269
|
+
it done.
|
package/skills/evals/SKILL.md
CHANGED
|
@@ -193,6 +193,9 @@ tool choice, tool avoidance, and output structure shouldn't.
|
|
|
193
193
|
findings-block fence) — not exact sentences.
|
|
194
194
|
4. For structured output, parse `t.reply` and `t.check` fields with
|
|
195
195
|
`satisfies` rather than substring-matching JSON.
|
|
196
|
+
5. When a shape gate keeps failing on model formatting, tighten the output
|
|
197
|
+
contract in instructions and re-run — do not move rendering into a host
|
|
198
|
+
tool to make the gate pass. That trades a prompt fix for permanent code.
|
|
196
199
|
|
|
197
200
|
Anti-patterns: asserting exact phrasing; more than ~5 gates in one case
|
|
198
201
|
(split it); cases that depend on live external state that drifts (pin the
|
|
@@ -125,6 +125,20 @@ Key built-in routes (each agent, under `/<slug>` in multi-agent mode):
|
|
|
125
125
|
Delete a session directory to forget a conversation. The playground can
|
|
126
126
|
open any `events.ndjson` ("Open trace").
|
|
127
127
|
|
|
128
|
+
## Where logic belongs
|
|
129
|
+
|
|
130
|
+
The model is the engine; TypeScript is the boundary layer. Code earns its
|
|
131
|
+
place on the deterministic path for side-effect gates and actuation,
|
|
132
|
+
idempotency/dedupe of external writes, auth/secrets, evidence seeding, and
|
|
133
|
+
hard caps at API boundaries. Formatting, summarizing, classification,
|
|
134
|
+
wording, and composing human-facing output belong to the model, under an
|
|
135
|
+
output contract in instructions/skills — prose lives in `.md` files, not TS
|
|
136
|
+
string builders. When `agent/lib/` + `tools/` dwarf instructions + skills,
|
|
137
|
+
you are usually looking at a service with a vestigial model turn, or at
|
|
138
|
+
framework gaps patched agent-side that should be fixed upstream. The
|
|
139
|
+
budget table and smells: `create-agent/SKILL.md` § "The deterministic-path
|
|
140
|
+
budget".
|
|
141
|
+
|
|
128
142
|
## The loop
|
|
129
143
|
|
|
130
144
|
Edit → inspect → run → assert. Canonical commands and flags live in
|
package/skills/github/SKILL.md
CHANGED
|
@@ -133,7 +133,12 @@ backend. Stream is metadata-only today (payload lookup later).
|
|
|
133
133
|
|
|
134
134
|
## Production-shaped channel patterns
|
|
135
135
|
|
|
136
|
-
Steal these when an agent must survive real webhook volume
|
|
136
|
+
Steal these when an agent must survive real webhook volume — each one
|
|
137
|
+
against its measured load signal, not as a starter kit. Debounce needs
|
|
138
|
+
event bursts you have seen; persisted buffers need wakes you cannot afford
|
|
139
|
+
to drop; affinity stores need cross-channel resume you actually do.
|
|
140
|
+
Preinstalling all of them is how a channel file hits 400 lines before the
|
|
141
|
+
first real delivery.
|
|
137
142
|
|
|
138
143
|
- **Debounce per PR** (~3s, latest event wins) and re-buffer while CI
|
|
139
144
|
settles; skip a flush when a turn for that PR is already in flight.
|
|
@@ -95,16 +95,28 @@ trigger grep loops”, “skill not on disk so model searches the monorepo”).
|
|
|
95
95
|
|
|
96
96
|
### 3. Propose one change
|
|
97
97
|
|
|
98
|
-
Prefer the smallest lever that addresses that failure mode
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
98
|
+
Prefer the smallest lever that addresses that failure mode — and check the
|
|
99
|
+
subtractive lever first:
|
|
100
|
+
|
|
101
|
+
0. **Deletion** — remove the code, cache, flag, or prompt that caused the
|
|
102
|
+
failure. A round that shrinks the agent while holding the metrics is a
|
|
103
|
+
win, not a wash.
|
|
104
|
+
1. **Instructions / skills** — tighten procedure, state the output contract
|
|
105
|
+
(shape, sections, caps), forbid escape hatches that invite thrash. First
|
|
106
|
+
lever for quality, formatting, and wording failures.
|
|
102
107
|
2. **Evidence shape** — trim, split, or order artifacts so the intended file
|
|
103
108
|
is primary
|
|
104
|
-
3. **
|
|
105
|
-
|
|
109
|
+
3. **Host prep** — deterministic tools / channel handlers seed only what the
|
|
110
|
+
model needs (`workspaceFiles`, channel `callTool`, …). First lever for
|
|
111
|
+
tool-wandering and latency failures. Prep evidence and gate side effects;
|
|
112
|
+
do **not** move formatting, summarizing, or classification here — that is
|
|
113
|
+
the model's job specified badly, and host code is a permanent tax (types,
|
|
114
|
+
tests, restarts, drift).
|
|
106
115
|
4. **Tool surface** — remove or gate tools that enable wandering
|
|
107
|
-
5. Framework changes only if the agent cannot express the fix otherwise
|
|
116
|
+
5. **Framework changes** only if the agent cannot express the fix otherwise —
|
|
117
|
+
but when the gap is plumbing the framework should own (posting, chunking,
|
|
118
|
+
auth, retries), extend it or file the gap. A hand-rolled transport
|
|
119
|
+
workaround in `agent/lib/` outlives the gap and never flows back.
|
|
108
120
|
|
|
109
121
|
State the hypothesis in one sentence: *“If we X, metric Y should move because Z.”*
|
|
110
122
|
|
|
@@ -134,6 +146,11 @@ Present a short round report to the user before starting the next climb.
|
|
|
134
146
|
from moving deterministic work to the host (one PR reviewer's host-prepared
|
|
135
147
|
reviews cut ~8-minute tool-wandering turns to ~1 minute), not from prompt
|
|
136
148
|
tuning.
|
|
149
|
+
- The reverse also holds: every optimization on the deterministic path —
|
|
150
|
+
prefetch, fingerprint dedupe, write coalescing, TTL caches — is code, tests,
|
|
151
|
+
and flags forever. Add one only against measured pressure (wake volume,
|
|
152
|
+
rate-limit hits, model spend) recorded in the round report; when the data
|
|
153
|
+
says the cache would rarely hit, don't build it.
|
|
137
154
|
- For quality, spot-check against a known-good review or oracle on at least
|
|
138
155
|
one fixture; efficiency-only climbs will silently drop findings.
|
|
139
156
|
- `turn.failed` with `"turn interrupted"` in a trace means a follow-up or
|
|
@@ -143,6 +160,10 @@ Present a short round report to the user before starting the next climb.
|
|
|
143
160
|
|
|
144
161
|
- One failure mode per round — no mixed “also rewrite instructions while
|
|
145
162
|
trimming evidence” bundles unless the user asks.
|
|
163
|
+
- Climbs accrete; schedule the counter-move. Every few rounds propose a
|
|
164
|
+
**shrink round**: dead flags, caches that never hit (the disposition
|
|
165
|
+
metrics tell you), host renderers the model could own under an output
|
|
166
|
+
contract. The eval suite is exactly what makes deletion safe.
|
|
146
167
|
- Keep fixtures fixed until a climb explicitly needs a harder case.
|
|
147
168
|
- Use mise/Node workflows already documented for this package; do not introduce
|
|
148
169
|
Bun.
|