@cursor/july 0.1.109 → 0.1.112

package/docs/guides/human-in-the-loop.md

@@ -1,131 +0,0 @@
----
-title: "Human-in-the-loop"
-description: "Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."
----
-
-# Human-in-the-loop approvals
-
-Some tools must wait for human review: promoting a build, approving a PR,
-spending money. Mark those tools `needsApproval` and the host parks the
-in-flight call until a person approves or denies it, from the
-playground, over HTTP, or with Slack buttons. The turn stays running;
-nothing executes until someone decides.
-
-## Gate a tool
-
-Mark the tool with `needsApproval` and export it like any other tool.
-
-```ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Promote a verified build to production.",
-  needsApproval: true,
-  inputSchema: z.object({
-    service: z.string(),
-    buildId: z.string(),
-  }),
-  async execute({ service, buildId }) {
-    return {
-      promoted: true,
-      service,
-      buildId,
-      environment: "production",
-    };
-  },
-});
-```
-
-`needsApproval` also takes a predicate over the validated input, so you
-can gate only the dangerous shapes:
-
-```ts
-needsApproval: (input) => input.amountUsd > 100,
-```
-
-## What happens to a gated call
-
-When the model calls a `needsApproval` tool, the call parks and the
-session's stream emits `action.approval_requested` with the `callId`,
-tool name, and arguments. The turn stays running and waits. When a
-person resolves it, the stream emits `action.approval_resolved` with the
-decision and, where known, who decided. On approval, `execute` runs and
-`action.result` follows exactly as if the tool had run immediately. On
-denial, the model receives the denial as the tool result and continues
-the turn. It can explain, adjust, or try something else.
-
-Approvals exist for `execution: "server"` tools on the local runtime
-only. Parked calls do not survive a host restart: pending approvals left
-after a crash resolve as interrupted, and you re-run the turn.
-
-## Resolve from the playground
-
-Parked calls render Approve / Deny buttons inline in the conversation.
-Nothing to configure.
-
-## Resolve over HTTP
-
-List and resolve programmatically. The routes run the same auth chain as
-the rest of the session API, and the caller must be the session owner:
-
-```bash
-curl http://127.0.0.1:3000/<slug>/v1/session/ses_.../approvals
-# {"approvals":[{"callId":"...","toolName":"approve_pr","args":{...}}]}
-
-curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_.../approvals/<callId> \
-  -H 'content-type: application/json' \
-  -d '{"decision":"approve"}'   # or "deny"
-```
-
-## Resolve from Slack
-
-Set `toolApprovals: true` on the Slack channel and the pack posts Block
-Kit Approve/Deny cards and routes the button clicks back to the parked
-call:
-
-```ts
-import { slackChannel } from "@cursor/july/channels/slack";
-
-export default slackChannel({
-  toolApprovals: true,
-});
-```
-
-Approval cards need interactivity on the Slack app. Cards show redacted,
-truncated arguments because of Block Kit size limits. Execution still
-uses the full validated input, so review sensitive tools in the
-playground when the arguments may exceed the card. Details in the
-[Slack guide](./slack.md#add-approval-buttons).
-
-In `serve --dev`, the playground can also list Slack sessions and
-resolve their parked tools (the audit trail records the HTTP caller).
-That bridge does not open cross-owner approval for HTTP sessions, and
-production and bearer-auth hosts stay strict: Slack approvals must come
-from Slack interactivity or a matching principal.
-
-## Design principles for approvals
-
-Park/resume is independent of delivery: `needsApproval` works with no
-Slack channel at all, because the playground and HTTP surfaces are
-always there.
-
-Prefer approval gates over trust in instructions. "Only call this tool
-when…" is a suggestion; `needsApproval` is a guarantee. And pair
-approvals with dry-run defaults for destructive integrations: post real
-PR reviews only behind an explicit env flag like `MY_AGENT_LIVE=1`, no
-matter who approved.
-
-Deterministic tool calls (`agent-sdk call`, `POST /v1/tools/:name`)
-execute directly without parking. There the human is the caller.
-Approval parking applies to model-initiated calls.
-
-## What's next
-
-Continue with these pages:
-
-- [Tools](../reference/tools.md): the full tool API `needsApproval`
-  lives on
-- [Slack](./slack.md): the approval cards in context
-- [Sessions and streaming](../reference/sessions.md): the
-  `action.approval_*` events on the wire

package/docs/reference/result.md

@@ -1,94 +0,0 @@
----
-title: "Turn result"
-description: "Run host code on the final assistant text when a turn finishes. Throw to fail the turn."
----
-
-# Turn result
-
-Judgment agents need a place to act on the model's last message: parse
-it, then page, comment, or close a ticket. Author `agent/result.ts`
-with `defineResult` from `@cursor/july/result`. When that file exists,
-every finished turn runs `commit` on the serving host with the full
-assistant text.
-
-A thrown `commit` fails the turn. Empty assistant text fails it too.
-Hooks still observe only; they cannot fail a valid turn.
-
-Use this for an end-of-turn actuation. Mid-turn actions belong in
-[tools](./tools.md). Durable records that outlive a session belong in
-[artifacts](./artifacts.md).
-
-## Author `agent/result.ts`
-
-```ts
-import { defineResult } from "@cursor/july/result";
-import { applyDecision, parseDecision } from "./lib/actuate.js";
-
-export default defineResult({
-  async commit(ctx) {
-    if (ctx.session.purpose === "eval") {
-      return;
-    }
-    await applyDecision(parseDecision(ctx.text), ctx.host);
-  },
-});
-```
-
-`commit` is required. Parse `ctx.text` however the agent needs. Tell
-the model the document shape in `instructions.md`. The Agent SDK does
-not inject a schema.
-
-Put `result.ts` on the root agent only. A copy under a subagent is
-ignored with a warning.
-
-## Commit on the host
-
-`commit` runs in the serving process after the model finishes, before
-the turn completes. `ctx` is the same host surface a server tool gets,
-plus the turn text:
-
-| Member | What it is |
-| --- | --- |
-| `ctx.session` | The session that produced this turn, including `purpose` |
-| `ctx.host` | Shared host services (`kv`, `files`, `mcp`) |
-| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade |
-| `ctx.stateRoot` | The agent's durable state root |
-| `ctx.workspaceDir` | The session workspace |
-| `ctx.text` | The full assistant string |
-
-A dry-run session skips `commit` and still completes. Eval sessions do
-run `commit`; return early when `ctx.session.purpose === "eval"` if the
-handler must not actuate.
-
-On cloud runtime, the model still runs on the VM. `commit` runs on the
-serving host after the turn returns.
-
-`GET /v1/info` reports `result: true` when the file is authored.
-
-## Assert in evals
-
-`t.succeeded()` fails when `commit` throws or the turn produced no
-text, because those are turn failures. Read the document on `t.reply`.
-
-```ts
-import { defineEval, includes } from "@cursor/july/evals";
-
-export default defineEval({
-  async test(t) {
-    await t.send("Triage LIN-1842. It duplicates LIN-1801.");
-    t.succeeded();
-    t.check(t.reply, includes("duplicate"));
-  },
-});
-```
-
-## What's next
-
-Continue with these pages:
-
-- [Evals](../evals.md): `t.succeeded` and `t.reply`
-- [Sessions and streaming](./sessions.md): `turn.completed` and
-  `turn.failed`
-- [Hooks](./hooks.md): observe the stream after the turn has already
-  settled
-- [Project layout](./project-layout.md): where `agent/result.ts` lives

package/docs/scaffolding-agents.md

@@ -1,135 +0,0 @@
----
-title: "Scaffold an agent with Cursor"
-description: "Use the bundled create-agent skill to plan, build, and verify a new agent."
----
-
-# Scaffold an agent with Cursor
-
-Turn an idea into a verified agent while Cursor guides you through each
-decision.
-
-## What does the create-agent skill do?
-
-The bundled
-[`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:
-
-- Installing `@cursor/july` (`npm install`, `npx @cursor/july`, a
-  version bump) copies every package skill into
-  `~/.cursor/skills/agentsdk/` with `alwaysApply: true`, so Cursor
-  injects the skill body into context instead of waiting for the
-  model to pick it from the catalog. The `/` menu lists them as
-  `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
-  copies with the package version.
-- 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.md). Run
-  `agent-sdk install-skills` if you want the same copies in
-  `~/.cursor/skills/agentsdk/` (the package postinstall skips the
-  source checkout).
-
-Cursor will:
-
-- Ask only for choices missing from your prompt
-- Recommend defaults based on what you want to build
-- Show you the plan and file tree before writing files
-- Create the agent after you confirm the plan
-- Run structural checks, a real turn, and a smoke eval
-
-Use this skill for a new agent. Use
-[convert-automation](./guides/convert-automation.md) when the starting
-point is a Cursor Automation in the dashboard. Use
-[`hillclimb`](./hillclimbing.md) (`skills/hillclimb/SKILL.md`) when an
-existing agent works but needs better results.
-
-## How do I start a guided scaffold?
-
-Describe the outcome and any constraints you already know:
-
-> Build a local weather agent for the playground. Give it one tool for
-> current conditions and add a smoke eval. Guide me through the remaining
-> decisions.
-
-More detail means fewer questions. Include a channel, runtime, model, or
-required integration when those choices are fixed.
-
-## Which choices will Cursor ask me to make?
-
-Cursor fills gaps in two short rounds:
-
-- **Identity:** purpose, project name, and location
-- **Runtime:** local or cloud
-- **Model:** the default model or another Cursor model
-- **Channels:** playground and HTTP, Slack, GitHub, a webhook, or a
-  schedule
-- **MCP connections:** remote or local MCP servers
-- **Capabilities:** tools, skills, subagents, hooks, seed files,
-  approvals, and evals
-
-Questions adapt to your goal. A playground chat agent won't get
-cloud-repository questions. A local agent won't get cloud setup
-questions.
-
-## What happens before Cursor writes files?
-
-Cursor shows one plan with the choices it made and the folders it will
-create. Choose **Scaffold it** to continue or **Adjust something** to
-change the plan.
-
-No files change before you approve this step.
-
-## What will Cursor create?
-
-A first version usually includes:
-
-- `AGENTS.md`, `.gitignore`, `package.json`, and `tsconfig.json`
-- `agent/agent.ts` for the model and runtime
-- `agent/instructions.md` for the always-on prompt
-- `agent/hooks/memory.ts` for memory guidance
-- One or two tools under `agent/tools/`
-- Any channels or MCP connections you selected
-- `evals/evals.config.ts` and one smoke eval
-
-Cursor keeps the first version small. Side-effecting server tools use
-`needsApproval`. Deterministic setup, such as fetching a pull request,
-stays in host code instead of model instructions.
-
-See [Project layout](./reference/project-layout.md) for every supported
-folder.
-
-## How does Cursor verify the scaffold?
-
-Cursor checks the project in this order:
-
-1. Run `agent-sdk validate` and fix every error
-2. Inspect the discovered surface with `info --json`
-3. Call each server tool directly with validated sample input
-4. Run one end-to-end model turn
-5. Run the smoke eval
-6. Run the project's TypeScript check
-
-Validation, discovery, direct server-tool calls, and server startup work
-without a Cursor credential. Model turns and evals need
-`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`), then `CURSOR_SERVICE_ACCOUNT_KEY`, then a saved
-`agent-sdk login`.
-
-## What happens after the first agent works?
-
-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.md).
-
-The hillclimb skill measures a baseline, changes one lever, runs the same
-inputs again, and adds an eval for each improvement you keep.
-
-## Related
-
-- [Build your first PR reviewer](./quickstart.md)
-- [Convert a Cursor Automation](./guides/convert-automation.md)
-- [Building agents with agents](./building-with-agents.md)
-- [Evals](./evals.md)
-- [Hillclimbing](./hillclimbing.md)
-- [Project layout](./reference/project-layout.md)

package/docs/skills/index.md

@@ -1,26 +0,0 @@
----
-title: "Coding-agent skills"
-description: "Task guides that ship with the Agent SDK for scaffolding, deployment, 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 |
-| [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 |
-| [deploy](./deploy.md) | Deploy with an attached service account |
-| [debug](./debug.md) | Diagnose a local run |

package/docs/storage.md

@@ -1,172 +0,0 @@
----
-title: "Storage"
-description: "Point the Agent SDK's durable storage at a backend you own with defineStorage."
----
-
-# Storage
-
-The Agent SDK owns durable storage for sessions, continuation tokens,
-reminders, and playground eval history. It chooses the keys, when to
-read and write, and how to restore after restart.
-
-The Agent SDK owns key encoding. Backends must accept the keys they are
-given. Do not fail `put` to enforce a shorter cap.
-
-By default that storage lives under `--state-root` on local disk. Fine
-for one machine; it does not survive replacing the host.
-
-To keep the same framework storage across hosts, plug in a key-value
-backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
-`list`. The optional `cas` group adds conditional writes (see
-[Conditional writes](#conditional-writes-the-cas-group)).
-
-```ts
-// agent/storage.ts
-import { defineStorage } from "@cursor/july/storage";
-
-export default defineStorage({
-  put: (key, value) => db.upsert(key, value),
-  get: (key) => db.get(key),
-  delete: (key) => db.delete(key),
-  list: (prefix) => db.listByPrefix(prefix), // [{ key, value }], key order
-  cas: {
-    getWithVersion: (key) => db.getRow(key), // { value, version }
-    putIfAbsent: (key, value) => db.insertIfAbsent(key, value),
-    putIfVersion: (key, value, expected) => db.casUpdate(key, value, expected),
-    listKeys: (prefix) => db.listKeysByPrefix(prefix),
-  },
-});
-```
-
-## Which fields to provide
-
-Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
-group) and you get **full functionality**: eval-run history is derived
-over the core automatically. The dedicated `evals` group is a
-backend-native optimization, not a required-or-lose-history hook.
-
-| Field | Required | Role |
-| --- | --- | --- |
-| `put` | Yes | Write or update a value |
-| `cas` | Optional | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
-| `get` | For restore | Look up one key |
-| `list` | For restore | Return entries under a prefix, in key order |
-| `delete` | For cleanup | Remove a key |
-| `name` | No | Label surfaced on `GET /v1/info` diagnostics |
-| `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval table](#eval-table) |
-
-A throwing `put` is logged and dropped. It never fails a turn. When
-resolving a missing continuation token, a throwing `get` fails the
-follow-up so a store outage does not open a new session. Return
-`undefined` only for a real miss.
-
-## Eval table
-
-The dedicated `evals` table group carries structured rows instead of
-opaque KV values. It is an **optional optimization**: when the group is
-not authored, `defineStorage` derives it over the KV core, so a backend
-that implements only the core loses nothing. Author the group only when
-the backend has a better native shape (a real database table, an
-analytics pipeline). The built-in `fileKv` and `cursorHostedStorage`
-both do.
-
-`evals` keeps playground eval batches across restarts (`put`, `delete`,
-`list` over run snapshots keyed by `runId`). A core missing `delete` or
-`list` leaves eval history in memory until restart.
-See [Evals](./evals.md#configure-eval-runs).
-
-## Policy
-
-Two knobs change behavior:
-
-```ts
-export default defineStorage({
-  policy: {
-    // Batch event writes while the session is busy (default: once per turn)
-    debounceMs: 30_000,
-    // Cap how much loads at serve start, or "off" to restore on demand
-    restore: { maxSessions: 500 },
-  },
-  // put / get / delete / list …
-});
-```
-
-| Knob | Default | Meaning |
-| --- | --- | --- |
-| `debounceMs` | unset (once per turn) | Wait this long after activity before writing event batches |
-| `restore` | caps below | How much to load at serve start |
-| `restore.maxSessions` | `1000` | Max sessions loaded at serve start |
-| `restore.maxAgeMs` | 30 days | Skip older sessions at serve start |
-| `restore.maxTotalBytes` | 1 GiB | Stop loading once this budget is reached |
-
-Set `restore: "off"` on high-traffic hosts. Sessions then load when a
-follow-up arrives instead of at startup.
-
-## Restore after restart
-
-With `get` and `list`, serve can rebuild local state from your store:
-
-- At startup, the Agent SDK loads recent sessions up to the restore caps.
-- On demand, a missing continuation token resolves through the store
-  and resumes that session.
-- Playground eval history can load from the same sink.
-
-A turn in flight at crash time is not replayed. The next follow-up
-resumes from the last flushed state.
-
-## Author KV (`ctx.host.kv`)
-
-Handlers can store their own JSON under the same sink without minting
-framework keys:
-
-```ts
-await ctx.host.kv.put("alert-memory/abc", { updated: "…" });
-const prior = await ctx.host.kv.get("alert-memory/abc");
-```
-
-Writes **await** the sink and propagate errors, unlike session mirrors,
-which are at-most-once.
-
-Without `agent/storage.ts`, `host.kv` is local-only and does not
-survive replacing the host. Hosted agents should author
-`cursorHostedStorage()` so session and `host.kv` records survive
-replace.
-
-```ts
-// agent/storage.ts: Cursor-managed hosting
-import { defineStorage } from "@cursor/july/storage";
-import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
-
-export default defineStorage({
-  ...cursorHostedStorage(),
-});
-```
-
-Built-in helpers:
-
-| Import | Backend |
-| --- | --- |
-| `@cursor/july/storage/file-kv` | File-per-key under the project state directory |
-| `@cursor/july/storage/cursor-hosted` | Cursor-managed hosting; records survive replace |
-
-## Bring your own backend
-
-Any durable store works if it can put, get, delete, list by prefix,
-and optionally compare-and-set. Implement the `StorageConfig` methods
-(and the optional `cas` group) against that store. The contract,
-defined at `@cursor/july/kv`: version tokens are opaque strings that
-change on every successful write, including plain `put`, so a stale
-token fences instead of clobbering; conditional writes are atomic;
-`listKeys` returns every key under the prefix.
-
-## Conditional writes (the `cas` group)
-
-The `cas` group is compare-and-swap over the same keyspace:
-`getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
-backend-agnostically at `@cursor/july/kv`. Plain storage works without
-it, so an existing backend keeps working across a platform upgrade.
-`defineStorage` rejects a partial group. Implement all four methods or
-none. Version tokens are opaque strings that must change on every write
-(a counter column, a row version, a content hash). The built-in backends
-both include the group.

package/docs/templates/agents-md.md

@@ -1,110 +0,0 @@
----
-title: "Keep AGENTS.md current from last week's work"
-description: "Scaffold the agent, pick a repo and Slack channels, dispatch the weekly job, and deploy."
----
-
-# Keep AGENTS.md current from last week's work
-
-This agent runs every Monday at 09:00 UTC. It reads last week's merged
-pull requests and the Slack channels you list. When a durable rule
-showed up, `apply_agents` parks the write until a person approves it,
-then opens a draft follow-up pull request against the default branch.
-Chores and rules the file already states stay quiet.
-
-This template is one model turn: read the week, then call
-`apply_agents`.
-
-Init once per app. Pass a different repo and channel list each time.
-
-## Scaffold
-
-```bash
-npx @cursor/july init ./agents-md --template agents-md
-```
-
-`init` asks which GitHub repo to watch and which Slack channels to
-read. Pass `--var repos=acme/api --var slack=#eng-api,#api-private`
-to skip the prompt. Use `--var slack=none` when Slack is out of
-scope.
-
-The answers land in `agent/lib/config.ts`. Edit that file when the
-set changes.
-
-## Connect GitHub and Slack
-
-Connect GitHub in Cursor for that repository (Settings or
-[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host
-in:
-
-```bash
-cd agents-md
-agent-sdk login
-```
-
-`cursorAccount` mints a short-lived, repo-scoped credential with
-`contents-write` so the agent can open the follow-up PR. See the
-[GitHub guide](../guides/github.md).
-
-Create the Slack app and invite the bot to each listed channel,
-including private ones:
-
-```bash
-agent-sdk slack create --dir .
-```
-
-See the [Slack guide](../guides/slack.md).
-
-## First weekly run
-
-```bash
-agent-sdk dev
-```
-
-Schedules never fire under `dev`. Dispatch the same path production
-uses:
-
-```bash
-curl -X POST http://127.0.0.1:3000/v1/dev/schedules/weekly
-```
-
-The playground can run `/queue/run` too.
-
-The host writes `week/prs.md`, `week/slack.md`, `week/window.txt`,
-and `week/tree/**.txt` snapshots of the current `AGENTS.md` files,
-then starts a model turn. The
-model calls `apply_agents` once. A skip finishes. An update parks in
-the playground until someone approves; then a draft PR opens against
-the repository default branch. Later updates to the same base stack
-on `agents-md/<base>`. Pull requests from those branches are ignored
-so the follow-up cannot feed the next week.
-
-Chat replies stay in the playground. `apply_agents` records a skip,
-or parks the write. Approve there or with
-`POST /v1/session/:id/approvals/:callId`.
-
-## What to edit
-
-- `agent/lib/config.ts`: repo and Slack channels
-- `agent/instructions.md`: what counts as an update
-- `evals/agents.eval.ts`: smoke cases
-
-## Evals
-
-Four smoke cases: a lint-only week, a billing rule that parks the
-write, the same rule already in `AGENTS.md`, and an empty week.
-
-```bash
-agent-sdk eval
-```
-
-Eval sessions skip the GitHub write.
-
-## Deploy
-
-```bash
-agent-sdk deploy
-```
-
-Run it from the agent's git checkout. The command infers repository,
-ref, path, and slug. Production fires the Monday cron. The deployment
-uses the team's Cursor GitHub connection for the watched repo.