@cursor/july 0.1.29 → 0.1.31

package/src/types.ts

@@ -190,7 +190,7 @@ export interface AgentConfig {
    */
   local?: AgentLocalOptions;
   /**
-   * Managed-hosting declarations (`agentkit deploy` onto Cursor's
+   * Managed-hosting declarations (`agent-sdk deploy` onto Cursor's
    * agent-serve hosting). The manifest is the source of truth: deploy reads
    * it and sends it with the deployment request. Ignored by local serving.
    */
@@ -265,7 +265,7 @@ export interface AgentHostingOptions {
    * Domains the deployed engine pod may reach (egress allowlist), e.g.
    * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
    * Lowercase hostnames with at least two labels and an alphabetic TLD;
-   * max 20. `agentkit deploy` sends these as `egressAllowedDomains`
+   * max 20. `agent-sdk deploy` sends these as `egressAllowedDomains`
    * (unioned with any `--allow-domain` flags). Only valid on repo-backed
    * deployments. Deployment-scoped like {@link secretNames}: not capped by
    * the team's Cloud Agent egress allowlist. The platform still merges a
@@ -274,9 +274,9 @@ export interface AgentHostingOptions {
   egressDomains?: string[];
   /**
    * Secret names this agent expects at runtime (declarative documentation;
-   * values are never authored in files). `agentkit deploy` warns when a
+   * values are never authored in files). `agent-sdk deploy` warns when a
    * declared name is not set on the deployment — set values with
-   * `agentkit secrets set <slug> NAME`.
+   * `agent-sdk secrets set <slug> NAME`.
    */
   secretNames?: string[];
 }
@@ -309,7 +309,7 @@ export interface AgentLocalOptions {
    * working tree, and a file one turn writes is visible to the next. Agent
    * scaffold (`AGENTS.md`, skills, tool scripts) is kept out of the shared
    * directory and delivered inline instead, so pointing this at a repo does
-   * not write agentkit files into it — but `workspaceFiles` still lands in
+   * not write Agent SDK files into it — but `workspaceFiles` still lands in
    * the harness cwd, as it does for a per-send override.
    */
   workspaceDir?: string;
@@ -473,6 +473,14 @@ export interface HostContext {
    * project tree so state survives host replacement.
    */
   kv: HostKvApi;
+  /**
+   * Author-facing durable files (`agentkit/v1/{agent}/files/…`). On
+   * Cursor-managed hosting they live in the deployment's durable store;
+   * otherwise under `--state-root/files`. Use this for file-shaped state —
+   * evidence, reports, hand-offs to a delegated run — that must outlive the
+   * process.
+   */
+  files: HostFilesApi;
 }
 
 /** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
@@ -485,6 +493,129 @@ export interface HostKvApi {
   delete(key: string): Promise<void>;
 }
 
+/**
+ * Which set of files a call addresses.
+ *
+ * `"session"` (the default) is private to one session. `"deployment"` is shared
+ * by every session of the agent and survives redeploys; `partition` subdivides
+ * it for author-chosen groupings such as a pull request or a customer.
+ */
+export type HostFilesScope =
+  | "session"
+  | "deployment"
+  | { kind: "session"; sessionId?: string }
+  | { kind: "deployment"; partition?: string };
+
+/** Scope selector shared by every {@link HostFilesApi} call. */
+export interface HostFilesCallOptions {
+  scope?: HostFilesScope;
+}
+
+/** One entry from {@link HostFilesApi.list}. */
+export interface HostFileEntry {
+  /** Path within the scope, as authors address it. */
+  path: string;
+  size: number;
+  /** Last-modified epoch ms, when the sink tracks one. */
+  mtimeMs?: number;
+}
+
+/** Result of {@link HostFilesApi.stat}. */
+export interface HostFileStat {
+  size: number;
+  mtimeMs?: number;
+  /** Opaque version tag; pass back as `ifMatch` to make a write conditional. */
+  etag?: string;
+}
+
+/**
+ * What the configured sink actually supports. Read these instead of assuming:
+ * the same authored code runs against local disk, an Agent Store, and whatever
+ * a customer plugged in, and those differ in ways that change correctness.
+ */
+export interface HostFilesCapabilities {
+  /**
+   * Conditional writes are enforced, so a lost race raises
+   * `FileConflictError` instead of silently clobbering. False means
+   * last-writer-wins.
+   */
+  conflictDetection: boolean;
+  /**
+   * Files have a real local path ({@link HostFilesApi.materializedPath}) the
+   * harness can open with ordinary file tools. False means the model cannot
+   * reach them directly — only authored handler code (tools, hooks) can,
+   * through this API.
+   */
+  materialized: boolean;
+  /** Largest value the sink accepts, when it declares a limit. */
+  maxBytes?: number;
+}
+
+/**
+ * Durable files attached to {@link HostContext.files}.
+ *
+ * Deliberately not a filesystem: no handles, no seeking, no rename, no
+ * directories, no errno. Paths are addresses within a {@link HostFilesScope},
+ * never filesystem paths — {@link materializedPath} is the one place a real
+ * path appears, and it is `undefined` whenever the sink keeps no local copy.
+ */
+export interface HostFilesApi {
+  /** What the configured sink supports. */
+  readonly capabilities: HostFilesCapabilities;
+
+  /** Bind `"session"`-scoped calls to `sessionId`. */
+  forSession(sessionId: string): HostFilesApi;
+
+  /** Read as text. Miss → `undefined`. */
+  read(
+    path: string,
+    options?: HostFilesCallOptions & { encoding?: BufferEncoding }
+  ): Promise<string | undefined>;
+
+  /** Read as bytes. Miss → `undefined`. */
+  readBytes(
+    path: string,
+    options?: HostFilesCallOptions
+  ): Promise<Uint8Array | undefined>;
+
+  /**
+   * Write or replace. Pass `ifMatch` with a {@link HostFileStat.etag} to make
+   * the write conditional, or `null` to require that it does not exist —
+   * enforced only when {@link HostFilesCapabilities.conflictDetection} is set.
+   */
+  write(
+    path: string,
+    data: string | Uint8Array,
+    options?: HostFilesCallOptions & { ifMatch?: string | null }
+  ): Promise<void>;
+
+  /** Remove one path. No-op when missing. */
+  remove(path: string, options?: HostFilesCallOptions): Promise<void>;
+
+  /** Entries whose path starts with `prefix` (all when omitted), in path order. */
+  list(
+    prefix?: string,
+    options?: HostFilesCallOptions
+  ): Promise<HostFileEntry[]>;
+
+  exists(path: string, options?: HostFilesCallOptions): Promise<boolean>;
+
+  stat(
+    path: string,
+    options?: HostFilesCallOptions
+  ): Promise<HostFileStat | undefined>;
+
+  /**
+   * Absolute local path the harness can read, or `undefined` when the sink
+   * keeps no local copy. Never use it as an identity — pass paths and scopes
+   * to the other calls so the same code works against a sink that has none.
+   */
+  materializedPath(
+    path: string,
+    options?: HostFilesCallOptions
+  ): string | undefined;
+}
+
 /** Runtime context handed to a tool's `execute`. */
 export interface ToolContext {
   /** Correlates with `actions.requested` / `action.result` stream events. */
@@ -640,7 +771,7 @@ export type ConnectionTransport =
       type?: "http" | "sse";
       url: string;
       headers?: Record<string, string>;
-      /** Host PKCE OAuth; `agentkit mcp oauth <name>`. No Authorization header. */
+      /** Host PKCE OAuth; `agent-sdk mcp oauth <name>`. No Authorization header. */
       oauth?: true;
     }
   | {
@@ -961,24 +1092,25 @@ export interface TurnUsage {
 }
 
 /**
- * Estimated dollar cost of one turn's token usage (one agent loop pass).
+ * Dollar cost of one turn's token usage (one agent loop pass).
  * Recorded on `turn.completed` events so traces, the playground, A/B
- * metrics, and the CLI can aggregate spend. Estimates price the turn's
- * {@link TurnUsage} against the framework's snapshot of Cursor's published
- * per-model rates — the billed amount on the Cursor dashboard is the source
- * of truth.
+ * metrics, and the CLI can aggregate spend. Computed by
+ * `POST /v1/models/estimate-cost` — billed usage events when available
+ * (credits, discounts, CTF), otherwise live catalog pricing.
  */
 export interface TurnCost {
-  /** Estimated total for the turn, in USD. */
+  /** Charged total for the turn, in USD. */
   totalUsd: number;
   inputUsd: number;
   outputUsd: number;
   cacheReadUsd: number;
   cacheWriteUsd: number;
-  /** Normalized model id the estimate was priced against. */
+  /** Model id the cost was priced against. */
   model: string;
-  /** Always `"estimate"`: framework rate table, not the billing pipeline. */
-  source: "estimate";
+  /** `"usage"` is billed events; `"catalog"` is live list pricing. */
+  source: "usage" | "catalog";
+  rawCostCents?: number;
+  chargedCents?: number;
 }
 
 // ============================================================================
@@ -1082,7 +1214,7 @@ export interface TurnOutcome {
   result?: string;
   errorMessage?: string;
   usage?: TurnUsage;
-  /** Estimated cost of {@link usage} when the model has known rates. */
+  /** Cost of {@link usage} from the Cloud Agents cost endpoint. */
   cost?: TurnCost;
 }
 

package/dist/docs/assets/building-with-agents.md.CJCtZCyi.js

@@ -1,13 +0,0 @@
-import{_ as a,c as t,o as i,ag as s}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return i(),t("div",null,[...e[0]||(e[0]=[s(`<h1 id="building-agents-with-agents" tabindex="-1">Building agents with agents <a class="header-anchor" href="#building-agents-with-agents" aria-label="Permalink to &quot;Building agents with agents&quot;">​</a></h1><p>Give a coding agent the goal. The built-in skills guide it through scaffolding, channels, verification, evals, and measured improvement.</p><h2 id="what-can-a-coding-agent-build-for-me" tabindex="-1">What can a coding agent build for me? <a class="header-anchor" href="#what-can-a-coding-agent-build-for-me" aria-label="Permalink to &quot;What can a coding agent build for me?&quot;">​</a></h2><p>A coding agent can take a agentkit project from an idea to a verified first version. It can:</p><ul><li>Create the project and choose the smallest useful surface</li><li>Add tools, skills, channels, MCP connections, and approval gates</li><li>Run a real turn and inspect its trace</li><li>Add evals for the behavior you want to keep</li><li>Improve the agent against fixed inputs</li></ul><p>This works because the project surface lives in files. The CLI also returns structured JSON and records each run as an NDJSON trace. Your coding agent can inspect what the framework discovered, run the agent, and verify the result without reading terminal prose.</p><h2 id="how-do-i-create-an-agent-with-the-built-in-skill" tabindex="-1">How do I create an agent with the built-in skill? <a class="header-anchor" href="#how-do-i-create-an-agent-with-the-built-in-skill" aria-label="Permalink to &quot;How do I create an agent with the built-in skill?&quot;">​</a></h2><p>Have the coding agent read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> (in the monorepo: <code>packages/agent-serve/skills/create-agent/SKILL.md</code>) and follow it.</p><p>The skill asks about your agent&#39;s purpose, runtime, model, channels, MCP connections, and capabilities. It then shows you a plan, writes the project, and verifies the result.</p><p>For example:</p><blockquote><p>Use the agent-serve create-agent skill to build a PR triage agent reachable through GitHub. It should summarize failed checks, require approval before posting a review, and include one smoke eval.</p></blockquote><p>The skill starts with a small surface: short instructions, one or two tools, the channels you chose, and a smoke eval. You can add more after the first end-to-end turn works.</p><h2 id="which-built-in-skill-should-i-use" tabindex="-1">Which built-in skill should I use? <a class="header-anchor" href="#which-built-in-skill-should-i-use" aria-label="Permalink to &quot;Which built-in skill should I use?&quot;">​</a></h2><p>The package ships task-specific guides under <a href="./../skills/"><code>skills/</code></a>:</p><table tabindex="0"><thead><tr><th>What you want to do</th><th>Skill</th></tr></thead><tbody><tr><td>Understand the project layout and runtimes</td><td><a href="./../skills/framework-map/SKILL.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./../skills/create-agent/SKILL.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./../skills/evals/SKILL.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./../skills/ab/SKILL.html"><code>ab</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./../skills/github/SKILL.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./../skills/setup-slack/SKILL.html"><code>setup-slack</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./../skills/debug/SKILL.html"><code>debug</code></a></td></tr></tbody></table><p>Point your coding agent at the matching <code>SKILL.md</code>. The guide contains the workflow, commands, and common mistakes for that task.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The skill bodies use the current <code>agent-serve</code> CLI names. This guide uses the upcoming <code>agentkit</code> names. See <a href="./README.html#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="how-does-a-coding-agent-verify-its-work" tabindex="-1">How does a coding agent verify its work? <a class="header-anchor" href="#how-does-a-coding-agent-verify-its-work" aria-label="Permalink to &quot;How does a coding agent verify its work?&quot;">​</a></h2><p>The coding agent should discover the project, test each server tool, run a real turn, and finish with evals:</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is https://github.com/acme/checkout/pull/42 ready to approve?&quot;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .agentkit/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p><code>serve</code> boots without an API key, which is enough to check channel mounts and the playground shell. Model turns need a credential. When the environment lacks one, finish every key-free check, then hand the <code>run</code> and <code>eval</code> commands to the operator.</p><p>Test server tools with <code>call</code> before tuning the prompt. It runs a tool in-process with schema validation and no model turn. If the tool returns the wrong data, a prompt change won&#39;t fix it.</p><p><code>validate</code> and <code>run</code> don&#39;t type-check the project because tsx strips types. Run the project&#39;s TypeScript check before shipping. Tool results must also be JSON-shaped. Use object literals or <code>type</code> aliases for <code>execute</code> return types instead of <code>interface</code> types.</p><h2 id="how-do-i-improve-the-agent-after-its-first-run" tabindex="-1">How do I improve the agent after its first run? <a class="header-anchor" href="#how-do-i-improve-the-agent-after-its-first-run" aria-label="Permalink to &quot;How do I improve the agent after its first run?&quot;">​</a></h2><p>Scaffolding proves the agent runs. It says nothing about quality. Once a smoke turn passes, give the hillclimb skill:</p><ol><li><strong>Fixtures</strong>: one to three fixed inputs, such as a PR URL, a canonical question, or a saved webhook payload</li><li><strong>Success criteria</strong>: correct tool choice, fewer tool calls, lower wall time, or better output</li><li><strong>The freeze line</strong>: the API contract, output shape, and existing evals that must stay unchanged</li></ol><p>Have the coding agent read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. It measures the current run, proposes one change, remeasures the same fixtures, and adds an eval for each kept improvement.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Create your first agent</a></li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/cli.html">CLI reference</a></li></ul>`,29)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};