@cursor/july 0.1.107 → 0.1.109

package/dist/channels/slack/dispatch.js

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { continuationSource, normalizeIdentity, } from "../../internal/continuation-identity.js";
+import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { routeLocalIngressContinuation } from "../../internal/local-ingress.js";
 import { steeringEnabled } from "../../internal/steering.js";
 import { buildSlackBinding, slackContinuationKey } from "./api.js";
@@ -206,6 +207,9 @@ export function dispatchInboundMessage(args) {
                 thread_ts: message.threadTs,
                 event_id: args.eventId,
             });
+            if (args.propagateHandlerErrors === true) {
+                throw error;
+            }
             return;
         }
         if (decision === null || decision === undefined) {
@@ -291,6 +295,19 @@ export function dispatchInboundMessage(args) {
             }), title: (_4 = decision.title) !== null && _4 !== void 0 ? _4 : `slack:${message.channelId}:${message.threadTs}`, workspaceDir: decision.workspaceDir, workspaceFiles: media.workspaceFiles, images: media.images, cloud: decision.cloud, sdkAgentId: decision.sdkAgentId });
         try {
             const session = yield args.send(prompt, sendOptions);
+            if (isDeferredChannelSession(session)) {
+                // Hosted admission captured the send; the control plane allocates
+                // the session and runs the turn only after this delivery is
+                // acknowledged, so there is nothing to observe or coalesce yet.
+                log.info("session send captured (hosted admission)", {
+                    kind,
+                    continuation,
+                    channel: message.channelId,
+                    thread_ts: message.threadTs,
+                    event_id: args.eventId,
+                });
+                return;
+            }
             log.info(session.coalesced === true ? "session coalesced" : "session start", {
                 kind,
                 session: session.id,
@@ -404,7 +421,7 @@ export function dispatchInboundFromEventBody(body, deps) {
                 return false;
             }
         }
-        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "app_mention", message: mention, handler: deps.onAppMention, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: deps.evalCommandsEnabled, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
+        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "app_mention", message: mention, handler: deps.onAppMention, propagateHandlerErrors: deps.propagateHandlerErrors, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: deps.evalCommandsEnabled, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
             ? {}
             : { hasContinuationSession: deps.hasContinuationSession })), (deps.isContinuationBusy === undefined
             ? {}
@@ -425,7 +442,7 @@ export function dispatchInboundFromEventBody(body, deps) {
             });
             return false;
         }
-        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "direct_message", message: dm, handler: deps.onDirectMessage, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: deps.evalCommandsEnabled, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
+        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "direct_message", message: dm, handler: deps.onDirectMessage, propagateHandlerErrors: deps.propagateHandlerErrors, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: deps.evalCommandsEnabled, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
             ? {}
             : { hasContinuationSession: deps.hasContinuationSession })), (deps.isContinuationBusy === undefined
             ? {}
@@ -440,7 +457,7 @@ export function dispatchInboundFromEventBody(body, deps) {
     }
     const reaction = parseReactionAddedEvent(body);
     if (reaction !== null && deps.onReactionAdded !== undefined) {
-        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "reaction_added", message: reaction, handler: deps.onReactionAdded, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: false, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
+        deps.waitUntil(dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind: "reaction_added", message: reaction, handler: deps.onReactionAdded, propagateHandlerErrors: deps.propagateHandlerErrors, send: deps.send, credentials: deps.credentials, host: deps.host, artifacts: deps.artifacts, log, evalCommandsEnabled: false, followUpStatus: deps.followUpStatus, blockExternals: deps.blockExternals }, continuationArg(deps.continuation)), (deps.hasContinuationSession === undefined
             ? {}
             : { hasContinuationSession: deps.hasContinuationSession })), (deps.isContinuationBusy === undefined
             ? {}

package/dist/channels/slack/slack-channel.d.ts

@@ -1,10 +1,17 @@
 /**
- * `slackChannel()` — platform channel pack for Slack (Socket Mode).
+ * `slackChannel()` — platform channel pack for Slack.
  *
- * Inbound events arrive over a WebSocket (`SLACK_APP_TOKEN`); no public
- * Request URL or Events HTTP route is required. When `toolApprovals`
- * is enabled, Approve/Deny buttons arrive as Socket Mode `interactive`
- * envelopes.
+ * Local / self-hosted transport is Socket Mode: inbound events arrive over
+ * a WebSocket (`SLACK_APP_TOKEN`); no public Request URL or Events HTTP
+ * route is required. When `toolApprovals` is enabled, Approve/Deny buttons
+ * arrive as Socket Mode `interactive` envelopes.
+ *
+ * Hosted v2 transport is the control plane's Events API ingest: the CP
+ * verifies the managed app's signature, fans out on the declared
+ * `slackEventTypes` (`app_mention`, `message`), and delivers the full
+ * `event_callback` body through hosted admission — the attached adapter
+ * routes it through the same inbound dispatch as Socket Mode. Without an
+ * app token the socket transport idles, so a hosted pod never needs one.
  */
 import type { ChannelDefinition } from "../../types.js";
 import type { SlackChannelOptions, SlackChannelState, SlackCredentials } from "./types.js";

package/dist/channels/slack/slack-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slack-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/slack-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAEV,iBAAiB,EAMlB,MAAM,gBAAgB,CAAC;AA4CxB,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GACjB,mBAAmB,GAAG,SAAS,CAEjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9C,uBAAuB,GAAG,SAAS,CAYrC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,GAAE,mBAAwB,GACjC,iBAAiB,CAAC,iBAAiB,CAAC,CAgbtC"}
+{"version":3,"file":"slack-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/slack-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,OAAO,KAAK,EAEV,iBAAiB,EAMlB,MAAM,gBAAgB,CAAC;AA4CxB,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GACjB,mBAAmB,GAAG,SAAS,CAEjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9C,uBAAuB,GAAG,SAAS,CAYrC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,GAAE,mBAAwB,GACjC,iBAAiB,CAAC,iBAAiB,CAAC,CAketC"}

package/dist/channels/slack/slack-channel.js

@@ -1,10 +1,17 @@
 /**
- * `slackChannel()` — platform channel pack for Slack (Socket Mode).
+ * `slackChannel()` — platform channel pack for Slack.
  *
- * Inbound events arrive over a WebSocket (`SLACK_APP_TOKEN`); no public
- * Request URL or Events HTTP route is required. When `toolApprovals`
- * is enabled, Approve/Deny buttons arrive as Socket Mode `interactive`
- * envelopes.
+ * Local / self-hosted transport is Socket Mode: inbound events arrive over
+ * a WebSocket (`SLACK_APP_TOKEN`); no public Request URL or Events HTTP
+ * route is required. When `toolApprovals` is enabled, Approve/Deny buttons
+ * arrive as Socket Mode `interactive` envelopes.
+ *
+ * Hosted v2 transport is the control plane's Events API ingest: the CP
+ * verifies the managed app's signature, fans out on the declared
+ * `slackEventTypes` (`app_mention`, `message`), and delivers the full
+ * `event_callback` body through hosted admission — the attached adapter
+ * routes it through the same inbound dispatch as Socket Mode. Without an
+ * app token the socket transport idles, so a hosted pod never needs one.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -16,7 +23,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { allowAll, defineChannel } from "../../channels.js";
+import { skipped, withPropagatingBackgroundErrors, } from "../../internal/channel-dispatch.js";
 import { continuationSource, normalizeIdentity, } from "../../internal/continuation-identity.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import { slackContinuationKey } from "./api.js";
 import { normalizeBotMentionAllowlist, SLACK_BOT_MENTION_DEFAULTS, SlackBotMentionGate, } from "./bot-mentions.js";
 import { createChannelPostWatcher, resolveChannelNames, SlackChannelAllowlist, } from "./channel-watch.js";
@@ -97,6 +106,18 @@ export function slackChannel(authored = {}) {
         normalizeBotMentionAllowlist(botMentions.allowFrom);
     }
     const eventIds = createEventIdDedupe();
+    // Hosted v2 event capability, matching what the engagement flags can
+    // dispatch: mentions ride `app_mention`; DMs and watched channel posts
+    // both arrive as `message`. Membership of `slack.thread/v2` admits
+    // exactly these two, so `reaction_added` (hosted follow-up only inside
+    // an existing thread) is deliberately not declared.
+    const slackEventTypes = [];
+    if (mentionsEnabled) {
+        slackEventTypes.push("app_mention");
+    }
+    if (directMessagesEnabled || channelPosts !== undefined) {
+        slackEventTypes.push("message");
+    }
     const toolApprovals = options.toolApprovals === true;
     const interactivity = options.interactivity === true;
     const onBlockAction = options.onBlockAction;
@@ -127,9 +148,9 @@ export function slackChannel(authored = {}) {
     let channelWatch;
     let botMentionGate;
     function inboundDeps(args) {
+        var _a;
         return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ send: args.send, continuation: options.continuation, waitUntil: args.waitUntil, onAppMention,
-            onDirectMessage }, (onReactionAdded === undefined ? {} : { onReactionAdded })), { credentials,
-            eventIds, host: args.host, artifacts: args.artifacts, log: getLog(), mentionsEnabled,
+            onDirectMessage }, (onReactionAdded === undefined ? {} : { onReactionAdded })), { credentials, eventIds: (_a = args.eventIds) !== null && _a !== void 0 ? _a : eventIds, propagateHandlerErrors: args.propagateHandlerErrors, host: args.host, artifacts: args.artifacts, log: getLog(), mentionsEnabled,
             directMessagesEnabled,
             evalCommandsEnabled,
             followUpStatus,
@@ -149,7 +170,10 @@ export function slackChannel(authored = {}) {
         auth: [allowAll()],
         state: emptySlackChannelState(),
         routes: [],
-        meta: Object.assign(Object.assign({ kind: "slack" }, (channelPosts === undefined
+        meta: Object.assign(Object.assign({ kind: "slack", 
+            // Omitted (not empty) when nothing dispatches, so fanout never
+            // materializes a subscription with no event types.
+            slackEventTypes: slackEventTypes.length === 0 ? undefined : slackEventTypes }, (channelPosts === undefined
             ? {}
             : { slackChannelPosts: [...channelPosts.allow] })), { deprecations: reply.deprecations }),
         receive(input_1, _a) {
@@ -379,5 +403,32 @@ export function slackChannel(authored = {}) {
         }),
     });
     slackChannelOptionsByDefinition.set(definition, options);
+    attachHostedAdmissionAdapter(definition, {
+        kind: "slack",
+        prepareArgs: withPropagatingBackgroundErrors,
+        // The payload is the full `event_callback` body the CP verified — the
+        // same shape Socket Mode unwraps — so it routes through the same
+        // inbound dispatch. Outcomes: a captured `send` overrides the fallback
+        // tag below, so `skipped` surfaces when the engagement rules declined
+        // (`not_engaged`) or no handler takes the shape (`not_dispatchable`);
+        // a throwing handler rejects `waitUntil` (propagateHandlerErrors) and
+        // hosted admission answers a retryable 503, like the PR adapters.
+        // The channel-level event_id dedupe is deliberately bypassed with a
+        // fresh instance per delivery: the control plane's app-scoped ingress
+        // claim already dedupes Slack retries, and on a warm pod the local set
+        // would otherwise swallow the control plane's own retry of a delivery
+        // that failed after the id was marked handled.
+        dispatch: (_a) => __awaiter(this, [_a], void 0, function* ({ payload, args }) {
+            const dispatched = dispatchInboundFromEventBody(payload, inboundDeps({
+                send: args.send,
+                waitUntil: args.waitUntil,
+                host: args.host,
+                artifacts: args.artifacts,
+                eventIds: createEventIdDedupe(),
+                propagateHandlerErrors: true,
+            }));
+            return skipped(dispatched ? "not_engaged" : "not_dispatchable");
+        }),
+    });
     return definition;
 }

package/dist/channels.d.ts

@@ -131,4 +131,49 @@ export declare function allowAll(): AuthPolicy;
 export declare function publicEndpoint(): AuthPolicy;
 /** True when a policy was created by {@link publicEndpoint}. */
 export declare function isPublicEndpointPolicy(policy: AuthPolicy): boolean;
+/**
+ * What `deploy` extracts from a {@link sharedSecretAuth} /
+ * {@link hmacSignatureAuth} policy into the manifest: the control plane runs
+ * the same check with the deployment secret of the same name before any
+ * compute starts. `secret` is a name, never a value.
+ */
+export type CatchAuthDeclaration = {
+    kind: "header";
+    header: string;
+    secret: string;
+} | {
+    kind: "hmac-sha256";
+    header: string;
+    secret: string;
+    prefix?: string;
+}
+/** `publicEndpoint()`: the handler verifies; the control plane only rate limits. */
+ | {
+    kind: "public";
+};
+/** The catch declaration a policy carries, if it is a catch-capable policy. */
+export declare function catchAuthDeclaration(policy: AuthPolicy): CatchAuthDeclaration | undefined;
+/**
+ * Admit requests whose `header` equals the secret named `secret` (an
+ * `Authorization: Bearer <secret>` header also matches). Locally the value
+ * is `process.env[secret]`; hosted, the deployment secret of that name. On
+ * Cursor hosting this ALSO declares the channel's routes reachable through
+ * the control-plane catch API, which runs the same comparison before any
+ * compute exists. An unset secret admits nothing.
+ */
+export declare function sharedSecretAuth(options: {
+    header: string;
+    secret: string;
+}): AuthPolicy;
+/**
+ * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
+ * under the secret named `secret` (optionally behind a literal `prefix`
+ * such as `sha256=`). Same local / hosted / catch semantics as
+ * {@link sharedSecretAuth}.
+ */
+export declare function hmacSignatureAuth(options: {
+    header: string;
+    secret: string;
+    prefix?: string;
+}): AuthPolicy;
 //# sourceMappingURL=channels.d.ts.map

package/dist/channels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../src/channels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,WAAW,EACX,aAAa,GACd,MAAM,sBAAsB,CAAC;AAS9B,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EAEZ,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,EAEV,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAC1B,kCAAkC,EAClC,2BAA2B,EAC3B,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,+BAA+B;AAC/B,wBAAgB,aAAa,CAAC,MAAM,GAAG,SAAS,EAC9C,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAC5B,iBAAiB,CAAC,MAAM,CAAC,CAW3B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,GAAE,iBAAsB,GAC7B,qBAAqB,CAUvB;AAoCD,4EAA4E;AAC5E,wBAAgB,GAAG,CAAC,MAAM,SAAS,kBAAkB,EACnD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAChC,YAAY,CAMd;AAED,2CAA2C;AAC3C,wBAAgB,IAAI,CAClB,KAAK,SAAS,kBAAkB,EAChC,MAAM,SAAS,kBAAkB,GAAG,SAAS,GAAG,SAAS,EACzD,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,YAAY,CAOvE;AAED,0CAA0C;AAC1C,wBAAgB,GAAG,CACjB,KAAK,SAAS,kBAAkB,EAChC,MAAM,SAAS,kBAAkB,GAAG,SAAS,GAAG,SAAS,EACzD,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,YAAY,CAOvE;AAED,4CAA4C;AAC5C,wBAAgB,KAAK,CACnB,KAAK,SAAS,kBAAkB,EAChC,MAAM,SAAS,kBAAkB,GAAG,SAAS,GAAG,SAAS,EACzD,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,YAAY,CAOvE;AAED,qCAAqC;AACrC,wBAAgB,MAAM,CACpB,KAAK,SAAS,kBAAkB,GAAG,SAAS,GAAG,SAAS,EACxD,MAAM,SAAS,kBAAkB,GAAG,SAAS,GAAG,SAAS,EACzD,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,YAAY,CAOzE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,IAAI,UAAU,CAcrC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAoB3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAWzC;AAOD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAiB9C;AAWD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,aAAa,EACT,MAAM,GACN,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,GACxE,UAAU,CAmBZ;AAWD;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,UAAU,CAMrC;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAa3C;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAMlE;AAID;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;AAC1E,oFAAoF;GAClF;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AASvB,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,GACjB,oBAAoB,GAAG,SAAS,CAOlC;AAYD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,CAwBb;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,UAAU,CAoCb"}

package/dist/channels.js

@@ -57,23 +57,32 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 export { openCiCheck, resumeCiCheck, } from "./channels/checks.js";
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";
 import { normalizeIdentity } from "./internal/continuation-identity.js";
+import { attachCatchAdmission } from "./internal/hosted-catch.js";
+import { attachHttpControlPlaneAdmission } from "./internal/http-control-plane-session.js";
 import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
 /** Define a custom channel. */
 export function defineChannel(config) {
-    return brandDefinition("channel", config);
+    const definition = brandDefinition("channel", config);
+    if (config.routes !== undefined && config.routes.length > 0) {
+        // Hosted: the control plane catches declared routes and replays them
+        // here. Provider packs attach their own admission afterwards.
+        attachCatchAdmission(definition, config.routes);
+    }
+    return definition;
 }
 /**
  * Configure the built-in HTTP session channel. Only meaningful as the
  * default export of `agent/channels/http.ts`.
  */
 export function httpChannel(config = {}) {
-    if (config.continuation !== undefined) {
-        return brandDefinition("http-channel", Object.assign(Object.assign({}, config), { continuation: normalizeIdentity(config.continuation, "http") }));
-    }
-    return brandDefinition("http-channel", config);
+    const definition = config.continuation !== undefined
+        ? brandDefinition("http-channel", Object.assign(Object.assign({}, config), { continuation: normalizeIdentity(config.continuation, "http") }))
+        : brandDefinition("http-channel", config);
+    attachHttpControlPlaneAdmission(definition);
+    return definition;
 }
 // ============================================================================
 // Route verbs
@@ -322,9 +331,99 @@ export function publicEndpoint() {
         principalId: "anonymous",
         principalType: "user",
     });
-    return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true });
+    // On the v2 control plane this also makes the channel's routes catchable
+    // with handler-side verification (the v1 alias posture): the CP admits
+    // every request on a declared route and the handler rejects bad ones.
+    return markCatchAuth(Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true }), { kind: "public" });
 }
 /** True when a policy was created by {@link publicEndpoint}. */
 export function isPublicEndpointPolicy(policy) {
     return (policy[PUBLIC_ENDPOINT_MARKER] === true);
 }
+const CATCH_AUTH_MARKER = Symbol.for("agent-serve.catch-auth");
+function markCatchAuth(policy, declaration) {
+    return Object.assign(policy, { [CATCH_AUTH_MARKER]: declaration });
+}
+/** The catch declaration a policy carries, if it is a catch-capable policy. */
+export function catchAuthDeclaration(policy) {
+    const declaration = policy[CATCH_AUTH_MARKER];
+    return typeof declaration === "object" && declaration !== null
+        ? declaration
+        : undefined;
+}
+function presentedHeaderSecret(headerName, value) {
+    if (headerName === "authorization" &&
+        value.toLowerCase().startsWith("bearer ")) {
+        return value.slice("bearer ".length).trim();
+    }
+    return value.trim();
+}
+/**
+ * Admit requests whose `header` equals the secret named `secret` (an
+ * `Authorization: Bearer <secret>` header also matches). Locally the value
+ * is `process.env[secret]`; hosted, the deployment secret of that name. On
+ * Cursor hosting this ALSO declares the channel's routes reachable through
+ * the control-plane catch API, which runs the same comparison before any
+ * compute exists. An unset secret admits nothing.
+ */
+export function sharedSecretAuth(options) {
+    const header = options.header.toLowerCase();
+    const policy = (request) => {
+        const expected = process.env[options.secret];
+        const presented = request.headers.get(header);
+        if (expected === undefined ||
+            expected.length === 0 ||
+            presented === null ||
+            !constantTimeEquals(presentedHeaderSecret(header, presented), expected)) {
+            return null;
+        }
+        return {
+            authenticator: "shared-secret",
+            principalId: "webhook",
+            principalType: "service",
+        };
+    };
+    return markCatchAuth(policy, {
+        kind: "header",
+        header,
+        secret: options.secret,
+    });
+}
+/**
+ * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
+ * under the secret named `secret` (optionally behind a literal `prefix`
+ * such as `sha256=`). Same local / hosted / catch semantics as
+ * {@link sharedSecretAuth}.
+ */
+export function hmacSignatureAuth(options) {
+    var _a;
+    const header = options.header.toLowerCase();
+    const prefix = (_a = options.prefix) !== null && _a !== void 0 ? _a : "";
+    const policy = (request) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const secret = process.env[options.secret];
+        const presented = (_a = request.headers.get(header)) === null || _a === void 0 ? void 0 : _a.trim();
+        if (secret === undefined ||
+            secret.length === 0 ||
+            presented === undefined ||
+            !presented.startsWith(prefix)) {
+            return null;
+        }
+        const body = Buffer.from(yield request.clone().arrayBuffer());
+        const expected = createHmac("sha256", secret).update(body).digest("hex");
+        if (!constantTimeEquals(presented.slice(prefix.length).toLowerCase(), expected)) {
+            return null;
+        }
+        return {
+            authenticator: "hmac-signature",
+            principalId: "webhook",
+            principalType: "service",
+        };
+    });
+    return markCatchAuth(policy, {
+        kind: "hmac-sha256",
+        header,
+        secret: options.secret,
+        prefix: options.prefix,
+    });
+}

package/dist/connections.d.ts

@@ -65,7 +65,8 @@
  * executes **on the Cursor backend** with the account's stored OAuth
  * credentials, so the agent gets Linear / Notion / Slack / … tools with
  * zero token plumbing and no OAuth secrets on this host. Requires the host
- * to be signed in (`agent-sdk login` or `CURSOR_API_KEY`):
+ * to be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
+ * `CURSOR_SERVICE_ACCOUNT_KEY`):
  *
  * ```ts
  * // agent/mcp-connections/account.ts — every connected server (no allowlist)

package/dist/connections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8HG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEzE,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,oBAAoB,CAEtB"}
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEzE,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,oBAAoB,CAEtB"}

package/dist/connections.js

@@ -65,7 +65,8 @@
  * executes **on the Cursor backend** with the account's stored OAuth
  * credentials, so the agent gets Linear / Notion / Slack / … tools with
  * zero token plumbing and no OAuth secrets on this host. Requires the host
- * to be signed in (`agent-sdk login` or `CURSOR_API_KEY`):
+ * to be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
+ * `CURSOR_SERVICE_ACCOUNT_KEY`):
  *
  * ```ts
  * // agent/mcp-connections/account.ts — every connected server (no allowlist)

package/dist/docs/404.html

@@ -9,7 +9,7 @@
     <link rel="preload stylesheet" href="/docs/assets/style.DCD_zyg3.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.CtuckIiL.js"></script>
+    <script type="module" src="/docs/assets/app.Cr-wVbnB.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>
@@ -18,7 +18,7 @@
   </head>
   <body>
     <div id="app"></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"mlVgqvSk\",\"building-with-agents.md\":\"CUSWxlP_\",\"concepts.md\":\"DgEcZOfT\",\"deployment.md\":\"MFPKqsqI\",\"evals.md\":\"CbMoebP1\",\"guides_agent-to-agent.md\":\"BDb0t1QV\",\"guides_cloud-agents.md\":\"DS8RIjwx\",\"guides_convert-automation.md\":\"B4sjlodG\",\"guides_github.md\":\"c0gdGJ-D\",\"guides_grokbot-agents.md\":\"DVqdhBKb\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Dp6cDP7f\",\"guides_opentelemetry.md\":\"SCRMskno\",\"guides_slack.md\":\"9oHPye9o\",\"guides_webhooks.md\":\"DKdA43Qm\",\"hillclimbing.md\":\"CpTGTCle\",\"index.md\":\"BW_6tOgR\",\"quickstart.md\":\"DdQOF7Y8\",\"reference_agent-config.md\":\"CHNpiyp4\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"D-qTqwcq\",\"reference_cli.md\":\"Dm67hd2D\",\"reference_connections.md\":\"Di6jJAXF\",\"reference_extensions.md\":\"CGmMLblt\",\"reference_hooks.md\":\"Ddt5DdgJ\",\"reference_http-api.md\":\"oySXBO8o\",\"reference_instructions.md\":\"CR7XSsGk\",\"reference_playground.md\":\"4myJPxrf\",\"reference_project-layout.md\":\"DuBu9a96\",\"reference_prompt.md\":\"DnaD5dNK\",\"reference_result.md\":\"BK5SxDrf\",\"reference_schedules.md\":\"DI_JrHgq\",\"reference_sessions.md\":\"CueyOHSL\",\"reference_skills.md\":\"l2ezAcaN\",\"reference_subagents.md\":\"CfsIloPm\",\"reference_tools.md\":\"aGrn99hP\",\"scaffolding-agents.md\":\"em43xlY1\",\"skills_ab.md\":\"CsFNatVx\",\"skills_create-agent.md\":\"BVoWPcan\",\"skills_debug.md\":\"CDbPhHfg\",\"skills_evals.md\":\"723kpUmA\",\"skills_framework-map.md\":\"haibFyoB\",\"skills_github.md\":\"D0JahM8c\",\"skills_hillclimb.md\":\"B_zJerxA\",\"skills_index.md\":\"DKwIxzGg\",\"skills_mcp-auth.md\":\"DGvFP3HE\",\"skills_otel.md\":\"B5Ddv1xH\",\"skills_setup-slack.md\":\"BBgx8lUz\",\"storage.md\":\"BOHeqk2M\",\"templates_agentic-owners.md\":\"BZSH4N9z\",\"templates_agents-md.md\":\"CXSMZljE\",\"templates_code-wiki.md\":\"CDYZIBFN\",\"templates_demo.md\":\"BeQX9V3H\",\"templates_grokbot-agents.md\":\"c1s6Flp9\",\"templates_pr-autofixer.md\":\"Bds_XWcV\",\"templates_security-help.md\":\"C3Ny_Qr2\",\"templates_security-reviewer.md\":\"lshxbCLK\",\"templates_triage.md\":\"Co4UNzkZ\",\"troubleshooting.md\":\"Cus_YZga\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.107\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Templates\",\"link\":\"/templates/demo\"},{\"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\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Code wiki\",\"link\":\"/templates/code-wiki\"},{\"text\":\"Living AGENTS.md\",\"link\":\"/templates/agents-md\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Security help\",\"link\":\"/templates/security-help\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"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\":\"Coding-agent skills\",\"collapsed\":true,\"items\":[{\"text\":\"Overview\",\"link\":\"/skills/\"},{\"text\":\"ab\",\"link\":\"/skills/ab\"},{\"text\":\"create-agent\",\"link\":\"/skills/create-agent\"},{\"text\":\"debug\",\"link\":\"/skills/debug\"},{\"text\":\"evals\",\"link\":\"/skills/evals\"},{\"text\":\"framework-map\",\"link\":\"/skills/framework-map\"},{\"text\":\"github\",\"link\":\"/skills/github\"},{\"text\":\"hillclimb\",\"link\":\"/skills/hillclimb\"},{\"text\":\"mcp-auth\",\"link\":\"/skills/mcp-auth\"},{\"text\":\"otel\",\"link\":\"/skills/otel\"},{\"text\":\"setup-slack\",\"link\":\"/skills/setup-slack\"}]},{\"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\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cursor cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Cursor Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"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\":\"Extensions\",\"link\":\"/reference/extensions\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Turn result\",\"link\":\"/reference/result\"},{\"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("{\"building-with-agents.md\":\"D0KbSkJn\",\"concepts.md\":\"B4o63Gul\",\"deployment.md\":\"JenwuCCB\",\"evals.md\":\"C7JLjoEP\",\"guides_agent-to-agent.md\":\"BDb0t1QV\",\"guides_bitbucket.md\":\"DZPzmUjU\",\"guides_cloud-agents.md\":\"BsloyHdY\",\"guides_convert-automation.md\":\"B4sjlodG\",\"guides_github.md\":\"TZaTZlfz\",\"guides_gitlab.md\":\"BmqwQfdG\",\"guides_grokbot-agents.md\":\"DyV-WArv\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_improve.md\":\"BGVk32bK\",\"guides_mcp-oauth.md\":\"Dp6cDP7f\",\"guides_opentelemetry.md\":\"SCRMskno\",\"guides_slack.md\":\"D4RVMM4G\",\"guides_webhooks.md\":\"CJK484ex\",\"hillclimbing.md\":\"BOiVo1tf\",\"index.md\":\"DD9Q2XuJ\",\"quickstart.md\":\"DdQOF7Y8\",\"reference_agent-config.md\":\"CvoL6pof\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"CAo-iK4j\",\"reference_cli.md\":\"Deg7849l\",\"reference_connections.md\":\"BojkC6c5\",\"reference_extensions.md\":\"ZAVUyuEX\",\"reference_hooks.md\":\"BlM_bOg6\",\"reference_http-api.md\":\"BwaCo-VO\",\"reference_instructions.md\":\"CR7XSsGk\",\"reference_playground.md\":\"DLnoaczX\",\"reference_project-layout.md\":\"BEU8MtQV\",\"reference_prompt.md\":\"DnaD5dNK\",\"reference_result.md\":\"BK5SxDrf\",\"reference_schedules.md\":\"DI_JrHgq\",\"reference_sessions.md\":\"CyXV1MUw\",\"reference_skills.md\":\"l2ezAcaN\",\"reference_subagents.md\":\"CfsIloPm\",\"reference_tools.md\":\"aGrn99hP\",\"scaffolding-agents.md\":\"Kctn3OVb\",\"skills_create-agent.md\":\"Q3h6Je-e\",\"skills_debug.md\":\"CVjCXMFF\",\"skills_deploy.md\":\"CWqi_ZxW\",\"skills_evals.md\":\"DFxYPErF\",\"skills_framework-map.md\":\"BxLSOhSY\",\"skills_github.md\":\"hgFX_oKY\",\"skills_hillclimb.md\":\"B_zJerxA\",\"skills_index.md\":\"DL7EHaQ-\",\"skills_mcp-auth.md\":\"DGvFP3HE\",\"skills_otel.md\":\"B5Ddv1xH\",\"skills_setup-slack.md\":\"BBgx8lUz\",\"storage.md\":\"BUrhJ-Zz\",\"templates_agentic-owners.md\":\"BZSH4N9z\",\"templates_agents-md.md\":\"CXSMZljE\",\"templates_code-wiki.md\":\"CDYZIBFN\",\"templates_demo.md\":\"BeQX9V3H\",\"templates_grokbot-agents.md\":\"c1s6Flp9\",\"templates_pr-autofixer.md\":\"Bds_XWcV\",\"templates_security-help.md\":\"C3Ny_Qr2\",\"templates_security-reviewer.md\":\"lshxbCLK\",\"templates_triage.md\":\"Co4UNzkZ\",\"troubleshooting.md\":\"CYEAO9bM\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.109\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Templates\",\"link\":\"/templates/demo\"},{\"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\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Code wiki\",\"link\":\"/templates/code-wiki\"},{\"text\":\"Living AGENTS.md\",\"link\":\"/templates/agents-md\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Security help\",\"link\":\"/templates/security-help\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Coding-agent skills\",\"collapsed\":true,\"items\":[{\"text\":\"Overview\",\"link\":\"/skills/\"},{\"text\":\"create-agent\",\"link\":\"/skills/create-agent\"},{\"text\":\"debug\",\"link\":\"/skills/debug\"},{\"text\":\"deploy\",\"link\":\"/skills/deploy\"},{\"text\":\"evals\",\"link\":\"/skills/evals\"},{\"text\":\"framework-map\",\"link\":\"/skills/framework-map\"},{\"text\":\"github\",\"link\":\"/skills/github\"},{\"text\":\"hillclimb\",\"link\":\"/skills/hillclimb\"},{\"text\":\"mcp-auth\",\"link\":\"/skills/mcp-auth\"},{\"text\":\"otel\",\"link\":\"/skills/otel\"},{\"text\":\"setup-slack\",\"link\":\"/skills/setup-slack\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"},{\"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\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cursor cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Cursor Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"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\":\"Extensions\",\"link\":\"/reference/extensions\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Turn result\",\"link\":\"/reference/result\"},{\"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.CtuckIiL.js → app.Cr-wVbnB.js}

@@ -1 +1 @@
-import{R as p}from"./chunks/theme.DhpIe0Pa.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as R,v as w,s as y,ad as C,ae as P,af as b,a2 as E}from"./chunks/framework.BCISBCiQ.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}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),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{R as p}from"./chunks/theme.Dnsd3XOn.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as R,v as w,s as y,ad as C,ae as P,af as b,a2 as E}from"./chunks/framework.BCISBCiQ.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}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),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};

package/dist/docs/assets/{building-with-agents.md.CUSWxlP_.js → building-with-agents.md.D0KbSkJn.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as i,ag as s}from"./chunks/framework.BCISBCiQ.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 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.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 <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.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./skills/create-agent.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./skills/evals.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./skills/ab.html"><code>ab</code></a></td></tr><tr><td>Export OpenTelemetry traces</td><td><a href="./skills/otel.html"><code>otel</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./skills/hillclimb.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./skills/github.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./skills/setup-slack.html"><code>setup-slack</code></a></td></tr><tr><td>Authorize host MCP OAuth</td><td><a href="./skills/mcp-auth.html"><code>mcp-auth</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./skills/debug.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>
+import{_ as t,c as a,o as i,ag as s}from"./chunks/framework.BCISBCiQ.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.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 <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.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./skills/create-agent.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./skills/evals.html"><code>evals</code></a></td></tr><tr><td>Export OpenTelemetry traces</td><td><a href="./skills/otel.html"><code>otel</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./skills/hillclimb.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./skills/github.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./skills/setup-slack.html"><code>setup-slack</code></a></td></tr><tr><td>Authorize host MCP OAuth</td><td><a href="./skills/mcp-auth.html"><code>mcp-auth</code></a></td></tr><tr><td>Deploy with an attached service account</td><td><a href="./skills/deploy.html"><code>deploy</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./skills/debug.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>
@@ -10,4 +10,4 @@ import{_ as a,c as t,o as i,ag as s}from"./chunks/framework.BCISBCiQ.js";const k
 <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.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="./skills/">Coding-agent skills</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=a(n,[["render",l]]);export{k as __pageData,g as default};
+<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.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="./skills/">Coding-agent skills</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.CUSWxlP_.lean.js → building-with-agents.md.D0KbSkJn.lean.js}

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