@cursor/july 0.1.111 → 0.1.113

package/templates/thermo-quality-review/agent/tools/post_findings.ts

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseGitHubPrRef } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+const SHA = /^[0-9a-f]{40}$/i;
+
+const finding = z.object({
+  severity: z.enum(["high", "medium", "low"]),
+  file: z.string().min(1).max(240),
+  line: z.number().int().positive(),
+  title: z.string().min(1).max(160),
+  detail: z.string().min(1).max(280),
+});
+
+type Finding = z.infer<typeof finding>;
+
+export default defineTool({
+  description:
+    "Post the review on this session's pull request. Call once. Empty findings = CLEAN.",
+  inputSchema: z.object({
+    findings: z.array(finding).describe("Issues in the diff. Empty for CLEAN."),
+  }),
+  async execute({ findings }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+    const key = ctx.session.continuationKey ?? "";
+    if (!key.startsWith("github-pr:")) {
+      throw new Error("post_findings requires a GitHub pull request session");
+    }
+    const ref = parseGitHubPrRef(key.slice("github-pr:".length));
+    if (ref === undefined) {
+      throw new Error(`unrecognized PR: ${key}`);
+    }
+    const headSha = (
+      await readFile(join(ctx.workspaceDir, "pr/head.sha"), "utf8")
+    ).trim();
+    if (!SHA.test(headSha)) {
+      throw new Error("missing pr/head.sha");
+    }
+    const octokit = await ctx.host.github.getOctokit();
+    const response = await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      commit_id: headSha,
+      body: reviewBody(findings),
+      event: "COMMENT",
+    });
+    return { posted: true, pr: ref.label, url: response.data.html_url };
+  },
+});
+
+function flatten(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function reviewBody(findings: Finding[]): string {
+  const verdict = findings.length === 0 ? "CLEAN" : "FINDINGS";
+  const lines = ["## Thermo quality review", "", `**Verdict:** ${verdict}`];
+  for (const item of findings) {
+    lines.push(
+      `- **${item.severity}** \`${flatten(item.file)}:${item.line}\` — ${flatten(item.title)}`
+    );
+    lines.push(`  ${flatten(item.detail)}`);
+  }
+  return lines.join("\n");
+}

package/templates/thermo-quality-review/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/thermo-quality-review/evals/review.eval.ts

@@ -0,0 +1,62 @@
+import { defineEval, includes } from "@cursor/july/evals";
+
+const OPENED = [
+  "GitHub pull request trigger: acme/api#12",
+  "Action: opened",
+  "PR: https://github.com/acme/api/pull/12",
+  "Title: VIP discount",
+  "Head: feat/vip-discount (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa)",
+  "Base: main",
+  "Author: sam",
+  "",
+  "Read pr/diff.patch.",
+].join("\n");
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "spaghetti",
+      description: "A special-case branch is posted as a finding.",
+      async test(t) {
+        await t.send(OPENED, {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/app/pricing.ts b/app/pricing.ts",
+              " function total(items, opts) {",
+              "+  if (items.length > 10 && opts.vip && !opts.dryRun) {",
+              "+    return items.reduce((sum, item) => sum + item.price, 0) * 0.9;",
+              "+  }",
+              "   return items.reduce((sum, item) => sum + item.price, 0);",
+              " }",
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(
+          t.reply,
+          includes(/branch|special|abstraction|spaghetti|finding/i)
+        );
+      },
+    },
+    {
+      id: "clean",
+      description: "A direct one-line fix is posted as clean.",
+      async test(t) {
+        await t.send(OPENED.replace("VIP discount", "Typo"), {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/app/pricing.ts b/app/pricing.ts",
+              "-const RATE = 0.08;",
+              "+const RATE = 0.09;",
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(t.reply, includes(/clean|no findings|no .*issues/i));
+      },
+    },
+  ],
+});

package/templates/thermo-quality-review/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "thermo-quality-review",
+  "private": true,
+  "type": "module",
+  "description": "Reviews pull requests for structural code quality.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "6.0.3"
+  }
+}

package/templates/thermo-quality-review/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}

package/templates/thermo-review/README.md

@@ -0,0 +1,35 @@
+# Thermo review
+
+Reviews pull requests for bugs and breakage. Posts one review comment.
+
+```bash
+npx @cursor/july init ./thermo-review --template thermo-review
+```
+
+## Run hosted
+
+```bash
+cd thermo-review
+agent-sdk login
+agent-sdk deploy --cursor-events-repo acme/api
+```
+
+The deployment watches that repo through your team's Cursor GitHub
+connection. Open a PR to get a review.
+
+## Run locally
+
+```bash
+agent-sdk dev --cursor-events --repo acme/api
+```
+
+Or replay a PR without pushing:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+## Files
+
+- `agent/instructions.md`: what counts as a finding
+- `evals/review.eval.ts`: two smoke cases

package/templates/thermo-review/agent/agent.ts

@@ -0,0 +1,8 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  tools: ["read"],
+  local: {
+    sandbox: true,
+  },
+});

package/templates/thermo-review/agent/channels/github.ts

@@ -0,0 +1,42 @@
+import {
+  defaultGitHubPullRequestDispatch,
+  githubChannel,
+} from "@cursor/july/channels/github";
+
+const MAX_DIFF_CHARS = 150_000;
+
+export default githubChannel({
+  cursorAccount: true,
+  deliverReplies: false,
+  onComment: () => null,
+  onPullRequest: (ctx, pr) => {
+    if (pr.draft) {
+      return null;
+    }
+    const dispatch = defaultGitHubPullRequestDispatch(ctx, pr);
+    if (dispatch === null) {
+      return null;
+    }
+    return {
+      auth: dispatch.auth,
+      context: ["Read pr/diff.patch."],
+      async workspaceFiles() {
+        const octokit = await ctx.github.getOctokit();
+        const diff = await octokit.rest.pulls.get({
+          owner: ctx.repository.owner,
+          repo: ctx.repository.name,
+          pull_number: pr.number,
+          mediaType: { format: "diff" },
+        });
+        const text = String(diff.data);
+        return {
+          "pr/diff.patch":
+            text.length > MAX_DIFF_CHARS
+              ? `${text.slice(0, MAX_DIFF_CHARS)}\n…[truncated]\n`
+              : text,
+          "pr/head.sha": pr.headSha,
+        };
+      },
+    };
+  },
+});

package/templates/thermo-review/agent/instructions.md

@@ -0,0 +1,40 @@
+# Thermo review
+
+You review pull requests for bugs and breakage. Be thorough; nothing
+slips through.
+
+## Scope
+
+Only added or modified code. Never report issues in unchanged code.
+
+## Hunt
+
+- Bugs in the new code.
+- Breaking side effects elsewhere. Trace each change end to end
+  through cross-package dependencies before judging it safe.
+- Devex breaks: secrets sources, env vars, ports, new setup scripts.
+  New alternative workflows and routine dependency installs are fine.
+- Feature-gate leaks, including subtle ones.
+
+## Skip
+
+- Style, tests, hypotheticals.
+- Breakage the PR clearly intends when the scope is tight. Report it
+  when the author likely misses the full implications.
+- Never inflate severity. Uncertain means low or unreported, never high.
+
+## Review
+
+The workspace has `pr/diff.patch`. Read it once. Call `post_findings`
+once with structured findings. Reply with the count and one line per
+finding. Clean review: empty findings.
+
+The host writes the GitHub comment. Verdict is CLEAN when the list
+is empty.
+
+## Finding
+
+- `severity`: `high`, `medium`, or `low`
+- `file`, `line`: path and line in the diff
+- `title`: short name
+- `detail`: one-line impact and fix

package/templates/thermo-review/agent/tools/post_findings.ts

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseGitHubPrRef } from "@cursor/july/channels/github";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+const SHA = /^[0-9a-f]{40}$/i;
+
+const finding = z.object({
+  severity: z.enum(["high", "medium", "low"]),
+  file: z.string().min(1).max(240),
+  line: z.number().int().positive(),
+  title: z.string().min(1).max(160),
+  detail: z.string().min(1).max(280),
+});
+
+type Finding = z.infer<typeof finding>;
+
+export default defineTool({
+  description:
+    "Post the review on this session's pull request. Call once. Empty findings = CLEAN.",
+  inputSchema: z.object({
+    findings: z.array(finding).describe("Issues in the diff. Empty for CLEAN."),
+  }),
+  async execute({ findings }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+    const key = ctx.session.continuationKey ?? "";
+    if (!key.startsWith("github-pr:")) {
+      throw new Error("post_findings requires a GitHub pull request session");
+    }
+    const ref = parseGitHubPrRef(key.slice("github-pr:".length));
+    if (ref === undefined) {
+      throw new Error(`unrecognized PR: ${key}`);
+    }
+    const headSha = (
+      await readFile(join(ctx.workspaceDir, "pr/head.sha"), "utf8")
+    ).trim();
+    if (!SHA.test(headSha)) {
+      throw new Error("missing pr/head.sha");
+    }
+    const octokit = await ctx.host.github.getOctokit();
+    const response = await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      commit_id: headSha,
+      body: reviewBody(findings),
+      event: "COMMENT",
+    });
+    return { posted: true, pr: ref.label, url: response.data.html_url };
+  },
+});
+
+function flatten(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function reviewBody(findings: Finding[]): string {
+  const verdict = findings.length === 0 ? "CLEAN" : "FINDINGS";
+  const lines = ["## Thermo review", "", `**Verdict:** ${verdict}`];
+  for (const item of findings) {
+    lines.push(
+      `- **${item.severity}** \`${flatten(item.file)}:${item.line}\` — ${flatten(item.title)}`
+    );
+    lines.push(`  ${flatten(item.detail)}`);
+  }
+  return lines.join("\n");
+}

package/templates/thermo-review/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/thermo-review/evals/review.eval.ts

@@ -0,0 +1,53 @@
+import { defineEval, includes } from "@cursor/july/evals";
+
+const OPENED = [
+  "GitHub pull request trigger: acme/api#12",
+  "Action: opened",
+  "PR: https://github.com/acme/api/pull/12",
+  "Title: Admin flag",
+  "Head: feat/admin-flag (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa)",
+  "Base: main",
+  "Author: sam",
+  "",
+  "Read pr/diff.patch.",
+].join("\n");
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "bypass",
+      description: "A query-param admin grant is posted as a finding.",
+      async test(t) {
+        await t.send(OPENED, {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/app/middleware/auth.ts b/app/middleware/auth.ts",
+              '+if (req.query.admin === "true") { grantAdmin(req.user); }',
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(t.reply, includes(/auth|bypass|admin|finding/i));
+      },
+    },
+    {
+      id: "clean",
+      description: "A docs-only change is posted as clean.",
+      async test(t) {
+        await t.send(OPENED.replace("Admin flag", "Docs"), {
+          workspaceFiles: {
+            "pr/diff.patch": [
+              "diff --git a/README.md b/README.md",
+              "+# API",
+            ].join("\n"),
+          },
+        });
+        t.succeeded();
+        t.calledTool("post_findings");
+        t.check(t.reply, includes(/clean|no findings|no .*issues/i));
+      },
+    },
+  ],
+});

package/templates/thermo-review/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "thermo-review",
+  "private": true,
+  "type": "module",
+  "description": "Reviews pull requests for bugs and breakage.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "6.0.3"
+  }
+}

package/templates/thermo-review/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}

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

@@ -1,13 +0,0 @@
-import{_ as t,c as a,o as i,a3 as s}from"./chunks/framework.dypDpWZ3.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(),a("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, deployment, 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 an Agent SDK 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> 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 SDK 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 <code>skills/</code>:</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>Export OpenTelemetry traces</td><td><a href="./../skills/otel/SKILL.html"><code>otel</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>Authorize host MCP OAuth</td><td><a href="./../skills/mcp-auth/SKILL.html"><code>mcp-auth</code></a></td></tr><tr><td>Deploy with an attached service account</td><td><a href="./../skills/deploy/SKILL.html"><code>deploy</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><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;">agent-sdk</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;">agent-sdk</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;">agent-sdk</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;">agent-sdk</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;">agent-sdk</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:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">state-roo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/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;">agent-sdk</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;">agent-sdk</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> do not type-check the project. 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="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/cli.html">CLI reference</a></li></ul>`,28)])])}const g=t(n,[["render",l]]);export{k as __pageData,g as default};

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

@@ -1 +0,0 @@
-import{_ as t,c as a,o as i,a3 as s}from"./chunks/framework.dypDpWZ3.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(),a("div",null,[...e[0]||(e[0]=[s("",28)])])}const g=t(n,[["render",l]]);export{k as __pageData,g as default};