@cursor/july 0.1.22 → 0.1.24

package/dist/docs/assets/index.md.t0TM2Qzz.js

@@ -1,20 +0,0 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function o(r,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="agentkit-documentation" tabindex="-1">agentkit documentation <a class="header-anchor" href="#agentkit-documentation" aria-label="Permalink to &quot;agentkit documentation&quot;">​</a></h1><p>agentkit helps you build your own software factory: agents that inspect builds, review pull requests, gate promotions, and wake from Slack or GitHub when work arrives. You author each agent as ordinary files in a TypeScript project under <code>agent/</code>: markdown for agent instruction prompts, TypeScript for typed behavior. The framework discovers those files, and serves the agent over channels. The Cursor SDK and the Cursor harness run the turns.</p><p>You write the tools, instructions, channels, and evals. In return you get a factory you can version, test, and ship: side effects stay behind human approvals, and every change stays regression-checked.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
-<span class="line"><span>├── package.json</span></span>
-<span class="line"><span>├── agent/</span></span>
-<span class="line"><span>│   ├── agent.ts             # runtime config: model, local/cloud runtime</span></span>
-<span class="line"><span>│   ├── instructions.md      # the always-on system prompt</span></span>
-<span class="line"><span>│   ├── tools/               # one typed tool per file</span></span>
-<span class="line"><span>│   ├── skills/              # on-demand procedures (SKILL.md convention)</span></span>
-<span class="line"><span>│   ├── mcp-connections/     # tools from external MCP servers</span></span>
-<span class="line"><span>│   ├── subagents/           # specialist child agents</span></span>
-<span class="line"><span>│   ├── channels/            # HTTP / Slack / GitHub surfaces</span></span>
-<span class="line"><span>│   ├── hooks/               # observe the runtime event stream</span></span>
-<span class="line"><span>│   ├── ab.ts                # optional live A/B experiment</span></span>
-<span class="line"><span>│   ├── ab/                  # optional: more experiments</span></span>
-<span class="line"><span>│   ├── schedules/           # cron-driven runs</span></span>
-<span class="line"><span>│   ├── sandbox/workspace/   # files seeded into each session workspace</span></span>
-<span class="line"><span>│   └── lib/                 # shared code (import-only, never discovered)</span></span>
-<span class="line"><span>└── evals/                   # filesystem evals (regression checks)</span></span></code></pre></div><p>Every running serve host also mounts this documentation at <code>/docs</code> (disable it with <code>--no-docs</code>).</p><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><p>Pick your entry point based on your goal.</p><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to agentkit</td><td><a href="./quickstart.html">Quickstart</a> (PR approver), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="the-documentation" tabindex="-1">The documentation <a class="header-anchor" href="#the-documentation" aria-label="Permalink to &quot;The documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR approver that reviews by complexity and wakes from webhooks.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./concepts.html">Concepts</a>: the mental model behind the framework.</li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: make an agent better one measured round at a time.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: wake the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and <code>--store</code> them on hosted deployments.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare all eleven agents by runtime, channels, tools, state, and architecture.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/fsd.html">Remote PR coordinator</a>: hand PR triage from local chat and webhooks to durable remote sessions.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: symptom to cause, in plain language.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>The docs write commands as <code>agentkit &lt;command&gt;</code>. Where that command comes from depends on where you run.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>When running from a source checkout there is no installed bin. Alias it from the package directory:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> packages/agent-serve</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">alias</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> agentkit</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pnpm exec tsx </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/src/bin/agent-serve.ts&quot;</span></span></code></pre></div><p>When <code>@cursor/july</code> is installed as a dependency, the <code>agentkit</code> bin is on your package manager&#39;s path (<code>pnpm exec agentkit</code>, <code>npx agentkit</code>).</p></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The framework is being renamed from agent-serve to agentkit, and CLI examples use the new <code>agentkit</code> name. Paths, package imports, and environment variables keep their current names until the code rename ships:</p><table tabindex="0"><thead><tr><th>Docs say</th><th>Current name</th></tr></thead><tbody><tr><td><code>@cursor/july</code> imports and dependency</td><td><code>@cursor/july</code></td></tr><tr><td><code>agentkit</code> bin</td><td><code>agent-serve</code></td></tr><tr><td><code>dist/bin/agentkit.js</code></td><td><code>dist/bin/agent-serve.js</code></td></tr><tr><td><code>.agentkit/</code> state directory</td><td><code>.agent-serve/</code></td></tr><tr><td><code>/var/lib/agentkit</code> (deploy state root)</td><td><code>/var/lib/agent-serve</code></td></tr><tr><td><code>CURSOR_AGENT_KIT_*</code> env vars</td><td><code>AGENT_SERVE_*</code></td></tr><tr><td><code>agentkit (&lt;hostname&gt;)</code> API key name</td><td><code>agent-serve (&lt;hostname&gt;)</code></td></tr><tr><td>Package path <code>packages/agentkit</code></td><td><code>packages/agent-serve</code></td></tr><tr><td>Package skills <code>packages/agentkit/skills/</code></td><td><code>packages/agent-serve/skills/</code></td></tr></tbody></table></div><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Run agentkit with Node 22.13 or newer, and never with Bun. Bun&#39;s HTTP/2 client corrupts the Cursor SDK&#39;s tool-result streams (<code>NGHTTP2_FRAME_SIZE_ERROR</code>), so every built-in read or grep the model makes fails and turns degrade into minutes-long retry loops.</p></div><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Model turns run on the Cursor harness, so the serving host needs a Cursor credential. Sign in once, or export an API key:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # browser sign-in; mints + stores a revocable API key</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">         # which account powers this host, and why</span></span></code></pre></div><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><p>These docs describe behavior. The package <a href="./../README.html"><code>README.md</code></a> is the compact reference, and <a href="./../AGENTS.html"><code>AGENTS.md</code></a> is the coding-agent cheat sheet. Task-shaped guides that ship with the package live under <a href="./../skills/"><code>skills/</code></a>; point a coding agent working on a agentkit project at them first. When the docs and the code disagree, the code is authoritative. Fix the doc.</p>`,31)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};

package/dist/internal/json-dir-store.d.ts

@@ -1,32 +0,0 @@
-/**
- * Small filesystem helpers for one-JSON-file-per-id persistence under a
- * project-relative directory (eval run snapshots, A/B aggregate snapshots).
- */
-export declare function assertNonEmptyDir(dir: string, fnName: string): string;
-/** Resolve `dir` against `projectRoot` when relative. */
-export declare function resolveProjectRelativeDir(args: {
-    dir: string;
-    projectRoot: string;
-}): string;
-/** List `*.json` basenames in `root` (any order). Missing dir → []. */
-export declare function listJsonBasenames(root: string): Promise<string[]>;
-/**
- * Read and JSON.parse every `*.json` file under `root`. Missing dir → [].
- * Unreadable or corrupt files are skipped so one bad snapshot cannot wipe
- * the rest of the history.
- */
-export declare function readJsonDir<T>(root: string, options?: {
-    sortBasenames?: "asc" | "desc";
-}): Promise<T[]>;
-/** Atomically write JSON under `root`/`fileName` (temp file + rename). */
-export declare function writeJsonFile(args: {
-    root: string;
-    fileName: string;
-    value: unknown;
-}): Promise<void>;
-/** Best-effort delete; ignores missing files. */
-export declare function deleteFileInDir(args: {
-    root: string;
-    fileName: string;
-}): Promise<void>;
-//# sourceMappingURL=json-dir-store.d.ts.map

package/dist/internal/json-dir-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json-dir-store.d.ts","sourceRoot":"","sources":["../../src/internal/json-dir-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAET;AAWD,uEAAuE;AACvE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWvE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBd;AAED,0EAA0E;AAC1E,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB"}

package/dist/internal/json-dir-store.js

@@ -1,100 +0,0 @@
-/**
- * Small filesystem helpers for one-JSON-file-per-id persistence under a
- * project-relative directory (eval run snapshots, A/B aggregate snapshots).
- */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { randomBytes } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
-import { isAbsolute, join } from "node:path";
-export function assertNonEmptyDir(dir, fnName) {
-    if (typeof dir !== "string" || dir.trim() === "") {
-        throw new Error(`${fnName}: dir must be a non-empty string`);
-    }
-    return dir;
-}
-/** Resolve `dir` against `projectRoot` when relative. */
-export function resolveProjectRelativeDir(args) {
-    return isAbsolute(args.dir) ? args.dir : join(args.projectRoot, args.dir);
-}
-function isEnoent(error) {
-    return (error !== null &&
-        typeof error === "object" &&
-        "code" in error &&
-        error.code === "ENOENT");
-}
-/** List `*.json` basenames in `root` (any order). Missing dir → []. */
-export function listJsonBasenames(root) {
-    return __awaiter(this, void 0, void 0, function* () {
-        let names;
-        try {
-            names = yield readdir(root);
-        }
-        catch (error) {
-            if (isEnoent(error)) {
-                return [];
-            }
-            throw error;
-        }
-        return names.filter((name) => name.endsWith(".json"));
-    });
-}
-/**
- * Read and JSON.parse every `*.json` file under `root`. Missing dir → [].
- * Unreadable or corrupt files are skipped so one bad snapshot cannot wipe
- * the rest of the history.
- */
-export function readJsonDir(root, options) {
-    return __awaiter(this, void 0, void 0, function* () {
-        let names = yield listJsonBasenames(root);
-        if ((options === null || options === void 0 ? void 0 : options.sortBasenames) === "asc") {
-            names = [...names].sort();
-        }
-        else if ((options === null || options === void 0 ? void 0 : options.sortBasenames) === "desc") {
-            names = [...names].sort().reverse();
-        }
-        const out = [];
-        for (const name of names) {
-            try {
-                const raw = yield readFile(join(root, name), "utf8");
-                out.push(JSON.parse(raw));
-            }
-            catch (_a) {
-                // skip corrupt / unreadable files
-            }
-        }
-        return out;
-    });
-}
-/** Atomically write JSON under `root`/`fileName` (temp file + rename). */
-export function writeJsonFile(args) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const { root, fileName, value } = args;
-        // Serialize before any await so callers get a stable snapshot even if they
-        // mutate `value` afterward.
-        const body = `${JSON.stringify(value, null, 2)}\n`;
-        yield mkdir(root, { recursive: true });
-        const finalPath = join(root, fileName);
-        const tmpPath = `${finalPath}.${randomBytes(4).toString("hex")}.tmp`;
-        yield writeFile(tmpPath, body, "utf8");
-        yield rename(tmpPath, finalPath);
-    });
-}
-/** Best-effort delete; ignores missing files. */
-export function deleteFileInDir(args) {
-    return __awaiter(this, void 0, void 0, function* () {
-        try {
-            yield rm(join(args.root, args.fileName), { force: true });
-        }
-        catch (_a) {
-            // ignore
-        }
-    });
-}