@cursor/july 0.1.101 → 0.1.103

package/src/types.ts

@@ -15,17 +15,10 @@ 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
 // ============================================================================
@@ -52,6 +45,8 @@ export type DefinitionKind =
   | "skill"
   | "extension"
   | "disabled-tool"
+  | "disabled-connection"
+  | "disabled"
   | "connection"
   | "channel"
   | "http-channel"
@@ -62,7 +57,8 @@ export type DefinitionKind =
   | "ab"
   | "storage"
   | "artifacts"
-  | "otel";
+  | "otel"
+  | "result";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -103,6 +99,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";
 
@@ -817,7 +814,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. */
@@ -825,7 +823,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;
@@ -884,6 +882,13 @@ export interface ToolContext {
   emit?: (payload: SessionEventPayload) => void;
   /** The session's frozen `asOf`, or the wall clock. Use instead of `Date.now()`. */
   now(): Date;
+  /**
+   * The session's frozen instant (ISO-8601), when it has one. Present exactly
+   * when this is an `asOf` session. A tool that reaches other tools itself —
+   * the script sandbox — reads it to apply the same forward-time guard to the
+   * calls it makes, which do not pass back through the host's gate.
+   */
+  asOf?: string;
 }
 
 /**
@@ -1134,24 +1139,61 @@ export interface Extension<TConfig = undefined, TInput = TConfig>
   readonly config: TConfig;
 }
 
-/** The mount-independent part of an {@link Extension}. */
+/** The mount-independent part of an {@link Extension}: an agent-shaped tree. */
 export interface ExtensionDeclaration {
   readonly root: string;
   readonly description: string | undefined;
 }
 
+/** A Cursor plugin directory declared by `cursorPlugin`. */
+export interface CursorPluginDeclaration extends ExtensionDeclaration {
+  readonly layout: "cursor-plugin";
+  readonly variables: Record<string, string>;
+}
+
 /** What `agent/extensions/<ns>.ts` default-exports. */
 export interface ExtensionMount extends BrandedDefinition<"extension"> {
-  readonly extension: ExtensionDeclaration;
+  readonly extension: ExtensionDeclaration | CursorPluginDeclaration;
   readonly config: unknown;
 }
 
+/** `cursorPlugin({ ... })`: mount a Cursor plugin directory as an extension. */
+export interface CursorPluginOptions {
+  /**
+   * The plugin directory: the one holding `.cursor-plugin/plugin.json`
+   * (or `.claude-plugin/plugin.json` / `plugin.json`). A relative path
+   * resolves against the project root.
+   */
+  path: string;
+  /**
+   * Values for the `${NAME}` placeholders in the plugin's MCP config, the
+   * variables a Cursor install prompts for. Names the mount omits fall back
+   * to `process.env`; a placeholder nothing resolves fails discovery.
+   */
+  variables?: Record<string, string>;
+}
+
 /**
  * `export default disableTool()` in a directory mount's `tools/<name>.ts`
  * removes the extension's `<ns>__<name>`.
  */
 export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
 
+/**
+ * `export default disableConnection()` in a directory mount's
+ * `mcp-connections/<server>.ts` removes the extension's `<ns>__<server>`.
+ */
+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/`. */
@@ -1161,6 +1203,26 @@ export interface DiscoveredExtension {
   tools: string[];
   /** Composed skill names (`<ns>__<name>`), overrides applied. */
   skills: string[];
+  /** Composed MCP connection names (`<ns>__<server>`). */
+  connections: string[];
+  /** 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[];
 }
 
 // ============================================================================
@@ -1687,7 +1749,11 @@ export type SessionEventPayload =
     }
   | {
       type: "turn.completed";
-      data: { result?: string; usage?: TurnUsage; cost?: TurnCost };
+      data: {
+        result?: string;
+        usage?: TurnUsage;
+        cost?: TurnCost;
+      };
     }
   | {
       /**
@@ -1755,7 +1821,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";
@@ -2287,12 +2353,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;
@@ -2318,8 +2378,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<
@@ -2422,7 +2489,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 {
@@ -2438,6 +2505,16 @@ 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`.
@@ -2521,22 +2598,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).
@@ -2604,6 +2674,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";
 
@@ -2995,6 +3097,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">;
 }
@@ -3045,8 +3149,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[];
@@ -3080,6 +3184,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[];
@@ -3162,6 +3268,10 @@ 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[];
     /** Slack channels watched for posts (opt-in channel watch), when declared. */
@@ -3182,6 +3292,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[];
 }
 
@@ -3309,7 +3421,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`. */
@@ -3394,7 +3506,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";