@cursor/july 0.1.108 → 0.1.111

package/skills/deploy/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: agentsdk-deploy
+description: >-
+  Deploy or redeploy an Agent SDK project to Cursor-managed hosting
+  with an attached service account. Use when asked to deploy,
+  redeploy, publish, or update a hosted Agent SDK agent.
+---
+
+# Deploy an Agent SDK agent
+
+Use this skill only after a person asks for a deployment. It deploys a
+pushed Git ref to Cursor-managed hosting. Local files never upload.
+
+Use the exact published `@cursor/july` release embedded in the installed
+skill. Do not use a floating npm tag or a workspace build of the CLI.
+
+## Gather the target
+
+Resolve these values from the request and checkout:
+
+- Agent directory. Default to the current directory only when it contains
+  one Agent SDK project.
+- Deployment slug. Default to the normalized directory name.
+- Git ref. Default to the exact pushed `HEAD` commit.
+- Team. Use the service account's team unless the request names another.
+- Cursor-event repositories and CLI-only egress domains.
+
+Ask one focused question when the target or requested ref is ambiguous.
+Do not ask for values the checkout or existing deployment supplies.
+
+## Use the attached service account
+
+Continue only when `CURSOR_SERVICE_ACCOUNT_KEY` is present. Never print
+the value. Do not run `agent-sdk login`.
+
+On Linux and macOS, run every Agent SDK command through this wrapper:
+
+```bash
+CURSOR_JULY_VERSION="__CURSOR_JULY_VERSION__"
+case "$CURSOR_JULY_VERSION" in
+  __CURSOR_JULY_*__)
+    echo "The Agent SDK deploy skill is not bound to a package version." >&2
+    exit 1
+    ;;
+esac
+
+run_agent_sdk() {
+  env -u NODE_OPTIONS -u CURSOR_API_KEY \
+    CURSOR_API_KEY_FILE=/dev/null \
+    npx --yes "@cursor/july@$CURSOR_JULY_VERSION" "$@"
+}
+```
+
+The installed copy pins the release it came from. The wrapper isolates that
+published CLI and the attached service account. The presence check prevents a
+stored personal login from being used when the attachment is missing.
+
+Verify the principal before any write:
+
+```bash
+test -n "${CURSOR_SERVICE_ACCOUNT_KEY:-}" || {
+  echo "No attached Cursor service account." >&2
+  exit 1
+}
+run_agent_sdk whoami --json
+```
+
+Continue only when `credentialSource` is `service-account`. Record the
+team and complete service-account ID for the final report. Stop on an
+authentication, team-access, repository-scope, or hosting-entitlement
+error.
+
+## Pin pushed source
+
+Find the Git root and commit:
+
+```bash
+GIT_ROOT="$(git -C "$AGENT_DIR" rev-parse --show-toplevel)"
+SOURCE_REF="$(git -C "$GIT_ROOT" rev-parse HEAD)"
+git -C "$GIT_ROOT" status --short
+git -C "$GIT_ROOT" branch -r --contains "$SOURCE_REF"
+```
+
+Use a ref from the request instead of `SOURCE_REF` when the person names
+one. Confirm the selected commit exists on the remote. If intended
+changes are uncommitted or unpushed, stop and explain they will not ship.
+Do not commit or push unless the request includes that work.
+
+The CLI infers the normalized HTTPS `origin`, agent path, and slug from
+`--dir`. Pass `--repo`, `--path`, or `--slug` when the request overrides
+the inferred value. Never print a remote URL that contains credentials.
+
+## Preserve deployment inputs
+
+A redeploy replaces its source, Cursor-event repositories, and
+CLI-supplied egress domains. Preserve the existing
+`cursorEventRepos` and `egressAllowedDomains` unless the request or
+project changes them. Reapply each value with:
+
+```text
+--cursor-events-repo <owner/repo>
+--allow-domain <hostname>
+```
+
+Read existing settings through a filter that selects only those two
+fields:
+
+```bash
+run_agent_sdk deployment "$SLUG" --json |
+  node -e '
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { raw += chunk; });
+    process.stdin.on("end", () => {
+      const value = JSON.parse(raw);
+      console.log(JSON.stringify({
+        cursorEventRepos: value.cursorEventRepos ?? [],
+        egressAllowedDomains: value.egressAllowedDomains ?? [],
+      }, null, 2));
+    });
+  '
+```
+
+Never print or save the full response because it can contain short-lived
+engine-access headers.
+
+For a new SCM-channel deployment, ask which repositories should wake the
+agent when the project does not declare the answer. The source repository
+is not always the event repository.
+
+## Validate, deploy, and verify
+
+Validate with the same published package and principal:
+
+```bash
+run_agent_sdk validate --dir "$AGENT_DIR"
+```
+
+Stop on validation errors. Review hosting warnings about secret names,
+egress domains, and channel configuration before continuing.
+
+Deploy the pinned source. Add the preserved or requested repeatable
+flags:
+
+```bash
+run_agent_sdk deploy \
+  --dir "$AGENT_DIR" \
+  --ref "$SOURCE_REF"
+```
+
+The command waits for a terminal deployment state. Do not treat
+`pending`, `accepted`, or `deploying` as success. If the command is
+interrupted, resume inspection with:
+
+```bash
+run_agent_sdk deployment "$SLUG"
+```
+
+A first deployment prints a one-time alias token. Never paste it into
+chat or expose it in an agent-captured terminal. Before a first deploy,
+ask for a secure destination or ask the person to run the final command
+in a private terminal. When writing the token, use mode `0600` and print
+only the path. Redeploys do not print the token. JSON deployment output
+can also contain credentials, so filter it before display.
+
+Finish only when the deployment reports `running`. Report the slug,
+team, generation, pinned ref, and complete service-account ID. On
+failure, report the deployment status and sanitized error without
+retrying a different ref or principal.

package/skills/evals/SKILL.md

@@ -3,17 +3,17 @@ name: agentsdk-evals
 description: >-
   Author and run defineEval cases. Use when writing, fixing, seeding,
   or hillclimbing evals. Ask whether to generate samples or take
-  uploaded data. Materialize API-backed fixtures first. Live A/B is
-  defineAB (skills/ab), not defineEval.
+  uploaded data. Materialize API-backed fixtures first.
 ---
 
 # Agent SDK evals
 
 Fixed input, model turn, gates on the trajectory. Files live at
 project-root `evals/**/*.eval.ts`. `agent/evals/` is ignored.
+Guide: `docs/evals.md`.
 
-Live traffic variants: `skills/ab/SKILL.md`. That is not a test
-runner.
+Observing production: hooks. Tool logic without a model:
+`agent-sdk call <tool> --input '{...}'`.
 
 ```bash
 agent-sdk eval --dir . --list
@@ -27,9 +27,13 @@ agent-sdk eval --dir . --tag smoke
 | `evals/weather.eval.ts` + `test` | `weather` |
 | `evals/weather/nyc.eval.ts` + `test` | `weather/nyc` |
 | `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
+| `evals/sql.eval.ts` exporting an array of `defineEval` calls | `sql/0000`, `sql/0001`, ... |
 
 `eval` boots an ephemeral server and a temp state root. `--url`
-points at a running agent. Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`).
+points at a running agent. Model turns need a Cursor credential
+(`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then
+`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`); `--list` does
+not. Node 22.13+, never Bun.
 
 ## Seeding
 
@@ -79,9 +83,30 @@ export default defineEvalConfig({
 });
 ```
 
-Either `test(t)` or `cases`, not both. `t.send` waits for park/fail.
-`workspaceFiles` seeds the first turn. Assert with `t.succeeded()`,
-`calledTool` / `notCalledTool`, `t.check(t.reply, …)`, `t.metric`.
+Either `test(t)` or `cases`, not both. `t.send` waits for the turn to
+settle (complete, park, or fail) and returns it; `turn.calledTool(...)`
+reads only that turn, `t.*` reads the whole run. First-send options:
+`workspaceFiles`, `workspaceDir`, `cloud`.
+
+Gates: `t.succeeded()` / `t.parked()`,
+`calledTool(name, { input, output, status, count })` / `notCalledTool`,
+`toolOrder`, `maxToolCalls`, `taggedArtifact`, `event` / `notEvent`,
+`t.check(value, includes | equals | matches | similarity | satisfies)`.
+Records: `t.metric`, `t.log`, `t.score` (soft 0-1).
+
+Severity is on the handle: default gate; `.soft()` tracked;
+`.atLeast(0.8)` soft with a bar (verdict `scored`, exit 1 only under
+`--strict`); `.gate(0.8)` hard. `t.judge.factuality`, `summarizes`,
+`closedQA`, and `sql` are soft by default and need a judge model
+(`judge` in `evals.config.ts`, on the eval or case, or per-call
+`{ model }`).
+
+## Side effects
+
+Eval sessions run real tools. Guard actuation with
+`ctx.session.purpose === "eval"` in the tool, hook, or `defineResult`
+and return a shaped result so `calledTool` can still assert the
+decision.
 
 ## What to gate
 
@@ -103,6 +128,18 @@ drifting inputs (pin them).
 | GitHub | `github replay … --dry-run --out fixtures/github` |
 | Host-prep PR review | A team-owned PR; gate findings shape, not counts |
 | Workspace | `workspaceFiles` in `t.send` |
+| Dataset | `loadJson` / `loadJsonl` / `loadYaml` from `@cursor/july/evals/loaders`, paths from the project root |
+
+## Debug and CI
+
+A failed local run leaves `evals/<case-id>.json` (assertions, inputs,
+tool I/O, final text, logs) under `evals/<stamp>/` in the project state
+directory (the CLI prints the path); read it before editing the eval.
+`--state-root <path>` keeps the raw session events too.
+
+CI: `agent-sdk eval --dir . --json --no-stream --junit reports/evals.xml`.
+Exit `1` on a failed gate, `2` when nothing matched, `--strict` to fail
+on `scored`.
 
 Every kept hillclimb change lands an eval that would have failed
 before it. Never weaken a gate to pass a round.

package/skills/framework-map/SKILL.md

@@ -50,9 +50,8 @@ Path is identity. Full list: README "Folder structure".
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
 | `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
-| `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
-| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
-| `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
+| `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`; `throw` or `ctx.reject`) |
+| `agent/otel.ts` | Factory-only OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
 | `agent/sandbox/workspace/` | Session seed files (local only) |
 | `agent/lib/` | Import-only. Never discovered |
@@ -99,10 +98,10 @@ only this agent's directory.
 | --- | --- |
 | Scaffold | `skills/create-agent/SKILL.md` |
 | Evals | `skills/evals/SKILL.md` |
-| Live A/B | `skills/ab/SKILL.md` |
 | OpenTelemetry | `skills/otel/SKILL.md` |
 | GitHub | `skills/github/SKILL.md` |
 | Slack | `skills/setup-slack/SKILL.md` |
 | Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Managed deployment | `skills/deploy/SKILL.md` |
 | Local triage | `skills/debug/SKILL.md` |
 | Measured improvement | `skills/hillclimb/SKILL.md` |

package/skills/otel/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentsdk-otel
 description: >-
-  Wire OpenTelemetry export (defineOtel, OTLP env, traces/metrics/logs,
+  Wire OpenTelemetry export (OTLP env, serve({ otel }), traces/metrics/logs,
   ctx.host.otel). Use when adding collector export or custom metrics.
 ---
 
-# Agent SDK OpenTelemetry (`defineOtel`)
+# Agent SDK OpenTelemetry
 
 Push traces and metrics from the serve process to an OTLP
 collector. Logs are off until you opt in.
@@ -14,28 +14,18 @@ Guide: `docs/guides/opentelemetry.md`.
 
 ## Enable
 
-Any one of:
+Public surface (use one of these):
 
 1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
    `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
    `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
-2. `agent/otel.ts`:
-
-```ts
-import { defineOtel } from "@cursor/july/otel";
-
-export default defineOtel({
-  serviceName: "cursor",
-  exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
-});
-```
-
-3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
+2. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
-Hosted secrets can arrive after startup. Use `defineOtel(() => …)` so
-flush re-resolves exporters. Authored `agent/otel.ts` records from
-process start even when the factory returns no exporters yet.
+`defineOtel` / `agent/otel.ts` is factory-only
+(`@cursor/july/internal/otel`). Do not import that path from a
+customer agent. Hosted secrets can arrive after startup; env and
+`serve({ otel })` are the supported public late-bind.
 
 | Signal | Default |
 | --- | --- |