@cursor/july 0.1.102 → 0.1.104

package/src/types.ts

@@ -11,21 +11,15 @@
 import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type { FileSystem } from "./filesystem.js";
 import type {
   ContinuationClaim,
   ContinuationIdentity,
   MailboxContinuation,
-} from "./continuation.js";
+} from "./internal/continuation-identity.js";
 import type { OtelConfig, OtelDefinition } from "./otel.js";
 import type { StorageDefinition } from "./storage.js";
 
-export type {
-  ContinuationClaim,
-  ContinuationIdentity,
-  ConversationType,
-  MailboxContinuation,
-} from "./continuation.js";
-
 // ============================================================================
 // JSON
 // ============================================================================
@@ -53,6 +47,7 @@ export type DefinitionKind =
   | "extension"
   | "disabled-tool"
   | "disabled-connection"
+  | "disabled"
   | "connection"
   | "channel"
   | "http-channel"
@@ -63,7 +58,8 @@ export type DefinitionKind =
   | "ab"
   | "storage"
   | "artifacts"
-  | "otel";
+  | "otel"
+  | "result";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -104,6 +100,7 @@ export const DEFAULT_MODEL: ModelSetting = {
  * `/v0/grokbot` session API, and the user-visible reply is whatever the
  * agent delivers through its SendToUser tool. The hosted harness picks
  * the model; {@link AgentConfig.model} does not apply to grokbot turns.
+ * The grokbot client is Cursor-internal and not in the published package.
  */
 export type AgentRuntime = "local" | "cloud" | "grokbot";
 
@@ -173,6 +170,18 @@ export function toPublicCloudInfo(
   };
 }
 
+/**
+ * Session-scoped facts a `root` factory needs and does not otherwise
+ * have at `defineAgent` time. The factory returns a handle: each
+ * method must observe the current binding. Do not snapshot the tree.
+ */
+export interface RootContext {
+  sessionId: string;
+  agentName?: string;
+  continuationKey?: string;
+  host?: { files: HostFilesApi; reminders?: ReminderHostApi };
+}
+
 /** Input to `defineAgent` (authored at `agent/agent.ts`). */
 export interface AgentConfig {
   /**
@@ -194,10 +203,21 @@ export interface AgentConfig {
    */
   instructions?: string;
   /**
-   * Execution runtime. Defaults to `"local"`. Use `"cloud"` to run turns
-   * on Cursor cloud agents (see {@link cloud}).
+   * Execution runtime. Defaults to `"local"`. Compatibility strings
+   * `"cloud"` and `"grokbot"` remain for agents that already ship; they
+   * are not a product surface. New agents omit this field.
    */
   runtime?: AgentRuntime;
+  /**
+   * The FileSystem the model can see. Omit it and the root is the host
+   * disk. A static handle (`tempFs`, `unionFs`, ...) is that object on
+   * every session — writes are shared. Pass `(ctx) => …` and return a
+   * new handle per session when you want isolation. A factory that
+   * returns the same object still shares. Incompatible with
+   * {@link local} `cwd` / `workspaceDir` / `sandbox` and with
+   * {@link runtime} `"cloud"`.
+   */
+  root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
   /**
    * Cloud agent defaults. Used when {@link runtime} is `"cloud"`, and as
    * the base merged under per-session {@link SendMessageOptions.cloud}
@@ -266,7 +286,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`,
-   * `deployments.deployment/v2`, `none/v2`). An explicit per-channel selector
+   * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
+   * `issues.issue/v2`, `none/v2`). An explicit per-channel selector
    * still overrides.
    *
    * ```ts
@@ -818,7 +839,8 @@ export type HostOtelAttributes = Record<
  *
  * Metrics and tags only — no custom spans, and no raw OTel `Meter` /
  * `Tracer`. First-party names (`cursor.token.usage`, …) and join keys
- * (`cursor.conversation.id`, `agent_sdk.agent`, …) are reserved.
+ * (`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
+ * …) are reserved.
  */
 export interface HostOtelApi {
   /** True when a meter is running and `increment` / `record` export. */
@@ -826,7 +848,7 @@ export interface HostOtelApi {
 
   /**
    * Merge tags onto this host binding. On a session-bound host they join
-   * the open session span and later first-party metrics. Unbound tags
+   * open turn/tool spans and later first-party metrics. Unbound tags
    * stay on this host instance only.
    */
   setAttributes(attributes: HostOtelAttributes): void;
@@ -1189,6 +1211,14 @@ export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
 export type DisabledConnectionDefinition =
   BrandedDefinition<"disabled-connection">;
 
+/**
+ * `export default disable()` / `disableSkill()` / `disableHook()` /
+ * `disableChannel()` / `disableSchedule()` / `disableSubagent()` /
+ * `disableInstructions()` / `disableAB()` / `disableArtifacts()` in a
+ * directory mount removes that contribution from the matching overlay slot.
+ */
+export type DisabledDefinition = BrandedDefinition<"disabled">;
+
 /** One mounted extension and the names it contributed. */
 export interface DiscoveredExtension {
   /** Mount namespace: the filename stem or directory name under `agent/extensions/`. */
@@ -1198,10 +1228,26 @@ export interface DiscoveredExtension {
   tools: string[];
   /** Composed skill names (`<ns>__<name>`), overrides applied. */
   skills: string[];
-  /** Composed MCP connection names (`<ns>__<server>`); Cursor plugin mounts. */
+  /** Composed MCP connection names (`<ns>__<server>`). */
   connections: string[];
-  /** Composed subagent names (`<ns>__<agent>`); Cursor plugin mounts. */
+  /** Composed host MCP connection names (`<ns>__<server>`). */
+  hostConnections: string[];
+  /** Composed subagent names (`<ns>__<id>`). */
   subagents: string[];
+  /** Composed hook names (`<ns>__<name>`). */
+  hooks: string[];
+  /** Composed channel ids (`<ns>__<id>`). */
+  channels: string[];
+  /** Composed schedule names (`<ns>__<name>`). */
+  schedules: string[];
+  /** Whether the mount contributed an instructions fragment. */
+  instructions: boolean;
+  /** Workspace seed paths the mount contributed. */
+  seedFiles: string[];
+  /** Composed A/B experiment names (`<ns>__<name>`). */
+  abs: string[];
+  /** Composed artifact kind names (`<ns>__<kind>`). */
+  artifactKinds: string[];
 }
 
 // ============================================================================
@@ -1728,7 +1774,11 @@ export type SessionEventPayload =
     }
   | {
       type: "turn.completed";
-      data: { result?: string; usage?: TurnUsage; cost?: TurnCost };
+      data: {
+        result?: string;
+        usage?: TurnUsage;
+        cost?: TurnCost;
+      };
     }
   | {
       /**
@@ -1796,7 +1846,7 @@ export type SessionMode = "chat" | "task";
 
 /**
  * Why the session exists. `"eval"` is regression traffic (`defineEval` /
- * `agent-serve eval` / playground Evals) and is excluded from live A/B
+ * `agent-sdk eval` / playground Evals) and is excluded from live A/B
  * enrollment. Default `"live"`.
  */
 export type SessionPurpose = "live" | "eval";
@@ -2328,12 +2378,6 @@ export interface ChannelDeleteRouteSpec<
   handler: ChannelRouteHandler;
 }
 
-/** @deprecated Prefer {@link ChannelGetRouteSpec} / {@link ChannelBodyRouteSpec}. */
-export type ChannelRouteSpec =
-  | ChannelGetRouteSpec
-  | ChannelBodyRouteSpec
-  | ChannelDeleteRouteSpec;
-
 export interface ChannelRoute {
   method: RouteMethod;
   path: string;
@@ -2359,8 +2403,15 @@ export interface ChannelEventContext<TState = JsonValue> {
   setContinuationToken(token: string | null): Promise<void>;
 }
 
+/** Per-event session context shared by channel `events` handlers and hooks. */
 export interface SessionContext {
   session: SessionInfo;
+  /**
+   * Shared host services (MCP / GitHub / Slack / kv / files). Same as
+   * tool `ctx.host`. `files` and `otel` are bound to this session, so a
+   * relative path cannot read another session's files.
+   */
+  host: HostContext;
 }
 
 export type ChannelEventHandler<
@@ -2463,7 +2514,7 @@ export interface ChannelStartArgs {
 
 /**
  * Descriptive metadata a channel pack attaches for tooling. Read by
- * discovery / `projectInfo` and CLI helpers (e.g. `agent-serve github
+ * discovery / `projectInfo` and CLI helpers (e.g. `agent-sdk github
  * forward`) — it never affects routing or dispatch.
  */
 export interface ChannelMeta {
@@ -2479,11 +2530,28 @@ export interface ChannelMeta {
    * to dispatch on. Used by `--cursor-events` to subscribe `provider: "origin"`.
    */
   originWebhookEvents?: readonly string[];
+  /**
+   * For GitLab webhook packs: the `object_kind`s this channel is wired to
+   * dispatch on (`merge_request`, `note`, `push`, `pipeline`, `tag_push`).
+   */
+  gitlabWebhookEvents?: readonly string[];
+  /**
+   * For Bitbucket webhook packs: the event keys this channel is wired to
+   * dispatch on, in the Cloud vocabulary (`pullrequest:created`, …).
+   */
+  bitbucketWebhookEvents?: 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 Change Monitor checkpoint and Factory issue packs: the factory
+   * event types this channel is wired to dispatch on. Extracted into the
+   * deploy manifest as `eventTypes`. Kept separate from
+   * `deploymentEventTypes`.
+   */
+  factoryEventTypes?: 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
@@ -2562,22 +2630,15 @@ export type HttpChannelDefinition = HttpChannelConfig &
 // Hooks (agent/hooks/*.ts)
 // ============================================================================
 
-export interface HookContext {
+export interface HookContext extends SessionContext {
   agent: { name: string };
   channel: { id: string; continuationToken: string | null };
-  session: SessionInfo;
   /**
    * Absolute path of the agent's durable state root (shared across every
    * session of this agent). Hooks that maintain derived state (e.g. the
    * memory journal) write here.
    */
   stateRoot: string;
-  /**
-   * Shared host services (MCP / GitHub / Slack / kv / files). Same as
-   * tool `ctx.host`. `files` is bound to this hook's session, so a
-   * relative path cannot read another session's files.
-   */
-  host: HostContext;
   /**
    * Durable artifacts, bound to this hook's session: `tag` auto-fills
    * `sessionId` (and `turnId` when known).
@@ -2645,6 +2706,38 @@ export interface ArtifactsConfig {
 export type ArtifactsDefinition = ArtifactsConfig &
   BrandedDefinition<"artifacts">;
 
+// ============================================================================
+// Result (agent/result.ts)
+// ============================================================================
+
+/**
+ * Host context passed to {@link ResultConfig.commit}. Same services as a
+ * server tool, without a tool call id.
+ */
+export interface ResultContext {
+  session: SessionInfo;
+  host: HostContext;
+  artifacts: ArtifactsApi;
+  stateRoot: string;
+  workspaceDir: string;
+  /** Full assistant text for the turn. */
+  text: string;
+}
+
+/**
+ * Input to `defineResult` (authored at `agent/result.ts`).
+ * Parse `ctx.text` in `commit`. Throw to fail the turn.
+ */
+export interface ResultConfig {
+  /**
+   * Host actuation after the model finishes, before `turn.completed`.
+   * Throw to fail the turn. A dry-run session skips this callback.
+   */
+  commit: (ctx: ResultContext) => void | Promise<void>;
+}
+
+export type ResultDefinition = ResultConfig & BrandedDefinition<"result">;
+
 /** Who tagged an artifact: host code, or the model via `tag_artifact`. */
 export type ArtifactSource = "host" | "model";
 
@@ -3036,6 +3129,8 @@ export interface DiscoveredHook {
 /** Live A/B metrics experiment (`agent/ab.ts` or `agent/ab/<name>.ts`). */
 export interface DiscoveredAB {
   name: string;
+  /** File stem the experiment was loaded from (`ab` or a path under `ab/`). */
+  source?: string;
   /** Branded `defineAB({ ... })` config (see `@cursor/july/ab`). */
   definition: BrandedDefinition<"ab">;
 }
@@ -3059,6 +3154,11 @@ export interface ResolvedAgent {
   instructions?: string;
   /** Execution runtime. Root agents default to `"local"`. */
   runtime: AgentRuntime;
+  /**
+   * Authored {@link AgentConfig.root}. The factory is persisted, not a
+   * serialized tree. A resumed session calls it again (or reuses the handle).
+   */
+  root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
   /** Cloud options when {@link runtime} is `"cloud"`. */
   cloud?: AgentCloudOptions;
   /**
@@ -3086,8 +3186,8 @@ export interface ResolvedAgent {
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   /**
-   * Mounted `agent/extensions/`. Their tools and skills are already merged
-   * into {@link tools} and {@link skills}; this records provenance.
+   * Mounted `agent/extensions/`. Their contributions are already merged
+   * into the agent and project lists; this records provenance.
    */
   extensions?: DiscoveredExtension[];
   connections: DiscoveredConnection[];
@@ -3121,6 +3221,8 @@ export interface AgentProject {
   storage?: StorageDefinition;
   /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
   artifacts?: ArtifactsDefinition;
+  /** Optional `agent/result.ts` (`defineResult`). */
+  result?: ResultDefinition;
   /** Optional `agent/otel.ts` (`defineOtel`). */
   otel?: OtelDefinition;
   diagnostics: Diagnostic[];
@@ -3203,8 +3305,14 @@ export interface AgentProjectInfo {
     githubWebhookEvents?: readonly string[];
     /** Origin webhook event types the channel dispatches on, when declared. */
     originWebhookEvents?: readonly string[];
+    /** GitLab `object_kind`s the channel dispatches on, when declared. */
+    gitlabWebhookEvents?: readonly string[];
+    /** Bitbucket event keys (Cloud vocabulary) the channel dispatches on. */
+    bitbucketWebhookEvents?: readonly string[];
     /** Factory deployment event types the channel dispatches on, when declared. */
     deploymentEventTypes?: readonly string[];
+    /** Change Monitor checkpoint or Factory issue event types the channel dispatches on, when declared. */
+    factoryEventTypes?: readonly string[];
     /** Slack channels watched for posts (opt-in channel watch), when declared. */
     slackChannelPosts?: readonly string[];
   }>;
@@ -3223,6 +3331,8 @@ export interface AgentProjectInfo {
   otel?: { serviceName?: string; enabled: true };
   /** Declared artifact kinds from `agent/artifacts.ts`, when authored. */
   artifacts?: { kinds: string[]; agentTool: boolean; max: number };
+  /** Present when `agent/result.ts` (`defineResult`) is authored. */
+  result?: true;
   diagnostics: Diagnostic[];
 }
 
@@ -3253,10 +3363,17 @@ export interface RunnerTurnRequest {
   sdkAgentId?: string;
   /** Absolute path of the session's materialized workspace. */
   workspaceDir: string;
+  /** Resolved FileSystem handle when {@link AgentConfig.root} is set. */
+  root?: FileSystem;
   /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
   sandbox?: boolean;
   /** Built-in tool allowlist ({@link AgentConfig.tools}, resolved). */
   tools?: ToolName[];
+  /**
+   * Native tools hidden on the Cursor SDK agent because synthesized
+   * FileSystem tools own those names. Host-default omitted `tools` only.
+   */
+  disallowedTools?: ToolName[];
   /** Absolute path for runner-owned durable state (conversation store). */
   runnerStateDir: string;
   prompt: string;
@@ -3350,7 +3467,7 @@ export interface ServeOptions {
   /**
    * Cursor API key for the SDK runner and Cursor account MCP connections.
    * When omitted, falls back to `CURSOR_API_KEY`, then to the credential
-   * stored by `agent-serve login`.
+   * stored by `agent-sdk login`.
    */
   apiKey?: string;
   /** Run schedules on their cron cadence. Defaults to `!dev`. */
@@ -3435,7 +3552,7 @@ export interface ServeOptions {
    * GitHub and Origin subscriptions are registered independently.
    * The stream is read as the host's Cursor user, so this requires a signed-in
    * host: `serve` throws when no key resolves from `apiKey` here,
-   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, or `agent-serve login`.
+   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, or `agent-sdk login`.
    */
   cursorEvents?: {
     repos: string[];

package/templates/triage/agent/lib/types.ts

@@ -45,8 +45,6 @@ export interface RecordTriageResult {
   tracker: TrackerResult;
 }
 
-export type TrackerKind = "none" | "linear" | "jira";
-
 export type TrackerConfig =
   | { kind: "none" }
   | { kind: "linear" | "jira"; connectionName: string };

package/dist/continuation.d.ts

@@ -1,20 +0,0 @@
-/**
- * Public continuation-identity surface for `@cursor/july`.
- *
- * Omitted `continuation` on a channel constructor stays `/v1` (engine
- * minting). Deploy onto the v2 control plane with a root architecture
- * flag; omitted channels then inherit the kind `/v2` default:
- *
- * ```ts
- * export default defineAgent({
- *   architecture: "v2",
- * });
- * ```
- *
- * Per-channel selectors still override type (`"github.issue/v2"`,
- * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
- * `"origin.pr/v2"`, `"deployments.deployment/v2"`, `"none/v2"`.
- */
-export type { ContinuationBuiltin, ContinuationClaim, ContinuationIdentity, ContinuationProtocolVersion, ContinuationSelector, ConversationType, MailboxContinuation, ParsedContinuation, } from "./internal/continuation-identity.js";
-export { BUILTINS, bindMailboxContinuationSend, builtinForType, CONTINUATION_SELECTORS, continuationSource, defaultContinuationSelector, extractContinuation, formatConversationKey, handshakeContinuation, isContinuationSelector, isV2DurableContinuationKey, mintClaim, newEvtKey, normalizeIdentity, parseContinuationSelector, resolveContinuation, resolveV2Key, stampMailboxContinuation, V2EngineError, } from "./internal/continuation-identity.js";
-//# sourceMappingURL=continuation.d.ts.map

package/dist/continuation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"continuation.d.ts","sourceRoot":"","sources":["../src/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,2BAA2B,EAC3B,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,QAAQ,EACR,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,aAAa,GACd,MAAM,qCAAqC,CAAC"}

package/dist/continuation.js

@@ -1,18 +0,0 @@
-/**
- * Public continuation-identity surface for `@cursor/july`.
- *
- * Omitted `continuation` on a channel constructor stays `/v1` (engine
- * minting). Deploy onto the v2 control plane with a root architecture
- * flag; omitted channels then inherit the kind `/v2` default:
- *
- * ```ts
- * export default defineAgent({
- *   architecture: "v2",
- * });
- * ```
- *
- * Per-channel selectors still override type (`"github.issue/v2"`,
- * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
- * `"origin.pr/v2"`, `"deployments.deployment/v2"`, `"none/v2"`.
- */
-export { BUILTINS, bindMailboxContinuationSend, builtinForType, CONTINUATION_SELECTORS, continuationSource, defaultContinuationSelector, extractContinuation, formatConversationKey, handshakeContinuation, isContinuationSelector, isV2DurableContinuationKey, mintClaim, newEvtKey, normalizeIdentity, parseContinuationSelector, resolveContinuation, resolveV2Key, stampMailboxContinuation, V2EngineError, } from "./internal/continuation-identity.js";