@cursor/july 0.1.22 → 0.1.24

package/README.md

@@ -14,11 +14,11 @@ over channels, using the Cursor SDK (`@cursor/sdk`) and the Cursor harness
 as the execution engine.
 
 **User-facing documentation lives in [`docs/`](./docs/README.md)** —
-also served at `/docs` by every running `agent-serve serve` host —
-getting started, concepts, guides (Slack, GitHub webhooks, approvals,
-agent-to-agent, cloud runtime), evals, live A/B metrics, hillclimbing,
-deployment, troubleshooting, and reference pages for each folder. This
-README is the compact package reference.
+open it with `npx @cursor/july docs`, or at `/docs` on every running
+`agent-serve serve` host — getting started, concepts, guides (Slack,
+GitHub webhooks, approvals, agent-to-agent, cloud runtime), evals, live
+A/B metrics, hillclimbing, deployment, troubleshooting, and reference
+pages for each folder. This README is the compact package reference.
 
 Instead of one large configuration object, each part of the agent gets a
 clear home. Instructions go in one file, tools in one folder, channels in

package/dist/bin/agent-serve.d.ts

@@ -4,6 +4,7 @@
  *
  *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
  *   agent-serve dev        [path] [--port 3000] [--host 127.0.0.1]
+ *   agent-serve docs       [--port 0] [--host 127.0.0.1] [--print]
  *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
  *   agent-serve resume    [sessionId] [--url | --prod] [--message "..."]
  *   agent-serve run       [--dir .] [--message "..."] [--json|--text]

package/dist/bin/agent-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-serve.d.ts","sourceRoot":"","sources":["../../src/bin/agent-serve.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}
+{"version":3,"file":"agent-serve.d.ts","sourceRoot":"","sources":["../../src/bin/agent-serve.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/bin/agent-serve.js

@@ -4,6 +4,7 @@
  *
  *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
  *   agent-serve dev        [path] [--port 3000] [--host 127.0.0.1]
+ *   agent-serve docs       [--port 0] [--host 127.0.0.1] [--print]
  *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
  *   agent-serve resume    [sessionId] [--url | --prod] [--message "..."]
  *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
@@ -58,6 +59,7 @@ Usage:
                           [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} playground  [--url <baseUrl> | --prod] [--session <id>] [--print]
                           [--slug <slug>] [--team <id>] [--dir <path>]
+  ${CLI} docs        [--port <n>] [--host <host>] [--print]
   ${CLI} run         [--dir <path>] [--message <text>]... [--url <baseUrl> | --prod]
                           [--session <id>] [--continuation-token <t>]
                           [--events <file.ndjson>] [--no-events] [--text]
@@ -134,6 +136,9 @@ Commands:
   playground  Open the web playground. --prod starts a loopback proxy that
               injects hosted engine credentials (browsers cannot set them).
               --print skips opening a browser. Ctrl-C stops the proxy.
+  docs        Serve the shipped documentation site on loopback and open it
+              (also: npx @cursor/july docs). No agent project required.
+              --print skips opening a browser. Ctrl-C stops the server.
   run         One-shot create→test loop: ephemeral server + JSON trajectory.
               Writes a single events.ndjson trace (visualize in the playground).
               Streams tool calls and reply text to stderr when stderr is a TTY.
@@ -269,9 +274,9 @@ Options:
                      persisted server-side batch (default is local).
   --once             logs: print current progress / log buffer once and exit
                      (default is to follow).
-  --print            playground: print the URL only; do not open a browser.
-                     install-skills: list the skills and the install path
-                     without writing them.
+  --print            playground/docs: print the URL only; do not open a
+                     browser. install-skills: list the skills and the install
+                     path without writing them.
   --no-wait          deploy/stop/eval: return right after the request is
                      accepted instead of polling until a terminal status.
                      For eval, prints the runId (deployment / --url only).
@@ -805,6 +810,19 @@ function main(argv) {
                     print: values.print,
                 }));
             }
+            case "docs": {
+                const docsPort = values.port === undefined ? 0 : Number.parseInt(values.port, 10);
+                if (Number.isNaN(docsPort) || docsPort < 0 || docsPort > 65535) {
+                    process.stderr.write(`invalid --port: ${values.port}\n`);
+                    return 1;
+                }
+                const { cmdDocs } = yield import("../internal/cli-docs.js");
+                return cmdDocs({
+                    port: docsPort,
+                    host: values.host,
+                    print: values.print === true,
+                });
+            }
             case "validate": {
                 const mounts = yield loadMounts(dir);
                 let hasError = false;

package/dist/docs/404.html

@@ -9,14 +9,14 @@
     <link rel="preload stylesheet" href="/docs/assets/style.Bj-IXa5W.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.BKNKMLp4.js"></script>
+    <script type="module" src="/docs/assets/app.CvSGaAxk.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"BMCZ6Hd7\",\"building-with-agents.md\":\"CJCtZCyi\",\"concepts.md\":\"Cfb9b-k1\",\"deployment.md\":\"TecHo0_2\",\"evals.md\":\"DYOjkRCX\",\"example-agents_approval-buddy.md\":\"DFGBYLcc\",\"example-agents_benny.md\":\"B0gjhI-p\",\"example-agents_bugbot.md\":\"DelIdhxB\",\"example-agents_codebase-wiki.md\":\"DC6sgwn0\",\"example-agents_codeowners-review.md\":\"Ku_tG2RY\",\"example-agents_concierge.md\":\"4rQTSMXt\",\"example-agents_fsd.md\":\"CzgUrDfi\",\"example-agents_index.md\":\"D2PEVSXl\",\"example-agents_knowledge-base.md\":\"BPJiVueF\",\"example-agents_oncall.md\":\"BG_sUMly\",\"example-agents_security-reviewer.md\":\"Dhj_m7_B\",\"example-agents_slack-agent.md\":\"buLbgvBf\",\"example-agents_weather-agent.md\":\"C9Qv-W0o\",\"guides_agent-to-agent.md\":\"Bpzgq2Pq\",\"guides_cloud-runtime.md\":\"gVzabdQL\",\"guides_github.md\":\"DOOCpqsW\",\"guides_human-in-the-loop.md\":\"DlUqsp1S\",\"guides_mcp-oauth.md\":\"Dd8EgSem\",\"guides_slack.md\":\"D_xFKlnF\",\"guides_webhooks.md\":\"B1EswtUu\",\"hillclimbing.md\":\"DHNast08\",\"index.md\":\"t0TM2Qzz\",\"quickstart.md\":\"BU6Iwi_9\",\"reference_agent-config.md\":\"DrW2JUM8\",\"reference_channels.md\":\"DdmiKgqf\",\"reference_cli.md\":\"DnYfr5V2\",\"reference_connections.md\":\"B9Q3TOve\",\"reference_hooks.md\":\"DyLVfE1O\",\"reference_http-api.md\":\"BncLd3PZ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"Bd_CKtNS\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"w_F2mXB6\",\"reference_sessions.md\":\"DLd6mvbv\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"zWAMNfi1\",\"reference_tools.md\":\"BRSDnTbN\",\"scaffolding-agents.md\":\"C3pTrmoE\",\"storage.md\":\"DRTdnFvd\",\"troubleshooting.md\":\"CmQkmnzC\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"agentkit\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"BMCZ6Hd7\",\"building-with-agents.md\":\"CJCtZCyi\",\"concepts.md\":\"Cfb9b-k1\",\"deployment.md\":\"TecHo0_2\",\"evals.md\":\"DYOjkRCX\",\"example-agents_approval-buddy.md\":\"DFGBYLcc\",\"example-agents_benny.md\":\"B0gjhI-p\",\"example-agents_bugbot.md\":\"DelIdhxB\",\"example-agents_codebase-wiki.md\":\"DC6sgwn0\",\"example-agents_codeowners-review.md\":\"Ku_tG2RY\",\"example-agents_concierge.md\":\"4rQTSMXt\",\"example-agents_fsd.md\":\"CzgUrDfi\",\"example-agents_index.md\":\"D2PEVSXl\",\"example-agents_knowledge-base.md\":\"BPJiVueF\",\"example-agents_oncall.md\":\"BG_sUMly\",\"example-agents_security-reviewer.md\":\"Dhj_m7_B\",\"example-agents_slack-agent.md\":\"buLbgvBf\",\"example-agents_weather-agent.md\":\"C9Qv-W0o\",\"guides_agent-to-agent.md\":\"Bpzgq2Pq\",\"guides_cloud-runtime.md\":\"gVzabdQL\",\"guides_github.md\":\"DOOCpqsW\",\"guides_human-in-the-loop.md\":\"DlUqsp1S\",\"guides_mcp-oauth.md\":\"Dd8EgSem\",\"guides_slack.md\":\"D_xFKlnF\",\"guides_webhooks.md\":\"B1EswtUu\",\"hillclimbing.md\":\"DHNast08\",\"index.md\":\"Dfv5ic9t\",\"quickstart.md\":\"BU6Iwi_9\",\"reference_agent-config.md\":\"DrW2JUM8\",\"reference_channels.md\":\"DdmiKgqf\",\"reference_cli.md\":\"ccoKOoXt\",\"reference_connections.md\":\"B9Q3TOve\",\"reference_hooks.md\":\"DyLVfE1O\",\"reference_http-api.md\":\"BncLd3PZ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"Bd_CKtNS\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"w_F2mXB6\",\"reference_sessions.md\":\"DLd6mvbv\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"zWAMNfi1\",\"reference_tools.md\":\"BRSDnTbN\",\"scaffolding-agents.md\":\"C3pTrmoE\",\"storage.md\":\"DRTdnFvd\",\"troubleshooting.md\":\"CmQkmnzC\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"agentkit\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist/docs/ab.html

@@ -9,9 +9,9 @@
     <link rel="preload stylesheet" href="/docs/assets/style.Bj-IXa5W.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.BKNKMLp4.js"></script>
+    <script type="module" src="/docs/assets/app.CvSGaAxk.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/docs/assets/chunks/theme.BvCHT5lj.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.C7vfzr7h.js">
     <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
     <link rel="modulepreload" href="/docs/assets/ab.md.BMCZ6Hd7.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
@@ -81,7 +81,7 @@
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Save aggregate snapshots whenever GET /v1/abs runs</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  persistSnapshots: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">persistABSnapshotsToDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.agent-serve/ab-snapshots&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>maxPlaygroundSessions</code></td><td><code>200</code></td><td>Max newest sessions folded into the playground / <code>GET /v1/abs</code> (not session logs or <code>persistSamples</code>)</td></tr><tr><td><code>persistSamples</code></td><td>unset</td><td>Durable sink for metric samples (<code>save(sample, ctx)</code>)</td></tr><tr><td><code>persistSnapshots</code></td><td>unset</td><td>Durable store for aggregate snapshots (<code>load</code> / <code>save</code> / optional <code>delete</code>)</td></tr><tr><td><code>retainSnapshots</code></td><td><code>20</code> when snapshots persist</td><td>Snapshot files kept after prune (<code>persistABSnapshotsToDir</code> honors this)</td></tr></tbody></table><p>Implement your own <code>{ save }</code> / <code>{ load, save, delete? }</code> for S3, a DB, or your metrics vendor. Without <code>persistSamples</code> / <code>persistSnapshots</code>, samples only go where each experiment&#39;s <code>onSample</code> sends them, and aggregates exist only as a live fold over session logs.</p><h2 id="keep-assignments-durable" tabindex="-1">Keep assignments durable <a class="header-anchor" href="#keep-assignments-durable" aria-label="Permalink to &quot;Keep assignments durable&quot;">​</a></h2><p>The append-only <code>events.ndjson</code> stream is the source of truth. Each <code>ab.assigned</code> event persists a variant key or null skip. Built-in metrics come from the turn and tool events that follow it.</p><p>After a server restart or a parked session resumes, the live collector replays the stream to rebuild cumulative counters. Replay does not call <code>onSample</code> (or <code>persistSamples</code>) for historical turns. Only a new completed or failed turn emits another sample.</p><p>The snapshot API also replays <code>derive</code> across the full stream, so custom totals match the current extractor. Changing a derive function can change historical snapshot totals. Treat metric definitions as versioned experiment code.</p><h2 id="keep-eval-traffic-separate" tabindex="-1">Keep eval traffic separate <a class="header-anchor" href="#keep-eval-traffic-separate" aria-label="Permalink to &quot;Keep eval traffic separate&quot;">​</a></h2><p>Sessions created by <code>agentkit eval</code> and the playground Evals runner use <code>purpose: &quot;eval&quot;</code>. They skip A/B enrollment entirely:</p><ul><li>No split function runs.</li><li>No <code>ab.assigned</code> event is recorded.</li><li>No <code>onSample</code> callback fires.</li><li>The session is omitted from <code>GET /v1/abs</code>.</li></ul><p>Ordinary chat, <code>agentkit run</code>, Slack, GitHub, and other channel sessions use the live purpose. You do not need <code>splitIf</code> to exclude eval traffic.</p><h2 id="know-the-boundaries" tabindex="-1">Know the boundaries <a class="header-anchor" href="#know-the-boundaries" aria-label="Permalink to &quot;Know the boundaries&quot;">​</a></h2><p><code>defineAB</code> provides sticky assignment, variant instructions, <code>session.abs</code> for tools, cumulative metrics, and local inspection. It does not provide:</p><ul><li>A test command, assertion API, or pass/fail result</li><li>Statistical significance calculations</li><li>An experiment rollout or lifecycle service</li><li>Per-variant model or runtime configuration</li><li>A built-in analytics warehouse (bring your own via <code>persistSamples</code> / <code>persistSnapshots</code> / <code>onSample</code>)</li></ul><p>Use <a href="./evals.html">evals</a> to protect known behavior. Configure <code>agent/ab.config.ts</code> (or <code>onSample</code>) when you need sample/snapshot exports beyond the session event log.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./evals.html">Evals</a>: pass/fail regression checks on fixed inputs</li><li><a href="./hillclimbing.html">Hillclimbing</a>: improve an agent against fixed fixtures</li><li><a href="./reference/hooks.html">Hooks</a>: other event-stream consumers</li><li><a href="./reference/sessions.html">Sessions and streaming</a>: the <code>ab.assigned</code> event and durable log</li><li><a href="./reference/playground.html">Playground</a>: the A/Bs tab</li><li><a href="./reference/http-api.html">HTTP API</a>: <code>GET /v1/abs</code></li><li><a href="./../skills/ab/SKILL.html">Live A/B metrics skill</a>: have a coding agent wire an experiment</li></ul></div></div></main><footer class="VPDocFooter" data-v-53b9fda6 data-v-3958cc3f><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-3958cc3f><span class="visually-hidden" id="doc-footer-aria-label" data-v-3958cc3f>Pager</span><div class="pager" data-v-3958cc3f><a class="VPLink link pager-link prev" href="/docs/evals.html" data-v-3958cc3f><!--[--><span class="desc" data-v-3958cc3f>Previous page</span><span class="title" data-v-3958cc3f>Evals</span><!--]--></a></div><div class="pager" data-v-3958cc3f><a class="VPLink link pager-link next" href="/docs/storage.html" data-v-3958cc3f><!--[--><span class="desc" data-v-3958cc3f>Next page</span><span class="title" data-v-3958cc3f>Storage</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"BMCZ6Hd7\",\"building-with-agents.md\":\"CJCtZCyi\",\"concepts.md\":\"Cfb9b-k1\",\"deployment.md\":\"TecHo0_2\",\"evals.md\":\"DYOjkRCX\",\"example-agents_approval-buddy.md\":\"DFGBYLcc\",\"example-agents_benny.md\":\"B0gjhI-p\",\"example-agents_bugbot.md\":\"DelIdhxB\",\"example-agents_codebase-wiki.md\":\"DC6sgwn0\",\"example-agents_codeowners-review.md\":\"Ku_tG2RY\",\"example-agents_concierge.md\":\"4rQTSMXt\",\"example-agents_fsd.md\":\"CzgUrDfi\",\"example-agents_index.md\":\"D2PEVSXl\",\"example-agents_knowledge-base.md\":\"BPJiVueF\",\"example-agents_oncall.md\":\"BG_sUMly\",\"example-agents_security-reviewer.md\":\"Dhj_m7_B\",\"example-agents_slack-agent.md\":\"buLbgvBf\",\"example-agents_weather-agent.md\":\"C9Qv-W0o\",\"guides_agent-to-agent.md\":\"Bpzgq2Pq\",\"guides_cloud-runtime.md\":\"gVzabdQL\",\"guides_github.md\":\"DOOCpqsW\",\"guides_human-in-the-loop.md\":\"DlUqsp1S\",\"guides_mcp-oauth.md\":\"Dd8EgSem\",\"guides_slack.md\":\"D_xFKlnF\",\"guides_webhooks.md\":\"B1EswtUu\",\"hillclimbing.md\":\"DHNast08\",\"index.md\":\"t0TM2Qzz\",\"quickstart.md\":\"BU6Iwi_9\",\"reference_agent-config.md\":\"DrW2JUM8\",\"reference_channels.md\":\"DdmiKgqf\",\"reference_cli.md\":\"DnYfr5V2\",\"reference_connections.md\":\"B9Q3TOve\",\"reference_hooks.md\":\"DyLVfE1O\",\"reference_http-api.md\":\"BncLd3PZ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"Bd_CKtNS\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"w_F2mXB6\",\"reference_sessions.md\":\"DLd6mvbv\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"zWAMNfi1\",\"reference_tools.md\":\"BRSDnTbN\",\"scaffolding-agents.md\":\"C3pTrmoE\",\"storage.md\":\"DRTdnFvd\",\"troubleshooting.md\":\"CmQkmnzC\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"agentkit\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"BMCZ6Hd7\",\"building-with-agents.md\":\"CJCtZCyi\",\"concepts.md\":\"Cfb9b-k1\",\"deployment.md\":\"TecHo0_2\",\"evals.md\":\"DYOjkRCX\",\"example-agents_approval-buddy.md\":\"DFGBYLcc\",\"example-agents_benny.md\":\"B0gjhI-p\",\"example-agents_bugbot.md\":\"DelIdhxB\",\"example-agents_codebase-wiki.md\":\"DC6sgwn0\",\"example-agents_codeowners-review.md\":\"Ku_tG2RY\",\"example-agents_concierge.md\":\"4rQTSMXt\",\"example-agents_fsd.md\":\"CzgUrDfi\",\"example-agents_index.md\":\"D2PEVSXl\",\"example-agents_knowledge-base.md\":\"BPJiVueF\",\"example-agents_oncall.md\":\"BG_sUMly\",\"example-agents_security-reviewer.md\":\"Dhj_m7_B\",\"example-agents_slack-agent.md\":\"buLbgvBf\",\"example-agents_weather-agent.md\":\"C9Qv-W0o\",\"guides_agent-to-agent.md\":\"Bpzgq2Pq\",\"guides_cloud-runtime.md\":\"gVzabdQL\",\"guides_github.md\":\"DOOCpqsW\",\"guides_human-in-the-loop.md\":\"DlUqsp1S\",\"guides_mcp-oauth.md\":\"Dd8EgSem\",\"guides_slack.md\":\"D_xFKlnF\",\"guides_webhooks.md\":\"B1EswtUu\",\"hillclimbing.md\":\"DHNast08\",\"index.md\":\"Dfv5ic9t\",\"quickstart.md\":\"BU6Iwi_9\",\"reference_agent-config.md\":\"DrW2JUM8\",\"reference_channels.md\":\"DdmiKgqf\",\"reference_cli.md\":\"ccoKOoXt\",\"reference_connections.md\":\"B9Q3TOve\",\"reference_hooks.md\":\"DyLVfE1O\",\"reference_http-api.md\":\"BncLd3PZ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"Bd_CKtNS\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"w_F2mXB6\",\"reference_sessions.md\":\"DLd6mvbv\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"zWAMNfi1\",\"reference_tools.md\":\"BRSDnTbN\",\"scaffolding-agents.md\":\"C3pTrmoE\",\"storage.md\":\"DRTdnFvd\",\"troubleshooting.md\":\"CmQkmnzC\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"agentkit\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist/docs/assets/{app.BKNKMLp4.js → app.CvSGaAxk.js}

@@ -1 +1 @@
-import{t as p}from"./chunks/theme.BvCHT5lj.js";import{R as s,a2 as i,a3 as u,a4 as c,a5 as l,a6 as f,a7 as d,a8 as m,a9 as h,aa as g,ab as A,d as v,u as y,v as C,s as P,ac as b,ad as w,ae as R,af as E}from"./chunks/framework.CAZyNGu9.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
+import{t as p}from"./chunks/theme.C7vfzr7h.js";import{R as s,a2 as i,a3 as u,a4 as c,a5 as l,a6 as f,a7 as d,a8 as m,a9 as h,aa as g,ab as A,d as v,u as y,v as C,s as P,ac as b,ad as w,ae as R,af as E}from"./chunks/framework.CAZyNGu9.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};