@cursor/july 0.1.92 → 0.1.94

package/src/internal/tool-catalog.ts

@@ -0,0 +1,106 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+
+import type {
+  DiscoveredTool,
+  JsonSchemaObject,
+  ToolEffect,
+  ToolExecution,
+} from "../types.js";
+
+/**
+ * Display names for the well-known tool names that do not come from MCP
+ * (authored tools have no title field; adding one to `defineTool` for a
+ * presentation concern is not worth the authoring surface).
+ */
+const WELL_KNOWN_TOOL_TITLES: Readonly<Record<string, string>> = {
+  diff: "Show change diffs",
+  glob: "Find files by pattern",
+  grep: "Search file contents",
+  ls: "List a directory",
+  read: "Read a file",
+  search: "Search with a typed query",
+  write: "Write a file",
+};
+
+function catalogTitle(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised === true) {
+    return tool.annotations?.title;
+  }
+  return WELL_KNOWN_TOOL_TITLES[tool.name];
+}
+
+/**
+ * Sand connector identifiers scope the connector name by owner
+ * (`dashboard-team-<id>-Buildkite`, `dashboard-<Name>`, `user-<Name>`);
+ * the suffix is the human-meaningful name.
+ */
+const CONNECTOR_SCOPE_PREFIX = /^(?:dashboard-team-\d+-|dashboard-|user-)/;
+
+/**
+ * Where a tool comes from, for humans: the upstream connector/plugin name
+ * when the tool declares one (the reserved `__conn__` selector's values
+ * name it), the connection name otherwise. One aggregating connection
+ * (e.g. a tenant `plugins` endpoint) hosts tools from several connectors,
+ * and "plugins" tells an operator nothing — "Buildkite" does.
+ */
+function catalogSource(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised !== true) {
+    return undefined;
+  }
+  const properties = tool.inputSchema.properties as
+    | Record<string, { enum?: unknown[] } | undefined>
+    | undefined;
+  const first = properties?.__conn__?.enum?.[0];
+  if (typeof first === "string" && first !== "") {
+    return first.replace(CONNECTOR_SCOPE_PREFIX, "");
+  }
+  return tool.connection;
+}
+
+/** Light listing entry: identifiers and curated display data only. */
+export interface CatalogListEntry {
+  name: string;
+  title?: string;
+  /** Connection name for advertised MCP tools; absent for authored tools. */
+  source?: string;
+}
+
+/** Full description behind `GET /v1/tools/:name`. */
+export interface CatalogDetailEntry extends CatalogListEntry {
+  description: string;
+  execution: ToolExecution;
+  needsApproval: boolean;
+  effect?: ToolEffect | "dynamic";
+  inputSchema: JsonSchemaObject;
+  outputSchema?: JsonSchemaObject;
+}
+
+export function catalogListEntry(tool: DiscoveredTool): CatalogListEntry {
+  return {
+    name: tool.name,
+    title: catalogTitle(tool),
+    source: catalogSource(tool),
+  };
+}
+
+export function catalogDetailEntry(tool: DiscoveredTool): CatalogDetailEntry {
+  return {
+    ...catalogListEntry(tool),
+    description: tool.description,
+    execution: tool.execution,
+    needsApproval: tool.needsApproval,
+    effect: tool.effect,
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+  };
+}

package/src/types.ts

@@ -263,7 +263,8 @@ export interface AgentConfig {
    * deploys onto the v2 control plane (v2 APIs and schemas). Omitted
    * channel `continuation` then inherits from declared events (`github.pr/v2`,
    * `github.issue/v2`, `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
-   * `none/v2`). An explicit per-channel selector still overrides.
+   * `deployments.deployment/v2`, `none/v2`). An explicit per-channel selector
+   * still overrides.
    *
    * ```ts
    * export default defineAgent({
@@ -552,8 +553,9 @@ export interface SlackNudgeHostApi {
  */
 export interface HostContext {
   /**
-   * Authored MCP connections (`agent/mcp-connections/*`). Call a specific MCP
-   * tool deterministically without going through the agent loop.
+   * Authored MCP connections (`agent/mcp-connections/*` and
+   * `agent/host-connections/*`). Call a specific MCP tool deterministically
+   * without going through the agent loop.
    */
   mcp: HostMcpRegistry;
   /**
@@ -920,6 +922,33 @@ export type ToolNeedsApproval<TInput> =
  */
 export type ToolEffect = "read" | "write";
 
+/** Authored `defineConnection({ effects })` — one effect or a set. */
+export type ConnectionEffects = ToolEffect | readonly ToolEffect[];
+
+const TOOL_EFFECTS: readonly ToolEffect[] = ["read", "write"];
+
+export function isToolEffect(value: unknown): value is ToolEffect {
+  return value === "read" || value === "write";
+}
+
+/**
+ * Normalize authored {@link ConnectionConfig.effects} to a unique list.
+ * Invalid values are left for discovery to reject — this only collapses
+ * `"read"` / `["read"]` / duplicates.
+ */
+export function normalizeConnectionEffects(
+  effects: ConnectionEffects
+): ToolEffect[] {
+  const list = typeof effects === "string" ? [effects] : [...effects];
+  const unique: ToolEffect[] = [];
+  for (const effect of TOOL_EFFECTS) {
+    if (list.includes(effect)) {
+      unique.push(effect);
+    }
+  }
+  return unique;
+}
+
 /**
  * A tool's declared {@link ToolEffect} — fixed, or decided per call from
  * validated input for tools that read or write depending on their arguments
@@ -1184,12 +1213,6 @@ export type ConnectionConfig = (
 ) & {
   /** Documentation only; shown in `info` output. */
   description?: string;
-  /**
-   * Omit from SDK `mcpServers` (model never sees it). Still available on
-   * `host.mcp` for server tools / channel handlers. Does not affect
-   * cloud-native account connectors provisioned by the platform.
-   */
-  hostOnly?: boolean;
   /**
    * Per-session auth: called at turn-build time with the session's
    * {@link SessionInfo}, returning headers merged over the transport's
@@ -1238,12 +1261,27 @@ export type ConnectionConfig = (
    * fails the turn — a turn never silently runs with a shrunken toolset.
    * Local runtime only, like all server tools: a `runtime: "cloud"` agent
    * fails discovery, and hybrid per-send cloud sessions refuse the turn.
-   * Not combinable with {@link hostOnly} (advertising puts the tools in
-   * the model's toolset; hostOnly means off the model — discovery rejects
-   * the pair). The listing runs once per turn; point this at endpoints
-   * that can answer `tools/list` cheaply.
+   * The listing runs once per turn; point this at endpoints that can
+   * answer `tools/list` cheaply.
    */
   advertiseTools?: boolean;
+  /**
+   * Intended effects of tools this connection serves. When set, only
+   * tools whose classified effect is in this set are advertised — a
+   * connection that wants reads never puts a write, or a tool nothing
+   * classified, in the model's toolset.
+   *
+   * Classification is the same fail-closed read of MCP annotations the
+   * dry-run gate uses (`readOnlyHint` / `destructiveHint`). A tool the
+   * server does not classify is omitted, not guessed. Servers that leave
+   * tools unannotated stay empty here until they annotate or a trusted
+   * listing injects a known-read hint.
+   *
+   * Requires {@link advertiseTools}: this filters the named passthroughs
+   * the model sees. A single value (`"read"`) and an array (`["read"]`)
+   * are the same.
+   */
+  effects?: ConnectionEffects;
 };
 
 /**
@@ -1265,15 +1303,13 @@ export function isInlineStdioConnection(
   connection: ConnectionConfig
 ): connection is InlineStdioConnectionConfig & {
   description?: string;
-  hostOnly?: boolean;
 } {
   return "tools" in connection && connection.tools !== undefined;
 }
 
 /**
  * An MCP connection is available to the agent (SDK `mcpServers`), host
- * (`ctx.host.mcp`), and channel/schedule handlers — unless `hostOnly`,
- * which keeps it off the model surface only.
+ * (`ctx.host.mcp`), and channel/schedule handlers.
  */
 export type ConnectionDefinition = ConnectionConfig &
   BrandedDefinition<"connection">;
@@ -1846,6 +1882,19 @@ export const DIRECT_TOOL_CALL_CHANNEL_ID = "direct";
 export interface CallToolOptions {
   /** Who is calling; becomes the tool context's session auth. */
   auth?: AuthContext | null;
+  /**
+   * Address the session by its wire continuation token
+   * (`<channelId>:<key>`, as `/v1/sessions` lists it). A token that maps
+   * to a live (or restorable) session behaves exactly like passing that
+   * session's {@link sessionId} — ownership check, turn serialization, and
+   * event recording included. A token with no session behind it runs the
+   * call scratch-bound with the token's channel id and continuation key as
+   * the call's session identity, so deployments whose tools resolve state
+   * from the continuation key (e.g. VFS mounts rebuilt by a binding
+   * resolver) can serve it with no live session. Mutually exclusive with
+   * {@link sessionId}.
+   */
+  continuationToken?: string;
   /**
    * Run the tool inside an existing session: the tool sees that session's
    * info and materialized workspace, and the call is recorded on the
@@ -1877,6 +1926,14 @@ export interface ToolCallOutcome {
   durationMs: number;
   /** Present when the call ran inside an existing session. */
   sessionId?: string;
+  /**
+   * Present (true) when a session-bound call could not materialize the
+   * session's harness cwd and ran in a scratch workspace instead. The
+   * session identity still applied (read-effect calls only get here), but
+   * `ctx.workspaceDir` was not the session workspace — callers rendering
+   * results as session state should surface this.
+   */
+  scratchWorkspace?: true;
 }
 
 /**
@@ -2160,18 +2217,17 @@ export interface ChannelMeta {
    * to dispatch on. Used by `--cursor-events` to subscribe `provider: "origin"`.
    */
   originWebhookEvents?: readonly string[];
+  /**
+   * For deployments packs: the factory event types this channel is wired
+   * to dispatch on. Extracted into the deploy manifest as `eventTypes`.
+   */
+  deploymentEventTypes?: readonly string[];
   /**
    * For Slack packs with the opt-in channel watch: the allowlisted channels
    * (ids or `#names`) this channel dispatches on without a mention. Surfaced
    * by `info` so watched channels are auditable.
    */
   slackChannelPosts?: readonly string[];
-  /**
-   * For Slack packs riding the signed-in Cursor account's Slack connection
-   * (`slackChannel({ cursorAccount: true })`): inbound relays from
-   * `/v0/slack-events` instead of Socket Mode.
-   */
-  slackCursorAccount?: boolean;
 }
 
 export interface ChannelConfig<TState = JsonValue> {
@@ -2642,6 +2698,8 @@ export interface DiscoveredTool {
    * refused — see `decideToolCall`.
    */
   advertised?: true;
+  /** Name of the advertising connection an advertised tool came from. */
+  connection?: string;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2666,11 +2724,15 @@ export interface DiscoveredConnection {
   name: string;
   transport: ConnectionTransport;
   description?: string;
-  hostOnly?: boolean;
   /** Per-session auth from {@link ConnectionConfig.auth} (http/sse only). */
   auth?: ConnectionAuthProvider;
   /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
   advertiseTools?: boolean;
+  /**
+   * Normalized intended effects from {@link ConnectionConfig.effects}.
+   * Absent means every listed tool is advertised.
+   */
+  effects?: readonly ToolEffect[];
 }
 
 export interface DiscoveredChannel {
@@ -2743,6 +2805,11 @@ export interface ResolvedAgent {
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
+  /**
+   * MCP connections from `agent/host-connections/`. Host tools and
+   * `mcp oauth` see them; the model does not.
+   */
+  hostConnections?: DiscoveredConnection[];
   subagents: ResolvedAgent[];
   seedFiles: SeedFile[];
 }
@@ -2810,14 +2877,20 @@ export interface AgentProjectInfo {
     description: string;
     execution: ToolExecution;
     needsApproval: boolean;
+    /**
+     * The tool's declared {@link ToolEffect} when static, `"dynamic"` when
+     * declared as a predicate. Absent when the author declared nothing —
+     * "unknown", not "mutates".
+     */
+    effect?: ToolEffect | "dynamic";
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
   connections: Array<{
     name: string;
     transport: string;
-    hostOnly?: boolean;
     advertiseTools?: boolean;
+    effects?: readonly ToolEffect[];
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the
@@ -2840,6 +2913,8 @@ export interface AgentProjectInfo {
     githubWebhookEvents?: readonly string[];
     /** Origin webhook event types the channel dispatches on, when declared. */
     originWebhookEvents?: readonly string[];
+    /** Factory deployment event types the channel dispatches on, when declared. */
+    deploymentEventTypes?: readonly string[];
     /** Slack channels watched for posts (opt-in channel watch), when declared. */
     slackChannelPosts?: readonly string[];
   }>;
@@ -2997,12 +3072,6 @@ export interface ServeOptions {
    * or `handle.dispatchReminder`.
    */
   reminders?: boolean;
-  /**
-   * Do not start the bundled control plane (schedule/reminder clocks).
-   * Cursor hosting passes this so the kit talks to the Cursor backend
-   * instead. Local `serve` should leave this unset.
-   */
-  noControlPlane?: boolean;
   /**
    * Serve the bundled web playground at `/playground` (chat, streaming,
    * tool calls, sessions, schedule dispatch). Defaults to true; the API
@@ -3047,16 +3116,6 @@ export interface ServeOptions {
    * authenticates callers (e.g. an SSO/Okta proxy in front of the host).
    */
   allowAnonymousGrokbot?: boolean;
-  /**
-   * Route `githubChannel({ cursorAccount })` API calls through the Cursor
-   * backend's GitHub forwarder (`/v0/github-proxy`) instead of minting raw
-   * installation tokens into this process. The backend logs and meters every
-   * call with per-deployment attribution. `AGENT_SERVE_GITHUB_PROXY_URL`
-   * overrides the forwarder base URL (default: the resolved Cursor API base
-   * URL + `/v0/github-proxy`). Child `gh` processes still use a minted
-   * `GH_TOKEN` lease (proxying `gh` is a follow-up).
-   */
-  cursorGithubProxy?: boolean;
   /**
    * Allow {@link allowAnonymous} together with
    * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`

package/templates/pr-autofixer/agent/channels/slack.ts

@@ -1,8 +1,14 @@
 import { slackChannel } from "@cursor/july/channels/slack";
 
+/**
+ * Slack channel (Socket Mode).
+ *
+ * Tokens: PR_AUTOFIXER_SLACK_BOT_TOKEN + PR_AUTOFIXER_SLACK_APP_TOKEN
+ *
+ * Full setup: agent-sdk slack create
+ */
 export default slackChannel({
-  cursorAccount: true,
-  agentName: "PrAutofixer",
+  envPrefix: "PR_AUTOFIXER",
   suggestedPromptsTitle: "Try asking",
   suggestedPrompts: [
     {

package/templates/triage/README.md

@@ -43,4 +43,5 @@ on both issues. `agent-sdk eval` classifies and skips tracker writes.
 - `agent/instructions.md`: procedure around the rubric
 - `evals/triage.eval.ts`: three smoke cases
 
-`agent/lib/actuate.ts` talks to the tracker. The connection is host-only.
+`agent/lib/actuate.ts` talks to the tracker. Writes go through
+`record_triage` so the host owns comments, priority, and duplicate links.

package/templates/triage/overlays/jira/agent/mcp-connections/tracker.ts

@@ -3,5 +3,4 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   cursorAccount: true,
   servers: ["Jira"],
-  hostOnly: true,
 });

package/templates/triage/overlays/linear/agent/mcp-connections/tracker.ts

@@ -3,5 +3,4 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   cursorAccount: true,
   servers: ["Linear", "Linear MCP"],
-  hostOnly: true,
 });

package/dist/channels/slack/cursor-account.d.ts

@@ -1,87 +0,0 @@
-/**
- * Cursor-account mode for the Slack channel pack: instead of a dedicated
- * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
- * signed-in Cursor account's Slack connection. Inbound events are relayed
- * by the serve host from `/v0/slack-events` (see
- * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
- * {@link SlackApiTransport} bound to the backend proxy.
- *
- * This file is the seam between the channel definition (authored at
- * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
- * a runtime ref here, and the server discovers it, binds the transport, and
- * dispatches relayed envelopes through the pack's normal inbound path.
- */
-import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
-import type { EventIdDedupe } from "./event-id-dedupe.js";
-import type { SlackLog } from "./log.js";
-import type { SlackApiTransport, SlackChannelOptions, SlackCredentials, SlackMessageFile, SlackMessageHandler } from "./types.js";
-/**
- * Transport placeholder created at `slackChannel()` definition time and
- * bound to the real backend proxy caller when the serve host starts its
- * relay. Calls before binding soft-fail Slack-style.
- */
-export interface PendingSlackApiTransport extends SlackApiTransport {
-    bind(impl: SlackApiTransport["call"]): void;
-}
-export declare function createPendingSlackApiTransport(): PendingSlackApiTransport;
-/**
- * One routed Slack event from `/v0/slack-events` (mirror of the backend's
- * SlackAgentEventEnvelope, minus server-only fields).
- */
-export interface CursorSlackEnvelope {
-    eventName: string;
-    slackTeamId: string;
-    channelId: string;
-    channelType?: string;
-    threadTs: string;
-    messageTs: string;
-    slackUserId?: string;
-    text: string;
-    agentName: string;
-    consumerId: string;
-    /**
-     * How the backend routed the event: leading agent name or owned thread.
-     */
-    matchedBy: "name" | "thread";
-    eventId?: string;
-    receivedAtMs: number;
-    /**
-     * Slack file uploads on the triggering message. When `dataBase64` is set
-     * the Cursor backend already downloaded bytes (cursorAccount has no bot
-     * token for files.slack.com).
-     */
-    files?: SlackMessageFile[];
-}
-/** Serve-time runtime handle for one cursor-account Slack channel. */
-export interface SlackCursorAccountRuntime {
-    options: SlackChannelOptions;
-    /** The channel's live credentials (botToken slot holds the transport). */
-    credentials: SlackCredentials;
-    transport: PendingSlackApiTransport;
-    eventIds: EventIdDedupe;
-    onAppMention: SlackMessageHandler;
-    onDirectMessage: SlackMessageHandler;
-    getLog: () => SlackLog;
-}
-export declare function registerSlackCursorAccountRuntime(definition: object, runtime: SlackCursorAccountRuntime): void;
-/**
- * Recover the cursor-account runtime for a channel definition, if it was
- * created via `slackChannel({ cursorAccount: true })`.
- */
-export declare function getSlackCursorAccountRuntime(definition: object): SlackCursorAccountRuntime | undefined;
-/**
- * Dispatch one relayed envelope through the pack's normal inbound path
- * (same handlers, session continuation, and reply delivery as Socket Mode).
- */
-export declare function dispatchCursorSlackEnvelope(args: {
-    runtime: SlackCursorAccountRuntime;
-    envelope: CursorSlackEnvelope;
-    send: SendMessageFn;
-    host: HostContext;
-    artifacts: ArtifactsApi;
-    hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
-    isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
-    getContinuationLastBotMessageTs?: (continuationToken: string) => Promise<string | undefined>;
-    interruptContinuation?: (continuationToken: string) => Promise<boolean>;
-}): Promise<void>;
-//# sourceMappingURL=cursor-account.d.ts.map

package/dist/channels/slack/cursor-account.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cursor-account.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/cursor-account.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAEhB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,8BAA8B,IAAI,wBAAwB,CAezE;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,0EAA0E;IAC1E,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,wBAAwB,CAAC;IACpC,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,EAAE,mBAAmB,CAAC;IACrC,MAAM,EAAE,MAAM,QAAQ,CAAC;CACxB;AAID,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,yBAAyB,GACjC,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,GACjB,yBAAyB,GAAG,SAAS,CAEvC;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,OAAO,EAAE,yBAAyB,CAAC;IACnC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,YAAY,CAAC;IACxB,sBAAsB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,kBAAkB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,+BAA+B,CAAC,EAAE,CAChC,iBAAiB,EAAE,MAAM,KACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuEhB"}

package/dist/channels/slack/cursor-account.js

@@ -1,100 +0,0 @@
-/**
- * Cursor-account mode for the Slack channel pack: instead of a dedicated
- * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
- * signed-in Cursor account's Slack connection. Inbound events are relayed
- * by the serve host from `/v0/slack-events` (see
- * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
- * {@link SlackApiTransport} bound to the backend proxy.
- *
- * This file is the seam between the channel definition (authored at
- * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
- * a runtime ref here, and the server discovers it, binds the transport, and
- * dispatches relayed envelopes through the pack's normal inbound path.
- */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { dispatchInboundMessage } from "./dispatch.js";
-import { slackTextToMarkdown } from "./inbound.js";
-export function createPendingSlackApiTransport() {
-    let bound;
-    return {
-        kind: "api-transport",
-        label: "cursor-account",
-        bind(impl) {
-            bound = impl;
-        },
-        call(method, args) {
-            return __awaiter(this, void 0, void 0, function* () {
-                if (bound === undefined) {
-                    return { ok: false, error: "cursor_slack_relay_not_started" };
-                }
-                return bound(method, args);
-            });
-        },
-    };
-}
-const runtimeByDefinition = new WeakMap();
-export function registerSlackCursorAccountRuntime(definition, runtime) {
-    runtimeByDefinition.set(definition, runtime);
-}
-/**
- * Recover the cursor-account runtime for a channel definition, if it was
- * created via `slackChannel({ cursorAccount: true })`.
- */
-export function getSlackCursorAccountRuntime(definition) {
-    return runtimeByDefinition.get(definition);
-}
-/**
- * Dispatch one relayed envelope through the pack's normal inbound path
- * (same handlers, session continuation, and reply delivery as Socket Mode).
- */
-export function dispatchCursorSlackEnvelope(args) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const { runtime, envelope } = args;
-        const log = runtime.getLog();
-        if (envelope.eventId !== undefined &&
-            envelope.eventId.length > 0 &&
-            !runtime.eventIds.tryHandle(envelope.eventId)) {
-            log.debug("cursor-account inbound dedupe drop", {
-                event_id: envelope.eventId,
-            });
-            return;
-        }
-        const message = Object.assign(Object.assign({ text: envelope.text, body: envelope.text, markdown: slackTextToMarkdown(envelope.text), ts: envelope.messageTs, threadTs: envelope.threadTs, channelId: envelope.channelId, teamId: envelope.slackTeamId }, (envelope.slackUserId === undefined
-            ? {}
-            : {
-                author: { userId: envelope.slackUserId, isBot: false },
-            })), { files: envelope.files });
-        // DMs to @Cursor route as direct messages; everything else (explicit
-        // `@Cursor <agent> …` mentions and claimed-thread replies) dispatches on
-        // the mention handler — a claimed-thread reply is addressed to the agent
-        // by construction. Mentions/DM disable toggles are rejected at
-        // `slackChannel({ cursorAccount: true })` construction so the backend
-        // never consumes events the host would drop.
-        const isDm = envelope.channelType === "im" || envelope.channelId.startsWith("D");
-        const kind = isDm ? "direct_message" : "app_mention";
-        const handler = isDm ? runtime.onDirectMessage : runtime.onAppMention;
-        yield dispatchInboundMessage(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ kind,
-            message,
-            handler, send: args.send, credentials: runtime.credentials, host: args.host, artifacts: args.artifacts, log, evalCommandsEnabled: runtime.options.evalCommands !== false, cursorAgentName: envelope.agentName, 
-            // Backend router already refused externals for this envelope.
-            blockExternals: false }, (args.hasContinuationSession === undefined
-            ? {}
-            : { hasContinuationSession: args.hasContinuationSession })), (args.isContinuationBusy === undefined
-            ? {}
-            : { isContinuationBusy: args.isContinuationBusy })), (args.getContinuationLastBotMessageTs === undefined
-            ? {}
-            : {
-                getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
-            })), (args.interruptContinuation === undefined
-            ? {}
-            : { interruptContinuation: args.interruptContinuation })), { continuation: runtime.options.continuation }), (envelope.eventId === undefined ? {} : { eventId: envelope.eventId })));
-    });
-}

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

@@ -1,13 +0,0 @@
-import{_ as a,c as t,o as s,ag as i}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 s(),t("div",null,[...e[0]||(e[0]=[i(`<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/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> (in the monorepo: <code>packages/agent-serve/skills/create-agent/SKILL.md</code>) and follow it.</p><p>The skill asks about your agent&#39;s purpose, runtime, model, channels, MCP connections, and capabilities. It then shows you a plan, writes the project, and verifies the result.</p><p>For example:</p><blockquote><p>Use the Agent 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/SKILL.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./../skills/create-agent/SKILL.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./../skills/evals/SKILL.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./../skills/ab/SKILL.html"><code>ab</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./../skills/github/SKILL.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./../skills/setup-slack/SKILL.html"><code>setup-slack</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./../skills/debug/SKILL.html"><code>debug</code></a></td></tr></tbody></table><p>Point your coding agent at the matching <code>SKILL.md</code>. The guide contains the workflow, commands, and common mistakes for that task.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The skill bodies use the current <code>agent-serve</code> CLI names. This guide uses the upcoming <code>agent-sdk</code> names. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="how-does-a-coding-agent-verify-its-work" tabindex="-1">How does a coding agent verify its work? <a class="header-anchor" href="#how-does-a-coding-agent-verify-its-work" aria-label="Permalink to &quot;How does a coding agent verify its work?&quot;">​</a></h2><p>The coding agent should discover the project, test each server tool, run a real turn, and finish with evals:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">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:#032F62;--shiki-dark:#9ECBFF;"> .agent-serve/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> don&#39;t type-check the project because tsx strips types. Run the project&#39;s TypeScript check before shipping. Tool results must also be JSON-shaped. Use object literals or <code>type</code> aliases for <code>execute</code> return types instead of <code>interface</code> types.</p><h2 id="how-do-i-improve-the-agent-after-its-first-run" tabindex="-1">How do I improve the agent after its first run? <a class="header-anchor" href="#how-do-i-improve-the-agent-after-its-first-run" aria-label="Permalink to &quot;How do I improve the agent after its first run?&quot;">​</a></h2><p>Scaffolding proves the agent runs. It says nothing about quality. Once a smoke turn passes, give the hillclimb skill:</p><ol><li><strong>Fixtures</strong>: one to three fixed inputs, such as a PR URL, a canonical question, or a saved webhook payload</li><li><strong>Success criteria</strong>: correct tool choice, fewer tool calls, lower wall time, or better output</li><li><strong>The freeze line</strong>: the API contract, output shape, and existing evals that must stay unchanged</li></ol><p>Have the coding agent read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. It measures the current run, proposes one change, remeasures the same fixtures, and adds an eval for each kept improvement.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Create your first agent</a></li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/cli.html">CLI reference</a></li></ul>`,29)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};